@mcp-b/chrome-devtools-mcp 2.0.2 → 2.0.5

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

@@ -5,7 +5,7 @@
  */
 import process from 'node:process';
 import './polyfill.js';
-import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
+import { connectToNewBrowser, disconnectBrowser, ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
 import { parseArguments } from './cli.js';
 import { loadIssueDescriptions } from './issue-descriptions.js';
 import { logger, saveLogsToFile } from './logger.js';
@@ -102,6 +102,7 @@ async function getContext() {
             devtools,
             channel: undefined,
             userDataDir: args.userDataDir,
+            includeExtensionPages: args.includeExtensionPages,
         });
     }
     // If autoConnect is true, try connecting first, then fall back to launching
@@ -115,6 +116,7 @@ async function getContext() {
                 devtools,
                 channel: args.channel,
                 userDataDir: args.userDataDir,
+                includeExtensionPages: args.includeExtensionPages,
             });
             logger('Successfully connected to running browser instance');
         }
@@ -131,6 +133,7 @@ async function getContext() {
                 args: extraArgs,
                 acceptInsecureCerts: args.acceptInsecureCerts,
                 devtools,
+                includeExtensionPages: args.includeExtensionPages,
             });
             wasLaunched = true;
         }
@@ -148,6 +151,7 @@ async function getContext() {
             args: extraArgs,
             acceptInsecureCerts: args.acceptInsecureCerts,
             devtools,
+            includeExtensionPages: args.includeExtensionPages,
         });
         wasLaunched = true;
     }
@@ -155,6 +159,8 @@ async function getContext() {
         context = await McpContext.from(browser, logger, {
             experimentalDevToolsDebugging: devtools,
             experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+            includeExtensionPages: args.includeExtensionPages,
+            onReconnect,
         });
         if (wasLaunched) {
             // Fresh browser launch - use the existing default page
@@ -201,6 +207,77 @@ async function getContext() {
     }
     return context;
 }
+/**
+ * Reconnect callback invoked by the connect_to_browser tool.
+ *
+ * Tears down the current browser session and connects to a new browser,
+ * rebuilding all infrastructure (McpContext, WebMCPToolHub, session window).
+ * Retries connection with exponential backoff for browsers that are still starting.
+ */
+async function onReconnect(options) {
+    const timeout = options.timeout ?? 30_000;
+    const retryInterval = 2_000;
+    const devtools = args.experimentalDevtools ?? false;
+    // 1. Tear down old session
+    if (context) {
+        try {
+            await context.closeSessionWindow();
+        }
+        catch (err) {
+            logger('Error closing session window during reconnect:', err);
+        }
+        context.dispose();
+    }
+    disconnectBrowser();
+    // 2. Retry loop to connect to new browser
+    const deadline = Date.now() + timeout;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const newBrowser = await connectToNewBrowser({
+                browserURL: options.browserURL,
+                wsEndpoint: options.wsEndpoint,
+                wsHeaders: options.wsHeaders,
+                includeExtensionPages: args.includeExtensionPages,
+            });
+            // 3. Rebuild context
+            context = await McpContext.from(newBrowser, logger, {
+                experimentalDevToolsDebugging: devtools,
+                experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+                includeExtensionPages: args.includeExtensionPages,
+                onReconnect,
+            });
+            // 4. Create session window
+            const { windowId } = await context.newWindow();
+            context.setSessionWindowId(windowId);
+            logger(`Reconnect: new session window ${windowId}`);
+            // 5. Rebuild tool hub
+            const toolHub = new WebMCPToolHub(server, context);
+            context.setToolHub(toolHub);
+            logger('Reconnect: WebMCPToolHub rebuilt');
+            // 6. Build response
+            const pages = context.getPages().map((page, index) => ({
+                index,
+                url: page.url(),
+                selected: context.isPageSelected(page),
+            }));
+            const wsEndpoint = newBrowser.wsEndpoint();
+            return { pages, wsEndpoint };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            logger(`Reconnect attempt failed: ${lastError.message}`);
+            const remaining = deadline - Date.now();
+            if (remaining > retryInterval) {
+                await new Promise(resolve => setTimeout(resolve, retryInterval));
+            }
+            else {
+                break;
+            }
+        }
+    }
+    throw new Error(`Failed to connect to browser after ${timeout}ms: ${lastError?.message ?? 'unknown error'}`);
+}
 /**
  * Log security disclaimers to stderr.
  *
@@ -251,7 +328,11 @@ function registerTool(tool) {
             await tool.handler({
                 params,
             }, response, context);
-            const content = await response.handle(tool.name, context);
+            // Re-fetch context in case the handler swapped it (e.g. connect_to_browser).
+            // The local `const context` shadows the module-level `let context`, so we
+            // must call getContext() to pick up any reassignment by onReconnect.
+            const activeContext = await getContext();
+            const content = await response.handle(tool.name, activeContext);
             const result = {
                 content,
             };

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;
+    }
+}

package/build/src/telemetry/flag-utils.js

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { toSnakeCase } from '../utils/string.js';
+/**
+ * Computes telemetry flag usage from parsed arguments and CLI options.
+ *
+ * Iterates over the defined CLI options to construct a payload:
+ * - Flag names are converted to snake_case (e.g. `browserUrl` -> `browser_url`).
+ * - A flag is logged as `{flag_name}_present` if:
+ *    - It has no default value, OR
+ *    - The provided value differs from the default value.
+ * - Boolean flags are logged with their literal value.
+ * - String flags with defined `choices` (Enums) are logged as their uppercase value.
+ */
+export function computeFlagUsage(args, options) {
+    const usage = {};
+    for (const [flagName, config] of Object.entries(options)) {
+        const value = args[flagName];
+        const snakeCaseName = toSnakeCase(flagName);
+        // If there isn't a default value provided for the flag,
+        // we're going to log whether it's present on the args user
+        // provided or not. If there is a default value, we only log presence
+        // if the value differs from the default, implying explicit user intent.
+        if (!('default' in config) || value !== config.default) {
+            usage[`${snakeCaseName}_present`] = value !== undefined && value !== null;
+        }
+        if (config.type === 'boolean' && typeof value === 'boolean') {
+            // For boolean options, we're going to log the value directly.
+            usage[snakeCaseName] = value;
+        }
+        else if (config.type === 'string' &&
+            typeof value === 'string' &&
+            'choices' in config &&
+            config.choices) {
+            // For enums, log the value as uppercase
+            // We're going to have an enum for such flags with choices represented
+            // as an `enum` where the keys of the enum will map to the uppercase `choice`.
+            usage[snakeCaseName] = `${snakeCaseName}_${value}`.toUpperCase();
+        }
+    }
+    return usage;
+}

package/build/src/telemetry/metric-utils.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const LATENCY_BUCKETS = [50, 100, 250, 500, 1000, 2500, 5000, 10000];
+export function bucketizeLatency(latencyMs) {
+    for (const bucket of LATENCY_BUCKETS) {
+        if (latencyMs <= bucket) {
+            return bucket;
+        }
+    }
+    return LATENCY_BUCKETS[LATENCY_BUCKETS.length - 1];
+}

package/build/src/telemetry/persistence.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { logger } from '../logger.js';
+const STATE_FILE_NAME = 'telemetry_state.json';
+function getDataFolder() {
+    const homedir = os.homedir();
+    const { env } = process;
+    const name = 'chrome-devtools-mcp';
+    if (process.platform === 'darwin') {
+        return path.join(homedir, 'Library', 'Application Support', name);
+    }
+    if (process.platform === 'win32') {
+        const localAppData = env.LOCALAPPDATA || path.join(homedir, 'AppData', 'Local');
+        return path.join(localAppData, name, 'Data');
+    }
+    return path.join(env.XDG_DATA_HOME || path.join(homedir, '.local', 'share'), name);
+}
+export class FilePersistence {
+    #dataFolder;
+    constructor(dataFolderOverride) {
+        this.#dataFolder = dataFolderOverride ?? getDataFolder();
+    }
+    async loadState() {
+        try {
+            const filePath = path.join(this.#dataFolder, STATE_FILE_NAME);
+            const content = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return {
+                lastActive: '',
+            };
+        }
+    }
+    async saveState(state) {
+        const filePath = path.join(this.#dataFolder, STATE_FILE_NAME);
+        try {
+            await fs.mkdir(this.#dataFolder, { recursive: true });
+            await fs.writeFile(filePath, JSON.stringify(state, null, 2), 'utf-8');
+        }
+        catch (error) {
+            // Ignore errors during state saving to avoid crashing the server
+            logger(`Failed to save telemetry state to ${filePath}:`, error);
+        }
+    }
+}

package/build/src/telemetry/types.js

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Enums
+export var OsType;
+(function (OsType) {
+    OsType[OsType["OS_TYPE_UNSPECIFIED"] = 0] = "OS_TYPE_UNSPECIFIED";
+    OsType[OsType["OS_TYPE_WINDOWS"] = 1] = "OS_TYPE_WINDOWS";
+    OsType[OsType["OS_TYPE_MACOS"] = 2] = "OS_TYPE_MACOS";
+    OsType[OsType["OS_TYPE_LINUX"] = 3] = "OS_TYPE_LINUX";
+})(OsType || (OsType = {}));
+export var ChromeChannel;
+(function (ChromeChannel) {
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_UNSPECIFIED"] = 0] = "CHROME_CHANNEL_UNSPECIFIED";
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_CANARY"] = 1] = "CHROME_CHANNEL_CANARY";
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_DEV"] = 2] = "CHROME_CHANNEL_DEV";
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_BETA"] = 3] = "CHROME_CHANNEL_BETA";
+    ChromeChannel[ChromeChannel["CHROME_CHANNEL_STABLE"] = 4] = "CHROME_CHANNEL_STABLE";
+})(ChromeChannel || (ChromeChannel = {}));
+export var McpClient;
+(function (McpClient) {
+    McpClient[McpClient["MCP_CLIENT_UNSPECIFIED"] = 0] = "MCP_CLIENT_UNSPECIFIED";
+    McpClient[McpClient["MCP_CLIENT_CLAUDE_CODE"] = 1] = "MCP_CLIENT_CLAUDE_CODE";
+    McpClient[McpClient["MCP_CLIENT_GEMINI_CLI"] = 2] = "MCP_CLIENT_GEMINI_CLI";
+})(McpClient || (McpClient = {}));
+// IPC types for messages between the main process and the
+// telemetry watchdog process.
+export var WatchdogMessageType;
+(function (WatchdogMessageType) {
+    WatchdogMessageType["LOG_EVENT"] = "log-event";
+})(WatchdogMessageType || (WatchdogMessageType = {}));