@fitchmultz/pi-mcp-adapter 5.0.0

package/dist/mcp-code.js

@@ -0,0 +1,366 @@
+import { formatWithOptions } from "node:util";
+import { Worker } from "node:worker_threads";
+import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.js";
+import { executeCall } from "./proxy-modes.js";
+import { combineAbortSignals } from "./runtime-owner.js";
+import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.js";
+import { findToolByName } from "./tool-metadata.js";
+import { renderTsShape } from "./ts-shape.js";
+export const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30_000;
+class McpScriptTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`mcp_script timed out after ${timeoutMs}ms`);
+        this.name = "McpScriptTimeoutError";
+    }
+}
+function needsInspectableFormatting(value, stack = new WeakSet()) {
+    if (value === undefined || typeof value === "bigint" || typeof value === "function" || typeof value === "symbol")
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (stack.has(value))
+        return true;
+    if (value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet)
+        return true;
+    stack.add(value);
+    try {
+        return Object.values(value).some((entry) => needsInspectableFormatting(entry, stack));
+    }
+    finally {
+        stack.delete(value);
+    }
+}
+function formatValue(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        if (!needsInspectableFormatting(value)) {
+            const json = JSON.stringify(value, null, 2);
+            if (json !== undefined)
+                return json;
+        }
+        return formatWithOptions({ colors: false, depth: 6 }, value);
+    }
+    catch {
+        return "[unserializable value]";
+    }
+}
+function toContentBlock(value) {
+    if (typeof value === "object" && value !== null) {
+        const block = value;
+        if (block.type === "text" && typeof block.text === "string") {
+            return { type: "text", text: block.text };
+        }
+        if (block.type === "image" && typeof block.data === "string" && typeof block.mimeType === "string") {
+            return { type: "image", data: block.data, mimeType: block.mimeType };
+        }
+    }
+    return { type: "text", text: formatValue(value) };
+}
+function textFromContent(content) {
+    return content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+}
+function abortReasonError(reason) {
+    return reason instanceof Error ? reason : new Error(String(reason ?? "MCP request aborted"));
+}
+function parseWorkerMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const message = value;
+    if (message.type === "emit" && "block" in message)
+        return { type: "emit", block: message.block };
+    if (message.type === "call" && typeof message.id === "number" && typeof message.path === "string") {
+        return "args" in message
+            ? { type: "call", id: message.id, path: message.path, args: message.args }
+            : { type: "call", id: message.id, path: message.path };
+    }
+    if ((message.type === "search" || message.type === "describe") && typeof message.id === "number") {
+        return "input" in message
+            ? { type: message.type, id: message.id, input: message.input }
+            : { type: message.type, id: message.id };
+    }
+    if (message.type === "done") {
+        return "returnBlock" in message ? { type: "done", returnBlock: message.returnBlock } : { type: "done" };
+    }
+    if (message.type === "error" && typeof message.message === "string") {
+        return { type: "error", message: message.message };
+    }
+    return null;
+}
+class McpScriptCaptureError extends Error {
+    recovery;
+    constructor(recovery, message) {
+        super(message);
+        this.recovery = recovery;
+    }
+}
+export const runMcpScript = async (...args) => {
+    const state = args[0];
+    state.owner?.beforeActivity();
+    state.activeScripts = (state.activeScripts ?? 0) + 1;
+    try {
+        return await runMcpScriptOperation(...args);
+    }
+    finally {
+        state.activeScripts--;
+    }
+};
+async function runMcpScriptOperation(state, code, timeoutMs = DEFAULT_MCP_SCRIPT_TIMEOUT_MS, getPiTools, signal, toolCallId, beforeDispatch) {
+    const resolvedTimeoutMs = timeoutMs === null ? null : Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? Math.floor(timeoutMs)
+        : DEFAULT_MCP_SCRIPT_TIMEOUT_MS;
+    const output = [];
+    const externalSignal = combineAbortSignals(state.owner?.signal, signal);
+    const timeoutController = new AbortController();
+    const callSignal = combineAbortSignals(externalSignal, timeoutController.signal);
+    const calls = [];
+    const snapshotCalls = () => calls.map(({ startedAt, ...operation }) => ({
+        ...operation,
+        durationMs: "error" in operation && operation.error === "incomplete"
+            ? Math.max(0, Date.now() - startedAt)
+            : operation.durationMs,
+    }));
+    let callsSnapshot;
+    const callTool = async (innerCallId, path, args) => {
+        // Record before dispatch so calls still in flight at timeout/abort appear in the trace.
+        const startedAt = Date.now();
+        const index = calls.push({ operation: "call", path, ok: false, error: "incomplete", durationMs: 0, startedAt }) - 1;
+        let rawResult;
+        let hasRawResult = false;
+        const result = await executeCall(state, path, args, undefined, getPiTools, callSignal, (raw) => {
+            rawResult = raw;
+            hasRawResult = true;
+        }, { ...(toolCallId !== undefined ? { toolCallId } : {}), innerCallId }, beforeDispatch);
+        const details = result.details;
+        if (details.error !== undefined) {
+            const errorCode = String(details.error);
+            const suggestions = Array.isArray(details.suggestions)
+                ? details.suggestions.filter((suggestion) => typeof suggestion === "string")
+                : [];
+            const message = errorCode === "tool_not_found"
+                ? `Tool "${path}" not found. Use await tools.search({ query: "..." }) inside mcp_script.${suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : ""}`
+                : typeof details.message === "string"
+                    ? details.message
+                    : textFromContent(result.content);
+            calls[index] = {
+                operation: "call", path, ok: false, error: errorCode, durationMs: Date.now() - startedAt, startedAt,
+                ...(errorCode === "ambiguous_outcome" ? { recovery: details.recovery } : {}),
+            };
+            if (errorCode === "call_capture_failed")
+                throw new McpScriptCaptureError(details.recovery, message);
+            if (errorCode === "ambiguous_outcome")
+                output.push({ type: "text", text: message });
+            return {
+                ok: false,
+                error: { code: errorCode, message, ...(details.recovery ? { recovery: details.recovery } : {}) },
+            };
+        }
+        calls[index] = { operation: "call", path, ok: true, durationMs: Date.now() - startedAt, startedAt };
+        return {
+            ok: true,
+            data: hasRawResult ? rawResult : details.mcpResult !== undefined ? details.mcpResult : textFromContent(result.content),
+        };
+    };
+    const searchTools = (input) => {
+        const startedAt = Date.now();
+        const query = typeof input?.query === "string" ? input.query : "";
+        let error;
+        try {
+            if (query.trim() === "") {
+                return { items: [], total: 0, hasMore: false, nextOffset: null };
+            }
+            const server = typeof input?.server === "string" ? input.server : undefined;
+            const limit = typeof input?.limit === "number" ? input.limit : 12;
+            const offset = typeof input?.offset === "number" ? input.offset : 0;
+            const page = paginate(rankToolMatches(state, query, server), offset, limit);
+            return {
+                ...page,
+                items: page.items.map(({ server: matchServer, tool, score }) => ({
+                    path: tool.name,
+                    name: tool.originalName,
+                    server: matchServer,
+                    ...(tool.description ? { description: tool.description } : {}),
+                    score,
+                })),
+            };
+        }
+        catch (caught) {
+            error = caught;
+            throw caught;
+        }
+        finally {
+            calls.push(error === undefined
+                ? { operation: "search", query, ok: true, durationMs: Date.now() - startedAt, startedAt }
+                : { operation: "search", query, ok: false, error: error instanceof Error ? error.message : String(error), durationMs: Date.now() - startedAt, startedAt });
+        }
+    };
+    const describeTool = (input) => {
+        const startedAt = Date.now();
+        const path = typeof input?.path === "string" ? input.path : "";
+        let error;
+        try {
+            for (const [server, metadata] of state.toolMetadata) {
+                const tool = findToolByName(metadata, path);
+                if (!tool)
+                    continue;
+                const inputTypeScript = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
+                return {
+                    path: tool.name,
+                    name: tool.originalName,
+                    server,
+                    ...(tool.description ? { description: tool.description } : {}),
+                    ...(inputTypeScript ? { inputTypeScript } : tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
+                    ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
+                };
+            }
+            const suggestions = path ? rankSuggestions(state, path, 5) : [];
+            error = "tool_not_found";
+            return {
+                path,
+                error: {
+                    code: "tool_not_found",
+                    message: `Tool not found: ${path}`,
+                    suggestions,
+                },
+            };
+        }
+        catch (caught) {
+            error = caught;
+            throw caught;
+        }
+        finally {
+            calls.push(error === undefined
+                ? { operation: "describe", path, ok: true, durationMs: Date.now() - startedAt, startedAt }
+                : { operation: "describe", path, ok: false, error: error instanceof Error ? error.message : String(error), durationMs: Date.now() - startedAt, startedAt });
+        }
+    };
+    let worker;
+    let timer;
+    let removeAbortListener = () => { };
+    let errorCode;
+    let recovery;
+    let errorMessage;
+    try {
+        if (externalSignal?.aborted) {
+            throw abortReasonError(externalSignal.reason);
+        }
+        worker = new Worker(new URL("./mcp-script-worker.mjs", import.meta.url), {
+            workerData: { code },
+            env: {},
+        });
+        const activeWorker = worker;
+        const execution = new Promise((resolve, reject) => {
+            let completed = false;
+            activeWorker.on("message", (value) => {
+                const message = parseWorkerMessage(value);
+                if (!message || completed)
+                    return;
+                if (message.type === "emit") {
+                    output.push(toContentBlock(message.block));
+                    return;
+                }
+                if (message.type === "done") {
+                    completed = true;
+                    if ("returnBlock" in message)
+                        output.push(toContentBlock(message.returnBlock));
+                    resolve();
+                    return;
+                }
+                if (message.type === "error") {
+                    completed = true;
+                    reject(new Error(message.message));
+                    return;
+                }
+                void (async () => {
+                    let envelope;
+                    if (message.type === "call") {
+                        envelope = await callTool(message.id, message.path, message.args);
+                    }
+                    else if (message.type === "search") {
+                        envelope = searchTools(message.input);
+                    }
+                    else {
+                        envelope = describeTool(message.input);
+                    }
+                    const response = { type: "result", id: message.id, envelope };
+                    activeWorker.postMessage(response);
+                })().catch(reject);
+            });
+            activeWorker.once("error", reject);
+            activeWorker.once("exit", (code) => {
+                if (!completed && code !== 0)
+                    reject(new Error(`mcp_script worker exited with code ${code}`));
+            });
+        });
+        const timeout = new Promise((_resolve, reject) => {
+            if (resolvedTimeoutMs === null)
+                return;
+            const timeoutError = new McpScriptTimeoutError(resolvedTimeoutMs);
+            timer = setTimeout(() => {
+                callsSnapshot = snapshotCalls();
+                timeoutController.abort(timeoutError);
+                void activeWorker.terminate();
+                reject(timeoutError);
+            }, resolvedTimeoutMs);
+        });
+        const aborted = externalSignal
+            ? new Promise((_resolve, reject) => {
+                const onAbort = () => {
+                    callsSnapshot = snapshotCalls();
+                    void activeWorker.terminate();
+                    reject(abortReasonError(externalSignal.reason));
+                };
+                externalSignal.addEventListener("abort", onAbort, { once: true });
+                removeAbortListener = () => externalSignal.removeEventListener("abort", onAbort);
+            })
+            : new Promise(() => { });
+        await Promise.race([execution, timeout, aborted]);
+    }
+    catch (error) {
+        if (error instanceof McpScriptCaptureError) {
+            errorCode = "call_capture_failed";
+            errorMessage = error.message;
+            recovery = error.recovery;
+        }
+        else if (error instanceof McpScriptTimeoutError) {
+            errorCode = "timeout";
+            errorMessage = `mcp_script timed out after ${resolvedTimeoutMs}ms`;
+        }
+        else if (externalSignal?.aborted) {
+            errorCode = "aborted";
+            errorMessage = error instanceof Error ? error.message : String(error);
+        }
+        else {
+            errorCode = "script_error";
+            errorMessage = error instanceof Error ? error.message : String(error);
+        }
+        output.push({ type: "text", text: errorMessage });
+    }
+    finally {
+        clearTimeout(timer);
+        removeAbortListener();
+        // "incomplete" means the call had not settled when the script finished
+        // (deadline, abort, or early return). Snapshot before aborting stragglers.
+        callsSnapshot ??= snapshotCalls();
+        // A script may finish without awaiting every call; abort leftovers so
+        // parent-side dispatches do not outlive the script.
+        timeoutController.abort(new Error("mcp_script finished"));
+        await worker?.terminate();
+    }
+    // Snapshot before the asynchronous output guard; the terminated worker can no longer emit.
+    const guarded = await guardMcpOutput(output.length > 0 ? [...output] : [{ type: "text", text: "(no output)" }], resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory));
+    return {
+        content: guarded.content,
+        details: {
+            mode: "script",
+            ...(errorCode ? { error: errorCode, message: errorMessage } : {}),
+            timeoutMs: resolvedTimeoutMs,
+            ...(recovery !== undefined ? { recovery } : {}),
+            ...(callsSnapshot.length > 0 ? { calls: callsSnapshot } : {}),
+            ...guardedMcpDetails(guarded),
+        },
+    };
+}

package/dist/mcp-keyring-helper.cjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createRequire } = require('node:module');
+const { dirname, join } = require('node:path');
+
+const requireFromHere = createRequire(__filename);
+
+function loadKeyringEntryClass() {
+  try {
+    return requireFromHere('@napi-rs/keyring').Entry;
+  } catch (loaderError) {
+    const suffixes = getNativeBindingSuffixes(process.platform, process.arch);
+    let lastError;
+    for (const suffix of suffixes) {
+      try {
+        const packageJsonPath = requireFromHere.resolve(`@napi-rs/keyring-${suffix}/package.json`);
+        return requireFromHere(join(dirname(packageJsonPath), `keyring.${suffix}.node`)).Entry;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    const error = new Error(`Failed to load @napi-rs/keyring in recovery helper: ${lastError?.message ?? loaderError.message}`);
+    error.cause = loaderError;
+    throw error;
+  }
+}
+
+function getNativeBindingSuffixes(platform, arch) {
+  if (platform === 'linux') {
+    if (arch === 'arm64') return ['linux-arm64-gnu', 'linux-arm64-musl'];
+    if (arch === 'arm') return ['linux-arm-gnueabihf'];
+    if (arch === 'riscv64') return ['linux-riscv64-gnu'];
+    if (arch === 'x64') return ['linux-x64-gnu', 'linux-x64-musl'];
+  }
+  return [];
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      input += chunk;
+      if (input.length > 1024 * 1024) {
+        reject(new Error('request too large'));
+        process.stdin.destroy();
+      }
+    });
+    process.stdin.on('error', reject);
+    process.stdin.on('end', () => resolve(input));
+  });
+}
+
+function writeResponse(response) {
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
+
+(async () => {
+  try {
+    const request = JSON.parse(await readStdin());
+    if (!request || typeof request !== 'object') throw new Error('invalid request');
+    const { operation, service, account, payload } = request;
+    if (!['read', 'write', 'remove'].includes(operation)) throw new Error('invalid operation');
+    if (typeof service !== 'string' || !service) throw new Error('invalid service');
+    if (typeof account !== 'string' || !account) throw new Error('invalid account');
+
+    const Entry = loadKeyringEntryClass();
+    const entry = new Entry(service, account);
+
+    if (operation === 'read') {
+      const value = entry.getPassword();
+      writeResponse(value === null ? { ok: true, found: false } : { ok: true, found: true, value });
+      return;
+    }
+    if (operation === 'write') {
+      if (typeof payload !== 'string') throw new Error('invalid payload');
+      entry.setPassword(payload);
+      writeResponse({ ok: true });
+      return;
+    }
+
+    entry.deleteCredential();
+    writeResponse({ ok: true });
+  } catch (error) {
+    writeResponse({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    process.exitCode = 1;
+  }
+})();

package/dist/mcp-oauth-provider.d.ts

@@ -0,0 +1,154 @@
+/**
+ * MCP OAuth Provider
+ *
+ * Implementation of the MCP SDK's OAuthClientProvider interface.
+ * Handles OAuth client registration, token storage, and authorization redirection.
+ */
+import { type FetchLike, type AddClientAuthentication, type OAuthClientProvider, type OAuthClientInformationContext, type StoredOAuthClientInformation, type StoredOAuthTokens, type OAuthDiscoveryState } from "@modelcontextprotocol/client";
+import type { OAuthClientMetadata } from "@modelcontextprotocol/client";
+import { type AuthStorageOptions } from "./mcp-auth.ts";
+import { type OAuthPrivateKeyJwtConfig, type OAuthCrossAppAccessConfig } from "./types.ts";
+/** Validate explicit document URLs without echoing possible credentials in errors. */
+export declare function validateOAuthClientMetadataUrl(value: string | false | undefined): void;
+/** Only the port may differ; keep raw host, path and query spelling exact. */
+export declare function loopbackRedirectsMatch(first: string, second: unknown): boolean;
+export declare function issuersMatch(first: string, second: string): boolean;
+declare const DEFAULT_OAUTH_CALLBACK_PORT = 19876;
+declare const DEFAULT_OAUTH_CALLBACK_PATH = "/callback";
+export declare function getConfiguredOAuthCallbackPort(): number;
+export declare function getOAuthCallbackPort(): number;
+export declare function setOAuthCallbackPort(port: number): void;
+export declare function getOAuthCallbackPath(): string;
+export declare function setOAuthCallbackPath(path: string): void;
+/** Configuration options for OAuth */
+export interface McpOAuthConfig {
+    skipIssuerMetadataValidation?: boolean;
+    grantType?: "authorization_code" | "client_credentials";
+    clientId?: string;
+    clientSecret?: string;
+    privateKeyJwt?: OAuthPrivateKeyJwtConfig;
+    crossAppAccess?: OAuthCrossAppAccessConfig;
+    scope?: string;
+    authorizationParams?: Record<string, string>;
+    redirectUri?: string;
+    clientName?: string;
+    clientUri?: string;
+    /** Custom client document URL; false disables automatic CIMD for new registrations. */
+    clientMetadataUrl?: string | false;
+}
+/** Validate shapes and method conflicts without resolving or disclosing key sources. */
+export declare function validateOAuthPrivateKeyJwt(config: McpOAuthConfig): void;
+export declare function validateOAuthCrossAppAccess(config: McpOAuthConfig): void;
+/** Callbacks for OAuth flow interactions */
+export interface McpOAuthCallbacks {
+    onRedirect: (url: URL) => void | Promise<void>;
+    onDiscoveryState?: (state: OAuthDiscoveryState) => void;
+}
+/**
+ * OAuth provider implementation for MCP servers.
+ * Implements the OAuthClientProvider interface from the MCP SDK.
+ */
+export declare class McpOAuthProvider implements OAuthClientProvider {
+    private serverName;
+    private serverUrl;
+    private config;
+    private callbacks;
+    private storageOptions;
+    private readonly redirectUrlSnapshot;
+    readonly clientMetadataUrl?: string;
+    private readonly controller;
+    readonly lifetimeSignal: AbortSignal;
+    private readonly requestSignals;
+    private flowAuthorizationServerUrl;
+    private flowResourceUrl;
+    private flowClientInfo;
+    private flowCodeVerifier;
+    private flowDiscoveryState;
+    private flowIssuerMismatch;
+    private flowState;
+    constructor(serverName: string, serverUrl: string, config: McpOAuthConfig, callbacks: McpOAuthCallbacks, storageOptions?: AuthStorageOptions, runtimeSignal?: AbortSignal, initialState?: string);
+    private get isNonInteractive();
+    private get discoveredIssuer();
+    get signal(): AbortSignal;
+    runWithSignal<T>(signal: AbortSignal | undefined, operation: () => T): T;
+    deactivate(): void;
+    private assertStoredIssuerBindings;
+    private throwIfInactive;
+    /**
+     * The redirect URL for OAuth callbacks.
+     * This must match the redirect_uri in client metadata.
+     */
+    get redirectUrl(): string | undefined;
+    /**
+     * Client metadata for dynamic registration.
+     * Describes this client to the OAuth authorization server.
+     */
+    get clientMetadata(): OAuthClientMetadata;
+    /**
+     * Get client information (for pre-registered or dynamically registered clients).
+     * Returns undefined if no client info exists or if the server URL has changed.
+     */
+    clientInformation(context?: OAuthClientInformationContext): Promise<StoredOAuthClientInformation | undefined>;
+    /**
+     * Save client information from dynamic registration.
+     */
+    saveClientInformation(info: StoredOAuthClientInformation, context?: OAuthClientInformationContext): Promise<void>;
+    /**
+     * Get stored OAuth tokens.
+     * Returns undefined if no tokens exist or if the server URL has changed.
+     */
+    tokens(context?: OAuthClientInformationContext): Promise<StoredOAuthTokens | undefined>;
+    /**
+     * Save OAuth tokens.
+     */
+    saveTokens(tokens: StoredOAuthTokens, context?: OAuthClientInformationContext): Promise<void>;
+    /**
+     * Redirect the user to the authorization URL.
+     * This opens the browser for the user to authenticate.
+     *
+     * Throws UnauthorizedError when called outside of a user-initiated flow
+     * (no oauthState saved by startAuth). That path is reached when the SDK
+     * falls through from a failed refresh into a fresh authorization_code
+     * flow, which library hosts cannot complete in-process.
+     */
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    /**
+     * Save the PKCE code verifier.
+     */
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    /**
+     * Get the stored PKCE code verifier.
+     * @throws Error if no code verifier is stored
+     */
+    codeVerifier(): Promise<string>;
+    /**
+     * Keep discovery with the in-flight PKCE verifier. The callback leg uses it
+     * to validate the authorization response issuer before token exchange.
+     */
+    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
+    saveAuthorizationServerUrl(issuer: string): void;
+    saveResourceUrl(resource: string): void;
+    readonly fetch: FetchLike;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    /**
+     * Save the OAuth state parameter for CSRF protection.
+     */
+    saveState(state: string): Promise<void>;
+    /**
+     * Get the stored OAuth state parameter.
+     * @throws UnauthorizedError if no flow is in progress (see redirectToAuthorization)
+     */
+    state(): Promise<string>;
+    /**
+     * Invalidate credentials when authentication fails.
+     * Clears tokens, client info, or all credentials based on the type.
+     */
+    invalidateCredentials(type: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void>;
+    /**
+     * Adds configured scope and client authentication to native token requests.
+     */
+    addClientAuthentication: AddClientAuthentication;
+    private prepareCrossAppRequest;
+    prepareTokenRequest(scope?: string): URLSearchParams | Promise<URLSearchParams> | undefined;
+}
+export { DEFAULT_OAUTH_CALLBACK_PORT, DEFAULT_OAUTH_CALLBACK_PATH };