ManagedCode.MCPGateway 服务器端实现

使用说明内容（Markdown格式）

• 项目简介

  • 这是一个基于 .NET 的 MCP 服务器实现与网关库，能够把本地 AITool 实例、HTTP/stdio/MCP 服务器以及现有 MCP 客户端整合到一个统一的执行和检索表面。核心功能包括：注册和描述工具、在需要时构建和维护工具描述索引、基于嵌入向量的向量检索、以及对 LLM 客户端发起的调用进行参数映射和输出规范化。

• 主要功能点

  • MCP 服务器核心接口：提供构建索引、列出工具、执行查询和调用工具等能力，全面支持 MCP 的请求/响应流程。
  • 资源与工具注册与加载：支持本地工具、HTTP 服务器、标准输入/输出的工具、以及现成的 MCP 客户端工具的注册和加载。
  • 元工具与统一调用入口：可将网关本身暴露为搜索工具和调用工具，帮助模型先查询网关再执行具体工具。
  • 嵌入式向量检索：可与 IEmbeddingGenerator 以及自定义的嵌入存储实现集成，进行描述描述 Documents 的向量化与相似度排名。
  • 持久化与增量更新：支持通过 IMcpGatewayToolEmbeddingStore 持久化工具向量，在后续构建中仅生成缺失向量，且能感知嵌入发生变化而重新生成。
  • 多源工具与多传输：支持本地、HTTP、Stdio、以及外部 MCP 客户端等多种工具源，便于搭建混合型后端。
  • 基于 DI 的可扩展性与测试友好性：通过 AddManagedCodeMcpGateway 扩展方法注入配置，易于在应用程序中集成并单元测试。

• 安装步骤

  • 在你的 .NET 项目中添加 NuGet 包 ManagedCode.MCPGateway：
    • dotnet add package ManagedCode.MCPGateway
  • 参考快速起步示例，使用依赖注入注册网关并构建索引、执行搜索与调用。

• 服务器配置（JSON 配置示例，供 MCP 客户端在启动服务器时读取）

  • serverName: 唯一标识服务器实例的名称，例如 "ManagedCodeGatewayServer"。
  • command: 启动 MCP 服务器进程所需的启动命令，例如「dotnet」。
  • args: 启动命令的参数，指向实现 MCP 服务器的宿主可执行文件或入口，例如托管网关库的宿主应用入口。
  • 注释说明：此配置用于 MCP 客户端在启动服务器前的准备工作，确保客户端能够根据命令与参数正确启动服务器并建立连接。实际的服务器实现可能在应用内作为库使用，需要一个宿主应用来引用并配置网关（如注册工具、服务器源等）。
  • 示例字段说明（非代码形式描述）：
    • serverName: 用于标识该服务器实例的名称，便于在多服务器场景下区分。
    • command: 启动服务器的可执行程序，例如使用 dotnet 启动一个宿主程序。
    • args: 上述命令的参数，指向服务器入口点或包含必要配置的参数集合。
  • 注：具体的运行方式需要你在应用中实现一个宿主来加载 ManagedCode.MCPGateway 并通过 MCPGatewayOptions 配置工具与数据源。

• 基本使用方法

  • 在应用中注入 MCP 网关并进行索引构建：
    • 将需要的工具通过 AddTool/AddTools 注册到网关的本地源或其他来源。
    • 调用 BuildIndexAsync 构建描述符、执行向量向量化、以及将缺失向量写入存储（若配置了嵌入存储）。
  • 使用 MCP 网关进行查询与调用：
    • 调用 SearchAsync 进行工具发现和排序（支持向量检索、词汇回退和浏览模式）。
    • 调用 InvokeAsync 进行工具执行，支持通过 ToolId、ToolName 或 ToolName+SourceId 的方式定位工具，并将查询、上下文等映射为工具的输入。
  • 元工具场景：通过 CreateMetaTools 生成 gateway_tools_search 和 gateway_tool_invoke，用于在其他模型中先搜索网关工具再执行。
  • 配置嵌入存储与嵌入生成器：将 IEmbeddingGenerator<string, Embedding<float>> 注册到 DI，或提供自定义的 IMcpGatewayToolEmbeddingStore 实现，以实现描述向量的持久化与增量更新。

• 运行与入口

  • 实际部署时，需要一个宿主应用来加载 ManagedCode.MCPGateway 并按需注册工具、源和嵌入存储，以及对外暴露 MCP 服务端口或其他传输。
  • 如需测试，可参考仓库中的测试用例与 TestMcpServerHost 实现来理解服务器端与 MCP 客户端的交互方式。