@goke/mcp 0.0.11 → 0.0.13

package/README.md

@@ -25,9 +25,9 @@ MCP server                        Your CLI
 
 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)
+3. **Cache** — tools and session ID are cached for 1 hour (no network on subsequent runs). Expired cache is still used when a live fetch is impossible (no token, 401 on `--help`)
 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
+5. **OAuth** — if the server returns 401, automatically opens the browser for OAuth, then retries. `--help`, `--version`, `completions`, and no-args never start OAuth
 
 ## Quick start
 
@@ -55,6 +55,24 @@ cli.completions()
 cli.parse()
 ```
 
+If the MCP server is HTTP, pass `getMcpUrl` even when the user has no token. `--help` and no-args must still run so the CLI can show `config` / login instructions. Use `getMcpTransport` when you need stdio or a custom transport.
+
+For an HTTP Bearer token, pass `getHeaders`:
+
+```ts
+await addMcpCommands({
+  cli,
+  getMcpUrl: () => 'https://api.example.com/mcp',
+  getHeaders: () => {
+    const token = process.env.EXAMPLE_TOKEN || loadConfig().token
+    if (!token) return
+    return { Authorization: `Bearer ${token}` }
+  },
+  loadCache: () => loadConfig().cache,
+  saveCache: (cache) => saveConfig({ cache }),
+})
+```
+
 That's it. Every tool the MCP server exposes becomes a CLI command:
 
 ```bash
@@ -467,7 +485,10 @@ 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 |
+| `getMcpUrl` | `() => string \| undefined` | — | Returns the MCP server URL. Return the URL even when the user is not logged in so `--help` still works |
+| `getMcpTransport` | `(sessionId?) => Transport \| null` | — | Custom transport. Use for stdio or anything `getMcpUrl` cannot express |
+| `getHeaders` | `() => Record<string, string> \| undefined` | — | Extra HTTP headers (for example `Authorization`). Used with `getMcpUrl` |
+| `argv` | `string[]` | `process.argv.slice(2)` | Args used to skip live discovery on help and already registered commands |
 | `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 |
@@ -537,6 +558,8 @@ Tools and the MCP session ID are cached for **1 hour** to avoid connecting on ev
 
 When the cache expires or a tool call fails, the cache is cleared and tools are re-fetched on the next run.
 
+If a live `tools/list` cannot run (no transport, 401 during `--help`), `addMcpCommands` still registers tools from an expired cache so help stays useful.
+
 ## License
 
 MIT

package/dist/__test__/add-mcp-commands-help.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=add-mcp-commands-help.test.d.ts.map

package/dist/__test__/add-mcp-commands-help.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-mcp-commands-help.test.d.ts","sourceRoot":"","sources":["../../src/__test__/add-mcp-commands-help.test.ts"],"names":[],"mappings":""}

package/dist/__test__/add-mcp-commands-help.test.js

@@ -0,0 +1,127 @@
+// First-run help and stale-cache behavior for addMcpCommands.
+import http from 'node:http';
+import { describe, expect, it } from 'vitest';
+import { goke } from 'goke';
+import { addMcpCommands } from '../index.js';
+const staleCache = (over = {}) => ({
+    tools: [
+        {
+            name: 'find_bookmarks',
+            description: 'Find bookmarks',
+            inputSchema: { type: 'object', properties: {} },
+        },
+    ],
+    timestamp: Date.now() - 2 * 60 * 60 * 1000,
+    sessionId: 'stale-session',
+    ...over,
+});
+function captureErrors() {
+    const errors = [];
+    const error = console.error;
+    console.error = (...args) => {
+        errors.push(args.map(String).join(' '));
+    };
+    return {
+        errors,
+        restore() {
+            console.error = error;
+        },
+    };
+}
+function listen401() {
+    const server = http.createServer((_req, res) => {
+        res.writeHead(401, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'unauthorized' }));
+    });
+    return new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            if (!addr || typeof addr === 'string')
+                throw new Error('no port');
+            resolve({
+                url: `http://127.0.0.1:${addr.port}/mcp`,
+                close: () => new Promise((done) => server.close(() => done())),
+            });
+        });
+    });
+}
+describe('addMcpCommands first-run help', () => {
+    it('lets --help run when there is no token and no cache', async () => {
+        const io = captureErrors();
+        const cli = goke('testcli');
+        cli.command('config', 'Save token').action(() => { });
+        try {
+            await addMcpCommands({
+                cli,
+                argv: ['--help'],
+                getMcpTransport: () => null,
+                loadCache: () => undefined,
+                saveCache: () => { },
+            });
+        }
+        finally {
+            io.restore();
+        }
+        const help = cli.helpText();
+        expect(io.errors.join('\n')).not.toMatch(/Failed to connect/);
+        expect(help).toMatch(/config/);
+        expect(help).not.toMatch(/find_bookmarks/);
+    });
+    it('registers stale cached tools when live fetch is impossible', async () => {
+        const cli = goke('testcli');
+        await addMcpCommands({
+            cli,
+            argv: ['--help'],
+            getMcpTransport: () => null,
+            loadCache: () => staleCache(),
+            saveCache: () => { },
+        });
+        expect(cli.helpText()).toMatch(/find_bookmarks/);
+    });
+    it('does not start OAuth when --help gets a 401', async () => {
+        const server = await listen401();
+        const authUrls = [];
+        const io = captureErrors();
+        const cli = goke('testcli');
+        try {
+            await addMcpCommands({
+                cli,
+                argv: ['--help'],
+                getMcpUrl: () => server.url,
+                oauth: {
+                    clientName: 'test',
+                    load: () => undefined,
+                    save: () => { },
+                    onAuthUrl: (url) => {
+                        authUrls.push(url);
+                    },
+                },
+                loadCache: () => undefined,
+                saveCache: () => { },
+            });
+        }
+        finally {
+            io.restore();
+            await server.close();
+        }
+        expect(authUrls).toEqual([]);
+        expect(io.errors.join('\n')).not.toMatch(/Authentication required/);
+        expect(cli.helpText()).toMatch(/Usage/);
+    });
+    it('does not connect for an already registered command', async () => {
+        let transportCalls = 0;
+        const cli = goke('testcli');
+        cli.command('config', 'Save token').action(() => { });
+        await addMcpCommands({
+            cli,
+            argv: ['config', '--token', 'x'],
+            getMcpTransport: () => {
+                transportCalls += 1;
+                return null;
+            },
+            loadCache: () => undefined,
+            saveCache: () => { },
+        });
+        expect(transportCalls).toBe(0);
+    });
+});

package/dist/auth.d.ts

@@ -1,10 +1,8 @@
 import type { OAuthFlowResult, StartOAuthFlowOptions } from "./types.js";
 /**
  * Start the OAuth flow for an MCP server.
- *
- * Used internally by addMcpCommands on 401 errors, but also available
- * for CLIs that need explicit control over the auth flow (e.g. a login
- * command that runs the flow in a background daemon).
+ * 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

package/dist/auth.d.ts.map

@@ -1 +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;;;;;;;;;;;;;;GAcG;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"}
+{"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

@@ -24,10 +24,8 @@ async function openBrowser(url) {
 }
 /**
  * Start the OAuth flow for an MCP server.
- *
- * Used internally by addMcpCommands on 401 errors, but also available
- * for CLIs that need explicit control over the auth flow (e.g. a login
- * command that runs the flow in a background daemon).
+ * 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

package/dist/index.d.ts

@@ -41,12 +41,11 @@
  */
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { Goke } from "goke";
-export { startOAuthFlow } from "./auth.js";
 import type { McpOAuthConfig } from "./types.js";
 export { addCliToolsToMcp, createMcpAction } from "./cli-to-mcp.js";
 export type { AddCliToolsToMcpOptions, CreateMcpActionOptions } from "./cli-to-mcp.js";
 export type { Transport };
-export type { McpOAuthConfig, McpOAuthState, StartOAuthFlowOptions, OAuthFlowResult } from "./types.js";
+export type { McpOAuthConfig, McpOAuthState } from "./types.js";
 export interface CachedMcpTools {
     tools: Array<{
         name: string;
@@ -76,12 +75,20 @@ export interface AddMcpCommandsOptions {
     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
+     * Use this for stdio servers or any setup `getMcpUrl` cannot express.
+     * @param sessionId - Optional session ID from a still-valid cache
      */
     getMcpTransport?: (sessionId?: string) => Transport | null | Promise<Transport | null>;
+    /**
+     * Argv used to decide whether to skip live discovery.
+     * Defaults to `process.argv.slice(2)`.
+     */
+    argv?: string[];
+    /**
+     * Extra headers for MCP HTTP requests (for example `Authorization`).
+     * Used with `getMcpUrl`. Ignored when `getMcpTransport` is set.
+     */
+    getHeaders?: () => Record<string, string> | undefined;
     /**
      * OAuth configuration. When provided, enables automatic OAuth authentication.
      *

package/dist/index.d.ts.map

@@ -1 +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,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGvF,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAExG,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"}
+{"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;AAChE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGvF,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;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEvF;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAEtD;;;;;;;;;;;;;;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;AA2JD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4NlF"}

package/dist/index.js

@@ -45,7 +45,6 @@ import { wrapJsonSchema } from "goke";
 import yaml from "js-yaml";
 import { FileOAuthProvider } from "./oauth-provider.js";
 import { startOAuthFlow, isAuthRequiredError } from "./auth.js";
-export { startOAuthFlow } from "./auth.js";
 export { addCliToolsToMcp, createMcpAction } from "./cli-to-mcp.js";
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 /**
@@ -125,7 +124,23 @@ function outputResult(result) {
 /**
  * Create a transport with optional OAuth authentication
  */
-function createTransportWithAuth(url, sessionId, oauthState, oauth) {
+function isHelpOrMetaArgv(argv) {
+    if (argv.length === 0)
+        return true;
+    if (argv[0] === "completions" || argv.includes("--get-goke-completions"))
+        return true;
+    return argv.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v");
+}
+function matchesRegisteredCommand({ argv, cli }) {
+    const parts = argv.filter((arg) => !arg.startsWith("-"));
+    return cli.commands.some((cmd) => {
+        if (!cmd.name)
+            return false;
+        const nameParts = cmd.name.split(" ");
+        return nameParts.every((part, i) => parts[i] === part);
+    });
+}
+function createTransportWithAuth({ url, sessionId, oauthState, oauth, headers, }) {
     let authProvider;
     if (oauth && oauthState?.tokens) {
         authProvider = new FileOAuthProvider({
@@ -140,9 +155,11 @@ function createTransportWithAuth(url, sessionId, oauthState, oauth) {
             },
         });
     }
+    const hasHeaders = headers && Object.keys(headers).length > 0;
     return new StreamableHTTPClientTransport(url, {
         sessionId,
         authProvider,
+        requestInit: hasHeaders ? { headers } : undefined,
     });
 }
 /**
@@ -155,7 +172,7 @@ function createTransportWithAuth(url, sessionId, oauthState, oauth) {
  * 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;
+    const { cli, commandPrefix = "", clientName = "mcp-cli-client", getMcpUrl, getMcpTransport, getHeaders, oauth, loadCache, saveCache, argv = process.argv.slice(2), } = options;
     // Helper to get transport - supports both old and new API
     const getTransport = async (sessionId) => {
         // New API: getMcpUrl + oauth
@@ -166,9 +183,15 @@ export async function addMcpCommands(options) {
             }
             const url = new URL(mcpUrl);
             const oauthState = oauth?.load();
-            return createTransportWithAuth(url, sessionId, oauthState, oauth);
+            return createTransportWithAuth({
+                url,
+                sessionId,
+                oauthState,
+                oauth,
+                headers: getHeaders?.(),
+            });
         }
-        // Legacy API: getMcpTransport
+        // Custom / stdio transport
         if (getMcpTransport) {
             return getMcpTransport(sessionId);
         }
@@ -201,54 +224,64 @@ export async function addMcpCommands(options) {
     // Try to use cached tools first (fast path - no network)
     const cachedTools = loadCache();
     const isCacheValid = cachedTools && (Date.now() - cachedTools.timestamp) < CACHE_TTL_MS;
+    const skipLiveDiscovery = isHelpOrMetaArgv(argv) || matchesRegisteredCommand({ argv, cli });
     let tools;
     let cachedSessionId;
-    if (isCacheValid) {
+    if (isCacheValid && cachedTools) {
         tools = cachedTools.tools;
         cachedSessionId = cachedTools.sessionId;
     }
+    else if (skipLiveDiscovery) {
+        if (cachedTools) {
+            tools = cachedTools.tools;
+        }
+    }
     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);
+        if (transport) {
+            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) {
+                const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !skipLiveDiscovery;
+                if (shouldAuth) {
+                    const mcpUrl = getMcpUrl();
+                    if (mcpUrl) {
+                        const authSuccess = await handleAuthRequired(mcpUrl);
+                        if (authSuccess) {
+                            return addMcpCommands(options);
+                        }
                     }
                 }
+                if (!skipLiveDiscovery) {
+                    console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            finally {
+                await client.close();
             }
-            console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
-            return;
         }
-        finally {
-            await client.close();
+        if (!tools && cachedTools) {
+            tools = cachedTools.tools;
         }
     }
+    if (!tools) {
+        return;
+    }
     // Register CLI commands for each tool
     for (const tool of tools) {
         const inputSchema = tool.inputSchema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goke/mcp",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "description": "Dynamically generate CLI commands from MCP server tools",
   "repository": {
@@ -51,7 +51,7 @@
     "@types/node": "^22.19.7",
     "vitest": "^3.1.0",
     "zod": "^4.3.6",
-    "goke": "^6.13.0"
+    "goke": "^6.12.1"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/__test__/add-mcp-commands-help.test.ts

@@ -0,0 +1,139 @@
+// First-run help and stale-cache behavior for addMcpCommands.
+import http from 'node:http'
+import { describe, expect, it } from 'vitest'
+import { goke } from 'goke'
+import { addMcpCommands, type CachedMcpTools } from '../index.js'
+
+const staleCache = (over: Partial<CachedMcpTools> = {}): CachedMcpTools => ({
+  tools: [
+    {
+      name: 'find_bookmarks',
+      description: 'Find bookmarks',
+      inputSchema: { type: 'object', properties: {} },
+    },
+  ],
+  timestamp: Date.now() - 2 * 60 * 60 * 1000,
+  sessionId: 'stale-session',
+  ...over,
+})
+
+function captureErrors() {
+  const errors: string[] = []
+  const error = console.error
+  console.error = (...args: unknown[]) => {
+    errors.push(args.map(String).join(' '))
+  }
+  return {
+    errors,
+    restore() {
+      console.error = error
+    },
+  }
+}
+
+function listen401() {
+  const server = http.createServer((_req, res) => {
+    res.writeHead(401, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({ error: 'unauthorized' }))
+  })
+  return new Promise<{ url: string; close: () => Promise<void> }>((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address()
+      if (!addr || typeof addr === 'string') throw new Error('no port')
+      resolve({
+        url: `http://127.0.0.1:${addr.port}/mcp`,
+        close: () => new Promise((done) => server.close(() => done())),
+      })
+    })
+  })
+}
+
+describe('addMcpCommands first-run help', () => {
+  it('lets --help run when there is no token and no cache', async () => {
+    const io = captureErrors()
+    const cli = goke('testcli')
+    cli.command('config', 'Save token').action(() => {})
+
+    try {
+      await addMcpCommands({
+        cli,
+        argv: ['--help'],
+        getMcpTransport: () => null,
+        loadCache: () => undefined,
+        saveCache: () => {},
+      })
+    } finally {
+      io.restore()
+    }
+
+    const help = cli.helpText()
+    expect(io.errors.join('\n')).not.toMatch(/Failed to connect/)
+    expect(help).toMatch(/config/)
+    expect(help).not.toMatch(/find_bookmarks/)
+  })
+
+  it('registers stale cached tools when live fetch is impossible', async () => {
+    const cli = goke('testcli')
+
+    await addMcpCommands({
+      cli,
+      argv: ['--help'],
+      getMcpTransport: () => null,
+      loadCache: () => staleCache(),
+      saveCache: () => {},
+    })
+
+    expect(cli.helpText()).toMatch(/find_bookmarks/)
+  })
+
+  it('does not start OAuth when --help gets a 401', async () => {
+    const server = await listen401()
+    const authUrls: string[] = []
+    const io = captureErrors()
+    const cli = goke('testcli')
+
+    try {
+      await addMcpCommands({
+        cli,
+        argv: ['--help'],
+        getMcpUrl: () => server.url,
+        oauth: {
+          clientName: 'test',
+          load: () => undefined,
+          save: () => {},
+          onAuthUrl: (url) => {
+            authUrls.push(url)
+          },
+        },
+        loadCache: () => undefined,
+        saveCache: () => {},
+      })
+    } finally {
+      io.restore()
+      await server.close()
+    }
+
+    expect(authUrls).toEqual([])
+    expect(io.errors.join('\n')).not.toMatch(/Authentication required/)
+    expect(cli.helpText()).toMatch(/Usage/)
+  })
+
+  it('does not connect for an already registered command', async () => {
+    let transportCalls = 0
+    const cli = goke('testcli')
+    cli.command('config', 'Save token').action(() => {})
+
+    await addMcpCommands({
+      cli,
+      argv: ['config', '--token', 'x'],
+      getMcpTransport: () => {
+        transportCalls += 1
+        return null
+      },
+      loadCache: () => undefined,
+      saveCache: () => {},
+    })
+
+    expect(transportCalls).toBe(0)
+  })
+})

package/src/auth.ts

@@ -29,10 +29,8 @@ async function openBrowser(url: string): Promise<void> {
 
 /**
  * Start the OAuth flow for an MCP server.
- *
- * Used internally by addMcpCommands on 401 errors, but also available
- * for CLIs that need explicit control over the auth flow (e.g. a login
- * command that runs the flow in a background daemon).
+ * 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

package/src/index.ts

@@ -48,14 +48,13 @@ import { wrapJsonSchema } from "goke";
 import yaml from "js-yaml";
 import { FileOAuthProvider } from "./oauth-provider.js";
 import { startOAuthFlow, isAuthRequiredError } from "./auth.js";
-export { startOAuthFlow } from "./auth.js";
 import type { McpOAuthConfig, McpOAuthState } from "./types.js";
 export { addCliToolsToMcp, createMcpAction } from "./cli-to-mcp.js";
 export type { AddCliToolsToMcpOptions, CreateMcpActionOptions } from "./cli-to-mcp.js";
 
-// Public exports
+// Public exports - only types that consumers need
 export type { Transport };
-export type { McpOAuthConfig, McpOAuthState, StartOAuthFlowOptions, OAuthFlowResult } from "./types.js";
+export type { McpOAuthConfig, McpOAuthState } from "./types.js";
 
 export interface CachedMcpTools {
   tools: Array<{
@@ -91,13 +90,23 @@ export interface AddMcpCommandsOptions {
 
   /**
    * 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
+   * Use this for stdio servers or any setup `getMcpUrl` cannot express.
+   * @param sessionId - Optional session ID from a still-valid cache
    */
   getMcpTransport?: (sessionId?: string) => Transport | null | Promise<Transport | null>;
 
+  /**
+   * Argv used to decide whether to skip live discovery.
+   * Defaults to `process.argv.slice(2)`.
+   */
+  argv?: string[];
+
+  /**
+   * Extra headers for MCP HTTP requests (for example `Authorization`).
+   * Used with `getMcpUrl`. Ignored when `getMcpTransport` is set.
+   */
+  getHeaders?: () => Record<string, string> | undefined;
+
   /**
    * OAuth configuration. When provided, enables automatic OAuth authentication.
    *
@@ -225,12 +234,34 @@ function outputResult(result: {
 /**
  * Create a transport with optional OAuth authentication
  */
-function createTransportWithAuth(
-  url: URL,
-  sessionId: string | undefined,
-  oauthState: McpOAuthState | undefined,
-  oauth: McpOAuthConfig | undefined,
-): StreamableHTTPClientTransport {
+function isHelpOrMetaArgv(argv: string[]) {
+  if (argv.length === 0) return true;
+  if (argv[0] === "completions" || argv.includes("--get-goke-completions")) return true;
+  return argv.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v");
+}
+
+function matchesRegisteredCommand({ argv, cli }: { argv: string[]; cli: Goke }) {
+  const parts = argv.filter((arg) => !arg.startsWith("-"));
+  return cli.commands.some((cmd) => {
+    if (!cmd.name) return false;
+    const nameParts = cmd.name.split(" ");
+    return nameParts.every((part, i) => parts[i] === part);
+  });
+}
+
+function createTransportWithAuth({
+  url,
+  sessionId,
+  oauthState,
+  oauth,
+  headers,
+}: {
+  url: URL
+  sessionId?: string
+  oauthState?: McpOAuthState
+  oauth?: McpOAuthConfig
+  headers?: Record<string, string>
+}): StreamableHTTPClientTransport {
   let authProvider: FileOAuthProvider | undefined;
 
   if (oauth && oauthState?.tokens) {
@@ -247,9 +278,11 @@ function createTransportWithAuth(
     });
   }
 
+  const hasHeaders = headers && Object.keys(headers).length > 0;
   return new StreamableHTTPClientTransport(url, {
     sessionId,
     authProvider,
+    requestInit: hasHeaders ? { headers } : undefined,
   });
 }
 
@@ -271,9 +304,11 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
     clientName = "mcp-cli-client",
     getMcpUrl,
     getMcpTransport,
+    getHeaders,
     oauth,
     loadCache,
     saveCache,
+    argv = process.argv.slice(2),
   } = options;
 
   // Helper to get transport - supports both old and new API
@@ -288,10 +323,16 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
       const url = new URL(mcpUrl);
       const oauthState = oauth?.load();
 
-      return createTransportWithAuth(url, sessionId, oauthState, oauth);
+      return createTransportWithAuth({
+        url,
+        sessionId,
+        oauthState,
+        oauth,
+        headers: getHeaders?.(),
+      });
     }
 
-    // Legacy API: getMcpTransport
+    // Custom / stdio transport
     if (getMcpTransport) {
       return getMcpTransport(sessionId);
     }
@@ -331,55 +372,66 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
   // Try to use cached tools first (fast path - no network)
   const cachedTools = loadCache();
   const isCacheValid = cachedTools && (Date.now() - cachedTools.timestamp) < CACHE_TTL_MS;
+  const skipLiveDiscovery =
+    isHelpOrMetaArgv(argv) || matchesRegisteredCommand({ argv, cli });
 
-  let tools: CachedMcpTools["tools"];
+  let tools: CachedMcpTools["tools"] | undefined;
   let cachedSessionId: string | undefined;
 
-  if (isCacheValid) {
+  if (isCacheValid && cachedTools) {
     tools = cachedTools.tools;
     cachedSessionId = cachedTools.sessionId;
+  } else if (skipLiveDiscovery) {
+    if (cachedTools) {
+      tools = cachedTools.tools;
+    }
   } 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 as { sessionId?: string }).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);
+    if (transport) {
+      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 as { sessionId?: string }).sessionId;
+
+        saveCache({
+          tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+          timestamp: Date.now(),
+          sessionId,
+        });
+        cachedSessionId = sessionId;
+      } catch (err) {
+        const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !skipLiveDiscovery;
+        if (shouldAuth) {
+          const mcpUrl = getMcpUrl();
+          if (mcpUrl) {
+            const authSuccess = await handleAuthRequired(mcpUrl);
+            if (authSuccess) {
+              return addMcpCommands(options);
+            }
           }
         }
+        if (!skipLiveDiscovery) {
+          console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
+        }
+      } finally {
+        await client.close();
       }
-      console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
-      return;
-    } finally {
-      await client.close();
     }
+
+    if (!tools && cachedTools) {
+      tools = cachedTools.tools;
+    }
+  }
+
+  if (!tools) {
+    return;
   }
 
   // Register CLI commands for each tool