pi-mcp-extension 1.11.4 → 1.11.6

package/README.md

@@ -163,7 +163,7 @@ For Pi 1.x compatibility, server entries also accept `type` as an alias for `tra
 | `cwd` | `string` | session working directory | Working directory for a `stdio` server (rejected on `streamable-http` / `sse`). A relative path resolves against the session working directory and a leading `~` expands to your home directory |
 | `env` | `Record<string, string>` | — | Extra environment variables for the child process (literal values, no `${VAR}` interpolation) |
 | `url` | `string` | — | Server URL (**required** for `streamable-http` and `sse`) |
-| `headers` | `Record<string, string>` | — | Static headers sent with `streamable-http` and `sse` requests |
+| `headers` | `Record<string, string>` | — | Static headers sent with `streamable-http` and `sse` requests. When `auth` is set, OAuth owns `Authorization`, so an `Authorization` entry here is ignored (other headers still apply) |
 | `auth` (or `oauth`) | `object` | — | OAuth 2.1 configuration described below and in [OAUTH.md](./OAUTH.md) (`streamable-http` / `sse` only) |
 | `lifecycle` | `"eager" \| "lazy"` | `"lazy"` (`"eager"` for `pi.registerMcpServer()` unless `enabled: false`) | `eager` = auto-start on `session_start`, `lazy` = connect on request via `mcp_connect`, `/mcp:start`, or `/mcp:auth` |
 | `enabled` | `boolean` | `true` | Pi 1.3.0 switch: `false` keeps the entry configured but out of the eager set (normalized to `lifecycle: "lazy"`, even when `lifecycle: "eager"` is also set) |

package/package.json

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

package/src/auth-challenge.ts

@@ -20,6 +20,31 @@ export interface ManualAuthChallengeOptions {
   signal?: AbortSignal | undefined;
 }
 
+/**
+ * Drop any `Authorization` header (any casing) from a configured static header set.
+ *
+ * WHY: `Authorization` is the one header an OAuth server owns. The MCP SDK builds it from the
+ * OAuth provider's access token and then spreads `requestInit.headers` on top, so an exact-case
+ * `Authorization` key silently replaces the token, while `authorization` in any other casing
+ * survives as a second entry that `new Headers()` comma-joins into one malformed value. The same
+ * static value would also ride along on the OAuth discovery, registration, and token requests
+ * made through `createHeadersFetch`, leaking a resource-server credential to the authorization
+ * server. Drop it (and only it) whenever OAuth is configured; every other static header
+ * (tenant keys, gateways) still applies.
+ */
+export function stripAuthorizationHeader(
+  headers: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!headers) return undefined;
+  const kept = Object.entries(headers).filter(([name]) => !isAuthorizationHeader(name));
+  return kept.length > 0 ? Object.fromEntries(kept) : undefined;
+}
+
+/** Case-insensitive test for the single header an OAuth server owns. */
+export function isAuthorizationHeader(name: string): boolean {
+  return name.toLowerCase() === "authorization";
+}
+
 /**
  * Wrap a fetch implementation so configured server headers are attached as
  * defaults on every request (e.g. during SDK OAuth metadata discovery and

package/src/authorize-flow.ts

@@ -9,6 +9,7 @@ import { isSafeAuthorizationUrl } from "./callback-url.js";
 import {
   discoverManualAuthChallenge,
   createHeadersFetch,
+  stripAuthorizationHeader,
   type ManualAuthChallenge,
 } from "./auth-challenge.js";
 import {
@@ -629,16 +630,22 @@ export async function authorize(
     // if empty, which the callback server then rejects as a CSRF error.
     authProvider.setState(oauthState);
 
+    // WHY: `Authorization` belongs to the OAuth flow here. Filter the same set the transport
+    // uses, so this flow's own challenge probe and its SDK `fetchFn` (metadata, registration,
+    // token) never carry a static credential that was configured for the MCP server — the
+    // authorization server is usually a different origin.
+    const staticHeaders = stripAuthorizationHeader(config.headers);
+
     const authChallenge = await discoverChallengeWithFallback({
       serverName,
       serverUrl,
-      headers: config.headers,
+      headers: staticHeaders,
       signal,
     });
     assertActive();
 
     const callbackPromise = registerCallbackPromise(callbackServer, oauthState);
-    const customFetch = config.headers ? createHeadersFetch(config.headers) : undefined;
+    const customFetch = staticHeaders ? createHeadersFetch(staticHeaders) : undefined;
 
     const authResult = await runInitialSdkAuth(
       authProvider,

package/src/config.ts

@@ -187,7 +187,9 @@ export const ServerConfigSchema = z.preprocess(
       /**
        * Static HTTP headers to include with every request (streamable-http / sse only).
        * Useful for API-key-based auth (e.g. { "Authorization": "Bearer <key>" }).
-       * For OAuth2, use the "auth" field instead.
+       * For OAuth2, use the "auth" field instead: when "auth" is set, OAuth owns the
+       * Authorization header and any Authorization entry here is ignored (other headers
+       * still apply).
        */
       headers: z.record(z.string(), z.string()).optional(),
       /**

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

package/src/transport-factory.ts

@@ -16,6 +16,8 @@ import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.
 import { McpError } from "./errors.js";
 import type { ServerConfig } from "./config.js";
 import { McpOAuthProvider } from "./oauth-provider.js";
+import { isAuthorizationHeader, stripAuthorizationHeader } from "./auth-challenge.js";
+import { reportDiagnostic } from "./debug-log.js";
 import { createLineSplitter } from "./stdio-process.js";
 import { sanitizeTerminalText } from "./terminal-text.js";
 
@@ -32,9 +34,9 @@ function resolveEnv(extra?: Record<string, string>): Record<string, string> {
   return env;
 }
 
-function createRequestInit(config: ServerConfig): RequestInit | undefined {
+function createRequestInit(headers: Record<string, string> | undefined): RequestInit | undefined {
   // Build requestInit for static headers (API keys, etc.)
-  return config.headers ? { headers: config.headers } : undefined;
+  return headers ? { headers } : undefined;
 }
 
 function createOAuthProvider(
@@ -188,7 +190,18 @@ export function createTransport(
 ): Transport {
   const cwd = typeof cwdOrOnStderr === "string" ? cwdOrOnStderr : cwdArg;
   const onStderr = typeof cwdOrOnStderr === "function" ? cwdOrOnStderr : undefined;
-  const requestInit = createRequestInit(config);
+  // WHY: with OAuth configured the SDK owns `Authorization` (see stripAuthorizationHeader);
+  // a leftover static header is a migration artifact, so drop it and record that we did.
+  const staticHeaders = config.auth ? stripAuthorizationHeader(config.headers) : config.headers;
+  if (config.auth && config.headers && Object.keys(config.headers).some(isAuthorizationHeader)) {
+    reportDiagnostic({
+      level: "info",
+      event: "config.static_authorization_ignored",
+      server: serverName,
+      message: `Ignoring the static Authorization header for "${serverName}": OAuth is configured, so requests carry the OAuth access token instead.`,
+    });
+  }
+  const requestInit = createRequestInit(staticHeaders);
   const authProvider = createOAuthProvider(serverName, config, storageDir);
 
   switch (config.transport) {