@mcp-b/chrome-devtools-mcp 1.6.2 → 1.7.0-canary.20260214192802

package/README.md

@@ -8,7 +8,7 @@
 [![27 Tools](https://img.shields.io/badge/MCP_Tools-27-green?style=flat-square)](./docs/tool-reference.md)
 [![Chrome](https://img.shields.io/badge/Chrome-DevTools-4285F4?style=flat-square&logo=googlechrome)](https://developer.chrome.com/docs/devtools/)
 
-📖 **[WebMCP Documentation](https://docs.mcp-b.ai)** | 🚀 **[Quick Start](https://docs.mcp-b.ai/quickstart)** | 🔌 **[Connecting Agents](https://docs.mcp-b.ai/connecting-agents)** | 🎯 **[Chrome DevTools Quickstart](https://github.com/WebMCP-org/chrome-devtools-quickstart)**
+**[WebMCP Documentation](https://docs.mcp-b.ai)** | **[Quick Start](https://docs.mcp-b.ai/quickstart)** | **[Connecting Agents](https://docs.mcp-b.ai/connecting-agents)** | **[Chrome DevTools Quickstart](https://github.com/WebMCP-org/chrome-devtools-quickstart)**
 
 **@mcp-b/chrome-devtools-mcp** lets AI coding agents like Claude, Gemini, Cursor, and Copilot control and inspect a live Chrome browser via the Model Context Protocol (MCP). Get performance insights, debug network requests, take screenshots, and interact with website-specific MCP tools through WebMCP integration.
 
@@ -48,13 +48,13 @@ This fork adds **WebMCP integration** - the ability to call MCP tools that are r
 
 | Feature | Chrome DevTools MCP | @mcp-b/chrome-devtools-mcp |
 |---------|--------------------|-----------------------------|
-| Browser automation | ✅ | ✅ |
-| Performance analysis | ✅ | ✅ |
-| Network inspection | ✅ | ✅ |
-| Screenshot/snapshot | ✅ | ✅ |
-| **Call website MCP tools** | ❌ | ✅ |
-| **List website MCP tools** | ❌ | ✅ |
-| **AI-driven tool development** | ❌ | ✅ |
+| Browser automation | Yes | Yes |
+| Performance analysis | Yes | Yes |
+| Network inspection | Yes | Yes |
+| Screenshot/snapshot | Yes | Yes |
+| **Call website MCP tools** | No | Yes |
+| **List website MCP tools** | No | Yes |
+| **AI-driven tool development** | No | Yes |
 
 The key addition is automatic WebMCP tool discovery and registration. When you visit a page with [@mcp-b/global](https://www.npmjs.com/package/@mcp-b/global), its tools are automatically registered as first-class MCP tools that your AI agent can call directly.
 

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}`);
                 }
             }
         }
@@ -805,7 +916,8 @@ export class McpContext {
         try {
             const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'chrome-devtools-mcp-'));
             const filename = path.join(dir, `screenshot.${getExtensionFromMimeType(mimeType)}`);
-            await fs.writeFile(filename, data);
+            // Use mode 0o600 (owner read/write only) for secure temp file creation
+            await fs.writeFile(filename, data, { mode: 0o600 });
             return { filename };
         }
         catch (err) {
@@ -816,7 +928,8 @@ export class McpContext {
     async saveFile(data, filename) {
         try {
             const filePath = path.resolve(filename);
-            await fs.writeFile(filePath, data);
+            // Use mode 0o644 (owner read/write, others read) for user-specified paths
+            await fs.writeFile(filePath, data, { mode: 0o644 });
             return { filename };
         }
         catch (err) {
@@ -879,8 +992,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/cli.js

@@ -170,10 +170,11 @@ export function parseArguments(version, argv = process.argv) {
         .check(args => {
         // We can't set default in the options else
         // Yargs will complain
-        if (!args.channel &&
-            !args.browserUrl &&
-            !args.wsEndpoint &&
-            !args.executablePath) {
+        // Note: Use explicit undefined checks since empty strings are valid falsy values
+        if (args.channel === undefined &&
+            args.browserUrl === undefined &&
+            args.wsEndpoint === undefined &&
+            args.executablePath === undefined) {
             args.channel = 'dev';
         }
         return true;

package/build/src/formatters/IssueFormatter.js

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ISSUE_UTILS } from '../issue-descriptions.js';
+import { logger } from '../logger.js';
+import { DevTools } from '../third_party/index.js';
+export class IssueFormatter {
+    #issue;
+    #options;
+    constructor(issue, options) {
+        this.#issue = issue;
+        this.#options = options;
+    }
+    toString() {
+        const title = this.#getTitle();
+        const count = this.#issue.getAggregatedIssuesCount();
+        const idPart = this.#options.id !== undefined ? `msgid=${this.#options.id} ` : '';
+        return `${idPart}[issue] ${title} (count: ${count})`;
+    }
+    toStringDetailed() {
+        const result = [];
+        if (this.#options.id !== undefined) {
+            result.push(`ID: ${this.#options.id}`);
+        }
+        const bodyParts = [];
+        const description = this.#getDescription();
+        let processedMarkdown = description?.trim();
+        // Remove heading in order not to conflict with the whole console message response markdown
+        if (processedMarkdown?.startsWith('# ')) {
+            processedMarkdown = processedMarkdown.substring(2).trimStart();
+        }
+        if (processedMarkdown) {
+            bodyParts.push(processedMarkdown);
+        }
+        else {
+            bodyParts.push(this.#getTitle() ?? 'Unknown Issue');
+        }
+        const links = this.#issue.getDescription()?.links;
+        if (links && links.length > 0) {
+            bodyParts.push('Learn more:');
+            for (const link of links) {
+                bodyParts.push(`[${link.linkTitle}](${link.link})`);
+            }
+        }
+        const affectedResources = this.#getAffectedResources();
+        if (affectedResources.length) {
+            bodyParts.push('### Affected resources');
+            bodyParts.push(...affectedResources.map(item => {
+                const details = [];
+                if (item.uid) {
+                    details.push(`uid=${item.uid}`);
+                }
+                if (item.request) {
+                    details.push((typeof item.request === 'number' ? `reqid=` : 'url=') +
+                        item.request);
+                }
+                if (item.data) {
+                    details.push(`data=${JSON.stringify(item.data)}`);
+                }
+                return details.join(' ');
+            }));
+        }
+        result.push(`Message: issue> ${bodyParts.join('\n')}`);
+        return result.join('\n');
+    }
+    toJSON() {
+        return {
+            type: 'issue',
+            title: this.#getTitle(),
+            count: this.#issue.getAggregatedIssuesCount(),
+            id: this.#options.id,
+        };
+    }
+    toJSONDetailed() {
+        return {
+            id: this.#options.id,
+            type: 'issue',
+            title: this.#getTitle(),
+            description: this.#getDescription(),
+            links: this.#issue.getDescription()?.links,
+            affectedResources: this.#getAffectedResources(),
+        };
+    }
+    #getAffectedResources() {
+        const issues = this.#issue.getAllIssues();
+        const affectedResources = [];
+        for (const singleIssue of issues) {
+            const details = singleIssue.details();
+            if (!details) {
+                continue;
+            }
+            // We send the remaining details as untyped JSON because the DevTools
+            // frontend code is currently not re-usable.
+            const data = structuredClone(details);
+            let uid;
+            let request;
+            if ('violatingNodeId' in details &&
+                details.violatingNodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.violatingNodeId);
+                delete data.violatingNodeId;
+            }
+            if ('nodeId' in details &&
+                details.nodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.nodeId);
+                delete data.nodeId;
+            }
+            if ('documentNodeId' in details &&
+                details.documentNodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.documentNodeId);
+                delete data.documentNodeId;
+            }
+            if ('request' in details && details.request) {
+                request = details.request.url;
+                if (details.request.requestId && this.#options.requestIdResolver) {
+                    const resolvedId = this.#options.requestIdResolver(details.request.requestId);
+                    if (resolvedId) {
+                        request = resolvedId;
+                        const requestData = data.request;
+                        delete requestData.requestId;
+                    }
+                }
+            }
+            // These fields has no use for the MCP client (redundant or irrelevant).
+            delete data.errorType;
+            delete data.frameId;
+            affectedResources.push({
+                uid,
+                data: data,
+                request,
+            });
+        }
+        return affectedResources;
+    }
+    isValid() {
+        return this.#getTitle() !== undefined;
+    }
+    // Helper to extract title
+    #getTitle() {
+        const markdownDescription = this.#issue.getDescription();
+        const filename = markdownDescription?.file;
+        if (!filename) {
+            logger(`no description found for issue:` + this.#issue.code());
+            return undefined;
+        }
+        // We already have the description logic in #getDescription, but title extraction is separate
+        // We can reuse the logic or cache it.
+        // Ideally we should process markdown once.
+        const rawMarkdown = ISSUE_UTILS.getIssueDescription(filename);
+        if (!rawMarkdown) {
+            logger(`no markdown ${filename} found for issue:` + this.#issue.code());
+            return undefined;
+        }
+        try {
+            const processedMarkdown = DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription?.substitutions);
+            const markdownAst = DevTools.Marked.Marked.lexer(processedMarkdown);
+            const title = DevTools.MarkdownIssueDescription.findTitleFromMarkdownAst(markdownAst);
+            if (!title) {
+                logger('cannot read issue title from ' + filename);
+                return undefined;
+            }
+            return title;
+        }
+        catch {
+            logger('error parsing markdown for issue ' + this.#issue.code());
+            return undefined;
+        }
+    }
+    #getDescription() {
+        const markdownDescription = this.#issue.getDescription();
+        const filename = markdownDescription?.file;
+        if (!filename) {
+            return undefined;
+        }
+        const rawMarkdown = ISSUE_UTILS.getIssueDescription(filename);
+        if (!rawMarkdown) {
+            return undefined;
+        }
+        try {
+            return DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription?.substitutions);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}

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/telemetry/clearcut-logger.js

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import process from 'node:process';
+import { logger } from '../logger.js';
+import { FilePersistence } from './persistence.js';
+import { WatchdogMessageType, OsType } from './types.js';
+import { WatchdogClient } from './watchdog-client.js';
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function detectOsType() {
+    switch (process.platform) {
+        case 'win32':
+            return OsType.OS_TYPE_WINDOWS;
+        case 'darwin':
+            return OsType.OS_TYPE_MACOS;
+        case 'linux':
+            return OsType.OS_TYPE_LINUX;
+        default:
+            return OsType.OS_TYPE_UNSPECIFIED;
+    }
+}
+export class ClearcutLogger {
+    #persistence;
+    #watchdog;
+    constructor(options) {
+        this.#persistence = options.persistence ?? new FilePersistence();
+        this.#watchdog =
+            options.watchdogClient ??
+                new WatchdogClient({
+                    parentPid: process.pid,
+                    appVersion: options.appVersion,
+                    osType: detectOsType(),
+                    logFile: options.logFile,
+                    clearcutEndpoint: options.clearcutEndpoint,
+                    clearcutForceFlushIntervalMs: options.clearcutForceFlushIntervalMs,
+                    clearcutIncludePidHeader: options.clearcutIncludePidHeader,
+                });
+    }
+    async logToolInvocation(args) {
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: {
+                tool_invocation: {
+                    tool_name: args.toolName,
+                    success: args.success,
+                    latency_ms: args.latencyMs,
+                },
+            },
+        });
+    }
+    async logServerStart(flagUsage) {
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: {
+                server_start: {
+                    flag_usage: flagUsage,
+                },
+            },
+        });
+    }
+    async logDailyActiveIfNeeded() {
+        try {
+            const state = await this.#persistence.loadState();
+            if (this.#shouldLogDailyActive(state)) {
+                let daysSince = -1;
+                if (state.lastActive) {
+                    const lastActiveDate = new Date(state.lastActive);
+                    const now = new Date();
+                    const diffTime = Math.abs(now.getTime() - lastActiveDate.getTime());
+                    daysSince = Math.ceil(diffTime / MS_PER_DAY);
+                }
+                this.#watchdog.send({
+                    type: WatchdogMessageType.LOG_EVENT,
+                    payload: {
+                        daily_active: {
+                            days_since_last_active: daysSince,
+                        },
+                    },
+                });
+                state.lastActive = new Date().toISOString();
+                await this.#persistence.saveState(state);
+            }
+        }
+        catch (err) {
+            logger('Error in logDailyActiveIfNeeded:', err);
+        }
+    }
+    #shouldLogDailyActive(state) {
+        if (!state.lastActive) {
+            return true;
+        }
+        const lastActiveDate = new Date(state.lastActive);
+        const now = new Date();
+        // Compare UTC dates
+        const isSameDay = lastActiveDate.getUTCFullYear() === now.getUTCFullYear() &&
+            lastActiveDate.getUTCMonth() === now.getUTCMonth() &&
+            lastActiveDate.getUTCDate() === now.getUTCDate();
+        return !isSameDay;
+    }
+}