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

package/dist/nodefony/mcp/guard.js

@@ -0,0 +1,82 @@
+// nodefony/mcp/guard.ts
+/**
+* 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.
+*/
+const RELAY_HEADERS = [
+	"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
+*/
+function isRelayedRequest(headers) {
+	return RELAY_HEADERS.some((name) => {
+		const value = headers[name];
+		const first = Array.isArray(value) ? value[0] : value;
+		return first !== void 0 && first !== "";
+	});
+}
+function isLocalAddress(address) {
+	if (!address) return false;
+	const bare = address.startsWith("::ffff:") ? address.slice(7) : address;
+	if (bare === "::1" || bare === "localhost") return true;
+	return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(bare);
+}
+/**
+* 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
+*/
+function checkMcpAccess(input, policy) {
+	if (!policy.allowRemote && !isLocalAddress(input.remoteAddress)) return {
+		allowed: false,
+		why: `adresse non locale (${input.remoteAddress ?? "inconnue"}) — voir l'option \`allowRemote\` du serveur MCP`
+	};
+	if (!policy.allowRemote && input.relayed === true) return {
+		allowed: false,
+		why: "appel relayé (en-tête Forwarded, X-Forwarded-For, X-Real-IP ou Via) sur une porte locale — la localité ne se prouve pas à travers un relais ; voir l'option `allowRemote` du serveur MCP"
+	};
+	if (input.origin !== void 0 && input.origin !== "") {
+		if (!policy.allowedOrigins.includes(input.origin)) return {
+			allowed: false,
+			why: `origine « ${input.origin} » non admise — voir l'option \`allowedOrigins\` du serveur MCP`
+		};
+	}
+	return { allowed: true };
+}
+export { RELAY_HEADERS, checkMcpAccess, isLocalAddress, isRelayedRequest };

package/dist/nodefony/mcp/progress.js

@@ -0,0 +1,74 @@
+import { jsonRpcNotification } from "nodefony";
+// nodefony/mcp/progress.ts
+/**
+* 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. */
+const MCP_PROGRESS_MIN_INTERVAL_MS = 100;
+/** Longueur maximale du `message` d'une progression, en caractères. */
+const MCP_PROGRESS_MESSAGE_MAX = 1e3;
+/**
+* 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.
+*/
+function readProgressToken(params) {
+	const meta = params._meta;
+	if (typeof meta !== "object" || meta === null || !("progressToken" in meta)) return null;
+	const token = meta.progressToken;
+	if (typeof token === "string") return token;
+	if (typeof token === "number" && Number.isInteger(token)) return token;
+	return null;
+}
+/** Le rapporteur muet : aucun jeton, ou aucune porte capable d'un flux. */
+const SILENT = {
+	progress: () => {},
+	end: () => {}
+};
+/**
+* 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.
+*/
+function createProgressReporter(token, notify, now = Date.now, minIntervalMs = 100) {
+	if (token === null || notify === void 0) return SILENT;
+	let ended = false;
+	let last = Number.NEGATIVE_INFINITY;
+	let lastAt = Number.NEGATIVE_INFINITY;
+	return {
+		progress(progress, total, message) {
+			if (ended || !Number.isFinite(progress) || progress <= last) return;
+			const at = now();
+			if (at - lastAt < minIntervalMs) return;
+			last = progress;
+			lastAt = at;
+			const params = {
+				progressToken: token,
+				progress
+			};
+			if (total !== void 0 && Number.isFinite(total)) params.total = total;
+			if (message !== void 0) params.message = message.slice(0, MCP_PROGRESS_MESSAGE_MAX);
+			notify(jsonRpcNotification("notifications/progress", params));
+		},
+		end() {
+			ended = true;
+		}
+	};
+}
+export { MCP_PROGRESS_MESSAGE_MAX, MCP_PROGRESS_MIN_INTERVAL_MS, createProgressReporter, readProgressToken };

package/dist/nodefony/mcp/protocol.js

@@ -0,0 +1,76 @@
+import { JsonRpcError, isNotification, jsonRpcFailure, jsonRpcSuccess } from "nodefony";
+// nodefony/mcp/protocol.ts
+/** Révision PRÉFÉRÉE de ce serveur — celle qu'il met en tête de ce qu'il sait faire. */
+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.
+*/
+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.
+*/
+const MCP_SUPPORTED_VERSIONS = [
+	MCP_PROTOCOL_VERSION,
+	"2025-11-25",
+	"2025-06-18",
+	MCP_DEFAULT_NEGOTIATED_VERSION,
+	"2024-11-05"
+];
+/**
+* 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.
+*/
+const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+/** Clé de métadonnée portant l'identité du serveur dans `server/discover`. */
+const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+/**
+* 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.
+*/
+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).
+	*/
+	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.
+	*/
+	UNSUPPORTED_PROTOCOL_VERSION: -32022
+};
+export { JsonRpcError, MCP_DEFAULT_NEGOTIATED_VERSION, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_VERSIONS, META_PROTOCOL_VERSION, META_SERVER_INFO, McpProtocolError, isNotification, jsonRpcFailure, jsonRpcSuccess };

package/dist/nodefony/mcp/server.js

@@ -0,0 +1,302 @@
+import { JsonRpcError, MCP_DEFAULT_NEGOTIATED_VERSION, MCP_SUPPORTED_VERSIONS, META_PROTOCOL_VERSION, META_SERVER_INFO, McpProtocolError, jsonRpcFailure, jsonRpcSuccess } from "./protocol.js";
+import { createProgressReporter, readProgressToken } from "./progress.js";
+import { callMcpTool, publishMcpTools } from "./tools.js";
+import { classifyJsonRpcFrame, isPlainObject } from "nodefony";
+// nodefony/mcp/server.ts
+/**
+* Défaut sûr : rien n'est frais, rien n'est partageable — le catalogue d'une
+* porte varie selon l'autorisation présentée, et en développement à chaque
+* rechargement.
+*/
+const DEFAULT_CACHE_HINTS = Object.freeze({
+	ttlMs: 0,
+	cacheScope: "private"
+});
+/** Phrase d'ouverture des `instructions` quand la porte n'en donne pas. */
+const DEFAULT_INSTRUCTIONS = "Outils de cette application.";
+/** Signal des appels sans transport qui annule : jamais abattu, partagé. */
+const NEVER_ABORTED = new AbortController().signal;
+/**
+* Extrait la révision déclarée dans `params._meta`, s'il y en a une.
+*
+* Un client MODERNE la pose à chaque requête ; un client LEGACY ne pose rien
+* et négocie par `initialize`. L'absence n'est donc pas une faute : c'est un
+* indice d'ère.
+*/
+function metaVersion(params) {
+	const meta = params._meta;
+	if (!isPlainObject(meta)) return void 0;
+	const value = meta[META_PROTOCOL_VERSION];
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* La requête relève-t-elle de l'ère MODERNE (≥ 2026-07-28) ?
+*
+* L'ère se lit de la déclaration du client — `_meta` OU en-tête, la spec les
+* fait équivalents (leur discordance est déjà refusée en amont). Aucune
+* déclaration = client legacy. Les révisions sont des dates ISO : la
+* comparaison lexicale EST la comparaison chronologique, et une révision
+* future reste moderne sans qu'on y revienne.
+*/
+function isModernRequest(params, headers) {
+	const declared = metaVersion(params) ?? headers.protocolVersion;
+	return declared !== void 0 && declared >= "2026-07-28";
+}
+/**
+* Donne à un résultat la FORME de l'ère du client.
+*
+* Ère moderne : `resultType` est un **MUST** du schéma (« Servers implementing
+* this protocol version MUST include this field ») et `_meta` serverInfo un
+* SHOULD sur chaque réponse. Payé par une connexion réelle : le client
+* officiel (claude-code 2.1.238) rejoue quatre fois un `tools/list` moderne
+* sans `resultType`, puis n'enregistre AUCUN outil — serveur « connected »,
+* porte morte. Un serveur qui annonce l'ère moderne et répond en forme legacy
+* est injoignable, exactement comme l'inverse l'était (cf
+* `MCP_SUPPORTED_VERSIONS`).
+*
+* Ère legacy : résultat inchangé — un client ≤ 2025-11-25 ne définit pas ces
+* champs, les lui envoyer serait du bruit d'une autre ère.
+*/
+function eraResult(modern, serverInfo, result) {
+	if (!modern) return result;
+	return {
+		...result,
+		resultType: "complete",
+		_meta: {
+			...isPlainObject(result._meta) ? result._meta : void 0,
+			[META_SERVER_INFO]: serverInfo
+		}
+	};
+}
+/**
+* Compose les `instructions` annoncées au client (`initialize` aujourd'hui ;
+* `server/discover` le jour de sa réactivation — cf le retrait plus bas).
+*
+* ⭐ **Le seul endroit où un catalogue filtré peut cesser de mentir par
+* omission.** Un outil retenu faute d'autorisation est, pour le client,
+* indistinguable d'un outil inexistant — c'est voulu (ne pas révéler ce qu'on
+* protège), mais pris au pied de la lettre cela ferait conclure « cette
+* application n'a rien de plus », quand la vérité est « rien de plus POUR TOI,
+* en l'état ». Un agent qui l'ignore ne demandera jamais de jeton.
+*
+* Le compromis retenu : dire qu'il EXISTE des outils réservés et combien, sans
+* jamais les nommer ni dire ce qu'ils font. C'est strictement moins que ce
+* qu'un `401` normalisé révélera le jour où le rôle *resource server* sera
+* branché (RFC 6750 + RFC 9728 disent « il faut un jeton » ET où l'obtenir) —
+* donc rien n'est concédé ici qui ne le soit déjà par la norme.
+*
+* Zéro outil retenu → aucune phrase : annoncer une réserve vide entraînerait un
+* agent à chercher une porte qui n'existe pas.
+*/
+function discoverInstructions(context) {
+	const names = context.tools.map((tool) => tool.name);
+	const base = `${context.instructions ?? DEFAULT_INSTRUCTIONS} ` + (names.length > 0 ? `Disponibles ici : ${names.join(", ")}.` : "Aucun outil n'est servi à cet appelant.");
+	const withheld = context.withheldCount ?? 0;
+	if (withheld <= 0) return base;
+	const reserved = `${base} ${withheld} outil(s) supplémentaire(s) sont RÉSERVÉS et ne figurent pas dans \`tools/list\` : ils exigent une autorisation que cette requête ne présente pas. Ce n'est pas une panne, et rien ne sert de les deviner — `;
+	return context.authorizable === true ? `${reserved}le document de ressource protégée de cette porte (RFC 9728) nomme les scopes à demander, et le défi du refus dit où le lire. Ce sont eux qu'il faut faire porter au jeton, pas un contournement.` : `${reserved}cette porte n'en reçoit aucune : ils ne sont servis que par une porte HTTP protégée de l'application, à qui l'on présente un jeton.`;
+}
+/**
+* Choisit la révision à ANNONCER en réponse à `initialize`.
+*
+* 🔴 **Répondre sa propre révision préférée est un bug, pas une politesse.** La
+* spec est explicite : si le serveur sait servir la version demandée, il DOIT
+* répondre celle-là ; sinon, une autre qu'il sait servir — à charge pour le
+* client de raccrocher. Ignorer `params.protocolVersion` et annoncer sa
+* dernière révision rend la porte injoignable par tout client qui ne la connaît
+* pas encore, ce qui est le cas de TOUS tant qu'un SDK n'a pas rattrapé la spec.
+* Vécu : un serveur annonçant `2026-07-28` était refusé par
+* `@modelcontextprotocol/sdk@1.30.0` (« Server's protocol version is not
+* supported ») — conforme à la dernière norme, et parlant à personne.
+*
+* Un client MUET n'obtient pas notre préférée non plus, mais
+* {@link MCP_DEFAULT_NEGOTIATED_VERSION} : c'est la révision que la spec impose
+* de supposer en l'absence de déclaration.
+*
+* @param params - `params` de la requête `initialize`
+* @returns la révision à annoncer
+*/
+function negotiateVersion(params, versions) {
+	const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : metaVersion(params);
+	const preferred = versions[0] ?? "2026-07-28";
+	if (asked === void 0) return versions.includes("2025-03-26") ? MCP_DEFAULT_NEGOTIATED_VERSION : preferred;
+	return versions.includes(asked) ? asked : preferred;
+}
+/**
+* Contrôle la cohérence et le support de la révision annoncée.
+*
+* Deux refus distincts, et la spec impose les deux :
+*  - **en-tête ≠ `_meta`** → `400` + `HeaderMismatch` (`-32020`). Le motif est
+*    une vraie faille : un répartiteur de charge peut router sur l'en-tête
+*    pendant que le serveur exécute d'après le corps — deux sources de vérité
+*    pour une même requête.
+*  - **révision inconnue** → `400` + `UnsupportedProtocolVersion` (`-32022`),
+*    **avec la liste de celles qu'on sert** : c'est elle qui permet au client
+*    de se rattraper au lieu d'abandonner.
+*
+* @returns `null` si tout va bien, sinon la réponse de refus
+*/
+function checkProtocolVersion(id, params, headers, versions) {
+	const fromMeta = metaVersion(params);
+	const fromHeader = headers.protocolVersion;
+	if (fromMeta && fromHeader && fromMeta !== fromHeader) return {
+		status: 400,
+		body: jsonRpcFailure(id, McpProtocolError.HEADER_MISMATCH, "MCP-Protocol-Version ne correspond pas à _meta", {
+			header: fromHeader,
+			meta: fromMeta
+		})
+	};
+	const declared = fromMeta ?? fromHeader;
+	if (!declared) return null;
+	if (!versions.includes(declared)) return {
+		status: 400,
+		body: jsonRpcFailure(id, McpProtocolError.UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version", {
+			supported: [...versions],
+			requested: declared
+		})
+	};
+	return null;
+}
+/**
+* Refus d'un message qui n'est pas une requête MCP acceptable : `400` + `-32600`.
+*
+* @param id - l'`id` de la requête quand il a été lu, sinon `null`
+* @param message - motif, une phrase
+* @returns la réponse HTTP à écrire
+*/
+function invalidRequest(id, message) {
+	return {
+		status: 400,
+		body: jsonRpcFailure(id, JsonRpcError.INVALID_REQUEST, message)
+	};
+}
+/**
+* Transmet une `notifications/cancelled` à la table des appels en cours.
+*
+* Une annulation mal formée s'IGNORE, comme celle qui ne trouve rien : la spec
+* permet d'ignorer une annulation, et une notification n'a pas de réponse où
+* dire la faute. Le motif n'est jamais renvoyé, seulement journalisé.
+*
+* @param params - paramètres de la notification
+* @param context - porte qui tient la table, liée à l'appelant
+*/
+function cancelRequest(params, context) {
+	const requestId = params.requestId;
+	if (typeof requestId !== "string" && !(typeof requestId === "number" && Number.isInteger(requestId))) return;
+	const reason = typeof params.reason === "string" ? params.reason : void 0;
+	context.cancellation?.cancel(requestId, reason);
+}
+/**
+* Traite UN message JSON-RPC.
+*
+* @param message - corps du `POST`, déjà parsé
+* @param context - outils autorisés et briques qui répondent
+* @param headers - en-têtes du transport (`MCP-Protocol-Version`)
+* @returns statut HTTP et corps à écrire (corps `null` = `202` sans contenu)
+*/
+async function handleMcpMessage(message, context, headers = {}) {
+	const kind = classifyJsonRpcFrame(message);
+	if (kind === "invalid") return invalidRequest(null, "message JSON-RPC 2.0 invalide");
+	if (kind === "response") return invalidRequest(null, "un client MCP n'envoie pas de réponse JSON-RPC sur cette porte");
+	const frame = message;
+	const method = frame.method;
+	const replyId = kind === "request" ? frame.id : null;
+	if (typeof replyId === "number" && !Number.isInteger(replyId)) return invalidRequest(null, "l'identifiant d'une requête MCP est une chaîne ou un entier");
+	const rawParams = frame.params;
+	let params = {};
+	if (rawParams !== void 0) {
+		if (Array.isArray(rawParams)) return {
+			status: 400,
+			body: jsonRpcFailure(replyId, JsonRpcError.INVALID_PARAMS, "`params` doit être un objet nommé : le MCP n'emploie pas de paramètres positionnels")
+		};
+		if (!isPlainObject(rawParams)) return invalidRequest(replyId, "`params` doit être une valeur structurée (JSON-RPC 2.0 §4.2)");
+		params = rawParams;
+	}
+	if (kind === "notification") {
+		if (method === "notifications/cancelled") cancelRequest(params, context);
+		return {
+			status: 202,
+			body: null
+		};
+	}
+	const id = frame.id;
+	const versions = context.versions ?? MCP_SUPPORTED_VERSIONS;
+	const refusal = checkProtocolVersion(id, params, headers, versions);
+	if (refusal) return refusal;
+	const modern = isModernRequest(params, headers);
+	switch (method) {
+		case "initialize": return {
+			status: 200,
+			body: jsonRpcSuccess(id, {
+				protocolVersion: negotiateVersion(params, versions),
+				capabilities: { tools: {} },
+				serverInfo: context.serverInfo,
+				instructions: discoverInstructions(context)
+			})
+		};
+		case "ping": return {
+			status: 200,
+			body: jsonRpcSuccess(id, eraResult(modern, context.serverInfo, {}))
+		};
+		case "tools/list": return {
+			status: 200,
+			body: jsonRpcSuccess(id, eraResult(modern, context.serverInfo, {
+				tools: publishMcpTools(context.tools),
+				...modern ? context.cache ?? DEFAULT_CACHE_HINTS : {}
+			}))
+		};
+		case "tools/call": {
+			const name = typeof params.name === "string" ? params.name : "";
+			const rawArgs = params.arguments;
+			if (rawArgs !== void 0 && !isPlainObject(rawArgs)) return {
+				status: 400,
+				body: jsonRpcFailure(id, JsonRpcError.INVALID_PARAMS, "`arguments` doit être un objet nommé pour `tools/call`")
+			};
+			const args = rawArgs ?? {};
+			if (!name) return {
+				status: 400,
+				body: jsonRpcFailure(id, JsonRpcError.INVALID_PARAMS, "`name` est requis pour `tools/call`")
+			};
+			const reporter = createProgressReporter(readProgressToken(params), context.transport?.notify);
+			const call = context.cancellation?.open(id);
+			const closed = context.transport?.signal;
+			const signal = call ? closed ? AbortSignal.any([closed, call.signal]) : call.signal : closed ?? NEVER_ABORTED;
+			let result;
+			try {
+				result = await callMcpTool(name, args, context.tools, context.caller, {
+					signal,
+					progress: (value, total, text) => reporter.progress(value, total, text)
+				});
+			} catch (error) {
+				return {
+					status: 200,
+					body: jsonRpcFailure(id, JsonRpcError.INTERNAL_ERROR, `l'outil « ${name} » a échoué — détail dans le journal du serveur`),
+					failure: {
+						tool: name,
+						error
+					}
+				};
+			} finally {
+				reporter.end();
+				call?.close();
+			}
+			if (result === null) return {
+				status: 200,
+				body: jsonRpcFailure(id, JsonRpcError.INVALID_PARAMS, `outil inconnu « ${name} » — voir tools/list`)
+			};
+			return {
+				status: 200,
+				body: jsonRpcSuccess(id, eraResult(modern, context.serverInfo, { ...result }))
+			};
+		}
+		case "subscriptions/listen": return {
+			status: 404,
+			body: jsonRpcFailure(id, JsonRpcError.METHOD_NOT_FOUND, "`subscriptions/listen` n'est pas servi : le catalogue ne change qu'au rechargement de l'application, qui redémarre son process — rappeler `tools/list` après une coupure rend l'état à jour.")
+		};
+		default: return {
+			status: 404,
+			body: jsonRpcFailure(id, JsonRpcError.METHOD_NOT_FOUND, `méthode inconnue « ${method} »`)
+		};
+	}
+}
+export { handleMcpMessage };

package/dist/nodefony/mcp/sessionTicket.js

@@ -0,0 +1,89 @@
+import { createHash, randomBytes } from "node:crypto";
+// nodefony/mcp/sessionTicket.ts
+/** Durée de vie d'un ticket : le temps d'une requête de connexion en boucle locale. */
+const SESSION_TICKET_TTL_MS = 1e4;
+/**
+* Tickets en attente au plus. Un outil en émet UN et le rachète aussitôt :
+* en atteindre huit signale un usage anormal, refusé plutôt qu'accumulé.
+*/
+const SESSION_TICKET_MAX_PENDING = 8;
+/** Longueur d'un ticket : 32 octets d'aléa en base64url, sans remplissage. */
+const SESSION_TICKET_LENGTH = 43;
+/** En-tête qui porte le ticket vers la route de connexion par ticket. */
+const SESSION_TICKET_HEADER = "x-nodefony-session-ticket";
+const TICKET_SHAPE = /^[A-Za-z0-9_-]+$/u;
+/** Empreinte sous laquelle un ticket est rangé : le ticket brut n'est jamais gardé. */
+function fingerprintSessionTicket(ticket) {
+	return createHash("sha256").update(ticket).digest("hex");
+}
+/**
+* Tickets à usage unique qui autorisent l'ouverture d'UNE session pour une
+* identité donnée — celle au nom de laquelle un outil MCP tire de vraies
+* requêtes HTTP vers l'application.
+*
+* Le ticket ne quitte jamais le process : l'outil qui l'émet est celui qui le
+* présente, en boucle locale, à la route de connexion de sa porte
+* (`defineTicketSessionGate`). L'identité est fixée à l'émission — la
+* requête de rachat n'en porte aucune, donc ne peut pas en choisir une autre.
+*
+* Aucune minuterie : les tickets expirés sont purgés à chaque émission et à
+* chaque rachat, sur au plus {@link SESSION_TICKET_MAX_PENDING} entrées.
+*/
+var SessionTicketStore = class {
+	#now;
+	#fingerprint;
+	#pending = /* @__PURE__ */ new Map();
+	/**
+	* @param options - horloge et empreinte, injectées par les tests.
+	*/
+	constructor(options = {}) {
+		this.#now = options.now ?? Date.now;
+		this.#fingerprint = options.fingerprint ?? fingerprintSessionTicket;
+	}
+	/** Nombre de tickets émis, ni rachetés ni expirés. */
+	get pending() {
+		this.#purge();
+		return this.#pending.size;
+	}
+	/**
+	* Émet un ticket pour `identifier`, valable {@link SESSION_TICKET_TTL_MS} ms.
+	*
+	* @param identifier - identifiant du compte pour lequel la session s'ouvrira.
+	* @returns le ticket, à présenter dans {@link SESSION_TICKET_HEADER}.
+	* @throws Error - identifiant vide, ou plafond de tickets en attente atteint.
+	*/
+	issue(identifier) {
+		if (identifier.length === 0) throw new Error("ticket de session : identifiant vide");
+		this.#purge();
+		if (this.#pending.size >= 8) throw new Error(`ticket de session : 8 tickets déjà en attente`);
+		const ticket = randomBytes(32).toString("base64url");
+		this.#pending.set(this.#fingerprint(ticket), {
+			identifier,
+			expiresAt: this.#now() + SESSION_TICKET_TTL_MS
+		});
+		return ticket;
+	}
+	/**
+	* Rachète un ticket : le retire, et rend l'identité pour laquelle il a été émis.
+	*
+	* La forme est contrôlée AVANT l'empreinte : une entrée hostile (1 Mo, autre
+	* type) ne coûte pas un hachage.
+	*
+	* @param ticket - valeur reçue, non fiable.
+	* @returns l'identifiant, ou `null` (absent, malformé, inconnu, expiré, déjà racheté).
+	*/
+	redeem(ticket) {
+		if (typeof ticket !== "string" || ticket.length !== 43 || !TICKET_SHAPE.test(ticket)) return null;
+		this.#purge();
+		const key = this.#fingerprint(ticket);
+		const entry = this.#pending.get(key);
+		if (entry === void 0) return null;
+		this.#pending.delete(key);
+		return entry.identifier;
+	}
+	#purge() {
+		const now = this.#now();
+		for (const [key, entry] of this.#pending) if (entry.expiresAt < now) this.#pending.delete(key);
+	}
+};
+export { SESSION_TICKET_HEADER, SESSION_TICKET_LENGTH, SESSION_TICKET_MAX_PENDING, SESSION_TICKET_TTL_MS, SessionTicketStore, fingerprintSessionTicket };