@mcp-b/chrome-devtools-mcp 1.7.0 → 1.7.1

package/README.md

@@ -8,7 +8,7 @@
 [![27 Tools](https://img.shields.io/badge/MCP_Tools-27-green?style=flat-square)](./docs/tool-reference.md)
 [![Chrome](https://img.shields.io/badge/Chrome-DevTools-4285F4?style=flat-square&logo=googlechrome)](https://developer.chrome.com/docs/devtools/)
 
-📖 **[WebMCP Documentation](https://docs.mcp-b.ai)** | 🚀 **[Quick Start](https://docs.mcp-b.ai/quickstart)** | 🔌 **[Connecting Agents](https://docs.mcp-b.ai/connecting-agents)** | 🎯 **[Chrome DevTools Quickstart](https://github.com/WebMCP-org/chrome-devtools-quickstart)**
+**[WebMCP Documentation](https://docs.mcp-b.ai)** | **[Quick Start](https://docs.mcp-b.ai/quickstart)** | **[Connecting Agents](https://docs.mcp-b.ai/connecting-agents)** | **[Chrome DevTools Quickstart](https://github.com/WebMCP-org/chrome-devtools-quickstart)**
 
 **@mcp-b/chrome-devtools-mcp** lets AI coding agents like Claude, Gemini, Cursor, and Copilot control and inspect a live Chrome browser via the Model Context Protocol (MCP). Get performance insights, debug network requests, take screenshots, and interact with website-specific MCP tools through WebMCP integration.
 
@@ -48,13 +48,13 @@ This fork adds **WebMCP integration** - the ability to call MCP tools that are r
 
 | Feature | Chrome DevTools MCP | @mcp-b/chrome-devtools-mcp |
 |---------|--------------------|-----------------------------|
-| Browser automation | ✅ | ✅ |
-| Performance analysis | ✅ | ✅ |
-| Network inspection | ✅ | ✅ |
-| Screenshot/snapshot | ✅ | ✅ |
-| **Call website MCP tools** | ❌ | ✅ |
-| **List website MCP tools** | ❌ | ✅ |
-| **AI-driven tool development** | ❌ | ✅ |
+| Browser automation | Yes | Yes |
+| Performance analysis | Yes | Yes |
+| Network inspection | Yes | Yes |
+| Screenshot/snapshot | Yes | Yes |
+| **Call website MCP tools** | No | Yes |
+| **List website MCP tools** | No | Yes |
+| **AI-driven tool development** | No | Yes |
 
 The key addition is automatic WebMCP tool discovery and registration. When you visit a page with [@mcp-b/global](https://www.npmjs.com/package/@mcp-b/global), its tools are automatically registered as first-class MCP tools that your AI agent can call directly.
 
@@ -366,6 +366,30 @@ The same way `@mcp-b/chrome-devtools-mcp` can be configured for JetBrains Junie
 
 </details>
 
+<details>
+  <summary>Katalon Studio</summary>
+
+The Chrome DevTools MCP server can be used with <a href="https://docs.katalon.com/katalon-studio/studioassist/mcp-servers/setting-up-chrome-devtools-mcp-server-for-studioassist">Katalon StudioAssist</a> via an MCP proxy.
+
+**Step 1:** Install the MCP proxy by following the <a href="https://docs.katalon.com/katalon-studio/studioassist/mcp-servers/setting-up-mcp-proxy-for-stdio-mcp-servers">MCP proxy setup guide</a>.
+
+**Step 2:** Start the Chrome DevTools MCP server with the proxy:
+
+```bash
+mcp-proxy --transport streamablehttp --port 8080 -- npx -y @mcp-b/chrome-devtools-mcp@latest
+```
+
+**Note:** You may need to pick another port if 8080 is already in use.
+
+**Step 3:** In Katalon Studio, add the server to StudioAssist with the following settings:
+
+- **Connection URL:** `http://127.0.0.1:8080/mcp`
+- **Transport type:** `HTTP`
+
+Once connected, the Chrome DevTools MCP tools will be available in StudioAssist.
+
+</details>
+
 <details>
   <summary>Kiro</summary>
 
@@ -375,6 +399,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", "@mcp-b/chrome-devtools-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
 <details>
   <summary>Qoder</summary>
 
@@ -546,6 +589,11 @@ The Chrome DevTools MCP server supports the following configuration option:
 
 <!-- BEGIN AUTO GENERATED OPTIONS -->
 
+- **`--autoConnect`**
+  If specified, automatically connects to a browser (Chrome 144+) running in the user data directory identified by the channel param. Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.
+  - **Type:** boolean
+  - **Default:** `true`
+
 - **`--browserUrl`, `-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
@@ -600,6 +648,10 @@ The Chrome DevTools MCP server supports the following configuration option:
   Additional arguments for Chrome. Only applies when Chrome is launched by `@mcp-b/chrome-devtools-mcp`.
   - **Type:** array
 
+- **`--ignoreDefaultChromeArg`**
+  Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by `@mcp-b/chrome-devtools-mcp`.
+  - **Type:** array
+
 - **`--categoryEmulation`**
   Set to false to exclude tools related to emulation.
   - **Type:** boolean
@@ -683,9 +735,65 @@ the browser is closed.
 
 ### Connecting to a running Chrome instance
 
-You can connect to a running Chrome instance by using the `--browser-url` option. This is useful if you want to use your existing Chrome profile or if you are running the MCP server in a sandboxed environment that does not allow starting a new Chrome instance.
+By default, the Chrome DevTools MCP server will start a new Chrome instance with a dedicated profile. This might not be ideal in all situations:
 
-Here is a step-by-step guide on how to connect to a running Chrome Stable instance:
+- If you would like to maintain the same application state when alternating between manual site testing and agent-driven testing.
+- When the MCP needs to sign into a website. Some accounts may prevent sign-in when the browser is controlled via WebDriver (the default launch mechanism for the Chrome DevTools MCP server).
+- If you're running your LLM inside a sandboxed environment, but you would like to connect to a Chrome instance that runs outside the sandbox.
+
+In these cases, start Chrome first and let the Chrome DevTools MCP server connect to it. There are two ways to do so:
+
+- **Automatic connection (available in Chrome 144+)**: best for sharing state between manual and agent-driven testing.
+- **Manual connection via remote debugging port**: best when running inside a sandboxed environment.
+
+#### Automatically connecting to a running Chrome instance
+
+**Step 1:** Set up remote debugging in Chrome
+
+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.
+
+**Step 2:** Configure the MCP server to automatically connect
+
+To connect the `@mcp-b/chrome-devtools-mcp` server to the running Chrome instance, use
+the `--autoConnect` command line argument (enabled by default):
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["@mcp-b/chrome-devtools-mcp@latest", "--autoConnect"]
+    }
+  }
+}
+```
+
+**Step 3:** Test your setup
+
+Make sure your browser is running. Open your MCP client and run the following prompt:
+
+```
+Check the performance of https://developers.chrome.com
+```
+
+> [!NOTE]
+> The `autoConnect` 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.
+
+Clicking **Allow** results in the Chrome DevTools MCP server opening
+[developers.chrome.com](http://developers.chrome.com) and taking a performance
+trace.
+
+#### Manual connection using port forwarding
+
+You can connect to a running Chrome instance by using the `--browser-url` option. This is useful if you are running the MCP server in a sandboxed environment that does not allow starting a new Chrome instance.
+
+Here is a step-by-step guide:
 
 **Step 1: Configure the MCP client**
 
@@ -748,6 +856,8 @@ For more details on remote debugging, see the [Chrome DevTools documentation](ht
 
 ## Known limitations
 
+See [Troubleshooting](./docs/troubleshooting.md) for the full list.
+
 ### Operating system sandboxes
 
 Some MCP clients allow sandboxing the MCP server using macOS Seatbelt or Linux

package/build/src/McpContext.js

@@ -160,7 +160,7 @@ export class McpContext {
                     // Skip chrome:// and devtools:// pages
                     const url = page.url();
                     if (url.startsWith('chrome://') ||
-                        url.startsWith('chrome-extension://') ||
+                        (!this.#options.includeExtensionPages && url.startsWith('chrome-extension://')) ||
                         url.startsWith('devtools://') ||
                         url === 'about:blank') {
                         continue;
@@ -302,7 +302,7 @@ export class McpContext {
         // Skip chrome:// and devtools:// pages
         const url = page.url();
         if (url.startsWith('chrome://') ||
-            url.startsWith('chrome-extension://') ||
+            (!this.#options.includeExtensionPages && url.startsWith('chrome-extension://')) ||
             url.startsWith('devtools://')) {
             return;
         }
@@ -317,7 +317,7 @@ export class McpContext {
             // Skip internal pages
             const newUrl = page.url();
             if (newUrl.startsWith('chrome://') ||
-                newUrl.startsWith('chrome-extension://') ||
+                (!this.#options.includeExtensionPages && newUrl.startsWith('chrome-extension://')) ||
                 newUrl.startsWith('devtools://') ||
                 newUrl === 'about:blank') {
                 return;
@@ -1053,6 +1053,53 @@ export class McpContext {
             };
         }
     }
+    /**
+     * Evaluate a JavaScript expression in a Chrome extension's background context.
+     *
+     * Supports both MV3 service workers (type "service_worker") and MV2/dev-mode
+     * background pages (type "background_page"). Uses waitForTarget to handle
+     * cases where the worker hasn't been discovered yet.
+     *
+     * @param expression - JavaScript expression to evaluate.
+     * @param extensionId - Optional extension ID. If omitted, uses the first found.
+     * @returns The result of the evaluation.
+     */
+    async evaluateInExtensionWorker(expression, extensionId) {
+        const isExtensionBackground = (t) => (t.type() === 'service_worker' || t.type() === 'background_page') &&
+            t.url().startsWith('chrome-extension://') &&
+            (!extensionId || t.url().includes(extensionId));
+        // First check already-known targets
+        let target = this.browser.targets().find(isExtensionBackground);
+        // If not found, wait briefly for the target to appear (handles startup timing)
+        if (!target) {
+            try {
+                target = await this.browser.waitForTarget(isExtensionBackground, { timeout: 5000 });
+            }
+            catch {
+                throw new Error('No extension background target found. Ensure the extension is loaded in the browser. ' +
+                    'If connecting to an existing browser, verify the extension is installed and active.');
+            }
+        }
+        if (target.type() === 'service_worker') {
+            const worker = await target.worker();
+            if (!worker) {
+                throw new Error('Could not attach to service worker');
+            }
+            return worker.evaluate(expression);
+        }
+        // background_page — get a Page handle instead
+        const page = await target.page();
+        if (!page) {
+            throw new Error('Could not attach to extension background page');
+        }
+        return page.evaluate(expression);
+    }
+    async reconnectBrowser(options) {
+        if (!this.#options.onReconnect) {
+            throw new Error('Browser reconnection is not supported in this configuration');
+        }
+        return this.#options.onReconnect(options);
+    }
     /**
      * We need to ignore favicon request as they make our test flaky
      */

package/build/src/browser.js

@@ -18,10 +18,10 @@ let browser;
  *
  * @returns A filter function for Puppeteer's targetFilter option.
  */
-function makeTargetFilter() {
+function makeTargetFilter(includeExtensionPages = false) {
     const ignoredPrefixes = new Set([
         'chrome://',
-        'chrome-extension://',
+        ...(includeExtensionPages ? [] : ['chrome-extension://']),
         'chrome-untrusted://',
     ]);
     return function targetFilter(target) {
@@ -53,14 +53,18 @@ function makeTargetFilter() {
  * @throws Error if connection fails or no connection method specified.
  */
 export async function ensureBrowserConnected(options) {
-    const { channel } = options;
+    const { channel, includeExtensionPages } = options;
     if (browser?.connected) {
         return browser;
     }
     const connectOptions = {
-        targetFilter: makeTargetFilter(),
+        targetFilter: makeTargetFilter(includeExtensionPages),
         defaultViewport: null,
         handleDevToolsAsPage: true,
+        ...(includeExtensionPages && {
+            isPageTargetCallback: (target) => target.type() === 'page' ||
+                target.url().startsWith('chrome-extension://'),
+        }),
     };
     if (options.wsEndpoint) {
         connectOptions.browserWSEndpoint = options.wsEndpoint;
@@ -201,7 +205,7 @@ export async function launch(options) {
     try {
         const browser = await puppeteer.launch({
             channel: puppeteerChannel,
-            targetFilter: makeTargetFilter(),
+            targetFilter: makeTargetFilter(options.includeExtensionPages),
             executablePath,
             defaultViewport: null,
             userDataDir,
@@ -210,6 +214,11 @@ export async function launch(options) {
             args,
             acceptInsecureCerts: options.acceptInsecureCerts,
             handleDevToolsAsPage: true,
+            ...(options.includeExtensionPages && {
+                enableExtensions: true,
+                isPageTargetCallback: (target) => target.type === 'page' ||
+                    target.url?.startsWith('chrome-extension://') === true,
+            }),
         });
         if (options.logFile) {
             // FIXME: we are probably subscribing too late to catch startup logs. We
@@ -219,7 +228,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,
@@ -250,3 +258,51 @@ export async function ensureBrowserLaunched(options) {
     browser = await launch(options);
     return browser;
 }
+/**
+ * Disconnect from the current browser without killing the process.
+ * Clears the cached browser reference so future calls can connect to a new instance.
+ */
+export function disconnectBrowser() {
+    if (browser) {
+        try {
+            browser.disconnect();
+        }
+        catch {
+            // Ignore disconnect errors — browser may already be gone
+        }
+        browser = undefined;
+    }
+}
+/**
+ * Connect to a new browser instance, replacing the cached reference.
+ *
+ * @param options - Connection options (browserURL or wsEndpoint).
+ * @returns Connected browser instance.
+ */
+export async function connectToNewBrowser(options) {
+    const connectOptions = {
+        targetFilter: makeTargetFilter(options.includeExtensionPages),
+        defaultViewport: null,
+        handleDevToolsAsPage: true,
+        ...(options.includeExtensionPages && {
+            isPageTargetCallback: (target) => target.type() === 'page' ||
+                target.url().startsWith('chrome-extension://'),
+        }),
+    };
+    if (options.wsEndpoint) {
+        connectOptions.browserWSEndpoint = options.wsEndpoint;
+        if (options.wsHeaders) {
+            connectOptions.headers = options.wsHeaders;
+        }
+    }
+    else if (options.browserURL) {
+        connectOptions.browserURL = options.browserURL;
+    }
+    else {
+        throw new Error('Either browserURL or wsEndpoint must be provided');
+    }
+    logger('Connecting Puppeteer to new browser:', JSON.stringify(connectOptions));
+    browser = await puppeteer.connect(connectOptions);
+    logger('Connected to new browser');
+    return browser;
+}

package/build/src/cli.js

@@ -162,6 +162,11 @@ export const cliOptions = {
         default: true,
         describe: 'Set to false to exclude tools related to network.',
     },
+    includeExtensionPages: {
+        type: 'boolean',
+        describe: 'Include chrome-extension:// pages in page listing and tool discovery.',
+        default: false,
+    },
 };
 export function parseArguments(version, argv = process.argv) {
     const yargsInstance = yargs(hideBin(argv))
@@ -175,7 +180,7 @@ export function parseArguments(version, argv = process.argv) {
             args.browserUrl === undefined &&
             args.wsEndpoint === undefined &&
             args.executablePath === undefined) {
-            args.channel = 'dev';
+            args.channel = 'stable';
         }
         return true;
     })

package/build/src/formatters/IssueFormatter.js

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ISSUE_UTILS } from '../issue-descriptions.js';
+import { logger } from '../logger.js';
+import { DevTools } from '../third_party/index.js';
+export class IssueFormatter {
+    #issue;
+    #options;
+    constructor(issue, options) {
+        this.#issue = issue;
+        this.#options = options;
+    }
+    toString() {
+        const title = this.#getTitle();
+        const count = this.#issue.getAggregatedIssuesCount();
+        const idPart = this.#options.id !== undefined ? `msgid=${this.#options.id} ` : '';
+        return `${idPart}[issue] ${title} (count: ${count})`;
+    }
+    toStringDetailed() {
+        const result = [];
+        if (this.#options.id !== undefined) {
+            result.push(`ID: ${this.#options.id}`);
+        }
+        const bodyParts = [];
+        const description = this.#getDescription();
+        let processedMarkdown = description?.trim();
+        // Remove heading in order not to conflict with the whole console message response markdown
+        if (processedMarkdown?.startsWith('# ')) {
+            processedMarkdown = processedMarkdown.substring(2).trimStart();
+        }
+        if (processedMarkdown) {
+            bodyParts.push(processedMarkdown);
+        }
+        else {
+            bodyParts.push(this.#getTitle() ?? 'Unknown Issue');
+        }
+        const links = this.#issue.getDescription()?.links;
+        if (links && links.length > 0) {
+            bodyParts.push('Learn more:');
+            for (const link of links) {
+                bodyParts.push(`[${link.linkTitle}](${link.link})`);
+            }
+        }
+        const affectedResources = this.#getAffectedResources();
+        if (affectedResources.length) {
+            bodyParts.push('### Affected resources');
+            bodyParts.push(...affectedResources.map(item => {
+                const details = [];
+                if (item.uid) {
+                    details.push(`uid=${item.uid}`);
+                }
+                if (item.request) {
+                    details.push((typeof item.request === 'number' ? `reqid=` : 'url=') +
+                        item.request);
+                }
+                if (item.data) {
+                    details.push(`data=${JSON.stringify(item.data)}`);
+                }
+                return details.join(' ');
+            }));
+        }
+        result.push(`Message: issue> ${bodyParts.join('\n')}`);
+        return result.join('\n');
+    }
+    toJSON() {
+        return {
+            type: 'issue',
+            title: this.#getTitle(),
+            count: this.#issue.getAggregatedIssuesCount(),
+            id: this.#options.id,
+        };
+    }
+    toJSONDetailed() {
+        return {
+            id: this.#options.id,
+            type: 'issue',
+            title: this.#getTitle(),
+            description: this.#getDescription(),
+            links: this.#issue.getDescription()?.links,
+            affectedResources: this.#getAffectedResources(),
+        };
+    }
+    #getAffectedResources() {
+        const issues = this.#issue.getAllIssues();
+        const affectedResources = [];
+        for (const singleIssue of issues) {
+            const details = singleIssue.details();
+            if (!details) {
+                continue;
+            }
+            // We send the remaining details as untyped JSON because the DevTools
+            // frontend code is currently not re-usable.
+            const data = structuredClone(details);
+            let uid;
+            let request;
+            if ('violatingNodeId' in details &&
+                details.violatingNodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.violatingNodeId);
+                delete data.violatingNodeId;
+            }
+            if ('nodeId' in details &&
+                details.nodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.nodeId);
+                delete data.nodeId;
+            }
+            if ('documentNodeId' in details &&
+                details.documentNodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.documentNodeId);
+                delete data.documentNodeId;
+            }
+            if ('request' in details && details.request) {
+                request = details.request.url;
+                if (details.request.requestId && this.#options.requestIdResolver) {
+                    const resolvedId = this.#options.requestIdResolver(details.request.requestId);
+                    if (resolvedId) {
+                        request = resolvedId;
+                        const requestData = data.request;
+                        delete requestData.requestId;
+                    }
+                }
+            }
+            // These fields has no use for the MCP client (redundant or irrelevant).
+            delete data.errorType;
+            delete data.frameId;
+            affectedResources.push({
+                uid,
+                data: data,
+                request,
+            });
+        }
+        return affectedResources;
+    }
+    isValid() {
+        return this.#getTitle() !== undefined;
+    }
+    // Helper to extract title
+    #getTitle() {
+        const markdownDescription = this.#issue.getDescription();
+        const filename = markdownDescription?.file;
+        if (!filename) {
+            logger(`no description found for issue:` + this.#issue.code());
+            return undefined;
+        }
+        // We already have the description logic in #getDescription, but title extraction is separate
+        // We can reuse the logic or cache it.
+        // Ideally we should process markdown once.
+        const rawMarkdown = ISSUE_UTILS.getIssueDescription(filename);
+        if (!rawMarkdown) {
+            logger(`no markdown ${filename} found for issue:` + this.#issue.code());
+            return undefined;
+        }
+        try {
+            const processedMarkdown = DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription?.substitutions);
+            const markdownAst = DevTools.Marked.Marked.lexer(processedMarkdown);
+            const title = DevTools.MarkdownIssueDescription.findTitleFromMarkdownAst(markdownAst);
+            if (!title) {
+                logger('cannot read issue title from ' + filename);
+                return undefined;
+            }
+            return title;
+        }
+        catch {
+            logger('error parsing markdown for issue ' + this.#issue.code());
+            return undefined;
+        }
+    }
+    #getDescription() {
+        const markdownDescription = this.#issue.getDescription();
+        const filename = markdownDescription?.file;
+        if (!filename) {
+            return undefined;
+        }
+        const rawMarkdown = ISSUE_UTILS.getIssueDescription(filename);
+        if (!rawMarkdown) {
+            return undefined;
+        }
+        try {
+            return DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription?.substitutions);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}