cdp-mcp 0.1.2 → 0.1.3

package/README.md

@@ -4,7 +4,7 @@ A Model Context Protocol (MCP) server that exposes the Chrome DevTools Protocol
 
 Designed for agents running in CLIs (Claude Code, GitHub Copilot CLI) that have local source + source-map access. Coordinates flow in TS terms; the server translates to JS for CDP under the hood.
 
-**Status:** alpha (v0.1.0). **License:** [MIT](./LICENSE).
+**Status:** alpha. **License:** [MIT](./LICENSE).
 
 ## What it gives an agent
 
@@ -22,6 +22,34 @@ Auto-attaches to iframes and workers via `Target.setAutoAttach({ flatten: true }
 
 ## Install / build
 
+### Runtime install from npm
+
+Requires Node.js 20+ and a local Chrome/Chromium browser.
+
+```sh
+npm install -g cdp-mcp
+cdp-mcp                           # stdio MCP transport
+cdp-mcp --port 9719               # SSE MCP transport on 127.0.0.1:9719
+cdp-mcp --host 0.0.0.0 --port 9719 --allow-remote
+```
+
+The npm package ships prebuilt `dist/`, so there is no build step for runtime
+use. If `launch_chrome` cannot find Chrome/Chromium automatically, set
+`CHROME_PATH` to the browser binary.
+
+For MCP clients that support SSE, you can run `cdp-mcp` as a persistent local
+service:
+
+- [macOS launchd user service](docs/launchd-service.md)
+- [Linux systemd user service](docs/systemd-service.md)
+
+Persistent service mode keeps the `cdp-mcp` process and current browser/CDP
+session alive across MCP client restarts or reconnects. It does **not** persist
+state across service-process restarts. SSE mode is single-client today; if a
+new client should start fresh, call `close_session` first.
+
+### Build from source
+
 ```sh
 npm install
 npm run build
@@ -62,11 +90,10 @@ Unit + L2 contract tests (~640ms, no browser, no LLM):
 npm test
 ```
 
-Currently 299 tests across 22 files. The `test/` tree is the L2 contract
-layer (every tool exercised against a fake CDP — see `test/fake-cdp.ts`);
-the inline `src/**/*.test.ts` files are L1 pure-data tests; `evals/**/
-*.test.ts` cover the L4 harness's grader/trace/oracle units (21 tests).
-See `docs/test-eval-plan.md` for the full pyramid.
+The `test/` tree is the L2 contract layer (every tool exercised against a fake
+CDP — see `test/fake-cdp.ts`); the inline `src/**/*.test.ts` files are L1
+pure-data tests; `evals/**/*.test.ts` cover the L4 harness's
+grader/trace/oracle units. See `docs/test-eval-plan.md` for the full pyramid.
 
 ### L3 — real-browser end-to-end
 

package/docs/chromium-sandboxing.md

@@ -0,0 +1,191 @@
+# Chromium sandboxing
+
+**Last updated: 2026-05-16**
+
+This project launches Chromium in two different contexts:
+
+- L3 e2e tests and L4 evals launch a real browser through `launch_chrome`.
+- Agents then control that browser through CDP, including `Runtime.evaluate`,
+  `Debugger.*`, DOM interaction, console inspection, and network inspection.
+
+That makes sandboxing a host setup and threat-model decision, not just a
+Chrome flag. This document is the canonical reference for `--no-sandbox`,
+AppArmor, unprivileged user namespaces, snap confinement, and Bubblewrap.
+
+## Current default
+
+`launch_chrome` defaults to `sandbox: false`, which adds `--no-sandbox`.
+
+The default exists because Ubuntu 23.10+ and 24.04 commonly restrict
+unprivileged user namespaces through AppArmor. Playwright-bundled Chromium
+does not ship with a SUID `chrome_sandbox` helper. On those hosts, launching
+Chromium without `--no-sandbox` can fail before the DevTools port opens:
+
+```text
+zygote_host_impl_linux.cc: No usable sandbox!
+```
+
+From `chrome-launcher`, that often surfaces as a startup port poll timeout or
+`ECONNREFUSED`.
+
+Other Linux distributions may allow Chromium's unprivileged user namespace
+sandbox path by default. Validate the actual host before assuming the Ubuntu
+automation default is necessary there.
+
+Use `sandbox: true` only when the host has a working Chromium sandbox path:
+
+- An AppArmor policy that permits the specific Chromium binary to create the
+  unprivileged user namespace it needs.
+- Or a working SUID `chrome_sandbox` helper installed alongside that binary.
+
+## Why the Chromium sandbox still matters
+
+The MCP caller is already highly privileged relative to the page. It can ask
+the server to evaluate JavaScript, drive the DOM, set breakpoints, inspect
+scopes, and read browser-observed network activity. For that caller, the
+Chromium renderer sandbox is not the primary trust boundary.
+
+The Chromium sandbox still matters for hostile page content and browser
+exploitation risk. With the sandbox enabled, Chromium isolates renderer, GPU,
+and utility child processes from the browser process using mechanisms such as
+namespaces, seccomp filters, brokered filesystem access, and per-process
+capability reduction. With `--no-sandbox`, a compromised renderer has a much
+larger blast radius inside the browser process tree.
+
+So the project default is a pragmatic automation default, not a claim that
+`--no-sandbox` is equally safe.
+
+## How the mechanisms relate
+
+These mechanisms solve different problems:
+
+- Chromium sandbox: Chromium's internal process sandbox. It is the boundary
+  between web content renderer processes and the rest of the browser.
+- AppArmor: host-enforced mandatory access control. It can confine Chromium,
+  and on recent Ubuntu systems it can also restrict whether an unprivileged
+  process may create user namespaces.
+- Snap confinement: the packaging sandbox used by snap-installed Chromium.
+  It can hide or remap filesystem locations and has caused DevTools port and
+  `userDataDir` friction in local runs.
+- Bubblewrap (`bwrap`): a small Linux sandboxing tool that starts a process in
+  new namespaces with a controlled filesystem, process, and optional network
+  view.
+
+Bubblewrap is useful defense-in-depth around a browser or eval job. For
+example, it can run the whole MCP server plus browser process tree with only
+the repository and selected temp/profile directories writable. That helps
+prevent accidental or malicious access to unrelated files such as SSH keys,
+cloud credentials, or the rest of the home directory.
+
+Bubblewrap is not a clean substitute for Chromium's own sandbox. If Chromium
+runs with `--no-sandbox` inside Bubblewrap, the entire browser process tree is
+inside an outer container-like boundary, but Chromium's internal renderer
+isolation is still disabled. A renderer compromise may be contained by the
+outer Bubblewrap filesystem or network policy, but it is not contained in the
+same way as Chromium's per-renderer sandbox.
+
+## Recommended posture
+
+Local development:
+
+- Treat the current default, `sandbox: false`, as a host-capability fallback:
+  it keeps work moving when Chromium sandbox setup is the blocker.
+- Prefer `sandbox: true` once the host has a known-good Chromium sandbox path.
+
+CI and L4 eval hosts:
+
+- Keep the default working and deterministic. If `--no-sandbox` is needed for
+  Playwright-bundled Chromium on Ubuntu, document that in the host setup.
+- Consider running the whole job inside an outer sandbox, VM, container, or
+  Bubblewrap profile with a throwaway browser profile and limited writable
+  paths.
+
+Untrusted browsing:
+
+- Prefer Chromium's sandbox on.
+- Use a throwaway `userDataDir`.
+- Add host-level confinement such as AppArmor, a container, VM, or Bubblewrap.
+- Do not treat `bwrap + --no-sandbox` as equivalent to Chromium sandboxing.
+
+## Validated hosts
+
+Hosts where `sandbox: true` has been verified working against this project, with the supporting posture:
+
+| Host | OS | Arch | `sandbox: true` | AppArmor profile | Notes |
+|---|---|---|---|---|---|
+| Ubuntu 24.04 arm64 (Parallels VM) | Ubuntu 24.04 | arm64 | ✓ | `/etc/apparmor.d/cdp-mcp-chromium` (named-unconfined, mirrors Ubuntu's stock `chrome` / `msedge` / `brave`) | `kernel.apparmor_restrict_unprivileged_userns = 0` was set as a side effect of enabling Bubblewrap, so the kernel-level userns restriction is already off system-wide. The AppArmor profile gives Playwright Chromium a stable named label (instead of `unconfined`) and grants `userns,` explicitly, so `sandbox: true` keeps working even if a future kernel/package update flips the global knob back to `1`. |
+
+When adding a new host to this table:
+
+1. Run the smoke tests below and capture the values.
+2. If `kernel.apparmor_restrict_unprivileged_userns` is `1` (Ubuntu's stock default) and `sandbox: true` is desired, install a profile under `/etc/apparmor.d/` mirroring Ubuntu's stock `chrome` / `msedge` / `brave` shape:
+   ```apparmor
+   abi <abi/4.0>,
+   include <tunables/global>
+
+   profile cdp-mcp-chromium /path/to/chromium flags=(unconfined) {
+     userns,
+     include if exists <local/cdp-mcp-chromium>
+   }
+   ```
+   Load with `sudo apparmor_parser -r /etc/apparmor.d/cdp-mcp-chromium`. The profile auto-loads at boot from `/etc/apparmor.d/`.
+3. Verify the running browser process is labelled correctly:
+   ```sh
+   cat /proc/<chromium-pid>/attr/current
+   ```
+   Expect the profile name (e.g. `cdp-mcp-chromium (unconfined)`), not `unconfined` alone.
+4. Add a row to the table above.
+
+Other hosts to characterize as they come online: Fedora — Fedora uses SELinux rather than AppArmor and ships userns enabled by default, so `sandbox: true` is expected to work without host-side profile work. The `dnf install bubblewrap` path is also first-class on Fedora.
+
+## Smoke tests
+
+Check whether unprivileged user namespaces are enabled:
+
+```sh
+cat /proc/sys/kernel/unprivileged_userns_clone
+cat /proc/sys/user/max_user_namespaces
+```
+
+Expected working values are usually `1` for
+`kernel.unprivileged_userns_clone` and a nonzero number for
+`user.max_user_namespaces`.
+
+On Ubuntu, AppArmor may still restrict unprivileged user namespaces:
+
+```sh
+sysctl kernel.apparmor_restrict_unprivileged_userns
+```
+
+Minimal Bubblewrap smoke tests:
+
+```sh
+bwrap --unshare-user --uid 0 --gid 0 --ro-bind / / /usr/bin/true
+bwrap --unshare-user --uid 0 --gid 0 --unshare-net --ro-bind / / /usr/bin/true
+```
+
+If the first command fails with `setting up uid map: Permission denied`, the
+host still blocks the user namespace setup Bubblewrap needs.
+
+If the second command fails with `loopback: Failed RTM_NEWADDR: Operation not
+permitted`, the network namespace setup is still blocked.
+
+Project-level browser check:
+
+```sh
+npm run test:e2e
+```
+
+For a direct MCP check, call `launch_chrome` with `sandbox: true` on the host
+you want to validate. If Chromium cannot create a usable sandbox, it will fail
+before exposing its DevTools target.
+
+## Decision summary
+
+- `--no-sandbox` remains the automation default because it keeps Ubuntu
+  Playwright-Chromium runs working.
+- `sandbox: true` is the preferred security posture when the host supports it.
+- AppArmor is the long-term host policy path for allowing Chromium's needed
+  user namespace behavior narrowly.
+- Bubblewrap is an outer containment layer and is valuable defense-in-depth.
+- Bubblewrap does not replace Chromium's internal renderer sandbox.

package/docs/known-chromium-gaps.md

@@ -0,0 +1,138 @@
+# Known Chromium gaps
+
+Specs in the L3 e2e suite that fail (or fail intermittently) on Chromium but
+pass on Chrome stable. Every entry below is a real coverage gap on Linux
+ARM64 + Chromium (the day-1 primary target) — not a CI-only concession.
+
+If the gap is mitigatable in production code, link the fix PR. If it's a CDP
+protocol-version difference, link the Chromium release that includes the fix.
+
+| Spec | Skip tag | CDP method missing/changed | Chromium version that fixes it | Tracking |
+|---|---|---|---|---|
+| _none yet — populate as L3 lands_ | | | | |
+
+## Pre-flagged risks (not yet observed; documented for triage)
+
+These are known protocol-version-sensitive areas the test+eval plan flagged
+as risky during planning. Add a row above when one of them actually fires
+on the e2e suite.
+
+- **`Network.loadNetworkResource`** — Used by `src/sourcemap/loader.ts:113`
+  to fetch source maps through the browser's network stack (so cookies/
+  origin/auth flow naturally). Older Chromium revisions ship a more limited
+  param set (no `options.includeCredentials`, no `options.disableCache`);
+  the production code already has a Node-fetch fallback, but verify the
+  fallback path is exercised under the older Chromium.
+
+- **`Page.captureScreenshot`** flag set — `captureBeyondViewport` and
+  `quality` (when `format=jpeg`) gained options across versions. The
+  screenshot e2e spec asserts byte-shape, not flag-respect, so this is
+  most likely to surface as a "bytes don't match" assertion under older
+  Chromium.
+
+## Conventions
+
+- Add a `// @chromium-skip — <gap-id>` comment on the spec's `it()` line.
+- Set the spec to `it.skipIf(process.env.CDP_TEST_BROWSER === "chromium")` or
+  use vitest's `.skip` with a runtime check.
+- Every skip MUST have a corresponding row in the table above. **Enforced** by
+  `scripts/check-chromium-skips.mjs` — runs as `pretest:e2e` on every PR and
+  also as `npm run lint:chromium-skips`. Greps `test/e2e/**/*.test.ts` for
+  `@chromium-skip` tags and `it.skipIf`/`describe.skipIf` Chromium guards,
+  parses the table above, exits 1 if any skip lacks a row OR any row points
+  at a spec that no longer exists. Zero-skip state (the current state) is
+  fine — the script is a no-op.
+
+_(no entries below this line yet means no L3 specs needed a Chromium skip)_
+
+## Known host gaps (not Chromium-version issues)
+
+These are host/library combinations where the e2e suite cannot run end-to-
+end, separate from the per-Chromium-version skip mechanism above. Listed
+here so future contributors don't waste a debug cycle.
+
+- **Windows 11 + chrome-launcher 1.2.1.** `chrome-launcher.launch()`'s
+  internal startup-port poll always fails with `ECONNREFUSED` on this Win11
+  configuration, regardless of headless mode (`--headless=new`, classic
+  `--headless`, or non-headless), browser (Chrome stable from Program
+  Files, Playwright-bundled Chromium under `~/AppData/Local/ms-playwright/
+  chromium-XXXX/chrome-win64/chrome.exe`), or how the port is selected
+  (chrome-launcher-managed vs explicit). Spawning `chrome.exe` directly via
+  `Start-Process` and probing `/json/version` over HTTP works fine — only
+  chrome-launcher's launch path fails. The same code works on Linux (CI)
+  and is widely used elsewhere, so this is a Windows-host quirk rather
+  than a cdp-mcp issue. **Workaround**: run L3 changes under WSL2
+  (Ubuntu) or push and let CI validate (but see WSL2 caveat below). Unit
+  + L2 tests work fine on native Windows.
+
+  *Originally hit on agents/l3-impl during PR #11 implementation.
+  Cross-confirmed by Codex reviewer who diagnosed the on-CI failure
+  separately — turned out to be a different root cause (Codex blocker on
+  --remote-debugging-port=0 in chromeFlags overriding chrome-launcher's
+  own port). After that fix, CI on Linux is the live validation; Win11
+  local-host status remains as documented here.*
+
+- **macOS arm64 + system unbranded Chromium (brew cask).** The `chromium`
+  Homebrew cask is **deprecated** ("does not pass the macOS Gatekeeper
+  check; will be disabled 2026-09-01"). Install completes and the wrapper
+  script lands at `/opt/homebrew/bin/chromium`, but on first launch
+  Gatekeeper rejects the `.app` as "damaged" and the binary is unusable
+  for unattended e2e/eval runs. Workaround for darwin-arm64: use Playwright
+  Chrome-for-Testing (`npx playwright install chromium`) — `resolveBrowser`
+  picks it up automatically from `~/Library/Caches/ms-playwright/chromium-
+  <rev>/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/
+  Google Chrome for Testing` (CfT layout added to `pickPlaywrightExe` in
+  the same PR that landed this entry). The resolver also explicitly skips
+  the brew-cask wrapper on darwin (`isBrewCaskChromium`) so users who
+  tried the deprecated cask first — and then turn to Playwright per this
+  entry — fall through to the Playwright cache instead of getting the
+  Gatekeeper-rejected wrapper back from Step 2. Functionally Chromium-
+  channel at a fixed protocol revision, but Google-branded — call it out
+  if your eval needs *unbranded* Chromium. Building Chromium from source
+  on macOS is multi-hour + multi-GB ongoing maintenance; not a viable
+  automation path.
+
+  *Originally hit while validating set_breakpoint idempotency on a
+  macOS arm64 host.*
+
+- **WSL2 (Ubuntu) + snap-installed chromium.** Default-template Ubuntu on
+  WSL2 ships chromium as a snap (`/snap/bin/chromium`), which runs in a
+  confined namespace. chrome-launcher launches the binary successfully
+  (visible window appears under WSLg) but its startup-port poll
+  `ECONNREFUSEs` on iter 1 and often iter 2 — the debug port either
+  binds to a different port than chrome-launcher polled (race) or is
+  invisible across the snap sandbox boundary. After 2-4 retries the
+  agent's tool-use loop eventually picks an instance that responds, so
+  the eval does run, but every trial pays an inflated cost in retry
+  iterations and the trace is contaminated with WARN entries that look
+  like real failures. Same chrome-launcher code path is clean on macOS,
+  Linux native, and Linux CI.
+
+  **Workaround options**: (a) **prefer macOS or Linux native** for
+  interactive eval iteration — a macOS arm64 host confirmed clean;
+  (b) install non-snap chromium in WSL2 via apt or
+  symlink Playwright's bundled chromium to `/usr/local/bin/chromium-browser`
+  before the snap path; (c) accept the noise and rely on CI for the
+  authoritative signal. Don't rely on WSL2 for eval validation runs.
+
+  *A re-run on the same commit (`f0ce92a`) on a native host showed 0
+  chrome-launcher errors, isolating the cause to the WSL2 + snap-chromium
+  combination rather than the harness.*
+
+- **Ubuntu 23.10+ (incl. 24.04) + Playwright-bundled Chromium.** Recent
+  Ubuntu kernels restrict unprivileged user namespaces via AppArmor, and
+  Playwright-bundled Chromium ships without a SUID `chrome_sandbox`
+  helper. Without `--no-sandbox`, Chromium FATALs at startup
+  (`zygote_host_impl_linux.cc: No usable sandbox!`) before opening its
+  debug port — chrome-launcher's port-poll loop then times out with
+  ECONNREFUSED, looking exactly like the WSL2/snap gap above but with a
+  different root cause. **Mitigation:** `launchChrome` defaults
+  `sandbox: false` so `--no-sandbox` is added automatically; eval
+  pipelines on this host work out-of-the-box. For the full security model,
+  including `sandbox: true`, AppArmor, snap confinement, and Bubblewrap, see
+  [docs/chromium-sandboxing.md](./chromium-sandboxing.md).
+
+  *First observed on an Ubuntu 24.04 arm64 host (Parallels VM) while
+  validating the L4 eval suite. Quick eval went from FAIL/$0.34/445s
+  (chrome-launcher retry storm) to PASS/$0.31/107s once `--no-sandbox`
+  was the default.*

package/docs/launchd-service.md

@@ -0,0 +1,217 @@
+# 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/systemd-service.md

@@ -0,0 +1,233 @@
+# 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Chrome DevTools Protocol MCP server — a TypeScript-aware frontend debugger for AI agents.",
   "license": "MIT",
   "author": "Leonard Janke",
@@ -29,7 +29,11 @@
   },
   "main": "dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    "docs/launchd-service.md",
+    "docs/systemd-service.md",
+    "docs/chromium-sandboxing.md",
+    "docs/known-chromium-gaps.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",