Référence d'API — @nodefony/ai

stable

Documentation › Référence d’API › @nodefony/ai

Générée depuis les déclarations de types publiées de @nodefony/ai 10.0.0-beta.5 : exactement ce que reçoit une application qui l’installe. Cette page n’existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

@nodefony/ai#

import { … } from "@nodefony/ai" — 106 symboles.

Classes (3)#

AiError#

class AiError extends Error

Erreur du module ai.

• readonly code: string
• readonly context?: Record<string, unknown>
• constructor(message: string, code?: string, context?: Record<string, unknown>)

SessionTicketStore#

class SessionTicketStore

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.

• constructor(options?: ISessionTicketStoreOptions)
• get pending(): number — Nombre de tickets émis, ni rachetés ni expirés.
• issue(identifier: string): string — Émet un ticket pour identifier, valable SESSION_TICKET_TTL_MS ms.
• redeem(ticket: unknown): string | null — Rachète un ticket : le retire, et rend l’identité pour laquelle il a été émis.

default#

class AiModule extends Module

• constructor(kernel: Kernel)
• onKernelRegister(): Promise<this> — Valide la config au boot — défauts du schéma fusionnés avec ce que l’app passe dans use().

Fonctions (30)#

aiConfigJsonSchema#

function aiConfigJsonSchema(): unknown

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.

callMcpTool#

function callMcpTool(name: string, args: Record<string, unknown>, tools: readonly IMcpTool[], caller?: IMcpCaller, run?: IMcpToolRun): Promise<IMcpToolResult | null>

Exécute un outil par son nom public.

checkMcpAccess#

function checkMcpAccess(input: IGuardInput, policy: IGuardPolicy): GuardVerdict

Décide si un appel MCP peut être servi.

collectMcpTools#

function collectMcpTools(options: IMcpCollectOptions): IMcpTool[]

Ramasse les outils SERVIS à cet appelant.

createMcpResponseStream#

function createMcpResponseStream<S extends IMcpEventSink>(options: IMcpResponseStreamOptions<S>): IMcpResponseStream<S>

Fabrique le flux de réponse paresseux d’une requête MCP.

createProgressReporter#

function createProgressReporter(token: McpProgressToken | null, notify: (notification: IJsonRpcNotification) => void, now?: () => number, minIntervalMs?: number): IMcpProgressReporter

Fabrique le rapporteur de progression d’un appel.

declareMcpTools#

function declareMcpTools(options: IMcpDeclareOptions): IMcpTool[]

Énumère ce que cette application DÉCLARE — les outils de ses modules, lus par getMcpTools() — sans rien retenir sur l’identité de qui que ce soit.

defineAiConfig#

function defineAiConfig(config?: unknown): IAiConfig

defineMcpGate#

function defineMcpGate(definition: IMcpGateDefinition): IMcpGate

Définit une porte MCP — UNE fois, à côté de son controller.

defineTicketSessionGate#

function defineTicketSessionGate(definition: ITicketSessionGateDefinition): ITicketSessionGate

Définit une porte de session par ticket : ce qui permet à un outil MCP de tirer de vraies requêtes HTTP vers l’application AU NOM d’un compte.

fingerprintSessionTicket#

function fingerprintSessionTicket(ticket: string): string

Empreinte sous laquelle un ticket est rangé : le ticket brut n’est jamais gardé.

handleMcpMessage#

function handleMcpMessage(message: IJsonRpcMessage | null, context: IMcpServerContext, headers?: IMcpHeaders): Promise<IMcpHttpReply>

Traite UN message JSON-RPC.

insufficientScopeMessage#

function insufficientScopeMessage(name: string, missing: readonly string[]): string

Le message d’un appel refusé faute de scope — le même pour le résultat isError et la description du défi 403.

isLocalAddress#

function isLocalAddress(address?: string): boolean

isNotification#

function isNotification(message: IJsonRpcMessage): boolean

Un message est-il une NOTIFICATION — un appel SANS membre id ?

isRelayedRequest#

function isRelayedRequest(headers: Readonly<Record<string, string | string[]>>): boolean

La requête a-t-elle traversé un relais (proxy inverse, répartiteur) ?

isSessionFlowView#

function isSessionFlowView(value: unknown): value is ISessionFlowView

Le service résolu est-il un flux de session utilisable ?

isSessionServiceView#

function isSessionServiceView(value: unknown): value is ISessionServiceView

Le service résolu est-il un service de sessions utilisable ?

jsonRpcFailure#

function jsonRpcFailure(id: JsonRpcId | null, code: number, message: string, data?: unknown): IJsonRpcFailure

Fabrique une réponse d’erreur — data n’apparaît que s’il est donné.

jsonRpcSuccess#

function jsonRpcSuccess(id: JsonRpcId, result: unknown): IJsonRpcSuccess

Fabrique une réponse de succès.

mcpCallScopes#

function mcpCallScopes(tool: IMcpTool, args: Readonly<Record<string, unknown>>): readonly string[] | null

Tous les scopes qu’exige UN appel : ceux de l’outil, puis ceux que ses arguments ajoutent (IMcpTool.scopesFor). Seule source de la règle, lue par l’appel en process ET par le défi insufficient_scope d’une porte.

mcpCallerRoles#

function mcpCallerRoles(posture: IMcpGatePosture, operatorRoles?: readonly string[]): readonly string[]

Quels rôles porte l’appelant d’une porte MCP — la règle, à un seul endroit.

mcpDeclaredScopes#

function mcpDeclaredScopes(options: IMcpDeclareOptions): string[]

Le vocabulaire de scopes que cette porte EXIGE — l’union de ce que ses outils déclarent, jamais une liste écrite à côté.

mcpText#

function mcpText(value: unknown, isError?: boolean): IMcpToolResult

Rend un résultat d’outil — les données partent en JSON COMPACT.

openTicketSession#

function openTicketSession(request: ITicketSessionRequest, deps: ITicketSessionDeps): Promise<TicketSessionVerdict>

Décide l’ouverture d’une session par ticket.

publishMcpTools#

function publishMcpTools(tools: readonly IMcpTool[]): IMcpToolDefinition[]

Projette les outils pour tools/list — sans leur implémentation.

readProgressToken#

function readProgressToken(params: Record<string, unknown>): McpProgressToken | null

Lit le jeton de progression d’une requête (params._meta.progressToken).

readTicketSessionVerdict#

function readTicketSessionVerdict(body: string | null): { identifier: string; roles: readonly string[]; ref: string; } | { message: string; }

Lit, côté outil, la réponse de la route de connexion par ticket — sans lui faire confiance. Vit à côté de openTicketSession, qui en produit la forme : deux copies du format divergeraient.

serveMcpStdio#

function serveMcpStdio(gate: IMcpGate, options: IMcpStdioOptions): Promise<void>

Sert une porte MCP sur un flux de lignes, jusqu’à la fin de l’entrée.

toTicketSessionUser#

function toTicketSessionUser(value: unknown, identifier: string): ITicketSessionUser

Lit le compte rendu par le flux de session, sans lui faire confiance.

Constantes (23)#

JsonRpcError#

const JsonRpcError: { readonly PARSE_ERROR: -32700; readonly INVALID_REQUEST: -32600; readonly METHOD_NOT_FOUND: -32601; readonly INVALID_PARAMS: -32602; readonly INTERNAL_ERROR: -32603; }

Les cinq codes d’erreur que JSON-RPC 2.0 §5.1 définit.

MCP_DEFAULT_NEGOTIATED_VERSION#

const MCP_DEFAULT_NEGOTIATED_VERSION = "2025-03-26"

Révision supposée quand un client n’en déclare AUCUNE.

MCP_PROGRESS_MESSAGE_MAX#

const MCP_PROGRESS_MESSAGE_MAX = 1000

Longueur maximale du message d’une progression, en caractères.

MCP_PROGRESS_MIN_INTERVAL_MS#

const MCP_PROGRESS_MIN_INTERVAL_MS = 100

Intervalle minimal entre deux notifications de progression, en millisecondes.

MCP_PROTOCOL_VERSION#

const MCP_PROTOCOL_VERSION = "2026-07-28"

Révision PRÉFÉRÉE de ce serveur — celle qu’il met en tête de ce qu’il sait faire.

MCP_RESERVED_PREFIX#

const MCP_RESERVED_PREFIX = "nodefony_"

Préfixe RÉSERVÉ aux modules du framework (@nodefony/*) — un agent qui lit nodefony_inspect doit pouvoir croire que c’est le framework qui répond.

MCP_STREAM_GRACE_MS#

const MCP_STREAM_GRACE_MS = 5000

Délai de grâce, en ms : au-delà, un appel sans réponse ouvre le flux. Très en deçà du délai d’inactivité d’une requête (30 s par défaut), assez long pour qu’un outil ordinaire réponde en JSON comme avant.

MCP_STREAM_MAX_EVENT_BYTES#

const MCP_STREAM_MAX_EVENT_BYTES: number

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).

MCP_SUPPORTED_VERSIONS#

const MCP_SUPPORTED_VERSIONS: readonly [ "2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05" ]

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.

MCP_TEXT_MAX_CHARS#

const MCP_TEXT_MAX_CHARS = 32000

Au-delà de quoi une réponse cesse d’être une réponse.

META_PROTOCOL_VERSION#

const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion"

Clé de métadonnée par laquelle un client MODERNE déclare sa révision.

META_SERVER_INFO#

const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"

Clé de métadonnée portant l’identité du serveur dans server/discover.

McpProtocolError#

const McpProtocolError: { readonly HEADER_MISMATCH: -32020; readonly UNSUPPORTED_PROTOCOL_VERSION: -32022; }

Codes réservés par la spec MCP, hors plage JSON-RPC standard.

RELAY_HEADERS#

const RELAY_HEADERS: readonly [ "forwarded", "x-forwarded-for", "x-real-ip", "via" ]

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.

SESSION_TICKET_HEADER#

const SESSION_TICKET_HEADER = "x-nodefony-session-ticket"

En-tête qui porte le ticket vers la route de connexion par ticket.

SESSION_TICKET_LENGTH#

const SESSION_TICKET_LENGTH = 43

Longueur d’un ticket : 32 octets d’aléa en base64url, sans remplissage.

SESSION_TICKET_MAX_PENDING#

const SESSION_TICKET_MAX_PENDING = 8

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é.

SESSION_TICKET_TTL_MS#

const SESSION_TICKET_TTL_MS = 10000

Durée de vie d’un ticket : le temps d’une requête de connexion en boucle locale.

TICKET_SESSION_REFUSED#

const TICKET_SESSION_REFUSED = "ticket de session refus\u00E9"

Message unique de tout refus : la cause fine ne sort jamais vers l’appelant.

aiConfigSchema#

const aiConfigSchema: z.ZodObject<{ enabled: z.ZodDefault<z.ZodBoolean>; }, z.core.$strict>

mcpConfigSchema#

const mcpConfigSchema: 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. …

Réglages de la porte MCP (POST /nodefony/mcp) — la SOURCE UNIQUE du schéma mcp.*, que tout module qui sert ou configure la porte importe d’ici.

mcpGateSchema#

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.Zo …

Le schéma d’une porte — les réglages de transport et d’autorisation de 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.

ticketSessionGateSchema#

const ticketSessionGateSchema: z.ZodObject<{ factor: z.ZodString; localOnly: z.ZodDefault<z.ZodBoolean>; }, z.core.$strict>

Définition d’une porte de session par ticket — validée et figée au boot.

Interfaces (36)#

IGuardInput#

interface IGuardInput

Ce que la garde a besoin de savoir d’une requête.

• origin?: string — En-tête Origin, undefined s’il est absent.
• remoteAddress?: string — Adresse distante de la connexion (socket.remoteAddress).
• relayed?: boolean — 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.

IGuardPolicy#

interface IGuardPolicy

Réglages qui gouvernent les gardes (viennent de la config du module).

• allowedOrigins: readonly string[] — Origines de navigateur admises ; vide = aucune.
• allowRemote: boolean — Accepter une adresse distante non locale.

IJsonRpcFailure#

interface IJsonRpcFailure

Réponse d’erreur.

• jsonrpc: "2.0"
• id: JsonRpcId | null — null quand l’erreur survient avant d’avoir pu lire un id.
• error: IJsonRpcErrorObject

IJsonRpcMessage#

interface IJsonRpcMessage

Message ENTRANT, tel qu’il arrive du réseau : rien n’y est garanti.

• jsonrpc?: unknown
• id?: unknown
• method?: unknown
• params?: unknown
• result?: unknown — Présent sur une réponse — qu’une porte serveur doit pouvoir refuser.
• error?: unknown — Présent sur une réponse d’erreur.

IJsonRpcSuccess#

interface IJsonRpcSuccess

Réponse de succès.

• jsonrpc: "2.0"
• id: JsonRpcId
• result: unknown

IMcpCacheHints#

interface IMcpCacheHints

Indices de cache d’un résultat MCP (spec server/utilities/caching).

• ttlMs: number — Durée de fraîcheur en millisecondes, >= 0 (MUST).
• cacheScope: "public" | "private" — private dès que le résultat dépend de l’appelant.

IMcpCaller#

interface IMcpCaller

Ce que le transport a pu ÉTABLIR de l’appelant — jamais ce qu’il prétend.

• authenticated: boolean — Une identité a-t-elle été PROUVÉE (jeton validé) ?
• scopes: readonly string[] — Scopes réellement accordés par le serveur d’autorisation.
• roles: readonly string[] — Rôles Nodefony de cet appelant — ce sur quoi le plan d’administration tranche.
• subject?: string — Sujet du jeton (sub), pour l’audit et pour filtrer les données rendues.

IMcpCollectOptions#

interface IMcpCollectOptions extends IMcpDeclareOptions

Ce qu’il faut pour ramasser les outils SERVIS à un appelant.

• caller?: IMcpCaller — Ce que la porte a ÉTABLI de l’appelant.
• onWithheld?: (name: string, why: string) => void — Appelé pour chaque outil RETENU faute d’autorisation.

IMcpDeclareOptions#

interface IMcpDeclareOptions

Ce qu’il faut pour ÉNUMÉRER les déclarations d’outils d’une application.

• modules?: Readonly<Record<string, unknown>> — Modules chargés (kernel.modules), dont on lit getMcpTools().
• onSkip?: (why: string) => void — Appelé pour chaque déclaration ÉCARTÉE, avec le motif.

IMcpEventSink#

interface IMcpEventSink

Ce qu’une porte sait ouvrir : un puits d’événements, ordonné.

• readonly closed: boolean — Le flux est-il fermé (client parti, ou clos) ?
• send(data: unknown): Promise<void> — Envoie un message JSON-RPC ; peut lever à l’appel ou rendre une promesse de contre-pression.

IMcpGate#

interface IMcpGate

Une porte MCP définie — à servir depuis une action de controller.

• readonly settings: IMcpGateSettings — Les réglages effectifs, validés et figés.
• serve(controller: Controller, body: unknown): Promise<unknown> — 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).
• respond<S extends IMcpEventSink>(request: IMcpGateRequest<S>, runtime?: IMcpGateRuntime): Promise<IMcpGateResponse<S>> — Répond à UN POST décrit — sans controller, éprouvable sans serveur (et réutilisable par un autre transport).
• respondStdio(request: IMcpStdioRequest, runtime?: IMcpGateRuntime): Promise<IMcpGateResponse> — Répond à UNE ligne reçue sur l’entrée standard — le pendant de IMcpGate.respond pour un client qui lance lui-même son serveur.
• protectedResources(modules?: Readonly<Record<string, unknown>>): readonly IProtectedResourceInput[] — Ce que la porte protège, à publier en RFC 9728 — une entrée, ou rien.

IMcpGatePosture#

interface IMcpGatePosture

Ce qu’une porte MCP sait d’elle-même et de son appelant, au moment de dire quels rôles celui-ci porte.

• protected: boolean — La porte déclare-t-elle un serveur d’autorisation ?
• authenticated: boolean — Un jeton a-t-il été vérifié pour cet appel ?
• scopes: readonly string[] — Scopes que le serveur d’autorisation a réellement accordés.

IMcpGateRequest#

interface IMcpGateRequest<S extends IMcpEventSink = IMcpEventSink>

Ce que la porte a reçu — lu par elle, jamais par la mécanique.

• body: unknown — Corps tel que le parseur HTTP l’a rendu ({} pour un JSON illisible).
• rawBody?: () => string — 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).
• origin?: string — En-tête Origin.
• protocolVersion?: string — En-tête MCP-Protocol-Version.
• authorization?: string — En-tête Authorization.
• remoteAddress?: string — Adresse de l’appelant (après trustProxy).
• relayed?: boolean — 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.
• signal?: AbortSignal — Abattu quand le client abandonne la requête.
• openStream?: (() => S | Promise<S>) — Ouvre un flux SSE — absent quand le client n’en accepte pas : la progression devient alors muette, jamais refusée.
• onAccount?: (identifier: string) => void — 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.

IMcpGateRuntime#

interface IMcpGateRuntime

Ce que l’environnement fournit à une réponse — serve() le lit seul.

• modules?: Readonly<Record<string, unknown>> — Les modules chargés, pour une porte tools: "modules".
• verifier?: IAccessTokenVerifier — Qui sait valider un jeton — requis dès qu’un serveur d’autorisation est déclaré.
• accountResolver?: IAccessAccountResolver — Qui retrouve le compte qu’un jeton désigne — requis par un outil actsForUser ; absent, un tel outil refuse de s’exécuter.
• serverInfo?: IServerInfo — Identité annoncée ; défaut : name/version de la porte, sinon le projet.
• log?: (message: string, severity: McpGateSeverity) => void — Journal de la porte ; muet si absent.

IMcpHeaders#

interface IMcpHeaders

En-têtes HTTP dont le protocole se sert.

• protocolVersion?: string — MCP-Protocol-Version, absent chez un client de l’ère legacy.

IMcpHttpReply#

interface IMcpHttpReply

Ce que le serveur MCP rend, avant traduction en réponse HTTP.

• status: number — Statut HTTP à poser.
• body: IJsonRpcSuccess | IJsonRpcFailure | null — Corps JSON, ou null pour un 202 Accepted sans corps — la spec l’exige pour une notification acceptée.
• failure?: { tool: string; error: unknown; } — L’exception levée par un outil, rendue À CÔTÉ de la réponse — jamais sérialisée.

IMcpProgressReporter#

interface IMcpProgressReporter

Le rapporteur d’UN appel : ce que l’outil appelle, ce que la porte clôt.

• progress(progress: number, total?: number, message?: string): void — 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 end.
• end(): void — L’outil a rendu sa réponse : plus aucune notification ne part.

IMcpResponseStream#

interface IMcpResponseStream<S extends IMcpEventSink>

Le flux de réponse d’UNE requête, vu de la porte.

• readonly transport: IMcpTransport — À donner au protocole (IMcpServerContext.transport).
• finish(body: unknown): Promise<S | null> — Attend les envois en cours puis, si un flux a été ouvert, y écrit la réponse finale.

IMcpResponseStreamOptions#

interface IMcpResponseStreamOptions<S extends IMcpEventSink>

Options de createMcpResponseStream.

• signal?: AbortSignal — Abattu quand le client abandonne la requête.
• open?: (() => S | Promise<S>) — Ouvre le flux de la porte ; absent quand le client n’en accepte pas — la progression devient alors muette, jamais refusée.
• graceMs?: number — Ouvre le flux si l’appel n’a pas répondu dans ce délai (ms) ; absent ou 0 : le flux ne s’ouvre qu’au premier envoi.
• onError?: (error: unknown, final: boolean) => void — Un envoi perdu (client parti, événement refusé) : à journaliser.

IMcpServerContext#

interface IMcpServerContext

Tout ce dont le traitement d’un message a besoin.

• tools: readonly IMcpTool[] — Outils SERVIS, déjà ramassés et filtrés (collectMcpTools).
• serverInfo: IServerInfo — Identité annoncée au client.
• caller?: IMcpCaller — Appelant établi par la porte, transmis aux handlers.
• withheldCount?: number — Combien d’outils la collecte a RETENUS pour cet appelant.
• authorizable?: boolean — Cette porte sait-elle RECEVOIR une autorisation (porte HTTP protégée, qui publie son document RFC 9728 et défie par 401) ?
• transport?: IMcpTransport — Ce que la porte sait faire PENDANT un appel — absent, l’appel est servi comme une lecture courte : jamais annulé, sans progression.
• cancellation?: IMcpCancellation — Les appels en cours de CET appelant, que notifications/cancelled abat — absent, seule la fermeture du flux annule un appel.
• versions?: readonly string[] — Révisions du protocole que CETTE porte accepte, la préférée en tête.
• instructions?: string — Ce que l’agent lit pour savoir QUAND se servir de cette porte — la phrase d’ouverture des instructions.
• cache?: IMcpCacheHints — Indices de cache des listes (ttlMs, cacheScope), servis aux clients de l’ère moderne seulement.

IMcpStdioOptions#

interface IMcpStdioOptions

Ce que sert une boucle stdio.

• input: Readable — L’entrée du protocole — process.stdin en pratique.
• write: (line: string) => void — Écrit UNE ligne sur la sortie du protocole, saut de ligne compris.
• runtime?: IMcpGateRuntime — Modules, identité, journal — transmis à la porte.

IMcpStdioRequest#

interface IMcpStdioRequest

Ce qu’un transport de process (stdio) a reçu : une ligne, sans en-tête ni adresse.

• line: string — La ligne reçue, telle quelle — un message JSON-RPC, en principe.
• signal?: AbortSignal — Abattu quand le client s’en va (entrée standard fermée).
• openStream?: (() => IMcpEventSink | Promise<IMcpEventSink>) — Ouvre le puits où écrire les notifications de l’appel, puis sa réponse finale — absent, la progression devient muette.

IMcpTool#

interface IMcpTool extends IMcpToolDefinition

Un outil exécutable : ce que tools/list publie, plus ce qui répond.

• scopes?: readonly string[] — Scopes OAuth exigés — tous, pas au moins un.
• scopesFor?: (args: Readonly<Record<string, unknown>>) => readonly string[] — Scopes que CES arguments exigent, en plus de IMcpTool.scopes — un paramètre qui élargit ce que l’outil fait (agir au nom d’un autre compte, écrire) sans conditionner sa visibilité.
• requiresAuth?: boolean — Exige une identité prouvée, sans scope particulier.
• actsForUser?: boolean — L’outil agit AU NOM du propriétaire du jeton : son handler s’exécute dans une bulle de requête où RequestContext.getAuthenticatedUser(), les services qu’il appelle et l’autorisation (`authorization. …
• handler: (args: Record<string, unknown>, caller: IMcpCaller, run?: IMcpToolRun) => IMcpToolResult | Promise<IMcpToolResult> — Implémentation.

IMcpToolAnnotations#

interface IMcpToolAnnotations

Ce qu’un outil promet de son effet — les indices ToolAnnotations de la spec MCP (révision 2026-07-28, schema.ts), publiés dans tools/list.

• title?: string — Titre lisible, préféré au nom par les interfaces.
• readOnlyHint?: boolean — L’outil ne modifie RIEN de son environnement (défaut de la spec : false).
• destructiveHint?: boolean — Une écriture peut détruire (défaut : true) — false : n’ajoute que.
• idempotentHint?: boolean — Rappeler l’outil avec les mêmes arguments n’a pas d’effet de plus (défaut : false) — vrai d’un remplacement ou d’une suppression, faux d’une création ou d’un envoi.
• openWorldHint?: boolean — L’outil touche un monde extérieur ouvert — web, API tierce, courriel (défaut : true).

IMcpToolDefinition#

interface IMcpToolDefinition

Un outil tel que tools/list le publie — sans son implémentation.

• name: string — Identifiant d’appel.
• description: string — ⭐ Le premier critère de déclenchement de l’outil, avant toute considération technique.
• inputSchema: Record<string, unknown> — Schéma JSON des arguments attendus.
• annotations?: IMcpToolAnnotations — Ce que l’outil promet de son effet — à poser sur CHAQUE outil.

IMcpToolResult#

interface IMcpToolResult

Ce que rend un outil — du contenu, et l’aveu d’un échec métier.

• content: { type: "text"; text: string; }[]
• isError?: boolean

IMcpToolRun#

interface IMcpToolRun

Ce que la porte prête à un outil pendant SON exécution : de quoi savoir que l’agent est parti, et de quoi lui donner signe de vie.

• readonly signal: AbortSignal — Abattu quand l’agent abandonne l’appel.
• progress(progress: number, total?: number, message?: string): void — Signale l’avancement (notifications/progress).

IMcpTransport#

interface IMcpTransport

Le transport d’UNE requête, vu du protocole.

• signal?: AbortSignal — Abattu quand le client abandonne la requête.
• notify?: (notification: IJsonRpcNotification) => void — Émet une notification liée à la requête, AVANT la réponse finale.

IServerInfo#

interface IServerInfo

Ce que ce serveur sait faire, annoncé à l’initialisation.

• name: string
• version: string

ISessionFlowView#

interface ISessionFlowView

Vue minimale du flux de session (authFlow, fourni par @nodefony/security). Ce module n’en dépend pas : le service se résout par NOM.

• establishSessionFor(context: ContextType, identifier: string, reason?: string): Promise<unknown>

ISessionServiceView#

interface ISessionServiceView

Vue minimale du service de sessions (sessions, @nodefony/http).

• sessionRef(id: string): string — Pseudonyme public d’une session, non réversible.
• destroyByRef(ref: string, actor?: string | null): Promise<boolean> — Détruit la session désignée par son pseudonyme.

ISessionTicketStoreOptions#

interface ISessionTicketStoreOptions

Réglages du magasin — injectés par les tests, défauts en production.

• readonly now?: () => number — Horloge, en millisecondes.
• readonly fingerprint?: (ticket: string) => string — Empreinte d’un ticket (instrumentée pour compter les hachages).

ITicketSessionDeps#

interface ITicketSessionDeps

Ce dont la décision a besoin, fourni par la porte.

• readonly tickets: SessionTicketStore | null — Magasin des tickets, null si aucun n’a jamais été émis.
• readonly establish: (identifier: string) => Promise<ITicketSessionUser> | null — Ouvre la session pour identifier par le flux de session de l’application, null quand aucun n’est installé.
• readonly sessionRef: () => string | null — Pseudonyme public de la session ouverte, null si aucune ne l’est.
• readonly localOnly?: boolean — Refuser tout appel qui ne vient pas de la machine locale.

ITicketSessionGate#

interface ITicketSessionGate

Une porte de session par ticket définie — à servir depuis une action de controller.

• readonly settings: ITicketSessionGateSettings — Les réglages effectifs, validés et figés.
• readonly pending: number — Tickets émis, ni rachetés ni expirés.
• issue(identifier: string): string — Émet un ticket à usage unique pour identifier.
• serve(controller: Controller): Promise<unknown> — Sert la requête courante d’un controller : rachète le ticket et ouvre la session par le flux de l’application (authFlow, résolu par NOM).
• close(sessions: unknown, ref: string): Promise<boolean> — Détruit une session ouverte par ticket, au nom du facteur de la porte.

ITicketSessionRequest#

interface ITicketSessionRequest

Ce que la route reçoit, tel que la requête le présente.

• readonly ticket: unknown — Valeur de l’en-tête du ticket, non fiable.
• readonly remoteAddress: string — Adresse distante de la connexion.
• readonly relayed?: boolean — La requête a traversé un relais (isRelayedRequest) : sur une porte locale, l’adresse ne prouve alors plus la localité.

ITicketSessionUser#

interface ITicketSessionUser

Compte pour lequel la session vient d’être ouverte.

• readonly identifier: string
• readonly roles?: readonly string[]

Types (14)#

GuardVerdict#

type GuardVerdict = { allowed: true; } | { allowed: false; why: string; }

Verdict d’une garde : passer, ou refuser en disant pourquoi.

IAiConfig#

type IAiConfig = z.output<typeof aiConfigSchema>

Config telle que le CODE la lit — défauts appliqués, rien d’optionnel.

IAiConfigInput#

type IAiConfigInput = z.input<typeof aiConfigSchema>

Config telle que l’APP l’écrit dans use() — tous les champs optionnels.

IMcpConfig#

type IMcpConfig = z.output<typeof mcpConfigSchema>

Réglages mcp.* tels que le CODE les lit — défauts appliqués.

IMcpGateDefinition#

type IMcpGateDefinition = z.input<typeof mcpGateSchema>

Ce qu’on écrit pour définir une porte (défauts compris).

IMcpGateResponse#

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; }

Réponse DÉCRITE par la mécanique — la porte l’écrit.

IMcpGateSettings#

type IMcpGateSettings = z.output<typeof mcpGateSchema>

Les réglages EFFECTIFS d’une porte, validés et figés.

ITicketSessionGateDefinition#

type ITicketSessionGateDefinition = z.input<typeof ticketSessionGateSchema>

Ce qu’on passe à defineTicketSessionGate.

ITicketSessionGateSettings#

type ITicketSessionGateSettings = z.output<typeof ticketSessionGateSchema>

Réglages effectifs d’une porte de session par ticket.

JsonRpcId#

type JsonRpcId = string | number

Identifiant d’une requête : chaîne ou nombre (JSON-RPC 2.0 §4).

McpGateSeverity#

type McpGateSeverity = "DEBUG" | "WARNING" | "ERROR" | "CRITIC"

Sévérités qu’une porte MCP écrit au journal.

McpProgressToken#

type McpProgressToken = string | number

Un jeton de progression : chaîne ou entier (progress §Progress Flow).

McpProtocolVersion#

type McpProtocolVersion = (typeof MCP_SUPPORTED_VERSIONS)[number]

Une révision du protocole que ce paquet sait servir.

TicketSessionVerdict#

type TicketSessionVerdict = { readonly status: 200; readonly identifier: string; readonly roles: readonly string[]; readonly ref: string; } | { readonly status: 403 | 503; readonly message: string; }

Verdict de la route : la session ouverte, ou un refus.

← Toutes les références d’API