pi-mcp-extension 1.5.0 → 1.5.2

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.5.0",
+  "version": "1.5.2",
   "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

@@ -6,6 +6,7 @@
  */
 
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http";
+import type { Socket } from "net";
 import { URL } from "url";
 
 interface PendingAuth {
@@ -16,14 +17,30 @@ interface PendingAuth {
 
 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><title>Pi - Authorization Successful</title>
+<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>
@@ -32,7 +49,7 @@ const HTML_SUCCESS = `<!DOCTYPE html>
 </body></html>`;
 
 const HTML_ERROR = (error: string) => `<!DOCTYPE html>
-<html><head><title>Pi - Authorization Failed</title>
+<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>
@@ -56,11 +73,11 @@ function escapeHtml(text: string): string {
  * 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}`);
+  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" });
+    res.writeHead(404, { "Content-Type": "text/plain", "Connection": "close" });
     res.end("Not found");
     return;
   }
@@ -73,7 +90,7 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
   // 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.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
     res.end(HTML_ERROR(errorMsg));
     return;
   }
@@ -81,7 +98,7 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
   // Handle OAuth errors
   if (error) {
     const errorMsg = errorDescription || error;
-    res.writeHead(200, { "Content-Type": "text/html" });
+    res.writeHead(200, { "Content-Type": "text/html", "Connection": "close" });
     res.end(HTML_ERROR(errorMsg));
     if (pendingAuths.has(state)) {
       const pending = pendingAuths.get(state)!;
@@ -94,7 +111,7 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
 
   // Require authorization code
   if (!code) {
-    res.writeHead(400, { "Content-Type": "text/html" });
+    res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
     res.end(HTML_ERROR("No authorization code provided"));
     return;
   }
@@ -102,7 +119,7 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
   // 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.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
     res.end(HTML_ERROR(errorMsg));
     return;
   }
@@ -114,54 +131,137 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
   pendingAuths.delete(state);
   pending.resolve(code);
 
-  res.writeHead(200, { "Content-Type": "text/html" });
+  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 if the preferred port is busy.
+ * 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): Promise<number> {
+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) {
-    // 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) {
+    if (actualServerPort === null && 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 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 = 25; // Try up to 25 ports
+  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);
         });
 
-        // Bind to 127.0.0.1 explicitly (IPv4) to avoid issues with IPv6
-        candidateServer.listen(candidatePort, "127.0.0.1", () => {
+        candidateServer.listen(candidatePort, host, () => {
           resolve();
         });
       });
-
       server = candidateServer;
       actualServerPort = candidatePort;
+      actualServerHost = host;
       server.unref(); // Don't block process exit
       return candidatePort;
     } catch (error) {
@@ -174,6 +274,10 @@ export async function ensureCallbackServer(preferredPort: number = DEFAULT_PORT)
       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`);
+      }
     }
   }
 
@@ -224,15 +328,7 @@ export function cancelCallback(oauthState: string): void {
  * 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;
-  }
+  await closeCurrentServer();
 
   // Reject all pending auths (defer to allow any pending operations to complete)
   const pendingList = Array.from(pendingAuths.entries());
@@ -260,4 +356,4 @@ export function getPendingAuthCount(): number {
 }
 
 // Export constants for testing/config
-export { DEFAULT_PORT, CALLBACK_PATH, TIMEOUT_MS };
+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([