npm - pi-mcp-adapter - Versions diffs - 2.3.3 → 2.3.5 - Mend

pi-mcp-adapter 2.3.3 → 2.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [2.3.5] - 2026-04-13
+### Fixed
+- Session lifecycle now always tears down OAuth callback state on restart and shutdown, preventing callback-server leaks across session transitions.
+- OAuth callback server now calls `unref()` after successful bind so it no longer keeps sub-agent processes alive by itself.
+- Strict OAuth port mode now rebinds to the configured callback port when safe, while refusing to switch ports when authorizations are still pending.
+- Added focused lifecycle/callback-server regression coverage for teardown, `unref()`, strict rebinding, and pending-auth guardrails.
+- Thanks @blai for the investigation and PR #43 that surfaced the sub-agent hang/root lifecycle issues.
+## [2.3.4] - 2026-04-12
+### Fixed
+- OAuth callback handling now allows dynamic-registration flows to fall back to a free local port when the preferred callback port is busy, while keeping pre-registered clients on their exact configured redirect port.
+- Documented the new callback-port behavior and added focused auth-flow regression coverage.
 ## [2.3.3] - 2026-04-12
 ### Fixed

package/index.ts CHANGED Viewed

@@ -8,7 +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";
+import { initializeOAuth, shutdownOAuth } from "./mcp-auth-flow.js";
 export default function mcpAdapter(pi: ExtensionAPI) {
   let state: McpExtensionState | null = null;
@@ -85,7 +85,10 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     initPromise = null;
     try {
-      await shutdownState(previousState, "session_restart");
+      await Promise.all([
+        shutdownState(previousState, "session_restart"),
+        shutdownOAuth(),
+      ]);
     } catch (error) {
       console.error("MCP: failed to shut down previous session state", error);
     }
@@ -133,7 +136,10 @@ export default function mcpAdapter(pi: ExtensionAPI) {
     initPromise = null;
     try {
-      await shutdownState(currentState, "session_shutdown");
+      await Promise.all([
+        shutdownState(currentState, "session_shutdown"),
+        shutdownOAuth(),
+      ]);
     } catch (error) {
       console.error("MCP: session shutdown cleanup failed", error);
     }

package/mcp-auth-flow.ts CHANGED Viewed

@@ -100,8 +100,9 @@ export async function startAuth(
     }
   }
-  // Start the callback server
-  await ensureCallbackServer()
+  // Start the callback server.
+  // Pre-registered OAuth clients require an exact redirect URI, so enforce strict port binding.
+  await ensureCallbackServer({ strictPort: Boolean(config.clientId) })
   // Generate and store OAuth state BEFORE creating the provider
   // The SDK will call provider.state() to read this value

package/mcp-callback-server.ts CHANGED Viewed

@@ -6,8 +6,12 @@
  */
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http"
-import { connect } from "net"
-import { OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_PATH } from "./mcp-oauth-provider.js"
+import {
+  OAUTH_CALLBACK_PATH,
+  getConfiguredOAuthCallbackPort,
+  getOAuthCallbackPort,
+  setOAuthCallbackPort,
+} from "./mcp-oauth-provider.js"
 // HTML templates for callback responses
 const HTML_SUCCESS = `<!DOCTYPE html>
@@ -65,29 +69,10 @@ const pendingAuths = new Map<string, PendingAuth>()
 /** Timeout for callback completion (5 minutes) */
 const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
-/**
- * Check if the callback port is already in use.
- * Used to detect if another instance is running the server.
- */
-async function isPortInUse(): Promise<boolean> {
-  return new Promise((resolve) => {
-    const socket = connect({ host: "127.0.0.1", port: OAUTH_CALLBACK_PORT })
-    socket.setTimeout(1000)
-    socket.on("connect", () => {
-      socket.end()
-      resolve(true)
-    })
+const MAX_PORT_SCAN_ATTEMPTS = 25
-    socket.on("error", () => {
-      resolve(false)
-    })
-    socket.on("timeout", () => {
-      socket.destroy()
-      resolve(false)
-    })
-  })
+interface EnsureCallbackServerOptions {
+  strictPort?: boolean
 }
 /**
@@ -160,27 +145,73 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
 /**
  * Ensure the callback server is running.
- * If the port is in use by another process, fail fast with a clear error.
+ * If strictPort is true, requires binding on the configured callback port.
+ * If strictPort is false, scans forward for an available local port.
  */
-export async function ensureCallbackServer(): Promise<void> {
-  if (server) return
+export async function ensureCallbackServer(options: EnsureCallbackServerOptions = {}): Promise<void> {
+  const configuredPort = getConfiguredOAuthCallbackPort()
+  const strictPort = options.strictPort === true
-  const running = await isPortInUse()
-  if (running) {
-    throw new Error(`OAuth callback port ${OAUTH_CALLBACK_PORT} is already in use`)
+  if (server) {
+    if (!strictPort || getOAuthCallbackPort() === configuredPort) return
+    if (pendingAuths.size > 0) {
+      throw new Error(
+        `OAuth callback server is running on port ${getOAuthCallbackPort()}, but strict callback port ${configuredPort} is required and cannot be switched while authorizations are pending`
+      )
+    }
+    await stopCallbackServer()
   }
-  server = createServer(handleRequest)
+  const preferredPort = configuredPort
+  const maxAttempts = strictPort ? 1 : MAX_PORT_SCAN_ATTEMPTS
+  let lastError: Error | undefined
-  await new Promise<void>((resolve, reject) => {
-    server!.once("error", (err) => {
-      reject(err)
-    })
+  for (let offset = 0; offset < maxAttempts; offset++) {
+    const candidatePort = preferredPort + offset
+    const candidateServer = createServer(handleRequest)
-    server!.listen(OAUTH_CALLBACK_PORT, "127.0.0.1", () => {
-      resolve()
-    })
-  })
+    try {
+      await new Promise<void>((resolve, reject) => {
+        candidateServer.once("error", (err) => {
+          reject(err)
+        })
+        candidateServer.listen(candidatePort, "127.0.0.1", () => {
+          resolve()
+        })
+      })
+      server = candidateServer
+      server.unref()
+      setOAuthCallbackPort(candidatePort)
+      return
+    } catch (error) {
+      const nodeError = error as NodeJS.ErrnoException
+      await new Promise<void>((resolve) => {
+        candidateServer.close(() => resolve())
+      })
+      if (nodeError.code !== "EADDRINUSE") {
+        throw error
+      }
+      lastError = error instanceof Error ? error : new Error(String(error))
+    }
+  }
+  if (strictPort) {
+    throw new Error(
+      `OAuth callback port ${preferredPort} is already in use. Pre-registered OAuth clients require an exact redirect URI; set MCP_OAUTH_CALLBACK_PORT to your registered port or free port ${preferredPort}`,
+      { cause: lastError }
+    )
+  }
+  throw new Error(
+    `OAuth callback port ${preferredPort} is already in use and no free port was found in range ${preferredPort}-${preferredPort + MAX_PORT_SCAN_ATTEMPTS - 1}`,
+    { cause: lastError }
+  )
 }
 /**
@@ -225,11 +256,13 @@ export async function stopCallbackServer(): Promise<void> {
     server = undefined
   }
+  setOAuthCallbackPort(getConfiguredOAuthCallbackPort())
   // Reject all pending auths (defer to allow any pending operations to complete)
   const pendingList = Array.from(pendingAuths.entries())
   pendingAuths.clear()
   setTimeout(() => {
-    for (const [state, pending] of pendingList) {
+    for (const [, pending] of pendingList) {
       clearTimeout(pending.timeout)
       pending.reject(new Error("OAuth callback server stopped"))
     }

package/mcp-oauth-provider.ts CHANGED Viewed

@@ -27,9 +27,32 @@ import {
 } from "./mcp-auth.js"
 // Callback server configuration
-const OAUTH_CALLBACK_PORT = 19876
+const DEFAULT_OAUTH_CALLBACK_PORT = 19876
 const OAUTH_CALLBACK_PATH = "/mcp/oauth/callback"
+let configuredOAuthCallbackPort = DEFAULT_OAUTH_CALLBACK_PORT
+if (process.env.MCP_OAUTH_CALLBACK_PORT) {
+  const parsedPort = Number.parseInt(process.env.MCP_OAUTH_CALLBACK_PORT, 10)
+  if (Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535) {
+    configuredOAuthCallbackPort = parsedPort
+  }
+}
+let oauthCallbackPort = configuredOAuthCallbackPort
+export function getConfiguredOAuthCallbackPort(): number {
+  return configuredOAuthCallbackPort
+}
+export function getOAuthCallbackPort(): number {
+  return oauthCallbackPort
+}
+export function setOAuthCallbackPort(port: number): void {
+  oauthCallbackPort = port
+}
 /** Configuration options for OAuth */
 export interface McpOAuthConfig {
   grantType?: "authorization_code" | "client_credentials"
@@ -65,7 +88,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
    */
   get redirectUrl(): string | undefined {
     if (this.usesClientCredentials) return undefined
-    return `http://127.0.0.1:${OAUTH_CALLBACK_PORT}${OAUTH_CALLBACK_PATH}`
+    return `http://127.0.0.1:${getOAuthCallbackPort()}${OAUTH_CALLBACK_PATH}`
   }
   /**
@@ -262,4 +285,4 @@ export class McpOAuthProvider implements OAuthClientProvider {
   }
 }
-export { OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_PATH }
+export { DEFAULT_OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_PATH }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.3.3",
+  "version": "2.3.5",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "license": "MIT",