pi-mcp-extension 1.4.1 → 1.5.1

package/README.md

@@ -21,6 +21,7 @@
 - **Global + project config** — Layered config (project overrides global) with per-server tuning
 - **Tool annotations** — `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` surfaced in tool descriptions
 - **Structured error handling** — Distinct error codes for config, connection, protocol, and tool-level failures
+- **OAuth 2.1** — Browser authorization with PKCE, protected-resource discovery, token refresh, and secure local persistence
 
 ## Installation
 
@@ -80,6 +81,9 @@ Config files are loaded from two locations. **Project config overrides global co
     "supabase": {
       "transport": "streamable-http",
       "url": "https://mcp.supabase.com/mcp",
+      "auth": {
+        "type": "oauth"
+      },
       "lifecycle": "eager"
     },
     "deepsource": {
@@ -137,18 +141,34 @@ Config files are loaded from two locations. **Project config overrides global co
 | `args` | `string[]` | `[]` | Arguments for the command |
 | `env` | `Record<string, string>` | — | Extra environment variables for the child process |
 | `url` | `string` | — | Server URL (**required** for streamable-http/sse) |
-| `lifecycle` | `"eager" \| "lazy"` | `"lazy"` | `eager` = auto-start on session start, `lazy` = manual via `/mcp:start` |
+| `headers` | `Record<string, string>` | — | Static headers sent with HTTP and SSE requests |
+| `auth` | `object` | — | OAuth configuration described below |
+| `lifecycle` | `"eager" \| "lazy"` | `"lazy"` | `eager` = auto-start on session start, `lazy` = connect on request via `/mcp:start` |
 | `requestTimeoutMs` | `number` | global setting | Per-server timeout override |
 | `healthCheckIntervalMs` | `number` | disabled | Opt-in ping interval for connection health monitoring |
 
+### OAuth Config
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `type` | `"oauth"` | `"oauth"` | Authentication type |
+| `scope` | `string` | discovered | Requested scope when the server does not advertise one |
+| `clientId` | `string` | dynamic registration | Pre-registered OAuth client ID |
+| `clientSecret` | `string` | — | Secret for a pre-registered confidential client |
+| `redirectUrl` | `string` | `http://127.0.0.1:19876/callback` | Local HTTP loopback callback used by `/mcp:auth` |
+
 ## Commands
 
 | Command | Description |
 |---|---|
 | `/mcp` | Show status summary of all configured servers |
 | `/mcp <name>` | Show detailed status and stderr log for a specific server |
-| `/mcp:start <name>` | Start a server (resets retry count) |
-| `/mcp:stop <name>` | Stop a running server and deactivate its tools |
+| `/mcp:start <name>` | Connect a server and wait for tool discovery |
+| `/mcp:stop <name>` | Cancel a pending connection 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 |
+
+Repeated credential resets share one pending authorization; stop or shutdown cancels it. Lazy servers remain stopped until requested. An interactive Pi session is required when browser authorization is needed. Eager startup never opens a browser. Retry opens the browser again only when selected in the OAuth prompt.
 
 ## How It Works
 
@@ -176,7 +196,7 @@ Config files are loaded from two locations. **Project config overrides global co
 ```
 
 1. **Config is loaded** from global and project files (project overrides global by server name)
-2. **Eager servers connect** at session start; lazy servers wait for `/mcp:start`
+2. **Eager servers connect** at session start without opening browsers; lazy servers wait for `/mcp:start`
 3. **Tools are discovered** via paginated `tools/list` calls (cursor-based, up to 100 pages)
 4. **JSON Schema → TypeBox** conversion registers tools with Pi-compatible parameter schemas
 5. **Pi tools are registered** as `<prefix>_<server>_<tool>` (sanitized, max 64 chars with hash suffix)
@@ -217,7 +237,7 @@ npm install
 # Type check (strict mode)
 npm run typecheck
 
-# Run all tests (47 tests)
+# Run all tests
 npm test
 
 # Run integration tests only (real stdio server)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "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

@@ -0,0 +1,60 @@
+/**
+ * OAuth challenge discovery helpers for manual MCP authentication commands.
+ */
+
+import { extractWWWAuthenticateParams } from "@modelcontextprotocol/sdk/client/auth.js";
+
+export interface ManualAuthChallenge {
+  resourceMetadataUrl?: URL | undefined;
+  scope?: string | undefined;
+}
+
+export type AuthChallengeFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+export const AUTH_CHALLENGE_TIMEOUT_MS = 10_000;
+
+export interface ManualAuthChallengeOptions {
+  fetchFn?: AuthChallengeFetch | undefined;
+  timeoutMs?: number | undefined;
+  headers?: Record<string, string> | undefined;
+}
+
+/**
+ * Discover OAuth challenge parameters from an MCP resource server.
+ *
+ * Some resource servers expose the protected resource metadata URL only in the
+ * WWW-Authenticate header of the initial 401 response. Manual auth must carry
+ * those values into the SDK auth flow so discovery reaches the real
+ * authorization server instead of falling back to the resource server origin.
+ */
+export async function discoverManualAuthChallenge(
+  serverUrl: string,
+  options: ManualAuthChallengeOptions = {},
+): Promise<ManualAuthChallenge> {
+  const fetchFn = options.fetchFn ?? fetch;
+  const headers = new Headers(options.headers);
+  headers.set("Accept", "application/json, text/event-stream");
+  const response = await fetchFn(serverUrl, {
+    method: "GET",
+    headers,
+    signal: AbortSignal.timeout(options.timeoutMs ?? AUTH_CHALLENGE_TIMEOUT_MS),
+  });
+
+  try {
+    if (response.status !== 401 && response.status !== 403) {
+      return {};
+    }
+
+    const { resourceMetadataUrl, scope, error } = extractWWWAuthenticateParams(response);
+    if (response.status === 403 && error !== "insufficient_scope") {
+      return {};
+    }
+
+    return {
+      ...(resourceMetadataUrl ? { resourceMetadataUrl } : {}),
+      ...(scope ? { scope } : {}),
+    };
+  } finally {
+    await response.body?.cancel().catch(() => {});
+  }
+}

package/src/callback-server.ts

@@ -0,0 +1,359 @@
+/**
+ * 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 type { Socket } from "net";
+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;
+let actualServerHost: string | null = null;
+const serverSockets = new Set<Socket>();
+const pendingAuths = new Map<string, PendingAuth>();
+
+const DEFAULT_PORT = 19876;
+const DEFAULT_HOST = "127.0.0.1";
+const CALLBACK_PATH = "/callback";
+
+export interface CallbackServerOptions {
+  /** Host to bind. Defaults to 127.0.0.1 for local-only callbacks. */
+  host?: string | undefined;
+  /** Whether to scan following ports when the preferred port is busy. */
+  allowPortFallback?: boolean | undefined;
+}
+
+export interface CallbackServerConfig {
+  preferredPort: number;
+  host: string;
+  allowPortFallback: boolean;
+}
+const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+const HTML_SUCCESS = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><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><meta charset="utf-8"><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://localhost");
+
+  // Only handle the callback path
+  if (url.pathname !== CALLBACK_PATH) {
+    res.writeHead(404, { "Content-Type": "text/plain", "Connection": "close" });
+    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", "Connection": "close" });
+    res.end(HTML_ERROR(errorMsg));
+    return;
+  }
+
+  // Handle OAuth errors
+  if (error) {
+    const errorMsg = errorDescription || error;
+    res.writeHead(200, { "Content-Type": "text/html", "Connection": "close" });
+    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", "Connection": "close" });
+    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", "Connection": "close" });
+    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", "Connection": "close" });
+  res.end(HTML_SUCCESS);
+}
+
+function isLocalCallbackHost(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+}
+
+async function closeCurrentServer(): Promise<void> {
+  if (!server) return;
+
+  const currentServer = server;
+  server = null;
+  actualServerPort = null;
+  actualServerHost = null;
+
+  for (const socket of Array.from(serverSockets)) {
+    socket.destroy();
+  }
+  serverSockets.clear();
+
+  await new Promise<void>((resolve) => {
+    currentServer.close(() => {
+      resolve();
+    });
+  });
+}
+
+/**
+ * Build callback server settings from the configured OAuth redirect URL.
+ *
+ * Local HTTP redirect URLs must use a fixed listener port because OAuth
+ * providers require exact redirect URI registration. When no local redirect URL
+ * is configured, the callback server keeps the historical default behavior and
+ * scans forward from the default port if needed.
+ */
+export function callbackServerConfigFromRedirectUrl(redirectUrl?: string): CallbackServerConfig {
+  if (!redirectUrl) {
+    return {
+      preferredPort: DEFAULT_PORT,
+      host: DEFAULT_HOST,
+      allowPortFallback: true,
+    };
+  }
+
+  const url = new URL(redirectUrl);
+  if (url.protocol !== "http:" || !isLocalCallbackHost(url.hostname)) {
+    throw new Error("Manual OAuth redirect URL must use HTTP with localhost, 127.0.0.1, or ::1");
+  }
+
+  if (url.hash) {
+    throw new Error("Manual OAuth redirect URL must not include a fragment");
+  }
+
+  if (url.username || url.password) {
+    throw new Error("Manual OAuth redirect URL must not include credentials");
+  }
+
+  if (url.pathname !== CALLBACK_PATH) {
+    throw new Error(`Local OAuth redirect URL must use path ${CALLBACK_PATH}`);
+  }
+
+  const preferredPort = Number(url.port || "80");
+  if (preferredPort === 0) {
+    throw new Error("Manual OAuth redirect URL must use a fixed non-zero port");
+  }
+
+  return {
+    preferredPort,
+    host: url.hostname === "[::1]" ? "::1" : url.hostname,
+    allowPortFallback: false,
+  };
+}
+
+/**
+ * Ensure the callback server is running.
+ * Scans forward for an available local port when port fallback is enabled.
+ *
+ * @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, options: CallbackServerOptions = {}): Promise<number> {
+  const host = options.host ?? DEFAULT_HOST;
+  const allowPortFallback = options.allowPortFallback ?? true;
+
+  if (server) {
+    const address = server.address();
+    if (actualServerPort === null && address && typeof address === "object" && "port" in address) {
+      actualServerPort = address.port;
+    }
+
+    const serverMatchesRequest = actualServerPort === preferredPort && actualServerHost === host;
+    if (serverMatchesRequest && actualServerPort !== null) {
+      return actualServerPort;
+    }
+
+    if (pendingAuths.size > 0) {
+      throw new Error(
+        `OAuth callback server is already handling an authorization flow on ${actualServerHost}:${actualServerPort}`
+      );
+    }
+
+    await closeCurrentServer();
+  }
+
+  const maxAttempts = allowPortFallback ? 25 : 1; // Try up to 25 ports unless a fixed redirect URI is configured
+
+  for (let offset = 0; offset < maxAttempts; offset++) {
+    const candidatePort = preferredPort + offset;
+    const candidateServer = createServer(handleRequest);
+
+    try {
+      candidateServer.on("connection", (socket: Socket) => {
+        serverSockets.add(socket);
+        socket.once("close", () => {
+          serverSockets.delete(socket);
+        });
+      });
+
+      await new Promise<void>((resolve, reject) => {
+        candidateServer.once("error", (err: any) => {
+          reject(err);
+        });
+
+        candidateServer.listen(candidatePort, host, () => {
+          resolve();
+        });
+      });
+      server = candidateServer;
+      actualServerPort = candidatePort;
+      actualServerHost = host;
+      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;
+      }
+
+      if (!allowPortFallback) {
+        throw new Error(`OAuth callback port ${preferredPort} is already in use, and redirect URL requires this exact port`);
+      }
+    }
+  }
+
+  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> {
+  await closeCurrentServer();
+
+  // 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, DEFAULT_HOST, CALLBACK_PATH, TIMEOUT_MS };

package/src/config.ts

@@ -170,8 +170,7 @@ function mergeConfigs(
  * Project config takes precedence over global config.
  * Returns a fully validated, merged config.
  */
-export async function loadConfig(cwd: string): Promise<McpConfig> {
-  const globalPath = join(homedir(), ".pi", "agent", "mcp.json");
+export async function loadConfig(cwd: string, globalPath = join(homedir(), ".pi", "agent", "mcp.json")): Promise<McpConfig> {
   const projectPath = join(cwd, ".pi", "mcp.json");
 
   const [globalRaw, projectRaw] = await Promise.all([