@fitchmultz/pi-mcp-adapter 5.0.0

package/dist/mcp-callback-server.d.ts

@@ -0,0 +1,56 @@
+/**
+ * MCP OAuth Callback Server
+ *
+ * HTTP server that handles OAuth callbacks from the authorization server.
+ * Uses Node.js http module for compatibility.
+ */
+/** Result of a successful OAuth callback */
+export interface OAuthCallbackResult {
+    code: string;
+    /** RFC 9207 `iss` authorization response parameter, when provided */
+    iss?: string;
+}
+export type ValidateOAuthCallback = (response: {
+    iss?: string;
+    error?: string;
+}) => void;
+type ReservedAuth = {
+    validate: ValidateOAuthCallback | undefined;
+    result?: OAuthCallbackResult | {
+        error: string;
+        iss?: string;
+    };
+};
+interface EnsureCallbackServerOptions {
+    strictPort?: boolean;
+    port?: number;
+    callbackHost?: string;
+    callbackPath?: string;
+    oauthState?: string;
+    reserveState?: boolean;
+    validate?: ValidateOAuthCallback;
+}
+/**
+ * Ensure the callback server is running.
+ * If strictPort is true, requires binding on the configured callback port.
+ * If strictPort is false, asks the OS for an available local port.
+ */
+export declare function ensureCallbackServer(options?: EnsureCallbackServerOptions): Promise<void>;
+export declare function releaseCallbackServer(oauthState: string): void;
+/** Consume a validated manual callback without releasing the flow's reservation. */
+export declare function takeCallbackResult(oauthState: string): ReservedAuth["result"];
+/**
+ * Wait for a callback with the given OAuth state.
+ * Returns a promise that resolves with the authorization code and, when the
+ * authorization server sends one, the RFC 9207 `iss` parameter.
+ */
+export declare function waitForCallback(oauthState: string): Promise<OAuthCallbackResult>;
+/**
+ * Cancel a pending authorization by state.
+ */
+export declare function cancelPendingCallback(oauthState: string): void;
+/**
+ * Stop the callback server and reject all pending authorizations.
+ */
+export declare function stopCallbackServer(): Promise<void>;
+export {};

package/dist/mcp-callback-server.js

@@ -0,0 +1,371 @@
+/**
+ * MCP OAuth Callback Server
+ *
+ * HTTP server that handles OAuth callbacks from the authorization server.
+ * Uses Node.js http module for compatibility.
+ */
+import { createServer } from "http";
+import { DEFAULT_OAUTH_CALLBACK_PATH, getConfiguredOAuthCallbackPort, getOAuthCallbackPath, getOAuthCallbackPort, setOAuthCallbackPath, setOAuthCallbackPort, } from "./mcp-oauth-provider.js";
+// HTML templates for callback responses
+const HTML_SUCCESS = `<!DOCTYPE html>
+<html>
+<head>
+  <title>Pi - Authorization Successful</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #1a1a2e; color: #eee; }
+    .container { text-align: center; padding: 2rem; }
+    h1 { color: #4ade80; margin-bottom: 1rem; }
+    p { color: #aaa; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Authorization Successful</h1>
+    <p>You can close this window and return to Pi.</p>
+  </div>
+  <script>setTimeout(() => window.close(), 2000);</script>
+</body>
+</html>`;
+const HTML_MANUAL_SUCCESS = `<!DOCTYPE html>
+<html>
+<head>
+  <title>Pi - Authorization Received</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #1a1a2e; color: #eee; }
+    .container { text-align: center; padding: 2rem; }
+    h1 { color: #4ade80; margin-bottom: 1rem; }
+    p { color: #aaa; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Authorization Received</h1>
+    <p>Return to Pi and run auth-complete for this server. No callback URL or code is needed.</p>
+  </div>
+</body>
+</html>`;
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+const HTML_ERROR = (error) => `<!DOCTYPE html>
+<html>
+<head>
+  <title>Pi - Authorization Failed</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #1a1a2e; color: #eee; }
+    .container { text-align: center; padding: 2rem; }
+    h1 { color: #f87171; margin-bottom: 1rem; }
+    p { color: #aaa; }
+    .error { color: #fca5a5; font-family: monospace; margin-top: 1rem; padding: 1rem; background: rgba(248,113,113,0.1); border-radius: 0.5rem; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Authorization Failed</h1>
+    <p>An error occurred during authorization.</p>
+    <div class="error">${escapeHtml(error)}</div>
+  </div>
+</body>
+</html>`;
+/** Server singleton state */
+let server;
+let bindingPromise;
+let stoppingPromise;
+let callbackGeneration = 0;
+const pendingAuths = new Map();
+const reservedAuthStates = new Map();
+/** Timeout for callback completion (5 minutes) */
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_OAUTH_CALLBACK_HOST = "localhost";
+let callbackServerHost = DEFAULT_OAUTH_CALLBACK_HOST;
+/**
+ * Handle incoming HTTP requests to the callback server.
+ */
+function handleRequest(req, res) {
+    const url = new URL(req.url || "/", `http://${req.headers.host}`);
+    // Only handle the callback path
+    if (url.pathname !== getOAuthCallbackPath()) {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not found");
+        return;
+    }
+    const code = url.searchParams.get("code");
+    const iss = url.searchParams.get("iss");
+    const state = url.searchParams.get("state");
+    const error = url.searchParams.get("error");
+    const errorDescription = url.searchParams.get("error_description");
+    // Enforce state parameter presence for CSRF protection
+    if (!state) {
+        const errorMsg = "Missing required state parameter - potential CSRF attack";
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(HTML_ERROR(errorMsg));
+        return;
+    }
+    const pending = pendingAuths.get(state);
+    const reserved = reservedAuthStates.get(state);
+    if (!pending && !reserved) {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(HTML_ERROR("Invalid or expired state parameter - potential CSRF attack"));
+        return;
+    }
+    try {
+        const validate = pending?.validate ?? reserved?.validate;
+        if (validate)
+            validate({ ...(iss !== null ? { iss } : {}), ...(error ? { error } : {}) });
+        else if (error)
+            throw new Error("Cannot verify the OAuth error callback issuer");
+    }
+    catch (failure) {
+        const message = failure instanceof Error ? failure.message : "Invalid OAuth callback";
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(HTML_ERROR(message));
+        if (pending) {
+            clearTimeout(pending.timeout);
+            pendingAuths.delete(state);
+            reservedAuthStates.delete(state);
+            pending.reject(new Error(message));
+        }
+        return;
+    }
+    // Provider error text is only trusted after state and issuer validation.
+    if (error) {
+        const errorMsg = errorDescription || error;
+        // Send HTTP response first before rejecting promise
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(HTML_ERROR(errorMsg));
+        // Reject promise after response is sent (defer to allow test to attach handler)
+        if (pending) {
+            reservedAuthStates.delete(state);
+            clearTimeout(pending.timeout);
+            pendingAuths.delete(state);
+            setTimeout(() => pending.reject(new Error(errorMsg)), 0);
+        }
+        else if (reserved) {
+            // Keep provider-controlled callback payloads out of tool output.
+            reserved.result = { error: "OAuth authorization was denied or failed. Finish authorization in the browser, then retry auth-complete.", ...(iss !== null ? { iss } : {}) };
+        }
+        return;
+    }
+    // Require authorization code
+    if (!code) {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(HTML_ERROR("No authorization code provided"));
+        return;
+    }
+    if (!pending) {
+        if (reserved)
+            reserved.result = { code, ...(iss !== null ? { iss } : {}) };
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(HTML_MANUAL_SUCCESS);
+        return;
+    }
+    // Clear timeout and resolve the pending promise
+    clearTimeout(pending.timeout);
+    pendingAuths.delete(state);
+    pending.resolve({ code, ...(iss !== null ? { iss } : {}) });
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(HTML_SUCCESS);
+}
+/**
+ * Ensure the callback server is running.
+ * If strictPort is true, requires binding on the configured callback port.
+ * If strictPort is false, asks the OS for an available local port.
+ */
+export async function ensureCallbackServer(options = {}) {
+    if (stoppingPromise) {
+        throw new Error("OAuth callback server stopped");
+    }
+    const generation = callbackGeneration;
+    while (bindingPromise) {
+        await bindingPromise;
+        if (generation !== callbackGeneration) {
+            throw new Error("OAuth callback server stopped");
+        }
+    }
+    if (generation !== callbackGeneration) {
+        throw new Error("OAuth callback server stopped");
+    }
+    const operation = ensureCallbackServerLocked(options);
+    bindingPromise = operation;
+    try {
+        await operation;
+    }
+    finally {
+        if (bindingPromise === operation) {
+            bindingPromise = undefined;
+        }
+    }
+}
+async function ensureCallbackServerLocked(options = {}) {
+    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;
+    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.set(options.oauthState, { validate: options.validate });
+                reservedState = options.oauthState;
+            }
+            return;
+        }
+        if (pendingAuths.size > 0 || reservedAuthStates.size > 0) {
+            throw new Error(`OAuth callback server is running on ${callbackServerHost}:${getOAuthCallbackPort()}, but strict callback endpoint ${requestedHost}:${requiredPort} is required and cannot be switched while authorizations are pending`);
+        }
+    }
+    const candidateServer = createServer(handleRequest);
+    const listenPort = strictPort ? requiredPort : 0;
+    try {
+        await new Promise((resolve, reject) => {
+            candidateServer.once("error", (err) => {
+                reject(err);
+            });
+            candidateServer.listen(listenPort, requestedHost, () => {
+                resolve();
+            });
+        });
+        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((resolve) => {
+                previousServer.close(() => resolve());
+            });
+        }
+        callbackServerHost = requestedHost;
+        setOAuthCallbackPath(requestedPath);
+        server = candidateServer;
+        if (options.reserveState && options.oauthState) {
+            reservedAuthStates.set(options.oauthState, { validate: options.validate });
+            reservedState = options.oauthState;
+        }
+        server.unref();
+    }
+    catch (error) {
+        if (reservedState) {
+            reservedAuthStates.delete(reservedState);
+        }
+        const nodeError = error;
+        await new Promise((resolve) => {
+            candidateServer.close(() => resolve());
+        });
+        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 });
+        }
+        throw error;
+    }
+}
+export function releaseCallbackServer(oauthState) {
+    reservedAuthStates.delete(oauthState);
+}
+/** Consume a validated manual callback without releasing the flow's reservation. */
+export function takeCallbackResult(oauthState) {
+    const reserved = reservedAuthStates.get(oauthState);
+    const result = reserved?.result;
+    if (reserved)
+        delete reserved.result;
+    return result;
+}
+/**
+ * Wait for a callback with the given OAuth state.
+ * Returns a promise that resolves with the authorization code and, when the
+ * authorization server sends one, the RFC 9207 `iss` parameter.
+ */
+export function waitForCallback(oauthState) {
+    const reserved = reservedAuthStates.get(oauthState);
+    reservedAuthStates.delete(oauthState);
+    if (reserved?.result) {
+        return "error" in reserved.result
+            ? Promise.reject(new Error(reserved.result.error))
+            : Promise.resolve(reserved.result);
+    }
+    const validate = reserved?.validate;
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            if (pendingAuths.has(oauthState)) {
+                pendingAuths.delete(oauthState);
+                reject(new Error("OAuth callback timeout - authorization took too long"));
+            }
+        }, CALLBACK_TIMEOUT_MS);
+        pendingAuths.set(oauthState, { resolve, reject, timeout, ...(validate ? { validate } : {}) });
+    });
+}
+/**
+ * Cancel a pending authorization by state.
+ */
+export function cancelPendingCallback(oauthState) {
+    reservedAuthStates.delete(oauthState);
+    const pending = pendingAuths.get(oauthState);
+    if (pending) {
+        clearTimeout(pending.timeout);
+        pendingAuths.delete(oauthState);
+        pending.reject(new Error("Authorization cancelled"));
+    }
+}
+/**
+ * Stop the callback server and reject all pending authorizations.
+ */
+export function stopCallbackServer() {
+    if (stoppingPromise)
+        return stoppingPromise;
+    callbackGeneration += 1;
+    const cleanup = (async () => {
+        while (bindingPromise) {
+            await bindingPromise.catch(() => { });
+        }
+        if (server) {
+            await new Promise((resolve) => {
+                server.close(() => {
+                    resolve();
+                });
+            });
+            server = undefined;
+        }
+        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);
+                pending.reject(new Error("OAuth callback server stopped"));
+            }
+        }, 0);
+    })();
+    const operation = cleanup.finally(() => {
+        if (stoppingPromise === operation)
+            stoppingPromise = undefined;
+    });
+    stoppingPromise = operation;
+    return operation;
+}

package/dist/mcp-code.d.ts

@@ -0,0 +1,51 @@
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { McpExtensionState } from "./state.ts";
+import type { ContentBlock, McpOperationContext } from "./types.ts";
+export declare const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30000;
+export declare const runMcpScript: typeof runMcpScriptOperation;
+declare function runMcpScriptOperation(state: McpExtensionState, code: string, timeoutMs?: number | null, getPiTools?: () => ToolInfo[], signal?: AbortSignal, toolCallId?: string, beforeDispatch?: (signal: AbortSignal | undefined, operation: McpOperationContext) => Promise<void>): Promise<{
+    content: ContentBlock[];
+    details: {
+        calls?: ({
+            operation: "call";
+            path: string;
+            ok: true;
+            durationMs: number;
+        } | {
+            operation: "call";
+            path: string;
+            ok: false;
+            error: string;
+            durationMs: number;
+            recovery?: unknown;
+        } | {
+            operation: "search";
+            query: string;
+            ok: true;
+            durationMs: number;
+        } | {
+            operation: "search";
+            query: string;
+            ok: false;
+            error: string;
+            durationMs: number;
+        } | {
+            operation: "describe";
+            path: string;
+            ok: true;
+            durationMs: number;
+        } | {
+            operation: "describe";
+            path: string;
+            ok: false;
+            error: string;
+            durationMs: number;
+        })[];
+        recovery?: {} | null;
+        timeoutMs: number | null;
+        error?: "aborted" | "timeout" | "call_capture_failed" | "script_error";
+        message?: string | undefined;
+        mode: string;
+    };
+}>;
+export {};