勇敢搜索MCP服务器事件流

Name: 勇敢搜索MCP服务器事件流
Author: Shoofio

作者：Shoofio13 星标更新：2025-04-24

安装使用来源：spider==github.com

项目介绍

Brave Search MCP/SSE Server

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

概览

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

关键设计目标：

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

功能

网络搜索： 访问Brave独立的网络搜索引擎，用于一般查询、新闻、文章等。支持分页和过滤控制。
本地搜索： 查找企业、餐馆和服务，包括详细信息如地址、电话号码和评分。
智能回退： 如果没有找到特定的本地结果，本地搜索会自动回退到过滤后的网络搜索。
服务器发送事件（SSE）： 高效地实时流式传输搜索结果和工具执行状态。
模型上下文协议（MCP）： 遵循MCP标准，以便与兼容客户端无缝集成。
Docker 支持： 包含一个 Dockerfile，便于容器化和部署。
Helm 图表： 提供一个Helm图表，便于部署到Kubernetes集群。

先决条件

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

Brave Search API 密钥： 所有部署方法都需要。参见“开始”部分。
Docker： 使用Docker部署时需要。
kubectl 和 Helm： 使用Helm部署到Kubernetes时需要。
Node.js 和 npm： 仅在本地开发时需要（推荐使用Node.js v22.x或更高版本）。
Git： 克隆仓库进行本地开发或构建自定义Docker镜像时需要。

开始

1. 获取Brave Search API密钥

注册一个Brave Search API账户。
选择一个计划（免费层级可用）。
从开发者仪表板生成您的API密钥。

2. 配置

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

其他潜在的环境变量（详情请查看 src/config/config.ts）：

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

可以在环境中设置这些变量，或者在项目根目录下的.env文件中设置，以供本地开发使用。

安装及使用

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

方案1：Docker（推荐用于部署）

先决条件： 已安装Docker。

获取Brave Search API密钥： 按照“开始”部分中的步骤操作。
拉取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 .)

运行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。

获取Brave Search API密钥： 按照“开始”部分中的步骤操作。

添加Helm仓库：

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

准备API密钥Secret（推荐）： 在目标命名空间中创建一个Kubernetes Secret：

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

安装Helm图表： 图表版本对应于应用版本（最新为 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"

图表配置： 您可以通过覆盖默认值来自定义部署。创建一个YAML文件（例如，dev-values.yaml，prod-values.yaml），包含您所需的设置，并在安装时使用 -f 标志：helm install ... -f dev-values.yaml。

参考图表的默认values.yaml文件，了解所有可用配置选项及其默认设置。

方案3：本地开发

先决条件： Node.js和npm（推荐使用v22.x或更高版本），Git。

获取Brave Search API密钥： 按照“开始”部分中的步骤操作。

克隆仓库：

git clone <repository_url> # 替换为实际URL
cd brave-search-mcp-sse

安装依赖项：
```
npm install
```

设置环境变量： 在根目录下创建一个.env文件：

BRAVE_API_KEY=YOUR_API_KEY_HERE
PORT=8080
# LOG_LEVEL=debug

构建TypeScript代码：
```
npm run build
```

运行服务器：

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消息进行通信。

可用工具

服务器向连接的客户端暴露以下工具：

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消息。
brave_local_search
- 描述： 使用Brave Search API搜索本地企业和地点。如果没有找到本地结果，则回退到网络搜索。
- 输入：
  - query（字符串，必需）：本地搜索查询（例如，“附近披萨”，“市中心咖啡馆”）。
  - count（数字，可选）：最大结果数量（1-20，默认5）。
- 输出： 流式传输包含本地企业详细信息（名称、地址、电话、评分等）的MCP消息。

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

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

客户端配置示例（Cursor）

要使用此服务器与MCP客户端（如Cursor）配合，您需要配置客户端以连接到服务器的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服务地址/端口或配置为到达服务器8080端口的Ingress主机名/路径。
- 确保URL路径以 /sse 结尾。

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

项目结构

.
├── Dockerfile             # 容器构建定义
├── helm/                  # Kubernetes部署的Helm图表
│   └── 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。

许可证

此MCP服务器根据MIT许可证授权。这意味着您可以自由使用、修改和分发软件，但需遵守MIT许可证的条款和条件。更多细节，请参阅项目存储库中的LICENSE文件。