couchbase-guru

Couchbase Guru MCP サーバー

LLMがMCPクライアントからCouchbaseのドキュメントを検索できるMCPサーバーです。ask_couchbase_docsという単一のツールを公開し、質問をホスト型の検索拡張生成（RAG）ドキュメントエージェントに転送して、参照元リンク付きの回答を返します。

Couchbase クラスターや認証情報は不要です。 サーバーはドキュメントエージェントのバックエンドとのみ通信し、データにはアクセスしません。

ツール

ツール名	説明
ask_couchbase_docs	公式ドキュメントを検索して、Couchbase の製品、機能、SDK、サービス、チュートリアル、サンプルについての質問に回答します。自然言語による回答に続けて、ドキュメントの参照元 URL を返します。

完全で、それだけで内容が分かる質問をしてください。バックエンドには会話履歴がないため、該当する場合は製品、バージョン、言語を含めてください（例：「Couchbase Server 7.6 で Python SDK を使ってプライマリーインデックスを作成するにはどうすればよいですか？」）。

前提条件

• Python 3.10 以降。
• サーバーの実行に必要なuv。
• Claude Desktop、Cursor、VS CodeなどのMCP クライアント。

設定

サーバーは、ビルド済みの PyPI パッケージから、または uv を使ってソースから実行できます。設定なしで動作し、デフォルトでは公開ドキュメントエージェントが使用されます。

PyPI から実行する

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uvx",
      "args": ["couchbase-guru"]
    }
  }
}

すでに他の MCP サーバーを設定している場合は、このエントリを既存の mcpServers オブジェクトに追加してください。

ソースから実行する

リポジトリをクローンします。

git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git

次に、MCP クライアントの接続先として指定します。

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/couchbase-guru/",
        "run",
        "src/mcp_server.py"
      ]
    }
  }
}

path/to/cloned/repo/couchbase-guru/ は、マシン上にクローンしたリポジトリのパスにしてください。末尾のスラッシュを忘れずに付けてください。

オプション

すべてのオプションは任意で、CLI 引数または環境変数で設定できます。

CLI 引数	環境変数	説明	デフォルト
--transport	CB_MCP_TRANSPORT	トランスポートモード：stdio または http	stdio
--host	CB_MCP_HOST	HTTP トランスポートモードのホスト	127.0.0.1
--port	CB_MCP_PORT	HTTP トランスポートモードのポート	8000
--agent-base-url	CB_AGENT_BASE_URL	ドキュメントエージェントのバックエンドのベース URL。独自のセルフホストエージェントを使用する場合に設定します。未設定の場合は公開エージェントが使用されます。	公開エージェント
--agent-ip-salt	CB_AGENT_IP_SALT	クライアント IP を仮名化するための秘密のソルト（HTTP トランスポート）。複数のインスタンス間で一貫したハッシュを使う場合は共通の値を設定します。未設定の場合はローカルのソルトが生成されます。	自動生成

インストールされているバージョンを確認します。

uvx couchbase-guru --version

ドキュメントエージェントのセルフホスティング

デフォルトでは、サーバーは共有の公開ドキュメントエージェントを使用するため、ほとんどのユーザーはセットアップ不要です。独自のエージェントバックエンドを実行している場合は、サーバーの接続先として指定します。

uvx couchbase-guru --agent-base-url https://your-agent.example.com

レート制限とプライバシー

公開エージェントでは、公平な利用のためのレート制限を適用しています。これを支援するため、サーバーはバックエンドに仮名化されたデバイス識別子を User-Agent ヘッダーで送信します。

• stdio：一度だけランダムな ID を生成し、マシン上のユーザーごとのファイルに保存します。
• HTTP：接続元 IP のソルト付き一方向ハッシュを使用します。生のアドレスは送信されません。

MCP サーバー自体は、質問の内容や個人データを保存しません。レート制限のための情報を共有したくない場合は、エージェントをセルフホストしてください（上記を参照）。

クライアント固有の設定

Claude Desktop

1. 設定ファイルを編集します（MCP クイックスタートガイドを参照してください）。
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. mcpServers セクションに設定を追加します。
3. Claude Desktop を再起動します。

ログ：~/Library/Logs/Claude（macOS）または %APPDATA%\Claude\Logs（Windows）。

Cursor

1. Cursor で、Cursor Settings > Tools & Integrations > MCP Tools に移動します。
2. 設定を手動で追加するか、ワンクリックの Cursor にインストールリンクを使用します。
3. 保存してから更新し、サーバーが有効になっていることを確認します。

ログ：下部パネルで Output をクリックし、ドロップダウンから Cursor MCP を選択します。

Windsurf Editor

1. Command Palette > Windsurf MCP Configuration Panel（または Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers）を開きます。
2. Add Server > Add custom server をクリックし、設定を追加します。
3. 保存してから更新し、サーバーが有効になっていることを確認します。

詳しくは、Windsurf MCP のドキュメントを参照してください。

VS Code

1. ワークスペースに .vscode/mcp.json を作成します（または MCP: Open User Configuration を実行してグローバル設定を作成します）。

2. VS Code では、最上位のキーとして mcpServers ではなく servers を使用します。

   {
     "servers": {
       "couchbase-guru": {
         "command": "uvx",
         "args": ["couchbase-guru"]
       }
     }
   }
   

3. 保存したら、インラインアクションリストを使ってサーバーの Start／Stop や管理を行います。

詳しくは、VS Code MCP ドキュメントを参照してください。

JetBrains IDEs

1. AI Assistant または Junie プラグインをインストールします。
2. Settings > Tools > AI Assistant or Junie > MCP Server に移動します。 3.「+」をクリックして設定を追加し、Save をクリックしてから Apply をクリックします。

ログ：Help > Show Log in Finder (Explorer) > mcp > couchbase-guru。

Streamable HTTP トランスポートモード

サーバーは Streamable HTTP モードで実行できるため、複数のクライアントが 1 つのインスタンスに接続できます。まず、お使いの MCP クライアントがこのトランスポートをサポートしていることを確認してください。

uvx couchbase-guru --transport=http --port=8000

サーバーは http://localhost:8000/mcp で利用できます。

{
  "mcpServers": {
    "couchbase-guru-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

このモードは認証をサポートしていません。

Docker

イメージをビルドします。

docker build -t couchbase-guru .

実行します（デフォルトは stdio です。認証情報は不要です）。

{
  "mcpServers": {
    "couchbase-guru-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "couchbase-guru"]
    }
  }
}

HTTP トランスポートを使用するには、ポートを公開してトランスポートを設定します。

docker run --rm -i \
  -e CB_MCP_TRANSPORT=http \
  -e CB_MCP_HOST=0.0.0.0 \
  -e CB_MCP_PORT=8000 \
  -p 8000:8000 \
  couchbase-guru

LLM に関連するリスク

• 大規模言語モデルおよび類似技術の使用には、不正確または有害な出力が生成される可能性を含むリスクがあります。
• Couchbase は、こうした出力の品質や正確性を確認または評価しておらず、出力の内容は Couchbase の見解を反映していない場合があります。
• 大規模言語モデルおよび関連技術を使用するかどうかの判断と、適用されるライセンス条件、利用規約、および所属組織のポリシーの遵守については、お客様が単独で責任を負います。

トラブルシューティング

• uv/uvx がインストールされ、PATH に含まれていることを確認してください。command フィールドに uv/uvx の絶対パスを指定する必要がある場合があります。
• 検索がタイムアウトする場合、ドキュメントのバックエンドが混み合っている可能性があります。少し待ってから再試行してください。
• パブリックバックエンドが原因かどうかを切り分けるには、--agent-base-url を指定してご自身のエージェントに対して実行してください。
• リポジトリを更新した後にソースから実行する場合は、uv sync を実行して依存関係を更新してください。
• MCP クライアントのログ（上記の場所）でエラーを確認してください。

テスト

ユニットテストはオフラインで実行されます（バックエンドはモックされています）。

uv sync --extra dev
uv run pytest tests/

統合テストは、稼働中のエージェントバックエンドに対してツールをエンドツーエンドで実行します。実行は任意です。

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

デフォルトではパブリックエージェントが使用されます。別のバックエンドを対象にするには、CB_AGENT_BASE_URL を設定してください。

---

👩‍💻 貢献

貢献を歓迎します！バグの報告、機能のリクエスト、改善への貢献を行うには、GitHub の issue を作成してください。

開発環境のセットアップ（uv を使った環境構築、Ruff による lint／フォーマット、pre-commit フック、プロジェクト構成）については、CONTRIBUTING.md をご覧ください。

# Clone and set up
git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git
cd couchbase-guru

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

---

📢 サポートポリシー

このプロジェクトに関心をお寄せいただき、ありがとうございます！このプロジェクトは Couchbase コミュニティによって保守されており、サポートチームによる公式サポートの対象ではありません。当社のエンジニアがこのリポジトリを監視・保守し、ベストエフォートで問題の解決に努めます。お問い合わせはすべて GitHub 上で行ってください。