Présentation détaillée du projet Apache Doris MCP Server

Aperçu du projet

Apache Doris MCP (Model Context Protocol) Server est un service backend basé sur Python et FastAPI, conçu pour s'intégrer de manière transparente avec la base de données Apache Doris via le protocole de contexte de modèle (MCP). Il fournit une interface standardisée aux agents et clients d'IA, prenant en charge des fonctionnalités telles que la conversion du langage naturel en SQL (NL2SQL), l'exécution de requêtes SQL, la gestion des métadonnées et l'analyse de données. Ce projet est une extension importante de la communauté Apache Doris, particulièrement adaptée aux scénarios commerciaux nécessitant une interaction de données efficace et une analyse intelligente.

Depuis la publication de la version 0.3.0 en 2025, le projet a subi une mise à jour architecturale majeure, passant d'une communication basée sur SSE (Server-Sent Events) à un protocole HTTP Streamable unifié, et a ajouté un cadre de sécurité de niveau entreprise et des fonctionnalités d'optimisation des performances. L'objectif principal du projet est de relier les systèmes d'IA et la base de données Apache Doris via le protocole MCP, afin de réaliser une exploration et une analyse de données intelligentes.

Fonctionnalités principales

Apache Doris MCP Server offre les principales fonctionnalités suivantes :

1. Conversion du langage naturel en SQL (NL2SQL)

   • Prend en charge la génération de requêtes SQL à partir d'entrées en langage naturel, en combinant des modèles de langage de grande taille (LLM) pour une génération de requêtes intelligente.
   • Adapté aux scénarios où les utilisateurs métiers peuvent interroger des données sans avoir à écrire des requêtes SQL complexes.

2. Exécution de requêtes SQL

   • Prend en charge l'exécution directe de commandes SQL via l'outil exec_query, avec la possibilité de personnaliser la sélection de la base de données, la limite du nombre de lignes et les paramètres de délai d'attente.
   • Intègre des contrôles de sécurité (tels que la protection contre les injections SQL) et l'ajout automatique de LIMIT, garantissant la sécurité et l'efficacité des requêtes.

3. Gestion des métadonnées

   • Fournit de riches outils d'extraction de métadonnées, notamment :
     • Liste de toutes les bases de données et tables (get_all_databases, get_database_tables).
     • Obtention de la structure de la table, des commentaires et des informations d'index (get_table_schema, get_table_comment, get_column_comments, get_table_indexes).
     • Prise en charge de la découverte de plusieurs catalogues (get_catalog_list).

4. Requête des journaux d'audit

   • Obtention des enregistrements d'audit récents via get_recent_audit_logs, avec prise en charge de la personnalisation de la plage de temps et de la limite d'enregistrements.

5. Cadre de sécurité de niveau entreprise

   • Prend en charge plusieurs méthodes d'authentification (Token, Basic Auth, OAuth).
   • Contrôle d'accès basé sur les rôles (RBAC), offrant quatre niveaux de sécurité.
   • Intègre la protection contre les injections SQL, la validation des requêtes et la fonctionnalité de dé-sensibilisation des données.

6. Optimisation des performances

   • Optimisation de l'exécution des requêtes, amélioration des performances grâce à des mécanismes de cache améliorés et à la gestion du pool de connexions.
   • Prend en charge la surveillance des performances et l'analyse statistique (performance_stats).

7. Modes de communication multiples

   • HTTP Streamable : Prend en charge les requêtes/réponses et la transmission en flux via un point de terminaison /mcp unifié (src/streamable_server.py).
   • SSE (obsolète) : Les versions antérieures prenaient en charge la communication via les points de terminaison /sse et /mcp/messages (src/sse_server.py).
   • Stdio (facultatif) : Interaction via l'entrée/sortie standard (src/stdio_server.py).

8. Fonctionnalités expérimentales

   • Analyse statistique des colonnes (column_analysis), fournissant des informations sur les données.
   • Prise en charge de la fédération de catalogues, adaptée aux environnements multi-catalogues.

Architecture technique

La conception de l'architecture du projet est modulaire et efficace, comprenant principalement les composants suivants :

• Cadre principal : Basé sur Python 3.12 et FastAPI, fournissant un service API haute performance.
• Implémentation du protocole MCP :
  • Fournit des interfaces standardisées pour l'appel d'outils, la gestion des ressources et l'interaction avec les invites.
  • Traite toutes les requêtes via un point de terminaison /mcp unifié, simplifiant l'intégration.
• Interaction avec la base de données :
  • doris_mcp_server/utils/db.py : Fournit des fonctions de connexion à la base de données (get_db_connection) et d'exécution de requêtes (execute_query, execute_query_df).
  • doris_mcp_server/utils/schema_extractor.py : La classe MetadataExtractor est responsable de l'extraction des métadonnées, y compris les mécanismes de cache.
  • doris_mcp_server/utils/sql_executor_tools.py : La fonction execute_sql_query encapsule la logique de requête, y compris les contrôles de sécurité et la sérialisation des résultats.
• Gestion de la sécurité :
  • Prend en charge plusieurs méthodes d'authentification et RBAC.
  • Fournit une protection contre les injections SQL, la validation des requêtes et l'enregistrement des journaux d'audit.
• Prise en charge du déploiement :
  • Déploiement via des images Docker, configuration unifiée des ports (3000, 3001, 3002).
  • Configuration des variables d'environnement (telles que DB_HOST, DB_PORT, DB_USER, DB_PASSWORD).

Évolution de l'architecture : La version 0.3.0 a supprimé environ 300 lignes de code SSE hérité, migré vers HTTP Streamable, unifié la nomenclature des outils (suppression du préfixe mcp_doris_), et amélioré le niveau de modularité.

Installation et utilisation

Exigences environnementales

• Python 3.12 ou supérieur
• Base de données Apache Doris (connexion via le protocole MySQL)
• Outil de gestion des paquets (tel que uv ou pip)
• Facultatif : Docker (pour le déploiement conteneurisé)

Étapes d'installation

1. Cloner le dépôt :

   git clone https://github.com/apache/doris-mcp-server.git
   cd doris-mcp-server
   

2. Installer les dépendances : Utiliser uv (recommandé) ou pip pour l'installation :

   uv sync
   

   Ou

   pip install -r requirements.txt
   

3. Configurer les variables d'environnement : Créer un fichier .env ou définir directement les variables d'environnement :

   export DORIS_HOST=<doris-host>
   export DORIS_PORT=<port>
   export DORIS_USER=<doris-user>
   export DORIS_PASSWORD=<doris-pwd>
   export SERVER_PORT=3000
   

4. Démarrer le serveur :

   uv run --with mcp-doris --python 3.13 mcp-doris
   

   Ou

   python -m mcp_doris.mcp_server
   

5. Vérifier le démarrage : Une fois le démarrage réussi, vous pouvez interagir via un client MCP (tel que Cursor) ou un navigateur MCP intégré (http://localhost:5173).

Tester la connexion

Exécuter le script de test pour vérifier la connexion à la base de données :

python src/doris-mcp-server/test.py

Sortie attendue :

🚀 Doris MCP Server is starting...
[DorisConnector] Connected to 127.0.0.1:9030
✅ Database connection successful.
[DorisConnector] Connection closed.

Scénarios d'application

1. Analyse de données en temps réel

   • En combinant la fonctionnalité NL2SQL, les utilisateurs métiers peuvent interroger des données en temps réel en langage naturel, générer des rapports ou des tableaux de bord.
   • Adapté à la prise de décision en temps réel dans les secteurs de la vente au détail, de la finance, des télécommunications, etc.

2. Exploration des métadonnées

   • Les ingénieurs de données peuvent rapidement obtenir le schéma de la base de données, la structure des tables et les informations d'index, accélérant ainsi la modélisation et l'optimisation des données.

3. Business Intelligence pilotée par l'IA

   • Intégration d'agents d'IA (tels que Claude, Cursor), réalisation de flux de travail automatisés de requête et d'analyse de données via le protocole MCP.

4. Gestion de la conformité et de la sécurité

   • Le cadre de sécurité de niveau entreprise et les fonctions de journalisation d'audit répondent aux exigences des secteurs de la finance, de la santé, etc., en matière de sécurité et de conformité des données.

5. Environnement multi-catalogues

   • La prise en charge de la fédération de plusieurs catalogues convient à la gestion des métadonnées et aux requêtes dans les environnements d'entrepôts de données complexes.

Avantages et limites du projet

Avantages

• Intelligence : L'intégration de NL2SQL et LLM réduit la barrière à l'entrée pour l'interrogation de données.
• Sécurité : L'authentification multiple, RBAC et la protection SQL garantissent la sécurité au niveau de l'entreprise.
• Haute performance : La mise en cache, le pool de connexions et l'optimisation des requêtes améliorent l'efficacité.
• Flexibilité : Prend en charge plusieurs modes de communication et l'extension d'outils modulaires.

Limites

• Stabilité des premières versions : Certaines fonctionnalités (telles que column_analysis) sont expérimentales et peuvent contenir des bogues.
• Dépendance à la base de données Doris : Principalement conçu pour Apache Doris, la compatibilité avec d'autres bases de données utilisant le protocole MySQL est limitée.
• Abandon de SSE : La version 0.3.0 a supprimé la prise en charge de SSE, il est nécessaire de migrer vers HTTP Streamable.

Conclusion

Apache Doris MCP Server est un outil puissant et flexible qui relie la base de données Apache Doris aux besoins d'analyse pilotés par l'IA. Ses fonctionnalités telles que NL2SQL, la gestion des métadonnées, la sécurité et l'optimisation des performances lui confèrent un large potentiel dans l'analyse de données en temps réel, la business intelligence et les applications d'entreprise.