{ "markdown": "# Kitewright\n\n**Browser automation for AI agents as a single small binary.** An MCP server (Streamable HTTP + stdio) that gives LLM clients `navigate` / `screenshot` / `extract` — without carrying the Node.js + Playwright stack.\n\n![Kitewright demo — starts in 75 ms, ~8 MB idle, a real MCP endpoint, one-line install](docs/demo.gif)\n\nInstall in one line:\n\n```bash\nclaude mcp add kitewright -- npx -y @kitewright/mcp\n```\n\n## Why — measured, not claimed\n\nHead-to-head vs `@playwright/mcp` 0.0.78, same machine, same Chromium headless-shell build, same page ([full methodology](BENCHMARKS.md)):\n\n| | @playwright/mcp | **Kitewright** |\n|---|---:|---:|\n| Cold start → listening | 354 ms | **75 ms** |\n| Server RSS (idle) | 102–125 MB | **7.6 MB** |\n| Server RSS (after work) | 93 MB | **10.9 MB** |\n| Distribution | 18 MB pkg + Node.js runtime | **6.9 MB static binary** |\n| First navigate (incl. browser launch) | 2623 ms | **822 ms** (session pre-warming) |\n| Warm navigate latency | 80–116 ms | 99–105 ms (tie) |\n| Idle behavior | browser kept alive | **browser reaped after idle TTL**, pre-warmed again on next session |\n\nThe browser itself (Chromium) costs the same in any language — warm latency is a tie because both speak CDP to the same browser. The wins are everything around it: startup, distribution, idle footprint, and lifecycle management. The honest gap: playwright-mcp ships ~25 tools today, we ship 21 — closing that is the roadmap.\n\n## Reliability — actionability auto-waiting\n\n`click` / `type` / `fill_form` / `select_option` / `hover` don't fire blindly. Before acting, the engine polls (100 ms, up to a 5 s per-op budget) until the target element is **present**, **visible** (not `display:none` / `visibility:hidden` / zero-size), **enabled** (no `disabled` / `aria-disabled`), **not covered** by another element at its click point, and **geometrically stable** across two consecutive frames. A settled element passes on the first poll, so this is invisible when things are fine — but when an action can't happen, you get a *cause-specific* error (`not found` / `not visible` / `disabled` / `covered` / `unstable`) instead of a silent misclick or a generic timeout. Transient CDP errors are retried twice. Pass `timeout_ms` on any interaction tool to override the 5 s per-op budget (e.g. a short timeout to fail fast when you expect an element to already be there).\n\n## Performance\n\nExternal-site latency is **network-bound** — DNS + TLS + TTFB (~400–600 ms) is a floor no tool beats, and Kitewright does not claim to. What it *does* attack is every controllable cost around the network:\n\n- **Prewarm + warm-context pool.** The moment an MCP session initializes, the server launches the browser and fills a small pool of pre-created blank browser contexts (`MCP_CONTEXT_POOL`, default 2) in the background. A new session is then handed a ready context+page, so its **first** navigate pays zero browser-launch *and* zero context-creation cost. Measured localhost first-navigate: **~31 ms prewarmed** vs ~709 ms cold (Apple Silicon; [details](BENCHMARKS.md)). The pool drains with the browser on idle-reap and refills lazily on next demand, so idle footprint stays at the ~8 MB baseline.\n- **Lite mode.** `browser_navigate {lite:true}` (and the default for `extract` / `extract_markdown`) blocks images/media/fonts + ad/analytics hosts before the load — 30–70 % faster DOM-ready on heavy pages by skipping the bulk of the bytes. Screenshots/PDF never block resources.\n- **Shared disk cache + connection pre-warm.** A stable `--disk-cache-dir` (`KITE_CACHE_DIR`) lets repeat asset fetches hit cache across runs; `KITE_PREWARM_URL` establishes DNS+TLS to a known origin during prewarm.\n\nThe honest framing: the wins are browser launch, page weight, session start, and connection setup — not the network round-trip to a remote origin.\n\n## Architecture\n\n```\ncrates/\n├── engine/ kitewright-engine — CDP core (chromiumoxide): lazy launch, idle reaper,\n│ per-session browser contexts, capped text extraction + AX snapshots.\n│ Shared by all frontends.\n└── server/ kitewright — rmcp Streamable HTTP server exposing the engine as MCP tools.\nbindings/\n└── node/ @kitewright/node — napi-rs bindings exposing a Puppeteer-compatible\n (experimental) API over the same engine (built separately; kept out\n of the core cargo workspace). See \"@kitewright/node\" below.\n```\n\nEach MCP session owns one persistent page inside its own Chromium browser context (cookie isolation between agents): log in once, keep clicking. The page and context are closed when the session ends; the browser itself is still reaped after the idle TTL and transparently relaunched on the next call.\n\n## Install\n\nThe zero-install way — run it straight from **npx**, like `@playwright/mcp`:\n\n```bash\nclaude mcp add kitewright -- npx -y @kitewright/mcp\n```\n\n`npx @kitewright/mcp` resolves the prebuilt `kite` binary for your platform (an\noptional per-platform dependency, esbuild-style) and starts a stdio MCP server —\nno Rust toolchain, no build. See [`npm/kitewright-mcp`](npm/kitewright-mcp).\n\nPrefer the raw `kite` binary? (npx above is the easy path; these need a Rust toolchain.)\n\n```bash\n# From the public repo — builds + installs the `kite` binary:\ncargo install --git https://github.com/kitewright/kitewright kitewright # → ~/.cargo/bin/kite\n\n# From a local checkout:\ncargo install --path crates/server\n\n# Docker (headless Chromium bundled in the image):\ndocker run --rm -p 8090:8090 kitewright # build locally: docker build -t kitewright .\n```\n\n> Not yet published to crates.io or Homebrew — `cargo binstall`/`brew` aren't wired up. Use `npx @kitewright/mcp` (no toolchain) or the `cargo install --git` line above.\n\n### Get a browser\n\nKitewright drives Chromium over CDP but does not embed one. It uses a system\nChrome/Chromium when present, honors `BROWSER_EXECUTABLE`, and — if neither is\nfound — falls back to a browser downloaded by `kite install`:\n\n```bash\nkite install # fetch the latest stable chrome-headless-shell into the kite cache\n```\n\n`kite install` downloads the current Chrome-for-Testing `chrome-headless-shell`\nbuild for your platform into `$KITE_CACHE_DIR` (or the OS cache dir) and the\nengine picks it up automatically — no `BROWSER_EXECUTABLE` needed. Re-running is\na no-op once a build is present. The Docker image already ships Chromium.\n\n## Run & connect\n\n`kite` with no arguments serves MCP over **Streamable HTTP** (networked, default,\nsupports auth + many sessions); `kite --stdio` serves a single session over\n**stdio** for local clients.\n\n```bash\nkite\n# → kitewright listening on http://0.0.0.0:8090/mcp\n```\n\n**HTTP transport** — connect from Claude Code:\n\n```bash\nclaude mcp add kite --transport http http://localhost:8090/mcp\n```\n\n**stdio transport** — MCP client config (Claude Desktop, Cursor, …):\n\n```json\n{\n \"mcpServers\": {\n \"kite\": {\n \"command\": \"kite\",\n \"args\": [\"--stdio\"]\n }\n }\n}\n```\n\n## Configuration\n\n| Env var | Default | Meaning |\n|---|---|---|\n| `MCP_HTTP_BIND` | `0.0.0.0:8090` | Listen address |\n| `MCP_AUTH_TOKEN` | unset | When set, `/mcp` requires `Authorization: Bearer ` (401 otherwise). Unset = open access + startup warning |\n| `MCP_RATE_LIMIT_PER_MINUTE` | `300` | Per-client-IP request limit (fixed 60s window); 429 when exceeded |\n| `BROWSER_EXECUTABLE` | auto-detect | Path to chrome / chromium / chrome-headless-shell. When unset: a system Chrome/Chromium is detected, else a `kite install`-managed build in the cache dir |\n| `BROWSER_NO_SANDBOX` | unset | Set (any value) to pass `--no-sandbox` (containers) |\n| `KITE_HEADLESS` | unset | Kite launches a **headed** (visible) browser by default so you can watch automation. Set (any value) to run **headless** — required on servers, CI, and containers with no display, where a headed Chrome fails to launch |\n| `KITE_IDLE_TIMEOUT_SECS` | `1800` | Idle seconds before a headless browser is reaped to free memory. Default 30min keeps a session alive across normal pauses (headed never reaps). A reap that does happen is recovered by cookie **auto-restore**, so an authenticated session survives it. Lower it on a memory-constrained multi-session server |\n| `KITE_ALLOW_SECRET_FILES` | unset | Set (any value) to let `browser_fill_secret` read `file:/path` secrets from disk. **Requires** `KITE_SECRET_DIR` (the directory reads are fenced to) so arbitrary host files can't be read/exfiltrated. `env:` secrets need no opt-in |\n| `KITE_VIEWPORT` | `1440x900` | Default viewport / window size as `WIDTHxHEIGHT` (Chromium's own default is a cramped 800x600). Adjust at runtime with the `browser_resize` tool |\n| `MCP_CONTEXT_POOL` | `2` | Number of pre-warmed blank browser contexts kept ready so a **new** session gets an instantly-usable context+page (zero context-creation latency). `0` disables. The pool refills in the background and drains with the browser on idle-reap (it never keeps the process alive) |\n| `KITE_CACHE_DIR` | `/kitewright-cache` | Shared on-disk HTTP cache (`--disk-cache-dir`), stable across launches so repeat asset fetches hit cache. NOTE: per-session isolated contexts (cookie isolation) use an ephemeral cache; this benefits the browser's default context |\n| `KITE_PREWARM_URL` | unset | If set, prewarm navigates a throwaway page to this origin to establish DNS+TLS+connection before the first real navigate. No-op when unset |\n| `BROWSER_PREWARM` | unset | Set (any value) to launch + pre-warm the browser at server boot (otherwise prewarm fires when an MCP session initializes) |\n| `RUST_LOG` | `info` | Log filter |\n\n## Security\n\nKitewright drives a real browser, so treat the endpoint as privileged. The\ndefaults are safe for local use; harden before exposing it.\n\n- **Binds loopback (`127.0.0.1:8090`) by default.** It's only network-reachable\n if you set `MCP_HTTP_BIND` explicitly. **If you expose it, set `MCP_AUTH_TOKEN`**\n — without it the `/mcp` endpoint is unauthenticated (logged as a warning at\n boot). Auth uses a constant-time compare; requests are rate-limited; and\n cross-origin browser requests are rejected (DNS-rebinding protection).\n- **SSRF is inherent to a browser tool.** A caller can navigate to internal or\n cloud-metadata addresses (`169.254.169.254`, RFC-1918, `localhost`) — which is\n *the point* for local/dev automation, but a risk on an exposed instance.\n Kitewright does not block these (doing so by default would break local\n automation). On an exposed deployment, put it behind auth and network policy\n that can't reach sensitive internal endpoints.\n- **Local-file access is off by default.** `file://` navigation requires\n `KITE_ALLOW_FILE_URLS=1`; `browser_fill_secret` file reads require\n `KITE_ALLOW_SECRET_FILES=1` **and** a `KITE_SECRET_DIR` fence (reads are\n canonicalized and must stay under it).\n- **Dependencies** are scanned in CI (Trivy + `cargo audit`). The shipped `kite`\n binary carries no known-vulnerable crates; see [`.cargo/audit.toml`](.cargo/audit.toml)\n for two DoS advisories confined to the (server-unused) `kite-pdf` crate.\n\n## Tools (v0.4)\n\nAll tools operate on the session's persistent page.\n\n**Read**\n\n- `browser_navigate {url, lite?}` — title, final URL, visible text (capped). `lite:true` enables **lite mode**: block images/media/fonts + common ad/analytics hosts (doubleclick, google-analytics, GTM, facebook pixel, …) via CDP `Network.setBlockedURLs` for a faster DOM-ready on heavy pages (30–70 % on heavy sites — text-only, do **not** use before a screenshot). Sticky for the session until changed. `extract` / `extract_markdown` default to lite when navigating (pixels irrelevant); `screenshot` / `pdf` never block resources\n- `browser_extract {url?, selector, attribute?}` — text/attribute from elements matching a selector\n- `browser_extract_markdown {url?}` — main content as Markdown (\"readability\" mode: headings/links/lists/code/tables, nav/script/style stripped, capped at ~20k chars)\n- `browser_screenshot {url?, full_page?}` — PNG of the current page (`url` navigates first)\n- `browser_pdf {url?, format?, landscape?, print_background?, display_header_footer?, header_template?, footer_template?, margin_top?, margin_bottom?, margin_left?, margin_right?, scale?, prefer_css_page_size?}` — print to PDF (CDP `Page.printToPDF`); the full puppeteer option set including running headers/footers (legal text, page numbers) and CSS-unit margins (`\"35px\"`/`\"20mm\"`). Returns a JSON envelope `{format, bytes, base64}` (MCP has no native PDF type — decode `base64` to get the file)\n- `browser_set_content {html, wait_until?}` — load a raw HTML string into the current page (puppeteer `page.setContent`) via CDP `Page.setDocumentContent`; `wait_until` is `load` (default) / `domcontentloaded` / `networkidle0`. Pair with `browser_pdf` for an HTML→PDF render with no server round-trip. Handles large documents\n- `browser_snapshot {diff?}` — accessibility-tree snapshot (roles, names, states) capped at ~15k chars; `diff:true` returns only what changed since the previous snapshot in this session (first call is the baseline)\n\n**Debug**\n\n- `browser_console {clear?}` — console messages (log/warn/error/info) captured on the page since the last call; `clear:true` empties the buffer\n- `browser_network {clear?, filter?}` — network requests (method, url, status, resourceType) captured on the page; `filter` substring-matches the URL\n\n**Interact**\n\n- `browser_click {selector, timeout_ms?}` — scroll into view + click the first match\n- `browser_type {selector, text, clear?, press_enter?, timeout_ms?}` — focus and type into an element\n- `browser_fill_form {fields: [{selector, value}], timeout_ms?}` — fill several inputs in one call (per-field ok/error summary)\n- `browser_fill_secret {selector, secret_ref, press_enter?, timeout_ms?}` — type a secret (password) whose plaintext **never enters the tool call**: `secret_ref` is `env:NAME` (a server env var) or `file:/path` (opt-in via `KITE_ALLOW_SECRET_FILES` + a required `KITE_SECRET_DIR` fence). Resolved server-side, then typed\n- `browser_select_option {selector, value?, label?, timeout_ms?}` — pick an `