pi-mcp-extension 1.3.0 → 1.4.1

package/README.md

@@ -1,11 +1,11 @@
-# pi-mcp
+# pi-mcp-extension
 
-[![npm version](https://img.shields.io/npm/v/pi-mcp.svg)](https://www.npmjs.com/package/pi-mcp)
-[![license](https://img.shields.io/npm/l/pi-mcp.svg)](https://github.com/irahardianto/pi-mcp/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/pi-mcp-extension.svg)](https://www.npmjs.com/package/pi-mcp-extension)
+[![license](https://img.shields.io/npm/l/pi-mcp-extension.svg)](https://github.com/irahardianto/pi-mcp-extension/blob/main/LICENSE)
 
 **Connect [Pi](https://pi.dev) to any MCP server.** Supabase, DeepSource, Playwright, Context7, filesystem, databases — if it speaks [MCP](https://modelcontextprotocol.io), Pi can use it.
 
-`pi-mcp` is a production-ready [Model Context Protocol](https://modelcontextprotocol.io/) client extension for the [Pi coding agent](https://pi.dev). It manages server connections, discovers tools, and bridges them into Pi so the LLM can call them directly.
+`pi-mcp-extension` is a production-ready [Model Context Protocol](https://modelcontextprotocol.io/) client extension for the [Pi coding agent](https://pi.dev). It manages server connections, discovers tools, and bridges them into Pi so the LLM can call them directly.
 
 ## Features
 
@@ -25,20 +25,20 @@
 ## Installation
 
 ```bash
-pi install npm:pi-mcp
+pi install npm:pi-mcp-extension
 ```
 
 Or try without installing:
 
 ```bash
-pi -e npm:pi-mcp
+pi -e npm:pi-mcp-extension
 ```
 
 ## Quick Start
 
 1. Install the extension:
    ```bash
-   pi install npm:pi-mcp
+   pi install npm:pi-mcp-extension
    ```
 
 2. Create a config file at `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project-level):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [
@@ -16,11 +16,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/irahardianto/pi-mcp.git"
+    "url": "git+https://github.com/irahardianto/pi-mcp-extension.git"
   },
-  "homepage": "https://github.com/irahardianto/pi-mcp",
+  "homepage": "https://github.com/irahardianto/pi-mcp-extension",
   "bugs": {
-    "url": "https://github.com/irahardianto/pi-mcp/issues"
+    "url": "https://github.com/irahardianto/pi-mcp-extension/issues"
   },
   "files": [
     "src/",

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,28 @@
 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";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+/**
+ * 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) => {
+    if (err) console.error(`[pi-mcp] Failed to open browser: ${err.message}`);
+  });
+}
 
 export default async function (pi: ExtensionAPI): Promise<void> {
   // ── 1. Load and validate config ──────────────────────────────────────────
@@ -35,7 +55,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
@@ -167,4 +197,82 @@ 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;
+      }
+
+      try {
+        // Stop the server if running
+        if (server.state !== "stopped") {
+          bridge.deactivateServer(serverName);
+          await manager.stopServer(serverName);
+        }
+        // Reset all OAuth credentials (tokens, client info, PKCE, discovery)
+        await manager.resetServerAuth(serverName);
+        ctx.ui.notify(
+          `pi-mcp: Reset credentials for ${serverName}. Starting server — a browser window will open for authentication...`,
+          "info",
+        );
+        // Start the server — this triggers the OAuth flow and opens the browser
+        await manager.startServer(serverName, ctx.cwd);
+
+        const newStatus = await manager.getServerAuthStatus(serverName);
+        if (newStatus?.hasTokens) {
+          ctx.ui.notify(`pi-mcp: ${serverName} authenticated successfully!`, "info");
+        } else {
+          ctx.ui.notify(
+            `pi-mcp: ${serverName} started but authentication may still be in progress. Check the browser window.`,
+            "info",
+          );
+        }
+      } catch (err) {
+        const msg = err instanceof McpError ? err.userMessage : String(err);
+        ctx.ui.notify(`pi-mcp: Authentication failed for ${serverName} — ${msg}`, "error");
+      }
+    },
+  });
 }

package/src/oauth-provider.ts

@@ -0,0 +1,316 @@
+/**
+ * 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 } 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;
+}
+
+// ─── 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;
+
+  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 | undefined {
+    return this._redirectUrl;
+  }
+
+  // --- clientMetadata ---
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      client_name: `pi-mcp/${this.serverName}`,
+      redirect_uris: this._redirectUrl ? [this._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;
+    // 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;
+  }
+
+  // --- 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> {
+  const provider = new McpOAuthProvider(serverName, {});
+  await provider.invalidateCredentials("all");
+}

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));

package/src/tool-bridge.ts

@@ -30,13 +30,20 @@ export type PiExtensionAPI = Pick<ExtensionAPI, "registerTool" | "getActiveTools
 
 /**
  * Convert a JSON Schema object to a TypeBox schema.
- * Handles the common subset used by real-world MCP servers.
- * Falls back to Type.Any() for unsupported constructs ($ref, oneOf, etc.)
- * and logs a warning so users can report gaps.
+ * Handles the common subset used by real-world MCP servers:
+ *   - Primitives (string, number, integer, boolean, null)
+ *   - Arrays, objects (with required/optional/additionalProperties)
+ *   - Enums (string enums → Union of Literals)
+ *   - Nullable types ("type": ["string", "null"])
+ *   - $ref (local #/$defs/ and #/definitions/ references)
+ *   - oneOf / anyOf → TypeBox Union
+ *   - allOf → TypeBox Intersect
+ * Falls back to Type.Any() for unresolvable $ref or missing type.
  */
 export function convertJsonSchemaToTypebox(
   schema: unknown,
   depth = 0,
+  defs?: Record<string, unknown>,
 ): TSchema {
   // Guard against infinite recursion and malformed schemas
   if (!schema || typeof schema !== "object" || Array.isArray(schema) || depth > 10) {
@@ -47,6 +54,71 @@ export function convertJsonSchemaToTypebox(
   const description = typeof s["description"] === "string" ? s["description"] : undefined;
   const opts = description ? { description } : {};
 
+  // Extract $defs / definitions for $ref resolution (carried through recursive calls)
+  const resolvedDefs: Record<string, unknown> = {
+    ...((s["$defs"] ?? s["definitions"]) as Record<string, unknown> | undefined),
+    ...defs,
+  };
+
+  // ── Handle $ref ──────────────────────────────────────────────────────────
+  if (typeof s["$ref"] === "string") {
+    const ref = s["$ref"] as string;
+    let resolved: unknown;
+
+    // Local references: #/$defs/Foo, #/definitions/Foo
+    if (ref.startsWith("#/")) {
+      const parts = ref.slice(2).split("/");
+      if (parts[0] === "$defs" || parts[0] === "definitions") {
+        const key = parts.slice(1).join("/");
+        resolved = resolvedDefs[key];
+      } else {
+        // Fallback: try walking the defs map by the last part
+        const key = parts[parts.length - 1]!;
+        resolved = resolvedDefs[key];
+      }
+    } else {
+      // External $ref — cannot resolve, fall back
+      console.warn(
+        `[pi-mcp] Cannot resolve external $ref "${ref}", using Type.Any()`,
+      );
+      return Type.Any(opts);
+    }
+
+    if (!resolved) {
+      console.warn(
+        `[pi-mcp] Could not resolve $ref "${ref}", using Type.Any()`,
+      );
+      return Type.Any(opts);
+    }
+
+    // Merge description from referencing schema into resolved schema
+    const merged = { ...(resolved as Record<string, unknown>) };
+    if (description && !merged["description"]) {
+      merged["description"] = description;
+    }
+    return convertJsonSchemaToTypebox(merged, depth + 1, resolvedDefs);
+  }
+
+  // ── Handle oneOf / anyOf → TypeBox Union ─────────────────────────────────
+  if (Array.isArray(s["oneOf"])) {
+    const members = (s["oneOf"] as unknown[])
+      .map((sub) => convertJsonSchemaToTypebox(sub, depth + 1, resolvedDefs));
+    return members.length === 1 ? members[0]! : Type.Union(members, opts);
+  }
+
+  if (Array.isArray(s["anyOf"])) {
+    const members = (s["anyOf"] as unknown[])
+      .map((sub) => convertJsonSchemaToTypebox(sub, depth + 1, resolvedDefs));
+    return members.length === 1 ? members[0]! : Type.Union(members, opts);
+  }
+
+  // ── Handle allOf → TypeBox Intersect ─────────────────────────────────────
+  if (Array.isArray(s["allOf"])) {
+    const members = (s["allOf"] as unknown[])
+      .map((sub) => convertJsonSchemaToTypebox(sub, depth + 1, resolvedDefs));
+    return members.length === 1 ? members[0]! : Type.Intersect(members, opts);
+  }
+
   // Handle nullable types: { "type": ["string", "null"] }
   const rawType = s["type"];
   const type = Array.isArray(rawType)
@@ -84,7 +156,7 @@ export function convertJsonSchemaToTypebox(
     case "array": {
       const items = s["items"];
       base = Type.Array(
-        items ? convertJsonSchemaToTypebox(items, depth + 1) : Type.Unknown(),
+        items ? convertJsonSchemaToTypebox(items, depth + 1, resolvedDefs) : Type.Unknown(),
         opts,
       );
       break;
@@ -104,7 +176,7 @@ export function convertJsonSchemaToTypebox(
 
       const props: Record<string, TSchema> = {};
       for (const [key, value] of Object.entries(properties)) {
-        const converted = convertJsonSchemaToTypebox(value, depth + 1);
+        const converted = convertJsonSchemaToTypebox(value, depth + 1, resolvedDefs);
         props[key] = required.has(key) ? converted : Type.Optional(converted);
       }
 
@@ -117,12 +189,7 @@ export function convertJsonSchemaToTypebox(
       break;
     }
     default: {
-      // Unsupported: $ref, oneOf, anyOf, allOf, or missing type field
-      if (s["oneOf"] || s["anyOf"] || s["allOf"] || s["$ref"]) {
-        console.error(
-          `[pi-mcp] Unsupported JSON Schema construct (oneOf/anyOf/allOf/$ref), using Type.Any(). Schema: ${JSON.stringify(s).slice(0, 200)}`,
-        );
-      }
+      // Truly unsupported or missing type field
       base = Type.Any(opts);
       break;
     }