mcp-web-search

# mcp-web-search

Servidor MCP (Model Context Protocol) para consultas na internet, publicado na Vercel como uma API HTTP stateless. Permite que agentes de IA como o Antigravity pesquisem na web, leiam páginas, consumam APIs REST e extraiam links — sem problemas de bloqueios anti-bot.

Ferramentas disponíveis

Related MCP server: Spider MCP Server

Markdown, não HTML

As ferramentas devolvem Markdown porque é o formato mais eficiente para o modelo que consome o MCP: a mesma informação em uma fração dos tokens do HTML, com a hierarquia que importa (títulos, listas, tabelas, links) preservada e o layout descartado. Além disso, o /extract da Tavily aceita apenas markdown ou text — HTML não existe no caminho, por isso o antigo modo raw_html foi removido em vez de continuar prometendo algo que não entregava.

As saídas das tools também são Markdown compacto em vez de JSON indentado. Medido em páginas reais: extract_links caiu 54% (6.470 → 2.980 tokens em 163 links) e web_search 9%.

As imagens viram o próprio texto alternativo: a URL do arquivo não diz nada a quem vai ler a página, e caminhos de CDN passam fácil de 100 caracteres cada. No catálogo da MANN-FILTER isso sozinho corta 18% do conteúdo.

O maior ganho de contexto, porém, está no query do read_webpage: a Tavily reordena a página e devolve só os trechos pertinentes. Na Wikipédia pt do Brasil, a página inteira dá ~142.800 tokens; com query: "população e economia do Brasil" são 509 tokens — e com chunks_per_source: 1, 153. Sem query, o conteúdo é cortado em max_chars (padrão 50.000 ≈ 12k tokens) e o corte é avisado no próprio texto, para o modelo saber que a página continua.

Stack

• Next.js 16 (App Router) — framework do servidor

• mcp-handler — adaptador HTTP para o protocolo MCP

• @modelcontextprotocol/server — SDK MCP v2

• Tavily API — mecanismo oficial de busca e extração de páginas (imune a bloqueios anti-bot)

• axios — cliente HTTP para a Tavily e para o fetch_json

• Zod v4 — validação de schemas das ferramentas

• Vercel Hobby — hospedagem gratuita (timeout de 60s por request)

Configurando a Tavily API

Como a Vercel e outros datacenters são frequentemente bloqueados por firewalls ao tentar raspar o conteúdo da web (scraping), este projeto utiliza o Tavily, que é uma API focada em IA que consegue ler páginas e buscar na internet de forma 100% confiável.

A chave é obrigatória — não há chave embutida no código. Sem variável de ambiente configurada, as ferramentas de busca falham com Nenhuma chave da Tavily configurada.

1. Crie uma conta gratuita em tavily.com (dá direito a 1.000 requisições/mês gratuitas).

2. Vá no painel da sua hospedagem (ex: Vercel) e adicione a Variável de Ambiente:

   • TAVILY_API_KEY: sua_chave_aqui

3. Para rodar local, crie um .env.local na raiz com a mesma variável. O arquivo é ignorado pelo git.

Múltiplas chaves com troca automática

Para não ficar sem busca quando uma conta gratuita atinge o limite, configure várias chaves separadas por vírgula:

• TAVILY_API_KEYS: tvly-dev-chave1,tvly-dev-chave2,tvly-dev-chave3

O servidor usa a primeira chave e, ao receber um erro de limite (429 por minuto, 432/433 por cota do plano) ou de chave inválida (401/403), repete a mesma requisição, com os mesmos parâmetros, na próxima chave — tudo dentro da mesma chamada MCP. O cliente (a IA) recebe o resultado normalmente e não precisa refazer a busca.

Detalhes do comportamento:

• A chave que funcionou vira a padrão das chamadas seguintes, então não há troca desnecessária.

• A chave que estourou fica em espera antes de voltar ao pool: o valor do header Retry-After (ou 1 minuto) para 429, 6 horas para cota do plano, 24 horas para chave inválida.

• Se a única chave disponível levar um 429 curto, o servidor espera até 3 segundos e repete em vez de devolver erro. Esperas maiores falham na hora, para não travar o cliente.

• Se todas as chaves estiverem em espera, ele ainda tenta a que libera primeiro — o tempo de espera é uma estimativa local, não um dado da Tavily.

• Erros que não são de limite (400 de parâmetro inválido, 500) sobem direto, sem queimar as outras chaves.

• Esgotado o pool, o erro lista o motivo de cada chave (ex: chave #1 (432 This request exceeds your plan's set usage limit...)).

TAVILY_API_KEYS e TAVILY_API_KEY podem ser usadas juntas — as chaves das duas são somadas no pool. A lógica fica em lib/tavily.ts.

Verificando

pnpm test:rotation   # testa a rotação com respostas simuladas (não gasta crédito)
pnpm test:links      # testa o parser de links do extract_links (não gasta crédito)
pnpm test:markdown   # testa a limpeza de Markdown e o corte por max_chars (não gasta crédito)
pnpm check:keys      # diz quais chaves do .env.local ainda têm saldo (1 crédito por chave)
pnpm check:tools     # roda as três ferramentas contra a API real (~3 créditos)

Deploy na Vercel

Pré-requisitos

• Node.js 20+

• pnpm

1. Clone o repositório

git clone https://github.com/suportebono/mcp-web-search.git
cd mcp-web-search
pnpm install

2. Teste localmente

pnpm dev

O endpoint MCP estará disponível em http://localhost:3000/api/mcp.

Para inspecionar as ferramentas visualmente:

npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp

3. Publique na Vercel

npx vercel

Após o deploy, você receberá uma URL no formato https://mcp-web-search-xxx.vercel.app. Não se esqueça de configurar o TAVILY_API_KEY!

Configurando no Antigravity

Edite o arquivo ~/.gemini/config/mcp_config.json (crie se não existir):

{
  "mcpServers": {
    "web-search": {
      "serverUrl": "https://seu-projeto.vercel.app/api/mcp"
    }
  }
}

Reinicie o Antigravity e verifique em ... > MCP Servers — as 4 ferramentas devem aparecer listadas.

Configurando em outros clientes MCP

Claude Desktop / Cursor / Windsurf

Adicione ao arquivo de configuração do seu cliente:

{
  "mcpServers": {
    "web-search": {
      "url": "https://seu-projeto.vercel.app/api/mcp"
    }
  }
}

Clientes que só suportam stdio

Use o pacote mcp-remote como proxy:

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://seu-projeto.vercel.app/api/mcp"]
    }
  }
}

Referência das ferramentas

web_search

Busca na internet usando a API do Tavily.

Parâmetros:

Exemplo de retorno:

[
  {
    "title": "Next.js 15 — Blog",
    "url": "https://nextjs.org/blog/next-15",
    "snippet": "Next.js 15 introduces...",
    "source": "nextjs.org"
  }
]

read_webpage

Lê e extrai o conteúdo de uma URL burlando paywalls e anti-bots usando o Tavily Extract.

Parâmetros:

Remove automaticamente scripts, estilos, anúncios, navegação e rodapé antes de retornar o conteúdo.

fetch_json

Faz uma requisição GET via Axios e retorna o JSON bruto.

Parâmetros:

extract_links

Usa o Tavily Extract para ler o HTML real da página (inclusive sites dinâmicos) e extrai todos os links.

Parâmetros:

Exemplo de retorno:

[
  {
    "text": "Documentação",
    "href": "/docs",
    "absolute_url": "https://exemplo.com/docs"
  }
]

Estrutura do projeto

mcp-web-search/
├── app/
│   └── api/
│       └── mcp/
│           └── route.ts        ← Endpoint MCP (GET + POST)
├── lib/
│   ├── mcp-server.ts           ← Registro de todas as ferramentas
│   ├── tavily.ts               ← Cliente Tavily com pool de chaves e troca no limite
│   └── tools/
│       ├── web-search.ts       ← Busca via Tavily API
│       ├── read-webpage.ts     ← Leitura e parsing de páginas (Tavily Extract)
│       ├── fetch-json.ts       ← Fetch de APIs REST genéricas
│       └── extract-links.ts    ← Extração de links via Tavily Extract HTML
├── next.config.ts
└── package.json

Protocolo MCP suportado

Este servidor implementa a especificação MCP 2026-07-28 via transporte Streamable HTTP stateless, compatível com clientes modernos. Também oferece fallback automático para clientes que usam a especificação 2025-era Streamable HTTP.

Licença

MIT