Konfiguration¶

Verwenden Sie die Upstream-Variablen PLAYWRIGHT_MCP_* für das Playwright-MCP-Verhalten. Verwenden Sie CLOAK_PLAYWRIGHT_MCP_* ausschließlich für das Cloak-spezifische Bridge-Verhalten.

Die alten CLOAKBROWSER_MCP_*-Variablen werden nicht unterstützt. Die generierte CLI-Referenz ist die maßgebliche Liste der Bridge-CLI-Flags und der dazugehörigen Umgebungsvariablen.

Brückenoptionen¶

CloakBrowser-Lizenz und GitHub-Anmeldung¶

Die Lizenzeinrichtung erfolgt über die vorgelagerte CloakBrowser-CLI; cloakbrowser-mcp fügt keine An- oder Abmeldebefehle hinzu:

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

login akzeptiert einen kostenpflichtigen Schlüssel oder startet die GitHub-Anmeldung für einen Schlüssel der kostenlosen Stufe. Der validierte Schlüssel wird in ~/.cloakbrowser/license.key gespeichert; logout entfernt diese Datei. info meldet die aktive Lizenzstufe und bei Pro-Lizenzen die Anzahl der aktiven Sitzungen.

Alternativ können Sie CLOAKBROWSER_LICENSE_KEY in der Umgebung des MCP-Servers setzen. Die Bridge leitet die Variable an den Upstream-/Browser-Kindprozess weiter, ohne sie zu protokollieren. Wenn CLOAKBROWSER_CACHE_DIR auf einen benutzerdefinierten Cache mit license.key verweist, löst CloakBrowser den Schlüssel auf und die Bridge leitet aus der generierten Browserumgebung nur diesen aufgelösten Schlüssel weiter. Andere generierte Umgebungseinträge werden nicht kopiert.

Wenn CloakBrowser einen bereitgestellten Lizenzschlüssel ablehnt, ihn nicht prüfen kann oder den Lizenzserver nicht erreicht, schlägt der Start mit dem eindeutigen CloakBrowser-Fehler fehl. Die Bridge bewahrt diesen Fehler; sie maskiert ihn nicht und wechselt nicht stillschweigend zu einem anderen Browser oder einer anderen Lizenzstufe.

Verwaltet CDP¶

Der verwaltete Zugriff auf das Chrome-DevTools-Protokoll (CDP) ist eine explizite Zustimmung. Es macht das derselbe Chromium-Browser-Generation, kontrolliert von MCP durch eine fähigkeitsbasierte Entdeckung URL. Das Konfigurieren eines Portpools allein aktiviert CDP nicht.

Jeder CLI-Wert überschreibt nur seine passende Umgebungsvariable. Insbesondere, --no-cdp-enabled überschreibt CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true, und --no-cdp-allow-remote überschreibt CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true. Eine aktivierte Sitzung ohne einen Portpool wird abgelehnt, bevor ihr übergeordnetes Kind startet. Ein effektiver falscher Wert erzeugt keinen Listener, keine Port-Lease und keine Berechtigung.

Für stdio gilt der Prozesswert direkt:

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

Für Streamable HTTP, das flache cdpEnabled-Boolean im authentifizierten initialize-Metadaten überschreiben den Prozessstandard für diese Sitzung. Das Auslassen der Das Feld erbt den Prozesswert. Diese Beispiele wählen explizit eine Sitzung aus und noch einer raus:

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

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

Eine CDP-fähige HTTP-Sitzung besitzt eine externe Port-Miete. Deaktivierte Sitzungen tun dies nicht den Pool verbrauchen. Die Zuweisung ist prozesslokal, wählt den niedrigsten nicht vermieteten Kandidaten aus, und bricht diese Sitzung sofort ab, wenn der ausgewählte externe Port bereits belegt ist. Sitzungen schließen, um Ports freizugeben, oder einen größeren Bereich konfigurieren, wenn der Pool erschöpft ist.

Rufen Sie den aktuellen URL von cloakbrowser_bridge_info ab, und geben Sie ihn dann weiter structuredContent.cdp.discoveryUrl an einen CDP-Kunden wie den von Playwright chromium.connectOverCDP(). Behandle dieses URL als Anmeldeinformation: es enthält ein Zufallselement Pro-Generation-Fähigkeit und wird nach dem Austausch des Browsers veraltet. Verwaltetes CDP ist kein Playwright Server-Endpunkt. chromium.connect() und der aktuelle Open WebUI PLAYWRIGHT_WS_URL-Flüsse werden nicht unterstützt.

--cdp-advertised-scheme https veröffentlicht https Entdeckung und wss WebSocket URLs nur. Die Brücke bietet kein TLS für verwaltete CDP: ihren externen Listener und Chromium hop bleibt Klartext HTTP/WebSocket. Ein von einem Betreiber besessener TLS-Terminator muss auf demselben beworbenen gemieteten Port lauschen, die beworbenen Host und Origin beibehalten Behörde und leitet es eins zu eins an den Klartext-Listener dieser Sitzung weiter.

Die Aktivierung von CDP beginnt Chromium während der MCP-Initialisierung, sodass Eigentum und extern Die Bereitschaft kann überprüft werden. Konfigurieren Sie das Timeout für die Initialisierung des MCP-Clients auf mindestens 60. Sekunden. Wenn verwaltet CDP aktiviert ist, vom Benutzer bereitgestellt CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS darf --remote-debugging-port nicht enthalten, --remote-debugging-address oder --remote-debugging-pipe (einschließlich =-Formen). Die eigene interne --remote-debugging-pipe von Playwright bleibt zusammen mit der aktiviert Bridge-verwalteter Loopback-TCP-Endpunkt.

Siehe Tools, Docker, Sicherheit, und Architektur für den Entdeckungszustand, die Bereitstellung, Grenzen und Neustartverhalten.

CloakBrowser-Release-Kanal¶

CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL wählt den Release-Kanal des CloakBrowser-Binärprogramms. Die Vorgabe ist stable. preview fordert einen Pro-Preview-Browser-Build an und ist nur mit einer Pro-Lizenz verfügbar. Eine explizite Festlegung von CLOAKBROWSER_VERSION hat Vorrang. Ist Preview für die Plattform nicht verfügbar, fällt CloakBrowser auf Stable zurück.

Der Release-Kanal wird beim Start des Bridge-Prozesses gewählt. Er gilt für alle Streamable-HTTP-Sitzungen und kann nicht in initialize-Metadaten gesetzt oder überschrieben werden. Starten Sie die Bridge neu, um ihn zu ändern.

Benutzerdefinäre CloakBrowser-Binärdatei¶

--binary-path <path> wählt eine benutzerdefinierte CloakBrowser-Binärdatei für den aktuellen Bridge-Prozess. CLOAKBROWSER_BINARY_PATH bietet dieselbe Einstellung für umgebungsbasierte Bereitstellungen; die CLI-Option hat Vorrang. Die Bridge löst den Pfad auf, verlangt eine lesbare reguläre Datei und schreibt ihn in browser.launchOptions.executablePath der erzeugten Playwright-MCP-Konfiguration.

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

Die Bridge lädt eine benutzerdefinierte Binärdatei nicht herunter und aktualisiert sie nicht. Ohne benutzerdefinierten Pfad kann CLOAKBROWSER_VERSION stattdessen die von CloakBrowser verwaltete Binärversion festlegen.

Bei Streamable HTTP gehört die gewählte Binärdatei zum Bridge-Prozess und wird von jeder erzeugten MCP-Sitzung verwendet. initialize-Metadaten können keinen Ausführungspfad auswählen oder überschreiben; verwenden Sie getrennte Prozesse für unterschiedliche Binärdateien.

Wenn die gewählte Binärdatei document.modelContext implementiert, kann Upstream Playwright MCP nach einem Seiten-Snapshot Werkzeuge der Form webmcp_<page-tool> hinzufügen. Es sendet tools/list_changed; die Bridge leitet die Benachrichtigung und die aktualisierte Werkzeugliste weiter. Die Seite definiert Namen und Schema jedes dynamischen Werkzeugs.

GeoIP-Proxy-Zuordnung¶

Setzen Sie CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true zusammen mit PLAYWRIGHT_MCP_PROXY_SERVER, um die Zeitzonen-, Sprach- und Ländereinstellungs-Fingerprint-Flags von CloakBrowser anhand des Proxy-Ausgangsstandorts abzuleiten. CloakBrowser wählt bei unterstützten Binärdateien die native Inline-Authentifizierung in der URL und behält bei älteren Binärdateien das Playwright-Proxyobjekt als Fallback bei.

Beispiele zur Konfiguration, zur Laufzeit von „Streamable HTTP Proxy“-Metadaten, Anwendungsfälle, Prioritätsregeln und Einschränkungen finden Sie unter GeoIP Proxy Matching.

Die Zuordnung arbeitet fail-closed: Kann CloakBrowser die Proxy-Ausgangs-IP, die GeoIP-Datenbank, die Zeitzone oder das Gebietsschema nicht auflösen, startet der Browser nicht mit einem nur teilweise passenden Fingerabdruck. Die GeoIP-Auflösung ist auf höchstens 20 Sekunden begrenzt; der erste Download der Offline-GeoIP-Datenbank erfolgt getrennt und kann länger dauern.

Menschliches Eingabeverhalten¶

Setzen Sie CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true, um die menschenähnliche Maus-, Tastatur- und Scroll-Ebene von CloakBrowser für Seiteninteraktionen zu aktivieren. Die Bridge wendet dies über den Hook zur Seiteninitialisierung von Playwright MCP an, sodass die Schemata der übergeordneten Browser-Tools unverändert bleiben.

Beispiele für die Einrichtung, Streamable-HTTP-Metadaten zur Laufzeit, Anwendungsfälle und Einschränkungen finden Sie unter Humanized Input Behavior.

Chrome-Erweiterungen¶

Chrome-Erweiterungen werden beim Start des Browsers geladen. Konfigurieren Sie sie daher vor dem Start der Bridge oder vor dem Erstellen einer Streamable-HTTP-Sitzung. Erweiterungen müssen entpackte Verzeichnisse sein und erfordern ein persistentes Profil:

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

Für Streamable HTTP übergeben Sie die Profil- und Erweiterungsverzeichnisse in den initialize-Metadaten:

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

Starten Sie die Bridge neu oder erstellen Sie eine neue HTTP-Sitzung, nachdem Sie Erweiterungsdateien oder Erweiterungspfade geändert haben. Verwenden Sie ein JSON-Array für CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS, wenn Pfade Kommas enthalten, wenn mehrere Erweiterungen übergeben werden oder wenn Windows-Pfade mit Laufwerksbuchstaben verwendet werden.

Playwright-Extension-Verbindungsmodus¶

Dieser Modus verbindet sich über die offizielle Playwright Extension, die bereits in einem Chrome- oder Edge-Profil installiert ist, und unterscheidet sich vom Laden entpackter Erweiterungen über CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS. Für stdio setzen Sie PLAYWRIGHT_MCP_EXTENSION=true, PLAYWRIGHT_MCP_EXTENSION_TOKEN, PLAYWRIGHT_MCP_USER_DATA_DIR und bei Bedarf ein einzelnes relatives Segment in PLAYWRIGHT_MCP_PROFILE_DIR_NAME. Bei Streamable HTTP überschreiben die Metadaten extensionMode, profileDirName und userDataDir die Prozesswerte; das Token wird nur aus der Prozessumgebung akzeptiert. Parallele Sitzungen benötigen unterschiedliche userDataDir; launch-, CDP-, proxy-, GeoIP-, humanization-, context- und extensionPaths-Optionen sind inkompatibel.

Streamfähige HTTP-Laufzeit-Metadaten¶

Streamable-HTTP-Clients können pro MCP-Sitzung bestimmte Laufzeitoptionen auswählen, indem sie brückenbezogene Metadaten zur Anfrage initialize hinzufügen:

{
  "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 hat für diese HTTP-Sitzung Vorrang vor PLAYWRIGHT_MCP_PROXY_SERVER. proxyBypass überschreibt PLAYWRIGHT_MCP_PROXY_BYPASS nur dann, wenn proxyServer vorhanden ist. geoipProxyMatch kann den GeoIP-Abgleich für diese Sitzung aktivieren oder deaktivieren, ohne den MCP-Server neu zu starten. Bestehende Sitzungen behalten ihren Start-Proxy; um den Standort zu wechseln, muss eine neue HTTP-Sitzung erstellt werden.

humanize kann das humanisierte Eingabeverhalten für diese Sitzung aktivieren oder deaktivieren, ohne andere Sitzungen zu beeinflussen. humanPreset kann für diese Sitzung zwischen default oder careful für diese Sitzung auswählen, aktiviert das humanisierte Verhalten jedoch nicht von selbst. Bestehende Sitzungen behalten das während initialize erfasste Verhalten bei.

In Docker startet headless: false bei Bedarf eine private virtuelle Anzeige. Außerhalb des Images benötigt eine Sitzung mit grafischer Oberfläche weiterhin eine nutzbare Anzeigeumgebung.

userDataDir aktiviert für diese Sitzung ein persistentes Chromium-Profil und überschreibt PLAYWRIGHT_MCP_USER_DATA_DIR. Die Bridge löst das Verzeichnis als absoluten, plattformnativen Pfad auf, erstellt es bei Bedarf, prüft die Schreibbarkeit und schreibt es in das generierte browser.userDataDir. Ein persistentes Profil deaktiviert das standardmäßige isolierte Streamable-HTTP-Profil für diese Sitzung. Die Bridge weist doppelte aktive Profilverzeichnisse innerhalb eines Prozesses zurück; prozessübergreifende Profilkonflikte bleiben Chromium/Playwright-Fehler.

contextOptions werden validiert und flach über CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS zusammengeführt; verschachtelte Objekte ersetzen ganze Werte. Unterstützte Felder sind userAgent, viewport, locale, timezoneId, colorScheme, permissions, geolocation, extraHTTPHeaders, httpCredentials, ignoreHTTPSErrors, offline, deviceScaleFactor, isMobile und hasTouch. Eine beliebige Weitergabe von BrowserContextOptions wird in dieser Version nicht unterstützt.

extensionPaths müssen auf vorhandene Verzeichnisse zeigen und erfordern ein persistentes userDataDir. Die Bridge löst Erweiterungspfade als absolute, plattformnative Pfade auf, übergibt sie an CloakBrowser und schreibt die generierten Chromium-Argumente --load-extension und --disable-extensions-except in die generierte Playwright-MCP-Konfiguration.

Authentifizierte HTTP-Proxy-Anmeldedaten können in proxyServer eingebettet werden, zum Beispiel http://user:pass@proxy.example:8080. Führen Sie eine Prozent-Kodierung für Anmeldeinformationen durch, die URL-Bedeutung haben, wie z. B. @, :, /, ?, # und %.

Bei unterstützten CloakBrowser-Binärdateien verwenden authentifizierte HTTP-Proxys die native Inline-Authentifizierung in der URL, und die Bridge entfernt das doppelte Playwright-Proxyobjekt. Ältere Binärdateien behalten das Playwright-Proxyobjekt als Kompatibilitäts-Fallback bei.

Informationen zu QA-Mustern für mehrere Standorte finden Sie unter GeoIP-Proxy-Abgleich. Informationen zu Mustern für realistische Interaktionen finden Sie unter Humanisiertes Eingabeverhalten.

Optionen für den Upstream¶

Die Bridge leitet die Einstellungen von PLAYWRIGHT_MCP_* an den vorgelagerten Playwright MCP weiter. Dazu gehören auch vorgelagerte Optionen wie:

• 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

Die vollständige Übersicht über die Optionen des Upstream-Projekts finden Sie in der Playwright-MCP-Dokumentation des Upstream-Projekts.

PLAYWRIGHT_MCP_CAPS=devtools wird an den Upstream-Kindprozess vererbt und aktiviert die von dieser Fähigkeit gesteuerten Tools ohne bridge-eigene Option --caps.

Protokollierung¶

Im „Streamable HTTP“-Modus werden für Menschen lesbare Start- und Anforderungsprotokolle an stdout ausgegeben. Im „Stdio“-Modus werden keine routinemäßigen Betriebsprotokolle ausgegeben, sodass die stdout-Ausgabe von MCP JSON-RPC protokollkonform bleibt. Schwerwiegende Fehler beim Start der Befehlszeilenschnittstelle werden weiterhin an stderr ausgegeben.

HTTPS¶

Streamable HTTP verwendet standardmäßig lokales HTTP. Wählen Sie „Direct TLS“ mit --http-protocol https oder CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https aus und geben Sie anschließend entweder ein Zertifikat/Schlüsselpaar oder eine PFX-Datei an:

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

Für den externen Zugriff oder den Zugriff außerhalb des Loopback-Modus verwenden Sie HTTPS in Kombination mit --http-auth-token oder lassen Sie TLS an einem vertrauenswürdigen Reverse-Proxy enden, der ebenfalls Authentifizierung und Netzwerkzugriffskontrollen durchführt.

Streamfähige HTTP-Sitzungen¶

Jede Streamable-HTTP-MCP-Sitzung verfügt über eine eigene Bridge-Laufzeitumgebung und einen eigenen vorgelagerten Playwright-MCP-Kindprozess. HTTP-Sitzungen führen das vorgelagerte Playwright-MCP mit einem isolierten Browserprofil aus, sodass gleichzeitige Benutzer nicht um dasselbe persistente Chromium-Profil konkurrieren. Das integrierte memory-Sitzungs-Backend speichert ausschließlich Metadaten wie Sitzungs-ID, Zeitstempel, Ablaufzeit und Status. Der Browserstatus verbleibt im aktiven Upstream-Kindprozess, und die Artefakte werden weiterhin von PLAYWRIGHT_MCP_OUTPUT_DIR verwaltet.

Für die horizontale Skalierung sollten Sie mehrere Server-Replikate hinter einem Load Balancer betreiben, wobei die Sticky-Sessions über den Header mcp-session-id zugeordnet werden. Zukünftige Redis-, Postgres- oder SQLite-Backends können Metadaten und Sperren koordinieren, sind jedoch nicht in der Lage, eine aktive Browsersitzung wiederherzustellen, nachdem der Prozess, dem sie gehört, beendet wurde.

Streamfähige HTTP-Probes¶

Wenn die Brücke mit --transport streamable-http betrieben wird, stellt sie feste Probe-Endpunkte auf demselben Host und Port wie der MCP-Endpunkt bereit:

• GET /healthz gibt Metadaten zum Prozesszustand zurück: status, version, transport und uptimeMs.
• GET /readyz gibt Metadaten zur Betriebsbereitschaft und zur Sitzungskapazität zurück: sessions.active, sessions.pending, sessions.max und sessions.available.

Die Bereitschaft gibt HTTP 200 zurück, solange Sitzungskapazität verfügbar ist, und HTTP 503, wenn active + pending >= max ist. Wenn --http-auth-token oder CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN konfiguriert ist, benötigen beide Probes denselben Authorization: Bearer ...-Header wie MCP-Anfragen. Ohne Authentifizierungstoken sind die Probes auf der konfigurierten HTTP-Bind-Adresse offen.

Weitere praktische Pfade¶

Für die Entscheidung zwischen upstream Playwright MCP und diesem Paket nutzen Sie den Vergleich. Für kurze Aufgaben nutzen Sie die Rezepte: persistentes Profil, Erweiterungen, reverse proxy, regionale QA, Claude Desktop, Codex CLI und CI-Smoke-Test.