MCP Roundabout

MCP环形交叉口

mcp-roundabout 是一个MCP服务器，它将工具发现和工具调用路由到中定义的其他MCP服务器 mcp_servers.json.

MCP Roundabout

MCP环形交叉口的工作原理

mcp-roundabout 暴露一个MCP端点，并充当中定义的下游MCP服务器的路由器 mcp_servers.json.

在典型的请求中，客户端会发现工具(list_servers, tool_search_*, describe_tool)，执行 call_tool，并接收持久化结果的文件路径 mcp_results/ 而不是将全部有效载荷内联。

上下文和令牌影响

对于此工作流程，将完整的工具模式推迟到需要时可以将MCP相关的令牌开销减少约99%。

随着您添加更多的MCP集成（GitHub、数据库、浏览器自动化等），工具定义可能会消耗大量可用上下文。这通常意味着：

• 推理和代码生成的空间更小
• 更频繁的上下文压缩会中断迭代流
• 一次可激活的MCP服务器数量的实际限制
• 额外的输入令牌增加了API的支出

动态上下文发现

mcp-roundabout 使用动态上下文发现而不是静态预加载。代理不会预先注入每个工具定义，而是首先发现候选工具，然后仅扩展与当前任务相关的工具。

MCP Roundabout Sequence

它的作用

• 暴露一个MCP端点(streamable-http)
• 通过以下方式连接到下游MCP服务器：

- stdio (command + args) - http (url)

• 支持每服务器工具筛选：

- allowedTools - disabledTools

• 将下游工具调用结果存储到文件中 mcp_results/
• 仅返回来自的结果文件路径 call_tool

技能.md

此repo包括使用Codex/Claude的技能 mcp-roundabout。复制到 ~/.claude/skills/mcp-roundabout 或项目目录。不需要启动此仓库，您可以从README.md中找到启动它的说明。

• SKILL.md

技能目的：

• 对待 mcp-roundabout 作为下游工具发现的主要事实来源
• 使用 list_servers, list_tools, describe_tool, grep_tools，以及 call_tool 而不是假设下游工具直接可用
• 更喜欢解析 call_tool 使用shell工具输出文件(rg, grep, jq, sed, awk)避免原始有效负载使聊天上下文膨胀

需求

• Python 3.10+
• 包裹在 requirements.txt

安装：

python3 -m pip install -r requirements.txt

配置

mcp-roundabout.py 从以下位置加载配置：

1. MCP_CONFIG_PATH （如果设置）
2. ./mcp_servers.json
3. ~/.mcp_servers.json
4. ~/.config/mcp/mcp_servers.json

示例 mcp_servers.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "remote-docs": {
      "url": "https://example.com/mcp"
    }
  }
}

HTTP下游服务器示例：

{
  "mcpServers": {
    "remote-docs": {
      "url": "https://example.com/mcp"
    }
  }
}

每台服务器的可选筛选器：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "allowedTools": ["read_*", "list_*"],
      "disabledTools": ["delete_*"]
    }
  }
}

跑

python3 mcp-roundabout.py

在处理请求之前，启动并初始化所有已配置的下游服务器：

python3 mcp-roundabout.py --start-all-servers

使用特定的配置文件：

python3 mcp-roundabout.py --start-all-servers --config-path /absolute/path/to/mcp_servers.json

--start-all-servers 如果无法访问任何下游服务器，则会快速失败。

默认端点：

• http://127.0.0.1:5052/mcp

环境变量：

• MCP_META_HOST （默认值： 127.0.0.1)
• MCP_META_PORT （默认值： 5052)
• MCP_CONFIG_PATH （可选配置文件路径）

HTTP客户端示例

指向此服务器的MCP客户端配置示例：

{
  "mcpServers": {
    "mcp-roundabout": {
      "url": "http://127.0.0.1:5052/mcp"
    }
  }
}

外露工具

• list_servers(config_path?)
• list_tools(server, with_descriptions?, config_path?)
• describe_tool(server, tool, config_path?)
• grep_tools(pattern, with_descriptions?, config_path?)
• tool_search_regex(pattern, max_results?, search_descriptions?, config_path?)
• tool_search_bm25(query, max_results?, config_path?)
• call_tool(server, tool, arguments?, config_path?)

tool_search_* 工具归还 tool_reference 记录（3-5个结果），包括：

• server
• name
• description
• expand_with: { tool: "describe_tool", arguments: { server, tool } }

这使得上游LLM客户端可以推迟大多数工具定义，只扩展相关工具。

工具搜索模式

包含一个搜索工具，让您的客户从返回的工具中扩展其他工具定义 tool_reference 条目。

正则表达式变体：

{
  "name": "tool_search_regex",
  "input_schema": {
    "type": "object",
    "properties": {
      "pattern": { "type": "string" }
    },
    "required": ["pattern"]
  }
}

BM25变体：

{
  "name": "tool_search_bm25",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" }
    },
    "required": ["query"]
  }
}

工具可见性/加载行为由MCP客户端运行时/config控制，而不是由 mcp-roundabout的下游 mcp_servers.json.

结果存储

call_tool 在下面写入JSON记录 mcp_results/ 并返回：

{
  "file": "/absolute/path/to/mcp_results/___.json"
}

每个结果文件都包含元数据(timestamp, server, tool, arguments, result, config_path).