StarRocks

Serveur MCP officiel StarRocks

Le serveur MCP StarRocks agit comme un pont entre les assistants IA et les bases de données StarRocks. Il permet l'exécution directe de SQL, l'exploration de bases de données, la visualisation de données via des graphiques, et la récupération d'aperçus détaillés du schéma et des données sans nécessiter une configuration complexe côté client.

Fonctionnalités

• Exécution SQL directe : Exécutez des requêtes SELECT (read_query) et des commandes DDL/DML (write_query).
• Exploration de bases de données : Listez les bases de données et les tables, récupérez les schémas de tables (ressources starrocks://).
• Informations système : Accédez aux métriques et états internes de StarRocks via le chemin de ressource proc://.
• Aperçus détaillés : Obtenez des résumés complets des tables (table_overview) ou de bases de données entières (db_overview), y compris les définitions de colonnes, les nombres de lignes et des données d'exemple.
• Visualisation de données : Exécutez une requête et générez un graphique Plotly directement à partir des résultats (query_and_plotly_chart).
• Mise en cache intelligente : Les aperçus de tables et de bases de données sont mis en cache en mémoire pour accélérer les requêtes répétées. Le cache peut être contourné si nécessaire.
• Configuration flexible : Définissez les détails de connexion et le comportement via des variables d'environnement.

Prérequis

• Python 3.11 ou plus récent.
• Un cluster StarRocks accessible (service FE). Par défaut, le serveur se connecte à localhost:9030 via le protocole MySQL.
• uv — un gestionnaire de paquets et de projets Python rapide (un remplacement moderne de pip + virtualenv) d'Astral. Ce projet utilise uv pour résoudre les dépendances, créer l'environnement virtuel et lancer le serveur. Les commandes uv run tout au long de ce README créent automatiquement un environnement isolé et installent les dépendances requises lors de la première utilisation, donc aucune étape manuelle de pip install n'est nécessaire.

Installation de 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

Consultez le guide d'installation officiel de uv pour d'autres options. Après l'installation, vérifiez qu'il est dans votre PATH :

uv --version

Installation

Vous n'avez généralement pas besoin d'installer le paquet manuellement — l'hôte MCP le lance pour vous via uv (voir Configuration ci-dessous). uv récupère le paquet et ses dépendances à la demande.

Pour l'exécuter directement pour des tests ou du développement :

# 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

Configuration

Le serveur MCP est généralement exécuté via un hôte MCP. La configuration est transmise à l'hôte, spécifiant comment lancer le processus du serveur MCP StarRocks.

Utilisation de Streamable HTTP (recommandé) :

Pour démarrer le serveur en mode Streamable HTTP :

Testez d'abord que la connexion à StarRocks est OK (9030 est le port du protocole MySQL de StarRocks, pas le port du serveur HTTP) :

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

Démarrez le serveur :

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

Configurez ensuite le MCP comme ceci :

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

Utilisation de Docker :

Construisez l'image :

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

Construisez et poussez une image versionnée :

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

Démarrez le serveur en mode Streamable HTTP :

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

Configurez ensuite le client MCP avec :

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

Utilisation de uv avec le paquet installé (variables d'environnement individuelles) :

{
  "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"
      }
    }
  }
}

Utilisation de uv avec le paquet installé (URL de connexion) :

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

Utilisation de uv avec le répertoire local (pour le développement) :

{
  "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"
      }
    }
  }
}

Utilisation de uv avec le répertoire local et l'URL de connexion :

{
  "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"
      }
    }
  }
}

Arguments de ligne de commande :

Le serveur prend en charge les arguments de ligne de commande suivants :

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http} : Mode de transport (défaut : stdio ou variable d'environnement MCP_TRANSPORT_MODE)
• --host HOST : Hôte du serveur pour les modes HTTP (défaut : localhost)
• --port PORT : Port du serveur pour les modes HTTP
• --test : Exécuter en mode test pour vérifier les fonctionnalités

Exemples :

# 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

• Le champ url doit pointer vers le point de terminaison Streamable HTTP de votre serveur MCP (ajustez l'hôte/le port si nécessaire).
• Avec cette configuration, les clients peuvent interagir avec le serveur en utilisant du JSON standard sur des requêtes HTTP POST. Aucun SDK spécial n'est requis.
• Toutes les API d'outils acceptent et renvoient du JSON standard comme décrit ci-dessus.

Remarque : Le mode sse (Server-Sent Events) est obsolète et n'est plus maintenu. Veuillez utiliser le mode Streamable HTTP pour toutes les nouvelles intégrations.

Variables d'environnement :

Configuration de la connexion

Vous pouvez configurer la connexion StarRocks en utilisant soit des variables d'environnement individuelles, soit une seule URL de connexion :

Option 1 : Variables d'environnement individuelles

• STARROCKS_HOST : (Facultatif) Nom d'hôte ou adresse IP du service FE StarRocks. Par défaut : localhost.
• STARROCKS_PORT : (Facultatif) Port du protocole MySQL du service FE StarRocks. Par défaut : 9030.
• STARROCKS_USER : (Facultatif) Nom d'utilisateur StarRocks. Par défaut : root.
• STARROCKS_PASSWORD : (Facultatif) Mot de passe StarRocks. Par défaut : chaîne vide.
• STARROCKS_PASSWORD_FILE : (Facultatif) Chemin vers un fichier texte UTF-8 contenant le mot de passe. Utile avec l'injection de secrets basée sur des fichiers comme les identifiants systemd. Un saut de ligne final est ignoré. Utilisé uniquement lorsqu'aucun mot de passe explicite n'est fourni via STARROCKS_PASSWORD ou STARROCKS_URL.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE : (Facultatif, macOS uniquement) Nom du service de mots de passe générique à utiliser lors de la lecture du mot de passe depuis le trousseau. Utilisé uniquement lorsqu'aucun mot de passe explicite ou STARROCKS_PASSWORD_FILE n'est configuré.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT : (Facultatif, macOS uniquement) Nom du compte de mots de passe générique à utiliser lors de la lecture du mot de passe depuis le trousseau. Par défaut : utilisateur StarRocks résolu.
• STARROCKS_DB : (Facultatif) Base de données par défaut à utiliser si elle n'est pas spécifiée dans les arguments d'outil ou les URI de ressources. Si définie, la connexion tentera de USE cette base de données. Des outils comme table_overview et db_overview l'utiliseront si la partie base de données est omise dans leurs arguments. Par défaut : vide (aucune base de données par défaut).
• STARROCKS_QUERY_TIMEOUT : (Facultatif) Nombre de secondes à attendre les résultats d'une requête avant d'abandonner, sous forme d'entier. Non défini par défaut, ce qui attend indéfiniment, correspondant au comportement précédent. Définissez-le si une requête bloquée ou de longue durée doit échouer au lieu de bloquer un appel d'outil pour toujours.

Option 2 : URL de connexion (prioritaire sur les variables individuelles)

• STARROCKS_URL : (Facultatif) Chaîne d'URL de connexion contenant tous les paramètres de connexion dans une seule variable. Format : [<schema>://]user:password@host:port/database. La partie schéma est facultative. Lorsque cette variable est définie, elle a priorité sur les variables individuelles STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD et STARROCKS_DB.

  Exemples :

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

Priorité du mot de passe :

• Un mot de passe intégré dans STARROCKS_URL gagne, y compris un mot de passe vide explicite comme user:@host:9030/db.
• Si STARROCKS_URL omet le mot de passe, STARROCKS_PASSWORD est utilisé s'il est défini.
• Si aucune source de mot de passe explicite n'est définie et que STARROCKS_PASSWORD_FILE est configuré, le mot de passe est lu depuis ce fichier.
• Si aucun mot de passe explicite ou fichier de mot de passe n'est configuré et que STARROCKS_PASSWORD_KEYCHAIN_SERVICE est défini, le mot de passe est lu depuis le trousseau macOS.

Exemple de trousseau macOS

Stockez le mot de passe :

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

Vérifiez le mot de passe stocké :

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

Utilisez-le avec ce serveur :

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

Identifiants chiffrés systemd exemple (systemd 250 ou ultérieur)

Le serveur n'invoque pas systemd-creds lui-même. Au moment du déploiement, un administrateur chiffre le mot de passe ; au démarrage du service, systemd le déchiffre dans le répertoire d'identifiants du service et n'expose que le chemin du fichier à ce serveur.

Créez un identifiant chiffré lié à l'hôte sans mettre le mot de passe dans l'historique du shell :

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

Ajoutez l'identifiant à l'unité de service. Le spécificateur %d s'étend au répertoire d'identifiants spécifique au service :

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

Laissez STARROCKS_PASSWORD non défini et omettez le mot de passe de STARROCKS_URL, puis rechargez l'unité et redémarrez le service. L'identifiant chiffré est normalement lié à l'hôte local (et à son dispositif TPM2 lorsqu'il est disponible) ; il n'est déchiffré que pendant l'activation du service. Le processus de service et les administrateurs disposant de privilèges root peuvent toujours accéder au mot de passe en clair au moment de l'exécution. N'utilisez pas systemd-creds encrypt --with-key=null, qui ne fournit pas de confidentialité.

Configuration supplémentaire

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT : (Facultatif) Port Arrow Flight SQL du service FE StarRocks. Lorsqu'il est défini, le serveur se connecte en utilisant le protocole haute performance Arrow Flight SQL (via les pilotes ADBC) au lieu du protocole MySQL standard. Laissez non défini pour utiliser la connexion MySQL par défaut. L'hôte, l'utilisateur et le mot de passe sont tirés des mêmes paramètres de connexion décrits ci-dessus.

• STARROCKS_OVERVIEW_LIMIT : (Facultatif) Une limite de caractères approximative pour le texte total généré par les outils d'aperçu (table_overview, db_overview) lors de la récupération des données pour remplir le cache. Cela aide à prévenir une utilisation excessive de la mémoire pour des schémas très volumineux ou de nombreuses tables. Par défaut : 20000.

• STARROCKS_MCP_OUTPUT_DIR : (Facultatif) Répertoire utilisé par read_query lorsque son argument output_file est un chemin relatif. Par défaut : ~/.mcp-server-starrocks/output/. Le répertoire est créé à la demande. Les chemins absolus passés à output_file (y compris les chemins préfixés par ~) contournent ce paramètre. Remarque : les fichiers sont écrits sur la machine où le serveur MCP s'exécute. Pour Claude Code / Claude Desktop, le serveur s'exécute localement, donc les fichiers atterrissent sur votre ordinateur portable. Pour les déploiements distants/http, le fichier atterrit sur le serveur, pas sur le client.

• STARROCKS_CHART_OUTPUT_DIR : (Facultatif) Répertoire où query_and_plotly_chart écrit les graphiques HTML interactifs (lorsque format="html"). Par défaut : répertoire temporaire du système. Le répertoire est créé à la demande. Remarque : comme les autres fichiers de sortie, les graphiques sont écrits sur la machine où le serveur MCP s'exécute.

• STARROCKS_CHART_INCLUDE_PLOTLYJS : (Facultatif) Contrôle la façon dont plotly.js est intégré dans les graphiques HTML. cdn (défaut) garde les fichiers petits mais nécessite un accès réseau lors de la visualisation ; inline/true intègre la bibliothèque complète pour une utilisation hors ligne ; directory et false sont également acceptés (transmis à write_html de Plotly).

• STARROCKS_CHART_DEFAULT_FORMAT : (Facultatif) Format de sortie par défaut pour query_and_plotly_chart lorsque l'argument format est omis. Un de json, png, jpeg (défaut) ou html. Définissez sur html pour toujours écrire un fichier de graphique interactif dans STARROCKS_CHART_OUTPUT_DIR (avec un aperçu PNG intégré) sans passer format à chaque appel. Les valeurs invalides reviennent à jpeg avec un avertissement.

• STARROCKS_MYSQL_AUTH_PLUGIN : (Facultatif) Spécifie le plugin d'authentification à utiliser lors de la connexion au service FE StarRocks. Par exemple, définissez sur mysql_clear_password si votre déploiement StarRocks nécessite une authentification par mot de passe en texte clair (comme lors de l'utilisation de certaines configurations LDAP ou d'authentification externe). Ne définissez ceci que si votre environnement l'exige spécifiquement ; sinon, le auth_plugin par défaut est utilisé.

Configuration TLS / SSL

Ces variables contrôlent TLS pour la connexion. Lorsqu'aucune d'entre elles n'est définie, le mysql.connector sous-jacent conserve son comportement par défaut (ssl-mode=PREFERRED) : la connexion est chiffrée si le serveur prend en charge TLS, mais le certificat du serveur n'est pas vérifié. Pour une sécurité réelle, fournissez un certificat d'autorité de certification et activez la vérification.

• STARROCKS_SSL_DISABLED : (Facultatif) Définir sur true pour forcer la désactivation de TLS. Remplace tous les autres paramètres SSL. Par défaut, false.
• STARROCKS_SSL_CA : (Facultatif) Chemin vers le certificat CA (PEM) utilisé pour vérifier le certificat du serveur StarRocks.
• STARROCKS_SSL_CERT : (Facultatif) Chemin vers le certificat client (PEM) pour TLS mutuel (mTLS).
• STARROCKS_SSL_KEY : (Facultatif) Chemin vers la clé privée du client (PEM) pour TLS mutuel (mTLS).
• STARROCKS_SSL_VERIFY_CERT : (Facultatif) Définir sur true pour vérifier le certificat du serveur par rapport à l'autorité de certification. Par défaut, false.
• STARROCKS_SSL_VERIFY_IDENTITY : (Facultatif) Définir sur true pour également vérifier que le nom d'hôte du serveur correspond au certificat. Par défaut, false.
• STARROCKS_TLS_VERSIONS : (Facultatif) Liste séparée par des virgules des versions TLS autorisées, par exemple TLSv1.2,TLSv1.3.

Exemple (vérifier le serveur par rapport à un certificat CA) :

"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"
}

Pour la connexion haute performance Arrow Flight SQL (activée via STARROCKS_FE_ARROW_FLIGHT_SQL_PORT), TLS est contrôlé séparément :

• STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS : (Facultatif) Définir sur true pour utiliser grpc+tls:// au lieu de grpc:// en texte brut. Lorsqu'il est activé, STARROCKS_SSL_CA est utilisé comme certificat racine TLS et STARROCKS_SSL_VERIFY_CERT=false (par défaut) ignore la vérification du certificat du serveur.

Note de sécurité : évitez de stocker des mots de passe en texte brut directement dans mcp.json. Préférez injecter STARROCKS_PASSWORD (et les chemins de certificats) depuis un gestionnaire de secrets ou l'environnement, et ne commettez jamais d'identifiants dans le contrôle de version.

• MCP_TRANSPORT_MODE : (Facultatif) Mode de communication qui spécifie comment le serveur MCP expose ses services. Options disponibles :
  • stdio (par défaut) : Communique via l'entrée/sortie standard, adapté à l'hébergement par l'hôte MCP.
  • streamable-http (Streamable HTTP) : Démarre en tant que serveur HTTP streamable, prenant en charge les appels API RESTful.
  • sse : (Obsolète, non recommandé) Démarre en mode de diffusion Server-Sent Events (SSE), adapté aux scénarios nécessitant des réponses en streaming. Remarque : le mode SSE n'est plus maintenu, il est recommandé d'utiliser uniformément le mode HTTP streamable.

Composants

Outils

• read_query

  • Description : Exécute une requête SELECT ou d'autres commandes qui renvoient un ResultSet (par exemple, SHOW, DESCRIBE). Écrit éventuellement le résultat complet dans un fichier local au lieu de le renvoyer en ligne — utile pour les résultats trop volumineux pour tenir dans le contexte du modèle.
  • Entrée :

    {
      "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"
    }
    

  • Sortie : Sans output_file, contenu texte contenant les résultats de la requête au format CSV avec une ligne d'en-tête et un résumé du nombre de lignes. Avec output_file, un court résumé incluant le chemin absolu résolu, le nombre d'octets et le nombre de lignes, plus un petit aperçu. Renvoie un message d'erreur en cas d'échec.

• write_query

  • Description : Exécute une commande DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) ou une autre commande StarRocks qui ne renvoie pas de ResultSet.
  • Entrée :

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

  • Sortie : Contenu texte confirmant le succès (par exemple, « Query OK, X rows affected ») ou signalant une erreur. Les modifications sont validées automatiquement en cas de succès.

• analyze_query

  • Description : Analyse une requête et obtient le résultat de l'analyse en utilisant le profil de requête ou l'analyse d'explication.
  • Entrée :

    {
      "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)"
    }
    

  • Sortie : Contenu texte contenant les résultats de l'analyse de la requête. Utilise ANALYZE PROFILE FROM si un uuid est fourni, sinon utilise EXPLAIN ANALYZE si une requête SQL est fournie.

• top_hot_tables

  • Description : Obtient les tables les plus chaudes par nombre de visites dans le journal d'audit. Il joint information_schema.tables avec starrocks_audit_db__.starrocks_audit_tbl__, exclut les instructions root et SHOW, fait correspondre le texte SQL d'audit aux noms de tables et trie par visit_count décroissant.
  • Entrée :

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

  • Sortie : Résumé texte plus contenu structuré contenant des lignes classées avec db, table et visit_count.

• top_bad_tables

  • Description : Obtient les pires tables par score de santé de table, en suivant la logique top-bad-tables de Star Management Studio. Il réutilise le calcul de santé de table basé sur information_schema.be_tablets et information_schema.partitions_meta, filtre les schémas système, trie par table_health_score croissant et renvoie les tables avec les scores les plus bas.
  • Entrée :

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

  • Sortie : Résumé texte plus contenu structuré contenant des lignes classées avec des champs de santé de table tels que db, table, tablet_num, replica_score, tablet_score et table_health_score.

• query_and_plotly_chart

  • Description : Exécute une requête SQL, charge les résultats dans un DataFrame Pandas et génère un graphique Plotly en utilisant une expression Python fournie. Conçu pour la visualisation dans les interfaces utilisateur prenant en charge.
  • Entrée :

    {
      "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)"
    }
    

  • Sortie : Une liste contenant :
    1. TextContent : Une représentation texte du DataFrame et une note indiquant que le graphique est destiné à l'affichage dans l'interface utilisateur.
    2. ImageContent : Le graphique Plotly généré encodé en image PNG base64 (image/png). Renvoie un message d'erreur texte en cas d'échec ou si la requête ne renvoie aucune donnée.

• table_overview

  • Description : Obtient un aperçu d'une table spécifique : colonnes (depuis DESCRIBE), nombre total de lignes et lignes d'échantillon (LIMIT 3). Utilise un cache en mémoire sauf si refresh est vrai.
  • Entrée :

    {
      "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.
    }
    

  • Sortie : Contenu texte contenant l'aperçu formaté (colonnes, nombre de lignes, données d'échantillon) ou un message d'erreur. Les résultats en cache incluent les erreurs précédentes si applicable.

• db_overview

  • Description : Obtient un aperçu (colonnes, nombre de lignes, lignes d'échantillon) pour toutes les tables d'une base de données spécifiée. Utilise le cache au niveau de la table pour chaque table sauf si refresh est vrai.
  • Entrée :

    {
      "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.
    }
    

  • Sortie : Contenu texte contenant les aperçus concaténés pour toutes les tables trouvées dans la base de données, séparés par des en-têtes. Renvoie un message d'erreur si la base de données ne peut pas être accédée ou ne contient aucune table.

Ressources

Ressources directes

• starrocks:///databases
  • Description : Liste toutes les bases de données accessibles à l'utilisateur configuré.
  • Requête équivalente : SHOW DATABASES
  • Type MIME : text/plain

Modèles de ressources

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

  • Description : Obtient la définition de schéma d'une table spécifique.
  • Requête équivalente : SHOW CREATE TABLE {db}.{table}
  • Type MIME : text/plain

• starrocks:///{db}/tables

  • Description : Liste toutes les tables d'une base de données spécifique.
  • Requête équivalente : SHOW TABLES FROM {db}
  • Type MIME : text/plain

• proc:///{+path}

  • Description : Accède aux informations système internes de StarRocks, similaire à Linux /proc. Le paramètre path spécifie le nœud d'information souhaité.
  • Requête équivalente : SHOW PROC '/{path}'
  • Type MIME : text/plain
  • Chemins courants :
    • /frontends - Informations sur les nœuds FE.
    • /backends - Informations sur les nœuds BE (pour les déploiements non cloud natifs).
    • /compute_nodes - Informations sur les nœuds CN (pour les déploiements cloud natifs).
    • /dbs - Informations sur les bases de données.
    • /dbs/<DB_ID> - Informations sur une base de données spécifique par ID.
    • /dbs/<DB_ID>/<TABLE_ID> - Informations sur une table spécifique par ID.
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - Informations de partition pour une table.
    • /transactions - Informations de transaction groupées par base de données.
    • /transactions/<DB_ID> - Informations de transaction pour un ID de base de données spécifique.
    • /transactions/<DB_ID>/running - Transactions en cours pour un ID de base de données.
    • /transactions/<DB_ID>/finished - Transactions terminées pour un ID de base de données.
    • /jobs - Informations sur les tâches asynchrones (Schema Change, Rollup, etc.).
    • /statistic - Statistiques pour chaque base de données.
    • /tasks - Informations sur les tâches d'agent.
    • /cluster_balance - Informations sur l'état de l'équilibrage de charge.
    • /routine_loads - Informations sur les tâches Routine Load.
    • /colocation_group - Informations sur les groupes Colocation Join.
    • /catalog - Informations sur les catalogues configurés (par exemple, Hive, Iceberg).

Invites

Aucune définie par ce serveur.

Comportement de mise en cache

• Les outils table_overview et db_overview utilisent un cache en mémoire pour stocker le texte d'aperçu généré.
• La clé de cache est un tuple de (database_name, table_name).
• Lorsque table_overview est appelé, il vérifie d'abord le cache. Si un résultat existe et que le paramètre refresh est false (par défaut), le résultat en cache est renvoyé immédiatement. Sinon, il récupère les données depuis StarRocks, les stocke dans le cache, puis les renvoie.
• Lorsque db_overview est appelé, il liste toutes les tables de la base de données puis tente de récupérer l'aperçu pour chaque table en utilisant la même logique de cache que table_overview (vérification du cache d'abord, récupération si nécessaire et refresh est false ou en cas d'absence dans le cache). Si refresh est true pour db_overview, il force une actualisation pour toutes les tables de cette base de données.
• La variable d'environnement STARROCKS_OVERVIEW_LIMIT fournit une cible souple pour la longueur maximale de la chaîne d'aperçu générée par table lors du remplissage du cache, aidant à gérer l'utilisation de la mémoire.
• Les résultats en cache, y compris les messages d'erreur rencontrés lors de la récupération d'origine, sont stockés et renvoyés lors des accès ultérieurs au cache.

Débogage

Après avoir démarré le serveur mcp, vous pouvez utiliser l'inspecteur pour déboguer :

npx @modelcontextprotocol/inspector

Démo