Dev Browser MCP

🚀 dev-browser-mcp

MCP（モデルコンテキストプロトコル）サーバーで、OpenCode（およびその他のMCPクライアント）がローカルで実際のChrome/Chromiumタブを駆動できます。これは、Chromeを--remote-debugging-portで起動する必要なく、Chrome DevTools Protocol（CDP） コマンドを送信することで実現されます。

このサーバーは、「既存のローカルブラウザーセッションでクリック、入力、ナビゲート、スクリーンショットを撮るエージェントが欲しい」 という問題を、軽量な拡張機能ブリッジとローカルリレーを使って解決します。

🚀 クイックスタート

このプロジェクトは、標準入出力 を介してMCPサーバーを実行します。内部的には、Chrome/Chromiumの 拡張機能 に接続するローカルの リレー と通信します。

✨ 主な機能

拡張機能モードのリレーとエンドポイント

リレーは以下のエンドポイントを公開します。

• ws://HOST:PORT/extension
  ブラウザー拡張機能がここに接続します（一度に1つの接続）。
• ws://HOST:PORT/cdp
  CDPに似たWebSocket エンドポイントです。MCPサーバーはここに接続し、CDPのJSONメッセージを送信します。

dev_browser_goto、dev_browser_click などのツールは、最終的に CDPコマンド（例：Page.navigate、Runtime.evaluate、Page.captureScreenshot）を /cdp を介して送信します。リレーはこれらのコマンドを拡張機能に転送し、CDPイベントを接続されたクライアントに転送します。

📦 インストール

前提条件

• Node.js >= 18
• dev-browser拡張機能 がインストールされたChrome/Chromium（拡張機能は実行中で、ws://HOST:PORT/extension に接続できる必要があります）
• OpenCode がインストールされ、MCPサーバーを実行するように設定されている

セットアップ

npm install
npm run build

これにより、dist/ と実行可能なエントリーポイントが生成されます。

📚 ドキュメント

OpenCodeの設定

OpenCodeは、グローバル 設定と プロジェクト 設定の両方をサポートしています。どちらの場合も、dev_browser という名前のMCPサーバーエントリを追加します。

グローバル設定: ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dev_browser": {
      "type": "local",
      "command": ["node", "/Users/<you>/Code/devtools/dev-browser-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "HOST": "127.0.0.1",
        "PORT": "9222",
        "RELAY_MODE": "auto"
      }
    }
  }
}

プロジェクト設定: ./opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dev_browser": {
      "type": "local",
      "command": ["node", "./dist/index.js"],
      "enabled": true,
      "environment": {
        "HOST": "127.0.0.1",
        "PORT": "9222",
        "RELAY_MODE": "auto"
      }
    }
  }
}

注意事項

• シークレットやトークンは必要ありません。
• MCPサーバーは標準入出力を介して通信します。OpenCodeは command 配列を介してサーバーを起動します。

環境変数

• HOST（デフォルト: 127.0.0.1）
  リレーのHTTP/WSサーバーのホストです。
• PORT（デフォルト: 9222）
  リレーのHTTP/WSサーバーのポートです。
• RELAY_MODE（デフォルト: auto）
  MCPサーバーがリレーを起動するか、既存のリレーに接続するかを制御します。
  • auto: 最初に http://HOST:PORT/ を調べます。既にリレーが実行中の場合は、接続 します。そうでない場合は、リレーを 起動 します。
    • リレーの起動が EADDRINUSE で失敗した場合、再度 http://HOST:PORT/ を調べます（タイムアウト時間を長くします）。リレーに到達できる場合は、接続 します。そうでない場合は、元のエラーを再スローします。
  • start: 常に独自のリレーを起動します（ポートの競合で失敗する可能性があります）。
  • connect: 決して起動せず、http://HOST:PORT/ に既存のリレーが必要です（到達できない場合はエラーをスローします）。

💻 使用例

典型的なフローは、拡張機能が接続されていることを確認 → タブを開く/選択 → ナビゲート → インタラクション → スナップショット/スクリーンショットを撮る です。

1) 拡張機能の接続を待つ

{
  "tool": "dev_browser_ensure_extension_connected",
  "input": { "timeoutMs": 30000, "pollIntervalMs": 250 }
}

2) 名前付きのタブを開く（または再利用する）

{
  "tool": "dev_browser_page_open",
  "input": { "name": "my-tab" }
}

3) ナビゲート

{
  "tool": "dev_browser_goto",
  "input": {
    "url": "https://example.com",
    "waitUntil": "load",
    "timeoutMs": 30000
  }
}

4) スナップショット（AIに適したDOMアウトライン）

{
  "tool": "dev_browser_snapshot",
  "input": {}
}

スナップショットには、クリックや入力に使用できる snapshotRef 識別子が含まれています。

5) クリック / 入力

CSSセレクターでクリック

{
  "tool": "dev_browser_click",
  "input": { "selector": "button[type='submit']" }
}

snapshotRef でクリック（dev_browser_snapshot の出力から）

{
  "tool": "dev_browser_click",
  "input": { "snapshotRef": "e123" }
}

CSSセレクターで入力

{
  "tool": "dev_browser_type",
  "input": { "selector": "input[name='q']", "text": "hello", "clearFirst": true }
}

snapshotRef で入力

{
  "tool": "dev_browser_type",
  "input": { "snapshotRef": "e456", "text": "hello", "clearFirst": true }
}

6) スクリーンショット

{
  "tool": "dev_browser_screenshot",
  "input": { "fullPage": false, "saveToFile": true }
}

saveToFile=true（デフォルト）の場合、以下の場所にPNG画像が保存されます。

• ./.opencode/dev_browser/

そして、ファイルパス（画像コンテンツも含む）が返されます。

ツールリスト

• dev_browser_relay_status — リレーの状態（wsEndpoint、extensionConnected、mode）を取得します。auto モードでは、リレーを起動または接続します。
• dev_browser_ensure_extension_connected — extensionConnected=true になるまで待ちます（リレーの / をポーリングします）。
• dev_browser_pages_list — リレーに登録された名前付きページのリストを取得します。
• dev_browser_page_open — リレーを介して名前付きタブを取得または作成し、以降のアクションの対象として選択します。
• dev_browser_page_delete_mapping — リレー内の名前付きページのマッピングを削除します。
• dev_browser_goto — 選択されたタブを指定のURLにナビゲートします。
• dev_browser_click — CSSセレクターまたは snapshotRef（dev_browser_snapshot から）で要素をクリックします。
• dev_browser_type — CSSセレクターまたは snapshotRef（dev_browser_snapshot から）で入力欄にテキストを入力します。
• dev_browser_wait_for_selector — 選択されたタブでセレクターが見つかるまで待ちます。
• dev_browser_evaluate — 選択されたタブのコンテキストでJavaScriptを評価します。
• dev_browser_screenshot — PNG形式のスクリーンショットを撮り、./.opencode/dev_browser に保存し、ファイルパスを返します。
• dev_browser_snapshot — 選択されたタブのAIに適したスナップショット（YAML形式に似たもの）を返します。

dev-browser (SawyerHood/dev-browser) との関係

このプロジェクトは、SawyerHood/dev-browser と同じコアアイデアをMCPクライアント（OpenCode）に公開するために構築されました。つまり、永続的な状態を持つ実際のブラウザーを駆動 し、LLMに適したDOMスナップショット を提供します。

再利用/整合性のある部分

• 拡張機能モードのCDPリレーの概念: dev-browserには、ローカルリレーが拡張機能（chrome.debugger）と自動化クライアント間でCDPメッセージを橋渡しする「拡張機能モード」があります。
• 名前付きページ: 両システムは POST /pages 抽象化を公開し、名前付きタブを作成/アクティブ化し、targetId を返します。
• スナップショット参照: dev-browserのスナップショットアプローチでは、注入されたスクリプトを使用して、安定した [ref=eN] マーカーを持つYAML形式に似たアウトラインを返します。

異なる部分

• プロトコルの表面: dev-browserはClaude Codeプラグイン/スキルとして配布されていますが、このリポジトリはOpenCode用に設計された独立した MCPサーバー です。
• 制御パス: 「スキルクライアント」APIを提供する代わりに、このプロジェクトはCDPコマンドを送信する個別のMCPツール（dev_browser_goto、dev_browser_click など）を公開します。
• マルチOpenCodeのリレー所有権: このMCPは RELAY_MODE=auto をサポートしているため、複数のOpenCodeインスタンスが単一のリレープロセスに接続でき、EADDRINUSE でクラッシュすることがありません。
• 決定的なタブターゲティング: アクションは targetId + Target.attachToTarget セッションを介して特定のChromeタブにスコープされているため、別々のOpenCodeインスタンスが異なる名前付きタブを確実に制御できます。

🔧 トラブルシューティング

extensionConnected=false

• Chrome/Chromiumが実行中で、dev-browser拡張機能がインストール/有効化されていることを確認してください。
• 拡張機能が ws://HOST:PORT/extension に接続できる必要があります。
• dev_browser_relay_status を実行して、リレーに到達できることと extensionConnected の状態を確認してください。

EADDRINUSE / ポートの競合

• PORT=9222 は他のツール（Chromeのリモートデバッグを含む）で一般的に使用されています。
• 別のポートを選択することで解決できます。
  • PORT を設定し（リレーと拡張機能で一貫性を保つ）
  • または、別の場所でリレーを実行して接続したい場合は、RELAY_MODE=connect を設定します。

複数のOpenCodeインスタンス / タブの命名

• dev_browser_page_open を使用して、明示的で一意のタブ名を使用することをおすすめします（例："myproject-admin"、"myproject-patient"）。
• ツールに pageName を渡さない場合、「最後に選択された」ページで操作されます。各ワークスペース/エージェントで常に名前付きページを開く/選択することで、衝突を回避してください。

スクリーンショットの保存場所

• デフォルトでは、スクリーンショットは以下の場所に保存されます。
  • ./.opencode/dev_browser/
• ファイルが見つからない場合は、現在の作業ディレクトリ（OpenCodeプロジェクトのルート）を確認し、saveToFile=true であることを確認してください。