@goke/mcp 0.0.4

package/README.md

@@ -0,0 +1,217 @@
+# @goke/mcp
+
+Turn any [MCP](https://modelcontextprotocol.io) server into a CLI. Connects to the server, discovers tools, and generates CLI commands with typed arguments — automatically.
+
+## Install
+
+```bash
+npm install @goke/mcp goke
+```
+
+`goke` is a peer dependency (the CLI framework that commands are registered on).
+
+## How it works
+
+```
+MCP server                        Your CLI
+┌──────────────────┐              ┌──────────────────────────┐
+│  tools/list      │──discover──▸ │  mycli notion-search     │
+│  - notion-search │              │  mycli notion-get-page   │
+│  - notion-get-…  │              │  mycli notion-create-…   │
+│  (JSON Schema)   │──coerce───▸ │  --query <string>        │
+│                  │              │  --pageId <string>       │
+└──────────────────┘              └──────────────────────────┘
+```
+
+1. **Discover** — calls `tools/list` on the MCP server to get every tool + its JSON Schema
+2. **Register** — creates a CLI command per tool with `--options` derived from the schema
+3. **Cache** — tools and session ID are cached for 1 hour (no network on subsequent runs)
+4. **Execute** — on invocation, connects to the server and calls the tool with coerced arguments
+5. **OAuth** — if the server returns 401, automatically opens the browser for OAuth, then retries
+
+## Quick start
+
+```ts
+import { goke } from 'goke'
+import { addMcpCommands } from '@goke/mcp'
+import type { McpOAuthState, CachedMcpTools } from '@goke/mcp'
+
+const cli = goke('notion-mcp-cli')
+
+await addMcpCommands({
+  cli,
+  getMcpUrl: () => 'https://mcp.notion.com/mcp',
+  oauth: {
+    clientName: 'Notion CLI',
+    load: () => loadConfig().oauthState,
+    save: (state) => saveConfig({ oauthState: state }),
+  },
+  loadCache: () => loadConfig().cache,
+  saveCache: (cache) => saveConfig({ cache }),
+})
+
+cli.help()
+cli.parse()
+```
+
+That's it. Every tool the MCP server exposes becomes a CLI command:
+
+```bash
+notion-mcp-cli notion-search --query "meeting notes"
+notion-mcp-cli notion-retrieve-page --page_id "abc123"
+notion-mcp-cli notion-list-users
+```
+
+## Full example (with config persistence)
+
+This is the pattern used by [notion-mcp-cli](../notion-mcp-cli):
+
+```ts
+import { goke } from 'goke'
+import { addMcpCommands } from '@goke/mcp'
+import type { McpOAuthState, CachedMcpTools } from '@goke/mcp'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+// --- Config persistence (JSON file in ~/.myapp/) ---
+
+const CONFIG_DIR = path.join(os.homedir(), '.myapp')
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json')
+
+interface AppConfig {
+  mcpUrl: string
+  oauthState?: McpOAuthState
+  cache?: CachedMcpTools
+}
+
+function loadConfig(): AppConfig {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'))
+  } catch {
+    return { mcpUrl: 'https://mcp.notion.com/mcp' }
+  }
+}
+
+function saveConfig(partial: Partial<AppConfig>): void {
+  const merged = { ...loadConfig(), ...partial }
+  fs.mkdirSync(CONFIG_DIR, { recursive: true })
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2))
+}
+
+// --- CLI setup ---
+
+const cli = goke('myapp')
+
+await addMcpCommands({
+  cli,
+  clientName: 'myapp',
+  getMcpUrl: () => loadConfig().mcpUrl,
+  oauth: {
+    clientName: 'My App',
+    load: () => loadConfig().oauthState,
+    save: (state) => saveConfig({ oauthState: state }),
+  },
+  loadCache: () => loadConfig().cache,
+  saveCache: (cache) => saveConfig({ cache }),
+})
+
+// Custom commands alongside auto-generated MCP commands
+cli
+  .command('login', 'Save MCP URL')
+  .option('--url <url>', 'MCP server URL')
+  .action((options) => {
+    saveConfig({ mcpUrl: options.url })
+    console.log(`Saved: ${options.url}`)
+  })
+
+cli.command('logout', 'Clear tokens').action(() => {
+  saveConfig({ oauthState: undefined, cache: undefined })
+  console.log('Logged out')
+})
+
+cli.help()
+cli.parse()
+```
+
+## API
+
+### `addMcpCommands(options)`
+
+Registers MCP tool commands on a goke CLI instance.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cli` | `Goke` | **required** | The goke CLI instance to add commands to |
+| `getMcpUrl` | `() => string \| undefined` | — | Returns the MCP server URL |
+| `commandPrefix` | `string` | `''` | Prefix for commands (e.g. `'mcp'` makes `mcp notion-search`) |
+| `clientName` | `string` | `'mcp-cli-client'` | Name sent to the MCP server during connection |
+| `oauth` | `McpOAuthConfig` | — | OAuth config for servers that require authentication |
+| `loadCache` | `() => CachedMcpTools \| undefined` | **required** | Load cached tools from storage |
+| `saveCache` | `(cache) => void` | **required** | Save cached tools to storage |
+
+### `McpOAuthConfig`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `clientName` | `string` | Name shown on the OAuth consent screen |
+| `load` | `() => McpOAuthState \| undefined` | Load persisted OAuth state |
+| `save` | `(state) => void` | Save OAuth state after auth or token refresh |
+| `onAuthUrl` | `(url: string) => void` | Custom handler for auth URL (default: opens browser) |
+| `onAuthSuccess` | `() => void` | Called after successful authentication |
+| `onAuthError` | `(error: string) => void` | Called on authentication failure |
+
+### Exports
+
+```ts
+// Main function
+export { addMcpCommands } from '@goke/mcp'
+
+// Types
+export type { AddMcpCommandsOptions } from '@goke/mcp'
+export type { CachedMcpTools } from '@goke/mcp'
+export type { McpOAuthConfig, McpOAuthState } from '@goke/mcp'
+```
+
+## OAuth flow
+
+OAuth is **lazy** — no auth check happens on startup. The flow is:
+
+```
+User runs command
+       │
+       ▼
+  Call MCP tool ───── success ──▸ Print result
+       │
+    401 error
+       │
+       ▼
+  Start local server (random port)
+       │
+       ▼
+  Open browser ──▸ User authorizes
+       │
+       ▼
+  Receive callback with auth code
+       │
+       ▼
+  Exchange code for tokens
+       │
+       ▼
+  Save tokens via oauth.save()
+       │
+       ▼
+  Retry the original tool call
+```
+
+Tokens are persisted via the `oauth.save()` callback you provide, so subsequent runs skip auth entirely.
+
+## Caching
+
+Tools and the MCP session ID are cached for **1 hour** to avoid connecting on every invocation. The cache is managed through the `loadCache`/`saveCache` callbacks — you control where it's stored (file, database, env, etc.).
+
+When the cache expires or a tool call fails, the cache is cleared and tools are re-fetched on the next run.
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+import type { OAuthFlowResult, StartOAuthFlowOptions } from "./types.js";
+/**
+ * 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 declare function startOAuthFlow(options: StartOAuthFlowOptions): Promise<OAuthFlowResult>;
+/**
+ * Check if an error indicates authentication is required.
+ * Internal function used by addMcpCommands.
+ */
+export declare function isAuthRequiredError(err: unknown): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAiB,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA0BxF;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4E7F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAazD"}

package/dist/auth.js

@@ -0,0 +1,122 @@
+import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
+import { FileOAuthProvider } from "./oauth-provider.js";
+import { startCallbackServer } from "./local-callback-server.js";
+/**
+ * Open a URL in the default browser.
+ * Uses platform-specific commands.
+ */
+async function openBrowser(url) {
+    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) {
+    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) {
+    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"));
+}

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * # 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 type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { Goke } from "goke";
+import type { McpOAuthConfig } from "./types.js";
+export type { Transport };
+export type { McpOAuthConfig, McpOAuthState } from "./types.js";
+export interface CachedMcpTools {
+    tools: Array<{
+        name: string;
+        description?: string;
+        inputSchema?: unknown;
+    }>;
+    timestamp: number;
+    sessionId?: string;
+}
+export interface AddMcpCommandsOptions {
+    cli: Goke;
+    /**
+     * Prefix for all MCP tool commands.
+     * Set to empty string '' for no prefix (e.g., 'notion-search' instead of 'mcp notion-search').
+     * @default ''
+     */
+    commandPrefix?: string;
+    /**
+     * Name used when connecting to the MCP server.
+     * @default 'mcp-cli-client'
+     */
+    clientName?: string;
+    /**
+     * Returns the MCP server URL, or undefined if not configured.
+     * Required when using the oauth option.
+     */
+    getMcpUrl?: () => string | undefined;
+    /**
+     * Returns a transport to connect to the MCP server, or null if not configured.
+     * If null is returned, no MCP tool commands will be registered.
+     * @param sessionId - Optional session ID from cache to reuse existing session
+     *
+     * @deprecated Use getMcpUrl + oauth instead for simpler setup
+     */
+    getMcpTransport?: (sessionId?: string) => Transport | null | Promise<Transport | null>;
+    /**
+     * OAuth configuration. When provided, enables automatic OAuth authentication.
+     *
+     * OAuth is lazy - no auth check happens on startup. Authentication is only
+     * triggered when a tool call returns 401. After successful auth, the tool
+     * call is automatically retried.
+     *
+     * The library handles everything internally:
+     * - Detecting 401 errors
+     * - Starting local callback server on random port
+     * - Opening browser for authorization
+     * - Exchanging code for tokens
+     * - Persisting tokens via save()
+     * - Retrying the failed tool call
+     */
+    oauth?: McpOAuthConfig;
+    /**
+     * Load cached MCP tools. Return undefined if no cache exists.
+     */
+    loadCache: () => CachedMcpTools | undefined;
+    /**
+     * Save cached MCP tools. Pass undefined to clear the cache.
+     */
+    saveCache: (cache: CachedMcpTools | undefined) => void;
+}
+/**
+ * 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 declare function addMcpCommands(options: AddMcpCommandsOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAKjC,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAGhE,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,IAAI,CAAC;IACV;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAErC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEvF;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAE5C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,CAAC;CACxD;AAmID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyMlF"}