mcp-aggregator: Instructions file for Claude Code

MCP Aggregator — Developer Guide

Project Structure

• src/McpAggregator.Core/ — Shared library: models, services, MCP tools, storage
• src/McpAggregator.StdioServer/ — Stdio MCP host (console app)
• src/McpAggregator.HttpServer/ — HTTP/SSE MCP + REST API host (web app)
• data/ — Runtime data directory (registry.json, skills/)

Build & Run

dotnet build                                          # Build all
dotnet run --project src/McpAggregator.HttpServer      # Run HTTP server
dotnet run --project src/McpAggregator.StdioServer     # Run stdio server

Critical Rules

1. StdioServer must NEVER write to stdout/stderr — those streams are the MCP transport. All logging goes to file/OTLP sinks only.
2. MCP tools are defined in Core — both hosts discover them via WithToolsFromAssembly(typeof(ConsumerTools).Assembly).
3. Registry persistence uses atomic writes — temp file + rename to prevent corruption.
4. Connections are lazy — downstream MCP servers are connected on first use, not at registration.
5. Only WrapperToolCatalog mutates McpServerOptions.ToolCollection, PromptCollection and ResourceCollection at runtime, and it only ever adds or removes DownstreamToolWrapper / DownstreamPromptWrapper / DownstreamResourceWrapper instances. The aggregator's own attributed tools are never touched.
6. ServerInstructions is the hand-written orientation in AggregatorInstructions (ceiling 6 KB, pinned by ServerInstructionsTests); the skill document is never embedded in the handshake, it stays behind get_service_skill(serverName: "mcp-aggregator") (issue #44).

Typed wrapper tools (issue #39), proxied prompts (issue #40) and bridged resources (issue #45)

Every downstream tool is exposed as a DownstreamToolWrapper named {server}__{tool} carrying the downstream inputSchema unchanged, every downstream prompt as a DownstreamPromptWrapper (McpServerPrompt) named {server}__{prompt} carrying the downstream arguments unchanged, and every downstream resource or resource template as a DownstreamResourceWrapper (McpServerResource) at mcp-aggregator://{server}/{uri} (ResourceUriNaming: fixed scheme, server name as authority, downstream URI verbatim as path, templates keep their {…}) carrying the downstream metadata unchanged. WrapperToolCatalog (singleton, registered in AddAggregatorMcpServer) builds all three from ToolIndex (ToolDetail.Protocol / PromptDetail.Protocol / ResourceDetail.Protocol + ProtocolTemplate keep the wire objects). Everything below applies to prompts and resources as it does to tools, with PromptCollection / ResourceCollection, ToolIndex.PromptsChanged / ResourcesChanged, prompts/list_changed / resources/list_changed, a ListPromptsHandler / ListResourcesHandler + ListResourceTemplatesHandler, and a GetPromptHandler / ReadResourceHandler fallback standing in for the tool equivalents; prompts and resources have no isError result, so wrapper-side failures are McpProtocolExceptions with readable messages. Resource specifics: the SDK's McpServerResourceCollection keys plain URIs as System.Uri (fragment ignored, host case-insensitive; the catalog keeps the first of two colliding entries), resources/read tries an exact key then IsMatch on every entry then the fallback handler, the wrapper's template matcher is its own RFC 6570 approximation (the SDK's is internal), the unknown-URI error code is ResourceNotFound before protocol 2026-07-28 and InvalidParams from it on, and subscriptions are not bridged: resources.subscribe is kept unadvertised (the PostConfigure guard clears what WithSubscribeToResourcesHandler sets) and the subscribe/unsubscribe handlers reject with InvalidRequest. Design note: docs/typed-wrapper-tools.md Q12. AggregatorOptions.WrapperMode: