智能工具路由代理

smartmcp

PyPI包： smartmcp-router （CLI: smartmcp)

智能MCP工具路由，通过仅提供人工智能实际需要的工具来减少上下文膨胀。

在我自己的设置中，有8个MCP服务器和224个工具，每个AI请求都在加载 约66000个代币 在模型开始思考之前，工具模式就已经存在。有了smartmcp，这下降到 ~1600个代币A. 减少97% 在每一个请求。

令牌计数估计为每个令牌约4个字符。实际计数因模型标记器而异。

大多数MCP设置会将每个服务器上的每个工具同时暴露给AI。有了5台以上的服务器，在人工智能开始思考之前，就有50-200多种工具模式挤进了上下文窗口。smartmcp解决了这个问题。

smartmcp是一个代理MCP服务器，位于您的AI客户端和上游MCP服务器之间。它使用语义嵌入对所有可用工具进行索引，并公开一个固定的双工具界面： search_tools 发现正确的上游工具和 call_discovered_tool 调用它。工具列表在会话期间永远不会改变，因此smartmcp即使在忽略它的客户端上也能工作 notifications/tools/list_changed.

运作原理

AI Client (Claude Desktop / Cursor / your agent)
    ↕  stdio
smartmcp (proxy server)
    ↕  stdio (one connection per server)
[github] [filesystem] [google-workspace] [git] [memory] [puppeteer] ...

smartmcp使用两相流： 发现那么 呼叫.

第一阶段：发现

1. 启动时，smartmcp连接到所有配置的MCP服务器，收集每个工具模式，并构建一个 FAISS 矢量索引使用 句子转换器 嵌入。
2. AI总是看到两个工具： search_tools 和 call_discovered_tool.它叫 search_tools 例如，使用自然语言查询 search_tools({ "query": "create a GitHub issue" }).
3. smartmcp在所有索引工具中运行语义搜索，并找到前k个匹配项。
4. search_tools 返回结构化JSON。每场比赛都包括 target 标识符，上游 server 和 name，the description，相关性 score，以及整个上游 input_schema.

第二阶段：通话

5. AI读取匹配工具的 input_schema 从搜索响应和构造有效 arguments.
6. AI呼叫 call_discovered_tool({ "target": "<exact target from search>", "arguments": { ... } }).smartmcp解析目标（例如 github__create_issue)，将呼叫路由到正确的上游服务器，并返回结果。参数将原封不动地转发给上游工具。

情报在 发现 步骤。AI仍然根据返回的模式进行自己的参数构造 search_tools.smartmcp只是缩小了范围 哪个 它看到的工具，静态的双工具界面意味着即使在快照的客户端上，流也能正常工作 tools/list 一次，永不刷新。

安装

pip install smartmcp-router

需要Python 3.10+。

建议在macOS上，特别是Apple Silicon上安装： pipx 因此，SmartMCP获得了一个无法继承过时环境的隔离环境 torch 或 torchvision 从其他项目。这避免了最常见的安装问题（请参阅 故障排除).

pipx install smartmcp-router

快速启动

1.创建配置文件

创建一个 smartmcp.json 使用您的上游MCP服务器（与Claude Desktop/Cursor配置格式相同）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  },
  "top_k": 5,
  "embedding_model": "all-MiniLM-L6-v2"
}

2.将smartmcp添加到您的AI客户端

添加 smartmcp 作为您的单一MCP服务器入口。它现在管理中定义的所有上游服务器 smartmcp.json.

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "smartmcp": {
      "command": "smartmcp",
      "args": ["--config", "/path/to/smartmcp.json"]
    }
  }
}

光标

添加到您的 .cursor/mcp.json:

{
  "mcpServers": {
    "smartmcp": {
      "command": "smartmcp",
      "args": ["--config", "/path/to/smartmcp.json"]
    }
  }
}

自定义代理

将MCP客户端指向smartmcp，就像指向任何stdio MCP服务器一样：

smartmcp --config /path/to/smartmcp.json

3.使用它

你的AI现在看到了两个工具： search_tools 和 call_discovered_tool当它需要做某事时，它会搜索并调用：

AI呼叫： search_tools({ "query": "read files from disk" })

smartmcp返回： 最多有k个匹配项的JSON。每场比赛包括 target （例如 filesystem__read_file)上游工具 description，以及完整 input_schema.

AI看到： 每个匹配中的完整参数定义。它选择正确的一个，构建 arguments 对抗那场比赛 input_schema，和电话 call_discovered_tool({ "target": "filesystem__read_file", "arguments": { ... } }).

smartmcp代理 对文件系统服务器的调用保持不变，并返回结果。

配置参考

为什么选择smartmcp？

• 减少上下文浪费：人工智能在每个请求中看到的不是100个工具模式，而是一个固定的双工具表面，只检查由返回的少数模式 search_tools.
• 更好的工具选择：语义搜索即使在人工智能不知道确切名称的情况下也能找到合适的工具。
• 搜索结果中的完整架构：每场比赛由以下人员返回 search_tools 包括上游 input_schema，因此AI可以正确构造调用，而无需任何进一步操作 tools/list 刷新。
• 客户不可知：工具列表在会话期间永远不会更改，因此smartmcp适用于忽略的客户端 notifications/tools/list_changed （如Qwen Code和类似代理商）。
• 适用于任何MCP服务器：如果它通过stdio与MCP通信，smartmcp可以代理它。
• 直接替换品：用一个smartmcp条目替换MCP服务器列表。无需更改代码。
• 优雅降级：如果某些上游服务器无法连接，smartmcp将继续使用任何可用的服务器。

故障排除

torchvision::nms does not exist 或 Could not import module 'BertModel'

如果smartmcp在启动时崩溃，并出现以下错误之一：

RuntimeError: operator torchvision::nms does not exist
ModuleNotFoundError: Could not import module 'BertModel'. Are this object's requirements defined correctly?

这是一个 torch / torchvision Python环境中的ABI不匹配，而不是smartmcp错误。SmartMCP本身不依赖于 torchvision。不匹配通常出现在 pip install --upgrade 向前传递依赖关系（更新 sentence-transformers ->较新 transformers ->较新 torch)而离开一个老人 torchvision 到位。更新 transformers 在 BertModel 自动加载，因此不匹配 torchvision 扩展无法注册 nms 运营商和整个进口链断裂。Apple Silicon用户经常看到这种情况，因为混合 arm64 和 x86_64 车轮使不匹配的可能性更大。

按顺序尝试这些修复：

1. 移除 torchvision.SmartMCP不需要它：

   复制

   pip uninstall -y torchvision
   

2. 重置焊炬堆栈，使焊炬和torchvision共享一个ABI：

   复制

   pip uninstall -y torch torchvision torchaudio
   pip install --upgrade torch
   

3. 重新创建一个干净的venv（在Apple Silicon上最可靠）：

   复制

   python3 -m venv ~/.venvs/smartmcp
   source ~/.venvs/smartmcp/bin/activate
   pip install --upgrade pip
   pip install smartmcp-router
   

安装方式 pipx （参见 安装)通过为SmartMCP提供自己的隔离环境，完全避免了这类问题。

贡献

smartmcp尚处于早期阶段，正在积极改进。欢迎投稿，特别是在搜索准确性、嵌入策略和对新传输的支持方面。

如果您有想法、发现错误或想添加功能，请在 GitHub.

许可证

麻省理工学院