Configuration¶

Utilisez les variables PLAYWRIGHT_MCP_* en amont pour le comportement du MCP Playwright. Utilisez CLOAK_PLAYWRIGHT_MCP_* uniquement pour le comportement du pont spécifique à Cloak.

Les anciennes variables CLOAKBROWSER_MCP_* ne sont plus prises en charge. La Référence CLI générée constitue la liste de référence des indicateurs CLI du pont et des variables d'environnement correspondantes.

Options de pont¶

Licence CloakBrowser et connexion GitHub¶

La configuration de la licence utilise la CLI CloakBrowser en amont ; cloakbrowser-mcp n'ajoute pas de commandes de connexion ou de déconnexion :

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

login accepte une clé payante ou lance la connexion GitHub afin d'obtenir une clé de l'offre gratuite. La clé validée est stockée dans ~/.cloakbrowser/license.key ; logout supprime ce fichier. info indique le niveau de licence actif et, pour les licences Pro, le nombre de sessions actives.

Vous pouvez aussi définir CLOAKBROWSER_LICENSE_KEY dans l'environnement du serveur MCP. Le pont transmet cette variable au processus enfant en amont/du navigateur sans la journaliser. Lorsque CLOAKBROWSER_CACHE_DIR pointe vers un cache personnalisé contenant license.key, CloakBrowser résout la clé et le pont ne transmet que cette clé résolue depuis l'environnement généré du navigateur. Les autres entrées d'environnement générées ne sont pas copiées.

Si CloakBrowser rejette la clé de licence fournie, ne peut pas la vérifier ou ne peut pas joindre son serveur de licences, le démarrage échoue avec l'erreur explicite de CloakBrowser. Le pont préserve cette erreur : il ne la masque pas et ne bascule pas silencieusement vers un autre navigateur ou niveau de licence.

CDP géré¶

L'accès géré au protocole Chrome DevTools (CDP) est une option explicite. Il expose le même génération de navigateur Chromium contrôlée par MCP via une capacité porteuse découverte URL. Configurer un pool de ports seul n'active pas CDP.

Chaque valeur CLI remplace uniquement sa variable d'environnement correspondante. En particulier, --no-cdp-enabled remplace CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true, et --no-cdp-allow-remote remplace CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true. Une session activée sans pool de ports est rejetée avant que son enfant en amont ne démarre. Une valeur fausse efficace ne crée aucun écouteur, location de port ou capacité.

Pour stdio, la valeur du processus s'applique directement :

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

Pour Streamable HTTP, le booléen plat cdpEnabled dans l'authentifié Les métadonnées initialize remplacent les paramètres par défaut du processus pour cette session. En omettant le le champ hérite de la valeur du processus. Ces exemples choisissent explicitement une session et un autre dehors :

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

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

Une session HTTP activée par CDP possède un bail de port externe. Les sessions désactivées ne le possèdent pas consommer le pool. L'allocation est locale au processus, elle sélectionne le candidat non loué le plus bas, et échoue cette session immédiatement si le port externe sélectionné est déjà occupé. Fermez les sessions pour libérer des ports ou configurez une plage plus large lorsque le pool est épuisé.

Récupérez le URL actuel à partir de cloakbrowser_bridge_info, puis transmettez-le structuredContent.cdp.discoveryUrl à un client CDP tel que Playwright chromium.connectOverCDP(). Traitez ce URL comme une référence : il inclut un aléatoire la capacité par génération et devient obsolète après le remplacement du navigateur. CDP géré est pas un point de terminaison de serveur Playwright. chromium.connect() et le Open WebUI actuel Les flux PLAYWRIGHT_WS_URL ne sont pas pris en charge.

--cdp-advertised-scheme https publie https découverte et wss WebSocket URL seulement. Le pont ne fournit pas TLS pour CDP géré : son écouteur externe et Chromium hop rester en texte clair HTTP/WebSocket. Un terminateur TLS appartenant à l'opérateur doit écouter sur le même port loué annoncé, préserver les Host et Origin annoncés autorité, et transmettre en avant en tête-à-tête à l'auditeur en texte clair de cette session.

L'activation de CDP commence Chromium lors de l'initialisation de MCP afin que la propriété et l'externe la préparation peut être vérifiée. Configurez le délai d'initialisation du client MCP à au moins 60 secondes. Lorsque CDP géré est activé, fourni par l'utilisateur CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS ne doit pas contenir --remote-debugging-port, --remote-debugging-address, ou --remote-debugging-pipe (y compris les formes =). Le propre --remote-debugging-pipe interne de Playwright reste activé parallèlement à la point de terminaison TCP de boucle locale géré par le pont.

Voir Outils, Docker, Sécurité, et Architecture pour l'état de découverte, le déploiement, limites et comportement de redémarrage.

Canal de publication de CloakBrowser¶

CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL sélectionne le canal de publication du binaire CloakBrowser. La valeur par défaut est stable. preview demande une version Preview du navigateur Pro et est disponible uniquement avec une licence Pro. Un verrouillage explicite de CLOAKBROWSER_VERSION est prioritaire. Si Preview n'est pas disponible pour la plateforme, CloakBrowser revient à Stable.

Le canal de publication est choisi au démarrage du processus de pont. Il s'applique à toutes les sessions Streamable HTTP et ne peut pas être défini ni remplacé dans les métadonnées initialize. Redémarrez le pont pour le modifier.

Binaire CloakBrowser personnalisé¶

--binary-path <path> sélectionne un exécutable CloakBrowser personnalisé pour le processus de pont actuel. CLOAKBROWSER_BINARY_PATH fournit le même réglage pour les déploiements fondés sur l'environnement ; l'option CLI est prioritaire. Le pont résout le chemin, exige un fichier ordinaire lisible et l'écrit dans browser.launchOptions.executablePath de la configuration Playwright MCP générée.

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

Le pont ne télécharge ni ne met à jour un exécutable personnalisé. Sans chemin personnalisé, CLOAKBROWSER_VERSION peut plutôt fixer la version du binaire géré par CloakBrowser.

Pour Streamable HTTP, le binaire sélectionné appartient au processus de pont et est utilisé par toutes les sessions MCP qu'il crée. Les métadonnées initialize ne peuvent pas sélectionner ni remplacer un chemin exécutable ; lancez des processus distincts pour des binaires différents.

Lorsque le binaire sélectionné implémente document.modelContext, Playwright MCP en amont peut ajouter des outils webmcp_<page-tool> après un instantané de page. Il envoie tools/list_changed ; le pont relaie la notification et la liste d’outils actualisée. La page définit le nom et le schéma de chaque outil dynamique.

Correspondance via le proxy GeoIP¶

Définissez CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true avec PLAYWRIGHT_MCP_PROXY_SERVER afin de déduire les indicateurs de fuseau horaire, de langue et de paramètres régionaux de CloakBrowser à partir de l'emplacement de sortie du proxy. CloakBrowser sélectionne l'authentification native intégrée à l'URL pour les binaires compatibles et conserve l'objet proxy de Playwright comme solution de repli pour les anciens binaires.

Consultez la section Correspondance de proxy GeoIP pour découvrir des exemples de configuration, les métadonnées de proxy HTTP Streamable en exécution, les cas d'utilisation, les règles de priorité et les limitations.

La correspondance fonctionne en fail-closed : si CloakBrowser ne peut pas résoudre l'IP de sortie du proxy, la base GeoIP, le fuseau horaire ou les paramètres régionaux, le navigateur ne démarre pas avec une empreinte partiellement correspondante. La résolution GeoIP est limitée à 20 secondes ; le premier téléchargement de la base GeoIP hors ligne est distinct et peut prendre plus de temps.

Comportement d'entrée humanisé¶

Définissez CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true pour activer la couche de CloakBrowser imitant les gestes de la souris, du clavier et du défilement pour les interactions avec les pages. Le pont applique cette modification via le hook d’initialisation de page de Playwright MCP, de sorte que les schémas des outils de navigation en amont restent inchangés.

Consultez la section Comportement d'entrée humanisé pour découvrir des exemples de configuration, les métadonnées HTTP Streamable en exécution, les cas d'utilisation et les limitations.

Extensions Chrome¶

Les extensions Chrome sont chargées au démarrage du navigateur. Configurez-les donc avant de démarrer le pont ou avant de créer une session Streamable HTTP. Les extensions doivent être des répertoires décompressés et nécessitent un profil persistant :

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

Pour Streamable HTTP, transmettez les répertoires du profil et de l'extension dans les métadonnées initialize :

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

Redémarrez le pont ou créez une nouvelle session HTTP après avoir modifié des fichiers ou chemins d'extensions. Utilisez un tableau JSON pour CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS lorsque les chemins contiennent des virgules, lors du passage de plusieurs extensions ou lors de l'utilisation de chemins Windows avec lettres de lecteur.

Mode de connexion Playwright Extension¶

Ce mode se connecte au moyen de l'extension Playwright officielle déjà installée dans un profil Chrome ou Edge ; il est distinct du chargement d'extensions décompressées avec CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS. Pour stdio, définissez PLAYWRIGHT_MCP_EXTENSION=true, PLAYWRIGHT_MCP_EXTENSION_TOKEN, PLAYWRIGHT_MCP_USER_DATA_DIR et, si nécessaire, un seul segment relatif dans PLAYWRIGHT_MCP_PROFILE_DIR_NAME. Avec Streamable HTTP, les métadonnées extensionMode, profileDirName et userDataDir remplacent les valeurs du processus, mais le token n'est accepté que depuis l'environnement du processus. Les sessions parallèles doivent utiliser des userDataDir différents ; les options launch, CDP, proxy, GeoIP, humanization, context et extensionPaths sont incompatibles.

Métadonnées d'exécution HTTP diffusables en continu¶

Les clients HTTP prenant en charge le streaming peuvent choisir certaines options d'exécution pour chaque session MCP en ajoutant des métadonnées spécifiques au pont à la requête initialize :

{
  "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 remplace PLAYWRIGHT_MCP_PROXY_SERVER pour cette session HTTP. proxyBypass remplace PLAYWRIGHT_MCP_PROXY_BYPASS uniquement lorsque proxyServer est présent. geoipProxyMatch permet d’activer ou de désactiver la correspondance GeoIP pour cette session sans redémarrer le serveur MCP. Les sessions existantes conservent leur proxy de démarrage ; créez une nouvelle session HTTP pour changer d’emplacement.

humanize permet d'activer ou de désactiver le comportement d'entrée humanisé pour cette session sans modifier les autres sessions. humanPreset permet de sélectionner default ou careful pour cette session, mais n’active pas en soi le comportement humanisé. Les sessions existantes conservent le comportement enregistré pendant initialize.

Dans Docker, headless: false démarre un affichage virtuel privé à la demande. En dehors de l’image, une session avec interface graphique requiert toujours un environnement d’affichage utilisable.

userDataDir active un profil Chromium persistant pour cette session et remplace PLAYWRIGHT_MCP_USER_DATA_DIR. Le pont résout le répertoire en chemin absolu natif de la plateforme, le crée s'il manque, vérifie qu'il est accessible en écriture et l'écrit dans le browser.userDataDir généré. Un profil persistant désactive le profil isolé Streamable HTTP par défaut pour cette session. Le pont rejette les répertoires de profil actifs en double dans un même processus ; les conflits de profil entre processus restent des erreurs Chromium/Playwright.

contextOptions sont validées et fusionnées superficiellement au-dessus de CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS ; les objets imbriqués remplacent des valeurs entières. Les champs pris en charge sont userAgent, viewport, locale, timezoneId, colorScheme, permissions, geolocation, extraHTTPHeaders, httpCredentials, ignoreHTTPSErrors, offline, deviceScaleFactor, isMobile et hasTouch. Le passage arbitraire de BrowserContextOptions n'est pas pris en charge dans cette version.

extensionPaths doivent pointer vers des répertoires existants et nécessitent un userDataDir persistant. Le pont résout les chemins d'extensions en chemins absolus natifs de la plateforme, les transmet à CloakBrowser et écrit les arguments Chromium générés --load-extension et --disable-extensions-except dans la configuration Playwright MCP générée.

Les identifiants de proxy HTTP authentifiés peuvent être intégrés dans proxyServer, par exemple http://user:pass@proxy.example:8080. Encodez en pourcentage les caractères d’identification ayant une signification URL, tels que @, :, /, ?, #, et %.

Sur les binaires CloakBrowser compatibles, les proxys HTTP authentifiés utilisent l'authentification native intégrée à l'URL et le pont supprime l'objet proxy Playwright en double. Les anciens binaires conservent l'objet proxy Playwright comme solution de repli pour la compatibilité.

Pour les modèles de contrôle qualité multi-sites, voir Correspondance de proxy GeoIP. Pour les modèles de réalisme d'interaction, voir Comportement d'entrée humanisé.

Options en amont¶

Le pont transmet les paramètres PLAYWRIGHT_MCP_* au MCP Playwright en amont. Cela inclut les options en amont telles que :

• 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

Consultez la documentation officielle de Playwright MCP pour découvrir l'ensemble des options disponibles.

PLAYWRIGHT_MCP_CAPS=devtools est hérité par le processus enfant upstream et active les outils contrôlés par cette capacité sans option --caps propre au pont.

Journalisation¶

En mode HTTP « Streamable », les journaux de démarrage et de requêtes, lisibles par l'utilisateur, sont écrits sur stdout. En mode « stdio », aucun journal d'exploitation courant n'est généré ; ainsi, la sortie stdout de MCP JSON-RPC reste conforme au protocole. Les échecs fatals au démarrage de l'interface CLI sont toujours consignés sur stderr.

HTTPS¶

HTTP Streamable utilise par défaut le protocole HTTP local. Sélectionnez le TLS direct avec --http-protocol https ou CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https, puis fournissez soit une paire certificat/clé, soit un fichier PFX :

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

Pour une exposition externe ou sans bouclage, utilisez le protocole HTTPS avec --http-auth-token, ou terminez la connexion TLS au niveau d'un proxy inverse de confiance qui applique également des contrôles d'authentification et d'accès au réseau.

Sessions HTTP en continu¶

Chaque session HTTP MCP de Streamable dispose de son propre environnement d’exécution « bridge » et de son propre processus enfant Playwright MCP en amont. Les sessions HTTP exécutent Playwright MCP en amont avec un profil de navigateur isolé, de sorte que les utilisateurs simultanés ne se disputent pas le même profil Chromium persistant. Le backend de session intégré memory ne stocke que des métadonnées telles que l'ID de session, les horodatages, la date d'expiration et l'état. L’état du navigateur reste dans le processus enfant en amont actif, et les artefacts sont toujours contrôlés par PLAYWRIGHT_MCP_OUTPUT_DIR.

Pour la mise à l'échelle horizontale, exécutez plusieurs répliques de serveur derrière un équilibreur de charge avec des sessions persistantes identifiées par l'en-tête mcp-session-id. Les futurs backends Redis, Postgres ou SQLite pourront coordonner les métadonnées et les verrous, mais ils ne pourront pas restaurer une session de navigateur en cours après la fermeture du processus qui la détient.

Sondes HTTP en continu¶

Lorsque le pont fonctionne avec --transport streamable-http, il expose des points de terminaison de sonde fixes sur le même hôte et le même port que le point de terminaison MCP :

• GET /healthz renvoie les métadonnées relatives à l'état du processus : status, version, transport, et uptimeMs.
• GET /readyz renvoie les métadonnées de disponibilité et la capacité de session : sessions.active, sessions.pending, sessions.max et sessions.available.

La fonctionnalité « Readiness » renvoie 200 tant qu'il reste de la capacité de session disponible, et 503 lorsque active + pending >= max. Si --http-auth-token ou CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN est configuré, les deux sondes doivent utiliser le même en-tête Authorization: Bearer ... que les requêtes MCP. En l'absence de jeton d'authentification, les sondes sont ouvertes sur l'adresse de liaison HTTP configurée.

Parcours pratiques supplémentaires¶

Pour choisir entre Playwright MCP amont et ce paquet, consultez la comparaison. Pour des tâches courtes, utilisez les recettes: profil persistant, extensions, reverse proxy, QA régionale, Claude Desktop, Codex CLI et test smoke CI.