@epoch-agent/plugin-mcp 0.4.0 → 0.5.0

package/README.md

@@ -126,6 +126,12 @@ snake_case 和 camelCase 两种写法都收。**未知字段会进启动诊断**
 - `tools/list` annotations + title 透传到 `EpochTool.annotations`（权限系统消费）
 - schema 缓存：内存优先，磁盘（0600）作降级；按连接配置指纹失效
 - 看门狗式重连：断连**不阻塞**工具调用，重连在后台按 1s/2s/4s 退避
+- **取消得掉**：`ToolContext.signal` 一路递到 SDK 的 `RequestOptions.signal`，
+  用户按停时 server 当场收到 `notifications/cancelled`（见下面那一节）
+- **`timeout` 对每一条请求都算数**：`tools/call` / `tools/list` / `resources/*` /
+  `prompts/*` 用的是同一个 `McpClient.requestOptions()`。
+  ⚠️ `resources/list` 这种翻页的是**逐页**给 —— SDK 的超时按请求算，只给第一页的话
+  第二页起又落回它那个 60 秒默认值
 - keepalive 心跳、idle 超时断开、最大生命周期
 - **OAuth**（`oauth/`）：`epoch mcp login` / `logout` 的后端，本机回调 server +
   token 刷新（带 skew）+ 0600 存储。认证过不去时置 `needsLogin`——重连解决不了
@@ -149,6 +155,28 @@ method-not-found **当空**处理——有些 server 声明了 capability 却没
 resources 包成工具而不是注入上下文：一个 server 挂几十份文档是常态，全量注入等于
 每一轮都为「模型多半用不到的东西」付 token；而工具是按需调用的，天然懒加载。
 
+## ⚠️ 写 MCP server 的人请处理 `notifications/cancelled`
+
+一次 `tools/call` 有两种结束不掉的方式，**两种我们都会发那条通知**：
+
+- 用户按停（`ToolContext.signal` → SDK 的 `RequestOptions.signal`）
+- `timeout` 到了（上面那张表里的 `timeout` 秒）
+
+通知的形状是 JSON-RPC 规范里那一条：
+
+```jsonc
+{ "method": "notifications/cancelled", "params": { "requestId": 2, "reason": "…" } }
+```
+
+**不认它的 server 会继续把活干完**，而客户端这侧已经没人在等了。实测过一趟真跑的
+代价：4 次 `invoke` → 后端 4 条「收流结束」一条不少，两份跑完的完整报告被扔掉，
+外加一次白烧的后端算力。用 SDK 写的 server 自动就有这个行为；**手写 JSON-RPC 的
+要自己接**（按 `requestId` 记一张在飞表，收到通知就中断那次活，且**取消之后
+result 和 error 都不发**）。
+
+⚠️ 这件事**不因为 `timeout` 配得多长而消失**：只要还有超时，「客户端放弃了而
+server 还在跑」这个窗口就一直在。
+
 ## 还没做
 
 `notifications/tools/list_changed` 收得到，但**不是热更新**：`AgentLoop` 的工具集是

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { ParseIssue } from '@epoch-agent/infra';
-import { ToolAnnotations, ToolArtifactInput, EpochTool } from '@epoch-agent/protocol';
+import { ToolAnnotations, ToolContext, ToolArtifactInput, EpochTool } from '@epoch-agent/protocol';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { OAuthClientInformationFull, OAuthTokens, OAuthClientMetadata, OAuthClientInformationMixed } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
 
 /**
@@ -390,6 +391,122 @@ declare class McpAuthStore {
  */
 declare function isExpired(entry: McpAuthEntry | undefined, now?: number): boolean;
 
+/**
+ * MCP 的另两个原语 —— resources 与 prompts。
+ *
+ * 之前只做了 tools 一个。这里只放**读取**逻辑，怎么暴露给模型 / 用户分别在
+ * `resource-tools.ts` 和 registry 的 `listPrompts()`。
+ *
+ * 三个共同点，都是从 gemini `packages/core/src/tools/mcp-client.ts` 的
+ * `listResources` 抄来的做法：
+ *
+ * 1. **先看 capability**。server 没声明 `resources` 就别问了 —— 问了多半得到
+ *    一个 `-32601 Method not found`，白跑一次往返还污染错误日志。
+ * 2. **翻页**。`resources/list` 和 `prompts/list` 都有 `nextCursor`，
+ *    不翻页就是「只有前 N 个」，而 N 由 server 决定，用户无从察觉。
+ * 3. **method-not-found 当空**。有些 server 声明了 capability 却没实现，
+ *    这种情况下「没有 resources」比「MCP 初始化失败」更贴近事实。
+ *
+ * ## 两个原语的**去处不一样**，这是刻意的
+ *
+ * - **resources → 包成工具**（`resource-tools.ts`：每个 server 一对
+ *   `mcp__<server>__list_resources` / `read_resource`）。不走「上下文注入」是因为
+ *   那条路只有两种走法，都不成立：全量塞（几个 server 就能把上下文吃光），
+ *   或者先猜模型需要哪些资源 —— 而「按需取」正是工具存在的意义。
+ * - **prompts → 不进工具表**，只有 registry 的 `listPrompts()` / `getPrompt()`，
+ *   **模型看不见**。判据在 MCP 规范里：**prompts 是 user-controlled、tools 是
+ *   model-controlled**。混进工具表等于让模型自己决定往自己的上下文里塞什么 ——
+ *   那不是「多一个工具」，是把一个由用户把关的入口改成由模型把关。
+ *   gemini 也把它放在用户侧（slash command）；我们的 TUI 入口还没做。
+ */
+
+/**
+ * ⚠️ **这四个函数的 `options` 一个都不能省**，`McpClient.requestOptions()` 是它唯一的
+ * 正当来源（2026-09-05）。
+ *
+ * 这个文件拿的是**裸 `Client`**，够不着 `McpServerConfig.timeout` —— 所以在补上这一格
+ * 之前，`resources/*` 和 `prompts/*` 全都吃 SDK 的 `DEFAULT_REQUEST_TIMEOUT_MSEC = 60000`，
+ * 而且没有取消入口。那正是 `callTool` 上刚修掉的那个 bug 的**同一份**，只是没人往
+ * 这条路上看：用户在 `mcp.json` 里写的 `timeout: 600` 对 `mcp__x__read_resource` 一直
+ * 是不生效的，按停也停不掉它。
+ *
+ * 收 `RequestOptions` 而不是收一个 `McpClient`：这一层是**纯读取**，不持有连接状态
+ * （文件头第一段），让它认识那个状态机等于把两件事又焊回去。
+ */
+type McpRequestOptions = RequestOptions;
+interface McpResourceInfo {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+}
+interface McpPromptInfo {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+declare function listResources(client: Client, options?: McpRequestOptions): Promise<McpResourceInfo[]>;
+declare function listPrompts(client: Client, options?: McpRequestOptions): Promise<McpPromptInfo[]>;
+/**
+ * 读一个 resource，压成纯文本。
+ *
+ * 二进制内容（`blob`）只留一行占位说明，不做 base64 透传 —— 那会把几 MB 的
+ * 图片塞进上下文，直接把方案 02 的成本闸门顶爆，而模型也读不懂那串字符。
+ * gemini 的 `read-mcp-resource.ts:145` 是同样的处理。
+ */
+declare function readResourceText(client: Client, uri: string, options?: McpRequestOptions): Promise<string>;
+/**
+ * 取一个 prompt 的消息内容，压成纯文本（给 CLI 展示 / 注入用）。
+ *
+ * 非文本那几支走 `convertMcpContent` 的同一套判别 —— 改造前这里是
+ * `JSON.stringify(content)`，和 tool result 那条路犯的是同一个错：
+ * prompt 里夹一张图，整张 base64 就进了展示文本和注入内容。
+ * 这里**不产生 artifact**：prompt 是给人看 / 拼进 system 的文本通道，
+ * 二进制在这条路上没有去处，只留一行占位。
+ */
+declare function getPromptText(client: Client, name: string, args?: Record<string, string>, options?: McpRequestOptions): Promise<string>;
+
+/**
+ * `McpToolSchema` → `EpochTool` 的适配。
+ *
+ * 单独一个文件是为了让「从缓存里重建工具」和「从 live 响应里重建工具」
+ * 走同一条代码路径 —— 两条路径分叉的话，缓存命中和不命中会得到不同的工具。
+ */
+
+/** MCP 工具名前缀。撞名交给 ToolRegistry 处理（先注册的胜出） */
+declare function prefixedName(serverName: string, toolName: string): string;
+/**
+ * 取消信号 —— `ToolContext.signal` 那一格，原样透传。
+ *
+ * 契约上它只保证有 `aborted` 一格（`protocol/src/tool.ts`），**不是** `AbortSignal`。
+ * 真要把它交给 SDK 得先过一道判别，判据全文在 `client.ts` 的 `sdkSignal()`。
+ */
+type CancelSignal = NonNullable<ToolContext['signal']>;
+type McpCall = (toolName: string, args: Record<string, unknown>, 
+/**
+ * 这一次调用的取消信号。**必须一路递到 `client.callTool` 的 `RequestOptions`** ——
+ * 断在任何一跳的表现都一样：用户按了停，UI 立刻回到可输入状态，而那次 MCP 调用
+ * 连同它背后的后端任务还在跑。判据在 {@link toEpochTool} 的 `execute` 上。
+ */
+signal?: CancelSignal) => Promise<{
+    success: boolean;
+    output: string;
+    artifacts?: ToolArtifactInput[];
+}>;
+/**
+ * 把一批 MCP 工具 schema 转成 EpochTool。
+ *
+ * annotations 直接透传，**不伪造默认值** —— server 没声明就是 undefined。
+ * 按 MCP 规范 annotations 全是「提示」，编造一个 `readOnlyHint: false`
+ * 会让权限系统（方案 04）把「未声明」和「明确声明有副作用」混为一谈。
+ * 参考 gemini-cli packages/core/src/tools/mcp-client.ts:1365。
+ */
+declare function toEpochTools(serverName: string, schemas: McpToolSchema[], call: McpCall): EpochTool[];
+
 /**
  * MCP 客户端 —— 连接状态机：握手、重连、保活 / 生存期 / 空闲计时器、工具调用。
  *
@@ -464,8 +581,34 @@ declare class McpClient {
      * **断线不在这里等重连**：以前这里 `await this.reconnect()`，而 reconnect 是
      * 1s + 2s + 4s 的 backoff 循环 —— 工具执行路径上最多阻塞 7 秒，用户看到的是
      * agent 卡住。现在改成排一次后台重连、立刻返回一条可重试的错误。
+     *
+     * ## ⚠️ `timeout` 必须走 SDK 的第三个参数，外面那层 `withTimeout` 不算数
+     *
+     * 这里原来只传了 `callTool` 的第一个参数，于是吃 SDK 的
+     * `DEFAULT_REQUEST_TIMEOUT_MSEC = 60000`（`shared/protocol.js`：
+     * `const timeout = options?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC`）——
+     * 外层那个 `withTimeout(config.timeout)` 永远轮不到，是**死代码**。
+     * 表现是 `McpServerConfig.timeout` 配成 600 也照样在 60.0 秒断，
+     * 报一句 `MCP error -32001: Request timed out`，而 server 那侧还在把活干完。
+     * 实测过一次 93 秒的正常 SSE 调用被这么判成失败、模型原样重试、
+     * 两份跑完的报告被扔掉。
+     *
+     * 同一个文件里 `connect()` **是给了的**（见 {@link connectInner} 里那段注释），
+     * 所以这不是「不知道有这个参数」，是漏在了 `callTool` / `listTools` 这两处。
+     *
+     * ## ⚠️ `signal` 和 `timeout` 是同一个 `RequestOptions` 的两格，缺哪一格都有后果
+     *
+     * 少了 `timeout`：上面那一段。少了 `signal`：**用户按停停不掉** —— 能结束一次
+     * 在飞调用的只剩 SDK 那个超时，UI 立刻回到可输入状态而后端还在跑。
+     * 而且两者相互放大：上限从 60 秒抬到 300 秒之后，「按了停但停不掉」的窗口
+     * 也跟着从 60 秒变成 300 秒。所以这两格是一起补的。
      */
-    callTool(name: string, args: Record<string, unknown>): Promise<McpToolCallResult>;
+    callTool(name: string, args: Record<string, unknown>, 
+    /**
+     * 这一次调用的取消信号，来自 `ToolContext.signal`（`toEpochTool` 那一跳递下来）。
+     * 不给就是没有取消入口 —— 与补这一格之前逐字相同。
+     */
+    signal?: CancelSignal): Promise<McpToolCallResult>;
     disconnect(): Promise<void>;
     /**
      * 建连。**握手成功之前不写 this.client**。
@@ -519,6 +662,17 @@ declare class McpClient {
      */
     private scheduleReconnect;
     private attemptReconnect;
+    /**
+     * 用户按停之后回给模型的那句话。
+     *
+     * ⚠️ 措辞上必须说清「是**用户**取消的」，不能只说「调用失败了」：模型对这两种的
+     * 处置正好相反 —— 失败它会重试，而重试一次用户刚刚亲手停掉的调用是这条路上
+     * 最贵的错。第 1 条那个 bug 的现场里模型就是这么原样重试的。
+     *
+     * 不带 `lastError`（`unavailableMessage()` 带）：那一格是「这台 server 怎么了」，
+     * 而这里 server 什么事都没有。
+     */
+    private cancelledMessage;
     private unavailableMessage;
     private startKeepalive;
     private pingOnce;
@@ -534,6 +688,41 @@ declare class McpClient {
     private resetIdle;
     private armDisconnect;
     private clearTimers;
+    /**
+     * 一次请求等多久（毫秒）—— `tools/call` 和 `tools/list` 共用这一个答案。
+     *
+     * 单独一个方法是为了**只有一处**在做「秒 → 毫秒」和「缺省值兜底」这两件事：
+     * 两处各算一遍的下场就是修完 `callTool` 之后 `listTools` 还在漏
+     * （那正是这个 bug 原来的形状）。
+     *
+     * ⚠️ `DEFAULTS.timeout = 300` 这个缺省值在这次改动之前是**没有意义的**
+     * （真实值恒为 SDK 的 60）。修完之后它才第一次生效 —— 所以这一改会**改变
+     * 现有行为**：今天所有跑得久的 MCP 工具都在 60 秒被切，之后变成 300 秒。
+     * 这是修不是回归，但它进了 changeset。
+     */
+    private requestTimeoutMs;
+    /**
+     * 一次请求交给 SDK 的 `RequestOptions` —— **timeout + signal 那两格的唯一来源**。
+     *
+     * ## 为什么是公开的
+     *
+     * `resources/*` 和 `prompts/*` 走的是 [primitives.ts](./primitives.ts)，那一层拿的是
+     * **裸 `Client`**、够不着 `this.config`。在补上这个方法之前它们因此**两格都没有**：
+     * 用户在 `mcp.json` 里写的 `timeout: 600` 对 `mcp__x__read_resource` 一直不生效
+     * （吃 SDK 的 60 秒），按停也停不掉它 —— 和 `callTool` 上刚修掉的是同一个 bug，
+     * 只是没人往那条路上看。
+     *
+     * 让它们**问这个方法**而不是各自去拼一份：两处各拼一份的下场，就是这个 bug 第一次
+     * 出现的方式（`connect()` 拼对了、`callTool` 漏了，两处谁也不知道对方存在）。
+     *
+     * ## ⚠️ 进度那三格不在这里
+     *
+     * `onprogress` / `resetTimeoutOnProgress` / `maxTotalTimeout` 只有 {@link callTool}
+     * 加，刻意的：那三格是给 SSE / 长任务类**工具**的，而 `resources/read` 和
+     * `prompts/get` 是一问一答，给它们塞一个 `progressToken` 是纯粹多出来的协议面
+     * （每次请求的 `params._meta` 多一格），换不回任何东西。
+     */
+    requestOptions(signal?: CancelSignal): McpRequestOptions;
     private withTimeout;
 }
 
@@ -711,71 +900,6 @@ declare class McpOAuthProvider implements OAuthClientProvider {
     private entry;
 }
 
-/**
- * MCP 的另两个原语 —— resources 与 prompts。
- *
- * 之前只做了 tools 一个。这里只放**读取**逻辑，怎么暴露给模型 / 用户分别在
- * `resource-tools.ts` 和 registry 的 `listPrompts()`。
- *
- * 三个共同点，都是从 gemini `packages/core/src/tools/mcp-client.ts` 的
- * `listResources` 抄来的做法：
- *
- * 1. **先看 capability**。server 没声明 `resources` 就别问了 —— 问了多半得到
- *    一个 `-32601 Method not found`，白跑一次往返还污染错误日志。
- * 2. **翻页**。`resources/list` 和 `prompts/list` 都有 `nextCursor`，
- *    不翻页就是「只有前 N 个」，而 N 由 server 决定，用户无从察觉。
- * 3. **method-not-found 当空**。有些 server 声明了 capability 却没实现，
- *    这种情况下「没有 resources」比「MCP 初始化失败」更贴近事实。
- *
- * ## 两个原语的**去处不一样**，这是刻意的
- *
- * - **resources → 包成工具**（`resource-tools.ts`：每个 server 一对
- *   `mcp__<server>__list_resources` / `read_resource`）。不走「上下文注入」是因为
- *   那条路只有两种走法，都不成立：全量塞（几个 server 就能把上下文吃光），
- *   或者先猜模型需要哪些资源 —— 而「按需取」正是工具存在的意义。
- * - **prompts → 不进工具表**，只有 registry 的 `listPrompts()` / `getPrompt()`，
- *   **模型看不见**。判据在 MCP 规范里：**prompts 是 user-controlled、tools 是
- *   model-controlled**。混进工具表等于让模型自己决定往自己的上下文里塞什么 ——
- *   那不是「多一个工具」，是把一个由用户把关的入口改成由模型把关。
- *   gemini 也把它放在用户侧（slash command）；我们的 TUI 入口还没做。
- */
-
-interface McpResourceInfo {
-    uri: string;
-    name?: string;
-    description?: string;
-    mimeType?: string;
-}
-interface McpPromptInfo {
-    name: string;
-    description?: string;
-    arguments?: Array<{
-        name: string;
-        description?: string;
-        required?: boolean;
-    }>;
-}
-declare function listResources(client: Client): Promise<McpResourceInfo[]>;
-declare function listPrompts(client: Client): Promise<McpPromptInfo[]>;
-/**
- * 读一个 resource，压成纯文本。
- *
- * 二进制内容（`blob`）只留一行占位说明，不做 base64 透传 —— 那会把几 MB 的
- * 图片塞进上下文，直接把方案 02 的成本闸门顶爆，而模型也读不懂那串字符。
- * gemini 的 `read-mcp-resource.ts:145` 是同样的处理。
- */
-declare function readResourceText(client: Client, uri: string): Promise<string>;
-/**
- * 取一个 prompt 的消息内容，压成纯文本（给 CLI 展示 / 注入用）。
- *
- * 非文本那几支走 `convertMcpContent` 的同一套判别 —— 改造前这里是
- * `JSON.stringify(content)`，和 tool result 那条路犯的是同一个错：
- * prompt 里夹一张图，整张 base64 就进了展示文本和注入内容。
- * 这里**不产生 artifact**：prompt 是给人看 / 拼进 system 的文本通道，
- * 二进制在这条路上没有去处，只留一行占位。
- */
-declare function getPromptText(client: Client, name: string, args?: Record<string, string>): Promise<string>;
-
 /**
  * MCP 注册中心 — 多 server 管理 [Hermes mcp_tool.py]。
  */
@@ -926,10 +1050,19 @@ declare class McpRegistry {
  * server 没声明 resources capability 时返回空数组 —— 给模型一个调了必然
  * 报错的工具，只会诱导它反复尝试。
  *
- * @param getClient 取当前连接。**不能捕获 Client 实例**：重连后 client 会换一个，
- *                  闭包里握着旧的就会一直往断掉的连接上打。
+ * @param owner 这台 server 的 {@link McpClient}。
+ *
+ * ⚠️ **收 `McpClient` 而不是 `() => Client | null`**（2026-09-05）。原来那个取值器
+ * 守的是一条真判据 —— 「**不能捕获 `Client` 实例**：重连后 client 会换一个，闭包里
+ * 握着旧的就会一直往断掉的连接上打」—— 而 `McpClient` 把那条守得**更**牢：
+ * 它本身跨重连是同一个对象，`client.raw` 每次现读。
+ *
+ * 换过来是因为光有连接不够：这两个工具还要 `timeout` 和 `signal`，而那两格的真源是
+ * `McpServerConfig`，只有 `McpClient` 够得着（判据全文在 `McpClient.requestOptions()`）。
+ * 拿裸 `Client` 的那个版本因此**两格都没有** —— 用户写的 `timeout: 600` 对
+ * `read_resource` 不生效（吃 SDK 的 60 秒），按停也停不掉它。
  */
-declare function createResourceTools(serverName: string, getClient: () => Client | null): EpochTool[];
+declare function createResourceTools(serverName: string, owner: McpClient): EpochTool[];
 
 /**
  * mcp.json 的校验与归一化。
@@ -953,28 +1086,4 @@ interface ParsedConfig {
  */
 declare function parseMcpConfig(raw: string, label: string): ParsedConfig;
 
-/**
- * `McpToolSchema` → `EpochTool` 的适配。
- *
- * 单独一个文件是为了让「从缓存里重建工具」和「从 live 响应里重建工具」
- * 走同一条代码路径 —— 两条路径分叉的话，缓存命中和不命中会得到不同的工具。
- */
-
-/** MCP 工具名前缀。撞名交给 ToolRegistry 处理（先注册的胜出） */
-declare function prefixedName(serverName: string, toolName: string): string;
-type McpCall = (toolName: string, args: Record<string, unknown>) => Promise<{
-    success: boolean;
-    output: string;
-    artifacts?: ToolArtifactInput[];
-}>;
-/**
- * 把一批 MCP 工具 schema 转成 EpochTool。
- *
- * annotations 直接透传，**不伪造默认值** —— server 没声明就是 undefined。
- * 按 MCP 规范 annotations 全是「提示」，编造一个 `readOnlyHint: false`
- * 会让权限系统（方案 04）把「未声明」和「明确声明有副作用」混为一谈。
- * 参考 gemini-cli packages/core/src/tools/mcp-client.ts:1365。
- */
-declare function toEpochTools(serverName: string, schemas: McpToolSchema[], call: McpCall): EpochTool[];
-
-export { CALLBACK_TIMEOUT_MS, type CallbackServer, type McpAuthEntry, type McpAuthFile, type McpAuthState, type McpAuthStatus, McpAuthStore, McpClient, type McpConfigLoadResult, type McpLoginOptions, McpLoginRequiredError, type McpLoginResult, type McpOAuthConfig, McpOAuthProvider, type McpOAuthProviderOptions, type McpPromptInfo, McpRegistry, type McpRegistryOptions, type McpResourceInfo, McpSchemaCache, type McpServerConfig, type McpServerSource, type McpServerStatus, type McpToolAnnotations, type McpToolSchema, type McpTransport, REFRESH_SKEW_MS, configFingerprint, createResourceTools, getPromptText, isExpired, listPrompts, listResources, loginToMcpServer, logoutFromMcpServer, mcpAuthStatus, parseMcpConfig, prefixedName, readResourceText, startCallbackServer, toEpochTools };
+export { CALLBACK_TIMEOUT_MS, type CallbackServer, type McpAuthEntry, type McpAuthFile, type McpAuthState, type McpAuthStatus, McpAuthStore, McpClient, type McpConfigLoadResult, type McpLoginOptions, McpLoginRequiredError, type McpLoginResult, type McpOAuthConfig, McpOAuthProvider, type McpOAuthProviderOptions, type McpPromptInfo, McpRegistry, type McpRegistryOptions, type McpRequestOptions, type McpResourceInfo, McpSchemaCache, type McpServerConfig, type McpServerSource, type McpServerStatus, type McpToolAnnotations, type McpToolSchema, type McpTransport, REFRESH_SKEW_MS, configFingerprint, createResourceTools, getPromptText, isExpired, listPrompts, listResources, loginToMcpServer, logoutFromMcpServer, mcpAuthStatus, parseMcpConfig, prefixedName, readResourceText, startCallbackServer, toEpochTools };

package/dist/index.js

@@ -81,7 +81,10 @@ function isDiskShape(value) {
 }
 // src/client.ts
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import {
+  CallToolResultSchema,
+  ToolListChangedNotificationSchema
+} from "@modelcontextprotocol/sdk/types.js";
 // src/content.ts
 var DEFAULT_MEDIA_TYPE = "application/octet-stream";
 function str(v) {
@@ -491,6 +494,12 @@ var DEFAULTS = {
 // src/client.ts
 var MAX_RECONNECT = 3;
 var RECONNECT_BACKOFF = [1e3, 2e3, 4e3];
+var OUTER_TIMEOUT_SLACK_MS = 5e3;
+var KEEPALIVE_TIMEOUT_MS = 1e4;
+function sdkSignal(signal) {
+  const maybe = signal;
+  return typeof maybe?.addEventListener === "function" ? signal : void 0;
+}
 var STDERR_TAIL_LINES = 20;
 var McpClient = class {
   config;
@@ -568,9 +577,10 @@ var McpClient = class {
     if (!this.client) return null;
     this.resetIdle();
     try {
+      const timeoutMs = this.requestTimeoutMs();
       const result = await this.withTimeout(
-        this.client.listTools(),
-        (this.config.timeout ?? DEFAULTS.timeout) * 1e3
+        this.client.listTools(void 0, { timeout: timeoutMs }),
+        timeoutMs + OUTER_TIMEOUT_SLACK_MS
       );
       return (result.tools ?? []).map((t10) => {
         const tool = t10;
@@ -587,16 +597,26 @@ var McpClient = class {
       return null;
     }
   }
-  async callTool(name, args) {
+  async callTool(name, args, signal) {
     if (!this.client) {
       this.scheduleReconnect();
       return { success: false, output: this.unavailableMessage() };
     }
+    if (signal?.aborted) {
+      return { success: false, output: this.cancelledMessage(name) };
+    }
     this.resetIdle();
     try {
+      const timeoutMs = this.requestTimeoutMs();
       const result = await this.withTimeout(
-        this.client.callTool({ name, arguments: args }),
-        (this.config.timeout ?? DEFAULTS.timeout) * 1e3
+        this.client.callTool({ name, arguments: args }, CallToolResultSchema, {
+          ...this.requestOptions(signal),
+          onprogress: () => {
+          },
+          resetTimeoutOnProgress: true,
+          maxTotalTimeout: timeoutMs
+        }),
+        timeoutMs + OUTER_TIMEOUT_SLACK_MS
       );
       const { text, artifacts } = convertMcpContent(result.content);
       return {
@@ -605,6 +625,9 @@ var McpClient = class {
         ...artifacts.length > 0 ? { artifacts } : {}
       };
     } catch (err) {
+      if (signal?.aborted) {
+        return { success: false, output: this.cancelledMessage(name) };
+      }
       const authHint = describeAuthFailure(err, this.config.name);
       if (authHint) {
         this.needsLogin = true;
@@ -713,6 +736,9 @@ var McpClient = class {
       this.startLifetime();
     }
   }
+  cancelledMessage(toolName) {
+    return `\u5DE5\u5177 ${toolName} \u7684\u8C03\u7528\u5DF2\u88AB\u7528\u6237\u53D6\u6D88\uFF08\u4E0D\u662F\u5931\u8D25\uFF09\u3002\u4E0D\u8981\u91CD\u8BD5\uFF0C\u7B49\u7528\u6237\u7684\u4E0B\u4E00\u53E5\u8BDD\u3002`;
+  }
   unavailableMessage() {
     if (this.needsLogin) {
       return this.lastError ?? `MCP server ${this.config.name} \u9700\u8981 OAuth \u767B\u5F55`;
@@ -733,7 +759,10 @@ var McpClient = class {
   async pingOnce() {
     if (!this.client) return;
     try {
-      await this.withTimeout(this.client.listTools(), 1e4);
+      await this.withTimeout(
+        this.client.listTools(void 0, { timeout: KEEPALIVE_TIMEOUT_MS }),
+        KEEPALIVE_TIMEOUT_MS
+      );
     } catch {
       this.lastError = "keepalive \u5931\u8D25";
       this.client = null;
@@ -779,6 +808,16 @@ var McpClient = class {
     this.lifetimeTimer = null;
     this.reconnectTimer = null;
   }
+  requestTimeoutMs() {
+    return (this.config.timeout ?? DEFAULTS.timeout) * 1e3;
+  }
+  requestOptions(signal) {
+    const forSdk = sdkSignal(signal);
+    return {
+      timeout: this.requestTimeoutMs(),
+      ...forSdk ? { signal: forSdk } : {}
+    };
+  }
   async withTimeout(promise, ms) {
     let timer;
     const timeout = new Promise((_, reject) => {
@@ -1031,22 +1070,22 @@ async function openInBrowser(url) {
 // src/primitives.ts
 var METHOD_NOT_FOUND = -32601;
 var MAX_PAGES = 50;
-async function listResources(client) {
+async function listResources(client, options) {
   if (!client.getServerCapabilities()?.resources) return [];
   return paginate(async (cursor) => {
-    const res = await client.listResources(cursor ? { cursor } : {});
+    const res = await client.listResources(cursor ? { cursor } : {}, options);
     return { items: res.resources ?? [], nextCursor: res.nextCursor };
   });
 }
-async function listPrompts(client) {
+async function listPrompts(client, options) {
   if (!client.getServerCapabilities()?.prompts) return [];
   return paginate(async (cursor) => {
-    const res = await client.listPrompts(cursor ? { cursor } : {});
+    const res = await client.listPrompts(cursor ? { cursor } : {}, options);
     return { items: res.prompts ?? [], nextCursor: res.nextCursor };
   });
 }
-async function readResourceText(client, uri) {
-  const result = await client.readResource({ uri });
+async function readResourceText(client, uri, options) {
+  const result = await client.readResource({ uri }, options);
   const parts = [];
   for (const content of result.contents ?? []) {
     if ("text" in content && typeof content.text === "string") {
@@ -1058,8 +1097,8 @@ async function readResourceText(client, uri) {
   }
   return parts.join("\n");
 }
-async function getPromptText(client, name, args = {}) {
-  const result = await client.getPrompt({ name, arguments: args });
+async function getPromptText(client, name, args = {}, options) {
+  const result = await client.getPrompt({ name, arguments: args }, options);
   return (result.messages ?? []).map((msg) => {
     const { text, artifacts } = convertMcpContent([msg.content]);
     const placeholders = artifacts.map(
@@ -1111,9 +1150,9 @@ function toEpochTool(serverName, schema, call) {
       properties: {}
     },
     annotations: schema.annotations ? stripTitle(schema.annotations) : void 0,
-    execute: async (args) => {
+    execute: async (args, ctx) => {
       const startedAt = performance.now();
-      const result = await call(schema.name, args);
+      const result = await call(schema.name, args, ctx.signal);
       return {
         success: result.success,
         output: result.output,
@@ -1132,19 +1171,18 @@ function stripTitle(annotations) {
 }
 // src/resource-tools.ts
 var MAX_LISTED = 200;
-function createResourceTools(serverName, getClient) {
-  const client = getClient();
-  if (!client?.getServerCapabilities()?.resources) return [];
+function createResourceTools(serverName, owner) {
+  if (!owner.raw?.getServerCapabilities()?.resources) return [];
   return [
     {
       name: prefixedName(serverName, "list_resources"),
       description: `\u5217\u51FA MCP server\u300C${serverName}\u300D\u63D0\u4F9B\u7684\u6240\u6709\u8D44\u6E90\uFF08URI + \u8BF4\u660E\uFF09\u3002\u60F3\u8BFB\u67D0\u4E2A\u8D44\u6E90\u7684\u5185\u5BB9\uFF0C\u518D\u8C03 ${prefixedName(serverName, "read_resource")}\u3002`,
       parameters: { type: "object", properties: {} },
       annotations: { readOnlyHint: true, openWorldHint: true },
-      execute: async () => {
+      execute: async (_args, ctx) => {
         return run(async () => {
-          const current = requireClient(getClient, serverName);
-          const resources = await listResources(current);
+          const current = requireClient(owner, serverName);
+          const resources = await listResources(current, owner.requestOptions(ctx.signal));
           if (resources.length === 0) return `${serverName} \u6CA1\u6709\u63D0\u4F9B\u4EFB\u4F55\u8D44\u6E90`;
           const shown = resources.slice(0, MAX_LISTED);
           const lines = shown.map(
@@ -1169,20 +1207,20 @@ function createResourceTools(serverName, getClient) {
         required: ["uri"]
       },
       annotations: { readOnlyHint: true, openWorldHint: true },
-      execute: async (args) => {
+      execute: async (args, ctx) => {
         return run(async () => {
           const uri = args["uri"];
           if (typeof uri !== "string" || uri.length === 0) throw new Error("\u7F3A\u5C11 uri \u53C2\u6570");
-          const current = requireClient(getClient, serverName);
-          const text = await readResourceText(current, uri);
+          const current = requireClient(owner, serverName);
+          const text = await readResourceText(current, uri, owner.requestOptions(ctx.signal));
           return text.length > 0 ? text : `\u8D44\u6E90 ${uri} \u6CA1\u6709\u53EF\u8BFB\u7684\u6587\u672C\u5185\u5BB9`;
         });
       }
     }
   ];
 }
-function requireClient(getClient, serverName) {
-  const client = getClient();
+function requireClient(owner, serverName) {
+  const client = owner.raw;
   if (!client) throw new Error(`MCP server ${serverName} \u5F53\u524D\u672A\u8FDE\u63A5`);
   return client;
 }
@@ -1385,8 +1423,10 @@ var McpRegistry = class {
     const allTools = [];
     for (const [name, client] of this.clients) {
       const schemas = await client.getToolSchemas();
-      allTools.push(...toEpochTools(name, schemas, (tool, args) => client.callTool(tool, args)));
-      allTools.push(...createResourceTools(name, () => client.raw));
+      allTools.push(
+        ...toEpochTools(name, schemas, (tool, args, signal) => client.callTool(tool, args, signal))
+      );
+      allTools.push(...createResourceTools(name, client));
     }
     return allTools;
   }
@@ -1396,12 +1436,12 @@ var McpRegistry = class {
   }
   async listPrompts(name) {
     const client = this.requireClient(name);
-    return client.raw ? listPrompts(client.raw) : [];
+    return client.raw ? listPrompts(client.raw, client.requestOptions()) : [];
   }
   async getPrompt(name, promptName, args = {}) {
     const client = this.requireClient(name);
     if (!client.raw) throw new Error(`MCP server "${name}" \u5F53\u524D\u672A\u8FDE\u63A5`);
-    return getPromptText(client.raw, promptName, args);
+    return getPromptText(client.raw, promptName, args, client.requestOptions());
   }
   getAuthStatus() {
     return [...this.clients.values()].map((c) => mcpAuthStatus(c.serverConfig, this.authStore));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-agent/plugin-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "epoch-agent MCP 客户端插件",
   "repository": {
@@ -23,8 +23,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3",
-    "@epoch-agent/infra": "0.4.0",
-    "@epoch-agent/protocol": "0.4.0"
+    "@epoch-agent/protocol": "0.5.0",
+    "@epoch-agent/infra": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",