chrome-bridge-mcp 1.14.0 → 1.15.0

package/README.md

@@ -1,12 +1,12 @@
 # Chrome Bridge
 
-![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-174%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
+![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-187%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
 
 **An MCP server that gives Claude Code your real, logged-in Chrome — measured
 2.75× fewer turns and 2.28× lower cost than the official "Claude in Chrome"
 extension on a form-filling task, with ~3× the toolset and no paid plan.**
 
-62 web-development tools (navigation, DOM inspection, visual regression, audits,
+63 web-development tools (navigation, DOM inspection, visual regression, audits,
 network mocking) over a local WebSocket bridge, plus a headless instance for CI.
 Self-hosted, local-only.
 
@@ -43,7 +43,7 @@ Chrome Bridge → Details (on Chrome 135-137, enable Developer Mode instead).
 | | Chrome Bridge | Claude in Chrome | Chrome DevTools MCP | Playwright MCP |
 |---|---|---|---|---|
 | **ChromeOS / Crostini** | **Yes** (real host) | No | Container only | Container only |
-| **Tools** | **62** (33 core) | ~20 | ~50 | 23 core (71 total) |
+| **Tools** | **63** (34 core) | ~20 | ~50 | 23 core (71 total) |
 | **Requires paid plan** | **No** | Yes (Pro+) | No | No |
 | **Network mocking** | **Yes** (stub/headers) | No | No | Yes |
 | **Visual regression** | **Yes** (`screenshot_diff`) | No | No | No |
@@ -87,7 +87,7 @@ user-script toggle isn't available.
 
 ## Tools
 
-62 in total, in seven groups. Only `core` (33 tools) loads by default; the rest
+63 in total, in seven groups. Only `core` (34 tools) loads by default; the rest
 are opt-in via `--caps`.
 
 | Group | N | What's in it |
@@ -153,7 +153,7 @@ paste into a chat.
 
 ## Documentation
 
-- [docs/TOOLS.md](docs/TOOLS.md) — all 62 tools, by group
+- [docs/TOOLS.md](docs/TOOLS.md) — all 63 tools, by group
 - [docs/EFFICIENCY.md](docs/EFFICIENCY.md) — the benchmark and the design behind it
 - [bench/RESULTS.md](bench/RESULTS.md) — raw runs and inclusion rule
 - [CHANGELOG.md](CHANGELOG.md)

package/extension/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.14.0",
-  "description": "Bridge your browser to Claude Code: 62 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
+  "version": "1.15.0",
+  "description": "Bridge your browser to Claude Code: 63 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
   "homepage_url": "https://github.com/frsorrentino/chrome-bridge",
   "minimum_chrome_version": "135",
   "permissions": [

package/extension/service-worker.js

@@ -941,7 +941,24 @@ async function cmdReadPage({ mode = 'text', tab_id, frame_id }) {
 
 // --- create_tab ---
 
-async function cmdCreateTab({ url, active = true }) {
+async function cmdCreateTab({ url, active = true, new_window = false, left, top, width, height }) {
+  if (new_window) {
+    // windows.create con i bounds apre direttamente sul monitor scelto: left è
+    // la coordinata sulla scrivania virtuale, quindi è ciò che sceglie lo schermo.
+    const winOpts = { focused: active !== false };
+    if (url) winOpts.url = url;
+    for (const [k, v] of [['left', left], ['top', top], ['width', width], ['height', height]]) {
+      if (typeof v === 'number') winOpts[k] = v;
+    }
+    const win = await chrome.windows.create(winOpts);
+    const tab = (win.tabs || [])[0];
+    if (url && tab) {
+      await waitForComplete(tab.id);
+      const updated = await chrome.tabs.get(tab.id);
+      return { id: updated.id, url: updated.url, title: updated.title, window_id: win.id };
+    }
+    return { id: tab?.id, url: tab?.url || 'chrome://newtab', title: tab?.title || '', window_id: win.id };
+  }
   const opts = { active };
   if (url) opts.url = url;
   const tab = await chrome.tabs.create(opts);
@@ -1075,11 +1092,30 @@ async function cmdTileWindows({ window_ids, reference_window_id, layout = 'grid'
   };
 }
 
-async function cmdMoveTab({ tab_id, window_id, index = -1 }) {
+async function cmdMoveTab({ tab_id, window_id, new_window = false, left, top, width, height, index = -1 }) {
   if (typeof tab_id !== 'number') throw new Error('Missing required parameter: tab_id');
-  if (typeof window_id !== 'number') throw new Error('Missing required parameter: window_id');
+  if (typeof window_id !== 'number' && !new_window) throw new Error('Provide window_id or new_window: true');
 
   const before = await chrome.tabs.get(tab_id);
+
+  if (new_window) {
+    // tabs.move vuole una finestra che esiste già; per estrarre in una finestra
+    // nuova (e posizionata) l'unica via è windows.create({tabId}).
+    const winOpts = { tabId: tab_id };
+    for (const [k, v] of [['left', left], ['top', top], ['width', width], ['height', height]]) {
+      if (typeof v === 'number') winOpts[k] = v;
+    }
+    const win = await chrome.windows.create(winOpts);
+    return {
+      moved: tab_id,
+      url: before.url,
+      from_window: before.windowId,
+      to_window: win.id,
+      new_window: true,
+      index: 0,
+      same_window: before.windowId === win.id,
+    };
+  }
   const moved = await chrome.tabs.move(tab_id, { windowId: window_id, index });
   const tab = Array.isArray(moved) ? moved[0] : moved;
 
@@ -1103,6 +1139,21 @@ async function cmdTabAction({ action, tab_id, bypass_cache = false }) {
     await chrome.tabs.remove(tabId);
     return { action, closed: tabId };
   }
+  if (action === 'discard') {
+    // La scheda resta nella barra e si ricarica al focus: il processo muore, la
+    // RAM torna. La tmux session dietro un terminale non c'entra: vive nel
+    // container, non nel renderer.
+    const t = await chrome.tabs.discard(tabId);
+    return { action, tabId: t?.id ?? tabId, discarded: true };
+  }
+  if (action === 'mute' || action === 'unmute') {
+    await chrome.tabs.update(tabId, { muted: action === 'mute' });
+    return { action, tabId, muted: action === 'mute' };
+  }
+  if (action === 'duplicate') {
+    const d = await chrome.tabs.duplicate(tabId);
+    return { action, source: tabId, duplicated: d.id, window_id: d.windowId };
+  }
   if (action === 'activate') {
     const tab = await chrome.tabs.get(tabId);
     await chrome.tabs.update(tabId, { active: true });
@@ -3626,9 +3677,19 @@ async function cmdSetGeolocation({ latitude, longitude, accuracy = 10, reset = f
 
 // --- manage_downloads ---
 
-async function cmdManageDownloads({ action, timeout = 30000, limit = 10 }) {
+async function cmdManageDownloads({ action, url, filename, timeout = 30000, limit = 10 }) {
   if (!action) throw new Error('Missing required parameter: action');
 
+  if (action === 'download') {
+    if (!url) throw new Error('action=download requires url');
+    // Parte dal browser, quindi con i cookie di sessione dell'origine: un file
+    // dietro login si scarica senza far passare i byte dal bridge.
+    const opts = { url, saveAs: false };
+    if (filename) opts.filename = filename;
+    const id = await chrome.downloads.download(opts);
+    return { started: true, id, url };
+  }
+
   if (action === 'list') {
     const items = await chrome.downloads.search({ orderBy: ['-startTime'], limit });
     return {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "type": "module",
-  "description": "MCP server with 62 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
+  "description": "MCP server with 63 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
   "main": "server/index.js",
   "bin": {
     "chrome-bridge-mcp": "server/index.js",

package/server/protocol.js

@@ -84,7 +84,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.14.0';
+export const VERSION               = '1.15.0';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;

package/server/tools.js

@@ -7,7 +7,7 @@
 
 import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, extname, join } from 'node:path';
+import { basename, dirname, extname, join } from 'node:path';
 import { parse as parseHtml } from 'node-html-parser';
 import { z } from 'zod';
 import { runAssert } from './assertions.js';
@@ -19,6 +19,9 @@ import { evaluateSecurityHeaders } from './security-headers.js';
 import { consoleLines, networkLines, interactivesLines, linksLines } from './formatters.js';
 
 const SESSIONS_DIR = join(homedir(), '.config', 'chrome-bridge', 'sessions');
+// Sovrascrivibile nei test: i layout sono un file solo, non una directory.
+const LAYOUTS_FILE = process.env.CHROME_BRIDGE_LAYOUTS_FILE
+  || join(homedir(), '.config', 'chrome-bridge', 'layouts.json');
 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
@@ -291,6 +294,7 @@ export const TOOL_ANNOTATIONS = {
   create_tab: rw({ open: true }),
   move_tab: rw({ idempotent: true }),   // rispostare dove è già = stesso esito
   tile_windows: rw({ idempotent: true }),
+  window_layout: rw({ destructive: true, idempotent: true }),  // save sovrascrive l'omonimo, restore sposta finestre
   navigate: rw({ idempotent: true, open: true }),
   tab_action: rw({ destructive: true, open: true }),  // close chiude una tab dell'utente
 
@@ -876,9 +880,14 @@ export function registerTools(server, wsManager, caps = 'all') {
     {
       url: z.string().optional().describe('URL to open (default: new tab page)'),
       active: z.boolean().optional().default(true).describe('false opens the tab in the background, leaving the current one focused'),
+      new_window: z.boolean().optional().default(false).describe('Open in a fresh window instead of a tab; with left/top it lands on the chosen monitor'),
+      left: z.number().optional().describe('Window x on the virtual desktop (new_window)'),
+      top: z.number().optional().describe('Window y (new_window)'),
+      width: z.number().optional().describe('Window width px (new_window)'),
+      height: z.number().optional().describe('Window height px (new_window)'),
     },
-    async ({ url, active }) => {
-      const data = await send(MessageType.CREATE_TAB, { url, active });
+    async ({ url, active, new_window, left, top, width, height }) => {
+      const data = await send(MessageType.CREATE_TAB, { url, active, new_window: new_window === true || undefined, left, top, width, height });
       if (data?.id != null) sessionTabId = data.id;
       return {
         content: [{
@@ -1342,7 +1351,7 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'tab and anything unsaved in it, and cannot be undone — it may be a tab the user is working in. '
       + 'reload and navigation drop injected CSS, emulations and page hooks.',
     {
-      action: z.enum(['close', 'activate', 'reload', 'back', 'forward']).describe('close cannot be undone; reload drops injected CSS and page hooks'),
+      action: z.enum(['close', 'activate', 'reload', 'back', 'forward', 'discard', 'mute', 'unmute', 'duplicate']).describe('close cannot be undone; discard frees memory, the tab reloads on focus; reload drops injected CSS and hooks'),
       bypass_cache: z.boolean().optional().default(false).describe('reload only'),
       tab_id: tabId,
     },
@@ -1659,12 +1668,15 @@ export function registerTools(server, wsManager, caps = 'all') {
     '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']).describe('wait_for_complete blocks until the newest download finishes or times out'),
+      action: z.enum(['list', 'wait_for_complete', 'download']).describe('download starts one with the browser cookie jar; wait_for_complete blocks until the newest finishes'),
+      url: z.string().optional().describe('What to download (action=download); sent with the session cookies of its origin'),
+      filename: z.string().optional().describe('Relative path inside the Downloads folder (action=download)'),
       timeout: z.number().optional().default(30000).describe('Max ms (wait_for_complete)'),
       limit: z.number().optional().default(10).describe('Max download entries returned, newest first'),
     },
-    async ({ action, timeout, limit }) => {
-      const data = await send(MessageType.MANAGE_DOWNLOADS, { action, timeout, limit });
+    async ({ action, url, filename, timeout, limit }) => {
+      if (action === 'download' && !url) throw new Error('action=download requires url');
+      const data = await send(MessageType.MANAGE_DOWNLOADS, { action, url, filename, timeout, limit });
       return { content: [{ type: 'text', text: jsonText(data) }] };
     }
   );
@@ -1751,11 +1763,19 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'an app window, and the refusal is reported verbatim rather than retried.',
     {
       tab_id: z.number().describe('Tab to move; get it from get_tabs'),
-      window_id: z.number().describe('Destination window; get_tabs reports windowId for every tab'),
+      window_id: z.number().optional().describe('Destination window; get_tabs reports windowId for every tab'),
+      new_window: z.boolean().optional().default(false).describe('Extract the tab into a fresh window instead — tabs.move needs an existing window, this does not'),
+      left: z.number().optional().describe('New window x (new_window)'),
+      top: z.number().optional().describe('New window y (new_window)'),
+      width: z.number().optional().describe('New window width px (new_window)'),
+      height: z.number().optional().describe('New window height px (new_window)'),
       index: z.number().optional().default(-1).describe('Position in the destination window; -1 appends at the end'),
     },
-    async ({ tab_id, window_id, index }) => {
-      const data = await send(MessageType.MOVE_TAB, { tab_id, window_id, index: index ?? -1 });
+    async ({ tab_id, window_id, new_window, left, top, width, height, index }) => {
+      if (window_id == null && new_window !== true) {
+        throw new Error('Provide window_id (an existing window) or new_window: true');
+      }
+      const data = await send(MessageType.MOVE_TAB, { tab_id, window_id, new_window: new_window === true || undefined, left, top, width, height, index: index ?? -1 });
       return { content: [{ type: 'text', text: jsonText(data) }] };
     }
   );
@@ -1786,6 +1806,133 @@ export function registerTools(server, wsManager, caps = 'all') {
     }
   );
 
+  // --- window_layout ---
+  server.tool(
+    'window_layout',
+    'Save the current window arrangement under a name, restore one, list or delete saved ones. save overwrites '
+      + 'a same-named layout without asking. Window ids do not survive a browser restart, so restore recognises '
+      + 'windows by the overlap of their tab URLs (same type required) and repositions the best match — windows '
+      + 'it cannot recognise are reported, not guessed. Needs extension >= 1.14.0 for window geometry.',
+    {
+      action: z.enum(['save', 'restore', 'list', 'delete']).describe('save snapshots every window; restore repositions the recognised ones'),
+      name: z.string().optional().describe('Layout name, required except for list'),
+    },
+    async ({ action, name }) => {
+      const readLayouts = async () => {
+        try { return JSON.parse(await readFile(LAYOUTS_FILE, 'utf8')); } catch { return {}; }
+      };
+
+      if (action === 'list') {
+        const all = await readLayouts();
+        const rows = Object.entries(all).map(([n, l]) => ({ name: n, windows: l.windows.length, savedAt: l.savedAt }));
+        return { content: [{ type: 'text', text: jsonText({ layouts: rows }) }] };
+      }
+
+      if (!name || !/^[\w-]+$/.test(name)) throw new Error('name is required and must match [\\w-]+');
+
+      if (action === 'delete') {
+        const all = await readLayouts();
+        const existed = Boolean(all[name]);
+        delete all[name];
+        await mkdir(dirname(LAYOUTS_FILE), { recursive: true });
+        await writeFile(LAYOUTS_FILE, JSON.stringify(all, null, 2));
+        return { content: [{ type: 'text', text: jsonText({ deleted: name, existed }) }] };
+      }
+
+      // save e restore hanno bisogno della fotografia corrente
+      const snap = await send(MessageType.GET_TABS, { include_windows: true });
+      if (Array.isArray(snap) || !snap?.windows) {
+        // Un'estensione < 1.14.0 risponde con il solo array di schede: meglio
+        // dirlo che fallire su una proprietà mancante.
+        throw new Error('window_layout needs extension >= 1.14.0: get_tabs returned no window geometry');
+      }
+      const urlsByWindow = new Map();
+      for (const t of snap.tabs || []) {
+        if (!urlsByWindow.has(t.windowId)) urlsByWindow.set(t.windowId, []);
+        urlsByWindow.get(t.windowId).push(t.url || '');
+      }
+
+      if (action === 'save') {
+        const all = await readLayouts();
+        all[name] = {
+          savedAt: new Date().toISOString(),
+          windows: snap.windows.map((w) => ({
+            type: w.type,
+            state: w.state,
+            left: w.left, top: w.top, width: w.width, height: w.height,
+            tabs: urlsByWindow.get(w.id) || [],
+          })),
+        };
+        await mkdir(dirname(LAYOUTS_FILE), { recursive: true });
+        await writeFile(LAYOUTS_FILE, JSON.stringify(all, null, 2));
+        return { content: [{ type: 'text', text: jsonText({ saved: name, windows: all[name].windows.length }) }] };
+      }
+
+      // restore
+      const all = await readLayouts();
+      const layout = all[name];
+      if (!layout) {
+        throw new Error(`Layout "${name}" not found — saved: ${Object.keys(all).join(', ') || 'none'}`);
+      }
+
+      // Matching: sovrapposizione degli URL (Jaccard), a parità di tipo. Greedy
+      // sulla coppia migliore. Gli id non entrano mai: non sopravvivono al
+      // riavvio del browser.
+      const current = snap.windows.map((w) => ({ ...w, urls: new Set(urlsByWindow.get(w.id) || []) }));
+      const pairs = [];
+      layout.windows.forEach((savedWin, si) => {
+        current.forEach((cur, ci) => {
+          if (savedWin.type !== cur.type) return;
+          const savedUrls = new Set(savedWin.tabs);
+          let shared = 0;
+          for (const u of savedUrls) if (cur.urls.has(u)) shared += 1;
+          const union = new Set([...savedUrls, ...cur.urls]).size || 1;
+          const score = shared / union;
+          if (score > 0) pairs.push({ si, ci, score });
+        });
+      });
+      pairs.sort((a, b) => b.score - a.score);
+
+      const usedSaved = new Set();
+      const usedCurrent = new Set();
+      const results = [];
+      for (const { si, ci, score } of pairs) {
+        if (usedSaved.has(si) || usedCurrent.has(ci)) continue;
+        usedSaved.add(si); usedCurrent.add(ci);
+        const savedWin = layout.windows[si];
+        const cur = current[ci];
+        const anyTab = (snap.tabs || []).find((t) => t.windowId === cur.id);
+        if (!anyTab) { results.push({ window_id: cur.id, error: 'no tab to address the window with' }); continue; }
+        // Una finestra da massimizzare riceve SOLO lo stato: i bounds verrebbero
+        // accettati e ignorati, e il confronto richiesto/ottenuto mentirebbe.
+        const params = savedWin.state === 'normal'
+          ? { tab_id: anyTab.id, left: savedWin.left, top: savedWin.top, width: savedWin.width, height: savedWin.height, state: 'normal' }
+          : { tab_id: anyTab.id, state: savedWin.state };
+        try {
+          const r = await send(MessageType.VIEWPORT_RESIZE, params);
+          results.push({ window_id: cur.id, score: Number(score.toFixed(2)), requested: params, window: r?.window ?? r?.actual ?? null });
+        } catch (e) {
+          results.push({ window_id: cur.id, score: Number(score.toFixed(2)), error: e.message });
+        }
+      }
+
+      const unmatchedSaved = layout.windows.filter((_, i) => !usedSaved.has(i)).length;
+      const unmatchedCurrent = current.filter((_, i) => !usedCurrent.has(i)).map((w) => w.id);
+      return {
+        content: [{
+          type: 'text',
+          text: jsonText({
+            restored: name,
+            matched: results.length,
+            unmatched_saved: unmatchedSaved,
+            unmatched_current: unmatchedCurrent,
+            results,
+          }),
+        }],
+      };
+    }
+  );
+
   // --- set_zoom ---
   server.tool(
     'set_zoom',