Skip to content

Overview.md

Latest commit

 

History

History
167 lines (138 loc) · 13.1 KB

Overview.md

File metadata and controls

167 lines (138 loc) · 13.1 KB

Architecture Overview

Scoping (read first)

This document is the module map for ManagedCode.MCPGateway.

In scope:

  • package boundaries
  • runtime collaboration between the public facade, registry, meta-tools, warmup hooks, and internal runtime
  • dependency direction between public APIs, internal modules, and optional AI services

Out of scope:

  • feature-level ranking metrics
  • test corpus details
  • CI or release process

Summary

ManagedCode.MCPGateway exposes three public DI surfaces:

  • IMcpGateway for list/search/invoke
  • IMcpGatewayRegistry for catalog mutation
  • McpGatewayToolSet for reusable meta-tools

McpGateway stays a thin facade over McpGatewayRuntime, which reads immutable catalog snapshots, coordinates vector or tokenizer-backed search, optionally rewrites queries through a keyed IChatClient, and invokes local or MCP tools. Optional startup warmup is available through a service-provider extension or hosted background service without changing the lazy default.

The package also keeps chat-client and agent integration generic: McpGatewayToolSet is the source of reusable AITool meta-tools and discovered proxy tools, ChatOptions.AddMcpGatewayTools(...) remains the low-level bridge, and McpGatewayAutoDiscoveryChatClient plus UseMcpGatewayAutoDiscovery(...) provide the recommended staged host wrapper that starts with two meta-tools and replaces the discovered proxy set on each new search result without introducing a hard Agent Framework dependency into the core package.

Governance Map

The solution uses root and project-local AGENTS.md files so agents can scope work without scanning the whole repository first.

flowchart LR
    Root["Root AGENTS.md"] --> Package["src/ManagedCode.MCPGateway/AGENTS.md"]
    Root --> Tests["tests/ManagedCode.MCPGateway.Tests/AGENTS.md"]
    Package --> SourceTree["Package source and runtime code"]
    Tests --> TestTree["Integration-style TUnit coverage"]
Loading

System And Module Map

flowchart LR
    Host["Host application"] --> DI["DI registration"]
    DI --> Facade["IMcpGateway / McpGateway"]
    DI --> Registry["IMcpGatewayRegistry / McpGatewayRegistry"]
    DI --> ToolSet["McpGatewayToolSet"]
    DI --> AutoDiscovery["Auto-discovery chat client bridge"]
    DI --> Warmup["Optional warmup hooks"]
    ToolSet --> Facade
    AutoDiscovery --> ToolSet
    AutoDiscovery --> HostChat["Host IChatClient / Agent host"]
    Warmup --> Facade
    Facade --> Runtime["Internal runtime orchestration"]
    Runtime --> Catalog["Internal catalog snapshots"]
    Registry --> Catalog
    Catalog --> Sources["Catalog source registrations"]
    Sources --> Local["Local AITool instances"]
    Sources --> MCP["HTTP, stdio, and provided MCP clients"]
    Runtime --> Embedder["Optional embedding generator"]
    Runtime --> Store["Optional embedding store"]
    Runtime --> Normalizer["Optional keyed search IChatClient"]
Loading

Interfaces And Contracts

flowchart LR
    IMcpGateway["IMcpGateway"] --> McpGateway["McpGateway"]
    IMcpGatewayRegistry["IMcpGatewayRegistry"] --> Registry["McpGatewayRegistry"]
    ToolSet["McpGatewayToolSet"] --> IMcpGateway
    ToolSet --> ToolList["IList<AITool> composition"]
    ToolSet --> DiscoveredTools["CreateDiscoveredTools(...)"]
    ChatOptions["ChatOptions.AddMcpGatewayTools(...)"] --> ToolSet
    AutoDiscovery["McpGatewayAutoDiscoveryChatClient / UseMcpGatewayAutoDiscovery(...)"] --> ToolSet
    AutoDiscovery --> ChatClient
    Warmup["McpGatewayServiceProviderExtensions / McpGatewayIndexWarmupService"] --> IMcpGateway
    McpGateway --> Runtime["McpGatewayRuntime"]
    Runtime --> SearchRequest["McpGatewaySearchRequest"]
    Runtime --> InvokeRequest["McpGatewayInvokeRequest"]
    Runtime --> Descriptor["McpGatewayToolDescriptor"]
    Runtime --> Options["McpGatewayOptions"]
    Runtime --> EmbeddingStore["IMcpGatewayToolEmbeddingStore"]
    Runtime --> ChatClient["IChatClient (keyed)"]
    Registry --> CatalogSource["IMcpGatewayCatalogSource"]
Loading

Key Classes And Types

flowchart LR
    McpGateway["McpGateway"] --> McpGatewayRuntime["McpGatewayRuntime"]
    AutoDiscovery["McpGatewayAutoDiscoveryChatClient"] --> ToolSet["McpGatewayToolSet"]
    AutoDiscovery --> RequestWrapper["AutoDiscoveryRequestChatClient"]
    RequestWrapper --> RuntimeTools["gateway_tools_search + discovered proxy tools"]
    McpGatewayRuntime --> RuntimeCore["Internal/Runtime/Core/*"]
    McpGatewayRuntime --> RuntimeCatalog["Internal/Runtime/Catalog/*"]
    McpGatewayRuntime --> RuntimeSearch["Internal/Runtime/Search/*"]
    McpGatewayRuntime --> RuntimeInvocation["Internal/Runtime/Invocation/*"]
    McpGatewayRuntime --> RuntimeEmbeddings["Internal/Runtime/Embeddings/*"]
    Registry["McpGatewayRegistry"] --> RegistrationCollection["McpGatewayRegistrationCollection"]
    Registry --> OperationGate["McpGatewayOperationGate"]
    RegistrationCollection --> SourceRegistrations["McpGatewayToolSourceRegistration*"]
    RuntimeSearch --> Json["McpGatewayJsonSerializer"]
    Warmup["McpGatewayIndexWarmupService"] --> McpGateway
    InMemoryStore["McpGatewayInMemoryToolEmbeddingStore"] --> MemoryCache["IMemoryCache"]
Loading

Module Index

Dependency Rules

  • Public code may depend on Models, Configuration, and Abstractions, but internal modules must not depend on tests or docs.
  • McpGateway is a thin facade only. It may delegate to McpGatewayRuntime, but it must not own registry mutation logic.
  • Internal/Catalog owns mutable source registration state. Internal/Runtime may read snapshots from it, but must not mutate registrations directly.
  • Internal/Catalog/Sources owns MCP transport-specific creation and caching. Transport setup must not leak into Internal/Runtime, Models, or Configuration.
  • Internal/Runtime may depend on Internal/Catalog, Embeddings, Models, Configuration, and Abstractions.
  • Optional AI services such as embedding generators and query-normalization chat clients must stay outside the package core and be resolved through DI service keys rather than hardwired provider code.
  • Chat-client and agent integrations must stay AITool-centric in the core package. Host-specific frameworks may consume those tools, but the base package should not take a hard dependency on a specific agent host unless that becomes an explicit product decision.
  • McpGatewayAutoDiscoveryChatClient may orchestrate tool visibility for host chat loops, but it must stay generic over IChatClient and must not take a dependency on Microsoft Agent Framework.
  • The recommended staged host flow is: advertise only the two gateway meta-tools first, then project only the latest search matches as direct proxy tools, then replace that discovered set on the next search result.
  • Models should stay contract-first. Internal transport, registry, or lifecycle helpers do not belong there.
  • Embedding support must stay optional and isolated behind IMcpGatewayToolEmbeddingStore and embedding-generator abstractions.
  • The built-in process-local embedding store may depend on IMemoryCache, but cross-instance persistence and cache replication must stay behind host-provided IMcpGatewayToolEmbeddingStore implementations.
  • Warmup remains optional. The package must work correctly with lazy indexing and must not require manual initialization for every host.

Key Decisions (ADRs)

Related Docs