cdp-mcp 0.2.2 → 0.4.0

package/docs/launchd-service.md

@@ -1,217 +0,0 @@
-# macOS: Run as a Persistent Service (launchd)
-
-Register `cdp-mcp` as a launchd user agent so it starts automatically on login
-and exposes the MCP SSE endpoint on `127.0.0.1:9719`.
-
-Persistent service mode is useful for MCP clients that support SSE because the
-`cdp-mcp` process and its browser/CDP session can survive MCP client restarts or
-reconnects. It does **not** persist state across service-process restarts.
-
-> Security note: the local SSE endpoint has no authentication. MCP tools include
-> in-page JavaScript evaluation and filesystem writes via screenshot paths. Only
-> run a persistent service on trusted single-user machines, and do not bind it to
-> non-loopback interfaces unless you understand the `--allow-remote` exposure.
-
-## Contents
-
-- [1. Install the server](#1-install-the-server)
-- [2. Create the plist](#2-create-the-plist)
-- [3. Load and start](#3-load-and-start)
-- [4. Verify](#4-verify)
-- [5. Configure an MCP client](#5-configure-an-mcp-client)
-- [6. Logs](#6-logs)
-- [7. Stop / uninstall](#7-stop--uninstall)
-- [8. Upgrade](#8-upgrade)
-- [Troubleshooting](#troubleshooting)
-
-## 1. Install the server
-
-Requires Node.js 20+ and a local Chrome/Chromium browser.
-
-```bash
-npm install -g cdp-mcp
-```
-
-Verify with `cdp-mcp --help`. The package ships prebuilt `dist/`, so there is no
-build step and no repo checkout needed.
-
-If `launch_chrome` cannot find Chrome/Chromium automatically, set `CHROME_PATH`
-in the plist generated below.
-
-## 2. Create the plist
-
-Run this from any directory:
-
-```bash
-# If you use fnm, nvm, or another Node version manager, set these variables to
-# stable paths before running this snippet. Example:
-# NODE_BIN="$HOME/.local/share/fnm/aliases/default/bin/node"
-# CDP_SCRIPT="$HOME/.local/share/fnm/aliases/default/bin/cdp-mcp"
-NODE_BIN="${NODE_BIN:-$(command -v node)}"
-CDP_SCRIPT="${CDP_SCRIPT:-$(command -v cdp-mcp)}"
-CHROME_PATH="${CHROME_PATH:-}"
-
-if [ -z "$NODE_BIN" ]; then
-  echo "Error: node not found in PATH. Install Node 20+ first." >&2
-  exit 1
-fi
-if [ -z "$CDP_SCRIPT" ]; then
-  echo "Error: cdp-mcp not found. Run 'npm install -g cdp-mcp' first." >&2
-  exit 1
-fi
-
-xml_escape() {
-  printf '%s' "$1" \
-    | sed \
-      -e 's/&/\&/g' \
-      -e 's/</\&lt;/g' \
-      -e 's/>/\&gt;/g' \
-      -e 's/"/\&quot;/g' \
-      -e "s/'/\&apos;/g"
-}
-
-NODE_DIR="$(dirname "$NODE_BIN")"
-mkdir -p ~/Library/LaunchAgents ~/Library/Logs/cdp-mcp
-ESC_NODE=$(xml_escape "$NODE_BIN")
-ESC_NODE_DIR=$(xml_escape "$NODE_DIR")
-ESC_CDP=$(xml_escape "$CDP_SCRIPT")
-ESC_HOME=$(xml_escape "$HOME")
-ESC_CHROME=$(xml_escape "$CHROME_PATH")
-cat > ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist <<PLIST
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
-  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>io.github.lcjanke2020.cdp-mcp</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>$ESC_NODE</string>
-    <string>$ESC_CDP</string>
-    <string>--port</string>
-    <string>9719</string>
-  </array>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <true/>
-  <key>StandardOutPath</key>
-  <string>$ESC_HOME/Library/Logs/cdp-mcp/server.stdout.log</string>
-  <key>StandardErrorPath</key>
-  <string>$ESC_HOME/Library/Logs/cdp-mcp/server.stderr.log</string>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PATH</key>
-    <string>$ESC_NODE_DIR:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
-$(if [ -n "$CHROME_PATH" ]; then printf '    <key>CHROME_PATH</key>\n    <string>%s</string>\n' "$ESC_CHROME"; fi)
-  </dict>
-</dict>
-</plist>
-PLIST
-```
-
-The plist invokes `node` directly with the `cdp-mcp` script path. That makes the
-`NODE_BIN` override authoritative even when your shell uses a Node version
-manager.
-
-## 3. Load and start
-
-On macOS 10.15+, use:
-
-```bash
-launchctl bootstrap gui/$UID ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist
-launchctl kickstart -k gui/$UID/io.github.lcjanke2020.cdp-mcp
-```
-
-Older macOS releases also support:
-
-```bash
-launchctl load ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist
-```
-
-## 4. Verify
-
-```bash
-launchctl print gui/$UID/io.github.lcjanke2020.cdp-mcp
-lsof -i :9719
-curl -v --max-time 2 http://127.0.0.1:9719/sse 2>&1 | head -20
-```
-
-The `curl` command should show a `200 OK` response and SSE event output. A
-timeout after the first event is expected because `/sse` keeps the connection
-open. The server also sends periodic SSE keepalive comments by default; tune
-with `CDP_MCP_SSE_KEEPALIVE_MS` only if your MCP client needs a different idle
-interval.
-
-## 5. Configure an MCP client
-
-Point an SSE-capable MCP client at:
-
-```text
-http://127.0.0.1:9719/sse
-```
-
-For example, clients that use JSON MCP server config commonly use:
-
-```json
-{
-  "mcpServers": {
-    "cdp-mcp": {
-      "type": "sse",
-      "url": "http://127.0.0.1:9719/sse"
-    }
-  }
-}
-```
-
-SSE mode is single-client today. Multiple MCP clients connected to the same
-service share one process-global browser/CDP session and can interfere with each
-other. Use one active debugging client per service, or run separate services on
-separate ports.
-
-A reconnecting client resumes the prior session. If you want a clean browser
-session after reconnecting, call `close_session` before launching or attaching
-again.
-
-## 6. Logs
-
-```bash
-tail -f ~/Library/Logs/cdp-mcp/server.stderr.log
-```
-
-## 7. Stop / uninstall
-
-```bash
-launchctl bootout gui/$UID/io.github.lcjanke2020.cdp-mcp
-rm ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist
-```
-
-Older macOS releases also support:
-
-```bash
-launchctl unload ~/Library/LaunchAgents/io.github.lcjanke2020.cdp-mcp.plist
-```
-
-## 8. Upgrade
-
-```bash
-npm install -g cdp-mcp@latest
-launchctl kickstart -k gui/$UID/io.github.lcjanke2020.cdp-mcp
-```
-
-Restart or reconnect your MCP client after a server upgrade so it reloads tool
-schemas.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| `bootstrap` says service already loaded | Run `launchctl bootout gui/$UID/io.github.lcjanke2020.cdp-mcp`, then bootstrap again |
-| Service exits immediately | Check `~/Library/Logs/cdp-mcp/server.stderr.log`; usually `cdp-mcp` is not installed, Node is too old, or a version-manager path moved |
-| Port 9719 is already in use | Check `lsof -i :9719`, then stop the other process or change the port in the plist |
-| MCP client rejects the config | Confirm the client supports SSE MCP servers and include both `"type": "sse"` and the `/sse` URL if your client uses JSON config |
-| `launch_chrome` cannot find Chrome | Set `CHROME_PATH` before generating the plist, or edit the plist environment and reload the service |
-| Service not starting after reboot | Verify the plist is in `~/Library/LaunchAgents/`, not `LaunchDaemons` |
-| Service not starting after reboot with fnm/nvm | Version-manager shell paths can be ephemeral. Recreate the plist with stable `NODE_BIN` and `CDP_SCRIPT` paths, or install with a system Node |
-| `already_session` after reconnecting | The prior browser/CDP session is still alive. Resume it, or call `close_session` before starting fresh |

package/docs/local-l3-e2e-setup.md

@@ -1,199 +0,0 @@
-# Local L3 e2e setup (Playwright Chromium + AppArmor)
-
-**Last updated: 2026-06-09**
-
-A step-by-step runbook for getting `npm run test:e2e` (the L3 real-browser
-suite) passing on a local Linux machine **with Chromium's sandbox on**. This is
-the practical companion to [`chromium-sandboxing.md`](./chromium-sandboxing.md);
-read that for the full `--no-sandbox` / `sandbox: true` threat model and the
-validated-hosts table.
-
-Assumes Ubuntu (23.10+/24.04). Other distributions may need no host-side work at
-all — see "Other distributions" below.
-
-## Why this is needed on Ubuntu
-
-The L3 e2e harness launches Chromium with the sandbox **on** when running
-locally; it only adds `--no-sandbox` when the `CI` env var is set
-(`test/e2e/setup/global.ts`). That is deliberate — locally we want the sandbox
-when the host can provide it.
-
-But recent Ubuntu releases ship:
-
-```sh
-kernel.apparmor_restrict_unprivileged_userns = 1
-```
-
-which blocks the unprivileged **user namespace** that Chromium's sandbox needs.
-Playwright-bundled Chromium does not ship a SUID `chrome_sandbox` helper, so on a
-stock Ubuntu host a sandbox-on launch fails before the DevTools port opens:
-
-```text
-zygote_host_impl_linux.cc: No usable sandbox!
-```
-
-From `chrome-launcher` this usually surfaces as a startup port-poll timeout or
-`ECONNREFUSED`.
-
-The fix is an AppArmor profile that grants `userns,` to the Playwright Chromium
-binary, giving it a stable named label that is allowed to create the user
-namespace. The steps below install Chromium, confirm the resolver finds it,
-attach the profile, and run the suite.
-
-## 1. Install Playwright Chromium
-
-From the repo:
-
-```sh
-npx --yes playwright install chromium
-```
-
-This drops a managed Chromium into the per-user cache:
-
-```text
-~/.cache/ms-playwright/chromium-<rev>/chrome-linux*/chrome
-```
-
-The leaf directory varies by Playwright version and arch — `chrome-linux` on
-ARM64 and older builds, `chrome-linux64` on x86_64 with the newer
-Chrome-for-Testing layout (the resolver and the AppArmor glob below cover both).
-Install it for **each OS user** that will run the suite — the cache is
-per-`$HOME`.
-
-## 2. Verify the resolver finds it
-
-The launcher resolver (`src/util/browser-resolve.ts`) finds Chromium in this
-order: an explicit `CDP_TEST_BROWSER_PATH`, then a system `chromium` on `PATH`,
-then the Playwright cache. After a build, confirm what it picks:
-
-```sh
-npm run build
-node --input-type=module \
-  -e "import('./dist/util/browser-resolve.js').then(m => console.log(JSON.stringify(m.resolveBrowser(), null, 2)))"
-```
-
-This runbook targets the **Playwright-cache** binary, so expect
-`source: "playwright-cache"` and a `binaryPath` under `~/.cache/ms-playwright/`:
-
-```json
-{
-  "binaryPath": "/home/<user>/.cache/ms-playwright/chromium-<rev>/chrome-linux/chrome",
-  "choice": "chromium",
-  "snapConfined": false,
-  "source": "playwright-cache"
-}
-```
-
-If you have a system Chromium on `PATH` (apt `/usr/bin/chromium`, snap
-`/snap/bin/chromium`), the resolver returns that first with
-`source: "which-chromium"` — that binary is *not* covered by the AppArmor
-profile below (snap brings its own confinement; apt Chromium is a separate
-sandbox story). To exercise the Playwright binary under this profile, point the
-suite at it explicitly:
-
-```sh
-export CDP_TEST_BROWSER_PATH="$(ls -d ~/.cache/ms-playwright/chromium-*/chrome-linux*/chrome | head -1)"
-```
-
-## 3. Attach the AppArmor profile
-
-First confirm the kernel knob is the restrictive default:
-
-```sh
-sysctl kernel.apparmor_restrict_unprivileged_userns   # = 1 on stock Ubuntu 24.04
-```
-
-If it is `0` (some hosts turn it off system-wide), Chromium's sandbox already
-works and you can skip to step 5.
-
-Create a profile that grants `userns,` to the Playwright Chromium binary path.
-This mirrors the shape of Ubuntu's stock `chrome` / `msedge` / `brave` profiles
-(a named-unconfined profile that opts into user namespaces):
-
-```apparmor
-# /etc/apparmor.d/cdp-mcp-chromium
-abi <abi/4.0>,
-include <tunables/global>
-
-profile cdp-mcp-chromium /home/*/.cache/ms-playwright/chromium-*/chrome-linux*/chrome flags=(unconfined) {
-  userns,
-
-  include if exists <local/cdp-mcp-chromium>
-}
-```
-
-The `chrome-linux*` component matches both the `chrome-linux` (ARM64/older) and
-`chrome-linux64` (x86_64 Chrome-for-Testing) layouts — in AppArmor `*` matches
-within a single path segment, so a too-specific `chrome-linux` would silently
-fail to attach on x86_64. The `/home/*/` glob matches any user's Playwright
-cache; if you prefer to scope it to specific accounts, replace `*` with a brace
-list of usernames, e.g. `/home/{alice,bob}/.cache/...`.
-
-Load it (profiles in `/etc/apparmor.d/` also auto-load at boot):
-
-```sh
-sudo apparmor_parser -r /etc/apparmor.d/cdp-mcp-chromium
-```
-
-## 4. Verify the label attaches
-
-Launch the bundled Chromium sandbox-on and read its AppArmor label — it must be
-the named profile, not bare `unconfined`:
-
-```sh
-BIN=$(ls -d ~/.cache/ms-playwright/chromium-*/chrome-linux*/chrome | head -1)
-"$BIN" --headless=new --no-startup-window --remote-debugging-port=0 \
-       --user-data-dir=$(mktemp -d) about:blank & pid=$!
-sleep 3; cat /proc/$pid/attr/current   # -> cdp-mcp-chromium (unconfined)
-kill $pid
-```
-
-If this prints `cdp-mcp-chromium (unconfined)`, the profile is attached. A bare
-`unconfined` means the binary path didn't match the profile's glob — re-check
-the cache path against the profile.
-
-## 5. Run L3
-
-```sh
-npm run test:e2e
-```
-
-With the sandbox on and the profile attached, the suite should pass, e.g.:
-
-```text
-Test Files  10 passed (10)
-Tests       29 passed (29)
-```
-
-## Fallback (before AppArmor is configured)
-
-The L3 harness adds `--no-sandbox` when `CI` is set, so you can run the suite
-without the profile as a lower-security stopgap:
-
-```sh
-env CI=1 npm run test:e2e
-```
-
-This keeps work moving, but the AppArmor profile is the desired long-term
-posture so that plain `npm run test:e2e` exercises sandbox-on Chromium. See
-[`chromium-sandboxing.md`](./chromium-sandboxing.md) for why `--no-sandbox`
-widens the blast radius of a compromised renderer.
-
-## Other distributions
-
-This profile work is Ubuntu-specific. Distributions that don't restrict
-unprivileged user namespaces by default (or use SELinux instead of AppArmor,
-e.g. Fedora) generally run sandbox-on Chromium without a host-side profile.
-Validate the actual host before assuming the Ubuntu steps are required — check
-`sysctl kernel.apparmor_restrict_unprivileged_userns` (absent or `0` means no
-AppArmor userns restriction to work around).
-
-## Related
-
-- [`docs/chromium-sandboxing.md`](./chromium-sandboxing.md) — the canonical
-  `--no-sandbox` / `sandbox: true` threat model, the AppArmor / userns / snap /
-  Bubblewrap mechanism map, and the validated-hosts table.
-- [`docs/known-chromium-gaps.md`](./known-chromium-gaps.md) — per-spec
-  Chromium-vs-Chrome gaps and host-OS workarounds.
-- [README §L3](../README.md) — browser selection, `CDP_TEST_BROWSER_PATH`, and
-  the per-platform support matrix.

package/docs/systemd-service.md

@@ -1,233 +0,0 @@
-# Linux: Run as a Persistent Service (systemd)
-
-Register `cdp-mcp` as a systemd user service so it starts automatically on login
-and exposes the MCP SSE endpoint on `127.0.0.1:9719`. If you enable lingering,
-the service can also start at boot before an interactive login.
-
-Persistent service mode is useful for MCP clients that support SSE because the
-`cdp-mcp` process and its browser/CDP session can survive MCP client restarts or
-reconnects. It does **not** persist state across service-process restarts.
-
-> Security note: the local SSE endpoint has no authentication. MCP tools include
-> in-page JavaScript evaluation and filesystem writes via screenshot paths. Only
-> run a persistent service on trusted single-user machines. Be especially careful
-> with `loginctl enable-linger` on shared hosts because it widens the service's
-> exposure window beyond your interactive login session.
-
-## Contents
-
-- [1. Install the server](#1-install-the-server)
-- [2. Optional: enable lingering](#2-optional-enable-lingering)
-- [3. Create the unit file](#3-create-the-unit-file)
-- [4. Enable and start the service](#4-enable-and-start-the-service)
-- [5. Verify](#5-verify)
-- [6. Configure an MCP client](#6-configure-an-mcp-client)
-- [7. Logs](#7-logs)
-- [8. Stop / uninstall](#8-stop--uninstall)
-- [9. Upgrade](#9-upgrade)
-- [Linux ARM64 / Chromium](#linux-arm64--chromium)
-- [Troubleshooting](#troubleshooting)
-
-## 1. Install the server
-
-Requires Node.js 20+ and a local Chrome/Chromium browser.
-
-```bash
-npm install -g cdp-mcp
-```
-
-Verify with `cdp-mcp --help`. The package ships prebuilt `dist/`, so there is no
-build step and no repo checkout needed.
-
-If `launch_chrome` cannot find Chrome/Chromium automatically, set `CHROME_PATH`
-when generating the unit file below.
-
-## 2. Optional: enable lingering
-
-Enable lingering only if you want the user service to start at boot even before
-you log in:
-
-```bash
-sudo loginctl enable-linger "$USER"
-```
-
-You only need to run this once per machine. Check with:
-
-```bash
-loginctl show-user "$USER" --property=Linger
-```
-
-Skip this step if starting the service during your login session is enough.
-
-## 3. Create the unit file
-
-Run this from any directory:
-
-```bash
-# If you use fnm, nvm, or another Node version manager, set these variables to
-# stable paths before running this snippet. Example:
-# NODE_BIN="$HOME/.local/share/fnm/aliases/default/bin/node"
-# CDP_SCRIPT="$HOME/.local/share/fnm/aliases/default/bin/cdp-mcp"
-NODE_BIN="${NODE_BIN:-$(command -v node)}"
-CDP_SCRIPT="${CDP_SCRIPT:-$(command -v cdp-mcp)}"
-CHROME_PATH="${CHROME_PATH:-}"
-
-if [ -z "$NODE_BIN" ]; then
-  echo "Error: node not found in PATH. Install Node 20+ first." >&2
-  exit 1
-fi
-if [ -z "$CDP_SCRIPT" ]; then
-  echo "Error: cdp-mcp not found. Run 'npm install -g cdp-mcp' first." >&2
-  exit 1
-fi
-
-NODE_DIR="$(dirname "$NODE_BIN")"
-mkdir -p ~/.config/systemd/user
-cat > ~/.config/systemd/user/cdp-mcp.service << EOF
-[Unit]
-Description=cdp-mcp browser MCP server (SSE on port 9719)
-After=network.target
-
-[Service]
-Type=simple
-ExecStart="${NODE_BIN}" "${CDP_SCRIPT}" --port 9719
-Restart=on-failure
-RestartSec=5
-Environment="PATH=${NODE_DIR}:/usr/local/bin:/usr/bin:/bin"
-$(if [ -n "$CHROME_PATH" ]; then printf 'Environment="CHROME_PATH=%s"\n' "$CHROME_PATH"; else printf '# Optional: set CHROME_PATH if launch_chrome cannot find Chrome/Chromium.\n# Environment="CHROME_PATH=/path/to/chrome"\n'; fi)
-
-[Install]
-WantedBy=default.target
-EOF
-```
-
-The unit invokes `node` directly with the `cdp-mcp` script path. That makes the
-`NODE_BIN` override authoritative even when your shell uses a Node version
-manager. The `ExecStart` and `Environment` values are double-quoted so systemd
-treats a path containing spaces as a single token rather than splitting it.
-
-## 4. Enable and start the service
-
-```bash
-systemctl --user daemon-reload
-systemctl --user enable --now cdp-mcp.service
-```
-
-## 5. Verify
-
-```bash
-systemctl --user status cdp-mcp.service
-ss -tlnp | grep 9719
-curl -s --max-time 2 http://127.0.0.1:9719/sse | head -1
-```
-
-The `curl` command should print an SSE `event:` line. The stream stays open by
-design. The server also sends periodic SSE keepalive comments by default; tune
-with `CDP_MCP_SSE_KEEPALIVE_MS` only if your MCP client needs a different idle
-interval.
-
-## 6. Configure an MCP client
-
-Point an SSE-capable MCP client at:
-
-```text
-http://127.0.0.1:9719/sse
-```
-
-For example, clients that use JSON MCP server config commonly use:
-
-```json
-{
-  "mcpServers": {
-    "cdp-mcp": {
-      "type": "sse",
-      "url": "http://127.0.0.1:9719/sse"
-    }
-  }
-}
-```
-
-SSE mode is single-client today. Multiple MCP clients connected to the same
-service share one process-global browser/CDP session and can interfere with each
-other. Use one active debugging client per service, or run separate services on
-separate ports.
-
-A reconnecting client resumes the prior session. If you want a clean browser
-session after reconnecting, call `close_session` before launching or attaching
-again.
-
-## 7. Logs
-
-```bash
-journalctl --user -u cdp-mcp.service -f
-journalctl --user -u cdp-mcp.service -n 100
-```
-
-## 8. Stop / uninstall
-
-```bash
-systemctl --user stop cdp-mcp.service
-systemctl --user disable cdp-mcp.service
-rm ~/.config/systemd/user/cdp-mcp.service
-systemctl --user daemon-reload
-```
-
-## 9. Upgrade
-
-```bash
-npm install -g cdp-mcp@latest
-systemctl --user restart cdp-mcp.service
-```
-
-Restart or reconnect your MCP client after a server upgrade so it reloads tool
-schemas.
-
-## Linux ARM64 / Chromium
-
-Google does not publish official Chrome builds for Linux ARM64. If your distro's
-Chromium package is unreliable for DevTools Protocol launches, use a
-Playwright-cached Chromium binary and set `CHROME_PATH` when generating the
-unit:
-
-```bash
-# Install Playwright's Chromium (one-time):
-npx playwright install chromium
-
-# Set CHROME_PATH to the latest revision before running the unit-file script:
-export CHROME_PATH="$HOME/.cache/ms-playwright/chromium-1223/chrome-linux/chrome"
-```
-
-Snap Chromium (`/snap/bin/chromium`) can be unreliable for persistent services
-because snap confinement may interfere with `--remote-debugging-port`, headless
-flags, and process lifecycle management. A Playwright-cached Chromium is often
-more predictable for CDP-based debugging sessions. The generated unit's `PATH`
-does not include `/snap/bin`, so if you do use snap Chromium you must set
-`CHROME_PATH=/snap/bin/chromium` explicitly — `launch_chrome` will not
-auto-detect it under the service environment.
-
-Playwright upgrades may relocate the binary. After running
-`npx playwright install chromium`, check the new revision directory name (for
-example, `chromium-1223` to `chromium-1250`), update `CHROME_PATH` in the unit
-file, and run:
-
-```bash
-systemctl --user daemon-reload
-systemctl --user restart cdp-mcp.service
-```
-
-For Chromium sandbox flags (`--no-sandbox`, AppArmor, snap confinement) and known
-host-OS launch gaps, see [chromium-sandboxing.md](./chromium-sandboxing.md) and
-[known-chromium-gaps.md](./known-chromium-gaps.md).
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Service exits immediately | Check `journalctl --user -u cdp-mcp.service -n 100`; usually `cdp-mcp` is not installed, Node is too old, or a version-manager path moved |
-| Port 9719 is already in use | Compare `systemctl --user show -p MainPID --value cdp-mcp.service` with `ss -tlnp \| grep 9719`, then stop the other process or change the port |
-| MCP client rejects the config | Confirm the client supports SSE MCP servers and include both `"type": "sse"` and the `/sse` URL if your client uses JSON config |
-| `launch_chrome` cannot find Chrome | Set `CHROME_PATH` in the unit file and restart the service; on Linux ARM64, try Playwright-cached Chromium (`~/.cache/ms-playwright/chromium-*/chrome-linux/chrome`) |
-| Service not starting after reboot | Enable lingering with `sudo loginctl enable-linger "$USER"` |
-| Node not found after reboot with fnm/nvm | Version-manager shell paths can be ephemeral. Recreate the unit with stable `NODE_BIN` and `CDP_SCRIPT` paths, or install with a system Node |
-| `Failed to connect to bus` over SSH | Run `export XDG_RUNTIME_DIR=/run/user/$(id -u)` before using `systemctl --user` |
-| `already_session` after reconnecting | The prior browser/CDP session is still alive. Resume it, or call `close_session` before starting fresh |