Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (64 loc) · 4.82 KB

AGENTS.md

File metadata and controls

82 lines (64 loc) · 4.82 KB
Raw

AGENTS.md

Project: ManagedCode.MCPGateway Owned by: ManagedCode.MCPGateway package maintainers

Parent: ../../AGENTS.md

Purpose

  • This project ships the reusable ManagedCode.MCPGateway NuGet library.
  • It owns the feature-first package slices for gateway orchestration, discovery, catalog, search, invocation, prompts, resources, and hosting integrations.

Entry Points

  • Gateway/
  • Discovery/
  • Catalog/
  • Search/
  • Invocation/
  • Prompts/
  • Resources/
  • Hosting/

Boundaries

  • In scope: public package APIs, internal runtime orchestration, catalog mutation infrastructure, transport registration, serialization, and embedding-store integration.
  • Out of scope: app-specific hosts, sample-only glue, test-only helpers, and CI workflow authoring.
  • Protected or high-risk areas: public API shape, search ranking behavior, MCP transport integration, runtime concurrency, and tool invocation contracts.

Project Commands

  • build: dotnet build src/ManagedCode.MCPGateway/ManagedCode.MCPGateway.csproj -c Release --no-restore
  • test: dotnet test --solution ManagedCode.MCPGateway.slnx -c Release --no-build
  • format: dotnet format ManagedCode.MCPGateway.slnx
  • analyze: dotnet build src/ManagedCode.MCPGateway/ManagedCode.MCPGateway.csproj -c Release --no-restore -p:RunAnalyzers=true

For this .NET project:

  • test framework: TUnit in the solution test project
  • runner model: Microsoft.Testing.Platform
  • analyzer severity lives in the repo-root .editorconfig

Applicable Skills

  • mcaf-dotnet
  • mcaf-dotnet-analyzer-config
  • mcaf-dotnet-code-analysis
  • mcaf-dotnet-codeql
  • mcaf-dotnet-coverlet
  • mcaf-dotnet-format
  • mcaf-dotnet-features
  • mcaf-dotnet-reportgenerator
  • mcaf-dotnet-roslynator
  • mcaf-testing
  • mcaf-dotnet-tunit
  • mcaf-dotnet-quality-ci
  • mcaf-dotnet-complexity
  • mcaf-solid-maintainability
  • mcaf-architecture-overview
  • mcaf-adr-writing
  • mcaf-feature-spec

Local Constraints

  • Stricter maintainability limits: none beyond root defaults unless a subfolder documents them explicitly.
  • Required local docs: keep README.md, docs/Architecture/Overview.md, and matching ADRs in sync when public behavior or architecture changes.
  • Local exception policy: document any temporary size or complexity breach in the nearest ADR, feature doc, or follow-up note before leaving the task.

Local Rules

  • Keep the project package-first and reusable; do not add app-specific hosting assumptions.
  • Keep McpGateway focused on search and invoke orchestration; registry mutation belongs in catalog and registration collaborators.
  • Keep transport-specific logic inside registration and source abstractions, not scattered through runtime code.
  • When production behavior changes here, update the integration-style tests under tests/ManagedCode.MCPGateway.Tests/ in the same task.
  • Keep package-owned production string values such as source ids, fallback names, protocol metadata keys, tool kinds, and default runtime identifiers behind named constants instead of inline literals, because gateway naming contracts must stay auditable and reusable.
  • Do not hide shared runtime services such as ILoggerFactory inside options bags for public factory APIs; when custom gateway instances need host-owned shared dependencies, expose a DI-registered factory service that resolves those dependencies from the container and accepts only gateway-specific configuration at creation time.
  • For public runtime-mutation APIs in this package, use precise lifecycle verbs such as Reconfigure or Reset; avoid ambiguous or alarming names like Replace when the operation only rebuilds in-memory registry configuration.
  • For public factory APIs in this package, prefer explicit overloads over nullable optional delegate parameters; use Create() plus Create(Action<T>) when both cases are supported.
  • Use official ModelContextProtocol SDK protocol models as the source of truth at MCP protocol boundaries; introduce gateway-owned models only for gateway-owned catalog, search, routing, or invocation concerns.
  • When a gateway-owned model carries protocol data such as tool schemas, resource metadata, prompt content, or result metadata, type those members to match the corresponding MCP SDK model members instead of inventing parallel string or loosely typed representations.
  • Preserve official MCP SDK protocol metadata and JSON schemas as typed JsonObject or JsonElement values across descriptors and proxy layers; do not downgrade them to JSON strings and parse them back when the SDK already provides structured objects.
  • Treat ManagedCode.MCPGateway as an adapter layer over the official MCP SDK: prefer carrying SDK protocol objects such as Tool, Prompt, Resource, and ResourceTemplate through internal catalog boundaries instead of recreating protocol DTOs field-by-field in gateway-owned models.