@mehmoodqureshi/chrome-mcp 0.1.0

package/dist/src/executor/manager.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * src/executor/manager.ts — owns the process-global active Executor and the
+ * `withReadyExecutor()` accessor every tool routes through (the `withReadyDriver`
+ * analog from the LinkedIn repo).
+ *
+ * Phase 1 holds a single Executor produced by an injected factory (the Stub).
+ * Later phases replace the factory with real selection logic (extension-if-
+ * responsive else CDP), but the surface the tools see — `ensureReady()` +
+ * `policy` — does not change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutorManager = void 0;
+exports.configureManager = configureManager;
+exports.getManager = getManager;
+exports.resetManagerForTesting = resetManagerForTesting;
+exports.withReadyExecutor = withReadyExecutor;
+const types_1 = require("./types");
+class ExecutorManager {
+    opts;
+    current = null;
+    readying = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get policy() {
+        return this.opts.policy;
+    }
+    /** Inject a ready-made executor (tests, or a later phase's selector). */
+    setExecutor(ex) {
+        this.current = ex;
+    }
+    /**
+     * Return a ready Executor, constructing it lazily and single-flight-guarding
+     * concurrent callers. Throws `NO_BACKEND` when nothing is configured.
+     */
+    async ensureReady() {
+        if (this.readying)
+            return this.readying;
+        this.readying = this.doEnsure();
+        try {
+            return await this.readying;
+        }
+        finally {
+            this.readying = null;
+        }
+    }
+    async doEnsure() {
+        // Selection strategy (Phase 3+): re-pick the backend each call.
+        if (this.opts.select) {
+            const chosen = await this.opts.select();
+            this.current = chosen;
+            await chosen.ensureReady();
+            return chosen;
+        }
+        // Single-backend path (Phase 1 stub).
+        if (!this.current) {
+            if (!this.opts.makeExecutor) {
+                throw new types_1.ExecutorError('NO_BACKEND', 'No Chrome available: pair the extension or enable a backend.');
+            }
+            this.current = this.opts.makeExecutor();
+        }
+        await this.current.ensureReady();
+        return this.current;
+    }
+    async dispose() {
+        const ex = this.current;
+        this.current = null;
+        await ex?.dispose();
+    }
+}
+exports.ExecutorManager = ExecutorManager;
+// ---------------------------------------------------------------------------
+// Process-global singleton
+// ---------------------------------------------------------------------------
+let singleton = null;
+/** Install (or replace) the global manager. Returns it. */
+function configureManager(opts) {
+    singleton = new ExecutorManager(opts);
+    return singleton;
+}
+function getManager() {
+    if (!singleton)
+        throw new Error('ExecutorManager has not been configured');
+    return singleton;
+}
+/** Tear down the singleton (tests). */
+function resetManagerForTesting() {
+    singleton = null;
+}
+async function withReadyExecutor() {
+    return getManager().ensureReady();
+}
+//# sourceMappingURL=manager.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * src/executor/select.ts — backend selection.
+ *
+ * Re-evaluated on every `ensureReady()`: prefer a *responsive* extension (an
+ * 800 ms ping probe, so a dead-but-not-yet-reconnected MV3 worker falls through
+ * instead of eating a 30 s command timeout), otherwise the CDP fallback. The
+ * extension and CDP executors are cached across calls; only the choice is live.
+ */
+import { type Executor } from './types';
+import { type CdpOptions } from './cdp-executor';
+import type { BridgeServer } from '../bridge/server';
+import type { BackendPreference } from '../config';
+export interface SelectorDeps {
+    bridge: BridgeServer;
+    cdpFallback: boolean;
+    prefer: BackendPreference;
+    cdp: CdpOptions;
+    pingDeadlineMs?: number;
+    /** Test seams — default to the real executors. */
+    makeExtension?: (bridge: BridgeServer) => Executor;
+    makeCdp?: (opts: CdpOptions) => Executor;
+}
+export declare function createSelector(deps: SelectorDeps): () => Promise<Executor>;

package/dist/src/executor/select.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * src/executor/select.ts — backend selection.
+ *
+ * Re-evaluated on every `ensureReady()`: prefer a *responsive* extension (an
+ * 800 ms ping probe, so a dead-but-not-yet-reconnected MV3 worker falls through
+ * instead of eating a 30 s command timeout), otherwise the CDP fallback. The
+ * extension and CDP executors are cached across calls; only the choice is live.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSelector = createSelector;
+const types_1 = require("./types");
+const extension_executor_1 = require("./extension-executor");
+const cdp_executor_1 = require("./cdp-executor");
+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 ext = makeExt(deps.bridge);
+    let cdp = null;
+    const cdpAllowed = () => deps.cdpFallback || deps.prefer === 'cdp' || !!deps.cdp.cdpEndpoint;
+    const getCdp = () => {
+        if (!cdpAllowed())
+            return null;
+        cdp ??= makeCdp(deps.cdp);
+        return cdp;
+    };
+    const tryExt = async () => {
+        if (!deps.bridge.hasActiveExtension())
+            return null;
+        return (await ext.ping(pingMs)) ? ext : null;
+    };
+    return async () => {
+        if (deps.prefer === 'cdp') {
+            const c = getCdp();
+            if (c)
+                return c;
+            const e = await tryExt();
+            if (e)
+                return e;
+        }
+        else {
+            const e = await tryExt();
+            if (e)
+                return e;
+            const c = getCdp();
+            if (c)
+                return c;
+        }
+        throw new types_1.ExecutorError('NO_BACKEND', 'No Chrome available: pair the extension, attach a --cdp-endpoint, or enable the CDP fallback.');
+    };
+}
+//# sourceMappingURL=select.js.map

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

@@ -0,0 +1,60 @@
+/**
+ * src/executor/stub-executor.ts — an in-memory Executor with no browser.
+ *
+ * Two jobs:
+ *   1. Lets Phase 1 ship a fully working MCP server you can point Claude at with
+ *      zero Chrome involved (the CLI uses it until the real backends land).
+ *   2. Drives the dispatch/policy/envelope tests with deterministic, canned
+ *      values (and a couple of forced-failure switches).
+ */
+import { type ActionOk, type BackendKind, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type NavResult, type ScreenshotResult, type TabId, type TabInfo, type Target, type WaitResult } from './types';
+export interface StubOptions {
+    /** URL of the (single) active tab — used to exercise the domain policy gate. */
+    activeUrl?: string;
+    /** When true, `eval` resolves `{ok:false}` to mimic a page-side throw. */
+    evalThrows?: boolean;
+}
+export declare class StubExecutor implements Executor {
+    readonly backend: BackendKind;
+    private url;
+    private readonly evalThrows;
+    private ready;
+    constructor(opts?: StubOptions);
+    private tab;
+    status(): ExecutorStatus;
+    ensureReady(): Promise<void>;
+    ping(): Promise<boolean>;
+    dispose(): Promise<void>;
+    tabsList(): Promise<TabInfo[]>;
+    tabSelect(tabId: TabId): Promise<TabInfo>;
+    tabNew(url?: string): Promise<TabInfo>;
+    tabClose(tabId: TabId): Promise<{
+        closed: true;
+        tabId: TabId;
+    }>;
+    navigate(args: {
+        url: string;
+    }): Promise<NavResult>;
+    back(): Promise<NavResult>;
+    forward(): Promise<NavResult>;
+    reload(): Promise<NavResult>;
+    click(): Promise<ActionOk>;
+    type(): Promise<ActionOk>;
+    fill(): Promise<ActionOk>;
+    press(): Promise<ActionOk>;
+    hover(): Promise<ActionOk>;
+    scroll(): Promise<ActionOk>;
+    getText(_t?: Target): Promise<{
+        text: string;
+        ref?: string;
+    }>;
+    getHtml(): Promise<{
+        html: string;
+    }>;
+    screenshot(): Promise<ScreenshotResult>;
+    eval(expression: string): Promise<EvalResult>;
+    waitFor(): Promise<WaitResult>;
+    download(args: {
+        suggestedName?: string;
+    }): Promise<DownloadResult>;
+}

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

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * src/executor/stub-executor.ts — an in-memory Executor with no browser.
+ *
+ * Two jobs:
+ *   1. Lets Phase 1 ship a fully working MCP server you can point Claude at with
+ *      zero Chrome involved (the CLI uses it until the real backends land).
+ *   2. Drives the dispatch/policy/envelope tests with deterministic, canned
+ *      values (and a couple of forced-failure switches).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StubExecutor = void 0;
+/** 1×1 transparent PNG, base64 — a valid image block for screenshot tests. */
+const TINY_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
+const ok = { ok: true };
+class StubExecutor {
+    backend = 'extension';
+    url;
+    evalThrows;
+    ready = false;
+    constructor(opts = {}) {
+        this.url = opts.activeUrl ?? 'about:blank';
+        this.evalThrows = opts.evalThrows ?? false;
+    }
+    tab() {
+        return { tabId: 'extension:stub:1', url: this.url, title: 'Stub Page', active: true, index: 0 };
+    }
+    status() {
+        return {
+            ready: this.ready,
+            backend: this.backend,
+            activeTabId: this.tab().tabId,
+            extensionConnected: true,
+            cdpAttached: false,
+        };
+    }
+    async ensureReady() {
+        this.ready = true;
+    }
+    async ping() {
+        return true;
+    }
+    async dispose() {
+        this.ready = false;
+    }
+    async tabsList() {
+        return [this.tab()];
+    }
+    async tabSelect(tabId) {
+        return { ...this.tab(), tabId };
+    }
+    async tabNew(url) {
+        if (url)
+            this.url = url;
+        return this.tab();
+    }
+    async tabClose(tabId) {
+        return { closed: true, tabId };
+    }
+    async navigate(args) {
+        this.url = args.url;
+        return { url: args.url, title: 'Stub Page', httpStatus: 200 };
+    }
+    async back() {
+        return { url: this.url, title: 'Stub Page' };
+    }
+    async forward() {
+        return { url: this.url, title: 'Stub Page' };
+    }
+    async reload() {
+        return { url: this.url, title: 'Stub Page' };
+    }
+    async click() {
+        return ok;
+    }
+    async type() {
+        return ok;
+    }
+    async fill() {
+        return ok;
+    }
+    async press() {
+        return ok;
+    }
+    async hover() {
+        return ok;
+    }
+    async scroll() {
+        return ok;
+    }
+    async getText(_t) {
+        return { text: 'stub text', ref: 'el_stub_1' };
+    }
+    async getHtml() {
+        return { html: '<html><body><a href="https://example.com">Example</a></body></html>' };
+    }
+    async screenshot() {
+        return { dataBase64: TINY_PNG, mimeType: 'image/png', width: 1, height: 1, truncated: false };
+    }
+    async eval(expression) {
+        if (this.evalThrows || /throw/.test(expression)) {
+            return { ok: false, error: 'Error: stub page threw' };
+        }
+        return { ok: true, value: 'stub-value', type: 'string' };
+    }
+    async waitFor() {
+        return { matched: true, waitedMs: 0 };
+    }
+    async download(args) {
+        return {
+            path: `/stub/downloads/${args.suggestedName ?? 'file.download'}`,
+            backend: this.backend,
+            bytes: 0,
+        };
+    }
+}
+exports.StubExecutor = StubExecutor;
+//# sourceMappingURL=stub-executor.js.map

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

@@ -0,0 +1,192 @@
+/**
+ * src/executor/types.ts — the single backend-agnostic Executor contract.
+ *
+ * Plain JSON-serializable in/out: no Playwright `Page`, no CDP session, no DOM
+ * handle ever crosses this boundary. Both `ExtensionExecutor` (over the WS
+ * bridge) and `CdpExecutor` (Playwright) implement this identical interface, so
+ * the tool layer never knows or cares which backend is live.
+ *
+ * Helpers (extract_links / read_as_markdown / fill_form) are composed in
+ * `mcp/helpers.ts` from these primitives; only `download` is privileged.
+ */
+export type BackendKind = 'extension' | 'cdp';
+export type WaitUntil = 'load' | 'domcontentloaded' | 'networkidle';
+export type KeyModifier = 'Alt' | 'Control' | 'Meta' | 'Shift';
+export type MouseButton = 'left' | 'right' | 'middle';
+/**
+ * A target element: selector XOR ref. `requireTarget()` enforces exactly-one-of.
+ * Refs are minted by getText/extractLinks/waitFor/eval results and are
+ * PAGE-scoped — invalidated when that tab navigates. Format:
+ * `el_<tabShort>_<backendNodeId>`.
+ */
+export type Target = {
+    selector: string;
+    ref?: never;
+} | {
+    ref: string;
+    selector?: never;
+};
+/**
+ * Tab handle. ALWAYS prefixed `<backend>:<sessionId>:<rawId>` so a handle minted
+ * by one backend/session can never mis-route after a fallback switch or a
+ * reconnect (a mismatch becomes a clean `STALE_TAB`, not a wrong-tab action).
+ */
+export type TabId = string;
+export interface TabInfo {
+    tabId: TabId;
+    url: string;
+    title: string;
+    active: boolean;
+    index: number;
+}
+export interface NavResult {
+    url: string;
+    title: string;
+    httpStatus?: number;
+}
+/** `value` is truncated when serialized > 256KB. */
+export interface EvalResult {
+    ok: boolean;
+    value?: unknown;
+    type?: string;
+    error?: string;
+}
+export interface WaitResult {
+    matched: boolean;
+    ref?: string;
+    waitedMs: number;
+}
+export interface ActionOk {
+    ok: true;
+}
+export interface ScreenshotResult {
+    dataBase64: string;
+    mimeType: 'image/png';
+    width: number;
+    height: number;
+    /** fullPage capture exceeded the height cap; `fullHeight` reports the real size. */
+    truncated: boolean;
+    fullHeight?: number;
+}
+export interface DownloadResult {
+    path: string;
+    backend: BackendKind;
+    bytes: number;
+    mimeType?: string;
+    suggestedName?: string;
+}
+export interface ExecutorStatus {
+    ready: boolean;
+    backend: BackendKind | null;
+    activeTabId: TabId | null;
+    /** WHY unavailable (port in use, no extension, policy denied, etc.). */
+    detail?: string;
+    extensionConnected: boolean;
+    cdpAttached: boolean;
+}
+export interface Executor {
+    readonly backend: BackendKind;
+    status(): ExecutorStatus;
+    /** Idempotent lazy connect/attach + self-heal; single-flight guarded. */
+    ensureReady(): Promise<void>;
+    /**
+     * Lightweight responsiveness probe (short deadline). Used by
+     * `withReadyExecutor` to detect a dead-but-not-yet-reconnected MV3 worker and
+     * fall through to CDP instead of eating a full command timeout.
+     */
+    ping(deadlineMs?: number): Promise<boolean>;
+    /** Close ONLY if we own the browser; never the user's Chrome. */
+    dispose(): Promise<void>;
+    tabsList(): Promise<TabInfo[]>;
+    tabSelect(tabId: TabId): Promise<TabInfo>;
+    tabNew(url?: string): Promise<TabInfo>;
+    tabClose(tabId: TabId): Promise<{
+        closed: true;
+        tabId: TabId;
+    }>;
+    navigate(args: {
+        url: string;
+        tabId?: TabId;
+        waitUntil?: WaitUntil;
+    }): Promise<NavResult>;
+    back(tabId?: TabId): Promise<NavResult>;
+    forward(tabId?: TabId): Promise<NavResult>;
+    reload(args?: {
+        tabId?: TabId;
+        waitUntil?: WaitUntil;
+    }): Promise<NavResult>;
+    click(t: Target, opts?: {
+        tabId?: TabId;
+        button?: MouseButton;
+        clickCount?: number;
+    }): Promise<ActionOk>;
+    type(t: Target, text: string, opts?: {
+        tabId?: TabId;
+        clear?: boolean;
+        pressEnter?: boolean;
+        keyEvents?: boolean;
+    }): Promise<ActionOk>;
+    /** Value-set + input/change events (used by fill_form). */
+    fill(t: Target, value: string, opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
+    press(key: string, opts?: {
+        tabId?: TabId;
+        modifiers?: KeyModifier[];
+    }): Promise<ActionOk>;
+    hover(t: Target, opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
+    scroll(opts: {
+        tabId?: TabId;
+        x?: number;
+        y?: number;
+        deltaX?: number;
+        deltaY?: number;
+        target?: Target;
+    }): Promise<ActionOk>;
+    getText(t?: Target, opts?: {
+        tabId?: TabId;
+    }): Promise<{
+        text: string;
+        ref?: string;
+    }>;
+    getHtml(t?: Target, opts?: {
+        tabId?: TabId;
+        outer?: boolean;
+    }): Promise<{
+        html: string;
+    }>;
+    screenshot(opts?: {
+        tabId?: TabId;
+        fullPage?: boolean;
+        target?: Target;
+    }): Promise<ScreenshotResult>;
+    eval(expression: string, opts?: {
+        tabId?: TabId;
+        awaitPromise?: boolean;
+    }): Promise<EvalResult>;
+    waitFor(opts: {
+        tabId?: TabId;
+        selector?: string;
+        textContains?: string;
+        gone?: boolean;
+        timeoutMs?: number;
+    }): Promise<WaitResult>;
+    download(args: {
+        url?: string;
+        target?: Target;
+        tabId?: TabId;
+        suggestedName?: string;
+    }): Promise<DownloadResult>;
+}
+/**
+ * Server-side executor error codes. A superset of the wire `ExecutorErrorCode`
+ * (which only carries codes that originate inside the extension); these extra
+ * codes describe failures on the server half (no backend, launch failed, etc.).
+ */
+export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'BACKPRESSURE';
+export declare class ExecutorError extends Error {
+    readonly code: ExecutorErrorCodeLocal;
+    constructor(code: ExecutorErrorCodeLocal, message: string);
+}

package/dist/src/executor/types.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * src/executor/types.ts — the single backend-agnostic Executor contract.
+ *
+ * Plain JSON-serializable in/out: no Playwright `Page`, no CDP session, no DOM
+ * handle ever crosses this boundary. Both `ExtensionExecutor` (over the WS
+ * bridge) and `CdpExecutor` (Playwright) implement this identical interface, so
+ * the tool layer never knows or cares which backend is live.
+ *
+ * Helpers (extract_links / read_as_markdown / fill_form) are composed in
+ * `mcp/helpers.ts` from these primitives; only `download` is privileged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutorError = void 0;
+class ExecutorError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ExecutorError';
+    }
+}
+exports.ExecutorError = ExecutorError;
+//# sourceMappingURL=types.js.map

package/dist/src/mcp/envelopes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * src/mcp/envelopes.ts — serialize handler results into the MCP `content`
+ * envelope. One place so every tool returns a consistent shape.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** A JSON payload rendered as pretty text (the default for structured results). */
+export declare function jsonResult(data: unknown): CallToolResult;
+/** A plain text payload (e.g. read_as_markdown). */
+export declare function textResult(text: string): CallToolResult;
+/** A base64 image, optionally with a caption line. */
+export declare function imageResult(dataBase64: string, mimeType: string, caption?: string): CallToolResult;
+/** A structured error result — never throws; sets `isError` for the host. */
+export declare function errorResult(message: string): CallToolResult;

package/dist/src/mcp/envelopes.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * src/mcp/envelopes.ts — serialize handler results into the MCP `content`
+ * envelope. One place so every tool returns a consistent shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonResult = jsonResult;
+exports.textResult = textResult;
+exports.imageResult = imageResult;
+exports.errorResult = errorResult;
+/** A JSON payload rendered as pretty text (the default for structured results). */
+function jsonResult(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+/** A plain text payload (e.g. read_as_markdown). */
+function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/** A base64 image, optionally with a caption line. */
+function imageResult(dataBase64, mimeType, caption) {
+    const content = [{ type: 'image', data: dataBase64, mimeType }];
+    if (caption)
+        content.push({ type: 'text', text: caption });
+    return { content };
+}
+/** A structured error result — never throws; sets `isError` for the host. */
+function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+//# sourceMappingURL=envelopes.js.map

package/dist/src/mcp/helpers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * src/mcp/helpers.ts — the high-level tools composed SERVER-SIDE from executor
+ * primitives. They never touch the wire directly: `extract_links` and
+ * `read_as_markdown` read via primitives; `fill_form` sequences fill+click.
+ * (Only `download_file` is privileged and lives on the executor.)
+ */
+import type { Executor } from '../executor/types';
+export interface LinkOut {
+    href: string;
+    text: string;
+    ref?: string;
+}
+/**
+ * Collect anchors from the page (or a subtree). Implemented as a single page
+ * eval so it is one round-trip; falls back to parsing getHtml if eval is denied.
+ */
+export declare function extractLinks(ex: Executor, args: {
+    selector?: string;
+    sameOriginOnly?: boolean;
+    tabId?: string;
+}): Promise<{
+    links: LinkOut[];
+}>;
+/** Read a page (or subtree) as readable markdown. */
+export declare function readAsMarkdown(ex: Executor, args: {
+    selector?: string;
+    tabId?: string;
+}): Promise<string>;
+/** Fill a set of fields (keyed by selector) and optionally submit. */
+export declare function fillForm(ex: Executor, args: {
+    fields: Record<string, string | boolean>;
+    submitSelector?: string;
+    tabId?: string;
+}): Promise<{
+    filled: number;
+    submitted: boolean;
+}>;