kitesurf-bridge

Treibe Cloudflare Kitesurf an — den agent-first Browser, der in V8-Isolaten auf Cloudflare Workers läuft — von überall. Null Abhängigkeiten, kein lokales Chrome.

Vier Wege, eine Engine zu nutzen:

Die Installationsbefehle unten verwenden die GitHub-Spezifikation, die heute ohne Registry-Konto funktioniert. Sobald als @truenix/kitesurf-bridge auf npm veröffentlicht, wird jedes github:TrueNix/kitesurf-bridge zu @truenix/kitesurf-bridge verkürzt.

npx -y github:TrueNix/kitesurf-bridge markdown https://news.ycombinator.com

Das rendert eine echte Seite in einer echten Browser-Engine, im Netzwerk von Cloudflare, ohne lokal installierten Browser und ohne API-Token.

Warum es das gibt

Kitesurf ist nicht Open Source und kann nicht auf deinem Rechner laufen. Cloudflare sagt, sie beabsichtigen, es "sobald wir bereit sind" als Open Source zu veröffentlichen, und selbst dann ist das erklärte Ziel, dass Kunden "ihre eigene Version von Kitesurf auf ihren eigenen Konten bereitstellen" — weiterhin auf Workers.

Es gibt auch kein lokales Kitesurf im Entwicklungszyklus: wrangler dev startet dein lokales Chrome, nicht Kitesurf. Kitesurf existiert nur hinter browser=kitesurf auf entfernten Endpunkten.

Die praktische Frage ist also nicht "kann ich es lokal ausführen", sondern "kann ich es von lokalem Code aus steuern". Dieses Paket ist diese Brücke.

Installation

Als MCP-Server

claude mcp add kitesurf -- npx -y github:TrueNix/kitesurf-bridge mcp

{
  "mcpServers": {
    "kitesurf": {
      "command": "npx",
      "args": ["-y", "github:TrueNix/kitesurf-bridge", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "kitesurf": {
      "command": "npx",
      "args": ["-y", "github:TrueNix/kitesurf-bridge", "mcp"],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "CLOUDFLARE_API_TOKEN": "your-browser-run-token"
      }
    }
  }
}

Bereitgestellte Tools: kitesurf_markdown, kitesurf_text, kitesurf_html, kitesurf_links, kitesurf_screenshot, kitesurf_evaluate, kitesurf_accessibility_tree, kitesurf_probe.

Als DSH / Cordis-Plugin

# in an agent preset composition
- '@truenix/kitesurf-bridge/cordis':
    cli: npx -y github:TrueNix/kitesurf-bridge
    timeoutMs: 120000

Das Plugin registriert dieselben Tools auf dem Host. Es ruft bewusst die CLI auf: Eine dynamische Cordis-Host-Hälfte hat keinen Zugriff auf WebSocket, fetch oder node:*, daher kann CDP nicht innerhalb der Sandbox geöffnet werden. Siehe cordis/plugin.mjs.

Als Bibliothek

npm install github:TrueNix/kitesurf-bridge

import { withSession } from '@truenix/kitesurf-bridge';

const md = await withSession({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

CLI

kitesurf-bridge <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JS runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Endpoint + engine capability report
  mcp                Run as an MCP server on stdio

Nützliche Optionen: --main, --raw, --full, --width, --height, --json, --endpoint, --account, --token, --timeout.

Endpunkte

Setze CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN (oder CF_*), um zu wechseln. Die Angabe einer Kontonummer ohne Token ist ein harter Fehler und kein stilles Downgrade auf den gemeinsamen Playground.

[!WARNUNG] Der Playground ist eine kostenlose, gemeinsame, nicht authentifizierte Ressource ohne SLA. Für Evaluierung und lokale Agentenarbeit in Ordnung — baue keine Produktion darauf auf.

Wissenswertes über Kitesurf

Diese Punkte sind gegen den Live-Dienst verifiziert, nicht aus Dokumentationen kopiert. kitesurf-bridge probe reproduziert sie.

Kitesurf führt für Seiten-Skripte nicht V8 aus — es läuft Boa, eine Rust-JS-Engine. Boa erzwingt ein viel niedrigeres Rekursionslimit und wirft RuntimeLimit: exceeded maximum number of recursive calls. Ein natürlicher rekursiver DOM-Durchlauf stirbt auf jeder großen Seite (Wikipedia, Doku-Seiten). Der Markdown-Konverter dieses Pakets durchläuft das DOM daher mit einem expliziten Stack und hält die JS-Aufruftiefe bei O(1). Wenn du kitesurf_evaluate verwendest, bevorzuge iterative Ausdrücke.

Navigationsfehler erscheinen als Cloudflare-Edge-Statuscodes, nicht als CDP-Fehler. Page.navigate gibt selbst für einen nicht existierenden Host eine normale frameId/loaderId zurück, und kein Network.loadingFailed wird ausgelöst. Eine fehlende Domain erscheint als HTTP 530, eine defekte Origin als 520, wobei ein ~16 Zeichen langes Platzhalterdokument zurückbleibt. Wenn man Page.navigate vertraut, bekommt ein Agent eine leere Seite und nennt das Erfolg — daher klassifiziert dieses Paket Ergebnisse aus der Network-Domain und wirft einen Fehler, wenn ein >=400-Status mit einem leeren Dokument einhergeht, während echte Fehlerseiten (mit status) mit lesbarem Inhalt weiterhin zurückgegeben werden.

Fähigkeits-Flags (verifiziert):

Verwende dafür stattdessen den Standard-Chromium-Browser von Browser Run.

Leistungsabwägung (Cloudflares eigene Zahlen): Kitesurf verbraucht 3–7× weniger CPU und Speicher als warmes Chromium, ist aber 1,7–1,8× langsamer in der Wanduhrzeit. Dieser Gewinn liegt auf Cloudflares Rechnung für stoßweise Cloud-Agent-Workloads — er spart nichts auf deiner eigenen Hardware. Wenn du nur lokale Browser-Automatisierung willst und bereits Chrome hast, ist lokales Playwright schneller und kann WebGL und Video.

Null Abhängigkeiten

package.json hat einen leeren dependencies-Block, einschließlich für den WebSocket-Transport.

Node's globales WebSocket (WHATWG) kann keine Request-Header senden, und der Konto-Endpunkt benötigt Authorization: Bearer …. undici ist nicht als eigenständiges Modul importierbar. Daher implementiert src/ws.mjs den RFC-6455-Client direkt über node:http(s) — Handshake, Maskierung, Fortsetzungsfragmente, 64-Bit-Längen, Ping/Pong, Close — was alles ist, was CDP mit Header-Unterstützung braucht.

Tests

npm test                        # live tests against the playground
KITESURF_SKIP_NETWORK=1 npm test   # offline only

Die Suite trifft absichtlich den echten Dienst: Die interessanten Fehler (Boas Rekursionslimit, Pipe-Trunkierung, Edge-Statuscodes) treten nur gegen das echte System auf.

Anforderungen

Node ≥ 18. Kein Browser, kein API-Token, kein Build-Schritt.

Lizenz

MIT