@mehmoodqureshi/chrome-mcp 0.6.3 → 0.6.5

package/README.md

@@ -4,36 +4,73 @@
 [![npm](https://img.shields.io/npm/v/%40mehmoodqureshi%2Fchrome-mcp?label=npm)](https://www.npmjs.com/package/@mehmoodqureshi/chrome-mcp)
 [![license](https://img.shields.io/npm/l/%40mehmoodqureshi%2Fchrome-mcp?label=license)](LICENSE)
 
-Drive a **real Chrome browser** from Claude (or any MCP host). One pluggable
-`Executor` interface, two backends:
-
-- **Extension (primary):** an MV3 extension drives your real Chrome — real
-  logins, real cookies — via `chrome.scripting`/`chrome.tabs`. The CLI runs a
-  localhost WebSocket server; the extension dials in.
-- **CDP fallback:** when no extension is paired, the CLI launches/attaches a
-  Playwright-driven Chromium for scripted/headless use.
+**Let Claude use the Chrome you are already logged into.** Not a fresh
+automated browser that greets every site as a stranger — *your* Chrome, with
+your sessions, your cookies, your 2FA already done. If you can see a page in
+your browser, your agent can read it, without logging in again and without
+pasting credentials anywhere.
+
+Most browser MCP servers launch their own Chromium and hand your agent a
+signed-out window. chrome-mcp does the opposite: an MV3 extension dials into a
+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.
 
+> **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
+> can run. The CDP flags (`--cdp-fallback`, `--no-cdp-fallback`, `--cdp-endpoint`,
+> `--prefer`) are still accepted for back-compat but are **ignored**.
+
 > **Full design:** [`docs/BLUEPRINT.md`](docs/BLUEPRINT.md) — architecture, wire
 > protocol, the complete tool surface, the extension manifest, the security
 > model, and the phased build plan.
 
 ## Quickstart
 
-**1. Register the MCP server** with your host (e.g. Claude Desktop / Code):
+**1. Register the MCP server** with your host.
+
+<details open>
+<summary><b>Claude Code (terminal)</b> — one command, no config file to find</summary>
+
+```bash
+claude mcp add chrome-mcp -s user -- \
+  npx -y @mehmoodqureshi/chrome-mcp \
+  --allow-domain example.com --enable-mutations --persist-token
+```
+
+Everything **before** `--` belongs to Claude Code; everything **after** it is this
+server's command and flags. Keep the `--` or `--allow-domain` gets read as a
+Claude Code option.
+
+`-s user` registers it for every project on your machine. Use `-s local` (the
+default) for just the current project, or `-s project` to write a `.mcp.json`
+your team can commit.
+
+Check it came up with `claude mcp list`. After upgrading the server, reconnect it
+with `/mcp` inside a session — no restart needed.
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b> and other MCP hosts — JSON config</summary>
 
 ```jsonc
 {
   "mcpServers": {
     "chrome-mcp": {
       "command": "npx",
-      "args": ["-y", "@mehmoodqureshi/chrome-mcp", "--allow-domain", "example.com", "--enable-mutations"]
+      "args": ["-y", "@mehmoodqureshi/chrome-mcp",
+               "--allow-domain", "example.com", "--enable-mutations",
+               "--persist-token"]
     }
   }
 }
 ```
 
+</details>
+
 By default everything is **deny-all** (no domains, no eval, no mutations). Grant
 exactly what you need with `--allow-domain <glob>` (repeatable), `--enable-mutations`,
 `--enable-downloads`, `--enable-uploads`, `--unsafe-enable-eval`, or `--unsafe-all-domains`.
@@ -44,38 +81,82 @@ exactly what you need with `--allow-domain <glob>` (repeatable), `--enable-mutat
 > with `--uploads-dir <path>` to restrict uploads to files inside that directory
 > (`..` traversal is blocked) — strongly recommended for unattended use.
 
-**Drive only your real Chrome (recommended for the extension).** Add
-`--no-cdp-fallback` so the server never launches a separate Chromium, and
-`--persist-token` so the pairing token survives restarts — **pair once, never
-again**:
+**Pair once, never again.** Both examples above include `--persist-token`, which
+is what makes the pairing survive a restart — drop it if you'd rather have the
+stricter default described next.
+
+Without `--persist-token` a fresh token is minted every boot (the secure
+default), which means re-pairing the extension on each restart. With it, the
+token is stored 0600 at `~/.chrome-mcp/token` and reused; the extension's
+keepalive auto-reconnects with no manual step. `CHROME_MCP_TOKEN` pins the token
+explicitly (and is never written to disk).
+
+**2. Load the extension** — **required**; the server can drive nothing without it.
+
+`extension-dist/` ships prebuilt inside the npm package, so there is nothing to
+compile. Install globally to get a stable path to it:
+
+```bash
+npm install -g @mehmoodqureshi/chrome-mcp
+npm root -g     # → <root>; the extension is at <root>/@mehmoodqureshi/chrome-mcp/extension-dist
+```
+
+Then `chrome://extensions` → enable **Developer mode** → **Load unpacked** →
+select that `extension-dist/` directory. (Working from a git clone instead? Run
+`npm install && npm run build:ext` first — `extension-dist/` is gitignored.)
+
+**3. Pair it:** run `npx chrome-mcp --print-pairing` to write the handshake and
+print its path, open the extension's **Options** page, and paste the `port` +
+`token` from `~/.chrome-mcp/handshake.json`.
+
+### Running more than one session
+
+The extension dials exactly **one** bridge port, so only one chrome-mcp can drive
+your Chrome at a time — but every MCP host session (each Claude tab/window)
+spawns its own server. With a pinned `--port`, the newest session **takes the
+port over**: it reads the owning pid from `handshake.json`, confirms that process
+really is a chrome-mcp, and stops it. Newest tab wins; the older session's browser
+tools go quiet until it reconnects. Nothing that isn't a verified chrome-mcp is
+ever touched — a port held by some other program is reported, never killed.
+
+Two servers can only run side by side if each has its own port **and** its own
+paired extension — i.e. a separate Chrome profile running its own copy of the
+extension, pointed at the other port (`--port 9223`). A single Chrome pairs to one
+server at a time, so a second server with no extension of its own can drive
+nothing.
+
+One server can, however, serve **several browsers at once**: connections are
+routed by profile key (`--profile <name>`, matching the profile set in the
+extension's Options), so each paired Chrome gets its own routing slot.
+
+Without `--port`, each server binds an ephemeral port (no conflict ever), but the
+port changes every boot — so you'd re-pair the extension each time. Pin `--port`
+plus `--persist-token` for a pair-once setup.
+
+### Windows
+
+WSL2 is **not** required — native Windows works. One config change is, though:
+on Windows `npx` is `npx.cmd`, a batch shim, and MCP hosts spawn the server
+without a shell, which cannot execute a `.cmd`. So `"command": "npx"` fails to
+start. Wrap it in `cmd /c`:
 
 ```jsonc
 {
   "mcpServers": {
     "chrome-mcp": {
-      "command": "npx",
-      "args": ["-y", "@mehmoodqureshi/chrome-mcp",
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@mehmoodqureshi/chrome-mcp",
                "--allow-domain", "example.com", "--enable-mutations",
-               "--no-cdp-fallback", "--persist-token"]
+               "--persist-token"]
     }
   }
 }
 ```
 
-Without `--persist-token` a fresh token is minted every boot (the secure
-default), which means re-pairing the extension on each restart. With it, the
-token is stored 0600 at `~/.chrome-mcp/token` and reused; the extension's
-keepalive auto-reconnects with no manual step. `CHROME_MCP_TOKEN` pins the token
-explicitly (and is never written to disk).
-
-**2. Load the extension** (to drive your *real* Chrome): build it, then
-`chrome://extensions` → enable Developer mode → **Load unpacked** → select
-`extension-dist/`.
+Or from Claude Code: `claude mcp add chrome-mcp -- cmd /c npx -y @mehmoodqureshi/chrome-mcp --allow-domain example.com`
 
-**3. Pair it:** run `npx chrome-mcp --print-pairing` to write the handshake and
-print its path, open the extension's **Options** page, and paste the `port` +
-`token` from `~/.chrome-mcp/handshake.json`. (Without the extension, the CLI
-falls back to a Playwright-driven Chromium automatically.)
+Everything else is the same — load `extension-dist/` from `npm root -g` and pair
+as above.
 
 The tools cover tabs, navigation, interaction (`click`/`type`/`press`/`hover`/
 `scroll`/`select_option`), reads (`get_text`/`get_html`/`screenshot`/`eval`/`wait_for`),
@@ -183,7 +264,11 @@ chrome-mcp --unsafe-all-domains            # loud footgun
 ```
 
 The per-boot 256-bit token in `~/.chrome-mcp/handshake.json` (mode 0600) is the
-only trust boundary; it is never written to stdout/stderr.
+only trust boundary; it is never written to stdout/stderr. On POSIX the mode is
+re-verified after every write and the server **fails closed** if the file ends up
+group/other-accessible. Windows has no such bits — `chmod` there only toggles the
+read-only attribute — so the check is skipped and the token's confidentiality
+rests on the per-user ACL of `%USERPROFILE%\.chrome-mcp`.
 
 ## Develop
 

package/dist/shared/protocol.d.ts

@@ -27,6 +27,18 @@ export declare const BRIDGE_HOST: "127.0.0.1";
 /** WebSocket close codes we use deliberately. */
 export declare const CLOSE_UNAUTHORIZED: 4401;
 export declare const CLOSE_SUPERSEDED: 4000;
+/**
+ * Capabilities an extension advertises in `hello`. Additive and optional, so an
+ * older extension (which sends none) keeps the conservative behaviour — never
+ * gate a capability behind a version-string comparison.
+ *
+ * `tab-url`: this extension (a) enforces the policy mirror FAIL-CLOSED — it
+ * refuses every command until a policy has arrived — and (b) reports the target
+ * tab's post-command URL as `ResultFrame.tabUrl`. Together those let the server
+ * gate from the reported URL instead of paying a `tabs_list` round-trip before
+ * every call. Without it, the server falls back to fetching the URL itself.
+ */
+export declare const WIRE_CAP_TAB_URL: "tab-url";
 /**
  * Every method that may travel on the wire = the MCP primitives 1:1, plus
  * `download_file` (privileged, executor-owned) and `ping_probe` (a short-deadline
@@ -52,6 +64,9 @@ export interface HelloFrame extends BaseFrame {
      *  NOT a security boundary (the token is) — it selects which connection slot the
      *  server routes commands to, so several browsers can stay paired at once. */
     profile?: string;
+    /** Optional capability advertisements (see `WIRE_CAP_TAB_URL`). An extension
+     *  that sends none gets the conservative path, so old builds stay correct. */
+    caps?: string[];
 }
 /**
  * The wire-serializable subset of the server's policy, delivered in `welcome` so
@@ -92,6 +107,13 @@ export interface ResultFrame extends BaseFrame {
     ok: true;
     /** For `screenshot`: { dataBase64, mimeType, width, height, truncated }. */
     data: unknown;
+    /**
+     * The target tab's URL as observed AFTER the command ran — the extension has
+     * it locally, so sending it costs nothing and saves the server a round-trip
+     * on the next policy gate. Omitted when it can't be resolved (e.g. the tab was
+     * closed). Only sent by extensions advertising `WIRE_CAP_TAB_URL`.
+     */
+    tabUrl?: string;
 }
 export interface ErrorFrame extends BaseFrame {
     type: 'error';

package/dist/shared/protocol.js

@@ -14,7 +14,7 @@
  * wire method beyond the primitives.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WIRE_METHODS = exports.CLOSE_SUPERSEDED = exports.CLOSE_UNAUTHORIZED = exports.BRIDGE_HOST = exports.DEFAULT_WS_PORT = exports.PROTOCOL_VERSION = void 0;
+exports.WIRE_METHODS = exports.WIRE_CAP_TAB_URL = exports.CLOSE_SUPERSEDED = exports.CLOSE_UNAUTHORIZED = exports.BRIDGE_HOST = exports.DEFAULT_WS_PORT = exports.PROTOCOL_VERSION = void 0;
 /** Bumped on any breaking change to the frames below. */
 exports.PROTOCOL_VERSION = 1;
 /**
@@ -29,6 +29,18 @@ exports.BRIDGE_HOST = '127.0.0.1';
 /** WebSocket close codes we use deliberately. */
 exports.CLOSE_UNAUTHORIZED = 4401;
 exports.CLOSE_SUPERSEDED = 4000;
+/**
+ * Capabilities an extension advertises in `hello`. Additive and optional, so an
+ * older extension (which sends none) keeps the conservative behaviour — never
+ * gate a capability behind a version-string comparison.
+ *
+ * `tab-url`: this extension (a) enforces the policy mirror FAIL-CLOSED — it
+ * refuses every command until a policy has arrived — and (b) reports the target
+ * tab's post-command URL as `ResultFrame.tabUrl`. Together those let the server
+ * gate from the reported URL instead of paying a `tabs_list` round-trip before
+ * every call. Without it, the server falls back to fetching the URL itself.
+ */
+exports.WIRE_CAP_TAB_URL = 'tab-url';
 /** Runtime list of every WireMethod, for boot-time drift assertions on both ends. */
 exports.WIRE_METHODS = [
     'tabs_list',

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

@@ -7,6 +7,7 @@
  *     that want a stable token so the extension never has to re-pair.
  *   - Written atomically (tmp + rename) to `handshake.json` at mode 0600; the
  *     mode is re-verified after write and we FAIL CLOSED if it can't be set.
+ *     POSIX only — Windows has no group/other bits to check (see assertPrivate).
  *   - Compared by hashing both sides to SHA-256 and `timingSafeEqual`-ing the
  *     digests — no length precondition, no length leak.
  *   - The token is NEVER written to stdout/stderr or any log (a test asserts it).

package/dist/src/bridge/auth.js

@@ -8,6 +8,7 @@
  *     that want a stable token so the extension never has to re-pair.
  *   - Written atomically (tmp + rename) to `handshake.json` at mode 0600; the
  *     mode is re-verified after write and we FAIL CLOSED if it can't be set.
+ *     POSIX only — Windows has no group/other bits to check (see assertPrivate).
  *   - Compared by hashing both sides to SHA-256 and `timingSafeEqual`-ing the
  *     digests — no length precondition, no length leak.
  *   - The token is NEVER written to stdout/stderr or any log (a test asserts it).
@@ -32,6 +33,23 @@ const datadir_1 = require("./datadir");
 function generateToken() {
     return (0, node_crypto_1.randomBytes)(32).toString('base64url');
 }
+/**
+ * Fail closed if `path` is group/other-accessible.
+ *
+ * No-op on Windows: NTFS ACLs don't map onto the POSIX mode bits, `chmodSync`
+ * there only toggles the read-only attribute, and `statSync` reports a synthetic
+ * 0o666 for any writable file. Enforcing the check would therefore throw on
+ * every well-formed file. The token's confidentiality on Windows rests on the
+ * per-user ACL of the profile directory holding it.
+ */
+function assertPrivate(path, what) {
+    if (process.platform === 'win32')
+        return;
+    const mode = (0, node_fs_1.statSync)(path).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new Error(`${what} ${path} is group/other-accessible (mode ${mode.toString(8)}); refusing to expose the token`);
+    }
+}
 /** Path of the optional persisted-token file (only used when persistence is on). */
 function tokenPath(dir) {
     return (0, node_path_1.join)(dir, 'token');
@@ -50,10 +68,7 @@ function readPersistedToken(dir) {
     catch {
         return null;
     }
-    const mode = (0, node_fs_1.statSync)(path).mode & 0o777;
-    if ((mode & 0o077) !== 0) {
-        throw new Error(`persisted token ${path} is group/other-accessible (mode ${mode.toString(8)}); refusing to reuse it`);
-    }
+    assertPrivate(path, 'persisted token');
     const token = raw.trim();
     return token.length > 0 ? token : null;
 }
@@ -65,10 +80,7 @@ function writePersistedToken(dir, token) {
     (0, node_fs_1.chmodSync)(tmp, 0o600);
     (0, node_fs_1.renameSync)(tmp, path);
     (0, node_fs_1.chmodSync)(path, 0o600);
-    const mode = (0, node_fs_1.statSync)(path).mode & 0o777;
-    if ((mode & 0o077) !== 0) {
-        throw new Error(`persisted token ${path} is group/other-accessible (mode ${mode.toString(8)}); refusing to expose it`);
-    }
+    assertPrivate(path, 'persisted token');
     return path;
 }
 /**
@@ -118,10 +130,7 @@ function writeHandshake(dir, fields) {
     (0, node_fs_1.chmodSync)(tmp, 0o600);
     (0, node_fs_1.renameSync)(tmp, path);
     (0, node_fs_1.chmodSync)(path, 0o600);
-    const mode = (0, node_fs_1.statSync)(path).mode & 0o777;
-    if ((mode & 0o077) !== 0) {
-        throw new Error(`handshake file ${path} is group/other-accessible (mode ${mode.toString(8)}); refusing to expose the token`);
-    }
+    assertPrivate(path, 'handshake file');
     return path;
 }
 function readHandshake(dir) {

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

@@ -17,6 +17,8 @@ export interface ConnectionDeps {
     extId: string;
     sessionId: string;
     heartbeatMs: number;
+    /** Capabilities from `hello` (see WIRE_CAP_TAB_URL). Old builds send none. */
+    caps?: string[];
     onEvent?: (event: WireEvent, data: Record<string, unknown>) => void;
     onClose?: (code: number) => void;
     onLog?: (message: string) => void;
@@ -30,6 +32,10 @@ export declare class ExtensionConnection {
     private closed;
     private heartbeat;
     private missedPongs;
+    /** Whether this extension reports `tabUrl` and gates fail-closed. */
+    private readonly reportsTabUrl;
+    /** Last URL the ACTIVE tab reported, with the wall-clock it arrived. */
+    private activeUrl;
     private readonly onEvent?;
     private readonly onClose?;
     private readonly onLog?;
@@ -43,6 +49,18 @@ export declare class ExtensionConnection {
     isOpen(): boolean;
     private handleMessage;
     private settle;
+    /**
+     * Cache the URL a result rode home with — but ONLY when it describes the active
+     * tab (no explicit tabId) and actually resolved. A blank `tabUrl` means the
+     * extension couldn't read it (closed tab, restricted page), which is a reason
+     * to forget what we knew, never to keep believing it.
+     */
+    private rememberActiveUrl;
+    /**
+     * The active tab's last reported URL if it is younger than `maxAgeMs`, else
+     * null — the caller then resolves it the slow way. Never returns a guess.
+     */
+    lastActiveUrl(maxAgeMs: number): string | null;
     private handleClose;
     private startHeartbeat;
 }

package/dist/src/bridge/connection.js

@@ -36,6 +36,8 @@ function mapWireErrorCode(code) {
     };
     return known[code] ?? 'TARGET_GONE';
 }
+/** Commands that can change WHICH tab is active, invalidating a cached URL. */
+const ACTIVE_TAB_CHANGERS = new Set(['tab_select', 'tab_new', 'tab_close']);
 class ExtensionConnection {
     extId;
     sessionId;
@@ -45,6 +47,10 @@ class ExtensionConnection {
     closed = false;
     heartbeat = null;
     missedPongs = 0;
+    /** Whether this extension reports `tabUrl` and gates fail-closed. */
+    reportsTabUrl;
+    /** Last URL the ACTIVE tab reported, with the wall-clock it arrived. */
+    activeUrl = null;
     onEvent;
     onClose;
     onLog;
@@ -52,6 +58,7 @@ class ExtensionConnection {
         this.ws = deps.ws;
         this.extId = deps.extId;
         this.sessionId = deps.sessionId;
+        this.reportsTabUrl = deps.caps?.includes(protocol_1.WIRE_CAP_TAB_URL) ?? false;
         this.onEvent = deps.onEvent;
         this.onClose = deps.onClose;
         this.onLog = deps.onLog;
@@ -71,6 +78,11 @@ class ExtensionConnection {
         }
         const id = String(++this.seq);
         const timeoutMs = opts?.timeoutMs ?? defaultTimeoutFor(method);
+        // Anything that reshuffles tabs makes the cached URL a claim about a tab that
+        // may no longer be the active one. Drop it before the command, not after, so
+        // a failure mid-flight can't leave a stale entry behind.
+        if (ACTIVE_TAB_CHANGERS.has(method))
+            this.activeUrl = null;
         const frame = {
             type: 'command',
             v: protocol_1.PROTOCOL_VERSION,
@@ -86,7 +98,7 @@ class ExtensionConnection {
                 reject(new types_1.ExecutorError('TIMEOUT', `"${method}" timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             timer.unref?.();
-            this.pending.set(id, { resolve, reject, timer, method });
+            this.pending.set(id, { resolve, reject, timer, method, activeTab: opts?.tabId === undefined });
             try {
                 this.ws.send(JSON.stringify(frame));
             }
@@ -148,12 +160,38 @@ class ExtensionConnection {
         clearTimeout(p.timer);
         this.pending.delete(id);
         if (frame.type === 'result') {
+            this.rememberActiveUrl(p, frame);
             p.resolve(frame.data);
         }
         else {
+            // A failed command tells us nothing reliable about where the tab ended up.
+            if (p.activeTab)
+                this.activeUrl = null;
             p.reject(new types_1.ExecutorError(mapWireErrorCode(frame.error.code), frame.error.message));
         }
     }
+    /**
+     * Cache the URL a result rode home with — but ONLY when it describes the active
+     * tab (no explicit tabId) and actually resolved. A blank `tabUrl` means the
+     * extension couldn't read it (closed tab, restricted page), which is a reason
+     * to forget what we knew, never to keep believing it.
+     */
+    rememberActiveUrl(p, frame) {
+        if (!this.reportsTabUrl || !p.activeTab)
+            return;
+        if (ACTIVE_TAB_CHANGERS.has(p.method))
+            return; // already invalidated; re-caching would race
+        this.activeUrl = frame.tabUrl ? { url: frame.tabUrl, at: Date.now() } : null;
+    }
+    /**
+     * The active tab's last reported URL if it is younger than `maxAgeMs`, else
+     * null — the caller then resolves it the slow way. Never returns a guess.
+     */
+    lastActiveUrl(maxAgeMs) {
+        if (!this.activeUrl)
+            return null;
+        return Date.now() - this.activeUrl.at <= maxAgeMs ? this.activeUrl.url : null;
+    }
     handleClose(code) {
         if (this.closed)
             return;

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

@@ -0,0 +1,32 @@
+/**
+ * src/bridge/evict.ts — take a pinned port back from a stale chrome-mcp.
+ *
+ * The extension dials exactly ONE bridge port, so only one server can own a
+ * given Chrome at a time. But every MCP host session spawns its own chrome-mcp
+ * child, so a second session (another Claude tab/window) racing for a pinned
+ * `--port` would otherwise just fail with EADDRINUSE and force the user to kill
+ * the old process by hand. Newest-session-wins: we do that kill for them.
+ *
+ * The safety bar is high, because a pid can be recycled onto an unrelated
+ * process. We evict ONLY when every check agrees:
+ *   - the handshake names that port (so it describes *this* listener), and
+ *   - the pid is not us, and
+ *   - the pid is alive, and
+ *   - its command line mentions chrome-mcp.
+ * If any check fails we leave the process alone and let the caller surface the
+ * plain-English port-busy error instead. Refusing to evict is always safe; a
+ * wrong kill is not.
+ */
+/** Does this command line belong to a chrome-mcp server? */
+export declare function looksLikeChromeMcp(cmdline: string): boolean;
+export interface EvictDeps {
+    /** Injectable for tests; defaults to the real probes. */
+    isAlive?: (pid: number) => boolean;
+    commandLine?: (pid: number) => string | null;
+    kill?: (pid: number, signal: NodeJS.Signals) => void;
+}
+/**
+ * Try to free `port` by terminating the chrome-mcp that owns it.
+ * Returns true only if an owner was found, killed, and confirmed gone.
+ */
+export declare function evictPortOwner(dataDir: string, port: number, log: (message: string) => void, deps?: EvictDeps): Promise<boolean>;

package/dist/src/bridge/evict.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * src/bridge/evict.ts — take a pinned port back from a stale chrome-mcp.
+ *
+ * The extension dials exactly ONE bridge port, so only one server can own a
+ * given Chrome at a time. But every MCP host session spawns its own chrome-mcp
+ * child, so a second session (another Claude tab/window) racing for a pinned
+ * `--port` would otherwise just fail with EADDRINUSE and force the user to kill
+ * the old process by hand. Newest-session-wins: we do that kill for them.
+ *
+ * The safety bar is high, because a pid can be recycled onto an unrelated
+ * process. We evict ONLY when every check agrees:
+ *   - the handshake names that port (so it describes *this* listener), and
+ *   - the pid is not us, and
+ *   - the pid is alive, and
+ *   - its command line mentions chrome-mcp.
+ * If any check fails we leave the process alone and let the caller surface the
+ * plain-English port-busy error instead. Refusing to evict is always safe; a
+ * wrong kill is not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.looksLikeChromeMcp = looksLikeChromeMcp;
+exports.evictPortOwner = evictPortOwner;
+const node_child_process_1 = require("node:child_process");
+const auth_1 = require("./auth");
+/** How long to let a SIGTERM'd owner exit before escalating to SIGKILL. */
+const EXIT_WAIT_MS = 3_000;
+const POLL_MS = 100;
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Whether `pid` exists. Signal 0 checks liveness without delivering anything. */
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists but belongs to another user — alive, just not ours.
+        return err?.code === 'EPERM';
+    }
+}
+/**
+ * Full command line of `pid`, or null if it can't be read.
+ *
+ * Windows needs PowerShell/CIM: `tasklist` reports only the image name
+ * ("node.exe"), which can't distinguish chrome-mcp from any other Node process
+ * — far too weak a signal to kill on.
+ */
+function commandLine(pid) {
+    const [cmd, args] = process.platform === 'win32'
+        ? [
+            'powershell.exe',
+            [
+                '-NoProfile',
+                '-Command',
+                `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CommandLine`,
+            ],
+        ]
+        : ['ps', ['-p', String(pid), '-o', 'command=']];
+    try {
+        const out = (0, node_child_process_1.execFileSync)(cmd, args, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        });
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Does this command line belong to a chrome-mcp server? */
+function looksLikeChromeMcp(cmdline) {
+    return /chrome-mcp/i.test(cmdline);
+}
+/**
+ * Try to free `port` by terminating the chrome-mcp that owns it.
+ * Returns true only if an owner was found, killed, and confirmed gone.
+ */
+async function evictPortOwner(dataDir, port, log, deps = {}) {
+    const alive = deps.isAlive ?? isAlive;
+    const cmdOf = deps.commandLine ?? commandLine;
+    const kill = deps.kill ?? ((pid, sig) => process.kill(pid, sig));
+    let pid;
+    let hsPort;
+    try {
+        const hs = (0, auth_1.readHandshake)(dataDir);
+        pid = Number(hs?.pid);
+        hsPort = Number(hs?.port);
+    }
+    catch {
+        return false; // no handshake (clean shutdown) or unreadable — nothing to evict
+    }
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    // The handshake describes a different listener; it says nothing about ours.
+    if (hsPort !== port)
+        return false;
+    if (pid === process.pid)
+        return false;
+    if (!alive(pid))
+        return false;
+    const cmdline = cmdOf(pid);
+    if (!cmdline || !looksLikeChromeMcp(cmdline)) {
+        log(`port ${port} is held by pid ${pid}, which does not look like chrome-mcp — ` +
+            `leaving it alone. Stop it yourself, or use a different --port.`);
+        return false;
+    }
+    log(`port ${port} is held by chrome-mcp pid ${pid} (another session) — taking the port over`);
+    try {
+        kill(pid, 'SIGTERM');
+    }
+    catch {
+        return false; // vanished or not ours to signal
+    }
+    const deadline = Date.now() + EXIT_WAIT_MS;
+    while (Date.now() < deadline) {
+        if (!alive(pid)) {
+            log(`previous owner (pid ${pid}) exited; reclaiming port ${port}`);
+            return true;
+        }
+        await delay(POLL_MS);
+    }
+    // Wouldn't go quietly.
+    try {
+        kill(pid, 'SIGKILL');
+    }
+    catch {
+        /* already gone */
+    }
+    const gone = !alive(pid);
+    if (gone)
+        log(`previous owner (pid ${pid}) force-killed; reclaiming port ${port}`);
+    return gone;
+}
+//# sourceMappingURL=evict.js.map

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

@@ -26,6 +26,9 @@ export interface BridgeOptions {
     port?: number;
     host?: string;
     heartbeatMs?: number;
+    /** Data dir holding the handshake. Enables reclaiming a pinned port from a
+     *  stale chrome-mcp (see ./evict). Omit to disable eviction entirely. */
+    dataDir?: string;
     /** Diagnostics — MUST never receive the token (a test asserts this). */
     onLog?: (message: string) => void;
     onDisplacement?: (info: DisplacementInfo) => void;
@@ -62,6 +65,12 @@ export declare class BridgeServer {
         timeoutMs?: number;
         profile?: string;
     }): Promise<unknown>;
+    /**
+     * The active tab's URL for `profile` as last reported by the extension, if it
+     * is younger than `maxAgeMs`. Null means "ask properly" — an extension too old
+     * to report URLs, a tab shuffle since, or simply nothing recent enough.
+     */
+    lastActiveUrl(profile: string | undefined, maxAgeMs: number): string | null;
     private noPairMessage;
     status(): {
         extensionConnected: boolean;

package/dist/src/bridge/server.js

@@ -20,6 +20,7 @@ const policy_1 = require("../../shared/policy");
 const types_1 = require("../executor/types");
 const connection_1 = require("./connection");
 const auth_1 = require("./auth");
+const evict_1 = require("./evict");
 const config_1 = require("../config");
 /** The routing label for a hello with no/blank profile — the back-compat default. */
 const DEFAULT_PROFILE = 'default';
@@ -46,11 +47,12 @@ const delay = (ms) => new Promise((r) => setTimeout(r, ms));
 /** A friendly, actionable message for the rare case the port stays busy past PORT_WAIT_MS. */
 function portBusyMessage(host, port) {
     return (`Couldn't start: another program is already using ${host}:${port}.\n` +
-        `This is almost always a previous chrome-mcp that didn't shut down. To fix it:\n` +
-        `  1. Fully quit/restart your MCP host (e.g. Claude Code), or\n` +
-        `  2. Stop the leftover process, then reconnect:\n` +
+        `A stale chrome-mcp is reclaimed automatically, so this is some OTHER program.\n` +
+        `To fix it:\n` +
+        `  1. Stop whatever owns the port, then reconnect:\n` +
         `       macOS/Linux:  lsof -nP -iTCP:${port} -sTCP:LISTEN   then  kill <PID>\n` +
-        `  3. Or run chrome-mcp with a different port:  --port <number>`);
+        `       Windows:      netstat -ano | findstr :${port}        then  taskkill /PID <PID> /F\n` +
+        `  2. Or run chrome-mcp with a different port:  --port <number>`);
 }
 class BridgeServer {
     opts;
@@ -76,6 +78,7 @@ class BridgeServer {
         // wait-and-retry for a few seconds so the old process can release it; only if
         // it never frees up do we surface a plain-English, actionable error.
         const deadline = Date.now() + PORT_WAIT_MS;
+        let evicted = false;
         for (let attempt = 1;; attempt++) {
             try {
                 const wss = await this.listenOnce(host, port);
@@ -87,11 +90,20 @@ class BridgeServer {
             }
             catch (err) {
                 const inUse = err?.code === 'EADDRINUSE';
-                if (!inUse || port === 0 || Date.now() >= deadline) {
-                    if (inUse)
-                        throw new Error(portBusyMessage(host, port));
-                    throw err;
+                if (!inUse || port === 0)
+                    throw inUse ? new Error(portBusyMessage(host, port)) : err;
+                // A live chrome-mcp from another session will never release the port on
+                // its own, so waiting it out is futile — take it over (once). Only a
+                // verified chrome-mcp is ever killed; anything else falls through to the
+                // wait-and-retry below, which covers our own just-replaced instance.
+                if (!evicted && this.opts.dataDir) {
+                    evicted = true;
+                    if (await (0, evict_1.evictPortOwner)(this.opts.dataDir, port, (m) => this.log(m))) {
+                        continue;
+                    }
                 }
+                if (Date.now() >= deadline)
+                    throw new Error(portBusyMessage(host, port));
                 if (attempt === 1)
                     this.log(`port ${host}:${port} busy — waiting for the previous instance to release it…`);
                 await delay(PORT_RETRY_MS);
@@ -166,6 +178,15 @@ class BridgeServer {
         }
         return conn.sendCommand(method, params, opts);
     }
+    /**
+     * The active tab's URL for `profile` as last reported by the extension, if it
+     * is younger than `maxAgeMs`. Null means "ask properly" — an extension too old
+     * to report URLs, a tab shuffle since, or simply nothing recent enough.
+     */
+    lastActiveUrl(profile, maxAgeMs) {
+        const conn = this.conns.get(routeKey(profile));
+        return conn?.isOpen() ? conn.lastActiveUrl(maxAgeMs) : null;
+    }
     noPairMessage(profile) {
         return (`No browser is paired for profile "${profile}". In that Chrome's chrome-mcp ` +
             `extension Options, set Port ${this.boundPort}, paste the token, set Profile to ` +
@@ -223,7 +244,7 @@ class BridgeServer {
             authed = true;
             clearTimeout(helloTimer);
             ws.off('message', onMessage);
-            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' }, routeKey(frame.profile));
+            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' }, routeKey(frame.profile), Array.isArray(frame.caps) ? frame.caps : undefined);
         };
         ws.on('message', onMessage);
         ws.on('error', () => {
@@ -240,7 +261,7 @@ class BridgeServer {
             /* ignore */
         }
     }
-    promote(ws, ext, profile) {
+    promote(ws, ext, profile, caps) {
         const sessionId = (0, node_crypto_1.randomUUID)();
         // Supersede only the SAME profile's connection (a re-pair). Other profiles
         // keep their live connections, so several browsers stay paired at once.
@@ -263,6 +284,7 @@ class BridgeServer {
             extId: ext.id,
             sessionId,
             heartbeatMs: this.heartbeatMs,
+            caps,
             onEvent: this.opts.onEvent,
             onLog: (m) => this.log(m),
             onClose: () => {

package/dist/src/cli.js

@@ -159,6 +159,7 @@ async function main() {
         // Wire-serializable policy subset (no local uploadsDir) so the extension mirrors the gate.
         policy: { allowDomains, allowEval, allowDownloads, allowUploads, allowAllTabs, enableMutations },
         port: cfg.wsPort,
+        dataDir,
         onLog: (m) => (0, server_2.logErr)(m),
         onDisplacement: (d) => (0, server_2.logErr)(`SECURITY: extension connection displaced (different id: ${d.differentId})`),
     });

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

@@ -65,8 +65,14 @@ function clearProfileLocks(profileDir) {
     }
 }
 function isChromiumProcess(pid) {
+    // Windows has no `ps`; tasklist is the equivalent and is a real .exe, so it
+    // needs no shell. Its CSV row leads with the image name (e.g. "chrome.exe"),
+    // and the no-match case prints an INFO line that fails the same test.
+    const [cmd, args] = process.platform === 'win32'
+        ? ['tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH']]
+        : ['ps', ['-p', String(pid), '-o', 'command=']];
     try {
-        const out = (0, node_child_process_1.execFileSync)('ps', ['-p', String(pid), '-o', 'command='], {
+        const out = (0, node_child_process_1.execFileSync)(cmd, args, {
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'ignore'],
         });

package/dist/src/executor/extension-executor.d.ts

@@ -21,6 +21,9 @@ export declare class ExtensionExecutor implements Executor {
     ensureReady(): Promise<void>;
     ping(deadlineMs?: number): Promise<boolean>;
     dispose(): Promise<void>;
+    /** The active tab's URL as reported by the last command on this profile, if it
+     *  is fresh enough to gate against. See `ACTIVE_URL_TTL_MS`. */
+    cachedActiveUrl(): string | null;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
     tabNew(url?: string, opts?: {

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

@@ -12,6 +12,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExtensionExecutor = void 0;
 const types_1 = require("./types");
 const workspace_1 = require("../bridge/workspace");
+/**
+ * How long a reported active-tab URL stays usable for the policy gate.
+ *
+ * Deliberately short. It exists to cover back-to-back calls (a `batch`, or an
+ * agent's read → click → read), where the tab demonstrably has not changed
+ * between them. Past that, pay the round-trip. Note the extension re-gates every
+ * command against the tab's live URL regardless, so this window trades a little
+ * pre-check precision for half the traffic — never enforcement itself.
+ */
+const ACTIVE_URL_TTL_MS = 1_000;
 /** Flatten a Target into the params a wire command carries. */
 function targetParams(t) {
     if (!t)
@@ -64,6 +74,11 @@ class ExtensionExecutor {
     async dispose() {
         // Never close the user's Chrome.
     }
+    /** The active tab's URL as reported by the last command on this profile, if it
+     *  is fresh enough to gate against. See `ACTIVE_URL_TTL_MS`. */
+    cachedActiveUrl() {
+        return this.bridge.lastActiveUrl(this.activeProfile(), ACTIVE_URL_TTL_MS);
+    }
     // -- tabs ---------------------------------------------------------------
     async tabsList() {
         return (await this.send('tabs_list', {}));

package/dist/src/executor/stub-executor.d.ts

@@ -13,14 +13,32 @@ export interface StubOptions {
     activeUrl?: string;
     /** When true, `eval` resolves `{ok:false}` to mimic a page-side throw. */
     evalThrows?: boolean;
+    /** When true, `tabsList` rejects — mimics a transient bridge failure. */
+    tabsListThrows?: boolean;
+    /** When true, `tabsList` resolves empty — mimics a browser reporting no tabs. */
+    noTabs?: boolean;
+    /** When true, the (single) tab reports an empty URL — mimics a chrome:// page
+     *  or a site the extension has no host access to. */
+    blankTabUrl?: boolean;
+    /** A URL the backend claims to already know, as the extension reports on every
+     *  result frame. Set it to assert the gate uses it INSTEAD of calling tabsList. */
+    cachedUrl?: string;
 }
 export declare class StubExecutor implements Executor {
     readonly backend: BackendKind;
     private url;
     private readonly evalThrows;
+    private readonly tabsListThrows;
+    private readonly noTabs;
+    private readonly blankTabUrl;
+    private readonly cached;
+    /** How many times the gate actually asked for the tab list — the round-trip
+     *  counter the caching path exists to keep at zero. */
+    tabsListCalls: number;
     private ready;
     constructor(opts?: StubOptions);
     private tab;
+    cachedActiveUrl(): string | null;
     status(): ExecutorStatus;
     ensureReady(): Promise<void>;
     ping(): Promise<boolean>;

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

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StubExecutor = void 0;
+const types_1 = require("./types");
 /** 1×1 transparent PNG, base64 — a valid image block for screenshot tests. */
 const TINY_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
 const ok = { ok: true };
@@ -17,13 +18,33 @@ class StubExecutor {
     backend = 'extension';
     url;
     evalThrows;
+    tabsListThrows;
+    noTabs;
+    blankTabUrl;
+    cached;
+    /** How many times the gate actually asked for the tab list — the round-trip
+     *  counter the caching path exists to keep at zero. */
+    tabsListCalls = 0;
     ready = false;
     constructor(opts = {}) {
         this.url = opts.activeUrl ?? 'about:blank';
         this.evalThrows = opts.evalThrows ?? false;
+        this.tabsListThrows = opts.tabsListThrows ?? false;
+        this.noTabs = opts.noTabs ?? false;
+        this.blankTabUrl = opts.blankTabUrl ?? false;
+        this.cached = opts.cachedUrl ?? null;
     }
     tab() {
-        return { tabId: 'extension:stub:1', url: this.url, title: 'Stub Page', active: true, index: 0 };
+        return {
+            tabId: 'extension:stub:1',
+            url: this.blankTabUrl ? '' : this.url,
+            title: 'Stub Page',
+            active: true,
+            index: 0,
+        };
+    }
+    cachedActiveUrl() {
+        return this.cached;
     }
     status() {
         return {
@@ -44,7 +65,10 @@ class StubExecutor {
         this.ready = false;
     }
     async tabsList() {
-        return [this.tab()];
+        this.tabsListCalls++;
+        if (this.tabsListThrows)
+            throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub bridge is down');
+        return this.noTabs ? [] : [this.tab()];
     }
     async tabSelect(tabId) {
         return { ...this.tab(), tabId };

package/dist/src/executor/types.d.ts

@@ -155,6 +155,14 @@ export interface Executor {
     ping(deadlineMs?: number): Promise<boolean>;
     /** Close ONLY if we own the browser; never the user's Chrome. */
     dispose(): Promise<void>;
+    /**
+     * The active tab's URL if the backend ALREADY knows it — the extension reports
+     * it on every result frame, so a gate that runs right after a command needs no
+     * round-trip. Null means "not known recently enough", and the caller must then
+     * resolve it properly; it never returns a guess. Optional: backends that can't
+     * report cheaply simply omit it.
+     */
+    cachedActiveUrl?(): string | null;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
     /** Open a tab. `active` (default true) focuses it; pass false to open in the background. */

package/dist/src/mcp/tools.js

@@ -81,19 +81,60 @@ exports.TOOL_DEFINITIONS = [
         },
     },
 ];
-/** Resolve the URL the policy should be evaluated against (the active tab). */
+const GATE_CONTEXT = 'cannot resolve the active tab URL for the policy gate';
+/**
+ * Resolve the URL the policy should be evaluated against (the active tab).
+ *
+ * NEVER substitutes a placeholder URL. If the tab list can't be read, the real
+ * origin is unknown, and evaluating the policy against a fabricated URL would
+ * silently allow or deny against the wrong origin with no signal to the caller.
+ * So a `tabsList` failure (or a browser reporting no tabs at all) propagates —
+ * the dispatch firewall renders it as a structured error carrying the code.
+ *
+ * Prefers a URL the backend already reported over asking again: the extension
+ * rides the tab's landing URL home on every result frame, which is what keeps a
+ * gated call to ONE round-trip instead of two.
+ */
 async function activeUrl(ex) {
+    const known = ex.cachedActiveUrl?.();
+    if (known)
+        return known;
+    let tabs;
     try {
-        const tabs = await ex.tabsList();
-        return tabs.find((t) => t.active)?.url ?? tabs[0]?.url ?? 'about:blank';
+        tabs = await ex.tabsList();
     }
-    catch {
-        return 'about:blank';
+    catch (err) {
+        // Keep the underlying code (TIMEOUT / EXTENSION_DISCONNECTED / …) so the
+        // caller can tell a transient bridge failure from a policy decision — the
+        // rendered message is prefixed with it, since only the text crosses MCP.
+        if (err instanceof types_1.ExecutorError)
+            throw new types_1.ExecutorError(err.code, `${GATE_CONTEXT}: ${err.message}`);
+        throw err; // an internal fault, not a browser one — don't relabel it
     }
+    const active = tabs.find((t) => t.active) ?? tabs[0];
+    if (!active)
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the browser reports no open tabs`);
+    // An empty URL is Chrome declining to reveal one (a chrome:// page, or a tab
+    // the extension has no host access to) — NOT an origin. Gating on '' would
+    // produce a baffling "blocked on " denial that reads like a policy decision.
+    if (!active.url) {
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the active tab (id ${active.tabId}) reports no URL. Chrome hides it for ` +
+            `internal pages (chrome://, the Web Store) and until the extension has access to that site — ` +
+            `switch to a normal page, or open the target site in a new tab.`);
+    }
+    return active.url;
 }
-/** Policy chokepoint. `urlOverride` is the destination for navigation. */
+/**
+ * Policy chokepoint. `urlOverride` is the destination for navigation.
+ *
+ * Only resolves the active URL for methods whose verdict actually depends on one
+ * (`isUrlGated`). Tab management and the capability gates — eval, downloads,
+ * uploads, mutations — are decided without any URL, so making them wait on the
+ * tab list bought nothing and, worse, made `tab_new` fail exactly when the tab
+ * list was unreadable: the one call that could dig you out.
+ */
 async function gate(ctx, method, urlOverride) {
-    const url = urlOverride ?? (await activeUrl(ctx.ex));
+    const url = urlOverride ?? ((0, policy_1.isUrlGated)(method) ? await activeUrl(ctx.ex) : '');
     (0, policy_1.assertUrlAllowed)(url, method, ctx.policy);
 }
 const tabId = (args) => (0, validators_1.optionalString)(args, 'tabId');
@@ -349,7 +390,12 @@ exports.TOOL_HANDLERS = {
 // Dispatch (never-throw firewall)
 // ---------------------------------------------------------------------------
 function errMessage(err) {
-    if (err instanceof validators_1.McpToolError || err instanceof types_1.ExecutorError)
+    // Only the text crosses the MCP boundary, so the code has to travel inside it —
+    // otherwise a caller cannot tell EXTENSION_DISCONNECTED (retry in a moment)
+    // from POLICY_DENIED (retrying will never help).
+    if (err instanceof types_1.ExecutorError)
+        return `[${err.code}] ${err.message}`;
+    if (err instanceof validators_1.McpToolError)
         return err.message;
     if (err instanceof Error)
         return `internal error: ${err.message}`;

package/extension-dist/background.js

@@ -2,6 +2,7 @@
 (() => {
   // shared/protocol.ts
   var PROTOCOL_VERSION = 1;
+  var WIRE_CAP_TAB_URL = "tab-url";
   var WIRE_METHODS = [
     "tabs_list",
     "tab_select",
@@ -63,7 +64,11 @@
           v: PROTOCOL_VERSION,
           token,
           ext: { id: chrome.runtime.id, version: chrome.runtime.getManifest().version, chrome: chromeVersion() },
-          profile: profile && profile.trim() ? profile.trim() : void 0
+          profile: profile && profile.trim() ? profile.trim() : void 0,
+          // This build gates fail-closed and reports tab URLs on results, so the
+          // server may skip its pre-flight tabs_list. An older build omits this and
+          // the server keeps fetching the URL itself.
+          caps: [WIRE_CAP_TAB_URL]
         };
         ws2.send(JSON.stringify(hello));
       };
@@ -494,6 +499,9 @@
       const u = cmd.params.url;
       return typeof u === "string" ? u : "";
     }
+    return observedTabUrl(cmd);
+  }
+  async function observedTabUrl(cmd) {
     try {
       const tabId = await targetTab(cmd);
       const t = await chrome.tabs.get(tabId);
@@ -1124,6 +1132,12 @@
     async dispatch(cmd) {
       try {
         const policy = this.deps.getPolicy();
+        if (!policy && cmd.method !== "ping_probe") {
+          throw new CmdError(
+            "POLICY_DENIED",
+            "no policy has arrived from the chrome-mcp server yet, so this extension is refusing every command"
+          );
+        }
         if (policy) {
           const url = isUrlGated(cmd.method) ? await urlForCommand(cmd) : "";
           const verdict = evaluatePolicy(url, cmd.method, policy);
@@ -1131,6 +1145,8 @@
         }
         const data = await this.deps.exec.run(cmd);
         const frame = { type: "result", v: PROTOCOL_VERSION, id: cmd.id, ok: true, data };
+        const tabUrl = await observedTabUrl(cmd);
+        if (tabUrl) frame.tabUrl = tabUrl;
         this.deps.send(frame);
       } catch (err) {
         const code = err instanceof CmdError ? err.code : "CDP_ERROR";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.6.3",
-  "description": "Drive a real Chrome browser over MCP. A stdio MCP server (CLI) plus an MV3 extension, behind one pluggable Executor (extension via chrome.scripting, or a Playwright CDP fallback).",
+  "version": "0.6.5",
+  "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",
   "homepage": "https://github.com/Mehmoodqureshi/chrome-mcp#readme",
@@ -32,12 +32,20 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "mcp-server",
     "chrome",
     "chrome-extension",
     "browser-automation",
-    "cdp",
-    "playwright",
-    "claude"
+    "browser-mcp",
+    "real-browser",
+    "logged-in",
+    "session",
+    "cookies",
+    "authenticated",
+    "web-scraping",
+    "ai-agent",
+    "claude",
+    "claude-code"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/scripts/postinstall.js

@@ -39,7 +39,13 @@ function main() {
   }
   try {
     const { execFileSync } = require('node:child_process');
-    execFileSync('npx', ['playwright', 'install', 'chromium'], { stdio: 'inherit' });
+    const { dirname, join } = require('node:path');
+    // Drive Playwright's CLI through node rather than the `npx`/`playwright` bin
+    // shim: on Windows those are .cmd files, which execFileSync cannot spawn
+    // without a shell. `cli.js` is playwright's own bin target; resolving it via
+    // package.json avoids the exports map, which exposes no './cli' subpath.
+    const cli = join(dirname(require.resolve('playwright/package.json')), 'cli.js');
+    execFileSync(process.execPath, [cli, 'install', 'chromium'], { stdio: 'inherit' });
   } catch (err) {
     process.stdout.write(
       `[postinstall] Chromium install skipped (non-fatal): ${err && err.message ? err.message : err}\n`,