Synapse MCP 服务器实现

使用说明（Markdown格式）

1. 项目简介

• 该仓库中的 MCP 模块实现了一个 MCP 服务端，用于向 MCP 客户端提供资源、工具以及工具执行能力的统一访问入口。它能够与多个下游 MCP 服务器建立连接，聚合工具清单，并对外暴露用于列出工具、调用工具以及搜索工具的接口。

2. 主要功能点

• MCP 服务器端路由与接口
  • /mcp/tools/list：列出当前连接的 MCP 服务端提供的工具信息。
  • /mcp/tools/call：向指定工具发送参数并获取执行结果。
  • /mcp/search：对聚合的工具进行全文检索。
• 下游 MCP 聚合
  • 能连接并缓存来自若干下游 MCP 服务器的工具列表，形成全局工具库。
• 访问控制与错误处理
  • 基于配置实现对工具的许可/拒绝控制，包含错误处理与清晰的错误返回。
• 动态下游连接缓存
  • 支持对动态下游连接进行缓存，减少重复建立连接的开销。
• 工具与工具输入输出描述
  • 工具信息包含服务器名、原始工具名、描述、以及输入模式（JSON Schema）等，便于客户端了解如何调用。

3. 安装与运行

• 编译构建（示例，实际按项目工作区要求操作）：
  • 使用 Rust 的 Cargo 构建你的工作区，确保已安装 Rust 与 Cargo。
  • 完整构建时，Cargo 会根据工作区中各 crate 的依赖编译 MCP 服务端及相关组件。
• 运行方式
  • 将经过编译的 MCP 服务器二进制作为独立服务启动，监听端口并暴露 MCP 接口。
  • 具体服务器的监听端口与配置参数由 MCP 的配置文件决定，通常与整个 Synapse 服务的配置保持一致。

4. 服务器配置（MCP 客户端连接 MCP 服务器所需的配置说明） 注：以下为 MCP 客户端需要的连接配置信息示例（以 JSON 格式给出，便于直接粘贴到配置文件中使用；客户端不需要包含这段示例代码，仅做参数说明）。配置示例中的 server 名称请按实际部署环境自定义。

{ "servers": { "mcp-backend-stdio": { "type": { "transport": "stdio", "stdio": { "command": "/path/to/mcp-downstream-executable", "args": ["--config", "/etc/synapse/mcp-downstream.yaml"], "env": { "MCP_LOG_LEVEL": "info" } } }, "rate_limit": null, "headers": [], "structured_content": false } }, "cache": null }

注释与要点

• server 名称（如 mcp-backend-stdio）用于标识这一路径指向的下游 MCP 服务。
• transport 标志用于指定位传输方式，当前示例为 stdio，指向一个外部可执行的下游 MCP 服务。
• stdio 字段包含：
  • command: 要执行的下游 MCP 服务程序的完整路径
  • args: 启动参数，数组形式（如传入配置文件路径等）
  • env: 启动时的环境变量字典，可选
• rate_limit、headers、structured_content 均为可选字段，按需启用。
• 如果你的环境中使用 SSE/HTTP 传输，请将 transport 设置为 sse 或 streamable_http，并提供相应的 url、认证信息等字段（具体结构与 stdio 相同的风格，详见代码中的 McpServerType 与 HttpConfig/authorization 配置定义）。
• 注意：此处给出的配置示例仅用于 MCP 客户端理解如何向 MCP 服务器注册一个下游服务的入口点。实际部署中，MCP 客户端不需要也不应该包含 MCP 服务器端的实现代码，仅需提供可执行的连接配置即可。

5. 基本使用方法

• 启动 MCP 服务器后，通过 /mcp/tools/list 可以获取当前聚合后的工具集合，包含服务器名、工具名、描述及输入模式。
• 使用 /mcp/tools/call 提供工具名称（全名 server__tool）和参数，调用所需工具并获取结果。
• 使用 /mcp/search 可以对聚合工具进行全文检索，便于跨服务器快速发现可用工具。
• 动态下游连接缓存可提升性能，若有大量下游 MCP 服务，请启用缓存并配置相应的 ttl 与容量，以避免频繁重新建立连接。
• 访问控制可通过配置对特定服务器/工具进行 deny/allow 控制，未配置的情况默认开放。

6. 关键词 工具聚合, 跨服务器调用, 工具注册, 全文检索, 远程执行

7. 分类 6