@mehmoodqureshi/chrome-mcp 0.7.1 → 0.9.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>
@@ -93,21 +108,55 @@ explicitly (and is never written to disk).
 
 **2. Load the extension** — **required**; the server can drive nothing without it.
 
-`extension-dist/` ships prebuilt inside the npm package, so there is nothing to
-compile. Install globally to get a stable path to it:
+The extension ships prebuilt inside the npm package, and every time the server
+boots it copies it to a plain folder right under your home directory:
+
+```
+~/chrome-mcp-extension          (macOS / Linux)
+%USERPROFILE%\chrome-mcp-extension   (Windows)
+```
+
+So after step 1 has started the server once (restart your client, or `/mcp` in
+Claude Code), the folder is already there. To create it without a client, or
+to print the exact path:
 
 ```bash
-npm install -g @mehmoodqureshi/chrome-mcp
-npm root -g     # → <root>; the extension is at <root>/@mehmoodqureshi/chrome-mcp/extension-dist
+npx -y @mehmoodqureshi/chrome-mcp --extension-path
 ```
 
 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`.
+pick `chrome-mcp-extension` in your home folder. After upgrading the package the
+server refreshes the files on its next boot; click **Reload** on
+`chrome://extensions` to pick them up. `CHROME_MCP_EXTENSION_DIR` moves the
+folder somewhere else. (Working from a git clone instead? Run
+`npm install && npm run build:ext` first — `extension-dist/` is gitignored, and
+the server mirrors it to the same home folder.)
+
+**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
+`chrome-mcp-extension` 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.
+
+**Where to see the badge:** it sits on the extension's icon in Chrome's
+toolbar, not on the `chrome://extensions` page. Chrome hides new extensions
+behind the puzzle-piece button at the right of the address bar, so click that,
+find **Chrome MCP Bridge**, and click the pin next to it once; the icon then
+stays in the toolbar. Hover it for the status in words.
+
+| Badge | Meaning |
+|---|---|
+| green dot | paired and connected |
+| yellow dots | connecting |
+| grey circle | not paired yet (no server has run, or no pairing file) |
+| red exclamation mark | token rejected; the server rotated it, re-pairs by itself in a moment |
+
+Manual fallback (a copied folder, a read-only home): run
+`npx -y @mehmoodqureshi/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 +204,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 `%USERPROFILE%\chrome-mcp-extension` and pair
 as above.
 
 The tools cover tabs, navigation, interaction (`click`/`type`/`press`/`hover`/
@@ -400,10 +449,13 @@ 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 `~/chrome-mcp-extension`, the
+mirror the server refreshes from `extension-dist/` on every boot (loading
+`extension-dist/` directly also works). It pairs itself from the `pairing.json`
+the server writes into that folder; the **Options** page paste of `port` +
+`token` from `~/.chrome-mcp/handshake.json` (run
+`npx -y @mehmoodqureshi/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,201 @@
+# 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 extension folder
+
+No global install is needed. This one command fetches the package, copies the
+extension to a plain folder directly under the home directory, and prints its
+path:
+
+```
+npx -y @mehmoodqureshi/chrome-mcp --extension-path
+```
+
+It prints `~/chrome-mcp-extension` (on Windows `%USERPROFILE%\chrome-mcp-extension`).
+Verify with `ls` (or `dir`) that the folder holds `manifest.json` and
+`background.js`. Record the 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. The server refreshes this folder on every boot, so upgrades need no
+re-copy, only a Reload on `chrome://extensions`.
+
+## 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 `chrome-mcp-extension` folder in
+   their home directory (the path 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 `chrome-mcp-extension` 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:
+
+  ```
+  npx -y @mehmoodqureshi/chrome-mcp --print-pairing --persist-token
+  ```
+
+Verify the file exists (do not print it):
+
+```
+ls "$(npx -y @mehmoodqureshi/chrome-mcp --extension-path)/pairing.json"
+```
+
+Then tell the human where to look. The status badge is on the extension's
+icon in Chrome's toolbar, not on the `chrome://extensions` page. Chrome hides
+new extensions behind the puzzle-piece button at the right of the address bar,
+so give them these exact steps:
+
+1. Click the puzzle-piece button at the right of the address bar.
+2. Find **Chrome MCP Bridge** in the list and click the pin icon next to it.
+   The extension icon now stays in the toolbar.
+3. Look at the small badge on that icon. Hovering it shows the status in words.
+
+Badge meanings: a green dot means paired and connected. Yellow dots mean
+connecting. A grey circle means not paired yet, usually because no server has
+run since the extension was loaded. A red exclamation mark means the token was
+rejected, which the extension fixes by itself within a few seconds by re-reading
+the pairing file.
+
+A green dot can take up to 30 seconds if the extension was loaded before the
+server first ran. Wait for the human to confirm the green dot.
+
+**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 `chrome-mcp-extension` path they loaded.
+- Which MCP client was configured, at which scope, with which domains and gates.
+- Whether the badge went green, and whether `tabs_list`, an allowed
+  navigation, and a refused navigation each verified.
+- 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/cli.js

@@ -21,6 +21,7 @@ const datadir_1 = require("./bridge/datadir");
 const workspace_1 = require("./bridge/workspace");
 const auth_1 = require("./bridge/auth");
 const server_2 = require("./mcp/server");
+const extension_install_1 = require("./extension-install");
 /** Hard deadline for clean shutdown before we force-exit (a stuck socket must not hang us). */
 const SHUTDOWN_DEADLINE_MS = 3000;
 /**
@@ -51,6 +52,25 @@ function version() {
         return '0.0.0';
     }
 }
+/**
+ * Mirror the bundled extension into the visible install folder
+ * (`~/chrome-mcp-extension`) and report where Chrome should load it from. On a
+ * read-only home the bundled folder is returned instead; both are loadable.
+ */
+function installExtension() {
+    const r = (0, extension_install_1.syncExtension)();
+    if (!r.ok) {
+        (0, server_2.logDebug)(`extension not mirrored to the home folder (${r.error}); using the bundled copy at ${r.dir}`);
+        return r.dir;
+    }
+    if (r.created) {
+        (0, server_2.logErr)(`extension installed at ${r.dir} — chrome://extensions -> Load unpacked -> pick that folder`);
+    }
+    else if (r.copied.length > 0) {
+        (0, server_2.logErr)(`extension files updated at ${r.dir} — click Reload on chrome://extensions to pick up the new version`);
+    }
+    return r.dir;
+}
 /** Render a byte count as a short human string (1.2 MB, 904 KB, …). */
 function humanBytes(n) {
     if (n < 1024)
@@ -154,6 +174,10 @@ async function main() {
         process.stdout.write(`${version()}\n`);
         return;
     }
+    if (cfg.showExtensionPath) {
+        process.stdout.write(`${installExtension()}\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 +203,21 @@ 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 extDir = installExtension();
+    const bundled = (0, auth_1.writeBundledPairing)(extDir, { port, token });
+    if (bundled) {
+        (0, server_2.logErr)(`auto-pairing file written to ${bundled} — Load unpacked from ${extDir} needs no token paste`);
+    }
+    else {
+        (0, server_2.logDebug)(`auto-pairing file not written (extension folder missing or read-only at ${extDir})`);
+    }
+    // Anyone who loaded the extension straight from the package folder (0.8.0
+    // docs) keeps pairing too.
+    if (extDir !== (0, extension_install_1.bundledExtensionDir)())
+        (0, auth_1.writeBundledPairing)((0, extension_install_1.bundledExtensionDir)(), { port, token });
     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,12 @@ 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       Install the extension to ~/chrome-mcp-extension (or
+                         CHROME_MCP_EXTENSION_DIR) and print that path — the folder
+                         to pick in chrome://extensions -> Load unpacked. The server
+                         also refreshes it on every boot.
   --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/dist/src/extension-install.d.ts

@@ -0,0 +1,42 @@
+/**
+ * src/extension-install.ts — put the extension somewhere a human can find.
+ *
+ * The extension ships inside the npm package, which is the wrong place to send
+ * someone with a "Load unpacked" file dialog: a global install buries it five
+ * folders deep under `npm root -g`, and an npx run hides it in a cache. So on
+ * every boot (and on `--extension-path`) the server mirrors the bundled
+ * `extension-dist/` into a plain, visible folder directly under the home
+ * directory — `~/chrome-mcp-extension` — and that is the folder the docs, the
+ * pairing file, and `--extension-path` all point at.
+ *
+ * The copy is a one-way mirror of top-level regular files, written only when
+ * content differs, so an unchanged boot touches nothing. It never deletes: the
+ * target may hold `pairing.json` (ours) and, if the operator pointed
+ * CHROME_MCP_EXTENSION_DIR somewhere of their own, files that are not ours to
+ * remove. It never throws — a read-only home just falls back to the bundled
+ * folder, which still works for Load unpacked.
+ */
+/** Folder name under the home directory. */
+export declare const EXTENSION_DIR_NAME = "chrome-mcp-extension";
+/** The auto-pairing file the server writes; never copied, never overwritten by the mirror. */
+export declare const PAIRING_FILE = "pairing.json";
+/** `dist/src/extension-install.js` -> `<pkg>/extension-dist`, which the tarball ships. */
+export declare function bundledExtensionDir(): string;
+/** Where the extension is mirrored for Load unpacked. `CHROME_MCP_EXTENSION_DIR` overrides. */
+export declare function extensionInstallDir(): string;
+export interface SyncResult {
+    /** The folder that now holds the extension (the target on success, the source on failure). */
+    dir: string;
+    /** Files written this run (new or changed). Empty means the target was already current. */
+    copied: string[];
+    /** True when the target folder did not exist before this run (first install). */
+    created: boolean;
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Mirror the bundled extension into the install dir. Returns the folder to
+ * point Chrome at either way: the target when the mirror succeeded, the source
+ * when it did not (so callers always have a loadable folder).
+ */
+export declare function syncExtension(from?: string, to?: string): SyncResult;

package/dist/src/extension-install.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * src/extension-install.ts — put the extension somewhere a human can find.
+ *
+ * The extension ships inside the npm package, which is the wrong place to send
+ * someone with a "Load unpacked" file dialog: a global install buries it five
+ * folders deep under `npm root -g`, and an npx run hides it in a cache. So on
+ * every boot (and on `--extension-path`) the server mirrors the bundled
+ * `extension-dist/` into a plain, visible folder directly under the home
+ * directory — `~/chrome-mcp-extension` — and that is the folder the docs, the
+ * pairing file, and `--extension-path` all point at.
+ *
+ * The copy is a one-way mirror of top-level regular files, written only when
+ * content differs, so an unchanged boot touches nothing. It never deletes: the
+ * target may hold `pairing.json` (ours) and, if the operator pointed
+ * CHROME_MCP_EXTENSION_DIR somewhere of their own, files that are not ours to
+ * remove. It never throws — a read-only home just falls back to the bundled
+ * folder, which still works for Load unpacked.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAIRING_FILE = exports.EXTENSION_DIR_NAME = void 0;
+exports.bundledExtensionDir = bundledExtensionDir;
+exports.extensionInstallDir = extensionInstallDir;
+exports.syncExtension = syncExtension;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+/** Folder name under the home directory. */
+exports.EXTENSION_DIR_NAME = 'chrome-mcp-extension';
+/** The auto-pairing file the server writes; never copied, never overwritten by the mirror. */
+exports.PAIRING_FILE = 'pairing.json';
+/** `dist/src/extension-install.js` -> `<pkg>/extension-dist`, which the tarball ships. */
+function bundledExtensionDir() {
+    return (0, node_path_1.resolve)(__dirname, '..', '..', 'extension-dist');
+}
+/** Where the extension is mirrored for Load unpacked. `CHROME_MCP_EXTENSION_DIR` overrides. */
+function extensionInstallDir() {
+    const override = process.env.CHROME_MCP_EXTENSION_DIR;
+    return override && override.trim() ? (0, node_path_1.resolve)(override.trim()) : (0, node_path_1.join)((0, node_os_1.homedir)(), exports.EXTENSION_DIR_NAME);
+}
+function sameBytes(a, b) {
+    return a.length === b.length && a.equals(b);
+}
+/**
+ * Mirror the bundled extension into the install dir. Returns the folder to
+ * point Chrome at either way: the target when the mirror succeeded, the source
+ * when it did not (so callers always have a loadable folder).
+ */
+function syncExtension(from = bundledExtensionDir(), to = extensionInstallDir()) {
+    const copied = [];
+    let created = false;
+    try {
+        const entries = (0, node_fs_1.readdirSync)(from, { withFileTypes: true }).filter((e) => e.isFile() && e.name !== exports.PAIRING_FILE);
+        if (!entries.some((e) => e.name === 'manifest.json')) {
+            return { dir: from, copied, created, ok: false, error: `no manifest.json in ${from}` };
+        }
+        try {
+            (0, node_fs_1.statSync)(to);
+        }
+        catch {
+            created = true;
+        }
+        (0, node_fs_1.mkdirSync)(to, { recursive: true });
+        for (const e of entries) {
+            const src = (0, node_fs_1.readFileSync)((0, node_path_1.join)(from, e.name));
+            const dst = (0, node_path_1.join)(to, e.name);
+            let current = null;
+            try {
+                if ((0, node_fs_1.statSync)(dst).isFile())
+                    current = (0, node_fs_1.readFileSync)(dst);
+            }
+            catch {
+                /* absent */
+            }
+            if (current && sameBytes(current, src))
+                continue;
+            (0, node_fs_1.writeFileSync)(dst, src);
+            copied.push(e.name);
+        }
+        return { dir: to, copied, created, ok: true };
+    }
+    catch (e) {
+        return { dir: from, copied, created, ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+//# sourceMappingURL=extension-install.js.map

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.9.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,10 +16,11 @@
   </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
-      <code>token</code> below.
+      Manual pairing: run <code>npx -y @mehmoodqureshi/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>
     <input id="port" type="number" inputmode="numeric" placeholder="38017" />

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.1",
+  "version": "0.9.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();