Web-curl

API Google Custom Search

A API Google Custom Search é gratuita com limites de uso (por exemplo, 100 consultas por dia gratuitas, com consultas adicionais exigindo pagamento). Para detalhes completos sobre cotas, preços e restrições, consulte a documentação oficial.

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_1.mp4 diretamente.

📚 Índice

• Changelog / Histórico de Atualizações
• Visão Geral
• Recursos
• Arquitetura
• Instalação
• Uso
• Uso via CLI
• Uso do Servidor MCP
• Configuração
• Exemplos
• Solução de Problemas
• Dicas e Melhores Práticas
• Contribuição e Problemas
• 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-o como CLI autônomo ou como 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 Google Custom Search.

✨ Recursos

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

• Automação Avançada do 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/.
• Instantâneos Eficientes em Tokens:
  • Árvore de Acessibilidade: Instantâneos limpos e estruturados em vez de HTML bagunçado.
  • Modo de Fatia HTML: HTML bruto com startIndex/endIndex para divisão segura quando necessário.
  • Filtragem por Viewport: Filtra automaticamente elementos não visíveis na tela, economizando até 90% dos tokens de contexto em páginas longas.
• Integração com Chrome DevTools (implementada, mas oculta de list_tools):
  • Monitoramento de Rede (browser_network_requests)
  • Logs do Console (browser_console_messages)
• Pesquisa Paralela:
  • multi_search: Execute várias pesquisas do Google de uma vez (única ferramenta de pesquisa exposta).
• Gerenciamento Inteligente de Recursos:
  • Fechamento Automático por Inatividade: O navegador é encerrado 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 log de erros: 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 a fatiamento startIndex/maxLength/chunkSize quando solicitado.
• 🚫 Bloqueio de recursos: blockResources agora é sempre forçado a false, o que significa que os recursos nunca são bloqueados para carregamentos de página mais rápidos.
• ⏱️ 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 de 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 retorna JSON/texto quando apropriado e base64 para respostas binárias.
• 🔍 Google Custom Search: requer APIKEY_GOOGLE_SEARCH e CX_GOOGLE_SEARCH.
• 🤖 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 -- browser_flow --> D["Puppeteer (Web Scraping)"]
    C -- fetch_api --> E["REST Client"]
    C -- multi_search --> F["Google Custom 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["Google 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.
• Web Scraping: 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 servidor MCP, adicione a seguinte configuração ao seu mcp_settings.json:

{
  "mcpServers": {
    "web-curl": {
      "command": "node",
      "args": [
        "build/index.js"
      ],
      "disabled": false,
      "alwaysAllow": [
        "browser_flow",
        "browser_configure",
        "browser_close",
        "multi_search",
        "fetch_api",
        "download_file",
        "parse_document"
      ],
      "env": {
        "APIKEY_GOOGLE_SEARCH": "YOUR_GOOGLE_API_KEY",
        "CX_GOOGLE_SEARCH": "YOUR_CX_ID"
      }
    }
  }
}

🔑 Como Obter a Chave da API do Google e o CX

1. Obtenha uma Chave da API do Google:
   • Acesse o Google Cloud Console.
   • Crie/selecione um projeto e vá para APIs & Services > Credenciais.
   • Clique em Criar Credenciais > Chave da API e copie-a.
2. Obtenha um ID do Mecanismo de Pesquisa Personalizada (CX):
   • Acesse o Google Custom Search Engine.
   • Crie/selecione um mecanismo de pesquisa e copie o ID do mecanismo de pesquisa (CX).
3. Ative a API Custom Search:
   • No Google Cloud Console, vá para APIs & Services > Biblioteca.
   • Pesquise por Custom Search API e ative-a.

Substitua YOUR_GOOGLE_API_KEY e YOUR_CX_ID na configuração acima.

🛠️ 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>: Defina o tempo limite de navegação (padrão: 60000)
• -o <file>: Envie o resultado para o arquivo especificado

Uso do Servidor MCP

O Web-curl pode ser executado como 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_flow: Fluxo de navegador em uma chamada (navegação opcional → ações opcionais → retorna UM resultado).

• browser_configure: Defina 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: Execute várias pesquisas do Google em paralelo (o único ponto de entrada de pesquisa exposto).

• 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.

Executando como Servidor MCP

npm run start

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

🚦 Exemplo de Fatiamento de HTML (Recomendado para Páginas Grandes)

Use browser_flow com result: { type: "snapshot", mode: "html" } quando precisar de HTML bruto, mas quiser manter a resposta pequena.

Solicitação do cliente para a primeira fatia:

{
  "name": "browser_flow",
  "arguments": {
    "result": {
      "type": "snapshot",
      "mode": "html",
      "startIndex": 0,
      "endIndex": 20000
    }
  }
}

Resposta (exemplo):

{
  "mode": "html",
  "totalLength": 123456,
  "startIndex": 0,
  "endIndex": 20000,
  "remainingCharacters": 103456,
  "content": "<html>...first slice...</html>"
}

🧩 Configuração

• Persistência de Sessão: Sempre ativada. 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: Usadas para integração com a API do Google Search (usadas por multi_search).

💡 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 Pesquisa do Google: Certifique-se de que APIKEY_GOOGLE_SEARCH e CX_GOOGLE_SEARCH estejam definidos no seu ambiente.
• Logs de Erro: Verifique o arquivo logs/error-log.txt para mensagens de erro detalhadas.

🧠 Dicas e Melhores 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 encontrar algum problema ou tiver sugestões, abra uma issue na página do repositório.

📄 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 API do Google Search é gratuita com limites de uso. Para detalhes, consulte: Visão Geral da API Google Custom Search