Couchbase Guru MCP Server

Ein MCP-Server, der LLMs ermöglicht, in der Couchbase-Dokumentation von Ihrem MCP-Client aus zu suchen. Er stellt ein einziges Tool bereit, ask_couchbase_docs, das Ihre Frage an einen gehosteten Retrieval-Augmented-(RAG-)Dokumentationsagenten weiterleitet und eine Antwort mit Quellenlinks zurückgibt.

Es ist kein Couchbase-Cluster oder keine Anmeldedaten erforderlich. Der Server kommuniziert nur mit dem Backend des Dokuumentationsagenten, nicht mit Ihren Daten.

Tool

Stellen Sie vollständige, in sich geschlossene Fragen – das Backend verfügt über keinen Gesprächsverlauf. Geben Sie daher, wo relevant, das Produkt, die Version und die Srache an (z. B. „Wie erstelle ich mit dem Python-SDK in Couchbase Server 7.6 einen primären Index?“).

Related MCP server: docrag

Voraussetzungen

• Python 3.10 oder höher.

• uv muss installiert sein, um den Server auszuführen.

• Ein MCP-Client wie Claude Desktop, Cursor oder VS Code.

Konfiguration

Der Server kann aus dem vorgefertigten PyPI-Paket oder aus dem Quellcode mit uv ausgeführt werden. Er funktioniert ohne jede Konfiguration – standardmäßig wird der öffentliche Dokumentationsagent verwendet.

Ausführen über PyPI

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

Wenn Sie bereits andere MCP-Server konfiguriert haben, fügen Sie diesen Eintrag zum vorhandenen mcpServers-Objekt hinzu.

Ausführen aus dem Quellcode

Klonen Sie das Repository:

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

Richten Sie dann Ihren MCP-Client darauf aus:

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

path/to/cloned/repo/couchbase-guru/ sollte der Pfad zum geklonten Repository auf Ihrem Rechner sein. Vergessen Sie den abschließenden Schrägstrich nicht.

Optionen

Alle Optionen sind optional und können über ein CLI-Argument oder eine Umgebungsvariable gesetzt werden:

Überprüfen Sie die installierte Version mit:

uvx couchbase-guru --version

Selbsthosting des Dokuumentationsagenten

Standardmäßig verwendet der Server einen gemeinsam genutzen, öffentlichen Dokuumentationsagenten, sodass die meisten Benutzer keine Einrichtung benötigen. Wenn Sie ein eigenes Agenten-Backend betreiben, richten Sie den Server darau aus:

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

Ratenbegrenzung und Datenschutz

Der öffentliche Agent wendet Ratenbegrenzungen für faire Nutzung an. Um dies zu unterstützen, sendet der Server eine pseudonyme Gerätekennung an das Backend (im User-Agent-Header):

• stdio: eine zufällige ID, die einmalig generiert und in einer benutzerspezifischen Datei auf Ihrem Rechner gespeichert wird.

• HTTP: ein mit Salt versehener Einweg-Hash der verbindenden IP – die rohe Adresse wird niemals gesendet.

Der MCP-Server selbst speichert weder Frageinhalte noch personenbezogene Daten. Wenn Sie kein Signal zur Ratenbegrenzung teilen möchten, hosten Sie den Agenten selbst (siehe oben).

Clientspezifische Konfiguration

1. Bearbeiten Sie die Konfigurationsdatei (siehe die MCP-Schnellstartanleitung):

   • macO: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Fügen Sie die Konfiguration zum Abschnitt mcpServers hinzu.

3. Starten Sie Clade Desktop neu.

Protokolle: ~/Library/Logs/Claude (macO) oder %APPDATA%\Claude\Logs (Windows).

1. Gehen Sie in Cursor zu Cursor Settings > Tools & Integrations > MCP Tools.

2. Fügen Sie die Konfiguration manuell hinzu oder verwenden Sie den Ein-Klick-Link In Cursr installieren.

3. Speichern Sie und aktualisieren Sie dann, um zu bestätigen, dass der Server aktiviert ist.

Protokolle: Klicken Sie im unteren Bereich auf Output und wählen Sie Cursor MCP aus dem Dropdown-Menü.

1. Öffnen Sie Command Palette > Windsurf MCP Configuration Panel (oder Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers).

2. Klicken Sie auf Add Server > Add custom server und fügen Sie die Konfiguration hinzu.

3. Speichern Sie und aktualisieren Sie dann, um zu bestätigen, dass der Server aktiviert ist.

Weitere Details finden Sie in der Windsurf-MCP-Dokumentation.

1. Erstellen Sie .vscode/mcp.json in Ihrem Workspace (oder führen Sie MCP: Open User Configuration für eine globale Konfiguration aus).

2. VS Code verwendet servers als Schlüssel auf oberster Ebene (nicht mcpServers):

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

3. Verwenden Sie nach dem Speichern die Inline-Aktionsliste, um den Server zu Start/Stop/verwalten.

Weitere Details finden Sie in der VS Code MCP-Dokumentation.

1. Installieren Sie das Plugin AI Assistant oder Junie.

2. Navigieren Sie zu Settings > Tools > AI Assistant or Junie > MCP Server.

3. Klicken Sie auf „+“, fügen Sie die Konfiguration hinzu und klicken Sie auf Save, dann auf Apply.

Protokolle: Help > Show Log in Finder (Explorer) > mcp > couchbase-guru.

Streamable HTTTP-Transportmodus

Der Server kann im Streamable HTTTP-Modus ausgeführt werden, sodass mehrere Clients eine Verbindung zu einer Instanz herstellen können. Prüfen Sie zuerst, ob Ihr MCP-Client diesen Transport unterstützt.

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

Der Server ist unter http://localhost:8000/mcp verfügbar:

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

Dieser Modus bietet keine Unterstützung für Autorisierung.

Docker

Erstellen Sie das Image:

docker build -t couchbase-guru .

Führen Sie es aus (standardmäßig stdio; keine Anmeldedaten erforderlich):

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

Für den HTTP-Transport veröffentlichen Sie den Port und setzen Sie den Transport:

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

Risiken im Zusammenhang mit LLMs

• Die Verwendung großer Sprachmodelle und ähnlicher Technologien ist mit Risiken verbunden, einschließlich der Möglichkeit ungenauer oder schädlicher Ausgaben.

• Couchbase prüft oder bewertet die Qualität oder Richtigkeit solcher Ausgaben nicht, und solche Ausgaben geben möglicherweise nicht die Ansichten von Couchbase wieder.

• Sie sind allein dafür verantwortlich zu entscheiden, ob Sie große Sprachmodelle und verwandte Technologien verwenden, und alle geltenden Lizenzbedingungen, Nutzungsbedingungen und Richtlinien Ihrer Organisation einzuhalten.

Fehlerbehebung

• Stellen Sie sicher, dass uv/uvx installiert und in Ihrem PATH ist. Möglicherweise müssen Sie im Feld command einen absoluten Pfad zu uv/uvx angeben.

• Wenn eine Suche ein Timeout verursacht, ist das Dokumentations-Backend möglicherweise ausgelastet – versuchen Sie es gleich noch einmal.

• Um das öffentliche Backend auszuschließen, führen Sie den Server mit --agent-base-url gegen Ihren eigenen Agenten aus.

• Wenn Sie nach einem Update des Repositories aus dem Quellcode arbeiten, führen Sie uv sync aus, um die Abhängigkeiten zu aktualisieren.

• Prüfen Sie die Protokolle Ihres MCP-Clients (Orte siehe oben) auf Fehler.

Tests

Unit-Tests laufen offline (das Backend wird simuliert):

uv sync --extra dev
uv run pytest tests/

Integrationstests testen das Tool Ende-zu-Ende gegen ein echtes Agenten-Backend und sind optional:

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

Standardmäßig verwenden sie den öffentlichen Agenten; setzen Sie CB_AGENT_BASE_URL, um ein anderes Backend anzusteuern.

👩💻 Mitwirken

Beiträge sind willkommen! Um einen Fehler zu melden, eine Funktion anzufordern oder Verbesserungen beizutragen, öffnen Sie ein GitHub-Issue.

Weitere Informationen zur Entwicklereinrichtung finden Sie in CONTRIBUTING.md (Umgebung mit uv, Linting/Formatierung mit Ruff, Pre-Commit-Hooks und Projektstruktur).

# 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

📢 Support-Richtlinie

Wir freuen uns über Ihr Interesse an diesem Projekt! Es wird von der Couchbase-Community gepflegt, was bedeutet, dass es von unserem Support-Team nicht offiziell unterstützt wird. Unsere Ingenieure überwachen und pflegen dieses Repository und werden sich nach besten Kräften bemühen, Probleme zu lösen. Bitte stellen Sie alle Anfragen über GitHub.