crawlio-browser

Crawlio Browser

ドキュメント | API リファレンス | Chrome 拡張機能

CDP 経由で AI に実行中の Chrome ブラウザーを完全に操作させる MCP サーバーです。150 個のツールを備え、フレームワークを考慮したインテリジェンス、型付きエビデンス基盤、トラッキングピクセル分析、テクノグラフィックフィンガープリンティング、SEO 監査、信頼度を追跡する調査結果を提供し、静的クローラーでは取得できない情報を収集します。

Crawlio Browser を使う場面

AI に実際のブラウザーを操作させる必要がある場合は、Crawlio Browser をお使いください。SPA、認証が必要なページ、動的コンテンツ、JS でレンダリングされるフレームワークに対応します。ヘッドレスブラウザーツールとは異なり、Crawlio Browser は軽量な拡張機能を介してお使いの実際の Chromeに接続するため、ログイン済みのセッション、Cookie、ブラウザーの状態全体に AI がアクセスできます。

**Crawlio Browser とヘッドレスブラウザーツールの比較：**ヘッドレスツールは別のブラウザープロセスを起動します。Crawlio Browser は既存の Chrome に接続するため、別のブラウザーもログイン操作も不要で、タブやセッションに完全にアクセスできます。

警告

これは明確に述べておくべきトレードオフです。お使いの Chrome に接続することがこの機能の特長であり、 その結果、AI エージェントはログイン中のすべてのサイトであなたとして操作できます。接続したタブに Chrome のデバッガーをアタッチするため、そのセッションの Cookie、ストレージ、ページコンテンツを読み取れます。

接続先をよく確認してください。エージェントの作業には専用の Chrome プロファイルを使うことをおすすめします。タブを 接続するまでは何も取得されません。また、設定を始める前に npx crawlio-browser tools を実行すれば、 使用できるツールの全容を確認できます。サイト側では <meta name="crawlio-agent" content="disable"> を指定して オプトアウトでき、拡張機能はこれを尊重します。

クイックスタート

1. Chrome 拡張機能をインストールします
2. 初期設定ウィザードを実行します：

   npx crawlio-browser init
   

これで完了です。Claude Code、Cursor、VS Code、Codex、Gemini CLI、Claude Desktop、ChatGPT Desktop、Windsurf、Cline、Zed、Goose、OpenCode、MCPorter、Cline CLI の 14 個の MCP クライアントを自動検出して設定します。

初期設定ウィザードのオプション

npx crawlio-browser init              # Default: code mode, stdio transport
npx crawlio-browser init --full       # Full mode (every tool exposed individually)
npx crawlio-browser init --portal     # Portal mode (persistent HTTP server)
npx crawlio-browser init --cloudflare # Add Cloudflare MCP (89 tools, no wrangler)
npx crawlio-browser init --dry-run    # Show what would happen
npx crawlio-browser init --yes        # Skip prompts (CI / scripted installs)
npx crawlio-browser init -a claude    # Target specific MCP client

エージェントプラグインとして使う

このパッケージは Agent Plugins v1 プラグインでもあるため、準拠したクライアントであればウィザードを実行せずに直接読み込めます。ルートにある plugin.json、skills/ 内の 11 個のスキル、mcp.json で宣言された MCP サーバーで構成されています。

製品向けの crawlio-* ワークフローは、同梱されている 11 個のスキルに統合されています。同様の名前を持つ agents/ 内の定義は、リポジトリ内だけで使う開発用フィクスチャのままです。これらは src/evidence/* と loops/* をインポートしますが、どちらも npm の実行環境には含まれません。実行できない別の製品機能として誤って案内しないよう、package.json から除外しています。

インストール済みのパッケージをクライアントに指定します：

node_modules/crawlio-browser        # after `npm install crawlio-browser`

mcp.json は ${PLUGIN_ROOT}/dist/mcp-server/index.js 経由でサーバーを解決します。そのため、このプラグインは展開した tarball ではなく、インストール済みのパッケージでなければなりません。サーバーは実行時に依存関係をインポートするため、単に展開しただけの状態では起動後に応答せず終了します。

公開される機能の確認

npx crawlio-browser tools          # What code mode exposes (the default)
npx crawlio-browser tools --full   # Every tool, individually
npx crawlio-browser tools --json   # Machine-readable, for diffing across versions
npx crawlio-browser doctor         # Bridge, portal, native host, client configs
npx crawlio-browser --help         # All commands and options
npx crawlio-browser --version      # Version only

どちらも読み取り専用で、ブラウザー、拡張機能、ネットワーク接続なしで実行できます。クライアントを設定する前に、機能の全容を確認できます。表示される数値はサーバーが登録に使うものと同じビルダーから取得するため、クライアントに提供される内容と食い違うことはありません。

トランスポートモード

Claude Code には Portal モードを推奨します。コンテキストの圧縮後やセッションの再起動後もサーバーが稼働し続けるためです。macOS では、--portal を指定すると、ログイン時に自動起動する launchd エージェントがインストールされます。

手動セットアップ（すべてのクライアント）

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

{ "mcpServers": { "crawlio-browser": { "type": "http", "url": "http://127.0.0.1:3001/mcp" } } }

claude mcp add crawlio-browser -- npx -y crawlio-browser

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

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

{ "cline.mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }

仕組み

AI Client (stdio/http)  -->  MCP Server (Node.js)  -->  Chrome Extension (MV3)
                             crawlio-browser               WebSocket -> CDP

MCP サーバーは WebSocket 経由で Chrome 拡張機能と通信します。拡張機能は Chrome DevTools Protocol (CDP) を通じてブラウザーを制御します。

機能

フレームワークを認識したインテリジェンス

すべての execute 呼び出しでブラウザーのフレームワークシグネチャを調べ、フレームワーク固有のアクセサーを備えた、状況に応じて変化する smart オブジェクトを挿入します。React の状態、Vue のリアクティビティ、Next.js のルーティング、Shopify のカートデータなど、4 つの階層にまたがる 17 のフレームワーク名前空間を実行時に検出し、ナビゲーションのたびに再構築します。AI は汎用 DOM を問い合わせるのではなく、フレームワーク独自のデータ構造を問い合わせます。

エビデンスに基づく分析

Method Mode は、Code Mode を基盤として、高次のメソッドと型付きエビデンスシステムを追加します。smart.extractPage() は、ページのキャプチャ、パフォーマンス指標、セキュリティ状態、フォント検出、メタデータの抽出、アクセシビリティ監査、モバイル対応状況の確認という 7 つの処理を、1 回の呼び出しで並列実行します。失敗した処理は、何も返さず null にするのではなく、型付きの CoverageGap レコードを生成します。smart.finding() で作成した所見は、裏付けとなるデータが不足している場合に信頼度が自動調整されます。その結果、ギャップの追跡と信頼度の伝播を備えた、構造化された監査可能な調査結果が得られます。

セッションの記録と再生

ブラウザーの操作を構造化データとして記録し、再利用可能な SKILL.md オートメーションにコンパイルします。記録中は 12 種類の操作ツールが自動的にインターセプトされ、クリック、テキスト入力、ナビゲーション、スクロールなどのそれぞれについて、引数、結果、タイミング、ページ URL が記録されます。compileRecording() を 1 回呼び出すだけで、セッションを決定論的なオートメーションスクリプトに変換できます。

ロボットのトレーニング

人が操作してブラウザーを実演した内容を、再生可能なロボットトレーニング用バンドルとして記録します。デフォルトモードの observe ライフサイクルでは、拡張機能内でイベント駆動型のレコーダーが起動します。MCP プロセスが切断または再起動しても、収集は続行されます。再接続後、training_stop を実行すると保持された実行内容がエクスポートされ、再生と API の合成に使用できる完全な 13 ファイルの RecordingBundle が生成されます。フルモードでは、既存の robot_training_* 名が互換性エイリアスとして維持されます。

ページの監視も同じ理由で常駐します。拡張機能が所有するバックグラウンドタブと Chrome アラームにより、MCP サーバーが存在しない間も、上限付きの ARIA スナップショットが収集されます。トレーニングと監視の履歴は、25 MiB のローカル容量を共有し、件数の上限はトレーニングの完了済み実行が 20 件、監視ジョブが 50 件、スナップショットが合計 200 件、監視ごとに 50 件です。古い完了済みデータから先に削除されます。進行中の作業が通知なく削除されることはありません。作業の開始は明示的な MCP ライフサイクルアクションでのみ行われます。同じアクションでステータスの報告、収集の停止、監視スナップショットの消去、さらに正確な ID と明示的な確認を指定した場合は、生成済みファイルを保持したまま、停止済みのトレーニング／記録レコードを Chrome から削除できます。拡張機能のポップアップは、接続状態とブラウザーへのアクセス状況を表示します。呼び出し側が明示的にオプトインしない限り、ストレージに保存される値はキーのみです。 監視スナップショットには、コンパクトな ARIA ページテキストが意図的にローカルに保持されるため、監視を開始すると、その URL の表示コンテンツが消去されるまで保持されることに同意したものとして扱う必要があります。

自動安定化と操作可能性

すべての変更操作（click、type、navigate、select_option）では、操作前に操作可能性をチェックします。表示状態、寸法、有効状態、オーバーレイの有無をポーリングで確認します。操作後は、段階的なバックオフを伴う安定化待機（[0, 20, 100, 100, 500]ms）により、DOM の変更が落ち着くまで待ちます。AI が操作の合間に手動で sleep() を呼び出す必要はありません。

複数のタブを同時に操作

ページに対して動作するすべてのコマンドでは、list_tabs で取得した任意指定の tabId を使用できます。省略すると、これまでどおり接続済みのタブでコマンドが実行されます。指定すると、そのタブで実行され、すべてのコマンド機能を利用できます。コマンドは並行して動作するため、2 つのタブを同時に操作できます。

const [checkout, search] = await Promise.all([
  bridge.send({ type: "browser_snapshot", tabId: 42 }),
  bridge.send({ type: "browser_snapshot", tabId: 57 }),
]);

タブを指定しても、connect_tab が指すタブは変更されません。そのため、複数のタブを扱うエージェントが、人の見ているタブを切り替えてしまうことはありません。フレームの選択、カバレッジセッション、フレームワーク検出はタブごとに行われます。例外はネットワークキャプチャです。これは一度に 1 つのタブを記録し、2 つのタブを混在させずに、どのタブを対象としているかを示します。

Chrome プロファイル

拡張機能の各インスタンスはそれぞれの Chrome プロファイル内に限定され、他のプロファイルは認識できません。そのため、複数のプロファイルで Crawlio が有効になっている場合、コマンドは最初に接続したプロファイルで実行されます。list_profiles では、接続したプロファイルと、現在操作しているプロファイルを確認できます。switch_profile で接続先を別のプロファイルに切り替えられます。一度に操作できるプロファイルは 1 つです。解放された拡張機能はバックグラウンドで再接続するため、切り替えはすぐに完了します。

プロファイルは、それぞれの拡張機能ストレージに生成される UUID で識別されます。これはプロファイルの説明を含まずに識別するもので、アカウント、メールアドレス、パス、追加の権限は必要ありません。

プロファイルを選択すると、連携する拡張機能同士が干渉せずに動作できます。ただし、ID は拡張機能が申告するものであり、証明されるものではないため、セキュリティ境界ではありません。ブリッジの既存の保護機能に変更はありません。一度に接続できる拡張機能は 1 つであり、それぞれが実行前にサーバーが本物のブリッジトークンを保持していることを証明する必要があります。

アーキテクチャ

各レイヤーが、本来ならモデルに降りかかる複雑さを種類ごとに吸収する、階層型の実行アーキテクチャです。モデルが目にするのは、4つの主要なツールと、すっきりとした SDK です。その表面より下にあるものはすべて、現実に対処するランタイムです。

理解しておく価値があるのは、自ら組み立てられるレイヤーです。初回使用時に実際のページに対して検出を実行し、そのページが何であるかに合わせて smart オブジェクトを構築します。smart.react.* が存在するのは、React が使われている場合だけです。起動時には対象について何もわからないため、インターフェースはあらかじめ定義されるのではなく、タブごとに構成されます。

                     ┌───────────────────────────────────┐
                     │        AI Model (LLM)             │
                     │  Writes code, reads errors, loops  │
                     └───────────────┬───────────────────┘
                                     │  search, execute, observe, connect_tab (+ 3 job tools)
                                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Crawlio Browser runtime                      │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  METHOD MODE                                               │  │
│  │  Behavioral protocol + higher-order methods                │  │
│  │  scrollCapture · waitForIdle · extractPage · comparePages  │  │
│  │  detectTables · extractTable · waitForNetworkIdle ·        │  │
│  │  extractData                                               │  │
│  │                                                            │  │
│  │  ↳ Absorbs: behavioral variance, ad-hoc composition,      │  │
│  │    inconsistent output shapes, data extraction patterns    │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │  POLYMORPHIC CONTEXT                                       │  │
│  │  17 framework namespaces, injected Just-In-Time            │  │
│  │  react · vue · angular · nextjs · shopify · ...            │  │
│  │                                                            │  │
│  │  ↳ Absorbs: framework opacity, minified code,             │  │
│  │    devtools hook complexity                                │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │  ACTIONABILITY ENGINE                                      │  │
│  │  7 core smart methods with built-in resilience             │  │
│  │  click · type · navigate · waitFor · evaluate ·            │  │
│  │  snapshot · rebuild                                        │  │
│  │                                                            │  │
│  │  ↳ Absorbs: DOM timing, hydration delays, CSS animations, │  │
│  │    disabled states, overlapping elements                   │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │  TETHERED IPC BRIDGE                                       │  │
│  │  WebSocket ↔ Chrome extension, message queue,              │  │
│  │  heartbeat, auto-reconnect, stale detection                │  │
│  │                                                            │  │
│  │  ↳ Absorbs: connection drops, tab refreshes,              │  │
│  │    port conflicts, extension lifecycle                     │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │  COMMAND CHANNEL                                           │  │
│  │  bridge.send → CDP browser control via the extension       │  │
│  │  crawlio.*   → Crawlio HTTP endpoints                      │  │
│  │  Live searchable catalog: browser + Crawlio HTTP           │  │
│  └────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
                     ┌───────────────────────────────────┐
                     │         Live Chrome Browser        │
                     │   Persistent session, real DOM,    │
                     │   framework runtime, user state    │
                     └───────────────────────────────────┘

各レイヤーが吸収するもの

実行ライフサイクル

1. 検出 — モデルが search("page capture performance") を呼び出し、関連するコマンドのドキュメントを取得します
2. フレームワーク検出 — ランタイムが実際の DOM を調査してアクティブなフレームワークを検出し、適切な名前空間を持つ多態的な smart オブジェクトを構築します
3. スコープの組み立て — モデルのコードが、注入されたパラメーターを含む非同期関数にコンパイルされます。パラメーターには bridge（ブラウザーのコマンドチャネル）、crawlio（HTTP クライアント）、sleep、TIMEOUTS、smart（7個のコアメソッド＋18個の高次メソッド＋最大17個のフレームワーク名前空間）、compileRecording が含まれます
4. 実行 — メソッドモードのメソッドが下位レイヤーを組み合わせます。extractPage() は7個の bridge.send() 呼び出しを並列実行し、click() は操作可能性エンジンを実行し、react.getVersion() はフレームワーク固有の式を評価します
5. エラー回復（エージェント型 REPL） — 失敗しても、ブラウザーはエラーを引き起こしたときとまったく同じ状態にとどまります。モデルは構造化されたエラーを読み取り、調整して、再度 execute を呼び出します。フレームワークのキャッシュは保持され、URL が変わらない限り再検出は行われません

設計原則

1. 複雑さを下位レイヤーで吸収する — 接続管理、DOM のタイミング、フレームワーク検出、複数ステップの組み立てといった、あらゆる種類の難しさは、それに最も適したレイヤーが処理します。モデルが接するのは最上位のすっきりとしたインターフェースだけです。
2. 対象に合わせて SDK を形作る — 多態的コンテキストシステムがページの種類を検出し、利用可能なメソッドをそれに合わせて再構成します。モデルは安定したインターフェースに対してコードを書き、その下ではランタイムが適応します。
3. サイクルをまたいで状態を維持する — テザリング型アーキテクチャにより、モデルは同じ実行中の環境で失敗から学び、再試行できます。これにより、エラー処理は「最初から再起動する」ものから、「調整して続行する」ものへと変わります。

比較

Code Mode は Cloudflare が考案した優れたアイデアです。ツールを型付き API として提示し、モデルにそれを使ったコードを書かせます。モデルはツール呼び出しよりもはるかに多くのコードを見てきているからです。Crawlio Browser は、このパターンを本来想定されていなかった対象、つまりセッションを保持した稼働中のブラウザーに適用しています。これは MCP サーバーであり、MCP の代替ではありません。

重要なのはエラーからの復旧の行です。アイソレートは設計上、破棄可能です。これにより信頼できないコードを安全に実行できる一方、失敗すると原因となった状態も破棄されます。ここでは実行環境が実際のタブに紐づいているため、コードが失敗してもブラウザーは失敗を引き起こした状況のままです。スクロール位置、モーダル、入力途中のフォームはそのまま残ります。モデルはエラーを読み取り、その状態で再実行します。どちらの方式が常に優れているというわけではありません。それぞれ異なる問題に対する解決策であり、V8 アイソレートによって Cloudflare が得られるサンドボックス化の保証は、ローカル非同期サンドボックスが提供するものより実際に強力です。

アーキテクチャガイド全文を読む →

2 つのモード

Code Mode（主要ツール 4 個）— デフォルト

150 個のツールを 4 個の高レベルツールに集約し、非同期実行用の get_job_result、 list_jobs、cancel_job を加えます。そのため、tools/list の結果は 7 個になります。

これにより、tools/list のペイロードは 85% 小さくなります。これはツール数から推定した値ではなく、各モードが実際に返す結果をシリアライズして測定したものです。Code Mode は無料ではありません。execute と search の説明が長いため、実測した削減率は単純なツール数だけの比率から想定されるより小さくなります。ご自身で確認するには、npx crawlio-browser tools --json を実行してください。何にも接続せずに両方のインターフェースを出力します。

// Navigate and screenshot
await bridge.send({ type: 'browser_navigate', url: 'https://example.com' }, 30000);
await sleep(2000);
const screenshot = await bridge.send({ type: 'take_screenshot' }, 10000);
return screenshot;

Full Mode（150 個のツール）

LLM にすべてのツールを直接公開します。--full で有効にします。

npx crawlio-browser init --full

Smart Object

Code Mode では、smart オブジェクトが自動待機とアクション可能性のチェックを備えた、フレームワーク対応のヘルパーを提供します。

主なメソッド

高次メソッド

型付きエビデンス

信頼度の伝播に対応した、構造化された分析結果を扱うメソッドです。

結果の dimension が有効なカバレッジギャップと一致する場合、信頼度は自動的に上限が設定されます。

フレームワークの名前空間

フレームワークが検出されると、スマートオブジェクトでフレームワーク固有のヘルパーを利用できます。

コードモードでは、モデルにコードを書かせます。メソッドモードでは、そのコードにテスト済みの語彙を与えます。モデルが本来なら即興で組み立てるマルチステップのパターンを表現する、18 個の高階メソッドです。

await smart.extractTable(selector)   // not a hand-rolled scrape loop
await smart.scrollCapture()          // not a guessed scroll cadence

これはコードモードの上に構築されたドメインレイヤーであり、置き換えるものではありません。ツールの構成は変わらず、モデルには引き続き同じ 4 つの主要なツールが表示され、その下には同じ 182 コマンドのカタログがあります。変わるのは、execute の内部で行われる処理です。

ツール群はページごとに構成されます。検出機能は 64 個のフレームワークを認識し、最大 17 個の対応する名前空間を追加します。そのため、smart.react.* は React が使用されているページでのみ利用できます。ページが何で構築されているかをモデルが尋ねたり、調べるためにフックのパスやファイバーの内部構造を推測したりする必要はありません。

また、実行環境は破棄可能な分離環境ではなく、ライブタブに接続されているため、失敗してもブラウザーは失敗が発生したときとまったく同じ状態を保ちます。モデルは構造化されたエラーを読み取り、状況を最初から再構築するのではなく、その状態を対象に再実行します。

成熟度の段階

アーキテクチャ

┌────────────────────────────────────────────────────────────┐
│                      execute sandbox                       │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Behavioral Protocol  (web-research skill)           │  │
│  │  Acquire → Normalize → Analyze                       │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  Evidence Infrastructure                             │  │
│  │  finding() · findings() · clearFindings()            │  │
│  │  Typed records · Coverage gaps · Confidence prop.    │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  Higher-Order Methods  [18]                          │  │
│  │  scrollCapture · waitForIdle · extractPage ·         │  │
│  │  comparePages · detectTables · extractTable ·        │  │
│  │  waitForNetworkIdle · extractData · detectSections · │  │
│  │  detectTechnologies · parseTrackingPixels · ...      │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  Smart Core  [7 methods]                             │  │
│  │  evaluate · click · type · navigate · waitFor ·      │  │
│  │  snapshot · rebuild                                  │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  Framework Namespaces  [up to 17, attached per page] │  │
│  │  react · vue · angular · nextjs · shopify · ...      │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  bridge.send()  — the browser command channel        │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘

上位のレイヤーほど、より多くのドメイン知識が組み込まれています。bridge.send({ type: "capture_page" }) はページをキャプチャします。smart.extractPage() はページをキャプチャし、さらにパフォーマンス指標、セキュリティ状態、フォント検出、アクセシビリティ分析、モバイル対応状況のチェックを並行して実行します。7 つの処理を 1 回の呼び出しで行い、補助データの取得に失敗しても適切に処理し、失敗した項目は型付きの不足項目として記録します。

エビデンスの基盤

カバレッジの不足項目 — extractPage() 内の補助処理に失敗しても、黙って null を返すことはありません。対象の次元、理由、影響、および関連する所見の信頼度を下げるかどうかを含む、型付きの不足項目が記録されます。

// Example gap from a failed performance metrics call
{ dimension: "performance", reason: "CDP domain disabled", impact: "method-failed", reducesConfidence: true }

ツールによって強制される所見 — smart.finding() は、ツールレベルですべてのフィールドを検証します。スキーマを満たさない所見をモデルが生成することはできません。有効な Finding を返すか、明確なエラーを受け取ります。所見は、セッション内の execute 呼び出しをまたいで蓄積され、smart.findings() で取得できます。

セッション全体の集約 — 所見とカバレッジの不足項目は、execute 呼び出しをまたいで保持されます。モデルは複数回の呼び出しにわたって所見を作成し、smart.findings() ですべてをまとめて取得できます。smart.clearFindings() でリセットします。

エンドツーエンドの例：競合分析

// 1. Extract and compare both sites (scaffold + gaps included)
const comparison = await smart.comparePages(
  'https://acme.com',
  'https://rival.com'
);

// 2. Make findings — confidence auto-adjusts based on data availability
smart.finding({
  claim: 'Rival loads 2.3x faster on Largest Contentful Paint',
  evidence: [
    `Acme LCP: ${comparison.siteA.performance?.webVitals?.lcp}ms`,
    `Rival LCP: ${comparison.siteB.performance?.webVitals?.lcp}ms`,
  ],
  sourceUrl: 'https://acme.com',
  confidence: 'high',
  method: 'comparePages + extractPage performance metrics',
  dimension: 'performance',  // if perf data failed, confidence caps to "medium"
});

smart.finding({
  claim: 'Acme has 12 images without alt text; Rival has 0',
  evidence: [
    `Acme imagesWithoutAlt: ${comparison.siteA.accessibility?.imagesWithoutAlt}`,
    `Rival imagesWithoutAlt: ${comparison.siteB.accessibility?.imagesWithoutAlt}`,
  ],
  sourceUrl: 'https://acme.com',
  confidence: 'high',
  method: 'comparePages + extractPage accessibility summary',
  dimension: 'accessibility',
});

// 3. Capture visual evidence
await smart.navigate('https://acme.com');
await smart.waitForIdle();
const acmeVisuals = await smart.scrollCapture({ maxSections: 5 });

// 4. Return accumulated session findings + visual evidence
return {
  findings: smart.findings(),
  scaffold: comparison.scaffold,
  gaps: { acme: comparison.siteA.gaps, rival: comparison.siteB.gaps },
  visualEvidence: { acme: acmeVisuals.sectionCount + ' sections captured' },
};

例

移動、抽出、分析

// Connect to active tab, extract structured page evidence
const page = await smart.extractPage();
const finding = smart.finding({
  claim: `Site uses ${page.capture.framework?.name || 'no detected framework'}`,
  evidence: [`Framework: ${JSON.stringify(page.capture.framework)}`],
  sourceUrl: page.meta?.canonical || 'active tab',
  confidence: 'high',
  method: 'extractPage framework detection',
});
return { page: page.meta, finding };

モバイルエミュレーション + スクリーンショット

// Emulate iPhone and capture
await bridge.send({ type: 'emulate_device', device: 'iPhone 14' }, 10000);
await smart.navigate('https://example.com');
await smart.waitForIdle();
const screenshot = await bridge.send({ type: 'take_screenshot' }, 10000);
return screenshot;

オートメーションの記録とコンパイル

// Record a browser session, then compile to reusable skill
await bridge.send({ type: 'start_recording' }, 10000);
await smart.navigate('https://example.com');
await smart.click('button.submit');
await smart.type('#email', '[email protected]');
const session = await bridge.send({ type: 'stop_recording' }, 10000);
return compileRecording(session.session, 'signup-flow');

ネットワークのインターセプトとモック

// Block analytics, mock API response
await bridge.send({
  type: 'browser_intercept',
  pattern: '*analytics*',
  action: 'block'
}, 10000);
await bridge.send({
  type: 'browser_intercept',
  pattern: '*/api/user',
  action: 'mock',
  body: JSON.stringify({ name: 'Test User' }),
  statusCode: 200
}, 10000);
await smart.navigate('https://example.com');
return await smart.snapshot();

セッションの記録

ブラウザーセッションを構造化データとして記録し、再利用可能なオートメーションスキルにコンパイルします。記録中は、12 個のインタラクションツール（クリック、入力、移動、スクロールなど）が自動的にインターセプトされ、引数、結果、タイミング、ページ URL が記録されます。

// In code mode: record, interact, compile
await bridge.send({ type: 'start_recording' }, 10000);
// ... interact with the page ...
const session = await bridge.send({ type: 'stop_recording' }, 10000);
const skill = compileRecording(session.session, 'my-automation');
return skill;

フルモードでは、記録機能は start_recording、stop_recording、get_recording_status、compile_recording の 4 つの個別ツールとして利用できます。

自動セトル

変更を伴うツール（browser_click、browser_type、browser_navigate、browser_select_option）は、アクション可能性を確認します。

1. 事前確認：操作前に要素の表示状態、安定性、有効状態をポーリングします
2. アクション：CDP コマンドをディスパッチします
3. 処理後のセトル：段階的なバックオフ [0, 20, 100, 100, 500]ms で DOM の変更が落ち着くまで待機します

つまり、AI はアクションの間に sleep() や waitFor() を手動で追加する必要はありません。ツールが SPA のレンダリング遅延を自動的に処理します。

フレームワークの検出

グローバル変数、DOM マーカー、メタタグ、HTTP ヘッダー、スクリプト URL を使って、4 つのティアにわたる 64 種類のテクノロジーを検出します。

複数のフレームワークが検出された場合、プライマリフレームワーク（メタフレームワークが優先）に加え、スタック全体を示す subFrameworks 配列を返します。

ツールリファレンス

以下の表は、よく使われるツールについて手作業で作成したガイドであり、すべてのツールを網羅するものではありません。
すべてのツール（150 種類）の最新情報をサーバー自体から取得するには、
npx crawlio-browser tools --full を実行してください。

要件

• Node.js >= 18
• Crawlio for Chrome 拡張機能がインストールされた Chrome（または Chromium）
• Crawlio.app（オプション） — サイトのクロールとエンリッチメントに使用します

権限の最小要件

本番環境の拡張機能には、常時有効なホストアクセス権がありません。必要な権限は、debugger（CDP 制御プレーン）、storage（ブリッジ／セッション設定と永続的な常駐メタデータ）、alarms（再接続、アイドル時の解放、常駐モニターの起動）のみです。専用のオンボーディングページでは、アクティブなビルドで宣言されているすべてのオプション機能について、一度だけ権限を求めます。本番環境では tabs、nativeMessaging、http://127.0.0.1/* が対象となり、タブの検出／引き継ぎ、認証済みのローカルトークンの提供、ループバックブリッジの検出に使用されます。

Chrome の権限プロンプトを開けるのはオンボーディング画面のみです。拡張機能のポップアップと MCP ツールは、不足しているアクセス権を報告し、ユーザーをオンボーディング画面に案内するだけです。tabs メタデータの権限が拒否されても、connect_tab({url})、エージェントが所有するタブ、ロボットのトレーニング、常駐モニタリングでは、引き続き独自のタブを作成して操作できます。Crawlio は <all_urls>、activeTab、tabGroups、unlimitedStorage を要求しません。

ソースからビルドする

git clone https://github.com/Crawlio-app/crawlio-browser.git
cd crawlio-browser
npm install
npm run build          # selectors → semantic-grounding → MCP server → extension

ビルド出力は dist/mcp-server/（ESM バンドル）と dist/extension/（展開済みの MV3 拡張機能）に生成されます。

拡張機能を使った開発では、開発用バリアントをビルドして、展開済みの状態で読み込みます。

npm run build:dev      # → dist/extension-dev, with __DEV__ logging enabled

次に、chrome://extensions を開き、デベロッパー モードを有効にして、Load unpacked を選択し、dist/extension-dev を指定します。ビルドのたびに、そこで拡張機能を再読み込みしてください。

npm test               # vitest
npm run typecheck      # server + extension TypeScript projects

リソース

• ドキュメント
• API リファレンス
• 製品ページ
• Chrome 拡張機能
• npm パッケージ
• ソースコード
• 変更履歴 | リリース

貢献

貢献を歓迎します。ビルドと開発の手順についてはCONTRIBUTING.md、コミュニティでの行動規範についてはCODE_OF_CONDUCT.mdをご覧ください。セキュリティ上の脆弱性は、公開イシューではなくSECURITY.mdを通じて非公開で報告してください。

ライセンス

Apache-2.0です。詳細はLICENSEをご覧ください。

packages/selectorsのセレクターカーネルはMITライセンスです。Selector Forge（MIT）およびChromium DevTools（BSD-3-Clause）から移植したコードが含まれています。帰属表示の詳細はpackages/selectors/LICENSEおよびTHIRD_PARTY_NOTICES.mdをご覧ください。