MCP服务静默退出:超时为何绕过异常处理
文章复盘Stitch MCP服务连接中断且缺少错误日志的案例,关注长时间运行的子进程与JSON-RPC传输超时之间的关系。摘录指出,仅在工具处理函数中使用try-catch,无法覆盖子进程持续挂起、Promise迟迟不结束的情况。
AI 深度解读
凌晨 2:14 PST,作者团队的 Stitch MCP 服务在执行一次大仓库克隆时失联:Claude Code 收到连接断开的错误,服务端却没有异常日志,还出现了退出码 0。作者据此提出,工具调用需要独立超时、传输关闭日志和健康检查,单靠 try-catch 不够。
这篇故障记录值得读,但要分开看:给长任务设置执行期限是实用建议;文中对 SDK 超时、SIGPIPE 和进程退出的归因,缺少足够证据,给出的修复也没有真正停止后台任务。
为什么写了 try-catch,调用还是会失联
作者描述的调用链是:Claude Code 发送 tools/call,调用 stitch-skills 中的 git_clone_skill,后者执行 git clone https://massive-monorepo.git,克隆一个 4.2 GB 的仓库。
按照作者的解释,任务超过 30 秒后,stdio 传输先关闭,而处理器仍在等待 Git 子进程。客户端看到 socket EOF,服务端却没有进入预期的异常处理流程。
这里有个需要纠正的表述:原文说 try-catch 只能处理同步异常,并不准确。在 try 内执行 await executeSkill(...),同样能捕获这个 Promise 的拒绝。问题是,一直没有完成的 Promise,不会自动变成一个能被捕获的超时异常。
子进程卡住、网络请求迟迟不返回,程序就可能一直等下去。如果连接由其他层先行关闭,业务处理器的 catch 也未必能感知这次关闭。
原文将后续过程归因为:管道关闭触发 SIGPIPE,Node.js 默认处理导致 process.exit(0)。但文章没有提供 Node.js 版本、平台行为、SDK 源码位置或最小复现,不能仅凭这段叙述确认整条因果链。
25 秒超时解决了什么,又留下了什么
作者称,@modelcontextprotocol/sdk 的稳定版 0.5.x 存在隐式且不可配置的 30 秒 stdio 读取超时,因此给技能设置了 25000 毫秒的期限。
下面是原文的主要修复代码,它试图让工具提前返回错误,并在收到 SIGPIPE 时记录日志、以非零状态退出:
// server.ts - Add at the top of your Stitch MCP server entrypoint
process.on('SIGPIPE', () => {
console.error('[SIGPIPE] Transport closed mid-execution, graceful shutdown');
process.exit(1); // Non-zero for monitoring
});
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const SKILL_TIMEOUT_MS = 25000; // Under transport's 30s limit
try {
const result = await Promise.race([
executeSkill(request.params.name, request.params.arguments),
new Promise((_, reject) =>
setTimeout(() => reject(new Error('Skill timeout')), SKILL_TIMEOUT_MS)
)
]);
return { content: [{ type: "text", text: JSON.stringify(result) }] };
} catch (error) {
console.error(`[tool:${request.params.name}] ${error.message}`);
return {
content: [{ type: "text", text: `Execution failed: ${error.message}` }],
isError: true
};
}
});
要盯住 Promise.race 这一行:它让超时 Promise 有机会先拒绝,使处理器进入 catch,返回带 isError: true 的工具结果;它没有取消 executeSkill,也没有终止 Git 子进程。
返回超时,不等于停止执行。
如果客户端随后重试,旧任务可能仍在占用网络、磁盘或子进程资源。另外,示例没有清理定时器;任务提前完成后,定时器仍会保留到触发。事件循环被阻塞时,25000 毫秒的定时器也无法保证准时执行,所以原文所谓「保证在传输超时前完成」说得过满。
作者还建议在 claude_desktop_config.json 中配置 node,通过 args 指向 /path/to/stitch-skills/dist/server.js,并设置 NODE_OPTIONS=--max-old-space-size=512、SKILL_TIMEOUT_MS=25000。
这里有两处边界:上面的代码将期限写成常量,没有读取环境变量;512 限制的是 Node.js 的 V8 老生代堆,不能当作 Git 子进程的内存限制。文章也没有说明,这个配置文件如何对应其使用的 Claude Code 配置入口。
健康检查能连通,不代表长任务能跑完
原文的健康检查通过 StdioClientTransport 启动 node ./dist/server.js,创建名称为 health-check、版本为 1.0.0 的 Client,依次执行 client.connect(transport)、client.listTools() 和 client.close(),输出已注册技能数量。
这个检查可以验证服务能否启动、连接和列出工具,却没有执行 tools/call。Git 卡住、工具超时后无法释放资源、客户端断开后任务继续运行,都可能绕过这项检查。
文中还提到经过 B-Lost relay gateway 的生产部署,但展示的健康检查直接启动本地 stdio 服务,没有覆盖 relay 链路。
作者建议观察 Claude Code 或 Cursor 测试中「没有错误日志却退出 0」的情况。这是有价值的排查线索,但不能直接当作某一种传输故障的确诊信号。开头记录还出现容器状态 137;它与服务端所见退出码 0 的关系,原文没有解释清楚。
我的判断
我赞同把执行期限和失败日志写进工具实现。对会运行 git clone、npm install 或外部 HTTP 请求的 MCP 服务,这比无限等待更容易排障。
但文章没有给出修复前后的复现结果、对照数据,也没有展示子进程被回收的证据。它提供的是一次故障归因和修复方案,尚不足以证明「所有异步技能都必须用 Promise.race,并统一比传输期限短 5-10 秒」。
相比单纯竞争一个定时器,支持取消的 HTTP 请求、带超时和终止流程的子进程封装,能进一步处理超时后的资源问题。25 秒可以作为作者环境里的选择,不能直接变成一般团队的固定配置。尤其是 4.2 GB 的仓库克隆,原文没有说明超过期限后应如何完成业务目标。
能拿来做什么
- 给 Node MCP 工具分别记录调用开始、完成、超时和进程退出,并带上工具名,方便把客户端断连与服务端执行过程对起来。
- 对
git clone、npm install等子进程同时设计等待期限和终止流程;若使用Promise.race,继续检查超时后任务是否仍在运行。 - 把健康检查分成连接与列举工具、实际调用工具两部分,并补测卡住、超时和客户端断开后的资源回收。
- 使用配置前核对实际 SDK 版本和客户端配置入口;要让
SKILL_TIMEOUT_MS生效,就让代码读取并校验它,再结合实际链路确定期限。