nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/mcp/protocol.js

@@ -0,0 +1,157 @@
+//#region src/mcp/protocol.ts
+/**
+* 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
+*/
+/** 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";
+/**
+* Chemin de l'endpoint MCP.
+*
+* ## Pourquoi `/nodefony/mcp`, et pas `/nodefony/devkit/api/mcp`
+*
+* Cette URL est un **contrat public** : elle est écrite dans le `.mcp.json` de
+* chaque utilisateur. Y faire figurer le module qui l'implémente la rendrait
+* caduque au premier déménagement — or ce serveur a vocation à bouger le jour
+* où une application voudra s'exposer en production (le devkit, lui, est
+* `policy: "dev"`). Le nom d'un module est un détail d'implémentation ; une URL
+* ne l'est pas.
+*
+* Le segment `api` est écarté pour une autre raison : il désigne le plan
+* d'administration JSON de Studio, avec son contrôle d'accès par rôle. Le MCP
+* n'est ni REST ni destiné à Studio — ranger deux protocoles sous le même
+* segment promettrait une parenté qui n'existe pas.
+*
+* Et `/mcp` à la racine, qui est la convention de fait ailleurs, prendrait un
+* chemin qui **appartient à l'application** : `/nodefony` est le préfixe
+* réservé du framework, donc sans collision possible.
+*
+* Constante et **non configurable** : une route décorée est statique, et un
+* réglage qui n'agirait pas serait pire qu'aucun réglage.
+*/
+const MCP_ENDPOINT_PATH = "/nodefony/mcp";
+/** Codes d'erreur JSON-RPC 2.0 employés par ce serveur. */
+const JsonRpcError = {
+	/** Corps illisible. */
+	PARSE_ERROR: -32700,
+	/** Message qui n'est pas une requête JSON-RPC valide. */
+	INVALID_REQUEST: -32600,
+	/** Méthode inconnue — la spec exige alors un `404` HTTP. */
+	METHOD_NOT_FOUND: -32601,
+	/** Paramètres absents ou mal typés. */
+	INVALID_PARAMS: -32602,
+	/** Échec côté serveur. */
+	INTERNAL_ERROR: -32603
+};
+/**
+* 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
+};
+/** Fabrique une réponse de succès. */
+function jsonRpcSuccess(id, result) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		result
+	};
+}
+/** Fabrique une réponse d'erreur. */
+function jsonRpcFailure(id, code, message, data) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: data === void 0 ? {
+			code,
+			message
+		} : {
+			code,
+			message,
+			data
+		}
+	};
+}
+/**
+* Un message est-il une NOTIFICATION (pas d'`id`) plutôt qu'une requête ?
+*
+* La distinction commande le statut HTTP : une notification acceptée rend
+* `202` **sans corps**, une requête rend son objet JSON.
+*/
+function isNotification(message) {
+	return message.id === void 0 || message.id === null;
+}
+//#endregion
+export { JsonRpcError, MCP_DEFAULT_NEGOTIATED_VERSION, MCP_ENDPOINT_PATH, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_VERSIONS, META_PROTOCOL_VERSION, META_SERVER_INFO, McpProtocolError, isNotification, jsonRpcFailure, jsonRpcSuccess };

package/dist/node/mcp/server.js

@@ -0,0 +1,216 @@
+import { JsonRpcError, MCP_DEFAULT_NEGOTIATED_VERSION, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_VERSIONS, META_PROTOCOL_VERSION, META_SERVER_INFO, McpProtocolError, isNotification, jsonRpcFailure, jsonRpcSuccess } from "./protocol.js";
+import { callMcpTool, publishMcpTools } from "./tools.js";
+//#region src/mcp/server.ts
+/**
+* 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 (typeof meta !== "object" || meta === null) 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: {
+			...result._meta,
+			[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 = "Outils d'introspection d'une application Nodefony — ils répondent depuis l'application qui TOURNE, pas depuis une lecture des sources. " + (names.length > 0 ? `Disponibles ici : ${names.join(", ")}. Commence par la carte de visite si tu arrives sur cette application.` : "Aucun outil n'est servi à cet appelant.");
+	const withheld = context.withheldCount ?? 0;
+	if (withheld <= 0) return base;
+	return `${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 — 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.`;
+}
+/**
+* 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) {
+	const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : metaVersion(params);
+	if (asked === void 0) return MCP_DEFAULT_NEGOTIATED_VERSION;
+	return MCP_SUPPORTED_VERSIONS.includes(asked) ? asked : MCP_PROTOCOL_VERSION;
+}
+/**
+* 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) {
+	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 (!MCP_SUPPORTED_VERSIONS.includes(declared)) return {
+		status: 400,
+		body: jsonRpcFailure(id, McpProtocolError.UNSUPPORTED_PROTOCOL_VERSION, "Unsupported protocol version", {
+			supported: [...MCP_SUPPORTED_VERSIONS],
+			requested: declared
+		})
+	};
+	return null;
+}
+/**
+* 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 = {}) {
+	if (message === null || typeof message !== "object" || typeof message.method !== "string") return {
+		status: 400,
+		body: jsonRpcFailure(null, JsonRpcError.INVALID_REQUEST, "message JSON-RPC invalide : `method` manquante")
+	};
+	const method = message.method;
+	if (isNotification(message)) return {
+		status: 202,
+		body: null
+	};
+	const id = message.id;
+	const params = typeof message.params === "object" && message.params !== null ? message.params : {};
+	const refusal = checkProtocolVersion(id, params, headers);
+	if (refusal) return refusal;
+	const modern = isModernRequest(params, headers);
+	switch (method) {
+		case "initialize": return {
+			status: 200,
+			body: jsonRpcSuccess(id, {
+				protocolVersion: negotiateVersion(params),
+				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) }))
+		};
+		case "tools/call": {
+			const name = typeof params.name === "string" ? params.name : "";
+			const args = typeof params.arguments === "object" && params.arguments !== null ? params.arguments : {};
+			if (!name) return {
+				status: 400,
+				body: jsonRpcFailure(id, JsonRpcError.INVALID_PARAMS, "`name` est requis pour `tools/call`")
+			};
+			let result;
+			try {
+				result = await callMcpTool(name, args, context.tools, context.caller);
+			} catch (error) {
+				return {
+					status: 200,
+					body: jsonRpcFailure(id, JsonRpcError.INTERNAL_ERROR, `l'outil « ${name} » a échoué : ${error.message}`)
+				};
+			}
+			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 }))
+			};
+		}
+		default: return {
+			status: 404,
+			body: jsonRpcFailure(id, JsonRpcError.METHOD_NOT_FOUND, `méthode inconnue « ${method} »`)
+		};
+	}
+}
+//#endregion
+export { handleMcpMessage };