chrome-devtools-mcp 0.20.3 → 0.21.0

package/README.md

@@ -27,6 +27,10 @@ allowing them to inspect, debug, and modify any data in the browser or DevTools.
 Avoid sharing sensitive or personal information that you don't want to share with
 MCP clients.
 
+`chrome-devtools-mcp` officially supports Google Chrome and [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) only.
+Other Chromium-based browser may work, but this is not guaranteed, and you may encounter unexpected behavior. Use at your own discretion.
+We are committed to providing fixes and support for the latest version of [Extended Stable Chrome](https://chromiumdash.appspot.com/schedule).
+
 Performance tools may send trace URLs to the Google CrUX API to fetch real-user
 experience data. This helps provide a holistic performance picture by
 presenting field data alongside lab data. This data is collected by the [Chrome
@@ -53,7 +57,7 @@ Collection is disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env vari
 
 - [Node.js](https://nodejs.org/) v20.19 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.
 - [Chrome](https://www.google.com/chrome/) current stable version or newer.
-- [npm](https://www.npmjs.com/).
+- [npm](https://www.npmjs.com/)
 
 ## Getting started
 
@@ -194,6 +198,17 @@ startup_timeout_ms = 20_000
 
 </details>
 
+<details>
+  <summary>Command Code</summary>
+  
+Use the Command Code CLI to add the Chrome DevTools MCP server (<a href="https://commandcode.ai/docs/mcp">MCP guide</a>):
+
+```bash
+cmd mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
+```
+
+</details>
+
 <details>
   <summary>Copilot CLI</summary>
 

package/build/src/McpContext.js

@@ -48,6 +48,7 @@ export class McpContext {
     #extensionRegistry = new ExtensionRegistry();
     #isRunningTrace = false;
     #screenRecorderData = null;
+    #inPageTools;
     #nextPageId = 1;
     #extensionPages = new WeakMap();
     #extensionServiceWorkerMap = new WeakMap();
@@ -328,6 +329,12 @@ export class McpContext {
         this.#selectedPage = newPage;
         this.#updateSelectedPageTimeouts();
     }
+    setInPageTools(toolGroup) {
+        this.#inPageTools = toolGroup;
+    }
+    getInPageTools() {
+        return this.#inPageTools;
+    }
     #updateSelectedPageTimeouts() {
         const page = this.#getSelectedMcpPage();
         // For waiters 5sec timeout should be sufficient.

package/build/src/McpResponse.js

@@ -12,6 +12,50 @@ import { DevTools } from './third_party/index.js';
 import { handleDialog } from './tools/pages.js';
 import { getInsightOutput, getTraceSummary } from './trace-processing/parse.js';
 import { paginate } from './utils/pagination.js';
+async function getToolGroup(page) {
+    // Check if there is a `devtoolstooldiscovery` event listener
+    const windowHandle = await page.pptrPage.evaluateHandle(() => window);
+    // @ts-expect-error internal API
+    const client = page.pptrPage._client();
+    const { listeners } = await client.send('DOMDebugger.getEventListeners', {
+        objectId: windowHandle.remoteObject().objectId,
+    });
+    if (listeners.find(l => l.type === 'devtoolstooldiscovery') === undefined) {
+        return;
+    }
+    const toolGroup = await page.pptrPage.evaluate(() => {
+        return new Promise(resolve => {
+            const event = new CustomEvent('devtoolstooldiscovery');
+            // @ts-expect-error Adding custom property
+            event.respondWith = (toolGroup) => {
+                if (!window.__dtmcp) {
+                    window.__dtmcp = {};
+                }
+                window.__dtmcp.toolGroup = toolGroup;
+                // When receiving a toolGroup for the first time, expose a simple execution helper
+                if (!window.__dtmcp.executeTool) {
+                    window.__dtmcp.executeTool = async (toolName, args) => {
+                        if (!window.__dtmcp?.toolGroup) {
+                            throw new Error('No tools found on the page');
+                        }
+                        const tool = window.__dtmcp.toolGroup.tools.find(t => t.name === toolName);
+                        if (!tool) {
+                            throw new Error(`Tool ${toolName} not found`);
+                        }
+                        return await tool.execute(args);
+                    };
+                }
+                resolve(toolGroup);
+            };
+            window.dispatchEvent(event);
+            // If the page does not synchronously call `event.respondWith`, return instead of timing out
+            setTimeout(() => {
+                resolve(undefined);
+            }, 0);
+        });
+    });
+    return toolGroup;
+}
 export class McpResponse {
     #includePages = false;
     #includeExtensionServiceWorkers = false;
@@ -28,6 +72,7 @@ export class McpResponse {
     #networkRequestsOptions;
     #consoleDataOptions;
     #listExtensions;
+    #listInPageTools;
     #devToolsData;
     #tabId;
     #args;
@@ -59,6 +104,11 @@ export class McpResponse {
     setListExtensions() {
         this.#listExtensions = true;
     }
+    setListInPageTools() {
+        if (this.#args.categoryInPageTools) {
+            this.#listInPageTools = true;
+        }
+    }
     setIncludeNetworkRequests(value, options) {
         if (!value) {
             this.#networkRequestsOptions = undefined;
@@ -94,8 +144,8 @@ export class McpResponse {
             includePreservedMessages: options?.includePreservedMessages,
         };
     }
-    attachNetworkRequest(reqid, options) {
-        this.#attachedNetworkRequestId = reqid;
+    attachNetworkRequest(reqId, options) {
+        this.#attachedNetworkRequestId = reqId;
         this.#attachedNetworkRequestOptions = options;
     }
     attachConsoleMessage(msgid) {
@@ -223,7 +273,7 @@ export class McpResponse {
                     elementIdResolver: context.resolveCdpElementId.bind(context, this.#page),
                 });
                 if (!formatter.isValid()) {
-                    throw new Error("Can't provide detals for the msgid " + consoleMessageStableId);
+                    throw new Error("Can't provide details for the msgid " + consoleMessageStableId);
                 }
                 detailedConsoleMessage = formatter;
             }
@@ -232,6 +282,11 @@ export class McpResponse {
         if (this.#listExtensions) {
             extensions = context.listExtensions();
         }
+        let inPageTools;
+        if (this.#listInPageTools) {
+            inPageTools = await getToolGroup(context.getSelectedMcpPage());
+            context.setInPageTools(inPageTools);
+        }
         let consoleMessages;
         if (this.#consoleDataOptions?.include) {
             if (!this.#page) {
@@ -308,6 +363,7 @@ export class McpResponse {
             traceSummary: this.#attachedTraceSummary,
             extensions,
             lighthouseResult: this.#attachedLighthouseResult,
+            inPageTools,
         });
     }
     format(toolName, context, data) {
@@ -498,6 +554,24 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(extensionsMessage);
             }
         }
+        if (this.#listInPageTools) {
+            structuredContent.inPageTools = data.inPageTools ?? undefined;
+            response.push('## In-page tools');
+            if (!data.inPageTools || !data.inPageTools.tools) {
+                response.push('No in-page tools available.');
+            }
+            else {
+                const toolGroup = data.inPageTools;
+                response.push(`${toolGroup.name}: ${toolGroup.description}`);
+                response.push('Available tools:');
+                const toolDefinitionsMessage = toolGroup.tools
+                    .map(tool => {
+                    return `name="${tool.name}", description="${tool.description}", inputSchema=${JSON.stringify(tool.inputSchema)}`;
+                })
+                    .join('\n');
+                response.push(toolDefinitionsMessage);
+            }
+        }
         if (this.#networkRequestsOptions?.include && data.networkRequests) {
             const requests = data.networkRequests;
             response.push('## Network requests');

package/build/src/PageCollector.js

@@ -198,10 +198,10 @@ class PageEventSubscriber {
     #resetIssueAggregator() {
         this.#issueManager = new FakeIssuesManager();
         if (this.#issueAggregator) {
-            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
+            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedIssue);
         }
         this.#issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
-        this.#issueAggregator.addEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
+        this.#issueAggregator.addEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedIssue);
     }
     async subscribe() {
         this.#resetIssueAggregator();
@@ -222,13 +222,13 @@ class PageEventSubscriber {
         this.#session.off('Audits.issueAdded', this.#onIssueAdded);
         this.#session.off('Runtime.exceptionThrown', this.#onExceptionThrown);
         if (this.#issueAggregator) {
-            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
+            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedIssue);
         }
         void this.#session.send('Audits.disable').catch(() => {
             // might fail.
         });
     }
-    #onAggregatedissue = (event) => {
+    #onAggregatedIssue = (event) => {
         if (this.#seenIssues.has(event.data)) {
             return;
         }

package/build/src/bin/chrome-devtools-mcp-cli-options.js

@@ -197,6 +197,11 @@ export const cliOptions = {
         conflicts: ['browserUrl', 'autoConnect', 'wsEndpoint'],
         describe: 'Set to true to include tools related to extensions. Note: This feature is only supported with a pipe connection. autoConnect is not supported.',
     },
+    categoryInPageTools: {
+        type: 'boolean',
+        hidden: true,
+        describe: 'Set to true to enable tools exposed by the inspected page itself',
+    },
     performanceCrux: {
         type: 'boolean',
         default: true,

package/build/src/bin/chrome-devtools-mcp.js

@@ -4,6 +4,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+process.title = 'chrome-devtools-mcp';
 import { version } from 'node:process';
 const [major, minor] = version.substring(1).split('.').map(Number);
 if (major === 20 && minor < 19) {

package/build/src/bin/chrome-devtools.js

@@ -4,6 +4,7 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+process.title = 'chrome-devtools';
 import process from 'node:process';
 import { startDaemon, stopDaemon, sendCommand, handleResponse, } from '../daemon/client.js';
 import { isDaemonRunning, serializeArgs } from '../daemon/utils.js';
@@ -26,7 +27,7 @@ delete startCliOptions.autoConnect;
 // Missing CLI serialization.
 delete startCliOptions.viewport;
 // CLI is generated based on the default tool definitions. To enable conditional
-// tools, they needs to be enabled during CLI generation.
+// tools, they need to be enabled during CLI generation.
 delete startCliOptions.experimentalPageIdRouting;
 delete startCliOptions.experimentalVision;
 delete startCliOptions.experimentalInteropTools;
@@ -42,9 +43,11 @@ if (!('default' in cliOptions.headless)) {
     throw new Error('headless cli option unexpectedly does not have a default');
 }
 if ('default' in cliOptions.isolated) {
-    throw new Error('headless cli option unexpectedly does not have a default');
+    throw new Error('isolated cli option unexpectedly has a default');
 }
 startCliOptions.headless.default = true;
+startCliOptions.isolated.description =
+    'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to true unless userDataDir is provided.';
 const y = yargs(hideBin(process.argv))
     .scriptName('chrome-devtools')
     .showHelpOnFail(true)
@@ -63,7 +66,7 @@ y.command('start', 'Start or restart chrome-devtools-mcp', y => y
         await stopDaemon();
     }
     // Defaults but we do not want to affect the yargs conflict resolution.
-    if (argv.isolated === undefined) {
+    if (argv.isolated === undefined && argv.userDataDir === undefined) {
         argv.isolated = true;
     }
     if (argv.headless === undefined) {

package/build/src/bin/cliDefinitions.js

@@ -503,7 +503,7 @@ export const commands = {
         },
     },
     take_memory_snapshot: {
-        description: 'Capture a memory heapsnapshot of the currently selected page to memory leak debugging',
+        description: 'Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.',
         category: 'Performance',
         args: {
             filePath: {

package/build/src/daemon/daemon.js

@@ -11,7 +11,7 @@ import process from 'node:process';
 import { logger } from '../logger.js';
 import { Client, PipeTransport, StdioClientTransport, } from '../third_party/index.js';
 import { VERSION } from '../version.js';
-import { getDaemonPid, getPidFilePath, getSocketPath, INDEX_SCRIPT_PATH, IS_WINDOWS, isDaemonRunning, } from './utils.js';
+import { DAEMON_CLIENT_NAME, getDaemonPid, getPidFilePath, getSocketPath, INDEX_SCRIPT_PATH, IS_WINDOWS, isDaemonRunning, } from './utils.js';
 const pid = getDaemonPid();
 if (isDaemonRunning(pid)) {
     logger('Another daemon process is running.');
@@ -42,7 +42,7 @@ async function setupMCPClient() {
         env: process.env,
     });
     mcpClient = new Client({
-        name: 'chrome-devtools-cli-daemon',
+        name: DAEMON_CLIENT_NAME,
         version: VERSION,
     }, {
         capabilities: {},

package/build/src/daemon/utils.js

@@ -11,6 +11,7 @@ import { logger } from '../logger.js';
 export const DAEMON_SCRIPT_PATH = path.join(import.meta.dirname, 'daemon.js');
 export const INDEX_SCRIPT_PATH = path.join(import.meta.dirname, '..', 'bin', 'chrome-devtools-mcp.js');
 const APP_NAME = 'chrome-devtools-mcp';
+export const DAEMON_CLIENT_NAME = 'chrome-devtools-cli-daemon';
 // Using these paths due to strict limits on the POSIX socket path length.
 export function getSocketPath() {
     const uid = os.userInfo().uid;

package/build/src/index.js

@@ -36,6 +36,12 @@ export async function createMcpServer(serverArgs, options) {
     server.server.setRequestHandler(SetLevelRequestSchema, () => {
         return {};
     });
+    server.server.oninitialized = () => {
+        const clientName = server.server.getClientVersion()?.name;
+        if (clientName) {
+            clearcutLogger?.setClientName(clientName);
+        }
+    };
     let context;
     async function getContext() {
         const chromeArgs = (serverArgs.chromeArg ?? []).map(String);
@@ -98,6 +104,10 @@ export async function createMcpServer(serverArgs, options) {
             !serverArgs.categoryExtensions) {
             return;
         }
+        if (tool.annotations.category === ToolCategory.IN_PAGE &&
+            !serverArgs.categoryInPageTools) {
+            return;
+        }
         if (tool.annotations.conditions?.includes('computerVision') &&
             !serverArgs.experimentalVision) {
             return;

package/build/src/telemetry/ClearcutLogger.js

@@ -4,11 +4,99 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import process from 'node:process';
+import { DAEMON_CLIENT_NAME } from '../daemon/utils.js';
 import { logger } from '../logger.js';
 import { FilePersistence } from './persistence.js';
-import { WatchdogMessageType, OsType } from './types.js';
+import { McpClient, WatchdogMessageType, OsType, } from './types.js';
 import { WatchdogClient } from './WatchdogClient.js';
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const PARAM_BLOCKLIST = new Set(['uid']);
+const SUPPORTED_ZOD_TYPES = [
+    'ZodString',
+    'ZodNumber',
+    'ZodBoolean',
+    'ZodArray',
+    'ZodEnum',
+];
+function isZodType(type) {
+    return SUPPORTED_ZOD_TYPES.includes(type);
+}
+function getZodType(zodType) {
+    const def = zodType._def;
+    const typeName = def.typeName;
+    if (typeName === 'ZodOptional' ||
+        typeName === 'ZodDefault' ||
+        typeName === 'ZodNullable') {
+        return getZodType(def.innerType);
+    }
+    if (typeName === 'ZodEffects') {
+        return getZodType(def.schema);
+    }
+    if (isZodType(typeName)) {
+        return typeName;
+    }
+    throw new Error(`Unsupported zod type for tool parameter: ${typeName}`);
+}
+function transformName(zodType, name) {
+    if (zodType === 'ZodString') {
+        return `${name}_length`;
+    }
+    else if (zodType === 'ZodArray') {
+        return `${name}_count`;
+    }
+    else {
+        return name;
+    }
+}
+function transformValue(zodType, value) {
+    if (zodType === 'ZodString') {
+        return value.length;
+    }
+    else if (zodType === 'ZodArray') {
+        return value.length;
+    }
+    else {
+        return value;
+    }
+}
+function hasEquivalentType(zodType, value) {
+    if (zodType === 'ZodString') {
+        return typeof value === 'string';
+    }
+    else if (zodType === 'ZodArray') {
+        return Array.isArray(value);
+    }
+    else if (zodType === 'ZodNumber') {
+        return typeof value === 'number';
+    }
+    else if (zodType === 'ZodBoolean') {
+        return typeof value === 'boolean';
+    }
+    else if (zodType === 'ZodEnum') {
+        return (typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean');
+    }
+    else {
+        return false;
+    }
+}
+export function sanitizeParams(params, schema) {
+    const transformed = {};
+    for (const [name, value] of Object.entries(params)) {
+        if (PARAM_BLOCKLIST.has(name)) {
+            continue;
+        }
+        const zodType = getZodType(schema[name]);
+        if (!hasEquivalentType(zodType, value)) {
+            throw new Error(`parameter ${name} has type ${zodType} but value ${value} is not of equivalent type`);
+        }
+        const transformedName = transformName(zodType, name);
+        const transformedValue = transformValue(zodType, value);
+        transformed[transformedName] = transformedValue;
+    }
+    return transformed;
+}
 function detectOsType() {
     switch (process.platform) {
         case 'win32':
@@ -24,6 +112,7 @@ function detectOsType() {
 export class ClearcutLogger {
     #persistence;
     #watchdog;
+    #mcpClient;
     constructor(options) {
         this.#persistence = options.persistence ?? new FilePersistence();
         this.#watchdog =
@@ -37,11 +126,37 @@ export class ClearcutLogger {
                     clearcutForceFlushIntervalMs: options.clearcutForceFlushIntervalMs,
                     clearcutIncludePidHeader: options.clearcutIncludePidHeader,
                 });
+        this.#mcpClient = McpClient.MCP_CLIENT_UNSPECIFIED;
+    }
+    setClientName(clientName) {
+        const lowerName = clientName.toLowerCase();
+        if (lowerName.includes('claude')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_CLAUDE_CODE;
+        }
+        else if (lowerName.includes('gemini')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_GEMINI_CLI;
+        }
+        else if (clientName === DAEMON_CLIENT_NAME) {
+            this.#mcpClient = McpClient.MCP_CLIENT_DT_MCP_CLI;
+        }
+        else if (lowerName.includes('openclaw')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_OPENCLAW;
+        }
+        else if (lowerName.includes('codex')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_CODEX;
+        }
+        else if (lowerName.includes('antigravity')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_ANTIGRAVITY;
+        }
+        else {
+            this.#mcpClient = McpClient.MCP_CLIENT_OTHER;
+        }
     }
     async logToolInvocation(args) {
         this.#watchdog.send({
             type: WatchdogMessageType.LOG_EVENT,
             payload: {
+                mcp_client: this.#mcpClient,
                 tool_invocation: {
                     tool_name: args.toolName,
                     success: args.success,
@@ -54,6 +169,7 @@ export class ClearcutLogger {
         this.#watchdog.send({
             type: WatchdogMessageType.LOG_EVENT,
             payload: {
+                mcp_client: this.#mcpClient,
                 server_start: {
                     flag_usage: flagUsage,
                 },
@@ -74,6 +190,7 @@ export class ClearcutLogger {
                 this.#watchdog.send({
                     type: WatchdogMessageType.LOG_EVENT,
                     payload: {
+                        mcp_client: this.#mcpClient,
                         daily_active: {
                             days_since_last_active: daysSince,
                         },

package/build/src/telemetry/types.js

@@ -24,6 +24,11 @@ export var 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["MCP_CLIENT_DT_MCP_CLI"] = 4] = "MCP_CLIENT_DT_MCP_CLI";
+    McpClient[McpClient["MCP_CLIENT_OPENCLAW"] = 5] = "MCP_CLIENT_OPENCLAW";
+    McpClient[McpClient["MCP_CLIENT_CODEX"] = 6] = "MCP_CLIENT_CODEX";
+    McpClient[McpClient["MCP_CLIENT_ANTIGRAVITY"] = 7] = "MCP_CLIENT_ANTIGRAVITY";
+    McpClient[McpClient["MCP_CLIENT_OTHER"] = 3] = "MCP_CLIENT_OTHER";
 })(McpClient || (McpClient = {}));
 // IPC types for messages between the main process and the
 // telemetry watchdog process.