@gabrielbryk/arc-devtools-mcp 1.3.0

package/build/src/bin/chrome-devtools.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+process.title = 'chrome-devtools';
+import process from 'node:process';
+import { startDaemon, stopDaemon, sendCommand, handleResponse, } from '../daemon/client.js';
+import { isDaemonRunning, serializeArgs } from '../daemon/utils.js';
+import { logDisclaimers } from '../index.js';
+import { hideBin, yargs } from '../third_party/index.js';
+import { checkForUpdates } from '../utils/check-for-updates.js';
+import { VERSION } from '../version.js';
+import { commands } from './chrome-devtools-cli-options.js';
+import { cliOptions, parseArguments } from './chrome-devtools-mcp-cli-options.js';
+await checkForUpdates('Run `npm install -g @gabrielbryk/arc-devtools-mcp@latest` and `arc-devtools start` to update and restart the daemon.');
+async function start(args, sessionId) {
+    const combinedArgs = [...args, ...defaultArgs];
+    await startDaemon(combinedArgs, sessionId);
+    logDisclaimers(parseArguments(VERSION, combinedArgs));
+}
+const defaultArgs = ['--viaCli', '--experimentalStructuredContent'];
+const startCliOptions = {
+    ...cliOptions,
+};
+// Missing CLI serialization.
+delete startCliOptions.viewport;
+// Change the defaults for the CLI.
+delete startCliOptions.experimentalStructuredContent;
+delete startCliOptions.experimentalInteropTools;
+delete startCliOptions.experimentalPageIdRouting;
+if (!('default' in cliOptions.headless)) {
+    throw new Error('headless cli option unexpectedly does not have a default');
+}
+if ('default' in cliOptions.isolated) {
+    throw new Error('isolated cli option unexpectedly has a default');
+}
+startCliOptions.headless.default = true;
+startCliOptions.isolated.description =
+    'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to true unless userDataDir is provided.';
+startCliOptions.categoryExtensions.default = true;
+const y = yargs(hideBin(process.argv))
+    .scriptName('arc-devtools')
+    .showHelpOnFail(true)
+    .usage('arc-devtools <command> [...args] --flags')
+    .usage(`Run 'arc-devtools <command> --help' for help on the specific command.`)
+    .option('sessionId', {
+    type: 'string',
+    description: 'Session ID for daemon scoping',
+    default: '',
+    hidden: true,
+})
+    .demandCommand()
+    .version(VERSION)
+    .strict()
+    .help(true)
+    .wrap(120);
+y.command('start', 'Start or restart chrome-devtools-mcp', y => y
+    .options(startCliOptions)
+    .example('$0 start --browserUrl http://localhost:9222', 'Start the server connecting to an existing browser')
+    .strict(), async (argv) => {
+    if (isDaemonRunning(argv.sessionId)) {
+        await stopDaemon(argv.sessionId);
+    }
+    // Defaults but we do not want to affect the yargs conflict resolution.
+    if (argv.isolated === undefined && argv.userDataDir === undefined) {
+        argv.isolated = true;
+    }
+    if (argv.headless === undefined) {
+        argv.headless = true;
+    }
+    const args = serializeArgs(cliOptions, argv);
+    await start(args, argv.sessionId);
+    process.exit(0);
+}).strict(); // Re-enable strict validation for other commands; this is applied to the yargs instance itself
+y.command('status', 'Checks if chrome-devtools-mcp is running', y => y, async (argv) => {
+    if (isDaemonRunning(argv.sessionId)) {
+        console.log('chrome-devtools-mcp daemon is running.');
+        const response = await sendCommand({
+            method: 'status',
+        }, argv.sessionId);
+        if (response.success) {
+            const data = JSON.parse(response.result);
+            console.log(`pid=${data.pid} socket=${data.socketPath} start-date=${data.startDate} version=${data.version}`);
+            console.log(`args=${JSON.stringify(data.args)}`);
+        }
+        else {
+            console.error('Error:', response.error);
+            process.exit(1);
+        }
+    }
+    else {
+        console.log('chrome-devtools-mcp daemon is not running.');
+    }
+    process.exit(0);
+});
+y.command('stop', 'Stop chrome-devtools-mcp if any', y => y, async (argv) => {
+    const sessionId = argv.sessionId;
+    if (!isDaemonRunning(sessionId)) {
+        process.exit(0);
+    }
+    await stopDaemon(sessionId);
+    process.exit(0);
+});
+for (const [commandName, commandDef] of Object.entries(commands)) {
+    const args = commandDef.args;
+    const requiredArgNames = Object.keys(args).filter(name => args[name].required);
+    const optionalArgNames = Object.keys(args).filter(name => !args[name].required);
+    let commandStr = commandName;
+    for (const arg of requiredArgNames) {
+        commandStr += ` <${arg}>`;
+    }
+    for (const arg of optionalArgNames) {
+        commandStr += ` [--${arg}]`;
+    }
+    y.command(commandStr, commandDef.description, y => {
+        y.option('output-format', {
+            choices: ['md', 'json'],
+            default: 'md',
+        });
+        for (const [argName, opt] of Object.entries(args)) {
+            const type = opt.type === 'integer' || opt.type === 'number'
+                ? 'number'
+                : opt.type === 'boolean'
+                    ? 'boolean'
+                    : opt.type === 'array'
+                        ? 'array'
+                        : 'string';
+            if (opt.required) {
+                const options = {
+                    describe: opt.description,
+                    type: type,
+                };
+                if (opt.default !== undefined) {
+                    options.default = opt.default;
+                }
+                if (opt.enum) {
+                    options.choices = opt.enum;
+                }
+                y.positional(argName, options);
+            }
+            else {
+                const options = {
+                    describe: opt.description,
+                    type: type,
+                };
+                if (opt.default !== undefined) {
+                    options.default = opt.default;
+                }
+                if (opt.enum) {
+                    options.choices = opt.enum;
+                }
+                y.option(argName, options);
+            }
+        }
+    }, async (argv) => {
+        const sessionId = argv.sessionId;
+        try {
+            if (!isDaemonRunning(sessionId)) {
+                await start([], sessionId);
+            }
+            const commandArgs = {};
+            for (const argName of Object.keys(args)) {
+                if (argName in argv) {
+                    commandArgs[argName] = argv[argName];
+                }
+            }
+            const response = await sendCommand({
+                method: 'invoke_tool',
+                tool: commandName,
+                args: commandArgs,
+            }, sessionId);
+            if (response.success) {
+                console.log(await handleResponse(JSON.parse(response.result), argv['output-format']));
+            }
+            else {
+                console.error('Error:', response.error);
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error('Failed to execute command:', error);
+            process.exit(1);
+        }
+    });
+}
+await y.parse();
+//# sourceMappingURL=chrome-devtools.js.map

package/build/src/browser.js

@@ -0,0 +1,253 @@
+/**
+ * @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;
+let browserMode;
+function makeTargetFilter(enableExtensions = false) {
+    // `arc://` is the Arc browser's internal scheme (analogous to `chrome://`).
+    // Filtering it keeps Arc's internal pages out of the page list. These entries
+    // are harmless on Chrome, where no `arc://` targets exist.
+    const ignoredPrefixes = new Set([
+        'chrome://',
+        'chrome-untrusted://',
+        'arc://',
+    ]);
+    if (!enableExtensions) {
+        ignoredPrefixes.add('chrome-extension://');
+    }
+    return function targetFilter(target) {
+        // Keep new-tab pages visible so they can be reused (see McpContext.newPage
+        // under `--arc`). Arc's new tab may surface as `arc://newtab` or `about:blank`.
+        if (target.url() === 'chrome://newtab/' ||
+            target.url().startsWith('arc://newtab')) {
+            return true;
+        }
+        // Could be the only page opened in the browser.
+        if (target.url().startsWith('chrome://inspect') ||
+            target.url().startsWith('arc://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,
+        blocklist: options.blocklist,
+        allowlist: options.allowlist,
+    };
+    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/Arc in ${userDataDir}. Check if the browser is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging (or arc://inspect/#remote-debugging in Arc).`, {
+                    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 {
+        // Assign mode before browser so a concurrent closeBrowser() never sees
+        // `browser` set with `browserMode` still undefined (would fall through
+        // to the disconnect() path and orphan a launched Chrome).
+        const connected = await puppeteer.connect(connectOptions);
+        browserMode = 'connected';
+        browser = connected;
+    }
+    catch (err) {
+        throw new Error(`Could not connect to Chrome/Arc. ${autoConnect ? `Check if the browser is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging (or arc://inspect/#remote-debugging in Arc).` : `Check if the browser 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,
+            blocklist: options.blocklist,
+            allowlist: options.allowlist,
+        });
+        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;
+    }
+    // Assign mode before browser; see the connect path above for rationale.
+    const launched = await launch(options);
+    browserMode = 'launched';
+    browser = launched;
+    return browser;
+}
+/**
+ * Shutdown hook for the active browser. Closes a launched browser (so the
+ * Chrome subprocess is reaped) or disconnects from an attached browser (so
+ * the user's Chrome instance stays alive). No-op if no browser is active or
+ * the connection has already been dropped. Called from the server entrypoint
+ * on stdin EOF / SIGTERM / SIGINT.
+ */
+export async function closeBrowser() {
+    const b = browser;
+    const mode = browserMode;
+    browser = undefined;
+    browserMode = undefined;
+    if (!b || !b.connected) {
+        return;
+    }
+    if (mode === 'launched') {
+        await b.close().catch(err => {
+            logger?.('Failed to close browser', err);
+        });
+        return;
+    }
+    await b.disconnect().catch(err => {
+        logger?.('Failed to disconnect from browser', err);
+    });
+}
+//# sourceMappingURL=browser.js.map

package/build/src/daemon/client.js

@@ -0,0 +1,160 @@
+/**
+ * @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);
+    }
+    const chunks = [];
+    const images = [];
+    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);
+            images.push({ filePath: filepath, mimeType });
+            chunks.push(`Saved to ${filepath}.`);
+        }
+        else {
+            throw new Error('Not supported response content type');
+        }
+    }
+    if (format === 'json') {
+        if (response.structuredContent) {
+            const structuredContent = {
+                ...response.structuredContent,
+                ...(images.length ? { images } : {}),
+            };
+            return JSON.stringify(structuredContent);
+        }
+        // Fall-through to text for backward compatibility.
+    }
+    return format === 'md' ? chunks.join(' ') : JSON.stringify(chunks);
+}
+//# sourceMappingURL=client.js.map