Brave Search MCP/SSE Server

Brave Search MCP/SSE 服务器

这是基于服务器发送事件（SSE）实现的模型上下文协议（MCP），集成了 Brave Search API，通过流式接口为 AI 模型和其他客户端提供网页和本地搜索能力。

概述

此服务为理解模型上下文协议的大语言模型提供工具。它通过 SSE 连接提供 Brave 强大的网页和本地搜索功能，可实时流式传输搜索结果和状态更新。

主要设计目标：

• 集中访问： 设计时注重集中管理，允许组织或个人统一管理一个 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 密钥 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
     # 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。

   请参阅 chart 的默认 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 交互需要客户端库)

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

客户端配置示例（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             # 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

参与贡献

欢迎贡献！欢迎提交包含更改的 Pull Request。请确保代码遵循现有风格，并在适用时包含测试。我会视时间安排审查 PR。

许可证

此 MCP 服务采用MIT License许可。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT License 的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。