chrome-devtools-mcp 0.12.0 → 0.13.0

package/build/src/cli.js

@@ -139,15 +139,34 @@ export const cliOptions = {
         describe: 'Whether to enable automation over DevTools targets',
         hidden: true,
     },
+    experimentalVision: {
+        type: 'boolean',
+        describe: 'Whether to enable vision tools',
+        hidden: true,
+    },
+    experimentalStructuredContent: {
+        type: 'boolean',
+        describe: 'Whether to output structured formatted content.',
+        hidden: true,
+    },
     experimentalIncludeAllPages: {
         type: 'boolean',
         describe: 'Whether to include all kinds of pages such as webviews or background pages as pages.',
         hidden: true,
     },
+    experimentalInteropTools: {
+        type: 'boolean',
+        describe: 'Whether to enable interoperability tools',
+        hidden: true,
+    },
     chromeArg: {
         type: 'array',
         describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
     },
+    ignoreDefaultChromeArg: {
+        type: 'array',
+        describe: 'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
+    },
     categoryEmulation: {
         type: 'boolean',
         default: true,
@@ -163,6 +182,13 @@ export const cliOptions = {
         default: true,
         describe: 'Set to false to exclude tools related to network.',
     },
+    usageStatistics: {
+        type: 'boolean',
+        // Marked as `false` until the feature is ready to be enabled by default.
+        default: false,
+        hidden: true,
+        describe: 'Set to false to opt-out of usage statistics collection.',
+    },
 };
 export function parseArguments(version, argv = process.argv) {
     const yargsInstance = yargs(hideBin(argv))
@@ -206,6 +232,10 @@ export function parseArguments(version, argv = process.argv) {
             `$0 --chrome-arg='--no-sandbox' --chrome-arg='--disable-setuid-sandbox'`,
             'Launch Chrome without sandboxes. Use with caution.',
         ],
+        [
+            `$0 --ignore-default-chrome-arg='--disable-extensions'`,
+            'Disable the default arguments provided by Puppeteer. Use with caution.',
+        ],
         ['$0 --no-category-emulation', 'Disable tools in the emulation category'],
         [
             '$0 --no-category-performance',

package/build/src/formatters/SnapshotFormatter.js

@@ -0,0 +1,128 @@
+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',
+]);

package/build/src/formatters/consoleFormatter.js

@@ -25,6 +25,7 @@ export function formatConsoleEventVerbose(msg, context) {
         `ID: ${msg.consoleMessageStableId}`,
         `Message: ${msg.type}> ${aggregatedIssue ? formatIssue(aggregatedIssue, msg.description, context) : msg.message}`,
         aggregatedIssue ? undefined : formatArgs(msg),
+        formatStackTrace(msg.stackTrace),
     ].filter(line => !!line);
     return result.join('\n');
 }
@@ -49,8 +50,9 @@ export function formatIssue(issue, description, context) {
     if (processedMarkdown?.startsWith('# ')) {
         processedMarkdown = processedMarkdown.substring(2).trimStart();
     }
-    if (processedMarkdown)
+    if (processedMarkdown) {
         result.push(processedMarkdown);
+    }
     const links = issue.getDescription()?.links;
     if (links && links.length > 0) {
         result.push('Learn more:');
@@ -62,8 +64,9 @@ export function formatIssue(issue, description, context) {
     const affectedResources = [];
     for (const singleIssue of issues) {
         const details = singleIssue.details();
-        if (!details)
+        if (!details) {
             continue;
+        }
         // We send the remaining details as untyped JSON because the DevTools
         // frontend code is currently not re-usable.
         // eslint-disable-next-line
@@ -106,16 +109,48 @@ export function formatIssue(issue, description, context) {
     }
     result.push(...affectedResources.map(item => {
         const details = [];
-        if (item.uid)
+        if (item.uid) {
             details.push(`uid=${item.uid}`);
+        }
         if (item.request) {
             details.push((typeof item.request === 'number' ? `reqid=` : 'url=') + item.request);
         }
-        if (item.data)
+        if (item.data) {
             details.push(`data=${JSON.stringify(item.data)}`);
+        }
         return details.join(' ');
     }));
-    if (result.length === 0)
+    if (result.length === 0) {
         return 'No affected resources found';
+    }
     return result.join('\n');
 }
+function formatStackTrace(stackTrace) {
+    if (!stackTrace) {
+        return '';
+    }
+    return [
+        '### Stack trace',
+        formatFragment(stackTrace.syncFragment),
+        ...stackTrace.asyncFragments.map(formatAsyncFragment),
+    ].join('\n');
+}
+function formatFragment(fragment) {
+    return fragment.frames.map(formatFrame).join('\n');
+}
+function formatAsyncFragment(fragment) {
+    const separatorLineLength = 40;
+    const prefix = `--- ${fragment.description || 'async'} `;
+    const separator = prefix + '-'.repeat(separatorLineLength - prefix.length);
+    return separator + '\n' + formatFragment(fragment);
+}
+function formatFrame(frame) {
+    let result = `at ${frame.name ?? '<anonymous>'}`;
+    if (frame.uiSourceCode) {
+        result += ` (${frame.uiSourceCode.displayName()}:${frame.line}:${frame.column})`;
+    }
+    else if (frame.url) {
+        result += ` (${frame.url}:${frame.line}:${frame.column})`;
+    }
+    return result;
+}

package/build/src/issue-descriptions.js

@@ -5,7 +5,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-const DESCRIPTIONS_PATH = path.join(import.meta.dirname, '../node_modules/chrome-devtools-frontend/front_end/models/issues_manager/descriptions');
+const DESCRIPTIONS_PATH = path.join(import.meta.dirname, 'third_party/issue-descriptions');
 let issueDescriptions = {};
 /**
  * Reads all issue descriptions from the filesystem into memory.

package/build/src/main.js

@@ -4,22 +4,32 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import './polyfill.js';
+import process from 'node:process';
 import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
-import { parseArguments } from './cli.js';
+import { cliOptions, parseArguments } from './cli.js';
 import { loadIssueDescriptions } from './issue-descriptions.js';
 import { logger, saveLogsToFile } from './logger.js';
 import { McpContext } from './McpContext.js';
 import { McpResponse } from './McpResponse.js';
 import { Mutex } from './Mutex.js';
+import { ClearcutLogger } from './telemetry/clearcut-logger.js';
+import { computeFlagUsage } from './telemetry/flag-utils.js';
 import { McpServer, StdioServerTransport, SetLevelRequestSchema, } from './third_party/index.js';
 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.12.0';
+const VERSION = '0.13.0';
 // x-release-please-end
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+let clearcutLogger;
+if (args.usageStatistics) {
+    clearcutLogger = new ClearcutLogger();
+}
+process.on('unhandledRejection', (reason, promise) => {
+    logger('Unhandled promise rejection', promise, reason);
+});
 logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
 const server = new McpServer({
     name: 'chrome_devtools',
@@ -31,9 +41,10 @@ server.server.setRequestHandler(SetLevelRequestSchema, () => {
 });
 let context;
 async function getContext() {
-    const extraArgs = (args.chromeArg ?? []).map(String);
+    const chromeArgs = (args.chromeArg ?? []).map(String);
+    const ignoreDefaultChromeArgs = (args.ignoreDefaultChromeArg ?? []).map(String);
     if (args.proxyServer) {
-        extraArgs.push(`--proxy-server=${args.proxyServer}`);
+        chromeArgs.push(`--proxy-server=${args.proxyServer}`);
     }
     const devtools = args.experimentalDevtools ?? false;
     const browser = args.browserUrl || args.wsEndpoint || args.autoConnect
@@ -54,7 +65,8 @@ async function getContext() {
             userDataDir: args.userDataDir,
             logFile,
             viewport: args.viewport,
-            args: extraArgs,
+            chromeArgs,
+            ignoreDefaultChromeArgs,
             acceptInsecureCerts: args.acceptInsecureCerts,
             devtools,
         });
@@ -70,6 +82,11 @@ const logDisclaimers = () => {
     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.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`);
+    }
 };
 const toolMutex = new Mutex();
 function registerTool(tool) {
@@ -85,12 +102,22 @@ function registerTool(tool) {
         args.categoryNetwork === false) {
         return;
     }
+    if (tool.annotations.conditions?.includes('computerVision') &&
+        !args.experimentalVision) {
+        return;
+    }
+    if (tool.annotations.conditions?.includes('experimentalInteropTools') &&
+        !args.experimentalInteropTools) {
+        return;
+    }
     server.registerTool(tool.name, {
         description: tool.description,
         inputSchema: tool.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();
@@ -100,10 +127,15 @@ function registerTool(tool) {
             await tool.handler({
                 params,
             }, response, context);
-            const content = await response.handle(tool.name, context);
-            return {
+            const { content, structuredContent } = await response.handle(tool.name, context);
+            const result = {
                 content,
             };
+            success = true;
+            if (args.experimentalStructuredContent) {
+                result.structuredContent = structuredContent;
+            }
+            return result;
         }
         catch (err) {
             logger(`${tool.name} error:`, err, err?.stack);
@@ -122,6 +154,11 @@ function registerTool(tool) {
             };
         }
         finally {
+            void clearcutLogger?.logToolInvocation({
+                toolName: tool.name,
+                success,
+                latencyMs: Date.now() - startTime,
+            });
             guard.dispose();
         }
     });
@@ -134,3 +171,4 @@ const transport = new StdioServerTransport();
 await server.connect(transport);
 logger('Chrome DevTools MCP Server connected');
 logDisclaimers();
+void clearcutLogger?.logServerStart(computeFlagUsage(args, cliOptions));

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

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ClearcutSender } from './clearcut-sender.js';
+export class ClearcutLogger {
+    #sender;
+    constructor(sender) {
+        this.#sender = sender ?? new ClearcutSender();
+    }
+    async logToolInvocation(args) {
+        await this.#sender.send({
+            tool_invocation: {
+                tool_name: args.toolName,
+                success: args.success,
+                latency_ms: args.latencyMs,
+            },
+        });
+    }
+    async logServerStart(flagUsage) {
+        await this.#sender.send({
+            server_start: {
+                flag_usage: flagUsage,
+            },
+        });
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from '../logger.js';
+export class ClearcutSender {
+    async send(event) {
+        logger('Telemetry event', JSON.stringify(event, null, 2));
+    }
+}

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] = value.toUpperCase();
+        }
+    }
+    return usage;
+}

package/build/src/telemetry/types.js

@@ -0,0 +1,27 @@
+/**
+ * @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 = {}));