opera-devtools-mcp 0.6.0 → 0.7.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

@@ -165,6 +165,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 = [];

package/build/src/daemon/utils.js

@@ -110,6 +110,12 @@ export function serializeArgs(options, argv) {
             continue;
         }
         const value = argv[key];
+        const option = options[key];
+        // Yargs reuses the option `default` object; skip it so the daemon parser
+        // still sees the original default (needed for filesystemRoot identity).
+        if (option !== undefined && value === option.default) {
+            continue;
+        }
         const kebabKey = key.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
         if (typeof value === 'boolean') {
             if (value) {

package/build/src/devtools/DevtoolsUtils.js

@@ -19,6 +19,11 @@ export function overrideDevToolsGlobals({ loadResource, }) {
     DevTools.Host.InspectorFrontendHost.installInspectorFrontendHost(new McpHostBindingAdapter(loadResource));
     // DevTools CDP errors can get noisy.
     DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
+    const noopAgentCommand = () => {
+        return Promise.resolve({
+            getError: () => undefined,
+        });
+    };
     // Stub out Network emulation commands on the DevTools Agent prototype globally.
     // This prevents the DevTools Frontend from ever resetting/clearing Puppeteer's
     // active network blocking/throttling rules during target setup or session lifetime.
@@ -36,41 +41,37 @@ export function overrideDevToolsGlobals({ loadResource, }) {
             enumerable: true,
         });
         Object.defineProperty(networkAgentPrototype, 'invoke_overrideNetworkState', {
-            value: () => {
-                return Promise.resolve({
-                    getError: () => undefined,
-                });
-            },
+            value: noopAgentCommand,
             writable: true,
             configurable: true,
             enumerable: true,
         });
         Object.defineProperty(networkAgentPrototype, 'invoke_enable', {
-            value: () => {
-                return Promise.resolve({
-                    getError: () => undefined,
-                });
-            },
+            value: noopAgentCommand,
             writable: true,
             configurable: true,
             enumerable: true,
         });
         Object.defineProperty(networkAgentPrototype, 'invoke_disable', {
-            value: () => {
-                return Promise.resolve({
-                    getError: () => undefined,
-                });
-            },
+            value: noopAgentCommand,
             writable: true,
             configurable: true,
             enumerable: true,
         });
         Object.defineProperty(networkAgentPrototype, 'invoke_setBlockedURLs', {
-            value: () => {
-                return Promise.resolve({
-                    getError: () => undefined,
-                });
-            },
+            value: noopAgentCommand,
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+    }
+    // Puppeteer already collects issues from its own Audits subscription. Avoid
+    // enabling the DevTools Frontend's redundant subscription, which can replay
+    // a large retained issue backlog and delay unrelated page work.
+    const auditsAgentPrototype = DevTools.ProtocolClient.InspectorBackend.inspectorBackend.agentPrototypes.get('Audits');
+    if (auditsAgentPrototype) {
+        Object.defineProperty(auditsAgentPrototype, 'invoke_enable', {
+            value: noopAgentCommand,
             writable: true,
             configurable: true,
             enumerable: true,
@@ -91,7 +92,7 @@ export function overrideDevToolsGlobals({ loadResource, }) {
             .resolve('../third_party/devtools-formatter-worker.js'),
     });
 }
-export async function createTargetUniverse(session) {
+export async function createTargetUniverse(session, options) {
     const settingStorage = new DevTools.Common.Settings.SettingsStorage({});
     const universe = new DevTools.Foundation.Universe.Universe({
         settingsCreationOptions: {
@@ -105,6 +106,11 @@ export async function createTargetUniverse(session) {
         inspectorFrontendHost: DevTools.Host.InspectorFrontendHost.InspectorFrontendHostInstance,
         supportsEmulation: false,
     });
+    const sourceMaps = options?.sourceMaps ?? true;
+    const jsSourceMapsSetting = universe.settings.resolve(DevTools.SDKSettings.jsSourceMapsEnabledSettingDescriptor);
+    jsSourceMapsSetting.set(sourceMaps);
+    const cssSourceMapsSetting = universe.settings.resolve(DevTools.SDKSettings.cssSourceMapsEnabledSettingDescriptor);
+    cssSourceMapsSetting.set(sourceMaps);
     const setting = universe.settings.resolve(DevTools.SourceMapManager.lazyLoadingSettingDescriptor);
     setting.set(true);
     const skipAllPausesSetting = universe.settings.resolve(DevTools.skipAllPausesSettingDescriptor);

package/build/src/formatters/NetworkFormatter.js

@@ -6,6 +6,7 @@
 import { isUtf8 } from 'node:buffer';
 import { DevTools, } from '../third_party/index.js';
 const BODY_CONTEXT_SIZE_LIMIT = 10000;
+const URL_CONTEXT_SIZE_LIMIT = 255;
 export class NetworkFormatter {
     #request;
     #options;
@@ -178,8 +179,10 @@ function getSizeLimitedString(text, sizeLimit) {
     return text;
 }
 function convertNetworkRequestConciseToString(data) {
-    // TODO truncate the URL
-    return `reqid=${data.requestId} ${data.method} ${data.url} [${data.status}]${data.selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
+    // Long URLs (e.g., data: URLs) bloat the concise list output. The full URL
+    // remains available via the detailed view and the structured content.
+    const url = getSizeLimitedString(data.url, URL_CONTEXT_SIZE_LIMIT);
+    return `reqid=${data.requestId} ${data.method} ${url} [${data.status}]${data.selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
 }
 function formatHeaders(headers) {
     const response = [];