Servidor MCP/SSE de Brave Search

Una implementación del Protocolo de contexto de modelo (MCP) que utiliza eventos enviados por el servidor (SSE) que integra la API de búsqueda Brave , proporcionando modelos de IA y otros clientes con capacidades de búsqueda web y local a través de una interfaz de transmisión.

Descripción general

Este servidor actúa como proveedor de herramientas para grandes modelos de lenguaje que comprenden el protocolo de contexto de modelo. Expone las potentes funcionalidades de búsqueda web y local de Brave mediante una conexión SSE, lo que permite la transmisión en tiempo real de los resultados de búsqueda y las actualizaciones de estado.

Objetivos clave del diseño:

• Acceso centralizado: diseñado con la centralidad en mente, lo que permite a las organizaciones o personas administrar una única clave API de Brave Search y brindar acceso controlado a múltiples clientes o aplicaciones internas.
• Observabilidad: cuenta con un registro sólido para rastrear solicitudes, interacciones de API, errores y límites de velocidad, lo que proporciona visibilidad del uso y ayuda a la depuración.
• Implementación flexible: se puede implementar de forma privada dentro de una red o, opcionalmente, exponer de forma pública a través de métodos como Kubernetes Ingress o mapeo directo de puertos Docker.

Características

• Búsqueda web : acceda 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 : encuentre empresas, restaurantes y servicios con información detallada como dirección, número de teléfono y calificaciones.
• Respaldos 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.
• Eventos enviados por el servidor (SSE) : transmisión eficiente y en tiempo real de los resultados de búsqueda y del estado de ejecución de la herramienta.
• Protocolo de contexto de modelo (MCP) : se adhiere al estándar MCP para una integración perfecta con clientes compatibles.
• Compatibilidad con Docker : incluye un Dockerfile para facilitar la contenedorización y la implementación.
• Gráfico de Helm : proporciona un gráfico de Helm para una implementación sencilla en clústeres de Kubernetes.

Prerrequisitos

Dependiendo del método de implementación elegido, necesitará algunos de los siguientes:

• Clave API de Brave Search : Requerida para todos los métodos de implementación. Consulta "Introducción" a continuación.
• Docker : Obligatorio si se realiza la implementación mediante Docker.
• kubectl y Helm : obligatorio si se implementa en Kubernetes usando Helm.
• Node.js y npm : necesarios solo para desarrollo local (se recomienda Node.js v22.x o posterior).
• Git : necesario para clonar el repositorio para el desarrollo local o crear imágenes Docker personalizadas.

Empezando

1. Obtenga una clave API de Brave Search

1. Regístrese para obtener una cuenta de Brave Search API .
2. Elija un plan (hay un nivel gratuito disponible).
3. Genere su clave API desde el panel de desarrollador .

2. Configuración

El servidor requiere que la clave API de Brave Search se configure a través de la variable de entorno BRAVE_API_KEY .

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

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

Establezca estas variables en su entorno o utilizando un archivo .env en la raíz del proyecto para el desarrollo local.

Instalación y uso

Elija el método de implementación que mejor se adapte a sus necesidades:

Opción 1: Docker (recomendado para la implementación)

Requisitos previos: Docker instalado.

1. Obtenga una clave API de Brave Search: siga los pasos de la sección "Introducción".
2. Extraiga la imagen de Docker: Extraiga la imagen más reciente de Docker Hub:
   docker pull shoofio/brave-search-mcp-sse:latest
   O extraiga una etiqueta de versión específica (por ejemplo, 1.0.10 ):
   docker pull shoofio/brave-search-mcp-sse:1.0.10
   (Alternativamente, puede crear la imagen localmente si es necesario. Clone el repositorio y ejecute docker build -t brave-search-mcp-sse:custom .
3. Ejecute el contenedor Docker: use la etiqueta que extrajo (por ejemplo, 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, asignando el puerto 8080 de su host al contenedor.

Opción 2: Helm (Implementación de Kubernetes)

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

1. Obtenga una clave API de Brave Search: siga los pasos de la sección "Introducción".
2. Agregue el repositorio Helm:
   helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/ helm repo update
3. Preparar el secreto de la clave API (recomendado): cree un secreto de Kubernetes en el espacio de nombres de destino:
   kubectl create secret generic brave-search-secret \ --from-literal=api-key='YOUR_API_KEY_HERE' \ -n <your-namespace>
4. Instalar el gráfico de Helm: La versión del gráfico corresponde a la de la aplicación (la última versión es 1.0.10 ). Instalar 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 proporcione 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 gráfico: Puede personalizar la implementación sobrescribiendo los valores predeterminados. Cree un archivo YAML (p. ej., dev-values.yaml o prod-values.yaml ) con la configuración deseada y use la opción -f durante la instalación: helm install ... -f dev-values.yaml .Consulte el archivo values.yaml del gráfico para ver todas las opciones de configuración disponibles y sus configuraciones predeterminadas.

Opción 3: Desarrollo local

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

1. Obtenga una clave API de Brave Search: siga los pasos de la sección "Introducción".
2. Clonar el repositorio:
   git clone <repository_url> # Replace with the actual URL cd brave-search-mcp-sse
3. Instalar dependencias:
   npm install
4. Establecer variables de entorno: Cree un archivo .env en el directorio raíz:
   BRAVE_API_KEY=YOUR_API_KEY_HERE PORT=8080 # LOG_LEVEL=debug
5. Construya el código TypeScript:
   npm run build
6. Ejecutar 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 (predeterminado 8080 ).

Interacción API/Protocolo

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

Una vez conectados, el servidor y el cliente se comunican mediante mensajes MCP a través de la transmisión 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 utilizando la API de búsqueda Brave.
   • Entradas :
     • query (cadena, obligatoria): la consulta de búsqueda.
     • count (número, opcional): Número de resultados a devolver (1-20, predeterminado 10).
     • offset (número, opcional): desplazamiento de paginación (0-9, predeterminado 0).
     • (Es posible que se admitan otros parámetros de la API de Brave como search_lang , country , freshness , result_filter y safesearch ; consulte 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 : Busca negocios y lugares locales mediante la API de búsqueda de Brave. Si no encuentra resultados locales, recurre a la búsqueda web.
   • Entradas :
     • query (cadena, obligatoria): la consulta de búsqueda local (por ejemplo, "pizza cerca de mí", "cafés en el centro").
     • count (número, opcional): Número máximo de resultados (1-20, predeterminado 5).
   • Salida : Transmite mensajes MCP que contienen detalles comerciales locales (nombre, dirección, teléfono, calificación, etc.).

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

Ejemplo de configuración del cliente (Cursor)

Para utilizar este servidor con un cliente MCP como Cursor, debe configurar el cliente para que se conecte al punto final SSE del servidor.

Agregue la siguiente configuración a la configuración de su Cursor ( mcp.json o un archivo de configuración similar), reemplazando la URL con la dirección y el puerto reales donde se puede acceder a su servidor brave-search-mcp-sse :

Explicación:

• transport : debe configurarse como "sse" para este servidor.
• url : Esta es la parte crucial.
  • Si se ejecuta localmente a través de Docker (como se muestra en el ejemplo), es probable que http://localhost:8080/sse sea correcto.
  • Si se ejecuta en Kubernetes, reemplace localhost:8080 con la dirección/puerto del servicio Kubernetes apropiado o el nombre de host/ruta de Ingress configurado para llegar al puerto 8080 del servidor.
  • Asegúrese de que la ruta URL termine con /sse .

(Es posible que se apliquen pasos de configuración similares a otros clientes MCP que admiten el transporte SSE, como versiones recientes de Claude Desktop, pero consulte su documentación específica).

Estructura del proyecto

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios. Asegúrese de que su código se ajuste al estilo actual e incluya pruebas cuando corresponda. Revisaré las solicitudes de incorporación de cambios cuando el tiempo lo permita.

Licencia

Este proyecto está licenciado bajo la Licencia MIT (asumiendo que existe o se agregará un archivo de LICENCIA).