diff --git a/app/config.example.yml b/app/config.example.yml index 75d9656..87d5998 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -131,6 +131,9 @@ model_hold: # enable 选填、默认 true;设为 false 时启动不加载该服务的工具(配置保留,改回 true 重启即恢复)。 # timeout_ms 选填、默认 60000:该服务单次工具调用的最大等待(毫秒,有 1s~10min 夹限), # 像视频生成这类上游就是慢的服务可以调大;握手/工具发现阶段用固定的 15s,不受本项影响。 +# tools_allow / tools_deny 选填:工具名单(字符串数组,按服务端的原始工具名在发现阶段过滤)。 +# allow 是白名单(配了就只保留名单内的),deny 在其后叠加生效(deny 优先);空名单视作未配。 +# 用于控制发给模型的工具数:单服务动辄二三十个工具(如浏览器类),只放行主循环用得上的。 # 服务不可用时只在启动日志告警,不影响其他服务与内置工具。 # # 无域名部署:agent-core 与 mcp 仓库的容器共用 agent-mcp-net,这里直接写【容器名:容器内端口】, @@ -150,3 +153,21 @@ mcp_servers: # url: "http://mcp_video_gen:3000/mcp" # headers: # Authorization: "Bearer <你的智谱 API Key>" + # 浏览器(Playwright MCP,需自行起 agent-browser 容器):工具多、单次操作比普通 MCP 慢, + # 典型用法就是白名单只放行要用的那几个 + 调大 timeout。 + # - name: browser + # url: "http://agent-browser:8931/mcp" + # enable: true + # timeout_ms: 120000 + # tools_allow: + # - browser_navigate + # - browser_snapshot + # - browser_click + # - browser_fill_form + # - browser_type + # - browser_press_key + # - browser_select_option + # - browser_wait_for + # - browser_tabs + # - browser_handle_dialog + # - browser_take_screenshot diff --git a/app/server/config.js b/app/server/config.js index 1cb5b9d..6344782 100644 --- a/app/server/config.js +++ b/app/server/config.js @@ -7,6 +7,14 @@ const log = require('./log'); // MCP 单次工具调用(tools/call)的缺省最大等待,与 mcp.js 的 CALL_TIMEOUT_MS 保持一致。 const MCP_CALL_TIMEOUT_MS = 60000; +// MCP 工具名单(tools_allow/tools_deny)归一化:只接受数组,项统一转字符串去空白、丢空项; +// 空数组/非数组视作未配置(返回 undefined),避免「allow: [] 是不是全禁」这种歧义。 +function normToolNames(v) { + if (!Array.isArray(v)) return undefined; + const out = v.map(x => String(x).trim()).filter(Boolean); + return out.length ? out : undefined; +} + const DEFAULTS = { port: 8090, // 数据根目录:db、prompt dump 等运行时产物默认放这里(容器内挂 ./data → /workspace/data)。 @@ -246,6 +254,9 @@ function parseAndValidate(rawText, configPath) { // 单次工具调用的超时上限:缺省 60s,夹在 [1s, 10min](一次调用长期占着模型槽位,不允许无限等)。 // YAML 里写成字符串或写了非法值都回落到缺省。 s.timeout_ms = Math.min(Math.max(Number(s.timeout_ms) || MCP_CALL_TIMEOUT_MS, 1000), 600000); + // 工具名单(发现阶段生效,见 mcp.init):allow 为白名单,deny 在其后叠加生效(deny 优先)。 + s.tools_allow = normToolNames(s.tools_allow); + s.tools_deny = normToolNames(s.tools_deny); } normalizePublicLink(cfg); diff --git a/app/server/mcp.js b/app/server/mcp.js index 411f8d3..7271d02 100644 --- a/app/server/mcp.js +++ b/app/server/mcp.js @@ -1,6 +1,7 @@ // 极简 MCP 客户端(Streamable HTTP:JSON-RPC over HTTP,无状态,响应可能是 SSE 帧包裹的 JSON)。 -// MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?, enable?, timeout_ms?}。 -// 启动时 init() 对每个服务调 tools/list 发现工具(enable: false 的服务跳过加载),转成 OpenAI function 格式, +// MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?, enable?, timeout_ms?, tools_allow?, tools_deny?}。 +// 启动时 init() 对每个服务调 tools/list 发现工具(enable: false 的服务跳过加载;配了 tools_allow/tools_deny +// 时按名单过滤),转成 OpenAI function 格式, // 追加在内置工具(definitions.json)之后一起随 system prompt 发给模型; // 工具调用经 tools/call 转发给对应服务。 // 与内置工具严格分离:本模块不碰内置定义;MCP 工具默认沿用原始名, @@ -133,7 +134,13 @@ async function init(cfg) { if (!/Method not found/i.test(String(e && e.message || e))) throw e; } const result = await rpc(s, 'tools/list', {}, 15000); - const tools = (result && result.tools) || []; + const all = (result && result.tools) || []; + // 工具名单过滤(发生在重命名之前,按服务端的【原始工具名】匹配): + // allow 是白名单(配了就只保留名单内),deny 在其后叠加生效(deny 优先)。 + // 动机:单服务动辄二三十个工具全塞进每次模型请求(如浏览器类),只放行主循环用得上的。 + let tools = all; + if (Array.isArray(s.tools_allow)) tools = tools.filter(t => s.tools_allow.includes(t && t.name)); + if (Array.isArray(s.tools_deny)) tools = tools.filter(t => !s.tools_deny.includes(t && t.name)); for (const t of tools) { if (!t || !t.name) continue; let name = t.name; @@ -148,7 +155,15 @@ async function init(cfg) { }, }); } - log.info('mcp', s.name + ': 发现 ' + tools.length + ' 个工具' + (s.sessionId ? ' (session)' : '')); + let msg = s.name + ': 发现 ' + tools.length + ' 个工具' + (s.sessionId ? ' (session)' : ''); + if (tools.length !== all.length) msg += '(服务端共 ' + all.length + ' 个,已按 tools_allow/tools_deny 过滤)'; + log.info('mcp', msg); + // 配了名单却一个都没过滤中,十有八九是名单里的名字跟 tools/list 返回不一致; + // 不 warn 的话排查时只能对着「发现 0 个工具」干瞪眼。 + if (all.length && !tools.length && (s.tools_allow || s.tools_deny)) { + log.warn('mcp', s.name + ': 名单过滤后剩 0 个工具,请核对 tools_allow/tools_deny 与 ' + + '服务端实际工具名(如 ' + all.slice(0, 3).map(t => t.name).join(', ') + ' …)'); + } } catch (err) { log.warn('mcp', s.name + ' 工具发现失败(本轮运行该服务不可用): ' + (err && err.message || err)); } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b77c05b..306434e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -261,6 +261,7 @@ stateDiagram-v2 - 协议:Streamable HTTP(JSON-RPC over HTTP,响应可能 SSE 包裹)。 - 启动 `init(cfg)` 对每个服务 initialize → notifications/initialized → tools/list;单个服务失败只 warn,不影响其他。 +- **工具名单过滤**:服务配 `tools_allow`(白名单)/ `tools_deny`(黑名单,allow 之后叠加生效)时,在 tools/list 后按服务端**原始工具名**过滤(重命名之前);两者都在 `config.js` 归一化(非数组/空数组视作未配)。过滤后剩 0 个会 warn(多半是名字写错)。 - 工具名冲突时重命名:`内置名` 或 `其他MCP名` 已占 → 加 `服务名__` 前缀(`toolIndex` 索引走重命名后的名,调用时按索引还原成原始名调 `tools/call`)。 - session 补偿:MCP 规范的 `Mcp-Session-Id` 缓存在 `server.sessionId`;过期(400 + 含 "session" 字样)自动重 initialize 后重试一次。 - 某些老服务无 `initialize` → catch `Method not found` 不阻断。 @@ -450,6 +451,7 @@ stateDiagram-v2 - `auth.users` —— 明文密码配在配置里(自用场景);`secret` 留空则随机生成(重启掉登录态,建议固定随机串)。 - `mcp_servers[].enable: false` —— 启动不加载该服务(配置保留),其余工具不受影响。 - `mcp_servers[].timeout_ms` —— 该服务单次 `tools/call` 的最大等待,默认 60000(夹在 1s~10min);工具发现/握手用固定 15s,不受本项影响。 +- `mcp_servers[].tools_allow` / `tools_deny` —— 发现阶段的工具名单(字符串数组,按服务端原始名):allow 白名单,deny 在其后叠加(deny 优先);用于压低发给模型的工具数(如浏览器类服务)。 - `executor.url` / `executor.token` —— 留空走环境变量 `EXECUTOR_URL` / `EXECUTOR_TOKEN`(compose 默认注入)。 --- @@ -566,7 +568,7 @@ sequenceDiagram ### 11.3 加一个 MCP 服务 -直接改 `config.yml` 的 `mcp_servers` 数组加一项 `{name, url, headers, enable?, timeout_ms?}`。重启生效。`enable: false` 的服务不加载工具(配置保留),单服务失败只 warn 不影响其他。`timeout_ms`(默认 60000,夹在 1s~10min)是该服务单次 `tools/call` 的最大等待。 +直接改 `config.yml` 的 `mcp_servers` 数组加一项 `{name, url, headers, enable?, timeout_ms?, tools_allow?, tools_deny?}`。重启生效。`enable: false` 的服务不加载工具(配置保留),单服务失败只 warn 不影响其他。`timeout_ms`(默认 60000,夹在 1s~10min)是该服务单次 `tools/call` 的最大等待。`tools_allow`/`tools_deny` 可按原始工具名只放行要用的那几个(见 §5.3)。 ### 11.4 加一个模型 / 平台