mcp 工具发现失败重试 3 次(2s/20s/1min)+ MCP 服务健康检查
This commit is contained in:
@@ -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` |
|
||||
|
||||
---
|
||||
|
||||
|
||||
+95
-53
@@ -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 工具定义(追加在内置工具之后)。
|
||||
|
||||
@@ -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"
|
||||
|
||||
+1
-1
@@ -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` 本栈。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user