opera-devtools-mcp 0.6.1 → 0.8.0

package/build/src/{bin/chrome-devtools-mcp-cli-options.js → config/mcp-options.js}

@@ -5,110 +5,17 @@
  *
  * Modified by Opera Software AS.
  */
-import { CACHE_DIR_NAME, ENV_NO_USAGE_STATISTICS, MCP_BIN_NAME, PACKAGE_NAME, REPO_URL, } from '../opera/branding.js';
+import { ENV_NO_USAGE_STATISTICS, PACKAGE_NAME, REPO_URL, } from '../opera/branding.js';
 import { PERFORMANCE_CRUX_DEFAULT, PERFORMANCE_CRUX_DESCRIPTION, USAGE_STATISTICS_DEFAULT, USAGE_STATISTICS_DESCRIPTION, } from '../opera/policy.js';
 import { yargs, hideBin } from '../third_party/index.js';
-export const cliOptions = {
-    autoConnect: {
-        type: 'boolean',
-        description: 'If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.',
-        conflicts: ['isolated', 'executablePath'],
-        default: false,
-        coerce: (value) => {
-            if (!value) {
-                return;
-            }
-            return value;
-        },
-    },
-    browserUrl: {
-        type: 'string',
-        description: `Connect to a running, debuggable Chrome instance (e.g. \`http://127.0.0.1:9222\`). For more details see: ${REPO_URL}#connecting-to-a-running-chrome-instance.`,
-        alias: 'u',
-        conflicts: ['wsEndpoint'],
-        coerce: (url) => {
-            if (!url) {
-                return;
-            }
-            try {
-                new URL(url);
-            }
-            catch {
-                throw new Error(`Provided browserUrl ${url} is not valid URL.`);
-            }
-            return url;
-        },
-    },
-    wsEndpoint: {
-        type: 'string',
-        description: 'WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',
-        alias: 'w',
-        conflicts: ['browserUrl'],
-        coerce: (url) => {
-            if (!url) {
-                return;
-            }
-            try {
-                const parsed = new URL(url);
-                if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
-                    throw new Error(`Provided wsEndpoint ${url} must use ws:// or wss:// protocol.`);
-                }
-                return url;
-            }
-            catch (error) {
-                if (error.message.includes('ws://')) {
-                    throw error;
-                }
-                throw new Error(`Provided wsEndpoint ${url} is not valid URL.`);
-            }
-        },
-    },
-    wsHeaders: {
-        type: 'string',
-        description: 'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',
-        implies: 'wsEndpoint',
-        coerce: (val) => {
-            if (!val) {
-                return;
-            }
-            try {
-                const parsed = JSON.parse(val);
-                if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-                    throw new Error('Headers must be a JSON object');
-                }
-                return parsed;
-            }
-            catch (error) {
-                throw new Error(`Invalid JSON for wsHeaders: ${error.message}`);
-            }
-        },
-    },
-    headless: {
-        type: 'boolean',
-        description: 'Whether to run in headless (no UI) mode.',
-        default: false,
-    },
-    executablePath: {
-        type: 'string',
-        description: 'Path to custom Chrome executable.',
-        conflicts: ['browserUrl', 'wsEndpoint'],
-        alias: 'e',
-    },
-    isolated: {
-        type: 'boolean',
-        description: 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.',
-    },
-    userDataDir: {
-        type: 'string',
-        description: `Path to the user data directory for Chrome. Default is $HOME/.cache/${CACHE_DIR_NAME}/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE`,
-        conflicts: ['browserUrl', 'wsEndpoint', 'isolated'],
-    },
-    channel: {
-        type: 'string',
-        description: 'Specify a different Chrome channel that should be used. The default is the stable channel version.',
-        choices: ['canary', 'dev', 'beta', 'stable'],
-        conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],
-    },
+import os from 'node:os';
+import { readFileSync } from 'node:fs';
+export const DEFAULT_FILESYSTEM_ROOT = [os.tmpdir()];
+import { getCategoryOptions } from './category-options.js';
+import { getBrowserOptions } from './browser-options.js';
+export const mcpOptions = {
+    ...getCategoryOptions(),
+    ...getBrowserOptions(),
     logFile: {
         type: 'string',
         describe: 'Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.',
@@ -130,17 +37,20 @@ export const cliOptions = {
             };
         },
     },
-    proxyServer: {
-        type: 'string',
-        description: `Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.`,
-    },
     acceptInsecureCerts: {
         type: 'boolean',
         description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,
     },
-    experimentalPageIdRouting: {
+    pageIdRouting: {
         type: 'boolean',
-        describe: 'Whether to expose pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions).',
+        describe: 'Require pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions). Use --no-page-id-routing to disable.',
+        default: true,
+    },
+    devtoolsComments: {
+        type: 'boolean',
+        describe: 'Whether to enable DevTools comments tools. Internal WIP feature.',
+        hidden: true,
+        default: false,
     },
     experimentalDevtools: {
         type: 'boolean',
@@ -152,11 +62,13 @@ export const cliOptions = {
     },
     memoryDebugging: {
         type: 'boolean',
+        default: false,
         describe: 'Whether to enable memory debugging tools.',
         alias: 'experimentalMemory',
     },
     experimentalStructuredContent: {
         type: 'boolean',
+        default: false,
         describe: 'Whether to output structured formatted content.',
     },
     experimentalToonFormat: {
@@ -188,13 +100,19 @@ export const cliOptions = {
         describe: 'Path to ffmpeg executable for screencast recording.',
         implies: 'experimentalScreencast',
     },
-    categoryExperimentalWebmcp: {
-        type: 'boolean',
-        describe: 'Set to true to enable debugging WebMCP tools. Requires Chrome 150+ with the following flag: `--enable-features=WebMCP`',
-    },
-    chromeArg: {
-        type: 'array',
-        describe: `Additional arguments for Chrome. Only applies when Chrome is launched by ${MCP_BIN_NAME}.`,
+    experimentalScreencastFps: {
+        type: 'number',
+        describe: 'Frames per second to use for screencast recording. Lower values can reduce memory pressure on pages that produce frames faster than ffmpeg can encode them.',
+        implies: 'experimentalScreencast',
+        coerce: (value) => {
+            if (value === undefined) {
+                return;
+            }
+            if (!Number.isInteger(value) || value <= 0) {
+                throw new Error(`Invalid experimentalScreencastFps ${value}. Expected a positive integer.`);
+            }
+            return value;
+        },
     },
     blockedUrlPattern: {
         type: 'array',
@@ -206,42 +124,6 @@ export const cliOptions = {
         describe: "Restricts browser's network access by allowing only specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Requires Chrome 149+. Silently detaches from targets with unallowed URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.",
         conflicts: ['blockedUrlPattern'],
     },
-    ignoreDefaultChromeArg: {
-        type: 'array',
-        describe: `Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by ${MCP_BIN_NAME}.`,
-    },
-    categoryEmulation: {
-        type: 'boolean',
-        default: true,
-        describe: 'Set to false to exclude tools related to emulation.',
-    },
-    categoryPerformance: {
-        type: 'boolean',
-        default: true,
-        describe: 'Set to false to exclude tools related to performance.',
-    },
-    categoryNetwork: {
-        type: 'boolean',
-        default: true,
-        describe: 'Set to false to exclude tools related to network.',
-    },
-    categoryExtensions: {
-        type: 'boolean',
-        hidden: false,
-        default: false,
-        describe: 'Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released.',
-    },
-    categoryExperimentalThirdParty: {
-        type: 'boolean',
-        default: false,
-        describe: 'Set to true to enable third-party developer tools exposed by the inspected page itself',
-    },
-    categoryPwa: {
-        type: 'boolean',
-        hidden: false,
-        conflicts: ['autoConnect', 'browserUrl', 'wsEndpoint'],
-        describe: 'Set to true to include tools for automating Progressive Web Apps (install, launch, uninstall, and OS state). This feature is only supported with a pipe connection; autoConnect, browserUrl, and wsEndpoint are not supported.',
-    },
     performanceCrux: {
         type: 'boolean',
         default: PERFORMANCE_CRUX_DEFAULT,
@@ -252,6 +134,16 @@ export const cliOptions = {
         default: USAGE_STATISTICS_DEFAULT,
         describe: USAGE_STATISTICS_DESCRIPTION,
     },
+    javascriptEvaluation: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to disable JavaScript execution. When disabled, evaluation tools (evaluate_script and slim evaluate) are disabled, the initScript parameter in navigate_page is turned off, and navigating to javascript:, data:, or vbscript: URLs is disallowed.',
+    },
+    sourceMaps: {
+        type: 'boolean',
+        default: true,
+        describe: 'Whether to enable source maps in DevTools. Use --no-source-maps to disable.',
+    },
     clearcutEndpoint: {
         type: 'string',
         hidden: true,
@@ -269,7 +161,7 @@ export const cliOptions = {
     },
     screenshotFormat: {
         type: 'string',
-        description: 'Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png").',
+        description: 'Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which reduces transfer and storage size. To reduce context size use --screenshotMaxWidth / --screenshotMaxHeight, since image tokens scale with dimensions rather than encoded bytes. Unset preserves the existing default ("png").',
         choices: ['jpeg', 'png', 'webp'],
     },
     screenshotQuality: {
@@ -328,30 +220,78 @@ export const cliOptions = {
     allowUnrestrictedPaths: {
         type: 'boolean',
         default: false,
+        deprecated: 'Use --workspace=/ instead.',
         describe: 'If set, disables the default path restriction that applies when the MCP client does not negotiate ' +
             'the roots capability. By default, file-writing tools are restricted to the OS temp directory when ' +
             'no roots are configured. Use this only when connecting a trusted local client that does not implement ' +
             'MCP roots and requires access to paths outside the temp directory.',
     },
+    filesystemRoot: {
+        type: 'array',
+        alias: 'workspace',
+        default: DEFAULT_FILESYSTEM_ROOT,
+        defaultDescription: 'OS temp directory',
+        describe: 'A directory that filesystem tools are allowed to access. May be specified more than once.',
+    },
+    config: {
+        type: 'string',
+        describe: 'Path to JSON configuration file.',
+    },
 };
+export function getMcpOptionsForViaCli() {
+    if (!('default' in mcpOptions.headless)) {
+        throw new Error('headless cli option unexpectedly does not have a default');
+    }
+    if (!('default' in mcpOptions.experimentalStructuredContent)) {
+        throw new Error('experimentalStructuredContent cli option unexpectedly does not have a default');
+    }
+    if ('default' in mcpOptions.isolated) {
+        throw new Error('isolated cli option unexpectedly has a default');
+    }
+    return {
+        ...mcpOptions,
+        headless: {
+            ...mcpOptions.headless,
+            default: true,
+        },
+        memoryDebugging: {
+            ...mcpOptions.memoryDebugging,
+            default: true,
+        },
+        categoryExtensions: {
+            ...mcpOptions.categoryExtensions,
+            default: true,
+        },
+        experimentalStructuredContent: {
+            ...mcpOptions.experimentalStructuredContent,
+            default: true,
+        },
+        isolated: {
+            ...mcpOptions.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.',
+        },
+    };
+}
 /**
  * Exported only for testing to not trigger process exit.
  */
 export function parser(version, argv = process.argv, env = process.env) {
-    // Preserve yargs' mixed camel/kebab-case expansion under strict validation.
-    const kebabCaseAliases = {};
-    for (const option of Object.keys(cliOptions)) {
-        const alias = option.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
-        if (alias !== option) {
-            kebabCaseAliases[option] = alias;
-        }
-    }
+    const isViaCli = argv.includes('--viaCli') || argv.includes('--via-cli');
+    const options = isViaCli ? getMcpOptionsForViaCli() : mcpOptions;
     const yargsInstance = yargs(hideBin(argv))
         .scriptName(`npx ${PACKAGE_NAME}@latest`)
-        .options(cliOptions)
-        .alias(kebabCaseAliases)
-        .strictOptions()
+        .parserConfiguration({
+        'strip-aliased': true,
+        'strip-dashed': true,
+    })
+        .options(options)
+        .showHelpOnFail(false, 'Specify --help for available options')
         .middleware(args => {
+        if (isViaCli && args.filesystemRoot === DEFAULT_FILESYSTEM_ROOT) {
+            const cliFilesystemArgs = args;
+            cliFilesystemArgs.allowUnrestrictedPaths = true;
+            cliFilesystemArgs.filesystemRoot = undefined;
+        }
         // We can't set default in the options else
         // Yargs will complain
         if (!args.channel &&
@@ -364,6 +304,16 @@ export function parser(version, argv = process.argv, env = process.env) {
             console.error(`turning off usage statistics. process.env['CI'] || process.env['${ENV_NO_USAGE_STATISTICS}'] is set.`);
             args.usageStatistics = false;
         }
+        const cliOptionsAllowedArgs = [
+            ...Object.keys(options),
+            // Yargs populated with positional args
+            '_',
+            '$0',
+        ];
+        const unknownArgs = Object.keys(args).filter(arg => !cliOptionsAllowedArgs.includes(arg));
+        if (unknownArgs.length > 0) {
+            console.error(`Unknown arguments: ${unknownArgs.map(arg => `--${arg}`)}`);
+        }
     })
         .example([
         [
@@ -422,12 +372,41 @@ export function parser(version, argv = process.argv, env = process.env) {
             '$0 --no-performance-crux',
             'Disable CrUX (field data) integration in performance tools.',
         ],
+        ['$0 --no-source-maps', 'Disable source maps in DevTools.'],
+        [
+            '$0 --no-javascript-evaluation',
+            'Disable JavaScript execution (disables evaluation tools, initScript in navigate_page, and navigating to javascript:, data:, or vbscript: URLs).',
+        ],
         [
             '$0 --slim',
             'Only 3 tools: navigation, JavaScript execution and screenshot',
         ],
     ]);
     return yargsInstance
+        .config('config', 'Path to JSON configuration file', configPath => {
+        try {
+            const parsed = JSON.parse(readFileSync(configPath, 'utf-8'));
+            if (typeof parsed !== 'object' ||
+                parsed === null ||
+                Array.isArray(parsed)) {
+                throw new Error('Config must be a JSON object');
+            }
+            return yargs()
+                .parserConfiguration({
+                'strip-aliased': true,
+                'camel-case-expansion': false,
+            })
+                .options(options)
+                .config(parsed)
+                .strict()
+                .fail(false)
+                .exitProcess(false)
+                .parseSync([]);
+        }
+        catch (err) {
+            throw new Error(`Invalid JSON config file: ${err.message}`);
+        }
+    })
         .wrap(Math.min(120, yargsInstance.terminalWidth()))
         .help()
         .version(version);
@@ -435,4 +414,4 @@ export function parser(version, argv = process.argv, env = process.env) {
 export function parseArguments(version, argv = process.argv, env = process.env) {
     return parser(version, argv, env).parseSync();
 }
-//# sourceMappingURL=chrome-devtools-mcp-cli-options.js.map
+//# sourceMappingURL=mcp-options.js.map

package/build/src/daemon/client.js

@@ -6,9 +6,11 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import net from 'node:net';
-import { PipeTransport } from '../third_party/index.js';
+import { ensureCleanStart, readExitReason } from '../opera/daemonLifecycle.js';
+import { nameSpawnFailure, openDaemonLog } from '../opera/daemonLog.js';
+import { requestOverSocket } from '../opera/daemonStreaming.js';
 import { getTempFilePath } from '../utils/files.js';
-import { logger, puppeteerLogger } from '../utils/logger.js';
+import { logger } from '../utils/logger.js';
 import { DAEMON_SCRIPT_PATH, getSocketPath, getPidFilePath, isDaemonRunning, } from './utils.js';
 const FILE_TIMEOUT = 10_000;
 const READY_CHECK_INTERVAL = 100;
@@ -77,64 +79,68 @@ async function waitForDaemonReady(sessionId) {
     throw new Error(`Timeout: daemon not ready within ${FILE_TIMEOUT}ms`, lastError === undefined ? undefined : { cause: lastError });
 }
 export async function startDaemon(mcpArgs = [], sessionId) {
-    if (isDaemonRunning(sessionId)) {
+    // Not `isDaemonRunning`: that reads the pid file, and a daemon whose pid file
+    // is gone (or whose socket a racing starter unlinked) is invisible to it.
+    // `ensureCleanStart` probes the socket and reaps whatever the last daemon left
+    // behind, so the daemon we are about to fork is the only one in the session.
+    if (await ensureCleanStart(sessionId)) {
         logger?.('Daemon is already running');
         await waitForDaemonReady(sessionId);
         return;
     }
+    logger?.('Starting daemon...', ...mcpArgs);
     const pidFilePath = getPidFilePath(sessionId);
-    if (fs.existsSync(pidFilePath)) {
-        fs.unlinkSync(pidFilePath);
+    const logFd = openDaemonLog(sessionId);
+    let child;
+    try {
+        child = spawn(process.execPath, [DAEMON_SCRIPT_PATH, ...mcpArgs], {
+            detached: true,
+            // Not 'ignore' unless there was nothing to open: the daemon is detached
+            // with no terminal, so discarding its output leaves a daemon that dies
+            // silently unexplainable. The file is what the mid-command failure below
+            // points the user at.
+            stdio: logFd === 'ignore' ? 'ignore' : ['ignore', logFd, logFd],
+            env: { ...process.env, CHROME_DEVTOOLS_MCP_SESSION_ID: sessionId },
+            cwd: process.cwd(),
+            windowsHide: true,
+        });
+    }
+    finally {
+        // The child holds its own descriptor; the parent's copy would outlive it.
+        if (logFd !== 'ignore') {
+            fs.closeSync(logFd);
+        }
     }
-    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);
+    // The pid file and the spawn's own failure, whichever comes first. See
+    // `opera/daemonLog.ts` for why a failed spawn must not surface as a timeout.
+    await Promise.race([
+        waitForFile(pidFilePath),
+        nameSpawnFailure(child, sessionId),
+    ]);
     await waitForDaemonReady(sessionId);
 }
 const SEND_COMMAND_TIMEOUT = 60_000; // ms
 /**
  * `sendCommand` opens a socket connection sends a single command and disconnects.
+ *
+ * The frame protocol — including `onLog`, which opts the request into the
+ * streaming variant and hands each chunk over as it arrives — lives in
+ * `opera/daemonStreaming.ts`'s `requestOverSocket`.
  */
-export async function sendCommand(command, sessionId, timeout = SEND_COMMAND_TIMEOUT) {
+export async function sendCommand(command, sessionId, timeout = SEND_COMMAND_TIMEOUT, onLog) {
     // Before connecting and sending, verify the daemon is still alive.
     if (!isDaemonRunning(sessionId)) {
-        throw new Error('Daemon is not running.');
+        // A daemon that tore itself down leaves a reason behind; surfacing it is
+        // the difference between "Daemon is not running." and knowing why.
+        const reason = readExitReason(sessionId);
+        throw new Error(reason ? `Daemon is not running: ${reason}` : 'Daemon is not running.');
     }
     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'));
-        }, timeout);
-        const transport = new PipeTransport(socket, socket, puppeteerLogger);
-        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));
-    });
+    return requestOverSocket({ socket, command, sessionId, timeout, onLog });
 }
 export async function stopDaemon(sessionId) {
     if (!isDaemonRunning(sessionId)) {
@@ -165,6 +171,15 @@ export async function verifyDaemonVersion(sessionId, cliVersion) {
 }
 export async function handleResponse(response, format) {
     if (response.isError) {
+        if (format === 'md') {
+            const chunks = [];
+            for (const content of response.content) {
+                if (content.type === 'text') {
+                    chunks.push(content.text);
+                }
+            }
+            return chunks.join(' ');
+        }
         return JSON.stringify(response.content);
     }
     const chunks = [];