kitesurf-bridge

Cloudflare Kitesurf — Cloudflare Workers上のV8アイソレートで動作するエージェントファーストブラウザ — をどこからでも操作できます。依存関係ゼロ、ローカルChrome不要。

1つのエンジンを4つの方法で利用できます：

以下のインストールコマンドはGitHub仕様を使用しており、レジストリアカウントなしで今日から動作します。 npmに@truenix/kitesurf-bridgeとして公開された後は、すべての github:TrueNix/kitesurf-bridgeは@truenix/kitesurf-bridgeに短縮されます。

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

これにより、実際のブラウザエンジンで実際のページがレンダリングされ、Cloudflareのネットワーク上で動作します。ローカルにブラウザをインストールする必要はなく、APIトークンも不要です。

なぜこれが必要か

Kitesurfはオープンソースではなく、お使いのマシンでは実行できません。Cloudflareはブログで「準備ができ次第」オープンソース化する意向を示していますが、その場合でも、顧客は「自分のアカウントに自分のバージョンのKitesurfをデプロイする」ことが目的とされており、依然としてWorkers上での実行になります。

また、開発ループにローカルのKitesurfはありません。wrangler devはお使いのローカルChromeを起動するものであり、Kitesurfではありません。Kitesurfはリモートエンドポイントのbrowser=kitesurfの背後にのみ存在します。

したがって、実際の問いは「ローカルで実行できるか」ではなく、「ローカルコードからドライブできるか」です。このパッケージがそのブリッジです。

存在理由

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_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

プラグインはホスト上に同じツールを登録します。動的なCordisホスト半分にはWebSocket、fetch、node:*へのアクセスがないため、サンドボックス内でCDPを開くことはできません。そのため、意図的にCLIをシェルアウトします。詳細は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を使用するのではなく、Rust製JSエンジンのBoaを使用します。 Boaは再帰制限がはるかに低く、RuntimeLimit: exceeded maximum number of recursive callsをスローします。自然な再帰的なDOMウォークは、大きなページ（Wikipedia、ドキュメントサイトなど）で失敗します。このパッケージのMarkdownコンバーターは、明示的なスタックでDOMをウォークし、呼び出し深度をO(1)に保ちます。kitesurf_evaluateを使用する場合は、反復的な式を推奨します。

ナビゲーション障害はCDPエラーではなく、エッジステータスコードとして現れます。 Page.navigateは、存在しないホストでも通常のframeId/loaderIdを返し、Network.loadingFailedは発生しません。欠落したドメインは520として現れ、Page.navigateはエージェントに空のページを成功として渡します。このパッケージは、Networkドメインのイベントから結果を分類し、空のドキュメントが>=400ステータスで返された場合にエラーをスローし、読み取り可能なコンテンツを持つ実際のエラーページ（status付き）はそのまま返します。

機能フラグ（検証済み）：

これらの機能が必要な場合は、Browser Runのデフォルトブラウザ（Chromium）を使用してください。

パフォーマンストレードオフ（Cloudflareの発表によると）：KitesurfはウォームなChromiumに比べてCPUとメモリを3〜7倍少なく使用しますが、1.7〜3倍遅いです。クラウド上でバースト的なエージェントワークロードにとっては有利ですが、自分のマシンでは何も節約できません。ローカルのブラウザ自動化だけが必要で、すでにChromeがある場合、ローカルのPlaywrightの方が高速で、WebGLもサポートしています。

ゼロ依存

package.jsonにはdependenciesブロックが空であり、WebSocketの依存関係も含まれていません。

NodeのグローバルなWebSocket（WHATWG）はリクエストヘッダーを送信できず、アカウントエンドポイントではAuthorization: Bearer …が必要です。undiciはスタンドアロンモジュールとしてインポートできません。そのため、src/ws.mjsはRFC 6455クライアントをnode:http(s)上で直接実装しています — ハンドシェイク、マスキング、継続フラグメント、64ビット長、ping/pong、クローズ — これらはすべてCDPに必要なもので、ヘッダーをサポートしています。

テスト

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

このスイートは意図的に実サービスに対して実行します。実際の障害（Boaの再帰制限、エッジステータスコード、空のドキュメント処理）は、実サービスに対してのみ発生します。

要件

Node.js ≥ 18。ブラウザもAPIトークンもビルドステップも不要です。

ライセンス

MIT