@mcp-b/chrome-devtools-mcp 1.7.0 → 1.7.1

package/build/src/main.js

@@ -5,7 +5,7 @@
  */
 import process from 'node:process';
 import './polyfill.js';
-import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
+import { connectToNewBrowser, disconnectBrowser, ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
 import { parseArguments } from './cli.js';
 import { loadIssueDescriptions } from './issue-descriptions.js';
 import { logger, saveLogsToFile } from './logger.js';
@@ -102,6 +102,7 @@ async function getContext() {
             devtools,
             channel: undefined,
             userDataDir: args.userDataDir,
+            includeExtensionPages: args.includeExtensionPages,
         });
     }
     // If autoConnect is true, try connecting first, then fall back to launching
@@ -115,6 +116,7 @@ async function getContext() {
                 devtools,
                 channel: args.channel,
                 userDataDir: args.userDataDir,
+                includeExtensionPages: args.includeExtensionPages,
             });
             logger('Successfully connected to running browser instance');
         }
@@ -131,6 +133,7 @@ async function getContext() {
                 args: extraArgs,
                 acceptInsecureCerts: args.acceptInsecureCerts,
                 devtools,
+                includeExtensionPages: args.includeExtensionPages,
             });
             wasLaunched = true;
         }
@@ -148,6 +151,7 @@ async function getContext() {
             args: extraArgs,
             acceptInsecureCerts: args.acceptInsecureCerts,
             devtools,
+            includeExtensionPages: args.includeExtensionPages,
         });
         wasLaunched = true;
     }
@@ -155,6 +159,8 @@ async function getContext() {
         context = await McpContext.from(browser, logger, {
             experimentalDevToolsDebugging: devtools,
             experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+            includeExtensionPages: args.includeExtensionPages,
+            onReconnect,
         });
         if (wasLaunched) {
             // Fresh browser launch - use the existing default page
@@ -201,6 +207,77 @@ async function getContext() {
     }
     return context;
 }
+/**
+ * Reconnect callback invoked by the connect_to_browser tool.
+ *
+ * Tears down the current browser session and connects to a new browser,
+ * rebuilding all infrastructure (McpContext, WebMCPToolHub, session window).
+ * Retries connection with exponential backoff for browsers that are still starting.
+ */
+async function onReconnect(options) {
+    const timeout = options.timeout ?? 30_000;
+    const retryInterval = 2_000;
+    const devtools = args.experimentalDevtools ?? false;
+    // 1. Tear down old session
+    if (context) {
+        try {
+            await context.closeSessionWindow();
+        }
+        catch (err) {
+            logger('Error closing session window during reconnect:', err);
+        }
+        context.dispose();
+    }
+    disconnectBrowser();
+    // 2. Retry loop to connect to new browser
+    const deadline = Date.now() + timeout;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const newBrowser = await connectToNewBrowser({
+                browserURL: options.browserURL,
+                wsEndpoint: options.wsEndpoint,
+                wsHeaders: options.wsHeaders,
+                includeExtensionPages: args.includeExtensionPages,
+            });
+            // 3. Rebuild context
+            context = await McpContext.from(newBrowser, logger, {
+                experimentalDevToolsDebugging: devtools,
+                experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+                includeExtensionPages: args.includeExtensionPages,
+                onReconnect,
+            });
+            // 4. Create session window
+            const { windowId } = await context.newWindow();
+            context.setSessionWindowId(windowId);
+            logger(`Reconnect: new session window ${windowId}`);
+            // 5. Rebuild tool hub
+            const toolHub = new WebMCPToolHub(server, context);
+            context.setToolHub(toolHub);
+            logger('Reconnect: WebMCPToolHub rebuilt');
+            // 6. Build response
+            const pages = context.getPages().map((page, index) => ({
+                index,
+                url: page.url(),
+                selected: context.isPageSelected(page),
+            }));
+            const wsEndpoint = newBrowser.wsEndpoint();
+            return { pages, wsEndpoint };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            logger(`Reconnect attempt failed: ${lastError.message}`);
+            const remaining = deadline - Date.now();
+            if (remaining > retryInterval) {
+                await new Promise(resolve => setTimeout(resolve, retryInterval));
+            }
+            else {
+                break;
+            }
+        }
+    }
+    throw new Error(`Failed to connect to browser after ${timeout}ms: ${lastError?.message ?? 'unknown error'}`);
+}
 /**
  * Log security disclaimers to stderr.
  *
@@ -251,7 +328,11 @@ function registerTool(tool) {
             await tool.handler({
                 params,
             }, response, context);
-            const content = await response.handle(tool.name, context);
+            // Re-fetch context in case the handler swapped it (e.g. connect_to_browser).
+            // The local `const context` shadows the module-level `let context`, so we
+            // must call getContext() to pick up any reassignment by onReconnect.
+            const activeContext = await getContext();
+            const content = await response.handle(tool.name, activeContext);
             const result = {
                 content,
             };

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

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import process from 'node:process';
+import { logger } from '../logger.js';
+import { FilePersistence } from './persistence.js';
+import { WatchdogMessageType, OsType } from './types.js';
+import { WatchdogClient } from './watchdog-client.js';
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function detectOsType() {
+    switch (process.platform) {
+        case 'win32':
+            return OsType.OS_TYPE_WINDOWS;
+        case 'darwin':
+            return OsType.OS_TYPE_MACOS;
+        case 'linux':
+            return OsType.OS_TYPE_LINUX;
+        default:
+            return OsType.OS_TYPE_UNSPECIFIED;
+    }
+}
+export class ClearcutLogger {
+    #persistence;
+    #watchdog;
+    constructor(options) {
+        this.#persistence = options.persistence ?? new FilePersistence();
+        this.#watchdog =
+            options.watchdogClient ??
+                new WatchdogClient({
+                    parentPid: process.pid,
+                    appVersion: options.appVersion,
+                    osType: detectOsType(),
+                    logFile: options.logFile,
+                    clearcutEndpoint: options.clearcutEndpoint,
+                    clearcutForceFlushIntervalMs: options.clearcutForceFlushIntervalMs,
+                    clearcutIncludePidHeader: options.clearcutIncludePidHeader,
+                });
+    }
+    async logToolInvocation(args) {
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: {
+                tool_invocation: {
+                    tool_name: args.toolName,
+                    success: args.success,
+                    latency_ms: args.latencyMs,
+                },
+            },
+        });
+    }
+    async logServerStart(flagUsage) {
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: {
+                server_start: {
+                    flag_usage: flagUsage,
+                },
+            },
+        });
+    }
+    async logDailyActiveIfNeeded() {
+        try {
+            const state = await this.#persistence.loadState();
+            if (this.#shouldLogDailyActive(state)) {
+                let daysSince = -1;
+                if (state.lastActive) {
+                    const lastActiveDate = new Date(state.lastActive);
+                    const now = new Date();
+                    const diffTime = Math.abs(now.getTime() - lastActiveDate.getTime());
+                    daysSince = Math.ceil(diffTime / MS_PER_DAY);
+                }
+                this.#watchdog.send({
+                    type: WatchdogMessageType.LOG_EVENT,
+                    payload: {
+                        daily_active: {
+                            days_since_last_active: daysSince,
+                        },
+                    },
+                });
+                state.lastActive = new Date().toISOString();
+                await this.#persistence.saveState(state);
+            }
+        }
+        catch (err) {
+            logger('Error in logDailyActiveIfNeeded:', err);
+        }
+    }
+    #shouldLogDailyActive(state) {
+        if (!state.lastActive) {
+            return true;
+        }
+        const lastActiveDate = new Date(state.lastActive);
+        const now = new Date();
+        // Compare UTC dates
+        const isSameDay = lastActiveDate.getUTCFullYear() === now.getUTCFullYear() &&
+            lastActiveDate.getUTCMonth() === now.getUTCMonth() &&
+            lastActiveDate.getUTCDate() === now.getUTCDate();
+        return !isSameDay;
+    }
+}

package/build/src/telemetry/flag-utils.js

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { toSnakeCase } from '../utils/string.js';
+/**
+ * Computes telemetry flag usage from parsed arguments and CLI options.
+ *
+ * Iterates over the defined CLI options to construct a payload:
+ * - Flag names are converted to snake_case (e.g. `browserUrl` -> `browser_url`).
+ * - A flag is logged as `{flag_name}_present` if:
+ *    - It has no default value, OR
+ *    - The provided value differs from the default value.
+ * - Boolean flags are logged with their literal value.
+ * - String flags with defined `choices` (Enums) are logged as their uppercase value.
+ */
+export function computeFlagUsage(args, options) {
+    const usage = {};
+    for (const [flagName, config] of Object.entries(options)) {
+        const value = args[flagName];
+        const snakeCaseName = toSnakeCase(flagName);
+        // If there isn't a default value provided for the flag,
+        // we're going to log whether it's present on the args user
+        // provided or not. If there is a default value, we only log presence
+        // if the value differs from the default, implying explicit user intent.
+        if (!('default' in config) || value !== config.default) {
+            usage[`${snakeCaseName}_present`] = value !== undefined && value !== null;
+        }
+        if (config.type === 'boolean' && typeof value === 'boolean') {
+            // For boolean options, we're going to log the value directly.
+            usage[snakeCaseName] = value;
+        }
+        else if (config.type === 'string' &&
+            typeof value === 'string' &&
+            'choices' in config &&
+            config.choices) {
+            // For enums, log the value as uppercase
+            // We're going to have an enum for such flags with choices represented
+            // as an `enum` where the keys of the enum will map to the uppercase `choice`.
+            usage[snakeCaseName] = `${snakeCaseName}_${value}`.toUpperCase();
+        }
+    }
+    return usage;
+}

package/build/src/telemetry/metric-utils.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const LATENCY_BUCKETS = [50, 100, 250, 500, 1000, 2500, 5000, 10000];
+export function bucketizeLatency(latencyMs) {
+    for (const bucket of LATENCY_BUCKETS) {
+        if (latencyMs <= bucket) {
+            return bucket;
+        }
+    }
+    return LATENCY_BUCKETS[LATENCY_BUCKETS.length - 1];
+}

package/build/src/telemetry/persistence.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { logger } from '../logger.js';
+const STATE_FILE_NAME = 'telemetry_state.json';
+function getDataFolder() {
+    const homedir = os.homedir();
+    const { env } = process;
+    const name = 'chrome-devtools-mcp';
+    if (process.platform === 'darwin') {
+        return path.join(homedir, 'Library', 'Application Support', name);
+    }
+    if (process.platform === 'win32') {
+        const localAppData = env.LOCALAPPDATA || path.join(homedir, 'AppData', 'Local');
+        return path.join(localAppData, name, 'Data');
+    }
+    return path.join(env.XDG_DATA_HOME || path.join(homedir, '.local', 'share'), name);
+}
+export class FilePersistence {
+    #dataFolder;
+    constructor(dataFolderOverride) {
+        this.#dataFolder = dataFolderOverride ?? getDataFolder();
+    }
+    async loadState() {
+        try {
+            const filePath = path.join(this.#dataFolder, STATE_FILE_NAME);
+            const content = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return {
+                lastActive: '',
+            };
+        }
+    }
+    async saveState(state) {
+        const filePath = path.join(this.#dataFolder, STATE_FILE_NAME);
+        try {
+            await fs.mkdir(this.#dataFolder, { recursive: true });
+            await fs.writeFile(filePath, JSON.stringify(state, null, 2), 'utf-8');
+        }
+        catch (error) {
+            // Ignore errors during state saving to avoid crashing the server
+            logger(`Failed to save telemetry state to ${filePath}:`, error);
+        }
+    }
+}

package/build/src/telemetry/types.js

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Enums
+export var OsType;
+(function (OsType) {
+    OsType[OsType["OS_TYPE_UNSPECIFIED"] = 0] = "OS_TYPE_UNSPECIFIED";
+    OsType[OsType["OS_TYPE_WINDOWS"] = 1] = "OS_TYPE_WINDOWS";
+    OsType[OsType["OS_TYPE_MACOS"] = 2] = "OS_TYPE_MACOS";
+    OsType[OsType["OS_TYPE_LINUX"] = 3] = "OS_TYPE_LINUX";
+})(OsType || (OsType = {}));
+export var ChromeChannel;
+(function (ChromeChannel) {
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_UNSPECIFIED"] = 0] = "CHROME_CHANNEL_UNSPECIFIED";
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_CANARY"] = 1] = "CHROME_CHANNEL_CANARY";
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_DEV"] = 2] = "CHROME_CHANNEL_DEV";
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_BETA"] = 3] = "CHROME_CHANNEL_BETA";
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_STABLE"] = 4] = "CHROME_CHANNEL_STABLE";
+})(ChromeChannel || (ChromeChannel = {}));
+export var McpClient;
+(function (McpClient) {
+    McpClient[McpClient["MCP_CLIENT_UNSPECIFIED"] = 0] = "MCP_CLIENT_UNSPECIFIED";
+    McpClient[McpClient["MCP_CLIENT_CLAUDE_CODE"] = 1] = "MCP_CLIENT_CLAUDE_CODE";
+    McpClient[McpClient["MCP_CLIENT_GEMINI_CLI"] = 2] = "MCP_CLIENT_GEMINI_CLI";
+})(McpClient || (McpClient = {}));
+// IPC types for messages between the main process and the
+// telemetry watchdog process.
+export var WatchdogMessageType;
+(function (WatchdogMessageType) {
+    WatchdogMessageType["LOG_EVENT"] = "log-event";
+})(WatchdogMessageType || (WatchdogMessageType = {}));

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

@@ -0,0 +1,201 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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;
+    #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();
+    }
+    enqueueEvent(event) {
+        if (Date.now() - this.#sessionCreated > SESSION_ROTATION_INTERVAL_MS) {
+            this.#sessionId = crypto.randomUUID();
+            this.#sessionCreated = Date.now();
+        }
+        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;
+    }
+}