chrome-bridge-mcp 1.8.0

package/extension/stack-detect.js

@@ -0,0 +1,54 @@
+/**
+ * Euristiche leggere di stack detection, eseguite in MAIN world sulla tab
+ * attiva quando l'utente apre il popup. Nessuna libreria esterna: solo
+ * global note e indizi DOM. Best-effort dichiarato: un framework ben
+ * nascosto (build minificata senza global) non viene rilevato.
+ *
+ * Nel browser il file viene iniettato via chrome.scripting.executeScript
+ * e deposita il risultato in window.__chromeBridge_stackDetect; nei unit
+ * test Node si importa per side effect e si usa globalThis.__cbStackDetect.
+ */
+(() => {
+  function detectStack(win, doc) {
+    const found = [];
+    const add = (name) => { if (!found.includes(name)) found.push(name); };
+
+    if (win.__REACT_DEVTOOLS_GLOBAL_HOOK__ || win.React) add('React');
+    if (win.__NEXT_DATA__) add('Next.js');
+    if (win.Vue || win.__VUE__) add('Vue');
+    if (win.__NUXT__) add('Nuxt');
+    if (win.ng || win.getAllAngularRootElements) add('Angular');
+    if (win.__svelte || win.__SVELTE_HMR__) add('Svelte');
+    if (win.Alpine) add('Alpine.js');
+    if (win.jQuery || win.$?.fn?.jquery) add('jQuery');
+    if (win.wp || win.wpApiSettings) add('WordPress');
+    if (win.prestashop) add('PrestaShop');
+    if (win.Shopify) add('Shopify');
+
+    const gen = doc.querySelector('meta[name="generator"]');
+    const genText = (gen && gen.content) || '';
+    for (const [needle, name] of [
+      ['WordPress', 'WordPress'], ['PrestaShop', 'PrestaShop'],
+      ['Joomla', 'Joomla'], ['Drupal', 'Drupal'], ['Hugo', 'Hugo'],
+      ['Gatsby', 'Gatsby'], ['Astro', 'Astro'],
+    ]) {
+      if (genText.includes(needle)) add(name);
+    }
+
+    for (const s of doc.querySelectorAll('script[src]')) {
+      const src = s.src || '';
+      if (src.includes('/@vite/')) add('Vite');
+      if (src.includes('webpack')) add('webpack');
+      if (src.includes('cdn.tailwindcss.com')) add('Tailwind');
+    }
+
+    return found;
+  }
+
+  globalThis.__cbStackDetect = { detectStack };
+
+  // Esecuzione come content script: deposita il risultato per il service worker
+  if (typeof window !== 'undefined' && typeof document !== 'undefined' && window.document === document) {
+    try { window.__chromeBridge_stackDetect = detectStack(window, document); } catch {}
+  }
+})();

package/extension/telemetry.js

@@ -0,0 +1,29 @@
+/**
+ * Funzioni pure per la telemetria del popup: ring buffer degli errori
+ * recenti e report diagnostico copiabile. Nessuna API chrome.* qui:
+ * il file è importato sia dal service worker sia dai unit test Node
+ * (side-effect import, export su globalThis).
+ */
+(() => {
+  function pushError(buf, entry, max = 5) {
+    const next = buf.concat([entry]);
+    return next.length > max ? next.slice(next.length - max) : next;
+  }
+
+  function buildDiagnostics(d) {
+    return JSON.stringify({
+      extension: d.extensionVersion,
+      server: d.serverVersion || 'unknown',
+      chrome: d.chromeVersion,
+      state: d.state,
+      port: d.port,
+      userScripts: d.userScriptsEnabled,
+      instrument: d.instrument,
+      toolCalls: d.toolCallCount,
+      lastTool: d.lastTool,
+      recentErrors: d.recentErrors,
+    }, null, 2);
+  }
+
+  globalThis.__cbTelemetry = { pushError, buildDiagnostics };
+})();

package/install.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SERVER_ENTRY="$SCRIPT_DIR/server/index.js"
+
+echo "=== Chrome Bridge Installer ==="
+echo ""
+
+# 1. Check Node.js
+if ! command -v node &>/dev/null; then
+  echo "ERROR: Node.js is required but not installed."
+  echo "Install it from https://nodejs.org/ or via your package manager."
+  exit 1
+fi
+echo "[OK] Node.js $(node -v)"
+
+# 2. Install npm dependencies
+echo ""
+echo "Installing dependencies..."
+cd "$SCRIPT_DIR"
+npm install --silent
+echo "[OK] Dependencies installed"
+
+# 3. Register MCP server in Claude Code
+echo ""
+if command -v claude &>/dev/null; then
+  echo "Registering MCP server in Claude Code..."
+  # -e CHROME_BRIDGE_CAPS=all: senza questo il default e caps=core (30 tool su 59)
+  # e chi installa non ha extract_table/audits, che i doc promettono.
+  claude mcp add --scope user chrome-bridge -e CHROME_BRIDGE_CAPS=all -- node "$SERVER_ENTRY" 2>/dev/null && \
+    echo "[OK] MCP server registered (scope: user, all 59 tools)" || \
+    echo "[SKIP] MCP server already registered or claude command failed"
+else
+  echo "[SKIP] 'claude' CLI not found. Register manually:"
+  echo "  claude mcp add --scope user chrome-bridge node $SERVER_ENTRY"
+fi
+
+# 4. Preflight: porta e piattaforma
+echo ""
+if command -v ss &>/dev/null && ss -ltn 2>/dev/null | grep -q ':8765 '; then
+  echo "[NOTE] Port 8765 is already in use — a second chrome-bridge starts as a relay"
+  echo "       and shares the existing bridge. Set CHROME_BRIDGE_PORT to change it."
+fi
+
+# 5. Chrome extension instructions
+echo ""
+echo "=== Chrome Extension Setup ==="
+echo ""
+if [ "$(hostname)" = "penguin" ]; then
+  # Su ChromeOS/Crostini un'estensione caricata da filesystem viene scartata a
+  # ogni reboot: il container non e montato quando Chrome parte.
+  echo "  ChromeOS/Crostini detected — install from the Chrome Web Store instead"
+  echo "  of Load unpacked (a filesystem-loaded extension is dropped on reboot):"
+  echo "  https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb"
+else
+  echo "  1. Open chrome://extensions in Chrome"
+  echo "  2. Enable 'Developer mode' (top right toggle)"
+  echo "  3. Click 'Load unpacked'"
+  echo "  4. Select: $SCRIPT_DIR/extension"
+fi
+echo ""
+echo "  Then enable 'Allow user scripts' in the extension Details page"
+echo "  (needed by execute_js and wait_for(condition=function))."
+echo ""
+echo "=== Done ==="
+echo ""
+echo "After loading the extension, restart Claude Code."
+echo "The extension popup shows connection status."
+echo "Test with: node $SCRIPT_DIR/test/test-devtools.js"

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "chrome-bridge-mcp",
+  "mcpName": "io.github.frsorrentino/chrome-bridge",
+  "version": "1.8.0",
+  "type": "module",
+  "description": "MCP server with 59 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
+  "main": "server/index.js",
+  "bin": {
+    "chrome-bridge-mcp": "server/index.js",
+    "chrome-bridge": "server/cli.js"
+  },
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "node --test test/unit/*.test.js",
+    "test:unit": "node --test test/unit/*.test.js",
+    "test:e2e": "node test/test-devtools.js",
+    "measure": "node tools/measure-schema.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "chrome",
+    "browser-automation",
+    "claude-code",
+    "chromeos",
+    "crostini",
+    "devtools",
+    "websocket",
+    "chrome-extension",
+    "accessibility",
+    "testing"
+  ],
+  "author": "frsorrentino",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frsorrentino/chrome-bridge.git"
+  },
+  "homepage": "https://github.com/frsorrentino/chrome-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/frsorrentino/chrome-bridge/issues"
+  },
+  "files": [
+    "server/",
+    "tools/",
+    "extension/",
+    "install.sh",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "node-html-parser": "^9.0.0",
+    "ws": "^8.18.0"
+  }
+}

package/server/assertions.js

@@ -0,0 +1,81 @@
+/**
+ * Assertion su condizioni di pagina, con polling fino a timeout.
+ * Condivisa tra tool MCP (tools.js) e CLI/replay (cli.js): stessa semantica
+ * nei flussi interattivi e nei replay registrati.
+ */
+
+import { MessageType } from './protocol.js';
+
+/** Pattern: "/.../" = regex, altrimenti substring. */
+export function matchPattern(value, pattern) {
+  const s = String(value ?? '');
+  if (typeof pattern === 'string' && pattern.length > 2 && pattern.startsWith('/') && pattern.endsWith('/')) {
+    return new RegExp(pattern.slice(1, -1)).test(s);
+  }
+  return s.includes(String(pattern));
+}
+
+/**
+ * Valuta le condizioni una volta. Ritorna array di failure (vuoto = passed).
+ *
+ * @param {(type: string, params?: object) => Promise<object>} send
+ * @param {object} p - parametri assert (selector, state, text, count, url, title, tab_id)
+ */
+async function evaluate(send, p) {
+  const failures = [];
+
+  if (p.url != null || p.title != null) {
+    const tabs = await send(MessageType.GET_TABS, {});
+    const list = Array.isArray(tabs) ? tabs : [];
+    const tab = p.tab_id != null ? list.find((t) => t.id === p.tab_id) : list.find((t) => t.active);
+    if (!tab) {
+      failures.push(`tab ${p.tab_id ?? '(active)'} not found`);
+    } else {
+      if (p.url != null && !matchPattern(tab.url, p.url)) failures.push(`url "${tab.url}" does not match "${p.url}"`);
+      if (p.title != null && !matchPattern(tab.title, p.title)) failures.push(`title "${tab.title}" does not match "${p.title}"`);
+    }
+  }
+
+  if (p.selector != null) {
+    // limit: per count esatto serve vedere se esistono match oltre l'atteso
+    const limit = p.count != null ? p.count + 1 : (p.text != null || p.state === 'visible' ? 10 : 1);
+    const data = await send(MessageType.QUERY_DOM, { selector: p.selector, limit, tab_id: p.tab_id });
+    const els = data?.elements ?? [];
+    if (p.count != null) {
+      if (els.length !== p.count) failures.push(`count ${els.length >= limit ? `>=${limit}` : els.length} != ${p.count} for "${p.selector}"`);
+    } else if (els.length === 0) {
+      failures.push(`no element matches "${p.selector}"`);
+    }
+    if (p.state === 'visible' && els.length && !els.some((e) => e.rect?.width > 0 && e.rect?.height > 0)) {
+      failures.push(`"${p.selector}" matched but not visible`);
+    }
+    if (p.text != null && els.length && !els.some((e) => matchPattern(e.textContent, p.text))) {
+      failures.push(`text "${p.text}" not found in "${p.selector}"`);
+    }
+  } else if (p.text != null) {
+    // Pagina intera: find_text è substring-only, niente regex
+    const data = await send(MessageType.FIND_TEXT, { text: p.text, max_results: 1, tab_id: p.tab_id });
+    if ((data?.count ?? 0) === 0) failures.push(`text "${p.text}" not found on page`);
+  }
+
+  return failures;
+}
+
+/**
+ * Esegue l'assert con retry fino a timeout. Ritorna { passed: true, waited_ms }
+ * o lancia Error col dettaglio dell'ultima valutazione fallita.
+ */
+export async function runAssert(send, params) {
+  const { timeout = 5000, interval = 300 } = params;
+  if (params.selector == null && params.text == null && params.url == null && params.title == null) {
+    throw new Error('assert requires at least one of: selector, text, url, title');
+  }
+  const start = Date.now();
+  const deadline = start + timeout;
+  for (;;) {
+    const failures = await evaluate(send, params);
+    if (!failures.length) return { passed: true, waited_ms: Date.now() - start };
+    if (Date.now() >= deadline) throw new Error(`Assertion failed after ${timeout}ms: ${failures.join('; ')}`);
+    await new Promise((r) => setTimeout(r, interval));
+  }
+}

package/server/cli.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+
+/**
+ * CLI di chrome-bridge: stessi comandi dei tool MCP, via Bash.
+ *
+ * Si connette come client relay al server WebSocket già attivo (mai come
+ * primary: processo breve, non deve contendere la porta all'istanza MCP).
+ * Pensata per batch e output filtrabili con pipe:
+ *
+ *   chrome-bridge tabs
+ *   chrome-bridge read_console --tab-id 42 | grep -i error | head -5
+ *   chrome-bridge js --code 'document.title'
+ *   chrome-bridge screenshot --out /tmp/shot.png
+ */
+
+import WebSocket from 'ws';
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DEFAULT_PORT, MessageType, createCommand, getTimeout } from './protocol.js';
+import { consoleLines, networkLines, interactivesLines, linksLines } from './formatters.js';
+import { runAssert } from './assertions.js';
+import { checkLinksBatch } from './link-checker.js';
+import { evaluateSecurityHeaders } from './security-headers.js';
+import { toHar } from './har.js';
+
+const INTERNAL_TYPES = new Set([
+  MessageType.RESULT, MessageType.ERROR, MessageType.PING, MessageType.PONG,
+  MessageType.EXT_INIT, MessageType.RELAY_INIT,
+]);
+
+// Comandi virtuali: logica lato CLI (come i corrispondenti tool MCP lato server)
+const VIRTUAL_COMMANDS = new Set(['status', 'check_links', 'security_headers', 'replay', 'assert']);
+
+const ALIASES = { tabs: 'get_tabs', js: 'execute_js', console: 'read_console', network: 'monitor_network', interactives: 'get_interactives' };
+
+const VALID_COMMANDS = new Set([
+  ...Object.values(MessageType).filter((t) => !INTERNAL_TYPES.has(t)),
+  ...VIRTUAL_COMMANDS,
+]);
+
+// Opzioni consumate dalla CLI, mai inoltrate all'estensione
+const CLI_OPTS = new Set(['out', 'format', 'max_chars']);
+
+// La coercizione numerica cieca corrompeva i valori testuali: `--text 00185`
+// diventava 185 (CAP, prefissi telefonici, codici con zeri iniziali digitati
+// sbagliati in silenzio) e `--code 42` diventava un numero invece di sorgente
+// JS. Solo le chiavi che sono davvero numeriche/booleane vengono convertite.
+const NUMERIC_KEYS = new Set([
+  'tab_id', 'frame_id', 'limit', 'timeout', 'interval', 'max_length', 'max_chars',
+  'max_rows', 'max_items', 'max_scrolls', 'max_segments', 'segment_offset', 'max_selectors',
+  'delay', 'offset', 'scan_rows', 'width', 'height', 'x', 'y', 'level_num',
+  'status', 'zoom', 'depth', 'count', 'index', 'port', 'threshold', 'scale',
+  'latitude', 'longitude', 'accuracy', 'step_px', 'settle_ms', 'repeat',
+]);
+const BOOLEAN_KEYS = new Set([
+  'clear', 'stop', 'force', 'visible', 'visible_only', 'stitch', 'reset',
+  'attributes', 'childList', 'characterData', 'subtree', 'print_mode',
+  'include_cross_origin', 'headless', 'active', 'submit', 'accept', 'include_rect',
+]);
+
+function coerce(raw, key) {
+  if (BOOLEAN_KEYS.has(key)) {
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+  }
+  if (NUMERIC_KEYS.has(key) && /^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+  // Chiavi non dichiarate: true/false restano booleani (comodo per i flag noti
+  // dei tool), tutto il resto resta stringa.
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  return raw;
+}
+
+export function parseCliArgs(argv) {
+  const [cmdRaw, ...rest] = argv;
+  if (!cmdRaw) throw new Error('Unknown command: (none). Run with --help.');
+  const command = ALIASES[cmdRaw] ?? cmdRaw;
+  if (!VALID_COMMANDS.has(command)) throw new Error(`Unknown command: ${cmdRaw}. Run with --help.`);
+
+  const params = {};
+  const opts = {};
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (!arg.startsWith('--')) throw new Error(`Unexpected argument: ${arg} (flags are --key value)`);
+    const key = arg.slice(2).replaceAll('-', '_');
+    let value = true;
+    if (i + 1 < rest.length && !rest[i + 1].startsWith('--')) {
+      value = coerce(rest[++i], key);
+    }
+    if (key === 'json') {
+      Object.assign(params, JSON.parse(value));
+    } else if (CLI_OPTS.has(key)) {
+      opts[key] = value;
+    } else {
+      params[key] = value;
+    }
+  }
+  return { command, params, opts };
+}
+
+// ─── Connessione relay ───────────────────────────────────────────
+
+function connect(port) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    const pending = new Map();
+
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ type: MessageType.RELAY_INIT }));
+      resolve({
+        sendCommand(type, params = {}) {
+          return new Promise((res, rej) => {
+            const command = createCommand(type, params);
+            const timer = setTimeout(() => {
+              pending.delete(command.id);
+              rej(new Error(`Command ${type} timed out after ${getTimeout(type)}ms`));
+            }, getTimeout(type));
+            pending.set(command.id, { res, rej, timer });
+            ws.send(JSON.stringify(command));
+          });
+        },
+        close: () => ws.close(),
+      });
+    });
+
+    ws.on('message', (raw) => {
+      let msg;
+      try { msg = JSON.parse(raw.toString()); } catch { return; }
+      const entry = pending.get(msg.id);
+      if (!entry) return;
+      pending.delete(msg.id);
+      clearTimeout(entry.timer);
+      if (msg.type === MessageType.ERROR) entry.rej(new Error(msg.error || 'Unknown error from extension'));
+      else entry.res(msg.data);
+    });
+
+    ws.on('error', (err) => {
+      reject(new Error(err.code === 'ECONNREFUSED'
+        ? `chrome-bridge server not running on port ${port} — start a Claude Code session (MCP server) or run: npm start`
+        : err.message));
+    });
+  });
+}
+
+// ─── Output helpers ──────────────────────────────────────────────
+
+const MIME_BY_EXT = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf',
+  '.txt': 'text/plain', '.csv': 'text/csv', '.json': 'application/json',
+  '.zip': 'application/zip', '.mp4': 'video/mp4', '.webm': 'video/webm',
+};
+
+function printResult(text, opts) {
+  // Nessun troncamento quando l'output non va a un terminale (pipe verso
+  // jq/grep) o quando è JSON: la nota per umani rendeva il JSON non parsabile.
+  const isJson = (() => {
+    const t = text.trimStart();
+    if (!t.startsWith('{') && !t.startsWith('[')) return false;
+    try { JSON.parse(text); return true; } catch { return false; }
+  })();
+  const explicit = opts.max_chars !== undefined;
+  const max = explicit ? opts.max_chars : (process.stdout.isTTY && !isJson ? 20000 : 0);
+  if (max > 0 && text.length > max) {
+    text = text.slice(0, max) + `\n…[truncated, ${text.length - max} more chars — use --max-chars 0 for full output, or pipe through grep/head]`;
+  }
+  process.stdout.write(text + '\n');
+}
+
+async function writeImages(images, outBase) {
+  const paths = [];
+  const dot = outBase.lastIndexOf('.');
+  const stem = dot > 0 ? outBase.slice(0, dot) : outBase;
+  const ext = dot > 0 ? outBase.slice(dot) : '.png';
+  for (let i = 0; i < images.length; i++) {
+    const path = images.length === 1 ? `${stem}${ext}` : `${stem}-${i + 1}${ext}`;
+    await writeFile(path, Buffer.from(images[i], 'base64'));
+    paths.push(path);
+  }
+  return paths;
+}
+
+// ─── Replay ──────────────────────────────────────────────────────
+
+/** Sostituisce i placeholder {{key}} nelle stringhe di un albero di params. */
+export function substituteVars(value, vars) {
+  if (typeof value === 'string') {
+    return value.replace(/\{\{(\w+)\}\}/g, (m, key) => (key in vars ? String(vars[key]) : m));
+  }
+  if (Array.isArray(value)) return value.map((v) => substituteVars(v, vars));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, substituteVars(v, vars)]));
+  }
+  return value;
+}
+
+/** Legge un recording jsonl e ritorna gli step {command, params}. */
+export function parseReplayFile(content) {
+  return content.split('\n').filter((l) => l.trim()).map((line, i) => {
+    let step;
+    try { step = JSON.parse(line); } catch { throw new Error(`Invalid JSON at line ${i + 1}`); }
+    if (!step.command) throw new Error(`Missing "command" at line ${i + 1}`);
+    return { command: step.command, params: step.params ?? {} };
+  });
+}
+
+async function replay(client, params) {
+  if (!params.file) throw new Error('replay requires --file /path/to/flow.jsonl');
+  const vars = params.vars ? (typeof params.vars === 'string' ? JSON.parse(params.vars) : params.vars) : {};
+  const delay = params.delay ?? 0;
+  const stopOnError = params.stop_on_error ?? true;
+  const steps = parseReplayFile(await readFile(params.file, 'utf8'));
+  const out = [];
+  let failed = 0;
+  for (let i = 0; i < steps.length; i++) {
+    const { command, params: stepParams } = steps[i];
+    try {
+      const p = substituteVars(stepParams, vars);
+      const data = command === 'assert'
+        ? await runAssert(client.sendCommand, p)
+        : await client.sendCommand(command, p);
+      const summary = JSON.stringify(data);
+      out.push(`${i + 1} ${command} ok ${summary.length > 120 ? summary.slice(0, 120) + '…' : summary}`);
+    } catch (err) {
+      failed++;
+      out.push(`${i + 1} ${command} ERR ${err.message}`);
+      if (stopOnError) break;
+    }
+    if (delay && i < steps.length - 1) await new Promise((r) => setTimeout(r, delay));
+  }
+  out.push(`replay ${params.file}: ${out.length - failed}/${steps.length} ok${failed ? `, ${failed} failed` : ''}`);
+  if (failed) process.exitCode = 1;
+  return out.join('\n');
+}
+
+// ─── Dispatch ────────────────────────────────────────────────────
+
+async function run(client, command, params, opts) {
+  if (command === 'replay') {
+    return replay(client, params);
+  }
+  if (command === 'assert') {
+    return JSON.stringify(await runAssert(client.sendCommand, params));
+  }
+  // Comandi virtuali
+  if (command === 'status') {
+    const tabs = await client.sendCommand(MessageType.GET_TABS);
+    return `server=ok extension=connected tabs=${Array.isArray(tabs) ? tabs.length : 0}`;
+  }
+  if (command === 'check_links') {
+    const { timeout, ...collectParams } = params;
+    const data = await client.sendCommand(MessageType.COLLECT_LINKS, collectParams);
+    const links = data.links ?? [];
+    const results = await checkLinksBatch(links, timeout ?? 5000);
+    const broken = results.filter((r) => r.broken).length;
+    if (opts.format === 'json') return JSON.stringify({ total: links.length, checked: results.length, broken, totalAnchors: data.totalAnchors, results });
+    return linksLines(results, { total: links.length, broken, anchors: data.totalAnchors });
+  }
+  if (command === 'security_headers') {
+    const data = await client.sendCommand(MessageType.GET_RESPONSE_HEADERS, params);
+    if (!data.available) return JSON.stringify(data);
+    const result = evaluateSecurityHeaders(data.headers, data.url);
+    result.status = data.status;
+    return JSON.stringify(result);
+  }
+
+  // Comandi con file I/O lato CLI
+  if (command === 'upload_file') {
+    const buf = await readFile(params.path);
+    if (buf.length > 10 * 1024 * 1024) throw new Error(`File too large: ${buf.length} bytes (max 10MB)`);
+    const mime = params.mime_type || MIME_BY_EXT[extname(params.path).toLowerCase()] || 'application/octet-stream';
+    const data = await client.sendCommand(MessageType.UPLOAD_FILE, {
+      selector: params.selector, name: basename(params.path), mime_type: mime,
+      content_b64: buf.toString('base64'), tab_id: params.tab_id,
+    });
+    return JSON.stringify(data);
+  }
+  if (command === 'save_page') {
+    if (!opts.out) throw new Error('save_page requires --out /path/to/page.mhtml');
+    const data = await client.sendCommand(MessageType.SAVE_PAGE, params);
+    await writeFile(opts.out, Buffer.from(data.mhtml_b64, 'base64'));
+    return JSON.stringify({ saved: opts.out, size: data.size });
+  }
+
+  const data = await client.sendCommand(command, params);
+
+  // Comandi che restituiscono immagini → file su disco
+  if (command === 'screenshot' || command === 'element_screenshot') {
+    if (!data?.image) return JSON.stringify(data);
+    const [path] = await writeImages([data.image], opts.out ?? `chrome-bridge-shot-${Date.now()}.png`);
+    return `saved ${path}`;
+  }
+  if (command === 'full_page_screenshot') {
+    const images = data?.images ?? (data?.image ? [data.image] : data?.captures ?? []);
+    if (!images.length) return JSON.stringify(data);
+    const paths = await writeImages(images, opts.out ?? `chrome-bridge-fullpage-${Date.now()}.png`);
+    return `saved ${paths.join(' ')} (${data.totalCaptures} captures, scrollHeight=${data.scrollHeight}${data.truncated ? ', truncated' : ''})`;
+  }
+  if (command === 'screenshot_diff' && data?.diff_image) {
+    const { diff_image, ...rest } = data;
+    const [path] = await writeImages([diff_image], opts.out ?? `chrome-bridge-diff-${Date.now()}.png`);
+    return `saved ${path}\n${JSON.stringify(rest)}`;
+  }
+
+  // Formati lines condivisi coi tool MCP
+  if (command === 'read_console' && opts.format !== 'json') {
+    const all = data?.messages ?? [];
+    return consoleLines(all.slice(-(params.limit ?? 50)), data?.count ?? all.length);
+  }
+  if (command === 'monitor_network' && opts.format !== 'json') {
+    const all = data?.requests ?? [];
+    const tail = all.slice(-(params.limit ?? 100));
+    if (opts.format === 'har') return JSON.stringify(toHar(tail));
+    return networkLines(tail, data?.count ?? all.length);
+  }
+  if (command === 'get_interactives' && opts.format !== 'json') {
+    return interactivesLines(data);
+  }
+  if (command === 'read_page' && typeof data === 'string') {
+    return data;
+  }
+
+  return JSON.stringify(data);
+}
+
+function printHelp() {
+  const commands = [...VALID_COMMANDS].sort().join(', ');
+  process.stdout.write(`chrome-bridge — CLI for the chrome-bridge WebSocket server
+
+Usage:
+  chrome-bridge <command> [--flag value ...] [--json '{...}']
+
+Options:
+  --out PATH        Output file for screenshot/save_page commands
+  --format FMT      lines (default) | json | har (monitor_network)
+  --max-chars N     Truncate output at N chars (default 20000, 0 = unlimited)
+  --json '{...}'    Merge raw JSON into command params
+
+Flags map to command params: --tab-id 42 → tab_id, --visible-only false, --force.
+Requires a running chrome-bridge server (MCP session or npm start); connects as relay.
+
+Aliases: ${Object.entries(ALIASES).map(([a, c]) => `${a}→${c}`).join(', ')}
+
+Commands:
+  ${commands}
+
+Examples:
+  chrome-bridge tabs
+  chrome-bridge navigate --url https://example.com
+  chrome-bridge read_console --tab-id 42 --level error | head -20
+  chrome-bridge js --code 'document.title'
+  chrome-bridge screenshot --out /tmp/shot.png
+  chrome-bridge check_links --scope same-origin
+  chrome-bridge replay --file ~/.config/chrome-bridge/recordings/login.jsonl --vars '{"user":"jane"}'
+`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (!argv.length || argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+    printHelp();
+    return;
+  }
+  const { command, params, opts } = parseCliArgs(argv);
+  const port = parseInt(process.env.CHROME_BRIDGE_PORT || DEFAULT_PORT, 10);
+  const client = await connect(port);
+  try {
+    printResult(await run(client, command, params, opts), opts);
+  } finally {
+    client.close();
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main().catch((err) => {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  });
+}