Architecture Chatbotaurus

Chatbotaurus est une plateforme MGaaS (MCP Gateway as a Service) européenne et souveraine, écrite en Rust. Elle combine un agent conversationnel, une passerelle MCP alimentée par des connecteurs déclarés en YAML, et une infrastructure auto-hébergeable sous Podman.

À la fin de ce chapitre, vous saurez situer chaque composant, dire dans quel plan il tourne et quelle page détaille son exploitation.

Vue d'ensemble

La plateforme tient en quatre couches :

• Interface : forge-ui, une seule base de code Dioxus 0.7 (binaire chatbotaurus). Elle se compile en wasm pour le navigateur (fonctionnalité web), ou en application bureau et mobile (fonctionnalités desktop et mobile de crates/forge-ui/Cargo.toml).
• Backend : forge-api, un serveur Axum qui expose /api/v1/** (REST, SSE, multipart, WebSocket), adossé à SeaORM sur PostgreSQL. Authentification, jeton CSRF, limitation de débit et contrôles de conformité UE sont des middlewares de ce crate.
• Passerelle MCP : le moteur forge-mcp (connecteurs, routage, sessions, transport Streamable HTTP). Il est monté dans forge-api (route /api/v1/mcp) et empaqueté seul dans forge-gateway, le binaire du service mcp-gateway du plan client.
• Infrastructure : conteneurs Podman répartis en deux plans (voir la section « Deux plans, une règle de nommage »), avec PostgreSQL, Valkey, Qdrant, OpenBao, Authentik, Ollama, la chaîne vocale et l'observabilité.

Deux plans, une règle de nommage

Le déploiement est découpé en deux projets Podman, chacun avec son réseau :

La règle tient au nom du service : un conteneur nommé mcp-* appartient au plan client, tout autre nom au plan backend. PostgreSQL et Valkey sont rattachés aux deux réseaux (alias DNS postgres et valkey sur mgaas-vps2) pour que les outils du plan client les joignent par leur nom.

Figure 1 : les deux plans de déploiement, leur règle de nommage et les deux services rattachés aux deux réseaux.

En production, ces plans sont décrits par des unités Quadlet (containers/*/*.container), l'ingress du plan backend est forge-traefik et celui du plan client mcp-caddy. Le détail est dans Déploiement avec Podman.

Crates du workspace

Le fichier Cargo.toml à la racine déclare ces membres :

Pile technique

Moteur MGaaS : quatre couches

Le moteur d'orchestration vit dans crates/forge-core/src/mgaas/ :

COUCHE 1 : raisonnement
  ToTLite, SelfConsistency, ChainOfVerification, MCTSLite

COUCHE 2 : orchestration d'agents
  routeur MoELite, TaskDecomposer, AgentMCPRegistry

COUCHE 3 : intelligence des outils
  RAREngine, DynamicToolPruner, ToolPatternMemory

COUCHE 4 : exécution et validation
  SpeculativeDecoder, ParallelStreamingExecutor, GroundingEngine

Sous pression de ressources, ce moteur est conçu pour désactiver ses techniques coûteuses par paliers : voir Gestion des erreurs.

État mesuré : la route GET /api/v1/mgaas/engines (crates/forge-api/src/routes/mgaas.rs) déclare « dormants », sans appelant de production, neuf des douze moteurs qu'elle liste. Seuls MoELiteRouter, TaskDecomposer et StructuredOutputValidator sont appelés en production.

Transport MCP : JSON-RPC 2.0 en Streamable HTTP

Dans forge-api, la route est montée dans crates/forge-api/src/router.rs :

POST   /api/v1/mcp   → JSON-RPC (initialize, tools/list, tools/call)
GET    /api/v1/mcp   → flux SSE de notifications
DELETE /api/v1/mcp   → terminer la session

• La session est portée par l'en-tête Mcp-Session-Id. Sa durée de vie par défaut est de 30 minutes d'inactivité (crates/forge-mcp/src/session.rs).
• La version de protocole annoncée à initialize est 2025-03-26 (crates/forge-mcp/src/protocol.rs).
• Ces routes exigent un utilisateur authentifié, et la surface MCP peut être coupée par l'interrupteur MCP_ENABLED.
• Le binaire forge-gateway expose, lui, POST /mcp et GET /health sur le port 8811 du plan client.

Pour explorer la flotte de connecteurs depuis l'API : GET /api/v1/mcp/catalogue (alias GET /api/v1/mcp/catalog) et GET /api/v1/mcp-gateway/servers.

Connecteurs MCP

Chaque fichier connectors/*.yaml déclare un connecteur. Au démarrage de forge-api, le CatalogueLoader (crates/forge-mcp/src/connector/catalogue.rs) lit ce dossier, résout les variables d'environnement et enregistre le connecteur dans le registre. Le nombre de connecteurs évolue avec le dépôt : il se compte avec ls connectors/*.yaml, jamais avec un chiffre recopié dans une page.

Un connecteur n'est accepté que s'il passe le contrôle de conformité UE du registre : voir Conception des connecteurs MCP.

Les connecteurs couvrent notamment les ERP et CRM (Odoo, ERPNext), les outils de collaboration, le support, l'analytique, les workflows (n8n), la sécurité, l'IA et un grand nombre de sources de données publiques européennes.

Modèles et chaîne vocale

• LLM : exécutés par Ollama (service forge-ollama). Le modèle par défaut se règle par la variable OLLAMA_MODEL, et forge-cli model pull télécharge un modèle.
• Embeddings : calculés localement (crate fastembed, crates/forge-core/src/rag/embedder.rs). La dimension des vecteurs est lue à l'exécution depuis le modèle chargé, pas fixée dans la documentation.
• Voix : synthèse par forge-kokoro-tts, transcription par forge-faster-whisper, temps réel par forge-livekit.

Les fournisseurs LLM tiers sont optionnels et désactivés par défaut.

Authentification

Les méthodes sont cumulables selon la configuration de l'organisation : mot de passe, second facteur TOTP (application d'authentification) et SSO OIDC via Authentik.

• Le jeton d'accès est un JWT signé en HS256 (l'algorithme est épinglé côté serveur). Sa durée se règle par JWT_EXPIRY ; le défaut du code est de 7 jours (crates/forge-api/src/state.rs).
• Protection CSRF par double soumission : cookie csrf-token et en-tête x-csrf-token sur les requêtes POST, PUT et DELETE.
• Les secrets de connecteurs sont chiffrés en AES-256-GCM avant stockage ; les locataires soumis à une exigence réglementaire peuvent les loger dans OpenBao.

Cloisonnement des locataires

Le filtre de locataire canonique repose sur l'organisation (organization_id), appliqué par accessible_workspace_filter (crates/forge-api/src/extractors/mod.rs). Un contrôle de pré-commit sur le cloisonnement des locataires protège les handlers du backend.

Gestion des erreurs

Chaque niveau capture et traduit ses erreurs :

• Transport MCP : JSON-RPC invalide, session expirée ;
• Connecteurs : délai dépassé, authentification, limite amont atteinte ;
• Moteur IA : dégradation par paliers sous pression de ressources.

Détails : Gestion des erreurs.

Compilation et contrôles

# Workspace complet
cargo build --workspace --release

# Interface web (wasm)
cargo build -p forge-ui --target wasm32-unknown-unknown --bin chatbotaurus

# Tests
cargo test --workspace

# Lint strict
cargo clippy --workspace --all-targets -- -D warnings

Les contrôles de pré-commit refusent notamment un fichier Rust de plus de 300 lignes sans exemption motivée et l'usage des termes « parity » ou « parité » sans preuve associée.

Voir aussi

• Conception des connecteurs MCP : manifestes YAML, connecteurs natifs et contrôle de conformité UE
• Gestion des erreurs : enveloppe d'erreur, codes JSON-RPC, disjoncteur et dégradation par paliers
• Routes MCP (Streamable HTTP) : transport, sessions et catalogue exposés par la passerelle
• Connecteurs MCP : comment un connecteur est chargé, authentifié et compté
• Déploiement avec Podman : les deux plans en pratique : Compose en développement, Quadlet en production