Website Snapshot

Um servidor MCP que fornece capacidades abrangentes de captura de snapshots de sites usando Playwright. Este servidor permite que LLMs capturem e analisem páginas da web por meio de snapshots de acessibilidade estruturados, monitoramento de rede e coleta de mensagens do console.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP Web Snapshot

Um servidor Model Context Protocol (MCP) que fornece recursos abrangentes de snapshot de sites usando Playwright. Este servidor permite que LLMs capturem e analisem páginas da web por meio de snapshots estruturados de acessibilidade, monitoramento de rede e coleta de mensagens do console.

Principais Recursos

🚀 Rápido e leve: Usa a árvore de acessibilidade do Playwright para snapshots eficientes
🎯 Otimizado para LLM: Saída de dados estruturados projetada especificamente para consumo por IA
📊 Monitoramento abrangente: Captura requisições de rede, respostas e mensagens do console
🔍 Referências de elementos: Adiciona identificadores únicos a elementos interativos para direcionamento preciso
🛡️ Pronto para produção: Tratamento de erros integrado, limites de recursos e gerenciamento de timeout
✅ Bem testado: Suíte de testes abrangente com cobertura de código

Requisitos

Python 3.11 ou mais recente
VS Code, Cursor, Windsurf, Claude Desktop ou qualquer outro cliente MCP

Começando

Primeiro, instale o servidor MCP Web Snapshot com seu cliente. Uma configuração típica se parece com isto:

{
  "mcpServers": {
    "mcp-web-snapshot": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-web-snapshot",
        "run",
        "python",
        "src/server.py"
      ]
    }
  }
}

Instalar no VS Code

Você pode instalar o servidor MCP Web Snapshot usando a CLI do VS Code:

# For VS Code
code --add-mcp '{"name":"mcp-web-snapshot","command":"uv","args":["--directory","/path/to/mcp-web-snapshot","run","python","src/server.py"]}'

Após a instalação, o servidor MCP Web Snapshot estará disponível para uso com seu agente GitHub Copilot no VS Code.

Instalar no Cursor

Vá para Cursor Settings → MCP → Add new MCP Server. Dê um nome de sua preferência, use o tipo command com o comando uv e argumentos ["--directory", "/path/to/mcp-web-snapshot", "run", "python", "src/server.py"].

{
  "mcpServers": {
    "mcp-web-snapshot": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-web-snapshot",
        "run",
        "python",
        "src/server.py"
      ]
    }
  }
}

Configuração de Desenvolvimento

Instalação Local

Clone este repositório:

git clone https://github.com/your-username/mcp-web-snapshot.git
cd mcp-web-snapshot

Instale as dependências usando uv:

uv sync

Instale os navegadores do Playwright:

uv run playwright install

Execute o servidor:

uv run python src/server.py

Estrutura do Projeto

├── src/
│   ├── server.py               # Main MCP server entry point
│   ├── registry.py             # Tool registration logic
│   └── tools/
│       ├── __init__.py
│       └── snapshot_url.py     # Web snapshot implementation
├── tests/                      # Test suite
│   ├── __init__.py
│   ├── test_snapshot_url.py    # Unit tests for website_snapshot
│   └── README.md               # Test documentation
├── pyproject.toml              # Project configuration
├── pytest.ini                  # Pytest configuration
├── uv.lock                     # Lock file for dependencies
└── README.md                   # This file

Testes

O projeto inclui uma suíte de testes abrangente usando pytest:

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run with coverage report
PYTHONPATH=. uv run pytest --cov=src.tools.snapshot_url --cov-report=term-missing

A cobertura de testes atualmente está em 92%, cobrindo:

Captura e formatação bem-sucedidas de snapshots
Monitoramento de requisições de rede e mensagens do console
Validação de URLs
Tratamento de erros e recuperação

Ferramentas Disponíveis

Website Snapshot

Ferramenta: website_snapshot

Descrição: Tire snapshots abrangentes de páginas da web com recursos de monitoramento

Parâmetros:

target_url (string): A URL a ser capturada (deve ser uma URL válida com protocolo)

Recursos:

🎭 Snapshot de Acessibilidade: Captura a estrutura completa da árvore de acessibilidade
🌐 Monitoramento de Rede: Registra todas as requisições e respostas de rede durante o carregamento da página
🖥️ Mensagens do Console: Captura a saída do console do lado do cliente (logs, avisos, erros)
🎯 Referências de Elementos: Adiciona IDs de referência únicos a elementos interativos
📊 Métricas de Desempenho: Fornece resumo dos elementos capturados e atividade de rede

Exemplo de Uso:

# Through MCP client
result = await website_snapshot("https://example.com")

Estrutura de Saída:

✅ Captured snapshot with 25 elements, 12 requests, 0 console messages
🔍 Example Website - Home Page
📍 https://example.com

🎭 Accessibility Snapshot:
- navigation "Main":
  - link "Home": [ref=1]
  - link "About": [ref=2]
  - button "Contact" [ref=3]
- main:
  - heading "Welcome to Example"
  - link "Get Started": [ref=4]

🌐 Network Requests:
🌐 GET https://example.com
   Status: 200
   Response: <!DOCTYPE html><html>...

🖥️ Console:
No console messages

🎯 Element References:
[ref=1]: link "Home"
[ref=2]: link "About"
[ref=3]: button "Contact"
[ref=4]: link "Get Started"

Configuração

O servidor pode ser configurado através do dicionário CONFIG em src/tools/snapshot_url.py:

CONFIG = {
    "viewport": {"width": 1920, "height": 1080},
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
    "timeout": 15000,  # 15 seconds
}

Opções de Personalização

Tamanho da Viewport: Ajuste as dimensões da janela do navegador
User Agent: Personalize a identificação do navegador
Timeout: Controle o tempo máximo de espera para operações de página
Filtragem de Conteúdo: Modifique os limites de tamanho do corpo da resposta e filtros de tipo de conteúdo

Casos de Uso

Testes Guiados por LLM

Capture o estado abrangente da página para geração automatizada de testes:

"Please take a snapshot of https://myapp.com/login and help me create Page Object Model classes based on the discovered elements and structure."

Análise de Conteúdo Web

Extraia dados estruturados para análise e monitoramento de conteúdo:

"Take a snapshot of https://competitor.com/pricing and analyze any pricing changes or new features compared to what we discussed last week."

Auditoria de Acessibilidade

Aproveite os dados da árvore de acessibilidade para verificação de conformidade:

"Please capture a snapshot of https://myapp.com and identify any accessibility issues or areas for improvement based on WCAG guidelines."

Análise de Integração de API

Monitore a atividade de rede para entender o comportamento da aplicação:

"Take a snapshot of https://dashboard.example.com after I log in and show me what API calls are being made so I can understand the data flow."

Configuração de Testes Cross-Browser

Gere cenários de teste com base nas interações capturadas:

"Snapshot https://myapp.com/checkout and help me create comprehensive test cases that cover all the interactive elements and user workflows."

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

URLs Inválidas: Retorna mensagens de erro úteis para URLs malformadas
Timeouts de Rede: Limites de timeout configuráveis com fallbacks graciosos
Crashs do Navegador: Limpeza automática e gerenciamento de recursos
Limites de Conteúdo: Filtragem inteligente de corpos de resposta grandes para evitar problemas de memória

Contribuindo

Faça um fork do repositório
Crie um branch de recurso: git checkout -b feature-name
Faça suas alterações e adicione testes
Execute os testes: uv run pytest
Verifique a cobertura de testes: PYTHONPATH=. uv run pytest --cov=src.tools.snapshot_url --cov-report=term-missing
Garanta a conformidade com o estilo de código: uv run ruff check
Envie um pull request

Por favor, garanta que todos os testes passem e mantenha ou melhore a cobertura de testes atual.

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Agradecimentos

Inspirado pelo artigo MCP Server Website Snapshot
Construído sobre a base do Playwright MCP da Microsoft
Desenvolvido com Playwright para automação confiável de navegadores
Usa Model Context Protocol para integração com LLM

Projetos Relacionados

Playwright MCP - Servidor MCP de automação interativa de navegador
MCP Python SDK - Framework Python para servidores MCP