@mehmoodqureshi/chrome-mcp 0.1.0

package/dist/src/bridge/connection.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtensionConnection = void 0;
+const protocol_1 = require("../../shared/protocol");
+const types_1 = require("../executor/types");
+const MAX_BUFFERED_BYTES = 8 * 1024 * 1024;
+const LONG_METHODS = new Set(['screenshot', 'wait_for', 'navigate', 'download_file']);
+function defaultTimeoutFor(method) {
+    return LONG_METHODS.has(method) ? 60_000 : 30_000;
+}
+/** Map a wire error code onto a local ExecutorError code (the wire enum is a
+ *  near-superset; unknown codes degrade to CDP_ERROR while keeping the message). */
+function mapWireErrorCode(code) {
+    const known = {
+        TIMEOUT: 'TIMEOUT',
+        POLICY_DENIED: 'POLICY_DENIED',
+        DETACHED: 'DETACHED',
+        DEVTOOLS_OPEN: 'DEVTOOLS_OPEN',
+        TARGET_GONE: 'TARGET_GONE',
+        SELECTOR_NOT_FOUND: 'SELECTOR_NOT_FOUND',
+        REF_EXPIRED: 'REF_EXPIRED',
+        DOWNLOAD_FAILED: 'DOWNLOAD_FAILED',
+        EVAL_THREW: 'EVAL_FAILED',
+    };
+    return known[code] ?? 'TARGET_GONE';
+}
+class ExtensionConnection {
+    extId;
+    sessionId;
+    ws;
+    pending = new Map();
+    seq = 0;
+    closed = false;
+    heartbeat = null;
+    missedPongs = 0;
+    onEvent;
+    onClose;
+    onLog;
+    constructor(deps) {
+        this.ws = deps.ws;
+        this.extId = deps.extId;
+        this.sessionId = deps.sessionId;
+        this.onEvent = deps.onEvent;
+        this.onClose = deps.onClose;
+        this.onLog = deps.onLog;
+        this.ws.on('message', (raw) => this.handleMessage(raw));
+        this.ws.on('close', (code) => this.handleClose(code));
+        this.ws.on('error', () => this.handleClose(1006));
+        if (deps.heartbeatMs > 0)
+            this.startHeartbeat(deps.heartbeatMs);
+    }
+    /** Send a command and await its result (or reject on error/timeout/disconnect). */
+    sendCommand(method, params, opts) {
+        if (this.closed || this.ws.readyState !== this.ws.OPEN) {
+            return Promise.reject(new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'extension is not connected'));
+        }
+        if (this.ws.bufferedAmount > MAX_BUFFERED_BYTES) {
+            return Promise.reject(new types_1.ExecutorError('BACKPRESSURE', 'bridge send buffer is full; try again'));
+        }
+        const id = String(++this.seq);
+        const timeoutMs = opts?.timeoutMs ?? defaultTimeoutFor(method);
+        const frame = {
+            type: 'command',
+            v: protocol_1.PROTOCOL_VERSION,
+            id,
+            method,
+            params,
+            tabId: opts?.tabId,
+            timeoutMs,
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new types_1.ExecutorError('TIMEOUT', `"${method}" timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, timer, method });
+            try {
+                this.ws.send(JSON.stringify(frame));
+            }
+            catch (err) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(new types_1.ExecutorError('EXTENSION_DISCONNECTED', `send failed: ${String(err)}`));
+            }
+        });
+    }
+    close(code, reason) {
+        if (this.closed)
+            return;
+        try {
+            this.ws.close(code, reason);
+        }
+        catch {
+            /* ignore */
+        }
+        this.handleClose(code);
+    }
+    isOpen() {
+        return !this.closed && this.ws.readyState === this.ws.OPEN;
+    }
+    // -- internals ----------------------------------------------------------
+    handleMessage(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw.toString());
+        }
+        catch {
+            this.onLog?.('dropped a non-JSON frame from the extension');
+            return;
+        }
+        switch (frame.type) {
+            case 'result':
+                this.settle(frame.id, frame);
+                break;
+            case 'error':
+                this.settle(frame.id, frame);
+                break;
+            case 'event': {
+                const ev = frame;
+                this.onEvent?.(ev.event, ev.data);
+                break;
+            }
+            case 'pong':
+                this.missedPongs = 0;
+                break;
+            default:
+                // hello arrives only pre-auth (handled by the server); ignore here.
+                break;
+        }
+    }
+    settle(id, frame) {
+        const p = this.pending.get(id);
+        if (!p)
+            return; // already timed out / unknown id
+        clearTimeout(p.timer);
+        this.pending.delete(id);
+        if (frame.type === 'result') {
+            p.resolve(frame.data);
+        }
+        else {
+            p.reject(new types_1.ExecutorError(mapWireErrorCode(frame.error.code), frame.error.message));
+        }
+    }
+    handleClose(code) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        const pendings = [...this.pending.values()];
+        this.pending.clear();
+        for (const p of pendings) {
+            clearTimeout(p.timer);
+            p.reject(new types_1.ExecutorError('EXTENSION_DISCONNECTED', `connection closed (code ${code})`));
+        }
+        this.onClose?.(code);
+    }
+    startHeartbeat(ms) {
+        this.heartbeat = setInterval(() => {
+            if (this.closed)
+                return;
+            if (this.missedPongs >= 2) {
+                this.onLog?.('extension missed 2 heartbeats; terminating connection');
+                this.close(1001, 'heartbeat lost');
+                return;
+            }
+            this.missedPongs++;
+            try {
+                this.ws.send(JSON.stringify({ type: 'ping', v: protocol_1.PROTOCOL_VERSION, ts: Date.now() }));
+            }
+            catch {
+                this.close(1006, 'heartbeat send failed');
+            }
+        }, ms);
+        this.heartbeat.unref?.();
+    }
+}
+exports.ExtensionConnection = ExtensionConnection;
+//# sourceMappingURL=connection.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * src/bridge/datadir.ts — the Electron-free data dir (the LinkedIn repo resolved
+ * this via `app.getPath`; we use `$CHROME_MCP_DATA` || `~/.chrome-mcp`). Holds
+ * the 0600 handshake and, later, the CDP-fallback profile.
+ */
+/** Create (if needed) and return the data dir, 0700 so only the user can read it. */
+export declare function ensureDataDir(dir?: string): string;
+export declare function handshakePath(dir: string): string;

package/dist/src/bridge/datadir.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * src/bridge/datadir.ts — the Electron-free data dir (the LinkedIn repo resolved
+ * this via `app.getPath`; we use `$CHROME_MCP_DATA` || `~/.chrome-mcp`). Holds
+ * the 0600 handshake and, later, the CDP-fallback profile.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureDataDir = ensureDataDir;
+exports.handshakePath = handshakePath;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("../config");
+/** Create (if needed) and return the data dir, 0700 so only the user can read it. */
+function ensureDataDir(dir) {
+    const d = dir ?? (0, config_1.resolveDataDir)();
+    (0, node_fs_1.mkdirSync)(d, { recursive: true, mode: 0o700 });
+    return d;
+}
+function handshakePath(dir) {
+    return (0, node_path_1.join)(dir, 'handshake.json');
+}
+//# sourceMappingURL=datadir.js.map

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

@@ -0,0 +1,58 @@
+/**
+ * src/bridge/server.ts — the localhost WebSocket bridge.
+ *
+ * The server is the WS SERVER; the extension dials in as the single privileged
+ * CLIENT. The token is the ONLY trust boundary (the loopback bind is merely
+ * defense-in-depth; Origin is NOT a gate). Flow:
+ *   1. Accept any loopback upgrade.
+ *   2. Require a valid `hello` (matching version + token) within HELLO_TIMEOUT;
+ *      otherwise send `unauthorized` and close 4401.
+ *   3. On success, send `welcome`, promote to the single ACTIVE connection
+ *      (superseding any prior one — a security-relevant displacement event).
+ */
+import { type WireEvent, type WireMethod } from '../../shared/protocol';
+export interface DisplacementInfo {
+    oldExtId: string;
+    newExtId: string;
+    /** True when a DIFFERENT extension id supplanted the active one (suspicious). */
+    differentId: boolean;
+}
+export interface BridgeOptions {
+    token: string;
+    serverVersion: string;
+    port?: number;
+    host?: string;
+    heartbeatMs?: number;
+    /** Diagnostics — MUST never receive the token (a test asserts this). */
+    onLog?: (message: string) => void;
+    onDisplacement?: (info: DisplacementInfo) => void;
+    onEvent?: (event: WireEvent, data: Record<string, unknown>) => void;
+}
+export declare class BridgeServer {
+    private readonly opts;
+    private wss;
+    private active;
+    private boundPort;
+    private readonly heartbeatMs;
+    constructor(opts: BridgeOptions);
+    /** Bind and start listening. Returns the actual port (useful with port 0). */
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    get port(): number;
+    hasActiveExtension(): boolean;
+    /** Send a command to the active extension, or reject if none is connected. */
+    sendCommand(method: WireMethod, params: Record<string, unknown>, opts?: {
+        tabId?: string;
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    status(): {
+        extensionConnected: boolean;
+        port: number;
+        sessionId: string | null;
+    };
+    private handleConnection;
+    private reject;
+    private promote;
+    private send;
+    private log;
+}

package/dist/src/bridge/server.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * src/bridge/server.ts — the localhost WebSocket bridge.
+ *
+ * The server is the WS SERVER; the extension dials in as the single privileged
+ * CLIENT. The token is the ONLY trust boundary (the loopback bind is merely
+ * defense-in-depth; Origin is NOT a gate). Flow:
+ *   1. Accept any loopback upgrade.
+ *   2. Require a valid `hello` (matching version + token) within HELLO_TIMEOUT;
+ *      otherwise send `unauthorized` and close 4401.
+ *   3. On success, send `welcome`, promote to the single ACTIVE connection
+ *      (superseding any prior one — a security-relevant displacement event).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BridgeServer = void 0;
+const ws_1 = require("ws");
+const node_crypto_1 = require("node:crypto");
+const protocol_1 = require("../../shared/protocol");
+const types_1 = require("../executor/types");
+const connection_1 = require("./connection");
+const auth_1 = require("./auth");
+const HELLO_TIMEOUT_MS = 5_000;
+const DEFAULT_HEARTBEAT_MS = 15_000;
+class BridgeServer {
+    opts;
+    wss = null;
+    active = null;
+    boundPort = 0;
+    heartbeatMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+    }
+    /** Bind and start listening. Returns the actual port (useful with port 0). */
+    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 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');
+        this.active = null;
+        const wss = this.wss;
+        this.wss = null;
+        if (wss)
+            await new Promise((resolve) => wss.close(() => resolve()));
+    }
+    get port() {
+        return this.boundPort;
+    }
+    hasActiveExtension() {
+        return this.active?.isOpen() ?? false;
+    }
+    /** Send a command to the active extension, or reject if none is connected. */
+    async sendCommand(method, params, opts) {
+        if (!this.active || !this.active.isOpen()) {
+            throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'no extension is paired');
+        }
+        return this.active.sendCommand(method, params, opts);
+    }
+    status() {
+        return {
+            extensionConnected: this.hasActiveExtension(),
+            port: this.boundPort,
+            sessionId: this.active?.sessionId ?? null,
+        };
+    }
+    // -- internals ----------------------------------------------------------
+    handleConnection(ws) {
+        let authed = false;
+        const helloTimer = setTimeout(() => {
+            if (authed)
+                return;
+            this.reject(ws, 'timeout');
+        }, HELLO_TIMEOUT_MS);
+        helloTimer.unref?.();
+        const onMessage = (raw) => {
+            if (authed)
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(raw.toString());
+            }
+            catch {
+                clearTimeout(helloTimer);
+                this.reject(ws, 'bad_token');
+                return;
+            }
+            if (frame.type !== 'hello')
+                return; // ignore noise until a hello arrives
+            if (frame.v !== protocol_1.PROTOCOL_VERSION) {
+                clearTimeout(helloTimer);
+                this.reject(ws, 'bad_version');
+                return;
+            }
+            if (typeof frame.token !== 'string' || !(0, auth_1.tokensMatch)(frame.token, this.opts.token)) {
+                clearTimeout(helloTimer);
+                this.reject(ws, 'bad_token');
+                return;
+            }
+            // Authenticated. Hand the socket to an ExtensionConnection.
+            authed = true;
+            clearTimeout(helloTimer);
+            ws.off('message', onMessage);
+            this.promote(ws, frame.ext ?? { id: 'unknown', version: '0', chrome: '0' });
+        };
+        ws.on('message', onMessage);
+        ws.on('error', () => {
+            /* pre-auth socket errors are non-fatal; the close will clean up */
+        });
+    }
+    reject(ws, reason) {
+        this.send(ws, { type: 'unauthorized', v: protocol_1.PROTOCOL_VERSION, reason });
+        this.log(`rejected a connection: ${reason}`);
+        try {
+            ws.close(protocol_1.CLOSE_UNAUTHORIZED, reason);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    promote(ws, ext) {
+        const sessionId = (0, node_crypto_1.randomUUID)();
+        if (this.active && this.active.isOpen()) {
+            const prev = this.active;
+            const differentId = prev.extId !== ext.id;
+            this.log(`extension "${ext.id}" superseded active connection "${prev.extId}"` +
+                (differentId ? ' (DIFFERENT id — possible hijack; surfaced to status)' : ''));
+            this.opts.onDisplacement?.({ oldExtId: prev.extId, newExtId: ext.id, differentId });
+            prev.close(protocol_1.CLOSE_SUPERSEDED, 'superseded');
+        }
+        const conn = new connection_1.ExtensionConnection({
+            ws,
+            extId: ext.id,
+            sessionId,
+            heartbeatMs: this.heartbeatMs,
+            onEvent: this.opts.onEvent,
+            onLog: (m) => this.log(m),
+            onClose: () => {
+                if (this.active?.sessionId === sessionId)
+                    this.active = null;
+            },
+        });
+        this.active = conn;
+        const welcome = {
+            type: 'welcome',
+            v: protocol_1.PROTOCOL_VERSION,
+            serverVersion: this.opts.serverVersion,
+            sessionId,
+            heartbeatMs: this.heartbeatMs,
+        };
+        this.send(ws, welcome);
+        this.log(`extension paired (session ${sessionId}, id "${ext.id}")`);
+    }
+    send(ws, frame) {
+        try {
+            ws.send(JSON.stringify(frame));
+        }
+        catch {
+            /* socket already gone */
+        }
+    }
+    log(message) {
+        this.opts.onLog?.(message);
+    }
+}
+exports.BridgeServer = BridgeServer;
+//# sourceMappingURL=server.js.map

package/dist/src/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * src/cli.ts — `npx chrome-mcp` entrypoint.
+ *
+ * Boot order: resolve config → ensure data dir → generate a per-boot token →
+ * start the loopback bridge → write the 0600 handshake → configure the manager
+ * with the backend selector → serve MCP over stdio. `--help`/`--version` print
+ * and exit before stdio is claimed; `--print-pairing` runs only the bridge and
+ * prints the handshake path (for manual pairing), never serving MCP.
+ */
+export {};

package/dist/src/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * src/cli.ts — `npx chrome-mcp` entrypoint.
+ *
+ * Boot order: resolve config → ensure data dir → generate a per-boot token →
+ * start the loopback bridge → write the 0600 handshake → configure the manager
+ * with the backend selector → serve MCP over stdio. `--help`/`--version` print
+ * and exit before stdio is claimed; `--print-pairing` runs only the bridge and
+ * prints the handshake path (for manual pairing), never serving MCP.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_1 = require("./config");
+const manager_1 = require("./executor/manager");
+const select_1 = require("./executor/select");
+const server_1 = require("./bridge/server");
+const datadir_1 = require("./bridge/datadir");
+const auth_1 = require("./bridge/auth");
+const server_2 = require("./mcp/server");
+function version() {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function main() {
+    const cfg = (0, config_1.parseArgs)(process.argv.slice(2));
+    if (cfg.showHelp) {
+        process.stdout.write(config_1.HELP_TEXT);
+        return;
+    }
+    if (cfg.showVersion) {
+        process.stdout.write(`${version()}\n`);
+        return;
+    }
+    const dataDir = (0, datadir_1.ensureDataDir)(cfg.dataDir);
+    const token = (0, auth_1.generateToken)();
+    const bridge = new server_1.BridgeServer({
+        token,
+        serverVersion: version(),
+        port: cfg.wsPort,
+        onLog: (m) => (0, server_2.logErr)(m),
+        onDisplacement: (d) => (0, server_2.logErr)(`SECURITY: extension connection displaced (different id: ${d.differentId})`),
+    });
+    const port = await bridge.start();
+    const handshakePath = (0, auth_1.writeHandshake)(dataDir, { port, token });
+    (0, server_2.logErr)(`pairing handshake written to ${handshakePath} (mode 0600; token not logged)`);
+    const cleanup = () => {
+        (0, auth_1.removeHandshake)(dataDir);
+    };
+    // Manual pairing helper: run the bridge, print the path, keep alive. NOT MCP.
+    if (cfg.printPairing) {
+        process.stdout.write(`${handshakePath}\n`);
+        (0, server_2.logErr)('pairing mode — bridge is up; open the extension and pair, then Ctrl-C.');
+        process.on('SIGINT', () => {
+            cleanup();
+            void bridge.stop().finally(() => process.exit(0));
+        });
+        return;
+    }
+    (0, manager_1.configureManager)({
+        policy: cfg.policy,
+        select: (0, select_1.createSelector)({
+            bridge,
+            cdpFallback: cfg.cdpFallback,
+            prefer: cfg.prefer,
+            cdp: {
+                mode: cfg.cdpEndpoint ? 'connect' : 'launch',
+                cdpEndpoint: cfg.cdpEndpoint,
+                userDataDir: dataDir,
+                headless: cfg.headless,
+            },
+        }),
+    });
+    (0, server_2.logErr)(`backend: extension-if-paired else ${cfg.cdpFallback ? 'CDP fallback' : 'none'} (prefer: ${cfg.prefer})`);
+    const shutdown = () => {
+        cleanup();
+        void Promise.allSettled([(0, server_2.stopMcpServer)(), bridge.stop()]).finally(() => process.exit(0));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await (0, server_2.startMcpServer)();
+}
+main().catch((err) => {
+    (0, server_2.logErr)(`fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/src/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * src/config.ts — the single source for runtime configuration.
+ *
+ * Resolves the WebSocket port, the data dir (where the 0600 handshake lives),
+ * and the security `Policy` from one place: defaults < env < CLI flags < policy
+ * file. Nothing else in the codebase should read `process.argv` or invent its
+ * own port/policy — they take a `CliConfig`.
+ */
+import { type Policy } from './security/policy';
+export type LogLevel = 'silent' | 'info' | 'debug';
+export type BackendPreference = 'extension' | 'cdp';
+export interface CliConfig {
+    /** Port the bridge binds; 0 = ephemeral (written to the handshake file). */
+    wsPort: number;
+    /** Directory holding handshake.json and the CDP-fallback profile. */
+    dataDir: string;
+    /** Resolved, fully-defaulted security policy. */
+    policy: Policy;
+    /** Whether to fall back to a Playwright-driven Chromium when no extension is paired. */
+    cdpFallback: boolean;
+    /** Optional CDP endpoint to attach to instead of launching (e.g. http://127.0.0.1:9222). */
+    cdpEndpoint?: string;
+    /** Which backend to prefer when both are available (testing knob). */
+    prefer: BackendPreference;
+    /** Run the CDP-fallback Chromium headless. */
+    headless: boolean;
+    /** `--print-pairing`: write the handshake and print its path (never the token). */
+    printPairing: boolean;
+    showHelp: boolean;
+    showVersion: boolean;
+    logLevel: LogLevel;
+}
+/** Resolve the data dir: `$CHROME_MCP_DATA` or `~/.chrome-mcp`. */
+export declare function resolveDataDir(): string;
+/**
+ * Parse argv (the slice AFTER `node script`, i.e. `process.argv.slice(2)`) plus
+ * env into a fully-resolved `CliConfig`. Pure except for the optional policy-file
+ * read triggered by `--policy <path>`.
+ */
+export declare function parseArgs(argv: string[]): CliConfig;
+/** Help text for `--help`. */
+export declare const HELP_TEXT: string;