mcpbrowser 0.3.36 → 0.3.38

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.36",
+  "version": "0.3.38",
   "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

@@ -139,6 +139,11 @@ export const CLICK_ELEMENT_TOOL = {
         type: "array", 
         items: { type: "string" },
         description: "Suggested next actions"
+      },
+      recommendedPlugins: {
+        type: "array",
+        items: { type: "object" },
+        description: "Detected site-specific plugins available for this domain"
       }
     },
     required: ["status", "fallbackUsed", "nativeAttempt", "currentUrl", "message", "html", "nextSteps"],

package/src/actions/execute-javascript.js

@@ -81,7 +81,12 @@ export const EXECUTE_JAVASCRIPT_TOOL = {
       urlChanged: { type: 'boolean', description: 'True if page URL changed during execution' },
       currentUrl: { type: 'string', description: 'URL after execution' },
       nextSteps: { type: 'array', items: { type: 'string' } },
-      error: { type: ['object', 'null'], description: 'Error object when script throws or times out' }
+      error: { type: ['object', 'null'], description: 'Error object when script throws or times out' },
+      recommendedPlugins: {
+        type: 'array',
+        items: { type: 'object' },
+        description: 'Detected site-specific plugins available for this domain'
+      }
     },
     required: ['type', 'executionTimeMs', 'truncated', 'urlChanged', 'currentUrl', 'nextSteps'],
     additionalProperties: false

package/src/actions/fetch-page.js

@@ -91,6 +91,11 @@ export const FETCH_WEBPAGE_TOOL = {
         type: "array", 
         items: { type: "string" },
         description: "Suggested next actions"
+      },
+      recommendedPlugins: {
+        type: "array",
+        items: { type: "object" },
+        description: "Detected site-specific plugins available for this domain"
       }
     },
     required: ["currentUrl", "html", "nextSteps"],

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

@@ -83,6 +83,11 @@ export const GET_CURRENT_HTML_TOOL = {
         type: "array", 
         items: { type: "string" },
         description: "Suggested next actions"
+      },
+      recommendedPlugins: {
+        type: "array",
+        items: { type: "object" },
+        description: "Detected site-specific plugins available for this domain"
       }
     },
     required: ["currentUrl", "html", "nextSteps"],

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;
+}

package/src/cli/registry.js

@@ -0,0 +1,256 @@
+/**
+ * cli/registry.js — Single source of truth for all CLI commands.
+ *
+ * To add a new CLI command:
+ *   1. Import the MCP TOOL definition and action function
+ *   2. Add an entry to CLI_REGISTRY below
+ *   3. Done — help, routing, flag mapping, coercion all auto-update
+ */
+
+import { writeFileSync } from 'fs';
+
+import { fetchPage, FETCH_WEBPAGE_TOOL } from '../actions/fetch-page.js';
+import { clickElement, CLICK_ELEMENT_TOOL } from '../actions/click-element.js';
+import { typeText, TYPE_TEXT_TOOL } from '../actions/type-text.js';
+import { executeJavascript, EXECUTE_JAVASCRIPT_TOOL } from '../actions/execute-javascript.js';
+import { getCurrentHtml, GET_CURRENT_HTML_TOOL } from '../actions/get-current-html.js';
+import { takeScreenshot, TAKE_SCREENSHOT_TOOL } from '../actions/take-screenshot.js';
+import { scrollPage, SCROLL_PAGE_TOOL } from '../actions/scroll-page.js';
+import { navigateHistory, NAVIGATE_HISTORY_TOOL } from '../actions/navigate-history.js';
+import { closeTab, CLOSE_TAB_TOOL } from '../actions/close-tab.js';
+
+import { htmlToText, getStructured, getPrimaryText } from './utils.js';
+
+// ---------------------------------------------------------------------------
+// Factory for back/forward (deduplicated)
+// ---------------------------------------------------------------------------
+
+function makeHistoryCommand(direction) {
+  return {
+    cmd: direction,
+    tool: NAVIGATE_HISTORY_TOOL,
+    action: navigateHistory,
+    requiresFetch: true,
+    flagMap: { raw: '_raw' },
+    flagDefaults: {},
+    buildParams: (url, flags) => ({
+      url,
+      direction,
+      returnHtml: true,
+      removeUnnecessaryHTML: !flags.raw,
+    }),
+    formatOutput: (mcp, flags) => {
+      const s = getStructured(mcp);
+      const out = {};
+      if (s.previousUrl || s.currentUrl) {
+        out.stderr = `${s.previousUrl || '?'} → ${s.currentUrl || '?'}`;
+      }
+      if (s.html) out.stdout = flags.raw ? s.html : htmlToText(s.html);
+      return out;
+    },
+    examples: [`mcpbrowser ${direction} https://example.com`],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI_REGISTRY
+// ---------------------------------------------------------------------------
+
+export const CLI_REGISTRY = [
+  {
+    cmd: 'fetch',
+    tool: FETCH_WEBPAGE_TOOL,
+    action: fetchPage,
+    requiresFetch: false,
+    flagMap: { wait: 'postLoadWait', raw: '_raw' },
+    flagDefaults: {},
+    buildParams: (url, flags) => ({
+      url,
+      browser: flags.browser || '',
+      removeUnnecessaryHTML: !flags.raw,
+      postLoadWait: flags.wait ? Number(flags.wait) : 0
+    }),
+    formatOutput: (mcp, flags) => {
+      const html = getStructured(mcp).html || getPrimaryText(mcp);
+      return { stdout: flags.raw ? html : htmlToText(html) };
+    },
+    examples: [
+      'mcpbrowser fetch https://eng.ms/docs/my-page',
+      'mcpbrowser fetch https://portal.azure.com --browser edge --wait 5000',
+      'mcpbrowser fetch https://github.com --raw',
+    ],
+    cliNote: '--raw    Output full HTML instead of extracted text',
+  },
+
+  {
+    cmd: 'screenshot',
+    tool: TAKE_SCREENSHOT_TOOL,
+    action: takeScreenshot,
+    requiresFetch: true,
+    autoFetch: true, // screenshot auto-fetches the page first
+    flagMap: { 'full-page': 'fullPage' },
+    buildParams: (url, flags) => ({
+      url,
+      fullPage: !!flags['full-page']
+    }),
+    formatOutput: (mcp, flags) => {
+      const base64 = getStructured(mcp).screenshotBase64;
+      if (!base64) return { error: 'No screenshot data returned' };
+      const outFile = flags.output || 'screenshot.png';
+      writeFileSync(outFile, Buffer.from(base64, 'base64'));
+      return { stderr: `Screenshot saved to ${outFile}` };
+    },
+    examples: [
+      'mcpbrowser screenshot https://example.com --output page.png',
+      'mcpbrowser screenshot https://dashboard.corp.com --full-page',
+    ],
+    cliNote: '--output <path>    File path to save (default: screenshot.png)',
+  },
+
+  {
+    cmd: 'click',
+    tool: CLICK_ELEMENT_TOOL,
+    action: clickElement,
+    requiresFetch: true,
+    flagMap: {},
+    buildParams: (url, flags) => ({
+      url,
+      selector: flags.selector || undefined,
+      text: flags.text || undefined,
+      returnHtml: flags.returnHtml !== 'false',
+      removeUnnecessaryHTML: true,
+      postClickWait: flags.postClickWait ? Number(flags.postClickWait) : 1000,
+    }),
+    validate: (flags) => {
+      if (!flags.selector && !flags.text) return '--selector or --text is required for click';
+    },
+    formatOutput: (mcp) => {
+      const html = getStructured(mcp).html;
+      return { stdout: html ? htmlToText(html) : getPrimaryText(mcp) };
+    },
+    examples: [
+      'mcpbrowser click https://example.com --selector "#login-btn"',
+      'mcpbrowser click https://example.com --text "Sign In"',
+    ],
+  },
+
+  {
+    cmd: 'type',
+    tool: TYPE_TEXT_TOOL,
+    action: typeText,
+    requiresFetch: true,
+    flagMap: {},
+    buildParams: (url, flags) => ({
+      url,
+      fields: [{ selector: flags.selector, text: flags.text }],
+      returnHtml: false
+    }),
+    validate: (flags) => {
+      if (!flags.selector || !flags.text) return '--selector and --text are required for type';
+    },
+    formatOutput: (mcp) => ({ stdout: getPrimaryText(mcp) }),
+    examples: [
+      'mcpbrowser type https://example.com --selector "#search" --text "query"',
+      'mcpbrowser type https://login.com --selector "input[name=email]" --text "user@corp.com"',
+    ],
+    cliNote: 'CLI shorthand: --selector + --text fills a single field',
+  },
+
+  {
+    cmd: 'exec',
+    tool: EXECUTE_JAVASCRIPT_TOOL,
+    action: executeJavascript,
+    requiresFetch: true,
+    flagMap: {},
+    buildParams: (url, flags) => ({
+      url,
+      script: flags.script,
+      timeoutMs: flags.timeoutMs ? Number(flags.timeoutMs) : 30000,
+      returnType: flags.returnType || 'json',
+    }),
+    validate: (flags) => {
+      if (!flags.script) return '--script is required for exec';
+    },
+    formatOutput: (mcp) => {
+      const r = getStructured(mcp).result;
+      if (r !== undefined && r !== null) {
+        return { stdout: typeof r === 'string' ? r : JSON.stringify(r, null, 2) };
+      }
+      return { stdout: getPrimaryText(mcp) };
+    },
+    examples: [
+      'mcpbrowser exec https://example.com --script "document.title"',
+      'mcpbrowser exec https://mail.google.com --script "[...document.querySelectorAll(\'.zA\')].map(r=>r.textContent)"',
+    ],
+  },
+
+  {
+    cmd: 'html',
+    tool: GET_CURRENT_HTML_TOOL,
+    action: getCurrentHtml,
+    requiresFetch: true,
+    flagMap: { raw: '_raw' },
+    buildParams: (url, flags) => ({
+      url,
+      removeUnnecessaryHTML: !flags.raw,
+    }),
+    formatOutput: (mcp) => ({ stdout: getStructured(mcp).html || getPrimaryText(mcp) }),
+    examples: [
+      'mcpbrowser html https://example.com',
+      'mcpbrowser html https://example.com --raw',
+    ],
+    cliNote: '--raw    Output raw HTML without cleanup',
+  },
+
+  {
+    cmd: 'scroll',
+    tool: SCROLL_PAGE_TOOL,
+    action: scrollPage,
+    requiresFetch: true,
+    flagMap: {},
+    buildParams: (url, flags) => {
+      const params = { url };
+      if (flags.selector) { params.selector = flags.selector; }
+      else if (flags.x !== undefined || flags.y !== undefined) {
+        if (flags.x !== undefined) params.x = Number(flags.x);
+        if (flags.y !== undefined) params.y = Number(flags.y);
+      } else {
+        params.direction = flags.direction || 'down';
+        if (flags.amount) params.amount = Number(flags.amount);
+      }
+      return params;
+    },
+    formatOutput: (mcp) => {
+      const s = getStructured(mcp);
+      return {
+        stdout: JSON.stringify({
+          scrollX: s.scrollX, scrollY: s.scrollY,
+          pageWidth: s.pageWidth, pageHeight: s.pageHeight,
+          viewportWidth: s.viewportWidth, viewportHeight: s.viewportHeight
+        }, null, 2)
+      };
+    },
+    examples: [
+      'mcpbrowser scroll https://example.com --direction down --amount 1000',
+      'mcpbrowser scroll https://example.com --selector "#footer"',
+      'mcpbrowser scroll https://example.com --x 0 --y 0',
+    ],
+  },
+
+  makeHistoryCommand('back'),
+  makeHistoryCommand('forward'),
+
+  {
+    cmd: 'close',
+    tool: CLOSE_TAB_TOOL,
+    action: closeTab,
+    requiresFetch: false,
+    flagMap: {},
+    buildParams: (url) => ({ url }),
+    formatOutput: (mcp) => ({ stdout: getPrimaryText(mcp) }),
+    examples: ['mcpbrowser close https://example.com'],
+  },
+];
+
+// Lookup map for O(1) command resolution
+export const CMD_MAP = new Map(CLI_REGISTRY.map(entry => [entry.cmd, entry]));

package/src/cli/utils.js

@@ -0,0 +1,39 @@
+/**
+ * cli/utils.js — Shared utilities for CLI output formatting and safe data access.
+ */
+
+/**
+ * Convert HTML to readable terminal text (lossy preview).
+ */
+export function htmlToText(html) {
+  return html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/p>/gi, '\n\n')
+    .replace(/<\/div>/gi, '\n')
+    .replace(/<\/li>/gi, '\n')
+    .replace(/<\/h[1-6]>/gi, '\n\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * Safely get the primary text content from an MCP result.
+ * Falls back to empty string if content is missing.
+ */
+export function getPrimaryText(mcp) {
+  return mcp?.content?.[0]?.text ?? '';
+}
+
+/**
+ * Safely get structuredContent from an MCP result.
+ * Returns an empty object if missing, so callers can destructure safely.
+ */
+export function getStructured(mcp) {
+  return mcp?.structuredContent ?? {};
+}

package/src/core/responses.js

@@ -128,6 +128,23 @@ export class InformationalResponse extends MCPResponse {
     }
     return summary;
   }
+
+  /**
+   * Informational responses omit structuredContent to avoid schema violations.
+   * Their fields (message, reason, status) don't match tool-specific outputSchemas.
+   * @returns {Object} MCP-compliant response with text content only
+   */
+  toMcpFormat() {
+    return {
+      content: [
+        {
+          type: "text",
+          text: this.getTextSummary()
+        }
+      ],
+      isError: false
+    };
+  }
 }
 
 /**
@@ -272,6 +289,23 @@ export class HttpStatusResponse extends MCPResponse {
     }
     return summary;
   }
+
+  /**
+   * HTTP status responses omit structuredContent to avoid schema violations.
+   * Their fields (url, statusCode, etc.) don't match tool-specific outputSchemas.
+   * @returns {Object} MCP-compliant response with text content only
+   */
+  toMcpFormat() {
+    return {
+      content: [
+        {
+          type: "text",
+          text: this.getTextSummary()
+        }
+      ],
+      isError: false
+    };
+  }
 }
 
 /**

package/src/mcp-browser.js

@@ -12,6 +12,9 @@ import { fileURLToPath } from 'url';
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 
+// Import CLI mode
+import { isCliMode, runCli } from './cli/index.js';
+
 // Import response classes
 import { ErrorResponse } from './core/responses.js';
 import logger, { attachServer as attachLoggerServer } from './core/logger.js';
@@ -203,6 +206,9 @@ export {
   scrollPage,
   navigateHistory,
   handleAcceptEula,
+  // CLI exports
+  isCliMode,
+  runCli,
   // Plugin system exports
   loadPlugins,
   getLoadedPlugins,
@@ -216,8 +222,20 @@ export {
 // Run the MCP server only if this is the main module (not imported for testing)
 if (import.meta.url === new URL(process.argv[1], 'file://').href || 
     fileURLToPath(import.meta.url) === process.argv[1]) {
-  main().catch((err) => {
-    logger.error(`Server failed: ${err.message}`);
-    process.exit(1);
-  });
+  const argv = process.argv.slice(2);
+  if (isCliMode(argv)) {
+    // CLI mode: run command and exit
+    runCli(argv).then((code) => {
+      process.exit(code);
+    }).catch((err) => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exit(1);
+    });
+  } else {
+    // MCP server mode (default): stdin/stdout JSON-RPC
+    main().catch((err) => {
+      logger.error(`Server failed: ${err.message}`);
+      process.exit(1);
+    });
+  }
 }