設定¶

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

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

ブリッジのオプション¶

GeoIPプロキシのマッチング¶

CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true を PLAYWRIGHT_MCP_PROXY_SERVER と設定し、 を組み合わせることで、プロキシの場所からCloakBrowserのタイムゾーン、言語、ロケールのフィンガープリントフラグを導出します。 このブリッジは、プロキシルーティングをアップストリームのPlaywright MCPに委任されたままにし、解決された --fingerprint-timezone、--lang、および --fingerprint-locale といった解決済みの起動フラグのみを注入します。

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

人間らしい入力行動¶

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

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

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 配列を使用してください。

ストリーミング可能な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,
        "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 を使用すると、そのセッションのヘッドレスブラウザモードを有効または無効にできます。 headless を false に設定するには、特に DockerやLinuxサーバーでの展開において、特に重要です。

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

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 上で意味を持つ認証情報の文字はパーセントエンコードしてください。 :、/、 ?, #、および %。

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

上流のオプション¶

このブリッジは、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_IMAGE_RESPONSES
• PLAYWRIGHT_MCP_SNAPSHOT_MODE
• PLAYWRIGHT_MCP_STORAGE_STATE

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

ログ記録¶

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セッションでは、上流のPlaywright MCPが隔離されたブラウザプロファイルで実行されるため、同時接続中のユーザーが同じ永続的なChromiumプロファイルを競合して使用することはありません。 組み込みの 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 スモークテスト。