@mehmoodqureshi/chrome-mcp 0.8.0 → 0.9.0

package/README.md

@@ -108,29 +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
-chrome-mcp --extension-path   # prints the absolute path of 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.)
+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
-`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.
+`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
 
@@ -178,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 the folder `chrome-mcp --extension-path` prints 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`/
@@ -423,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/`. 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.
+`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

@@ -33,25 +33,22 @@ npm --version
 
 If Node is below 18, stop and tell the human to upgrade before anything else.
 
-## Step 2 — Install the package globally
+## Step 2 — Install the extension folder
 
-A global install gives the extension a stable path that Chrome can load from.
+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:
 
 ```
-npm install -g @mehmoodqureshi/chrome-mcp
-chrome-mcp --version
+npx -y @mehmoodqureshi/chrome-mcp --extension-path
 ```
 
-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.
+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
 
@@ -108,7 +105,8 @@ 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.
+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.
@@ -116,7 +114,7 @@ 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.
+(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:
 
@@ -124,19 +122,33 @@ sure a server has booted at least once since step 2, in either of these ways:
 - start one yourself in pairing mode and leave it running in the background:
 
   ```
-  chrome-mcp --print-pairing --persist-token
+  npx -y @mehmoodqureshi/chrome-mcp --print-pairing --persist-token
   ```
 
 Verify the file exists (do not print it):
 
 ```
-ls "$(chrome-mcp --extension-path)/pairing.json"
+ls "$(npx -y @mehmoodqureshi/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.
+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
@@ -178,10 +190,10 @@ not stick. Re-check the port and token before anything else.
 Summarize for the human:
 
 - Node and package versions installed.
-- The absolute `extension-dist` path they loaded.
+- The absolute `chrome-mcp-extension` 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.
+- 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

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;
 /**
@@ -52,12 +53,23 @@ function version() {
     }
 }
 /**
- * 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.
+ * 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 extensionPath() {
-    return (0, node_path_1.resolve)(__dirname, '..', '..', 'extension-dist');
+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) {
@@ -163,7 +175,7 @@ async function main() {
         return;
     }
     if (cfg.showExtensionPath) {
-        process.stdout.write(`${extensionPath()}\n`);
+        process.stdout.write(`${installExtension()}\n`);
         return;
     }
     const dataDir = (0, datadir_1.ensureDataDir)(cfg.dataDir);
@@ -194,13 +206,18 @@ async function main() {
     // 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 });
+    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 that folder needs no token paste`);
+        (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 ${extensionPath()})`);
+        (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.js

@@ -274,8 +274,10 @@ Connection:
                          land in profiles/<profile>/tasks/<task>/.
   --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)
+  --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/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/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Chrome MCP Bridge",
-  "version": "0.8.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

@@ -18,9 +18,9 @@
     <h1>Pair with chrome-mcp</h1>
     <p class="hint" id="source">Checking pairing source…</p>
     <p class="hint">
-      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.
+      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/package.json

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