chrome-devtools-mcp 0.9.0 → 0.10.0

package/build/src/McpContext.js

@@ -6,6 +6,7 @@
 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';
@@ -44,6 +45,7 @@ export class McpContext {
     logger;
     // The most recent page state.
     #pages = [];
+    #pageToDevToolsPage = new Map();
     #selectedPageIdx = 0;
     // The most recent snapshot.
     #textSnapshot = null;
@@ -56,11 +58,13 @@ export class McpContext {
     #nextSnapshotId = 1;
     #traceResults = [];
     #locatorClass;
-    constructor(browser, logger, locatorClass) {
+    #options;
+    constructor(browser, logger, options, locatorClass) {
         this.browser = browser;
         this.logger = logger;
         this.#locatorClass = locatorClass;
-        this.#networkCollector = new NetworkCollector(this.browser);
+        this.#options = options;
+        this.#networkCollector = new NetworkCollector(this.browser, undefined, this.#options.experimentalIncludeAllPages);
         this.#consoleCollector = new PageCollector(this.browser, collect => {
             return {
                 console: event => {
@@ -77,7 +81,7 @@ export class McpContext {
                     }
                 },
             };
-        });
+        }, this.#options.experimentalIncludeAllPages);
     }
     async #init() {
         await this.createPagesSnapshot();
@@ -85,13 +89,47 @@ export class McpContext {
         await this.#networkCollector.init();
         await this.#consoleCollector.init();
     }
-    static async from(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, locatorClass);
+        const context = new McpContext(browser, logger, opts, locatorClass);
         await context.#init();
         return context;
     }
+    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, includePreservedRequests);
@@ -233,16 +271,84 @@ 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(verbose = false) {
+    async createTextSnapshot(verbose = false, devtoolsData = undefined) {
         const page = this.getSelectedPage();
         const rootNode = await page.accessibility.snapshot({
             includeIframes: true,
@@ -281,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;

package/build/src/McpResponse.js

@@ -1,24 +1,28 @@
 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;
-    #includeVerboseSnapshot = false;
+    #snapshotParams;
     #attachedNetworkRequestId;
     #attachedConsoleMessageId;
     #textResponseLines = [];
     #images = [];
     #networkRequestsOptions;
     #consoleDataOptions;
+    #devToolsData;
+    attachDevToolsData(data) {
+        this.#devToolsData = data;
+    }
     setIncludePages(value) {
         this.#includePages = value;
     }
-    setIncludeSnapshot(value, verbose = false) {
-        this.#includeSnapshot = value;
-        this.#includeVerboseSnapshot = verbose;
+    includeSnapshot(params) {
+        this.#snapshotParams = params ?? {
+            verbose: false,
+        };
     }
     setIncludeNetworkRequests(value, options) {
         if (!value) {
@@ -35,6 +39,7 @@ export class McpResponse {
                 : undefined,
             resourceTypes: options?.resourceTypes,
             includePreservedRequests: options?.includePreservedRequests,
+            networkRequestIdInDevToolsUI: options?.networkRequestIdInDevToolsUI,
         };
     }
     setIncludeConsoleData(value, options) {
@@ -93,18 +98,26 @@ export class McpResponse {
     get images() {
         return this.#images;
     }
-    get includeSnapshot() {
-        return this.#includeSnapshot;
-    }
-    get includeVersboseSnapshot() {
-        return this.#includeVerboseSnapshot;
+    get snapshotParams() {
+        return this.#snapshotParams;
     }
     async handle(toolName, context) {
         if (this.#includePages) {
             await context.createPagesSnapshot();
         }
-        if (this.#includeSnapshot) {
-            await context.createTextSnapshot(this.#includeVerboseSnapshot);
+        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);
+                }
+            }
         }
         const bodies = {};
         if (this.#attachedNetworkRequestId) {
@@ -186,6 +199,7 @@ export class McpResponse {
             bodies,
             consoleData,
             consoleListData,
+            formattedSnapshot,
         });
     }
     format(toolName, context, data) {
@@ -222,13 +236,9 @@ 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.#formatNetworkRequestData(context, data.bodies));
         response.push(...this.#formatConsoleData(data.consoleData));
@@ -247,7 +257,8 @@ 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, context.getNetworkRequestStableId(request)));
+                    response.push(getShortDescriptionForRequest(request, context.getNetworkRequestStableId(request), context.getNetworkRequestStableId(request) ===
+                        this.#networkRequestsOptions?.networkRequestIdInDevToolsUI));
                 }
             }
             else {

package/build/src/PageCollector.js

@@ -18,18 +18,20 @@ export class PageCollector {
     #listenersInitializer;
     #listeners = new WeakMap();
     #maxNavigationSaved = 3;
+    #includeAllPages;
     /**
      * This maps a Page to a list of navigations with a sub-list
      * of all collected resources.
      * The newer navigations come first.
      */
     storage = new WeakMap();
-    constructor(browser, listeners) {
+    constructor(browser, listeners, includeAllPages) {
         this.#browser = browser;
         this.#listenersInitializer = listeners;
+        this.#includeAllPages = includeAllPages;
     }
     async init() {
-        const pages = await this.#browser.pages();
+        const pages = await this.#browser.pages(this.#includeAllPages);
         for (const page of pages) {
             this.#initializePage(page);
         }
@@ -118,14 +120,24 @@ export class PageCollector {
         if (!navigations) {
             throw new Error('No requests found for selected page');
         }
+        const item = this.find(page, item => item[stableIdSymbol] === stableId);
+        if (item) {
+            return item;
+        }
+        throw new Error('Request not found for selected page');
+    }
+    find(page, filter) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            return;
+        }
         for (const navigation of navigations) {
-            for (const collected of navigation) {
-                if (collected[stableIdSymbol] === stableId) {
-                    return collected;
-                }
+            const item = navigation.find(filter);
+            if (item) {
+                return item;
             }
         }
-        throw new Error('Request not found for selected page');
+        return;
     }
 }
 export class NetworkCollector extends PageCollector {
@@ -135,8 +147,8 @@ export class NetworkCollector extends PageCollector {
                 collect(req);
             },
         };
-    }) {
-        super(browser, listeners);
+    }, includeAllPages) {
+        super(browser, listeners, includeAllPages);
     }
     splitAfterNavigation(page) {
         const navigations = this.storage.get(page) ?? [];

package/build/src/browser.js

@@ -6,17 +6,15 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { logger } from './logger.js';
 import { puppeteer } from './third_party/index.js';
 let browser;
-function makeTargetFilter(devtools) {
+function makeTargetFilter() {
     const ignoredPrefixes = new Set([
         'chrome://',
         'chrome-extension://',
         'chrome-untrusted://',
     ]);
-    if (!devtools) {
-        ignoredPrefixes.add('devtools://');
-    }
     return function targetFilter(target) {
         if (target.url() === 'chrome://newtab/') {
             return true;
@@ -34,9 +32,9 @@ export async function ensureBrowserConnected(options) {
         return browser;
     }
     const connectOptions = {
-        targetFilter: makeTargetFilter(options.devtools),
+        targetFilter: makeTargetFilter(),
         defaultViewport: null,
-        handleDevToolsAsPage: options.devtools,
+        handleDevToolsAsPage: true,
     };
     if (options.wsEndpoint) {
         connectOptions.browserWSEndpoint = options.wsEndpoint;
@@ -50,7 +48,9 @@ export async function ensureBrowserConnected(options) {
     else {
         throw new Error('Either browserURL or wsEndpoint must be provided');
     }
+    logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
     browser = await puppeteer.connect(connectOptions);
+    logger('Connected Puppeteer');
     return browser;
 }
 export async function launch(options) {
@@ -85,7 +85,7 @@ export async function launch(options) {
     try {
         const browser = await puppeteer.launch({
             channel: puppeteerChannel,
-            targetFilter: makeTargetFilter(options.devtools),
+            targetFilter: makeTargetFilter(),
             executablePath,
             defaultViewport: null,
             userDataDir,
@@ -93,7 +93,7 @@ export async function launch(options) {
             headless,
             args,
             acceptInsecureCerts: options.acceptInsecureCerts,
-            handleDevToolsAsPage: options.devtools,
+            handleDevToolsAsPage: true,
         });
         if (options.logFile) {
             // FIXME: we are probably subscribing too late to catch startup logs. We

package/build/src/cli.js

@@ -123,6 +123,11 @@ export const cliOptions = {
         describe: 'Whether to enable automation over DevTools targets',
         hidden: true,
     },
+    experimentalIncludeAllPages: {
+        type: 'boolean',
+        describe: 'Whether to include all kinds of pages such as webviews or background pages as pages.',
+        hidden: true,
+    },
     chromeArg: {
         type: 'array',
         describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
@@ -130,17 +135,17 @@ export const cliOptions = {
     categoryEmulation: {
         type: 'boolean',
         default: true,
-        describe: 'Set to false to exlcude tools related to emulation.',
+        describe: 'Set to false to exclude tools related to emulation.',
     },
     categoryPerformance: {
         type: 'boolean',
         default: true,
-        describe: 'Set to false to exlcude tools related to performance.',
+        describe: 'Set to false to exclude tools related to performance.',
     },
     categoryNetwork: {
         type: 'boolean',
         default: true,
-        describe: 'Set to false to exlcude tools related to network.',
+        describe: 'Set to false to exclude tools related to network.',
     },
 };
 export function parseArguments(version, argv = process.argv) {

package/build/src/formatters/networkFormatter.js

@@ -5,9 +5,9 @@
  */
 import { isUtf8 } from 'node:buffer';
 const BODY_CONTEXT_SIZE_LIMIT = 10000;
-export function getShortDescriptionForRequest(request, id) {
+export function getShortDescriptionForRequest(request, id, selectedInDevToolsUI = false) {
     // TODO truncate the URL
-    return `reqid=${id} ${request.method()} ${request.url()} ${getStatusFromRequest(request)}`;
+    return `reqid=${id} ${request.method()} ${request.url()} ${getStatusFromRequest(request)}${selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
 }
 export function getStatusFromRequest(request) {
     const httpResponse = request.response();

package/build/src/formatters/snapshotFormatter.js

@@ -1,10 +1,15 @@
-export function formatA11ySnapshot(serializedAXNodeRoot, depth = 0) {
+export function formatSnapshotNode(root, snapshot, depth = 0) {
     let result = '';
-    const attributes = getAttributes(serializedAXNodeRoot);
-    const line = ' '.repeat(depth * 2) + attributes.join(' ') + '\n';
+    const attributes = getAttributes(root);
+    const line = ' '.repeat(depth * 2) +
+        attributes.join(' ') +
+        (root.id === snapshot?.selectedElementUid
+            ? ' [selected in the DevTools Elements panel]'
+            : '') +
+        '\n';
     result += line;
-    for (const child of serializedAXNodeRoot.children) {
-        result += formatA11ySnapshot(child, depth + 1);
+    for (const child of root.children) {
+        result += formatSnapshotNode(child, snapshot, depth + 1);
     }
     return result;
 }
@@ -19,7 +24,14 @@ function getAttributes(serializedAXNodeRoot) {
     if (serializedAXNodeRoot.name) {
         attributes.push(`"${serializedAXNodeRoot.name}"`);
     }
-    const excluded = new Set(['id', 'role', 'name', 'elementHandle', 'children']);
+    const excluded = new Set([
+        'id',
+        'role',
+        'name',
+        'elementHandle',
+        'children',
+        'backendNodeId',
+    ]);
     const booleanPropertyMap = {
         disabled: 'disableable',
         expanded: 'expandable',

package/build/src/main.js

@@ -23,7 +23,7 @@ import * as scriptTools from './tools/script.js';
 import * as snapshotTools from './tools/snapshot.js';
 // If moved update release-please config
 // x-release-please-start-version
-const VERSION = '0.9.0';
+const VERSION = '0.10.0';
 // x-release-please-end
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
@@ -62,7 +62,10 @@ async function getContext() {
             devtools,
         });
     if (context?.browser !== browser) {
-        context = await McpContext.from(browser, logger);
+        context = await McpContext.from(browser, logger, {
+            experimentalDevToolsDebugging: devtools,
+            experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+        });
     }
     return context;
 }
@@ -94,6 +97,8 @@ function registerTool(tool) {
         try {
             logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
             const context = await getContext();
+            logger(`${tool.name} context: resolved`);
+            await context.detectOpenDevToolsWindows();
             const response = new McpResponse();
             await tool.handler({
                 params,