chrome-devtools-mcp 0.12.1 → 0.13.0

package/README.md

@@ -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>
@@ -241,6 +241,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 +369,20 @@ The Chrome DevTools MCP server supports the following configuration option:
 
 <!-- BEGIN AUTO GENERATED OPTIONS -->
 
-- **`--autoConnect`**
+- **`--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.
   - **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 +391,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 +399,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 +408,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 +416,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 +522,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 +539,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 +556,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.

package/build/src/McpContext.js

@@ -56,6 +56,8 @@ export class McpContext {
     #cpuThrottlingRateMap = new WeakMap();
     #geolocationMap = new WeakMap();
     #dialog;
+    #pageIdMap = new WeakMap();
+    #nextPageId = 1;
     #nextSnapshotId = 1;
     #traceResults = [];
     #locatorClass;
@@ -163,11 +165,11 @@ export class McpContext {
         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) {
@@ -231,14 +233,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;
     };
@@ -302,6 +306,11 @@ export class McpContext {
      */
     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.

package/build/src/McpResponse.js

@@ -6,7 +6,7 @@
 import { mapIssueToMessageObject } from './DevtoolsUtils.js';
 import { formatConsoleEventShort, formatConsoleEventVerbose, } from './formatters/consoleFormatter.js';
 import { getFormattedHeaderValue, getFormattedResponseBody, getFormattedRequestBody, getShortDescriptionForRequest, getStatusFromRequest, } from './formatters/networkFormatter.js';
-import { formatSnapshotNode } from './formatters/snapshotFormatter.js';
+import { SnapshotFormatter } from './formatters/SnapshotFormatter.js';
 import { DevTools } from './third_party/index.js';
 import { handleDialog } from './tools/pages.js';
 import { paginate } from './utils/pagination.js';
@@ -20,9 +20,13 @@ export class McpResponse {
     #networkRequestsOptions;
     #consoleDataOptions;
     #devToolsData;
+    #tabId;
     attachDevToolsData(data) {
         this.#devToolsData = data;
     }
+    setTabId(tabId) {
+        this.#tabId = tabId;
+    }
     setIncludePages(value) {
         this.#includePages = value;
     }
@@ -112,17 +116,18 @@ export class McpResponse {
         if (this.#includePages) {
             await context.createPagesSnapshot();
         }
-        let formattedSnapshot;
+        let snapshot;
         if (this.#snapshotParams) {
             await context.createTextSnapshot(this.#snapshotParams.verbose, this.#devToolsData);
-            const snapshot = context.getTextSnapshot();
-            if (snapshot) {
+            const textSnapshot = context.getTextSnapshot();
+            if (textSnapshot) {
+                const formatter = new SnapshotFormatter(textSnapshot);
                 if (this.#snapshotParams.filePath) {
-                    await context.saveFile(new TextEncoder().encode(formatSnapshotNode(snapshot.root, snapshot)), this.#snapshotParams.filePath);
-                    formattedSnapshot = `Saved snapshot to ${this.#snapshotParams.filePath}.`;
+                    await context.saveFile(new TextEncoder().encode(formatter.toString()), this.#snapshotParams.filePath);
+                    snapshot = this.#snapshotParams.filePath;
                 }
                 else {
-                    formattedSnapshot = formatSnapshotNode(snapshot.root, snapshot);
+                    snapshot = formatter;
                 }
             }
         }
@@ -157,8 +162,9 @@ export class McpResponse {
             }
             else if (message instanceof DevTools.AggregatedIssue) {
                 const mappedIssueMessage = mapIssueToMessageObject(message);
-                if (!mappedIssueMessage)
+                if (!mappedIssueMessage) {
                     throw new Error("Can't provide detals for the msgid " + consoleMessageStableId);
+                }
                 consoleData = {
                     consoleMessageStableId,
                     ...mappedIssueMessage,
@@ -208,8 +214,9 @@ export class McpResponse {
                 }
                 if (item instanceof DevTools.AggregatedIssue) {
                     const mappedIssueMessage = mapIssueToMessageObject(item);
-                    if (!mappedIssueMessage)
+                    if (!mappedIssueMessage) {
                         return null;
+                    }
                     return {
                         consoleMessageStableId,
                         ...mappedIssueMessage,
@@ -227,7 +234,7 @@ export class McpResponse {
             bodies,
             consoleData,
             consoleListData,
-            formattedSnapshot,
+            snapshot,
         });
     }
     format(toolName, context, data) {
@@ -257,16 +264,25 @@ Call ${handleDialog.name} to handle it before continuing.`);
         }
         if (this.#includePages) {
             const parts = [`## Pages`];
-            let idx = 0;
             for (const page of context.getPages()) {
-                parts.push(`${idx}: ${page.url()}${context.isPageSelected(page) ? ' [selected]' : ''}`);
-                idx++;
+                parts.push(`${context.getPageId(page)}: ${page.url()}${context.isPageSelected(page) ? ' [selected]' : ''}`);
             }
             response.push(...parts);
         }
-        if (data.formattedSnapshot) {
-            response.push('## Latest page snapshot');
-            response.push(data.formattedSnapshot);
+        const structuredContent = {};
+        if (this.#tabId) {
+            structuredContent.tabId = this.#tabId;
+        }
+        if (data.snapshot) {
+            if (typeof data.snapshot === 'string') {
+                response.push(`Saved snapshot to ${data.snapshot}.`);
+                structuredContent.snapshotFilePath = data.snapshot;
+            }
+            else {
+                response.push('## Latest page snapshot');
+                response.push(data.snapshot.toString());
+                structuredContent.snapshot = data.snapshot.toJSON();
+            }
         }
         response.push(...this.#formatNetworkRequestData(context, data.bodies));
         response.push(...this.#formatConsoleData(context, data.consoleData));
@@ -315,7 +331,10 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 ...imageData,
             };
         });
-        return [text, ...images];
+        return {
+            content: [text, ...images],
+            structuredContent,
+        };
     }
     #dataWithPagination(data, pagination) {
         const response = [];

package/build/src/browser.js

@@ -116,9 +116,10 @@ export async function launch(options) {
         });
     }
     const args = [
-        ...(options.args ?? []),
+        ...(options.chromeArgs ?? []),
         '--hide-crash-restore-bubble',
     ];
+    const ignoreDefaultArgs = options.ignoreDefaultChromeArgs ?? false;
     if (headless) {
         args.push('--screen-info={3840x2160}');
     }
@@ -142,6 +143,7 @@ export async function launch(options) {
             pipe: true,
             headless,
             args,
+            ignoreDefaultArgs: ignoreDefaultArgs,
             acceptInsecureCerts: options.acceptInsecureCerts,
             handleDevToolsAsPage: true,
         });
@@ -153,7 +155,6 @@ export async function launch(options) {
         }
         if (options.viewport) {
             const [page] = await browser.pages();
-            // @ts-expect-error internal API for now.
             await page?.resize({
                 contentWidth: options.viewport.width,
                 contentHeight: options.viewport.height,

package/build/src/cli.js

@@ -139,15 +139,34 @@ export const cliOptions = {
         describe: 'Whether to enable automation over DevTools targets',
         hidden: true,
     },
+    experimentalVision: {
+        type: 'boolean',
+        describe: 'Whether to enable vision tools',
+        hidden: true,
+    },
+    experimentalStructuredContent: {
+        type: 'boolean',
+        describe: 'Whether to output structured formatted content.',
+        hidden: true,
+    },
     experimentalIncludeAllPages: {
         type: 'boolean',
         describe: 'Whether to include all kinds of pages such as webviews or background pages as pages.',
         hidden: true,
     },
+    experimentalInteropTools: {
+        type: 'boolean',
+        describe: 'Whether to enable interoperability tools',
+        hidden: true,
+    },
     chromeArg: {
         type: 'array',
         describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
     },
+    ignoreDefaultChromeArg: {
+        type: 'array',
+        describe: 'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
+    },
     categoryEmulation: {
         type: 'boolean',
         default: true,
@@ -163,6 +182,13 @@ export const cliOptions = {
         default: true,
         describe: 'Set to false to exclude tools related to network.',
     },
+    usageStatistics: {
+        type: 'boolean',
+        // Marked as `false` until the feature is ready to be enabled by default.
+        default: false,
+        hidden: true,
+        describe: 'Set to false to opt-out of usage statistics collection.',
+    },
 };
 export function parseArguments(version, argv = process.argv) {
     const yargsInstance = yargs(hideBin(argv))
@@ -206,6 +232,10 @@ export function parseArguments(version, argv = process.argv) {
             `$0 --chrome-arg='--no-sandbox' --chrome-arg='--disable-setuid-sandbox'`,
             'Launch Chrome without sandboxes. Use with caution.',
         ],
+        [
+            `$0 --ignore-default-chrome-arg='--disable-extensions'`,
+            'Disable the default arguments provided by Puppeteer. Use with caution.',
+        ],
         ['$0 --no-category-emulation', 'Disable tools in the emulation category'],
         [
             '$0 --no-category-performance',

package/build/src/formatters/SnapshotFormatter.js

@@ -0,0 +1,128 @@
+export class SnapshotFormatter {
+    #snapshot;
+    constructor(snapshot) {
+        this.#snapshot = snapshot;
+    }
+    toString() {
+        const chunks = [];
+        const root = this.#snapshot.root;
+        // Top-level content of the snapshot.
+        if (this.#snapshot.verbose &&
+            this.#snapshot.hasSelectedElement &&
+            !this.#snapshot.selectedElementUid) {
+            chunks.push(`Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
+Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
+        }
+        chunks.push(this.#formatNode(root, 0));
+        return chunks.join('');
+    }
+    toJSON() {
+        return this.#nodeToJSON(this.#snapshot.root);
+    }
+    #formatNode(node, depth = 0) {
+        const chunks = [];
+        const attributes = this.#getAttributes(node);
+        const line = ' '.repeat(depth * 2) +
+            attributes.join(' ') +
+            (node.id === this.#snapshot.selectedElementUid
+                ? ' [selected in the DevTools Elements panel]'
+                : '') +
+            '\n';
+        chunks.push(line);
+        for (const child of node.children) {
+            chunks.push(this.#formatNode(child, depth + 1));
+        }
+        return chunks.join('');
+    }
+    #nodeToJSON(node) {
+        const rawAttrs = this.#getAttributesMap(node);
+        const children = node.children.map(child => this.#nodeToJSON(child));
+        const result = structuredClone(rawAttrs);
+        if (children.length > 0) {
+            result.children = children;
+        }
+        return result;
+    }
+    #getAttributes(serializedAXNodeRoot) {
+        const attributes = [`uid=${serializedAXNodeRoot.id}`];
+        if (serializedAXNodeRoot.role) {
+            attributes.push(serializedAXNodeRoot.role === 'none'
+                ? 'ignored'
+                : serializedAXNodeRoot.role);
+        }
+        if (serializedAXNodeRoot.name) {
+            attributes.push(`"${serializedAXNodeRoot.name}"`);
+        }
+        const simpleAttrs = this.#getAttributesMap(serializedAXNodeRoot, 
+        /* excludeSpecial */ true);
+        for (const attr of Object.keys(serializedAXNodeRoot).sort()) {
+            if (excludedAttributes.has(attr)) {
+                continue;
+            }
+            const mapped = booleanPropertyMap[attr];
+            if (mapped && simpleAttrs[mapped]) {
+                attributes.push(mapped);
+            }
+            const val = simpleAttrs[attr];
+            if (val === true) {
+                attributes.push(attr);
+            }
+            else if (typeof val === 'string' || typeof val === 'number') {
+                attributes.push(`${attr}="${val}"`);
+            }
+        }
+        return attributes;
+    }
+    #getAttributesMap(node, excludeSpecial = false) {
+        const result = {};
+        if (!excludeSpecial) {
+            result.id = node.id;
+            if (node.role) {
+                result.role = node.role;
+            }
+            if (node.name) {
+                result.name = node.name;
+            }
+        }
+        // Re-implementing the exact logic from original function for #getAttributes to be safe:
+        return {
+            ...result,
+            ...this.#extractedAttributes(node),
+        };
+    }
+    #extractedAttributes(node) {
+        const result = {};
+        for (const attr of Object.keys(node).sort()) {
+            if (excludedAttributes.has(attr)) {
+                continue;
+            }
+            const value = node[attr];
+            if (typeof value === 'boolean') {
+                if (booleanPropertyMap[attr]) {
+                    result[booleanPropertyMap[attr]] = true;
+                }
+                if (value) {
+                    result[attr] = true;
+                }
+            }
+            else if (typeof value === 'string' || typeof value === 'number') {
+                result[attr] = value;
+            }
+        }
+        return result;
+    }
+}
+const booleanPropertyMap = {
+    disabled: 'disableable',
+    expanded: 'expandable',
+    focused: 'focusable',
+    selected: 'selectable',
+};
+const excludedAttributes = new Set([
+    'id',
+    'role',
+    'name',
+    'elementHandle',
+    'children',
+    'backendNodeId',
+]);

package/build/src/formatters/consoleFormatter.js

@@ -25,6 +25,7 @@ export function formatConsoleEventVerbose(msg, context) {
         `ID: ${msg.consoleMessageStableId}`,
         `Message: ${msg.type}> ${aggregatedIssue ? formatIssue(aggregatedIssue, msg.description, context) : msg.message}`,
         aggregatedIssue ? undefined : formatArgs(msg),
+        formatStackTrace(msg.stackTrace),
     ].filter(line => !!line);
     return result.join('\n');
 }
@@ -49,8 +50,9 @@ export function formatIssue(issue, description, context) {
     if (processedMarkdown?.startsWith('# ')) {
         processedMarkdown = processedMarkdown.substring(2).trimStart();
     }
-    if (processedMarkdown)
+    if (processedMarkdown) {
         result.push(processedMarkdown);
+    }
     const links = issue.getDescription()?.links;
     if (links && links.length > 0) {
         result.push('Learn more:');
@@ -62,8 +64,9 @@ export function formatIssue(issue, description, context) {
     const affectedResources = [];
     for (const singleIssue of issues) {
         const details = singleIssue.details();
-        if (!details)
+        if (!details) {
             continue;
+        }
         // We send the remaining details as untyped JSON because the DevTools
         // frontend code is currently not re-usable.
         // eslint-disable-next-line
@@ -106,16 +109,48 @@ export function formatIssue(issue, description, context) {
     }
     result.push(...affectedResources.map(item => {
         const details = [];
-        if (item.uid)
+        if (item.uid) {
             details.push(`uid=${item.uid}`);
+        }
         if (item.request) {
             details.push((typeof item.request === 'number' ? `reqid=` : 'url=') + item.request);
         }
-        if (item.data)
+        if (item.data) {
             details.push(`data=${JSON.stringify(item.data)}`);
+        }
         return details.join(' ');
     }));
-    if (result.length === 0)
+    if (result.length === 0) {
         return 'No affected resources found';
+    }
     return result.join('\n');
 }
+function formatStackTrace(stackTrace) {
+    if (!stackTrace) {
+        return '';
+    }
+    return [
+        '### Stack trace',
+        formatFragment(stackTrace.syncFragment),
+        ...stackTrace.asyncFragments.map(formatAsyncFragment),
+    ].join('\n');
+}
+function formatFragment(fragment) {
+    return fragment.frames.map(formatFrame).join('\n');
+}
+function formatAsyncFragment(fragment) {
+    const separatorLineLength = 40;
+    const prefix = `--- ${fragment.description || 'async'} `;
+    const separator = prefix + '-'.repeat(separatorLineLength - prefix.length);
+    return separator + '\n' + formatFragment(fragment);
+}
+function formatFrame(frame) {
+    let result = `at ${frame.name ?? '<anonymous>'}`;
+    if (frame.uiSourceCode) {
+        result += ` (${frame.uiSourceCode.displayName()}:${frame.line}:${frame.column})`;
+    }
+    else if (frame.url) {
+        result += ` (${frame.url}:${frame.line}:${frame.column})`;
+    }
+    return result;
+}