@mehmoodqureshi/chrome-mcp 0.7.0 → 0.8.0

package/README.md

@@ -29,6 +29,21 @@ Distributed as an `npx` CLI (the MCP server) plus a load-unpacked extension.
 
 ## Quickstart
 
+### Up and running in one paste
+
+Hand this to your AI agent (Claude Code, Cursor, Windsurf, anything MCP) and it
+installs the server, wires it into the client, and walks you through the two
+steps that must happen inside Chrome:
+
+```text
+Set up chrome-mcp on this machine by fetching and following
+https://raw.githubusercontent.com/Mehmoodqureshi/chrome-mcp/main/SETUP.md
+exactly, step by step. Work autonomously and verify each step.
+```
+
+Prefer to read before you run an agent on your machine? [`SETUP.md`](SETUP.md)
+is the exact file the agent follows. The manual steps are below.
+
 **1. Register the MCP server** with your host.
 
 <details open>
@@ -98,16 +113,24 @@ 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
+chrome-mcp --extension-path   # prints the absolute path of 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`.
+**3. Pair it — usually nothing to do.** Every time the server boots it writes
+`pairing.json` (mode 0600, never shipped in the tarball) into the very
+`extension-dist/` folder you just loaded. The extension reads that file from its
+own folder on startup and pairs itself, so the toolbar badge turns green with no
+token to paste. Load the extension before the server has ever run? It re-checks
+every 30 seconds and pairs as soon as the file appears.
+
+Manual fallback (a copied folder, a read-only install): run
+`npx chrome-mcp --print-pairing`, open the extension's **Options** page, and
+paste the `port` + `token` from `~/.chrome-mcp/handshake.json`. Values saved
+there take precedence over the bundled file.
 
 ### Running more than one session
 
@@ -155,7 +178,7 @@ start. Wrap it in `cmd /c`:
 
 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
+Everything else is the same — load the folder `chrome-mcp --extension-path` prints and pair
 as above.
 
 The tools cover tabs, navigation, interaction (`click`/`type`/`press`/`hover`/
@@ -400,10 +423,10 @@ RUN_EXT_SMOKE=1 node --test dist/test/extension-smoke.test.js   # live, headed
 ## The extension
 
 `extension/` builds (esbuild) to `extension-dist/`, loaded via
-`chrome://extensions` → **Load unpacked** → select `extension-dist/`. Pair it
-from the extension's **Options** page using the `port` + `token` from
-`~/.chrome-mcp/handshake.json` (run `npx chrome-mcp --print-pairing` to get the
-path).
+`chrome://extensions` → **Load unpacked** → select `extension-dist/`. It pairs
+itself from the `pairing.json` the server writes into that folder on boot; the
+**Options** page paste of `port` + `token` from `~/.chrome-mcp/handshake.json`
+(run `npx chrome-mcp --print-pairing` to get the path) is only the fallback.
 
 > **Reads/interaction use `chrome.scripting`/`chrome.tabs`** — no "is being
 > debugged" banner, CSP-safe reads (isolated world), testable under Playwright.

package/SETUP.md

@@ -0,0 +1,189 @@
+# chrome-mcp — agent setup instructions
+
+**You are an AI agent. Follow these steps to set up chrome-mcp end-to-end on this
+machine and prove it works.** chrome-mcp lets an MCP client drive the human's
+real Chrome browser: real logins, real cookies, no separate Chromium. It has two
+halves that must be paired: a stdio MCP server (npm package
+`@mehmoodqureshi/chrome-mcp`) and a Manifest V3 extension that ships inside the
+same package. Work autonomously; pause only for the two actions that must happen
+inside Chrome's own UI (loading the extension, pasting the pairing token).
+
+## Ground rules
+
+- Verify each step's result before moving on. If a command fails, diagnose and
+  fix it. Do not proceed on a broken step.
+- The server is **deny-all by default**: no domains, no clicks, no eval, no
+  downloads, no uploads. Ask the human which domains they want to automate and
+  grant only those with `--allow-domain`. Never reach for `--unsafe-all-domains`
+  or `--unsafe-enable-eval` unless the human asks for them by name.
+- Never print or log the pairing token. It lives in a 0600 file; show the human
+  its path, not its contents.
+- Requires Node 18 or newer (`node --version`) and Chrome 116 or newer.
+- On Windows, MCP hosts must launch the server through `cmd /c npx ...`. See
+  step 3.
+
+## Step 1 — Confirm the environment
+
+Run and record the output:
+
+```
+node --version
+npm --version
+```
+
+If Node is below 18, stop and tell the human to upgrade before anything else.
+
+## Step 2 — Install the package globally
+
+A global install gives the extension a stable path that Chrome can load from.
+
+```
+npm install -g @mehmoodqureshi/chrome-mcp
+chrome-mcp --version
+```
+
+Verify: the second command prints a version. Then locate the extension folder:
+
+```
+chrome-mcp --extension-path
+```
+
+It prints the absolute path of the bundled `extension-dist` folder. Verify with
+`ls` (or `dir`) that the folder holds `manifest.json` and `background.js`.
+Record the absolute path; the human needs it in step 4. The install is small
+and downloads no browser: the server drives the Chrome the human already has.
+
+## Step 3 — Wire the server into this MCP client
+
+Ask the human which domains they want to automate. Build the argument list from
+their answer: one `--allow-domain <glob>` per domain, plus `--enable-mutations`
+if they want the agent to click, type, and navigate (almost always yes). Add
+`--persist-token` so the pairing survives restarts. Leave every other gate off
+unless they ask.
+
+**Claude Code** (registers for every project on this machine):
+
+```
+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 the
+server's own command line. Keep the `--` or `--allow-domain` gets read as a
+Claude Code option. Verify with `claude mcp list`: chrome-mcp should be listed.
+It will show as connected once the server boots, even before the extension has
+paired.
+
+**Claude Desktop, Cursor, Windsurf, VS Code, and other JSON-configured hosts:**
+add this to the host's MCP config file (the exact path differs per client; VS
+Code uses a top-level `servers` key instead of `mcpServers`).
+
+```json
+{
+  "mcpServers": {
+    "chrome-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mehmoodqureshi/chrome-mcp",
+               "--allow-domain", "example.com",
+               "--enable-mutations",
+               "--persist-token"]
+    }
+  }
+}
+```
+
+**Windows:** the command must be `cmd` with args `["/c", "npx", "-y",
+"@mehmoodqureshi/chrome-mcp", ...]`, or for Claude Code:
+`claude mcp add chrome-mcp -s user -- cmd /c npx -y @mehmoodqureshi/chrome-mcp --allow-domain example.com --enable-mutations --persist-token`.
+
+Tell the human to restart the client (or run `/mcp` in Claude Code) so the
+server loads. The first boot writes `~/.chrome-mcp/handshake.json` (mode 0600)
+holding the bridge port and the pairing token, and with `--persist-token` it
+also stores the token at `~/.chrome-mcp/token` for reuse.
+
+## Step 4 — Load the extension (human action inside Chrome)
+
+You cannot do this step yourself. Give the human these exact instructions:
+
+1. Open `chrome://extensions` in Chrome.
+2. Turn on **Developer mode** (top right).
+3. Click **Load unpacked** and choose the `extension-dist` folder from step 2.
+4. Confirm an extension named **Chrome MCP Bridge** now appears in the list.
+
+Wait for the human to confirm before continuing.
+
+## Step 5 — Pairing (automatic; verify it)
+
+Pairing needs no paste. Every time the server boots it writes `pairing.json`
+(mode 0600) into the same `extension-dist` folder the human loaded in step 4.
+The extension reads that file from its own folder and pairs itself. So make
+sure a server has booted at least once since step 2, in either of these ways:
+
+- the client started one in step 3 (a restart or `/mcp` reconnect is enough), or
+- start one yourself in pairing mode and leave it running in the background:
+
+  ```
+  chrome-mcp --print-pairing --persist-token
+  ```
+
+Verify the file exists (do not print it):
+
+```
+ls "$(chrome-mcp --extension-path)/pairing.json"
+```
+
+Then ask the human to look at the extension's toolbar icon on
+`chrome://extensions` or in the toolbar: a green dot badge means paired and
+connected. It can take up to 30 seconds if the extension was loaded before the
+server first ran. Wait for the human to confirm.
+
+**Manual fallback**, only if the badge stays grey after a minute (a copied
+extension folder or a read-only global install): read the port without
+printing the token,
+
+```
+node -e "console.log(require(require('os').homedir()+'/.chrome-mcp/handshake.json').port)"
+```
+
+then have the human open **Details** on Chrome MCP Bridge, then **Extension
+options**, enter that **Port**, open `~/.chrome-mcp/handshake.json` in a text
+editor and paste its `token` into the **Token** field, leave **Profile** as
+`default`, and click **Save**. The status line should read **connected** within
+a few seconds. Values saved by hand take precedence over the bundled file.
+
+If you started a pairing-mode server in this step, stop it now with Ctrl-C. The
+client's own server takes the port over on its next boot, and with
+`--persist-token` the extension reconnects to it with no further pairing.
+
+## Step 6 — Prove the chain end-to-end
+
+From the restarted client session, call the MCP tools in this order and check
+each result:
+
+1. `chrome_status` — reports the backend as the extension and the session as
+   connected.
+2. `tabs_list` — returns at least one tab from the human's real Chrome.
+3. `navigate` to a URL on one of the allowlisted domains, then `snapshot` —
+   returns interactive elements with `ref` ids.
+4. `navigate` to a domain that is **not** allowlisted — must be refused with a
+   policy error. This confirms deny-all is working, which matters more than the
+   happy path.
+
+If `chrome_status` shows the extension disconnected, the pairing in step 5 did
+not stick. Re-check the port and token before anything else.
+
+## Step 7 — Report
+
+Summarize for the human:
+
+- Node and package versions installed.
+- The absolute `extension-dist` path they loaded.
+- Which MCP client was configured, at which scope, with which domains and gates.
+- Whether pairing, `tabs_list`, an allowed navigation, and a refused navigation
+  each verified green.
+- Anything still open on their side, such as restarting the client.
+
+For any failure, name the exact symptom, what you tried, and the matching
+section of the README's troubleshooting notes at
+`https://github.com/Mehmoodqureshi/chrome-mcp#readme`.

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

@@ -42,6 +42,20 @@ export interface WriteHandshakeFields {
     token: string;
     expectedExtensionId?: string;
 }
+/** Name of the auto-pairing file the server drops into its bundled extension folder. */
+export declare const BUNDLED_PAIRING_FILE = "pairing.json";
+/**
+ * Write `<extDir>/pairing.json` so an extension loaded unpacked from that very
+ * folder can pair itself: its service worker fetches the file from its own
+ * package and adopts the port + token with no Options-page paste. Same secret,
+ * same 0600 mode, same trust boundary as the handshake (only this user can read
+ * it, and the file is neither web-accessible nor shipped in the npm tarball).
+ *
+ * Best-effort: returns the path on success, or null when the folder is missing
+ * or read-only (a locked-down global install). Never throws — manual pairing
+ * still works without it.
+ */
+export declare function writeBundledPairing(extDir: string, fields: WriteHandshakeFields): string | null;
 /**
  * Atomically write the handshake at 0600 and verify the mode. Throws (fail
  * closed) if the file ends up group/other-readable — the token is the entire

package/dist/src/bridge/auth.js

@@ -14,12 +14,14 @@
  *   - The token is NEVER written to stdout/stderr or any log (a test asserts it).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUNDLED_PAIRING_FILE = void 0;
 exports.generateToken = generateToken;
 exports.tokenPath = tokenPath;
 exports.readPersistedToken = readPersistedToken;
 exports.writePersistedToken = writePersistedToken;
 exports.resolveToken = resolveToken;
 exports.tokensMatch = tokensMatch;
+exports.writeBundledPairing = writeBundledPairing;
 exports.writeHandshake = writeHandshake;
 exports.readHandshake = readHandshake;
 exports.removeHandshake = removeHandshake;
@@ -110,6 +112,40 @@ function tokensMatch(a, b) {
     const hb = (0, node_crypto_1.createHash)('sha256').update(b, 'utf8').digest();
     return (0, node_crypto_1.timingSafeEqual)(ha, hb);
 }
+/** Name of the auto-pairing file the server drops into its bundled extension folder. */
+exports.BUNDLED_PAIRING_FILE = 'pairing.json';
+/**
+ * Write `<extDir>/pairing.json` so an extension loaded unpacked from that very
+ * folder can pair itself: its service worker fetches the file from its own
+ * package and adopts the port + token with no Options-page paste. Same secret,
+ * same 0600 mode, same trust boundary as the handshake (only this user can read
+ * it, and the file is neither web-accessible nor shipped in the npm tarball).
+ *
+ * Best-effort: returns the path on success, or null when the folder is missing
+ * or read-only (a locked-down global install). Never throws — manual pairing
+ * still works without it.
+ */
+function writeBundledPairing(extDir, fields) {
+    const path = (0, node_path_1.join)(extDir, exports.BUNDLED_PAIRING_FILE);
+    const tmp = `${path}.tmp.${process.pid}`;
+    const payload = { v: protocol_1.PROTOCOL_VERSION, port: fields.port, token: fields.token, ts: Date.now() };
+    try {
+        (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(payload), { mode: 0o600 });
+        (0, node_fs_1.chmodSync)(tmp, 0o600);
+        (0, node_fs_1.renameSync)(tmp, path);
+        (0, node_fs_1.chmodSync)(path, 0o600);
+        return path;
+    }
+    catch {
+        try {
+            (0, node_fs_1.unlinkSync)(tmp);
+        }
+        catch {
+            /* nothing to clean */
+        }
+        return null;
+    }
+}
 /**
  * Atomically write the handshake at 0600 and verify the mode. Throws (fail
  * closed) if the file ends up group/other-readable — the token is the entire

package/dist/src/bridge/workspace.js

@@ -26,12 +26,11 @@ exports.appendHistory = appendHistory;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const config_1 = require("../config");
+// `mcp/log` (not `mcp/server`) so this stays free of the server import cycle
+// while still honouring `--log-level silent`.
+const log_1 = require("../mcp/log");
 const download_1 = require("../../shared/download");
 const datadir_1 = require("./datadir");
-/** stderr only (never stdout in stdio mode); local to avoid an import cycle with mcp/server. */
-function logErr(message) {
-    process.stderr.write(`[chrome-mcp] ${message}\n`);
-}
 let active = null;
 /** Monotonic counter so saved result/screenshot filenames sort in capture order. */
 let seq = 0;
@@ -100,7 +99,7 @@ function saveResult(tool, ext, body) {
         return path;
     }
     catch (err) {
-        logErr(`results save failed: ${err instanceof Error ? err.message : String(err)}`);
+        (0, log_1.logErr)(`results save failed: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
 }
@@ -119,7 +118,7 @@ function saveBinary(tool, ext, bytes) {
         return path;
     }
     catch (err) {
-        logErr(`results save failed: ${err instanceof Error ? err.message : String(err)}`);
+        (0, log_1.logErr)(`results save failed: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
 }
@@ -134,7 +133,7 @@ function saveScreenshot(dataBase64) {
         return path;
     }
     catch (err) {
-        logErr(`screenshot save failed: ${err instanceof Error ? err.message : String(err)}`);
+        (0, log_1.logErr)(`screenshot save failed: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
 }
@@ -176,7 +175,7 @@ function appendHistory(entry) {
         (0, node_fs_1.appendFileSync)(w.historyPath, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
     }
     catch (err) {
-        logErr(`history append failed: ${err instanceof Error ? err.message : String(err)}`);
+        (0, log_1.logErr)(`history append failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
 //# sourceMappingURL=workspace.js.map

package/dist/src/cli.js

@@ -51,6 +51,14 @@ function version() {
         return '0.0.0';
     }
 }
+/**
+ * Absolute path of the bundled extension. `dist/src/cli.js` -> `<pkg>/extension-dist`,
+ * which `files` in package.json ships in the tarball, so this is right for a global
+ * install, an npx cache entry, and a git checkout alike.
+ */
+function extensionPath() {
+    return (0, node_path_1.resolve)(__dirname, '..', '..', 'extension-dist');
+}
 /** Render a byte count as a short human string (1.2 MB, 904 KB, …). */
 function humanBytes(n) {
     if (n < 1024)
@@ -154,6 +162,10 @@ async function main() {
         process.stdout.write(`${version()}\n`);
         return;
     }
+    if (cfg.showExtensionPath) {
+        process.stdout.write(`${extensionPath()}\n`);
+        return;
+    }
     const dataDir = (0, datadir_1.ensureDataDir)(cfg.dataDir);
     const token = (0, auth_1.resolveToken)(dataDir, { persist: cfg.persistToken });
     const { allowDomains, allowEval, allowDownloads, allowUploads, allowAllTabs, enableMutations } = cfg.policy;
@@ -179,6 +191,16 @@ async function main() {
     })}`);
     const handshakePath = (0, auth_1.writeHandshake)(dataDir, { port, token });
     (0, server_2.logErr)(`pairing handshake written to ${handshakePath} (mode 0600; token not logged)`);
+    // Drop the same port + token into the bundled extension folder so a Load
+    // unpacked from there pairs itself. Best-effort: a read-only install just
+    // falls back to the Options-page paste.
+    const bundled = (0, auth_1.writeBundledPairing)(extensionPath(), { port, token });
+    if (bundled) {
+        (0, server_2.logErr)(`auto-pairing file written to ${bundled} — Load unpacked from that folder needs no token paste`);
+    }
+    else {
+        (0, server_2.logDebug)(`auto-pairing file not written (extension folder missing or read-only at ${extensionPath()})`);
+    }
     if (process.env.CHROME_MCP_TOKEN) {
         (0, server_2.logErr)('token: pinned from CHROME_MCP_TOKEN (stable; pair once, never again).');
     }

package/dist/src/config.d.ts

@@ -28,8 +28,10 @@ export interface CliConfig {
     prefer: BackendPreference;
     /** Run the CDP-fallback Chromium headless. */
     headless: boolean;
-    /** `--print-pairing`: write the handshake and print its path (never the token). */
+    /** `--print-pairing`: write the handshake, print its path (never the token), and keep the bridge up until Ctrl-C. */
     printPairing: boolean;
+    /** `--extension-path`: print the absolute path of the bundled extension (for Load unpacked) and exit. */
+    showExtensionPath: boolean;
     /** `--persist-token`: reuse a stable on-disk token so the extension never re-pairs. */
     persistToken: boolean;
     showHelp: boolean;

package/dist/src/config.js

@@ -80,6 +80,7 @@ function parseArgs(argv) {
     let persistToken = false;
     let showHelp = false;
     let showVersion = false;
+    let showExtensionPath = false;
     let logLevel = 'info';
     // Policy assembled from flags, layered over an optional file.
     let policyFile;
@@ -95,6 +96,9 @@ function parseArgs(argv) {
             case '--version':
                 showVersion = true;
                 break;
+            case '--extension-path':
+                showExtensionPath = true;
+                break;
             case '--port':
                 wsPort = requireInt(argv[++i], '--port');
                 break;
@@ -214,6 +218,7 @@ function parseArgs(argv) {
         persistToken,
         showHelp,
         showVersion,
+        showExtensionPath,
         logLevel,
     };
 }
@@ -267,7 +272,10 @@ Connection:
                          the extension Options; tools route to the active profile.
   --task <name>          Task label (default "default"). Downloads and a meta.json
                          land in profiles/<profile>/tasks/<task>/.
-  --print-pairing        Write the handshake and print its path, then exit
+  --print-pairing        Write the handshake, print its path, and keep the bridge
+                         up until Ctrl-C (manual pairing; never serves MCP)
+  --extension-path       Print the absolute path of the bundled extension folder
+                         (what to pick in chrome://extensions -> Load unpacked)
   --persist-token        Reuse a stable on-disk token across restarts so the
                          extension never has to re-pair (default: fresh per boot).
                          CHROME_MCP_TOKEN env, if set, pins the token explicitly.

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

@@ -7,7 +7,7 @@
  * extension and CDP executors are cached across calls; only the choice is live.
  */
 import { type Executor } from './types';
-import { type CdpOptions } from './cdp-executor';
+import type { CdpOptions } from './cdp-executor';
 import type { BridgeServer } from '../bridge/server';
 import type { BackendPreference } from '../config';
 export interface SelectorDeps {

package/dist/src/executor/select.js

@@ -11,10 +11,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSelector = createSelector;
 const types_1 = require("./types");
 const extension_executor_1 = require("./extension-executor");
-const cdp_executor_1 = require("./cdp-executor");
 function createSelector(deps) {
     const makeExt = deps.makeExtension ?? ((b) => new extension_executor_1.ExtensionExecutor(b));
-    const makeCdp = deps.makeCdp ?? ((o) => new cdp_executor_1.CdpExecutor(o));
+    const makeCdp = deps.makeCdp ??
+        ((o) => {
+            // Loaded lazily: playwright is a devDependency (tests + HITL only). The
+            // published CLI is extension-only, so a fresh install never pulls a
+            // browser. Reaching this without playwright present is a config error.
+            let mod;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                mod = require('./cdp-executor');
+            }
+            catch (e) {
+                const why = e instanceof Error ? e.message : String(e);
+                throw new types_1.ExecutorError('NO_BACKEND', `CDP backend requested but this build is extension-only (playwright is not installed: ${why}). Pair the extension instead.`);
+            }
+            return new mod.CdpExecutor(o);
+        });
     const pingMs = deps.pingDeadlineMs ?? 800;
     const pingCacheMs = deps.pingCacheMs ?? 2_000;
     const ext = makeExt(deps.bridge);

package/extension-dist/background.js

@@ -1572,7 +1572,10 @@
   var executor = new ChromeExecutor(() => currentPolicy);
   var ws = new WsClient({
     onCommand: (cmd) => void router.dispatch(cmd),
-    onState: (state) => void persistState(state),
+    onState: (state) => {
+      void persistState(state);
+      if (state === "unauthorized") void adoptBundledPairing();
+    },
     onPolicy: (policy) => {
       currentPolicy = policy;
       void syncObserverScript(policy, (m) => console.debug("[chrome-mcp]", m));
@@ -1585,6 +1588,27 @@
     getPolicy: () => currentPolicy,
     log: (m) => console.debug("[chrome-mcp]", m)
   });
+  async function readBundledPairing() {
+    try {
+      const res = await fetch(chrome.runtime.getURL("pairing.json"), { cache: "no-store" });
+      if (!res.ok) return null;
+      const j = await res.json();
+      if (typeof j.port === "number" && j.port > 0 && typeof j.token === "string" && j.token.length > 0) {
+        return { wsPort: j.port, token: j.token };
+      }
+    } catch {
+    }
+    return null;
+  }
+  async function adoptBundledPairing() {
+    const { wsPort, token, pairingSource } = await chrome.storage.local.get(["wsPort", "token", "pairingSource"]);
+    if (pairingSource === "manual") return false;
+    const bundled = await readBundledPairing();
+    if (!bundled) return false;
+    if (bundled.wsPort === wsPort && bundled.token === token) return false;
+    await chrome.storage.local.set({ wsPort: bundled.wsPort, token: bundled.token, pairingSource: "auto" });
+    return true;
+  }
   async function getConfig() {
     const { wsPort, token, profile } = await chrome.storage.local.get(["wsPort", "token", "profile"]);
     if (typeof wsPort === "number" && wsPort > 0 && typeof token === "string" && token.length > 0) {
@@ -1620,6 +1644,7 @@
   }
   async function keepalivePulse() {
     await chrome.storage.local.get("connState");
+    if (!ws.isConnected() && !await getConfig()) await adoptBundledPairing();
     await ensureConnected();
   }
   chrome.runtime.onInstalled.addListener(() => void bootstrap());
@@ -1643,7 +1668,7 @@
   });
   async function bootstrap() {
     await chrome.alarms.create(KEEPALIVE_ALARM, { periodInMinutes: 0.5 });
-    await ensureConnected();
+    if (!await adoptBundledPairing()) await ensureConnected();
   }
   void bootstrap();
 })();

package/extension-dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Chrome MCP Bridge",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Lets a local chrome-mcp server drive this browser. Pair it with the server's handshake token.",
   "minimum_chrome_version": "116",
   "background": {

package/extension-dist/options.html

@@ -16,9 +16,10 @@
   </head>
   <body>
     <h1>Pair with chrome-mcp</h1>
+    <p class="hint" id="source">Checking pairing source…</p>
     <p class="hint">
-      Run <code>npx chrome-mcp --print-pairing</code>, open the printed
-      <code>handshake.json</code>, and paste its <code>port</code> and
+      Manual pairing: run <code>npx chrome-mcp --print-pairing</code>, open the
+      printed <code>handshake.json</code>, and paste its <code>port</code> and
       <code>token</code> below.
     </p>
     <label for="port">Port</label>

package/extension-dist/options.js

@@ -9,8 +9,15 @@
   var profileEl = document.getElementById("profile");
   var saveEl = document.getElementById("save");
   var statusEl = document.getElementById("status");
+  var sourceEl = document.getElementById("source");
   async function loadExisting() {
-    const { wsPort, profile, connState } = await chrome.storage.local.get(["wsPort", "profile", "connState"]);
+    const { wsPort, profile, connState, pairingSource } = await chrome.storage.local.get([
+      "wsPort",
+      "profile",
+      "connState",
+      "pairingSource"
+    ]);
+    sourceEl.textContent = pairingSource === "auto" ? "Paired automatically from the pairing.json the server wrote into this extension folder. Saving here overrides it." : pairingSource === "manual" ? "Paired by hand. Saved values take precedence over the bundled pairing.json." : "Not paired yet. If you loaded this extension from the chrome-mcp package folder, start the server once and it pairs itself; otherwise paste the values below.";
     portEl.value = typeof wsPort === "number" && wsPort > 0 ? String(wsPort) : String(DEFAULT_WS_PORT);
     profileEl.value = typeof profile === "string" ? profile : "";
     render(typeof connState === "string" ? connState : "idle");
@@ -32,7 +39,7 @@
       statusEl.textContent = "Status: enter a valid port (> 0) and token";
       return;
     }
-    await chrome.storage.local.set({ wsPort, token, profile });
+    await chrome.storage.local.set({ wsPort, token, profile, pairingSource: "manual" });
     await chrome.runtime.sendMessage({ type: "reconnect" }).catch(() => void 0);
     statusEl.textContent = "Status: \u2026 connecting";
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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",
@@ -24,8 +24,9 @@
     "dist/shared/**/*.js",
     "dist/shared/**/*.d.ts",
     "extension-dist",
-    "scripts/postinstall.js",
+    "!extension-dist/pairing.json",
     "README.md",
+    "SETUP.md",
     "LICENSE",
     "docs/BLUEPRINT.md"
   ],
@@ -55,12 +56,10 @@
     "clean": "rimraf dist extension-dist",
     "test": "npm run clean && npm run build && npm run build:ext && node --test dist/test/*.test.js",
     "test:hitl": "npm run build && node dist/hitl/index.js",
-    "prepack": "npm run clean && npm run build && npm run build:ext",
-    "postinstall": "node scripts/postinstall.js"
+    "prepack": "npm run clean && npm run build && npm run build:ext"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "playwright": "^1.49.1",
     "ws": "^8.18.0",
     "zod": "^4.4.3"
   },
@@ -69,6 +68,7 @@
     "@types/node": "^20.17.10",
     "@types/ws": "^8.5.13",
     "esbuild": "^0.24.0",
+    "playwright": "^1.49.1",
     "rimraf": "^5.0.10",
     "typescript": "^5.7.2"
   },

package/scripts/postinstall.js

@@ -1,56 +0,0 @@
-/**
- * postinstall — install the Chromium that the CDP fallback needs.
- *
- * Skip-guarded and never fatal: a failure here must not break `npm install`
- * (the extension path needs no browser, and CI rarely wants the download).
- * Skips when:
- *   - CHROME_MCP_SKIP_BROWSER_DOWNLOAD / PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD is set,
- *   - CI is set,
- *   - playwright is not installed yet (it is added in phase 3).
- */
-'use strict';
-
-function shouldSkip() {
-  return (
-    process.env.CHROME_MCP_SKIP_BROWSER_DOWNLOAD === '1' ||
-    process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1' ||
-    process.env.CI === 'true' ||
-    process.env.CI === '1'
-  );
-}
-
-function hasPlaywright() {
-  try {
-    require.resolve('playwright');
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function main() {
-  if (shouldSkip()) {
-    process.stdout.write('[postinstall] skipping Chromium download (guard set).\n');
-    return;
-  }
-  if (!hasPlaywright()) {
-    process.stdout.write('[postinstall] playwright not installed; CDP fallback unavailable until phase 3.\n');
-    return;
-  }
-  try {
-    const { execFileSync } = require('node:child_process');
-    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`,
-    );
-  }
-}
-
-main();