substrate-browser

Substrate

ウェブページを読むために、48Kトークンを無駄にするのはやめましょう。Substrateは一般的なコンテンツページを、LLMが実際に使える約1～4Kトークンに圧縮します。生のHTMLでは約48Kトークンです。

Substrateは、AIエージェントにウェブ上の視覚と操作の手段を提供するMCP サーバーです。あらゆるウェブページから、ボタン、入力欄、リンク、ドロップダウン、チェックボックスなどを含む圧縮されたセマンティックグラフを、正確なピクセル座標とともに抽出し、座標を使ったクリック、入力、選択を実行します。CSSセレクターもXPathも不要です。幻覚もありません。

重要な理由

他のあらゆるブラウザー自動化手法では、ノイズにトークンを浪費します。

手法	トークン数	抽出時間	LLMが得るもの
生のHTML（page.content()）	約48,000	5ms	完全なDOMツリー。スクリプト、スタイル、非表示要素、広告のマークアップも含まれます。LLMはノイズに埋もれ、見えない要素をクリックする幻覚を起こします。
ビジョン（スクリーンショット＋OCR）	約8,000	約800ms	ピクセルの塊です。LLMはページを「見る」ことはできますが、正確な対象を指定できません。クリック位置が20pxずれ、フォームの操作に失敗します。
Substrate	約1,000～4,000	約10～30ms	構造化されたJSONです。各要素が何で、どこにあり、どのような状態かを示します。LLMは最初の試行で正しい対象をクリックできます。

計算例： 約110個の要素を含むコンテンツページ（たとえばWikipedia）は、約2,300トークンに圧縮されます。一般的な128Kのコンテキストウィンドウの約1.8%です。LLMのコンテキストが埋まるまで、約55ページ分を抽出できます。生のHTMLでは2ページです。

トークン数は概算値で、代表的なページで実測しています（example.com：約84トークン、Wikipedia：約3.5K、Hacker Newsのトップページ：約4.4K、抽出時間：8～58ms）。ページの密度に応じて増減します。抽出器は出力をMAX_ELEMENTS=400に制限しているため、非常に密度の高いページは全体を出力せず、途中で切り詰められます。計算は単純です。約2.3Kトークンのページなら、⌊128K/2.3K⌋ ≈ 55回抽出できます。

真のメリット — アクションループの短縮：

Without Substrate:                          With Substrate:
navigate → screenshot                       navigate
→ "I see a button" → click (wrong)          → {btn id=3 "Submit" [640,400]}
→ screenshot → "ah, more right"             → click(3) → done.
→ click → "not that either"                 
→ screenshot → ...                          2 tool calls. Task complete.
8-12 tool calls. Task complete.

これはわずかな改善ではありません。ウェブタスクあたり、API呼び出しが5～6倍少なく、レイテンシが5～6分の1になり、コストが5～6分の1になります。

仕組み

Substrateは、Model Context Protocol（MCP）を介して、ヘッドレスChromiumブラウザーとして動作します。LLMエージェントは、10個のシンプルなツールを通じて操作します。

ツール	機能
navigate	URLを読み込み、ページグラフを取得します（要素数は最大400）
click	数値IDで任意の要素をクリックします
type_text	入力欄にテキストを入力します（最初に自動でクリア）
select_option	値を指定してドロップダウンの項目を選択します
press_key	キーボードキーを押します（Escape、Enter、Tab、矢印キー、修飾キー）
scroll	ビューポートの80%分だけ上下にスクロールします
screenshot	ビジュアルスナップショットとグラフを一緒に取得します
go_back / go_forward	ブラウザーの履歴を移動します
get_current_url	現在のURLを確認します

すべてのナビゲーションツールと操作ツールは、同じ圧縮グラフを返します（get_current_urlはURLのみを返し、screenshotは画像とグラフを返します）。LLMはグラフを読み、要素IDを選び、次のツールを呼び出します。画像の解釈も、HTMLの解析も不要です。IDと座標だけです。

インストールとセットアップ

Substrateは、単独で動作するModel Context Protocol（MCP）サーバーです。使用するためにコードを書く必要はありません。AI アシスタントに追加するだけです。

オプション1：Claude Desktop（推奨）

1. Claude Desktopの設定ファイルを開きます。
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. mcpServersブロックにsubstrate-browserサーバーを追加します。

{
  "mcpServers": {
    "substrate-browser": {
      "command": "npx",
      "args": ["-y", "substrate-browser"]
    }
  }
}

3. Claude Desktopを再起動します。10個のブラウザーツール（小さなハンマーのアイコン）が利用できるようになります。Claudeに「example.comにアクセスして、何が見えるか教えて」と頼むことができます。

*(注：初回実行時に、PlaywrightがChromiumのバイナリを自動的にダウンロードします。システムに**Node.js 20+*がインストールされている必要があります。)

オプション 2：ソースから実行する（開発者向け）

抽出ロジックを変更したり、独自のツールを追加したりする場合：

git clone https://github.com/manuelinuxkr/substrate-b.git
cd substrate-b
npm install
npx playwright install chromium
npm run build
npm start

ライセンス

MIT