@vibebrowser/chrome-devtools-mcp 0.26.0

package/build/src/bin/install-service.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_PORT = 9333;
+function getNodePath() {
+    return process.execPath;
+}
+function getBinPath() {
+    return path.resolve(__dirname, 'chrome-devtools-mcp.js');
+}
+function printMcpConfig(url) {
+    console.log(`\nAdd to your agent config (opencode, copilot, claude, etc.):\n`);
+    console.log(JSON.stringify({
+        mcpServers: {
+            'chrome-devtools': { url },
+        },
+    }, null, 2));
+    console.log('');
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let port = DEFAULT_PORT;
+    let tailscale = false;
+    let action = 'install';
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--port' || args[i] === '-p') {
+            port = parseInt(args[++i], 10);
+        }
+        else if (args[i] === '--tailscale') {
+            tailscale = true;
+        }
+        else if (args[i] === 'uninstall') {
+            action = 'uninstall';
+        }
+        else if (args[i] === 'status') {
+            action = 'status';
+        }
+    }
+    return { port, action, tailscale };
+}
+function installMacOS(port) {
+    const templatePath = path.resolve(__dirname, 'service', 'com.vibebrowser.chrome-devtools-mcp.plist.template');
+    const template = fs.readFileSync(templatePath, 'utf-8');
+    const logDir = path.join(process.env['HOME'] || '/tmp', 'Library', 'Logs', 'chrome-devtools-mcp');
+    fs.mkdirSync(logDir, { recursive: true });
+    const plist = template
+        .replaceAll('{{NODE_PATH}}', getNodePath())
+        .replaceAll('{{BIN_PATH}}', getBinPath())
+        .replaceAll('{{PORT}}', String(port))
+        .replaceAll('{{LOG_DIR}}', logDir);
+    const plistDir = path.join(process.env['HOME'] || '/tmp', 'Library', 'LaunchAgents');
+    fs.mkdirSync(plistDir, { recursive: true });
+    const plistPath = path.join(plistDir, 'com.vibebrowser.chrome-devtools-mcp.plist');
+    // Unload if already loaded
+    try {
+        execSync(`launchctl unload "${plistPath}" 2>/dev/null`);
+    }
+    catch {
+        // ignore
+    }
+    fs.writeFileSync(plistPath, plist);
+    execSync(`launchctl load "${plistPath}"`);
+    console.log(`✅ Installed and started launchd service`);
+    console.log(`   Plist: ${plistPath}`);
+    console.log(`   Logs:  ${logDir}/`);
+    console.log(`   URL:   http://localhost:${port}/mcp`);
+}
+function uninstallMacOS() {
+    const plistPath = path.join(process.env['HOME'] || '/tmp', 'Library', 'LaunchAgents', 'com.vibebrowser.chrome-devtools-mcp.plist');
+    try {
+        execSync(`launchctl unload "${plistPath}" 2>/dev/null`);
+    }
+    catch {
+        // ignore
+    }
+    if (fs.existsSync(plistPath)) {
+        fs.unlinkSync(plistPath);
+        console.log(`✅ Uninstalled launchd service`);
+    }
+    else {
+        console.log(`⚠️  Service not installed`);
+    }
+}
+function statusMacOS() {
+    try {
+        const output = execSync('launchctl list com.vibebrowser.chrome-devtools-mcp 2>&1', { encoding: 'utf-8' });
+        console.log(`Service status:\n${output}`);
+    }
+    catch {
+        console.log('Service is not loaded');
+    }
+}
+function installLinux(port) {
+    const templatePath = path.resolve(__dirname, 'service', 'chrome-devtools-mcp.service.template');
+    const template = fs.readFileSync(templatePath, 'utf-8');
+    const service = template
+        .replaceAll('{{NODE_PATH}}', getNodePath())
+        .replaceAll('{{BIN_PATH}}', getBinPath())
+        .replaceAll('{{PORT}}', String(port));
+    const serviceDir = path.join(process.env['HOME'] || '/tmp', '.config', 'systemd', 'user');
+    fs.mkdirSync(serviceDir, { recursive: true });
+    const servicePath = path.join(serviceDir, 'chrome-devtools-mcp.service');
+    fs.writeFileSync(servicePath, service);
+    execSync('systemctl --user daemon-reload');
+    execSync('systemctl --user enable chrome-devtools-mcp.service');
+    execSync('systemctl --user start chrome-devtools-mcp.service');
+    console.log(`✅ Installed and started systemd user service`);
+    console.log(`   Unit:  ${servicePath}`);
+    console.log(`   URL:   http://localhost:${port}/mcp`);
+    console.log(`   Logs:  journalctl --user -u chrome-devtools-mcp`);
+}
+function uninstallLinux() {
+    try {
+        execSync('systemctl --user stop chrome-devtools-mcp.service 2>/dev/null');
+        execSync('systemctl --user disable chrome-devtools-mcp.service 2>/dev/null');
+    }
+    catch {
+        // ignore
+    }
+    const servicePath = path.join(process.env['HOME'] || '/tmp', '.config', 'systemd', 'user', 'chrome-devtools-mcp.service');
+    if (fs.existsSync(servicePath)) {
+        fs.unlinkSync(servicePath);
+        execSync('systemctl --user daemon-reload');
+        console.log(`✅ Uninstalled systemd service`);
+    }
+    else {
+        console.log(`⚠️  Service not installed`);
+    }
+}
+function statusLinux() {
+    try {
+        const output = execSync('systemctl --user status chrome-devtools-mcp.service 2>&1', { encoding: 'utf-8' });
+        console.log(output);
+    }
+    catch (e) {
+        console.log(e.stdout || 'Service is not installed');
+    }
+}
+function installTailscale(port) {
+    // Check tailscale is available
+    try {
+        execSync('tailscale version', { stdio: 'pipe' });
+    }
+    catch {
+        console.error('❌ tailscale CLI not found. Install from https://tailscale.com/download');
+        process.exit(1);
+    }
+    // Check tailscale is connected
+    try {
+        const status = execSync('tailscale status --json', { encoding: 'utf-8', stdio: 'pipe' });
+        const parsed = JSON.parse(status);
+        if (parsed.BackendState !== 'Running') {
+            console.error('❌ Tailscale is not connected. Run: tailscale up');
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error('❌ Could not get tailscale status. Is it running?');
+        process.exit(1);
+    }
+    // Expose via tailscale serve
+    try {
+        execSync(`tailscale serve --bg --https=443 http://localhost:${port}`, {
+            stdio: 'inherit',
+        });
+    }
+    catch {
+        // Retry without --https (older tailscale versions)
+        try {
+            execSync(`tailscale serve --bg ${port}`, { stdio: 'inherit' });
+        }
+        catch (e) {
+            console.error('❌ Failed to configure tailscale serve:', e.message);
+            process.exit(1);
+        }
+    }
+    // Get the tailscale hostname
+    try {
+        const dnsName = execSync('tailscale status --json', { encoding: 'utf-8', stdio: 'pipe' });
+        const parsed = JSON.parse(dnsName);
+        const self = parsed.Self;
+        const hostname = self?.DNSName?.replace(/\.$/, '') || '<your-machine>.tailnet.ts.net';
+        console.log(`\n✅ Tailscale serve configured`);
+        console.log(`   Remote URL: https://${hostname}/mcp`);
+        console.log(`   Accessible from any device on your tailnet`);
+        printMcpConfig(`https://${hostname}/mcp`);
+    }
+    catch {
+        console.log(`\n✅ Tailscale serve configured`);
+        console.log(`   Remote URL: https://<your-machine>.tailnet.ts.net/mcp`);
+        printMcpConfig('https://<your-machine>.tailnet.ts.net/mcp');
+    }
+}
+function uninstallTailscale(port) {
+    try {
+        execSync(`tailscale serve --remove / 2>/dev/null`, { stdio: 'pipe' });
+        console.log('✅ Removed tailscale serve');
+    }
+    catch {
+        // ignore — might not have been configured
+    }
+}
+// Main
+const { port, action, tailscale } = parseArgs();
+const platform = process.platform;
+if (platform === 'darwin') {
+    if (action === 'install')
+        installMacOS(port);
+    else if (action === 'uninstall') {
+        uninstallTailscale(port);
+        uninstallMacOS();
+    }
+    else
+        statusMacOS();
+}
+else if (platform === 'linux') {
+    if (action === 'install')
+        installLinux(port);
+    else if (action === 'uninstall') {
+        uninstallTailscale(port);
+        uninstallLinux();
+    }
+    else
+        statusLinux();
+}
+else {
+    console.error(`❌ Unsupported platform: ${platform}`);
+    console.error('   Supported: macOS (launchd), Linux (systemd)');
+    process.exit(1);
+}
+if (action === 'install' && tailscale) {
+    installTailscale(port);
+}
+else if (action === 'install') {
+    printMcpConfig(`http://localhost:${port}/mcp`);
+}
+//# sourceMappingURL=install-service.js.map

package/build/src/bin/service/chrome-devtools-mcp.service.template

@@ -0,0 +1,17 @@
+[Unit]
+Description=Chrome DevTools MCP Server (Streamable HTTP)
+After=network.target
+
+[Service]
+Type=simple
+ExecStart={{NODE_PATH}} --max-old-space-size=4096 {{BIN_PATH}} --autoConnect --experimentalPageIdRouting --port {{PORT}}
+Restart=on-failure
+RestartSec=5
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+Environment=CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1
+Environment=CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target

package/build/src/bin/service/com.vibebrowser.chrome-devtools-mcp.plist.template

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.vibebrowser.chrome-devtools-mcp</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{NODE_PATH}}</string>
+    <string>--max-old-space-size=4096</string>
+    <string>{{BIN_PATH}}</string>
+    <string>--autoConnect</string>
+    <string>--experimentalPageIdRouting</string>
+    <string>--port</string>
+    <string>{{PORT}}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>{{LOG_DIR}}/chrome-devtools-mcp.stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>{{LOG_DIR}}/chrome-devtools-mcp.stderr.log</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+    <key>CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS</key>
+    <string>1</string>
+    <key>CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS</key>
+    <string>1</string>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+</dict>
+</plist>

package/build/src/browser.js

@@ -0,0 +1,204 @@
+/**
+ * @license
+ * 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';
+let browser;
+function makeTargetFilter(enableExtensions = false) {
+    const ignoredPrefixes = new Set(['chrome://', 'chrome-untrusted://']);
+    if (!enableExtensions) {
+        ignoredPrefixes.add('chrome-extension://');
+    }
+    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;
+        }
+        for (const prefix of ignoredPrefixes) {
+            if (target.url().startsWith(prefix)) {
+                return false;
+            }
+        }
+        return true;
+    };
+}
+export async function ensureBrowserConnected(options) {
+    const { channel, enableExtensions } = options;
+    if (browser?.connected) {
+        return browser;
+    }
+    const connectOptions = {
+        targetFilter: makeTargetFilter(enableExtensions),
+        defaultViewport: null,
+        handleDevToolsAsPage: true,
+    };
+    let autoConnect = false;
+    if (options.wsEndpoint) {
+        connectOptions.browserWSEndpoint = options.wsEndpoint;
+        if (options.wsHeaders) {
+            connectOptions.headers = options.wsHeaders;
+        }
+    }
+    else if (options.browserURL) {
+        connectOptions.browserURL = options.browserURL;
+    }
+    else if (channel || options.userDataDir) {
+        const userDataDir = options.userDataDir;
+        if (userDataDir) {
+            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;
+            }
+            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');
+            }
+            connectOptions.channel = (channel === 'stable' ? 'chrome' : `chrome-${channel}`);
+        }
+    }
+    else {
+        throw new Error('Either browserURL, wsEndpoint, channel or userDataDir must be provided');
+    }
+    logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
+    try {
+        browser = await puppeteer.connect(connectOptions);
+    }
+    catch (err) {
+        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;
+}
+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'
+        ? `chrome-profile-${channel}`
+        : 'chrome-profile';
+    let userDataDir = options.userDataDir;
+    if (!isolated && !userDataDir) {
+        userDataDir = path.join(os.homedir(), '.cache', options.viaCli ? 'chrome-devtools-mcp-cli' : 'chrome-devtools-mcp', profileDirName);
+        await fs.promises.mkdir(userDataDir, {
+            recursive: true,
+        });
+    }
+    const args = [
+        ...(options.chromeArgs ?? []),
+        '--hide-crash-restore-bubble',
+    ];
+    const ignoreDefaultArgs = options.ignoreDefaultChromeArgs ?? false;
+    if (headless) {
+        args.push('--screen-info={3840x2160}');
+    }
+    let puppeteerChannel;
+    if (options.devtools) {
+        args.push('--auto-open-devtools-for-tabs');
+    }
+    if (!executablePath) {
+        puppeteerChannel =
+            channel && channel !== 'stable'
+                ? `chrome-${channel}`
+                : 'chrome';
+    }
+    if (!headless) {
+        detectDisplay();
+    }
+    try {
+        const browser = await puppeteer.launch({
+            channel: puppeteerChannel,
+            targetFilter: makeTargetFilter(options.enableExtensions),
+            executablePath,
+            defaultViewport: null,
+            userDataDir,
+            pipe: true,
+            headless,
+            args,
+            ignoreDefaultArgs: ignoreDefaultArgs,
+            acceptInsecureCerts: options.acceptInsecureCerts,
+            handleDevToolsAsPage: true,
+            enableExtensions: options.enableExtensions,
+        });
+        if (options.logFile) {
+            // FIXME: we are probably subscribing too late to catch startup logs. We
+            // should expose the process earlier or expose the getRecentLogs() getter.
+            browser.process()?.stderr?.pipe(options.logFile);
+            browser.process()?.stdout?.pipe(options.logFile);
+        }
+        if (options.viewport) {
+            const [page] = await browser.pages();
+            await page?.resize({
+                contentWidth: options.viewport.width,
+                contentHeight: options.viewport.height,
+            });
+        }
+        return browser;
+    }
+    catch (error) {
+        if (userDataDir &&
+            error.message.includes('The browser is already running')) {
+            throw new Error(`The browser is already running for ${userDataDir}. Use --isolated to run multiple browser instances.`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}
+export async function ensureBrowserLaunched(options) {
+    if (browser?.connected) {
+        return browser;
+    }
+    browser = await launch(options);
+    return browser;
+}
+//# sourceMappingURL=browser.js.map

package/build/src/daemon/client.js

@@ -0,0 +1,154 @@
+/**
+ * @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 { getTempFilePath } 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 = [], sessionId) {
+    if (isDaemonRunning(sessionId)) {
+        logger('Daemon is already running');
+        return;
+    }
+    const pidFilePath = getPidFilePath(sessionId);
+    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, CHROME_DEVTOOLS_MCP_SESSION_ID: sessionId },
+        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, sessionId) {
+    const socketPath = getSocketPath(sessionId);
+    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(sessionId) {
+    if (!isDaemonRunning(sessionId)) {
+        logger('Daemon is not running');
+        return;
+    }
+    const pidFilePath = getPidFilePath(sessionId);
+    await sendCommand({ method: 'stop' }, sessionId);
+    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 'image/webp':
+                    extension = '.webp';
+                    break;
+            }
+            const data = Buffer.from(imageData, 'base64');
+            const name = crypto.randomUUID();
+            const filepath = await getTempFilePath(`${name}${extension}`);
+            fs.writeFileSync(filepath, data);
+            chunks.push(`Saved to ${filepath}.`);
+        }
+        else {
+            throw new Error('Not supported response content type');
+        }
+    }
+    return format === 'md' ? chunks.join(' ') : JSON.stringify(chunks);
+}
+//# sourceMappingURL=client.js.map