@mcp-b/chrome-devtools-mcp 2.3.0 → 2.3.1-beta.20260528050333

package/build/src/formatters/SnapshotFormatter.js

@@ -1,131 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-export class SnapshotFormatter {
-    #snapshot;
-    constructor(snapshot) {
-        this.#snapshot = snapshot;
-    }
-    toString() {
-        const chunks = [];
-        const root = this.#snapshot.root;
-        // Top-level content of the snapshot.
-        if (this.#snapshot.verbose &&
-            this.#snapshot.hasSelectedElement &&
-            !this.#snapshot.selectedElementUid) {
-            chunks.push(`Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
-Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
-        }
-        chunks.push(this.#formatNode(root, 0));
-        return chunks.join('');
-    }
-    toJSON() {
-        return this.#nodeToJSON(this.#snapshot.root);
-    }
-    #formatNode(node, depth = 0) {
-        const chunks = [];
-        const attributes = this.#getAttributes(node);
-        const line = ' '.repeat(depth * 2) +
-            attributes.join(' ') +
-            (node.id === this.#snapshot.selectedElementUid
-                ? ' [selected in the DevTools Elements panel]'
-                : '') +
-            '\n';
-        chunks.push(line);
-        for (const child of node.children) {
-            chunks.push(this.#formatNode(child, depth + 1));
-        }
-        return chunks.join('');
-    }
-    #nodeToJSON(node) {
-        const rawAttrs = this.#getAttributesMap(node);
-        const children = node.children.map((child) => this.#nodeToJSON(child));
-        const result = structuredClone(rawAttrs);
-        if (children.length > 0) {
-            result.children = children;
-        }
-        return result;
-    }
-    #getAttributes(serializedAXNodeRoot) {
-        const attributes = [`uid=${serializedAXNodeRoot.id}`];
-        if (serializedAXNodeRoot.role) {
-            attributes.push(serializedAXNodeRoot.role === 'none' ? 'ignored' : serializedAXNodeRoot.role);
-        }
-        if (serializedAXNodeRoot.name) {
-            attributes.push(`"${serializedAXNodeRoot.name}"`);
-        }
-        const simpleAttrs = this.#getAttributesMap(serializedAXNodeRoot, /* excludeSpecial */ true);
-        for (const attr of Object.keys(serializedAXNodeRoot).sort()) {
-            if (excludedAttributes.has(attr)) {
-                continue;
-            }
-            const mapped = booleanPropertyMap[attr];
-            if (mapped && simpleAttrs[mapped]) {
-                attributes.push(mapped);
-            }
-            const val = simpleAttrs[attr];
-            if (val === true) {
-                attributes.push(attr);
-            }
-            else if (typeof val === 'string' || typeof val === 'number') {
-                attributes.push(`${attr}="${val}"`);
-            }
-        }
-        return attributes;
-    }
-    #getAttributesMap(node, excludeSpecial = false) {
-        const result = {};
-        if (!excludeSpecial) {
-            result.id = node.id;
-            if (node.role) {
-                result.role = node.role;
-            }
-            if (node.name) {
-                result.name = node.name;
-            }
-        }
-        // Re-implementing the exact logic from original function for #getAttributes to be safe:
-        return {
-            ...result,
-            ...this.#extractedAttributes(node),
-        };
-    }
-    #extractedAttributes(node) {
-        const result = {};
-        for (const attr of Object.keys(node).sort()) {
-            if (excludedAttributes.has(attr)) {
-                continue;
-            }
-            const value = node[attr];
-            if (typeof value === 'boolean') {
-                if (booleanPropertyMap[attr]) {
-                    result[booleanPropertyMap[attr]] = true;
-                }
-                if (value) {
-                    result[attr] = true;
-                }
-            }
-            else if (typeof value === 'string' || typeof value === 'number') {
-                result[attr] = value;
-            }
-        }
-        return result;
-    }
-}
-const booleanPropertyMap = {
-    disabled: 'disableable',
-    expanded: 'expandable',
-    focused: 'focusable',
-    selected: 'selectable',
-};
-const excludedAttributes = new Set([
-    'id',
-    'role',
-    'name',
-    'elementHandle',
-    'children',
-    'backendNodeId',
-    'loaderId',
-]);

package/build/src/index.js

@@ -1,202 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
-import { loadIssueDescriptions } from './issue-descriptions.js';
-import { logger } from './logger.js';
-import { McpContext } from './McpContext.js';
-import { McpResponse } from './McpResponse.js';
-import { Mutex } from './Mutex.js';
-import { SlimMcpResponse } from './SlimMcpResponse.js';
-import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
-import { bucketizeLatency } from './telemetry/metricUtils.js';
-import { McpServer, SetLevelRequestSchema } from './third_party/index.js';
-import { ToolCategory } from './tools/categories.js';
-import { pageIdSchema } from './tools/ToolDefinition.js';
-import { createTools } from './tools/tools.js';
-import { VERSION } from './version.js';
-export async function createMcpServer(serverArgs, options) {
-    let clearcutLogger;
-    if (serverArgs.usageStatistics) {
-        clearcutLogger = new ClearcutLogger({
-            logFile: serverArgs.logFile,
-            appVersion: VERSION,
-            clearcutEndpoint: serverArgs.clearcutEndpoint,
-            clearcutForceFlushIntervalMs: serverArgs.clearcutForceFlushIntervalMs,
-            clearcutIncludePidHeader: serverArgs.clearcutIncludePidHeader,
-        });
-    }
-    const server = new McpServer({
-        name: 'chrome_devtools',
-        title: 'Chrome DevTools MCP server',
-        version: VERSION,
-    }, { capabilities: { logging: {} } });
-    server.server.setRequestHandler(SetLevelRequestSchema, () => {
-        return {};
-    });
-    let context;
-    async function getContext() {
-        const chromeArgs = (serverArgs.chromeArg ?? []).map(String);
-        const ignoreDefaultChromeArgs = (serverArgs.ignoreDefaultChromeArg ?? []).map(String);
-        if (serverArgs.proxyServer) {
-            chromeArgs.push(`--proxy-server=${serverArgs.proxyServer}`);
-        }
-        const devtools = serverArgs.experimentalDevtools ?? false;
-        const browser = serverArgs.browserUrl || serverArgs.wsEndpoint || serverArgs.autoConnect
-            ? await ensureBrowserConnected({
-                browserURL: serverArgs.browserUrl,
-                wsEndpoint: serverArgs.wsEndpoint,
-                wsHeaders: serverArgs.wsHeaders,
-                // Important: only pass channel, if autoConnect is true.
-                channel: serverArgs.autoConnect ? serverArgs.channel : undefined,
-                userDataDir: serverArgs.userDataDir,
-                devtools,
-            })
-            : await ensureBrowserLaunched({
-                headless: serverArgs.headless,
-                executablePath: serverArgs.executablePath,
-                channel: serverArgs.channel,
-                isolated: serverArgs.isolated ?? false,
-                userDataDir: serverArgs.userDataDir,
-                logFile: options.logFile,
-                viewport: serverArgs.viewport,
-                chromeArgs,
-                ignoreDefaultChromeArgs,
-                acceptInsecureCerts: serverArgs.acceptInsecureCerts,
-                devtools,
-                enableExtensions: serverArgs.categoryExtensions,
-                viaCli: serverArgs.viaCli,
-            });
-        if (context?.browser !== browser) {
-            context = await McpContext.from(browser, logger, {
-                experimentalDevToolsDebugging: devtools,
-                experimentalIncludeAllPages: serverArgs.experimentalIncludeAllPages,
-                performanceCrux: serverArgs.performanceCrux,
-            });
-        }
-        return context;
-    }
-    const toolMutex = new Mutex();
-    function registerTool(tool) {
-        if (tool.annotations.category === ToolCategory.EMULATION &&
-            serverArgs.categoryEmulation === false) {
-            return;
-        }
-        if (tool.annotations.category === ToolCategory.PERFORMANCE &&
-            serverArgs.categoryPerformance === false) {
-            return;
-        }
-        if (tool.annotations.category === ToolCategory.NETWORK &&
-            serverArgs.categoryNetwork === false) {
-            return;
-        }
-        if (tool.annotations.category === ToolCategory.EXTENSIONS && !serverArgs.categoryExtensions) {
-            return;
-        }
-        if (tool.annotations.conditions?.includes('computerVision') && !serverArgs.experimentalVision) {
-            return;
-        }
-        if (tool.annotations.conditions?.includes('experimentalInteropTools') &&
-            !serverArgs.experimentalInteropTools) {
-            return;
-        }
-        if (tool.annotations.conditions?.includes('screencast') && !serverArgs.experimentalScreencast) {
-            return;
-        }
-        const schema = 'pageScoped' in tool &&
-            tool.pageScoped &&
-            serverArgs.experimentalPageIdRouting &&
-            !serverArgs.slim
-            ? { ...tool.schema, ...pageIdSchema }
-            : tool.schema;
-        server.registerTool(tool.name, {
-            description: tool.description,
-            inputSchema: schema,
-            annotations: tool.annotations,
-        }, async (params) => {
-            const guard = await toolMutex.acquire();
-            const startTime = Date.now();
-            let success = false;
-            try {
-                logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
-                const context = await getContext();
-                logger(`${tool.name} context: resolved`);
-                await context.detectOpenDevToolsWindows();
-                const response = serverArgs.slim
-                    ? new SlimMcpResponse(serverArgs)
-                    : new McpResponse(serverArgs);
-                if ('pageScoped' in tool && tool.pageScoped) {
-                    const page = serverArgs.experimentalPageIdRouting && params.pageId && !serverArgs.slim
-                        ? context.getPageById(params.pageId)
-                        : context.getSelectedMcpPage();
-                    response.setPage(page);
-                    await tool.handler({
-                        params,
-                        page,
-                    }, response, context);
-                }
-                else {
-                    await tool.handler(
-                    // @ts-expect-error types do not match.
-                    {
-                        params,
-                    }, response, context);
-                }
-                const { content, structuredContent } = await response.handle(tool.name, context);
-                const result = {
-                    content,
-                };
-                success = true;
-                if (serverArgs.experimentalStructuredContent) {
-                    result.structuredContent = structuredContent;
-                }
-                return result;
-            }
-            catch (err) {
-                logger(`${tool.name} error:`, err, err?.stack);
-                let errorText = err && 'message' in err ? err.message : String(err);
-                if ('cause' in err && err.cause) {
-                    errorText += `\nCause: ${err.cause.message}`;
-                }
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: errorText,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            finally {
-                void clearcutLogger?.logToolInvocation({
-                    toolName: tool.name,
-                    success,
-                    latencyMs: bucketizeLatency(Date.now() - startTime),
-                });
-                guard.dispose();
-            }
-        });
-    }
-    const tools = createTools(serverArgs);
-    for (const tool of tools) {
-        registerTool(tool);
-    }
-    await loadIssueDescriptions();
-    return { server, clearcutLogger };
-}
-export const logDisclaimers = (args) => {
-    console.error(`chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
-debug, and modify any data in the browser or DevTools.
-Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
-    if (!args.slim && args.performanceCrux) {
-        console.error(`Performance tools may send trace URLs to the Google CrUX API to fetch real-user experience data. To disable, run with --no-performance-crux.`);
-    }
-    if (!args.slim && args.usageStatistics) {
-        console.error(`
-Google collects usage statistics to improve Chrome DevTools MCP. To opt-out, run with --no-usage-statistics.
-For more details, visit: https://github.com/ChromeDevTools/chrome-devtools-mcp#usage-statistics`);
-    }
-};

package/build/src/issue-descriptions.js

@@ -1,39 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-const DESCRIPTIONS_PATH = path.join(import.meta.dirname, 'third_party/issue-descriptions');
-let issueDescriptions = {};
-/**
- * Reads all issue descriptions from the filesystem into memory.
- */
-export async function loadIssueDescriptions() {
-    if (Object.keys(issueDescriptions).length > 0) {
-        return;
-    }
-    const files = await fs.promises.readdir(DESCRIPTIONS_PATH);
-    const descriptions = {};
-    for (const file of files) {
-        if (!file.endsWith('.md')) {
-            continue;
-        }
-        const content = await fs.promises.readFile(path.join(DESCRIPTIONS_PATH, file), 'utf-8');
-        descriptions[file] = content;
-    }
-    issueDescriptions = descriptions;
-}
-/**
- * Gets an issue description from the in-memory cache.
- * @param fileName The file name of the issue description.
- * @returns The description of the issue, or null if it doesn't exist.
- */
-export function getIssueDescription(fileName) {
-    return issueDescriptions[fileName] ?? null;
-}
-export const ISSUE_UTILS = {
-    loadIssueDescriptions,
-    getIssueDescription,
-};

package/build/src/logger.js

@@ -1,36 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import fs from 'node:fs';
-import { debug } from './third_party/index.js';
-const mcpDebugNamespace = 'mcp:log';
-const namespacesToEnable = [
-    mcpDebugNamespace,
-    ...(process.env['DEBUG'] ? [process.env['DEBUG']] : []),
-];
-export function saveLogsToFile(fileName) {
-    // Enable overrides everything so we need to add them
-    debug.enable(namespacesToEnable.join(','));
-    const logFile = fs.createWriteStream(fileName, { flags: 'a+' });
-    debug.log = function (...chunks) {
-        logFile.write(`${chunks.join(' ')}\n`);
-    };
-    logFile.on('error', function (error) {
-        console.error(`Error when opening/writing to log file: ${error.message}`);
-        logFile.end();
-        process.exit(1);
-    });
-    return logFile;
-}
-export function flushLogs(logFile, timeoutMs = 2000) {
-    return new Promise((resolve, reject) => {
-        const timeout = setTimeout(reject, timeoutMs);
-        logFile.end(() => {
-            clearTimeout(timeout);
-            resolve();
-        });
-    });
-}
-export const logger = debug(mcpDebugNamespace);

package/build/src/polyfill.js

@@ -1,7 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google Inc.
- * SPDX-License-Identifier: Apache-2.0
- */
-// polyfills are now bundled with all other dependencies
-import './third_party/index.js';

package/build/src/telemetry/ClearcutLogger.js

@@ -1,102 +0,0 @@
-/**
- * @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 './WatchdogClient.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/WatchdogClient.js

@@ -1,60 +0,0 @@
-/**
- * @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/telemetry/flagUtils.js

@@ -1,45 +0,0 @@
-/**
- * @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/metricUtils.js

@@ -1,14 +0,0 @@
-/**
- * @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];
-}