chrome-devtools-mcp 0.22.0 → 0.24.0

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

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from './logger.js';
+export class TextSnapshot {
+    static nextSnapshotId = 1;
+    static resetCounter() {
+        TextSnapshot.nextSnapshotId = 1;
+    }
+    root;
+    idToNode;
+    snapshotId;
+    selectedElementUid;
+    hasSelectedElement;
+    verbose;
+    constructor(data) {
+        this.root = data.root;
+        this.idToNode = data.idToNode;
+        this.snapshotId = data.snapshotId;
+        this.selectedElementUid = data.selectedElementUid;
+        this.hasSelectedElement = data.hasSelectedElement;
+        this.verbose = data.verbose;
+    }
+    static async create(page, options = {}) {
+        const verbose = options.verbose ?? false;
+        const rootNode = await page.pptrPage.accessibility.snapshot({
+            includeIframes: true,
+            interestingOnly: !verbose,
+        });
+        if (!rootNode) {
+            throw new Error('Failed to create accessibility snapshot');
+        }
+        const { uniqueBackendNodeIdToMcpId } = page;
+        const snapshotId = TextSnapshot.nextSnapshotId++;
+        // Iterate through the whole accessibility node tree and assign node ids that
+        // will be used for the tree serialization and mapping ids back to nodes.
+        let idCounter = 0;
+        const idToNode = new Map();
+        const seenUniqueIds = new Set();
+        const seenBackendNodeIds = new Set();
+        const assignIds = (node) => {
+            let id = '';
+            // @ts-expect-error untyped backendNodeId.
+            const backendNodeId = node.backendNodeId;
+            // @ts-expect-error untyped loaderId.
+            const uniqueBackendId = `${node.loaderId}_${backendNodeId}`;
+            const existingMcpId = uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+            if (existingMcpId !== undefined) {
+                // Re-use MCP exposed ID if the uniqueId is the same.
+                id = existingMcpId;
+            }
+            else {
+                // Only generate a new ID if we have not seen the node before.
+                id = `${snapshotId}_${idCounter++}`;
+                uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+            }
+            seenUniqueIds.add(uniqueBackendId);
+            seenBackendNodeIds.add(backendNodeId);
+            const nodeWithId = {
+                ...node,
+                id,
+                children: node.children
+                    ? node.children.map(child => assignIds(child))
+                    : [],
+            };
+            // The AXNode for an option doesn't contain its `value`.
+            // Therefore, set text content of the option as value.
+            if (node.role === 'option') {
+                const optionText = node.name;
+                if (optionText) {
+                    nodeWithId.value = optionText.toString();
+                }
+            }
+            idToNode.set(nodeWithId.id, nodeWithId);
+            return nodeWithId;
+        };
+        const rootNodeWithId = assignIds(rootNode);
+        await TextSnapshot.insertExtraNodes(page, idToNode, seenUniqueIds, snapshotId, idCounter, rootNodeWithId, seenBackendNodeIds, options.extraHandles ?? []);
+        const snapshot = new TextSnapshot({
+            root: rootNodeWithId,
+            snapshotId: String(snapshotId),
+            idToNode,
+            hasSelectedElement: false,
+            verbose,
+        });
+        const data = options.devtoolsData ?? (await page.getDevToolsData());
+        if (data?.cdpBackendNodeId) {
+            snapshot.hasSelectedElement = true;
+            snapshot.selectedElementUid = page.resolveCdpElementId(data.cdpBackendNodeId);
+        }
+        // Clean up unique IDs that we did not see anymore.
+        for (const key of uniqueBackendNodeIdToMcpId.keys()) {
+            if (!seenUniqueIds.has(key)) {
+                uniqueBackendNodeIdToMcpId.delete(key);
+            }
+        }
+        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.
+    static async insertExtraNodes(page, idToNode, seenUniqueIds, snapshotId, idCounter, rootNodeWithId, seenBackendNodeIds, extraHandles) {
+        const { uniqueBackendNodeIdToMcpId } = page;
+        const createExtraNode = async (handle) => {
+            const backendNodeId = await handle.backendNodeId();
+            if (!backendNodeId || seenBackendNodeIds.has(backendNodeId)) {
+                return null;
+            }
+            const uniqueBackendId = `custom_${backendNodeId}`;
+            if (seenUniqueIds.has(uniqueBackendId)) {
+                return null;
+            }
+            seenBackendNodeIds.add(backendNodeId);
+            let id = '';
+            const mcpId = uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+            if (mcpId !== undefined) {
+                id = mcpId;
+            }
+            else {
+                id = `${snapshotId}_${idCounter++}`;
+                uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+            }
+            seenUniqueIds.add(uniqueBackendId);
+            const tagHandle = await handle.getProperty('localName');
+            const tagValue = await tagHandle.jsonValue();
+            const extraNode = {
+                role: tagValue,
+                id,
+                backendNodeId,
+                children: [],
+                elementHandle: async () => handle,
+            };
+            return extraNode;
+        };
+        const findAncestorNode = async (handle) => {
+            let ancestorHandle = await handle.evaluateHandle(el => el.parentElement);
+            while (ancestorHandle) {
+                const ancestorElement = ancestorHandle.asElement();
+                if (!ancestorElement) {
+                    await ancestorHandle.dispose();
+                    return null;
+                }
+                const ancestorBackendId = await ancestorElement.backendNodeId();
+                if (ancestorBackendId) {
+                    const ancestorNode = idToNode
+                        .values()
+                        .find(node => node.backendNodeId === ancestorBackendId);
+                    if (ancestorNode) {
+                        await ancestorHandle.dispose();
+                        return ancestorNode;
+                    }
+                }
+                const nextHandle = await ancestorElement.evaluateHandle(el => el.parentElement);
+                await ancestorHandle.dispose();
+                ancestorHandle = nextHandle;
+            }
+            return null;
+        };
+        const findDescendantNodes = async (backendNodeId) => {
+            const descendantIds = new Set();
+            if (!backendNodeId) {
+                return descendantIds;
+            }
+            try {
+                // @ts-expect-error internal API
+                const client = page.pptrPage._client();
+                if (client) {
+                    const { node } = await client.send('DOM.describeNode', {
+                        backendNodeId,
+                        depth: -1,
+                        pierce: true,
+                    });
+                    const collect = (node) => {
+                        if (node.backendNodeId && node.backendNodeId !== backendNodeId) {
+                            descendantIds.add(node.backendNodeId);
+                        }
+                        if (node.children) {
+                            for (const child of node.children) {
+                                collect(child);
+                            }
+                        }
+                    };
+                    collect(node);
+                }
+            }
+            catch (e) {
+                logger(`Failed to collect descendants for backend node ${backendNodeId}`, e);
+            }
+            return descendantIds;
+        };
+        const moveChildNodes = (attachTarget, extraNode, descendantIds) => {
+            let firstMovedIndex = -1;
+            if (descendantIds.size > 0 && attachTarget.children) {
+                const remainingChildren = [];
+                for (const child of attachTarget.children) {
+                    if (child.backendNodeId && descendantIds.has(child.backendNodeId)) {
+                        if (firstMovedIndex === -1) {
+                            firstMovedIndex = remainingChildren.length;
+                        }
+                        extraNode.children.push(child);
+                    }
+                    else {
+                        remainingChildren.push(child);
+                    }
+                }
+                attachTarget.children = remainingChildren;
+            }
+            return firstMovedIndex !== -1
+                ? firstMovedIndex
+                : attachTarget.children
+                    ? attachTarget.children.length
+                    : 0;
+        };
+        if (extraHandles.length) {
+            page.extraHandles = extraHandles;
+        }
+        const reorgInfo = [];
+        for (const handle of page.extraHandles) {
+            const extraNode = await createExtraNode(handle);
+            if (!extraNode) {
+                continue;
+            }
+            idToNode.set(extraNode.id, extraNode);
+            const attachTarget = (await findAncestorNode(handle)) || rootNodeWithId;
+            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

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

@@ -28,6 +28,36 @@ export const commands = {
             },
         },
     },
+    click_at: {
+        description: 'Clicks at the provided coordinates (requires flag: --experimentalVision=true)',
+        category: 'Input automation',
+        args: {
+            x: {
+                name: 'x',
+                type: 'number',
+                description: 'The x coordinate',
+                required: true,
+            },
+            y: {
+                name: 'y',
+                type: 'number',
+                description: 'The y coordinate',
+                required: true,
+            },
+            dblClick: {
+                name: 'dblClick',
+                type: 'boolean',
+                description: 'Set to true for double clicks. Default is false.',
+                required: false,
+            },
+            includeSnapshot: {
+                name: 'includeSnapshot',
+                type: 'boolean',
+                description: 'Whether to include a snapshot in the response. Default is false.',
+                required: false,
+            },
+        },
+    },
     close_page: {
         description: 'Closes the page by its index. The last open page cannot be closed.',
         category: 'Navigation automation',
@@ -84,7 +114,7 @@ export const commands = {
             geolocation: {
                 name: 'geolocation',
                 type: 'string',
-                description: 'Geolocation (`<latitude>x<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.',
+                description: 'Geolocation (`<latitude>x<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.',
                 required: false,
             },
             userAgent: {
@@ -124,10 +154,34 @@ export const commands = {
                 description: 'An optional list of arguments to pass to the function.',
                 required: false,
             },
+            dialogAction: {
+                name: 'dialogAction',
+                type: 'string',
+                description: 'Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.',
+                required: false,
+            },
+        },
+    },
+    execute_webmcp_tool: {
+        description: 'Executes a WebMCP tool exposed by the page. (requires flag: --experimentalWebmcp=true)',
+        category: 'Debugging',
+        args: {
+            toolName: {
+                name: 'toolName',
+                type: 'string',
+                description: 'The name of the WebMCP tool to execute',
+                required: true,
+            },
+            input: {
+                name: 'input',
+                type: 'string',
+                description: 'The JSON-stringified parameters to pass to the WebMCP tool',
+                required: false,
+            },
         },
     },
     fill: {
-        description: 'Type text into a input, text area or select an option from a <select> element.',
+        description: 'Type text into an input, text area or select an option from a <select> element.',
         category: 'Input automation',
         args: {
             uid: {
@@ -150,24 +204,6 @@ export const commands = {
             },
         },
     },
-    fill_form: {
-        description: 'Fill out multiple form elements at once',
-        category: 'Input automation',
-        args: {
-            elements: {
-                name: 'elements',
-                type: 'array',
-                description: 'Elements from snapshot to fill out.',
-                required: true,
-            },
-            includeSnapshot: {
-                name: 'includeSnapshot',
-                type: 'boolean',
-                description: 'Whether to include a snapshot in the response. Default is false.',
-                required: false,
-            },
-        },
-    },
     get_console_message: {
         description: 'Gets a console message by its ID. You can get all messages by calling list_console_messages.',
         category: 'Debugging',
@@ -180,6 +216,30 @@ export const commands = {
             },
         },
     },
+    get_memory_snapshot_details: {
+        description: 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --experimentalMemory=true)',
+        category: 'Memory',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'A path to a .heapsnapshot file to read.',
+                required: true,
+            },
+            pageIdx: {
+                name: 'pageIdx',
+                type: 'number',
+                description: 'The page index for pagination of aggregates.',
+                required: false,
+            },
+            pageSize: {
+                name: 'pageSize',
+                type: 'number',
+                description: 'The page size for pagination of aggregates.',
+                required: false,
+            },
+        },
+    },
     get_network_request: {
         description: 'Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.',
         category: 'Network',
@@ -193,13 +253,43 @@ export const commands = {
             requestFilePath: {
                 name: 'requestFilePath',
                 type: 'string',
-                description: 'The absolute or relative path to save the request body to. If omitted, the body is returned inline.',
+                description: 'The absolute or relative path to a .network-request file to save the request body to. If omitted, the body is returned inline.',
                 required: false,
             },
             responseFilePath: {
                 name: 'responseFilePath',
                 type: 'string',
-                description: 'The absolute or relative path to save the response body to. If omitted, the body is returned inline.',
+                description: 'The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.',
+                required: false,
+            },
+        },
+    },
+    get_nodes_by_class: {
+        description: 'Loads a memory heapsnapshot and returns instances of a specific class with their stable IDs. (requires flag: --experimentalMemory=true)',
+        category: 'Memory',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'A path to a .heapsnapshot file to read.',
+                required: true,
+            },
+            uid: {
+                name: 'uid',
+                type: 'number',
+                description: 'The unique UID for the class, obtained from aggregates listing.',
+                required: true,
+            },
+            pageIdx: {
+                name: 'pageIdx',
+                type: 'number',
+                description: 'The page index for pagination.',
+                required: false,
+            },
+            pageSize: {
+                name: 'pageSize',
+                type: 'number',
+                description: 'The page size for pagination.',
                 required: false,
             },
         },
@@ -241,8 +331,20 @@ export const commands = {
             },
         },
     },
+    install_extension: {
+        description: 'Installs a Chrome extension from the given path. (requires flag: --categoryExtensions=true)',
+        category: 'Extensions',
+        args: {
+            path: {
+                name: 'path',
+                type: 'string',
+                description: 'Absolute path to the unpacked extension folder.',
+                required: true,
+            },
+        },
+    },
     lighthouse_audit: {
-        description: 'Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run performance_start_trace',
+        description: 'Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance. For performance audits, run performance_start_trace',
         category: 'Debugging',
         args: {
             mode: {
@@ -276,7 +378,7 @@ export const commands = {
             pageSize: {
                 name: 'pageSize',
                 type: 'integer',
-                description: 'Maximum number of messages to return. When omitted, returns all requests.',
+                description: 'Maximum number of messages to return. When omitted, returns all messages.',
                 required: false,
             },
             pageIdx: {
@@ -300,6 +402,11 @@ export const commands = {
             },
         },
     },
+    list_extensions: {
+        description: 'Lists all the Chrome extensions installed in the browser. This includes their name, ID, version, and enabled status. (requires flag: --categoryExtensions=true)',
+        category: 'Extensions',
+        args: {},
+    },
     list_network_requests: {
         description: 'List all requests for the currently selected page since the last navigation.',
         category: 'Network',
@@ -332,10 +439,27 @@ export const commands = {
         },
     },
     list_pages: {
-        description: 'Get a list of pages  open in the browser.',
+        description: 'Get a list of pages open in the browser.',
         category: 'Navigation automation',
         args: {},
     },
+    list_webmcp_tools: {
+        description: 'Lists all WebMCP tools the page exposes. (requires flag: --experimentalWebmcp=true)',
+        category: 'Debugging',
+        args: {},
+    },
+    load_memory_snapshot: {
+        description: 'Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --experimentalMemory=true)',
+        category: 'Memory',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'A path to a .heapsnapshot file to read.',
+                required: true,
+            },
+        },
+    },
     navigate_page: {
         description: 'Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.',
         category: 'Navigation automation',
@@ -484,6 +608,18 @@ export const commands = {
             },
         },
     },
+    reload_extension: {
+        description: 'Reloads an unpacked Chrome extension by its ID. (requires flag: --categoryExtensions=true)',
+        category: 'Extensions',
+        args: {
+            id: {
+                name: 'id',
+                type: 'string',
+                description: 'ID of the extension to reload.',
+                required: true,
+            },
+        },
+    },
     resize_page: {
         description: "Resizes the selected page's window so that the page has specified dimension",
         category: 'Emulation',
@@ -502,6 +638,23 @@ export const commands = {
             },
         },
     },
+    screencast_start: {
+        description: 'Starts recording a screencast (video) of the selected page in specified format. (requires flag: --experimentalScreencast=true)',
+        category: 'Debugging',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'Output file path (.webm,.mp4 are supported). Uses mkdtemp to generate a unique path if not provided.',
+                required: false,
+            },
+        },
+    },
+    screencast_stop: {
+        description: 'Stops the active screencast recording on the selected page. (requires flag: --experimentalScreencast=true)',
+        category: 'Debugging',
+        args: {},
+    },
     select_page: {
         description: 'Select a page as a context for future tool calls.',
         category: 'Navigation automation',
@@ -521,8 +674,8 @@ export const commands = {
         },
     },
     take_memory_snapshot: {
-        description: 'Capture a memory heapsnapshot of the currently selected page to memory leak debugging',
-        category: 'Performance',
+        description: 'Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.',
+        category: 'Memory',
         args: {
             filePath: {
                 name: 'filePath',
@@ -553,7 +706,7 @@ export const commands = {
             uid: {
                 name: 'uid',
                 type: 'string',
-                description: 'The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.',
+                description: 'The uid of an element on the page from the page content snapshot. If omitted, takes a page screenshot.',
                 required: false,
             },
             fullPage: {
@@ -588,6 +741,18 @@ export const commands = {
             },
         },
     },
+    trigger_extension_action: {
+        description: 'Triggers the default action of an extension by its ID. (requires flag: --categoryExtensions=true)',
+        category: 'Extensions',
+        args: {
+            id: {
+                name: 'id',
+                type: 'string',
+                description: 'ID of the extension to trigger the action for.',
+                required: true,
+            },
+        },
+    },
     type_text: {
         description: 'Type text using keyboard into a previously focused input',
         category: 'Input automation',
@@ -606,6 +771,18 @@ export const commands = {
             },
         },
     },
+    uninstall_extension: {
+        description: 'Uninstalls a Chrome extension by its ID. (requires flag: --categoryExtensions=true)',
+        category: 'Extensions',
+        args: {
+            id: {
+                name: 'id',
+                type: 'string',
+                description: 'ID of the extension to uninstall.',
+                required: true,
+            },
+        },
+    },
     upload_file: {
         description: 'Upload a file through a provided element.',
         category: 'Input automation',
@@ -630,22 +807,5 @@ export const commands = {
             },
         },
     },
-    wait_for: {
-        description: 'Wait for the specified text to appear on the selected page.',
-        category: 'Navigation automation',
-        args: {
-            text: {
-                name: 'text',
-                type: 'array',
-                description: 'Non-empty list of texts. Resolves when any value appears on the page.',
-                required: true,
-            },
-            timeout: {
-                name: 'timeout',
-                type: 'integer',
-                description: 'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.',
-                required: false,
-            },
-        },
-    },
 };
+//# sourceMappingURL=chrome-devtools-cli-options.js.map