chrome-devtools-mcp 0.11.0 → 0.12.0

package/README.md

@@ -7,7 +7,7 @@ control and inspect a live Chrome browser. It acts as a Model-Context-Protocol
 (MCP) server, giving your AI coding assistant access to the full power of
 Chrome DevTools for reliable automation, in-depth debugging, and performance analysis.
 
-## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md)
+## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
 
 ## Key features
 
@@ -350,6 +350,11 @@ 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.
+  - **Type:** boolean
+  - **Default:** `false`
+
 - **`--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

package/build/src/browser.js

@@ -32,6 +32,7 @@ function makeTargetFilter() {
     };
 }
 export async function ensureBrowserConnected(options) {
+    const { channel } = options;
     if (browser?.connected) {
         return browser;
     }
@@ -49,11 +50,56 @@ export async function ensureBrowserConnected(options) {
     else if (options.browserURL) {
         connectOptions.browserURL = options.browserURL;
     }
+    else if (channel || options.userDataDir) {
+        const userDataDir = options.userDataDir;
+        if (userDataDir) {
+            // TODO: re-expose this logic via Puppeteer.
+            const portPath = path.join(userDataDir, 'DevToolsActivePort');
+            try {
+                const fileContent = await fs.promises.readFile(portPath, 'utf8');
+                const [rawPort, rawPath] = fileContent
+                    .split('\n')
+                    .map(line => {
+                    return line.trim();
+                })
+                    .filter(line => {
+                    return !!line;
+                });
+                if (!rawPort || !rawPath) {
+                    throw new Error(`Invalid DevToolsActivePort '${fileContent}' found`);
+                }
+                const port = parseInt(rawPort, 10);
+                if (isNaN(port) || port <= 0 || port > 65535) {
+                    throw new Error(`Invalid port '${rawPort}' found`);
+                }
+                const browserWSEndpoint = `ws://127.0.0.1:${port}${rawPath}`;
+                connectOptions.browserWSEndpoint = browserWSEndpoint;
+            }
+            catch (error) {
+                throw new Error(`Could not connect to Chrome in ${userDataDir}. Check if Chrome is running and remote debugging is enabled.`, {
+                    cause: error,
+                });
+            }
+        }
+        else {
+            if (!channel) {
+                throw new Error('Channel must be provided if userDataDir is missing');
+            }
+            connectOptions.channel = (channel === 'stable' ? 'chrome' : `chrome-${channel}`);
+        }
+    }
     else {
-        throw new Error('Either browserURL or wsEndpoint must be provided');
+        throw new Error('Either browserURL, wsEndpoint, channel or userDataDir must be provided');
     }
     logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
-    browser = await puppeteer.connect(connectOptions);
+    try {
+        browser = await puppeteer.connect(connectOptions);
+    }
+    catch (err) {
+        throw new Error('Could not connect to Chrome. Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.', {
+            cause: err,
+        });
+    }
     logger('Connected Puppeteer');
     return browser;
 }

package/build/src/cli.js

@@ -5,6 +5,18 @@
  */
 import { yargs, hideBin } from './third_party/index.js';
 export const cliOptions = {
+    autoConnect: {
+        type: 'boolean',
+        description: '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.',
+        conflicts: ['isolated', 'executablePath'],
+        default: false,
+        coerce: (value) => {
+            if (!value) {
+                return;
+            }
+            return value;
+        },
+    },
     browserUrl: {
         type: 'string',
         description: '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.',
@@ -204,6 +216,14 @@ export function parseArguments(version, argv = process.argv) {
             '$0 --user-data-dir=/tmp/user-data-dir',
             'Use a custom user data directory',
         ],
+        [
+            '$0 --auto-connect',
+            'Connect to a stable Chrome instance (Chrome 145+) running instead of launching a new instance',
+        ],
+        [
+            '$0 --auto-connect --channel=canary',
+            'Connect to a canary Chrome instance (Chrome 145+) running instead of launching a new instance',
+        ],
     ]);
     return yargsInstance
         .wrap(Math.min(120, yargsInstance.terminalWidth()))

package/build/src/main.js

@@ -16,7 +16,7 @@ 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.11.0';
+const VERSION = '0.12.0';
 // x-release-please-end
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
@@ -36,11 +36,14 @@ async function getContext() {
         extraArgs.push(`--proxy-server=${args.proxyServer}`);
     }
     const devtools = args.experimentalDevtools ?? false;
-    const browser = args.browserUrl || args.wsEndpoint
+    const browser = args.browserUrl || args.wsEndpoint || args.autoConnect
         ? await ensureBrowserConnected({
             browserURL: args.browserUrl,
             wsEndpoint: args.wsEndpoint,
             wsHeaders: args.wsHeaders,
+            // Important: only pass channel, if autoConnect is true.
+            channel: args.autoConnect ? args.channel : undefined,
+            userDataDir: args.userDataDir,
             devtools,
         })
         : await ensureBrowserLaunched({
@@ -104,7 +107,10 @@ function registerTool(tool) {
         }
         catch (err) {
             logger(`${tool.name} error:`, err, err?.stack);
-            const errorText = err && 'message' in err ? err.message : String(err);
+            let errorText = err && 'message' in err ? err.message : String(err);
+            if ('cause' in err && err.cause) {
+                errorText += `\nCause: ${err.cause.message}`;
+            }
             return {
                 content: [
                     {