pi-mcp-extension 1.9.7 → 1.9.8

package/README.md

@@ -183,8 +183,8 @@ Server-name arguments provide autocomplete suggestions from the configured MCP s
 | `/mcp <name>` | Show detailed status and stderr log for a specific server |
 | `/mcp:start <name>` | Connect a server and wait for tool discovery |
 | `/mcp:stop <name>` | Cancel a pending connection, startup prompt, or authorization, or stop a running server and deactivate its tools |
-| `/mcp:auth <name>` | Connect with stored OAuth credentials; request browser authorization only if needed |
-| `/mcp:auth <name> --reset` | Discard stored OAuth credentials and request fresh authorization |
+| `/mcp:auth <name>` | Connect with stored OAuth credentials and client registration; request browser authorization only if needed |
+| `/mcp:auth <name> --reset` | Discard stored tokens and client registration (re-running Dynamic Client Registration) and request fresh authorization |
 
 Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and connect one named server without routine slash commands. `mcp_status` reports lifecycle, connection state, discovered and active tool counts, credential presence, and safe action hints without returning tokens, headers, or authorization URLs. `mcp_connect` activates discovered tools before returning success. Connection failures return fixed actionable categories instead of raw server response text.
 
@@ -194,6 +194,7 @@ Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and
 - **Startup prompt for eager OAuth servers**: Silent startup and background reconnects never open a browser unprompted or trigger Dynamic Client Registration when no client credentials are stored. When an `eager` OAuth server needs interactive authorization at startup in an interactive Pi session, Pi presents a sequential `<name> needs authorization` prompt (`Authorize now` / `Not now`). Choosing `Authorize now` runs the interactive OAuth flow; choosing `Not now` leaves the server stopped, shows a `run /mcp:auth <name>` footer hint, and remembers the decline for the rest of the session.
 - **Headless and SSH support**: While authorization is pending, Pi displays the authorization URL and offers `Retry: open browser again`, `Paste redirect URL`, and `Cancel authentication`. On remote/SSH or headless machines, open the URL locally and either forward the callback port (`ssh -L <port>:127.0.0.1:<port>`) or paste the browser's final `http://127.0.0.1:<port>/callback?code=...&state=...` redirect URL into `Paste redirect URL`. Only `https:` (or loopback `http:`) authorization URLs are passed to the system browser opener.
 - **Coordinated connects and cross-process locks**: Concurrent connect requests join an in-flight attempt, while `--reset` supersedes a normal connect and shares one pending reset. Cross-process interactive flows are serialized per server via `<agent dir>/mcp-auth/<hash>.json.lock` with a 30s heartbeat and automatic reclamation of locks from dead local PIDs or stale heartbeats (>90s), while allowing silent token refreshes to persist rotated tokens.
+- **Resetting stale client registrations (`--reset`)**: `/mcp:auth <name>` reuses the cached Dynamic Client Registration (`clientInfo.client_id`) stored in `<agent dir>/mcp-auth/<hash>.json`. If an OAuth provider expires or purges a previously registered client—for example, when the browser displays `{"message":"Unrecognized client_id"}` or `invalid_client` on the authorization page without redirecting back to the local callback—run `/mcp:auth <name> --reset` to discard the cached `client_id`, register a new client via Dynamic Client Registration, and start a fresh authorization flow.
 
 ### Connection readiness and active tools
 
@@ -266,6 +267,9 @@ Implements the **MCP 2025-03-26** specification for tool clients:
 # Install dependencies
 npm install
 
+# Lint (type-aware ESLint)
+npm run lint
+
 # Type check (strict mode)
 npm run typecheck
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.9.7",
+  "version": "1.9.8",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [
@@ -33,7 +33,7 @@
     ]
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "^3.25.0"
   },
   "peerDependencies": {
@@ -42,13 +42,18 @@
     "typebox": "*"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
+    "eslint": "^10.13.0",
     "tsx": "^4.19.4",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.71.2"
   },
   "scripts": {
+    "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx/esm --test ./tests/*.test.ts",
+    "test:coverage": "node --import tsx/esm --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-lines=95 --test-coverage-branches=85 --test-coverage-functions=83 ./tests/*.test.ts",
     "test:integration": "node --import tsx/esm --test ./tests/server-manager.test.ts"
   }
 }

package/src/auth-lock.ts

@@ -171,6 +171,9 @@ export function parseLockRecord(raw: string): LockRecord | null {
     const result = LockRecordSchema.safeParse(parsed);
     return result.success ? result.data : null;
   } catch {
+    // WHY: JSON.parse on a string throws SyntaxError if the lock file is corrupt or
+    // partially written. LockRecordSchema.safeParse does not throw. Unparseable lock
+    // files map to null so isLockStale() can fall back to mtime-based staleness.
     return null;
   }
 }
@@ -312,7 +315,7 @@ export async function acquireAuthLock(
 
       process.once("exit", onExit);
 
-      heartbeatTimer = deps.clock.setInterval(async () => {
+      const heartbeatTick = async (): Promise<void> => {
         if (released || lost) return;
         const current = await readLockRecordWithRetry(deps.fs, path, usingRealFs);
         if (released || lost) return;
@@ -336,6 +339,9 @@ export async function acquireAuthLock(
             }
           }
         }
+      };
+      heartbeatTimer = deps.clock.setInterval(() => {
+        void heartbeatTick();
       }, HEARTBEAT_MS);
       heartbeatTimer.unref?.();
 

package/src/errors.ts

@@ -15,7 +15,7 @@ export type McpErrorCode =
 export class McpError extends Error {
   public readonly server: string;
   public readonly code: McpErrorCode;
-  public readonly cause: unknown;
+  public override readonly cause: unknown;
 
   constructor(
     message: string,

package/src/index.ts

@@ -362,7 +362,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
   let config: McpConfig = mergeWithRegisteredServers(fileConfig, extensionServers);
 
   // ── 2. Initialize bridge components ──────────────────────────────────────
-  const manager = new ServerManager(config, undefined, paths.authStorageDir);
+  const manager = new ServerManager(config, paths.authStorageDir);
   const bridge = new ToolBridge(config.settings, pi);
   const connectAttempts = new Map<string, { promise: Promise<void>; controller: AbortController; reset: boolean; waiters: number }>();
   const declinedStartupAuth = new Set<string>();
@@ -391,7 +391,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
             resolve();
           }
         },
-        (err) => {
+        (err: unknown) => {
           signal.removeEventListener("abort", onAbort);
           reject(err);
         },
@@ -513,7 +513,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
                   promptController.signal.removeEventListener("abort", onAbort);
                   resolve(value);
                 },
-                (err) => {
+                (err: unknown) => {
                   promptController.signal.removeEventListener("abort", onAbort);
                   if (promptController.signal.aborted) resolve(undefined);
                   else reject(err);
@@ -639,8 +639,8 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
       );
     }
   });
-  bridge.setAuthErrorCallback(async (serverName, err) => {
-    await manager.handleUnauthorizedServerError(serverName, err);
+  bridge.setAuthErrorCallback(async (serverName) => {
+    await manager.handleUnauthorizedServerError(serverName);
   });
 
   // ── 3. Session lifecycle ──────────────────────────────────────────────────
@@ -999,7 +999,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           if (signal.aborted) {
             throw new AuthCancelledError(serverName);
           }
-          console.warn(
+          console.error(
             `[pi-mcp] Failed to discover OAuth challenge for "${serverName}"; falling back to standard discovery`,
           );
           return {};

package/src/oauth-provider.ts

@@ -76,6 +76,9 @@ export function canonicalServerUrl(rawUrl: string): string {
     const path = u.pathname.length > 1 ? u.pathname.replace(/\/+$/, "") : u.pathname;
     return `${u.origin}${path}${u.search}`;
   } catch {
+    // WHY: new URL() throws TypeError per WHATWG URL spec on malformed or relative
+    // URL strings. Falling back to trimmed rawUrl allows graceful degradation for
+    // non-standard or unparseable URLs without crashing callers.
     return rawUrl.trim();
   }
 }
@@ -95,6 +98,9 @@ function isResourceCompatibleWithServerUrl(resource: string, expectedServerUrl:
     const cfgPath = cfg.pathname.endsWith("/") ? cfg.pathname : `${cfg.pathname}/`;
     return reqPath.startsWith(cfgPath);
   } catch {
+    // WHY: new URL() throws TypeError per WHATWG URL spec if canonicalServerUrl produced
+    // an invalid or relative URL. If either URL cannot be parsed into an absolute URL,
+    // they cannot be origin/path-compatible, so returning false is the safe fallback.
     return false;
   }
 }
@@ -108,6 +114,7 @@ interface StoredClientInfo {
   client_secret_expires_at: number | undefined;
   token_endpoint_auth_method: string | undefined;
   redirect_uris: string[] | undefined;
+  issuer: string | undefined;
 }
 
 interface StoredTokens {
@@ -118,6 +125,7 @@ interface StoredTokens {
   scope: string | undefined;
   /** ISO timestamp when tokens were saved (for expiry estimation). */
   saved_at: string | undefined;
+  issuer: string | undefined;
 }
 
 interface StoredState {
@@ -127,6 +135,11 @@ interface StoredState {
   discoveryState: OAuthDiscoveryState | undefined;
 }
 
+// WHY: Credentials persisted before SDK 1.31 (GHSA-6qxp-vccf-f47h) have no `issuer`
+// property. We allow `issuer: z.string().optional()` so legacy state loads gracefully;
+// the SDK binds them to the discovered authorization server on first successful use.
+// Unknown keys are stripped by z.object, so explicit schema inclusion is required to
+// persist and return the SDK's issuer stamp.
 const StoredClientInfoSchema = z.object({
   client_id: z.string(),
   client_secret: z.string().optional(),
@@ -134,6 +147,7 @@ const StoredClientInfoSchema = z.object({
   client_secret_expires_at: z.number().optional(),
   token_endpoint_auth_method: z.string().optional(),
   redirect_uris: z.array(z.string()).optional(),
+  issuer: z.string().optional(),
 });
 
 const StoredTokensSchema = z.object({
@@ -143,6 +157,7 @@ const StoredTokensSchema = z.object({
   expires_in: z.number().optional(),
   scope: z.string().optional(),
   saved_at: z.string().optional(),
+  issuer: z.string().optional(),
 });
 
 export const StoredStateSchema = z.object({
@@ -231,6 +246,7 @@ async function loadState(
           client_secret_expires_at: parsed.clientInfo.client_secret_expires_at,
           token_endpoint_auth_method: parsed.clientInfo.token_endpoint_auth_method,
           redirect_uris: parsed.clientInfo.redirect_uris,
+          issuer: parsed.clientInfo.issuer,
         }
       : undefined,
     tokens: parsed.tokens
@@ -241,6 +257,7 @@ async function loadState(
           expires_in: parsed.tokens.expires_in,
           scope: parsed.tokens.scope,
           saved_at: parsed.tokens.saved_at,
+          issuer: parsed.tokens.issuer,
         }
       : undefined,
     discoveryState,
@@ -340,9 +357,13 @@ export class McpOAuthProvider implements OAuthClientProvider {
   async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
     // If static credentials provided, use those
     if (this.authConfig.clientId) {
+      const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+      const boundIssuer =
+        state.clientInfo?.client_id === this.authConfig.clientId ? state.clientInfo.issuer : undefined;
       return {
         client_id: this.authConfig.clientId,
         ...(this.authConfig.clientSecret && { client_secret: this.authConfig.clientSecret }),
+        ...(boundIssuer !== undefined && { issuer: boundIssuer }),
       };
     }
     // Otherwise load from persisted DCR state
@@ -384,7 +405,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
           token_endpoint_auth_method: info.token_endpoint_auth_method,
         }),
         ...(info.redirect_uris !== undefined && { redirect_uris: info.redirect_uris }),
-      } as OAuthClientInformationMixed;
+        ...(info.issuer !== undefined && { issuer: info.issuer }),
+      };
     }
     if (this.silent) throw new AuthRequiredError(this.serverName);
     return undefined;
@@ -393,9 +415,88 @@ export class McpOAuthProvider implements OAuthClientProvider {
   // --- saveClientInformation (DCR) ---
 
   async saveClientInformation(clientInformation: OAuthClientInformationMixed): Promise<void> {
-    if (this.silent) throw new AuthRequiredError(this.serverName);
+    const issuerToBind =
+      typeof clientInformation.issuer === "string" ? clientInformation.issuer : undefined;
+
+    if (this.silent) {
+      const knownClientId = this.authConfig.clientId;
+      let handle: AuthLockHandle | undefined;
+      try {
+        handle = await acquireAuthLock(this.serverName, this.storageDir);
+        const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+        const storedClient = state.clientInfo;
+        const matchingId = knownClientId ?? storedClient?.client_id;
+        if (!matchingId || clientInformation.client_id !== matchingId) {
+          // WHY: Silent background connections must never execute Dynamic Client Registration
+          // for a new or different client_id without interactive user consent.
+          throw new AuthRequiredError(this.serverName);
+        }
+        if (storedClient?.issuer !== undefined && issuerToBind !== undefined && storedClient.issuer !== issuerToBind) {
+          // WHY: A stored client already bound to an authorization server issuer must never be
+          // re-bound to a different issuer. Switching authorization servers requires an explicit reset.
+          throw new McpError(
+            `OAuth client for "${this.serverName}" is already bound to authorization server ${storedClient.issuer} and cannot be bound to ${issuerToBind}. Run /mcp:auth ${this.serverName} --reset to re-authorize.`,
+            this.serverName,
+            "auth",
+          );
+        }
+        if (this.serverUrl) {
+          state.serverUrl = canonicalServerUrl(this.serverUrl);
+        }
+        if (storedClient) {
+          // WHY: Mirror silent saveTokens: pure issuer binding of the already-known client
+          // preserves all stored credentials and DCR metadata on disk while stamping issuer.
+          if (this.authConfig.clientId) {
+            storedClient.client_secret = undefined;
+          }
+          storedClient.issuer = issuerToBind ?? storedClient.issuer;
+        } else {
+          state.clientInfo = {
+            client_id: clientInformation.client_id,
+            client_secret: this.authConfig.clientId
+              ? undefined
+              : (this.authConfig.clientSecret ?? clientInformation.client_secret),
+            client_id_issued_at: undefined,
+            client_secret_expires_at: undefined,
+            token_endpoint_auth_method: undefined,
+            redirect_uris: undefined,
+            issuer: issuerToBind,
+          };
+        }
+        await saveState(this.serverName, state, this.storageDir, this.isCancelled);
+      } catch (err) {
+        if (err instanceof AuthRequiredError || err instanceof McpError) {
+          throw err;
+        }
+        // WHY: When another process holds the interactive auth lock (e.g. during an interactive
+        // /mcp:auth or --reset), acquireAuthLock fails fast. We skip this background binding
+        // without failing the refresh — the SDK will bind client information again on the next refresh.
+        if (!(err instanceof AuthLockError)) {
+          console.error(`[pi-mcp] Failed to persist OAuth client info for "${this.serverName}":`, err);
+        }
+      } finally {
+        await handle?.();
+      }
+      return;
+    }
+
+    if (this.isCancelled()) throw new AuthRequiredError(this.serverName, "Authorization cancelled");
     await this.assertLockHeld?.();
     const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+    if (
+      state.clientInfo?.client_id === clientInformation.client_id &&
+      state.clientInfo.issuer !== undefined &&
+      issuerToBind !== undefined &&
+      state.clientInfo.issuer !== issuerToBind
+    ) {
+      // WHY: A stamped client is never re-stamped with a different authorization server issuer.
+      // To switch authorization servers, credentials must be explicitly reset via /mcp:auth <server> --reset.
+      throw new McpError(
+        `OAuth client for "${this.serverName}" is already bound to authorization server ${state.clientInfo.issuer} and cannot be bound to ${issuerToBind}. Run /mcp:auth ${this.serverName} --reset to re-authorize.`,
+        this.serverName,
+        "auth",
+      );
+    }
     if (this.serverUrl) {
       state.serverUrl = canonicalServerUrl(this.serverUrl);
     }
@@ -407,18 +508,28 @@ export class McpOAuthProvider implements OAuthClientProvider {
     }>;
     state.clientInfo = {
       client_id: clientInformation.client_id,
-      client_secret: clientInformation.client_secret,
-      client_id_issued_at:
-        typeof fullInfo.client_id_issued_at === "number" ? fullInfo.client_id_issued_at : undefined,
-      client_secret_expires_at:
-        typeof fullInfo.client_secret_expires_at === "number" ? fullInfo.client_secret_expires_at : undefined,
-      token_endpoint_auth_method:
-        typeof fullInfo.token_endpoint_auth_method === "string"
+      client_secret: this.authConfig.clientId ? undefined : clientInformation.client_secret,
+      client_id_issued_at: this.authConfig.clientId
+        ? undefined
+        : typeof fullInfo.client_id_issued_at === "number"
+          ? fullInfo.client_id_issued_at
+          : undefined,
+      client_secret_expires_at: this.authConfig.clientId
+        ? undefined
+        : typeof fullInfo.client_secret_expires_at === "number"
+          ? fullInfo.client_secret_expires_at
+          : undefined,
+      token_endpoint_auth_method: this.authConfig.clientId
+        ? undefined
+        : typeof fullInfo.token_endpoint_auth_method === "string"
           ? fullInfo.token_endpoint_auth_method
           : undefined,
-      redirect_uris: Array.isArray(fullInfo.redirect_uris)
-        ? fullInfo.redirect_uris.map((u) => String(u))
-        : undefined,
+      redirect_uris: this.authConfig.clientId
+        ? undefined
+        : Array.isArray(fullInfo.redirect_uris)
+          ? fullInfo.redirect_uris.map((u) => String(u))
+          : undefined,
+      issuer: issuerToBind,
     };
     await this.assertLockHeld?.();
     await saveState(this.serverName, state, this.storageDir, this.isCancelled);
@@ -454,6 +565,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
     if (storedTokens.refresh_token !== undefined) tokens.refresh_token = storedTokens.refresh_token;
     if (storedTokens.expires_in !== undefined) tokens.expires_in = storedTokens.expires_in;
     if (storedTokens.scope !== undefined) tokens.scope = storedTokens.scope;
+    if (storedTokens.issuer !== undefined) tokens.issuer = storedTokens.issuer;
     return tokens as unknown as OAuthTokens;
   }
 
@@ -467,6 +579,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
       expires_in: tokens.expires_in,
       scope: tokens.scope,
       saved_at: new Date().toISOString(),
+      issuer: typeof tokens.issuer === "string" ? tokens.issuer : undefined,
     };
 
     if (this.silent) {

package/src/server-manager.ts

@@ -192,11 +192,6 @@ export type ToolRefreshCallback = (
 /** Called when background auto-recovery after a disconnect or health check fails. */
 export type RecoveryFailedCallback = (serverName: string, error: Error) => void;
 
-export interface TransportAuthCallbacks {
-  /** Legacy callback type. Background transport attempts never invoke this callback. */
-  onAuthRequired: (serverName: string, authorizationUrl: URL) => void | Promise<void>;
-}
-
 // ─── Transport Factory ────────────────────────────────────────────────────────
 
 export function createTransport(
@@ -310,7 +305,7 @@ export function createTransport(
               rejectPendingStart = null;
               resolve();
             },
-            (err) => {
+            (err: unknown) => {
               rejectPendingStart = null;
               reject(err);
             },
@@ -338,7 +333,7 @@ export class ServerManager {
   private onServerStopped: ((name: string) => void) | null = null;
   private onRecoveryFailed: RecoveryFailedCallback | null = null;
 
-  constructor(config: McpConfig, _authCallbacks?: TransportAuthCallbacks, private readonly storageDir?: string) {
+  constructor(config: McpConfig, private readonly storageDir?: string) {
     this.settings = config.settings;
     for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
       this.servers.set(name, {
@@ -443,7 +438,7 @@ export class ServerManager {
     * Mark an OAuth server as requiring re-authorization when a mid-session
     * request (tools/list or tools/call) fails with 401/403 insufficient_scope.
     */
-  async handleUnauthorizedServerError(name: string, _cause?: unknown): Promise<void> {
+  async handleUnauthorizedServerError(name: string): Promise<void> {
     const server = this.servers.get(name);
     if (!server || !server.config.auth || server.config.transport === "stdio") {
       return;
@@ -871,7 +866,7 @@ export class ServerManager {
       }
       if (server.config.healthCheckIntervalMs) {
         let pingInFlight = false;
-        server.healthCheckTimer = setInterval(async () => {
+        const runHealthCheck = async (): Promise<void> => {
           if (pingInFlight || server.state !== "ready" || !server.client || signal.aborted) {
             return;
           }
@@ -908,6 +903,10 @@ export class ServerManager {
               }),
             ]);
           } catch {
+            // WHY: Ping failure triggers background recovery if the server is still ready.
+            // The ping error is intentionally not kept on lastError because _recover() →
+            // _shutdown() synchronously resets lastError during teardown before any reader
+            // observes it; if reconnection fails, _recover() records the failure on lastError.
             if (server.state === "ready" && !signal.aborted) {
               void this._recover(server, server.cwd ?? cwd);
             }
@@ -917,6 +916,9 @@ export class ServerManager {
             }
             pingInFlight = false;
           }
+        };
+        server.healthCheckTimer = setInterval(() => {
+          void runHealthCheck();
         }, server.config.healthCheckIntervalMs);
       }
       // Unexpected transport close (e.g. the server subprocess crashes

package/src/tool-bridge.ts

@@ -110,7 +110,7 @@ function extractSchemaOptions(schema: Record<string, unknown>): Record<string, u
 
 function withSchemaOptions(schema: TSchema, opts: Record<string, unknown>): TSchema {
   if (Object.keys(opts).length === 0) return schema;
-  const clone = Object.defineProperties({}, Object.getOwnPropertyDescriptors(schema)) as TSchema;
+  const clone = Object.defineProperties<TSchema>({}, Object.getOwnPropertyDescriptors(schema));
   return Object.assign(clone, opts);
 }
 
@@ -566,6 +566,7 @@ export function convertJsonSchemaToTypebox(
       // rather than `Type.Record` (`patternProperties`), which Gemini and OpenAI reject.
       return Type.Object(props, objOpts);
     }
+    case undefined:
     default:
       return Type.Any(opts);
   }
@@ -678,7 +679,7 @@ export async function listAllTools(
       throw new AuthCancelledError(serverName);
     }
     if (pageCount >= MAX_PAGES) {
-      console.warn(
+      console.error(
         `[pi-mcp] tools/list pagination exceeded ${MAX_PAGES} pages, stopping. The server may be malfunctioning.`,
       );
       break;