Puppeteer Vision

Extrae páginas web y conviértelas a markdown usando Puppeteer. Cuenta con capacidades de interacción impulsadas por IA.

GitHub
48
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

Servidor MCP de Puppeteer Vision

Este servidor del Protocolo de Contexto de Modelos (MCP) proporciona una herramienta para extraer páginas web y convertirlas a formato markdown utilizando Puppeteer, Readability y Turndown. Cuenta con capacidades de interacción impulsadas por IA para manejar cookies, captchas y otros elementos interactivos automáticamente.

¡Ahora se puede ejecutar fácilmente mediante npx!

Características

  • Extrae páginas web usando Puppeteer con modo sigiloso
  • Utiliza interacción impulsada por IA para manejar automáticamente:
    • Banners de consentimiento de cookies
    • CAPTCHAs
    • Solicitudes de boletines o suscripciones
    • Muros de pago y muros de inicio de sesión
    • Solicitudes de verificación de edad
    • Anuncios intersticiales
    • Cualquier otro elemento interactivo que bloquee el contenido
  • Extrae el contenido principal con Readability de Mozilla
  • Convierte HTML a Markdown bien formateado
  • Manejo especial para bloques de código, tablas y otro contenido estructurado
  • Accesible a través del Protocolo de Contexto de Modelos
  • Opción para ver la interacción del navegador en tiempo real desactivando el modo sin cabeza
  • Fácilmente consumible como paquete npx.

Inicio rápido con NPX

La forma recomendada de usar este servidor es mediante npx, lo que garantiza que estés ejecutando la versión más reciente sin necesidad de clonar o instalar manualmente.

  1. Requisitos previos: Asegúrate de tener Node.js y npm instalados.

  2. Configuración del entorno: El servidor requiere un OPENAI_API_KEY. Puedes proporcionar esta y otras configuraciones opcionales de dos maneras:

    • Archivo .env: Crea un archivo .env en el directorio donde ejecutarás el comando npx.
    • Variables de entorno del shell: Exporta las variables en tu sesión de terminal.

    Ejemplo de archivo .env o exportaciones del shell:

    # Required
OPENAI_API_KEY=your_api_key_here

# Optional (defaults shown)
# VISION_MODEL=gpt-4.1
# API_BASE_URL=https://api.openai.com/v1   # Uncomment to override
# TRANSPORT_TYPE=stdio                     # Options: stdio, sse, http
# USE_SSE=true                             # Deprecated: use TRANSPORT_TYPE=sse instead
# PORT=3001                                # Only used in sse/http modes
# DISABLE_HEADLESS=true                    # Uncomment to see the browser in action

  3. Ejecutar el servidor: Abre tu terminal y ejecuta:

    npx -y puppeteer-vision-mcp-server
    • La bandera -y confirma automáticamente cualquier solicitud de npx.
    • Este comando descargará (si no está en caché) y ejecutará el servidor.
    • Por defecto, se inicia en modo stdio. Establece TRANSPORT_TYPE=sse o TRANSPORT_TYPE=http para los modos de servidor HTTP.

Uso como herramienta MCP con NPX

Este servidor está diseñado para integrarse como una herramienta dentro de un orquestador LLM compatible con MCP. Aquí hay un ejemplo de configuración:

{
  "mcpServers": {
    "web-scraper": {
      "command": "npx",
      "args": ["-y", "puppeteer-vision-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        // Optional:
        // "VISION_MODEL": "gpt-4.1",
        // "API_BASE_URL": "https://api.example.com/v1",
        // "TRANSPORT_TYPE": "stdio", // or "sse" or "http"
        // "DISABLE_HEADLESS": "true" // To see the browser during operations
      }
    }
    // ... other MCP servers
  }
}

Cuando se configura de esta manera, el orquestador MCP gestionará el ciclo de vida del proceso puppeteer-vision-mcp-server.

Detalles de configuración del entorno

Independientemente de cómo ejecutes el servidor (NPX o desarrollo local), utiliza las siguientes variables de entorno:

  • OPENAI_API_KEY: (Requerido) Tu clave de API para acceder al modelo de visión.
  • VISION_MODEL: (Opcional) El modelo a utilizar para el análisis de visión.
    • Predeterminado: gpt-4.1
    • Puede ser cualquier modelo con capacidades de visión.
  • API_BASE_URL: (Opcional) URL personalizada del endpoint de API.
    • Úsalo para conectarte a proveedores alternativos compatibles con OpenAI (por ejemplo, Together.ai, Groq, Anthropic, implementaciones locales).
  • TRANSPORT_TYPE: (Opcional) El protocolo de transporte a utilizar.
    • Opciones: stdio (predeterminado), sse, http
    • stdio: Comunicación directa de procesos (recomendado para la mayoría de los casos de uso)
    • sse: Eventos enviados por el servidor sobre HTTP (modo heredado)
    • http: Transporte HTTP transmisible con gestión de sesiones
  • USE_SSE: (Opcional, obsoleto) Establece true para habilitar el modo SSE sobre HTTP.
    • Obsoleto: Usa TRANSPORT_TYPE=sse en su lugar.
  • PORT: (Opcional) El puerto para el servidor HTTP en modo SSE o HTTP.
    • Predeterminado: 3001.
  • DISABLE_HEADLESS: (Opcional) Establece true para ejecutar el navegador en modo visible.
    • Predeterminado: false (el navegador se ejecuta en modo sin cabeza).

Modos de comunicación

El servidor admite tres modos de comunicación:

  1. stdio (Predeterminado): Se comunica a través de entrada/salida estándar.
    • Perfecto para la integración directa con herramientas LLM que gestionan procesos.
    • Ideal para uso en línea de comandos y scripts.
    • No se inicia ningún servidor HTTP. Este es el modo predeterminado.
  2. Modo SSE: Se comunica a través de Eventos Enviados por el Servidor sobre HTTP.
    • Habilítalo estableciendo TRANSPORT_TYPE=sse en tu entorno.
    • Inicia un servidor HTTP en el PORT especificado (predeterminado: 3001).
    • Úsalo cuando necesites conectarte a la herramienta a través de una red.
    • Conéctate a: http://localhost:3001/sse
  3. Modo HTTP: Se comunica a través de transporte HTTP transmisible con gestión de sesiones.
    • Habilítalo estableciendo TRANSPORT_TYPE=http en tu entorno.
    • Inicia un servidor HTTP en el PORT especificado (predeterminado: 3001).
    • Admite gestión completa de sesiones y conexiones reanudables.
    • Conéctate a: http://localhost:3001/mcp

Uso de la herramienta (Invocación MCP)

El servidor proporciona una herramienta scrape-webpage.

Parámetros de la herramienta:

  • url (cadena, requerido): La URL de la página web a extraer.
  • autoInteract (booleano, opcional, predeterminado: true): Si se deben manejar automáticamente los elementos interactivos.
  • maxInteractionAttempts (número, opcional, predeterminado: 3): Número máximo de intentos de interacción con IA.
  • waitForNetworkIdle (booleano, opcional, predeterminado: true): Si se debe esperar a que la red esté inactiva antes de procesar.

Formato de respuesta:

La herramienta devuelve su resultado en un formato estructurado:

  • content: Una matriz que contiene un solo objeto de texto con el markdown sin procesar de la página web extraída.
  • metadata: Contiene información adicional:
    • message: Mensaje de estado.
    • success: Booleano que indica éxito.
    • contentSize: Tamaño del contenido en caracteres (en caso de éxito).

Ejemplo de respuesta exitosa:

{
  "content": [
    {
      "type": "text",
      "text": "# Page Title\n\nThis is the content..."
    }
  ],
  "metadata": {
    "message": "Scraping successful",
    "success": true,
    "contentSize": 8734
  }
}

Ejemplo de respuesta de error:

{
  "content": [
    {
      "type": "text",
      "text": ""
    }
  ],
  "metadata": {
    "message": "Error scraping webpage: Failed to load the URL",
    "success": false
  }
}

Cómo funciona

Interacción impulsada por IA

El sistema utiliza modelos de IA con capacidades de visión (configurables mediante VISION_MODEL y API_BASE_URL) para analizar capturas de pantalla de páginas web y decidir acciones como hacer clic, escribir o desplazarse para omitir superposiciones y formularios de consentimiento. Este proceso se repite hasta maxInteractionAttempts.

Extracción de contenido

Después de las interacciones, Readability de Mozilla extrae el contenido principal, que luego se sanitiza y se convierte a Markdown usando Turndown con reglas personalizadas para bloques de código y tablas.

Instalación y desarrollo (para modificar el código)

Si deseas contribuir, modificar el servidor o ejecutar una versión de desarrollo local:

  1. Clonar el repositorio:

    git clone https://github.com/djannot/puppeteer-vision-mcp.git
cd puppeteer-vision-mcp

  2. Instalar dependencias:

    npm install

  3. Compilar el proyecto:

    npm run build

  4. Configurar el entorno: Crea un archivo .env en el directorio raíz del proyecto con tu OPENAI_API_KEY y cualquier otra configuración deseada (consulta "Detalles de configuración del entorno" arriba).

  5. Ejecutar para desarrollo:

    npm start # Starts the server using the local build

    O, para recompilación automática en cambios:

    npm run dev

Personalización (para desarrolladores)

Puedes modificar el comportamiento del extractor editando:

  • src/ai/vision-analyzer.ts (función analyzePageWithAI): Personaliza el prompt de IA.
  • src/ai/page-interactions.ts (función executeAction): Agrega nuevos tipos de acciones.
  • src/scrapers/webpage-scraper.ts (función visitWebPage): Cambia las opciones de Puppeteer.
  • src/utils/markdown-formatters.ts: Ajusta las reglas de Turndown para la conversión a Markdown.

Dependencias

Las dependencias clave incluyen:

  • @modelcontextprotocol/sdk
  • puppeteer, puppeteer-extra
  • @mozilla/readability, jsdom
  • turndown, sanitize-html
  • openai (o API compatible para modelos de visión)
  • express (para modo SSE)
  • zod