Brave Search MCP/SSE サーバー

Brave Search APIを統合する Server-Sent Events (SSE) を使用した Model Context Protocol (MCP) の実装。ストリーミングインターフェースを通じて AI モデルやその他のクライアントに Web およびローカル検索機能を提供します。

概要

このサーバーは、モデルコンテキストプロトコルを理解する大規模言語モデルのツールプロバイダーとして機能します。SSE接続を介してBraveの強力なウェブ検索機能とローカル検索機能を公開し、検索結果とステータス更新のリアルタイムストリーミングを可能にします。

主な設計目標:

**集中アクセス:**集中性を念頭に置いて設計されており、組織または個人が単一の Brave Search API キーを管理し、複数の内部クライアントまたはアプリケーションへの制御されたアクセスを提供できます。
**可観測性:**リクエスト、API インタラクション、エラー、レート制限を追跡するための強力なログ記録機能を備えており、使用状況の可視性を提供し、デバッグを支援します。
**柔軟な展開:**ネットワーク内でプライベートに展開することも、Kubernetes Ingress や直接 Docker ポートマッピングなどの方法を使用してオプションでパブリックに公開することもできます。

特徴

Web 検索: 一般的なクエリ、ニュース、記事などを検索する Brave の独立した Web 検索インデックスにアクセスします。ページ区切りとフィルタリングコントロールをサポートします。
ローカル検索: 住所、電話番号、評価などの詳細情報を使用して、企業、レストラン、サービスを検索します。
スマートフォールバック: クエリに対して特定のローカル結果が見つからない場合、ローカル検索は自動的にフィルターされた Web 検索にフォールバックします。
サーバー送信イベント (SSE) : 検索結果とツール実行ステータスの効率的なリアルタイムストリーミング。
モデルコンテキストプロトコル (MCP) : 互換性のあるクライアントとのシームレスな統合のために MCP 標準に準拠しています。
Docker サポート: コンテナ化とデプロイメントを簡単に行うためのDockerfileが含まれています。
Helm チャート: Kubernetes クラスターへの簡単なデプロイのための Helm チャートを提供します。

前提条件

選択した展開方法に応じて、次のものが必要になります。

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" # 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 がインストールされている。

Brave Search API キーを取得する: 「はじめに」セクションの手順に従います。
Helm リポジトリを追加します。
helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/ helm repo update
**API キーシークレットを準備する (推奨):**ターゲット名前空間に Kubernetes シークレットを作成します。
kubectl create secret generic brave-search-secret \ --from-literal=api-key='YOUR_API_KEY_HERE' \ -n <your-namespace>
**Helmチャートをインストールします。**チャートのバージョンはアプリケーションのバージョンに対応しています（最新バージョンは1.0.10 ）。シークレットを使用してインストールします。
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"
**チャート設定：**デフォルト値を上書きすることで、デプロイメントをカスタマイズできます。必要な設定を含む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> # Replace with the actual 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 # 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 メッセージを使用して通信します。

利用可能なツール

サーバーは、接続されたクライアントに次のツールを公開します。

brave_web_search
- 説明: Brave Search API を使用して一般的な Web 検索を実行します。
- 入力:
  - query (文字列、必須): 検索クエリ。
  - count (数値、オプション): 返される結果の数 (1 ～ 20、デフォルトは 10)。
  - offset (数値、オプション): ページ区切りのオフセット (0-9、デフォルトは 0)。
  - ( search_lang 、 country 、 freshness 、 result_filter 、 safesearchなどの他の Brave API パラメータもサポートされている可能性があります - src/services/braveSearchApi.tsを確認してください)
- 出力: 検索結果 (タイトル、URL、スニペットなど) を含む MCP メッセージをストリームします。
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 などの MCP クライアントで使用するには、サーバーの SSE エンドポイントに接続するようにクライアントを構成する必要があります。

カーソル設定 ( 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で終わることを確認します。

(Claude Desktop の最新バージョンなど、SSE トランスポートをサポートする他の MCP クライアントにも同様の構成手順が適用される場合がありますが、それぞれの特定のドキュメントを参照してください。)

プロジェクト構造

.
├── 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

貢献

貢献を歓迎します！変更内容をプルリクエストでお気軽に送信してください。コードが既存のスタイルに準拠していること、および必要に応じてテストが含まれていることを確認してください。プルリクエストは時間の許す限りレビューさせていただきます。

ライセンス

このプロジェクトは、 MIT ライセンスの下でライセンスされます (LICENSE ファイルが存在するか、追加されることを前提としています)。

Brave Search MCP Server

Integrations