@mehmoodqureshi/chrome-mcp 0.9.11 → 0.9.13

package/README.md

@@ -16,7 +16,9 @@ localhost WebSocket server and drives the browser you already have open, through
 `chrome.scripting`/`chrome.tabs`. Works with Claude Code, Claude Desktop, and any
 other MCP host.
 
-Distributed as an `npx` CLI (the MCP server) plus a load-unpacked extension.
+Distributed as an `npx` CLI (the MCP server) plus an extension, from the
+[Chrome Web Store](https://chromewebstore.google.com/detail/mcp-extension-for-chrome/jelfhdlkhbfmlpbghoeaepijllcnplgh)
+or loaded unpacked.
 
 > **This build is extension-only.** It never launches or attaches a Chromium of
 > its own, so **the extension is required, not optional** — without it, no tool
@@ -27,6 +29,46 @@ Distributed as an `npx` CLI (the MCP server) plus a load-unpacked extension.
 > protocol, the complete tool surface, the extension manifest, the security
 > model, and the phased build plan.
 
+## Use Claude in your signed-in Chrome
+
+You are already signed in to Gmail, GitHub, your analytics dashboards, the admin
+panel, the CRM. chrome-mcp lets Claude (Claude Code, Claude Desktop, or any
+other MCP host) work in those same tabs: no re-login, no second 2FA prompt, no
+password or cookie in a config file. The extension runs inside your normal
+Chrome, so a page the agent opens is the page you would see.
+
+- **Gmail** — read a thread or search results in a tab you already have open.
+- **GitHub** — go through PRs, issues and settings pages as yourself, private
+  repositories included.
+- **Dashboards** — pull numbers from analytics, billing or admin screens that
+  have no API, or whose API you never set up.
+
+Other tools drive a signed-in Chrome too (the `hangwin/mcp-chrome` extension,
+for one), so the question is what you get on top of the session:
+
+- **A per-domain allowlist, deny-all by default.** With no flags the agent can
+  read nothing. `--allow-domain mail.google.com --allow-domain github.com`
+  opens exactly those hosts (`*.example.com` covers a domain and its
+  subdomains); every other site is refused before the call reaches the page.
+  Reads are gated, not only clicks, and the extension re-checks the same policy
+  on its side. Mutations, eval, downloads and uploads are separate opt-ins.
+- **Password values are never returned**, and `--redact` scrubs tokens, API
+  keys and JWTs out of page reads.
+- **An audit trail**: every call is logged with the URL, the allow/deny
+  verdict, duration and bytes returned.
+- **Background tabs and `batch`**: open pages with `active: false` and read many
+  at once in one call, without stealing focus from the tab you are working in.
+- **Several Chrome profiles**: load the extension in your work and personal
+  profiles and switch between them with `profile_use`.
+- **`auth_check`**: when a session does expire, the agent gets an
+  `[AUTH_REQUIRED]` signal instead of a confusing timeout, so it can stop and
+  ask you to sign in again. chrome-mcp never holds credentials or signs in for
+  you.
+
+Setup is two pieces: the MCP server (`npx`, below) and the extension, which you
+can **[install from the Chrome Web Store](https://chromewebstore.google.com/detail/mcp-extension-for-chrome/jelfhdlkhbfmlpbghoeaepijllcnplgh)**
+or load from the folder the server unpacks.
+
 ## Quickstart
 
 ### Up and running in one paste

package/dist/shared/fill-form.d.ts

@@ -29,6 +29,14 @@ export interface FillFormHooks {
         code: FillFormError['code'];
         message: string;
     };
+    /**
+     * Epoch ms after which no further field is started — the moment the server
+     * stops waiting for this command. Without it a timed-out batch kept typing
+     * into the page after the caller had already been told it failed.
+     */
+    deadline?: number;
+    /** Clock, injectable for tests. */
+    now?: () => number;
 }
 type FillFormError = NonNullable<FillFormWireResult['error']>;
 /**

package/dist/shared/fill-form.js

@@ -27,7 +27,16 @@ const policy_1 = require("./policy");
  */
 async function runFillFields(ops, hooks) {
     const res = { filled: 0 };
+    const now = hooks.now ?? Date.now;
     for (const op of ops) {
+        if (hooks.deadline !== undefined && now() >= hooks.deadline) {
+            res.error = {
+                selector: op.selector,
+                code: 'TIMEOUT',
+                message: `fill_form ran out of time after ${res.filled} of ${ops.length} fields; the rest were not written`,
+            };
+            return res;
+        }
         try {
             // Fails CLOSED, exactly as the router does: no policy means nothing runs.
             const policy = hooks.policy();

package/dist/shared/protocol.d.ts

@@ -52,6 +52,19 @@ export interface FillFieldOp {
     /** A string is value-set (cleared first); a boolean toggles via a click. */
     value: string | boolean;
 }
+/** Floor for a batched `fill_form` — the old flat budget, so small forms keep it. */
+export declare const FILL_FORM_MIN_TIMEOUT_MS = 60000;
+/** Per-field allowance: the extension's 5 s element wait plus headroom for the write. */
+export declare const FILL_FORM_PER_FIELD_MS = 6000;
+/** Ceiling, so a runaway field count can't hold the tab for longer than this. */
+export declare const FILL_FORM_MAX_TIMEOUT_MS = 600000;
+/**
+ * Wire timeout for a `fill_form` of `fields` fields. One flat 60 s used to cover
+ * the whole batch, so a long form whose fields each waited for their element
+ * timed out server-side while the extension was still typing. The budget now
+ * grows with the field count (10 s base + 6 s per field), clamped to 60 s..10 min.
+ */
+export declare function fillFormTimeoutMs(fields: number): number;
 /**
  * `fill_form` result. Ops run in order and stop at the first failure, so
  * `filled` counts the fields that landed and `error` names the one that did not.

package/dist/shared/protocol.js

@@ -15,7 +15,8 @@
  * in one round-trip; capability-gated, see `WIRE_CAP_FILL_FORM`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WIRE_METHODS = exports.WIRE_CAP_FILL_FORM = exports.WIRE_CAP_TAB_URL = exports.CLOSE_SUPERSEDED = exports.CLOSE_UNAUTHORIZED = exports.BRIDGE_HOST = exports.DEFAULT_WS_PORT = exports.PROTOCOL_VERSION = void 0;
+exports.WIRE_METHODS = exports.FILL_FORM_MAX_TIMEOUT_MS = exports.FILL_FORM_PER_FIELD_MS = exports.FILL_FORM_MIN_TIMEOUT_MS = exports.WIRE_CAP_FILL_FORM = exports.WIRE_CAP_TAB_URL = exports.CLOSE_SUPERSEDED = exports.CLOSE_UNAUTHORIZED = exports.BRIDGE_HOST = exports.DEFAULT_WS_PORT = exports.PROTOCOL_VERSION = void 0;
+exports.fillFormTimeoutMs = fillFormTimeoutMs;
 /** Bumped on any breaking change to the frames below. */
 exports.PROTOCOL_VERSION = 1;
 /**
@@ -48,6 +49,22 @@ exports.WIRE_CAP_TAB_URL = 'tab-url';
  * field over `type`/`click`, which every extension build understands.
  */
 exports.WIRE_CAP_FILL_FORM = 'fill-form';
+/** Floor for a batched `fill_form` — the old flat budget, so small forms keep it. */
+exports.FILL_FORM_MIN_TIMEOUT_MS = 60_000;
+/** Per-field allowance: the extension's 5 s element wait plus headroom for the write. */
+exports.FILL_FORM_PER_FIELD_MS = 6_000;
+/** Ceiling, so a runaway field count can't hold the tab for longer than this. */
+exports.FILL_FORM_MAX_TIMEOUT_MS = 600_000;
+/**
+ * Wire timeout for a `fill_form` of `fields` fields. One flat 60 s used to cover
+ * the whole batch, so a long form whose fields each waited for their element
+ * timed out server-side while the extension was still typing. The budget now
+ * grows with the field count (10 s base + 6 s per field), clamped to 60 s..10 min.
+ */
+function fillFormTimeoutMs(fields) {
+    const n = Number.isFinite(fields) && fields > 0 ? Math.floor(fields) : 0;
+    return Math.min(exports.FILL_FORM_MAX_TIMEOUT_MS, Math.max(exports.FILL_FORM_MIN_TIMEOUT_MS, 10_000 + n * exports.FILL_FORM_PER_FIELD_MS));
+}
 /** Runtime list of every WireMethod, for boot-time drift assertions on both ends. */
 exports.WIRE_METHODS = [
     'tabs_list',

package/dist/shared/tab-border.d.ts

@@ -0,0 +1,42 @@
+/**
+ * shared/tab-border.ts — the pure half of the "chrome-mcp is working here"
+ * border: choosing its colour from the page's theme and writing the CSS.
+ *
+ * The extension paints the border with `chrome.scripting.insertCSS` on
+ * `html::after`, a user stylesheet rather than a DOM node, so get_html,
+ * get_text and snapshot never see it. Kept free of chrome.* so it is tested
+ * in plain Node.
+ */
+/** Default border colour on a light page. */
+export declare const BORDER_BLUE = "#2563eb";
+/** Default border colour on a dark page (the light blue stays visible). */
+export declare const BORDER_BLUE_ON_DARK = "#60a5fa";
+/** What the page reports about its theme; colours already normalised by a
+ *  canvas `fillStyle` round-trip to `#rrggbb` or `rgba(r, g, b, a)`. */
+export interface PageTheme {
+    /** The matching `<meta name="theme-color">`, or '' when the page has none. */
+    themeColor: string;
+    /** The effective page background (body, else html), or ''. */
+    background: string;
+    /** `prefers-color-scheme: dark`, used when the background is transparent. */
+    prefersDark: boolean;
+}
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Parse `#rgb`, `#rrggbb` or `rgb(a)(...)`; anything else is null. */
+export declare function parseColor(value: string): Rgb | null;
+/**
+ * Pick the border colour for a page:
+ *   1. the site's own theme-color, when it is opaque and stands out from the
+ *      background (so the border matches the site),
+ *   2. otherwise blue, the lighter blue on a dark page.
+ */
+export declare function pickBorderColor(theme: PageTheme): string;
+/** The user stylesheet that draws the border. Only `color` varies, and it is
+ *  always a `#rrggbb` from pickBorderColor or a constant above. */
+export declare function borderCss(color: string): string;
+export {};

package/dist/shared/tab-border.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * shared/tab-border.ts — the pure half of the "chrome-mcp is working here"
+ * border: choosing its colour from the page's theme and writing the CSS.
+ *
+ * The extension paints the border with `chrome.scripting.insertCSS` on
+ * `html::after`, a user stylesheet rather than a DOM node, so get_html,
+ * get_text and snapshot never see it. Kept free of chrome.* so it is tested
+ * in plain Node.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BORDER_BLUE_ON_DARK = exports.BORDER_BLUE = void 0;
+exports.parseColor = parseColor;
+exports.pickBorderColor = pickBorderColor;
+exports.borderCss = borderCss;
+/** Default border colour on a light page. */
+exports.BORDER_BLUE = '#2563eb';
+/** Default border colour on a dark page (the light blue stays visible). */
+exports.BORDER_BLUE_ON_DARK = '#60a5fa';
+/** Parse `#rgb`, `#rrggbb` or `rgb(a)(...)`; anything else is null. */
+function parseColor(value) {
+    const v = value.trim().toLowerCase();
+    let m = /^#([0-9a-f]{3})$/.exec(v);
+    if (m) {
+        const [r, g, b] = m[1].split('').map((c) => parseInt(c + c, 16));
+        return { r, g, b, a: 1 };
+    }
+    m = /^#([0-9a-f]{6})$/.exec(v);
+    if (m) {
+        const n = parseInt(m[1], 16);
+        return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255, a: 1 };
+    }
+    m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+))?\s*\)$/.exec(v);
+    if (m) {
+        return { r: Number(m[1]), g: Number(m[2]), b: Number(m[3]), a: m[4] === undefined ? 1 : Number(m[4]) };
+    }
+    return null;
+}
+function luminance({ r, g, b }) {
+    const lin = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+const toHex = ({ r, g, b }) => '#' + [r, g, b].map((c) => Math.round(c).toString(16).padStart(2, '0')).join('');
+/** A border has to stand out from the page to be worth drawing. */
+const MIN_CONTRAST = 2;
+/**
+ * Pick the border colour for a page:
+ *   1. the site's own theme-color, when it is opaque and stands out from the
+ *      background (so the border matches the site),
+ *   2. otherwise blue, the lighter blue on a dark page.
+ */
+function pickBorderColor(theme) {
+    const bg = parseColor(theme.background);
+    const opaqueBg = bg && bg.a > 0 ? bg : null;
+    const dark = opaqueBg ? luminance(opaqueBg) < 0.2 : theme.prefersDark;
+    const fallback = dark ? exports.BORDER_BLUE_ON_DARK : exports.BORDER_BLUE;
+    const tc = parseColor(theme.themeColor);
+    if (!tc || tc.a < 1)
+        return fallback;
+    const against = opaqueBg ?? (dark ? { r: 0, g: 0, b: 0, a: 1 } : { r: 255, g: 255, b: 255, a: 1 });
+    return contrast(tc, against) >= MIN_CONTRAST ? toHex(tc) : fallback;
+}
+/** The user stylesheet that draws the border. Only `color` varies, and it is
+ *  always a `#rrggbb` from pickBorderColor or a constant above. */
+function borderCss(color) {
+    const c = /^#[0-9a-f]{6}$/i.test(color) ? color : exports.BORDER_BLUE;
+    return ('html::after{content:"" !important;display:block !important;position:fixed !important;' +
+        'inset:0 !important;box-sizing:border-box !important;' +
+        `border:3px solid ${c} !important;box-shadow:inset 0 0 12px ${c}66 !important;` +
+        'pointer-events:none !important;z-index:2147483647 !important;}');
+}
+//# sourceMappingURL=tab-border.js.map

package/dist/src/bridge/auth.d.ts

@@ -56,6 +56,18 @@ export declare const BUNDLED_PAIRING_FILE = "pairing.json";
  * still works without it.
  */
 export declare function writeBundledPairing(extDir: string, fields: WriteHandshakeFields): string | null;
+/** The port an existing `<extDir>/pairing.json` points at, or null when absent/unreadable. */
+export declare function readBundledPairingPort(extDir: string): number | null;
+/** True when something is accepting TCP connections on 127.0.0.1:`port`. */
+export declare function portIsListening(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Should a hub on `port` leave `<extDir>/pairing.json` alone? Yes when the file
+ * already points the extension at a DIFFERENT port that is still live: another
+ * chrome-mcp (e.g. one started with its own CHROME_MCP_DATA / --ws-port) owns
+ * that pairing, and overwriting it would silently steal the user's extension.
+ * A file naming our own port, a dead port, or no file at all is fair game.
+ */
+export declare function bundledPairingHeldByOther(extDir: string, port: number): Promise<boolean>;
 /**
  * Atomically write the handshake at 0600 and verify the mode. Throws (fail
  * closed) if the file ends up group/other-readable — the token is the entire

package/dist/src/bridge/auth.js

@@ -22,6 +22,9 @@ exports.writePersistedToken = writePersistedToken;
 exports.resolveToken = resolveToken;
 exports.tokensMatch = tokensMatch;
 exports.writeBundledPairing = writeBundledPairing;
+exports.readBundledPairingPort = readBundledPairingPort;
+exports.portIsListening = portIsListening;
+exports.bundledPairingHeldByOther = bundledPairingHeldByOther;
 exports.writeHandshake = writeHandshake;
 exports.readHandshake = readHandshake;
 exports.removeHandshake = removeHandshake;
@@ -29,6 +32,7 @@ exports.redactToken = redactToken;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_crypto_1 = require("node:crypto");
+const node_net_1 = require("node:net");
 const protocol_1 = require("../../shared/protocol");
 const datadir_1 = require("./datadir");
 /** A fresh 256-bit token, base64url. Generated once per server boot. */
@@ -146,6 +150,42 @@ function writeBundledPairing(extDir, fields) {
         return null;
     }
 }
+/** The port an existing `<extDir>/pairing.json` points at, or null when absent/unreadable. */
+function readBundledPairingPort(extDir) {
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(extDir, exports.BUNDLED_PAIRING_FILE), 'utf8'));
+        return typeof raw.port === 'number' && Number.isInteger(raw.port) && raw.port > 0 ? raw.port : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when something is accepting TCP connections on 127.0.0.1:`port`. */
+function portIsListening(port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const sock = (0, node_net_1.connect)({ host: '127.0.0.1', port });
+        const done = (live) => {
+            sock.destroy();
+            resolve(live);
+        };
+        sock.setTimeout(timeoutMs, () => done(false));
+        sock.once('connect', () => done(true));
+        sock.once('error', () => done(false));
+    });
+}
+/**
+ * Should a hub on `port` leave `<extDir>/pairing.json` alone? Yes when the file
+ * already points the extension at a DIFFERENT port that is still live: another
+ * chrome-mcp (e.g. one started with its own CHROME_MCP_DATA / --ws-port) owns
+ * that pairing, and overwriting it would silently steal the user's extension.
+ * A file naming our own port, a dead port, or no file at all is fair game.
+ */
+async function bundledPairingHeldByOther(extDir, port) {
+    const current = readBundledPairingPort(extDir);
+    if (current === null || current === port)
+        return false;
+    return portIsListening(current);
+}
 /**
  * Atomically write the handshake at 0600 and verify the mode. Throws (fail
  * closed) if the file ends up group/other-readable — the token is the entire

package/dist/src/cli.js

@@ -223,12 +223,22 @@ async function main() {
         },
     });
     const publishPairing = (port, pairToken) => {
+        // Synchronous so a handshake that can't be made private still fails closed.
         const path = (0, auth_1.writeHandshake)(dataDir, { port, token: pairToken });
         (0, server_2.logErr)(`pairing handshake written to ${path} (mode 0600; token not logged)`);
+        publishBundledPairing(port, pairToken).catch((err) => (0, server_2.logDebug)(`auto-pairing file not written: ${err instanceof Error ? err.message : String(err)}`));
+    };
+    const publishBundledPairing = async (port, pairToken) => {
         // Drop the same port + token into the bundled extension folder so a Load
         // unpacked from there pairs itself. Best-effort: a read-only install just
-        // falls back to the Options-page paste.
+        // falls back to the Options-page paste. Never take over a pairing file that
+        // a different, still-running chrome-mcp published (a second server with its
+        // own data dir or port would otherwise re-point the user's extension).
         const extDir = installExtension();
+        if (await (0, auth_1.bundledPairingHeldByOther)(extDir, port)) {
+            (0, server_2.logErr)(`auto-pairing file at ${extDir} belongs to another running chrome-mcp — left as is; pair this server from the extension Options page if you want it`);
+            return;
+        }
         const bundled = (0, auth_1.writeBundledPairing)(extDir, { port, token: pairToken });
         if (bundled) {
             (0, server_2.logErr)(`auto-pairing file written to ${bundled} — Load unpacked from ${extDir} needs no token paste`);
@@ -238,8 +248,10 @@ async function main() {
         }
         // Anyone who loaded the extension straight from the package folder (0.8.0
         // docs) keeps pairing too.
-        if (extDir !== (0, extension_install_1.bundledExtensionDir)())
-            (0, auth_1.writeBundledPairing)((0, extension_install_1.bundledExtensionDir)(), { port, token: pairToken });
+        const pkgDir = (0, extension_install_1.bundledExtensionDir)();
+        if (extDir !== pkgDir && !(await (0, auth_1.bundledPairingHeldByOther)(pkgDir, port))) {
+            (0, auth_1.writeBundledPairing)(pkgDir, { port, token: pairToken });
+        }
     };
     const port = await bridge.start();
     (0, tools_1.setProfileBridge)(bridge);

package/dist/src/executor/extension-executor.js

@@ -149,7 +149,7 @@ class ExtensionExecutor {
         // An extension that predates the op never advertised it: let the caller go field by field.
         if (!this.bridge.hasCap(this.activeProfile(), protocol_1.WIRE_CAP_FILL_FORM))
             return null;
-        const res = (await this.send('fill_form', { ops: fields, ...frameParams(opts) }, { tabId: opts?.tabId }));
+        const res = (await this.send('fill_form', { ops: fields, ...frameParams(opts) }, { tabId: opts?.tabId, timeoutMs: (0, protocol_1.fillFormTimeoutMs)(fields.length) }));
         if (res.error) {
             // Say how far the batch got: the fields before this one DID land, and a
             // blind retry of the whole form would write them a second time.

package/extension-dist/background.js

@@ -242,7 +242,16 @@
   // shared/fill-form.ts
   async function runFillFields(ops, hooks) {
     const res = { filled: 0 };
+    const now = hooks.now ?? Date.now;
     for (const op of ops) {
+      if (hooks.deadline !== void 0 && now() >= hooks.deadline) {
+        res.error = {
+          selector: op.selector,
+          code: "TIMEOUT",
+          message: `fill_form ran out of time after ${res.filled} of ${ops.length} fields; the rest were not written`
+        };
+        return res;
+      }
       try {
         const policy = hooks.policy();
         if (!policy) throw new PolicyStop("no policy is in force; refusing to fill");
@@ -1171,6 +1180,11 @@
     };
     if (enc.format === "jpeg") params.quality = enc.quality;
     if (plan.clip) params.clip = plan.clip;
+    if (!plan.clip) {
+      const d = measured.dims;
+      params.clip = { x: d.scrollX ?? 0, y: d.scrollY ?? 0, width: d.w, height: d.h, scale: 1 / (d.dpr && d.dpr > 0 ? d.dpr : 1) };
+    }
+    params.captureBeyondViewport = true;
     const data = await withDebugger(tabId, async (target) => {
       const res = await chrome.debugger.sendCommand(target, "Page.captureScreenshot", params);
       return res.data ?? "";
@@ -1527,7 +1541,9 @@
             selector: String(f.selector ?? ""),
             value: typeof f.value === "boolean" ? f.value : String(f.value ?? "")
           }));
+          const deadline = typeof cmd.timeoutMs === "number" && cmd.timeoutMs > 0 ? Date.now() + cmd.timeoutMs - 1e3 : void 0;
           return runFillFields(ops, {
+            deadline,
             currentUrl: () => observedTabUrl(cmd, id),
             policy: () => this.getPolicy(),
             // Frame ids are re-probed per field too: an iframe that navigates
@@ -1808,6 +1824,7 @@
   }
 
   // extension/src/sw/router.ts
+  var CAPTURES = /* @__PURE__ */ new Set(["screenshot", "print_pdf"]);
   var CommandRouter = class {
     constructor(deps) {
       this.deps = deps;
@@ -1830,7 +1847,9 @@
           const verdict = evaluatePolicy(url, cmd.method, policy);
           if (!verdict.ok) throw new CmdError("POLICY_DENIED", verdict.reason);
         }
-        const data = await this.deps.exec.run(cmd, tab);
+        const border2 = this.deps.border;
+        const data = border2 && CAPTURES.has(cmd.method) ? await border2.aroundCapture(tab, () => this.deps.exec.run(cmd, tab)) : await this.deps.exec.run(cmd, tab);
+        if (border2) void this.markBorder(border2, cmd, tab, data);
         const frame = { type: "result", v: PROTOCOL_VERSION, id: cmd.id, ok: true, data };
         const tabUrl = await observedTabUrl(cmd, tab);
         if (tabUrl) frame.tabUrl = tabUrl;
@@ -1849,6 +1868,19 @@
         this.deps.send(frame);
       }
     }
+    /** Border the tab a successful command worked in. Never delays or fails the reply. */
+    async markBorder(border2, cmd, tab, data) {
+      try {
+        if (cmd.method === "tab_new") {
+          const handle = data?.tabId;
+          const id = typeof handle === "string" ? Number(handle.split(":")[2]) : NaN;
+          if (Number.isInteger(id)) await border2.opened(id);
+        } else if (tab !== null && cmd.method !== "tab_close") {
+          await border2.used(tab);
+        }
+      } catch {
+      }
+    }
   };
 
   // extension/src/sw/observers.ts
@@ -1881,10 +1913,204 @@
     }
   }
 
+  // shared/tab-border.ts
+  var BORDER_BLUE = "#2563eb";
+  var BORDER_BLUE_ON_DARK = "#60a5fa";
+  function parseColor(value) {
+    const v = value.trim().toLowerCase();
+    let m = /^#([0-9a-f]{3})$/.exec(v);
+    if (m) {
+      const [r, g, b] = m[1].split("").map((c) => parseInt(c + c, 16));
+      return { r, g, b, a: 1 };
+    }
+    m = /^#([0-9a-f]{6})$/.exec(v);
+    if (m) {
+      const n = parseInt(m[1], 16);
+      return { r: n >> 16 & 255, g: n >> 8 & 255, b: n & 255, a: 1 };
+    }
+    m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+))?\s*\)$/.exec(v);
+    if (m) {
+      return { r: Number(m[1]), g: Number(m[2]), b: Number(m[3]), a: m[4] === void 0 ? 1 : Number(m[4]) };
+    }
+    return null;
+  }
+  function luminance({ r, g, b }) {
+    const lin = (c) => {
+      const s = c / 255;
+      return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+  }
+  function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+  }
+  var toHex = ({ r, g, b }) => "#" + [r, g, b].map((c) => Math.round(c).toString(16).padStart(2, "0")).join("");
+  var MIN_CONTRAST = 2;
+  function pickBorderColor(theme) {
+    const bg = parseColor(theme.background);
+    const opaqueBg = bg && bg.a > 0 ? bg : null;
+    const dark = opaqueBg ? luminance(opaqueBg) < 0.2 : theme.prefersDark;
+    const fallback = dark ? BORDER_BLUE_ON_DARK : BORDER_BLUE;
+    const tc = parseColor(theme.themeColor);
+    if (!tc || tc.a < 1) return fallback;
+    const against = opaqueBg ?? (dark ? { r: 0, g: 0, b: 0, a: 1 } : { r: 255, g: 255, b: 255, a: 1 });
+    return contrast(tc, against) >= MIN_CONTRAST ? toHex(tc) : fallback;
+  }
+  function borderCss(color) {
+    const c = /^#[0-9a-f]{6}$/i.test(color) ? color : BORDER_BLUE;
+    return `html::after{content:"" !important;display:block !important;position:fixed !important;inset:0 !important;box-sizing:border-box !important;border:3px solid ${c} !important;box-shadow:inset 0 0 12px ${c}66 !important;pointer-events:none !important;z-index:2147483647 !important;}`;
+  }
+
+  // extension/src/sw/tab-border.ts
+  var KEY = "borderTabs";
+  async function loadMarked() {
+    const got = await chrome.storage.session.get(KEY).catch(() => ({}));
+    const v = got[KEY];
+    return v && typeof v === "object" ? { ...v } : {};
+  }
+  var saveMarked = (m) => chrome.storage.session.set({ [KEY]: m }).catch(() => void 0);
+  async function enabled() {
+    const { tabBorder } = await chrome.storage.local.get("tabBorder");
+    return tabBorder !== false;
+  }
+  function readPageTheme() {
+    const ctx = document.createElement("canvas").getContext("2d");
+    const norm = (v) => {
+      if (!ctx || !v) return "";
+      ctx.fillStyle = "#010203";
+      ctx.fillStyle = v;
+      const out = String(ctx.fillStyle);
+      return out === "#010203" ? "" : out;
+    };
+    const meta = Array.from(document.querySelectorAll('meta[name="theme-color"]')).find((m) => {
+      const media = m.getAttribute("media");
+      try {
+        return !media || matchMedia(media).matches;
+      } catch {
+        return false;
+      }
+    });
+    const clear = (v) => !v || v === "transparent" || /,\s*0\)$/.test(v);
+    let bg = document.body ? getComputedStyle(document.body).backgroundColor : "";
+    if (clear(bg)) bg = getComputedStyle(document.documentElement).backgroundColor;
+    return {
+      themeColor: norm(meta?.getAttribute("content") ?? ""),
+      background: clear(bg) ? "" : norm(bg),
+      prefersDark: matchMedia("(prefers-color-scheme: dark)").matches
+    };
+  }
+  async function tabAllowed(tabId, policy) {
+    if (!policy) return false;
+    const tab = await chrome.tabs.get(tabId).catch(() => null);
+    return !!tab?.url && evaluatePolicy(tab.url, "get_text", policy).ok;
+  }
+  async function paint(tabId) {
+    try {
+      const [res] = await chrome.scripting.executeScript({ target: { tabId }, func: readPageTheme });
+      const css = borderCss(pickBorderColor(res?.result ?? { themeColor: "", background: "", prefersDark: false }));
+      await chrome.scripting.insertCSS({ target: { tabId }, css, origin: "USER" });
+      return css;
+    } catch {
+      return "";
+    }
+  }
+  async function unpaint(tabId, css) {
+    if (css) await chrome.scripting.removeCSS({ target: { tabId }, css, origin: "USER" }).catch(() => void 0);
+  }
+  var TabBorder = class {
+    constructor(getPolicy) {
+      this.getPolicy = getPolicy;
+    }
+    /** One lock for all border state: parallel batch ops touching the same tab
+     *  must not both inject (removeCSS takes out one copy, not both). */
+    lock = new KeyedMutex();
+    /** Captures in flight per tab: the border comes back after the last one. */
+    capturing = /* @__PURE__ */ new Map();
+    locked(fn) {
+      return this.lock.run("border", fn);
+    }
+    /** A command just ran in `tabId`: border it if it isn't already. */
+    async used(tabId) {
+      return this.locked(async () => {
+        if (!await enabled() || !await tabAllowed(tabId, this.getPolicy())) return;
+        const marked = await loadMarked();
+        if (marked[tabId]) return;
+        marked[tabId] = await paint(tabId);
+        await saveMarked(marked);
+      });
+    }
+    /** A tab opened by tab_new: remember it, and paint once it loads. */
+    async opened(tabId) {
+      return this.locked(async () => {
+        if (!await enabled()) return;
+        const marked = await loadMarked();
+        marked[tabId] = marked[tabId] ?? "";
+        await saveMarked(marked);
+      });
+    }
+    /** A marked tab finished loading a page: the old document took its CSS with
+     *  it, so repaint (the new page may have another theme), or drop the tab if
+     *  it left the allowed sites. */
+    async loaded(tabId) {
+      return this.locked(async () => {
+        const marked = await loadMarked();
+        if (!(tabId in marked)) return;
+        if (!await enabled() || !await tabAllowed(tabId, this.getPolicy())) {
+          await unpaint(tabId, marked[tabId]);
+          delete marked[tabId];
+        } else {
+          await unpaint(tabId, marked[tabId]);
+          marked[tabId] = await paint(tabId);
+        }
+        await saveMarked(marked);
+      });
+    }
+    async closed(tabId) {
+      return this.locked(async () => {
+        const marked = await loadMarked();
+        if (!(tabId in marked)) return;
+        delete marked[tabId];
+        await saveMarked(marked);
+      });
+    }
+    /** Take the border down for a capture (screenshot, PDF) and put it back after. */
+    async aroundCapture(tabId, fn) {
+      if (tabId === null) return fn();
+      const css = await this.locked(async () => {
+        const c = (await loadMarked())[tabId] ?? "";
+        if (c) this.capturing.set(tabId, (this.capturing.get(tabId) ?? 0) + 1);
+        await unpaint(tabId, c);
+        return c;
+      });
+      if (!css) return fn();
+      try {
+        return await fn();
+      } finally {
+        await this.locked(async () => {
+          const left = (this.capturing.get(tabId) ?? 1) - 1;
+          if (left > 0) return void this.capturing.set(tabId, left);
+          this.capturing.delete(tabId);
+          if ((await loadMarked())[tabId] !== css) return;
+          await chrome.scripting.insertCSS({ target: { tabId }, css, origin: "USER" }).catch(() => void 0);
+        });
+      }
+    }
+    /** Server gone or border switched off: clear every tab. */
+    async clearAll() {
+      return this.locked(async () => {
+        const marked = await loadMarked();
+        await Promise.all(Object.entries(marked).map(([id, css]) => unpaint(Number(id), css)));
+        await saveMarked({});
+      });
+    }
+  };
+
   // extension/src/sw/background.ts
   var KEEPALIVE_ALARM = "chrome-mcp-keepalive";
   var currentPolicy = null;
   var executor = new ChromeExecutor(() => currentPolicy);
+  var border = new TabBorder(() => currentPolicy);
   var RECONNECT_DELAYS_MS = [1e3, 2e3, 4e3, 8e3, 1e4];
   var reconnectAttempt = 0;
   var reconnectTimer = null;
@@ -1908,6 +2134,7 @@
       void persistState(state);
       if (state === "connected") clearReconnect();
       else if (state === "idle") scheduleReconnect();
+      if (state === "idle" || state === "unauthorized") void border.clearAll();
       if (state === "unauthorized") void adoptBundledPairing();
     },
     onPolicy: (policy) => {
@@ -1922,7 +2149,8 @@
     exec: executor,
     send: (frame) => ws.send(frame),
     getPolicy: () => currentPolicy,
-    log: (m) => console.debug("[chrome-mcp]", m)
+    log: (m) => console.debug("[chrome-mcp]", m),
+    border
   });
   async function readBundledPairing() {
     try {
@@ -2015,7 +2243,12 @@
   chrome.alarms.onAlarm.addListener((alarm) => {
     if (alarm.name === KEEPALIVE_ALARM) void keepalivePulse();
   });
+  chrome.tabs.onUpdated.addListener((tabId, info) => {
+    if (info.status === "complete") void border.loaded(tabId);
+  });
+  chrome.tabs.onRemoved.addListener((tabId) => void border.closed(tabId));
   chrome.storage.onChanged.addListener((changes, area) => {
+    if (area === "local" && changes.tabBorder?.newValue === false) void border.clearAll();
     if (area === "local" && (changes.wsPort || changes.token || changes.profile)) {
       if (ws.state === "unauthorized") ws.state = "idle";
       if (changes.profile) ws.close();

package/extension-dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "MCP Extension for Chrome",
-  "version": "0.9.8",
+  "version": "0.9.13",
   "description": "Lets a local chrome-mcp server drive this browser. Pair it with the server's handshake token.",
   "homepage_url": "https://chrome-mcp-omega.vercel.app",
   "minimum_chrome_version": "116",

package/extension-dist/options.html

@@ -12,6 +12,8 @@
       .status { margin-top: 1rem; padding: 0.5rem 0.75rem; border-radius: 0.4rem; background: #eef; }
       code { background: #f3f3f3; padding: 0 0.25rem; }
       .hint { color: #555; font-size: 0.9rem; }
+      label.check { display: flex; gap: 0.5rem; align-items: center; font-weight: 600; margin-top: 1rem; }
+      label.check input { width: auto; }
     </style>
   </head>
   <body>
@@ -35,6 +37,11 @@
       <code>profile_use</code>. Type a name here only to pin one yourself.
     </p>
     <p class="hint" id="paired-as"></p>
+    <label class="check"><input id="tab-border" type="checkbox" checked /> Outline the tabs chrome-mcp is working in</label>
+    <p class="hint">
+      A border in the page's theme colour (blue when the site has none) marks every tab the
+      agent is driving. It never shows in screenshots or PDFs, and is removed when the server disconnects.
+    </p>
     <button id="save">Save & connect</button>
     <div class="status" id="status">Status: unknown</div>
     <script src="options.js"></script>

package/extension-dist/options.js

@@ -11,6 +11,9 @@
   var statusEl = document.getElementById("status");
   var sourceEl = document.getElementById("source");
   var pairedAsEl = document.getElementById("paired-as");
+  var borderEl = document.getElementById("tab-border");
+  void chrome.storage.local.get("tabBorder").then(({ tabBorder }) => borderEl.checked = tabBorder !== false);
+  borderEl.addEventListener("change", () => void chrome.storage.local.set({ tabBorder: borderEl.checked }));
   function renderPairedAs(name) {
     pairedAsEl.textContent = typeof name === "string" && name ? `This browser is paired as "${name}".` : "";
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
   "mcpName": "io.github.Mehmoodqureshi/chrome-mcp",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "Drive your real Chrome browser over MCP — real logins, real cookies. A stdio MCP server (CLI) plus an MV3 extension, driving Chrome via chrome.scripting/chrome.tabs. Multi-tab batch automation, accessibility snapshots, deny-all security by default.",
   "author": "Mehmood Ur Rehman Qureshi",
   "license": "MIT",