[Bug] HTTP 型 MCP 的工具调用被连接超时（10s）截断，慢工具必然失败 / HTTP MCP tool calls are cut off by the connect timeout (10s)

[lowlandsheperd]

What happened? / 问题描述

HTTP（streamable HTTP）类型的 MCP 服务器，当单个工具调用耗时超过 10 秒时，调用必定被中断，报 This operation was aborted（AbortError，errorCode: 20），而不是预期的 MCP_CALL_TIMEOUT_MS（100s）。

问题不在于「缺少可配置的超时」，而在于连接超时被误用为每次请求的中断上限——即代码没有按其自身设计运行：

apps/desktop/electron/main/plugin-mcp.ts

• :10 MCP_CONNECT_TIMEOUT_MS = 10_000
• :12 MCP_CALL_TIMEOUT_MS = 100_000
• :497-498 handshake() 里取的是连接超时，并把它传进 createTransport()：

  const timeoutMs = this.opts.connectTimeoutMs ?? MCP_CONNECT_TIMEOUT_MS;  // 10s
  const transport = this.createTransport(timeoutMs);

• :567 createTransport() 再把它交给 HTTP 传输层作为 timeoutMs
• :304 HTTP 传输层用它给每一次 send() 挂 abort 定时器：

  const timer = setTimeout(() => controller.abort(), options.timeoutMs);

因此 tools/call 的 HTTP 请求在 10 秒被 fetch abort。而 callTool() 在 :475 传入的 callTimeoutMs ?? MCP_CALL_TIMEOUT_MS（100s）只挂在 JSON-RPC 层的 Promise 上（:649-652），永远来不及触发——fetch 先抛 AbortError，request() 在 :654-660 把它 reject 出去，错误类型也随之退化成 abort 而非 TIMEOUT。

stdio 型 MCP 不受影响，可作对照证据：createStdioTransport（:129，由 :551-561 调用）不接收 timeoutMs，也没有 abort 定时器，其 tools/call 只受 JSON-RPC 层 100s 约束——这正是设计意图。HTTP 是唯一偏离的路径。

附带一个同类问题：tools/list 每页也被 10s 卡住（:511 传入 timeoutMs，:605-609 用 Math.min(timeoutMs, remaining)），虽然 :589 的整体 discovery deadline 是 30s。

影响面

只有单个工具执行 > 10s 才会暴露，因此触发面窄、不易被发现。本例中 tavily_research 实测 39.45s，在该 MCP 服务器上必然失败；其余四个工具（1.2s / 9.3s / 2.3s / 3.6s）均正常，形成清晰对照。

Steps to reproduce / 复现步骤

1. 从冷启动打开应用，配置一个 HTTP 型 MCP 服务器，且其中至少一个工具的响应时间 > 10 秒。
   • 可复现的最小样本：任意对 tools/call 延迟 12 秒再返回的 HTTP MCP 端点。
   • 本报告使用的真实样本：某远程 HTTP MCP（https://<private-mcp-endpoint>/mcp），其中 tavily_research 约 39 秒。
2. 在 Agent 模式下让模型调用该慢工具（工具通过 ToolSearch 按需激活，无需特殊设置）。
3. 观察：约 10 秒后调用失败；同一服务器上的快工具仍然可用。

补充：用直连 MCP 端点的方式（initialize → tools/list → tools/call，超时放宽到 240s）调用同一个 tavily_research，39.45 秒正常返回结果，证明服务端与凭据都没有问题。

Expected behavior / 预期行为

单次 tools/call 应受 MCP_CALL_TIMEOUT_MS（100s）约束。耗时 39 秒的工具调用应正常返回；超过 100 秒才应失败，且错误类型应为 TIMEOUT（mcp tools/call timed out after 100000ms），而非 fetch 的 AbortError。

---

Actual behavior / 实际行为

调用在 10 秒被中断，且错误类型退化为 AbortError：

{"api":"mcp.call","ok":false,"serverId":"<server-id>","transport":"http",
 "tool":"tavily_research","durationMs":10006,"errorCode":20}

message: "This operation was aborted"。

因为抛的不是 TIMEOUT，使用者无法从错误本身区分「超时」与「服务器连接中断」，排查成本被抬高。

App version / 应用版本

0.15.6

Operating system / 操作系统

Windows

Extra environment / 其他环境信息

Windows 11 Pro (build 26200) · x64 (12th Gen Intel Core i7-12700)
protocol 11 · host 0.15.6 · NSIS 安装（%LOCALAPPDATA%\Programs\PI-Desktop）
MCP transport: http (streamable HTTP) · 该服务器注册 5 个工具

Logs / 日志

同一次会话、同一个 HTTP MCP 服务器——前四个工具成功，第五个在 10 秒被截断：


{"api":"mcp.connect","ok":true,"serverId":"<server-id>","transport":"http","toolCount":5}
{"api":"mcp.call","ok":true, "tool":"tavily_search",   "durationMs":1220}
{"api":"mcp.call","ok":true, "tool":"tavily_extract",  "durationMs":9301}
{"api":"mcp.call","ok":true, "tool":"tavily_map",      "durationMs":2267}
{"api":"mcp.call","ok":true, "tool":"tavily_crawl",    "durationMs":3602}
{"api":"mcp.call","ok":false,"tool":"tavily_research", "durationMs":10006,"errorCode":20,
 "message":"This operation was aborted"}


注意 `durationMs: 10006` 与 `MCP_CONNECT_TIMEOUT_MS = 10_000` 的吻合，以及其余工具全部低于 10s——这排除了服务端或网络问题。

Screenshots / 截图

附：修复方向建议（仅供参考，供维护者判断）

原则应是按请求语义分派超时，而不是让传输层继承连接超时：

1. McpTransport.send 增加可选的 per-request 超时参数，HTTP 传输层用它（connectTimeoutMs 仅作兜底）。
2. request() 把 timeoutMs 下传给 send()，使 JSON-RPC 定时器与传输层 abort 同源同值——谁先到都报同一个 TIMEOUT，不再退化成 AbortError。
3. 各调用点用自己的预算：initialize → connectTimeoutMs(10s)；tools/list 每页 → 受 30s discovery deadline 约束；tools/call → callTimeoutMs(100s)。

这样修完，慢工具的默认行为即恢复为设计值 100s，无需新增任何配置项。

若后续希望开放该超时可调，需注意既有上限不变式：
host-core DESKTOP_TOOL_DISPATCH_TIMEOUT_MS = 150s（crates/host-core/src/tools/mod.rs:966-976）必须包住内层全部预算
（PLUGIN_TOOL_TIMEOUT_MS = 110s，以及 MCP 最宽 leg = 10s + 30s + 100s = 140s）。
因此 callTimeoutMs 若对外开放，上限不能超过 100s，否则 host-core 会先报通用 TOOL_TIMEOUT，
内层永远报不出自己的错误——那会比当前这个 bug 更难诊断。

[lowlandsheperd]

1. 根因（两个问题，主次分明）

Bug A（真根因）：HTTP 传输层把「连接超时」当作每次请求的 abort 上限

apps/desktop/electron/main/plugin-mcp.ts

• :10 MCP_CONNECT_TIMEOUT_MS = 10_000
• :12 MCP_CALL_TIMEOUT_MS = 100_000
• :497 handshake() 里 const timeoutMs = this.opts.connectTimeoutMs ?? MCP_CONNECT_TIMEOUT_MS;
• :498 const transport = this.createTransport(timeoutMs); ← 传的是连接超时
• :563-570 createTransport 把它当 timeoutMs 交给 HTTP 传输层
• :304 const timer = setTimeout(() => controller.abort(), options.timeoutMs); ← 挂在每一次 send() 上

于是：tools/call 的 HTTP 请求在 10 秒被 fetch abort。callTool 在 :475 传的
callTimeoutMs ?? MCP_CALL_TIMEOUT_MS（100s）只挂在 JSON-RPC Promise 上（:649-652），
永远来不及触发 —— fetch 先抛 AbortError，request() 在 :654-660 把它
reject 出去，错误码退化成 abort 而非 TIMEOUT。

日志实证：durationMs: 10006、errorCode: 20（AbortError）、"This operation was aborted"。

为什么只有 HTTP 型中招

createStdioTransport（:129、:551-561）不接收 timeoutMs，没有 abort 定时器
（全文件 grep timer|abort 在该区间零命中）。stdio 的 tools/call 因此只受
JSON-RPC 层 100s 约束 —— 即「设计意图」。HTTP 是唯一偏离的路径。

影响面

只有单个工具执行 > 10s 才暴露。Tavily tavily_research 实测 39.45s，故在 UI 内
必然失败；search/extract/crawl/map 均 < 6s，不受影响。

Bug B（次要，同样要修）：tools/list 每页也吃 10s

:511 this.tools = await this.listTools(timeoutMs) 把 10s 当每页上限，
:605-609 用 Math.min(timeoutMs, remaining)。虽然 :589 的 discovery deadline
是 30s，但每页仍被 10s 卡住。分页慢的服务器会被误判超时。

---

2. 修复方案（PR 主体，约 20 行）

原则：超时按「请求语义」分派，而不是让传输层继承连接超时。

2.1 传输层接受 per-request 超时

// :50-53
export type McpTransport = {
  send: (message: JsonRpcMessage, timeoutMs?: number) => Promise<void>;
  close: () => void;
};

// createHttpTransport options: timeoutMs → defaultTimeoutMs（仅兜底）
// :304
const timer = setTimeout(
  () => controller.abort(),
  timeoutMs ?? options.defaultTimeoutMs,
);

createStdioTransport 保持无 abort 定时器，只为满足类型签名接收并忽略第二个参数。

2.2 request() 把超时下传

// :654
void transport.send({ jsonrpc: "2.0", id, method, params }, timeoutMs).catch(...)

这样 JSON-RPC 定时器（:649）与传输层 abort 同源同值，谁先到都报同一个
TIMEOUT，不再退化成 AbortError。

2.3 调用点各用各的预算

调用点	行	传的超时
initialize	:501-509	connectTimeoutMs（10s，语义正确）
tools/list 每页	:605-609	Math.min(connectTimeoutMs, remaining)（或直接用 remaining，受 30s deadline 约束）
tools/call	:472-476	callTimeoutMs（100s）✅ 修复点

createTransport() 去掉参数，改从 opts.connectTimeoutMs 取兜底值。

2.4 回归测试（AGENTS.md §12 要求先红后绿）

apps/desktop/test/plugin-mcp.test.mjs 已有 startHttpServer 夹具（:325 起，
connectTimeoutMs/callTimeoutMs: 5_000），复用即可：

test("an http tool call is not cut off by the connect timeout", async (t) => {
  // 服务器对 tools/call 延迟 300ms 应答
  const client = new McpServerClient({
    /* ... */
    connectTimeoutMs: 100,      // 握手必须挤进 100ms
    callTimeoutMs: 5_000,       // 调用有充足预算
  });
  await client.connect();
  const result = await client.callTool("slow", {});   // 旧代码：abort
  assert.equal(describeMcpContent(result.content), "…");
});

旧代码上失败（tools/call 在 100ms 被 abort），新代码上通过。

2.5 验证命令（AGENTS.md §12 command surface）

本改动只动 apps/desktop/electron/main/plugin-mcp.ts（纯 TS），不动 Rust、不动
renderer，故取最窄的充分集合：

pnpm build:js                                        # 依赖包需先构建
pnpm --filter @pi-desktop/desktop typecheck
pnpm --filter @pi-desktop/desktop test               # node --test test/*.test.mjs

pnpm lint 对本改动不适用——biome.json 的 lint 范围只含
apps/desktop/src/features/{app,chat/composer,plugins,settings}/**、
electron/main/runtime/session-launch.ts、electron/main/ipc/workspace-ipc.ts、
packages/shared/src/types/**/*.ts、scripts/**，而 plugin-mcp.ts 不在其中。
cargo 门禁同样不适用（未动 Rust）。

若采纳 §3.4 的配置项，范围扩到 Rust + shared + renderer，需追加：

pnpm --filter @pi-desktop/shared test
pnpm --filter @pi-desktop/i18n test
pnpm docs:check                                      # 改过 zh-CN 镜像后
cargo fmt --check && cargo test -p host-core --locked && cargo clippy -p host-core --all-targets

---

3. 关于「加超时配置项」

3.1 配置项不是修这个 bug 的必要条件

Bug A 修好后，tools/call 的默认预算就是既有的 MCP_CALL_TIMEOUT_MS = 100s。
research 39.45s < 100s，默认配置即可正常工作。也就是说：这个 bug 的本质是
「代码没按自己的设计走」，而非「缺一个可调项」。先修 A，用户立刻可解。

3.2 配置项有一条硬上限，不能开放

外层预算链条是既有的、被文档和常量双重固定的不变量：

host-core DESKTOP_TOOL_DISPATCH_TIMEOUT_MS = 150s   crates/host-core/src/tools/mod.rs:976
  镜像   DESKTOP_TOOL_DISPATCH_TIMEOUT_MS = 150s   packages/shared/src/rpc-timeouts.ts
PLUGIN_TOOL_TIMEOUT_MS      = 110s   apps/desktop/electron/main/plugin-runtime.ts:557
MCP 最宽 leg = 10s 握手 + 30s tools/list + 100s 调用 = 140s

• crates/host-core/src/tools/mod.rs:966-976 注释明确写：该值「must outlast every
  budget Electron enforces inside it — the plugin tool budget (110s), and the widest
  MCP leg: a lazy handshake (10s) plus the whole tools/list traversal (30s) plus the
  call (100s)」，目的正是「so the innermost layer reports its own timeout instead of
  being cut off here」。
• plugin-mcp.ts:11 的注释同样说明 100s 是「Kept under the plugin tool budget so the
  MCP error wins the race」。
• docs/spec/06-delivery/04-e2e-test-plan.md:14607 与
  docs/spec/07-plugins/12-plugin-ipc-and-host-services.md:242 记录同一个 140s/150s 等式。

结论：callTimeoutMs 必须封顶 100s。 若允许用户设成 150s，140s 会变成 190s > 150s，
链条断裂：host-core 先报 TOOL_TIMEOUT，MCP 层永远报不出自己的错，用户拿到的是
一个无法定位的通用超时 —— 恰好比现在的 bug 更难诊断。要突破 100s，必须同时上移
Rust + shared 两处镜像常量，属跨语言架构改动，不该塞进这个 PR。

3.3 因此配置项的真实价值是「调小」和「预留」

• 调小：本地快工具不必干等 100s，可设 10s 快速失败并重试。
• 预留：为将来 > 100s 的超长工具留扩展点（需配套 §3.2 的链条调整）。

[hui455]

感谢详细分析，这个问题应该已经在 #1003 中修复，并且目前已经合并到 main。不过这个修复目前还没有包含在 v0.15.6 里，需要等下个版本