mcp: 服务级工具名单 tools_allow/tools_deny(发现阶段按原始名过滤,allow 白名单 + deny 叠加)

This commit is contained in:
2026-09-19 19:26:51 +08:00
parent dec0e3a5dd
commit 8c67ca8981
4 changed files with 54 additions and 5 deletions
+21
View File
@@ -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
+11
View File
@@ -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);
+19 -4
View File
@@ -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));
}
+3 -1
View File
@@ -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 加一个模型 / 平台