mcp-multi-bridge 2.1.4 → 2.3.0

package/README.md

@@ -52,7 +52,7 @@ bridge 拉取工具列表的规则：
 
 1. 按 `path` 去重，同一 path 只查一次（不是按组织逐个查）
 2. 多个 path 并行查询
-3. 按**工具名**合并：同名工具只出现一次，`orgKey` 的可选值是提供该工具的所有组织
+3. 按**工具名**合并，同名是否合并看参数结构（见下）
 4. 单个 path 失败不阻断整体，能拿到多少给多少，失败的写进 `login` 工具的告警里
 
 ### `orgKey` 只能选同后端的组织
@@ -60,36 +60,232 @@ bridge 拉取工具列表的规则：
 这是为了避免一种必然失败的情况：工具来自 A 后端，`orgKey` 却指向 B 后端的组织，
 请求发过去那边不认识这个工具。bridge 会在调用前校验，跨后端直接拒绝并列出可用选项。
 
-### 工具数量上限
+### 同名工具怎么合并
 
-默认上限 40 个。超过后会在 `login` 工具的描述里告警——工具过多会挤占模型上下文，
-也会降低工具选择的准确率。真到这一步，说明该拆 server 了。
+不同 path 下出现同名工具时，按 `inputSchema` 的指纹判断：
+
+| 情况 | 处理 | 例子 |
+|---|---|---|
+| 结构相同 | **合并**成一个工具，`orgKey` 取并集 | sz / tc / vn 三个 MES 环境共用一套 API |
+| 结构不同 | **拆开**，加 `<系统>__` 前缀 | MES 的 `search(rid)` 与 ERP 的 `search(keyword)` |
+
+结构相同说明是同一套后端的不同部署环境，靠 `orgKey` 就能区分，加前缀反而让模型困惑。
+结构不同则是真的两个工具，必须区分，否则模型会拿着 A 系统的参数去调 B 系统。
+
+系统名从 path 末段提取并去掉 `-mcp-server` / `-api` 后缀：
+`/mcp-servers/sz-mes-mcp-server` → `sz-mes`，冲突时暴露为 `sz-mes__search`。
+
+**例外**：如果一个实例只连一个后端（一套系统一个 `--name`），系统名直接取
+`--name` 的值，不再从 path 推导。部署者写什么就是什么，比从 path 猜更准：
+
+```
+--name warehouse，path 是 /mcp-servers/erp-api
+  → 系统名取 warehouse，不取 erp
+```
+
+因为这时 `--name` 和系统是一一对应的，没有歧义。多后端聚合时
+`--name` 代表的是配置目录、下面挂着好几套系统，只能按 path 区分。
+
+## 三个容易混淆的 name
+
+| 名称 | 在哪 | 作用 |
+|---|---|---|
+| `--name` | 命令行 | **只用来算配置目录** `~/.<name>-mcp-login`，不参与路由 |
+| `orgs[].path` | config.json | **决定调用哪个 MCP server**，唯一的路由依据 |
+| mcp.json 的 key | 客户端配置 | 客户端侧 server 名，工具前缀 `mcp__<key>__` 来自它 |
+
+`--name` 不决定调用哪个后端。一个 `--name` 可以聚合多个 path
+（当前 `--name mes` 下有 5 个 path、10 个组织），这种情况必须靠 path 区分系统。
+
+## 工具很多时：按需检索
+
+工具定义要常驻模型上下文。按中等复杂度工具约 350 tokens 估算：
+
+| 工具数 | 常驻开销 | 能否直接用 |
+|---|---|---|
+| 20 | 7K | ✅ |
+| 100 | 35K | ✅ 但选择准确率开始下降 |
+| 500 | 175K | ⚠ 接近上限 |
+| 1000 | 350K | ❌ 超过多数模型整个窗口 |
+
+所以工具多了不能全塞。bridge 有三种模式：
+
+```
+MCP_BRIDGE_TOOL_MODE=auto      默认。工具数超过 40 自动切 layered
+MCP_BRIDGE_TOOL_MODE=layered   强制分层
+MCP_BRIDGE_TOOL_MODE=flat      强制全量
+```
+
+**默认 auto 而不是一直分层**：工具少时分层反而多一层间接，模型要先 `search_tools`
+才能调，纯属负担。只有当全量塞不下时才值得这个代价。
+
+### 分层时模型看到什么
+
+```
+login                     状态查询
+search_tools              按关键词检索工具（描述里带系统目录摘要）
+describe_tool             看某个工具的完整参数定义
+call_tool                 调用任意工具
++ 常驻的 N 个高频工具      默认 20 个
+```
+
+`search_tools` 的返回只给「名称 + 一句话 + 前几个参数名」，不给完整 schema——
+一个完整 schema 就几百 token，一次返回 5 个等于回到全量暴露。需要细节时走 `describe_tool`。
+
+实测 1200 个工具（6 套系统 × 200）：
+
+```
+flat    : 604 KB ≈ 177K tokens
+layered :  12 KB ≈   4K tokens     降幅 98%
+检索延迟: 10-40ms
+```
+
+### 常驻哪些工具
+
+默认按组织覆盖数排序取前 N 个——被多套部署共用的工具更可能是每次都用的。
+但真实频次只有日志知道，所以应该按调用统计把名单固化下来：
+
+```bash
+MCP_BRIDGE_RESIDENT_COUNT=20
+MCP_BRIDGE_RESIDENT=searchRidReport,captchaGet
+```
+
+> **这两个只对分层模式生效。** 工具没超过 40 个时走 flat（全量暴露），
+> 它们会被忽略。为免误以为配置写错，这种情况会在 stderr 和 `login` 工具的描述里
+> 各提示一次——`login` 那条是给客户端界面看的，因为多数客户端不显示 stderr。
+
+统计方法（如果接了 Loki，`request_body` 里有工具名）：
+
+```logql
+sum by (tool) (count_over_time({filename=~".+"} | json | line_format "{{.request_body}}" |= "tools/call" [7d]))
+```
+
+### 客户端最终看到几个工具
+
+分层模式下是 `1 + 3 + N`：
+
+| 组成 | 数量 | 能否配置 |
+|---|---|---|
+| `login` | 1 | 不能，本包提供的状态查询 |
+| `search_tools` / `describe_tool` / `call_tool` | 3 | 不能，分层机制本身 |
+| 常驻业务工具 | 默认 20（上限 200） | `MCP_BRIDGE_RESIDENT_COUNT` / `MCP_BRIDGE_RESIDENT` |
+
+所以默认是 24 个。但这是「工具数超过 40」之后才会出现的情况——
+工具少的时候走 flat，看到的就是 `1 + 全部业务工具`。
+
+### 聚合几十上百套 MCP 时
+
+一个 bridge 可以聚合任意多个 path。数量上去之后有两个成本要处理：
+
+**1. 全量拉取很贵**
+
+启动时要对每个后端发一次 `tools/list`。实测（单后端 30ms 延迟）：
+
+| 后端数 | 首次拉取 |
+|---|---|
+| 5 | 约 1 秒 |
+| 50 | 约 6 秒 |
+| 200 | 约 20 秒 |
+
+所以工具清单**按 TTL 缓存**，默认 5 分钟：
+
+```bash
+MCP_BRIDGE_TOOLS_TTL_MS=300000
+```
+
+缓存期必须远大于拉取耗时，否则客户端每次刷新都要重来一遍——实测 200 个后端时，
+缓存让重复的 `tools/list` 从 19 秒降到 0.1 秒。
+
+**新增的工具怎么被发现？** 不需要把 TTL 调小。`tools/call` 进来时如果索引里
+查不到该工具，会自动强制刷新一次再判断。所以「网关刚加了工具、模型马上要用」
+这个场景是通的，代价只有那一次调用多花一轮拉取。
+
+**2. 并发要限**
+
+不设上限时 200 个后端会在同一瞬间建立 200 个连接，网关和本地 socket 都吃不住，
+而且失败会一起失败。
+
+```bash
+MCP_BRIDGE_FETCH_CONCURRENCY=16
+```
+
+默认 16。实测 200 个后端下，8 并发约 28 秒、16 并发约 18 秒，再往上收益不明显
+（压测环境是单进程 mock，序列化大 JSON 会成为新瓶颈，真实网关下最优值可能不同）。
+
+### 检索是怎么打分的
+
+不是向量检索，是加权关键词命中。1000 个工具用倒排就够，上 embedding 反而多一个服务要维护。
+
+**匹配依据只有三处**：工具名、描述、参数名。全部来自工具定义本身，
+bridge 侧**不维护任何业务词对照表**。
+
+早期版本内置过一份约 30 条的「料号 → material/item」别名表，后来删掉了，因为实测有两个问题：
+
+| 问题 | 说明 |
+|---|---|
+| 对写全中文描述的工具零贡献 | 真实 MES 的描述里本来就有「料号、批次、仓库、库位」，别名表一条都没用上 |
+| 会误匹配 | 「料号」被映射到 `item`，而别的系统里 `item` 可能是电商商品，`queryItem` 就被错误命中 |
+
+所以规则很简单：**工具名或描述里有这个词，就能搜到；没有就搜不到。**
+这是可预期的，也不会出现「bridge 猜错了领域」这种难以排查的情况。
+
+**新增工具不需要改代码**：
+
+```
+新增 queryCustomsDeclaration，描述「查询报关单」
+  「报关单」→ 命中（中文来自 description）
+  「customs」→ 命中（英文来自 name）
+  「declNo」→ 命中（参数名）
+```
+
+搜不到时，问题在工具定义，不在 bridge。正确的修法是**在网关侧补描述**：
+
+```
+❌ doZzz / "Process ZZZ"           「质量追溯」搜不到
+✅ doZzz / "质量追溯 · Process ZZZ"  「质量追溯」直接命中
+```
+
+描述里带上用户可能说的中文说法（含同义词），比维护一份注定对不齐的词表更省事，
+也不会漏掉长尾——业务词根本不可能靠人工枚举穷尽。
+
+**2. 意图分级**。业务 API 的工具名几乎都是 `queryXxx` / `createXxx` / `updateXxx` /
+`deleteXxx` 四件套，光看业务对象四个分数完全一样。用户说「料号」时想要的是查不是创建，
+所以按动作词加权重：
+
+```
+「料号」    → queryMaterial    只说业务对象，偏向读操作
+「创建物料」 → createMaterial   明说动作，导向写操作
+「导出物料」 → exportMaterial   导出和查询都是读，靠动作词再分一层
+```
+
+只想业务对象时不会优先给出「删除批次」这类写操作——读操作选错代价小，写操作有数据风险。
 
 ### 拆成多个客户端条目
 
-不想把所有后端压在一个 bridge 里，可以用环境变量限定本实例负责的 path：
+另一种办法是不分层，而是用环境变量限定本实例负责的 path：
 
 ```json
 {
   "mcpServers": {
     "mes-test": {
       "command": "mcp-multi-bridge",
-      "args": [],
-      "env": { "MES_MCP_PATHS": "mes-mcp-server" }
+      "args": ["--name", "mes-test"],
+      "env": { "MCP_BRIDGE_PATHS": "mes-mcp-server" }
     },
     "mes-prod": {
       "command": "mcp-multi-bridge",
-      "args": [],
-      "env": { "MES_MCP_PATHS": "tc-mes-mcp-server" }
+      "args": ["--name", "mes-prod"],
+      "env": { "MCP_BRIDGE_PATHS": "tc-mes-mcp-server" }
     }
   }
 }
 ```
 
-`MES_MCP_PATHS` 用逗号分隔，可以写完整 path（`/mcp-servers/xxx`），
-也可以只写末段（`xxx`），两种都识别。
+`MCP_BRIDGE_PATHS` 用逗号分隔，可以写完整 path（`/mcp-servers/xxx`），
+也可以只写末段（`xxx`），两种都识别。旧名 `MES_MCP_PATHS` 仍兼容。
 
-这样客户端列表里会出现两个独立条目，各自的工具集和 `orgKey` 范围互不干扰。
+两种做法的取舍：拆 server 简单但要维护多套配置和凭证；分层只维护一套，
+代价是每次找工具多一跳。系统数量不多时，拆 server 更省事。
 
 ## 检查安装的版本
 
@@ -322,6 +518,8 @@ mcp-multi-login --home "C:/Users/你/.mes-mcp-login" --org tc
 ## 提供的工具
 
 工具列表由网关返回，本包原样透传。`login` 会被本包替换成本地状态查询工具。
+分层模式下还会额外提供 `search_tools` / `describe_tool` / `call_tool` 三个元工具，
+用于按需发现工具，避免把上千个定义全塞进上下文。
 
 工具本身（有哪些、叫什么、什么参数）完全取决于网关侧配置，本包不做增删。
 当前 MES 网关提供的是：