Doris MCP Server

Doris MCP Server

Der Doris MCP (Model Control Panel) Server ist ein Backend-Dienst, der mit Python und FastAPI erstellt wurde. Er implementiert das MCP (Model Control Panel)-Protokoll und ermöglicht Clients die Interaktion mit ihm über definierte „Tools“. Er ist primär für die Verbindung mit Apache Doris-Datenbanken konzipiert und nutzt Large Language Models (LLMs) für Aufgaben wie die Konvertierung von Abfragen in natürlicher Sprache in SQL (NL2SQL), die Ausführung von Abfragen sowie die Verwaltung und Analyse von Metadaten.

Kernfunktionen

• MCP-Protokollimplementierung : Bietet standardmäßige MCP-Schnittstellen, unterstützt Tool-Aufrufe, Ressourcenverwaltung und schnelle Interaktionen.
• Mehrere Kommunikationsmodi :
  • SSE (Server-Sent Events) : Wird über die Endpunkte /sse (Initialisierung) und /mcp/messages (Kommunikation) bereitgestellt ( src/sse_server.py ).
  • Streamable HTTP : Wird über den einheitlichen /mcp -Endpunkt bereitgestellt und unterstützt Anforderung/Antwort und Streaming ( src/streamable_server.py ).
  • (Optional) Stdio : Interaktion über Standard-Eingabe/Ausgabe ( src/stdio_server.py ) möglich, erfordert spezielle Startkonfiguration.
• Toolbasierte Schnittstelle : Kernfunktionen sind als MCP-Tools gekapselt, die Clients bei Bedarf aufrufen können. Die aktuell verfügbaren Schlüsseltools konzentrieren sich auf die direkte Datenbankinteraktion:
  • SQL-Ausführung ( mcp_doris_exec_query )
  • Datenbank- und Tabellenliste ( mcp_doris_get_db_list , mcp_doris_get_db_table_list )
  • Metadatenabruf ( mcp_doris_get_table_schema , mcp_doris_get_table_comment , mcp_doris_get_table_column_comments , mcp_doris_get_table_indexes )
  • Abrufen von Prüfprotokollen ( mcp_doris_get_recent_audit_logs ) Hinweis: Aktuelle Tools konzentrieren sich hauptsächlich auf direkte DB-Operationen.
• Datenbankinteraktion : Bietet Funktionen zum Herstellen einer Verbindung mit Apache Doris (oder anderen kompatiblen Datenbanken) und Ausführen von Abfragen ( src/utils/db.py ).
• Flexible Konfiguration : Konfiguriert über eine .env Datei, unterstützt Einstellungen für Datenbankverbindungen, LLM-Anbieter/-Modelle, API-Schlüssel, Protokollierungsebenen usw.
• Metadatenextraktion : Kann Metadateninformationen aus Datenbanken extrahieren ( src/utils/schema_extractor.py ).

Systemanforderungen

• Python 3.12+
• Datenbankverbindungsdetails (z. B. Doris-Host, Port, Benutzer, Passwort, Datenbank)

Schnellstart

1. Klonen Sie das Repository

2. Abhängigkeiten installieren

3. Umgebungsvariablen konfigurieren

Kopieren Sie die Datei .env.example nach .env und ändern Sie die Einstellungen entsprechend Ihrer Umgebung:

Wichtige Umgebungsvariablen:

• Datenbankverbindung :
  • DB_HOST : Datenbank-Hostname
  • DB_PORT : Datenbankport (Standard 9030)
  • DB_USER : Datenbankbenutzername
  • DB_PASSWORD : Datenbankkennwort
  • DB_DATABASE : Standarddatenbankname
• Serverkonfiguration :
  • SERVER_HOST : Hostadresse, auf der der Server lauscht (Standard 0.0.0.0 )
  • SERVER_PORT : Port, auf dem der Server lauscht (Standard 3000 )
  • ALLOWED_ORIGINS : Von CORS zugelassene Ursprünge (durch Komma getrennt, * erlaubt alle)
  • MCP_ALLOW_CREDENTIALS : Ob CORS-Anmeldeinformationen zugelassen werden sollen (Standard: false )
• Protokollierungskonfiguration :
  • LOG_DIR : Verzeichnis für Protokolldateien (Standard ./logs )
  • LOG_LEVEL : Protokollebene (z. B. INFO , DEBUG , WARNING , ERROR , Standard INFO )
  • CONSOLE_LOGGING : Ob Protokolle an die Konsole ausgegeben werden sollen (Standard: false )

Verfügbare MCP-Tools

In der folgenden Tabelle sind die wichtigsten Tools aufgeführt, die derzeit über einen MCP-Client aufgerufen werden können:

Hinweis: Alle Tools benötigen einen random_string Parameter als Aufrufkennung, der normalerweise automatisch vom MCP-Client verarbeitet wird. „Optional“ und „Erforderlich“ beziehen sich auf die interne Logik des Tools; der Client muss je nach Implementierung möglicherweise Werte für alle Parameter angeben. Die hier aufgeführten Toolnamen sind die Basisnamen; Clients können sie je nach Verbindungsmodus mit einem Präfix versehen sehen (z. B. mcp_doris_stdio3_get_db_list ).

4. Führen Sie den Dienst aus

Wenn Sie den SSE-Modus verwenden, führen Sie den folgenden Befehl aus:

Dieser Befehl startet die FastAPI-Anwendung und stellt standardmäßig sowohl SSE- als auch Streamable HTTP MCP-Dienste bereit.

Service-Endpunkte:

• SSE-Initialisierung : http://<host>:<port>/sse
• SSE-Kommunikation : http://<host>:<port>/mcp/messages (POST)
• Streambares HTTP : http://<host>:<port>/mcp (Unterstützt GET, POST, DELETE, OPTIONS)
• Integritätsprüfung : http://<host>:<port>/health
• (Potenzielle) Statusprüfung : http://<host>:<port>/status (Bestätigen, ob in main.py implementiert)

Verwendung

Für die Interaktion mit dem Doris MCP-Server ist ein MCP-Client erforderlich. Der Client verbindet sich mit den SSE- oder Streamable-HTTP-Endpunkten des Servers und sendet Anfragen (wie tool_call ) gemäß der MCP-Spezifikation, um die Tools des Servers aufzurufen.

Hauptinteraktionsfluss:

1. Client-Initialisierung : Stellen Sie eine Verbindung zu /sse (SSE) her oder senden Sie einen initialize an /mcp (Streamable).
2. (Optional) Tools entdecken : Der Client kann mcp/listTools oder mcp/listOfferings aufrufen, um die Liste der unterstützten Tools, deren Beschreibungen und Parameterschemata abzurufen.
3. Tool aufrufen : Der Client sendet eine tool_call -Nachricht/Anforderung und gibt dabei den tool_name und arguments an.
   • Beispiel: Tabellenschema abrufen
     • tool_name : mcp_doris_get_table_schema (oder der modusspezifische Name)
     • arguments : Schließen Sie random_string , table_name und db_name ein.
4. Handle-Antwort :
   • Nicht-Streaming : Der Client erhält eine Antwort mit result oder error .
   • Streaming : Der Client erhält eine Reihe von tools/progress , gefolgt von einer abschließenden Antwort mit dem result oder error .

Auf bestimmte Toolnamen und Parameter sollte im src/tools/ -Code verwiesen oder sie sollten über MCP-Erkennungsmechanismen abgerufen werden.

Verbinden mit Cursor

Sie können Cursor entweder im Stdio- oder im SSE-Modus mit diesem MCP-Server verbinden.

Stdio-Modus

Im Stdio-Modus kann Cursor den Serverprozess direkt verwalten. Die Konfiguration erfolgt in der MCP-Server-Einstellungsdatei von Cursor (normalerweise ~/.cursor/mcp.json oder ähnlich).

Wenn Sie den Stdio-Modus verwenden, führen Sie bitte den folgenden Befehl aus, um das Umgebungsabhängigkeitspaket herunterzuladen und zu erstellen. Beachten Sie jedoch, dass Sie den Projektpfad in die richtige Pfadadresse ändern müssen :

1. Cursor konfigurieren: Fügen Sie Ihrer Cursor-MCP-Konfiguration einen Eintrag wie den folgenden hinzu:
   { "mcpServers": { "doris-stdio": { "command": "uv", "args": ["--project", "/path/to/your/doris-mcp-server", "run", "doris-mcp"], "env": { "DB_HOST": "127.0.0.1", "DB_PORT": "9030", "DB_USER": "root", "DB_PASSWORD": "your_db_password", "DB_DATABASE": "your_default_db" } }, // ... other server configurations ... } }
2. Wichtige Punkte:
   • Ersetzen Sie /path/to/your/doris-mcp durch den tatsächlichen absoluten Pfad zum Stammverzeichnis des Projekts auf Ihrem System. Das Argument --project ist entscheidend, damit uv die pyproject.toml findet und den richtigen Befehl ausführt.
   • Der command ist auf uv eingestellt (vorausgesetzt, Sie verwenden uv für die Paketverwaltung, wie in uv.lock angegeben). Die args umfassen --project , den Pfad, run und mcp-doris (was einem in Ihrer pyproject.toml definierten Skript entsprechen sollte).
   • Die Datenbankverbindungsdaten ( DB_HOST , DB_PORT , DB_USER , DB_PASSWORD , DB_DATABASE ) werden direkt im env Block der Konfigurationsdatei festgelegt. Cursor leitet diese an den Serverprozess weiter. Bei der Konfiguration über Cursor ist für diesen Modus keine .env Datei erforderlich.

SSE-Modus

Im SSE-Modus müssen Sie den MCP-Server zunächst unabhängig ausführen und Cursor dann mitteilen, wie eine Verbindung zu ihm hergestellt werden soll.

1. Konfigurieren Sie .env : Stellen Sie sicher, dass Ihre Datenbankanmeldeinformationen und alle anderen erforderlichen Einstellungen (wie SERVER_PORT , wenn Sie nicht den Standardwert 3000 verwenden) in der .env Datei im Projektverzeichnis richtig konfiguriert sind.
2. Starten Sie den Server: Führen Sie den Server von Ihrem Terminal im Stammverzeichnis des Projekts aus:
   ./start_server.sh
   Dieses Skript liest typischerweise die .env Datei und startet den FastAPI-Server im SSE-Modus (siehe das Skript und sse_server.py / main.py für weitere Einzelheiten). Beachten Sie den Host und den Port, auf dem der Server lauscht (Standard ist 0.0.0.0:3000 ).
3. Cursor konfigurieren: Fügen Sie Ihrer Cursor-MCP-Konfiguration einen Eintrag wie den folgenden hinzu, der auf den SSE-Endpunkt des laufenden Servers verweist:
   { "mcpServers": { "doris-sse": { "url": "http://127.0.0.1:3000/sse" // Adjust host/port if your server runs elsewhere }, // ... other server configurations ... } }
   Hinweis: Im Beispiel wird der Standardport 3000 verwendet. Wenn Ihr Server auf einem anderen Port (z. B. 3010 im Beispiel) läuft, passen Sie die URL entsprechend an.

Nachdem Sie einen der Modi in Cursor konfiguriert haben, sollten Sie in der Lage sein, den Server (z. B. doris-stdio oder doris-sse ) auszuwählen und seine Tools zu verwenden.

Verzeichnisstruktur

Entwicklung neuer Tools

In diesem Abschnitt wird der Prozess zum Hinzufügen neuer MCP-Tools zum Doris MCP-Server unter Berücksichtigung der aktuellen Projektstruktur beschrieben.

1. Nutzen Sie Dienstprogrammmodule

Bevor Sie eine neue Datenbankinteraktionslogik von Grund auf neu schreiben, überprüfen Sie die vorhandenen Dienstprogrammmodule:

• doris_mcp_server/utils/db.py : Bietet grundlegende Funktionen zum Abrufen von Datenbankverbindungen ( get_db_connection ) und Ausführen von Rohabfragen ( execute_query , execute_query_df ).
• doris_mcp_server/utils/schema_extractor.py ( MetadataExtractor -Klasse) : Bietet hochrangige Methoden zum Abrufen von Datenbankmetadaten, z. B. zum Auflisten von Datenbanken/Tabellen ( get_all_databases , get_database_tables ), zum Abrufen von Tabellenschemata/Kommentaren/Indizes ( get_table_schema , get_table_comment , get_column_comments , get_table_indexes ) und zum Zugriff auf Audit-Protokolle ( get_recent_audit_logs ). Enthält Caching-Mechanismen.
• doris_mcp_server/utils/sql_executor_tools.py (Funktion execute_sql_query ) : Bietet einen Wrapper für db.execute_query , der Sicherheitsprüfungen enthält (optional, gesteuert durch die Umgebungsvariable ENABLE_SQL_SECURITY_CHECK ), SELECT-Abfragen automatisch LIMIT hinzufügt, die Ergebnisserialisierung (Datum, Dezimalzahlen) übernimmt und die Ausgabe in die standardmäßige MCP-Erfolgs-/Fehlerstruktur formatiert. Es wird empfohlen, dies für die Ausführung von benutzerdefiniertem oder generiertem SQL zu verwenden.

Sie können Funktionen aus diesen Modulen importieren und kombinieren, um Ihr neues Tool zu erstellen.

2. Tool-Logik implementieren

Implementieren Sie die Kernlogik Ihres neuen Tools als async Funktion in doris_mcp_server/tools/mcp_doris_tools.py . Dadurch bleiben die primären Toolimplementierungen zentralisiert. Stellen Sie sicher, dass Ihre Funktion Daten in einem Format zurückgibt, das sich problemlos in die Standard-MCP-Antwortstruktur integrieren lässt (siehe _format_response in derselben Datei als Referenz).

Beispiel: Erstellen wir ein einfaches Tool get_server_time .

3. Registrieren Sie das Tool (Doppelregistrierung)

Aufgrund der separaten Handhabung der Modi SSE/Streamable und Stdio müssen Sie das Tool an zwei Stellen registrieren:

A. SSE/Streamable-Registrierung ( tool_initializer.py )

• Importieren Sie Ihre neue Tool-Funktion aus mcp_doris_tools.py .
• Fügen Sie innerhalb der Funktion register_mcp_tools eine neue Wrapper-Funktion hinzu, die mit @mcp.tool() dekoriert ist.
• Die Wrapper-Funktion sollte Ihre Kerntoolfunktion aufrufen.
• Definieren Sie den Werkzeugnamen und geben Sie im Dekorator eine ausführliche Beschreibung (einschließlich Parameter, falls vorhanden) an. Denken Sie daran, die obligatorische Parameterbeschreibung random_string aus Gründen der Clientkompatibilität einzuschließen, auch wenn Ihr Wrapper diese nicht explizit verwendet.

Beispiel ( tool_initializer.py ):

B. Stdio-Registrierung ( mcp_core.py )

• Fügen Sie ähnlich wie bei SSE eine neue Wrapper-Funktion hinzu, die mit @stdio_mcp.tool() dekoriert ist.
• Wichtig: Importieren Sie Ihre Kerntoolfunktion ( mcp_doris_get_server_time ) in die Wrapper-Funktion (in dieser Datei wird ein verzögertes Importmuster verwendet).
• Der Wrapper ruft die Kernfunktion des Tools auf. Der Wrapper selbst muss möglicherweise async def sein, abhängig davon, wie FastMCP Tools im Stdio-Modus verarbeitet, selbst wenn die zugrunde liegende Funktion einfach ist (siehe aktuelle Dateistruktur). Stellen Sie sicher, dass der Aufruf übereinstimmt (z. B. verwenden Sie await wenn eine asynchrone Funktion aufgerufen wird).

Beispiel ( mcp_core.py ):

4. Neustart und Test

Nachdem Sie das Tool in beiden Dateien implementiert und registriert haben, starten Sie den MCP-Server neu (sowohl im SSE-Modus über ./start_server.sh als auch stellen Sie sicher, dass der von Cursor verwendete Stdio-Befehl bei Bedarf aktualisiert wird) und testen Sie das neue Tool mit Ihrem MCP-Client (wie Cursor) in beiden Verbindungsmodi.

Beitragen

Beiträge sind über Issues oder Pull Requests willkommen.

Lizenz

Dieses Projekt ist unter der Apache 2.0-Lizenz lizenziert. Weitere Informationen finden Sie in der Datei LICENSE (sofern vorhanden).