mcp-multi-bridge 0.0.0-stage → 2.1.0

package/README.md

@@ -1,3 +1,337 @@
-# Temporary Holding Version
+# mcp-multi-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+多后端 MCP 桥接（stdio 代理）。
+
+把一个网关后面「多个后端 × 多个租户」的工具集，合并成一个 MCP 服务暴露给客户端；
+调用时按 `orgKey` 选中租户，自动注入凭据后转发。
+
+**只做转发，不做登录。** 没有 HTTP 服务、不监听端口、不弹浏览器。
+
+最初为 MES 系统而写，现已与具体业务系统解耦：系统名、租户称谓、凭据字段名、
+登录失效错误码、登录命令全部可配置（见[自定义](#自定义系统差异)）。不配置时沿用 MES 的默认值。
+
+## 安装
+
+```bash
+npm i -g mcp-multi-bridge mcp-multi-login
+```
+
+两个包配合使用：
+
+- `mcp-multi-login` 负责登录，把 token 写入本地文件（旧名 `mes-login-cli`，命令 `mes-login` 仍可用）
+- `mcp-multi-bridge` 负责读取 token 并转发请求
+
+> **从 `mes-mcp-bridge` 升级是破坏性的，按下面三步走**
+>
+> 1. 卸载旧包、装新包：
+>
+>    ```bash
+>    npm rm -g mes-mcp-bridge
+>    npm i -g mcp-multi-bridge
+>    ```
+>
+> 2. **改 `mcp.json` 里的 command**（这一步不能省——本包只提供 `mcp-multi-bridge`
+>    一个命令名，旧的 `mes-mcp-bridge` 不再存在）：
+>
+>    ```diff
+>    - "command": "mes-mcp-bridge"
+>    + "command": "mcp-multi-bridge"
+>    ```
+>
+> 3. 重启 MCP 客户端。
+>
+> 配置目录与 `config.json` 结构不变，无需重新登录。
+
+## 多后端与工具列表
+
+`config.json` 里的每个组织都带一个 `path`，指向它在 Higress 上的 MCP 路由。
+**多个组织可能共享同一个 path**（比如测试环境的太仓和具身智能），
+它们只是登录身份不同，后台是同一个 MCP Server。
+
+bridge 拉取工具列表的规则：
+
+1. 按 `path` 去重，同一 path 只查一次（不是按组织逐个查）
+2. 多个 path 并行查询
+3. 按**工具名**合并：同名工具只出现一次，`orgKey` 的可选值是提供该工具的所有组织
+4. 单个 path 失败不阻断整体，能拿到多少给多少，失败的写进 `login` 工具的告警里
+
+### `orgKey` 只能选同后端的组织
+
+这是为了避免一种必然失败的情况：工具来自 A 后端，`orgKey` 却指向 B 后端的组织，
+请求发过去那边不认识这个工具。bridge 会在调用前校验，跨后端直接拒绝并列出可用选项。
+
+### 工具数量上限
+
+默认上限 40 个。超过后会在 `login` 工具的描述里告警——工具过多会挤占模型上下文，
+也会降低工具选择的准确率。真到这一步，说明该拆 server 了。
+
+### 拆成多个客户端条目
+
+不想把所有后端压在一个 bridge 里，可以用环境变量限定本实例负责的 path：
+
+```json
+{
+  "mcpServers": {
+    "mes-test": {
+      "command": "mcp-multi-bridge",
+      "args": [],
+      "env": { "MES_MCP_PATHS": "mes-mcp-server" }
+    },
+    "mes-prod": {
+      "command": "mcp-multi-bridge",
+      "args": [],
+      "env": { "MES_MCP_PATHS": "tc-mes-mcp-server" }
+    }
+  }
+}
+```
+
+`MES_MCP_PATHS` 用逗号分隔，可以写完整 path（`/mcp-servers/xxx`），
+也可以只写末段（`xxx`），两种都识别。
+
+这样客户端列表里会出现两个独立条目，各自的工具集和 `orgKey` 范围互不干扰。
+
+## 检查安装的版本
+
+```bash
+mcp-multi-bridge --version     # 只输出版本号，如 1.4.0
+mcp-multi-bridge --status      # 版本 + 安装位置 + 网关地址 + 后端分组 + 各组织登录状态
+mcp-multi-bridge --help        # 帮助
+```
+
+`--version` 只输出纯版本号，方便脚本取值：
+
+```bash
+mcp-multi-bridge --version | xargs echo "当前版本:"
+```
+
+如果怀疑跑的不是自己想跑的那份（比如同时存在 `npm link` 的软链和全局安装），
+用 `--status` 看「安装位置」即可确认。
+
+`mes-login` 同样支持 `--version`。
+
+## 配置 MCP 客户端
+
+任选其一。
+
+### 方式一：npx（免安装）
+
+```json
+{
+  "mcpServers": {
+    "mes": {
+      "command": "npx",
+      "args": ["-y", "mcp-multi-bridge"]
+    }
+  }
+}
+```
+
+### 方式二：全局安装（推荐）
+
+```bash
+npm i -g mcp-multi-bridge
+```
+
+```json
+{
+  "mcpServers": {
+    "mes": {
+      "command": "mcp-multi-bridge",
+      "args": []
+    }
+  }
+}
+```
+
+全局安装的好处是升级可控：`npx` 只跳过安装确认，**不会因为发布了新版本就刷新本地缓存**。
+
+### 方式三：绝对路径（最稳）
+
+如果客户端启动子进程时找不到命令（`ENOENT`），直接用 node 加绝对路径：
+
+```json
+{
+  "mcpServers": {
+    "mes": {
+      "command": "node",
+      "args": ["C:/Users/你的用户名/AppData/Roaming/npm/node_modules/mcp-multi-bridge/bin.js"]
+    }
+  }
+}
+```
+
+实际路径用这条命令查：
+
+```bash
+npm root -g
+```
+
+## 使用流程
+
+1. 首次使用，或 token 过期时，执行登录：
+
+   ```bash
+   mes-login
+   ```
+
+2. 在打开的登录页里完成账号密码和图形验证码
+
+3. 回到 MCP 客户端，直接调用工具即可
+
+**登录后无需重启客户端。** bridge 每次调用都重新读取 token 文件，所以登录结果立即生效。
+
+## 未登录时的表现
+
+工具调用会返回明确的引导文案，说明该执行 `mes-login` 以及要等人工完成验证码。模型拿到这段文字后可以自行发起登录。
+
+## 多组织
+
+登录页支持切换组织，每个组织单独保存 token，互不覆盖。
+
+调用工具时可以指定组织：
+
+```json
+{ "orgKey": "tc" }
+```
+
+`orgKey` 的取值就是 `config.json` 里各组织的 `key`，不传则用最后一次登录的组织。
+
+## 自定义系统差异
+
+合并、路由、凭据注入这套逻辑与具体业务系统无关，真正随系统变化的是六件事。
+全部在 `config.json` 里配置，**都不写则沿用 MES 的默认值，升级后行为不变**。
+
+```json
+{
+  "systemName": "ERP 中台",
+  "tenantLabel": "租户",
+  "credentialField": "authToken",
+  "tenantIdField": "tenantId",
+  "hiddenArgs": ["authToken", "tenantId"],
+  "invalidCodes": [401, 403],
+  "invalidCodeReasons": { "401": "未授权，请重新登录" },
+  "loginCommand": "erp-login"
+}
+```
+
+| 字段 | 默认值 | 作用 |
+|---|---|---|
+| `systemName` | `MES` | 系统名，出现在登录引导与状态标题里 |
+| `tenantLabel` | `组织` | 租户称谓，出现在 `orgKey` 参数说明、状态清单与各类提示里 |
+| `credentialField` | `access_token` | 注入到工具参数里的凭据字段名，**必须与网关 requestTemplate 取值的字段一致** |
+| `tenantIdField` | `orgId` | 注入租户 ID 时用的参数名，取值来自配置的 `orgs[].orgId` |
+| `hiddenArgs` | 跟随上面两个字段 | 对模型隐藏的参数。凭据与租户 ID 由本层填，露给模型只会引发「我该填什么」 |
+| `invalidCodes` | `[613,614,615,616]` | 视为「登录失效」的业务错误码，命中后返回重新登录引导 |
+| `invalidCodeReasons` | MES 的四个码 | 错误码说明，与默认值**合并**，只写要覆盖的项 |
+| `loginCommand` | `mes-login` | 登录引导里让模型执行的命令名 |
+
+> **租户 ID 由本层注入，不让模型填。** 网关的工具模板通常是
+> `{{if .args.orgId}}{{.args.orgId}}{{else}}1{{end}}` —— 不传就一律按 1 查，
+> 同一个后端下的其他租户会静默查到错误组织的数据。所以本层总是把
+> `orgs[].orgId` 注入进去，客户端传的同名字段会被覆盖。
+
+### 显示效果对比
+
+| | 默认 | 上面那份配置 |
+|---|---|---|
+| 工具描述 | 查询 MES 的组织与登录状态 | 查询 ERP 中台的租户与登录状态 |
+| 参数说明 | 要操作的组织标识 | 要操作的租户标识 |
+| 状态标题 | ## MES 组织状态 | ## ERP 中台租户状态 |
+| 更新提示 | 该组织尚未登录 | 该租户尚未登录 |
+| 引导命令 | `mes-login --org tc` | `erp-login --org tc` |
+
+`orgKey` 这个参数名不会变——它是路由用的标识，改文案不影响调用方代码。
+
+### 容错
+
+所有字段都做了类型校验，配错（`null`、空串、非数组、非数字）时**静默回落默认值**，
+不会让服务起不来。`systemName` 以汉字结尾时不加空格（「查询 ERP 中台的租户」），
+以拉丁字母结尾时加（「查询 MES 的组织」）。
+
+## 配置目录与多系统并存
+
+**默认目录 `~/.mes-mcp-login`**，不设环境变量就用它。现有用户升级后行为不变。
+
+目录名带 `mes` 是历史沿革：`mcp-multi-login` 的默认值也是它，两边必须一致，
+否则登录完桥接层找不到 token。要改名得两个包一起改。
+
+**同一个客户端接多套系统**时，每个 bridge 实例指向不同目录：
+
+```json
+{
+  "mcpServers": {
+    "mes": {
+      "command": "mcp-multi-bridge",
+      "args": [],
+      "env": { "MCP_MULTI_HOME": "C:/Users/你/.mes-mcp-login" }
+    },
+    "erp": {
+      "command": "mcp-multi-bridge",
+      "args": [],
+      "env": { "MCP_MULTI_HOME": "C:/Users/你/.erp-login" }
+    }
+  }
+}
+```
+
+工具名由客户端加前缀区分（`mcp__mes__captchaGet` / `mcp__erp__captchaGet`），同名工具不冲突。
+
+| 环境变量 | 作用 | 默认 |
+|---|---|---|
+| `MCP_MULTI_HOME` | 配置目录 | `~/.mes-mcp-login` |
+| `MCP_BRIDGE_HOME` | 同上（旧名，仍兼容） | — |
+| `MCP_BRIDGE_PATHS` | 限定本实例负责的 path，逗号分隔 | 不限制（全部加载） |
+
+> `MCP_MULTI_HOME` 优先于 `MCP_BRIDGE_HOME`；`MCP_BRIDGE_PATHS` 优先于旧名 `MES_MCP_PATHS`。
+
+### 登录引导会带上 `--home`
+
+未登录或登录失效时，本服务返回的引导命令是**完整可执行**的：
+
+```bash
+mcp-multi-login --home "C:/Users/你/.mes-mcp-login" --org tc
+```
+
+`--home` 指向本实例实际读取的目录，不能省——省了就会写到默认目录去，
+表现是「登录成功了但这边还是未登录」，非常难查。
+
+若登录命令不是默认的 `mcp-multi-login`（例如仍在用旧的 `mes-login`），
+用 `loginCommand` 配置改：
+
+```json
+{ "loginCommand": "mes-login" }
+```
+
+## 文件依赖
+
+读取配置目录下的两个文件：
+
+| 文件 | 由谁创建 |
+|---|---|
+| `config.json` | 登录侧 CLI（`mcp-multi-login` / 旧 `mes-login-cli`），也可手写 |
+| `token.json` | 登录侧 CLI（登录时写入） |
+
+本包**只读不写**，不会创建、修改或删除这两个文件。
+
+所以使用前必须先安装并运行一次登录 CLI（`mcp-multi-login`）。
+
+## 提供的工具
+
+工具列表由网关返回，本包原样透传。`login` 会被本包替换成本地状态查询工具。
+
+工具本身（有哪些、叫什么、什么参数）完全取决于网关侧配置，本包不做增删。
+当前 MES 网关提供的是：
+
+- `login` 登录态查询（本包接管）
+- `captchaGet` 获取验证码
+- `captchaCheck` 校验验证码
+- `searchRidReport` RID 明细报表
+
+## 平台支持
+
+Windows / macOS / Linux。需要 Node.js >= 18。
+
+## License
+
+MIT