chrome-devtools-mcp 0.12.0 → 0.12.1

package/README.md

@@ -160,9 +160,9 @@ Configure the following fields and press `CTRL+S` to save the configuration:
 
 **Click the button to install:**
 
-[<img src="https://mcpbadge.dev/badge-install-in-vs-code-stable-dark" alt="Install in VS Code">](https://vscode.dev/redirect/mcp/install?name=io.github.ChromeDevTools%2Fchrome-devtools-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22chrome-devtools-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://vscode.dev/redirect/mcp/install?name=io.github.ChromeDevTools%2Fchrome-devtools-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22chrome-devtools-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)
 
-[<img src="https://mcpbadge.dev/badge-install-in-vs-code-insiders-dark" alt="Install in VS Code Insiders">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522io.github.ChromeDevTools%252Fchrome-devtools-mcp%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522chrome-devtools-mcp%2522%255D%252C%2522env%2522%253A%257B%257D%257D%257D)
+[<img src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5" alt="Install in VS Code Insiders">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522io.github.ChromeDevTools%252Fchrome-devtools-mcp%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522chrome-devtools-mcp%2522%255D%252C%2522env%2522%253A%257B%257D%257D%257D)
 
 **Or install manually:**
 
@@ -484,9 +484,73 @@ 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, 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 Chrome DevTools MCP server to automatically connect to a running Chrome Instance
+
+To connect the `chrome-devtools-mcp` server to the running Chrome instance, use
+`--autoConnect` command line argument for the MCP server.
+
+The following code snippet is an example configuration for gemini-cli:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--autoConnect",
+        "--channel=canary"
+      ]
+    }
+  }
+}
+```
+
+Note: you have to specify `--channel=canary` until Chrome M144 has reached the
+stable channel.
+
+**Step 3:** Test your setup
+
+Make sure your browser is running. Open gemini-cli and run the following prompt:
+
+```none
+Check the performance of https://developers.chrome.com
+```
+
+Note: The <code>autoConnect</code> option requires the user to start Chrome.
+
+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 on how to connect to a running Chrome instance:
 
 **Step 1: Configure the MCP client**
 

package/build/src/DevtoolsUtils.js

@@ -3,11 +3,11 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { DebuggerModel, Foundation, TargetManager, MarkdownIssueDescription, Marked, ProtocolClient, Common, I18n, } from '../node_modules/chrome-devtools-frontend/mcp/mcp.js';
 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) {
     const match = title.match(new RegExp(`DevTools - (.*)`));
     return match?.[1] ?? undefined;
@@ -58,7 +58,7 @@ function normalizeUrl(url) {
  * A mock implementation of an issues manager that only implements the methods
  * that are actually used by the IssuesAggregator
  */
-export class FakeIssuesManager extends Common.ObjectWrapper
+export class FakeIssuesManager extends DevTools.Common.ObjectWrapper
     .ObjectWrapper {
     issues() {
         return [];
@@ -82,9 +82,11 @@ export function mapIssueToMessageObject(issue) {
     let processedMarkdown;
     let title;
     try {
-        processedMarkdown = MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription.substitutions);
-        const markdownAst = Marked.Marked.lexer(processedMarkdown);
-        title = MarkdownIssueDescription.findTitleFromMarkdownAst(markdownAst);
+        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());
@@ -103,8 +105,8 @@ export function mapIssueToMessageObject(issue) {
     };
 }
 // DevTools CDP errors can get noisy.
-ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
-I18n.DevToolsLocale.DevToolsLocale.instance({
+DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
+DevTools.I18n.DevToolsLocale.DevToolsLocale.instance({
     create: true,
     data: {
         navigatorLanguage: 'en-US',
@@ -112,7 +114,7 @@ I18n.DevToolsLocale.DevToolsLocale.instance({
         lookupClosestDevToolsLocale: l => l,
     },
 });
-I18n.i18n.registerLocaleDataForTest('en-US', {});
+DevTools.I18n.i18n.registerLocaleDataForTest('en-US', {});
 export class UniverseManager {
     #browser;
     #createUniverseFor;
@@ -173,20 +175,20 @@ export class UniverseManager {
     };
 }
 const DEFAULT_FACTORY = async (page) => {
-    const settingStorage = new Common.Settings.SettingsStorage({});
-    const universe = new Foundation.Universe.Universe({
+    const settingStorage = new DevTools.Common.Settings.SettingsStorage({});
+    const universe = new DevTools.Foundation.Universe.Universe({
         settingsCreationOptions: {
             syncedStorage: settingStorage,
             globalStorage: settingStorage,
             localStorage: settingStorage,
-            settingRegistrations: Common.SettingRegistration.getRegisteredSettings(),
+            settingRegistrations: DevTools.Common.SettingRegistration.getRegisteredSettings(),
         },
-        overrideAutoStartModels: new Set([DebuggerModel]),
+        overrideAutoStartModels: new Set([DevTools.DebuggerModel]),
     });
     const session = await page.createCDPSession();
     const connection = new PuppeteerDevToolsConnection(session);
-    const targetManager = universe.context.get(TargetManager);
-    targetManager.observeModels(DebuggerModel, SKIP_ALL_PAUSES);
+    const targetManager = universe.context.get(DevTools.TargetManager);
+    targetManager.observeModels(DevTools.DebuggerModel, SKIP_ALL_PAUSES);
     const target = targetManager.createTarget('main', '', 'frame', // eslint-disable-line @typescript-eslint/no-explicit-any
     /* parentTarget */ null, session.id(), undefined, connection);
     return { target, universe };

package/build/src/McpContext.js

@@ -249,10 +249,16 @@ export class McpContext {
         const oldPage = this.#selectedPage;
         if (oldPage) {
             oldPage.off('dialog', this.#dialogHandler);
+            void oldPage.emulateFocusedPage(false).catch(error => {
+                this.logger('Error turning off focused page emulation', error);
+            });
         }
         this.#selectedPage = newPage;
         newPage.on('dialog', this.#dialogHandler);
         this.#updateSelectedPageTimeouts();
+        void newPage.emulateFocusedPage(true).catch(error => {
+            this.logger('Error turning on focused page emulation', error);
+        });
     }
     #updateSelectedPageTimeouts() {
         const page = this.getSelectedPage();

package/build/src/McpResponse.js

@@ -3,11 +3,11 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { AggregatedIssue } from '../node_modules/chrome-devtools-frontend/mcp/mcp.js';
 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 { DevTools } from './third_party/index.js';
 import { handleDialog } from './tools/pages.js';
 import { paginate } from './utils/pagination.js';
 export class McpResponse {
@@ -155,7 +155,7 @@ export class McpResponse {
                     })),
                 };
             }
-            else if (message instanceof AggregatedIssue) {
+            else if (message instanceof DevTools.AggregatedIssue) {
                 const mappedIssueMessage = mapIssueToMessageObject(message);
                 if (!mappedIssueMessage)
                     throw new Error("Can't provide detals for the msgid " + consoleMessageStableId);
@@ -182,7 +182,7 @@ export class McpResponse {
                     if ('type' in message) {
                         return normalizedTypes.has(message.type());
                     }
-                    if (message instanceof AggregatedIssue) {
+                    if (message instanceof DevTools.AggregatedIssue) {
                         return normalizedTypes.has('issue');
                     }
                     return normalizedTypes.has('error');
@@ -206,7 +206,7 @@ export class McpResponse {
                         })),
                     };
                 }
-                if (item instanceof AggregatedIssue) {
+                if (item instanceof DevTools.AggregatedIssue) {
                     const mappedIssueMessage = mapIssueToMessageObject(item);
                     if (!mappedIssueMessage)
                         return null;

package/build/src/PageCollector.js

@@ -3,9 +3,9 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { createIssuesFromProtocolIssue, IssueAggregator, } from '../node_modules/chrome-devtools-frontend/mcp/mcp.js';
 import { FakeIssuesManager } from './DevtoolsUtils.js';
 import { logger } from './logger.js';
+import { DevTools } from './third_party/index.js';
 function createIdGenerator() {
     let i = 1;
     return () => {
@@ -43,18 +43,28 @@ export class PageCollector {
         this.#browser.off('targetdestroyed', this.#onTargetDestroyed);
     }
     #onTargetCreated = async (target) => {
-        const page = await target.page();
-        if (!page) {
-            return;
+        try {
+            const page = await target.page();
+            if (!page) {
+                return;
+            }
+            this.addPage(page);
+        }
+        catch (err) {
+            logger('Error getting a page for a target onTargetCreated', err);
         }
-        this.addPage(page);
     };
     #onTargetDestroyed = async (target) => {
-        const page = await target.page();
-        if (!page) {
-            return;
+        try {
+            const page = await target.page();
+            if (!page) {
+                return;
+            }
+            this.cleanupPageDestroyed(page);
+        }
+        catch (err) {
+            logger('Error getting a page for a target onTargetDestroyed', err);
         }
-        this.cleanupPageDestroyed(page);
     };
     addPage(page) {
         this.#initializePage(page);
@@ -164,7 +174,7 @@ export class ConsoleCollector extends PageCollector {
 }
 class PageIssueSubscriber {
     #issueManager = new FakeIssuesManager();
-    #issueAggregator = new IssueAggregator(this.#issueManager);
+    #issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
     #seenKeys = new Set();
     #seenIssues = new Set();
     #page;
@@ -177,10 +187,10 @@ class PageIssueSubscriber {
     #resetIssueAggregator() {
         this.#issueManager = new FakeIssuesManager();
         if (this.#issueAggregator) {
-            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
+            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
         }
-        this.#issueAggregator = new IssueAggregator(this.#issueManager);
-        this.#issueAggregator.addEventListener("AggregatedIssueUpdated" /* IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
+        this.#issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
+        this.#issueAggregator.addEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
     }
     async subscribe() {
         this.#resetIssueAggregator();
@@ -199,7 +209,7 @@ class PageIssueSubscriber {
         this.#page.off('framenavigated', this.#onFrameNavigated);
         this.#session.off('Audits.issueAdded', this.#onIssueAdded);
         if (this.#issueAggregator) {
-            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
+            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedissue);
         }
         void this.#session.send('Audits.disable').catch(() => {
             // might fail.
@@ -225,9 +235,9 @@ class PageIssueSubscriber {
     #onIssueAdded = (data) => {
         try {
             const inspectorIssue = data.issue;
-            // @ts-expect-error Types of protocol from Puppeteer and CDP are
-            // incomparable for InspectorIssueCode, one is union, other is enum.
-            const issue = createIssuesFromProtocolIssue(null, inspectorIssue)[0];
+            const issue = DevTools.createIssuesFromProtocolIssue(null, 
+            // @ts-expect-error Protocol types diverge.
+            inspectorIssue)[0];
             if (!issue) {
                 logger('No issue mapping for for the issue: ', inspectorIssue.code);
                 return;
@@ -237,7 +247,7 @@ class PageIssueSubscriber {
                 return;
             }
             this.#seenKeys.add(primaryKey);
-            this.#issueManager.dispatchEventToListeners("IssueAdded" /* IssuesManagerEvents.ISSUE_ADDED */, {
+            this.#issueManager.dispatchEventToListeners("IssueAdded" /* DevTools.IssuesManagerEvents.ISSUE_ADDED */, {
                 issue,
                 // @ts-expect-error We don't care that issues model is null
                 issuesModel: null,

package/build/src/issue-descriptions.js

@@ -5,7 +5,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-const DESCRIPTIONS_PATH = path.join(import.meta.dirname, '../node_modules/chrome-devtools-frontend/front_end/models/issues_manager/descriptions');
+const DESCRIPTIONS_PATH = path.join(import.meta.dirname, 'third_party/issue-descriptions');
 let issueDescriptions = {};
 /**
  * Reads all issue descriptions from the filesystem into memory.

package/build/src/main.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import './polyfill.js';
+import process from 'node:process';
 import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
 import { parseArguments } from './cli.js';
 import { loadIssueDescriptions } from './issue-descriptions.js';
@@ -16,10 +17,13 @@ import { ToolCategory } from './tools/categories.js';
 import { tools } from './tools/tools.js';
 // If moved update release-please config
 // x-release-please-start-version
-const VERSION = '0.12.0';
+const VERSION = '0.12.1';
 // x-release-please-end
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+process.on('unhandledRejection', (reason, promise) => {
+    logger('Unhandled promise rejection', promise, reason);
+});
 logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
 const server = new McpServer({
     name: 'chrome_devtools',