@mcp-b/chrome-devtools-mcp 1.6.2 → 1.6.3

package/build/src/McpContext.js

@@ -167,8 +167,10 @@ export class McpContext {
                     }
                     await page.evaluate(WEB_MCP_BRIDGE_SCRIPT);
                 }
-                catch {
-                    // Page might not be ready or accessible, ignore
+                catch (err) {
+                    // Page might not be ready or accessible - log for debugging
+                    const message = err instanceof Error ? err.message : String(err);
+                    this.logger(`Bridge injection skipped for ${page.url()}: ${message}`);
                 }
             }
             this.logger('WebMCP bridge injected into existing pages');
@@ -191,7 +193,10 @@ export class McpContext {
         this.#toolHub = hub;
         // Trigger auto-detection for all existing pages asynchronously
         this.#setupWebMCPAutoDetectionForAllPages().catch(err => {
-            this.logger('Error setting up WebMCP auto-detection:', err);
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger(`WebMCP auto-detection setup failed: ${message}`);
+            // Note: This is non-fatal - individual page connections may still work
+            // when explicitly requested via getWebMCPClient()
         });
     }
     /**
@@ -202,11 +207,23 @@ export class McpContext {
     }
     /**
      * Get or create a browser-level CDP session for window operations.
+     * Recreates the session if it has become invalid.
      */
     async #getBrowserCdpSession() {
-        if (!this.#browserCdpSession) {
-            this.#browserCdpSession = await this.browser.target().createCDPSession();
+        if (this.#browserCdpSession) {
+            // Verify session is still valid by attempting a simple operation
+            try {
+                await this.#browserCdpSession.send('Browser.getVersion');
+                return this.#browserCdpSession;
+            }
+            catch (err) {
+                // Session is stale, recreate it
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger(`Browser CDP session stale (${message}), recreating...`);
+                this.#browserCdpSession = undefined;
+            }
         }
+        this.#browserCdpSession = await this.browser.target().createCDPSession();
         return this.#browserCdpSession;
     }
     /**
@@ -235,6 +252,44 @@ export class McpContext {
     getSessionWindowId() {
         return this.#sessionWindowId;
     }
+    /**
+     * Close all pages in the session's window.
+     * Called during cleanup when the MCP server is shutting down.
+     */
+    async closeSessionWindow() {
+        if (this.#sessionWindowId === undefined) {
+            this.logger('No session window to close');
+            return;
+        }
+        this.logger(`Closing session window ${this.#sessionWindowId}...`);
+        // Get all pages in this session's window and close them
+        const pagesToClose = [...this.#pages];
+        for (const page of pagesToClose) {
+            try {
+                if (!page.isClosed()) {
+                    await page.close();
+                }
+            }
+            catch (err) {
+                // Ignore errors during cleanup - page might already be closed
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger(`Error closing page during cleanup: ${message}`);
+            }
+        }
+        // Clean up the CDP session
+        if (this.#browserCdpSession) {
+            try {
+                await this.#browserCdpSession.detach();
+            }
+            catch (err) {
+                // Detach errors during cleanup are expected - log for debugging
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger(`CDP detach during cleanup: ${message}`);
+            }
+            this.#browserCdpSession = undefined;
+        }
+        this.logger('Session window closed');
+    }
     /**
      * Set up automatic WebMCP detection for a page.
      * This installs listeners that detect WebMCP after navigation and sync tools.
@@ -270,7 +325,17 @@ export class McpContext {
             // 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);
+                const message = err instanceof Error ? err.message : String(err);
+                // Differentiate expected timeouts from unexpected errors
+                const isExpected = message.includes('timeout') ||
+                    message.includes('WebMCP not detected') ||
+                    message.includes('server did not respond');
+                if (isExpected) {
+                    this.logger(`No WebMCP detected after navigation: ${page.url()}`);
+                }
+                else {
+                    this.logger(`Unexpected WebMCP connection error for ${page.url()}: ${message}`);
+                }
             });
         };
         page.on('framenavigated', onFrameNavigated);
@@ -324,7 +389,17 @@ export class McpContext {
             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);
+                const message = err instanceof Error ? err.message : String(err);
+                // Differentiate expected timeouts from unexpected errors
+                const isExpected = message.includes('timeout') ||
+                    message.includes('WebMCP not detected') ||
+                    message.includes('server did not respond');
+                if (isExpected) {
+                    this.logger(`No WebMCP on page during initial scan: ${page.url()}`);
+                }
+                else {
+                    this.logger(`Unexpected error during initial WebMCP scan for ${page.url()}: ${message}`);
+                }
             });
         }
     }
@@ -412,8 +487,10 @@ export class McpContext {
                     await existingPage.bringToFront();
                 }
             }
-            catch {
+            catch (err) {
                 // Best effort - focus might fail if page is closing
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger(`Window focus failed (non-critical): ${message}`);
             }
         }
         const page = await this.browser.newPage();
@@ -427,8 +504,10 @@ export class McpContext {
                         `Tab may not be visible in list_pages.`);
                 }
             }
-            catch {
+            catch (err) {
                 // Failed to get windowId - page might be in an unexpected state
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger(`Window ID check failed (non-critical): ${message}`);
             }
         }
         await this.createPagesSnapshot();
@@ -631,6 +710,10 @@ export class McpContext {
      */
     async createPagesSnapshot() {
         const allPages = await this.browser.pages(this.#options.experimentalIncludeAllPages);
+        this.logger(`createPagesSnapshot: found ${allPages.length} total pages`);
+        for (const page of allPages) {
+            this.logger(`  - ${page.url()}`);
+        }
         // First filter: DevTools pages (unless experimental mode is enabled)
         let filteredPages = allPages.filter(page => {
             return (this.#options.experimentalDevToolsDebugging ||
@@ -642,23 +725,50 @@ export class McpContext {
             const windowFilteredPages = [];
             // Check window IDs in parallel for better performance
             const windowIdResults = await Promise.allSettled(filteredPages.map(async (page) => {
-                try {
-                    const windowId = await this.getWindowIdForPage(page);
-                    return { page, windowId };
+                // Try to get windowId with retry for pages that might be in transitional state
+                let windowId = null;
+                let lastError = null;
+                for (let attempt = 0; attempt < 3; attempt++) {
+                    try {
+                        windowId = await this.getWindowIdForPage(page);
+                        break; // Success, exit retry loop
+                    }
+                    catch (err) {
+                        lastError = err instanceof Error ? err.message : String(err);
+                        if (attempt < 2) {
+                            // Wait before retry (50ms, then 100ms)
+                            await new Promise(r => setTimeout(r, 50 * (attempt + 1)));
+                        }
+                    }
                 }
-                catch {
-                    // Page might be closing, exclude it
-                    return null;
+                if (windowId !== null) {
+                    return { page, windowId, url: page.url() };
                 }
+                // All retries failed
+                this.logger(`Failed to get windowId for page ${page.url()} after 3 attempts: ${lastError}`);
+                return null;
             }));
             for (const result of windowIdResults) {
-                if (result.status === 'fulfilled' &&
-                    result.value &&
-                    result.value.windowId === this.#sessionWindowId) {
-                    windowFilteredPages.push(result.value.page);
+                if (result.status === 'fulfilled' && result.value) {
+                    if (result.value.windowId === this.#sessionWindowId) {
+                        windowFilteredPages.push(result.value.page);
+                    }
+                    else {
+                        this.logger(`Excluding page ${result.value.url} (windowId ${result.value.windowId} != session ${this.#sessionWindowId})`);
+                    }
                 }
             }
             filteredPages = windowFilteredPages;
+            this.logger(`Window filter: ${windowFilteredPages.length} pages in session window ${this.#sessionWindowId}`);
+            // Always include the explicitly selected page even if window filtering excluded it
+            // This handles edge cases where windowId lookup fails after cross-origin navigation
+            if (this.#pageExplicitlySelected &&
+                this.#selectedPage &&
+                !this.#selectedPage.isClosed() &&
+                !filteredPages.includes(this.#selectedPage)) {
+                this.logger(`Re-adding explicitly selected page that was filtered out: ${this.#selectedPage.url()}`);
+                filteredPages.unshift(this.#selectedPage);
+            }
         }
         this.#pages = filteredPages;
         // Only auto-select pages[0] if:
@@ -709,7 +819,8 @@ export class McpContext {
                     }
                 }
                 catch (error) {
-                    this.logger('Issue occurred while trying to find DevTools', error);
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.logger(`DevTools detection failed for ${devToolsPage.url()}: ${message}`);
                 }
             }
         }
@@ -879,8 +990,10 @@ export class McpContext {
             try {
                 await conn.client.close();
             }
-            catch {
-                // Ignore close errors
+            catch (err) {
+                // Close errors during reconnection are expected - log for debugging
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger(`WebMCP client close during reconnection: ${message}`);
             }
             this.#webMCPConnections.delete(targetPage);
         }

package/build/src/main.js

@@ -27,6 +27,39 @@ const VERSION = '1.5.6';
 process.on('unhandledRejection', (reason, promise) => {
     logger('Unhandled promise rejection', promise, reason);
 });
+/**
+ * Cleanup handler for graceful shutdown.
+ * Closes the session window when the MCP server is killed.
+ */
+let isCleaningUp = false;
+async function cleanup() {
+    if (isCleaningUp)
+        return;
+    isCleaningUp = true;
+    logger('Shutting down MCP server...');
+    if (context) {
+        try {
+            await context.closeSessionWindow();
+        }
+        catch (err) {
+            logger('Error during cleanup:', err);
+        }
+    }
+    process.exit(0);
+}
+// Handle various termination signals
+process.on('SIGINT', () => {
+    logger('Received SIGINT');
+    cleanup();
+});
+process.on('SIGTERM', () => {
+    logger('Received SIGTERM');
+    cleanup();
+});
+process.on('SIGHUP', () => {
+    logger('Received SIGHUP');
+    cleanup();
+});
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
 logger(`Starting Chrome DevTools MCP Server v${VERSION}`);

package/build/src/tools/WebMCPToolHub.js

@@ -79,8 +79,10 @@ export class WebMCPToolHub {
             return this.#applyToolChanges(page, tools);
         }
         catch (err) {
-            this.#logger('Failed to sync WebMCP tools:', err);
-            return { synced: 0, removed: 0, updated: 0 };
+            const message = err instanceof Error ? err.message : String(err);
+            this.#logger(`Failed to sync WebMCP tools: ${message}`);
+            // Return error indicator so callers know sync failed vs "no tools found"
+            return { synced: 0, removed: 0, updated: 0, error: message };
         }
         finally {
             this.#syncInProgress.delete(page);
@@ -305,7 +307,12 @@ export function extractDomain(url) {
             : hostname;
         return sanitizeName(domain);
     }
-    catch {
+    catch (err) {
+        // Log at debug level for troubleshooting malformed URLs
+        if (typeof console !== 'undefined' && console.debug) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.debug(`[WebMCPToolHub] Failed to extract domain from URL "${url}": ${message}`);
+        }
         return 'unknown';
     }
 }

package/build/src/tools/webmcp.js

@@ -368,7 +368,29 @@ export const callWebMCPTool = defineTool({
                     }
                 }
             }
-            response.appendResponseLine(`Failed to call tool: ${errorMessage}`);
+            // Classify errors and provide actionable guidance
+            if (errorMessage.includes('timeout') || errorMessage.includes('Timeout')) {
+                response.appendResponseLine(`Tool call timed out: ${name}`);
+                response.appendResponseLine('');
+                response.appendResponseLine('The page may be unresponsive. Try:');
+                response.appendResponseLine('  1. Refresh the page with navigate_page({ type: "reload" })');
+                response.appendResponseLine('  2. Check list_console_messages for JavaScript errors');
+            }
+            else if (errorMessage.includes('validation') || errorMessage.includes('schema')) {
+                response.appendResponseLine(`Tool argument validation failed: ${errorMessage}`);
+                response.appendResponseLine('');
+                response.appendResponseLine('Check the tool schema with list_webmcp_tools to see expected arguments.');
+            }
+            else if (errorMessage.includes('not found') || errorMessage.includes('No such tool')) {
+                response.appendResponseLine(`Tool not found: ${name}`);
+                response.appendResponseLine('');
+                response.appendResponseLine('The tool may have been unregistered. Use list_webmcp_tools to see available tools.');
+            }
+            else {
+                response.appendResponseLine(`Failed to call tool: ${errorMessage}`);
+                response.appendResponseLine('');
+                response.appendResponseLine('For debugging, check list_console_messages for page errors.');
+            }
             response.setIsError(true);
         }
     },

package/build/src/transports/WebMCPClientTransport.js

@@ -59,6 +59,8 @@ export class WebMCPClientTransport {
     _frameNavigatedHandler = null;
     /** Bound handler for CDP binding calls (stored for cleanup). */
     _bindingCalledHandler = null;
+    /** Guards against concurrent navigation handling. */
+    _navigationInProgress = false;
     /** Callback invoked when transport is closed. */
     onclose;
     /** Callback invoked when an error occurs. */
@@ -190,8 +192,13 @@ export class WebMCPClientTransport {
             };
             this._frameNavigatedHandler = (frame) => {
                 if (frame === this._page.mainFrame()) {
-                    // Main frame navigated, bridge is gone
-                    this._handleNavigation();
+                    // Main frame navigated - check if bridge survived (SPA navigation)
+                    this._handleNavigation().catch((err) => {
+                        // Log navigation handling errors for debugging
+                        const message = err instanceof Error ? err.message : String(err);
+                        const logFn = console.debug || console.log;
+                        logFn('[WebMCPClientTransport] Navigation handling error:', message);
+                    });
                 }
             };
             // Listen for binding calls (messages from bridge → this transport)
@@ -272,31 +279,72 @@ export class WebMCPClientTransport {
         }
     }
     /**
-     * Handle page navigation - bridge is lost
+     * Handle page navigation - check if OUR BRIDGE survived (SPA navigation)
      *
-     * Navigation is a normal lifecycle event in browsers, not a fatal error.
-     * We perform full teardown (detach CDP session, remove listeners) and
-     * allow the client to reconnect by creating a new transport instance.
+     * The `framenavigated` event fires for BOTH:
+     * 1. Full page navigations (where the bridge IS destroyed)
+     * 2. Client-side SPA navigations via History API (where the bridge survives)
+     *
+     * For SPA navigations (React Router, TanStack Router, Next.js, etc.),
+     * the page doesn't actually reload - only the URL changes.
+     * The injected bridge script remains intact and functional.
+     *
+     * IMPORTANT: We check for OUR bridge (window.__mcpCdpBridge), not just the
+     * page's WebMCP availability. A full navigation to another WebMCP page would
+     * have a new TabServerTransport but our bridge would be destroyed.
      */
-    _handleNavigation() {
-        if (this._closed)
+    async _handleNavigation() {
+        // Guard against concurrent navigation handling
+        if (this._closed || this._navigationInProgress)
             return;
-        this._serverReady = false;
-        this._closed = true;
-        this._started = false;
-        // Reject any pending server ready promise (safe - has attached catch handler)
-        if (!this._serverReadyRejected) {
-            this._serverReadyReject(new Error('Page navigated, connection lost'));
+        this._navigationInProgress = true;
+        try {
+            // Give the page a moment to settle after navigation
+            // This helps with rapid SPA navigations
+            await new Promise(resolve => setTimeout(resolve, 50));
+            // Re-check closed state after the wait (could have been closed during delay)
+            if (this._closed)
+                return;
+            // Check if OUR BRIDGE survived the navigation (not just the page's WebMCP)
+            // This distinguishes SPA navigation from full navigation to another WebMCP page
+            try {
+                const bridgeAlive = await this._page.evaluate((bridgeProp) => {
+                    return !!window[bridgeProp];
+                }, CDP_BRIDGE_WINDOW_PROPERTY);
+                if (bridgeAlive) {
+                    // Our bridge survived - this was an SPA navigation, don't close
+                    const logFn = console.debug || console.log;
+                    logFn('[WebMCPClientTransport] Bridge survived navigation (SPA), keeping connection open');
+                    return;
+                }
+            }
+            catch {
+                // Evaluation failed - page context is gone, proceed with close
+            }
+            // Re-check closed state (could have been closed during bridge check)
+            if (this._closed)
+                return;
+            // Bridge is lost - full navigation occurred
+            this._serverReady = false;
+            this._closed = true;
+            this._started = false;
+            // Reject any pending server ready promise (safe - has attached catch handler)
+            if (!this._serverReadyRejected) {
+                this._serverReadyReject(new Error('Page navigated, connection lost'));
+            }
+            // Full teardown - detach CDP session and remove listeners
+            this._cleanup().catch((err) => {
+                // Cleanup errors during navigation are expected and non-critical
+                const message = err instanceof Error ? err.message : String(err);
+                const logFn = console.debug || console.log;
+                logFn('[WebMCPClientTransport] Cleanup error during navigation (non-critical):', message);
+            });
+            // Signal clean disconnection (not an error)
+            this.onclose?.();
+        }
+        finally {
+            this._navigationInProgress = false;
         }
-        // Full teardown - detach CDP session and remove listeners
-        this._cleanup().catch((err) => {
-            // Cleanup errors during navigation are expected and non-critical
-            const message = err instanceof Error ? err.message : String(err);
-            const logFn = console.debug || console.log;
-            logFn('[WebMCPClientTransport] Cleanup error during navigation (non-critical):', message);
-        });
-        // Signal clean disconnection (not an error)
-        this.onclose?.();
     }
     /**
      * Handle server stopped signal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-b/chrome-devtools-mcp",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "MCP server for Chrome DevTools with WebMCP integration for connecting to website MCP tools",
   "keywords": [
     "mcp",