Architecture

erp-platform sépare la plateforme SaaS multi-tenant de la couche d'adapters ERP. La plateforme gère l'authentification, la tenancy, le chiffrement, le routage MCP et l'audit. Son runtime charge actuellement la version 0.1.0 de @casys/mcp-erp, une dépendance interne dont la surface publiée est limitée aux diagnostics.

mcp-erpnext est un serveur MCP ERPNext autonome distinct. Sa version 3.0.1 apporte la preuve métier publique avec 124 tools, 14 catégories et 7 viewers ; elle n'est pas une dépendance du runtime hébergé actuel.

Flux logique

Client MCP / assistant IA
        ↓
  endpoint tenant erp-platform
        ↓
  authentification OAuth/OIDC + résolution tenant
        ↓
  catalogue diagnostic de @casys/mcp-erp 0.1.0
        ↓
  configuration directe ou routage par tunnel local

1. MCP-native

Les assistants IA ne devraient pas avoir à connaître chaque API ERP. erp-platform expose un serveur MCP par tenant : le client découvre les tools, leurs schémas et leurs erreurs via le protocole MCP.

Cette frontière garde les prompts et les agents stables pendant que les adapters ERP évoluent. Elle ne garantit pas à elle seule la profondeur du catalogue : le runtime hébergé expose aujourd'hui les diagnostics erpnext.ping et dolibarr.ping.

2. Multi-tenant

Chaque requête est résolue depuis le host tenant, par exemple acme.erp-platform.fr. Les credentials et les événements d'audit sont attachés au tenant, et les routes protocolaires (/mcp, /oauth, /.well-known) gardent des contrats stables.

3. Adapters ERP

Le repo ne duplique pas la logique ERP dans la plateforme Fresh. Il délègue à @casys/mcp-erp, qui expose une interface commune pour construire un adapter, lister ses tools et exécuter un appel. La version publiée et verrouillée ici est la 0.1.0 ; ses deux tools sont des diagnostics de configuration qui renvoient notamment l'URL configurée. Ils ne prouvent ni un appel métier ERPNext ni une parité avec le catalogue de mcp-erpnext.

Les types explicitement autorisés côté plateforme sont erpnext et dolibarr. ERPNext est le parcours produit prioritaire. Dolibarr est un chemin secondaire au périmètre plus étroit. L'allowlist appartient à erp-platform : publier un nouvel adapter dans @casys/mcp-erp ne l'expose pas automatiquement dans /setup ou l'API de credentials.

La réutilisation future des tools de mcp-erpnext devra préserver l'isolation par tenant, avec un client Frappe explicitement lié aux credentials du tenant. La documentation ne présentera cette intégration comme active qu'après sa mise en œuvre et sa vérification dans le runtime hébergé.

4. Connexion directe ou tunnel local

Deux modes de connexion coexistent :

direct : la plateforme détient la configuration destinée aux appels ERP depuis le VPS ;
tunnel : un agent local côté client ouvre une connexion sortante vers erp-platform, ce qui évite d'exposer l'ERP à Internet.

Le mode tunnel est important pour les ERPs internes, les instances on-premise et les environnements où l'ouverture réseau entrante est impossible. Ces chemins de transport existent dans la plateforme, mais le catalogue 0.1.0 actuellement chargé ne démontre pas encore un workflow métier ERPNext de bout en bout.

5. Secrets et traces opérationnelles

En mode direct, les credentials ERP sont chiffrés avec une clé AES-256-GCM par tenant et la base ne stocke pas les secrets en clair. En mode tunnel, la plateforme efface les credentials ERP : ils restent dans l'agent local, tandis que la plateforme conserve le matériel d'enrôlement du tunnel.

Après un appel MCP réussi, le runtime tente d'écrire un événement avec le tenant, l'acteur et le nom du tool. Cette écriture est best-effort : une erreur de base est journalisée côté serveur mais n'échoue pas l'appel utilisateur. Ce mécanisme sert au support et à l'observabilité ; il ne constitue pas un journal de conformité garanti.

Le but est d'améliorer l'observabilité opérationnelle sans présenter cette trace comme une preuve exhaustive.