@nodefony/ai 0.0.0-stage → 10.0.0-beta.4

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -0,0 +1,43 @@
+import type { IAiConfig } from "./config.js";
+/**
+ * @nodefony/ai — LE COMMENT : builder PUR de la config.
+ *
+ * ⭐ TL;DR : ce fichier VALIDE et GÈLE. Il ne porte AUCUNE valeur — les défauts
+ * vivent dans le schéma de `./config.ts` (règle d'or ADR-0006). Pour changer un
+ * défaut, c'est là-bas ; ici, on ne fait que le faire respecter.
+ *
+ * Le nom du FICHIER est le même dans tous les modules Nodefony
+ * (`defineModuleConfig.ts`) ; la FONCTION, elle, est préfixée par le module —
+ * deux modules importés côte à côte ne se marchent pas dessus.
+ *
+ * L'environnement ne se lit JAMAIS ici. La surcharge générique
+ * (`NF__AI__<CHEMIN>`) comme un nom court (`NF_AI_<RÉGLAGE>`) sont
+ * posés par le Kernel avant cette validation. Un nom court se DÉCLARE sur son
+ * champ, dans `./config.ts` : `.meta({ env: "NF_AI_<RÉGLAGE>" })`.
+ *
+ * 🔴 **La validation passe par `parseModuleConfig`, du cœur** — un seul endroit
+ * pour une seule règle. Il lève une `BootConfigurationError`, et pas une `Error`
+ * ordinaire : le kernel distingue les deux. Un hook de cycle de vie qui lève une
+ * erreur QUELCONQUE est absorbé en développement (fail-soft — il protège la DX
+ * d'un module optionnel cassé), tandis qu'une erreur de CONFIGURATION interrompt
+ * le boot dans TOUS les environnements. Mesuré sur un module généré : avec une
+ * `Error`, `use("@nodefony/ai", { gretting: "…" })` laissait l'application
+ * démarrer, servir, et rendre 0 — la faute de frappe n'atteignait personne. Une
+ * configuration explicite qu'on ne peut pas honorer ne se répare pas en
+ * continuant.
+ *
+ * ⚠️ Ne PAS réécrire ce bloc à la main : les dix modules du framework portaient
+ * chacun leur copie du `try`/`catch`, et elles avaient divergé sur les deux
+ * points qui comptent — le type de l'erreur levée et la langue du message.
+ *
+ * @param config - config brute venue de `use("@nodefony/ai", { … })`.
+ * @returns config validée et gelée.
+ * @throws BootConfigurationError si un champ est invalide ou inconnu (toutes les
+ *   erreurs Zod agrégées, par champ) — le boot s'interrompt, en dev comme en prod.
+ */
+export declare function defineAiConfig(config?: unknown): IAiConfig;
+/**
+ * JSON Schema de la config — Studio en dérive son formulaire d'édition
+ * (libellés, types, défauts, descriptions), sans une ligne d'UI écrite à la main.
+ */
+export declare function aiConfigJsonSchema(): unknown;

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

@@ -0,0 +1,54 @@
+/**
+ * Ce qu'une porte MCP sait d'elle-même et de son appelant, au moment de dire
+ * quels rôles celui-ci porte.
+ *
+ * Les trois champs sont séparés parce qu'ils répondent à trois questions
+ * distinctes que confondre a déjà coûté : « cette porte exige-t-elle une
+ * autorisation ? », « une identité a-t-elle été prouvée ? », « qu'ouvre-t-elle ? ».
+ */
+export interface IMcpGatePosture {
+    /**
+     * La porte déclare-t-elle un serveur d'autorisation ?
+     *
+     * ⚠️ À ne PAS confondre avec `authenticated`. Une porte protégée peut tolérer
+     * l'anonyme ; une porte non protégée n'a personne à authentifier. Ce sont ces
+     * deux cas — tous deux « non authentifiés » — qui doivent recevoir des
+     * réponses opposées.
+     */
+    protected: boolean;
+    /** Un jeton a-t-il été vérifié pour cet appel ? */
+    authenticated: boolean;
+    /** Scopes que le serveur d'autorisation a réellement accordés. */
+    scopes: readonly string[];
+}
+/**
+ * Quels rôles porte l'appelant d'une porte MCP — **la règle, à un seul endroit**.
+ *
+ * ⭐ Toute porte MCP passe par ici, y compris celles qu'un module créera plus
+ * tard (gestion d'agents, passerelles métier). C'est délibéré : la question
+ * « que vaut un appelant sur ma porte » a exactement une bonne réponse, et
+ * laisser chaque porte la réécrire garantit qu'une copie finira plus permissive
+ * que les autres sans que rien ne le signale — c'est déjà ce qui s'est produit
+ * quand la lecture d'administration fabriquait un administrateur.
+ *
+ * Les trois postures :
+ *
+ * | La porte | L'appelant | Ce qu'il porte |
+ * | --- | --- | --- |
+ * | non protégée | quiconque l'atteint | `operatorRoles` — AUCUN par défaut ; une porte dont le PÉRIMÈTRE protège l'élargit |
+ * | protégée | jeton vérifié | ce que ses SCOPES ouvrent, rien de plus |
+ * | protégée | anonyme toléré | **rien** — la déclaration d'autorisation serait vidée de son sens |
+ *
+ * Le premier cas n'accorde RIEN par défaut : une porte non protégée peut être
+ * celle d'une application, ouverte en production. Seule une porte que son
+ * PÉRIMÈTRE protège — la porte de développement de devkit, module
+ * `policy: "dev"`, dont l'appelant lit déjà les sources — passe le rôle
+ * d'opérateur, et l'écrit. Ce qui compte, c'est que ce soit un CHOIX écrit par
+ * la porte — pas un administrateur fabriqué au fond d'une fonction de lecture.
+ *
+ * @param posture - ce que la porte sait d'elle-même et de cet appel.
+ * @param operatorRoles - ce qu'accorde une porte NON protégée ; aucun rôle par
+ *   défaut.
+ * @returns les rôles à poser sur `IMcpCaller.roles`.
+ */
+export declare function mcpCallerRoles(posture: IMcpGatePosture, operatorRoles?: readonly string[]): readonly string[];

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

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import type { IAccessAccountResolver, IAccessTokenVerifier, IProtectedResourceInput, IMcpTool } from "nodefony";
+import type { Controller } from "@nodefony/framework";
+import type { IServerInfo } from "./server.js";
+import { type IMcpEventSink } from "./stream.js";
+/**
+ * Une porte MCP sur HTTP — la mécanique, sans la route.
+ *
+ * `@nodefony/ai` ne monte AUCUNE route : une porte se DÉCLARE, par qui en a
+ * besoin — devkit pour l'outillage de développement, une application pour ses
+ * propres outils, en développement ou en production selon son choix. On la
+ * définit une fois ({@link defineMcpGate}), on la sert d'une ligne
+ * (`gate.serve(this, body)`). Gardes d'origine et de localité, validation du
+ * jeton, défi `401` avec `resource_metadata`, traduction HTTP ↔ JSON-RPC, flux
+ * SSE, refus `405` des verbes retirés : une porte qui recoderait l'une de ces
+ * règles finirait plus permissive que les autres sans que rien ne le dise.
+ */
+/**
+ * Plafond d'un événement sur le flux de réponse MCP, octets UTF-8 — celui de la
+ * réponse finale, qui porte le résultat entier de l'outil (16 Mio).
+ */
+export declare const MCP_STREAM_MAX_EVENT_BYTES: number;
+/** Sévérités qu'une porte MCP écrit au journal. */
+export type McpGateSeverity = "DEBUG" | "WARNING" | "ERROR" | "CRITIC";
+/**
+ * Le schéma d'une porte — les réglages de transport et d'autorisation de
+ * {@link mcpConfigSchema} (les MÊMES clés que `devkit.mcp.*`), plus ce que la
+ * porte publie et comment. Strict : une clé inconnue arrête le démarrage en la
+ * nommant, au lieu d'être ignorée.
+ */
+export declare const mcpGateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    allowRemote: z.ZodDefault<z.ZodBoolean>;
+    authorization: z.ZodDefault<z.ZodObject<{
+        authorizationServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        resource: z.ZodDefault<z.ZodString>;
+        additionalResources: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        resourceName: z.ZodOptional<z.ZodString>;
+        resourceDocumentation: z.ZodOptional<z.ZodString>;
+        anonymous: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    name: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+    tools: z.ZodUnion<readonly [z.ZodLiteral<"modules">, z.ZodArray<z.ZodCustom<IMcpTool, IMcpTool>>]>;
+    unprotectedRoles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    protocol: z.ZodDefault<z.ZodObject<{
+        versions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            "2024-11-05": "2024-11-05";
+            "2025-03-26": "2025-03-26";
+            "2025-06-18": "2025-06-18";
+            "2025-11-25": "2025-11-25";
+            "2026-07-28": "2026-07-28";
+        }>>>;
+    }, z.core.$strict>>;
+    cache: z.ZodDefault<z.ZodObject<{
+        ttlMs: z.ZodDefault<z.ZodNumber>;
+        scope: z.ZodDefault<z.ZodEnum<{
+            private: "private";
+            public: "public";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Ce qu'on écrit pour définir une porte (défauts compris). */
+export type IMcpGateDefinition = z.input<typeof mcpGateSchema>;
+/** Les réglages EFFECTIFS d'une porte, validés et figés. */
+export type IMcpGateSettings = z.output<typeof mcpGateSchema>;
+/** Ce que la porte a reçu — lu par elle, jamais par la mécanique. */
+export interface IMcpGateRequest<S extends IMcpEventSink = IMcpEventSink> {
+    /** Corps tel que le parseur HTTP l'a rendu (`{}` pour un JSON illisible). */
+    body: unknown;
+    /**
+     * Le corps BRUT, lu à la demande : seul moyen de distinguer un `{}` envoyé
+     * d'un texte qui ne se parse pas (JSON-RPC `-32700` contre `-32600`). Appelé
+     * uniquement quand le corps n'a aucune clé.
+     */
+    rawBody?: (() => string | undefined) | undefined;
+    /** En-tête `Origin`. */
+    origin?: string | undefined;
+    /** En-tête `MCP-Protocol-Version`. */
+    protocolVersion?: string | undefined;
+    /** En-tête `Authorization`. */
+    authorization?: string | undefined;
+    /** Adresse de l'appelant (après `trustProxy`). */
+    remoteAddress?: string | undefined;
+    /**
+     * La requête a traversé un relais (en-tête `Forwarded`, `X-Forwarded-For`,
+     * `X-Real-IP` ou `Via`) — refusée par une porte locale.
+     */
+    relayed?: boolean | undefined;
+    /** Abattu quand le client abandonne la requête. */
+    signal?: AbortSignal | undefined;
+    /**
+     * Ouvre un flux SSE — absent quand le client n'en accepte pas : la
+     * progression devient alors muette, jamais refusée.
+     */
+    openStream?: (() => S | Promise<S>) | undefined;
+    /**
+     * Prévenu de l'identifiant du compte au nom duquel un outil agit — pour le
+     * journal de la requête, qui le lit au démontage, hors de la bulle.
+     */
+    onAccount?: ((identifier: string) => void) | undefined;
+}
+/**
+ * Ce qu'un transport de process (stdio) a reçu : une ligne, sans en-tête ni
+ * adresse.
+ */
+export interface IMcpStdioRequest {
+    /** La ligne reçue, telle quelle — un message JSON-RPC, en principe. */
+    line: string;
+    /** Abattu quand le client s'en va (entrée standard fermée). */
+    signal?: AbortSignal | undefined;
+    /**
+     * Ouvre le puits où écrire les notifications de l'appel, puis sa réponse
+     * finale — absent, la progression devient muette.
+     */
+    openStream?: (() => IMcpEventSink | Promise<IMcpEventSink>) | undefined;
+}
+/** Ce que l'environnement fournit à une réponse — `serve()` le lit seul. */
+export interface IMcpGateRuntime {
+    /** Les modules chargés, pour une porte `tools: "modules"`. */
+    modules?: Readonly<Record<string, unknown>> | undefined;
+    /** Qui sait valider un jeton — requis dès qu'un serveur d'autorisation est déclaré. */
+    verifier?: IAccessTokenVerifier | undefined;
+    /**
+     * Qui retrouve le compte qu'un jeton désigne — requis par un outil
+     * `actsForUser` ; absent, un tel outil refuse de s'exécuter.
+     */
+    accountResolver?: IAccessAccountResolver | undefined;
+    /** Identité annoncée ; défaut : `name`/`version` de la porte, sinon le projet. */
+    serverInfo?: IServerInfo | undefined;
+    /** Journal de la porte ; muet si absent. */
+    log?: ((message: string, severity: McpGateSeverity) => void) | undefined;
+}
+/** Réponse DÉCRITE par la mécanique — la porte l'écrit. */
+export type IMcpGateResponse<S extends IMcpEventSink = IMcpEventSink> = {
+    kind: "json";
+    status: number;
+    body: unknown;
+    headers?: Readonly<Record<string, string>>;
+} | {
+    kind: "empty";
+    status: number;
+    headers?: Readonly<Record<string, string>>;
+} | {
+    kind: "stream";
+    stream: S;
+};
+/** Une porte MCP définie — à servir depuis une action de controller. */
+export interface IMcpGate {
+    /** Les réglages effectifs, validés et figés. */
+    readonly settings: IMcpGateSettings;
+    /**
+     * Sert la requête courante d'un controller : `POST` sert le message, `GET` et
+     * `DELETE` rendent `405` (verbes retirés par la révision `2026-07-28`).
+     *
+     * @param controller - le controller de la porte.
+     * @param body - le corps reçu (`@Body()`).
+     * @returns ce que l'action doit rendre.
+     */
+    serve(controller: Controller, body: unknown): Promise<unknown>;
+    /**
+     * Répond à UN `POST` décrit — sans controller, éprouvable sans serveur (et
+     * réutilisable par un autre transport).
+     *
+     * @param request - ce que la porte a reçu.
+     * @param runtime - modules, vérificateur, identité, journal.
+     * @returns la réponse à écrire ; `stream` quand un flux SSE a été ouvert.
+     */
+    respond<S extends IMcpEventSink>(request: IMcpGateRequest<S>, runtime?: IMcpGateRuntime): Promise<IMcpGateResponse<S>>;
+    /**
+     * Répond à UNE ligne reçue sur l'entrée standard — le pendant de
+     * {@link IMcpGate.respond} pour un client qui lance lui-même son serveur.
+     *
+     * Ni origine, ni adresse, ni jeton : la frontière est celle du process.
+     * L'appelant est anonyme et porte les rôles d'une porte non protégée
+     * (`unprotectedRoles`, aucun par défaut) ; les outils réservés restent
+     * retenus. Les annulations (`notifications/cancelled`) visent l'unique
+     * appelant du process ; un appel annulé ne produit PLUS RIEN — ni
+     * progression, ni réponse (`empty`), comme la spec l'exige en stdio. Le
+     * statut de la réponse décrite n'a pas de sens hors HTTP : seul son corps
+     * s'écrit.
+     *
+     * @param request - la ligne reçue, et le puits où écrire.
+     * @param runtime - modules, identité, journal.
+     * @returns la réponse à écrire ; `stream` quand le puits a déjà tout reçu.
+     */
+    respondStdio(request: IMcpStdioRequest, runtime?: IMcpGateRuntime): Promise<IMcpGateResponse>;
+    /**
+     * Ce que la porte protège, à publier en RFC 9728 — une entrée, ou rien.
+     *
+     * Un service qui expose `publishedProtectedResources()` voit
+     * `@nodefony/framework` monter le document ; les scopes publiés sont ceux
+     * que le défi exige. Rôle éteint (aucun serveur d'autorisation) ⇒ rien : un
+     * document sans `authorization_servers` apprendrait au client qu'un jeton est
+     * nécessaire sans lui dire où l'obtenir.
+     *
+     * @param modules - les modules chargés, pour une porte `tools: "modules"`.
+     * @returns zéro ou une entrée.
+     */
+    protectedResources(modules?: Readonly<Record<string, unknown>>): readonly IProtectedResourceInput[];
+}
+/**
+ * Définit une porte MCP — UNE fois, à côté de son controller.
+ *
+ * La définition est validée et figée ici : une clé inconnue, une révision du
+ * protocole que le paquet installé ne sait pas servir, un outil mal formé, un
+ * nom en double ou réservé (`nodefony_`) lèvent une `BootConfigurationError`
+ * qui nomme la faute — au démarrage, jamais à la première requête. Chaque
+ * requête ne paie ensuite aucune validation.
+ *
+ * ```ts
+ * const shopGate = defineMcpGate({
+ *   name: "shop",
+ *   instructions: "Stock et commandes du magasin.",
+ *   tools: [stockTool, orderTool],
+ * });
+ *
+ * @route("shop-mcp", { path: "/mcp", requirements: { methods: ["POST", "GET", "DELETE"] } })
+ * mcp(@Body() body: unknown) {
+ *   return shopGate.serve(this, body);
+ * }
+ * ```
+ *
+ * Défauts : appels locaux seulement (`allowRemote: false`), aucune origine
+ * navigateur, aucun jeton exigé, AUCUN rôle accordé — les outils réservés
+ * (`scopes`, `requiresAuth`) restent retenus tant qu'une `authorization` ne
+ * les ouvre pas.
+ *
+ * @param definition - ce que la porte publie, à qui, et comment.
+ * @returns la porte, prête à servir.
+ * @throws BootConfigurationError si la définition est invalide.
+ */
+export declare function defineMcpGate(definition: IMcpGateDefinition): IMcpGate;

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

@@ -0,0 +1,89 @@
+/**
+ * Gardes du transport MCP — ce qui protège une porte locale SANS authentification.
+ *
+ * Ces deux contrôles ne sont pas un pis-aller : ce sont exactement les
+ * exigences que la spec pose au transport lui-même, indépendamment de toute
+ * autorisation (`transports/streamable-http` §Security & Endpoint) —
+ * « Servers **MUST** validate the `Origin` header on all incoming connections
+ * to prevent DNS rebinding attacks » et « When running locally, servers
+ * **SHOULD** bind only to localhost ».
+ *
+ * Fonctions **pures** : elles reçoivent ce qu'elles jugent, elles ne le lisent
+ * nulle part. C'est ce qui les rend éprouvables sans serveur ni requête réelle
+ * — et ce qui permet de vérifier le refus, qui est le comportement qui compte.
+ */
+/** Verdict d'une garde : passer, ou refuser en disant pourquoi. */
+export type GuardVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    why: string;
+};
+/** Ce que la garde a besoin de savoir d'une requête. */
+export interface IGuardInput {
+    /** En-tête `Origin`, `undefined` s'il est absent. */
+    origin?: string | undefined;
+    /** Adresse distante de la connexion (`socket.remoteAddress`). */
+    remoteAddress?: string | undefined;
+    /**
+     * La requête porte un en-tête de relais (`Forwarded`, `X-Forwarded-For`,
+     * `X-Real-IP`, `Via`) : elle a traversé un proxy, quelle que soit
+     * l'adresse de la connexion.
+     */
+    relayed?: boolean | undefined;
+}
+/** Réglages qui gouvernent les gardes (viennent de la config du module). */
+export interface IGuardPolicy {
+    /** Origines de navigateur admises ; vide = aucune. */
+    allowedOrigins: readonly string[];
+    /** Accepter une adresse distante non locale. */
+    allowRemote: boolean;
+}
+/**
+ * Une adresse est-elle celle de la machine locale ?
+ *
+ * Couvre les trois formes que Node rend selon la pile réseau : IPv4
+ * (`127.x.x.x`), IPv6 (`::1`), et l'IPv4 encapsulée en IPv6
+ * (`::ffff:127.0.0.1`) — la plus fréquente sur un serveur à double pile, et
+ * celle qu'une comparaison naïve à `"127.0.0.1"` rate.
+ *
+ * @param address - `socket.remoteAddress`, éventuellement absent
+ * @returns `true` si l'appel vient de cette machine
+ */
+/**
+ * Les en-têtes qu'un relais pose — leur présence suffit à dire que la requête
+ * n'est pas arrivée directement, quelle que soit l'adresse de la connexion.
+ */
+export declare const RELAY_HEADERS: readonly ["forwarded", "x-forwarded-for", "x-real-ip", "via"];
+/**
+ * La requête a-t-elle traversé un relais (proxy inverse, répartiteur) ?
+ *
+ * Un relais posé sur la MÊME machine fait arriver un client distant depuis la
+ * boucle locale : l'adresse de la connexion ne prouve alors plus rien. Toute
+ * porte qui exige la localité refuse donc aussi l'appel relayé — la porte MCP
+ * comme la porte de session par ticket, une seule règle.
+ *
+ * @param headers - en-têtes reçus (`request.headers` de Node)
+ * @returns `true` si un en-tête de relais non vide est présent
+ */
+export declare function isRelayedRequest(headers: Readonly<Record<string, string | string[] | undefined>>): boolean;
+export declare function isLocalAddress(address?: string): boolean;
+/**
+ * Décide si un appel MCP peut être servi.
+ *
+ * ⭐ **La règle sur `Origin` est contre-intuitive, et c'est elle qui protège.**
+ * Un client MCP légitime est un *process* (Cursor, Claude Code, un agent tiers)
+ * : il n'envoie **aucun** `Origin`, cet en-tête étant posé par les navigateurs.
+ * Une page web malveillante, elle, en pose **toujours** un lorsqu'elle vise
+ * `https://localhost:5152`. Donc : *absent* → on passe ; *présent et hors
+ * allowlist* → `403`. C'est ce qui referme le DNS rebinding, le seul vecteur
+ * réel contre un serveur MCP local.
+ *
+ * L'ordre des contrôles est délibéré : la localité d'abord, parce qu'un appel
+ * distant ne doit même pas apprendre quelles origines sont admises.
+ *
+ * @param input - ce que la requête présente
+ * @param policy - les réglages du module
+ * @returns le verdict, avec le motif quand il refuse
+ */
+export declare function checkMcpAccess(input: IGuardInput, policy: IGuardPolicy): GuardVerdict;

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

@@ -0,0 +1,48 @@
+import { type IJsonRpcNotification } from "nodefony";
+/**
+ * La progression d'un appel d'outil (`notifications/progress`) — règle PURE,
+ * horloge injectée.
+ *
+ * La norme (`basic/patterns/progress`) pose quatre exigences, toutes tenues
+ * ICI plutôt que dans chaque outil :
+ *  - une notification ne cite qu'un jeton fourni par une requête EN COURS — le
+ *    rapporteur se tait dès que l'outil a rendu sa réponse ({@link IMcpProgressReporter.end}) ;
+ *  - `progress` CROÎT à chaque notification — une valeur qui stagne ou recule
+ *    est ignorée, pas transmise ;
+ *  - la cadence est bornée (« SHOULD implement rate limiting ») ;
+ *  - sans jeton, rien n'est émis : l'agent n'a rien demandé.
+ */
+/** Intervalle minimal entre deux notifications de progression, en millisecondes. */
+export declare const MCP_PROGRESS_MIN_INTERVAL_MS = 100;
+/** Longueur maximale du `message` d'une progression, en caractères. */
+export declare const MCP_PROGRESS_MESSAGE_MAX = 1000;
+/** Un jeton de progression : chaîne ou entier (`progress` §Progress Flow). */
+export type McpProgressToken = string | number;
+/** Le rapporteur d'UN appel : ce que l'outil appelle, ce que la porte clôt. */
+export interface IMcpProgressReporter {
+    /**
+     * Signale un avancement ; ignoré s'il ne croît pas, s'il arrive trop tôt
+     * après le précédent, ou après {@link end}.
+     */
+    progress(progress: number, total?: number, message?: string): void;
+    /** L'outil a rendu sa réponse : plus aucune notification ne part. */
+    end(): void;
+}
+/**
+ * Lit le jeton de progression d'une requête (`params._meta.progressToken`).
+ *
+ * @param params - les `params` de la requête.
+ * @returns le jeton, ou `null` s'il manque ou n'est ni une chaîne ni un entier.
+ */
+export declare function readProgressToken(params: Record<string, unknown>): McpProgressToken | null;
+/**
+ * Fabrique le rapporteur de progression d'un appel.
+ *
+ * @param token - le jeton de la requête ({@link readProgressToken}), ou `null`.
+ * @param notify - émet une notification sur le flux de la réponse ; absent
+ *   quand la porte ne sait pas tenir de flux.
+ * @param now - horloge (millisecondes), injectée pour l'épreuve.
+ * @param minIntervalMs - intervalle minimal entre deux notifications.
+ * @returns un rapporteur, muet quand il n'y a ni jeton ni flux.
+ */
+export declare function createProgressReporter(token: McpProgressToken | null, notify: ((notification: IJsonRpcNotification) => void) | undefined, now?: () => number, minIntervalMs?: number): IMcpProgressReporter;

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

@@ -0,0 +1,107 @@
+/**
+ * Model Context Protocol — types et constantes du transport « Streamable HTTP ».
+ *
+ * Révision visée : **2026-07-28**, celle qui a supprimé les sessions de niveau
+ * protocole et le flux `GET`. C'est ce qui rend cette porte possible sans
+ * process dédié : chaque message est un `POST` autonome, donc un redémarrage du
+ * serveur de développement ne casse rien — le client rejoue simplement sa
+ * requête, et la réponse vient du code qui vient d'être rechargé.
+ *
+ * @see https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http
+ */
+import type { IJsonRpcSuccess, IJsonRpcFailure } from "nodefony";
+/** Révision PRÉFÉRÉE de ce serveur — celle qu'il met en tête de ce qu'il sait faire. */
+export declare const MCP_PROTOCOL_VERSION = "2026-07-28";
+/**
+ * Révision supposée quand un client n'en déclare AUCUNE.
+ *
+ * Ce n'est pas un choix : la spec impose de traiter une requête sans
+ * déclaration comme `2025-03-26`, et le SDK de référence en fait sa
+ * `DEFAULT_NEGOTIATED_PROTOCOL_VERSION`. Répondre notre préférée à un client
+ * muet reviendrait à lui imposer une révision qu'il n'a pas demandée.
+ */
+export declare const MCP_DEFAULT_NEGOTIATED_VERSION = "2025-03-26";
+/**
+ * Versions que ce serveur sait servir — publiées par `server/discover`, listées
+ * dans l'erreur `UnsupportedProtocolVersion`, et candidates à l'écho
+ * d'`initialize`. De la plus récente à la plus ancienne.
+ *
+ * 🔴 **N'en servir qu'une était un défaut, et il a coûté la connexion.** Le
+ * serveur annonçait `2026-07-28` à TOUT client, y compris à ceux qui
+ * demandaient autre chose — or aucun client déployé ne connaît cette révision :
+ * le SDK de référence (`@modelcontextprotocol/sdk@1.30.0`) porte
+ * `LATEST = 2025-11-25` et refuse net toute réponse hors de sa liste
+ * (« Server's protocol version is not supported »). Une porte parfaitement
+ * conforme à la dernière spec, et injoignable par tout le monde.
+ *
+ * Ces cinq révisions sont celles que la spec a publiées. Les servir toutes est
+ * honnête ici, et vérifiable : les quatre méthodes de ce serveur — `initialize`,
+ * `ping`, `tools/list`, `tools/call` — ont la même forme de REQUÊTE dans
+ * chacune. La forme du RÉSULTAT, elle, dépend de l'ÈRE du client : depuis
+ * `2026-07-28`, tout résultat porte `resultType` (MUST du schéma) et `_meta`
+ * serverInfo — servis par `eraResult` (server.ts) à un client moderne, jamais
+ * à un client legacy qui ne définit pas ces champs. Un test EXERCE chacune,
+ * plutôt que de se fier à cette phrase.
+ */
+export declare const MCP_SUPPORTED_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+/** Une révision du protocole que ce paquet sait servir. */
+export type McpProtocolVersion = (typeof MCP_SUPPORTED_VERSIONS)[number];
+/**
+ * Clé de métadonnée par laquelle un client MODERNE déclare sa révision.
+ *
+ * ⭐ **C'est la différence d'ÈRE, et elle commande tout le reste.** Jusqu'à
+ * `2025-11-25` (ère « legacy »), un client ouvrait une session par un handshake
+ * `initialize`. Depuis `2026-07-28` (ère « modern »), il n'y a plus de session :
+ * chaque requête porte elle-même sa version et les capacités du client, dans
+ * `params._meta`. Un serveur qui n'écouterait que `initialize` serait un
+ * serveur *legacy* — quelle que soit la version qu'il prétend annoncer.
+ */
+export declare const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+/** Clé de métadonnée portant l'identité du serveur dans `server/discover`. */
+export declare const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+export { JsonRpcError, jsonRpcSuccess, jsonRpcFailure, isNotification, } from "nodefony";
+export type { JsonRpcId, IJsonRpcMessage, IJsonRpcSuccess, IJsonRpcFailure, } from "nodefony";
+/**
+ * Codes réservés par la spec MCP, hors plage JSON-RPC standard.
+ *
+ * Ils ne sont pas décoratifs : un client s'en sert pour se rattraper seul —
+ * renégocier une version sur `-32022`, relire `tools/list` puis réessayer sur
+ * `-32020`. Rendre un `-32600` générique à leur place le priverait de cette
+ * reprise et transformerait un désaccord réparable en échec définitif.
+ */
+export declare const McpProtocolError: {
+    /**
+     * Les en-têtes HTTP contredisent le corps, ou un en-tête requis manque.
+     * La spec impose `400` **et** ce code (`streamable-http` §Server Validation).
+     */
+    readonly HEADER_MISMATCH: -32020;
+    /**
+     * La révision demandée n'est pas servie. La réponse **doit** lister celles
+     * qu'on sert, sans quoi le client n'a rien pour choisir.
+     */
+    readonly UNSUPPORTED_PROTOCOL_VERSION: -32022;
+};
+/** Ce que le serveur MCP rend, avant traduction en réponse HTTP. */
+export interface IMcpHttpReply {
+    /** Statut HTTP à poser. */
+    status: number;
+    /**
+     * Corps JSON, ou `null` pour un `202 Accepted` sans corps — la spec l'exige
+     * pour une notification acceptée.
+     */
+    body: IJsonRpcSuccess | IJsonRpcFailure | null;
+    /**
+     * L'exception levée par un outil, rendue À CÔTÉ de la réponse — jamais
+     * sérialisée.
+     *
+     * Le client ne reçoit qu'un message générique : le message d'une exception
+     * peut porter un chemin de disque, une chaîne de connexion ou un secret, et
+     * l'outil qui la lève est du code d'application arbitraire. Le détail reste
+     * donc au serveur, et c'est au TRANSPORT de le journaliser : le protocole est
+     * une fonction pure, qui n'a pas de journal.
+     */
+    failure?: {
+        tool: string;
+        error: unknown;
+    } | undefined;
+}