@mehmoodqureshi/chrome-mcp 0.6.1 → 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/shared/policy.js

@@ -80,17 +80,38 @@ function hostOf(url) {
 function isAboutBlank(url) {
     return url === 'about:blank' || url === '' || url.startsWith('about:');
 }
+/**
+ * Reduce an allowlist entry to the bare host it constrains. Users routinely paste
+ * a full URL ("https://example.com/app") or a "host:port/path" instead of a bare
+ * host; those forms would never equal a hostname and so silently match nothing.
+ * We strip the scheme, userinfo, port, and path/query/fragment, preserving a
+ * leading "*." wildcard and the two catch-all forms. Returns '' for a pattern
+ * that carries no host (which then matches nothing).
+ */
+function normalizeDomainPattern(pattern) {
+    let p = pattern.trim().toLowerCase();
+    if (p === '*' || p === '*://*/*')
+        return '*';
+    // Strip a leading scheme ("https://", "http://", any "scheme://").
+    p = p.replace(/^[a-z][a-z0-9+.-]*:\/\//, '');
+    // Drop everything from the first path/query/fragment separator onward.
+    p = p.replace(/[/?#].*$/, '');
+    // Strip userinfo ("user:pass@") then a trailing port (":8080").
+    p = p.replace(/^[^@]*@/, '').replace(/:\d+$/, '');
+    return p;
+}
 /** Convert a single domain glob to a predicate. '*' matches everything;
- *  '*.example.com' matches example.com and any subdomain; otherwise exact host. */
+ *  '*.example.com' matches example.com and any subdomain; otherwise exact host.
+ *  URL/port/path forms are normalized to their bare host first. */
 function globMatches(host, pattern) {
-    const p = pattern.trim().toLowerCase();
-    if (p === '*' || p === '*://*/*')
+    const p = normalizeDomainPattern(pattern);
+    if (p === '*')
         return true;
     if (p.startsWith('*.')) {
         const base = p.slice(2);
         return host === base || host.endsWith('.' + base);
     }
-    return host === p;
+    return p !== '' && host === p;
 }
 function isDomainAllowed(url, policy) {
     const host = hostOf(url);

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/config.js

@@ -162,6 +162,14 @@ function parseArgs(argv) {
                 throw new Error(`unknown argument: ${arg}`);
         }
     }
+    // Fallback permanently removed — this build is EXTENSION-ONLY. It NEVER
+    // launches or attaches a Chromium of its own; it only ever drives the user's
+    // real Chrome through the paired extension. Any CDP flags (--cdp-fallback,
+    // --cdp-endpoint, --prefer cdp) are still accepted for back-compat but are
+    // hard-overridden here so no separate/"fallback" browser can ever open.
+    cdpFallback = false;
+    cdpEndpoint = undefined;
+    prefer = 'extension';
     // File first, then flags win.
     const policy = (0, policy_1.resolvePolicy)({ ...policyFile, ...policyFlags });
     // Uploads must be confined to a directory — refuse to start with uploads enabled
@@ -242,13 +250,14 @@ Connection:
                          CHROME_MCP_TOKEN env, if set, pins the token explicitly.
 
 Backend:
-  --cdp-fallback         Opt in to launching/attaching Chromium when no extension
-                         is paired. OFF by default — extension-only, never opens
-                         a browser of its own.
-  --no-cdp-fallback      Explicitly disable the fallback (already the default).
-  --cdp-endpoint <url>   Attach to an existing Chrome (e.g. http://127.0.0.1:9222)
-  --prefer <which>       "extension" (default) or "cdp"
-  --headless             Run the CDP-fallback Chromium headless
+  This build is EXTENSION-ONLY — it drives ONLY your real Chrome via the paired
+  extension and never launches or attaches a Chromium of its own. The CDP flags
+  below are accepted for back-compat but IGNORED (there is no fallback).
+  --cdp-fallback         (ignored — fallback permanently removed)
+  --no-cdp-fallback      (ignored — extension-only is always on)
+  --cdp-endpoint <url>   (ignored — no CDP attach)
+  --prefer <which>       (ignored — always "extension")
+  --headless             (ignored — no CDP Chromium to run headless)
 
 Security (default: deny-all safe mode):
   --policy <file>        Load a JSON policy file

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/mcp/helpers.d.ts

@@ -13,10 +13,16 @@ export interface LinkOut {
 /**
  * Collect anchors from the page (or a subtree). Implemented as a single page
  * eval so it is one round-trip; falls back to parsing getHtml if eval is denied.
+ *
+ * `dedupe` collapses anchors that share an href (nav/footer repetition is common
+ * noise when crawling); `limit` caps the number of links returned. Both are
+ * applied server-side after collection, so they work on either code path.
  */
 export declare function extractLinks(ex: Executor, args: {
     selector?: string;
     sameOriginOnly?: boolean;
+    dedupe?: boolean;
+    limit?: number;
     tabId?: string;
 }): Promise<{
     links: LinkOut[];

package/dist/src/mcp/helpers.js

@@ -13,6 +13,10 @@ const markdown_extract_1 = require("./markdown-extract");
 /**
  * Collect anchors from the page (or a subtree). Implemented as a single page
  * eval so it is one round-trip; falls back to parsing getHtml if eval is denied.
+ *
+ * `dedupe` collapses anchors that share an href (nav/footer repetition is common
+ * noise when crawling); `limit` caps the number of links returned. Both are
+ * applied server-side after collection, so they work on either code path.
  */
 async function extractLinks(ex, args) {
     const root = args.selector ? JSON.stringify(args.selector) : 'null';
@@ -24,21 +28,46 @@ async function extractLinks(ex, args) {
       href: a.href, text: (a.textContent || '').trim().slice(0, 200),
     })).filter(l => l.href && (${args.sameOriginOnly ? 'l.href.startsWith(here)' : 'true'}));
   })()`;
+    let links;
     const res = await ex.eval(expr, { tabId: args.tabId });
     if (res.ok && Array.isArray(res.value)) {
-        return { links: res.value };
+        links = res.value;
     }
-    // Fallback: parse hrefs out of the HTML (e.g. when eval is policy-denied).
-    const { html } = await ex.getHtml(args.selector ? { selector: args.selector } : undefined, {
-        tabId: args.tabId,
-    });
-    const links = [];
-    const re = /<a[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
-    let m;
-    while ((m = re.exec(html)) !== null) {
-        links.push({ href: m[1], text: m[2].replace(/<[^>]+>/g, '').trim().slice(0, 200) });
+    else {
+        // Fallback: parse hrefs out of the HTML (e.g. when eval is policy-denied).
+        const { html } = await ex.getHtml(args.selector ? { selector: args.selector } : undefined, {
+            tabId: args.tabId,
+        });
+        links = [];
+        const re = /<a[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
+        let m;
+        while ((m = re.exec(html)) !== null) {
+            links.push({ href: m[1], text: m[2].replace(/<[^>]+>/g, '').trim().slice(0, 200) });
+        }
+    }
+    return { links: refineLinks(links, args) };
+}
+/**
+ * Collapse links that share an href (keeping the first, but preferring a
+ * non-empty label) when `dedupe` is set, then cap to `limit`. Order is
+ * preserved so the first occurrence of each href wins.
+ */
+function refineLinks(links, opts) {
+    let out = links;
+    if (opts.dedupe) {
+        const byHref = new Map();
+        for (const l of links) {
+            const existing = byHref.get(l.href);
+            if (!existing)
+                byHref.set(l.href, { ...l });
+            else if (!existing.text && l.text)
+                existing.text = l.text;
+        }
+        out = [...byHref.values()];
     }
-    return { links };
+    if (opts.limit !== undefined && out.length > opts.limit)
+        out = out.slice(0, opts.limit);
+    return out;
 }
 /** Read a page (or subtree) as readable markdown. */
 async function readAsMarkdown(ex, args) {

package/dist/src/mcp/tools.js

@@ -58,7 +58,7 @@ exports.TOOL_DEFINITIONS = [
     { name: 'storage', description: 'Read/write localStorage (or sessionStorage). op: get|set|remove|clear.', inputSchema: { op: zod_1.z.enum(['get', 'set', 'remove', 'clear']), key: zod_1.z.string().optional(), value: zod_1.z.string().optional(), session: zod_1.z.boolean().optional(), tabId: tabIdField } },
     { name: 'eval', description: 'Evaluate JavaScript in the page (disabled in safe-mode).', inputSchema: { expression: zod_1.z.string(), awaitPromise: zod_1.z.boolean().optional(), tabId: tabIdField } },
     { name: 'wait_for', description: 'Wait for a selector or text to appear/disappear.', inputSchema: { selector: zod_1.z.string().optional(), textContains: zod_1.z.string().optional(), gone: zod_1.z.boolean().optional(), timeoutMs: zod_1.z.number().optional(), tabId: tabIdField } },
-    { name: 'extract_links', description: 'Extract anchors from the page or a subtree.', inputSchema: { selector: zod_1.z.string().optional(), sameOriginOnly: zod_1.z.boolean().optional(), tabId: tabIdField } },
+    { name: 'extract_links', description: 'Extract anchors from the page or a subtree. dedupe=true collapses links sharing an href (nav/footer noise); limit caps the count.', inputSchema: { selector: zod_1.z.string().optional(), sameOriginOnly: zod_1.z.boolean().optional(), dedupe: zod_1.z.boolean().optional(), limit: zod_1.z.number().optional(), tabId: tabIdField } },
     { name: 'read_as_markdown', description: 'Read the page (or subtree) as readable markdown.', inputSchema: { selector: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'fill_form', description: 'Fill multiple fields (keyed by selector) and optionally submit.', inputSchema: { fields: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()])), submitSelector: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'download_file', description: 'Download a file by URL or from a link element.', inputSchema: { url: zod_1.z.string().optional(), ...TARGET_PROPS, suggestedName: zod_1.z.string().optional(), tabId: tabIdField } },
@@ -276,6 +276,8 @@ exports.TOOL_HANDLERS = {
         const res = await (0, helpers_1.extractLinks)(ctx.ex, {
             selector: (0, validators_1.optionalString)(a, 'selector'),
             sameOriginOnly: (0, validators_1.optionalBoolean)(a, 'sameOriginOnly'),
+            dedupe: (0, validators_1.optionalBoolean)(a, 'dedupe'),
+            limit: (0, validators_1.optionalNumber)(a, 'limit', { min: 1, max: 10_000 }),
             tabId: tabId(a),
         });
         (0, workspace_1.saveResult)('extract_links', 'json', JSON.stringify(res, null, 2));

package/extension-dist/background.js

@@ -39,7 +39,6 @@
     constructor(deps) {
       this.deps = deps;
     }
-    deps;
     ws = null;
     state = "idle";
     isConnected() {
@@ -160,14 +159,22 @@
   function isAboutBlank(url) {
     return url === "about:blank" || url === "" || url.startsWith("about:");
   }
+  function normalizeDomainPattern(pattern) {
+    let p = pattern.trim().toLowerCase();
+    if (p === "*" || p === "*://*/*") return "*";
+    p = p.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+    p = p.replace(/[/?#].*$/, "");
+    p = p.replace(/^[^@]*@/, "").replace(/:\d+$/, "");
+    return p;
+  }
   function globMatches(host, pattern) {
-    const p = pattern.trim().toLowerCase();
-    if (p === "*" || p === "*://*/*") return true;
+    const p = normalizeDomainPattern(pattern);
+    if (p === "*") return true;
     if (p.startsWith("*.")) {
       const base = p.slice(2);
       return host === base || host.endsWith("." + base);
     }
-    return host === p;
+    return p !== "" && host === p;
   }
   function isDomainAllowed(url, policy) {
     const host = hostOf(url);
@@ -425,7 +432,6 @@
       super(message);
       this.code = code;
     }
-    code;
   };
   var DOWNLOAD_TIMEOUT_MS = 12e4;
   function waitForDownloadComplete(id) {
@@ -527,7 +533,7 @@
   async function waitForSelector(tabId, selector, timeoutMs = 5e3) {
     const found = await execInTab(
       tabId,
-      ((s, timeout, interval) => new Promise((resolve) => {
+      (s, timeout, interval) => new Promise((resolve) => {
         const deadline = Date.now() + timeout;
         const tick = () => {
           if (document.querySelector(s)) return resolve(true);
@@ -535,7 +541,7 @@
           setTimeout(tick, interval);
         };
         tick();
-      })),
+      }),
       [selector, timeoutMs, 120]
     );
     return found === true;
@@ -1036,7 +1042,7 @@
           const start = Date.now();
           const matched = await execInTab(
             id,
-            ((sel, text, gone, timeoutMs, interval) => new Promise((resolve) => {
+            (sel, text, gone, timeoutMs, interval) => new Promise((resolve) => {
               const deadline = Date.now() + timeoutMs;
               const hit = () => {
                 let present;
@@ -1051,7 +1057,7 @@
                 setTimeout(tick, interval);
               };
               tick();
-            })),
+            }),
             [cmd.params.selector ?? null, cmd.params.textContains ?? null, cmd.params.gone === true, timeout, 150]
           );
           return { matched: matched === true, waitedMs: Date.now() - start };
@@ -1115,7 +1121,6 @@
         if (!HANDLED.has(m)) throw new Error(`router drift: no handler for wire method "${m}"`);
       }
     }
-    deps;
     async dispatch(cmd) {
       try {
         const policy = this.deps.getPolicy();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.6.1",
-  "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`,