@goke/mcp 0.0.12 → 0.0.13

package/README.md

@@ -55,9 +55,9 @@ cli.completions()
 cli.parse()
 ```
 
-Always pass `getMcpUrl`. Do not return `undefined` just because the user has no token. `--help` and no-args must still run so the CLI can show `config` / login instructions.
+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 a Bearer token, pass `getHeaders` instead of a custom transport:
+For an HTTP Bearer token, pass `getHeaders`:
 
 ```ts
 await addMcpCommands({
@@ -486,7 +486,9 @@ Registers MCP tool commands on a goke CLI instance.
 |--------|------|---------|-------------|
 | `cli` | `Goke` | **required** | The goke CLI instance to add commands to |
 | `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 |

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

@@ -1,4 +1,5 @@
 // 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';
@@ -11,65 +12,82 @@ const staleCache = (over = {}) => ({
         },
     ],
     timestamp: Date.now() - 2 * 60 * 60 * 1000,
+    sessionId: 'stale-session',
     ...over,
 });
-async function withArgv(argv, fn) {
-    const previous = process.argv;
-    process.argv = ['node', 'testcli', ...argv];
-    try {
-        return await fn();
-    }
-    finally {
-        process.argv = previous;
-    }
+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 errors = [];
-        const error = console.error;
-        console.error = (...args) => {
-            errors.push(args.map(String).join(' '));
-        };
+        const io = captureErrors();
         const cli = goke('testcli');
         cli.command('config', 'Save token').action(() => { });
-        await withArgv(['--help'], async () => {
+        try {
             await addMcpCommands({
                 cli,
+                argv: ['--help'],
                 getMcpTransport: () => null,
                 loadCache: () => undefined,
                 saveCache: () => { },
             });
-        });
-        console.error = error;
+        }
+        finally {
+            io.restore();
+        }
         const help = cli.helpText();
-        expect(errors.join('\n')).not.toMatch(/Failed to connect/);
+        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 withArgv(['--help'], async () => {
-            await addMcpCommands({
-                cli,
-                getMcpTransport: () => null,
-                loadCache: () => staleCache(),
-                saveCache: () => { },
-            });
+        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 errors = [];
-        const error = console.error;
-        console.error = (...args) => {
-            errors.push(args.map(String).join(' '));
-        };
+        const io = captureErrors();
         const cli = goke('testcli');
-        await withArgv(['--help'], async () => {
+        try {
             await addMcpCommands({
                 cli,
-                getMcpUrl: () => 'http://127.0.0.1:1/mcp',
+                argv: ['--help'],
+                getMcpUrl: () => server.url,
                 oauth: {
                     clientName: 'test',
                     load: () => undefined,
@@ -81,10 +99,29 @@ describe('addMcpCommands first-run help', () => {
                 loadCache: () => undefined,
                 saveCache: () => { },
             });
-        });
-        console.error = error;
+        }
+        finally {
+            io.restore();
+            await server.close();
+        }
         expect(authUrls).toEqual([]);
-        expect(errors.join('\n')).not.toMatch(/Authentication required/);
+        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/index.d.ts

@@ -75,12 +75,15 @@ 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.

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,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;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEvF;;;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;AA4ID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiNlF"}
+{"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

@@ -131,7 +131,16 @@ function isHelpOrMetaArgv(argv) {
         return true;
     return argv.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v");
 }
-function createTransportWithAuth(url, sessionId, oauthState, oauth, headers) {
+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({
@@ -163,7 +172,7 @@ function createTransportWithAuth(url, sessionId, oauthState, oauth, headers) {
  * After successful auth, the operation is automatically retried.
  */
 export async function addMcpCommands(options) {
-    const { cli, commandPrefix = "", clientName = "mcp-cli-client", getMcpUrl, getMcpTransport, getHeaders, 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
@@ -174,9 +183,15 @@ export async function addMcpCommands(options) {
             }
             const url = new URL(mcpUrl);
             const oauthState = oauth?.load();
-            return createTransportWithAuth(url, sessionId, oauthState, oauth, getHeaders?.());
+            return createTransportWithAuth({
+                url,
+                sessionId,
+                oauthState,
+                oauth,
+                headers: getHeaders?.(),
+            });
         }
-        // Legacy API: getMcpTransport
+        // Custom / stdio transport
         if (getMcpTransport) {
             return getMcpTransport(sessionId);
         }
@@ -209,13 +224,18 @@ 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 helpOrMeta = isHelpOrMetaArgv(process.argv.slice(2));
+    const skipLiveDiscovery = isHelpOrMetaArgv(argv) || matchesRegisteredCommand({ argv, cli });
     let tools;
     let cachedSessionId;
     if (isCacheValid && cachedTools) {
         tools = cachedTools.tools;
         cachedSessionId = cachedTools.sessionId;
     }
+    else if (skipLiveDiscovery) {
+        if (cachedTools) {
+            tools = cachedTools.tools;
+        }
+    }
     else {
         const transport = await getTransport();
         if (transport) {
@@ -237,7 +257,7 @@ export async function addMcpCommands(options) {
                 cachedSessionId = sessionId;
             }
             catch (err) {
-                const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !helpOrMeta;
+                const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !skipLiveDiscovery;
                 if (shouldAuth) {
                     const mcpUrl = getMcpUrl();
                     if (mcpUrl) {
@@ -247,7 +267,7 @@ export async function addMcpCommands(options) {
                         }
                     }
                 }
-                if (!helpOrMeta) {
+                if (!skipLiveDiscovery) {
                     console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
                 }
             }
@@ -257,7 +277,6 @@ export async function addMcpCommands(options) {
         }
         if (!tools && cachedTools) {
             tools = cachedTools.tools;
-            cachedSessionId = cachedTools.sessionId;
         }
     }
     if (!tools) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goke/mcp",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "type": "module",
   "description": "Dynamically generate CLI commands from MCP server tools",
   "repository": {

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

@@ -1,4 +1,5 @@
 // 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'
@@ -12,42 +13,61 @@ const staleCache = (over: Partial<CachedMcpTools> = {}): CachedMcpTools => ({
     },
   ],
   timestamp: Date.now() - 2 * 60 * 60 * 1000,
+  sessionId: 'stale-session',
   ...over,
 })
 
-async function withArgv<T>(argv: string[], fn: () => Promise<T>) {
-  const previous = process.argv
-  process.argv = ['node', 'testcli', ...argv]
-  try {
-    return await fn()
-  } finally {
-    process.argv = previous
+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 errors: string[] = []
-    const error = console.error
-    console.error = (...args: unknown[]) => {
-      errors.push(args.map(String).join(' '))
-    }
-
+    const io = captureErrors()
     const cli = goke('testcli')
     cli.command('config', 'Save token').action(() => {})
 
-    await withArgv(['--help'], async () => {
+    try {
       await addMcpCommands({
         cli,
+        argv: ['--help'],
         getMcpTransport: () => null,
         loadCache: () => undefined,
         saveCache: () => {},
       })
-    })
-    console.error = error
+    } finally {
+      io.restore()
+    }
 
     const help = cli.helpText()
-    expect(errors.join('\n')).not.toMatch(/Failed to connect/)
+    expect(io.errors.join('\n')).not.toMatch(/Failed to connect/)
     expect(help).toMatch(/config/)
     expect(help).not.toMatch(/find_bookmarks/)
   })
@@ -55,32 +75,28 @@ describe('addMcpCommands first-run help', () => {
   it('registers stale cached tools when live fetch is impossible', async () => {
     const cli = goke('testcli')
 
-    await withArgv(['--help'], async () => {
-      await addMcpCommands({
-        cli,
-        getMcpTransport: () => null,
-        loadCache: () => staleCache(),
-        saveCache: () => {},
-      })
+    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 errors: string[] = []
-    const error = console.error
-    console.error = (...args: unknown[]) => {
-      errors.push(args.map(String).join(' '))
-    }
-
+    const io = captureErrors()
     const cli = goke('testcli')
 
-    await withArgv(['--help'], async () => {
+    try {
       await addMcpCommands({
         cli,
-        getMcpUrl: () => 'http://127.0.0.1:1/mcp',
+        argv: ['--help'],
+        getMcpUrl: () => server.url,
         oauth: {
           clientName: 'test',
           load: () => undefined,
@@ -92,11 +108,32 @@ describe('addMcpCommands first-run help', () => {
         loadCache: () => undefined,
         saveCache: () => {},
       })
-    })
-    console.error = error
+    } finally {
+      io.restore()
+      await server.close()
+    }
 
     expect(authUrls).toEqual([])
-    expect(errors.join('\n')).not.toMatch(/Authentication required/)
+    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/index.ts

@@ -90,13 +90,17 @@ 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.
@@ -236,13 +240,28 @@ function isHelpOrMetaArgv(argv: string[]) {
   return argv.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v");
 }
 
-function createTransportWithAuth(
-  url: URL,
-  sessionId: string | undefined,
-  oauthState: McpOAuthState | undefined,
-  oauth: McpOAuthConfig | undefined,
-  headers?: Record<string, string>,
-): StreamableHTTPClientTransport {
+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) {
@@ -289,6 +308,7 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
     oauth,
     loadCache,
     saveCache,
+    argv = process.argv.slice(2),
   } = options;
 
   // Helper to get transport - supports both old and new API
@@ -303,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, getHeaders?.());
+      return createTransportWithAuth({
+        url,
+        sessionId,
+        oauthState,
+        oauth,
+        headers: getHeaders?.(),
+      });
     }
 
-    // Legacy API: getMcpTransport
+    // Custom / stdio transport
     if (getMcpTransport) {
       return getMcpTransport(sessionId);
     }
@@ -346,7 +372,8 @@ 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 helpOrMeta = isHelpOrMetaArgv(process.argv.slice(2));
+  const skipLiveDiscovery =
+    isHelpOrMetaArgv(argv) || matchesRegisteredCommand({ argv, cli });
 
   let tools: CachedMcpTools["tools"] | undefined;
   let cachedSessionId: string | undefined;
@@ -354,6 +381,10 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
   if (isCacheValid && cachedTools) {
     tools = cachedTools.tools;
     cachedSessionId = cachedTools.sessionId;
+  } else if (skipLiveDiscovery) {
+    if (cachedTools) {
+      tools = cachedTools.tools;
+    }
   } else {
     const transport = await getTransport();
     if (transport) {
@@ -376,7 +407,7 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
         });
         cachedSessionId = sessionId;
       } catch (err) {
-        const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !helpOrMeta;
+        const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !skipLiveDiscovery;
         if (shouldAuth) {
           const mcpUrl = getMcpUrl();
           if (mcpUrl) {
@@ -386,7 +417,7 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
             }
           }
         }
-        if (!helpOrMeta) {
+        if (!skipLiveDiscovery) {
           console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
         }
       } finally {
@@ -396,7 +427,6 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
 
     if (!tools && cachedTools) {
       tools = cachedTools.tools;
-      cachedSessionId = cachedTools.sessionId;
     }
   }