pi-mcp-adapter 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-06-04
+
+### Added
+- Added MCP elicitation support with Pi form prompts and browser-opening URL requests.
+
+### Fixed
+- Rejected non-http/https MCP URL elicitations before prompting or opening a browser.
+- Preserved empty string form values for MCP string elicitations unless schema constraints reject them.
+
+## [2.8.0] - 2026-05-25
+
+### Added
+- Added per-server OAuth `redirectUri`, `clientName`, and `clientUri` overrides for pre-registered callbacks and dynamic client metadata.
+
+### Fixed
+- Avoided OAuth callback port exhaustion by starting the callback server lazily and using OS-assigned ports for dynamic OAuth flows.
+- Re-register dynamic OAuth clients before browser auth when cached redirect URI metadata is missing or no longer matches the active callback URI.
+
 ## [2.7.0] - 2026-05-22
 
 ### Added

package/README.md

@@ -126,6 +126,12 @@ Pi-specific files are the write targets for imported or shared global servers wh
 | `headers` | HTTP headers; supports `${VAR}` and `$env:VAR` interpolation |
 | `auth` | `"bearer"` or `"oauth"` |
 | `oauth.grantType` | `"authorization_code"` (default) or `"client_credentials"` for non-interactive machine auth |
+| `oauth.clientId` | Pre-registered OAuth client ID; dynamic registration is used when omitted |
+| `oauth.clientSecret` | OAuth client secret for confidential clients |
+| `oauth.scope` | Requested OAuth scopes |
+| `oauth.redirectUri` | Exact localhost redirect URI for browser OAuth, including port and path, for providers that pre-register callbacks |
+| `oauth.clientName` | Client display name advertised during dynamic registration |
+| `oauth.clientUri` | Client homepage URI advertised during dynamic registration |
 | `bearerToken` / `bearerTokenEnv` | Token or env var name; `bearerToken` supports `${VAR}` and `$env:VAR` interpolation |
 | `lifecycle` | `"lazy"` (default), `"eager"`, or `"keep-alive"` |
 | `idleTimeout` | Minutes before idle disconnect (overrides global) |
@@ -134,6 +140,8 @@ Pi-specific files are the write targets for imported or shared global servers wh
 | `excludeTools` | `string[]` of tool names to hide (matches original names like `get_screenshot` and prefixed names like `figma_get_screenshot`) |
 | `debug` | Show server stderr (default: false) |
 
+For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port.
+
 ### Lifecycle Modes
 
 - **`lazy`** (default) — Don't connect at startup. Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
@@ -161,9 +169,15 @@ Pi-specific files are the write targets for imported or shared global servers wh
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
 | `sampling` | Allow MCP servers to sample through Pi models, honoring `modelPreferences.hints` before current/default fallback (default: true when UI approval is available). |
 | `samplingAutoApprove` | Skip sampling confirmation prompts. Required for sampling in non-UI sessions (default: false). |
+| `elicitation` | Allow MCP servers to request user input through Pi UI forms/URL prompts (default: true when Pi UI form support is available). |
+| `elicitationAutoOpenUrls` | Automatically open URL elicitations without prompting first (default: false). |
 
 Per-server `idleTimeout` overrides the global setting.
 
+### MCP Elicitation
+
+When Pi exposes UI, the adapter advertises MCP elicitation support. Form elicitations are rendered with `ctx.ui.form()` and map Pi actions to MCP actions: submit → `accept`, secondary → `decline`, cancel → `cancel`. URL elicitations prompt before opening a browser unless `elicitationAutoOpenUrls` is enabled.
+
 ### Direct Tools
 
 By default, all MCP tools are accessed through the single `mcp` proxy tool. This keeps context small but means the LLM has to discover MCP tools via proxy search. If you want specific tools to show up directly in the agent's tool list — alongside `read`, `bash`, `edit`, etc. — add `directTools` to your config.

package/elicitation-handler.ts

@@ -0,0 +1,353 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  ElicitRequestSchema,
+  type ElicitRequest,
+  type ElicitRequestFormParams,
+  type ElicitRequestURLParams,
+  type ElicitResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import open from "open";
+
+export type ExtensionUIFormValue = string | number | boolean | string[] | undefined;
+
+export interface ExtensionUIFormSelectOption {
+  value: string;
+  label?: string;
+  description?: string;
+}
+
+export type ExtensionUIFormField =
+  | {
+      type: "text";
+      name: string;
+      label: string;
+      description?: string;
+      placeholder?: string;
+      required?: boolean;
+      defaultValue?: string;
+      minLength?: number;
+      maxLength?: number;
+      pattern?: string;
+    }
+  | {
+      type: "number" | "integer";
+      name: string;
+      label: string;
+      description?: string;
+      required?: boolean;
+      defaultValue?: number;
+      minimum?: number;
+      maximum?: number;
+    }
+  | {
+      type: "boolean";
+      name: string;
+      label: string;
+      description?: string;
+      defaultValue?: boolean;
+    }
+  | {
+      type: "select";
+      name: string;
+      label: string;
+      description?: string;
+      required?: boolean;
+      options: ExtensionUIFormSelectOption[];
+      defaultValue?: string;
+    }
+  | {
+      type: "multiSelect";
+      name: string;
+      label: string;
+      description?: string;
+      required?: boolean;
+      options: ExtensionUIFormSelectOption[];
+      defaultValue?: string[];
+    };
+
+export interface ExtensionUIFormRequest {
+  title: string;
+  message?: string;
+  fields: ExtensionUIFormField[];
+  submitLabel?: string;
+  secondaryLabel?: string;
+  cancelLabel?: string;
+}
+
+export type ExtensionUIFormResult =
+  | { action: "submit"; values: Record<string, ExtensionUIFormValue> }
+  | { action: "secondary" }
+  | { action: "cancel" };
+
+export interface ElicitationUIContext extends ExtensionUIContext {
+  form(request: ExtensionUIFormRequest): Promise<ExtensionUIFormResult>;
+}
+
+export interface ElicitationHandlerOptions {
+  serverName: string;
+  ui: ElicitationUIContext;
+  autoOpenUrls: boolean;
+}
+
+export type ServerElicitationConfig = Omit<ElicitationHandlerOptions, "serverName">;
+
+export function registerElicitationHandler(client: Client, options: ElicitationHandlerOptions): void {
+  client.setRequestHandler(ElicitRequestSchema, (request) => {
+    return handleElicitationRequest(options, request as ElicitRequest);
+  });
+}
+
+export async function handleElicitationRequest(
+  options: ElicitationHandlerOptions,
+  request: ElicitRequest,
+): Promise<ElicitResult> {
+  const params = request.params;
+  if (params.mode === "url") {
+    return handleUrlElicitation(options, params);
+  }
+  return handleFormElicitation(options, params);
+}
+
+export async function handleFormElicitation(
+  options: ElicitationHandlerOptions,
+  params: ElicitRequestFormParams,
+): Promise<ElicitResult> {
+  const form = convertMcpSchemaToPiForm(options.serverName, params);
+  const result = await options.ui.form(form);
+  if (result.action !== "submit") {
+    return convertPiFormResultToMcpResult(result);
+  }
+  return {
+    action: "accept",
+    content: coerceAndValidateFormValues(params, result.values),
+  };
+}
+
+export async function handleUrlElicitation(
+  options: ElicitationHandlerOptions,
+  params: ElicitRequestURLParams,
+): Promise<ElicitResult> {
+  const browserUrl = getBrowserElicitationUrl(params.url);
+  if (!options.autoOpenUrls) {
+    const result = await options.ui.form({
+      title: "MCP Browser Request",
+      message: [
+        `Server: ${options.serverName}`,
+        "",
+        params.message,
+        "",
+        `Domain: ${browserUrl.host}`,
+        `URL: ${browserUrl.toString()}`,
+        "",
+        "Open this URL in your browser?",
+      ].join("\n"),
+      fields: [],
+      submitLabel: "Open",
+      secondaryLabel: "Decline",
+      cancelLabel: "Cancel",
+    });
+    if (result.action === "secondary") return { action: "decline" };
+    if (result.action === "cancel") return { action: "cancel" };
+  }
+
+  await open(browserUrl.toString());
+  options.ui.notify("Opened browser for MCP elicitation.", "info");
+  return { action: "accept" };
+}
+
+export function convertMcpSchemaToPiForm(
+  serverName: string,
+  params: ElicitRequestFormParams,
+): ExtensionUIFormRequest {
+  const required = new Set(params.requestedSchema.required ?? []);
+  return {
+    title: "MCP Input Request",
+    message: `Server: ${serverName}\n\n${params.message}`,
+    submitLabel: "Submit",
+    secondaryLabel: "Decline",
+    cancelLabel: "Cancel",
+    fields: Object.entries(params.requestedSchema.properties).map(([name, schema]): ExtensionUIFormField => {
+      const label = schema.title ?? humanizeName(name);
+      const base = {
+        name,
+        label,
+        description: schema.description,
+        required: required.has(name),
+      };
+
+      if (schema.type === "string" && "oneOf" in schema && Array.isArray(schema.oneOf)) {
+        return omitUndefined({
+          ...base,
+          type: "select" as const,
+          options: schema.oneOf.map((option) => ({ value: option.const, label: option.title })),
+          defaultValue: schema.default,
+        });
+      }
+
+      if (schema.type === "string" && "enum" in schema && Array.isArray(schema.enum)) {
+        const enumNames = "enumNames" in schema && Array.isArray(schema.enumNames) ? schema.enumNames : undefined;
+        return omitUndefined({
+          ...base,
+          type: "select" as const,
+          options: schema.enum.map((value, index) => omitUndefined({ value, label: enumNames?.[index] })),
+          defaultValue: schema.default,
+        });
+      }
+
+      if (schema.type === "array") {
+        return omitUndefined({
+          ...base,
+          type: "multiSelect" as const,
+          options: extractMultiSelectOptions(schema),
+          defaultValue: schema.default,
+        });
+      }
+
+      if (schema.type === "number" || schema.type === "integer") {
+        return omitUndefined({
+          ...base,
+          type: schema.type,
+          defaultValue: schema.default,
+          minimum: schema.minimum,
+          maximum: schema.maximum,
+        });
+      }
+
+      if (schema.type === "boolean") {
+        return omitUndefined({
+          type: "boolean" as const,
+          name,
+          label,
+          description: schema.description,
+          defaultValue: schema.default,
+        });
+      }
+
+      const stringSchema = schema as { default?: string; minLength?: number; maxLength?: number };
+      return omitUndefined({
+        ...base,
+        type: "text" as const,
+        defaultValue: stringSchema.default,
+        minLength: stringSchema.minLength,
+        maxLength: stringSchema.maxLength,
+      });
+    }),
+  };
+}
+
+export function convertPiFormResultToMcpResult(result: ExtensionUIFormResult): ElicitResult {
+  if (result.action === "secondary") return { action: "decline" };
+  if (result.action === "cancel") return { action: "cancel" };
+  return { action: "accept", content: stripUndefined(result.values) as ElicitResult["content"] };
+}
+
+export function coerceAndValidateFormValues(
+  params: ElicitRequestFormParams,
+  values: Record<string, ExtensionUIFormValue>,
+): Record<string, string | number | boolean | string[]> {
+  const output: Record<string, string | number | boolean | string[]> = {};
+  const required = new Set(params.requestedSchema.required ?? []);
+
+  for (const [name, schema] of Object.entries(params.requestedSchema.properties)) {
+    const raw = values[name] ?? schema.default;
+    if (raw === undefined || (raw === "" && schema.type !== "string")) {
+      if (required.has(name)) throw new Error(`Missing required elicitation field: ${name}`);
+      continue;
+    }
+
+    if (schema.type === "string") {
+      const stringSchema = schema as { minLength?: number; maxLength?: number };
+      const value = String(raw);
+      if (stringSchema.minLength !== undefined && value.length < stringSchema.minLength) {
+        throw new Error(`Elicitation field ${name} is shorter than minimum length ${stringSchema.minLength}`);
+      }
+      if (stringSchema.maxLength !== undefined && value.length > stringSchema.maxLength) {
+        throw new Error(`Elicitation field ${name} is longer than maximum length ${stringSchema.maxLength}`);
+      }
+      if ("enum" in schema && Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+        throw new Error(`Elicitation field ${name} is not an allowed value`);
+      }
+      if ("oneOf" in schema && Array.isArray(schema.oneOf) && !schema.oneOf.some((option) => option.const === value)) {
+        throw new Error(`Elicitation field ${name} is not an allowed value`);
+      }
+      output[name] = value;
+      continue;
+    }
+
+    if (schema.type === "number" || schema.type === "integer") {
+      const value = typeof raw === "number" ? raw : Number(raw);
+      if (!Number.isFinite(value)) throw new Error(`Elicitation field ${name} must be a number`);
+      if (schema.type === "integer" && !Number.isInteger(value)) throw new Error(`Elicitation field ${name} must be an integer`);
+      if (schema.minimum !== undefined && value < schema.minimum) {
+        throw new Error(`Elicitation field ${name} is below minimum ${schema.minimum}`);
+      }
+      if (schema.maximum !== undefined && value > schema.maximum) {
+        throw new Error(`Elicitation field ${name} is above maximum ${schema.maximum}`);
+      }
+      output[name] = value;
+      continue;
+    }
+
+    if (schema.type === "boolean") {
+      output[name] = typeof raw === "boolean" ? raw : raw === "true";
+      continue;
+    }
+
+    if (schema.type === "array") {
+      if (!Array.isArray(raw)) throw new Error(`Elicitation field ${name} must be a list`);
+      const allowed = new Set(extractMultiSelectOptions(schema).map((option) => option.value));
+      const value = raw.map(String);
+      if (schema.minItems !== undefined && value.length < schema.minItems) {
+        throw new Error(`Elicitation field ${name} has fewer than ${schema.minItems} selections`);
+      }
+      if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+        throw new Error(`Elicitation field ${name} has more than ${schema.maxItems} selections`);
+      }
+      for (const item of value) {
+        if (!allowed.has(item)) throw new Error(`Elicitation field ${name} contains an invalid selection`);
+      }
+      output[name] = value;
+    }
+  }
+
+  return output;
+}
+
+function extractMultiSelectOptions(schema: Extract<ElicitRequestFormParams["requestedSchema"]["properties"][string], { type: "array" }>): ExtensionUIFormSelectOption[] {
+  const items = schema.items as { enum?: string[]; anyOf?: Array<{ const: string; title: string }> };
+  if (Array.isArray(items.anyOf)) {
+    return items.anyOf.map((option) => ({ value: option.const, label: option.title }));
+  }
+  return (items.enum ?? []).map((value) => ({ value }));
+}
+
+function humanizeName(name: string): string {
+  return name
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/^./, (char) => char.toUpperCase());
+}
+
+function getBrowserElicitationUrl(url: string): URL {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`MCP URL elicitation only supports http/https URLs: ${parsed.protocol}`);
+  }
+  return parsed;
+}
+
+function stripUndefined(values: Record<string, ExtensionUIFormValue>): Record<string, string | number | boolean | string[]> {
+  const output: Record<string, string | number | boolean | string[]> = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (value !== undefined) output[key] = value;
+  }
+  return output;
+}
+
+function omitUndefined<T extends Record<string, unknown>>(value: T): T {
+  for (const key of Object.keys(value)) {
+    if (value[key] === undefined) delete value[key];
+  }
+  return value;
+}

package/init.ts

@@ -43,6 +43,16 @@ export async function initializeMcp(
       getSignal: () => ctx.signal,
     });
   }
+  const elicitationEnabled =
+    config.settings?.elicitation !== false &&
+    ctx.hasUI &&
+    typeof (ctx.ui as { form?: unknown }).form === "function";
+  if (elicitationEnabled) {
+    manager.setElicitationConfig({
+      ui: ctx.ui as any,
+      autoOpenUrls: config.settings?.elicitationAutoOpenUrls === true,
+    });
+  }
   const lifecycle = new McpLifecycleManager(manager);
   const toolMetadata = new Map<string, ToolMetadata[]>();
   const failureTracker = new Map<string, number>();

package/mcp-auth-flow.ts

@@ -16,6 +16,7 @@ import {
   waitForCallback,
   cancelPendingCallback,
   stopCallbackServer,
+  releaseCallbackServer,
 } from "./mcp-callback-server.ts"
 import {
   getAuthForUrl,
@@ -23,6 +24,7 @@ import {
   hasStoredTokens,
   clearAllCredentials,
   clearClientInfo,
+  clearTokens,
   clearCodeVerifier,
   updateOAuthState,
   getOAuthState,
@@ -52,17 +54,82 @@ function generateState(): string {
 /**
  * Extract OAuth configuration from a ServerEntry.
  */
-function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig {
-  // If oauth is explicitly false, return empty config
+export function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig {
   if (definition.oauth === false) {
     return {}
   }
-  return {
-    grantType: definition.oauth?.grantType,
-    clientId: definition.oauth?.clientId,
-    clientSecret: definition.oauth?.clientSecret,
-    scope: definition.oauth?.scope,
+
+  const config: McpOAuthConfig = {}
+  if (definition.oauth?.grantType !== undefined) config.grantType = definition.oauth.grantType
+  if (definition.oauth?.clientId !== undefined) config.clientId = definition.oauth.clientId
+  if (definition.oauth?.clientSecret !== undefined) config.clientSecret = definition.oauth.clientSecret
+  if (definition.oauth?.scope !== undefined) config.scope = definition.oauth.scope
+  if (definition.oauth?.redirectUri !== undefined) {
+    if (typeof definition.oauth.redirectUri !== "string") {
+      throw new Error("OAuth redirectUri must be a string")
+    }
+    const redirectUri = definition.oauth.redirectUri.trim()
+    if (!redirectUri) {
+      throw new Error("OAuth redirectUri must not be empty")
+    }
+    config.redirectUri = redirectUri
   }
+  if (definition.oauth?.clientName !== undefined) {
+    if (typeof definition.oauth.clientName !== "string") {
+      throw new Error("OAuth clientName must be a string")
+    }
+    const clientName = definition.oauth.clientName.trim()
+    if (!clientName) {
+      throw new Error("OAuth clientName must not be empty")
+    }
+    config.clientName = clientName
+  }
+  if (definition.oauth?.clientUri !== undefined) {
+    if (typeof definition.oauth.clientUri !== "string") {
+      throw new Error("OAuth clientUri must be a string")
+    }
+    const clientUri = definition.oauth.clientUri.trim()
+    if (!clientUri) {
+      throw new Error("OAuth clientUri must not be empty")
+    }
+    config.clientUri = clientUri
+  }
+  return config
+}
+
+function parseOAuthRedirectUri(redirectUri: string): { port: number; callbackHost: string; callbackPath: string } {
+  let url: URL
+  try {
+    url = new URL(redirectUri)
+  } catch (error) {
+    throw new Error(`Invalid OAuth redirectUri: ${redirectUri}`, { cause: error })
+  }
+
+  const hostname = url.hostname.toLowerCase()
+  const isLocalhost = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1"
+  if (url.protocol !== "http:" || !isLocalhost) {
+    throw new Error("OAuth redirectUri must be an http:// localhost or loopback URI")
+  }
+
+  if (url.username || url.password) {
+    throw new Error("OAuth redirectUri must not include username or password")
+  }
+
+  if (url.hash) {
+    throw new Error("OAuth redirectUri must not include a fragment")
+  }
+
+  if (!url.port) {
+    throw new Error("OAuth redirectUri must include an explicit numeric port")
+  }
+
+  const port = Number.parseInt(url.port, 10)
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("OAuth redirectUri must include an explicit numeric port")
+  }
+
+  const callbackHost = hostname === "[::1]" ? "::1" : hostname
+  return { port, callbackHost, callbackPath: url.pathname }
 }
 
 /**
@@ -76,14 +143,14 @@ export async function startAuth(
 ): Promise<{ authorizationUrl: string }> {
   const config = definition ? extractOAuthConfig(definition) : {}
 
-  const storedAuth = await getAuthForUrl(serverName, serverUrl)
-  if (storedAuth?.clientInfo && !storedAuth.tokens && !config.clientId) {
-    clearClientInfo(serverName)
-    clearCodeVerifier(serverName)
-    await clearOAuthState(serverName)
-  }
-
   if (config.grantType === "client_credentials") {
+    const storedAuth = await getAuthForUrl(serverName, serverUrl)
+    if (storedAuth?.clientInfo && !storedAuth.tokens && !config.clientId) {
+      clearClientInfo(serverName)
+      clearCodeVerifier(serverName)
+      await clearOAuthState(serverName)
+    }
+
     const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
       onRedirect: async () => {
         throw new Error("Browser redirect is not used for client_credentials flow")
@@ -96,12 +163,20 @@ export async function startAuth(
     return { authorizationUrl: "" }
   }
 
-  // Start the callback server.
-  // Pre-registered OAuth clients require an exact redirect URI, so enforce strict port binding.
-  await ensureCallbackServer({ strictPort: Boolean(config.clientId) })
-
+  const redirectCallback = config.redirectUri !== undefined ? parseOAuthRedirectUri(config.redirectUri) : undefined
   const oauthState = generateState()
-  await updateOAuthState(serverName, oauthState, serverUrl)
+
+  try {
+    await ensureCallbackServer({
+      strictPort: Boolean(config.clientId) || config.redirectUri !== undefined,
+      oauthState,
+      reserveState: true,
+      ...(redirectCallback ? { port: redirectCallback.port, callbackHost: redirectCallback.callbackHost, callbackPath: redirectCallback.callbackPath } : {}),
+    })
+  } catch (error) {
+    await clearOAuthState(serverName)
+    throw error
+  }
 
   let capturedUrl: URL | undefined
   const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
@@ -111,8 +186,28 @@ export async function startAuth(
   })
 
   try {
+    const storedAuth = await getAuthForUrl(serverName, serverUrl)
+    if (storedAuth?.clientInfo && !config.clientId) {
+      if (!storedAuth.tokens) {
+        clearClientInfo(serverName)
+        clearCodeVerifier(serverName)
+        await clearOAuthState(serverName)
+      } else {
+        const redirectUris = storedAuth.clientInfo.redirectUris
+        if (!Array.isArray(redirectUris) || !redirectUris.includes(authProvider.redirectUrl ?? "")) {
+          clearClientInfo(serverName)
+          clearTokens(serverName)
+          clearCodeVerifier(serverName)
+          await clearOAuthState(serverName)
+        }
+      }
+    }
+
+    await updateOAuthState(serverName, oauthState, serverUrl)
+
     const result = await runSdkAuth(authProvider, { serverUrl })
     if (result === "AUTHORIZED") {
+      releaseCallbackServer(oauthState)
       await clearOAuthState(serverName)
       return { authorizationUrl: "" }
     }
@@ -125,6 +220,7 @@ export async function startAuth(
     )
     return { authorizationUrl: capturedUrl.toString() }
   } catch (error) {
+    releaseCallbackServer(oauthState)
     await clearOAuthState(serverName)
     throw error
   }
@@ -142,11 +238,17 @@ export async function completeAuth(
     throw new Error(`No pending OAuth flow for server: ${serverName}`)
   }
 
+  const oauthState = await getOAuthState(serverName)
+
   try {
     // Complete the auth using the transport's finishAuth method
     await transport.finishAuth(authorizationCode)
     return "authenticated"
   } finally {
+    if (oauthState) {
+      releaseCallbackServer(oauthState)
+    }
+    await clearOAuthState(serverName)
     pendingTransports.delete(serverName)
     await transport.close().catch(() => {})
   }
@@ -347,11 +449,9 @@ export function supportsOAuth(definition: ServerEntry): boolean {
 
 /**
  * Initialize the OAuth system on startup.
- * Starts the callback server if there are any OAuth servers configured.
+ * OAuth callback binding is lazy and starts from startAuth() only.
  */
-export async function initializeOAuth(): Promise<void> {
-  await ensureCallbackServer()
-}
+export async function initializeOAuth(): Promise<void> {}
 
 /**
  * Shutdown the OAuth system.

package/mcp-auth.ts

@@ -27,6 +27,7 @@ export interface StoredClientInfo {
   clientSecret?: string;
   clientIdIssuedAt?: number;
   clientSecretExpiresAt?: number;
+  redirectUris?: string[];
 }
 
 /** Complete auth entry for a server */

package/mcp-callback-server.ts

@@ -7,9 +7,11 @@
 
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http"
 import {
-  OAUTH_CALLBACK_PATH,
+  DEFAULT_OAUTH_CALLBACK_PATH,
   getConfiguredOAuthCallbackPort,
+  getOAuthCallbackPath,
   getOAuthCallbackPort,
+  setOAuthCallbackPath,
   setOAuthCallbackPort,
 } from "./mcp-oauth-provider.ts"
 
@@ -34,6 +36,15 @@ const HTML_SUCCESS = `<!DOCTYPE html>
 </body>
 </html>`
 
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;")
+}
+
 const HTML_ERROR = (error: string) => `<!DOCTYPE html>
 <html>
 <head>
@@ -50,7 +61,7 @@ const HTML_ERROR = (error: string) => `<!DOCTYPE html>
   <div class="container">
     <h1>Authorization Failed</h1>
     <p>An error occurred during authorization.</p>
-    <div class="error">${error}</div>
+    <div class="error">${escapeHtml(error)}</div>
   </div>
 </body>
 </html>`
@@ -64,17 +75,25 @@ interface PendingAuth {
 
 /** Server singleton state */
 let server: Server | undefined
+let bindingPromise: Promise<void> | undefined
 const pendingAuths = new Map<string, PendingAuth>()
+const reservedAuthStates = new Set<string>()
 
 /** Timeout for callback completion (5 minutes) */
 const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
 
-const MAX_PORT_SCAN_ATTEMPTS = 25
-
 interface EnsureCallbackServerOptions {
   strictPort?: boolean
+  port?: number
+  callbackHost?: string
+  callbackPath?: string
+  oauthState?: string
+  reserveState?: boolean
 }
 
+const DEFAULT_OAUTH_CALLBACK_HOST = "localhost"
+let callbackServerHost = DEFAULT_OAUTH_CALLBACK_HOST
+
 /**
  * Handle incoming HTTP requests to the callback server.
  */
@@ -82,7 +101,7 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
   const url = new URL(req.url || "/", `http://${req.headers.host}`)
 
   // Only handle the callback path
-  if (url.pathname !== OAUTH_CALLBACK_PATH) {
+  if (url.pathname !== getOAuthCallbackPath()) {
     res.writeHead(404, { "Content-Type": "text/plain" })
     res.end("Not found")
     return
@@ -101,15 +120,25 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
     return
   }
 
-  // Handle OAuth errors
+  const pending = pendingAuths.get(state)
+  const isReserved = reservedAuthStates.has(state)
+
+  // Handle OAuth errors only for a state that belongs to an active flow.
   if (error) {
+    if (!pending && !isReserved) {
+      const errorMsg = "Invalid or expired state parameter - potential CSRF attack"
+      res.writeHead(400, { "Content-Type": "text/html" })
+      res.end(HTML_ERROR(errorMsg))
+      return
+    }
+
     const errorMsg = errorDescription || error
     // Send HTTP response first before rejecting promise
     res.writeHead(200, { "Content-Type": "text/html" })
     res.end(HTML_ERROR(errorMsg))
+    reservedAuthStates.delete(state)
     // Reject promise after response is sent (defer to allow test to attach handler)
-    if (pendingAuths.has(state)) {
-      const pending = pendingAuths.get(state)!
+    if (pending) {
       clearTimeout(pending.timeout)
       pendingAuths.delete(state)
       setTimeout(() => pending.reject(new Error(errorMsg)), 0)
@@ -117,22 +146,20 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
     return
   }
 
-  // Require authorization code
-  if (!code) {
-    res.writeHead(400, { "Content-Type": "text/html" })
-    res.end(HTML_ERROR("No authorization code provided"))
-    return
-  }
-
   // Validate state parameter
-  if (!pendingAuths.has(state)) {
+  if (!pending) {
     const errorMsg = "Invalid or expired state parameter - potential CSRF attack"
     res.writeHead(400, { "Content-Type": "text/html" })
     res.end(HTML_ERROR(errorMsg))
     return
   }
 
-  const pending = pendingAuths.get(state)!
+  // Require authorization code
+  if (!code) {
+    res.writeHead(400, { "Content-Type": "text/html" })
+    res.end(HTML_ERROR("No authorization code provided"))
+    return
+  }
 
   // Clear timeout and resolve the pending promise
   clearTimeout(pending.timeout)
@@ -146,72 +173,128 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
 /**
  * Ensure the callback server is running.
  * If strictPort is true, requires binding on the configured callback port.
- * If strictPort is false, scans forward for an available local port.
+ * If strictPort is false, asks the OS for an available local port.
  */
 export async function ensureCallbackServer(options: EnsureCallbackServerOptions = {}): Promise<void> {
-  const configuredPort = getConfiguredOAuthCallbackPort()
-  const strictPort = options.strictPort === true
+  while (bindingPromise) {
+    await bindingPromise
+  }
 
-  if (server) {
-    if (!strictPort || getOAuthCallbackPort() === configuredPort) return
+  const operation = ensureCallbackServerLocked(options)
+  bindingPromise = operation
+  try {
+    await operation
+  } finally {
+    if (bindingPromise === operation) {
+      bindingPromise = undefined
+    }
+  }
+}
 
-    if (pendingAuths.size > 0) {
+async function ensureCallbackServerLocked(options: EnsureCallbackServerOptions = {}): Promise<void> {
+  const requiredPort = options.port ?? getConfiguredOAuthCallbackPort()
+  const strictPort = options.strictPort === true
+  const requestedHost = options.callbackHost ?? DEFAULT_OAUTH_CALLBACK_HOST
+  const rawRequestedPath = options.callbackPath ?? DEFAULT_OAUTH_CALLBACK_PATH
+  const requestedPath = rawRequestedPath.startsWith("/") ? rawRequestedPath : `/${rawRequestedPath}`
+  if (options.reserveState && !options.oauthState) {
+    throw new Error("OAuth callback reservation requires an oauthState")
+  }
+  let reservedState: string | undefined
+
+  const previousServer = server
+  const needsStrictRebind = Boolean(previousServer && strictPort && getOAuthCallbackPort() !== requiredPort)
+  const needsHostSwitch = Boolean(previousServer && callbackServerHost !== requestedHost)
+  const needsPathSwitch = Boolean(previousServer && getOAuthCallbackPath() !== requestedPath)
+
+  if (previousServer) {
+    if (!needsStrictRebind && !needsHostSwitch) {
+      if (needsPathSwitch) {
+        if (pendingAuths.size > 0 || reservedAuthStates.size > 0) {
+          throw new Error(
+            `OAuth callback server is using path ${getOAuthCallbackPath()}, but callback path ${requestedPath} is required and cannot be switched while authorizations are pending`
+          )
+        }
+        setOAuthCallbackPath(requestedPath)
+      }
+      if (options.reserveState && options.oauthState) {
+        reservedAuthStates.add(options.oauthState)
+        reservedState = options.oauthState
+      }
+      return
+    }
+
+    if (pendingAuths.size > 0 || reservedAuthStates.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`
+        `OAuth callback server is running on ${callbackServerHost}:${getOAuthCallbackPort()}, but strict callback endpoint ${requestedHost}:${requiredPort} is required and cannot be switched while authorizations are pending`
       )
     }
-
-    await stopCallbackServer()
   }
 
-  const preferredPort = configuredPort
-  const maxAttempts = strictPort ? 1 : MAX_PORT_SCAN_ATTEMPTS
-  let lastError: Error | undefined
+  const candidateServer = createServer(handleRequest)
+  const listenPort = strictPort ? requiredPort : 0
 
-  for (let offset = 0; offset < maxAttempts; offset++) {
-    const candidatePort = preferredPort + offset
-    const candidateServer = createServer(handleRequest)
-
-    try {
-      await new Promise<void>((resolve, reject) => {
-        candidateServer.once("error", (err) => {
-          reject(err)
-        })
+  try {
+    await new Promise<void>((resolve, reject) => {
+      candidateServer.once("error", (err) => {
+        reject(err)
+      })
 
-        candidateServer.listen(candidatePort, "localhost", () => {
-          resolve()
-        })
+      candidateServer.listen(listenPort, requestedHost, () => {
+        resolve()
       })
+    })
 
-      server = candidateServer
-      server.unref()
-      setOAuthCallbackPort(candidatePort)
-      return
-    } catch (error) {
-      const nodeError = error as NodeJS.ErrnoException
+    if (strictPort) {
+      setOAuthCallbackPort(requiredPort)
+    } else {
+      const address = candidateServer.address()
+      if (!address || typeof address === "string" || typeof address.port !== "number") {
+        throw new Error("OAuth callback server did not report an assigned port")
+      }
+      setOAuthCallbackPort(address.port)
+    }
+
+    if (previousServer && (needsStrictRebind || needsHostSwitch)) {
       await new Promise<void>((resolve) => {
-        candidateServer.close(() => resolve())
+        previousServer.close(() => resolve())
       })
+    }
 
-      if (nodeError.code !== "EADDRINUSE") {
-        throw error
-      }
+    callbackServerHost = requestedHost
+    setOAuthCallbackPath(requestedPath)
+    server = candidateServer
+    if (options.reserveState && options.oauthState) {
+      reservedAuthStates.add(options.oauthState)
+      reservedState = options.oauthState
+    }
+    server.unref()
+  } catch (error) {
+    if (reservedState) {
+      reservedAuthStates.delete(reservedState)
+    }
+    const nodeError = error as NodeJS.ErrnoException
+    await new Promise<void>((resolve) => {
+      candidateServer.close(() => resolve())
+    })
 
-      lastError = error instanceof Error ? error : new Error(String(error))
+    if (strictPort && nodeError.code === "EADDRINUSE") {
+      throw new Error(
+        `OAuth callback port ${requiredPort} 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 ${requiredPort}`,
+        { cause: 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 error
   }
+}
+
+export function reserveCallbackServer(oauthState: string): void {
+  reservedAuthStates.add(oauthState)
+}
 
-  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 }
-  )
+export function releaseCallbackServer(oauthState: string): void {
+  reservedAuthStates.delete(oauthState)
 }
 
 /**
@@ -219,6 +302,7 @@ export async function ensureCallbackServer(options: EnsureCallbackServerOptions
  * Returns a promise that resolves with the authorization code.
  */
 export function waitForCallback(oauthState: string): Promise<string> {
+  reservedAuthStates.delete(oauthState)
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
       if (pendingAuths.has(oauthState)) {
@@ -235,6 +319,7 @@ export function waitForCallback(oauthState: string): Promise<string> {
  * Cancel a pending authorization by state.
  */
 export function cancelPendingCallback(oauthState: string): void {
+  reservedAuthStates.delete(oauthState)
   const pending = pendingAuths.get(oauthState)
   if (pending) {
     clearTimeout(pending.timeout)
@@ -257,10 +342,13 @@ export async function stopCallbackServer(): Promise<void> {
   }
 
   setOAuthCallbackPort(getConfiguredOAuthCallbackPort())
+  callbackServerHost = DEFAULT_OAUTH_CALLBACK_HOST
+  setOAuthCallbackPath(DEFAULT_OAUTH_CALLBACK_PATH)
 
   // Reject all pending auths (defer to allow any pending operations to complete)
   const pendingList = Array.from(pendingAuths.entries())
   pendingAuths.clear()
+  reservedAuthStates.clear()
   setTimeout(() => {
     for (const [, pending] of pendingList) {
       clearTimeout(pending.timeout)

package/mcp-oauth-provider.ts

@@ -28,7 +28,7 @@ import {
 
 // Callback server configuration
 const DEFAULT_OAUTH_CALLBACK_PORT = 19876
-const OAUTH_CALLBACK_PATH = "/callback"
+const DEFAULT_OAUTH_CALLBACK_PATH = "/callback"
 
 let configuredOAuthCallbackPort = DEFAULT_OAUTH_CALLBACK_PORT
 
@@ -40,6 +40,7 @@ if (process.env.MCP_OAUTH_CALLBACK_PORT) {
 }
 
 let oauthCallbackPort = configuredOAuthCallbackPort
+let oauthCallbackPath = DEFAULT_OAUTH_CALLBACK_PATH
 
 export function getConfiguredOAuthCallbackPort(): number {
   return configuredOAuthCallbackPort
@@ -53,12 +54,23 @@ export function setOAuthCallbackPort(port: number): void {
   oauthCallbackPort = port
 }
 
+export function getOAuthCallbackPath(): string {
+  return oauthCallbackPath
+}
+
+export function setOAuthCallbackPath(path: string): void {
+  oauthCallbackPath = path.startsWith("/") ? path : `/${path}`
+}
+
 /** Configuration options for OAuth */
 export interface McpOAuthConfig {
   grantType?: "authorization_code" | "client_credentials"
   clientId?: string
   clientSecret?: string
   scope?: string
+  redirectUri?: string
+  clientName?: string
+  clientUri?: string
 }
 
 /** Callbacks for OAuth flow interactions */
@@ -71,12 +83,18 @@ export interface McpOAuthCallbacks {
  * Implements the OAuthClientProvider interface from the MCP SDK.
  */
 export class McpOAuthProvider implements OAuthClientProvider {
+  private readonly redirectUrlSnapshot: string | undefined
+
   constructor(
     private serverName: string,
     private serverUrl: string,
     private config: McpOAuthConfig,
     private callbacks: McpOAuthCallbacks,
-  ) {}
+  ) {
+    this.redirectUrlSnapshot = config.grantType === "client_credentials"
+      ? undefined
+      : config.redirectUri ?? `http://localhost:${getOAuthCallbackPort()}${getOAuthCallbackPath()}`
+  }
 
   private get usesClientCredentials(): boolean {
     return this.config.grantType === "client_credentials"
@@ -87,8 +105,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
    * This must match the redirect_uri in client metadata.
    */
   get redirectUrl(): string | undefined {
-    if (this.usesClientCredentials) return undefined
-    return `http://localhost:${getOAuthCallbackPort()}${OAUTH_CALLBACK_PATH}`
+    return this.redirectUrlSnapshot
   }
 
   /**
@@ -98,7 +115,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
   get clientMetadata(): OAuthClientMetadata {
     if (this.usesClientCredentials) {
       return {
-        client_name: "Pi Coding Agent",
+        client_name: this.config.clientName ?? "Pi Coding Agent",
+        client_uri: this.config.clientUri ?? "https://github.com/nicobailon/pi-mcp-adapter",
         redirect_uris: [],
         grant_types: ["client_credentials"],
         token_endpoint_auth_method: this.config.clientSecret ? "client_secret_post" : "none",
@@ -112,8 +130,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
     return {
       redirect_uris: [redirectUrl],
-      client_name: "Pi Coding Agent",
-      client_uri: "https://github.com/nicobailon/pi-mcp-adapter",
+      client_name: this.config.clientName ?? "Pi Coding Agent",
+      client_uri: this.config.clientUri ?? "https://github.com/nicobailon/pi-mcp-adapter",
       grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: this.config.clientSecret ? "client_secret_post" : "none",
@@ -155,11 +173,13 @@ export class McpOAuthProvider implements OAuthClientProvider {
    * Save client information from dynamic registration.
    */
   async saveClientInformation(info: OAuthClientInformationFull): Promise<void> {
+    const redirectUris = info.redirect_uris ?? (this.redirectUrl ? [this.redirectUrl] : undefined)
     const clientInfo: StoredClientInfo = {
       clientId: info.client_id,
       clientSecret: info.client_secret,
       clientIdIssuedAt: info.client_id_issued_at,
       clientSecretExpiresAt: info.client_secret_expires_at,
+      redirectUris,
     }
     updateClientInfo(this.serverName, clientInfo, this.serverUrl)
   }
@@ -299,4 +319,4 @@ export class McpOAuthProvider implements OAuthClientProvider {
   }
 }
 
-export { DEFAULT_OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_PATH }
+export { DEFAULT_OAUTH_CALLBACK_PORT, DEFAULT_OAUTH_CALLBACK_PATH }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "config.ts",
     "server-manager.ts",
     "sampling-handler.ts",
+    "elicitation-handler.ts",
     "tool-registrar.ts",
     "tool-result-renderer.ts",
     "resource-tools.ts",

package/server-manager.ts

@@ -15,8 +15,9 @@ import { serverStreamResultPatchNotificationSchema } from "./types.ts";
 import { resolveNpxBinary } from "./npx-resolver.ts";
 import { logger } from "./logger.ts";
 import { McpOAuthProvider } from "./mcp-oauth-provider.ts";
-import { supportsOAuth } from "./mcp-auth-flow.ts";
+import { extractOAuthConfig, supportsOAuth } from "./mcp-auth-flow.ts";
 import { registerSamplingHandler, type ServerSamplingConfig } from "./sampling-handler.ts";
+import { registerElicitationHandler, type ServerElicitationConfig } from "./elicitation-handler.ts";
 import { interpolateEnvRecord, resolveBearerToken, resolveConfigPath } from "./utils.ts";
 
 interface ServerConnection {
@@ -37,10 +38,15 @@ export class McpServerManager {
   private connectPromises = new Map<string, Promise<ServerConnection>>();
   private uiStreamListeners = new Map<string, UiStreamListener>();
   private samplingConfig: ServerSamplingConfig | undefined;
+  private elicitationConfig: ServerElicitationConfig | undefined;
 
   setSamplingConfig(config: ServerSamplingConfig | undefined): void {
     this.samplingConfig = config;
   }
+
+  setElicitationConfig(config: ServerElicitationConfig | undefined): void {
+    this.elicitationConfig = config;
+  }
   
   async connect(name: string, definition: ServerDefinition): Promise<ServerConnection> {
     // Dedupe concurrent connection attempts
@@ -148,14 +154,32 @@ export class McpServerManager {
     }
   }
   
+  private buildClientCapabilities() {
+    return {
+      ...(this.samplingConfig ? { sampling: {} } : {}),
+      ...(this.elicitationConfig
+        ? {
+            elicitation: {
+              form: { applyDefaults: true },
+              url: {},
+            },
+          }
+        : {}),
+    };
+  }
+
   private createClient(serverName: string): Client {
+    const capabilities = this.buildClientCapabilities();
     const client = new Client(
       { name: `pi-mcp-${serverName}`, version: "1.0.0" },
-      this.samplingConfig ? { capabilities: { sampling: {} } } : undefined,
+      Object.keys(capabilities).length > 0 ? { capabilities } : undefined,
     );
     if (this.samplingConfig) {
       registerSamplingHandler(client, { ...this.samplingConfig, serverName });
     }
+    if (this.elicitationConfig) {
+      registerElicitationHandler(client, { ...this.elicitationConfig, serverName });
+    }
     return client;
   }
 
@@ -182,13 +206,7 @@ export class McpServerManager {
     // For OAuth servers, create an auth provider
     let authProvider: McpOAuthProvider | undefined;
     if (supportsOAuth(definition)) {
-      // Extract OAuth config (handles both object and false cases)
-      const oauthConfig = definition.oauth === false ? {} : {
-        grantType: definition.oauth?.grantType,
-        clientId: definition.oauth?.clientId,
-        clientSecret: definition.oauth?.clientSecret,
-        scope: definition.oauth?.scope,
-      };
+      const oauthConfig = extractOAuthConfig(definition);
       authProvider = new McpOAuthProvider(
         serverName,
         definition.url!,

package/types.ts

@@ -272,6 +272,12 @@ export interface OAuthConfig {
   clientSecret?: string;
   /** Requested OAuth scopes */
   scope?: string;
+  /** Exact authorization-code redirect URI for pre-registered clients */
+  redirectUri?: string;
+  /** Client display name for dynamic registration */
+  clientName?: string;
+  /** Client homepage URI for dynamic registration */
+  clientUri?: string;
 }
 
 // Server configuration
@@ -320,6 +326,8 @@ export interface McpSettings {
   autoAuth?: boolean;
   sampling?: boolean;
   samplingAutoApprove?: boolean;
+  elicitation?: boolean;
+  elicitationAutoOpenUrls?: boolean;
   /**
    * Message returned in tool results when a server needs (re-)authentication.
    * "${server}" is substituted with the server name. Defaults to a TUI