chrome-devtools-mcp-for-extension 0.12.0 → 0.14.0

package/build/src/McpContext.js

@@ -10,6 +10,7 @@ import { NetworkCollector, PageCollector } from './PageCollector.js';
 import { listPages } from './tools/pages.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
 import { WaitForHelper } from './WaitForHelper.js';
+import { BrowserConnectionManager, } from './browser-connection-manager.js';
 const DEFAULT_TIMEOUT = 5_000;
 const NAVIGATION_TIMEOUT = 10_000;
 function getNetworkMultiplierFromString(condition) {
@@ -29,6 +30,7 @@ function getNetworkMultiplierFromString(condition) {
 export class McpContext {
     browser;
     logger;
+    connectionManager;
     // The most recent page state.
     #pages = [];
     #selectedPageIdx = 0;
@@ -42,9 +44,14 @@ export class McpContext {
     #dialog;
     #nextSnapshotId = 1;
     #traceResults = [];
-    constructor(browser, logger) {
+    constructor(browser, logger, browserFactory, connectionOptions) {
         this.browser = browser;
         this.logger = logger;
+        this.connectionManager = new BrowserConnectionManager(connectionOptions);
+        // Set up browser instance and factory for reconnection
+        if (browserFactory) {
+            this.connectionManager.setBrowser(browser, browserFactory);
+        }
         this.#networkCollector = new NetworkCollector(this.browser, (page, collect) => {
             page.on('request', request => {
                 collect(request);
@@ -65,11 +72,87 @@ export class McpContext {
         await this.#networkCollector.init();
         await this.#consoleCollector.init();
     }
-    static async from(browser, logger) {
-        const context = new McpContext(browser, logger);
+    static async from(browser, logger, browserFactory, connectionOptions) {
+        const context = new McpContext(browser, logger, browserFactory, connectionOptions);
         await context.#init();
         return context;
     }
+    /**
+     * Reinitialize CDP protocol domains after reconnection
+     * This ensures proper CDP event handling after browser restart
+     */
+    async reinitializeCDP() {
+        try {
+            // Get CDP client from the browser
+            const client = await this.browser._client();
+            if (!client) {
+                this.logger('Warning: Unable to get CDP client for reinitialization');
+                return;
+            }
+            // 1. Enable Target discovery and auto-attach
+            // This is critical for multi-target scenarios (iframes, workers, etc.)
+            try {
+                await client.send('Target.setDiscoverTargets', { discover: true });
+                this.logger('CDP: Target discovery enabled');
+            }
+            catch (err) {
+                this.logger('Warning: Failed to enable target discovery:', err);
+            }
+            try {
+                await client.send('Target.setAutoAttach', {
+                    autoAttach: true,
+                    waitForDebuggerOnStart: false,
+                    flatten: true
+                });
+                this.logger('CDP: Auto-attach configured');
+            }
+            catch (err) {
+                this.logger('Warning: Failed to configure auto-attach:', err);
+            }
+            // 2. Enable essential CDP domains for each page
+            const pages = await this.browser.pages();
+            for (const page of pages) {
+                try {
+                    const pageClient = page._client();
+                    if (pageClient) {
+                        // Enable Network domain for request interception
+                        await pageClient.send('Network.enable');
+                        // Enable Runtime domain for console messages and exceptions
+                        await pageClient.send('Runtime.enable');
+                        // Enable Log domain for browser logs
+                        await pageClient.send('Log.enable');
+                        this.logger(`CDP domains enabled for page: ${page.url()}`);
+                    }
+                }
+                catch (err) {
+                    this.logger(`Warning: Failed to enable CDP domains for page ${page.url()}:`, err);
+                }
+            }
+            this.logger('CDP protocol reinitialization completed');
+        }
+        catch (err) {
+            this.logger('Error during CDP reinitialization:', err);
+            // Don't throw - this is a best-effort operation
+            // The browser should still be usable even if CDP setup partially fails
+        }
+    }
+    /**
+     * Update browser instance after reconnection
+     */
+    async updateBrowser(newBrowser) {
+        this.browser = newBrowser;
+        this.connectionManager.setBrowser(newBrowser, async () => newBrowser);
+        // Reinitialize CDP protocol domains BEFORE collectors
+        // This ensures CDP events are properly set up
+        await this.reinitializeCDP();
+        // Reinitialize collectors for new browser
+        await this.#networkCollector.init();
+        await this.#consoleCollector.init();
+        // Recreate pages snapshot
+        await this.createPagesSnapshot();
+        this.setSelectedPageIdx(0);
+        this.logger('Browser instance updated after reconnection');
+    }
     getNetworkRequests() {
         const page = this.getSelectedPage();
         return this.#networkCollector.getData(page);

package/build/src/browser-connection-manager.js

@@ -0,0 +1,356 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ProtocolError, TimeoutError } from 'puppeteer';
+/**
+ * Default connection manager options
+ */
+const DEFAULT_OPTIONS = {
+    maxReconnectAttempts: 3,
+    initialRetryDelay: 1000, // 1 second
+    maxRetryDelay: 10000, // 10 seconds
+    enableLogging: true,
+    onReconnect: undefined,
+};
+/**
+ * Connection state enum
+ */
+var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["CONNECTED"] = "CONNECTED";
+    ConnectionState["RECONNECTING"] = "RECONNECTING";
+    ConnectionState["CLOSED"] = "CLOSED";
+})(ConnectionState || (ConnectionState = {}));
+/**
+ * Browser Connection Manager
+ *
+ * Provides automatic reconnection for CDP operations with:
+ * - Single-flight pattern to prevent concurrent reconnections
+ * - Event-driven detection via browser 'disconnected' event
+ * - State machine tracking (CONNECTED | RECONNECTING | CLOSED)
+ * - Exponential backoff with jitter to prevent thundering herd
+ */
+export class BrowserConnectionManager {
+    reconnectAttempts = 0;
+    options;
+    browser = null;
+    browserFactory = null;
+    /** Single-flight pattern: prevents concurrent reconnection attempts */
+    reconnectInFlight = null;
+    /** Shared reconnection sequence for multiple operations */
+    reconnectSequenceInFlight = null;
+    /** Current connection state */
+    state = ConnectionState.CLOSED;
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Set browser instance and factory for reconnection
+     *
+     * @param browser - Browser instance to manage
+     * @param factory - Factory function to create new browser instances on reconnection
+     */
+    setBrowser(browser, factory) {
+        this.browser = browser;
+        this.browserFactory = factory;
+        this.state = ConnectionState.CONNECTED;
+        // Event-driven detection: hook into browser 'disconnected' event
+        this.browser.on('disconnected', () => {
+            this.log('Browser disconnected event fired');
+            this.setState(ConnectionState.CLOSED);
+            // Trigger immediate reconnection (will be handled by next operation)
+        });
+        this.log('Browser instance set, state: CONNECTED');
+    }
+    /**
+     * Execute an operation with automatic retry on CDP connection errors
+     */
+    async executeWithRetry(operation, operationName) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (this.isCDPConnectionError(error)) {
+                this.log(`CDP connection error in ${operationName}, attempting reconnect...`);
+                return await this.retryWithReconnect(operation, operationName);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Retry operation with exponential backoff and jitter
+     *
+     * Implements single-flight pattern at the sequence level:
+     * - Multiple concurrent operations share the same reconnection sequence
+     * - Only one reconnection sequence runs at a time
+     * - All waiting operations retry after the shared sequence completes
+     *
+     * Adds ±20% randomness to retry delays to prevent thundering herd problem.
+     *
+     * @param operation - Operation to retry
+     * @param operationName - Name of operation for logging
+     * @returns Result of operation
+     */
+    async retryWithReconnect(operation, operationName) {
+        // Single-flight pattern: if a reconnection sequence is already running,
+        // wait for it to complete, then try the operation once
+        if (this.reconnectSequenceInFlight) {
+            this.log(`${operationName}: Waiting for ongoing reconnection sequence...`);
+            try {
+                await this.reconnectSequenceInFlight;
+                this.log(`${operationName}: Reconnection sequence completed, retrying operation...`);
+                return await operation();
+            }
+            catch (error) {
+                // Reconnection sequence failed, propagate the error
+                throw error;
+            }
+        }
+        // Start a new reconnection sequence
+        this.reconnectSequenceInFlight = this._runReconnectionSequence();
+        try {
+            await this.reconnectSequenceInFlight;
+            this.log(`${operationName}: Reconnection sequence completed, retrying operation...`);
+            return await operation();
+        }
+        catch (error) {
+            throw error;
+        }
+        finally {
+            // Clear the in-flight sequence
+            this.reconnectSequenceInFlight = null;
+        }
+    }
+    /**
+     * Run a full reconnection sequence with exponential backoff
+     *
+     * This is the actual retry loop that multiple operations can share.
+     *
+     * @private
+     */
+    async _runReconnectionSequence() {
+        const maxAttempts = this.options.maxReconnectAttempts ?? 3;
+        const initialDelay = this.options.initialRetryDelay ?? 1000;
+        const maxDelay = this.options.maxRetryDelay ?? 10000;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            this.reconnectAttempts++;
+            const attemptNum = attempt + 1;
+            this.log(`Reconnect attempt ${attemptNum}/${maxAttempts}...`);
+            // Exponential backoff with max delay
+            const baseDelay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
+            // Add jitter: ±20% randomness to prevent thundering herd
+            const jitter = baseDelay * 0.2 * (Math.random() * 2 - 1);
+            const delay = Math.max(0, baseDelay + jitter);
+            this.log(`Waiting ${delay.toFixed(0)}ms before reconnect attempt...`);
+            await this.sleep(delay);
+            try {
+                await this.reconnectBrowser();
+                this.log(`Reconnection successful`);
+                return; // Success!
+            }
+            catch (error) {
+                if (attempt === maxAttempts - 1) {
+                    // Last attempt failed
+                    throw this.createReconnectionFailedError(attemptNum, error);
+                }
+                this.log(`Reconnect attempt ${attemptNum} failed: ${error}`);
+            }
+        }
+        throw new Error('Reconnection logic error'); // Should never reach here
+    }
+    /**
+     * Check if error is a CDP connection error
+     *
+     * Uses type-safe error detection with instanceof checks and falls back
+     * to string matching for compatibility.
+     *
+     * @param error - Error to check
+     * @returns true if error is a CDP connection error
+     */
+    isCDPConnectionError(error) {
+        // Type-safe detection using instanceof
+        if (error instanceof ProtocolError || error instanceof TimeoutError) {
+            return true;
+        }
+        // Fallback: string matching for error messages
+        const errorMessage = error?.message || '';
+        return (errorMessage.includes('Target closed') ||
+            errorMessage.includes('Protocol error') ||
+            errorMessage.includes('Session closed') ||
+            errorMessage.includes('Connection closed') ||
+            errorMessage.includes('WebSocket is not open'));
+    }
+    /**
+     * Reconnect browser instance with single-flight pattern
+     *
+     * Ensures only one reconnection attempt happens at a time.
+     * Multiple concurrent calls will wait for the same reconnection promise.
+     *
+     * @returns Promise that resolves when reconnection is complete
+     */
+    async reconnectBrowser() {
+        // Single-flight pattern: return existing promise if reconnection is already in progress
+        if (this.reconnectInFlight) {
+            this.log('Reconnection already in progress, waiting...');
+            return this.reconnectInFlight;
+        }
+        // Create new reconnection promise
+        this.reconnectInFlight = this._doReconnect();
+        try {
+            await this.reconnectInFlight;
+        }
+        finally {
+            // Clear in-flight promise when complete
+            this.reconnectInFlight = null;
+        }
+    }
+    /**
+     * Internal reconnection logic
+     *
+     * @private
+     */
+    async _doReconnect() {
+        if (!this.browserFactory) {
+            throw new Error('Browser factory not set. Cannot reconnect.');
+        }
+        this.setState(ConnectionState.RECONNECTING);
+        try {
+            // Close old browser if still connected
+            if (this.browser?.isConnected()) {
+                await this.browser.close().catch(() => {
+                    // Ignore errors during close
+                });
+            }
+        }
+        catch (error) {
+            // Ignore errors during cleanup
+        }
+        // Create new browser instance
+        const newBrowser = await this.browserFactory();
+        this.browser = newBrowser;
+        // Re-attach disconnected event handler
+        this.browser.on('disconnected', () => {
+            this.log('Browser disconnected event fired');
+            this.setState(ConnectionState.CLOSED);
+        });
+        this.setState(ConnectionState.CONNECTED);
+        this.log('Browser reconnected successfully');
+        // Notify callback if provided
+        if (this.options.onReconnect) {
+            await this.options.onReconnect(newBrowser);
+        }
+    }
+    /**
+     * Create user-friendly error for reconnection failure
+     */
+    createReconnectionFailedError(attempts, lastError) {
+        const message = `
+❌ Chrome DevTools接続エラー
+
+${attempts}回の再接続を試みましたが、Chrome DevToolsとの接続を回復できませんでした。
+
+📋 最後のエラー:
+${lastError?.message || 'Unknown error'}
+
+🔧 解決方法:
+1. Claude Codeを再起動してください
+2. Chromeブラウザを完全に終了して再起動してください
+3. chrome://extensions でChrome DevTools拡張機能を確認してください
+
+詳細: docs/troubleshooting.md#cdp-connection-error
+    `.trim();
+        const error = new Error(message);
+        error.name = 'CDPReconnectionError';
+        return error;
+    }
+    /**
+     * Set connection state and log transition
+     *
+     * @param newState - New connection state
+     */
+    setState(newState) {
+        if (this.state !== newState) {
+            this.log(`State transition: ${this.state} -> ${newState}`);
+            this.state = newState;
+        }
+    }
+    /**
+     * Log message if logging is enabled
+     *
+     * @param message - Message to log
+     */
+    log(message) {
+        if (this.options.enableLogging !== false) {
+            console.log(`[ConnectionManager] ${message}`);
+        }
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Get current browser instance
+     */
+    getBrowser() {
+        return this.browser;
+    }
+    /**
+     * Get total reconnection attempts made
+     */
+    getReconnectAttempts() {
+        return this.reconnectAttempts;
+    }
+    /**
+     * Reset reconnection attempt counter
+     */
+    resetReconnectAttempts() {
+        this.reconnectAttempts = 0;
+    }
+    /**
+     * Check if browser is currently connected
+     *
+     * @returns true if browser is connected
+     */
+    isConnected() {
+        return this.browser?.isConnected() ?? false;
+    }
+    /**
+     * Get current connection state
+     *
+     * @returns Current connection state (CONNECTED | RECONNECTING | CLOSED)
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Check if reconnection is currently in progress
+     *
+     * @returns true if reconnection is in progress
+     */
+    isReconnecting() {
+        return this.state === ConnectionState.RECONNECTING;
+    }
+}
+/**
+ * Global connection manager instance
+ */
+let globalConnectionManager = null;
+/**
+ * Get or create global connection manager
+ */
+export function getConnectionManager(options) {
+    if (!globalConnectionManager) {
+        globalConnectionManager = new BrowserConnectionManager(options);
+    }
+    return globalConnectionManager;
+}
+/**
+ * Reset global connection manager (for testing)
+ */
+export function resetConnectionManager() {
+    globalConnectionManager = null;
+}

package/build/src/main.js

@@ -60,7 +60,7 @@ server.server.setRequestHandler(SetLevelRequestSchema, () => {
 let context;
 let uiHealthCheckRun = false; // Track if UI health check has been run
 async function getContext() {
-    const browser = await resolveBrowser({
+    const browserOptions = {
         browserUrl: args.browserUrl,
         headless: args.headless,
         executablePath: args.executablePath,
@@ -73,10 +73,23 @@ async function getContext() {
         chromeProfile: args.chromeProfile,
         userDataDir: args.userDataDir,
         logFile,
-    });
+    };
+    const browser = await resolveBrowser(browserOptions);
+    // Browser factory function for reconnection
+    const browserFactory = async () => {
+        logger('Reconnecting browser...');
+        return await resolveBrowser(browserOptions);
+    };
     // Always recreate context if browser reference changed or context doesn't exist
     if (!context || context.browser !== browser) {
-        context = await McpContext.from(browser, logger);
+        // Connection manager options with reconnect callback
+        const connectionOptions = {
+            onReconnect: async (newBrowser) => {
+                logger('Updating context with reconnected browser...');
+                await context.updateBrowser(newBrowser);
+            },
+        };
+        context = await McpContext.from(browser, logger, browserFactory, connectionOptions);
         // Run UI health check only once per browser instance
         if (!uiHealthCheckRun) {
             uiHealthCheckRun = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp-for-extension",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "MCP server for Chrome extension development with Web Store automation. Fork of chrome-devtools-mcp with extension-specific tools.",
   "type": "module",
   "bin": "./build/src/index.js",