Brave Search

Um servidor MCP para a API Brave Search, oferecendo capacidades de busca web e local através de uma interface SSE de streaming.

GitHub
16
Experimente este MCPPatrocinado

Documentação

Servidor MCP/SSE Brave Search

License: MIT Docker Hub Helm Chart

Uma implementação do Model Context Protocol (MCP) usando Server-Sent Events (SSE) que integra a API Brave Search, fornecendo recursos de busca web e local para modelos de IA e outros clientes por meio de uma interface de streaming.

Visão Geral

Este servidor atua como um provedor de ferramentas para Modelos de Linguagem de Grande Porte que entendem o Model Context Protocol. Ele expõe as poderosas funcionalidades de busca web e local da Brave por meio de uma conexão SSE, permitindo streaming em tempo real dos resultados de busca e atualizações de status.

Principais Objetivos de Design:

  • Acesso Centralizado: Projetado com centralidade em mente, permitindo que organizações ou indivíduos gerenciem uma única chave de API do Brave Search e forneçam acesso controlado a vários clientes ou aplicativos internos.
  • Observabilidade: Possui registro robusto para rastrear solicitações, interações com a API, erros e limites de taxa, fornecendo visibilidade sobre o uso e auxiliando na depuração.
  • Implantação Flexível: Pode ser implantado de forma privada em uma rede ou opcionalmente exposto publicamente por meio de métodos como Kubernetes Ingress ou mapeamento direto de portas Docker.

Recursos

  • Busca Web: Acesse o índice de busca web independente da Brave para consultas gerais, notícias, artigos, etc. Suporta controles de paginação e filtragem.
  • Busca Local: Encontre empresas, restaurantes e serviços com informações detalhadas como endereço, telefone e avaliações.
  • Fallbacks Inteligentes: A busca local automaticamente recorre a uma busca web filtrada se nenhum resultado local específico for encontrado para a consulta.
  • Server-Sent Events (SSE): Streaming eficiente e em tempo real dos resultados de busca e do status de execução das ferramentas.
  • Model Context Protocol (MCP): Adere ao padrão MCP para integração perfeita com clientes compatíveis.
  • Suporte a Docker: Inclui um Dockerfile para fácil conteinerização e implantação.
  • Helm Chart: Fornece um Helm chart para implantação direta em clusters Kubernetes.

Pré-requisitos

Dependendo do método de implantação escolhido, você precisará de alguns dos seguintes:

  • Chave da API Brave Search: Necessária para todos os métodos de implantação. Veja "Começando" abaixo.
  • Docker: Necessário se estiver implantando usando Docker.
  • kubectl & Helm: Necessários se estiver implantando no Kubernetes usando Helm.
  • Node.js & npm: Necessários apenas para desenvolvimento local (Node.js v22.x ou posterior recomendado).
  • Git: Necessário para clonar o repositório para desenvolvimento local ou construir imagens Docker personalizadas.

Começando

1. Obtenha uma Chave da API Brave Search

  1. Cadastre-se em uma conta da API Brave Search.
  2. Escolha um plano (um nível gratuito está disponível).
  3. Gere sua chave de API no painel do desenvolvedor.

2. Configuração

O servidor requer que a chave da API Brave Search seja definida por meio da variável de ambiente BRAVE_API_KEY.

Outras variáveis de ambiente possíveis (verifique src/config/config.ts para detalhes):

  • PORT: A porta em que o servidor escuta (padrão é 8080).
  • LOG_LEVEL: Nível de detalhe do registro (por exemplo, info, debug).

Defina essas variáveis no seu ambiente ou usando um arquivo .env na raiz do projeto para desenvolvimento local.

Instalação e Uso

Escolha o método de implantação que melhor atende às suas necessidades:

Opção 1: Docker (Recomendado para Implantação)

Pré-requisitos: Docker instalado.

  1. Obtenha uma Chave da API Brave Search: Siga os passos na seção "Começando".
  2. Baixe a imagem Docker: Baixe a imagem mais recente do Docker Hub: 
    docker pull shoofio/brave-search-mcp-sse:latest
    Ou baixe uma tag de versão específica (por exemplo, 1.0.10): 
    docker pull shoofio/brave-search-mcp-sse:1.0.10
    (Alternativamente, você pode construir a imagem localmente se necessário. Clone o repositório e execute docker build -t brave-search-mcp-sse:custom .)
  3. Execute o contêiner Docker: Use a tag que você baixou (por exemplo, latest ou 1.0.10): 
    docker run -d --rm \
  -p 8080:8080 \
  -e BRAVE_API_KEY="YOUR_API_KEY_HERE" \
  -e PORT="8080" # Optional: Define the port if needed
  # -e LOG_LEVEL="info" # Optional: Set log level
  --name brave-search-server \
  shoofio/brave-search-mcp-sse:latest # Or your specific tag
    Isso executa o servidor em modo destacado, mapeando a porta 8080 do seu host para o contêiner.

Opção 2: Helm (Implantação no Kubernetes)

Pré-requisitos: kubectl conectado ao seu cluster, Helm instalado.

  1. Obtenha uma Chave da API Brave Search: Siga os passos na seção "Começando".

  2. Adicione o repositório Helm:

    helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/
helm repo update

  3. Prepare o Segredo da Chave da API (Recomendado): Crie um segredo Kubernetes no namespace de destino:

    kubectl create secret generic brave-search-secret \
  --from-literal=api-key='YOUR_API_KEY_HERE' \
  -n <your-namespace>

  4. Instale o Helm chart: A versão do chart corresponde à versão do aplicativo (a mais recente é 1.0.10). Instale usando o segredo:

    helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \
  -n <your-namespace> \
  --set braveSearch.existingSecret=brave-search-secret
  # Optionally specify a version: --version 1.0.10

    Ou forneça a chave diretamente (menos seguro):

    helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \
  -n <your-namespace> \
  --set braveSearch.apiKey="YOUR_API_KEY_HERE"

  5. Configuração do Chart: Você pode personalizar a implantação substituindo os valores padrão. Crie um arquivo YAML (por exemplo, dev-values.yaml, prod-values.yaml) com as configurações desejadas e use a flag -f durante a instalação: helm install ... -f dev-values.yaml.

    Consulte o arquivo padrão values.yaml do chart para ver todas as opções de configuração disponíveis e suas configurações padrão.

Opção 3: Desenvolvimento Local

Pré-requisitos: Node.js e npm (v22.x ou posterior recomendado), Git.

  1. Obtenha uma Chave da API Brave Search: Siga os passos na seção "Começando".
  2. Clone o repositório: 
    git clone <repository_url> # Replace with the actual URL
cd brave-search-mcp-sse
  3. Instale as dependências: 
    npm install
  4. Defina as Variáveis de Ambiente: Crie um arquivo .env no diretório raiz: 
    BRAVE_API_KEY=YOUR_API_KEY_HERE
PORT=8080
# LOG_LEVEL=debug
  5. Compile o código TypeScript: 
    npm run build
  6. Execute o servidor: 
    npm start
# Or for development with auto-reloading (if nodemon/ts-node-dev is configured)
# npm run dev
    O servidor começará a escutar na porta configurada (padrão 8080).

Interação com API / Protocolo

Os clientes se conectam a este servidor por meio de uma solicitação HTTP GET para estabelecer uma conexão SSE. O endpoint específico depende da sua implantação (por exemplo, http://localhost:8080/, http://<k8s-service-ip>:8080/, ou por meio de um Ingress).

Uma vez conectados, o servidor e o cliente se comunicam usando mensagens MCP por meio do fluxo SSE.

Ferramentas Disponíveis

O servidor expõe as seguintes ferramentas aos clientes conectados:

  1. brave_web_search

    • Descrição: Realiza uma busca web geral usando a API Brave Search.
    • Entradas:
      • query (string, obrigatório): A consulta de busca.
      • count (número, opcional): Número de resultados a retornar (1-20, padrão 10).
      • offset (número, opcional): Deslocamento de paginação (0-9, padrão 0).
      • (Outros parâmetros da API Brave, como search_lang, country, freshness, result_filter, safesearch, podem ser suportados - verifique src/services/braveSearchApi.ts)
    • Saída: Transmite mensagens MCP contendo resultados de busca (título, URL, trecho, etc.).

  2. brave_local_search

    • Descrição: Realiza uma busca por empresas e lugares locais usando a API Brave Search. Recorre à busca web se nenhum resultado local for encontrado.
    • Entradas:
      • query (string, obrigatório): A consulta de busca local (por exemplo, "pizza perto de mim", "cafés no centro").
      • count (número, opcional): Número máximo de resultados (1-20, padrão 5).
    • Saída: Transmite mensagens MCP contendo detalhes de empresas locais (nome, endereço, telefone, avaliação, etc.).

(Exemplo usando curl - Nota: A interação real com MCP requer uma biblioteca de cliente)

# Example: Connect to SSE endpoint (won't show MCP messages directly)
curl -N http://localhost:8080/ # Or your deployed endpoint

Exemplo de Configuração do Cliente (Cursor)

Para usar este servidor com um cliente MCP como o Cursor, você precisa configurar o cliente para se conectar ao endpoint SSE do servidor.

Adicione a seguinte configuração às configurações do seu Cursor (mcp.json ou arquivo de configuração semelhante), substituindo a URL pelo endereço e porta reais onde seu servidor brave-search-mcp-sse está acessível:

{
  "mcpServers": {
    "brave-search": {
      "transport": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Explicação:

  • transport: Deve ser definido como "sse" para este servidor.
  • url: Esta é a parte crucial.
    • Se estiver executando localmente via Docker (como mostrado no exemplo), http://localhost:8080/sse provavelmente está correto.
    • Se estiver executando no Kubernetes, substitua localhost:8080 pelo endereço/porta do Serviço Kubernetes apropriado ou pelo hostname/caminho do Ingress configurado para alcançar a porta 8080 do servidor.
    • Certifique-se de que o caminho da URL termine com /sse.

(Passos de configuração semelhantes podem se aplicar a outros clientes MCP que suportam o transporte SSE, como versões recentes do Claude Desktop, mas consulte a documentação específica deles.)

Estrutura do Projeto

.
├── Dockerfile             # Container build definition
├── helm/                  # Helm chart for Kubernetes deployment
│   └── brave-search-mcp-sse/
├── node_modules/        # Project dependencies (ignored by git)
├── src/                   # Source code (TypeScript)
│   ├── config/            # Configuration loading
│   ├── services/          # Brave API interaction logic
│   ├── tools/             # Tool definitions for MCP
│   ├── transport/         # SSE/MCP communication handling
│   ├── types/             # TypeScript type definitions
│   ├── utils/             # Utility functions
│   └── index.ts           # Main application entry point
├── dist/                  # Compiled JavaScript output (ignored by git)
├── package.json           # Project metadata and dependencies
├── tsconfig.json          # TypeScript compiler options
├── .env.example           # Example environment file
├── .gitignore
└── README.md              # This file

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request com suas alterações. Certifique-se de que seu código siga o estilo existente e inclua testes quando aplicável. Revisarei os PRs conforme o tempo permitir.

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.