@mehmoodqureshi/chrome-mcp 0.9.6 → 0.9.8

package/README.md

@@ -520,6 +520,31 @@ group/other-accessible. Windows has no such bits — `chmod` there only toggles
 read-only attribute — so the check is skipped and the token's confidentiality
 rests on the per-user ACL of `%USERPROFILE%\.chrome-mcp`.
 
+## Telemetry
+
+The chrome-mcp **server** sends anonymous usage statistics to PostHog, so the
+project can see how many installs are active, which versions and platforms are
+in use, and which tools fail most. A notice is printed the first time it runs.
+
+What is sent: a random install id (kept in `~/.chrome-mcp/telemetry.json`), the
+chrome-mcp version, OS, CPU architecture and Node major version, whether the
+session owns the bridge port or shares it, how many browsers are paired, and
+per-tool call and error **counts** with error codes — batched every 10 minutes.
+
+What is never sent: URLs, domains, tool arguments, page content, screenshots,
+cookies, profile names, tokens, file paths, or anything you type. Events are
+personless and GeoIP lookup is disabled.
+
+The **browser extension sends nothing** — it only ever talks to `127.0.0.1`.
+
+Turn it off with any of:
+
+```bash
+CHROME_MCP_TELEMETRY=0     # or false / off
+DO_NOT_TRACK=1
+--no-telemetry             # server flag
+```
+
 ## Develop
 
 ```

package/dist/shared/fill-form.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The sequencing behind a batched `fill_form`.
+ *
+ * Batching a form into ONE wire command removes a round-trip per field, but it
+ * also removes the router's per-command policy gate: the router evaluates once,
+ * before the first field, and then N writes happen with nothing re-checking
+ * where they land. That matters because a field's input handler — or a
+ * checkbox's click — can navigate the tab, and the values still to be written
+ * are exactly the sensitive ones (passwords, personal data). Typing them into
+ * whatever page replaced the allowlisted one would be a silent exfiltration.
+ *
+ * So the gate moves in here and runs per field, against the tab's CURRENT url,
+ * reproducing what N separate commands would have enforced. This lives in
+ * `shared/` for the same reason `evaluatePolicy` does: it is a security
+ * decision, so it belongs where both ends and the test suite can reach it
+ * (`extension/` is outside the tsconfig the tests compile).
+ */
+import type { FillFieldOp, FillFormWireResult, WirePolicy } from './protocol';
+/** What the caller must supply; everything chrome-specific stays outside. */
+export interface FillFormHooks {
+    /** The target tab's url right now — re-read before every field. */
+    currentUrl: () => Promise<string>;
+    /** The live wire policy, or null before a handshake has delivered one. */
+    policy: () => WirePolicy | null;
+    /** Perform one field write. Throws to fail the batch at this field. */
+    write: (op: FillFieldOp) => Promise<void>;
+    /** Map a thrown value to a wire error. */
+    toError: (err: unknown) => {
+        code: FillFormError['code'];
+        message: string;
+    };
+}
+type FillFormError = NonNullable<FillFormWireResult['error']>;
+/**
+ * Run `ops` in order, re-gating before each one, stopping at the first failure.
+ * Never throws: the failing field is reported in `error` and `filled` counts the
+ * writes that actually landed, so the server can tell the caller how far the
+ * form got rather than leaving it ambiguous.
+ */
+export declare function runFillFields(ops: readonly FillFieldOp[], hooks: FillFormHooks): Promise<FillFormWireResult>;
+export {};

package/dist/shared/fill-form.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * The sequencing behind a batched `fill_form`.
+ *
+ * Batching a form into ONE wire command removes a round-trip per field, but it
+ * also removes the router's per-command policy gate: the router evaluates once,
+ * before the first field, and then N writes happen with nothing re-checking
+ * where they land. That matters because a field's input handler — or a
+ * checkbox's click — can navigate the tab, and the values still to be written
+ * are exactly the sensitive ones (passwords, personal data). Typing them into
+ * whatever page replaced the allowlisted one would be a silent exfiltration.
+ *
+ * So the gate moves in here and runs per field, against the tab's CURRENT url,
+ * reproducing what N separate commands would have enforced. This lives in
+ * `shared/` for the same reason `evaluatePolicy` does: it is a security
+ * decision, so it belongs where both ends and the test suite can reach it
+ * (`extension/` is outside the tsconfig the tests compile).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFillFields = runFillFields;
+const policy_1 = require("./policy");
+/**
+ * Run `ops` in order, re-gating before each one, stopping at the first failure.
+ * Never throws: the failing field is reported in `error` and `filled` counts the
+ * writes that actually landed, so the server can tell the caller how far the
+ * form got rather than leaving it ambiguous.
+ */
+async function runFillFields(ops, hooks) {
+    const res = { filled: 0 };
+    for (const op of ops) {
+        try {
+            // Fails CLOSED, exactly as the router does: no policy means nothing runs.
+            const policy = hooks.policy();
+            if (!policy)
+                throw new PolicyStop('no policy is in force; refusing to fill');
+            const verdict = (0, policy_1.evaluatePolicy)(await hooks.currentUrl(), 'fill_form', policy);
+            if (!verdict.ok)
+                throw new PolicyStop(verdict.reason);
+            await hooks.write(op);
+        }
+        catch (err) {
+            res.error =
+                err instanceof PolicyStop
+                    ? { selector: op.selector, code: 'POLICY_DENIED', message: err.message }
+                    : { selector: op.selector, ...hooks.toError(err) };
+            return res;
+        }
+        res.filled++;
+    }
+    return res;
+}
+/** A refusal raised by the gate itself, kept distinct from a page-op failure. */
+class PolicyStop extends Error {
+}
+//# sourceMappingURL=fill-form.js.map

package/dist/shared/policy.js

@@ -42,6 +42,7 @@ const MUTATE_CONTENT = new Set([
     'press',
     'hover',
     'scroll',
+    'fill_form',
 ]);
 /** Navigation — URL-gated by the DESTINATION url, and mutation-gated. */
 const NAVIGATION = new Set([

package/dist/shared/protocol.d.ts

@@ -8,9 +8,10 @@
  *
  * 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.
+ * Helpers (extract_links / read_as_markdown) are NOT on the wire — they are
+ * composed server-side from these primitives. `download_file` is a wire method
+ * beyond the primitives, and so is `fill_form` (a batch of `type`/`click` writes
+ * in one round-trip; capability-gated, see `WIRE_CAP_FILL_FORM`).
  */
 /** Bumped on any breaking change to the frames below. */
 export declare const PROTOCOL_VERSION: 1;
@@ -39,12 +40,36 @@ export declare const CLOSE_SUPERSEDED: 4000;
  * every call. Without it, the server falls back to fetching the URL itself.
  */
 export declare const WIRE_CAP_TAB_URL: "tab-url";
+/**
+ * `fill-form`: this extension handles the `fill_form` wire method — every field
+ * of a form written in ONE round-trip. Without it the server fills field by
+ * field over `type`/`click`, which every extension build understands.
+ */
+export declare const WIRE_CAP_FILL_FORM: "fill-form";
+/** One field write inside a `fill_form` command: set a value, or click to toggle. */
+export interface FillFieldOp {
+    selector: string;
+    /** A string is value-set (cleared first); a boolean toggles via a click. */
+    value: string | boolean;
+}
+/**
+ * `fill_form` result. Ops run in order and stop at the first failure, so
+ * `filled` counts the fields that landed and `error` names the one that did not.
+ */
+export interface FillFormWireResult {
+    filled: number;
+    error?: {
+        selector: string;
+        code: ExecutorErrorCode;
+        message: string;
+    };
+}
 /**
  * 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' | 'snapshot' | 'select_option' | 'get_cookies' | 'storage' | 'eval' | 'wait_for' | 'download_file' | 'upload_file' | 'frames_list' | 'observers' | 'print_pdf' | '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' | 'frames_list' | 'observers' | 'print_pdf' | 'fill_form' | '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' | 'UPLOAD_FAILED' | 'FRAME_NOT_FOUND' | 'OBSERVERS_DISABLED' | 'UNKNOWN_METHOD';

package/dist/shared/protocol.js

@@ -9,12 +9,13 @@
  *
  * 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.
+ * Helpers (extract_links / read_as_markdown) are NOT on the wire — they are
+ * composed server-side from these primitives. `download_file` is a wire method
+ * beyond the primitives, and so is `fill_form` (a batch of `type`/`click` writes
+ * in one round-trip; capability-gated, see `WIRE_CAP_FILL_FORM`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WIRE_METHODS = exports.WIRE_CAP_TAB_URL = exports.CLOSE_SUPERSEDED = exports.CLOSE_UNAUTHORIZED = exports.BRIDGE_HOST = exports.DEFAULT_WS_PORT = exports.PROTOCOL_VERSION = void 0;
+exports.WIRE_METHODS = exports.WIRE_CAP_FILL_FORM = exports.WIRE_CAP_TAB_URL = 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;
 /**
@@ -41,6 +42,12 @@ exports.CLOSE_SUPERSEDED = 4000;
  * every call. Without it, the server falls back to fetching the URL itself.
  */
 exports.WIRE_CAP_TAB_URL = 'tab-url';
+/**
+ * `fill-form`: this extension handles the `fill_form` wire method — every field
+ * of a form written in ONE round-trip. Without it the server fills field by
+ * field over `type`/`click`, which every extension build understands.
+ */
+exports.WIRE_CAP_FILL_FORM = 'fill-form';
 /** Runtime list of every WireMethod, for boot-time drift assertions on both ends. */
 exports.WIRE_METHODS = [
     'tabs_list',
@@ -70,6 +77,7 @@ exports.WIRE_METHODS = [
     'frames_list',
     'observers',
     'print_pdf',
+    'fill_form',
     'ping_probe',
 ];
 //# sourceMappingURL=protocol.js.map

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

@@ -12,6 +12,10 @@
  */
 import type { WebSocket } from 'ws';
 import { type WireEvent, type WireMethod } from '../../shared/protocol';
+import { type ExecutorErrorCodeLocal } from '../executor/types';
+/** 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). */
+export declare function mapWireErrorCode(code: string): ExecutorErrorCodeLocal;
 export interface ConnectionDeps {
     ws: WebSocket;
     extId: string;
@@ -34,6 +38,8 @@ export declare class ExtensionConnection {
     private missedPongs;
     /** Whether this extension reports `tabUrl` and gates fail-closed. */
     private readonly reportsTabUrl;
+    /** Every capability the extension advertised in `hello`. */
+    private readonly caps;
     /** Last URL the ACTIVE tab reported, with the wall-clock it arrived. */
     private activeUrl;
     /** Last URL each explicitly-targeted tab reported, keyed by wire tab id. A
@@ -69,6 +75,8 @@ export declare class ExtensionConnection {
      * to forget what we knew, never to keep believing it.
      */
     private rememberActiveUrl;
+    /** Whether the extension advertised `cap` in its `hello`. */
+    hasCap(cap: string): boolean;
     /**
      * The active tab's last reported URL if it is younger than `maxAgeMs`, else
      * null — the caller then resolves it the slow way. Never returns a guess.

package/dist/src/bridge/connection.js

@@ -13,10 +13,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExtensionConnection = void 0;
+exports.mapWireErrorCode = mapWireErrorCode;
 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']);
+const LONG_METHODS = new Set(['screenshot', 'wait_for', 'navigate', 'download_file', 'fill_form']);
 function defaultTimeoutFor(method) {
     return LONG_METHODS.has(method) ? 60_000 : 30_000;
 }
@@ -51,6 +52,8 @@ class ExtensionConnection {
     missedPongs = 0;
     /** Whether this extension reports `tabUrl` and gates fail-closed. */
     reportsTabUrl;
+    /** Every capability the extension advertised in `hello`. */
+    caps;
     /** Last URL the ACTIVE tab reported, with the wall-clock it arrived. */
     activeUrl = null;
     /** Last URL each explicitly-targeted tab reported, keyed by wire tab id. A
@@ -64,7 +67,8 @@ class ExtensionConnection {
         this.ws = deps.ws;
         this.extId = deps.extId;
         this.sessionId = deps.sessionId;
-        this.reportsTabUrl = deps.caps?.includes(protocol_1.WIRE_CAP_TAB_URL) ?? false;
+        this.caps = new Set(deps.caps ?? []);
+        this.reportsTabUrl = this.caps.has(protocol_1.WIRE_CAP_TAB_URL);
         this.onEvent = deps.onEvent;
         this.onClose = deps.onClose;
         this.onLog = deps.onLog;
@@ -237,6 +241,10 @@ class ExtensionConnection {
             return; // already invalidated; re-caching would race
         this.activeUrl = frame.tabUrl ? { url: frame.tabUrl, at: Date.now() } : null;
     }
+    /** Whether the extension advertised `cap` in its `hello`. */
+    hasCap(cap) {
+        return this.caps.has(cap);
+    }
     /**
      * The active tab's last reported URL if it is younger than `maxAgeMs`, else
      * null — the caller then resolves it the slow way. Never returns a guess.

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

@@ -122,6 +122,9 @@ export declare class BridgeServer {
         timeoutMs?: number;
         profile?: string;
     }): Promise<unknown>;
+    /** Whether the browser paired as `profile` advertised capability `cap`. A peer
+     *  cannot see the hub's handshake, so it answers false (the conservative path). */
+    hasCap(profile: string | undefined, cap: string): boolean;
     /**
      * The active tab's URL for `profile` as last reported by the extension, if it
      * is younger than `maxAgeMs`. Null means "ask properly" — an extension too old

package/dist/src/bridge/server.js

@@ -296,6 +296,14 @@ class BridgeServer {
         }
         return conn.sendCommand(method, params, opts);
     }
+    /** Whether the browser paired as `profile` advertised capability `cap`. A peer
+     *  cannot see the hub's handshake, so it answers false (the conservative path). */
+    hasCap(profile, cap) {
+        if (this.hub)
+            return false;
+        const conn = this.conns.get(routeKey(profile));
+        return !!conn?.isOpen() && conn.hasCap(cap);
+    }
     /**
      * The active tab's URL for `profile` as last reported by the extension, if it
      * is younger than `maxAgeMs`. Null means "ask properly" — an extension too old

package/dist/src/cli.js

@@ -22,6 +22,7 @@ const workspace_1 = require("./bridge/workspace");
 const auth_1 = require("./bridge/auth");
 const server_2 = require("./mcp/server");
 const tools_1 = require("./mcp/tools");
+const telemetry_1 = require("./telemetry");
 const extension_install_1 = require("./extension-install");
 /** Hard deadline for clean shutdown before we force-exit (a stuck socket must not hang us). */
 const SHUTDOWN_DEADLINE_MS = 3000;
@@ -242,6 +243,13 @@ async function main() {
     };
     const port = await bridge.start();
     (0, tools_1.setProfileBridge)(bridge);
+    (0, telemetry_1.initTelemetry)({
+        dataDir,
+        version: version(),
+        disabledByFlag: cfg.noTelemetry,
+        log: (m) => (0, server_2.logErr)(m),
+        context: () => ({ role: bridge.role, browsers: bridge.connectedProfiles().length }),
+    });
     // Never includes the pairing token — only the resolved, non-secret config.
     (0, server_2.logDebug)(`resolved config: ${JSON.stringify({
         wsPort: port,
@@ -309,7 +317,9 @@ async function main() {
             return;
         shuttingDown = true;
         cleanup();
-        exitWithDeadline(Promise.allSettled([(0, server_2.stopMcpServer)(), bridge.stop()]));
+        // Telemetry first: its final summary reads the bridge's role and paired
+        // browsers, which bridge.stop() clears synchronously.
+        exitWithDeadline(Promise.allSettled([(0, telemetry_1.stopTelemetry)(), (0, server_2.stopMcpServer)(), bridge.stop()]));
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);

package/dist/src/config.d.ts

@@ -34,6 +34,8 @@ export interface CliConfig {
     showExtensionPath: boolean;
     /** `--persist-token`: reuse a stable on-disk token so the extension never re-pairs. */
     persistToken: boolean;
+    /** `--no-telemetry`: send no anonymous usage statistics (see src/telemetry.ts). */
+    noTelemetry: boolean;
     /**
      * `--tools`: advertise only these tools. `undefined` = the whole catalog.
      * Names are validated against the catalog by `setToolAllowlist` at startup —

package/dist/src/config.js

@@ -78,6 +78,7 @@ function parseArgs(argv) {
     let headless = false;
     let printPairing = false;
     let persistToken = false;
+    let noTelemetry = false;
     let showHelp = false;
     let showVersion = false;
     let showExtensionPath = false;
@@ -178,6 +179,9 @@ function parseArgs(argv) {
             case '--persist-token':
                 persistToken = true;
                 break;
+            case '--no-telemetry':
+                noTelemetry = true;
+                break;
             case '--tools':
                 toolsFlagSeen = true;
                 for (const name of splitList(requireValue(argv[++i], '--tools')))
@@ -234,6 +238,7 @@ function parseArgs(argv) {
         headless,
         printPairing,
         persistToken,
+        noTelemetry,
         showHelp,
         showVersion,
         showExtensionPath,
@@ -309,6 +314,10 @@ Connection:
   --persist-token        Reuse a stable on-disk token across restarts so the
                          extension never has to re-pair (default: fresh per boot).
                          CHROME_MCP_TOKEN env, if set, pins the token explicitly.
+  --no-telemetry         Send no anonymous usage statistics. Same as
+                         CHROME_MCP_TELEMETRY=0 or DO_NOT_TRACK=1. Only counts are
+                         ever sent (version, OS, tool calls, error codes) — never
+                         URLs, page content or arguments.
 
 Backend:
   This build is EXTENSION-ONLY — it drives ONLY your real Chrome via the paired

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

@@ -7,7 +7,7 @@
  * method-specific arguments travel in `params`. Results are trusted shapes
  * produced by the extension router (validated there).
  */
-import { type ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type FrameInfo, type FrameOpts, type ObserverArgs, type ObserverReadResult, type PdfResult, type KeyModifier, type MouseButton, type NavResult, type ScreenshotEncoding, type ScreenshotResult, type SnapshotLocator, type SnapshotResult, type StorageOp, type StorageResult, type TabId, type TabInfo, type Target, type WaitResult, type WaitUntil } from './types';
+import { type ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type FillFieldOp, type FrameInfo, type FrameOpts, type ObserverArgs, type ObserverReadResult, type PdfResult, type KeyModifier, type MouseButton, type NavResult, type ScreenshotEncoding, type ScreenshotResult, type SnapshotLocator, type SnapshotResult, type StorageOp, type StorageResult, type TabId, type TabInfo, type Target, type WaitResult, type WaitUntil } from './types';
 import type { BridgeServer } from '../bridge/server';
 export declare class ExtensionExecutor implements Executor {
     private readonly bridge;
@@ -69,6 +69,11 @@ export declare class ExtensionExecutor implements Executor {
     fill(t: Target, value: string, opts?: {
         tabId?: TabId;
     } & FrameOpts): Promise<ActionOk>;
+    fillFields(fields: FillFieldOp[], opts?: {
+        tabId?: TabId;
+    } & FrameOpts): Promise<{
+        filled: number;
+    } | null>;
     press(key: string, opts?: {
         tabId?: TabId;
         modifiers?: KeyModifier[];

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

@@ -11,6 +11,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExtensionExecutor = void 0;
 const types_1 = require("./types");
+const protocol_1 = require("../../shared/protocol");
+const connection_1 = require("../bridge/connection");
 const workspace_1 = require("../bridge/workspace");
 /**
  * How long a reported active-tab URL stays usable for the policy gate.
@@ -143,6 +145,19 @@ class ExtensionExecutor {
         // No dedicated wire method: a cleared insertText is the fill primitive.
         return (await this.send('type', { ...targetParams(t), ...frameParams(opts), text: value, clear: true, keyEvents: false }, { tabId: opts?.tabId }));
     }
+    async fillFields(fields, opts) {
+        // An extension that predates the op never advertised it: let the caller go field by field.
+        if (!this.bridge.hasCap(this.activeProfile(), protocol_1.WIRE_CAP_FILL_FORM))
+            return null;
+        const res = (await this.send('fill_form', { ops: fields, ...frameParams(opts) }, { tabId: opts?.tabId }));
+        if (res.error) {
+            // Say how far the batch got: the fields before this one DID land, and a
+            // blind retry of the whole form would write them a second time.
+            const where = `field ${res.filled + 1} of ${fields.length} (${res.error.selector}) failed after ${res.filled} filled`;
+            throw new types_1.ExecutorError((0, connection_1.mapWireErrorCode)(res.error.code), `${where}: ${res.error.message}`);
+        }
+        return { filled: res.filled };
+    }
     async press(key, opts) {
         return (await this.send('press', { key, modifiers: opts?.modifiers }, { tabId: opts?.tabId }));
     }

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

@@ -10,7 +10,8 @@
  * `mcp/helpers.ts` from these primitives; only `download` is privileged.
  */
 import type { ObserverReadResult, DialogPolicy } from '../../shared/observers';
-export type { ObserverReadResult, DialogPolicy };
+import type { FillFieldOp } from '../../shared/protocol';
+export type { ObserverReadResult, DialogPolicy, FillFieldOp };
 export type BackendKind = 'extension' | 'cdp';
 export type WaitUntil = 'load' | 'domcontentloaded' | 'networkidle';
 export type KeyModifier = 'Alt' | 'Control' | 'Meta' | 'Shift';
@@ -334,6 +335,17 @@ export interface Executor {
         gone?: boolean;
         timeoutMs?: number;
     } & FrameOpts): Promise<WaitResult>;
+    /**
+     * Write several fields in ONE round-trip (string = value-set like `fill`,
+     * boolean = toggle via click), in order, throwing the first field's failure.
+     * Resolves null when the live backend cannot batch (e.g. an extension build
+     * older than the op) — the caller then falls back to `fill`/`click` per field.
+     */
+    fillFields?(fields: FillFieldOp[], opts?: {
+        tabId?: TabId;
+    } & FrameOpts): Promise<{
+        filled: number;
+    } | null>;
     /** Every frame of a tab that the extension can inject into, with its URL. */
     framesList?(opts?: {
         tabId?: TabId;

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

@@ -1,7 +1,8 @@
 /**
  * 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.
+ * `read_as_markdown` read via primitives; `fill_form` batches its field writes
+ * when the backend can (else sequences fill+click).
  * (Only `download_file` is privileged and lives on the executor.)
  */
 import type { Executor, FrameOpts } from '../executor/types';
@@ -32,7 +33,12 @@ export declare function readAsMarkdown(ex: Executor, args: {
     selector?: string;
     tabId?: string;
 } & FrameOpts): Promise<string>;
-/** Fill a set of fields (keyed by selector) and optionally submit. */
+/**
+ * Fill a set of fields (keyed by selector) and optionally submit. All writes go
+ * out as ONE executor call when the backend can batch them; otherwise (older
+ * extension, CDP) they fall back to one fill/click per field. Either way the
+ * first failing field throws, and submit is a separate click after the fills.
+ */
 export declare function fillForm(ex: Executor, args: {
     fields: Record<string, string | boolean>;
     submitSelector?: string;

package/dist/src/mcp/helpers.js

@@ -2,7 +2,8 @@
 /**
  * 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.
+ * `read_as_markdown` read via primitives; `fill_form` batches its field writes
+ * when the backend can (else sequences fill+click).
  * (Only `download_file` is privileged and lives on the executor.)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -80,20 +81,29 @@ async function readAsMarkdown(ex, args) {
     });
     return (0, markdown_extract_1.htmlToMarkdown)(html);
 }
-/** Fill a set of fields (keyed by selector) and optionally submit. */
+/**
+ * Fill a set of fields (keyed by selector) and optionally submit. All writes go
+ * out as ONE executor call when the backend can batch them; otherwise (older
+ * extension, CDP) they fall back to one fill/click per field. Either way the
+ * first failing field throws, and submit is a separate click after the fills.
+ */
 async function fillForm(ex, args) {
     const opts = { tabId: args.tabId, frameId: args.frameId, allFrames: args.allFrames };
-    let filled = 0;
-    for (const [selector, value] of Object.entries(args.fields)) {
-        const target = { selector };
-        if (typeof value === 'boolean') {
-            // Checkbox/radio: a click toggles it.
-            await ex.click(target, opts);
-        }
-        else {
-            await ex.fill(target, value, opts);
+    const ops = Object.entries(args.fields).map(([selector, value]) => ({ selector, value }));
+    const batched = ops.length > 0 && ex.fillFields ? await ex.fillFields(ops, opts) : null;
+    let filled = batched?.filled ?? 0;
+    if (!batched) {
+        for (const { selector, value } of ops) {
+            const target = { selector };
+            if (typeof value === 'boolean') {
+                // Checkbox/radio: a click toggles it.
+                await ex.click(target, opts);
+            }
+            else {
+                await ex.fill(target, value, opts);
+            }
+            filled++;
         }
-        filled++;
     }
     let submitted = false;
     if (args.submitSelector) {

package/dist/src/mcp/tools.js

@@ -38,6 +38,7 @@ const auth_wall_1 = require("../../shared/auth-wall");
 const audit_1 = require("./audit");
 const log_1 = require("./log");
 const tasks_1 = require("../bridge/tasks");
+const telemetry_1 = require("../telemetry");
 const config_1 = require("../config");
 const workspace_1 = require("../bridge/workspace");
 const validators_1 = require("./validators");
@@ -1075,6 +1076,8 @@ function summarizeArgs(rawArgs) {
  */
 function recordHistory(tool, rawArgs, ok, extra = {}) {
     const a = extra.audit ?? {};
+    // Counts only — the tool name and error code, never the args or URL below.
+    (0, telemetry_1.noteToolCall)(tool, ok, extra.error);
     (0, workspace_1.appendHistory)({
         ts: new Date().toISOString(),
         tool,

package/dist/src/telemetry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * src/telemetry.ts — anonymous usage statistics from the chrome-mcp SERVER.
+ *
+ * What it sends, to PostHog: a random per-install id, the chrome-mcp version,
+ * OS, CPU architecture and Node major version, whether this session owns the
+ * port or shares it, how many browsers are paired, and per-tool call and error
+ * COUNTS. Never URLs, domains, tool arguments, page content, profile names,
+ * tokens, file paths, or anything typed. Events are marked personless and ask
+ * PostHog not to geolocate them.
+ *
+ * The browser extension sends nothing; this lives only in the npm server.
+ *
+ * On by default with a one-time notice on first run. Off with
+ * CHROME_MCP_TELEMETRY=0 (or false/off), DO_NOT_TRACK=1, or --no-telemetry.
+ * Every failure is swallowed: telemetry can never break or slow a tool call.
+ */
+/** PostHog project key. Public by design: it can only WRITE events, never read them. */
+export declare const POSTHOG_KEY = "phc_CG5QX5JEkRokfUN87rZQnPa3URdLWePCZnfqW6MCyCdU";
+export declare const POSTHOG_HOST = "https://us.i.posthog.com";
+export declare const TELEMETRY_NOTICE: string;
+interface Event {
+    event: string;
+    distinct_id: string;
+    timestamp: string;
+    properties: Record<string, unknown>;
+}
+export interface TelemetryOptions {
+    dataDir: string;
+    version: string;
+    /** --no-telemetry */
+    disabledByFlag?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** Override the project key (tests, forks). Empty = telemetry off. */
+    key?: string;
+    log?: (message: string) => void;
+    /** Test seam: replaces the HTTP POST. */
+    send?: (events: Event[]) => Promise<void>;
+    /** Live context added to each summary (role, paired browsers). */
+    context?: () => Record<string, unknown>;
+}
+/** Whether the user has turned telemetry off, by env or flag. */
+export declare function telemetryDisabled(env: NodeJS.ProcessEnv, disabledByFlag?: boolean): boolean;
+/** Pull the `[CODE]` prefix off a tool error message, if any. */
+export declare function errorCodeOf(message: string | undefined): string;
+/** Start telemetry for this server process, unless turned off or unconfigured. */
+export declare function initTelemetry(opts: TelemetryOptions): boolean;
+/** Count one tool call. A no-op when telemetry is off. */
+export declare function noteToolCall(tool: string, ok: boolean, error?: string): void;
+/** Flush and send session_ended. Safe to call when telemetry is off. */
+export declare function stopTelemetry(): Promise<void>;
+/** Test seam: forget the active instance. */
+export declare function resetTelemetryForTesting(): void;
+export {};

package/dist/src/telemetry.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * src/telemetry.ts — anonymous usage statistics from the chrome-mcp SERVER.
+ *
+ * What it sends, to PostHog: a random per-install id, the chrome-mcp version,
+ * OS, CPU architecture and Node major version, whether this session owns the
+ * port or shares it, how many browsers are paired, and per-tool call and error
+ * COUNTS. Never URLs, domains, tool arguments, page content, profile names,
+ * tokens, file paths, or anything typed. Events are marked personless and ask
+ * PostHog not to geolocate them.
+ *
+ * The browser extension sends nothing; this lives only in the npm server.
+ *
+ * On by default with a one-time notice on first run. Off with
+ * CHROME_MCP_TELEMETRY=0 (or false/off), DO_NOT_TRACK=1, or --no-telemetry.
+ * Every failure is swallowed: telemetry can never break or slow a tool call.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEMETRY_NOTICE = exports.POSTHOG_HOST = exports.POSTHOG_KEY = void 0;
+exports.telemetryDisabled = telemetryDisabled;
+exports.errorCodeOf = errorCodeOf;
+exports.initTelemetry = initTelemetry;
+exports.noteToolCall = noteToolCall;
+exports.stopTelemetry = stopTelemetry;
+exports.resetTelemetryForTesting = resetTelemetryForTesting;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** PostHog project key. Public by design: it can only WRITE events, never read them. */
+exports.POSTHOG_KEY = 'phc_CG5QX5JEkRokfUN87rZQnPa3URdLWePCZnfqW6MCyCdU';
+exports.POSTHOG_HOST = 'https://us.i.posthog.com';
+/** How often the aggregated counts are sent while a session runs. */
+const FLUSH_INTERVAL_MS = 10 * 60_000;
+/** A send never holds up the process longer than this. */
+const SEND_TIMEOUT_MS = 3_000;
+const STATE_FILE = 'telemetry.json';
+exports.TELEMETRY_NOTICE = 'chrome-mcp collects anonymous usage statistics (version, OS, tool call and error counts; never URLs, ' +
+    'page content or arguments) to see how it is used. Turn it off with CHROME_MCP_TELEMETRY=0 or DO_NOT_TRACK=1. ' +
+    'Details: https://github.com/Mehmoodqureshi/chrome-mcp#telemetry';
+/** Whether the user has turned telemetry off, by env or flag. */
+function telemetryDisabled(env, disabledByFlag = false) {
+    if (disabledByFlag)
+        return true;
+    const own = (env.CHROME_MCP_TELEMETRY ?? '').trim().toLowerCase();
+    if (['0', 'false', 'off', 'no'].includes(own))
+        return true;
+    const dnt = (env.DO_NOT_TRACK ?? '').trim().toLowerCase();
+    return dnt !== '' && dnt !== '0' && dnt !== 'false';
+}
+/** Pull the `[CODE]` prefix off a tool error message, if any. */
+function errorCodeOf(message) {
+    const m = /^\[([A-Z_]+)\]/.exec(message ?? '');
+    return m ? m[1] : 'OTHER';
+}
+class Telemetry {
+    opts;
+    installId;
+    calls = new Map();
+    errorCodes = new Map();
+    timer = null;
+    base;
+    /** Sends still on the wire, so a quick exit doesn't cut session_started off. */
+    inflight = new Set();
+    constructor(opts) {
+        this.opts = opts;
+        this.installId = this.loadInstallId();
+        this.base = {
+            version: opts.version,
+            os: (0, node_os_1.platform)(),
+            arch: (0, node_os_1.arch)(),
+            node: process.versions.node.split('.')[0],
+            // Anonymous: no person profile, no GeoIP lookup from the request IP.
+            $process_person_profile: false,
+            $geoip_disable: true,
+        };
+    }
+    start() {
+        void this.capture('session_started', this.opts.context?.() ?? {});
+        this.timer = setInterval(() => void this.flush(), FLUSH_INTERVAL_MS);
+        this.timer.unref();
+    }
+    noteCall(tool, ok, error) {
+        const c = this.calls.get(tool) ?? { calls: 0, errors: 0 };
+        c.calls++;
+        if (!ok) {
+            c.errors++;
+            const code = errorCodeOf(error);
+            this.errorCodes.set(code, (this.errorCodes.get(code) ?? 0) + 1);
+        }
+        this.calls.set(tool, c);
+    }
+    /** Send the counts gathered since the last flush (skipped when idle). */
+    async flush() {
+        const summary = this.takeSummary();
+        if (summary)
+            await this.send([summary]);
+    }
+    /** The counts since the last summary as an event, resetting them; null when idle. */
+    takeSummary() {
+        if (this.calls.size === 0)
+            return null;
+        const tools = Object.fromEntries(this.calls);
+        const errors = Object.fromEntries(this.errorCodes);
+        let total = 0;
+        let failed = 0;
+        for (const c of this.calls.values()) {
+            total += c.calls;
+            failed += c.errors;
+        }
+        this.calls = new Map();
+        this.errorCodes = new Map();
+        return this.event('usage_summary', { ...(this.opts.context?.() ?? {}), calls: total, errors: failed, tools, error_codes: errors });
+    }
+    /** Last summary and session_ended in ONE request, so both fit the shutdown deadline. */
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        const summary = this.takeSummary();
+        const final = this.send([...(summary ? [summary] : []), this.event('session_ended', {})]);
+        // Also wait for anything already sent (session_started on a short session).
+        await Promise.allSettled([...this.inflight, final]);
+    }
+    capture(event, props) {
+        return this.send([this.event(event, props)]);
+    }
+    event(event, props) {
+        return {
+            event,
+            distinct_id: this.installId,
+            timestamp: new Date().toISOString(),
+            properties: { ...this.base, ...props },
+        };
+    }
+    send(batch) {
+        const p = (async () => {
+            try {
+                await (this.opts.send ?? ((b) => this.post(b)))(batch);
+            }
+            catch {
+                /* offline, blocked, or PostHog down — never matters to the user */
+            }
+        })();
+        this.inflight.add(p);
+        void p.finally(() => this.inflight.delete(p));
+        return p;
+    }
+    async post(batch) {
+        await fetch(`${exports.POSTHOG_HOST}/batch/`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ api_key: this.opts.key, batch }),
+            signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+        });
+    }
+    /** The random install id, created (with the first-run notice) on first use. */
+    loadInstallId() {
+        const path = (0, node_path_1.join)(this.opts.dataDir, STATE_FILE);
+        try {
+            if ((0, node_fs_1.existsSync)(path)) {
+                const saved = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+                if (typeof saved.installId === 'string' && saved.installId.length > 0)
+                    return saved.installId;
+            }
+        }
+        catch {
+            /* unreadable: start over with a new id */
+        }
+        const installId = (0, node_crypto_1.randomUUID)();
+        this.opts.log?.(exports.TELEMETRY_NOTICE);
+        try {
+            const tmp = `${path}.tmp`;
+            (0, node_fs_1.writeFileSync)(tmp, JSON.stringify({ installId, noticeShownAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+            (0, node_fs_1.renameSync)(tmp, path);
+        }
+        catch {
+            /* read-only data dir: a new id (and notice) next boot is harmless */
+        }
+        return installId;
+    }
+}
+let active = null;
+/** Start telemetry for this server process, unless turned off or unconfigured. */
+function initTelemetry(opts) {
+    const key = opts.key ?? exports.POSTHOG_KEY;
+    if (!key || telemetryDisabled(opts.env ?? process.env, opts.disabledByFlag))
+        return false;
+    active = new Telemetry({ ...opts, key });
+    active.start();
+    return true;
+}
+/** Count one tool call. A no-op when telemetry is off. */
+function noteToolCall(tool, ok, error) {
+    active?.noteCall(tool, ok, error);
+}
+/** Flush and send session_ended. Safe to call when telemetry is off. */
+async function stopTelemetry() {
+    const t = active;
+    active = null;
+    await t?.stop();
+}
+/** Test seam: forget the active instance. */
+function resetTelemetryForTesting() {
+    active = null;
+}
+//# sourceMappingURL=telemetry.js.map

package/extension-dist/background.js

@@ -3,6 +3,7 @@
   // shared/protocol.ts
   var PROTOCOL_VERSION = 1;
   var WIRE_CAP_TAB_URL = "tab-url";
+  var WIRE_CAP_FILL_FORM = "fill-form";
   var WIRE_METHODS = [
     "tabs_list",
     "tab_select",
@@ -31,6 +32,7 @@
     "frames_list",
     "observers",
     "print_pdf",
+    "fill_form",
     "ping_probe"
   ];
 
@@ -72,7 +74,7 @@
           // This build gates fail-closed and reports tab URLs on results, so the
           // server may skip its pre-flight tabs_list. An older build omits this and
           // the server keeps fetching the URL itself.
-          caps: [WIRE_CAP_TAB_URL]
+          caps: [WIRE_CAP_TAB_URL, WIRE_CAP_FILL_FORM]
         };
         ws2.send(JSON.stringify(hello));
       };
@@ -146,7 +148,8 @@
     "type",
     "press",
     "hover",
-    "scroll"
+    "scroll",
+    "fill_form"
   ]);
   var NAVIGATION = /* @__PURE__ */ new Set([
     "navigate",
@@ -236,6 +239,27 @@
     return `Blocked: "${method}" can't run on ${host} because it isn't on this browser tool's allowed-sites list. This is a safety limit (the tool drives your real, logged-in browser, so it only touches sites you've approved) \u2014 not an error. ${allowedLine} To allow ${host}, add it to the chrome-mcp settings as: --allow-domain "${host}" (or "*.${host}" to include subdomains), then restart/reconnect. To allow every site (less safe), use --unsafe-all-domains.`;
   }
 
+  // shared/fill-form.ts
+  async function runFillFields(ops, hooks) {
+    const res = { filled: 0 };
+    for (const op of ops) {
+      try {
+        const policy = hooks.policy();
+        if (!policy) throw new PolicyStop("no policy is in force; refusing to fill");
+        const verdict = evaluatePolicy(await hooks.currentUrl(), "fill_form", policy);
+        if (!verdict.ok) throw new PolicyStop(verdict.reason);
+        await hooks.write(op);
+      } catch (err) {
+        res.error = err instanceof PolicyStop ? { selector: op.selector, code: "POLICY_DENIED", message: err.message } : { selector: op.selector, ...hooks.toError(err) };
+        return res;
+      }
+      res.filled++;
+    }
+    return res;
+  }
+  var PolicyStop = class extends Error {
+  };
+
   // shared/download.ts
   var MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
   var DANGEROUS_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -1225,7 +1249,8 @@
     "ping_probe",
     "frames_list",
     "observers",
-    "print_pdf"
+    "print_pdf",
+    "fill_form"
   ]);
   var ChromeExecutor = class {
     /**
@@ -1495,6 +1520,34 @@
           if (!out.found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           return { ok: true, frameId: out.frameId };
         }
+        case "fill_form": {
+          const id = await targetTab2(cmd);
+          const raw = Array.isArray(cmd.params.ops) ? cmd.params.ops : [];
+          const ops = raw.map((f) => ({
+            selector: String(f.selector ?? ""),
+            value: typeof f.value === "boolean" ? f.value : String(f.value ?? "")
+          }));
+          return runFillFields(ops, {
+            currentUrl: () => observedTabUrl(cmd, id),
+            policy: () => this.getPolicy(),
+            // Frame ids are re-probed per field too: an iframe that navigates
+            // mid-batch must not keep a grant the policy would no longer give it.
+            write: async (op) => {
+              const out = await execOp(
+                id,
+                withWait(
+                  typeof op.value === "boolean" ? { op: "click", selector: op.selector } : { op: "type", selector: op.selector, text: op.value, clear: true }
+                ),
+                await this.frames(cmd, id)
+              );
+              if (!out.found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${op.selector}`);
+            },
+            toError: (err) => ({
+              code: err instanceof CmdError ? err.code : "CDP_ERROR",
+              message: err instanceof Error ? err.message : String(err)
+            })
+          });
+        }
         case "press": {
           const id = await targetTab2(cmd);
           const key = String(cmd.params.key ?? "");

package/extension-dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "MCP Extension for Chrome",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Lets a local chrome-mcp server drive this browser. Pair it with the server's handshake token.",
   "homepage_url": "https://chrome-mcp-omega.vercel.app",
   "minimum_chrome_version": "116",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Drive your real Chrome browser over MCP — real logins, real cookies. A stdio MCP server (CLI) plus an MV3 extension, driving Chrome via chrome.scripting/chrome.tabs. Multi-tab batch automation, accessibility snapshots, deny-all security by default.",
   "author": "Mehmood Ur Rehman Qureshi",
   "license": "MIT",