cdp-mcp 0.1.1 → 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/dist/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { createServer } from "node:http";
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { buildServer } from "./server.js";
@@ -93,6 +95,23 @@ function parsePort(raw) {
     }
     return port;
 }
+const DEFAULT_SSE_KEEPALIVE_MS = 25_000;
+// SSE streams sit idle between tool calls, and HTTP clients enforce a
+// body-idle timeout (e.g. undici inside GitHub Copilot CLI tears the stream
+// down after ~12 min with "Body Timeout Error"). A periodic SSE comment frame
+// (`: ...\n\n`) is a no-op per the spec but resets that idle timer. Tunable via
+// CDP_MCP_SSE_KEEPALIVE_MS (non-negative integer ms; 0 disables). See issue #1.
+function getKeepaliveMs() {
+    const raw = process.env.CDP_MCP_SSE_KEEPALIVE_MS;
+    if (raw === undefined || raw === "")
+        return DEFAULT_SSE_KEEPALIVE_MS;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        log.warn("invalid CDP_MCP_SSE_KEEPALIVE_MS; using default", { value: raw, default: DEFAULT_SSE_KEEPALIVE_MS });
+        return DEFAULT_SSE_KEEPALIVE_MS;
+    }
+    return value;
+}
 async function main() {
     const mode = parseArgs(process.argv.slice(2));
     if (mode.transport === "sse") {
@@ -191,7 +210,7 @@ function installProcessErrorHandlers() {
         log.error("unhandledRejection", { reason: String(reason) });
     });
 }
-async function handleSseRequest({ req, res, clients, host, port, validateHostOrigin, allowedHosts, allowedOrigins, }) {
+export async function handleSseRequest({ req, res, clients, host, port, validateHostOrigin, allowedHosts, allowedOrigins, }) {
     try {
         // DNS-rebinding defense for loopback binds: validate Host (and
         // Origin if present) before the SDK touches the request. The MCP
@@ -262,7 +281,12 @@ function buildAllowedOrigins(bindHost, port) {
 async function startSseConnection({ res, clients, }) {
     const transport = new SSEServerTransport("/messages", res);
     const server = buildServer();
+    // Assigned after connect() (below) so the keepalive never writes before the
+    // SDK has sent the SSE response headers; cleared here on disconnect.
+    let keepalive;
     transport.onclose = () => {
+        if (keepalive)
+            clearInterval(keepalive);
         const client = clients.get(transport.sessionId);
         clients.delete(transport.sessionId);
         void client?.server.close().catch((e) => {
@@ -274,6 +298,23 @@ async function startSseConnection({ res, clients, }) {
     };
     clients.set(transport.sessionId, { server, transport });
     await server.connect(transport);
+    // connect() has now written the SSE headers + endpoint event, so it's safe
+    // to interleave keepalive comment frames on the stream.
+    const keepaliveMs = getKeepaliveMs();
+    if (keepaliveMs > 0) {
+        keepalive = setInterval(() => {
+            if (res.writableEnded)
+                return;
+            try {
+                res.write(": keepalive\n\n");
+            }
+            catch (e) {
+                log.warn("SSE keepalive write failed", { sessionId: transport.sessionId, error: String(e) });
+            }
+        }, keepaliveMs);
+        // Don't let the keepalive timer alone keep the process alive.
+        keepalive.unref();
+    }
     log.info("SSE client connected", { sessionId: transport.sessionId });
 }
 async function handleSseMessage({ req, res, clients, sessionId, }) {
@@ -338,8 +379,24 @@ function respondText(res, statusCode, body) {
     res.writeHead(statusCode, { "Content-Type": "text/plain; charset=utf-8" });
     res.end(body);
 }
-main().catch((err) => {
-    log.error("fatal", { error: String(err), stack: err?.stack });
-    process.exit(1);
-});
+// Only run the server when executed as the CLI entry point — not when this
+// module is imported (e.g. by the SSE transport tests). `realpathSync`
+// resolves the npm bin symlink so the comparison holds for global installs.
+function isRunAsMain() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (isRunAsMain()) {
+    main().catch((err) => {
+        log.error("fatal", { error: String(err), stack: err?.stack });
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -11,7 +11,7 @@ import { registerDomTools } from "./tools/dom.js";
 export function buildServer() {
     const server = new McpServer({
         name: "cdp-mcp",
-        version: "0.1.0",
+        version: "0.1.2",
     });
     registerSessionTools(server);
     registerNavTools(server);
@@ -22,6 +22,16 @@ export function buildServer() {
     registerConsoleTools(server);
     registerNetworkTools(server);
     registerDomTools(server);
+    // The SDK advertises `tools: { listChanged: true }` as soon as any tool is
+    // registered, but never emits the matching notification on its own. Some
+    // clients (e.g. GitHub Copilot CLI over SSE) gate their first `tools/list`
+    // call on receiving a `notifications/tools/list_changed` and otherwise wait
+    // forever — registering zero tools. Emit it once, right after the client's
+    // `initialized` (so the transport is connected and the client is ready).
+    // Harmless for clients that already fetch eagerly. See issue #1.
+    server.server.oninitialized = () => {
+        server.sendToolListChanged();
+    };
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEzB,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5B,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEzB,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,iEAAiE;IACjE,MAAM,CAAC,MAAM,CAAC,aAAa,GAAG,GAAG,EAAE;QACjC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC/B,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

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.1",
+  "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",