chrome-devtools-mcp 0.20.2 → 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/DevtoolsUtils.js

@@ -6,52 +6,6 @@
 import { PuppeteerDevToolsConnection } from './DevToolsConnectionAdapter.js';
 import { Mutex } from './Mutex.js';
 import { DevTools } from './third_party/index.js';
-export function extractUrlLikeFromDevToolsTitle(title) {
-    const match = title.match(new RegExp(`DevTools - (.*)`));
-    return match?.[1] ?? undefined;
-}
-export function urlsEqual(url1, url2) {
-    const normalizedUrl1 = normalizeUrl(url1);
-    const normalizedUrl2 = normalizeUrl(url2);
-    return normalizedUrl1 === normalizedUrl2;
-}
-/**
- * For the sake of the MCP server, when we determine if two URLs are equal we
- * remove some parts:
- *
- * 1. We do not care about the protocol.
- * 2. We do not care about trailing slashes.
- * 3. We do not care about "www".
- * 4. We ignore the hash parts.
- *
- * For example, if the user types "record a trace on foo.com", we would want to
- * match a tab in the connected Chrome instance that is showing "www.foo.com/"
- */
-function normalizeUrl(url) {
-    let result = url.trim();
-    // Remove protocols
-    if (result.startsWith('https://')) {
-        result = result.slice(8);
-    }
-    else if (result.startsWith('http://')) {
-        result = result.slice(7);
-    }
-    // Remove 'www.'. This ensures that we find the right URL regardless of if the user adds `www` or not.
-    if (result.startsWith('www.')) {
-        result = result.slice(4);
-    }
-    // We use target URLs to locate DevTools but those often do
-    // no include hash.
-    const hashIdx = result.lastIndexOf('#');
-    if (hashIdx !== -1) {
-        result = result.slice(0, hashIdx);
-    }
-    // Remove trailing slash
-    if (result.endsWith('/')) {
-        result = result.slice(0, -1);
-    }
-    return result;
-}
 /**
  * A mock implementation of an issues manager that only implements the methods
  * that are actually used by the IssuesAggregator

package/build/src/McpContext.js

@@ -5,9 +5,9 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { extractUrlLikeFromDevToolsTitle, UniverseManager, urlsEqual, } from './DevtoolsUtils.js';
+import { UniverseManager } from './DevtoolsUtils.js';
 import { McpPage } from './McpPage.js';
-import { NetworkCollector, ConsoleCollector } from './PageCollector.js';
+import { NetworkCollector, ConsoleCollector, } from './PageCollector.js';
 import { Locator } from './third_party/index.js';
 import { PredefinedNetworkConditions } from './third_party/index.js';
 import { listPages } from './tools/pages.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.
@@ -467,38 +474,26 @@ export class McpContext {
     async detectOpenDevToolsWindows() {
         this.logger('Detecting open DevTools windows');
         const { pages } = await this.#getAllPages();
-        // Clear all devToolsPage references before re-detecting.
-        for (const mcpPage of this.#mcpPages.values()) {
-            mcpPage.devToolsPage = undefined;
-        }
-        for (const devToolsPage of pages) {
-            if (devToolsPage.url().startsWith('devtools://')) {
-                try {
-                    this.logger('Calling getTargetInfo for ' + devToolsPage.url());
-                    const data = await devToolsPage
-                        // @ts-expect-error no types for _client().
-                        ._client()
-                        .send('Target.getTargetInfo');
-                    const devtoolsPageTitle = data.targetInfo.title;
-                    const urlLike = extractUrlLikeFromDevToolsTitle(devtoolsPageTitle);
-                    if (!urlLike) {
-                        continue;
-                    }
-                    // TODO: lookup without a loop.
-                    for (const page of this.#pages) {
-                        if (urlsEqual(page.url(), urlLike)) {
-                            const mcpPage = this.#mcpPages.get(page);
-                            if (mcpPage) {
-                                mcpPage.devToolsPage = devToolsPage;
-                            }
-                        }
-                    }
+        await Promise.all(pages.map(async (page) => {
+            const mcpPage = this.#mcpPages.get(page);
+            if (!mcpPage) {
+                return;
+            }
+            // Prior to Chrome 144.0.7559.59, the command fails,
+            // Some Electron apps still use older version
+            // Fall back to not exposing DevTools at all.
+            try {
+                if (await page.hasDevTools()) {
+                    mcpPage.devToolsPage = await page.openDevTools();
                 }
-                catch (error) {
-                    this.logger('Issue occurred while trying to find DevTools', error);
+                else {
+                    mcpPage.devToolsPage = undefined;
                 }
             }
-        }
+            catch {
+                mcpPage.devToolsPage = undefined;
+            }
+        }));
     }
     getExtensionServiceWorkers() {
         return this.#extensionServiceWorkers;

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

@@ -28,7 +28,7 @@ export class PageCollector {
     #browser;
     #listenersInitializer;
     #listeners = new WeakMap();
-    #maxNavigationSaved = 3;
+    maxNavigationSaved = 3;
     /**
      * This maps a Page to a list of navigations with a sub-list
      * of all collected resources.
@@ -109,7 +109,7 @@ export class PageCollector {
         }
         // Add the latest navigation first
         navigations.unshift([]);
-        navigations.splice(this.#maxNavigationSaved);
+        navigations.splice(this.maxNavigationSaved);
     }
     cleanupPageDestroyed(page) {
         const listeners = this.#listeners.get(page);
@@ -129,7 +129,7 @@ export class PageCollector {
             return navigations[0];
         }
         const data = [];
-        for (let index = this.#maxNavigationSaved; index >= 0; index--) {
+        for (let index = this.maxNavigationSaved; index >= 0; index--) {
             if (navigations[index]) {
                 data.push(...navigations[index]);
             }
@@ -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;
         }
@@ -305,5 +305,6 @@ export class NetworkCollector extends PageCollector {
         else {
             navigations.unshift([]);
         }
+        navigations.splice(this.maxNavigationSaved);
     }
 }

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

@@ -8,7 +8,7 @@ export const cliOptions = {
     autoConnect: {
         type: 'boolean',
         description: 'If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remoted debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.',
-        conflicts: ['isolated', 'executablePath'],
+        conflicts: ['isolated', 'executablePath', 'categoryExtensions'],
         default: false,
         coerce: (value) => {
             if (!value) {
@@ -21,7 +21,7 @@ export const cliOptions = {
         type: 'string',
         description: 'Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.',
         alias: 'u',
-        conflicts: 'wsEndpoint',
+        conflicts: ['wsEndpoint', 'categoryExtensions'],
         coerce: (url) => {
             if (!url) {
                 return;
@@ -39,7 +39,7 @@ export const cliOptions = {
         type: 'string',
         description: 'WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',
         alias: 'w',
-        conflicts: 'browserUrl',
+        conflicts: ['browserUrl', 'categoryExtensions'],
         coerce: (url) => {
             if (!url) {
                 return;
@@ -193,9 +193,14 @@ export const cliOptions = {
     },
     categoryExtensions: {
         type: 'boolean',
-        default: false,
         hidden: true,
-        describe: 'Set to false to exclude tools related to extensions.',
+        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',

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);
@@ -95,7 +101,11 @@ export async function createMcpServer(serverArgs, options) {
             return;
         }
         if (tool.annotations.category === ToolCategory.EXTENSIONS &&
-            serverArgs.categoryExtensions === false) {
+            !serverArgs.categoryExtensions) {
+            return;
+        }
+        if (tool.annotations.category === ToolCategory.IN_PAGE &&
+            !serverArgs.categoryInPageTools) {
             return;
         }
         if (tool.annotations.conditions?.includes('computerVision') &&