chrome-devtools-mcp-docker 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KiritoMiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# chrome-devtools-mcp-docker
+
+Lazy Docker-backed Chrome for Chrome DevTools MCP, with a noVNC web interface for watching or controlling the same browser session.
+
+When the MCP server starts, it:
+
+1. Starts a Selenium standalone Chrome container in Docker.
+2. Generates a temporary noVNC password.
+3. Prints web-control URLs with the password embedded.
+4. Creates a Chrome session and connects the bundled `chrome-devtools-mcp` server to its CDP endpoint.
+5. Stops the container when the MCP server exits, unless configured otherwise.
+
+## Requirements
+
+- Node.js 20.19 or newer.
+- Docker Engine.
+- Permission to run Docker as the current user, or passwordless `sudo docker`.
+
+## Codex Config
+
+From GitHub:
+
+```toml
+[mcp_servers.chrome-devtools]
+command = "npx"
+args = [
+  "-y",
+  "git+ssh://git@github.com/KiritoMiao/chrome-devtools-mcp-docker.git",
+  "--web-host",
+  "127.0.0.1",
+  "--web-port",
+  "8080"
+]
+startup_timeout_ms = 60_000
+```
+
+From npm, after publishing:
+
+```toml
+[mcp_servers.chrome-devtools]
+command = "npx"
+args = ["-y", "chrome-devtools-mcp-docker"]
+startup_timeout_ms = 60_000
+```
+
+## Web Interface
+
+The temporary URL is printed to MCP stderr on startup:
+
+```text
+[chrome-devtools-mcp-docker] browser web control URL (configured): http://127.0.0.1:8080/?autoconnect=1&resize=scale&password=<temporary-password>
+[chrome-devtools-mcp-docker] browser web control URL (cloudflare public IP <detected-ip>): http://<detected-ip>:8080/?autoconnect=1&resize=scale&password=<temporary-password>
+[chrome-devtools-mcp-docker] browser web control URL (interface IP <detected-ip>): http://<detected-ip>:8080/?autoconnect=1&resize=scale&password=<temporary-password>
+```
+
+The Cloudflare line is detected from `https://www.cloudflare.com/cdn-cgi/trace`. The interface line is detected from the host network interfaces. If a detector cannot find an address, that line is omitted.
+
+Useful options:
+
+```sh
+npx -y chrome-devtools-mcp-docker --web-host 127.0.0.1 --web-port 8080
+npx -y chrome-devtools-mcp-docker --web-listen 0.0.0.0:18080 --web-url http://YOUR_HOST:18080
+```
+
+`--web-host` controls the listen IP address for the browser web interface. `--web-port` controls the browser web interface host port. Selenium/CDP stays bound to `127.0.0.1:4444` by default.
+
+If exposing the web interface beyond localhost, set `--web-url` to the URL users should open.
+
+## CLI
+
+```text
+chrome-devtools-mcp-docker [options] [-- chrome-devtools-mcp args]
+```
+
+Options:
+
+- `--web-host <ip>`: IP address for the browser web UI to listen on. Default: `127.0.0.1`.
+- `--web-port <port>`: Host port for the browser web UI. Default: `8080`.
+- `--web-listen <ip:port>`: Shorthand for `--web-host` and `--web-port`.
+- `--web-url <url>`: URL printed for users. Default: `http://127.0.0.1:<web-port>`.
+- `--selenium-port <port>`: Host port for the Selenium/CDP proxy. Default: `4444`.
+- `--selenium-session-timeout <seconds>`: Selenium browser session timeout. Default: `86400`.
+- `--devtools-host <ip>`: IP address for the Selenium/CDP host port. Default: `127.0.0.1`.
+- `--image <image>`: Docker image. Default: `selenium/standalone-chrome:latest`.
+- `--container <name>`: Docker container name. Default: `chrome-devtools-mcp-docker`.
+- `--no-stop-on-exit`: Leave the browser container running after MCP exits.
+- `--status`: Show container status without starting it.
+- `--stop-container`: Stop the container.
+
+Environment variables use the `CHROME_DEVTOOLS_MCP_DOCKER_` prefix, for example:
+
+- `CHROME_DEVTOOLS_MCP_DOCKER_WEB_HOST`
+- `CHROME_DEVTOOLS_MCP_DOCKER_WEB_PORT`
+- `CHROME_DEVTOOLS_MCP_DOCKER_WEB_URL`
+- `CHROME_DEVTOOLS_MCP_DOCKER_SELENIUM_PORT`
+- `CHROME_DEVTOOLS_MCP_DOCKER_SELENIUM_SESSION_TIMEOUT`
+
+## Development
+
+```sh
+npm install
+npm test
+npm pack --dry-run
+```
+
+## Publishing
+
+Publishing is handled by GitHub Actions through npm trusted publishing. Configure npm before the first release:
+
+1. Create or claim the `chrome-devtools-mcp-docker` package on npm.
+2. In npm package settings, add a trusted publisher:
+   - Provider: GitHub Actions
+   - Organization/user: `KiritoMiao`
+   - Repository: `chrome-devtools-mcp-docker`
+   - Workflow filename: `publish.yml`
+   - Environment: leave empty
+3. Push a version bump to `main`.
+4. Create a GitHub release for that version.
+
+The workflow runs tests and `npm pack --dry-run`, then publishes to npm with provenance. Published prereleases use the `next` dist-tag by default; normal releases use `latest`. You can also run the workflow manually and choose `latest` or `next`.

package/bin/chrome-devtools-mcp-docker.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { helpText, loadConfig } from '../src/config.js';
+import { runServer } from '../src/runtime.js';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+try {
+  const config = loadConfig();
+
+  if (config.help) {
+    process.stdout.write(helpText());
+    process.exit(0);
+  }
+
+  if (config.version) {
+    const packageJson = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    process.stdout.write(`${packageJson.version}\n`);
+    process.exit(0);
+  }
+
+  const exitCode = await runServer(config);
+  process.exit(exitCode);
+} catch (error) {
+  process.stderr.write(`[chrome-devtools-mcp-docker] error: ${error.message}\n`);
+  process.exit(1);
+}

package/examples/codex-config.toml

@@ -0,0 +1,11 @@
+[mcp_servers.chrome-devtools]
+command = "npx"
+args = [
+  "-y",
+  "git+ssh://git@github.com/KiritoMiao/chrome-devtools-mcp-docker.git",
+  "--web-host",
+  "127.0.0.1",
+  "--web-port",
+  "8080"
+]
+startup_timeout_ms = 60_000

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "chrome-devtools-mcp-docker",
+  "version": "0.1.5",
+  "description": "Lazy Docker-backed Chrome DevTools MCP server with a noVNC web UI.",
+  "type": "module",
+  "bin": {
+    "chrome-devtools-mcp-docker": "bin/chrome-devtools-mcp-docker.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "start": "node ./bin/chrome-devtools-mcp-docker.js"
+  },
+  "dependencies": {
+    "chrome-devtools-mcp": "0.25.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KiritoMiao/chrome-devtools-mcp-docker.git"
+  },
+  "keywords": [
+    "mcp",
+    "chrome-devtools",
+    "selenium",
+    "novnc",
+    "docker",
+    "chromium"
+  ],
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/config.js

@@ -0,0 +1,281 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export const DEFAULTS = Object.freeze({
+  containerName: 'chrome-devtools-mcp-docker',
+  image: undefined,
+  webHost: '127.0.0.1',
+  webPort: 8080,
+  devtoolsHost: '127.0.0.1',
+  seleniumPort: 4444,
+  seleniumContainerPort: 4444,
+  seleniumSessionTimeout: 86400,
+  shmSize: '2g',
+  stopOnExit: true,
+  waitAttempts: 80
+});
+
+const ENV_MAP = Object.freeze({
+  containerName: 'CHROME_DEVTOOLS_MCP_DOCKER_CONTAINER',
+  image: 'CHROME_DEVTOOLS_MCP_DOCKER_IMAGE',
+  webHost: 'CHROME_DEVTOOLS_MCP_DOCKER_WEB_HOST',
+  webPort: 'CHROME_DEVTOOLS_MCP_DOCKER_WEB_PORT',
+  webUrl: 'CHROME_DEVTOOLS_MCP_DOCKER_WEB_URL',
+  devtoolsHost: 'CHROME_DEVTOOLS_MCP_DOCKER_DEVTOOLS_HOST',
+  seleniumPort: 'CHROME_DEVTOOLS_MCP_DOCKER_SELENIUM_PORT',
+  seleniumContainerPort: 'CHROME_DEVTOOLS_MCP_DOCKER_SELENIUM_CONTAINER_PORT',
+  seleniumSessionTimeout: 'CHROME_DEVTOOLS_MCP_DOCKER_SELENIUM_SESSION_TIMEOUT',
+  shmSize: 'CHROME_DEVTOOLS_MCP_DOCKER_SHM_SIZE',
+  currentUrlFile: 'CHROME_DEVTOOLS_MCP_DOCKER_CURRENT_URL_FILE',
+  stopOnExit: 'CHROME_DEVTOOLS_MCP_DOCKER_STOP_CONTAINER_ON_EXIT',
+  waitAttempts: 'CHROME_DEVTOOLS_MCP_DOCKER_WAIT_ATTEMPTS'
+});
+
+const FLAG_MAP = Object.freeze({
+  '--container': 'containerName',
+  '--container-name': 'containerName',
+  '--image': 'image',
+  '--web-host': 'webHost',
+  '--web-port': 'webPort',
+  '--web-url': 'webUrl',
+  '--devtools-host': 'devtoolsHost',
+  '--selenium-port': 'seleniumPort',
+  '--selenium-container-port': 'seleniumContainerPort',
+  '--selenium-session-timeout': 'seleniumSessionTimeout',
+  '--shm-size': 'shmSize',
+  '--current-url-file': 'currentUrlFile',
+  '--wait-attempts': 'waitAttempts'
+});
+
+const REMOVED_FLAGS = new Set([
+  '--backend',
+  '--devtools-port',
+  '--devtools-container-port',
+  '--webrtc-port',
+  '--webrtc-nat-ip',
+  '--screen-width',
+  '--screen-height',
+  '--screen-rate'
+]);
+
+const NUMBER_KEYS = new Set([
+  'webPort',
+  'seleniumPort',
+  'seleniumContainerPort',
+  'seleniumSessionTimeout',
+  'waitAttempts'
+]);
+
+export function loadConfig({ argv = process.argv.slice(2), env = process.env } = {}) {
+  const options = { ...DEFAULTS };
+  options.currentUrlFile = defaultCurrentUrlFile(env);
+
+  for (const [key, envName] of Object.entries(ENV_MAP)) {
+    if (env[envName] !== undefined && env[envName] !== '') {
+      options[key] = coerceValue(key, env[envName]);
+    }
+  }
+
+  const passthroughArgs = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--') {
+      passthroughArgs.push(...argv.slice(index + 1));
+      break;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--version' || arg === '-v') {
+      options.version = true;
+      continue;
+    }
+
+    if (arg === '--status' || arg === '--stop-container') {
+      options.command = arg.slice(2);
+      continue;
+    }
+
+    if (arg === '--no-stop-on-exit') {
+      options.stopOnExit = false;
+      continue;
+    }
+
+    if (arg === '--stop-on-exit') {
+      options.stopOnExit = true;
+      continue;
+    }
+
+    if (arg === '--web-listen') {
+      const value = argv[++index];
+      if (!value) {
+        throw new Error('--web-listen requires host:port');
+      }
+      const parsed = parseHostPort(value, '--web-listen');
+      options.webHost = parsed.host;
+      options.webPort = parsed.port;
+      continue;
+    }
+
+    const inline = arg.match(/^(--[^=]+)=(.*)$/);
+    const flag = inline ? inline[1] : arg;
+    if (REMOVED_FLAGS.has(flag)) {
+      throw new Error(`Unsupported option: ${flag}`);
+    }
+    if (FLAG_MAP[flag]) {
+      const key = FLAG_MAP[flag];
+      const value = inline ? inline[2] : argv[++index];
+      if (value === undefined) {
+        throw new Error(`${flag} requires a value`);
+      }
+      options[key] = coerceValue(key, value);
+      continue;
+    }
+
+    passthroughArgs.push(arg);
+  }
+
+  validateConfig(options);
+
+  if (!options.image) {
+    options.image = 'selenium/standalone-chrome:latest';
+  }
+
+  const webUrl = options.webUrl ?? `http://${displayHost(options.webHost)}:${options.webPort}`;
+  const seleniumUrl = `http://${options.devtoolsHost}:${options.seleniumPort}`;
+  const seleniumWsUrl = `ws://${options.devtoolsHost}:${options.seleniumPort}`;
+
+  return Object.freeze({
+    ...options,
+    webUrl,
+    seleniumUrl,
+    seleniumWsUrl,
+    passthroughArgs
+  });
+}
+
+export function buildDockerRunArgs(config, { adminPassword }) {
+  return [
+    'run',
+    '-d',
+    '--rm',
+    '--name',
+    config.containerName,
+    '--shm-size',
+    config.shmSize,
+    '-p',
+    `${config.webHost}:${config.webPort}:7900/tcp`,
+    '-p',
+    `${config.devtoolsHost}:${config.seleniumPort}:${config.seleniumContainerPort}/tcp`,
+    '-e',
+    `SE_VNC_PASSWORD=${adminPassword}`,
+    '-e',
+    'SE_NODE_MAX_SESSIONS=1',
+    '-e',
+    `SE_NODE_SESSION_TIMEOUT=${config.seleniumSessionTimeout}`,
+    config.image
+  ];
+}
+
+export function helpText() {
+  return `chrome-devtools-mcp-docker
+
+Starts a Docker-backed browser with a web UI and proxies chrome-devtools-mcp to it.
+
+Usage:
+  chrome-devtools-mcp-docker [options] [-- chrome-devtools-mcp args]
+
+Options:
+  --web-host <ip>            IP address for the browser web UI to listen on. Default: 127.0.0.1
+  --web-port <port>          Host port for the browser web UI. Default: 8080
+  --web-listen <ip:port>     Shorthand for --web-host and --web-port
+  --web-url <url>            URL printed for users. Default: http://127.0.0.1:<web-port>
+  --selenium-port <port>     Host port for Selenium/CDP proxy. Default: 4444
+  --selenium-session-timeout <seconds>
+                              Selenium browser session timeout. Default: 86400
+  --devtools-host <ip>       IP address for DevTools host port. Default: 127.0.0.1
+  --image <image>            Docker image. Default: selenium/standalone-chrome:latest
+  --container <name>         Docker container name. Default: chrome-devtools-mcp-docker
+  --no-stop-on-exit          Leave the browser container running after MCP exits
+  --status                   Show the browser container status
+  --stop-container           Stop the browser container
+  --help                     Show this help
+
+Environment:
+  CHROME_DEVTOOLS_MCP_DOCKER_WEB_HOST
+  CHROME_DEVTOOLS_MCP_DOCKER_WEB_PORT
+  CHROME_DEVTOOLS_MCP_DOCKER_WEB_URL
+  CHROME_DEVTOOLS_MCP_DOCKER_SELENIUM_PORT
+  CHROME_DEVTOOLS_MCP_DOCKER_SELENIUM_SESSION_TIMEOUT
+`;
+}
+
+function defaultCurrentUrlFile(env) {
+  const base =
+    env.XDG_RUNTIME_DIR ||
+    env.TMPDIR ||
+    os.tmpdir();
+  return path.join(base, 'chrome-devtools-mcp-docker-current-url');
+}
+
+function coerceValue(key, value) {
+  if (NUMBER_KEYS.has(key)) {
+    return parsePortishNumber(key, value);
+  }
+
+  if (key === 'stopOnExit') {
+    return !['0', 'false', 'no', 'off'].includes(String(value).toLowerCase());
+  }
+
+  return value;
+}
+
+function parseHostPort(value, label) {
+  const lastColon = value.lastIndexOf(':');
+  if (lastColon <= 0 || lastColon === value.length - 1) {
+    throw new Error(`${label} requires host:port`);
+  }
+
+  return {
+    host: value.slice(0, lastColon),
+    port: parsePort(value.slice(lastColon + 1))
+  };
+}
+
+function parsePortishNumber(key, value) {
+  const number = Number(value);
+  if (!Number.isInteger(number)) {
+    throw new Error(`Invalid number for ${key}: ${value}`);
+  }
+  if (key.toLowerCase().includes('port')) {
+    return parsePort(value);
+  }
+  if (number <= 0) {
+    throw new Error(`Invalid positive number for ${key}: ${value}`);
+  }
+  return number;
+}
+
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+  return port;
+}
+
+function validateConfig(config) {
+  for (const key of ['webHost', 'devtoolsHost']) {
+    if (!config[key] || typeof config[key] !== 'string') {
+      throw new Error(`${key} is required`);
+    }
+  }
+}
+
+function displayHost(host) {
+  return host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
+}

package/src/docker.js

@@ -0,0 +1,72 @@
+import { spawn, spawnSync } from 'node:child_process';
+
+export function resolveDockerCommand() {
+  if (commandSucceeds(['docker', 'info'])) {
+    return ['docker'];
+  }
+  if (commandSucceeds(['sudo', '-n', 'docker', 'info'])) {
+    return ['sudo', 'docker'];
+  }
+  throw new Error('Docker is not available. Re-login for docker group membership or configure passwordless sudo for docker.');
+}
+
+export function runDocker(dockerCommand, args, options = {}) {
+  const result = spawnSync(dockerCommand[0], [...dockerCommand.slice(1), ...args], {
+    encoding: 'utf8',
+    ...options
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    const stderr = result.stderr?.trim();
+    const stdout = result.stdout?.trim();
+    throw new Error(stderr || stdout || `docker ${args.join(' ')} failed with status ${result.status}`);
+  }
+
+  return result.stdout ?? '';
+}
+
+export function spawnDocker(dockerCommand, args, options = {}) {
+  return spawn(dockerCommand[0], [...dockerCommand.slice(1), ...args], {
+    stdio: 'inherit',
+    ...options
+  });
+}
+
+export function containerRunning(dockerCommand, name) {
+  const result = spawnSync(dockerCommand[0], [
+    ...dockerCommand.slice(1),
+    'inspect',
+    '-f',
+    '{{.State.Running}}',
+    name
+  ], {
+    encoding: 'utf8'
+  });
+
+  return result.status === 0 && result.stdout.trim() === 'true';
+}
+
+export function containerExists(dockerCommand, name) {
+  const result = spawnSync(dockerCommand[0], [
+    ...dockerCommand.slice(1),
+    'inspect',
+    name
+  ], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'ignore', 'ignore']
+  });
+
+  return result.status === 0;
+}
+
+function commandSucceeds(command) {
+  const result = spawnSync(command[0], command.slice(1), {
+    stdio: ['ignore', 'ignore', 'ignore']
+  });
+
+  return result.status === 0;
+}

package/src/runtime.js

@@ -0,0 +1,433 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+
+import { buildDockerRunArgs } from './config.js';
+import { containerExists, containerRunning, resolveDockerCommand, runDocker } from './docker.js';
+
+const require = createRequire(import.meta.url);
+
+export async function runServer(config, streams = process) {
+  const dockerCommand = resolveDockerCommand();
+
+  if (config.command === 'status') {
+    streams.stderr.write(runDocker(dockerCommand, ['ps', '-a', '--filter', `name=^/${config.containerName}$`]));
+    await printCurrentUrl(config, streams);
+    return 0;
+  }
+
+  if (config.command === 'stop-container') {
+    if (containerExists(dockerCommand, config.containerName)) {
+      runDocker(dockerCommand, ['stop', config.containerName], { stdio: 'ignore' });
+    }
+    await removeCurrentUrl(config);
+    return 0;
+  }
+
+  let startedByWrapper = false;
+  let mcpProcess;
+  let seleniumSession;
+
+  const cleanup = async () => {
+    if (mcpProcess && !mcpProcess.killed) {
+      mcpProcess.kill('SIGTERM');
+    }
+
+    if (seleniumSession) {
+      try {
+        await deleteSeleniumSession(config, seleniumSession.id);
+      } catch {
+        // Best-effort cleanup.
+      }
+      seleniumSession = undefined;
+    }
+
+    if (startedByWrapper && config.stopOnExit) {
+      log(streams, `stopping container: ${config.containerName}`);
+      try {
+        runDocker(dockerCommand, ['stop', '-t', '10', config.containerName], { stdio: 'ignore' });
+      } catch {
+        // Best-effort cleanup.
+      }
+    }
+
+    await removeCurrentUrl(config);
+  };
+
+  const handleSignal = async (signal) => {
+    await cleanup();
+    process.kill(process.pid, signal);
+  };
+
+  process.once('SIGINT', handleSignal);
+  process.once('SIGTERM', handleSignal);
+
+  try {
+    if (containerRunning(dockerCommand, config.containerName)) {
+      log(streams, `container already running: ${config.containerName}`);
+    } else {
+      if (containerExists(dockerCommand, config.containerName)) {
+        log(streams, `removing stale container: ${config.containerName}`);
+        runDocker(dockerCommand, ['rm', '-f', config.containerName], { stdio: 'ignore' });
+      }
+
+      const adminPassword = generatePassword();
+
+      log(streams, `creating and starting Chrome container: ${config.containerName}`);
+      runDocker(dockerCommand, buildDockerRunArgs(config, {
+        adminPassword
+      }), { stdio: 'ignore' });
+      startedByWrapper = true;
+
+      const controlUrlEntries = await resolveWebControlUrlEntries(config, adminPassword);
+      await fs.writeFile(config.currentUrlFile, serializeWebControlUrlEntries(controlUrlEntries), { mode: 0o600 });
+      logWebControlUrlEntries(streams, controlUrlEntries);
+      log(streams, `temporary browser web password: ${adminPassword}`);
+    }
+
+    await waitForReady(config, dockerCommand, streams);
+    await printCurrentUrl(config, streams);
+
+    seleniumSession = await createSeleniumSession(config, streams);
+
+    mcpProcess = spawnChromeDevtoolsMcp(config, seleniumSession.cdpWsUrl);
+    return await waitForChild(mcpProcess);
+  } finally {
+    process.off('SIGINT', handleSignal);
+    process.off('SIGTERM', handleSignal);
+    await cleanup();
+  }
+}
+
+export async function waitForReady(config, dockerCommand, streams = process) {
+  const statusUrl = `${config.seleniumUrl.replace(/\/$/, '')}/status`;
+  if (!(await waitForHttp(statusUrl, config.waitAttempts))) {
+    log(streams, `Selenium did not become ready at ${statusUrl}`);
+    dumpDockerLogs(dockerCommand, config, streams);
+    throw new Error('Selenium failed to become ready');
+  }
+}
+
+function spawnChromeDevtoolsMcp(config, cdpWsUrl) {
+  const packageJsonPath = require.resolve('chrome-devtools-mcp/package.json');
+  const binPath = path.join(path.dirname(packageJsonPath), 'build/src/bin/chrome-devtools-mcp.js');
+
+  return spawn(process.execPath, [
+    binPath,
+    '--wsEndpoint',
+    cdpWsUrl,
+    '--no-usage-statistics',
+    '--no-performance-crux',
+    ...config.passthroughArgs
+  ], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: '1',
+      CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: '1'
+    }
+  });
+}
+
+async function createSeleniumSession(config, streams) {
+  const response = await requestJson(`${config.seleniumUrl.replace(/\/$/, '')}/session`, {
+    method: 'POST',
+    body: {
+      capabilities: {
+        alwaysMatch: {
+          browserName: 'chrome',
+          'goog:chromeOptions': {
+            args: ['--remote-allow-origins=*']
+          }
+        }
+      }
+    }
+  });
+  const sessionId = response.value?.sessionId;
+  if (!sessionId) {
+    throw new Error('Selenium did not return a session id');
+  }
+
+  const cdpWsUrl = `${config.seleniumWsUrl.replace(/\/$/, '')}/session/${sessionId}/se/cdp`;
+  log(streams, `created Selenium Chrome session: ${sessionId}`);
+  return { id: sessionId, cdpWsUrl };
+}
+
+async function deleteSeleniumSession(config, sessionId) {
+  await requestJson(`${config.seleniumUrl.replace(/\/$/, '')}/session/${sessionId}`, {
+    method: 'DELETE',
+    allowEmpty: true
+  });
+}
+
+function waitForChild(child) {
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        resolve(128);
+      } else {
+        resolve(code ?? 0);
+      }
+    });
+  });
+}
+
+function waitForHttp(url, attempts) {
+  return new Promise((resolve) => {
+    let remaining = attempts;
+
+    const attempt = () => {
+      const request = http.get(url, (response) => {
+        response.resume();
+        if (response.statusCode && response.statusCode >= 200 && response.statusCode < 500) {
+          resolve(true);
+        } else {
+          retry();
+        }
+      });
+
+      request.setTimeout(2000, () => {
+        request.destroy();
+        retry();
+      });
+
+      request.once('error', retry);
+    };
+
+    const retry = () => {
+      remaining -= 1;
+      if (remaining <= 0) {
+        resolve(false);
+        return;
+      }
+      setTimeout(attempt, 500);
+    };
+
+    attempt();
+  });
+}
+
+function requestJson(url, { method = 'GET', body, allowEmpty = false } = {}) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? undefined : JSON.stringify(body);
+    const request = http.request(url, {
+      method,
+      headers: payload
+        ? {
+            'content-type': 'application/json',
+            'content-length': Buffer.byteLength(payload)
+          }
+        : undefined
+    }, (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(text || `HTTP ${response.statusCode} from ${url}`));
+          return;
+        }
+        if (!text && allowEmpty) {
+          resolve({});
+          return;
+        }
+        try {
+          resolve(JSON.parse(text));
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+
+    request.once('error', reject);
+    if (payload) {
+      request.write(payload);
+    }
+    request.end();
+  });
+}
+
+function dumpDockerLogs(dockerCommand, config, streams) {
+  try {
+    streams.stderr.write(runDocker(dockerCommand, ['logs', '--tail=160', config.containerName]));
+  } catch {
+    // Ignore log collection errors.
+  }
+}
+
+async function printCurrentUrl(config, streams) {
+  try {
+    const text = (await fs.readFile(config.currentUrlFile, 'utf8')).trim();
+    if (!text) {
+      return;
+    }
+    logWebControlUrlEntries(streams, parseSerializedWebControlUrlEntries(text));
+  } catch {
+    // No current URL yet.
+  }
+}
+
+export function buildWebControlUrlEntries(config, password, { cloudflarePublicIp, interfacePublicIp } = {}) {
+  const entries = [
+    {
+      label: 'configured',
+      url: webControlUrl(config, password)
+    }
+  ];
+
+  if (cloudflarePublicIp) {
+    entries.push({
+      label: `cloudflare public IP ${cloudflarePublicIp}`,
+      url: webControlUrlForHost(config, password, cloudflarePublicIp)
+    });
+  }
+
+  if (interfacePublicIp) {
+    entries.push({
+      label: `interface IP ${interfacePublicIp}`,
+      url: webControlUrlForHost(config, password, interfacePublicIp)
+    });
+  }
+
+  return entries;
+}
+
+export function serializeWebControlUrlEntries(entries) {
+  if (entries.length === 0) {
+    return '';
+  }
+  const [primary, ...rest] = entries;
+  return [
+    primary.url,
+    ...rest.map((entry) => `${entry.label}=${entry.url}`)
+  ].join('\n') + '\n';
+}
+
+export function parseCloudflareTrace(text) {
+  for (const line of text.split(/\r?\n/)) {
+    const [key, value] = line.split('=', 2);
+    if (key === 'ip' && value && net.isIP(value)) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+export function findInterfacePublicIp(networkInterfaces = os.networkInterfaces()) {
+  for (const addresses of Object.values(networkInterfaces)) {
+    for (const address of addresses ?? []) {
+      const family = typeof address.family === 'string' ? address.family : `IPv${address.family}`;
+      if (family !== 'IPv4' || address.internal || !net.isIPv4(address.address)) {
+        continue;
+      }
+      if (!isPrivateOrLocalIPv4(address.address)) {
+        return address.address;
+      }
+    }
+  }
+  return undefined;
+}
+
+async function resolveWebControlUrlEntries(config, password) {
+  const [cloudflarePublicIp, interfacePublicIp] = await Promise.all([
+    fetchCloudflarePublicIp().catch(() => undefined),
+    Promise.resolve(findInterfacePublicIp())
+  ]);
+
+  return buildWebControlUrlEntries(config, password, {
+    cloudflarePublicIp,
+    interfacePublicIp
+  });
+}
+
+function webControlUrl(config, password) {
+  const baseUrl = config.webUrl.replace(/\/$/, '');
+  return webControlUrlFromBase(config, password, baseUrl);
+}
+
+function webControlUrlForHost(config, password, host) {
+  const base = new URL(config.webUrl);
+  return webControlUrlFromBase(config, password, `${base.protocol}//${urlHost(host)}:${config.webPort}`);
+}
+
+function webControlUrlFromBase(config, password, baseUrl) {
+  return `${baseUrl}/?autoconnect=1&resize=scale&password=${encodeURIComponent(password)}`;
+}
+
+function parseSerializedWebControlUrlEntries(text) {
+  return text.split(/\r?\n/)
+    .filter(Boolean)
+    .map((line, index) => {
+      if (index === 0) {
+        return { label: 'configured', url: line };
+      }
+      const separator = line.indexOf('=');
+      if (separator === -1) {
+        return { label: `url ${index + 1}`, url: line };
+      }
+      return {
+        label: line.slice(0, separator),
+        url: line.slice(separator + 1)
+      };
+    });
+}
+
+function logWebControlUrlEntries(streams, entries) {
+  for (const entry of entries) {
+    log(streams, `browser web control URL (${entry.label}): ${entry.url}`);
+  }
+}
+
+function fetchCloudflarePublicIp() {
+  return new Promise((resolve, reject) => {
+    const request = https.get('https://www.cloudflare.com/cdn-cgi/trace', (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => {
+        if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(`HTTP ${response.statusCode} from Cloudflare trace`));
+          return;
+        }
+        resolve(parseCloudflareTrace(Buffer.concat(chunks).toString('utf8')));
+      });
+    });
+
+    request.setTimeout(3000, () => {
+      request.destroy(new Error('Cloudflare trace timed out'));
+    });
+    request.once('error', reject);
+  });
+}
+
+function isPrivateOrLocalIPv4(address) {
+  const [a, b] = address.split('.').map(Number);
+  return a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168);
+}
+
+function urlHost(host) {
+  return net.isIPv6(host) ? `[${host}]` : host;
+}
+
+async function removeCurrentUrl(config) {
+  await fs.rm(config.currentUrlFile, { force: true });
+}
+
+function generatePassword() {
+  return crypto.randomBytes(18).toString('hex');
+}
+
+function log(streams, message) {
+  streams.stderr.write(`[chrome-devtools-mcp-docker] ${message}\n`);
+}