AI导哈

MCP工具搜索代理

一个轻量级的MCP工具搜索代理服务器，通过按需加载工具定义大幅减少模型上下文窗口的令牌消耗。

  • by KGT24k
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 KGT24k/mcp-tool-search

使用说明

MCP工具搜索

将MCP工具定义上下文开销减少约85-96%。

MCP工具搜索是一个代理服务器，它仅用4个轻量级工具替换模型上下文窗口中的数十个MCP工具模式。该模型不是预先加载每个工具定义，而是按需搜索工具并通过代理调用它们。

Before: 50 tool schemas loaded → ~10,000 context tokens consumed every turn
After:  4 proxy tools loaded   →    ~600 context tokens (constant)

问题

您添加的每个MCP服务器都将其完整的工具模式转储到模型的上下文窗口中。拥有5+台服务器和40+个工具 8000–20000+代币 对于模式定义，模型必须在每一个转折点上进行处理，即使它没有使用任何模式定义。

解决方案

MCP工具搜索位于MCP客户端和后端服务器之间：

  1. 目录生成器 预扫描所有MCP服务器，并将其工具定义快照到本地JSON文件中
  2. 代理服务器 仅公开4个工具——模型通过代理搜索、检查和调用工具
  3. 懒惰连接 --后端服务器在首次使用时生成，并保持活动5分钟
MCP Client ←→ MCP Tool Search Proxy ←→ Backend MCP Servers
                     ↓                    (lazily spawned)
               catalog.json             Context7, GitHub, etc.
               (pre-built snapshot)

4代理工具

工具 目的
search_tools 按关键字或功能对所有后端工具进行模糊搜索
get_tool_schema 检索特定工具的完整输入模式
call_tool 通过代理在后端服务器上执行工具
list_servers 列出所有已编目的服务器及其连接状态

快速开始

npx mcp-tool-search --help
# Or: npm install -g mcp-tool-search && mcp-build-catalog && mcp-tool-search

安装

选项A：npm（推荐）

npm install -g mcp-tool-search

选项B：来源

git clone https://github.com/KGT24k/mcp-tool-search.git
cd mcp-tool-search
npm install
npm run build

设置

1.配置后端服务器

MCP工具搜索读取MCP客户端的服务器配置以发现后端工具。它使用相同的 .mcp.json 格式为克劳德代码。

2.构建工具目录

# If installed globally:
mcp-build-catalog

# If from source:
npm run catalog

这将连接到每个配置的MCP服务器，快照其工具定义，并写入 catalog.json。代理本身会自动从目录中排除。

3.将代理添加到您的MCP客户端

请在下面选择您的客户端以进行正确的配置：

Claude Code

添加到您的 .mcp.json 在项目根目录中（或 ~/.mcp.json 全局配置）：

{
  "mcpServers": {
    "mcp-tool-search": {
      "command": "npx",
      "args": ["-y", "mcp-tool-search"]
    }
  }
}

或者，如果从源代码安装：

{
  "mcpServers": {
    "mcp-tool-search": {
      "command": "node",
      "args": ["/path/to/mcp-tool-search/dist/index.js"]
    }
  }
}
Claude Desktop

添加到您的 claude_desktop_config.json:

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-tool-search": {
      "command": "npx",
      "args": ["-y", "mcp-tool-search"]
    }
  }
}
Cursor

添加到光标MCP设置(.cursor/mcp.json 在您的项目或全局配置中）：

{
  "mcpServers": {
    "mcp-tool-search": {
      "command": "npx",
      "args": ["-y", "mcp-tool-search"]
    }
  }
}
Windsurf

添加到您的Windsurf MCP配置(~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mcp-tool-search": {
      "command": "npx",
      "args": ["-y", "mcp-tool-search"]
    }
  }
}

4.禁用直接后端服务器

在中删除或禁用其他MCP服务器条目 .mcp.json --代理现在处理对它们的所有工具调用。

环境变量

变量 默认值 用途
MCP_TOOL_SEARCH_CATALOG ./catalog.json 目录文件的路径
MCP_TOOL_SEARCH_METRICS （无） 编写JSON指标的路径（用于监控仪表板）

代币节省

代理的令牌足迹为 恒定 --4个工具，无论存在多少后端服务器。

后端工具 直接令牌 代理令牌 节省
10 ~2,000 ~600 70%
25 ~5,000 ~600 88%
50 ~10,000 ~600 94%
100 ~20,000 ~600 97%
200 ~40,000 ~600 99%

看 基准.md 详细的方法和测量。

安全

MCP工具搜索使用 基于allowlist的环境过滤器 生成后端服务器时。只有显式安全的环境变量（PATH、HOME、NODE_PATH等）才会转发给子进程。外壳环境中的API密钥、令牌和秘密 从不 除非在目录的每台服务器中明确配置，否则会泄漏到后端服务器 env 块。

附加安全措施：

  • 连接盖：最多20个并发服务器连接（达到限制时，最旧的空闲连接将被清除）
  • 连接超时：服务器启动时超时15秒
  • 闲置清理：连接在5分钟不活动后自动关闭
  • 不执行shell：服务器命令作为数组传递给 child_process.spawn()，永远不要通过shell解释
  • TypeScript 严格模式：全型安全，无 any 注入核心逻辑
  • 最小依赖性：只有2个运行时deps(@modelcontextprotocol/sdk, zod)

注： catalog.json 存储MCP配置中的每个服务器env vars（包括后端服务器运行所需的API令牌）。将此文件视为敏感文件——它被排除在git之外(.gitignore)npm发布(.npmignore + "files" 默认情况下为allowlist。不要分享或承诺。

权衡

  • 延迟：每次工具调用都需要一个搜索+模式查找步骤（首次使用工具需要额外进行约2次LLM循环）
  • 发现：模型必须搜索工具，而不是预先看到所有工具——对于小型目录来说，这是一笔很小的开销
  • 连接启动：服务器是延迟生成的，因此对新服务器的首次调用会产生连接开销

何时使用代理

  • 用它 当您拥有5台以上的MCP服务器或20多种工具时
  • 用它 当您需要跨客户端兼容性时（Cursor、Windsurf、VS Code等）
  • 用它 当您想在一个端点后聚合来自多个服务器的工具时
  • 跳过它 当你有1-2台服务器，但工具很少时

对比Anthropic的内置工具搜索

Claude Code包含一个内置 defer_loading 工具模式优化机制。以下是MCP工具搜索的不同之处：

功能 MCP工具搜索 人为延迟加载
适用于光标、风帆、VS代码 ✅ ❌ 只有克劳德
跨服务器聚合 ✅ 单端点 ❌ 每台服务器
可流式HTTP传输 ✅ 远程客户端 ❌ 仅限标准
允许拼写错误的模糊搜索 ✅ Levenstein 基本正则表达式/BM25
预构建目录（离线） ✅ ❌ 仅限运行时

如果你 仅 使用克劳德代码，Anthropic的内置解决方案可能就足够了。如果您使用多个MCP客户端或需要跨服务器工具联盟，MCP工具搜索可以填补这一空白。

兼容性

测试方法：

应适用于支持stdio传输的任何MCP客户端。

项目结构

mcp-tool-search/
├── src/
│   ├── types.ts          # Shared type definitions
│   ├── catalog.ts        # Catalog loader + fuzzy search engine
│   ├── pool.ts           # Lazy server connection pool with timeouts
│   ├── index.ts          # Main proxy MCP server
│   └── build-catalog.ts  # Catalog builder CLI
├── dist/                 # Compiled JavaScript (after build)
├── catalog.json          # Generated tool catalog (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

发展

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Watch mode
npm run dev

# Rebuild catalog
npm run catalog

贡献

欢迎投稿！以下是如何开始：

  1. 分叉 存储库并克隆你的fork
  2. 安装依赖项： npm install
  3. 构建： npm run build
  4. 运行测试： npm test （所有81项测试必须通过）
  5. 进行更改 在特征分支上
  6. 提交PR 清楚地描述了发生了什么变化以及原因

指南

  • 遵循现有的TypeScript风格（严格模式，否 any 核心逻辑）
  • 为新功能或错误修复添加测试
  • 保持最小的依赖关系——任何新的运行时依赖关系都需要强有力的理由
  • 跑 npm audit 并在提交前确保0个漏洞
  • 如果您的更改影响公共API或设置过程，请更新文档

报告问题

发现错误或有功能请求？ 打开一个问题 在GitHub上。

对于安全漏洞，请使用 GitHub安全公告 而不是公共问题。

更新日志

看 更改日志.md 查看所有版本的详细历史记录。

安全

使用许多MCP服务器？ 首先审核您的配置。

配置保护 扫描您的 .mcp.json 针对20种类型的安全漏洞——拼写错误、已知CVE、秘密泄露、地毯拉断等。零依赖，完全离线。

pip install mcp-config-guard && config-guard

MCP工具搜索保存令牌。Config Guard可保护您免受CVE的侵害。

许可证

麻省理工学院 --版权所有（c）2026 AEGIS锻造团队

相关 MCP