MCP Server for Milvus

MCP-Server für Milvus

Das Model Context Protocol (MCP) ist ein offenes Protokoll, das die nahtlose Integration zwischen LLM-Anwendungen und externen Datenquellen und Tools ermöglicht. Ob Sie eine KI-gestützte IDE erstellen, eine Chat-Oberfläche optimieren oder benutzerdefinierte KI-Workflows erstellen – MCP bietet eine standardisierte Möglichkeit, LLMs mit dem benötigten Kontext zu verbinden.

Dieses Repository enthält einen MCP-Server, der Zugriff auf die Vektordatenbankfunktionalität von Milvus bietet.

Voraussetzungen

Stellen Sie vor der Verwendung dieses MCP-Servers sicher, dass Sie über Folgendes verfügen:

• Python 3.10 oder höher
• Eine laufende Milvus- Instanz (lokal oder remote)
• UV installiert (empfohlen zum Ausführen des Servers)

Verwendung

Die empfohlene Vorgehensweise zur Verwendung dieses MCP-Servers besteht darin, ihn direkt mit uv ohne Installation auszuführen. So sind sowohl Claude Desktop als auch Cursor in den folgenden Beispielen für die Verwendung konfiguriert.

Wenn Sie das Repository klonen möchten:

Anschließend können Sie den Server direkt ausführen:

Alternativ können Sie die .env-Datei im Verzeichnis src/mcp_server_milvus/ ändern, um die Umgebungsvariablen festzulegen und den Server mit dem folgenden Befehl auszuführen:

Wichtig: Die .env-Datei hat eine höhere Priorität als die Befehlszeilenargumente.

Laufmodi

Der Server unterstützt zwei Ausführungsmodi: stdio (Standard) und SSE (Server-Sent Events).

Stdio-Modus (Standard)

• Beschreibung : Kommuniziert mit dem Client über die Standard-Ein-/Ausgabe. Dies ist der Standardmodus, wenn kein Modus angegeben ist.
• Verwendung:
  uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

SSE-Modus

• Beschreibung : Verwendet HTTP Server-Sent Events zur Kommunikation. Dieser Modus ermöglicht die Verbindung mehrerer Clients über HTTP und eignet sich für webbasierte Anwendungen.
• Verwendung:
  uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
  • --sse : Aktiviert den SSE-Modus.
  • --port : Gibt den Port für den SSE-Server an (Standard: 8000).
• Debuggen im SSE-Modus:Wenn Sie im SSE-Modus debuggen möchten, geben Sie nach dem Starten des SSE-Dienstes den folgenden Befehl ein:
  mcp dev src/mcp_server_milvus/server.py
  Die Ausgabe sieht ungefähr so aus:
  % mcp dev src/mcp_server_milvus/merged_server.py Starting MCP inspector... ⚙️ Proxy server listening on port 6277 🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
  Anschließend können Sie zum Testen auf den MCP Inspector unter http://127.0.0.1:6274 zugreifen.

Unterstützte Anwendungen

Dieser MCP-Server kann mit verschiedenen LLM-Anwendungen verwendet werden, die das Model Context Protocol unterstützen:

• Claude Desktop : Anthropics Desktop-Anwendung für Claude
• Cursor : KI-gestützter Code-Editor mit MCP-Unterstützung
• Benutzerdefinierte MCP-Clients : Jede Anwendung, die die MCP-Client-Spezifikation implementiert

Verwendung mit Claude Desktop

Konfiguration für verschiedene Modi

SSE-Modus-Konfiguration

Befolgen Sie diese Schritte, um Claude Desktop für den SSE-Modus zu konfigurieren:

1. Installieren Sie Claude Desktop von https://claude.ai/download .
2. Öffnen Sie Ihre Claude Desktop-Konfigurationsdatei:
   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
3. Fügen Sie die folgende Konfiguration für den SSE-Modus hinzu:

4. Starten Sie Claude Desktop neu, um die Änderungen zu übernehmen.

Stdio-Modus-Konfiguration

Führen Sie für den Standardmodus die folgenden Schritte aus:

1. Installieren Sie Claude Desktop von https://claude.ai/download .
2. Öffnen Sie Ihre Claude Desktop-Konfigurationsdatei:
   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
3. Fügen Sie die folgende Konfiguration für den Standardmodus hinzu:

4. Starten Sie Claude Desktop neu, um die Änderungen zu übernehmen.

Verwendung mit Cursor

Cursor unterstützt auch MCP- Tools. Sie können Ihren Milvus MCP-Server mit Cursor integrieren, indem Sie die folgenden Schritte ausführen:

Integrationsschritte

1. Öffnen Sie Cursor Settings > MCP
2. Klicken Sie auf Add new global MCP server
3. Nach dem Klicken werden Sie automatisch zur Datei mcp.json weitergeleitet, die erstellt wird, falls sie nicht vorhanden ist

Konfigurieren der Datei mcp.json

Für den Stdio-Modus:

Überschreiben Sie die Datei mcp.json mit folgendem Inhalt:

Für den SSE-Modus:

1. Starten Sie den Dienst, indem Sie den folgenden Befehl ausführen:
   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port

   Hinweis : Ersetzen Sie http://your_sse_host durch Ihre tatsächliche SSE-Hostadresse und port durch die spezifische Portnummer, die Sie verwenden.

2. Sobald der Dienst läuft, überschreiben Sie die Datei mcp.json mit dem folgenden Inhalt:
   { "mcpServers": { "milvus-sse": { "url": "http://your_sse_host:port/sse", "disabled": false, "autoApprove": [] } } }

Abschließen der Integration

Starten Sie Cursor nach Abschluss der obigen Schritte neu oder laden Sie das Fenster neu, um sicherzustellen, dass die Konfiguration wirksam wird.

Überprüfen der Integration

So überprüfen Sie, ob Cursor erfolgreich in Ihren Milvus MCP-Server integriert wurde:

1. Öffnen Sie Cursor Settings > MCP
2. Überprüfen Sie, ob „milvus“ oder „milvus-sse“ in der Liste erscheint (je nach gewähltem Modus).
3. Bestätigen Sie, dass die relevanten Tools aufgelistet sind (z. B. milvus_list_collections, milvus_vector_search usw.).
4. Wenn der Server aktiviert ist, aber einen Fehler anzeigt, lesen Sie den Abschnitt zur Fehlerbehebung weiter unten.

Verfügbare Tools

Der Server stellt die folgenden Tools bereit:

Such- und Abfragevorgänge

• milvus_text_search : Suche nach Dokumenten mit der Volltextsuche
  • Parameter:
    • collection_name : Name der zu durchsuchenden Sammlung
    • query_text : Zu suchender Text
    • limit : Die maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5)
    • output_fields : In die Ergebnisse einzuschließende Felder
    • drop_ratio : Anteil der zu ignorierenden Begriffe mit niedriger Frequenz (0,0–1,0)
• milvus_vector_search : Führen Sie eine Vektorähnlichkeitssuche für eine Sammlung durch
  • Parameter:
    • collection_name : Name der zu durchsuchenden Sammlung
    • vector : Abfragevektor
    • vector_field : Feldname für die Vektorsuche (Standard: „Vektor“)
    • limit : Die maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5)
    • output_fields : In die Ergebnisse einzuschließende Felder
    • filter_expr : Filterausdruck
    • metric_type : Distanzmetrik (COSINE, L2, IP) (Standard: „COSINE“)
• milvus_hybrid_search : Führen Sie eine Hybridsuche in einer Sammlung durch
  • Parameter:
    • collection_name : Name der zu durchsuchenden Sammlung
    • query_text : Textabfrage für die Suche
    • text_field : Feldname für die Textsuche
    • vector : Vektor der Textabfrage
    • vector_field : Feldname für die Vektorsuche
    • limit : Die maximale Anzahl der zurückzugebenden Ergebnisse
    • output_fields : In die Ergebnisse einzuschließende Felder
    • filter_expr : Filterausdruck
• milvus_query : Abfragesammlung mit Filterausdrücken
  • Parameter:
    • collection_name : Name der abzufragenden Sammlung
    • filter_expr : Filterausdruck (zB „Alter > 20“)
    • output_fields : In die Ergebnisse einzuschließende Felder
    • limit : Die maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 10)

Sammlungsverwaltung

• milvus_list_collections : Listet alle Sammlungen in der Datenbank auf
• milvus_create_collection : Erstellen Sie eine neue Sammlung mit dem angegebenen Schema
  • Parameter:
    • collection_name : Name für die neue Sammlung
    • collection_schema : Definition des Sammlungsschemas
    • index_params : Optionale Indexparameter
• milvus_load_collection : Lädt eine Sammlung für Suche und Abfrage in den Speicher
  • Parameter:
    • collection_name : Name der zu ladenden Sammlung
    • replica_number : Anzahl der Replikate (Standard: 1)
• milvus_release_collection : Gibt eine Sammlung aus dem Speicher frei
  • Parameter:
    • collection_name : Name der freizugebenden Sammlung
• milvus_get_collection_info : Listet detaillierte Informationen wie Schema, Eigenschaften, Sammlungs-ID und andere Metadaten einer bestimmten Sammlung auf.
  • Parameter:
    • collection_name : Name der Sammlung, über die detaillierte Informationen abgerufen werden sollen

Datenoperationen

• milvus_insert_data : Daten in eine Sammlung einfügen
  • Parameter:
    • collection_name : Name der Sammlung
    • data : Wörterbuch, das Feldnamen Wertelisten zuordnet
• milvus_delete_entities : Löscht Entitäten aus einer Sammlung basierend auf einem Filterausdruck
  • Parameter:
    • collection_name : Name der Sammlung
    • filter_expr : Filterausdruck zum Auswählen zu löschender Entitäten

Umgebungsvariablen

• MILVUS_URI : Milvus-Server-URI (kann anstelle von --milvus-uri festgelegt werden)
• MILVUS_TOKEN : Optionales Authentifizierungstoken
• MILVUS_DB : Datenbankname (standardmäßig „default“)

Entwicklung

So führen Sie den Server direkt aus:

Beispiele

Verwenden von Claude Desktop

Beispiel 1: Auflisten von Sammlungen

Claude wird dann MCP verwenden, um diese Informationen in Ihrer Milvus-Datenbank zu überprüfen.

Beispiel 2: Suche nach Dokumenten

Claude wird die Volltextsuchfunktionen von Milvus nutzen, um relevante Dokumente zu finden:

Verwenden des Cursors

Beispiel: Erstellen einer Sammlung

Im Cursor können Sie fragen:

Cursor verwendet den MCP-Server, um diesen Vorgang auszuführen:

Fehlerbehebung

Häufige Probleme

Verbindungsfehler

Wenn Sie Fehler wie „Verbindung zum Milvus-Server fehlgeschlagen“ sehen:

1. Überprüfen Sie, ob Ihre Milvus-Instanz ausgeführt wird: docker ps (bei Verwendung von Docker)
2. Überprüfen Sie, ob die URI in Ihrer Konfiguration korrekt ist
3. Stellen Sie sicher, dass keine Firewall-Regeln die Verbindung blockieren
4. Versuchen Sie, 127.0.0.1 anstelle von localhost in der URI zu verwenden

Authentifizierungsprobleme

Wenn Authentifizierungsfehler auftreten:

1. Überprüfen Sie, ob Ihr MILVUS_TOKEN korrekt ist
2. Überprüfen Sie, ob Ihre Milvus-Instanz eine Authentifizierung erfordert
3. Stellen Sie sicher, dass Sie über die richtigen Berechtigungen für die Vorgänge verfügen, die Sie ausführen möchten

Werkzeug nicht gefunden

Wenn die MCP-Tools nicht in Claude Desktop oder Cursor angezeigt werden:

1. Starten Sie die Anwendung neu
2. Überprüfen Sie die Serverprotokolle auf Fehler
3. Überprüfen Sie, ob der MCP-Server ordnungsgemäß ausgeführt wird
4. Drücken Sie die Schaltfläche „Aktualisieren“ in den MCP-Einstellungen (für Cursor).

Hilfe bekommen

Wenn weiterhin Probleme auftreten:

1. Überprüfen Sie die GitHub-Probleme auf ähnliche Probleme
2. Treten Sie dem Zilliz Community Discord bei, um Unterstützung zu erhalten
3. Melden Sie ein neues Problem mit detaillierten Informationen zu Ihrem Problem