chrome-devtools-mcp 0.21.0 → 0.23.0

package/build/src/McpPage.js

@@ -3,7 +3,10 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { logger } from './logger.js';
+import { TextSnapshot } from './TextSnapshot.js';
 import { takeSnapshot } from './tools/snapshot.js';
+import { getNetworkMultiplierFromString, WaitForHelper, } from './WaitForHelper.js';
 /**
  * Per-page state wrapper. Consolidates dialog, snapshot, emulation,
  * and metadata that were previously scattered across Maps in McpContext.
@@ -18,6 +21,7 @@ export class McpPage {
     // Snapshot
     textSnapshot = null;
     uniqueBackendNodeIdToMcpId = new Map();
+    extraHandles = [];
     // Emulation
     emulationSettings = {};
     // Metadata
@@ -26,6 +30,7 @@ export class McpPage {
     // Dialog
     #dialog;
     #dialogHandler;
+    inPageTools;
     constructor(page, id) {
         this.pptrPage = page;
         this.id = id;
@@ -43,6 +48,12 @@ export class McpPage {
     clearDialog() {
         this.#dialog = undefined;
     }
+    getInPageTools() {
+        return this.inPageTools;
+    }
+    getWebMcpTools() {
+        return this.pptrPage.webmcp.tools();
+    }
     get networkConditions() {
         return this.emulationSettings.networkConditions ?? null;
     }
@@ -61,9 +72,162 @@ export class McpPage {
     get colorScheme() {
         return this.emulationSettings.colorScheme ?? null;
     }
+    // Public for testability: tests spy on this method to verify throttle multipliers.
+    createWaitForHelper(cpuMultiplier, networkMultiplier) {
+        return new WaitForHelper(this.pptrPage, cpuMultiplier, networkMultiplier);
+    }
+    waitForEventsAfterAction(action, options) {
+        const helper = this.createWaitForHelper(this.cpuThrottlingRate, getNetworkMultiplierFromString(this.networkConditions));
+        return helper.waitForEventsAfterAction(action, options);
+    }
     dispose() {
         this.pptrPage.off('dialog', this.#dialogHandler);
     }
+    async executeInPageTool(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
+        // are passed as non-nested arguments.
+        const handles = [];
+        for (const value of Object.values(params)) {
+            if (value instanceof Object &&
+                'uid' in value &&
+                typeof value.uid === 'string' &&
+                Object.keys(value).length === 1) {
+                handles.push(await this.getElementByUid(value.uid));
+            }
+        }
+        const result = await this.pptrPage.evaluate(async (name, args, ...elements) => {
+            // Replace the UIDs with DOM elements.
+            for (const [key, value] of Object.entries(args)) {
+                if (value instanceof Object &&
+                    'uid' in value &&
+                    typeof value.uid === 'string' &&
+                    Object.keys(value).length === 1) {
+                    args[key] = elements.shift();
+                }
+            }
+            if (!window.__dtmcp?.executeTool) {
+                throw new Error('No tools found on the page');
+            }
+            const toolResult = await window.__dtmcp.executeTool(name, args);
+            const stashDOMElement = (el) => {
+                if (!window.__dtmcp) {
+                    window.__dtmcp = {};
+                }
+                if (window.__dtmcp.stashedElements === undefined) {
+                    window.__dtmcp.stashedElements = [];
+                }
+                window.__dtmcp.stashedElements.push(el);
+                return {
+                    stashedId: `stashed-${window.__dtmcp.stashedElements.length - 1}`,
+                };
+            };
+            const ancestors = [];
+            // Recursively walks the tool result:
+            // - Replaces DOM elements with an ID and stashes the DOM element on the window object
+            // - Replaces non-plain objects with a string representation of the object
+            // - Replaces circular references with the string '<Circular reference>'
+            // - Replaces functions with the string '<Function object>'
+            const processToolResult = (data, parentEl) => {
+                // 1. Handle DOM Elements
+                if (data instanceof Element) {
+                    return stashDOMElement(data);
+                }
+                // 2. Handle Arrays
+                if (Array.isArray(data)) {
+                    return data.map((item) => processToolResult(item, parentEl));
+                }
+                // 3. Handle Objects
+                if (data !== null && typeof data === 'object') {
+                    while (ancestors.length > 0 && ancestors.at(-1) !== parentEl) {
+                        ancestors.pop();
+                    }
+                    if (ancestors.includes(data)) {
+                        return '<Circular reference>';
+                    }
+                    ancestors.push(data);
+                    // If not a plain object, return a string representation of the object
+                    if (Object.getPrototypeOf(data) !== Object.prototype) {
+                        return `<${data.constructor.name} instance>`;
+                    }
+                    const processedObj = {};
+                    for (const [key, value] of Object.entries(data)) {
+                        processedObj[key] = processToolResult(value, data);
+                    }
+                    return processedObj;
+                }
+                // 4. Handle Functions
+                if (typeof data === 'function') {
+                    return '<Function object>';
+                }
+                // 5. Return primitives (strings, numbers, booleans) as-is
+                return data;
+            };
+            return {
+                result: processToolResult(toolResult),
+                stashed: window.__dtmcp?.stashedElements?.length ?? 0,
+            };
+        }, toolName, params, ...handles);
+        const elementHandles = [];
+        for (let i = 0; i < (result.stashed ?? 0); i++) {
+            const elementHandle = await this.pptrPage.evaluateHandle(index => {
+                const el = window.__dtmcp?.stashedElements?.[index];
+                if (!el) {
+                    throw new Error(`Stashed element at index ${index} not found`);
+                }
+                return el;
+            }, i);
+            elementHandles.push(elementHandle);
+        }
+        if (elementHandles.length) {
+            const oldHandles = [...this.extraHandles];
+            this.textSnapshot = await TextSnapshot.create(this, {
+                extraHandles: elementHandles,
+            });
+            response.includeSnapshot();
+            for (const handle of oldHandles) {
+                await handle
+                    .dispose()
+                    .catch(e => logger('Failed to dispose old handle', e));
+            }
+        }
+        const cdpElementIds = await Promise.all(elementHandles.map(async (elementHandle, index) => {
+            const backendNodeId = await elementHandle.backendNodeId();
+            if (!backendNodeId) {
+                logger(`No backendNodeId for stashed DOM element with index ${index}`);
+                return `stashed-${index}`;
+            }
+            const cdpElementId = this.resolveCdpElementId(backendNodeId);
+            if (!cdpElementId) {
+                logger(`Could not get cdpElementId for backend node ${backendNodeId}`);
+                return `stashed-${index}`;
+            }
+            return cdpElementId;
+        }));
+        const recursivelyReplaceStashedElements = (node) => {
+            if (Array.isArray(node)) {
+                return node.map(x => recursivelyReplaceStashedElements(x));
+            }
+            if (node !== null && typeof node === 'object') {
+                if ('stashedId' in node &&
+                    typeof node.stashedId === 'string' &&
+                    node.stashedId.startsWith('stashed-') &&
+                    Object.keys(node).length === 1) {
+                    const index = parseInt(node.stashedId.split('-')[1]);
+                    return { uid: cdpElementIds[index] };
+                }
+                const resultObj = {};
+                for (const [key, value] of Object.entries(node)) {
+                    resultObj[key] = recursivelyReplaceStashedElements(value);
+                }
+                return resultObj;
+            }
+            return node;
+        };
+        const resultWithUids = recursivelyReplaceStashedElements(result.result);
+        response.appendResponseLine(JSON.stringify(resultWithUids, null, 2));
+    }
     async getElementByUid(uid) {
         if (!this.textSnapshot) {
             throw new Error(`No snapshot found for page ${this.id ?? '?'}. Use ${takeSnapshot.name} to capture one.`);
@@ -92,4 +256,54 @@ export class McpPage {
     getAXNodeByUid(uid) {
         return this.textSnapshot?.idToNode.get(uid);
     }
+    resolveCdpElementId(cdpBackendNodeId) {
+        if (!cdpBackendNodeId) {
+            logger('no cdpBackendNodeId');
+            return;
+        }
+        const snapshot = this.textSnapshot;
+        if (!snapshot) {
+            logger('no text snapshot');
+            return;
+        }
+        // TODO: index by backendNodeId instead.
+        const queue = [snapshot.root];
+        while (queue.length) {
+            const current = queue.pop();
+            if (current.backendNodeId === cdpBackendNodeId) {
+                return current.id;
+            }
+            for (const child of current.children) {
+                queue.push(child);
+            }
+        }
+        return;
+    }
+    async getDevToolsData() {
+        try {
+            logger('Getting DevTools UI data');
+            const devtoolsPage = this.devToolsPage;
+            if (!devtoolsPage) {
+                logger('No DevTools page detected');
+                return {};
+            }
+            const { cdpRequestId, cdpBackendNodeId } = await devtoolsPage.evaluate(async () => {
+                // @ts-expect-error no types
+                const UI = await import('/bundled/ui/legacy/legacy.js');
+                // @ts-expect-error no types
+                const SDK = await import('/bundled/core/sdk/sdk.js');
+                const request = UI.Context.Context.instance().flavor(SDK.NetworkRequest.NetworkRequest);
+                const node = UI.Context.Context.instance().flavor(SDK.DOMModel.DOMNode);
+                return {
+                    cdpRequestId: request?.requestId(),
+                    cdpBackendNodeId: node?.backendNodeId(),
+                };
+            });
+            return { cdpBackendNodeId, cdpRequestId };
+        }
+        catch (err) {
+            logger('error getting devtools data', err);
+        }
+        return {};
+    }
 }

package/build/src/McpResponse.js

@@ -4,14 +4,62 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { ConsoleFormatter } from './formatters/ConsoleFormatter.js';
+import { HeapSnapshotFormatter } from './formatters/HeapSnapshotFormatter.js';
 import { IssueFormatter } from './formatters/IssueFormatter.js';
 import { NetworkFormatter } from './formatters/NetworkFormatter.js';
 import { SnapshotFormatter } from './formatters/SnapshotFormatter.js';
 import { UncaughtError } from './PageCollector.js';
+import { TextSnapshot } from './TextSnapshot.js';
 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';
+export function replaceHtmlElementsWithUids(schema) {
+    if (typeof schema === 'boolean') {
+        return;
+    }
+    let isHtmlElement = false;
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === 'x-mcp-type' && value === 'HTMLElement') {
+            isHtmlElement = true;
+            break;
+        }
+    }
+    if (isHtmlElement) {
+        schema.properties = { uid: { type: 'string' } };
+        schema.required = ['uid'];
+    }
+    if (schema.properties) {
+        for (const key of Object.keys(schema.properties)) {
+            replaceHtmlElementsWithUids(schema.properties[key]);
+        }
+    }
+    if (schema.items) {
+        if (Array.isArray(schema.items)) {
+            for (const item of schema.items) {
+                replaceHtmlElementsWithUids(item);
+            }
+        }
+        else {
+            replaceHtmlElementsWithUids(schema.items);
+        }
+    }
+    if (schema.anyOf) {
+        for (const s of schema.anyOf) {
+            replaceHtmlElementsWithUids(s);
+        }
+    }
+    if (schema.allOf) {
+        for (const s of schema.allOf) {
+            replaceHtmlElementsWithUids(s);
+        }
+    }
+    if (schema.oneOf) {
+        for (const s of schema.oneOf) {
+            replaceHtmlElementsWithUids(s);
+        }
+    }
+}
 async function getToolGroup(page) {
     // Check if there is a `devtoolstooldiscovery` event listener
     const windowHandle = await page.pptrPage.evaluateHandle(() => window);
@@ -54,6 +102,9 @@ async function getToolGroup(page) {
             }, 0);
         });
     });
+    for (const tool of toolGroup?.tools ?? []) {
+        replaceHtmlElementsWithUids(tool.inputSchema);
+    }
     return toolGroup;
 }
 export class McpResponse {
@@ -69,20 +120,26 @@ export class McpResponse {
     #attachedLighthouseResult;
     #textResponseLines = [];
     #images = [];
+    #heapSnapshotOptions;
     #networkRequestsOptions;
     #consoleDataOptions;
     #listExtensions;
     #listInPageTools;
+    #listWebMcpTools;
     #devToolsData;
     #tabId;
     #args;
     #page;
+    #redactNetworkHeaders = true;
     constructor(args) {
         this.#args = args;
     }
     setPage(page) {
         this.#page = page;
     }
+    setRedactNetworkHeaders(value) {
+        this.#redactNetworkHeaders = value;
+    }
     attachDevToolsData(data) {
         this.#devToolsData = data;
     }
@@ -109,6 +166,9 @@ export class McpResponse {
             this.#listInPageTools = true;
         }
     }
+    setListWebMcpTools() {
+        this.#listWebMcpTools = true;
+    }
     setIncludeNetworkRequests(value, options) {
         if (!value) {
             this.#networkRequestsOptions = undefined;
@@ -197,6 +257,22 @@ export class McpResponse {
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
     }
+    setHeapSnapshotAggregates(aggregates, options) {
+        this.#heapSnapshotOptions = {
+            ...this.#heapSnapshotOptions,
+            include: true,
+            aggregates,
+            pagination: options,
+        };
+    }
+    setHeapSnapshotStats(stats, staticData) {
+        this.#heapSnapshotOptions = {
+            ...this.#heapSnapshotOptions,
+            include: true,
+            stats,
+            staticData,
+        };
+    }
     attachImage(value) {
         this.#images.push(value);
     }
@@ -209,6 +285,9 @@ export class McpResponse {
     get snapshotParams() {
         return this.#snapshotParams;
     }
+    get listWebMcpTools() {
+        return this.#listWebMcpTools;
+    }
     async handle(toolName, context) {
         if (this.#includePages) {
             await context.createPagesSnapshot();
@@ -221,13 +300,16 @@ export class McpResponse {
             if (!this.#page) {
                 throw new Error('Response must have a page');
             }
-            await context.createTextSnapshot(this.#page, this.#snapshotParams.verbose, this.#devToolsData);
+            this.#page.textSnapshot = await TextSnapshot.create(this.#page, {
+                verbose: this.#snapshotParams.verbose,
+                devtoolsData: this.#devToolsData,
+            });
             const textSnapshot = this.#page.textSnapshot;
             if (textSnapshot) {
                 const formatter = new SnapshotFormatter(textSnapshot);
                 if (this.#snapshotParams.filePath) {
-                    await context.saveFile(new TextEncoder().encode(formatter.toString()), this.#snapshotParams.filePath);
-                    snapshot = this.#snapshotParams.filePath;
+                    const result = await context.saveFile(new TextEncoder().encode(formatter.toString()), this.#snapshotParams.filePath, '.txt');
+                    snapshot = result.filename;
                 }
                 else {
                     snapshot = formatter;
@@ -246,7 +328,8 @@ export class McpResponse {
                 fetchData: true,
                 requestFilePath: this.#attachedNetworkRequestOptions?.requestFilePath,
                 responseFilePath: this.#attachedNetworkRequestOptions?.responseFilePath,
-                saveFile: (data, filename) => context.saveFile(data, filename),
+                saveFile: (data, filename, extension) => context.saveFile(data, filename, extension),
+                redactNetworkHeaders: this.#redactNetworkHeaders,
             });
             detailedNetworkRequest = formatter;
         }
@@ -270,7 +353,7 @@ export class McpResponse {
                 const formatter = new IssueFormatter(message, {
                     id: consoleMessageStableId,
                     requestIdResolver: context.resolveCdpRequestId.bind(context, this.#page),
-                    elementIdResolver: context.resolveCdpElementId.bind(context, this.#page),
+                    elementIdResolver: this.#page.resolveCdpElementId.bind(this.#page),
                 });
                 if (!formatter.isValid()) {
                     throw new Error("Can't provide details for the msgid " + consoleMessageStableId);
@@ -280,12 +363,18 @@ export class McpResponse {
         }
         let extensions;
         if (this.#listExtensions) {
-            extensions = context.listExtensions();
+            extensions = await context.listExtensions();
         }
         let inPageTools;
         if (this.#listInPageTools) {
-            inPageTools = await getToolGroup(context.getSelectedMcpPage());
-            context.setInPageTools(inPageTools);
+            const page = this.#page ?? context.getSelectedMcpPage();
+            inPageTools = await getToolGroup(page);
+            page.inPageTools = inPageTools;
+        }
+        let webmcpTools;
+        if (this.#listWebMcpTools && this.#args.experimentalWebmcp) {
+            const page = this.#page ?? context.getSelectedMcpPage();
+            webmcpTools = page.getWebMcpTools();
         }
         let consoleMessages;
         if (this.#consoleDataOptions?.include) {
@@ -349,7 +438,8 @@ export class McpResponse {
                     selectedInDevToolsUI: context.getNetworkRequestStableId(request) ===
                         this.#networkRequestsOptions?.networkRequestIdInDevToolsUI,
                     fetchData: false,
-                    saveFile: (data, filename) => context.saveFile(data, filename),
+                    saveFile: (data, filename, extension) => context.saveFile(data, filename, extension),
+                    redactNetworkHeaders: this.#redactNetworkHeaders,
                 })));
             }
         }
@@ -364,6 +454,7 @@ export class McpResponse {
             extensions,
             lighthouseResult: this.#attachedLighthouseResult,
             inPageTools,
+            webmcpTools,
         });
     }
     format(toolName, context, data) {
@@ -529,6 +620,32 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 structuredContent.snapshot = data.snapshot.toJSON();
             }
         }
+        if (this.#heapSnapshotOptions?.include) {
+            response.push('## Heap Snapshot Data');
+            const stats = this.#heapSnapshotOptions.stats;
+            const staticData = this.#heapSnapshotOptions.staticData;
+            if (stats) {
+                response.push(`Statistics: ${JSON.stringify(stats, null, 2)}`);
+                structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
+                structuredContent.heapSnapshot.stats = stats;
+            }
+            if (staticData) {
+                response.push(`Static Data: ${JSON.stringify(staticData, null, 2)}`);
+                structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
+                structuredContent.heapSnapshot.staticData = staticData;
+            }
+            const aggregates = this.#heapSnapshotOptions.aggregates;
+            if (aggregates) {
+                const sortedEntries = HeapSnapshotFormatter.sort(aggregates);
+                const paginationData = this.#dataWithPagination(sortedEntries, this.#heapSnapshotOptions.pagination);
+                structuredContent.pagination = paginationData.pagination;
+                response.push(...paginationData.info);
+                const paginatedRecord = Object.fromEntries(paginationData.items);
+                const formatter = new HeapSnapshotFormatter(paginatedRecord);
+                response.push(formatter.toString());
+                structuredContent.heapSnapshotData = formatter.toJSON();
+            }
+        }
         if (data.detailedNetworkRequest) {
             response.push(data.detailedNetworkRequest.toStringDetailed());
             structuredContent.networkRequest =
@@ -540,15 +657,16 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 data.detailedConsoleMessage.toJSONDetailed();
         }
         if (data.extensions) {
-            structuredContent.extensions = data.extensions;
+            const extensionArray = Array.from(data.extensions.values());
+            structuredContent.extensions = extensionArray;
             response.push('## Extensions');
-            if (data.extensions.length === 0) {
+            if (extensionArray.length === 0) {
                 response.push('No extensions installed.');
             }
             else {
-                const extensionsMessage = data.extensions
+                const extensionsMessage = extensionArray
                     .map(extension => {
-                    return `id=${extension.id} "${extension.name}" v${extension.version} ${extension.isEnabled ? 'Enabled' : 'Disabled'}`;
+                    return `id=${extension.id} "${extension.name}" v${extension.version} ${extension.enabled ? 'Enabled' : 'Disabled'}`;
                 })
                     .join('\n');
                 response.push(extensionsMessage);
@@ -572,6 +690,26 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(toolDefinitionsMessage);
             }
         }
+        if (this.#listWebMcpTools && data.webmcpTools) {
+            structuredContent.webmcpTools = data.webmcpTools.map(({ name, description, inputSchema, annotations }) => ({
+                name,
+                description,
+                inputSchema,
+                annotations,
+            }));
+            response.push('## WebMCP tools');
+            if (data.webmcpTools.length === 0) {
+                response.push('No WebMCP tools available.');
+            }
+            else {
+                const webmcpToolsMessage = data.webmcpTools
+                    .map(tool => {
+                    return `name="${tool.name}", description="${tool.description}", inputSchema=${JSON.stringify(tool.inputSchema)}, annotations=${JSON.stringify(tool.annotations)}`;
+                })
+                    .join('\n');
+                response.push(webmcpToolsMessage);
+            }
+        }
         if (this.#networkRequestsOptions?.include && data.networkRequests) {
             const requests = data.networkRequests;
             response.push('## Network requests');

package/build/src/PageCollector.js

@@ -6,6 +6,7 @@
 import { FakeIssuesManager } from './DevtoolsUtils.js';
 import { logger } from './logger.js';
 import { DevTools } from './third_party/index.js';
+import { createIdGenerator, stableIdSymbol, } from './utils/id.js';
 export class UncaughtError {
     details;
     targetId;
@@ -14,16 +15,6 @@ export class UncaughtError {
         this.targetId = targetId;
     }
 }
-function createIdGenerator() {
-    let i = 1;
-    return () => {
-        if (i === Number.MAX_SAFE_INTEGER) {
-            i = 0;
-        }
-        return i++;
-    };
-}
-export const stableIdSymbol = Symbol('stableIdSymbol');
 export class PageCollector {
     #browser;
     #listenersInitializer;
@@ -206,34 +197,25 @@ class PageEventSubscriber {
     async subscribe() {
         this.#resetIssueAggregator();
         this.#page.on('framenavigated', this.#onFrameNavigated);
-        this.#session.on('Audits.issueAdded', this.#onIssueAdded);
+        this.#page.on('issue', this.#onIssueAdded);
         this.#session.on('Runtime.exceptionThrown', this.#onExceptionThrown);
-        try {
-            await this.#session.send('Audits.enable');
-        }
-        catch (error) {
-            logger('Error subscribing to issues', error);
-        }
     }
     unsubscribe() {
         this.#seenKeys.clear();
         this.#seenIssues.clear();
         this.#page.off('framenavigated', this.#onFrameNavigated);
-        this.#session.off('Audits.issueAdded', this.#onIssueAdded);
+        this.#page.off('issue', this.#onIssueAdded);
         this.#session.off('Runtime.exceptionThrown', this.#onExceptionThrown);
         if (this.#issueAggregator) {
             this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedIssue);
         }
-        void this.#session.send('Audits.disable').catch(() => {
-            // might fail.
-        });
     }
     #onAggregatedIssue = (event) => {
         if (this.#seenIssues.has(event.data)) {
             return;
         }
         this.#seenIssues.add(event.data);
-        this.#page.emit('issue', event.data);
+        this.#page.emit('devtoolsAggregatedIssue', event.data);
     };
     #onExceptionThrown = (event) => {
         this.#page.emit('uncaughtError', new UncaughtError(event.exceptionDetails, this.#targetId));
@@ -248,9 +230,13 @@ class PageEventSubscriber {
         this.#seenIssues.clear();
         this.#resetIssueAggregator();
     };
-    #onIssueAdded = (data) => {
+    #onIssueAdded = (inspectorIssue) => {
         try {
-            const inspectorIssue = data.issue;
+            // DevTools currently defines this protocol issue code but has no
+            // IssuesManager handler for it, so calling into the mapper only warns.
+            if (String(inspectorIssue.code) === 'PerformanceIssue') {
+                return;
+            }
             const issue = DevTools.createIssuesFromProtocolIssue(null, 
             // @ts-expect-error Protocol types diverge.
             inspectorIssue)[0];