@mcp-b/chrome-devtools-mcp 2.0.2 → 2.0.5

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

@@ -89,6 +89,7 @@ export class McpContext {
     #networkConditionsMap = new WeakMap();
     #cpuThrottlingRateMap = new WeakMap();
     #geolocationMap = new WeakMap();
+    #bypassCSPMap = new WeakMap();
     #dialog;
     #nextSnapshotId = 1;
     #traceResults = [];
@@ -160,7 +161,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 +303,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 +318,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;
@@ -616,6 +617,20 @@ export class McpContext {
         const page = this.getSelectedPage();
         return this.#geolocationMap.get(page) ?? null;
     }
+    async setBypassCSP(enabled) {
+        const page = this.getSelectedPage();
+        await page.setBypassCSP(enabled);
+        if (enabled) {
+            this.#bypassCSPMap.set(page, true);
+        }
+        else {
+            this.#bypassCSPMap.delete(page);
+        }
+    }
+    getBypassCSP() {
+        const page = this.getSelectedPage();
+        return this.#bypassCSPMap.get(page) ?? false;
+    }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
     }
@@ -916,7 +931,8 @@ export class McpContext {
         try {
             const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'chrome-devtools-mcp-'));
             const filename = path.join(dir, `screenshot.${getExtensionFromMimeType(mimeType)}`);
-            await fs.writeFile(filename, data);
+            // Use mode 0o600 (owner read/write only) for secure temp file creation
+            await fs.writeFile(filename, data, { mode: 0o600 });
             return { filename };
         }
         catch (err) {
@@ -927,7 +943,8 @@ export class McpContext {
     async saveFile(data, filename) {
         try {
             const filePath = path.resolve(filename);
-            await fs.writeFile(filePath, data);
+            // Use mode 0o644 (owner read/write, others read) for user-specified paths
+            await fs.writeFile(filePath, data, { mode: 0o644 });
             return { filename };
         }
         catch (err) {
@@ -1051,6 +1068,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

@@ -10,6 +10,61 @@ import { logger } from './logger.js';
 import { puppeteer } from './third_party/index.js';
 /** Cached browser instance for reuse across calls. */
 let browser;
+/**
+ * Get Chrome's default user data directory for the given platform and channel.
+ *
+ * @returns The platform-specific path to Chrome's user data directory.
+ */
+function getChromeDefaultUserDataDir(channel = 'stable') {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        const suffix = channel === 'stable'
+            ? ''
+            : ` ${channel.charAt(0).toUpperCase() + channel.slice(1)}`;
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Google', `Chrome${suffix}`);
+    }
+    if (platform === 'win32') {
+        const appData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+        const suffix = channel === 'stable'
+            ? ''
+            : ` ${channel.charAt(0).toUpperCase() + channel.slice(1)}`;
+        return path.join(appData, 'Google', `Chrome${suffix}`, 'User Data');
+    }
+    // Linux
+    const channelSuffix = channel === 'stable'
+        ? ''
+        : channel === 'beta'
+            ? '-beta'
+            : '-unstable';
+    return path.join(os.homedir(), '.config', `google-chrome${channelSuffix}`);
+}
+/**
+ * Try to read a WebSocket endpoint from a DevToolsActivePort file.
+ *
+ * @param userDataDir - Directory containing the DevToolsActivePort file.
+ * @returns The WebSocket endpoint URL, or undefined if the file doesn't exist or is invalid.
+ */
+function readDevToolsActivePort(userDataDir) {
+    const portPath = path.join(userDataDir, 'DevToolsActivePort');
+    try {
+        const fileContent = fs.readFileSync(portPath, 'utf8');
+        const [rawPort, rawPath] = fileContent
+            .split('\n')
+            .map(line => line.trim())
+            .filter(line => !!line);
+        if (!rawPort || !rawPath) {
+            return undefined;
+        }
+        const port = parseInt(rawPort, 10);
+        if (isNaN(port) || port <= 0 || port > 65535) {
+            return undefined;
+        }
+        return `ws://127.0.0.1:${port}${rawPath}`;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Create a target filter for Puppeteer that excludes internal Chrome pages.
  *
@@ -18,10 +73,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 +108,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;
@@ -74,64 +133,59 @@ export async function ensureBrowserConnected(options) {
     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;
+            // Explicit user data dir provided
+            const wsEndpoint = readDevToolsActivePort(userDataDir);
+            if (wsEndpoint) {
+                connectOptions.browserWSEndpoint = wsEndpoint;
             }
-            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 {
+                throw new Error(`Could not connect to Chrome in ${userDataDir}. Check if Chrome is running and remote debugging is enabled.`);
             }
         }
         else {
             if (!channel) {
                 throw new Error('Channel must be provided if userDataDir is missing');
             }
-            // Derive the default userDataDir from the channel (same as launch does)
+            // Collect candidate WebSocket endpoints from multiple directories.
+            // Try each one in order — stale DevToolsActivePort files are common,
+            // so we attempt the actual connection before moving to the next.
             const profileDirName = channel && channel !== 'stable'
                 ? `chrome-profile-${channel}`
                 : 'chrome-profile';
-            const derivedUserDataDir = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', profileDirName);
-            // Try to read DevToolsActivePort from the derived userDataDir
-            const portPath = path.join(derivedUserDataDir, 'DevToolsActivePort');
-            try {
-                const fileContent = await fs.promises.readFile(portPath, 'utf8');
-                const [rawPort, rawPath] = fileContent
-                    .split('\n')
-                    .map(line => line.trim())
-                    .filter(line => !!line);
-                if (!rawPort || !rawPath) {
-                    throw new Error(`Invalid DevToolsActivePort '${fileContent}' found`);
+            const mcpUserDataDir = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', profileDirName);
+            const chromeUserDataDir = getChromeDefaultUserDataDir(channel);
+            // Chrome's default profile is checked first — this is the user's
+            // real browser with remote debugging enabled via chrome://inspect.
+            // The MCP cache dir is checked second as a fallback for instances
+            // launched by the MCP server itself.
+            const candidates = [];
+            const chromeWsEndpoint = readDevToolsActivePort(chromeUserDataDir);
+            if (chromeWsEndpoint) {
+                candidates.push({ dir: chromeUserDataDir, wsEndpoint: chromeWsEndpoint });
+            }
+            const mcpWsEndpoint = readDevToolsActivePort(mcpUserDataDir);
+            if (mcpWsEndpoint) {
+                candidates.push({ dir: mcpUserDataDir, wsEndpoint: mcpWsEndpoint });
+            }
+            if (candidates.length === 0) {
+                throw new Error(`Could not connect to Chrome ${channel} channel. Checked ${mcpUserDataDir} and ${chromeUserDataDir}. Ensure Chrome is running with remote debugging enabled (chrome://inspect/#remote-debugging).`);
+            }
+            // Try each candidate endpoint, returning the first that connects
+            for (const candidate of candidates) {
+                try {
+                    logger(`Trying DevToolsActivePort from ${candidate.dir}: ${candidate.wsEndpoint}`);
+                    browser = await puppeteer.connect({
+                        ...connectOptions,
+                        browserWSEndpoint: candidate.wsEndpoint,
+                    });
+                    logger(`Connected via ${candidate.dir}`);
+                    return browser;
                 }
-                const port = parseInt(rawPort, 10);
-                if (isNaN(port) || port <= 0 || port > 65535) {
-                    throw new Error(`Invalid port '${rawPort}' found`);
+                catch (err) {
+                    logger(`Failed to connect via ${candidate.dir}: ${err.message}`);
                 }
-                const browserWSEndpoint = `ws://127.0.0.1:${port}${rawPath}`;
-                connectOptions.browserWSEndpoint = browserWSEndpoint;
-            }
-            catch (error) {
-                throw new Error(`Could not connect to Chrome ${channel} channel in ${derivedUserDataDir}. Check if Chrome is running and was launched with remote debugging enabled.`, { cause: error });
             }
+            throw new Error(`Could not connect to Chrome ${channel} channel. Tried ${candidates.map(c => c.dir).join(' and ')}. Ensure Chrome is running with remote debugging enabled (chrome://inspect/#remote-debugging).`);
         }
     }
     else {
@@ -201,7 +255,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 +264,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 +278,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 +308,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))
@@ -170,11 +175,12 @@ export function parseArguments(version, argv = process.argv) {
         .check(args => {
         // We can't set default in the options else
         // Yargs will complain
-        if (!args.channel &&
-            !args.browserUrl &&
-            !args.wsEndpoint &&
-            !args.executablePath) {
-            args.channel = 'dev';
+        // Note: Use explicit undefined checks since empty strings are valid falsy values
+        if (args.channel === undefined &&
+            args.browserUrl === undefined &&
+            args.wsEndpoint === undefined &&
+            args.executablePath === undefined) {
+            args.channel = 'stable';
         }
         return true;
     })