chrome-devtools-mcp 0.23.0 → 0.25.0

package/README.md

@@ -477,7 +477,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
 
 <!-- BEGIN AUTO GENERATED TOOLS -->
 
-- **Input automation** (9 tools)
+- **Input automation** (10 tools)
   - [`click`](docs/tool-reference.md#click)
   - [`drag`](docs/tool-reference.md#drag)
   - [`fill`](docs/tool-reference.md#fill)
@@ -487,6 +487,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`press_key`](docs/tool-reference.md#press_key)
   - [`type_text`](docs/tool-reference.md#type_text)
   - [`upload_file`](docs/tool-reference.md#upload_file)
+  - [`click_at`](docs/tool-reference.md#click_at)
 - **Navigation automation** (6 tools)
   - [`close_page`](docs/tool-reference.md#close_page)
   - [`list_pages`](docs/tool-reference.md#list_pages)
@@ -504,21 +505,32 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
 - **Network** (2 tools)
   - [`get_network_request`](docs/tool-reference.md#get_network_request)
   - [`list_network_requests`](docs/tool-reference.md#list_network_requests)
-- **Debugging** (6 tools)
+- **Debugging** (8 tools)
   - [`evaluate_script`](docs/tool-reference.md#evaluate_script)
   - [`get_console_message`](docs/tool-reference.md#get_console_message)
   - [`lighthouse_audit`](docs/tool-reference.md#lighthouse_audit)
   - [`list_console_messages`](docs/tool-reference.md#list_console_messages)
   - [`take_screenshot`](docs/tool-reference.md#take_screenshot)
   - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
+  - [`screencast_start`](docs/tool-reference.md#screencast_start)
+  - [`screencast_stop`](docs/tool-reference.md#screencast_stop)
+- **Memory** (4 tools)
+  - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
+  - [`get_memory_snapshot_details`](docs/tool-reference.md#get_memory_snapshot_details)
+  - [`get_nodes_by_class`](docs/tool-reference.md#get_nodes_by_class)
+  - [`load_memory_snapshot`](docs/tool-reference.md#load_memory_snapshot)
 - **Extensions** (5 tools)
   - [`install_extension`](docs/tool-reference.md#install_extension)
   - [`list_extensions`](docs/tool-reference.md#list_extensions)
   - [`reload_extension`](docs/tool-reference.md#reload_extension)
   - [`trigger_extension_action`](docs/tool-reference.md#trigger_extension_action)
   - [`uninstall_extension`](docs/tool-reference.md#uninstall_extension)
-- **Memory** (1 tools)
-  - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
+- **Third-party** (2 tools)
+  - [`execute_3p_developer_tool`](docs/tool-reference.md#execute_3p_developer_tool)
+  - [`list_3p_developer_tools`](docs/tool-reference.md#list_3p_developer_tools)
+- **WebMCP** (2 tools)
+  - [`execute_webmcp_tool`](docs/tool-reference.md#execute_webmcp_tool)
+  - [`list_webmcp_tools`](docs/tool-reference.md#list_webmcp_tools)
 
 <!-- END AUTO GENERATED TOOLS -->
 
@@ -595,7 +607,7 @@ The Chrome DevTools MCP server supports the following configuration option:
   Path to ffmpeg executable for screencast recording.
   - **Type:** string
 
-- **`--experimentalWebmcp`/ `--experimental-webmcp`**
+- **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`**
   Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`
   - **Type:** boolean
 
@@ -627,6 +639,11 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `false`
 
+- **`--categoryExperimentalThirdParty`/ `--category-experimental-third-party`**
+  Set to true to enable third-party developer tools exposed by the inspected page itself
+  - **Type:** boolean
+  - **Default:** `false`
+
 - **`--performanceCrux`/ `--performance-crux`**
   Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.
   - **Type:** boolean

package/build/src/DevToolsConnectionAdapter.js

@@ -67,3 +67,4 @@ export class PuppeteerDevToolsConnection {
         }
     }
 }
+//# sourceMappingURL=DevToolsConnectionAdapter.js.map

package/build/src/DevtoolsUtils.js

@@ -292,3 +292,4 @@ async function waitForScript(model, scriptId, signal) {
         });
     }
 }
+//# sourceMappingURL=DevtoolsUtils.js.map

package/build/src/HeapSnapshotManager.js

@@ -56,6 +56,17 @@ export class HeapSnapshotManager {
         }
         return uid;
     }
+    async getNodesByUid(filePath, uid) {
+        const snapshot = await this.getSnapshot(filePath);
+        const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+        const className = await this.resolveClassKeyFromUid(filePath, uid);
+        if (!className) {
+            throw new Error(`Class with UID ${uid} not found in heap snapshot`);
+        }
+        const provider = snapshot.createNodesProviderForClass(className, filter);
+        const range = await provider.serializeItemsRange(0, 1);
+        return await provider.serializeItemsRange(0, range.totalLength);
+    }
     #getCachedSnapshot(filePath) {
         const absolutePath = path.resolve(filePath);
         const cached = this.#snapshots.get(absolutePath);
@@ -64,6 +75,10 @@ export class HeapSnapshotManager {
         }
         return cached;
     }
+    async resolveClassKeyFromUid(filePath, uid) {
+        const cached = this.#getCachedSnapshot(filePath);
+        return cached.uidToClassKey.get(uid);
+    }
     async #loadSnapshot(absolutePath) {
         const workerProxy = new DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy(() => {
             /* noop */
@@ -92,3 +107,4 @@ export class HeapSnapshotManager {
         }
     }
 }
+//# sourceMappingURL=HeapSnapshotManager.js.map

package/build/src/McpContext.js

@@ -4,16 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { UniverseManager } from './DevtoolsUtils.js';
 import { HeapSnapshotManager } from './HeapSnapshotManager.js';
 import { McpPage } from './McpPage.js';
 import { NetworkCollector, ConsoleCollector, } from './PageCollector.js';
-import { Locator } from './third_party/index.js';
-import { PredefinedNetworkConditions } from './third_party/index.js';
+import { Locator, PredefinedNetworkConditions, } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
-import { ensureExtension, saveTemporaryFile } from './utils/files.js';
+import { ensureExtension, getTempFilePath } from './utils/files.js';
 import { getNetworkMultiplierFromString } from './WaitForHelper.js';
 const DEFAULT_TIMEOUT = 5_000;
 const NAVIGATION_TIMEOUT = 10_000;
@@ -41,6 +42,7 @@ export class McpContext {
     #locatorClass;
     #options;
     #heapSnapshotManager = new HeapSnapshotManager();
+    #roots = undefined;
     constructor(browser, logger, options, locatorClass) {
         this.browser = browser;
         this.logger = logger;
@@ -89,6 +91,39 @@ export class McpContext {
         await context.#init();
         return context;
     }
+    roots() {
+        if (this.#roots === undefined) {
+            return undefined;
+        }
+        return [
+            ...this.#roots,
+            {
+                uri: pathToFileURL(os.tmpdir()).href,
+                name: 'temp',
+            },
+        ];
+    }
+    setRoots(roots) {
+        this.#roots = roots;
+    }
+    validatePath(filePath) {
+        if (filePath === undefined) {
+            return;
+        }
+        const roots = this.roots();
+        if (roots === undefined) {
+            return;
+        }
+        const absolutePath = path.resolve(filePath);
+        for (const root of roots) {
+            const rootPath = path.resolve(fileURLToPath(root.uri));
+            if (absolutePath === rootPath ||
+                absolutePath.startsWith(rootPath + path.sep)) {
+                return;
+            }
+        }
+        throw new Error(`Access denied: path ${filePath} is not within any of the workspace roots ${JSON.stringify(roots)}.`);
+    }
     resolveCdpRequestId(page, cdpRequestId) {
         if (!cdpRequestId) {
             this.logger('no network request');
@@ -463,9 +498,18 @@ export class McpContext {
         return this.#mcpPages.get(page)?.isolatedContextName;
     }
     async saveTemporaryFile(data, filename) {
-        return await saveTemporaryFile(data, filename);
+        const filepath = await getTempFilePath(filename);
+        this.validatePath(filepath);
+        try {
+            await fs.writeFile(filepath, data);
+        }
+        catch (err) {
+            throw new Error('Could not save a file', { cause: err });
+        }
+        return { filepath };
     }
     async saveFile(data, clientProvidedFilePath, extension) {
+        this.validatePath(clientProvidedFilePath);
         try {
             const filePath = ensureExtension(path.resolve(clientProvidedFilePath), extension);
             await fs.mkdir(path.dirname(filePath), { recursive: true });
@@ -518,6 +562,7 @@ export class McpContext {
         await this.#networkCollector.init(pages);
     }
     async installExtension(extensionPath) {
+        this.validatePath(extensionPath);
         const id = await this.browser.installExtension(extensionPath);
         return id;
     }
@@ -541,12 +586,20 @@ export class McpContext {
         return pptrExtensions.get(id);
     }
     async getHeapSnapshotAggregates(filePath) {
+        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getAggregates(filePath);
     }
     async getHeapSnapshotStats(filePath) {
+        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getStats(filePath);
     }
     async getHeapSnapshotStaticData(filePath) {
+        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getStaticData(filePath);
     }
+    async getHeapSnapshotNodesByUid(filePath, uid) {
+        this.validatePath(filePath);
+        return await this.#heapSnapshotManager.getNodesByUid(filePath, uid);
+    }
 }
+//# sourceMappingURL=McpContext.js.map

package/build/src/McpPage.js

@@ -30,7 +30,7 @@ export class McpPage {
     // Dialog
     #dialog;
     #dialogHandler;
-    inPageTools;
+    thirdPartyDeveloperTools;
     constructor(page, id) {
         this.pptrPage = page;
         this.id = id;
@@ -48,8 +48,13 @@ export class McpPage {
     clearDialog() {
         this.#dialog = undefined;
     }
-    getInPageTools() {
-        return this.inPageTools;
+    throwIfDialogOpen() {
+        if (this.#dialog) {
+            throw new Error(`A dialog is open (${this.#dialog.type()}: ${this.#dialog.message()}).`);
+        }
+    }
+    getThirdPartyDeveloperTools() {
+        return this.thirdPartyDeveloperTools;
     }
     getWebMcpTools() {
         return this.pptrPage.webmcp.tools();
@@ -83,7 +88,7 @@ export class McpPage {
     dispose() {
         this.pptrPage.off('dialog', this.#dialogHandler);
     }
-    async executeInPageTool(toolName, params, response) {
+    async executeThirdPartyDeveloperTool(toolName, params, response) {
         // Creates array of ElementHandles from the UIDs in the params.
         // We do not replace the uids with the ElementsHandles yet, because
         // the `evaluate` function only turns them into DOM elements if they
@@ -307,3 +312,4 @@ export class McpPage {
         return {};
     }
 }
+//# sourceMappingURL=McpPage.js.map

package/build/src/McpResponse.js

@@ -5,6 +5,7 @@
  */
 import { ConsoleFormatter } from './formatters/ConsoleFormatter.js';
 import { HeapSnapshotFormatter } from './formatters/HeapSnapshotFormatter.js';
+import { isNodeLike } from './formatters/HeapSnapshotFormatter.js';
 import { IssueFormatter } from './formatters/IssueFormatter.js';
 import { NetworkFormatter } from './formatters/NetworkFormatter.js';
 import { SnapshotFormatter } from './formatters/SnapshotFormatter.js';
@@ -124,13 +125,14 @@ export class McpResponse {
     #networkRequestsOptions;
     #consoleDataOptions;
     #listExtensions;
-    #listInPageTools;
+    #listThirdPartyDeveloperTools;
     #listWebMcpTools;
     #devToolsData;
     #tabId;
     #args;
     #page;
     #redactNetworkHeaders = true;
+    #error;
     constructor(args) {
         this.#args = args;
     }
@@ -161,9 +163,9 @@ export class McpResponse {
     setListExtensions() {
         this.#listExtensions = true;
     }
-    setListInPageTools() {
-        if (this.#args.categoryInPageTools) {
-            this.#listInPageTools = true;
+    setListThirdPartyDeveloperTools() {
+        if (this.#args.categoryExperimentalThirdParty) {
+            this.#listThirdPartyDeveloperTools = true;
         }
     }
     setListWebMcpTools() {
@@ -204,6 +206,9 @@ export class McpResponse {
             includePreservedMessages: options?.includePreservedMessages,
         };
     }
+    setError(error) {
+        this.#error = error;
+    }
     attachNetworkRequest(reqId, options) {
         this.#attachedNetworkRequestId = reqId;
         this.#attachedNetworkRequestOptions = options;
@@ -254,6 +259,9 @@ export class McpResponse {
     get consoleMessagesTypes() {
         return this.#consoleDataOptions?.types;
     }
+    get error() {
+        return this.#error;
+    }
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
     }
@@ -273,6 +281,14 @@ export class McpResponse {
             staticData,
         };
     }
+    setHeapSnapshotNodes(nodes, options) {
+        this.#heapSnapshotOptions = {
+            ...this.#heapSnapshotOptions,
+            include: true,
+            nodes,
+            pagination: options,
+        };
+    }
     attachImage(value) {
         this.#images.push(value);
     }
@@ -365,14 +381,14 @@ export class McpResponse {
         if (this.#listExtensions) {
             extensions = await context.listExtensions();
         }
-        let inPageTools;
-        if (this.#listInPageTools) {
+        let thirdPartyDeveloperTools;
+        if (this.#listThirdPartyDeveloperTools) {
             const page = this.#page ?? context.getSelectedMcpPage();
-            inPageTools = await getToolGroup(page);
-            page.inPageTools = inPageTools;
+            thirdPartyDeveloperTools = await getToolGroup(page);
+            page.thirdPartyDeveloperTools = thirdPartyDeveloperTools;
         }
         let webmcpTools;
-        if (this.#listWebMcpTools && this.#args.experimentalWebmcp) {
+        if (this.#listWebMcpTools && this.#args.categoryExperimentalWebmcp) {
             const page = this.#page ?? context.getSelectedMcpPage();
             webmcpTools = page.getWebMcpTools();
         }
@@ -453,8 +469,9 @@ export class McpResponse {
             traceSummary: this.#attachedTraceSummary,
             extensions,
             lighthouseResult: this.#attachedLighthouseResult,
-            inPageTools,
+            thirdPartyDeveloperTools,
             webmcpTools,
+            errorMessage: this.#error?.message,
         });
     }
     format(toolName, context, data) {
@@ -645,6 +662,17 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(formatter.toString());
                 structuredContent.heapSnapshotData = formatter.toJSON();
             }
+            const nodes = this.#heapSnapshotOptions.nodes;
+            if (nodes) {
+                const sortedItems = nodes.items
+                    .filter(isNodeLike)
+                    .sort((a, b) => b.retainedSize - a.retainedSize);
+                const paginationData = this.#dataWithPagination(sortedItems, this.#heapSnapshotOptions.pagination);
+                response.push(HeapSnapshotFormatter.formatNodes(paginationData.items));
+                structuredContent.pagination = paginationData.pagination;
+                response.push(...paginationData.info);
+                structuredContent.heapSnapshotNodes = paginationData.items;
+            }
         }
         if (data.detailedNetworkRequest) {
             response.push(data.detailedNetworkRequest.toStringDetailed());
@@ -672,14 +700,16 @@ 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.');
+        if (this.#listThirdPartyDeveloperTools) {
+            structuredContent.thirdPartyDeveloperTools =
+                data.thirdPartyDeveloperTools ?? undefined;
+            response.push('## Third-party developer tools');
+            if (!data.thirdPartyDeveloperTools ||
+                !data.thirdPartyDeveloperTools.tools) {
+                response.push('No third-party developer tools available.');
             }
             else {
-                const toolGroup = data.inPageTools;
+                const toolGroup = data.thirdPartyDeveloperTools;
                 response.push(`${toolGroup.name}: ${toolGroup.description}`);
                 response.push('Available tools:');
                 const toolDefinitionsMessage = toolGroup.tools
@@ -733,16 +763,21 @@ Call ${handleDialog.name} to handle it before continuing.`);
             const messages = data.consoleMessages ?? [];
             response.push('## Console messages');
             if (messages.length) {
-                const paginationData = this.#dataWithPagination(messages, this.#consoleDataOptions.pagination);
+                const grouped = ConsoleFormatter.groupConsecutive(messages);
+                const paginationData = this.#dataWithPagination(grouped, this.#consoleDataOptions.pagination);
                 structuredContent.pagination = paginationData.pagination;
                 response.push(...paginationData.info);
-                response.push(...paginationData.items.map(message => message.toString()));
-                structuredContent.consoleMessages = paginationData.items.map(message => message.toJSON());
+                response.push(...paginationData.items.map(item => item.toString()));
+                structuredContent.consoleMessages = paginationData.items.map(item => item.toJSON());
             }
             else {
                 response.push('<no console messages found>');
             }
         }
+        if (data.errorMessage) {
+            response.push(`Error: ${data.errorMessage}`);
+            structuredContent.errorMessage = data.errorMessage;
+        }
         const text = {
             type: 'text',
             text: response.join('\n'),
@@ -804,3 +839,4 @@ function createStructuredPage(page, context) {
     }
     return entry;
 }
+//# sourceMappingURL=McpResponse.js.map

package/build/src/Mutex.js

@@ -35,3 +35,4 @@ export class Mutex {
         resolve();
     }
 }
+//# sourceMappingURL=Mutex.js.map

package/build/src/PageCollector.js

@@ -294,3 +294,4 @@ export class NetworkCollector extends PageCollector {
         navigations.splice(this.maxNavigationSaved);
     }
 }
+//# sourceMappingURL=PageCollector.js.map

package/build/src/SlimMcpResponse.js

@@ -16,3 +16,4 @@ export class SlimMcpResponse extends McpResponse {
         };
     }
 }
+//# sourceMappingURL=SlimMcpResponse.js.map

package/build/src/TextSnapshot.js

@@ -99,8 +99,8 @@ export class TextSnapshot {
         return snapshot;
     }
     // ExtraHandles represent DOM nodes which might not be part of the accessibility tree, e.g. DOM nodes
-    // returned by in-page tools. We insert them into the tree by finding the closest ancestor in the
-    // tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
+    // returned by third-party developer tools. We insert them into the tree by finding the closest ancestor
+    // in the tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
     static async insertExtraNodes(page, idToNode, seenUniqueIds, snapshotId, idCounter, rootNodeWithId, seenBackendNodeIds, extraHandles) {
         const { uniqueBackendNodeIdToMcpId } = page;
         const createExtraNode = async (handle) => {
@@ -160,6 +160,9 @@ export class TextSnapshot {
         };
         const findDescendantNodes = async (backendNodeId) => {
             const descendantIds = new Set();
+            if (!backendNodeId) {
+                return descendantIds;
+            }
             try {
                 // @ts-expect-error internal API
                 const client = page.pptrPage._client();
@@ -213,6 +216,7 @@ export class TextSnapshot {
         if (extraHandles.length) {
             page.extraHandles = extraHandles;
         }
+        const reorgInfo = [];
         for (const handle of page.extraHandles) {
             const extraNode = await createExtraNode(handle);
             if (!extraNode) {
@@ -220,11 +224,13 @@ export class TextSnapshot {
             }
             idToNode.set(extraNode.id, extraNode);
             const attachTarget = (await findAncestorNode(handle)) || rootNodeWithId;
-            if (extraNode.backendNodeId !== undefined) {
-                const descendantIds = await findDescendantNodes(extraNode.backendNodeId);
-                const index = moveChildNodes(attachTarget, extraNode, descendantIds);
-                attachTarget.children.splice(index, 0, extraNode);
-            }
+            const descendantIds = await findDescendantNodes(extraNode.backendNodeId);
+            reorgInfo.push({ extraNode, attachTarget, descendantIds });
+        }
+        for (const { extraNode, attachTarget, descendantIds } of reorgInfo) {
+            const index = moveChildNodes(attachTarget, extraNode, descendantIds);
+            attachTarget.children.splice(index, 0, extraNode);
         }
     }
 }
+//# sourceMappingURL=TextSnapshot.js.map

package/build/src/WaitForHelper.js

@@ -104,8 +104,10 @@ export class WaitForHelper {
         });
     }
     async waitForEventsAfterAction(action, options) {
+        let dialogOpened = false;
         if (options?.handleDialog) {
             const dialogHandler = (dialog) => {
+                dialogOpened = true;
                 if (options.handleDialog === 'dismiss') {
                     void dialog.dismiss();
                 }
@@ -142,6 +144,9 @@ export class WaitForHelper {
         }
         try {
             await navigationFinished;
+            if (dialogOpened) {
+                return;
+            }
             // Wait for stable dom after navigation so we execute in
             // the correct context
             await this.waitForStableDom();
@@ -168,3 +173,4 @@ export function getNetworkMultiplierFromString(condition) {
     }
     return 1;
 }
+//# sourceMappingURL=WaitForHelper.js.map

package/build/src/bin/check-latest-version.js

@@ -23,3 +23,4 @@ if (cachePath) {
         // Ignore errors.
     }
 }
+//# sourceMappingURL=check-latest-version.js.map