@mehmoodqureshi/chrome-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmood Ur Rehman Qureshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# chrome-mcp
+
+Drive a **real Chrome browser** from Claude (or any MCP host). One pluggable
+`Executor` interface, two backends:
+
+- **Extension (primary):** 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.
+- **CDP fallback:** when no extension is paired, the CLI launches/attaches a
+  Playwright-driven Chromium for scripted/headless use.
+
+Distributed as an `npx` CLI (the MCP server) plus a load-unpacked extension.
+
+> **Full design:** [`docs/BLUEPRINT.md`](docs/BLUEPRINT.md) — architecture, wire
+> protocol, the complete tool surface, the extension manifest, the security
+> model, and the phased build plan.
+
+## Quickstart
+
+**1. Register the MCP server** with your host (e.g. Claude Desktop / Code):
+
+```jsonc
+{
+  "mcpServers": {
+    "chrome-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mehmoodqureshi/chrome-mcp", "--allow-domain", "example.com", "--enable-mutations"]
+    }
+  }
+}
+```
+
+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`, `--unsafe-enable-eval`, or `--unsafe-all-domains`.
+
+**2. Load the extension** (to drive your *real* Chrome): build it, then
+`chrome://extensions` → enable Developer mode → **Load unpacked** → select
+`extension-dist/`.
+
+**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`. (Without the extension, the CLI
+falls back to a Playwright-driven Chromium automatically.)
+
+The 26 tools cover tabs, navigation, interaction (`click`/`type`/`press`/`hover`/
+`scroll`), reads (`get_text`/`get_html`/`screenshot`/`eval`/`wait_for`), helpers
+(`extract_links`/`read_as_markdown`/`fill_form`/`download_file`), and `chrome_status`.
+
+## Status
+
+v0.1.0 — all six build phases complete and green (50 automated tests + a gated
+headed extension smoke). End-to-end working: `npx chrome-mcp` ⇄ bridge ⇄
+extension ⇄ your real Chrome, with a Playwright CDP fallback.
+
+- [x] **Phase 0 — Contracts & skeleton:** `shared/protocol.ts` (wire contract),
+      `src/executor/types.ts` (Executor interface), `src/security/policy.ts`
+      (default-deny policy + capability gates), `src/config.ts` (CLI/env/policy
+      resolution), build + test harness.
+- [x] **Phase 1 — MCP server + StubExecutor:** `mcp/server.ts` (clean-stdout
+      stdio), `mcp/tools.ts` (23-tool catalog + never-throw dispatch +
+      drift-check), validators/envelopes/helpers, `ExecutorManager` +
+      `StubExecutor`, `cli.ts`. Point an MCP host at `node dist/src/cli.js` today.
+- [x] **Phase 2 — WebSocket bridge + auth:** `bridge/server.ts` (loopback WS,
+      hello-token gate, welcome/unauthorized, displacement), `bridge/auth.ts`
+      (per-boot 256-bit token, atomic-0600 handshake, SHA-256 `timingSafeEqual`),
+      `bridge/connection.ts` (id-correlation, method-aware timeouts, backpressure,
+      reject-all-on-close, heartbeat).
+- [x] **Phase 3 — ExtensionExecutor + CdpExecutor + selection:**
+      `executor/extension-executor.ts` (Executor over the bridge),
+      `executor/cdp-executor.ts` (Playwright connect/launch + lock recovery +
+      tab resolution), `executor/select.ts` (extension-if-ping-responsive else
+      CDP). CLI now starts the bridge, writes the 0600 handshake, and serves a
+      real backend. Adds `playwright`.
+- [x] **Phase 4 — MV3 extension:** `extension/` — `manifest.json`,
+      `sw/ws-client.ts` (dial + hello/welcome + pong), `sw/executor.ts`
+      (chrome.scripting/chrome.tabs command impls), `sw/router.ts` (never-throw +
+      drift), `sw/background.ts` (top-level listeners + 25s keepalive/reconnect),
+      options page (manual pairing), esbuild build → `extension-dist/`. Verified
+      by a live `--load-extension` smoke (pair → navigate → get_text). Adds
+      `esbuild` + `@types/chrome`.
+- [x] **Phase 5 — Helpers, downloads, HITL:** hardened `download_file`
+      (`shared/download.ts` — path-traversal/dangerous-ext sanitize + size cap,
+      wired into both backends), richer `read_as_markdown`, and a human-in-the-loop
+      harness (`hitl/` — `npm run test:hitl [-- --include-mutating]`) with pure,
+      unit-tested gating. 50 automated tests.
+- [x] **Phase 6 — Packaging & docs:** `files` whitelist (ships `dist/src`,
+      `dist/shared`, `extension-dist`, LICENSE, blueprint — not source/tests),
+      `prepack` build, `bin`, quickstart + `.mcp.json` snippet. Verified by a
+      tarball install smoke (`npm pack` → install → MCP `tools/list`).
+
+## Security posture (default)
+
+**Deny-all safe mode.** With no policy configured: empty domain allowlist,
+`eval` off, downloads off, mutating tools off. Opt in explicitly:
+
+```
+chrome-mcp --allow-domain example.com --enable-mutations
+chrome-mcp --policy ./policy.json          # see policy.example.json
+chrome-mcp --unsafe-all-domains            # loud footgun
+```
+
+The per-boot 256-bit token in `~/.chrome-mcp/handshake.json` (mode 0600) is the
+only trust boundary; it is never written to stdout/stderr.
+
+## Develop
+
+```
+npm install
+npm run typecheck       # server/test sources
+npm run typecheck:ext   # extension sources (@types/chrome)
+npm run build:ext       # bundle the extension → extension-dist/
+npm test                # builds, then runs node --test on dist/test
+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).
+
+> **v1 uses `chrome.scripting`/`chrome.tabs`, not `chrome.debugger`.** No
+> "is being debugged" banner, CSP-safe reads (isolated world), and it's testable
+> under Playwright. Trade-off: clicks/typing are synthetic DOM events, not
+> OS-level trusted input, and `screenshot` is visible-tab only. A trusted-input
+> `chrome.debugger` backend is a documented future upgrade (BLUEPRINT §10).

package/dist/shared/download.d.ts

@@ -0,0 +1,15 @@
+/**
+ * shared/download.ts — download-name hardening, shared by the server (CDP
+ * fallback) and the extension so both sanitize identically.
+ *
+ * An LLM driven by injected page content could be steered to `download_file` a
+ * malicious payload to a predictable name, so we: strip path separators and
+ * traversal, drop control/illegal characters, refuse leading dots, neutralize
+ * dangerous executable extensions (→ `.download`), and cap the length.
+ */
+export declare const MAX_DOWNLOAD_BYTES: number;
+/** Extensions we never let land with their original suffix. */
+export declare const DANGEROUS_EXTENSIONS: ReadonlySet<string>;
+export declare function sanitizeDownloadName(name?: string): string;
+/** True when `bytes` is within the cap. */
+export declare function isWithinSizeCap(bytes: number): boolean;

package/dist/shared/protocol.d.ts

@@ -0,0 +1,114 @@
+/**
+ * shared/protocol.ts — THE SINGLE SOURCE OF TRUTH for the wire contract.
+ *
+ * Imported VERBATIM by both the server build (`src/`) and the extension build
+ * (`extension/`). Nothing about the bridge wire format, the default port, or the
+ * protocol version may be redeclared anywhere else — if it is, the two ends can
+ * silently drift. (Phase 0 verification asserts there is exactly one copy.)
+ *
+ * The server is the WebSocket SERVER; the extension is the single privileged
+ * CLIENT that dials in. Methods on the wire mirror the MCP primitives 1:1.
+ * Helpers (extract_links / read_as_markdown / fill_form) are NOT on the wire —
+ * they are composed server-side from these primitives. Only `download_file` is a
+ * wire method beyond the primitives.
+ */
+/** Bumped on any breaking change to the frames below. */
+export declare const PROTOCOL_VERSION: 1;
+export type ProtocolVersion = typeof PROTOCOL_VERSION;
+/**
+ * Default loopback port the bridge binds and the extension dials. NOT a security
+ * boundary (the token is) — a fixed port is only a convenience; the canonical
+ * port travels with the token in `handshake.json`, and ephemeral port `0` is
+ * supported because the extension re-reads the handshake on every failed dial.
+ */
+export declare const DEFAULT_WS_PORT: 38017;
+/** Loopback host. Never bind 0.0.0.0. */
+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;
+/**
+ * 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
+ * responsiveness check used to detect a dead-but-not-yet-reconnected worker).
+ */
+export type WireMethod = 'tabs_list' | 'tab_select' | 'tab_new' | 'tab_close' | 'navigate' | 'back' | 'forward' | 'reload' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'screenshot' | 'get_text' | 'get_html' | 'eval' | 'wait_for' | 'download_file' | 'ping_probe';
+/** Runtime list of every WireMethod, for boot-time drift assertions on both ends. */
+export declare const WIRE_METHODS: readonly WireMethod[];
+export type ExecutorErrorCode = 'NO_TARGET' | 'TARGET_GONE' | 'DETACHED' | 'DEVTOOLS_OPEN' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_THREW' | 'TIMEOUT' | 'BAD_ARGS' | 'CDP_ERROR' | 'POLICY_DENIED' | 'DOWNLOAD_FAILED' | 'UNKNOWN_METHOD';
+export interface BaseFrame {
+    type: string;
+    v: ProtocolVersion;
+}
+export interface HelloFrame extends BaseFrame {
+    type: 'hello';
+    token: string;
+    ext: {
+        id: string;
+        version: string;
+        chrome: string;
+    };
+}
+export interface WelcomeFrame extends BaseFrame {
+    type: 'welcome';
+    serverVersion: string;
+    sessionId: string;
+    heartbeatMs: number;
+}
+export interface UnauthFrame extends BaseFrame {
+    type: 'unauthorized';
+    reason: 'bad_token' | 'bad_version' | 'timeout';
+}
+export interface CommandFrame extends BaseFrame {
+    type: 'command';
+    id: string;
+    method: WireMethod;
+    params: Record<string, unknown>;
+    tabId?: string;
+    timeoutMs: number;
+}
+export interface ResultFrame extends BaseFrame {
+    type: 'result';
+    id: string;
+    ok: true;
+    /** For `screenshot`: { dataBase64, mimeType, width, height, truncated }. */
+    data: unknown;
+}
+export interface ErrorFrame extends BaseFrame {
+    type: 'error';
+    id: string;
+    ok: false;
+    error: {
+        code: ExecutorErrorCode;
+        message: string;
+        data?: Record<string, unknown>;
+    };
+}
+export type WireEvent = 'tab_created' | 'tab_removed' | 'tab_updated' | 'detached' | 'target_gone';
+export interface EventFrame extends BaseFrame {
+    type: 'event';
+    event: WireEvent;
+    data: Record<string, unknown>;
+}
+export interface PingFrame extends BaseFrame {
+    type: 'ping';
+    ts: number;
+}
+export interface PongFrame extends BaseFrame {
+    type: 'pong';
+    ts: number;
+}
+/** Frames the SERVER sends to the extension. */
+export type ServerFrame = CommandFrame | WelcomeFrame | UnauthFrame | PingFrame;
+/** Frames the EXTENSION sends to the server. */
+export type ExtensionFrame = HelloFrame | ResultFrame | ErrorFrame | EventFrame | PongFrame;
+export type Frame = ServerFrame | ExtensionFrame;
+/** Shape of `$CHROME_MCP_DATA/handshake.json`. The token is a secret. */
+export interface HandshakeFile {
+    v: ProtocolVersion;
+    port: number;
+    token: string;
+    pid: number;
+    ts: number;
+    expectedExtensionId?: string;
+}

package/dist/shared/protocol.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * shared/protocol.ts — THE SINGLE SOURCE OF TRUTH for the wire contract.
+ *
+ * Imported VERBATIM by both the server build (`src/`) and the extension build
+ * (`extension/`). Nothing about the bridge wire format, the default port, or the
+ * protocol version may be redeclared anywhere else — if it is, the two ends can
+ * silently drift. (Phase 0 verification asserts there is exactly one copy.)
+ *
+ * The server is the WebSocket SERVER; the extension is the single privileged
+ * CLIENT that dials in. Methods on the wire mirror the MCP primitives 1:1.
+ * Helpers (extract_links / read_as_markdown / fill_form) are NOT on the wire —
+ * they are composed server-side from these primitives. Only `download_file` is a
+ * 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;
+/** Bumped on any breaking change to the frames below. */
+exports.PROTOCOL_VERSION = 1;
+/**
+ * Default loopback port the bridge binds and the extension dials. NOT a security
+ * boundary (the token is) — a fixed port is only a convenience; the canonical
+ * port travels with the token in `handshake.json`, and ephemeral port `0` is
+ * supported because the extension re-reads the handshake on every failed dial.
+ */
+exports.DEFAULT_WS_PORT = 38017;
+/** Loopback host. Never bind 0.0.0.0. */
+exports.BRIDGE_HOST = '127.0.0.1';
+/** WebSocket close codes we use deliberately. */
+exports.CLOSE_UNAUTHORIZED = 4401;
+exports.CLOSE_SUPERSEDED = 4000;
+/** Runtime list of every WireMethod, for boot-time drift assertions on both ends. */
+exports.WIRE_METHODS = [
+    'tabs_list',
+    'tab_select',
+    'tab_new',
+    'tab_close',
+    'navigate',
+    'back',
+    'forward',
+    'reload',
+    'click',
+    'type',
+    'press',
+    'hover',
+    'scroll',
+    'screenshot',
+    'get_text',
+    'get_html',
+    'eval',
+    'wait_for',
+    'download_file',
+    'ping_probe',
+];
+//# sourceMappingURL=protocol.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * src/bridge/auth.ts — the ONE auth model (every other variant in the design
+ * drafts was deleted on purpose).
+ *
+ *   - Fresh 256-bit token EVERY boot, never persisted across restarts.
+ *   - Written atomically (tmp + rename) to `handshake.json` at mode 0600; the
+ *     mode is re-verified after write and we FAIL CLOSED if it can't be set.
+ *   - Compared by hashing both sides to SHA-256 and `timingSafeEqual`-ing the
+ *     digests — no length precondition, no length leak.
+ *   - The token is NEVER written to stdout/stderr or any log (a test asserts it).
+ */
+import { type HandshakeFile } from '../../shared/protocol';
+/** A fresh 256-bit token, base64url. Generated once per server boot. */
+export declare function generateToken(): string;
+/** Constant-time token compare via fixed-length SHA-256 digests. */
+export declare function tokensMatch(a: string, b: string): boolean;
+export interface WriteHandshakeFields {
+    port: number;
+    token: string;
+    expectedExtensionId?: string;
+}
+/**
+ * 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
+ * trust boundary, so a loose permission is a hard error, not a warning.
+ */
+export declare function writeHandshake(dir: string, fields: WriteHandshakeFields): string;
+export declare function readHandshake(dir: string): HandshakeFile;
+/** Best-effort removal (kill switch / clean shutdown). */
+export declare function removeHandshake(dir: string): void;
+/** Redact a token for any human-facing string (defense against accidental logs). */
+export declare function redactToken(s: string, token: string): string;

package/dist/src/bridge/auth.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * src/bridge/auth.ts — the ONE auth model (every other variant in the design
+ * drafts was deleted on purpose).
+ *
+ *   - Fresh 256-bit token EVERY boot, never persisted across restarts.
+ *   - Written atomically (tmp + rename) to `handshake.json` at mode 0600; the
+ *     mode is re-verified after write and we FAIL CLOSED if it can't be set.
+ *   - Compared by hashing both sides to SHA-256 and `timingSafeEqual`-ing the
+ *     digests — no length precondition, no length leak.
+ *   - The token is NEVER written to stdout/stderr or any log (a test asserts it).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateToken = generateToken;
+exports.tokensMatch = tokensMatch;
+exports.writeHandshake = writeHandshake;
+exports.readHandshake = readHandshake;
+exports.removeHandshake = removeHandshake;
+exports.redactToken = redactToken;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const protocol_1 = require("../../shared/protocol");
+const datadir_1 = require("./datadir");
+/** A fresh 256-bit token, base64url. Generated once per server boot. */
+function generateToken() {
+    return (0, node_crypto_1.randomBytes)(32).toString('base64url');
+}
+/** Constant-time token compare via fixed-length SHA-256 digests. */
+function tokensMatch(a, b) {
+    const ha = (0, node_crypto_1.createHash)('sha256').update(a, 'utf8').digest();
+    const hb = (0, node_crypto_1.createHash)('sha256').update(b, 'utf8').digest();
+    return (0, node_crypto_1.timingSafeEqual)(ha, hb);
+}
+/**
+ * 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
+ * trust boundary, so a loose permission is a hard error, not a warning.
+ */
+function writeHandshake(dir, fields) {
+    const path = (0, datadir_1.handshakePath)(dir);
+    const tmp = `${path}.tmp.${process.pid}`;
+    const payload = {
+        v: protocol_1.PROTOCOL_VERSION,
+        port: fields.port,
+        token: fields.token,
+        pid: process.pid,
+        ts: Date.now(),
+        expectedExtensionId: fields.expectedExtensionId,
+    };
+    (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);
+    const mode = (0, node_fs_1.statSync)(path).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new Error(`handshake file ${path} is group/other-accessible (mode ${mode.toString(8)}); refusing to expose the token`);
+    }
+    return path;
+}
+function readHandshake(dir) {
+    return JSON.parse((0, node_fs_1.readFileSync)((0, datadir_1.handshakePath)(dir), 'utf8'));
+}
+/** Best-effort removal (kill switch / clean shutdown). */
+function removeHandshake(dir) {
+    try {
+        (0, node_fs_1.unlinkSync)((0, datadir_1.handshakePath)(dir));
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Redact a token for any human-facing string (defense against accidental logs). */
+function redactToken(s, token) {
+    return token ? s.split(token).join('«redacted»') : s;
+}
+//# sourceMappingURL=auth.js.map

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

@@ -0,0 +1,48 @@
+/**
+ * src/bridge/connection.ts — one authenticated extension connection.
+ *
+ * Owns the pending-request table: each `sendCommand` mints an id, sends a
+ * CommandFrame, and parks a {resolve,reject,timer} until the matching
+ * result/error frame arrives. Guarantees:
+ *   - method-aware per-request timeout that rejects the ONE call (never closes
+ *     the socket),
+ *   - reject-ALL-pending with EXTENSION_DISCONNECTED on close,
+ *   - backpressure rejection (screenshots are large; never queue unboundedly),
+ *   - app-level ping/pong heartbeat (optional; disabled when heartbeatMs<=0).
+ */
+import type { WebSocket } from 'ws';
+import { type WireEvent, type WireMethod } from '../../shared/protocol';
+export interface ConnectionDeps {
+    ws: WebSocket;
+    extId: string;
+    sessionId: string;
+    heartbeatMs: number;
+    onEvent?: (event: WireEvent, data: Record<string, unknown>) => void;
+    onClose?: (code: number) => void;
+    onLog?: (message: string) => void;
+}
+export declare class ExtensionConnection {
+    readonly extId: string;
+    readonly sessionId: string;
+    private readonly ws;
+    private readonly pending;
+    private seq;
+    private closed;
+    private heartbeat;
+    private missedPongs;
+    private readonly onEvent?;
+    private readonly onClose?;
+    private readonly onLog?;
+    constructor(deps: ConnectionDeps);
+    /** Send a command and await its result (or reject on error/timeout/disconnect). */
+    sendCommand(method: WireMethod, params: Record<string, unknown>, opts?: {
+        tabId?: string;
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    close(code: number, reason?: string): void;
+    isOpen(): boolean;
+    private handleMessage;
+    private settle;
+    private handleClose;
+    private startHeartbeat;
+}