MCP Tool Search 代理服务器

使用说明（Markdown格式）

• 项目简介

  • MCP Tool Search 代理服务器是一款将多个后端 MCP 服务器的工具定义通过单一入口聚合的后端服务。它通过四个代理工具实现跨服务器的工具搜索、获取工具输入模式、执行工具以及列出服务器和工具信息，显著减少模型上下文中需要处理的工具定义令牌数量，并对后端服务器进行连接池管理、超时控制和重试机制，提升稳定性与可扩展性。

• 主要功能点

  • 跨服务器工具聚合代理：将多个 MCP 服务器的工具集合在一个入口点，暴露统一的代理工具。
  • 四大代理工具：
    • search_tools：在所有后端工具中进行模糊搜索，返回匹配的工具与描述，便于先定位目标工具再执行。
    • get_tool_schema：检索某个服务器上某个工具的完整输入模式（输入 schema）。
    • call_tool：通过代理将参数传递给指定服务器上的工具进行执行，并返回结果。
    • list_servers：列出可用的 MCP 服务器及其工具数量、连接状态等元信息。
  • 会话与连接管理（连接池实现）：懒加载后台服务器、5分钟闲置自动断开、并发连接上限、超时与重试策略，提升稳定性与资源利用率。
  • 传输模式灵活：支持标准输入输出（stdio）传输，默认适用于大多数 MCP 客户端；在需要时可通过 HTTP 实现流式传输（streamable HTTP transport）。
  • 安全性与监控：对后端环境变量进行白名单过滤，避免敏感信息泄露；提供指标输出入口以便接入外部监控。

• 安装步骤

  • 克隆仓库并安装依赖
  • 构建 TypeScript 代码
  • 运行测试以验证功能
  • 构建工具目录快照（catalog）以便代理使用
  • 启动代理服务，选择 stdio 传输或 HTTP 传输

• 服务器配置（MCP 客户端使用的配置示例，不需要客户端代码）

  • MCP 客户端需要了解如何启动你要连接的 MCP 服务器（这里以代理服务器为例，下面描述的是代理的配置结构信息，帮助你理解客户端所需的连接信息）。
  • 配置结构（服务器级别的最小字段）：
    • server name：mcp-tool-search（代理服务器的唯一标识）
    • command：node
    • args：包含启动入口的参数，例如指向构建产物 dist/index.js 的路径
    • env（可选）：仅包含用户在 catalog 中显式声明需要传给后端服务器的环境变量（如 API KEY 等）。代理会对环境变量进行安全过滤，只有列入白名单的键会被传递给后端进程。
  • 注释说明
    • 该配置用于 MCP 客户端知道要如何启动并连接到代理服务器。代理服务器内部会对后端 MCP 服务器进行懒加载、连接管理与请求转发，客户端本身无需改动即可通过代理实现跨服务器工具调用。

• 基本使用方法

  • 启动代理前，请确保已构建并生成 catalog.json，用于代理在第一次请求时加载服务器与工具信息。
  • 连接方式：默认通过标准输入输出（stdio）进行 MCP 请求/响应；如果需要远程接入或流式传输，请按照文档启用流式 HTTP 传输并使用相应的端口/端点。
  • 常用操作顺序：
    • 使用 search_tools 先对多个后端工具进行搜索，快速定位需要的工具。
    • 使用 get_tool_schema 获取目标工具的输入模式，确保参数结构正确。
    • 使用 call_tool 将参数传给目标工具，获取执行结果。
    • 使用 list_servers 了解当前可用服务器及其工具数量与连接状态。
  • 维护与运维：可通过指标输出功能接入监控系统，查看活跃连接、服务器状态和工具调用情况；如需安全性加强，请确保 catalog.json 及环境变量配置符合你们的安全策略。