mcpbrowser 0.3.35 → 0.3.37

package/README.md

@@ -38,6 +38,7 @@ Example workflow for AI assistant to use MCPBrowser
   - [scroll_page](#scroll_page)
   - [take_screenshot](#take_screenshot)
   - [close_tab](#close_tab)
+- [CLI Mode](#cli-mode)
 - [Configuration](#configuration-optional)
 - [Troubleshooting](#troubleshooting)
 - [Links](#links)
@@ -397,6 +398,38 @@ Closes the browser tab for the given URL's hostname. Removes the page from the t
 - Reset to fresh state before new login
 
 
+## CLI Mode
+
+MCPBrowser can also be used as a **standalone command-line tool**, making it easy to use from shell scripts, CI/CD pipelines, or AI agents that work through shell commands (like GitHub Copilot CLI).
+
+```bash
+# Show help
+mcpbrowser --help
+
+# Fetch a page (handles auth, SSO, SPAs automatically)
+mcpbrowser fetch https://eng.ms/docs/my-page
+
+# Fetch with raw HTML output
+mcpbrowser fetch https://github.com --browser chrome --raw
+
+# Take a screenshot
+mcpbrowser screenshot https://example.com --output page.png --full-page
+
+# Click an element on a loaded page
+mcpbrowser click https://example.com --selector "#login-btn"
+
+# Type into a form field
+mcpbrowser type https://example.com --selector "input[name=q]" --text "search query"
+
+# Execute JavaScript
+mcpbrowser exec https://example.com --script "document.title"
+
+# Get current HTML of a loaded page
+mcpbrowser html https://example.com
+```
+
+**CLI vs MCP mode:** When run without arguments, MCPBrowser starts as an MCP server (stdin/stdout JSON-RPC). When run with a subcommand, it executes the command and exits — no MCP protocol needed.
+
 
 ## Configuration (Optional)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.35",
+  "version": "0.3.37",
   "mcpName": "io.github.cherchyk/mcpbrowser",
   "type": "module",
   "description": "MCP browser server - fetch web pages using real Chrome/Edge/Brave browser. Handles authentication, SSO, CAPTCHAs, and anti-bot protection. Browser automation for AI assistants.",
@@ -12,6 +12,7 @@
     "mcp": "node src/mcp-browser.js",
     "test": "node tests/run-all.js",
     "test:unit": "node tests/run-unit.js",
+    "test:cli": "node tests/cli.test.js",
     "test:descriptions": "node tests/tool-selection/run-tool-selection-tests.js"
   },
   "keywords": [

package/src/actions/click-element.js

@@ -28,7 +28,7 @@ import { getBrowser, getValidatedPage } from '../core/browser.js';
 import { extractAndProcessHtml, waitForPageReady } from '../core/page.js';
 import { MCPResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
-import { getPluginNextSteps } from '../core/plugin-loader.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -38,7 +38,7 @@ import { getPluginNextSteps } from '../core/plugin-loader.js';
  * Structured response for click_element with JS fallback metadata
  */
 export class ClickWithFallbackResponse extends MCPResponse {
-  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [] }) {
+  constructor({ status, fallbackUsed = false, nativeAttempt, fallbackAttempt, postClickWait, currentUrl, html = null, message, nextSteps = [], recommendedPlugins = [] }) {
     super(nextSteps);
     this.status = status;
     this.fallbackUsed = fallbackUsed;
@@ -48,6 +48,7 @@ export class ClickWithFallbackResponse extends MCPResponse {
     this.currentUrl = currentUrl;
     this.html = html;
     this.message = message;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
@@ -59,7 +60,8 @@ export class ClickWithFallbackResponse extends MCPResponse {
       postClickWait: this.postClickWait,
       currentUrl: this.currentUrl,
       html: this.html,
-      message: this.message
+      message: this.message,
+      recommendedPlugins: this.recommendedPlugins
     };
   }
 
@@ -329,12 +331,12 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
 
     const nextSteps = returnHtml
       ? [
+          ...(html ? getPluginNextSteps(currentUrl, html) : []),
           "Use MCPBrowser's click_element again to navigate further",
           "Use MCPBrowser's type_text to fill forms if needed",
           "Use MCPBrowser's get_current_html to refresh page state",
           "Use MCPBrowser's take_screenshot if page has popups or visual content that's hard to parse from HTML",
-          "Use MCPBrowser's close_tab when finished",
-          ...(html ? getPluginNextSteps(currentUrl, html) : [])
+          "Use MCPBrowser's close_tab when finished"
         ]
       : [
           "Use MCPBrowser's get_current_html to see updated page state",
@@ -354,7 +356,8 @@ export async function clickElement({ url, selector, text, waitForElementTimeout
       currentUrl,
       html,
       message,
-      nextSteps
+      nextSteps,
+      recommendedPlugins: html ? getRecommendedPlugins(currentUrl, html) : []
     });
   } catch (err) {
     logger.error(`click_element failed: ${err.message}`);

package/src/actions/execute-javascript.js

@@ -7,7 +7,7 @@ import { waitForPageReady } from '../core/page.js';
 import { MCPResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
 import { serializeExecutionResult } from '../utils.js';
-import { getPluginNextSteps } from '../core/plugin-loader.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 // Shared execution defaults for script actions
 export const EXECUTION_TIMEOUT_DEFAULT_MS = 30_000;
@@ -22,7 +22,7 @@ export const EXECUTION_RESULT_MAX_BYTES = 100_000;
  * Structured response for execute_javascript action
  */
 export class ExecuteJavascriptResponse extends MCPResponse {
-  constructor({ result, type, executionTimeMs, truncated = false, urlChanged = false, currentUrl = '', error = null, nextSteps = [] }) {
+  constructor({ result, type, executionTimeMs, truncated = false, urlChanged = false, currentUrl = '', error = null, nextSteps = [], recommendedPlugins = [] }) {
     super(nextSteps);
 
     this.result = result;
@@ -32,6 +32,7 @@ export class ExecuteJavascriptResponse extends MCPResponse {
     this.urlChanged = urlChanged;
     this.currentUrl = currentUrl;
     this.error = error;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
@@ -42,7 +43,8 @@ export class ExecuteJavascriptResponse extends MCPResponse {
       truncated: this.truncated,
       urlChanged: this.urlChanged,
       currentUrl: this.currentUrl,
-      error: this.error || undefined
+      error: this.error || undefined,
+      recommendedPlugins: this.recommendedPlugins
     };
   }
 
@@ -224,11 +226,12 @@ export async function executeJavascript({ url, script, timeoutMs = EXECUTION_TIM
     urlChanged,
     currentUrl,
     nextSteps: [
+      ...getPluginNextSteps(currentUrl, ''),
       'Use click_element or type_text for follow-up actions',
       'Inspect urlChanged to decide if navigation occurred',
-      serialization.truncated ? 'Narrow your selector or reduce returned fields to avoid truncation' : 'Proceed with the returned data',
-      ...getPluginNextSteps(currentUrl, '')
-    ]
+      serialization.truncated ? 'Narrow your selector or reduce returned fields to avoid truncation' : 'Proceed with the returned data'
+    ],
+    recommendedPlugins: getRecommendedPlugins(currentUrl, '')
   });
 }
 

package/src/actions/fetch-page.js

@@ -8,7 +8,7 @@ import { getOrCreatePage, queueRequest, navigateToUrl, waitForPageReady, extract
 import { isLikelyAuthUrl, waitForAuth } from '../core/auth.js';
 import { MCPResponse, ErrorResponse, HttpStatusResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
-import { getPluginNextSteps } from '../core/plugin-loader.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -26,8 +26,9 @@ export class FetchPageSuccessResponse extends MCPResponse {
    * @param {string} currentUrl - Final URL after redirects
    * @param {string} html - Page HTML content
    * @param {string[]} nextSteps - Suggested next actions
+   * @param {Array} [recommendedPlugins] - Detected plugin metadata
    */
-  constructor(currentUrl, html, nextSteps) {
+  constructor(currentUrl, html, nextSteps, recommendedPlugins = []) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -39,12 +40,14 @@ export class FetchPageSuccessResponse extends MCPResponse {
     
     this.currentUrl = currentUrl;
     this.html = html;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
     return {
       currentUrl: this.currentUrl,
-      html: this.html
+      html: this.html,
+      recommendedPlugins: this.recommendedPlugins
     };
   }
 
@@ -221,13 +224,14 @@ async function doFetchPage({ url, browser, removeUnnecessaryHTML, postLoadWait }
       page.url(),
       processedHtml,
       [
+        ...getPluginNextSteps(page.url(), processedHtml),
         "Use MCPBrowser's click_element to interact with buttons/links on the page",
         "Use MCPBrowser's type_text to fill in form fields",
         "Use MCPBrowser's get_current_html to re-check page state after interactions",
         "Use MCPBrowser's take_screenshot if page has charts, images, or complex visual layout that's hard to understand from HTML",
-        "Use MCPBrowser's close_tab when finished to free browser resources",
-        ...getPluginNextSteps(page.url(), processedHtml)
-      ]
+        "Use MCPBrowser's close_tab when finished to free browser resources"
+      ],
+      getRecommendedPlugins(page.url(), processedHtml)
     );
   } catch (err) {
     logger.error(`fetch_webpage failed: ${err.message || String(err)}`);

package/src/actions/get-current-html.js

@@ -6,7 +6,7 @@ import { getBrowser, getValidatedPage } from '../core/browser.js';
 import { extractAndProcessHtml } from '../core/page.js';
 import { MCPResponse, InformationalResponse } from '../core/responses.js';
 import logger from '../core/logger.js';
-import { getPluginNextSteps } from '../core/plugin-loader.js';
+import { getPluginNextSteps, getRecommendedPlugins } from '../core/plugin-loader.js';
 
 /**
  * @typedef {import('@modelcontextprotocol/sdk/types.js').Tool} Tool
@@ -24,8 +24,9 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
    * @param {string} currentUrl - Current page URL
    * @param {string} html - Page HTML content
    * @param {string[]} nextSteps - Suggested next actions
+   * @param {Array} [recommendedPlugins] - Detected plugin metadata
    */
-  constructor(currentUrl, html, nextSteps) {
+  constructor(currentUrl, html, nextSteps, recommendedPlugins = []) {
     super(nextSteps);
     
     if (typeof currentUrl !== 'string') {
@@ -37,12 +38,14 @@ export class GetCurrentHtmlSuccessResponse extends MCPResponse {
     
     this.currentUrl = currentUrl;
     this.html = html;
+    this.recommendedPlugins = recommendedPlugins;
   }
 
   _getAdditionalFields() {
     return {
       currentUrl: this.currentUrl,
-      html: this.html
+      html: this.html,
+      recommendedPlugins: this.recommendedPlugins
     };
   }
 
@@ -158,12 +161,13 @@ export async function getCurrentHtml({ url, removeUnnecessaryHTML = true }) {
       currentUrl,
       html,
       [
+        ...getPluginNextSteps(currentUrl, html),
         "Use MCPBrowser's click_element to interact with elements",
         "Use MCPBrowser's type_text to fill forms",
         "Use MCPBrowser's take_screenshot if page layout or visual content is hard to understand from HTML",
-        "Use MCPBrowser's close_tab to free resources when done",
-        ...getPluginNextSteps(currentUrl, html)
-      ]
+        "Use MCPBrowser's close_tab to free resources when done"
+      ],
+      getRecommendedPlugins(currentUrl, html)
     );
   } catch (err) {
     logger.error(`get_current_html failed: ${err.message}`);

package/src/cli/args.js

@@ -0,0 +1,81 @@
+/**
+ * cli/args.js — Argument parsing and schema-driven flag coercion.
+ */
+
+/**
+ * Parse CLI argv into { command, positional, flags }.
+ * Supports --flag value, --flag=value, --flag (boolean), -h, -v.
+ */
+export function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  let command = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      flags.version = true;
+    } else if (arg.startsWith('--')) {
+      const eqIdx = arg.indexOf('=');
+      if (eqIdx !== -1) {
+        // --flag=value
+        flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+      } else {
+        const key = arg.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+          flags[key] = next;
+          i++;
+        } else {
+          flags[key] = true;
+        }
+      }
+    } else if (!command) {
+      command = arg;
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { command, positional, flags };
+}
+
+/**
+ * Coerce flag values to correct types using MCP tool inputSchema.
+ * Returns { coerced, errors } where errors is an array of validation messages.
+ */
+export function coerceFlags(flags, tool, flagMap = {}) {
+  const props = tool?.inputSchema?.properties || {};
+  const coerced = { ...flags };
+  const errors = [];
+
+  // Build reverse map: CLI flag → MCP param name
+  const reverseMap = {};
+  for (const [cliFlag, mcpParam] of Object.entries(flagMap)) {
+    if (!mcpParam.startsWith('_')) reverseMap[cliFlag] = mcpParam;
+  }
+
+  for (const [key, value] of Object.entries(coerced)) {
+    // Skip built-in flags
+    if (key === 'help' || key === 'version' || key === 'json' || key === 'output') continue;
+
+    const mcpParam = reverseMap[key] || key;
+    const schema = props[mcpParam];
+    if (!schema) continue; // unknown flag — leave as-is
+
+    if (schema.type === 'number' && typeof value === 'string') {
+      const n = Number(value);
+      if (Number.isNaN(n)) {
+        errors.push(`--${key} must be a number, got '${value}'`);
+      } else {
+        coerced[key] = n;
+      }
+    } else if (schema.type === 'boolean' && typeof value === 'string') {
+      coerced[key] = value !== 'false' && value !== '0';
+    }
+  }
+
+  return { coerced, errors };
+}

package/src/cli/help.js

@@ -0,0 +1,169 @@
+/**
+ * cli/help.js — Auto-generated help from CLI_REGISTRY + MCP tool schemas.
+ */
+
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+import { CLI_REGISTRY } from './registry.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function getVersion() {
+  return JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8')).version;
+}
+
+/**
+ * Format inputSchema properties into CLI option lines.
+ * Skips 'url' (positional) and internal-only params.
+ */
+function formatSchemaOptions(tool, entry) {
+  const props = tool.inputSchema?.properties || {};
+  const required = new Set(tool.inputSchema?.required || []);
+  const reverseMap = {};
+  for (const [cliFlag, mcpParam] of Object.entries(entry.flagMap || {})) {
+    if (!mcpParam.startsWith('_')) reverseMap[mcpParam] = cliFlag;
+  }
+
+  const lines = [];
+  for (const [name, schema] of Object.entries(props)) {
+    if (name === 'url') continue;
+
+    const cliName = reverseMap[name] || name;
+    let typeHint = '';
+    if (schema.enum) {
+      typeHint = `<${schema.enum.filter(Boolean).join('|')}>`;
+    } else if (schema.type === 'string') {
+      typeHint = `<${cliName}>`;
+    } else if (schema.type === 'number') {
+      typeHint = '<n>';
+    } else if (schema.type === 'boolean') {
+      typeHint = '';
+    } else if (schema.type === 'array' && schema.items?.properties) {
+      lines.push(`    --${cliName}  (structured — see MCP schema)`);
+      const itemReq = new Set(schema.items.required || []);
+      for (const [iName, iProp] of Object.entries(schema.items.properties)) {
+        const ir = itemReq.has(iName) ? ' (required)' : '';
+        const id = iProp.default !== undefined ? `  [default: ${iProp.default}]` : '';
+        lines.push(`      .${iName} (${iProp.type})${ir}${id} — ${iProp.description || ''}`);
+      }
+      continue;
+    }
+
+    const defVal = schema.default !== undefined ? `  [default: ${schema.default}]` : '';
+    const req = required.has(name) ? '  (required)' : '';
+    const desc = schema.description || '';
+    const shortDesc = desc.length > 80 ? desc.slice(0, 77) + '...' : desc;
+    lines.push(`    --${cliName} ${typeHint}${req}${defVal}  ${shortDesc}`);
+  }
+  return lines;
+}
+
+/**
+ * Format outputSchema into a compact output description.
+ */
+function formatSchemaOutput(tool) {
+  const props = tool.outputSchema?.properties || {};
+  const lines = [];
+  for (const [name, prop] of Object.entries(props)) {
+    let t = prop.type || 'any';
+    if (Array.isArray(t)) t = t.filter(x => x !== 'null').join('|');
+    if (t === 'array') t = `array<${prop.items?.type || 'any'}>`;
+    if (t === 'object' && !prop.description) continue;
+    lines.push(`    ${name} (${t})${prop.description ? ' — ' + prop.description : ''}`);
+  }
+  return lines;
+}
+
+export function printHelp() {
+  const version = getVersion();
+  const o = (s) => process.stdout.write(s + '\n');
+
+  o(`MCPBrowser v${version} — Browser automation for AI agents and CLI`);
+  o('');
+  o('USAGE');
+  o('  mcpbrowser                              Start MCP server (stdin/stdout)');
+  o('  mcpbrowser <command> <url> [options]     Run a CLI command and exit');
+  o('  mcpbrowser -h | --help                  Show this help');
+  o('  mcpbrowser -v | --version               Show version');
+  o('');
+  o('GLOBAL FLAGS');
+  o('  --json     Output raw MCP result as JSON (for agent/programmatic use)');
+  o('');
+  o('WORKFLOW');
+  o('  fetch  ──▶  click / type / exec / scroll  ──▶  html  ──▶  close');
+  o('  (load)      (interact)                         (read)      (cleanup)');
+  o('');
+  o('  Start with "fetch" to load a page, then interact. The browser keeps tabs');
+  o('  open between commands. Auth, SSO, CAPTCHAs are handled automatically.');
+  o('');
+  o('BROWSERS');
+  o('  chrome, edge, brave — auto-detected, or set with --browser');
+  o('  Uses your real browser profile (existing logins/cookies available).');
+  o('');
+  o('━'.repeat(70));
+  o('COMMANDS');
+  o('━'.repeat(70));
+
+  for (const entry of CLI_REGISTRY) {
+    o('');
+    const depTag = entry.requiresFetch ? '  [requires: fetch]' : '';
+    const desc = (entry.tool.description || '')
+      .replace(/\*\*/g, '')
+      .replace(/\\n/g, ' ')
+      .split('\n')[0];
+
+    o(`${entry.cmd} <url> [options]${depTag}`);
+    o(`  ${desc}`);
+    o('');
+
+    const schemaOpts = formatSchemaOptions(entry.tool, entry);
+    if (schemaOpts.length > 0 || entry.cliNote) {
+      o('  Options:');
+      for (const line of schemaOpts) o(line);
+      if (entry.cliNote) o(`    ${entry.cliNote}`);
+      o('');
+    }
+
+    const outFields = formatSchemaOutput(entry.tool);
+    if (outFields.length > 0) {
+      o('  Output fields:');
+      for (const line of outFields) o(line);
+      o('');
+    }
+
+    if (entry.examples?.length) {
+      o('  Examples:');
+      for (const ex of entry.examples) o(`    ${ex}`);
+    }
+  }
+
+  o('');
+  o('━'.repeat(70));
+  o('MULTI-STEP EXAMPLE');
+  o('━'.repeat(70));
+  o('');
+  o('  mcpbrowser fetch https://app.example.com/login');
+  o('  mcpbrowser type  https://app.example.com/login --selector "#email" --text "me@corp.com"');
+  o('  mcpbrowser type  https://app.example.com/login --selector "#password" --text "secret"');
+  o('  mcpbrowser click https://app.example.com/login --text "Sign In"');
+  o('  mcpbrowser html  https://app.example.com/dashboard');
+  o('  mcpbrowser screenshot https://app.example.com/dashboard --output dash.png');
+  o('  mcpbrowser close https://app.example.com');
+  o('');
+  o('  Use --json with any command for structured output:');
+  o('  mcpbrowser fetch https://example.com --json');
+  o('');
+
+  o('━'.repeat(70));
+  o('MCP SERVER MODE');
+  o('━'.repeat(70));
+  o('');
+  o('  No arguments → starts MCP server (stdin/stdout JSON-RPC).');
+  o('  CLI commands map 1:1 to MCP tools (fetch→fetch_webpage, etc.).');
+  o('');
+  o('  { "mcpServers": { "mcpbrowser": { "command": "npx", "args": ["-y", "mcpbrowser@latest"] } } }');
+  o('');
+}

package/src/cli/index.js

@@ -0,0 +1,130 @@
+/**
+ * cli/index.js — CLI entrypoint and generic command executor.
+ *
+ * Thin orchestration layer: parses args, coerces types, validates,
+ * dispatches to registry actions, and formats output.
+ */
+
+import { parseArgs, coerceFlags } from './args.js';
+import { CLI_REGISTRY, CMD_MAP } from './registry.js';
+import { getVersion, printHelp } from './help.js';
+import { getPrimaryText } from './utils.js';
+
+import { fetchPage } from '../actions/fetch-page.js';
+import { closeBrowser } from '../core/browser.js';
+import logger from '../core/logger.js';
+
+logger.setConsoleOutput(false);
+
+export function isCliMode(argv) {
+  return argv.length > 0;
+}
+
+/**
+ * Generic command executor — driven by CLI_REGISTRY entry.
+ */
+async function executeCommand(entry, url, flags) {
+  // Custom validation
+  if (entry.validate) {
+    const err = entry.validate(flags);
+    if (err) {
+      process.stderr.write(`Error: ${err}\n`);
+      return 1;
+    }
+  }
+
+  // Schema-driven type coercion
+  const { coerced, errors } = coerceFlags(flags, entry.tool, entry.flagMap);
+  if (errors.length > 0) {
+    for (const e of errors) process.stderr.write(`Error: ${e}\n`);
+    return 1;
+  }
+
+  // Build params
+  const params = entry.buildParams
+    ? entry.buildParams(url, coerced)
+    : { url, ...coerced };
+
+  // Call the MCP action
+  const result = await entry.action(params);
+  const mcp = result.toMcpFormat();
+
+  if (mcp.isError) {
+    process.stderr.write(`Error: ${getPrimaryText(mcp)}\n`);
+    return 1;
+  }
+
+  // --json: output raw MCP result
+  if (coerced.json) {
+    const jsonOut = {
+      content: mcp.content,
+      ...(mcp.structuredContent ? { structuredContent: mcp.structuredContent } : {})
+    };
+    process.stdout.write(JSON.stringify(jsonOut, null, 2) + '\n');
+    return 0;
+  }
+
+  // Formatted output
+  const output = entry.formatOutput
+    ? entry.formatOutput(mcp, coerced)
+    : { stdout: getPrimaryText(mcp) };
+
+  if (output.error) {
+    process.stderr.write(`Error: ${output.error}\n`);
+    return 1;
+  }
+  if (output.stderr) process.stderr.write(output.stderr + '\n');
+  if (output.stdout) process.stdout.write(output.stdout + '\n');
+
+  return 0;
+}
+
+/**
+ * Main CLI entry point.
+ */
+export async function runCli(argv) {
+  const { command, positional, flags } = parseArgs(argv);
+
+  if (flags.help) { printHelp(); return 0; }
+  if (flags.version) { process.stdout.write(getVersion() + '\n'); return 0; }
+  if (!command) { printHelp(); return 0; }
+
+  const entry = CMD_MAP.get(command);
+  if (!entry) {
+    process.stderr.write(`Unknown command: ${command}\n`);
+    process.stderr.write(`Available: ${[...CMD_MAP.keys()].join(', ')}\n`);
+    process.stderr.write('Run mcpbrowser --help for usage\n');
+    return 1;
+  }
+
+  const url = positional[0];
+  if (!url) {
+    process.stderr.write(`Error: <url> is required for '${command}'\n`);
+    process.stderr.write(`Usage: mcpbrowser ${command} <url> [options]\n`);
+    return 1;
+  }
+
+  let exitCode = 1;
+  try {
+    // Auto-fetch for commands that declare it (e.g. screenshot)
+    if (entry.autoFetch) {
+      const fetchResult = await fetchPage({ url, browser: flags.browser || '', removeUnnecessaryHTML: true });
+      const fetchMcp = fetchResult.toMcpFormat();
+      if (fetchMcp.isError) {
+        process.stderr.write(`Error loading page: ${getPrimaryText(fetchMcp)}\n`);
+        return 1;
+      }
+      const actualUrl = fetchMcp.structuredContent?.currentUrl || url;
+      exitCode = await executeCommand(entry, actualUrl, flags);
+    } else {
+      exitCode = await executeCommand(entry, url, flags);
+    }
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    exitCode = 1;
+  } finally {
+    try { await closeBrowser(); } catch { /* ignore */ }
+  }
+
+  return exitCode;
+}