Read Website Fast

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

Extração rápida e eficiente em tokens de conteúdo web para agentes de IA - converte sites em Markdown limpo.

Visão Geral

Os crawlers web MCP existentes são lentos e consomem grandes quantidades de tokens. Isso interrompe o processo de desenvolvimento e fornece resultados incompletos, pois os LLMs precisam analisar páginas web inteiras.

Este pacote MCP busca páginas web localmente, remove ruídos e converte o conteúdo em Markdown limpo, preservando links. Projetado para Claude Code, IDEs e pipelines de LLM com pegada mínima de tokens. Rastreie sites localmente com dependências mínimas.

Nota: Este pacote agora usa @just-every/crawl para sua funcionalidade principal de rastreamento e conversão de Markdown.

Funcionalidades

• Inicialização rápida usando o SDK oficial do MCP com carregamento preguiçoso para desempenho ideal
• Extração de conteúdo usando Mozilla Readability (o mesmo do Firefox Reader View)
• Conversão de HTML para Markdown com suporte a Turndown + GFM
• Cache inteligente com URLs com hash SHA-256
• Rastreamento educado com suporte a robots.txt e limitação de taxa
• Busca concorrente com rastreamento de profundidade configurável
• Design stream-first para baixo uso de memória
• Preservação de links para grafos de conhecimento
• Fragmentação opcional para processamento downstream

Instalação

Claude Code

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

VS Code

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

Cursor

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

IDEs JetBrains

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

Escolha "As JSON" e cole:

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

Ou, na janela de chat, digite /add e preencha o mesmo JSON—ambos os caminhos configuram o servidor em uma única etapa. 

JSON bruto (funciona em qualquer cliente MCP)

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

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

Funcionalidades

• Inicialização rápida usando o SDK oficial do MCP com carregamento preguiçoso para desempenho ideal
• Extração de conteúdo usando Mozilla Readability (o mesmo do Firefox Reader View)
• Conversão de HTML para Markdown com suporte a Turndown + GFM
• Cache inteligente com URLs com hash SHA-256
• Rastreamento educado com suporte a robots.txt e limitação de taxa
• Busca concorrente com rastreamento de profundidade configurável
• Design stream-first para baixo uso de memória
• Preservação de links para grafos de conhecimento
• Fragmentação opcional para processamento downstream

Ferramentas Disponíveis

• read_website - Busca uma página web e a converte em Markdown limpo
  • Parâmetros:
    • url (obrigatório): A URL HTTP/HTTPS a ser buscada
    • pages (opcional): Número máximo de páginas a rastrear (padrão: 1, máximo: 100)

Recursos Disponíveis

• read-website-fast://status - Obter estatísticas do cache
• read-website-fast://clear-cache - Limpar o diretório de cache

Uso em Desenvolvimento

Instalação

npm install
npm run build

Busca de página única

npm run dev fetch https://example.com/article

Rastreamento com profundidade

npm run dev fetch https://example.com --depth 2 --concurrency 5

Formatos de saída

# Markdown only (default)
npm run dev fetch https://example.com

# JSON output with metadata
npm run dev fetch https://example.com --output json

# Both URL and markdown
npm run dev fetch https://example.com --output both

Opções de CLI

• -p, --pages <number> - Número máximo de páginas a rastrear (padrão: 1)
• -c, --concurrency <number> - Máximo de requisições concorrentes (padrão: 3)
• --no-robots - Ignorar robots.txt
• --all-origins - Permitir rastreamento entre origens
• -u, --user-agent <string> - User agent personalizado
• --cache-dir <path> - Diretório de cache (padrão: .cache)
• -t, --timeout <ms> - Tempo limite de requisição em milissegundos (padrão: 30000)
• -o, --output <format> - Formato de saída: json, markdown ou ambos (padrão: markdown)

Limpar cache

npm run dev clear-cache

Recurso de Reinicialização Automática

O servidor MCP inclui capacidade de reinicialização automática por padrão para maior confiabilidade:

• Reinicia automaticamente o servidor se ele falhar
• Lida com exceções não tratadas e rejeições de promises
• Implementa backoff exponencial (máximo de 10 tentativas em 1 minuto)
• Registra todas as tentativas de reinicialização para monitoramento
• Lida graciosamente com sinais de desligamento (SIGINT, SIGTERM)

Para desenvolvimento/depuração sem reinicialização automática:

# Run directly without restart wrapper
npm run serve:dev

Arquitetura

mcp/
├── src/
│   ├── crawler/        # URL fetching, queue management, robots.txt
│   ├── parser/         # DOM parsing, Readability, Turndown conversion
│   ├── cache/          # Disk-based caching with SHA-256 keys
│   ├── utils/          # Logger, chunker 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 fetch https://example.com

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

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 de Cache

npm run dev clear-cache

Erros de Tempo Limite

• Aumente o tempo limite com a flag -t
• Verifique a conectividade de rede
• Verifique se a URL está acessível

Conteúdo Não Extraído

• Alguns sites bloqueiam acesso automatizado
• Tente um user agent personalizado com a flag -u
• Verifique se o site requer JavaScript (não suportado)

Licença

MIT