MCP Deep Search

MCP Deep Search

Servidor MCP para busca profunda na web usando @just-every/search. Pesquise em vários provedores, incluindo Google, Bing, Brave, DuckDuckGo, Perplexity e outros.

Início Rápido

1. Crie ou use um arquivo de ambiente

Opção A: Crie um novo arquivo .llm.env no seu diretório inicial:

# Download example env file
curl -o ~/.llm.env https://raw.githubusercontent.com/just-every/mcp-deep-search/main/.env.example

# Edit with your API keys
nano ~/.llm.env

Opção B: Use um arquivo .env existente (deve usar caminho absoluto):

# Example: /Users/yourname/projects/myproject/.env
# Example: /home/yourname/workspace/.env

2. Instalação

Claude Code

# Using ~/.llm.env
claude mcp add deep-search -s user -e ENV_FILE=$HOME/.llm.env -- npx -y @just-every/mcp-deep-search

# Using existing .env file (absolute path required)
claude mcp add deep-search -s user -e ENV_FILE=/absolute/path/to/your/.env -- npx -y @just-every/mcp-deep-search

# For debugging, check if ENV_FILE is being passed correctly:
claude mcp list

Outros Clientes MCP

Adicione à sua configuração MCP:

{
  "mcpServers": {
    "deep-search": {
      "command": "npx",
      "args": ["-y", "@just-every/mcp-deep-search"],
      "env": {
        "ENV_FILE": "/path/to/.llm.env"
      }
    }
  }
}

Ferramentas MCP

deep_search

Realize buscas na web usando um provedor específico.

Parâmetros:

• query (obrigatório): A consulta de busca
• provider: Provedor de busca (padrão: brave)
• maxResults: Número máximo de resultados (padrão: 10)
• includeAnswer: Incluir resposta de IA se disponível (padrão: false)

comprehensive_research

Realize pesquisas abrangentes usando agentes de IA que selecionam e consultam inteligentemente vários mecanismos de busca.

Parâmetros:

• query (obrigatório): O tópico da pesquisa
• modelClass: Classe do modelo de IA (padrão: reasoning_mini)

Provedores de Busca

Provedor	Chave de API Necessária	Descrição
brave	BRAVE_API_KEY	Busca com foco em privacidade e resultados estruturados
anthropic	ANTHROPIC_API_KEY	Pesquisa profunda em múltiplas etapas
openai	OPENAI_API_KEY	Busca contextual de nível ChatGPT
google	GOOGLE_API_KEY	Busca com ancoragem Gemini
sonar / sonar-pro	OPENROUTER_API_KEY	Variantes de busca Perplexity
xai	XAI_API_KEY	Busca Grok em tempo real

Uso via CLI

# Basic search
mcp-deep-search search "your query"

# Search with specific provider
mcp-deep-search search "your query" -p brave

# Get more results
mcp-deep-search search "your query" -n 20

Solução de Problemas

Servidor MCP Mostra "Falhou" no Claude

Se você vir "deep-search ✘ falhou" no Claude, verifique estes problemas comuns:

1. Chaves de API Ausentes: O problema mais comum é a ausência de chaves de API. Verifique se o seu ENV_FILE está configurado corretamente:

   # Test if ENV_FILE is working
   ENV_FILE=/path/to/your/.env npx @just-every/mcp-deep-search search "test"
   

2. Comando de Instalação Incorreto: Certifique-se de estar usando -e para variáveis de ambiente:

   # Correct - environment variable passed with -e flag before --
   claude mcp add deep-search -s user -e ENV_FILE=$HOME/.llm.env -- npx -y @just-every/mcp-deep-search
   
   # Incorrect - trying to pass as argument
   claude mcp add deep-search -s user -- npx -y @just-every/mcp-deep-search --env ENV_FILE=$HOME/.llm.env
   

3. Problemas de Caminho: O ENV_FILE deve usar caminhos absolutos:

   # Good
   ENV_FILE=/Users/yourname/.llm.env
   ENV_FILE=$HOME/.llm.env
   
   # Bad
   ENV_FILE=.env
   ENV_FILE=~/.llm.env  # ~ not expanded in some contexts
   

4. Verifique a Instalação: Confira sua configuração MCP:

   claude mcp list
   

5. Modo de Depuração: Para mensagens de erro detalhadas, execute manualmente:

   ENV_FILE=/path/to/.env npx @just-every/mcp-deep-search
   

Obtendo Chaves de API

• Brave: brave.com/search/api
• Anthropic: console.anthropic.com
• OpenAI: platform.openai.com
• Google: makersuite.google.com
• OpenRouter: openrouter.ai
• xAI: x.ai

Recurso de Reinício Automático

O servidor MCP inclui capacidade de reinício automático por padrão para maior confiabilidade:

• Reinicia automaticamente o servidor se ele travar
• Trata exceções não capturadas e rejeições de promessas
• Implementa backoff exponencial (máximo de 10 tentativas em 1 minuto)
• Registra todas as tentativas de reinício para monitoramento
• Lida graciosamente com sinais de desligamento (SIGINT, SIGTERM)

Para desenvolvimento/depuração sem reinício automático:

# Run directly without restart wrapper
npm run serve:dev

Licença

MIT © Just Every