From 722db2681ef70f56adf2688df2f0adb1e2df950a Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 20 Oct 2026 15:20:19 +0800 Subject: [PATCH] =?UTF-8?q?mcp=20=E5=B7=A5=E5=85=B7=E5=8F=91=E7=8E=B0?= =?UTF-8?q?=E5=A4=B1=E8=B4=A5=E9=87=8D=E8=AF=95=203=20=E6=AC=A1=EF=BC=882s?= =?UTF-8?q?/20s/1min=EF=BC=89+=20MCP=20=E6=9C=8D=E5=8A=A1=E5=81=A5?= =?UTF-8?q?=E5=BA=B7=E6=A3=80=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 3 + app/server/mcp.js | 148 +++++++++++++++++++++++++++++---------------- docker-compose.yml | 23 +++++++ mcp/README.md | 2 +- 4 files changed, 122 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index dc6f90d..b4bc93a 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,8 @@ mcp_servers: 接入栈外的 MCP 服务:在设置页添加 `url` / `headers`,或在 `config.yml` 的 `mcp_servers` 追加一项。服务不可达时 core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。 +工具发现只在启动时做一次,因此发现失败后会自动按 **2s / 20s / 1min 重试 3 次**(覆盖 compose 并行拉起与宿主机重启后的容器乱序);成功后工具在下一轮请求即可用,三次都失败则需重启 core。三个 MCP 服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。 + --- ## 使用 @@ -389,6 +391,7 @@ curl -s http://127.0.0.1:8090/api/health | 技能依赖缺失 | 重新 `docker compose up -d --build agent-executor`;或检查 `skills/deps` | | 微信设置页显示未连接 | wxbot 未启动,或 `WXBOT_TOKEN` 两侧不一致 | | 图生视频拉不到参考图 | `public_link.base_url` 未配置,或公网不可达 | +| 启动日志出现 `xxx 工具发现失败` | 当时服务未就绪,core 会按 2s/20s/1min 重试 3 次;仍失败则重启 `agent-core` | --- diff --git a/app/server/mcp.js b/app/server/mcp.js index cba261b..3e37c7c 100644 --- a/app/server/mcp.js +++ b/app/server/mcp.js @@ -1,7 +1,7 @@ // 极简 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 -// 时按名单过滤),转成 OpenAI function 格式, +// 时按名单过滤),发现失败的服务按 2s / 20s / 1min 再试 3 次(容器并行启动/重启后的乱序兜底),转成 OpenAI function 格式, // 追加在内置工具(definitions.json)之后一起随 system prompt 发给模型; // 工具调用经 tools/call 转发给对应服务。 // 与内置工具严格分离:本模块不碰内置定义;MCP 工具默认沿用原始名, @@ -108,8 +108,98 @@ async function rpc(server, method, params, timeoutMs, extraHeaders) { } } -// 发现所有 MCP 服务的工具。单个服务失败只警告,不影响其他服务与内置工具。 +// 启动发现失败后的重试阶梯(毫秒):2s / 20s / 1min,共 3 次。 +// 动机:compose 并行拉起容器、宿主机重启后容器顺序也不保证,而工具发现只在启动时跑一次; +// 不重试的话该服务会在这个进程的整个生命周期里缺席,只能重启 core 才能恢复。 +const DISCOVERY_RETRY_DELAYS_MS = [2000, 20000, 60000]; + +// 发现单个服务的工具并并入工具表:成功返回 true,失败返回 false(不抛)。 // 对要求会话的服务,先发 initialize 拿到 Mcp-Session-Id,再发 notifications/initialized + tools/list。 +async function loadServer(s) { + // 清理上次会话 id(重启后服务端会拒绝旧 id;不清理会一直 400) + s.sessionId = null; + try { + // 先 initialize:兼容要求会话的服务。strict 模式下服务端会返回 session id; + // 不要求的服务也会正常响应(只是响应头里没有 mcp-session-id)。 + try { + await rpc(s, 'initialize', { + protocolVersion: '2024-11-05', + capabilities: {}, + clientInfo: { name: 'agent', version: '1.0.0' }, + }, 15000); + // 按 MCP 规范:initialize 成功后发 notifications/initialized 通知(不需要 id,不期待响应体) + try { await rpc(s, 'notifications/initialized', {}, 5000); } catch (_) { /* 通知失败不阻断 */ } + } catch (e) { + // 某些老服务(无 initialize)会报 Method not found;不阻断,走原 tools/list 路径 + if (!/Method not found/i.test(String(e && e.message || e))) throw e; + } + const result = await rpc(s, 'tools/list', {}, 15000); + 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; + if (builtinNames.has(name) || toolIndex.has(name)) name = s.name + '__' + name; + toolIndex.set(name, { server: s, tool: t.name }); + toolDefs.push({ + type: 'function', + function: { + name, + description: t.description || t.title || '', + parameters: t.inputSchema || t.input_schema || { type: 'object', properties: {} }, + }, + }); + } + 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(', ') + ' …)'); + } + return true; + } catch (err) { + log.warn('mcp', s.name + ' 工具发现失败(' + (err && err.message || err) + ')'); + return false; + } +} + +// 对启动时发现失败的服务按阶梯重试;成功后工具立即并入工具表,模型的下一轮请求即可见。 +function retryFailed(failed) { + let pending = failed.slice(); + const attempt = (i) => { + const timer = setTimeout(async () => { + if (!pending.length) return; + log.info('mcp', '重试工具发现 第 ' + (i + 1) + '/' + DISCOVERY_RETRY_DELAYS_MS.length + ' 次: ' + + pending.map(s => s.name).join(', ')); + const still = []; + for (const s of pending) { + if (!(await loadServer(s))) still.push(s); + } + pending = still; + if (!pending.length) { + log.info('mcp', '重试成功:失败服务的工具已并入'); + } else if (i + 1 < DISCOVERY_RETRY_DELAYS_MS.length) { + attempt(i + 1); + } else { + log.warn('mcp', '重试结束仍不可用: ' + pending.map(s => s.name).join(', ') + + '(服务恢复后需重启 core 才能加载其工具)'); + } + }, DISCOVERY_RETRY_DELAYS_MS[i]); + // 不因待重试的定时器拖住进程退出(测试、一次性脚本里尤其明显) + if (timer.unref) timer.unref(); + }; + attempt(0); +} + +// 发现所有 MCP 服务的工具。单个服务失败只警告,不影响其他服务与内置工具,并进入重试阶梯。 async function init(cfg) { toolDefs = []; toolIndex.clear(); @@ -121,64 +211,16 @@ async function init(cfg) { } catch (_) { /* 内置定义读不到就不做重名保护 */ } 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,跳过工具加载'); continue; } - // 清理上次会话 id(重启后服务端会拒绝旧 id;不清理会一直 400) - s.sessionId = null; - try { - // 先 initialize:兼容要求会话的服务。strict 模式下服务端会返回 session id; - // 不要求的服务也会正常响应(只是响应头里没有 mcp-session-id)。 - try { - await rpc(s, 'initialize', { - protocolVersion: '2024-11-05', - capabilities: {}, - clientInfo: { name: 'agent', version: '1.0.0' }, - }, 15000); - // 按 MCP 规范:initialize 成功后发 notifications/initialized 通知(不需要 id,不期待响应体) - try { await rpc(s, 'notifications/initialized', {}, 5000); } catch (_) { /* 通知失败不阻断 */ } - } catch (e) { - // 某些老服务(无 initialize)会报 Method not found;不阻断,走原 tools/list 路径 - if (!/Method not found/i.test(String(e && e.message || e))) throw e; - } - const result = await rpc(s, 'tools/list', {}, 15000); - 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; - if (builtinNames.has(name) || toolIndex.has(name)) name = s.name + '__' + name; - toolIndex.set(name, { server: s, tool: t.name }); - toolDefs.push({ - type: 'function', - function: { - name, - description: t.description || t.title || '', - parameters: t.inputSchema || t.input_schema || { type: 'object', properties: {} }, - }, - }); - } - 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)); - } + if (!(await loadServer(s))) failed.push(s); } + if (failed.length) retryFailed(failed); } // 随请求发送的 MCP 工具定义(追加在内置工具之后)。 diff --git a/docker-compose.yml b/docker-compose.yml index 513d665..d61b02b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -152,11 +152,22 @@ services: # 同栈 MCP 服务(./mcp/):三个 Model Context Protocol 适配器,由 core 按容器名调用。 # 全部不占宿主机端口、无服务端鉴权,**永远不要**把 ports 映射出去(会被白嫖额度)。 # 工具说明、header 覆盖项与 curl 调试见 mcp/README.md 及各子目录 README。 + # + # 刻意不写 depends_on / 不等 healthy:MCP 是可选能力,core 不该因它们缺席而拒绝启动 + # (构建失败、单个服务被删都不影响 Web 主流程)。启动瞬间的竞态由 core 侧的工具发现重试 + # 兜底(2s / 20s / 1min × 3),healthcheck 只用于 docker ps 判态。 # ---------------------------------------------------------------- mcp_web_search: build: ./mcp/web_search container_name: mcp_web_search restart: unless-stopped + # 供 core 的启动顺序参考与 docker ps 判态(core 侧的发现失败重试不依赖它) + healthcheck: + test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 5s # 调试用(默认关): # ports: # - "${WEB_SEARCH_PORT:-8081}:3000" @@ -167,6 +178,12 @@ services: build: ./mcp/image_task container_name: mcp_image_task restart: unless-stopped + healthcheck: + test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 5s # 调试用(默认关): # ports: # - "${IMAGE_TASK_PORT:-8082}:3000" @@ -177,6 +194,12 @@ services: build: ./mcp/video_task container_name: mcp_video_task restart: unless-stopped + healthcheck: + test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 5s # 调试用(默认关;这里映的是 MCP 端口,会暴露 /mcp,仅本机短时调试用): # ports: # - "${VIDEO_TASK_PORT:-8083}:3000" diff --git a/mcp/README.md b/mcp/README.md index 5ae0b85..034db1e 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -33,7 +33,7 @@ mcp_servers: url: "http://mcp_video_task:3000/mcp" ``` -服务没起来时,core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。 +服务没起来时,core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。工具发现只在启动时做一次,失败后会自动按 2s / 20s / 1min 重试 3 次;三次都失败则需重启 core。三个服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。 > 从旧的「agent + mcp 双仓库」部署升级:先在旧 mcp 仓库目录 `docker compose down`(只需一次,否则同名容器与网络会冲突),再 `up` 本栈。