@dbalabka/chrome-wsl 0.3.2 → 0.5.1

package/README.md

@@ -1,21 +1,29 @@
 # Chrome Start From WSL Helper for MCP
 
-A small WSL helper to open Google Chrome on Windows with remote debugging (port 9222) while bridging traffic from WSL via `socat`. It checks/prints the required Windows portproxy and firewall setup, ensures `socat` is installed, starts the tunnel, and launches Chrome with a temporary profile.
-
-## Features
-- Detects Windows host IP automatically from WSL.
-- Verifies Windows portproxy forwarding (9222) and shows admin PowerShell commands if missing.
-- Verifies the Windows firewall rule for port 9222 and shows the admin command if missing.
-- Ensures `socat` is installed on WSL, installs via `apt` when needed.
-- Starts a background `socat` bridge WSL→Windows (logs to `/tmp/socat-9222.log`).
-- Launches Windows Chrome with `--remote-debugging-port=9222` and a temp profile.
-- Skips launching if port 9222 is already listening on Windows; warns if Chrome is running without the debug port.
-- Works under bash or zsh; includes `--stop` to kill the `socat` forwarder.
+A lightweight shell script that **automates Chrome DevTools MCP setup** from **WSL** by launching **Windows Chrome** with remote debugging enabled and transparently proxying traffic from WSL using `socat`.
+
+No Linux Chrome, no gWSL, no manual Windows networking setup.
+
+## What It Does
+
+* 🤖 Automatically bridges **WSL → Windows Chrome DevTools (9222)** using `socat`
+* ✅ Validates required **Windows portproxy and firewall rules**
+* 🚀 Launches **existing Windows Chrome** with remote debugging and a temporary profile
+* 🧹 Cleans up easily with a stop command and leaves no permanent system changes
+
+## Key Features
+
+* **Fully automated**: one command to get Chrome DevTools MCP working from WSL
+* **Lightweight**: simple, readable shell script
+* **Uses your existing Windows Chrome** — no Linux Chrome or gWSL required
+* **Clean & reversible**: minimal system changes, easy to uninstall
 
 ## Prerequisites
-- WSL with `powershell.exe` available.
-- Windows Chrome installed at `C:\Program Files\Google\Chrome\Application\chrome.exe` (adjust the path in the script if different).
-- Network/apt access to install `socat` on first run (or preinstall manually).
+
+* Windows Chrome already installed
+* WSL environment
+* The script will install one small dependency (`socat`) automatically for port proxying
+
 
 ## Usage
 
@@ -35,6 +43,8 @@ npx @dbalabka/chrome-wsl
 ```
 - Runs directly via npm without cloning; default entrypoint is `chrome-wsl` (matching the package name).
 
+> ℹ️️ Note: Must be run from WSL. Docker is supported only for proxying (no Chrome launch).
+
 #### Example
 ```sh
 ❯ npx @dbalabka/chrome-wsl
@@ -64,10 +74,14 @@ Then run:
   chrome-wsl --uninstall
   ```
 
-## Notes
-- Portproxy check expects forwarding from the detected Windows host IP to `127.0.0.1:9222`.
-- Chrome launch is skipped when port 9222 already listens on Windows (assumed active remote-debug session).
-- For a different remote debugging port or Chrome path, edit `PORT` or `WINDOWS_CHROME_PATH` in `start_chrome_wsl.sh`.
+## Docker
+
+`chrome-wsl` can also take care of starting a proxy inside the Docker container and allow to access the MCP server from localhost. It helps to use the same Chrome DevTools MCP configuration for agents running inside the docker container as well as outside.
+```shell
+npx @dbalabka/chrome-wsl --container=<name>
+npx @dbalabka/chrome-wsl --stop --container=<name>
+npx @dbalabka/chrome-wsl --uninstall --container=<name>
+```
 
 ## Chrome DevTools MCP configuration for agents
 
@@ -83,5 +97,13 @@ args = ["-y", "chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222
 startup_timeout_sec = 20.0
 ```
 
+To run Codex inside the container and use the same MCP configuration and authorisation token, mount the Codex configuration folder inside the docker container using the following docker composer settings:
+```shell
+services:
+    app:
+        volumes:
+            - ~/.codex:/home/vscode/.codex
+```
+
 ## License
 MIT License. See `LICENSE` for details.

package/chrome-wsl

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # Compatible with bash and zsh.
+PACKAGE_VERSION="0.4.0"
 set -e
 set -u
 if command -v setopt >/dev/null 2>&1; then
@@ -12,15 +13,25 @@ PORT=9222
 WINDOWS_CHROME_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
 FIREWALL_RULE_NAME='Chrome Remote Debug'
 PID_FILE="/tmp/start-chrome-wsl.pids"
+HOST_IP=""
+BROWSER_VERSION=""
 OK_MARK="✅"
+WARN_MARK="❗"
 ERR_MARK="❌"
 
 ok() {
-  echo "${OK_MARK} $*"
+  local prefix="${CONTAINER_LABEL:+[${CONTAINER_LABEL}] }"
+  echo "${OK_MARK} ${prefix}$*"
 }
 
 err() {
-  echo "${ERR_MARK} $*" >&2
+  local prefix="${CONTAINER_LABEL:+[${CONTAINER_LABEL}] }"
+  echo "${ERR_MARK} ${prefix}$*" >&2
+}
+
+warn() {
+  local prefix="${CONTAINER_LABEL:+[${CONTAINER_LABEL}] }"
+  echo "${WARN_MARK} ${prefix}$*" >&2
 }
 
 set_pid() {
@@ -63,6 +74,66 @@ stop_socat() {
   fi
 }
 
+debug_socat_info() {
+  echo "socat status:"
+  if command -v socat >/dev/null 2>&1; then
+    echo "  version: $(socat -V 2>&1 | head -n 1)"
+  else
+    echo "  version: not installed"
+  fi
+
+  local pattern="socat TCP-LISTEN:${PORT},fork,reuseaddr"
+  if pgrep -af "$pattern" >/dev/null 2>&1; then
+    pgrep -af "$pattern" | while read -r line; do
+      echo "  process: ${line}"
+    done
+  else
+    echo "  process: not running"
+  fi
+
+  local socat_pid
+  socat_pid=$(get_pid "SOCAT_PID")
+  if [[ -n "${socat_pid:-}" ]]; then
+    echo "  tracked pid: ${socat_pid}"
+  else
+    echo "  tracked pid: none"
+  fi
+
+  if [[ -f /tmp/socat-9222.log ]]; then
+    echo "  log: /tmp/socat-9222.log"
+  else
+    echo "  log: not found"
+  fi
+}
+
+debug_linux_listeners() {
+  echo "Linux listeners on port ${PORT}:"
+  if command -v ss >/dev/null 2>&1; then
+    if ss -lntp 2>/dev/null | awk -v port=":${PORT}" '$0 ~ port {print "  " $0}' | head -n 50; then
+      return 0
+    fi
+  fi
+  if command -v lsof >/dev/null 2>&1; then
+    if lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN 2>/dev/null | awk 'NR==1 {print "  " $0; next} {print "  " $0}'; then
+      return 0
+    fi
+  fi
+  echo "  unavailable (no permissions or tools)"
+}
+
+debug_windows_listeners() {
+  echo "Windows listeners on port ${PORT}:"
+  run_powershell "netstat -ano | Select-String -Pattern \"LISTENING\" | Select-String -Pattern \":${PORT}\" | ForEach-Object { \"  \" + \$_.Line }"
+  run_powershell "if (-not (netstat -ano | Select-String -Pattern \"LISTENING\" | Select-String -Pattern \":${PORT}\")) { Write-Output '  none' }"
+}
+
+debug_windows_rules() {
+  echo "Portproxy rules for port ${PORT}:"
+  run_powershell "\$lines = netsh interface portproxy show all | Select-String -SimpleMatch '${PORT}' | ForEach-Object { \$_.Line }; if (\$lines) { \$lines } else { '  none' }"
+  echo "Firewall rules for port ${PORT}:"
+  run_powershell "\$port='${PORT}'; \$rules = Get-NetFirewallRule -ErrorAction SilentlyContinue | Where-Object { \$filter = Get-NetFirewallPortFilter -AssociatedNetFirewallRule \$_ -ErrorAction SilentlyContinue; \$filter -and (\$filter.LocalPort -contains \$port) }; if (\$rules) { \$rules | ForEach-Object { \"  {0} enabled={1} direction={2} action={3} profile={4}\" -f \$_.DisplayName, \$_.Enabled, \$_.Direction, \$_.Action, \$_.Profile } } else { '  none' }"
+}
+
 run_powershell() {
   # Runs a PowerShell command from WSL. If RUN_AS_ADMIN=1, invoke via Start-Process -Verb RunAs
   # and capture output through a temp script/output file to mirror direct execution.
@@ -90,13 +161,25 @@ run_powershell() {
   fi
 }
 
+CONFIRM_MARK="❔"
 confirm() {
   local prompt=$1
   local reply
-  read -r -p "${prompt} [y/N] " reply
+  local prefix="${CONTAINER_LABEL:+[${CONTAINER_LABEL}] }"
+  if [[ -r /dev/tty ]]; then
+    read -r -p "${CONFIRM_MARK} ${prefix}${prompt} [y/N] " reply </dev/tty
+  else
+    read -r -p "${CONFIRM_MARK} ${prefix}${prompt} [y/N] " reply
+  fi
   [[ "${reply}" =~ ^[Yy]$ ]]
 }
 
+version_suffix() {
+  if [[ -n "${BROWSER_VERSION:-}" ]]; then
+    printf " (Chrome %s)" "$BROWSER_VERSION"
+  fi
+}
+
 chrome_running() {
   run_powershell "if (Get-Process -Name chrome -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }"
 }
@@ -118,6 +201,46 @@ port_listening_info() {
   run_powershell "\$conns = Get-NetTCPConnection -LocalPort ${PORT} -ErrorAction SilentlyContinue | Select-Object -Property LocalAddress,LocalPort,RemoteAddress,RemotePort,State,OwningProcess; foreach (\$c in \$conns) { \$p = Get-Process -Id \$c.OwningProcess -ErrorAction SilentlyContinue; \$name = if (\$p) { \$p.Name } else { 'unknown' }; Write-Output (\"{0}:{1} owner={2} pid={3} state={4}\" -f \$c.LocalAddress, \$c.LocalPort, \$name, \$c.OwningProcess, \$c.State) }"
 }
 
+get_browser_version() {
+  local host_ip=${1:-$HOST_IP}
+  [[ -z "${host_ip:-}" ]] && return 0
+  curl -s "http://${host_ip}:${PORT}/json/version" \
+    | sed -n "s/.*\"Browser\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" \
+    | head -n 1
+}
+
+get_protocol_version() {
+  local host_ip=${1:-$HOST_IP}
+  [[ -z "${host_ip:-}" ]] && return 0
+  curl -s "http://${host_ip}:${PORT}/json/version" \
+    | sed -n "s/.*\"Protocol-Version\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" \
+    | head -n 1
+}
+
+check_devtools_access_wsl() {
+  local url_local="http://127.0.0.1:${PORT}/json/version"
+  local url_host="http://${HOST_IP}:${PORT}/json/version"
+  local json browser protocol
+
+  json=$(curl -s --max-time 2 "$url_local" || true)
+  if [[ -z "${json:-}" ]]; then
+    warn "Chrome DevTools not reachable at ${url_local} from WSL."
+    json=$(curl -s --max-time 2 "$url_host" || true)
+    if [[ -z "${json:-}" ]]; then
+      err "Chrome DevTools not reachable at ${url_host} from WSL."
+      return 1
+    fi
+  fi
+
+  browser=$(echo "$json" | sed -n "s/.*\"Browser\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" | head -n 1)
+  protocol=$(echo "$json" | sed -n "s/.*\"Protocol-Version\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" | head -n 1)
+  if [[ -n "${browser:-}" || -n "${protocol:-}" ]]; then
+    ok "DevTools reachable from WSL: ${browser:-unknown} (Protocol ${protocol:-unknown})."
+  else
+    warn "DevTools reachable from WSL, but version info was not parsed."
+  fi
+}
+
 get_wsl_host_ip() {
   local host_ip
   host_ip=$(ip route | awk '/^default via / {print $3; exit}')
@@ -132,12 +255,38 @@ check_portproxy() {
   local host_ip=$1
   local output regex
   output=$(run_powershell "netsh interface portproxy show all" | tr -d '\r')
-  regex="${host_ip//./\\.}[[:space:]]+${PORT}[[:space:]]+127\\.0\\.0\\.1[[:space:]]+${PORT}"
+
+  echo "$output" | awk 'NF>=4 && $2 ~ /^[0-9]+$/ {print $1, $2, $3, $4}' | while read -r listen_addr listen_port connect_addr connect_port; do
+    if [[ "$listen_port" == "$PORT" && "$listen_addr" != "$host_ip" ]]; then
+      if confirm "Remove portproxy ${listen_addr}:${listen_port} -> ${connect_addr}:${connect_port} (conflicts with ${host_ip}:${PORT})?"; then
+        if RUN_AS_ADMIN=1 run_powershell "netsh interface portproxy delete v4tov4 listenaddress=${listen_addr} listenport=${listen_port}"; then
+          ok "Removed conflicting portproxy ${listen_addr}:${listen_port}."
+        else
+          warn "Failed to remove conflicting portproxy ${listen_addr}:${listen_port}."
+        fi
+      else
+        warn "Keeping conflicting portproxy ${listen_addr}:${listen_port}."
+      fi
+    fi
+  done
+
+  output=$(run_powershell "netsh interface portproxy show all" | tr -d '\r')
+  regex="${host_ip//./\.}[[:space:]]+${PORT}[[:space:]]+127\.0\.0\.1[[:space:]]+${PORT}"
   if echo "$output" | grep -Eq "$regex"; then
     ok "Portproxy ${host_ip}:${PORT} -> 127.0.0.1:${PORT} is configured."
     return 0
   fi
 
+  warn "Portproxy on ${host_ip}:${PORT} is missing; attempting to create it (may prompt for admin)."
+  if RUN_AS_ADMIN=1 run_powershell "netsh interface portproxy add v4tov4 listenaddress=${host_ip} listenport=${PORT} connectaddress=127.0.0.1 connectport=${PORT}"; then
+    output=$(run_powershell "netsh interface portproxy show all" | tr -d '
+')
+    if echo "$output" | grep -Eq "$regex"; then
+      ok "Created portproxy ${host_ip}:${PORT} -> 127.0.0.1:${PORT}."
+      return 0
+    fi
+  fi
+
   cat <<EOF
 ${ERR_MARK} Portproxy on ${host_ip}:${PORT} is missing.
 Run this in an **admin PowerShell** window:
@@ -154,7 +303,7 @@ check_firewall_rule() {
     return 0
   fi
 
-  err "Firewall rule \"${FIREWALL_RULE_NAME}\" is missing; attempting to create it (may prompt for admin)."
+  warn "Firewall rule \"${FIREWALL_RULE_NAME}\" is missing; attempting to create it (may prompt for admin)."
   if RUN_AS_ADMIN=1 run_powershell "New-NetFirewallRule -DisplayName \"${FIREWALL_RULE_NAME}\" -Direction Inbound -LocalPort ${PORT} -Protocol TCP -Action Allow" \
      && run_powershell "${rule_check_cmd}"; then
     ok "Created firewall rule \"${FIREWALL_RULE_NAME}\"."
@@ -209,13 +358,40 @@ uninstall_socat() {
   fi
 }
 
+# Remove portproxy entry
+uninstall_portproxy() {
+  local host_ip=${1:-$HOST_IP}
+  if [[ -z "${host_ip:-}" ]]; then
+    host_ip=$(get_wsl_host_ip)
+  fi
+  local output regex
+  output=$(run_powershell "netsh interface portproxy show all" | tr -d '\r')
+  regex="${host_ip//./\\.}[[:space:]]+${PORT}[[:space:]]+127\\.0\\.0\\.1[[:space:]]+${PORT}"
+  if ! echo "$output" | grep -Eq "$regex"; then
+    ok "Portproxy ${host_ip}:${PORT} is already absent."
+    return 0
+  fi
+
+  if ! confirm "Remove portproxy ${host_ip}:${PORT} -> 127.0.0.1:${PORT}?"; then
+    ok "Skipped portproxy removal."
+    return 0
+  fi
+
+  if RUN_AS_ADMIN=1 run_powershell "netsh interface portproxy delete v4tov4 listenaddress=${host_ip} listenport=${PORT}" \
+     && ! (run_powershell "netsh interface portproxy show all" | tr -d '\r' | grep -Eq "$regex"); then
+    ok "Removed portproxy ${host_ip}:${PORT} -> 127.0.0.1:${PORT}."
+  else
+    err "Failed to remove portproxy ${host_ip}:${PORT}."
+  fi
+}
+
 ensure_socat() {
   if command -v socat >/dev/null 2>&1; then
     ok "socat is already installed."
     return 0
   fi
 
-  err "socat not found. Installing via apt..."
+  warn "socat not found. Installing via apt..."
   sudo apt-get update
   sudo apt-get install -y socat
 }
@@ -232,6 +408,40 @@ start_socat() {
   ok "Started socat (logging to /tmp/socat-9222.log)."
 }
 
+is_docker() {
+  [[ -f /.dockerenv ]] && return 0
+  grep -qaE 'docker|containerd|kubepods' /proc/1/cgroup 2>/dev/null
+}
+
+container_exec() {
+  local container=$1; shift
+  local script_path
+  script_path=$(readlink -f "$0")
+  ensure_docker
+  local tty_flag="-i"
+  if [ -t 0 ]; then
+    tty_flag="-it"
+  fi
+  if ! cat "$script_path" | docker exec -i "${container}" sh -c "cat > /tmp/chrome-wsl.sh"; then
+    err "Failed to copy script into container ${container}."
+    exit 1
+  fi
+  local inner_cmd="CONTAINER_LABEL=${container} chmod +x /tmp/chrome-wsl.sh && CONTAINER_LABEL=${container} /tmp/chrome-wsl.sh $*"
+  docker exec ${tty_flag} "${container}" sh -lc "${inner_cmd}"
+}
+
+get_docker_host_ip() {
+  getent hosts host.docker.internal 2>/dev/null | awk '{print $1; exit}'
+}
+
+ensure_docker() {
+  if command -v docker >/dev/null 2>&1; then
+    return 0
+  fi
+  err "Docker CLI is required for --container."
+  exit 1
+}
+
 stop_chrome() {
   local chrome_pid
   chrome_pid=$(get_pid "CHROME_PID")
@@ -280,28 +490,108 @@ start_chrome() {
   fi
 }
 
+ensure_wsl() {
+  if grep -qEi 'Microsoft|WSL' /proc/version >/dev/null 2>&1; then
+    return 0
+  fi
+  err "This tool must be run inside WSL; exiting."
+  exit 1
+}
+
 main() {
-  if [[ "${1-}" == "--uninstall" ]]; then
+  local container="" uninstall_flag=0 stop_flag=0 debug_flag=0
+  for arg in "$@"; do
+    case "$arg" in
+      --container=*) container=${arg#*=} ;;
+      --uninstall) uninstall_flag=1 ;;
+      --stop) stop_flag=1 ;;
+      --debug) debug_flag=1 ;;
+    esac
+  done
+
+  if [[ "${1-}" == "--version" || "${1-}" == "-V" ]]; then
+    echo "chrome-wsl ${PACKAGE_VERSION:-unknown}"
+    exit 0
+  fi
+
+  if is_docker && [[ -n "$container" ]]; then
+    err "--container is only supported when running in WSL, not inside Docker."
+    exit 1
+  fi
+
+  if is_docker; then
+    if [[ $debug_flag -eq 1 ]]; then
+      debug_socat_info
+      exit 0
+    fi
+
+    if [[ $uninstall_flag -eq 1 ]]; then
+      uninstall_socat
+      exit 0
+    fi
+
+    if [[ $stop_flag -eq 1 ]]; then
+      stop_socat
+      exit 0
+    fi
+
+    HOST_IP=$(get_docker_host_ip)
+    if [[ -z "${HOST_IP:-}" ]]; then
+      err "Could not resolve host.docker.internal inside Docker."
+      exit 1
+    fi
+
+    ensure_socat
+    start_socat "$HOST_IP"
+    exit 0
+  fi
+
+  ensure_wsl
+
+  if [[ $debug_flag -eq 1 ]]; then
+    debug_windows_rules
+    debug_windows_listeners
+    debug_linux_listeners
+    debug_socat_info
+    if [[ -n "$container" ]]; then
+      container_exec "$container" --debug
+    fi
+    exit 0
+  fi
+
+  if [[ $uninstall_flag -eq 1 ]]; then
+    uninstall_portproxy
     uninstall_firewall_rule
     uninstall_socat
+    if [[ -n "$container" ]]; then
+      container_exec "$container" --uninstall
+    fi
     exit 0
   fi
 
-  if [[ "${1-}" == "--stop" ]]; then
+  if [[ $stop_flag -eq 1 ]]; then
     stop_chrome
     stop_socat
+    if [[ -n "$container" ]]; then
+      container_exec "$container" --stop
+    fi
     exit 0
   fi
 
-  local host_ip
-  host_ip=$(get_wsl_host_ip)
+  HOST_IP=$(get_wsl_host_ip)
+  local host_ip="$HOST_IP"
   ok "Detected Windows host IP: ${host_ip}"
 
   check_portproxy "$host_ip" || exit 1
   check_firewall_rule || exit 1
+  start_chrome
   ensure_socat
   start_socat "$host_ip"
-  start_chrome
+  check_devtools_access_wsl || true
+
+  if [[ -n "$container" ]]; then
+    container_exec "$container"
+  fi
 }
 
 main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbalabka/chrome-wsl",
-  "version": "0.3.2",
+  "version": "0.5.1",
   "description": "WSL helper to start Windows Chrome with remote debugging and socat port forwarding.",
   "bin": "./chrome-wsl",
   "files": [
@@ -28,4 +28,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}