@nimbus21.ai/chrome-devtools-mcp 0.6.3 → 0.12.2

package/build/src/DevtoolsUtils.js

@@ -0,0 +1,208 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { PuppeteerDevToolsConnection } from './DevToolsConnectionAdapter.js';
+import { ISSUE_UTILS } from './issue-descriptions.js';
+import { logger } from './logger.js';
+import { Mutex } from './Mutex.js';
+import { DevTools } from './third_party/index.js';
+export function extractUrlLikeFromDevToolsTitle(title) {
+    const match = title.match(new RegExp(`DevTools - (.*)`));
+    return match?.[1] ?? undefined;
+}
+export function urlsEqual(url1, url2) {
+    const normalizedUrl1 = normalizeUrl(url1);
+    const normalizedUrl2 = normalizeUrl(url2);
+    return normalizedUrl1 === normalizedUrl2;
+}
+/**
+ * For the sake of the MCP server, when we determine if two URLs are equal we
+ * remove some parts:
+ *
+ * 1. We do not care about the protocol.
+ * 2. We do not care about trailing slashes.
+ * 3. We do not care about "www".
+ * 4. We ignore the hash parts.
+ *
+ * For example, if the user types "record a trace on foo.com", we would want to
+ * match a tab in the connected Chrome instance that is showing "www.foo.com/"
+ */
+function normalizeUrl(url) {
+    let result = url.trim();
+    // Remove protocols
+    if (result.startsWith('https://')) {
+        result = result.slice(8);
+    }
+    else if (result.startsWith('http://')) {
+        result = result.slice(7);
+    }
+    // Remove 'www.'. This ensures that we find the right URL regardless of if the user adds `www` or not.
+    if (result.startsWith('www.')) {
+        result = result.slice(4);
+    }
+    // We use target URLs to locate DevTools but those often do
+    // no include hash.
+    const hashIdx = result.lastIndexOf('#');
+    if (hashIdx !== -1) {
+        result = result.slice(0, hashIdx);
+    }
+    // Remove trailing slash
+    if (result.endsWith('/')) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}
+/**
+ * A mock implementation of an issues manager that only implements the methods
+ * that are actually used by the IssuesAggregator
+ */
+export class FakeIssuesManager extends DevTools.Common.ObjectWrapper
+    .ObjectWrapper {
+    issues() {
+        return [];
+    }
+}
+export function mapIssueToMessageObject(issue) {
+    const count = issue.getAggregatedIssuesCount();
+    const markdownDescription = issue.getDescription();
+    const filename = markdownDescription?.file;
+    if (!markdownDescription) {
+        logger(`no description found for issue:` + issue.code);
+        return null;
+    }
+    const rawMarkdown = filename
+        ? ISSUE_UTILS.getIssueDescription(filename)
+        : null;
+    if (!rawMarkdown) {
+        logger(`no markdown ${filename} found for issue:` + issue.code);
+        return null;
+    }
+    let processedMarkdown;
+    let title;
+    try {
+        processedMarkdown =
+            DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription.substitutions);
+        const markdownAst = DevTools.Marked.Marked.lexer(processedMarkdown);
+        title =
+            DevTools.MarkdownIssueDescription.findTitleFromMarkdownAst(markdownAst);
+    }
+    catch {
+        logger('error parsing markdown for issue ' + issue.code());
+        return null;
+    }
+    if (!title) {
+        logger('cannot read issue title from ' + filename);
+        return null;
+    }
+    return {
+        type: 'issue',
+        item: issue,
+        message: title,
+        count,
+        description: processedMarkdown,
+    };
+}
+// DevTools CDP errors can get noisy.
+DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
+DevTools.I18n.DevToolsLocale.DevToolsLocale.instance({
+    create: true,
+    data: {
+        navigatorLanguage: 'en-US',
+        settingLanguage: 'en-US',
+        lookupClosestDevToolsLocale: l => l,
+    },
+});
+DevTools.I18n.i18n.registerLocaleDataForTest('en-US', {});
+export class UniverseManager {
+    #browser;
+    #createUniverseFor;
+    #universes = new WeakMap();
+    /** Guard access to #universes so we don't create unnecessary universes */
+    #mutex = new Mutex();
+    constructor(browser, factory = DEFAULT_FACTORY) {
+        this.#browser = browser;
+        this.#createUniverseFor = factory;
+    }
+    async init(pages) {
+        try {
+            await this.#mutex.acquire();
+            const promises = [];
+            for (const page of pages) {
+                promises.push(this.#createUniverseFor(page).then(targetUniverse => this.#universes.set(page, targetUniverse)));
+            }
+            this.#browser.on('targetcreated', this.#onTargetCreated);
+            this.#browser.on('targetdestroyed', this.#onTargetDestroyed);
+            await Promise.all(promises);
+        }
+        finally {
+            this.#mutex.release();
+        }
+    }
+    get(page) {
+        return this.#universes.get(page) ?? null;
+    }
+    dispose() {
+        this.#browser.off('targetcreated', this.#onTargetCreated);
+        this.#browser.off('targetdestroyed', this.#onTargetDestroyed);
+    }
+    #onTargetCreated = async (target) => {
+        const page = await target.page();
+        try {
+            await this.#mutex.acquire();
+            if (!page || this.#universes.has(page)) {
+                return;
+            }
+            this.#universes.set(page, await this.#createUniverseFor(page));
+        }
+        finally {
+            this.#mutex.release();
+        }
+    };
+    #onTargetDestroyed = async (target) => {
+        const page = await target.page();
+        try {
+            await this.#mutex.acquire();
+            if (!page || !this.#universes.has(page)) {
+                return;
+            }
+            this.#universes.delete(page);
+        }
+        finally {
+            this.#mutex.release();
+        }
+    };
+}
+const DEFAULT_FACTORY = async (page) => {
+    const settingStorage = new DevTools.Common.Settings.SettingsStorage({});
+    const universe = new DevTools.Foundation.Universe.Universe({
+        settingsCreationOptions: {
+            syncedStorage: settingStorage,
+            globalStorage: settingStorage,
+            localStorage: settingStorage,
+            settingRegistrations: DevTools.Common.SettingRegistration.getRegisteredSettings(),
+        },
+        overrideAutoStartModels: new Set([DevTools.DebuggerModel]),
+    });
+    const session = await page.createCDPSession();
+    const connection = new PuppeteerDevToolsConnection(session);
+    const targetManager = universe.context.get(DevTools.TargetManager);
+    targetManager.observeModels(DevTools.DebuggerModel, SKIP_ALL_PAUSES);
+    const target = targetManager.createTarget('main', '', 'frame', // eslint-disable-line @typescript-eslint/no-explicit-any
+    /* parentTarget */ null, session.id(), undefined, connection);
+    return { target, universe };
+};
+// We don't want to pause any DevTools universe session ever on the MCP side.
+//
+// Note that calling `setSkipAllPauses` only affects the session on which it was
+// sent. This means DevTools can still pause, step and do whatever. We just won't
+// see the `Debugger.paused`/`Debugger.resumed` events on the MCP side.
+const SKIP_ALL_PAUSES = {
+    modelAdded(model) {
+        void model.agent.invoke_setSkipAllPauses({ skip: true });
+    },
+    modelRemoved() {
+        // Do nothing.
+    },
+};

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 { NetworkCollector, PageCollector } from './PageCollector.js';
+import { extractUrlLikeFromDevToolsTitle, urlsEqual } from './DevtoolsUtils.js';
+import { NetworkCollector, ConsoleCollector } 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,7 +45,8 @@ export class McpContext {
     logger;
     // The most recent page state.
     #pages = [];
-    #selectedPageIdx = 0;
+    #pageToDevToolsPage = new Map();
+    #selectedPage;
     // The most recent snapshot.
     #textSnapshot = null;
     #networkCollector;
@@ -51,49 +54,111 @@ export class McpContext {
     #isRunningTrace = false;
     #networkConditionsMap = new WeakMap();
     #cpuThrottlingRateMap = new WeakMap();
+    #geolocationMap = new WeakMap();
     #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);
+        this.#consoleCollector = new ConsoleCollector(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);
+                    }
+                },
+                issue: event => {
+                    collect(event);
+                },
+            };
         });
     }
     async #init() {
-        await this.createPagesSnapshot();
-        this.setSelectedPageIdx(0);
-        await this.#networkCollector.init();
-        await this.#consoleCollector.init();
+        const pages = await this.createPagesSnapshot();
+        await this.#networkCollector.init(pages);
+        await this.#consoleCollector.init(pages);
     }
-    static async from(browser, logger) {
-        const context = new McpContext(browser, logger);
+    dispose() {
+        this.#networkCollector.dispose();
+        this.#consoleCollector.dispose();
+    }
+    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;
+        }
+        if (this.#textSnapshot === null) {
+            this.logger('no text snapshot');
+            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();
-        const pages = await this.createPagesSnapshot();
-        this.setSelectedPageIdx(pages.indexOf(page));
+        await this.createPagesSnapshot();
+        this.selectPage(page);
         this.#networkCollector.addPage(page);
         this.#consoleCollector.addPage(page);
         return page;
@@ -103,20 +168,10 @@ export class McpContext {
             throw new Error(CLOSE_PAGE_ERROR);
         }
         const page = this.getPageByIdx(pageIdx);
-        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();
@@ -141,6 +196,19 @@ export class McpContext {
         const page = this.getSelectedPage();
         return this.#cpuThrottlingRateMap.get(page) ?? 1;
     }
+    setGeolocation(geolocation) {
+        const page = this.getSelectedPage();
+        if (geolocation === null) {
+            this.#geolocationMap.delete(page);
+        }
+        else {
+            this.#geolocationMap.set(page, geolocation);
+        }
+    }
+    getGeolocation() {
+        const page = this.getSelectedPage();
+        return this.#geolocationMap.get(page) ?? null;
+    }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
     }
@@ -154,7 +222,7 @@ export class McpContext {
         this.#dialog = undefined;
     }
     getSelectedPage() {
-        const page = this.#pages[this.#selectedPageIdx];
+        const page = this.#selectedPage;
         if (!page) {
             throw new Error('No page selected');
         }
@@ -171,19 +239,26 @@ export class McpContext {
         }
         return page;
     }
-    getSelectedPageIdx() {
-        return this.#selectedPageIdx;
-    }
     #dialogHandler = (dialog) => {
         this.#dialog = dialog;
     };
-    setSelectedPageIdx(idx) {
-        const oldPage = this.getSelectedPage();
-        oldPage.off('dialog', this.#dialogHandler);
-        this.#selectedPageIdx = idx;
-        const newPage = this.getSelectedPage();
+    isPageSelected(page) {
+        return this.#selectedPage === page;
+    }
+    selectPage(newPage) {
+        const oldPage = this.#selectedPage;
+        if (oldPage) {
+            oldPage.off('dialog', this.#dialogHandler);
+            void oldPage.emulateFocusedPage(false).catch(error => {
+                this.logger('Error turning off focused page emulation', error);
+            });
+        }
+        this.#selectedPage = newPage;
         newPage.on('dialog', this.#dialogHandler);
         this.#updateSelectedPageTimeouts();
+        void newPage.emulateFocusedPage(true).catch(error => {
+            this.logger('Error turning on focused page emulation', error);
+        });
     }
     #updateSelectedPageTimeouts() {
         const page = this.getSelectedPage();
@@ -201,6 +276,9 @@ export class McpContext {
         const page = this.getSelectedPage();
         return page.getDefaultNavigationTimeout();
     }
+    getAXNodeByUid(uid) {
+        return this.#textSnapshot?.idToNode.get(uid);
+    }
     async getElementByUid(uid) {
         if (!this.#textSnapshot?.idToNode.size) {
             throw new Error(`No snapshot found. Use ${takeSnapshot.name} to capture one.`);
@@ -223,19 +301,92 @@ 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://'));
+        });
+        if ((!this.#selectedPage || this.#pages.indexOf(this.#selectedPage) === -1) &&
+            this.#pages[0]) {
+            this.selectPage(this.#pages[0]);
+        }
+        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;
@@ -253,6 +404,14 @@ export class McpContext {
                     ? 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;
         };
@@ -261,7 +420,14 @@ export class McpContext {
             root: rootNodeWithId,
             snapshotId: String(snapshotId),
             idToNode,
+            hasSelectedElement: false,
+            verbose,
         };
+        const data = devtoolsData ?? (await this.getDevToolsData());
+        if (data?.cdpBackendNodeId) {
+            this.#textSnapshot.hasSelectedElement = true;
+            this.#textSnapshot.selectedElementUid = this.resolveCdpElementId(data?.cdpBackendNodeId);
+        }
     }
     getTextSnapshot() {
         return this.#textSnapshot;
@@ -305,4 +471,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();
+        let locator = this.#locatorClass.race(frames.flatMap(frame => [
+            frame.locator(`aria/${text}`),
+            frame.locator(`text/${text}`),
+        ]));
+        if (timeout) {
+            locator = 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(await this.browser.pages());
+    }
 }