@nodefony/ai 10.0.0-beta.3 → 10.0.0-beta.4

package/dist/types/nodefony/mcp/tools.d.ts

@@ -0,0 +1,232 @@
+import type { IMcpTool, IMcpToolAnnotations, IMcpToolDefinition, IMcpToolResult, IMcpCaller, IMcpToolRun } from "nodefony";
+export type { IMcpTool, IMcpToolAnnotations, IMcpToolDefinition, IMcpToolResult, IMcpCaller, IMcpToolRun, };
+/**
+ * Outils MCP : la **collecte** de ceux qu'une application déclare, leur
+ * publication et leur exécution — la part générique de toute porte MCP.
+ *
+ * Les CONTRATS (`IMcpTool` et ses voisins) vivent au cœur, parce qu'un module
+ * les implémente par {@link IModule.getMcpTools} sans dépendre d'aucune porte ;
+ * la MÉCANIQUE vit ici. Le catalogue `nodefony_*` n'est pas ici non plus : il
+ * appartient à `@nodefony/devkit`, qui le déclare comme n'importe quel module.
+ *
+ * ## Pourquoi la collecte, et pas un registre
+ *
+ * Un module déclare ses outils par {@link IModule.getMcpTools} ; ils sont
+ * ramassés **au moment de servir la requête**, jamais stockés. C'est
+ * délibérément l'inverse du data plane admin ({@link IAdminRegistry}), qui a
+ * besoin d'un registre parce qu'il monte des ROUTES au boot et qu'un module
+ * arrivé trop tard n'aurait plus rien à monter. Un outil MCP n'a rien à monter :
+ * il est lu à la demande. D'où trois propriétés gagnées gratuitement — aucune
+ * structure allouée au démarrage (donc coût nul en production, où aucune porte
+ * MCP n'existe), aucun ordre de `register()` à respecter, et une fraîcheur qui
+ * est une propriété du mécanisme plutôt qu'une discipline à tenir.
+ */
+/**
+ * Au-delà de quoi une réponse cesse d'être une réponse.
+ *
+ * Mesuré, pas choisi en l'air : `inspect routes` rendait 47 000 caractères et
+ * `inspect config` 190 730 — le second dépassait ce que le client accepte, il
+ * partait sur disque, et l'agent brûlait vingt tours à le relire au `jq`. Le
+ * premier passait, et ne servait à rien pour autant : à qui demandait le NOMBRE
+ * de routes, il fallait compter 119 objets dans un mur de JSON.
+ *
+ * La borne est donc largement SOUS la limite des clients : ce qu'on protège
+ * n'est pas le transport, c'est la capacité de l'agent à répondre sans relire.
+ */
+export declare const MCP_TEXT_MAX_CHARS = 32000;
+/**
+ * Rend un résultat d'outil — les données partent en JSON COMPACT.
+ *
+ * Le lecteur est un agent : il relit le JSON compact sans peine, et chaque
+ * caractère rendu se repaie à chaque tour suivant de sa conversation.
+ * L'indentation représentait ~25 % d'un rapport `nodefony_check`.
+ *
+ * Exporté parce qu'une application qui déclare un outil en a besoin : sans lui,
+ * chacune réinventerait l'enveloppe `content[]`, et une enveloppe mal formée
+ * n'échoue pas — elle rend un résultat vide que l'agent prend pour une réponse.
+ *
+ * **Un résultat est BORNÉ** ({@link MCP_TEXT_MAX_CHARS}) : au-delà, il rend un
+ * résumé plutôt qu'un déversement (voir {@link summarize}). La garde vit ICI, et
+ * non dans chaque outil, pour qu'un outil déclaré par une
+ * application en hérite sans le savoir — c'est le genre de règle qu'on
+ * n'applique jamais deux fois de la même façon si on la laisse à l'appelant.
+ * En deçà de la borne — le cas courant — la donnée part TELLE QUELLE : un
+ * consommateur qui la parse n'a rien à changer, et on ne paie pas la garde sur
+ * 100 % des appels pour 1 % de gros sujets.
+ *
+ * @param value - donnée à rendre (sérialisée si ce n'est pas déjà du texte)
+ * @param isError - marque un échec MÉTIER (pas une faute de protocole)
+ */
+export declare function mcpText(value: unknown, isError?: boolean): IMcpToolResult;
+/**
+ * Ce qu'il faut pour ÉNUMÉRER les déclarations d'outils d'une application.
+ *
+ * Distinct de {@link IMcpCollectOptions}, qui ajoute l'appelant : énumérer est
+ * une question sur le CODE (« que déclare cette application ? »), collecter est
+ * une question sur une REQUÊTE (« que sert-on à celui-ci ? »). Le document de
+ * ressource protégée, servi sans contexte d'appelant, ne peut poser que la
+ * première.
+ */
+export interface IMcpDeclareOptions {
+    /**
+     * Modules chargés (`kernel.modules`), dont on lit `getMcpTools()`.
+     *
+     * Typé large à dessein : le cœur ne peut pas dépendre de la forme concrète
+     * d'un module ici, et la lecture est de toute façon défensive.
+     */
+    modules?: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Appelé pour chaque déclaration ÉCARTÉE, avec le motif.
+     *
+     * Sans ce rappel, un outil mal nommé ou en collision disparaîtrait en
+     * silence, et son auteur chercherait la faute dans son handler — qui n'a
+     * jamais été appelé.
+     */
+    onSkip?: ((why: string) => void) | undefined;
+}
+/** Ce qu'il faut pour ramasser les outils SERVIS à un appelant. */
+export interface IMcpCollectOptions extends IMcpDeclareOptions {
+    /**
+     * Ce que la porte a ÉTABLI de l'appelant. Absent = anonyme.
+     *
+     * Une porte sans authentification n'a rien à passer, et c'est le cas sûr :
+     * l'anonyme par défaut RETIENT tout outil qui exige quoi que ce soit.
+     */
+    caller?: IMcpCaller | undefined;
+    /**
+     * Appelé pour chaque outil RETENU faute d'autorisation.
+     *
+     * Distinct d'{@link IMcpCollectOptions.onSkip}, et la distinction n'est pas
+     * cosmétique : un `onSkip` dénonce une FAUTE de l'auteur (nom hors forme,
+     * handler absent) et mérite un avertissement ; une rétention est le
+     * fonctionnement NORMAL d'un catalogue filtré, et crier à chaque requête pour
+     * chaque outil protégé noierait le journal. Le rappel existe quand même,
+     * parce que sans lui un développeur qui déclare des scopes sur une porte non
+     * authentifiée chercherait son outil sans jamais comprendre.
+     */
+    onWithheld?: (name: string, why: string) => void;
+}
+/**
+ * Préfixe RÉSERVÉ aux modules du framework (`@nodefony/*`) — un agent qui lit
+ * `nodefony_inspect` doit pouvoir croire que c'est le framework qui répond.
+ *
+ * Sans la réserve, un module d'application pourrait déclarer `nodefony_doc` et
+ * répondre à la place de l'outil que l'agent a lu dans la documentation du
+ * framework : l'ordre de chargement des modules ne protège rien, il change
+ * avec le manifeste.
+ */
+export declare const MCP_RESERVED_PREFIX = "nodefony_";
+/**
+ * Énumère ce que cette application DÉCLARE — les outils de ses modules, lus
+ * par `getMcpTools()` — sans rien retenir sur l'identité de qui que ce soit.
+ *
+ * Cinq refus, tous énoncés par `onSkip` plutôt que silencieux :
+ *  - **nom hors forme** ({@link NAME_PATTERN}) — il ne serait pas appelable ;
+ *  - **forme fausse** ({@link mcpToolFault}) — handler, description, schéma ou
+ *    autorisation qui ne respectent pas `IMcpTool` ;
+ *  - **préfixe réservé** ({@link MCP_RESERVED_PREFIX}) pris par un module hors de
+ *    `@nodefony/` — un module d'application ne peut donc pas se substituer à
+ *    `nodefony_inspect` et répondre à sa place ;
+ *  - **collision** — le premier inscrit garde le nom ;
+ *  - **déclaration en échec** — un `getMcpTools()` qui lève ne doit pas priver
+ *    l'agent des outils de tous les autres modules.
+ *
+ * 🔴 **Ce que rend cette fonction n'est PAS servable tel quel** : elle contient
+ * les outils réservés. Toute porte passe par {@link collectMcpTools}, qui filtre
+ * sur l'appelant. Le seul usage légitime de la liste brute est de raisonner sur
+ * le CODE — ce que la porte EXIGE ({@link mcpDeclaredScopes}) — jamais de
+ * répondre à une requête.
+ *
+ * @param options - modules et journal des écarts
+ * @returns les outils déclarés, dans l'ordre où ils seraient publiés
+ */
+export declare function declareMcpTools(options: IMcpDeclareOptions): IMcpTool[];
+/**
+ * Ramasse les outils SERVIS à cet appelant.
+ *
+ * Aux trois refus de {@link declareMcpTools} s'ajoute une RÉTENTION, qui n'est
+ * pas une faute : un outil dont l'appelant ne satisfait pas les exigences
+ * ({@link IMcpTool.scopes}, {@link IMcpTool.requiresAuth}) ne sort pas d'ici.
+ * ⭐ **Filtrer À LA COLLECTE protège `tools/list` ET `tools/call` d'un seul
+ * geste** : le protocole ne reçoit que les outils servis, donc un outil retenu
+ * est « inconnu » pour lui — indistinguable d'un outil inexistant, ce qui ne
+ * révèle même pas son existence. Filtrer la liste sans filtrer l'appel n'aurait
+ * été qu'un rideau, et c'est l'erreur classique : deux points de décision, dont
+ * un qu'on oublie.
+ *
+ * @param options - modules, appelant et journaux
+ * @returns les outils exécutables, dans l'ordre où ils seront publiés
+ */
+export declare function collectMcpTools(options: IMcpCollectOptions): IMcpTool[];
+/**
+ * Le vocabulaire de scopes que cette porte EXIGE — l'union de ce que ses outils
+ * déclarent, jamais une liste écrite à côté.
+ *
+ * 🔴 **C'est ce qu'un client doit demander**, et c'est à ce titre qu'il est
+ * publié (RFC 9728 `scopes_supported`) et nommé dans le défi (RFC 6750
+ * `scope`). Une liste de configuration disait autre chose que le code par
+ * simple oubli, dans les deux sens et sans qu'aucun contrôle ne l'aperçoive :
+ * un scope publié que rien n'exige envoie demander un droit qui n'ouvre rien ;
+ * un scope exigé que rien ne publie laisse le client deviner ce qu'on attend de
+ * lui — et un outil de module en était systématiquement là.
+ *
+ * L'énumération est délibérément celle des outils DÉCLARÉS, pas de ceux servis
+ * à un appelant : le document se lit avant d'avoir un jeton, et un catalogue
+ * filtré n'annoncerait à l'anonyme que ce dont il n'a pas besoin.
+ *
+ * @param options - modules et journal des écarts
+ * @returns les scopes, dédupliqués et triés ; vide si la porte n'exige rien
+ */
+export declare function mcpDeclaredScopes(options: IMcpDeclareOptions): string[];
+/**
+ * Projette les outils pour `tools/list` — sans leur implémentation.
+ *
+ * Le `handler` est une fermeture sur l'état du serveur ; `JSON.stringify` le
+ * laisserait tomber en silence, mais compter là-dessus reviendrait à publier
+ * par accident ce qu'on ne publie pas exprès.
+ */
+export declare function publishMcpTools(tools: readonly IMcpTool[]): IMcpToolDefinition[];
+/**
+ * Exécute un outil par son nom public.
+ *
+ * Un échec métier (sujet inconnu, module absent) rend un résultat `isError`,
+ * **pas** une erreur JSON-RPC : le protocole réserve celle-ci aux fautes de
+ * protocole. La distinction compte pour l'agent — une erreur de protocole
+ * signifie « tu t'y prends mal », un `isError` signifie « ta demande est
+ * recevable, voici pourquoi elle n'aboutit pas » ; c'est la seconde qu'il peut
+ * corriger seul.
+ *
+ * ⭐ **Aucun contrôle d'autorisation ici, et c'est voulu** : `tools` ne contient
+ * que ce que {@link collectMcpTools} a servi à CET appelant. Refaire la
+ * vérification à ce niveau créerait un second point de décision — deux copies
+ * d'une même règle, qui divergent en silence. Le corollaire tient en une
+ * phrase : **ne jamais passer ici une liste non filtrée.**
+ *
+ * @param name - nom public de l'outil (`nodefony_inspect`…)
+ * @param args - arguments fournis par l'agent
+ * @param tools - outils servis, tels que {@link collectMcpTools} les a ramassés
+ * @param caller - appelant établi, transmis au handler (anonyme par défaut)
+ * @param run - annulation et progression de CET appel (détaché par défaut)
+ * @returns le résultat de l'outil, ou `null` si le nom n'est pas exposé
+ */
+export declare function callMcpTool(name: string, args: Record<string, unknown>, tools: readonly IMcpTool[], caller?: IMcpCaller, run?: IMcpToolRun): Promise<IMcpToolResult | null>;
+/**
+ * Tous les scopes qu'exige UN appel : ceux de l'outil, puis ceux que ses
+ * arguments ajoutent ({@link IMcpTool.scopesFor}). Seule source de la règle,
+ * lue par l'appel en process ET par le défi `insufficient_scope` d'une porte.
+ *
+ * @param tool - outil servi
+ * @param args - arguments de l'appel
+ * @returns les scopes exigés, sans doublon ; `null` si `scopesFor` lève ou rend
+ *   une forme fausse (l'appel est alors refusé, jamais servi sans borne)
+ */
+export declare function mcpCallScopes(tool: IMcpTool, args: Readonly<Record<string, unknown>>): readonly string[] | null;
+/**
+ * Le message d'un appel refusé faute de scope — le même pour le résultat
+ * `isError` et la description du défi `403`.
+ *
+ * @param name - nom de l'outil
+ * @param missing - scopes absents du jeton
+ * @returns l'explication, qui nomme les scopes à demander
+ */
+export declare function insufficientScopeMessage(name: string, missing: readonly string[]): string;

package/docs/index.md

@@ -0,0 +1,56 @@
+---
+title: "@nodefony/ai — la boîte à outils de l'IA dans une application"
+navTitle: ai
+lang: fr
+module: "@nodefony/ai"
+topic: overview
+audience: [developer]
+tags: [module, ia, mcp, agent]
+status: draft
+updated: 2026-10-16
+source: "src/packages/@nodefony/ai/docs/index.md"
+---
+
+# ai
+
+> La boîte à outils de l'IA DANS une application Nodefony : exposer ses outils métier à un
+> agent par le _Model Context Protocol_, et ouvrir sa propre porte MCP.
+
+📍 [Documentation](../../../../../docs/index.md) › **@nodefony/ai**
+
+Cette page est **surfacée dans Studio** (onglet Docs du module).
+
+## Ce que fait le module
+
+- **Le protocole MCP, tenu pour toi** : versions, erreurs, progression, annulation, flux SSE.
+  Un outil n'écrit que sa logique.
+- **La mécanique de porte** : `defineMcpGate()` définit une porte, validée au démarrage ;
+  `gate.serve(this, body)` la sert depuis une action de controller.
+- **Aucune route montée** : une porte se déclare, par le controller de qui en a besoin — la
+  porte de développement de `@nodefony/devkit`, ou celle de ton application.
+
+C'est un module **socle** (`policy: "mandatory"`), chargé dans tous les environnements. Il ne
+coûte rien par requête tant qu'aucune porte n'est déclarée.
+
+## Configuration
+
+```ts
+use("@nodefony/ai", undefined, { policy: "mandatory" }),
+```
+
+Les réglages d'une porte se passent à `defineMcpGate()`, pas au module.
+
+## Par où commencer
+
+```nodefony-cards
+[
+  { "icon": "🤖", "title": "Boîte à outils MCP", "href": "mcp.md",
+    "desc": "Écrire un outil, le réserver à un appelant authentifié, signaler la progression d'un outil long, et monter sa propre porte avec defineMcpGate.",
+    "meta": "un agent doit interroger ou piloter ton application" }
+]
+```
+
+## Pour aller plus loin
+
+- La porte de développement et ses outils intégrés → [devkit](../../devkit/docs/index.md)
+- [Toute la documentation](../../../../../docs/index.md)