@fitchmultz/pi-mcp-adapter 5.0.0

package/dist/lifecycle.d.ts

@@ -0,0 +1,40 @@
+import { type ServerDefinition } from "./types.ts";
+import type { McpServerManager } from "./server-manager.ts";
+import { hasPendingAuth } from "./mcp-auth-flow.ts";
+export type ReconnectCallback = (serverName: string) => void;
+export type ReconnectFailureCallback = (serverName: string, error: unknown) => void;
+export declare class McpLifecycleManager {
+    private readonly manager;
+    private readonly hasPendingAuthForServer;
+    private keepAliveServers;
+    private allServers;
+    private serverSettings;
+    private globalIdleTimeout;
+    private healthCheckInterval;
+    private onReconnect;
+    private onReconnectFailure;
+    private onIdleShutdown;
+    private activeHealthCheck;
+    private shutdownPromise;
+    private stopped;
+    private checkpointPauses;
+    hasActiveHealthCheck(): boolean;
+    /** Skip ticks, without cancelling accepted work or permanently closing the manager. */
+    pauseForCheckpoint(): () => void;
+    private healthSignal;
+    private removeHealthAbortListener;
+    constructor(manager: McpServerManager, hasPendingAuthForServer?: typeof hasPendingAuth);
+    setReconnectCallback(callback: ReconnectCallback): void;
+    setReconnectFailureCallback(callback: ReconnectFailureCallback): void;
+    markKeepAlive(name: string, definition: ServerDefinition): void;
+    registerServer(name: string, definition: ServerDefinition, settings?: {
+        idleTimeout?: number;
+    }): void;
+    setGlobalIdleTimeout(minutes: number): void;
+    setIdleShutdownCallback(callback: (serverName: string) => void): void;
+    startHealthChecks(signalOrInterval?: AbortSignal | number, maybeIntervalMs?: number): void;
+    private checkConnections;
+    private getIdleTimeout;
+    gracefulShutdown(): Promise<void>;
+    private shutdownOnce;
+}

package/dist/lifecycle.js

@@ -0,0 +1,167 @@
+import { isServerDisabled } from "./types.js";
+import { hasPendingAuth } from "./mcp-auth-flow.js";
+import { logger } from "./logger.js";
+import { formatTerminalError, sanitizeTerminalText } from "./utils.js";
+export class McpLifecycleManager {
+    manager;
+    hasPendingAuthForServer;
+    keepAliveServers = new Map();
+    allServers = new Map();
+    serverSettings = new Map();
+    globalIdleTimeout = 10 * 60 * 1000;
+    healthCheckInterval;
+    onReconnect;
+    onReconnectFailure;
+    onIdleShutdown;
+    activeHealthCheck;
+    shutdownPromise;
+    stopped = false;
+    checkpointPauses = 0;
+    hasActiveHealthCheck() { return this.activeHealthCheck !== undefined; }
+    /** Skip ticks, without cancelling accepted work or permanently closing the manager. */
+    pauseForCheckpoint() {
+        this.checkpointPauses++;
+        let released = false;
+        return () => {
+            if (!released) {
+                released = true;
+                this.checkpointPauses--;
+            }
+        };
+    }
+    healthSignal;
+    removeHealthAbortListener;
+    constructor(manager, hasPendingAuthForServer = hasPendingAuth) {
+        this.manager = manager;
+        this.hasPendingAuthForServer = hasPendingAuthForServer;
+    }
+    setReconnectCallback(callback) {
+        this.onReconnect = callback;
+    }
+    setReconnectFailureCallback(callback) {
+        this.onReconnectFailure = callback;
+    }
+    markKeepAlive(name, definition) {
+        if (isServerDisabled(definition))
+            return;
+        this.keepAliveServers.set(name, definition);
+    }
+    registerServer(name, definition, settings) {
+        if (isServerDisabled(definition))
+            return;
+        this.allServers.set(name, definition);
+        if (settings?.idleTimeout !== undefined)
+            this.serverSettings.set(name, settings);
+    }
+    setGlobalIdleTimeout(minutes) {
+        this.globalIdleTimeout = minutes * 60 * 1000;
+    }
+    setIdleShutdownCallback(callback) {
+        this.onIdleShutdown = callback;
+    }
+    startHealthChecks(signalOrInterval, maybeIntervalMs = 30000) {
+        const signal = typeof signalOrInterval === "number" ? undefined : signalOrInterval;
+        const intervalMs = typeof signalOrInterval === "number" ? signalOrInterval : maybeIntervalMs;
+        if (this.healthCheckInterval)
+            clearInterval(this.healthCheckInterval);
+        this.removeHealthAbortListener?.();
+        this.stopped = false;
+        this.healthSignal = signal;
+        if (signal?.aborted) {
+            this.stopped = true;
+            this.healthSignal = undefined;
+            return;
+        }
+        const stop = () => {
+            this.stopped = true;
+            if (this.healthCheckInterval)
+                clearInterval(this.healthCheckInterval);
+            this.healthCheckInterval = undefined;
+        };
+        signal?.addEventListener("abort", stop, { once: true });
+        this.removeHealthAbortListener = () => signal?.removeEventListener("abort", stop);
+        this.healthCheckInterval = setInterval(() => {
+            if (this.stopped || signal?.aborted || this.activeHealthCheck || this.checkpointPauses > 0)
+                return;
+            const check = this.checkConnections(signal)
+                .catch(error => {
+                console.error(`MCP: Health check failed: ${formatTerminalError(error)}`);
+            })
+                .finally(() => {
+                if (this.activeHealthCheck === check)
+                    this.activeHealthCheck = undefined;
+            });
+            this.activeHealthCheck = check;
+        }, intervalMs);
+        this.healthCheckInterval.unref();
+    }
+    async checkConnections(signal) {
+        if (this.stopped || signal?.aborted)
+            return;
+        for (const [name, definition] of this.keepAliveServers) {
+            if (isServerDisabled(definition))
+                continue;
+            const connection = this.manager.getConnection(name);
+            if (!connection || connection.status !== "connected") {
+                if (this.hasPendingAuthForServer(name)) {
+                    logger.debug(`Skipping reconnect for ${name} while OAuth authorization is pending`);
+                    continue;
+                }
+                try {
+                    await this.manager.connect(name, definition, signal);
+                    if (this.stopped || signal?.aborted)
+                        return;
+                    logger.debug(`Reconnected to ${name}`);
+                    this.onReconnect?.(name);
+                }
+                catch (error) {
+                    if (this.stopped || signal?.aborted)
+                        return;
+                    this.onReconnectFailure?.(name, error);
+                    const message = error instanceof Error ? error.message : String(error);
+                    console.error(`MCP: Failed to reconnect to ${name}: ${sanitizeTerminalText(message)}`);
+                }
+            }
+        }
+        for (const [name] of this.allServers) {
+            if (this.keepAliveServers.has(name))
+                continue;
+            const timeout = this.getIdleTimeout(name);
+            if (timeout > 0 && this.manager.isIdle(name, timeout)) {
+                await this.manager.close(name);
+                if (this.stopped || signal?.aborted)
+                    return;
+                this.onIdleShutdown?.(name);
+            }
+        }
+    }
+    getIdleTimeout(name) {
+        const perServer = this.serverSettings.get(name)?.idleTimeout;
+        if (perServer !== undefined)
+            return perServer * 60 * 1000;
+        return this.globalIdleTimeout;
+    }
+    async gracefulShutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        this.shutdownPromise = this.shutdownOnce();
+        return this.shutdownPromise;
+    }
+    async shutdownOnce() {
+        this.stopped = true;
+        if (this.healthCheckInterval)
+            clearInterval(this.healthCheckInterval);
+        this.healthCheckInterval = undefined;
+        this.removeHealthAbortListener?.();
+        this.removeHealthAbortListener = undefined;
+        this.healthSignal = undefined;
+        await this.activeHealthCheck;
+        this.activeHealthCheck = undefined;
+        this.onReconnect = undefined;
+        this.onReconnectFailure = undefined;
+        this.onIdleShutdown = undefined;
+        if (typeof this.manager.closeAll === "function") {
+            await this.manager.closeAll();
+        }
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Centralized logging for MCP UI operations.
+ * Provides structured, contextual logs with levels.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogContext {
+    server?: string;
+    session?: string;
+    tool?: string;
+    uri?: string;
+    [key: string]: unknown;
+}
+declare class Logger {
+    private minLevel;
+    setLevel(level: LogLevel): void;
+    private shouldLog;
+    private emit;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, error?: Error, context?: LogContext): void;
+    /**
+     * Create a child logger with additional default context.
+     */
+    child(context: LogContext): ChildLogger;
+}
+declare class ChildLogger {
+    private parent;
+    private context;
+    constructor(parent: Logger, context: LogContext);
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, error?: Error, context?: LogContext): void;
+    child(context: LogContext): ChildLogger;
+}
+export declare const logger: Logger;
+export {};

package/dist/logger.js

@@ -0,0 +1,102 @@
+/**
+ * Centralized logging for MCP UI operations.
+ * Provides structured, contextual logs with levels.
+ */
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const LEVEL_PREFIX = {
+    debug: "[MCP-UI:DEBUG]",
+    info: "[MCP-UI]",
+    warn: "[MCP-UI:WARN]",
+    error: "[MCP-UI:ERROR]",
+};
+class Logger {
+    minLevel = "info";
+    setLevel(level) {
+        this.minLevel = level;
+    }
+    shouldLog(level) {
+        return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.minLevel];
+    }
+    emit(level, message, context, error) {
+        if (!this.shouldLog(level))
+            return;
+        const prefix = LEVEL_PREFIX[level];
+        const contextStr = formatContext(context);
+        const fullMessage = contextStr ? `${prefix} ${message} ${contextStr}` : `${prefix} ${message}`;
+        if (level === "error") {
+            console.error(fullMessage, error ?? "");
+        }
+        else if (level === "warn") {
+            console.warn(fullMessage);
+        }
+        else if (level === "debug") {
+            console.debug(fullMessage);
+        }
+        else {
+            console.log(fullMessage);
+        }
+    }
+    debug(message, context) {
+        this.emit("debug", message, context);
+    }
+    info(message, context) {
+        this.emit("info", message, context);
+    }
+    warn(message, context) {
+        this.emit("warn", message, context);
+    }
+    error(message, error, context) {
+        this.emit("error", message, context, error);
+    }
+    /**
+     * Create a child logger with additional default context.
+     */
+    child(context) {
+        return new ChildLogger(this, context);
+    }
+}
+class ChildLogger {
+    parent;
+    context;
+    constructor(parent, context) {
+        this.parent = parent;
+        this.context = context;
+    }
+    debug(message, context) {
+        this.parent.debug(message, { ...this.context, ...context });
+    }
+    info(message, context) {
+        this.parent.info(message, { ...this.context, ...context });
+    }
+    warn(message, context) {
+        this.parent.warn(message, { ...this.context, ...context });
+    }
+    error(message, error, context) {
+        this.parent.error(message, error, { ...this.context, ...context });
+    }
+    child(context) {
+        return new ChildLogger(this.parent, { ...this.context, ...context });
+    }
+}
+function formatContext(context) {
+    if (!context || Object.keys(context).length === 0)
+        return "";
+    const parts = [];
+    for (const [key, value] of Object.entries(context)) {
+        if (value !== undefined && value !== null) {
+            parts.push(`${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+        }
+    }
+    return parts.length > 0 ? `(${parts.join(", ")})` : "";
+}
+// Singleton instance
+export const logger = new Logger();
+// Enable debug mode via environment variable
+if (process.env.MCP_UI_DEBUG === "1" || process.env.MCP_UI_DEBUG === "true") {
+    logger.setLevel("debug");
+}

package/dist/mcp-auth-flow.d.ts

@@ -0,0 +1,113 @@
+/**
+ * MCP Auth Flow
+ *
+ * High-level OAuth flow management using the MCP SDK's built-in auth functions.
+ */
+import { UnauthorizedError, InsufficientScopeError, SdkHttpError } from "@modelcontextprotocol/client";
+import { type McpOAuthConfig } from "./mcp-oauth-provider.ts";
+import { type AuthStorageOptions } from "./mcp-auth.ts";
+import { type ServerEntry } from "./types.ts";
+/** Auth status for a server */
+export type AuthStatus = "authenticated" | "expired" | "not_authenticated";
+import type { McpCheckpointEvent } from "./checkpoint.ts";
+export interface McpOAuthRuntime {
+    readonly signal: AbortSignal;
+}
+export interface AuthenticateOptions {
+    onAuthorizationUrl?: (authorizationUrl: string) => void | Promise<void>;
+    authStorageOptions?: AuthStorageOptions;
+    signal?: AbortSignal;
+    runtime?: McpOAuthRuntime;
+}
+export declare function createOAuthRuntime(signal?: AbortSignal): McpOAuthRuntime;
+export declare function holdOAuthCheckpoint(runtime: McpOAuthRuntime, event: McpCheckpointEvent): () => void;
+export declare function getOAuthCheckpointBlocker(runtime: McpOAuthRuntime): string | undefined;
+type OAuthRequest = {
+    serverName: string;
+    serverUrl: string;
+    requestedScope?: string;
+    challenge?: {
+        requiredScope?: string;
+        resourceMetadataUrl?: URL;
+    };
+    issuer?: string;
+};
+export declare function isOAuthChallenge(error: unknown): error is InsufficientScopeError | UnauthorizedError | SdkHttpError;
+export declare function getOAuthRequest(serverName: string, serverUrl: string, storageBase: string, runtime?: McpOAuthRuntime): OAuthRequest | undefined;
+/** Observe native challenges only; no credential reads or auth work here. */
+export declare function recordOAuthChallenge(serverName: string, serverUrl: string, storageBase: string, error: unknown, runtime?: McpOAuthRuntime): void;
+export declare function bindOAuthRequestIssuer(serverName: string, serverUrl: string, storageBase: string, issuer: string, runtime?: McpOAuthRuntime): void;
+export declare function hasPendingAuth(serverName: string, options?: AuthStorageOptions, runtime?: McpOAuthRuntime): boolean;
+/**
+ * Extract OAuth configuration from a ServerEntry.
+ */
+export declare function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig;
+/**
+ * Start OAuth authentication flow for a server.
+ * Returns the authorization URL when browser authorization is required.
+ */
+export declare const startAuth: typeof startAuthOperation;
+declare function startAuthOperation(serverName: string, serverUrl: string, definition?: ServerEntry, options?: AuthenticateOptions): Promise<{
+    authorizationUrl: string;
+}>;
+/** Authorization code plus the optional RFC 9207 `iss` callback parameter. */
+export interface AuthorizationCodeInput {
+    code: string;
+    iss?: string;
+}
+/**
+ * Extract an OAuth authorization code (and the RFC 9207 `iss` parameter, when
+ * present) from either a raw code, a query string, or the full localhost
+ * redirect URL copied from the browser address bar.
+ */
+type AuthorizationResponseInput = AuthorizationCodeInput | {
+    error: string;
+    errorDescription?: string;
+    iss?: string;
+    code?: never;
+};
+export declare function parseAuthorizationRedirectInput(input: string, expectedState?: string): AuthorizationResponseInput;
+/**
+ * Complete OAuth authentication from pasted input or a captured browser callback.
+ */
+export declare function completeAuthFromInput(serverName: string, input?: string, options?: AuthenticateOptions): Promise<AuthStatus>;
+/**
+ * Complete OAuth authentication with an explicit code or a captured callback.
+ */
+export declare const completeAuth: typeof completeAuthOperation;
+declare function completeAuthOperation(serverName: string, authorizationCode?: string | AuthorizationResponseInput, options?: AuthenticateOptions): Promise<AuthStatus>;
+/**
+ * Perform the complete OAuth authentication flow for a server.
+ *
+ * @param serverName - The name of the MCP server
+ * @param serverUrl - The URL of the MCP server
+ * @param definition - The server definition (optional)
+ * @returns The final auth status
+ */
+export declare function authenticate(serverName: string, serverUrl: string, definition?: ServerEntry, options?: AuthenticateOptions): Promise<AuthStatus>;
+/**
+ * Remove all OAuth credentials for a server.
+ *
+ * @param serverName - The name of the MCP server
+ */
+export declare const removeAuth: typeof removeAuthOperation;
+declare function removeAuthOperation(serverName: string, options?: AuthenticateOptions): Promise<void>;
+/**
+ * Check if OAuth is supported for a server configuration.
+ * OAuth is supported for HTTP servers unless explicitly disabled.
+ *
+ * @param definition - The server definition
+ * @returns True if OAuth is supported
+ */
+export declare function supportsOAuth(definition: ServerEntry): boolean;
+/**
+ * Initialize the OAuth system on startup.
+ * OAuth callback binding is lazy and starts from startAuth() only.
+ */
+export declare function initializeOAuth(runtimeOrSignal?: McpOAuthRuntime | AbortSignal): Promise<McpOAuthRuntime>;
+/**
+ * Shutdown one OAuth runtime. The callback server remains process-shared while
+ * another runtime has pending/reserved callback state or is still active.
+ */
+export declare function shutdownOAuth(runtime?: McpOAuthRuntime): Promise<void>;
+export {};