chrome-devtools-mcp 0.13.0 → 0.15.0

package/README.md

@@ -27,6 +27,20 @@ allowing them to inspect, debug, and modify any data in the browser or DevTools.
 Avoid sharing sensitive or personal information that you don't want to share with
 MCP clients.
 
+## **Usage statistics**
+
+Google collects usage statistics (such as tool invocation success rates, latency, and environment information) to improve the reliability and performance of Chrome DevTools MCP.
+
+Data collection is **enabled by default**. You can opt-out by passing the `--no-usage-statistics` flag when starting the server:
+
+```json
+"args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]
+```
+
+Google handles this data in accordance with the [Google Privacy Policy](https://policies.google.com/privacy).
+
+Google's collection of usage statistics for Chrome DevTools MCP is independent from the Chrome browser's usage statistics. Opting out of Chrome metrics does not automatically opt you out of this tool, and vice-versa.
+
 ## Requirements
 
 - [Node.js](https://nodejs.org/) v20.19 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.
@@ -66,7 +80,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 +219,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 +387,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`
 
@@ -447,6 +464,11 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `true`
 
+- **`--usageStatistics`/ `--usage-statistics`**
+  Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics.
+  - **Type:** boolean
+  - **Default:** `true`
+
 <!-- END AUTO GENERATED OPTIONS -->
 
 Pass them via the `args` property in the JSON configuration. For example:
@@ -631,6 +653,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,15 @@ 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();
+    #colorSchemeMap = new WeakMap();
     #dialog;
     #pageIdMap = new WeakMap();
     #nextPageId = 1;
@@ -62,6 +68,7 @@ export class McpContext {
     #traceResults = [];
     #locatorClass;
     #options;
+    #uniqueBackendNodeIdToMcpId = new Map();
     constructor(browser, logger, options, locatorClass) {
         this.browser = browser;
         this.logger = logger;
@@ -88,15 +95,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 +161,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 +224,45 @@ 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;
+    }
+    setColorScheme(scheme) {
+        const page = this.getSelectedPage();
+        if (scheme === null) {
+            this.#colorSchemeMap.delete(page);
+        }
+        else {
+            this.#colorSchemeMap.set(page, scheme);
+        }
+    }
+    getColorScheme() {
+        const page = this.getSelectedPage();
+        return this.#colorSchemeMap.get(page) ?? null;
+    }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
     }
@@ -287,19 +339,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 +461,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 +507,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 +541,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 +589,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);
+    }
 }