@mehmoodqureshi/chrome-mcp 0.3.0 → 0.4.0

package/README.md

@@ -32,7 +32,13 @@ Distributed as an `npx` CLI (the MCP server) plus a load-unpacked extension.
 
 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`.
+`--enable-downloads`, `--enable-uploads`, `--unsafe-enable-eval`, or `--unsafe-all-domains`.
+
+> `--enable-uploads` permits `upload_file` (setting local file(s) on a page's file
+> `<input>`). It is **off by default** because sending local files to a page is an
+> exfiltration risk; it is also gated by the destination-domain allowlist. Pair it
+> with `--uploads-dir <path>` to restrict uploads to files inside that directory
+> (`..` traversal is blocked) — strongly recommended for unattended use.
 
 **Drive only your real Chrome (recommended for the extension).** Add
 `--no-cdp-fallback` so the server never launches a separate Chromium, and
@@ -71,8 +77,9 @@ The tools cover tabs, navigation, interaction (`click`/`type`/`press`/`hover`/
 `scroll`/`select_option`), reads (`get_text`/`get_html`/`screenshot`/`eval`/`wait_for`),
 an accessibility `snapshot` (interactive elements with stable `ref`s the model can
 target instead of guessing CSS selectors), session access (`get_cookies`/`storage`),
-helpers (`extract_links`/`read_as_markdown`/`fill_form`/`download_file`), and
-`chrome_status`.
+helpers (`extract_links`/`read_as_markdown`/`fill_form`/`download_file`/`upload_file`),
+and `chrome_status`. `upload_file` sets local file(s) on a file `<input>` without the
+OS dialog (requires `--enable-uploads`).
 
 `click`/`type` accept `trusted: true` for real OS-level input (works on
 React/Vue controlled inputs); interactions auto-wait for the target to appear.
@@ -91,7 +98,7 @@ token (`--persist-token`).
       (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 +
+      stdio), `mcp/tools.ts` (28-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,

package/dist/shared/protocol.d.ts

@@ -32,10 +32,10 @@ export declare const CLOSE_SUPERSEDED: 4000;
  * `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' | 'snapshot' | 'select_option' | 'get_cookies' | 'storage' | 'eval' | 'wait_for' | 'download_file' | 'ping_probe';
+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' | 'snapshot' | 'select_option' | 'get_cookies' | 'storage' | 'eval' | 'wait_for' | 'download_file' | 'upload_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 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' | 'UPLOAD_FAILED' | 'UNKNOWN_METHOD';
 export interface BaseFrame {
     type: string;
     v: ProtocolVersion;

package/dist/shared/protocol.js

@@ -54,6 +54,7 @@ exports.WIRE_METHODS = [
     'eval',
     'wait_for',
     'download_file',
+    'upload_file',
     'ping_probe',
 ];
 //# sourceMappingURL=protocol.js.map

package/dist/shared/snapshot.js

@@ -20,7 +20,30 @@ function collectSnapshot(interactiveOnly = true, max = 200) {
         if (r.width === 0 && r.height === 0)
             return false;
         const s = window.getComputedStyle(el);
-        return s.visibility !== 'hidden' && s.display !== 'none';
+        if (s.visibility === 'hidden' || s.display === 'none')
+            return false;
+        // Prefer the native check (accounts for ancestors, content-visibility, etc.).
+        const cv = el.checkVisibility;
+        if (typeof cv === 'function') {
+            try {
+                return cv.call(el, { checkOpacity: false, checkVisibilityCSS: true });
+            }
+            catch {
+                /* fall through to manual ancestor walk */
+            }
+        }
+        // Fallback: walk ancestors for display:none / visibility:hidden. An element
+        // with no offsetParent (and not position:fixed) is detached/hidden.
+        let p = el.parentElement;
+        while (p) {
+            const ps = window.getComputedStyle(p);
+            if (ps.display === 'none' || ps.visibility === 'hidden')
+                return false;
+            p = p.parentElement;
+        }
+        if (el.offsetParent === null && s.position !== 'fixed')
+            return false;
+        return true;
     };
     const accName = (el) => {
         const aria = el.getAttribute('aria-label');
@@ -69,7 +92,46 @@ function collectSnapshot(interactiveOnly = true, max = 200) {
         }
         return tag;
     };
-    const els = Array.from(document.querySelectorAll(sel)).filter(visible);
+    // Collect candidates across the light DOM *and* open shadow roots, descending
+    // recursively. Defensive against null/closed shadow roots and re-visits.
+    const seen = new Set();
+    const candidates = [];
+    const collect = (root) => {
+        if (candidates.length >= max)
+            return;
+        let matched;
+        try {
+            matched = Array.from(root.querySelectorAll(sel));
+        }
+        catch {
+            matched = [];
+        }
+        for (const el of matched) {
+            if (candidates.length >= max)
+                break;
+            if (seen.has(el))
+                continue;
+            seen.add(el);
+            candidates.push(el);
+        }
+        // Descend into any open shadow roots hosted under this root.
+        let hosts;
+        try {
+            hosts = Array.from(root.querySelectorAll('*'));
+        }
+        catch {
+            hosts = [];
+        }
+        for (const host of hosts) {
+            if (candidates.length >= max)
+                break;
+            const sr = host.shadowRoot;
+            if (sr)
+                collect(sr);
+        }
+    };
+    collect(document);
+    const els = candidates.filter(visible);
     const nodes = [];
     let n = 0;
     for (const el of els) {

package/dist/src/bridge/server.js

@@ -21,6 +21,8 @@ const connection_1 = require("./connection");
 const auth_1 = require("./auth");
 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;
 class BridgeServer {
     opts;
     wss = null;
@@ -78,6 +80,9 @@ class BridgeServer {
     // -- internals ----------------------------------------------------------
     handleConnection(ws) {
         let authed = false;
+        // Cap pre-auth frames so a peer can't hold a socket idle by streaming
+        // non-hello noise until HELLO_TIMEOUT_MS.
+        let preAuthFrames = 0;
         const helloTimer = setTimeout(() => {
             if (authed)
                 return;
@@ -87,6 +92,11 @@ class BridgeServer {
         const onMessage = (raw) => {
             if (authed)
                 return;
+            if (++preAuthFrames > MAX_PREAUTH_FRAMES) {
+                clearTimeout(helloTimer);
+                this.reject(ws, 'bad_token');
+                return;
+            }
             let frame;
             try {
                 frame = JSON.parse(raw.toString());
@@ -136,7 +146,13 @@ class BridgeServer {
             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 });
+            try {
+                this.opts.onDisplacement?.({ oldExtId: prev.extId, newExtId: ext.id, differentId });
+            }
+            catch {
+                // A throwing displacement callback must not take down the bridge.
+                this.log('onDisplacement callback threw; ignored');
+            }
             prev.close(protocol_1.CLOSE_SUPERSEDED, 'superseded');
         }
         const conn = new connection_1.ExtensionConnection({

package/dist/src/cli.js

@@ -19,6 +19,27 @@ const server_1 = require("./bridge/server");
 const datadir_1 = require("./bridge/datadir");
 const auth_1 = require("./bridge/auth");
 const server_2 = require("./mcp/server");
+/** Hard deadline for clean shutdown before we force-exit (a stuck socket must not hang us). */
+const SHUTDOWN_DEADLINE_MS = 3000;
+/**
+ * Race a best-effort shutdown against a hard deadline, then exit. The timer is
+ * unref'd so it never itself keeps the process alive; if it fires first we log a
+ * brief note that clean shutdown did not complete in time.
+ */
+function exitWithDeadline(work) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), SHUTDOWN_DEADLINE_MS);
+        timer.unref();
+    });
+    void Promise.race([work.then(() => 'clean'), deadline]).then((outcome) => {
+        clearTimeout(timer);
+        if (outcome === 'timeout') {
+            (0, server_2.logErr)(`shutdown deadline (${SHUTDOWN_DEADLINE_MS}ms) hit before clean shutdown; forcing exit.`);
+        }
+        process.exit(0);
+    });
+}
 function version() {
     try {
         const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', '..', 'package.json'), 'utf8'));
@@ -65,7 +86,7 @@ async function main() {
         (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));
+            exitWithDeadline(bridge.stop());
         });
         return;
     }
@@ -86,11 +107,11 @@ async function main() {
     (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));
+        exitWithDeadline(Promise.allSettled([(0, server_2.stopMcpServer)(), bridge.stop()]));
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
-    await (0, server_2.startMcpServer)();
+    await (0, server_2.startMcpServer)(version());
 }
 main().catch((err) => {
     (0, server_2.logErr)(`fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);

package/dist/src/config.js

@@ -84,6 +84,12 @@ function parseArgs(argv) {
             case '--enable-downloads':
                 policyFlags.allowDownloads = true;
                 break;
+            case '--enable-uploads':
+                policyFlags.allowUploads = true;
+                break;
+            case '--uploads-dir':
+                policyFlags.uploadsDir = (0, node_path_1.resolve)(requireValue(argv[++i], '--uploads-dir'));
+                break;
             case '--allow-all-tabs':
                 policyFlags.allowAllTabs = true;
                 break;
@@ -194,6 +200,8 @@ Security (default: deny-all safe mode):
   --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)
+  --enable-uploads       Enable upload_file — sends local files to a page (off by default)
+  --uploads-dir <path>   Restrict upload_file to files inside <path> (recommended with --enable-uploads)
   --allow-all-tabs       Relax tab list/select to all tabs
 
 Misc:

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

@@ -45,6 +45,13 @@ export declare class CdpExecutor implements Executor {
     private contentPages;
     private resolveTab;
     private locator;
+    /**
+     * Run a live-page operation, converting an opaque "target closed"/crashed
+     * error from Playwright into a clean DETACHED. On such a failure we also drop
+     * the cached context/tabs so the next call relaunches or reconnects cleanly.
+     * Any other error is rethrown unchanged.
+     */
+    private guard;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
     tabNew(url?: string): Promise<TabInfo>;
@@ -151,4 +158,7 @@ export declare class CdpExecutor implements Executor {
         tabId?: TabId;
         suggestedName?: string;
     }): Promise<DownloadResult>;
+    uploadFile(t: Target, files: string[], opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
 }