@goke/mcp 0.0.4

package/dist/index.js

@@ -0,0 +1,324 @@
+/**
+ * # MCP to CLI
+ *
+ * Dynamically generates CLI commands from MCP (Model Context Protocol) server tools.
+ * This module connects to any MCP server, discovers available tools, and creates
+ * corresponding CLI commands with proper argument parsing and validation.
+ *
+ * ## Features
+ *
+ * - **Auto-discovery**: Fetches all tools from the MCP server and creates CLI commands
+ * - **Caching**: Tools are cached for 1 hour to avoid reconnecting on every invocation
+ * - **Session reuse**: MCP session IDs are cached to skip initialization handshake
+ * - **Type-aware parsing**: Handles string, number, boolean, object, and array arguments
+ * - **JSON schema support**: Generates CLI options from tool input schemas
+ * - **OAuth support**: Automatic OAuth authentication on 401 errors (lazy auth)
+ *
+ * ## Example Usage
+ *
+ * ```ts
+ * import { goke } from 'goke'
+ * import { addMcpCommands } from '@goke/mcp'
+ *
+ * const cli = goke('mycli')
+ *
+ * await addMcpCommands({
+ *   cli,
+ *   getMcpUrl: () => 'https://your-mcp-server.com/mcp',
+ *   oauth: {
+ *     clientName: 'My CLI',
+ *     load: () => loadConfig().oauthState,
+ *     save: (state) => saveConfig({ oauthState: state }),
+ *   },
+ *   loadCache: () => loadConfig().cache,
+ *   saveCache: (cache) => saveConfig({ cache }),
+ * })
+ *
+ * cli.parse()
+ * ```
+ *
+ * @module @goke/mcp
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { wrapJsonSchema } from "goke";
+import yaml from "js-yaml";
+import { FileOAuthProvider } from "./oauth-provider.js";
+import { startOAuthFlow, isAuthRequiredError } from "./auth.js";
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * Check if a schema represents a complex type (object/array) for help text display.
+ */
+function isComplexJsonSchema(schema) {
+    const type = schema.type;
+    if (type) {
+        const types = Array.isArray(type) ? type : [type];
+        if (types.some((t) => t === "object" || t === "array"))
+            return true;
+    }
+    if (schema.properties || schema.additionalProperties)
+        return true;
+    if (schema.items)
+        return true;
+    const unionTypes = [...(schema.anyOf || []), ...(schema.oneOf || []), ...(schema.allOf || [])];
+    return unionTypes.some((s) => isComplexJsonSchema(s));
+}
+/**
+ * Convert JSON schema to compact JSON string for display
+ */
+function schemaToString(schema) {
+    const compact = { ...schema };
+    delete compact.description;
+    return JSON.stringify(compact);
+}
+/**
+ * Extract tool arguments from CLI options.
+ * Goke now handles all type coercion via schemas, so this just picks
+ * the relevant keys from the parsed options.
+ */
+function extractToolArguments(options, inputSchema) {
+    const args = {};
+    if (!inputSchema?.properties) {
+        return args;
+    }
+    for (const name of Object.keys(inputSchema.properties)) {
+        const value = options[name];
+        if (value !== undefined) {
+            args[name] = value;
+        }
+    }
+    return args;
+}
+function outputResult(result) {
+    for (const block of result.content) {
+        if (block.type === "text" && block.text) {
+            // Try to parse as JSON and format as YAML for better readability
+            try {
+                const parsed = JSON.parse(block.text);
+                if (parsed) {
+                    console.log(yaml.dump(parsed, {
+                        indent: 2,
+                        lineWidth: 120,
+                        noRefs: true,
+                        sortKeys: false,
+                    }));
+                }
+                else {
+                    console.log(block.text);
+                }
+            }
+            catch {
+                // Not JSON, output as-is
+                console.log(block.text);
+            }
+        }
+        else if (block.type === "image") {
+            console.log("[Image content omitted]");
+        }
+        else {
+            console.log(JSON.stringify(block, null, 2));
+        }
+    }
+}
+/**
+ * Create a transport with optional OAuth authentication
+ */
+function createTransportWithAuth(url, sessionId, oauthState, oauth) {
+    let authProvider;
+    if (oauth && oauthState?.tokens) {
+        authProvider = new FileOAuthProvider({
+            serverUrl: url.toString(),
+            redirectUri: "http://localhost/callback", // Placeholder, real one set during auth flow
+            clientName: oauth.clientName,
+            tokens: oauthState.tokens,
+            clientInformation: oauthState.clientInformation,
+            codeVerifier: oauthState.codeVerifier,
+            onStateUpdated: (newState) => {
+                oauth.save(newState);
+            },
+        });
+    }
+    return new StreamableHTTPClientTransport(url, {
+        sessionId,
+        authProvider,
+    });
+}
+/**
+ * Adds MCP tool commands to a goke CLI instance.
+ *
+ * Tools are cached for 1 hour to avoid connecting on every CLI invocation.
+ * Session ID is also cached to skip MCP initialization handshake.
+ *
+ * OAuth is lazy - authentication only happens when a 401 error occurs.
+ * After successful auth, the operation is automatically retried.
+ */
+export async function addMcpCommands(options) {
+    const { cli, commandPrefix = "", clientName = "mcp-cli-client", getMcpUrl, getMcpTransport, oauth, loadCache, saveCache, } = options;
+    // Helper to get transport - supports both old and new API
+    const getTransport = async (sessionId) => {
+        // New API: getMcpUrl + oauth
+        if (getMcpUrl) {
+            const mcpUrl = getMcpUrl();
+            if (!mcpUrl) {
+                return null;
+            }
+            const url = new URL(mcpUrl);
+            const oauthState = oauth?.load();
+            return createTransportWithAuth(url, sessionId, oauthState, oauth);
+        }
+        // Legacy API: getMcpTransport
+        if (getMcpTransport) {
+            return getMcpTransport(sessionId);
+        }
+        return null;
+    };
+    // Handle auth required - triggers OAuth flow internally
+    const handleAuthRequired = async (serverUrl) => {
+        if (!oauth) {
+            console.error("Authentication required but OAuth not configured.");
+            console.error("Add oauth config to addMcpCommands() to enable automatic authentication.");
+            return false;
+        }
+        console.log("\n🔐 Authentication required. Opening browser...\n");
+        const result = await startOAuthFlow({
+            serverUrl,
+            clientName: oauth.clientName,
+            existingState: oauth.load(),
+            onAuthUrl: oauth.onAuthUrl,
+        });
+        if (result.success && result.state) {
+            oauth.save(result.state);
+            oauth.onAuthSuccess?.();
+            console.log("✓ Authentication successful! Retrying...\n");
+            return true;
+        }
+        oauth.onAuthError?.(result.error || "Unknown error");
+        console.error(`✗ Authentication failed: ${result.error}\n`);
+        return false;
+    };
+    // Try to use cached tools first (fast path - no network)
+    const cachedTools = loadCache();
+    const isCacheValid = cachedTools && (Date.now() - cachedTools.timestamp) < CACHE_TTL_MS;
+    let tools;
+    let cachedSessionId;
+    if (isCacheValid) {
+        tools = cachedTools.tools;
+        cachedSessionId = cachedTools.sessionId;
+    }
+    else {
+        // Cache invalid/missing - connect to fetch tools
+        const transport = await getTransport();
+        if (!transport) {
+            return;
+        }
+        const client = new Client({ name: clientName, version: "1.0.0" }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+            const result = await client.listTools();
+            tools = result.tools;
+            const sessionId = transport.sessionId;
+            saveCache({
+                tools: tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    inputSchema: t.inputSchema,
+                })),
+                timestamp: Date.now(),
+                sessionId,
+            });
+            cachedSessionId = sessionId;
+        }
+        catch (err) {
+            // Check if auth is required during tool discovery
+            if (isAuthRequiredError(err) && oauth && getMcpUrl) {
+                const mcpUrl = getMcpUrl();
+                if (mcpUrl) {
+                    const authSuccess = await handleAuthRequired((mcpUrl).toString());
+                    if (authSuccess) {
+                        // Retry after auth
+                        return addMcpCommands(options);
+                    }
+                }
+            }
+            console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
+            return;
+        }
+        finally {
+            await client.close();
+        }
+    }
+    // Register CLI commands for each tool
+    for (const tool of tools) {
+        const inputSchema = tool.inputSchema;
+        const cmdName = commandPrefix ? `${commandPrefix} ${tool.name}` : tool.name;
+        const description = tool.description || `Run MCP tool ${tool.name}`;
+        const cmd = cli.command(cmdName, description);
+        if (inputSchema?.properties) {
+            for (const [propName, propSchema] of Object.entries(inputSchema.properties)) {
+                const isRequired = inputSchema.required?.includes(propName) ?? false;
+                const schemaType = propSchema.type;
+                // Only treat as boolean flag if type is exclusively "boolean".
+                // Union types like ["boolean", "string"] should take a value.
+                const isBooleanType = schemaType === "boolean";
+                const optionStr = isBooleanType ? `--${propName}` : `--${propName} <${propName}>`;
+                let optionDesc = propSchema.description || propName;
+                if (isRequired) {
+                    optionDesc += " (required)";
+                }
+                if (isComplexJsonSchema(propSchema)) {
+                    optionDesc += ` (JSON: ${schemaToString(propSchema)})`;
+                }
+                if (isBooleanType && propSchema.default === undefined) {
+                    // Boolean flags without defaults don't need schema — mri handles them natively.
+                    cmd.option(optionStr, optionDesc);
+                }
+                else {
+                    // Wrap the MCP tool's JSON Schema property into a StandardJSONSchemaV1
+                    // object so Goke can use it for type coercion (string → typed value).
+                    // Put the enriched description into the JSON Schema so it's extracted automatically.
+                    // Boolean flags with defaults also go through this path to preserve the default.
+                    const enrichedSchema = { ...propSchema, description: optionDesc };
+                    cmd.option(optionStr, wrapJsonSchema(enrichedSchema));
+                }
+            }
+        }
+        cmd.action(async (cliOptions) => {
+            // Goke already coerced all values via schemas — just extract the relevant keys
+            const parsedArgs = extractToolArguments(cliOptions, inputSchema);
+            const executeWithRetry = async (isRetry = false) => {
+                const transport = await getTransport(isRetry ? undefined : cachedSessionId);
+                if (!transport) {
+                    console.error("MCP transport not available. Run login command first.");
+                    process.exit(1);
+                }
+                const actionClient = new Client({ name: clientName, version: "1.0.0" }, { capabilities: {} });
+                try {
+                    await actionClient.connect(transport);
+                    const result = await actionClient.callTool({ name: tool.name, arguments: parsedArgs });
+                    outputResult(result);
+                }
+                catch (err) {
+                    // On 401, trigger OAuth and retry (only once)
+                    if (!isRetry && isAuthRequiredError(err) && oauth && getMcpUrl) {
+                        const mcpUrl = getMcpUrl();
+                        if (mcpUrl) {
+                            const authSuccess = await handleAuthRequired((mcpUrl).toString());
+                            if (authSuccess) {
+                                await actionClient.close();
+                                return executeWithRetry(true);
+                            }
+                        }
+                    }
+                    // Clear cache on error (might be stale)
+                    saveCache(undefined);
+                    console.error(`Error calling ${tool.name}:`, err instanceof Error ? err.message : err);
+                    process.exit(1);
+                }
+                finally {
+                    await actionClient.close();
+                }
+            };
+            await executeWithRetry();
+        });
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { CallbackResult, CallbackServerOptions } from "./types.js";
+/**
+ * Start a local HTTP server to receive OAuth callbacks.
+ * Uses a random available port to avoid conflicts.
+ *
+ * @returns Object with port, redirectUri, waitForCallback promise, and close function
+ */
+export declare function startCallbackServer(options?: CallbackServerOptions): Promise<{
+    port: number;
+    redirectUri: string;
+    waitForCallback: () => Promise<CallbackResult>;
+    close: () => void;
+}>;
+//# sourceMappingURL=local-callback-server.d.ts.map

package/dist/local-callback-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-callback-server.d.ts","sourceRoot":"","sources":["../src/local-callback-server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA2FxE;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC,CAgFD"}

package/dist/local-callback-server.js

@@ -0,0 +1,162 @@
+import http from "node:http";
+import net from "node:net";
+const DEFAULT_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+/**
+ * Find a random available port by letting the OS assign one.
+ */
+async function findAvailablePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.on("error", reject);
+        server.listen(0, () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close();
+                reject(new Error("Failed to get port from server"));
+                return;
+            }
+            const port = address.port;
+            server.close(() => {
+                resolve(port);
+            });
+        });
+    });
+}
+/**
+ * Generate HTML response for the callback page
+ */
+function generateCallbackHtml(success, message) {
+    const color = success ? "#22c55e" : "#ef4444";
+    const icon = success ? "✓" : "✗";
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${success ? "Authentication Successful" : "Authentication Failed"}</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      margin: 0;
+      background-color: #f5f5f5;
+    }
+    .container {
+      background: white;
+      padding: 3rem;
+      border-radius: 12px;
+      box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+      text-align: center;
+      max-width: 400px;
+    }
+    .icon {
+      font-size: 4rem;
+      color: ${color};
+      margin-bottom: 1rem;
+    }
+    h1 {
+      color: #1f2937;
+      margin-bottom: 0.5rem;
+    }
+    p {
+      color: #6b7280;
+      margin-bottom: 1.5rem;
+    }
+    .hint {
+      font-size: 0.875rem;
+      color: #9ca3af;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="icon">${icon}</div>
+    <h1>${success ? "Authentication Successful" : "Authentication Failed"}</h1>
+    <p>${message}</p>
+    <p class="hint">You can close this window and return to your terminal.</p>
+  </div>
+  <script>
+    // Try to close the window after a short delay
+    setTimeout(() => { window.close(); }, 2000);
+  </script>
+</body>
+</html>`;
+}
+/**
+ * Start a local HTTP server to receive OAuth callbacks.
+ * Uses a random available port to avoid conflicts.
+ *
+ * @returns Object with port, redirectUri, waitForCallback promise, and close function
+ */
+export async function startCallbackServer(options = {}) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const port = await findAvailablePort();
+    const redirectUri = `http://localhost:${port}/callback`;
+    let resolveCallback;
+    let rejectCallback;
+    let timeoutId;
+    const callbackPromise = new Promise((resolve, reject) => {
+        resolveCallback = resolve;
+        rejectCallback = reject;
+    });
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url || "/", `http://localhost:${port}`);
+        // Only handle the callback path
+        if (url.pathname !== "/callback") {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not Found");
+            return;
+        }
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const error = url.searchParams.get("error");
+        const errorDescription = url.searchParams.get("error_description");
+        if (error) {
+            const message = errorDescription || error;
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(generateCallbackHtml(false, message));
+            rejectCallback?.(new Error(`OAuth error: ${message}`));
+            return;
+        }
+        if (!code) {
+            res.writeHead(400, { "Content-Type": "text/html" });
+            res.end(generateCallbackHtml(false, "Missing authorization code"));
+            rejectCallback?.(new Error("Missing authorization code"));
+            return;
+        }
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(generateCallbackHtml(true, "You have been authenticated successfully."));
+        resolveCallback?.({ code, state: state || "" });
+    });
+    server.listen(port, () => {
+        options.onReady?.(redirectUri);
+    });
+    // Set up timeout
+    timeoutId = setTimeout(() => {
+        rejectCallback?.(new Error(`OAuth callback timed out after ${timeout / 1000} seconds`));
+        server.close();
+    }, timeout);
+    const close = () => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        server.close();
+    };
+    const waitForCallback = async () => {
+        try {
+            return await callbackPromise;
+        }
+        finally {
+            close();
+        }
+    };
+    return {
+        port,
+        redirectUri,
+        waitForCallback,
+        close,
+    };
+}

package/dist/oauth-provider.d.ts

@@ -0,0 +1,63 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformation, OAuthClientInformationFull, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { McpOAuthState } from "./types.js";
+export interface FileOAuthProviderOptions {
+    serverUrl: string;
+    redirectUri: string;
+    clientName: string;
+    tokens?: OAuthTokens;
+    clientInformation?: OAuthClientInformation;
+    codeVerifier?: string;
+    /**
+     * Called when tokens are updated (initial save or refresh).
+     * Use this to persist the new state.
+     */
+    onStateUpdated?: (state: McpOAuthState) => void;
+}
+/**
+ * File-based OAuth provider implementation for CLI usage.
+ * Implements the OAuthClientProvider interface from MCP SDK.
+ *
+ * Unlike server-based implementations that use a database,
+ * this stores state in memory and calls onStateUpdated for persistence.
+ */
+export declare class FileOAuthProvider implements OAuthClientProvider {
+    private _clientInformation;
+    private _codeVerifier;
+    private _tokens;
+    private _redirectStartAuthUrl;
+    private readonly serverUrl;
+    private readonly redirectUri;
+    private readonly clientName;
+    private readonly onStateUpdated?;
+    constructor(options: FileOAuthProviderOptions);
+    get redirectUrl(): string;
+    /**
+     * The authorization URL to redirect the user to.
+     * Set by redirectToAuthorization().
+     */
+    get redirectStartAuthUrl(): URL | undefined;
+    clientInformation(): Promise<OAuthClientInformation | undefined>;
+    saveClientInformation(clientInformation: OAuthClientInformationFull): Promise<void>;
+    codeVerifier(): Promise<string>;
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    get clientMetadata(): OAuthClientMetadata;
+    /**
+     * Called by the MCP SDK when the user needs to be redirected to authorize.
+     * We store the URL so the CLI can open it in the browser.
+     */
+    redirectToAuthorization(authorizationUrl: URL): void;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    /**
+     * Get the current state for persistence
+     */
+    getState(): McpOAuthState;
+    private notifyStateUpdated;
+}
+/**
+ * Create a FileOAuthProvider for use with MCP transports.
+ * This is the simpler factory function for common use cases.
+ */
+export declare function createFileOAuthProvider(options: FileOAuthProviderOptions): FileOAuthProvider;
+//# sourceMappingURL=oauth-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider.d.ts","sourceRoot":"","sources":["../src/oauth-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,KAAK,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,EACnB,WAAW,EACZ,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CACjD;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,mBAAmB;IAC3D,OAAO,CAAC,kBAAkB,CAAqC;IAC/D,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,qBAAqB,CAAkB;IAE/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiC;gBAErD,OAAO,EAAE,wBAAwB;IAU7C,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACH,IAAI,oBAAoB,IAAI,GAAG,GAAG,SAAS,CAE1C;IAEK,iBAAiB,IAAI,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IAIhE,qBAAqB,CAAC,iBAAiB,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnF,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAO/B,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3D,IAAI,cAAc,IAAI,mBAAmB,CAKxC;IAED;;;OAGG;IACH,uBAAuB,CAAC,gBAAgB,EAAE,GAAG,GAAG,IAAI;IAI9C,MAAM,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAI1C,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD;;OAEG;IACH,QAAQ,IAAI,aAAa;IASzB,OAAO,CAAC,kBAAkB;CAK3B;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAE5F"}

package/dist/oauth-provider.js

@@ -0,0 +1,96 @@
+/**
+ * File-based OAuth provider implementation for CLI usage.
+ * Implements the OAuthClientProvider interface from MCP SDK.
+ *
+ * Unlike server-based implementations that use a database,
+ * this stores state in memory and calls onStateUpdated for persistence.
+ */
+export class FileOAuthProvider {
+    _clientInformation;
+    _codeVerifier;
+    _tokens;
+    _redirectStartAuthUrl;
+    serverUrl;
+    redirectUri;
+    clientName;
+    onStateUpdated;
+    constructor(options) {
+        this.serverUrl = options.serverUrl;
+        this.redirectUri = options.redirectUri;
+        this.clientName = options.clientName;
+        this._tokens = options.tokens;
+        this._clientInformation = options.clientInformation;
+        this._codeVerifier = options.codeVerifier;
+        this.onStateUpdated = options.onStateUpdated;
+    }
+    get redirectUrl() {
+        return this.redirectUri;
+    }
+    /**
+     * The authorization URL to redirect the user to.
+     * Set by redirectToAuthorization().
+     */
+    get redirectStartAuthUrl() {
+        return this._redirectStartAuthUrl;
+    }
+    async clientInformation() {
+        return this._clientInformation;
+    }
+    async saveClientInformation(clientInformation) {
+        this._clientInformation = clientInformation;
+        this.notifyStateUpdated();
+    }
+    async codeVerifier() {
+        if (!this._codeVerifier) {
+            throw new Error("Code verifier not set");
+        }
+        return this._codeVerifier;
+    }
+    async saveCodeVerifier(codeVerifier) {
+        this._codeVerifier = codeVerifier;
+        this.notifyStateUpdated();
+    }
+    get clientMetadata() {
+        return {
+            redirect_uris: [this.redirectUri],
+            client_name: this.clientName,
+        };
+    }
+    /**
+     * Called by the MCP SDK when the user needs to be redirected to authorize.
+     * We store the URL so the CLI can open it in the browser.
+     */
+    redirectToAuthorization(authorizationUrl) {
+        this._redirectStartAuthUrl = authorizationUrl;
+    }
+    async tokens() {
+        return this._tokens;
+    }
+    async saveTokens(tokens) {
+        this._tokens = tokens;
+        this.notifyStateUpdated();
+    }
+    /**
+     * Get the current state for persistence
+     */
+    getState() {
+        return {
+            tokens: this._tokens,
+            clientInformation: this._clientInformation,
+            codeVerifier: this._codeVerifier,
+            serverUrl: this.serverUrl,
+        };
+    }
+    notifyStateUpdated() {
+        if (this.onStateUpdated) {
+            this.onStateUpdated(this.getState());
+        }
+    }
+}
+/**
+ * Create a FileOAuthProvider for use with MCP transports.
+ * This is the simpler factory function for common use cases.
+ */
+export function createFileOAuthProvider(options) {
+    return new FileOAuthProvider(options);
+}