opera-devtools-mcp 0.6.1 → 0.8.0

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

@@ -7,42 +7,45 @@
  * Modified by Opera Software AS.
  */
 import process from 'node:process';
-import { startDaemon, stopDaemon, sendCommand, handleResponse, verifyDaemonVersion, } from '../daemon/client.js';
+import { startDaemon, stopDaemon, sendCommand } from '../daemon/client.js';
 import { isDaemonRunning, serializeArgs, assertValidSessionId, } from '../daemon/utils.js';
 import { logDisclaimers } from '../index.js';
 import { CLI_BIN_NAME, MCP_BIN_NAME, PACKAGE_NAME } from '../opera/branding.js';
+import { describeBrowserMode } from '../opera/browserFlags.js';
+import { EXIT_CODES } from '../opera/cdpErrors.js';
+import { registerOperaCommands, registerToolCommand, } from '../opera/cliCommands.js';
+import { launcherMigrationNotice } from '../opera/launcherNotice.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';
+import { commands } from '../config/cli-options.js';
+import { mcpOptions, parseArguments, getMcpOptionsForViaCli, } from '../config/mcp-options.js';
 process.title = CLI_BIN_NAME;
 await checkForUpdates(`Run \`npm install -g ${PACKAGE_NAME}@latest\` and \`${CLI_BIN_NAME} start\` to update and restart the daemon.`);
+const DEFAULT_CLI_ARGS = ['--viaCli'];
+// `--version` is also what a user runs when something looks wrong, so it has to
+// carry the phase-2 recipe when the compatibility launcher is what ran this CLI
+// (`src/opera/launcherNotice.ts`). Without the marker the banner is the plain
+// version, exactly as before.
+const versionBanner = [VERSION, launcherMigrationNotice()]
+    .filter(Boolean)
+    .join('\n\n');
 async function start(args, sessionId) {
-    const combinedArgs = [...args, ...defaultArgs];
+    const combinedArgs = [...DEFAULT_CLI_ARGS, ...args];
     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');
+function getCliOptions() {
+    const options = {
+        ...getMcpOptionsForViaCli(),
+    };
+    // Missing CLI serialization.
+    delete options.viewport;
+    // Change the defaults for the CLI.
+    delete options.experimentalStructuredContent;
+    delete options.experimentalInteropTools;
+    return options;
 }
-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))
     .locale('en') // Force English to ensure error string matching works in .fail, all custom messages we output are in English anyways
     .scriptName(CLI_BIN_NAME)
@@ -60,7 +63,7 @@ const y = yargs(hideBin(process.argv))
     },
 })
     .demandCommand()
-    .version(VERSION)
+    .version(versionBanner)
     .strict()
     .help(true)
     .wrap(120)
@@ -72,36 +75,45 @@ const y = yargs(hideBin(process.argv))
             msg.includes('Unknown arguments')) {
             console.error('\n=========================================');
             console.error('💡 TIP FOR AI AGENT / DEVELOPER:');
-            console.error('In the `chrome-devtools` CLI:');
+            console.error(`In the \`${CLI_BIN_NAME}\` CLI:`);
             console.error('1. Required parameters MUST be passed as positional arguments (without flags).');
-            console.error('   - INCORRECT: chrome-devtools evaluate_script --expression "() => document.title"');
-            console.error('   - CORRECT:   chrome-devtools evaluate_script "() => document.title"');
-            console.error('2. Optional parameters are passed as double-dash options/flags (e.g. --pageId 1).');
+            console.error(`   - INCORRECT: ${CLI_BIN_NAME} click --pageId 1 --uid "1_2"`);
+            console.error(`   - CORRECT:   ${CLI_BIN_NAME} click 1 "1_2"`);
+            console.error('2. Optional parameters are passed as double-dash options/flags (e.g. --dblClick true).');
             console.error('3. Make sure to escape quotes properly for your shell environment.');
-            console.error('Run `chrome-devtools <command> --help` to see exact positional and optional parameters.');
+            console.error(`Run \`${CLI_BIN_NAME} <command> --help\` to see exact positional and optional parameters.`);
             console.error('=========================================');
         }
     }
     else if (err) {
         console.error(err);
     }
-    process.exit(1);
+    // A parse failure is exactly what exit code 2 means — "fix the command" — so
+    // it is reported as one rather than as an unknown failure.
+    process.exit(msg ? EXIT_CODES.VALIDATION_ERROR : EXIT_CODES.UNKNOWN);
 });
 y.command('start', `Start or restart ${MCP_BIN_NAME}`, y => y
-    .options(startCliOptions)
+    .options(getCliOptions())
     .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) {
+    if (argv.isolated === undefined &&
+        argv.userDataDir === undefined &&
+        !argv.autoConnect &&
+        !argv.browserUrl &&
+        !argv.wsEndpoint) {
         argv.isolated = true;
     }
-    if (argv.headless === undefined) {
+    if (argv.headless === undefined &&
+        !argv.autoConnect &&
+        !argv.browserUrl &&
+        !argv.wsEndpoint) {
         argv.headless = true;
     }
-    const args = serializeArgs(cliOptions, argv);
+    const args = serializeArgs(mcpOptions, 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
@@ -114,9 +126,12 @@ y.command('status', `Checks if ${MCP_BIN_NAME} is running`, y => y, async (argv)
         if (response.success) {
             const data = JSON.parse(response.result);
             console.log(`pid=${data.pid} socket=${data.socketPath} start-date=${data.startDate} version=${data.version}`);
+            // Who owns the browser decides what recovery to expect from it: we
+            // relaunch what we launched, and never touch a browser we attached to.
+            console.log(`browser=${describeBrowserMode(data.args)}`);
             console.log(`args=${JSON.stringify(data.args)}`);
             if (data.version !== VERSION) {
-                console.warn(`Warning: Daemon server version (${data.version}) does not match CLI version (${VERSION}). Run 'chrome-devtools start' to update and restart the daemon.`);
+                console.warn(`Warning: Daemon server version (${data.version}) does not match CLI version (${VERSION}). Run '${CLI_BIN_NAME} start' to update and restart the daemon.`);
             }
         }
         else {
@@ -137,96 +152,13 @@ y.command('stop', `Stop ${MCP_BIN_NAME} if any`, y => y, async (argv) => {
     await stopDaemon(sessionId);
     process.exit(0);
 });
+// The fork's own commands (`setup`, `doctor`, `logs`, `url`) and the wrapper
+// that turns a generated tool definition into a runnable command live in
+// `src/opera/cliCommands.ts`, along with the exit-code and streaming plumbing
+// of a tool call. `start` stays here: it is upstream's, and prepends `--viaCli`.
+registerOperaCommands(y, { start });
 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 {
-            const versionWarningPromise = isDaemonRunning(sessionId)
-                ? verifyDaemonVersion(sessionId, VERSION)
-                : Promise.resolve(undefined);
-            if (!isDaemonRunning(sessionId)) {
-                await start(serializeArgs(cliOptions, argv), 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);
-            }
-            const versionWarning = await versionWarningPromise;
-            if (versionWarning) {
-                console.warn(versionWarning);
-            }
-            if (!response.success) {
-                process.exit(1);
-            }
-        }
-        catch (error) {
-            console.error('Failed to execute command:', error);
-            process.exit(1);
-        }
-    });
+    registerToolCommand(y, commandName, commandDef, { start });
 }
 await y.parse();
 //# sourceMappingURL=chrome-devtools.js.map

package/build/src/bin/opera-browser-cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2026 Opera Software AS.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Opera-named bin entry (see `package.json` `bin`). The implementation lives in
+// the upstream-owned file and is branded via `src/opera/branding.ts`.
+//
+// The guard comes FIRST, and has to stay first: it installs on import, and the
+// imports below it reach `third_party`, whose bundled `debug` reads the
+// `localStorage` global and prints Node's Web Storage warning. An import listed
+// before this one that reaches `third_party` puts the warning back in front of
+// every command's output.
+import { preloadWebStorageWarningGuardInChildren } from '../opera/webStorageWarning.js';
+import { CLI_BIN_NAME } from '../opera/branding.js';
+import { extractTakeoverFlag, preflightBrowser, sessionIdFromArgv, } from '../opera/browserTarget.js';
+import { formatError } from '../opera/cliOutput.js';
+import { autoConfigure, shouldAutoConfigure } from '../opera/config.js';
+import { applyEnvToArgv, loadOperaCliConfig } from '../opera/envConfig.js';
+import { runLegacyMigrationGuard } from '../opera/legacyBridgeCleanup.js';
+/**
+ * Configure a fresh machine in place, without asking. Skips pure queries and
+ * the (future) `setup`/`logs` commands; reports what it did on stderr so a
+ * scripted user sees the same first-run note as opera-browser-cli.
+ */
+function ensureConfigured(argv) {
+    if (!shouldAutoConfigure(argv)) {
+        return;
+    }
+    const command = argv[2];
+    const result = autoConfigure();
+    if (result.status === 'configured') {
+        const ai = result.browser.isNeon
+            ? 'Opera AI available'
+            : 'chat only — install Opera Neon for invoke-do/make/research';
+        process.stderr.write(`configured: ${result.browser.name} (${ai}) — run \`${CLI_BIN_NAME} setup\` to change\n`);
+        return;
+    }
+    if (result.status === 'no-browser' && command !== 'doctor') {
+        process.stderr.write(`hint: no Opera installation found — run \`${CLI_BIN_NAME} setup\`, or set OPERA_CLI_EXECUTABLE_PATH\n`);
+    }
+}
+// Promote ~/.opera-browser-cli/config into process.env (and warn on unknown
+// keys) before the CLI spawns the daemon, which inherits this environment.
+loadOperaCliConfig();
+// A machine that upgraded from the two-package era may still have the old HTTP
+// bridge running, holding port 9225 and a browser of its own. Nothing runs at
+// install time any more — npm ≥12 blocks install scripts unless the user opts in
+// — so this is the path that always runs: the launcher spawns this CLI for every
+// command, `--version` and `--help` included. One file read when there is no
+// bridge; the port probe behind it runs once per boot. Never throws.
+//
+// The home is the *invoking* user's, not `os.homedir()`: under `sudo`, the
+// bridge (and its PID file) belongs to the user who started it.
+await runLegacyMigrationGuard();
+// The daemon cannot import this module before its own static imports reach
+// `third_party`, so the guard travels to it (and to the MCP server it spawns)
+// through NODE_OPTIONS instead.
+preloadWebStorageWarningGuardInChildren();
+// On a machine that has never been configured, detect the installed Opera
+// build and write a config + set OPERA_CLI_* so this first command works.
+ensureConfigured(process.argv);
+// `--takeover` decides how a profile conflict is settled, and belongs to the
+// preflight rather than to any command — every command parser is strict, so it
+// is read and removed before one of them sees it. It is left in the environment
+// because the preflight is not the only place a conflict is settled: a tool
+// call that fails on one settles it too, one process deeper than any argument
+// the command parser kept (`cliCommands.ts`).
+const takeover = extractTakeoverFlag(process.argv);
+if (takeover) {
+    process.env.OPERA_CLI_TAKEOVER = '1';
+}
+// Which browser to drive is decided here, before the command starts a daemon:
+// settling a conflict may need to ask the user, and the daemon is detached with
+// no terminal. The decision travels as OPERA_CLI_* environment, which the
+// daemon and the MCP server it spawns both inherit — and, for `start`, as the
+// flags translated from it immediately below.
+try {
+    await preflightBrowser(process.argv.slice(2), sessionIdFromArgv(process.argv), takeover);
+}
+catch (error) {
+    const { output, exitCode } = await formatError(error);
+    console.error(output);
+    process.exit(exitCode);
+}
+// `start` is the command that decides the daemon's browser options, and its own
+// defaults (`--headless` from the viaCli options, `--isolated`) are serialized
+// as if the user had passed them — so the MCP server bin's `applyEnvToArgv`,
+// which skips a flag already on argv, can no longer see OPERA_CLI_HEADED or
+// OPERA_CLI_USER_DATA_DIR. Translating the environment into explicit flags
+// here, before yargs parses the command, lets the config beat those defaults.
+// Only `start` takes the browser flags; `status`, `stop` and the tool commands
+// have strict parsers that would reject them, and a directly-run MCP server
+// still does the translation in its own bin.
+if (process.argv[2] === 'start') {
+    applyEnvToArgv(process.argv);
+}
+// Dynamic import: static imports are hoisted above the module body, so the
+// config load above would otherwise run after the CLI already parsed argv.
+await import('./chrome-devtools.js');
+//# sourceMappingURL=opera-browser-cli.js.map

package/build/src/bin/opera-devtools-cli-options.js

@@ -4,5 +4,5 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 // Compatibility shim. The canonical file is generated by `npm run cli:generate`.
-export * from './chrome-devtools-cli-options.js';
+export * from '../config/cli-options.js';
 //# sourceMappingURL=opera-devtools-cli-options.js.map

package/build/src/bin/opera-devtools-mcp-cli-options.js

@@ -4,5 +4,5 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 // Compatibility shim. Prefer importing the canonical path directly.
-export * from './chrome-devtools-mcp-cli-options.js';
+export * from '../config/mcp-options.js';
 //# sourceMappingURL=opera-devtools-mcp-cli-options.js.map

package/build/src/bin/opera-devtools-mcp.js

@@ -6,5 +6,24 @@
  */
 // Opera-named bin entry (see `package.json` `bin`). The implementation lives in
 // the upstream-owned file and is branded via `src/opera/branding.ts`.
-import './chrome-devtools-mcp.js';
+import { applyEnvToArgv, loadOperaCliConfig } from '../opera/envConfig.js';
+import { runLegacyMigrationGuard } from '../opera/legacyBridgeCleanup.js';
+// Import for its side effect: silences Node's Web Storage warning before
+// `third_party` reads `localStorage`. See `opera/webStorageWarning.ts`.
+import '../opera/webStorageWarning.js';
+// Apply ~/.opera-browser-cli/config and OPERA_CLI_* env vars before the
+// upstream implementation reads `process.argv`.
+loadOperaCliConfig();
+applyEnvToArgv(process.argv);
+// An MCP client starts this bin directly, with no CLI invocation anywhere, so
+// the migration guard has to run here too: a machine that upgraded from the
+// two-package era may still have the old HTTP bridge (port 9225) holding a
+// browser. Nothing runs at install time — npm ≥12 blocks install scripts unless
+// the user opts in — and this file is also the server the daemon spawns, so both
+// shapes of MCP start are covered. One file read when there is no bridge; the
+// port probe behind it runs once per boot. Never throws, never writes to stdout.
+await runLegacyMigrationGuard();
+// Dynamic import: static imports are hoisted above the module body, so the
+// env/config setup above would otherwise run after the server parsed argv.
+await import('./chrome-devtools-mcp.js');
 //# sourceMappingURL=opera-devtools-mcp.js.map

package/build/src/browser.js

@@ -9,29 +9,20 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { disarmBrowserOrphanCleanup, watchBrowserForOrphans, } from './opera/browserCleanup.js';
+import { attachFailed, noDevToolsEndpoint, profileInUse, } from './opera/browserErrors.js';
 import { puppeteer } from './third_party/index.js';
 import { logger, puppeteerLogger } from './utils/logger.js';
+import { isAllowedUrl } from './utils/url.js';
 let browser;
 let browserMode;
-function makeTargetFilter(enableExtensions = false) {
-    const ignoredPrefixes = new Set(['chrome://', 'chrome-untrusted://']);
-    if (!enableExtensions) {
-        ignoredPrefixes.add('chrome-extension://');
-    }
+export function makeTargetFilter(enableExtensions = false) {
     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')) {
+        const url = target.url();
+        if (!url) {
             return true;
         }
-        for (const prefix of ignoredPrefixes) {
-            if (target.url().startsWith(prefix)) {
-                return false;
-            }
-        }
-        return true;
+        return isAllowedUrl(url, { categoryExtensions: enableExtensions });
     };
 }
 export async function ensureBrowserConnected(options) {
@@ -84,9 +75,7 @@ export async function ensureBrowserConnected(options) {
                 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,
-                });
+                throw new Error(noDevToolsEndpoint(userDataDir), { cause: error });
             }
         }
         else {
@@ -109,9 +98,7 @@ export async function ensureBrowserConnected(options) {
         browser = connected;
     }
     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,
-        });
+        throw new Error(attachFailed(options, autoConnect), { cause: err });
     }
     logger?.('Connected Puppeteer');
     return browser;
@@ -201,9 +188,10 @@ export async function launch(options) {
     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,
-            });
+            // The wording lives in `opera/browserErrors.ts`: upstream's answer to a
+            // profile in use ("use --isolated") is the wrong one for the case that
+            // matters — driving the browser you already have.
+            throw new Error(profileInUse(userDataDir), { cause: error });
         }
         throw error;
     }
@@ -214,6 +202,12 @@ export async function ensureBrowserLaunched(options) {
     }
     // Assign mode before browser; see the connect path above for rationale.
     const launched = await launch(options);
+    // Chrome's helpers sit in the browser's process group, not under it in the
+    // process tree, so a browser that dies without closing — SIGKILL, a crash,
+    // an OOM kill — leaves them running as orphans. `disconnected` is the only
+    // signal that the browser is gone, and the group kill it arms is the only
+    // teardown that reaches the helpers; see `opera/browserCleanup.ts`.
+    watchBrowserForOrphans(launched);
     browserMode = 'launched';
     browser = launched;
     return browser;
@@ -237,6 +231,9 @@ export async function closeBrowser() {
         return;
     }
     if (mode === 'launched') {
+        // The close below emits `disconnected` too; without this the orphan-cleanup
+        // handler would SIGKILL the group mid-shutdown. See `opera/browserCleanup.ts`.
+        disarmBrowserOrphanCleanup();
         await b.close().catch(err => {
             logger?.('Failed to close browser', err);
         });
@@ -248,6 +245,7 @@ export async function closeBrowser() {
 }
 export async function closeBrowserIfOpen() {
     if (browser?.connected) {
+        disarmBrowserOrphanCleanup();
         try {
             await browser.close();
         }

package/build/src/config/browser-options.js

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Modified by Opera Software AS.
+ */
+import { CACHE_DIR_NAME, MCP_BIN_NAME, REPO_URL } from '../opera/branding.js';
+export const browserOptions = {
+    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'],
+    },
+    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.`,
+    },
+    chromeArg: {
+        type: 'array',
+        describe: `Additional arguments for Chrome. Only applies when Chrome is launched by ${MCP_BIN_NAME}.`,
+    },
+    ignoreDefaultChromeArg: {
+        type: 'array',
+        describe: `Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by ${MCP_BIN_NAME}.`,
+    },
+};
+export function getBrowserOptions() {
+    return browserOptions;
+}
+//# sourceMappingURL=browser-options.js.map