StarRocks

StarRocks Offizieller MCP-Server

Der StarRocks MCP-Server fungiert als Brücke zwischen KI-Assistenten und StarRocks-Datenbanken. Er ermöglicht die direkte SQL-Ausführung, Datenbankerkundung, Datenvisualisierung über Diagramme sowie das Abrufen detaillierter Schema-/Datenübersichten, ohne dass eine komplexe clientseitige Einrichtung erforderlich ist.

Funktionen

• Direkte SQL-Ausführung: Führen Sie SELECT-Abfragen (read_query) und DDL/DML-Befehle (write_query) aus.
• Datenbankerkundung: Listen Sie Datenbanken und Tabellen auf, rufen Sie Tabellenschemas ab (starrocks://-Ressourcen).
• Systeminformationen: Zugriff auf interne StarRocks-Metriken und -Zustände über den proc://-Ressourcenpfad.
• Detaillierte Übersichten: Erhalten Sie umfassende Zusammenfassungen von Tabellen (table_overview) oder ganzen Datenbanken (db_overview), einschließlich Spaltendefinitionen, Zeilenanzahlen und Beispieldaten.
• Datenvisualisierung: Führen Sie eine Abfrage aus und generieren Sie direkt aus den Ergebnissen ein Plotly-Diagramm (query_and_plotly_chart).
• Intelligentes Caching: Tabellen- und Datenbankübersichten werden im Speicher zwischengespeichert, um wiederholte Anfragen zu beschleunigen. Der Cache kann bei Bedarf umgangen werden.
• Flexible Konfiguration: Legen Sie Verbindungsdetails und Verhalten über Umgebungsvariablen fest.

Voraussetzungen

• Python 3.11 oder neuer.
• Ein erreichbarer StarRocks-Cluster (FE-Dienst). Standardmäßig verbindet sich der Server über das MySQL-Protokoll mit localhost:9030.
• uv — ein schnelles Python-Paket und Projektmanager (ein moderner Ersatz für pip + virtualenv) von Astral. Dieses Projekt verwendet uv, um Abhängigkeiten aufzulösen, die virtuelle Umgebung zu erstellen und den Server zu starten. Die uv run-Befehle in dieser README erstellen bei der ersten Verwendung automatisch eine isolierte Umgebung und installieren die erforderlichen Abhängigkeiten, sodass kein manueller pip install-Schritt erforderlich ist.

Installieren von uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via Homebrew / pipx / pip
brew install uv
# pipx install uv
# pip install uv

Weitere Optionen finden Sie in der offiziellen uv-Installationsanleitung. Überprüfen Sie nach der Installation, ob es sich in Ihrem PATH befindet:

uv --version

Installation

Sie müssen das Paket im Allgemeinen nicht manuell installieren — der MCP-Host startet es für Sie über uv (siehe Konfiguration unten). uv ruft das Paket und seine Abhängigkeiten bei Bedarf ab.

Um es direkt für Tests oder Entwicklung auszuführen:

# Run the published package in a throwaway environment
uv run --with mcp-server-starrocks mcp-server-starrocks --help

# Or, from a local checkout of this repository
git clone https://github.com/starrocks/mcp-server-starrocks.git
cd mcp-server-starrocks
uv sync                      # create the virtual environment and install dependencies
uv run mcp-server-starrocks --help

Konfiguration

Der MCP-Server wird normalerweise über einen MCP-Host ausgeführt. Die Konfiguration wird an den Host übergeben und legt fest, wie der StarRocks-MCP-Serverprozess gestartet wird.

Verwendung von Streamable HTTP (empfohlen):

Um den Server im Streamable-HTTP-Modus zu starten:

Testen Sie zuerst, ob die Verbindung zu StarRocks in Ordnung ist (9030 ist der StarRocks-MySQL-Protokollport, nicht der HTTP-Serverport):

$ STARROCKS_URL=root:@localhost:9030 uv run mcp-server-starrocks --test

Starten Sie den Server:

uv run mcp-server-starrocks --mode streamable-http --port 8000

Konfigurieren Sie dann den MCP wie folgt:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Verwendung von Docker:

Erstellen Sie das Image:

docker build -t mcp-server-starrocks:local .

Erstellen und pushen Sie ein versioniertes Image:

docker build -t <registry>/<namespace>/mcp-starrocks:0.4.0 .
docker push <registry>/<namespace>/mcp-starrocks:0.4.0

Starten Sie den Server im Streamable-HTTP-Modus:

docker run --rm -p 8000:8000 \
  -e STARROCKS_HOST=host.docker.internal \
  -e STARROCKS_PORT=9030 \
  -e STARROCKS_USER=root \
  -e STARROCKS_PASSWORD='' \
  mcp-server-starrocks:local

Konfigurieren Sie dann den MCP-Client mit:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Verwendung von uv mit installiertem Paket (einzelne Umgebungsvariablen):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

Verwendung von uv mit installiertem Paket (Verbindungs-URL):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Verwendung von uv mit lokalem Verzeichnis (für Entwicklung):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

Verwendung von uv mit lokalem Verzeichnis und Verbindungs-URL:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Befehlszeilenargumente:

Der Server unterstützt die folgenden Befehlszeilenargumente:

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http}: Transportmodus (Standard: stdio oder MCP_TRANSPORT_MODE-Umgebungsvariable)
• --host HOST: Server-Host für HTTP-Modi (Standard: localhost)
• --port PORT: Server-Port für HTTP-Modi
• --test: Im Testmodus ausführen, um die Funktionalität zu überprüfen

Beispiele:

# Start in streamable HTTP mode on custom host/port
uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080

# Start in stdio mode (default)
uv run mcp-server-starrocks --mode stdio

# Run test mode
uv run mcp-server-starrocks --test

• Das url-Feld sollte auf den Streamable-HTTP-Endpunkt Ihres MCP-Servers zeigen (Host/Port nach Bedarf anpassen).
• Mit dieser Konfiguration können Clients über Standard-JSON über HTTP-POST-Anfragen mit dem Server interagieren. Kein spezielles SDK erforderlich.
• Alle Tool-APIs akzeptieren und geben Standard-JSON wie oben beschrieben zurück.

Hinweis: Der sse-Modus (Server-Sent Events) ist veraltet und wird nicht mehr gewartet. Verwenden Sie für alle neuen Integrationen den Streamable-HTTP-Modus.

Umgebungsvariablen:

Verbindungskonfiguration

Sie können die StarRocks-Verbindung entweder über einzelne Umgebungsvariablen oder eine einzelne Verbindungs-URL konfigurieren:

Option 1: Einzelne Umgebungsvariablen

• STARROCKS_HOST: (Optional) Hostname oder IP-Adresse des StarRocks-FE-Dienstes. Standard: localhost.
• STARROCKS_PORT: (Optional) MySQL-Protokollport des StarRocks-FE-Dienstes. Standard: 9030.
• STARROCKS_USER: (Optional) StarRocks-Benutzername. Standard: root.
• STARROCKS_PASSWORD: (Optional) StarRocks-Passwort. Standard: leere Zeichenfolge.
• STARROCKS_PASSWORD_FILE: (Optional) Pfad zu einer UTF-8-Textdatei, die das Passwort enthält. Dies ist nützlich bei dateibasierter Geheimnisinjektion wie systemd-Anmeldeinformationen. Ein abschließender Zeilenumbruch wird ignoriert. Dies wird nur verwendet, wenn kein explizites Passwort über STARROCKS_PASSWORD oder STARROCKS_URL bereitgestellt wird.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Optional, nur macOS) Generischer Passwortdienstname, der beim Lesen des Passworts aus dem Schlüsselbund verwendet wird. Dies wird nur verwendet, wenn kein explizites Passwort oder STARROCKS_PASSWORD_FILE konfiguriert ist.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Optional, nur macOS) Generischer Passwortkontoname, der beim Lesen des Passworts aus dem Schlüsselbund verwendet wird. Standard: der aufgelöste StarRocks-Benutzer.
• STARROCKS_DB: (Optional) Standarddatenbank, die verwendet wird, wenn sie nicht in Tool-Argumenten oder Ressourcen-URIs angegeben ist. Wenn gesetzt, versucht die Verbindung, diese Datenbank zu USE. Tools wie table_overview und db_overview verwenden diese, wenn der Datenbankteil in ihren Argumenten weggelassen wird. Standard: leer (keine Standarddatenbank).
• STARROCKS_QUERY_TIMEOUT: (Optional) Anzahl der Sekunden, die auf die Ergebnisse einer Abfrage gewartet wird, bevor aufgegeben wird, als Ganzzahl. Standardmäßig nicht gesetzt, was unbegrenzt wartet und dem bisherigen Verhalten entspricht. Setzen Sie dies, wenn eine hängende oder langlaufende Abfrage fehlschlagen soll, anstatt einen Tool-Aufruf für immer zu blockieren.

Option 2: Verbindungs-URL (hat Vorrang vor einzelnen Variablen)

• STARROCKS_URL: (Optional) Eine Verbindungs-URL-Zeichenfolge, die alle Verbindungsparameter in einer einzigen Variablen enthält. Format: [<schema>://]user:password@host:port/database. Der Schema-Teil ist optional. Wenn diese Variable gesetzt ist, hat sie Vorrang vor den einzelnen STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD- und STARROCKS_DB-Variablen.

  Beispiele:

  • root:mypass@localhost:9030/test_db
  • mysql://admin:secret@db.example.com:9030/production
  • starrocks://user:pass@192.168.1.100:9030/analytics

Passwort-Priorität:

• Ein in STARROCKS_URL eingebettetes Passwort gewinnt, einschließlich eines expliziten leeren Passworts wie user:@host:9030/db.
• Wenn STARROCKS_URL das Passwort weglässt, wird STARROCKS_PASSWORD verwendet, wenn gesetzt.
• Wenn keine explizite Passwortquelle gesetzt ist und STARROCKS_PASSWORD_FILE konfiguriert ist, wird das Passwort aus dieser Datei gelesen.
• Wenn kein explizites Passwort oder keine Passwortdatei konfiguriert ist und STARROCKS_PASSWORD_KEYCHAIN_SERVICE gesetzt ist, wird das Passwort aus dem macOS-Schlüsselbund gelesen.

macOS-Schlüsselbund-Beispiel

Speichern Sie das Passwort:

security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'

Überprüfen Sie das gespeicherte Passwort:

security find-generic-password -a root -s mcp-server-starrocks -w

Verwenden Sie es mit diesem Server:

export STARROCKS_URL=root@localhost:9030/test_db
export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=root

systemd-verschlüsselte Anmeldeinformationen-Beispiel (systemd 250 oder später)

Der Server ruft systemd-creds nicht selbst auf. Bei der Bereitstellung verschlüsselt ein Administrator das Passwort; beim Dienststart entschlüsselt systemd es in das Anmeldeinformationsverzeichnis des Dienstes und legt dem Server nur den Dateipfad offen.

Erstellen Sie eine hostgebundene verschlüsselte Anmeldeinformation, ohne das Passwort in den Shell-Verlauf zu schreiben:

sudo -v
sudo install -d -m 0700 /etc/credstore.encrypted
sudo systemd-ask-password -n "StarRocks password:" \
  | sudo systemd-creds encrypt \
      --name=starrocks-password \
      - /etc/credstore.encrypted/starrocks-password.cred

Fügen Sie die Anmeldeinformation zur Dienst-Einheit hinzu. Der %d-Spezifizierer erweitert sich zum dienstspezifischen Anmeldeinformationsverzeichnis:

[Service]
LoadCredentialEncrypted=starrocks-password:/etc/credstore.encrypted/starrocks-password.cred
Environment=STARROCKS_PASSWORD_FILE=%d/starrocks-password
PrivateMounts=yes

Lassen Sie STARROCKS_PASSWORD ungesetzt und lassen Sie das Passwort aus STARROCKS_URL weg, laden Sie dann die Einheit neu und starten Sie den Dienst neu. Die verschlüsselte Anmeldeinformation ist normalerweise an den lokalen Host gebunden (und an sein TPM2-Gerät, falls verfügbar); sie wird nur entschlüsselt, während der Dienst aktiviert wird. Der Dienstprozess und Administratoren mit Root-Rechten können das Klartext-Passwort zur Laufzeit weiterhin lesen. Verwenden Sie nicht systemd-creds encrypt --with-key=null, da dies keine Vertraulichkeit bietet.

Zusätzliche Konfiguration

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Optional) Arrow-Flight-SQL-Port des StarRocks-FE-Dienstes. Wenn gesetzt, verbindet sich der Server über das Hochleistungs-Arrow-Flight-SQL-Protokoll (über ADBC-Treiber) anstelle des Standard-MySQL-Protokolls. Lassen Sie es ungesetzt, um die Standard-MySQL-Verbindung zu verwenden. Host, Benutzer und Passwort werden aus denselben oben beschriebenen Verbindungseinstellungen übernommen.

• STARROCKS_OVERVIEW_LIMIT: (Optional) Ein ungefähres Zeichenlimit für den gesamten Text, der von Übersichtstools (table_overview, db_overview) generiert wird, wenn Daten zum Füllen des Caches abgerufen werden. Dies hilft, übermäßigen Speicherverbrauch bei sehr großen Schemas oder zahlreichen Tabellen zu verhindern. Standard: 20000.

• STARROCKS_MCP_OUTPUT_DIR: (Optional) Verzeichnis, das von read_query verwendet wird, wenn sein output_file-Argument ein relativer Pfad ist. Standard: ~/.mcp-server-starrocks/output/. Das Verzeichnis wird bei Bedarf erstellt. Absolute Pfade, die an output_file übergeben werden (einschließlich ~-präfixierter Pfade), umgehen diese Einstellung. Hinweis: Dateien werden auf dem Rechner geschrieben, auf dem der MCP-Server läuft. Bei Claude Code / Claude Desktop läuft der Server lokal, sodass Dateien auf Ihrem Laptop landen. Bei Remote-/HTTP-Bereitstellungen landen die Dateien auf dem Server, nicht auf dem Client.

• STARROCKS_CHART_OUTPUT_DIR: (Optional) Verzeichnis, in das query_and_plotly_chart interaktive HTML-Diagramme schreibt (wenn format="html"). Standard: das System-Temp-Verzeichnis. Das Verzeichnis wird bei Bedarf erstellt. Hinweis: Wie andere Ausgabedateien werden Diagramme auf dem Rechner geschrieben, auf dem der MCP-Server läuft.

• STARROCKS_CHART_INCLUDE_PLOTLYJS: (Optional) Steuert, wie plotly.js in HTML-Diagramme eingebettet wird. cdn (Standard) hält Dateien klein, benötigt aber Netzwerkzugriff beim Anzeigen; inline/true bettet die vollständige Bibliothek für die Offline-Nutzung ein; directory und false werden ebenfalls akzeptiert (durchgereicht an Plotlys write_html).

• STARROCKS_CHART_DEFAULT_FORMAT: (Optional) Standardausgabeformat für query_and_plotly_chart, wenn das format-Argument weggelassen wird. Eines von json, png, jpeg (Standard) oder html. Setzen Sie es auf html, um immer eine interaktive Diagrammdatei in STARROCKS_CHART_OUTPUT_DIR zu schreiben (mit einer Inline-PNG-Vorschau), ohne format bei jedem Aufruf zu übergeben. Ungültige Werte fallen mit einer Warnung auf jpeg zurück.

• STARROCKS_MYSQL_AUTH_PLUGIN: (Optional) Gibt das Authentifizierungs-Plugin an, das bei der Verbindung zum StarRocks-FE-Dienst verwendet wird. Setzen Sie es beispielsweise auf mysql_clear_password, wenn Ihre StarRocks-Bereitstellung eine Klartext-Passwortauthentifizierung erfordert (z. B. bei bestimmten LDAP- oder externen Authentifizierungseinrichtungen). Setzen Sie dies nur, wenn Ihre Umgebung es speziell erfordert; andernfalls wird das Standard-auth_plugin verwendet.

TLS / SSL-Konfiguration

Diese Variablen steuern TLS für die Verbindung. Wenn keine von ihnen gesetzt ist, behält das zugrunde liegende mysql.connector sein Standardverhalten (ssl-mode=PREFERRED): Die Verbindung wird verschlüsselt, wenn der Server TLS unterstützt, aber das Serverzertifikat wird nicht überprüft. Für echte Sicherheit stellen Sie ein CA-Zertifikat bereit und aktivieren Sie die Überprüfung.

• STARROCKS_SSL_DISABLED: (Optional) Auf true setzen, um TLS zu deaktivieren. Überschreibt alle anderen SSL-Einstellungen. Standardwert ist false.
• STARROCKS_SSL_CA: (Optional) Pfad zum CA-Zertifikat (PEM), das zur Überprüfung des StarRocks-Serverzertifikats verwendet wird.
• STARROCKS_SSL_CERT: (Optional) Pfad zum Client-Zertifikat (PEM) für gegenseitiges TLS (mTLS).
• STARROCKS_SSL_KEY: (Optional) Pfad zum privaten Clientschlüssel (PEM) für gegenseitiges TLS (mTLS).
• STARROCKS_SSL_VERIFY_CERT: (Optional) Auf true setzen, um das Serverzertifikat gegen die CA zu überprüfen. Standardwert ist false.
• STARROCKS_SSL_VERIFY_IDENTITY: (Optional) Auf true setzen, um auch zu überprüfen, dass der Server-Hostname mit dem Zertifikat übereinstimmt. Standardwert ist false.
• STARROCKS_TLS_VERSIONS: (Optional) Kommagetrennte Liste der erlaubten TLS-Versionen, z. B. TLSv1.2,TLSv1.3.

Beispiel (Server gegen ein CA-Zertifikat überprüfen):

"env": {
  "STARROCKS_HOST": "your-fe-host",
  "STARROCKS_PORT": "9030",
  "STARROCKS_USER": "root",
  "STARROCKS_PASSWORD": "your-password",
  "STARROCKS_SSL_CA": "/path/to/ca.pem",
  "STARROCKS_SSL_VERIFY_CERT": "true",
  "STARROCKS_SSL_VERIFY_IDENTITY": "true"
}

Für die Hochleistungsverbindung Arrow Flight SQL (aktiviert über STARROCKS_FE_ARROW_FLIGHT_SQL_PORT) wird TLS separat gesteuert:

• STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS: (Optional) Auf true setzen, um grpc+tls:// anstelle von Klartext grpc:// zu verwenden. Wenn aktiviert, wird STARROCKS_SSL_CA als TLS-Root-Zertifikat verwendet und STARROCKS_SSL_VERIFY_CERT=false (Standard) überspringt die Serverzertifikatsprüfung.

Sicherheitshinweis: Vermeiden Sie es, Klartext-Passwörter direkt in mcp.json zu speichern. Bevorzugen Sie die Injektion von STARROCKS_PASSWORD (und Zertifikatspfaden) aus einem Secrets-Manager oder der Umgebung, und committen Sie Anmeldedaten niemals in die Versionskontrolle.

• MCP_TRANSPORT_MODE: (Optional) Kommunikationsmodus, der angibt, wie der MCP-Server seine Dienste bereitstellt. Verfügbare Optionen:
  • stdio (Standard): Kommunikation über Standard-Eingabe/Ausgabe, geeignet für MCP-Host-Hosting.
  • streamable-http (Streamable HTTP): Startet als Streamable-HTTP-Server, unterstützt RESTful-API-Aufrufe.
  • sse: (Veraltet, nicht empfohlen) Startet im Server-Sent-Events-Streaming-Modus (SSE), geeignet für Szenarien, die Streaming-Antworten erfordern. Hinweis: Der SSE-Modus wird nicht mehr gewartet; es wird empfohlen, einheitlich den Streamable-HTTP-Modus zu verwenden.

Komponenten

Tools

• read_query

  • Beschreibung: Führt eine SELECT-Abfrage oder andere Befehle aus, die ein ResultSet zurückgeben (z. B. SHOW, DESCRIBE). Optional kann das vollständige Ergebnis in eine lokale Datei geschrieben werden, anstatt es inline zurückzugeben – nützlich für Ergebnisse, die zu groß für den Modellkontext sind.
  • Eingabe:

    {
      "query": "SQL query string",
      "db": "database name (optional, uses default database if not specified)",
      "output_file": "optional path; if set, writes the full result to disk and returns only a summary + small preview. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/); absolute paths and ~ are used as-is",
      "output_format": "optional: csv | tsv | json | jsonl. If omitted, inferred from output_file extension (.csv/.tsv/.json/.jsonl/.ndjson); defaults to csv"
    }
    

  • Ausgabe: Ohne output_file Textinhalt mit den Abfrageergebnissen im CSV-ähnlichen Format mit Kopfzeile und Zeilenanzahl-Zusammenfassung. Mit output_file eine kurze Zusammenfassung mit dem aufgelösten absoluten Pfad, der Byteanzahl und der Zeilenanzahl sowie eine kleine Vorschau. Gibt bei Fehlern eine Fehlermeldung zurück.

• write_query

  • Beschreibung: Führt einen DDL-Befehl (CREATE, ALTER, DROP), DML-Befehl (INSERT, UPDATE, DELETE) oder einen anderen StarRocks-Befehl aus, der kein ResultSet zurückgibt.
  • Eingabe:

    {
      "query": "SQL command string",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Ausgabe: Textinhalt, der den Erfolg bestätigt (z. B. „Query OK, X rows affected") oder einen Fehler meldet. Änderungen werden bei Erfolg automatisch committet.

• analyze_query

  • Beschreibung: Analysiert eine Abfrage und erhält das Analyseergebnis mithilfe des Query-Profils oder der Explain-Analyse.
  • Eingabe:

    {
      "uuid": "Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12",
      "sql": "Query SQL to analyze",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Ausgabe: Textinhalt mit den Abfrageanalyseergebnissen. Verwendet ANALYZE PROFILE FROM, wenn eine UUID angegeben ist, andernfalls EXPLAIN ANALYZE, wenn SQL angegeben ist.

• top_hot_tables

  • Beschreibung: Ruft die Top-Hot-Tabellen nach Audit-Log-Besuchszahl ab. Verknüpft information_schema.tables mit starrocks_audit_db__.starrocks_audit_tbl__, schließt root- und SHOW-Anweisungen aus, gleicht Audit-SQL-Text mit Tabellennamen ab und sortiert absteigend nach visit_count.
  • Eingabe:

    {
      "db": "optional database/schema filter",
      "table": "optional table name substring filter",
      "min_start_time_ms": 1704067200000,
      "max_start_time_ms": 1704153600000,
      "top_n": 20
    }
    

  • Ausgabe: Textzusammenfassung plus strukturierter Inhalt mit Rangzeilen, die db, table und visit_count enthalten.

• top_bad_tables

  • Beschreibung: Ruft die Top-Schlecht-Tabellen nach Tabellen-Gesundheitswert ab, gemäß der top-bad-tables-Logik von Star Management Studio. Es verwendet die Tabellen-Gesundheitsberechnung basierend auf information_schema.be_tablets und information_schema.partitions_meta, filtert System-Schemas heraus, sortiert aufsteigend nach table_health_score und gibt die Tabellen mit den niedrigsten Werten zurück.
  • Eingabe:

    {
      "db": "optional database/schema filter",
      "table": "optional table name substring filter",
      "top_n": 20
    }
    

  • Ausgabe: Textzusammenfassung plus strukturierter Inhalt mit Rangzeilen, die Tabellen-Gesundheitsfelder wie db, table, tablet_num, replica_score, tablet_score und table_health_score enthalten.

• query_and_plotly_chart

  • Beschreibung: Führt eine SQL-Abfrage aus, lädt die Ergebnisse in einen Pandas-DataFrame und generiert ein Plotly-Diagramm mithilfe eines bereitgestellten Python-Ausdrucks. Entwickelt für die Visualisierung in unterstützenden UIs.
  • Eingabe:

    {
      "query": "SQL query to fetch data",
      "plotly_expr": "Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\"col1\", y=\"col2\")'",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Ausgabe: Eine Liste mit:
    1. TextContent: Eine Textdarstellung des DataFrames und einen Hinweis, dass das Diagramm für die UI-Anzeige bestimmt ist.
    2. ImageContent: Das generierte Plotly-Diagramm, kodiert als Base64-PNG-Bild (image/png). Gibt bei Fehlern oder wenn die Abfrage keine Daten liefert, eine Textfehlermeldung zurück.

• table_overview

  • Beschreibung: Ruft eine Übersicht einer bestimmten Tabelle ab: Spalten (aus DESCRIBE), Gesamtzeilenanzahl und Beispielzeilen (LIMIT 3). Verwendet einen In-Memory-Cache, es sei denn, refresh ist wahr.
  • Eingabe:

    {
      "table": "Table name, optionally prefixed with database name (e.g., 'db_name.table_name' or 'table_name'). If database is omitted, uses STARROCKS_DB environment variable if set.",
      "refresh": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.
    }
    

  • Ausgabe: Textinhalt mit der formatierten Übersicht (Spalten, Zeilenanzahl, Beispieldaten) oder eine Fehlermeldung. Zwischengespeicherte Ergebnisse enthalten ggf. frühere Fehler.

• db_overview

  • Beschreibung: Ruft eine Übersicht (Spalten, Zeilenanzahl, Beispielzeilen) für alle Tabellen in einer bestimmten Datenbank ab. Verwendet den Tabellen-Cache für jede Tabelle, es sei denn, refresh ist wahr.
  • Eingabe:

    {
      "db": "database_name", // Optional if default database is set.
      "refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
    }
    

  • Ausgabe: Textinhalt mit verketteten Übersichten für alle in der Datenbank gefundenen Tabellen, getrennt durch Überschriften. Gibt eine Fehlermeldung zurück, wenn die Datenbank nicht zugänglich ist oder keine Tabellen enthält.

Ressourcen

Direkte Ressourcen

• starrocks:///databases
  • Beschreibung: Listet alle Datenbanken auf, die für den konfigurierten Benutzer zugänglich sind.
  • Äquivalente Abfrage: SHOW DATABASES
  • MIME-Typ: text/plain

Ressourcenvorlagen

• starrocks:///{db}/{table}/schema

  • Beschreibung: Ruft die Schema-Definition einer bestimmten Tabelle ab.
  • Äquivalente Abfrage: SHOW CREATE TABLE {db}.{table}
  • MIME-Typ: text/plain

• starrocks:///{db}/tables

  • Beschreibung: Listet alle Tabellen in einer bestimmten Datenbank auf.
  • Äquivalente Abfrage: SHOW TABLES FROM {db}
  • MIME-Typ: text/plain

• proc:///{+path}

  • Beschreibung: Greift auf interne Systeminformationen von StarRocks zu, ähnlich wie Linux /proc. Der Parameter path gibt den gewünschten Informationsknoten an.
  • Äquivalente Abfrage: SHOW PROC '/{path}'
  • MIME-Typ: text/plain
  • Häufige Pfade:
    • /frontends - Informationen über FE-Knoten.
    • /backends - Informationen über BE-Knoten (für nicht Cloud-native Bereitstellungen).
    • /compute_nodes - Informationen über CN-Knoten (für Cloud-native Bereitstellungen).
    • /dbs - Informationen über Datenbanken.
    • /dbs/<DB_ID> - Informationen über eine bestimmte Datenbank nach ID.
    • /dbs/<DB_ID>/<TABLE_ID> - Informationen über eine bestimmte Tabelle nach ID.
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - Partitionsinformationen für eine Tabelle.
    • /transactions - Transaktionsinformationen gruppiert nach Datenbank.
    • /transactions/<DB_ID> - Transaktionsinformationen für eine bestimmte Datenbank-ID.
    • /transactions/<DB_ID>/running - Laufende Transaktionen für eine Datenbank-ID.
    • /transactions/<DB_ID>/finished - Abgeschlossene Transaktionen für eine Datenbank-ID.
    • /jobs - Informationen über asynchrone Jobs (Schema Change, Rollup usw.).
    • /statistic - Statistiken für jede Datenbank.
    • /tasks - Informationen über Agent-Aufgaben.
    • /cluster_balance - Informationen zum Lastausgleichsstatus.
    • /routine_loads - Informationen über Routine-Load-Jobs.
    • /colocation_group - Informationen über Colocation-Join-Gruppen.
    • /catalog - Informationen über konfigurierte Kataloge (z. B. Hive, Iceberg).

Prompts

Von diesem Server sind keine definiert.

Cache-Verhalten

• Die Tools table_overview und db_overview verwenden einen In-Memory-Cache, um den generierten Übersichtstext zu speichern.
• Der Cache-Schlüssel ist ein Tupel aus (database_name, table_name).
• Wenn table_overview aufgerufen wird, wird zuerst der Cache geprüft. Wenn ein Ergebnis vorhanden ist und der Parameter refresh false (Standard) ist, wird das zwischengespeicherte Ergebnis sofort zurückgegeben. Andernfalls werden die Daten von StarRocks abgerufen, im Cache gespeichert und dann zurückgegeben.
• Wenn db_overview aufgerufen wird, listet es alle Tabellen in der Datenbank auf und versucht dann, die Übersicht für jede Tabelle mit derselben Cache-Logik wie table_overview abzurufen (zuerst Cache prüfen, bei Bedarf abrufen, wenn refresh false ist oder Cache-Fehlschlag). Wenn refresh true für db_overview ist, erzwingt es eine Aktualisierung für alle Tabellen in dieser Datenbank.
• Die Umgebungsvariable STARROCKS_OVERVIEW_LIMIT bietet ein weiches Ziel für die maximale Länge des Übersichtstexts, der pro Tabelle beim Auffüllen des Caches generiert wird, um die Speichernutzung zu verwalten.
• Zwischengespeicherte Ergebnisse, einschließlich aller Fehlermeldungen, die während des ursprünglichen Abrufs aufgetreten sind, werden gespeichert und bei nachfolgenden Cache-Treffern zurückgegeben.

Debug

Nach dem Start des MCP-Servers können Sie den Inspector zum Debuggen verwenden:

npx @modelcontextprotocol/inspector

Demo