mcp-multi-bridge 2.4.0 → 2.6.0

package/README.md

@@ -76,6 +76,63 @@ npm i -g mcp-multi-bridge mcp-multi-login
 MCP_MULTI_HOME=~/.my-mcp mcp-multi-bridge --preset ebs-plus
 ```
 
+## 免登录：按组织使用访问密钥
+
+后端支持 `X-Api-Key` 时，可以用密钥代替登录令牌，免去登录和过期重登。
+密钥按组织配置，一个变量装全部（`orgs[].key` 里可能有连字符，所以不能拆成变量名）：
+
+```json
+"env": {
+  "MCP_BRIDGE_SECRET_KEYS": "{\"test-taicang\":\"mom_xxx\",\"tc\":\"mom_yyy\"}"
+}
+```
+
+行为：
+
+| 组织 | 调用时 | 结果 |
+|---|---|---|
+| 配了密钥 | 只带 `apiKey`，**不带** `access_token` | MES 用密钥认证 |
+| 没配密钥 | 照旧带 `access_token` | 与原来完全一致 |
+
+两种凭据不混发——MES 收到空头时的行为不确定，混发会让排错变难。
+
+### 密钥失效时自动回退
+
+各系统对「密钥失效」的定义不统一，所以判据是**配置的错误码**，不是语义：
+
+```json
+"protocol": { "authFailureCodes": [626, 649, 613, 614, 615, 616] }
+```
+
+默认值覆盖 MES 的两种情形：`626`（设备未注册，等同没带密钥）、`649`（秘钥无效），
+再加上登录失效的 `613~616`（有些系统密钥失败会回落到令牌校验）。
+
+命中后：
+
+1. 用登录令牌重试一次
+2. 成功 → 该 **(组织 + 工具)** 冷却 5 分钟，期间直接走令牌（`MCP_BRIDGE_KEY_RETRY_MS`）
+3. 失败 → 返回**密钥调用的原始错误**，并列出令牌方式的错误，避免把「密钥配错」显示成「登录失效」
+
+冷却粒度到工具级：只有部分工具配了密钥透传时，一个工具的失败不会拖累其他工具。
+
+### 网关侧必须两边都配
+
+插件是按 `requestTemplate` 重建请求的，**不会透传客户端请求头**，所以密钥只能走「参数 + 模板」：
+
+```yaml
+# ① 工具参数里声明
+- description: "访问密钥，由调用方服务自动注入，无需人工填写"
+  name: apiKey
+  required: false
+  type: "string"
+
+# ② 请求模板里引用
+- key: "X-Api-Key"
+  value: "{{.args.apiKey}}"
+```
+
+缺任意一条都会静默失效（渲染成空值，MES 返回 626），不报错。
+
 ## 多后端与工具列表
 
 `config.json` 里的每个组织都带一个 `path`，指向它在 Higress 上的 MCP 路由。

package/bin.js

@@ -56,6 +56,13 @@ import { rpc, extractPayload } from './lib/higress.js';
 import { settings, DEFAULT_SETTINGS } from './lib/settings.js';
 import { buildIndex, searchTools, summarize } from './lib/toolindex.js';
 import { ensureConfig, listPresets, resolvePresetsDir } from './lib/preset.js';
+import {
+    secretKeyFor,
+    inKeyCooldown,
+    markKeyCooldown,
+    keyRetryMs,
+    API_KEY_FIELD
+} from './lib/secretkeys.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -454,9 +461,12 @@ function orgOverview(cfg) {
     const sections = groups.map((g) => {
         const rows = g.orgs.map((o) => {
             const isLogged = logged.has(o.key);
+            const hasKey = Boolean(secretKeyFor(o.key));
             const marks = [];
             if (o.key === current) marks.push('当前生效');
-            if (!isLogged) marks.push('未登录');
+            // 配了密钥的组织不需要登录；标出来，避免看到「未登录」误以为不能用
+            if (hasKey) marks.push('密钥认证');
+            else if (!isLogged) marks.push('未登录');
             const suffix = marks.length ? `（${marks.join('，')}）` : '';
             const auth = isLogged ? getOrgAuth(o.key) : null;
             const who = auth && auth.username ? `，账号 ${auth.username}` : '';
@@ -1095,22 +1105,76 @@ async function main() {
             }
 
             const { org, auth, reason } = selectOrg(cfg, orgKey, info.orgKeys);
-            if (!org || !auth) return textResult(reason || loginGuide('未登录'), true);
-
-            const result = await rpc(cfg, org, 'tools/call', {
-                name,
-                arguments: {
-                    ...bizArgs,
-                    [S.credentialField]: auth.token,
-                    // 租户 ID 必须由本层注入：网关模板通常是
-                    // {{if .args.orgId}}{{.args.orgId}}{{else}}1{{end}}，
-                    // 不传就一律按 1 查，同后端下的其他租户会查错组织。
-                    // 取值固定来自配置的 orgs[].orgId，tenantIdField 只决定发给网关的参数名。
-                    ...(org.orgId != null ? { [S.tenantIdField]: String(org.orgId) } : {})
-                }
+            if (!org) return textResult(reason || loginGuide('未登录'), true);
+
+            // 该组织配了密钥且不在冷却期 → 走密钥模式，不依赖登录令牌
+            const key = secretKeyFor(org.key);
+            const keyMode = Boolean(key) && !inKeyCooldown(org.key, name);
+            if (!keyMode && !auth) return textResult(reason || loginGuide('未登录'), true);
+
+            // 密钥模式只带 apiKey；令牌模式只带 credentialField。
+            // 两种凭据不混发：MES 收到空头时的行为不确定，混发会让排错变难。
+            const buildArgs = (useKey) => ({
+                ...bizArgs,
+                ...(useKey ? { [API_KEY_FIELD]: key } : { [S.credentialField]: auth.token }),
+                // 租户 ID 必须由本层注入：网关模板通常是
+                // {{if .args.orgId}}{{.args.orgId}}{{else}}1{{end}}，
+                // 不传就一律按 1 查，同后端下的其他租户会查错组织。
+                // 取值固定来自配置的 orgs[].orgId，tenantIdField 只决定发给网关的参数名。
+                ...(org.orgId != null ? { [S.tenantIdField]: String(org.orgId) } : {})
             });
 
-            const payload = extractPayload(result);
+            const callOnce = (useKey) => rpc(cfg, org, 'tools/call', { name, arguments: buildArgs(useKey) });
+
+            let usedKey = keyMode;
+            let result = await callOnce(usedKey);
+            let payload = extractPayload(result);
+
+            // 密钥失效：各系统的失效定义不统一，只认配置里的 authFailureCodes。
+            // 命中后用登录令牌重试一次；令牌也失败则返回密钥调用的原始错误，
+            // 避免把「密钥配错了」显示成「登录已失效」。
+            if (usedKey && payload && S.authFailureCodes.includes(payload.code)) {
+                const why = S.invalidReasons[payload.code] || payload.message || '凭据不可用';
+
+                if (!auth) {
+                    console.error(
+                        `[bridge] ${S.tenantLabel} ${org.key} 的密钥不可用（code=${payload.code}），且未登录无法回退`
+                    );
+                    return textResult(
+                        `工具 ${name} 调用失败：密钥不可用（code=${payload.code}：${why}）。\n\n` +
+                            `该${S.tenantLabel}尚未登录，无法回退到令牌方式。\n` +
+                            `请检查 MCP_BRIDGE_SECRET_KEYS 里 ${org.key} 的密钥是否正确，或先运行登录命令。`,
+                        true
+                    );
+                }
+
+                console.error(
+                    `[bridge] ${S.tenantLabel} ${org.key} 的密钥不可用（code=${payload.code}：${why}），改用登录令牌重试`
+                );
+                const retry = await callOnce(false);
+                const retryPayload = extractPayload(retry);
+
+                if (retryPayload && S.authFailureCodes.includes(retryPayload.code)) {
+                    console.error(`[bridge] ${S.tenantLabel} ${org.key} 的令牌同样不可用（code=${retryPayload.code}）`);
+                    return textResult(
+                        `工具 ${name} 调用失败，两种凭据都不可用。\n\n` +
+                            `密钥方式（X-Api-Key）：code=${payload.code} ${payload.message || why}\n` +
+                            `令牌方式（${S.credentialField}）：code=${retryPayload.code} ${retryPayload.message || '凭据不可用'}\n\n` +
+                            `请检查 MCP_BRIDGE_SECRET_KEYS 里 ${org.key} 的密钥，或重新登录后再试。`,
+                        true
+                    );
+                }
+
+                // 令牌能通 → 确认是密钥的问题，冷却一段时间直接走令牌
+                markKeyCooldown(org.key, name);
+                console.error(
+                    `[bridge] ${S.tenantLabel} ${org.key} 的「${name}」已回退到令牌，` +
+                        `${Math.round(keyRetryMs() / 60000)} 分钟内不再尝试密钥`
+                );
+                result = retry;
+                payload = retryPayload;
+                usedKey = false;
+            }
 
             // 失效判定有两个维度：
             //   invalidCodes      业务码，绝大多数系统走这条（HTTP 200 + code）

package/lib/preset.js

@@ -16,21 +16,43 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** 本包位于 <node_modules>/mcp-multi-bridge/lib，往上两层是 node_modules */
 const NODE_MODULES = path.resolve(HERE, '..', '..');
+const require = createRequire(import.meta.url);
 
 /**
- * preset 目录查找顺序
+ * preset 目录的查找顺序
  *
  * 1. 环境变量 MCP_BRIDGE_PRESETS —— 自定义目录，或本机没装 login 包时指过去
- * 2. 同级安装的 mcp-multi-login/presets —— 全局安装时两个包是兄弟目录
+ * 2. 按模块解析定位已安装的 mcp-multi-login —— 不猜目录层级，
+ *    npm 提升/嵌套安装都能找到
+ * 3. 兄弟目录 mcp-multi-login/presets —— npm 全局安装的常见形态
+ * 4. 兄弟目录 mes-login-cli/presets —— 源码工作区（仓库目录名与包名不同）
+ *
+ * 返回第一个真实存在的目录；都不存在时返回第 3 项，
+ * 让调用方的报错里给出「按默认位置找不到」的提示。
  */
 export function resolvePresetsDir() {
     const env = (process.env.MCP_BRIDGE_PRESETS || '').trim();
     if (env) return env;
-    return path.join(NODE_MODULES, 'mcp-multi-login', 'presets');
+
+    const candidates = [];
+    try {
+        const pkgPath = require.resolve('mcp-multi-login/package.json');
+        candidates.push(path.join(path.dirname(pkgPath), 'presets'));
+    } catch (e) {
+        // login 包未安装（optionalDependencies 被跳过），继续试兄弟目录
+    }
+    candidates.push(path.join(NODE_MODULES, 'mcp-multi-login', 'presets'));
+    candidates.push(path.join(NODE_MODULES, 'mes-login-cli', 'presets'));
+
+    for (const dir of candidates) {
+        if (fs.existsSync(dir)) return dir;
+    }
+    return candidates[1];
 }
 
 /** 列出可用的预设名，目录不存在时返回空数组 */

package/lib/secretkeys.js

@@ -0,0 +1,121 @@
+/**
+ * secretkeys.js —— 按组织解析访问密钥（X-Api-Key 模式）
+ *
+ * MES 一侧支持用请求头 X-Api-Key 代替登录令牌。密钥按组织分配，
+ * 一个桥接实例下可能同时存在「某组织用密钥、另一组织用登录令牌」的情况，
+ * 所以这里只做「按 orgKey 查表」，是否启用由调用方判定。
+ *
+ * 配置格式（一个环境变量装全部，避免 orgKey 里的连字符污染变量名）：
+ *
+ *   MCP_BRIDGE_SECRET_KEYS={"tc":"k1","hn":"k2","vn-plan":"k3"}
+ *
+ * 解析失败不抛错：整表视为空，全部退回登录令牌模式，并在 stderr 提示一次。
+ * 这条路径在请求链路上，任何异常都不该让服务不可用。
+ */
+
+/** 网关模板里承载密钥的参数名，必须与 Higress 的 requestTemplate 保持一致 */
+export const API_KEY_FIELD = 'apiKey';
+
+/** 缓存解析结果，避免每次调用都 JSON.parse */
+let cachedRaw = null;
+let cached = { keys: new Map(), error: null };
+
+/**
+ * 解析 MCP_BRIDGE_SECRET_KEYS
+ *
+ * @param {string|undefined} raw 环境变量原文
+ * @returns {{keys: Map<string,string>, error: string|null}}
+ *   空值返回空表且无错误（未启用）；非法 JSON 返回空表 + 错误说明
+ */
+export function parseSecretKeys(raw) {
+    const text = typeof raw === 'string' ? raw.trim() : '';
+    if (!text) return { keys: new Map(), error: null };
+
+    let obj;
+    try {
+        obj = JSON.parse(text);
+    } catch (e) {
+        return { keys: new Map(), error: `MCP_BRIDGE_SECRET_KEYS 不是合法 JSON：${e.message}` };
+    }
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        return { keys: new Map(), error: 'MCP_BRIDGE_SECRET_KEYS 必须是对象，形如 {"tc":"<密钥>"}' };
+    }
+
+    const keys = new Map();
+    for (const [k, v] of Object.entries(obj)) {
+        // 空值视为「该组织不启用密钥」，跳过而不是当成错误——
+        // 编排里把某个环境的密钥留空是很自然的做法
+        if (typeof v !== 'string' || !v.trim()) continue;
+        keys.set(String(k).trim(), v.trim());
+    }
+    return { keys, error: null };
+}
+
+/**
+ * 当前进程生效的密钥表（读环境变量，带缓存）
+ *
+ * @returns {{keys: Map<string,string>, error: string|null}}
+ */
+export function secretKeys() {
+    const raw = process.env.MCP_BRIDGE_SECRET_KEYS;
+    if (raw !== cachedRaw) {
+        cachedRaw = raw;
+        cached = parseSecretKeys(raw);
+        if (cached.error) console.error(`[bridge] ${cached.error}，将全部使用登录令牌模式`);
+    }
+    return cached;
+}
+
+/**
+ * 取某个组织的密钥
+ *
+ * @param {string} orgKey 配置里的 orgs[].key
+ * @returns {string|null} 未配置返回 null
+ */
+export function secretKeyFor(orgKey) {
+    if (!orgKey) return null;
+    return secretKeys().keys.get(String(orgKey)) || null;
+}
+
+/** 清缓存，仅供测试使用 */
+export function _resetSecretKeysCache() {
+    cachedRaw = null;
+    cached = { keys: new Map(), error: null };
+}
+
+/**
+ * 密钥失效后的冷却表
+ *
+ * 某个 (组织, 工具) 回退到令牌后，接下来一段时间直接走令牌，
+ * 不再每次都「先失败一次再重试」——否则一个没配透传的工具会让
+ * 每个请求都多打一次 MES。
+ *
+ * 粒度是「组织 + 工具」而不是「组织」：只有部分工具配了密钥透传时，
+ * 一个工具的失败不该把其他工具的密钥能力也拖下水。
+ */
+const cooldowns = new Map();
+
+/** 冷却时长，默认 5 分钟 */
+export function keyRetryMs() {
+    const v = Number(process.env.MCP_BRIDGE_KEY_RETRY_MS);
+    return Number.isFinite(v) && v >= 0 ? v : 300000;
+}
+
+export function markKeyCooldown(orgKey, toolName) {
+    cooldowns.set(`${orgKey}:${toolName}`, Date.now() + keyRetryMs());
+}
+
+export function inKeyCooldown(orgKey, toolName) {
+    const until = cooldowns.get(`${orgKey}:${toolName}`);
+    if (!until) return false;
+    if (Date.now() >= until) {
+        cooldowns.delete(`${orgKey}:${toolName}`);
+        return false;
+    }
+    return true;
+}
+
+/** 清空冷却表，仅供测试使用 */
+export function _clearCooldowns() {
+    cooldowns.clear();
+}

package/lib/settings.js

@@ -28,6 +28,16 @@ export const DEFAULT_TENANT_ID_FIELD = 'orgId';
 export const DEFAULT_HIDDEN_ARGS = [DEFAULT_CREDENTIAL_FIELD, DEFAULT_TENANT_ID_FIELD];
 /** 默认的登录失效错误码 */
 export const DEFAULT_INVALID_CODES = [613, 614, 615, 616];
+/**
+ * 默认的「密钥失效」错误码（X-Api-Key 模式）
+ *
+ * 各系统对密钥失效的定义不统一，所以不靠语义判断，只认配置里的码：
+ *   626  设备未注册（等于没带密钥，MES 侧对空的 X-Api-Key 就是这个）
+ *   649  秘钥无效
+ * 再加上登录失效的 613~616：某些系统密钥失败时直接回落到令牌校验，
+ * 报的仍是登录相关码。
+ */
+export const DEFAULT_AUTH_FAILURE_CODES = [626, 649, 613, 614, 615, 616];
 /**
  * 默认的登录失效 HTTP 状态码
  *
@@ -130,6 +140,7 @@ export function settings(cfg) {
         tenantIdField,
         hiddenArgs,
         invalidCodes: codeList(cfg?.invalidCodes, DEFAULT_INVALID_CODES),
+        authFailureCodes: codeList(cfg?.authFailureCodes, DEFAULT_AUTH_FAILURE_CODES),
         invalidHttpStatus: codeList(cfg?.invalidHttpStatus, DEFAULT_INVALID_HTTP_STATUS),
         invalidReasons: reasonMap(cfg?.invalidCodeReasons),
         loginCommand: isNonEmptyString(cfg?.loginCommand) ? cfg.loginCommand.trim() : DEFAULT_LOGIN_COMMAND

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-multi-bridge",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "多后端 MCP 桥接：把网关后多个后端、多个租户的工具集合并成一个 MCP 服务，凭据由登录 CLI 提供",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   "scripts": {
     "start": "node bin.js",
     "pack:check": "npm pack --dry-run",
-    "test": "node test/toolindex.test.mjs && node test/headers.test.mjs && node test/preset.test.mjs"
+    "test": "node test/toolindex.test.mjs && node test/headers.test.mjs && node test/preset.test.mjs && node test/secretkeys.test.mjs"
   },
   "keywords": [
     "mcp",
@@ -30,5 +30,8 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2"
+  },
+  "optionalDependencies": {
+    "mcp-multi-login": "^3.5.0"
   }
 }