aggrega mcp
Exécuter un serveur Model Context Protocol sur l’entrée et la sortie standard, ou sur HTTP, pour l’intégration d’assistants IA
Synopsis
aggrega mcp [flags]Description
Run Aggrega as a Model Context Protocol (MCP) server, so an AIassistant can discover and drive Aggrega operations through a structuredprotocol instead of scraping command output.
Two transports reach the same server, and --transport chooses betweenthem, with mcp.transport in the workspace configuration as the key itoverrides. The default, stdio, speaks newline-delimited JSON-RPC 2.0 overthe process's standard input and output, which is how an MCP-capableclient runs it: spawned as a subprocess, not typed by hand. http servesthe protocol over HTTP instead — one long-running process on a host,reached by callers who are not at its keyboard — on the address --listennames, or mcp.listen when the flag is absent.
An address chooses no transport. --listen given with the stdio transportis refused, whether stdio was typed, configured or left as the default,because it names where to listen for a transport that does not listen.An address mcp.listen names is left unused by a server on standard inputand output, which says so in one line on stderr, so a client can launchthis command in a directory whose configuration is written for alistener. And the http transport with no address from either is refusedbefore anything binds.
It speaks two MCP protocol revisions on both transports, 2026-07-28 and2025-06-18, so a client of either connects. In 2026-07-28 nothing issettled for the connection as a whole: every request states the protocolversion it speaks and the capabilities its sender offers, and the serverreads both from the request it is answering rather than holding anythingbetween messages. In 2025-06-18 a client settles those same facts once,by opening the connection with an initialize handshake.
Both revisions reach the same server, and a client learns the samethings about it either way. A client on 2026-07-28 calls server/discoverfor the revisions the server speaks, the capabilities it advertises —tools, resources, and prompts — and the guidance it offers a modelbefore the first call. A client on 2025-06-18 receives those samecapabilities, and that same guidance, in the reply to its handshake.
From there the client discovers the server's surface through the listmethods (tools, resources, resource templates, and prompts) and invokesit through tools/call and resources/read. The server exposes Aggregaoperations — compiling and inspecting a Release, reading catalogentities — as tools and resources an assistant can call directly.
On standard input and output, stream discipline is strict: stdout carriesonly protocol messages, one JSON object per line, so the client can parsethe stream without heuristics. Every log, warning, and diagnostic iswritten to stderr instead. The server reads one message per line andexits cleanly when stdin reaches end of stream, so a client that closesthe connection shuts the server down. A client ends one call by namingits id, and every other call carries on.
Over HTTP there is one endpoint, /mcp, accepting POST. Every message isits own request and no session of any kind is kept, so nothing a clientsends first decides how a later request is answered. Closing theconnection ends the call it carried. A request carrying an Origin headeris checked against mcp.allowed_origins, and mcp.limits bounds how largeone request body may be, how many requests are answered at once, and howmany one caller may send in a minute. A caller sending faster thanmcp.limits.requests_per_minute is answered 429, counted against thatcaller alone.
Every request to /mcp carries a credential, and which one depends onwhether a proxy in front has already checked it. By default it is abearer token the server verifies itself, against the keysmcp.authorization.issuer publishes: it must come from that issuer, namemcp.authorization.resource among its audiences, be inside its validitywindow, and be signed with an asymmetric algorithm. A request carrying notoken is answered 401 with a challenge, and so is one whose token failsany of those. A token is never accepted from the address, never forwardedanywhere, never exchanged, and never written to any log; the subject itnames is recorded and compared to nothing.
Set mcp.authorization.trusted_proxy instead and the caller is read from aheader the proxy sets rather than from a token, with its scopes from asecond header; no token is read at all in that mode, and a requestwithout the principal header is answered 401. Because that header is thenthe whole credential, it is trustworthy only where nothing else can setit: the process is refused before it binds unless mcp.listen is loopbackor a Unix socket.
The challenge names where to obtain a token. A listener publishes anOAuth protected-resource metadata document, with no credential asked for,naming the authorization server, this deployment's own address and thescopes that exist; it is served at /.well-known/oauth-protected-resourceand at that path followed by the endpoint path, which are the two placesa client looks. A client reads it before it can hold a token, which iswhy it is the one answer given without one. What that document publishescomes from mcp.authorization.issuer and mcp.authorization.resource, and alistener is refused before it binds unless both are set.
The issuer is an https address unless the authorization server runs onthis machine (localhost, 127.0.0.1 or ::1), and that holds in everymode: with the keys read from the issuer, with a key file, and with aproxy in front. Every client is sent to the issuer to obtain its token,so a plain http issuer on another host would carry each client'sauthorization code and token across the network unprotected, and alistener naming one is refused before it binds.
The verification keys are read from the issuer itself, by asking it whereit publishes them and fetching them from the address it names, and readagain once when a token arrives signed by a key identifier the held setdoes not carry. That address is held to the same rule as the issuer, andso is every redirect either read is answered with: a plain http addresson another host is never asked, and a token needing those keys isanswered 503 until the authorization server publishes its metadata andkeys over https. A workspace that is offline makes no such request, sothere mcp.authorization.jwks_file names a file holding those keys and alistener is refused before it binds without it.
Liveness and readiness are answered on a second address, and only there.Set mcp.health.listen and a GET of /healthz reports that the process isrunning while a GET of /readyz reports whether it can answer a call yet,each a status code with an empty body and no credential asked for. Theaddress opens before the workspace is resolved, so a supervisor sees theprocess alive while it is still deciding whether it can serve at all.Leave the key unset and no second listener exists. The endpoint itselfanswers both paths the same not-found it gives every path it does notserve, with a token and without one, so reaching this process over thenetwork is never a way to probe it.
The workspace this process serves is fixed when it starts, on eithertransport: --workspace-root names it, and AGGREGA_WORKSPACE_ROOT suppliesit when the flag is absent. The folder named is the workspace rootitself, as it is for every command: a call naming no workspace of itsown is answered there, and nothing above it is searched for a workspace,so name the folder that holds the workspace's .aggrega-config.yaml. Anamed folder that does not exist is refused, naming the flag or thevariable that supplied it and the value as it was given: a listener isrefused before it binds, while a server on standard input and outputwrites the refusal to stderr and starts all the same, answering everycall that acts in that workspace with it, so a client that showsnothing of stderr still shows the refusal. An emptyAGGREGA_WORKSPACE_ROOT is read as unset, but for one launch: a serveron standard input and output given no --workspace-root, whoseenvironment carries the AGGREGA_BUNDLE_VERSION the desktop bundle sets,was started with the desktop application's Workspace folder settingempty. It is served the same way, the refusal naming that setting, sono call naming no workspace of its own is answered in the directory itwas started in. In every other case where neither names a root, aserver on standard input and output resolves the workspace from thedirectory it was started in, while a listener is refused before itbinds unless a workspace resolves there: one reachedover HTTP serves a workspace an operator chose rather thanwhichever directory it happened to be started in. Where that directoryanchors no workspace, a call naming no workspace of its own that namesits Release or document by an absolute path is answered in the workspacethat file's folder resolves, as the same command typed at a terminal inthat directory would be.
For the same reason a call arriving over HTTP cannot name a workspace ofits own. Sending workspace_root or catalog_dirs is refused, naming theargument, and the directories searched for catalog entities beside theserved workspace are the ones that workspace itself resolves: its ownworkspace.catalog_dirs setting — or, for a Release it gives directoriesof its own under workspace.releases, that Release's — then its catalogdirectory. Overstandard input and output both arguments are honoured: the client thatlaunched the server is running on this machine.
A workspace_root such a call sends is read the same way by every tool,the tools that run a command included. An absolute one is used asgiven. A relative one is read from the root a call naming no workspaceof its own is answered in — the folder --workspace-root orAGGREGA_WORKSPACE_ROOT names, which the desktop application sets fromits Workspace folder, or, where neither names one, the workspace rootthe directory the server was started in resolves to — so a client thatcannot see where that folder sits on the machine still names a folderinside it, as quickstart-ai/1. Where there is no such root to read itfrom, a relative one is refused as a call naming none is refused, andan absolute one is answered as it always is.
Asking the process itself to stop — an interrupt from the terminal, or atermination request from a supervisor or container runtime — shuts theserver down on the first request, whether or not a client is sendinganything: it stops accepting messages, ends the work a call in progressis doing, and exits cleanly. A listener stops accepting and lets a callalready being answered finish, within a bounded budget, before theprocess exits. A second request ends the process at once.Options
| Option | Par défaut | Description |
|---|---|---|
--listen | — | L’adresse sur laquelle écoute le transport HTTP, sous l’une de deux formes : host:port, ou unix: suivi d’un chemin du système de fichiers. Elle indique où écouter et ne choisit aucun transport : elle est lue avec —transport http, ou mcp.transport: http dans la configuration du workspace, et, donnée avec le transport stdio, elle est refusée. Un listener sans certificat sert en clair et n’est autorisé que sur le loopback (127.0.0.1, ::1, localhost) ou sur un socket Unix, ce qui est la forme que prend un serveur derrière un proxy de terminaison ; toute autre adresse nécessite mcp.tls.cert_file et mcp.tls.key_file, que ce processus utilise alors pour terminer TLS lui-même. Lorsqu’elle est définie, elle remplace la clé de configuration mcp.listen. |
--transport | — | Comment le serveur est atteint : stdio parle le protocole sur l’entrée et la sortie standard, ce qui est la façon dont l’atteint un client qui lance cette commande comme sous-processus ; http le sert sur HTTP à l’adresse que nomme —listen ou mcp.listen, et sur HTTPS là où mcp.tls nomme un certificat et une clé. Lorsqu’il est défini, il remplace la clé de configuration mcp.transport, dont la valeur par défaut est stdio. |
Fonctionnement
aggrega mcp exécute un serveur Model Context Protocol. Deux transports l’atteignent, et --transport choisit entre eux : stdio ou http, avec mcp.transport dans la configuration du workspace comme clé que le flag remplace, et stdio comme valeur par défaut.
Sur stdio, la valeur par défaut, il communique par l’entrée et la sortie standard du processus. Sous cette forme, ce n’est pas une commande que vous exécutez de manière interactive — un client compatible MCP le lance comme sous-processus et parle le protocole sur stdio ; Connecter le serveur MCP indique où chaque client conserve l’entrée qui le lance. L’exécuter transforme la CLI en un assistant de rédaction qui connaît Aggrega au sein de votre éditeur ou de votre client de chat.
Sur http, il sert plutôt le protocole sur HTTP : un seul processus de longue durée sur un hôte, atteint par des appelants qui ne sont pas devant son clavier, à l’écoute sur l’adresse que nomme --listen, ou mcp.listen lorsque le flag est absent. Consultez Atteindre le serveur sur HTTPS pour savoir comment ce listener est configuré et ce qu’il accepte.
Il parle deux révisions du protocole, 2026-07-28 et 2025-06-18, de sorte qu’un client de l’une ou l’autre se connecte et atteint les mêmes surfaces. La révision que parle un appel est indiquée sur cet appel plutôt que convenue une fois pour la connexion. Un client en 2026-07-28 envoie avec chaque requête la version du protocole qu’il parle et ses propres capacités, et demande à server/discover ce que le serveur prend en charge ; un client en 2025-06-18 règle ces mêmes choses une seule fois, en ouvrant la connexion par un handshake initialize. Dans les deux cas, le serveur ne conserve rien entre les messages, de sorte que ce que vous envoyez en premier ne décide rien de la façon dont un appel ultérieur reçoit sa réponse. Une requête qui nomme une révision que le serveur ne parle pas est refusée, et on lui indique les deux qu’elle peut demander, plutôt que de lui répondre comme si elle avait demandé l’une d’elles.
Le serveur expose trois surfaces à l’assistant connecté :
-
Prompts — deux familles, et la différence tient à ce à quoi chacune répond. Les prompts de rédaction répondent à « qu’est-ce que j’écris » : une persona par rôle (développement, architecture, exploitation), plus un modèle ciblé par entité. Chacun cadre le rôle et oriente l’assistant vers le bon schéma, la bonne page de référence et le bon guide de rédaction, de sorte que ses suggestions restent dans les piliers dont ce rôle est responsable. Les prompts de workflow répondent à « quels appels, dans quel ordre » : chacun expose la séquence ordonnée d’appels d’outils qui atteint un objectif couvrant plusieurs opérations, avec les points de décision entre eux — composer de zéro un nouvel Aggregate et sa Release, faire entrer dans Aggrega un chart, un module d’infrastructure ou un fichier container-compose existant, comprendre pourquoi un build ne compile pas ou rend les mauvais artefacts.
prompts/listénumère les deux familles etprompts/geten rend un, de sorte que l’ensemble se lit sur le serveur plutôt que sur cette page.Un prompt de workflow nomme les appels et c’est vous qui les faites, un à la fois, en lisant chaque résultat avant le suivant. Aucun appel ne réalise un objectif entier : chaque outil encapsule une opération que vous pouvez vérifier, c’est donc la séquence qui vous mène au but. Les personas de rédaction acceptent un
kindfacultatif sur lequel se concentrer, le modèle par entité en exige un, et unkindauquel aucun schéma ne correspond est refusé avec la liste des valeurs acceptées plutôt que d’être ignoré en silence. -
Ressources — documentation de référence en lecture seule servie en ligne :
schema://<kind>pour le JSON Schema d’une entité,langref://<path>pour toute page de la référence du langage,authoring://<topic>pour le guide de rédaction,catalog://<kind>/<name>pour le YAML rédigé d’une entité du catalogue, etcli://<command>pour l’aide propre d’une commande, aveccli://seul comme point d’entrée — cette aide est fournie à partir des commandes que le serveur embarque lui-même, de sorte qu’en lire une ne démarre aucun processus et renvoie le même texte que celui qu’affiche la commande pour--help. Une lecturecatalog://d’une entité que le catalogue ne contient pas reçoit une réponse « introuvable » ; lorsque c’est parce qu’exactement un fichier du catalogue déclarant l’entité a été ignoré au chargement, le message de la réponse nomme ce fichier, la contrainte qu’il enfreint et le code court de la condition au lieu de la seule URI — le refus par lequelaggrega buildcommence pour le même fichier.resources/listénumère celles qui sont adressables sans paramètre etresources/templates/listannonce la forme d’URI de chaque famille. -
Outils — des actions sur votre workspace, et
tools/listrépond avec tous.Les outils qu’un assistant rencontre en premier sont conçus pour la boucle de rédaction :
list-entitiesetlist-releasespour découvrir ce que contient le workspace,scaffoldpour un squelette portant les champs qu’exige son type, avec un espace réservé partout où une valeur est due — ou, avecexample, pour écrire l’un des exemples exécutables de la documentation dans un nouveau répertoire, en répondant avec l’emplacement de ce répertoire, les fichiers écrits et les commandes pour le construire, et, aveclist: true, pour lister les exemples —get-schemapour le JSON Schema d’une entité,validatepour valider un brouillon (il nomme chaque espace réservé que le brouillon porte encore, et ce que chacun accepte),describepour décrire une entité du catalogue — ou une entité lue depuis son registry par référence —pullpour résoudre les dépendances d’une Release dans le cache local et écrire son lockfile,buildpour construire une Release en ses artefacts rendus — en mémoire par défaut, sans aucun artefact écrit sur le disque, ou écrits dansdist/à la racine du workspace, là oùaggrega buildles écrit, lorsque vous envoyezwrite(et les dépendances ne sont résolues d’abord que si vous envoyezauto_pull),gen-catalogpour générer des entités Plugin à partir d’invités Wasm, etexplain-errorpour développer un diagnostic du compilateur en indications exploitables — y compris, lorsque le diagnostic commence par le code court d’une condition d’arrêt, cette condition et le guide publié de la correction à apporter, le même développement que celui que donneaggrega explainpour le même code dans un terminal.Le reste de la surface se trouve dans la même réponse plutôt que derrière elle : d’autres outils qui s’exécutent au sein du serveur —
lint, l’outil qui nomme la connexion écrite à un endroit d’un document, les deux outils de candidature, les outils de conteneur d’attachements et de point d’insertion, l’outil qui applique une modification délimitée à un document,pin, qui enregistre les épinglages de contenu des entrées d’une entité comme l’expose Épingler les entrées propres d’une entité, et les quatre outils de publication décrits ci-dessous, ainsi que des inventaires des caches et des registries configurés — et, pour un client qui a lancé ce serveur sur son entrée et sa sortie standard, un outil pour chaque commande que vous pourriez sinon taper, nommé d’après son chemin d’invocation. Ces outils de commande n’existent que sur ce transport : un serveur atteint sur HTTP n’en propose aucun, pour la raison donnée sous Atteindre le serveur sur HTTPS. Rien n’est réservé pour un appel ultérieur. La part d’une liste d’outils à présenter à un modèle est une décision qui revient au client — il récupère les définitions et choisit ce qu’il charge — et une définition qu’un client n’a jamais reçue est une opération qu’un modèle ne peut jamais appeler, aussi accessible que soit le nom de cet outil sur le fil. Lorsque la liste complète dépasse ce que votre client accepte, Restreindre ce qu’annonce le serveur est la façon de la raccourcir.describe-capabilitiesrestreint cette surface au type d’entité que vous rédigez. Avec unkind, il répond avec les outils qui servent ce type, déterminés d’après les types que déclare chaque outil plutôt que d’après les mots d’une description ; sans argument, il répond avec ce même index sur chaque outil que ce serveur vous propose — le nom de chacun, un objectif en une ligne, les types qu’il sert et s’il écrit, sans schémas d’arguments, de sorte que toute la surface arrive en une seule réponse lisible. Pour un outilcli-, le fait qu’il écrive dépend de ce que la commande qu’il exécute écrit ou non :cli-buildest indiqué comme écrivant, car la commande enregistre les artefacts rendus sous la racine du workspace, de même quecli-scaffold, car avecexamplela commande écrit l’un des exemples exécutables de la documentation dans un nouveau répertoire, tandis qu’une commande qui ne fait que lire est indiquée comme en lecture seule, même lorsqu’elle remplit en chemin un cache que partagent tous les projets de la machine, comme l’outil qui exécute la même opération au sein du serveur ; avectoolsnommant un ou plusieurs outils, il répond avec exactement les définitions complètes et les schémas d’arguments de ces outils. Les outilscli-ne sont jamais restreints par type, car rien n’enregistre quel type d’entité sert une commande, de sorte qu’une réponse limitée à un type les omet et que l’index sans argument est l’endroit où les lire. Les arguments d’un outil de commande sont nommés d’après les flags propres de la commande, de sorte que--output-direst envoyé sous la formeoutput_dir, et un nom non reconnu est refusé avec la liste des graphies acceptées plutôt que d’être écarté en silence.Certaines capacités sont présentes deux fois sur l’entrée et la sortie standard : un outil conçu pour la boucle de rédaction exécute l’opération au sein du serveur, et l’outil nommé d’après la commande qui porte la même capacité exécute cette commande. Les deux ne se comportent pas de la même façon, donc sur ce transport chacun nomme l’autre et en indique la différence ; sur HTTP, les outils de commande sont absents, et la phrase d’appariement est omise plutôt que de désigner un outil que l’appelant ne peut pas atteindre. Celui qui s’exécute au sein du serveur est celui à privilégier — il répond avec un résultat lisible par machine à côté du texte lisible, de sorte qu’un assistant obtient un verdict, une liste de fichiers ou un diagnostic sous forme de champs plutôt que sous forme de transcription à analyser. L’outil de commande lance la vraie commande dans un processus séparé, il fait donc tout ce que fait cette commande sur la machine où elle s’exécute, y compris écrire sur le disque là où la commande écrit —
cli-buildécrit les artefacts rendus dansdist/à la racine du workspace, et les fichiers d’un build tracé dans.trace/à côté, et la ligne finale qu’il renvoie nomme ce répertoire en entier — et ne renvoie que la ligne de commande qu’il a exécutée et le texte que cette commande a affiché. Utilisez-le lorsque vous avez besoin d’un flag que la commande déclare et que l’autre outil n’accepte pas.Cette ligne de commande commence par les flags globaux avec lesquels ce serveur a été démarré et qui décident de la configuration —
--configet--offline, si vous les avez donnés — avant la commande et les flags propres de l’appel. Ainsi, la commande lit la configuration que lit tout autre outil ici : un serveur démarré avec--offlineexécute ses commandes hors ligne, et un serveur démarré avec--configles exécute sur ce fichier global. Un flag que l’appel envoie pour lui-même vient après eux et l’emporte, de sorte queoffline: falsesur un appel atteint le réseau pour cet appel seulement, et la ligne de commande renvoyée montre les deux. Lorsque le serveur a été démarré avec une racine de workspace — par--workspace-rootou parAGGREGA_WORKSPACE_ROOT— la ligne de commande commence par cette racine sous la forme--workspace-root, avant ces deux-là, de sorte que la commande prend ce répertoire comme racine de workspace, comme elle le ferait tapée avec le même flag et comme le prend tout outil s’exécutant au sein du serveur, plutôt que de trouver son workspace à partir du répertoire dans lequel le serveur a été démarré. Un appel qui envoieworkspace_rootnomme la sienne, et la ligne de commande ne porte que celle-ci — y compris une valeur vide, que la commande lit comme se lit--workspace-root ""dans un terminal : trouver le workspace à partir du répertoire dans lequel le serveur a été démarré. Un serveur démarré sans l’un ni l’autre ne transmet aucune racine, de sorte que ses commandes trouvent leur workspace à partir de ce répertoire, selon la règle qu’établit Dans quel workspace un appel reçoit sa réponse pour chaque outil — sauf lors du lancement du bundle de bureau avec son paramètre Workspace folder vide, où un appel ne nommant aucun workspace propre ne démarre aucune commande et reçoit en réponse le refus de ce paramètre. La commande démarre dans la racine de workspace que nomme l’appel ou le lancement : leworkspace_rootpropre de l’appel, lu comme le lit chaque outil — un absolu tel qu’il a été envoyé, un relatif à partir de la racine dans laquelle reçoit sa réponse un appel n’en nommant aucun — et transmis à la commande sous sa forme absolue, sinon la racine avec laquelle le serveur a été démarré. Ainsi, un chemin relatif qu’un appel passe comme fichier à lire — un document à soumettre àvalidate, un--releaseou un--catalog— est lu au sein de ce workspace, comme dans un terminal ouvert à cet endroit, et un build qu’exécute la commande écritdist/sous cette racine. Lorsque rien ne nomme de racine — aucune racine de lancement, et aucunworkspace_rootou un vide — la commande démarre dans le répertoire dans lequel le serveur a été démarré et lit un chemin relatif à partir de là ; unworkspace_rootne nommant aucun dossier existant est transmis tel qu’il a été lu — un absolu tel qu’il a été envoyé, un relatif sous sa forme complète — et la commande le refuse dans ses propres termes. Une commande qu’enregistre un plugin d’extension de commandes n’en reçoit aucun, car elle transmet chaque argument au plugin sans le lire plutôt que d’analyser un flag global, dans un terminal comme ici ; elle démarre dans le même dossier que toute autre commande.Quelques commandes sont délibérément absentes même sur l’entrée et la sortie standard, là où les outils de commande existent — sur HTTP, elles sont toutes absentes, et c’est une propriété du transport plutôt que d’une commande. Sur l’entrée et la sortie standard, chacune de celles-ci est omise pour une raison énoncée : le daemon et ce serveur lui-même ne renverraient jamais de résultat ; une commande qui lit un mot de passe depuis le terminal n’a rien d’où le lire ; une commande qui écrit un script de complétion de shell n’a aucun shell où l’installer ; supprimer un credential stocké agit sur le magasin de toute la machine plutôt que sur un workspace que vous avez nommé ; et acquérir un jeton d’identité de manière interactive n’a aucune forme non interactive à proposer. Absente pour ce même motif lié à toute la machine,
aggrega plugin run-localcharge un invité.wasmdepuis un chemin que vous lui donnez : ce à quoi sert la commande, c’est lire un fichier où que vous l’ayez placé, il n’existe donc aucun workspace auquel elle pourrait être confinée, et la lecture a lieu dans le processus lui-même avant que l’invité n’existe. Rien n’est accordé à l’invité lorsqu’il s’exécute — aucun répertoire, aucun socket, aucun environnement — mais c’est une limite sur le module plutôt que sur la lecture, ce n’est donc pas ce qui en décide. Exécutez-la dans votre terminal, là où c’est vous qui nommez le chemin. La signature et la publication sont un tout autre cas, et c’est cette différence qui les tient hors de cette liste. Chacune résout une identité à partir d’une entrée fournie ou ambiante et refuse explicitement lorsqu’aucune n’est disponible, de sorte que chacune a une forme qui aboutit sans que personne ne regarde — alors qu’acquérir un jeton de manière interactive est un verbe qu’aucune entrée ne peut satisfaire, même en principe. Elles sont donc présentes deux fois : comme commandes, et comme les quatre outils internes au processus décrits sous Publier, signer et retirer. Là où la ligne de commande ouvrirait un navigateur, elles refusent et nomment ce qu’il faut fournir à la place, plutôt que d’attendre une personne qui n’est pas là.
Dans quel workspace un appel reçoit sa réponse
Un appel nomme son workspace avec workspace_root ; sinon, il reçoit sa réponse dans le workspace sur lequel le serveur a été démarré. Lorsque le lancement a nommé une racine, avec --workspace-root ou AGGREGA_WORKSPACE_ROOT, cette racine est la racine du workspace elle-même, comme l’est le flag sur chaque commande : rien au-dessus d’elle n’est parcouru à la recherche d’un workspace englobant, de sorte qu’un lancement nomme le dossier qui contient le .aggrega-config.yaml du workspace, et qu’un appel y reçoit sa réponse aussi bien des outils s’exécutant au sein du serveur que des outils de commande. Lorsque le lancement n’en a nommé aucune, le workspace est trouvé à partir du répertoire dans lequel le serveur a été démarré, exactement comme le découvre une commande tapée dans un terminal à cet endroit — l’ordre est exposé sous Les autres façons dont une racine de projet est reconnue — sauf lors du lancement du bundle de bureau avec son paramètre Workspace folder vide, qui refuse alors un tel appel, comme exposé ci-dessous. Un workspace_root relatif est lu à partir de la racine dans laquelle reçoit sa réponse un appel n’en nommant aucun — la racine qu’a nommée le lancement ou, s’il n’en a nommé aucune, la racine de workspace à laquelle se résout le répertoire dans lequel le serveur a été démarré — de sorte qu’un appel nomme un dossier au sein du workspace, comme quickstart-ai/1, sans savoir où se trouve le workspace sur la machine ; un absolu est utilisé tel qu’il est donné. Chaque outil le lit ainsi, outils de commande compris. Lorsqu’il n’existe aucune racine à partir de laquelle lire un relatif — une racine de lancement qui n’est pas un dossier existant, ou le lancement de bureau avec un Workspace folder vide — un relatif est refusé comme l’est un appel n’en nommant aucun. Un workspace_root qui ne nomme aucun dossier existant, ou qui nomme un fichier, est refusé avant que l’outil ne fasse quoi que ce soit d’autre, en nommant l’argument et en citant la valeur — un absolu tel qu’il a été envoyé, un relatif sous la forme complète dans laquelle il a été lu — comme une commande refuse --workspace-root.
Une racine de lancement qui n’est pas un dossier existant est servie comme un refus sur l’entrée et la sortie standard. Lorsque --workspace-root ou AGGREGA_WORKSPACE_ROOT nomme un dossier qui n’existe pas, ou nomme un fichier, le serveur écrit le refus dans son flux d’erreur et démarre malgré tout, de sorte qu’un client qui ne montre rien de ce flux à son utilisateur en montre tout de même la raison. Il répond à initialize et à ses listes d’outils, de ressources et de prompts, et chaque appel qui agirait dans ce workspace reçoit le refus en réponse : un appel d’outil comme résultat en échec, une lecture d’une entité catalog:// ou d’une page de documentation comme erreur. Le refus nomme le flag, ou la variable avec le paramètre Workspace folder de l’application de bureau qui la définit — le paramètre que décrit Claude Desktop — et cite la valeur exactement telle qu’elle a été donnée ; une valeur que le client a envoyée sans la renseigner est citée telle qu’elle est arrivée, et rien de son contenu n’est interprété. Un outil qui exécute une commande n’en démarre aucune pour un appel ne nommant aucun workspace propre, puisque le dossier dans lequel cette commande démarrerait n’existe pas, et répond avec le même refus. Un appel qui nomme un workspace propre par un chemin absolu y reçoit sa réponse ; un appel qui le nomme par un chemin relatif n’a aucun dossier à partir duquel le lire, et reçoit le même refus en réponse. Ce qui n’agit dans aucun workspace — un schéma, un prompt, l’aide d’une commande — reçoit sa réponse comme sur n’importe quel serveur. Un listener est au contraire refusé au démarrage, avant que quoi que ce soit ne soit lié, avec le même refus, de sorte que quiconque le supervise lit l’échec là où il le cherche.
Un lancement de bureau avec son paramètre Workspace folder vide est servi comme un refus de la même façon. Le bundle de bureau transmet toujours au serveur AGGREGA_WORKSPACE_ROOT, avec ce que contient Workspace folder, et définit AGGREGA_BUNDLE_VERSION à côté, tandis que l’application démarre le serveur dans un dossier de son choix — souvent un dossier système — plutôt que dans votre projet. Ainsi, un serveur sur l’entrée et la sortie standard démarré sans --workspace-root, dont l’environnement porte AGGREGA_BUNDLE_VERSION et un AGGREGA_WORKSPACE_ROOT vide ou absent, ne cherche pas de workspace à partir du dossier dans lequel il a été démarré. Il écrit le refus dans son flux d’erreur et démarre malgré tout, en répondant comme pour une racine de lancement qui n’existe pas : chaque appel qui agirait dans un workspace et n’en nomme aucun propre reçoit en réponse un refus indiquant que l’application de bureau a lancé le serveur avec son paramètre Workspace folder vide, de sorte que AGGREGA_WORKSPACE_ROOT ne nomme aucune racine de workspace, vous demandant de définir Workspace folder sur le dossier qui contient le .aggrega-config.yaml de votre workspace, et indiquant qu’un dossier défini après le démarrage du serveur prend effet une fois l’extension désactivée puis réactivée ou l’application redémarrée, car l’application ne transmet le paramètre au serveur qu’au moment où elle le démarre. Un outil qui exécute une commande n’en démarre aucune pour un tel appel. Un appel qui nomme un workspace propre par un chemin absolu y reçoit sa réponse, et un appel qui le nomme par un chemin relatif reçoit le même refus, puisqu’il n’existe aucun Workspace folder à partir duquel le lire ; ce qui n’agit dans aucun workspace reçoit sa réponse comme sur n’importe quel serveur. Le serveur reconnaît le lancement à AGGREGA_BUNDLE_VERSION seule : un bundle qui ne définit pas cette variable voit un paramètre vide lu comme aucune racine, et un lancement qui définit la variable à la main et ne nomme aucune racine est refusé comme celui du bundle. Toute autre valeur vide continue de ne nommer aucune racine — un AGGREGA_WORKSPACE_ROOT vide sur un lancement ne portant aucune AGGREGA_BUNDLE_VERSION, un --workspace-root tapé vide, un listener, aggrega serve et toute autre commande la lisent chacun comme non définie.
Lorsqu’aucun workspace n’a été trouvé et qu’aucun n’a été nommé, une réponse qui concerne le workspace indique quel dossier elle a utilisé. Sans racine de lancement, sans workspace_root sur l’appel et sans rien qui ancre un workspace à partir du dossier dans lequel l’appel a reçu sa réponse, l’appel reçoit sa réponse dans ce dossier. Lorsque le résultat de l’outil dépend du workspace — les mêmes outils dont les commandes émettent un avertissement sur la ligne de commande — son texte se termine par l’avertissement de la ligne de commande, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, et par une ligne qui vous demande d’envoyer workspace_root en nommant le dossier qui contient le .aggrega-config.yaml de votre workspace ; une réponse que le workspace ne détermine pas, comme la lecture de la configuration ou la liste des plugins, ne dit rien des workspaces. La phrase n’ajoute aucun champ propre au résultat structuré ; le résultat structuré la porte dans text_answer, qui contient le texte, comme l’expose Les deux parties d’une réponse. Un outil qui exécute une commande dans un processus séparé porte la ligne propre de la commande qui dit la même chose, telle que la commande l’a affichée. Rien n’est écrit dans un cache d’artefacts dans un tel dossier : un pull, ou un build auquel on demande de résoudre d’abord ses dépendances, y est refusé avant que quoi que ce soit ne soit récupéré, en nommant le dossier et les deux possibilités — envoyer workspace_root, ou donner au dossier un .aggrega-config.yaml portant un bloc workspace:. Un épinglage, ou une publication d’une Recipe ou d’une FeatureRecipe, est refusé de la même façon lorsqu’il récupérerait une source distante que l’entité écrit en entier — pour l’épingler, ou pour comparer son épinglage — avant que cette source ne soit récupérée ; lorsqu’il n’en récupère aucune, parce que l’entité n’a pas de source, en a une locale ou une dont chaque Release renseigne les coordonnées, il reçoit sa réponse comme partout ailleurs. Un build à cet endroit qui ne résout rien au préalable effectue tout de même le rendu, mais une entrée externe que son lockfile épingle et que le cache ne contient plus n’est pas récupérée à nouveau : le rendu reçoit cette même phrase à la place de l’entrée, comme il reçoit celle d’un mode hors ligne. Aucune réponse sur HTTP ne porte la phrase : un listener sert toujours un workspace qui lui a été donné ou qu’il a trouvé. Le lancement du bundle de bureau avec un paramètre Workspace folder vide ne la porte pas non plus, puisqu’il refuse un appel ne nommant aucun workspace propre plutôt que de lui répondre dans le dossier dans lequel il a été démarré.
Un appel portant sur une Release ou sur un document qu’il nomme par un chemin absolu reçoit sa réponse dans le workspace propre de ce fichier lorsque rien d’autre n’en a fixé un. Lorsque le lancement n’a nommé aucune racine, que l’appel n’envoie aucun workspace_root et que le répertoire dans lequel le serveur a été démarré n’ancre aucun workspace, le workspace est à nouveau découvert à partir du dossier où se trouve ce fichier, et ce que cela trouve — le projet auquel appartient le fichier ou, à défaut de tout le reste, ce dossier — est celui dans lequel l’appel reçoit sa réponse. C’est la règle que suit une commande tapée dans un terminal, elle vaut donc pour chaque outil dont l’appel porte sur une Release ou un document d’entité qu’il nomme : un build, un pull, une validation, un lint, une description, une liste dans les termes d’une Release, une question sur un nœud du graphe d’une Release, un épinglage, la publication d’une entité, une modification et une position lue dans un document. Lorsqu’un appel nomme à la fois une Release et un document, c’est la Release qui décide. Ainsi, pour un client qui a lancé le serveur hors de votre projet, une Release de ce projet est tout de même construite à partir de la configuration propre du projet. Les autres chemins que nomme l’appel sont lus comme toujours — un chemin relatif à partir du répertoire dans lequel le serveur a été démarré — et un outil qui exécute une commande dans un processus séparé reçoit sa réponse depuis le même workspace, car la commande suit la même règle dans ce même répertoire. Une racine que le lancement a nommée, un workspace_root que l’appel envoie, un répertoire de départ qui se trouve lui-même dans un workspace, et une Release ou un document nommé par un chemin relatif sont utilisés tels quels. Sur HTTP, rien de tout cela ne se pose : un listener sert toujours un workspace qui lui a été donné ou qu’il a trouvé, et chaque chemin que nomme un appel est relatif à celui-ci. Il en va de même pour le lancement du bundle de bureau avec un paramètre Workspace folder vide, qui refuse un appel ne nommant aucun workspace propre, quel que soit le fichier qu’il nomme.
Restreindre ce que le serveur annonce
mcp.announce_tools nomme les outils que ce serveur annonce, écrits exactement comme la liste des outils les rapporte. Omettez la clé et chaque outil que porte ce serveur est annoncé, ce qui est le comportement par défaut et la forme qu’attend un client qui suit le protocole. Écrivez une liste et exactement ces outils sont annoncés : un outil omis est absent de la liste des outils, absent de ce que répond describe-capabilities, et refusé s’il est tout de même appelé par son nom, le refus nommant ce paramètre. Écrivez une liste vide et rien n’est annoncé du tout — omettre la clé et écrire [] sont donc deux énoncés différents, et le paramètre n’a aucune valeur par défaut renseignée à votre place.
Définissez-le là où le client à l’autre bout plafonne le nombre d’outils qu’il enregistrera, parfois sur l’ensemble des serveurs auxquels il est connecté à la fois, et nommez les outils dont ce client a besoin. Ce plafond est le cas pour lequel le paramètre existe, et le client auquel il s’applique est généralement celui qui a lancé ce serveur sur sa propre entrée et sortie standard — ainsi, contrairement au reste du bloc mcp, qui configure le listener que démarre le transport http, cette clé est lue quel que soit le transport parlé par le serveur.
Il restreint ce qui est annoncé et rien de plus. Nommer un outil ici n’élargit rien. Cela ne lève pas mcp.deny_reach, qui retire purement et simplement une capacité, de sorte qu’un outil nommé ici d’un type que ce paramètre retire reste hors de la liste et est refusé en nommant ce paramètre. Cela ne lève pas non plus les scopes que porte le jeton d’un appelant : un outil nommé ici est listé quels que soient ces scopes, et un appel qu’ils n’admettent pas est tout de même refusé, en nommant le scope qui l’admettrait. Dans les deux cas, le refus que rencontre l’appelant est celui de cette autre limite plutôt que de celle-ci. Un refus dû à ce paramètre ne porte aucun challenge et ne nomme aucun scope, car aucun identifiant ne change ce qu’un serveur a choisi d’offrir — ce qu’il nomme à la place est le paramètre, seule chose sur laquelle quiconque lit le refus peut agir.
Chaque nom doit être l’un de ceux que porte ce binaire. Un nom auquel aucun outil ne répond arrête le serveur avant qu’il ne serve quoi que ce soit, et le refus liste les outils dont il dispose — ainsi une faute de frappe est détectée au démarrage plutôt que par une surface silencieusement plus étroite que celle demandée. Un nom de la famille cli-, qui exécute une commande aggrega dans un processus séparé, est accepté sur les deux transports et n’annonce rien sur HTTP, où aucun outil de ce type n’est de toute façon proposé à aucun appelant.
L’ensemble annoncé est fixé au démarrage du processus, de sorte que le modifier nécessite un redémarrage et que rien ne fait grandir la liste sous un client déjà connecté.
De quelle version provient le serveur
describe-capabilities envoyé sans argument indique de quelle version provient ce serveur. Sa réponse structurée porte server_version, la version que l’exécutable aggrega rapporte pour lui-même — celle que aggrega version affiche pour le même fichier — et son texte s’ouvre sur une ligne qui la nomme, avant l’index. La réponse structurée porte cette même ligne sous la forme version_summary, mot pour mot, de sorte qu’un client qui ne transmet à un modèle que la réponse structurée lui transmet aussi la ligne.
Là où le bundle de bureau a lancé le serveur, la même réponse nomme à côté la version du bundle. Le bundle ne contient aucun programme : il lance l’exécutable aggrega que nomme son paramètre Path to the aggrega executable — par défaut le nom de commande aggrega, que l’application recherche dans son PATH —, de sorte que le bundle et l’exécutable sont installés séparément et peuvent provenir de versions différentes, et l’application qui liste le bundle n’affiche que la version propre du bundle. Le bundle transmet sa version au serveur sous la forme AGGREGA_BUNDLE_VERSION dans son environnement ; le serveur la lit une fois, au démarrage, et la réponse la porte sous la forme bundle_version. Les deux sont comparées exactement telles qu’elles sont écrites, ce qui est une comparaison juste, car le bundle et l’exécutable d’une même version sont estampillés de la version de celle-ci sous la même forme, tandis qu’un build de développement se lit différemment de toute version publiée. Lorsqu’elles sont égales, la ligne nomme les deux et n’en dit pas plus. Lorsqu’elles diffèrent, la ligne indique, en nommant les deux, que l’exécutable et le bundle proviennent de versions différentes, et les indications que le serveur donne à un modèle lorsqu’il se connecte s’ouvrent sur cette même phrase, de sorte que la différence est sous les yeux du modèle avant qu’il ne pose la question.
Un serveur qu’aucun bundle n’a lancé ne rapporte que sa propre version. Démarré depuis un terminal, depuis la configuration d’un éditeur ou en tant que listener, il ne porte aucun bundle_version, à moins que quelque chose ne définisse la variable dans son environnement. Un serveur sur l’entrée et la sortie standard qui porte la variable est considéré comme lancé par le bundle à un égard de plus : si aucune racine ne lui est nommée, il refuse le paramètre Workspace folder vide, comme l’expose Dans quel workspace un appel reçoit sa réponse. Un appel à describe-capabilities envoyé avec kind ou tools ne porte ni server_version, ni bundle_version, ni version_summary, ni une telle ligne, car il répond sur des outils plutôt que sur le serveur.
Une différence est signalée et jamais refusée. Le serveur démarre et répond à chaque appel exactement comme il le ferait avec les deux alignées. Ce qu’une différence signifie pour une installation de bureau, et comment réaligner les deux, se trouve dans Connecter le serveur MCP.
Atteindre le serveur en HTTPS
aggrega mcp --transport http sert le protocole en HTTP plutôt que sur l’entrée et la sortie standard. mcp.transport dans la configuration du workspace est la clé que ce flag remplace, et sa valeur par défaut, stdio, est ce qu’attend un client qui lance la commande — ainsi un serveur que d’autres personnes atteignent porte transport: http dans sa configuration, et un client lancé depuis un répertoire que couvre cette configuration atteint tout de même le serveur sur ses propres flux. C’est le même serveur dans les deux cas — le même workspace et les mêmes surfaces de protocole — et ce qui change, c’est la manière dont un message l’atteint, la manière dont un appel se termine et ce que doit détenir la personne qui l’exploite. Cette section décrit ce qu’un opérateur configure ; l’entrée dont un client a besoin pour atteindre un serveur en cours d’exécution se trouve dans Connecter le serveur MCP.
Une adresse ne choisit aucun transport. --listen <address>, ou mcp.listen en l’absence du flag, nomme l’endroit où le listener se lie une fois http choisi, et rien de plus. Ainsi http sans adresse provenant de l’un ou de l’autre est refusé avant toute liaison, et le refus nomme les deux. --listen saisi alors que le transport est stdio — saisi sous la forme --transport stdio, configuré sous la forme mcp.transport: stdio ou laissé par défaut — est refusé également, en nommant --transport http comme le flag qui servirait sur cette adresse ; un --listen reçu avec une valeur vide est refusé comme ne nommant aucune adresse, quel que soit le transport. Et une adresse que seule la configuration nomme reste inutilisée par un serveur qui parle sur ses propres flux, lequel le signale par une ligne sur son flux d’erreur, en nommant le fichier qui l’a définie et mcp.transport: http. Ce dernier cas n’est refusé nulle part, à dessein : c’est le lancement qu’effectue un client lorsqu’il démarre la commande dans un répertoire dont la configuration porte les paramètres d’un listener, et une configuration de listener qui oublie transport: http ne démarre aucun listener, et c’est là que cela se voit.
Un serveur atteint en HTTP ne propose aucun outil qui exécute une commande aggrega dans un processus séparé. Ces outils n’existent que pour un client qui a lancé ce serveur sur son entrée et sa sortie standard, sur la propre machine de ce client, où nommer un dossier ou un flag n’accorde à l’appelant rien qu’il n’avait déjà. Un appelant qui atteint le serveur en HTTP ne possède pas l’hôte sur lequel celui-ci tourne, de sorte qu’une commande qui agirait sur le système de fichiers de cet hôte avec l’autorité propre du serveur est plutôt exécutée dans un terminal sur l’hôte. Les outils sont absents de la liste et de describe-capabilities plutôt que d’être proposés puis refusés, et un appel qui en nomme un reçoit une erreur qui le dit. C’est une propriété du transport, pas un paramètre : aucune configuration ne les rétablit.
Lisez Rien n’est servi sans identifiant avant d’en déployer un. Chaque requête vers l’endpoint porte un identifiant, et aucun paramètre ne sert une requête qui n’en a pas — ce qu’un paramètre choisit, c’est si ce serveur vérifie lui-même un jeton bearer ou lit un appelant qu’un proxy placé devant a déjà vérifié.
Les deux formes de déploiement
Le processus termine TLS lui-même. Définissez mcp.tls.cert_file sur une chaîne de certificats PEM et mcp.tls.key_file sur sa clé privée, et le listener sert HTTPS directement sur l’adresse que vous lui avez donnée. Les deux fichiers sont lus au démarrage du processus, de sorte qu’un certificat remplacé est pris en compte en redémarrant le processus. Définir l’un sans l’autre est refusé au démarrage plutôt que de se rabattre sur autre chose : un certificat sans clé ne peut pas être présenté, une clé sans certificat ne nomme rien, et une faute de frappe dans un chemin n’est pas une raison pour commencer à servir du trafic non chiffré.
Un proxy placé devant termine TLS et transmet à un listener confiné. Laissez les deux clés non définies et le listener sert en clair, ce qui n’est accepté que sur loopback ou sur un socket Unix — de sorte que rien qui ne soit déjà sur cet hôte ne peut l’atteindre. C’est la forme qu’utilise un reverse proxy, un sidecar ou un service mesh, et c’est celle où le certificat se trouve devant ce processus plutôt qu’en lui.
Un listener en clair sur toute autre adresse est refusé avant toute liaison, et le refus nomme les deux clés TLS. Aucun paramètre ne lève cette restriction et aucune adresse ne fait exception : un listener qui accepte des connexions depuis le réseau sans certificat propre n’est jamais sûr, de sorte que le processus refuse de démarrer plutôt que de démarrer sous cette forme.
Les formes d’adresse
--listen et mcp.listen prennent l’une de deux formes :
host:port— une adresse TCP, telle que127.0.0.1:7777ou0.0.0.0:8443. Loopback signifie127.0.0.1,::1, oulocalhostlorsque chaque adresse vers laquelle ce nom se résout est une adresse de loopback. Tout le reste est une adresse réseau et nécessite un certificat : un hôte vide, qui correspond à toutes les interfaces de la machine ; l’adresse d’une interface précise ; et tout autre nom, même un nom qui se résout à cet instant vers une adresse de loopback, car l’endroit où un listener peut se lier ne devrait pas dépendre d’une résolution susceptible de changer sous lui.unix:suivi d’un chemin du système de fichiers — un socket de domaine Unix, tel queunix:/run/aggrega/mcp.sock. Un socket n’est joignable que depuis l’hôte sur lequel il se trouve, de sorte qu’il ne nécessite aucun certificat.
Un chemin de socket est pris exactement tel qu’il est écrit, y compris un chemin relatif. Il n’est délibérément pas résolu par rapport au fichier de configuration qui l’a déclaré, car la même adresse arrive aussi de --listen, qui n’a pas de fichier déclarant — voir où pointe un chemin relatif.
Ce que le listener accepte
Un seul endpoint, /mcp, qui accepte POST. Chaque message JSON-RPC est sa propre requête et aucune session d’aucune sorte n’est conservée : rien de ce qu’un client envoie en premier ne décide de la réponse à une requête ultérieure, aucun identifiant de session n’est jamais émis, et un en-tête de session ou de reprise de flux qu’un client envoie est ignoré. Toute autre méthode sur cet endpoint reçoit 405 avec Allow: POST, et tout autre chemin 404 — les deux étant tranchés avant la vérification de l’identifiant, de sorte qu’un sondage n’apprend rien d’un challenge sur un chemin ou une méthode qui ne servirait rien de toute façon.
Une requête reçoit en réponse un objet JSON et un code de statut — ou, lorsque l’appel a signalé sa progression en chemin vers cet objet, un flux d’événements qui se termine par celui-ci, comme l’expose Être informé de l’avancement d’un appel long. Une notification — un message sans id — reçoit 202 avec un corps vide. Un message qui n’est ni l’un ni l’autre, y compris une réponse JSON-RPC, reçoit 400, car un client envoie à ce serveur des requêtes et des notifications et rien d’autre.
Les deux révisions du protocole sont servies ici exactement comme sur l’entrée et la sortie standard. Une requête 2026-07-28 reflète son corps dans des en-têtes de transport afin qu’un intermédiaire puisse la router sans analyser le corps : MCP-Protocol-Version porte la révision que déclare le corps, Mcp-Method la méthode qu’il nomme, et Mcp-Name la cible, pour les méthodes qui en adressent une par son nom. Un en-tête en désaccord avec le corps reçoit 400. Un client 2025-06-18 commence par un handshake initialize, auquel il est répondu sans état ; il peut porter l’en-tête de version nommant cette révision ou l’omettre. Une requête nommant une révision que le serveur ne parle pas reçoit 400 en listant les deux qu’il parle, et une requête nommant une méthode qu’il ne sert pas reçoit 404.
mcp.allowed_origins n’est consulté que lorsqu’une requête porte un en-tête Origin, ce qui signifie en pratique qu’un navigateur l’a envoyée : une requête nommant une origine que la liste ne contient pas reçoit 403, et une requête sans cet en-tête est servie. Un client qui n’est pas un navigateur n’envoie pas cet en-tête et n’a besoin d’aucune entrée. Un client basé sur un navigateur a toujours besoin d’une entrée : la liste est vide jusqu’à ce qu’un opérateur l’écrive, de sorte que jusque-là aucune origine n’y figure et chaque requête de navigateur reçoit 403 — y compris une requête provenant d’une page servie à l’adresse même de l’endpoint. L’entrée est comparée exactement à l’en-tête, elle s’écrit donc comme un navigateur envoie une origine — un schéma en minuscules, ://, un hôte en minuscules et, lorsqu’il ne s’agit pas de celui par défaut du schéma, : et le port, comme https://app.example.com — et une entrée avec un chemin, un / final, sans schéma ou avec une majuscule est refusée au chargement de la configuration, en nommant l’entrée, car elle ne pourrait jamais correspondre.
mcp.limits borne le trafic accepté. Un corps dépassant max_body_bytes reçoit 413 et n’est pas lu au-delà du plafond. Une requête qui arrive alors que max_concurrent_requests sont déjà en cours reçoit 503 plutôt que d’être mise en file derrière un travail qu’elle ne peut pas voir. Un appelant qui envoie plus de requests_per_minute en une minute reçoit 429, compté pour cet appelant seul, de sorte qu’un appelant qui envoie beaucoup ne coûte rien à un autre. La valeur par défaut de chaque plafond est indiquée à côté de sa clé dans la référence de configuration, et aucun d’eux n’a de valeur qui le désactive.
Un processus, un workspace
Le workspace pour lequel répond un processus de service est fixé à son démarrage. --workspace-root le nomme ; la variable AGGREGA_WORKSPACE_ROOT le fournit en l’absence du flag. Le dossier nommé est la racine même du workspace, sans recherche au-dessus, et un dossier qui n’existe pas est refusé, en nommant celui des deux qui l’a fourni et en citant la valeur telle qu’elle a été donnée — par un listener avant sa liaison, et par un serveur sur l’entrée et la sortie standard dans sa réponse à chaque appel qui agit dans ce workspace, comme l’expose Dans quel workspace un appel reçoit sa réponse — de sorte qu’un lancement composé par un client plutôt que saisi indique tout de même ce qui lui a été transmis. Sans l’un ni l’autre, un serveur sur l’entrée et la sortie standard résout le workspace à partir du répertoire dans lequel il a été démarré — là où rien n’y ancre de workspace, chaque réponse qui concerne le workspace indique quel dossier elle a utilisé, et le lancement du bundle de bureau avec un paramètre Workspace folder vide refuse plutôt un appel qui ne nomme aucun workspace propre, comme l’expose Dans quel workspace un appel reçoit sa réponse — et un listener est refusé avant sa liaison à moins qu’un workspace ne s’y résolve — un processus atteint en HTTP répond à des appelants qui ne peuvent pas voir la machine, de sorte qu’il sert un workspace choisi par un opérateur plutôt que le répertoire dans lequel il s’est trouvé démarré. Servez plusieurs projets en exécutant un processus par racine de projet.
Un appel arrivant en HTTP ne peut pas nommer de workspace propre. workspace_root et catalog_dirs sont refusés, en nommant l’argument envoyé, plutôt que d’être silencieusement abandonnés : un argument ignoré en silence apparaît à son expéditeur exactement comme un argument respecté. Les répertoires de catalogue parcourus à côté du workspace servi sont ceux du paramètre workspace.catalog_dirs propre à ce workspace — ou, pour une Release à laquelle il donne ses propres répertoires sous workspace.releases, ceux de cette Release — que l’opérateur écrit. Sur l’entrée et la sortie standard, les deux arguments sont respectés, car le client qui a lancé le serveur tourne sur la propre machine de l’appelant. Là, une entrée de catalog_dirs est absolue, ou relative à la racine du workspace depuis laquelle une release relative est lue — la racine qu’ont établie en premier le workspace_root propre à l’appel, le lancement ou le répertoire dans lequel le serveur a été démarré, et celle depuis laquelle la lecture continue là où une Release nommée de manière absolue déplace l’appel dans le workspace propre à cette Release — et non au répertoire dans lequel tourne le serveur, lorsque celui-ci se trouve ailleurs.
Un chemin que nomme un appel reste lui aussi à l’intérieur de ce workspace. En HTTP, un argument de chemin est résolu par rapport à la racine du workspace et refusé s’il en sort — un chemin relatif qui remonte hors du workspace, un chemin absolu qui nomme un autre endroit, et un chemin relatif qui sort du workspace par un lien vers un fichier ou un répertoire qui s’y trouve reviennent chacun comme un échec nommant l’argument, sans nommer ni la racine du workspace ni l’endroit que le chemin aurait atteint ; un chemin relatif est restitué tel que vous l’avez envoyé. Chaque argument de chemin est jugé selon l’endroit où il mène, d’après la définition de l’intérieur que donne La frontière du workspace, que l’outil le lise ou l’écrive — le répertoire dans lequel gen-catalog écrit sa sortie, le document que edit-document réécrit et l’entité à côté de laquelle pin écrit son verrou tout autant qu’un document qu’un outil lit — de sorte qu’un chemin pas encore créé sous un lien qui sort du workspace est refusé comme l’est ce lien, sans que rien ne soit lu ni écrit. Une release nommant une Release que nomme la configuration du workspace servi, en tant que build.authoring_release ou en tant que clé de workspace.releases, est atteinte par cette configuration et acceptée à travers un lien où que se trouve son fichier ; aucun autre argument n’a cette exception. Lorsque le chemin que vous visiez est à l’intérieur de ce workspace mais a été écrit de manière absolue, le refus vous donne l’écriture relative à la racine à envoyer à la place, de sorte qu’un appelant qui a deviné la mauvaise forme apprend la bonne plutôt que seulement qu’elle était mauvaise. Cela vaut pour les chemins qu’un appel nomme comme son objet — le document à valider, la Release à construire, le répertoire dans lequel une génération écrit sa sortie — et pour ceux dans lesquels un outil écrit, pas moins que pour ceux qu’il lit : un appelant qui atteint un serveur par le réseau demande à une machine qu’il ne peut pas voir de lire et d’écrire des fichiers, et le workspace choisi par l’opérateur est l’endroit où cette lecture et cette écriture sont contenues. Sur l’entrée et la sortie standard, les arguments de chemin de chaque outil conservent le contrat décrit plus bas pour cet outil, où un chemin peut être absolu et peut pointer hors du workspace — la personne qui appelle possède la machine sur laquelle tourne le serveur, de sorte que la confiner à un répertoire qu’elle a elle-même choisi n’apporterait rien. Les deux outils dont l’opération elle-même ne répond que sur un document que contient le workspace, insertion-point et edit-document, conservent ce comportement sur les deux transports, et refusent un document hors du workspace, qu’il soit écrit ainsi ou atteint par un lien qui en sort. Ce qui est respecté sur l’entrée et la sortie standard, c’est le chemin que nomme un appel et rien au-delà. Ce que l’opération lit et écrit ensuite pour son propre compte est contenu sur les deux transports exactement comme lorsque la même commande est saisie dans un terminal : un parcours ou une recherche ne lit pas à travers un lien qui sort du workspace, un fichier qu’une Release du workspace ou son Manifest nomme par un chemin n’est pas lu depuis l’extérieur du workspace — et un fichier que nomme une Release nommée par l’appel hors du workspace n’est pas lu depuis l’extérieur du répertoire qui contient cette Release — et un fichier écrit sous un répertoire — le workspace, ou un répertoire nommé par l’appel — reste à l’intérieur de ce répertoire. La frontière du workspace place les deux transports à côté de la ligne de commande et de l’éditeur, et indique ce qui reste ouvert sur l’entrée et la sortie standard : un document dans un workspace que vous avez cloné peut amener un assistant à nommer un chemin hors du workspace, et ce chemin est respecté tel qu’il est nommé.
Ce qu’une réponse dit du système de fichiers du serveur
En HTTP, une réponse nomme un emplacement du système de fichiers du serveur relativement à la racine du workspace, ou le retient. Un client qui a lancé le serveur tourne là où tourne le serveur, de sorte que sur l’entrée et la sortie standard chaque réponse nomme chaque emplacement tel que l’opération le détient — de manière absolue, si c’est ainsi qu’elle le détient — et chacun est un emplacement que cet appelant possède déjà. Un appelant qui atteint un listener n’a choisi aucun de ces emplacements et ne peut pas les ouvrir, et un serveur qui les lui a divulgués ne peut pas les reprendre. Ainsi, en HTTP, une réponse dit à cet appelant l’une de deux choses sur un emplacement :
- Un emplacement à l’intérieur du workspace est nommé relativement à la racine du workspace — la même forme que prend un chemin que vous envoyez, de sorte qu’un nom lu dans une réponse peut être renvoyé inchangé dans l’appel suivant. Une Release à la racine est
release.yaml, et son fichier de verrouillage estrelease.lock. - Un emplacement hors du workspace est retenu, tout comme la racine du workspace elle-même. Le champ ne porte aucune valeur — il vaut
nullou est omis, et surattachment-container, dont la réponse conserve la forme dans laquelle chaque surface la rapporte,fileest laissé vide — et une marque à côté, nommée d’après le champ avec_withheldajouté, indique qu’il a été retenu plutôt que non défini :workspace_root_withheldà côté deworkspace_root,file_withheldà côté defile. Une marque n’est présente que là où quelque chose a été retenu. La racine est retenue parce qu’un listener sert exactement un workspace, de sorte que l’endroit où se trouve ce workspace ne nomme rien dont vous avez besoin pour nommer ce qu’il contient.
Qu’un emplacement soit à l’intérieur se juge à la manière dont il est écrit, et non au fichier qu’il atteint. Un chemin écrit via la cible d’un lien symbolique plutôt que via la racine sur laquelle le serveur a été démarré, et un chemin qui sort de la racine puis y revient, sont chacun considérés comme hors du workspace et sont retenus. Le jugement penche vers moins d’information, jamais vers la mention d’un emplacement hors du workspace.
En HTTP, le texte lisible d’une réponse suit la même règle. Lorsque le texte, une ligne de diagnostic ou le message d’un échec nomme un emplacement que contient le workspace — sa racine ou tout ce qui se trouve dessous, un fichier de configuration depuis lequel sa configuration a été lue, un répertoire depuis lequel son catalogue est lu — cet emplacement est écrit relativement à la racine, ou se lit (location withheld) lorsqu’il se trouve hors du workspace ou qu’il est la racine. Le texte qu’une réponse compose sur son propre workspace l’appelle le workspace que sert ce serveur. Un emplacement en dehors de tous ceux-ci qu’une opération écrit dans un message n’est pas reconnu comme tel, et vous parvient tel qu’il a été écrit.
Les réponses concernées, en HTTP :
list-entities,list-releases,cache-status,registry-list,search,attach-candidates,connection-candidates,insertion-point,attachment-container,connection-at-positionetedit-documentretiennentworkspace_root. Les chemins qu’ils donnent déjà relativement à la racine — le fichier source d’une entité, le chemin d’une Release et son fichier de verrouillage souslockfiles, le document que concerne un point d’insertion ou une modification, les fichiers qu’une modification a écrits — se lisent de la même façon sur les deux transports.cache-statusretient aussi ce qui nomme un plugin que le serveur a chargé depuis un fichier sur son hôte. Une telle identité vautnullà sa place dansprovenance[].identities, chaque autre identité conserve sa position, et l’entrée est marquéeidentities_withheld. Lanoted’un module compilé est une phrase nommant les identités pour lesquelles le module a été construit, de sorte que lorsque l’une d’elles nomme un tel fichier, lanoteest entièrement omise et marquéenote_withheld; ledigestdu module reste présent. Une identité nommant une référence de registre ou une entité Plugin reçoit une réponse complète, tout comme unenotene nommant que celles-ci. Lelabeld’un artefact source est son emplacement dans le cache, formé à partir de l’hôte et du chemin de l’URL depuis laquelle il a été résolu, de sorte que pour un dépôt lu depuis le propre système de fichiers du serveur — via une URLfile://ou un chemin — lelabelest omis et marquélabel_withheld, sasizeet sondigestrestent présents, et unlabelnommant un hôte réseau reçoit une réponse complète. Le texte de la liste affiche(location withheld)là où il en aurait nommé un.validatenommetarget, etreleasepour une Release, relativement à la racine ; pour l’ensemble du catalogue,targetest la racine et est retenu. Un emplacement dansdiagnosticsounoticessuit la règle applicable au texte.buildnommereleaserelativement à la racine, et un build qui a d’abord résolu ses dépendances portedependency_resolutiontel quepullle répond. Un build envoyé avecwritenomme le répertoire dans lequel il a écrit sous la formeoutput_dir, qui vautdist— relativement à la racine — et chaque chemin dansfilesest relatif à ce répertoire. Unrefusal, et chaque entrée de sesfindings, nomme sonfilerelativement à la racine, ou le retient lorsque le document se trouve hors du workspace.advisories,deprecations,declined_external_inputset chaquemessagedurefusalsuivent la règle applicable au texte.pullnommereleaseetlockfilerelativement à la racine.diagnosticsetincomplete_external_inputssuivent la règle applicable au texte. Lasourcede chaque entrée deresolvedreçoit une réponse complète sur les deux transports : elle nomme ce que l’exécution a fait, jamais un emplacement sur l’hôte.describenomme lareleased’une Release relativement à la racine, et lefiled’une entité relativement à la racine lorsque son document se trouve à l’intérieur du workspace ; une entité lue depuis un répertoire de catalogue hors du workspace voit sonfileretenu.mapping_diagnosticsetdeprecationssuivent la règle applicable au texte.lintnomme lelocation.filede chaque constat relativement à la racine, ou le retient lorsque l’entité se trouve hors du workspace. Lemessageet lesuggestd’un constat suivent la règle applicable au texte.pinnommeentityetlockrelativement à la racine, tout comme lepinque porte une publication.gen-catalognomme chaque fichier listé dansoutputrelativement à la racine.importretientworkspace_root, ainsi queoutput_dirlorsque les brouillons sont allés dans cette racine ; un répertoire que vous avez nommé dansoutput_direst indiqué par son nom relatif à la racine. Chaque chemin de brouillon danswrittenetdraftsest relatif àoutput_dir, de sorte que l’endroit où sont allés les brouillons figure dans la réponse dans tous les cas. Lemessaged’un diagnostic, ainsi que lesparams_summary,rationaleetswap_hintd’une décision, sont de la prose composée par l’importateur et suivent la règle applicable au texte.config-showetplugin-listretiennent davantage que la racine, car l’essentiel de ce qu’ils rapportent est de la configuration qui nomme des emplacements, comme l’expose Ce qu’un listener ne vous dit pas de son hôte.scaffold, lorsqu’il écrit un exemple, nommedirtel que vous l’avez envoyé, relativement à la racine, et chaque chemin defilesrelativement à ce répertoire ; la rédaction d’un brouillon et le listage ne nomment aucun emplacement.- Les outils de publication,
sign-artifacts,deprecate-artifact,get-schema,explain-erroretdescribe-capabilitiesne nomment d’eux-mêmes aucun emplacement sur l’hôte. Le message d’échec de chacun d’eux suit la règle applicable au texte : le refus que lève un workspace hors ligne nomme son.aggrega-config.yamlrelativement à la racine. - Un argument de chemin refusé parce qu’il sort du workspace est refusé sans nommer la racine ni l’endroit qu’il aurait atteint, comme ci-dessus.
Comment un appel se termine
Fermer la connexion annule l’appel qu’elle portait. C’est le signal d’annulation de ce transport : le serveur traite la déconnexion d’un appelant comme l’annulation de cette requête, met fin au travail qu’il effectuait et n’écrit plus rien pour elle. Aucun message d’annulation n’est nécessaire ni attendu ici — à l’opposé de l’entrée et de la sortie standard, où il n’y a pas de flux par requête à fermer et où un client met fin à un appel en nommant plutôt son id. Un message d’annulation qui arrive malgré tout en HTTP est accepté et ne met fin à rien.
Arrêter le processus draine le listener. Une interruption, ou une demande d’arrêt d’un superviseur ou d’un runtime de conteneurs, fait cesser au listener d’accepter et laisse un appel déjà en cours de réponse se terminer, dans un délai borné, de sorte qu’un appelant qui a demandé quelque chose avant l’arrêt reçoit tout de même sa réponse. Un appel qui ne s’est pas terminé dans ce délai perd sa connexion. Une seconde demande d’arrêt met fin au processus immédiatement.
Liveness et readiness, sur une adresse dédiée
mcp.health.listen est l’endroit où un superviseur demande si ce processus est actif et s’il peut répondre à un appel. Donnez-lui une adresse sous l’une des formes ci-dessus et un second listener y répond à GET /healthz et GET /readyz. Omettez-le — c’est le comportement par défaut — et aucun second listener n’est démarré et aucune des deux vérifications ne reçoit de réponse nulle part.
Les deux réponses disent des choses différentes, et cette différence est la raison pour laquelle il y en a deux. /healthz reçoit 200 dès que le processus est en cours d’exécution, ce qui est tout ce qu’affirme la liveness : il est actif, et un superviseur qui ne reçoit aucune réponse devrait le redémarrer. /readyz reçoit 503 jusqu’à ce que le workspace que sert ce processus soit résolu et que l’endpoint soit lié, puis 200 à partir de ce moment — de sorte qu’un répartiteur de charge retient le trafic jusqu’à ce que le processus puisse réellement répondre à un appel, plutôt que d’envoyer la première requête à un processus encore en train de démarrer. Chaque réponse est un code de statut avec un corps vide ; aucun identifiant n’est demandé, et rien de ce que l’appelant a envoyé n’est lu.
L’endpoint ne répond jamais à ces deux chemins. GET /healthz et GET /readyz sur l’adresse que nomme mcp.listen reçoivent 404, exactement comme tout autre chemin que cet endpoint ne sert pas, avec un jeton comme sans. Répondre là à une sonde donnerait à tout ce qui atteint l’endpoint une lecture gratuite de l’état du processus, ainsi qu’un moyen gratuit de le faire travailler — sur un listener qui refuse par ailleurs toute requête ne portant aucun identifiant.
L’emplacement de l’adresse de santé est à votre choix, et elle n’est pas confinée comme l’est mcp.listen. Aucune adresse n’est refusée pour elle. Pointez-la vers loopback ou vers un socket Unix, ce pour quoi elle est faite : un superviseur, un répartiteur de charge ou un runtime de conteneurs tournant à côté de ce processus sur le même hôte. Tout ce qui peut atteindre l’adresse que vous choisissez peut lire ces deux réponses, de sorte qu’une adresse que le réseau ouvert atteint les publie sur le réseau ouvert.
Rien n’est servi sans identifiant
Chaque requête vers l’endpoint porte un identifiant, et lequel dépend de ce qu’un proxy placé devant l’a déjà vérifié ou non. Par défaut, il s’agit d’un jeton bearer que ce serveur vérifie lui-même, décrit dans le reste de cette section. Définissez mcp.authorization.trusted_proxy et il s’agit plutôt d’un en-tête que définit ce proxy, décrit sous Lire l’appelant depuis un proxy placé devant — où aucun jeton n’est lu du tout. Aucune des deux formes ne sert une requête qui ne présente rien.
Par défaut, le serveur vérifie lui-même un jeton bearer. Il lit le jeton dans l’en-tête Authorization et ne l’accepte que si la signature se vérifie avec une clé que publie le serveur d’autorisation, si le jeton nomme mcp.authorization.issuer comme émetteur, s’il nomme le mcp.authorization.resource propre à ce déploiement parmi ses audiences, s’il se trouve dans sa fenêtre de validité et s’il indique qui l’a présenté. Un jeton qui échoue à l’une de ces vérifications reçoit 401, avec error="invalid_token" ajouté au même challenge que reçoit un appelant qui ne porte rien — et la réponse est identique quelle que soit la vérification qui l’a rejeté, de sorte qu’un appelant apprend qu’il lui faut un autre jeton plutôt que quelle partie de celui qu’il a envoyé était erronée. Seuls les algorithmes de signature asymétriques sont acceptés : un jeton non signé, et un jeton nommant un algorithme symétrique, sont refusés avant que quoi que ce soit n’en soit lu.
Un jeton peut indiquer de quel type de jeton il s’agit, et quatre formes sont acceptées. Un JWT peut porter un en-tête typ nommant son propre type. Ce serveur accepte at+jwt et application/at+jwt, les deux graphies enregistrées pour un jeton d’accès ; JWT, qui indique seulement que le jeton est un JWT ; et un jeton qui ne déclare aucun type. Tout le reste reçoit 401 exactement comme tout autre jeton refusé. L’ensemble est fixe et aucun paramètre ne l’élargit ni ne le restreint, car la forme qui y apparaît est décidée par le serveur d’autorisation qui a émis le jeton plutôt que par le déploiement qui le reçoit. Accepter JWT signifie certes que le type déclaré seul ne distingue plus un jeton d’accès d’un jeton d’identité — c’est la vérification de l’audience qui les distingue, et c’est pourquoi cette vérification est celle qui porte la charge : l’audience d’un jeton d’identité est le client auquel il a été émis, jamais le mcp.authorization.resource propre à ce déploiement, de sorte qu’un jeton émis pour autre chose que ce déploiement est refusé quel que soit le nom qu’il se donne.
Quels serveurs d’autorisation cela admet. Microsoft Entra ID émet des jetons d’accès de type JWT. Keycloak émet at+jwt, et JWT lorsque son mode de compatibilité OpenID Connect est activé. Auth0 émet JWT sous son propre profil de jeton et at+jwt sous son profil RFC 9068. Un jeton de l’un quelconque d’entre eux satisfait cette vérification, quelle que soit celle des deux formes qu’il porte. Okta n’est pas pris en charge : ses jetons d’accès déclarent un type qui leur est propre et qui n’est aucune des quatre formes ci-dessus, de sorte que ce serveur les refuse.
Un jeton refusé laisse la raison sur le flux d’erreur propre au serveur. L’appelant apprend seulement que ce qu’il a présenté n’a pas été accepté ; le processus de service écrit une ligne nommant la vérification qui a rejeté le jeton — l’audience, l’émetteur, la fenêtre de validité, la signature, l’identifiant de clé, le type déclaré, et chacune des autres. Cette ligne est ce qui permet à la personne qui exploite un déploiement refusant toutes les requêtes de le diagnostiquer, et pas seulement à celle qui l’appelle. Elle ne contient aucune partie du jeton. Une requête ne présentant aucun identifiant n’écrit aucune ligne, car recevoir un challenge est la manière dont un client découvre où obtenir un jeton en premier lieu ; c’est donc la première chose que fait tout client bien conçu.
Un jeton a sa place dans l’en-tête et nulle part ailleurs. Un jeton envoyé comme paramètre de requête access_token reçoit 400 et n’est jamais lu, car une adresse est enregistrée par chaque journal de proxy, chaque historique de navigateur et chaque en-tête referrer que traverse la requête, de sorte qu’un jeton arrivé ainsi a déjà été exposé. Le serveur n’écrit jamais un jeton dans un journal, n’en envoie jamais nulle part, et n’en obtient ni n’en échange jamais au nom d’un appelant : il lit ce qui a été présenté, décide, et n’en conserve rien. Le sujet que nomme le jeton est enregistré et comparé à rien.
Les clés de vérification proviennent du serveur d’autorisation, ou d’un fichier que vous nommez. Lorsque mcp.authorization.jwks_file n’est pas défini, le serveur lit les métadonnées du serveur d’autorisation à son adresse well-known, suit le jwks_uri qui y est publié et conserve les clés qu’il y trouve ; un jeton signé avec un identifiant de clé que ces clés ne contiennent pas provoque une relecture, et pas plus d’une dans un court intervalle, de sorte qu’un appelant envoyant des identifiants de clé inventés ne peut pas provoquer une requête sortante par requête. Les lire depuis le serveur d’autorisation nécessite une adresse de clés https, ou une adresse http en clair sur cette machine : un jwks_uri en clair http sur un autre hôte n’est jamais interrogé, et une redirection qui enverrait l’une ou l’autre lecture vers du http en clair sur un autre hôte n’est pas suivie, car quiconque se trouve sur un chemin non protégé vers les clés pourrait répondre avec ses propres clés. Un jeton nécessitant ces clés reçoit alors 503, exactement comme pour des clés illisibles, et la ligne que le serveur écrit pour cette requête indique que la lecture a été refusée pour cause de http en clair, et non que le serveur d’autorisation était injoignable — la correction relève du serveur d’autorisation, qui doit publier ses métadonnées et ses clés en https. Lorsque jwks_file est défini, les clés sont lues depuis ce fichier et le serveur d’autorisation n’est jamais contacté — ce dont a besoin un workspace déclarant offline: true, et un tel workspace est refusé avant la liaison de son listener à moins que le fichier ne soit nommé. Lorsque les clés ne peuvent pas être lues du tout, les requêtes reçoivent 503 sans challenge : rien de ce qu’un appelant a présenté n’a été jugé insuffisant, de sorte que le renvoyer avec un autre jeton n’aiderait pas.
La seule réponse donnée sans qu’aucune information d’identification soit demandée est le document de métadonnées de la ressource protégée. Un client doit le lire avant de pouvoir détenir un jeton, donc en exiger un à cet endroit fermerait la seule porte d’entrée. Il est servi à /.well-known/oauth-protected-resource et — lorsque l’adresse que nomme mcp.authorization.resource possède un chemin propre — également à ce chemin well-known suivi de ce chemin. Ce sont les deux endroits où un client regarde, et la forme avec le chemin ajouté est l’adresse que nomme la challenge. Le document indique cette adresse comme la ressource sous laquelle ce déploiement est appelé, mcp.authorization.issuer comme le serveur d’autorisation auprès duquel obtenir un jeton, header comme seule manière de présenter un jeton, et les trois noms de scope ci-dessous.
L’issuer est une adresse https, sauf si le serveur d’autorisation s’exécute sur cette machine. Le http simple est accepté pour un issuer sur localhost, 127.0.0.1 ou ::1, ce qui correspond à un test local avec un serveur d’autorisation local ; un issuer en http simple sur tout autre hôte est refusé avant que le listener ne se lie, et le refus nomme mcp.authorization.issuer et demande une adresse https. Cela vaut dans tous les modes — avec les clés lues depuis l’issuer, avec mcp.authorization.jwks_file et avec un proxy en amont — parce que chaque mode publie l’issuer dans ce document : un client qui le suit exécute son flux d’autorisation auprès de cette adresse, donc en http simple le code d’autorisation et le jeton qu’il obtient traverseraient le réseau sans protection, que ce serveur y lise un jour une clé ou non. Lorsqu’il y lit effectivement ses clés, quiconque se trouve sur ce chemin pourrait aussi répondre avec ses propres clés, et tout jeton signé avec elles serait admis.
Les noms de scope que ce déploiement publie sont aggrega:read, aggrega:workspace-write et aggrega:registry-write. Ce sont les noms à enregistrer auprès du serveur d’autorisation et les noms qu’un client lui demande, et la challenge que reçoit un appelant refusé nomme aggrega:read comme celui à obtenir en premier. Ce que chacun d’eux admet — ainsi que la seconde limite, celle que ce déploiement s’impose à lui-même — est décrit plus bas sous Ce qu’un appelant peut atteindre.
Lire l’appelant depuis un proxy en amont
Lorsqu’un proxy en amont valide déjà les jetons, mcp.authorization.trusted_proxy indique à ce serveur de lire l’appelant depuis ce proxy au lieu de vérifier un jeton une seconde fois. Indiquez principal_header, l’en-tête que ce proxy définit pour dire qui est l’appelant, et éventuellement scopes_header, un second en-tête qui porte les scopes de cet appelant séparés par des espaces. Chacun est un nom d’en-tête HTTP tel que X-Forwarded-User, sans espace ni deux-points ; un nom de toute autre forme est refusé au chargement de la configuration, en nommant la clé, de même qu’un principal_header vide — omettez le bloc pour laisser ce mode désactivé. Ces deux en-têtes sont les seuls lus : aucun en-tête d’adresse transférée ni aucun autre en-tête n’intervient. Une requête arrivant sans l’en-tête du principal reçoit 401, et aucun jeton n’est lu dans ce mode — une requête portant un jeton que ce serveur aurait autrement refusé est servie lorsque son en-tête du principal est présent, et une requête portant un jeton que ce serveur aurait accepté est tout de même refusée lorsque cet en-tête est absent.
Ce mode n’est accepté que sur loopback ou sur un socket Unix, et le processus est refusé avant de se lier ailleurs. Un en-tête est digne de confiance exactement lorsque rien d’autre que le proxy ne peut le définir. Sur une adresse que le réseau atteint, n’importe quoi peut le définir — un listener dans ce mode sur une telle adresse permettrait donc à chaque appelant de se nommer comme il l’entend. Le refus nomme les deux paramètres en conflit, de sorte que vous pouvez le lever en déplaçant l’adresse ou en supprimant le bloc.
Ce que le proxy affirme est ce que ce serveur croit, et c’est là le marché. Dans ce mode, ce serveur ne vérifie aucune signature et ne compare l’appelant affirmé à rien, exactement comme il ne compare à rien le subject d’un jeton. Que le proxy ait validé ce qu’il a transmis, et que quoi que ce soit puisse atteindre ce listener sans passer par le proxy, c’est au déploiement de le faire correctement ; le confinement ci-dessus est ce qui permet de le faire correctement, et non une garantie que cela a été fait.
Définir mcp.authorization.trusted_proxy ne supprime pas les autres exigences. issuer et resource restent nécessaires, parce que le document de métadonnées est toujours publié et que la challenge le nomme toujours — un client derrière le proxy doit toujours apprendre où obtenir le jeton que le proxy vérifiera. Pour la même raison, l’issuer reste une adresse https sauf s’il s’exécute sur cette machine : ce client obtient son jeton auprès de l’issuer, donc un issuer en http simple sur un autre hôte est refusé avant que le listener ne se lie dans ce mode exactement comme dans tous les autres, même si ce serveur n’y lit rien.
Ce qu’un appelant peut atteindre
Deux limites décident de ce qu’un appelant atteint en HTTP, et elles sont fixées par des personnes différentes. Les informations d’identification propres à l’appelant sont la première ; ce que ce serveur propose tout court est la seconde. Les deux sont lues avant que quoi que ce soit ne s’exécute, à partir d’une déclaration que chaque opération fait sur elle-même, et elles parviennent à un client à des endroits différents : la liste des tools montre ce que ce serveur propose et annonce, et la réponse que reçoit chaque appel montre ce que les informations d’identification admettent.
Chaque opération déclare jusqu’où vont ses propres effets, et il en existe quatre types, le plus large en dernier :
- N’atteint rien — lit une définition, inspecte ce qu’une Release fixe, effectue le rendu d’artefacts en mémoire et les renvoie. Elle ne laisse rien derrière elle : rien n’est écrit, et la réponse est tout ce qu’elle produit.
- Atteint le workspace — écrit dans le workspace que sert ce processus : le lockfile d’une Release, le cache d’artefacts, des entités générées, un document modifié.
- Atteint un registre — publie, signe ou attache un marqueur de retrait à quelque chose de déjà publié. Ce qu’elle modifie est ce que résout chaque consommateur de ce registre, et rien de cela ne peut être repris à quiconque l’a déjà récupéré.
- Atteint la machine — modifie ce que partagent tous les workspaces de l’hôte, parmi lesquels le magasin de modules compilés, le fichier de configuration commun à tous et le magasin d’informations d’identification. Un cache qu’un seul projet conserve dans son propre répertoire de cache n’est pas de ce type, et
cache-statusindique lequel de ces types porte chaque cache qu’il liste.
Le type est une propriété de l’opération et non du tool qui la propose, et il couvre ce que l’opération laisse derrière elle — et non l’endroit où une surface place la réponse qu’elle renvoie. Le rendu d’une Release produit des artefacts comme réponse, il n’atteint donc rien ; une ligne de commande qui enregistre ensuite ces artefacts dans un répertoire que vous avez nommé livre cette réponse au lieu d’aller plus loin. Lu dans l’autre sens, chaque opération qui répond par du contenu prendrait le type de la surface qui se trouverait l’enregistrer, et le type cesserait tout à fait d’être une propriété de l’opération. Pour la même raison, describe lisant une entité par sa référence de registre n’atteint rien : il contacte ce registre pour récupérer sa réponse et ne laisse rien derrière lui, ni dans le registre ni sur cette machine, et les registres qu’il peut contacter sont décrits sous Quelles informations d’identification un appel utilise. Un appel peut tout de même aller plus loin que le type de son opération, lorsque l’appel lui-même demande une écriture : un build envoyé avec write enregistre ses artefacts dans le workspace que sert ce serveur, donc cet appel atteint le workspace, comme le fait un build qui résout d’abord ses dépendances.
Un scope admet un type, et chaque scope d’écriture implique le scope de lecture. aggrega:read admet une opération qui n’atteint rien. aggrega:workspace-write en admet une qui atteint le workspace, et implique le scope de lecture. aggrega:registry-write en admet une qui atteint un registre, et implique aussi le scope de lecture. Un client demande donc à son serveur d’autorisation le scope d’écriture dont il a besoin et n’a pas à demander en plus le scope de lecture.
Aucun scope n’admet le type machine, et aucun paramètre n’en ajoute un. Les opérations de ce type ne sont proposées que par les tools qui exécutent une commande aggrega dans un processus séparé, et un serveur atteint en HTTP n’en propose aucun, pour la raison donnée plus haut sous Atteindre le serveur en HTTPS. Exécutez-les dans un terminal sur l’hôte.
La liste des tools montre chaque tool que ce serveur propose et annonce, quels que soient les scopes que détiennent les informations d’identification appelantes, et ce sont ces informations d’identification qui décident lesquels un appel peut exécuter. describe-capabilities indexe et définit ce même ensemble. Un appel que les informations d’identification n’admettent pas reçoit 403 avec error="insufficient_scope" dans la challenge, qui nomme le seul scope qui l’admettrait, et rien de ce que l’appel demandait n’a été exécuté. Ce refus est celui auquel répond le step-up du protocole : un client qui implémente le step-up vous demande de vous reconnecter pour le scope que nomme la challenge. La liste ne change pas avec les informations d’identification, de sorte qu’un client qui s’est reconnecté détient déjà la bonne. Des informations d’identification ne portant aucun des trois scopes reçoivent la même liste de tools et ne peuvent appeler aucun des tools qu’elle contient, describe-capabilities compris.
Un build est le cas à connaître. Il ne modifie rien par lui-même et n’a donc besoin que de aggrega:read, mais un build qui écrit a besoin de aggrega:workspace-write : un build envoyé avec write enregistre ses artefacts dans dist/ à la racine du workspace, et un build qui résout d’abord ses dépendances écrit le lockfile — que l’appel l’ait demandé avec auto_pull ou que ce soit le paramètre auto_pull du workspace lui-même. Le tool est listé pour un appelant disposant du scope de lecture comme tout autre tool, et les builds qui restent en mémoire lui sont réellement disponibles ; ce qui est refusé, en nommant aggrega:workspace-write, c’est l’appel qui écrit.
Un client qui ne fait pas de step-up peut tout de même recevoir les scopes d’écriture, et cela se règle au niveau du serveur d’autorisation. Celui qui exploite le serveur d’autorisation fait des scopes d’écriture des scopes par défaut pour ce client — des scopes qu’il place dans chaque jeton qu’il émet pour ce client, que le client les ait demandés ou non — de sorte que le jeton obtenu lors de sa première connexion les porte déjà. Un client qui s’enregistre à nouveau auprès du serveur d’autorisation à chaque connexion y est chaque fois un nouveau client, et un paramètre défini lors d’un enregistrement précédent n’est pas conservé ; pour un tel client, le paramètre qui s’applique est l’ensemble des scopes par défaut que le serveur d’autorisation donne à chaque client qu’il enregistre. Le coût est que chaque connexion via ce client porte alors une portée d’écriture, que le travail en cours en ait besoin ou non — et lorsque les valeurs par défaut sont celles données à l’enregistrement, chaque client enregistré de cette manière porte aussi cette portée. Ne faites un scope par défaut que du scope d’écriture dont ce travail a besoin : aggrega:workspace-write et aggrega:registry-write admettent des types différents, et aucun des deux n’implique l’autre.
mcp.deny_reach est l’endroit où celui qui exploite ce serveur lui retire un type, et c’est l’un des deux paramètres qui raccourcissent la liste des tools. Listez les types — none, workspace, registry, machine — que ce serveur ne propose pas, et chaque tool qui atteint l’un d’eux est absent de la liste des tools de chaque appelant et de describe-capabilities quoi que dise le jeton de cet appelant, et refusé s’il est appelé malgré tout, avec une erreur qui nomme ce paramètre. C’est la limite propre au serveur et non celle de l’appelant, donc aucune information d’identification ne la lève et le refus ne porte aucune challenge : un serveur destiné à ne servir que des lectures liste ici workspace, registry et machine, et ne peut alors pas publier, même pour un appelant dont le jeton porte les trois scopes. Omettez-le, ce qui est le comportement par défaut, et ce serveur ne retire aucun type, de sorte que les types qu’atteint un appel sont décidés par les propres scopes de l’appelant. Nommer machine est accepté et ne change rien, puisque rien de ce type n’est proposé ici de toute façon. Une valeur qui n’est pas l’une des quatre est refusée au chargement de la configuration, au lieu d’être ignorée — un opérateur qui orthographie mal un type a demandé une limite, et être servi silencieusement sans elle est la mauvaise façon d’y répondre.
mcp.announce_tools est l’autre paramètre qui raccourcit la liste des tools, et les deux ne sont pas la même limite. deny_reach retire une capacité : une opération d’un type qui y est nommé n’est pas du tout proposée ici, pour personne. announce_tools ne retire qu’une annonce : les tools qu’il omet sont des capacités que ce serveur possède toujours, et ce à quoi il répond est le plafond propre à un client sur le nombre de tools qu’il enregistrera. Lorsque les deux sont définis, le retrait l’emporte, de sorte qu’un tool d’un type retiré reste absent quelle que soit la manière dont announce_tools le nomme, et le refus que rencontre un appelant nomme le retrait. Rien de ce qui raccourcit la liste ne lit les scopes de l’appelant : un scope qui manque à l’appelant refuse un appel et ne retire jamais un tool de la liste. Restreindre ce que le serveur annonce décrit le reste.
Quelles informations d’identification un appel utilise
La signature keyless via un listener tire son identité de l’identity_token que porte l’appel, et de rien d’autre. Un jeton envoyé dans l’appel est une information d’identification que l’appelant détient : il a dû l’obtenir, il lui est lié, et la signature qu’il produit lui est attribuable. Toute autre source d’où pourrait venir une identité appartient à celui qui a démarré ce processus, de sorte que sur ce transport la résolution reçoit un environnement qui ne répond rien. AGGREGA_IDENTITY_TOKEN et SIGSTORE_ID_TOKEN dans l’environnement du serveur ne sont pas lus, et l’endpoint OIDC ambiant de GitHub Actions n’est pas atteint. Ils sont hors de portée et non simplement déconseillés — il n’y a rien à trouver pour la résolution. Un appel qui n’envoie aucun identity_token est refusé, et le refus nomme identity_token comme ce qu’il faut envoyer et ne nomme aucune variable ni aucun endpoint : un appelant qui n’est pas au clavier de cette machine ne peut rien exporter ici, donc en nommer une reviendrait à lui dire de mettre en place quelque chose qui ne peut pas changer la réponse.
Une clé de signature détenue sur cette machine ne peut être sélectionnée par aucune des deux voies. key_path est refusé avant que quoi que ce soit ne soit résolu, et il est absent des schémas d’arguments que publish-entity, sign-artifacts et deprecate-artifact annoncent ici, de sorte qu’un appelant ne se voit jamais proposer un argument qui ne pourrait pas réussir. La clé de signature que nomme la configuration propre au workspace servi n’est pas atteinte non plus — signing.key_path, qu’elle soit définie pour le workspace dans son ensemble, définie pour un registre ou fournie par l’environnement. Une seule raison couvre les deux : un chemin de clé n’est pas une information d’identification, c’est un nom pour un secret que ce serveur détient. Un appelant qui en fournit un ne prouve rien, quiconque a atteint cette adresse pourrait fournir le même nom, et la signature qui suivrait dirait que c’est l’opérateur qui se porte garant de l’artefact et non l’appelant. Fermer l’argument tout en laissant la configuration ouverte reviendrait à fermer une porte sur une pièce que l’autre ouvre encore. La signature par clé est donc inaccessible via un listener : seul un jeton envoyé dans l’appel signe.
fulcio_url, rekor_url et timestamp_url ne sont pas concernés et restent disponibles sur les deux transports. Ils nomment des services à contacter et non quelque chose que cette machine détient, de sorte qu’un appelant qui ne peut pas sélectionner de clé signe tout de même auprès des endpoints que ce déploiement configure.
Un listener démarré sur un workspace qui nomme une clé de signature le signale une fois, au démarrage. Le processus écrit une ligne sur son propre flux d’erreur qui nomme le paramètre et indique qu’un appelant atteignant ce listener ne peut pas utiliser cette clé — ainsi un opérateur l’apprend du processus qu’il a démarré plutôt que d’une signature à laquelle il ne s’attendait pas. Un workspace qui ne nomme aucune clé ne produit pas une telle ligne, parce qu’il n’y a rien à en dire. La ligne porte le nom du paramètre, et ni la clé ni quoi que ce soit sur le fichier vers lequel il pointe.
Sur l’entrée et la sortie standard, rien de ce qui précède ne s’applique. Là, l’environnement est lu et key_path sélectionne une clé détenue sur cette machine, parce que le client qui a lancé ce serveur s’exécute sur la propre machine de l’appelant, et ce que ce processus peut atteindre appartient à cet appelant lui-même.
Lire une entité par sa référence de registre contacte un seul registre, avec la connexion propre à cet hôte, et via un listener uniquement un registre avec lequel le workspace servi est configuré. describe envoyé avec une référence oci:// comme name lit l’entité publiée à cette coordonnée — la même lecture qu’effectue aggrega inspect — depuis le seul registre que nomme la référence, en utilisant la connexion que cet hôte détient déjà pour ce registre. L’appel ne porte aucune information d’identification, et describe n’en accepte aucune. En HTTP, le registre doit être l’un de ceux avec lesquels le workspace servi est configuré : l’hôte que nomme son default_registry, ou un hôte listé sous registries, comparé exactement et avec le port. Une référence vers tout autre hôte — y compris une adresse sur cette machine — est refusée avant que cet hôte ne soit contacté, et le refus nomme l’hôte, de sorte qu’un appelant ne peut pas diriger ce serveur vers une destination de son choix. Ce qui reste accessible est délibéré : un appelant détenant aggrega:read peut lire tout ce que la connexion de cet hôte peut lire sur un registre avec lequel le workspace est configuré, ce qui est aussi ce qu’une personne au terminal de cet hôte peut lire. Sur l’entrée et la sortie standard, une référence vers n’importe quel registre est lue, comme en ligne de commande. Décrire une entité par son nom de catalogue n’est pas concerné.
Un appel à un registre utilise le magasin d’informations d’identification de l’utilisateur du système d’exploitation sous lequel ce processus s’exécute, exactement comme le fait le même appel dans un terminal sur cet hôte. Il n’existe aucune source d’informations d’identification par workspace ni aucun paramètre qui en ajoute une, et c’est pourquoi registry-list indique l’état des informations d’identification d’un hôte de la même manière dans chaque workspace de cette machine. Un déploiement qui veut que différents workspaces détiennent différentes informations d’identification de registre les exécute sous différents utilisateurs du système d’exploitation — un processus par workspace, chacun démarré sous son propre utilisateur. C’est de là que vient la séparation, et la mettre en place revient à l’opérateur.
Ce que le serveur enregistre
Chaque requête à laquelle cet endpoint répond laisse une ligne sur le flux d’erreur du processus, et cette ligne est un unique objet JSON. Elle porte le time auquel elle a été écrite et un request_id que ce processus a généré pour l’appel et qu’il ne renvoie pas à l’appelant ; subject et issuer tels que les informations d’identification présentées les ont affirmés, avec client_id lorsqu’elles en nommaient un ; workspace_root, le workspace que sert ce processus ; method, et target lorsque la méthode désigne quelque chose par son nom ; reach, le type que déclare l’opération, et reach_escalated_to lorsque l’appel est allé plus loin ; outcome ; duration_ms ; et transport. Un champ qui n’a rien à dire est omis plutôt qu’écrit vide, de sorte qu’un client_id absent correspond à des informations d’identification qui ne nommaient aucun client, et un reach_escalated_to absent à un appel qui a atteint exactement ce que déclare son opération.
outcome indique ce qu’il est advenu de l’appel, et les valeurs sont distinctes pour que vous puissiez les compter séparément. ok s’est exécuté et a réussi. tool-failure s’est exécuté et est revenu signalé comme un échec que l’appelant peut corriger — un appel que ce serveur a servi et non un appel qu’il a refusé, il n’a donc pas sa place parmi vos refus. error est un refus renvoyé sous forme d’enveloppe d’erreur du protocole. unauthenticated, forbidden et rate-capped sont les informations d’identification, la limite d’origine ou de scope, et le plafond de débit par appelant qui rejettent une requête. cancelled est un appelant qui a fermé sa connexion avant d’obtenir une réponse.
La raison pour laquelle des informations d’identification refusées ont été rejetées est un champ de cette même ligne et non une ligne à part. Une requête refusée laisse un enregistrement comme toute autre, avec refusal qui nomme la vérification qui l’a rejetée. Aucune information d’identification, ni aucune partie de celle-ci, n’atteint une ligne — ni lors d’un refus, ni lors d’un appel servi.
Un appelant qui n’a rien présenté du tout ne laisse aucune ligne. Recevoir une challenge est la manière dont un client découvre où obtenir un jeton, c’est donc la première chose que fait tout client correctement conçu, et une ligne pour chacune d’elles enfouirait les refus qui ont un sens. Une requête qui nomme un chemin ou une méthode que cet endpoint ne sert pas n’en laisse pas non plus : les deux sont tranchés avant que quoi que ce soit ne soit lu au sujet d’un appelant, de sorte que balayer l’adresse n’écrit rien dans ce qui collecte le flux.
Le contexte de trace qu’envoie un client est copié tel quel sur la ligne. traceparent, et à côté tracestate et baggage lorsque ceux-ci sont aussi envoyés, sont transmis exactement tels que reçus, de sorte que ce qui collecte ce flux peut le relier aux propres enregistrements de l’appelant. Une requête qui n’en envoie aucun, ou qui en envoie un qui n’est pas un contexte de trace W3C bien formé, produit une ligne sans ces clés : rien n’est inventé, et rien n’est modifié en chemin.
Le processus enregistre sa propre vie sous la même forme et sur le même flux, chacune de ces lignes nommant un event là où une ligne de requête nomme une méthode et un appelant : startup à son démarrage, listening avec l’adresse à laquelle il s’est lié, startup-refused avec la raison pour laquelle un lancement a été refusé avant de servir, signing-key-ignored lorsque le workspace qu’il sert nomme une clé de signature qu’aucun appelant atteignant ce listener ne peut utiliser, docs-bundle avec le résultat de l’acquisition du bundle de documentation, et shutdown à la fin de l’exécution. C’est la présence de event qui permet de distinguer les deux sortes de lignes.
Vous collectez tout cela depuis le flux d’erreur du processus, et c’est là toute la livraison. Il n’y a aucun exportateur à configurer, aucun fichier à nommer et aucun paramètre qui active, désactive ou redirige quoi que ce soit : ce qui supervise ce processus — un runtime de conteneurs, un gestionnaire de services, un expéditeur de logs — est ce qui collecte ce flux, et l’endroit où vous l’interrogez ensuite. Sur l’entrée et la sortie standard, le même flux porte à la place une prose lisible, parce que le client qui le lit a lancé le processus et se trouve sur la même machine.
Rien de tout cela n’est envoyé à l’appelant. Le serveur ne publie aucun flux de logs via le protocole, sur aucun des deux transports, et une requête portant le champ de niveau de log par requête du protocole reçoit exactement la même réponse qu’une requête qui n’en porte pas : ce qui est enregistré ici appartient à l’opérateur, et va au seul flux de l’opérateur.
Ce que le serveur dit au modèle lorsqu’il se connecte
Le serveur propose un bloc de consignes pour le modèle, que votre client peut lui présenter avant le premier appel. Un client en 2026-07-28 le lit dans la réponse à server/discover ; un client en 2025-06-18 le lit dans la réponse à sa poignée de main initialize. C’est le même texte sur les deux chemins, octet pour octet, et le même texte pour chaque client qui atteint un processus : rien n’y est négocié, et rien n’est dérivé de ce que le client a envoyé ni des informations d’identification qu’il a présentées, de sorte que ce que l’on dit à un modèle à la connexion ne varie ni entre les sessions ni entre les clients.
Deux choses varient, et aucune n’est le client. Le paragraphe final est composé pour le transport que sert un processus, de sorte qu’un serveur parlant sur l’entrée et la sortie standard et un listener remettent au modèle un texte final différent. Et lorsque le bundle de bureau qui a lancé un serveur provient d’une version différente de celle de l’exécutable aggrega qu’il a lancé, les consignes s’ouvrent par l’unique phrase qui le signale, en nommant les deux versions — la phrase par laquelle s’ouvre la réponse de describe-capabilities sans argument, comme l’explique De quelle version provient le serveur ; un lancement qu’aucun bundle n’a effectué, et un lancement dont le bundle provient de la version de l’exécutable lui-même, remettent les consignes sans elle. Les deux sont fixées au démarrage du processus, et dans chacun des processus les deux révisions servent toujours à l’identique le texte propre à ce processus.
Elles enseignent le modèle mental que le schéma d’arguments d’un tool ne peut pas transmettre à lui seul :
- Ce que fait le compilateur, et ce qu’il ne fait délibérément pas — qu’il achemine du texte et évalue des correspondances de labels au lieu d’interpréter ce que signifie une valeur, qu’il est sans parti pris sur le contenu que vous mettez dans vos documents, et qu’en compilant il ne s’authentifie jamais auprès d’un fournisseur, ne lit jamais l’état d’un cluster et ne transforme jamais un secret en texte en clair. Une valeur qui n’existe qu’une fois l’infrastructure en cours d’exécution transite sous forme de chaîne pointeur que l’environnement cible renseigne plus tard.
- Le vocabulaire d’authoring, et la manière dont les types sont liés — à quoi sert chaque type et sur lequel un build est réellement exécuté, de sorte qu’un assistant n’a pas à déduire la forme d’un déploiement de la liste des tools.
- L’ordre dans lequel se déroule la boucle d’authoring — lire le contrat, générer une structure à partir de celui-ci, inspecter ce à quoi vous vous connectez, puis vérifier avant le rendu.
- Quand recourir à un prompt plutôt qu’à un tool — un tool pour agir, un prompt pour cadrer une tâche.
- Que la liste des tools est toute la surface — chaque tool que propose ce serveur s’y trouve, et les tools que propose un serveur dépendent de la manière dont il a été configuré, de sorte qu’un assistant lit ce qui est présent dans cette liste et dans
describe-capabilitiesau lieu d’en chercher une seconde. Lorsque la connexion a présenté des informations d’identification, elles indiquent que ce sont ces informations d’identification qui décident lesquels de ces tools un appel peut exécuter, et jamais lesquels sont listés : un appel qu’elles n’admettent pas est refusé en nommant le scope qui l’admettrait, et le client peut se reconnecter pour ce scope. - Ce que signifie un workspace vide, et ce que le modèle peut y faire — le paragraphe qui diffère selon le transport, ci-dessous.
Elles nomment les surfaces au lieu de les reformuler. Chaque tool porte déjà sa propre description et son schéma d’arguments dans tools/list, et le contrat de chaque type se trouve déjà dans son schéma et sa page de référence, de sorte que les consignes renvoient à ceux-ci et s’arrêtent là — un seul emplacement par énoncé. Un tool qu’elles nomment est un tool que le serveur sert, et elles renvoient à chaque famille de ressources que la surface de lecture résout, de sorte que rien vers quoi elles envoient un assistant n’est une impasse.
Elles ne contiennent aucun index des tools eux-mêmes, et c’est la même règle, non une omission par rapport à elle. Un client détient la définition de chaque tool depuis tools/list avant de lire un mot de ce texte, de sorte qu’une ligne par tool ici serait une seconde copie de finalités qu’il possède déjà — payée à chaque session, par chaque client, et libre de diverger de la liste des tools dès que l’une ou l’autre serait modifiée.
Elles indiquent aussi ce qu’elles n’énumèrent pas, et pourquoi : les cibles de rendu disponibles et les types de bibliothèques installés sont des propriétés de vos plugins et de votre ensemble de schémas, de sorte que les surfaces de ressources les rapportent directement au lieu que les consignes en portent une copie qui pourrait diverger.
Ce que l’on dit à un modèle au sujet d’un workspace vide
Le paragraphe final répond à la question qu’un modèle rencontre en premier sur un workspace qui ne contient rien : ce que signifie un list-entities vide, et ce qu’il peut y faire. Son début est le même sur les deux transports — une liste vide signifie que le workspace que ce processus a résolu ne contient aucun document Aggrega qu’il puisse lire et que les répertoires de catalogue configurés à côté n’en déclarent aucun non plus — et ce qui suit dépend du transport que sert ce processus, parce que la réponse honnête n’est pas la même sur les deux.
Sur l’entrée et la sortie standard, on dit au modèle que le workspace est à lui pour l’inspecter et le réparer. On lui dit où un appel qui ne nomme aucun workspace reçoit sa réponse — dans le dossier avec lequel le serveur a été lancé, lorsqu’il a été lancé avec un dossier, et sinon dans le workspace trouvé à partir du dossier dans lequel il a été démarré, qui peut être ce dossier lui-même — et que workspace_root sur un appel en nomme un autre. On l’oriente vers config-show pour la configuration en vigueur et la couche qui a décidé de chaque paramètre, et vers cli-config-init pour en initialiser une fonctionnelle ; les deux figurent dans la liste des tools sur ce transport. Le client qui exécute le serveur se trouve sur la propre machine de l’appelant, de sorte que ce que ce processus peut atteindre appartient à cet appelant lui-même — et l’endroit où vous fixez la limite est celui où elle est fixée pour tout autre tool, dans votre client MCP, comme l’explique Ce qu’un assistant peut faire sans vous demander d’abord.
En HTTP, on dit au modèle de signaler plutôt que de configurer. Le workspace est celui sur lequel vous avez démarré le processus et il est fixé pour toute sa durée de vie ; un appel qui nomme workspace_root ou catalog_dirs est refusé, en nommant l’argument ; et aucun tool qui écrit de la configuration n’est proposé ici à un appelant, quels que soient les scopes que portent ses informations d’identification. Ces opérations ne sont proposées que par les tools qui exécutent une commande aggrega dans un processus séparé, et une session atteinte en HTTP est composée sans eux — la limite est donc la composition et non un scope, et aucun jeton ne l’élargit. Un modèle qui atteint votre déploiement via un listener ne peut donc ni initialiser un registre ni réécrire une politique de confiance sur votre hôte, et le paragraphe le lui dit au lieu de le laisser essayer et lire le refus.
Ce qu’un assistant peut faire sans vous demander d’abord
Un assistant connecté à ce serveur sur l’entrée et la sortie standard peut appeler chaque tool que le serveur expose, sans vous le demander, sauf si votre client est configuré pour le refuser. Sur ce transport, le serveur propose les tools et ne décide pas lesquels un appel donné est autorisé à utiliser : cette décision appartient à votre client, et c’est à vous de la prendre là. En HTTP, il n’en va pas de même : le serveur liste chaque tool qu’il propose et annonce, et refuse un appel que les scopes du jeton appelant n’admettent pas, de sorte que la limite relève du serveur aussi bien que du client.
Cela compte parce que la surface des tools est la ligne de commande. Tout ce que vous pouvez taper, un assistant peut l’appeler — y compris les opérations qui modifient votre machine.
Certaines de ces opérations vont au-delà du workspace dans lequel vous travaillez, et ne peuvent pas être annulées en exécutant autre chose. Voici celles qu’il vaut la peine de connaître par leur nom, la portée la plus large en premier :
publish-entity,publish-artifact,sign-artifactsetdeprecate-artifactvont entièrement au-delà de la machine. Ils placent des octets, une signature ou un marqueur de retrait dans un registre, de sorte que ce qu’ils modifient est ce que résout chaque consommateur de ce registre — pas seulement ce que fait cette machine. Republier un contenu différent sur un tag est refusé plutôt que proposé, donc rien ici ne revient sur une publication ; la réponse consiste à publier une nouvelle version. Une signature et un marqueur de retrait laissent intacts les octets de l’artefact, mais quiconque récupère cet artefact par la suite les récupère aussi, et aucun des deux ne peut être repris à quiconque l’a déjà. Sur l’entrée et la sortie standard, les quatre mêmes capacités sont aussi accessibles sous la forme decli-push,cli-push-artifact,cli-signetcli-deprecate, qui exécutent les commandes ; en HTTP, ces quatre tools n’existent pas.- La signature utilise des informations d’identification. Sur l’entrée et la sortie standard, la signature keyless prend un jeton d’identité dans l’argument
identity_tokende l’appel, dansAGGREGA_IDENTITY_TOKENouSIGSTORE_ID_TOKENde l’environnement du serveur, ou auprès de l’endpoint OIDC ambiant de GitHub Actions lorsqu’il est accessible ;key_pathsélectionne à la place une clé détenue hors ligne. Un assistant qui peut appeler ces tools peut donc signer en votre nom, avec l’identité que porte déjà la machine qui exécute le serveur — et une signature est une déclaration sur qui se porte garant d’un artefact, c’est pourquoi c’est l’opération à laquelle il faut réfléchir le plus avant de l’autoriser. Via un listener, seul un jeton envoyé dans l’appel signe : rien dans l’environnement du serveur n’est lu, et aucune clé détenue sur l’hôte ne peut être sélectionnée par un argument ou par la configuration du workspace servi, comme l’explique Quelles informations d’identification un appel utilise. aggrega cache evictréduit le magasin de modules compilés, etaggrega cache clearle vide. Ce magasin est partagé par chaque projet Aggrega de la machine. Les modules qui en sont retirés sont recompilés à la demande, donc rien n’est perdu définitivement — mais le build suivant de n’importe quel projet en paie le coût.aggrega cache clearsupprime aussi le bundle de documentation que lit chaque projet de la machine, qui est récupéré à nouveau la prochaine fois que l’un d’eux l’acquiert.aggrega cache prunelibère les entrées du cache d’artefacts qu’aucun lockfile ne référence. Lorsque le lockfile d’un projet n’est pas présent pour être lu, ses artefacts fixés ne sont pas protégés par celui-ci, et les libérer implique de les récupérer à nouveau.aggrega registry addetaggrega registry removeécrivent par défaut dans la configuration partagée par tous les workspaces, de sorte qu’ils modifient ce qui est résolu partout sur la machine, pas seulement ici.aggrega registry adddemande aussi au registre qu’il nomme la politique de confiance que ce registre annonce et fixe ce qu’il reçoit, exactement comme dans un terminal. Dans un workspace hors ligne, cette récupération est refusée avant toute connexion, de sorte que l’ajout d’un registre autre que le hub officiel est refusé — code courtE0310, dans les mêmes termes — sauf si l’appel fournitidentityoukey;aggrega config init, qui n’accepte ni l’un ni l’autre, ne peut initialiser hors ligne que le hub. Sur l’entrée et la sortie standard, ils sont accessibles sous la forme decli-registry-addetcli-registry-remove, et l’initialisation sous la forme decli-config-init, qui exécutent les commandes ; en HTTP, ces tools n’existent pas.pulllit depuis un registre et écrit dans le workspace vers lequel il est dirigé. Il écrit le lockfile de cette Release, remplit le cache d’artefacts avec ce qu’il a résolu, et enregistre à côté du lockfile l’identité de chaque plugin renvoyant un verdict que votre workspace attache. Envoyé avecpin_sources— ou dans un workspace dontpin_sources_at_pullest activé et pour un appel qui ne l’envoie pas à false — il exécute aussi l’étape de pin de l’auteur de l’entité sur les Recipes et les FeatureRecipes que la Release construit à partir de vos répertoires de catalogue, en écrivant l’entity.lockà côté de chacune ; sans cela, un pull sur une telle entité dont le lock n’enregistre aucun pin pour une entrée qu’elle lit est refusé, en nommant l’étape. Les fichiers d’entité eux-mêmes ne sont jamais écrits. Rien de tout cela ne quitte la machine, et résoudre à nouveau est la manière de changer ce qui a été enregistré, c’est donc la plus légère des opérations d’écriture présentées ici. C’est l’un des tools conçus pour la boucle d’authoring qui écrivent dans le workspace :pinécrit l’entity.lockà côté de la Recipe ou de la FeatureRecipe que vous nommez, comme l’explique Fixer les entrées propres d’une entité ;gen-catalogécrit des entités Plugin générées dans le répertoire que vous nommez ;edit-documentapplique une modification structurée et bornée à un document que vous avez déjà et le réécrit, en préservant chaque octet que la modification ne touche pas, comme l’explique Appliquer une modification bornée à un document ; etimporttransforme une description produite par un autre outil en fichiers d’authoring brouillons et les écrit dans le workspace, comme l’explique Transformer une description étrangère en entités brouillons ; etscaffold, envoyé avecexample, écrit l’un des exemples exécutables de la documentation dans un répertoire nouveau ou vide,dir, comme le faitaggrega scaffold --example, ce qu’admet en HTTP la portée d’écriture dans le workspace. Ce répertoire de sortie, le guest que litgen-cataloget tout overlay que vous lui donnez sont chacun relatifs à la racine du workspace, ou absolus sur l’entrée et la sortie standard, selon le même contrat que tout autre argument de chemin sur cette surface. Sur l’entrée et la sortie standard, la même capacité est aussi accessible sous la forme decli-pull, qui exécute la commande ; en HTTP, ce tool n’existe pas.buildlit le même registre et effectue la même écriture lorsque vous lui envoyezauto_pull, et seulement dans ce cas. Résoudre les dépendances d’une Release est une seule et même opération partout où elle est demandée, de sorte qu’un build à qui l’on demande de résoudre d’abord fait exactement ce que faitpullpuis effectue le rendu à partir de ce qu’il a écrit — c’est pourquoi il porte la même portée et non une portée moindre. Envoyé avecwrite, il écrit aussi les artefacts rendus dansdist/à la racine du workspace, là oùaggrega buildles écrit et par la même écriture, de sorte qu’il atteint le workspace pour cet appel ; il n’écrit nulle part ailleurs, et undistqui est un lien menant hors du workspace est refusé avant que quoi que ce soit n’y soit supprimé ou écrit. Sans aucun des deux arguments, ce qui est le comportement par défaut,buildeffectue le rendu à partir des pins que le workspace détient déjà et n’atteint rien. Lisez Construire à partir du contenu qu’une Release fixe déjà pour savoir ce que l’argument change et ce qu’il laisse inchangé.
Les tools d’inventaire le disent dans leurs propres réponses. cache-status marque chaque classe de cache avec sa portée — workspace pour le cache d’artefacts dans le répertoire de cache propre à ce projet, machine pour les magasins que partagent tous les projets — et nomme explicitement ceux qui s’étendent à toute la machine, de sorte qu’un assistant qui lit l’inventaire avant de proposer un nettoyage apprend quelles parties ne vous appartiennent pas à vous seul. Les opérations de maintenance indiquent la même portée pour chaque élément qu’elles ont supprimé. Chacun des quatre résultats de publication porte son propre reach, contenant registries — chaque hôte de registre auquel l’appel s’est adressé, chacun nommé une fois, dans l’ordre où il s’est adressé à eux pour la première fois — et beyond_this_machine, qui se déduit de ce que l’appel a réellement attaché et non de ce qu’il a demandé : true dès qu’il a téléversé du contenu ou attaché une signature, une date de publication ou un marqueur de dépréciation, et false pour une simulation et pour un appel qui a trouvé tout cela déjà présent, comme une publication exécutée à nouveau sur une version complète ou un lot de signature dont les références étaient toutes déjà signées.
Où vous fixez la limite. Le protocole lui-même ne définit aucune autorisation par tool — son authentification porte sur la question de savoir si un client peut se connecter, et non sur les tools qu’il peut ensuite appeler. La décision d’autorisation se trouve dans votre client MCP. Les clients largement utilisés peuvent généralement autoriser et refuser des tools individuels d’un même serveur par leur nom, et désactiver entièrement un serveur pour un projet donné ; le nom et l’emplacement du paramètre diffèrent selon le client, consultez donc la documentation de votre client sur les autorisations des tools. Si vous voulez les lectures et non les écritures, autorisez-y les tools que vous voulez et refusez le reste. Une configuration permissive, ou un client sans un tel paramètre, laisse appelable chaque tool exposé.
Découvrir ce que contient un espace de travail
La plupart des outils prennent un sujet : un nom d’entité ou le chemin d’une Release. Les deux ci-dessous n’en prennent aucun, et c’est par eux qu’un assistant qui vient d’arriver en obtient un.
list-entities répond à ce que contient l’espace de travail et list-releases répond à la question plus étroite que le reste de la surface ne cesse de poser : quelles Releases existent. Aucun des deux ne prend de sujet, car ce que contient un espace de travail est une propriété de l’espace de travail et non de quelque chose que l’appelant doit connaître d’abord.
Chacun répond sous l’une de deux formes, et un appel qui ne nomme aucune forme reçoit le résumé. Ce comportement par défaut n’appartient qu’à ces deux outils, et c’est l’inverse de celui qu’adoptent build, describe et validate. Ceux-là sont interrogés sur un sujet que l’appelant a déjà nommé, si bien que la réponse la plus complète est celle qui a été demandée et la réponse concise est l’option. Ces deux-ci sont interrogés sur ce qui se trouve ici, par un appelant qui n’a encore rien à nommer et aucun moyen de savoir ce que coûtera la réponse avant qu’elle n’arrive — ils indiquent donc d’abord la taille et la forme de l’espace de travail et ne livrent des enregistrements que sur demande.
Le résumé dit ce qui se trouve ici et en quelle quantité. list-entities indique la racine de l’espace de travail — retenue sur HTTP, comme l’expose Ce qu’une réponse dit du système de fichiers du serveur —, le nombre total d’entités et un décompte par type ; list-releases indique le total et un décompte par répertoire de premier niveau, de sorte que vous savez combien de Releases il y a et dans quelle partie de l’arborescence elles se trouvent. Les deux ventilations sont lues dans les documents eux-mêmes, si bien qu’un espace de travail organisé d’une manière que personne n’avait prévue est résumé aussi fidèlement qu’un autre. Toutes deux comportent une ligne par type, ou par répertoire de premier niveau, si bien que leur taille suit le nombre de types que déclare un espace de travail et le nombre de répertoires où se trouvent ses Releases, et non le nombre de documents qu’il contient : multipliez par cent les documents d’un espace de travail, sans changer ses types, et le résumé ne grandit que des quelques octets nécessaires pour écrire les nombres plus grands. C’est déclarer davantage de types qui l’allonge. Aucun des deux n’est une première page d’enregistrements, et toute la différence est là : « voici quelques-unes des entités » est une autre réponse que « voici ce dont est fait l’espace de travail », et seule la seconde vous dit si vous voulez des enregistrements, et lesquels.
Envoyez response_format: detailed pour obtenir les enregistrements, qui arrivent une page à la fois. list-entities indique alors le type, le nom, l’apiVersion, la description, les étiquettes et le fichier source de chaque entité, lus directement dans le document qui la déclare. Il indique aussi les Features que déclarent vos répertoires de catalogue configurés, de sorte qu’une Feature qui vous est proposée comme attachable soit aussi une Feature que vous pouvez consulter ; celles-ci n’ont pas de fichier source, car le seul chemin qu’elles ont se trouve sur la machine où tourne le serveur, et chacune dit d’où elle vient, de sorte qu’un fichier vide se lit comme « résolu depuis le catalogue » et non comme une valeur manquante. list-releases indique le chemin de chaque Release, et lockfiles associe chaque chemin renvoyé au chemin du lockfile de cette Release, dans la même coordonnée : le fichier que pull écrit pour elle et que build lit, le même fichier que nomment les réponses du serveur de langage sur les Release. La table décrit les chemins que porte cette réponse, elle suit donc la page, et le résumé la porte vide.
detailed et concise sont les seules valeurs que prend response_format, et elles sont comparées exactement. Toute autre graphie — un autre mot, une autre casse ou des espaces autour de l’une d’elles — est refusée, et le refus nomme ce qui a été envoyé à côté des valeurs que l’argument accepte. Omettre response_format est la façon de demander la valeur par défaut, qui pour ces deux outils est le résumé. Il en va de même partout où l’argument apparaît : build, describe et validate prennent les deux mêmes valeurs aux mêmes conditions, et leur valeur par défaut est la forme la plus complète plutôt que la forme concise.
Les enregistrements sont bornés, que vous les borniez ou non. limit indique combien une réponse en porte, entre 1 et 500, avec 50 par défaut — un appel qui demande des enregistrements sans nommer de taille de page est donc tout de même borné, et aucune invocation de l’un ou l’autre outil ne renvoie une réponse dont la taille de l’espace de travail décide. offset indique où commencer dans la liste, en comptant à partir de 0. Tous deux bornent les enregistrements, si bien qu’aucun n’a d’effet sur le résumé, qui n’en porte aucun. Un limit hors de cette plage est refusé et nomme la borne ; un offset au-delà de la fin de la liste revient vide, parce qu’il n’y a rien là et non parce que la question pose problème.
Poursuivez une liste en lisant trois champs de la réponse. count indique combien d’enregistrements contient l’espace de travail, offset et returned disent où commence cette réponse et combien elle en porte, et more_remaining dit s’il en reste. Tant que more_remaining vaut true, rappelez avec offset plus returned. Ce signal est calculé à partir de la page rapportée au total plutôt qu’écrit dans la réponse, si bien qu’il ne peut pas indiquer qu’il ne reste rien alors qu’il reste des enregistrements.
Tout cela compte parce que les outils qui prennent un nom refusent celui qu’ils ne peuvent pas résoudre plutôt que de répondre par un résultat vide. Le refus est délibéré — une réponse vide présenterait un nom mal saisi comme un sujet n’ayant rien à offrir —, mais il signifie qu’un appelant qui n’a aucun nom ne peut pas en obtenir un en devinant. Énumérer est le moyen d’en obtenir un.
Les deux se combinent, entre eux et avec le reste de la surface :
- Appelez
list-entitiespour obtenir le résumé et voir quels types contient l’espace de travail et combien de chacun, puis appelez-le à nouveau avecresponse_format: detailedpour les enregistrements, prenez un nom dans le résultat et transmettez-le àdescribepour voir la définition entièrement résolue de cette entité. C’est la définition par laquelle répondaggrega/entityDefinitiondu serveur de langage, transportée en JSON : chaque clé sous le nom que son auteur écrit, dans l’ordre où la définition la contient, un schéma tel que l’auteur l’a écrit, et un schéma que l’entité ne déclare pas omis — les sockets d’un Component, chacun avec les slots que ses connexions peuvent remplir. - Faites de même avec
list-releases, prenez un chemin dans le résultat détaillé et transmettez-le àdescribeou àbuildcomme la Release sur laquelle travailler. - Le chemin que renvoie
list-releasesest relatif à la racine de l’espace de travail, qui est la même coordonnée sous laquellelist-entitiesindique un fichier, si bien que les deux réponses s’alignent sur le fichier et peuvent être lues ensemble. Son lockfile, souslockfiles, est relatif à la même racine, de sorte que vous pouvez lire ou comparer ce fichier sans avoir à déterminer où il se trouve.
Tous deux décident de ce qui compte en lisant le kind propre à chaque document, jamais son nom de fichier. Une Release nommée sans préfixe conventionnel est listée ; un fichier simplement nommé comme tel ne l’est pas, et apparaît sous le type qu’il déclare réellement. Un YAML qui ne déclare aucun kind — le fichier de valeurs d’un chart, un fichier de configuration qui se trouve dans l’arborescence — n’est pas une entité et n’est pas indiqué, pas plus qu’un document appartenant à un autre projet, comme un manifeste Kubernetes rendu. Un document compte comme entité lorsqu’il déclare à la fois un kind et un nom, car c’est ensemble qu’ils le rendent adressable par la suite, et qu’il ne déclare aucune apiVersion en dehors du groupe propre à Aggrega. Un document qui ne déclare aucune apiVersion est indiqué, puisqu’il s’agit d’un document Aggrega auquel il manque un champ et non du fichier d’un autre projet. list-releases ne parcourt aucun répertoire en dehors de la racine de l’espace de travail, de sorte qu’une Release que votre éditeur affiche sous un lien menant à un tel répertoire n’est pas listée ; unread_linked_dirs nomme chaque lien qui se trouve là où la liste lirait un répertoire et qui mène hors de la racine — par le chemin propre du lien relatif à la racine, jamais par sa destination —, sous les deux formes et sur les deux transports, et il est vide là où il n’y en a pas. Il ne lit pas non plus de fichier hors de la racine à travers un lien : unread_linked_files nomme, de la même façon, chaque lien dont le nom propre se termine par .yaml ou .yml et qui mène à un fichier hors de la racine, quel que soit le contenu de ce fichier, de sorte qu’une Release atteinte uniquement par un tel lien n’est pas listée — sauf si la configuration de l’espace de travail nomme cette Release, comme build.authoring_release ou comme clé de workspace.releases, auquel cas elle est lue et listée à l’emplacement propre du lien et n’est pas nommée. list-entities ne lit pas non plus de document derrière un lien menant hors de l’espace de travail — il ne parcourt aucun répertoire en dehors de la racine et ne lit aucun fichier hors de celle-ci, quoi que ce fichier déclare — et nomme chacun de ces liens de la même façon, dans ses propres unread_linked_dirs et unread_linked_files, sous les deux formes et sur les deux transports. Cela vaut quoi que déclare le document, avec la seule exception que fait list-releases : une Release que nomme la configuration de l’espace de travail, comme build.authoring_release ou comme clé de workspace.releases, est lue et listée à l’emplacement propre du lien et n’est pas nommée, tandis qu’un fichier nommé par l’un de ces paramètres qui déclare autre chose qu’une Release n’est pas listé, et son lien est nommé. Les répertoires de catalogue configurés sont le moyen par lequel un espace de travail lit d’autres entités conservées ailleurs, de sorte qu’un lien vers un répertoire que la configuration liste sous catalog_dirs, ou vers un répertoire situé en dessous, n’est nommé par aucune des deux listes : la configuration l’a atteint. Les Features que list-entities prend dans les répertoires de catalogue n’en incluent jamais une derrière un lien menant hors du répertoire dans lequel les lectures d’un répertoire de catalogue doivent rester — l’espace de travail, pour un répertoire de catalogue qui s’y trouve, ou le répertoire lui-même, pour un répertoire que la configuration nomme en dehors de celui-ci —, de sorte qu’une entité nommée comme se trouvant derrière un lien non lu n’est jamais listée à côté de ce nom. Un lien que la liste écarte — par son nom, par son emplacement ou par un .gitignore — n’est pas nommé, et avec release pas davantage un lien situé sous un répertoire de catalogue que seules d’autres Releases lisent ; un .gitignore qui est lui-même un lien menant hors de l’espace de travail n’est pas lu. Lorsque l’une de ces listes nomme un lien, la réponse textuelle se termine par une ligne à part qui le signale.
Un espace de travail dont le fichier de configuration mène hors de lui est tout de même listé, et rien d’autre n’est répondu pour lui. Lorsque le .aggrega-config.yaml propre à l’espace de travail, ou la surcouche gérée par la CI à côté de lui, est un lien menant hors de l’espace de travail, sa configuration n’est pas lue, comme dans un terminal, et rien de ce qu’elle aurait configuré n’est lu à sa place. Le serveur démarre tout de même sur l’entrée et la sortie standard, et le signale en une ligne sur son flux d’erreur. list-entities et list-releases répondent avec les documents propres à l’espace de travail, lus sans aucune configuration, de sorte qu’aucune Feature d’un répertoire de catalogue n’est listée. Chacun nomme le fichier retenu dans unread_linked_files, ainsi que dans la ligne qui clôt son texte, que la liste l’ait rencontré ou non — ce nom est la façon de savoir que la configuration de l’espace de travail mène hors de lui. Une liste à laquelle on a envoyé release ou catalog_dirs, ainsi que tout autre outil nommant cet espace de travail, dépend de la configuration qui n’a pas été lue, si bien que chacun est refusé avec E0321, qui nomme le lien et sa destination. Un serveur à qui sa ligne de commande dit d’écouter — --transport http ou --listen — ne démarre pas sur un tel espace de travail, car l’adresse à laquelle il se lierait, son certificat et qui peut l’appeler sont précisément ce que décide cette configuration. Supprimez le lien, ou faites-le mener à un fichier à l’intérieur de l’espace de travail, et l’appel suivant lit la configuration. Voir la frontière de l’espace de travail.
Interroger dans les termes d’une Release
Un espace de travail peut donner à chaque Release ses propres répertoires de catalogue — voir Donner à une Release ses propres répertoires de catalogue — et ainsi conserver côte à côte une variante d’une entité par Release. Trois outils qui répondent autrement sur les répertoires de catalogue propres à l’espace de travail prennent un release facultatif, le chemin d’un fichier de Release, et répondent alors dans les termes de cette Release :
list-entitiesavecreleaseliste les entités que voit cette Release. Les Features listées sont celles que déclarent ses répertoires de catalogue, et un document de l’espace de travail situé sous un répertoire de catalogue que seules d’autres Releases lisent est écarté, de sorte que chaque variante est listée pour la Release qui construit avec elle et pour aucune autre. Un document qui ne se trouve sous aucun répertoire de catalogue — une Release, son Aggregate et son Manifest écrits à côté des catalogues — est listé pour chaque Release.describeavec unnameet unreleaserésout le nom à travers les répertoires de catalogue de cette Release, de sorte qu’un nom que déclarent plusieurs variantes se résout vers celle avec laquelle cette Release construit. Un nom que ces répertoires ne résolvent pas est refusé avec une explication nommant l’entrée de cette Release sousworkspace.releases. Une référence de registre est lue depuis son registre quelle que soit la Release nommée, elle est donc refusée à côté d’unrelease. Unreleaseenvoyé sansnamereste la Release quedescriberésume.validateavec unentityet unreleaseexécute les vérifications d’entité unique dans les termes de cette Release : les références de l’entité — le Component qu’implémente une Recipe, une SchemaLibrary à laquelle se réfère un pilier — se résolvent à travers les répertoires de catalogue de cette Release, et la réponse nomme la Release à côté de l’entité. Aucune fermeture n’est validée ; unreleaseenvoyé sansentityreste la portée de la Release.catalog_dirsest placé ici devant les répertoires de la Release, comme partout ailleurs. Un répertoire que la configuration de l’espace de travail liste et qui n’est pas un répertoire — rien n’existe à cet endroit, par exemple —, pour cette Release, ou pour l’espace de travail lorsqu’aucunreleasen’est envoyé, fait refuser l’appel avant toute vérification, son texte portant le refus que lui oppose chaque commande et nommant l’entrée ainsi que le fichier de configuration et la ligne qui la listent (D’où sont lues les entités locales), comme le refuseaggrega validate.
Un release nommant un fichier qui n’existe pas, ou nommant un répertoire, est refusé par les trois au lieu de recevoir une réponse dans les termes de l’espace de travail. N’en envoyer aucun fait répondre sur les répertoires de catalogue propres à l’espace de travail.
Lorsqu’il recherche un nom, describe refuse un répertoire de catalogue à travers lequel il résoudrait le nom et qui ne peut pas être parcouru, comme le refuse aggrega inspect — les répertoires de cette Release lorsqu’un release est envoyé, ceux de l’espace de travail lorsqu’aucun ne l’est, et tous ceux que l’appel nomme dans catalog_dirs. Un répertoire nommé par l’appel qui n’existe pas, ou qui existe mais ne peut pas être lu, est refusé avant que le nom ne soit recherché, et le texte nomme le répertoire comme le rapporte la ligne de commande, sur une seule ligne — le répertoire, catalog load et la raison donnée par le système de fichiers — au lieu de résoudre le nom à partir des répertoires restants. Un répertoire que la configuration de l’espace de travail liste et qui n’est pas un répertoire est refusé au même moment, le texte portant le refus que lui oppose chaque commande (D’où sont lues les entités locales). Un release nommant un fichier qui n’existe pas est refusé avant cela, comme indiqué plus haut. Un répertoire de catalogue contenant un lien qui mène hors du répertoire dans lequel ses lectures doivent rester est refusé de la même façon, le texte nommant le lien et sa destination, car un nom résolu sans lui pourrait se résoudre à sa place vers une autre entité du même nom. La description de la fermeture des dépendances d’une Release n’est pas affectée par un répertoire qui ne peut pas être parcouru, et répond sur les répertoires qui peuvent l’être, comme le fait aggrega inspect --closure — sauf un répertoire que la configuration de l’espace de travail liste pour cette Release et qui n’est pas un répertoire, qu’elle refuse comme le refuse aggrega inspect --closure ; un lien menant hors des lectures d’un répertoire de catalogue, ou hors des documents situés à côté de la Release, l’interrompt, comme il interrompt un build.
validate avec un entity signale un rendu qu’il ne peut pas juger comme non tenté, dans les termes d’une Release ou sans. Il place le Component d’une Recipe dans un build synthétisé qui ne câble aucune connexion et n’attache aucune Feature, de sorte qu’une Recipe dont le rendu s’arrête pendant que ses templates — y compris les fichiers et les entrées de bibliothèque qu’ils importent — lisent quoi que ce soit sous .context.inject, .context.uses ou .features répond valid: true sans rien dans diagnostics ; son texte porte Render: not attempted (this Recipe reads values a build of one cannot supply), les lectures pour lesquelles il a été mis de côté et la phrase sur laquelle le rendu s’est arrêté. Ce qui en décide, c’est ce que lit la Recipe, de sorte qu’un défaut propre à la Recipe à côté d’une telle lecture est mis de côté avec elle, tandis qu’un template qui ne s’analyse pas et une référence que le rendu refuse répondent toujours valid: false. aggrega validate rend le même verdict sur les mêmes entrées.
validate avec un entity signale une assertion échouée comme un avertissement, dans les termes d’une Release ou sans. Une assertion qui appelle fail — celle de la Recipe elle-même, ou une que déclare le Component qu’elle implémente — répond valid: true sans rien dans diagnostics. Le build synthétisé porte des valeurs fictives et les valeurs par défaut du schéma à la place des valeurs que définit une vraie Release, de sorte qu’une assertion portant sur une telle valeur y échoue, que la Recipe soit correcte ou non, et la vérification ne peut pas distinguer une assertion qui attend une Release d’une assertion défectueuse. L’échec suit les autres notices, dans le message complet de l’assertion clos par la phrase A Release must satisfy this assertion before a build of it can pass., et le texte le porte sur une ligne ouverte par warning:, à côté de la ligne de rapport indiquant où l’exécution s’est arrêtée. Une assertion qui s’arrête sur une clé qu’elle lit mais ne trouve pas est un défaut de son propre texte et non une assertion échouée, et elle est jugée comme tout autre arrêt ; le build d’une Release qui ne satisfait pas une assertion est toujours refusé à cause d’elle. aggrega validate rend le même verdict sur les mêmes entrées.
Lire la configuration en vigueur et les plugins que ce serveur résout
config-show indique la configuration en vigueur et quelle couche a décidé de chaque paramètre. plugin-list indique les plugins que ce serveur peut résoudre et ce que chacun dit de lui-même. Tous deux ne lisent et n’écrivent rien, de sorte qu’aucun n’atteint quoi que ce soit et que aggrega:read les admet — et aucun ne vous demande de nommer un sujet, car ce qui est configuré et ce qui se résout sont des propriétés de ce serveur et non de quelque chose que vous devez connaître d’abord. Chacun prend un workspace_root facultatif sur l’entrée et la sortie standard ; sur HTTP, cet argument est refusé, comme l’expose Un processus, un espace de travail.
Ensemble, ils répondent à une question en deux moitiés : une capacité est-elle absente, ou simplement non configurée ici ? La configuration dit si un provider, un importeur ou une vérification de gouvernance est attaché ou non ; la lecture des plugins dit si un attachement atteint un invité qui se résout, se décrit et sert ce qu’il prétend servir. Partout ailleurs sur cette surface, ces deux situations se ressemblent, et elles appellent des étapes suivantes opposées.
config-show indique une entrée par paramètre : son field, sa value effective et la source qui en a décidé — un fichier de configuration, une variable d’environnement, un flag de ligne de commande ou les valeurs par défaut intégrées. À côté, layers porte les couches qui ont contribué, par ordre de priorité, la plus basse d’abord. La source d’un paramètre s’écrit exactement comme l’entrée correspondante de layers, de sorte que les deux se joignent directement, et un paramètre décidé par les valeurs par défaut ne nomme aucune couche, car les valeurs par défaut ne sont pas une couche qui a contribué. La couche globale est le fichier que sélectionne la ligne de commande propre au serveur — celui que --config a nommé à son démarrage, sinon celui que nomme la variable d’environnement AGGREGA_CONFIG, sinon l’emplacement par défaut —, de sorte qu’un paramètre décidé par ce fichier est attribué à ce fichier, exactement comme l’attribue aggrega config show --origin, et qu’un flag tel que --offline passé au serveur est indiqué comme ce flag. Il ne prend ni response_format ni taille de page : les paramètres sont l’ensemble fixe dont ce binaire rend compte et chaque résolution les indique tous, de sorte que la taille de la réponse suit le binaire et non ce que vous configurez.
plugin-list répond sous les deux formes qu’utilisent les listes de l’espace de travail, et un appel qui ne nomme aucune forme reçoit le résumé. Le résumé est un décompte par groupe, et il y a deux groupes — embedded, les invités compilés dans ce binaire, qui se résolvent sans accès au système de fichiers, au cache ni au réseau, et configured, les liaisons propres à l’espace de travail. Envoyez response_format: detailed pour les enregistrements : le groupe de chaque plugin, la référence sous laquelle il a été trouvé, l’endroit où cette référence a été liée, son type, sa version, son commit, ses capacités servies, ses types d’entrée rendus, son assemblage de frontière et ses exports tels qu’il les déclare lui-même, son état de disponibilité lorsqu’il en a un, et s’il s’est résolu. Les enregistrements sont bornés par limit et offset aux mêmes conditions que la liste des entités, avec count, returned et more_remaining pour poursuivre. Cette réponse, elle, grandit avec ce que vous configurez — les plugins intégrés sont fixes, les liaisons sont les vôtres —, c’est pourquoi elle est paginée et la lecture de la configuration ne l’est pas.
Un plugin qui échoue est indiqué avec son échec au lieu d’être retiré de la liste. resolved dit si la référence a atteint des octets de module, et un plugin qui s’est résolu mais n’a pas pu se décrire est indiqué exactement comme tel — de sorte qu’un attachement présent et inutilisable se distingue d’un attachement qui n’a jamais été fait.
Ce qu’un listener ne vous dit pas de son hôte
Sur HTTP, aucune des deux lectures n’indique une valeur qui nomme un emplacement du système de fichiers du serveur. Un client qui a lancé le serveur s’exécute là où s’exécute le serveur, de sorte que chaque emplacement que l’une ou l’autre réponse pourrait nommer est un emplacement que cet appelant possède déjà et peut aller consulter. Un appelant qui atteint un listener n’en a choisi aucun, ne peut rien faire de leur connaissance, et un serveur qui les a publiés à un tel appelant ne peut pas les reprendre. Sur ce transport, ces valeurs sont absentes ; sur l’entrée et la sortie standard, elles sont toutes présentes. C’est la règle que suit chaque réponse de cette surface, comme l’expose Ce qu’une réponse dit du système de fichiers du serveur, et ces deux lectures sont celles où elle porte le plus loin, car l’essentiel de ce qu’elles indiquent est de la configuration qui nomme des emplacements.
Ce qui est retenu. De config-show : la value d’un paramètre lorsque la valeur propre de ce paramètre est un emplacement — une adresse de service ou de santé, qui peut être un fichier socket ; un fichier de certificat, de clé privée ou de jeu de clés ; un répertoire de catalogue, ainsi que les répertoires de catalogue propres à une Release sous workspace.releases, dont chaque entrée a pour clé un fichier de Release ; une référence de plugin ; une Release d’authoring. Également la source d’un paramètre lorsque la couche qui en a décidé est un fichier de configuration, puisqu’une telle couche est nommée par le chemin propre de ce fichier — et, dans la même graphie et pour la même raison, les entrées de layers correspondant à des fichiers de configuration. De plugin-list : l’uri d’un plugin lorsque cette référence est elle-même un chemin du système de fichiers, et le texte d’un échec de résolution ou de description, qui est composé à partir des emplacements essayés et nomme donc des emplacements que la référence elle-même ne nomme pas. Des deux : workspace_root.
Ce qui est indiqué en entier, sur les deux transports. Une référence de registre, une version, un commit, un digest, une capacité servie, une étiquette de disponibilité, le nom d’une variable d’environnement ou d’un flag, et une couche qui n’est pas un fichier. origin sur un enregistrement de plugin en fait partie : c’est la clé de configuration à laquelle une liaison a été écrite, ou le digest épinglé que porte une extension de commande installée, et un plugin intégré n’en porte aucun — c’est donc la même chaîne, d’où que le plugin soit lu. resolved en est une autre : l’échec d’un plugin est indiqué à chaque appelant, même là où sa raison ne l’est pas.
Une valeur absente dit toujours qu’elle a été retenue, et c’est ce qui rend la réponse exploitable. Une valeur retenue est indiquée comme absente avec une marque à côté — value_withheld et source_withheld sur un paramètre, withheld sur une entrée de couche, uri_withheld et error_withheld sur un enregistrement de plugin, et workspace_root_withheld sur la réponse. Un paramètre que personne n’a défini porte la valeur vide sous laquelle sa forme se rend, et ne porte aucune marque. « Ce serveur ne vous dit pas où se trouve la clé de signature » et « aucune clé de signature n’est configurée » sont des réponses différentes qui appellent des étapes suivantes différentes, et une lecture qui les indiquerait de façon identique ne vous dirait rien sur quoi agir. Chaque réponse porte aussi host_locations_withheld, toujours, qui dit laquelle des deux réponses vous avez en main : une réponse sans marques est sinon la même, que cette règle l’ait façonnée sans rien trouver à retenir sur l’hôte, ou qu’elle ne se soit jamais appliquée. Le texte lisible à côté des champs dit la même chose en mots.
La règle est une propriété et non une liste de noms de champs : une valeur est retenue lorsqu’elle nomme un emplacement du système de fichiers de l’hôte, quelle que soit la personne qui l’a définie et quelle que soit la couche d’où elle vient. Une valeur ajoutée plus tard à l’une ou l’autre lecture est soumise à cette même propriété.
Sur l’entrée et la sortie standard, chaque capacité est aussi accessible sous la forme de l’outil nommé d’après sa commande — cli-config-show et cli-plugin-list —, qui exécute cette commande dans un processus distinct et renvoie le texte qu’elle a affiché ; sur HTTP, ces outils n’existent pas. Les deux décrits ici portent plutôt les valeurs, de sorte que vous lisez si une capacité est attachée, ou relevez la version d’un plugin, sans avoir à reconvertir une mise en page en colonnes en ce à partir de quoi elle a été rendue.
Demander ce qui peut être attaché, et ce qui peut se connecter à quoi
Deux outils répondent aux questions sur lesquelles un assistant devrait autrement deviner : quelles Features peuvent être attachées à un nœud, et à quoi un nœud peut se connecter. Tous deux exécutent la même correspondance d’étiquettes que le compilateur, de sorte que ce que l’assistant vous propose est l’ensemble qu’un build ferait correspondre et non un ensemble déduit du schéma.
attach-candidates indique les Features dont l’applicabilité déclarée est satisfaite par les étiquettes d’un nœud. Désignez le nœud d’exactement l’une de trois façons :
node— lemetadata.named’une entité de l’espace de travail, tel que l’indiquelist-entities. La correspondance porte sur les étiquettes que déclare ce document.graph_nodeavecrelease— un nœud d’un graphe compilé, avec la clé que lui donne le graphe, y compris la forme qualifiée que porte un nœud apporté par un sous-agrégat. La correspondance porte sur les étiquettes finalisées de ce nœud, qui sont celles qu’évalue un build.labels— un ensemble d’étiquettes seul, qui ne nomme aucun nœud. Il ne demande aucune coordonnée, si bien que si vous disposez déjà des étiquettes d’un nœud, c’est la forme à utiliser ; il ne recherche rien et ne reconstruit aucun graphe.
La réponse porte les étiquettes sur lesquelles la correspondance a porté et de lequel de ces trois ensembles elles proviennent, de sorte que vous pouvez expliquer n’importe quel candidat — ou l’absence d’un candidat — à partir de la réponse elle-même au lieu de le recalculer. Les relire par un second chemin, c’est là que votre idée des étiquettes d’un nœud et celle du compilateur divergent.
Pour demander ce qui peut être attaché à une connexion que trace un nœud, ajoutez connection à côté de graph_node et de release — son socket et son alias, tels que l’auteur les a écrits. Une connexion porte des attachements qui remplissent les slots que son socket déclare sur le Component consommateur, de sorte que la réponse porte alors aussi slots : chaque slot que déclare le socket, avec ses selector, required, inject, sensitive et description exactement tels que le Component les déclare, et les candidates qui peuvent le remplir. Ce sont les Features dont l’applicabilité est satisfaite par les étiquettes du nœud et dont les propres étiquettes sont admises par le sélecteur du slot — les deux règles auxquelles un build soumet un tel attachement —, de sorte que les candidats d’un slot figurent toujours parmi ceux du nœud lui-même. Là où rien ne peut être rempli, slots est vide et noSlotReason dit pourquoi : feature-created-connection (une Feature a tracé la connexion, et rien n’est attaché à une telle connexion), ad-hoc-socket (le socket n’est pas déclaré par le Component) ou no-slot-declared (le socket n’en déclare aucun). Ne lisez pas un slots vide comme « rien ne correspond » ; c’est précisément ce que la raison est là pour exclure, et elle est absente partout où un slot existe. candidates à côté conserve son sens — ce qui peut être attaché au nœud lui-même — et document, si vous en envoyez un, ne change rien ici. connection à côté de node ou de labels, ou ne nommant aucun socket ni alias, est refusé, tout comme une connexion que le nœud ne trace pas. Ce sont les mêmes réponses que donne le serveur de langage, aux mêmes conditions.
connection-candidates indique les sockets de dépendance que déclare une entité et, par socket, les Components de l’espace de travail dont les étiquettes déclarées satisfont la contrainte que ce socket déclare sur ses cibles. Il prend le metadata.name de l’entité dans node. Contrairement à attach-candidates, il n’a pas de forme sans coordonnée : il n’y a pas ici de forme par ensemble d’étiquettes, car les sockets sont lus dans la déclaration propre de l’entité nommée.
Ses deux moitiés ne sont pas également complètes, et la réponse dit laquelle est laquelle — ne les présentez pas comme une seule liste. Les cibles sont complètes : ce sont les composants que la même contrainte admet pendant un build. Les sockets ne le sont pas, et ne peuvent pas l’être. Un consommateur peut inventer une connexion mais ne peut consommer que ce qu’un producteur déclare, de sorte qu’un auteur peut légitimement écrire un socket que l’entité du catalogue n’a jamais déclaré, et les sockets déclarés sont un point de départ utile et non l’ensemble des noms autorisés. Chaque socket dit donc s’il est declared ou ad-hoc, et la réponse dit si un socket non déclaré est accepté ou non sur cette entité — la surface de dépendance d’un Component en accepte un, car un auteur est maître de la topologie de son application ; la surface d’attachement d’une Feature non, car un attachement participe à la topologie que déclare la Feature attachée au lieu d’en créer une. Cette ouverture est une conséquence de votre liberté d’authoring, pas une lacune : passez socket avec un nom que l’entité ne déclare pas pour vous renseigner à son sujet.
Tous deux répondent et s’arrêtent. Aucun ne crée d’attachement, ne crée d’arête, n’écrit dans un fichier ni ne propose le texte d’une telle modification ; composer et appliquer la modification qui s’ensuit vous revient.
Tous deux renvoient la même identité minimale qu’utilise toute autre réponse ici — type, nom et fichier source — et rien de plus. Tout le reste de ce que vous voudriez afficher sur une entité se trouve déjà dans list-entities pour les trois mêmes champs, de sorte que vous joignez les deux réponses au lieu de lire deux copies qui pourraient diverger. Tous deux refusent un nom qu’ils ne peuvent pas résoudre plutôt que de répondre par une liste vide, pour la même raison que le reste de la surface : une réponse vide présenterait une faute de frappe comme un sujet n’ayant rien à offrir. Un appel labels n’a aucun nom à mal saisir, si bien qu’un résultat vide y signifie ce qu’il dit.
Tout ce que le serveur lit pour référence est servi depuis cette machine — les JSON Schema sont intégrés au binaire et la documentation est lue depuis le cache de paquets de documentation que conserve la machine, comme décrit ci-dessous. La rédaction d’un document de départ, la validation, la description, le build et le linting s’exécutent tous sur votre espace de travail et les caches locaux, et aucun n’atteint un registre de sa propre initiative : un rendu sert une référence externe épinglée depuis le magasin adressé par contenu et décline une référence non épinglée au lieu de la récupérer, ce qui maintient hors ligne toute la boucle d’inspection et de rendu. Vous pouvez demander deux lectures de registre : describe avec une référence de registre, qui récupère cette seule coordonnée, n’écrit rien et, sur HTTP, n’atteint qu’un registre avec lequel l’espace de travail servi est configuré ; et scaffold envoyé avec example ou list, qui acquiert le paquet de documentation depuis le registre par défaut de l’espace de travail lorsque la machine ne détient aucune copie qu’admet la politique de signature de l’espace de travail, en le vérifiant avant de le conserver, comme le fait aggrega scaffold --example. La publication et la signature en sont le revers délibéré, et elles sont traitées plus haut.
Entre les deux se situe la résolution des dépendances d’une Release, qui est ici la seule chose qui acquiert : elle atteint un registre parce que demander de résoudre des dépendances, c’est demander de les récupérer. Elle n’a lieu que lorsque vous la demandez, et il y a exactement deux façons de la demander — appeler pull, dont c’est toute la fonction, ou envoyer auto_pull à build, qui effectue cette même résolution comme première étape du build. Rien d’autre ne fait de pull en votre nom, et un build auquel vous n’avez pas envoyé auto_pull n’atteint aucun registre. Le seul paramètre qui change cela est l’auto_pull propre à l’espace de travail : un espace de travail ainsi configuré demande à chaque build qu’il contient de résoudre d’abord, d’où que ce build soit exécuté, ce qui est traité ci-dessous.
La seule exception parmi ces lectures de référence est l’acquisition du paquet de documentation lui-même, et elle a lieu à l’écart de toute lecture. Le paquet est conservé une fois par machine, dans le cache que partagent tous les projets Aggrega, une copie par registre et par version — de sorte qu’un serveur démarré dans un dossier où aucun cache d’espace de travail ne peut être créé le conserve tout de même (voir aggrega cache). Au démarrage du serveur, avant qu’il ne réponde à quoi que ce soit que vous envoyez, il y cherche une copie qu’admet la vérification de signature de votre espace de travail — la même vérification à laquelle répond un pull du paquet — et ne récupère le paquet, via les mêmes paramètres de sortie réseau que le reste de la CLI, que lorsqu’il n’y en a aucune. Le paquet qu’il cherche est celui publié pour la version d’aggrega qu’exécute le serveur ou, lorsqu’aucun n’est publié pour elle, le plus récent publié pour une version antérieure — le même choix que font aggrega explain et aggrega scaffold --example — et chaque page qu’il sert, ainsi que chaque explication, est lue à partir de celui qu’il a obtenu. Ainsi, les pages sont déjà là au moment où quelque chose en demande une, quoi que votre client envoie en premier, et un autre serveur, ou aggrega explain dans un autre projet, trouve la même copie au lieu de la télécharger à nouveau.
Servir une page est alors une lecture de cette copie, et n’atteint aucun registre. Avant qu’une page ne soit servie, les signatures conservées à côté de la copie sont vérifiées à nouveau selon la vérification de votre espace de travail, de sorte qu’une copie qu’a laissée entrer le paramètre plus permissif d’un autre projet ne vous est pas servie : là où la vérification épingle une clé ou une racine de confiance, cette vérification se fait hors ligne, et là où elle n’épingle ni l’une ni l’autre — la vérification intégrée du hub officiel en est une — elle obtient la racine de confiance publique de Sigstore, comme le fait un pull. Un espace de travail hors ligne ne peut pas récupérer cette racine de confiance, il vérifie donc hors ligne par rapport à la racine de confiance qu’une récupération en ligne antérieure sur cette machine a laissée dans le cache que le client Sigstore conserve sous .sigstore dans votre répertoire personnel, quelle que soit l’ancienneté de cette récupération, et ne récupère rien ; sur une machine qui ne l’a jamais récupérée, la vérification ne peut pas s’exécuter hors ligne, la copie n’est pas servie et le flux de journalisation le signale. Cette vérification s’exécute une fois pour chaque copie et chaque vérification tant que le serveur tourne, et les pages lues ensuite sont servies sur la base de ce qu’elle a admis : une copie récupérée depuis, un espace de travail dont la vérification diffère — y compris une racine de confiance épinglée modifiée sur place —, une lecture faite hors ligne, ou une lecture hors ligne trouvant une autre racine de confiance laissée sur la machine est vérifiée pour elle-même. Une copie que votre vérification a refusée est vérifiée à nouveau à la lecture suivante, de sorte qu’une récupération qui l’a admise depuis n’est pas contredite. Si le paquet ne peut pas être acquis, ou si la seule copie est une copie que votre vérification refuse et que sa nouvelle récupération selon cette vérification échoue, le serveur démarre tout de même et toutes les autres surfaces fonctionnent ; les requêtes de documentation répondent not-found, et le flux de journalisation du serveur dit pourquoi.
Construire à partir du contenu qu’une Release épingle déjà
build effectue en mémoire le rendu d’une Release en ses artefacts, et un rendu peut demander du contenu à une URL distante — le schéma des values d’un chart comportant une référence distante, par exemple. Les entrées externes sont figées pour la durée de l’appel. Une référence que le lockfile de la Release épingle déjà est servie depuis le store adressé par contenu, ce qui est une lecture de contenu déjà présent sur disque et non un téléchargement. Une référence que le lockfile n’épingle pas est écartée et nommée au lieu d’être téléchargée : ce que vous avez demandé, c’est un rendu, et acquérir une référence reviendrait à la fois à atteindre le réseau et à écrire un blob dans le store, comme effet de bord de la production d’octets. Ce gel est une propriété du rendu. La résolution est l’étape qui acquiert : elle effectue le rendu de la Release pour savoir quelles références distantes ce rendu demande, les télécharge et les enregistre dans la même écriture du lockfile que celle qui porte les épinglages des dépendances. Ce que la résolution change, c’est donc quelles références sont épinglées au moment où un rendu s’exécute, jamais ce qu’un rendu peut atteindre — et une référence qu’aucune résolution n’a épinglée est écartée lors d’un appel qui a d’abord résolu exactement comme lors d’un appel qui ne l’a pas fait.
Les fichiers reviennent sous la forme des octets qu’émet un vrai build, et deux choses ensemble rendent cela vrai. La première est le gel décrit plus haut : une référence épinglée est lue depuis le store au lieu d’être téléchargée. La seconde est que le lockfile lu décrit toujours ce vers quoi la Release se résout — build le vérifie donc, et refuse un lockfile qui ne correspond plus, exactement comme le fait aggrega build dans un terminal. Lire des octets épinglés ne dit rien, à lui seul, sur le fait qu’il s’agissait des bons octets à lire.
Les trois états du lockfile, afin que le comportement soit explicite. Sans aucun lockfile, build effectue le rendu à partir de ce que l’espace de travail épingle déjà et écarte chaque référence externe qu’il ne peut pas servir, en les nommant une à une ; laissé à lui-même, il n’exige pas de lockfile et n’en écrit pas, et la vérification décrite plus haut n’y change rien — il n’y a pas de lockfile à comparer, donc rien n’est refusé. Avec un lockfile qui correspond, il effectue le rendu. Avec un lockfile qui ne correspond plus, il refuse, et le refus indique comment lever le problème : appelez pull avec la même release et sans upgrade_targets, ce qui réconcilie le lockfile avec ce vers quoi la Release se résout aujourd’hui. Le refus porte aussi la forme pour terminal de cette même opération, aggrega pull --release <release>. L’une ou l’autre invocation le lève ; il s’agit d’une seule opération accessible depuis deux endroits, et non de deux instructions entre lesquelles choisir. Lorsque pull aboutit et que le refus revient, les deux appels ont résolu sur des entrées différentes — le plus souvent catalog_dirs fourni à l’un et pas à l’autre, ou une configuration de l’espace de travail modifiée entre les deux — et le refus le dit : appelez les deux avec les mêmes.
validate et describe, lorsqu’ils reçoivent une release seule, sont tenus au même lockfile. Sur un lockfile qui ne correspond plus à ce vers quoi la Release se résout, chacun refuse au lieu de répondre, son texte portant l’arrêt pour dérive avec lequel build refuse et le même moyen de le lever — comme refusent dans un terminal aggrega validate --release et aggrega inspect --closure. Avec un lockfile qui correspond, ou sans lockfile, chacun répond comme il le fait par ailleurs.
Demander à un build de résoudre d’abord ses dépendances
Envoyez auto_pull et le build résout avant d’effectuer le rendu. Il effectue la même résolution que pull — l’opération elle-même, et non une seconde écrite pour un build, de sorte qu’un espace de travail rempli par un build et un espace rempli par un appel pull sont remplis à l’identique —, écrit le lockfile de la Release, puis effectue le rendu à partir de ce qu’il a écrit. Cette étape atteint un registre et écrit, ce que rien d’autre dans build ne fait hormis write, et write n’atteint aucun registre — elle est donc désactivée sauf si on la demande.
Il répond aux deux refus décrits plus haut sans quitter le protocole. Une Release que personne n’a encore résolue effectue son rendu à partir des épinglages qui se trouvent là et écarte le reste ; un lockfile qui a dérivé arrête net le build. Envoyer auto_pull résout d’abord et effectue le rendu à partir d’un lockfile dérivé de la fermeture dont traite ce build, de sorte que les deux cas reviennent sous forme de rendu plutôt que comme quelque chose à aller corriger. Si vous voulez la résolution et le rendu comme deux étapes distinctes — pour lire ce qui a été épinglé avant d’en effectuer le rendu —, appelez pull puis build, ce qui revient aux deux mêmes opérations avec un coup d’œil entre les deux.
Un appel effectue le rendu de la Release une seule fois. Découvrir quelles références distantes une Release consomme est en soi un rendu, de sorte qu’une résolution a déjà effectué le rendu de la Release dont traite le build — à partir des épinglages mêmes qu’elle vient d’écrire, avec chaque contrôle qu’exécute un build. Le build reçoit sa réponse de ce rendu au lieu de le répéter, c’est pourquoi envoyer auto_pull coûte une résolution et non un second rendu. Seul un rendu qui s’est terminé est utilisé ainsi : lorsqu’une résolution a épinglé ses dépendances mais n’a pas pu terminer la découverte des références externes, le build effectue son propre rendu à partir des épinglages effectivement écrits, et une référence non épinglée l’arrête alors en la nommant, au lieu de revenir sous la forme d’une liste de fichiers en deçà de ce qu’émet un build.
Ce qui revient dit ce qui a été résolu. Un build qui a rempli porte dependency_resolution dans sa réponse, sous la forme dans laquelle répond pull : le lockfile qu’il a écrit, chaque référence atteinte par la résolution avec la version vers laquelle chacune s’est résolue et l’endroit où la résolution de ce build l’a prise, les décomptes que contient ensuite le lockfile, et le compte rendu que la résolution fait d’elle-même ligne par ligne. Un build qui n’a pas rempli ne porte pas du tout ce champ, de sorte que sa présence permet de distinguer les deux sans lire le disque. Les fichiers rendus sont signalés exactement comme pour tout autre build, et ils sont toujours renvoyés en mémoire à moins que l’appel n’ait aussi reçu write — la résolution écrit le lockfile et le cache des artefacts, jamais un artefact.
Un espace de travail peut le demander de façon permanente, et un appel ne peut pas le désactiver. Le paramètre auto_pull propre à l’espace de travail active la même étape pour chaque build de cet espace, et auto_pull sur un appel s’ajoute à ce paramètre au lieu de le remplacer : l’un ou l’autre suffit, et aucun argument ne supprime une résolution que l’espace de travail a demandée. C’est de la même façon que le paramètre et aggrega build --auto-pull se combinent dans un terminal, de sorte qu’un espace de travail répond de la même manière quelle que soit la surface par laquelle arrive un build.
L’écartement est signalé au lieu d’être absorbé, et avec les fournisseurs qu’embarque ce binaire, un écartement arrête le rendu : le fournisseur qui a demandé la référence renvoie le refus, de sorte que l’appel répond par cet échec et ne renvoie aucun fichier. La référence est nommée là où un lecteur peut agir, à côté de la commande qui l’épingle : aggrega pull --release <path>. Le même épinglage est accessible sur cette surface sous la forme de l’outil pull, décrit plus bas dans Résoudre ce dont dépend une Release, de sorte qu’un assistant qui rencontre ce refus peut agir sans quitter le protocole. Un rendu entièrement épinglé ne dit rien de tout cela. Consultez aggrega pull pour savoir ce que l’épinglage télécharge et enregistre, et aggrega build, où une référence non épinglée est signalée et arrête l’exécution de la même manière.
Écrire les artefacts là où aggrega build les écrit
Envoyez write et le rendu terminé est aussi écrit dans dist/ à la racine de l’espace de travail, là où aggrega build l’écrit. Le répertoire est celui que compose la ligne de commande sous la même racine d’espace de travail, et l’écriture est celle qu’elle effectue, de sorte que pour une Release dans un espace de travail, aggrega build, la requête aggrega/build du serveur de langage ne nommant aucun outputParent et cet appel écrivent une seule arborescence, octet pour octet, et nomment ce répertoire de la même façon — la ligne finale de la commande, l’outputDirectory du serveur de langage et l’output_dir de cette réponse. Un dist qui est un lien menant hors de l’espace de travail est refusé avant que quoi que ce soit n’y soit supprimé ou écrit, comme dans un terminal. Omis, ce qui est la valeur par défaut, les artefacts sont renvoyés en mémoire et rien n’est écrit.
La racine de l’espace de travail est celle de l’appel lui-même. Sur l’entrée et la sortie standard, c’est la racine de l’espace de travail que l’appel a résolu, comme l’expose Dans quel espace de travail un appel reçoit sa réponse : la racine que nomme workspace_root, sinon la racine avec laquelle le serveur a été lancé, sinon l’espace de travail trouvé à partir du répertoire dans lequel le serveur a été démarré — et, lorsqu’une Release nommée par un chemin absolu déplace l’appel dans l’espace de travail propre à cette Release, la racine de cet espace. C’est la racine sous laquelle aggrega build écrit pour la même Release et la même racine nommée, de sorte que le dossier dans lequel le serveur s’exécute ne reçoit un dist que si ce dossier est la racine que l’appel a résolue, comme ce serait le cas dans un terminal ouvert à cet endroit. Sur HTTP, c’est l’espace de travail que sert le serveur, et rien n’est écrit en dehors de celui-ci.
L’écriture atteint l’espace de travail, elle exige donc sur HTTP aggrega:workspace-write. Un appel qui a reçu write atteint l’espace de travail pour cet appel, exactement comme un build qui résout d’abord ses dépendances : un identifiant ne portant que aggrega:read reçoit pour réponse 403 nommant aggrega:workspace-write, et rien n’est écrit, et un serveur dont mcp.deny_reach nomme workspace refuse l’appel en nommant ce paramètre. L’outil reste dans la liste d’outils de chaque appelant, et un build qui n’a pas reçu write reste disponible pour un appelant à portée de lecture seule.
Il écrit en dernier. Avec auto_pull également, l’appel résout, effectue le rendu puis écrit, dans cet ordre. Un appel refusé à un point antérieur quelconque — sa Release, son espace de travail, un répertoire de catalogue, la résolution, le rendu — n’écrit aucun artefact.
La réponse nomme ce qui a été écrit. output_dir est le répertoire — en entier sur l’entrée et la sortie standard, dist sur HTTP — et files liste chaque fichier écrit, relativement à celui-ci, avec son contenu sous response_format: detailed et son seul chemin sous concise ; le texte indique combien de fichiers ont été écrits et où. Un appel qui n’a pas reçu write ne porte aucun output_dir, de sorte que son absence vous indique que rien n’a été écrit. Une écriture qui échoue une fois le rendu terminé — dans une racine d’espace de travail où personne ne peut écrire, par exemple — répond par un échec nommant le répertoire et la cause, et ne liste aucun fichier comme écrit : une partie de l’écriture peut se trouver sur disque, et nommer les fichiers rendus comme écrits affirmerait plus que ce qui s’est produit.
Aucun argument ne nomme un répertoire, et aucun ne demande de trace. L’emplacement des artefacts est décidé par l’espace de travail que l’appel a résolu, jamais par l’appel, et un build écrit depuis ici ne laisse aucun répertoire .trace à côté de sa sortie ; un build tracé, c’est aggrega build --trace.
Ce qu’un build vous apprend en plus de ses fichiers
Un build porte chaque avertissement qu’il a émis, dans la réponse elle-même. Ce sont les constats qu’affiche aggrega build pendant qu’il travaille — un nom à une seule modification d’un nom déclaré, un paramètre que rien ne lit, une cible qui ne peut pas respecter un champ écrit par l’auteur, un verdict de gouvernance non bloquant, un répertoire de frontière qu’une Release a hérité de la Release qu’elle étend et qui se résout vers le même chemin, une propriété qu’un Component ou une Feature qu’atteint la Release déclare à la fois dans son pilier values et dans son pilier infra. Aucun d’eux ne change le résultat : un build qui porte des avertissements a tout de même réussi, et les fichiers qu’il renvoie sont les fichiers qu’il a produits. Ils arrivent dans l’ordre où un terminal les affiche, de sorte qu’un lecteur qui compare les deux trouve une seule séquence et non deux : d’abord tout ce qu’a émis le rendu, dans l’ordre où il l’a émis, puis les constats sur la Release et sur ce qu’elle atteint, qu’affiche aggrega build une fois le rendu terminé, et enfin, pour un build envoyé avec write, l’avertissement nommant chaque fichier que l’écriture a trouvé à côté des siens et qu’elle n’a pas écrit, et qu’elle laisse en place — celui qu’affiche aggrega build une fois ses fichiers écrits (Fichiers que le build n’a pas écrits).
Ils figurent dans la réponse et pas seulement dans le texte de synthèse parce qu’un assistant qui pilote cette surface ne lit aucun terminal, et qu’un constat dont personne n’est informé est un constat qui n’a pas été fait. Chacun porte une severity — warn pour quelque chose qui demande de l’attention, info pour une observation enregistrée — et un message ; un code là où sa classe en attribue un, afin que vous puissiez réagir à une condition précise sans comparer de texte ; et un key_path nommant la clé du document rédigé sur laquelle porte le constat, lorsqu’il porte sur une clé. Un constat sur la forme de la topologie déployée ne nomme aucune clé, parce que ses coordonnées sont celles du déploiement et non celles d’un document, et il indique plutôt dans son message ce qu’il concerne.
Deux sortes de constats qu’affiche un terminal atteignent cette réponse ailleurs que dans advisories, parce que chacune a un emplacement qui en dit davantage. Un marqueur de dépréciation enregistré se trouve dans deprecations, que le lockfile l’ait enregistré pour une référence épinglée ou que l’enregistrement de confiance des plugins situé à côté l’ait enregistré pour un plugin attaché dans un rôle qui renvoie un verdict d’acceptation ou de rejet. describe d’une Release nomme le même ensemble dans ses propres deprecations, et validate d’une Release parmi ses notices, chacun laissant le verdict tel quel ; un enregistrement de confiance présent mais illisible fait refuser l’un ou l’autre appel au lieu de passer pour un enregistrement qui ne consigne rien. Un parent dont hérite une entité et qui n’a pas pu être résolu arrête le build, il est donc nommé dans le texte du refus au lieu d’être listé comme un constat qui n’a rien changé. Une sorte est bornée par ce que cet outil charge plutôt que par ce que porte sa réponse : aggrega build charge chaque répertoire de catalogue configuré avant de résoudre une Release, et un avis concernant une forme de catalogue dépréciée proviendrait de ce chargement, alors que cet outil ne lit que ce qu’atteint la Release et n’effectue pas un tel chargement, de sorte qu’il ne signale aucun avis de ce genre. Aucun build n’en émet actuellement, donc les deux signalent les mêmes constats.
Une Release qui n’émet rien ne dit rien : la clé est absente plutôt que présente et vide, de sorte que sa seule présence vous indique qu’il y a quelque chose à lire.
Ce que renvoie un build refusé
Un build qui refuse répond dans les mêmes champs que ceux d’un build qui a réussi, remplis aussi loin que l’exécution est allée. Il revient marqué comme un échec, avec la correction pour texte, et la charge utile structurée se trouve à côté de ce texte au lieu d’être remplacée par lui. Un refus émis pendant le rendu de la Release se lit dans les termes du compilateur, comme le décrit plus bas Un refus émis pendant le rendu, et ajoute un champ qui lui est propre. Les avertissements y figurent : les phases qui se sont exécutées ont émis ce qu’elles ont émis, et ce sont les constats sur lesquels vous devez agir pour dépasser le refus, ils arrivent donc sous forme d’entrées que vous pouvez faire correspondre plutôt que de prose qu’il vous faudrait analyser. deprecations et declined_external_inputs y figurent pour la même raison — un marqueur enregistré est signalé parce qu’un marqueur a été enregistré, et une référence écartée parce qu’une référence a été écartée, et aucun de ces faits n’est une conséquence de la façon dont l’exécution s’est terminée.
files ne signale rien en cas de refus, et ce n’est pas le champ dans lequel lire le résultat. Rien n’a été émis, il n’y a donc aucun artefact à nommer. Ne vous fondez pas sur la présence de la clé : elle est signalée dans les deux cas, et un files vide ne peut pas à lui seul distinguer un build qui a refusé d’un build qui s’est exécuté sans rien émettre. Lisez l’indicateur d’échec du résultat — c’est le discriminant propre au protocole — et lisez files pour ce qu’il est, la liste de ce qui a été rendu, et aussi écrit lorsque l’appel a reçu write.
Ce qui borne les avertissements en cas de refus, c’est jusqu’où l’exécution est allée, et non ce que la réponse est capable de porter. Un refus issu d’un contrôle qui s’exécute avant que la Release ne soit résolue — une entrée épinglée dans le cache ne correspond plus à l’empreinte enregistrée pour elle et aucun répertoire de catalogue ne contient les octets épinglés, ou ce dont dépend la Release n’a pas pu être résolu — ne signale aucun avertissement, parce que rien n’avait encore été émis. Les constats sur la façon dont une Release se compose avec la Release qu’elle étend sont émis au moment où elle se résout, avant chaque contrôle qui suit, de sorte que chaque refus ultérieur les porte : le Manifest associe un type à une recette qui ne l’implémente pas, une entité qu’atteint la Release ne satisfait pas son schéma, le lockfile ne correspond plus à ce vers quoi la Release se résout. Les constats propres au rendu sont émis à mesure que le rendu s’exécute, de sorte qu’un refus issu de l’un de ces contrôles antérieurs n’en porte aucun, et qu’un refus issu du rendu porte tout ce qui a été émis avant lui. Lisez donc advisories en cas de refus exactement comme vous le lisez en cas de succès : ce que cette exécution a trouvé, dans l’ordre où un terminal l’affiche.
Un refus dû à une entité qui hérite d’un parent qui n’a pas pu être résolu nomme chacun de ces héritages dans son texte, dans les termes que aggrega build affiche pour lui, afin que vous sachiez lequel réparer. Ce détail est la raison pour laquelle le build s’est arrêté, c’est pourquoi il figure dans le texte et non parmi les constats qui n’ont rien changé ; les constats de composition émis avant lui se trouvent dans advisories comme pour tout refus ultérieur.
Un répertoire de catalogue que lit la Release et qui ne peut pas être parcouru est refusé avant que quoi que ce soit ne soit écrit, comme le refuse aggrega build. Il s’agit d’un répertoire que l’appel nomme dans catalog_dirs et qui n’existe pas, comme aggrega build refuse un répertoire --catalog qui n’existe pas, ou d’un répertoire qui existe mais ne peut pas être lu. aggrega build charge chaque répertoire que lit la Release avant de résoudre la Release, et s’arrête sur un répertoire qu’il ne peut pas parcourir ; build parcourt d’abord les mêmes répertoires, sans y lire aucun document, avant toute résolution des dépendances et avant le rendu — de sorte qu’un build qui a reçu auto_pull n’écrit aucun lockfile, et rien n’est rendu. Le texte nomme le répertoire comme le signale la ligne de commande, sur une ligne : le répertoire, catalog load et la raison donnée par le système de fichiers. La charge utile nomme la Release, avec un files vide et aucun constat, parce que rien ne s’était exécuté. Un répertoire que liste la configuration de l’espace de travail et qui n’est pas un répertoire — rien n’existe à cet endroit, par exemple — est refusé avant ce parcours, sous la même forme, le texte portant le refus que lui oppose aggrega build, en nommant l’entrée ainsi que le fichier de configuration et la ligne qui la listent (D’où sont lues les entités locales). Un répertoire de catalogue contenant un lien qui mène hors du répertoire dans lequel ses lectures doivent rester est refusé au même moment, sans que rien ne soit écrit, le texte nommant le lien et l’endroit où il mène — aggrega build le refuse de la même façon.
Un exemple concret, pour que les deux moitiés soient tangibles. Une Release déclarant un paramètre qu’aucune référence ne lit, et dont le rendu ne peut ensuite pas aboutir, revient sous la forme d’un échec dont le texte porte le refus du rendu et dont la charge utile porte l’avertissement de paramètre non lu avec ses severity, message, code et key_path — la même entrée, avec les mêmes valeurs, que la même Release signale dans la réponse lorsque le rendu aboutit — à côté de l’entrée refusal pour ce qui a arrêté le rendu. Une Release qui en étend une autre et hérite d’un répertoire de frontière ne comportant aucune variable de modèle, et dont le Manifest associe un type à une recette qui ne l’implémente pas, revient sous la forme de ce refus avec une entrée advisories par répertoire hérité, chacune avec le code inherited-boundary-directory-is-literal. Une Release dont les dépendances ne peuvent pas être résolues, dans un espace de travail dont les répertoires de catalogue listés existent tous, revient sous la forme d’un échec sans aucune clé advisories, parce que rien n’avait été émis lorsqu’elle s’est arrêtée.
Un refus émis pendant le rendu
Une Release que le compilateur refuse pendant le rendu — un Workload nommant un slot que son Component ne déclare pas, une assertion qui échoue, un modèle qui ne peut pas être évalué — revient avec le refus dans les termes du compilateur et avec chaque cause en dessous, les termes que cli-build renvoie pour la même Release : le nœud en cours de rendu, puis ce qui, en lui, a refusé. Lorsque le refus nomme une condition enregistrée, le texte ajoute le nom de cette condition — le code court et le code descriptif sur lesquels faire correspondre —, comme le ferait explain-error. Le texte commence par indiquer quelle étape a refusé : The build failed during rendering; nothing was written to disk. pour un refus émis par le rendu, et The build refused before rendering anything; nothing was written to disk. pour un refus émis par l’exécution du compilateur avant tout rendu — la composition du graphe sur lequel travaille le rendu qui refuse, ou une assertion que déclare un Component ou une Feature.
La charge utile porte le même refus sous la forme d’une seule entrée, refusal, de sorte qu’un appelant qui doit modifier un document lit lequel, et où, sans analyser la phrase :
file— le document que désigne le refus : la Recipe d’un Workload, la Recipe ou la FeatureRecipe déclarant une assertion qui échoue, la Release ou l’Aggregate qui a écrit une entrée que refuse la composition du graphe, ou l’Aggregate de la Release pour un refus qui ne désigne aucun document.key_path— la clé dans ce document, lorsque le refus en nomme une :.spec.workloadpour un refus concernant un Workload, la clé propre de l’assertion sous.spec.assertionspour une assertion qui échoue, la clé propre de l’entrée pour le refus d’une entrée. Un refus concernant un Workload est placé sur sa cléworkloadet pas plus finement, parce que le Workload que juge un contrôle est ce que son modèle a produit, et qu’un modèle écrit des lignes que son auteur n’a jamais écrites ; les chemins que le refus nomme à l’intérieur de ce Workload rendu restent dans sonmessage.lineetcolumn— la position de cette clé, comptée à partir de un, la colonne en unités UTF-16. Absents lorsque le refus ne nomme aucune clé ou que le document ne la contient pas : une position n’est donnée que là où une position a été trouvée.severity—halt, la gravité du constat qui a arrêté un build.codeetshort_code— les deux identifiants de la condition, lorsque le refus nomme une condition enregistrée.message— le texte du refus, exactement tel qu’il apparaît dans le texte de la réponse.findings— présent uniquement lorsque le refus réunit plusieurs constats, comme le fait la composition du graphe avec chaque violation qu’elle a trouvée : une entrée par constat, dans l’ordre où le refus les énonce, chacune de cette même forme — avec ses propresfile,key_path,line,column,severity,code,short_codeetmessage. Les champs propres au refus nomment alors l’endroit que désigne son premier constat, et sonmessageporte chaque constat, comme le texte ; la ligne de commande affiche chaque constat comme un diagnostic à part entière.
L’entrée est présente chaque fois que l’exécution propre du compilateur a refusé — pendant le rendu, ou avant celui-ci : à la composition du graphe, ou à une assertion que déclare un Component ou une Feature, qui ne nomme aucun document, de sorte que son entrée nomme l’Aggregate. Un build qui réussit n’en porte aucune, pas plus qu’un build refusé par un contrôle qui s’exécute avant le démarrage du compilateur — le lockfile, les correspondances du Manifest, ce dont dépend la Release —, dont le refus est le texte seul. Une valeur qu’un auteur a déclarée sensible est retenue hors du refus là où le compilateur l’émet, de sorte que l’entrée et le texte portent ce que portent cli-build et le terminal — voir ce que dit un refus d’une valeur déclarée.
Résoudre ce dont dépend une Release
pull résout les dépendances de catalogue et de source d’une Release dans le cache local et écrit le lockfile de cette Release. Il figure sur cette surface pour une raison qui mérite d’être énoncée : les deux refus décrits plus haut — un rendu qui a écarté une référence externe non épinglée, et un build qui s’est arrêté parce que le lockfile ne correspond plus à ce vers quoi la Release se résout — trouvent tous deux leur réponse dans l’épinglage, et un assistant qui doit vous demander d’exécuter une commande n’a aucun moyen d’y répondre lui-même. Lisez Ce qu’un assistant peut faire sans vous demander d’abord pour savoir ce qu’il écrit et jusqu’où cela va.
Passez release, le chemin de la Release, absolu ou relatif à la racine de l’espace de travail — le même contrat que celui qu’utilise chaque autre argument de chemin ici. workspace_root et catalog_dirs remplacent la détection de l’espace de travail et du catalogue exactement comme sur build. Tous deux valent sur un serveur atteint par l’entrée et la sortie standard ; sur HTTPS, ces deux arguments sont refusés et le chemin doit se résoudre à l’intérieur de l’espace de travail que sert le processus, comme l’expose Un processus, un espace de travail.
Par défaut, il réconcilie au lieu de résoudre à nouveau. Un épinglage que le lockfile enregistre déjà est respecté et téléchargé à cette version, et refusé au lieu d’être épinglé à nouveau en silence si le registre ne sert plus ces octets. Une référence sans épinglage — ajoutée récemment, ou retirée du lockfile à la main — est résolue à neuf et ajoutée. Une référence qui ne figure plus parmi les dépendances résolues est élaguée. Un ensemble de dépendances inchangé laisse donc le fichier identique octet pour octet, horodatage enregistré compris, de sorte qu’un appel qui n’a changé aucun épinglage ne produit aucune différence pour quiconque examine ensuite l’espace de travail.
verify compare, et laisse le lockfile tel quel. Il vérifie le lockfile enregistré par rapport à la résolution qu’effectuerait maintenant l’appel de réconciliation décrit plus haut, en respectant les épinglages enregistrés exactement comme le fait cet appel, et revient sous la forme d’un échec en cas de dérive, ou lorsqu’il n’y a aucun lockfile à comparer — c’est donc ainsi qu’un assistant découvre si un épinglage est nécessaire avant que quoi que ce soit ne réécrive le lockfile. Rien de ce qu’enregistre cet appel n’est écrit — ni le lockfile, ni les identités de plugins enregistrées à côté, ni un entity.lock —, tandis que le cache de contenu est lu et rempli exactement comme cet appel le lit et le remplit. Il signale aussi la chaîne d’outils qu’enregistre le lockfile : la version du compilateur qui a écrit le fichier et la version de chaque plugin principal qu’embarquait ce compilateur. Cela est signalé à des fins d’audit et jamais comparé au binaire en cours d’exécution, parce que la chaîne d’outils ne fait pas partie de ce qu’épingle le lockfile et que la vérifier épinglerait le compilateur par procuration — une différence de chaîne d’outils n’est pas une dérive.
upgrade_targets résout à nouveau les références que vous nommez, et rien d’autre. Donnez-lui un ou plusieurs URI d’entité sous la forme rédigée nue — core/database, et non une forme versionnée. Chaque épinglage nommé est abandonné et résolu à nouveau vers la version la plus élevée disponible, tandis que chaque autre épinglage et les entrées externes enregistrées restent inchangés. Un URI qui ne correspond ni à un épinglage enregistré ni à une pièce jointe configurée est refusé au lieu d’être ignoré.
Il n’existe délibérément aucun argument qui résout à nouveau tout d’un coup. La ligne de commande dispose de cette forme, et elle abandonne le lockfile entier avant de résoudre à nouveau à partir de l’état actuel du registre. Sur cette surface, l’argument n’existe pas, de sorte que l’appel ne peut tout simplement pas être composé, au lieu d’être accepté puis refusé : personne n’observe un flux de protocole, donc un abandon global n’a personne pour le confirmer. Si vous le voulez, et sur l’entrée et la sortie standard uniquement, cli-pull exécute la commande, et c’est la surface où une personne est présente ; un appelant qui atteint ce serveur par HTTP l’exécute plutôt dans un terminal sur l’hôte. verify ne peut pas être combiné avec upgrade_targets — l’un laisse le lockfile tel quel et l’autre le réécrit — ni avec pin_sources, quelle que soit sa valeur : cet argument décide si une résolution enregistre les épinglages qui manquent à un entity.lock ou refuse à cause d’eux, et une comparaison n’écrit aucun entity.lock, elle ne ferait donc ni l’un ni l’autre. Un appel envoyant l’une ou l’autre paire est refusé avant que quoi que ce soit ne soit résolu, avec une phrase nommant la paire. Le schéma annoncé de l’outil n’énonce pas ces deux exclusions, parce qu’un client qui en affiche une peut la lire comme une obligation d’envoyer verify ; c’est le refus qui les fait connaître à un client. La ligne de commande et le démon refusent les mêmes paires.
Le résultat nomme ce qui a été résolu, et pas seulement le fait que quelque chose l’a été. Il porte le lockfile qu’il a écrit ou auquel il a comparé ; resolved, chaque référence atteinte par la résolution avec la version vers laquelle chacune s’est résolue, le type qu’écrit un auteur lorsque la résolution en enregistre un, et sa source — l’endroit où cette exécution a pris la référence, dans le mot qu’affiche aggrega pull --detail pour la même résolution : fetched-fresh, cache-reuse, local, in-binary ou external ; les décomptes des artefacts sources, des entrées externes et des identités de plugins de confiance que contient ensuite le lockfile ; et diagnostics, le compte rendu que la résolution fait d’elle-même dans l’ordre où elle a émis chaque ligne — quel épinglage a été réutilisé, quelle signature a été vérifiée, quelle version a été ignorée parce que retirée. Ces lignes parviennent à un terminal lorsque vous exécutez la commande ; ici, elles figurent dans la réponse, parce qu’un appelant qui ne lit aucun terminal n’a pas d’autre moyen de les recevoir. verified n’est présent que lors d’une comparaison, de sorte que son absence permet de distinguer une exécution qui a écrit d’une exécution qui a seulement comparé. Une source décrit cette exécution sur cette machine, de sorte que le lockfile ne l’enregistre pas, et describe, qui indique ce dont dépend une Release, n’en nomme aucune.
Un refus répond dans les mêmes champs, remplis aussi loin que l’exécution est allée. Une fois la résolution calculée, resolved est porté quel que soit le verdict — un verdict de dérive plus que tout autre, puisque c’est le refus au sujet duquel un appelant doit décider quoi changer. Un refus antérieur à ce point, comme un chemin de Release qui ne se résout pas, porte la correction pour texte et aucune résolution, parce qu’il n’y en avait aucune à porter.
Lorsque les épinglages sont complets et que les entrées externes ne le sont pas, l’appel réussit tout de même et le dit. Découvrir quelles entrées externes consomme une Release est un rendu, et un rendu peut échouer alors que les épinglages des dépendances sont déjà corrects et sur disque. Signaler l’appel entier comme un échec vous dirait de refaire un travail qui est correct, c’est pourquoi incomplete_external_inputs est plutôt défini sur le résultat réussi, en nommant ce qui s’est arrêté : les épinglages des dépendances sont complets, ceux des entrées externes peuvent ne pas l’être.
C’est l’outil le plus lent ici, et la réconciliation sans changement n’est pas un chemin rapide. Une résolution paie son coût complet pour établir qu’un ensemble de dépendances est inchangé, de sorte qu’un appel qui ne réécrit rien coûte autant qu’une première résolution — sur une petite Release, des secondes plutôt que des millisecondes, et cela croît avec la taille de l’ensemble de dépendances. Un verify est la moins coûteuse des deux formes, parce qu’une comparaison saute la descente dans les sources de chaque composant qu’effectue une exécution qui écrit. Si votre client impose un délai d’expiration par appel, c’est l’outil sur lequel le vérifier. Demander à être informé de l’avancement, ci-dessous, signifie que quelque chose arrive pendant que l’appel s’exécute au lieu de rien jusqu’à sa fin — ce qui répond à un délai d’inactivité dans votre client, ou dans tout ce qui se trouve entre vous et un serveur atteint par HTTP, mais pas à un plafond sur la durée totale d’un appel.
Une entité dont l’entity.lock n’enregistre aucun épinglage pour une entrée qu’elle lit refuse le pull, et le refus nomme l’étape qui l’enregistre. Une Recipe ou une FeatureRecipe que la Release construit à partir de vos répertoires de catalogue et qui lit une source distante écrite en entier, ou importe un fichier par ses artefacts, est censée porter déjà ces épinglages à côté d’elle — son auteur les enregistre avec pin, ci-dessous. pin_sources demande à cet appel d’exécuter cette étape au nom de l’auteur sur chacune de ces entités au lieu de refuser, en écrivant l’entity.lock à côté de chacune ; c’est la même étape qu’exécute l’outil pin, et elle écrit les mêmes octets. Omettez-le et c’est le pin_sources_at_pull de l’espace de travail qui décide ; envoyez-le et il décide dans un sens comme dans l’autre, de sorte que pin_sources: false refuse même dans un espace de travail configuré pour épingler. Une entité que la résolution a atteinte dans le cache plutôt que dans l’un de vos répertoires de catalogue n’a ici aucun emplacement inscriptible et n’est jamais épinglée par cet appel.
Épingler les entrées propres à une entité
pin enregistre, dans l’entity.lock à côté d’une Recipe ou d’une FeatureRecipe, l’épinglage de contenu de chaque entrée que l’entité lit hors de son propre document : une source distante dont les coordonnées sont écrites en entier, et un fichier qu’importe une entrée d’artefacts. C’est la même étape qu’exécute aggrega pin dans un terminal, et le verrou qu’elle écrit est identique octet pour octet à celui qu’écrit cette commande. Passez entity, le document de l’entité, absolu ou relatif à la racine de l’espace de travail selon le même contrat que chaque autre argument de chemin ici ; sur HTTPS, il doit se résoudre à l’intérieur de l’espace de travail que sert le processus.
Aucune Release n’est nommée, parce qu’aucune n’est nécessaire. Une source dont les coordonnées ne portent aucun modèle nomme un seul artefact pour chaque Release qui utilise l’entité, de sorte que l’étape la résout et l’épingle sans rien que fournisse une Release. Une source dont les coordonnées proviennent d’un modèle n’est pas épinglée ici : l’artefact qu’elle nomme est décidé par chaque Release, et pull épingle chaque identité vers laquelle elle se résout dans le lockfile de cette Release.
Le résultat dit ce que l’étape a fait au verrou. Il porte l’entity, son kind et son name, ainsi que pinnable, qui vaut false pour un type qui ne lit rien de ce qu’enregistre un verrou — un Component ou une Feature —, auquel cas rien à côté de l’entité n’a été touché et les autres champs sont absents. Sinon, il porte le lock qu’il a écrit, changed, qui vaut false lorsque le verrou enregistrait déjà chaque épinglage et a été laissé identique octet pour octet, removed lorsque l’entité ne lit désormais rien de ce qu’enregistre un verrou et que son verrou a été supprimé, et pins, une entrée par classe d’épinglage avec le décompte que contient ensuite le verrou. dry_run répond avec le verrou que l’étape écrirait sous forme de content et n’écrit rien à côté de l’entité ; le cache de contenu se remplit tout de même, parce que les entrées sont résolues exactement comme elles le seraient autrement.
Il écrit à l’intérieur de l’espace de travail et atteint les hôtes que nomment les sources de l’entité — un dépôt de charts, un hôte Git, une URL —, de sorte que sur HTTP il est admis pour un identifiant portant la portée qui admet pull, et refusé pour un identifiant qui ne peut que lire. Sur l’entrée et la sortie standard, la même capacité est aussi accessible sous la forme de cli-pin, qui exécute la commande ; sur HTTP, cet outil n’existe pas.
Être informé de l’avancement d’un appel long
Un appel signale son avancement lorsque vous demandez à en être informé, et le demander tient en un seul champ. Placez progressToken dans le _meta de l’appel — une chaîne ou un nombre, à votre choix. Il revient dans chaque signalement exactement tel que vous l’avez écrit, et c’est la seule chose d’un signalement qui renvoie à votre appel : un signalement ne répond à rien, il ne porte donc aucun identifiant. N’envoyez aucun jeton, ou envoyez-le à null, et rien ne change — l’appel reçoit la même réponse que sans jeton. Un jeton de toute autre forme est refusé, avant que l’appel ne fasse quoi que ce soit, en nommant les deux formes qu’il peut prendre au lieu d’être ignoré : un appelant qui a demandé à être informé et se heurte ensuite au silence n’a rien sur quoi agir.
Ce qui arrive est notifications/progress, portant votre jeton et un compteur qui augmente à chaque signalement. Il n’y a ni total ni message, et aucun des deux n’est une omission en attente de travail : ce que le travail signale, c’est qu’il est entré dans une autre phase, de sorte qu’un total ne pourrait qu’être inventé et qu’une phrase ne pourrait qu’être composée ici au lieu d’être transmise. Dessinez un indicateur indéterminé à partir du compteur croissant ; il n’y a aucune fraction avec laquelle remplir une barre.
Sur HTTP, la réponse devient un flux d’événements, et seulement une fois que quelque chose a effectivement été signalé. Elle est servie en text/event-stream, marquée comme ne devant pas être mise en cache, et porte X-Accel-Buffering: no pour un intermédiaire qui, sinon, retiendrait chaque événement jusqu’à la fin du travail et transformerait le flux en une seule réponse lente. Chaque signalement est un événement, et la réponse propre de l’appel est le dernier événement avant la fermeture du flux. Tant que le travail est silencieux, le flux porte à intervalles une ligne de commentaire, qui atteint tout ce qui se trouve entre les deux sous forme d’octets sur une connexion active et n’atteint votre client sous aucune forme. Un appel qui a demandé l’avancement et qui a atteint un travail qui n’en signale aucun reçoit tout de même pour réponse un seul objet JSON, parce que ce qui ouvre le flux est le premier signalement et non le jeton.
Sur un flux, lisez le résultat dans ce dernier événement plutôt que dans le code d’état. L’état et les en-têtes sont écrits à l’ouverture du flux, c’est-à-dire avant que le travail ne soit terminé, de sorte qu’un appel qui signale puis refuse porte son refus comme dernier événement sous l’état déjà envoyé. Fermer la connexion en cours de flux met fin au travail et rien d’autre n’est écrit pour lui, exactement comme Comment un appel se termine le décrit pour tout autre appel.
Sur l’entrée et la sortie standard, les signalements sont des lignes qui précèdent la ligne de réponse, encadrées comme tout autre message de ce flux — un objet JSON par ligne, dans l’ordre où ils ont été écrits —, et la ligne de réponse les suit. Rien n’est signalé une fois qu’un appel est terminé, sur aucun des deux transports.
La résolution des dépendances d’une Release est ce qui signale ici. pull signale chaque fois que la résolution entre dans une phase. build ne signale que lorsqu’il résout d’abord — parce que vous avez envoyé auto_pull, ou parce que le paramètre propre à l’espace de travail demande à chaque build qui s’y trouve de résoudre —, puisque le signalement appartient à cette étape : un build qui effectue le rendu à partir des épinglages qu’il détient déjà n’atteint rien et ne signale rien, de sorte qu’un jeton sur cet appel ne change rien à la façon dont il reçoit sa réponse. Tout appel signale aussi chaque étape dans laquelle entre son travail et qu’il attend — la lecture d’un registre, la récupération d’un artefact ou d’un paquet de documentation, la première compilation d’un plugin —, les étapes que la ligne de commande affiche à une personne à côté de son indicateur d’activité. Un appel dont le travail n’attend aucune de ces étapes ne signale rien, ce qui est inoffensif et non une erreur : la réponse est celle que vous auriez reçue sans jeton.
Demander quelle connexion est écrite à un endroit d’un document
connection-at-position répond à la question qui précède le volet connexion des deux outils ci-dessus, lorsque vous disposez d’un endroit dans un document plutôt que d’un nœud dans un graphe — une ligne que vous regardez dans un Aggregate ou une Release. Transmettez file, le document, relatif à la racine de l’espace de travail ou absolu et lu depuis le disque de la même manière que insertion-point en lit un ; position, une line et un character tous deux comptés à partir de zéro, mesurés dans les unités que nomme position_encoding, exactement comme insertion-point lit cet argument ; et release, la Release dont le graphe compilé enregistre les connexions. La Release est requise aussi pour un endroit dans l’Aggregate : un nœud du graphe et une connexion n’existent que sur un graphe compilé.
La réponse est l’une de deux moitiés. Lorsque l’endroit se trouve sur l’entrée d’une connexion, elle porte graphNode et connection — son socket, son alias et le document dans lequel l’endroit a été lu —, qui sont exactement ce que attach-candidates accepte à côté de graph_node et release, et ce que attachment-container accepte pour indiquer où va un rattachement sur cette connexion ; ce conteneur se trouve à l’intérieur de l’entrée même où tombait l’endroit. Sinon, elle porte noConnectionReason, issu d’un ensemble fermé : no-connection-entry (l’endroit ne se trouve sur aucune entrée dans laquelle s’écrit un rattachement), feature-created-connection (l’endroit se trouve sur l’entrée de la Release pour une connexion tracée par une Feature) ou unknown-connection (l’endroit se trouve sur une entrée que la Release écrit pour une connexion que le graphe compilé ne porte pas). La réponse lisible énonce la raison en toutes lettres.
Un endroit situé n’importe où dans une entrée se trouve dans celle-ci — sur l’alias, sur son target, dans ses features — et, là où des entrées s’imbriquent, c’est la plus interne qui l’emporte. Un endroit sur la clé même d’un socket, au-dessus des alias qu’elle contient, ne se trouve dans aucun d’eux. Les entrées sont celles qu’enregistre le graphe compilé : dans l’Aggregate, chaque connexion que trace un composant, à son entrée sous l’alias de la connexion dans le document où le composant a été rédigé, qui, pour un composant fourni par un module importé, est le document propre de ce module ; dans la Release, chaque entrée par arête qu’elle écrit. Une connexion écrite sous forme de liste de cibles, et une connexion tracée par le bloc de dépendances propre d’une Feature, ne portent aucune entrée dans laquelle s’écrit un rattachement. Le fait qu’une clé soit une connexion ne se déduit jamais de son nom.
Il répond et s’arrête. Il n’écrit rien dans aucun fichier. Un document qui n’est pas dans l’espace de travail, ne peut pas être lu ou n’est pas du YAML bien formé revient sous forme de résultat en échec indiquant ce qu’il faut changer, comme avec insertion-point ; il en va de même pour un endroit auquel manque sa line ou son character, et pour un position_encoding hors des trois valeurs.
Demander dans quel conteneur va un rattachement
attachment-container répond à la question qui se pose entre une réponse de candidature et un point d’insertion. Vous avez établi ce que vous rattachez à un nœud ; avant de pouvoir demander où l’écrire dans un fichier, vous devez savoir quel fichier et quel conteneur à l’intérieur. Transmettez graph_node — un identifiant de nœud sur un graphe compilé, tel que le graphe l’utilise comme clé — et release, la Release à laquelle appartient le graphe. Les deux sont requis : un identifiant de nœud est une clé du graphe d’une Release et ne signifie rien sans elle.
N’assemblez pas ce chemin vous-même. L’identifiant d’un nœud et le chemin du sous-système qui l’englobe s’écrivent tous deux avec des points entre leurs parties, et le point est un caractère autorisé dans un nom saisi par un auteur — de l’extérieur du document, il est donc impossible de distinguer un point structurel d’un point situé dans un nom. Un chemin que vous auriez composé se lirait correctement et adresserait une clé que personne n’a écrite, et la modification qui suivrait créerait cette clé au lieu d’être refusée. Pire encore, un identifiant de nœud ne porte aucune trace de son sous-système englobant : un composant rédigé dans subsystems.billing.subsystems.payments a pour clé ledger, exactement comme un composant de premier niveau. Demandez le conteneur.
La réponse porte node, le nœud concerné ; file, le document dans lequel ce nœud a été rédigé ; et container, le chemin structurel depuis la racine de ce document sous forme de liste de segments — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. C’est délibérément une liste plutôt qu’une chaîne jointe : un chemin joint devrait être redécoupé par celui qui le reçoit, ce qui réintroduirait l’ambiguïté décrite ci-dessus un appel plus tard. Transmettez file et container tels quels à insertion-point.
file fait partie de la réponse plutôt que d’être quelque chose que vous savez déjà. Un nœud fourni par un module importé a été rédigé dans le document propre de ce module sous le nom que le module lui a donné, de sorte que le fichier et le dernier segment du conteneur diffèrent tous deux de tout ce que vous avez envoyé.
Pour un rattachement sur une connexion que trace le nœud, ajoutez connection avec son socket, son alias et son document, requis ici parce que l’un ou l’autre document peut en contenir une. Avec aggregate, la réponse est l’entrée propre de la connexion dans le document où le nœud a été rédigé, avec son bloc features en dernier ; une connexion tracée par la Release n’y a pas d’entrée et est refusée. Avec release, c’est l’entrée par arête sous l’entrée de la Release pour le nœud — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] —, indiquée que la Release écrive déjà cette entrée par arête ou non, de sorte que insertion-point nomme les clés restant à écrire ; une Release qui n’écrit aucune entrée pour le nœud est refusée, car ce n’est pas à cet outil de décider où le nœud est placé. Une connexion tracée par une Feature est refusée dans les deux documents.
Il répond et s’arrête. Il ne crée aucun rattachement, n’écrit rien dans aucun fichier et ne compose aucun texte. Il ne statue pas non plus sur ce qui peut être rattaché — c’est le rôle de attach-candidates. Un nœud que le graphe ne porte pas, ou un nœud pour lequel il n’enregistre aucun document, revient sous forme de résultat en échec indiquant ce qu’il faut changer plutôt que sous forme de réponse avec un champ vide.
Localiser l’emplacement d’une entrée dans un document
insertion-point répond à la question qui suit une réponse de candidature. Vous avez établi ce que vous rattachez ou connectez ; il vous faut maintenant savoir où l’écrire dans le fichier. Il renvoie une position et les colonnes d’indentation, pour que vous puissiez appliquer la modification sans analyser vous-même le document. Comme ce qu’il lit est la structure propre d’un document plutôt que la forme d’un type particulier, describe-capabilities l’indexe sous n’importe quel type d’entité auquel vous vous restreignez.
Transmettez file — le document, relatif à la racine de l’espace de travail ou absolu, et à l’intérieur de l’espace de travail : un document atteint par un lien menant hors de celui-ci, vers le fichier ou vers un répertoire en chemin, ne l’est pas, et il est refusé sur les deux transports — et container, le chemin structurel depuis la racine du document jusqu’au conteneur dans lequel va l’entrée, chaque élément étant une clé de mapping ou une position de séquence écrite en décimal.
C’est à vous de fournir le chemin du conteneur. L’outil lit la structure du document et ne déduit jamais où va quelque chose d’après son nom, le type qu’il porte ou ce qu’il semble signifier. Vous dites quelle clé ; il dit où vont les entrées de cette clé dans ce document — quels segments du chemin le fichier porte déjà, les colonnes où se trouvent ses entrées et la dernière ligne qu’atteint son bloc le plus interne. Pour le rattachement d’une Feature à un nœud d’un graphe compilé, vous n’avez pas à connaître vous-même cette clé : attachment-container, ci-dessus, indique le document et le conteneur, et tous deux se transmettent ici tels quels.
La réponse est une position de largeur nulle, dont la line et le character comptent tous deux à partir de zéro ; entryIndent et indentStep, les colonnes auxquelles écrire ; et missingContainerKeys, les clés de conteneur que ce document ne porte pas encore, la plus externe en premier, que vous écrivez avant l’entrée. entryShape indique si le conteneur contient un mapping ou une sequence, et indique unknown lorsque le conteneur n’existe pas encore ou ne contient rien, parce que le document ne l’a pas dit — la forme est alors à votre choix. indentStepMeasured indique si le pas a été mesuré à partir de l’imbrication propre de ce document ou s’il s’agit d’une valeur de repli pour un document qui n’en présente aucune. Lorsque precededByLineBreak est défini, commencez votre texte par un saut de ligne : la position se situe à la fin de la ligne que suit l’entrée, ce qui est valide que le fichier se termine ou non par un saut de ligne et ne perturbe aucun octet déjà écrit. Lisez missingContainerKeys même lorsque vous vous attendez à ce que le conteneur existe — une position appliquée sans les clés qui doivent la précéder produit un document qui ne s’analyse plus.
position_encoding nomme les unités dans lesquelles est mesuré le décalage de caractère indiqué : utf-8, utf-16 ou utf-32. C’est ici un argument parce qu’aucune des deux révisions de ce protocole n’en négocie un, et sa valeur par défaut est utf-16, ce qu’adopte une session d’éditeur lorsqu’un client ne négocie rien — ainsi, un appelant qui ne nomme rien reçoit la même réponse sur les deux surfaces. Une valeur qui n’est aucune des trois est refusée plutôt que remplacée silencieusement par la valeur par défaut, car des décalages mesurés d’une façon et appliqués dans un tampon mesuré d’une autre corrompent le document au premier caractère hors ASCII.
Il répond et s’arrête. Il n’écrit rien dans aucun fichier, ne compose aucun texte d’entrée et n’applique aucune modification ; composer le texte et décider de l’appliquer vous reviennent. Une requête qui n’adresse pas un endroit où une entrée peut aller revient sous forme de résultat en échec indiquant ce qu’il faut changer — un document qui n’est pas dans l’espace de travail, ne peut pas être lu ou n’est pas du YAML bien formé ; un chemin de conteneur sans segment ou avec un segment vide ; un chemin passant par un scalaire, à l’intérieur duquel rien ne peut être ajouté ; un chemin atteignant une collection écrite en style flow, où ajouter réécrirait des octets que l’auteur a déjà écrits au lieu d’ajouter une ligne ; ou un chemin adressant une séquence en bloc avec quelque chose qui n’est pas l’un de ses indices. Si vous préférez que la modification soit appliquée plutôt que de l’appliquer vous-même, Appliquer une modification délimitée à un document est l’outil qui s’en charge.
Appliquer une modification délimitée à un document
edit-document applique ce que localisent les deux outils ci-dessus. Un appel ajoute une entrée sous un conteneur, ou définit un scalaire, et ne peut rien faire d’autre. Il écrit le document que vous nommez, à l’intérieur de l’espace de travail, donc sur HTTPS il nécessite aggrega:workspace-write : un appelant qui ne détient que aggrega:read le trouve dans la liste des outils, et un appel qu’il effectue est refusé en nommant cette portée.
Nommez la modification dans edit ; l’ensemble est fermé. add-component ajoute une instance de composant sous un conteneur de composants ; attach-feature rattache une Feature au nœud que vous nommez ; wire-edge câble une connexion dans l’un des sockets de ce nœud ; set-value définit une valeur sur ce nœud. Un nom hors de ces quatre est refusé plutôt qu’interprété. Aucune modification ne supprime, ne remplace un bloc que vous avez déjà écrit, ne réordonne quoi que ce soit ni n’écrit telles quelles des octets que vous fournissez — ce n’est donc pas un outil d’écriture de fichiers et il ne peut pas être utilisé comme tel.
Transmettez file, le document — relatif à la racine de l’espace de travail ou absolu, et à l’intérieur de l’espace de travail : un document situé hors de celui-ci, tel qu’écrit ou par un lien qui en sort, est refusé sur les deux transports sans que rien soit lu ou écrit ; node, le chemin structurel depuis la racine du document sous forme de liste de segments ; name, la clé sous laquelle l’entrée est écrite ; et value, ce que porte cette entrée. node est une liste pour la même raison que attachment-container répond par une liste : un point est autorisé dans un nom saisi par un auteur, de sorte qu’un chemin joint pourrait adresser une clé que personne n’a écrite et que l’entrée y serait créée au lieu d’être refusée. Pour add-component, le chemin nomme le conteneur de composants lui-même, car l’entrée ajoutée est le nœud ; pour les trois autres, il nomme le nœud concerné par la modification, et le conteneur découle de la modification. socket est lu pour wire-edge et ignoré sinon. Ce que signifie value découle de edit — l’entité que demande l’entrée, le nœud vers lequel pointe une connexion ou le scalaire auquel une valeur est fixée — et c’est une valeur JSON de son propre type : un nombre reste un nombre, un chiffre entre guillemets reste du texte, et l’omettre ne définit rien du tout. Un mapping ou une séquence est refusé, car écrire un bloc ne fait pas partie de ces modifications.
Chaque octet que la modification ne touche pas est préservé. Le document n’est analysé que pour localiser le conteneur et la ligne où se termine son bloc, de sorte que commentaires, lignes vides, style de guillemets, scalaires pliés et littéraux et forme du saut de ligne final sont tous conservés, et le pas d’imbrication est mesuré à partir de l’indentation propre du document plutôt qu’imposé. La même requête sur le même document produit les mêmes octets.
Le résultat doit être un document que vous auriez pu saisir vous-même, et c’est à cette condition qu’est subordonnée l’écriture. Le document composé est vérifié par rapport au schéma de son propre type et n’atteint le disque que si cette vérification réussit. Une requête qui produirait quelque chose que le schéma refuse est refusée, en nommant la propriété que le schéma n’admettrait pas et son emplacement, et le fichier reste octet pour octet tel qu’il était — une modification refusée est donc impossible à distinguer d’une modification jamais tentée, et vous pouvez relancer une requête corrigée sur le document de départ. Une entrée déjà présente qui porte ce que vous avez demandé est sans effet ; une entrée de ce nom qui porte autre chose est refusée plutôt que remplacée.
La réponse porte container, le chemin structurel où l’entrée a abouti ; created_containers, les niveaux de conteneur que cette modification a dû créer, le plus externe en premier, vide dans le cas ordinaire où le chemin entier existait déjà ; et written, le document qui a atteint le disque, vide lorsque rien ne l’a atteint. Lisez created_containers : une modification qui a discrètement écrit deux blocs imbriqués que le document ne portait pas est sinon impossible à distinguer d’une modification qui a ajouté une seule entrée à un bloc que vous avez écrit vous-même.
dry_run fait tout sauf écrire. Le document modifié revient sous forme de content, rien n’est créé et written est vide — pour un client qui présente le résultat à l’auteur avant qu’il soit enregistré. Tout autre comportement est celui de l’écriture, vérification du schéma comprise, de sorte qu’une requête que l’écriture refuserait est également refusée avec lui. Sans lui, le document est écrit et content est absent, car le document est alors sur le disque et written le nomme.
Le caractère sémantiquement admissible de ce que vous câblez — qu’un socket soit l’un de ceux que déclare le producteur, ou que l’applicabilité d’une Feature soit satisfaite — n’est pas décidé ici. C’est à cela que répond validate.
Sur l’entrée et la sortie standard, la même capacité est aussi accessible sous le nom cli-edit-document, qui exécute la commande et renvoie le texte qu’elle a affiché ; sur HTTP, cet outil n’existe pas, et c’est celui-ci qui y donne accès à la capacité.
Transformer une description externe en brouillons d’entités
import convertit une description produite par un autre outil — par exemple un flux exporté depuis un constructeur d’agents — en brouillons de fichiers de rédaction Aggrega. Il écrit ces fichiers dans l’espace de travail que sert ce serveur, donc sur HTTPS il nécessite aggrega:workspace-write : un appelant qui ne détient que aggrega:read le trouve dans la liste des outils, et un appel qu’il effectue est refusé en nommant cette portée.
Transmettez source, le fichier ou le répertoire à convertir. Il est absolu ou relatif à la racine de l’espace de travail, le même contrat que celui de tout autre argument de chemin sur cette surface, et sur un serveur atteint via HTTPS il se résout à l’intérieur de l’espace de travail que sert ce serveur.
D’un répertoire sont lus exactement les fichiers que sélectionnent les motifs de fichiers de son importateur. Un chart ou un projet est un répertoire, et source peut en nommer un. L’importateur reçoit alors ceux de ses fichiers, à n’importe quelle profondeur, que sélectionne l’un des motifs de fichiers déclarés par ses signatures, chacun nommé par son chemin dans le répertoire écrit avec des barres obliques, dans l’ordre trié, ainsi que les fichiers que son rattachement plugins.importer nomme sous with.sources, sous leur nom de base ; un fichier du répertoire et un fichier with.sources de même nom sont refusés plutôt que l’un masque l’autre. Un importateur qui ne déclare aucun motif de fichiers lit un seul fichier et refuse un répertoire, sous la condition An importer that declares no file patterns is handed a directory (Un répertoire est remis à un importateur qui ne déclare aucun motif de fichiers), et un répertoire ne contenant aucun fichier que sélectionnent ses motifs est également refusé. Le répertoire est cantonné à lui-même où qu’il se trouve : un lien parmi les fichiers que lirait l’importation, ou vers un répertoire, qui mène hors de celui-ci est refusé avant toute lecture, et un lien vers un répertoire n’est jamais parcouru — comme l’expose Un répertoire que vous importez. Sur un serveur atteint via HTTPS, le répertoire lui-même se résout à l’intérieur de l’espace de travail, et donc chaque fichier qui y est lu aussi.
L’importateur est l’un de ceux que contient le catalogue de votre espace de travail, ou l’un des importateurs intégrés du compilateur. La traduction est l’œuvre du plugin importateur qui annonce le format de la source : l’un de ceux que contient le catalogue de votre espace de travail, ou l’un des importateurs intégrés du compilateur, qui servent leurs formats dans chaque espace de travail sans aucune entrée de catalogue. Cet outil le sélectionne, l’exécute et écrit ce qu’il a produit. Un rattachement plugins.importer dont l’uri nomme un importateur par son identité et sa version — importer/<name>:<version>, tel que l’écrit aggrega plugin add importer — rattache cet importateur : là où il annonce le format de la source, c’est lui qui s’exécute, dans cette version, quel que soit l’autre importateur qui annonce aussi le format, et il reçoit les sources et paramètres with de ce rattachement, qu’aucun autre importateur ne reçoit. Lorsque plusieurs importateurs annoncent le format et qu’aucun d’eux n’est rattaché seul — parmi eux un importateur intégré et un importateur d’un autre nom que contient votre catalogue pour le même format —, l’appel est refusé en les nommant, comme le décrit Configuration. Un format que vous nommez et qu’aucun importateur n’annonce est refusé en nommant la capacité qu’un importateur devrait annoncer — import:langflow pour une source Langflow —, c’est-à-dire ce que déclare un importateur que vous ajoutez au catalogue, plutôt que par un échec générique qu’il vous faudrait ensuite interpréter.
Un importateur intégré que la machine du serveur ne détient pas est récupéré une seule fois, par la première importation qui en a besoin. L’importation le récupère depuis le registre par défaut de l’espace de travail servi, le confronte au module que publie la version du compilateur, vérifie sa signature selon la politique de confiance de ce registre ainsi que les fonctions hôte qu’il utilise, comme un pull vérifie un plugin qu’il récupère, et le conserve dans le cache de contenu de l’espace de travail, de sorte que chaque importation ultérieure le lit depuis ce cache et ne contacte aucun registre. Rien d’autre n’est écrit pour lui — aucun lockfile, et aucun enregistrement de plugins de confiance. Sur HTTPS, c’est le seul registre qu’un appel à cet outil peut faire contacter au serveur, dans la limite que fixe Quels identifiants un appel dépense pour une lecture de registre : le registre est le registre par défaut de l’espace de travail que sert ce serveur, donc un registre avec lequel cet espace de travail est configuré ; rien dans l’appel ne nomme un registre ni ne porte d’identifiant ; et la récupération dépense la connexion et la politique de confiance propres à cet hôte. L’outil n’atteint toujours que l’espace de travail et rien au-delà, de sorte que aggrega:workspace-write est tout ce dont un appel a besoin : ce que la récupération laisse derrière elle est un module dans le cache de contenu propre à l’espace de travail. Un module qui ne passe pas la vérification est refusé comme il l’est dans un terminal, et rien n’est conservé. Lorsque le module ne peut pas être récupéré — l’espace de travail est hors ligne, son registre est injoignable ou le registre ne le contient pas —, l’appel est refusé sous A plugin’s .wasm is not on this machine (Le .wasm d’un plugin n’est pas sur cette machine), en nommant l’importateur, sa version et ce qui place son module sur la machine.
Lorsque l’espace de travail n’indique aucun dossier de catalogue, l’importation lit le catalogue que publie son registre par défaut. Un espace de travail dont workspace.catalog_dirs, AGGREGA_CATALOG_DIRS et la racine n’indiquent aucun dossier de catalogue lit le catalogue de la bibliothèque standard sous la forme d’un unique instantané signé, à catalog/snapshot sur le registre par défaut de l’espace de travail servi — le même registre que celui d’où est récupéré un importateur de base, atteint dans les mêmes conditions, sans que rien dans l’appel ne nomme un registre ni ne transporte d’identifiant. Un instantané est récupéré une seule fois : sa signature est vérifiée selon la politique de confiance de ce registre, puis il est conservé dans le cache de contenu de l’espace de travail et lu à cet endroit comme un dossier de catalogue, lié à son condensé, sans qu’aucun registre ne soit de nouveau sollicité. Quel instantané lit un appel : avec upgrade, le plus récent ; sinon celui que nomme l’enregistrement dans le répertoire de sortie, récupéré par son condensé lorsque la machine ne le détient pas ; sinon celui que l’espace de travail a récupéré en dernier comme le plus récent ; sinon le plus récent. L’enregistrement qu’écrit l’importation nomme l’instantané qu’elle a lu, par son condensé, de sorte qu’un appel ultérieur produisant des brouillons dans le même répertoire lit le même catalogue. Hors ligne, un appel qui devrait récupérer un instantané est refusé en indiquant ce qu’il faut exécuter, et upgrade est refusé quoi que détienne la machine, puisque seul le registre peut dire quel instantané est le plus récent. Un registre qui ne publie aucun instantané laisse l’importation sans catalogue, et une entrée warn dans diagnostics le signale. Un espace de travail qui indique un dossier de catalogue importe en s’appuyant sur celui-ci et ne récupère aucun instantané, et upgrade n’y change rien.
Omettez format et le format est reconnu grâce aux signatures que déclarent les importateurs — celles de votre catalogue comme celles des importateurs intégrés. L’entité Plugin de chaque importateur les enregistre : la syntaxe dans laquelle une source est lue, les noms de fichiers auxquels s’applique une signature, et les chemins que l’arbre analysé doit ou ne doit pas porter. La source est analysée, au moyen du parseur que sert le catalogue de votre espace de travail pour une syntaxe — ou, pour une syntaxe pour laquelle votre catalogue ne sert aucun parseur, celui qu’embarque le compilateur lui-même —, une fois pour chaque syntaxe dans laquelle la lit une signature s’appliquant à son nom, et le format utilisé est celui de l’unique importateur dont la signature correspond. L’importateur lit ensuite la source au moyen du même parseur. Les signatures des importateurs intégrés lisent un fichier en JSON ou en YAML, et celles qui ne nomment aucun fichier le lisent en JSON — celle de l’importateur Dify en YAML —, de sorte que reconnaître un fichier importé seul le lit dans les deux et ne nécessite aucun parseur dans le catalogue de votre espace de travail : le compilateur embarque un parseur JSON et un parseur YAML, et un parseur que sert votre catalogue est utilisé à sa place. Un répertoire est reconnu de la même manière sur ses fichiers : chaque signature est essayée sur ceux de ses fichiers que sélectionnent ses motifs, et une signature ne déclarant aucun motif ne s’applique à aucun d’eux. La reconnaissance lit le fichier que vous avez nommé — ou, pour un répertoire, uniquement les fichiers que sélectionnent les motifs d’une signature — et aucun réseau. Une source à laquelle ne correspond aucune signature est refusée en demandant format et en nommant les formats qu’annoncent les importateurs — ou, pour un répertoire, en demandant l’un de ses fichiers envoyé seul comme source ou un format dont l’importateur déclare des motifs de fichiers, en ne nommant que ces formats —, sous la condition No importer recognises the source (Aucun importateur ne reconnaît la source) ; une source à laquelle correspondent des signatures de plus d’un format est refusée en les nommant, sous la condition More than one importer recognises the source (Plus d’un importateur reconnaît la source) ; aucune n’est remise à un importateur deviné. Envoyez format pour nommer explicitement le format dans les deux cas — pour un répertoire, un format dont l’importateur déclare des motifs de fichiers, puisqu’un répertoire n’est lu qu’au travers de ceux-ci. Un format vide est refusé plutôt que lu comme si vous l’aviez omis, car ce sont des requêtes différentes.
Envoyez target pour rédiger en brouillon le Manifest sur lequel se construit la Release en brouillon pour un fournisseur. target est une capacité de fournisseur — le mot auquel se lie le spec.capability d’une Recipe, tel que compose ou helm — et c’est le --target de aggrega import, composé par la même opération, de sorte qu’un appel et la commande produisent les mêmes brouillons à partir de la même source. Pour chaque type de composant et chaque type de fonctionnalité dont les brouillons ont besoin — sur les composants de l’Aggregate en brouillon, leurs connexions et ses sous-systèmes, sur les Aggregates du catalogue qu’il compose, et sur les rattachements de la Release en brouillon —, dans l’ordre où les brouillons le déclarent pour la première fois, l’importation cherche dans le catalogue de l’espace de travail les Recipes, ou pour un type de fonctionnalité les recettes de fonctionnalité, qui implémentent le type et se lient à cette capacité. Lorsqu’il y en a exactement une — plusieurs versions de l’une d’elles comptent pour une —, le Manifest associe le type à celle-ci par son nom qualifié par la capacité, sans version, tel que compose/postgres, que le premier pull épingle dans le lockfile à la version la plus élevée disponible. Lorsqu’il y en a plusieurs de noms différents, il associe celle qui porte le nom du type lui-même, telle que helm/postgres pour core/datastore/postgres. Lorsqu’il n’y en a aucune, ou plusieurs dont aucune ne porte ce nom, le type reste non associé et une entrée warn dans diagnostics le nomme ainsi que la raison — chacune des candidates par son nom —, de sorte qu’un build des brouillons s’arrête en nommant chacune de ses instances ou chacun de ses rattachements, sous No Recipe is mapped for a component or feature instance (Aucune Recipe n’est associée à une instance de composant ou de fonctionnalité), jusqu’à ce que l’association soit ajoutée. Lorsque l’importateur rédige lui-même le Manifest, pour choisir la Recipe par laquelle une instance est rendue ou une recette de fonctionnalité parmi plusieurs, chaque association qu’il a écrite et que le catalogue propose pour ce type et cette capacité est conservée, toute autre est abandonnée avec une entrée warn, et les types qu’il laisse sont associés comme ci-dessus. Le Manifest est rédigé en tant que manifest.yaml à côté de la Release en brouillon, avec le même nom et la même version que la Release, et le spec.manifest de la Release est défini sur ce nom — le commentaire que l’importateur avait écrit à sa place est remplacé, et rien d’autre ne change dans la Release. Une Release qui nomme déjà un Manifest est laissée telle quelle, et lorsque l’importation ne produit aucune Release en brouillon, le Manifest est rédigé à côté de l’Aggregate, avec son nom et sa version, et une entrée info indique que rien n’y fait référence. Le Manifest et la Release modifiée sont des brouillons comme les autres : dans written, dans l’enregistrement et renvoyés sous dry_run. Un target auquel ne se lie aucune Recipe du catalogue est refusé avant l’exécution de l’importateur, sous An import’s target names a capability no Recipe in the catalog binds to (La cible d’une importation nomme une capacité à laquelle ne se lie aucune Recipe du catalogue), en le nommant tel que vous l’avez envoyé ainsi que les capacités auxquelles se lient les Recipes du catalogue, et rien n’est écrit. Omettez target et aucun Manifest n’est rédigé — sauf sous sync, qui rédige pour la cible avec laquelle l’importation précédente avait été envoyée ; un target vide est refusé plutôt que lu comme si vous l’aviez omis.
Envoyez output_dir pour nommer le répertoire où vont les brouillons. Omettez-le et ils aboutissent sous la racine de l’espace de travail résolu par l’appel — là où aggrega import les écrit lorsque vous ne nommez aucune destination, où que vous l’exécutiez, et là où aggrega/import du serveur de langage les écrit lorsque sa requête n’en nomme aucune. La destination est facultative dans les trois cas, et se nomme de la même manière que tout chemin que vous envoyez à ce serveur. Sur HTTP, c’est un répertoire à l’intérieur de l’espace de travail que sert ce serveur, écrit relativement à sa racine : une valeur qui remonte hors de la racine, un emplacement absolu hors de celle-ci et un répertoire qui en sort par un lien — y compris un répertoire pas encore créé sous un tel lien — sont chacun refusés en nommant output_dir, et rien n’est lu ni écrit. Sur l’entrée et la sortie standard, il est pris tel qu’il est nommé, comme tout chemin à cet endroit : une valeur relative se résout par rapport à la racine de l’espace de travail résolu par l’appel, et une valeur absolue peut nommer un répertoire hors de l’espace de travail, dans lequel les brouillons sont rédigés comme aggrega import --output-dir les y rédige. Ce qui y est écrit est cantonné, liens résolus, à l’espace de travail — ou, pour un répertoire que vous avez nommé hors de celui-ci, à ce répertoire —, de sorte qu’un lien à l’intérieur qui en sort est refusé et que rien n’est écrit. Un output_dir vide est refusé plutôt que lu comme si vous l’aviez omis. Sur l’entrée et la sortie standard, cli-import porte également le --output-dir de la commande comme son propre output_dir ; une valeur relative s’y résout dans le dossier où s’exécute la commande : la racine de l’espace de travail que nomme l’appel, sinon celle avec laquelle le serveur a été démarré, sinon le dossier où s’exécute le serveur.
Chaque chemin de brouillon est vérifié par rapport au répertoire de sortie avant que quoi que ce soit soit écrit. Un chemin qui en sort est refusé en nommant à la fois le chemin et le répertoire, et rien du tout n’est écrit — pas même les fichiers du même ensemble dont les chemins propres étaient corrects, car une importation refusée qui laisserait une partie d’elle-même derrière elle serait un résultat que personne n’a demandé. Un chemin de brouillon provient du plugin importateur et non de vous, c’est pourquoi il est vérifié pour la même raison qu’un chemin que vous envoyez.
Toute importation qui produit un brouillon écrit aussi .aggrega-import.json à côté de ses brouillons : l’enregistrement de ce qu’elle a écrit — le target avec lequel elle a été envoyée, lorsqu’il y en a eu un, l’instantané de catalogue qu’elle a lu, lorsqu’elle en a lu un, et chaque fichier en brouillon et, dans un Aggregate ou une Release en brouillon, chaque clé à toutes les profondeurs, avec un condensé du texte écrit à cet endroit ; tout autre fichier en brouillon est enregistré en entier. Le texte d’une clé est sa ligne, les lignes de sa valeur lorsque cette valeur n’est pas un mapping de clés, et les lignes de commentaire écrites directement au-dessus d’elle à sa propre indentation. written nomme l’enregistrement avec les brouillons, et sous dry_run il fait partie des brouillons renvoyés. L’enregistrement est en JSON, de sorte que rien de ce qui lit les documents YAML de l’espace de travail ne le lit.
Un appel n’écrase jamais un Aggregate déjà présent dans le répertoire de sortie. Un Aggregate est le document qu’un auteur continue de modifier une fois rédigé, de sorte qu’un appel dont l’un des brouillons aboutirait sur un fichier qui se lit comme un Aggregate est refusé, en nommant le brouillon et le répertoire, et rien du tout n’est écrit — sous dry_run également, puisqu’un essai à blanc refuse ce que refuse l’écriture. Tout autre fichier déjà présent à un chemin de brouillon est écrasé, et un fichier qu’une importation précédente a rédigé et que celle-ci ne rédige pas est laissé où il est.
Envoyez sync pour mettre plutôt à jour par rapport à la source ce qu’une importation précédente a rédigé, en ne changeant que ce que l’importation a écrit. Une synchronisation à laquelle aucun target n’est envoyé rédige pour la cible que nomme l’enregistrement, et rédige donc le Manifest que l’importation précédente a rédigé ; une synchronisation à laquelle un target est envoyé rédige pour celui-ci, et l’enregistrement le nomme ensuite. Une cible enregistrée à laquelle ne se lie aucune Recipe du catalogue est refusée comme une cible envoyée, le refus précisant qu’il s’agit de la cible enregistrée. Chaque partie est jugée de trois façons — ce que l’enregistrement dit que l’importation a écrit là en dernier, ce qui se trouve sur le disque, et ce que la source produit maintenant. Une partie que la source a laissée telle que l’importation l’avait écrite en dernier reste exactement telle qu’elle est sur le disque, qu’un auteur l’ait modifiée ou non. Une partie que la source a changée est réécrite, une partie qu’elle a abandonnée est supprimée — un fichier en brouillon effacé en entier —, et une partie qu’elle a gagnée est ajoutée à côté des parties que le brouillon nomme autour d’elle, chacune uniquement là où ce qui se trouve sur le disque est ce que l’importation a écrit en dernier et ne contient rien qu’un auteur ait ajouté. Tout le reste est conservé octet pour octet : une clé qu’un auteur a ajoutée n’importe où — un paramètre, une Feature, y compris sous une instance de Component en brouillon, un autre Component, l’environnement qu’une Release en brouillon laisse à son auteur —, un commentaire qui n’est pas écrit directement au-dessus d’une clé en brouillon, et chaque fichier que l’enregistrement ne liste pas. Le drift de la réponse liste chaque partie mise à jour — ou, sous dry_run, chaque partie qui le serait — dans l’ordre où le brouillon les nomme, chacune sous la forme change (added, removed ou changed), file, le fichier en brouillon où elle se trouve, et key, les clés qui y mènent dans un Aggregate ou une Release en brouillon, sous forme de liste, vide lorsque la partie est le fichier entier ; la réponse textuelle nomme chacune sur une ligne à part avec les mots qu’écrit aggrega import sur la sortie d’erreur standard, <change> <key> in <file> ou <change> <file>. Un drift vide sous dry_run indique que les brouillons sont alignés sur la source. Sous dry_run, les brouillons renvoyés sont les fichiers qu’écrirait la synchronisation, avec le contenu qu’elle leur donnerait. Une synchronisation qui modifierait ou supprimerait une partie qu’un auteur a modifiée, ajouterait une partie là où un auteur en a déjà écrit une, ou supprimerait une partie contenant quelque chose qu’un auteur a ajouté est refusée, en nommant chacune de ces parties et la raison, et rien n’est écrit ; un commentaire écrit directement au-dessus d’une clé en brouillon modifie cette clé. Une synchronisation sur un Aggregate qu’aucun enregistrement ne liste est refusée en le signalant, de même qu’une synchronisation dont l’enregistrement ne peut pas être lu, et une synchronisation dont l’importateur n’a pas pu aller au bout n’écrit rien. Une synchronisation dans un répertoire ne contenant aucun enregistrement et rien à ses chemins de brouillon écrit le brouillon entier. drift est une liste vide pour un appel qui n’est pas une synchronisation.
La réponse porte source, tel que vous l’avez nommé ; format, la manière dont la source a été lue ; workspace_root, la racine de l’espace de travail résolu par l’appel ; output_dir, le répertoire par rapport auquel les chemins de brouillon sont relatifs ; written, les fichiers qui ont atteint le disque ; drift, ce qu’une synchronisation a mis à jour ; diagnostics, une entrée par construction que l’importateur n’a pas pu traduire ; decisions, la manière dont l’importateur a associé chaque nœud source ; et halted. output_dir est le répertoire que vous avez envoyé, ou cette racine lorsque vous n’en avez envoyé aucun, relevé d’après ce que l’importation a réellement utilisé, et il est indiqué sous dry_run également, où rien n’est écrit mais où chaque chemin de brouillon reste relatif à lui. Sur HTTP, workspace_root est retenu et marqué workspace_root_withheld, car la racine est un emplacement sur l’hôte du serveur, comme l’expose Ce qu’une réponse dit du système de fichiers du serveur ; output_dir est retenu et marqué output_dir_withheld lorsqu’il est cette racine, et sinon indiqué par son nom relatif à la racine — la forme que prennent vos propres chemins —, de sorte que l’endroit où sont allés les brouillons figure toujours dans la réponse. Une importation que l’importateur n’a pas pu terminer produit tout de même les brouillons qu’elle a pu, et revient marquée comme un échec en portant cette réponse complète — halted à true, les fichiers qui ont bien atteint le disque nommés dans written, et à côté d’eux les diagnostics qui nomment ce qui manque. C’est un résultat partiel que vous pouvez conserver ou rejeter, et non un appel qui n’a rien fait.
decisions indique où l’importation a deviné. Il porte une entrée par nœud source que l’importateur a associé, dans l’ordre de l’importateur : source_node, l’id, le type et le params_summary du nœud ; candidates, chaque Component du catalogue que l’importateur a envisagé pour lui, sous la forme component, score, tier et signals — ce que chacun de ses signaux a apporté, sous table, category, domain_labels, shape et name ; chosen, le target qu’il a choisi, le mode dans lequel il l’a écrit — une reference à un Component existant ou un draft — et le tier du choix ; rationale, la justification ; et swap_hint, comment choisir autrement. candidates est absent lorsque l’importateur n’en a envisagé aucun, chosen lorsqu’il n’a fait aucun choix, et rationale et swap_hint lorsqu’il n’en a écrit aucun. Chaque valeur est propre à l’importateur — la manière dont il note un candidat et l’endroit où tombent ses paliers relèvent de ses choix —, lisez donc une entrée comme son compte rendu de l’association. decisions figure dans la réponse sous dry_run comme lorsque l’importation s’est interrompue, et c’est une liste vide pour un importateur qui n’en signale aucune. La réponse textuelle nomme chaque décision sur une ligne à part après les diagnostics, avec les mots qu’écrit aggrega import sur la sortie d’erreur standard : mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, le score étant celui du meilleur candidat.
dry_run fait tout sauf écrire. Chaque fichier en brouillon revient sous drafts avec son chemin, relatif à output_dir, et son contenu, et rien n’est créé — pour un client qui vous présente le résultat avant qu’il soit enregistré. Tout autre comportement est celui de l’écriture, le même importateur sur la même source signalant les mêmes diagnostics, de sorte qu’une source que l’écriture refuserait est également refusée avec lui. Sans lui, les fichiers sont sur le disque et written les nomme, et drafts est absent plutôt que de répéter des octets dont vous avez demandé l’écriture.
Les brouillons sont un point de départ qui vous appartient et que vous continuez à modifier. Le caractère admissible de ce qu’ils disent — qu’un socket soit l’un de ceux que déclare le producteur, ou que l’applicabilité d’une Feature soit satisfaite — n’est pas décidé ici. C’est à cela que répond validate.
Sur l’entrée et la sortie standard, la même capacité est aussi accessible sous le nom cli-import, qui exécute la commande et renvoie le texte qu’elle a affiché ; sur HTTP, cet outil n’existe pas, et c’est celui-ci qui y donne accès à la capacité.
Publier, signer et retirer
Quatre outils déposent quelque chose là où d’autres personnes le résoudront. publish-entity met en bundle une entité du catalogue et la publie ; publish-artifact publie un fichier autonome, tel qu’un bundle de documentation, dont les octets restent opaques et sans qu’aucune enveloppe d’entité soit analysée ; sign-artifacts signe des références déjà publiées et attache chaque signature, laissant telle quelle une référence qui en porte déjà une que la politique de confiance de son registry vérifie ; deprecate-artifact attache à une référence un marqueur de retrait signé. Lisez Ce qu’un assistant peut faire sans vous demander d’abord avant d’autoriser l’un d’eux : ce sont les outils dont les effets quittent la machine.
publish-entity prend entity, le document à publier, et un Plugin nécessite aussi plugin, l’exécutable publié dans son manifeste. publish-artifact prend file avec le name et le tag sous lesquels il est publié. Chaque argument de chemin est ici absolu ou relatif à la racine du workspace, le même contrat que celui de tous les autres outils de cette surface, et workspace_root désigne le workspace visé par l’appel — sur un serveur atteint par l’entrée et la sortie standard. Un serveur atteint par HTTPS refuse workspace_root et exige que chacun de ces chemins se résolve à l’intérieur du workspace qu’il sert, comme l’explique Un processus, un workspace. registry est la destination et vaut par défaut celui configuré dans le workspace ; n’envoyer ni l’un ni l’autre, sans valeur par défaut configurée, est refusé en indiquant quoi envoyer. sign-artifacts prend references, une ou plusieurs adresses de registry plutôt que des chemins, et facultativement jobs, le nombre de références signées à la fois : s’il est omis, elles sont signées l’une après l’autre, et une valeur inférieure à 1 est refusée en indiquant quoi envoyer. Chacune est tout de même signée exactement comme elle le serait seule, comme le décrit aggrega sign. deprecate-artifact prend soit reference avec severity et reason, soit from désignant un fichier de lot — et refuse les arguments de contenu envoyés avec un fichier de lot plutôt que de les abandonner, car un fichier de lot fournit les siens et un argument ignoré en silence se lit comme un argument respecté.
Les deux outils de publication prennent dry_run, qui montre ce qu’une publication enverrait sans contacter aucun registry. Il calcule le bundle, indique ce qu’il aurait publié et répond avec beyond_this_machine à false et la destination à laquelle il se serait adressé dans registries ; publish-entity répond aussi avec le digest que cette publication produirait, celui qu’affiche aggrega push --dry-run. C’est le moyen de montrer à quelqu’un une publication proposée avant qu’elle n’en devienne une. La signature et le retrait n’ont pas de telle forme : tous deux agissent sur quelque chose de déjà publié, il n’y a donc rien à prévisualiser.
publish-entity répond avec windows_unusable_entries lorsque l’archive qu’il publie contient des entrées que Windows ne peut pas conserver telles qu’elles sont écrites — un chemin dont une partie porte le nom d’un périphérique, comme CON, AUX ou NUL, quelle que soit la casse et quelle que soit l’extension qui suit, ou une partie se terminant par un point ou une espace — en les nommant chacune, d’abord le nom de fichier du document de l’entité, puis les fichiers qu’il transporte. Le champ est absent lorsqu’il n’y en a aucune, ce qui inclut une entité publiée sous la forme de son seul document. aggrega exécuté sous Windows refuse de décompresser une telle entrée, de sorte qu’un workspace Windows ne peut pas utiliser la version ; ce sont les entrées au sujet desquelles aggrega push avertit, et le texte de la réponse les nomme aussi. Elles ne refusent rien : l’appel se poursuit ou est refusé exactement comme il le serait sans elles, dry_run compris.
publish-entity prend pin_sources, qui exécute sur l’entité l’étape de pin de l’auteur de l’entité avant sa mise en bundle, de sorte que l’entity.lock que l’étape écrit à côté d’elle fait partie de ce qui est publié. C’est la même étape que celle qu’exécute l’outil pin, qui écrit les mêmes octets, et elle s’exécute avant tout refus qui juge l’entité — une publication refusée à ce stade, pour une signature manquante par exemple, laisse donc tout de même le lock écrit à côté de l’entité. Un refus qui porte sur l’appel lui-même, comme un workspace hors ligne ou l’absence de destination, vient en premier et ne pin rien. Si vous l’omettez, c’est pin_sources_at_push du workspace qui décide ; si vous l’envoyez, c’est lui qui décide, dans un sens comme dans l’autre. Une publication qui pin écrit dans le workspace en plus du registry, elle nécessite donc sur HTTP un identifiant portant les deux scopes, et un identifiant ne portant que le scope qui autorise la publication est refusé en nommant l’autre. Le résultat contient pin, sous la forme dans laquelle répond l’outil pin, lorsque l’étape a été exécutée ; sous dry_run, l’étape indique le lock qu’elle écrirait et n’écrit rien. Lorsque l’étape n’est pas exécutée, une Recipe ou une FeatureRecipe dont l’entity.lock n’enregistre aucun pin pour une entrée qu’elle lit est refusée — ou une à laquelle l’entrée ne correspond plus — avant toute mise en bundle, dry_run compris, en nommant aggrega pin, pin_sources et pin_sources_at_push. C’est le refus que pull émet sur le même lock, et sa vérification récupère chaque source distante que l’entité écrit en entier, comme le ferait l’étape.
La signature est le moment où l’identifiant est utilisé, et trois des quatre outils la réalisent — la publication d’un artefact de données ne signe rien et est signée ensuite par référence. identity_token fournit une identité sans clé pour l’appel. Sur un serveur atteint par l’entrée et la sortie standard, l’omettre fait retomber sur l’identité que porte l’environnement propre de ce serveur, et key_path sélectionne à la place une clé détenue hors ligne. Sur un listener, ni l’un ni l’autre n’est accessible : l’environnement n’est pas lu, key_path est refusé et retiré de ce que ces trois outils annoncent, et une clé que la configuration du workspace servi désigne n’est pas atteinte — seul un jeton envoyé dans l’appel signe donc, comme l’explique Quels identifiants un appel utilise. Un appel signe avec un seul identifiant. Chaque référence envoyée à sign-artifacts, et chaque entrée d’un fichier de lot que lit deprecate-artifact, est signée avec la même clé détenue ou la même identité sans clé ; lorsque la configuration du workspace servi désigne une clé pour le registry d’une référence et aucune pour celui d’une autre, ou deux clés différentes, l’appel ne signe rien et est refusé en nommant les registries de chaque côté, avant qu’aucune identité ne soit résolue ni aucun registry lu — envoyez un appel par identifiant, ou un seul key_path pour toutes sur l’entrée et la sortie standard. Sur un listener, aucune clé configurée n’est atteinte, chaque référence y est donc signée avec l’identité qu’envoie l’appel, et l’appel n’est jamais refusé pour cette raison. Le refus est décrit dans References signed together need different signing credentials (Des références signées ensemble nécessitent des identifiants de signature différents). fulcio_url, rekor_url et timestamp_url remplacent les points de terminaison sans clé que configure le workspace, sur l’un ou l’autre transport. Lorsqu’aucune identité ne se résout, l’appel refuse et indique quoi envoyer — rien ici n’ouvre de navigateur ni n’attend une personne, car personne n’observe un flux de protocole, et un appel bloqué serait précisément l’échec silencieux que ce refus existe pour empêcher. Sur publish-entity, l’attachement ou non d’une signature suit la politique du registry de destination, sauf si sign en dispose autrement, et un registry qui exige des signatures refuse une publication non signée quoi que vous envoyiez : aucun argument ne contourne ce refus. Consultez aggrega sign pour les deux modes de signature et ce que chacun contacte.
Chaque résultat contient les faits plutôt qu’une transcription : où l’artefact a atterri, son tag, le digest publié — ou, pour l’exécution à blanc d’une entité du catalogue, le digest que produirait une publication — si le tag pointait déjà vers un contenu identique octet pour octet, si une publication a été signée, et son reach. Un lot de signature indique chaque référence signée avec le digest sur lequel sa signature s’engage, dans l’ordre où les références ont été données, et un lot dans lequel une référence a échoué revient comme un échec qui les nomme chacune plutôt que comme un résultat avec une liste écourtée — un lot partiel présenté comme un succès est la façon dont un refus finit par être lu comme une réussite. Une dépréciation indique chaque marqueur avec son propre digest, puisqu’un marqueur est attaché comme referrer sans tag de l’artefact qu’il retire et que rien d’autre ne l’adresse. Signer ou retirer une référence que rien n’a publiée est refusé plutôt qu’attaché à rien.
Les deux parties d’une réponse
Chaque outil répond par un texte lisible et, partout où l’opération en a un, par un résultat structuré à côté. Le texte est écrit pour une personne qui lit la conversation. Le résultat structuré porte la même réponse sous forme de champs qu’un programme lit — un verdict, une liste de fichiers, un diagnostic — et un refus en porte un aussi lorsque l’opération avait des constats en main au moment du refus, comme le décrit Ce que renvoie une build refusée pour une build.
Le résultat structuré porte aussi le texte, sous la forme text_answer. Le résultat structuré de chaque outil possède un champ text_answer contenant le texte de la réponse exactement tel que le texte le porte : chaque phrase, dans l’ordre, inchangée. Ainsi, un client qui transmet à son modèle le résultat structuré plutôt que le texte, comme le fait Claude Desktop, lui transmet tout de même chaque phrase du texte — la ligne par laquelle s’ouvre la réponse de describe-capabilities sans argument, la configuration en vigueur que rapporte config-show, la phrase qui nomme le dossier utilisé par une réponse lorsqu’aucun workspace n’a été trouvé. text_answer est écrit en premier, avant les champs par lesquels l’outil répond, et c’est le texte que reçoit l’appelant : sur HTTP, il nomme chaque emplacement de l’hôte du serveur comme le fait le texte, comme l’explique Ce qu’une réponse dit du système de fichiers du serveur. Le texte lui-même reste la prose qu’il est, pour les clients qui le lisent, de sorte que les mêmes mots voyagent deux fois dans chaque réponse.
Aucun outil ne fait exception, lint compris. Aucun outil ne répond avec un champ propre nommé text_answer, de sorte que le champ ne se substitue jamais à l’un d’eux. Le résultat structuré de lint conserve son summary — le nombre d’entités vérifiées et de constats, au total et par gravité, sous les noms qu’écrit aggrega lint avec -o json — et porte text_answer à côté. describe-capabilities conserve aussi ses propres champs : version_summary, la ligne de version seule, lorsqu’il est appelé sans argument, et dans chaque entrée de son index un summary, l’objet de cet outil en une ligne.
Aucun outil n’annonce de schéma de sortie. La description d’un outil porte un schéma pour les arguments qu’il prend et aucun pour son résultat, c’est pourquoi text_answer est nommé ici plutôt que dans un schéma.
Une réponse sans résultat structuré se réduit à son texte. Le refus des arguments d’un appel, et tout autre échec pour lequel l’opération n’avait rien de structuré à rapporter, revient sous forme de texte et de rien d’autre, et le texte est alors la seule partie qu’un client peut montrer à son modèle.
Quand un appel n’aboutit pas
L’endroit où arrive la réponse dépend d’une seule chose : l’appelant peut-il corriger le problème en modifiant les arguments d’un outil qui existe ?
Tout ce qui peut être corrigé de cette façon revient comme le résultat propre de l’outil, marqué comme un échec et portant la correction dans son texte — une combinaison de sélecteurs que l’outil n’accepte pas, un argument obligatoire omis, un argument envoyé avec le mauvais type JSON, un chemin qui ne se résout pas, un diagnostic du compilateur. C’est le canal qui est montré à un assistant, qui lit donc ce qui n’a pas fonctionné et rappelle avec l’argument corrigé.
Le canal d’erreur du protocole est réservé à ce qui n’a aucun résultat d’outil dans lequel figurer : un nom d’outil que le serveur ne sert pas, une requête dont il ne peut pas lire les paramètres, une méthode qu’il n’implémente pas, et un message qui n’est pas du tout du JSON valide. La lecture d’une ressource et le rendu d’un prompt y répondent aussi, car aucun de ces résultats ne porte d’indicateur d’échec propre.
Le schéma annoncé d’un outil déclare aussi la plupart des règles que ses arguments doivent respecter — quels sélecteurs s’excluent mutuellement, quel argument n’a de sens qu’avec un autre et lesquels sont obligatoires — de sorte qu’un client qui compose des appels d’après le schéma déclaré a rarement besoin de passer l’appel pour les apprendre. Une règle que le schéma n’énonce pas est tout de même refusée, avec une phrase qui la nomme ; la règle de pull selon laquelle verify ne se combine pas avec upgrade_targets ou pin_sources est volontairement laissée au refus, pour la raison donnée sous Résoudre ce dont dépend une Release.
Ce qui arrête le serveur
Sur l’entrée et la sortie standard, fermer la connexion l’arrête. Le serveur lit un message par ligne et se termine proprement lorsque son entrée standard atteint la fin du flux, de sorte qu’un client qui ferme la connexion arrête le serveur. C’est le cas ordinaire sur ce transport, car vous ne lancez jamais la commande vous-même : c’est le client qui l’a démarrée qui y met fin, si bien que quitter votre éditeur, ou désactiver ce serveur pour un projet, est la forme que prend habituellement son arrêt.
Demander au processus lui-même de s’arrêter atteint le serveur sur l’un ou l’autre transport. Une interruption depuis un terminal, ou une demande de terminaison d’un superviseur ou d’un runtime de conteneurs, l’arrête dès la première demande, qu’un client envoie quelque chose ou non : il cesse d’accepter des messages, met fin au travail d’un appel en cours et se termine proprement. Une seconde demande met fin au processus immédiatement. Sur l’entrée et la sortie standard, un appel encore en cours lorsque le processus est invité à s’arrêter ne se termine donc pas ; un listener, lui, se vide, laissant un appel déjà en cours de réponse se terminer dans un délai borné avant que le processus ne se termine.
Un client peut aussi arrêter un seul appel sans arrêter le serveur, et la façon de le faire dépend du transport. Les appels reçoivent leur réponse de manière concurrente, de sorte que la fin de l’un est traitée pendant que cet appel est encore en cours plutôt que d’attendre derrière lui. Sur l’entrée et la sortie standard, un client nomme l’identifiant de l’appel ; annuler un appel qui a déjà reçu sa réponse, ou un appel sur lequel le serveur ne travaille pas, n’a aucun effet — ce qui rend sûr l’envoi d’un tel message sans savoir au préalable si la réponse est déjà en route. Sur HTTP, il n’y a aucun message à envoyer : fermer la connexion qui a porté l’appel y met fin. Dans les deux cas, l’appel reçoit l’ordre de s’arrêter — son travail s’achève au prochain point où l’opération vérifie, et une opération qui ne vérifie jamais va jusqu’à son terme — rien de plus n’est envoyé pour cet appel, chaque autre appel en cours se poursuit, et le serveur continue de servir.
Quand l’utiliser
Utilisez aggrega mcp lorsque vous voulez qu’un assistant IA vous aide à rédiger des entités Aggrega d’après les schémas et la référence réels — afin que ses suggestions reposent sur la structure exacte qu’accepte le compilateur plutôt que d’être devinées. Il s’intègre directement à la boucle de rédaction : l’assistant lit le schéma et la référence d’un type, génère un squelette, remplit les champs qui relèvent de votre rôle et valide avant de vous rendre le brouillon. Consultez Rédiger des fichiers Aggrega pour cette boucle.
Sur l’entrée et la sortie standard, vous ne tapez en général jamais aggrega mcp vous-même. Vous le nommez plutôt une fois dans la configuration MCP de votre client, et le client le démarre et l’arrête pour vous. Un listener est l’autre cas : c’est vous qui exécutez le processus, et il continue de tourner pour des appelants qui ne l’ont pas démarré.
Exemple : configuration du client sur l’entrée et la sortie standard
Dirigez un client MCP vers la commande avec une entrée de serveur stdio :
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Le seul prérequis est le binaire aggrega installé dans le PATH du client. Pour les chemins de configuration propres à chaque client et le dépannage, consultez Connecter le serveur MCP. Pour récupérer un schéma directement en ligne de commande sans client, consultez aggrega get-schema.