Web-curl

Web-curl

Desenvolvido por Rayss

🚀 Projeto Open Source
🛠️ Construído com Node.js & TypeScript (Node.js v18+ necessário)

🎬 Vídeo de Demonstração

Clique aqui para assistir ao vídeo de demonstração diretamente no seu navegador.

Se a sua plataforma suportar, você também pode baixar e reproduzir demo/demo.mp4 diretamente.

📚 Sumário

• Changelog / Histórico de Atualizações
• Visão Geral
• Recursos
• Arquitetura
• Instalação
• Uso
• Uso via CLI
• Uso como Servidor MCP
• Configuração
• Exemplos
• Solução de Problemas
• Dicas e Boas Práticas
• Contribuição e Problemas
• Publicação Acadêmica
• Licença e Atribuição

📝 Changelog / Histórico de Atualizações

Consulte CHANGELOG.md para um histórico completo de atualizações e novos recursos.

📝 Visão Geral

Web-curl é uma ferramenta poderosa para buscar e extrair conteúdo de texto de páginas web e APIs. Use-a como CLI autônoma ou como um servidor MCP (Model Context Protocol). O Web-curl utiliza Puppeteer para raspagem web robusta e suporta recursos avançados como bloqueio de recursos, cabeçalhos personalizados, autenticação e integração com API de Busca Externa.

✨ Recursos

🚀 Pesquisa Avançada e Automação (v1.4.2)

• Automação Avançada de Navegador: Controle total sobre o Chromium via Puppeteer (clique, digitação, rolagem, passar o mouse, pressionamentos de teclas).
• Persistência de Sessão Sempre Ativa: Os perfis do navegador agora são sempre persistentes. Sessões de login, cookies e cache são salvos automaticamente em um diretório local user_data/.
• Snapshots Eficientes em Tokens (disponíveis através do manipulador oculto browser_snapshot):
  • Árvore de Acessibilidade: Snapshots limpos e estruturados em vez de HTML bagunçado.
  • Modo de Fatia HTML: HTML bruto com startIndex/endIndex para divisão segura em blocos quando necessário.
• Integração com Chrome DevTools (implementada, mas oculta do list_tools):
  • Monitoramento de Rede (browser_network_requests)
  • Logs de Console (browser_console_messages)
• API de Busca Externa:
  • multi_search: Executa múltiplas consultas em paralelo usando uma API de busca externa configurada.
• Gerenciamento Inteligente de Recursos:
  • Fechamento Automático por Inatividade: O navegador é desligado automaticamente após 15 minutos de inatividade para economizar RAM/CPU.
  • Rotação de Abas: Substitui automaticamente a aba mais antiga quando o limite de 10 abas é atingido.
• Mídia e Documentos:
  • Capturas de Tela de Página Inteira: Capture capturas de tela de alta qualidade com ciclo de vida de limpeza automática de 5 dias e suporte a destino personalizado.
  • Análise de Documentos: Extraia texto de arquivos PDF e DOCX diretamente de URLs.

Detalhes de Armazenamento e Download

• 🗂️ Rotação de logs de erro: logs/error-log.txt é rotacionado quando excede ~1MB (renomeado para error-log.txt.bak) para evitar crescimento ilimitado.
• 🧹 Limpeza de logs e temporários: arquivos temporários antigos no diretório logs/ são limpos na inicialização.
• 🛑 Ciclo de vida do navegador: instâncias do navegador Puppeteer são fechadas em blocos finally para evitar vazamentos de arquivos temporários do Chromium.
• 🔎 Extração de conteúdo:
  • Retorna texto bruto, HTML e "artigo principal" do Readability quando disponível. O Readability tenta extrair o conteúdo primário de uma página web, removendo cabeçalhos, rodapés, barras laterais e outros elementos não essenciais, fornecendo um texto mais limpo e focado.
  • A saída do Readability está sujeita ao fatiamento startIndex/maxLength/chunkSize quando solicitado.
• ⏱️ Controle de tempo limite: os tempos limite de navegação e solicitações de API são configuráveis via argumentos da ferramenta.
• 💾 Saída: os resultados podem ser impressos no stdout ou gravados em um arquivo via opções da CLI.
• ⬇️ Comportamento de download (download_file):
  • destinationFolder aceita caminhos relativos (resolvidos em relação à raiz do projeto) ou caminhos absolutos.
  • O servidor cria destinationFolder se não existir.
  • Os downloads são transmitidos usando streams do Node + pipeline para minimizar o uso de memória e garantir gravações robustas.
  • Os nomes de arquivo são derivados do caminho da URL (por exemplo, https://.../path/file.jpg -> file.jpg). Se nenhum nome de arquivo estiver presente, o nome de fallback é downloaded_file.
  • Semântica de sobrescrita: por padrão, a implementação sobrescreverá um arquivo existente com o mesmo nome.
• 🖥️ Modos de uso: CLI e servidor MCP (transporte stdin/stdout).
• 🌐 Cliente REST: fetch_api tenta um GET direto primeiro e usa a busca web da API Externa configurada quando a solicitação falha ou retorna uma resposta não-2xx. Métodos não-GET são enviados diretamente.
• 🔍 A busca usa o Google Custom Search primeiro e depois recorre à API de Busca Externa quando o Google relata cota ou limite de taxa.
• 🤖 Comando inteligente:
  • Detecção automática de idioma (franc-min) e tradução opcional (importação dinâmica de translate).
  • O enriquecimento de consulta é baseado em heurísticas; os resultados dependem da intenção detectada.

🏗️ Arquitetura

Esta seção descreve a arquitetura de alto nível do Web-curl.

graph TD
    A[User/MCP Host] --> B(CLI / MCP Server)
    B --> C{Tool Handlers}
    C -- extract/crawl/agent --> D["Puppeteer (Web Scraping)"]
    C -- fetch_api --> E["REST Client"]
    C -- multi_search --> F["External Search API"]
    C -- parse_document --> G["Document Parser (PDF/DOCX)"]
    C -- download_file --> H["File System (Downloads)"]
    D --> I["Web Content"]
    E --> J["External APIs"]
    F --> K["External Search Results"]
    H --> L["Local Storage"]

• CLI e Servidor MCP: src/index.ts Implementa tanto o ponto de entrada da CLI quanto o servidor MCP.
• Raspagem Web: Usa Puppeteer para navegação headless e extração de conteúdo.
• Cliente REST: src/rest-client.ts Fornece um cliente HTTP flexível para solicitações de API.

⚙️ Exemplo de Configuração do Servidor MCP

Para integrar o web-curl como um servidor MCP, adicione a seguinte configuração ao seu mcp_settings.json:

{
  "mcpServers": {
    "web-curl": {
      "command": "node",
      "args": [
        "build/index.js"
      ],
      "disabled": false,
      "alwaysAllow": [
        "extract",
        "crawl",
        "agent",
        "research",
        "browser_configure",
        "browser_close",
        "multi_search",
        "fetch_api",
        "download_file",
        "parse_document"
      ],
      "env": {
        "SEARCH_BASE_URL": "https://example.com/v1/search",
        "SEARCH_MODEL": "search-combo",
        "SEARCH_API_KEY": "YOUR_EXTERNAL_SEARCH_API_KEY",
        "APIKEY_GOOGLE_SEARCH": "YOUR_GOOGLE_API_KEY",
        "CX_GOOGLE_SEARCH": "YOUR_CX_ID"
      }
    }
  }
}

🔑 Configure a API de Busca Externa

A busca sempre tenta o Google Custom Search primeiro, usando APIKEY_GOOGLE_SEARCH e CX_GOOGLE_SEARCH. Se o Google relatar cota ou limite de taxa (429, ou um 403 de cota/limite de taxa), a busca recorre automaticamente à API de Busca Externa. Configure SEARCH_BASE_URL (por exemplo, https://example.com/v1/search), SEARCH_MODEL (por exemplo, search-combo) e SEARCH_API_KEY para habilitar o fallback. Outros erros do Google são retornados sem fallback.

🛠️ Instalação

# Clone the repository
git clone https://github.com/rayss868/MCP-Web-Curl
cd web-curl

# Install dependencies
npm install

# Build the project
npm run build

• Pré-requisitos: Certifique-se de ter Node.js (v18+) e Git instalados no seu sistema.

Notas de instalação do Puppeteer

• Windows: Basta executar npm install.

• Linux / Ubuntu Server: Você deve instalar dependências extras para o Chromium lidar com renderização e capturas de tela em um ambiente headless. Execute:

  sudo apt-get update && sudo apt-get install -y \
    fonts-liberation \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libc6 \
    libcairo2 \
    libcups2 \
    libdbus-1-3 \
    libexpat1 \
    libfontconfig1 \
    libgbm1 \
    libgcc1 \
    libglib2.0-0 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libpango-1-0-0 \
    libpangocairo-1.0-0 \
    libstdc++6 \
    libx11-6 \
    libx11-xcb1 \
    libxcb1 \
    libxcomposite1 \
    libxcursor1 \
    libxdamage1 \
    libxext6 \
    libxfixes3 \
    libxi6 \
    libxrandr2 \
    libxrender1 \
    libxss1 \
    libxtst6 \
    lsb-release \
    wget \
    xdg-utils
  

Para mais detalhes, consulte o guia de solução de problemas do Puppeteer.

🚀 Uso

Uso via CLI

A CLI suporta busca e extração de conteúdo de texto de páginas web.

# Basic usage
node build/index.js https://example.com

# With options
node build/index.js --timeout 30000 https://example.com

# Save output to a file
node build/index.js -o result.json https://example.com

Opções de Linha de Comando

• --timeout <ms>: Define o tempo limite de navegação (padrão: 60000)
• -o <file>: Envia o resultado para o arquivo especificado

Uso como Servidor MCP

O Web-curl pode ser executado como um servidor MCP para integração com Roo Context ou outros ambientes compatíveis com MCP.

Ferramentas Expostas (v1.4.2)

Apenas as ferramentas abaixo são expostas via list_tools para reduzir o encadeamento de ferramentas em clientes de agente.

• browser_configure: Define proxy/user-agent/viewport (a persistência de sessão está sempre ativa via user_data/).
• browser_close: Fecha o navegador e as abas (também fecha automaticamente após 15 minutos de inatividade).
• multi_search: Executa múltiplas buscas em paralelo usando o backend de busca selecionado.
• fetch_api: Solicitação de API REST com truncamento de resposta (limit).
• download_file: Baixa um arquivo de uma URL.
• parse_document: Extrai texto de URLs de PDF/DOCX.
• research: Decompõe uma pergunta em sub-consultas, busca em paralelo e retorna um relatório em markdown com citações.
• extract: Extrai campos estruturados de uma página via seletores CSS, tabelas, meta tags, JSON-LD ou Readability. Respostas não-HTML (texto simples, JSON, arquivos de código-fonte) retornam como texto bruto em mainContent com isHtml: false.
• crawl: Percorre um site (BFS/DFS/sitemap/mapa de links) com filtros de inclusão/exclusão e atraso de polidez.
• agent: Coleta registros planos de muitas páginas usando um esquema de campos (seletores CSS e/ou caminhos JSON-LD).

Ferramentas de navegador de nível inferior ainda têm manipuladores em CallToolRequestSchema, mas não são expostas intencionalmente.

Executando como Servidor MCP

npm run start

O servidor se comunicará via stdin/stdout e exporá as ferramentas conforme definido em src/index.ts.

🚦 Mantendo Respostas Pequenas (Recomendado para Páginas Grandes)

Use extract com maxTextChars para limitar o texto do conteúdo principal e desative os extratores extras que você não precisa. Isso evita que páginas grandes inundem o contexto.

Solicitação do cliente para extração reduzida:

{
  "name": "extract",
  "arguments": {
    "url": "https://example.com/article",
    "includeTables": false,
    "includeJsonLd": false,
    "includeMeta": false,
    "maxTextChars": 20000
  }
}

Resposta (exemplo):

{
  "url": "https://example.com/article",
  "title": "Example Article",
  "mainContent": "The first 20000 characters of readable text...",
  "truncated": true
}

🧩 Configuração

• Persistência de Sessão: Sempre habilitada. Logins e cookies são reutilizados automaticamente entre reinicializações.
• Tempo Limite: Defina os tempos limite de navegação e solicitações de API.
• Variáveis de Ambiente: Configure o Google Custom Search e o fallback da API de Busca Externa. Para fallback de GET direto, configure EXTERNAL_API_URL, EXTERNAL_API_KEY e EXTERNAL_API_MODEL.

💡 Exemplos {#examples}

{
  "name": "fetch_api",
  "arguments": {
    "url": "https://api.github.com/repos/nodejs/node",
    "method": "GET",
    "headers": {
      "Accept": "application/vnd.github.v3+json"
    },
    "limit": 10000
  }
}

{
  "name": "download_file",
  "arguments": {
    "url": "https://example.com/image.jpg",
    "destinationFolder": "downloads"
  }
}

{
  "name": "browser_configure",
  "arguments": {
    "proxy": "http://proxy.example.com:8080",
    "viewport": { "width": 1920, "height": 1080 }
  }
}

🛠️ Solução de Problemas {#troubleshooting}

• Erros de Tempo Limite: Aumente o parâmetro timeout se as solicitações estiverem expirando.
• Falha na Busca Externa: Certifique-se de que SEARCH_PROVIDER=external e SEARCH_BASE_URL, SEARCH_MODEL e SEARCH_API_KEY correspondam ao seu provedor. Para o Google Custom Search, defina SEARCH_PROVIDER=google, APIKEY_GOOGLE_SEARCH e CX_GOOGLE_SEARCH.
• Logs de Erro: Verifique o arquivo logs/error-log.txt para mensagens de erro detalhadas.

🧠 Dicas e Boas Práticas {#tips--best-practices}

🤝 Contribuição e Problemas {#contributing--issues}

Contribuições são bem-vindas! Se você quiser contribuir, faça um fork deste repositório e envie um pull request.
Se você encontrar problemas ou tiver sugestões, abra uma issue na página do repositório.

📄 Publicação Acadêmica

Este projeto é o assunto de um artigo de revista revisado por pares:

Saleh, R. Z., & Lubis, M. (2026). Design and Implementation of MCP-Web-Curl: A Model Context Protocol Server for Web and API Access in Agentic Coding Assistants. JURNAL TEKNIK INFORMATIKA, 19(1), 122–134.

• DOI: 10.15408/jti.v19i1.49625
• Artigo: journal.uinjkt.ac.id/index.php/ti/article/view/49625
• PDF: Baixar
• Licença: CC BY-SA 4.0

📄 Licença e Atribuição {#license--attribution}

Este projeto foi desenvolvido por Rayss.
Para dúvidas, melhorias ou contribuições, entre em contato com o autor ou abra uma issue no repositório.

Nota: A disponibilidade de busca, cotas e preços dependem do backend selecionado, seja o seu provedor de API de Busca Externa ou o Google Custom Search.