Brave Search

Un servidor MCP para la API de Brave Search, que proporciona capacidades de búsqueda web y local a través de una interfaz SSE de transmisión.

GitHub
16
Prueba este MCPPatrocinado

Documentación

Servidor MCP/SSE de Brave Search

License: MIT Docker Hub Helm Chart

Una implementación del Model Context Protocol (MCP) que utiliza Server-Sent Events (SSE) e integra la Brave Search API, proporcionando a los modelos de IA y otros clientes capacidades de búsqueda web y local a través de una interfaz de streaming.

Resumen

Este servidor actúa como proveedor de herramientas para modelos de lenguaje de gran tamaño que entienden el Model Context Protocol. Expone las potentes funcionalidades de búsqueda web y local de Brave a través de una conexión SSE, permitiendo la transmisión en tiempo real de resultados de búsqueda y actualizaciones de estado.

Objetivos de diseño clave:

  • Acceso centralizado: Diseñado con la centralización en mente, permitiendo a organizaciones o individuos gestionar una única clave de API de Brave Search y proporcionar acceso controlado a múltiples clientes o aplicaciones internas.
  • Observabilidad: Incluye un registro robusto para rastrear solicitudes, interacciones con la API, errores y límites de tasa, proporcionando visibilidad sobre el uso y facilitando la depuración.
  • Despliegue flexible: Puede desplegarse de forma privada dentro de una red u opcionalmente exponerse públicamente mediante métodos como Kubernetes Ingress o el mapeo directo de puertos de Docker.

Características

  • Búsqueda web: Accede al índice de búsqueda web independiente de Brave para consultas generales, noticias, artículos, etc. Admite controles de paginación y filtrado.
  • Búsqueda local: Encuentra negocios, restaurantes y servicios con información detallada como dirección, número de teléfono y valoraciones.
  • Alternativas inteligentes: La búsqueda local recurre automáticamente a una búsqueda web filtrada si no se encuentran resultados locales específicos para la consulta.
  • Server-Sent Events (SSE): Transmisión eficiente y en tiempo real de resultados de búsqueda y estado de ejecución de herramientas.
  • Model Context Protocol (MCP): Se adhiere al estándar MCP para una integración perfecta con clientes compatibles.
  • Soporte de Docker: Incluye un Dockerfile para facilitar la contenedorización y el despliegue.
  • Helm Chart: Proporciona un Helm chart para el despliegue directo en clústeres de Kubernetes.

Requisitos previos

Dependiendo del método de despliegue que elijas, necesitarás algunos de los siguientes elementos:

  • Clave de API de Brave Search: Requerida para todos los métodos de despliegue. Consulta "Cómo empezar" a continuación.
  • Docker: Requerido si se despliega con Docker.
  • kubectl y Helm: Requeridos si se despliega en Kubernetes con Helm.
  • Node.js y npm: Requeridos solo para el desarrollo local (se recomienda Node.js v22.x o posterior).
  • Git: Requerido para clonar el repositorio para desarrollo local o para crear imágenes de Docker personalizadas.

Cómo empezar

1. Obtener una clave de API de Brave Search

  1. Regístrate en una cuenta de Brave Search API.
  2. Elige un plan (hay un nivel gratuito disponible).
  3. Genera tu clave de API desde el panel de desarrollador.

2. Configuración

El servidor requiere que la clave de API de Brave Search se establezca mediante la variable de entorno BRAVE_API_KEY.

Otras variables de entorno posibles (consulta src/config/config.ts para más detalles):

  • PORT: El puerto en el que escucha el servidor (por defecto 8080).
  • LOG_LEVEL: Nivel de detalle del registro (p. ej., info, debug).

Establece estas variables en tu entorno o mediante un archivo .env en la raíz del proyecto para el desarrollo local.

Instalación y uso

Elige el método de despliegue que mejor se adapte a tus necesidades:

Opción 1: Docker (recomendado para despliegue)

Requisitos previos: Docker instalado.

  1. Obtén una clave de API de Brave Search: Sigue los pasos de la sección "Cómo empezar".
  2. Descarga la imagen de Docker: Descarga la última imagen desde Docker Hub: 
    docker pull shoofio/brave-search-mcp-sse:latest
    O descarga una etiqueta de versión específica (p. ej., 1.0.10): 
    docker pull shoofio/brave-search-mcp-sse:1.0.10
    (Alternativamente, puedes crear la imagen localmente si es necesario. Clona el repositorio y ejecuta docker build -t brave-search-mcp-sse:custom .)
  3. Ejecuta el contenedor de Docker: Usa la etiqueta que descargaste (p. ej., latest o 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
    Esto ejecuta el servidor en modo separado, mapeando el puerto 8080 de tu host al contenedor.

Opción 2: Helm (despliegue en Kubernetes)

Requisitos previos: kubectl conectado a tu clúster, Helm instalado.

  1. Obtén una clave de API de Brave Search: Sigue los pasos de la sección "Cómo empezar".

  2. Añade el repositorio de Helm:

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

  3. Prepara el secreto de la clave de API (recomendado): Crea un secreto de Kubernetes en el namespace de destino:

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

  4. Instala el Helm chart: La versión del chart corresponde a la versión de la aplicación (la última es 1.0.10). Instala usando el secreto:

    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

    O proporciona la clave directamente (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. Configuración del chart: Puedes personalizar el despliegue sobrescribiendo los valores predeterminados. Crea un archivo YAML (p. ej., dev-values.yaml, prod-values.yaml) con la configuración deseada y usa la bandera -f durante la instalación: helm install ... -f dev-values.yaml.

    Consulta el archivo values.yaml predeterminado del chart para ver todas las opciones de configuración disponibles y sus valores predeterminados.

Opción 3: Desarrollo local

Requisitos previos: Node.js y npm (se recomienda v22.x o posterior), Git.

  1. Obtén una clave de API de Brave Search: Sigue los pasos de la sección "Cómo empezar".
  2. Clona el repositorio: 
    git clone <repository_url> # Replace with the actual URL
cd brave-search-mcp-sse
  3. Instala las dependencias: 
    npm install
  4. Establece las variables de entorno: Crea un archivo .env en el directorio raíz: 
    BRAVE_API_KEY=YOUR_API_KEY_HERE
PORT=8080
# LOG_LEVEL=debug
  5. Compila el código TypeScript: 
    npm run build
  6. Ejecuta el servidor: 
    npm start
# Or for development with auto-reloading (if nodemon/ts-node-dev is configured)
# npm run dev
    El servidor comenzará a escuchar en el puerto configurado (por defecto 8080).

Interacción con la API / Protocolo

Los clientes se conectan a este servidor mediante una solicitud HTTP GET para establecer una conexión SSE. El endpoint específico depende de tu despliegue (p. ej., http://localhost:8080/, http://<k8s-service-ip>:8080/, o a través de un Ingress).

Una vez conectados, el servidor y el cliente se comunican usando mensajes MCP a través del flujo SSE.

Herramientas disponibles

El servidor expone las siguientes herramientas a los clientes conectados:

  1. brave_web_search

    • Descripción: Realiza una búsqueda web general usando la Brave Search API.
    • Entradas:
      • query (cadena, obligatorio): La consulta de búsqueda.
      • count (número, opcional): Número de resultados a devolver (1-20, por defecto 10).
      • offset (número, opcional): Desplazamiento de paginación (0-9, por defecto 0).
      • (Otros parámetros de la API de Brave como search_lang, country, freshness, result_filter, safesearch podrían ser compatibles: consulta src/services/braveSearchApi.ts)
    • Salida: Transmite mensajes MCP que contienen resultados de búsqueda (título, URL, fragmento, etc.).

  2. brave_local_search

    • Descripción: Realiza una búsqueda de negocios y lugares locales usando la Brave Search API. Recurre a la búsqueda web si no se encuentran resultados locales.
    • Entradas:
      • query (cadena, obligatorio): La consulta de búsqueda local (p. ej., "pizza cerca de mí", "cafés en el centro").
      • count (número, opcional): Número máximo de resultados (1-20, por defecto 5).
    • Salida: Transmite mensajes MCP que contienen detalles de negocios locales (nombre, dirección, teléfono, valoración, etc.).

(Ejemplo usando curl - Nota: La interacción real con MCP requiere una biblioteca de cliente)

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

Ejemplo de configuración de cliente (Cursor)

Para usar este servidor con un cliente MCP como Cursor, debes configurar el cliente para que se conecte al endpoint SSE del servidor.

Añade la siguiente configuración a la configuración de Cursor (mcp.json o un archivo de configuración similar), reemplazando la URL con la dirección y el puerto reales donde tu servidor brave-search-mcp-sse sea accesible:

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

Explicación:

  • transport: Debe establecerse en "sse" para este servidor.
  • url: Esta es la parte crucial.
    • Si se ejecuta localmente con Docker (como se muestra en el ejemplo), http://localhost:8080/sse es probablemente correcto.
    • Si se ejecuta en Kubernetes, reemplaza localhost:8080 con la dirección/puerto apropiados del Servicio de Kubernetes o el hostname/ruta del Ingress configurado para alcanzar el puerto 8080 del servidor.
    • Asegúrate de que la ruta de la URL termine en /sse.

(Pueden aplicarse pasos de configuración similares a otros clientes MCP que admitan el transporte SSE, como versiones recientes de Claude Desktop, pero consulta su documentación específica.)

Estructura del proyecto

.
├── 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

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request con tus cambios. Asegúrate de que tu código se adhiera al estilo existente e incluya pruebas cuando corresponda. Revisaré los PRs según mi disponibilidad.

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.