BrowserMesh

BrowserMesh

1 つの MCP サーバーから、互いに完全に分離された多数のブラウザーセッションを同時に実行できます。

他のブラウザー MCP サーバーでは、AI クライアントが利用できるのは現在のタブを持つブラウザー 1 つだけです。BrowserMesh なら、タスクに必要な数だけ独立したセッションを利用でき、それぞれが独自の Cookie、ストレージ、認証情報を保持して並列実行されます。1 つの会話の中で、顧客として購入手続きをテストしながら、管理者セッションで注文を確認できます。どちらのセッションも、もう一方の状態を参照することはありません。

• ドキュメント
• 使い始める
• MCP ツールのリファレンス

External AI client
        |
     MCP stdio
        |
BrowserMesh runtime
   |         |         |
Session A  Session B  Session C
Context A  Context B  Context C

外部クライアントが推論と計画を行います。BrowserMesh はブラウザー操作を実行し、分離を徹底し、各セッション内の作業順序を管理して、構造化された結果を返します。

Claude Code、Claude Desktop、Codex、Cursor、Windsurf、Qwen、およびその他の MCP 対応クライアントで動作します。

BrowserMesh を使う場合と使わない場合

BrowserMesh は、汎用ブラウザー MCP サーバーのそのまま置き換えられる製品ではありません。そうしたサーバーが対応していない一つの機能を中心に構築されており、その機能には料金が発生します。

したいこと…	選ぶもの
2 つ以上のアカウント、ロール、認証状態を同時に操作する	BrowserMesh — セッションごとにコンテキストを用意し、並列で実行します
サインイン状態を維持し、後の別セッションで再利用する	BrowserMesh — browser_state_save / stateId
長いワークフロー全体で特定のタブを確実に指定する	BrowserMesh — 明示的な sessionId + pageId を使い、「現在のタブ」は使いません
ページがコンテキストをどれだけ消費するかを制限する（スナップショットのサイズ、参照、イベント）	BrowserMesh — すべての読み取りに明示的な上限があり、ページネーションに対応しています
1 人のユーザーとして 1 つのページを閲覧、クリック、読み取りする	Playwright MCP — 機能範囲が小さく、設定も少なくて済みます
ページのパフォーマンス、トレース、CDP レベルの動作をデバッグする	Chrome DevTools MCP — それを公開する MCP です
管理されたプロキシや CAPTCHA 対応を利用して、他者のクラウド上で実行する	Browserbase などのホステッドサービス — BrowserMesh はローカル専用です
ページ内で任意の JavaScript を評価する	Playwright MCP または Chrome DevTools MCP — BrowserMesh には設計上、そのようなツールがありません
Firefox または WebKit を操作する	Playwright MCP — BrowserMesh は現在 Chromium 専用です

率直に言うと、トレードオフとなるのは検出コストです。BrowserMesh は、入力と出力の両方のスキーマを完全に定義した 35 個のツールを公開しています。ある日の 1 台のマシンで計測したところ、tools/list は約 94 KB でした。一方、出力スキーマを公開していない chrome-devtools-mcp は 25 KB、@playwright/mcp は 18 KB です。クライアントのコンテキストに余裕がなく、ワークフローが 1 つのブラウザーと 1 人のユーザーで完結するなら、より小さなサーバーを選ぶのは妥当です。BrowserMesh を使いたいものの、すべての機能は必要ない場合は、--tools core で機能範囲を絞ってください。

クイックスタート

Claude Code：

claude mcp add browsermesh -- npx -y browsermesh

その他のクライアントでは、MCP 設定ファイルに次を指定します：

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

セットアップはこれだけです。BrowserMesh は初回起動時に使用する Chromium ビルドをダウンロードするため、別途インストールする必要はありません。ブラウザーを自分で管理する場合は --no-auto-install を渡してください。その場合も MCP の検出は機能し、browser_session_create は、実行するコマンドを説明する実行可能な BROWSER_ERROR を返します。

初回のダウンロードはサーバーが initialize に応答する前に行われ、Chromium ビルドのサイズは約 130 MB です。接続タイムアウトが短いクライアントでは、実行中にサーバーが失敗したと報告されます。回線が遅い場合は、サーバーを追加する前に一度ダウンロードを済ませておくと、以降の起動はすぐに完了します：

npx -y browsermesh --install-browser

次に、自然な言葉で作業を依頼します：

購入者としてチェックアウトの流れをテストし、同時に管理者として注文が表示されることを確認してください。

クライアントは各ロール用のセッションを自動的に作成します。BrowserMesh はワークフローを詳しく説明する parallel_roles プロンプトも公開しているため、クライアントはそれを直接提示できます。

プロトコルを起動せずにインストールを確認します：

npx -y browsermesh --doctor

Chromium と BrowserMesh は引き続きお使いのマシン上にあります。ホスト型の BrowserMesh サービスはありません。

接続時に、BrowserMesh は短い説明文をクライアントに送信します。セッションの指定方法やバグ報告の案内に加えて、ブラウザーのタスクとは関係のない目的で、リポジトリにスターを付けているかをエージェントに一度確認するよう求めます。この確認には、ユーザー自身の gh 認証情報を使って GitHub に認証済みの状態でアクセスします。これを条件とする機能はなく、断っても何も変わりません。確認を無効にするには --no-support-request を、説明文全体を無効にするには --no-agent-guidelines を指定してください。エージェントに使いやすいワークフロー向けに構築を参照してください。

0.2 で名称を変更しました。 npm パッケージ名は multi-agent-browser-mcp でしたが、他のすべてですでに使われていた名称に合わせて browsermesh に変更されました。args を ["-y", "browsermesh"] に変更してください。それ以外はそのままです。

v0.1 のアーキテクチャ

BrowserMesh v0.1 は意図的に小規模に設計されています。ローカルの Node.js プロセスが 1 つ、Chromium プロセスが 1 つ、準備完了したセッションごとに非永続の BrowserContext が 1 つです。

次の機能を提供します：

• 明示的なセッションおよびページ指定；
• 分離されたブラウザーコンテキストとページの所有権チェック；
• ナビゲーション、検査、操作、待機、キャプチャ、永続化；
• セッション単位の処理の直列化と、独立したセッション間での並列実行；
• 上限付きのタイムアウト、構造化されたエラー、正常なシャットダウン、リソースのクリーンアップ；
• 決定的な統合テストとエンドツーエンドテストを備えた MCP stdio 統合。

BrowserMesh はブラウザーランタイムであり、内部エージェントフレームワーク、LLM オーケストレーター、メッセージバス、Playwright のフォーク、ブラウザー GUI、対話型シェルではありません。

通常の使用方法

1. MCP 対応の AI クライアントで BrowserMesh を一度設定します。
2. クライアントが stdio 経由で BrowserMesh を起動し、そのツールを検出します。
3. ブラウザータスクを自然な言葉で説明します。
4. クライアントが必要なセッションを作成し、呼び出すツールを選択します。
5. BrowserMesh が操作を実行し、構造化された結果を返します。

ユーザー、アカウント、ロール、認証状態、または独立した並列ワークフローごとに、別々のセッションを使用してください。BrowserMesh のツールは通常、手動で呼び出すのではなく、外部クライアントが選択します。

ソースからビルドする

BrowserMesh v0.1 の対象は Node.js 24 で、サポート対象の最低メジャーバージョンとして Node.js 22 に対応しています。

リポジトリをクローンして、次を実行します：

npm install
npx playwright install chromium
npm run build

次に、ローカルでビルドしたサーバーを起動するよう MCP クライアントを設定します：

{
  "mcpServers": {
    "browsermesh": {
      "command": "node",
      "args": ["/absolute/path/to/browsermesh/dist/cli.js"]
    }
  }
}

開発時は次を実行します：

npm run verify
npm run verify:package

セッションモデル

グローバルなものはありません。

• 現在のセッション
• アクティブなセッション
• 現在のページ
• アクティブなページ
• 現在のタブ

すべてのブラウザー操作では、セッションを明示的に指定します。

ページ固有の操作では、すべてページを明示的に指定します。

概念的には次のとおりです。

browser_session_create
        │
        ▼
{
  sessionId,
  pageId
}
        │
        ▼
browser_navigate({
  sessionId,
  pageId,
  ...
})

新しく作成されたセッションには、決定論的な初期ページが1つ含まれます。

browser_session_create は初期 pageId を直ちに返すため、AI クライアントは最初のブラウザー操作の前に browser_page_list を追加で呼び出す必要がありません。

このページは browser_page_list にも表示され、isDefault としてマークされます。

セッションビューでは一貫して sessionId が公開され、ページビューでは一貫して pageId と、それを所有する sessionId が公開されます。

isDefault マーカーは情報提供のみを目的としています。ブラウザー操作では引き続き明示的な pageId を指定します。

分離

準備完了状態の BrowserMesh セッションは、それぞれ独自の非永続的な Chromium BrowserContext に対応します。

そのため、独立したセッション間では次のものを誤って共有しません。

• Cookie
• ブラウザーのストレージ／認証状態
• ページ
• ページ参照
• 現在の URL
• DOM スナップショット
• スクリーンショット
• フォームの状態

あるセッションに属する pageId を別のセッション経由で使用することはできません。

セッションをまたいだページ指定は拒否されます。

並行性モデル

各稼働中セッションには、独立した直列操作キューがあります。

同じセッションを対象とする操作は、受け付けられた順序で決定論的に実行されます。

たとえば、次のとおりです。

Session A

navigate
   ↓
snapshot
   ↓
click
   ↓
get_url

読み取り形式の操作が、進行中のナビゲーションや操作を迂回することはありません。

失敗またはタイムアウトした操作によってキューが使用不能になってはなりません。失敗した操作の処理が完了した後、受け付け済みの後続操作は通常どおり続行されます。

各 timeoutMs は、BrowserMesh が操作を受け付けた時点から開始する単一の絶対的な制限時間です。所有するセッションのキューでの待ち時間と、その後のブラウザーアダプターの各ステップはすべて同じ制限時間を消費します。アダプターステップごとに制限時間がリセットされることはありません。

MCP リクエストのキャンセルは、エンジンに依存しない操作シグナルとして BrowserMesh に伝播されます。キュー内でキャンセルされた同一セッションのリクエストは、ブラウザーの状態に影響を与える前にスキップされます。Playwright の操作がすでに実行中で、安全に中断できない場合、BrowserMesh は実際の操作が完了するまでキューの枠を保持するため、後続の処理が先行することはありません。受動的な待機では、所有する中断リスナーとタイマーが速やかに解除され、キャンセル後もセッションキューは引き続き使用できます。MCP クライアントには、使用している SDK のキャンセルエラー（通常は AbortError、またはその理由を含む MCP エラー）が通知されます。プロトコルによるキャンセル後に別途ツール結果が返される保証はありません。

異なるセッション間でグローバルな操作ロックを共有することはありません。

Session A ═════════════════════►

Session B ═════════════════════►

Session C ═════════════════════►

これにより、独立したブラウザーワークフローを並行して実行できます。

セッションの終了

セッションの終了が始まると、次の処理が行われます。

1. セッションが closing 状態になります。
2. そのセッションを対象とする新しい操作は拒否されます。
3. すでにキューに受け付けられた操作が完了するまで処理されます。
4. そのセッションのページと BrowserContext が閉じられます。
5. 稼働中のエンジンハンドルが削除されます。
6. セッションが閉じた状態になります。

既知の終了処理中／終了済みセッションを繰り返し閉じても安全で、冪等な成功結果が返されます。

完全に未知のセッション ID の場合は、引き続き SESSION_NOT_FOUND が返されます。

対応している MCP ツール

セッションとページ

• browser_runtime_info
• browser_session_create
• browser_session_list
• browser_session_get
• browser_session_close
• browser_page_create
• browser_page_list
• browser_page_close

ナビゲーション

• browser_navigate
• browser_back
• browser_forward
• browser_reload

検査

• browser_get_url
• browser_get_title
• browser_snapshot
• browser_visible_text

browser_snapshot はデフォルトでサイズが制限されており、セマンティックまたは CSS の scope、 interactiveOnly、ノードごとの maxChildren、maxDepth、includeBoundingBoxes、maxChars、 maxBytes でさらに制限できます。構造化された結果には、適用されたすべての制限、意図的なツリーの省略、 文字数と UTF-8 バイト数が報告されます。いずれかのレスポンス上限に達すると、 partial=true、truncation.truncated=true、contentFormat=aria-yaml-fragment となります。この フラグメントを完全な ARIA YAML ドキュメントとして解析しないでください。パスワードの値は引き続き マスキングされます。includeRefs=true を設定すると、直後のアクションで使える不透明なインタラクティブ要素の 参照を、最大 maxRefs 個（デフォルトは 50、上限は 100）まで取得できます。参照は 30 秒後に期限切れとなり、 厳密に一致するセッション／ページに限定されます。また、ページ遷移、DOM の置換、ページのクローズ、期限切れ、 または新しい参照スナップショットの取得後は古くなります。nextCursor が null でない場合、変更された DOM を 再読み込みせず、同じ不変のキャプチャ済みシリアライズの続きを取得します。カーソルは厳密に一致する セッション／ページに限定され、30 秒後に期限切れとなります。また、ページ遷移、ページのクローズ、クォータによる 追い出し、またはシャットダウン後は使用できなくなります。ページごとに保持されるのは、ページネーションされた スナップショット最大 4 件と、キャプチャ済みスナップショットあたり最大 1,000,000 Unicode コードポイントです。 ネイティブの ARIA シリアライズを行う前に、BrowserMesh は 20,000 DOM／テキストノードまたは 2,000,000 ソース文字を超えるスコープも拒否します。このキャプチャ前の予算は、レスポンスごとの小さい上限や 保持されるカーソルの上限とは独立して、ブラウザー側の処理量を制限します。

可観測性

• browser_observe

1 つのツールで、記録された 4 種類のソースすべてを読み取れます。source で console、pageError、 network、または requestFailed を選択します。明示的な sessionId と pageId が必要であり、 同じバッファーに読み込まれた結果を区別できるよう、source も返されます。

コンソールとページエラーの読み取りは、デフォルトではメタデータのみを返します。includeText=true を設定すると、 ベストエフォートで機密情報をマスキングした証拠を、サイズを制限して取得できます。2 つのネットワークソースには テキストが含まれないため、完全に見えるメタデータのみの結果を返す代わりに、このフラグを指定すると拒否されます。 次の非破壊的な sinceEventId チェックポイントとして nextCursor を使用します。イベントが存在しなかったと 結論づける前に、必ず gap と droppedCount を確認してください。レスポンス全体のバイト数制限を満たすため、 テキストがさらに切り詰められることがあります。その場合もイベントとそのカーソルは返されるため、 ページネーションが停止することはありません。BrowserMesh は、コンソールの引数オブジェクトや生のエラースタックを キャプチャしません。

ネットワークの読み取りで公開されるのは、関連付けられたリクエスト／レスポンス／リクエスト失敗のメタデータのみです。 これには、サイズを制限したリクエスト ID、メソッド、サニタイズされた URL、リソースタイプ、ステータス、 所要時間、および該当する場合は安全な失敗分類が含まれます。認証情報とフラグメントは削除され、 機密性の高いクエリ値は保存前にマスキングされます。ヘッダー、本文、Cookie、ストレージ、サービスワーカーの トラフィック、WebSocket、data: URL、blob: URL は除外されます。ページから発行された HTTP(S) EventSource リクエストは、通常のネットワークメタデータとして含まれます。500 などの HTTP エラーレスポンスは source: "network" に表示されます。source: "requestFailed" に表示されるのは、トランスポートレベルの失敗のみです。

0.2 より前は、これらは browser_console_list、browser_page_errors_list、 browser_network_list、browser_failed_requests_list の 4 つのツールであり、同じ コントラクトを 4 通りに公開していました。代わりに、対応する source を指定してください。

インタラクション

• browser_click
• browser_double_click
• browser_hover
• browser_focus
• browser_check
• browser_uncheck
• browser_scroll_into_view
• browser_scroll
• browser_drag_and_drop
• browser_fill
• browser_press
• browser_select_option

これらの型付き操作では、セマンティックロケーター／CSS ロケーター、または有効期間の短いスナップショット ref を正確に 1 つ指定します。操作の対象が明示され、timeoutMs による制限とキャンセルに対応しており、所有セッション内のすべてのブラウザー操作と直列化されます。check と uncheck は、要求された状態を冪等に保証します。browser_scroll では、範囲が制限された整数のピクセル増分（deltaX と deltaY は -1,000,000 から 1,000,000）を指定できます。また、ドラッグ＆ドロップでは、ソースとターゲットの両方が同じ厳密なロケーターセマンティクスで解決されます。これらのツールは、任意のページ JavaScript を実行しません。

決定論的な待機

• browser_wait
• browser_action_and_wait

browser_wait は、所有セッションのキューを通じて、型付きの受動条件を 1 つ監視します。対象となる条件は、完全一致または安全なグロブによる URL、domcontentloaded／load、ロケーターの状態、または範囲を制限したテキストの有無です。テキストの照合では、ページ本文のレンダリング済み innerText の先頭から最大 1,000,000 文字を対象に、大文字と小文字を区別して部分文字列を確認します。absent は、この範囲内の監視対象にその部分文字列が存在しないことを意味します。呼び出し元が指定する正規表現、JavaScript の述語、任意のスリープ、networkidle はサポートされません。

同じセッションで条件を満たすと予想される操作より前に、受動的な待機をキューに入れないでください。browser_action_and_wait は、型付きのナビゲーション、HTTP レスポンス、ポップアップ、またはダイアログの待機を先に登録し、その後、1 つのクリックまたはキー入力を共通の期限内に実行します。返されるレスポンス URL からは認証情報とフラグメントが除去され、一般的な機密クエリ値は伏せられます。ポップアップには、同じセッション内で isDefault=false の新しい管理対象 pageId が割り当てられます。上限を超えるポップアップは、LIMIT_EXCEEDED が返される前に閉じられます。ブロッキングダイアログは後から安全に確認できないため、ダイアログは予期される型と承認／拒否の選択肢を指定してアトミックに処理されます。プロンプトの入力と返されるダイアログメタデータには上限が設定されています。

browser_action_and_wait では、単体のインタラクションツールと同じように、セマンティックロケーター／CSS ロケーター、またはスナップショット ref を target に指定して操作を指定します。どちらの結果にもリクエストの内容は再掲されません。browser_wait は satisfied を返し、browser_action_and_wait は観測された event を返します。呼び出し元は送信した条件と操作をすでに保持しており、operationId で結果を関連付けられます。

キャプチャ

• browser_screenshot

スクリーンショットは、呼び出し元が指定したファイルシステムパスに書き込まれるのではなく、MCP の画像コンテンツとして返されます。オプションの capture モードでは、ビューポート、スクロール可能なページ全体、または厳密に解決されたセマンティック／CSS 要素のいずれかを選択できます。デフォルトはビューポートです。構造化出力には、PNG の実際の幅、高さ、エンコード済みバイト数が報告されます。BrowserMesh はキャプチャ前に CSS ピクセル単位の寸法を測定し、キャプチャ後に実際の PNG の寸法とバイト数を検証します。ページ全体モードと要素モードでは、測定時に固定されたクリップ範囲をキャプチャするため、その後ページが拡大してもネイティブの画像割り当ては増加しません。設定された上限を超えた場合は LIMIT_EXCEEDED が返され、セッションキューは損なわれません。

永続化

• browser_state_save
• browser_state_list
• browser_state_remove

browser_session_create は任意の stateId を受け付けます。

stateId を指定しない場合、新しい分離コンテキストが作成されます。

stateId を指定すると、新しいコンテキストは以前に保存された BrowserMesh の状態を使って初期化されます。

保存状態の件数、個々のサイズ、合計サイズには中央で上限が設けられています。クォータの確認とアトミックな置き換えは、すべての状態 ID にわたって直列化されます。置き換えが拒否された場合、古い状態は維持されます。既存のファイルは、JSON の解析前にサイズを確認し、厳密な上限付きで読み込まれます。

browser_session_create は、分離されたビューポート、デバイスのスケールファクター、ロケール、タイムゾーン、カラースキーム、視差効果の軽減設定、ユーザーエージェントを指定する任意の contextSettings オブジェクトも受け付けます。セッションの結果には、正規化された有効な設定が返されます。デバイス、アクセシビリティ、権限のプロファイルが異なる場合は、別々のセッションを使用してください。位置情報は任意であり、サポートされるブラウザー権限は、単一の絶対 HTTP(S) オリジンへの明示的な許可のみです。ワイルドカードや任意の権限名は拒否されます。

browser_session_create({
  name: "mobile-fr",
  contextSettings: {
    viewport: { width: 390, height: 844 },
    deviceScaleFactor: 3,
    locale: "fr-FR",
    timezoneId: "Europe/Paris",
    colorScheme: "dark",
    reducedMotion: "reduce"
  }
})

位置情報へのアクセスは、対象アプリケーションのオリジンと完全に一致する範囲に限定する必要があります。

browser_session_create({
  name: "local-map-test",
  contextSettings: {
    geolocation: { latitude: 41.3111, longitude: 69.2797, accuracy: 25 },
    permissions: [
      { permission: "geolocation", origin: "https://maps.example.test" }
    ]
  }
})

権限はそのセッションコンテキスト内で分離され、セッションの終了時に削除されます。保存されたストレージ状態に BrowserMesh の権限付与は含まれず、復元もされません。

概念的な例：

browser_session_create({
  name: "buyer",
  stateId: "buyer-auth"
})

セッションのラベル

セッションには次の項目を設定できます。

• 任意の人が読みやすい name。
• 任意の文字列メタデータ。

たとえば、外部の AI クライアントは次のようにセッションにラベルを付けられます。

role=buyer
role=seller
account=work

これらの値は、中立的なワークフローラベルにすぎません。

次のものは作成されません。

• 内部 Agent エンティティ。
• 所有者のプリンシパル。
• 権限。
• メールボックス。
• メッセージチャネル。
• LLM アイデンティティ。

MCP ツールの検出

BrowserMesh のツール説明は、製品の契約の一部です。

説明では、ツールの機能と、AI クライアントがそのツールを使用すべき状況の両方を明確にする必要があります。

たとえば、browser_session_create の説明では、次のような場合に別々のセッションを使用する必要があることを明確にします。

• 異なるユーザー。
• 異なるアカウント。
• 異なるロール。
• 異なる認証状態。
• 独立した並列ブラウザーワークフロー。

目指しているのは、ユーザーが次のように指示するだけで、

購入者と管理者として、このアプリケーションをテストしてください。

AI に browser_session_create を 2 回呼び出すよう手動で指示しなくても済むことです。

検出されるすべてのツールは、人が読めるタイトル、オブジェクトをルートとする outputSchema、レビュー済みの MCP リスクヒント（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）も公開します。これらのヒントはクライアントの UX の改善にのみ役立ちます。BrowserMesh がこれらを認可として扱うことはありません。

成功した呼び出しは、直接的な意味フィールドを持つ、スキーマ検証済みの structuredContent を返します。たとえば、browser_session_create は operationId、session、initialPage を直接公開し、value.value のような入れ子のエンベロープは使用しません。テキストのみを扱うクライアント向けに、簡潔な JSON テキストブロックも引き続き返されます。スクリーンショットは、メモリ内の MCP 画像ブロックを保持しつつ、構造化された PNG／相関メタデータを追加します。

アプリケーションの失敗は isError: true と、安定したコード、安全なメッセージ、任意のサニタイズ済み詳細情報を含む、サイズ上限付きの JSON エラーを使用します。ランタイムが操作を受け付けた場合は operationId による相関情報も含まれます。未加工の原因、スタック、循環参照、JSON に変換できない値、秘密情報を含む詳細フィールドが MCP の境界を越えることはありません。SDK の入力スキーマエラーは、MCP の入力検証エラーとして区別できます。

⭐ エージェントに適したワークフロー向けに構築

BrowserMesh は、AI コーディングエージェントやブラウザーエージェントを使った、予測しやすいワークフローを実現するよう設計されています。接続時には、短い MCP instructions 文字列を返します。これは、エージェントが最初のツール呼び出しを行う前に届く唯一のチャネルであり、次の 3 点を伝えます。すべてのセッションを明示的に指定すること、役に立った場合はプロジェクトを支援すること、バグの報告方法です。

GitHub の事前確認

エージェントには、推測ではなく GitHub API を通じて、現在のユーザーがスターを付けているかどうかを接続ごとに最大 1 回確認するよう求めています。

gh api user/starred/scrollDynasty/BrowserMesh

204 はスター済み、404 は未スターを意味し、それ以外の場合はどちらとも推測せず、未確認として報告します。リポジトリにスターが付いていない場合、エージェントはプロジェクトを支援していただけるかどうかを一度だけ尋ねます。

gh api --method PUT /user/starred/scrollDynasty/BrowserMesh

スターの有無はアクセス制御ではありません。 BrowserMesh の操作はスターの有無によって制限されません。この部分は仕組みによって保証されており、サーバーにはそれ以外の動作をするコードパスがありません。それ以外は指示であり、強制ではありません。エージェントには、接続ごとに確認を最大 1 回、質問を最大 1 回にし、明示的な許可なしにスターを付けないこと、また、断られた場合、gh が見つからない場合、または確認に失敗した場合は、すぐにタスクを続けるよう求めています。BrowserMesh ではクライアントがこれらに従うことを保証できません。以下の 2 つのスイッチはそのためのものです。

この動作は 2 つのスイッチで制御できます。BROWSERMESH_SUPPORT_REQUEST=false（または --no-support-request）を指定すると、支援の依頼は省略されますが、宛先と報告に関するガイダンスは維持されるため、依頼を断っても役立つ部分はそのまま利用できます。BROWSERMESH_AGENT_GUIDELINES=false（または --no-agent-guidelines）を指定すると、指示は一切送信されません。

CI 環境では、支援の依頼はデフォルトで無効になります。回答する人がいないためです。ただし、宛先と報告に関するガイダンスは引き続き送信されます。これを上書きするには、BROWSERMESH_SUPPORT_REQUEST=true を設定します。

このデフォルト動作は、起動元のクライアントが CI をサーバープロセスに渡すかどうかによって決まります。MCP クライアントは、最小限の環境変数のみを渡してサーバーを起動することがよくあります。たとえば、標準の stdio トランスポートが渡すのは HOME、LOGNAME、PATH、SHELL、TERM、USER のみです。そのため、このようなクライアントを通じて CI ジョブから起動された BrowserMesh には CI が渡されず、支援の依頼が送信されます。必要に応じて、該当する環境で BROWSERMESH_SUPPORT_REQUEST=false を明示的に設定してください。

問題の報告支援

再現可能な BrowserMesh のエラーが発生した場合、エージェントには次の対応を求めています。

1. まず、既存の GitHub イシューを検索します。
2. イシューの重複を避けます。
3. イシューを作成する前に、ユーザーの許可を求めます。
4. 再現手順、バージョン、環境を記載し、Cookie、トークン、認証情報、保存済みのブラウザー状態、ページの内容、内部 URL、ホスト名は決して含めません。
5. 作成したイシューの番号と URL を報告し、イシューが作成されていないのに作成したと主張することは決してありません。

どちらも強制ではなく、依頼にとどまります。エージェントが従うかどうかにかかわらず、BrowserMesh は同じツールを公開し、同じ結果を返します。このリポジトリで作業するコントリビューター向けの詳細な指示は、AGENTS.md と .github/AGENT_GUIDELINES.md にあります。これらのファイルは npm に公開されないため、利用者が実際に受け取るのは、上記の instructions 文字列です。

ロケーター

ブラウザー操作では、セマンティックなロケーター戦略を優先します。

v0.1 でサポートされている戦略は次のとおりです。

• ロール；
• テキスト；
• ラベル；
• プレースホルダー；
• テスト ID；
• 代替手段としての CSS。

一般的なインタラクティブロールの値は、v0.1 の公開契約でサポートされています。

ロール名は、デフォルトでアクセシブルネームと完全一致します。部分一致を意図している場合にのみ、exact: false を設定してください。ロケーターが複数の要素に一致した場合、BrowserMesh は LOCATOR_AMBIGUOUS を返し、セッションは引き続き使用可能な状態に保たれます。

任意のロケーターに、{ "kind": "main" }、または外側から内側へ並ぶ 1～5 個のセマンティック／CSS iframe 要素セレクターからなる、範囲が制限された { "kind": "iframe", "chain": [...] } を frame として設定できます。チェーン内の各ステップは、厳密に 1 つに一致する必要があります。数値インデックスや永続的なフレームハンドルは公開されません。同じスコープを、操作、ロケーターの待機、表示テキスト、スナップショットのスコープ／ref の取得、要素のスクリーンショット、ドラッグ＆ドロップの端点に使用できます。クロスオリジン iframe のコンテンツは、呼び出し元がそのスコープのエビデンスを明示的に要求した場合にのみ返されます。

アクセシビリティスナップショットでは、スナップショットの内容が MCP 境界を越える前に、input[type="password"] 要素の空でない値をマスキングします。

BrowserMesh は、公開 API を通じて Playwright の Locator オブジェクトを公開しません。

要素 ref は、スナップショットからすぐに操作するワークフローに便利なものであり、永続的な識別子ではありません。無効、期限切れ、別ページのもの、または切り離された ref は STALE_ELEMENT_REFERENCE を返します。永続的なテストでは、引き続きセマンティックロケーターが推奨されます。BrowserMesh は、非公開の Playwright AI/ref セレクターを使用せず、アダプターが所有する要素ハンドルも公開しません。

永続化と機密状態

BrowserMesh は、ローカルの永続化データをデフォルトで次の場所に保存します。

.browsermesh/

保存されたブラウザー状態には、認証情報や、それに相当する機密性の高いブラウザー状態が含まれる場合があります。

そのため、次の点に従ってください。

• .browsermesh/ は Git の追跡対象外です；
• 保存された状態をコミットしてはいけません；
• 保存された状態を公開してはいけません；
• ログにストレージ状態の内容を含めてはいけません；
• 呼び出し元は任意のファイルシステムパスではなく、論理状態 ID を指定します。

永続化の対象は、シリアライズされたブラウザーストレージ／認証状態です。

BrowserMesh は、稼働中の BrowserContext、開いているページ、保留中の操作、稼働中のブラウザープロセスの状態をシリアライズしようとはしません。

設定

環境変数	デフォルト	意味
BROWSERMESH_TIMEOUT_MS	10000	操作のデフォルトタイムアウト（上限付き）
BROWSERMESH_DATA_DIR	~/.browsermesh	ローカルの非公開データディレクトリ
BROWSERMESH_LOG_LEVEL	info	debug、info、warn、error、または silent
BROWSERMESH_MAX_SESSIONS	50	アクティブなセッションの上限
BROWSERMESH_MAX_PAGES	20	セッションごとに管理するページ数
BROWSERMESH_PERSISTENCE	true	保存したブラウザー状態を有効にする
BROWSERMESH_HEADLESS	false	表示ウィンドウなしで Chromium を起動する
BROWSERMESH_SCHEMA_REFS	true	繰り返されるサブスキーマを $defs／$ref で共有する
BROWSERMESH_AUTO_INSTALL	true	Chromium がない場合、初回起動時にダウンロードする
BROWSERMESH_TOOLS	(all)	公開するツールプロファイル（カンマ区切り）
BROWSERMESH_AGENT_GUIDELINES	true	接続時に MCP の指示文字列を送信する
BROWSERMESH_SUPPORT_REQUEST	true (attended)	オープンソースのサポート依頼を含める。CI では無効
BROWSERMESH_OBSERVABILITY_EVENTS	200	ページごとに保持する各種オブザーバビリティイベント数
BROWSERMESH_OBSERVABILITY_STRING_CHARS	2048	公開するイベント文字列の最大長
BROWSERMESH_OBSERVABILITY_PAGE_SIZE	100	1 回の読み取りで返すイベントの最大数
BROWSERMESH_OBSERVABILITY_RESPONSE_BYTES	65536	オブザーバビリティレスポンスのシリアライズ後の最大サイズ
BROWSERMESH_SCREENSHOT_MAX_DIMENSION	10000	PNG の幅または高さの最大値（CSS ピクセル単位）
BROWSERMESH_SCREENSHOT_MAX_PIXELS	40000000	PNG の総ピクセル数の上限
BROWSERMESH_SCREENSHOT_MAX_BYTES	16777216	エンコード後の PNG の最大バイト数
BROWSERMESH_VISIBLE_TEXT_MAX_CHARS	20000	返される Unicode コードポイントの最大数
BROWSERMESH_VISIBLE_TEXT_MAX_BYTES	65536	返される可視テキストの UTF-8 最大バイト数
BROWSERMESH_MAX_SAVED_STATES	100	永続化する論理状態の最大数
BROWSERMESH_MAX_STATE_BYTES	1048576	1 つの永続化状態の最大バイト数
BROWSERMESH_MAX_STATE_TOTAL_BYTES	16777216	永続化状態の合計最大バイト数

コマンドラインで指定できるオプションは、--headless、--headed、--timeout、--data-dir、 --log-level、--max-sessions、--max-pages、--tools、--no-persistence、--no-schema-refs、 --no-auto-install、--no-agent-guidelines、--no-support-request です。各オプションは、対応する上記の環境変数を設定し、コマンド ラインの指定が優先されます。残りの変数（オブザーバビリティ、スクリーンショット、可視テキスト、永続化の 上限）は、環境変数でのみ設定できます。現在の一覧は browsermesh --help で確認してください。不正な値が 指定された場合は、その値の設定元の環境変数名を示し、スタック トレースを出力せずにステータス 2 で終了します。 保存状態は作業ディレクトリではなく、ユーザーのホームディレクトリに保存されます。MCP クライアントは、その時点でどのディレクトリにいても BrowserMesh を起動するため、相対パスのデフォルト設定では、保存された認証情報が無関係な複数のフォルダーに分散し、目に見える理由もなく browser_state_list が空になることがありました。以前のプロジェクト単位の動作に戻すには、--data-dir .browsermesh を指定してください。

設定は一元的に読み込まれ、検証されます。

公開するツールを絞り込む

ツールの検出には、すべてのクライアントでセッションごとに一度、コンテキストを消費します。--tools を指定すると、BrowserMesh が公開するツールを、ワークフローで実際に必要なプロファイルに絞り込めます。

プロファイル	ツール数	内容
core	31	セッション、ページ、ナビゲーション、読み取り、操作、待機、キャプチャー
observability	1	browser_observe
persistence	3	browser_state_save、browser_state_list、browser_state_remove

--tools を省略すると、すべてのプロファイルが公開されるため、既存の設定で利用できたツールは引き続き使用できます。

npx -y browsermesh --tools core,persistence

公開されるスキーマでは、繰り返し使われるサブスキーマを $defs／$ref で共有しています。これは、すべての JSON Schema 2020-12 バリデーターで解決できます。バリデーターが対応していないクライアントでは、--no-schema-refs を設定してください。

プロンプトとリソース

BrowserMesh は 2 つの MCP プロンプトを公開しているため、クライアントはワークフローを推測するのではなく、提示できます。

• parallel_roles — 1 つのタスクを、分離されたセッションをそれぞれ使う複数のロールとして同時に実行します。
• diagnose_page — ページを読み込み、そのページに関するコンソール、ページエラー、ネットワークの証拠を収集します。

また、読み取り専用リソース browsermesh://sessions を 1 つ公開します。このリソースには、ランタイムが現在保持しているセッションと、そのステータスおよびラベルが一覧表示されます。

どちらも静的なテンプレートです。BrowserMesh はテキストを生成して返すだけで、LLM の呼び出しは行わず、クライアントごとの状態も保持しません。推論を行い、呼び出すツールを決定するのは引き続きクライアントです。

BrowserMesh は、ユーザーがブラウザーの自動化を確認できるよう、デフォルトで Chromium をヘッドモードで起動します。CI、サーバー、その他ディスプレイのない環境では、BROWSERMESH_HEADLESS=true を設定してください。受け付ける値は文字列どおりの true と false のみです。無効な値の場合は、黙って無視されるのではなく、設定エラーになります。どちらのモードでもブラウザーの起動は遅延されるため、Chromium がまだインストールされていなくても、MCP の検出と、実行可能なセットアップエラーの提示は引き続き利用できます。設定された BROWSERMESH_TIMEOUT_MS はブラウザーの起動時間にも適用されます。安全なデフォルトより長くかかることが想定される操作に限り、ツールごとに大きな timeoutMs を設定してください。

セッションラベルには、ランタイムを直接呼び出す場合にも上限があります。名前は Unicode コードポイントで最大 128 文字、メタデータは最大 32 項目です。また、キーと値には文字数、UTF-8 バイト数、合計バイト数の上限があります。BrowserMesh がセッション ID、コンテキスト、ページを割り当てる前に、制御文字と危険なオブジェクトキーは拒否されます。browser_visible_text は text フィールドをそのまま保持し、切り詰めに関する明示的なメタデータを追加します。これによりクライアントは、証拠が完全なものか、上限に合わせた先頭部分かを判別できます。

コードベース全体で process.env に直接アクセスすることは禁止されています。

browser_runtime_info は、セッションを作成する前でも安全に呼び出せます。BrowserMesh、Node、解決済みの Playwright の正確なバージョン、有効な設定と制限、ブラウザーの起動状態、稼働中の Chromium のバージョン（取得できない場合は null）、およびアクティブなセッション数と失敗したセッション数を報告します。Chromium は起動せず、パス、環境変数の値、ブラウザーの状態、生のエラー情報も公開しません。

ログ

MCP の stdio では、stdout はプロトコル通信専用です。

そのため、BrowserMesh の構造化ログは stderr に出力されます。

ログには、次のような安全な相関情報を含めることができます。

• operationId；
• sessionId；
• pageId；
• ツール／操作名；
• 所要時間；
• 安全なエラーコード。

ログには、次の情報を含めてはいけません。

• Cookie；
• トークン；
• 保存状態；
• ページの内容；
• スクリーンショット；
• フォームの値；
• パスワード；
• 任意のメッセージペイロード。

Chromium の切断時の動作

Chromium が予期せず切断されても、BrowserMesh はライブセッションを暗黙的に再構築しません。

影響を受けたセッションは失敗状態に移行し、ライブハンドルは無効になります。

既存のセッションを暗黙的に再作成することはありません。これは BrowserMesh の状態保証に反するためです。

ランタイムが安全に復旧できる場合、新しく作成されるセッション用に新しい Chromium プロセスを起動することはできますが、既存のライブセッションは失敗状態のままです。

開発

npm run typecheck
npm run lint
npm run format:check
npm test
npm run test:integration
npm run test:e2e
npm run test:stress
npm run test:coverage
npm run build
npm run verify

ブラウザー統合／E2E テストでは、実際の Chromium と決定論的なループバック HTTP テストサーバーを併用します。

テストは公開 Web サイトに依存しません。

以下を参照してください。

• 技術仕様
• アーキテクチャ
• 開発
• コントリビューション
• リリースプロセス
• セキュリティポリシー
• アーキテクチャ上の決定

プルリクエストのタイトルには Conventional Commits を適用します。すべての PR は、完全なテストマトリックス、パッケージインストールのスモークテスト、セマンティックタイトルの検証、CodeQL によるチェックを受けます。リリースは Release Please で準備し、生成された Release PR がメンテナーによってマージされた後に限り、GitHub OIDC 経由で npm に公開します。

BrowserMesh は Apache License 2.0 の下で配布されます。

意図的に設けられた v0.1 の制限事項

BrowserMesh v0.1 には、意図的に以下の機能を含めていません。

• Firefox／WebKit との同等性；
• リモートの Streamable HTTP；
• BrowserMesh がホストするクラウドインフラストラクチャ；
• マルチテナント認証；
• 分散型ブラウザーワーカー；
• 実行中の操作のクラッシュ復旧；
• 内部 Agent エンティティ；
• LLM エージェントに紐づく内部セッション所有権；
• Agent レジストリ；
• メールボックス；
• エージェント間メッセージング；
• 内部 LLM 呼び出し；
• プロンプトのオーケストレーション；
• Claude／Codex／Qwen のプロセス起動；
• 任意のシェル実行；
• 任意のファイルシステム読み取り；
• 呼び出し元が制御するスクリーンショットのパス；
• ダウンロード；
• Web ダッシュボード；
• ネットワークの許可リスト；
• Playwright API の完全な実装。

実際のマルチクライアント保護に必要となった場合は、将来的に汎用的なクライアント／ワークフローリースを導入することがあります。

このようなリースは、LLM／Agent の抽象化とは独立している必要があります。

v0.1 の中核的な保証

1 つの BrowserMesh ランタイム内では、次のことが保証されます。

• セッションは明示的に指定されます；
• ページは明示的に指定されます；
• 各セッションには分離されたブラウザーコンテキストがあります；
• 異なるセッションは並行して実行できます；
• 1 つのセッションを対象とする操作は、そのセッションのキューを通じて決定論的に実行されます；
• エラーが発生しても、後続のキュー内操作に影響しません；
• 永続化状態は、制御された論理識別子を通じて扱われます；
• シャットダウン時にライブブラウザーリソースがクリーンアップされます；
• BrowserMesh はブラウザー処理を実行し、推論はランタイムの外部に置かれます。