chrome-devtools-mcp 0.8.1 → 0.10.0

package/build/src/McpContext.js

@@ -6,7 +6,9 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { extractUrlLikeFromDevToolsTitle, urlsEqual } from './DevtoolsUtils.js';
 import { NetworkCollector, PageCollector } from './PageCollector.js';
+import { Locator } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { takeSnapshot } from './tools/snapshot.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
@@ -43,6 +45,7 @@ export class McpContext {
     logger;
     // The most recent page state.
     #pages = [];
+    #pageToDevToolsPage = new Map();
     #selectedPageIdx = 0;
     // The most recent snapshot.
     #textSnapshot = null;
@@ -54,22 +57,31 @@ export class McpContext {
     #dialog;
     #nextSnapshotId = 1;
     #traceResults = [];
-    constructor(browser, logger) {
+    #locatorClass;
+    #options;
+    constructor(browser, logger, options, locatorClass) {
         this.browser = browser;
         this.logger = logger;
-        this.#networkCollector = new NetworkCollector(this.browser, (page, collect) => {
-            page.on('request', request => {
-                collect(request);
-            });
-        });
-        this.#consoleCollector = new PageCollector(this.browser, (page, collect) => {
-            page.on('console', event => {
-                collect(event);
-            });
-            page.on('pageerror', event => {
-                collect(event);
-            });
-        });
+        this.#locatorClass = locatorClass;
+        this.#options = options;
+        this.#networkCollector = new NetworkCollector(this.browser, undefined, this.#options.experimentalIncludeAllPages);
+        this.#consoleCollector = new PageCollector(this.browser, collect => {
+            return {
+                console: event => {
+                    collect(event);
+                },
+                pageerror: event => {
+                    if (event instanceof Error) {
+                        collect(event);
+                    }
+                    else {
+                        const error = new Error(`${event}`);
+                        error.stack = undefined;
+                        collect(error);
+                    }
+                },
+            };
+        }, this.#options.experimentalIncludeAllPages);
     }
     async #init() {
         await this.createPagesSnapshot();
@@ -77,18 +89,60 @@ export class McpContext {
         await this.#networkCollector.init();
         await this.#consoleCollector.init();
     }
-    static async from(browser, logger) {
-        const context = new McpContext(browser, logger);
+    static async from(browser, logger, opts, 
+    /* Let tests use unbundled Locator class to avoid overly strict checks within puppeteer that fail when mixing bundled and unbundled class instances */
+    locatorClass = Locator) {
+        const context = new McpContext(browser, logger, opts, locatorClass);
         await context.#init();
         return context;
     }
-    getNetworkRequests() {
+    resolveCdpRequestId(cdpRequestId) {
+        const selectedPage = this.getSelectedPage();
+        if (!cdpRequestId) {
+            this.logger('no network request');
+            return;
+        }
+        const request = this.#networkCollector.find(selectedPage, request => {
+            // @ts-expect-error id is internal.
+            return request.id === cdpRequestId;
+        });
+        if (!request) {
+            this.logger('no network request for ' + cdpRequestId);
+            return;
+        }
+        return this.#networkCollector.getIdForResource(request);
+    }
+    resolveCdpElementId(cdpBackendNodeId) {
+        if (!cdpBackendNodeId) {
+            this.logger('no cdpBackendNodeId');
+            return;
+        }
+        // TODO: index by backendNodeId instead.
+        const queue = [this.#textSnapshot?.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;
+    }
+    getNetworkRequests(includePreservedRequests) {
         const page = this.getSelectedPage();
-        return this.#networkCollector.getData(page);
+        return this.#networkCollector.getData(page, includePreservedRequests);
     }
-    getConsoleData() {
+    getConsoleData(includePreservedMessages) {
         const page = this.getSelectedPage();
-        return this.#consoleCollector.getData(page);
+        return this.#consoleCollector.getData(page, includePreservedMessages);
+    }
+    getConsoleMessageStableId(message) {
+        return this.#consoleCollector.getIdForResource(message);
+    }
+    getConsoleMessageById(id) {
+        return this.#consoleCollector.getById(this.getSelectedPage(), id);
     }
     async newPage() {
         const page = await this.browser.newPage();
@@ -106,17 +160,8 @@ export class McpContext {
         this.setSelectedPageIdx(0);
         await page.close({ runBeforeUnload: false });
     }
-    getNetworkRequestByUrl(url) {
-        const requests = this.getNetworkRequests();
-        if (!requests.length) {
-            throw new Error('No requests found for selected page');
-        }
-        for (const request of requests) {
-            if (request.url() === url) {
-                return request;
-            }
-        }
-        throw new Error('Request not found for selected page');
+    getNetworkRequestById(reqid) {
+        return this.#networkCollector.getById(this.getSelectedPage(), reqid);
     }
     setNetworkConditions(conditions) {
         const page = this.getSelectedPage();
@@ -226,19 +271,88 @@ export class McpContext {
      * Creates a snapshot of the pages.
      */
     async createPagesSnapshot() {
-        this.#pages = await this.browser.pages();
+        const allPages = await this.browser.pages(this.#options.experimentalIncludeAllPages);
+        this.#pages = allPages.filter(page => {
+            // If we allow debugging DevTools windows, return all pages.
+            // If we are in regular mode, the user should only see non-DevTools page.
+            return (this.#options.experimentalDevToolsDebugging ||
+                !page.url().startsWith('devtools://'));
+        });
+        await this.detectOpenDevToolsWindows();
         return this.#pages;
     }
+    async detectOpenDevToolsWindows() {
+        this.logger('Detecting open DevTools windows');
+        const pages = await this.browser.pages(this.#options.experimentalIncludeAllPages);
+        this.#pageToDevToolsPage = new Map();
+        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)) {
+                            this.#pageToDevToolsPage.set(page, devToolsPage);
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger('Issue occurred while trying to find DevTools', error);
+                }
+            }
+        }
+    }
     getPages() {
         return this.#pages;
     }
+    getDevToolsPage(page) {
+        return this.#pageToDevToolsPage.get(page);
+    }
+    async getDevToolsData() {
+        try {
+            this.logger('Getting DevTools UI data');
+            const selectedPage = this.getSelectedPage();
+            const devtoolsPage = this.getDevToolsPage(selectedPage);
+            if (!devtoolsPage) {
+                this.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) {
+            this.logger('error getting devtools data', err);
+        }
+        return {};
+    }
     /**
      * Creates a text snapshot of a page.
      */
-    async createTextSnapshot() {
+    async createTextSnapshot(verbose = false, devtoolsData = undefined) {
         const page = this.getSelectedPage();
         const rootNode = await page.accessibility.snapshot({
             includeIframes: true,
+            interestingOnly: !verbose,
         });
         if (!rootNode) {
             return;
@@ -273,6 +387,10 @@ export class McpContext {
             snapshotId: String(snapshotId),
             idToNode,
         };
+        const data = devtoolsData ?? (await this.getDevToolsData());
+        if (data?.cdpBackendNodeId) {
+            this.#textSnapshot.selectedElementUid = this.resolveCdpElementId(data?.cdpBackendNodeId);
+        }
     }
     getTextSnapshot() {
         return this.#textSnapshot;
@@ -316,4 +434,35 @@ export class McpContext {
         const waitForHelper = this.getWaitForHelper(page, cpuMultiplier, networkMultiplier);
         return waitForHelper.waitForEventsAfterAction(action);
     }
+    getNetworkRequestStableId(request) {
+        return this.#networkCollector.getIdForResource(request);
+    }
+    waitForTextOnPage({ text, timeout, }) {
+        const page = this.getSelectedPage();
+        const frames = page.frames();
+        const locator = this.#locatorClass.race(frames.flatMap(frame => [
+            frame.locator(`aria/${text}`),
+            frame.locator(`text/${text}`),
+        ]));
+        if (timeout) {
+            locator.setTimeout(timeout);
+        }
+        return locator.wait();
+    }
+    /**
+     * We need to ignore favicon request as they make our test flaky
+     */
+    async setUpNetworkCollectorForTesting() {
+        this.#networkCollector = new NetworkCollector(this.browser, collect => {
+            return {
+                request: req => {
+                    if (req.url().includes('favicon.ico')) {
+                        return;
+                    }
+                    collect(req);
+                },
+            };
+        });
+        await this.#networkCollector.init();
+    }
 }

package/build/src/McpResponse.js

@@ -1,22 +1,28 @@
-import { formatConsoleEvent } from './formatters/consoleFormatter.js';
+import { formatConsoleEventShort, formatConsoleEventVerbose, } from './formatters/consoleFormatter.js';
 import { getFormattedHeaderValue, getFormattedResponseBody, getFormattedRequestBody, getShortDescriptionForRequest, getStatusFromRequest, } from './formatters/networkFormatter.js';
-import { formatA11ySnapshot } from './formatters/snapshotFormatter.js';
+import { formatSnapshotNode } from './formatters/snapshotFormatter.js';
 import { handleDialog } from './tools/pages.js';
 import { paginate } from './utils/pagination.js';
 export class McpResponse {
     #includePages = false;
-    #includeSnapshot = false;
-    #attachedNetworkRequestData;
-    #includeConsoleData = false;
+    #snapshotParams;
+    #attachedNetworkRequestId;
+    #attachedConsoleMessageId;
     #textResponseLines = [];
-    #formattedConsoleData;
     #images = [];
     #networkRequestsOptions;
+    #consoleDataOptions;
+    #devToolsData;
+    attachDevToolsData(data) {
+        this.#devToolsData = data;
+    }
     setIncludePages(value) {
         this.#includePages = value;
     }
-    setIncludeSnapshot(value) {
-        this.#includeSnapshot = value;
+    includeSnapshot(params) {
+        this.#snapshotParams = params ?? {
+            verbose: false,
+        };
     }
     setIncludeNetworkRequests(value, options) {
         if (!value) {
@@ -32,16 +38,33 @@ export class McpResponse {
                 }
                 : undefined,
             resourceTypes: options?.resourceTypes,
+            includePreservedRequests: options?.includePreservedRequests,
+            networkRequestIdInDevToolsUI: options?.networkRequestIdInDevToolsUI,
         };
     }
-    setIncludeConsoleData(value) {
-        this.#includeConsoleData = value;
-    }
-    attachNetworkRequest(url) {
-        this.#attachedNetworkRequestData = {
-            networkRequestUrl: url,
+    setIncludeConsoleData(value, options) {
+        if (!value) {
+            this.#consoleDataOptions = undefined;
+            return;
+        }
+        this.#consoleDataOptions = {
+            include: value,
+            pagination: options?.pageSize || options?.pageIdx
+                ? {
+                    pageSize: options.pageSize,
+                    pageIdx: options.pageIdx,
+                }
+                : undefined,
+            types: options?.types,
+            includePreservedMessages: options?.includePreservedMessages,
         };
     }
+    attachNetworkRequest(reqid) {
+        this.#attachedNetworkRequestId = reqid;
+    }
+    attachConsoleMessage(msgid) {
+        this.#attachedConsoleMessageId = msgid;
+    }
     get includePages() {
         return this.#includePages;
     }
@@ -49,14 +72,20 @@ export class McpResponse {
         return this.#networkRequestsOptions?.include ?? false;
     }
     get includeConsoleData() {
-        return this.#includeConsoleData;
+        return this.#consoleDataOptions?.include ?? false;
     }
-    get attachedNetworkRequestUrl() {
-        return this.#attachedNetworkRequestData?.networkRequestUrl;
+    get attachedNetworkRequestId() {
+        return this.#attachedNetworkRequestId;
     }
     get networkRequestsPageIdx() {
         return this.#networkRequestsOptions?.pagination?.pageIdx;
     }
+    get consoleMessagesPageIdx() {
+        return this.#consoleDataOptions?.pagination?.pageIdx;
+    }
+    get consoleMessagesTypes() {
+        return this.#consoleDataOptions?.types;
+    }
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
     }
@@ -69,37 +98,111 @@ export class McpResponse {
     get images() {
         return this.#images;
     }
-    get includeSnapshot() {
-        return this.#includeSnapshot;
+    get snapshotParams() {
+        return this.#snapshotParams;
     }
     async handle(toolName, context) {
         if (this.#includePages) {
             await context.createPagesSnapshot();
         }
-        if (this.#includeSnapshot) {
-            await context.createTextSnapshot();
+        let formattedSnapshot;
+        if (this.#snapshotParams) {
+            await context.createTextSnapshot(this.#snapshotParams.verbose, this.#devToolsData);
+            const snapshot = context.getTextSnapshot();
+            if (snapshot) {
+                if (this.#snapshotParams.filePath) {
+                    await context.saveFile(new TextEncoder().encode(formatSnapshotNode(snapshot.root, snapshot)), this.#snapshotParams.filePath);
+                    formattedSnapshot = `Saved snapshot to ${this.#snapshotParams.filePath}.`;
+                }
+                else {
+                    formattedSnapshot = formatSnapshotNode(snapshot.root, snapshot);
+                }
+            }
         }
-        let formattedConsoleMessages;
-        if (this.#attachedNetworkRequestData?.networkRequestUrl) {
-            const request = context.getNetworkRequestByUrl(this.#attachedNetworkRequestData.networkRequestUrl);
-            this.#attachedNetworkRequestData.requestBody =
-                await getFormattedRequestBody(request);
+        const bodies = {};
+        if (this.#attachedNetworkRequestId) {
+            const request = context.getNetworkRequestById(this.#attachedNetworkRequestId);
+            bodies.requestBody = await getFormattedRequestBody(request);
             const response = request.response();
             if (response) {
-                this.#attachedNetworkRequestData.responseBody =
-                    await getFormattedResponseBody(response);
+                bodies.responseBody = await getFormattedResponseBody(response);
+            }
+        }
+        let consoleData;
+        if (this.#attachedConsoleMessageId) {
+            const message = context.getConsoleMessageById(this.#attachedConsoleMessageId);
+            const consoleMessageStableId = this.#attachedConsoleMessageId;
+            if ('args' in message) {
+                const consoleMessage = message;
+                consoleData = {
+                    consoleMessageStableId,
+                    type: consoleMessage.type(),
+                    message: consoleMessage.text(),
+                    args: await Promise.all(consoleMessage.args().map(async (arg) => {
+                        const stringArg = await arg.jsonValue().catch(() => {
+                            // Ignore errors.
+                        });
+                        return typeof stringArg === 'object'
+                            ? JSON.stringify(stringArg)
+                            : String(stringArg);
+                    })),
+                };
+            }
+            else {
+                consoleData = {
+                    consoleMessageStableId,
+                    type: 'error',
+                    message: message.message,
+                    args: [],
+                };
             }
         }
-        if (this.#includeConsoleData) {
-            const consoleMessages = context.getConsoleData();
-            if (consoleMessages) {
-                formattedConsoleMessages = await Promise.all(consoleMessages.map(message => formatConsoleEvent(message)));
-                this.#formattedConsoleData = formattedConsoleMessages;
+        let consoleListData;
+        if (this.#consoleDataOptions?.include) {
+            let messages = context.getConsoleData(this.#consoleDataOptions.includePreservedMessages);
+            if (this.#consoleDataOptions.types?.length) {
+                const normalizedTypes = new Set(this.#consoleDataOptions.types);
+                messages = messages.filter(message => {
+                    if ('type' in message) {
+                        return normalizedTypes.has(message.type());
+                    }
+                    return normalizedTypes.has('error');
+                });
             }
+            consoleListData = await Promise.all(messages.map(async (item) => {
+                const consoleMessageStableId = context.getConsoleMessageStableId(item);
+                if ('args' in item) {
+                    const consoleMessage = item;
+                    return {
+                        consoleMessageStableId,
+                        type: consoleMessage.type(),
+                        message: consoleMessage.text(),
+                        args: await Promise.all(consoleMessage.args().map(async (arg) => {
+                            const stringArg = await arg.jsonValue().catch(() => {
+                                // Ignore errors.
+                            });
+                            return typeof stringArg === 'object'
+                                ? JSON.stringify(stringArg)
+                                : String(stringArg);
+                        })),
+                    };
+                }
+                return {
+                    consoleMessageStableId,
+                    type: 'error',
+                    message: item.message,
+                    args: [],
+                };
+            }));
         }
-        return this.format(toolName, context);
+        return this.format(toolName, context, {
+            bodies,
+            consoleData,
+            consoleListData,
+            formattedSnapshot,
+        });
     }
-    format(toolName, context) {
+    format(toolName, context, data) {
         const response = [`# ${toolName} response`];
         for (const line of this.#textResponseLines) {
             response.push(line);
@@ -133,17 +236,14 @@ Call ${handleDialog.name} to handle it before continuing.`);
             }
             response.push(...parts);
         }
-        if (this.#includeSnapshot) {
-            const snapshot = context.getTextSnapshot();
-            if (snapshot) {
-                const formattedSnapshot = formatA11ySnapshot(snapshot.root);
-                response.push('## Page content');
-                response.push(formattedSnapshot);
-            }
+        if (data.formattedSnapshot) {
+            response.push('## Page content');
+            response.push(data.formattedSnapshot);
         }
-        response.push(...this.#getIncludeNetworkRequestsData(context));
+        response.push(...this.#formatNetworkRequestData(context, data.bodies));
+        response.push(...this.#formatConsoleData(data.consoleData));
         if (this.#networkRequestsOptions?.include) {
-            let requests = context.getNetworkRequests();
+            let requests = context.getNetworkRequests(this.#networkRequestsOptions?.includePreservedRequests);
             // Apply resource type filtering if specified
             if (this.#networkRequestsOptions.resourceTypes?.length) {
                 const normalizedTypes = new Set(this.#networkRequestsOptions.resourceTypes);
@@ -157,17 +257,21 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 const data = this.#dataWithPagination(requests, this.#networkRequestsOptions.pagination);
                 response.push(...data.info);
                 for (const request of data.items) {
-                    response.push(getShortDescriptionForRequest(request));
+                    response.push(getShortDescriptionForRequest(request, context.getNetworkRequestStableId(request), context.getNetworkRequestStableId(request) ===
+                        this.#networkRequestsOptions?.networkRequestIdInDevToolsUI));
                 }
             }
             else {
                 response.push('No requests found.');
             }
         }
-        if (this.#includeConsoleData && this.#formattedConsoleData) {
+        if (this.#consoleDataOptions?.include) {
+            const messages = data.consoleListData ?? [];
             response.push('## Console messages');
-            if (this.#formattedConsoleData.length) {
-                response.push(...this.#formattedConsoleData);
+            if (messages.length) {
+                const data = this.#dataWithPagination(messages, this.#consoleDataOptions.pagination);
+                response.push(...data.info);
+                response.push(...data.items.map(message => formatConsoleEventShort(message)));
             }
             else {
                 response.push('<no console messages found>');
@@ -206,22 +310,30 @@ Call ${handleDialog.name} to handle it before continuing.`);
             items: paginationResult.items,
         };
     }
-    #getIncludeNetworkRequestsData(context) {
+    #formatConsoleData(data) {
+        const response = [];
+        if (!data) {
+            return response;
+        }
+        response.push(formatConsoleEventVerbose(data));
+        return response;
+    }
+    #formatNetworkRequestData(context, data) {
         const response = [];
-        const url = this.#attachedNetworkRequestData?.networkRequestUrl;
-        if (!url) {
+        const id = this.#attachedNetworkRequestId;
+        if (!id) {
             return response;
         }
-        const httpRequest = context.getNetworkRequestByUrl(url);
+        const httpRequest = context.getNetworkRequestById(id);
         response.push(`## Request ${httpRequest.url()}`);
         response.push(`Status:  ${getStatusFromRequest(httpRequest)}`);
         response.push(`### Request Headers`);
         for (const line of getFormattedHeaderValue(httpRequest.headers())) {
             response.push(line);
         }
-        if (this.#attachedNetworkRequestData?.requestBody) {
+        if (data.requestBody) {
             response.push(`### Request Body`);
-            response.push(this.#attachedNetworkRequestData.requestBody);
+            response.push(data.requestBody);
         }
         const httpResponse = httpRequest.response();
         if (httpResponse) {
@@ -230,9 +342,9 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(line);
             }
         }
-        if (this.#attachedNetworkRequestData?.responseBody) {
+        if (data.responseBody) {
             response.push(`### Response Body`);
-            response.push(this.#attachedNetworkRequestData.responseBody);
+            response.push(data.responseBody);
         }
         const httpFailure = httpRequest.failure();
         if (httpFailure) {
@@ -244,7 +356,7 @@ Call ${handleDialog.name} to handle it before continuing.`);
             response.push(`### Redirect chain`);
             let indent = 0;
             for (const request of redirectChain.reverse()) {
-                response.push(`${'  '.repeat(indent)}${getShortDescriptionForRequest(request)}`);
+                response.push(`${'  '.repeat(indent)}${getShortDescriptionForRequest(request, context.getNetworkRequestStableId(request))}`);
                 indent++;
             }
         }