pi-mcp-adapter 2.2.2 → 2.3.2

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.2] - 2026-04-11
+
+### Added
+- Optional `oauth.grantType: "client_credentials"` for non-interactive machine-to-machine OAuth on HTTP MCP servers.
+
+### Fixed
+- `/mcp-auth <server>` now handles `client_credentials` without browser/callback flow.
+- MCP panel status no longer marks `client_credentials` servers as auth-blocked solely because no stored user tokens exist yet.
+- OAuth auth flow now closes temporary transports consistently on success, refresh, and auth removal paths.
+- Init paths now preserve debug-level context for previously silent direct-tool bootstrap and lazy-connect failures.
+
+## [2.3.1] - 2026-04-11
+
+### Fixed
+- Removed `/mcp-auth-callback`. OAuth auth now hard-cuts to `/mcp-auth <server>` only.
+
+## [2.3.0] - 2026-04-11
+
+### Added
+- OAuth callback server initialization on session start and a deprecated `/mcp-auth-callback` command that now points users to `/mcp-auth <server>`.
+
+### Fixed
+- OAuth `needs-auth` handling across `/mcp` status/panel, `mcp({ connect })`, `mcp({ tool })`, reconnect flow, lazy/direct tool execution, and startup bootstrap.
+- OAuth callback cleanup now cancels by stored OAuth state and closes pending transports on failure/cancel paths.
+- Callback server now fails fast when the OAuth callback port is occupied by another process.
+- Package manifest test now ignores root `*.test.ts` files.
+
 ## [2.2.2] - 2026-04-03
 
 ### Fixed

package/README.md

@@ -85,6 +85,7 @@ Two calls instead of 26 tools cluttering the context.
 | `cwd` | Working directory |
 | `url` | HTTP endpoint (StreamableHTTP with SSE fallback) |
 | `auth` | `"bearer"` or `"oauth"` |
+| `oauth.grantType` | `"authorization_code"` (default) or `"client_credentials"` for non-interactive machine auth |
 | `bearerToken` / `bearerTokenEnv` | Token or env var name |
 | `lifecycle` | `"lazy"` (default), `"eager"`, or `"keep-alive"` |
 | `idleTimeout` | Minutes before idle disconnect (overrides global) |
@@ -291,6 +292,4 @@ Tool names are fuzzy-matched on hyphens and underscores — `context7_resolve_li
 
 ## Limitations
 
-- OAuth tokens obtained externally (no browser flow)
-- No automatic token refresh
 - Cross-session server sharing not yet implemented (each Pi session runs its own server processes)

package/commands.ts

@@ -4,8 +4,9 @@ import type { McpConfig, ServerEntry, McpPanelCallbacks, McpPanelResult } from "
 import { getServerProvenance, writeDirectToolsConfig } from "./config.js";
 import { lazyConnect, updateMetadataCache, updateStatusBar, getFailureAgeSeconds } from "./init.js";
 import { loadMetadataCache } from "./metadata-cache.js";
-import { getStoredTokens } from "./oauth-handler.js";
 import { buildToolMetadata } from "./tool-metadata.js";
+import { supportsOAuth, authenticate } from "./mcp-auth-flow.js";
+import { hasStoredTokens } from "./mcp-auth.js";
 
 export async function showStatus(state: McpExtensionState, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) return;
@@ -24,6 +25,9 @@ export async function showStatus(state: McpExtensionState, ctx: ExtensionContext
     if (connection?.status === "connected") {
       status = "connected";
       statusIcon = "✓";
+    } else if (connection?.status === "needs-auth") {
+      status = "needs auth";
+      statusIcon = "⚠";
     } else if (failedAgo !== null) {
       status = `failed ${failedAgo}s ago`;
       statusIcon = "✗";
@@ -85,6 +89,12 @@ export async function reconnectServers(
       await state.manager.close(name);
 
       const connection = await state.manager.connect(name, definition);
+      if (connection.status === "needs-auth") {
+        if (ctx.hasUI) {
+          ctx.ui.notify(`MCP: ${name} requires OAuth. Run /mcp-auth ${name} first.`, "warning");
+        }
+        continue;
+      }
       const prefix = state.config.settings?.toolPrefix ?? "server";
 
       const { metadata, failedTools } = buildToolMetadata(connection.tools, connection.resources, definition, name, prefix);
@@ -126,10 +136,10 @@ export async function authenticateServer(
     return;
   }
 
-  if (definition.auth !== "oauth") {
+  if (!supportsOAuth(definition)) {
     ctx.ui.notify(
       `Server "${serverName}" does not use OAuth authentication.\n` +
-      `Current auth mode: ${definition.auth ?? "none"}`,
+      `Set "auth": "oauth" or omit auth for auto-detection.`,
       "error"
     );
     return;
@@ -143,21 +153,31 @@ export async function authenticateServer(
     return;
   }
 
-  const tokenPath = `~/.pi/agent/mcp-oauth/${serverName}/tokens.json`;
-
-  ctx.ui.notify(
-    `OAuth setup for "${serverName}":\n\n` +
-    `1. Obtain an access token from your OAuth provider\n` +
-    `2. Create the token file:\n` +
-    `   ${tokenPath}\n\n` +
-    `3. Add your token:\n` +
-    `   {\n` +
-    `     "access_token": "your-token-here",\n` +
-    `     "token_type": "bearer"\n` +
-    `   }\n\n` +
-    `4. Run /mcp reconnect to connect with the token`,
-    "info"
-  );
+  // Full automatic OAuth flow using SDK
+  try {
+    ctx.ui.setStatus("mcp-auth", `Authenticating ${serverName}...`);
+
+    // Runs the configured OAuth flow (interactive browser or non-interactive client_credentials)
+    const status = await authenticate(serverName, definition.url, definition);
+
+    if (status === "authenticated") {
+      ctx.ui.notify(
+        `OAuth authentication successful for "${serverName}"!\n` +
+        `Run /mcp reconnect ${serverName} to connect with the new token.`,
+        "success"
+      );
+    } else {
+      ctx.ui.notify(
+        `OAuth authentication failed for "${serverName}".`,
+        "error"
+      );
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.ui.notify(`Failed to authenticate "${serverName}": ${message}`, "error");
+  } finally {
+    ctx.ui.setStatus("mcp-auth", undefined);
+  }
 }
 
 export async function openMcpPanel(
@@ -176,10 +196,18 @@ export async function openMcpPanel(
     },
     getConnectionStatus: (serverName: string) => {
       const definition = config.mcpServers[serverName];
-      if (definition?.auth === "oauth" && getStoredTokens(serverName) === undefined) {
+      const connection = state.manager.getConnection(serverName);
+      if (connection?.status === "needs-auth") {
+        return "needs-auth";
+      }
+      if (
+        definition?.auth === "oauth"
+        && definition.oauth !== false
+        && definition.oauth?.grantType !== "client_credentials"
+        && !hasStoredTokens(serverName)
+      ) {
         return "needs-auth";
       }
-      const connection = state.manager.getConnection(serverName);
       if (connection?.status === "connected") return "connected";
       if (getFailureAgeSeconds(state, serverName) !== null) return "failed";
       return "idle";

package/direct-tools.ts

@@ -198,6 +198,13 @@ export function createDirectToolExecutor(
 
     const connected = await lazyConnect(state, spec.serverName);
     if (!connected) {
+      const authConnection = state.manager.getConnection(spec.serverName);
+      if (authConnection?.status === "needs-auth") {
+        return {
+          content: [{ type: "text" as const, text: `MCP server "${spec.serverName}" requires OAuth authentication. Run /mcp-auth ${spec.serverName} first.` }],
+          details: { error: "auth_required", server: spec.serverName },
+        };
+      }
       const failedAgo = getFailureAgeSeconds(state, spec.serverName);
       return {
         content: [{ type: "text" as const, text: `MCP server "${spec.serverName}" not available${failedAgo !== null ? ` (failed ${failedAgo}s ago)` : ""}` }],

package/index.ts

@@ -8,6 +8,7 @@ import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.js";
 import { loadMetadataCache } from "./metadata-cache.js";
 import { executeCall, executeConnect, executeDescribe, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.js";
 import { getConfigPathFromArgv, truncateAtWord } from "./utils.js";
+import { initializeOAuth } from "./mcp-auth-flow.js";
 
 export default function mcpAdapter(pi: ExtensionAPI) {
   let state: McpExtensionState | null = null;
@@ -93,6 +94,10 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       return;
     }
 
+    await initializeOAuth().catch(err => {
+      console.error("MCP OAuth initialization failed:", err);
+    });
+
     const promise = initializeMcp(pi, ctx);
     initPromise = promise;
 

package/init.ts

@@ -108,6 +108,9 @@ export async function initializeMcp(
   const results = await parallelLimit(startupServers, 10, async ([name, definition]) => {
     try {
       const connection = await manager.connect(name, definition);
+      if (connection.status === "needs-auth") {
+        return { name, definition, connection: null, error: `OAuth authentication required. Run /mcp-auth ${name}.` };
+      }
       return { name, definition, connection, error: null };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -169,11 +172,16 @@ export async function initializeMcp(
           const definition = config.mcpServers[name];
           try {
             const connection = await manager.connect(name, definition);
+            if (connection.status === "needs-auth") {
+              return { name, ok: false };
+            }
             const { metadata } = buildToolMetadata(connection.tools, connection.resources, definition, name, prefix);
             toolMetadata.set(name, metadata);
             updateMetadataCache(state, name);
             return { name, ok: true };
-          } catch {
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.debug(`MCP: direct-tools bootstrap failed for ${name}: ${message}`);
             return { name, ok: false };
           }
         },
@@ -279,6 +287,9 @@ export function getFailureAgeSeconds(state: McpExtensionState, serverName: strin
 
 export async function lazyConnect(state: McpExtensionState, serverName: string): Promise<boolean> {
   const connection = state.manager.getConnection(serverName);
+  if (connection?.status === "needs-auth") {
+    return false;
+  }
   if (connection?.status === "connected") {
     updateServerMetadata(state, serverName);
     return true;
@@ -294,14 +305,19 @@ export async function lazyConnect(state: McpExtensionState, serverName: string):
     if (state.ui) {
       state.ui.setStatus("mcp", `MCP: connecting to ${serverName}...`);
     }
-    await state.manager.connect(serverName, definition);
+    const newConnection = await state.manager.connect(serverName, definition);
+    if (newConnection.status === "needs-auth") {
+      return false;
+    }
     state.failureTracker.delete(serverName);
     updateServerMetadata(state, serverName);
     updateMetadataCache(state, serverName);
     updateStatusBar(state);
     return true;
-  } catch {
+  } catch (error) {
     state.failureTracker.set(serverName, Date.now());
+    const message = error instanceof Error ? error.message : String(error);
+    logger.debug(`MCP: lazy connect failed for ${serverName}: ${message}`);
     updateStatusBar(state);
     return false;
   }

package/mcp-auth-flow.ts

@@ -0,0 +1,378 @@
+/**
+ * MCP Auth Flow
+ * 
+ * High-level OAuth flow management using the MCP SDK's built-in auth functions.
+ * Follows the OpenCode pattern: let the SDK handle discovery internally via transport.
+ */
+
+import {
+  UnauthorizedError,
+} from "@modelcontextprotocol/sdk/client/auth.js"
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import open from "open"
+import { McpOAuthProvider, type McpOAuthConfig } from "./mcp-oauth-provider.js"
+import {
+  ensureCallbackServer,
+  waitForCallback,
+  cancelPendingCallback,
+  stopCallbackServer,
+} from "./mcp-callback-server.js"
+import {
+  getAuthForUrl,
+  isTokenExpired,
+  hasStoredTokens,
+  clearAllCredentials,
+  updateOAuthState,
+  getOAuthState,
+  clearOAuthState,
+  type StoredTokens,
+} from "./mcp-auth.js"
+import type { ServerEntry } from "./types.js"
+
+/** Auth status for a server */
+export type AuthStatus = "authenticated" | "expired" | "not_authenticated"
+
+// Track pending transports for auth completion
+const pendingTransports = new Map<string, StreamableHTTPClientTransport>()
+
+/**
+ * Generate a cryptographically secure random state parameter.
+ */
+function generateState(): string {
+  return Array.from(crypto.getRandomValues(new Uint8Array(32)))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+}
+
+/**
+ * Extract OAuth configuration from a ServerEntry.
+ */
+function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig {
+  // If oauth is explicitly false, return empty config
+  if (definition.oauth === false) {
+    return {}
+  }
+  return {
+    grantType: definition.oauth?.grantType,
+    clientId: definition.oauth?.clientId,
+    clientSecret: definition.oauth?.clientSecret,
+    scope: definition.oauth?.scope,
+  }
+}
+
+/**
+ * Start OAuth authentication flow for a server.
+ * Returns the authorization URL that should be opened in a browser.
+ * 
+ * This follows the OpenCode pattern:
+ * 1. Create transport with auth provider
+ * 2. Try to connect - SDK handles discovery internally
+ * 3. If UnauthorizedError, capture the auth URL from onRedirect
+ */
+export async function startAuth(
+  serverName: string,
+  serverUrl: string,
+  definition?: ServerEntry
+): Promise<{ authorizationUrl: string; transport: StreamableHTTPClientTransport }> {
+  const config = definition ? extractOAuthConfig(definition) : {}
+
+  if (config.grantType === "client_credentials") {
+    const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
+      onRedirect: async () => {
+        throw new Error("Browser redirect is not used for client_credentials flow")
+      },
+    })
+    const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+      authProvider,
+    })
+    const client = new Client({
+      name: "pi-mcp",
+      version: "3.0.0",
+    })
+
+    try {
+      await client.connect(transport)
+      return { authorizationUrl: "", transport }
+    } finally {
+      await client.close().catch(() => {})
+      await transport.close().catch(() => {})
+    }
+  }
+
+  // Start the callback server
+  await ensureCallbackServer()
+
+  // Generate and store OAuth state BEFORE creating the provider
+  // The SDK will call provider.state() to read this value
+  const oauthState = generateState()
+  await updateOAuthState(serverName, oauthState)
+
+  // Create the auth provider
+  let capturedUrl: URL | undefined
+  const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
+    onRedirect: async (url) => {
+      capturedUrl = url
+    },
+  })
+
+  // Create transport with auth provider
+  // The SDK handles OAuth discovery internally when connecting
+  const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+    authProvider,
+  })
+  const client = new Client({
+    name: "pi-mcp",
+    version: "3.0.0",
+  })
+
+  // Try to connect - this triggers the OAuth flow
+  try {
+    await client.connect(transport)
+    // If we get here, we're already authenticated
+    await client.close().catch(() => {})
+    await transport.close().catch(() => {})
+    return { authorizationUrl: "", transport }
+  } catch (error) {
+    if (error instanceof UnauthorizedError && capturedUrl) {
+      await client.close().catch(() => {})
+      // Store transport for later finishAuth
+      pendingTransports.set(serverName, transport)
+      return { authorizationUrl: capturedUrl.toString(), transport }
+    }
+    await client.close().catch(() => {})
+    await transport.close().catch(() => {})
+    throw error
+  }
+}
+
+/**
+ * Complete OAuth authentication with the authorization code.
+ */
+export async function completeAuth(
+  serverName: string,
+  authorizationCode: string
+): Promise<AuthStatus> {
+  const transport = pendingTransports.get(serverName)
+  if (!transport) {
+    throw new Error(`No pending OAuth flow for server: ${serverName}`)
+  }
+
+  try {
+    // Complete the auth using the transport's finishAuth method
+    await transport.finishAuth(authorizationCode)
+    return "authenticated"
+  } finally {
+    pendingTransports.delete(serverName)
+    await transport.close().catch(() => {})
+  }
+}
+
+/**
+ * Perform the complete OAuth authentication flow for a server.
+ * 
+ * @param serverName - The name of the MCP server
+ * @param serverUrl - The URL of the MCP server  
+ * @param definition - The server definition (optional)
+ * @returns The final auth status
+ */
+export async function authenticate(
+  serverName: string,
+  serverUrl: string,
+  definition?: ServerEntry,
+): Promise<AuthStatus> {
+  // Start auth flow
+  const { authorizationUrl } = await startAuth(serverName, serverUrl, definition)
+
+  // If no auth URL needed, already authenticated
+  if (!authorizationUrl) {
+    return "authenticated"
+  }
+
+  // Get the state that was already generated and stored in startAuth()
+  const oauthState = await getOAuthState(serverName)
+  if (!oauthState) {
+    throw new Error("OAuth state not found - this should not happen")
+  }
+
+  // Register the callback BEFORE opening the browser
+  const callbackPromise = waitForCallback(oauthState)
+
+  // Open browser
+  console.log(`MCP Auth: Opening browser for ${serverName}`)
+  try {
+    await open(authorizationUrl)
+  } catch (error) {
+    console.warn(`MCP Auth: Failed to open browser for ${serverName}`, { error })
+    throw new Error(
+      `Could not open browser. Please open this URL manually: ${authorizationUrl}`
+    )
+  }
+
+  try {
+    // Wait for callback
+    const code = await callbackPromise
+
+    // Validate state
+    const storedState = await getOAuthState(serverName)
+    if (storedState !== oauthState) {
+      await clearOAuthState(serverName)
+      throw new Error("OAuth state mismatch - potential CSRF attack")
+    }
+    await clearOAuthState(serverName)
+
+    // Complete the auth
+    return await completeAuth(serverName, code)
+  } catch (error) {
+    cancelPendingCallback(oauthState)
+    const pendingTransport = pendingTransports.get(serverName)
+    if (pendingTransport) {
+      pendingTransports.delete(serverName)
+      await pendingTransport.close().catch(() => {})
+    }
+    throw error
+  }
+}
+
+/**
+ * Get a valid access token for a server, refreshing if necessary.
+ * 
+ * @param serverName - The name of the MCP server
+ * @param serverUrl - The URL of the MCP server
+ * @returns The valid tokens or null if not authenticated
+ */
+export async function getValidToken(
+  serverName: string,
+  serverUrl: string,
+): Promise<StoredTokens | null> {
+  // Check if we have valid tokens
+  const entry = await getAuthForUrl(serverName, serverUrl)
+  if (!entry?.tokens) {
+    return null
+  }
+
+  // Check expiration
+  const expired = await isTokenExpired(serverName)
+  if (expired === false) {
+    return entry.tokens
+  }
+
+  if (expired === true && entry.tokens.refreshToken) {
+    // Token is expired, try to refresh
+    console.log(`MCP Auth: Token expired for ${serverName}, attempting refresh`)
+
+    try {
+      // Create auth provider for token refresh
+      const authProvider = new McpOAuthProvider(serverName, serverUrl, {}, {
+        onRedirect: async () => {},
+      })
+
+      const clientInfo = await authProvider.clientInformation()
+      if (!clientInfo) {
+        console.log(`MCP Auth: No client info for refresh for ${serverName}`)
+        return null
+      }
+
+      // Try to get tokens to find the token endpoint
+      const existingTokens = await authProvider.tokens()
+      if (!existingTokens) {
+        return null
+      }
+
+      // Create transport to trigger refresh
+      const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+        authProvider,
+      })
+
+      // Try to connect - SDK will attempt token refresh internally
+      const client = new Client({ name: "pi-mcp", version: "3.0.0" })
+      try {
+        await client.connect(transport)
+        // Get refreshed tokens
+        const refreshed = await getAuthForUrl(serverName, serverUrl)
+        return refreshed?.tokens ?? null
+      } catch (error) {
+        console.error(`MCP Auth: Token refresh failed for ${serverName}`, { error })
+        return null
+      } finally {
+        await client.close().catch(() => {})
+        await transport.close().catch(() => {})
+      }
+    } catch (error) {
+      console.error(`MCP Auth: Token refresh failed for ${serverName}`, { error })
+      return null
+    }
+  }
+
+  // No expiration info or no refresh token, assume valid
+  return entry.tokens
+}
+
+/**
+ * Check the authentication status for a server.
+ * 
+ * @param serverName - The name of the MCP server
+ * @returns The current auth status
+ */
+export async function getAuthStatus(serverName: string): Promise<AuthStatus> {
+  const hasTokens = await hasStoredTokens(serverName)
+  if (!hasTokens) return "not_authenticated"
+
+  const expired = await isTokenExpired(serverName)
+  return expired ? "expired" : "authenticated"
+}
+
+/**
+ * Remove all OAuth credentials for a server.
+ * 
+ * @param serverName - The name of the MCP server
+ */
+export async function removeAuth(serverName: string): Promise<void> {
+  const oauthState = await getOAuthState(serverName)
+  if (oauthState) {
+    cancelPendingCallback(oauthState)
+  }
+  const pendingTransport = pendingTransports.get(serverName)
+  if (pendingTransport) {
+    pendingTransports.delete(serverName)
+    await pendingTransport.close().catch(() => {})
+  }
+  clearAllCredentials(serverName)
+  await clearOAuthState(serverName)
+  console.log(`MCP Auth: Removed credentials for ${serverName}`)
+}
+
+/**
+ * Check if OAuth is supported for a server configuration.
+ * OAuth is supported for HTTP servers unless explicitly disabled.
+ * 
+ * @param definition - The server definition
+ * @returns True if OAuth is supported
+ */
+export function supportsOAuth(definition: ServerEntry): boolean {
+  // OAuth requires a URL
+  if (!definition.url) return false
+  
+  // Explicitly disabled via auth: false or oauth: false
+  if (definition.auth === false) return false
+  if (definition.oauth === false) return false
+  
+  // OAuth is enabled if auth is 'oauth' or not specified (auto-detect)
+  return definition.auth === "oauth" || definition.auth === undefined
+}
+
+/**
+ * Initialize the OAuth system on startup.
+ * Starts the callback server if there are any OAuth servers configured.
+ */
+export async function initializeOAuth(): Promise<void> {
+  await ensureCallbackServer()
+}
+
+/**
+ * Shutdown the OAuth system.
+ * Stops the callback server and cancels pending auths.
+ */
+export async function shutdownOAuth(): Promise<void> {
+  await stopCallbackServer()
+}