@mehmoodqureshi/chrome-mcp 0.6.3 → 0.6.4

package/README.md

@@ -4,17 +4,18 @@
 [![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.
+Drive a **real Chrome browser** from Claude (or any MCP host). 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.
 
 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.
@@ -44,10 +45,8 @@ 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.** Add `--persist-token` so the pairing token survives
+restarts:
 
 ```jsonc
 {
@@ -56,7 +55,7 @@ again**:
       "command": "npx",
       "args": ["-y", "@mehmoodqureshi/chrome-mcp",
                "--allow-domain", "example.com", "--enable-mutations",
-               "--no-cdp-fallback", "--persist-token"]
+               "--persist-token"]
     }
   }
 }
@@ -68,14 +67,72 @@ 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/`.
+**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`. (Without the extension, the CLI
-falls back to a Playwright-driven Chromium automatically.)
+`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": "cmd",
+      "args": ["/c", "npx", "-y", "@mehmoodqureshi/chrome-mcp",
+               "--allow-domain", "example.com", "--enable-mutations",
+               "--persist-token"]
+    }
+  }
+}
+```
+
+Or from Claude Code: `claude mcp add chrome-mcp -- cmd /c npx -y @mehmoodqureshi/chrome-mcp --allow-domain example.com`
+
+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 +240,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/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/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;

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);

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/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.4",
+  "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",

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`,