@mcp-b/chrome-devtools-mcp 1.3.0 → 1.4.0

package/README.md

@@ -5,7 +5,7 @@
 [![npm @mcp-b/chrome-devtools-mcp package](https://img.shields.io/npm/v/@mcp-b/chrome-devtools-mcp.svg)](https://www.npmjs.com/package/@mcp-b/chrome-devtools-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/@mcp-b/chrome-devtools-mcp?style=flat-square)](https://www.npmjs.com/package/@mcp-b/chrome-devtools-mcp)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
-[![28 Tools](https://img.shields.io/badge/MCP_Tools-28-green?style=flat-square)](./docs/tool-reference.md)
+[![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)**
@@ -21,7 +21,7 @@
 
 | Feature | Benefit |
 |---------|---------|
-| **28 MCP Tools** | Comprehensive browser control - navigation, input, screenshots, performance, debugging |
+| **27 MCP Tools** | Comprehensive browser control - navigation, input, screenshots, performance, debugging |
 | **WebMCP Integration** | Connect to website-specific AI tools via `@mcp-b/global` |
 | **Performance Analysis** | Chrome DevTools-powered performance insights and trace recording |
 | **Reliable Automation** | Puppeteer-based with automatic waiting for action results |
@@ -56,7 +56,7 @@ This fork adds **WebMCP integration** - the ability to call MCP tools that are r
 | **List website MCP tools** | ❌ | ✅ |
 | **AI-driven tool development** | ❌ | ✅ |
 
-The key addition is the `list_webmcp_tools` and `call_webmcp_tool` tools that let your AI agent interact with MCP tools that websites expose via [@mcp-b/global](https://www.npmjs.com/package/@mcp-b/global).
+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.
 
 ## AI-Driven Development Workflow
 
@@ -124,7 +124,7 @@ This creates a tight feedback loop where your AI assistant can:
 - **Write** WebMCP tools in your codebase
 - **Deploy** them automatically via hot-reload
 - **Discover** them through `list_webmcp_tools`
-- **Test** them through `call_webmcp_tool`
+- **Test** them by calling tools directly by their prefixed names (e.g., `webmcp_localhost_3000_page0_search_products`)
 - **Debug** issues using console messages and snapshots
 - **Iterate** until the tool works correctly
 
@@ -475,9 +475,8 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`list_console_messages`](docs/tool-reference.md#list_console_messages)
   - [`take_screenshot`](docs/tool-reference.md#take_screenshot)
   - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
-- **Website MCP Tools** (2 tools)
-  - [`list_webmcp_tools`](docs/tool-reference.md#list_webmcp_tools) - List available website tools (auto-connects)
-  - [`call_webmcp_tool`](docs/tool-reference.md#call_webmcp_tool) - Call a website tool (auto-connects)
+- **Website MCP Tools** (1 tool)
+  - [`list_webmcp_tools`](docs/tool-reference.md#list_webmcp_tools) - List available website tools across all pages (with diff)
 
 <!-- END AUTO GENERATED TOOLS -->
 
@@ -674,6 +673,14 @@ all instances of `@mcp-b/chrome-devtools-mcp`. Set the `isolated` option to `tru
 to use a temporary user data dir instead which will be cleared automatically after
 the browser is closed.
 
+> [!NOTE]
+> When using a shared user data directory (non-isolated), the server launches
+> Chrome with a local remote debugging port (`--remote-debugging-port=0` and
+> `--remote-debugging-address=127.0.0.1`) so it can auto-connect on future runs.
+> This means any local process can attach to that port. If you prefer pipe-only
+> mode, pass `--chrome-arg=--remote-debugging-pipe` (auto-connect across runs
+> will be disabled).
+
 ### 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.
@@ -810,17 +817,39 @@ What tools are available on this website?
 The AI agent will use `list_webmcp_tools` to show you what functionality the
 website exposes. This automatically connects to the page's WebMCP server.
 
-**3. Use the tools**
+**3. Use the tools directly**
 
 ```
 Search for "wireless headphones" using the website's search tool
 ```
 
-The AI agent will use `call_webmcp_tool` to invoke the website's functionality.
+The AI agent will call the tool directly by its prefixed name (e.g., `webmcp_example_com_page0_search_products`).
+WebMCP tools are registered as first-class MCP tools, so they appear directly in your agent's tool list.
 
 That's it! No explicit connect or disconnect steps needed - WebMCP tools
-auto-connect when called and automatically reconnect when you navigate to
-a different page.
+auto-connect when detected and automatically update when you navigate.
+
+### Dynamic Tool Registration
+
+By default, WebMCP tools are automatically registered as first-class MCP tools when detected on a webpage. This means tools like `search_products` appear directly in your MCP client's tool list with prefixed names like `webmcp_localhost_3000_page0_search_products`.
+
+**MCP Client Compatibility:**
+
+| Client | Dynamic Tool Updates | Notes |
+|--------|---------------------|-------|
+| Claude Code | Yes | Full support for `tools/list_changed` |
+| GitHub Copilot | Yes | Supports list changed notifications |
+| Gemini CLI | Yes | Recently added support |
+| Cursor | No | Use `list_webmcp_tools` to poll manually |
+| Cline | Partial | May need manual polling with `list_webmcp_tools` |
+| Continue | Unknown | Use `list_webmcp_tools` if tools don't appear |
+
+**For clients without dynamic tool support:**
+
+If your MCP client doesn't support `tools/list_changed` notifications, use `list_webmcp_tools` to manually see which tools are available, then call them directly by their prefixed names. The `list_webmcp_tools` tool is diff-aware to reduce context pollution:
+- First call returns the full tool list
+- Subsequent calls return only added/removed tools
+- Use `full: true` to force the complete list
 
 ### Example prompts
 

package/build/src/McpContext.js

@@ -8,16 +8,25 @@ import os from 'node:os';
 import path from 'node:path';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { extractUrlLikeFromDevToolsTitle, urlsEqual } from './DevtoolsUtils.js';
+import { ToolListChangedNotificationSchema } from './third_party/index.js';
 import { NetworkCollector, ConsoleCollector } from './PageCollector.js';
-import { WEB_MCP_BRIDGE_SCRIPT, CHECK_WEBMCP_AVAILABLE_SCRIPT } from './transports/WebMCPBridgeScript.js';
+import { WEB_MCP_BRIDGE_SCRIPT } from './transports/WebMCPBridgeScript.js';
 import { WebMCPClientTransport } from './transports/WebMCPClientTransport.js';
 import { Locator } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { takeSnapshot } from './tools/snapshot.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
 import { WaitForHelper } from './WaitForHelper.js';
+/** Default timeout for page operations in milliseconds. */
 const DEFAULT_TIMEOUT = 5_000;
+/** Default timeout for navigation operations in milliseconds. */
 const NAVIGATION_TIMEOUT = 10_000;
+/**
+ * Get the timeout multiplier for a given network condition.
+ *
+ * @param condition - The network condition name (e.g., "Fast 4G", "Slow 3G").
+ * @returns Multiplier to apply to timeouts (1 = no slowdown, 10 = max slowdown).
+ */
 function getNetworkMultiplierFromString(condition) {
     const puppeteerCondition = condition;
     switch (puppeteerCondition) {
@@ -32,6 +41,13 @@ function getNetworkMultiplierFromString(condition) {
     }
     return 1;
 }
+/**
+ * Get the file extension for a given MIME type.
+ *
+ * @param mimeType - The MIME type (e.g., "image/png").
+ * @returns The corresponding file extension without the dot.
+ * @throws Error if the MIME type is not supported.
+ */
 function getExtensionFromMimeType(mimeType) {
     switch (mimeType) {
         case 'image/png':
@@ -43,14 +59,23 @@ function getExtensionFromMimeType(mimeType) {
     }
     throw new Error(`No mapping for Mime type ${mimeType}.`);
 }
+/**
+ * Central context for MCP operations on a browser instance.
+ *
+ * Manages page state, accessibility snapshots, network/console collection,
+ * WebMCP connections, and tool registration. This class serves as the primary
+ * interface between MCP tools and the browser.
+ */
 export class McpContext {
     browser;
     logger;
-    // The most recent page state.
+    /** Cached list of available pages (refreshed by createPagesSnapshot). */
     #pages = [];
+    /** Mapping of content pages to their associated DevTools inspector pages. */
     #pageToDevToolsPage = new Map();
+    /** Currently selected page for tool operations. */
     #selectedPage;
-    // The most recent snapshot.
+    /** Most recent accessibility snapshot of the selected page. */
     #textSnapshot = null;
     #networkCollector;
     #consoleCollector;
@@ -64,6 +89,9 @@ export class McpContext {
     #locatorClass;
     #options;
     #webMCPConnections = new WeakMap();
+    #toolHub;
+    /** Tracks pages that have WebMCP auto-detection listeners installed. */
+    #pagesWithWebMCPListeners = new WeakSet();
     constructor(browser, logger, options, locatorClass) {
         this.browser = browser;
         this.logger = logger;
@@ -141,9 +169,128 @@ export class McpContext {
         this.#networkCollector.dispose();
         this.#consoleCollector.dispose();
     }
-    static async from(browser, logger, opts, 
-    /* Let tests use unbundled Locator class to avoid overly strict checks within puppeteer that fail when mixing bundled and unbundled class instances */
-    locatorClass = Locator) {
+    /**
+     * Set the WebMCPToolHub for dynamic tool registration.
+     * This enables automatic registration of WebMCP tools as native MCP tools.
+     * Also sets up auto-detection for all existing pages.
+     */
+    setToolHub(hub) {
+        this.#toolHub = hub;
+        // Trigger auto-detection for all existing pages asynchronously
+        this.#setupWebMCPAutoDetectionForAllPages().catch(err => {
+            this.logger('Error setting up WebMCP auto-detection:', err);
+        });
+    }
+    /**
+     * Get the WebMCPToolHub instance (for testing purposes)
+     */
+    getToolHub() {
+        return this.#toolHub;
+    }
+    /**
+     * Set up automatic WebMCP detection for a page.
+     * This installs listeners that detect WebMCP after navigation and sync tools.
+     */
+    #setupWebMCPAutoDetection(page) {
+        // Skip if listeners already installed
+        if (this.#pagesWithWebMCPListeners.has(page)) {
+            return;
+        }
+        // Skip chrome:// and devtools:// pages
+        const url = page.url();
+        if (url.startsWith('chrome://') ||
+            url.startsWith('chrome-extension://') ||
+            url.startsWith('devtools://')) {
+            return;
+        }
+        this.#pagesWithWebMCPListeners.add(page);
+        // Handler for frame navigation - detect WebMCP after main frame navigates
+        const onFrameNavigated = async (frame) => {
+            // Only handle main frame navigation
+            // @ts-expect-error Frame type not exported
+            if (frame.parentFrame?.() !== null) {
+                return;
+            }
+            // Skip internal pages
+            const newUrl = page.url();
+            if (newUrl.startsWith('chrome://') ||
+                newUrl.startsWith('chrome-extension://') ||
+                newUrl.startsWith('devtools://') ||
+                newUrl === 'about:blank') {
+                return;
+            }
+            // Immediately try to connect - no polling needed
+            // If no WebMCP, connection will timeout gracefully
+            this.#tryConnectWebMCP(page).catch(err => {
+                this.logger('WebMCP connection attempt failed (expected if page has no WebMCP):', err);
+            });
+        };
+        page.on('framenavigated', onFrameNavigated);
+        // Clean up listener when page closes
+        page.once('close', () => {
+            page.off('framenavigated', onFrameNavigated);
+            this.#pagesWithWebMCPListeners.delete(page);
+        });
+        this.logger(`WebMCP auto-detection listener installed for page: ${url}`);
+    }
+    /**
+     * Attempt to connect to WebMCP on a page without pre-checking.
+     * Uses the extension's approach: just try to connect, handle failure gracefully.
+     *
+     * This matches the WebMCP extension's behavior:
+     * - No pre-flight detection polling
+     * - Immediate connection attempt
+     * - Graceful handling if no server exists
+     * - Notification-based syncing when tools appear later
+     *
+     * Reference: /WebMCP/apps/extension/entrypoints/content/connection.ts lines 88-118
+     */
+    async #tryConnectWebMCP(page) {
+        // Skip if tool hub is not enabled
+        if (!this.#toolHub?.isEnabled()) {
+            return;
+        }
+        try {
+            // Immediately try to get/create WebMCP client
+            // Transport is configured with requireWebMCP: false and 30s timeout in getWebMCPClient
+            const result = await this.getWebMCPClient(page);
+            if (result.connected) {
+                this.logger(`WebMCP connected for page: ${page.url()}`);
+            }
+            else {
+                // This is normal for pages without WebMCP
+                this.logger(`No WebMCP on page: ${page.url()}`);
+            }
+        }
+        catch (err) {
+            // Connection timeout or error is expected on pages without WebMCP
+            this.logger(`WebMCP connection failed for ${page.url()} (normal if page has no WebMCP):`, err);
+        }
+    }
+    /**
+     * Set up WebMCP auto-detection for all current pages.
+     * Called during initialization and when tool hub is set.
+     */
+    async #setupWebMCPAutoDetectionForAllPages() {
+        for (const page of this.#pages) {
+            this.#setupWebMCPAutoDetection(page);
+            // Try to connect immediately (don't await - run in parallel for all pages)
+            this.#tryConnectWebMCP(page).catch(err => {
+                this.logger('Initial WebMCP connection attempt failed (expected):', err);
+            });
+        }
+    }
+    /**
+     * Create a new McpContext instance.
+     *
+     * @param browser - Puppeteer browser instance to operate on.
+     * @param logger - Debug logger for internal operations.
+     * @param opts - Configuration options.
+     * @param locatorClass - Locator class to use (injectable for testing with
+     *   unbundled Puppeteer to avoid class instance mismatch errors).
+     * @returns Initialized McpContext ready for use.
+     */
+    static async from(browser, logger, opts, locatorClass = Locator) {
         const context = new McpContext(browser, logger, opts, locatorClass);
         await context.#init();
         return context;
@@ -164,6 +311,14 @@ export class McpContext {
         }
         return this.#networkCollector.getIdForResource(request);
     }
+    /**
+     * Resolve a CDP backend node ID to a snapshot element UID.
+     *
+     * @param cdpBackendNodeId - The CDP backend node ID from DevTools.
+     * @returns The corresponding snapshot UID, or undefined if not found.
+     *
+     * @todo Optimize with a backendNodeId index instead of tree traversal.
+     */
     resolveCdpElementId(cdpBackendNodeId) {
         if (!cdpBackendNodeId) {
             this.logger('no cdpBackendNodeId');
@@ -173,7 +328,6 @@ export class McpContext {
             this.logger('no text snapshot');
             return;
         }
-        // TODO: index by backendNodeId instead.
         const queue = [this.#textSnapshot.root];
         while (queue.length) {
             const current = queue.pop();
@@ -206,6 +360,8 @@ export class McpContext {
         this.selectPage(page);
         this.#networkCollector.addPage(page);
         this.#consoleCollector.addPage(page);
+        // Set up WebMCP auto-detection for the new page
+        this.#setupWebMCPAutoDetection(page);
         return page;
     }
     async closePage(pageIdx) {
@@ -352,8 +508,21 @@ export class McpContext {
             this.selectPage(this.#pages[0]);
         }
         await this.detectOpenDevToolsWindows();
+        // Set up WebMCP auto-detection for any new pages
+        // (safe to call for existing pages - it checks if listeners are already installed)
+        for (const page of this.#pages) {
+            this.#setupWebMCPAutoDetection(page);
+        }
         return this.#pages;
     }
+    /**
+     * Detect and map open DevTools windows to their inspected pages.
+     *
+     * Iterates through all browser pages to find DevTools windows and
+     * associates them with the pages they're inspecting.
+     *
+     * @todo Optimize page lookup with a URL-indexed map instead of nested loops.
+     */
     async detectOpenDevToolsWindows() {
         this.logger('Detecting open DevTools windows');
         const pages = await this.browser.pages(this.#options.experimentalIncludeAllPages);
@@ -371,7 +540,6 @@ export class McpContext {
                     if (!urlLike) {
                         continue;
                     }
-                    // TODO: lookup without a loop.
                     for (const page of this.#pages) {
                         if (urlsEqual(page.url(), urlLike)) {
                             this.#pageToDevToolsPage.set(page, devToolsPage);
@@ -385,7 +553,7 @@ export class McpContext {
         }
     }
     getPages() {
-        return this.#pages;
+        return [...this.#pages];
     }
     getDevToolsPage(page) {
         return this.#pageToDevToolsPage.get(page);
@@ -554,17 +722,12 @@ export class McpContext {
             }
             this.#webMCPConnections.delete(targetPage);
         }
-        // Check if WebMCP is available
-        const hasWebMCP = await this.#checkWebMCPAvailable(targetPage);
-        if (!hasWebMCP) {
-            return { connected: false, error: 'WebMCP not detected on this page' };
-        }
-        // Connect
+        // Connect - no pre-checking needed (extension approach)
         try {
             const transport = new WebMCPClientTransport({
                 page: targetPage,
-                readyTimeout: 10000,
-                requireWebMCP: false, // We already checked
+                readyTimeout: 30000, // 30s to handle slow React apps (up from 10s)
+                requireWebMCP: false, // Don't pre-check, just try to connect
             });
             const client = new Client({ name: 'chrome-devtools-mcp', version: '1.0.0' }, { capabilities: {} });
             // Set up onclose handler to clean up connection state
@@ -574,10 +737,36 @@ export class McpContext {
                 if (currentConn?.client === client) {
                     this.#webMCPConnections.delete(targetPage);
                 }
+                // Remove tools for this page when transport closes
+                this.#toolHub?.removeToolsForPage(targetPage);
+            };
+            // Also listen for page close events to trigger cleanup
+            // This handles cases where the page is closed without navigation
+            const onPageClose = () => {
+                const currentConn = this.#webMCPConnections.get(targetPage);
+                if (currentConn?.client === client) {
+                    this.#webMCPConnections.delete(targetPage);
+                }
+                this.#toolHub?.removeToolsForPage(targetPage);
+                // Clean up the listener
+                targetPage.off('close', onPageClose);
             };
+            targetPage.on('close', onPageClose);
             await client.connect(transport);
             // Store connection for this page
             this.#webMCPConnections.set(targetPage, { client, transport, page: targetPage });
+            // Subscribe to tool list changes if tool hub is enabled and server supports it
+            const serverCapabilities = client.getServerCapabilities();
+            if (serverCapabilities?.tools?.listChanged && this.#toolHub?.isEnabled()) {
+                client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+                    this.logger('WebMCP tools changed, re-syncing...');
+                    await this.#toolHub?.syncToolsForPage(targetPage, client);
+                });
+            }
+            // Initial tool sync if tool hub is enabled
+            if (this.#toolHub?.isEnabled()) {
+                await this.#toolHub.syncToolsForPage(targetPage, client);
+            }
             return { connected: true, client };
         }
         catch (err) {
@@ -587,19 +776,6 @@ export class McpContext {
             };
         }
     }
-    /**
-     * Check if WebMCP is available on a page by checking the bridge's hasWebMCP() method.
-     * The bridge is auto-injected into all pages, so we just need to check if it detected WebMCP.
-     */
-    async #checkWebMCPAvailable(page) {
-        try {
-            const result = await page.evaluate(CHECK_WEBMCP_AVAILABLE_SCRIPT);
-            return result.available;
-        }
-        catch {
-            return false;
-        }
-    }
     /**
      * We need to ignore favicon request as they make our test flaky
      */

package/build/src/McpResponse.js

@@ -17,6 +17,7 @@ export class McpResponse {
     #attachedConsoleMessageId;
     #textResponseLines = [];
     #images = [];
+    #isError = false;
     #networkRequestsOptions;
     #consoleDataOptions;
     #devToolsData;
@@ -96,6 +97,12 @@ export class McpResponse {
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
     }
+    setIsError(value) {
+        this.#isError = value;
+    }
+    get isError() {
+        return this.#isError;
+    }
     attachImage(value) {
         this.#images.push(value);
     }

package/build/src/browser.js

@@ -8,7 +8,16 @@ import os from 'node:os';
 import path from 'node:path';
 import { logger } from './logger.js';
 import { puppeteer } from './third_party/index.js';
+/** Cached browser instance for reuse across calls. */
 let browser;
+/**
+ * Create a target filter for Puppeteer that excludes internal Chrome pages.
+ *
+ * Includes new tab and inspect pages (may be the only user-accessible page),
+ * but excludes chrome://, chrome-extension://, and chrome-untrusted:// pages.
+ *
+ * @returns A filter function for Puppeteer's targetFilter option.
+ */
 function makeTargetFilter() {
     const ignoredPrefixes = new Set([
         'chrome://',
@@ -19,7 +28,6 @@ function makeTargetFilter() {
         if (target.url() === 'chrome://newtab/') {
             return true;
         }
-        // Could be the only page opened in the browser.
         if (target.url().startsWith('chrome://inspect')) {
             return true;
         }
@@ -31,6 +39,19 @@ function makeTargetFilter() {
         return true;
     };
 }
+/**
+ * Connect to an existing Chrome browser instance.
+ *
+ * Connection priority:
+ * 1. wsEndpoint - Direct WebSocket connection with optional headers
+ * 2. browserURL - HTTP URL to Chrome's DevTools endpoint
+ * 3. userDataDir - Read DevToolsActivePort from profile directory
+ * 4. channel - Derive profile directory from channel name
+ *
+ * @param options - Connection options.
+ * @returns Connected browser instance.
+ * @throws Error if connection fails or no connection method specified.
+ */
 export async function ensureBrowserConnected(options) {
     const { channel } = options;
     if (browser?.connected) {
@@ -85,7 +106,32 @@ export async function ensureBrowserConnected(options) {
             if (!channel) {
                 throw new Error('Channel must be provided if userDataDir is missing');
             }
-            connectOptions.channel = (channel === 'stable' ? 'chrome' : `chrome-${channel}`);
+            // Derive the default userDataDir from the channel (same as launch does)
+            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 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 ${channel} channel in ${derivedUserDataDir}. Check if Chrome is running and was launched with remote debugging enabled.`, { cause: error });
+            }
         }
     }
     else {
@@ -103,6 +149,13 @@ export async function ensureBrowserConnected(options) {
     logger('Connected Puppeteer');
     return browser;
 }
+/**
+ * Launch a new Chrome browser instance.
+ *
+ * @param options - Launch configuration options.
+ * @returns Launched browser instance.
+ * @throws Error if Chrome is already running with the same profile.
+ */
 export async function launch(options) {
     const { channel, executablePath, headless, isolated } = options;
     const profileDirName = channel && channel !== 'stable'
@@ -115,10 +168,21 @@ export async function launch(options) {
             recursive: true,
         });
     }
+    const extraArgs = options.args ?? [];
+    const hasRemoteDebuggingPipe = extraArgs.includes('--remote-debugging-pipe');
+    const hasRemoteDebuggingPort = extraArgs.some(arg => arg.startsWith('--remote-debugging-port'));
+    const hasRemoteDebuggingAddress = extraArgs.some(arg => arg.startsWith('--remote-debugging-address'));
     const args = [
-        ...(options.args ?? []),
+        ...extraArgs,
         '--hide-crash-restore-bubble',
     ];
+    const enableRemoteDebuggingPort = !isolated && !hasRemoteDebuggingPipe && !hasRemoteDebuggingPort;
+    if (enableRemoteDebuggingPort) {
+        args.push('--remote-debugging-port=0');
+        if (!hasRemoteDebuggingAddress) {
+            args.push('--remote-debugging-address=127.0.0.1');
+        }
+    }
     if (headless) {
         args.push('--screen-info={3840x2160}');
     }
@@ -132,6 +196,8 @@ export async function launch(options) {
                 ? `chrome-${channel}`
                 : 'chrome';
     }
+    const usePipe = hasRemoteDebuggingPipe ||
+        (!hasRemoteDebuggingPort && !enableRemoteDebuggingPort);
     try {
         const browser = await puppeteer.launch({
             channel: puppeteerChannel,
@@ -139,7 +205,7 @@ export async function launch(options) {
             executablePath,
             defaultViewport: null,
             userDataDir,
-            pipe: true,
+            pipe: usePipe,
             headless,
             args,
             acceptInsecureCerts: options.acceptInsecureCerts,
@@ -171,6 +237,12 @@ export async function launch(options) {
         throw error;
     }
 }
+/**
+ * Ensure a browser is launched, reusing existing instance if connected.
+ *
+ * @param options - Launch configuration options.
+ * @returns Connected or newly launched browser instance.
+ */
 export async function ensureBrowserLaunched(options) {
     if (browser?.connected) {
         return browser;

package/build/src/cli.js

@@ -8,8 +8,7 @@ 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. Falls back to launching a new instance if no running browser is found.',
-        conflicts: ['isolated', 'executablePath'],
-        default: true,
+        default: false,
         coerce: (value) => {
             if (value === false) {
                 return false;