@mehmoodqureshi/chrome-mcp 0.5.0 → 0.5.2

package/dist/shared/policy.d.ts

@@ -30,5 +30,12 @@ export type PolicyVerdict = {
  * verdict; the caller throws its own error type on `{ ok: false }`.
  */
 export declare function evaluatePolicy(url: string, method: WireMethod, policy: WirePolicy): PolicyVerdict;
+/**
+ * A plain-English, actionable message for a blocked domain. Tells the user what
+ * happened, why it's blocked (safety, not a bug), which sites ARE allowed, and
+ * the exact one-line change to permit this one — so a non-technical user is never
+ * left at a dead end. Never includes the token or any other secret.
+ */
+export declare function blockedDomainMessage(method: string, host: string, policy: WirePolicy): string;
 /** A wire policy that allows nothing — the safe default when none was delivered. */
 export declare const DENY_ALL_WIRE_POLICY: WirePolicy;

package/dist/shared/policy.js

@@ -17,6 +17,7 @@ exports.isUrlGated = isUrlGated;
 exports.hostOf = hostOf;
 exports.isDomainAllowed = isDomainAllowed;
 exports.evaluatePolicy = evaluatePolicy;
+exports.blockedDomainMessage = blockedDomainMessage;
 // ---------------------------------------------------------------------------
 // Method classification
 // ---------------------------------------------------------------------------
@@ -131,14 +132,27 @@ function evaluatePolicy(url, method, policy) {
         return { ok: true };
     if (!isDomainAllowed(url, policy)) {
         const host = hostOf(url) || url;
-        return {
-            ok: false,
-            reason: `"${method}" denied: ${host} is not in the domain allowlist. ` +
-                `Add it to allowDomains, or pass --unsafe-all-domains.`,
-        };
+        return { ok: false, reason: blockedDomainMessage(method, host, policy) };
     }
     return { ok: true };
 }
+/**
+ * A plain-English, actionable message for a blocked domain. Tells the user what
+ * happened, why it's blocked (safety, not a bug), which sites ARE allowed, and
+ * the exact one-line change to permit this one — so a non-technical user is never
+ * left at a dead end. Never includes the token or any other secret.
+ */
+function blockedDomainMessage(method, host, policy) {
+    const allowed = policy.allowDomains.filter((d) => d !== '*');
+    const allowedLine = allowed.length
+        ? `Currently allowed: ${allowed.join(', ')}.`
+        : `Right now no sites are allowed.`;
+    return (`Blocked: "${method}" can't run on ${host} because it isn't on this browser tool's allowed-sites list. ` +
+        `This is a safety limit (the tool drives your real, logged-in browser, so it only touches sites you've approved) — not an error. ` +
+        `${allowedLine} ` +
+        `To allow ${host}, add it to the chrome-mcp settings as: --allow-domain "${host}" (or "*.${host}" to include subdomains), ` +
+        `then restart/reconnect. To allow every site (less safe), use --unsafe-all-domains.`);
+}
 /** A wire policy that allows nothing — the safe default when none was delivered. */
 exports.DENY_ALL_WIRE_POLICY = {
     allowDomains: [],

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

@@ -40,6 +40,8 @@ export declare class BridgeServer {
     constructor(opts: BridgeOptions);
     /** Bind and start listening. Returns the actual port (useful with port 0). */
     start(): Promise<number>;
+    /** One bind attempt. Resolves with a listening server or rejects with the listen error. */
+    private listenOnce;
     stop(): Promise<void>;
     get port(): number;
     hasActiveExtension(): boolean;

package/dist/src/bridge/server.js

@@ -24,6 +24,20 @@ const HELLO_TIMEOUT_MS = 5_000;
 const DEFAULT_HEARTBEAT_MS = 15_000;
 /** Max pre-auth frames a socket may send before a valid hello (anti-idle-hold). */
 const MAX_PREAUTH_FRAMES = 10;
+/** How long to wait for a just-replaced instance to release a fixed port before giving up. */
+const PORT_WAIT_MS = 4_000;
+/** Pause between port-bind retries while waiting for the old listener to exit. */
+const PORT_RETRY_MS = 250;
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A friendly, actionable message for the rare case the port stays busy past PORT_WAIT_MS. */
+function portBusyMessage(host, port) {
+    return (`Couldn't start: another program is already using ${host}:${port}.\n` +
+        `This is almost always a previous chrome-mcp that didn't shut down. To fix it:\n` +
+        `  1. Fully quit/restart your MCP host (e.g. Claude Code), or\n` +
+        `  2. Stop the leftover process, then reconnect:\n` +
+        `       macOS/Linux:  lsof -nP -iTCP:${port} -sTCP:LISTEN   then  kill <PID>\n` +
+        `  3. Or run chrome-mcp with a different port:  --port <number>`);
+}
 class BridgeServer {
     opts;
     wss = null;
@@ -38,17 +52,58 @@ class BridgeServer {
     async start() {
         if (this.wss)
             return this.boundPort;
-        const wss = new ws_1.WebSocketServer({ host: this.opts.host ?? protocol_1.BRIDGE_HOST, port: this.opts.port ?? 0 });
-        wss.on('connection', (ws) => this.handleConnection(ws));
-        await new Promise((resolve, reject) => {
-            wss.once('listening', resolve);
-            wss.once('error', reject);
+        const host = this.opts.host ?? protocol_1.BRIDGE_HOST;
+        const port = this.opts.port ?? 0;
+        // A fixed port can be briefly held by a just-replaced instance of ourselves
+        // (e.g. on a host "Reconnect"). Rather than crash with a cryptic EADDRINUSE,
+        // wait-and-retry for a few seconds so the old process can release it; only if
+        // it never frees up do we surface a plain-English, actionable error.
+        const deadline = Date.now() + PORT_WAIT_MS;
+        for (let attempt = 1;; attempt++) {
+            try {
+                const wss = await this.listenOnce(host, port);
+                const addr = wss.address();
+                this.boundPort = typeof addr === 'object' && addr ? addr.port : port;
+                this.wss = wss;
+                this.log(`bridge listening on ${host}:${this.boundPort}`);
+                return this.boundPort;
+            }
+            catch (err) {
+                const inUse = err?.code === 'EADDRINUSE';
+                if (!inUse || port === 0 || Date.now() >= deadline) {
+                    if (inUse)
+                        throw new Error(portBusyMessage(host, port));
+                    throw err;
+                }
+                if (attempt === 1)
+                    this.log(`port ${host}:${port} busy — waiting for the previous instance to release it…`);
+                await delay(PORT_RETRY_MS);
+            }
+        }
+    }
+    /** One bind attempt. Resolves with a listening server or rejects with the listen error. */
+    listenOnce(host, port) {
+        return new Promise((resolve, reject) => {
+            const wss = new ws_1.WebSocketServer({ host, port });
+            const onError = (err) => {
+                wss.off('listening', onListening);
+                // Close so the failed server doesn't linger and leak a handle on retry.
+                try {
+                    wss.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            };
+            const onListening = () => {
+                wss.off('error', onError);
+                wss.on('connection', (ws) => this.handleConnection(ws));
+                resolve(wss);
+            };
+            wss.once('error', onError);
+            wss.once('listening', onListening);
         });
-        const addr = wss.address();
-        this.boundPort = typeof addr === 'object' && addr ? addr.port : (this.opts.port ?? 0);
-        this.wss = wss;
-        this.log(`bridge listening on ${this.opts.host ?? protocol_1.BRIDGE_HOST}:${this.boundPort}`);
-        return this.boundPort;
     }
     async stop() {
         this.active?.close(1001, 'server stopping');

package/dist/src/cli.js

@@ -108,16 +108,29 @@ async function main() {
         }),
     });
     (0, server_2.logErr)(`backend: extension-if-paired else ${cfg.cdpFallback ? 'CDP fallback' : 'none'} (prefer: ${cfg.prefer})`);
+    let shuttingDown = false;
     const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
         cleanup();
         exitWithDeadline(Promise.allSettled([(0, server_2.stopMcpServer)(), bridge.stop()]));
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    // The MCP host owns our stdin. When it disconnects (host quit, or a
+    // "Reconnect" that spawns a fresh child), stdin reaches EOF — that's our cue
+    // to exit and release the port, so a stale process never lingers and blocks
+    // the next connection. This is what makes reconnects "just work".
+    process.stdin.on('end', shutdown);
+    process.stdin.on('close', shutdown);
     await (0, server_2.startMcpServer)(version());
 }
 main().catch((err) => {
-    (0, server_2.logErr)(`fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+    // Port-busy and similar startup failures carry a plain-English message already;
+    // show that to the user without a noisy stack trace.
+    const friendly = err instanceof Error && /Couldn't start:/.test(err.message);
+    (0, server_2.logErr)(friendly ? err.message : `fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
     process.exit(1);
 });
 //# sourceMappingURL=cli.js.map

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

@@ -16,6 +16,9 @@ export interface SelectorDeps {
     prefer: BackendPreference;
     cdp: CdpOptions;
     pingDeadlineMs?: number;
+    /** How long a successful ping is trusted before re-probing (ms). A burst of
+     *  commands within this window skips the per-call ping round-trip. 0 disables. */
+    pingCacheMs?: number;
     /** Test seams — default to the real executors. */
     makeExtension?: (bridge: BridgeServer) => Executor;
     makeCdp?: (opts: CdpOptions) => Executor;

package/dist/src/executor/select.js

@@ -16,8 +16,10 @@ 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 pingMs = deps.pingDeadlineMs ?? 800;
+    const pingCacheMs = deps.pingCacheMs ?? 2_000;
     const ext = makeExt(deps.bridge);
     let cdp = null;
+    let lastPingOkAt = 0;
     const cdpAllowed = () => deps.cdpFallback || deps.prefer === 'cdp' || !!deps.cdp.cdpEndpoint;
     const getCdp = () => {
         if (!cdpAllowed())
@@ -28,7 +30,17 @@ function createSelector(deps) {
     const tryExt = async () => {
         if (!deps.bridge.hasActiveExtension())
             return null;
-        return (await ext.ping(pingMs)) ? ext : null;
+        // A recent successful ping proves liveness; skip re-pinging within the TTL so
+        // a burst of commands doesn't each pay the ~ping round-trip. A truly dead
+        // worker closes its socket, flipping hasActiveExtension() false above before
+        // this matters — the ping only guards the narrow open-but-frozen window.
+        if (pingCacheMs > 0 && Date.now() - lastPingOkAt < pingCacheMs)
+            return ext;
+        if (await ext.ping(pingMs)) {
+            lastPingOkAt = Date.now();
+            return ext;
+        }
+        return null;
     };
     return async () => {
         if (deps.prefer === 'cdp') {

package/extension-dist/background.js

@@ -195,13 +195,15 @@
     if (isAboutBlank(url) && NAVIGATION.has(method)) return { ok: true };
     if (!isDomainAllowed(url, policy)) {
       const host = hostOf(url) || url;
-      return {
-        ok: false,
-        reason: `"${method}" denied: ${host} is not in the domain allowlist. Add it to allowDomains, or pass --unsafe-all-domains.`
-      };
+      return { ok: false, reason: blockedDomainMessage(method, host, policy) };
     }
     return { ok: true };
   }
+  function blockedDomainMessage(method, host, policy) {
+    const allowed = policy.allowDomains.filter((d) => d !== "*");
+    const allowedLine = allowed.length ? `Currently allowed: ${allowed.join(", ")}.` : `Right now no sites are allowed.`;
+    return `Blocked: "${method}" can't run on ${host} because it isn't on this browser tool's allowed-sites list. This is a safety limit (the tool drives your real, logged-in browser, so it only touches sites you've approved) \u2014 not an error. ${allowedLine} To allow ${host}, add it to the chrome-mcp settings as: --allow-domain "${host}" (or "*.${host}" to include subdomains), then restart/reconnect. To allow every site (less safe), use --unsafe-all-domains.`;
+  }
 
   // shared/download.ts
   var MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
@@ -490,13 +492,20 @@
     return resolveSelector(cmd);
   }
   async function waitForSelector(tabId, selector, timeoutMs = 5e3) {
-    const start = Date.now();
-    for (; ; ) {
-      const present = await execInTab(tabId, (s) => !!document.querySelector(s), [selector]);
-      if (present) return true;
-      if (Date.now() - start > timeoutMs) return false;
-      await delay(120);
-    }
+    const found = await execInTab(
+      tabId,
+      (s, timeout, interval) => new Promise((resolve) => {
+        const deadline = Date.now() + timeout;
+        const tick = () => {
+          if (document.querySelector(s)) return resolve(true);
+          if (Date.now() > deadline) return resolve(false);
+          setTimeout(tick, interval);
+        };
+        tick();
+      }),
+      [selector, timeoutMs, 120]
+    );
+    return found === true;
   }
   async function withDebugger(tabId, fn) {
     return locks.run(`dbg:${tabId}`, async () => {
@@ -986,26 +995,33 @@
           return result ?? { ok: false, error: "no result" };
         }
         // -- wait_for (poll the isolated world) --
+        // One injection that polls IN-PAGE until the condition holds or the deadline
+        // passes, rather than one executeScript round-trip per tick.
         case "wait_for": {
           const id = await targetTab(cmd);
           const timeout = typeof cmd.params.timeoutMs === "number" ? cmd.params.timeoutMs : 3e4;
           const start = Date.now();
-          for (; ; ) {
-            const matched = await execInTab(
-              id,
-              (sel, text, gone) => {
+          const matched = await execInTab(
+            id,
+            (sel, text, gone, timeoutMs, interval) => new Promise((resolve) => {
+              const deadline = Date.now() + timeoutMs;
+              const hit = () => {
                 let present;
                 if (sel) present = !!document.querySelector(sel);
                 else if (text) present = (document.body?.innerText ?? "").includes(text);
                 else present = true;
                 return gone ? !present : present;
-              },
-              [cmd.params.selector ?? null, cmd.params.textContains ?? null, cmd.params.gone === true]
-            );
-            if (matched) return { matched: true, waitedMs: Date.now() - start };
-            if (Date.now() - start > timeout) return { matched: false, waitedMs: Date.now() - start };
-            await delay(150);
-          }
+              };
+              const tick = () => {
+                if (hit()) return resolve(true);
+                if (Date.now() > deadline) return resolve(false);
+                setTimeout(tick, interval);
+              };
+              tick();
+            }),
+            [cmd.params.selector ?? null, cmd.params.textContains ?? null, cmd.params.gone === true, timeout, 150]
+          );
+          return { matched: matched === true, waitedMs: Date.now() - start };
         }
         // -- download (user's Downloads dir) --
         case "download_file": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Drive a real Chrome browser over MCP. A stdio MCP server (CLI) plus an MV3 extension, behind one pluggable Executor (extension via chrome.scripting, or a Playwright CDP fallback).",
   "author": "Mehmood Ur Rehman Qureshi",
   "license": "MIT",