chrome-devtools-mcp 0.18.1 → 0.20.0

package/build/src/daemon/client.js

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import { logger } from '../logger.js';
+import { PipeTransport } from '../third_party/index.js';
+import { saveTemporaryFile } from '../utils/files.js';
+import { DAEMON_SCRIPT_PATH, getSocketPath, getPidFilePath, isDaemonRunning, } from './utils.js';
+const FILE_TIMEOUT = 10_000;
+/**
+ * Waits for a file to be created and populated (removed = false) or removed (removed = true).
+ */
+function waitForFile(filePath, removed = false) {
+    return new Promise((resolve, reject) => {
+        const check = () => {
+            const exists = fs.existsSync(filePath);
+            if (removed) {
+                return !exists;
+            }
+            if (!exists) {
+                return false;
+            }
+            try {
+                return fs.statSync(filePath).size > 0;
+            }
+            catch {
+                return false;
+            }
+        };
+        if (check()) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            fs.unwatchFile(filePath);
+            reject(new Error(`Timeout: file ${filePath} ${removed ? 'not removed' : 'not found'} within ${FILE_TIMEOUT}ms`));
+        }, FILE_TIMEOUT);
+        fs.watchFile(filePath, { interval: 500 }, () => {
+            if (check()) {
+                clearTimeout(timer);
+                fs.unwatchFile(filePath);
+                resolve();
+            }
+        });
+    });
+}
+export async function startDaemon(mcpArgs = []) {
+    if (isDaemonRunning()) {
+        logger('Daemon is already running');
+        return;
+    }
+    const pidFilePath = getPidFilePath();
+    if (fs.existsSync(pidFilePath)) {
+        fs.unlinkSync(pidFilePath);
+    }
+    logger('Starting daemon...', ...mcpArgs);
+    const child = spawn(process.execPath, [DAEMON_SCRIPT_PATH, ...mcpArgs], {
+        detached: true,
+        stdio: 'ignore',
+        env: process.env,
+        cwd: process.cwd(),
+        windowsHide: true,
+    });
+    child.unref();
+    await waitForFile(pidFilePath);
+}
+const SEND_COMMAND_TIMEOUT = 60_000; // ms
+/**
+ * `sendCommand` opens a socket connection sends a single command and disconnects.
+ */
+export async function sendCommand(command) {
+    const socketPath = getSocketPath();
+    const socket = net.createConnection({
+        path: socketPath,
+    });
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error('Timeout waiting for daemon response'));
+        }, SEND_COMMAND_TIMEOUT);
+        const transport = new PipeTransport(socket, socket);
+        transport.onmessage = async (message) => {
+            clearTimeout(timer);
+            logger('onmessage', message);
+            resolve(JSON.parse(message));
+        };
+        socket.on('error', error => {
+            clearTimeout(timer);
+            logger('Socket error:', error);
+            reject(error);
+        });
+        socket.on('close', () => {
+            clearTimeout(timer);
+            logger('Socket closed:');
+            reject(new Error('Socket closed'));
+        });
+        logger('Sending message', command);
+        transport.send(JSON.stringify(command));
+    });
+}
+export async function stopDaemon() {
+    if (!isDaemonRunning()) {
+        logger('Daemon is not running');
+        return;
+    }
+    const pidFilePath = getPidFilePath();
+    await sendCommand({ method: 'stop' });
+    await waitForFile(pidFilePath, /*removed=*/ true);
+}
+export async function handleResponse(response, format) {
+    if (response.isError) {
+        return JSON.stringify(response.content);
+    }
+    if (format === 'json') {
+        if (response.structuredContent) {
+            return JSON.stringify(response.structuredContent);
+        }
+        // Fall-through to text for backward compatibility.
+    }
+    const chunks = [];
+    for (const content of response.content) {
+        if (content.type === 'text') {
+            chunks.push(content.text);
+        }
+        else if (content.type === 'image') {
+            const imageData = content.data;
+            const mimeType = content.mimeType;
+            let extension = '.png';
+            switch (mimeType) {
+                case 'image/jpg':
+                case 'image/jpeg':
+                    extension = '.jpeg';
+                    break;
+                case 'webp':
+                    extension = '.webp';
+                    break;
+            }
+            const data = Buffer.from(imageData, 'base64');
+            const name = crypto.randomUUID();
+            const { filepath } = await saveTemporaryFile(data, `${name}${extension}`);
+            chunks.push(`Saved to ${filepath}.`);
+        }
+        else {
+            throw new Error('Not supported response content type');
+        }
+    }
+    return format === 'md' ? chunks.join(' ') : JSON.stringify(chunks);
+}

package/build/src/daemon/daemon.js

@@ -4,27 +4,41 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import fs from 'node:fs/promises';
+import fs from 'node:fs';
 import { createServer } from 'node:net';
+import path from 'node:path';
 import process from 'node:process';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { logger } from '../logger.js';
-import { PipeTransport } from '../third_party/index.js';
+import { Client, PipeTransport, StdioClientTransport, } from '../third_party/index.js';
 import { VERSION } from '../version.js';
-import { getSocketPath, handlePidFile, INDEX_SCRIPT_PATH, IS_WINDOWS, } from './utils.js';
-const pidFile = handlePidFile();
+import { getDaemonPid, getPidFilePath, getSocketPath, INDEX_SCRIPT_PATH, IS_WINDOWS, isDaemonRunning, } from './utils.js';
+const pid = getDaemonPid();
+if (isDaemonRunning(pid)) {
+    logger('Another daemon process is running.');
+    process.exit(1);
+}
+const pidFilePath = getPidFilePath();
+fs.mkdirSync(path.dirname(pidFilePath), {
+    recursive: true,
+});
+fs.writeFileSync(pidFilePath, process.pid.toString());
+logger(`Writing ${process.pid.toString()} to ${pidFilePath}`);
 const socketPath = getSocketPath();
+const startDate = new Date();
+const mcpServerArgs = process.argv.slice(2);
 let mcpClient = null;
 let mcpTransport = null;
 let server = null;
 async function setupMCPClient() {
     console.log('Setting up MCP client connection...');
-    const args = process.argv.slice(2);
     // Create stdio transport for chrome-devtools-mcp
+    // Workaround for https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/src/client/stdio.ts#L128
+    // which causes the console window to show on Windows.
+    // @ts-expect-error no types for type.
+    process.type = 'mcp-client';
     mcpTransport = new StdioClientTransport({
         command: process.execPath,
-        args: [INDEX_SCRIPT_PATH, ...args],
+        args: [INDEX_SCRIPT_PATH, ...mcpServerArgs],
         env: process.env,
     });
     mcpClient = new Client({
@@ -53,7 +67,9 @@ async function handleRequest(msg) {
             };
         }
         else if (msg.method === 'stop') {
-            // Trigger cleanup asynchronously
+            // Ensure we are not interrupting in-progress starting.
+            await started;
+            // Trigger cleanup asynchronously.
             setImmediate(() => {
                 void cleanup();
             });
@@ -62,7 +78,19 @@ async function handleRequest(msg) {
                 message: 'stopping',
             };
         }
-        else {
+        else if (msg.method === 'status') {
+            return {
+                success: true,
+                result: JSON.stringify({
+                    pid: process.pid,
+                    socketPath,
+                    startDate: startDate.toISOString(),
+                    version: VERSION,
+                    args: mcpServerArgs,
+                }),
+            };
+        }
+        {
             return {
                 success: false,
                 error: `Unknown method: ${JSON.stringify(msg, null, 2)}`,
@@ -81,7 +109,7 @@ async function startSocketServer() {
     // Remove existing socket file if it exists (only on non-Windows)
     if (!IS_WINDOWS) {
         try {
-            await fs.unlink(socketPath);
+            fs.unlinkSync(socketPath);
         }
         catch {
             // ignore errors.
@@ -135,12 +163,23 @@ async function cleanup() {
     catch (error) {
         logger('Error closing MCP transport:', error);
     }
-    server?.close(() => {
-        if (!IS_WINDOWS) {
-            void fs.unlink(socketPath).catch(() => undefined);
+    if (server) {
+        await new Promise(resolve => {
+            server.close(() => resolve());
+        });
+    }
+    if (!IS_WINDOWS) {
+        try {
+            fs.unlinkSync(socketPath);
         }
-    });
-    await fs.unlink(pidFile).catch(() => undefined);
+        catch {
+            // ignore errors
+        }
+    }
+    logger(`unlinking ${pidFilePath}`);
+    if (fs.existsSync(pidFilePath)) {
+        fs.unlinkSync(pidFilePath);
+    }
     process.exit(0);
 }
 // Handle shutdown signals
@@ -161,7 +200,7 @@ process.on('unhandledRejection', error => {
     logger('Unhandled rejection:', error);
 });
 // Start the server
-startSocketServer().catch(error => {
+const started = startSocketServer().catch(error => {
     logger('Failed to start daemon server:', error);
     process.exit(1);
 });

package/build/src/daemon/types.js

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/build/src/daemon/utils.js

@@ -7,8 +7,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
+import { logger } from '../logger.js';
 export const DAEMON_SCRIPT_PATH = path.join(import.meta.dirname, 'daemon.js');
-export const INDEX_SCRIPT_PATH = path.join(import.meta.dirname, '..', 'index.js');
+export const INDEX_SCRIPT_PATH = path.join(import.meta.dirname, '..', 'bin', 'chrome-devtools-mcp.js');
 const APP_NAME = 'chrome-devtools-mcp';
 // Using these paths due to strict limits on the POSIX socket path length.
 export function getSocketPath() {
@@ -43,25 +44,65 @@ export function getRuntimeHome() {
     return path.join(os.tmpdir(), APP_NAME);
 }
 export const IS_WINDOWS = os.platform() === 'win32';
-export function handlePidFile() {
+export function getPidFilePath() {
     const runtimeDir = getRuntimeHome();
-    const pidPath = path.join(runtimeDir, 'daemon.pid');
-    if (fs.existsSync(pidPath)) {
-        const oldPid = parseInt(fs.readFileSync(pidPath, 'utf8'), 10);
+    return path.join(runtimeDir, 'daemon.pid');
+}
+export function getDaemonPid() {
+    try {
+        const pidFile = getPidFilePath();
+        logger(`Daemon pid file ${pidFile}`);
+        if (!fs.existsSync(pidFile)) {
+            return null;
+        }
+        const pidContent = fs.readFileSync(pidFile, 'utf-8');
+        const pid = parseInt(pidContent.trim(), 10);
+        logger(`Daemon pid: ${pid}`);
+        if (isNaN(pid)) {
+            return null;
+        }
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}
+export function isDaemonRunning(pid = getDaemonPid()) {
+    if (pid) {
         try {
-            // Sending signal 0 checks if the process is still alive without killing it
-            process.kill(oldPid, 0);
-            console.error('Daemon is already running!');
-            process.exit(1);
+            process.kill(pid, 0); // Throws if process doesn't exist
+            return true;
         }
         catch {
-            // Process is dead, we can safely overwrite the PID file
-            fs.unlinkSync(pidPath);
+            // Process is dead, stale PID file. Proceed with startup.
+        }
+    }
+    return false;
+}
+export function serializeArgs(options, argv) {
+    const args = [];
+    for (const key of Object.keys(options)) {
+        if (argv[key] === undefined || argv[key] === null) {
+            continue;
+        }
+        const value = argv[key];
+        const kebabKey = key.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
+        if (typeof value === 'boolean') {
+            if (value) {
+                args.push(`--${kebabKey}`);
+            }
+            else {
+                args.push(`--no-${kebabKey}`);
+            }
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value) {
+                args.push(`--${kebabKey}`, String(item));
+            }
+        }
+        else {
+            args.push(`--${kebabKey}`, String(value));
         }
     }
-    fs.mkdirSync(path.dirname(pidPath), {
-        recursive: true,
-    });
-    fs.writeFileSync(pidPath, process.pid.toString());
-    return pidPath;
+    return args;
 }

package/build/src/index.js

@@ -1,21 +1,209 @@
-#!/usr/bin/env node
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { version } from 'node:process';
-const [major, minor] = version.substring(1).split('.').map(Number);
-if (major === 20 && minor < 19) {
-    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
-    process.exit(1);
+import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
+import { loadIssueDescriptions } from './issue-descriptions.js';
+import { logger } from './logger.js';
+import { McpContext } from './McpContext.js';
+import { McpResponse } from './McpResponse.js';
+import { Mutex } from './Mutex.js';
+import { SlimMcpResponse } from './SlimMcpResponse.js';
+import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
+import { bucketizeLatency } from './telemetry/metricUtils.js';
+import { McpServer, SetLevelRequestSchema, } from './third_party/index.js';
+import { ToolCategory } from './tools/categories.js';
+import { pageIdSchema } from './tools/ToolDefinition.js';
+import { createTools } from './tools/tools.js';
+import { VERSION } from './version.js';
+export async function createMcpServer(serverArgs, options) {
+    let clearcutLogger;
+    if (serverArgs.usageStatistics) {
+        clearcutLogger = new ClearcutLogger({
+            logFile: serverArgs.logFile,
+            appVersion: VERSION,
+            clearcutEndpoint: serverArgs.clearcutEndpoint,
+            clearcutForceFlushIntervalMs: serverArgs.clearcutForceFlushIntervalMs,
+            clearcutIncludePidHeader: serverArgs.clearcutIncludePidHeader,
+        });
+    }
+    const server = new McpServer({
+        name: 'chrome_devtools',
+        title: 'Chrome DevTools MCP server',
+        version: VERSION,
+    }, { capabilities: { logging: {} } });
+    server.server.setRequestHandler(SetLevelRequestSchema, () => {
+        return {};
+    });
+    let context;
+    async function getContext() {
+        const chromeArgs = (serverArgs.chromeArg ?? []).map(String);
+        const ignoreDefaultChromeArgs = (serverArgs.ignoreDefaultChromeArg ?? []).map(String);
+        if (serverArgs.proxyServer) {
+            chromeArgs.push(`--proxy-server=${serverArgs.proxyServer}`);
+        }
+        const devtools = serverArgs.experimentalDevtools ?? false;
+        const browser = serverArgs.browserUrl || serverArgs.wsEndpoint || serverArgs.autoConnect
+            ? await ensureBrowserConnected({
+                browserURL: serverArgs.browserUrl,
+                wsEndpoint: serverArgs.wsEndpoint,
+                wsHeaders: serverArgs.wsHeaders,
+                // Important: only pass channel, if autoConnect is true.
+                channel: serverArgs.autoConnect
+                    ? serverArgs.channel
+                    : undefined,
+                userDataDir: serverArgs.userDataDir,
+                devtools,
+            })
+            : await ensureBrowserLaunched({
+                headless: serverArgs.headless,
+                executablePath: serverArgs.executablePath,
+                channel: serverArgs.channel,
+                isolated: serverArgs.isolated ?? false,
+                userDataDir: serverArgs.userDataDir,
+                logFile: options.logFile,
+                viewport: serverArgs.viewport,
+                chromeArgs,
+                ignoreDefaultChromeArgs,
+                acceptInsecureCerts: serverArgs.acceptInsecureCerts,
+                devtools,
+                enableExtensions: serverArgs.categoryExtensions,
+                viaCli: serverArgs.viaCli,
+            });
+        if (context?.browser !== browser) {
+            context = await McpContext.from(browser, logger, {
+                experimentalDevToolsDebugging: devtools,
+                experimentalIncludeAllPages: serverArgs.experimentalIncludeAllPages,
+                performanceCrux: serverArgs.performanceCrux,
+            });
+        }
+        return context;
+    }
+    const toolMutex = new Mutex();
+    function registerTool(tool) {
+        if (tool.annotations.category === ToolCategory.EMULATION &&
+            serverArgs.categoryEmulation === false) {
+            return;
+        }
+        if (tool.annotations.category === ToolCategory.PERFORMANCE &&
+            serverArgs.categoryPerformance === false) {
+            return;
+        }
+        if (tool.annotations.category === ToolCategory.NETWORK &&
+            serverArgs.categoryNetwork === false) {
+            return;
+        }
+        if (tool.annotations.category === ToolCategory.EXTENSIONS &&
+            serverArgs.categoryExtensions === false) {
+            return;
+        }
+        if (tool.annotations.conditions?.includes('computerVision') &&
+            !serverArgs.experimentalVision) {
+            return;
+        }
+        if (tool.annotations.conditions?.includes('experimentalInteropTools') &&
+            !serverArgs.experimentalInteropTools) {
+            return;
+        }
+        if (tool.annotations.conditions?.includes('screencast') &&
+            !serverArgs.experimentalScreencast) {
+            return;
+        }
+        const schema = 'pageScoped' in tool &&
+            tool.pageScoped &&
+            serverArgs.experimentalPageIdRouting &&
+            !serverArgs.slim
+            ? { ...tool.schema, ...pageIdSchema }
+            : tool.schema;
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: schema,
+            annotations: tool.annotations,
+        }, async (params) => {
+            const guard = await toolMutex.acquire();
+            const startTime = Date.now();
+            let success = false;
+            try {
+                logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+                const context = await getContext();
+                logger(`${tool.name} context: resolved`);
+                await context.detectOpenDevToolsWindows();
+                const response = serverArgs.slim
+                    ? new SlimMcpResponse(serverArgs)
+                    : new McpResponse(serverArgs);
+                if ('pageScoped' in tool && tool.pageScoped) {
+                    const page = serverArgs.experimentalPageIdRouting &&
+                        params.pageId &&
+                        !serverArgs.slim
+                        ? context.getPageById(params.pageId)
+                        : context.getSelectedMcpPage();
+                    response.setPage(page);
+                    await tool.handler({
+                        params,
+                        page,
+                    }, response, context);
+                }
+                else {
+                    await tool.handler(
+                    // @ts-expect-error types do not match.
+                    {
+                        params,
+                    }, response, context);
+                }
+                const { content, structuredContent } = await response.handle(tool.name, context);
+                const result = {
+                    content,
+                };
+                success = true;
+                if (serverArgs.experimentalStructuredContent) {
+                    result.structuredContent = structuredContent;
+                }
+                return result;
+            }
+            catch (err) {
+                logger(`${tool.name} error:`, err, err?.stack);
+                let errorText = err && 'message' in err ? err.message : String(err);
+                if ('cause' in err && err.cause) {
+                    errorText += `\nCause: ${err.cause.message}`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: errorText,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            finally {
+                void clearcutLogger?.logToolInvocation({
+                    toolName: tool.name,
+                    success,
+                    latencyMs: bucketizeLatency(Date.now() - startTime),
+                });
+                guard.dispose();
+            }
+        });
+    }
+    const tools = createTools(serverArgs);
+    for (const tool of tools) {
+        registerTool(tool);
+    }
+    await loadIssueDescriptions();
+    return { server, clearcutLogger };
 }
-if (major === 22 && minor < 12) {
-    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 22.12.0 LTS or a newer LTS.`);
-    process.exit(1);
-}
-if (major < 20) {
-    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
-    process.exit(1);
-}
-await import('./main.js');
+export const logDisclaimers = (args) => {
+    console.error(`chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
+debug, and modify any data in the browser or DevTools.
+Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
+    if (!args.slim && args.performanceCrux) {
+        console.error(`Performance tools may send trace URLs to the Google CrUX API to fetch real-user experience data. To disable, run with --no-performance-crux.`);
+    }
+    if (!args.slim && args.usageStatistics) {
+        console.error(`
+Google collects usage statistics to improve Chrome DevTools MCP. To opt-out, run with --no-usage-statistics.
+For more details, visit: https://github.com/ChromeDevTools/chrome-devtools-mcp#usage-statistics`);
+    }
+};

package/build/src/telemetry/watchdog/ClearcutSender.js

@@ -125,6 +125,7 @@ export class ClearcutSender {
         });
     }
     #scheduleFlush(delayMs) {
+        logger(`Scheduling flush in ${delayMs}`);
         if (this.#flushTimer) {
             clearTimeout(this.#flushTimer);
         }
@@ -135,6 +136,7 @@ export class ClearcutSender {
         }, delayMs);
     }
     async #sendBatch(events) {
+        logger(`Sending batch of ${events.length}`);
         const requestBody = {
             log_source: LOG_SOURCE,
             request_time_ms: Date.now().toString(),