コンテンツにスキップ

設定

Playwright MCP の動作には、アップストリームの PLAYWRIGHT_MCP_* 変数を使用してください。 CLOAK_PLAYWRIGHT_MCP_* は、Cloak 固有のブリッジ動作にのみ使用してください。

旧式の CLOAKBROWSER_MCP_* 変数はサポートされていません。 生成された CLI リファレンス は、ブリッジ CLI フラグとそれに対応する環境変数の公式リストです。

ブリッジのオプション

変数 既定値 説明
CLOAK_PLAYWRIGHT_MCP_TRANSPORT stdio ブリッジの通信方式:stdio または streamable-http。
CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL http Streamable HTTP リスナーのプロトコル:http または https。
CLOAK_PLAYWRIGHT_MCP_HTTP_HOST 127.0.0.1 Streamable HTTP リスナーのバインド先ホスト。
CLOAK_PLAYWRIGHT_MCP_HTTP_PORT 3000 Streamable HTTP リスナーのバインド先ポート。テストでは 0 を指定して一時ポートを割り当てられます。
CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINT /mcp Streamable HTTP エンドポイントのパス。/healthz と /readyz はプローブ用に予約されています。
CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN unset 任意の Bearer トークン。設定すると、Streamable HTTP リクエストでこのトークンが必須になります。
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_BACKEND memory セッションメタデータのバックエンド。このリリースでは memory のみ実装されています。
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_IDLE_TTL_MS 3600000 Streamable HTTP セッションのアイドル有効期間。期限切れのセッションでは、ブリッジのリソースを解放して上流子プロセスを終了します。
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_MAX 32 1 プロセス内のアクティブな Streamable HTTP セッションの最大数。
CLOAK_PLAYWRIGHT_MCP_HTTPS_CERT unset Streamable HTTP で HTTPS を使用する際の TLS 証明書 PEM ファイルのパス。
CLOAK_PLAYWRIGHT_MCP_HTTPS_KEY unset Streamable HTTP で HTTPS を使用する際の TLS 秘密鍵 PEM ファイルのパス。
CLOAK_PLAYWRIGHT_MCP_HTTPS_PFX unset Streamable HTTP で HTTPS を使用する際の TLS PFX/PKCS12 ファイルのパス。
CLOAK_PLAYWRIGHT_MCP_HTTPS_PASSPHRASE unset 暗号化された HTTPS 秘密鍵または PFX ファイルのパスフレーズ。
CLOAK_PLAYWRIGHT_MCP_LOG_LEVEL info Streamable HTTP の運用ログレベル:trace、debug、info、warn、error、fatal または silent。
PLAYWRIGHT_MCP_PROXY_SERVER unset 上流 Playwright MCP のプロキシサーバー。位置の照合を有効にすると、GeoIP 情報の取得元として使用します。
PLAYWRIGHT_MCP_PROXY_BYPASS unset PLAYWRIGHT_MCP_PROXY_SERVER を使用しないホストを指定する、上流プロキシの除外リスト。
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH false PLAYWRIGHT_MCP_PROXY_SERVER の GeoIP 情報を取得し、CloakBrowser のタイムゾーンとロケールのフィンガープリント引数をプロキシの所在地に合わせます。
CLOAK_PLAYWRIGHT_MCP_HUMANIZE false CloakBrowser の人間らしいマウス、キーボード、スクロール動作を有効にします。
CLOAK_PLAYWRIGHT_MCP_HUMAN_PRESET default CloakBrowser の人間らしい動作のプリセット:default または careful。humanize が有効な場合のみ使用します。
CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL stable CloakBrowser バイナリのリリースチャネル: stable または Pro 限定の preview。
CLOAKBROWSER_BINARY_PATH unset カスタム CloakBrowser 実行ファイルへのパス。CLI オプション --binary-path が優先されます。
CLOAKBROWSER_VERSION unset カスタム実行ファイルを選択しない場合に CloakBrowser のキャッシュ解決へ渡す固定バージョン。有効な無料プランのライセンスキーでは固定値が無視され、キャッシュ済みのバイナリを再利用する場合があります。
PLAYWRIGHT_MCP_BROWSER_ENGINE cloak cloak は CloakBrowser バイナリを使用します。playwright は Cloak 固有の実行ファイル置換を省略します。
PLAYWRIGHT_MCP_HEADLESS true Chromium をヘッドレスモードで実行します。
PLAYWRIGHT_MCP_OUTPUT_DIR .playwright-mcp npm 実行時の成果物ディレクトリ。Docker では /data に設定します。
PLAYWRIGHT_MCP_CODEGEN typescript コード生成の対象言語: typescript、python、java、csharp、または none。ブリッジは値を検証し、生成する Playwright MCP 設定の codegen に書き込みます。
PLAYWRIGHT_MCP_SNAPSHOT_BOXES false true または false。スナップショットに各要素の境界ボックスを [box=x,y,width,height] として含めます。ブリッジは値を検証し、生成する Playwright MCP 設定の snapshot.boxes に書き込みます。
PLAYWRIGHT_MCP_TIMEOUT_SETTLE 500 アクション後、発生した処理が安定するまで待機する上流の時間(ミリ秒)。Playwright MCP に直接転送されます。
PLAYWRIGHT_MCP_TIMEOUT_ACTION 5000 操作の既定タイムアウト。単位はミリ秒です。
PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION 60000 ナビゲーションの既定タイムアウト。単位はミリ秒です。
PLAYWRIGHT_MCP_VIEWPORT_SIZE upstream default WIDTHxHEIGHT 形式のブラウザビューポートサイズ。
PLAYWRIGHT_MCP_USER_DATA_DIR unset 永続的な Chromium プロファイルディレクトリ。ブリッジは絶対パスに解決し、存在しない場合は作成し、書き込み可能であることを確認して、生成された browser.userDataDir に書き込みます。
CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS unset 検証済みのコンテキストオプションを含む JSON オブジェクト。サポートされるフィールドは下記に記載されています。
CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS unset 既存の Chrome 拡張機能ディレクトリの JSON 配列またはカンマ区切りリスト。PLAYWRIGHT_MCP_USER_DATA_DIR が必要です。Windows パスやカンマを含むパスには JSON 配列を使用してください。
CLOAK_PLAYWRIGHT_MCP_CONSOLE_FALLBACK true コンソールメッセージの互換性パッチを有効にします。
CLOAK_PLAYWRIGHT_MCP_STEALTH_ARGS true CloakBrowser の既定のステルス起動引数を追加します。
CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS unset 追加の Chromium 引数。カンマ区切りのリストまたは JSON 配列で指定します。
CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX true --no-sandbox を追加し、Chromium のサンドボックスを無効にします。

管理された CDP

管理された Chrome DevTools Protocol (CDP) へのアクセスは、明示的なオプトインです。それは以下を公開します MCPによって能力を持つものを通して制御された同じChromiumブラウザ世代 discovery URL。ポートプールを設定するだけでは、CDPは有効になりません。

CLI オプション 環境変数 デフォルト 目的
--cdp-enabled、--no-cdp-enabled CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED false stdioの値とStreamable HTTPセッションのデフォルトを設定します。
--cdp-port-range <port\|start-end> CLOAK_PLAYWRIGHT_MCP_CDP_PORT_RANGE 未設定 プロセスローカルの外部プロキシポートプールを構成します。1つの有効なセッションが1つのポートをリースします。
--cdp-host <host> CLOAK_PLAYWRIGHT_MCP_CDP_HOST 127.0.0.1 管理された CDP プロキシをバインドします。
--cdp-allow-remote、--no-cdp-allow-remote CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE false ループバックでないバインドを許可または拒否する。
--cdp-advertised-host <host> CLOAK_PLAYWRIGHT_MCP_CDP_ADVERTISED_HOST 未設定 ディスカバリーURLに外部から到達可能な具体的なホストを設定してください。ワイルドカードバインドには必須です。
--cdp-advertised-scheme <http\|https> CLOAK_PLAYWRIGHT_MCP_CDP_ADVERTISED_SCHEME http http/ws または https/wss の URL を公開します。これは TLS を有効にしません。

各 CLI の値は、対応する環境変数だけを上書きします。特に、 --no-cdp-enabled は CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true を上書きし、そして --no-cdp-allow-remote は CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true を上書きします。 ポートプールなしで有効になったセッションは、上流の子が開始する前に拒否されます。 効果的な偽の値は、リスナー、ポートリース、または機能を作成しません。

stdioの場合、プロセス値は直接適用されます:

cloakbrowser-mcp \
  --cdp-enabled \
  --cdp-port-range 9222

認証された中で、Streamable HTTP のために、平坦な cdpEnabled ブール値 initialize メタデータは、そのセッションのプロセスデフォルトを上書きします。省略すると フィールドはプロセスの値を継承します。これらの例は、1つのセッションを明示的に選択しています。そして 別のアウト:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": true
      }
    }
  }
}
{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": false
      }
    }
  }
}

一つの CDP 対応 HTTP セッションは、一つの外部ポートリースを所有します。無効化されたセッションは所有しません プールを消費します。割り当てはプロセスごとで、最も低い未リースの候補を選択します。 そして、選択された外部ポートがすでに使用されている場合、そのセッションを直ちに失敗させます。 セッションを閉じてポートを解放するか、プールが枯渇したときにより大きな範囲を設定してください。

cloakbrowser_bridge_info から現在の URL を取得し、それを渡します structuredContent.cdp.discoveryUrl を Playwright のような CDP クライアントに chromium.connectOverCDP()。URLを資格情報として扱ってください:それにはランダムなものが含まれています 世代ごとの機能であり、ブラウザの交換後に古くなります。管理された CDP は Playwright サーバーのエンドポイントではありません。chromium.connect() と現在の Open WebUI PLAYWRIGHT_WS_URL フローはサポートされていません。

--cdp-advertised-scheme https は https の発見と wss WebSocket のURLを公開します のみ。このブリッジは管理対象CDPに対してTLSを提供しません:その外部リスナーと Chromium ホップはプレーンテキスト HTTP/WebSocket のままです。オペレーター所有の TLS 終端装置が必要です 同じ広告されたリースポートで待ち受け、広告された Host と Origin を保持する 権限を持ち、そのセッションの平文リスナーに1対1で転送します。

CDP の有効化は、MCP の初期化中に Chromium で開始されるため、所有権および外部 準備状況を確認できます。MCPクライアントの初期化タイムアウトを少なくとも60に設定してください 秒。CDP が有効になっている場合、ユーザー提供の CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS は --remote-debugging-port を含んではいけません。 --remote-debugging-address、または --remote-debugging-pipe(= 形式を含む)。 Playwrightの独自の内部--remote-debugging-pipeは、〜と並行して有効のままです ブリッジ管理のループバックTCPエンドポイント。

こちらを参照してください ツール、Docker、 セキュリティ、そして 発見状態、展開のためのアーキテクチャ、 制限、および再起動の動作。

CloakBrowser ライセンスと GitHub サインイン

ライセンスの設定にはアップストリームの CloakBrowser CLI を使用します。 cloakbrowser-mcp がログインまたはログアウトのコマンドを追加することはありません。

npx -y cloakbrowser@latest login
npx -y cloakbrowser@latest info
npx -y cloakbrowser@latest logout

login は有料キーを受け取るか、無料枠のキーを取得するための GitHub サインインを開始します。検証済みのキーは ~/.cloakbrowser/license.key に保存され、logout はそのファイルを削除します。info は有効なライセンス階層を 表示し、Pro ライセンスの場合はアクティブなセッション数も表示します。

代わりに、MCP サーバーの環境で CLOAKBROWSER_LICENSE_KEY を設定できます。 ブリッジはその値をログに記録せず、アップストリーム/ブラウザの子プロセスに転送します。 CLOAKBROWSER_CACHE_DIR が license.key を含むカスタムキャッシュを指している場合、 CloakBrowser がキーを解決し、ブリッジは生成されたブラウザ環境からその解決済みキー だけを転送します。生成されたその他の環境エントリはコピーされません。

指定したライセンスキーを CloakBrowser が拒否するか、ライセンスサーバーとキャッシュ済みの検証結果のいずれでも検証できない場合、起動は明示的な CloakBrowser エラーで失敗します。ブリッジはエラーを保持し、隠したり別のブラウザやライセンス階層へ黙って切り替えたりしません。

ライセンスサーバーが利用できない場合、CloakBrowser はキャッシュ済みの検証結果を再利用できます。ただし、オフライン起動は保証されません。バイナリのダウンロードやブラウザの起動は失敗する可能性があります。

CloakBrowser リリースチャネル

CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL は CloakBrowser バイナリのリリースチャネルを選択します。既定値は stable です。preview は Pro ブラウザのプレビュービルドを要求し、Pro ライセンスでのみ利用できます。キーなしまたは有料キーでのダウンロードでは、明示的な CLOAKBROWSER_VERSION の固定値が優先されます。有効な無料プランのライセンスキーでは、固定値を無視し、キャッシュ済みのバイナリを再利用する場合があります。プラットフォームで Preview を利用できない場合は Stable に戻ります。

リリースチャネルはブリッジプロセスの起動時に選択されます。すべての Streamable HTTP セッションに適用され、initialize メタデータで設定または上書きすることはできません。変更するにはブリッジを再起動してください。

カスタム CloakBrowser バイナリ

--binary-path <path> は、現在のブリッジプロセス用のカスタム CloakBrowser 実行ファイルを選択します。CLOAKBROWSER_BINARY_PATH は環境ベースの配置で同じ 設定を提供し、CLI オプションが優先されます。ブリッジはパスを解決し、読み取り 可能な通常ファイルを要求して、生成した Playwright MCP 設定の browser.launchOptions.executablePath に書き込みます。

npx -y cloakbrowser-mcp@latest --binary-path /opt/cloakbrowser/chrome

ブリッジはカスタム実行ファイルをダウンロードまたは更新しません。カスタムパスを 選ばない場合、代わりに CLOAKBROWSER_VERSION で CloakBrowser 管理バイナリの バージョンを固定できます。

Streamable HTTP では、選択したバイナリはブリッジプロセスに属し、そのプロセスが 作成するすべての MCP セッションで使用されます。initialize メタデータで実行 ファイルのパスを選択または上書きすることはできません。異なるバイナリには別の ブリッジプロセスを実行してください。

選択したビルドが getTools() メソッドを持つ document.modelContext または navigator.modelContext を提供する場合、上流 Playwright MCP はページのスナップショット後に webmcp_<page-tool> ツールを追加できます。tools/list_changed を送信し、ブリッジは通知と更新済みの一覧を転送します。各動的ツールの名前とスキーマはページが定義します。

GeoIPプロキシのマッチング

CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true を PLAYWRIGHT_MCP_PROXY_SERVER と一緒に設定すると、プロキシの出口位置から CloakBrowser のタイムゾーン、言語、ロケールのフィンガープリントフラグが導出されます。 対応するバイナリでは CloakBrowser がネイティブの URL 内インライン認証を選択し、 古いバイナリでは Playwright のプロキシオブジェクトをフォールバックとして保持します。

設定例、実行時の ストリーム可能なHTTPプロキシメタデータ、ユースケース、優先順位ルール、および制限事項については、GeoIPプロキシのマッチングを参照してください。

簡潔な手順はプロキシ経由の地域別 QAを参照してください。

人間らしい入力行動

CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true を設定すると、CloakBrowser の 人間のようなマウス、キーボード、スクロールレイヤーがページ操作に使用できるようになります。 この設定は、 Playwright MCPのページ初期化フックを通じて適用されるため、上流のブラウザツールの スキーマに変更は生じません。

設定例、 実行時の Streamable HTTP メタデータ、ユースケース、および制限事項については、人間らしい入力行動 を参照してください。

Chrome 拡張機能

Chrome 拡張機能はブラウザ起動時に読み込まれるため、ブリッジを起動する前、 または Streamable HTTP セッションを作成する前に設定してください。拡張機能は 展開済みディレクトリである必要があり、永続プロファイルが必要です:

PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \
  CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS='["/absolute/path/to/my-extension"]' \
  npx -y cloakbrowser-mcp@latest

Streamable HTTP では、initialize メタデータでプロファイルディレクトリと 拡張機能ディレクトリを渡します:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "userDataDir": "/absolute/path/to/profile",
        "extensionPaths": ["/absolute/path/to/my-extension"]
      }
    }
  }
}

拡張機能ファイルまたは拡張機能パスを変更した後は、ブリッジを再起動するか、 新しい HTTP セッションを作成してください。パスにカンマが含まれる場合、複数の 拡張機能を渡す場合、または Windows のドライブ文字付きパスを使用する場合は、 CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS に JSON 配列を使用してください。

コピーして使える短い設定例はChrome 拡張機能の読み込みを参照してください。

Playwright Extension 接続モード

Playwright Extension 接続モードは、CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS で展開済み拡張機能を読み込む仕組みとは別です。このモードは Chrome または Edge のプロファイルにインストール済みの公式 Playwright Extension を通じて接続します。ブリッジはこの拡張機能をインストールしません。

stdio では、プロセスの環境変数を設定します:

PLAYWRIGHT_MCP_EXTENSION=true \
  PLAYWRIGHT_MCP_EXTENSION_TOKEN='<secret-from-the-extension>' \
  PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/playwright-extension" \
  PLAYWRIGHT_MCP_PROFILE_DIR_NAME='Profile 1' \
  npx -y cloakbrowser-mcp@latest

Streamable HTTP では、initialize メタデータの extensionMode と profileDirName が対応するプロセス単位の設定を上書きします。userDataDir もセッションごとに指定します。トークンは引き続きプロセスの環境変数からのみ受け付けます:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "extensionMode": true,
        "profileDirName": "Profile 1",
        "userDataDir": "/absolute/path/to/profile"
      }
    }
  }
}

拡張機能モードには、空でないトークンと永続プロファイルが必要です。同時に実行する HTTP 拡張機能セッションは、異なる userDataDir を使用する必要があります。ブリッジは上流子プロセスを起動する前に、管理対象または外部の CDP エンドポイント、リモートブラウザのエンドポイント、ヘッドレスまたは隔離された起動設定、プロキシと GeoIP の設定、人間らしい操作、コンテキストの変更、展開済み拡張機能の extensionPaths、明示的に指定された CloakBrowser 起動オプションを拒否します。接続が成功するケースのエンドツーエンド検証は手動で行います。選択したブラウザプロファイルに公式 Playwright Extension があらかじめインストールされている必要があるためです。

ストリーミング可能なHTTPランタイムメタデータ

ストリーミング対応のHTTPクライアントは、initialize リクエストにブリッジ固有のメタデータを追加することで、MCPセッションごとに特定のランタイムオプションを選択できます:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "proxyServer": "http://user:pass@proxy.example:8080",
        "proxyBypass": ".internal,localhost",
        "geoipProxyMatch": true,
        "headless": false,
        "extensionMode": false,
        "profileDirName": "Profile 1",
        "humanize": true,
        "humanPreset": "careful",
        "userDataDir": "/absolute/path/to/profile",
        "contextOptions": {
          "viewport": { "width": 1280, "height": 720 },
          "locale": "en-US",
          "timezoneId": "America/New_York"
        },
        "extensionPaths": ["/absolute/path/to/extension"]
      }
    }
  }
}

proxyServer は、その HTTP セッションにおいて PLAYWRIGHT_MCP_PROXY_SERVER を上書きします。 proxyBypass は、PLAYWRIGHT_MCP_PROXY_BYPASS を上書きするのは、proxyServer が 存在する場合に限られます。 geoipProxyMatch を使用すると、MCP サーバーを再起動することなく、そのセッションの GeoIP マッチングを有効または無効に できます。既存のセッションは起動時のプロキシを維持します。 ロケーションを切り替えるには、新しい HTTP セッションを作成してください。

humanize は、他のセッションに影響を与えることなく、そのセッションにおける人間らしい入力動作を有効または無効にすることができます。 humanPreset を使用すると、そのセッションに対して default または careful を選択できますが、それ自体ではヒューマナイズド動作を有効にはしません。 既存の セッションは、initializeの間に記録された挙動を維持します。

headless は、そのセッションのヘッドレスブラウザモードを有効または無効にします。Docker イメージでは、headless を false に設定すると、必要に応じてコンテナ専用の仮想ディスプレイが起動します。このイメージ以外では、ヘッドありセッションに利用可能なディスプレイ環境が必要です。

extensionMode と profileDirName は、そのセッションの PLAYWRIGHT_MCP_EXTENSION と PLAYWRIGHT_MCP_PROFILE_DIR_NAME を上書きします。PLAYWRIGHT_MCP_EXTENSION_TOKEN はメタデータから受け付けません。

userDataDir は、そのセッションで永続的な Chromium プロファイルを有効にし、 PLAYWRIGHT_MCP_USER_DATA_DIR を上書きします。ブリッジはディレクトリを プラットフォームネイティブの絶対パスに解決し、存在しない場合は作成し、 書き込み可能であることを確認して、生成された browser.userDataDir に 書き込みます。永続プロファイルは、そのセッションのデフォルトの Streamable HTTP 分離プロファイルを無効にします。ブリッジは、同一プロセス内と同じプロセス ID 名前空間のプロセス間で、同じプロファイルディレクトリの重複したアクティブ利用を拒否します。ロックの復旧とその制限については、永続ログインプロファイルを参照してください。

contextOptions は検証され、CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS の上に 浅くマージされます。ネストされたオブジェクトは値全体として置き換えられます。 サポートされるフィールドは userAgent、viewport、locale、timezoneId、 colorScheme、permissions、geolocation、extraHTTPHeaders、 httpCredentials、ignoreHTTPSErrors、offline、deviceScaleFactor、 isMobile、hasTouch です。このリリースでは任意の BrowserContextOptions のパススルーはサポートされません。

extensionPaths は既存のディレクトリを指す必要があり、永続的な userDataDir が必要です。ブリッジは拡張機能のパスをプラットフォームネイティブの 絶対パスに解決し、CloakBrowser に渡し、生成された Chromium 引数 --load-extension と --disable-extensions-except を生成済みの Playwright MCP 設定に書き込みます。

認証済みHTTPプロキシの認証情報は、proxyServerに埋め込むことができます。 例えば、http://user:pass@proxy.example:8080 などです。@、 :、/ など、URL 上で意味を持つ認証情報の文字はパーセントエンコードしてください。 :、/、 ?, #、および %。

対応する CloakBrowser バイナリでは、認証付き HTTP プロキシにネイティブの URL 内インライン認証を使用し、ブリッジは重複する Playwright プロキシオブジェクトを削除します。古いバイナリでは互換性のため、 Playwright のプロキシオブジェクトをフォールバックとして保持します。

複数拠点のQAパターンについては、GeoIPプロキシマッチングを参照してください。 インタラクションのリアリズムに関するパターンについては、人間らしい入力行動を参照してください。

ログイン状態の再利用と拡張機能の設定は永続ログインプロファイルとChrome 拡張機能の読み込みを参照してください。

上流のオプション

このブリッジは、PLAYWRIGHT_MCP_* の設定をアップストリームの Playwright MCP に転送します。これには、次のようなアップストリームオプションが含まれます:

  • PLAYWRIGHT_MCP_ALLOWED_ORIGINS
  • PLAYWRIGHT_MCP_BLOCKED_ORIGINS
  • PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS
  • PLAYWRIGHT_MCP_CAPS
  • PLAYWRIGHT_MCP_CONSOLE_LEVEL
  • PLAYWRIGHT_MCP_FILE_PATHS
  • PLAYWRIGHT_MCP_IDLE_TIMEOUT
  • PLAYWRIGHT_MCP_IMAGE_RESPONSES
  • PLAYWRIGHT_MCP_PROFILE_DIR_NAME
  • PLAYWRIGHT_MCP_SNAPSHOT_MODE
  • PLAYWRIGHT_MCP_STORAGE_STATE
  • PLAYWRIGHT_MCP_WEBMCP

アップストリームのオプションの全一覧については、Playwright MCPのアップストリームドキュメントを参照してください。

PLAYWRIGHT_MCP_CAPS=devtools は上流の子プロセスに継承され、ブリッジ固有の --caps フラグなしで、その機能により制御されるツールを有効にします。

ログ記録

Streamable HTTP モードでは、人間が読み取れる形式の起動ログおよびリクエストログが stdout に出力されます。Stdio モードでは、通常の動作ログは出力されないため、MCP JSON-RPC の stdout はプロトコルに準拠した状態が保たれます。CLI の起動時に発生した致命的なエラーは、引き続き stderr に出力されます。

HTTPS

Streamable HTTP は、デフォルトでローカル HTTP を使用します。--http-protocol https または CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https を使用してダイレクト TLS を選択し、証明書/鍵ペアまたは PFX ファイルのいずれかを指定してください:

cloakbrowser-mcp --transport streamable-http \
  --http-protocol https \
  --https-cert ./cert.pem \
  --https-key ./key.pem

外部またはループバック以外の環境に公開する場合は、HTTPS に --http-auth-token を追加するか、認証およびネットワークアクセス制御も実施する信頼できるリバースプロキシで TLS を終了させてください。

ストリーム可能なHTTPセッション

各 Streamable HTTP MCP セッションは、独自のブリッジランタイムと上流 Playwright MCP 子プロセスを持ちます。永続プロファイルを設定しない限り、HTTP セッションは既定で隔離されたブラウザプロファイルを使用します。明示的な永続プロファイルはロックされるため、同時セッションには異なるプロファイルディレクトリが必要です。組み込みの memory バックエンドは、セッション ID、タイムスタンプ、有効期限、状態などのメタデータのみを保存します。ブラウザの状態は動作中の上流子プロセスに残り、成果物は引き続き PLAYWRIGHT_MCP_OUTPUT_DIR で管理されます。

水平スケーリングを行うには、mcp-session-id ヘッダーをキーとするスティッキーセッションを設定し、ロードバランサーの背後で複数のサーバーレプリカを実行します。 将来的にRedis、Postgres、またはSQLiteのバックエンドが導入された場合、メタデータやロックの調整は可能ですが、セッションを所有するプロセスが終了した後、稼働中のブラウザセッションを復元することはできません。

ストリーミング可能なHTTPプローブ

ブリッジが --transport streamable-http で動作している場合、MCPエンドポイントと同じホストおよびポート上に固定のプローブエンドポイントを公開します:

  • GET /healthz は、プロセスの健全性に関するメタデータを返します: status、version、 transport、および uptimeMs。
  • GET /readyz は、稼働状態のメタデータとセッション容量を返します: sessions.active、sessions.pending、 sessions.max、および sessions.available。

Readiness returns HTTP 200 while session capacity is available and HTTP 503 when active + pending >= max. --http-auth-token または CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN が設定されている場合、両方のプローブは、MCP リクエストと同様に Authorization: Bearer ... ヘッダーを必要とします。 認証トークンがない場合、プローブは設定されたHTTPバインドアドレスで公開されます。

追加の実用パス

upstream Playwright MCP とこのパッケージのどちらを使うかは比較を参照してください。短い作業手順にはレシピを使います: 永続プロファイル、拡張機能、reverse proxy、リージョン QA、Claude Desktop、Codex CLI、CI スモークテスト。