mcp-multi-bridge 2.1.4 → 2.3.0

package/bin.js

@@ -32,7 +32,7 @@
  *   - 只读 token.json / config.json，永不写入或删除
  *   - 不监听任何端口，不弹浏览器
  *   - 凭据每次调用重新读文件（所以登录后立即生效，无需重启）
- *   - 工具列表短暂缓存（TOOLS_TTL_MS），避免一次会话内反复打网关
+ *   - 工具列表按 TTL 缓存（默认 5 分钟），避免一次会话内反复打网关
  */
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -40,10 +40,21 @@ import { createRequire } from 'node:module';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { loadConfig, findOrg, defaultOrg, allowedPaths, CONFIG_FILE, CONFIG_DIR } from './lib/config.js';
+import {
+    loadConfig,
+    findOrg,
+    defaultOrg,
+    allowedPaths,
+    CONFIG_FILE,
+    CONFIG_DIR,
+    CONFIG_DIR_ERROR,
+    CONFIG_NAME,
+    NAME_DIR_SUFFIX
+} from './lib/config.js';
 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';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -52,11 +63,59 @@ const PKG = require('./package.json');
 // 由 bridge 自己提供、不从 Higress 透传的工具
 const LOCAL_TOOL = 'login';
 
+// 分层模式下由 bridge 提供、用来按需发现和调用工具的三个元工具。
+// 名字用下划线前缀风格，和业务工具区分开，避免撞名。
+const META_SEARCH = 'search_tools';
+const META_DESCRIBE = 'describe_tool';
+const META_CALL = 'call_tool';
+const META_TOOLS = new Set([META_SEARCH, META_DESCRIBE, META_CALL]);
+
 // 工具数量上限：超过则告警，建议拆分 server 或缩小合并范围
 const MAX_TOOLS = 40;
 
-// 工具列表缓存时长：客户端本来只在启动时拉一次，这里仅避免同一会话内重复打网关
-const TOOLS_TTL_MS = 5000;
+/**
+ * 工具暴露模式
+ *
+ * flat    全量塞给模型。工具少时最优：少一次往返，模型能看见全部选项
+ * layered 只给常驻集 + 三个元工具，其余按需检索
+ * auto    工具数超过阈值自动切 layered（默认）
+ *
+ * 为什么默认 auto 而不是永远 layered：当前 MES 只有 4 个工具，
+ * 加三个元工具反而多一层间接，模型要先 search 才能调，纯属负担。
+ */
+function toolMode() {
+    const m = String(process.env.MCP_BRIDGE_TOOL_MODE || 'auto').toLowerCase();
+    return ['flat', 'layered', 'auto'].includes(m) ? m : 'auto';
+}
+
+/** 常驻工具数量：layered 模式下直接暴露给模型的工具个数 */
+function residentCount() {
+    const n = Number(process.env.MCP_BRIDGE_RESIDENT_COUNT || 20);
+    return Number.isFinite(n) && n > 0 ? Math.min(200, Math.floor(n)) : 20;
+}
+
+/** 手动指定的常驻工具名单，优先级高于按名字排序 */
+function residentList() {
+    const raw = String(process.env.MCP_BRIDGE_RESIDENT || '').trim();
+    if (!raw) return [];
+    return raw.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * 工具列表缓存时长
+ *
+ * 定这个值的依据是「重拉一次有多贵」：聚合几十上百个后端时，
+ * 全量拉取要十几秒（实测 200 个后端在 30ms 延迟下约 20 秒）。
+ * 缓存期比拉取时间还短就毫无意义，客户端每次刷新都要重来。
+ *
+ * 工具清单只在网关侧改配置时变，不需要秒级感知；
+ * 真需要立刻用上新工具时，tools/call 查不到会强制刷新一次。
+ * 所以默认给 5 分钟，可用 MCP_BRIDGE_TOOLS_TTL_MS 调整。
+ */
+function toolsTtl() {
+    const n = Number(process.env.MCP_BRIDGE_TOOLS_TTL_MS || 300000);
+    return Number.isFinite(n) && n >= 0 ? n : 300000;
+}
 
 /**
  * 按 path 归组组织
@@ -143,11 +202,46 @@ async function handleCli(argv) {
     MCP_BRIDGE_PATHS=/mcp-servers/tc-mes-mcp-server
   然后在 mcp.json 里配多个带不同 env 的条目。
 
-配置文件: ${CONFIG_FILE}
-登录文件: ${CONFIG_DIR}/token.json（由 ${L.loginCommand} 写入）
+工具暴露模式（工具多时必看）:
+  工具定义会常驻模型上下文。按中等复杂度工具约 350 tokens 估算，
+  1000 个工具就是 35 万 tokens，超过多数模型的整个窗口。
+  这时应改为按需检索：
+
+    MCP_BRIDGE_TOOL_MODE=auto      默认。工具数超过 ${MAX_TOOLS} 自动分层
+    MCP_BRIDGE_TOOL_MODE=layered   强制分层：常驻集 + search/describe/call 三个元工具
+    MCP_BRIDGE_TOOL_MODE=flat      强制全量，工具少时最优（少一次往返）
+
+    MCP_BRIDGE_RESIDENT_COUNT=20   分层时常驻几个工具
+    MCP_BRIDGE_RESIDENT=queryXxx,queryYyy
+                                   手动指定常驻名单。频次只有日志知道，
+                                   建议按真实调用统计后把名单固化下来。
+
+  同名工具的处理：参数结构相同的视为同一套后端的不同部署环境，会合并；
+  结构不同的视为不同系统的冲突，自动加 <系统>__ 前缀区分。
+
+聚合很多后端时（几十上百套 MCP）:
+    MCP_BRIDGE_TOOLS_TTL_MS=300000
+                                   工具清单缓存时长，默认 5 分钟。
+                                   全量拉取很贵：200 个后端 30ms 延迟下约 20 秒，
+                                   所以缓存期要远大于拉取耗时。
+                                   新增工具靠 tools/call 的强制刷新兜底，
+                                   不需要把 TTL 调很小。
+
+    MCP_BRIDGE_FETCH_CONCURRENCY=16
+                                   拉清单时的并发上限，默认 16。
+                                   不设上限会在同一瞬间建立上百个连接，
+                                   网关和本地 socket 都吃不住。
+
+配置目录（二选一，必须指定）:
+  MCP_MULTI_HOME=<绝对路径>      旧名 MCP_BRIDGE_HOME 仍兼容
+  --name <系统名>                目录为 ~/.<系统名>${NAME_DIR_SUFFIX}
 
-配置目录可用环境变量 MCP_MULTI_HOME 改到别处（旧名 MCP_BRIDGE_HOME 仍兼容）。
-放在客户端配置的 env 里，可以一个客户端同时接多套系统。默认 ~/.mes-mcp-login。
+  以前没配时会静默用 ~/.mes-mcp-login，导致新系统忘配就读到 MES 的数据。
+  现在没配直接报错，不再猜。
+
+当前配置目录: ${CONFIG_DIR || '（未配置）'}
+配置文件: ${CONFIG_FILE || '（未配置）'}
+登录文件: ${CONFIG_DIR ? CONFIG_DIR + '/token.json' : '（未配置）'}（由 ${L.loginCommand} 写入）
 
 本程序只读上述文件，不会修改或删除。`);
         return true;
@@ -171,7 +265,9 @@ async function handleCli(argv) {
         console.log(`${PKG.name} ${PKG.version}`);
         console.log(`安装位置: ${__dirname}`);
         console.log(`网关地址: ${cfg.baseUrl}`);
-        console.log(`工具上限: ${MAX_TOOLS}`);
+        const mode = toolMode();
+        const modeLabel = mode === 'auto' ? `auto（超过 ${MAX_TOOLS} 个自动分层）` : mode;
+        console.log(`工具暴露: ${modeLabel}`);
         if (allow) console.log(`限定 path: ${allow.join(', ')}`);
         console.log();
 
@@ -209,6 +305,14 @@ if (await handleCli(process.argv.slice(2))) {
     process.exit(0);
 }
 
+// 走到这里说明要进入 stdio 服务模式。没有配置目录就没法干活，
+// 直接退出并说明原因——绝不像以前那样悄悄回落到某个既有目录，
+// 那会让这个实例读到别的系统的配置与 token。
+if (!CONFIG_DIR) {
+    console.error(`[bridge] ${CONFIG_DIR_ERROR}`);
+    process.exit(1);
+}
+
 function textResult(text, isError = false) {
     return {
         content: [{ type: 'text', text }],
@@ -463,65 +567,258 @@ function localLoginTool(cfg, orgKeys, warning) {
     };
 }
 
+/**
+ * 挑选常驻工具（layered 模式下直接暴露给模型的那批）
+ *
+ * 排序依据：组织覆盖数降序，再按名字。
+ * 被多套部署环境共用的工具（通用查询这类）更可能是每次对话都要用的，
+ * 放进常驻集能省掉最常见的几次往回搜索。
+ *
+ * 环境变量 MCP_BRIDGE_RESIDENT 可手动指定名单，优先级最高——
+ * 真实调用频次只有日志能统计出来，bridge 自己不知道，
+ * 所以最终应该由运维按日志数据把名单固化下来。
+ */
+function pickResident(items, limit) {
+    const picked = [];
+    const seen = new Set();
+
+    for (const n of residentList()) {
+        const it = items.get(n) || [...items.values()].find((x) => x.originalName === n);
+        if (it && !seen.has(it.name)) {
+            picked.push(it.name);
+            seen.add(it.name);
+        }
+    }
+
+    if (picked.length >= limit) return picked.slice(0, limit);
+
+    const rest = [...items.values()]
+        .filter((it) => !seen.has(it.name))
+        .sort((a, b) => {
+            const pa = a.orgKeys.length * 1000 + a.paths.length * 100;
+            const pb = b.orgKeys.length * 1000 + b.paths.length * 100;
+            return pb - pa || a.name.localeCompare(b.name);
+        });
+
+    for (const it of rest) {
+        if (picked.length >= limit) break;
+        picked.push(it.name);
+    }
+    return picked;
+}
+
+/**
+ * 三个元工具：把「发现工具」这件事本身变成工具
+ *
+ * 为什么不把完整工具清单塞进 search_tools 的 description：
+ * 那样每轮都要为整份目录付 token，而模型多数时候只查一两个工具。
+ * 目录只以「系统 + 数量 + 少量样例」的缩略形式给出，够它判断该搜哪套系统。
+ */
+function metaTools(items, bySystem, tenantLabel) {
+    const dir = summarize(bySystem, items, 4)
+        .map((r) => `  - ${r.text}`)
+        .join('\n');
+
+    return [
+        {
+            name: META_SEARCH,
+            description: `按关键词检索可用的工具。当前共 ${items.size} 个工具，分属下列系统：\n${dir}\n\n参数 query 支持中英文，例如「料号」「批次」「创建订单」。返回命中的工具名与简短说明，然后用 ${META_CALL} 调用。`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: '检索词。中英文都可以，描述你要做的事或涉及的业务对象' },
+                    system: { type: 'string', description: '可选，只在某套系统内搜索。留空则搜全部' },
+                    limit: { type: 'number', description: '返回条数，默认 5，最多 20' }
+                },
+                required: ['query']
+            }
+        },
+        {
+            name: META_DESCRIBE,
+            description: `查看某个工具的完整参数定义。先用 ${META_SEARCH} 找到工具名，不确定参数格式时再调用这里。`,
+            inputSchema: {
+                type: 'object',
+                properties: { name: { type: 'string', description: '工具名，来自检索结果' } },
+                required: ['name']
+            }
+        },
+        {
+            name: META_CALL,
+            description: `调用一个工具。工具名可以是检索结果里的任意工具。凭据与${tenantLabel}信息由本服务注入，不需要自己传。`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: '要调用的工具名' },
+                    arguments: { type: 'object', description: '传给该工具的参数对象' }
+                },
+                required: ['name']
+            }
+        }
+    ];
+}
+
+/**
+ * 生成系统标签
+ *
+ * 聚合几十套同构系统时（比如 50 个 MES 部署环境共用一套 API），
+ * 把系统名全列出来会占掉整条检索结果 15% 的体积，而且对模型没有信息量——
+ * 它只需要知道「这个工具能用」，具体用哪套由 orgKey 决定。
+ * 所以超过 3 个就折叠成数量。
+ */
+function systemLabel(it) {
+    const list = it.systemList && it.systemList.length ? it.systemList : [it.system];
+    if (list.length <= 1) return `[${list[0]}]`;
+    if (list.length <= 3) return `[${list.join('/')}]`;
+    return `[${list[0]} 等 ${list.length} 套系统]`;
+}
+
+/**
+ * 生成 search 返回给模型的文本
+ *
+ * 只给名称 + 一句话 + 前几个参数名，不给完整 JSON Schema：
+ * 一个工具的完整 schema 就几百 token，一次返回 5 个等于回到全量暴露。
+ * 需要细节时让模型再走 describe。
+ */
+function formatFound(list) {
+    if (!list.length) {
+        // 搜不到说明工具自带的名称与描述里没有这些词。提示去补描述而不是加映射表：
+        // 桥接层不维护业务词对照，缺中文就该在网关侧把描述写全。
+        return (
+            '没有匹配的工具。\n' +
+            '可以换用工具名里的英文词（search / query / report / create）再试；\n' +
+            '若仍然搜不到，说明该工具的描述里没有这些说法，需要在网关侧补上中文描述。'
+        );
+    }
+    return list
+        .map((it) => {
+            const props = Object.keys(it.tool?.inputSchema?.properties || {});
+            const shown = props.slice(0, 6).join(', ');
+            const more = props.length > 6 ? ` …共 ${props.length} 个参数` : '';
+            const desc = String(it.tool?.description || '').split('\n')[0].slice(0, 90);
+            return `- ${it.name} ${systemLabel(it)}\n  ${desc}\n  参数：${shown || '无'}${more}`;
+        })
+        .join('\n');
+}
+
+/**
+ * 限并发执行
+ *
+ * 一个实例可能聚合几十上百个后端。无限制地打出去会同时建立上百个连接，
+ * 网关侧和本地的 socket 都吃不住，而且失败时是一起失败。
+ * 实测 200 个后端并发拉取时峰值 200 个连接，网关压力不可控。
+ *
+ * @param {T[]} list
+ * @param {number} limit
+ * @param {(item:T)=>Promise<R>} fn
+ * @returns {Promise<PromiseSettledResult<R>[]>} 与 Promise.allSettled 结构一致
+ */
+async function mapSettled(list, limit, fn) {
+    const out = new Array(list.length);
+    let cursor = 0;
+    const worker = async () => {
+        while (true) {
+            const i = cursor++;
+            if (i >= list.length) return;
+            try {
+                out[i] = { status: 'fulfilled', value: await fn(list[i]) };
+            } catch (e) {
+                out[i] = { status: 'rejected', reason: e };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, list.length) }, worker));
+    return out;
+}
+
+/**
+ * 拉工具清单的并发上限
+ *
+ * 不设上限时，200 个后端会在同一瞬间建立 200 个连接——
+ * 网关和本地 socket 都吃不住，且失败会一起失败。
+ *
+ * 默认 16 是折中：实测 200 个后端 30ms 延迟下，
+ * 8 并发约 28 秒、16 并发约 18 秒；再往上收益不明显
+ * （压测环境是单进程 mock，序列化大 JSON 会成为新瓶颈，
+ * 真实网关下最优值可能不同，所以留了环境变量可调）。
+ */
+function fetchConcurrency() {
+    const n = Number(process.env.MCP_BRIDGE_FETCH_CONCURRENCY || 16);
+    return Number.isFinite(n) && n > 0 ? Math.min(64, Math.floor(n)) : 16;
+}
+
 /**
  * 按 path 去重拉取工具清单，并按工具名合并
  *
  * 并行的目的是：后端多时不要串行等 N 次网络往返。
  * 单个后端失败不阻断整体——能拿到多少给多少，失败的记在 errors 里。
  *
- * @returns {{tools:object[], index:Map<string,{orgKeys:string[],paths:string[]}>, errors:string[], warnings:string[]}}
+ * 同名工具的合并规则交给 toolindex.buildIndex：
+ * 参数结构相同视为同一套后端的不同部署环境（合并），
+ * 结构不同则是不同系统的真冲突（加系统前缀拆开）。
+ *
+ * @returns {{tools:object[], index:Map<string,{orgKeys:string[],paths:string[],system:string}>,
+ *            items:Map, bySystem:Map, conflicts:string[], errors:string[], warnings:string[]}}
  */
 async function collectTools(cfg) {
     const allow = allowedPaths();
     const groups = groupByPath(cfg).filter((g) => pathAllowed(g.path, allow));
 
-    const settled = await Promise.allSettled(
-        groups.map(async (g) => {
-            const r = await rpc(cfg, g.rep, 'tools/list', {});
-            return { group: g, tools: (r.result || r).tools || [] };
-        })
-    );
+    const conc = fetchConcurrency();
+    const settled = await mapSettled(groups, conc, async (g) => {
+        const r = await rpc(cfg, g.rep, 'tools/list', {});
+        return { group: g, tools: (r.result || r).tools || [] };
+    });
 
     const errors = [];
     const warnings = [];
-    const merged = new Map(); // name -> { tool, orgKeys:Set, paths:Set }
 
+    // 拉成功的后端，交给 buildIndex 统一处理命名冲突
+    const byPath = [];
+    const orgKeysByPath = new Map();
     settled.forEach((s, i) => {
         const g = groups[i];
         if (s.status === 'rejected') {
             errors.push(`${g.path}: ${s.reason?.message || s.reason}`);
             return;
         }
-        for (const t of s.value.tools) {
-            if (t.name === LOCAL_TOOL) continue; // 用本地状态工具替换远端登录
-            let e = merged.get(t.name);
-            if (!e) {
-                e = { tool: t, orgKeys: new Set(), paths: new Set() };
-                merged.set(t.name, e);
-            }
-            for (const o of g.orgs) e.orgKeys.add(o.key);
-            e.paths.add(g.path);
-        }
+        const usable = s.value.tools.filter((t) => t && t.name !== LOCAL_TOOL);
+        byPath.push({ path: g.path, tools: usable });
+        orgKeysByPath.set(g.path, g.orgs.map((o) => o.key));
     });
 
-    // 同名工具出现在多个后端时提示一次——语义可能不同，但通常是一致的
-    for (const [name, e] of merged) {
-        if (e.paths.size > 1) {
-            warnings.push(
-                `工具 ${name} 同时存在于 ${e.paths.size} 个后端，已合并（orgKey 为各后端${settings(cfg).tenantLabel}的并集）`
-            );
-        }
+    const built = buildIndex(byPath, orgKeysByPath, { defaultSystem: CONFIG_NAME });
+
+    if (built.conflicts.length) {
+        warnings.push(
+            `${built.conflicts.length} 个工具名在多套系统里定义不同，已加系统前缀区分：` +
+                built.conflicts.slice(0, 8).join('、') +
+                (built.conflicts.length > 8 ? ' 等' : '')
+        );
     }
 
     const tools = [];
     const index = new Map();
-    for (const [name, e] of merged) {
-        const orgKeys = [...e.orgKeys];
-        tools.push(augmentTool(e.tool, orgKeys, cfg));
-        index.set(name, { orgKeys, paths: [...e.paths] });
+    for (const item of built.items.values()) {
+        tools.push(augmentTool(item.tool, item.orgKeys, cfg));
+        index.set(item.name, {
+            orgKeys: item.orgKeys,
+            paths: item.paths,
+            system: item.system,
+            originalName: item.originalName,
+            prefixed: item.prefixed
+        });
     }
 
-    return { tools, index, errors, warnings, groupCount: groups.length };
+    return {
+        tools,
+        index,
+        items: built.items,
+        bySystem: built.bySystem,
+        conflicts: built.conflicts,
+        errors,
+        warnings,
+        groupCount: groups.length
+    };
 }
 
 async function main() {
@@ -534,7 +831,7 @@ async function main() {
     let cache = { at: 0, index: new Map(), tools: [], errors: [], warnings: [], groupCount: 0 };
 
     async function getTools(force = false) {
-        if (!force && Date.now() - cache.at < TOOLS_TTL_MS && cache.index.size) return cache;
+        if (!force && Date.now() - cache.at < toolsTtl() && cache.index.size) return cache;
         const cfg = loadConfig();
         if (!cfg) {
             cache = { at: Date.now(), index: new Map(), tools: [], errors: ['未找到配置'], warnings: [], groupCount: 0 };
@@ -553,31 +850,131 @@ async function main() {
             return { tools: [localLoginTool(null, [])] };
         }
 
+        const L = settings(cfg);
         const allKeys = cfg.orgs.map((o) => o.key);
-        const r = await getTools(true);
+
+        // 走缓存，不再每次强制重拉。
+        // 聚合几十上百个后端时，一次全量拉取要十几秒——实测 200 个后端
+        // 在 30ms 延迟下约 20 秒。如果客户端每次刷新工具列表都重来一遍，
+        // 界面会一直转圈。工具清单变化本来就不频繁，用 TTL 缓存足够。
+        // 真正需要「立刻看到新工具」的场景由 tools/call 兜底：
+        // 索引里查不到该工具时会强制刷新一次。
+        const r = await getTools(false);
 
         for (const e of r.errors) console.error(`[bridge] 后端拉取失败 ${e}`);
         for (const w of r.warnings) console.error(`[bridge] ${w}`);
 
+        // 模式判定：flat 全量、layered 分层、auto 按数量切换。
+        // 阈值用 MAX_TOOLS：超过它时模型的选择准确率已经明显下滑，
+        // 这时才值得付出「多一次搜索」的代价。
+        const mode = toolMode();
+        const layered = mode === 'layered' || (mode === 'auto' && r.tools.length > MAX_TOOLS);
+
         let warning;
-        if (r.tools.length + 1 > MAX_TOOLS) {
-            warning = `当前合并了 ${r.tools.length + 1} 个工具，超过建议上限 ${MAX_TOOLS}。` +
-                `工具过多会挤占模型上下文并降低选择准确率，建议用 MCP_BRIDGE_PATHS 拆分到多个 server 条目。`;
-            console.error(`[bridge] ${warning}`);
-        } else if (r.errors.length) {
+        if (r.errors.length) {
             warning = `${r.errors.length} 个后端拉取失败，工具列表可能不完整：${r.errors.join('；')}`;
         }
 
-        return { tools: [localLoginTool(cfg, allKeys, warning), ...r.tools] };
+        if (!layered) {
+            if (r.tools.length + 1 > MAX_TOOLS) {
+                const note = `当前合并了 ${r.tools.length + 1} 个工具，超过建议上限 ${MAX_TOOLS}。` +
+                    `工具过多会挤占模型上下文并降低选择准确率。` +
+                    `可用 MCP_BRIDGE_TOOL_MODE=layered 改为按需检索，或调整 MCP_BRIDGE_RESIDENT 指定常驻工具。`;
+                console.error(`[bridge] ${note}`);
+                warning = warning ? `${warning}；${note}` : note;
+            }
+            // 常驻相关配置只对 layered 生效。扁平模式下被静默忽略会让人以为配置没写对，
+            // 所以显式说一句——排查这类「配了没反应」最费时间。
+            const ignored = [];
+            if (process.env.MCP_BRIDGE_RESIDENT_COUNT) ignored.push('MCP_BRIDGE_RESIDENT_COUNT');
+            if (process.env.MCP_BRIDGE_RESIDENT) ignored.push('MCP_BRIDGE_RESIDENT');
+            let ignoredNote;
+            if (ignored.length) {
+                ignoredNote =
+                    `注意：当前是全量暴露（flat），${ignored.join(' 与 ')} 被忽略——` +
+                    `它们只对分层模式生效。要启用请设 MCP_BRIDGE_TOOL_MODE=layered。`;
+                console.error(`[bridge] ${ignoredNote}`);
+            }
+            console.error(`[bridge] 工具 ${r.tools.length} 个，全量暴露（flat）`);
+            warning = [warning, ignoredNote].filter(Boolean).join('；') || undefined;
+            return { tools: [localLoginTool(cfg, allKeys, warning), ...r.tools] };
+        }
+
+        // 分层模式：login + 三个元工具 + 常驻集
+        const limit = residentCount();
+        const residentNames = pickResident(r.items, limit);
+        const resident = residentNames.map((n) => r.items.get(n)).filter(Boolean);
+
+        console.error(
+            `[bridge] 工具 ${r.tools.length} 个，分层暴露（layered）：` +
+                `常驻 ${resident.length} 个 + 元工具 ${META_TOOLS.size} 个，其余按需检索`
+        );
+
+        const metaNote =
+            `工具较多（共 ${r.tools.length} 个），已改为按需检索：` +
+            `先用 ${META_SEARCH} 找到工具，再用 ${META_CALL} 调用。`;
+
+        return {
+            tools: [
+                localLoginTool(cfg, allKeys, warning ? `${warning}；${metaNote}` : metaNote),
+                ...metaTools(r.items, r.bySystem, L.tenantLabel),
+                ...resident.map((it) => augmentTool(it.tool, it.orgKeys, cfg))
+            ]
+        };
     });
 
     // tools/call：按 orgKey 选中组织，注入该组织的 token 后转发
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name, arguments: args = {} } = request.params;
+        let { name, arguments: args = {} } = request.params;
 
         try {
             const cfg = loadConfig();
 
+            // ── 元工具：工具检索与描述 ──
+            // 这两个不碰后端，只查本地索引，所以放在最前面，不需要 token
+            if (name === META_SEARCH) {
+                if (!cfg) return textResult(loginGuide('尚未初始化配置'), true);
+                const r = await getTools(false);
+                const hits = searchTools(r.items, args.query, {
+                    system: args.system || undefined,
+                    limit: Number(args.limit) || 5
+                });
+                return textResult(
+                    `${formatFound(hits)}\n\n—— 共 ${r.items.size} 个工具，用 ${META_DESCRIBE} 看完整参数，用 ${META_CALL} 调用。`
+                );
+            }
+
+            if (name === META_DESCRIBE) {
+                if (!cfg) return textResult(loginGuide('尚未初始化配置'), true);
+                const r = await getTools(false);
+                const it = r.items.get(args.name);
+                if (!it) {
+                    const hint = searchTools(r.items, args.name, { limit: 5 });
+                    return textResult(
+                        `没有名为 \`${args.name}\` 的工具。` +
+                            (hint.length ? `\n\n相近的有：\n${formatFound(hint)}` : `\n\n用 ${META_SEARCH} 检索。`),
+                        true
+                    );
+                }
+                return textResult(
+                    `工具：${it.name}\n` +
+                        `系统：${it.systemList.join(', ')}\n` +
+                        `可用${settings(cfg).tenantLabel}：${it.orgKeys.join(', ') || '（无）'}\n` +
+                        `说明：${it.tool?.description || '（无）'}\n\n` +
+                        `参数定义：\n${JSON.stringify(it.tool?.inputSchema || {}, null, 2)}`
+                );
+            }
+
+            // 元工具转发：把 name/arguments 换成真实工具，后续流程完全复用。
+            // 不另写一套转发逻辑，避免凭据注入、失效判定、组织选择三处各维护一份。
+            if (name === META_CALL) {
+                if (!args || !args.name) {
+                    return textResult(`缺少参数 name。用 ${META_SEARCH} 找到工具名后传入。`, true);
+                }
+                name = String(args.name);
+                args = (args.arguments && typeof args.arguments === 'object') ? args.arguments : {};
+            }
+
             // login 已改造成状态查询，不走网关
             if (name === LOCAL_TOOL) {
                 if (!cfg) return textResult(loginGuide('尚未初始化配置'), true);