kitesurf-bridge

어디서나 Cloudflare Kitesurf — Cloudflare Workers의 V8 isolate에서 실행되는 에이전트 우선 브라우저 — 를 구동하세요. 의존성 제로, 로컬 Chrome 불필요.

하나의 엔진을 사용하는 네 가지 방법을 제공합니다:

아래 설치 명령은 GitHub 스펙을 사용하며, 레지스트리 계정 없이도 오늘 바로 작동합니다. npm에 @truenix/kitesurf-bridge로 게시되면 모든 github:TrueNix/kitesurf-bridge는 @truenix/kitesurf-bridge로 단축됩니다.

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

이것은 로컬에 브라우저가 설치되어 있지 않고 API 토큰도 없이, Cloudflare 네트워크에서 실제 브라우저 엔진으로 실제 페이지를 렌더링합니다.

왜 필요한가

Kitesurf는 오픈 소스가 아니며 사용자 머신에서 실행할 수 없습니다. Cloudflare는 "준비가 되면" 오픈 소스화할 의도가 있다고 밝혔지만, 그때조차 명시된 목표는 고객이 *"자체 계정에 자체 Kitesurf 버전을 배포"*하는 것 — 여전히 Workers에서입니다.

또한 개발 루프에는 로컬 Kitesurf가 없습니다: wrangler dev는 사용자 로컬 Chrome을 실행하지 Kitesurf를 실행하지 않습니다. Kitesurf는 원격 엔드포인트의 browser=kitesurf 뒤에만 존재합니다.

따라서 실질적인 질문은 "로컬에서 실행할 수 있나"가 아니라 "로컬 코드에서 구동할 수 있나"입니다. 이 패키지가 바로 그 다리입니다.

설치

MCP 서버로

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"
      }
    }
  }
}

노출되는 도구: kitesurf_markdown, kitesurf_text, kitesurf_html, kitesurf_links, kitesurf_screenshot, kitesurf_evaluate, kitesurf_accessibility_tree, kitesurf_probe.

DSH / Cordis 플러그인으로

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

이 플러그인은 호스트에 동일한 도구를 등록합니다. 의도적으로 CLI로 셸 아웃합니다: 동적 Cordis 호스트 절반에는 WebSocket, fetch 또는 node:* 액세스가 없으므로 샌드박스 내에서 CDP를 열 수 없습니다. cordis/plugin.mjs를 참조하세요.

라이브러리로

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

유용한 옵션: --main, --raw, --full, --width, --height, --json, --endpoint, --account, --token, --timeout.

엔드포인트

CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN(또는 CF_*)을 설정하여 전환하세요. 토큰 없이 계정 ID를 제공하면 공유 플레이그라운드로 조용히 다운그레이드되는 대신 하드 오류가 발생합니다.

[!WARNING] 플레이그라운드는 무료, 공유, 인증되지 않은 리소스이며 SLA가 없습니다. 평가 및 로컬 에이전트 작업에는 적합하지만 — 프로덕션을 구축하지 마세요.

Kitesurf에 대해 알아두면 좋은 사항

이 내용은 문서에서 복사한 것이 아니라 실제 서비스에 대해 검증된 것입니다. kitesurf-bridge probe가 이를 재현합니다.

Kitesurf는 페이지 스크립트에 V8을 실행하지 않고 Boa — Rust JS 엔진 — 을 실행합니다. Boa는 훨씬 낮은 재귀 한도를 적용하며 RuntimeLimit: exceeded maximum number of recursive calls를 던집니다. 자연스러운 재귀 DOM 탐색은 큰 페이지(위키백과, 문서 사이트)에서 죽습니다. 따라서 이 패키지의 Markdown 변환기는 명시적 스택으로 DOM을 탐색하여 JS 호출 깊이를 O(1)로 유지합니다. kitesurf_evaluate를 사용한다면 반복 표현식을 선호하세요.

탐색 실패는 CDP 오류가 아닌 Cloudflare 엣지 상태 코드로 도착합니다. Page.navigate는 존재하지 않는 호스트에 대해서도 정상적인 frameId/loaderId를 반환하며 Network.loadingFailed는 발생하지 않습니다. 존재하지 않는 도메인은 HTTP 530으로, 손상된 오리진은 520으로 나타나며 ~16자짜리 플레이스홀더 문서가 남습니다. Page.navigate를 신뢰하면 에이전트가 빈 페이지를 받고 성공으로 처리합니다 — 그래서 이 패키지는 Network 도메인에서 결과를 분류하고 빈 문서와 함께 >=400 상태가 오면 예외를 던지며, 읽을 수 있는 콘텐츠가 있는 실제 오류 페이지(status 포함)는 계속 반환합니다.

기능 플래그(검증됨):

이러한 기능이 필요하면 대신 Browser Run의 기본 Chromium 브라우저를 사용하세요.

성능 트레이드오프(Cloudflare 자체 수치): Kitesurf는 웜 Chromium보다 CPU와 메모리를 3–7배 적게 사용하지만 벽시계 시간은 1.7–1.8배 느립니다. 이 이점은 버스트성 클라우드 에이전트 워크로드에 대한 Cloudflare의 청구서에 대한 것입니다 — 사용자 하드웨어에서는 아무것도 절약되지 않습니다. 로컬 브라우저 자동화만 원하고 이미 Chrome이 있다면 로컬 Playwright가 더 빠르고 WebGL과 비디오도 지원합니다.

의존성 제로

package.json에는 WebSocket 전송을 포함하여 dependencies 블록이 비어 있습니다.

Node의 전역 WebSocket(WHATWG)은 요청 헤더를 보낼 수 없으며, 계정 엔드포인트에는 Authorization: Bearer …가 필요합니다. undici는 독립 모듈로 가져올 수 없습니다. 따라서 src/ws.mjs는 node:http(s) 위에서 RFC 6455 클라이언트를 직접 구현합니다 — 핸드셰이크, 마스킹, 연속 프래그먼트, 64비트 길이, ping/pong, close — CDP에 필요한 모든 것이며 헤더 지원이 포함됩니다.

테스트

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

이 스위트는 의도적으로 실제 서비스를 대상으로 합니다: 흥미로운 실패(Boa의 재귀 한도, 파이프 잘림, 엣지 상태 코드)는 실제 서비스에서만 나타납니다.

요구 사항

Node ≥ 18. 브라우저 불필요, API 토큰 불필요, 빌드 단계 불필요.

라이선스

MIT