@apify/mcpc 0.2.4 → 0.3.0-beta.0

package/dist/cli/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { initProxy } from '../lib/proxy.js';
-import { Command, Help } from 'commander';
+import { Command, CommanderError, Help } from 'commander';
 import { setVerbose, setJsonMode, closeFileLogger } from '../lib/index.js';
 import { isMcpError, formatHumanError, ClientError } from '../lib/index.js';
 import chalk from 'chalk';
-import { formatJson, formatJsonError, rainbow } from './output.js';
+import { formatJson, formatJsonError, rainbow, theme } from './output.js';
 import * as tools from './commands/tools.js';
 import * as resources from './commands/resources.js';
 import * as prompts from './commands/prompts.js';
@@ -16,7 +16,7 @@ import * as tasks from './commands/tasks.js';
 import * as grepCmd from './commands/grep.js';
 import { handleX402Command } from './commands/x402.js';
 import { clean } from './commands/clean.js';
-import { extractOptions, getVerboseFromEnv, getJsonFromEnv, validateOptions, validateArgValues, parseServerArg, hasSubcommand, optionTakesValue, KNOWN_COMMANDS, KNOWN_SESSION_COMMANDS, } from './parser.js';
+import { extractOptions, getVerboseFromEnv, getJsonFromEnv, validateOptions, validateArgValues, parseServerArg, hasSubcommand, optionTakesValue, suggestCommand, KNOWN_COMMANDS, KNOWN_SESSION_COMMANDS, } from './parser.js';
 import { createRequire } from 'module';
 const { version: mcpcVersion } = createRequire(import.meta.url)('../../package.json');
 {
@@ -64,8 +64,21 @@ function getOptionsFromCommand(command) {
     }
     if (opts.full)
         options.full = opts.full;
+    if (opts.maxChars) {
+        const maxChars = parseInt(opts.maxChars, 10);
+        if (isNaN(maxChars) || maxChars <= 0) {
+            throw new Error(`Invalid --max-chars value: "${opts.maxChars}". Must be a positive number (characters).`);
+        }
+        options.maxChars = maxChars;
+    }
     return options;
 }
+function jsonHelp(description, shape, schemaUrl) {
+    const line = shape ? `  ${description}:\n  ${shape}` : `  ${description}`;
+    const link = schemaUrl ? `\n  Schema: ${schemaUrl}` : '';
+    return `\n${chalk.bold('JSON output (--json):')}\n${line}${link}\n`;
+}
+const SCHEMA_BASE = 'https://modelcontextprotocol.io/specification/2025-11-25/schema';
 async function main() {
     const args = process.argv.slice(2);
     const handleExit = () => {
@@ -90,23 +103,33 @@ async function main() {
         return;
     }
     if (args.includes('--help') || args.includes('-h')) {
-        if (args.includes('x402')) {
+        const hasSessionArg = args.some((a) => a.startsWith('@') && !a.startsWith('--'));
+        if (hasSessionArg) {
+        }
+        else if (args.includes('x402')) {
             const x402Index = args.indexOf('x402');
             const x402Args = args.slice(x402Index + 1);
             await handleX402Command(x402Args);
             await closeFileLogger();
             return;
         }
-        const program = createTopLevelProgram();
-        await program.parseAsync(process.argv);
-        return;
+        else {
+            const helpTarget = args.find((a) => a !== '--help' && a !== '-h' && !a.startsWith('-') && !a.startsWith('@'));
+            if (helpTarget && KNOWN_SESSION_COMMANDS.includes(helpTarget)) {
+                showSessionCommandHelp(helpTarget);
+                return;
+            }
+            const program = createTopLevelProgram();
+            await program.parseAsync(process.argv);
+            return;
+        }
     }
     try {
         validateOptions(args);
         validateArgValues(args);
     }
     catch (error) {
-        console.error(chalk.red(formatHumanError(error, false)));
+        console.error(theme.red(formatHumanError(error, false)));
         process.exit(1);
     }
     let firstNonOption;
@@ -154,7 +177,7 @@ async function main() {
                     console.error(formatJsonError(error, error.code));
                 }
                 else {
-                    console.error(chalk.red(formatHumanError(error, opts.verbose)));
+                    console.error(theme.red(formatHumanError(error, opts.verbose)));
                 }
                 process.exit(error.code);
             }
@@ -185,7 +208,7 @@ async function main() {
                     console.error(formatJsonError(error, error.code));
                 }
                 else {
-                    console.error(chalk.red(formatHumanError(error, opts.verbose)));
+                    console.error(theme.red(formatHumanError(error, opts.verbose)));
                 }
                 process.exit(error.code);
             }
@@ -210,11 +233,20 @@ async function main() {
         }
     }
     else {
+        const suggestion = suggestCommand(firstNonOption, allCommands);
         if (outputMode === 'json') {
             console.error(formatJsonError(new Error(`Unknown command: ${firstNonOption}`), 1));
         }
         else {
             console.error(`Error: Unknown command: ${firstNonOption}`);
+            if (suggestion) {
+                if (KNOWN_SESSION_COMMANDS.includes(suggestion)) {
+                    console.error(`\nDid you mean: mcpc <@session> ${suggestion}`);
+                }
+                else {
+                    console.error(`\nDid you mean: mcpc ${suggestion}`);
+                }
+            }
             console.error(`Run "mcpc --help" for usage information.\n`);
         }
     }
@@ -231,7 +263,7 @@ function createTopLevelProgram() {
     program.configureHelp({
         subcommandTerm: (cmd) => `${cmd.name()} ${cmd.usage()}`.replace(/^\[options\]\s*|\s*\[options\]/g, '').trim(),
         styleTitle: (str) => chalk.bold(str),
-        styleSubcommandText: (str) => chalk.cyan(str),
+        styleSubcommandText: (str) => theme.cyan(str),
         formatHelp: (cmd, helper) => {
             const output = Help.prototype.formatHelp.call(helper, cmd, helper);
             const sections = output.split('\n\n');
@@ -248,78 +280,131 @@ function createTopLevelProgram() {
                 .join('\n\n') + '\n');
         },
     });
-    const docsUrl = process.stdout.isTTY
-        ? `https://github.com/apify/mcpc/tree/v${mcpcVersion}`
-        : `https://raw.githubusercontent.com/apify/mcpc/v${mcpcVersion}/README.md`;
+    const docsUrl = `https://github.com/apify/mcpc/raw/refs/tags/v${mcpcVersion}/README.md`;
     program
         .name('mcpc')
         .description(`${rainbow('Universal')} command-line client for the Model Context Protocol (MCP).`)
         .usage('[<@session>] [<command>] [options]')
-        .option('-j, --json', 'Output in JSON format for scripting')
+        .option('--json', 'Output in JSON format for scripting')
         .option('--verbose', 'Enable debug logging')
         .option('--profile <name>', 'OAuth profile for the server ("default" if not provided)')
-        .option('--schema <file>', 'Validate tool/prompt schema against expected schema')
-        .option('--schema-mode <mode>', 'Schema validation mode: strict, compatible (default), ignore')
         .option('--timeout <seconds>', 'Request timeout in seconds (default: 300)')
+        .option('--max-chars <n>', 'Truncate output to n characters (ignored in --json mode)')
         .option('--insecure', 'Skip TLS certificate verification (for self-signed certs)')
         .version(mcpcVersion, '-v, --version', 'Output the version number')
         .helpOption('-h, --help', 'Display help');
     program.addHelpText('after', `
 ${chalk.bold('MCP session commands (after connecting):')}
-  <@session>                   Show MCP server info, capabilities, and tools
-  <@session> ${chalk.cyan('grep')} <pattern>    Search tools and instructions
-  <@session> ${chalk.cyan('tools-list')}        List all server tools
-  <@session> ${chalk.cyan('tools-get')} <name>  Get tool details and schema
-  <@session> ${chalk.cyan('tools-call')} <name> [arg:=val ... | <json> | <stdin]
-  <@session> ${chalk.cyan('prompts-list')}
-  <@session> ${chalk.cyan('prompts-get')} <name> [arg:=val ... | <json> | <stdin]
-  <@session> ${chalk.cyan('resources-list')}
-  <@session> ${chalk.cyan('resources-read')} <uri>
-  <@session> ${chalk.cyan('resources-subscribe')} <uri>
-  <@session> ${chalk.cyan('resources-unsubscribe')} <uri>
-  <@session> ${chalk.cyan('resources-templates-list')}
-  <@session> ${chalk.cyan('tasks-list')}
-  <@session> ${chalk.cyan('tasks-get')} <taskId>
-  <@session> ${chalk.cyan('tasks-cancel')} <taskId>
-  <@session> ${chalk.cyan('logging-set-level')} <level>
-  <@session> ${chalk.cyan('ping')}
+  <@session>                   Show MCP server info, capabilities, and tools overview
+  <@session> ${theme.cyan('grep')} <pattern>    Search tools and instructions
+  <@session> ${theme.cyan('tools-list')}        List all server tools
+  <@session> ${theme.cyan('tools-get')} <name>  Get tool details and schema
+  <@session> ${theme.cyan('tools-call')} <name> [arg:=val ... | <json> | <stdin]
+  <@session> ${theme.cyan('prompts-list')}
+  <@session> ${theme.cyan('prompts-get')} <name> [arg:=val ... | <json> | <stdin]
+  <@session> ${theme.cyan('resources-list')}
+  <@session> ${theme.cyan('resources-read')} <uri>
+  <@session> ${theme.cyan('resources-subscribe')} <uri>
+  <@session> ${theme.cyan('resources-unsubscribe')} <uri>
+  <@session> ${theme.cyan('resources-templates-list')}
+  <@session> ${theme.cyan('tasks-list')}
+  <@session> ${theme.cyan('tasks-get')} <taskId>
+  <@session> ${theme.cyan('tasks-result')} <taskId>
+  <@session> ${theme.cyan('tasks-cancel')} <taskId>
+  <@session> ${theme.cyan('logging-set-level')} <level>
+  <@session> ${theme.cyan('ping')}
 
 Run "mcpc" without arguments to show active sessions and OAuth profiles.
+Run "mcpc --json" to get the same data as \`{ sessions: [...], profiles: [...] }\`.
 
 Full docs: ${docsUrl}`);
     program
         .command('connect [server] [@session]')
-        .usage('<server> <@session>')
+        .usage('<server> [@session]')
         .description('Connect to an MCP server and start a new named @session')
         .option('-H, --header <header>', 'HTTP header (can be repeated)')
         .option('--profile <name>', 'OAuth profile to use ("default" if skipped)')
         .option('--no-profile', 'Skip OAuth profile (connect anonymously)')
         .option('--proxy <[host:]port>', 'Start proxy MCP server for session')
         .option('--proxy-bearer-token <token>', 'Require authentication for access to proxy server')
+        .option('--stdio', 'Launch all local stdio servers from selected config files')
         .option('--x402', 'Enable x402 auto-payment using the configured wallet')
         .addHelpText('after', `
 ${chalk.bold('Server formats:')}
-  mcp.apify.com                 Remote HTTP server (https:// added automatically)
+  mcp.apify.com                 Remote HTTP server (https:// auto-added)
   ~/.vscode/mcp.json:puppeteer  Config file entry (file:entry)
-`)
+  ~/.vscode/mcp.json            Config file — connect every entry
+  ${chalk.dim('(no server)')}                  Auto-discover configs and connect everything
+
+${chalk.bold('Auto-discovery (no server arg):')}
+  Scans ./ and ~ for .mcp.json, mcp.json, mcp_config.json, .cursor/mcp.json,
+  .vscode/mcp.json, .kiro/settings/mcp.json, ~/.claude.json,
+  ~/.codeium/windsurf/mcp_config.json, plus VS Code & Claude Desktop configs.
+  Set APIFY_API_TOKEN to auto-connect mcp.apify.com as @apify.
+
+${chalk.bold('Session name:')}
+  Omit @session to auto-generate from the server (mcp.apify.com → @apify)
+  or config entry. Matching sessions (same server, profile, header keys)
+  are reused. Bulk connects don't accept @session.
+
+${chalk.bold('Stdio servers (command-based, run locally):')}
+  Config entries spawn the command on connect, even if the handshake
+  later fails — only connect to configs you trust. Stderr is logged to
+  ~/.mcpc/logs/bridge-<session>.log. Bulk connects skip stdio by default;
+  pass --stdio to include them.
+${jsonHelp('Array of `InitializeResult` objects (one per session), extended with `toolNames` and `_mcpc` metadata', '`[{ protocolVersion?, capabilities?, serverInfo?, instructions?, toolNames?, _mcpc: { sessionName, server?, ... }]`', `${SCHEMA_BASE}#initializeresult`)}`)
         .action(async (server, sessionName, opts, command) => {
-        if (!server) {
-            throw new ClientError('Missing required argument: server\n\nExample: mcpc connect mcp.apify.com @myapp');
-        }
-        if (!sessionName) {
-            throw new ClientError('Missing required argument: @session\n\nExample: mcpc connect mcp.apify.com @myapp');
-        }
         const globalOpts = getOptionsFromCommand(command);
-        const parsed = parseServerArg(server);
         const headers = opts.header
             ? Array.isArray(opts.header)
                 ? opts.header
                 : [opts.header]
             : undefined;
+        if (!server) {
+            if (sessionName) {
+                throw new ClientError(`Cannot specify @session name when discovering and connecting all servers.\n` +
+                    `To connect a specific server, pass a URL or config entry: mcpc connect <server> ${sessionName}`);
+            }
+            await sessions.connectAllFromStandardConfigs({
+                ...globalOpts,
+                ...(headers && { headers }),
+                ...(opts.proxy && { proxy: opts.proxy }),
+                ...(opts.proxyBearerToken && { proxyBearerToken: opts.proxyBearerToken }),
+                ...(opts.stdio && { stdio: true }),
+                ...(opts.x402 && { x402: opts.x402 }),
+                ...(globalOpts.insecure && { insecure: true }),
+            });
+            return;
+        }
+        const parsed = parseServerArg(server);
         if (!parsed) {
             throw new ClientError(`Invalid server: "${server}"\n\n` +
                 `Expected a URL (e.g. mcp.apify.com) or a config file entry (e.g. ~/.vscode/mcp.json:filesystem)`);
         }
+        if (parsed.type === 'config-file') {
+            if (sessionName) {
+                throw new ClientError(`Cannot specify @session name when connecting all servers from a config file.\n` +
+                    `To connect a specific entry, use: mcpc connect ${server}:<entry> ${sessionName}`);
+            }
+            await sessions.connectAllFromConfig(parsed.file, {
+                ...globalOpts,
+                ...(headers && { headers }),
+                ...(opts.proxy && { proxy: opts.proxy }),
+                ...(opts.proxyBearerToken && { proxyBearerToken: opts.proxyBearerToken }),
+                ...(opts.stdio && { stdio: true }),
+                ...(opts.x402 && { x402: opts.x402 }),
+                ...(globalOpts.insecure && { insecure: true }),
+            });
+            return;
+        }
+        if (!sessionName) {
+            sessionName = await sessions.resolveSessionName(parsed, {
+                outputMode: globalOpts.outputMode,
+                ...(globalOpts.profile && { profile: globalOpts.profile }),
+                ...(headers && { headers }),
+                ...(globalOpts.noProfile && { noProfile: globalOpts.noProfile }),
+            });
+        }
         if (parsed.type === 'config') {
             await sessions.connectSession(parsed.entry, sessionName, {
                 ...globalOpts,
@@ -346,6 +431,7 @@ ${chalk.bold('Server formats:')}
         .command('close [@session]')
         .usage('<@session>')
         .description('Close a session')
+        .addHelpText('after', jsonHelp('`{ sessionName, closed: true }`'))
         .action(async (sessionName, _opts, command) => {
         if (!sessionName) {
             throw new ClientError('Missing required argument: @session\n\nExample: mcpc close @myapp');
@@ -377,18 +463,48 @@ ${chalk.bold('Server formats:')}
         .usage('<server>')
         .description('Interactively login to a server using OAuth and save profile')
         .option('--profile <name>', 'Profile name (default: "default")')
-        .option('--scope <scopes>', 'OAuth scopes to request, quoted and space-separated (e.g. --scope "read write")')
-        .option('--client-id <id>', 'OAuth client ID (for servers without dynamic client registration)')
-        .option('--client-secret <secret>', 'OAuth client secret (for servers without dynamic client registration)')
+        .option('--scope <scopes>', 'OAuth scopes to request (e.g. --scope "read write")')
+        .option('--client-id <id>', 'Pre-registered OAuth client ID (skips CIMD and DCR)')
+        .option('--client-secret <secret>', 'Pre-registered OAuth client secret (requires --client-id)')
+        .option('--client-metadata-url <url>', 'HTTPS URL of an OAuth CIMD (default: https://apify.github.io/mcpc/client-metadata.json)')
+        .option('--no-client-metadata-url', 'Disable CIMD; force DCR on CIMD-capable servers')
+        .option('--callback-port <port>', 'Loopback port for OAuth callback (default: 13316–13325)')
+        .addHelpText('after', `
+${chalk.bold('OAuth client registration approaches:')}
+
+  1. Pre-registration: --client-id (and optionally --client-secret).
+  2. Client ID Metadata Documents (CIMD): used by default. mcpc ships with a
+     hosted CIMD at https://apify.github.io/mcpc/client-metadata.json
+     which identifies all mcpc installs as the same client. Override with
+     --client-metadata-url <url> or disable with --no-client-metadata-url.
+     Active only when the authorization server advertises
+     "client_id_metadata_document_supported: true".
+  3. Dynamic Client Registration (DCR): fallback when the server exposes a
+     "registration_endpoint" and CIMD is not supported or disabled.
+
+  See https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
+
+${jsonHelp('Interactive prompts are written to stderr, stdout contains a clean JSON object', '`{ profile, serverUrl, scopes }`')}
+`)
         .action(async (server, opts, command) => {
         if (!server) {
             throw new ClientError('Missing required argument: server\n\nExample: mcpc login mcp.apify.com');
         }
+        let callbackPort;
+        if (opts.callbackPort) {
+            const parsed = parseInt(opts.callbackPort, 10);
+            if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+                throw new ClientError(`Invalid --callback-port value: "${opts.callbackPort}". Must be an integer between 1 and 65535.`);
+            }
+            callbackPort = parsed;
+        }
         await auth.login(server, {
             profile: opts.profile,
             scope: opts.scope,
             clientId: opts.clientId,
             clientSecret: opts.clientSecret,
+            clientMetadataUrl: opts.clientMetadataUrl,
+            ...(callbackPort !== undefined ? { callbackPort } : {}),
             ...getOptionsFromCommand(command),
         });
     });
@@ -397,6 +513,7 @@ ${chalk.bold('Server formats:')}
         .usage('<server>')
         .description('Delete an OAuth profile for a server')
         .option('--profile <name>', 'Profile name (default: "default")')
+        .addHelpText('after', jsonHelp('`{ profile, serverUrl, deleted: true, affectedSessions }`'))
         .action(async (server, opts, command) => {
         if (!server) {
             throw new ClientError('Missing required argument: server\n\nExample: mcpc logout mcp.apify.com');
@@ -417,7 +534,7 @@ ${chalk.bold('Resources:')}
   all         Remove all of the above
 
 Without arguments, performs safe cleanup of stale data only.
-`)
+${jsonHelp('`{ crashedBridges, expiredSessions, orphanedBridgeLogs, sessions, profiles, logs }`')}`)
         .action(async (resources, _opts, command) => {
         const globalOpts = getOptionsFromCommand(command);
         const VALID_CLEAN_TYPES = ['sessions', 'profiles', 'logs', 'all'];
@@ -458,7 +575,7 @@ ${chalk.bold('Examples:')}
   mcpc @apify grep "actor"                  Search within a single session
   mcpc grep "file" --json                   JSON output for scripting
   mcpc grep "actor" -m 5                    Show at most 5 results
-`)
+${jsonHelp('`[{ sessionName, tools?: Tool[], resources?: Resource[], prompts?: Prompt[], instructions?: string[] }]`')}`)
         .action(async (pattern, opts, command) => {
         if (!pattern) {
             throw new ClientError('Missing required argument: pattern\n\nUsage: mcpc grep <pattern>\n\nExample: mcpc grep "search"');
@@ -496,18 +613,17 @@ ${chalk.bold('Examples:')}
         }
         const topLevelCmd = program.commands.find((c) => c.name() === cmdName || c.aliases().includes(cmdName));
         if (topLevelCmd) {
+            tuneCommandHelp(topLevelCmd);
             topLevelCmd.outputHelp();
             return;
         }
-        const dummyProgram = new Command();
-        dummyProgram.name('mcpc <@session>');
-        registerSessionCommands(dummyProgram, '@dummy');
-        const sessionCmd = dummyProgram.commands.find((c) => c.name() === cmdName || c.aliases().includes(cmdName));
-        if (sessionCmd) {
-            sessionCmd.outputHelp();
+        if (showSessionCommandHelp(cmdName))
             return;
-        }
         console.error(`Unknown command: ${cmdName}`);
+        const suggestion = suggestCommand(cmdName, [...KNOWN_COMMANDS, ...KNOWN_SESSION_COMMANDS]);
+        if (suggestion) {
+            console.error(`\nDid you mean: mcpc help ${suggestion}`);
+        }
         console.error(`Run "mcpc --help" for usage information.`);
         process.exit(1);
     });
@@ -523,57 +639,158 @@ ${chalk.bold('Examples:')}
     });
     return program;
 }
+const NO_JSON_COMMANDS = new Set(['shell']);
+function tuneCommandHelp(cmd) {
+    if (!NO_JSON_COMMANDS.has(cmd.name()) && !cmd.options.some((o) => o.long === '--json')) {
+        cmd.option('--json', 'Output in JSON format');
+    }
+    cmd.helpOption('-h, --help', 'Display help');
+    const helpOpt = cmd._getHelpOption?.();
+    if (helpOpt)
+        helpOpt.hidden = true;
+}
+function showSessionCommandHelp(cmdName) {
+    const dummyProgram = createSessionProgram();
+    registerSessionCommands(dummyProgram, '<@session>');
+    for (const cmd of dummyProgram.commands) {
+        tuneCommandHelp(cmd);
+    }
+    const sessionCmd = dummyProgram.commands.find((c) => c.name() === cmdName || c.aliases().includes(cmdName));
+    if (sessionCmd) {
+        sessionCmd.outputHelp();
+        return true;
+    }
+    return false;
+}
 function registerSessionCommands(program, session) {
     program
-        .command('help')
-        .description('Show server instructions and available capabilities')
-        .action(async (_options, command) => {
-        await sessions.showHelp(session, getOptionsFromCommand(command));
+        .command('help', { hidden: true })
+        .description('Show available commands and options.')
+        .action((_options, command) => {
+        command.parent.outputHelp();
     });
     program
         .command('shell')
-        .description('Interactive shell for the session')
+        .description('Launch interactive MCP shell.')
         .action(async () => {
         await sessions.openShell(session);
     });
     program
-        .command('close', { hidden: true })
-        .description('Close the session')
+        .command('close')
+        .description('Close MCP session.')
         .action(async (_options, command) => {
         await sessions.closeSession(session, getOptionsFromCommand(command));
     });
     program
         .command('restart')
-        .description('Restart the session (stop and start the bridge)')
+        .description('Restart MCP session (losing all state).')
         .action(async (_options, command) => {
         await sessions.restartSession(session, getOptionsFromCommand(command));
     });
     program
-        .command('tools')
-        .description('List available tools (shorthand for tools-list)')
-        .option('--full', 'Show full tool details including complete input schema')
-        .action(async (_options, command) => {
-        await tools.listTools(session, getOptionsFromCommand(command));
+        .command('grep <pattern>')
+        .usage('<pattern> [options]')
+        .description('Search MCP session objects.')
+        .option('--tools', 'Search tools')
+        .option('--resources', 'Search resources')
+        .option('--prompts', 'Search prompts')
+        .option('--instructions', 'Search server instructions')
+        .option('-E, --regex', 'Treat pattern as a regular expression')
+        .option('-s, --case-sensitive', 'Case-sensitive matching')
+        .option('-m, --max-results <n>', 'Limit the number of results')
+        .addHelpText('after', `
+${chalk.bold('Type filters:')}
+  By default, tools and instructions are searched. Use --resources or --prompts
+  to search those instead. Combine flags to search multiple types.
+
+${chalk.bold('Examples:')}
+  mcpc ${session} grep "search"                  Search tools and instructions
+  mcpc ${session} grep "search" --resources      Search resources only
+  mcpc ${session} grep "search|find" -E          Regex search
+${jsonHelp('`{ tools?: Tool[], resources?: Resource[], prompts?: Prompt[], instructions?: string[] }`')}`)
+        .action(async (pattern, opts, command) => {
+        const globalOpts = getOptionsFromCommand(command);
+        const maxResults = opts.maxResults ? parseInt(opts.maxResults, 10) : undefined;
+        const exitCode = await grepCmd.grepSession(session, pattern, {
+            tools: opts.tools,
+            resources: opts.resources,
+            prompts: opts.prompts,
+            instructions: opts.instructions,
+            regex: opts.regex,
+            caseSensitive: opts.caseSensitive,
+            maxResults,
+            ...globalOpts,
+        });
+        process.exit(exitCode);
     });
     program
         .command('tools-list')
-        .description('List available tools')
-        .option('--full', 'Show full tool details including complete input schema')
+        .description('List all MCP tools.')
+        .option('--full', 'Show full tool details including schema')
+        .addHelpText('after', jsonHelp('Array of `Tool` objects', '`[{ name, description?, inputSchema, outputSchema?, annotations? }, ...]`', `${SCHEMA_BASE}#tool`))
         .action(async (_options, command) => {
         await tools.listTools(session, getOptionsFromCommand(command));
     });
     program
         .command('tools-get <name>')
-        .description('Get information about a specific tool')
+        .description('Get details and schema for an MCP tool.')
+        .option('--schema <file>', 'Validate tool schema against expected schema')
+        .option('--schema-mode <mode>', 'Schema validation mode: strict, compatible (default), ignore')
+        .addHelpText('after', `
+${chalk.bold('Schema validation:')}
+  --schema <file>       Validate against expected schema (save with tools-get --json)
+  --schema-mode <mode>  strict | compatible (default) | ignore
+${jsonHelp('`Tool` object', '`{ name, description?, inputSchema, outputSchema?, annotations? }`', `${SCHEMA_BASE}#tool`)}`)
         .action(async (name, _options, command) => {
         await tools.getTool(session, name, getOptionsFromCommand(command));
     });
+    const toolsCallJsonHelp = jsonHelp('`CallToolResult` object', '`{ content: [{ type, text?, ... }], isError?, structuredContent?: { ... } }`', `${SCHEMA_BASE}#calltoolresult`);
+    const toolsCallCombinedJsonHelp = `
+${chalk.bold('JSON output (--json):')}
+  \`CallToolResult\` object:
+  \`{ content: [{ type, text?, ... }], isError?, structuredContent?: { ... } }\`
+  Schema: ${SCHEMA_BASE}#calltoolresult
+
+  With \`--detach\`: \`CreateTaskResult\` object:
+  \`{ taskId: string, status: string }\`
+  Schema: ${SCHEMA_BASE}#createtaskresult
+`;
     program
         .command('tools-call <name> [args...]')
-        .description('Call a tool with arguments (key:=value pairs or JSON)')
-        .option('--task', 'Use task execution (experimental)')
+        .description('Call an MCP tool with arguments.')
+        .helpOption(false)
+        .option('--task', 'Use async task execution; Ctrl+C prints the task ID and exits (experimental)')
         .option('--detach', 'Start task and return immediately with task ID (implies --task)')
+        .option('--schema <file>', 'Validate tool schema against expected schema before calling')
+        .option('--schema-mode <mode>', 'Schema validation mode: strict, compatible (default), ignore')
+        .addHelpText('after', `
+${chalk.bold('Arguments:')}
+  key:=value pairs    mcpc ${session} tools-call search query:=hello limit:=10
+  Inline JSON         mcpc ${session} tools-call search '{"query":"hello"}'
+  Stdin pipe          echo '{"query":"hello"}' | mcpc ${session} tools-call search
+
+  Values are auto-parsed: strings, numbers, booleans, JSON objects/arrays.
+  To force a string, wrap in quotes: id:='"123"'
+
+${chalk.bold('Async tasks (--task, --detach):')}
+  --task shows a progress spinner while the task runs on the server.
+  If you press Ctrl+C, the task keeps running and a hint with the task ID
+  is printed so you can fetch or cancel it later.
+  --detach returns the task ID immediately without waiting.
+
+${chalk.bold('Schema validation:')}
+  --schema <file>       Validate tool schema before calling (save with tools-get --json)
+  --schema-mode <mode>  strict | compatible (default) | ignore
+${toolsCallCombinedJsonHelp}`)
         .action(async (name, args, options, command) => {
+        if (name === '--help' || name === '-h') {
+            command.help();
+            return;
+        }
+        if (args.includes('--help') || args.includes('-h')) {
+            await tools.getTool(session, name, getOptionsFromCommand(command));
+            return;
+        }
         await tools.callTool(session, name, {
             args,
             task: options.task,
@@ -583,39 +800,45 @@ function registerSessionCommands(program, session) {
     });
     program
         .command('tasks-list')
-        .description('List active tasks')
+        .description('List all MCP tasks.')
+        .addHelpText('after', jsonHelp('`{ tasks: Task[] }`', '`{ tasks: [{ taskId, status, ttl, createdAt, lastUpdatedAt, statusMessage?, pollInterval? }] }`', `${SCHEMA_BASE}#task`))
         .action(async (_options, command) => {
         await tasks.listTasks(session, getOptionsFromCommand(command));
     });
     program
         .command('tasks-get <taskId>')
-        .description('Get status of a specific task')
+        .description('Get MCP task status.')
+        .addHelpText('after', jsonHelp('`Task` object', '`{ taskId, status, ttl, createdAt, lastUpdatedAt, statusMessage?, pollInterval? }`', `${SCHEMA_BASE}#task`))
         .action(async (taskId, _options, command) => {
         await tasks.getTask(session, taskId, getOptionsFromCommand(command));
     });
     program
-        .command('tasks-cancel <taskId>')
-        .description('Cancel a running task')
+        .command('tasks-result <taskId>')
+        .description('Get MCP task final result (blocks until task reaches a terminal state).')
+        .addHelpText('after', toolsCallJsonHelp)
         .action(async (taskId, _options, command) => {
-        await tasks.cancelTask(session, taskId, getOptionsFromCommand(command));
+        await tasks.getTaskResult(session, taskId, getOptionsFromCommand(command));
     });
     program
-        .command('resources')
-        .description('List available resources (shorthand for resources-list)')
-        .action(async (_options, command) => {
-        await resources.listResources(session, getOptionsFromCommand(command));
+        .command('tasks-cancel <taskId>')
+        .description('Cancel an MCP task.')
+        .addHelpText('after', jsonHelp('`Task` object', '`{ taskId, status, ttl, createdAt, lastUpdatedAt, statusMessage?, pollInterval? }`', `${SCHEMA_BASE}#task`))
+        .action(async (taskId, _options, command) => {
+        await tasks.cancelTask(session, taskId, getOptionsFromCommand(command));
     });
     program
         .command('resources-list')
-        .description('List available resources')
+        .description('List all MCP resources.')
+        .addHelpText('after', jsonHelp('Array of `Resource` objects', '`[{ uri, name?, description?, mimeType? }, ...]`', `${SCHEMA_BASE}#resource`))
         .action(async (_options, command) => {
         await resources.listResources(session, getOptionsFromCommand(command));
     });
     program
         .command('resources-read <uri>')
-        .description('Get a resource by URI')
+        .description('Read an MCP resource by URI.')
         .option('-o, --output <file>', 'Write resource to file')
         .option('--max-size <bytes>', 'Maximum resource size in bytes')
+        .addHelpText('after', jsonHelp('`ReadResourceResult` object', '`{ contents: [{ uri, mimeType?, text? | blob? }] }`', `${SCHEMA_BASE}#readresourceresult`))
         .action(async (uri, options, command) => {
         await resources.getResource(session, uri, {
             output: options.output,
@@ -625,37 +848,44 @@ function registerSessionCommands(program, session) {
     });
     program
         .command('resources-subscribe <uri>')
-        .description('Subscribe to resource updates')
+        .description('Subscribe to MCP resource updates.')
+        .addHelpText('after', jsonHelp('`{ subscribed: true, uri: string }`'))
         .action(async (uri, _options, command) => {
         await resources.subscribeResource(session, uri, getOptionsFromCommand(command));
     });
     program
         .command('resources-unsubscribe <uri>')
-        .description('Unsubscribe from resource updates')
+        .description('Unsubscribe from MCP resource updates.')
+        .addHelpText('after', jsonHelp('`{ unsubscribed: true, uri: string }`'))
         .action(async (uri, _options, command) => {
         await resources.unsubscribeResource(session, uri, getOptionsFromCommand(command));
     });
     program
         .command('resources-templates-list')
-        .description('List available resource templates')
+        .description('List MCP resource templates.')
+        .addHelpText('after', jsonHelp('Array of `ResourceTemplate` objects', '`[{ uriTemplate, name?, description?, mimeType? }, ...]`', `${SCHEMA_BASE}#resourcetemplate`))
         .action(async (_options, command) => {
         await resources.listResourceTemplates(session, getOptionsFromCommand(command));
     });
-    program
-        .command('prompts')
-        .description('List available prompts (shorthand for prompts-list)')
-        .action(async (_options, command) => {
-        await prompts.listPrompts(session, getOptionsFromCommand(command));
-    });
     program
         .command('prompts-list')
-        .description('List available prompts')
+        .description('List all MCP prompts.')
+        .addHelpText('after', jsonHelp('Array of `Prompt` objects', '`[{ name, description?, arguments?: [{ name, required? }] }, ...]`', `${SCHEMA_BASE}#prompt`))
         .action(async (_options, command) => {
         await prompts.listPrompts(session, getOptionsFromCommand(command));
     });
     program
         .command('prompts-get <name> [args...]')
-        .description('Get a prompt by name with arguments (key:=value pairs or JSON)')
+        .description('Get an MCP prompt with arguments.')
+        .addHelpText('after', `
+${chalk.bold('Arguments:')}
+  key:=value pairs    mcpc ${session} prompts-get summarize style:=brief lang:=en
+  Inline JSON         mcpc ${session} prompts-get summarize '{"style":"brief"}'
+  Stdin pipe          echo '{"style":"brief"}' | mcpc ${session} prompts-get summarize
+
+  Values are auto-parsed: strings, numbers, booleans, JSON objects/arrays.
+  To force a string, wrap in quotes: id:='"123"'
+${jsonHelp('`GetPromptResult` object', '`{ description?, messages: [{ role, content: { type, text?, ... } }] }`', `${SCHEMA_BASE}#getpromptresult`)}`)
         .action(async (name, args, _options, command) => {
         await prompts.getPrompt(session, name, {
             args,
@@ -664,63 +894,47 @@ function registerSessionCommands(program, session) {
     });
     program
         .command('logging-set-level <level>')
-        .description('Set server logging level (debug, info, notice, warning, error, critical, alert, emergency)')
+        .description('Set MCP server logging level.')
+        .addHelpText('after', jsonHelp('`{ level: string }`'))
         .action(async (level, _options, command) => {
         await logging.setLogLevel(session, level, getOptionsFromCommand(command));
     });
     program
         .command('ping')
-        .description('Ping the MCP server to check if it is alive')
+        .description('Ping the MCP server.')
+        .addHelpText('after', jsonHelp('`{ success: true, durationMs: number }`'))
         .action(async (_options, command) => {
         await utilities.ping(session, getOptionsFromCommand(command));
     });
-    program
-        .command('grep <pattern>')
-        .description('Search tools and instructions')
-        .option('--tools', 'Search tools')
-        .option('--resources', 'Search resources')
-        .option('--prompts', 'Search prompts')
-        .option('--instructions', 'Search server instructions')
-        .option('-E, --regex', 'Treat pattern as a regular expression')
-        .option('-s, --case-sensitive', 'Case-sensitive matching')
-        .option('-m, --max-results <n>', 'Limit the number of results')
-        .action(async (pattern, opts, command) => {
-        const globalOpts = getOptionsFromCommand(command);
-        const maxResults = opts.maxResults ? parseInt(opts.maxResults, 10) : undefined;
-        const exitCode = await grepCmd.grepSession(session, pattern, {
-            tools: opts.tools,
-            resources: opts.resources,
-            prompts: opts.prompts,
-            instructions: opts.instructions,
-            regex: opts.regex,
-            caseSensitive: opts.caseSensitive,
-            maxResults,
-            ...globalOpts,
-        });
-        process.exit(exitCode);
-    });
 }
 function createSessionProgram() {
     const program = new Command();
     program.configureOutput({
-        outputError: (str, write) => write(str),
+        outputError: () => { },
         getOutHelpWidth: () => 100,
         getErrHelpWidth: () => 100,
     });
+    program.configureHelp({
+        subcommandTerm: (cmd) => `${cmd.name()} ${cmd.usage()}`.replace(/^\[options\]\s*|\s*\[options\]/g, '').trim(),
+        styleTitle: (str) => chalk.bold(str),
+        styleSubcommandText: (str) => theme.cyan(str),
+    });
     program
         .name('mcpc <@session>')
+        .description('Execute MCP commands on a connected session.')
         .helpOption('-h, --help', 'Display help')
-        .option('-j, --json', 'Output in JSON format for scripting and code mode')
+        .option('--json', 'Output in JSON format for scripting and code mode')
         .option('--verbose', 'Enable debug logging')
         .option('--profile <name>', 'OAuth profile override')
-        .option('--schema <file>', 'Validate tool/prompt schema against expected schema')
-        .option('--schema-mode <mode>', 'Schema validation mode: strict, compatible (default), ignore')
         .option('--timeout <seconds>', 'Request timeout in seconds (default: 300)')
-        .option('--insecure', 'Skip TLS certificate verification (for self-signed certs)');
+        .option('--max-chars <n>', 'Truncate output to n characters (ignored in --json mode)')
+        .option('--insecure', 'Skip TLS certificate verification (for self-signed certs)')
+        .addHelpText('after', `\nWhen no command is given, shows server info, capabilities, and tools.\n`);
     return program;
 }
 async function handleSessionCommands(session, args) {
-    if (!hasSubcommand(args)) {
+    const argsSlice = args.slice(2);
+    if (!hasSubcommand(args) && !argsSlice.includes('--help') && !argsSlice.includes('-h')) {
         const options = extractOptions(args);
         if (options.verbose)
             setVerbose(true);
@@ -734,25 +948,50 @@ async function handleSessionCommands(session, args) {
         return;
     }
     const program = createSessionProgram();
+    program.name(`mcpc ${session}`);
+    program.exitOverride();
     registerSessionCommands(program, session);
+    for (const cmd of program.commands) {
+        tuneCommandHelp(cmd);
+    }
     try {
         await program.parseAsync(args);
     }
     catch (error) {
         const opts = program.opts();
         const outputMode = opts.json ? 'json' : 'human';
+        if (error instanceof CommanderError && error.code === 'commander.unknownCommand') {
+            const unknownCmd = args.find((a, i) => i >= 2 && !a.startsWith('-') && !KNOWN_SESSION_COMMANDS.includes(a));
+            if (unknownCmd) {
+                const suggestion = suggestCommand(unknownCmd, KNOWN_SESSION_COMMANDS);
+                if (outputMode === 'json') {
+                    console.error(formatJsonError(new Error(`Unknown command: ${unknownCmd}`), 1));
+                }
+                else {
+                    console.error(`Error: Unknown command: ${unknownCmd}`);
+                    if (suggestion) {
+                        console.error(`\nDid you mean: mcpc ${session} ${suggestion}`);
+                    }
+                    console.error(`Run "mcpc ${session} --help" for available commands.\n`);
+                }
+                process.exit(1);
+            }
+        }
+        if (error instanceof CommanderError && error.code === 'commander.helpDisplayed') {
+            process.exit(0);
+        }
         if (isMcpError(error)) {
             if (outputMode === 'json') {
                 console.error(formatJsonError(error, error.code));
             }
             else {
-                console.error(chalk.red(formatHumanError(error, opts.verbose)));
+                console.error(theme.red(formatHumanError(error, opts.verbose)));
             }
             process.exit(error.code);
         }
         console.error(outputMode === 'json'
             ? formatJsonError(error, 1)
-            : chalk.red(formatHumanError(error, opts.verbose)));
+            : theme.red(formatHumanError(error, opts.verbose)));
         process.exit(1);
     }
 }