Browser Controller

このプロジェクトが解決する問題

あなたは修正をリリースする。エージェントは「完了しました。確認してください」と言う。 あなたはAlt-TabでChromeに切り替え、ページに移動し、ログインし、クリックして回り、バグを見つける。

エージェントはコードを書いたばかりなのだから、検証もできるはずだ。 あなたのブラウザはすでに開かれていて、そこにある。ただ、エージェントには見えていないだけだ。

今、それが可能になります。 Browser Controllerは、MCP互換のあらゆるAIエージェント（Cursor、Claude Desktop、Windsurfなど）に、あなたがすでに開いているブラウザへの直接制御を与えます — あなたの実際のセッション、ログイン、クッキーもそのまま。ヘッドレスブラウザも、新しいプロファイルも、再認証も不要です。

Related MCP server: Tabryn

主な機能

• 複数エージェントの同時利用。 Cursorがタブ10を操作しながら、Claudeがタブ11を操作できます — どちらも1つの共有デーモンを介して、互いにブロックしません。

• 「アクティブタブ」ではなく「タブ指定」。 すべてのアクションがtabIdを指定します。マウスを動かしても、タブを切り替えても、YouTubeを見ていても、エージェントはあなたが指定したタブで作業を続けます。あなたが読んでいるページを乗っ取ることは決してありません。

• タブごとの分離。 要素参照、コンソールログ、ネットワークバッファはタブごとにスコープされます。タブ10の参照がタブ20の何かをクリックすることは絶対にありません。

• タブごとの並行処理。 同じタブへの2つのアクションは直列化されます（競合なし）。異なるタブへのアクションは並列実行されます。

• タブのロック。 エージェントがタブを確保でき、他のエージェントは競合せずに待機します（browser_tabs { action: "lock" }）。ロックはChromeのサービスワーカー再起動後も維持されます（chrome.storage.session）。

• エージェント制御シールド。 エージェントがタブで作業している間、半透明の青い内側フレームが表示され、そのタブでの入力（マウス、キーボード、ホイール）はブロックされます — バッジにはagent <name> controlling the tabと表示され、アクションが完了すると消えます。タブをロックすると、ロックの間はプレーンなフレームが維持されます。

• 同一オリジンのiframe貫通。 iframe内にあるレガシー/エンタープライズUI（例：iframe#mainFrame内のONTコンソール）にも到達可能です。すべてのロケーターツールがiframeドキュメントを検索し、find/click_textはすべてのフレームを走査します。

• ダイアログ救出。 ネイティブのalert/confirm/promptはページのJSスレッドをフリーズさせます — browser_handle_dialogはCDP経由でページJSを介さずにそれを閉じ、同じタブの他のすべてのツールのブロックも解除します。browser_tabs close/focusは、フリーズしたタブでも常に機能します。

• 認証付きローカル接続。 トークン＋ワンタイム登録シークレットにより、他のローカルプロセスがあなたのブラウザを静かに操作することはできません。すべてはlocalhost上で完結します — クラウドもテレメトリもありません。

• デバッガーバナーなし。 browser_evaluateはchrome.scripting経由でページのMAINワールドで実行されます — 黄色い「このタブはデバッグ中です」バナーは表示されず、実際の値がMV3のワールド境界を越えて返されます。

• 正直なエラー。 すべてのツールの失敗は、完全なペイロードを伴う実際のisError結果としてエージェントに届きます — ワークフロー途中の失敗を隠す「成功」レスポンスはありません。

仕組み

3つのコンポーネント、すべてあなたのマシン上にあります。localhostの外には何も出ません。

  Agent (Cursor / Claude / Windsurf)        ── other agents connect too ──┐
                  │ stdio (MCP protocol)                                   │
                  ▼                                                        ▼
  ┌─────────────────────────────┐   ┌─────────────────────────────────────────┐
  │  thin MCP client            │   │  thin MCP client                        │
  │  (node mcp-server/dist/     │   │  (node mcp-server/dist/                 │
  │   index.js)                 │   │   index.js)                             │
  │  - speaks MCP over stdio    │   │  - spawns daemon if not running         │
  │  - forwards calls to daemon │   │  - gets its own sessionId               │
  └──────────────┬──────────────┘   └────────────────────┬───────────────────┘
                 │ local IPC socket (AF_UNIX / named pipe, token-auth)     │
                 ▼                                                          ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  DAEMON (single long-running process, owns port 7225)                     │
  │  - multiplexes N clients → 1 extension                                    │
  │  - tags every call with the client's sessionId                            │
  │  - heartbeat eviction, per-session rate limiting                          │
  └──────────────────────────────┬───────────────────────────────────────────┘
                                 │ WebSocket ws://127.0.0.1:7225 (token-auth)
                                 ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  Chrome Extension (Manifest V3 service worker)                            │
  │  - resolves the target tabId (never "the active tab" implicitly)          │
  │  - serializes same-tab actions, parallelizes cross-tab actions            │
  │  - executes click/type/snapshot/evaluate against the named tab            │
  └──────────────────────────────────────────────────────────────────────────┘

重要なアイデア： 最初のエージェントが実行されると、シンクライアントがバックグラウンドデーモンを起動し、ポート7225と拡張機能の接続を所有します。その後のすべてのエージェント（別のMCPクライアントからでも）は、ローカルIPCソケット経由で同じデーモンに接続し、独自のsessionIdを取得します。拡張機能は1つの安定した接続を認識し、各呼び出しを呼び出し元が指定した正確なタブにルーティングします。

クイックスタート

このプロジェクトはChrome Web Storeやnpmには公開されていません — このリポジトリからインストールします。2つのパーツがあります：MCPサーバー（あなたのマシンで実行され、AIエージェントと通信します）とChrome拡張機能（ブラウザ内に常駐し、コマンドを実行します）。

前提条件： Node.js ≥ 20 と Chrome/Chromium/Edge。

1. クローンしてビルド

git clone https://github.com/compnew2006/browser-controller.git
cd browser-controller
npm install
npm run build        # compiles TypeScript → mcp-server/dist/

2. Chrome拡張機能を読み込む

1. chrome://extensionsを開き、デベロッパーモードを有効にします（右上のトグル）

2. パッケージ化されていない拡張機能を読み込むをクリックし、クローンしたリポジトリのextension/フォルダを選択します

3. Browser Controllerのアイコンをツールバーにピン留めします

グレーのドット＝デーモンを待機中。緑＝接続済み。

3. MCPサーバーをクライアントに追加

Cursor：設定 → MCP → 「新しいMCPサーバーを追加」。Claude Desktop：claude_desktop_config.jsonを編集。Windsurf：設定 → MCP。MCP互換のクライアントならどれでも動作します。

/path/to/browser-controllerをクローン先の絶対パスに置き換えてください（Windows：C:\\path\\to\\browser-controller\\mcp-server\\dist\\index.jsを使用）：

{
  "mcpServers": {
    "browser-controller": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"]
    }
  }
}

デフォルトでは、デーモンは各接続を親IDEの名前（「Cursor」「Claude」など）で命名します。上書きする場合 — 例えば複数のエージェントが1つのIDEを共有している場合や、プロジェクトごとにラベルを付けたい場合 — 引数に--agent <name>を渡します。これはすべての自動検出より優先されます：

{
  "mcpServers": {
    "browser-controller": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js", "--agent", "My Project Agent"]
    }
  }
}

名前はポップアップの接続済みエージェントリストに表示されます。（MCP_AGENT_NAME環境変数でも設定できます — 同等です。）同じ名前で再接続すると古いエントリが置き換えられるため、IDEの再起動で重複が蓄積されることはありません。

4. 拡張機能とデーモンをペアリング

デーモンは2つのシークレットを使用します。どちらも初回実行時に~/.browser-controller/（Windows：%USERPROFILE%\.browser-controller\）に生成されます。エージェントに「ブラウザのタブを一覧表示して」と依頼して一度起動し、その後：

1. シークレットを読み取ります：

   cat ~/.browser-controller/enrollment.json   # one-time pairing secret
   cat ~/.browser-controller/token.json        # WebSocket auth token

   （登録シークレットは初回実行時にMCPクライアントのログにも出力されます。）

2. 拡張機能のアイコンをクリック → 設定タブ → 登録シークレットと認証トークンを貼り付けます（WS_PORTを変更していない限り、ポートは7225のままにします）。

緑のドット＝接続完了。エージェントがあなたのブラウザを見られるようになりました。

これらのシークレットにより、他のローカルプロセスがWebSocketを開いて認証済みのブラウザセッションを操作することを防ぎます。ローテーションするには、MCPクライアントを停止し、フォルダを削除すると、次回の実行で両方のシークレットが再生成されます。完全な脅威モデルについてはSECURITY.mdを参照してください。

使い方

モデルはタブファーストです：エージェントは常にどのタブで操作するかを指定します。「アクティブタブ」を推測することはありません。

基本ワークフロー

1. タブを一覧表示してtabIdを取得します：

   browser_tabs { action: "list" }
   → [{ id: 15, url: "...", title: "...", active: true, lockedBy: null }, ...]

2. そのタブをスナップショットして構造を確認し、要素参照を取得します：

   browser_snapshot { tabId: 15 }
   → { tree: [ { ref: "e3", role: "button", name: "Sign in" }, ... ] }

   参照はこのtabIdに対してのみ有効です。ナビゲーションやDOMの変更があった場合は、再スナップショットしてください。前回のスナップショット以降に追加された新しい要素には**isNew: true**のタグが付きます — アクションでオーバーレイやドロップダウンが開いた後、エージェントはツリー全体を読み直す代わりに、それらの要素だけに注目できます。

3. 操作は参照と同じtabIdを使用して行います：

   browser_click { tabId: 15, ref: "e3" }
   browser_type  { tabId: 15, ref: "e5", text: "hello@example.com" }
   browser_press_key { tabId: 15, key: "Enter" }

   参照が古くても要素がまだ存在する場合は、堅牢なセレクター＋テキスト/ロールスキャンで自動的に見つかります（レスポンスにはvia: "fallback"が含まれます）。要素が完全にスクロールアウトされている場合（仮想化フィード）、レスポンスには**freshRefs: [...]**として新しいスナップショットがインラインで含まれます — 同じステップでその新しい参照のいずれかを使って再試行してください。別途スナップショットは不要です。

4. 検証 — アクション後に再度スナップショットまたはテキストを読み取ります。

マルチエージェント連携（2つのエージェント、2つのタブ）

1. エージェントAがタブを一覧表示し、タブ10を選択し、必要に応じてロックします：browser_tabs { action: "lock", tabId: 10 }

2. エージェントBがタブを一覧表示し、タブ11を選択し、ロックします：browser_tabs { action: "lock", tabId: 11 }

3. 両方が並列で作業します。各エージェントの呼び出しは自身のタブに対して直列化され、2つのタブが干渉することはありません。

4. 完了したら：browser_tabs { action: "unlock", tabId: 10 }。

ポップアップはコントロールパネル

固定高さのタブ付きシェル（本体はスクロールせず、リストのみがスクロールします）：

• タブ — ロック所有者付きのすべての開いているタブ。ツールバーのすべてロック解除で、エージェントがロック中にクラッシュした場合もワンクリックで解放できます。

• エージェント — 接続中の各エージェントの名前、セッションID、稼働時間、および即時切断用の✕（ハートビートがまだ回収していないゾンビをクリアします）。

• 設定 — WebSocketポート、認証トークン、登録シークレット。

• アクティビティバー — 下部の折りたたみ可能なストリップで、最新のツールアクティビティを表示します。展開するとロールログが表示されます。

知っておくべきこと

• tabIdを忘れた？ 明確なエラーが返ります：tabId is required. Call browser_tabs list first.

• 保護されたページ（chrome://、Web Store、devtools）はスクリプト化できません — サイレントハングではなくCannot access protected page (chrome://...)が返ります。

• **browser_navigate**はtabIdがオプションの唯一のツールです（デフォルトはアクティブタブ）— ただしマルチエージェントの安全性のため、明示的に渡してください。ハッシュのみの変更（例：/page → /page#section）は、completeイベントを待たずにURLが設定された時点で解決します（SPAはハッシュ変更でリロードしないため、そのイベントは発生しません）。

• browser_evaluateはページのMAINワールドで実行され（デバッガーバナーなし、CSPセーフ）、実際の値を返します（ワールド境界を越えてJSONシリアライズされます）。強力ですが非冪等です — タイムアウト時に自動再試行されません。

• 仮想化フィードのスクロール（Facebook/Instagram/Twitter）：browser_scrollはrefsMayBeStale: trueを返します。これらのサイトはDOMノードを再利用するためです。次の操作の前に再スナップショットしてください。

• 重複要素：複数の要素が同じテキスト＋ロールを共有する場合（例：「いいね」ボタンが3つ）、フォールバックリゾルバーは最初の一致だけでなく、序数（nth）で正しいものを選択します。

• フリーズしたタブ（ネイティブダイアログによるブロック）でもデッドロックしません：browser_handle_dialogがCDP経由で閉じ、browser_tabs { action: "close" }が保証された脱出手段として常に機能します。

🧠 エージェントに教える

エージェントは22のツールすべてをすぐに使用できますが、タブファーストのワークフローを知っていればよりうまく機能します。リポジトリのルートから：

npm run setup:cursor   # or: node mcp-server/dist/index.js --setup cursor

これにより以下がインストールされます：

• ~/.cursor/rules/browser-controller.mdc — タブ指定ワークフロー、ドロップダウン処理、タブをロックすべきタイミング

• ~/.cursor/commands/check-browser.md — Cursorチャットに/check-browserを追加

その後、任意のチャットで/check-browserと入力します。または「ブラウザで結果を確認して」と言うだけで、エージェントは何をすべきか理解します。

npm run setup:claude

プロジェクトのルートにAGENTS.mdを追加します。Claude Codeが自動的に検出します。

手動インストールやルールのカスタマイズについてはagent-config/を参照してください。

できること

22のツール。すべてのページ操作ツールは**tabId**を受け取ります（唯一の例外はbrowser_navigateで、オプションです）。

参照

操作

browser_upload_fileは、ユーザーが選択したかのようにローカルファイルを<input type="file">に注入します。ネイティブダイアログは開かず、その後input/changeイベントが発火するため、React/Vueフォームが反応します。

browser_upload_file { tabId: 15, selector: "#resume", filePath: "/Users/me/resume.pdf" }
browser_upload_file { tabId: 15, ref: "e12", files: ["/tmp/a.png", "/tmp/b.png"] }

パスは絶対パスで、ブラウザを実行しているマシンにローカルです。ref/selectorを省略すると、ページ上の最初のファイル入力を自動ターゲットします。複数ファイルを一度に扱うには、multiple属性を持つ入力が必要です。

ナビゲーション

デバッグと高度な機能

他との比較

設定

デーモンの状態ファイル

デーモンはすべてを~/.browser-controller/（Windows: %USERPROFILE%\.browser-controller\）に保持します：

完全にリセットするには：MCPクライアントを停止し、フォルダを削除すると、次回の実行で新しいシークレットとともに再作成されます。

信頼性

• デーモンは、最初にクライアントが実行されたときに自動起動され、デタッチされた状態で実行され続けます。

• 接続切断時は指数バックオフ（1秒→30秒）を使用し、10秒ごとにping/pongヘルスチェックを行います。3回のpongを逃したクライアントは排除されます。

• セッションごとのレート制限（毎分120コール）により、暴走するエージェントループからデーモンを保護します。

• ツールごとのタイムアウト（ほとんどのアクションで5〜15秒、ナビゲーションで60秒）は、各ツールの定義と同じ場所に配置されているため、レジストリからずれることはありません。

• 冪等な読み取りツール（snapshot、screenshot、text、find）はタイムアウト時に再試行されます。副作用のあるツール（click、type、navigate、evaluate）— およびconsole/network（clear:trueで変更される）— は決して再試行されないため、クリックが2回発生することはありません。

• 別のプロセスがすでにポート7225を保持している場合、デーモンは自分が起動していないプロセスを強制終了するのではなく、起動を拒否します。競合を報告するので、意図的に解決できます。

クライアントごとにWS_PORTを設定して、異なるポートで2つのデーモンを実行します：

{
  "mcpServers": {
    "browser-work": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"]
    },
    "browser-personal": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"],
      "env": { "WS_PORT": "9333" }
    }
  }
}

各拡張機能のポップアップのポートを一致するように更新します。

アーキテクチャ

すべてはあなたのマシン上に留まります。拡張機能はlocalhost上の認証付きWebSocketを介してデーモンに接続します。MCPクライアントはローカルIPCソケットを介してデーモンに接続します。クラウドもプロキシもなく、ブラウザから何も外部に出ません。

browser-controller/
├── mcp-server/          MCP server (TypeScript)
│   └── src/
│       ├── daemon.ts        Single multi-client daemon (owns WS :7225)
│       ├── daemon-config.ts IPC protocol, paths, auth/enrollment tokens
│       ├── index.ts         Thin stdio MCP client (spawns daemon, multiplexes)
│       ├── bridge.ts        Extension WS server + cross-platform port probe
│       ├── register-tools.ts Progressive-disclosure wiring
│       └── tools/           One file per tool (22), registry pattern
├── extension/           Chrome extension (Manifest V3, plain JS, ES modules)
│   ├── background.js        Wiring only (~30 lines): inject router, register events, connect
│   ├── lib/                 state (buffers/locks/persistence), connection (WS lifecycle),
│   │                        router (dispatch + mutex/locks + control shield), page-exec,
│   │                        overlay, lock-ops, tab-concurrency (pure, unit-tested)
│   ├── handlers/            Tool implementations: navigation, interaction, inspection, tabs, cdp
│   ├── utils/               navigation + smart-selector fallback resolution
│   ├── events.js            chrome.* listeners (console capture, popup, webRequest, lifecycle)
│   ├── content.js           Console capture
│   └── popup/               Fixed tabbed shell (Tabs · Agents · Settings) + collapsible activity bar
├── agent-config/        Pre-built configs for Cursor + Claude Code
│   ├── cursor/              Rules and commands
│   ├── skills/              Browser automation skill
│   └── setup.mjs            One-command installer
└── tests/               15 suites / 215 tests

スタック: TypeScript (strict) · MCP SDK · WebSocket · Chrome Extension Manifest V3 · Vitest

開発

git clone https://github.com/compnew2006/browser-controller.git
cd browser-controller
npm install
npm run build
npm test

このスイートは、WebSocketブリッジ（トークン認証拒否と統合エラーチャネルを含む）、ツールレジストリ、デーモンのライフサイクル（ハートビート排除、レート制限、IPC認証）、タブごとの並行性（同一タブの直列化 + タブ間の並列化）、およびモックされたchrome APIを介した拡張機能の動作（ルーターディスパッチ、シールドセマンティクス、evaluateラウンドトリップ、iframe貫通、ダイアログレスキュー）をカバーしています。CIはNode 20と22でスイートを実行し、さらにCodeQLとScorecardスキャンも行います。

既存のインストールの更新

git pull
npm install
npm run build

次に2つの手動ステップ：chrome://extensionsで拡張機能を再読み込みし（実行中のサービスワーカーはファイル変更を自動的に取得しません）、デーモンを再起動します — デーモンは長時間稼働し、dist/も再読み込みしません（デーモンを強制終了するか、MCPクライアントを再起動するだけで、次回の実行で新しいビルドで再起動されます）。

FAQ

それがまさにポイントです。拡張機能は実際のChrome内で実行されます — 同じクッキー、同じセッション、同じローカルストレージ。再認証は不要です。

いいえ。MCPクライアント、デーモン、拡張機能はすべてlocalhost（IPCソケット + WebSocket）で通信します。あなたのマシンから何も外部に出ません。アナリティクスもテレメトリもクラウドコンポーネントもありません。脅威モデル、認証設計、初回接触のTOFUウィンドウについてはSECURITY.mdを参照してください。

MCP互換のクライアントならどれでも動作します。Cursor、Claude Desktop、Claude Code、Windsurf、Cline、その他MCPプロトコルに対応するすべてのクライアントが対象です。複数のクライアントを同じデーモンに対して同時に実行できます。

はい。各エージェントは共有デーモンに接続し、独自のsessionIdを取得して、特定のtabIdを対象とします。同じタブに対する操作はタブごとのミューテックスを通じて直列化され、異なるタブに対する操作は並列に実行されます。オプションとして、エージェントはlockを使用してタブの排他アクセスを要求できます。他のエージェントは失敗するのではなく、ロックの後ろで待機します。

それは起こりません。少なくとも黙っては起こりません。すべてのページ操作ツールはtabIdを必須としており、欠落している場合は明確なtabId is requiredエラーが返されます。エージェントが偶然あなたが見ているタブで操作することは決してありません。(唯一の例外はtabIdなしのbrowser_navigateで、これはアクティブなタブを使用します。ただし、マルチエージェント利用時は常にtabIdを渡すべきです。)

これらがないと、マシン上の任意のローカルプロセスがポート7225へのWebSocketを開き、認証済みのブラウザセッション(銀行、メール、会社のSSO)を操作できてしまいます。エンロールメントシークレットは、拡張機能とデーモンを一度だけペアリングします(WebSocketが存在する前の帯域外で)。その後、認証トークンがすべての接続を認証します。両方とも~/.browser-controller/にモード0600で保存されます。

それらはゼロから新しいブラウザインスタンスを起動します。状態もクッキーもセッションもありません。毎回ログインフロー全体をやり直す必要があります。これは、すでに開いているブラウザに接続し、すべてが読み込まれた状態を利用します。

コントリビューション

バグ報告、機能リクエスト、PRはイシュートラッカーで歓迎します。大きな変更の場合は、まずイシューを開いてください。

セキュリティ

SECURITY.mdを参照してください。localhost限定のアーキテクチャ、トークン+エンロールメント設計、脅威モデル、報告ガイドラインについて説明しています。

ライセンス

MIT