@vibebrowser/chrome-devtools-mcp 0.26.0

package/build/src/issue-descriptions.js

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DESCRIPTIONS_PATH = path.join(import.meta.dirname, 'third_party/issue-descriptions');
+let issueDescriptions = {};
+/**
+ * Reads all issue descriptions from the filesystem into memory.
+ */
+export async function loadIssueDescriptions() {
+    if (Object.keys(issueDescriptions).length > 0) {
+        return;
+    }
+    const files = await fs.promises.readdir(DESCRIPTIONS_PATH);
+    const descriptions = {};
+    for (const file of files) {
+        if (!file.endsWith('.md')) {
+            continue;
+        }
+        const content = await fs.promises.readFile(path.join(DESCRIPTIONS_PATH, file), 'utf-8');
+        descriptions[file] = content;
+    }
+    issueDescriptions = descriptions;
+}
+/**
+ * Gets an issue description from the in-memory cache.
+ * @param fileName The file name of the issue description.
+ * @returns The description of the issue, or null if it doesn't exist.
+ */
+export function getIssueDescription(fileName) {
+    return issueDescriptions[fileName] ?? null;
+}
+export const ISSUE_UTILS = {
+    loadIssueDescriptions,
+    getIssueDescription,
+};
+//# sourceMappingURL=issue-descriptions.js.map

package/build/src/logger.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import { debug } from './third_party/index.js';
+const mcpDebugNamespace = 'mcp:log';
+const namespacesToEnable = [
+    mcpDebugNamespace,
+    ...(process.env['DEBUG'] ? [process.env['DEBUG']] : []),
+];
+export function saveLogsToFile(fileName) {
+    // Enable overrides everything so we need to add them
+    debug.enable(namespacesToEnable.join(','));
+    const logFile = fs.createWriteStream(fileName, { flags: 'a+' });
+    debug.log = function (...chunks) {
+        logFile.write(`${chunks.join(' ')}\n`);
+    };
+    logFile.on('error', function (error) {
+        console.error(`Error when opening/writing to log file: ${error.message}`);
+        logFile.end();
+        process.exit(1);
+    });
+    return logFile;
+}
+export function flushLogs(logFile, timeoutMs = 2000) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(reject, timeoutMs);
+        logFile.end(() => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+}
+export const logger = debug(mcpDebugNamespace);
+//# sourceMappingURL=logger.js.map

package/build/src/polyfill.js

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// polyfills are now bundled with all other dependencies
+import './third_party/index.js';
+//# sourceMappingURL=polyfill.js.map

package/build/src/telemetry/ClearcutLogger.js

@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import process from 'node:process';
+import { DAEMON_CLIENT_NAME } from '../daemon/utils.js';
+import { logger } from '../logger.js';
+import { sanitizeParams, stripUnderscoreBeforeNumber } from './transformation.js';
+import { McpClient, WatchdogMessageType, OsType, } from './types.js';
+import { WatchdogClient } from './WatchdogClient.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;
+    }
+}
+// Not const to allow resetting the instance for testing purposes.
+let _clearcut_logger_instance;
+export class ClearcutLogger {
+    #persistence;
+    #watchdog;
+    #mcpClient;
+    static initialize(options) {
+        if (_clearcut_logger_instance) {
+            throw new Error('ClearcutLogger is already initialized');
+        }
+        _clearcut_logger_instance = new ClearcutLogger(options);
+        return _clearcut_logger_instance;
+    }
+    static get() {
+        return _clearcut_logger_instance;
+    }
+    static resetForTesting() {
+        _clearcut_logger_instance = undefined;
+    }
+    constructor(options) {
+        this.#persistence = options.persistence;
+        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,
+                });
+        this.#mcpClient = McpClient.MCP_CLIENT_UNSPECIFIED;
+    }
+    setClientName(clientName) {
+        const lowerName = clientName.toLowerCase();
+        if (lowerName.includes('claude')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_CLAUDE_CODE;
+        }
+        else if (lowerName.includes('gemini')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_GEMINI_CLI;
+        }
+        else if (clientName === DAEMON_CLIENT_NAME) {
+            this.#mcpClient = McpClient.MCP_CLIENT_DT_MCP_CLI;
+        }
+        else if (lowerName.includes('openclaw')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_OPENCLAW;
+        }
+        else if (lowerName.includes('codex')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_CODEX;
+        }
+        else if (lowerName.includes('antigravity')) {
+            this.#mcpClient = McpClient.MCP_CLIENT_ANTIGRAVITY;
+        }
+        else {
+            this.#mcpClient = McpClient.MCP_CLIENT_OTHER;
+        }
+    }
+    async logToolInvocation(args) {
+        const sanitizedToolName = stripUnderscoreBeforeNumber(args.toolName);
+        const tool_invocation = {
+            tool_name: sanitizedToolName,
+            success: args.success,
+            latency_ms: args.latencyMs,
+        };
+        if (Object.keys(args.params).length > 0) {
+            tool_invocation.tool_params = {
+                [`${sanitizedToolName}_params`]: sanitizeParams(args.params, args.schema),
+            };
+        }
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: {
+                mcp_client: this.#mcpClient,
+                tool_invocation: tool_invocation,
+            },
+        });
+    }
+    async logServerStart(flagUsage) {
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: {
+                mcp_client: this.#mcpClient,
+                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: {
+                        mcp_client: this.#mcpClient,
+                        daily_active: {
+                            days_since_last_active: daysSince,
+                        },
+                    },
+                });
+                state.lastActive = new Date().toISOString();
+                await this.#persistence.saveState(state);
+            }
+        }
+        catch (err) {
+            logger('Error in logDailyActiveIfNeeded:', err);
+        }
+    }
+    async logServerError(args) {
+        this.#watchdog.send({
+            type: WatchdogMessageType.LOG_EVENT,
+            payload: {
+                mcp_client: this.#mcpClient,
+                server_error: {
+                    tool_name: args.toolName
+                        ? stripUnderscoreBeforeNumber(args.toolName)
+                        : '',
+                    error_code: args.errorCode,
+                },
+            },
+        });
+    }
+    #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;
+    }
+}
+//# sourceMappingURL=ClearcutLogger.js.map

package/build/src/telemetry/WatchdogClient.js

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../logger.js';
+export class WatchdogClient {
+    #childProcess;
+    constructor(config, options) {
+        const watchdogPath = fileURLToPath(new URL('./watchdog/main.js', import.meta.url));
+        const args = [
+            watchdogPath,
+            `--parent-pid=${config.parentPid}`,
+            `--app-version=${config.appVersion}`,
+            `--os-type=${config.osType}`,
+        ];
+        if (config.logFile) {
+            args.push(`--log-file=${config.logFile}`);
+        }
+        if (config.clearcutEndpoint) {
+            args.push(`--clearcut-endpoint=${config.clearcutEndpoint}`);
+        }
+        if (config.clearcutForceFlushIntervalMs) {
+            args.push(`--clearcut-force-flush-interval-ms=${config.clearcutForceFlushIntervalMs}`);
+        }
+        if (config.clearcutIncludePidHeader) {
+            args.push('--clearcut-include-pid-header');
+        }
+        const spawner = options?.spawn ?? spawn;
+        this.#childProcess = spawner(process.execPath, args, {
+            stdio: ['pipe', 'ignore', 'ignore'],
+            detached: true,
+        });
+        this.#childProcess.unref();
+        this.#childProcess.on('error', err => {
+            logger('Watchdog process error:', err);
+        });
+        this.#childProcess.on('exit', (code, signal) => {
+            logger(`Watchdog exited with code ${code} and signal ${signal}`);
+        });
+    }
+    send(message) {
+        if (this.#childProcess.stdin &&
+            !this.#childProcess.stdin.destroyed &&
+            this.#childProcess.pid) {
+            try {
+                const line = JSON.stringify(message) + '\n';
+                this.#childProcess.stdin.write(line);
+            }
+            catch (err) {
+                logger('Failed to write to watchdog stdin', err);
+            }
+        }
+        else {
+            logger('Watchdog stdin not available, dropping message');
+        }
+    }
+}
+//# sourceMappingURL=WatchdogClient.js.map

package/build/src/telemetry/errors.js

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * IMPORTANT:
+ *   1. this module must only contain ErrorCode.
+ *   2. do not refactor ErrorCode to elsewhere.
+ *   3. prefix new enum values with "ERROR_CODE_". This makes it easier to
+ *      programmtically parse this file.
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode[ErrorCode["ERROR_CODE_UNSPECIFIED"] = 0] = "ERROR_CODE_UNSPECIFIED";
+    ErrorCode[ErrorCode["ERROR_CODE_PERSISTENCE_FILE_READ_FAILED"] = 1] = "ERROR_CODE_PERSISTENCE_FILE_READ_FAILED";
+    ErrorCode[ErrorCode["ERROR_CODE_PERSISTENCE_FILE_SAVE_FAILED"] = 2] = "ERROR_CODE_PERSISTENCE_FILE_SAVE_FAILED";
+})(ErrorCode || (ErrorCode = {}));
+//# sourceMappingURL=errors.js.map

package/build/src/telemetry/flagUtils.js

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { toSnakeCase } from '../utils/string.js';
+import { stripUnderscoreBeforeNumber } from './transformation.js';
+/**
+ * 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`.
+ */
+function formatEnumChoice(snakeCaseName, choice) {
+    return stripUnderscoreBeforeNumber(`${snakeCaseName}_${choice}`).toUpperCase();
+}
+/**
+ * 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.
+ *
+ * IMPORTANT: keep getPossibleFlagMetrics() in sync with this function.
+ */
+export function computeFlagUsage(args, options) {
+    const usage = {};
+    for (const [flagName, config] of Object.entries(options)) {
+        const value = args[flagName];
+        const snakeCaseName = stripUnderscoreBeforeNumber(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) {
+            usage[snakeCaseName] = formatEnumChoice(snakeCaseName, value);
+        }
+    }
+    return usage;
+}
+/**
+ * Computes the list of possible flag metrics based on the CLI options.
+ *
+ * IMPORTANT: keep this function in sync with computeFlagUsage().
+ */
+export function getPossibleFlagMetrics(options) {
+    const metrics = [];
+    for (const [flagName, config] of Object.entries(options)) {
+        const snakeCaseName = stripUnderscoreBeforeNumber(toSnakeCase(flagName));
+        // _present is always a possible metric
+        metrics.push({
+            name: `${snakeCaseName}_present`,
+            flagType: 'boolean',
+        });
+        if (config.type === 'boolean') {
+            metrics.push({
+                name: snakeCaseName,
+                flagType: 'boolean',
+            });
+        }
+        else if (config.type === 'string' &&
+            'choices' in config &&
+            config.choices) {
+            metrics.push({
+                name: snakeCaseName,
+                flagType: 'enum',
+                choices: [
+                    `${snakeCaseName.toUpperCase()}_UNSPECIFIED`,
+                    ...config.choices.map(choice => formatEnumChoice(snakeCaseName, choice)),
+                ],
+            });
+        }
+    }
+    return metrics;
+}
+//# sourceMappingURL=flagUtils.js.map

package/build/src/telemetry/metricsRegistry.js

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { transformArgName, transformArgType, getZodType, PARAM_BLOCKLIST, stripUnderscoreBeforeNumber, } from './transformation.js';
+/**
+ * Validates that all values in an enum are of the homogeneous primitive type.
+ * Returns the primitive type string. Throws an error if heterogeneous.
+ */
+export function validateEnumHomogeneity(values) {
+    const firstType = typeof values[0];
+    for (const val of values) {
+        if (typeof val !== firstType) {
+            throw new Error('Heterogeneous enum types found');
+        }
+    }
+    return firstType;
+}
+export function applyToExistingMetrics(existing, update) {
+    const updated = applyToExisting(existing, update);
+    const existingByName = new Map(existing.map(tool => [tool.name, tool]));
+    const updatedByName = new Map(update.map(tool => [tool.name, tool]));
+    return updated.map(tool => {
+        const existingTool = existingByName.get(tool.name);
+        const updatedTool = updatedByName.get(tool.name);
+        // If the tool still exists in the update, we will update the args.
+        if (existingTool && updatedTool) {
+            const updatedArgs = applyToExisting(existingTool.args, updatedTool.args);
+            return { ...tool, args: updatedArgs };
+        }
+        return tool;
+    });
+}
+export function applyToExisting(existing, update) {
+    const existingNames = new Set(existing.map(item => item.name));
+    const updatedNames = new Set(update.map(item => item.name));
+    const result = [];
+    // Keep the original ordering.
+    for (const entry of existing) {
+        const toAdd = { ...entry };
+        if (!updatedNames.has(entry.name)) {
+            toAdd.isDeprecated = true;
+        }
+        result.push(toAdd);
+    }
+    // New entries must be added to the very back of the list.
+    for (const entry of update) {
+        if (!existingNames.has(entry.name)) {
+            result.push({ ...entry });
+        }
+    }
+    return result;
+}
+/**
+ * Generates tool metrics from tool definitions.
+ */
+export function generateToolMetrics(tools) {
+    return tools.map(tool => {
+        const args = [];
+        for (const [name, schema] of Object.entries(tool.schema)) {
+            if (PARAM_BLOCKLIST.has(name)) {
+                continue;
+            }
+            const zodType = getZodType(schema);
+            const transformedName = transformArgName(zodType, name);
+            let argType = transformArgType(zodType);
+            if (argType === 'enum') {
+                let values;
+                if (schema._def.values?.length > 0) {
+                    values = schema._def.values;
+                }
+                else {
+                    values = schema._def.innerType._def.values;
+                }
+                argType = validateEnumHomogeneity(values);
+            }
+            args.push({
+                name: transformedName,
+                argType,
+            });
+        }
+        return {
+            name: stripUnderscoreBeforeNumber(tool.name),
+            args,
+        };
+    });
+}
+//# sourceMappingURL=metricsRegistry.js.map

package/build/src/telemetry/persistence.js

@@ -0,0 +1,72 @@
+/**
+ * @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';
+import { ClearcutLogger } from './ClearcutLogger.js';
+import { ErrorCode } from './errors.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() {
+        const filePath = path.join(this.#dataFolder, STATE_FILE_NAME);
+        try {
+            await fs.access(filePath);
+        }
+        catch {
+            // File doesn't exist. Not an error because new users do not have the state file.
+            return {
+                lastActive: '',
+            };
+        }
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            logger(`Failed to read telemetry state from ${filePath}:`, error);
+            void ClearcutLogger.get()?.logServerError({
+                errorCode: ErrorCode.ERROR_CODE_PERSISTENCE_FILE_READ_FAILED,
+            });
+            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);
+            void ClearcutLogger.get()?.logServerError({
+                errorCode: ErrorCode.ERROR_CODE_PERSISTENCE_FILE_SAVE_FAILED,
+            });
+        }
+    }
+}
+//# sourceMappingURL=persistence.js.map