@mehmoodqureshi/chrome-mcp 0.6.4 → 0.6.6

package/README.md

@@ -4,10 +4,17 @@
 [![npm](https://img.shields.io/npm/v/%40mehmoodqureshi%2Fchrome-mcp?label=npm)](https://www.npmjs.com/package/@mehmoodqureshi/chrome-mcp)
 [![license](https://img.shields.io/npm/l/%40mehmoodqureshi%2Fchrome-mcp?label=license)](LICENSE)
 
-Drive a **real Chrome browser** from Claude (or any MCP host). An MV3 extension
-drives your real Chrome — real logins, real cookies — via
-`chrome.scripting`/`chrome.tabs`. The CLI runs a localhost WebSocket server; the
-extension dials in.
+**Let Claude use the Chrome you are already logged into.** Not a fresh
+automated browser that greets every site as a stranger — *your* Chrome, with
+your sessions, your cookies, your 2FA already done. If you can see a page in
+your browser, your agent can read it, without logging in again and without
+pasting credentials anywhere.
+
+Most browser MCP servers launch their own Chromium and hand your agent a
+signed-out window. chrome-mcp does the opposite: an MV3 extension dials into a
+localhost WebSocket server and drives the browser you already have open, through
+`chrome.scripting`/`chrome.tabs`. Works with Claude Code, Claude Desktop, and any
+other MCP host.
 
 Distributed as an `npx` CLI (the MCP server) plus a load-unpacked extension.
 
@@ -22,19 +29,48 @@ Distributed as an `npx` CLI (the MCP server) plus a load-unpacked extension.
 
 ## Quickstart
 
-**1. Register the MCP server** with your host (e.g. Claude Desktop / Code):
+**1. Register the MCP server** with your host.
+
+<details open>
+<summary><b>Claude Code (terminal)</b> — one command, no config file to find</summary>
+
+```bash
+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 this
+server's command and flags. Keep the `--` or `--allow-domain` gets read as a
+Claude Code option.
+
+`-s user` registers it for every project on your machine. Use `-s local` (the
+default) for just the current project, or `-s project` to write a `.mcp.json`
+your team can commit.
+
+Check it came up with `claude mcp list`. After upgrading the server, reconnect it
+with `/mcp` inside a session — no restart needed.
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b> and other MCP hosts — JSON config</summary>
 
 ```jsonc
 {
   "mcpServers": {
     "chrome-mcp": {
       "command": "npx",
-      "args": ["-y", "@mehmoodqureshi/chrome-mcp", "--allow-domain", "example.com", "--enable-mutations"]
+      "args": ["-y", "@mehmoodqureshi/chrome-mcp",
+               "--allow-domain", "example.com", "--enable-mutations",
+               "--persist-token"]
     }
   }
 }
 ```
 
+</details>
+
 By default everything is **deny-all** (no domains, no eval, no mutations). Grant
 exactly what you need with `--allow-domain <glob>` (repeatable), `--enable-mutations`,
 `--enable-downloads`, `--enable-uploads`, `--unsafe-enable-eval`, or `--unsafe-all-domains`.
@@ -45,21 +81,9 @@ exactly what you need with `--allow-domain <glob>` (repeatable), `--enable-mutat
 > with `--uploads-dir <path>` to restrict uploads to files inside that directory
 > (`..` traversal is blocked) — strongly recommended for unattended use.
 
-**Pair once, never again.** Add `--persist-token` so the pairing token survives
-restarts:
-
-```jsonc
-{
-  "mcpServers": {
-    "chrome-mcp": {
-      "command": "npx",
-      "args": ["-y", "@mehmoodqureshi/chrome-mcp",
-               "--allow-domain", "example.com", "--enable-mutations",
-               "--persist-token"]
-    }
-  }
-}
-```
+**Pair once, never again.** Both examples above include `--persist-token`, which
+is what makes the pairing survive a restart — drop it if you'd rather have the
+stricter default described next.
 
 Without `--persist-token` a fresh token is minted every boot (the secure
 default), which means re-pairing the extension on each restart. With it, the

package/dist/shared/protocol.d.ts

@@ -27,6 +27,18 @@ export declare const BRIDGE_HOST: "127.0.0.1";
 /** WebSocket close codes we use deliberately. */
 export declare const CLOSE_UNAUTHORIZED: 4401;
 export declare const CLOSE_SUPERSEDED: 4000;
+/**
+ * Capabilities an extension advertises in `hello`. Additive and optional, so an
+ * older extension (which sends none) keeps the conservative behaviour — never
+ * gate a capability behind a version-string comparison.
+ *
+ * `tab-url`: this extension (a) enforces the policy mirror FAIL-CLOSED — it
+ * refuses every command until a policy has arrived — and (b) reports the target
+ * tab's post-command URL as `ResultFrame.tabUrl`. Together those let the server
+ * gate from the reported URL instead of paying a `tabs_list` round-trip before
+ * every call. Without it, the server falls back to fetching the URL itself.
+ */
+export declare const WIRE_CAP_TAB_URL: "tab-url";
 /**
  * Every method that may travel on the wire = the MCP primitives 1:1, plus
  * `download_file` (privileged, executor-owned) and `ping_probe` (a short-deadline
@@ -52,6 +64,9 @@ export interface HelloFrame extends BaseFrame {
      *  NOT a security boundary (the token is) — it selects which connection slot the
      *  server routes commands to, so several browsers can stay paired at once. */
     profile?: string;
+    /** Optional capability advertisements (see `WIRE_CAP_TAB_URL`). An extension
+     *  that sends none gets the conservative path, so old builds stay correct. */
+    caps?: string[];
 }
 /**
  * The wire-serializable subset of the server's policy, delivered in `welcome` so
@@ -92,6 +107,13 @@ export interface ResultFrame extends BaseFrame {
     ok: true;
     /** For `screenshot`: { dataBase64, mimeType, width, height, truncated }. */
     data: unknown;
+    /**
+     * The target tab's URL as observed AFTER the command ran — the extension has
+     * it locally, so sending it costs nothing and saves the server a round-trip
+     * on the next policy gate. Omitted when it can't be resolved (e.g. the tab was
+     * closed). Only sent by extensions advertising `WIRE_CAP_TAB_URL`.
+     */
+    tabUrl?: string;
 }
 export interface ErrorFrame extends BaseFrame {
     type: 'error';

package/dist/shared/protocol.js

@@ -14,7 +14,7 @@
  * wire method beyond the primitives.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WIRE_METHODS = exports.CLOSE_SUPERSEDED = exports.CLOSE_UNAUTHORIZED = exports.BRIDGE_HOST = exports.DEFAULT_WS_PORT = exports.PROTOCOL_VERSION = void 0;
+exports.WIRE_METHODS = exports.WIRE_CAP_TAB_URL = exports.CLOSE_SUPERSEDED = exports.CLOSE_UNAUTHORIZED = exports.BRIDGE_HOST = exports.DEFAULT_WS_PORT = exports.PROTOCOL_VERSION = void 0;
 /** Bumped on any breaking change to the frames below. */
 exports.PROTOCOL_VERSION = 1;
 /**
@@ -29,6 +29,18 @@ exports.BRIDGE_HOST = '127.0.0.1';
 /** WebSocket close codes we use deliberately. */
 exports.CLOSE_UNAUTHORIZED = 4401;
 exports.CLOSE_SUPERSEDED = 4000;
+/**
+ * Capabilities an extension advertises in `hello`. Additive and optional, so an
+ * older extension (which sends none) keeps the conservative behaviour — never
+ * gate a capability behind a version-string comparison.
+ *
+ * `tab-url`: this extension (a) enforces the policy mirror FAIL-CLOSED — it
+ * refuses every command until a policy has arrived — and (b) reports the target
+ * tab's post-command URL as `ResultFrame.tabUrl`. Together those let the server
+ * gate from the reported URL instead of paying a `tabs_list` round-trip before
+ * every call. Without it, the server falls back to fetching the URL itself.
+ */
+exports.WIRE_CAP_TAB_URL = 'tab-url';
 /** Runtime list of every WireMethod, for boot-time drift assertions on both ends. */
 exports.WIRE_METHODS = [
     'tabs_list',

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

@@ -17,6 +17,8 @@ export interface ConnectionDeps {
     extId: string;
     sessionId: string;
     heartbeatMs: number;
+    /** Capabilities from `hello` (see WIRE_CAP_TAB_URL). Old builds send none. */
+    caps?: string[];
     onEvent?: (event: WireEvent, data: Record<string, unknown>) => void;
     onClose?: (code: number) => void;
     onLog?: (message: string) => void;
@@ -30,6 +32,10 @@ export declare class ExtensionConnection {
     private closed;
     private heartbeat;
     private missedPongs;
+    /** Whether this extension reports `tabUrl` and gates fail-closed. */
+    private readonly reportsTabUrl;
+    /** Last URL the ACTIVE tab reported, with the wall-clock it arrived. */
+    private activeUrl;
     private readonly onEvent?;
     private readonly onClose?;
     private readonly onLog?;
@@ -43,6 +49,18 @@ export declare class ExtensionConnection {
     isOpen(): boolean;
     private handleMessage;
     private settle;
+    /**
+     * Cache the URL a result rode home with — but ONLY when it describes the active
+     * tab (no explicit tabId) and actually resolved. A blank `tabUrl` means the
+     * extension couldn't read it (closed tab, restricted page), which is a reason
+     * to forget what we knew, never to keep believing it.
+     */
+    private rememberActiveUrl;
+    /**
+     * The active tab's last reported URL if it is younger than `maxAgeMs`, else
+     * null — the caller then resolves it the slow way. Never returns a guess.
+     */
+    lastActiveUrl(maxAgeMs: number): string | null;
     private handleClose;
     private startHeartbeat;
 }

package/dist/src/bridge/connection.js

@@ -36,6 +36,8 @@ function mapWireErrorCode(code) {
     };
     return known[code] ?? 'TARGET_GONE';
 }
+/** Commands that can change WHICH tab is active, invalidating a cached URL. */
+const ACTIVE_TAB_CHANGERS = new Set(['tab_select', 'tab_new', 'tab_close']);
 class ExtensionConnection {
     extId;
     sessionId;
@@ -45,6 +47,10 @@ class ExtensionConnection {
     closed = false;
     heartbeat = null;
     missedPongs = 0;
+    /** Whether this extension reports `tabUrl` and gates fail-closed. */
+    reportsTabUrl;
+    /** Last URL the ACTIVE tab reported, with the wall-clock it arrived. */
+    activeUrl = null;
     onEvent;
     onClose;
     onLog;
@@ -52,6 +58,7 @@ class ExtensionConnection {
         this.ws = deps.ws;
         this.extId = deps.extId;
         this.sessionId = deps.sessionId;
+        this.reportsTabUrl = deps.caps?.includes(protocol_1.WIRE_CAP_TAB_URL) ?? false;
         this.onEvent = deps.onEvent;
         this.onClose = deps.onClose;
         this.onLog = deps.onLog;
@@ -71,6 +78,11 @@ class ExtensionConnection {
         }
         const id = String(++this.seq);
         const timeoutMs = opts?.timeoutMs ?? defaultTimeoutFor(method);
+        // Anything that reshuffles tabs makes the cached URL a claim about a tab that
+        // may no longer be the active one. Drop it before the command, not after, so
+        // a failure mid-flight can't leave a stale entry behind.
+        if (ACTIVE_TAB_CHANGERS.has(method))
+            this.activeUrl = null;
         const frame = {
             type: 'command',
             v: protocol_1.PROTOCOL_VERSION,
@@ -86,7 +98,7 @@ class ExtensionConnection {
                 reject(new types_1.ExecutorError('TIMEOUT', `"${method}" timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             timer.unref?.();
-            this.pending.set(id, { resolve, reject, timer, method });
+            this.pending.set(id, { resolve, reject, timer, method, activeTab: opts?.tabId === undefined });
             try {
                 this.ws.send(JSON.stringify(frame));
             }
@@ -148,12 +160,38 @@ class ExtensionConnection {
         clearTimeout(p.timer);
         this.pending.delete(id);
         if (frame.type === 'result') {
+            this.rememberActiveUrl(p, frame);
             p.resolve(frame.data);
         }
         else {
+            // A failed command tells us nothing reliable about where the tab ended up.
+            if (p.activeTab)
+                this.activeUrl = null;
             p.reject(new types_1.ExecutorError(mapWireErrorCode(frame.error.code), frame.error.message));
         }
     }
+    /**
+     * Cache the URL a result rode home with — but ONLY when it describes the active
+     * tab (no explicit tabId) and actually resolved. A blank `tabUrl` means the
+     * extension couldn't read it (closed tab, restricted page), which is a reason
+     * to forget what we knew, never to keep believing it.
+     */
+    rememberActiveUrl(p, frame) {
+        if (!this.reportsTabUrl || !p.activeTab)
+            return;
+        if (ACTIVE_TAB_CHANGERS.has(p.method))
+            return; // already invalidated; re-caching would race
+        this.activeUrl = frame.tabUrl ? { url: frame.tabUrl, at: Date.now() } : null;
+    }
+    /**
+     * The active tab's last reported URL if it is younger than `maxAgeMs`, else
+     * null — the caller then resolves it the slow way. Never returns a guess.
+     */
+    lastActiveUrl(maxAgeMs) {
+        if (!this.activeUrl)
+            return null;
+        return Date.now() - this.activeUrl.at <= maxAgeMs ? this.activeUrl.url : null;
+    }
     handleClose(code) {
         if (this.closed)
             return;

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

@@ -65,6 +65,12 @@ export declare class BridgeServer {
         timeoutMs?: number;
         profile?: string;
     }): Promise<unknown>;
+    /**
+     * The active tab's URL for `profile` as last reported by the extension, if it
+     * is younger than `maxAgeMs`. Null means "ask properly" — an extension too old
+     * to report URLs, a tab shuffle since, or simply nothing recent enough.
+     */
+    lastActiveUrl(profile: string | undefined, maxAgeMs: number): string | null;
     private noPairMessage;
     status(): {
         extensionConnected: boolean;

package/dist/src/bridge/server.js

@@ -178,6 +178,15 @@ class BridgeServer {
         }
         return conn.sendCommand(method, params, opts);
     }
+    /**
+     * The active tab's URL for `profile` as last reported by the extension, if it
+     * is younger than `maxAgeMs`. Null means "ask properly" — an extension too old
+     * to report URLs, a tab shuffle since, or simply nothing recent enough.
+     */
+    lastActiveUrl(profile, maxAgeMs) {
+        const conn = this.conns.get(routeKey(profile));
+        return conn?.isOpen() ? conn.lastActiveUrl(maxAgeMs) : null;
+    }
     noPairMessage(profile) {
         return (`No browser is paired for profile "${profile}". In that Chrome's chrome-mcp ` +
             `extension Options, set Port ${this.boundPort}, paste the token, set Profile to ` +
@@ -235,7 +244,7 @@ class BridgeServer {
             authed = true;
             clearTimeout(helloTimer);
             ws.off('message', onMessage);
-            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' }, routeKey(frame.profile));
+            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' }, routeKey(frame.profile), Array.isArray(frame.caps) ? frame.caps : undefined);
         };
         ws.on('message', onMessage);
         ws.on('error', () => {
@@ -252,7 +261,7 @@ class BridgeServer {
             /* ignore */
         }
     }
-    promote(ws, ext, profile) {
+    promote(ws, ext, profile, caps) {
         const sessionId = (0, node_crypto_1.randomUUID)();
         // Supersede only the SAME profile's connection (a re-pair). Other profiles
         // keep their live connections, so several browsers stay paired at once.
@@ -275,6 +284,7 @@ class BridgeServer {
             extId: ext.id,
             sessionId,
             heartbeatMs: this.heartbeatMs,
+            caps,
             onEvent: this.opts.onEvent,
             onLog: (m) => this.log(m),
             onClose: () => {

package/dist/src/executor/extension-executor.d.ts

@@ -21,6 +21,9 @@ export declare class ExtensionExecutor implements Executor {
     ensureReady(): Promise<void>;
     ping(deadlineMs?: number): Promise<boolean>;
     dispose(): Promise<void>;
+    /** The active tab's URL as reported by the last command on this profile, if it
+     *  is fresh enough to gate against. See `ACTIVE_URL_TTL_MS`. */
+    cachedActiveUrl(): string | null;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
     tabNew(url?: string, opts?: {

package/dist/src/executor/extension-executor.js

@@ -12,6 +12,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExtensionExecutor = void 0;
 const types_1 = require("./types");
 const workspace_1 = require("../bridge/workspace");
+/**
+ * How long a reported active-tab URL stays usable for the policy gate.
+ *
+ * Deliberately short. It exists to cover back-to-back calls (a `batch`, or an
+ * agent's read → click → read), where the tab demonstrably has not changed
+ * between them. Past that, pay the round-trip. Note the extension re-gates every
+ * command against the tab's live URL regardless, so this window trades a little
+ * pre-check precision for half the traffic — never enforcement itself.
+ */
+const ACTIVE_URL_TTL_MS = 1_000;
 /** Flatten a Target into the params a wire command carries. */
 function targetParams(t) {
     if (!t)
@@ -64,6 +74,11 @@ class ExtensionExecutor {
     async dispose() {
         // Never close the user's Chrome.
     }
+    /** The active tab's URL as reported by the last command on this profile, if it
+     *  is fresh enough to gate against. See `ACTIVE_URL_TTL_MS`. */
+    cachedActiveUrl() {
+        return this.bridge.lastActiveUrl(this.activeProfile(), ACTIVE_URL_TTL_MS);
+    }
     // -- tabs ---------------------------------------------------------------
     async tabsList() {
         return (await this.send('tabs_list', {}));

package/dist/src/executor/stub-executor.d.ts

@@ -13,14 +13,43 @@ export interface StubOptions {
     activeUrl?: string;
     /** When true, `eval` resolves `{ok:false}` to mimic a page-side throw. */
     evalThrows?: boolean;
+    /** When true, `tabsList` rejects — mimics a transient bridge failure. */
+    tabsListThrows?: boolean;
+    /** When true, `tabsList` resolves empty — mimics a browser reporting no tabs. */
+    noTabs?: boolean;
+    /** When true, the (single) tab reports an empty URL — mimics a chrome:// page
+     *  or a site the extension has no host access to. */
+    blankTabUrl?: boolean;
+    /** A URL the backend claims to already know, as the extension reports on every
+     *  result frame. Set it to assert the gate uses it INSTEAD of calling tabsList. */
+    cachedUrl?: string;
+    /** Background (non-active) tabs, so a test can target one by an explicit tabId
+     *  and check the gate authorizes against THAT tab rather than the active one. */
+    backgroundTabs?: Array<{
+        tabId: TabId;
+        url: string;
+    }>;
+    /** When true, tabs exist but none is flagged active — the case the gate used to
+     *  paper over by silently gating against `tabs[0]`. */
+    noActiveTab?: boolean;
 }
 export declare class StubExecutor implements Executor {
     readonly backend: BackendKind;
     private url;
     private readonly evalThrows;
+    private readonly tabsListThrows;
+    private readonly noTabs;
+    private readonly blankTabUrl;
+    private readonly cached;
+    private readonly backgroundTabs;
+    private readonly noActiveTab;
+    /** How many times the gate actually asked for the tab list — the round-trip
+     *  counter the caching path exists to keep at zero. */
+    tabsListCalls: number;
     private ready;
     constructor(opts?: StubOptions);
     private tab;
+    cachedActiveUrl(): string | null;
     status(): ExecutorStatus;
     ensureReady(): Promise<void>;
     ping(): Promise<boolean>;

package/dist/src/executor/stub-executor.js

@@ -10,6 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StubExecutor = void 0;
+const types_1 = require("./types");
 /** 1×1 transparent PNG, base64 — a valid image block for screenshot tests. */
 const TINY_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
 const ok = { ok: true };
@@ -17,13 +18,37 @@ class StubExecutor {
     backend = 'extension';
     url;
     evalThrows;
+    tabsListThrows;
+    noTabs;
+    blankTabUrl;
+    cached;
+    backgroundTabs;
+    noActiveTab;
+    /** How many times the gate actually asked for the tab list — the round-trip
+     *  counter the caching path exists to keep at zero. */
+    tabsListCalls = 0;
     ready = false;
     constructor(opts = {}) {
         this.url = opts.activeUrl ?? 'about:blank';
         this.evalThrows = opts.evalThrows ?? false;
+        this.tabsListThrows = opts.tabsListThrows ?? false;
+        this.noTabs = opts.noTabs ?? false;
+        this.blankTabUrl = opts.blankTabUrl ?? false;
+        this.cached = opts.cachedUrl ?? null;
+        this.backgroundTabs = opts.backgroundTabs ?? [];
+        this.noActiveTab = opts.noActiveTab ?? false;
     }
     tab() {
-        return { tabId: 'extension:stub:1', url: this.url, title: 'Stub Page', active: true, index: 0 };
+        return {
+            tabId: 'extension:stub:1',
+            url: this.blankTabUrl ? '' : this.url,
+            title: 'Stub Page',
+            active: !this.noActiveTab,
+            index: 0,
+        };
+    }
+    cachedActiveUrl() {
+        return this.cached;
     }
     status() {
         return {
@@ -44,7 +69,21 @@ class StubExecutor {
         this.ready = false;
     }
     async tabsList() {
-        return [this.tab()];
+        this.tabsListCalls++;
+        if (this.tabsListThrows)
+            throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub bridge is down');
+        if (this.noTabs)
+            return [];
+        return [
+            this.tab(),
+            ...this.backgroundTabs.map((t, i) => ({
+                tabId: t.tabId,
+                url: t.url,
+                title: 'Stub Background Page',
+                active: false,
+                index: i + 1,
+            })),
+        ];
     }
     async tabSelect(tabId) {
         return { ...this.tab(), tabId };

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

@@ -155,6 +155,14 @@ export interface Executor {
     ping(deadlineMs?: number): Promise<boolean>;
     /** Close ONLY if we own the browser; never the user's Chrome. */
     dispose(): Promise<void>;
+    /**
+     * The active tab's URL if the backend ALREADY knows it — the extension reports
+     * it on every result frame, so a gate that runs right after a command needs no
+     * round-trip. Null means "not known recently enough", and the caller must then
+     * resolve it properly; it never returns a guess. Optional: backends that can't
+     * report cheaply simply omit it.
+     */
+    cachedActiveUrl?(): string | null;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
     /** Open a tab. `active` (default true) focuses it; pass false to open in the background. */

package/dist/src/mcp/tools.js

@@ -81,19 +81,79 @@ exports.TOOL_DEFINITIONS = [
         },
     },
 ];
-/** Resolve the URL the policy should be evaluated against (the active tab). */
-async function activeUrl(ex) {
+const GATE_CONTEXT = 'cannot resolve the target tab URL for the policy gate';
+/**
+ * Resolve the URL the policy should be evaluated against: the URL of the tab
+ * this very call will act on — the explicit `tabId` when the caller gave one,
+ * the active tab only when they didn't.
+ *
+ * Gating on the ACTIVE tab regardless of `tabId` is an authorization bypass:
+ * park an allowlisted page as active and every `tabId`-addressed read (get_text,
+ * get_html, screenshot, eval, …) sails through against a tab whose origin was
+ * never checked. The tab that gets touched is the tab that must be authorized.
+ *
+ * NEVER substitutes a placeholder URL, and never falls back to some *other*
+ * tab. If the real origin is unknown, evaluating the policy against a stand-in
+ * would silently allow or deny against the wrong origin with no signal to the
+ * caller. So a `tabsList` failure (or a browser reporting no tabs at all)
+ * propagates — the dispatch firewall renders it as an error carrying the code.
+ *
+ * Prefers a URL the backend already reported over asking again: the extension
+ * rides the tab's landing URL home on every result frame, which is what keeps a
+ * gated call to ONE round-trip instead of two. That cache only ever describes
+ * the active tab, so it is bypassed whenever an explicit `tabId` is in play.
+ */
+async function gatedUrl(ex, tabId) {
+    if (!tabId) {
+        const known = ex.cachedActiveUrl?.();
+        if (known)
+            return known;
+    }
+    let tabs;
     try {
-        const tabs = await ex.tabsList();
-        return tabs.find((t) => t.active)?.url ?? tabs[0]?.url ?? 'about:blank';
+        tabs = await ex.tabsList();
     }
-    catch {
-        return 'about:blank';
+    catch (err) {
+        // Keep the underlying code (TIMEOUT / EXTENSION_DISCONNECTED / …) so the
+        // caller can tell a transient bridge failure from a policy decision — the
+        // rendered message is prefixed with it, since only the text crosses MCP.
+        if (err instanceof types_1.ExecutorError)
+            throw new types_1.ExecutorError(err.code, `${GATE_CONTEXT}: ${err.message}`);
+        throw err; // an internal fault, not a browser one — don't relabel it
     }
+    if (tabs.length === 0) {
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the browser reports no open tabs`);
+    }
+    const target = tabId ? tabs.find((t) => t.tabId === tabId) : tabs.find((t) => t.active);
+    if (!target) {
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', tabId
+            ? `${GATE_CONTEXT}: no open tab has id ${tabId} — call tabs_list for the current ids`
+            : `${GATE_CONTEXT}: the browser reports open tabs but none active — pass an explicit tabId`);
+    }
+    // An empty URL is Chrome declining to reveal one (a chrome:// page, or a tab
+    // the extension has no host access to) — NOT an origin. Gating on '' would
+    // produce a baffling "blocked on " denial that reads like a policy decision.
+    if (!target.url) {
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the target tab (id ${target.tabId}) reports no URL. Chrome hides it for ` +
+            `internal pages (chrome://, the Web Store) and until the extension has access to that site — ` +
+            `switch to a normal page, or open the target site in a new tab.`);
+    }
+    return target.url;
 }
-/** Policy chokepoint. `urlOverride` is the destination for navigation. */
-async function gate(ctx, method, urlOverride) {
-    const url = urlOverride ?? (await activeUrl(ctx.ex));
+/**
+ * Policy chokepoint. `opts.url` is the destination for navigation (it governs
+ * instead of any current tab URL); `opts.tabId` is the tab the call will act on,
+ * and MUST be threaded through by every URL-gated handler that accepts one —
+ * omitting it silently authorizes the call against the active tab instead.
+ *
+ * Only resolves a tab URL for methods whose verdict actually depends on one
+ * (`isUrlGated`). Tab management and the capability gates — eval, downloads,
+ * uploads, mutations — are decided without any URL, so making them wait on the
+ * tab list bought nothing and, worse, made `tab_new` fail exactly when the tab
+ * list was unreadable: the one call that could dig you out.
+ */
+async function gate(ctx, method, opts = {}) {
+    const url = opts.url ?? ((0, policy_1.isUrlGated)(method) ? await gatedUrl(ctx.ex, opts.tabId) : '');
     (0, policy_1.assertUrlAllowed)(url, method, ctx.policy);
 }
 const tabId = (args) => (0, validators_1.optionalString)(args, 'tabId');
@@ -139,24 +199,24 @@ exports.TOOL_HANDLERS = {
     },
     navigate: async (a, ctx) => {
         const url = (0, validators_1.requireString)(a, 'url');
-        await gate(ctx, 'navigate', url);
+        await gate(ctx, 'navigate', { url });
         return (0, envelopes_1.jsonResult)(await ctx.ex.navigate({ url, tabId: tabId(a), waitUntil: waitUntil(a) }));
     },
     back: async (a, ctx) => {
-        await gate(ctx, 'back');
+        await gate(ctx, 'back', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.back(tabId(a)));
     },
     forward: async (a, ctx) => {
-        await gate(ctx, 'forward');
+        await gate(ctx, 'forward', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.forward(tabId(a)));
     },
     reload: async (a, ctx) => {
-        await gate(ctx, 'reload');
+        await gate(ctx, 'reload', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) }));
     },
     click: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'click');
+        await gate(ctx, 'click', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.click(t, {
             tabId: tabId(a),
             button: (0, validators_1.optionalString)(a, 'button'),
@@ -166,7 +226,7 @@ exports.TOOL_HANDLERS = {
     },
     type: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'type');
+        await gate(ctx, 'type', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.type(t, (0, validators_1.requireWithinLength)((0, validators_1.requireString)(a, 'text'), 'text', validators_1.MAX_TEXT_LEN), {
             tabId: tabId(a),
             clear: (0, validators_1.optionalBoolean)(a, 'clear'),
@@ -177,14 +237,14 @@ exports.TOOL_HANDLERS = {
     },
     select_option: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'type'); // mutating
+        await gate(ctx, 'type', { tabId: tabId(a) }); // mutating
         const values = (0, validators_1.optionalStringArray)(a, 'values');
         if (!values || values.length === 0)
             throw new validators_1.McpToolError('"values" must be a non-empty array of strings');
         return (0, envelopes_1.jsonResult)(await ctx.ex.selectOption(t, values, { tabId: tabId(a) }));
     },
     press: async (a, ctx) => {
-        await gate(ctx, 'press');
+        await gate(ctx, 'press', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
             tabId: tabId(a),
             modifiers: (0, validators_1.optionalStringArray)(a, 'modifiers'),
@@ -192,11 +252,11 @@ exports.TOOL_HANDLERS = {
     },
     hover: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'hover');
+        await gate(ctx, 'hover', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.hover(t, { tabId: tabId(a) }));
     },
     scroll: async (a, ctx) => {
-        await gate(ctx, 'scroll');
+        await gate(ctx, 'scroll', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.scroll({
             tabId: tabId(a),
             x: (0, validators_1.optionalNumber)(a, 'x'),
@@ -207,7 +267,7 @@ exports.TOOL_HANDLERS = {
         }));
     },
     screenshot: async (a, ctx) => {
-        await gate(ctx, 'screenshot');
+        await gate(ctx, 'screenshot', { tabId: tabId(a) });
         const shot = await ctx.ex.screenshot({
             tabId: tabId(a),
             fullPage: (0, validators_1.optionalBoolean)(a, 'fullPage'),
@@ -218,17 +278,17 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.imageResult)(shot.dataBase64, shot.mimeType, caption);
     },
     get_text: async (a, ctx) => {
-        await gate(ctx, 'get_text');
+        await gate(ctx, 'get_text', { tabId: tabId(a) });
         const res = await ctx.ex.getText((0, validators_1.optionalTarget)(a), { tabId: tabId(a) });
         (0, workspace_1.saveResult)('get_text', 'json', JSON.stringify(res, null, 2));
         return (0, envelopes_1.jsonResult)(res);
     },
     get_html: async (a, ctx) => {
-        await gate(ctx, 'get_html');
+        await gate(ctx, 'get_html', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.getHtml((0, validators_1.optionalTarget)(a), { tabId: tabId(a), outer: (0, validators_1.optionalBoolean)(a, 'outer') }));
     },
     snapshot: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // read of page structure
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page structure
         return (0, envelopes_1.jsonResult)(await ctx.ex.snapshot({
             tabId: tabId(a),
             interactiveOnly: (0, validators_1.optionalBoolean)(a, 'interactiveOnly'),
@@ -236,13 +296,13 @@ exports.TOOL_HANDLERS = {
         }));
     },
     get_cookies: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // reads tab-scoped secrets; same domain gate as content reads
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // reads tab-scoped secrets; same domain gate as content reads
         return (0, envelopes_1.jsonResult)(await ctx.ex.getCookies({ tabId: tabId(a), url: (0, validators_1.optionalString)(a, 'url') }));
     },
     storage: async (a, ctx) => {
         const op = (0, validators_1.requireString)(a, 'op');
         // get is a read; set/remove/clear mutate.
-        await gate(ctx, op === 'get' ? 'get_text' : 'type');
+        await gate(ctx, op === 'get' ? 'get_text' : 'type', { tabId: tabId(a) });
         if ((op === 'set' || op === 'remove') && !(0, validators_1.optionalString)(a, 'key')) {
             throw new validators_1.McpToolError(`storage "${op}" requires a "key"`);
         }
@@ -255,14 +315,14 @@ exports.TOOL_HANDLERS = {
         }));
     },
     eval: async (a, ctx) => {
-        await gate(ctx, 'eval');
+        await gate(ctx, 'eval', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.eval((0, validators_1.requireString)(a, 'expression'), {
             tabId: tabId(a),
             awaitPromise: (0, validators_1.optionalBoolean)(a, 'awaitPromise'),
         }));
     },
     wait_for: async (a, ctx) => {
-        await gate(ctx, 'wait_for');
+        await gate(ctx, 'wait_for', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.waitFor({
             tabId: tabId(a),
             selector: (0, validators_1.optionalString)(a, 'selector'),
@@ -272,7 +332,7 @@ exports.TOOL_HANDLERS = {
         }));
     },
     extract_links: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // read of page content
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page content
         const res = await (0, helpers_1.extractLinks)(ctx.ex, {
             selector: (0, validators_1.optionalString)(a, 'selector'),
             sameOriginOnly: (0, validators_1.optionalBoolean)(a, 'sameOriginOnly'),
@@ -284,13 +344,13 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.jsonResult)(res);
     },
     read_as_markdown: async (a, ctx) => {
-        await gate(ctx, 'get_text');
+        await gate(ctx, 'get_text', { tabId: tabId(a) });
         const md = await (0, helpers_1.readAsMarkdown)(ctx.ex, { selector: (0, validators_1.optionalString)(a, 'selector'), tabId: tabId(a) });
         (0, workspace_1.saveResult)('read_as_markdown', 'md', md);
         return (0, envelopes_1.textResult)(md);
     },
     fill_form: async (a, ctx) => {
-        await gate(ctx, 'type'); // mutating
+        await gate(ctx, 'type', { tabId: tabId(a) }); // mutating
         const fields = a.fields;
         if (typeof fields !== 'object' || fields === null || Array.isArray(fields)) {
             throw new validators_1.McpToolError('"fields" must be an object mapping selector -> string|boolean');
@@ -315,7 +375,7 @@ exports.TOOL_HANDLERS = {
     },
     upload_file: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'upload_file');
+        await gate(ctx, 'upload_file', { tabId: tabId(a) });
         const files = (0, validators_1.optionalStringArray)(a, 'files');
         if (!files || files.length === 0)
             throw new validators_1.McpToolError('"files" must be a non-empty array of absolute local paths');
@@ -349,7 +409,12 @@ exports.TOOL_HANDLERS = {
 // Dispatch (never-throw firewall)
 // ---------------------------------------------------------------------------
 function errMessage(err) {
-    if (err instanceof validators_1.McpToolError || err instanceof types_1.ExecutorError)
+    // Only the text crosses the MCP boundary, so the code has to travel inside it —
+    // otherwise a caller cannot tell EXTENSION_DISCONNECTED (retry in a moment)
+    // from POLICY_DENIED (retrying will never help).
+    if (err instanceof types_1.ExecutorError)
+        return `[${err.code}] ${err.message}`;
+    if (err instanceof validators_1.McpToolError)
         return err.message;
     if (err instanceof Error)
         return `internal error: ${err.message}`;

package/extension-dist/background.js

@@ -2,6 +2,7 @@
 (() => {
   // shared/protocol.ts
   var PROTOCOL_VERSION = 1;
+  var WIRE_CAP_TAB_URL = "tab-url";
   var WIRE_METHODS = [
     "tabs_list",
     "tab_select",
@@ -63,7 +64,11 @@
           v: PROTOCOL_VERSION,
           token,
           ext: { id: chrome.runtime.id, version: chrome.runtime.getManifest().version, chrome: chromeVersion() },
-          profile: profile && profile.trim() ? profile.trim() : void 0
+          profile: profile && profile.trim() ? profile.trim() : void 0,
+          // This build gates fail-closed and reports tab URLs on results, so the
+          // server may skip its pre-flight tabs_list. An older build omits this and
+          // the server keeps fetching the URL itself.
+          caps: [WIRE_CAP_TAB_URL]
         };
         ws2.send(JSON.stringify(hello));
       };
@@ -494,6 +499,9 @@
       const u = cmd.params.url;
       return typeof u === "string" ? u : "";
     }
+    return observedTabUrl(cmd);
+  }
+  async function observedTabUrl(cmd) {
     try {
       const tabId = await targetTab(cmd);
       const t = await chrome.tabs.get(tabId);
@@ -1124,6 +1132,12 @@
     async dispatch(cmd) {
       try {
         const policy = this.deps.getPolicy();
+        if (!policy && cmd.method !== "ping_probe") {
+          throw new CmdError(
+            "POLICY_DENIED",
+            "no policy has arrived from the chrome-mcp server yet, so this extension is refusing every command"
+          );
+        }
         if (policy) {
           const url = isUrlGated(cmd.method) ? await urlForCommand(cmd) : "";
           const verdict = evaluatePolicy(url, cmd.method, policy);
@@ -1131,6 +1145,8 @@
         }
         const data = await this.deps.exec.run(cmd);
         const frame = { type: "result", v: PROTOCOL_VERSION, id: cmd.id, ok: true, data };
+        const tabUrl = await observedTabUrl(cmd);
+        if (tabUrl) frame.tabUrl = tabUrl;
         this.deps.send(frame);
       } catch (err) {
         const code = err instanceof CmdError ? err.code : "CDP_ERROR";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "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",
@@ -32,12 +32,20 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "mcp-server",
     "chrome",
     "chrome-extension",
     "browser-automation",
-    "cdp",
-    "playwright",
-    "claude"
+    "browser-mcp",
+    "real-browser",
+    "logged-in",
+    "session",
+    "cookies",
+    "authenticated",
+    "web-scraping",
+    "ai-agent",
+    "claude",
+    "claude-code"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",