npm - mcpcac - Versions diffs - 0.0.1 - Mend

mcpcac 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/dist/auth.d.ts +21 -0
package/dist/auth.d.ts.map +1 -0
package/dist/auth.js +122 -0
package/dist/index.d.ts +120 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +311 -0
package/dist/local-callback-server.d.ts +14 -0
package/dist/local-callback-server.d.ts.map +1 -0
package/dist/local-callback-server.js +162 -0
package/dist/oauth-provider.d.ts +63 -0
package/dist/oauth-provider.d.ts.map +1 -0
package/dist/oauth-provider.js +96 -0
package/dist/types.d.ts +77 -0
package/dist/types.d.ts.map +1 -0
package/dist/types.js +1 -0
package/package.json +42 -0
package/src/auth.ts +138 -0
package/src/index.ts +445 -0
package/src/local-callback-server.ts +185 -0
package/src/oauth-provider.ts +134 -0
package/src/types.ts +87 -0

package/dist/local-callback-server.js ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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);
+}

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,77 @@
+import type { OAuthTokens, OAuthClientInformation } from "@modelcontextprotocol/sdk/shared/auth.js";
+/**
+ * Persisted OAuth state for file-based storage
+ */
+export interface McpOAuthState {
+    tokens?: OAuthTokens;
+    clientInformation?: OAuthClientInformation;
+    codeVerifier?: string;
+    serverUrl?: string;
+}
+/**
+ * OAuth configuration for addMcpCommands
+ */
+export interface McpOAuthConfig {
+    /** Client name shown during OAuth consent screen */
+    clientName: string;
+    /**
+     * Load persisted OAuth state from storage (e.g., config file)
+     */
+    load: () => McpOAuthState | undefined;
+    /**
+     * Save OAuth state to storage. Called after successful auth or token refresh.
+     * Pass undefined to clear the state (logout).
+     */
+    save: (state: McpOAuthState | undefined) => void;
+    /**
+     * Called with the authorization URL. Default behavior opens the browser.
+     * Override to customize (e.g., just print the URL).
+     */
+    onAuthUrl?: (url: string) => void;
+    /**
+     * Called on successful authentication
+     */
+    onAuthSuccess?: () => void;
+    /**
+     * Called on authentication error
+     */
+    onAuthError?: (error: string) => void;
+}
+/**
+ * Result of startOAuthFlow
+ */
+export interface OAuthFlowResult {
+    success: boolean;
+    state?: McpOAuthState;
+    error?: string;
+}
+/**
+ * Options for starting OAuth flow
+ */
+export interface StartOAuthFlowOptions {
+    serverUrl: string;
+    clientName: string;
+    /** Existing OAuth state (for re-auth scenarios) */
+    existingState?: McpOAuthState;
+    /** Called with auth URL, default opens browser */
+    onAuthUrl?: (url: string) => void;
+    /** Timeout in ms waiting for callback, default 5 minutes */
+    timeout?: number;
+}
+/**
+ * Options for the local callback server
+ */
+export interface CallbackServerOptions {
+    /** Called when server starts with the redirect URI */
+    onReady?: (redirectUri: string) => void;
+    /** Timeout in ms, default 5 minutes */
+    timeout?: number;
+}
+/**
+ * Result from callback server
+ */
+export interface CallbackResult {
+    code: string;
+    state: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAEpG;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,IAAI,EAAE,MAAM,aAAa,GAAG,SAAS,CAAC;IAEtC;;;OAGG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,KAAK,IAAI,CAAC;IAEjD;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAElC;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAE3B;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,kDAAkD;IAClD,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/types.js ADDED Viewed

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

package/package.json ADDED Viewed

@@ -0,0 +1,42 @@
+{
+  "name": "mcpcac",
+  "version": "0.0.1",
+  "description": "Dynamically generate CLI commands from MCP server tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./src/index.js": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "mcp",
+    "cli",
+    "cac"
+  ],
+  "author": "Tommaso De Rossi, morse <beats.by.morse@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@xmorse/cac": "*"
+  },
+  "devDependencies": {
+    "@xmorse/cac": "^6.0.7"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w"
+  }
+}

package/src/auth.ts ADDED Viewed

@@ -0,0 +1,138 @@
+import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
+import { FileOAuthProvider } from "./oauth-provider.js";
+import { startCallbackServer } from "./local-callback-server.js";
+import type { McpOAuthState, OAuthFlowResult, StartOAuthFlowOptions } from "./types.js";
+/**
+ * Open a URL in the default browser.
+ * Uses platform-specific commands.
+ */
+async function openBrowser(url: string): Promise<void> {
+  const { exec } = await import("node:child_process");
+  const { promisify } = await import("node:util");
+  const execAsync = promisify(exec);
+  const platform = process.platform;
+  const command = (() => {
+    if (platform === "darwin") {
+      return `open "${url}"`;
+    }
+    if (platform === "win32") {
+      return `start "" "${url}"`;
+    }
+    // Linux and others
+    return `xdg-open "${url}"`;
+  })();
+  await execAsync(command);
+}
+/**
+ * Start the OAuth flow for an MCP server.
+ * This is an internal function - consumers should not call this directly.
+ * It is automatically triggered by addMcpCommands when a 401 error occurs.
+ *
+ * This function:
+ * 1. Starts a local callback server on a random port
+ * 2. Initiates OAuth with the MCP server
+ * 3. Opens the browser for user authorization
+ * 4. Waits for the callback with the authorization code
+ * 5. Exchanges the code for tokens
+ * 6. Returns the OAuth state for persistence
+ */
+export async function startOAuthFlow(options: StartOAuthFlowOptions): Promise<OAuthFlowResult> {
+  const { serverUrl, clientName, existingState, onAuthUrl, timeout } = options;
+  // Start local callback server on random port
+  const callbackServer = await startCallbackServer({ timeout });
+  const { redirectUri, waitForCallback, close } = callbackServer;
+  try {
+    // Create OAuth provider with the dynamic redirect URI
+    const oauthProvider = new FileOAuthProvider({
+      serverUrl,
+      redirectUri,
+      clientName,
+      tokens: existingState?.tokens,
+      clientInformation: existingState?.clientInformation,
+      codeVerifier: existingState?.codeVerifier,
+    });
+    // Start the OAuth flow - this will trigger dynamic client registration
+    // and set the authorization URL on the provider
+    const authResult = await auth(oauthProvider, { serverUrl });
+    if (authResult !== "REDIRECT") {
+      // Auth succeeded without redirect (had valid tokens)
+      close();
+      return {
+        success: true,
+        state: oauthProvider.getState(),
+      };
+    }
+    // Get the authorization URL
+    const authUrl = oauthProvider.redirectStartAuthUrl;
+    if (!authUrl) {
+      close();
+      return {
+        success: false,
+        error: "No authorization URL returned from OAuth flow",
+      };
+    }
+    // Open browser or call custom handler
+    const authUrlString = authUrl.toString();
+    if (onAuthUrl) {
+      onAuthUrl(authUrlString);
+    } else {
+      await openBrowser(authUrlString);
+    }
+    // Wait for the callback
+    const callback = await waitForCallback();
+    // Complete the OAuth flow by exchanging the code for tokens
+    const finalResult = await auth(oauthProvider, {
+      serverUrl,
+      authorizationCode: callback.code,
+    });
+    if (finalResult === "REDIRECT") {
+      return {
+        success: false,
+        error: "Unexpected redirect after code exchange",
+      };
+    }
+    return {
+      success: true,
+      state: oauthProvider.getState(),
+    };
+  } catch (err) {
+    close();
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+/**
+ * Check if an error indicates authentication is required.
+ * Internal function used by addMcpCommands.
+ */
+export function isAuthRequiredError(err: unknown): boolean {
+  if (!(err instanceof Error)) {
+    return false;
+  }
+  const message = err.message.toLowerCase();
+  return (
+    message.includes("401") ||
+    message.includes("unauthorized") ||
+    message.includes("authentication required") ||
+    message.includes("not authenticated") ||
+    message.includes("invalid_token") ||
+    message.includes("missing or invalid access token")
+  );
+}