chrome-devtools-mcp 0.14.0 → 0.15.1

package/README.md

@@ -27,6 +27,22 @@ allowing them to inspect, debug, and modify any data in the browser or DevTools.
 Avoid sharing sensitive or personal information that you don't want to share with
 MCP clients.
 
+## **Usage statistics**
+
+Google collects usage statistics (such as tool invocation success rates, latency, and environment information) to improve the reliability and performance of Chrome DevTools MCP.
+
+Data collection is **enabled by default**. You can opt-out by passing the `--no-usage-statistics` flag when starting the server:
+
+```json
+"args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]
+```
+
+Google handles this data in accordance with the [Google Privacy Policy](https://policies.google.com/privacy).
+
+Google's collection of usage statistics for Chrome DevTools MCP is independent from the Chrome browser's usage statistics. Opting out of Chrome metrics does not automatically opt you out of this tool, and vice-versa.
+
+Collection is disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env variables are set.
+
 ## Requirements
 
 - [Node.js](https://nodejs.org/) v20.19 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.
@@ -450,6 +466,11 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `true`
 
+- **`--usageStatistics`/ `--usage-statistics`**
+  Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics. Disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env variables are set.
+  - **Type:** boolean
+  - **Default:** `true`
+
 <!-- END AUTO GENERATED OPTIONS -->
 
 Pass them via the `args` property in the JSON configuration. For example:

package/build/src/McpContext.js

@@ -60,6 +60,7 @@ export class McpContext {
     #geolocationMap = new WeakMap();
     #viewportMap = new WeakMap();
     #userAgentMap = new WeakMap();
+    #colorSchemeMap = new WeakMap();
     #dialog;
     #pageIdMap = new WeakMap();
     #nextPageId = 1;
@@ -249,6 +250,19 @@ export class McpContext {
         const page = this.getSelectedPage();
         return this.#userAgentMap.get(page) ?? null;
     }
+    setColorScheme(scheme) {
+        const page = this.getSelectedPage();
+        if (scheme === null) {
+            this.#colorSchemeMap.delete(page);
+        }
+        else {
+            this.#colorSchemeMap.set(page, scheme);
+        }
+    }
+    getColorScheme() {
+        const page = this.getSelectedPage();
+        return this.#colorSchemeMap.get(page) ?? null;
+    }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
     }
@@ -537,12 +551,12 @@ export class McpContext {
     getWaitForHelper(page, cpuMultiplier, networkMultiplier) {
         return new WaitForHelper(page, cpuMultiplier, networkMultiplier);
     }
-    waitForEventsAfterAction(action) {
+    waitForEventsAfterAction(action, options) {
         const page = this.getSelectedPage();
         const cpuMultiplier = this.getCpuThrottlingRate();
         const networkMultiplier = getNetworkMultiplierFromString(this.getNetworkConditions());
         const waitForHelper = this.getWaitForHelper(page, cpuMultiplier, networkMultiplier);
-        return waitForHelper.waitForEventsAfterAction(action);
+        return waitForHelper.waitForEventsAfterAction(action, options);
     }
     getNetworkRequestStableId(request) {
         return this.#networkCollector.getIdForResource(request);

package/build/src/McpResponse.js

@@ -308,6 +308,12 @@ export class McpResponse {
             response.push(`Emulating: ${cpuThrottlingRate}x slowdown`);
             structuredContent.cpuThrottlingRate = cpuThrottlingRate;
         }
+        const colorScheme = context.getColorScheme();
+        if (colorScheme) {
+            response.push(`## Color Scheme emulation`);
+            response.push(`Emulating: ${colorScheme}`);
+            structuredContent.colorScheme = colorScheme;
+        }
         const dialog = context.getDialog();
         if (dialog) {
             const defaultValueIfNeeded = dialog.type() === 'prompt'

package/build/src/WaitForHelper.js

@@ -103,12 +103,12 @@ export class WaitForHelper {
             });
         });
     }
-    async waitForEventsAfterAction(action) {
+    async waitForEventsAfterAction(action, options) {
         const navigationFinished = this.waitForNavigationStarted()
             .then(navigationStated => {
             if (navigationStated) {
                 return this.#page.waitForNavigation({
-                    timeout: this.#navigationTimeout,
+                    timeout: options?.timeout ?? this.#navigationTimeout,
                     signal: this.#abortController.signal,
                 });
             }

package/build/src/cli.js

@@ -190,10 +190,23 @@ export const cliOptions = {
     },
     usageStatistics: {
         type: 'boolean',
-        // Marked as `false` until the feature is ready to be enabled by default.
-        default: false,
+        default: true,
+        describe: 'Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics. Disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env variables are set.',
+    },
+    clearcutEndpoint: {
+        type: 'string',
+        hidden: true,
+        describe: 'Endpoint for Clearcut telemetry.',
+    },
+    clearcutForceFlushIntervalMs: {
+        type: 'number',
         hidden: true,
-        describe: 'Set to false to opt-out of usage statistics collection.',
+        describe: 'Force flush interval in milliseconds (for testing).',
+    },
+    clearcutIncludePidHeader: {
+        type: 'boolean',
+        hidden: true,
+        describe: 'Include watchdog PID in Clearcut request headers (for testing).',
     },
 };
 export function parseArguments(version, argv = process.argv) {
@@ -260,6 +273,10 @@ export function parseArguments(version, argv = process.argv) {
             '$0 --auto-connect --channel=canary',
             'Connect to a canary Chrome instance (Chrome 144+) running instead of launching a new instance',
         ],
+        [
+            '$0 --no-usage-statistics',
+            'Do not send usage statistics https://github.com/ChromeDevTools/chrome-devtools-mcp#usage-statistics.',
+        ],
     ]);
     return yargsInstance
         .wrap(Math.min(120, yargsInstance.terminalWidth()))

package/build/src/main.js

@@ -20,15 +20,23 @@ import { ToolCategory } from './tools/categories.js';
 import { tools } from './tools/tools.js';
 // If moved update release-please config
 // x-release-please-start-version
-const VERSION = '0.14.0';
+const VERSION = '0.15.1';
 // x-release-please-end
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+if (process.env['CI'] ||
+    process.env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS']) {
+    console.error("turning off usage statistics. process.env['CI'] || process.env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS'] is set.");
+    args.usageStatistics = false;
+}
 let clearcutLogger;
 if (args.usageStatistics) {
     clearcutLogger = new ClearcutLogger({
         logFile: args.logFile,
         appVersion: VERSION,
+        clearcutEndpoint: args.clearcutEndpoint,
+        clearcutForceFlushIntervalMs: args.clearcutForceFlushIntervalMs,
+        clearcutIncludePidHeader: args.clearcutIncludePidHeader,
     });
 }
 process.on('unhandledRejection', (reason, promise) => {

package/build/src/telemetry/clearcut-logger.js

@@ -33,6 +33,9 @@ export class ClearcutLogger {
                     appVersion: options.appVersion,
                     osType: detectOsType(),
                     logFile: options.logFile,
+                    clearcutEndpoint: options.clearcutEndpoint,
+                    clearcutForceFlushIntervalMs: options.clearcutForceFlushIntervalMs,
+                    clearcutIncludePidHeader: options.clearcutIncludePidHeader,
                 });
     }
     async logToolInvocation(args) {

package/build/src/telemetry/watchdog/clearcut-sender.js

@@ -5,44 +5,197 @@
  */
 import crypto from 'node:crypto';
 import { logger } from '../../logger.js';
+const MAX_BUFFER_SIZE = 1000;
+const DEFAULT_CLEARCUT_ENDPOINT = 'https://play.googleapis.com/log?format=json_proto';
+const DEFAULT_FLUSH_INTERVAL_MS = 15 * 60 * 1000;
+const LOG_SOURCE = 2839;
+const CLIENT_TYPE = 47;
+const MIN_RATE_LIMIT_WAIT_MS = 30_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const SHUTDOWN_TIMEOUT_MS = 5_000;
 const SESSION_ROTATION_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export class ClearcutSender {
     #appVersion;
     #osType;
+    #clearcutEndpoint;
+    #flushIntervalMs;
+    #includePidHeader;
     #sessionId;
     #sessionCreated;
-    constructor(appVersion, osType) {
-        this.#appVersion = appVersion;
-        this.#osType = osType;
+    #buffer = [];
+    #flushTimer = null;
+    #isFlushing = false;
+    #timerStarted = false;
+    constructor(config) {
+        this.#appVersion = config.appVersion;
+        this.#osType = config.osType;
+        this.#clearcutEndpoint =
+            config.clearcutEndpoint ?? DEFAULT_CLEARCUT_ENDPOINT;
+        this.#flushIntervalMs =
+            config.forceFlushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+        this.#includePidHeader = config.includePidHeader ?? false;
         this.#sessionId = crypto.randomUUID();
         this.#sessionCreated = Date.now();
     }
-    async send(event) {
-        this.#rotateSessionIfNeeded();
-        const enrichedEvent = this.#enrichEvent(event);
-        this.transport(enrichedEvent);
-    }
-    transport(event) {
-        logger('Telemetry event', JSON.stringify(event, null, 2));
-    }
-    async sendShutdownEvent() {
-        const shutdownEvent = {
-            server_shutdown: {},
-        };
-        await this.send(shutdownEvent);
-    }
-    #rotateSessionIfNeeded() {
+    enqueueEvent(event) {
         if (Date.now() - this.#sessionCreated > SESSION_ROTATION_INTERVAL_MS) {
             this.#sessionId = crypto.randomUUID();
             this.#sessionCreated = Date.now();
         }
-    }
-    #enrichEvent(event) {
-        return {
+        logger('Enqueing telemetry event', JSON.stringify(event, null, 2));
+        this.#addToBuffer({
             ...event,
             session_id: this.#sessionId,
             app_version: this.#appVersion,
             os_type: this.#osType,
+        });
+        if (!this.#timerStarted) {
+            this.#timerStarted = true;
+            this.#scheduleFlush(this.#flushIntervalMs);
+        }
+    }
+    async sendShutdownEvent() {
+        if (this.#flushTimer) {
+            clearTimeout(this.#flushTimer);
+            this.#flushTimer = null;
+        }
+        const shutdownEvent = {
+            server_shutdown: {},
         };
+        this.enqueueEvent(shutdownEvent);
+        try {
+            await Promise.race([
+                this.#finalFlush(),
+                new Promise(resolve => setTimeout(resolve, SHUTDOWN_TIMEOUT_MS)),
+            ]);
+            logger('Final flush completed');
+        }
+        catch (error) {
+            logger('Final flush failed:', error);
+        }
+    }
+    async #flush() {
+        if (this.#isFlushing) {
+            return;
+        }
+        if (this.#buffer.length === 0) {
+            this.#scheduleFlush(this.#flushIntervalMs);
+            return;
+        }
+        this.#isFlushing = true;
+        let nextDelayMs = this.#flushIntervalMs;
+        // Optimistically remove events from buffer before sending.
+        // This prevents race conditions where a simultaneous #finalFlush would include these same events.
+        const eventsToSend = [...this.#buffer];
+        this.#buffer = [];
+        try {
+            const result = await this.#sendBatch(eventsToSend);
+            if (result.success) {
+                if (result.nextRequestWaitMs !== undefined) {
+                    nextDelayMs = Math.max(result.nextRequestWaitMs, MIN_RATE_LIMIT_WAIT_MS);
+                }
+            }
+            else if (result.isPermanentError) {
+                logger('Permanent error, dropped batch of', eventsToSend.length, 'events');
+            }
+            else {
+                // Transient error: Requeue events at the front of the buffer
+                // to maintain order and retry them later.
+                this.#buffer = [...eventsToSend, ...this.#buffer];
+            }
+        }
+        catch (error) {
+            // Safety catch for unexpected errors, requeue events
+            this.#buffer = [...eventsToSend, ...this.#buffer];
+            logger('Flush failed unexpectedly:', error);
+        }
+        finally {
+            this.#isFlushing = false;
+            this.#scheduleFlush(nextDelayMs);
+        }
+    }
+    #addToBuffer(event) {
+        if (this.#buffer.length >= MAX_BUFFER_SIZE) {
+            this.#buffer.shift();
+            logger('Telemetry buffer overflow: dropped oldest event');
+        }
+        this.#buffer.push({
+            event,
+            timestamp: Date.now(),
+        });
+    }
+    #scheduleFlush(delayMs) {
+        if (this.#flushTimer) {
+            clearTimeout(this.#flushTimer);
+        }
+        this.#flushTimer = setTimeout(() => {
+            this.#flush().catch(err => {
+                logger('Flush error:', err);
+            });
+        }, delayMs);
+    }
+    async #sendBatch(events) {
+        const requestBody = {
+            log_source: LOG_SOURCE,
+            request_time_ms: Date.now().toString(),
+            client_info: {
+                client_type: CLIENT_TYPE,
+            },
+            log_event: events.map(({ event, timestamp }) => ({
+                event_time_ms: timestamp.toString(),
+                source_extension_json: JSON.stringify(event),
+            })),
+        };
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const response = await fetch(this.#clearcutEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    // Used in E2E tests to confirm that the watchdog process is killed
+                    ...(this.#includePidHeader
+                        ? { 'X-Watchdog-Pid': process.pid.toString() }
+                        : {}),
+                },
+                body: JSON.stringify(requestBody),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const data = (await response.json());
+                return {
+                    success: true,
+                    nextRequestWaitMs: data.next_request_wait_millis,
+                };
+            }
+            const status = response.status;
+            if (status >= 500 || status === 429) {
+                return { success: false };
+            }
+            logger('Telemetry permanent error:', status);
+            return { success: false, isPermanentError: true };
+        }
+        catch {
+            clearTimeout(timeoutId);
+            return { success: false };
+        }
+    }
+    async #finalFlush() {
+        if (this.#buffer.length === 0) {
+            return;
+        }
+        const eventsToSend = [...this.#buffer];
+        await this.#sendBatch(eventsToSend);
+    }
+    stopForTesting() {
+        if (this.#flushTimer) {
+            clearTimeout(this.#flushTimer);
+            this.#flushTimer = null;
+        }
+        this.#timerStarted = false;
+    }
+    get bufferSizeForTesting() {
+        return this.#buffer.length;
     }
 }

package/build/src/telemetry/watchdog/main.js

@@ -9,20 +9,50 @@ import { parseArgs } from 'node:util';
 import { logger, flushLogs, saveLogsToFile } from '../../logger.js';
 import { WatchdogMessageType } from '../types.js';
 import { ClearcutSender } from './clearcut-sender.js';
-function main() {
+function parseWatchdogArgs() {
     const { values } = parseArgs({
         options: {
             'parent-pid': { type: 'string' },
             'app-version': { type: 'string' },
             'os-type': { type: 'string' },
             'log-file': { type: 'string' },
+            'clearcut-endpoint': { type: 'string' },
+            'clearcut-force-flush-interval-ms': { type: 'string' },
+            'clearcut-include-pid-header': { type: 'boolean' },
         },
         strict: true,
     });
+    // Verify required arguments
     const parentPid = parseInt(values['parent-pid'] ?? '', 10);
     const appVersion = values['app-version'];
     const osType = parseInt(values['os-type'] ?? '', 10);
+    if (isNaN(parentPid) || !appVersion || isNaN(osType)) {
+        console.error('Invalid arguments provided for watchdog process: ', JSON.stringify({ parentPid, appVersion, osType }));
+        process.exit(1);
+    }
+    // Parse Optional Arguments
     const logFile = values['log-file'];
+    const clearcutEndpoint = values['clearcut-endpoint'];
+    const clearcutIncludePidHeader = values['clearcut-include-pid-header'];
+    let clearcutForceFlushIntervalMs;
+    if (values['clearcut-force-flush-interval-ms']) {
+        const parsed = parseInt(values['clearcut-force-flush-interval-ms'], 10);
+        if (!isNaN(parsed)) {
+            clearcutForceFlushIntervalMs = parsed;
+        }
+    }
+    return {
+        parentPid,
+        appVersion,
+        osType,
+        logFile,
+        clearcutEndpoint,
+        clearcutForceFlushIntervalMs,
+        clearcutIncludePidHeader,
+    };
+}
+function main() {
+    const { parentPid, appVersion, osType, logFile, clearcutEndpoint, clearcutForceFlushIntervalMs, clearcutIncludePidHeader, } = parseWatchdogArgs();
     let logStream;
     if (logFile) {
         logStream = saveLogsToFile(logFile);
@@ -35,18 +65,19 @@ function main() {
             process.exit(code);
         });
     };
-    if (isNaN(parentPid) || !appVersion || isNaN(osType)) {
-        logger('Invalid arguments provided for watchdog process: ', JSON.stringify({ parentPid, appVersion, osType }));
-        exit(1);
-        return;
-    }
     logger('Watchdog started', JSON.stringify({
         pid: process.pid,
         parentPid,
         version: appVersion,
         osType,
     }, null, 2));
-    const sender = new ClearcutSender(appVersion, osType);
+    const sender = new ClearcutSender({
+        appVersion,
+        osType: osType,
+        clearcutEndpoint,
+        forceFlushIntervalMs: clearcutForceFlushIntervalMs,
+        includePidHeader: clearcutIncludePidHeader,
+    });
     let isShuttingDown = false;
     function onParentDeath(reason) {
         if (isShuttingDown) {
@@ -79,9 +110,7 @@ function main() {
             }
             const msg = JSON.parse(line);
             if (msg.type === WatchdogMessageType.LOG_EVENT && msg.payload) {
-                sender.send(msg.payload).catch(err => {
-                    logger('Error sending event', err);
-                });
+                sender.enqueueEvent(msg.payload);
             }
         }
         catch (err) {

package/build/src/telemetry/watchdog-client.js

@@ -19,6 +19,15 @@ export class WatchdogClient {
         if (config.logFile) {
             args.push(`--log-file=${config.logFile}`);
         }
+        if (config.clearcutEndpoint) {
+            args.push(`--clearcut-endpoint=${config.clearcutEndpoint}`);
+        }
+        if (config.clearcutForceFlushIntervalMs) {
+            args.push(`--clearcut-force-flush-interval-ms=${config.clearcutForceFlushIntervalMs}`);
+        }
+        if (config.clearcutIncludePidHeader) {
+            args.push('--clearcut-include-pid-header');
+        }
         const spawner = options?.spawn ?? spawn;
         this.#childProcess = spawner(process.execPath, args, {
             stdio: ['pipe', 'ignore', 'ignore'],