Apache Doris

Serveur MCP Apache Doris

English | 简体中文

Le serveur MCP Apache Doris expose des capacités Apache Doris en lecture seule aux hôtes MCP et aux agents IA via MCP 2026-07-28. La version 1.0 remplace une vaste surface d'outils plats par huit domaines stables et cinquante-cinq capacités enfants progressivement dévoilées, tout en rendant explicites la disponibilité à l'exécution, l'autorisation, les schémas d'entrée, les schémas de sortie et le comportement en cas d'échec.

Statut de la version

La version du paquet est 1.0.0. La compatibilité du protocole MCP 2026-07-28 sur master est généralement disponible (GA) sur Streamable HTTP et stdio. Cette déclaration GA est limitée à la compatibilité du protocole ; le classifieur du paquet Python reste Beta, et les limites de déploiement documentées s'appliquent toujours.

Avant de mettre à niveau, lisez les notes de version 1.0, le guide de migration 1.0 et le registre généré 8-domaines/55-enfants. Le compte rendu détaillé de la version est Issue #189.

Architecture en un coup d'œil

MCP Host
  -> stdio or Streamable HTTP
  -> transport security and authentication
  -> MCP protocol validation and authorization
  -> stable domain discovery
  -> route-aware Doris capability detection
  -> exact child dispatch and read-only runtime
  -> request-specific Doris route and RBAC
  -> bounded, schema-validated result

Le mode hierarchical par défaut expose ces domaines :

Domaine	Enfants	Responsabilité
doris_catalog	5	catalogues, bases de données, tables, contexte de table, taille
doris_query	7	requête, explain, profile, diagnostic, requêtes lentes, ADBC explicite
doris_cluster	11	nœuds, tâches, métriques, mémoire, cache, compaction, charges de travail
doris_pipeline	5	ingestion, vues matérialisées, fraîcheur, dépendances
doris_search	4	recherche texte/vectorielle/hybride, analyseurs, index, diagnostic
doris_governance	8	qualité, stockage, lignage, audit, UDF, mappage d'authentification
doris_lakehouse	3	catalogues externes, tables lakehouse, Variant
doris_semantic	12	ancrage optionnel Apache Ossie et consommation MetricFlow

Appelez un domaine avec {} pour découvrir ses enfants autorisés et ses schémas exacts. Appelez le même domaine à nouveau avec child_tool, arguments et le manifest_version renvoyé. Les hôtes qui ne peuvent pas utiliser la divulgation progressive peuvent définir MCP_TOOL_EXPOSURE_MODE=flat avant le démarrage ; cela expose les mêmes 55 enfants sous des noms formels sans collision et ne restaure pas les alias d'avant la 1.0.

Consultez Architecture, Cycle de vie des requêtes et Domaines d'outils.

Démarrage rapide

Prérequis :

• Python 3.12 ou version ultérieure ;
• Apache Doris 2.0.0 ou version ultérieure ;
• accès réseau au point de terminaison MySQL FE de Doris, normalement le port 9030.

Installez la version épinglée :

pip install doris-mcp-server==1.0.0

doris-mcp-server démarre le serveur. doris-mcp-client est un client séparé ; les deux commandes ne sont pas interchangeables.

Configurez une route Doris :

export DORIS_HOST=127.0.0.1
export DORIS_PORT=9030
export DORIS_USER=root
export DORIS_PASSWORD='replace-me'
export DORIS_DATABASE=information_schema

Démarrez Streamable HTTP sur loopback :

doris-mcp-server \
  --transport http \
  --host 127.0.0.1 \
  --port 3000

Points de terminaison :

• MCP : POST http://127.0.0.1:3000/mcp
• MCP hérité (opt-in) : POST http://127.0.0.1:3000/mcp/legacy
• liveness : GET http://127.0.0.1:3000/live
• readiness basé sur Doris : GET http://127.0.0.1:3000/ready

Les hôtes limités au Streamable HTTP de l'ère handshake, y compris Dify 1.16.1 avec MCP 2025-06-18, doivent définir ENABLE_LEGACY_HTTP_ADAPTER=true et se connecter à /mcp/legacy. L'adaptateur ne modifie que la frontière du protocole ; il préserve les mêmes outils 1.0, l'autorisation, les portes de capacité et l'exécution en lecture seule.

Ou exécutez stdio pour un hôte local :

doris-mcp-server --transport stdio

Consultez le Démarrage rapide complet et le Guide d'intégration des hôtes.

Frontière de sécurité

• Le catalogue 1.0 intégré est en lecture seule ; doris_admin est réservé et n'est pas enregistré.
• Les jetons statiques, JWT, OAuth/OIDC externes et OAuth adossé à Doris sont pris en charge dans des frontières de configuration validées mutuellement.
• La découverte de domaines et l'exécution d'enfants utilisent des identifiants d'autorisation exacts.
• Le RBAC de Doris reste l'autorité finale pour les objets et données visibles.
• La forme SQL, les identifiants, les paramètres, le délai d'expiration, les lignes, les octets et les schémas de résultats sont bornés avant que les données ne quittent le serveur.
• Les secrets et les erreurs de backend sont expurgés des résultats publics et des journaux.
• Le HTTP hors loopback requiert une authentification, sauf si un remplacement de développement dangereux explicite est activé.

Lisez le Modèle de sécurité et d'autorisation et le Guide d'accès fin à Doris.

Frontière de fiabilité

Le serveur utilise des manifestes et erreurs déterministes, des curseurs signés à expiration, des instantanés de capacité sensibles à la route, un repli borné sur données périmées, un routage de connexion spécifique aux requêtes, un basculement multi-FE, une séparation liveness/readiness, une validation de schéma de sortie et une propagation de traces assainie. Les capacités non prises en charge ou mal configurées restent découvrables avec callable=false et échouent de manière fermée lorsqu'elles sont appelées.

Les limites actuelles incluent l'OAuth adossé à Doris local au processus, l'ADBC uniquement explicite désactivé par défaut et à échec fermé sur les routes liées aux jetons, l'ancrage optionnel en lecture seule Ossie, un sidecar compilateur MetricFlow optionnel dont le SQL doit s'exécuter via le runtime de requêtes MCP borné, et une livraison de lignage natif au mieux. Consultez Fiabilité et limites.

Documentation

Le README racine est intentionnellement un point d'entrée. Le système de documentation bilingue est indexé à :

• English documentation
• 简体中文文档

Guides principaux :

• Architecture
• Flux de requêtes et de données
• Domaines d'outils
• Disponibilité des capacités
• Matrice de capacités par version Doris
• Intégration MetricFlow
• Contrat MCP 2026-07-28
• Modèle de sécurité
• Déploiement
• Fiabilité et limites
• Dépannage
• Référence de configuration
• Intégrations d'hôtes
• Fournisseurs d'outils personnalisés
• Contribuer

Développement

git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server
uv sync --group dev
uv run pytest

Les artefacts générés doivent rester synchronisés :

uv run python generate_tool_catalog.py --check
uv lock --check

Consultez Contribuer et vérification.

Licence

Apache License 2.0. Voir LICENSE.txt et NOTICE.