Brave Search MCP/SSE 服务器

<!-- Add other badges here if applicable (e.g., build status, Docker pulls) -->

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

概述

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

主要设计目标：

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

特性

• Web 搜索：访问 Brave 的独立 Web 搜索索引，以进行常规查询、新闻、文章等。支持分页和过滤控制。
• 本地搜索：查找具有详细信息（如地址、电话号码和评分）的商家、餐厅和服务。
• 智能回退：如果查询没有找到特定的本地结果，本地搜索会自动回退到经过筛选的 Web 搜索。
• 服务器发送事件 (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" # 可选：如果需要，定义端口
     # -e LOG_LEVEL="info" # 可选：设置日志级别
     --name brave-search-server \
     shoofio/brave-search-mcp-sse:latest # 或您的特定标签
   

   这将在分离模式下运行服务器，将主机上的端口 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 密钥 Secret（推荐）： 在目标命名空间中创建一个 Kubernetes secret：

   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
     # 可选：指定版本：--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。

   请参阅 chart 的默认 values.yaml 文件，以查看所有可用的配置选项及其默认设置。

选项 3：本地开发

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

1. 获取 Brave Search API 密钥： 按照“入门”部分中的步骤操作。
2. 克隆存储库：

   git clone <repository_url> # 替换为实际 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
   # 或者用于具有自动重新加载功能的开发（如果配置了 nodemon/ts-node-dev）
   # 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 执行常规 Web 搜索。
   • 输入：
     • 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 搜索本地商家和地点。如果未找到本地结果，则回退到 Web 搜索。
   • 输入：
     • query（字符串，必需）：本地搜索查询（例如，“我附近的披萨店”、“市中心的咖啡馆”）。
     • count（数字，可选）：最大结果数（1-20，默认为 5）。
   • 输出：流式传输包含本地商家详细信息（名称、地址、电话、评分等）的 MCP 消息。

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

# 示例：连接到 SSE 端点（不会直接显示 MCP 消息）
curl -N http://localhost:8080/ # 或您部署的端点

客户端配置示例 (Cursor)

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

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

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

说明：

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

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

项目结构

.
├── Dockerfile             # 容器构建定义
├── helm/                  # 用于 Kubernetes 部署的 Helm chart
│   └── brave-search-mcp-sse/
├── node_modules/        # 项目依赖项（git 忽略）
├── src/                   # 源代码 (TypeScript)
│   ├── config/            # 配置加载
│   ├── services/          # Brave API 交互逻辑
│   ├── tools/             # MCP 的工具定义
│   ├── transport/         # SSE/MCP 通信处理
│   ├── types/             # TypeScript 类型定义
│   ├── utils/             # 实用程序函数
│   └── index.ts           # 主应用程序入口点
├── dist/                  # 编译后的 JavaScript 输出（git 忽略）
├── package.json           # 项目元数据和依赖项
├── tsconfig.json          # TypeScript 编译器选项
├── .env.example           # 示例环境变量文件
├── .gitignore
└── README.md              # 此文件

贡献

欢迎贡献！请随时提交包含您的更改的 Pull Request。确保您的代码符合现有样式，并在适用的情况下包含测试。我会尽快审查 PR。

许可证

本项目已获得 MIT 许可证 的许可（假设存在或将添加 LICENSE 文件）。