Apache Doris MCP Server

officiel

Serveur MCP pour Apache Doris, un entrepôt de données en temps réel basé sur MPP.

Documentation

Serveur MCP Doris

Le serveur MCP (Model Context Protocol) Doris est un service backend construit avec Python et FastAPI. Il implémente le protocole MCP, permettant aux clients d'interagir avec lui via des « Outils » définis. Il est principalement conçu pour se connecter aux bases de données Apache Doris, en exploitant potentiellement les grands modèles de langage (LLM) pour des tâches telles que la conversion de requêtes en langage naturel en SQL (NL2SQL), l'exécution de requêtes et la gestion et l'analyse des métadonnées.

🚀 Nouveautés de la v0.6.0

🔐 Système d'authentification d'entreprise : Configuration de base de données révolutionnaire liée aux jetons avec prise en charge complète de l'authentification par jeton, JWT et OAuth, permettant un accès multi-tenant sécurisé avec des commutateurs de contrôle granulaires et des paramètres de sécurité par défaut de niveau entreprise.
⚡ Validation immédiate de la base de données : Validation de la configuration de la base de données en temps réel au moment de la connexion, éliminant les blocages au moment de la requête et fournissant un retour instantané pour les configurations invalides - atteignant une élimination à 100 % des échecs de connexion tardifs.
🔄 Gestion de la configuration par rechargement à chaud : Mises à jour de configuration sans interruption de service avec rechargement à chaud intelligent de tokens.json, revalidation automatique des jetons et gestion complète des erreurs avec mécanismes de restauration.
🏗️ Architecture de connexion avancée : Mise en cache des sessions et optimisation du pool de connexions avec une réduction de 60 % de la surcharge de connexion, recréation intelligente du pool et gestion automatique des ressources.
🌐 Scalabilité multi-worker : Véritable mise à l'échelle horizontale avec une architecture multi-worker sans état, une distribution de charge efficace et des capacités de traitement simultané de niveau entreprise.
🔒 Cadre de sécurité amélioré : Contrôle d'accès complet et validation de sécurité SQL avec validation immédiate, autorisations basées sur les rôles et modèles de détection d'injection améliorés.
🛠️ Système de configuration unifié : Gestion de configuration rationalisée avec une priorité correcte de la ligne de commande, une compatibilité Docker améliorée et une prise en charge du déploiement multiplateforme.
📊 Tableau de bord de gestion des jetons : Gestion complète du cycle de vie des jetons avec création, révocation, statistiques et pistes d'audit complètes pour la gouvernance des jetons d'entreprise.
🌐 Interface de gestion basée Web : Administration sécurisée des jetons uniquement sur localhost avec tableau de bord intuitif, configuration de liaison de base de données, opérations en temps réel et contrôles d'accès de niveau entreprise.

🚀 Jalon majeur : La v0.6.0 établit la plateforme comme un système de gestion de base de données et d'authentification d'entreprise prêt pour la production avec des opérations sans interruption de service (rechargement à chaud + validation immédiate + mise à l'échelle multi-worker), des contrôles de sécurité avancés et une configuration complète de base de données liée aux jetons - représentant une avancée fondamentale dans les capacités des plateformes de données d'entreprise.

Également inclus depuis la v0.5.1

🔥 Correction critique de connexion at_eof : Élimination complète des erreurs de pool de connexions avec une surveillance intelligente de l'état et une récupération auto-réparatrice.
🔧 Système de journalisation d'entreprise : Séparation des fichiers basée sur les niveaux avec nettoyage automatique et horodatage de précision à la milliseconde.
📊 Suite d'analyse de données avancée : 7 outils de gouvernance des données de niveau entreprise, y compris l'analyse de la qualité, le suivi de la lignée et la surveillance des performances.
🏃‍♂️ Intégration ADBC haute performance : Prise en charge d'Apache Arrow Flight SQL avec des améliorations de performances de 3 à 10x pour les grands ensembles de données.
⚙️ Gestion de configuration améliorée : Système de configuration ADBC complet avec validation intelligente des paramètres.

Fonctionnalités principales

Implémentation du protocole MCP : Fournit des interfaces MCP standard, prenant en charge les appels d'outils, la gestion des ressources et les interactions par invites.
Communication HTTP streamable : Point de terminaison HTTP unifié prenant en charge à la fois la communication requête/réponse et la diffusion en continu pour des performances et une fiabilité optimales.
Communication Stdio : Mode entrée/sortie standard pour une intégration directe avec les clients MCP comme Cursor.
Architecture de niveau entreprise : Conception modulaire avec des fonctionnalités complètes :
- Gestionnaire d'outils : Enregistrement et routage centralisés des outils avec des interfaces unifiées (doris_mcp_server/tools/tools_manager.py)
- Module d'outils de surveillance améliorés : Suivi avancé de la mémoire, collecte de métriques et découverte flexible des nœuds BE avec une conception modulaire et extensible
- Outils d'information sur les requêtes : Explication SQL et profilage améliorés avec troncature de contenu configurable, exportation de fichiers pour les pièces jointes LLM et analyses de requêtes avancées
- Gestionnaire de ressources : Gestion des ressources et exposition des métadonnées (doris_mcp_server/tools/resources_manager.py)
- Gestionnaire d'invites : Modèles d'invites intelligents pour l'analyse de données (doris_mcp_server/tools/prompts_manager.py)
Fonctionnalités de base de données avancées :
- Exécution de requêtes : Exécution SQL haute performance avec mise en cache et optimisation avancées, stabilité de connexion améliorée et mécanismes de nouvelle tentative automatique (doris_mcp_server/utils/query_executor.py)
- Gestion de la sécurité : Validation complète de la sécurité SQL avec mots-clés bloqués configurables, protection contre l'injection SQL, masquage des données et gestion unifiée de la configuration de sécurité (doris_mcp_server/utils/security.py)
- Extraction de métadonnées : Métadonnées de base de données complètes avec prise en charge de la fédération de catalogues (doris_mcp_server/utils/schema_extractor.py)
- Analyse des performances : Analyse avancée des colonnes, surveillance des performances et outils d'analyse de données (doris_mcp_server/utils/analysis_tools.py)
Prise en charge de la fédération de catalogues : Prise en charge complète des environnements multi-catalogues (tables Doris internes et sources de données externes comme Hive, MySQL, etc.)
Sécurité d'entreprise : Cadre de sécurité complet avec authentification, autorisation, protection contre l'injection SQL et capacités de masquage des données avec prise en charge de la configuration par variables d'environnement
Gestion des jetons basée Web : Interface sécurisée uniquement sur localhost pour la gestion complète du cycle de vie des jetons avec liaison de base de données, statistiques en temps réel et contrôles d'accès de niveau entreprise (doris_mcp_server/auth/token_handlers.py)
Cadre de configuration unifié : Gestion centralisée de la configuration via config.py avec validation complète, nommage standardisé des paramètres et gestion intelligente de la base de données par défaut avec basculement automatique vers information_schema

Configuration système requise

Python : 3.12+
Base de données : Détails de connexion à Apache Doris (hôte, port, utilisateur, mot de passe, base de données)

🚀 Démarrage rapide

Installation depuis PyPI

# Install the latest version
pip install doris-mcp-server

# Install specific version
pip install doris-mcp-server==0.6.0

💡 Compatibilité des commandes : Après l'installation, les deux commandes doris-mcp-server sont disponibles pour une compatibilité ascendante. Vous pouvez utiliser l'une ou l'autre commande de manière interchangeable.

Démarrer le mode HTTP streamable (service Web)

Le mode de communication principal offrant des performances et une fiabilité optimales :

# Full configuration with database connection
doris-mcp-server \
    --transport http \
    --host 0.0.0.0 \
    --port 3000 \
    --db-host 127.0.0.1 \
    --db-port 9030 \
    --db-user root \
    --db-password your_password

Démarrer le mode Stdio (pour Cursor et autres clients MCP)

Mode entrée/sortie standard pour une intégration directe avec les clients MCP :

# For direct integration with MCP clients like Cursor
doris-mcp-server --transport stdio

🌐 Interface de gestion des jetons (Nouveauté de la v0.6.0)

Accédez au Tableau de bord de gestion des jetons basé Web pour une administration des jetons de niveau entreprise :

Exigences d'accès sécurisé

Accès localhost uniquement : Interface restreinte à 127.0.0.1 et ::1 pour une sécurité maximale
Authentification administrateur : Nécessite TOKEN_MANAGEMENT_ADMIN_TOKEN pour l'accès

Prérequis de configuration :

# Required environment variables
ENABLE_HTTP_TOKEN_MANAGEMENT=true
ENABLE_TOKEN_AUTH=true
TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token
TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

Accès à l'interface

# Access the token management interface
http://localhost:3000/token/management?admin_token=your_secure_admin_token

Opérations disponibles

📊 Statistiques des jetons : Aperçu en temps réel des jetons actifs, expirés et totaux
➕ Créer des jetons :
- Informations de base (ID, description, expiration)
- Liaison de base de données (hôte, port, utilisateur, mot de passe, base de données)
- Valeurs de jeton personnalisées ou jetons sécurisés générés automatiquement
📋 Gestion des jetons :
- Lister tous les jetons avec l'état de liaison de base de données
- Révocation de jeton en un clic
- Nettoyage automatique des jetons expirés
🔒 Sécurité d'entreprise :
- Toutes les opérations nécessitent une authentification administrateur
- Validation IP en temps réel
- Journalisation d'audit complète
- Persistance automatique vers tokens.json

🔐 Note de sécurité : L'interface est conçue pour l'administration localhost uniquement. Elle n'est pas accessible à distance, garantissant une sécurité maximale pour les opérations de gestion des jetons.

Vérifier l'installation

# Check installation
doris-mcp-server --help

# Test HTTP mode (in another terminal)
curl http://localhost:3000/health

Variables d'environnement (facultatif)

Au lieu des arguments de ligne de commande, vous pouvez utiliser des variables d'environnement :

# Basic Database Configuration
export DORIS_HOST="127.0.0.1"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

# Token Management Interface (Security-Critical)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN="your_secure_admin_token"
export TOKEN_MANAGEMENT_ALLOWED_IPS="127.0.0.1,::1"

# Then start with simplified command
doris-mcp-server --transport http --host 0.0.0.0 --port 3000

Arguments de ligne de commande

La commande doris-mcp-server prend en charge les arguments suivants :

Argument	Description	Par défaut	Requis
`--transport`	Mode de transport : `http` ou `stdio`	`http`	Non
`--host`	Hôte du serveur HTTP (mode HTTP uniquement)	`0.0.0.0`	Non
`--port`	Port du serveur HTTP (mode HTTP uniquement)	`3000`	Non
`--db-host`	Hôte de la base de données Doris	`localhost`	Non
`--db-port`	Port de la base de données Doris	`9030`	Non
`--db-user`	Nom d'utilisateur de la base de données Doris	`root`	Non
`--db-password`	Mot de passe de la base de données Doris	-	Oui (sauf si dans env)

Configuration de développement

Pour les développeurs qui souhaitent construire à partir des sources :

1. Cloner le dépôt

# Replace with the actual repository URL if different
git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

2. Installer les dépendances

pip install -r requirements.txt

3. Configurer les variables d'environnement

Copiez le fichier .env.example vers .env et modifiez les paramètres en fonction de votre environnement :

cp .env.example .env

Variables d'environnement clés :

Connexion à la base de données :
- DORIS_HOST : Nom d’hôte de la base de données (par défaut : localhost)
- DORIS_PORT : Port de la base de données (par défaut : 9030)
- DORIS_USER : Nom d’utilisateur de la base de données (par défaut : root)
- DORIS_PASSWORD : Mot de passe de la base de données
- DORIS_DATABASE : Nom de la base de données par défaut (par défaut : information_schema)
- DORIS_MIN_CONNECTIONS : Taille minimale du pool de connexions (par défaut : 5)
- DORIS_MAX_CONNECTIONS : Taille maximale du pool de connexions (par défaut : 20)
- DORIS_BE_HOSTS : Nœuds BE pour la surveillance (séparés par des virgules, facultatif - découverte automatique via SHOW BACKENDS si vide)
- DORIS_BE_WEBSERVER_PORT : Port du serveur web BE pour les outils de surveillance (par défaut : 8040)
- FE_ARROW_FLIGHT_SQL_PORT : Port SQL Arrow Flight du Frontend pour ADBC (Nouveauté v0.5.0)
- BE_ARROW_FLIGHT_SQL_PORT : Port SQL Arrow Flight du Backend pour ADBC (Nouveauté v0.5.0)
Configuration de l’authentification (Améliorée dans v0.6.0) :
- ENABLE_TOKEN_AUTH : Activer l’authentification par jeton (par défaut : false)
- ENABLE_JWT_AUTH : Activer l’authentification JWT (par défaut : false)
- ENABLE_OAUTH_AUTH : Activer l’authentification OAuth (par défaut : false)
- ENABLE_DORIS_OAUTH_AUTH : Activer l’authentification OAuth adossée à Doris (par défaut : false)
- DORIS_OAUTH_BASE_URL : URL de base publique utilisée par les points de terminaison de découverte et de jeton OAuth adossés à Doris
- TOKEN_FILE_PATH : Chemin vers le fichier tokens.json pour la gestion des jetons (par défaut : tokens.json)
- TOKEN_HOT_RELOAD : Activer le rechargement à chaud de la configuration des jetons (par défaut : true)
- DEFAULT_ADMIN_TOKEN : Jeton administrateur par défaut (personnalisable via env)
- DEFAULT_ANALYST_TOKEN : Jeton analyste par défaut (personnalisable via env)
- DEFAULT_READONLY_TOKEN : Jeton lecture seule par défaut (personnalisable via env)
Configuration de sécurité héritée :
- AUTH_TYPE : Type d’authentification héritée (token/basic/oauth, déprécié - utiliser les commutateurs individuels)
- TOKEN_SECRET : Clé secrète de jeton héritée (utiliser plutôt l’authentification par jeton)
- ENABLE_SECURITY_CHECK : Activer/désactiver la validation de sécurité SQL (par défaut : true)
- BLOCKED_KEYWORDS : Liste de mots-clés SQL bloqués séparés par des virgules
- ENABLE_MASKING : Activer le masquage des données (par défaut : true)
- MAX_RESULT_ROWS : Nombre maximal de lignes de résultat (par défaut : 10000)
Configuration ADBC (Nouveauté v0.5.0) :
- ADBC_DEFAULT_MAX_ROWS : Nombre maximal de lignes par défaut pour les requêtes ADBC (par défaut : 100000)
- ADBC_DEFAULT_TIMEOUT : Délai d’expiration par défaut des requêtes ADBC en secondes (par défaut : 60)
- ADBC_DEFAULT_RETURN_FORMAT : Format de retour par défaut - arrow/pandas/dict (par défaut : arrow)
- ADBC_CONNECTION_TIMEOUT : Délai de connexion ADBC en secondes (par défaut : 30)
- ADBC_ENABLED : Activer/désactiver les outils ADBC (par défaut : true)
Configuration des performances :
- ENABLE_QUERY_CACHE : Activer la mise en cache des requêtes (par défaut : true)
- CACHE_TTL : Durée de vie du cache en secondes (par défaut : 300)
- MAX_CONCURRENT_QUERIES : Nombre maximal de requêtes simultanées (par défaut : 50)
- MAX_RESPONSE_CONTENT_SIZE : Taille maximale du contenu de réponse pour la compatibilité LLM (par défaut : 4096, Nouveauté v0.4.0)
Configuration de journalisation améliorée (Améliorée dans v0.5.0) :
- LOG_LEVEL : Niveau de journalisation (DEBUG/INFO/WARNING/ERROR, par défaut : INFO)
- LOG_FILE_PATH : Chemin du fichier journal (automatiquement organisé par niveau)
- ENABLE_AUDIT : Activer la journalisation d’audit (par défaut : true)
- ENABLE_LOG_CLEANUP : Activer le nettoyage automatique des journaux (par défaut : true, Amélioré dans v0.5.0)
- LOG_MAX_AGE_DAYS : Âge maximal des fichiers journaux en jours (par défaut : 30, Amélioré dans v0.5.0)
- LOG_CLEANUP_INTERVAL_HOURS : Intervalle de vérification du nettoyage des journaux en heures (par défaut : 24, Amélioré dans v0.5.0)
- Nouvelles fonctionnalités dans v0.5.0 :
  - Séparation des fichiers par niveau : Séparation automatique en debug.log, info.log, warning.log, error.log, critical.log
  - Format horodaté : Formatage amélioré avec précision à la milliseconde et alignement correct
  - Planificateur de nettoyage en arrière-plan : Nettoyage automatique avec politiques de rétention configurables
  - Piste d’audit : audit.log dédié avec gestion de rétention séparée
  - Optimisé pour les performances : Journalisation asynchrone à surcharge minimale avec prise en charge de la rotation

Outils MCP disponibles

Le tableau suivant répertorie les principaux outils actuellement disponibles pour invocation via un client MCP :

Nom de l’outil	Description	Paramètres
`exec_query`	Exécuter une requête SQL et renvoyer les résultats.	`sql` (chaîne, Obligatoire), `db_name` (chaîne, Facultatif), `catalog_name` (chaîne, Facultatif), `max_rows` (entier, Facultatif), `timeout` (entier, Facultatif)
`get_table_schema`	Obtenir des informations détaillées sur la structure de la table.	`table_name` (chaîne, Obligatoire), `db_name` (chaîne, Facultatif), `catalog_name` (chaîne, Facultatif)
`get_db_table_list`	Obtenir la liste de tous les noms de tables dans la base de données spécifiée.	`db_name` (chaîne, Facultatif), `catalog_name` (chaîne, Facultatif)
`get_db_list`	Obtenir la liste de tous les noms de bases de données.	`catalog_name` (chaîne, Facultatif)
`get_table_comment`	Obtenir les informations de commentaire de la table.	`table_name` (chaîne, Obligatoire), `db_name` (chaîne, Facultatif), `catalog_name` (chaîne, Facultatif)
`get_table_column_comments`	Obtenir les informations de commentaire pour toutes les colonnes de la table.	`table_name` (chaîne, Obligatoire), `db_name` (chaîne, Facultatif), `catalog_name` (chaîne, Facultatif)
`get_table_indexes`	Obtenir les informations d’index pour la table spécifiée.	`table_name` (chaîne, Obligatoire), `db_name` (chaîne, Facultatif), `catalog_name` (chaîne, Facultatif)
`get_recent_audit_logs`	Obtenir les enregistrements du journal d’audit pour la période récente.	`days` (entier, Facultatif), `limit` (entier, Facultatif)
`get_catalog_list`	Obtenir la liste de tous les noms de catalogues.	`random_string` (chaîne, Obligatoire)
`get_sql_explain`	Obtenir le plan d’exécution SQL avec troncature de contenu configurable et export de fichier pour l’analyse LLM.	`sql` (chaîne, Obligatoire), `verbose` (booléen, Facultatif), `db_name` (chaîne, Facultatif), `catalog_name` (chaîne, Facultatif)
`get_sql_profile`	Obtenir le profil d’exécution SQL avec gestion de contenu et export de fichier pour les workflows d’optimisation LLM.	`sql` (chaîne, Obligatoire), `db_name` (chaîne, Facultatif), `catalog_name` (chaîne, Facultatif), `timeout` (entier, Facultatif)
`get_table_data_size`	Obtenir les informations de taille des données de la table via l’API HTTP FE.	`db_name` (chaîne, Facultatif), `table_name` (chaîne, Facultatif), `single_replica` (booléen, Facultatif)
`get_monitoring_metrics_info`	Obtenir les définitions et descriptions des métriques de surveillance Doris.	`role` (chaîne, Facultatif), `monitor_type` (chaîne, Facultatif), `priority` (chaîne, Facultatif)
`get_monitoring_metrics_data`	Obtenir les données réelles des métriques de surveillance Doris à partir des nœuds avec découverte flexible des BE.	`role` (chaîne, Facultatif), `monitor_type` (chaîne, Facultatif), `priority` (chaîne, Facultatif)
`get_realtime_memory_stats`	Obtenir des statistiques mémoire en temps réel via le BE Memory Tracker avec découverte automatique/manuelle des BE.	`tracker_type` (chaîne, Facultatif), `include_details` (booléen, Facultatif)
`get_historical_memory_stats`	Obtenir des statistiques mémoire historiques via l’interface BE Bvar avec configuration flexible des BE.	`tracker_names` (tableau, Facultatif), `time_range` (chaîne, Facultatif)
`analyze_data_quality`	Analyse complète de la qualité des données combinant l’analyse de complétude et de distribution.	`table_name` (chaîne, Obligatoire), `analysis_scope` (chaîne, Facultatif), `sample_size` (entier, Facultatif), `business_rules` (tableau, Facultatif)
`trace_column_lineage`	Traçage de lignage de colonnes de bout en bout via l’analyse SQL et la cartographie des dépendances.	`target_columns` (tableau, Obligatoire), `analysis_depth` (entier, Facultatif), `include_transformations` (booléen, Facultatif)
`monitor_data_freshness`	Surveillance de la fraîcheur des données en temps réel avec seuils de fraîcheur configurables.	`table_names` (tableau, Facultatif), `freshness_threshold_hours` (entier, Facultatif), `include_update_patterns` (booléen, Facultatif)
`analyze_data_access_patterns`	Analyse du comportement utilisateur et détection d’anomalies de sécurité avec surveillance des modèles d’accès.	`days` (entier, Facultatif), `include_system_users` (booléen, Facultatif), `min_query_threshold` (entier, Facultatif)
`analyze_data_flow_dependencies`	Analyse d’impact des flux de données et cartographie des dépendances entre tables et vues.	`target_table` (chaîne, Facultatif), `analysis_depth` (entier, Facultatif), `include_views` (booléen, Facultatif)
`analyze_slow_queries_topn`	Identification des goulots d’étranglement de performance avec analyse des requêtes lentes top-N et des modèles.	`days` (entier, Facultatif), `top_n` (entier, Facultatif), `min_execution_time_ms` (entier, Facultatif), `include_patterns` (booléen, Facultatif)
`analyze_resource_growth_curves`	Planification de capacité avec analyse de croissance des ressources et prévision des tendances.	`days` (entier, Facultatif), `resource_types` (tableau, Facultatif), `include_predictions` (booléen, Facultatif)
`exec_adbc_query`	Exécution SQL haute performance utilisant le protocole ADBC (Arrow Flight SQL).	`sql` (chaîne, Obligatoire), `max_rows` (entier, Facultatif), `timeout` (entier, Facultatif), `return_format` (chaîne, Facultatif)
`get_adbc_connection_info`	Diagnostics de connexion ADBC et surveillance de l’état pour Arrow Flight SQL.	Aucun paramètre requis

Remarque : Tous les outils de métadonnées prennent en charge la fédération de catalogues pour les environnements multi-catalogues. Les outils de surveillance améliorés offrent des capacités complètes de suivi de la mémoire et de collecte de métriques. Nouveauté v0.5.0 : 7 outils d’analyse avancée pour la gouvernance des données d’entreprise et 2 outils ADBC pour le transfert de données haute performance avec des améliorations de performance de 3 à 10x pour les grands ensembles de données.

Remarque sur OAuth adossé à Doris : Le tableau ci-dessus décrit les capacités globales du serveur. OAuth adossé à Doris utilise des portes de configuration pour sa surface d’opération. Les ressources MCP sont disponibles avec la mise en cache des métadonnées de ressources désactivée. Les outils de métadonnées examinés sont appelables lorsque DORIS_OAUTH_DB_TOOLS_ENABLED=true ; exec_query et get_sql_explain sont appelables lorsque leurs portes de requête/explication OAuth Doris sont activées. Ces opérations du canal MySQL s’exécutent via le pool d’utilisateurs Doris connectés, donc le RBAC Doris est le backend final d’autorisation des données. Les invites, ADBC, le profil/surveillance HTTP FE, l’audit/gouvernance et l’analyse de performance restent fermés jusqu’à ce qu’ils disposent d’un routage par utilisateur ou d’une conception explicite de compte de service/admin.

4. Exécuter le service

Exécutez la commande suivante pour démarrer le serveur :

./start_server.sh

Cette commande démarre l’application FastAPI avec le service MCP HTTP Streamable.

5. Déploiement avec Docker

Si vous souhaitez exécuter uniquement le serveur Doris MCP dans Docker :

cd doris-mcp-server
docker build -t doris-mcp-server .
docker run -d -p <port>:<port> -v /*your-host*/doris-mcp-server/.env:/app/.env --name <your-mcp-server-name> -it doris-mcp-server:latest

Points de terminaison du service :

HTTP Streamable : http://<host>:<port>/mcp (Point de terminaison MCP principal - prend en charge GET, POST, DELETE, OPTIONS)
Vérification de l’état : http://<host>:<port>/health

Remarque : Le serveur utilise HTTP Streamable pour la communication basée sur le web, offrant des capacités unifiées de requête/réponse et de streaming.

Utilisation

L’interaction avec le serveur Doris MCP nécessite un Client MCP. Le client se connecte au point de terminaison HTTP Streamable du serveur et envoie des requêtes conformément à la spécification MCP pour invoquer les outils du serveur.

Flux d’interaction principal :

Initialisation du client : Envoyez un appel de méthode initialize à /mcp (HTTP Streamable).
(Optionnel) Découvrir les outils : Le client peut appeler tools/list pour obtenir la liste des outils pris en charge, leurs descriptions et les schémas de paramètres.
Appeler un outil : Le client envoie une requête tools/call, en spécifiant le name et les arguments.
- Exemple : Obtenir le schéma de table
  - name : get_table_schema
  - arguments : Inclure table_name, db_name, catalog_name.
Gérer la réponse :
- Non-streaming : Le client reçoit une réponse contenant content ou isError.
- Streaming : Le client reçoit une série de notifications de progression, suivies d'une réponse finale.

Prise en charge de la fédération de catalogues

Le serveur MCP Doris prend en charge la fédération de catalogues, permettant d'interagir avec plusieurs catalogues de données (tables Doris internes et sources de données externes comme Hive, MySQL, etc.) au sein d'une interface unifiée.

Fonctionnalités clés :

Accès aux métadonnées multi-catalogues : Tous les outils de métadonnées (get_db_list, get_db_table_list, get_table_schema, etc.) prennent en charge un paramètre optionnel catalog_name pour interroger des catalogues spécifiques.
Requêtes SQL inter-catalogues : Exécutez des requêtes SQL qui couvrent plusieurs catalogues en utilisant une dénomination de table en trois parties.
Découverte de catalogues : Utilisez get_catalog_list pour découvrir les catalogues disponibles et leurs types.

Exigence de dénomination en trois parties :

Toutes les requêtes SQL DOIVENT utiliser une dénomination en trois parties pour les références de table :

Tables internes : internal.database_name.table_name
Tables externes : catalog_name.database_name.table_name

Exemples :

Obtenir les catalogues disponibles :

{
  "tool_name": "get_catalog_list",
  "arguments": {"random_string": "unique_id"}
}

Obtenir les bases de données dans un catalogue spécifique :

{
  "tool_name": "get_db_list", 
  "arguments": {"random_string": "unique_id", "catalog_name": "mysql"}
}

Interroger le catalogue interne :

{
  "tool_name": "exec_query",
  "arguments": {
    "random_string": "unique_id",
    "sql": "SELECT COUNT(*) FROM internal.ssb.customer"
  }
}

Interroger le catalogue externe :

{
  "tool_name": "exec_query", 
  "arguments": {
    "random_string": "unique_id",
    "sql": "SELECT COUNT(*) FROM mysql.ssb.customer"
  }
}

Requête inter-catalogues :

{
  "tool_name": "exec_query",
  "arguments": {
    "random_string": "unique_id", 
    "sql": "SELECT i.c_name, m.external_data FROM internal.ssb.customer i JOIN mysql.test.user_info m ON i.c_custkey = m.customer_id"
  }
}

Configuration de la sécurité

Le serveur MCP Doris inclut un cadre de sécurité complet de niveau entreprise avec une authentification avancée, une autorisation, une validation de sécurité SQL et des capacités de masquage de données améliorées dans la v0.6.0.

Fonctionnalités de sécurité (Améliorées dans la v0.6.0)

🔐 Système d'authentification multiple : Authentification complète par Token, JWT et OAuth avec des commutateurs de contrôle indépendants
🔗 Configuration de base de données liée au token : Approche révolutionnaire permettant aux tokens de porter leurs propres paramètres de connexion à la base de données
🔄 Rechargement à chaud de la sécurité : Mises à jour de la configuration de sécurité sans temps d'arrêt avec revalidation intelligente des tokens
⚡ Validation immédiate : Validation en temps réel de la base de données et de l'authentification au moment de la connexion
🛡️ Autorisation basée sur les rôles : RBAC avancé avec classification de sécurité à quatre niveaux
🚫 Sécurité SQL améliorée : Protection avancée contre les injections SQL avec une détection de motifs améliorée
🎭 Masquage intelligent des données : Masquage automatique des données sensibles avec des permissions basées sur l'utilisateur
📊 Analyse de sécurité : Pistes d'audit complètes et surveillance de la sécurité

Configuration de l'authentification (v0.6.0)

Configurez le nouveau système d'authentification avec un contrôle granulaire :

# Individual Authentication Control (New in v0.6.0)
ENABLE_TOKEN_AUTH=true          # Enable token-based authentication
ENABLE_JWT_AUTH=false           # Enable JWT authentication  
ENABLE_OAUTH_AUTH=false         # Enable OAuth authentication

# Token Management (New in v0.6.0)
TOKEN_FILE_PATH=tokens.json     # Token configuration file
TOKEN_HOT_RELOAD=true          # Enable hot reloading

# Default Tokens (Customizable via environment)
DEFAULT_ADMIN_TOKEN=doris_admin_token_123456
DEFAULT_ANALYST_TOKEN=doris_analyst_token_123456
DEFAULT_READONLY_TOKEN=doris_readonly_token_123456

# Legacy Configuration (Deprecated)
# AUTH_TYPE=token               # Use individual switches instead
# TOKEN_SECRET=your_secret_key  # Use token-based auth instead

Authentification OAuth adossée à Doris

L'OAuth adossé à Doris est un mode OAuth distinct où Doris elle-même est le backend d'autorisation. Le client MCP découvre les métadonnées OAuth de ce serveur, l'utilisateur se connecte avec un nom d'utilisateur et un mot de passe Doris, le serveur valide ces informations d'identification en créant un pool de connexions Doris par utilisateur, et les tokens d'accès doa_ émis acheminent les appels d'outils via le pool Doris de cet utilisateur. Les portées MCP contrôlent quelles opérations MCP peuvent être appelées ; le RBAC Doris contrôle quels catalogues, bases de données, tables et métadonnées l'utilisateur peut voir.

Ce mode n'est pas le même que l'OAuth/OIDC externe. ENABLE_DORIS_OAUTH_AUTH=true est en conflit avec ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true et l'ancien AUTH_TYPE=oauth ; le démarrage échoue rapidement si les deux modes sont configurés. Un agent MCP standard entre une URL MCP et doit découvrir exactement un comportement OAuth pour cette URL, donc le flux de connexion OAuth externe /auth/* existant n'est pas utilisé en mode OAuth adossé à Doris.

Configuration locale minimale

L'exemple suivant est destiné au développement local sur un seul worker :

TRANSPORT=http
WORKERS=1

DORIS_HOST=localhost
DORIS_PORT=9030
DORIS_USER=root
DORIS_PASSWORD=<service-account-password>
DORIS_DATABASE=information_schema

ENABLE_DORIS_OAUTH_AUTH=true
DORIS_OAUTH_BASE_URL=http://localhost:3000
ENABLE_OAUTH_AUTH=false

DORIS_OAUTH_DB_TOOLS_ENABLED=true
DORIS_OAUTH_DB_TOOL_ALLOWLIST=get_db_list,get_db_table_list,get_table_schema,get_table_comment,get_table_column_comments,get_table_indexes,get_catalog_list
DORIS_OAUTH_QUERY_TOOLS_ENABLED=true
DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true

# Optional: let Doris RBAC, not the legacy MCP SQL guard, decide DDL/DML.
ENABLE_SECURITY_CHECK=false

Le compte de service Doris configuré est toujours requis par la validation au démarrage et par les chemins de compatibilité non-Doris-OAuth. Les requêtes OAuth adossées à Doris sont fermées par défaut si le pool par utilisateur est manquant et ne doivent pas revenir au compte de service/global.

Accès aux outils OAuth Doris

DORIS_OAUTH_DB_TOOLS_ENABLED=true ouvre le compartiment de métadonnées examiné. Les outils examinés sont :

get_db_list
get_db_table_list
get_table_schema
get_table_comment
get_table_column_comments
get_table_indexes
get_catalog_list

Pour les flux OAuth MCP normaux, les clients n'ont pas besoin de passer une longue liste --scopes. Si la requête OAuth omet la portée, le serveur accorde l'enveloppe de capacité OAuth Doris configurée. Pour les opérations du canal MySQL, le RBAC Doris décide si l'utilisateur Doris connecté peut réellement lire les métadonnées, exécuter du SQL ou expliquer le SQL.

DORIS_OAUTH_QUERY_TOOLS_ENABLED=true ouvre exec_query. DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true ouvre get_sql_explain. Si ENABLE_SECURITY_CHECK=true, la couche de sécurité SQL MCP héritée peut toujours rejeter certaines requêtes SQL avant que Doris ne les voie. Définissez ENABLE_SECURITY_CHECK=false lorsque la politique prévue est de laisser le RBAC Doris décider pour SQL/DDL/DML.

L'OAuth adossé à Doris n'ouvre toujours pas les invites, ADBC, le profil/surveillance HTTP FE, l'audit/gouvernance ou l'analyse des performances dans cette phase, à moins que ces chemins ne soient acheminés séparément via des informations d'identification par utilisateur ou dotés d'un compte de service/admin explicite.

Limites opérationnelles actuelles

L'OAuth adossé à Doris est actuellement monoprocessus et mono-worker :

WORKERS=1 est requis. WORKERS=0 s'étend au nombre de CPU et échoue lorsque l'OAuth adossé à Doris est activé.
Les clients OAuth, les transactions d'autorisation, les codes d'autorisation, les tokens d'accès, les tokens de rafraîchissement et les clients DCR sont uniquement en mémoire et locaux au processus.
Les pools de connexions Doris par utilisateur sont locaux au processus.
Le redémarrage du processus oblige les utilisateurs à se reconnecter.
Les tokens et les pools ne sont pas partagés entre les workers, les processus ou les nœuds.
La mise à l'échelle horizontale sans état et le déploiement multi-nœuds ne sont pas encore pris en charge pour l'OAuth adossé à Doris.

Si un token d'accès est autrement valide mais que son pool d'utilisateur Doris a disparu, la requête échoue avec connexion requise / DORIS_OAUTH_POOL_MISSING. Le serveur ne stocke pas les mots de passe Doris bruts pour la reconstruction automatique du pool.

Durcissement pour la production

Pour les déploiements en production :

Utilisez une DORIS_OAUTH_BASE_URL HTTPS pour toute adresse non locale.
Conservez DORIS_OAUTH_ALLOW_INSECURE_HTTP=false ; le http:// non local est rejeté sauf s'il est explicitement remplacé pour le développement.
Activez DORIS_OAUTH_TRUST_PROXY_HEADERS uniquement derrière un proxy inverse contrôlé et définissez DORIS_OAUTH_TRUSTED_PROXY_CIDRS.
Gardez les limites de débit de connexion, d'autorisation, de token, de rafraîchissement, de révocation et de DCR activées.
Utilisez le RBAC Doris comme limite d'autorisation finale des données et n'accordez aux utilisateurs Doris que les données qu'ils doivent inspecter.
Ne journalisez pas les mots de passe Doris, les en-têtes d'autorisation, les tokens d'accès, les tokens de rafraîchissement, les codes d'autorisation, les vérificateurs PKCE ou les secrets client.
Traitez le préfixe doa_ comme réservé aux tokens d'accès OAuth adossés à Doris ; les tokens statiques et les valeurs de porteur JWT ne doivent pas l'utiliser.
Gardez l'enregistrement dynamique des clients en auto pour le développement en boucle locale ou configurez explicitement le DCR de production avec ENABLE_DORIS_OAUTH_PRODUCTION_DCR=true.

Configuration de base de données liée au token (Nouveau dans la v0.6.0)

Créez un fichier tokens.json pour une gestion avancée des tokens avec liaison à la base de données :

{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "customer-a-token",
      "token": "customer_a_secure_token_12345",
      "description": "Customer A dedicated database access",
      "expires_hours": null,
      "is_active": true,
      "database_config": {
        "host": "customer-a-db.example.com",
        "port": 9030,
        "user": "customer_a_user",
        "password": "secure_password",
        "database": "customer_a_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    },
    {
      "token_id": "customer-b-token", 
      "token": "customer_b_secure_token_67890",
      "description": "Customer B dedicated database access",
      "expires_hours": 720,
      "is_active": true,
      "database_config": {
        "host": "customer-b-db.example.com",
        "port": 9030,
        "user": "customer_b_user", 
        "password": "secure_password",
        "database": "customer_b_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    }
  ]
}

Mises à jour de configuration par rechargement à chaud (Nouveau dans la v0.6.0)

Le système détecte et applique automatiquement les modifications de configuration :

Détection automatique : Surveillance de la modification des fichiers toutes les 10 secondes
Validation instantanée : Validation immédiate de la configuration de la base de données pour les nouveaux tokens
Zéro temps d'arrêt : Mises à jour de la configuration sans interruption de service
Protection contre le retour en arrière : Retour automatique en cas d'erreurs de configuration
Piste d'audit : Journalisation complète des modifications de configuration

Exemple d'authentification par token

# Client authentication with token
auth_info = {
    "type": "token",
    "token": "your_jwt_token",
    "session_id": "unique_session_id"
}

Exemple d'authentification de base

# Client authentication with username/password
auth_info = {
    "type": "basic",
    "username": "analyst",
    "password": "secure_password",
    "session_id": "unique_session_id"
}

Autorisation et niveaux de sécurité

Le système prend en charge quatre niveaux de sécurité avec un contrôle d'accès hiérarchique :

Niveau de sécurité	Portée d'accès	Cas d'utilisation typiques
Public	Accès sans restriction	Rapports publics, statistiques générales
Interne	Employés de l'entreprise	Tableaux de bord internes, métriques commerciales
Confidentiel	Personnel autorisé	Données clients, rapports financiers
Secret	Direction générale	Données stratégiques, analyses sensibles

Configuration des rôles

Configurez les rôles et les permissions des utilisateurs :

# Example role configuration
role_permissions = {
    "data_analyst": {
        "security_level": "internal",
        "permissions": ["read_data", "execute_query"],
        "allowed_tables": ["sales", "products", "orders"]
    },
    "data_admin": {
        "security_level": "confidential", 
        "permissions": ["read_data", "execute_query", "admin"],
        "allowed_tables": ["*"]
    },
    "executive": {
        "security_level": "secret",
        "permissions": ["read_data", "execute_query", "admin"],
        "allowed_tables": ["*"]
    }
}

Validation de la sécurité SQL

Le système valide automatiquement les requêtes SQL pour les risques de sécurité :

Opérations bloquées

Configurez les opérations SQL bloquées à l'aide de variables d'environnement (Nouveau dans la v0.4.2) :

# Enable/disable SQL security check (New in v0.4.2)
ENABLE_SECURITY_CHECK=true

# Customize blocked keywords via environment variable (New in v0.4.2)
BLOCKED_KEYWORDS="DROP,DELETE,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL"

# Maximum query complexity score
MAX_QUERY_COMPLEXITY=100

Mots-clés bloqués par défaut (Unifiés dans la v0.4.2) :

Opérations DDL : DROP, CREATE, ALTER, TRUNCATE
Opérations DML : DELETE, INSERT, UPDATE
Opérations DCL : GRANT, REVOKE
Opérations système : EXEC, EXECUTE, SHUTDOWN, KILL

Protection contre les injections SQL

Le système détecte et bloque automatiquement :

Injections basées sur UNION : attaques UNION SELECT
Injections booléennes : motifs OR 1=1
Injections temporelles : fonctions SLEEP(), WAITFOR
Injections de commentaires : motifs --, /**/
Requêtes empilées : Instructions multiples séparées par ;

Exemple de validation de sécurité

# This query would be blocked
dangerous_sql = "SELECT * FROM users WHERE id = 1; DROP TABLE users;"

# This query would be allowed
safe_sql = "SELECT name, email FROM users WHERE department = 'sales'"

Configuration du masquage des données

Configurez le masquage automatique des données pour les informations sensibles :

Règles de masquage intégrées

# Default masking rules
masking_rules = [
    {
        "column_pattern": r".*phone.*|.*mobile.*",
        "algorithm": "phone_mask",
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 3,
            "keep_suffix": 4
        },
        "security_level": "internal"
    },
    {
        "column_pattern": r".*email.*", 
        "algorithm": "email_mask",
        "parameters": {"mask_char": "*"},
        "security_level": "internal"
    },
    {
        "column_pattern": r".*id_card.*|.*identity.*",
        "algorithm": "id_mask", 
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 6,
            "keep_suffix": 4
        },
        "security_level": "confidential"
    }
]

Algorithmes de masquage

Algorithme	Description	Exemple
`phone_mask`	Masque les numéros de téléphone	`138****5678`
`email_mask`	Masque les adresses e-mail	`j***[email protected]`
`id_mask`	Masque les numéros de carte d'identité	`110101****1234`
`name_mask`	Masque les noms personnels	`张*明`
`partial_mask`	Masquage partiel avec ratio	`abc***xyz`

Règles de masquage personnalisées

Ajoutez des règles de masquage personnalisées dans votre configuration :

# Custom masking rule
custom_rule = {
    "column_pattern": r".*salary.*|.*income.*",
    "algorithm": "partial_mask",
    "parameters": {
        "mask_char": "*",
        "mask_ratio": 0.6
    },
    "security_level": "confidential"
}

Exemples de configuration de sécurité

Variables d'environnement

# .env file
AUTH_TYPE=token
TOKEN_SECRET=your_jwt_secret_key
ENABLE_MASKING=true
MAX_RESULT_ROWS=10000
BLOCKED_SQL_OPERATIONS=DROP,DELETE,TRUNCATE,ALTER
MAX_QUERY_COMPLEXITY=100
ENABLE_AUDIT=true

Configuration des tables sensibles

# Configure sensitive tables with security levels
sensitive_tables = {
    "user_profiles": "confidential",
    "payment_records": "secret", 
    "employee_salaries": "secret",
    "customer_data": "confidential",
    "public_reports": "public"
}

Meilleures pratiques de sécurité

🔑 Authentification forte : Utilisez des tokens JWT avec une expiration appropriée
🎯 Principe du moindre privilège : Accordez les permissions minimales requises
🔍 Audit régulier : Activez la journalisation d'audit pour la surveillance de la sécurité
🛡️ Validation des entrées : Toutes les requêtes SQL sont automatiquement validées
🎭 Classification des données : Classez correctement les données avec des niveaux de sécurité
🔄 Mises à jour régulières : Maintenez les règles et configurations de sécurité à jour
Durcissement OAuth adossé à Doris : Utilisez HTTPS, gardez l'OAuth externe désactivé dans ce mode, conservez WORKERS=1, fiez-vous au RBAC Doris pour l'accès aux données du canal MySQL et exposez uniquement les opérations qui sont configurées et vérifiées pour utiliser les informations d'identification de l'utilisateur Doris connecté.

Surveillance de la sécurité

Le système fournit une surveillance complète de la sécurité :

# Security audit log example
{
    "timestamp": "2024-01-15T10:30:00Z",
    "user_id": "analyst_user",
    "action": "query_execution", 
    "resource": "customer_data",
    "result": "blocked",
    "reason": "insufficient_permissions",
    "risk_level": "medium"
}

⚠️ Important : Testez toujours les configurations de sécurité dans un environnement de développement avant de les déployer en production. Révisez et mettez à jour régulièrement les politiques de sécurité en fonction des exigences de votre organisation.

Connexion avec Cursor

Vous pouvez connecter Cursor à ce serveur MCP en utilisant le mode Stdio (recommandé) ou le mode HTTP Streamable.

Mode Stdio

Le mode Stdio permet à Cursor de gérer directement le processus du serveur. La configuration se fait dans le fichier de paramètres du serveur MCP de Cursor (généralement ~/.cursor/mcp.json ou similaire).

Méthode 1 : Utilisation de l'installation PyPI (Recommandée)

Installez le package depuis PyPI et configurez Cursor pour l'utiliser :

pip install doris-mcp-server

Configurer Cursor : Ajoutez une entrée similaire à la suivante dans votre configuration Cursor MCP :

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Méthode 2 : Utilisation de uv (Développement)

Si vous avez uv installé et souhaitez exécuter depuis les sources :

uv run --project /path/to/doris-mcp-server doris-mcp-server

Remarque : Remplacez /path/to/doris-mcp-server par le chemin absolu réel de votre répertoire de projet.

Configurer Cursor : Ajoutez une entrée similaire à la suivante dans votre configuration Cursor MCP :

{
  "mcpServers": {
    "doris-stdio": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/your/doris-mcp-server", "doris-mcp-server"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Mode HTTP Streamable

Le mode HTTP Streamable nécessite d'exécuter d'abord le serveur MCP de manière indépendante, puis de configurer Cursor pour s'y connecter.

Configurer .env : Assurez-vous que vos identifiants de base de données et tout autre paramètre nécessaire sont correctement configurés dans le fichier .env du répertoire du projet.
Démarrer le serveur : Exécutez le serveur depuis votre terminal dans le répertoire racine du projet :
```
./start_server.sh
```
Ce script lit le fichier .env et démarre le serveur FastAPI avec le support HTTP Streamable. Notez l'hôte et le port sur lesquels le serveur écoute (par défaut 0.0.0.0:3000).
Configurer Cursor : Ajoutez une entrée similaire à la suivante dans votre configuration Cursor MCP, pointant vers le point de terminaison HTTP Streamable du serveur en cours d'exécution :
```
{
  "mcpServers": {
    "doris-http": {
       "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```
Remarque : Ajustez l'hôte/port si votre serveur s'exécute sur une adresse différente. Le point de terminaison /mcp est l'interface HTTP Streamable unifiée.

Après avoir configuré l'un ou l'autre mode dans Cursor, vous devriez pouvoir sélectionner le serveur (par exemple, doris-stdio ou doris-http) et utiliser ses outils.

Connexion avec Kiro

Ou ajoutez ce qui suit à votre fichier de configuration Kiro MCP (~/.kiro/settings/mcp.json pour global, ou .kiro/settings/mcp.json pour la portée du projet). Consultez la documentation Kiro MCP pour plus de détails.

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Structure du répertoire

doris-mcp-server/
├── doris_mcp_server/           # Main server package
│   ├── main.py                 # Main entry point and FastAPI app
│   ├── multiworker_app.py      # Multi-worker application module (New in v0.6.0)
│   ├── auth/                   # Authentication modules (New in v0.6.0)
│   │   ├── token_manager.py    # Enterprise token management with hot reload
│   │   ├── jwt_manager.py      # JWT authentication provider
│   │   ├── oauth_provider.py   # OAuth authentication provider  
│   │   ├── oauth_handlers.py   # OAuth HTTP endpoint handlers
│   │   ├── token_handlers.py   # Token management HTTP endpoints
│   │   ├── auth_middleware.py  # Authentication middleware
│   │   └── __init__.py
│   ├── tools/                  # MCP tools implementation
│   │   ├── tools_manager.py    # Centralized tools management and registration
│   │   ├── resources_manager.py # Resource management and metadata exposure
│   │   ├── prompts_manager.py  # Intelligent prompt templates for data analysis
│   │   └── __init__.py
│   ├── utils/                  # Core utility modules
│   │   ├── config.py           # Configuration management with validation
│   │   ├── db.py               # Enhanced database connection management with token binding (Enhanced in v0.6.0)
│   │   ├── query_executor.py   # High-performance SQL execution with caching
│   │   ├── security.py         # Advanced security management and authentication (Enhanced in v0.6.0)
│   │   ├── schema_extractor.py # Metadata extraction with catalog federation
│   │   ├── analysis_tools.py   # Data analysis and performance monitoring
│   │   ├── data_governance_tools.py  # Data lineage and freshness monitoring (v0.5.0)
│   │   ├── data_quality_tools.py     # Comprehensive data quality analysis (v0.5.0)
│   │   ├── data_exploration_tools.py # Advanced statistical analysis (v0.5.0)
│   │   ├── security_analytics_tools.py # Access pattern analysis (v0.5.0)
│   │   ├── dependency_analysis_tools.py # Impact analysis and dependency mapping (v0.5.0)
│   │   ├── performance_analytics_tools.py # Query optimization and capacity planning (v0.5.0)
│   │   ├── adbc_query_tools.py       # High-performance Arrow Flight SQL operations (v0.5.0)
│   │   ├── logger.py           # Logging configuration
│   │   └── __init__.py
│   └── __init__.py
├── doris_mcp_client/           # MCP client implementation
│   ├── client.py               # Unified MCP client for testing and integration
│   ├── README.md               # Client documentation
│   └── __init__.py
├── logs/                       # Log files directory
├── tokens.json                 # Token configuration file (New in v0.6.0)
├── README.md                   # This documentation
├── RELEASE_NOTES_v0.6.0.md     # Release notes for v0.6.0
├── .env.example                # Environment variables template
├── requirements.txt            # Python dependencies
├── pyproject.toml              # Project configuration and entry points
├── uv.lock                     # UV package manager lock file
├── generate_requirements.py    # Requirements generation script
├── start_server.sh             # Server startup script
└── restart_server.sh           # Server restart script

Développement de nouveaux outils

Cette section décrit le processus d'ajout de nouveaux outils MCP au serveur Doris MCP, basé sur l'architecture modulaire unifiée avec gestion centralisée des outils.

1. Tirer parti des modules utilitaires existants

Le serveur fournit des modules utilitaires complets pour les opérations courantes de base de données :

doris_mcp_server/utils/db.py : Gestion des connexions à la base de données avec pool de connexions et surveillance de l'état.
doris_mcp_server/utils/query_executor.py : Exécution SQL haute performance avec mise en cache avancée, optimisation et surveillance des performances.
doris_mcp_server/utils/schema_extractor.py : Extraction de métadonnées avec support complet de fédération de catalogues.
doris_mcp_server/utils/security.py : Gestion complète de la sécurité, validation SQL et masquage des données.
doris_mcp_server/utils/analysis_tools.py : Outils avancés d'analyse de données et de statistiques.
doris_mcp_server/utils/config.py : Gestion de la configuration avec validation.
doris_mcp_server/utils/data_governance_tools.py : Suivi de la traçabilité des données et surveillance de la fraîcheur (Nouveau dans la v0.5.0).
doris_mcp_server/utils/data_quality_tools.py : Cadre complet d'analyse de la qualité des données (Nouveau dans la v0.5.0).
doris_mcp_server/utils/adbc_query_tools.py : Opérations Arrow Flight SQL haute performance (Nouveau dans la v0.5.0).

2. Implémenter la logique de l'outil

Ajoutez votre nouvel outil à la classe DorisToolsManager dans doris_mcp_server/tools/tools_manager.py. Le gestionnaire d'outils fournit une approche centralisée pour l'enregistrement et l'exécution des outils avec des interfaces unifiées.

Exemple : Ajout d'un nouvel outil d'analyse :

# In doris_mcp_server/tools/tools_manager.py

async def your_new_analysis_tool(self, arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
    """
    Your new analysis tool implementation
    
    Args:
        arguments: Tool arguments from MCP client
        
    Returns:
        List of MCP response messages
    """
    try:
        # Use existing utilities
        result = await self.query_executor.execute_sql_for_mcp(
            sql="SELECT COUNT(*) FROM your_table",
            max_rows=arguments.get("max_rows", 100)
        )
        
        return [{
            "type": "text",
            "text": json.dumps(result, ensure_ascii=False, indent=2)
        }]
        
    except Exception as e:
        logger.error(f"Tool execution failed: {str(e)}", exc_info=True)
        return [{
            "type": "text", 
            "text": f"Error: {str(e)}"
        }]

3. Enregistrer l'outil

Ajoutez votre outil à la méthode _register_tools dans la même classe :

# In the _register_tools method of DorisToolsManager

@self.mcp.tool(
    name="your_new_analysis_tool",
    description="Description of your new analysis tool",
    inputSchema={
        "type": "object",
        "properties": {
            "parameter1": {
                "type": "string",
                "description": "Description of parameter1"
            },
            "parameter2": {
                "type": "integer", 
                "description": "Description of parameter2",
                "default": 100
            }
        },
        "required": ["parameter1"]
    }
)
async def your_new_analysis_tool_wrapper(arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
    return await self.your_new_analysis_tool(arguments)

4. Fonctionnalités avancées

Pour des outils plus complexes, vous pouvez tirer parti du cadre complet :

Mise en cache avancée : Utilisez la mise en cache intégrée de l'exécuteur de requêtes pour des performances améliorées
Sécurité d'entreprise : Appliquez une validation SQL complète et un masquage des données via le gestionnaire de sécurité
Invites intelligentes : Utilisez le gestionnaire d'invites pour la génération avancée de requêtes
Gestion des ressources : Exposez les métadonnées via le gestionnaire de ressources
Surveillance des performances : Intégrez-vous aux outils d'analyse pour les capacités de surveillance

5. Tests

Testez votre nouvel outil en utilisant le client MCP inclus :

# Using doris_mcp_client/client.py
from doris_mcp_client.client import DorisUnifiedMCPClient

async def test_new_tool():
    client = DorisUnifiedMCPClient()
    result = await client.call_tool("your_new_analysis_tool", {
        "parameter1": "test_value",
        "parameter2": 50
    })
    print(result)

Client MCP

Le projet inclut un client MCP unifié (doris_mcp_client/) à des fins de test et d'intégration. Le client prend en charge plusieurs modes de connexion et fournit une interface pratique pour interagir avec le serveur MCP.

Pour une documentation détaillée du client, voir doris_mcp_client/README.md.

Contribution

Les contributions sont les bienvenues via des Issues ou des Pull Requests.

Licence

Ce projet est sous licence Apache 2.0. Voir le fichier LICENSE pour plus de détails.

FAQ

Q : Pourquoi Qwen3-32b et d'autres modèles à petits paramètres échouent-ils toujours lors de l'appel d'outils ?

R : C'est un problème courant. La raison principale est que ces modèles ont besoin de conseils plus explicites pour utiliser correctement les outils MCP. Il est recommandé d'ajouter l'invite d'instruction suivante pour le modèle :

Version chinoise :

<instruction>
尽可能使用MCP工具完成任务，仔细阅读每个工具的注解、方法名、参数说明等内容。请按照以下步骤操作：

1. 仔细分析用户的问题，从已有的Tools列表中匹配最合适的工具。
2. 确保工具名称、方法名和参数完全按照工具注释中的定义使用，不要自行创造工具名称或参数。
3. 传入参数时，严格遵循工具注释中规定的参数格式和要求。
4. 调用工具时，根据需要直接调用工具，但参数请求参考以下请求格式：{"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. 输出结果时，不要包含任何XML标签，仅返回纯文本内容。

<input>
用户问题：user_query
</input>

<output>
返回工具调用结果或最终答案，以及对结果的分析。
</output>
</instruction>

Version anglaise :

<instruction>
Use MCP tools to complete tasks as much as possible. Carefully read the annotations, method names, and parameter descriptions of each tool. Please follow these steps:

1. Carefully analyze the user's question and match the most appropriate tool from the existing Tools list.
2. Ensure tool names, method names, and parameters are used exactly as defined in the tool annotations. Do not create tool names or parameters on your own.
3. When passing parameters, strictly follow the parameter format and requirements specified in the tool annotations.
4. When calling tools, call them directly as needed, but refer to the following request format for parameters: {"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. When outputting results, do not include any XML tags, return plain text content only.

<input>
User question: user_query
</input>

<output>
Return tool call results or final answer, along with analysis of the results.
</output>
</instruction>

Si vous avez d'autres exigences concernant les résultats retournés, vous pouvez décrire les exigences spécifiques dans la balise <output>.

Q : Comment configurer différentes connexions de base de données ?

R : Vous pouvez configurer les connexions de base de données de plusieurs manières :

Variables d'environnement (Recommandé) :

export DORIS_HOST="your_doris_host"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

Arguments de ligne de commande :

doris-mcp-server --db-host your_host --db-port 9030 --db-user root --db-password your_password

Fichier de configuration : Modifiez les éléments de configuration correspondants dans le fichier .env.

Q : Comment configurer les nœuds BE pour les outils de surveillance ?

R : Choisissez la configuration appropriée en fonction de votre scénario de déploiement :

Réseau externe (Configuration manuelle) :

# Manually specify BE node addresses
DORIS_BE_HOSTS=10.1.1.100,10.1.1.101,10.1.1.102
DORIS_BE_WEBSERVER_PORT=8040

Réseau interne (Découverte automatique) :

# Leave BE_HOSTS empty for auto-discovery
# DORIS_BE_HOSTS=  # Not set or empty
# System will use 'SHOW BACKENDS' command to get internal IPs

Q : Comment utiliser les fichiers SQL Explain/Profile avec un LLM pour l'optimisation ?

R : Les outils fournissent à la fois du contenu tronqué et des fichiers complets pour l'analyse par LLM :

Obtenir les résultats d'analyse :

{
  "content": "Truncated plan for immediate review",
  "file_path": "/tmp/explain_12345.txt",
  "is_content_truncated": true
}

Flux de travail d'analyse LLM :
- Examinez le contenu tronqué pour des aperçus rapides
- Téléchargez le fichier complet vers votre LLM en tant que pièce jointe
- Demandez des suggestions d'optimisation ou une analyse des performances
- Implémentez les améliorations recommandées

Configurer la taille du contenu :

MAX_RESPONSE_CONTENT_SIZE=4096  # Adjust as needed

Q : Comment activer les fonctionnalités de sécurité et de masquage des données ?

R : Définissez les configurations suivantes dans votre fichier .env :

# Enable data masking
ENABLE_MASKING=true
# Set authentication type
AUTH_TYPE=token
# Configure token secret
TOKEN_SECRET=your_secret_key
# Set maximum result rows
MAX_RESULT_ROWS=10000

Q : Quelle est la différence entre le mode Stdio et le mode HTTP ?

R :

Mode Stdio : Convient à l'intégration directe avec les clients MCP (comme Cursor), où le client gère le processus du serveur
Mode HTTP : Service web indépendant qui prend en charge plusieurs connexions client, adapté aux environnements de production

Recommandations :

Développement et usage personnel : Mode Stdio
Production et environnements multi-utilisateurs : Mode HTTP

Q : Comment résoudre les problèmes de délai de connexion ?

R : Essayez les solutions suivantes :

Augmenter les paramètres de délai :

# Set in .env file
QUERY_TIMEOUT=60
CONNECTION_TIMEOUT=30

Vérifier la connectivité réseau :

# Test database connection
curl http://localhost:3000/health

Optimiser la configuration du pool de connexions :
```
DORIS_MAX_CONNECTIONS=20
```

Q : Comment résoudre les erreurs de connexion `at_eof` ? (Complètement corrigé dans la v0.5.0)

R : La version 0.5.0 a complètement résolu les erreurs de connexion critiques at_eof grâce à une refonte complète du pool de connexions :

Le problème :

Les erreurs at_eof se produisaient en raison de la pré-création du pool de connexions et d'une gestion incorrecte de l'état des connexions
L'état du lecteur MySQL aiomysql devenait incohérent pendant le cycle de vie de la connexion
Instabilité du pool de connexions sous charge concurrente

La solution (v0.5.0) :

Refonte de la stratégie du pool de connexions :
- Zéro connexion minimale : Changement de min_connections de la valeur par défaut à 0 pour éviter les problèmes de pré-création
- Création de connexion à la demande : Les connexions sont créées uniquement lorsque nécessaire, éliminant les problèmes de connexions périmées
- Stratégie de connexion fraîche : Acquisition systématique de connexions fraîches du pool, sans mise en cache au niveau de la session
Surveillance de l'état améliorée :
- Vérifications de l'état basées sur le délai : Délai de 3 secondes pour les requêtes de validation de connexion
- Moniteur d'état en arrière-plan : Surveillance continue de l'état du pool toutes les 30 secondes
- Détection proactive des connexions périmées : Détection et nettoyage automatiques des connexions problématiques
Système de récupération intelligent :
- Récupération automatique du pool : Pool auto-réparateur avec gestion complète des erreurs
- Nouvelle tentative avec backoff exponentiel : Mécanisme de nouvelle tentative intelligent avec jusqu'à 3 tentatives
- Détection d'erreur spécifique à la connexion : Identification précise des erreurs liées à la connexion
Optimisations des performances :
- Préchauffage du pool : Préchauffage intelligent du pool de connexions pour des performances optimales
- Nettoyage en arrière-plan : Nettoyage périodique des connexions périmées sans affecter les opérations actives
- Diagnostics de connexion : Surveillance et rapport en temps réel de l'état des connexions

Surveillance de l'état des connexions :

# Monitor connection pool health in real-time
tail -f logs/doris_mcp_server_info.log | grep -E "(pool|connection|at_eof)"

# Check detailed connection diagnostics
tail -f logs/doris_mcp_server_debug.log | grep "connection health"

# View connection pool metrics
curl http://localhost:8000/health  # If running in HTTP mode

Configuration pour des performances de connexion optimales :

# Recommended connection pool settings in .env
DORIS_MAX_CONNECTIONS=20          # Adjust based on workload
CONNECTION_TIMEOUT=30             # Connection establishment timeout
QUERY_TIMEOUT=60                  # Query execution timeout

# Health monitoring settings
HEALTH_CHECK_INTERVAL=60          # Pool health check frequency

Résultat : Élimination à 99,9 % des erreurs at_eof avec une stabilité et des performances de connexion considérablement améliorées.

Q : Comment résoudre les problèmes de compatibilité de version de la bibliothèque MCP ? (Corrigé dans la v0.4.2)

R : La version 0.4.2 a introduit une couche de compatibilité MCP intelligente qui prend en charge les versions MCP 1.8.x et 1.9.x :

Le problème :

MCP 1.9.3 a introduit des changements cassants dans la classe RequestContext (passage de 2 à 3 paramètres génériques)
Cela provoquait des erreurs TypeError: Too few arguments for RequestContext

La solution (v0.4.2) :

Détection intelligente de version : Détecte automatiquement la version MCP installée
Couche de compatibilité : Gère élégamment les différences d'API entre les versions
Support de version flexible : mcp>=1.8.0,<2.0.0 dans les dépendances

Versions MCP prises en charge :

# Both versions now work seamlessly
pip install mcp==1.8.0  # Stable version (recommended)
pip install mcp==1.9.3  # Latest version with new features

Informations de version :

# Check which MCP version is being used
doris-mcp-server --transport stdio
# The server will log: "Using MCP version: x.x.x"

Si vous rencontrez des erreurs de démarrage liées à MCP :

# Recommended: Use stable version
pip uninstall mcp
pip install mcp==1.8.0

# Or upgrade to latest compatible version
pip install --upgrade doris-mcp-server==0.5.0

Q : Comment activer les fonctionnalités haute performance ADBC ? (Nouveau dans la v0.5.0)

R : ADBC (Arrow Flight SQL) offre des améliorations de performances de 3 à 10 fois pour les grands ensembles de données :

Dépendances ADBC (automatiquement incluses dans la v0.5.0+) :

# ADBC dependencies are now included by default in doris-mcp-server>=0.5.0
# No separate installation required

Configurer les ports Arrow Flight SQL :

# Add to your .env file
FE_ARROW_FLIGHT_SQL_PORT=8096
BE_ARROW_FLIGHT_SQL_PORT=8097

Personnalisation ADBC optionnelle :

# Customize ADBC behavior (optional)
ADBC_DEFAULT_MAX_ROWS=200000
ADBC_DEFAULT_TIMEOUT=120
ADBC_DEFAULT_RETURN_FORMAT=pandas  # arrow/pandas/dict

Tester la connexion ADBC :

# Use get_adbc_connection_info tool to verify setup
# Should show "status": "ready" and port connectivity

Q : Comment utiliser les nouveaux outils d'analyse de données ? (Nouveau dans la v0.5.0)

R : Les 7 nouveaux outils d'analyse fournissent des capacités complètes de gouvernance des données :

Analyse de la qualité des données :

{
  "tool_name": "analyze_data_quality",
  "arguments": {
    "table_name": "customer_data",
    "analysis_scope": "comprehensive",
    "sample_size": 100000
  }
}

Suivi de la traçabilité des colonnes :

{
  "tool_name": "trace_column_lineage", 
  "arguments": {
    "target_columns": ["users.email", "orders.customer_id"],
    "analysis_depth": 3
  }
}

Surveillance de la fraîcheur des données :

{
  "tool_name": "monitor_data_freshness",
  "arguments": {
    "freshness_threshold_hours": 24,
    "include_update_patterns": true
  }
}

Analyse des performances :

{
  "tool_name": "analyze_slow_queries_topn",
  "arguments": {
    "days": 7,
    "top_n": 20,
    "include_patterns": true
  }
}

Q : Comment utiliser le système de journalisation amélioré ? (Amélioré dans la v0.5.0)

R : La version 0.5.0 introduit un système de journalisation complet avec gestion automatique et organisation par niveau :

Structure des fichiers journaux (Nouveau dans la v0.5.0) :

logs/
├── doris_mcp_server_debug.log      # DEBUG level messages
├── doris_mcp_server_info.log       # INFO level messages  
├── doris_mcp_server_warning.log    # WARNING level messages
├── doris_mcp_server_error.log      # ERROR level messages
├── doris_mcp_server_critical.log   # CRITICAL level messages
├── doris_mcp_server_all.log        # Combined log (all levels)
└── doris_mcp_server_audit.log      # Audit trail (separate)

Fonctionnalités de journalisation améliorées :

Séparation des fichiers par niveau : Organisation automatique par niveau de journalisation pour un dépannage plus facile
Formatage horodaté : Précision à la milliseconde avec alignement approprié pour une journalisation professionnelle
Rotation automatique des journaux : Empêche les problèmes d'espace disque avec des limites de taille de fichier configurables
Nettoyage en arrière-plan : Planificateur de nettoyage intelligent avec politiques de rétention configurables
Piste d'audit : Journalisation d'audit séparée pour la conformité et la surveillance de la sécurité

Visualisation des journaux :

# View real-time logs by level
tail -f logs/doris_mcp_server_info.log     # General operational info
tail -f logs/doris_mcp_server_error.log    # Error tracking
tail -f logs/doris_mcp_server_debug.log    # Detailed debugging

# View all activity in combined log
tail -f logs/doris_mcp_server_all.log

# Monitor specific operations
tail -f logs/doris_mcp_server_info.log | grep -E "(query|connection|tool)"

# View audit trail
tail -f logs/doris_mcp_server_audit.log

Configuration :

# Enhanced logging configuration in .env
LOG_LEVEL=INFO                         # Base log level
ENABLE_AUDIT=true                      # Enable audit logging
ENABLE_LOG_CLEANUP=true                # Enable automatic cleanup
LOG_MAX_AGE_DAYS=30                    # Keep logs for 30 days
LOG_CLEANUP_INTERVAL_HOURS=24          # Check for cleanup daily

# Advanced settings
LOG_FILE_PATH=logs                     # Log directory (auto-organized)

Dépannage avec les journaux améliorés :

# Debug connection issues
grep -E "(connection|pool|at_eof)" logs/doris_mcp_server_error.log

# Monitor tool performance
grep "execution_time" logs/doris_mcp_server_info.log

# Check system health
tail -20 logs/doris_mcp_server_warning.log

# View recent critical issues
cat logs/doris_mcp_server_critical.log

Gestion du nettoyage des journaux :

Automatique : Le planificateur en arrière-plan supprime les fichiers plus anciens que LOG_MAX_AGE_DAYS
Manuel : Les journaux sont automatiquement pivotés lorsqu'ils atteignent 10 Mo
Sauvegarde : Conserve 5 fichiers de sauvegarde pour chaque niveau de journalisation
Performance : Impact minimal sur les performances du serveur

Q : Comment utiliser la nouvelle configuration de base de données liée aux jetons ? (Nouveau dans la v0.6.0)

R : La configuration révolutionnaire de base de données liée aux jetons permet à chaque jeton de transporter ses propres paramètres de connexion à la base de données pour un accès multi-tenant sécurisé :

Activer l'authentification par jeton :

# In your .env file
ENABLE_TOKEN_AUTH=true
TOKEN_HOT_RELOAD=true
TOKEN_FILE_PATH=tokens.json

Créer la configuration tokens.json :

{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "tenant-alpha",
      "token": "tenant_alpha_secure_token_123",
      "description": "Tenant Alpha database access",
      "expires_hours": null,
      "is_active": true,
      "database_config": {
        "host": "tenant-alpha-db.company.com",
        "port": 9030,
        "user": "alpha_user",
        "password": "secure_password",
        "database": "alpha_analytics",
        "charset": "UTF8"
      }
    }
  ]
}

Priorité de configuration (Nouveauté v0.6.0) :
- Configuration BD liée au jeton (priorité la plus élevée)
- Variables d'environnement (.env)
- Erreur si aucune n'est disponible
Avantages du rechargement à chaud :
- Ajouter de nouveaux locataires sans redémarrer le service
- Mettre à jour les identifiants de base de données en temps réel
- Validation automatique et retour arrière en cas d'erreur
- Piste d'audit complète des modifications

Utilisation multi-tenant :

# Different tokens access different databases automatically
curl -H "Authorization: Bearer tenant_alpha_secure_token_123" http://localhost:3000/mcp
curl -H "Authorization: Bearer tenant_beta_secure_token_456" http://localhost:3000/mcp

Q : En quoi l'OAuth adossé à Doris diffère-t-il de l'OAuth/OIDC externe ?

R : L'OAuth/OIDC externe délègue l'identité à un fournisseur externe tel que Google, Azure AD, GitHub, GitLab ou Keycloak. L'OAuth adossé à Doris est émis par ce serveur MCP après que l'utilisateur s'est connecté avec les identifiants Doris. Le serveur valide le nom d'utilisateur/mot de passe Doris, crée un pool de connexions Doris par utilisateur, émet des jetons d'accès et de rafraîchissement doa_, et laisse le RBAC Doris décider des données et métadonnées auxquelles cet utilisateur peut accéder.

Ces modes sont mutuellement exclusifs sur une même URL MCP. N'activez pas ENABLE_DORIS_OAUTH_AUTH=true avec ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true ou AUTH_TYPE=oauth ; le démarrage échoue rapidement si les deux modes OAuth sont configurés.

L'OAuth adossé à Doris expose actuellement les ressources MCP avec le cache de métadonnées des ressources désactivé. Il expose les outils de métadonnées examinés lorsque DORIS_OAUTH_DB_TOOLS_ENABLED=true, exec_query lorsque DORIS_OAUTH_QUERY_TOOLS_ENABLED=true, et l'explication SQL lorsque DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true. Les clients normaux n'ont pas besoin de passer une longue liste de scopes ; l'omission du scope OAuth accorde l'enveloppe de capacité OAuth Doris configurée. Le RBAC Doris reste le backend d'autorisation final des données pour ces opérations du canal MySQL.

Q : L'OAuth adossé à Doris peut-il fonctionner avec plusieurs workers ou plusieurs nœuds ?

R : Pas dans l'implémentation actuelle. L'OAuth adossé à Doris utilise un stockage OAuth en mémoire uniquement et des pools Doris locaux au processus par utilisateur. Les jetons d'accès, les jetons de rafraîchissement, les codes d'autorisation, les clients DCR et les pools ne sont pas partagés entre les workers, les processus ou les nœuds.

Utilisez WORKERS=1 avec l'OAuth adossé à Doris. WORKERS=0 s'étend au nombre de CPU et échoue car cela créerait plusieurs workers effectifs. La mise à l'échelle horizontale sans état, le stockage partagé des jetons, les identifiants Doris chiffrés partagés, la récupération de session persistante et la reconstruction des pools sont des conceptions futures, pas des capacités actuelles.

Q : Comment fonctionne le rechargement à chaud et est-il sûr ? (Nouveauté v0.6.0)

R : Le système de rechargement à chaud est conçu pour les environnements de production d'entreprise avec des mesures de sécurité complètes :

Comment ça fonctionne :

Surveillance de fichier : Vérifie tokens.json toutes les 10 secondes pour les modifications
Validation immédiate : Les nouveaux jetons sont validés, y compris la connectivité à la base de données
Mises à jour atomiques : Mises à jour de configuration tout ou rien
Protection par retour arrière : Retour arrière automatique si une validation de jeton échoue

Fonctionnalités de sécurité :

Sauvegarde et restauration : Configuration actuelle sauvegardée avant les modifications
Test de connexion : Connexions à la base de données testées avant d'appliquer les modifications
Isolation des erreurs : Les jetons invalides n'affectent pas les jetons valides existants
Journalisation d'audit : Piste complète de tous les changements de configuration

Meilleures pratiques :

# Monitor hot reload activity
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

# Test configuration before applying
cp tokens.json tokens.json.backup
# Make changes to tokens.json
# System will automatically validate and apply or rollback

Q : Comment gérer le cycle de vie et la sécurité des jetons ? (Nouveauté v0.6.0)

R : La gestion des jetons utilise une approche sécurisée basée sur des fichiers avec des points de terminaison administratifs optionnels dotés de contrôles de sécurité complets.

Méthode principale de gestion des jetons (recommandée) :

# 1. Edit tokens.json file directly (safest method)
nano tokens.json

# 2. Hot reload will automatically detect changes
# No server restart required - changes applied within 10 seconds

# 3. Monitor hot reload in logs
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

Points de terminaison administratifs (sécurisés, accès local uniquement) :

🛡️ SÉCURITÉ : Ces points de terminaison sont protégés par des contrôles de sécurité complets et sont désactivés par défaut.

# Security Requirements (ALL must be met):
# ✓ HTTP token management explicitly enabled in configuration
# ✓ Access only from localhost (127.0.0.1/::1) - IP restrictions enforced
# ✓ Valid admin authentication token required
# ✓ Admin authentication enabled in configuration

# Enable HTTP token management (disabled by default)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token
export REQUIRE_ADMIN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

# Access with proper authentication
curl -H "Authorization: Bearer your_secure_admin_token" http://127.0.0.1:3000/token/stats

# Demo page (local access only, with authentication)
# Access: http://127.0.0.1:3000/token/demo

Flux de travail recommandé pour la gestion des jetons :

Développement/Test :

// tokens.json
{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "dev-token",
      "token": "dev_secure_token_123",
      "description": "Development environment access",
      "expires_hours": 24,
      "is_active": true
    }
  ]
}

Déploiement en production :

# Use secure token generation
openssl rand -hex 32  # Generate secure token

# Store in secure configuration management
# Never commit tokens to version control
# Use environment variables for sensitive tokens

Fonctionnalités de sécurité :

Gestion basée sur des fichiers : Gestion principale via des fichiers de configuration sécurisés
Rechargement à chaud : Mises à jour automatiques de la configuration sans interruption de service
Hachage des jetons : Jetons stockés en interne sous forme de hachages SHA-256
Piste d'audit : Journalisation complète de toutes les opérations et modifications de jetons
Gestion de l'expiration : Nettoyage automatique des jetons expirés
Admin local uniquement : Points de terminaison de gestion restreints à l'accès localhost
Validation de la configuration : Validation immédiate des configurations de jetons et de base de données

Meilleures pratiques de sécurité :

Toujours gérer les jetons via des fichiers de configuration sécurisés
Ne jamais exposer les points de terminaison de gestion des jetons aux réseaux externes
Utiliser des jetons forts et générés aléatoirement pour la production
Mettre en œuvre des permissions de fichier appropriées pour tokens.json (600 ou 640)
Auditer régulièrement les jetons actifs et leurs modèles d'utilisation
Surveiller les journaux de rechargement à chaud pour les modifications de configuration non autorisées

Pour d'autres problèmes, veuillez consulter les Issues GitHub ou soumettre une nouvelle issue.