feat(mcp): mcp_servers 增加 mode 三态(advertise/silent/disable)

silent 让工具只进 toolIndex、不进 toolDefs:模型看不到,技能与 lab 仍可调用,
用于把能力包在技能后面、省掉每轮 schema。disable 连 tools/list 都不发。
旧字段 enable 直接报错而非静默忽略(未知键会被丢弃,导致以为关掉的服务照常连)。

- config.js: mode 三值校验 + enable 废弃守卫
- mcp.js: disable 跳过加载;silent 注册不下发;启动日志区分
- 设置页: 勾选框改为三选一;advertise 时删键,不把默认值写进文件
- init.sh / 示例配置 / README / AGENTS.md 同步
This commit is contained in:
2026-10-21 08:50:01 +08:00
parent fcc9ebc519
commit 5d5482891f
10 changed files with 77 additions and 29 deletions
+12 -2
View File
@@ -61,7 +61,7 @@ PUBLIC_IP=1.2.3.4 \
- `.env`:`EXECUTOR_TOKEN`、`WXBOT_TOKEN`、`AGENT_PORT` 等部署变量。
- `config.yml`:模型平台、登录账号、MCP 服务、公网前缀。
`image_task` / `video_task` 两个 MCP 服务复用 `BIGMODEL_KEY`(智谱与 BigModel 是同一个 key);未配置 `BIGMODEL_KEY` 时它们以 `enable: false` 写入配置。
`image_task` / `video_task` 两个 MCP 服务复用 `BIGMODEL_KEY`(智谱与 BigModel 是同一个 key);未配置 `BIGMODEL_KEY` 时它们以 `mode: disable` 写入配置。
`AUTH_USER` / `AUTH_PASSWORD` 不传时默认是 `admin` / `admin`,首次部署务必改掉。
@@ -110,6 +110,16 @@ mcp_servers:
接入栈外的 MCP 服务:在设置页添加 `url` / `headers`,或在 `config.yml` 的 `mcp_servers` 追加一项。服务不可达时 core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。
每个服务可用 `mode` 控制「工具是否下发给模型」:
| `mode` | 连接/发现 | 模型可见 | 谁可以调用 |
|---|---|---|---|
| `advertise`(默认) | ✓ | ✓ | 模型与技能 |
| `silent` | ✓ | ✗ | 技能(`mcp_tool`)与 `lab` |
| `disable` | ✗ | ✗ | 无人 |
`silent` 用于「能力包在技能后面」的场景:工具照常发现并注册,只是不进模型的 tools 数组,省掉每轮的 schema 开销。旧字段 `enable` 已废弃,写进配置会直接启动报错。
工具发现只在启动时做一次,因此发现失败后会自动按 **2s / 20s / 1min 重试 3 次**(覆盖 compose 并行拉起与宿主机重启后的容器乱序);成功后工具在下一轮请求即可用,三次都失败则需重启 core。三个 MCP 服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。
---
@@ -186,7 +196,7 @@ mcp_servers:
| `model_profiles` | prompt + 工具名单组合;模型用 `profile: <名>` 引用 |
| `tools_deny` | 全局工具黑名单,默认屏蔽元工具 `lab` |
| `auth` | 登录账号、`secret`、有效期;留空则不启用认证 |
| `mcp_servers` | 外部 MCP 服务:`url`、`headers`、`enable`、`timeout_ms`、工具名单 |
| `mcp_servers` | 外部 MCP 服务:`url`、`headers`、`mode`(advertise / silent / disable)、`timeout_ms`、工具名单 |
| `public_link` | 公网临时链接前缀与有效期 |
| `agent` | 温度、最大工具迭代、重试、语言、压缩阈值、空闲收口、历史裁剪 |
| `memory` | 日记注入条数、保留期、空闲收口阈值 |
+3
View File
@@ -158,6 +158,9 @@ POST /api/sessions/:id/messages
白名单、`tools_deny` 黑名单(**deny 赢**;profile 不配 deny 时继承全局 `tools_deny`)。
`tools_allow: []` = 零工具(纯文本组合)。过滤只影响"模型看得到什么",名单外工具若真被调用,
`executeTool` 仍会执行(不误杀)。
- MCP 服务按 `mcp_servers[].mode` 参与:`advertise`(默认)进 `toolDefs` 下发;`silent` 只进
`toolIndex`(`mcp.hasTool` 为真,技能 `mcp_tool` 与 `lab` 可调)但不进 tools 数组;`disable`
连 `tools/list` 都不发。旧字段 `enable` 已废弃,出现即报配置错(不静默忽略)。
- `executeTool(baseCtx, name, args)`:先查 `HANDLERS` 表,未命中再交给 MCP 注册表。
`ctx = {sessionId, taskDir, run, cfg, db, vision}`;工具返回字符串,`read_file` 读图时返回
`{text, image_rel}`(由 engine 转成 `image_ref` 块)。
+3 -1
View File
@@ -78,7 +78,9 @@ auth: # users 留空 = 不启用登
role: admin # admin=管理员(全部设置 + 用户管理);user 或缺省=普通用户(仅账户页)
# model: qwen-tp/qwen3.8-flash # 选填:该用户新建会话时锁定的模型(内部键「平台名/模型id」)
# MCP 服务列表(仓库自带的 mcp/ 三个服务,或栈外服务):每项 {name?, url, headers?, enable?(默认 true), timeout_ms?, tools_allow?, tools_deny?}。
# MCP 服务列表(仓库自带的 mcp/ 三个服务,或栈外服务):每项 {name?, url, headers?, mode?(默认 advertise), timeout_ms?, tools_allow?, tools_deny?}。
# mode 三态:advertise=工具下发给模型;silent=只注册可调用(技能 mcp_tool / lab)不下发;disable=不连接、不发现。
# 旧字段 enable 已废弃,写进配置会启动报错。
mcp_servers: []
public_link:
+14 -4
View File
@@ -121,7 +121,8 @@ const DEFAULTS = {
},
// 登录认证:{users:[{user,password}], secret?, ttl_ms?};null / users 空 = 不启用。
auth: null,
// 外部 MCP 服务列表(无默认值):{name?, url, headers?, enable?(默认 true), timeout_ms?(默认 60s)}。
// 外部 MCP 服务列表(无默认值):{name?, url, headers?, mode?(默认 advertise), timeout_ms?(默认 60s)}。
// mode 三态:advertise=工具下发给模型;silent=只注册可调用(技能/lab)不下发;disable=不加载。
mcp_servers: [],
// 公网临时链接:base_url 非空才启用 mint_public_link;容器配 VIRTUAL_HOST 时以它为准。
public_link: { base_url: '', ttl_ms: 1800000 },
@@ -340,7 +341,7 @@ function parseAndValidate(rawText, configPath) {
}
// MCP 服务规范化:url 必填;name 缺省取主机名首段;headers 为普通键值对象(如 Authorization);
// enable 缺省 true,显式 false 时启动不加载该服务的工具(见 mcp.init);
// mode 缺省 advertise,见下方三态校验(工具是否下发 / 是否加载,见 mcp.init);
// timeout_ms 为该服务单次 tools/call 的最大等待,缺省 60s(长任务服务如视频生成可调大)。
if (!Array.isArray(cfg.mcp_servers)) cfg.mcp_servers = [];
for (const s of cfg.mcp_servers) {
@@ -348,8 +349,17 @@ function parseAndValidate(rawText, configPath) {
if (!s.name) {
try { s.name = String(new URL(s.url).hostname.split('.')[0]); } catch (_) { s.name = 'mcp'; }
}
// 容错 YAML 里写成字符串 "false" / "off" 的情况,统一归一为布尔
s.enable = !(s.enable === false || s.enable === 'false' || s.enable === 'off' || s.enable === 0);
// 旧字段 enable 已废弃且不静默忽略:未知键会被无声丢弃,那样「以为关了」的服务会照常连上、
// 照常烧额度。宁可启动即报错,把迁移动作逼到明面上。
if (s.enable !== undefined) {
throw new Error('mcp_servers 的 enable 已废弃,请改用 mode: advertise | silent | disable');
}
// 三态:advertise(默认,工具下发给模型)/ silent(注册但不下发,配合技能 mcp_tool 使用)/
// disable(不连接、不发现)。拼错要报错而不是回落默认,否则又是一次静默降级。
const mode = String(s.mode == null ? '' : s.mode).trim().toLowerCase();
if (!mode) s.mode = 'advertise';
else if (mode === 'advertise' || mode === 'silent' || mode === 'disable') s.mode = mode;
else throw new Error('mcp_servers 的 mode 只能是 advertise / silent / disable,收到:' + mode);
const headers = {};
for (const [k, v] of Object.entries(s.headers || {})) headers[k] = String(v);
s.headers = headers;
+10 -5
View File
@@ -1,8 +1,9 @@
// 极简 MCP 客户端(Streamable HTTP:JSON-RPC over HTTP,无状态,响应可能是 SSE 帧包裹的 JSON)。
// MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?, enable?, timeout_ms?, tools_allow?, tools_deny?}。
// 启动时 init() 对每个服务调 tools/list 发现工具(enable: false 的服务跳过加载;配了 tools_allow/tools_deny
// MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?, mode?, timeout_ms?, tools_allow?, tools_deny?}。
// 启动时 init() 对每个服务调 tools/list 发现工具(mode: disable 的服务跳过加载;配了 tools_allow/tools_deny
// 时按名单过滤),发现失败的服务按 2s / 20s / 1min 再试 3 次(容器并行启动/重启后的乱序兜底),转成 OpenAI function 格式,
// 追加在内置工具(definitions.json)之后一起随 system prompt 发给模型;
// mode: silent 的服务工具照常注册进 toolIndex(技能 mcp_tool / lab 可调),只是不追加进 toolDefs(模型看不到)。
// 工具调用经 tools/call 转发给对应服务。
// 与内置工具严格分离:本模块不碰内置定义;MCP 工具默认沿用原始名,
// 仅当与内置工具或其他 MCP 工具重名时加「服务名__」前缀。
@@ -141,11 +142,14 @@ async function loadServer(s) {
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));
let hidden = 0;
for (const t of tools) {
if (!t || !t.name) continue;
let name = t.name;
if (builtinNames.has(name) || toolIndex.has(name)) name = s.name + '__' + name;
// 先进索引:silent 的工具要能被技能(mcp_tool)与 lab 调到,只是不下发。
toolIndex.set(name, { server: s, tool: t.name });
if (s.mode === 'silent') { hidden++; continue; }
toolDefs.push({
type: 'function',
function: {
@@ -157,6 +161,7 @@ async function loadServer(s) {
}
let msg = s.name + ': 发现 ' + tools.length + ' 个工具' + (s.sessionId ? ' (session)' : '');
if (tools.length !== all.length) msg += '(服务端共 ' + all.length + ' 个,已按 tools_allow/tools_deny 过滤)';
if (hidden) msg += '(mode=silent:' + hidden + ' 个不下发给模型,仅供技能调用)';
log.info('mcp', msg);
// 配了名单却一个都没过滤中,十有八九是名单里的名字跟 tools/list 返回不一致;
// 不 warn 的话排查时只能对着「发现 0 个工具」干瞪眼。
@@ -213,9 +218,9 @@ async function init(cfg) {
const servers = (cfg && cfg.mcp_servers) || [];
const failed = [];
for (const s of servers) {
// enable: false 时启动不加载该服务(不建工具表;配置保留,改回 true 重启后恢复)
if (s.enable === false) {
log.info('mcp', s.name + ': enable=false,跳过工具加载');
// mode: disable 时启动不加载该服务(不建工具表;配置保留,改回 advertise 重启后恢复)
if (s.mode === 'disable') {
log.info('mcp', s.name + ': mode=disable,跳过工具加载');
continue;
}
if (!(await loadServer(s))) failed.push(s);
+2
View File
@@ -1098,6 +1098,8 @@ label.icon-btn { cursor: pointer; }
.modal .mpe-num { display: flex; align-items: center; gap: 5px; flex: none; font-size: 12.5px; color: var(--gray); }
.modal .mpe-num input { width: 92px; padding: 5px 8px; margin: 0; font-size: 13px; border: 1px solid #dde1ea; border-radius: 8px; background: #fff; color: var(--ink); }
.modal .mpe-num input:focus { border-color: var(--active); }
/* MCP 的 mode 三态下拉:独立成行(弹窗内容宽仅 ~320px,与超时框同排会撑破),内层 select 用 .modal select 的全宽样式 */
.modal .mpe-field { display: block; margin-top: 14px; font-size: 12.5px; color: var(--gray); }
.modal .mpe-ck { display: flex; align-items: center; gap: 5px; font-size: 12.5px; color: var(--gray); }
.modal .mpe-ck input { width: 15px; height: 15px; padding: 0; margin: 0; border: none; background: none; accent-color: var(--active); cursor: pointer; }
.modal .mpe-del { flex: none; border: none; background: none; margin: 0; padding: 2px 7px; cursor: pointer; color: var(--gray-light); font-size: 18px; line-height: 1.2; }
+7 -1
View File
@@ -335,8 +335,14 @@
</div>
<div class="mpe-cks" style="margin-top:14px">
<label class="mpe-num">单次调用超时<input type="number" id="mce-timeout" min="1000" max="600000" step="1000" placeholder="默认 60000">ms</label>
<label class="mpe-ck"><input type="checkbox" id="mce-enable" checked>启用</label>
</div>
<label class="mpe-field">工具暴露
<select id="mce-mode">
<option value="advertise">advertise(下发给模型)</option>
<option value="silent">silent(仅技能可调用)</option>
<option value="disable">disable(不加载)</option>
</select>
</label>
<div class="btn-row mpe-foot">
<button class="ghost-btn danger hidden" id="mce-del-btn" onclick="mcpUI.del()">删除服务</button>
<button class="primary-btn" onclick="mcpUI.save()">保存</button>
+19 -10
View File
@@ -1416,11 +1416,13 @@
} catch (e) { toast('删除失败:' + e.message); }
}
// ---------- 页:MCP 服务(增/改/删;name / url / 多 headers / timeout_ms / enable) ----------
// ---------- 页:MCP 服务(增/改/删;name / url / 多 headers / timeout_ms / mode) ----------
// 与模型池共用 PATCH /api/config 的细粒度 edit 接口:
// · 新增 = append 到 mcp_servers;
// · 删 = delete mcp_servers[pi];
// · 改 = setIn mcp_servers[pi].(name|url|timeout_ms|enable);headers 是普通键值对象,整体 setIn 一次到位。
// · 改 = setIn mcp_servers[pi].(name|url|timeout_ms|mode);headers 是普通键值对象,整体 setIn 一次到位。
// mode 三态:advertise(默认,工具下发给模型) / silent(只注册可调用,不下发) / disable(不加载):
// 默认值不写进文件——选 advertise 时删键,回落到 config.js 的缺省。
// 运行配置(cg.effective.mcp_servers)即文件刚解析后的视图,按 pi 直接定位;重启后才会重新发现工具。
let mcpEdit = null; // 工作态:{ idx, headers:[{key, value, masked}] };idx=-1 为新增
const MCP_HEADER_MASK = '*****'; // 与后端 routes/config.js 的掩码保持一致
@@ -1449,16 +1451,20 @@
? '<div class="restart-bar"><span>配置已写入,重启后生效</span><button class="primary-btn" onclick="sUI.restartNow()">重启服务</button></div>'
: '';
box.innerHTML = banner + SET.cfgMcp.map(mcpCardHtml).join('') +
'<div class="empty-tip">点卡片编辑 MCP 服务,启用后启动时发现其工具并追加到内置工具之后。</div>';
'<div class="empty-tip">点卡片编辑 MCP 服务。advertise 的工具启动时发现并追加到内置工具之后;silent 只注册可调用(供技能 mcp_tool),不下发给模型。</div>';
} catch (e) {
const b = $('mcp-list');
if (b && (!ctx || ctx())) b.innerHTML = '<div class="empty-tip">加载失败:' + esc(e.message) + '</div>';
}
}
// MCP 卡:头部 = 名称 + url + enable 状态;体内 = headers 键值列表。整卡点击进入编辑。
// MCP 卡:头部 = 名称 + url + mode 状态;体内 = headers 键值列表。整卡点击进入编辑。
function mcpCardHtml(s, pi) {
const off = s.enable === false;
const stateHtml = off ? '<span class="model-card-state off">已禁用</span>' : '<span class="model-card-state idle">启用</span>';
const mode = s.mode || 'advertise';
const stateHtml = mode === 'disable'
? '<span class="model-card-state off">已禁用</span>'
: mode === 'silent'
? '<span class="model-card-state idle">仅技能可见</span>'
: '<span class="model-card-state idle">启用</span>';
const entries = Object.entries(s.headers || {});
// header 值等同密码对待:后端 effective 已脱敏为固定短掩码,这里透传展示;若收到未脱敏原文也一律替换,不外显
const maskVal = (v) => { const str = String(v == null ? '' : v); if (!str) return '--'; return str.includes('*') ? esc(str) : MCP_HEADER_MASK; };
@@ -1490,7 +1496,7 @@
$('mce-url').value = add ? '' : (s.url || '');
// 运行配置里的 timeout_ms 已被 config.js 填上缺省值,所以这里显示的就是当前生效值(没配则为 60000)。
$('mce-timeout').value = add || s.timeout_ms == null ? '' : String(s.timeout_ms);
$('mce-enable').checked = add ? true : (s.enable !== false);
$('mce-mode').value = add ? 'advertise' : (s.mode || 'advertise');
$('mce-del-btn').classList.toggle('hidden', add);
renderMcpHeaders();
$('mcp-edit-modal').classList.remove('hidden');
@@ -1530,7 +1536,7 @@
const edits = [];
const name = $('mce-name').value.trim();
const url = $('mce-url').value.trim();
const enable = $('mce-enable').checked;
const mode = $('mce-mode').value;
// 超时:留空 = 不写入该项(沿用缺省 60s)。区间在 UI 先把一道,
// 比写进 YAML 再被 config.js 静默夹掉好排查(两边上限保持 600000 一致)。
const tmoRaw = $('mce-timeout').value.trim();
@@ -1545,7 +1551,7 @@
if (!url) throw new Error('请填写 url');
const obj = { url };
if (name) obj.name = name;
if (!enable) obj.enable = false;
if (mode !== 'advertise') obj.mode = mode;
if (tmo != null) obj.timeout_ms = tmo;
const headers = {};
for (const r of mcpEdit.headers) {
@@ -1560,7 +1566,10 @@
if (!url) throw new Error('请填写 url');
if (name !== (cur.name || '')) edits.push({ path: ['mcp_servers', mcpEdit.idx, 'name'], value: name });
if (url !== (cur.url || '')) edits.push({ path: ['mcp_servers', mcpEdit.idx, 'url'], value: url });
if (!!cur.enable !== enable) edits.push({ path: ['mcp_servers', mcpEdit.idx, 'enable'], value: enable });
// mode:默认值不写进文件(选 advertise 就删键)
if ((cur.mode || 'advertise') !== mode) edits.push(mode === 'advertise'
? { path: ['mcp_servers', mcpEdit.idx, 'mode'], op: 'delete' }
: { path: ['mcp_servers', mcpEdit.idx, 'mode'], value: mode });
// 超时:清空 = 删掉该键(回落到缺省);后端 deleteIn 支持嵌套键,无键时是空操作。
const curTmo = cur.timeout_ms == null ? null : Number(cur.timeout_ms);
if (tmo !== curTmo) edits.push(tmo == null
+2 -1
View File
@@ -193,7 +193,8 @@ mcp.init(cfg).then(async () => {
log.info('startup', ' workspace_root=' + cfg.workspace_root);
log.info('startup', ' data_root=' + cfg.data_root);
log.info('startup', ' models=' + cfg.models.map(m => m.id + '@' + m.url).join(', '));
const mcpList = (cfg.mcp_servers || []).map(s => s.name + '@' + s.url + (s.enable === false ? '(禁用)' : '')).join(', ');
const mcpList = (cfg.mcp_servers || []).map(s => s.name + '@' + s.url +
(s.mode === 'disable' ? '(禁用)' : s.mode === 'silent' ? '(仅技能)' : '')).join(', ');
log.info('startup', ' mcp_servers=' + (mcpList || '(none)'));
log.info('startup', ' auth=' + (auth.enabled ? 'login: ' + cfg.auth.users.map(u => u.user).join(', ') : '(disabled)'));
log.info('startup', ' wxbot=' + (cfg.wxbot.url && cfg.wxbot.token ? cfg.wxbot.url : '(未启用)'));
+5 -5
View File
@@ -11,7 +11,7 @@
# 输入(都可选):
# BIGMODEL_KEY / DEEPSEEK_KEY / QWEN_KEY 模型平台 key,填几个启用几个(0~3 个)
# image_task / video_task 复用 BIGMODEL_KEY(智谱即 BigModel);
# 未配 BIGMODEL_KEY 时这两个服务写为 enable: false
# 未配 BIGMODEL_KEY 时这两个服务写为 mode: disable
# AUTH_USER / AUTH_PASSWORD 登录账号(默认 admin / admin,请自行改掉)
# PUBLIC_IP / AGENT_PORT 对外地址与端口,写进 public_link.base_url;
# PUBLIC_IP 不配置则自动探测公网 IP
@@ -220,10 +220,10 @@ EOF
cat <<'EOF'
- name: image_task
url: "http://mcp_image_task:3000/mcp"
enable: false # 未配 BIGMODEL_KEY:只注册不加载,工具不发给模型
mode: disable # 未配 BIGMODEL_KEY:不连接、不发现;补上 key 后重跑本脚本
- name: video_task
url: "http://mcp_video_task:3000/mcp"
enable: false # 未配 BIGMODEL_KEY:只注册不加载,工具不发给模型
mode: disable # 未配 BIGMODEL_KEY:不连接、不发现;补上 key 后重跑本脚本
EOF
fi
@@ -235,7 +235,7 @@ public_link:
EOF
} > "$CONFIG_YML"
info "平台: ${enabled_plats[*]:-无};图像/视频 MCP: $([ -n "$BIGMODEL_KEY" ] && echo 启用 || echo 未配置(enable: false))"
info "平台: ${enabled_plats[*]:-无};图像/视频 MCP: $([ -n "$BIGMODEL_KEY" ] && echo 启用 || echo 未配置(mode: disable))"
# ============================================================
# 3. 汇总
@@ -246,7 +246,7 @@ echo " 访问地址 : http://${PUBLIC_IP:-<公网IP>}:${AGENT_PORT}"
echo " 账号 : $AUTH_USER"
echo " 密码 : $AUTH_PASSWORD"
echo " 平台 : ${enabled_plats[*]:-(无)}"
echo " 图像/视频: $([ -n "$BIGMODEL_KEY" ] && echo "image_task / video_task 已启用" || echo "未配置(enable: false)")"
echo " 图像/视频: $([ -n "$BIGMODEL_KEY" ] && echo "image_task / video_task 已启用" || echo "未配置(mode: disable)")"
echo " MCP 服务 : web_search / image_task / video_task(同栈,随 compose 启动)"
echo " 微信接入 : WXBOT_TOKEN 已就位(compose 注入 core 与 wxbot 两侧;wxbot 无需配置文件)"
echo "---------------------------------------------"