BrowserLoop

Toma capturas de pantalla y lee registros de consola de páginas web usando Playwright.

Documentación

BrowserLoop

⚠️ ARCHIVADO: Este proyecto está archivado y no recibirá más actualizaciones. Con el lanzamiento de Chrome DevTools MCP, ya no es necesario un servidor MCP dedicado para la automatización del navegador, ya que ese proyecto ofrece capacidades de interacción con el navegador más completas, incluyendo capturas de pantalla, monitoreo de consola y mucho más.

Un servidor de Protocolo de Contexto de Modelo (MCP) para tomar capturas de pantalla y leer registros de consola de páginas web usando Playwright. Esta herramienta permite a los agentes de IA capturar automáticamente capturas de pantalla y monitorear la salida de la consola del navegador para tareas de depuración, pruebas y desarrollo.

NOTA: Casi todo el código de este repositorio ha sido generado automáticamente. Eso significa que probablemente no deberías confiar demasiado en él. Dicho esto, funciona y lo estoy usando yo mismo.

NOTA: Si la documentación es incorrecta, por favor házmelo saber o envía un PR. Si también quieres usar una herramienta de generación de código para actualizar el código de este proyecto, PROJECT_CONTEXT.md se ha utilizado como contexto para dar una buena visión general de las diversas partes del proyecto. Puede estar un poco desordenado ahora, pero es un buen punto de partida y eres bienvenido a actualizarlo.

Características

📸 Captura de pantalla de alta calidad usando Playwright
📝 Monitoreo y recopilación de registros de consola de páginas web
🌐 Soporte para localhost y URLs remotas
🍪 Autenticación basada en cookies para páginas protegidas
🐳 Contenerización con Docker para entornos consistentes
⚡ Soporte de formatos PNG, JPEG y WebP con calidad configurable
🛡️ Ejecución segura de contenedores sin root
🤖 Integración completa del protocolo MCP con herramientas de desarrollo de IA
🔧 Tamaños de viewport y opciones de captura configurables
📱 Captura de pantalla de página completa y de elementos específicos
⚠️ Captura de advertencias y errores del navegador (Permissions-Policy, advertencias de seguridad)
⚡ TypeScript con Biome para desarrollo rápido
🧪 Pruebas exhaustivas con el ejecutor de pruebas integrado de Node.js

Inicio rápido

📦 Uso con NPX (Recomendado)

La forma más fácil de empezar: ¡sin necesidad de instalación!

# Install Chromium browser (one-time setup)
npx playwright install chromium

# Test that BrowserLoop works
npx browserloop@latest --version

¡Eso es todo! La última versión de BrowserLoop se descargará y ejecutará automáticamente. Perfecto para usuarios de MCP que quieren capturas de pantalla sin mantenimiento.

Configuración de MCP

Añade BrowserLoop a tu archivo de configuración de MCP (por ejemplo, ~/.cursor/mcp.json):

{
  "mcpServers": {
    "browserloop": {
      "command": "npx",
      "args": ["-y", "browserloop@latest"],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

💡 Usar @latest asegura que siempre obtengas las funciones más nuevas y correcciones de errores automáticamente.

🚀 Instalación con un clic para Cursor

Añade BrowserLoop a Cursor con un solo clic usando este enlace profundo:

🔗 Añadir BrowserLoop a Cursor

Este enlace profundo configurará automáticamente BrowserLoop en la configuración de MCP de Cursor con la configuración óptima usando npx y la última versión.

Requisitos previos: Asegúrate de tener Chromium instalado primero:

npx playwright install chromium

Requisitos de instalación del navegador

🚨 Crítico: BrowserLoop requiere que Chromium esté instalado a través de Playwright antes de poder tomar capturas de pantalla.

Configuración inicial (todos los usuarios)

Instalar el navegador Chromium:

npx playwright install chromium

Verificar la instalación:

# Check Playwright installation
npx playwright --version

# Test BrowserLoop (if using NPX)
npx browserloop@latest --version

🐳 Alternativa con Docker

Para entornos contenerizados:

# Pull and run with Docker
docker run --rm --network host browserloop

# Or use docker-compose for development
git clone <repository-url>
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 Instalación para desarrollo

Para contribuyentes o usuarios avanzados que quieran compilar desde el código fuente:

# Clone the repository
git clone <repository-url>
cd browserloop

# Install dependencies
npm install

# Install Playwright browsers (required for screenshots)
npx playwright install chromium
# OR use the convenient script:
npm run install-browsers

# Build the project
npm run build

Configuración de MCP para desarrollo

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

Reemplaza /absolute/path/to/browserloop/ con la ruta real de tu proyecto.

Uso básico

Una vez configurado, puedes usar comandos en lenguaje natural en tu herramienta de IA:

Capturas de pantalla

Take a screenshot of https://example.com
Take a screenshot of https://example.com with width 1920 and height 1080
Take a screenshot of https://example.com in JPEG format with 95% quality
Take a full page screenshot of https://example.com
Take a screenshot of http://localhost:3000 to verify the UI changes

Lectura de registros de consola

Read console logs from https://example.com
Check for console errors on https://example.com
Monitor console warnings from http://localhost:3000
Read only error and warning logs from https://example.com
Capture console output from https://example.com for debugging

🔐 Autenticación con cookies

BrowserLoop admite autenticación basada en cookies para capturar pantallas de páginas protegidas por inicio de sesión durante el desarrollo:

Take a screenshot of http://localhost:3000/admin/dashboard using these cookies: [{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]

📖 Para métodos de extracción de cookies y flujos de trabajo de desarrollo, consulta:

📖 Guía de autenticación con cookies

Casos de uso comunes en desarrollo:

Servidores de desarrollo local con autenticación
Pruebas de entornos de staging
Herramientas de documentación de API (Swagger, GraphQL Playground)
Aplicaciones web personalizadas durante el desarrollo
Paneles de administración y rutas protegidas

Documentación

🔐 Guía de autenticación con cookies - Guía completa para capturas de pantalla autenticadas
📚 Referencia completa de la API - Documentación detallada de parámetros, ejemplos y formatos de respuesta

Parámetros clave de la API

Parámetro	Tipo	Descripción	Predeterminado
`url`	string	URL de destino para capturar (obligatorio)	-
`width`	number	Ancho del viewport (200-4000)	1280
`height`	number	Alto del viewport (200-4000)	720
`format`	string	Formato de imagen (webp, png, jpeg)	webp
`quality`	number	Calidad de imagen (1-100)	80
`fullPage`	boolean	Capturar página completa	false
`selector`	string	Selector CSS para captura de elementos	-

📖 Consulta docs/API.md para detalles completos de parámetros, ejemplos de uso y opciones de configuración.

Configuración

BrowserLoop se puede configurar usando variables de entorno:

Configuración básica

Variable	Predeterminado	Descripción
`BROWSERLOOP_DEFAULT_WIDTH`	`1280`	Ancho de viewport predeterminado (200-4000)
`BROWSERLOOP_DEFAULT_HEIGHT`	`720`	Alto de viewport predeterminado (200-4000)
`BROWSERLOOP_DEFAULT_FORMAT`	`webp`	Formato de imagen predeterminado (`webp`, `png`, `jpeg`)
`BROWSERLOOP_DEFAULT_QUALITY`	`80`	Calidad de imagen predeterminada (0-100)
`BROWSERLOOP_DEFAULT_TIMEOUT`	`30000`	Tiempo de espera predeterminado en milisegundos
`BROWSERLOOP_USER_AGENT`	-	Cadena de agente de usuario personalizada

Configuración de autenticación

Variable	Predeterminado	Descripción
`BROWSERLOOP_DEFAULT_COOKIES`	-	Cookies predeterminadas como ruta de archivo o cadena JSON (consulta Guía de autenticación con cookies)

Configuración de registros de consola

Variable	Predeterminado	Descripción
`BROWSERLOOP_CONSOLE_LOG_LEVELS`	`log,info,warn,error,debug`	Lista separada por comas de niveles de registro a capturar
`BROWSERLOOP_CONSOLE_TIMEOUT`	`30000`	Tiempo de espera de navegación de página en milisegundos (no el tiempo de recopilación de registros)
`BROWSERLOOP_SANITIZE_LOGS`	`true`	Habilitar/deshabilitar la sanitización de datos sensibles en los registros
`BROWSERLOOP_CONSOLE_WAIT_NETWORK_IDLE`	`true`	Esperar a que la red esté inactiva antes de finalizar la recopilación
`BROWSERLOOP_MAX_LOG_SIZE`	`1048576`	Tamaño máximo total de registro en bytes (1MB)

Nota: La recopilación de registros de consola siempre espera exactamente 3 segundos después de la carga de la página para capturar mensajes de consola. La configuración de tiempo de espera solo afecta cuánto tiempo tiene la página para cargar inicialmente.

Sanitización de registros

La sanitización de registros de consola está habilitada por defecto (BROWSERLOOP_SANITIZE_LOGS=true) para proteger información sensible. Cuando está habilitada, los siguientes patrones se enmascaran automáticamente:

Tipo de patrón	Entrada de ejemplo	Salida enmascarada
Claves de API	`sk_live_1234567890abcdef...`	`[API_KEY_MASKED]`
Direcciones de correo electrónico	`user@example.com`	`[EMAIL_MASKED]`
Tokens JWT	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`	`[JWT_TOKEN_MASKED]`
Encabezados de autenticación	`Bearer abc123token...`	`[AUTH_HEADER_MASKED]`
URLs con autenticación	`https://api.com/data?token=secret123`	`[URL_WITH_AUTH_MASKED]`
Variables secretas	`password: mySecretPass`	`password: [VALUE_MASKED]`

Para deshabilitar la sanitización (para depuración):

BROWSERLOOP_SANITIZE_LOGS=false

Nota: La sanitización preserva la estructura del registro mientras enmascara contenido sensible, haciendo que los registros sean seguros para compartir y analizar.

Rendimiento y fiabilidad

Variable	Predeterminado	Descripción
`BROWSERLOOP_RETRY_COUNT`	`3`	Número de intentos de reintento para operaciones fallidas
`BROWSERLOOP_RETRY_DELAY`	`1000`	Retraso entre reintentos en milisegundos

Registro y depuración

Variable	Predeterminado	Descripción
`BROWSERLOOP_DEBUG`	`false`	Habilitar registro de depuración en `/tmp/browserloop.log`
`BROWSERLOOP_ENABLE_METRICS`	`true`	Habilitar recopilación de métricas de errores
`BROWSERLOOP_DISABLE_FILE_WATCHING`	`false`	Deshabilitar monitoreo automático de archivos de cookies

Registro de depuración

Cuando BROWSERLOOP_DEBUG=true, se escriben registros detallados en /tmp/browserloop.log incluyendo:

Eventos de carga y actualización automática de archivos de cookies
Estado de monitoreo de archivos y eventos de recreación
Detalles de operaciones de captura de pantalla
Cambios de configuración y errores

Monitorear registros en tiempo real:

tail -f /tmp/browserloop.log

Nota: Los registros se escriben en un archivo (no en la consola) para mantener la compatibilidad con el protocolo stdio de MCP.

Ejemplo de configuración de MCP con cookies predeterminadas

Método 1: Archivo JSON (Recomendado)

Crea un archivo de cookies:

// ~/.config/browserloop/cookies.json
[
  {
    "name": "connect.sid",
    "value": "s:your-dev-session.signature",
    "domain": "localhost"
  }
]

Referencia en la configuración de MCP:

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "/home/username/.config/browserloop/cookies.json",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

Método 2: Cadena JSON (Legado)

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "[{\"name\":\"session_id\",\"value\":\"your_session_value\",\"domain\":\"example.com\"},{\"name\":\"auth_token\",\"value\":\"your_auth_token\"}]",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

Ejemplos de configuración de registros de consola

# Only capture warnings and errors
BROWSERLOOP_CONSOLE_LOG_LEVELS="warn,error"

# Debug mode with all logs, no sanitization
BROWSERLOOP_DEBUG="true"
BROWSERLOOP_SANITIZE_LOGS="false"
BROWSERLOOP_CONSOLE_LOG_LEVELS="log,info,warn,error,debug"

Solución de problemas

Problemas comunes

Error "Ejecutable no existe"

# Install Chromium browser (most common fix)
npx playwright install chromium

El servidor MCP no se inicia

Prueba manualmente: npx browserloop@latest --version
Verifica los requisitos:
- Node.js 20+: node --version
- npm: npm --version
- npx: npx --version
Revisa la sintaxis JSON de la configuración de MCP

Las capturas de pantalla muestran páginas de inicio de sesión

Usa autenticación con cookies (consulta Guía de autenticación con cookies)
Verifica la expiración de cookies y la configuración de dominio

Los registros de consola están vacíos

Algunos sitios web de producción no tienen salida de consola (esto es normal)
Prueba con sitios de desarrollo que tengan actividad de consola
Habilita el registro de depuración: BROWSERLOOP_DEBUG=true y revisa /tmp/browserloop.log
Revisa el filtrado de niveles de registro: BROWSERLOOP_CONSOLE_LOG_LEVELS=log,info,warn,error,debug

Tiempo de recopilación de registros de consola

La recopilación siempre espera exactamente 3 segundos después de la carga de la página
BROWSERLOOP_CONSOLE_TIMEOUT controla el tiempo de espera de carga de la página, no el tiempo de recopilación de registros
Los sitios rápidos aún tardarán ~3-4 segundos en total (carga + 3s de recopilación + procesamiento)

Problemas de red/conexión

Prueba primero con URLs externas: https://example.com
Para localhost: asegúrate de que tu servidor de desarrollo esté ejecutándose
Revisa la configuración del firewall

Actualizar BrowserLoop

NPX: Usa automáticamente la última versión con @latest - ¡no se necesitan actualizaciones manuales!
Verificar versión actual: npx browserloop@latest --version

Diagnóstico rápido

# Test complete setup
node --version && npm --version
npx playwright --version

# Test BrowserLoop
npx browserloop@latest --version

Habilitar registro de depuración: Establece BROWSERLOOP_DEBUG=true en tu configuración de MCP y monitorea /tmp/browserloop.log

📖 Consulta docs/API.md#error-handling para solución de problemas detallada.

Licencia

BrowserLoop está licenciado bajo la GNU Affero General Public License v3.0 o posterior (AGPL-3.0-or-later).

Qué significa esto:

✅ Uso gratuito - Se permite uso personal y comercial
✅ Modificación gratuita - Puedes adaptar el código a tus necesidades
✅ Distribución gratuita - Comparte copias con otros
✅ Protección de patentes - Los contribuyentes otorgan licencias de patente
⚠️ Copyleft - Las obras derivadas también deben ser de código abierto bajo AGPL-3.0
⚠️ Cláusula de red - Si ejecutas una versión modificada en un servidor, debes proporcionar el código fuente a los usuarios

Para servicios de red

Importante: Si modificas BrowserLoop y lo ejecutas como un servicio de red (por ejemplo, aplicación web, servidor API o servicio en la nube), la AGPL te exige:

Ofrecer el código fuente completo a todos los usuarios de tu servicio
Incluir un aviso destacado sobre cómo los usuarios pueden acceder al código fuente
Usar una licencia compatible para todo el servicio

Archivos de licencia

LICENSE - Texto completo de la licencia

Uso comercial

Las organizaciones pueden usar BrowserLoop bajo la AGPL con fines comerciales, pero deben cumplir con los requisitos de copyleft. Si necesitas mantener las modificaciones privadas, considera:

Usar BrowserLoop sin modificaciones
Contribuir mejoras a la comunidad
Contactar a los mantenedores sobre posibles acuerdos de licencia alternativos

Para preguntas sobre licencias, abre un issue o contacta a los mantenedores.