@mcp-b/chrome-devtools-mcp 2.0.13 → 2.2.0

package/build/src/browser.js

@@ -3,86 +3,23 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { logger } from './logger.js';
 import { puppeteer } from './third_party/index.js';
-/** Cached browser instance for reuse across calls. */
 let browser;
-/**
- * Get Chrome's default user data directory for the given platform and channel.
- *
- * @returns The platform-specific path to Chrome's user data directory.
- */
-function getChromeDefaultUserDataDir(channel = 'stable') {
-    const platform = os.platform();
-    if (platform === 'darwin') {
-        const suffix = channel === 'stable'
-            ? ''
-            : ` ${channel.charAt(0).toUpperCase() + channel.slice(1)}`;
-        return path.join(os.homedir(), 'Library', 'Application Support', 'Google', `Chrome${suffix}`);
-    }
-    if (platform === 'win32') {
-        const appData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
-        const suffix = channel === 'stable'
-            ? ''
-            : ` ${channel.charAt(0).toUpperCase() + channel.slice(1)}`;
-        return path.join(appData, 'Google', `Chrome${suffix}`, 'User Data');
+function makeTargetFilter(enableExtensions = false) {
+    const ignoredPrefixes = new Set(['chrome://', 'chrome-untrusted://']);
+    if (!enableExtensions) {
+        ignoredPrefixes.add('chrome-extension://');
     }
-    // Linux
-    const channelSuffix = channel === 'stable'
-        ? ''
-        : channel === 'beta'
-            ? '-beta'
-            : '-unstable';
-    return path.join(os.homedir(), '.config', `google-chrome${channelSuffix}`);
-}
-/**
- * Try to read a WebSocket endpoint from a DevToolsActivePort file.
- *
- * @param userDataDir - Directory containing the DevToolsActivePort file.
- * @returns The WebSocket endpoint URL, or undefined if the file doesn't exist or is invalid.
- */
-function readDevToolsActivePort(userDataDir) {
-    const portPath = path.join(userDataDir, 'DevToolsActivePort');
-    try {
-        const fileContent = fs.readFileSync(portPath, 'utf8');
-        const [rawPort, rawPath] = fileContent
-            .split('\n')
-            .map(line => line.trim())
-            .filter(line => !!line);
-        if (!rawPort || !rawPath) {
-            return undefined;
-        }
-        const port = parseInt(rawPort, 10);
-        if (isNaN(port) || port <= 0 || port > 65535) {
-            return undefined;
-        }
-        return `ws://127.0.0.1:${port}${rawPath}`;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Create a target filter for Puppeteer that excludes internal Chrome pages.
- *
- * Includes new tab and inspect pages (may be the only user-accessible page),
- * but excludes chrome://, chrome-extension://, and chrome-untrusted:// pages.
- *
- * @returns A filter function for Puppeteer's targetFilter option.
- */
-function makeTargetFilter(includeExtensionPages = false) {
-    const ignoredPrefixes = new Set([
-        'chrome://',
-        ...(includeExtensionPages ? [] : ['chrome-extension://']),
-        'chrome-untrusted://',
-    ]);
     return function targetFilter(target) {
         if (target.url() === 'chrome://newtab/') {
             return true;
         }
+        // Could be the only page opened in the browser.
         if (target.url().startsWith('chrome://inspect')) {
             return true;
         }
@@ -94,33 +31,17 @@ function makeTargetFilter(includeExtensionPages = false) {
         return true;
     };
 }
-/**
- * Connect to an existing Chrome browser instance.
- *
- * Connection priority:
- * 1. wsEndpoint - Direct WebSocket connection with optional headers
- * 2. browserURL - HTTP URL to Chrome's DevTools endpoint
- * 3. userDataDir - Read DevToolsActivePort from profile directory
- * 4. channel - Derive profile directory from channel name
- *
- * @param options - Connection options.
- * @returns Connected browser instance.
- * @throws Error if connection fails or no connection method specified.
- */
 export async function ensureBrowserConnected(options) {
-    const { channel, includeExtensionPages } = options;
+    const { channel, enableExtensions } = options;
     if (browser?.connected) {
         return browser;
     }
     const connectOptions = {
-        targetFilter: makeTargetFilter(includeExtensionPages),
+        targetFilter: makeTargetFilter(enableExtensions),
         defaultViewport: null,
         handleDevToolsAsPage: true,
-        ...(includeExtensionPages && {
-            isPageTargetCallback: (target) => target.type() === 'page' ||
-                target.url().startsWith('chrome-extension://'),
-        }),
     };
+    let autoConnect = false;
     if (options.wsEndpoint) {
         connectOptions.browserWSEndpoint = options.wsEndpoint;
         if (options.wsHeaders) {
@@ -133,59 +54,40 @@ export async function ensureBrowserConnected(options) {
     else if (channel || options.userDataDir) {
         const userDataDir = options.userDataDir;
         if (userDataDir) {
-            // Explicit user data dir provided
-            const wsEndpoint = readDevToolsActivePort(userDataDir);
-            if (wsEndpoint) {
-                connectOptions.browserWSEndpoint = wsEndpoint;
+            autoConnect = true;
+            // TODO: re-expose this logic via Puppeteer.
+            const portPath = path.join(userDataDir, 'DevToolsActivePort');
+            try {
+                const fileContent = await fs.promises.readFile(portPath, 'utf8');
+                const [rawPort, rawPath] = fileContent
+                    .split('\n')
+                    .map(line => {
+                    return line.trim();
+                })
+                    .filter(line => {
+                    return !!line;
+                });
+                if (!rawPort || !rawPath) {
+                    throw new Error(`Invalid DevToolsActivePort '${fileContent}' found`);
+                }
+                const port = parseInt(rawPort, 10);
+                if (isNaN(port) || port <= 0 || port > 65535) {
+                    throw new Error(`Invalid port '${rawPort}' found`);
+                }
+                const browserWSEndpoint = `ws://127.0.0.1:${port}${rawPath}`;
+                connectOptions.browserWSEndpoint = browserWSEndpoint;
             }
-            else {
-                throw new Error(`Could not connect to Chrome in ${userDataDir}. Check if Chrome is running and remote debugging is enabled.`);
+            catch (error) {
+                throw new Error(`Could not connect to Chrome in ${userDataDir}. Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.`, {
+                    cause: error,
+                });
             }
         }
         else {
             if (!channel) {
                 throw new Error('Channel must be provided if userDataDir is missing');
             }
-            // Collect candidate WebSocket endpoints from multiple directories.
-            // Try each one in order — stale DevToolsActivePort files are common,
-            // so we attempt the actual connection before moving to the next.
-            const profileDirName = channel && channel !== 'stable'
-                ? `chrome-profile-${channel}`
-                : 'chrome-profile';
-            const mcpUserDataDir = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', profileDirName);
-            const chromeUserDataDir = getChromeDefaultUserDataDir(channel);
-            // Chrome's default profile is checked first — this is the user's
-            // real browser with remote debugging enabled via chrome://inspect.
-            // The MCP cache dir is checked second as a fallback for instances
-            // launched by the MCP server itself.
-            const candidates = [];
-            const chromeWsEndpoint = readDevToolsActivePort(chromeUserDataDir);
-            if (chromeWsEndpoint) {
-                candidates.push({ dir: chromeUserDataDir, wsEndpoint: chromeWsEndpoint });
-            }
-            const mcpWsEndpoint = readDevToolsActivePort(mcpUserDataDir);
-            if (mcpWsEndpoint) {
-                candidates.push({ dir: mcpUserDataDir, wsEndpoint: mcpWsEndpoint });
-            }
-            if (candidates.length === 0) {
-                throw new Error(`Could not connect to Chrome ${channel} channel. Checked ${mcpUserDataDir} and ${chromeUserDataDir}. Ensure Chrome is running with remote debugging enabled (chrome://inspect/#remote-debugging).`);
-            }
-            // Try each candidate endpoint, returning the first that connects
-            for (const candidate of candidates) {
-                try {
-                    logger(`Trying DevToolsActivePort from ${candidate.dir}: ${candidate.wsEndpoint}`);
-                    browser = await puppeteer.connect({
-                        ...connectOptions,
-                        browserWSEndpoint: candidate.wsEndpoint,
-                    });
-                    logger(`Connected via ${candidate.dir}`);
-                    return browser;
-                }
-                catch (err) {
-                    logger(`Failed to connect via ${candidate.dir}: ${err.message}`);
-                }
-            }
-            throw new Error(`Could not connect to Chrome ${channel} channel. Tried ${candidates.map(c => c.dir).join(' and ')}. Ensure Chrome is running with remote debugging enabled (chrome://inspect/#remote-debugging).`);
+            connectOptions.channel = (channel === 'stable' ? 'chrome' : `chrome-${channel}`);
         }
     }
     else {
@@ -196,20 +98,29 @@ export async function ensureBrowserConnected(options) {
         browser = await puppeteer.connect(connectOptions);
     }
     catch (err) {
-        throw new Error('Could not connect to Chrome. Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.', {
+        throw new Error(`Could not connect to Chrome. ${autoConnect ? `Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.` : `Check if Chrome is running.`}`, {
             cause: err,
         });
     }
     logger('Connected Puppeteer');
     return browser;
 }
-/**
- * Launch a new Chrome browser instance.
- *
- * @param options - Launch configuration options.
- * @returns Launched browser instance.
- * @throws Error if Chrome is already running with the same profile.
- */
+export function detectDisplay() {
+    // Only detect display on Linux/UNIX.
+    if (os.platform() === 'win32' || os.platform() === 'darwin') {
+        return;
+    }
+    if (!process.env['DISPLAY']) {
+        try {
+            const result = execSync(`ps -u $(id -u) -o pid= | xargs -I{} cat /proc/{}/environ 2>/dev/null | tr '\\0' '\\n' | grep -m1 '^DISPLAY=' | cut -d= -f2`);
+            const display = result.toString('utf8').trim();
+            process.env['DISPLAY'] = display;
+        }
+        catch {
+            // no-op
+        }
+    }
+}
 export async function launch(options) {
     const { channel, executablePath, headless, isolated } = options;
     const profileDirName = channel && channel !== 'stable'
@@ -217,26 +128,16 @@ export async function launch(options) {
         : 'chrome-profile';
     let userDataDir = options.userDataDir;
     if (!isolated && !userDataDir) {
-        userDataDir = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', profileDirName);
+        userDataDir = path.join(os.homedir(), '.cache', options.viaCli ? 'chrome-devtools-mcp-cli' : 'chrome-devtools-mcp', profileDirName);
         await fs.promises.mkdir(userDataDir, {
             recursive: true,
         });
     }
-    const extraArgs = options.args ?? [];
-    const hasRemoteDebuggingPipe = extraArgs.includes('--remote-debugging-pipe');
-    const hasRemoteDebuggingPort = extraArgs.some(arg => arg.startsWith('--remote-debugging-port'));
-    const hasRemoteDebuggingAddress = extraArgs.some(arg => arg.startsWith('--remote-debugging-address'));
     const args = [
-        ...extraArgs,
+        ...(options.chromeArgs ?? []),
         '--hide-crash-restore-bubble',
     ];
-    const enableRemoteDebuggingPort = !isolated && !hasRemoteDebuggingPipe && !hasRemoteDebuggingPort;
-    if (enableRemoteDebuggingPort) {
-        args.push('--remote-debugging-port=0');
-        if (!hasRemoteDebuggingAddress) {
-            args.push('--remote-debugging-address=127.0.0.1');
-        }
-    }
+    const ignoreDefaultArgs = options.ignoreDefaultChromeArgs ?? false;
     if (headless) {
         args.push('--screen-info={3840x2160}');
     }
@@ -250,25 +151,23 @@ export async function launch(options) {
                 ? `chrome-${channel}`
                 : 'chrome';
     }
-    const usePipe = hasRemoteDebuggingPipe ||
-        (!hasRemoteDebuggingPort && !enableRemoteDebuggingPort);
+    if (!headless) {
+        detectDisplay();
+    }
     try {
         const browser = await puppeteer.launch({
             channel: puppeteerChannel,
-            targetFilter: makeTargetFilter(options.includeExtensionPages),
+            targetFilter: makeTargetFilter(options.enableExtensions),
             executablePath,
             defaultViewport: null,
             userDataDir,
-            pipe: usePipe,
+            pipe: true,
             headless,
             args,
+            ignoreDefaultArgs: ignoreDefaultArgs,
             acceptInsecureCerts: options.acceptInsecureCerts,
             handleDevToolsAsPage: true,
-            ...(options.includeExtensionPages && {
-                enableExtensions: true,
-                isPageTargetCallback: (target) => target.type === 'page' ||
-                    target.url?.startsWith('chrome-extension://') === true,
-            }),
+            enableExtensions: options.enableExtensions,
         });
         if (options.logFile) {
             // FIXME: we are probably subscribing too late to catch startup logs. We
@@ -295,12 +194,6 @@ export async function launch(options) {
         throw error;
     }
 }
-/**
- * Ensure a browser is launched, reusing existing instance if connected.
- *
- * @param options - Launch configuration options.
- * @returns Connected or newly launched browser instance.
- */
 export async function ensureBrowserLaunched(options) {
     if (browser?.connected) {
         return browser;
@@ -308,51 +201,3 @@ export async function ensureBrowserLaunched(options) {
     browser = await launch(options);
     return browser;
 }
-/**
- * Disconnect from the current browser without killing the process.
- * Clears the cached browser reference so future calls can connect to a new instance.
- */
-export function disconnectBrowser() {
-    if (browser) {
-        try {
-            browser.disconnect();
-        }
-        catch {
-            // Ignore disconnect errors — browser may already be gone
-        }
-        browser = undefined;
-    }
-}
-/**
- * Connect to a new browser instance, replacing the cached reference.
- *
- * @param options - Connection options (browserURL or wsEndpoint).
- * @returns Connected browser instance.
- */
-export async function connectToNewBrowser(options) {
-    const connectOptions = {
-        targetFilter: makeTargetFilter(options.includeExtensionPages),
-        defaultViewport: null,
-        handleDevToolsAsPage: true,
-        ...(options.includeExtensionPages && {
-            isPageTargetCallback: (target) => target.type() === 'page' ||
-                target.url().startsWith('chrome-extension://'),
-        }),
-    };
-    if (options.wsEndpoint) {
-        connectOptions.browserWSEndpoint = options.wsEndpoint;
-        if (options.wsHeaders) {
-            connectOptions.headers = options.wsHeaders;
-        }
-    }
-    else if (options.browserURL) {
-        connectOptions.browserURL = options.browserURL;
-    }
-    else {
-        throw new Error('Either browserURL or wsEndpoint must be provided');
-    }
-    logger('Connecting Puppeteer to new browser:', JSON.stringify(connectOptions));
-    browser = await puppeteer.connect(connectOptions);
-    logger('Connected to new browser');
-    return browser;
-}

package/build/src/daemon/client.js

@@ -0,0 +1,176 @@
+/**
+ * @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;
+function fileExtensionForMimeType(mimeType) {
+    switch (mimeType) {
+        case 'image/png':
+            return '.png';
+        case 'image/jpg':
+        case 'image/jpeg':
+            return '.jpeg';
+        case 'image/webp':
+            return '.webp';
+        case 'text/plain':
+            return '.txt';
+        case 'application/json':
+            return '.json';
+        default:
+            return '.bin';
+    }
+}
+/**
+ * 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;
+            const extension = fileExtensionForMimeType(mimeType);
+            const data = Buffer.from(imageData, 'base64');
+            const name = crypto.randomUUID();
+            const { filepath } = await saveTemporaryFile(data, `${name}${extension}`);
+            chunks.push(`Saved to ${filepath}.`);
+        }
+        else if (content.type === 'resource') {
+            const resource = content.resource;
+            if ('text' in resource && typeof resource.text === 'string') {
+                chunks.push(resource.text);
+                continue;
+            }
+            if ('blob' in resource && typeof resource.blob === 'string') {
+                const extension = fileExtensionForMimeType(resource.mimeType);
+                const data = Buffer.from(resource.blob, 'base64');
+                const name = crypto.randomUUID();
+                const { filepath } = await saveTemporaryFile(data, `${name}${extension}`);
+                chunks.push(`Saved resource ${resource.uri} to ${filepath}.`);
+                continue;
+            }
+            chunks.push(resource.uri);
+        }
+        else {
+            throw new Error('Not supported response content type');
+        }
+    }
+    return format === 'md' ? chunks.join(' ') : JSON.stringify(chunks);
+}