@fitchmultz/pi-mcp-adapter 5.0.0

package/dist/session-recovery.d.ts

@@ -0,0 +1,31 @@
+import { type FetchLike, type Transport } from "@modelcontextprotocol/client";
+import { type McpConfig } from "./types.ts";
+import type { McpServerManager, ServerConnection } from "./server-manager.ts";
+export declare function isToolTransportFailure(error: unknown): boolean;
+/** Retain fetch/body-error origin without parsing or buffering the SSE response. */
+export declare const trackToolTransportFailure: FetchLike;
+/** Observe only the originating tool send, not OAuth or catalog requests. */
+export declare function trackToolHttpFailures(transport: Transport): void;
+export declare function isTerminatedSession(err: unknown, hadSessionId: boolean): boolean;
+export declare class SessionRecoveryAuthRequiredError extends Error {
+    readonly serverName: string;
+    readonly authMessage?: string | undefined;
+    constructor(serverName: string, authMessage?: string | undefined);
+}
+export interface AuthChallengeContext {
+    connection: ServerConnection;
+    error: Error;
+}
+export interface SessionRecoveryDeps {
+    manager: McpServerManager;
+    config: McpConfig;
+    signal?: AbortSignal;
+    /** Only replay-safe tool calls may opt into a same-client retry of a proven modern POST transport failure. */
+    retryOnTransportFailure?: boolean;
+    onNeedsAuth?: (serverName: string, signal?: AbortSignal, challenge?: AuthChallengeContext) => Promise<ServerConnection | undefined>;
+}
+/**
+ * Retry once on the same modern client when explicitly enabled, or reconnect
+ * an expired legacy session once. Neither path retries its second failure.
+ */
+export declare function withSessionRecovery<T>(deps: SessionRecoveryDeps, serverName: string, fn: (conn: ServerConnection) => Promise<T>): Promise<T>;

package/dist/session-recovery.js

@@ -0,0 +1,310 @@
+// session-recovery.ts
+//
+// Streamable HTTP session recovery.
+//
+// Per the MCP spec (Streamable HTTP transport):
+//   "When a client receives HTTP 404 in response to a request containing an
+//   Mcp-Session-Id, it MUST start a new session by sending a new
+//   InitializeRequest without a session ID attached."
+//
+// A 404 for a request that carried a session ID is therefore the spec's own
+// definition of "this session no longer exists" (e.g. the remote server
+// process restarted and lost its in-memory session table). Because the spec
+// requires the server to reject the request *before* processing it, retrying
+// the same call against a freshly initialized session cannot double-execute
+// the original request.
+//
+// This module intentionally does NOT:
+//   - match broad error messages without a prior session id
+//   - match generic HTTP 400 responses, which are ambiguous and can mean
+//     many things other than "your session is gone"
+//   - treat generic -32000/ConnectionClosed errors as session expiry
+//   - treat AbortError/cancellation as a session failure
+import { AsyncLocalStorage } from "node:async_hooks";
+import { SdkHttpError, SdkErrorCode, ProtocolError, InsufficientScopeError, UnauthorizedError } from "@modelcontextprotocol/client";
+import { logger } from "./logger.js";
+import { abortable, throwIfAborted } from "./abort.js";
+import { isServerDisabled, isNonInteractiveOAuth } from "./types.js";
+import { supportsOAuth } from "./mcp-auth-flow.js";
+const toolTransportFailures = new WeakSet();
+export function isToolTransportFailure(error) {
+    return error instanceof Error && toolTransportFailures.has(error);
+}
+const toolSend = new AsyncLocalStorage();
+/** Retain fetch/body-error origin without parsing or buffering the SSE response. */
+export const trackToolTransportFailure = async (input, init) => {
+    const pending = toolSend.getStore();
+    if (pending)
+        pending.bodyFailure = undefined;
+    try {
+        const response = await fetch(input, init);
+        if (!pending || !response.ok || !response.body
+            || response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !== "text/event-stream")
+            return response;
+        pending.streaming = true;
+        // The native end hook has no error argument. Only a failed body read proves loss.
+        const reader = response.body.getReader();
+        return new Response(new ReadableStream({
+            async pull(controller) {
+                try {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        controller.close();
+                        reader.releaseLock();
+                    }
+                    else
+                        controller.enqueue(value);
+                }
+                catch (error) {
+                    // Native intentional closure suppresses onRequestStreamEnd.
+                    if (init?.signal?.aborted)
+                        pending.finishSend();
+                    else if (error instanceof Error)
+                        pending.bodyFailure = error;
+                    controller.error(error);
+                    reader.releaseLock();
+                }
+            },
+            cancel: reason => reader.cancel(reason).finally(() => reader.releaseLock()),
+        }), response);
+    }
+    catch (error) {
+        if (error instanceof Error && !init?.signal?.aborted && init?.method === "POST"
+            && new Headers(init.headers).get("Mcp-Method") === "tools/call") {
+            toolTransportFailures.add(error);
+        }
+        throw error;
+    }
+};
+/** Observe only the originating tool send, not OAuth or catalog requests. */
+export function trackToolHttpFailures(transport) {
+    const onmessage = transport.onmessage;
+    transport.onmessage = (message, extra) => {
+        const pending = toolSend.getStore();
+        if (pending && "id" in message && message.id === pending.id && ("result" in message || "error" in message)) {
+            pending.responseReceived = true;
+            pending.finishSend();
+        }
+        onmessage?.(message, extra);
+    };
+    const onerror = transport.onerror;
+    transport.onerror = error => {
+        const pending = toolSend.getStore();
+        // Reader failures are observed before the SDK reports them; earlier parser errors are not retryable.
+        if (pending && !pending.bodyFailure)
+            pending.otherFailure ??= error;
+        onerror?.(error);
+    };
+    const send = transport.send.bind(transport);
+    transport.send = async (message, options) => {
+        try {
+            if (!("method" in message && message.method === "tools/call" && "id" in message && options?.requestSignal)) {
+                return await toolSend.run(undefined, () => send(message, options));
+            }
+            const pending = {
+                id: message.id, streaming: false, responseReceived: false,
+                bodyFailure: undefined, otherFailure: undefined,
+                finishSend: () => { },
+            };
+            try {
+                await abortable(new Promise((resolve, reject) => {
+                    pending.finishSend = resolve;
+                    void toolSend.run(pending, () => send(message, {
+                        ...options,
+                        onRequestStreamEnd: () => {
+                            options.onRequestStreamEnd?.();
+                            const error = pending.otherFailure ?? pending.bodyFailure;
+                            if (!pending.responseReceived && error) {
+                                if (!pending.otherFailure)
+                                    toolTransportFailures.add(error);
+                                reject(error);
+                            }
+                            else
+                                resolve();
+                        },
+                    })).then(() => { if (!pending.streaming)
+                        resolve(); }, reject);
+                }), options.requestSignal);
+            }
+            finally {
+                pending.finishSend = () => { };
+            }
+        }
+        catch (error) {
+            if ("method" in message && message.method === "tools/call"
+                && error instanceof SdkHttpError && error.code === SdkErrorCode.ClientHttpNotImplemented
+                && error.status >= 500 && error.status < 600) {
+                let errorBody = false;
+                try {
+                    const body = JSON.parse(String(error.data.text));
+                    errorBody = body?.jsonrpc === "2.0" && body.error !== undefined;
+                }
+                catch { }
+                if (!errorBody)
+                    toolTransportFailures.add(error);
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * True when `err` is a stale Streamable HTTP session signal for a request
+ * sent while carrying an `Mcp-Session-Id`: the spec's 404 transport
+ * response, or the narrowly-known `-32000 Server not initialized` protocol
+ * gate response some servers emit before dispatching to a handler.
+ *
+ * `hadSessionId` must reflect the transport's session id from *before* the
+ * call that produced `err` was made. The SDK does not
+ * clear `transport.sessionId` on a 404 response, so callers must capture it
+ * before the call rather than rely on catch-time transport state.
+ */
+const SERVER_NOT_INITIALIZED_MCP_MESSAGES = new Set([
+    "Server not initialized",
+    "Bad Request: Server not initialized",
+]);
+export function isTerminatedSession(err, hadSessionId) {
+    if (!hadSessionId)
+        return false;
+    if (err instanceof SdkHttpError) {
+        return err.status === 404
+            || (err.status === 400
+                && /"code"\s*:\s*-32000/.test(err.message)
+                && /"message"\s*:\s*"Bad Request: Server not initialized"/.test(err.message));
+    }
+    return err instanceof ProtocolError
+        && err.code === -32000
+        && SERVER_NOT_INITIALIZED_MCP_MESSAGES.has(err.message);
+}
+function hasSessionId(connection) {
+    // Only StreamableHTTPClientTransport exposes `sessionId`; stdio/SSE
+    // transports (and test doubles that omit `transport` entirely) simply
+    // read as `undefined` here.
+    const transport = connection.transport;
+    return transport?.sessionId != null;
+}
+export class SessionRecoveryAuthRequiredError extends Error {
+    serverName;
+    authMessage;
+    constructor(serverName, authMessage) {
+        super(authMessage ?? `MCP server "${serverName}" requires OAuth authentication after reconnect.`);
+        this.serverName = serverName;
+        this.authMessage = authMessage;
+        this.name = "SessionRecoveryAuthRequiredError";
+    }
+}
+/**
+ * Retry once on the same modern client when explicitly enabled, or reconnect
+ * an expired legacy session once. Neither path retries its second failure.
+ */
+export async function withSessionRecovery(deps, serverName, fn) {
+    if (isServerDisabled(deps.config.mcpServers[serverName])) {
+        throw new Error(`MCP server "${serverName}" is disabled`);
+    }
+    throwIfAborted(deps.signal);
+    let connection = deps.manager.getConnection(serverName);
+    if (!connection) {
+        throw new Error(`Server "${serverName}" is not connected`);
+    }
+    const reconnect = async (stale, error) => {
+        const definition = deps.config.mcpServers[serverName];
+        if (!definition)
+            throw error;
+        throwIfAborted(deps.signal);
+        let fresh = stale;
+        if (fresh.status !== "needs-auth") {
+            fresh = deps.signal
+                ? await deps.manager.reconnect(serverName, definition, stale, deps.signal)
+                : await deps.manager.reconnect(serverName, definition, stale);
+        }
+        throwIfAborted(deps.signal);
+        if (fresh.status === "needs-auth" && deps.onNeedsAuth) {
+            fresh = await abortable(deps.onNeedsAuth(serverName, deps.signal), deps.signal) ?? fresh;
+            throwIfAborted(deps.signal);
+        }
+        if (fresh.status === "needs-auth")
+            throw new SessionRecoveryAuthRequiredError(serverName);
+        if (fresh.status !== "connected")
+            throw error;
+        return fresh;
+    };
+    const isRecoverableAuth = (error, failed, activating = false) => {
+        const definition = deps.config.mcpServers[serverName];
+        if (!definition || isServerDisabled(definition) || !supportsOAuth(definition))
+            return false;
+        if (error instanceof SdkHttpError) {
+            // A provider's exhausted native 401/M2M retry is terminal, not another consent cycle.
+            return failed.oauthProvider === false && error.status === 401 && error.code !== SdkErrorCode.ClientHttpAuthentication;
+        }
+        if (failed.oauthProvider && isNonInteractiveOAuth(definition.oauth))
+            return false;
+        return error instanceof InsufficientScopeError || (activating && error instanceof UnauthorizedError);
+    };
+    const terminalDispatch = async (fresh) => {
+        throwIfAborted(deps.signal);
+        try {
+            return await fn(fresh);
+        }
+        catch (error) {
+            throwIfAborted(deps.signal);
+            if (isRecoverableAuth(error, fresh))
+                throw new SessionRecoveryAuthRequiredError(serverName);
+            throw error;
+        }
+    };
+    const recoverAuth = async (failed, error) => {
+        const definition = deps.config.mcpServers[serverName];
+        const current = deps.manager.getConnection(serverName);
+        if (current && current !== failed && failed.oauthProvider !== false) {
+            return terminalDispatch(current.status === "connected" ? current : await reconnect(current, error));
+        }
+        if (failed.oauthProvider === false) {
+            // One anonymous rejection may activate the provider without asking the user to sign in.
+            failed = await deps.manager.reconnect(serverName, definition, failed, deps.signal);
+            throwIfAborted(deps.signal);
+            if (failed.status === "connected") {
+                try {
+                    return await fn(failed);
+                }
+                catch (providerError) {
+                    throwIfAborted(deps.signal);
+                    if (!isRecoverableAuth(providerError, failed, true))
+                        throw providerError;
+                    error = providerError;
+                }
+            }
+        }
+        if (isNonInteractiveOAuth(definition.oauth))
+            throw error;
+        const fresh = await abortable(deps.onNeedsAuth?.(serverName, deps.signal, { connection: failed, error }) ?? Promise.resolve(undefined), deps.signal);
+        throwIfAborted(deps.signal);
+        if (!fresh || fresh === failed || fresh.status !== "connected")
+            throw new SessionRecoveryAuthRequiredError(serverName);
+        return terminalDispatch(fresh);
+    };
+    // Nothing has been dispatched yet: wait for replacement/auth begun during UI preparation.
+    if (connection.status !== "connected") {
+        connection = await reconnect(connection, new Error(`Server "${serverName}" is not connected`));
+    }
+    const hadSessionId = hasSessionId(connection);
+    try {
+        return await fn(connection);
+    }
+    catch (err) {
+        throwIfAborted(deps.signal);
+        if (isRecoverableAuth(err, connection))
+            return recoverAuth(connection, err);
+        if (deps.retryOnTransportFailure === true
+            && deps.config.mcpServers[serverName]?.retryOnTransportFailure === true
+            && connection.client.getProtocolEra?.() === "modern"
+            && isToolTransportFailure(err)) {
+            return terminalDispatch(connection);
+        }
+        if (!isTerminatedSession(err, hadSessionId)) {
+            throw err;
+        }
+        logger.debug(`MCP session for "${serverName}" expired; reconnecting`, {
+            server: serverName,
+        });
+        return terminalDispatch(await reconnect(connection, err));
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,63 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ConsentManager } from "./consent-manager.ts";
+import type { McpLifecycleManager } from "./lifecycle.ts";
+import type { McpServerManager } from "./server-manager.ts";
+import type { AuthStorageOptions } from "./mcp-auth.ts";
+import type { ToolMetadata, PromptMetadata, McpConfig, McpAdapterOptions, UiSessionMessages, UiStreamSummary } from "./types.ts";
+import type { UiResourceHandler } from "./ui-resource-handler.ts";
+import type { UiServerHandle } from "./ui-server.ts";
+import type { McpRuntimeOwner } from "./runtime-owner.ts";
+import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
+import type { McpStatusEventBus } from "./mcp-status.ts";
+export interface CompletedUiSession {
+    serverName: string;
+    toolName: string;
+    completedAt: Date;
+    reason: string;
+    messages: UiSessionMessages;
+    stream?: UiStreamSummary;
+}
+export type SendMessageFn = (message: {
+    customType: string;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    display?: string;
+    details?: unknown;
+}, options?: {
+    triggerTurn?: boolean;
+}) => void;
+export interface McpExtensionState {
+    owner: McpRuntimeOwner;
+    manager: McpServerManager;
+    lifecycle: McpLifecycleManager;
+    toolMetadata: Map<string, ToolMetadata[]>;
+    /** Resource counts retained separately because tool metadata includes resource tools. */
+    resourceCounts: Map<string, number>;
+    promptMetadata: Map<string, PromptMetadata[]>;
+    /** Servers whose prompt inventory came from successful live discovery. */
+    promptMetadataLive: Set<string>;
+    serverInstructions: Map<string, string>;
+    config: McpConfig;
+    programmaticConfig?: boolean;
+    outputDirectory?: string;
+    onToolCall?: McpAdapterOptions["onToolCall"];
+    oauthRuntime: McpOAuthRuntime;
+    authStorageOptions: AuthStorageOptions;
+    metadataCacheEnabled: boolean;
+    failureTracker: Map<string, number>;
+    failureMessages: Map<string, string>;
+    /** Session-only approvals keyed by server and original tool name. */
+    approvedToolCalls: Map<string, true>;
+    uiResourceHandler: UiResourceHandler;
+    consentManager: ConsentManager;
+    uiServer: UiServerHandle | null;
+    completedUiSessions: CompletedUiSession[];
+    activeScripts: number;
+    openBrowser: (url: string) => Promise<void>;
+    ui?: ExtensionContext["ui"];
+    sendMessage?: SendMessageFn;
+    onToolMetadataUpdated?: (serverName: string, reason: string) => void | Promise<void>;
+    statusEvents?: McpStatusEventBus;
+}

package/dist/state.js

@@ -0,0 +1 @@
+export {};

package/dist/tool-approval.d.ts

@@ -0,0 +1,10 @@
+import type { McpExtensionState } from "./state.ts";
+import { type McpConfig, type ToolMetadata } from "./types.ts";
+export type ToolCallApprovalResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "denied" | "approval_required_headless";
+};
+export declare function isToolCallApprovalRequired(config: McpConfig, serverName: string, toolMeta: Pick<ToolMetadata, "originalName">): boolean;
+export declare function ensureToolCallApproved(state: McpExtensionState, serverName: string, toolMeta: ToolMetadata, args: Record<string, unknown> | undefined, signal?: AbortSignal): Promise<ToolCallApprovalResult>;

package/dist/tool-approval.js

@@ -0,0 +1,42 @@
+import { abortable } from "./abort.js";
+import { combineAbortSignals } from "./runtime-owner.js";
+import { getToolNameCandidates, matchesToolPattern, resolveToolPrefix, } from "./types.js";
+import { sanitizeTerminalText } from "./utils.js";
+export function isToolCallApprovalRequired(config, serverName, toolMeta) {
+    const definition = config.mcpServers[serverName];
+    const approval = definition?.approveTools !== undefined
+        ? definition.approveTools
+        : config.settings?.approveTools;
+    if (approval === true)
+        return true;
+    if (!Array.isArray(approval) || approval.length === 0)
+        return false;
+    const prefix = resolveToolPrefix(definition, config.settings?.toolPrefix);
+    return matchesToolPattern(getToolNameCandidates(toolMeta.originalName, serverName, prefix), approval);
+}
+export async function ensureToolCallApproved(state, serverName, toolMeta, args, signal) {
+    if (!isToolCallApprovalRequired(state.config, serverName, toolMeta)) {
+        return { ok: true };
+    }
+    const cacheKey = `${serverName}\u0000${toolMeta.originalName}`;
+    if (state.approvedToolCalls.has(cacheKey)) {
+        return { ok: true };
+    }
+    if (!state.ui) {
+        return { ok: false, reason: "approval_required_headless" };
+    }
+    const json = JSON.stringify(args ?? {}, null, 2);
+    const sanitized = sanitizeTerminalText(json);
+    const preview = sanitized.length > 500 ? `${sanitized.slice(0, 500)}...` : sanitized;
+    const title = `MCP: ${sanitizeTerminalText(serverName)} wants to run ${sanitizeTerminalText(toolMeta.originalName)}`;
+    const ownedSignal = combineAbortSignals(state.owner?.signal, signal);
+    const decision = await abortable(state.ui.select(`${title}\n\nArguments:\n${preview}`, ["Allow once", "Allow for session", "Deny"]), ownedSignal);
+    if (decision === "Allow once") {
+        return { ok: true };
+    }
+    if (decision === "Allow for session") {
+        state.approvedToolCalls.set(cacheKey, true);
+        return { ok: true };
+    }
+    return { ok: false, reason: "denied" };
+}

package/dist/tool-metadata.d.ts

@@ -0,0 +1,9 @@
+import type { McpExtensionState } from "./state.ts";
+import type { ToolMetadata, McpTool, McpResource, ServerEntry, ToolPrefix } from "./types.ts";
+export declare function buildToolMetadata(tools: McpTool[], resources: McpResource[], definition: ServerEntry, serverName: string, prefix: ToolPrefix): {
+    metadata: ToolMetadata[];
+    failedTools: string[];
+};
+export declare function totalToolCount(state: McpExtensionState): number;
+export declare function findToolByName(metadata: ToolMetadata[] | undefined, toolName: string): ToolMetadata | undefined;
+export declare function formatSchema(schema: unknown, indent?: string): string;

package/dist/tool-metadata.js

@@ -0,0 +1,193 @@
+import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { formatToolName, isToolAllowed, resolveToolPrefix } from "./types.js";
+import { resourceNameToToolName } from "./resource-tools.js";
+import { extractToolUiStreamMode } from "./utils.js";
+import { extractUiToolVisibility, isUiToolVisibleToModel } from "./ui-tool-visibility.js";
+export function buildToolMetadata(tools, resources, definition, serverName, prefix) {
+    const metadata = [];
+    const failedTools = [];
+    const seenNames = new Set();
+    const effectivePrefix = resolveToolPrefix(definition, prefix);
+    for (const tool of tools) {
+        if (!tool?.name) {
+            failedTools.push("(unnamed)");
+            continue;
+        }
+        if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools)) {
+            continue;
+        }
+        const name = formatToolName(tool.name, serverName, effectivePrefix);
+        if (seenNames.has(name)) {
+            continue;
+        }
+        const uiVisibility = extractUiToolVisibility(tool._meta);
+        if (!isUiToolVisibleToModel(uiVisibility)) {
+            continue;
+        }
+        seenNames.add(name);
+        let uiResourceUri;
+        try {
+            uiResourceUri = getToolUiResourceUri({ _meta: tool._meta });
+        }
+        catch {
+            failedTools.push(tool.name);
+        }
+        const uiStreamMode = extractToolUiStreamMode(tool._meta);
+        metadata.push({
+            name,
+            originalName: tool.name,
+            description: tool.description ?? "",
+            ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
+            ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
+            ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
+            ...(uiVisibility !== undefined ? { uiVisibility } : {}),
+            ...(uiStreamMode !== undefined ? { uiStreamMode } : {}),
+        });
+    }
+    if (definition.exposeResources !== false) {
+        for (const resource of resources) {
+            const baseName = `read_${resourceNameToToolName(resource.name)}`;
+            if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools)) {
+                continue;
+            }
+            const name = formatToolName(baseName, serverName, effectivePrefix);
+            if (seenNames.has(name)) {
+                continue;
+            }
+            seenNames.add(name);
+            metadata.push({
+                name,
+                originalName: baseName,
+                description: resource.description ?? `Read resource: ${resource.uri}`,
+                resourceUri: resource.uri,
+            });
+        }
+    }
+    return { metadata, failedTools };
+}
+export function totalToolCount(state) {
+    let count = 0;
+    for (const metadata of state.toolMetadata.values()) {
+        count += metadata.length;
+    }
+    return count;
+}
+export function findToolByName(metadata, toolName) {
+    if (!metadata)
+        return undefined;
+    const exact = metadata.find(m => m.name === toolName);
+    if (exact)
+        return exact;
+    const normalized = toolName.replace(/-/g, "_");
+    return metadata.find(m => m.name.replace(/-/g, "_") === normalized);
+}
+export function formatSchema(schema, indent = "  ") {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return `${indent}(no schema)`;
+    }
+    const s = schema;
+    if (s.type === "object" && s.properties && typeof s.properties === "object" && !Array.isArray(s.properties)) {
+        const props = s.properties;
+        const required = Array.isArray(s.required) ? s.required.filter((name) => typeof name === "string") : [];
+        if (Object.keys(props).length === 0) {
+            return `${indent}(no parameters)`;
+        }
+        const lines = [];
+        for (const [name, propSchema] of Object.entries(props)) {
+            lines.push(...formatProperty(name, propSchema, required.includes(name), indent));
+        }
+        return lines.join("\n");
+    }
+    const lines = formatNestedSchema(s, indent);
+    if (lines.length > 0) {
+        return lines.join("\n");
+    }
+    const typeStr = formatType(s);
+    if (typeStr) {
+        return `${indent}(${typeStr})`;
+    }
+    return `${indent}(complex schema)`;
+}
+function formatProperty(name, schema, required, indent) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return [`${indent}${name}${required ? " *required*" : ""}`];
+    }
+    const s = schema;
+    const parts = [`${indent}${name}`];
+    const typeStr = formatType(s);
+    if (typeStr)
+        parts.push(`(${typeStr})`);
+    if (required)
+        parts.push("*required*");
+    appendSchemaAnnotations(parts, s);
+    return [parts.join(" "), ...formatNestedSchema(s, `${indent}  `)];
+}
+function formatNestedSchema(schema, indent) {
+    const lines = [];
+    if (Array.isArray(schema.anyOf)) {
+        lines.push(...formatVariants("anyOf", schema.anyOf, indent));
+    }
+    if (Array.isArray(schema.oneOf)) {
+        lines.push(...formatVariants("oneOf", schema.oneOf, indent));
+    }
+    if (schema.items !== undefined) {
+        lines.push(...formatProperty("items", schema.items, false, indent));
+    }
+    if (schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)) {
+        const required = Array.isArray(schema.required) ? schema.required.filter((name) => typeof name === "string") : [];
+        for (const [name, propSchema] of Object.entries(schema.properties)) {
+            lines.push(...formatProperty(name, propSchema, required.includes(name), indent));
+        }
+    }
+    return lines;
+}
+function formatVariants(keyword, variants, indent) {
+    const lines = [`${indent}${keyword}:`];
+    for (const variant of variants) {
+        if (!variant || typeof variant !== "object" || Array.isArray(variant)) {
+            lines.push(`${indent}  - ${JSON.stringify(variant)}`);
+            continue;
+        }
+        const s = variant;
+        const typeStr = formatType(s) || "schema";
+        const parts = [`${indent}  - ${typeStr}`];
+        appendSchemaAnnotations(parts, s);
+        lines.push(parts.join(" "));
+        lines.push(...formatNestedSchema(s, `${indent}    `));
+    }
+    return lines;
+}
+function formatType(schema) {
+    if (Object.hasOwn(schema, "const")) {
+        return `const ${JSON.stringify(schema.const)}`;
+    }
+    if (Array.isArray(schema.enum)) {
+        return `enum: ${schema.enum.map(v => JSON.stringify(v)).join(", ")}`;
+    }
+    if (Array.isArray(schema.type)) {
+        return schema.type.map(type => String(type)).join(" | ");
+    }
+    if (schema.type) {
+        return String(schema.type);
+    }
+    if (schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)) {
+        return "object";
+    }
+    if (schema.items !== undefined) {
+        return "array";
+    }
+    return "";
+}
+function appendSchemaAnnotations(parts, schema) {
+    if (schema.description && typeof schema.description === "string") {
+        parts.push(`- ${schema.description}`);
+    }
+    for (const key of ["minLength", "maxLength", "minimum", "maximum", "minItems", "maxItems", "format", "pattern"]) {
+        if (schema[key] !== undefined) {
+            parts.push(`[${key}: ${JSON.stringify(schema[key])}]`);
+        }
+    }
+    if (schema.default !== undefined) {
+        parts.push(`[default: ${JSON.stringify(schema.default)}]`);
+    }
+}

package/dist/tool-registrar.d.ts

@@ -0,0 +1,10 @@
+import type { McpContent, ContentBlock } from "./types.ts";
+/**
+ * Transform MCP content types to Pi content blocks.
+ */
+export declare function transformMcpContent(content: McpContent[]): ContentBlock[];
+/**
+ * Resolve a tool result's content blocks, falling back to structuredContent
+ * when content is empty.
+ */
+export declare function resolveMcpResultContent(result: Record<string, unknown>): ContentBlock[];