nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/mcp/tools.js

@@ -0,0 +1,861 @@
+import { skippedChecks } from "../kernel/checks/report.js";
+import { INSPECT_SUBJECTS, callAdminEndpoint, readAdminSubject } from "../kernel/inspect/adminSubjects.js";
+import { collectDoctorReport, countCheckFindings } from "../kernel/checks/runDoctor.js";
+import { ADMIN_SCOPE_READ, rolesFromScopes } from "../kernel/adminPlane/adminCaller.js";
+import { lookupSymbol, readSymbolsGraph } from "../cli/symbols.js";
+import { outlineMarkdown } from "../kernel/inspect/docOutline.js";
+import { adminReadCatalog, findAdminReadEntry } from "../kernel/adminPlane/catalog.js";
+//#region src/mcp/tools.ts
+/**
+* Outils MCP : le **catalogue intégré** du framework, et la **collecte** de ceux
+* qu'une application déclare.
+*
+* ⚠️ **Rien n'est calculé ici.** Chaque outil intégré traduit un appel JSON-RPC
+* vers une brique qui répond DÉJÀ à une autre porte : `inspect` lit le plan
+* d'administration par {@link readAdminSubject} (la même fonction que la
+* commande `nodefony inspect`), `check` appelle {@link collectDoctorReport} (la
+* même que `nodefony doctor`). Une source, plusieurs portes — un outil qui
+* recalculerait sa réponse finirait par contredire la commande, et c'est lui
+* qu'on croirait sur parole.
+*
+* ⭐ **La description d'un outil est le premier critère de son déclenchement.**
+* Un modèle n'appelle pas ce qu'il ne comprend pas : le POC de 2026-05 l'a payé
+* cash — un outil à description neutre n'a jamais été appelé, un skill
+* auto-déclenché prenait la main à chaque fois. Ces descriptions disent donc ce
+* que l'outil rend ET quand s'en servir, pas seulement son nom.
+*
+* ## 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.
+*/
+const MCP_TEXT_MAX_CHARS = 32e3;
+/** Ce qu'on garde d'une valeur dans une vue d'ensemble : la surface. */
+const SCALAR_MAX_CHARS = 120;
+/**
+* La SURFACE d'un objet — ses champs scalaires courts, sans sa profondeur.
+*
+* Ce qui pèse dans un inventaire n'est presque jamais ce qu'on y cherche : sur
+* une route, `name`/`path`/`controller` tiennent en cent caractères, et c'est la
+* description, les tableaux de tags et les objets imbriqués qui font les 47 ko.
+* On jette donc la profondeur et on garde la surface — TOUTES les entrées
+* restent visibles, ce qu'un échantillon des N premières ne permet pas : une
+* question portant sur la 100ᵉ recevrait une réponse fausse, et l'agent n'aurait
+* aucun moyen de le savoir.
+*/
+function surfaceOf(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return `[${value.length}]`;
+	const kept = {};
+	for (const [key, v] of Object.entries(value)) if (v === null || typeof v === "number" || typeof v === "boolean") kept[key] = v;
+	else if (typeof v === "string" && v.length <= SCALAR_MAX_CHARS) kept[key] = v;
+	else if (Array.isArray(v) && v.every((e) => typeof e === "string")) {
+		if (v.join(",").length <= SCALAR_MAX_CHARS) kept[key] = v;
+	}
+	return kept;
+}
+/**
+* Une donnée trop volumineuse, ramenée à une RÉPONSE.
+*
+* Deux formes, selon ce qu'on a sous la main :
+*  - **un tableau** rend son `count` — la première chose qu'on veut d'une liste,
+*    et celle qu'un modèle calcule mal et cher — puis ses entrées en surface ;
+*  - **un objet** rend ses clés de premier niveau : c'est la carte qui permet de
+*    demander ensuite la bonne branche (pour `config`, `inspect module <nom>`).
+*
+* Dans les deux cas la réponse DIT ce qu'elle a fait, et elle le dit EN TÊTE.
+* Une troncature muette est pire que pas de troncature — l'agent croit tout
+* tenir ; une troncature annoncée APRÈS vingt mille caractères d'entrées ne vaut
+* guère mieux, il a déjà décidé quoi faire de ce qu'il a lu. Mesuré : sur la
+* tâche « annonce le nombre de routes », l'agent recevait `count` puis 88
+* entrées puis, tout en bas, l'avertissement — et repartait recompter les
+* entrées visibles au lieu de lire le compte exact qu'on venait de lui donner.
+*
+* Et la note ne renvoie PAS vers un affinement : `routes`, `services` ou
+* `modules` n'acceptent aucun filtre, si bien que « affine la demande » nommait
+* un geste qui n'existe pas. Elle désigne ce qui EST utilisable — `count`, exact
+* et portant sur la liste entière.
+*/
+function summarize(value, size) {
+	if (Array.isArray(value)) {
+		const items = value.map(surfaceOf);
+		let rendered = JSON.stringify({
+			count: value.length,
+			note: `count = ${value.length} : c'est le nombre EXACT, il porte sur la liste entière. Les entrées ci-dessous sont ramenées à leur surface (${size} caractères au complet) — demande le détail d'une entrée précise plutôt que la liste entière`,
+			items
+		}, null, 2);
+		if (rendered.length <= MCP_TEXT_MAX_CHARS) return rendered;
+		let keptCount = items.length;
+		while (keptCount > 1 && rendered.length > MCP_TEXT_MAX_CHARS) {
+			keptCount = Math.floor(keptCount / 2);
+			rendered = JSON.stringify({
+				count: value.length,
+				note: `count = ${value.length} : c'est le nombre EXACT, il porte sur la liste entière. Seules ${keptCount} entrées sont montrées (la liste pèse ${size} caractères) — toute affirmation sur le NOMBRE se fonde sur count, jamais sur les entrées visibles.`,
+				items: items.slice(0, keptCount)
+			}, null, 2);
+		}
+		return rendered;
+	}
+	const keys = value && typeof value === "object" ? Object.keys(value) : void 0;
+	return JSON.stringify({
+		keys,
+		note: `réponse de ${size} caractères, trop volumineuse pour être rendue entière — demande une branche précise (par exemple le module qui t'intéresse)`
+	}, null, 2);
+}
+/**
+* Rend un résultat d'outil — les données partent en JSON indenté, lisible.
+*
+* 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 les quatre outils intégrés, 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)
+*/
+function mcpText(value, isError = false) {
+	const rendered = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+	const text = isError || rendered.length <= MCP_TEXT_MAX_CHARS ? rendered : summarize(value, rendered.length);
+	return isError ? {
+		content: [{
+			type: "text",
+			text
+		}],
+		isError: true
+	} : { content: [{
+		type: "text",
+		text
+	}] };
+}
+/**
+* Marge laissée au corps d'un refus. Un producteur qui explique pourquoi il
+* refuse tient en quelques centaines d'octets (un plan de page, une liste de
+* valeurs) ; au-delà, c'est une donnée déguisée en message d'erreur, et une
+* réponse démesurée sature la fenêtre de celui qui la lit.
+*/
+const MCP_ERROR_BODY_MAX_CHARS = 4e3;
+/**
+* Rend un refus du plan d'administration — la phrase ET ce que le producteur a
+* joint pour la corriger.
+*
+* ⚠️ Rendre la seule phrase faisait conclure l'inverse de la vérité : demander
+* une section absente d'une page PRÉSENTE produit « … introuvable (404) », et
+* l'agent en déduisait que la page n'existait pas — alors que le producteur
+* joignait le plan de cette page, c'est-à-dire la réponse. Une porte qui résume
+* un refus lui fait dire autre chose.
+*
+* @param read - l'échec rendu par la lecture, corps du producteur inclus.
+* @returns le résultat d'outil, en erreur, borné en volume.
+*/
+function mcpAdminFailure(read) {
+	if (read.body === void 0 || read.body === null) return mcpText(read.message, true);
+	const rendered = JSON.stringify(read.body, null, 2);
+	const body = rendered.length <= MCP_ERROR_BODY_MAX_CHARS ? rendered : `${rendered.slice(0, MCP_ERROR_BODY_MAX_CHARS)}\n… body du refus tronqué (${rendered.length} caractères)`;
+	return mcpText(`${read.message}\n\n${body}`, true);
+}
+/**
+* Une page de documentation, ou son PLAN quand elle est trop lourde.
+*
+* Le résumé générique ({@link summarize}) sait ramener une liste à son compte et un
+* objet à ses clés ; sur une page de 78 ko il rendrait
+* `keys: [slug, frontmatter, markdown]` et conseillerait « demande une branche
+* précise » — une phrase qui ne désigne aucun geste possible. Le plan, lui, se lit
+* en quelques centaines d'octets et nomme exactement ce qu'il faut redemander.
+*
+* @param data - ce que le producteur a rendu pour la page
+* @param module - module interrogé, pour rédiger le geste suivant
+* @param slug - page interrogée, idem
+*/
+function pageOrOutline(data, module, slug) {
+	const page = data;
+	const markdown = typeof page?.markdown === "string" ? page.markdown : null;
+	if (markdown === null || markdown.length <= 28e3) return data;
+	return {
+		...data,
+		markdown: void 0,
+		chars: markdown.length,
+		note: `cette page pèse ${markdown.length} caractères — voici son PLAN. Rappelle l'outil avec section: "<titre>" (module: "${module}", slug: "${slug}") pour n'obtenir que le passage utile.`,
+		outline: outlineMarkdown(markdown)
+	};
+}
+/**
+* Clé de module telle que le kernel la connaît, depuis un nom de package npm.
+*
+* Le graphe symbolique indexe par nom npm (`@nodefony/http`) ; le plan
+* d'administration, lui, désigne les modules par leur clé courte (`http`), et
+* le socle sous le nom logique `core` — son package réel s'appelant `nodefony`
+* pour des raisons d'histoire. Deux vocabulaires pour une même chose : la
+* traduction vit ICI, une fois, plutôt que dans chaque appelant.
+*/
+function moduleKey(packageName) {
+	if (packageName === "nodefony" || packageName === "@nodefony/core") return "core";
+	return packageName.replace(/^@nodefony\//u, "");
+}
+/**
+* Largeur maximale d'un résumé dans le catalogue d'administration.
+*
+* Le catalogue vaut par sa densité : soixante lignes qu'on parcourt d'un coup
+* d'œil. Un résumé de trois phrases y ferait perdre la colonne de gauche — le
+* chemin, c'est-à-dire la seule chose qu'on recopie ensuite.
+*/
+const CATALOG_SUMMARY_MAX = 96;
+/** Largeur de la colonne des chemins, au-delà de laquelle on cesse d'aligner. */
+const CATALOG_PATH_COLUMN = 34;
+/**
+* Budget du catalogue rendu, sous la borne générique de {@link mcpText}.
+*
+* 🔴 Il ne s'agit pas de politesse : au-delà de sa borne, `mcpText` remplace une
+* CHAÎNE par une note générique — le résumé sait ramener une liste à son compte
+* et un objet à ses clés, mais d'un texte il ne garde rien. Le catalogue
+* disparaîtrait donc en entier, en conseillant « demande une branche précise »,
+* un geste qui ne désigne rien ici. On borne nous-mêmes, en gardant des entrées
+* ET en nommant les deux restrictions qui EXISTENT.
+*/
+const CATALOG_MAX_CHARS = 24e3;
+/**
+* Met le catalogue en forme pour un lecteur qui va s'en servir tout de suite.
+*
+* Texte plutôt que JSON, et ce n'est pas une question de goût : la même
+* information sérialisée en objets indentés pèse environ trois fois plus, pour
+* une porte dont l'unique raison d'être est de ne pas coûter de contexte. Le
+* groupement par producteur porte la seule structure nécessaire — le producteur
+* est le premier argument de l'appel qui suit.
+*
+* @param view - ce que le cœur a retenu, et ce qu'il a écarté.
+* @returns le catalogue rendu, écarts annoncés.
+*/
+function renderAdminCatalog(view) {
+	const gaps = [];
+	if (view.mutations > 0) gaps.push(`${view.mutations} mutations (POST/PATCH/DELETE — cette porte ne fait que LIRE)`);
+	if (view.selfService > 0) gaps.push(`${view.selfService} self-service liés à une session (« me », « sessions/mine ») — cette porte n'a pas d'utilisateur connecté`);
+	if (view.denied > 0) gaps.push(`${view.denied} hors des droits de ce jeton`);
+	if (view.filtered > 0) gaps.push(`${view.filtered} hors du filtre demandé`);
+	const lines = [`${view.entries.length} lectures appelables — sur ${view.total} endpoints déclarés par cette application.`, `Appel : nodefony_admin_call { namespace, path, params?, query? } — recopier « path » TEL QUEL, variables comprises.`];
+	if (gaps.length > 0) lines.push(`Non listés : ${gaps.join(" · ")}.`);
+	let namespace = null;
+	for (const entry of view.entries) {
+		if (entry.namespace !== namespace) {
+			namespace = entry.namespace;
+			const count = view.entries.filter((other) => other.namespace === namespace).length;
+			lines.push("", `## ${namespace} (${count})`);
+		}
+		const summary = entry.summary.length > CATALOG_SUMMARY_MAX ? `${entry.summary.slice(0, 95)}…` : entry.summary;
+		const suffix = summary === "" ? "" : `  ${summary}`;
+		lines.push(`${entry.path.padEnd(CATALOG_PATH_COLUMN)}${suffix}`.trimEnd());
+		const caps = [];
+		if (entry.page?.sortable.length) caps.push(`tri: ${entry.page.sortable.join(",")}`);
+		if (entry.page?.filters.length) caps.push(`filtres: ${entry.page.filters.join(",")}`);
+		if (entry.page?.search) caps.push("recherche q");
+		if (caps.length > 0) lines.push(`${" ".repeat(4)}${caps.join(" | ")}`);
+	}
+	if (view.entries.length === 0) lines.push("", "(aucune entrée ne répond à cette demande)");
+	const rendered = lines.join("\n");
+	if (rendered.length <= CATALOG_MAX_CHARS) return rendered;
+	const cut = rendered.slice(0, CATALOG_MAX_CHARS);
+	return `${cut.slice(0, cut.lastIndexOf("\n"))}\n\n… catalogue tronqué (${rendered.length} caractères pour ${view.entries.length} entrées). Rappelle l'outil avec namespace: "<producteur>" ou q: "<termes>" pour voir le reste.`;
+}
+function stringTable(value, field, arrays) {
+	if (value === void 0 || value === null) return {
+		ok: true,
+		value: {}
+	};
+	if (typeof value !== "object" || Array.isArray(value)) return {
+		ok: false,
+		why: `« ${field} » doit être un objet { clé: valeur }`
+	};
+	const table = {};
+	for (const [key, raw] of Object.entries(value)) {
+		if (typeof raw === "string") {
+			table[key] = raw;
+			continue;
+		}
+		if (typeof raw === "number" || typeof raw === "boolean") {
+			table[key] = String(raw);
+			continue;
+		}
+		if (arrays && Array.isArray(raw) && raw.every((item) => typeof item === "string")) {
+			table[key] = raw;
+			continue;
+		}
+		return {
+			ok: false,
+			why: `« ${field}.${key} » n'est pas une valeur transportable — attendu du texte${arrays ? " ou une liste de textes" : ""}`
+		};
+	}
+	return {
+		ok: true,
+		value: table
+	};
+}
+/** Préfixe des noms d'outils intégrés — un agent voit à qui il parle. */
+const PREFIX = "nodefony_";
+/**
+* Forme admise pour un nom d'outil.
+*
+* Ce nom ne reste pas dans le serveur : il voyage jusque dans le contexte du
+* modèle, et sert d'identifiant d'appel. Un nom porteur d'espace, de guillemet
+* ou de saut de ligne ne provoque pas d'erreur — il produit des appels que rien
+* ne résout, ce qui est bien pire à diagnostiquer. La borne haute est du même
+* ordre : un nom de 4 000 caractères passerait, et mangerait le contexte.
+*/
+const NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+* Clés des outils intégrés — ce que l'allowlist de configuration nomme.
+*
+* Publiée pour qu'un schéma de configuration puisse la valider au lieu de la
+* retaper : une clé inconnue en config est silencieusement sans effet, et
+* l'utilisateur croit avoir activé quelque chose.
+*/
+const BUILTIN_MCP_TOOL_KEYS = [
+	"inspect",
+	"card",
+	"check",
+	"symbols",
+	"docs",
+	"admin_list",
+	"admin_call"
+];
+/**
+* Liste des sujets, rendue lisible pour la description de l'outil.
+*
+* Dérivée de {@link INSPECT_SUBJECTS} : ajouter un sujet au cœur le publie ici
+* sans rien réécrire, et il ne peut pas exister de sujet annoncé qu'on ne
+* saurait pas lire.
+*/
+function subjectLines() {
+	return Object.entries(INSPECT_SUBJECTS).map(([key, spec]) => `- \`${key}\` : ${spec.summary}`).join("\n");
+}
+/**
+* Catalogue intégré du framework, indexé par clé d'allowlist.
+*
+* Chaque handler capture ses dépendances par fermeture : c'est ce qui permet à
+* ces quatre outils d'être des {@link IMcpTool} ordinaires, du même type que
+* ceux d'une application — le serveur n'a plus aucun cas particulier à traiter.
+*
+* @param deps - briques qui répondent réellement
+*/
+function builtinMcpTools(deps) {
+	return {
+		inspect: {
+			name: `${PREFIX}inspect`,
+			description: `Lit l'état RÉEL de cette application Nodefony : les routes réellement montées, les modules chargés, les services enregistrés, la configuration effective et la provenance de chaque valeur, les stores de données, les entités de l'ORM. À utiliser avant d'écrire du code qui suppose une route, un service ou une clé de configuration — la réponse vient de l'application qui tourne, pas d'une lecture des sources, donc elle ne peut pas se tromper sur ce qui est chargé.
+
+Sujets disponibles :\n${subjectLines()}`,
+			inputSchema: {
+				type: "object",
+				properties: {
+					subject: {
+						type: "string",
+						enum: Object.keys(INSPECT_SUBJECTS),
+						description: "Ce qu'on veut voir"
+					},
+					target: {
+						type: "string",
+						description: "Paramètre du sujet, quand il en attend un (ex. le nom d'un module pour `module`)"
+					}
+				},
+				required: ["subject"]
+			},
+			handler: async (args, caller) => {
+				const subject = typeof args.subject === "string" ? args.subject : "";
+				const target = typeof args.target === "string" ? args.target : void 0;
+				const read = await readAdminSubject(deps.broker, subject, adminCallerFromMcp(caller), target);
+				return read.ok ? mcpText(read.data) : mcpAdminFailure(read);
+			}
+		},
+		card: {
+			name: `${PREFIX}card`,
+			description: "Carte de visite de l'application : son identité, les modules chargés, où trouver la documentation, et les commandes à lancer. À utiliser en ARRIVANT sur une application inconnue, avant toute autre exploration — elle dit en un appel ce qu'il y a et où aller ensuite.",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			},
+			handler: () => mcpText(deps.getCard())
+		},
+		check: {
+			name: `${PREFIX}check`,
+			description: "Diagnostic STATIQUE de l'application : classes écrites que rien n'enregistre (entité, controller ou service jamais câblé), paquets importés sans être déclarés, variables d'environnement requises absentes, modules du manifeste non installés, ports occupés, et le bilan du dernier démarrage. À utiliser APRÈS avoir écrit ou généré du code, avant de conclure que c'est fini : ni la compilation ni les tests ne voient qu'une classe n'est branchée à rien.",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			},
+			handler: async () => {
+				const report = await collectDoctorReport(deps.projectRoot);
+				const total = countCheckFindings(report);
+				const skipped = skippedChecks(report.execution);
+				return mcpText({
+					verdict: total > 0 ? "manquements" : skipped.length > 0 ? "ok-mais-incomplet" : "ok",
+					total,
+					skipped,
+					...report
+				});
+			}
+		},
+		docs: {
+			name: `${PREFIX}docs`,
+			description: "Cherche et lit la DOCUMENTATION des modules installés — la prose écrite par leurs auteurs : concepts, recettes, pièges, exemples. À utiliser AVANT d'écrire du code qui utilise une brique du framework, et avant de conclure qu'une capacité n'existe pas. ⭐ Cette documentation vit sous `node_modules`, que les outils de recherche de fichiers EXCLUENT par défaut (dossier ignoré par git) : elle est livrée avec les paquets mais introuvable autrement qu'ici.\n\nSans argument : ce que l'application documente, module par module. Avec `query` : les pages qui portent tous les termes, avec leurs extraits. Avec `module` et `slug` : la page. Une page pèse souvent plus que ce qu'une réponse peut porter — demander alors `outline` pour son plan, puis `section` pour le seul passage utile.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					query: {
+						type: "string",
+						description: "Texte cherché dans toute la documentation ; les espaces séparent des termes CUMULATIFS (`session redis` = les deux)"
+					},
+					module: {
+						type: "string",
+						description: "Module dont on veut la documentation (`http`, `security`, `core`…)"
+					},
+					slug: {
+						type: "string",
+						description: "Page à lire, telle que la recherche ou l'index la nomme"
+					},
+					section: {
+						type: "string",
+						description: "Titre de la seule section voulue (approchant suffit : sans accent, sans casse, sans emoji)"
+					},
+					outline: {
+						type: "boolean",
+						description: "Rendre le PLAN de la page au lieu de son body — le premier geste sur une page volumineuse"
+					},
+					limit: {
+						type: "integer",
+						description: "Nombre maximum de documents rendus par `query` (défaut 20)"
+					}
+				}
+			},
+			handler: async (args, caller) => {
+				const admin = adminCallerFromMcp(caller);
+				const module = typeof args.module === "string" ? args.module : "";
+				const slug = typeof args.slug === "string" ? args.slug : "";
+				const query = typeof args.query === "string" ? args.query.trim() : "";
+				const section = typeof args.section === "string" ? args.section : "";
+				if (module !== "" && slug !== "") {
+					const read = await callAdminEndpoint(deps.broker, {
+						namespace: "kernel",
+						path: "module/{name}/docs/{slug}",
+						params: {
+							name: module,
+							slug
+						},
+						query: section !== "" ? { section } : args.outline === true ? { outline: "1" } : {},
+						label: `${module}/${slug}`
+					}, admin);
+					if (!read.ok) return mcpAdminFailure(read);
+					return mcpText(pageOrOutline(read.data, module, slug));
+				}
+				if (query !== "") {
+					const limit = typeof args.limit === "number" && Number.isFinite(args.limit) ? Math.trunc(args.limit) : null;
+					const read = await callAdminEndpoint(deps.broker, {
+						namespace: "kernel",
+						path: "docs/search",
+						query: limit !== null && limit > 0 ? {
+							q: query,
+							limit: String(limit)
+						} : { q: query },
+						label: `recherche « ${query} »`
+					}, admin);
+					return read.ok ? mcpText(read.data) : mcpAdminFailure(read);
+				}
+				const read = module !== "" ? await callAdminEndpoint(deps.broker, {
+					namespace: "kernel",
+					path: "module/{name}/docs",
+					params: { name: module },
+					label: module
+				}, admin) : await callAdminEndpoint(deps.broker, {
+					namespace: "kernel",
+					path: "docs",
+					label: "documentation"
+				}, admin);
+				return read.ok ? mcpText(read.data) : mcpAdminFailure(read);
+			}
+		},
+		symbols: {
+			name: `${PREFIX}symbols`,
+			description: "Donne la SIGNATURE RÉELLE d'un symbole du framework — ses paramètres, ses types de retour, sa documentation — plus ce qu'il étend ou implémente et où il est défini. À utiliser AVANT d'appeler une classe, une interface ou une fonction du framework, plutôt que d'en deviner les arguments. ⭐ La déclaration est lue dans les types LIVRÉS du paquet installé (`node_modules`, que les outils de recherche de fichiers excluent) : c'est la version qui tourne vraiment, pas une supposition. Sans argument, rend le résumé du graphe ; avec `module`, la surface exportée d'un paquet.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					name: {
+						type: "string",
+						description: "Nom exact du symbole (ex. `AbstractCrudService`, `IKernel`)"
+					},
+					module: {
+						type: "string",
+						description: "Paquet dont on veut la surface exportée (ex. `@nodefony/http`)"
+					}
+				}
+			},
+			handler: async (args, caller) => {
+				const graph = readSymbolsGraph(deps.projectRoot);
+				if (graph === null) return mcpText("aucun graphe symbolique atteignable — il est publié par le paquet `nodefony` (node_modules/nodefony/.ai/symbols.json) et régénérable dans ce dépôt par `npm run generate-symbols`", true);
+				const wanted = typeof args.name === "string" ? args.name : null;
+				const module = typeof args.module === "string" ? args.module : null;
+				if (wanted !== null) {
+					const sym = lookupSymbol(graph, wanted);
+					if (!sym) return mcpText(`« ${wanted} » est introuvable dans le graphe (${Object.keys(graph.symbols).length} symboles)`, true);
+					const declared = await callAdminEndpoint(deps.broker, {
+						namespace: "kernel",
+						path: "module/{name}/symbol/{symbol}",
+						params: {
+							name: moduleKey(sym.module),
+							symbol: sym.name
+						},
+						label: sym.name
+					}, adminCallerFromMcp(caller));
+					return mcpText(declared.ok ? {
+						...sym,
+						...declared.data
+					} : {
+						...sym,
+						declaration: null,
+						why: declared.message
+					});
+				}
+				const entries = Object.values(graph.symbols).filter((s) => module === null || s.module === module || moduleKey(s.module) === moduleKey(module));
+				if (module !== null) {
+					if (entries.length === 0) return mcpText(`aucun symbole pour « ${module} » — paquets présents dans le graphe : ${[...new Set(Object.values(graph.symbols).map((s) => s.module))].sort().join(", ")}`, true);
+					return mcpText(entries.sort((a, b) => a.name.localeCompare(b.name)));
+				}
+				const perPackage = Object.create(null);
+				for (const sym of entries) perPackage[sym.module] = (perPackage[sym.module] ?? 0) + 1;
+				return mcpText({
+					total: entries.length,
+					perPackage
+				});
+			}
+		},
+		admin_list: {
+			name: `${PREFIX}admin_list`,
+			description: "Catalogue des lectures d'ADMINISTRATION que cette application expose — bien au-delà des sujets de `nodefony_inspect` : journaux, sessions, comptes, clés d'API, webhooks, profileur, santé des connexions, entités, capacités de pagination. Chaque ligne est directement appelable par `nodefony_admin_call`. À utiliser dès que `nodefony_inspect` ne couvre pas ce qu'on cherche, plutôt que de supposer que la donnée n'existe pas.\n\nUn seul appel rend tout le catalogue ; `namespace` et `q` servent à le réduire quand on sait déjà ce qu'on cherche.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					namespace: {
+						type: "string",
+						description: "Ne garder qu'un producteur (`kernel`, `http`, `security`, `syslog`, `user`, `orm`…)"
+					},
+					q: {
+						type: "string",
+						description: "Termes cherchés dans le chemin et le résumé ; les espaces séparent des termes CUMULATIFS (`session redis` = les deux)"
+					}
+				}
+			},
+			requiresAuth: true,
+			scopes: [ADMIN_SCOPE_READ],
+			handler: (args, caller) => mcpText(renderAdminCatalog(adminReadCatalog(deps.broker, adminCallerFromMcp(caller), {
+				namespace: typeof args.namespace === "string" ? args.namespace : void 0,
+				q: typeof args.q === "string" ? args.q : void 0
+			})))
+		},
+		admin_call: {
+			name: `${PREFIX}admin_call`,
+			description: "Appelle une lecture d'administration, telle que `nodefony_admin_list` la nomme. La réponse vient de l'application qui TOURNE — pas d'une lecture des sources — et elle est identique à ce que rendrait la console d'administration, redaction des secrets comprise.\n\nLECTURE seule : les mutations du plan (créer, modifier, supprimer) ne passent pas par ici. Recopier `namespace` et `path` tels quels ; `params` porte les variables du chemin (`module/{name}` → `{ name: \"http\" }`), `query` les paramètres de requête que l'endpoint accepte (pagination `page`/`limit`, tri `sort`, recherche `q`). Le catalogue publie, sous chaque entrée qui rend une liste, les tris et filtres RÉELLEMENT acceptés — tout le reste est refusé en 400, jamais ignoré.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					namespace: {
+						type: "string",
+						description: "Producteur, tel que le catalogue le titre"
+					},
+					path: {
+						type: "string",
+						description: "Chemin, recopié TEL QUEL du catalogue (variables `{…}` comprises)"
+					},
+					params: {
+						type: "object",
+						description: "Valeurs des variables du chemin, par nom (`{ name: \"http\" }`)",
+						additionalProperties: { type: "string" }
+					},
+					query: {
+						type: "object",
+						description: "Paramètres de requête, comme une URL les porterait (`{ limit: \"20\" }`)"
+					}
+				},
+				required: ["namespace", "path"]
+			},
+			requiresAuth: true,
+			scopes: [ADMIN_SCOPE_READ],
+			handler: async (args, caller) => {
+				const admin = adminCallerFromMcp(caller);
+				const namespace = typeof args.namespace === "string" ? args.namespace.trim() : "";
+				const path = typeof args.path === "string" ? args.path.trim() : "";
+				if (namespace === "" || path === "") return mcpText("« namespace » et « path » sont requis — demande d'abord nodefony_admin_list, puis recopie les deux tels quels", true);
+				const entry = findAdminReadEntry(deps.broker, admin, namespace, path);
+				if (!entry) {
+					const proches = adminReadCatalog(deps.broker, admin, { namespace });
+					return mcpText(proches.entries.length === 0 ? `« ${namespace}/${path} » n'est pas appelable ici, et « ${namespace} » ne propose aucune lecture — soit ce module n'est pas chargé, soit ce jeton ne l'ouvre pas. nodefony_admin_list rend le catalogue réel.` : `« ${namespace}/${path} » n'est pas appelable ici. Chemins de « ${namespace} » : ${proches.entries.map((other) => other.path).join(", ")}`, true);
+				}
+				const params = stringTable(args.params, "params", false);
+				if (!params.ok) return mcpText(params.why, true);
+				const query = stringTable(args.query, "query", true);
+				if (!query.ok) return mcpText(query.why, true);
+				const missing = entry.params.filter((name) => typeof params.value[name] !== "string");
+				if (missing.length > 0) return mcpText(`« ${namespace}/${path} » attend ${missing.length > 1 ? "les variables" : "la variable"} ${missing.map((name) => `« ${name} »`).join(", ")} dans « params »`, true);
+				const read = await callAdminEndpoint(deps.broker, {
+					namespace,
+					path,
+					method: "GET",
+					params: params.value,
+					query: query.value,
+					label: `${namespace}/${path}`
+				}, admin);
+				return read.ok ? mcpText(read.data) : mcpAdminFailure(read);
+			}
+		}
+	};
+}
+/** Appelant anonyme — le défaut, et le seul défaut sûr. */
+const ANONYMOUS = {
+	authenticated: false,
+	scopes: [],
+	roles: []
+};
+/**
+* L'appelant satisfait-il ce que l'outil exige ?
+*
+* @returns `null` s'il passe, sinon le motif de la rétention
+*/
+/**
+* Présente un appelant MCP au plan d'administration.
+*
+* Aucune décision ici : les rôles ont été posés par la porte, qui seule sait si
+* elle est protégée et par qui. Cette fonction ne fait que TRADUIRE — et c'est
+* volontaire : la traduction est le seul endroit où une identité pourrait se
+* perdre, alors elle ne fait rien d'autre que la transporter.
+*
+* @param caller - l'appelant établi par la porte.
+* @returns la même identité, dans le vocabulaire du plan d'administration.
+*/
+function adminCallerFromMcp(caller) {
+	return {
+		user: null,
+		roles: caller.roles,
+		label: caller.subject ? `le porteur « ${caller.subject} »` : caller.authenticated ? "un porteur authentifié" : "un appelant anonyme"
+	};
+}
+function withholdReason(tool, caller) {
+	const needsScopes = tool.scopes !== void 0 && tool.scopes.length > 0;
+	if (!needsScopes && tool.requiresAuth !== true) return null;
+	if (!caller.authenticated) {
+		const opened = needsScopes ? rolesFromScopes(tool.scopes) : [];
+		if (opened.length > 0 && opened.every((role) => caller.roles.includes(role))) return null;
+		return "exige une identité prouvée, l'appelant est anonyme";
+	}
+	if (!needsScopes) return null;
+	const missing = tool.scopes.filter((scope) => !caller.scopes.includes(scope));
+	return missing.length === 0 ? null : `scopes manquants : ${missing.join(", ")}`;
+}
+/**
+* Énumère ce que cette application DÉCLARE : les intégrés autorisés, puis les
+* outils des modules — sans rien retenir sur l'identité de qui que ce soit.
+*
+* Trois refus, tous énoncés par `onSkip` plutôt que silencieux :
+*  - **nom hors forme** ({@link NAME_PATTERN}) — il ne serait pas appelable ;
+*  - **collision** — le premier inscrit garde le nom, les intégrés passant en
+*    tête ; un module ne peut donc pas se substituer à `nodefony_inspect` et
+*    répondre à sa place ;
+*  - **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 - allowlist, dépendances, modules et journal des écarts
+* @returns les outils déclarés, dans l'ordre où ils seraient publiés
+*/
+function declareMcpTools(options) {
+	const declared = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (tool, origin) => {
+		if (typeof tool?.name !== "string" || !NAME_PATTERN.test(tool.name)) {
+			options.onSkip?.(`outil écarté (${origin}) : nom absent ou hors forme — attendu ${NAME_PATTERN.source}`);
+			return;
+		}
+		if (typeof tool.handler !== "function") {
+			options.onSkip?.(`outil « ${tool.name} » écarté (${origin}) : sans handler`);
+			return;
+		}
+		if (seen.has(tool.name)) {
+			options.onSkip?.(`outil « ${tool.name} » écarté (${origin}) : ce nom est déjà pris`);
+			return;
+		}
+		seen.add(tool.name);
+		declared.push(tool);
+	};
+	const builtin = builtinMcpTools(options.deps);
+	for (const key of options.builtins) if (Object.hasOwn(builtin, key)) add(builtin[key], "intégré");
+	for (const [name, module] of Object.entries(options.modules ?? {})) {
+		const declare = module?.getMcpTools;
+		if (typeof declare !== "function") continue;
+		let tools;
+		try {
+			tools = declare.call(module);
+		} catch (error) {
+			options.onSkip?.(`module « ${name} » : getMcpTools() a échoué — ${error.message}`);
+			continue;
+		}
+		if (!Array.isArray(tools)) {
+			options.onSkip?.(`module « ${name} » : getMcpTools() doit rendre un tableau`);
+			continue;
+		}
+		for (const tool of tools) add(tool, `module ${name}`);
+	}
+	return declared;
+}
+/**
+* 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 - allowlist, dépendances, modules, appelant et journaux
+* @returns les outils exécutables, dans l'ordre où ils seront publiés
+*/
+function collectMcpTools(options) {
+	const caller = options.caller ?? ANONYMOUS;
+	const served = [];
+	for (const tool of declareMcpTools(options)) {
+		const withheld = withholdReason(tool, caller);
+		if (withheld !== null) {
+			options.onWithheld?.(tool.name, withheld);
+			continue;
+		}
+		served.push(tool);
+	}
+	return served;
+}
+/**
+* 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 - allowlist, dépendances, modules et journal des écarts
+* @returns les scopes, dédupliqués et triés ; vide si la porte n'exige rien
+*/
+function mcpDeclaredScopes(options) {
+	const vocabulaire = /* @__PURE__ */ new Set();
+	for (const tool of declareMcpTools(options)) for (const scope of tool.scopes ?? []) vocabulaire.add(scope);
+	return [...vocabulaire].sort();
+}
+/**
+* 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.
+*/
+function publishMcpTools(tools) {
+	return tools.map(({ name, description, inputSchema }) => ({
+		name,
+		description,
+		inputSchema
+	}));
+}
+/**
+* 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)
+* @returns le résultat de l'outil, ou `null` si le nom n'est pas exposé
+*/
+async function callMcpTool(name, args, tools, caller = ANONYMOUS) {
+	const tool = tools.find((candidate) => candidate.name === name);
+	if (!tool) return null;
+	const refusal = unknownArguments(tool, args);
+	if (refusal !== null) return mcpText(refusal, true);
+	return tool.handler(args, caller);
+}
+/**
+* Arguments que l'outil ne déclare pas — refusés, jamais ignorés.
+*
+* ⚠️ Un paramètre accepté puis jeté est pire qu'un refus : la réponse a l'air
+* d'avoir honoré la demande. Vécu sur cette porte — un `limit` passé à la
+* recherche documentaire revenait avec vingt résultats, sans un mot, et
+* l'appelant en concluait que la borne ne marchait pas plutôt que de voir
+* qu'elle n'avait jamais été transmise. Le même silence accueillait une clé
+* mal orthographiée : l'outil répondait comme si de rien n'était.
+*
+* La garde vit ICI, une fois, plutôt que dans chaque handler — et elle
+* s'applique donc aussi aux outils qu'une application déclare. Un outil qui
+* veut réellement des arguments libres l'écrit dans son schéma
+* (`additionalProperties: true`), ce qui en fait un choix relu, pas un défaut.
+*
+* @param tool - l'outil visé, avec son schéma d'entrée.
+* @param args - ce que l'agent a passé.
+* @returns le message de refus, ou `null` si tout est déclaré.
+*/
+function unknownArguments(tool, args) {
+	const schema = tool.inputSchema;
+	if (schema?.additionalProperties === true) return null;
+	const declared = schema?.properties;
+	if (!declared || typeof declared !== "object") return null;
+	const intruders = Object.keys(args).filter((key) => !Object.hasOwn(declared, key));
+	if (intruders.length === 0) return null;
+	const known = Object.keys(declared);
+	return `« ${tool.name} » ne connaît pas ${intruders.map((c) => `« ${c} »`).join(", ")}. ` + (known.length > 0 ? `Arguments acceptés : ${known.join(", ")}.` : "Cet outil ne prend aucun argument.");
+}
+//#endregion
+export { BUILTIN_MCP_TOOL_KEYS, builtinMcpTools, callMcpTool, collectMcpTools, declareMcpTools, mcpDeclaredScopes, mcpText, publishMcpTools };