Nodefony 10.0.2
Framework Node.js fullstack — HTTP & WebSocket, même contexte

@nodefony/ai — la mécanique MCP hors du cœur, une porte se déclare

accepted

Summary. The MCP protocol engine used to live in the framework core, and the only HTTP gate was a development-only one: an application could not open its own MCP endpoint in production without re-implementing the protocol. This decision moves the whole MCP mechanics into a separate package, @nodefony/ai, which mounts no route by itself: a gate is declared with defineMcpGate({ … }) and served from a controller action of the application that needs it. For a user, this means an MCP endpoint at the address of your choice, in development or in production, safe by default (an unprotected gate grants no role), and at zero per-request cost as long as no gate is declared.

Cette page porte le pourquoi de la décision ; le comment — déclarer une porte, la protéger, y exposer des outils — vit dans le guide MCP dans @nodefony/ai.

📍 Documentation › Décisions d’architecture › ADR-0017

Statut#

Accepté le 2026-10-16 — en vigueur, ni remplacé ni amendé. Complète l’ADR-0004 : l’inférence reste hors du process ; c’est l’OUTILLAGE de l’IA dans l’application qui trouve ici sa place. Après la 10.0.0, déplacer un symbole public de @nodefony/ai, ou renommer une clé de réglage d’une porte, est une rupture.

Contexte#

Le protocole MCP (moteur JSON-RPC, progression, flux SSE, garde d’origine, rôles des appelants, collecte des outils) vivait dans le paquet nodefony, et l’unique porte HTTP était celle de @nodefony/devkit : POST /nodefony/mcp, policy: "dev". Trois défauts en découlaient.

  1. Une application ne pouvait pas ouvrir SA porte en production. La seule porte existante disparaît hors développement — c’est voulu pour les outils nodefony_*, qui divulguent l’architecture —, et en écrire une seconde exigeait de recoder le protocole avec des briques du cœur jamais pensées pour être assemblées.
  2. Le cœur portait un protocole que la plupart des applications n’emploient pas, et un protocole qui évolue vite : la révision 2026-07-28 a retiré les sessions et le flux ouvert par GET. Le cœur publie la version la plus lente du dépôt.
  3. Les capacités d’IA à venir (accès modèle, index vectoriel, mémoire, agents) n’avaient pas de maison : cinq esquisses de paquets privés, chacune à 0.0.0.

Un premier plan prévoyait un service McpService qui MONTAIT la porte depuis @nodefony/ai. C’était un contresens : un module socle, chargé partout, aurait servi une route en production à toutes les applications, qu’elles l’aient demandée ou non.

Décision#

  1. @nodefony/ai est un module SOCLE (policy: "mandatory"), paquet distinct du cœur. Il porte le protocole MCP, le moteur handleMcpMessage, la progression, le flux, la garde, les rôles des appelants, la collecte et l’appel des outils. Les gabarits create app (minimal et complete) le déclarent en dependencies et le chargent avant devkit.

  2. Il ne monte AUCUNE route. Une porte se DÉCLARE : defineMcpGate({ … }) la définit une fois, validée et figée au chargement ; gate.serve(this, body) la sert depuis l’action d’un controller de qui en a besoin. Une application ouvre la sienne, en développement ou en production, à l’adresse qu’elle choisit.

  3. Frontières :

    Où Ce qui y vit
    cœur nodefony les CONTRATS en types (IMcpTool, hook getMcpTools()), JSON-RPC 2.0, serveur de ressource OAuth, MCP_ENDPOINT_PATH, ai:mcp, ai:sync
    @nodefony/ai le protocole et la mécanique de porte (defineMcpGate, gate.serve, gate.respond, gate.protectedResources, mcpConfigSchema)
    @nodefony/devkit les outils nodefony_* et SA porte de développement /nodefony/mcp, policy: "dev", bâtie sur defineMcpGate

    Le cœur n’importe jamais @nodefony/ai (scripts/gates/check-package-deps.mjs).

  4. Défaut sûr : une porte non protégée n’accorde AUCUN rôle ; ses outils réservés restent retenus. Seule une porte que son PÉRIMÈTRE protège (devkit, policy: "dev") élargit, et l’écrit (unprotectedRoles). Une porte qui déclare un serveur d’autorisation exige un jeton.

  5. Un seul vocabulaire de réglages : les clés d’une porte sont celles de mcpConfigSchema, déjà publiques sous devkit.mcp.*. Aucune cassure pour qui avait réglé la porte de dev.

  6. Coût nul par requête tant qu’aucune porte n’est déclarée : aucun écouteur, aucun registre peuplé au démarrage, collecte des outils à la requête.

Conséquences#

Alternatives écartées#