chrome-bridge-mcp 1.8.0

package/server/tools.js

@@ -0,0 +1,1728 @@
+/**
+ * Registra i tool MCP sul server.
+ *
+ * Ogni tool crea un comando WebSocket, lo invia tramite il WSManager
+ * e restituisce il risultato al client MCP.
+ */
+
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, extname, join } from 'node:path';
+import { parse as parseHtml } from 'node-html-parser';
+import { z } from 'zod';
+import { runAssert } from './assertions.js';
+import { ensureStubServer, addStub, clearStubs, listStubs, stubHost } from './stub-server.js';
+import { MessageType, VERSION } from './protocol.js';
+import { checkLinksBatch } from './link-checker.js';
+import { toHar } from './har.js';
+import { evaluateSecurityHeaders } from './security-headers.js';
+import { consoleLines, networkLines, interactivesLines, linksLines } from './formatters.js';
+
+const SESSIONS_DIR = join(homedir(), '.config', 'chrome-bridge', 'sessions');
+const RECORDINGS_DIR = process.env.CHROME_BRIDGE_RECORD_DIR || join(homedir(), '.config', 'chrome-bridge', 'recordings');
+
+// Comandi rumore per un replay: letture interne (tabSnapshot) o senza effetto
+const RECORD_EXCLUDE = new Set([MessageType.GET_TABS]);
+
+// `hint` è il parametro REALE del tool chiamante che riduce i dati. Suggerire
+// max_length quando 56 tool su 59 non lo espongono mandava il modello a
+// ritentare con un argomento inesistente: un turno bruciato per un consiglio
+// sbagliato.
+function truncateText(text, max, hint = null) {
+  if (typeof text !== 'string' || text.length <= max) return text;
+  const remedy = hint
+    ? `use ${hint} to get less data`
+    : "narrow the request (limit / max_rows / scope / selector) — this tool has no max_length";
+  return text.slice(0, max) + `\n…[truncated, ${text.length - max} more chars — ${remedy}]`;
+}
+
+// Limite di default sull'output testuale di ogni tool: protegge il contesto
+// del client MCP da payload fuori scala (es. buffer console/network pieni).
+const DEFAULT_MAX_OUTPUT = 20000;
+
+/**
+ * Serializza compatto (niente pretty-print: solo token sprecati per il modello).
+ *
+ * Se il payload supera il cap, si riducono gli ELEMENTI e non i caratteri:
+ * tagliare la stringa a metà di un valore produceva JSON non parsabile su ogni
+ * path format=json/har (verificato: `JSON.parse` falliva con "Bad control
+ * character in string literal"). Qui il risultato resta sempre valido e dichiara
+ * quanto è stato omesso.
+ */
+function jsonText(data, max = DEFAULT_MAX_OUTPUT, hint = null) {
+  const text = JSON.stringify(data);
+  if (text == null || text.length <= max) return text;
+
+  // Caso array puro
+  if (Array.isArray(data)) {
+    const kept = fitArray(data, max, (items) => JSON.stringify({ shown: items.length, total: data.length, items }));
+    return JSON.stringify({ shown: kept.length, total: data.length, truncated: true, hint: hint ?? undefined, items: kept });
+  }
+
+  // Caso oggetto con un array dominante (requests, messages, violations, rows…)
+  if (data && typeof data === 'object') {
+    let key = null;
+    let best = -1;
+    for (const [k, v] of Object.entries(data)) {
+      if (Array.isArray(v) && v.length > best) { key = k; best = v.length; }
+    }
+    if (key) {
+      const full = data[key];
+      const kept = fitArray(full, max, (items) => JSON.stringify({ ...data, [key]: items }));
+      return JSON.stringify({
+        ...data,
+        [key]: kept,
+        shown: kept.length,
+        total: full.length,
+        truncated: kept.length < full.length,
+        ...(hint && kept.length < full.length ? { hint } : {}),
+      });
+    }
+  }
+
+  // Nessun array da ridurre: resta il taglio testuale, ma con il rimedio giusto.
+  return truncateText(text, max, hint);
+}
+
+/** Il più lungo prefisso di `items` la cui serializzazione sta sotto `max` (ricerca binaria). */
+function fitArray(items, max, serialize) {
+  if (serialize(items).length <= max) return items;
+  let lo = 0;
+  let hi = items.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (serialize(items.slice(0, mid)).length <= max) lo = mid; else hi = mid - 1;
+  }
+  return items.slice(0, lo);
+}
+
+/** Una riga (oggetto colonna→valore o array di celle) soddisfa il filtro where. */
+function tableRowMatches(row, where) {
+  return Object.entries(where).every(([col, needle]) => {
+    const n = String(needle).toLowerCase();
+    if (Array.isArray(row)) return row.some((cell) => String(cell).toLowerCase().includes(n));
+    if (col === 'any') return Object.values(row).some((cell) => String(cell).toLowerCase().includes(n));
+    const cell = row[col];
+    return cell != null && String(cell).toLowerCase().includes(n);
+  });
+}
+
+/** Proietta solo le colonne richieste (solo righe-oggetto; array intatti). */
+function projectCols(row, columns) {
+  if (Array.isArray(row)) return row;
+  const o = {};
+  for (const c of columns) o[c] = row[c] ?? '';
+  return o;
+}
+
+/**
+ * Modella la risposta grezza di extract_table lato server: filtra (where),
+ * pagina (offset/max_rows) e proietta (columns) PRIMA di spedire al modello,
+ * così il payload resta piccolo anche su tabelle enormi. row_count resta il
+ * totale reale della tabella; match_count è quante righe passano il filtro.
+ */
+function shapeTable(data, { where, columns, offset = 0, max_rows = 100 } = {}) {
+  let rows = Array.isArray(data.rows) ? data.rows : [];
+  const total = data.row_count ?? rows.length;
+  const hasWhere = where && Object.keys(where).length > 0;
+  let match_count;
+  if (hasWhere) {
+    rows = rows.filter((r) => tableRowMatches(r, where));
+    match_count = rows.length;
+  }
+  const available = rows.length;
+  const page = rows.slice(offset, offset + max_rows);
+  const projected = (columns && columns.length) ? page.map((r) => projectCols(r, columns)) : page;
+  const out = {
+    caption: data.caption ?? null,
+    headers: data.headers ?? [],
+    row_count: total,
+    rows: projected,
+    truncated: (offset + page.length) < available || Boolean(data.truncated && !hasWhere),
+    tables_found: data.tables_found ?? 0,
+  };
+  if (hasWhere) out.match_count = match_count;
+  if (offset) out.offset = offset;
+  return out;
+}
+
+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',
+};
+
+/**
+ * Dopo un'azione (click/type/fill), attende navigazione o network idle se richiesto.
+ *
+ * @param {(type: string, params?: object) => Promise<object>} send - invio comandi (con default tab di sessione)
+ * @param {'none'|'navigation'|'networkidle'} wait_after - tipo di attesa
+ * @param {number} [tab_id] - tab target
+ * @returns {Promise<object|null>} risultato dell'attesa, o null se none
+ */
+async function applyWaitAfter(send, wait_after, tab_id) {
+  if (wait_after === 'navigation') {
+    return await send(MessageType.WAIT_FOR_NAVIGATION, { timeout: 15000, tab_id });
+  }
+  if (wait_after === 'networkidle') {
+    return await send(MessageType.WAIT_FOR_NETWORK_IDLE, { idle_ms: 500, timeout: 15000, tab_id });
+  }
+  return null;
+}
+
+/**
+ * Gruppi capability opt-in. I tool non elencati qui sono il set core,
+ * sempre registrato. Gli altri si attivano con --caps group1,group2 o
+ * CHROME_BRIDGE_CAPS (valore speciale "all" = tutto).
+ */
+export const TOOL_CAPS = {
+  audits: ['accessibility_audit', 'seo_audit', 'security_headers', 'check_links', 'unused_css', 'web_vitals', 'get_performance'],
+  visual: ['screenshot_diff', 'highlight_elements', 'inject_css', 'measure_spacing', 'emulate_media', 'viewport_resize', 'set_zoom'],
+  network: ['network_rules', 'monitor_websocket', 'http_auth', 'set_geolocation'],
+  storage: ['get_storage', 'set_storage', 'session_fixture'],
+  dom: ['modify_dom', 'watch_dom', 'list_event_listeners', 'drag_and_drop'],
+  files: ['save_page', 'manage_downloads', 'extract_table', 'session_record'],
+};
+
+const TOOL_TO_CAP = new Map();
+for (const [group, names] of Object.entries(TOOL_CAPS)) {
+  for (const n of names) TOOL_TO_CAP.set(n, group);
+}
+
+/**
+ * Registra tutti i tool MCP.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/index.js').McpServer} server - MCP Server
+ * @param {import('./ws-manager.js').WSManager} wsManager - WebSocket manager
+ * @param {string} [caps='all'] - 'all', 'core', o lista di gruppi "audits,visual"
+ */
+export function registerTools(server, wsManager, caps = 'all') {
+  const startedAt = Date.now();
+  const activeCaps = caps === 'all'
+    ? ['core', ...Object.keys(TOOL_CAPS)]
+    : ['core', ...String(caps).split(',').map((s) => s.trim()).filter((s) => s && s !== 'core')];
+
+  // Filtro capability: i tool opt-in fuori dai gruppi attivi non vengono registrati
+  if (caps !== 'all') {
+    const enabled = new Set(String(caps).split(',').map((s) => s.trim()).filter(Boolean));
+    const target = server;
+    server = {
+      tool(name, desc, schema, handler) {
+        const group = TOOL_TO_CAP.get(name);
+        if (group && !enabled.has(group) && !enabled.has('all')) return;
+        target.tool(name, desc, schema, handler);
+      },
+    };
+  }
+
+  // Ultimo tab toccato da navigate/create_tab in questa sessione: è il default
+  // dei comandi senza tab_id esplicito. "Tab attivo" è una landmine quando
+  // l'utente usa Chrome durante l'automazione (il comando colpirebbe la pagina
+  // che sta guardando lui, non quella navigata dall'agente).
+  let sessionTabId = null;
+
+  // Recording attivo: { name, file }. I comandi (senza tab_id, che in un
+  // replay sarebbe stale) vengono appesi come jsonl replayabile dal CLI.
+  let recording = null;
+  // Gli append del recording erano fire-and-forget: un comando registrato
+  // poteva non essere ancora sul disco quando session_record stop tornava, e
+  // uno step mancante rende un replay silenziosamente sbagliato. La catena
+  // serializza le scritture e stop() la attende.
+  let recordChain = Promise.resolve();
+  // >0 mentre un tool composito (assert) esegue query interne che nel
+  // recording sarebbero rumore: registra il tool, non le sue query.
+  let recordSuppressed = 0;
+
+  const send = async (type, params = {}) => {
+    if (recording && !recordSuppressed && !RECORD_EXCLUDE.has(type)) {
+      const { tab_id: _tab, ...rest } = params;
+      const file = recording.file;
+      const line = JSON.stringify({ command: type, params: rest }) + '\n';
+      recordChain = recordChain.then(() => appendFile(file, line)).catch(() => {});
+    }
+    const implicitTab = params.tab_id == null && sessionTabId != null;
+    if (implicitTab) params = { ...params, tab_id: sessionTabId };
+    try {
+      return await wsManager.sendCommand(type, params);
+    } catch (err) {
+      // Se l'utente chiude a mano la tab di sessione, ogni comando successivo
+      // fallisce fino al prossimo navigate. Un solo ritentativo sulla tab
+      // attiva salva un turno intero al modello.
+      const gone = /No tab with id|No active tab|No tab found/i.test(err?.message ?? '');
+      if (!gone || !implicitTab) throw err;
+      sessionTabId = null;
+      const { tab_id: _drop, ...retry } = params;
+      const data = await wsManager.sendCommand(type, retry);
+      return data;
+    }
+  };
+
+  // Mappa ref → selector per tab, popolata da get_interactives.
+  // Permette click/type_text/hover per ref (n1, n2…) senza ripetere selettori lunghi.
+  const interactivesRefs = new Map();
+
+  const refsKey = (tab_id) => tab_id ?? sessionTabId ?? 'active';
+
+  function resolveTarget(selector, ref, tab_id) {
+    if (selector) return selector;
+    if (ref) {
+      const sel = interactivesRefs.get(refsKey(tab_id))?.get(ref);
+      if (!sel) throw new Error(`Unknown ref ${ref} — run get_interactives first`);
+      return sel;
+    }
+    throw new Error('Either selector or ref is required');
+  }
+
+  // Snapshot url/title del tab target, per il delta post-azione.
+  async function tabSnapshot(tab_id) {
+    try {
+      const tabs = await send(MessageType.GET_TABS);
+      const list = Array.isArray(tabs) ? tabs : [];
+      const eff = tab_id ?? sessionTabId;
+      const tab = eff != null ? list.find((t) => t.id === eff) : list.find((t) => t.active);
+      return tab ? { url: tab.url, title: tab.title } : null;
+    } catch { return null; }
+  }
+
+  // Delta compatto dopo un'azione: presente solo se url/title sono cambiati.
+  // Costa pochi token quando scatta, zero quando la pagina è stabile, e
+  // risparmia al client un giro di ispezione per capire "cosa è successo".
+  function pageDelta(before, after) {
+    if (!before || !after) return null;
+    const delta = {};
+    if (after.url !== before.url) delta.url = after.url;
+    if (after.title !== before.title) delta.title = after.title;
+    return Object.keys(delta).length ? delta : null;
+  }
+
+  // Anteprima compatta dei primi interactives (con ref), allegata a navigate:
+  // il client può agire subito senza un giro di discovery. Cappata e best-effort.
+  async function interactivesPreview(tab_id, limit = 12) {
+    try {
+      const data = await send(MessageType.GET_INTERACTIVES, { limit, visible_only: true, tab_id });
+      const refMap = new Map();
+      (data?.elements ?? []).forEach((e, i) => {
+        e.ref = `n${i + 1}`;
+        if (e.selector) refMap.set(e.ref, e.selector);
+      });
+      interactivesRefs.set(refsKey(tab_id), refMap);
+      return refMap.size ? truncateText(interactivesLines(data), 1500) : null;
+    } catch { return null; }
+  }
+
+  // --- get_status ---
+  server.tool(
+    'get_status',
+    'Check bridge status: extension connection, server mode (primary/relay), port, version',
+    {},
+    async () => {
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText({
+            connected: wsManager.isConnected(),
+            mode: wsManager.mode,
+            host: wsManager.host,
+            port: wsManager.port,
+            version: VERSION,
+            extension_version: wsManager.extVersion ?? null,
+            // Un agente che non trova accessibility_audit non aveva modo di
+            // scoprire che esiste ma è in un gruppo disattivato.
+            caps_active: activeCaps,
+            caps_available: ['core', ...Object.keys(TOOL_CAPS)],
+            session_tab_id: sessionTabId,
+            uptime_sec: Math.round((Date.now() - startedAt) / 1000),
+          }),
+        }],
+      };
+    }
+  );
+
+  // --- get_tabs ---
+  server.tool(
+    'get_tabs',
+    'List all open Chrome tabs',
+    {},
+    async () => {
+      const data = await send(MessageType.GET_TABS);
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- navigate ---
+  server.tool(
+    'navigate',
+    'Navigate a Chrome tab to a URL. Returns a preview of interactive elements with refs usable in click/type_text/hover.',
+    {
+      url:    z.string(),
+      tab_id: z.number().optional(),
+    },
+    async ({ url, tab_id }) => {
+      const data = await send(MessageType.NAVIGATE, { url, tab_id });
+      // Il tab navigato diventa il default di sessione per i comandi successivi
+      if (data?.tabId != null) sessionTabId = data.tabId;
+      const preview = await interactivesPreview(data?.tabId ?? tab_id);
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data) + (preview ? `\n${preview}` : ''),
+        }],
+      };
+    }
+  );
+
+  // --- screenshot ---
+  server.tool(
+    'screenshot',
+    'Screenshot a tab (PNG). Activates the tab in the background without stealing window focus, then restores the previous tab.',
+    {
+      tab_id: z.number().optional(),
+    },
+    async ({ tab_id }) => {
+      const data = await send(MessageType.SCREENSHOT, { tab_id });
+      // data.image è base64 PNG
+      if (data && data.image) {
+        return {
+          content: [{
+            type: 'image',
+            data: data.image,
+            mimeType: 'image/png',
+          }],
+        };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- execute_js ---
+  server.tool(
+    'execute_js',
+    'Run JavaScript in the page (MAIN world). Requires the extension\'s "Allow user scripts" toggle; errors explain setup if disabled.',
+    {
+      code:       z.string(),
+      tab_id:     z.number().optional(),
+      frame_id:   z.number().optional(),
+      max_length: z.number().optional().default(20000).describe('Max output chars'),
+    },
+    async ({ code, tab_id, frame_id, max_length }) => {
+      const data = await send(MessageType.EXECUTE_JS, { code, tab_id, frame_id });
+      return {
+        content: [{
+          type: 'text',
+          text: truncateText(JSON.stringify(data), max_length ?? DEFAULT_MAX_OUTPUT, 'max_length'),
+        }],
+      };
+    }
+  );
+
+  // --- click ---
+  server.tool(
+    'click',
+    'Click an element by CSS selector or by ref from get_interactives.',
+    {
+      selector: z.string().optional(),
+      ref:      z.string().optional().describe('From get_interactives, e.g. "n3"'),
+      force:    z.boolean().optional().default(false).describe('Click even if occluded'),
+      wait_after: z.enum(['none', 'navigation', 'networkidle']).optional().default('none'),
+      tab_id:   z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ selector, ref, force, wait_after, tab_id, frame_id }) => {
+      const target = resolveTarget(selector, ref, tab_id);
+      const before = await tabSnapshot(tab_id);
+      const data = await send(MessageType.CLICK, { selector: target, force, frame_id, tab_id });
+      // Niente attesa se il click non è andato a buon fine (es. elemento occluso)
+      const waited = data?.occluded ? null : await applyWaitAfter(send, wait_after, tab_id);
+      const changed = data?.occluded ? null : pageDelta(before, await tabSnapshot(tab_id));
+      const out = { ...data, ...(waited && { wait_after: waited }), ...(changed && { page_changed: changed }) };
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(out),
+        }],
+      };
+    }
+  );
+
+  // --- type_text ---
+  server.tool(
+    'type_text',
+    'Type text into an input, by CSS selector or by ref from get_interactives.',
+    {
+      selector: z.string().optional(),
+      ref:      z.string().optional().describe('From get_interactives, e.g. "n3"'),
+      text:     z.string(),
+      mode:     z.enum(['set', 'keys']).optional().default('set').describe('set = assign value; keys = per-char events (autocomplete/masked)'),
+      wait_after: z.enum(['none', 'navigation', 'networkidle']).optional().default('none'),
+      tab_id:   z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ selector, ref, text, mode, wait_after, tab_id, frame_id }) => {
+      const target = resolveTarget(selector, ref, tab_id);
+      const data = await send(MessageType.TYPE_TEXT, { selector: target, text, mode, tab_id, frame_id });
+      const waited = await applyWaitAfter(send, wait_after, tab_id);
+      const out = waited ? { ...data, wait_after: waited } : data;
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(out),
+        }],
+      };
+    }
+  );
+
+  // --- read_page ---
+  server.tool(
+    'read_page',
+    'Read the content of a Chrome tab page',
+    {
+      mode:       z.enum(['text', 'html', 'accessibility']).default('text'),
+      tab_id:     z.number().optional(),
+      frame_id:   z.number().optional(),
+      max_length: z.number().optional().default(50000).describe('Max output chars'),
+    },
+    async ({ mode, tab_id, frame_id, max_length }) => {
+      const data = await send(MessageType.READ_PAGE, { mode, tab_id, frame_id });
+      return {
+        content: [{
+          type: 'text',
+          text: truncateText(typeof data === 'string' ? data : JSON.stringify(data), max_length ?? 50000, 'max_length'),
+        }],
+      };
+    }
+  );
+
+  // --- get_page_info ---
+  server.tool(
+    'get_page_info',
+    'Get page metadata: meta tags, scripts, stylesheets, links, and forms',
+    {
+      tab_id: z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ tab_id, frame_id }) => {
+      const data = await send(MessageType.GET_PAGE_INFO, { tab_id, frame_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- get_storage ---
+  server.tool(
+    'get_storage',
+    'Get page storage: localStorage, sessionStorage, and cookies',
+    {
+      type:   z.enum(['all', 'localStorage', 'sessionStorage', 'cookies']).default('all'),
+      tab_id: z.number().optional(),
+    },
+    async ({ type, tab_id }) => {
+      const data = await send(MessageType.GET_STORAGE, { type, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- get_performance ---
+  server.tool(
+    'get_performance',
+    'Get page performance metrics: navigation timing, paint metrics, memory, and resource loading',
+    {
+      tab_id: z.number().optional(),
+    },
+    async ({ tab_id }) => {
+      const data = await send(MessageType.GET_PERFORMANCE, { tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- query_dom ---
+  server.tool(
+    'query_dom',
+    'Query DOM elements by CSS selector, returning structure, attributes, bounding rect, and computed styles.',
+    {
+      selector: z.string(),
+      properties: z.array(z.string()).optional().describe('Computed styles to include, e.g. ["color"]'),
+      limit: z.number().optional().default(50),
+      tab_id: z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ selector, properties, limit, tab_id, frame_id }) => {
+      const data = await send(MessageType.QUERY_DOM, { selector, properties, limit, tab_id, frame_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- modify_dom ---
+  server.tool(
+    'modify_dom',
+    'Modify DOM elements: setAttribute, removeAttribute, addClass, removeClass, setStyle, setTextContent',
+    {
+      selector: z.string(),
+      action: z.enum(['setAttribute', 'removeAttribute', 'addClass', 'removeClass', 'setStyle', 'setTextContent']),
+      name: z.string().optional().describe('Attribute name'),
+      value: z.string().optional(),
+      className: z.string().optional(),
+      tab_id: z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ selector, action, name, value, className, tab_id, frame_id }) => {
+      const data = await send(MessageType.MODIFY_DOM, { selector, action, name, value, className, tab_id, frame_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- inject_css ---
+  server.tool(
+    'inject_css',
+    'Inject CSS rules into a Chrome tab page',
+    {
+      css: z.string(),
+      tab_id: z.number().optional(),
+    },
+    async ({ css, tab_id }) => {
+      const data = await send(MessageType.INJECT_CSS, { css, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- read_console ---
+  server.tool(
+    'read_console',
+    'Read console messages captured since page load, incl. uncaught errors and unhandled rejections.',
+    {
+      clear: z.boolean().optional().default(false).describe('Clear buffer after read'),
+      level: z.enum(['all', 'log', 'warn', 'error', 'info', 'debug']).optional().default('all'),
+      limit: z.number().optional().default(50).describe('Most recent; buffer 1000'),
+      format: z.enum(['lines', 'json']).optional().default('lines'),
+      tab_id: z.number().optional(),
+    },
+    async ({ clear, level, limit, format, tab_id }) => {
+      // limit va all'estensione: taglia in pagina e cancella (con clear) solo
+      // ciò che ha restituito. Lo slice qui resta come fallback per estensioni
+      // più vecchie che ignorano il parametro.
+      const data = await send(MessageType.READ_CONSOLE, { clear, level, limit, tab_id });
+      const all = data?.messages ?? [];
+      const tail = all.slice(-(limit ?? 50));
+      const total = data?.count ?? all.length;
+      const note = data?.note;
+      if ((format ?? 'lines') === 'json') {
+        return { content: [{ type: 'text', text: jsonText({ total, shown: tail.length, ...(note ? { note } : {}), messages: tail }) }] };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: truncateText(
+            (note ? `note=${note}\n` : '') + consoleLines(tail, total),
+            DEFAULT_MAX_OUTPUT,
+          ),
+        }],
+      };
+    }
+  );
+
+  // --- monitor_network ---
+  server.tool(
+    'monitor_network',
+    'Monitor network requests. source=page: XHR/fetch hook (installed on first call); source=browser: all requests incl. static assets. format=har exports HAR 1.2.',
+    {
+      clear: z.boolean().optional().default(false).describe('Clear buffer after read'),
+      source: z.enum(['page', 'browser']).optional().default('page'),
+      format: z.enum(['lines', 'json', 'har']).optional().default('lines'),
+      limit: z.number().optional().default(100).describe('Most recent; buffer 1000'),
+      tab_id: z.number().optional(),
+    },
+    async ({ clear, source, format, limit, tab_id }) => {
+      // limit va all'estensione (taglia in pagina, clear solo del restituito);
+      // lo slice qui resta come fallback per estensioni non ancora aggiornate.
+      const data = await send(MessageType.MONITOR_NETWORK, { clear, source, limit, tab_id });
+      const { requests, count, note, ...rest } = data ?? {};
+      const all = requests ?? [];
+      const tail = all.slice(-(limit ?? 100));
+      const total = count ?? all.length;
+      const fmt = format ?? 'lines';
+      if (fmt !== 'lines') {
+        const out = fmt === 'har'
+          ? toHar(tail)
+          : { ...rest, total, shown: tail.length, ...(note ? { note } : {}), requests: tail };
+        return { content: [{ type: 'text', text: jsonText(out) }] };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: truncateText(
+            (note ? `note=${note}\n` : '') + networkLines(tail, total),
+            DEFAULT_MAX_OUTPUT,
+          ),
+        }],
+      };
+    }
+  );
+
+  // --- create_tab ---
+  server.tool(
+    'create_tab',
+    'Create a new Chrome tab, optionally navigating to a URL',
+    {
+      url: z.string().optional().describe('URL to open (default: new tab page)'),
+      active: z.boolean().optional().default(true),
+    },
+    async ({ url, active }) => {
+      const data = await send(MessageType.CREATE_TAB, { url, active });
+      if (data?.id != null) sessionTabId = data.id;
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- wait_for ---
+  server.tool(
+    'wait_for',
+    'Wait for: element (selector in DOM), function (JS expression truthy; needs "Allow user scripts"), navigation (mode=spa for route changes), network_idle.',
+    {
+      condition: z.enum(['element', 'function', 'navigation', 'network_idle']),
+      selector: z.string().optional().describe('condition=element'),
+      expression: z.string().optional().describe('JS expression (condition=function)'),
+      visible: z.boolean().optional().default(false).describe('Element must also be visible'),
+      mode: z.enum(['load', 'spa']).optional().default('load').describe('spa = pushState/popstate/hashchange'),
+      idle_ms: z.number().optional().default(500).describe('Quiet period ms (network_idle)'),
+      timeout: z.number().optional().describe('Max ms (default 10000; 15000 navigation/network_idle)'),
+      interval: z.number().optional().describe('Poll ms, min 50'),
+      tab_id: z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ condition, selector, expression, visible, mode, idle_ms, timeout, interval, tab_id, frame_id }) => {
+      let data;
+      if (condition === 'element') {
+        data = await send(MessageType.WAIT_FOR_ELEMENT, {
+          selector, timeout: timeout ?? 10000, interval: interval ?? 200, visible: visible ?? false, tab_id, frame_id,
+        });
+      } else if (condition === 'function') {
+        data = await send(MessageType.WAIT_FOR_FUNCTION, {
+          expression, timeout: timeout ?? 10000, polling_ms: interval ?? 100, tab_id, frame_id,
+        });
+      } else if (condition === 'navigation') {
+        data = await send(MessageType.WAIT_FOR_NAVIGATION, {
+          timeout: timeout ?? 15000, mode: mode ?? 'load', tab_id,
+        });
+      } else {
+        data = await send(MessageType.WAIT_FOR_NETWORK_IDLE, {
+          idle_ms: idle_ms ?? 500, timeout: timeout ?? 15000, tab_id,
+        });
+      }
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- scroll ---
+  server.tool(
+    'scroll',
+    'Scroll. action=to: once to element/coordinates; action=until: repeatedly until element visible, network idle, or no new content (infinite scroll).',
+    {
+      action: z.enum(['to', 'until']).optional().default('to'),
+      selector: z.string().optional().describe('Target (to) or stop element (until=element)'),
+      x: z.number().optional(),
+      y: z.number().optional(),
+      behavior: z.enum(['smooth', 'instant', 'auto']).optional().default('auto'),
+      offset_y: z.number().optional().default(0).describe('px offset for fixed headers (to)'),
+      until: z.enum(['element', 'network_idle', 'no_new_content']).optional().default('no_new_content'),
+      max_scrolls: z.number().optional().default(20),
+      step_px: z.number().optional().describe('px per step, default viewport height'),
+      settle_ms: z.number().optional().default(400).describe('Pause ms after each step'),
+      tab_id: z.number().optional(),
+      frame_id: z.number().optional().describe('action=to only'),
+    },
+    async ({ action, selector, x, y, behavior, offset_y, until, max_scrolls, step_px, settle_ms, tab_id, frame_id }) => {
+      const data = (action ?? 'to') === 'until'
+        ? await send(MessageType.SCROLL_UNTIL, { until, selector, max_scrolls, step_px, settle_ms, tab_id })
+        : await send(MessageType.SCROLL_TO, { selector, x, y, behavior, offset_y, tab_id, frame_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- set_storage ---
+  server.tool(
+    'set_storage',
+    'Write, delete, or clear localStorage, sessionStorage, or cookies',
+    {
+      type: z.enum(['localStorage', 'sessionStorage', 'cookie']),
+      action: z.enum(['set', 'delete', 'clear']),
+      key: z.string().optional().describe('Required for set/delete'),
+      value: z.string().optional(),
+      path: z.string().optional().describe('Cookie path (default /)'),
+      domain: z.string().optional().describe('Cookie domain'),
+      expires: z.string().optional().describe('UTC date string (cookie)'),
+      secure: z.boolean().optional(),
+      sameSite: z.enum(['Strict', 'Lax', 'None']).optional(),
+      http_only: z.boolean().optional(),
+      tab_id: z.number().optional(),
+    },
+    async ({ type, action, key, value, path, domain, expires, secure, sameSite, http_only, tab_id }) => {
+      const data = await send(MessageType.SET_STORAGE, { type, action, key, value, path, domain, expires, secure, sameSite, http_only, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- fill_form ---
+  server.tool(
+    'fill_form',
+    'Batch fill form fields with React-compatible events. Handles input, select, checkbox, radio, and textarea.',
+    {
+      fields: z.array(z.object({
+        selector: z.string(),
+        value: z.string(),
+      })).describe('{selector, value} pairs'),
+      submit_selector: z.string().optional().describe('Submit button to click after filling'),
+      wait_after: z.enum(['none', 'navigation', 'networkidle']).optional().default('none'),
+      tab_id: z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ fields, submit_selector, wait_after, tab_id, frame_id }) => {
+      const before = await tabSnapshot(tab_id);
+      const data = await send(MessageType.FILL_FORM, { fields, submit_selector, tab_id, frame_id });
+      const waited = await applyWaitAfter(send, wait_after, tab_id);
+      const changed = pageDelta(before, await tabSnapshot(tab_id));
+      const out = { ...data, ...(waited && { wait_after: waited }), ...(changed && { page_changed: changed }) };
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(out),
+        }],
+      };
+    }
+  );
+
+  // --- viewport_resize ---
+  server.tool(
+    'viewport_resize',
+    'Resize Chrome window to preset (mobile/tablet/desktop) or custom dimensions',
+    {
+      preset: z.enum(['mobile', 'tablet', 'desktop']).optional().describe('375x812, 768x1024, 1440x900'),
+      width: z.number().optional().describe('Overrides preset'),
+      height: z.number().optional().describe('Overrides preset'),
+      tab_id: z.number().optional(),
+    },
+    async ({ preset, width, height, tab_id }) => {
+      const data = await send(MessageType.VIEWPORT_RESIZE, { preset, width, height, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- element_screenshot ---
+  server.tool(
+    'element_screenshot',
+    'Screenshot a single element (scrolled into view, cropped). PNG.',
+    {
+      selector: z.string(),
+      tab_id: z.number().optional(),
+    },
+    async ({ selector, tab_id }) => {
+      const data = await send(MessageType.ELEMENT_SCREENSHOT, { selector, tab_id });
+      if (data && data.image) {
+        return { content: [{ type: 'image', data: data.image, mimeType: 'image/png' }] };
+      }
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- full_page_screenshot ---
+  server.tool(
+    'full_page_screenshot',
+    'Full-page capture by scrolling: stitched segments of ~2 viewports (≤1568px, top→bottom), or one image per viewport with stitch=false.',
+    {
+      max_scrolls: z.number().optional().default(20),
+      delay: z.number().optional().default(500).describe('ms between captures (min 500, Chrome quota)'),
+      stitch: z.boolean().optional().default(true).describe('false = one image per viewport'),
+      max_segments: z.number().optional().default(3).describe('Images returned, from the top (each ≈2.7k image tokens); raise or use segment_offset for the rest'),
+      segment_offset: z.number().optional().default(0).describe('Skip the first N segments'),
+      tab_id: z.number().optional(),
+    },
+    async ({ max_scrolls, delay, stitch, max_segments, segment_offset, tab_id }) => {
+      const data = await send(MessageType.FULL_PAGE_SCREENSHOT, { max_scrolls, delay, stitch, tab_id });
+      if (data && data.images) {
+        // DEFAULT_MAX_OUTPUT protegge solo il testo: senza questo cap una sola
+        // chiamata su una pagina lunga restituiva 10 immagini (~4 MB base64,
+        // ~27k token) ed era l'unico output del set capace di saturare il contesto.
+        const off = Math.max(0, segment_offset ?? 0);
+        const cap = Math.max(1, max_segments ?? 3);
+        const slice = data.images.slice(off, off + cap);
+        const more = data.images.length - (off + slice.length);
+        const note = `Full page: ${data.totalCaptures} captures, ${data.images.length} segments (top→bottom), scrollHeight=${data.scrollHeight}`
+          + `, showing ${off + 1}-${off + slice.length}`
+          + (more > 0 ? ` — ${more} more: call with segment_offset=${off + slice.length}` : '')
+          + (data.truncated ? ' (page continues beyond captured area — raise max_scrolls to capture more)' : '');
+        return {
+          content: [
+            { type: 'text', text: note },
+            ...slice.map((img) => ({ type: 'image', data: img, mimeType: 'image/png' })),
+          ],
+        };
+      }
+      // Retrocompatibilità: extension non ancora ricaricata → singola immagine stitched
+      if (data && data.image) {
+        const note = `Full page: ${data.totalCaptures} captures stitched, scrollHeight=${data.scrollHeight}${data.truncated ? ' (truncated at 16384px canvas limit)' : ''}`;
+        return { content: [{ type: 'text', text: note }, { type: 'image', data: data.image, mimeType: 'image/png' }] };
+      }
+      const content = [{ type: 'text', text: `Full page screenshot: ${data.captures?.length || 0} captures, scrollHeight=${data.scrollHeight}, viewportHeight=${data.viewportHeight}` }];
+      for (const img of data.captures || []) {
+        content.push({ type: 'image', data: img, mimeType: 'image/png' });
+      }
+      return { content };
+    }
+  );
+
+  // --- highlight_elements ---
+  server.tool(
+    'highlight_elements',
+    'Add colored overlay on elements matching a CSS selector. remove=true clears all highlights.',
+    {
+      selector: z.string().optional(),
+      color: z.string().optional().default('rgba(255,0,0,0.3)'),
+      border: z.string().optional().default('2px solid red'),
+      label: z.boolean().optional().default(false).describe('Show tag.class (WxH) label'),
+      remove: z.boolean().optional().default(false),
+      tab_id: z.number().optional(),
+    },
+    async ({ selector, color, border, label, remove, tab_id }) => {
+      const data = await send(MessageType.HIGHLIGHT_ELEMENTS, { selector, color, border, label, remove, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- accessibility_audit ---
+  server.tool(
+    'accessibility_audit',
+    'A11y audit: missing alt, empty links, heading hierarchy, ARIA, contrast (approximate), form labels.',
+    {
+      scope: z.string().optional().describe('Limit scope (CSS selector)'),
+      checks: z.array(z.enum(['images', 'links', 'headings', 'aria', 'contrast', 'forms', 'all'])).optional().default(['all']),
+      tab_id: z.number().optional(),
+    },
+    async ({ scope, checks, tab_id }) => {
+      const data = await send(MessageType.ACCESSIBILITY_AUDIT, { scope, checks, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- check_links ---
+  server.tool(
+    'check_links',
+    'Check page links for broken URLs, verified server-side (no CORS limits, real HTTP status).',
+    {
+      scope: z.enum(['same-origin', 'all', 'external']).optional().default('all'),
+      selector: z.string().optional().default('a[href]'),
+      timeout: z.number().optional().default(5000).describe('Per-link ms'),
+      max_links: z.number().optional().default(50),
+      format: z.enum(['lines', 'json']).optional().default('lines'),
+      tab_id: z.number().optional(),
+    },
+    async ({ scope, selector, timeout, max_links, format, tab_id }) => {
+      const data = await send(MessageType.COLLECT_LINKS, { scope, selector, max_links, tab_id });
+      const links = data.links ?? [];
+      const results = await checkLinksBatch(links, timeout);
+      const broken = results.filter((r) => r.broken).length;
+      if ((format ?? 'lines') === 'json') {
+        return {
+          content: [{
+            type: 'text',
+            text: jsonText({ total: links.length, checked: results.length, broken, totalAnchors: data.totalAnchors, results }),
+          }],
+        };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: truncateText(linksLines(results, { total: links.length, broken, anchors: data.totalAnchors }), DEFAULT_MAX_OUTPUT),
+        }],
+      };
+    }
+  );
+
+  // --- measure_spacing ---
+  server.tool(
+    'measure_spacing',
+    'Measure pixel distance, gap, overlap, and margin/padding between two elements',
+    {
+      selector1: z.string(),
+      selector2: z.string(),
+      tab_id: z.number().optional(),
+    },
+    async ({ selector1, selector2, tab_id }) => {
+      const data = await send(MessageType.MEASURE_SPACING, { selector1, selector2, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- watch_dom ---
+  server.tool(
+    'watch_dom',
+    'Watch DOM mutations (MutationObserver). First call installs the watcher; later calls read accumulated mutations.',
+    {
+      selector: z.string().optional().default('body'),
+      attributes: z.boolean().optional().default(true),
+      childList: z.boolean().optional().default(true),
+      characterData: z.boolean().optional().default(false),
+      subtree: z.boolean().optional().default(true),
+      clear: z.boolean().optional().default(false).describe('Clear buffer after read'),
+      stop: z.boolean().optional().default(false).describe('Disconnect observer'),
+      limit: z.number().optional().default(100).describe('Most recent mutations; buffer 1000'),
+      tab_id: z.number().optional(),
+    },
+    async ({ selector, attributes, childList, characterData, subtree, clear, stop, limit, tab_id }) => {
+      const data = await send(MessageType.WATCH_DOM, { selector, attributes, childList, characterData, subtree, clear, stop, limit, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- emulate_media ---
+  server.tool(
+    'emulate_media',
+    'Emulate prefers-color-scheme, prefers-reduced-motion, print mode (matchMedia override + CSS).',
+    {
+      colorScheme: z.enum(['dark', 'light', 'no-preference']).optional(),
+      reducedMotion: z.enum(['reduce', 'no-preference']).optional(),
+      printMode: z.boolean().optional().default(false),
+      reset: z.boolean().optional().default(false).describe('Remove all emulations'),
+      tab_id: z.number().optional(),
+    },
+    async ({ colorScheme, reducedMotion, printMode, reset, tab_id }) => {
+      const data = await send(MessageType.EMULATE_MEDIA, { colorScheme, reducedMotion, printMode, reset, tab_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- hover ---
+  server.tool(
+    'hover',
+    'Hover over an element (mouseenter/mouseover), by CSS selector or ref.',
+    {
+      selector: z.string().optional(),
+      ref: z.string().optional().describe('From get_interactives'),
+      tab_id: z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ selector, ref, tab_id, frame_id }) => {
+      const data = await send(MessageType.HOVER, { selector: resolveTarget(selector, ref, tab_id), tab_id, frame_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- press_key ---
+  server.tool(
+    'press_key',
+    'Press a keyboard key with optional modifiers (keydown/keypress/keyup).',
+    {
+      key: z.string().describe('e.g. "Enter", "Escape", "Tab", "ArrowDown"'),
+      selector: z.string().optional().describe('Target (default: activeElement)'),
+      ctrl: z.boolean().optional().default(false),
+      shift: z.boolean().optional().default(false),
+      alt: z.boolean().optional().default(false),
+      meta: z.boolean().optional().default(false),
+      tab_id: z.number().optional(),
+      frame_id: z.number().optional(),
+    },
+    async ({ key, selector, ctrl, shift, alt, meta, tab_id, frame_id }) => {
+      const data = await send(MessageType.PRESS_KEY, { key, selector, ctrl, shift, alt, meta, tab_id, frame_id });
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText(data),
+        }],
+      };
+    }
+  );
+
+  // --- get_frames ---
+  server.tool(
+    'get_frames',
+    'List frames (main + iframes) with frameId, parent, URL — for the frame_id parameter of DOM tools.',
+    {
+      tab_id: z.number().optional(),
+    },
+    async ({ tab_id }) => {
+      const data = await send(MessageType.GET_FRAMES, { tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- tab_action ---
+  server.tool(
+    'tab_action',
+    'Tab lifecycle actions: close, activate (focus), reload (optional cache bypass), back, forward',
+    {
+      action: z.enum(['close', 'activate', 'reload', 'back', 'forward']),
+      bypass_cache: z.boolean().optional().default(false).describe('reload only'),
+      tab_id: z.number().optional(),
+    },
+    async ({ action, bypass_cache, tab_id }) => {
+      const data = await send(MessageType.TAB_ACTION, { action, bypass_cache, tab_id });
+      if (action === 'close' && (tab_id == null || tab_id === sessionTabId)) sessionTabId = null;
+      if (action === 'activate' && tab_id != null) sessionTabId = tab_id;
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- upload_file ---
+  server.tool(
+    'upload_file',
+    'Set a file on input[type=file] from the server filesystem via DataTransfer (max 10MB).',
+    {
+      selector: z.string(),
+      path: z.string().describe('Absolute path on the server machine'),
+      mime_type: z.string().optional().describe('Default: inferred from extension'),
+      tab_id: z.number().optional(),
+    },
+    async ({ selector, path, mime_type, tab_id }) => {
+      const buf = await readFile(path);
+      if (buf.length > 10 * 1024 * 1024) throw new Error(`File too large: ${buf.length} bytes (max 10MB)`);
+      const mime = mime_type || MIME_BY_EXT[extname(path).toLowerCase()] || 'application/octet-stream';
+      const data = await send(MessageType.UPLOAD_FILE, {
+        selector, name: basename(path), mime_type: mime, content_b64: buf.toString('base64'), tab_id,
+      });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- dismiss_overlays ---
+  server.tool(
+    'dismiss_overlays',
+    'Dismiss cookie banners/modal overlays: OneTrust, Cookiebot, Usercentrics, then generic heuristic. Idempotent.',
+    {
+      tab_id: z.number().optional(),
+    },
+    async ({ tab_id }) => {
+      const data = await send(MessageType.DISMISS_OVERLAYS, { tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- handle_dialogs ---
+  server.tool(
+    'handle_dialogs',
+    'Auto-accept/dismiss future JS dialogs (alert/confirm/prompt), logging them. reset restores native dialogs and returns the log.',
+    {
+      action: z.enum(['accept', 'dismiss', 'reset']).optional().default('accept'),
+      prompt_text: z.string().optional().describe('Returned by window.prompt on accept'),
+      tab_id: z.number().optional(),
+    },
+    async ({ action, prompt_text, tab_id }) => {
+      const data = await send(MessageType.HANDLE_DIALOGS, { action, prompt_text, tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- find_text ---
+  server.tool(
+    'find_text',
+    'Find text on the page: parent selector, context, visibility, position per match. Attaches nearby interactive elements (with refs for click/type_text/hover) for the first visible match.',
+    {
+      text: z.string(),
+      case_sensitive: z.boolean().optional().default(false),
+      max_results: z.number().optional().default(20),
+      tab_id: z.number().optional(),
+    },
+    async ({ text, case_sensitive, max_results, tab_id }) => {
+      const data = await send(MessageType.FIND_TEXT, { text, case_sensitive, max_results, tab_id });
+      // Interactives vicini al primo match visibile, con ref: rende il match
+      // azionabile subito (click sul bottone della stessa riga/sezione).
+      // Nota coordinate: match.position è in coordinate pagina, i rect degli
+      // interactives in coordinate viewport — coincidono a scroll 0 (il flusso
+      // tipico navigate → find_text). Con pagina scrollata il filtro per
+      // distanza non trova candidati e non allega nulla: degradazione sicura.
+      let near = null;
+      const first = (data?.matches ?? []).find((m) => m.visible && m.position);
+      if (first) {
+        try {
+          const inter = await send(MessageType.GET_INTERACTIVES, { limit: 3000, visible_only: true, tab_id });
+          const els = (inter?.elements ?? [])
+            .map((e) => ({ e, dy: Math.abs((e.rect?.y ?? Infinity) - first.position.y), dx: Math.abs((e.rect?.x ?? Infinity) - first.position.x) }))
+            .filter((c) => c.dy <= 150)
+            .sort((a, b) => (a.dy * 4 + a.dx) - (b.dy * 4 + b.dx))
+            .slice(0, 5)
+            .map((c) => c.e);
+          if (els.length) {
+            const refMap = new Map();
+            els.forEach((e, i) => {
+              e.ref = `n${i + 1}`;
+              if (e.selector) refMap.set(e.ref, e.selector);
+            });
+            interactivesRefs.set(refsKey(tab_id), refMap);
+            near = truncateText(interactivesLines({ count: els.length, elements: els, note: 'near first match' }), 1200);
+          }
+        } catch {}
+      }
+      return { content: [{ type: 'text', text: jsonText(data) + (near ? `\n${near}` : '') }] };
+    }
+  );
+
+  // --- network_rules ---
+  server.tool(
+    'network_rules',
+    'Network interception, browser-wide, survives reloads until cleared: block requests, redirect URLs, set/remove request headers, or stub responses with a synthetic body (served by a local helper; from HTTPS pages the stub host must be trustworthy).',
+    {
+      action: z.enum(['block', 'redirect', 'modify_header', 'stub', 'list', 'clear']),
+      url_filter: z.string().optional().describe('declarativeNetRequest urlFilter, e.g. "||example.com/api/*"'),
+      redirect_url: z.string().optional(),
+      header: z.string().optional(),
+      header_value: z.string().optional().describe('Omit to remove header'),
+      header_target: z.enum(['request', 'response']).optional().default('request').describe("response = strip content-security-policy / x-frame-options, inject CORS"),
+      body: z.string().optional().describe('Response body (action=stub)'),
+      status: z.number().optional().default(200).describe('action=stub'),
+      content_type: z.string().optional().default('application/json').describe('action=stub'),
+      resource_types: z.array(z.enum(['main_frame', 'sub_frame', 'stylesheet', 'script', 'image', 'font', 'object', 'xmlhttprequest', 'ping', 'csp_report', 'media', 'websocket', 'other'])).optional(),
+    },
+    async ({ action, url_filter, redirect_url, header, header_value, header_target, body, status, content_type, resource_types }) => {
+      if (action === 'stub') {
+        if (!url_filter) throw new Error('url_filter is required for action=stub');
+        if (body == null) throw new Error('body is required for action=stub');
+        const port = await ensureStubServer();
+        const id = addStub({ body, status: status ?? 200, content_type: content_type ?? 'application/json' });
+        const stub_url = `http://${stubHost()}:${port}/__stub__/${id}`;
+        const data = await send(MessageType.NETWORK_RULES, { action: 'redirect', url_filter, redirect_url: stub_url, resource_types });
+        return { content: [{ type: 'text', text: jsonText({ ...data, stub: id, stub_url }) }] };
+      }
+      if (action === 'clear') clearStubs();
+      const data = await send(MessageType.NETWORK_RULES, { action, url_filter, redirect_url, header, header_value, header_target, resource_types });
+      if (action === 'list') {
+        const stubsInfo = listStubs();
+        if (stubsInfo.length) return { content: [{ type: 'text', text: jsonText({ ...data, stubs: stubsInfo }) }] };
+      }
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- screenshot_diff ---
+  server.tool(
+    'screenshot_diff',
+    'Visual regression: save a named baseline (viewport or element), compare later — returns changed-pixel % and red-highlighted diff image. Baselines are in-memory (lost on service worker restart).',
+    {
+      action: z.enum(['baseline', 'compare', 'list', 'clear']),
+      name: z.string().optional().default('default'),
+      selector: z.string().optional().describe('Capture one element (default viewport)'),
+      threshold: z.number().optional().default(10).describe('Per-channel tolerance 0-255'),
+      tab_id: z.number().optional(),
+    },
+    async ({ action, name, selector, threshold, tab_id }) => {
+      const data = await send(MessageType.SCREENSHOT_DIFF, { action, name, selector, threshold, tab_id });
+      if (data && data.diff_image) {
+        const { diff_image, ...rest } = data;
+        return {
+          content: [
+            { type: 'text', text: jsonText(rest) },
+            { type: 'image', data: diff_image, mimeType: 'image/png' },
+          ],
+        };
+      }
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- web_vitals ---
+  server.tool(
+    'web_vitals',
+    'Core Web Vitals since page load: CLS, LCP, FCP, TTFB, long tasks, INP approximation.',
+    {
+      tab_id: z.number().optional(),
+    },
+    async ({ tab_id }) => {
+      const data = await send(MessageType.WEB_VITALS, { tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- list_event_listeners ---
+  server.tool(
+    'list_event_listeners',
+    'List addEventListener registrations since page load: counts by type + recent entries.',
+    {
+      type: z.string().optional().describe('e.g. "click"'),
+      limit: z.number().optional().default(100),
+      tab_id: z.number().optional(),
+    },
+    async ({ type, limit, tab_id }) => {
+      const data = await send(MessageType.LIST_EVENT_LISTENERS, { type, limit, tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- monitor_websocket ---
+  server.tool(
+    'monitor_websocket',
+    'Monitor WebSocket connections/messages (500-char previews). Hook installs on first call; earlier connections are missed.',
+    {
+      clear: z.boolean().optional().default(false).describe('Clear buffer after read'),
+      tab_id: z.number().optional(),
+    },
+    async ({ clear, tab_id }) => {
+      const data = await send(MessageType.MONITOR_WEBSOCKET, { clear, tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- seo_audit ---
+  server.tool(
+    'seo_audit',
+    'SEO audit: title/description lengths, canonical, robots, h1 count, Open Graph, Twitter card, JSON-LD validity, hreflang, lang, viewport, favicon',
+    {
+      tab_id: z.number().optional(),
+    },
+    async ({ tab_id }) => {
+      const data = await send(MessageType.SEO_AUDIT, { tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- extract_table ---
+  server.tool(
+    'extract_table',
+    'Extract an HTML table as JSON (thead headers, rows as objects). Use `where` to pull only matching rows from a large table without reading it all (server-side filter). `row_count` is always the table total; `match_count` is how many rows pass the filter. index picks among multiple matches.',
+    {
+      selector: z.string().optional().default('table'),
+      index: z.number().optional().default(0),
+      max_rows: z.number().optional().default(100).describe('Max rows returned to you (output cap).'),
+      where: z.record(z.string(), z.string()).optional().describe('Keep only rows where each {column: substring} matches (case-insensitive contains). Use key "any" (or when the table has no headers) to match against any cell.'),
+      columns: z.array(z.string()).optional().describe('Return only these columns per row.'),
+      offset: z.number().optional().default(0).describe('Skip N rows of the (filtered) set before applying max_rows.'),
+      scan_rows: z.number().optional().default(2000).describe('Max rows materialized in-page to scan/filter; raise for very large tables.'),
+      tab_id: z.number().optional(),
+    },
+    async ({ selector, index, max_rows, where, columns, offset, scan_rows, tab_id }) => {
+      const data = await send(MessageType.EXTRACT_TABLE, { selector, index, scan_rows, tab_id });
+      const shaped = shapeTable(data, { where, columns, offset, max_rows });
+      return { content: [{ type: 'text', text: jsonText(shaped) }] };
+    }
+  );
+
+  // --- unused_css ---
+  server.tool(
+    'unused_css',
+    'List CSS selectors matching nothing in the current DOM (approximate; cross-origin sheets unreadable).',
+    {
+      max_selectors: z.number().optional().default(200),
+      tab_id: z.number().optional(),
+    },
+    async ({ max_selectors, tab_id }) => {
+      const data = await send(MessageType.UNUSED_CSS, { max_selectors, tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- drag_and_drop ---
+  server.tool(
+    'drag_and_drop',
+    'Drag an element onto another. html5 = DragEvent+DataTransfer; pointer = pointer/mouse events (sortable libraries).',
+    {
+      source_selector: z.string(),
+      target_selector: z.string(),
+      mode: z.enum(['html5', 'pointer']).optional().default('html5'),
+      frame_id: z.number().optional(),
+      tab_id: z.number().optional(),
+    },
+    async ({ source_selector, target_selector, mode, frame_id, tab_id }) => {
+      const data = await send(MessageType.DRAG_AND_DROP, { source_selector, target_selector, mode, frame_id, tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- clipboard ---
+  server.tool(
+    'clipboard',
+    'Read or write the system clipboard (text). Activates the tab first.',
+    {
+      action: z.enum(['read', 'write']),
+      text: z.string().optional().describe('For write'),
+      tab_id: z.number().optional(),
+    },
+    async ({ action, text, tab_id }) => {
+      const data = await send(MessageType.CLIPBOARD, { action, text, tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- set_geolocation ---
+  server.tool(
+    'set_geolocation',
+    'Override navigator.geolocation with fixed coordinates (page-level patch). reset restores native.',
+    {
+      latitude: z.number().optional(),
+      longitude: z.number().optional(),
+      accuracy: z.number().optional().default(10).describe('Meters'),
+      reset: z.boolean().optional().default(false),
+      tab_id: z.number().optional(),
+    },
+    async ({ latitude, longitude, accuracy, reset, tab_id }) => {
+      const data = await send(MessageType.SET_GEOLOCATION, { latitude, longitude, accuracy, reset, tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- manage_downloads ---
+  server.tool(
+    'manage_downloads',
+    'List downloads or wait for one to complete. Files land in the browser Downloads folder, not on the server.',
+    {
+      action: z.enum(['list', 'wait_for_complete']),
+      timeout: z.number().optional().default(30000).describe('Max ms (wait_for_complete)'),
+      limit: z.number().optional().default(10),
+    },
+    async ({ action, timeout, limit }) => {
+      const data = await send(MessageType.MANAGE_DOWNLOADS, { action, timeout, limit });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- save_page ---
+  server.tool(
+    'save_page',
+    'Save the full page (DOM, styles, images) as an MHTML archive file on the server filesystem.',
+    {
+      output_path: z.string().describe('Absolute file path to write (e.g. /tmp/page.mhtml)'),
+      tab_id: z.number().optional(),
+    },
+    async ({ output_path, tab_id }) => {
+      const data = await send(MessageType.SAVE_PAGE, { tab_id });
+      await writeFile(output_path, Buffer.from(data.mhtml_b64, 'base64'));
+      return { content: [{ type: 'text', text: jsonText({ saved: output_path, size: data.size }) }] };
+    }
+  );
+
+  // --- set_zoom ---
+  server.tool(
+    'set_zoom',
+    'Get or set tab zoom (0.25–5). No factor = read current; reset restores default.',
+    {
+      factor: z.number().optional().describe('1 = 100%'),
+      reset: z.boolean().optional().default(false),
+      tab_id: z.number().optional(),
+    },
+    async ({ factor, reset, tab_id }) => {
+      const data = await send(MessageType.SET_ZOOM, { factor, reset, tab_id });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- http_auth ---
+  server.tool(
+    'http_auth',
+    'Set/clear credentials for HTTP Basic/Digest auth dialogs (browser-wide, in-memory only).',
+    {
+      action: z.enum(['set', 'clear']),
+      username: z.string().optional(),
+      password: z.string().optional(),
+    },
+    async ({ action, username, password }) => {
+      if (action === 'set' && !username) throw new Error('username is required for action=set');
+      const data = await send(MessageType.HTTP_AUTH, { action, username, password });
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- security_headers ---
+  server.tool(
+    'security_headers',
+    'Audit security headers (CSP, HSTS, XCTO, clickjacking, Referrer/Permissions-Policy, version leaks). Captured from real navigations — reload if unavailable.',
+    {
+      tab_id: z.number().optional(),
+    },
+    async ({ tab_id }) => {
+      const data = await send(MessageType.GET_RESPONSE_HEADERS, { tab_id });
+      if (!data.available) {
+        return { content: [{ type: 'text', text: jsonText(data) }] };
+      }
+      const result = evaluateSecurityHeaders(data.headers, data.url);
+      result.status = data.status;
+      return { content: [{ type: 'text', text: jsonText(result) }] };
+    }
+  );
+
+  // --- session_fixture ---
+  server.tool(
+    'session_fixture',
+    'Save/restore localStorage+sessionStorage+cookies as a named fixture (e.g. a logged-in state). Restore requires the tab to be on the origin recorded at save.',
+    {
+      action: z.enum(['save', 'restore', 'list']),
+      name: z.string().optional().describe('Required for save/restore'),
+      tab_id: z.number().optional(),
+    },
+    async ({ action, name, tab_id }) => {
+      if (action === 'list') {
+        const { readdir } = await import('node:fs/promises');
+        let files = [];
+        try { files = (await readdir(SESSIONS_DIR)).filter((f) => f.endsWith('.json')); } catch {}
+        return { content: [{ type: 'text', text: jsonText({ fixtures: files.map((f) => f.replace(/\.json$/, '')) }) }] };
+      }
+      if (!name || !/^[\w-]+$/.test(name)) throw new Error('name is required and must match [\\w-]+');
+      const file = join(SESSIONS_DIR, `${name}.json`);
+
+      // Origin del tab target (match per tab_id, altrimenti tab attivo)
+      const getTabOrigin = async () => {
+        const tabs = await send(MessageType.GET_TABS);
+        const list = Array.isArray(tabs) ? tabs : [];
+        const tab = tab_id != null ? list.find((t) => t.id === tab_id) : list.find((t) => t.active);
+        try { return tab?.url ? new URL(tab.url).origin : null; } catch { return null; }
+      };
+
+      if (action === 'save') {
+        const data = await send(MessageType.GET_STORAGE, { type: 'all', tab_id });
+        const origin = await getTabOrigin();
+        await mkdir(SESSIONS_DIR, { recursive: true });
+        // File su disco per umani: pretty-print qui non costa token
+        await writeFile(file, JSON.stringify({ savedAt: new Date().toISOString(), origin, ...data }, null, 2));
+        return { content: [{ type: 'text', text: jsonText({ saved: name, origin, localStorage: Object.keys(data.localStorage || {}).length, sessionStorage: Object.keys(data.sessionStorage || {}).length, cookies: (data.cookies || []).length }) }] };
+      }
+
+      // restore
+      const fixture = JSON.parse(await readFile(file, 'utf8'));
+      if (fixture.origin) {
+        const currentOrigin = await getTabOrigin();
+        if (currentOrigin && currentOrigin !== fixture.origin) {
+          throw new Error(`Fixture was saved on ${fixture.origin}, current tab is ${currentOrigin} — cookies/storage would attach to the wrong site. Navigate there first.`);
+        }
+      }
+      const restored = { localStorage: 0, sessionStorage: 0, cookies: 0, cookie_errors: [] };
+      for (const storageType of ['localStorage', 'sessionStorage']) {
+        for (const [k, v] of Object.entries(fixture[storageType] || {})) {
+          await send(MessageType.SET_STORAGE, { type: storageType, action: 'set', key: k, value: v, tab_id });
+          restored[storageType]++;
+        }
+      }
+      for (const c of fixture.cookies || []) {
+        try {
+          await send(MessageType.SET_STORAGE, {
+            type: 'cookie', action: 'set', key: c.name, value: c.value,
+            path: c.path, domain: c.domain && c.domain.startsWith('.') ? c.domain : undefined,
+            expires: c.expirationDate ? new Date(c.expirationDate * 1000).toUTCString() : undefined,
+            secure: c.secure, sameSite: c.sameSite === 'no_restriction' ? 'None' : c.sameSite === 'strict' ? 'Strict' : c.sameSite === 'lax' ? 'Lax' : undefined,
+            http_only: c.httpOnly,
+            tab_id,
+          });
+          restored.cookies++;
+        } catch (err) {
+          restored.cookie_errors.push({ name: c.name, error: err.message });
+        }
+      }
+      if (restored.cookie_errors.length === 0) delete restored.cookie_errors;
+      return { content: [{ type: 'text', text: jsonText({ restored: name, ...restored }) }] };
+    }
+  );
+
+  // --- get_interactives ---
+  server.tool(
+    'get_interactives',
+    'List actionable elements (buttons, links, inputs, [role], [onclick]) with ready-to-use CSS selector, label, position, flags. Prefer this over dumping HTML to discover selectors.',
+    {
+      scope: z.string().optional().describe('Limit search (CSS selector)'),
+      limit: z.number().optional().default(100),
+      visible_only: z.boolean().optional().default(true),
+      format: z.enum(['lines', 'json']).optional().default('lines'),
+      frame_id: z.number().optional(),
+      tab_id: z.number().optional(),
+    },
+    async ({ scope, limit, visible_only, format, frame_id, tab_id }) => {
+      const data = await send(MessageType.GET_INTERACTIVES, { scope, limit, visible_only, frame_id, tab_id });
+      // Assegna ref n1..nN e memorizza la mappa ref → selector per click/type_text/hover
+      const refMap = new Map();
+      (data?.elements ?? []).forEach((e, i) => {
+        e.ref = `n${i + 1}`;
+        if (e.selector) refMap.set(e.ref, e.selector);
+      });
+      interactivesRefs.set(refsKey(tab_id), refMap);
+      if ((format ?? 'lines') === 'json') {
+        return { content: [{ type: 'text', text: jsonText(data) }] };
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: truncateText(interactivesLines(data), DEFAULT_MAX_OUTPUT),
+        }],
+      };
+    }
+  );
+
+  // --- extract ---
+  server.tool(
+    'extract',
+    'Extract repeated structured data (rows, cards, lists) in one call: item_selector matches the items, fields map names to relative selectors. Deterministic, parses the main-document HTML server-side.',
+    {
+      item_selector: z.string().describe('CSS selector matching each item'),
+      fields: z.record(z.string(), z.object({
+        selector: z.string().optional().describe('Relative to the item (default: the item itself)'),
+        attr: z.string().optional().describe('Attribute to read (default: text content)'),
+      })).describe('field name → {selector, attr}'),
+      max_items: z.number().optional().default(50),
+      format: z.enum(['lines', 'json']).optional().default('lines'),
+      tab_id: z.number().optional(),
+      max_length: z.number().optional().default(20000).describe('Max output chars'),
+    },
+    async ({ item_selector, fields, max_items, format, tab_id, max_length }) => {
+      max_length = max_length ?? DEFAULT_MAX_OUTPUT;
+      const html = await send(MessageType.READ_PAGE, { mode: 'html', tab_id });
+      if (typeof html !== 'string') throw new Error('Could not read page HTML');
+      const root = parseHtml(html);
+      const names = Object.keys(fields);
+      const nodes = root.querySelectorAll(item_selector);
+      const items = nodes.slice(0, max_items ?? 50).map((node) => {
+        const row = {};
+        for (const name of names) {
+          const { selector, attr } = fields[name];
+          const el = selector ? node.querySelector(selector) : node;
+          const value = el ? (attr ? el.getAttribute(attr) : el.text.trim().replace(/\s+/g, ' ')) : null;
+          row[name] = value ?? null;
+        }
+        return row;
+      });
+      if ((format ?? 'lines') === 'json') {
+        return { content: [{ type: 'text', text: truncateText(JSON.stringify({ total: nodes.length, shown: items.length, items }), max_length, 'max_items or max_length') }] };
+      }
+      const lines = [`extract total=${nodes.length} shown=${items.length}`, names.join('\t'),
+        ...items.map((row) => names.map((n) => row[n] ?? '').join('\t'))];
+      return { content: [{ type: 'text', text: truncateText(lines.join('\n'), max_length, 'max_items or max_length') }] };
+    }
+  );
+
+  // --- assert ---
+  server.tool(
+    'assert',
+    'Assert a page condition, polling until timeout: element exists/visible (optionally with count or containing text), text on page, tab url/title. Patterns: substring, or "/…/" for regex. Recorded flows replay it as a test.',
+    {
+      selector: z.string().optional(),
+      state: z.enum(['attached', 'visible']).optional().default('attached'),
+      text: z.string().optional().describe('In the element (with selector) or anywhere on the page'),
+      count: z.number().optional().describe('Exact match count for selector'),
+      url: z.string().optional().describe('Tab url pattern'),
+      title: z.string().optional().describe('Tab title pattern'),
+      timeout: z.number().optional().default(5000),
+      tab_id: z.number().optional(),
+    },
+    async ({ selector, state, text, count, url, title, timeout, tab_id }) => {
+      const params = { selector, state, text, count, url, title, timeout, tab_id: tab_id ?? sessionTabId ?? undefined };
+      if (recording) {
+        const { tab_id: _tab, ...rest } = params;
+        appendFile(recording.file, JSON.stringify({ command: 'assert', params: rest }) + '\n').catch(() => {});
+      }
+      recordSuppressed++;
+      try {
+        const result = await runAssert(send, params);
+        return { content: [{ type: 'text', text: jsonText(result) }] };
+      } finally {
+        recordSuppressed--;
+      }
+    }
+  );
+
+  // --- session_record ---
+  server.tool(
+    'session_record',
+    'Record the commands of this session as a replayable jsonl file (replay with the CLI: chrome-bridge replay --file <path>). tab_id is stripped — replays target the tab they navigate.',
+    {
+      action: z.enum(['start', 'stop', 'status', 'list']),
+      name: z.string().optional().describe('Required for start'),
+    },
+    async ({ action, name }) => {
+      if (action === 'status') {
+        return { content: [{ type: 'text', text: jsonText(recording ? { recording: recording.name, file: recording.file } : { recording: null }) }] };
+      }
+      if (action === 'list') {
+        const { readdir } = await import('node:fs/promises');
+        let files = [];
+        try { files = (await readdir(RECORDINGS_DIR)).filter((f) => f.endsWith('.jsonl')); } catch {}
+        return { content: [{ type: 'text', text: jsonText({ recordings: files.map((f) => join(RECORDINGS_DIR, f)) }) }] };
+      }
+      if (action === 'start') {
+        if (!name || !/^[\w-]+$/.test(name)) throw new Error('name is required and must match [\\w-]+');
+        await mkdir(RECORDINGS_DIR, { recursive: true });
+        const file = join(RECORDINGS_DIR, `${name}.jsonl`);
+        await writeFile(file, '');
+        recording = { name, file };
+        return { content: [{ type: 'text', text: jsonText({ recording: name, file }) }] };
+      }
+      // stop
+      const stopped = recording;
+      recording = null;
+      await recordChain; // il file deve essere completo quando il tool ritorna
+      return { content: [{ type: 'text', text: jsonText(stopped ? { stopped: stopped.name, file: stopped.file } : { stopped: null }) }] };
+    }
+  );
+}