--- title: "Référence d'API — @nodefony/ai" source: docs/api/ai.md url: https://nodefony.github.io/nodefony-core/docs/api/ai/ --- [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` ```ts class AiError extends Error ``` Erreur du module ai. - `readonly code: string` - `readonly context?: Record` - `constructor(message: string, code?: string, context?: Record)` #### `SessionTicketStore` ```ts 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` ```ts class AiModule extends Module ``` - `constructor(kernel: Kernel)` - `onKernelRegister(): Promise` — Valide la config au boot — défauts du schéma fusionnés avec ce que l'app passe dans `use()`. ### Fonctions (30) #### `aiConfigJsonSchema` ```ts 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` ```ts function callMcpTool(name: string, args: Record, tools: readonly IMcpTool[], caller?: IMcpCaller, run?: IMcpToolRun): Promise ``` Exécute un outil par son nom public. #### `checkMcpAccess` ```ts function checkMcpAccess(input: IGuardInput, policy: IGuardPolicy): GuardVerdict ``` Décide si un appel MCP peut être servi. #### `collectMcpTools` ```ts function collectMcpTools(options: IMcpCollectOptions): IMcpTool[] ``` Ramasse les outils SERVIS à cet appelant. #### `createMcpResponseStream` ```ts function createMcpResponseStream(options: IMcpResponseStreamOptions): IMcpResponseStream ``` Fabrique le flux de réponse paresseux d'une requête MCP. #### `createProgressReporter` ```ts function createProgressReporter(token: McpProgressToken | null, notify: (notification: IJsonRpcNotification) => void, now?: () => number, minIntervalMs?: number): IMcpProgressReporter ``` Fabrique le rapporteur de progression d'un appel. #### `declareMcpTools` ```ts 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` ```ts function defineAiConfig(config?: unknown): IAiConfig ``` #### `defineMcpGate` ```ts function defineMcpGate(definition: IMcpGateDefinition): IMcpGate ``` Définit une porte MCP — UNE fois, à côté de son controller. #### `defineTicketSessionGate` ```ts 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` ```ts function fingerprintSessionTicket(ticket: string): string ``` Empreinte sous laquelle un ticket est rangé : le ticket brut n'est jamais gardé. #### `handleMcpMessage` ```ts function handleMcpMessage(message: IJsonRpcMessage | null, context: IMcpServerContext, headers?: IMcpHeaders): Promise ``` Traite UN message JSON-RPC. #### `insufficientScopeMessage` ```ts 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` ```ts function isLocalAddress(address?: string): boolean ``` #### `isNotification` ```ts function isNotification(message: IJsonRpcMessage): boolean ``` Un message est-il une NOTIFICATION — un appel SANS membre `id` ? #### `isRelayedRequest` ```ts function isRelayedRequest(headers: Readonly>): boolean ``` La requête a-t-elle traversé un relais (proxy inverse, répartiteur) ? #### `isSessionFlowView` ```ts function isSessionFlowView(value: unknown): value is ISessionFlowView ``` Le service résolu est-il un flux de session utilisable ? #### `isSessionServiceView` ```ts function isSessionServiceView(value: unknown): value is ISessionServiceView ``` Le service résolu est-il un service de sessions utilisable ? #### `jsonRpcFailure` ```ts 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` ```ts function jsonRpcSuccess(id: JsonRpcId, result: unknown): IJsonRpcSuccess ``` Fabrique une réponse de succès. #### `mcpCallScopes` ```ts function mcpCallScopes(tool: IMcpTool, args: Readonly>): 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` ```ts 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` ```ts 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` ```ts function mcpText(value: unknown, isError?: boolean): IMcpToolResult ``` Rend un résultat d'outil — les données partent en JSON COMPACT. #### `openTicketSession` ```ts function openTicketSession(request: ITicketSessionRequest, deps: ITicketSessionDeps): Promise ``` Décide l'ouverture d'une session par ticket. #### `publishMcpTools` ```ts function publishMcpTools(tools: readonly IMcpTool[]): IMcpToolDefinition[] ``` Projette les outils pour `tools/list` — sans leur implémentation. #### `readProgressToken` ```ts function readProgressToken(params: Record): McpProgressToken | null ``` Lit le jeton de progression d'une requête (`params._meta.progressToken`). #### `readTicketSessionVerdict` ```ts 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` ```ts function serveMcpStdio(gate: IMcpGate, options: IMcpStdioOptions): Promise ``` Sert une porte MCP sur un flux de lignes, jusqu'à la fin de l'entrée. #### `toTicketSessionUser` ```ts function toTicketSessionUser(value: unknown, identifier: string): ITicketSessionUser ``` Lit le compte rendu par le flux de session, sans lui faire confiance. ### Constantes (23) #### `JsonRpcError` ```ts 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` ```ts const MCP_DEFAULT_NEGOTIATED_VERSION = "2025-03-26" ``` Révision supposée quand un client n'en déclare AUCUNE. #### `MCP_PROGRESS_MESSAGE_MAX` ```ts const MCP_PROGRESS_MESSAGE_MAX = 1000 ``` Longueur maximale du `message` d'une progression, en caractères. #### `MCP_PROGRESS_MIN_INTERVAL_MS` ```ts const MCP_PROGRESS_MIN_INTERVAL_MS = 100 ``` Intervalle minimal entre deux notifications de progression, en millisecondes. #### `MCP_PROTOCOL_VERSION` ```ts 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` ```ts 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` ```ts 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` ```ts 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` ```ts 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` ```ts const MCP_TEXT_MAX_CHARS = 32000 ``` Au-delà de quoi une réponse cesse d'être une réponse. #### `META_PROTOCOL_VERSION` ```ts 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` ```ts const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo" ``` Clé de métadonnée portant l'identité du serveur dans `server/discover`. #### `McpProtocolError` ```ts 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` ```ts 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` ```ts 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` ```ts const SESSION_TICKET_LENGTH = 43 ``` Longueur d'un ticket : 32 octets d'aléa en base64url, sans remplissage. #### `SESSION_TICKET_MAX_PENDING` ```ts 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` ```ts 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` ```ts const TICKET_SESSION_REFUSED = "ticket de session refus\u00E9" ``` Message unique de tout refus : la cause fine ne sort jamais vers l'appelant. #### `aiConfigSchema` ```ts const aiConfigSchema: z.ZodObject<{ enabled: z.ZodDefault; }, z.core.$strict> ``` #### `mcpConfigSchema` ```ts const mcpConfigSchema: z.ZodObject<{ enabled: z.ZodDefault; allowedOrigins: z.ZodDefault>; allowRemote: z.ZodDefault; authorization: z.ZodDefault>; resource: z.ZodDefault; additionalResources: z.ZodDefault>; resourceName: z.ZodOptional; allowedOrigins: z.ZodDefault>; allowRemote: z.ZodDefault; authorization: z.ZodDefault>; resource: z.ZodDefault; additionalResources: z.ZodDefault>; resourceName: z.ZodOptional; }, z.core.$strict> ``` Définition d'une porte de session par ticket — validée et figée au boot. ### Interfaces (36) #### `IGuardInput` ```ts 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` ```ts 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` ```ts 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` ```ts 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` ```ts interface IJsonRpcSuccess ``` Réponse de succès. - `jsonrpc: "2.0"` - `id: JsonRpcId` - `result: unknown` #### `IMcpCacheHints` ```ts 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` ```ts 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` ```ts 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` ```ts interface IMcpDeclareOptions ``` Ce qu'il faut pour ÉNUMÉRER les déclarations d'outils d'une application. - `modules?: Readonly>` — Modules chargés (`kernel.modules`), dont on lit `getMcpTools()`. - `onSkip?: (why: string) => void` — Appelé pour chaque déclaration ÉCARTÉE, avec le motif. #### `IMcpEventSink` ```ts 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` — Envoie un message JSON-RPC ; peut lever à l'appel ou rendre une promesse de contre-pression. #### `IMcpGate` ```ts 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` — 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(request: IMcpGateRequest, runtime?: IMcpGateRuntime): Promise>` — Répond à UN `POST` décrit — sans controller, éprouvable sans serveur (et réutilisable par un autre transport). - `respondStdio(request: IMcpStdioRequest, runtime?: IMcpGateRuntime): Promise` — 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>): readonly IProtectedResourceInput[]` — Ce que la porte protège, à publier en RFC 9728 — une entrée, ou rien. #### `IMcpGatePosture` ```ts 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` ```ts interface IMcpGateRequest ``` 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)` — 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` ```ts interface IMcpGateRuntime ``` Ce que l'environnement fournit à une réponse — `serve()` le lit seul. - `modules?: Readonly>` — 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` ```ts 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` ```ts 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` ```ts 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` ```ts interface IMcpResponseStream ``` 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` — Attend les envois en cours puis, si un flux a été ouvert, y écrit la réponse finale. #### `IMcpResponseStreamOptions` ```ts interface IMcpResponseStreamOptions ``` Options de `createMcpResponseStream`. - `signal?: AbortSignal` — Abattu quand le client abandonne la requête. - `open?: (() => S | Promise)` — 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` ```ts 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` ```ts 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` ```ts 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)` — Ouvre le puits où écrire les notifications de l'appel, puis sa réponse finale — absent, la progression devient muette. #### `IMcpTool` ```ts 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>) => 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, caller: IMcpCaller, run?: IMcpToolRun) => IMcpToolResult | Promise` — Implémentation. #### `IMcpToolAnnotations` ```ts 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` ```ts 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` — Schéma JSON des arguments attendus. - `annotations?: IMcpToolAnnotations` — Ce que l'outil promet de son effet — à poser sur CHAQUE outil. #### `IMcpToolResult` ```ts 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` ```ts 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` ```ts 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` ```ts interface IServerInfo ``` Ce que ce serveur sait faire, annoncé à l'initialisation. - `name: string` - `version: string` #### `ISessionFlowView` ```ts 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` #### `ISessionServiceView` ```ts 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` — Détruit la session désignée par son pseudonyme. #### `ISessionTicketStoreOptions` ```ts 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` ```ts 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 | 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` ```ts 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` — 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` — Détruit une session ouverte par ticket, au nom du facteur de la porte. #### `ITicketSessionRequest` ```ts 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` ```ts interface ITicketSessionUser ``` Compte pour lequel la session vient d'être ouverte. - `readonly identifier: string` - `readonly roles?: readonly string[]` ### Types (14) #### `GuardVerdict` ```ts type GuardVerdict = { allowed: true; } | { allowed: false; why: string; } ``` Verdict d'une garde : passer, ou refuser en disant pourquoi. #### `IAiConfig` ```ts type IAiConfig = z.output ``` Config telle que le CODE la lit — défauts appliqués, rien d'optionnel. #### `IAiConfigInput` ```ts type IAiConfigInput = z.input ``` Config telle que l'APP l'écrit dans `use()` — tous les champs optionnels. #### `IMcpConfig` ```ts type IMcpConfig = z.output ``` Réglages `mcp.*` tels que le CODE les lit — défauts appliqués. #### `IMcpGateDefinition` ```ts type IMcpGateDefinition = z.input ``` Ce qu'on écrit pour définir une porte (défauts compris). #### `IMcpGateResponse` ```ts type IMcpGateResponse = { kind: "json"; status: number; body: unknown; headers?: Readonly>; } | { kind: "empty"; status: number; headers?: Readonly>; } | { kind: "stream"; stream: S; } ``` Réponse DÉCRITE par la mécanique — la porte l'écrit. #### `IMcpGateSettings` ```ts type IMcpGateSettings = z.output ``` Les réglages EFFECTIFS d'une porte, validés et figés. #### `ITicketSessionGateDefinition` ```ts type ITicketSessionGateDefinition = z.input ``` Ce qu'on passe à `defineTicketSessionGate`. #### `ITicketSessionGateSettings` ```ts type ITicketSessionGateSettings = z.output ``` Réglages effectifs d'une porte de session par ticket. #### `JsonRpcId` ```ts type JsonRpcId = string | number ``` Identifiant d'une requête : chaîne ou nombre (JSON-RPC 2.0 §4). #### `McpGateSeverity` ```ts type McpGateSeverity = "DEBUG" | "WARNING" | "ERROR" | "CRITIC" ``` Sévérités qu'une porte MCP écrit au journal. #### `McpProgressToken` ```ts type McpProgressToken = string | number ``` Un jeton de progression : chaîne ou entier (`progress` §Progress Flow). #### `McpProtocolVersion` ```ts type McpProtocolVersion = (typeof MCP_SUPPORTED_VERSIONS)[number] ``` Une révision du protocole que ce paquet sait servir. #### `TicketSessionVerdict` ```ts 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](../)