pi-mcp-extension 1.3.1 → 1.5.0

package/package.json

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

package/src/callback-server.ts

@@ -0,0 +1,263 @@
+/**
+ * MCP OAuth Callback Server
+ *
+ * Simple HTTP server that handles OAuth callbacks from the authorization server.
+ * Uses Node.js http module for compatibility with no external dependencies.
+ */
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http";
+import { URL } from "url";
+
+interface PendingAuth {
+  resolve: (code: string) => void;
+  reject: (error: Error) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
+
+let server: Server | null = null;
+let actualServerPort: number | null = null;
+const pendingAuths = new Map<string, PendingAuth>();
+
+const DEFAULT_PORT = 19876;
+const CALLBACK_PATH = "/callback";
+const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+const HTML_SUCCESS = `<!DOCTYPE html>
+<html><head><title>Pi - Authorization Successful</title>
+<style>body{font-family:system-ui,-apple-system,sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#1a1a2e;color:#eee}
+.container{text-align:center;padding:2rem}h1{color:#4ade80;margin-bottom:1rem}p{color:#aaa}</style>
+</head><body>
+<div class="container"><h1>✓ Authorization Successful</h1><p>You can close this window and return to Pi.</p></div>
+<script>setTimeout(()=>window.close(),2000)</script>
+</body></html>`;
+
+const HTML_ERROR = (error: string) => `<!DOCTYPE html>
+<html><head><title>Pi - Authorization Failed</title>
+<style>body{font-family:system-ui,-apple-system,sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#1a1a2e;color:#eee}
+.container{text-align:center;padding:2rem}h1{color:#f87171;margin-bottom:1rem}p{color:#aaa}
+.error{color:#fca5a5;font-family:monospace;margin-top:1rem;padding:1rem;background:rgba(248,113,113,0.1);border-radius:.5rem;white-space:pre-wrap;word-break:break-word}</style>
+</head><body>
+<div class="container"><h1>✗ Authorization Failed</h1><p>An error occurred during authorization.</p><div class="error">${escapeHtml(error)}</div></div>
+</body></html>`;
+
+/**
+ * Escape HTML entities to prevent XSS attacks.
+ */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+/**
+ * Handle incoming HTTP requests to the callback server.
+ */
+function handleRequest(req: IncomingMessage, res: ServerResponse): void {
+  const url = new URL(req.url || "/", `http://${req.headers.host}`);
+
+  // Only handle the callback path
+  if (url.pathname !== CALLBACK_PATH) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+    return;
+  }
+
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+  const error = url.searchParams.get("error");
+  const errorDescription = url.searchParams.get("error_description");
+
+  // Enforce state parameter presence for CSRF protection
+  if (!state) {
+    const errorMsg = "Missing required state parameter - potential CSRF attack";
+    res.writeHead(400, { "Content-Type": "text/html" });
+    res.end(HTML_ERROR(errorMsg));
+    return;
+  }
+
+  // Handle OAuth errors
+  if (error) {
+    const errorMsg = errorDescription || error;
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(HTML_ERROR(errorMsg));
+    if (pendingAuths.has(state)) {
+      const pending = pendingAuths.get(state)!;
+      clearTimeout(pending.timeout);
+      pendingAuths.delete(state);
+      setTimeout(() => pending.reject(new Error(errorMsg)), 0);
+    }
+    return;
+  }
+
+  // Require authorization code
+  if (!code) {
+    res.writeHead(400, { "Content-Type": "text/html" });
+    res.end(HTML_ERROR("No authorization code provided"));
+    return;
+  }
+
+  // Validate state parameter
+  if (!pendingAuths.has(state)) {
+    const errorMsg = "Invalid or expired state parameter - potential CSRF attack";
+    res.writeHead(400, { "Content-Type": "text/html" });
+    res.end(HTML_ERROR(errorMsg));
+    return;
+  }
+
+  const pending = pendingAuths.get(state)!;
+
+  // Clear timeout and resolve the pending promise
+  clearTimeout(pending.timeout);
+  pendingAuths.delete(state);
+  pending.resolve(code);
+
+  res.writeHead(200, { "Content-Type": "text/html" });
+  res.end(HTML_SUCCESS);
+}
+
+/**
+ * Ensure the callback server is running.
+ * Scans forward for an available local port if the preferred port is busy.
+ *
+ * @param preferredPort - The preferred port to use (default: 19876)
+ * @returns The actual port the server is listening on
+ */
+export async function ensureCallbackServer(preferredPort: number = DEFAULT_PORT): Promise<number> {
+  if (server) {
+    // Already running, return the tracked actual port
+    if (actualServerPort !== null) {
+      return actualServerPort;
+    }
+    // Fallback: try to get the port from the server
+    const address = server.address();
+    if (address && typeof address === "object" && "port" in address) {
+      actualServerPort = address.port;
+      return address.port;
+    }
+    // If we still can't determine the port, return the preferred port
+    // (this shouldn't happen in practice)
+    return preferredPort;
+  }
+
+  const maxAttempts = 25; // Try up to 25 ports
+
+  for (let offset = 0; offset < maxAttempts; offset++) {
+    const candidatePort = preferredPort + offset;
+    const candidateServer = createServer(handleRequest);
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        candidateServer.once("error", (err: any) => {
+          reject(err);
+        });
+
+        // Bind to 127.0.0.1 explicitly (IPv4) to avoid issues with IPv6
+        candidateServer.listen(candidatePort, "127.0.0.1", () => {
+          resolve();
+        });
+      });
+
+      server = candidateServer;
+      actualServerPort = candidatePort;
+      server.unref(); // Don't block process exit
+      return candidatePort;
+    } catch (error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      await new Promise<void>((resolve) => {
+        candidateServer.close(() => resolve());
+      });
+
+      // If not EADDRINUSE, rethrow
+      if (nodeError.code !== "EADDRINUSE") {
+        throw error;
+      }
+    }
+  }
+
+  throw new Error(
+    `OAuth callback port ${preferredPort} is already in use and no free port was found in range ${preferredPort}-${preferredPort + maxAttempts - 1}`
+  );
+}
+
+/**
+ * Wait for a callback with the given OAuth state.
+ * Returns a promise that resolves with the authorization code.
+ *
+ * @param oauthState - The OAuth state parameter to wait for
+ * @param timeoutMs - Timeout in milliseconds (default: 5 minutes)
+ * @returns Promise that resolves with the authorization code
+ */
+export function waitForCallback(
+  oauthState: string,
+  timeoutMs: number = TIMEOUT_MS
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      if (pendingAuths.has(oauthState)) {
+        pendingAuths.delete(oauthState);
+        reject(new Error("OAuth callback timeout - authorization took too long"));
+      }
+    }, timeoutMs);
+
+    pendingAuths.set(oauthState, { resolve, reject, timeout });
+  });
+}
+
+/**
+ * Cancel a pending authorization by state.
+ *
+ * @param oauthState - The OAuth state to cancel
+ */
+export function cancelCallback(oauthState: string): void {
+  const pending = pendingAuths.get(oauthState);
+  if (pending) {
+    clearTimeout(pending.timeout);
+    pendingAuths.delete(oauthState);
+    pending.reject(new Error("Authorization cancelled"));
+  }
+}
+
+/**
+ * Stop the callback server and reject all pending authorizations.
+ */
+export async function stopCallbackServer(): Promise<void> {
+  if (server) {
+    await new Promise<void>((resolve) => {
+      server!.close(() => {
+        resolve();
+      });
+    });
+    server = null;
+    actualServerPort = null;
+  }
+
+  // Reject all pending auths (defer to allow any pending operations to complete)
+  const pendingList = Array.from(pendingAuths.entries());
+  pendingAuths.clear();
+  setTimeout(() => {
+    for (const [, pending] of pendingList) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("OAuth callback server stopped"));
+    }
+  }, 0);
+}
+
+/**
+ * Check if the callback server is running.
+ */
+export function isCallbackServerRunning(): boolean {
+  return server !== null;
+}
+
+/**
+ * Get the number of pending authorizations.
+ */
+export function getPendingAuthCount(): number {
+  return pendingAuths.size;
+}
+
+// Export constants for testing/config
+export { DEFAULT_PORT, CALLBACK_PATH, TIMEOUT_MS };

package/src/config.ts

@@ -17,6 +17,28 @@ import { McpError } from "./errors.js";
 
 // ─── Zod Schemas ──────────────────────────────────────────────────────────────
 
+const AuthConfigSchema = z.object({
+  /** Auth type. Currently only "oauth" is supported. Default: "oauth". */
+  type: z.enum(["oauth"]).default("oauth"),
+  /**
+   * Callback URL for the OAuth redirect.
+   * Default: auto-detected local callback server.
+   */
+  redirectUrl: z.string().optional(),
+  /**
+   * Optional scope to request during authorization.
+   */
+  scope: z.string().optional(),
+  /**
+   * Pre-registered client_id (skip dynamic client registration).
+   */
+  clientId: z.string().optional(),
+  /**
+   * Pre-registered client_secret.
+   */
+  clientSecret: z.string().optional(),
+});
+
 const ServerConfigSchema = z
   .object({
     /** Executable to spawn (e.g. "npx", "node", "uvx"). Required for stdio. */
@@ -36,6 +58,19 @@ const ServerConfigSchema = z
      * Must be a valid URL (e.g. "https://my-mcp-server.example.com/mcp").
      */
     url: z.string().url().optional(),
+    /**
+     * 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.
+     */
+    headers: z.record(z.string()).optional(),
+    /**
+     * OAuth2 configuration for servers that require authorization.
+     * When set, the transport will use the SDK's OAuth flow (discovery,
+     * dynamic client registration, PKCE, token refresh).
+     * Only applies to streamable-http and sse transports.
+     */
+    auth: AuthConfigSchema.optional(),
     /**
      * "eager" — start at session_start.
      * "lazy"  — start manually via /mcp:start command.
@@ -85,6 +120,7 @@ const McpConfigSchema = z.object({
 
 // ─── Public Types ─────────────────────────────────────────────────────────────
 
+export type AuthConfig = z.output<typeof AuthConfigSchema>;
 export type ServerConfig = z.output<typeof ServerConfigSchema>;
 export type Settings = z.output<typeof SettingsSchema>;
 export type McpConfig = z.output<typeof McpConfigSchema>;

package/src/index.ts

@@ -10,8 +10,43 @@
 import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { loadConfig } from "./config.js";
 import { ServerManager } from "./server-manager.js";
+import type { TransportAuthCallbacks } from "./server-manager.js";
 import { ToolBridge } from "./tool-bridge.js";
 import { McpError } from "./errors.js";
+import { exec } from "node:child_process";
+
+// OAuth imports
+import {
+  ensureCallbackServer,
+  waitForCallback,
+  cancelCallback,
+  stopCallbackServer,
+} from "./callback-server.js";
+import { setCallbackPort, McpOAuthProvider } from "./oauth-provider.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
+
+/**
+ * Open a URL in the user's default browser.
+ * Works on macOS, Linux, and Windows.
+ */
+function openBrowser(url: string): void {
+  const cmd = process.platform === "darwin"
+    ? `open "${url}"`
+    : process.platform === "win32"
+      ? `start "" "${url}"`
+      : `xdg-open "${url}"`;
+
+  exec(cmd, (err, stdout, stderr) => {
+    if (err) {
+      const errorMsg = `[pi-mcp] Failed to open browser: ${err.message}`;
+      console.error(errorMsg);
+      if (stderr) {
+        console.error(`[pi-mcp] Browser error output: ${stderr}`);
+      }
+    }
+  });
+}
 
 export default async function (pi: ExtensionAPI): Promise<void> {
   // ── 1. Load and validate config ──────────────────────────────────────────
@@ -35,7 +70,17 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   }
 
   // ── 2. Initialize bridge components ──────────────────────────────────────
-  const manager = new ServerManager(config);
+  // Auth callbacks — opens browser and notifies user when OAuth is needed
+  const authCallbacks: TransportAuthCallbacks = {
+    onAuthRequired: (serverName: string, authorizationUrl: URL): void => {
+      console.error(
+        `[pi-mcp] OAuth required for "${serverName}". Opening browser for authorization...`,
+      );
+      openBrowser(authorizationUrl.toString());
+    },
+  };
+
+  const manager = new ServerManager(config, authCallbacks);
   const bridge = new ToolBridge(config.settings, pi);
 
   // Connect tool refresh callback: called on connect and on list_changed
@@ -86,6 +131,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   });
 
   pi.on("session_shutdown", async (_event, _ctx: ExtensionContext) => {
+    // Stop the callback server
+    await stopCallbackServer().catch(() => {});
+
     // Deactivate all tools before shutting down servers
     for (const server of manager.getAllServers()) {
       bridge.deactivateServer(server.name);
@@ -167,4 +215,157 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       }
     },
   });
+
+  // ── 7. /mcp:auth — trigger OAuth authentication for a server ────────────────
+  pi.registerCommand("mcp:auth", {
+    description:
+      "Trigger OAuth authentication for a server. Resets credentials and opens browser for re-authorization. Usage: /mcp:auth <server-name>",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const serverName = args.trim();
+      if (!serverName) {
+        // List servers with auth config
+        const authServers = manager.getAllServers().filter((s) => s.config.auth);
+        if (authServers.length === 0) {
+          ctx.ui.notify(
+            "pi-mcp: No servers with OAuth configured. Add `auth: { type: \"oauth\" }` to a server in mcp.json.",
+            "error",
+          );
+          return;
+        }
+        const lines = authServers.map(async (s) => {
+          const status = await manager.getServerAuthStatus(s.name);
+          const authIcon = status?.hasTokens ? "\u2705 authenticated" : "\u274C not authenticated";
+          const savedInfo = status?.savedAt ? ` (since ${status.savedAt})` : "";
+          return `  ${s.name}: ${authIcon}${savedInfo}`;
+        });
+        const statusLines = await Promise.all(lines);
+        ctx.ui.notify(
+          [
+            "Usage: /mcp:auth <server-name>",
+            "",
+            "OAuth-enabled servers:",
+            ...statusLines,
+          ].join("\n"),
+          "info",
+        );
+        return;
+      }
+      const server = manager.getServer(serverName);
+      if (!server) {
+        ctx.ui.notify(`pi-mcp: No server named "${serverName}"`, "error");
+        return;
+      }
+      if (!server.config.auth) {
+        ctx.ui.notify(
+          `pi-mcp: Server "${serverName}" does not have OAuth configured. Add \`auth: { type: "oauth" }\` to its config in mcp.json.`,
+          "error",
+        );
+        return;
+      }
+
+      const config = server.config;
+      let oauthState: string | undefined;
+
+      try {
+        // Stop the server if running
+        if (server.state !== "stopped") {
+          bridge.deactivateServer(serverName);
+          await manager.stopServer(serverName);
+        }
+
+        // Validate that we have a server URL (required for OAuth)
+        if (!config.url) {
+          throw new McpError(
+            `Server "${serverName}" has OAuth configured but no URL. OAuth requires a URL-based server transport.`,
+            serverName,
+            "config",
+          );
+        }
+
+        // Reset all OAuth credentials (tokens, client info, PKCE, discovery)
+        await manager.resetServerAuth(serverName);
+
+        ctx.ui.notify(
+          `pi-mcp: Starting OAuth flow for ${serverName}...`,
+          "info",
+        );
+
+        // 1. Start the callback server
+        const port = await ensureCallbackServer();
+        setCallbackPort(port);
+
+        // 2. Generate a cryptographically secure state parameter for CSRF protection
+        oauthState = Array.from(crypto.getRandomValues(new Uint8Array(32)))
+          .map((b: number) => b.toString(16).padStart(2, "0"))
+          .join("");
+
+        // 3. Register the callback promise BEFORE opening the browser
+        const callbackPromise = waitForCallback(oauthState);
+
+        // 4. Create auth provider and transport
+        const authProvider = new McpOAuthProvider(
+          serverName,
+          config.auth || { type: "oauth" },
+          (url: URL) => {
+            console.error(`[pi-mcp] Opening browser for ${serverName}...`);
+            openBrowser(url.toString());
+          },
+        );
+
+        // CRITICAL FIX #1: Set the OAuth state on the provider before calling auth()
+        // This ensures the state parameter is included in the authorization URL
+        authProvider.setState(oauthState);
+
+        const transport = new StreamableHTTPClientTransport(
+          new URL(config.url),
+          { authProvider },
+        );
+
+        // 5. Start the auth flow - this will trigger redirectToAuthorization which opens the browser
+        // CRITICAL FIX #2: Check the return value of auth() instead of catching UnauthorizedError
+        // The SDK returns 'REDIRECT' when it needs browser interaction, not an error
+        const authResult = await auth(authProvider, { serverUrl: config.url });
+
+        if (authResult === "AUTHORIZED") {
+          // Auth succeeded without needing browser interaction (e.g., had valid tokens)
+          ctx.ui.notify(`pi-mcp: ${serverName} authenticated successfully!`, "info");
+        } else if (authResult === "REDIRECT") {
+          // Browser was opened, wait for the callback from the user
+          ctx.ui.notify(
+            `pi-mcp: Browser opened for ${serverName}. Complete authorization to continue...`,
+            "info",
+          );
+
+          // 6. Wait for the callback (this blocks until the user authorizes)
+          const code = await callbackPromise;
+
+          // 7. Complete the OAuth flow with the authorization code
+          await transport.finishAuth(code);
+
+          ctx.ui.notify(`pi-mcp: ${serverName} authenticated successfully!`, "info");
+        } else {
+          throw new McpError(
+            `Unexpected auth result: ${authResult}`,
+            serverName,
+            "protocol",
+          );
+        }
+
+        // 8. Close the transport (we'll create a new one when starting the server)
+        await transport.close().catch(() => {});
+
+        // 9. Start the server with fresh auth credentials
+        await manager.startServer(serverName, ctx.cwd);
+
+      } catch (err) {
+        const msg = err instanceof McpError ? err.userMessage : String(err);
+        ctx.ui.notify(`pi-mcp: Authentication failed for ${serverName} — ${msg}`, "error");
+
+        // Clean up on error
+        if (oauthState) {
+          cancelCallback(oauthState);
+        }
+      }
+    },
+  });
 }

package/src/oauth-provider.ts

@@ -0,0 +1,367 @@
+/**
+ * File-based OAuthClientProvider for MCP servers.
+ *
+ * Implements the full OAuth2 Authorization Code flow with PKCE and
+ * Dynamic Client Registration (RFC 7591) as required by the MCP spec.
+ *
+ * Token and client state are persisted per-server under ~/.pi/agent/mcp-auth/
+ * so they survive pi restarts without requiring re-authorization.
+ *
+ * Usage: config adds `auth: { ... }` to a server config. This module
+ * constructs an OAuthClientProvider and the transport factory wires it in.
+ */
+
+import type { OAuthClientProvider, OAuthDiscoveryState } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientMetadata, OAuthClientInformationMixed, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** Auth config in mcp.json server entry. Matches the Zod AuthConfigSchema in config.ts. */
+export interface AuthConfig {
+  /** Auth type. Currently only "oauth" is supported. */
+  type?: "oauth" | undefined;
+  /**
+   * Callback URL the OAuth server redirects to after authorization.
+   * Default: auto-detected local callback server.
+   */
+  redirectUrl?: string | undefined;
+  /**
+   * Optional scope to request during authorization.
+   */
+  scope?: string | undefined;
+  /**
+   * Pre-registered client_id (skip dynamic client registration).
+   */
+  clientId?: string | undefined;
+  /**
+   * Pre-registered client_secret.
+   */
+  clientSecret?: string | undefined;
+}
+
+// ─── Callback Server Port ───────────────────────────────────────────────────────
+
+let callbackPort = 19876;
+
+/** Set the callback server port. Called by the auth flow when the server starts. */
+export function setCallbackPort(port: number): void {
+  callbackPort = port;
+}
+
+/** Get the current callback server port. */
+export function getCallbackPort(): number {
+  return callbackPort;
+}
+
+// ─── Persistent State Types ───────────────────────────────────────────────────
+
+interface StoredClientInfo {
+  client_id: string;
+  client_secret: string | undefined;
+}
+
+interface StoredTokens {
+  access_token: string;
+  token_type: string | undefined;
+  refresh_token: string | undefined;
+  expires_in: number | undefined;
+  scope: string | undefined;
+  /** ISO timestamp when tokens were saved (for expiry estimation). */
+  saved_at: string | undefined;
+}
+
+interface StoredState {
+  clientInfo: StoredClientInfo | undefined;
+  tokens: StoredTokens | undefined;
+  codeVerifier: string | undefined;
+  discoveryState: OAuthDiscoveryState | undefined;
+}
+
+// ─── File helpers ─────────────────────────────────────────────────────────────
+
+const AUTH_DIR = join(homedir(), ".pi", "agent", "mcp-auth");
+
+function statePath(serverName: string): string {
+  // Hash the server name to avoid filesystem issues with special chars
+  const hash = createHash("sha256").update(serverName).digest("hex").slice(0, 16);
+  return join(AUTH_DIR, `${hash}.json`);
+}
+
+async function loadState(serverName: string): Promise<StoredState> {
+  try {
+    const raw = await readFile(statePath(serverName), "utf8");
+    const parsed = JSON.parse(raw) as StoredState;
+    return {
+      clientInfo: parsed.clientInfo ?? undefined,
+      tokens: parsed.tokens ?? undefined,
+      codeVerifier: parsed.codeVerifier ?? undefined,
+      discoveryState: parsed.discoveryState ?? undefined,
+    };
+  } catch {
+    return {
+      clientInfo: undefined,
+      tokens: undefined,
+      codeVerifier: undefined,
+      discoveryState: undefined,
+    };
+  }
+}
+
+async function saveState(serverName: string, state: StoredState): Promise<void> {
+  await mkdir(AUTH_DIR, { recursive: true });
+  // Only write defined fields
+  const toWrite: Record<string, unknown> = {};
+  if (state.clientInfo !== undefined) toWrite.clientInfo = state.clientInfo;
+  if (state.tokens !== undefined) toWrite.tokens = state.tokens;
+  if (state.codeVerifier !== undefined) toWrite.codeVerifier = state.codeVerifier;
+  if (state.discoveryState !== undefined) toWrite.discoveryState = state.discoveryState;
+  await writeFile(statePath(serverName), JSON.stringify(toWrite, null, 2), "utf8");
+}
+
+// ─── OAuthClientProvider Implementation ────────────────────────────────────────
+
+export class McpOAuthProvider implements OAuthClientProvider {
+  private serverName: string;
+  private authConfig: AuthConfig;
+  private _redirectUrl: string | undefined;
+  private _onAuthRequired: ((url: URL) => void | Promise<void>) | undefined;
+  private _oauthState: string | undefined;
+
+  constructor(
+    serverName: string,
+    authConfig: AuthConfig,
+    onAuthRequired?: (url: URL) => void | Promise<void>,
+  ) {
+    this.serverName = serverName;
+    this.authConfig = authConfig;
+    this._redirectUrl = authConfig.redirectUrl;
+    this._onAuthRequired = onAuthRequired;
+  }
+
+  // --- redirectUrl ---
+
+  get redirectUrl(): string | URL {
+    // Use configured redirect URL if provided, otherwise use the callback server
+    // Use 127.0.0.1 explicitly (IPv4) to match the callback server binding
+    return this._redirectUrl || `http://127.0.0.1:${callbackPort}/callback`;
+  }
+
+  // --- clientMetadata ---
+
+  get clientMetadata(): OAuthClientMetadata {
+    const redirectUrl = String(this.redirectUrl);
+    return {
+      client_name: `pi-mcp/${this.serverName}`,
+      redirect_uris: [redirectUrl],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: this.authConfig.clientSecret ? "client_secret_basic" : "none",
+    };
+  }
+
+  // --- clientInformation ---
+
+  async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
+    // If static credentials provided, use those
+    if (this.authConfig.clientId) {
+      return {
+        client_id: this.authConfig.clientId,
+        ...(this.authConfig.clientSecret && { client_secret: this.authConfig.clientSecret }),
+      };
+    }
+    // Otherwise load from persisted DCR state
+    const state = await loadState(this.serverName);
+    if (state.clientInfo) {
+      return {
+        client_id: state.clientInfo.client_id,
+        ...(state.clientInfo.client_secret && { client_secret: state.clientInfo.client_secret }),
+      };
+    }
+    return undefined;
+  }
+
+  // --- saveClientInformation (DCR) ---
+
+  async saveClientInformation(clientInformation: OAuthClientInformationMixed): Promise<void> {
+    const state = await loadState(this.serverName);
+    state.clientInfo = {
+      client_id: clientInformation.client_id,
+      client_secret: clientInformation.client_secret,
+    };
+    await saveState(this.serverName, state);
+  }
+
+  // --- tokens ---
+
+  async tokens(): Promise<OAuthTokens | undefined> {
+    const state = await loadState(this.serverName);
+    if (!state.tokens) return undefined;
+
+    // Always return stored tokens — even if expired.
+    // The SDK's auth() function checks tokens?.refresh_token and attempts
+    // silent refresh before falling back to a new authorization flow.
+    // Returning undefined for expired tokens would prevent that silent refresh
+    // and force the user to re-authenticate via browser every time.
+    //
+    // Flow when we return expired tokens:
+    //   transport sends expired access_token → 401
+    //   → auth() sees refresh_token → silent refresh → success → retry
+    //
+    // Flow when we return undefined (WRONG):
+    //   transport has no token → auth() → no refresh possible → REDIRECT
+    //   → user must re-authenticate in browser
+
+    // Build OAuthTokens — only include defined fields
+    const tokens: Record<string, string> = {
+      access_token: state.tokens.access_token,
+    };
+    if (state.tokens.token_type !== undefined) tokens.token_type = state.tokens.token_type;
+    if (state.tokens.refresh_token !== undefined) tokens.refresh_token = state.tokens.refresh_token;
+    return tokens as unknown as OAuthTokens;
+  }
+
+  // --- saveTokens ---
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    const state = await loadState(this.serverName);
+    state.tokens = {
+      access_token: tokens.access_token,
+      token_type: tokens.token_type,
+      refresh_token: tokens.refresh_token,
+      expires_in: tokens.expires_in,
+      scope: tokens.scope,
+      saved_at: new Date().toISOString(),
+    };
+    await saveState(this.serverName, state);
+  }
+
+  // --- redirectToAuthorization ---
+
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    if (this._onAuthRequired) {
+      await this._onAuthRequired(authorizationUrl);
+    } else {
+      // Fallback: just log it
+      console.error(
+        `[pi-mcp] OAuth authorization required for "${this.serverName}".`,
+        `\n  Open this URL in your browser: ${authorizationUrl.toString()}`,
+      );
+    }
+  }
+
+  // --- PKCE code verifier ---
+
+  async saveCodeVerifier(codeVerifier: string): Promise<void> {
+    const state = await loadState(this.serverName);
+    state.codeVerifier = codeVerifier;
+    await saveState(this.serverName, state);
+  }
+
+  async codeVerifier(): Promise<string> {
+    const state = await loadState(this.serverName);
+    if (!state.codeVerifier) {
+      throw new Error(`[pi-mcp] No PKCE code verifier found for "${this.serverName}"`);
+    }
+    return state.codeVerifier;
+  }
+
+  // --- Discovery state caching ---
+
+  async saveDiscoveryState(discState: OAuthDiscoveryState): Promise<void> {
+    const state = await loadState(this.serverName);
+    state.discoveryState = discState;
+    await saveState(this.serverName, state);
+  }
+
+  async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
+    const state = await loadState(this.serverName);
+    return state.discoveryState;
+  }
+
+  // --- OAuth state parameter (CSRF protection) ---
+
+  /**
+   * Set the OAuth state parameter before calling auth().
+   * This should be called with a cryptographically random value.
+   */
+  setState(state: string): void {
+    this._oauthState = state;
+  }
+
+  /**
+   * Returns the OAuth state parameter for CSRF protection.
+   * This is called by the SDK's auth() function when building the authorization URL.
+   * Returns empty string if no state has been set (no CSRF protection).
+   */
+  async state(): Promise<string> {
+    return this._oauthState || "";
+  }
+
+  // --- Credential invalidation ---
+
+  async invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void> {
+    const state = await loadState(this.serverName);
+    switch (scope) {
+      case "all":
+        state.clientInfo = undefined;
+        state.tokens = undefined;
+        state.codeVerifier = undefined;
+        state.discoveryState = undefined;
+        break;
+      case "client":
+        state.clientInfo = undefined;
+        break;
+      case "tokens":
+        state.tokens = undefined;
+        break;
+      case "verifier":
+        state.codeVerifier = undefined;
+        break;
+      case "discovery":
+        state.discoveryState = undefined;
+        break;
+    }
+    await saveState(this.serverName, state);
+  }
+}
+
+// ─── Public Helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Get auth status info for a server — whether tokens exist, when they were saved, etc.
+ * Returns null if no auth state file exists at all.
+ */
+export async function getAuthStatus(serverName: string): Promise<{
+  hasTokens: boolean;
+  hasClientInfo: boolean;
+  savedAt: string | undefined;
+  scope: string | undefined;
+} | null> {
+  const state = await loadState(serverName);
+  if (
+    state.clientInfo === undefined &&
+    state.tokens === undefined &&
+    state.codeVerifier === undefined &&
+    state.discoveryState === undefined
+  ) {
+    return null;
+  }
+  return {
+    hasTokens: state.tokens !== undefined,
+    hasClientInfo: state.clientInfo !== undefined,
+    savedAt: state.tokens?.saved_at,
+    scope: state.tokens?.scope,
+  };
+}
+
+/**
+ * Reset all OAuth state for a server (tokens, client info, PKCE verifier, discovery).
+ * Used to force re-authorization on next connection.
+ */
+export async function resetAuth(serverName: string): Promise<void> {
+  await unlink(statePath(serverName)).catch(() => {});
+}

package/src/server-manager.ts

@@ -23,7 +23,9 @@ import {
   LoggingMessageNotificationSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { McpError } from "./errors.js";
-import type { McpConfig, ServerConfig, Settings } from "./config.js";
+import type { McpConfig, ServerConfig, Settings, AuthConfig } from "./config.js";
+import { McpOAuthProvider, getAuthStatus, resetAuth } from "./oauth-provider.js";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -54,12 +56,36 @@ export interface ManagedServer {
 /** Called after tool list is refreshed for a server (e.g. on list_changed notification). */
 export type ToolRefreshCallback = (serverName: string, client: Client) => Promise<void>;
 
+export interface TransportAuthCallbacks {
+  /** Called when OAuth authorization is required (browser redirect needed). */
+  onAuthRequired: (serverName: string, authorizationUrl: URL) => void | Promise<void>;
+}
+
 // ─── Transport Factory ────────────────────────────────────────────────────────
 
 function createTransport(
+  serverName: string,
   config: ServerConfig,
   onStderr: (line: string) => void,
+  authCallbacks?: TransportAuthCallbacks,
 ): Transport {
+  // Build requestInit for static headers (API keys, etc.)
+  const requestInit: RequestInit | undefined = config.headers
+    ? { headers: config.headers }
+    : undefined;
+
+  // Build OAuth authProvider if auth config is present
+  let authProvider: OAuthClientProvider | undefined;
+  if (config.auth && config.transport !== "stdio") {
+    authProvider = new McpOAuthProvider(
+      serverName,
+      config.auth,
+      authCallbacks
+        ? (url: URL) => authCallbacks.onAuthRequired(serverName, url)
+        : undefined,
+    );
+  }
+
   switch (config.transport) {
     case "stdio": {
       // Build clean env: process.env may contain undefined values,
@@ -83,11 +109,21 @@ function createTransport(
       return transport;
     }
     case "streamable-http":
-      // Cast needed: exactOptionalPropertyTypes conflicts with sessionId?: string vs string
-      return new StreamableHTTPClientTransport(new URL(config.url!)) as unknown as Transport;
+      return new StreamableHTTPClientTransport(
+        new URL(config.url!),
+        {
+          ...(requestInit && { requestInit }),
+          ...(authProvider && { authProvider }),
+        },
+      ) as unknown as Transport;
     case "sse":
-      // Legacy HTTP+SSE transport (2024-11-05 spec) — backwards compatibility
-      return new SSEClientTransport(new URL(config.url!));
+      return new SSEClientTransport(
+        new URL(config.url!),
+        {
+          ...(requestInit && { requestInit }),
+          ...(authProvider && { authProvider }),
+        },
+      );
   }
 }
 
@@ -98,8 +134,11 @@ export class ServerManager {
   private settings: Settings;
   private onToolRefresh: ToolRefreshCallback | null = null;
 
-  constructor(config: McpConfig) {
+  private authCallbacks: TransportAuthCallbacks | undefined;
+
+  constructor(config: McpConfig, authCallbacks?: TransportAuthCallbacks) {
     this.settings = config.settings;
+    this.authCallbacks = authCallbacks;
     for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
       this.servers.set(name, {
         name,
@@ -146,6 +185,21 @@ export class ServerManager {
     return [`MCP: ${ready}/${all.length} servers ready`, ...lines].join("\n");
   }
 
+  /** Reset OAuth credentials for a server, forcing re-authorization on next connect. */
+  async resetServerAuth(name: string): Promise<void> {
+    await resetAuth(name);
+  }
+
+  /** Get auth status for a server. */
+  async getServerAuthStatus(name: string): Promise<{
+    hasTokens: boolean;
+    hasClientInfo: boolean;
+    savedAt: string | undefined;
+    scope: string | undefined;
+  } | null> {
+    return getAuthStatus(name);
+  }
+
   /** Get recent stderr output for a server. */
   getServerLogs(name: string): string {
     const server = this.servers.get(name);
@@ -227,7 +281,7 @@ export class ServerManager {
 
     let transport: Transport;
     try {
-      transport = createTransport(server.config, appendStderr);
+      transport = createTransport(server.name, server.config, appendStderr, this.authCallbacks);
     } catch (err) {
       server.state = "stopped";
       server.lastError = err instanceof Error ? err : new Error(String(err));