mcp-multi-bridge 2.3.1 → 2.4.0

package/README.md

@@ -42,6 +42,40 @@ npm i -g mcp-multi-bridge mcp-multi-login
 >
 > 配置目录与 `config.json` 结构不变，无需重新登录。
 
+### 首次使用：配好 mcp.json 即可，不用先跑命令
+
+配置不存在时，bridge 启动会按预设自动生成，无需先手动执行登录命令：
+
+```json
+"ebs-plus": {
+  "command": "mcp-multi-bridge",
+  "args": ["--name", "ebs-plus"]
+}
+```
+
+启动后按以下顺序找预设：
+
+| 顺序 | 来源 | 说明 |
+|---|---|---|
+| 1 | `--preset <名>` | 显式指定，优先级最高 |
+| 2 | `--name <名>` 同名匹配 | `--name ebs-plus` → `presets/ebs-plus.json` |
+| 3 | 都没有 | 不生成，按原行为提示运行登录命令 |
+
+预设文件来自 `mcp-multi-login` 包（`presets/`），所以**两个包都要安装**。
+预设不在默认位置时用 `MCP_BRIDGE_PRESETS=<目录>` 指定。
+
+三条边界：
+
+- **已存在的 `config.json` 一律不覆盖**，手改过的内容不会被冲掉
+- 只生成配置，不写 token——首次调用业务工具时仍需登录一次
+- 生成过程只在 stderr 打印一行，不会污染 stdout 的 JSON-RPC 通道
+
+用 `MCP_MULTI_HOME` 指定目录时 `--name` 为空，此时只能靠 `--preset` 指定：
+
+```bash
+MCP_MULTI_HOME=~/.my-mcp mcp-multi-bridge --preset ebs-plus
+```
+
 ## 多后端与工具列表
 
 `config.json` 里的每个组织都带一个 `path`，指向它在 Higress 上的 MCP 路由。
@@ -300,6 +334,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

@@ -55,6 +55,7 @@ import { getOrgAuth, getCurrentOrgKey, listLoggedInOrgs } from './lib/token.js';
 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';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -163,6 +164,59 @@ function pathAllowed(p, allow) {
     });
 }
 
+/**
+ * 取 --flag 后面的值；没有该参数时返回空字符串
+ */
+function argOf(argv, flag) {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? String(argv[i + 1] || '').trim() : '';
+}
+
+/**
+ * 首次启动时按预设生成 config.json
+ *
+ * 只写 stderr：stdout 是 JSON-RPC 通道，写一个字都会破坏 MCP 握手。
+ * 任何失败都只提示、不退出——服务还能以「仅 login 工具」的形态起来，
+ * 比直接崩掉更容易让用户看到原因。
+ */
+function tryInitFromPreset(argv) {
+    if (!CONFIG_FILE) return;
+
+    const preset = argOf(argv, '--preset');
+    let r;
+    try {
+        r = ensureConfig({ configFile: CONFIG_FILE, name: CONFIG_NAME, preset });
+    } catch (e) {
+        console.error(`[bridge] 自动初始化配置失败（不影响启动）：${e.message}`);
+        return;
+    }
+
+    if (r.created) {
+        console.error(`[bridge] 已按预设「${r.preset}」初始化配置: ${r.file}`);
+        return;
+    }
+    if (r.reason === 'exists' || r.reason === 'no_name') return;
+
+    if (r.reason === 'presets_dir_missing') {
+        console.error(
+            `[bridge] 未找到预设目录 ${resolvePresetsDir()}\n` +
+            '  自动初始化需要 mcp-multi-login 包提供的预设：npm i -g mcp-multi-login'
+        );
+        return;
+    }
+    if (r.reason === 'preset_not_found') {
+        const avail = listPresets(resolvePresetsDir());
+        console.error(
+            `[bridge] 预设「${preset || CONFIG_NAME}」不存在，可用：${avail.join('、') || '（无）'}\n` +
+            `  也可以手动创建 ${CONFIG_FILE}`
+        );
+        return;
+    }
+    if (r.reason === 'invalid_preset') {
+        console.error(`[bridge] 预设「${preset || CONFIG_NAME}」内容不合法（缺 baseUrl 或 orgs），已跳过`);
+    }
+}
+
 /**
  * 处理 --version / --help / --status
  *
@@ -239,6 +293,13 @@ async function handleCli(argv) {
   以前没配时会静默用 ~/.mes-mcp-login，导致新系统忘配就读到 MES 的数据。
   现在没配直接报错，不再猜。
 
+首次配置（自动生成）:
+  配置不存在时，启动会按预设复制一份，无需先手动运行登录命令：
+    --name ebs-plus         套用 mcp-multi-login 包里的 presets/ebs-plus.json
+    --preset <名>           显式指定预设，优先于 --name 同名匹配
+    MCP_BRIDGE_PRESETS=<目录> 预设目录不在 login 包默认位置时指定
+  已存在的 config.json 一律不覆盖；生成后仍需登录一次才有业务凭据。
+
 当前配置目录: ${CONFIG_DIR || '（未配置）'}
 配置文件: ${CONFIG_FILE || '（未配置）'}
 登录文件: ${CONFIG_DIR ? CONFIG_DIR + '/token.json' : '（未配置）'}（由 ${L.loginCommand} 写入）
@@ -301,7 +362,9 @@ async function handleCli(argv) {
     return false;
 }
 
-if (await handleCli(process.argv.slice(2))) {
+const ARGV = process.argv.slice(2);
+
+if (await handleCli(ARGV)) {
     process.exit(0);
 }
 
@@ -313,6 +376,10 @@ if (!CONFIG_DIR) {
     process.exit(1);
 }
 
+// 配置不存在时按预设生成，省掉「必须先手动跑一次登录命令」这一步。
+// 放在 handleCli 之后：--help / --version 不该有写文件的副作用。
+tryInitFromPreset(ARGV);
+
 function textResult(text, isError = false) {
     return {
         content: [{ type: 'text', text }],

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/preset.js

@@ -0,0 +1,125 @@
+/**
+ * preset.js —— 首次启动时按预设生成 config.json
+ *
+ * 背景：config.json 的唯一所有者是 `mcp-multi-login`（presets/ 在它那边），
+ * bridge 只读不写。于是「先配 mcp.json、客户端拉起 bridge」这条路径上没人写配置，
+ * 第一次连上只能退化成一个只有 login 工具的服务，用户必须先手动跑一次登录命令。
+ *
+ * 本模块把这一步收进 bridge：启动时若配置不存在，按预设复制一份。
+ *
+ * 四条约束：
+ *   1. 只在 config.json **不存在**时写，已存在一律不动（不覆盖用户改过的内容）
+ *   2. 不猜目录：仍要求显式 --name 或 MCP_MULTI_HOME（静默默认目录曾导致登错环境）
+ *   3. preset 文件仍由 login 包提供，本包不复制一份，避免两边漂移
+ *   4. 任何失败都不抛出，只返回 reason —— 初始化失败不该让服务起不来
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** 本包位于 <node_modules>/mcp-multi-bridge/lib，往上两层是 node_modules */
+const NODE_MODULES = path.resolve(HERE, '..', '..');
+
+/**
+ * preset 目录查找顺序
+ *
+ * 1. 环境变量 MCP_BRIDGE_PRESETS —— 自定义目录，或本机没装 login 包时指过去
+ * 2. 同级安装的 mcp-multi-login/presets —— 全局安装时两个包是兄弟目录
+ */
+export function resolvePresetsDir() {
+    const env = (process.env.MCP_BRIDGE_PRESETS || '').trim();
+    if (env) return env;
+    return path.join(NODE_MODULES, 'mcp-multi-login', 'presets');
+}
+
+/** 列出可用的预设名，目录不存在时返回空数组 */
+export function listPresets(dir) {
+    try {
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => f.replace(/\.json$/, ''))
+            .sort();
+    } catch (e) {
+        return [];
+    }
+}
+
+/**
+ * 读取并校验一个预设
+ *
+ * @returns {object|null} 结构不合格时返回 null（宁可不生成，也不写一份坏配置）
+ */
+export function readPreset(dir, name) {
+    if (!name) return null;
+    try {
+        const file = path.join(dir, `${name}.json`);
+        if (!fs.existsSync(file)) return null;
+        const cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!cfg || typeof cfg !== 'object') return null;
+        if (!Array.isArray(cfg.orgs) || !cfg.orgs.length) return null;
+        // baseUrl 与 orgs[].path 是后续一切请求的基础，缺了等于不能用
+        if (typeof cfg.baseUrl !== 'string' || !cfg.baseUrl.trim()) return null;
+        if (!cfg.orgs.every((o) => o && typeof o.key === 'string' && o.key && typeof o.path === 'string' && o.path)) {
+            return null;
+        }
+        return cfg;
+    } catch (e) {
+        return null;
+    }
+}
+
+/**
+ * 配置不存在时按预设生成
+ *
+ * @param {object} opts
+ * @param {string} opts.configFile  目标文件（CONFIG_FILE）
+ * @param {string} [opts.name]      --name 传入的系统名；用 MCP_MULTI_HOME 时为空
+ * @param {string} [opts.preset]    --preset 显式指定，优先级高于 name
+ * @param {string} [opts.presetsDir] 覆盖预设目录（测试用）
+ * @returns {{created:boolean, file?:string, preset?:string, reason?:string}}
+ *   reason 取值：exists / no_name / presets_dir_missing / preset_not_found / invalid_preset
+ */
+export function ensureConfig(opts = {}) {
+    const { configFile, name, preset, presetsDir } = opts;
+
+    if (!configFile) return { created: false, reason: 'no_config_file' };
+    if (fs.existsSync(configFile)) return { created: false, reason: 'exists' };
+
+    // --preset 优先；否则用 --name 同名匹配（presets 的文件名就等于系统名）
+    const target = (preset || name || '').trim();
+    if (!target) return { created: false, reason: 'no_name' };
+
+    const dir = presetsDir || resolvePresetsDir();
+    if (!fs.existsSync(dir)) return { created: false, reason: 'presets_dir_missing' };
+
+    const cfg = readPreset(dir, target);
+    if (!cfg) {
+        // 区分「文件没有」和「文件损坏」，两者的排查方向完全不同
+        const file = path.join(dir, `${target}.json`);
+        return {
+            created: false,
+            reason: fs.existsSync(file) ? 'invalid_preset' : 'preset_not_found'
+        };
+    }
+
+    const targetDir = path.dirname(configFile);
+    fs.mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+
+    // 原子写：客户端可能同时拉起多个实例，直接写会让另一个读到半个 JSON
+    const tmp = `${configFile}.tmp-${process.pid}`;
+    try {
+        fs.writeFileSync(tmp, JSON.stringify(cfg, null, 4), { encoding: 'utf8', mode: 0o600 });
+        fs.renameSync(tmp, configFile);
+    } catch (e) {
+        try {
+            fs.unlinkSync(tmp);
+        } catch (ignored) {
+            // 清理临时文件失败不掩盖原始错误
+        }
+        throw e;
+    }
+
+    return { created: true, file: configFile, preset: target };
+}

package/package.json

@@ -1,34 +1,34 @@
-{
-  "name": "mcp-multi-bridge",
-  "version": "2.3.1",
-  "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.4.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 && node test/headers.test.mjs && node test/preset.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bridge",
+    "multi-tenant",
+    "multi-backend",
+    "mes"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2"
+  }
+}