Umbra

サインイン済みの自分の Chrome を、AI エージェントに Cookie を渡すことなく、セッション単位でエージェントから操作する。

Umbra は、あなたが生成する共有キーで連携する2つの部品から成ります。すべての Chrome API 呼び出しを担う MV3 Chrome 拡張機能と、任意の MCP クライアントにブラウザのツール面を公開するローカル MCP サーバーです。2つは認証付きループバック WebSocket でのみ通信します。マシンの外に出る情報は何もありません。

存在理由

ブラウザをリモートデバッグすると、エージェントに一度にすべてが渡ります。すべてのタブ、すべての Cookie、すべてのプロファイルです。Umbra はその逆の立場を取ります。エージェントが取得できるのは、自分が作成したタブグループとその中のタブだけです。所有していない保有タブの読み取りを要求されても、Umbra は Chrome に触れる前に拒否します。

2つのツールが意図的にその境界の外側に置かれており、その両方が docs/permissions.md にそう記載されています。browser_find_tabs と browser_find_groups は、セッションが所有していないタブのタイトルと URL を報告します。これがタブを引き渡す方法です。また browser_cleanup_groups は、プロファイル全体でタブグループのタイトルを照合し、消えたセッションが残したタブを整理できます。browser_cleanup_groups には自分のグループが共有しないタイトルプレフィックスを指定するか、初回は dryRun: true で実行してください。

その境界があるからこそ、すでにログインしているブラウザで安全に使えます。エージェントはサインイン済みのダッシュボードを読み取り、フォームへ入力し、CSV を出力し、終わったら自分のタブを閉じられます。あなたの他のウィンドウは一切触れられず、読み取られることもありません。

このプロジェクトは、あえて地味な設計にしています。

• 実ブラウザ (Chrome)、実プロファイル、実サインイン状態 — すべてあなたが選ぶ

• 1つのブラウザで複数のエージェントセッションを並行実行し、それぞれ個別のタブグループに隔離

• すべての操作でセッションごとのタブ所有権を強制

• Cookie のエクスポート、トークンの抽出、CAPTCHA の解決、汎用バックグラウンドフェッチはいずれも行わない

• ループバック限定の転送と、双方向の HMAC ハンドシェイク

Related MCP server: byob

インストール

通常のインストールに必要なすべての変数を説明した完全な手順は docs/install.md にあります。短くまとめると:

git clone https://github.com/RobertJLora/umbra
cd umbra/mcp-server
npm install
npm test

依存関係はルートではなく mcp-server/ に入っているため、ルートでの npm install は何もインストールせず、上記コマンドを一度実行するまでルートでの npm test は失敗します。実行後は npm test、npm run doctor、npm run release:check がすべてルートで動作します。

chrome://extensions でデベロッパーモードをオンにし、extension/ ディレクトリを「パッケージ化されていない拡張機能を読み込む」で読み込みます。拡張機能のオプションページを開いて Generate Key をクリックし、次に Copy Environment Line をクリックして、その行を MCP クライアントの設定にペーストしてください。クライアントを再起動するとツールが表示されます。初めてページを読むまで、同じページの Grant Site Access もクリックしておきます。Umbra はインストール時にはサイト アクセスを一切要求しないためです。

インストールは公開リポジトリからのチェックアウトです。上記のクローンを行った後の node mcp-server/cli.js pair でキーが生成され、~/.umbra/shared-key に書き込まれ、クライアント設定ブロックが出力されます。公開チェックアウトにオプションのローカルプラグインは含まれていません。

ツール一覧

セッションとタブ browser_create_tab、browser_list_tabs、browser_switch_tab、browser_close_tab、browser_close_session_tabs、browser_freeze_session_tabs、browser_group_tabs、browser_cleanup_groups、browser_mark_debug_group、browser_tabs_context、browser_get_session_status、browser_get_bridge_pressure

既に開いているタブの受け取り browser_find_tabs、browser_adopt_tab、browser_find_groups、browser_adopt_group

移動 browser_navigate、browser_navigate_back、browser_navigate_forward、browser_wait、browser_resize

読み取り browser_get_page_content、browser_read_page、browser_read_interactive、browser_find、browser_get_technical_snapshot、browser_screenshot、browser_console_messages

操作 browser_click、browser_click_text、browser_type、browser_fill、browser_form_input、browser_select_option、browser_hover、browser_press_key、browser_shortcut、browser_scroll、browser_file_upload

往復を減らす複合ツール browser_batch、browser_wait_click_read、browser_navigate_wait_read、browser_click_wait_selector_read

エスケープ手段 browser_javascript、browser_run_page_action、browser_wait_for_download

browser_reload_extension は、アンパック開発インストール専用です。UMBRA_ALLOW_EXTENSION_RELOAD=1 でのみ表示され、ストアインストールでは拒否されます。オプションページの Reload ボタンでも同様の操作ができ、セッションをまたぐツールを公開する必要はありません。

上記のリストは公開ビルドの全ツール面です。チェックアウトには、公開ビルドに含まれない任意のページレシピプラグインをローカルに置けます。mcp-server/plugins/ のモジュールと extension/recipes/ のページレシピ引き合わせです。どちらのフォルダもトラックされておらず未公開で、プラグインは、それを保持しているインストールにのみ、独自のツールと独自の browser_run_page_action 値を追加します。

呼び出す前に知っておくべき注意点:

• browser_get_page_content はデフォルトでテキストのみを返し、セレクタの範囲指定と maxChars 上限に対応します。表示中の画像一覧 (可視イメージインベントリ) が必要なときだけ includeImages: true を渡してください。

• browser_batch は生成、移動、待機、読み取り、クリック、入力、キー押下、スクロール、閉じるを、1回の MCP 呼び出しで制限付きで実行します。子パラメーターは、直前の成功ステップを {"$ref":"prev.tabId"}、ステップをインデックスで参照する場合は {"$ref":"0.tabId"}、以前の呼び出しが label: "create" を設定していた場合は {"$ref":"create.tabId"} で参照できます。

• browser_read_interactive は、可視コントロールの一覧と、現在の DOM バージョンに対応した短時間だけ有効な参照 (ref) を通常で返します。browser_click、browser_fill、browser_scroll、browser_screenshot はその ref を受け取ります。期限切れの ref は、呼び出し元に再読み取りを求めるエラーを返します。

• browser_get_bridge_pressure は、1つのセッションのプレッシャーを報告します。所有タブ数とそのサンプル、接続中のリスナー数、コンテンツエージェント、コンテンツエージェントのキュー深さです。また、もう存在しないタブの所有権レコードを整理するため、純粋な読み取り専用でもありません。

• browser_freeze_session_tabs は、所有している非アクティブのタブを chrome.tabs.discard で破棄してレンダラーのメモリを解放します。デフォルトは dryRun: true で、別セッションが所有するタブを対象にすることはありません。

• browser_run_page_action は、定義済みの名前付きページアクションを実行し、JSON 安全な値を返します。これは任意のスクリプトを実行するツールではありません。任意のスクリプトを実行するのは browser_javascript 側で、所有タブの debugger を通じて実行されます。

全体の仕組み

1. MCP クライアントは stdio でローカルサーバーと通信します。

2. サーバーはループバックブリッジ・リスナーに直接、または Rust Broker 経由でセッションを登録します。

3. Chrome 拡張機能のオフスクリーンドキュメントが WebSocket を保持し、サービスワーカーの churn をまたいで接続を続けます。

4. 拡張機能は共有キーとセッション単位の nonce による HMAC チャレンジで各接続を認証します。

5. バックグラウンドサービスワーカーは各セッションに専用のタブグループを割り当て、すべての Chrome 呼び出しの前に所有権をチェックします。

トランスポートは2種類あります。Rust Broker がランチャーのデフォルトで、1つの拡張 WebSocket に対して多数の軽量 MCP シム、ローカル Unix ソケット越しにセッションを登録し、ブローカーがルーティング、認証、プレッシャーカウンター、リクエストクリリーンナップを担います。レガシーモードではセッションごとに個別のループバックリスナーを持ち、UMBRA_BROKER_MODE=legacy で切り替えられます。どちらでも Chrome API に触れるのは拡張だけです。

並行性と所有権

• 1つの Chrome プロファイルが多数のセッションを同時にホストします。

• 各セッションには has、セッション ID、名前付きシアン色のタブグループ、それぞれのブラウザビューが割り当てられます。

• オープン、ナビ制御、DOM 操作はデフォルトで non-act扱いのタブに作用するため、通常の一連の作業が Chrome を前面に出しません。実際にフォーカスが必要な場合のみ activate: true を渡してください。

• Umbra は自分のタブ用に専用の Chrome ウィンドウを記憶し、新しいセッションのタブをそこへ割り当てします。そのウィンドウがフォーカスされている間はそれを再利用しないため、あなたが作業しているウィンドウにタブを追加することはありません。

• ナビゲーションは拡張境界でスキームに制限されます。http:、https:、file:、about:blank が許可され、javascript: や data: などの危険なスキームは Chrome が受け取る前に拒否されます。

• タスク完了では、エージェントは browser_close_session_tabs を呼び出し、所有グループ全体を閉じます。ウィンドウ内の全タブがセッションに属しているときだけウィンドウ全体を閉じ、所有されていない空白タブは残ります。

• サーバーの正常終了もデフォルトと同じクリーンアップを行います。実行後タブを開いたまま確認する必要がある場合は UMBRA_KEEP_TABS_OPEN=1 か UMBRA_CLOSE_ON_SHUTDOWN=0 を設定します。

• デフォルトのポート範囲は 47821-47852 で、一般的なマルチエージェント環境で不足することはありません。拡張機能は設定されたポートを 1024-65535 に制限します。両側で同じ範囲を設定してください。

Umbra がやらないこと

• Cookie のダンプや同期

• トークンの抽出

• ストレージの読み書きをツールとして公開

• ページの代わりにバックグラウンドフェッチ

• CAPTCHA の自動解決

• ブックマーク、履歴、クリップボードに触れること

• ネイティブメッセージングの利用

• 自動更新、自動プール、自動インストール

さらにその他は一切行いません。

既知の制限

• デフォルトのスクリーンショットは、撮影前にセッション所有のタブをアクティブにします。silent: true を指定すると、所有タブに じあった上で Page.captureScreenshot` を一度実行して回避しますが、その際 Chrome は自動化中バナーを表示します。

• サイトアクセスはオプション権限で、インストール時ではなくオプションページの Grant Access Access ボタンから要求します。許可されるまで、ページ読み取りとスクリーンショットは Chrome の権限エラーで失敗します。Chrome がプログラム上の表示タブキャプチャに、リテラルな広域ホスト権限を要求するためです。docs/permissions.md には、拡張機能が宣言する全権限の理由が書かれています。

• ダウンロードの完了検出はファイルシステムの監視で行います。これは拡張が Chrome の downloads 権限を要求しないためです。ブラウザのダウンロードフォルダを変更している場合は、UMBRA_DOWNLOAD_DIR をそれを示すよう設定してください。

• browser_read_interactive が意図的に控えめなのはおすすめ。Umbra は完全なアクセシビリティツリーのダンプを公開しません。

• 一般的なテキストのクリックは、検索のページネーションのような濃厚なアプリ UI で誤ったコントロールを押すことがあります。推測代わりに、ref を使うた browser_read_interactive、または browser_run_page_action で inspect_controls の後に click_control を使ってください。

• ポート範囲を変更するには両側の再読込が必要です。MCP クライアントを再起動して新サーバプロセスが環境変数を継承し、展開した拡張を再読み込みして、永続化された拡張ストレージを正規化してください。

ディレクトリ構成

• extension/ - MV3 拡張機能: バックグラウンドワーカー、オフスクリーンブリッジ、コンテンツエージェント、options ページ、ポップアップ

• extension/recipes/ - オプションの、サイト固有ページレシピ。必要に応じ注入され、公開パッケージには含まれません

• mcp -server/ - stdio 度 MCP サーバー、ループバックブリッジ、Rust River Broker シムクライアント、ローカル開発ハーネス

• rust-broker/ - 1つの拡張 WebSocket 上でセッションを多重化する Tokio ブローカーランタイム

• tests/ - 認証、保持、セッション分離、拡張ライフサイクル、パッケージングのテストカバー

• scripts/ - 分離した Chrome テストプロファイル起動とスモークテストラッパー

• launchd/ - オプションの macOS ジョブのテンプレート。ブローカーを起動し続けます

• docs/ - インストール、アーキテクチャ、権限、スモークテストの資料

ドキュメント

• docs /install.md - クローンからセッションが繋がるまでのセットアップと、すべての環境変数

• docs/architecture.md - コンポーネント、フロー、オフスクリーンとバックグラウンド分割の設計意図

• docs/permissions.md - 各 Chrome 権限のリスクと対策

• docs/smoke-test.md - 自動および手動の確認手順

• docs/performance/performance-work.md - パフォーマンス改善が変えたものと測定したもの

• MCP_PROTOCOL.md - 拡張とサーバー間のワイヤープロトコル

• THREAT_MODEL.md - 資産、信頼境界、攻撃者、対策

• SECURITY_REVIEW.md - レビューの観点・維持/削除マトリクス、上流監査の指摘事項

• ブラウザ;ブラウザ - ブローカー(ブラウザ?) の対象範囲と実行方法

• ceruss-broker/LEGACY_FALLBACK.md - ロールバックトリガーと移行形態

rust-broker/README.md - ブローカーの機能と実行方法 rust-broker/LEGACY_FALLBACK.md - ロールバックの誘因と切替構成

THREAT_MODEL.md と SECURITY_REVIEW.md を読んでから、大切なものが入っているブラウザにこれを向けてください。