mcp-multi-bridge 2.3.0 → 2.3.2

package/README.md

@@ -130,7 +130,20 @@ call_tool                 调用任意工具
 ```
 
 `search_tools` 的返回只给「名称 + 一句话 + 前几个参数名」，不给完整 schema——
-一个完整 schema 就几百 token，一次返回 5 个等于回到全量暴露。需要细节时走 `describe_tool`。
+一个完整 schema 就几百 token，一次返回 10 个就等于回到全量暴露。需要细节时走 `describe_tool`。
+
+**命中多个时不自动挑一个。** bridge 不知道上下文：用户说「物料」可能是查也可能是建，
+猜错会调错工具、产生副作用（误删数据是最坏情况）。所以按分数排好后交给模型选。
+
+返回条数默认 5，可传 `limit`，**上限 10**。上限卡在 10 是因为：
+一次返回太多，模型的选择准确率会下降，而且每条结果都占上下文。
+需要看更多时应该收窄查询词，而不是调大 limit。
+
+排序依据三层：
+
+1. 文本相关度 —— 名称命中 > 参数名命中 > 描述命中
+2. 意图加权 —— 「料号」偏向读操作，「创建料号」偏向写操作
+3. 名称字典序 —— 完全平票时的兜底，保证同样查询返回同样顺序
 
 实测 1200 个工具（6 套系统 × 200）：
 
@@ -287,6 +300,54 @@ bridge 侧**不维护任何业务词对照表**。
 两种做法的取舍：拆 server 简单但要维护多套配置和凭证；分层只维护一套，
 代价是每次找工具多一跳。系统数量不多时，拆 server 更省事。
 
+### 网关侧认证（key-auth）
+
+桥接默认只发 `Content-Type`，不带任何认证头——业务登录 token 是作为**工具参数**
+传给后端的，不参与网关认证。所以当网关对某个端点开了 Key 认证时，
+必须让桥接额外带一个头，否则该端点会直接 401（表现为只剩本地的 `login` 工具）。
+
+三个来源，后者覆盖前者：
+
+| 来源 | 作用范围 | 适合 |
+| --- | --- | --- |
+| `MCP_BRIDGE_HEADERS`（环境变量，JSON） | 本实例所有组织 | 一套凭证走全部环境 |
+| `config.json` 顶层 `headers` | 本实例所有组织 | 同上，但想写进配置文件 |
+| `orgs[].headers` | 单个组织 | 每个环境用不同凭证 |
+
+最省事的是写在客户端条目的 `env` 里：
+
+```json
+{
+  "mcpServers": {
+    "mes": {
+      "command": "mcp-multi-bridge",
+      "args": ["--name", "mes"],
+      "env": {
+        "MCP_BRIDGE_HEADERS": "{\"Authorization\":\"Bearer <网关消费者凭证>\"}"
+      }
+    }
+  }
+}
+```
+
+要给不同环境配不同消费者，就写进 `config.json` 的组织里（优先级更高）：
+
+```json
+{
+  "orgs": [
+    { "key": "test", "path": "/mcp-servers/mes-mcp-server" },
+    { "key": "prod", "path": "/mcp-servers/tc-mes-mcp-server",
+      "headers": { "Authorization": "Bearer <prod 的凭证>" } }
+  ]
+}
+```
+
+三个来源都没配时，请求头与旧版完全一致，不影响未开认证的网关。
+
+> 凭证是明文，别提交进仓库；`MCP_BRIDGE_HEADERS` 不是合法 JSON 时会被忽略并打一行提示，
+> 不会让进程退出——但那个端点会因此 401，排查时先看这条提示。
+
+
 ## 检查安装的版本
 
 ```bash

package/bin.js

@@ -628,7 +628,7 @@ function metaTools(items, bySystem, tenantLabel) {
                 properties: {
                     query: { type: 'string', description: '检索词。中英文都可以，描述你要做的事或涉及的业务对象' },
                     system: { type: 'string', description: '可选，只在某套系统内搜索。留空则搜全部' },
-                    limit: { type: 'number', description: '返回条数，默认 5，最多 20' }
+                    limit: { type: 'number', description: '返回条数，默认 5，最多 10' }
                 },
                 required: ['query']
             }

package/lib/higress.js

@@ -12,13 +12,44 @@ import { orgUrl } from './config.js';
 // 自增 id，避免同毫秒并发撞号
 let rpcSeq = 0;
 
+/**
+ * 附加到网关请求上的头
+ *
+ * 用于网关侧的消费者认证（如 key-auth 的 Authorization）。三个来源按优先级合并，
+ * 后者覆盖前者：
+ *   1. 环境变量 MCP_BRIDGE_HEADERS —— 客户端 mcp.json 的 env 里配，JSON 字符串
+ *   2. config.json 顶层 headers —— 对本实例所有组织生效
+ *   3. orgs[].headers —— 只对该组织生效，用于不同环境不同凭证
+ *
+ * 都没配时返回空对象，请求头与旧版完全一致（不改变既有行为）。
+ * 为什么不放在工具参数里：网关的 key-auth 只认请求头，参数是给后端业务用的。
+ */
+export function bridgeHeaders(cfg, org) {
+    let fromEnv = {};
+    const raw = process.env.MCP_BRIDGE_HEADERS;
+    if (raw) {
+        try {
+            const v = JSON.parse(raw);
+            if (v && typeof v === 'object' && !Array.isArray(v)) fromEnv = v;
+            else console.error('[bridge] MCP_BRIDGE_HEADERS 必须是 JSON 对象，已忽略');
+        } catch (e) {
+            console.error('[bridge] MCP_BRIDGE_HEADERS 不是合法 JSON，已忽略');
+        }
+    }
+    return {
+        ...fromEnv,
+        ...((cfg && cfg.headers) || {}),
+        ...((org && org.headers) || {})
+    };
+}
+
 /**
  * 发一个 JSON-RPC 请求到网关
  */
 export async function rpc(cfg, org, method, params) {
     const res = await fetch(orgUrl(cfg, org), {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', ...bridgeHeaders(cfg, org) },
         body: JSON.stringify({ jsonrpc: '2.0', id: ++rpcSeq, method, params })
     });
     const text = await res.text();

package/lib/toolindex.js

@@ -340,13 +340,20 @@ function actionBonus(query, name) {
  * 匹配依据只认三处：工具名、描述、参数名。缺中文就去补描述，
  * 不在桥接层维护一张注定对不齐的词表。
  *
+ * 命中多个时按分数排序取前 N 个，不自动挑一个——bridge 不知道上下文，
+ * 用户说「物料」可能是查也可能是建，猜错会调错工具、产生副作用。
+ * 选择权留给模型。
+ *
+ * 上限 10：一次返回太多，模型的选择准确率会下降，
+ * 而且每条结果都占上下文。需要更多时应该收窄查询词。
+ *
  * @param {Map} items buildIndex 返回的 items
  * @param {string} query 检索词
  * @param {{system?:string, limit?:number}} opts
  */
 export function searchTools(items, query, opts = {}) {
     const q = String(query || '').trim();
-    const limit = Math.max(1, Math.min(50, opts.limit || 5));
+    const limit = Math.max(1, Math.min(10, opts.limit || 5));
     if (!q) return [];
 
     const qTokens = tokenize(q);

package/package.json

@@ -1,34 +1,34 @@
-{
-  "name": "mcp-multi-bridge",
-  "version": "2.3.0",
-  "description": "多后端 MCP 桥接：把网关后多个后端、多个租户的工具集合并成一个 MCP 服务，凭据由登录 CLI 提供",
-  "type": "module",
-  "bin": {
-    "mcp-multi-bridge": "bin.js"
-  },
-  "files": [
-    "bin.js",
-    "lib/",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "start": "node bin.js",
-    "pack:check": "npm pack --dry-run",
-    "test": "node test/toolindex.test.mjs"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "bridge",
-    "multi-tenant",
-    "multi-backend",
-    "mes"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.2"
-  }
-}
+{
+  "name": "mcp-multi-bridge",
+  "version": "2.3.2",
+  "description": "多后端 MCP 桥接：把网关后多个后端、多个租户的工具集合并成一个 MCP 服务，凭据由登录 CLI 提供",
+  "type": "module",
+  "bin": {
+    "mcp-multi-bridge": "bin.js"
+  },
+  "files": [
+    "bin.js",
+    "lib/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin.js",
+    "pack:check": "npm pack --dry-run",
+    "test": "node test/toolindex.test.mjs && node test/headers.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bridge",
+    "multi-tenant",
+    "multi-backend",
+    "mes"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2"
+  }
+}