pi-mcp-adapter 2.2.1 → 2.3.2

package/CHANGELOG.md

@@ -7,6 +7,42 @@ 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
+- Session lifecycle teardown now handles repeated `session_start` transitions safely and prevents stale async init results from replacing newer state.
+- Shutdown now still runs `gracefulShutdown()` even if metadata cache flushing throws, avoiding leaked MCP processes.
+- Proxy/direct tool init error paths now preserve and surface underlying error messages instead of returning generic failures.
+- Invalid `mcp` tool `args` now fail by throwing with parse/type context instead of returning non-failing tool payloads.
+- Added focused lifecycle regressions tests for stale init cleanup and init-error visibility.
+
 ## [2.2.1] - 2026-03-23
 
 ### 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

@@ -181,10 +181,11 @@ export function createDirectToolExecutor(
     if (!state && initPromise) {
       try {
         state = await initPromise;
-      } catch {
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
         return {
-          content: [{ type: "text" as const, text: "MCP initialization failed" }],
-          details: { error: "init_failed" },
+          content: [{ type: "text" as const, text: `MCP initialization failed: ${message}` }],
+          details: { error: "init_failed", message },
         };
       }
     }
@@ -197,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

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ToolInfo } from "@mariozechner/pi-coding-agent";
 import type { McpExtensionState } from "./state.js";
 import { Type } from "@sinclair/typebox";
 import { showStatus, showTools, reconnectServers, authenticateServer, openMcpPanel } from "./commands.js";
@@ -8,10 +8,42 @@ 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;
   let initPromise: Promise<McpExtensionState> | null = null;
+  let lifecycleGeneration = 0;
+
+  async function shutdownState(currentState: McpExtensionState | null, reason: string): Promise<void> {
+    if (!currentState) return;
+
+    if (currentState.uiServer) {
+      currentState.uiServer.close(reason);
+      currentState.uiServer = null;
+    }
+
+    let flushError: unknown;
+    try {
+      flushMetadataCache(currentState);
+    } catch (error) {
+      flushError = error;
+    }
+
+    try {
+      await currentState.lifecycle.gracefulShutdown();
+    } catch (error) {
+      if (flushError) {
+        console.error("MCP: graceful shutdown failed after metadata flush error", error);
+      } else {
+        throw error;
+      }
+    }
+
+    if (flushError) {
+      throw flushError;
+    }
+  }
 
   const earlyConfigPath = getConfigPathFromArgv();
   const earlyConfig = loadMcpConfig(earlyConfigPath);
@@ -47,35 +79,63 @@ export default function mcpAdapter(pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    initPromise = initializeMcp(pi, ctx);
+    const generation = ++lifecycleGeneration;
+    const previousState = state;
+    state = null;
+    initPromise = null;
+
+    try {
+      await shutdownState(previousState, "session_restart");
+    } catch (error) {
+      console.error("MCP: failed to shut down previous session state", error);
+    }
+
+    if (generation !== lifecycleGeneration) {
+      return;
+    }
+
+    await initializeOAuth().catch(err => {
+      console.error("MCP OAuth initialization failed:", err);
+    });
 
-    initPromise.then(s => {
-      state = s;
+    const promise = initializeMcp(pi, ctx);
+    initPromise = promise;
+
+    promise.then(async (nextState) => {
+      if (generation !== lifecycleGeneration || initPromise !== promise) {
+        try {
+          await shutdownState(nextState, "stale_session_start");
+        } catch (error) {
+          console.error("MCP: failed to clean stale session state", error);
+        }
+        return;
+      }
+
+      state = nextState;
+      updateStatusBar(nextState);
       initPromise = null;
-      updateStatusBar(s);
     }).catch(err => {
+      if (generation !== lifecycleGeneration) {
+        return;
+      }
+      if (initPromise !== promise && initPromise !== null) {
+        return;
+      }
       console.error("MCP initialization failed:", err);
       initPromise = null;
     });
   });
 
   pi.on("session_shutdown", async () => {
-    if (initPromise) {
-      try {
-        state = await initPromise;
-      } catch {
-        // Initialization failed, nothing to clean up
-      }
-    }
+    ++lifecycleGeneration;
+    const currentState = state;
+    state = null;
+    initPromise = null;
 
-    if (state) {
-      if (state.uiServer) {
-        state.uiServer.close("session_shutdown");
-        state.uiServer = null;
-      }
-      flushMetadataCache(state);
-      await state.lifecycle.gracefulShutdown();
-      state = null;
+    try {
+      await shutdownState(currentState, "session_shutdown");
+    } catch (error) {
+      console.error("MCP: session shutdown cleanup failed", error);
     }
   });
 
@@ -85,8 +145,9 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       if (!state && initPromise) {
         try {
           state = await initPromise;
-        } catch {
-          if (ctx.hasUI) ctx.ui.notify("MCP initialization failed", "error");
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (ctx.hasUI) ctx.ui.notify(`MCP initialization failed: ${message}`, "error");
           return;
         }
       }
@@ -131,8 +192,9 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       if (!state && initPromise) {
         try {
           state = await initPromise;
-        } catch {
-          if (ctx.hasUI) ctx.ui.notify("MCP initialization failed", "error");
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (ctx.hasUI) ctx.ui.notify(`MCP initialization failed: ${message}`, "error");
           return;
         }
       }
@@ -178,28 +240,24 @@ export default function mcpAdapter(pi: ExtensionAPI) {
           parsedArgs = JSON.parse(params.args);
           if (typeof parsedArgs !== "object" || parsedArgs === null || Array.isArray(parsedArgs)) {
             const gotType = Array.isArray(parsedArgs) ? "array" : parsedArgs === null ? "null" : typeof parsedArgs;
-            return {
-              content: [{ type: "text" as const, text: `Invalid args: expected a JSON object, got ${gotType}` }],
-              isError: true,
-              details: { error: "invalid_args_type" },
-            };
+            throw new Error(`Invalid args: expected a JSON object, got ${gotType}`);
           }
-        } catch (e) {
-          return {
-            content: [{ type: "text" as const, text: `Invalid args JSON: ${e instanceof Error ? e.message : e}` }],
-            isError: true,
-            details: { error: "invalid_args" },
-          };
+        } catch (error) {
+          if (error instanceof SyntaxError) {
+            throw new Error(`Invalid args JSON: ${error.message}`, { cause: error });
+          }
+          throw error;
         }
       }
 
       if (!state && initPromise) {
         try {
           state = await initPromise;
-        } catch {
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
           return {
-            content: [{ type: "text" as const, text: "MCP initialization failed" }],
-            details: { error: "init_failed" },
+            content: [{ type: "text" as const, text: `MCP initialization failed: ${message}` }],
+            details: { error: "init_failed", message },
           };
         }
       }

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