chrome-devtools-mcp 0.12.1 → 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
 {
@@ -91,10 +91,10 @@ Chrome DevTools MCP will not start the browser instance automatically using this
 
 <details>
   <summary>Claude Code</summary>
-    Use the Claude Code CLI to add the Chrome DevTools MCP server (<a href="https://docs.anthropic.com/en/docs/claude-code/mcp">guide</a>):
+    Use the Claude Code CLI to add the Chrome DevTools MCP server (<a href="https://code.claude.com/docs/en/mcp">guide</a>):
 
 ```bash
-claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
+claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
 ```
 
 </details>
@@ -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:**
@@ -241,6 +244,25 @@ Or, from the IDE **Activity Bar** > `Kiro` > `MCP Servers` > `Click Open MCP Con
 
 </details>
 
+<details>
+  <summary>OpenCode</summary>
+
+Add the following configuration to your `opencode.json` file. If you don't have one, create it at `~/.config/opencode/opencode.json` (<a href="https://opencode.ai/docs/mcp-servers">guide</a>):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "chrome-devtools": {
+      "type": "local",
+      "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
 <details>
   <summary>Qoder</summary>
 
@@ -350,20 +372,20 @@ The Chrome DevTools MCP server supports the following configuration option:
 
 <!-- BEGIN AUTO GENERATED OPTIONS -->
 
-- **`--autoConnect`**
-  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.
+- **`--autoConnect`/ `--auto-connect`**
+  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`
 
-- **`--browserUrl`, `-u`**
+- **`--browserUrl`/ `--browser-url`, `-u`**
   Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.
   - **Type:** string
 
-- **`--wsEndpoint`, `-w`**
+- **`--wsEndpoint`/ `--ws-endpoint`, `-w`**
   WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.
   - **Type:** string
 
-- **`--wsHeaders`**
+- **`--wsHeaders`/ `--ws-headers`**
   Custom headers for WebSocket connection in JSON format (e.g., '{"Authorization":"Bearer token"}'). Only works with --wsEndpoint.
   - **Type:** string
 
@@ -372,7 +394,7 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `false`
 
-- **`--executablePath`, `-e`**
+- **`--executablePath`/ `--executable-path`, `-e`**
   Path to custom Chrome executable.
   - **Type:** string
 
@@ -380,7 +402,7 @@ The Chrome DevTools MCP server supports the following configuration option:
   If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.
   - **Type:** boolean
 
-- **`--userDataDir`**
+- **`--userDataDir`/ `--user-data-dir`**
   Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE
   - **Type:** string
 
@@ -389,7 +411,7 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** string
   - **Choices:** `stable`, `canary`, `beta`, `dev`
 
-- **`--logFile`**
+- **`--logFile`/ `--log-file`**
   Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.
   - **Type:** string
 
@@ -397,29 +419,33 @@ The Chrome DevTools MCP server supports the following configuration option:
   Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.
   - **Type:** string
 
-- **`--proxyServer`**
+- **`--proxyServer`/ `--proxy-server`**
   Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.
   - **Type:** string
 
-- **`--acceptInsecureCerts`**
+- **`--acceptInsecureCerts`/ `--accept-insecure-certs`**
   If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
   - **Type:** boolean
 
-- **`--chromeArg`**
+- **`--chromeArg`/ `--chrome-arg`**
   Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
   - **Type:** array
 
-- **`--categoryEmulation`**
+- **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**
+  Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
+  - **Type:** array
+
+- **`--categoryEmulation`/ `--category-emulation`**
   Set to false to exclude tools related to emulation.
   - **Type:** boolean
   - **Default:** `true`
 
-- **`--categoryPerformance`**
+- **`--categoryPerformance`/ `--category-performance`**
   Set to false to exclude tools related to performance.
   - **Type:** boolean
   - **Default:** `true`
 
-- **`--categoryNetwork`**
+- **`--categoryNetwork`/ `--category-network`**
   Set to false to exclude tools related to network.
   - **Type:** boolean
   - **Default:** `true`
@@ -499,7 +525,7 @@ In these cases, start Chrome first and let the Chrome DevTools MCP server connec
 
 **Step 1:** Set up remote debugging in Chrome
 
-In Chrome, do the following to set up remote debugging:
+In Chrome (\>= M144), do the following to set up remote debugging:
 
 1.  Navigate to `chrome://inspect/#remote-debugging` to enable remote debugging.
 2.  Follow the dialog UI to allow or disallow incoming debugging connections.
@@ -516,17 +542,13 @@ The following code snippet is an example configuration for gemini-cli:
   "mcpServers": {
     "chrome-devtools": {
       "command": "npx",
-      "args": [
-        "chrome-devtools-mcp@latest",
-        "--autoConnect",
-        "--channel=canary"
-      ]
+      "args": ["chrome-devtools-mcp@latest", "--autoConnect", "--channel=beta"]
     }
   }
 }
 ```
 
-Note: you have to specify `--channel=canary` until Chrome M144 has reached the
+Note: you have to specify `--channel=beta` until Chrome M144 has reached the
 stable channel.
 
 **Step 3:** Test your setup
@@ -537,7 +559,8 @@ Make sure your browser is running. Open gemini-cli and run the following prompt:
 Check the performance of https://developers.chrome.com
 ```
 
-Note: The <code>autoConnect</code> option requires the user to start Chrome.
+> [!NOTE]  
+> The <code>autoConnect</code> option requires the user to start Chrome. If the user has multiple active profiles, the MCP server will connect to the default profile (as determined by Chrome). The MCP server has access to all open windows for the selected profile.
 
 The Chrome DevTools MCP server will try to connect to your running Chrome
 instance. It shows a dialog asking for user permission.
@@ -611,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,15 +52,22 @@ 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;
     #nextSnapshotId = 1;
     #traceResults = [];
     #locatorClass;
     #options;
+    #uniqueBackendNodeIdToMcpId = new Map();
     constructor(browser, logger, options, locatorClass) {
         this.browser = browser;
         this.logger = logger;
@@ -86,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 */
@@ -149,25 +160,28 @@ 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);
         this.#consoleCollector.addPage(page);
         return page;
     }
-    async closePage(pageIdx) {
+    async closePage(pageId) {
         if (this.#pages.length === 1) {
             throw new Error(CLOSE_PAGE_ERROR);
         }
-        const page = this.getPageByIdx(pageIdx);
+        const page = this.getPageById(pageId);
         await page.close({ runBeforeUnload: false });
     }
     getNetworkRequestById(reqid) {
@@ -209,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;
     }
@@ -231,14 +271,16 @@ export class McpContext {
         }
         return page;
     }
-    getPageByIdx(idx) {
-        const pages = this.#pages;
-        const page = pages[idx];
+    getPageById(pageId) {
+        const page = this.#pages.find(p => this.#pageIdMap.get(p) === pageId);
         if (!page) {
             throw new Error('No page found');
         }
         return page;
     }
+    getPageId(page) {
+        return this.#pageIdMap.get(page);
+    }
     #dialogHandler = (dialog) => {
         this.#dialog = dialog;
     };
@@ -283,25 +325,34 @@ 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 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;
         }
-        const handle = await node.elementHandle();
-        if (!handle) {
-            throw new Error('No such element found in the snapshot');
+        catch (error) {
+            throw new Error(message, {
+                cause: error,
+            });
         }
-        return handle;
     }
     /**
      * Creates a snapshot of the pages.
      */
     async createPagesSnapshot() {
         const allPages = await this.browser.pages(this.#options.experimentalIncludeAllPages);
+        for (const page of allPages) {
+            if (!this.#pageIdMap.has(page)) {
+                this.#pageIdMap.set(page, this.#nextPageId++);
+            }
+        }
         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.
@@ -396,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))
                     : [],
@@ -428,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;
@@ -456,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() {
@@ -502,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);
+    }
 }