just-every/mcp-screenshot-website-fast

Captura de screenshot de alta qualidade otimizada para a API Claude Vision. Divide automaticamente páginas completas em blocos de 1072x1072 (1,15 megapixels) com viewports configuráveis e estratégias de espera para conteúdo dinâmico.

GitHub
108
Experimente este MCPPatrocinado

Documentação

@just-every/mcp-screenshot-website-fast

Captura de screenshots de páginas web rápida e eficiente - otimizada para ferramentas de codificação CLI. Divide automaticamente páginas inteiras em blocos de 1072x1072 para processamento ideal.

Screenshot Website Fast MCP server

npm version GitHub Actions

Visão Geral

Construída especificamente para fluxos de trabalho de visão de IA, esta ferramenta captura screenshots de alta qualidade com limitação automática de resolução e divisão em blocos para processamento ideal pela Claude Vision API e outros modelos de IA. Garante que os screenshots sejam perfeitamente dimensionados em 1072x1072 pixels (1,15 megapixels) para máxima compatibilidade.

Recursos

  • 📸 Captura rápida de screenshots usando o navegador headless Puppeteer
  • 🎯 Otimizado para Claude Vision com limitação automática de resolução (1072x1072 para 1,15 megapixels ideais)
  • 🔲 Divisão automática em blocos - Páginas inteiras são automaticamente divididas em blocos de 1072x1072
  • 🎬 Captura de screencast - Grave uma série de screenshots ao longo do tempo com intervalos configuráveis
  • 🔄 Conteúdo sempre atualizado - Sem cache garante screenshots atualizados
  • 📱 Viewports configuráveis para testes responsivos
  • ⏱️ Estratégias de espera para conteúdo dinâmico (networkidle, atrasos personalizados)
  • 📄 Captura de página inteira por padrão para screenshots completos
  • 🎥 Exportação em WebP animado - Salve screencasts como arquivos WebP animados de alta qualidade
  • 💉 Injeção de JavaScript - Execute JS personalizado antes da captura de screencast
  • 📦 Dependências mínimas para instalações npm rápidas
  • 🔌 Integração MCP para fluxos de trabalho de IA sem interrupções
  • 🪟 Inicializador compatível com Windows para uso de MCP instalado via npm
  • 🔋 Eficiente em recursos - Limpeza automática do navegador após 60 segundos de inatividade
  • 🧹 Gerenciamento de memória - As páginas são fechadas após cada screenshot para evitar vazamentos

Instalação

Claude Code

claude mcp add screenshot-website-fast -s user -- npx -y @just-every/mcp-screenshot-website-fast

VS Code

code --add-mcp '{"name":"screenshot-website-fast","command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}'

Cursor

cursor://anysphere.cursor-deeplink/mcp/install?name=screenshot-website-fast&config=eyJzY3JlZW5zaG90LXdlYnNpdGUtZmFzdCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqdXN0LWV2ZXJ5L21jcC1zY3JlZW5zaG90LXdlYnNpdGUtZmFzdCJdfX0=

IDEs JetBrains

Configurações → Ferramentas → Assistente de IA → Model Context Protocol (MCP) → Adicionar

Escolha "Como JSON" e cole:

{"command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}

JSON bruto (funciona em qualquer cliente MCP)

{
  "mcpServers": {
    "screenshot-website-fast": {
      "command": "npx",
      "args": ["-y", "@just-every/mcp-screenshot-website-fast"]
    }
  }
}

Coloque isso no mcp.json do seu cliente (por exemplo, .vscode/mcp.json, ~/.cursor/mcp.json ou .mcp.json para Claude).

Pré-requisitos

  • Node.js 20.x ou superior
  • npm ou npx
  • Chrome/Chromium (baixado automaticamente pelo Puppeteer)

Início Rápido

Uso do Servidor MCP

Uma vez instalado no seu IDE, as seguintes ferramentas estão disponíveis:

Ferramentas Disponíveis

  • take_screenshot - Captura um screenshot de alta qualidade de uma página web

    • Parâmetros:
      • url (obrigatório): A URL HTTP/HTTPS a ser capturada
      • width (opcional): Largura do viewport em pixels (máx. 1072, padrão: 1072)
      • height (opcional): Altura do viewport em pixels (máx. 1072, padrão: 1072)
      • fullPage (opcional): Capturar screenshot da página inteira com divisão em blocos (padrão: true)
      • waitUntil (opcional): Aguardar até o evento: load, domcontentloaded, networkidle0, networkidle2 (padrão: domcontentloaded)
      • waitFor (opcional): Tempo de espera adicional em milissegundos
      • directory (opcional): Diretório para salvar screenshots - retorna caminhos de arquivo em vez de imagens base64

  • capture_selector - Captura um screenshot de um elemento DOM específico correspondente a um seletor CSS

    • Parâmetros:
      • url (obrigatório): A URL HTTP/HTTPS a ser capturada
      • selector (obrigatório): Seletor CSS para o elemento a ser capturado
      • width (opcional): Largura do viewport em pixels (máx. 1072, padrão: 1072)
      • height (opcional): Altura do viewport em pixels (máx. 1072, padrão: 1072)
      • waitUntil (opcional): Aguardar até o evento: load, domcontentloaded, networkidle0, networkidle2 (padrão: domcontentloaded)
      • waitForMS (opcional): Tempo de espera adicional em milissegundos
      • selectorTimeoutMS (opcional): Quanto tempo esperar pelo seletor antes de falhar (padrão: 5000)

Exemplos de Uso

Uso padrão (retorna imagens base64):

take_screenshot(url="https://example.com")

Salvar em diretório (retorna caminhos de arquivo):

take_screenshot(url="https://example.com", directory="/path/to/screenshots")

Capturar um elemento específico:

capture_selector(url="https://example.com", selector="#main")

Ao usar o parâmetro directory:

  • Os screenshots são salvos como arquivos PNG com carimbos de data/hora
  • Os caminhos dos arquivos são retornados em vez de dados base64
  • Para screenshots divididos em blocos, cada bloco é salvo como um arquivo separado
  • O diretório é criado automaticamente se não existir

take_screencast

Captura uma série de screenshots ao longo do tempo para criar um screencast. Captura apenas o bloco superior (1072x1072) do viewport.

Parâmetros

  • url (obrigatório): A URL a ser capturada
  • duration (opcional): Duração total em segundos (padrão: 10)
  • interval (opcional): Intervalo entre screenshots em segundos (padrão: 2)
  • jsEvaluate (opcional): Código JavaScript a ser executado no início
  • waitUntil (opcional): Estratégia de espera: 'load', 'domcontentloaded', 'networkidle0', 'networkidle2'
  • waitForMS (opcional): Tempo de espera adicional antes de iniciar
  • directory (opcional): Salvar como WebP animado em diretório (captura a cada 1 segundo)

Exemplos de Uso

Screencast básico (5 quadros em 10 segundos):

take_screencast(url="https://example.com")

Tempo personalizado:

take_screencast(url="https://example.com", duration=15, interval=3)

Com execução de JavaScript:

take_screencast(
  url="https://example.com",
  jsEvaluate="document.body.style.backgroundColor = 'red';"
)

Salvar como WebP animado:

take_screencast(url="https://example.com", directory="/path/to/output")

Ao usar o parâmetro directory:

  • Um WebP animado é criado com intervalos de 1 segundo
  • Os quadros individuais também são salvos como arquivos PNG
  • A animação se repete para sempre por padrão
  • O WebP oferece excelente qualidade:
    • Suporte total a cores (sem limitação de 256 cores)
    • Compressão eficiente para animações web
    • Perfeito para fundos com gradiente e animações suaves
    • Tamanhos de arquivo menores em comparação com GIF, com melhor qualidade

Uso em Desenvolvimento

Instalação

npm install
npm run build

Capturar screenshot

# Full page with automatic tiling (default)
npm run dev capture https://example.com -o screenshot.png

# Viewport-only screenshot  
npm run dev capture https://example.com --no-full-page -o screenshot.png

# Wait for specific conditions
npm run dev capture https://example.com --wait-until networkidle0 --wait-for 2000 -o screenshot.png

Opções de CLI

  • -w, --width <pixels> - Largura do viewport (máx. 1072, padrão: 1072)
  • -h, --height <pixels> - Altura do viewport (máx. 1072, padrão: 1072)
  • --no-full-page - Desativar captura de página inteira e divisão em blocos
  • --wait-until <event> - Aguardar até o evento: load, domcontentloaded, networkidle0, networkidle2
  • --wait-for <ms> - Tempo de espera adicional em milissegundos
  • -o, --output <path> - Caminho do arquivo de saída (obrigatório para saída dividida em blocos)

Recurso de Reinício Automático

O servidor MCP inclui capacidade de reinício automático por padrão para maior confiabilidade:

  • Reinicia automaticamente o servidor se ele travar
  • Lida com exceções não tratadas e rejeições de promessas
  • Implementa backoff exponencial (máx. 10 tentativas em 1 minuto)
  • Registra todas as tentativas de reinício para monitoramento
  • Lida graciosamente com sinais de desligamento (SIGINT, SIGTERM)

Para desenvolvimento/depuração sem reinício automático:

# Run directly without restart wrapper
npm run serve:dev

Arquitetura

mcp-screenshot-website-fast/
├── src/
│   ├── internal/       # Core screenshot capture logic
│   ├── utils/          # Logger and utilities
│   ├── index.ts        # CLI entry point
│   ├── serve.ts        # MCP server entry point
│   └── serve-restart.ts # Auto-restart wrapper

Desenvolvimento

# Run in development mode
npm run dev capture https://example.com -o screenshot.png

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

Por Que Esta Ferramenta?

Construída especificamente para fluxos de trabalho de visão de IA:

  1. Otimizada para Claude Vision API - Limitação automática de resolução para 1072x1072 pixels (1,15 megapixels)
  2. Divisão automática em blocos - Páginas inteiras divididas em blocos perfeitos para processamento de IA
  3. Sempre atualizada - Sem cache garante que você obtenha o conteúdo mais recente
  4. MCP nativo - Integração de primeira classe com ferramentas de desenvolvimento de IA
  5. API simples - Interface limpa e direta para capturar screenshots

Contribuindo

Contribuições são bem-vindas! Por favor:

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Adicione testes para novas funcionalidades
  4. Envie um pull request

Solução de Problemas

Problemas com Puppeteer

  • Certifique-se de que o Chrome/Chromium possa ser baixado
  • Verifique as configurações do firewall
  • Tente definir PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true e fornecer um executável personalizado

Qualidade do Screenshot

  • Ajuste as dimensões do viewport
  • Use estratégias de espera apropriadas
  • Verifique se o site requer autenticação

Erros de Tempo Limite

  • Aumente o tempo de espera com a flag --wait-for
  • Use diferentes estratégias de --wait-until
  • Verifique se o site está acessível

Licença

MIT