@mcp-b/chrome-devtools-mcp 2.0.2 → 2.0.6

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;
+    }
+}

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

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import process from 'node:process';
+import readline from 'node:readline';
+import { parseArgs } from 'node:util';
+import { logger, flushLogs, saveLogsToFile } from '../../logger.js';
+import { WatchdogMessageType } from '../types.js';
+import { ClearcutSender } from './clearcut-sender.js';
+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);
+    }
+    const exit = (code) => {
+        if (!logStream) {
+            process.exit(code);
+        }
+        void flushLogs(logStream).finally(() => {
+            process.exit(code);
+        });
+    };
+    logger('Watchdog started', JSON.stringify({
+        pid: process.pid,
+        parentPid,
+        version: appVersion,
+        osType,
+    }, null, 2));
+    const sender = new ClearcutSender({
+        appVersion,
+        osType: osType,
+        clearcutEndpoint,
+        forceFlushIntervalMs: clearcutForceFlushIntervalMs,
+        includePidHeader: clearcutIncludePidHeader,
+    });
+    let isShuttingDown = false;
+    function onParentDeath(reason) {
+        if (isShuttingDown) {
+            return;
+        }
+        isShuttingDown = true;
+        logger(`Parent death detected (${reason}). Sending shutdown event...`);
+        sender
+            .sendShutdownEvent()
+            .then(() => {
+            logger('Shutdown event sent. Exiting.');
+            exit(0);
+        })
+            .catch(err => {
+            logger('Failed to send shutdown event', err);
+            exit(1);
+        });
+    }
+    process.stdin.on('end', () => onParentDeath('stdin end'));
+    process.stdin.on('close', () => onParentDeath('stdin close'));
+    process.on('disconnect', () => onParentDeath('ipc disconnect'));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        terminal: false,
+    });
+    rl.on('line', line => {
+        try {
+            if (!line.trim()) {
+                return;
+            }
+            const msg = JSON.parse(line);
+            if (msg.type === WatchdogMessageType.LOG_EVENT && msg.payload) {
+                sender.enqueueEvent(msg.payload);
+            }
+        }
+        catch (err) {
+            logger('Failed to parse IPC message', err);
+        }
+    });
+}
+try {
+    main();
+}
+catch (err) {
+    console.error('Watchdog fatal error:', err);
+    process.exit(1);
+}

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

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../logger.js';
+export class WatchdogClient {
+    #childProcess;
+    constructor(config, options) {
+        const watchdogPath = fileURLToPath(new URL('./watchdog/main.js', import.meta.url));
+        const args = [
+            watchdogPath,
+            `--parent-pid=${config.parentPid}`,
+            `--app-version=${config.appVersion}`,
+            `--os-type=${config.osType}`,
+        ];
+        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'],
+            detached: true,
+        });
+        this.#childProcess.unref();
+        this.#childProcess.on('error', err => {
+            logger('Watchdog process error:', err);
+        });
+        this.#childProcess.on('exit', (code, signal) => {
+            logger(`Watchdog exited with code ${code} and signal ${signal}`);
+        });
+    }
+    send(message) {
+        if (this.#childProcess.stdin &&
+            !this.#childProcess.stdin.destroyed &&
+            this.#childProcess.pid) {
+            try {
+                const line = JSON.stringify(message) + '\n';
+                this.#childProcess.stdin.write(line);
+            }
+            catch (err) {
+                logger('Failed to write to watchdog stdin', err);
+            }
+        }
+        else {
+            logger('Watchdog stdin not available, dropping message');
+        }
+    }
+}

package/build/src/third_party/devtools-formatter-worker.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// eslint-disable-next-line no-restricted-imports
+import '../../vendor/chrome-devtools-frontend/front_end/entrypoints/formatter_worker/formatter_worker-entrypoint.js';

package/build/src/third_party/index.js

@@ -11,6 +11,6 @@ export { default as debug } from 'debug';
 export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 export { SetLevelRequestSchema, ToolListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
-export { z as zod } from 'zod/v4';
+export { z as zod } from 'zod';
 export { Locator, PredefinedNetworkConditions, CDPSessionEvent, } from 'puppeteer-core';
 export { default as puppeteer } from 'puppeteer-core';

package/build/src/tools/browser.js

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const connectToBrowser = defineTool({
+    name: 'connect_to_browser',
+    description: 'Connect to a different Chrome browser instance at runtime. ' +
+        'Disconnects from the current browser (without closing it) and attaches to the new one. ' +
+        'Useful for WXT extension development: run `wxt dev`, parse the debug URL from stdout, ' +
+        'then call this tool to attach. Retries automatically if the browser is still starting up.',
+    annotations: {
+        title: 'Connect to Browser',
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        browserUrl: zod
+            .string()
+            .optional()
+            .describe('HTTP URL to the browser\'s DevTools endpoint, e.g. "http://127.0.0.1:9222". ' +
+            'Exactly one of browserUrl or wsEndpoint is required.'),
+        wsEndpoint: zod
+            .string()
+            .optional()
+            .describe('WebSocket URL to connect to, e.g. "ws://127.0.0.1:9222/devtools/browser/...". ' +
+            'Exactly one of browserUrl or wsEndpoint is required.'),
+        wsHeaders: zod
+            .record(zod.string())
+            .optional()
+            .describe('Optional HTTP headers for WebSocket connection (only used with wsEndpoint).'),
+        timeout: zod
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Maximum time in milliseconds to wait for the browser to become available. ' +
+            'Defaults to 30000 (30 seconds). The tool retries every 2 seconds within this window.'),
+    },
+    handler: async (request, response, context) => {
+        const { browserUrl, wsEndpoint, wsHeaders, timeout } = request.params;
+        // Validate: exactly one connection method required
+        if (!browserUrl && !wsEndpoint) {
+            throw new Error('Either browserUrl or wsEndpoint is required. ' +
+                'Example: browserUrl "http://127.0.0.1:9222" or wsEndpoint "ws://127.0.0.1:9222/devtools/browser/..."');
+        }
+        if (browserUrl && wsEndpoint) {
+            throw new Error('Provide only one of browserUrl or wsEndpoint, not both.');
+        }
+        // Validate URL protocols
+        if (browserUrl && !browserUrl.startsWith('http://') && !browserUrl.startsWith('https://')) {
+            throw new Error(`Invalid browserUrl: "${browserUrl}". Must start with http:// or https://`);
+        }
+        if (wsEndpoint && !wsEndpoint.startsWith('ws://') && !wsEndpoint.startsWith('wss://')) {
+            throw new Error(`Invalid wsEndpoint: "${wsEndpoint}". Must start with ws:// or wss://`);
+        }
+        try {
+            const result = await context.reconnectBrowser({
+                browserURL: browserUrl,
+                wsEndpoint,
+                wsHeaders,
+                timeout,
+            });
+            response.appendResponseLine(`Connected to browser at ${wsEndpoint ?? browserUrl}`);
+            response.appendResponseLine(`WebSocket endpoint: ${result.wsEndpoint}`);
+            response.appendResponseLine('');
+            response.appendResponseLine('Pages:');
+            for (const page of result.pages) {
+                const marker = page.selected ? ' (selected)' : '';
+                response.appendResponseLine(`  [${page.index}] ${page.url}${marker}`);
+            }
+        }
+        catch (err) {
+            response.setIsError(true);
+            const message = err instanceof Error ? err.message : String(err);
+            response.appendResponseLine(`Failed to connect: ${message}`);
+            response.appendResponseLine('');
+            response.appendResponseLine('Troubleshooting:');
+            response.appendResponseLine('  - Ensure Chrome was launched with --remote-debugging-port=<port>');
+            response.appendResponseLine('  - Verify the URL is reachable: curl ' + (browserUrl ?? wsEndpoint));
+            if (timeout) {
+                response.appendResponseLine('  - Try increasing the timeout (current: ' + timeout + 'ms)');
+            }
+            else {
+                response.appendResponseLine('  - Try setting a longer timeout (default is 30s)');
+            }
+        }
+    },
+});

package/build/src/tools/extension.js

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const evaluateInExtensionWorker = defineTool({
+    name: 'evaluate_in_extension_worker',
+    description: 'Execute a JavaScript expression in a Chrome extension background service worker. ' +
+        'Useful for inspecting extension state (e.g., McpHub connections, offscreen status) ' +
+        'that is not accessible from page contexts.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+    },
+    schema: {
+        expression: zod
+            .string()
+            .describe('JavaScript expression to evaluate in the service worker.'),
+        extensionId: zod
+            .string()
+            .optional()
+            .describe('Extension ID to target. If omitted, the first extension service worker found is used.'),
+    },
+    handler: async (request, response, context) => {
+        const result = await context.evaluateInExtensionWorker(request.params.expression, request.params.extensionId);
+        response.appendResponseLine(JSON.stringify(result, null, 2));
+    },
+});

package/build/src/tools/extensions.js

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+const EXTENSIONS_CONDITION = 'experimentalExtensionSupport';
+export const installExtension = defineTool({
+    name: 'install_extension',
+    description: 'Installs a Chrome extension from the given path.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {
+        path: zod
+            .string()
+            .describe('Absolute path to the unpacked extension folder.'),
+    },
+    handler: async (request, response, context) => {
+        const { path } = request.params;
+        const id = await context.installExtension(path);
+        response.appendResponseLine(`Extension installed. Id: ${id}`);
+    },
+});
+export const uninstallExtension = defineTool({
+    name: 'uninstall_extension',
+    description: 'Uninstalls a Chrome extension by its ID.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {
+        id: zod.string().describe('ID of the extension to uninstall.'),
+    },
+    handler: async (request, response, context) => {
+        const { id } = request.params;
+        await context.uninstallExtension(id);
+        response.appendResponseLine(`Extension uninstalled. Id: ${id}`);
+    },
+});
+export const listExtensions = defineTool({
+    name: 'list_extensions',
+    description: 'Lists all extensions via this server, including their name, ID, version, and enabled status.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: true,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {},
+    handler: async (_request, response, _context) => {
+        response.setListExtensions();
+    },
+});
+export const reloadExtension = defineTool({
+    name: 'reload_extension',
+    description: 'Reloads an unpacked Chrome extension by its ID.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+        conditions: [EXTENSIONS_CONDITION],
+    },
+    schema: {
+        id: zod.string().describe('ID of the extension to reload.'),
+    },
+    handler: async (request, response, context) => {
+        const { id } = request.params;
+        const extension = context.getExtension(id);
+        if (!extension) {
+            throw new Error(`Extension with ID ${id} not found.`);
+        }
+        await context.installExtension(extension.path);
+        response.appendResponseLine('Extension reloaded.');
+    },
+});

package/build/src/tools/input.js

@@ -103,11 +103,16 @@ async function selectOption(handle, aXNode, value) {
         throw new Error(`Could not find option with text "${value}"`);
     }
 }
+function hasOptionChildren(aXNode) {
+    return aXNode.children.some(child => child.role === 'option');
+}
 async function fillFormElement(uid, value, context) {
     const handle = await context.getElementByUid(uid);
     try {
         const aXNode = context.getAXNodeByUid(uid);
-        if (aXNode && aXNode.role === 'combobox') {
+        // We assume that combobox needs to be handled as select if it has
+        // role='combobox' and option children.
+        if (aXNode && aXNode.role === 'combobox' && hasOptionChildren(aXNode)) {
             await selectOption(handle, aXNode, value);
         }
         else {

package/build/src/tools/pages.js

@@ -110,6 +110,10 @@ export const navigatePage = defineTool({
             .boolean()
             .optional()
             .describe('Whether to ignore cache on reload.'),
+        bypassCSP: zod
+            .boolean()
+            .optional()
+            .describe('Bypass Content-Security-Policy on the page. Useful for injecting scripts into third-party sites during development.'),
         ...timeoutSchema,
     },
     handler: async (request, response, context) => {
@@ -117,6 +121,9 @@ export const navigatePage = defineTool({
         const options = {
             timeout: request.params.timeout,
         };
+        if (request.params.bypassCSP !== undefined) {
+            await context.setBypassCSP(request.params.bypassCSP);
+        }
         if (!request.params.type && !request.params.url) {
             throw new Error('Either URL or a type is required.');
         }
@@ -185,7 +192,6 @@ export const resizePage = defineTool({
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
-        // @ts-expect-error internal API for now.
         await page.resize({
             contentWidth: request.params.width,
             contentHeight: request.params.height,