Brave Search MCP/SSE 服务器

使用服务器发送事件 (SSE) 实现的模型上下文协议 (MCP) 集成了Brave Search API ，通过流接口为 AI 模型和其他客户端提供网络和本地搜索功能。

概述

该服务器充当理解模型上下文协议的大型语言模型的工具提供者。它通过 SSE 连接公开 Brave 强大的 Web 和本地搜索功能，从而实现搜索结果和状态更新的实时流式传输。

主要设计目标：

• **集中访问：**设计时考虑了中心性，允许组织或个人管理单个 Brave Search API 密钥并提供对多个内部客户端或应用程序的受控访问。
• **可观察性：**具有强大的日志记录功能，可跟踪请求、API 交互、错误和速率限制，提供使用情况的可见性并帮助调试。
• **灵活部署：**可以在网络内私下部署，也可以选择通过 Kubernetes Ingress 或直接 Docker 端口映射等方法公开部署。

特征

• 网络搜索：访问 Brave 的独立网络搜索索引，获取一般查询、新闻、文章等。支持分页和过滤控制。
• 本地搜索：查找企业、餐馆和服务，包括地址、电话号码和评级等详细信息。
• 智能回退：如果未找到查询的特定本地结果，本地搜索将自动回退到过滤的网络搜索。
• 服务器发送事件 (SSE) ：高效、实时地传输搜索结果和工具执行状态。
• 模型上下文协议 (MCP) ：遵循 MCP 标准，可与兼容客户端无缝集成。
• Docker 支持：包含一个Dockerfile ，可轻松实现容器化和部署。
• Helm Chart ：提供 Helm Chart，可直接部署到 Kubernetes 集群。

先决条件

根据您选择的部署方法，您将需要以下一些内容：

• Brave Search API 密钥：所有部署方式均需使用。请参阅下方的“入门指南”。
• Docker ：如果使用 Docker 部署则必需。
• kubectl 和 Helm ：如果使用 Helm 部署到 Kubernetes，则需要。
• Node.js 和 npm ：仅本地开发所需（建议使用 Node.js v22.x 或更高版本）。
• Git ：需要克隆存储库以进行本地开发或构建自定义 Docker 镜像。

入门

1. 获取 Brave Search API 密钥

1. 注册一个Brave Search API 帐户。
2. 选择一个计划（提供免费套餐）。
3. 从开发者仪表板生成您的 API 密钥。

2.配置

服务器需要通过BRAVE_API_KEY环境变量设置 Brave Search API 密钥。

其他潜在的环境变量（有关详细信息，请查看src/config/config.ts ）：

• PORT ：服务器监听的端口（默认为8080 ）。
• LOG_LEVEL ：日志详细程度（例如， info 、 debug ）。

在您的环境中设置这些变量或使用项目根目录中的.env文件进行本地开发。

安装和使用

选择最适合您需求的部署方法：

选项 1：Docker（推荐部署）

**先决条件：**已安装 Docker。

1. **获取 Brave Search API 密钥：**按照“入门”部分中的步骤操作。
2. **拉取 Docker 镜像：**从 Docker Hub 拉取最新镜像：
   docker pull shoofio/brave-search-mcp-sse:latest
   或者拉取特定的版本标签（例如1.0.10 ）：
   docker pull shoofio/brave-search-mcp-sse:1.0.10
   （或者，如果需要，您可以本地构建映像。克隆存储库并运行docker build -t brave-search-mcp-sse:custom . ）
3. **运行 Docker 容器：**使用您拉取的标签（例如latest或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
   这将以分离模式运行服务器，将主机上的端口 8080 映射到容器。

选项 2：Helm（Kubernetes 部署）

先决条件： kubectl已连接到您的集群，并且已安装 Helm。

1. **获取 Brave Search API 密钥：**按照“入门”部分中的步骤操作。
2. 添加 Helm 存储库：
   helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/ helm repo update
3. **准备 API 密钥（推荐）：**在目标命名空间中创建 Kubernetes 密钥：
   kubectl create secret generic brave-search-secret \ --from-literal=api-key='YOUR_API_KEY_HERE' \ -n <your-namespace>
4. 安装 Helm chart： chart 版本对应应用程序版本（最新版本为1.0.10 ）。使用 secret 安装：
   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
   或者直接提供密钥（不太安全）：
   helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.apiKey="YOUR_API_KEY_HERE"
5. **Chart 配置：**您可以通过覆盖默认值来自定义部署。创建一个包含所需设置的 YAML 文件（例如dev-values.yaml或prod-values.yaml ），并在安装过程中使用-f标志： helm install ... -f dev-values.yaml 。请参阅图表的默认values.yaml文件以查看所有可用的配置选项及其默认设置。

选项 3：本地开发

先决条件： Node.js 和 npm（建议使用 v22.x 或更高版本）、Git。

1. **获取 Brave Search API 密钥：**按照“入门”部分中的步骤操作。
2. 克隆存储库：
   git clone <repository_url> # Replace with the actual URL cd brave-search-mcp-sse
3. 安装依赖项：
   npm install
4. **设置环境变量：**在根目录中创建一个.env文件：
   BRAVE_API_KEY=YOUR_API_KEY_HERE PORT=8080 # LOG_LEVEL=debug
5. 构建 TypeScript 代码：
   npm run build
6. 运行服务器：
   npm start # Or for development with auto-reloading (if nodemon/ts-node-dev is configured) # npm run dev
   服务器将开始监听配置的端口（默认为8080 ）。

API/协议交互

客户端通过 HTTP GET 请求连接到此服务器，以建立 SSE 连接。具体端点取决于你的部署（例如， http://localhost:8080/ 、 http://<k8s-service-ip>:8080/ ，或通过 Ingress）。

一旦连接，服务器和客户端就通过 SSE 流使用 MCP 消息进行通信。

可用工具

服务器向连接的客户端公开以下工具：

1. brave_web_search
   • 描述：使用 Brave Search API 执行常规网络搜索。
   • 输入：
     • query （字符串，必需）：搜索查询。
     • count （数字，可选）：返回的结果数（1-20，默认10）。
     • offset （数字，可选）：分页偏移量（0-9，默认为 0）。
     • （其他 Brave API 参数，如search_lang 、 country 、 freshness 、 result_filter 、 safesearch可能受支持 - 检查src/services/braveSearchApi.ts ）
   • 输出：包含搜索结果（标题、URL、片段等）的流式 MCP 消息。
2. brave_local_search
   • 描述：使用 Brave Search API 搜索本地商家和地点。如果未找到本地结果，则返回网页搜索。
   • 输入：
     • query （字符串，必需）：本地搜索查询（例如，“我附近的披萨”，“市中心的咖啡馆”）。
     • count （数字，可选）：最大结果数（1-20，默认 5）。
   • 输出：包含本地业务详细信息（名称、地址、电话、评级等）的流式 MCP 消息。

（使用curl的示例 - 注意：实际的 MCP 交互需要客户端库）

客户端配置示例（游标）

要将此服务器与 Cursor 等 MCP 客户端一起使用，您需要配置客户端以连接到服务器的 SSE 端点。

将以下配置添加到您的 Cursor 设置（ mcp.json或类似的配置文件）中，将 URL 替换为您的brave-search-mcp-sse服务器可访问的实际地址和端口：

解释：

• transport ：对于此服务器，必须设置为"sse" 。
• url ：这是关键部分。
  • 如果通过 Docker 在本地运行（如示例所示）， http://localhost:8080/sse可能是正确的。
  • 如果在 Kubernetes 中运行，请将localhost:8080替换为适当的 Kubernetes 服务地址/端口或配置为到达服务器端口 8080 的 Ingress 主机名/路径。
  • 确保 URL 路径以/sse结尾。

（类似的配置步骤可能适用于支持 SSE 传输的其他 MCP 客户端，例如 Claude Desktop 的最新版本，但请参阅其具体文档。）

项目结构

贡献

欢迎贡献代码！请随时提交 Pull 请求，包含您的修改。请确保您的代码遵循现有代码规范，并在适用的情况下包含测试。我会在时间允许的情况下审核 PR。

执照

该项目根据MIT 许可证获得许可（假设 LICENSE 文件存在或将被添加）。