unbrowser by Unchained

unbrowser

エージェント向けの低コストなブラウザ処理。ネイティブバイナリ1つ。Chromeは不要です。

公式 MCP Registry ID： mcp-name: io.github.protostatis/unbrowser

unbrowser は、エージェント向けのステートフルな非ビジュアルウェブランタイムです。curl／WebFetch と実際のブラウザの中間に位置し、Cookie と DOM の状態を保持して、クエリ可能な要素参照を返し、リンクや HTML フォームを処理し、チャレンジや SPA のシグナルを検出します。また、静的 HTML だけでは不十分な場合に、範囲を限定した QuickJS のページスクリプトを実行できます。

デフォルトの navigate は、高速な静的／SSR 処理です。 範囲を限定した QuickJS の実行が必要な場合に限り、exec_scripts: true を設定してください。大規模な SPA、ピクセル、V8 の忠実度、拡張機能、対話型のボット対策チャレンジには、実際の Chrome を使用してください。

インストールする前に、ライブ公開ウェブデモをお試しください。このデモで受け付けるのは、ページに表示されている固定の公開ソースセットのみです。個人データ、Cookie、認証が必要なタスクは送信しないでください。公開サイトでのスモークテストには、共有 Streamable HTTP MCP エンドポイント https://unchainedsky.com/unbrowser-mcp を利用できます。本番環境のセッションにはローカルインストールを使用してください。

アクセスが許可されているサイト、アカウント、データに対してのみ unbrowser を使用してください。 チャレンジの検出や Cookie のインポートによって、アクセス制御やサイトの利用規約を回避する許可が与えられるわけではありません。セッション Cookie は認証情報として扱ってください。ローカルに保管し、許可されたタスクに限定して使用し、公開デモには決して送信しないでください。

適切なティアを選ぶ

HTTP だけでは機能が足りず、フルブラウザーのコストが高すぎる場合に unbrowser を使用してください。ページで Chrome が必要な場合、実現できない互換性があるかのように装うのではなく、出力でエージェントに上位ティアへの移行を指示します。

クイックスタート

Docker — Linux amd64/arm64、プルサイズ約13 MiB

docker pull ghcr.io/protostatis/unbrowser:latest

# One-shot navigation
docker run --rm ghcr.io/protostatis/unbrowser:latest \
  navigate https://example.com --json

# Default mode: MCP over stdio
docker run --rm -i ghcr.io/protostatis/unbrowser:latest

イメージは distroless で、root 以外のユーザーとして実行されます。シェル、パッケージマネージャー、永続状態はありません。本番環境では :vX.Y.Z またはイメージダイジェストを固定してください。

Python

pipx install pyunbrowser   # recommended on macOS / modern Linux
# or, inside a Python 3.10+ virtual environment:
pip install pyunbrowser

from unbrowser import Client

with Client() as ub:
    ub.navigate("https://news.ycombinator.com")
    for link in ub.query(".titleline > a")[:3]:
        print(link["text"], link["attrs"]["href"])

macOS では、/usr/bin/python3 は3.9であり、wheelをインストールできません。pipx または Homebrew の Python を使用してください。PyPI の配布名は pyunbrowser ですが、インポート名と実行ファイル名は引き続き unbrowser です。

MCP

{
  "mcpServers": {
    "unbrowser": {
      "command": "unbrowser",
      "args": ["--mcp"]
    }
  }
}

最小構成："--mcp-profile", "minimal" を追加すると、navigate／query／extract／help のみが公開され、エージェントは help(topic) を使って残りの機能を見つけられます。Python ラッパーには、3つのツール（search／open／help）を備えたスマートサーバーが unbrowser-smart コンソールスクリプトとして含まれています。

{
  "mcpServers": {
    "unbrowser": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "ghcr.io/protostatis/unbrowser:latest"
      ]
    }
  }
}

Cargo、リリースアーカイブ、ソースビルド、永続シェルセッション、生の JSON-RPC、すべての MCP オプションについては、インストールとインターフェースのリファレンスを参照してください。

エージェントが得られる情報

• navigate は BlockMap を返します：ページタイトル、ランドマーク、見出し、操作可能な要素、密度シグナル、ASCII のアウトラインが含まれます。サイズはページによって異なり、固定トークン数を保証するものではなく、計画に役立つよう構造化されています。
• 安定した要素参照（e:142）：要素を一度クエリすれば、HTML を再解析せずに click、type、または submit を実行できます。
• 状態を保持する Cookie とフォーム：Cookie jar、GET および URL エンコードされた POST フォーム送信、リンク、リダイレクトはセッション内で維持されます。
• ページとチャレンジのシグナル：density.likely_js_filled、thin_shell、challenge.provider により、スクリプトを実行するか、埋め込みデータを調べるか、停止するか、許可されたブラウザーセッションにエスカレーションするかをエージェントが判断できます。
• すべての結果にルーティング支援機能：micro_hint（次に行う具体的な手順）、next_tools（優先順位付きの候補）、avoid（実行できる処理がないツール）、および再試行可能性／重大度／証拠を伴う安定した escalation 分類（challenge、thin_shell、partial_result など）が含まれます。推奨事項が avoid と矛盾することはありません。
• 構造化されたヘルパー：ルートの検出、カードの抽出、テーブルの正規化、text_main、セレクターのデバッグにより、一般的な抽出ワークフローに対応します。

スクリプトモードとエスカレーション

{"id":1,"method":"navigate","params":{"url":"https://example.com","exec_scripts":true}}

exec_scripts: true を指定すると、インラインスクリプトと外部スクリプトが、制限付きウォッチドッグのもとで QuickJS 上で実行されます。これにより、軽量なハイドレーションや取得可能なデータを反映できますが、V8 やレンダリングエンジンではありません。負荷の大きい React／Vue／Ember アプリでは、空のシェルが残ることがあります。

許可されたタスクで実際のピクセル、Canvas／WebGL、Workers、ブラウザー拡張機能、V8 互換性、認証済みプロファイル、または人間による確認が必要な場合は、unchainedsky-cli または Unchained にエスカレーションしてください。ユーザーが Chrome ですでに許可されたセッションを確立している場合、cookies_set を使って必要なセッション Cookie をローカルにインポートでき、有効期限が切れるまで利用できます。これはサイトの制御を回避する許可ではありません。

ドキュメント

ライセンス

Apache-2.0 — LICENSE を参照してください。