chrome-devtools-mcp 0.13.0 → 0.14.0

package/README.md

@@ -66,7 +66,7 @@ amp mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
 <details>
   <summary>Antigravity</summary>
 
-To use the Chrome DevTools MCP server follow the instructions from <a href="https://antigravity.google/docs/mcp">Antigravity's docs<a/> to install a custom MCP server. Add the following config to the MCP servers config:
+To use the Chrome DevTools MCP server follow the instructions from <a href="https://antigravity.google/docs/mcp">Antigravity's docs</a> to install a custom MCP server. Add the following config to the MCP servers config:
 
 ```bash
 {
@@ -205,7 +205,10 @@ Install the Chrome DevTools MCP server using the Gemini CLI.
 **Project wide:**
 
 ```bash
+# Either MCP only:
 gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest
+# Or as a Gemini extension (MCP+Skills):
+gemini extensions install --auto-update https://github.com/ChromeDevTools/chrome-devtools-mcp
 ```
 
 **Globally:**
@@ -370,7 +373,7 @@ The Chrome DevTools MCP server supports the following configuration option:
 <!-- BEGIN AUTO GENERATED OPTIONS -->
 
 - **`--autoConnect`/ `--auto-connect`**
-  If specified, automatically connects to a browser (Chrome 145+) running in the user data directory identified by the channel param. Requires remote debugging being enabled in Chrome here: chrome://inspect/#remote-debugging.
+  If specified, automatically connects to a browser (Chrome 144+) running in the user data directory identified by the channel param. Requires the remoted debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.
   - **Type:** boolean
   - **Default:** `false`
 
@@ -631,6 +634,10 @@ If you hit VM-to-host port forwarding issues, see the “Remote debugging betwee
 
 For more details on remote debugging, see the [Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/remote-debugging/).
 
+### Debugging Chrome on Android
+
+Please consult [these instructions](./docs/debugging-android.md).
+
 ## Known limitations
 
 ### Operating system sandboxes

package/build/src/DevtoolsUtils.js

@@ -4,8 +4,6 @@
  * 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) {
@@ -64,46 +62,6 @@ export class FakeIssuesManager extends DevTools.Common.ObjectWrapper
         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({
@@ -115,6 +73,11 @@ DevTools.I18n.DevToolsLocale.DevToolsLocale.instance({
     },
 });
 DevTools.I18n.i18n.registerLocaleDataForTest('en-US', {});
+DevTools.Formatter.FormatterWorkerPool.FormatterWorkerPool.instance({
+    forceNew: true,
+    entrypointURL: import.meta
+        .resolve('./third_party/devtools-formatter-worker.js'),
+});
 export class UniverseManager {
     #browser;
     #createUniverseFor;
@@ -206,3 +169,57 @@ const SKIP_ALL_PAUSES = {
         // Do nothing.
     },
 };
+export async function createStackTraceForConsoleMessage(devTools, consoleMessage) {
+    const message = consoleMessage;
+    const rawStackTrace = message._rawStackTrace();
+    if (!rawStackTrace) {
+        return undefined;
+    }
+    const targetManager = devTools.universe.context.get(DevTools.TargetManager);
+    const messageTargetId = message._targetId();
+    const target = messageTargetId
+        ? targetManager.targetById(messageTargetId) || devTools.target
+        : devTools.target;
+    const model = target.model(DevTools.DebuggerModel);
+    // DevTools doesn't wait for source maps to attach before building a stack trace, rather it'll send
+    // an update event once a source map was attached and the stack trace retranslated. This doesn't
+    // work in the MCP case, so we'll collect all script IDs upfront and wait for any pending source map
+    // loads before creating the stack trace. We might also have to wait for Debugger.ScriptParsed events if
+    // the stack trace is created particularly early.
+    const scriptIds = new Set();
+    for (const frame of rawStackTrace.callFrames) {
+        scriptIds.add(frame.scriptId);
+    }
+    for (let asyncStack = rawStackTrace.parent; asyncStack; asyncStack = asyncStack.parent) {
+        for (const frame of asyncStack.callFrames) {
+            scriptIds.add(frame.scriptId);
+        }
+    }
+    const signal = AbortSignal.timeout(1_000);
+    await Promise.all([...scriptIds].map(id => waitForScript(model, id, signal)
+        .then(script => model.sourceMapManager().sourceMapForClientPromise(script))
+        .catch()));
+    const binding = devTools.universe.context.get(DevTools.DebuggerWorkspaceBinding);
+    // DevTools uses branded types for ScriptId and others. Casting the puppeteer protocol type to the DevTools protocol type is safe.
+    return binding.createStackTraceFromProtocolRuntime(rawStackTrace, target);
+}
+// Waits indefinitely for the script so pair it with Promise.race.
+async function waitForScript(model, scriptId, signal) {
+    while (true) {
+        if (signal.aborted) {
+            throw signal.reason;
+        }
+        const script = model.scriptForId(scriptId);
+        if (script) {
+            return script;
+        }
+        await new Promise((resolve, reject) => {
+            signal.addEventListener('abort', () => reject(signal.reason), {
+                once: true,
+            });
+            void model
+                .once('ParsedScriptSource')
+                .then(resolve);
+        });
+    }
+}

package/build/src/McpContext.js

@@ -6,12 +6,13 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { extractUrlLikeFromDevToolsTitle, urlsEqual } from './DevtoolsUtils.js';
+import { extractUrlLikeFromDevToolsTitle, UniverseManager, 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';
+import { ExtensionRegistry, } from './utils/ExtensionRegistry.js';
 import { WaitForHelper } from './WaitForHelper.js';
 const DEFAULT_TIMEOUT = 5_000;
 const NAVIGATION_TIMEOUT = 10_000;
@@ -51,10 +52,14 @@ export class McpContext {
     #textSnapshot = null;
     #networkCollector;
     #consoleCollector;
+    #devtoolsUniverseManager;
+    #extensionRegistry = new ExtensionRegistry();
     #isRunningTrace = false;
     #networkConditionsMap = new WeakMap();
     #cpuThrottlingRateMap = new WeakMap();
     #geolocationMap = new WeakMap();
+    #viewportMap = new WeakMap();
+    #userAgentMap = new WeakMap();
     #dialog;
     #pageIdMap = new WeakMap();
     #nextPageId = 1;
@@ -62,6 +67,7 @@ export class McpContext {
     #traceResults = [];
     #locatorClass;
     #options;
+    #uniqueBackendNodeIdToMcpId = new Map();
     constructor(browser, logger, options, locatorClass) {
         this.browser = browser;
         this.logger = logger;
@@ -88,15 +94,18 @@ export class McpContext {
                 },
             };
         });
+        this.#devtoolsUniverseManager = new UniverseManager(this.browser);
     }
     async #init() {
         const pages = await this.createPagesSnapshot();
         await this.#networkCollector.init(pages);
         await this.#consoleCollector.init(pages);
+        await this.#devtoolsUniverseManager.init(pages);
     }
     dispose() {
         this.#networkCollector.dispose();
         this.#consoleCollector.dispose();
+        this.#devtoolsUniverseManager.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 */
@@ -151,14 +160,17 @@ export class McpContext {
         const page = this.getSelectedPage();
         return this.#consoleCollector.getData(page, includePreservedMessages);
     }
+    getDevToolsUniverse() {
+        return this.#devtoolsUniverseManager.get(this.getSelectedPage());
+    }
     getConsoleMessageStableId(message) {
         return this.#consoleCollector.getIdForResource(message);
     }
     getConsoleMessageById(id) {
         return this.#consoleCollector.getById(this.getSelectedPage(), id);
     }
-    async newPage() {
-        const page = await this.browser.newPage();
+    async newPage(background) {
+        const page = await this.browser.newPage({ background });
         await this.createPagesSnapshot();
         this.selectPage(page);
         this.#networkCollector.addPage(page);
@@ -211,6 +223,32 @@ export class McpContext {
         const page = this.getSelectedPage();
         return this.#geolocationMap.get(page) ?? null;
     }
+    setViewport(viewport) {
+        const page = this.getSelectedPage();
+        if (viewport === null) {
+            this.#viewportMap.delete(page);
+        }
+        else {
+            this.#viewportMap.set(page, viewport);
+        }
+    }
+    getViewport() {
+        const page = this.getSelectedPage();
+        return this.#viewportMap.get(page) ?? null;
+    }
+    setUserAgent(userAgent) {
+        const page = this.getSelectedPage();
+        if (userAgent === null) {
+            this.#userAgentMap.delete(page);
+        }
+        else {
+            this.#userAgentMap.set(page, userAgent);
+        }
+    }
+    getUserAgent() {
+        const page = this.getSelectedPage();
+        return this.#userAgentMap.get(page) ?? null;
+    }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
     }
@@ -287,19 +325,23 @@ export class McpContext {
         if (!this.#textSnapshot?.idToNode.size) {
             throw new Error(`No snapshot found. Use ${takeSnapshot.name} to capture one.`);
         }
-        const [snapshotId] = uid.split('_');
-        if (this.#textSnapshot.snapshotId !== snapshotId) {
-            throw new Error('This uid is coming from a stale snapshot. Call take_snapshot to get a fresh snapshot.');
-        }
         const node = this.#textSnapshot?.idToNode.get(uid);
         if (!node) {
-            throw new Error('No such element found in the snapshot');
+            throw new Error('No such element found in the snapshot.');
         }
-        const handle = await node.elementHandle();
-        if (!handle) {
-            throw new Error('No such element found in the snapshot');
+        const message = `Element with uid ${uid} no longer exists on the page.`;
+        try {
+            const handle = await node.elementHandle();
+            if (!handle) {
+                throw new Error(message);
+            }
+            return handle;
+        }
+        catch (error) {
+            throw new Error(message, {
+                cause: error,
+            });
         }
-        return handle;
     }
     /**
      * Creates a snapshot of the pages.
@@ -405,10 +447,24 @@ export class McpContext {
         // will be used for the tree serialization and mapping ids back to nodes.
         let idCounter = 0;
         const idToNode = new Map();
+        const seenUniqueIds = new Set();
         const assignIds = (node) => {
+            let id = '';
+            // @ts-expect-error untyped loaderId & backendNodeId.
+            const uniqueBackendId = `${node.loaderId}_${node.backendNodeId}`;
+            if (this.#uniqueBackendNodeIdToMcpId.has(uniqueBackendId)) {
+                // Re-use MCP exposed ID if the uniqueId is the same.
+                id = this.#uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+            }
+            else {
+                // Only generate a new ID if we have not seen the node before.
+                id = `${snapshotId}_${idCounter++}`;
+                this.#uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+            }
+            seenUniqueIds.add(uniqueBackendId);
             const nodeWithId = {
                 ...node,
-                id: `${snapshotId}_${idCounter++}`,
+                id,
                 children: node.children
                     ? node.children.map(child => assignIds(child))
                     : [],
@@ -437,6 +493,12 @@ export class McpContext {
             this.#textSnapshot.hasSelectedElement = true;
             this.#textSnapshot.selectedElementUid = this.resolveCdpElementId(data?.cdpBackendNodeId);
         }
+        // Clean up unique IDs that we did not see anymore.
+        for (const key of this.#uniqueBackendNodeIdToMcpId.keys()) {
+            if (!seenUniqueIds.has(key)) {
+                this.#uniqueBackendNodeIdToMcpId.delete(key);
+            }
+        }
     }
     getTextSnapshot() {
         return this.#textSnapshot;
@@ -465,6 +527,8 @@ export class McpContext {
         }
     }
     storeTraceRecording(result) {
+        // Clear the trace results because we only consume the latest trace currently.
+        this.#traceResults = [];
         this.#traceResults.push(result);
     }
     recordedTraces() {
@@ -511,4 +575,19 @@ export class McpContext {
         });
         await this.#networkCollector.init(await this.browser.pages());
     }
+    async installExtension(extensionPath) {
+        const id = await this.browser.installExtension(extensionPath);
+        await this.#extensionRegistry.registerExtension(id, extensionPath);
+        return id;
+    }
+    async uninstallExtension(id) {
+        await this.browser.uninstallExtension(id);
+        this.#extensionRegistry.remove(id);
+    }
+    listExtensions() {
+        return this.#extensionRegistry.list();
+    }
+    getExtension(id) {
+        return this.#extensionRegistry.getById(id);
+    }
 }