Brave Search MCP/SSE Server

Brave Search MCP/SSE サーバー

Server-Sent Events（SSE）を使用した Model Context Protocol（MCP）の実装です。Brave Search APIと連携し、ストリーミングインターフェースを通じて、AI モデルやその他のクライアントにウェブ検索とローカル検索の機能を提供します。

概要

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

主な設計目標：

• 一元的なアクセス： 一元管理を念頭に設計されており、組織や個人が単一の Brave Search API キーを管理し、複数の内部クライアントやアプリケーションに制御されたアクセスを提供できます。
• 可観測性： リクエスト、API とのやり取り、エラー、レート制限を追跡する堅牢なロギング機能を備えており、使用状況を可視化し、デバッグに役立てることができます。
• 柔軟なデプロイ： ネットワーク内にプライベートにデプロイできるほか、Kubernetes Ingress や Docker のポート直接マッピングなどを利用して、任意でパブリックに公開できます。

機能

• ウェブ検索：一般的なクエリ、ニュース、記事などを対象に、Brave の独自のウェブ検索インデックスを利用できます。ページネーションとフィルタリングの制御に対応しています。
• ローカル検索：住所、電話番号、評価などの詳細情報を含む、ビジネス、レストラン、サービスを検索できます。
• スマートなフォールバック：クエリに対して特定のローカル検索結果が見つからない場合、ローカル検索は自動的にフィルタリングされたウェブ検索に切り替わります。
• Server-Sent Events（SSE）：検索結果とツール実行のステータスを、効率よくリアルタイムにストリーミングします。
• Model Context Protocol（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 キーを取得する

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 キーを取得します：「Getting Started」セクションの手順に従ってください。
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 キーを取得します：「Getting Started」セクションの手順に従ってください。

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 チャートをインストールします： チャートのバージョンはアプリケーションのバージョンに対応しています（最新は 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. チャートの設定： デフォルト値を上書きして、デプロイをカスタマイズできます。希望する設定を記述した 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 キーを取得します：「Getting Started」セクションの手順に従ってください。
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 で終わることを確認してください。

（最近のバージョンの 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

コントリビューション

コントリビューションを歓迎します！変更を加えた Pull Request をお気軽に提出してください。コードが既存のスタイルに準拠し、該当する場合はテストが含まれていることを確認してください。時間の許す範囲で PR をレビューします。

ライセンス

この MCP サーバーはMIT Licenseの下でライセンスされています。つまり、MIT License の利用規約に従う限り、このソフトウェアを自由に使用、変更、配布できます。詳細については、プロジェクトリポジトリの LICENSE ファイルを参照してください。