Skip to main content
Glama
README.md
# mcphub — 把 N 个 MCP 服务器路由成一个

[magpie](https://github.com/yetone/magpie) 的 MCP router
(`internal/gateway/hub_mcp.go` + `internal/library/mcp_hub.go`)的 Python 抽离实现。

零第三方依赖即可跑(stdio 传输)。

**为什么做这个**:magpie 用 Go 写成桌面应用,路由逻辑和 GUI、账户系统绑在一起。
把 MCP 路由单独抽出来,可以在任何地方跑、按需改造,也是一个能读的实现参考。

## 它做什么

```
agent ──> /mcp/hub/{agent} ──> MCPHub ──> github (stdio 子进程)
                                     ├──> sentry (Streamable HTTP)
                                     └──> legacy (SSE)
```

- `tools/list` 把各服务器的工具拍平成 `<server>__<tool>` 一个列表;
- `tools/call` 按名字解回 `(server, tool)` 转发;
- 每个服务器**只起一份进程**,所有 agent 共用;
- 工具多时切到按需模式,只给 `find_tools` 和 `call_tool`。

## 快速开始

```bash
# 1. 起一个空配置
echo '{"servers": []}' > config.json

# 2. 加服务器(会校验名字与字段,写错不落盘)
python -m mcphub -c config.json add stdio github -- npx -y @modelcontextprotocol/server-github

# 3. 连一次确认能用
python -m mcphub -c config.json check

# 4. 起服务
python -m mcphub -c config.json --port 8765 -v
```

在 Cursor / VS Code / Claude Desktop 里加:

```json
{
  "mcpServers": {
    "mcphub": { "type": "http", "url": "http://127.0.0.1:8765/mcp/hub/cursor" }
  }
}
```

`/mcp/hub`(不带 agent)给任何第三方 app 用,看到全部服务器;
`/mcp/hub/{agent}` 只给该 agent 的服务器集合。

## 怎么加新的 MCP 服务器

有四条路,日常用第一条。

### 1. 命令行(推荐)

```bash
# stdio:本机命令,-- 之后全部是命令与参数
python -m mcphub -c config.json add stdio github -- npx -y @modelcontextprotocol/server-github

# 带环境变量
python -m mcphub -c config.json add stdio playwright -- npx -y @playwright/mcp@latest \
  --env BROWSER=chromium

# Streamable HTTP
python -m mcphub -c config.json add http sentry \
  --url https://mcp.sentry.dev/mcp \
  --header "Authorization=Bearer YOUR_TOKEN"

# 旧版 SSE
python -m mcphub -c config.json add sse legacy --url http://127.0.0.1:9000/sse

# 其他可选项
#   --disabled-tool NAME   关掉某个工具(可重复)
#   --hidden               不参与路由,先存着
#   --direct               点名直连,不走路由
#   --cwd /path            命令的工作目录
```

`add` 会先做校验,错了直接不写:名字非法、stdio 缺 `command`、
http 缺 `url`、transport 不认识。

### 2. 直接改配置文件

格式见 `config.example.json`。关键点:`servers` 是数组,每项 `name` 唯一,
`name` 会进工具名,只能用字母数字和 `_` `-`。

### 3. 环境变量引用,别写明文密钥

`env` 与 `headers` 里的 `${VAR}` 会在启动时换成环境变量的值:

```json
{ "name": "github", "transport": "stdio", "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } }
```

没设置的变量保持原样,便于发现配错。

### 4. 加完怎么生效

不用重启服务。两条路:

- **自动**:后台每 2 秒看配置文件的 mtime 与大小,变了就重载;
- **手动**:`python -m mcphub reload` 或 `POST /admin/reload`。

重载时按启动指纹判断:

| 变化 | 行为 |
| --- | --- |
| 新增服务器 | 下次列工具时惰性启动,首次使用才起进程 |
| 删掉服务器 | 立刻结束它的后端进程 |
| 改了命令/参数/url/env | 指纹变了,旧进程被替换 |
| 只改 `disabled_tools` / `hidden` | 不重启进程,只改可见集合 |
| 配置文件写坏了 | 保留旧配置继续服务,只记日志 |

## 验证与排查

```bash
python -m mcphub -c config.json ls      # 列服务器与状态
python -m mcphub -c config.json check   # 真连一次,报每个服务器有几个工具
curl http://127.0.0.1:8765/admin/servers   # JSON 形式,含 last_error
```

`check` 会对每个服务器报 `✓ 名字: N 个工具 (...)` 或
`✗ 名字: 原因`,有失败时退出码为 1。

## 配置字段

| 字段 | 作用 | 对应 magpie |
| --- | --- | --- |
| `enabled` | 路由总开关 | `Library.MCPHub` |
| `idle_timeout` | 闲置多少秒关后端 | `hubIdle` |
| `on_demand_over` | 超过多少工具切按需 | `hubOnDemandOver` |
| `all_tools` | 强制全量工具 | `settings.RouterAllTools` |
| `api_key` | 外部调用令牌 | gateway key |
| `projects` | 项目作用域可见集合 | `projectHubs` |

服务器字段:`name` `transport` `command` `args` `env` `cwd` `url` `headers`
`hidden` `disabled_tools` `direct`。

## 与 magpie 的对应

| 本实现 | magpie |
| --- | --- |
| `hub.HubPool` | `hubPool` / `backendOf` |
| `hub.Backend` | `backend` |
| `hub.Hub.named` | `hubNamed` |
| `hub.Hub.reload` | `hubPrune` |
| `transport.StdioConn` | `streamConn` / `dialStdio` |
| `transport.HTTPConn` | `httpConn` / `dialHTTP` |
| `transport.SSEConn` | `dialSSE` |
| `server.HubService` | `hubMCPCall` |
| `ondemand.*` | `hub_ondemand.go` |
| `config.ServerConfig.startup_fingerprint` | `hubKey` |
| `cli.cmd_add` | Library 的 Add 表单 |

## 把另一个 MCP 路由接进来(bridge)

magpie 自己的 hub(`/mcp/.../hub`)本身就是一个路由。把它当普通 HTTP 服务器接进来
会得到 `magpie__notion__notion-search` 这种双前缀,所以要标 `bridge`:

```json
{"name": "magpie", "transport": "http",
 "url": "http://127.0.0.1:3425/mcp/magpie/hub", "bridge": true}
```

`url` 里含 `/hub` 时会自动识别成 bridge,不写也行。

bridge 的行为:

- 它的工具**保留原名**(`notion__notion-search`),不再拼一层前缀;
- `find_tools` 的 `server` 参数两种名字都认:`magpie`(本地服务器名)与
  `notion`(对方路由里的服务器名);
- 请求它时带 `X-Magpie-Router`,对方据此剔除自己的 bridge,两个路由互相接也不会成环;
- 反过来,我们自己收到带 `X-Magpie-Router` 的请求,也不列出自己的 bridge。

## 并发与懒加载

### 并发

| 场景 | 实测 |
| --- | --- |
| 纯路由层(ping) | 579 req/s,48 并发下 p50 40ms |
| 1 个后端,8 个并发调用(每个 1s) | 1.01s(串行需 8s,**8×** 加速) |
| 5 个后端各 1 个并发调用(每个 1s) | 1.01s(串行需 5s,**5×**) |
| 5 个后端同时冷启动 | 0.15s |
| 12 并发 `initialize` | 0.03s |

**并发度取决于后端本身。** mcphub 不限制并发,但如果后端(比如大多数 Python 写的
stdio MCP 服务器)是单线程处理请求,它的调用就会排队。实测同一个单线程后端上
4 个 0.8s 的调用要 3.2s——量的是后端,不是路由。

判断谁在排队:`parallelism = Σ单个耗时 / 总墙钟`。接近 N 说明真并行,
接近 1 说明后端在串行。

### 懒加载

| 阶段 | 行为 |
| --- | --- |
| 启动服务 | **不起任何后端进程** |
| 首次 `tools/list` 或 `tools/call` | 才启动该后端(惰性) |
| 工具列表 | 缓存到内存;命中时 0.3ms |
| 闲置 `idle_timeout`(默认 600s) | 关闭连接,**但保留工具缓存** |
| 回收后再列工具 | 走缓存,**不唤醒进程** |
| 回收后调用工具 | 自动重启,对调用方透明 |
| N 个请求同时首连 | singleflight,**只起 1 个进程** |

工具表还有一层缓存(TTL 2s)+ singleflight:`tools/call` 不需要每次都把
所有后端的工具重列一遍。这一层把单次调用从 3.6s 降到 170ms。

## 检索是向量召回吗

不是。工具召回是**词法打分**(`ondemand.score`):

- 查询词出现在 hub 名里 → 3 分;
- 出现在描述里 → 1 分;
- 整串出现在名字里 → 再加 5 分。

magpie 的 MCP 路由全程没有 embedding。它的向量检索在另一个子系统
(`internal/memembed`,记忆检索,用 sentence-transformers 的 ONNX 模型),
与工具路由无关。

## 测试

```bash
python tests/run_checks.py     # 路由算法:命名、消毒、按需判定(15 项)
python tests/e2e_stdio.py      # 真子进程:进程复用、调用、超时(7 项)
python tests/e2e_http.py       # HTTP:会话、404 重开(5 项,需 httpx2)
python tests/e2e_server.py     # 完整 MCP 会话(13 项)
python tests/e2e_reload.py     # 热加载、管理接口、坏配置容错(8 项)
```

`e2e_http.py` 与 `transport.HTTPConn` 用 `httpx2`(MCP SDK 2.x 同款)。只用
stdio 的话不需要它。

## 已知偏差

- 没有 magpie 的 `HubVisitor` 全部规则:网页伪装判定、root 转发、Magpie Browser
  的 per-key 会话都未实现。
- 没有插件服务器(本进程内调用,不走 URL)。
- 没有跨机同步与 mTLS。
- `direct` 语义简化:不参与路由,需要调用方自己配直连条目。
- 重载按 2 秒轮询 mtime,不是 inotify(跨平台优先)。

## 测试清单

| 文件 | 覆盖 | 数量 |
| --- | --- | --- |
| `tests/run_checks.py` | 命名、消毒、截断、按需判定、权限、项目作用域 | 15 |
| `tests/e2e_stdio.py` | 真子进程:复用、调用、超时、错误 | 7 |
| `tests/e2e_http.py` | HTTP 会话、404 重开、应答解析 | 5 |
| `tests/e2e_server.py` | 完整 MCP 会话与按需模式 | 13 |
| `tests/e2e_reload.py` | 热加载、管理接口、坏配置容错 | 8 |
| `tests/bench_concurrency.py` | 并发、懒加载、singleflight | 13 |

共 **61 项**,全部通过。

最简跑法(不需要 pytest):

```bash
python tests/run_checks.py
python tests/e2e_stdio.py
python tests/e2e_server.py
```

## 实测数据

### 召回

| 场景 | 结果 |
| --- | --- |
| 102 个工具,单次召回 | 67μs |
| 复杂度 | 严格 O(N),每工具 0.7–0.87μs |
| 检索方式 | **全量线性扫描**,无倒排索引、无向量 |

`tests/show_scoring.py` 与 `tests/show_no_index.py` 可复现这些数字。

### 并发

| 场景 | 结果 |
| --- | --- |
| 纯路由层(ping) | 579 req/s,48 并发 p50 40ms |
| 1 后端 8 并发调用(每个 1s) | 1.01s(串行 8s,8× 加速) |
| 12 并发 initialize | 0.03s |

并发度最终取决于后端:单线程的 MCP 服务器自己会排队。

### 延迟

| 项 | 值 |
| --- | --- |
| `tools/call`(本地服务器) | ~170ms |
| `tools/call`(跨路由) | ~1.2s |
| 工具表缓存命中 | 0.4ms |

## 已知问题

- 桥接(`bridge`)的服务器与本地服务器同名时,工具会变成 `x__tool` 和 `x__tool_2`
  两份。去重正确,但语义重复,建议本地不要与上游重复配置同一个服务器。

## 致谢

路由的设计(命名空间、进程池、按需发现、防递归桥接)来自
[magpie](https://github.com/yetone/magpie),本仓库是它的 Python 重述。
Magpie 与 mcphub 均为 MIT 许可。