アーキテクチャ¶

実行時間¶

cloakbrowser-mcp は、stdio または Streamable HTTP を公開できる外部 MCP サーバーです。起動時には、以下の処理を行います：

CloakBrowser Chromium バイナリを解決またはインストールします。
一時的な Playwright MCP 設定ファイルを作成します。
アップストリームの @playwright/mcp を、stdio 経由で子プロセスとして起動します。
MCP SDK クライアントトランスポートを使用して、その子プロセスに接続します；
選択されたトランスポートを介して、ユーザーの MCP クライアントに対して外部 MCP サーバーを公開します；
アップストリームのツールリストおよびツール呼び出しを、変更せずに転送します；
cloakbrowser_binary_info および cloakbrowser_bridge_info を追加します。

このデザインを選んだ理由¶

上流のPlaywright MCPプロジェクトは、すでにブラウザツール用の契約を保有しており、急速に進化しています。このブリッジモデルにより、本プロジェクトの規模を小さく抑え、ブラウザ自動化ロジックの複製を回避しています。

管理された CDP の所有権¶

管理された CDP は、同じブラウザ世代向けのオプションのセカンドコントロールサーフェスです:

MCP client -> outer bridge -> upstream Playwright MCP child -> Chromium
                    |                    |                    |-- Playwright pipe
                    |                    `-- generated config `-- internal loopback CDP
                    `-- external capability proxy <--------- CDP client

MCP セッションは、外部ポートリース、ケーパビリティプロキシ、上流で生成されたものを所有しています構成、交換可能な上流の子、および現在の Chromium 世代。CDP クライアントは内部ループバックエンドポイントに直接接続することはありません。ブートストラップは配置します MCPを通しての一度きりのブラウザページチャレンジを行い、それをCDPを通して消費します。外部機能が公開されています。Playwright の内部リモートデバッグパイプは残っていますブリッジ管理のTCPエンドポイントと並行してアクティブです。

外部ポートのリースはMCPセッションでは安定していますが、子プロセスは、内部エンドポイント、世代番号、および能力 URL は置き換え可能です。ブラウザ損失は現在の機能を無効にし、そのプロキシされたソケットを閉じますが、…しませんバックグラウンドで子プロセスを開始します。最初の後のbrowser_* MCP呼び出しが適用されます前方進行前に再起動するルール：

同時に行われるブラウザの呼び出しは、1つの制限された再起動を共有します；
古い子供は到達不可能になり、破棄されます；
置き換え子は、同じセッション構成と新しい内部ポートを使用します；
公開前に所有権と外部の準備状況が確認されます；
待機中のブラウザ呼び出しは、それぞれ正確に1回だけ準備ができている置き換えに転送されます。

もし準備ができていなければ、待機しているブラウザの呼び出しは上流の子に届かず、能力もありません公開され、後のブラウザ呼び出しで新しい制限付きの試行が開始される場合があります。ブラウザの状態タブやメモリ内ストレージのようなものは、交換時に復元されません。ローカルツール、ツールの一覧表示、ディスカバリー読み取り、および通常のCDPの切断では再起動はトリガーされません。

クリーンアップは到達可能性を逆転させます：アクセスを停止し、権限を無効化し、プロキシを閉じますソケット、上流の子とブラウザを破棄し、外部リスナーを閉じて、次にポートリースを解放します。これにより、古い URL が新しいブラウザに静かに移動するのを防ぎます。

MCP および CDP コマンドは同時に実行される可能性があります。ブリッジはプロトコル間変換を追加しませんトランザクションまたはどの呼び出し元がページを所有しているかを推測すること；呼び出し元は破壊的な処理を調整する必要がある相反する操作。

Docker¶

この Docker イメージは、ピン留めされた公式の Playwright MCP イメージをベースイメージとして使用しています。ブリッジは /opt/cloakbrowser-mcp の下にインストールされますが、上流の Playwright MCP は /app/cli.jsで引き続き利用可能です。

設定¶

このブリッジは、CloakBrowserの起動オプションを含む一時的なJSON設定を書き込みます。アップストリームの PLAYWRIGHT_MCP_* 環境変数は、引き続きアップストリームのPlaywright MCPに転送されます。

輸送¶

デフォルトのトランスポートは stdio です。ストリーム可能なHTTPは、--transport streamable-http または CLOAK_PLAYWRIGHT_MCP_TRANSPORT=streamable-http によって明示的に有効化されます。

stdioの場合、1つの外部サーバーが1つのアップストリームPlaywright MCP子プロセスを所有し、アップストリームPlaywright MCPのデフォルトのプロファイル動作を維持します。 Streamable HTTPの場合、各MCPセッションは、独自の外部サーバー、アップストリームの子プロセス、生成された設定、およびメモリ内のトランスポート状態を保持します。HTTPセッションは、隔離されたブラウザプロファイルを使用してアップストリームのPlaywright MCPを起動するため、同時接続ユーザー間で同じ永続的なChromiumプロファイルを共有したり、競合したりすることはありません。

このセッションバックエンドはメタデータのみを保存します。組み込みのバックエンドは memory です。将来実装される Redis、Postgres、または SQLite アダプタは、メタデータとロックの調整を行うことはできますが、所有するサーバープロセスが終了した後、稼働中のアップストリームブラウザプロセスを復元することはできません。水平スケーリングでは、mcp-session-idをキーとするスティッキーセッションを使用する必要があります。

このブリッジは、Streamable HTTP 向けに MCP SDK StreamableHTTPServerTransport を使用しています。非推奨となった MCP SSEServerTransportやレガシーな /sse エンドポイントは公開していません。