Configuración¶

Utiliza las variables PLAYWRIGHT_MCP_* de upstream para el comportamiento del MCP de Playwright. Utilice CLOAK_PLAYWRIGHT_MCP_* únicamente para el comportamiento del puente específico de Cloak.

Las antiguas variables CLOAKBROWSER_MCP_* ya no son compatibles. La Referencia de la CLI generada es la lista oficial de los indicadores de la CLI del puente y sus variables de entorno correspondientes.

Opciones de puente¶

Licencia de CloakBrowser e inicio de sesión con GitHub¶

La licencia se configura con la CLI original de CloakBrowser; cloakbrowser-mcp no añade comandos de inicio o cierre de sesión:

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

login acepta una clave de pago o inicia la autenticación con GitHub para obtener una clave del nivel gratuito. La clave validada se guarda en ~/.cloakbrowser/license.key; logout elimina ese archivo. info muestra el nivel de licencia activo y, para las licencias Pro, el número de sesiones activas.

También puedes definir CLOAKBROWSER_LICENSE_KEY en el entorno del servidor MCP. El puente reenvía esa variable al proceso secundario ascendente/del navegador sin registrarla. Si CLOAKBROWSER_CACHE_DIR apunta a una caché personalizada que contiene license.key, CloakBrowser resuelve la clave y el puente reenvía únicamente esa clave resuelta desde el entorno generado del navegador. No se copian otras entradas de entorno generadas.

Canal de lanzamiento de CloakBrowser¶

CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL selecciona el canal de lanzamiento del binario de CloakBrowser. El valor predeterminado es stable. preview solicita una compilación previa de navegador Pro y solo está disponible con una licencia Pro. Una versión fijada explícitamente mediante CLOAKBROWSER_VERSION tiene prioridad. Si Preview no está disponible para la plataforma, CloakBrowser vuelve a Stable.

El canal de lanzamiento se selecciona cuando se inicia el proceso del puente. Se aplica a todas las sesiones de Streamable HTTP y no se puede establecer ni reemplazar en los metadatos de initialize. Reinicie el puente para cambiarlo.

Coincidencia de proxy GeoIP¶

Configura CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true junto con PLAYWRIGHT_MCP_PROXY_SERVER para obtener los indicadores de zona horaria, idioma y configuración regional de CloakBrowser a partir de la ubicación de salida del proxy. CloakBrowser selecciona la autenticación nativa integrada en la URL para los binarios compatibles y conserva el objeto proxy de Playwright como alternativa para los binarios antiguos.

Consulta Coincidencia de proxies GeoIP para ver ejemplos de configuración, metadatos de proxy HTTP transmisibles en tiempo de ejecución, casos de uso, reglas de prioridad y limitaciones.

Comportamiento de entrada humanizado¶

Establece CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true para activar la capa de CloakBrowser que simula el comportamiento humano del ratón, el teclado y el desplazamiento para las interacciones con la página. El puente aplica esto a través del gancho de inicialización de la página de Playwright MCP, de modo que los esquemas de las herramientas de navegador de origen permanecen inalterados.

Consulte Comportamiento de entrada humanizado para ver ejemplos de configuración, metadatos HTTP de Streamable en tiempo de ejecución, casos de uso y limitaciones.

Extensiones de Chrome¶

Las extensiones de Chrome se cargan cuando se inicia el navegador, así que configúralas antes de iniciar el puente o antes de crear una sesión Streamable HTTP. Las extensiones deben ser directorios descomprimidos y requieren un perfil persistente:

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

Para Streamable HTTP, pasa los directorios del perfil y de la extensión en los metadatos de initialize:

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

Reinicia el puente o crea una nueva sesión HTTP después de cambiar archivos o rutas de extensiones. Usa una matriz JSON para CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS cuando las rutas contengan comas, al pasar varias extensiones o al usar rutas de Windows con letras de unidad.

Metadatos de tiempo de ejecución HTTP transmitibles¶

Los clientes HTTP de transmisión pueden seleccionar determinadas opciones de tiempo de ejecución para cada sesión de MCP añadiendo metadatos específicos del puente a la solicitud 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 anula PLAYWRIGHT_MCP_PROXY_SERVER para esa sesión HTTP. proxyBypass sustituye a PLAYWRIGHT_MCP_PROXY_BYPASS únicamente cuando proxyServer está presente. geoipProxyMatch puede activar o desactivar la coincidencia de GeoIP para esa sesión sin reiniciar el servidor MCP. Las sesiones existentes conservan su proxy de inicio; crea una nueva sesión HTTP para cambiar de ubicación.

humanize puede activar o desactivar el comportamiento de entrada humanizado para esa sesión sin afectar a las demás sesiones. humanPreset puede seleccionar default o careful para esa sesión, pero no activa por sí mismo el comportamiento humanizado. Las sesiones existentes conservan el comportamiento capturado durante initialize.

headless puede activar o desactivar el modo de navegador sin interfaz gráfica para esa sesión. Configurar headless en false requiere un entorno de visualización operativo, especialmente en implementaciones en Docker o en servidores Linux.

userDataDir habilita un perfil persistente de Chromium para esa sesión y sobrescribe PLAYWRIGHT_MCP_USER_DATA_DIR. El puente resuelve el directorio como una ruta absoluta nativa de la plataforma, lo crea si falta, comprueba que se pueda escribir y lo escribe en el browser.userDataDir generado. Un perfil persistente deshabilita el perfil aislado predeterminado de Streamable HTTP para esa sesión. El puente rechaza directorios de perfil activos duplicados dentro de un mismo proceso; los conflictos de perfil entre procesos siguen siendo errores de Chromium/Playwright.

contextOptions se validan y se fusionan superficialmente sobre CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS; los objetos anidados se sustituyen por completo. Los campos admitidos son userAgent, viewport, locale, timezoneId, colorScheme, permissions, geolocation, extraHTTPHeaders, httpCredentials, ignoreHTTPSErrors, offline, deviceScaleFactor, isMobile y hasTouch. En esta versión no se admite el paso arbitrario de BrowserContextOptions.

extensionPaths deben apuntar a directorios existentes y requieren un userDataDir persistente. El puente resuelve las rutas de extensiones como rutas absolutas nativas de la plataforma, las pasa a CloakBrowser y escribe los argumentos de Chromium generados --load-extension y --disable-extensions-except en la configuración generada de Playwright MCP.

Las credenciales de proxy HTTP autenticadas se pueden incrustar en proxyServer, por ejemplo http://user:pass@proxy.example:8080. Codifica en formato «percent» los caracteres de las credenciales que tengan significado en una URL, como @, :, /, ?, #, y %.

En los binarios de CloakBrowser compatibles, los proxies HTTP autenticados utilizan la autenticación nativa integrada en la URL y el puente elimina el objeto proxy duplicado de Playwright. Los binarios antiguos conservan el objeto proxy de Playwright como alternativa de compatibilidad.

Para los patrones de control de calidad en múltiples ubicaciones, consulta Coincidencia de proxy GeoIP. Para los patrones de realismo en la interacción, véase Comportamiento de entrada humanizado.

Opciones de origen¶

El puente reenvía la configuración de PLAYWRIGHT_MCP_* al MCP de Playwright situado en la parte superior de la cadena. Esto incluye opciones de la parte superior de la cadena como:

• 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

Consulta la documentación de Playwright MCP del proyecto original para conocer todas las opciones disponibles.

Registro¶

El modo HTTP «Streamable» escribe registros de inicio y de solicitudes legibles para el usuario en stdout. El modo «stdio» no genera registros operativos rutinarios, por lo que la salida stdout de MCP JSON-RPC se mantiene libre de datos del protocolo. Los errores graves de inicio de la CLI siguen registrándose en stderr.

HTTPS¶

Streamable HTTP utiliza HTTP local de forma predeterminada. Selecciona TLS directo con --http-protocol https o CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https y, a continuación, facilite un par de certificado y clave o un archivo PFX:

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

Para una exposición externa o sin bucle cerrado, utiliza HTTPS junto con --http-auth-token, o bien termina el TLS en un proxy inverso de confianza que también aplique controles de autenticación y de acceso a la red.

Sesiones HTTP transmisibles¶

Cada sesión HTTP de Streamable MCP cuenta con su propio entorno de ejecución de puente y su propio proceso hijo de Playwright MCP en el nivel superior. Las sesiones HTTP ejecutan Playwright MCP en el nivel superior con un perfil de navegador aislado, de modo que los usuarios simultáneos no compiten por el mismo perfil persistente de Chromium. El backend de sesión integrado memory almacena únicamente metadatos, como el ID de sesión, las marcas de tiempo, la fecha de caducidad y el estado. El estado del navegador permanece en el proceso hijo activo de nivel superior, y los artefactos siguen estando controlados por PLAYWRIGHT_MCP_OUTPUT_DIR.

Para el escalado horizontal, ejecuta varias réplicas del servidor detrás de un equilibrador de carga con sesiones persistentes identificadas mediante el encabezado mcp-session-id. Los futuros backends de Redis, Postgres o SQLite podrán coordinar metadatos y bloqueos, pero no podrán restaurar una sesión de navegador activa una vez que se haya cerrado el proceso al que pertenece.

Sondas HTTP con transmisión continua¶

Cuando el puente funciona con --transport streamable-http, expone puntos finales de sonda fijos en el mismo host y puerto que el punto final del MCP:

• GET /healthz devuelve metadatos sobre el estado del proceso: status, version, transport y uptimeMs.
• GET /readyz devuelve metadatos de disponibilidad y capacidad de sesión: sessions.active, sessions.pending, sessions.max y sessions.available.

La disponibilidad devuelve HTTP 200 mientras haya capacidad de sesión disponible y HTTP 503 cuando active + pending >= max. Si se configura --http-auth-token o CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN, ambas sondas requieren el mismo encabezado Authorization: Bearer ... que las solicitudes MCP. Sin un token de autenticación, las sondas permanecen abiertas en la dirección de enlace HTTP configurada.

Más rutas prácticas¶

Para elegir entre Playwright MCP upstream y este paquete, consulta la comparación. Para tareas rápidas, usa las recetas: perfil persistente, extensiones, reverse proxy, QA regional, Claude Desktop, Codex CLI y prueba smoke de CI.