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.

Si CloakBrowser rechaza la clave de licencia proporcionada, no puede validarla o no puede comunicarse con su servidor de licencias, el inicio falla con el error explícito de CloakBrowser. El puente conserva ese error: no lo oculta ni cambia silenciosamente a otro navegador o nivel de licencia.

CDP gestionado¶

El acceso administrado al Protocolo de Chrome DevTools (CDP) es una opción explícita de aceptación. Expone el misma generación de navegador Chromium controlada por MCP a través de una capacidad portadora descubrimiento URL. Configurar solo un grupo de puertos no habilita CDP.

Cada valor CLI anula únicamente su variable de entorno correspondiente. En particular, --no-cdp-enabled reemplaza a CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true, y --no-cdp-allow-remote anula CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true. Una sesión habilitada sin un grupo de puertos es rechazada antes de que su hijo ascendente comience. Un valor falso eficaz no crea ningún oyente, arrendamiento de puerto ni capacidad.

Para stdio, el valor del proceso se aplica directamente:

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

Para Streamable HTTP, el booleano plano cdpEnabled en el autenticado Los metadatos initialize anulan el valor predeterminado del proceso para esa sesión. Omitir el el campo hereda el valor del proceso. Estos ejemplos optan explícitamente por una sesión y otro fuera:

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

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

Una sesión CDP habilitada con HTTP posee un arrendamiento de puerto externo. Las sesiones deshabilitadas no lo hacen consume la piscina. La asignación es local al proceso, selecciona el candidato no arrendado más bajo, y falla esa sesión inmediatamente si el puerto externo seleccionado ya está ocupado. Cierre sesiones para liberar puertos o configure un rango más grande cuando el grupo esté agotado.

Recupere el URL actual de cloakbrowser_bridge_info, luego pase su structuredContent.cdp.discoveryUrl a un cliente CDP como el de Playwright chromium.connectOverCDP(). Trata ese URL como una credencial: incluye un aleatorio capacidad por generación y se vuelve obsoleta después del reemplazo del navegador. CDP gestionado es no es un endpoint del servidor Playwright. chromium.connect() y el Open WebUI actual El flujo PLAYWRIGHT_WS_URL no es compatible.

--cdp-advertised-scheme https publica https descubrimiento y wss WebSocket URLs solo. El puente no proporciona TLS para CDP gestionado: su oyente externo y Chromium mantener la parte en texto claro HTTP/WebSocket. Un terminador TLS propiedad del operador debe escuchar en el mismo puerto arrendado anunciado, preservar los anuncios Host y Origin autoridad, y reenviar uno a uno a ese oyente de texto plano de la sesión.

La habilitación de CDP comienza Chromium durante la inicialización de MCP, por lo que la propiedad y externa se puede verificar la preparación. Configure el tiempo de espera de inicialización del cliente MCP a al menos 60 segundos. Cuando se habilita CDP gestionado, suministrado por el usuario CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS no debe contener --remote-debugging-port, --remote-debugging-address, o --remote-debugging-pipe (incluyendo las formas =). El propio Playwright mantiene interno --remote-debugging-pipe activado junto con el punto final TCP de bucle invertido gestionado por el puente.

Ver Herramientas, Docker, Seguridad, y Arquitectura para el estado de descubrimiento, despliegue, límites y comportamiento de reinicio.

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.

Binario personalizado de CloakBrowser¶

--binary-path <path> selecciona un ejecutable personalizado de CloakBrowser para el proceso actual del puente. CLOAKBROWSER_BINARY_PATH ofrece el mismo ajuste para despliegues basados en variables de entorno; la opción de CLI tiene prioridad. El puente resuelve la ruta, exige un archivo regular legible y la escribe en browser.launchOptions.executablePath de la configuración generada de Playwright MCP.

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

El puente no descarga ni actualiza un ejecutable personalizado. Si no se selecciona una ruta, CLOAKBROWSER_VERSION puede fijar la versión del binario administrado por CloakBrowser.

En Streamable HTTP, el binario seleccionado pertenece al proceso del puente y se usa en todas las sesiones MCP que crea. Los metadatos de initialize no pueden seleccionar ni reemplazar una ruta ejecutable; ejecute procesos separados para usar binarios distintos.

Cuando el binario seleccionado implementa document.modelContext, el Playwright MCP de origen puede añadir herramientas webmcp_<page-tool> después de una instantánea de página. Envía tools/list_changed; el puente reenvía la notificación y la lista de herramientas actualizada. La página define el nombre y el esquema de cada herramienta dinámica.

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.

La coincidencia funciona en modo fail-closed: si CloakBrowser no puede resolver la IP de salida del proxy, la base de datos GeoIP, la zona horaria o la configuración regional, el navegador no se inicia con una huella parcialmente coincidente. La resolución de GeoIP tiene un máximo de 20 segundos; la primera descarga de la base de datos GeoIP sin conexión es independiente y puede tardar más.

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.

Modo de conexión Playwright Extension¶

Este modo se conecta mediante la extensión oficial de Playwright ya instalada en un perfil de Chrome o Edge y es distinto de cargar extensiones desempaquetadas con CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS. Para stdio, configura PLAYWRIGHT_MCP_EXTENSION=true, PLAYWRIGHT_MCP_EXTENSION_TOKEN, PLAYWRIGHT_MCP_USER_DATA_DIR y, si hace falta, un solo segmento relativo en PLAYWRIGHT_MCP_PROFILE_DIR_NAME. En Streamable HTTP, los metadatos extensionMode, profileDirName y userDataDir sustituyen los valores del proceso, pero el token solo se acepta desde el entorno del proceso. Las sesiones paralelas deben usar distintos userDataDir; las opciones de launch, CDP, proxy, GeoIP, humanization, context y extensionPaths son incompatibles.

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.

En Docker, headless: false inicia una pantalla virtual privada bajo demanda. Fuera de la imagen, una sesión con interfaz gráfica todavía requiere un entorno de pantalla utilizable.

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.

PLAYWRIGHT_MCP_CAPS=devtools se hereda en el proceso hijo upstream y habilita las herramientas controladas por esa capacidad sin una opción --caps propia del puente.

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.