@dbalabka/chrome-wsl 0.4.0 → 0.6.0

package/README.md

@@ -1,22 +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).
-- Run the script from inside WSL; non-WSL Linux is not supported (Docker has limited proxy-only support, see below).
+
+* Windows Chrome already installed
+* WSL environment
+* The script will install one small dependency (`socat`) automatically for port proxying
+
 
 ## Usage
 
@@ -26,6 +33,10 @@ npx @dbalabka/chrome-wsl
 ```
 - If portproxy/firewall entries are missing, run the printed admin PowerShell commands on Windows, then rerun the script.
 - The script logs `socat` output to `/tmp/socat-9222.log`.
+- To run Chrome in headless mode (no visible window, requires Chrome 112+):
+```sh
+npx @dbalabka/chrome-wsl --headless
+```
 - To stop the `socat` forwarder:
 ```sh
  npx @dbalabka/chrome-wsl --stop
@@ -36,6 +47,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
@@ -61,6 +74,7 @@ To install globally instead of npx:
 Then run:
   ```sh
   chrome-wsl
+  chrome-wsl --headless
   chrome-wsl --stop
   chrome-wsl --uninstall
   ```
@@ -81,6 +95,7 @@ to cofigure the DevTools to connect to `--browser-url=http://127.0.0.1:9222`.
 
 ### Codex
 
+Configuration of [Chrome DevTools](https://github.com/ChromeDevTools/chrome-devtools-mcp):
 ```toml
 [mcp_servers.chome-devtools]
 command = "npx"
@@ -88,6 +103,13 @@ args = ["-y", "chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222
 startup_timeout_sec = 20.0
 ```
 
+Configuratio of [Playwrite](https://github.com/microsoft/playwright-mcp):
+```toml
+[mcp_servers.playwright]
+command = "npx"
+args = ["@playwright/mcp@latest", "--browser=chrome", "--isolated", "--cdp-endpoint=http://127.0.0.1:9222"]
+```
+
 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:

package/chrome-wsl

@@ -74,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.
@@ -106,7 +166,11 @@ confirm() {
   local prompt=$1
   local reply
   local prefix="${CONTAINER_LABEL:+[${CONTAINER_LABEL}] }"
-  read -r -p "${CONFIRM_MARK} ${prefix}${prompt} [y/N] " reply
+  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]$ ]]
 }
 
@@ -145,6 +209,38 @@ get_browser_version() {
     | 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}')
@@ -158,8 +254,23 @@ get_wsl_host_ip() {
 check_portproxy() {
   local host_ip=$1
   local output regex
-  output=$(run_powershell "netsh interface portproxy show all" | tr -d '
-')
+  output=$(run_powershell "netsh interface portproxy show all" | tr -d '\r')
+
+  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."
@@ -348,8 +459,13 @@ stop_chrome() {
 }
 
 start_chrome() {
+  local headless_mode="${1:-0}"
+  local headless_args=""
+  if [[ "$headless_mode" -eq 1 ]]; then
+    headless_args=", \"--headless=new\""
+  fi
   local chrome_cmd
-  chrome_cmd="\$args = @(\"--remote-debugging-port=${PORT}\", \"--no-first-run\", \"--no-default-browser-check\", \"--user-data-dir=\$env:TEMP\\chrome-profile-stable\"); \$p = Start-Process -FilePath \"${WINDOWS_CHROME_PATH}\" -ArgumentList \$args -PassThru; Write-Output \$p.Id"
+  chrome_cmd="\$args = @(\"--remote-debugging-port=${PORT}\", \"--no-first-run\", \"--no-default-browser-check\", \"--user-data-dir=\$env:TEMP\\chrome-profile-stable\"${headless_args}); \$p = Start-Process -FilePath \"${WINDOWS_CHROME_PATH}\" -ArgumentList \$args -PassThru; Write-Output \$p.Id"
 
   if [[ -n "$(get_pid "CHROME_PID")" ]]; then
     if port_listening_by_chrome; then
@@ -388,12 +504,14 @@ ensure_wsl() {
 }
 
 main() {
-  local container="" uninstall_flag=0 stop_flag=0
+  local container="" uninstall_flag=0 stop_flag=0 debug_flag=0 headless_flag=0
   for arg in "$@"; do
     case "$arg" in
       --container=*) container=${arg#*=} ;;
       --uninstall) uninstall_flag=1 ;;
       --stop) stop_flag=1 ;;
+      --debug) debug_flag=1 ;;
+      --headless) headless_flag=1 ;;
     esac
   done
 
@@ -408,6 +526,11 @@ main() {
   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
@@ -431,6 +554,17 @@ main() {
 
   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
@@ -456,13 +590,14 @@ main() {
 
   check_portproxy "$host_ip" || exit 1
   check_firewall_rule || exit 1
+  start_chrome "$headless_flag"
   ensure_socat
   start_socat "$host_ip"
-  start_chrome
+  check_devtools_access_wsl || true
 
   if [[ -n "$container" ]]; then
     container_exec "$container"
   fi
 }
 
-main "$@"
+main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbalabka/chrome-wsl",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "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"
   }
-}
+}