@mehmoodqureshi/chrome-mcp 0.1.0

package/dist/src/config.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP_TEXT = void 0;
+exports.resolveDataDir = resolveDataDir;
+exports.parseArgs = parseArgs;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const protocol_1 = require("../shared/protocol");
+const policy_1 = require("./security/policy");
+/** Resolve the data dir: `$CHROME_MCP_DATA` or `~/.chrome-mcp`. */
+function resolveDataDir() {
+    return process.env.CHROME_MCP_DATA ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.chrome-mcp');
+}
+function readPolicyFile(path) {
+    const raw = (0, node_fs_1.readFileSync)(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error(`policy file ${path} did not contain a JSON object`);
+    }
+    return parsed;
+}
+/**
+ * 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>`.
+ */
+function parseArgs(argv) {
+    let wsPort = envInt('CHROME_MCP_WS_PORT') ?? protocol_1.DEFAULT_WS_PORT;
+    let cdpFallback = true;
+    let cdpEndpoint;
+    let prefer = 'extension';
+    let headless = false;
+    let printPairing = false;
+    let showHelp = false;
+    let showVersion = false;
+    let logLevel = 'info';
+    // Policy assembled from flags, layered over an optional file.
+    let policyFile;
+    const policyFlags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case '-h':
+            case '--help':
+                showHelp = true;
+                break;
+            case '-v':
+            case '--version':
+                showVersion = true;
+                break;
+            case '--port':
+                wsPort = requireInt(argv[++i], '--port');
+                break;
+            case '--data-dir':
+                process.env.CHROME_MCP_DATA = requireValue(argv[++i], '--data-dir');
+                break;
+            case '--policy':
+                policyFile = readPolicyFile(requireValue(argv[++i], '--policy'));
+                break;
+            case '--unsafe-all-domains':
+                policyFlags.allowDomains = ['*'];
+                break;
+            case '--allow-domain':
+                (policyFlags.allowDomains ??= []).push(requireValue(argv[++i], '--allow-domain'));
+                break;
+            case '--enable-mutations':
+                policyFlags.enableMutations = true;
+                break;
+            case '--unsafe-enable-eval':
+                policyFlags.allowEval = true;
+                break;
+            case '--enable-downloads':
+                policyFlags.allowDownloads = true;
+                break;
+            case '--allow-all-tabs':
+                policyFlags.allowAllTabs = true;
+                break;
+            case '--no-cdp-fallback':
+                cdpFallback = false;
+                break;
+            case '--cdp-endpoint':
+                cdpEndpoint = requireValue(argv[++i], '--cdp-endpoint');
+                break;
+            case '--prefer':
+                prefer = requirePreference(argv[++i]);
+                break;
+            case '--headless':
+                headless = true;
+                break;
+            case '--print-pairing':
+                printPairing = true;
+                break;
+            case '--log-level':
+                logLevel = requireLogLevel(argv[++i]);
+                break;
+            default:
+                throw new Error(`unknown argument: ${arg}`);
+        }
+    }
+    // File first, then flags win.
+    const policy = (0, policy_1.resolvePolicy)({ ...policyFile, ...policyFlags });
+    return {
+        wsPort,
+        dataDir: resolveDataDir(),
+        policy,
+        cdpFallback,
+        cdpEndpoint,
+        prefer,
+        headless,
+        printPairing,
+        showHelp,
+        showVersion,
+        logLevel,
+    };
+}
+// ---------------------------------------------------------------------------
+// Small parsing helpers
+// ---------------------------------------------------------------------------
+function envInt(name) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isInteger(n) || n < 0)
+        throw new Error(`${name} must be a non-negative integer`);
+    return n;
+}
+function requireValue(value, flag) {
+    if (value === undefined)
+        throw new Error(`${flag} requires a value`);
+    return value;
+}
+function requireInt(value, flag) {
+    const n = Number.parseInt(requireValue(value, flag), 10);
+    if (!Number.isInteger(n) || n < 0)
+        throw new Error(`${flag} must be a non-negative integer`);
+    return n;
+}
+function requirePreference(value) {
+    if (value === 'extension' || value === 'cdp')
+        return value;
+    throw new Error('--prefer must be "extension" or "cdp"');
+}
+function requireLogLevel(value) {
+    if (value === 'silent' || value === 'info' || value === 'debug')
+        return value;
+    throw new Error('--log-level must be "silent", "info", or "debug"');
+}
+/** Help text for `--help`. */
+exports.HELP_TEXT = `chrome-mcp — drive a real Chrome browser over MCP.
+
+Usage: chrome-mcp [options]
+
+Connection:
+  --port <n>             WebSocket bridge port (default ${protocol_1.DEFAULT_WS_PORT}; 0 = ephemeral)
+  --data-dir <path>      Override the data dir (default ~/.chrome-mcp)
+  --print-pairing        Write the handshake and print its path, then exit
+
+Backend:
+  --no-cdp-fallback      Do not launch/attach Chromium when no extension is paired
+  --cdp-endpoint <url>   Attach to an existing Chrome (e.g. http://127.0.0.1:9222)
+  --prefer <which>       "extension" (default) or "cdp"
+  --headless             Run the CDP-fallback Chromium headless
+
+Security (default: deny-all safe mode):
+  --policy <file>        Load a JSON policy file
+  --allow-domain <glob>  Add a domain to the allowlist (repeatable)
+  --unsafe-all-domains   Allow every domain (loud footgun)
+  --enable-mutations     Enable click/type/navigate/… (off by default)
+  --unsafe-enable-eval   Enable the eval primitive (off by default)
+  --enable-downloads     Enable download_file (off by default)
+  --allow-all-tabs       Relax tab list/select to all tabs
+
+Misc:
+  --log-level <lvl>      silent | info | debug (default info)
+  -h, --help             Show this help
+  -v, --version          Show version
+`;
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1,131 @@
+/**
+ * src/executor/cdp-executor.ts — the Playwright-driven fallback Executor.
+ *
+ * Used when no extension is paired. Two acquisition modes:
+ *   - 'connect': attach over CDP to a Chrome we did NOT launch (never closed by
+ *     us — its lifecycle is the user's).
+ *   - 'launch':  spawn a dedicated persistent Chromium under a profile that is
+ *     NOT the user's real one (would conflict with the extension-driven Chrome).
+ *
+ * Ported from linkedin-mcp/src/driver/browser.ts: the stale-profile-lock
+ * recovery (a SIGKILLed MCP child orphans `SingletonLock`), connect-once reuse,
+ * stealth init on the launch path only, and tab resolution. `tabId`s are stamped
+ * `cdp:<sessionId>:<n>` so a handle never mis-routes across a backend switch.
+ */
+import { type ActionOk, type BackendKind, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type KeyModifier, type NavResult, type ScreenshotResult, type TabId, type TabInfo, type Target, type WaitResult, type WaitUntil } from './types';
+export interface CdpOptions {
+    mode: 'connect' | 'launch';
+    cdpEndpoint?: string;
+    userDataDir: string;
+    headless?: boolean;
+    downloadDir?: string;
+}
+export declare class CdpExecutor implements Executor {
+    private readonly opts;
+    readonly backend: BackendKind;
+    private readonly sessionId;
+    private readonly profileDir;
+    private cdpBrowser;
+    private context;
+    private launching;
+    /** Whether WE own (launched) the browser — only then may we close it. */
+    private launched;
+    private readonly tabs;
+    private seq;
+    constructor(opts: CdpOptions);
+    status(): ExecutorStatus;
+    ensureReady(): Promise<void>;
+    ping(): Promise<boolean>;
+    dispose(): Promise<void>;
+    private getContext;
+    private doConnect;
+    private doLaunch;
+    private launchWithLockRecovery;
+    private idFor;
+    private contentPages;
+    private resolveTab;
+    private locator;
+    tabsList(): Promise<TabInfo[]>;
+    tabSelect(tabId: TabId): Promise<TabInfo>;
+    tabNew(url?: string): Promise<TabInfo>;
+    tabClose(tabId: TabId): Promise<{
+        closed: true;
+        tabId: TabId;
+    }>;
+    private toState;
+    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>;
+    private ok;
+    click(t: Target, opts?: {
+        tabId?: TabId;
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+    }): Promise<ActionOk>;
+    type(t: Target, text: string, opts?: {
+        tabId?: TabId;
+        clear?: boolean;
+        pressEnter?: boolean;
+        keyEvents?: boolean;
+    }): Promise<ActionOk>;
+    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>;
+}