Puppeteer Vision

Extraia páginas da web e converta-as para markdown usando Puppeteer. Possui capacidades de interação orientadas por IA.

GitHub
48
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Servidor MCP Puppeteer Vision

Este servidor do Model Context Protocol (MCP) fornece uma ferramenta para extrair páginas da web e convertê-las para o formato markdown usando Puppeteer, Readability e Turndown. Ele possui capacidades de interação orientadas por IA para lidar com cookies, captchas e outros elementos interativos automaticamente.

Agora facilmente executável via npx!

Recursos

  • Extrai páginas da web usando Puppeteer com modo stealth
  • Usa interação orientada por IA para lidar automaticamente com:
    • Banners de consentimento de cookies
    • CAPTCHAs
    • Prompts de newsletter ou assinatura
    • Paywalls e muros de login
    • Prompts de verificação de idade
    • Anúncios intersticiais
    • Quaisquer outros elementos interativos que bloqueiam conteúdo
  • Extrai o conteúdo principal com o Readability da Mozilla
  • Converte HTML para Markdown bem formatado
  • Tratamento especial para blocos de código, tabelas e outros conteúdos estruturados
  • Acessível via Model Context Protocol
  • Opção de visualizar a interação do navegador em tempo real desativando o modo headless
  • Facilmente consumível como um pacote npx.

Início Rápido com NPX

A maneira recomendada de usar este servidor é via npx, o que garante que você esteja executando a versão mais recente sem precisar clonar ou instalar manualmente.

  1. Pré-requisitos: Certifique-se de ter Node.js e npm instalados.

  2. Configuração do Ambiente: O servidor requer um OPENAI_API_KEY. Você pode fornecer esta e outras configurações opcionais de duas maneiras:

    • Arquivo .env: Crie um arquivo .env no diretório onde você executará o comando npx.
    • Variáveis de Ambiente do Shell: Exporte as variáveis na sua sessão de terminal.

    Exemplo de arquivo .env ou exportações do 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. Execute o Servidor: Abra seu terminal e execute:

    npx -y puppeteer-vision-mcp-server
    • A flag -y confirma automaticamente quaisquer prompts do npx.
    • Este comando baixará (se ainda não estiver em cache) e executará o servidor.
    • Por padrão, ele inicia no modo stdio. Defina TRANSPORT_TYPE=sse ou TRANSPORT_TYPE=http para modos de servidor HTTP.

Usando como Ferramenta MCP com NPX

Este servidor é projetado para ser integrado como uma ferramenta dentro de um orquestrador LLM compatível com MCP. Aqui está um exemplo de configuração:

{
  "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
  }
}

Quando configurado desta forma, o orquestrador MCP gerenciará o ciclo de vida do processo puppeteer-vision-mcp-server.

Detalhes da Configuração do Ambiente

Independentemente de como você execute o servidor (NPX ou desenvolvimento local), ele usa as seguintes variáveis de ambiente:

  • OPENAI_API_KEY: (Obrigatório) Sua chave de API para acessar o modelo de visão.
  • VISION_MODEL: (Opcional) O modelo a ser usado para análise de visão.
    • Padrão: gpt-4.1
    • Pode ser qualquer modelo com capacidades de visão.
  • API_BASE_URL: (Opcional) URL personalizada do endpoint da API.
    • Use isto para conectar a provedores alternativos compatíveis com OpenAI (ex.: Together.ai, Groq, Anthropic, implantações locais).
  • TRANSPORT_TYPE: (Opcional) O protocolo de transporte a ser usado.
    • Opções: stdio (padrão), sse, http
    • stdio: Comunicação direta por processo (recomendado para a maioria dos casos de uso)
    • sse: Server-Sent Events sobre HTTP (modo legado)
    • http: Transporte HTTP streamable com gerenciamento de sessão
  • USE_SSE: (Opcional, obsoleto) Defina como true para habilitar o modo SSE sobre HTTP.
    • Obsoleto: Use TRANSPORT_TYPE=sse em vez disso.
  • PORT: (Opcional) A porta para o servidor HTTP no modo SSE ou HTTP.
    • Padrão: 3001.
  • DISABLE_HEADLESS: (Opcional) Defina como true para executar o navegador em modo visível.
    • Padrão: false (o navegador executa em modo headless).

Modos de Comunicação

O servidor suporta três modos de comunicação:

  1. stdio (Padrão): Comunica-se via entrada/saída padrão.
    • Perfeito para integração direta com ferramentas LLM que gerenciam processos.
    • Ideal para uso em linha de comando e scripts.
    • Nenhum servidor HTTP é iniciado. Este é o modo padrão.
  2. Modo SSE: Comunica-se via Server-Sent Events sobre HTTP.
    • Ative definindo TRANSPORT_TYPE=sse no seu ambiente.
    • Inicia um servidor HTTP na PORT especificada (padrão: 3001).
    • Use quando precisar conectar à ferramenta através de uma rede.
    • Conecte-se a: http://localhost:3001/sse
  3. Modo HTTP: Comunica-se via transporte HTTP streamable com gerenciamento de sessão.
    • Ative definindo TRANSPORT_TYPE=http no seu ambiente.
    • Inicia um servidor HTTP na PORT especificada (padrão: 3001).
    • Suporta gerenciamento completo de sessão e conexões retomáveis.
    • Conecte-se a: http://localhost:3001/mcp

Uso da Ferramenta (Invocação MCP)

O servidor fornece uma ferramenta scrape-webpage.

Parâmetros da Ferramenta:

  • url (string, obrigatório): A URL da página da web a ser extraída.
  • autoInteract (booleano, opcional, padrão: true): Se deve lidar automaticamente com elementos interativos.
  • maxInteractionAttempts (número, opcional, padrão: 3): Número máximo de tentativas de interação com IA.
  • waitForNetworkIdle (booleano, opcional, padrão: true): Se deve aguardar a rede ficar ociosa antes de processar.

Formato da Resposta:

A ferramenta retorna seu resultado em um formato estruturado:

  • content: Um array contendo um único objeto de texto com o markdown bruto da página extraída.
  • metadata: Contém informações adicionais:
    • message: Mensagem de status.
    • success: Booleano indicando sucesso.
    • contentSize: Tamanho do conteúdo em caracteres (em caso de sucesso).

Exemplo de Resposta de Sucesso:

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

Exemplo de Resposta de Erro:

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

Como Funciona

Interação Orientada por IA

O sistema usa modelos de IA com capacidade de visão (configuráveis via VISION_MODEL e API_BASE_URL) para analisar capturas de tela de páginas da web e decidir ações como clicar, digitar ou rolar para contornar sobreposições e formulários de consentimento. Este processo se repete até maxInteractionAttempts.

Extração de Conteúdo

Após as interações, o Readability da Mozilla extrai o conteúdo principal, que é então sanitizado e convertido para Markdown usando Turndown com regras personalizadas para blocos de código e tabelas.

Instalação e Desenvolvimento (para Modificar o Código)

Se você deseja contribuir, modificar o servidor ou executar uma versão de desenvolvimento local:

  1. Clone o Repositório:

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

  2. Instale as Dependências:

    npm install

  3. Compile o Projeto:

    npm run build

  4. Configure o Ambiente: Crie um arquivo .env no diretório raiz do projeto com seu OPENAI_API_KEY e quaisquer outras configurações desejadas (veja "Detalhes da Configuração do Ambiente" acima).

  5. Execute para Desenvolvimento:

    npm start # Starts the server using the local build

    Ou, para recompilação automática em mudanças:

    npm run dev

Personalização (para Desenvolvedores)

Você pode modificar o comportamento do extrator editando:

  • src/ai/vision-analyzer.ts (função analyzePageWithAI): Personalize o prompt da IA.
  • src/ai/page-interactions.ts (função executeAction): Adicione novos tipos de ação.
  • src/scrapers/webpage-scraper.ts (função visitWebPage): Altere as opções do Puppeteer.
  • src/utils/markdown-formatters.ts: Ajuste as regras do Turndown para conversão de Markdown.

Dependências

As principais dependências incluem:

  • @modelcontextprotocol/sdk
  • puppeteer, puppeteer-extra
  • @mozilla/readability, jsdom
  • turndown, sanitize-html
  • openai (ou API compatível para modelos de visão)
  • express (para modo SSE)
  • zod