MCP Server for Stealth Web Search and Fetching

Tolerante a falhas MCP Server for Stealth Web Search and Fetching

Documentação

SearchFetch (Servidor MCP)

Um servidor de Protocolo de Contexto de Modelo (MCP) tolerante a falhas e com modo furtivo para busca na web e obtenção de conteúdo. Construído para Agentes de IA (Cursor, Claude Code, OpenCode), ele usa um navegador para renderizar páginas e converte seu conteúdo em Markdown.

Recursos

Renderização por navegador: O CloakBrowser executa Chromium com interações humanizadas. Sites ainda podem exigir autenticação ou apresentar desafios.
Tolerância a falhas: Reconecta navegadores desconectados, tenta novamente falhas de rede e HTTP 429 uma vez, e bloqueia tipos de recursos selecionados por template. Erros HTTP são relatados antes de aguardar a renderização.
Saída Otimizada para Tokens: Remove imagens base64, SVGs, scripts e estilos inline do DOM antes da conversão para Markdown.
Runtime duplo: Execute via Python (uvx, Python 3.10+) ou Node.js (npx, Node 24+). O primeiro uso baixa dependências e um binário de navegador.
Extração Orientada por Templates: Extração estruturada via templates JSON compartilhados (GitHub, npm, PyPI, crates.io, páginas de documentação, Docker Hub e outros). Suporta templates inline personalizados.

Uso e Instalação

Você não precisa instalar este repositório manualmente. Configure seu agente para usar os comandos de instalação zero npx ou uvx.

Configuração do Claude Desktop

Opção A: Python (uvx - Recomendado)

{
  "mcpServers": {
    "searchfetch": {
      "command": "uvx",
      "args": ["searchfetch"]
    }
  }
}

Opção B: Node.js (npx)

{
  "mcpServers": {
    "searchfetch": {
      "command": "npx",
      "args": ["-y", "searchfetch"]
    }
  }
}

Configuração do Cursor / IDE

Adicione via o painel MCP nas configurações do Cursor:

Tipo: command
Comando: uvx searchfetch (ou npx -y searchfetch)

Ferramentas Disponíveis

1. `websearch`

Busque na web através do pipeline de templates. DuckDuckGo e Google são integrados; templates de busca personalizados podem ser selecionados por nome.

Parâmetro	Tipo	Padrão	Descrição
`query`	string	obrigatório	A string de consulta de busca.
`engine`	string	`"duckduckgo"`	`"duckduckgo"`, `"google"`, ou um nome de template de busca personalizado.
`max_results`	number	`10`	Limite inteiro positivo de resultados extraídos.
`region`	string/null	`null`	Código de região/idioma (ex.: `"us-en"`, `"de-de"`). DDG mapeia diretamente; Google mapeia para `gl`/`hl`.
`safe_search`	boolean/null	`null`	Ativa busca segura. `null` usa o padrão do template.
`block_media`	boolean	`true`	Bloqueia imagens, mídia e fontes na camada de rede.

2. `webfetch`

Obtenha uma página com o navegador furtivo e extraia Markdown estruturado usando um template. Recorre à extração genérica de Markdown para páginas desconhecidas.

Parâmetro	Tipo	Padrão	Descrição
`url`	string	obrigatório	URL completa (deve começar com `http`/`https`).
`template`	string	`"auto"`	`"auto"`, um nome integrado, ou template JSON inline.
`start_index`	number	`0`	Deslocamento inteiro não negativo em pontos de código Unicode.
`max_length`	number	`10000`	Limite inteiro positivo em pontos de código Unicode.
`block_media`	boolean	`true`	Bloqueia imagens, vídeos e fontes na camada de rede.

A extração por template suporta formatos text, markdown, attribute e html; campos filhos dentro de uma seção; seções repetidas; transformações de decodificação de URL; cookies por template; e bloqueio de recursos por template.

Templates integrados ficam em templates/*.json e são compartilhados pelas implementações Node.js e Python.

Templates de página disponíveis (auto-detectados por URL ou selecionáveis por nome): wikipedia, reddit, mdn-web-docs, gitlab, youtube, devto, go-pkg, javadoc, github-repo, github-issue, npm-package, pypi-package, crates-package, docker-hub, docs-rs, docs-page

raw — template especial que aplica filtragem mínima e retorna o conteúdo completo do corpo como markdown. Use quando precisar da página completa sem extração específica por template.

Desenvolvimento Local

# Install dependencies
npm ci
uv sync --locked --extra dev

# Run tests
npm test                # runs all tests (JS + Python)
npm run test:js         # Node.js unit tests (built-in test runner)
npm run test:py         # Python unit tests (pytest)

# Lint
npm run lint            # runs all linters
npm run lint:js         # ESLint
npm run lint:py         # Ruff

# Format
npm run format          # auto-format all source files
npm run format:check    # check formatting without changes

# MCP inspector (for manual testing)
npm run inspector-js    # test with MCP Inspector (Node.js)
npm run inspector-py    # test with MCP Inspector (Python)

Arquitetura

Ambos os servidores MCP expõem websearch e webfetch sobre entrada/saída padrão:

Valida entradas das ferramentas e resolve um template JSON integrado ou inline.
Reutiliza um navegador, criando um contexto de navegador isolado para cada tentativa de obtenção.
Aplica cookies e bloqueio de recursos do template, navega, verifica o status HTTP e permite até cinco segundos para a atividade de rede se estabilizar.
Remove elementos configurados, extrai campos de seção, aplica transformações e compõe Markdown. Templates de página podem primeiro tentar uma URL de fonte Markdown bruta.
Pagina a saída da página usando pontos de código Unicode. Solicitações de busca podem recorrer do Google para DuckDuckGo HTML e depois Lite; a saída nomeia qualquer mecanismo de fallback.

index.js e server.py contêm a integração de navegador e MCP específica do runtime. lib/ e selectors_utils.py contêm auxiliares focados de formatação e seletores. Ambos os runtimes leem o mesmo templates/*.json; wheels Python agrupam estes como recursos searchfetch_templates. Fixtures compartilhados em tests/fixtures/ exercitam o comportamento de extração em ambos os runtimes.

Seletores separados por vírgulas de nível superior são fallbacks ordenados. Vírgulas dentro de funções CSS ou atributos são preservadas; um fallback vazio seleciona o elemento atual. A extração de filhos busca descendentes e elementos envolventes, sem emprestar campos de resultados vizinhos. Campos obrigatórios ausentes e seletores malformados relatam erros.

Verificação e limites

npm test, npm run lint e npm run format:check verificam ambos os runtimes. npm run e2e executa solicitações reais de navegador contra fixtures HTTP locais, exercita cada template integrado e verifica o executável npm instalado e o wheel Python. A disponibilidade pública de mecanismos de busca e layouts de páginas de terceiros em mudança exigem verificações ao vivo separadas. Uma página que continua renderizando além da espera limitada pode retornar conteúdo parcial.

package-lock.json e uv.lock registram a resolução de dependências.