@mehmoodqureshi/chrome-mcp 0.9.6 → 0.9.7

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/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/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/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "MCP Extension for Chrome",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "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.7",
   "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",