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

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
 
@@ -123,8 +123,8 @@ The AI can see the actual response, fix any bugs, and repeat until it works perf
 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`
+- **Discover** them through `diff_webmcp_tools`
+- **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)
+  - [`diff_webmcp_tools`](docs/tool-reference.md#diff_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.
@@ -807,20 +814,42 @@ Navigate to https://example.com/app
 What tools are available on this website?
 ```
 
-The AI agent will use `list_webmcp_tools` to show you what functionality the
+The AI agent will use `diff_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 `diff_webmcp_tools` to poll manually |
+| Cline | Partial | May need manual polling with `diff_webmcp_tools` |
+| Continue | Unknown | Use `diff_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 `diff_webmcp_tools` to manually see which tools are available, then call them directly by their prefixed names. The `diff_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
 
@@ -843,9 +872,9 @@ Call the website's form submission tool to fill out the contact form
 - **"WebMCP not detected"**: The current webpage doesn't have `@mcp-b/global`
   installed or no tools are registered. The page needs the WebMCP polyfill loaded.
 - **Tool call fails**: Check the tool's input schema matches your parameters.
-  Use `list_webmcp_tools` to see the expected input format.
+  Use `diff_webmcp_tools` to see the expected input format.
 - **Tools not appearing after navigation**: WebMCP auto-reconnects when you
-  navigate. If the new page has different tools, call `list_webmcp_tools` again.
+  navigate. If the new page has different tools, call `diff_webmcp_tools` again.
 
 ## Related Packages
 

package/build/src/McpContext.js

@@ -8,6 +8,7 @@ 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 { WebMCPClientTransport } from './transports/WebMCPClientTransport.js';
@@ -16,8 +17,16 @@ 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,122 @@ 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;
+            }
+            // Wait a bit for the page to initialize WebMCP
+            // The bridge script runs on DOMContentLoaded, and WebMCP may initialize after that
+            await new Promise(resolve => setTimeout(resolve, 500));
+            // Proactively check for WebMCP and sync tools
+            await this.#proactivelyDetectWebMCP(page);
+        };
+        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}`);
+    }
+    /**
+     * Proactively detect WebMCP on a page and sync tools if available.
+     * This is called after page navigation to automatically discover WebMCP tools.
+     */
+    async #proactivelyDetectWebMCP(page) {
+        // Skip if tool hub is not enabled
+        if (!this.#toolHub?.isEnabled()) {
+            return;
+        }
+        try {
+            // Check if WebMCP is available on the page
+            const hasWebMCP = await this.#checkWebMCPAvailable(page);
+            if (!hasWebMCP) {
+                this.logger(`No WebMCP detected on page: ${page.url()}`);
+                return;
+            }
+            this.logger(`WebMCP detected on page: ${page.url()}, connecting...`);
+            // Connect and sync tools - this handles everything including sending list_changed
+            const result = await this.getWebMCPClient(page);
+            if (result.connected) {
+                this.logger(`WebMCP tools synced for page: ${page.url()}`);
+            }
+            else {
+                this.logger(`Failed to connect to WebMCP: ${result.error}`);
+            }
+        }
+        catch (err) {
+            this.logger('Error during proactive WebMCP detection:', 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);
+            // Also do an initial check for existing pages
+            await this.#proactivelyDetectWebMCP(page);
+        }
+    }
+    /**
+     * 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 +305,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 +322,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 +354,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 +502,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 +534,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);
@@ -574,10 +736,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) {

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,7 +8,6 @@ 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,
         coerce: (value) => {
             if (value === false) {

package/build/src/main.js

@@ -16,7 +16,11 @@ import { McpServer, StdioServerTransport, SetLevelRequestSchema, } from './third
 import { registerPrompts } from './prompts/index.js';
 import { ToolCategory } from './tools/categories.js';
 import { tools } from './tools/tools.js';
-// If moved update release-please config
+import { WebMCPToolHub } from './tools/WebMCPToolHub.js';
+/**
+ * Package version (managed by release-please).
+ * @remarks If moved, update release-please config.
+ */
 // x-release-please-start-version
 const VERSION = '0.12.1';
 // x-release-please-end
@@ -30,13 +34,24 @@ const server = new McpServer({
     name: 'chrome_devtools',
     title: 'Chrome DevTools MCP server',
     version: VERSION,
-}, { capabilities: { logging: {}, prompts: {} } });
+}, { capabilities: { logging: {}, prompts: {}, tools: { listChanged: true } } });
 // Register WebMCP development prompts
 registerPrompts(server);
 server.server.setRequestHandler(SetLevelRequestSchema, () => {
     return {};
 });
+/** Cached McpContext instance for the current browser. */
 let context;
+/**
+ * Get or create the McpContext for browser operations.
+ *
+ * Handles browser connection/launch with the following priority:
+ * 1. Explicit browserUrl/wsEndpoint - connect directly
+ * 2. autoConnect enabled - try connecting, fall back to launching
+ * 3. Otherwise - launch a new browser
+ *
+ * @returns Initialized McpContext ready for tool operations.
+ */
 async function getContext() {
     const extraArgs = (args.chromeArg ?? []).map(String);
     if (args.proxyServer) {
@@ -105,15 +120,35 @@ async function getContext() {
             experimentalDevToolsDebugging: devtools,
             experimentalIncludeAllPages: args.experimentalIncludeAllPages,
         });
+        // Initialize WebMCP tool hub for dynamic tool registration
+        const toolHub = new WebMCPToolHub(server, context);
+        context.setToolHub(toolHub);
+        logger('WebMCPToolHub initialized for dynamic tool registration');
     }
     return context;
 }
+/**
+ * Log security disclaimers to stderr.
+ *
+ * Warns users that browser content is exposed to MCP clients.
+ */
 const logDisclaimers = () => {
     console.error(`chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
 debug, and modify any data in the browser or DevTools.
 Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
 };
+/**
+ * Mutex to serialize tool execution and prevent concurrent modifications.
+ */
 const toolMutex = new Mutex();
+/**
+ * Register a tool with the MCP server.
+ *
+ * Handles category-based filtering (emulation, performance, network)
+ * and wraps the handler with context initialization and error handling.
+ *
+ * @param tool - Tool definition to register.
+ */
 function registerTool(tool) {
     if (tool.annotations.category === ToolCategory.EMULATION &&
         args.categoryEmulation === false) {