pi-mcp-extension 1.11.4 → 1.11.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.11.4",
+  "version": "1.11.5",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [

package/src/connect-policy.ts

@@ -3,6 +3,8 @@
  *
  * Owns:
  *   - Pure OAuth 401/403 connect and tool error detection (`isOAuthUnauthorizedError`)
+ *   - Pure SDK request-timeout detection (`isSdkTimeoutError`) and cancellation detection
+ *     (`isCancellationError`)
  *   - Fixed retry backoff schedule (`RETRY_DELAYS_MS`)
  *   - Connect-failure classification into retry, auth-required, fast-fail, give-up, or cancelled (`classifyConnectFailure`)
  */
@@ -138,6 +140,59 @@ export function isOAuthUnauthorizedError(error: unknown, seen = new Set<unknown>
 /** Fixed retry delay schedule — predictable, no jitter math needed. */
 export const RETRY_DELAYS_MS = [1000, 3000, 5000, 10000, 30000] as const;
 
+/** Message text of an error-ish value, preferring a real `message` field over `String()`. */
+function errorMessageOf(err: unknown): string {
+  // WHY: transports reject with plain `{ code, message, data }` objects too, where
+  // `String(err)` is "[object Object]" and the message would be lost.
+  const message = (err as { message?: unknown } | null)?.message;
+  return typeof message === "string" ? message : String(err);
+}
+
+/**
+ * Whether `err` is the MCP SDK's own request-timeout rejection.
+ *
+ * The SDK rejects a timed-out `initialize`, `tools/list`, or `tools/call` with **its**
+ * `McpError` carrying the numeric JSON-RPC code `ErrorCode.RequestTimeout` (-32001) —
+ * a different class from pi-mcp's own {@link McpError}, so an `instanceof McpError`
+ * check here only excludes codes this extension already decided on. Any layer that
+ * re-wraps an SDK error must keep the timeout distinction: `classifyConnectFailure`
+ * fast-fails an error coded `"protocol"`, which would turn a transient discovery
+ * timeout into a first-attempt failure with no retries.
+ */
+export function isSdkTimeoutError(err: unknown): boolean {
+  // WHY: our own McpError already carries a deliberate code; never re-derive it from
+  // the message (e.g. "Connection timed out after 5000ms" is already code "timeout").
+  if (err instanceof McpError) return false;
+  const code = (err as { code?: unknown } | null)?.code;
+  // WHY: a negative numeric code is a JSON-RPC error code, and a server error response
+  // arrives with its own (e.g. ErrorCode.InternalError = -32603) plus a message that may
+  // well say "timed out". Only the SDK's own RequestTimeout means the client gave up on
+  // the server, so no other negative code may fall through to the message heuristic.
+  if (typeof code === "number" && code < 0) return code === -32001;
+  return /Request timed out|timed out/i.test(errorMessageOf(err));
+}
+
+/**
+ * Whether `err`/`signal` are our own cancellation rather than a failure of the server.
+ *
+ * The SDK's `Protocol.request` rejects an in-flight request on abort as
+ * `McpError(ErrorCode.RequestTimeout, String(signal.reason))` — carrying the *timeout* code
+ * for a caller cancellation (`cancel()` in the SDK is shared by the timeout handler and the
+ * abort listener). Anything that classifies an SDK error must therefore test cancellation
+ * first, or a cancelled tool call is reported as a server timeout.
+ */
+export function isCancellationError(err: unknown, signal?: AbortSignal | undefined): boolean {
+  // WHY: the caller's own abort is authoritative — it survives the SDK rewrapping the reason.
+  if (signal?.aborted || err instanceof AuthCancelledError) return true;
+  if (!(err instanceof Error)) return false;
+  // WHY: fallback for an abort-shaped rejection that arrives without our signal — the SDK's
+  // abort listener sets `signal.aborted` before rejecting, so this leg only matters when the
+  // rejection came from a signal we were never handed (or a transport-level abort). Still
+  // narrow on purpose: only a -32001 carrier is inspected, so a JSON-RPC error response whose
+  // message merely mentions "aborted" keeps its own class.
+  return err.name === "AbortError" || ((err as { code?: unknown }).code === -32001 && /abort/i.test(err.message));
+}
+
 export type TransportType = ServerConfig["transport"];
 
 export type ConnectFailureAction =

package/src/errors.ts

@@ -9,7 +9,7 @@ export type McpErrorCode =
   | "connection"  // Transport/connection failed
   | "auth"        // Authentication/authorization failed
   | "timeout"     // Request or connection timed out
-  | "protocol"    // JSON-RPC protocol violation (server error response, timeout, etc.)
+  | "protocol"    // JSON-RPC protocol violation (a server error response, a malformed payload, or a call the caller cancelled)
   | "tool";       // Tool execution error (isError: true from server)
 
 export class McpError extends Error {

package/src/index.ts

@@ -406,10 +406,15 @@ function formatMcpAuthError(err: unknown, hasUI: boolean): string | undefined {
   return undefined;
 }
 
-function formatMcpProtocolOrGenericError(err: unknown): string {
+function formatMcpConnectFailureMessage(err: unknown): string {
   if (err instanceof McpError && err.code === "protocol") {
     return "MCP tool discovery failed. Check the server and retry.";
   }
+  // WHY: a request timeout means the server was reachable but too slow, so pointing at the
+  // configuration would send the user down the wrong path (#209).
+  if (err instanceof McpError && err.code === "timeout") {
+    return "MCP server did not respond in time. Check that it is running and retry.";
+  }
   return "MCP connection failed. Check the server configuration and retry.";
 }
 
@@ -420,7 +425,7 @@ function formatMcpConnectError(err: unknown, options: McpConnectErrorOptions): s
   if (!options.serverExists) {
     return "Unknown MCP server name. Use mcp_status to list configured servers.";
   }
-  return formatMcpAuthError(err, options.hasUI) ?? formatMcpProtocolOrGenericError(err);
+  return formatMcpAuthError(err, options.hasUI) ?? formatMcpConnectFailureMessage(err);
 }
 
 function registerManagementTools(

package/src/server-manager.ts

@@ -38,6 +38,7 @@ import { createTransport } from "./transport-factory.js";
 import {
   classifyConnectFailure,
   isOAuthUnauthorizedError,
+  isSdkTimeoutError,
   type ConnectFailureAction,
 } from "./connect-policy.js";
 
@@ -182,13 +183,6 @@ function createConnectRaceGuard(
   return { outcome, dispose };
 }
 
-function isSdkTimeoutError(err: unknown): boolean {
-  if (err instanceof McpError) return false;
-  if ((err as { code?: unknown } | null)?.code === -32001) return true;
-  const message = err instanceof Error ? err.message : String(err);
-  return /Request timed out|timed out/i.test(message);
-}
-
 function rethrowNormalizedConnectError(
   err: unknown,
   signal: AbortSignal,

package/src/tool-bridge.ts

@@ -18,7 +18,7 @@ import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { McpError, AuthCancelledError } from "./errors.js";
 import type { Settings } from "./config.js";
-import { isOAuthUnauthorizedError } from "./server-manager.js";
+import { isCancellationError, isOAuthUnauthorizedError, isSdkTimeoutError } from "./connect-policy.js";
 import { convertJsonSchemaToTypebox } from "./schema-convert.js";
 import { listAllTools, type McpToolDefinition } from "./tool-discovery.js";
 
@@ -353,8 +353,9 @@ export class ToolBridge {
   }
 
   /**
-   * Discover a server's tools, normalizing aborts into {@link AuthCancelledError}
-   * and every other failure into an `McpError("protocol")`.
+   * Discover a server's tools, normalizing aborts into {@link AuthCancelledError},
+   * SDK request timeouts into `McpError("timeout")`, and every other failure into
+   * `McpError("protocol")`.
    */
   private async _fetchToolsForServer(
     serverName: string,
@@ -365,20 +366,20 @@ export class ToolBridge {
     try {
       return await listAllTools(client, effectiveTimeoutMs, effectiveSignal, serverName);
     } catch (err) {
-      if (
-        err instanceof AuthCancelledError ||
-        effectiveSignal?.aborted ||
-        (err instanceof Error && err.name === "AbortError")
-      ) {
+      if (isCancellationError(err, effectiveSignal)) {
         throw err instanceof AuthCancelledError ? err : new AuthCancelledError(serverName);
       }
       if (isOAuthUnauthorizedError(err)) {
         await this.onAuthError?.(serverName, err);
       }
+      // WHY: an SDK request timeout is retryable — `classifyConnectFailure` fast-fails on
+      // "protocol", so mislabelling it would skip `maxRetries` and report a discovery
+      // timeout as a protocol violation (#209).
+      const code = isSdkTimeoutError(err) ? "timeout" : "protocol";
       throw new McpError(
         `Failed to list tools from ${serverName}: ${err instanceof Error ? err.message : String(err)}`,
         serverName,
-        "protocol",
+        code,
         err,
       );
     }
@@ -482,11 +483,13 @@ export class ToolBridge {
           if (isOAuthUnauthorizedError(err)) {
             await notifyAuthError(err);
           }
-          // Protocol-level errors (JSON-RPC error response, timeout, etc.)
+          // Protocol-level errors (JSON-RPC error response, malformed payload) keep
+          // "protocol"; an SDK request timeout keeps its own code so callers can tell
+          // "the server answered badly" from "the server did not answer in time" (#209).
           throw new McpError(
             err instanceof Error ? err.message : String(err),
             serverName,
-            "protocol",
+            isSdkTimeoutError(err) ? "timeout" : "protocol",
             err,
           );
         }
@@ -509,13 +512,24 @@ export class ToolBridge {
       throw new McpError("Tool execution cancelled", serverName, "protocol");
     }
 
-    const result = await callToolWithClient(
-      client,
-      toolName,
-      params,
-      this.serverTimeouts.get(serverName) ?? this.settings.requestTimeoutMs,
-      signal,
-    );
+    let result: ToolCallResponse;
+    try {
+      result = await callToolWithClient(
+        client,
+        toolName,
+        params,
+        this.serverTimeouts.get(serverName) ?? this.settings.requestTimeoutMs,
+        signal,
+      );
+    } catch (err) {
+      // WHY: an abort mid-call is rejected by the SDK with its RequestTimeout error, so the
+      // cancellation has to be recognised here — otherwise a caller cancellation is reported
+      // as a server timeout, and blamed on the server (#209).
+      if (isCancellationError(err, signal)) {
+        throw new McpError("Tool execution cancelled", serverName, "protocol");
+      }
+      throw err;
+    }
     const content = buildToolCallContent(result);
 
     // Tool execution errors (isError: true) — distinct from protocol errors