aggrega mcp
Ejecutar un servidor Model Context Protocol sobre la entrada y salida estándar, o sobre HTTP, para la integración con asistentes de IA
Sinopsis
aggrega mcp [flags]Descripción
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.Flags
| Flag | Predeterminado | Descripción |
|---|---|---|
--listen | — | La dirección en la que escucha el transporte HTTP, en una de dos formas: host:port, o unix: seguido de una ruta del sistema de archivos. Indica dónde escuchar y no elige ningún transporte: se lee con —transport http, o con mcp.transport: http en la configuración del workspace, y si se da con el transporte stdio se rechaza. Un listener sin certificado sirve en texto plano y solo se permite en loopback (127.0.0.1, ::1, localhost) o en un socket Unix, que es la forma que adopta un servidor detrás de un proxy de terminación; cualquier otra dirección necesita mcp.tls.cert_file y mcp.tls.key_file, que este proceso usa entonces para terminar TLS por sí mismo. Si se establece, anula la clave de configuración mcp.listen. |
--transport | — | Cómo se llega al servidor: stdio habla el protocolo por la entrada y salida estándar, que es como llega a él un cliente que lanza este comando como subproceso; http lo sirve por HTTP en la dirección que indica —listen o mcp.listen, y por HTTPS donde mcp.tls indica un certificado y una clave. Si se establece, anula la clave de configuración mcp.transport, cuyo valor predeterminado es stdio. |
Qué hace
aggrega mcp ejecuta un servidor Model Context Protocol. Dos transportes llegan a él, y --transport elige entre ellos: stdio o http, con mcp.transport en la configuración del workspace como la clave que el flag anula, y stdio como valor predeterminado.
Sobre stdio, el predeterminado, se comunica por la entrada y salida estándar del proceso. De esa forma no es un comando que ejecutes de manera interactiva — un cliente compatible con MCP lo lanza como subproceso y habla el protocolo por stdio; Conectar el servidor MCP indica dónde guarda cada cliente la entrada que lo lanza. Ejecutarlo convierte la CLI en un asistente de autoría que conoce Aggrega dentro de tu editor o cliente de chat.
Sobre http, en cambio, sirve el protocolo por HTTP: un único proceso de larga duración en un host, al que llegan llamadores que no están frente a su teclado, escuchando en la dirección que indica --listen, o mcp.listen cuando el flag no está. Consulta Llegar al servidor por HTTPS para saber cómo se configura ese listener y qué acepta.
Habla dos revisiones del protocolo, 2026-07-28 y 2025-06-18, de modo que un cliente de cualquiera de ellas se conecta y llega a las mismas superficies. Cuál habla una llamada se indica en esa llamada en lugar de acordarse una vez para la conexión. Un cliente en 2026-07-28 envía con cada solicitud la versión del protocolo que habla y sus propias capacidades, y pregunta a server/discover qué admite el servidor; un cliente en 2025-06-18 fija esas mismas cosas una sola vez, abriendo la conexión con un handshake initialize. En ambos casos el servidor no guarda nada entre mensajes, así que lo que envías primero no decide nada sobre cómo se responde a una llamada posterior. Una solicitud que nombra una revisión que el servidor no habla se rechaza y se le indica cuáles son las dos que puede pedir, en lugar de responderse como si hubiera pedido una de ellas.
El servidor expone tres superficies al asistente conectado:
-
Prompts — dos familias, y la diferencia está en lo que responde cada una. Los prompts de autoría responden a «qué estoy escribiendo»: una persona por rol (desarrollo, arquitectura, operaciones), más una plantilla específica por entidad. Cada uno enmarca el rol y orienta al asistente hacia el esquema, la página de referencia y la guía de autoría adecuados, de modo que sus sugerencias se mantengan dentro de los pilares de los que se ocupa ese rol. Los prompts de flujo de trabajo responden a «qué llamadas, en qué orden»: cada uno expone la secuencia ordenada de llamadas a herramientas que alcanza un objetivo que abarca varias operaciones, con los puntos de decisión entre ellas — componer desde cero un nuevo Aggregate y su Release, llevar a Aggrega un chart, un módulo de infraestructura o un archivo container-compose existente, averiguar por qué una build no compila o renderiza los artefactos equivocados.
prompts/listenumera ambas familias yprompts/getrenderiza uno, de modo que el conjunto se lee del servidor y no de esta página.Un prompt de flujo de trabajo nombra las llamadas y tú las haces, una a una, leyendo cada resultado antes del siguiente. No hay ninguna llamada que realice un objetivo completo: cada herramienta envuelve una operación que puedes comprobar, así que es la secuencia lo que te lleva hasta allí. Las personas de autoría aceptan un
kindopcional en el que centrarse, la plantilla por entidad exige uno, y unkindal que no responde ningún esquema se rechaza con la lista de valores aceptados en lugar de ignorarse en silencio. -
Recursos — material de referencia de solo lectura servido en línea:
schema://<kind>para el JSON Schema de una entidad,langref://<path>para cualquier página de la referencia del lenguaje,authoring://<topic>para la guía de autoría,catalog://<kind>/<name>para el YAML escrito de una entidad del catálogo, ycli://<command>para la ayuda propia de un comando, concli://solo como punto de entrada — esa ayuda se responde a partir de los comandos que lleva el propio servidor, de modo que leer una no inicia ningún proceso y devuelve el mismo texto que el comando imprime para--help. Una lecturacatalog://de una entidad que el catálogo no contiene se responde como no encontrada; cuando eso se debe a que exactamente un archivo del catálogo que declara la entidad se omitió durante la carga, el mensaje de la respuesta nombra ese archivo, la restricción que incumple y el código corto de la condición en lugar de solo el URI — el rechazo con el queaggrega buildempieza para el mismo archivo.resources/listenumera los que se pueden direccionar sin parámetro yresources/templates/listanuncia la forma de URI de cada familia. -
Herramientas — acciones sobre tu workspace, y
tools/listresponde con todas ellas.Las herramientas con las que se encuentra primero un asistente están pensadas para el ciclo de autoría:
list-entitiesylist-releasespara averiguar qué contiene el workspace,scaffoldpara un esqueleto que lleva los campos que exige su tipo, con un marcador de posición dondequiera que se deba un valor — o, si recibeexample, para escribir uno de los ejemplos ejecutables de la documentación en un directorio nuevo, respondiendo con dónde está ese directorio, los archivos escritos y los comandos para construirlo, y, si recibelist: true, para listar los ejemplos —get-schemapara el JSON Schema de una entidad,validatepara validar un borrador (nombra cada marcador de posición que el borrador aún lleva, y lo que acepta cada uno),describepara describir una entidad del catálogo — o una entidad leída de su registry por referencia —pullpara resolver las dependencias de una Release en la caché local y escribir su lockfile,buildpara construir una Release en sus artefactos renderizados — en memoria por defecto, sin escribir ningún artefacto en disco, o escritos endist/en la raíz del workspace, donde los escribeaggrega build, cuando envíaswrite(y las dependencias se resuelven primero solo si envíasauto_pull),gen-catalogpara generar entidades Plugin a partir de invitados Wasm, yexplain-errorpara ampliar un diagnóstico del compilador en orientación práctica — incluidas, donde el diagnóstico empieza con el código corto de una condición de detención, esa condición y la guía publicada de la corrección de autoría, la misma ampliación queaggrega explainda para el mismo código en una terminal.El resto de la superficie está en la misma respuesta y no detrás de ella: más herramientas que se ejecutan dentro del servidor —
lint, la herramienta que nombra la conexión escrita en un punto de un documento, las dos herramientas de candidatura, las herramientas de contenedor de adjuntos y de punto de inserción, la herramienta que aplica una edición acotada a un documento,pin, que registra los pines de contenido de las entradas de una entidad como expone Fijar las entradas propias de una entidad, y las cuatro herramientas de publicación descritas más abajo, además de inventarios de las cachés y de los registries configurados — y, para un cliente que lanzó este servidor sobre su entrada y salida estándar, una herramienta por cada comando que de otro modo podrías escribir, con el nombre de su ruta de invocación. Esas herramientas de comando existen solo en ese transporte: un servidor al que se llega por HTTP no ofrece ninguna de ellas, por el motivo que se da en Llegar al servidor por HTTPS. No se reserva nada para una llamada posterior. Cuánto de una lista de herramientas poner delante de un modelo es una decisión que corresponde al cliente — obtiene las definiciones y elige qué cargar — y una definición que un cliente nunca recibió es una operación que un modelo nunca puede llamar, por muy accesible que sea el nombre de esa herramienta en el wire. Donde la lista completa supera lo que admite tu cliente, Acotar lo que anuncia el servidor es la forma de acortarla.describe-capabilitiesacota esa superficie al tipo de entidad que estás escribiendo. Si recibe unkind, responde con las herramientas que sirven a ese tipo, obtenidas de los tipos que declara cada herramienta y no de las palabras de una descripción; sin argumentos, responde con ese mismo índice sobre cada herramienta que este servidor te ofrece — el nombre de cada una, un propósito en una línea, los tipos que sirve y si escribe, sin esquemas de argumentos, de modo que toda la superficie llega en una única respuesta legible. Para una herramientacli-, si escribe depende de si escribe el comando que ejecuta:cli-buildse indica como de escritura, porque el comando guarda los artefactos renderizados bajo la raíz del workspace, y tambiéncli-scaffold, porque si recibeexampleel comando escribe uno de los ejemplos ejecutables de la documentación en un directorio nuevo, mientras que un comando que solo lee se indica como de solo lectura, incluso cuando por el camino llena una caché que comparten todos los proyectos de la máquina, igual que la herramienta que ejecuta la misma operación dentro del servidor; si recibetoolsnombrando una o más, responde exactamente con las definiciones completas y los esquemas de argumentos de esas herramientas. Las herramientascli-nunca se acotan por tipo, porque nada registra a qué tipo de entidad sirve un comando, de modo que una respuesta acotada a un tipo las omite y el índice sin argumentos es donde leerlas. Los argumentos de una herramienta de comando llevan el nombre de los flags propios del comando, de modo que--output-dirse envía comooutput_dir, y un nombre no reconocido se rechaza con la lista de grafías aceptadas en lugar de descartarse en silencio.Algunas capacidades están presentes dos veces en la entrada y salida estándar: una herramienta pensada para el ciclo de autoría ejecuta la operación dentro del servidor, y la herramienta con el nombre del comando que ofrece la misma capacidad ejecuta ese comando. Las dos no se comportan igual, así que en ese transporte cada una nombra a la otra e indica la diferencia; por HTTP las herramientas de comando no están, y la frase de emparejamiento se omite en lugar de señalar una herramienta a la que el llamador no puede llegar. La que se ejecuta dentro del servidor es la que conviene usar — responde con un resultado legible por máquina junto al texto legible, de modo que un asistente obtiene un veredicto, una lista de archivos o un diagnóstico como campos en lugar de como una transcripción que analizar. La herramienta de comando inicia el comando real en un proceso aparte, así que hace todo lo que ese comando hace en la máquina en la que se ejecuta, incluido escribir en disco donde el comando escribe —
cli-buildescribe los artefactos renderizados endist/en la raíz del workspace, y los archivos de una build trazada en.trace/junto a ella, y la línea final que devuelve nombra ese directorio completo — y devuelve solo la línea de comandos que ejecutó y el texto que ese comando imprimió. Recurre a ella cuando necesites un flag que el comando declara y que la otra herramienta no acepta.Esa línea de comandos empieza con los flags globales con los que se inició este servidor que deciden la configuración —
--configy--offline, si los diste — por delante del comando y de los flags propios de la llamada. Así, el comando lee la configuración que lee cualquier otra herramienta de aquí: un servidor iniciado con--offlineejecuta sus comandos sin conexión, y uno iniciado con--configlos ejecuta sobre ese archivo global. Un flag que la llamada envía para sí misma va después de ellos y prevalece, de modo queoffline: falseen una llamada accede a la red solo para esa llamada, y la línea de comandos devuelta muestra ambos. Donde el servidor se inició con una raíz de workspace — mediante--workspace-rooto medianteAGGREGA_WORKSPACE_ROOT— la línea de comandos empieza con esa raíz como--workspace-root, por delante de esos dos, de modo que el comando toma ese directorio como raíz del workspace, como lo haría escrito con el mismo flag y como lo toma cada herramienta que se ejecuta dentro del servidor, en lugar de encontrar su workspace a partir del directorio en el que se inició el servidor. Una llamada que envíaworkspace_rootnombra la suya, y la línea de comandos lleva solo esa — incluido un valor vacío, que el comando lee como se lee--workspace-root ""en una terminal: encontrar el workspace a partir del directorio en el que se inició el servidor. Un servidor iniciado sin ninguno de los dos no pasa ninguna raíz, así que sus comandos encuentran su workspace a partir de ese directorio, según la regla que En qué workspace se responde una llamada establece para cada herramienta — salvo el lanzamiento del bundle de escritorio con su ajuste Workspace folder vacío, en el que una llamada que no nombra un workspace propio no inicia ningún comando y se responde con el rechazo de ese ajuste. El comando se inicia en la raíz del workspace que nombra la llamada o el lanzamiento: elworkspace_rootpropio de la llamada, leído como lo lee cada herramienta — uno absoluto tal como se envió, uno relativo a partir de la raíz en la que se responde una llamada que no nombra ninguno — y pasado al comando en su forma absoluta, o si no la raíz con la que se inició el servidor. Así, una ruta relativa que una llamada pasa como archivo que leer — un documento paravalidate, un--releaseo un--catalog— se lee dentro de ese workspace, como en una terminal abierta allí, y una build que ejecuta el comando escribedist/bajo esa raíz. Donde nada nombra una raíz — ninguna raíz de lanzamiento, y ningúnworkspace_rooto uno vacío — el comando se inicia en el directorio en el que se inició el servidor y lee una ruta relativa desde allí; unworkspace_rootque no nombra ninguna carpeta existente se pasa tal como se leyó — uno absoluto tal como se envió, uno relativo en su forma completa — y el comando lo rechaza con sus propias palabras. Un comando que registra un plugin de extensión de comandos no recibe ninguno de ellos, porque pasa cada argumento al plugin sin leerlo en lugar de analizar un flag global, en una terminal como aquí; se inicia en la misma carpeta que cualquier otro comando.Algunos comandos faltan deliberadamente incluso en la entrada y salida estándar, donde las herramientas de comando sí existen — por HTTP faltan todos, y eso es una propiedad del transporte y no de ningún comando. En la entrada y salida estándar, cada uno de estos se deja fuera por un motivo declarado: el daemon y este mismo servidor nunca devolverían un resultado; un comando que lee una contraseña de la terminal no tiene de dónde leerla; uno que escribe un script de autocompletado de la shell no tiene ninguna shell en la que instalarlo; eliminar una credencial almacenada actúa sobre el almacén de toda la máquina en lugar de sobre un workspace que hayas nombrado; y obtener un token de identidad de forma interactiva no tiene ninguna forma no interactiva que ofrecer. Falta por ese mismo motivo de toda la máquina
aggrega plugin run-local, que carga un invitado.wasmdesde una ruta que le das: aquello para lo que sirve el comando es leer un archivo dondequiera que lo pongas, así que no hay ningún workspace al que pueda limitarse, y la lectura ocurre en el propio proceso antes de que exista el invitado. Al invitado no se le concede nada cuando se ejecuta — ni directorios, ni sockets, ni entorno — pero eso es un límite sobre el módulo y no sobre la lectura, así que no es lo que lo decide. Ejecútalo en tu terminal, donde eres tú quien nombra la ruta. Firmar y publicar son un caso completamente distinto, y esa diferencia es lo que los mantiene fuera de esa lista. Cada uno resuelve una identidad a partir de una entrada proporcionada o del entorno y la rechaza explícitamente cuando no hay ninguna disponible, de modo que cada uno tiene una forma que se completa sin que nadie esté mirando — mientras que obtener un token de forma interactiva es un verbo que ninguna entrada puede satisfacer ni siquiera en principio. Así que están presentes dos veces: como los comandos, y como las cuatro herramientas internas al proceso descritas en Publicar, firmar y retirar. Donde la línea de comandos abriría un navegador, rechazan y nombran qué proporcionar en su lugar, en vez de esperar a una persona que no está.
En qué workspace se responde una llamada
Una llamada nombra su workspace con workspace_root; de lo contrario, se responde en el workspace sobre el que se inició el servidor. Donde el lanzamiento nombró una raíz, con --workspace-root o AGGREGA_WORKSPACE_ROOT, esa raíz es la propia raíz del workspace, como lo es el flag en cada comando: no se busca por encima de ella ningún workspace que la contenga, así que un lanzamiento nombra la carpeta que contiene el .aggrega-config.yaml del workspace, y una llamada se responde allí tanto por las herramientas que se ejecutan dentro del servidor como por las herramientas de comando. Donde el lanzamiento no nombró ninguna, el workspace se encuentra a partir del directorio en el que se inició el servidor, exactamente como lo descubre un comando escrito en una terminal allí — el orden se expone en Las otras formas en que se reconoce la raíz de un proyecto — salvo en el lanzamiento del bundle de escritorio con su ajuste Workspace folder vacío, que en cambio rechaza una llamada así, como se expone más abajo. Un workspace_root relativo se lee a partir de la raíz en la que se responde una llamada que no nombra ninguno — la raíz que nombró el lanzamiento o, donde no nombró ninguna, la raíz del workspace a la que se resuelve el directorio en el que se inició el servidor — de modo que una llamada nombra una carpeta dentro del workspace, como quickstart-ai/1, sin saber dónde está el workspace en la máquina; uno absoluto se usa tal como se da. Cada herramienta lo lee así, incluidas las herramientas de comando. Donde no hay ninguna raíz desde la que leer uno relativo — una raíz de lanzamiento que no es una carpeta existente, o el lanzamiento de escritorio con Workspace folder vacío — uno relativo se rechaza igual que una llamada que no nombra ninguno. Un workspace_root que no nombra ninguna carpeta existente, o que nombra un archivo, se rechaza antes de que la herramienta haga cualquier otra cosa, nombrando el argumento y citando el valor — uno absoluto tal como se envió, uno relativo en la forma completa en que se leyó — igual que un comando rechaza --workspace-root.
Una raíz de lanzamiento que no es una carpeta existente se sirve como un rechazo en la entrada y salida estándar. Donde --workspace-root o AGGREGA_WORKSPACE_ROOT nombra una carpeta que no existe, o nombra un archivo, el servidor escribe el rechazo en su flujo de error y se inicia de todos modos, de modo que un cliente que no muestra a su usuario nada de ese flujo muestra igualmente el porqué. Responde a initialize y a sus listas de herramientas, recursos y prompts, y cada llamada que actuaría en ese workspace se responde con el rechazo: una llamada a una herramienta como resultado fallido, una lectura de una entidad catalog:// o de una página de la documentación como error. El rechazo nombra el flag, o la variable junto con el ajuste Workspace folder de la aplicación de escritorio que la establece — el ajuste que describe Claude Desktop — y cita el valor exactamente como se dio; un valor que el cliente envió sin rellenar se cita tal como llegó, y nada de su contenido se interpreta. Una herramienta que ejecuta un comando no inicia ninguno para una llamada que no nombra un workspace propio, ya que la carpeta en la que ese comando se iniciaría no existe, y responde con el mismo rechazo. Una llamada que nombra un workspace propio mediante una ruta absoluta se responde allí; una que lo nombra mediante una ruta relativa no tiene ninguna carpeta desde la que leerla, y se responde con el mismo rechazo. Lo que no actúa en ningún workspace — un esquema, un prompt, la ayuda de un comando — se responde como en cualquier servidor. Un listener, en cambio, se rechaza al iniciarse, antes de que se vincule nada, con el mismo rechazo, de modo que quien lo supervisa lee el fallo donde lo busca.
Un lanzamiento de escritorio con su ajuste Workspace folder vacío se sirve como un rechazo de la misma manera. El bundle de escritorio siempre pasa al servidor AGGREGA_WORKSPACE_ROOT, con lo que contenga Workspace folder, y establece AGGREGA_BUNDLE_VERSION junto a ella, mientras que la aplicación inicia el servidor en una carpeta de su elección — a menudo una carpeta del sistema — en lugar de en tu proyecto. Así, un servidor sobre la entrada y salida estándar iniciado sin --workspace-root, cuyo entorno lleva AGGREGA_BUNDLE_VERSION y un AGGREGA_WORKSPACE_ROOT vacío o ausente, no busca un workspace a partir de la carpeta en la que se inició. Escribe el rechazo en su flujo de error y se inicia de todos modos, respondiendo como lo hace con una raíz de lanzamiento que no existe: cada llamada que actuaría en un workspace y no nombra uno propio se responde con un rechazo que dice que la aplicación de escritorio lanzó el servidor con su ajuste Workspace folder vacío, de modo que AGGREGA_WORKSPACE_ROOT no nombra ninguna raíz de workspace, que te indica que establezcas Workspace folder en la carpeta que contiene el .aggrega-config.yaml de tu workspace, y que dice que una carpeta establecida después de que se inició el servidor surte efecto una vez que la extensión se desactiva y se vuelve a activar o se reinicia la aplicación, porque la aplicación pasa el ajuste al servidor solo cuando lo inicia. Una herramienta que ejecuta un comando no inicia ninguno para una llamada así. Una llamada que nombra un workspace propio mediante una ruta absoluta se responde allí, y una que lo nombra mediante una ruta relativa se responde con el mismo rechazo, ya que no hay ningún Workspace folder desde el que leerla; lo que no actúa en ningún workspace se responde como en cualquier servidor. El servidor reconoce el lanzamiento solo por AGGREGA_BUNDLE_VERSION: en un bundle que no establece esa variable, un ajuste vacío se lee como ninguna raíz, y un lanzamiento que establece la variable a mano y no nombra ninguna raíz se rechaza como el del bundle. Cualquier otro valor vacío sigue sin nombrar ninguna raíz — un AGGREGA_WORKSPACE_ROOT vacío en un lanzamiento que no lleva AGGREGA_BUNDLE_VERSION, un --workspace-root escrito vacío, un listener, aggrega serve y cualquier otro comando lo leen cada uno como no establecido.
Donde no se encontró ningún workspace y no se nombró ninguno, una respuesta sobre el workspace dice qué carpeta usó. Sin raíz de lanzamiento, sin workspace_root en la llamada y sin nada que ancle un workspace a partir de la carpeta en la que se respondió la llamada, la llamada se responde en esa carpeta. Cuando el resultado de la herramienta depende del workspace — las mismas herramientas cuyos comandos advierten en la línea de comandos —, su texto termina con la advertencia de la línea de comandos, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, y una línea que te indica que envíes workspace_root nombrando la carpeta que contiene el .aggrega-config.yaml de tu workspace; una respuesta que el workspace no determina, como la lectura de la configuración o el listado de plugins, no dice nada sobre workspaces. La frase no añade ningún campo propio al resultado estructurado; el resultado estructurado la lleva en text_answer, que contiene el texto, como expone Las dos partes de una respuesta. Una herramienta que ejecuta un comando en un proceso aparte lleva la propia línea del comando que dice lo mismo, tal como la imprimió el comando. En una carpeta así no se escribe nada en una caché de artefactos: un pull, o una build a la que se pide que resuelva primero sus dependencias, se rechaza allí antes de que se descargue nada, nombrando la carpeta y las dos alternativas — enviar workspace_root, o dar a la carpeta un .aggrega-config.yaml que lleve un bloque workspace:. Un pin, o una publicación de una Recipe o una FeatureRecipe, se rechaza de la misma manera donde descargaría una fuente remota que la entidad escribe completa — para fijarla, o para comparar su pin — antes de que esa fuente se descargue; donde no descarga ninguna, porque la entidad no tiene fuente, tiene una local o una cuyas coordenadas rellena cada Release, se responde como en cualquier otro lugar. Una build allí que no resuelve nada antes sigue renderizando, pero una entrada externa que su lockfile fija y que la caché ya no contiene no se vuelve a descargar: al render se le comunica esa misma frase en lugar de la entrada, igual que se le comunica la de un modo sin conexión. Ninguna respuesta por HTTP lleva la frase: un listener siempre sirve un workspace que se le dio o que encontró. Tampoco la lleva el lanzamiento del bundle de escritorio con un ajuste Workspace folder vacío, que rechaza una llamada que no nombra un workspace propio en lugar de responderla en la carpeta en la que se inició.
Una llamada sobre una Release o un documento que nombra con una ruta absoluta se responde en el workspace propio de ese archivo cuando nada más ha fijado uno. Donde el lanzamiento no nombró ninguna raíz, la llamada no envía ningún workspace_root y el directorio en el que se inició el servidor no ancla ningún workspace, el workspace se descubre de nuevo a partir de la carpeta en la que está ese archivo, y lo que eso encuentre — el proyecto al que pertenece el archivo o, si todo lo demás falla, esa carpeta — es aquel en el que se responde la llamada. Es la regla que sigue un comando escrito en una terminal, así que se aplica a cada herramienta cuya llamada trata sobre una Release o un documento de entidad que nombra: una build, un pull, una validación, un lint, una descripción, un listado en los términos de una Release, una pregunta sobre un nodo del grafo de una Release, un pin, la publicación de una entidad, una edición y una posición leída en un documento. Donde una llamada nombra tanto una Release como un documento, decide la Release. Así, para un cliente que lanzó el servidor fuera de tu proyecto, una Release de ese proyecto se construye igualmente a partir de la configuración propia del proyecto. Las demás rutas que nombra la llamada se leen como siempre — una relativa, a partir del directorio en el que se inició el servidor — y una herramienta que ejecuta un comando en un proceso aparte se responde desde el mismo workspace, porque el comando sigue la misma regla en ese mismo directorio. Una raíz que nombró el lanzamiento, un workspace_root que envía la llamada, un directorio de inicio que está él mismo dentro de un workspace, y una Release o un documento nombrados con una ruta relativa se usan tal cual. Por HTTP no se plantea nada de esto: un listener siempre sirve un workspace que se le dio o que encontró, y cada ruta que nombra una llamada es relativa a él. Tampoco en el lanzamiento del bundle de escritorio con un ajuste Workspace folder vacío, que rechaza una llamada que no nombra un workspace propio, sea cual sea el archivo que nombre.
Restringir lo que anuncia el servidor
mcp.announce_tools nombra las herramientas que este servidor anuncia, escritas exactamente como las informa la lista de herramientas. Si omites la clave, se anuncia cada herramienta que incluye este servidor, que es el valor predeterminado y la forma que espera un cliente que sigue el protocolo. Si escribes una lista, se anuncian exactamente esas herramientas: una que quede fuera está ausente de la lista de herramientas, ausente de lo que responde describe-capabilities y se rechaza si aun así se llama por su nombre, con un rechazo que nombra este ajuste. Si escribes una lista vacía, no se anuncia nada en absoluto — así que omitir la clave y escribir [] son afirmaciones distintas, y el ajuste no tiene ningún valor predeterminado que se rellene por ti.
Configúralo donde el cliente del otro extremo limite cuántas herramientas registrará, a veces sumando todos los servidores a los que está conectado a la vez, y nombra las herramientas que ese cliente necesita. Ese límite es el caso para el que existe el ajuste, y el cliente al que se aplica suele ser el que inició este servidor por su propia entrada y salida estándar — así que, a diferencia del resto del bloque mcp, que configura el listener que inicia el transporte http, esta clave se lee sea cual sea el transporte que hable el servidor.
Restringe lo que se anuncia y nada más. Nombrar aquí una herramienta no amplía nada. No anula mcp.deny_reach, que retira una capacidad por completo, así que una herramienta nombrada aquí de un tipo que ese ajuste retira queda fuera de la lista y se rechaza nombrando ese ajuste. Tampoco anula los scopes que lleva el token de un llamante: una herramienta nombrada aquí aparece en la lista sean cuales sean esos scopes, y una llamada que ellos no admiten se rechaza igualmente, nombrando el scope que la admitiría. En ambos casos, el rechazo que encuentra el llamante es el de ese otro límite y no el de este. Un rechazo de este ajuste no lleva ningún challenge ni nombra ningún scope, porque ninguna credencial cambia lo que un servidor eligió ofrecer — lo que nombra en su lugar es el ajuste, que es lo único sobre lo que puede actuar quien lee el rechazo.
Cada nombre tiene que ser uno que incluya este binario. Un nombre al que no responde ninguna herramienta detiene el servidor antes de que sirva nada, y el rechazo enumera las herramientas que sí tiene — así un error tipográfico se detecta al arrancar en lugar de mediante una superficie silenciosamente más estrecha que la que pediste. Un nombre de la familia cli-, que ejecuta un comando aggrega en un proceso separado, se acepta en ambos transportes y no anuncia nada por HTTP, donde de entrada no se ofrece ninguna herramienta de ese tipo a ningún llamante.
El conjunto anunciado se fija cuando arranca el proceso, así que cambiarlo requiere un reinicio y nada hace crecer la lista bajo un cliente que ya se ha conectado.
De qué versión procede el servidor
describe-capabilities enviado sin argumentos indica de qué versión procede este servidor. Su respuesta estructurada lleva server_version, la versión que el ejecutable aggrega informa de sí mismo — la que aggrega version imprime para el mismo archivo — y su texto se abre con una línea que la nombra, antes del índice. La respuesta estructurada lleva esa misma línea como version_summary, palabra por palabra, de modo que un cliente que entrega a un modelo solo la respuesta estructurada le entrega también la línea.
Donde el paquete de escritorio inició el servidor, la misma respuesta nombra a su lado la versión del paquete. El paquete no contiene ningún programa: inicia el ejecutable aggrega que nombre su ajuste Path to the aggrega executable —de forma predeterminada, el nombre de comando aggrega, que la aplicación busca en su PATH—, así que el paquete y el ejecutable se instalan por separado y pueden proceder de versiones distintas, y la aplicación que muestra el paquete indica solo la versión del propio paquete. El paquete entrega al servidor su versión como AGGREGA_BUNDLE_VERSION en su entorno; el servidor la lee una vez, al arrancar, y la respuesta la lleva como bundle_version. Las dos se comparan exactamente como están escritas, lo cual es una comparación justa porque el paquete y el ejecutable de una misma versión llevan estampada la versión de esa entrega en la misma forma, mientras que una compilación de desarrollo se lee distinta de cualquier versión publicada. Cuando son iguales, la línea nombra ambas y no dice nada más. Cuando difieren, la línea dice, nombrando ambas, que el ejecutable y el paquete proceden de versiones distintas, y la orientación que el servidor ofrece a un modelo cuando se conecta se abre con esa misma frase, de modo que la diferencia está ante el modelo antes de que pregunte.
Un servidor que no inició ningún paquete informa solo de su propia versión. Iniciado desde un terminal, desde la configuración de un editor o como listener, no lleva bundle_version, a menos que algo defina la variable en su entorno. Un servidor por entrada y salida estándar que lleva la variable se considera iniciado por el paquete en un aspecto más: si no se le nombró ninguna raíz, rechaza el ajuste Workspace folder vacío, como expone En qué workspace se responde una llamada. Una llamada a describe-capabilities enviada con kind o tools no lleva server_version, bundle_version ni version_summary, ni esa línea, porque responde sobre herramientas y no sobre el servidor.
Una diferencia se informa y nunca se rechaza. El servidor arranca y responde a cada llamada exactamente como lo haría con las dos sincronizadas. Qué significa una diferencia para una instalación de escritorio, y cómo volver a alinear ambas, está en Conectar el servidor MCP.
Llegar al servidor por HTTPS
aggrega mcp --transport http sirve el protocolo por HTTP en lugar de por la entrada y salida estándar. mcp.transport en la configuración del workspace es la clave que ese flag sobrescribe, y su valor predeterminado, stdio, es lo que espera un cliente que inicia el comando — así que un servidor al que llegan otras personas lleva transport: http en su configuración, y un cliente iniciado desde un directorio que cubre esa configuración sigue llegando al servidor por sus propios flujos. Es el mismo servidor en ambos casos — el mismo workspace y las mismas superficies del protocolo — y lo que cambia es cómo le llega un mensaje, cómo termina una llamada y qué tiene que poseer quien lo ejecuta. Esta sección describe lo que configura un operador; la entrada que necesita un cliente para llegar a un servidor en ejecución está en Conectar el servidor MCP.
Una dirección no elige ningún transporte. --listen <address>, o mcp.listen cuando falta el flag, nombra dónde se enlaza el listener una vez elegido http, y nada más. Así que http sin dirección de ninguno de los dos se rechaza antes de que se enlace nada, y el rechazo nombra ambos. --listen escrito mientras el transporte es stdio — escrito como --transport stdio, configurado como mcp.transport: stdio o dejado en el valor predeterminado — también se rechaza, nombrando --transport http como el flag que serviría en esa dirección; un --listen con un valor vacío se rechaza por no nombrar ninguna dirección, sea cual sea el transporte. Y una dirección que solo nombra la configuración queda sin usar por un servidor que habla por sus propios flujos, que lo indica en una línea de su flujo de errores, nombrando el archivo que la definió y mcp.transport: http. Ese último caso no se rechaza en ninguna parte a propósito: es el inicio que hace un cliente cuando arranca el comando en un directorio cuya configuración lleva los ajustes de un listener, y una configuración de listener que olvida transport: http no inicia ningún listener, que es donde se nota.
Un servidor al que se llega por HTTP no ofrece ninguna herramienta que ejecute un comando aggrega en un proceso separado. Esas herramientas existen solo para un cliente que inició este servidor por su entrada y salida estándar, en la propia máquina de ese cliente, donde nombrar una carpeta o un flag no concede al llamante nada que no tuviera ya. Un llamante que llega al servidor por HTTP no es dueño del host en el que se ejecuta, así que un comando que actuaría sobre el sistema de archivos de ese host con la autoridad del propio servidor se ejecuta en su lugar en un terminal del host. Las herramientas están ausentes de la lista y de describe-capabilities en lugar de ofrecerse y rechazarse, y una llamada que nombra una recibe un error que lo indica. Es una propiedad del transporte, no un ajuste: no hay ninguna configuración que las devuelva.
Lee Nada se sirve sin una credencial antes de desplegar uno. Cada solicitud al endpoint lleva una credencial, y no hay ningún ajuste que sirva una solicitud sin ella — lo que elige un ajuste es si este servidor verifica él mismo un bearer token o lee un llamante que un proxy situado delante ya ha verificado.
Las dos formas de despliegue
El proceso termina TLS él mismo. Configura mcp.tls.cert_file con una cadena de certificados PEM y mcp.tls.key_file con su clave privada, y el listener sirve HTTPS directamente en la dirección que le hayas dado. Ambos archivos se leen cuando arranca el proceso, así que un certificado reemplazado se aplica reiniciando el proceso. Configurar uno sin el otro se rechaza al arrancar en lugar de recurrir a otra cosa: un certificado sin clave no puede presentarse, una clave sin certificado no nombra nada, y un error tipográfico en una ruta no es motivo para empezar a servir tráfico sin cifrar.
Un proxy situado delante termina TLS y reenvía a un listener confinado. Deja ambas claves sin configurar y el listener sirve en texto plano, lo que solo se acepta en loopback o en un socket Unix — así nada que no esté ya en ese host puede llegar a él. Es la forma que usa un proxy inverso, un sidecar o una service mesh, y es aquella en la que el certificado está delante de este proceso en lugar de en él.
Un listener en texto plano en cualquier otra dirección se rechaza antes de que se enlace nada, y el rechazo nombra ambas claves TLS. No hay ningún ajuste que lo levante ni ninguna dirección que sea una excepción: un listener que acepta conexiones de la red sin un certificado propio nunca es seguro, así que el proceso se niega a arrancar en lugar de arrancar con esa forma.
Las formas de dirección
--listen y mcp.listen adoptan una de dos formas:
host:port— una dirección TCP, como127.0.0.1:7777o0.0.0.0:8443. Loopback significa127.0.0.1,::1, olocalhostcuando cada dirección a la que se resuelve ese nombre es una dirección de loopback. Cualquier otra cosa es una dirección de red y necesita un certificado: un host vacío, que es cada interfaz que tiene la máquina; la dirección de una interfaz concreta; y cualquier otro nombre, incluso uno que en este momento se resuelva a una dirección de loopback, porque dónde puede enlazarse un listener no debería depender de una resolución que puede cambiar bajo él.unix:seguido de una ruta del sistema de archivos — un socket de dominio Unix, comounix:/run/aggrega/mcp.sock. Un socket solo es accesible desde el host en el que se encuentra, así que no necesita ningún certificado.
Una ruta de socket se toma exactamente como está escrita, incluida una relativa. Deliberadamente no se resuelve respecto al archivo de configuración que la declaró, porque la misma dirección también llega desde --listen, que no tiene archivo declarante — consulta adónde apunta una ruta relativa.
Qué acepta el listener
Un único endpoint, /mcp, que acepta POST. Cada mensaje JSON-RPC es su propia solicitud y no se mantiene ninguna sesión de ningún tipo: nada que un cliente envíe primero decide cómo se responde una solicitud posterior, nunca se genera ningún identificador de sesión, y se ignora un encabezado de sesión o de reanudación de flujo que envíe un cliente. Cualquier otro método en ese endpoint recibe 405 con Allow: POST, y cualquier otra ruta 404 — ambos resueltos antes de la comprobación de la credencial, de modo que un sondeo no aprende nada de un challenge en una ruta o un método que de todos modos no serviría nada.
Una solicitud se responde con un objeto JSON y un código de estado — o, cuando la llamada informó de su progreso en el camino hacia ese objeto, con un flujo de eventos que termina en él, como expone Saber cómo avanza una llamada larga. Una notificación — un mensaje sin id — recibe 202 con un cuerpo vacío. Un mensaje que no es ninguna de las dos cosas, incluida una respuesta JSON-RPC, recibe 400, porque un cliente envía a este servidor solicitudes y notificaciones y nada más.
Ambas revisiones del protocolo se sirven aquí exactamente como por la entrada y salida estándar. Una solicitud 2026-07-28 refleja su cuerpo en encabezados de transporte para que un intermediario pueda enrutarla sin analizar el cuerpo: MCP-Protocol-Version lleva la revisión que indica el cuerpo, Mcp-Method el método que nombra y Mcp-Name el destino, para los métodos que se dirigen a uno por su nombre. Un encabezado que no coincide con el cuerpo recibe 400. Un cliente 2025-06-18 empieza con un handshake initialize, que se responde sin estado; puede llevar el encabezado de versión que nombra esa revisión u omitirlo. Una solicitud que nombra una revisión que el servidor no habla recibe 400 con la lista de las dos que habla, y una que nombra un método que no sirve recibe 404.
mcp.allowed_origins solo se consulta cuando una solicitud lleva un encabezado Origin, lo que en la práctica significa que la envió un navegador: una solicitud que nombra un origen que la lista no contiene recibe 403, y una que no lleva ese encabezado se sirve. Un cliente que no es un navegador no envía ese encabezado y no necesita ninguna entrada. Uno basado en navegador siempre necesita una entrada: la lista está vacía hasta que un operador la escribe, así que hasta entonces no hay ningún origen y cada solicitud de navegador recibe 403 — incluida una de una página servida en la propia dirección del endpoint. La entrada se compara exactamente con el encabezado, así que se escribe como un navegador envía un origen — un esquema en minúsculas, ://, un host en minúsculas y, cuando no es el predeterminado del esquema, : y el puerto, como https://app.example.com — y una entrada con una ruta, una / final, sin esquema o con una mayúscula se rechaza al cargar la configuración, nombrando la entrada, porque nunca podría coincidir.
mcp.limits acota el tráfico que se acepta. Un cuerpo que supera max_body_bytes recibe 413 y no se lee más allá del límite. Una solicitud que llega mientras ya hay max_concurrent_requests en curso recibe 503 en lugar de quedar en cola detrás de un trabajo que no puede ver. Un llamante que envía más de requests_per_minute en un minuto recibe 429, contabilizado solo para ese llamante, de modo que un llamante que envía mucho no le cuesta nada a otro. El valor predeterminado de cada límite se indica junto a su clave en la referencia de configuración, y ninguno tiene un valor que lo desactive.
Un proceso, un workspace
El workspace por el que responde un proceso de servicio se fija cuando arranca. --workspace-root lo nombra; la variable AGGREGA_WORKSPACE_ROOT lo proporciona cuando falta el flag. La carpeta nombrada es la propia raíz del workspace, sin buscar nada por encima, y una carpeta que no existe se rechaza, nombrando cuál de los dos la proporcionó y citando el valor tal como se dio — por un listener antes de enlazarse, y por un servidor por entrada y salida estándar en su respuesta a cada llamada que actúa en ese workspace, como expone En qué workspace se responde una llamada — de modo que un inicio compuesto por un cliente en lugar de escrito sigue diciendo qué recibió. Sin ninguno de los dos, un servidor por entrada y salida estándar resuelve el workspace a partir del directorio en el que se inició — donde nada ancla allí un workspace, cada respuesta sobre el workspace dice qué carpeta usó, y el inicio del paquete de escritorio con un ajuste Workspace folder vacío rechaza en su lugar una llamada que no nombra un workspace propio, como expone En qué workspace se responde una llamada — y un listener se rechaza antes de enlazarse a menos que allí se resuelva un workspace — un proceso al que se llega por HTTP responde a llamantes que no pueden ver la máquina, así que sirve un workspace que eligió un operador en lugar del directorio en el que le tocó iniciarse. Para servir varios proyectos, ejecuta un proceso por cada raíz de proyecto.
Una llamada que llega por HTTP no puede nombrar un workspace propio. workspace_root y catalog_dirs se rechazan, nombrando el argumento enviado, en lugar de descartarse en silencio: un argumento ignorado en silencio le parece a quien lo envía exactamente igual que uno respetado. Los directorios de catálogo que se buscan junto al workspace servido son los del propio ajuste workspace.catalog_dirs de ese workspace — o, para una Release a la que asigna directorios propios en workspace.releases, los de esa Release — que escribe el operador. Por entrada y salida estándar se respetan ambos argumentos, porque el cliente que inició el servidor se ejecuta en la propia máquina del llamante. Allí una entrada de catalog_dirs es absoluta, o relativa a la raíz del workspace desde la que se lee una release relativa — la raíz que estableció primero el propio workspace_root de la llamada, el inicio o el directorio en el que se inició el servidor, y aquella desde la que se sigue leyendo cuando una Release nombrada de forma absoluta traslada la llamada al propio workspace de esa Release — y no al directorio en el que se ejecuta el servidor, cuando este está en otro lugar.
Una ruta que nombra una llamada también permanece dentro de ese workspace. Por HTTP, un argumento de ruta se resuelve respecto a la raíz del workspace y se rechaza si sale de ella — una ruta relativa que sube fuera del workspace, una ruta absoluta que nombra otro lugar y una ruta relativa que sale del workspace a través de un enlace a un archivo o un directorio que está ahí vuelven cada una como un fallo que nombra el argumento, sin nombrar ni la raíz del workspace ni el lugar al que la ruta habría llegado; una ruta relativa se devuelve tal como la enviaste. Cada argumento de ruta se juzga por adónde lleva, según la definición de «dentro» que da El límite del workspace, tanto si la herramienta lo lee como si lo escribe — el directorio en el que gen-catalog escribe su salida, el documento que edit-document reescribe y la entidad junto a la que pin escribe su bloqueo tanto como un documento que lee una herramienta — así que una ruta aún no creada bajo un enlace que sale del workspace se rechaza igual que ese enlace, sin que se lea ni se escriba nada. Una release que nombra una Release que nombra la configuración del workspace servido, como build.authoring_release o como clave de workspace.releases, se alcanza a través de esa configuración y se acepta a través de un enlace dondequiera que esté su archivo; ningún otro argumento tiene esa excepción. Cuando la ruta que querías está dentro de ese workspace pero se escribió de forma absoluta, el rechazo te da la forma relativa a la raíz que debes enviar en su lugar, de modo que a un llamante que adivinó la forma equivocada se le indica la correcta en lugar de solo decirle que era equivocada. Eso vale para las rutas que una llamada nombra como su objeto — el documento que se ha de validar, la Release que se ha de compilar, el directorio en el que una generación escribe su salida — y para aquellas en las que escribe una herramienta no menos que para las que lee: un llamante que llega a un servidor por la red le pide a una máquina que no puede ver que lea y escriba archivos, y el workspace que eligió el operador es donde se contienen esa lectura y esa escritura. Por entrada y salida estándar, los argumentos de ruta de cada herramienta mantienen el contrato descrito más abajo para esa herramienta, donde una ruta puede ser absoluta y puede apuntar fuera del workspace — la persona que llama es dueña de la máquina en la que se ejecuta el servidor, así que confinarla a un directorio que eligió ella misma no aportaría nada. Las dos herramientas cuya propia operación responde solo sobre un documento que contiene el workspace, insertion-point y edit-document, mantienen eso en ambos transportes, y rechazan un documento fuera del workspace tanto si está escrito así como si se alcanza a través de un enlace que sale de él. Lo que se respeta por entrada y salida estándar es la ruta que nombra una llamada y nada más allá. Lo que la operación lee y escribe luego por su cuenta se contiene en ambos transportes exactamente igual que cuando el mismo comando se escribe en un terminal: un recorrido o una búsqueda no lee a través de un enlace que sale del workspace, un archivo que una Release del workspace o su Manifest nombra mediante una ruta no se lee desde fuera del workspace — y uno que nombra una Release que la llamada nombró fuera del workspace no se lee desde fuera del directorio que contiene esa Release — y un archivo escrito bajo un directorio — el workspace, o uno que nombró la llamada — permanece dentro de ese directorio. El límite del workspace sitúa los dos transportes junto a la línea de comandos y el editor, y expone lo que queda abierto por entrada y salida estándar: un documento en un workspace que clonaste puede llevar a un asistente a nombrar una ruta fuera del workspace, y esa ruta se respeta tal como se nombra.
Qué dice una respuesta sobre el sistema de archivos del servidor
Por HTTP, una respuesta nombra un lugar del sistema de archivos del servidor de forma relativa a la raíz del workspace, o lo retiene. Un cliente que inició el servidor se ejecuta donde se ejecuta el servidor, así que por entrada y salida estándar cada respuesta nombra cada lugar tal como lo tiene la operación — de forma absoluta, cuando así es como lo tiene — y cada uno es un lugar que ese llamante ya posee. Un llamante que llega a un listener no eligió ninguno de esos lugares y no puede abrirlos, y un servidor que se los ha revelado no puede retirarlos. Así que, por HTTP, una respuesta le dice a ese llamante una de dos cosas sobre un lugar:
- Un lugar dentro del workspace se nombra de forma relativa a la raíz del workspace — la misma forma que adopta una ruta que envías, de modo que un nombre leído en una respuesta puede devolverse sin cambios en la siguiente llamada. Una Release en la raíz es
release.yaml, y su archivo de bloqueo esrelease.lock. - Un lugar fuera del workspace se retiene, y también la propia raíz del workspace. El campo no lleva ningún valor — es
nullo se omite, y enattachment-container, cuya respuesta mantiene la forma en que la informa cada superficie,filequeda vacío — y una marca a su lado, con el nombre del campo seguido de_withheld, indica que se retuvo en lugar de quedar sin definir:workspace_root_withheldjunto aworkspace_root,file_withheldjunto afile. Una marca solo está presente donde se retuvo algo. La raíz se retiene porque un listener sirve exactamente un workspace, así que dónde se encuentra ese workspace no nombra nada que necesites para nombrar lo que hay dentro de él.
Si un lugar está dentro se juzga por cómo está escrito, no por el archivo al que llega. Una ruta escrita a través del destino de un enlace simbólico en lugar de a través de la raíz sobre la que se inició el servidor, y una ruta que sale de la raíz y vuelve a entrar, se consideran cada una fuera del workspace y se retienen. El juicio se inclina a decirte menos, nunca a nombrar un lugar fuera del workspace.
Por HTTP, el texto legible de una respuesta sigue la misma regla. Donde el texto, una línea de diagnóstico o el mensaje de un fallo nombra un lugar que contiene el workspace — su raíz o cualquier cosa por debajo, un archivo de configuración del que se leyó su configuración, un directorio del que se lee su catálogo — ese lugar se escribe de forma relativa a la raíz, o figura como (location withheld) cuando está fuera del workspace o es la raíz. El texto que una respuesta compone sobre su propio workspace lo llama el workspace que sirve este servidor. Un lugar fuera de todos esos que una operación escribe en un mensaje no se reconoce como tal, y te llega tal como se escribió.
Las respuestas a las que esto alcanza, por HTTP:
list-entities,list-releases,cache-status,registry-list,search,attach-candidates,connection-candidates,insertion-point,attachment-container,connection-at-positionyedit-documentretienenworkspace_root. Las rutas que ya dan de forma relativa a la raíz — el archivo fuente de una entidad, la ruta de una Release y su archivo de bloqueo enlockfiles, el documento al que se refiere un punto de inserción o una edición, los archivos que escribió una edición — se leen igual en ambos transportes.cache-statustambién retiene lo que nombra un plugin que el servidor cargó desde un archivo de su host. Una identidad así esnullen su lugar enprovenance[].identities, cada otra identidad mantiene su posición y la entrada se marca conidentities_withheld. Lanotede un módulo compilado es una frase que nombra las identidades para las que se compiló el módulo, así que, cuando alguna de ellas nombra un archivo así, lanotese omite por completo y se marca connote_withheld; eldigestdel módulo sigue presente. Una identidad que nombra una referencia de registro o una entidad Plugin se responde completa, y también unanoteque solo nombra esas. Lalabelde un artefacto fuente es su lugar en la caché, formado a partir del host y la ruta de la URL desde la que se resolvió, así que para un repositorio leído desde el propio sistema de archivos del servidor — mediante una URLfile://o una ruta — lalabelse omite y se marca conlabel_withheld, susizey sudigestsiguen presentes, y unalabelque nombra un host de red se responde completa. El texto del listado muestra(location withheld)donde habría nombrado uno.validatenombratarget, yreleasepara una Release, de forma relativa a la raíz; para todo el catálogo,targetes la raíz y se retiene. Un lugar endiagnosticsonoticessigue la regla del texto.buildnombrareleasede forma relativa a la raíz, y una compilación que resolvió primero sus dependencias llevadependency_resolutiontal como lo respondepull. Una compilación enviada conwritenombra el directorio en el que escribió comooutput_dir, que esdist— relativo a la raíz — y cada ruta defileses relativa a ese directorio. Unrefusal, y cada entrada de susfindings, nombra sufilede forma relativa a la raíz, o lo retiene cuando el documento está fuera del workspace.advisories,deprecations,declined_external_inputsy cadamessagedelrefusalsiguen la regla del texto.pullnombrareleaseylockfilede forma relativa a la raíz.diagnosticseincomplete_external_inputssiguen la regla del texto. Lasourcede cada entrada deresolvedse responde completa en ambos transportes: nombra lo que hizo la ejecución, nunca un lugar del host.describenombra lareleasede una Release de forma relativa a la raíz, y elfilede una entidad de forma relativa a la raíz cuando su documento está dentro del workspace; una entidad leída desde un directorio de catálogo fuera del workspace tiene sufileretenido.mapping_diagnosticsydeprecationssiguen la regla del texto.lintnombra ellocation.filede cada hallazgo de forma relativa a la raíz, o lo retiene cuando la entidad está fuera del workspace. Elmessagey elsuggestde un hallazgo siguen la regla del texto.pinnombraentityylockde forma relativa a la raíz, y lo mismo hace elpinque lleva una publicación.gen-catalognombra cada archivo listado enoutputde forma relativa a la raíz.importretieneworkspace_root, youtput_dircuando los borradores fueron a esa raíz; un directorio que nombraste enoutput_dirse indica por su nombre relativo a la raíz. Cada ruta de borrador enwrittenydraftses relativa aoutput_dir, así que adónde fueron los borradores está en la respuesta en cualquier caso. Elmessagede un diagnóstico, y losparams_summary,rationaleyswap_hintde una decisión, son prosa que compuso el importador y siguen la regla del texto.config-showyplugin-listretienen más que la raíz, porque la mayor parte de lo que informan es configuración que nombra lugares, como expone Lo que un listener no te dice sobre su host.scaffold, al escribir un ejemplo, nombradirtal como lo enviaste, de forma relativa a la raíz, y cada ruta defilesde forma relativa a ese directorio; la redacción de borradores y el listado no nombran ningún lugar.- Las herramientas de publicación,
sign-artifacts,deprecate-artifact,get-schema,explain-errorydescribe-capabilitiesno nombran por sí mismas ningún lugar del host. El mensaje de un fallo de cualquiera de ellas sigue la regla del texto: el rechazo que genera un workspace sin conexión nombra su.aggrega-config.yamlde forma relativa a la raíz. - Un argumento de ruta rechazado por salir del workspace se rechaza sin nombrar la raíz ni el lugar al que habría llegado, como se indicó arriba.
Cómo termina una llamada
Cerrar la conexión cancela la llamada que transportaba. Esa es la señal de cancelación de este transporte: el servidor trata la desconexión de un llamante como la cancelación de esa solicitud, termina el trabajo que estaba haciendo y no escribe nada más para ella. Aquí no se necesita ni se espera ningún mensaje de cancelación — lo contrario de la entrada y salida estándar, donde no hay un flujo por solicitud que cerrar y un cliente termina una llamada nombrando en su lugar su id. Un mensaje de cancelación que llega igualmente por HTTP se acepta y no termina nada.
Detener el proceso vacía el listener. Una interrupción, o una solicitud de terminación de un supervisor o de un runtime de contenedores, hace que el listener deje de aceptar y permite que una llamada que ya se está respondiendo termine, dentro de un margen acotado, de modo que un llamante que pidió algo antes de la detención sigue recibiendo su respuesta. Una llamada que no ha terminado dentro de ese margen pierde su conexión. Una segunda solicitud de detención termina el proceso de inmediato.
Liveness y readiness, en una dirección propia
mcp.health.listen es donde un supervisor pregunta si este proceso está activo y si puede responder a una llamada. Dale una dirección en cualquiera de las formas anteriores y un segundo listener responde allí a GET /healthz y GET /readyz. Omítelo — que es el valor predeterminado — y no se inicia ningún segundo listener ni se responde a ninguna de las dos comprobaciones en ningún lugar.
Las dos respuestas dicen cosas distintas, y esa diferencia es la razón de que haya dos. /healthz recibe 200 desde el momento en que el proceso está en ejecución, que es todo lo que afirma la liveness: está activo, y un supervisor que no recibe ninguna respuesta debería reiniciarlo. /readyz recibe 503 hasta que el workspace que sirve este proceso se ha resuelto y el endpoint se ha enlazado, y 200 a partir de entonces — así un balanceador retiene el tráfico hasta que el proceso puede responder realmente a una llamada, en lugar de enviar la primera solicitud a uno que todavía está arrancando. Cada respuesta es un código de estado con un cuerpo vacío; no se pide ninguna credencial y no se lee nada de lo que envió el llamante.
El endpoint nunca responde a esas dos rutas. GET /healthz y GET /readyz en la dirección que nombra mcp.listen reciben 404, exactamente igual que cualquier otra ruta que ese endpoint no sirve, con token o sin él. Responder allí a una sonda le daría a cualquier cosa que llegue al endpoint una lectura gratuita de si el proceso está activo, junto con una forma gratuita de hacerlo trabajar — en un listener que, por lo demás, rechaza cada solicitud que no lleva credencial.
Dónde se encuentra la dirección de health lo eliges tú, y no está confinada como lo está mcp.listen. Ninguna dirección se rechaza para ella. Apúntala a loopback o a un socket Unix, que es para lo que existe: un supervisor, un balanceador o un runtime de contenedores que se ejecuta junto a este proceso en el mismo host. Cualquier cosa que pueda llegar a la dirección que elijas puede leer esas dos respuestas, así que una dirección a la que llega la red abierta las publica en la red abierta.
Nada se sirve sin una credencial
Cada solicitud al endpoint lleva una credencial, y cuál depende de si un proxy situado delante ya la ha comprobado. De forma predeterminada es un bearer token que este servidor verifica él mismo, descrito en el resto de esta sección. Configura mcp.authorization.trusted_proxy y pasa a ser un encabezado que define ese proxy, descrito en Leer el llamante desde un proxy situado delante — donde no se lee ningún token en absoluto. Ninguna de las dos formas sirve una solicitud que no presenta nada.
De forma predeterminada, el servidor comprueba él mismo un bearer token. Lee el token del encabezado Authorization y solo lo acepta si la firma se verifica con una clave que publica el servidor de autorización, el token nombra mcp.authorization.issuer como su emisor, nombra el propio mcp.authorization.resource de este despliegue entre sus audiencias, está dentro de su periodo de validez y dice quién lo presentó. Un token que no supera cualquiera de esas comprobaciones recibe 401, con error="invalid_token" añadido al mismo challenge que recibe un llamante que no lleva nada — y la respuesta es idéntica sea cual sea la comprobación que lo rechazó, de modo que un llamante aprende que necesita un token distinto y no qué parte del que envió era incorrecta. Solo se aceptan algoritmos de firma asimétricos: un token sin firmar, y uno que nombra un algoritmo simétrico, se rechazan antes de leer nada de él.
Un token puede decir qué tipo de token es, y se aceptan cuatro formas. Un JWT puede llevar un encabezado typ que nombra su propio tipo. Este servidor acepta at+jwt y application/at+jwt, las dos grafías registradas para un access token; JWT, que solo dice que el token es un JWT; y un token que no declara ningún tipo. Cualquier otra cosa recibe 401 exactamente igual que cualquier otro token rechazado. El conjunto es fijo y ningún ajuste lo amplía ni lo reduce, porque qué forma aparece ahí lo decide el servidor de autorización que emitió el token y no el despliegue que lo recibe. Aceptar JWT sí significa que el tipo declarado por sí solo ya no distingue un access token de un identity token — es la comprobación de audiencia la que los distingue, y por eso esa comprobación es la que sostiene todo: la audiencia de un identity token es el cliente al que se emitió, nunca el propio mcp.authorization.resource de este despliegue, así que un token emitido para cualquier cosa que no sea este despliegue se rechaza se llame como se llame.
Qué servidores de autorización admite eso. Microsoft Entra ID emite access tokens de tipo JWT. Keycloak emite at+jwt, y JWT cuando su modo de compatibilidad con OpenID Connect está activado. Auth0 emite JWT con su propio perfil de token y at+jwt con su perfil RFC 9068. Un token de cualquiera de ellos supera esta comprobación sea cual sea la de las dos formas que lleve. Okta no es compatible: sus access tokens declaran un tipo propio que no es ninguna de las cuatro formas anteriores, así que este servidor los rechaza.
Un token rechazado deja el motivo en el propio flujo de errores del servidor. Al llamante solo se le dice que lo que presentó no fue aceptado; el proceso de servicio escribe una línea que nombra la comprobación que rechazó el token — la audiencia, el emisor, el periodo de validez, la firma, el identificador de clave, el tipo declarado y cada una de las demás. Esa línea es lo que permite que un despliegue que rechaza cada solicitud pueda diagnosticarlo quien lo ejecuta y no solo quien lo llama. No contiene ninguna parte del token. Una solicitud que no presenta ninguna credencial no escribe ninguna línea, porque recibir un challenge es como un cliente averigua, de entrada, dónde obtener un token, así que es lo primero que hace todo cliente que se comporta correctamente.
Un token va en el encabezado y en ningún otro sitio. Uno enviado como parámetro de consulta access_token recibe 400 y nunca se lee, porque una dirección la registran cada log de proxy, cada historial de navegador y cada encabezado referrer por los que pasa la solicitud, así que un token que llegó de esa forma ya ha quedado expuesto. El servidor nunca escribe un token en un log, nunca envía uno a ninguna parte y nunca obtiene ni intercambia uno en nombre de un llamante: lee lo que se presentó, decide y no conserva nada. El sujeto que nombra el token se registra y no se compara con nada.
Las claves de verificación proceden del servidor de autorización, o de un archivo que nombres. Sin mcp.authorization.jwks_file configurado, el servidor lee los metadatos del servidor de autorización en su dirección well-known, sigue el jwks_uri publicado allí y conserva las claves que encuentra; un token firmado con un identificador de clave que esas claves no contienen provoca una relectura, y no más de una dentro de un intervalo corto, de modo que un llamante que envía identificadores de clave inventados no puede provocar una solicitud saliente por cada solicitud. Leerlas del servidor de autorización requiere una dirección de claves https, o una http sin cifrar en esta máquina: un jwks_uri que es http sin cifrar en otro host nunca se consulta, y no se sigue una redirección que enviaría cualquiera de las dos lecturas a http sin cifrar en otro host, porque quien esté en una ruta no protegida hacia las claves podría responder con claves propias. Un token que necesita esas claves recibe entonces 503, exactamente igual que con claves que no se pueden leer, y la línea que el servidor escribe para esa solicitud dice que la lectura se rechazó por ser http sin cifrar y no que el servidor de autorización no estuviera accesible — la solución está del lado del servidor de autorización, que tiene que publicar sus metadatos y claves por https. Con jwks_file configurado, las claves se leen de ese archivo y nunca se contacta con el servidor de autorización — que es lo que necesita un workspace que declara offline: true, y un workspace así se rechaza antes de que su listener se enlace a menos que se nombre el archivo. Cuando las claves no se pueden leer en absoluto, las solicitudes reciben 503 sin challenge: no se consideró deficiente nada de lo que presentó un llamante, así que volver a enviarlo con otro token no ayudaría.
La única respuesta que se da sin pedir ninguna credencial es el documento de metadatos del recurso protegido. Un cliente tiene que leerlo antes de poder tener un token, así que exigir uno ahí cerraría la única puerta de entrada. Se responde en /.well-known/oauth-protected-resource y — donde la dirección que indica mcp.authorization.resource tiene una ruta propia — también en esa ruta well-known con esa ruta añadida al final. Esos son los dos lugares donde mira un cliente, y la forma con la ruta añadida es la dirección que indica el challenge. El documento lleva esa dirección como el recurso con el que se denomina este despliegue, mcp.authorization.issuer como el servidor de autorización del que obtener un token, header como la única forma de presentar un token, y los tres nombres de scope que se indican abajo.
El issuer es una dirección https, salvo que el servidor de autorización se ejecute en esta máquina. Se acepta http simple para un issuer en localhost, 127.0.0.1 o ::1, que es la forma que toma una prueba local con un servidor de autorización local; un issuer en http simple en cualquier otro host se rechaza antes de que el listener se vincule, y el rechazo indica mcp.authorization.issuer y pide una dirección https. Esto se cumple en todos los modos — con las claves leídas del issuer, con mcp.authorization.jwks_file y con un proxy delante — porque todos los modos publican el issuer en este documento: un cliente que lo sigue ejecuta su flujo de autorización contra esa dirección, así que sobre http simple el código de autorización y el token que obtiene cruzarían la red sin protección, tanto si este servidor lee alguna vez una clave de ahí como si no. Donde sí lee sus claves de ahí, quien esté en esa ruta también podría responder con claves propias, y cualquier token firmado con ellas se admitiría.
Los nombres de scope que publica este despliegue son aggrega:read, aggrega:workspace-write y aggrega:registry-write. Son los nombres que hay que registrar en el servidor de autorización y los que un cliente le pide, y el challenge que recibe un llamador rechazado indica aggrega:read como el que debe obtener primero. Lo que admite cada uno — y el segundo límite, el que este despliegue se impone a sí mismo — se describe más abajo en Qué puede alcanzar un llamador.
Leer el llamador desde un proxy delante
Donde un proxy delante ya valida los tokens, mcp.authorization.trusted_proxy indica a este servidor que lea el llamador desde él en lugar de comprobar un token por segunda vez. Indica principal_header, la cabecera que ese proxy establece para decir quién es el llamador, y opcionalmente scopes_header, una segunda cabecera que lleva los scopes de ese llamador separados por espacios. Cada uno es un nombre de cabecera HTTP como X-Forwarded-User, sin espacios ni dos puntos; un nombre con cualquier otra forma se rechaza al cargar la configuración, indicando la clave, y lo mismo ocurre con un principal_header vacío — omite el bloque para dejar este modo desactivado. Esas dos cabeceras son las únicas que se leen: no interviene ninguna cabecera de dirección reenviada ni ninguna otra cabecera. Una solicitud que llega sin la cabecera del principal recibe 401, y en este modo no se lee ningún token — una solicitud con un token que este servidor habría rechazado en otro caso se atiende cuando su cabecera del principal está presente, y una con un token que este servidor habría aceptado se rechaza igualmente cuando esa cabecera falta.
Ese modo solo se acepta en loopback o en un socket Unix, y el proceso se rechaza antes de vincularse en cualquier otro lugar. Una cabecera es fiable exactamente cuando nada salvo el proxy puede establecerla. En una dirección que alcanza la red, cualquier cosa puede establecerla — así que un listener en este modo en una dirección así permitiría a cada llamador identificarse como quisiera. El rechazo indica las dos configuraciones en conflicto, para que puedas levantarlo moviendo la dirección o eliminando el bloque.
Lo que el proxy afirma es lo que este servidor cree, y ese es el trato. En este modo este servidor no comprueba ninguna firma y no compara el llamador afirmado con nada, exactamente igual que no compara con nada el subject de un token. Si el proxy validó lo que reenvió, y si algo puede alcanzar ese listener sin pasar por el proxy, le corresponde al despliegue hacerlo bien; el confinamiento descrito arriba es lo que hace posible hacerlo bien, no una garantía de que se haya hecho.
Establecer mcp.authorization.trusted_proxy no elimina los demás requisitos. issuer y resource siguen siendo necesarios, porque el documento de metadatos se sigue publicando y el challenge sigue indicándolo — un cliente detrás del proxy sigue teniendo que saber dónde obtener el token que el proxy comprobará. Por la misma razón el issuer sigue siendo una dirección https salvo que se ejecute en esta máquina: ese cliente obtiene su token del issuer, así que un issuer en http simple en otro host se rechaza antes de que el listener se vincule en este modo exactamente igual que en cualquier otro, aunque este servidor no lea nada de él.
Qué puede alcanzar un llamador
Dos límites deciden lo que alcanza un llamador por HTTP, y los fijan personas distintas. La credencial propia del llamador es el primero; lo que este servidor ofrece en absoluto es el segundo. Ambos se leen antes de que se ejecute nada, a partir de una declaración que cada operación hace sobre sí misma, y llegan a un cliente en lugares distintos: la lista de tools muestra lo que este servidor ofrece y anuncia, y la respuesta que recibe cada llamada muestra lo que la credencial admite.
Cada operación declara hasta dónde llegan sus propios efectos, y hay cuatro tipos, el más amplio al final:
- No alcanza nada — lee una definición, inspecciona lo que fija una Release, renderiza artefactos en memoria y los devuelve. No deja nada atrás: no se escribe nada, y la respuesta es todo lo que produce.
- Alcanza el workspace — escribe dentro del workspace que sirve este proceso: el lockfile de una Release, la caché de artefactos, entidades generadas, un documento editado.
- Alcanza un registro — publica, firma o adjunta un marcador de retirada a algo ya publicado. Lo que cambia es lo que resuelve cada consumidor de ese registro, y nada de ello puede recuperarse de quien ya lo haya descargado.
- Alcanza la máquina — cambia lo que comparten todos los workspaces del host, entre ellos el almacén de módulos compilados, el archivo de configuración común a todos ellos y el almacén de credenciales. Una caché que un solo proyecto mantiene en su propio directorio de caché no es de este tipo, y
cache-statusinforma de cuál de estos tipos tiene cada caché que lista.
El tipo es una propiedad de la operación y no del tool que la ofrece, y abarca lo que la operación deja atrás — no dónde pone una superficie la respuesta que devuelve. Renderizar una Release produce artefactos como respuesta, así que no alcanza nada; una línea de comandos que luego guarda esos artefactos en un directorio que tú indicaste está entregando esa respuesta, no llegando más lejos. Leído al revés, cada operación que responde con contenido tomaría el tipo de la superficie que resultara guardarlo, y el tipo dejaría por completo de ser una propiedad de la operación. Por la misma razón, describe leyendo una entidad por su referencia de registro no alcanza nada: contacta ese registro para obtener su respuesta y no deja nada atrás, ni en el registro ni en esta máquina, y qué registros puede contactar se explica en Qué credenciales gasta una llamada. Una llamada puede llegar aun así más lejos que el tipo de su operación, cuando la propia llamada pide una escritura: una build enviada con write guarda sus artefactos en el workspace que sirve este servidor, así que esa llamada alcanza el workspace, igual que una build que primero resuelve sus dependencias.
Un scope admite un tipo, y cada scope de escritura implica el scope de lectura. aggrega:read admite una operación que no alcanza nada. aggrega:workspace-write admite una que alcanza el workspace, e implica el scope de lectura. aggrega:registry-write admite una que alcanza un registro, e implica también el scope de lectura. Así, un cliente pide a su servidor de autorización el scope de escritura que necesita y no tiene que pedir además el scope de lectura.
Ningún scope admite el tipo máquina, y ninguna configuración añade uno. Las operaciones de ese tipo solo las ofrecen los tools que ejecutan un comando aggrega en un proceso separado, y un servidor alcanzado por HTTP no ofrece ninguno de ellos, por la razón dada arriba en Alcanzar el servidor por HTTPS. Ejecútalas en un terminal en el host.
La lista de tools muestra cada tool que este servidor ofrece y anuncia, sean cuales sean los scopes que tenga la credencial que llama, y la credencial decide cuáles de ellos puede ejecutar una llamada. describe-capabilities indexa y define ese mismo conjunto. Una llamada que la credencial no admite recibe 403 con error="insufficient_scope" en el challenge, que indica el único scope que la admitiría, y no se ha ejecutado nada de lo que pidió la llamada. Ese rechazo es el que responde el step-up del protocolo: un cliente que implementa step-up te pide que vuelvas a iniciar sesión para el scope que indica el challenge. La lista no cambia con la credencial, así que un cliente que ha vuelto a iniciar sesión ya tiene la correcta. Una credencial que no lleva ninguno de los tres scopes recibe la misma lista de tools y no puede llamar a ninguno de los tools que contiene, describe-capabilities incluido.
Una build es el caso que conviene conocer. Por sí misma no cambia nada y por eso solo necesita aggrega:read, pero una build que escribe necesita aggrega:workspace-write: una enviada con write guarda sus artefactos en dist/ en la raíz del workspace, y una que primero resuelve sus dependencias escribe el lockfile — tanto si la llamada lo pidió con auto_pull como si lo hizo la configuración auto_pull del propio workspace. El tool se lista a un llamador con scope de lectura como cualquier otro tool, y las builds que se quedan en memoria están realmente disponibles para él; lo que se rechaza, indicando aggrega:workspace-write, es la llamada que escribe.
A un cliente que no hace step-up se le pueden dar igualmente los scopes de escritura, y eso se resuelve en el servidor de autorización. Quien administra el servidor de autorización convierte los scopes de escritura en scopes predeterminados para ese cliente — scopes que pone en cada token que emite para ese cliente, los haya pedido el cliente o no — de modo que el token que obtiene su primer inicio de sesión ya los lleva. Un cliente que se registra de nuevo en el servidor de autorización cada vez que se conecta es allí un cliente nuevo cada vez, y una configuración hecha en un registro anterior no se conserva; para un cliente así, la configuración que surte efecto es el conjunto de scopes predeterminados que el servidor de autorización da a cada cliente que registra. El coste es que cada inicio de sesión a través de ese cliente lleva entonces alcance de escritura, lo necesite o no el trabajo en curso — y donde los predeterminados son los que se dan en el registro, cada cliente registrado de esa forma lleva también ese alcance. Haz predeterminado solo el scope de escritura que necesita ese trabajo: aggrega:workspace-write y aggrega:registry-write admiten tipos distintos, y ninguno implica al otro.
mcp.deny_reach es donde quien administra este servidor le retira un tipo, y es una de las dos configuraciones que acortan la lista de tools. Lista los tipos — none, workspace, registry, machine — que este servidor no ofrece, y cada tool que alcanza uno de ellos queda ausente de la lista de tools de cada llamador y de describe-capabilities diga lo que diga el token de ese llamador, y se rechaza si se llama igualmente, con un error que indica esta configuración. Es el límite propio del servidor y no el del llamador, así que ninguna credencial lo levanta y el rechazo no lleva challenge: un servidor pensado para atender lecturas y nada más lista aquí workspace, registry y machine, y entonces no puede publicar ni siquiera para un llamador cuyo token lleva los tres scopes. Omítela, que es lo predeterminado, y este servidor no retira ningún tipo, así que los tipos que alcanza una llamada los deciden los propios scopes del llamador. Indicar machine se acepta y no cambia nada, ya que aquí no se ofrece nada de ese tipo de entrada. Un valor que no sea uno de los cuatro se rechaza al cargar la configuración, en lugar de pasarse por alto — un operador que escribe mal un tipo ha pedido un límite, y que se le atienda en silencio sin él es la forma equivocada de responder a eso.
mcp.announce_tools es la otra configuración que acorta la lista de tools, y las dos no son el mismo límite. deny_reach retira una capacidad: una operación de un tipo indicado ahí no se ofrece aquí en absoluto, para nadie. announce_tools retira solo un anuncio: los tools que deja fuera son capacidades que este servidor sigue teniendo, y a lo que responde es al tope propio de un cliente sobre cuántos tools registrará. Donde se establecen ambas gana la retirada, así que un tool de un tipo retirado sigue ausente se indique como se indique en announce_tools, y el rechazo que encuentra un llamador indica la retirada. Nada de lo que acorta la lista lee los scopes del llamador: un scope que le falta al llamador rechaza una llamada y nunca quita un tool de la lista. Restringir lo que anuncia el servidor describe el resto.
Qué credenciales gasta una llamada
La firma keyless sobre un listener toma su identidad del identity_token que lleva la llamada, y de nada más. Un token enviado en la llamada es una credencial que tiene el llamador: tuvo que obtenerlo, está vinculado a él, y la firma que produce le es atribuible. Cualquier otro lugar del que pudiera venir una identidad pertenece a quien inició este proceso, así que en este transporte la resolución recibe un entorno que no responde nada. AGGREGA_IDENTITY_TOKEN y SIGSTORE_ID_TOKEN en el entorno del servidor no se leen, y no se alcanza el endpoint OIDC ambiental de GitHub Actions. Están fuera de alcance, no desaconsejados — no hay nada que la resolución pueda encontrar. Una llamada que no envía ningún identity_token se rechaza, y el rechazo indica identity_token como lo que hay que enviar y no indica ninguna variable ni ningún endpoint: un llamador que no está ante el teclado de esta máquina no puede exportar nada aquí, así que indicarle una sería decirle que prepare algo que no puede cambiar la respuesta.
Una clave de firma guardada en esta máquina no se puede seleccionar por ninguna de las dos vías. key_path se rechaza antes de que se resuelva nada, y no aparece en los esquemas de argumentos que publish-entity, sign-artifacts y deprecate-artifact anuncian aquí, de modo que a un llamador nunca se le ofrece un argumento que no podría tener éxito. Tampoco se alcanza la clave de firma que indica la configuración propia del workspace servido — signing.key_path, tanto si está establecida para el workspace en su conjunto, como para un registro concreto, como si se proporciona desde el entorno. Una sola razón cubre ambos casos: una ruta de clave no es una credencial, es un nombre para un secreto que este servidor guarda. Un llamador que proporciona una no demuestra nada, cualquiera que alcanzara esta dirección podría proporcionar el mismo nombre, y la firma resultante diría que es el operador quien responde por el artefacto y no el llamador. Cerrar el argumento dejando abierta la configuración sería cerrar una puerta a una habitación que la otra sigue abriendo. Así que la firma con clave es inalcanzable sobre un listener: solo firma un token enviado en la llamada.
fulcio_url, rekor_url y timestamp_url no se ven afectados y siguen disponibles en ambos transportes. Indican servicios que contactar y no algo que guarde esta máquina, así que un llamador que no puede seleccionar una clave firma igualmente contra los endpoints que configura este despliegue.
Un listener iniciado sobre un workspace que indica una clave de firma lo dice una vez, al arrancar. El proceso escribe una línea en su propio flujo de errores que indica la configuración y dice que un llamador que alcanza este listener no puede gastar esa clave — así un operador lo sabe por el proceso que inició y no por una firma que no esperaba. Un workspace que no indica ninguna clave no produce esa línea, porque no hay nada que decir al respecto. La línea lleva el nombre de la configuración y ni la clave ni nada sobre el archivo al que apunta.
Sobre la entrada y la salida estándar no se aplica nada de lo anterior. Ahí el entorno se lee y key_path selecciona una clave guardada en esta máquina, porque el cliente que lanzó este servidor se ejecuta en la propia máquina del llamador y lo que ese proceso puede alcanzar le corresponde gastarlo a ese mismo llamador.
Leer una entidad por su referencia de registro contacta un solo registro, con el inicio de sesión propio de este host, y sobre un listener solo un registro con el que el workspace servido está configurado. describe enviado con una referencia oci:// como name lee la entidad publicada en esa coordenada — la misma lectura que realiza aggrega inspect — del único registro que indica la referencia, usando el inicio de sesión que este host ya tiene para ese registro. La llamada no lleva ninguna credencial, y describe no acepta ninguna. Por HTTP el registro debe ser uno con el que el workspace servido está configurado: el host que indica su default_registry, o un host listado en registries, comparado exactamente y con el puerto. Una referencia a cualquier otro host — incluida una dirección en esta máquina — se rechaza antes de contactar ese host, y el rechazo indica el host, así que un llamador no puede dirigir este servidor a un destino de su elección. Lo que sigue siendo alcanzable es deliberado: un llamador que tiene aggrega:read puede leer todo lo que el inicio de sesión de este host puede leer en un registro con el que el workspace está configurado, que es también lo que puede leer una persona en el terminal de este host. Sobre la entrada y la salida estándar se lee una referencia a cualquier registro, como en la línea de comandos. Describir una entidad por su nombre de catálogo no se ve afectado.
Una llamada a un registro usa el almacén de credenciales del usuario del sistema operativo con el que se ejecuta este proceso, exactamente como lo hace la misma llamada en un terminal de este host. No hay ninguna fuente de credenciales por workspace ni ninguna configuración que añada una, y por eso registry-list informa del estado de las credenciales de un host de la misma forma en cada workspace de esta máquina. Un despliegue que quiere que distintos workspaces tengan distintas credenciales de registro los ejecuta como distintos usuarios del sistema operativo — un proceso por workspace, cada uno iniciado como su propio usuario. De ahí viene la separación, y prepararla le corresponde al operador.
Qué registra el servidor
Cada solicitud que responde este endpoint deja una línea en el flujo de errores del proceso, y esa línea es un único objeto JSON. Lleva el time en que se escribió y un request_id que este proceso generó para la llamada y que no devuelve al llamador; subject e issuer tal como los afirmó la credencial presentada, con client_id donde indicaba uno; workspace_root, el workspace que sirve este proceso; method, y target donde el método se dirige a algo por su nombre; reach, el tipo que declara la operación, y reach_escalated_to donde la llamada llegó más lejos; outcome; duration_ms; y transport. Un campo sin nada que decir se omite en lugar de escribirse vacío, así que un client_id ausente es una credencial que no indicaba ningún cliente, y un reach_escalated_to ausente es una llamada que alcanzó exactamente lo que declara su operación.
outcome dice qué fue de la llamada, y los valores son distintos para que puedas contarlos por separado. ok se ejecutó y tuvo éxito. tool-failure se ejecutó y volvió marcada como un fallo que el llamador puede corregir — una llamada que este servidor atendió y no una que rechazó, así que no corresponde contarla entre tus rechazos. error es un rechazo devuelto como sobre de error del protocolo. unauthenticated, forbidden y rate-capped son la credencial, el límite de origen o de scope y el tope de frecuencia por llamador rechazando una solicitud. cancelled es un llamador que cerró su conexión antes de recibir respuesta.
El motivo por el que se rechazó una credencial es un campo de esa misma línea y no una línea propia. Una solicitud rechazada deja un registro como cualquier otra, con refusal indicando la comprobación que la rechazó. Ninguna credencial, ni parte de ella, llega a ninguna línea — ni en un rechazo ni en una llamada atendida.
Un llamador que no presentó nada en absoluto no deja ninguna línea. Recibir un challenge es la forma en que un cliente descubre dónde obtener un token, así que es lo primero que hace todo cliente bien hecho, y una línea por cada uno de ellos enterraría los rechazos que significan algo. Una solicitud que indica una ruta o un método que este endpoint no atiende tampoco deja ninguna: ambas cosas se resuelven antes de leer nada sobre un llamador, así que escanear la dirección no escribe nada en lo que recoge el flujo.
El contexto de traza que envía un cliente se copia literalmente en la línea. traceparent, y junto a él tracestate y baggage donde también se envían, se transmiten exactamente como se recibieron, de modo que lo que recoge este flujo puede unirlo a los registros propios del llamador. Una solicitud que no envía ninguno, o que envía uno que no es un contexto de traza W3C bien formado, produce una línea sin esas claves: no se inventa nada, y no se altera nada por el camino.
El proceso registra su propia vida con la misma forma y en el mismo flujo, y cada una de esas líneas indica un event donde una línea de solicitud indica un método y un llamador: startup al empezar, listening con la dirección a la que se vinculó, startup-refused con el motivo por el que se rechazó un arranque antes de atender, signing-key-ignored donde el workspace que sirve indica una clave de firma que ningún llamador que alcance este listener puede gastar, docs-bundle con el resultado de obtener el paquete de documentación, y shutdown al terminar la ejecución. La presencia de event es lo que distingue los dos tipos de línea.
Todo ello lo recoges del flujo de errores del proceso, y esa es toda la entrega. No hay ningún exportador que configurar, ningún archivo que indicar y ninguna configuración que active, desactive o redirija nada de ello: lo que supervisa este proceso — un runtime de contenedores, un gestor de servicios, un enviador de logs — es lo que recoge ese flujo, y donde lo consultas después. Sobre la entrada y la salida estándar el mismo flujo lleva en su lugar prosa legible, porque el cliente que lo lee lanzó el proceso y está en la misma máquina.
Nada de ello se envía al llamador. El servidor no publica ningún flujo de logs por el protocolo en ninguno de los dos transportes, y una solicitud que lleva el campo de nivel de log por solicitud del protocolo recibe exactamente la misma respuesta que una que no lo lleva: lo que se registra aquí es del operador, y va solo al flujo del operador.
Qué le dice el servidor al modelo cuando se conecta
El servidor ofrece un bloque de orientaciones para el modelo, que tu cliente puede presentarle antes de la primera llamada. Un cliente en 2026-07-28 lo lee de la respuesta a server/discover; un cliente en 2025-06-18 lo lee de la respuesta a su handshake initialize. Es el mismo texto por ambas vías, byte a byte, y el mismo texto para cada cliente que alcanza un proceso: nada en él se negocia, y nada se deriva de lo que envió el cliente ni de la credencial que presentó, así que lo que se le dice a un modelo al conectarse no varía entre sesiones ni entre clientes.
Dos cosas varían, y ninguna es el cliente. El párrafo final se compone para el transporte que sirve un proceso, así que un servidor que habla por la entrada y la salida estándar y un listener entregan a un modelo un texto final distinto. Y donde el paquete de escritorio que lanzó un servidor procede de una versión distinta de la del ejecutable aggrega que lanzó, las orientaciones empiezan con la única frase que lo dice, indicando ambas versiones — la frase con la que empieza la respuesta de describe-capabilities sin argumentos, como explica De qué versión procede el servidor; un arranque que no hizo ningún paquete, y uno cuyo paquete procede de la versión del propio ejecutable, entregan las orientaciones sin ella. Ambas cosas se fijan al iniciarse el proceso, y dentro de cada proceso las dos revisiones siguen sirviendo de forma idéntica el texto propio de ese proceso.
Enseña el modelo mental que el esquema de argumentos de un tool no puede transmitir por sí solo:
- Lo que hace el compilador, y lo que deliberadamente no hace — que enruta texto y evalúa coincidencias de etiquetas en lugar de interpretar lo que significa un valor, que no tiene opiniones propias sobre el contenido que pones en tus documentos, y que al compilar nunca se autentica con un proveedor, nunca lee el estado de un clúster y nunca convierte un secreto en texto plano. Un valor que solo existe una vez que la infraestructura está en ejecución viaja como una cadena puntero que el entorno de destino rellena más tarde.
- El vocabulario de autoría, y cómo se relacionan los tipos — para qué sirve cada tipo y contra cuál se ejecuta realmente una build, de modo que un asistente no tenga que inferir la forma de un despliegue a partir de la lista de tools.
- El orden en que se ejecuta el ciclo de autoría — leer el contrato, generar la estructura a partir de él, inspeccionar aquello a lo que te conectas y luego comprobar antes de renderizar.
- Cuándo recurrir a un prompt en lugar de a un tool — un tool para actuar, un prompt para enmarcar una tarea.
- Que la lista de tools es toda la superficie — cada tool que ofrece este servidor está en ella, y qué tools ofrece un servidor depende de cómo se configuró, así que un asistente lee lo que hay a partir de esa lista y de
describe-capabilitiesen lugar de ir a buscar una segunda. Donde la conexión presentó una credencial, dice que la credencial decide cuáles de esos tools puede ejecutar una llamada y nunca cuáles se listan: una llamada que no admite se rechaza indicando el scope que la admitiría, y el cliente puede volver a iniciar sesión para ese scope. - Qué significa un workspace vacío, y qué puede hacer el modelo al respecto — el párrafo que difiere según el transporte, más abajo.
Indica las superficies en lugar de repetirlas. Cada tool ya lleva su propia descripción y su esquema de argumentos en tools/list, y el contrato de cada tipo ya vive en su esquema y en su página de referencia, así que las orientaciones remiten a ellos y se detienen — un solo lugar por afirmación. Un tool que nombran es un tool que el servidor sirve, y remiten a cada familia de recursos que resuelve la superficie de lectura, de modo que nada hacia lo que envían a un asistente es un callejón sin salida.
No contiene ningún índice de los propios tools, y esa es la misma regla, no una omisión de ella. Un cliente tiene la definición de cada tool desde tools/list antes de leer una sola palabra de este texto, así que una línea por tool aquí sería una segunda copia de propósitos que ya tiene — pagada en cada sesión, por cada cliente, y libre de discrepar de la lista de tools en el momento en que se editara cualquiera de las dos.
También indica lo que no enumera, y por qué: los destinos de renderizado disponibles y los tipos de biblioteca instalados son propiedades de tus plugins y de tu conjunto de esquemas, así que las superficies de recursos los informan directamente en lugar de que las orientaciones lleven una copia que podría discrepar.
Qué se le dice a un modelo sobre un workspace vacío
El párrafo final responde a la pregunta que un modelo encuentra primero en un workspace que no contiene nada: qué significa un list-entities vacío, y qué puede hacer al respecto. Su comienzo es el mismo en ambos transportes — una lista vacía significa que el workspace que resolvió este proceso no contiene documentos Aggrega que pueda leer y que los directorios de catálogo configurados junto a él tampoco declaran ninguno — y lo que sigue depende del transporte que sirve este proceso, porque la respuesta honesta no es la misma en los dos.
Sobre la entrada y la salida estándar se le dice al modelo que el workspace es suyo para inspeccionarlo y repararlo. Se le dice dónde se responde una llamada que no indica ningún workspace — en la carpeta con la que se lanzó el servidor, donde se lanzó con una, y si no en el workspace encontrado a partir de la carpeta en la que se inició, que puede ser esa misma carpeta — y que workspace_root en una llamada indica otro. Se le remite a config-show para la configuración vigente y qué capa decidió cada ajuste, y a cli-config-init para inicializar una que funcione; ambos están en la lista de tools en ese transporte. El cliente que ejecuta el servidor está en la propia máquina del llamador, así que lo que ese proceso puede alcanzar le corresponde gastarlo a ese mismo llamador — y donde fijas el límite es donde se fija para cualquier otro tool, en tu cliente MCP, como explica Qué puede hacer un asistente sin preguntarte antes.
Por HTTP se le dice al modelo que informe en lugar de configurar. El workspace es aquel sobre el que iniciaste el proceso y queda fijo durante toda su vida; una llamada que indica workspace_root o catalog_dirs se rechaza, indicando el argumento; y aquí no se ofrece a ningún llamador ningún tool que escriba configuración, sean cuales sean los scopes que lleve su credencial. Esas operaciones solo las ofrecen los tools que ejecutan un comando aggrega en un proceso separado, y una sesión alcanzada por HTTP se compone sin ellos — así que el límite es la composición y no un scope, y ningún token lo amplía. Un modelo que alcanza tu despliegue a través de un listener no puede, por tanto, inicializar un registro ni reescribir una política de confianza en tu host, y el párrafo se lo dice en lugar de dejar que lo intente y lea el rechazo.
Qué puede hacer un asistente sin preguntarte antes
Un asistente conectado a este servidor por la entrada y la salida estándar puede llamar a cada tool que expone el servidor, sin preguntarte, a menos que tu cliente esté configurado para denegarlo. En ese transporte el servidor ofrece los tools y no decide cuáles de ellos puede usar una llamada concreta: esa decisión es de tu cliente, y te corresponde tomarla ahí. Por HTTP no es lo mismo: el servidor lista cada tool que ofrece y anuncia, y rechaza una llamada que los scopes del token que llama no admiten, así que el límite es del servidor además de del cliente.
Esto importa porque la superficie de tools es la línea de comandos. Todo lo que puedes escribir, un asistente puede llamarlo — incluidas las operaciones que cambian tu máquina.
Algunas de esas operaciones llegan más allá del workspace en el que estás trabajando, y no se pueden deshacer ejecutando otra cosa. Estas son las que conviene conocer por su nombre, empezando por la de mayor alcance:
publish-entity,publish-artifact,sign-artifactsydeprecate-artifactllegan por completo más allá de la máquina. Ponen bytes, una firma o un marcador de retirada en un registro, así que lo que cambian es lo que resuelve cada consumidor de ese registro — no solo lo que hace esta máquina. Volver a publicar contenido distinto sobre una etiqueta se rechaza en lugar de ofrecerse, así que nada aquí deshace una publicación; la respuesta es publicar una nueva versión. Una firma y un marcador de retirada dejan intactos los bytes del artefacto, pero cualquiera que descargue ese artefacto después los descarga también, y ninguno de los dos puede recuperarse de quien ya lo tenga. Sobre la entrada y la salida estándar las mismas cuatro capacidades también son alcanzables comocli-push,cli-push-artifact,cli-signycli-deprecate, que ejecutan los comandos; por HTTP esos cuatro tools no existen.- La firma usa credenciales. Sobre la entrada y la salida estándar, la firma keyless toma un token de identidad del argumento
identity_tokende la llamada, deAGGREGA_IDENTITY_TOKENoSIGSTORE_ID_TOKENen el entorno del servidor, o del endpoint OIDC ambiental de GitHub Actions donde haya uno alcanzable;key_pathselecciona en su lugar una clave guardada sin conexión. Un asistente que puede llamar a estos tools puede, por tanto, firmar como tú, con cualquier identidad que ya tenga la máquina que ejecuta el servidor — y una firma es una declaración sobre quién responde por un artefacto, por eso esta es la operación sobre la que más hay que pensar antes de permitirla. Sobre un listener solo firma un token enviado en la llamada: no se lee nada del entorno del servidor, y ninguna clave guardada en el host puede seleccionarse mediante un argumento ni mediante la configuración del workspace servido, como explica Qué credenciales gasta una llamada. aggrega cache evictrecorta el almacén de módulos compilados, yaggrega cache clearlo vacía. Ese almacén lo comparte cada proyecto Aggrega de la máquina. Los módulos eliminados de él se recompilan bajo demanda, así que nada se pierde de forma permanente — pero la siguiente build de cualquier proyecto paga ese coste.aggrega cache cleartambién elimina el paquete de documentación que lee cada proyecto de la máquina, que se vuelve a descargar la próxima vez que uno de ellos lo obtiene.aggrega cache prunelibera las entradas de la caché de artefactos a las que no hace referencia ningún lockfile. Donde el lockfile de un proyecto no está presente para leerse, sus artefactos fijados no están protegidos por él, y liberarlos significa tener que volver a descargarlos.aggrega registry addyaggrega registry removeescriben de forma predeterminada en la configuración compartida por todos los workspaces, así que cambian lo que se resuelve en toda la máquina, no solo aquí.aggrega registry addtambién pide al registro que indica la política de confianza que ese registro anuncia y fija lo que recibe, exactamente como lo hace en un terminal. En un workspace sin conexión esa obtención se rechaza antes de establecer ninguna conexión, así que añadir un registro distinto del hub oficial se rechaza — código cortoE0310, con las mismas palabras — a menos que la llamada proporcioneidentityokey;aggrega config init, que no acepta ninguno de los dos, solo puede inicializar el hub sin conexión. Sobre la entrada y la salida estándar son alcanzables comocli-registry-addycli-registry-remove, y la inicialización comocli-config-init, que ejecutan los comandos; por HTTP esos tools no existen.pulllee de un registro y escribe dentro del workspace al que se dirige. Escribe el lockfile de esa Release, llena la caché de artefactos con lo que resolvió, y registra junto al lockfile la identidad de cada plugin que devuelve veredictos que tu workspace adjunta. Enviado conpin_sources— o en un workspace cuyopin_sources_at_pullestá activado y con una llamada que no lo envía como false — también ejecuta el paso de pin del autor de la entidad sobre las Recipes y las FeatureRecipes que la Release construye a partir de tus directorios de catálogo, escribiendo elentity.lockjunto a cada una; sin ello, un pull sobre una entidad así cuyo lock no registra ningún pin para una entrada que lee se rechaza, indicando el paso. Los propios archivos de entidad nunca se escriben. Nada de ello sale de la máquina, y volver a resolver es la forma de cambiar lo que registró, así que esta es la más leve de las operaciones de aquí que escriben. Es uno de los tools pensados para el ciclo de autoría que escriben dentro del workspace:pinescribe elentity.lockjunto a la Recipe o FeatureRecipe que indiques, como explica Fijar las entradas propias de una entidad;gen-catalogescribe entidades Plugin generadas en el directorio que indiques;edit-documentaplica una edición estructurada y acotada a un documento que ya tienes y lo vuelve a escribir, conservando cada byte que la edición no toca, como explica Aplicar una edición acotada a un documento; eimportconvierte una descripción producida por otra herramienta en archivos de autoría en borrador y los escribe en el workspace, como explica Convertir una descripción externa en entidades en borrador; yscaffold, enviado conexample, escribe uno de los ejemplos ejecutables de la documentación en un directorio nuevo o vacío,dir, como haceaggrega scaffold --example, algo que por HTTP admite el scope de escritura en el workspace. Ese directorio de salida, el guest que leegen-catalogy cualquier overlay que le des son cada uno relativos a la raíz del workspace, o absolutos sobre la entrada y la salida estándar, el mismo contrato que usa cualquier otro argumento de ruta en esta superficie. Sobre la entrada y la salida estándar la misma capacidad también es alcanzable comocli-pull, que ejecuta el comando; por HTTP ese tool no existe.buildlee el mismo registro y realiza la misma escritura cuando le envíasauto_pull, y solo entonces. Resolver las dependencias de una Release es una única operación dondequiera que se pida, así que una build a la que se le dice que resuelva primero hace exactamente lo que hacepully luego renderiza contra lo que escribió — por eso lleva el mismo alcance y no uno menor. Enviada conwrite, también escribe los artefactos renderizados endist/en la raíz del workspace, donde los escribeaggrega buildy mediante la misma escritura, así que alcanza el workspace en esa llamada; no escribe en ningún otro lugar, y undistque es un enlace que sale del workspace se rechaza antes de que se elimine o escriba nada en él. Sin ninguno de los dos argumentos, que es lo predeterminado,buildrenderiza a partir de los pins que el workspace ya tiene y no alcanza nada. Lee Hacer una build contra el contenido que una Release ya fija para saber qué cambia el argumento y qué deja igual.
Los tools de inventario lo dicen en sus propias respuestas. cache-status marca cada clase de caché con su alcance — workspace para la caché de artefactos en el propio directorio de caché de este proyecto, machine para los almacenes que comparten todos los proyectos — e indica expresamente los que abarcan toda la máquina, de modo que a un asistente que lee el inventario antes de proponer una limpieza se le dice qué partes no son solo tuyas. Las operaciones de mantenimiento informan del mismo alcance para cada elemento que eliminaron. Cada uno de los cuatro resultados de publicación lleva su propio reach, que contiene registries — cada host de registro al que se dirigió la llamada, cada uno indicado una vez, en el orden en que se dirigió a ellos por primera vez — y beyond_this_machine, que se deduce de lo que la llamada adjuntó realmente y no de lo que pidió: true en cuanto ha subido contenido o adjuntado una firma, una fecha de publicación o un marcador de obsolescencia, y false para una ejecución de prueba y para una llamada que lo encontró todo ya presente, como una publicación ejecutada de nuevo sobre una versión completa o un lote de firma cuyas referencias ya estaban todas firmadas.
Dónde fijas el límite. El propio protocolo no define permisos por tool — su autenticación trata de si un cliente puede conectarse siquiera, no de qué tools puede llamar después. La decisión de permisos reside en tu cliente MCP. Los clientes de uso extendido pueden en general permitir y denegar tools concretos por nombre de un mismo servidor, y desactivar un servidor por completo para un proyecto determinado; el nombre y la ubicación de la configuración difieren según el cliente, así que consulta la documentación de tu cliente sobre los permisos de tools. Si quieres las lecturas y no las escrituras, permite ahí los tools que quieras y deniega el resto. Una configuración permisiva, o un cliente sin una configuración así, deja invocable cada tool expuesto.
Averiguar qué contiene un espacio de trabajo
La mayoría de las herramientas toman un sujeto: el nombre de una entidad o la ruta de una Release. Las dos siguientes no toman ninguno, y son la forma en que un asistente que acaba de llegar obtiene uno.
list-entities responde qué contiene el espacio de trabajo y list-releases responde la pregunta más concreta que el resto de la superficie no deja de hacer: qué Releases hay. Ninguna de las dos toma un sujeto, porque lo que contiene un espacio de trabajo es una propiedad del espacio de trabajo y no de algo que quien llama tenga que conocer primero.
Cada una responde en una de dos formas, y una llamada que no indica ninguna forma recibe el resumen. Ese valor predeterminado es exclusivo de estas dos, y es el opuesto al que adoptan build, describe y validate. A aquellas se les pregunta por un sujeto que quien llama ya ha nombrado, así que la respuesta más completa es la que se pidió y la concisa es la opcional. A estas dos se les pregunta qué hay aquí, por parte de quien todavía no tiene nada que nombrar ni forma de saber cuánto costará la respuesta antes de que llegue, así que primero informan del tamaño y la forma del espacio de trabajo y solo entregan registros cuando se les piden.
El resumen dice qué hay aquí y cuánto. list-entities informa de la raíz del espacio de trabajo —retenida sobre HTTP, como explica Qué dice una respuesta sobre el sistema de archivos del servidor—, el número total de entidades y un recuento por tipo; list-releases informa del total y de un recuento por directorio de primer nivel, de modo que sabes cuántas Releases hay y en qué parte del árbol se encuentran. Ambos desgloses se leen de los propios documentos, así que un espacio de trabajo organizado de una forma que nadie previó se resume con la misma precisión que uno que no lo está. Ambos contienen una fila por tipo, o por directorio de primer nivel, así que su tamaño depende de cuántos tipos declara un espacio de trabajo y en cuántos directorios están sus Releases, no de cuántos documentos contiene: multiplica por cien los documentos de un espacio de trabajo, sin cambiar sus tipos, y el resumen solo crece los pocos bytes que ocupa escribir los números más grandes. Lo que lo alarga es declarar más tipos. Ninguno de los dos es una primera página de registros, y esa es precisamente la diferencia: «aquí hay algunas de las entidades» es una respuesta distinta de «esto es de lo que está hecho el espacio de trabajo», y solo la segunda te dice si quieres algún registro, y cuáles.
Envía response_format: detailed para obtener los registros, que llegan de página en página. list-entities informa entonces del tipo, el nombre, la apiVersion, la descripción, las etiquetas y el archivo de origen de cada entidad, leídos directamente del documento que la declara. También informa de las Features que declaran tus directorios de catálogo configurados, de modo que una Feature que se te ofrece como acoplable sea también una que puedes consultar; estas no tienen archivo de origen, porque la única ruta que tienen está en la máquina donde se ejecuta el servidor, y cada una dice de dónde procede, de modo que un archivo vacío se lee como «resuelto desde el catálogo» y no como un valor que falta. list-releases informa de la ruta de cada Release, y lockfiles asigna a cada ruta devuelta la ruta del lockfile de esa Release, en la misma coordenada: el archivo que pull escribe para ella y que build lee, el mismo archivo que nombran las respuestas del servidor de lenguaje sobre la Release. El mapa describe las rutas que lleva esta respuesta, así que sigue a la página, y el resumen lo lleva vacío.
detailed y concise son los únicos valores que admite response_format, y se comparan de forma exacta. Cualquier otra grafía —una palabra distinta, mayúsculas y minúsculas distintas o espacios alrededor de uno de ellos— se rechaza, y el rechazo nombra lo que se envió junto con los valores que acepta el argumento. Omitir response_format es la forma de pedir el valor predeterminado, que para estas dos herramientas es el resumen. Lo mismo vale dondequiera que aparezca el argumento: build, describe y validate admiten los mismos dos valores en las mismas condiciones, y su valor predeterminado es la forma más completa y no la concisa.
Los registros están limitados tanto si los limitas como si no. limit es cuántos lleva una respuesta, entre 1 y 500, y su valor predeterminado es 50, así que una llamada que pide registros sin indicar un tamaño de página sigue estando limitada, y ninguna invocación de ninguna de las dos herramientas devuelve una respuesta cuyo tamaño decida el del espacio de trabajo. offset es dónde empezar dentro del listado, contando desde 0. Ambos limitan los registros, así que ninguno tiene efecto sobre el resumen, que no lleva ninguno. Un limit fuera de ese intervalo se rechaza y nombra el límite; un offset más allá del final del listado vuelve vacío, porque ahí no hay nada, no porque la pregunta tenga algún problema.
Continúa un listado leyendo tres campos de la respuesta. count es cuántos registros contiene el espacio de trabajo, offset y returned dicen dónde empieza esta respuesta y cuántos lleva, y more_remaining dice si quedan más. Mientras more_remaining sea true, vuelve a llamar con offset más returned. Esa señal se calcula a partir de la página respecto al total en lugar de escribirse en la respuesta, así que no puede indicar que no queda nada mientras queden registros.
Todo eso importa porque las herramientas que sí toman un nombre rechazan uno que no pueden resolver en lugar de responder con un resultado vacío. El rechazo es deliberado —una respuesta vacía presentaría un nombre mal escrito como un sujeto sin nada que ofrecer—, pero significa que quien llama sin tener un nombre no puede obtenerlo adivinando. Enumerar es la forma de obtener uno.
Las dos se combinan, entre sí y con el resto de la superficie:
- Llama a
list-entitiespara obtener el resumen y ver qué tipos contiene el espacio de trabajo y cuántos de cada uno, luego vuelve a llamarla conresponse_format: detailedpara obtener los registros, toma un nombre del resultado y pásalo adescribepara ver la definición completamente resuelta de esa entidad. Es la definición con la que respondeaggrega/entityDefinitiondel servidor de lenguaje, transmitida como JSON: cada clave con el nombre que escribe su autor, en el orden en que la definición la contiene, un esquema tal como lo escribió el autor, y omitido un esquema que la entidad no declara; los sockets de un Component, cada uno con los slots que sus conexiones pueden llenar. - Haz lo mismo con
list-releases, toma una ruta del resultado detallado y pásala adescribeo abuildcomo la Release con la que trabajar. - La ruta que devuelve
list-releaseses relativa a la raíz del espacio de trabajo, que es la misma coordenada bajo la quelist-entitiesinforma de un archivo, así que las dos respuestas coinciden en el archivo y pueden leerse juntas. Su lockfile, bajolockfiles, es relativo a la misma raíz, así que puedes leer o comparar ese archivo sin averiguar dónde se encuentra.
Ambas deciden qué cuenta leyendo el propio kind de cada documento, nunca su nombre de archivo. Una Release nombrada sin un prefijo convencional se lista; un archivo que simplemente se llama como tal no, y aparece bajo el tipo que declara realmente. Un YAML que no declara ningún kind —el archivo de valores de un chart, un archivo de configuración que casualmente está en el árbol— no es una entidad y no se informa de él, como tampoco de un documento que pertenece a otro proyecto, como un manifiesto de Kubernetes renderizado. Un documento cuenta como entidad cuando declara tanto un kind como un nombre, porque son esos dos juntos los que lo hacen direccionable después, y no declara ninguna apiVersion fuera del grupo propio de Aggrega. Uno que no declara ninguna apiVersion sí se informa, por ser un documento de Aggrega al que le falta un campo y no un archivo de otro proyecto. list-releases no busca en ningún directorio fuera de la raíz del espacio de trabajo, así que una Release que tu editor muestra bajo un enlace que lleva a uno de esos directorios no se lista; unread_linked_dirs nombra cada enlace que está donde el listado leería un directorio y que lleva fuera de la raíz —por la propia ruta del enlace relativa a la raíz, nunca por adónde lleva—, en ambas formas y en ambos transportes, y está vacío donde no hay ninguno. Tampoco lee un archivo fuera de la raíz a través de un enlace: unread_linked_files nombra, de la misma manera, cada enlace cuyo propio nombre termina en .yaml o .yml y que lleva a un archivo fuera de la raíz, sea cual sea su contenido, así que una Release a la que solo se llega a través de uno de ellos no se lista, salvo que la configuración del espacio de trabajo nombre esa Release, como build.authoring_release o como clave de workspace.releases, en cuyo caso se lee y se lista en el propio lugar del enlace y no se nombra. list-entities tampoco lee ningún documento detrás de un enlace que lleva fuera del espacio de trabajo —no busca en ningún directorio fuera de la raíz ni lee ningún archivo fuera de ella, declare lo que declare ese archivo— y nombra cada uno de esos enlaces de la misma manera, en sus propios unread_linked_dirs y unread_linked_files, en ambas formas y en ambos transportes. Eso vale declare lo que declare el documento, con la única excepción que hace list-releases: una Release que nombra la configuración del espacio de trabajo, como build.authoring_release o como clave de workspace.releases, se lee y se lista en el propio lugar del enlace y no se nombra, mientras que un archivo que nombra uno de esos ajustes y que declara algo distinto de una Release no se lista, y su enlace se nombra. Los directorios de catálogo configurados son la forma en que un espacio de trabajo lee otras entidades guardadas en otro lugar, así que un enlace a un directorio que la configuración incluye en catalog_dirs, o a un directorio por debajo de uno de ellos, no lo nombra ninguno de los dos listados: la configuración ha llegado a él. Las Features que list-entities toma de los directorios de catálogo nunca incluyen una detrás de un enlace que lleva fuera del directorio dentro del cual deben permanecer las lecturas de un directorio de catálogo —el espacio de trabajo, para un directorio de catálogo dentro de él, o el propio directorio, para uno que la configuración nombra fuera de él—, así que una entidad nombrada como situada detrás de un enlace que no se leyó nunca se lista junto a ese nombre. Un enlace que el listado deja fuera —por su nombre, por dónde está o por un .gitignore— no se nombra, y con release tampoco uno situado bajo un directorio de catálogo que solo leen otras Releases; un .gitignore que es a su vez un enlace que lleva fuera del espacio de trabajo no se lee. Donde alguna de estas listas nombra un enlace, la respuesta de texto termina con una línea propia que lo indica.
Un espacio de trabajo cuyo archivo de configuración lleva fuera de él se sigue listando, y no se responde nada más para él. Donde el propio .aggrega-config.yaml del espacio de trabajo, o la superposición gestionada por la CI que está a su lado, es un enlace que lleva fuera del espacio de trabajo, su configuración no se lee, como en una terminal, y nada de lo que habría configurado se lee en su lugar. El servidor se inicia igualmente sobre la entrada y la salida estándar, y lo indica en una línea en su flujo de errores. list-entities y list-releases responden con los propios documentos del espacio de trabajo, leídos sin nada configurado, así que no se lista ninguna Feature de ningún directorio de catálogo. Cada una nombra el archivo retenido en unread_linked_files, y en la línea que cierra su texto, tanto si el listado lo encontró como si no; ese nombre es la forma de saber que la configuración del espacio de trabajo lleva fuera de él. Un listado al que se envía release o catalog_dirs, y cualquier otra herramienta que nombre ese espacio de trabajo, depende de la configuración que no se leyó, así que cada uno se rechaza con E0321, que nombra el enlace y adónde lleva. Un servidor al que su línea de comandos le indica que escuche —--transport http o --listen— no se inicia sobre un espacio de trabajo así, porque la dirección a la que se vincularía, su certificado y quién puede llamarlo son lo que decide esa configuración. Elimina el enlace, o haz que lleve a un archivo dentro del espacio de trabajo, y la siguiente llamada lee la configuración. Consulta el límite del espacio de trabajo.
Preguntar en los términos de una Release
Un espacio de trabajo puede dar a cada Release sus propios directorios de catálogo —consulta Dar a una Release sus propios directorios de catálogo— y así mantener una variante de una entidad por Release, una junto a otra. Tres herramientas que de otro modo responden sobre los propios directorios de catálogo del espacio de trabajo toman un release opcional, la ruta de un archivo de Release, y entonces responden en los términos de esa Release:
list-entitiesconreleaselista las entidades que ve esa Release. Las Features listadas son las que declaran sus directorios de catálogo, y un documento del espacio de trabajo bajo un directorio de catálogo que solo leen otras Releases se deja fuera, así que cada variante se lista para la Release que compila con ella y para ninguna otra. Un documento que no está bajo ningún directorio de catálogo —una Release, su Aggregate y su Manifest escritos junto a los catálogos— se lista para cada Release.describecon unnamey unreleaseresuelve el nombre a través de los directorios de catálogo de esa Release, así que un nombre que declaran varias variantes se resuelve en la que usa esa Release para compilar. Un nombre que esos directorios no resuelven se rechaza con una explicación que nombra la entrada de esa Release enworkspace.releases. Una referencia de registro se lee de su registro sea cual sea la Release nombrada, así que se rechaza junto a unrelease. Unreleaseenviado sinnamesigue siendo la Release quedescriberesume.validatecon unentityy unreleaseejecuta las comprobaciones de una sola entidad en los términos de esa Release: las referencias de la entidad —el Component que implementa una Recipe, una SchemaLibrary a la que hace referencia un pilar— se resuelven a través de los directorios de catálogo de esa Release, y la respuesta nombra la Release junto a la entidad. No se valida ningún cierre; unreleaseenviado sinentitysigue siendo el ámbito de la Release.catalog_dirsse antepone aquí a los directorios de la Release, como en todas partes. Un directorio que la configuración del espacio de trabajo incluye y que no es un directorio —porque ahí no existe nada, por ejemplo—, para esa Release, o para el espacio de trabajo cuando no se envía ningúnrelease, hace que la llamada se rechace antes de comprobar nada, con un texto que lleva el rechazo que le da cada comando y nombra la entrada y el archivo y la línea de configuración que la incluyen (De dónde se leen las entidades locales), tal como lo rechazaaggrega validate.
Un release que nombra un archivo que no existe, o que nombra un directorio, se rechaza en las tres en lugar de responderse en los términos del espacio de trabajo. Si no se envía ninguno, se responde sobre los propios directorios de catálogo del espacio de trabajo.
describe, al buscar un nombre, rechaza un directorio de catálogo a través del cual resolvería el nombre y que no puede recorrerse, igual que lo rechaza aggrega inspect: los directorios de esa Release cuando se envía un release, los propios del espacio de trabajo cuando no se envía ninguno, y cualquiera que la llamada nombre en catalog_dirs. Un directorio que nombra la llamada y que no existe, o uno que existe y no puede leerse, se rechaza antes de buscar el nombre, y el texto nombra el directorio tal como lo informa la línea de comandos, en una sola línea —el directorio, catalog load y el motivo que dio el sistema de archivos— en lugar de resolver el nombre a partir de los directorios restantes. Un directorio que la configuración del espacio de trabajo incluye y que no es un directorio se rechaza en ese mismo momento, con un texto que lleva el rechazo que le da cada comando (De dónde se leen las entidades locales). Un release que nombra un archivo que no existe se rechaza antes de eso, como se indicó arriba. Un directorio de catálogo que contiene un enlace que lleva fuera del directorio dentro del cual deben permanecer sus lecturas se rechaza de la misma manera, con el texto nombrando el enlace y adónde lleva, porque un nombre resuelto sin él podría resolverse en su lugar en otra entidad con el mismo nombre. Describir el cierre de dependencias de una Release no se ve afectado por un directorio que no puede recorrerse, y responde sobre los directorios que sí pueden recorrerse, como hace aggrega inspect --closure, salvo un directorio que la configuración del espacio de trabajo incluye para esa Release y que no es un directorio, que rechaza tal como lo rechaza aggrega inspect --closure; un enlace que lleva fuera de las lecturas de un directorio de catálogo, o fuera de los documentos junto a la Release, lo detiene, igual que detiene un build.
validate con un entity informa de un renderizado que no puede juzgar como no intentado, en los términos de una Release o sin ellos. Coloca el Component de una Recipe en un build sintetizado que no cablea ninguna conexión ni acopla ninguna Feature, así que una Recipe cuyo renderizado se detiene mientras sus plantillas —incluidos los archivos y las entradas de biblioteca que importan— leen algo bajo .context.inject, .context.uses o .features responde valid: true sin nada en diagnostics; su texto lleva Render: not attempted (this Recipe reads values a build of one cannot supply), las lecturas por las que se dejó a un lado y la frase en la que se detuvo el renderizado. Lo que lo decide es lo que lee la Recipe, así que un fallo propio de la Recipe junto a una lectura así se deja a un lado con ella, mientras que una plantilla que no se analiza y una referencia que el renderizado rechaza siguen respondiendo valid: false. aggrega validate da el mismo veredicto con las mismas entradas.
validate con un entity informa de una aserción fallida como advertencia, en los términos de una Release o sin ellos. Una aserción que llama a fail —la de la propia Recipe, o una que declara el Component que implementa— responde valid: true sin nada en diagnostics. El build sintetizado lleva marcadores de posición y valores predeterminados del esquema en lugar de los valores que establece una Release real, así que una aserción sobre uno de esos valores falla ahí tanto si la Recipe es correcta como si no, y la comprobación no puede distinguir una aserción que espera a una Release de una que está rota. El fallo sigue a las demás notices, en el mensaje completo de la aserción cerrado por la frase A Release must satisfy this assertion before a build of it can pass., y el texto lo lleva en una línea que empieza por warning:, junto a la línea de informe que dice dónde se detuvo la ejecución. Una aserción que se detiene en una clave que lee pero no encuentra es un fallo de su propio texto y no una aserción fallida, y se juzga como cualquier otra detención; un build de una Release que no satisface una aserción se sigue rechazando por ella. aggrega validate da el mismo veredicto con las mismas entradas.
Leer la configuración vigente y los plugins que resuelve este servidor
config-show informa de la configuración vigente y de qué capa decidió cada ajuste. plugin-list informa de los plugins que este servidor puede resolver y de lo que cada uno dice de sí mismo. Ninguno de los dos lee ni escribe nada, así que ninguno llega a nada y aggrega:read los admite, y ninguno te pide que nombres un sujeto, porque lo que está configurado y lo que se resuelve son propiedades de este servidor y no de algo que tengas que conocer primero. Cada uno toma un workspace_root opcional sobre la entrada y la salida estándar; sobre HTTP ese argumento se rechaza, como explica Un proceso, un espacio de trabajo.
Juntos responden a una pregunta en dos mitades: si una capacidad está ausente o simplemente no está configurada aquí. La configuración dice si un provider, un importador o una comprobación de gobernanza está acoplado o no; la lectura de los plugins dice si un acoplamiento llega a un invitado que se resuelve, se describe a sí mismo y sirve lo que afirma servir. Desde cualquier otro punto de esta superficie ambas cosas parecen iguales, y requieren pasos siguientes opuestos.
config-show informa de una entrada por ajuste: su field, su value efectivo y la source que lo decidió, ya sea un archivo de configuración, una variable de entorno, un flag de la línea de comandos o los valores predeterminados integrados. Junto a ellos, layers lleva las capas que contribuyeron en orden de precedencia, la más baja primero. La source de un ajuste se escribe exactamente como la entrada correspondiente de layers, así que las dos se unen directamente, y un ajuste que decidieron los valores predeterminados no nombra ninguna capa, porque los valores predeterminados no son una capa que haya contribuido. La capa global es el archivo que selecciona la propia línea de comandos del servidor —el que nombró --config al iniciarse, si no el que nombra la variable de entorno AGGREGA_CONFIG, y si no la ubicación predeterminada—, así que un ajuste que decide ese archivo se atribuye a ese archivo, exactamente como lo atribuye aggrega config show --origin, y un flag como --offline pasado al servidor se informa como ese flag. No toma response_format ni tamaño de página: los ajustes son el conjunto fijo del que da cuenta este binario y cada resolución los informa todos, así que el tamaño de la respuesta depende del binario y no de lo que configures.
plugin-list responde en las dos formas que usan los listados del espacio de trabajo, y una llamada que no indica ninguna forma recibe el resumen. El resumen es un recuento por grupo, y hay dos grupos: embedded, los invitados compilados en este binario, que se resuelven sin acceso al sistema de archivos, a la caché ni a la red, y configured, los enlaces propios del espacio de trabajo. Envía response_format: detailed para obtener los registros: el grupo de cada plugin, la referencia bajo la que se encontró, dónde se enlazó esa referencia, su tipo, versión, commit, capacidades servidas, tipos de entrada renderizados, ensamblado de frontera y exportaciones según los declara el propio plugin, su estado de preparación cuando lo tiene, y si se resolvió. Los registros están limitados por limit y offset en las mismas condiciones que usa el listado de entidades, con count, returned y more_remaining para continuar. Esta respuesta sí crece con lo que configuras —los integrados son fijos, los enlaces son tuyos—, y por eso está paginada y la lectura de la configuración no.
Un plugin que falla se informa con su fallo en lugar de quitarse del listado. resolved dice si la referencia llegó siquiera a los bytes de un módulo, y un plugin que se resolvió pero no pudo describirse a sí mismo se informa exactamente así, de modo que un acoplamiento presente e inutilizable se distingue de uno que nunca se hizo.
Lo que un listener no te dice sobre su host
Sobre HTTP ninguna de las dos lecturas informa de un valor que nombre un lugar del sistema de archivos del servidor. Un cliente que inició el servidor se ejecuta donde se ejecuta el servidor, así que cada ubicación que cualquiera de las dos respuestas podría nombrar es una que ese llamador ya posee y puede ir a mirar. Un llamador que llega a un listener no eligió ninguna de ellas, no puede actuar sabiéndolas, y un servidor que se las ha publicado a un llamador así no puede retirarlas. Sobre ese transporte esos valores están ausentes; sobre la entrada y la salida estándar están todos presentes. Es la regla que sigue cada respuesta de esta superficie, como explica Qué dice una respuesta sobre el sistema de archivos del servidor, y estas dos lecturas son donde llega más lejos, porque la mayor parte de lo que informan es configuración que nombra lugares.
Lo que se retiene. De config-show: el value de un ajuste cuando el propio valor de ese ajuste es una ubicación, ya sea una dirección de servicio o de estado, que puede ser un archivo de socket; un archivo de certificado, de clave privada o de conjunto de claves; un directorio de catálogo, y los propios directorios de catálogo de una Release bajo workspace.releases, cada una de cuyas entradas tiene como clave un archivo de Release; una referencia de plugin; una Release de autoría. También la source de un ajuste cuando la capa que lo decidió es un archivo de configuración, ya que esa capa se nombra por la propia ruta de ese archivo, y, con la misma grafía y por la misma razón, las entradas de archivo de configuración de layers. De plugin-list: el uri de un plugin cuando esa referencia es en sí misma una ruta del sistema de archivos, y el texto de un fallo de resolución o de descripción, que se compone a partir de los lugares que se probaron y por tanto nombra ubicaciones que la propia referencia no nombra. De ambos: workspace_root.
Lo que se informa completo, en ambos transportes. Una referencia de registro, una versión, un commit, un digest, una capacidad servida, una etiqueta de preparación, el nombre de una variable de entorno o de un flag, y una capa que no es un archivo. origin en un registro de plugin es uno de ellos: es la clave de configuración en la que se escribió un enlace, o el digest fijado que lleva una extensión de comando instalada, y uno integrado no lleva ninguno, así que es la misma cadena dondequiera que se lea el plugin. resolved es otro: si un plugin falló se informa a todos los llamadores, incluso donde no se informa el motivo.
Un valor ausente siempre dice que se retuvo, y eso es lo que hace utilizable la respuesta. Un valor retenido se informa como ausente con una marca a su lado: value_withheld y source_withheld en un ajuste, withheld en una entrada de capa, uri_withheld y error_withheld en un registro de plugin, y workspace_root_withheld en la respuesta. Un ajuste que nadie estableció lleva el valor vacío con el que se representa su forma, y no lleva ninguna marca. «Este servidor no te dice dónde está la clave de firma» y «no hay ninguna clave de firma configurada» son respuestas distintas que requieren pasos siguientes distintos, y una lectura que las informara de forma idéntica no te diría nada sobre lo que pudieras actuar. Cada respuesta lleva además host_locations_withheld, siempre, que dice cuál de las dos respuestas tienes: una respuesta sin marcas es por lo demás la misma tanto si esta regla le dio forma y no había nada en el host que retener, como si nunca se aplicó. El texto legible junto a los campos dice lo mismo con palabras.
La regla es una propiedad y no una lista de nombres de campos: un valor se retiene cuando nombra un lugar del sistema de archivos del host, quienquiera que lo haya establecido y sea cual sea la capa de la que proceda. Un valor que se añada más adelante a cualquiera de las dos lecturas queda sujeto a esa misma propiedad.
Sobre la entrada y la salida estándar cada capacidad también es accesible como la herramienta que lleva el nombre de su comando —cli-config-show y cli-plugin-list—, que ejecutan ese comando en un proceso aparte y devuelven el texto que imprimió; sobre HTTP esas herramientas no existen. Las dos descritas aquí llevan en cambio los valores, así que puedes leer si una capacidad está acoplada, o sacar la versión de un plugin, sin tener que convertir un formato en columnas de vuelta en aquello a partir de lo cual se renderizó.
Preguntar qué puede acoplarse y qué puede conectarse con qué
Dos herramientas responden a las preguntas sobre las que, de otro modo, un asistente tendría que adivinar: qué Features pueden acoplarse a un nodo y con qué puede conectarse un nodo. Ambas ejecutan la misma coincidencia de etiquetas que ejecuta el compilador, así que lo que el asistente te ofrece es el conjunto con el que coincidiría un build y no un conjunto deducido del esquema.
attach-candidates informa de las Features cuya aplicabilidad declarada satisfacen las etiquetas de un nodo. Indica el nodo exactamente de una de tres formas:
node: elmetadata.namede una entidad del espacio de trabajo, tal como lo informalist-entities. La coincidencia se ejecuta sobre las etiquetas que declara ese documento.graph_nodeconrelease: un nodo de un grafo compilado, con la clave que le da el grafo, incluida la forma cualificada que lleva un nodo aportado por un subagregado. La coincidencia se ejecuta sobre las etiquetas finalizadas de ese nodo, que son las que evalúa un build.labels: un conjunto de etiquetas por sí solo, que no nombra ningún nodo. No necesita ninguna coordenada, así que si ya tienes las etiquetas de un nodo esta es la forma que debes usar; no busca nada ni reconstruye ningún grafo.
La respuesta lleva las etiquetas sobre las que se ejecutó la coincidencia y de cuál de esos tres conjuntos proceden, así que puedes explicar cualquier candidato, o la ausencia de uno, a partir de la propia respuesta en lugar de volver a deducirlo. Leerlas de nuevo por un segundo camino es justo donde tu idea de las etiquetas de un nodo y la del compilador se separan.
Para preguntar qué puede acoplarse a una conexión que traza un nodo, añade connection junto a graph_node y release: su socket y su alias, tal como los escribió el autor. Una conexión lleva acoplamientos que llenan los slots que su socket declara en el Component consumidor, así que la respuesta lleva entonces también slots: cada slot que declara el socket, con su selector, required, inject, sensitive y description exactamente como los declara el Component, y los candidates que pueden llenarlo. Son las Features cuya aplicabilidad satisfacen las etiquetas del nodo y cuyas propias etiquetas admite el selector del slot —las dos reglas a las que un build somete un acoplamiento así—, así que los candidatos de un slot siempre están entre los del propio nodo. Donde no puede llenarse nada, slots está vacío y noSlotReason dice por qué: feature-created-connection (una Feature trazó la conexión, y a una conexión así no se le acopla nada), ad-hoc-socket (el socket es uno que el Component no declara) o no-slot-declared (el socket no declara ninguno). No leas un slots vacío como «no coincidió nada»; eso es lo que el motivo está ahí para descartar, y está ausente dondequiera que exista un slot. candidates junto a ellos conserva su significado —lo que puede acoplarse al propio nodo— y document, si envías uno, no cambia nada aquí. connection junto a node o labels, o sin nombrar ningún socket ni alias, se rechaza, igual que una conexión que el nodo no traza. Son las mismas respuestas que da el servidor de lenguaje, en las mismas condiciones.
connection-candidates informa de los sockets de dependencia que declara una entidad y, por cada socket, de los Components del espacio de trabajo cuyas etiquetas declaradas satisfacen la restricción que ese socket declara sobre sus destinos. Toma el metadata.name de la entidad en node. A diferencia de attach-candidates, no tiene una forma libre de coordenadas: aquí no hay una forma de conjunto de etiquetas, porque los sockets se leen de la propia declaración de la entidad nombrada.
Sus dos mitades no están igual de completas, y la respuesta dice cuál es cuál; no las presentes como una sola lista. Los destinos están completos: son los componentes que la misma restricción admite durante un build. Los sockets no lo están, ni pueden estarlo. Un consumidor puede inventar una conexión pero solo puede consumir lo que declara un productor, así que un autor puede escribir legítimamente un socket que la entidad del catálogo nunca declaró, y los sockets declarados son un punto de partida útil y no el conjunto de nombres válidos. Por eso cada socket dice si es declared o ad-hoc, y la respuesta dice si en esa entidad se acepta siquiera un socket no declarado: la superficie de dependencias de un Component acepta uno, porque un autor es dueño de la topología de su aplicación; la superficie de acoplamiento de una Feature no, porque un acoplamiento participa en la topología que declara la Feature acoplada en lugar de crear una propia. Esa apertura es una consecuencia de tu libertad de autoría, no una carencia: pasa socket con un nombre que la entidad no declara para preguntar por él.
Ambas responden y se detienen. Ninguna crea un acoplamiento, crea una arista, escribe en ningún archivo ni propone el texto de una modificación; redactar y aplicar la modificación que siga te corresponde a ti.
Ambas devuelven la misma identidad mínima que usa cualquier otra respuesta aquí —tipo, nombre y archivo de origen— y nada más. Todo lo demás que quisieras mostrar sobre una entidad ya está en list-entities para esos mismos tres campos, así que unes las dos respuestas en lugar de leer dos copias que podrían no coincidir. Ambas rechazan un nombre que no pueden resolver en lugar de responder con una lista vacía, por la misma razón que el resto de la superficie: una respuesta vacía presentaría un error tipográfico como un sujeto sin nada que ofrecer. Una llamada con labels no tiene ningún nombre que escribir mal, así que un resultado vacío ahí significa lo que dice.
Todo lo que el servidor lee como referencia se sirve desde esta máquina: los JSON Schema están integrados en el binario y la documentación se lee de la caché de paquetes de documentación que mantiene la máquina, como se describe más abajo. La redacción de un documento inicial, la validación, la descripción, la compilación y el linting se ejecutan todos sobre tu espacio de trabajo y las cachés locales, y ninguno llega a un registro por iniciativa propia: un renderizado sirve una referencia externa fijada desde el almacén direccionado por contenido y declina una no fijada en lugar de descargarla, que es lo que mantiene sin conexión todo el ciclo de inspección y renderizado. Puedes pedir dos lecturas de registro: describe con una referencia de registro, que descarga esa única coordenada, no escribe nada y, sobre HTTP, solo llega a un registro con el que esté configurado el espacio de trabajo servido; y scaffold enviado con example o list, que obtiene el paquete de documentación del registro predeterminado del espacio de trabajo cuando la máquina no guarda ninguna copia que admita la política de firmas del espacio de trabajo, verificándolo antes de conservarlo, como hace aggrega scaffold --example. La publicación y la firma son la otra cara deliberada de esto, y se tratan más arriba.
Entre ambas cosas se sitúa la resolución de las dependencias de una Release, que es lo único aquí que adquiere: llega a un registro porque pedir que se resuelvan dependencias es pedir que se descarguen. Solo ocurre cuando lo pides, y hay exactamente dos formas de pedirlo: llamar a pull, cuya única función es esa, o enviar auto_pull a build, que realiza esa misma resolución como primer paso del build. Nada más hace pull en tu nombre, y un build al que no enviaste auto_pull no llega a ningún registro. El único ajuste que cambia esto es el propio auto_pull del espacio de trabajo: un espacio de trabajo configurado así pide a cada build que contiene que resuelva primero, se ejecute desde donde se ejecute ese build, lo que se trata más abajo.
La única excepción entre esas lecturas de referencia es la adquisición del propio paquete de documentación, y ocurre al margen de toda lectura. El paquete se guarda una vez por máquina, en la caché que comparten todos los proyectos de Aggrega, una copia por cada registro y versión, así que un servidor iniciado en una carpeta donde no puede crearse ninguna caché del espacio de trabajo lo guarda igualmente (consulta aggrega cache). Cuando el servidor se inicia, antes de responder a nada de lo que envíes, busca ahí una copia que admita la comprobación de firma de tu propio espacio de trabajo —la misma comprobación a la que responde un pull del paquete— y descarga el paquete, mediante los mismos ajustes de salida de red que usa el resto de la CLI, solo cuando no hay ninguna. El paquete que busca es el publicado para la versión de aggrega que ejecuta el servidor o, cuando no hay ninguno publicado para ella, el más reciente publicado para una versión anterior —la misma elección que hacen aggrega explain y aggrega scaffold --example—, y cada página que sirve, y cada explicación, se lee del que obtuvo. Así, las páginas ya están ahí para cuando algo pide una, envíe lo que envíe primero tu cliente, y otro servidor, o aggrega explain en otro proyecto, encuentra la misma copia en lugar de descargarla de nuevo.
Servir una página es entonces una lectura de esa copia, y no llega a ningún registro. Antes de servir una página, las firmas guardadas junto a la copia se verifican de nuevo con la comprobación de tu espacio de trabajo, así que no se te sirve una copia que dejó entrar el ajuste más permisivo de otro proyecto: donde la comprobación fija una clave o una raíz de confianza, esa verificación se ejecuta sin conexión, y donde no fija ninguna de las dos —la comprobación integrada del hub oficial es una de ellas— obtiene la raíz de confianza pública de Sigstore, como hace un pull. Un espacio de trabajo sin conexión no puede descargar esa raíz de confianza, así que sin conexión verifica contra la raíz de confianza que una descarga anterior con conexión en esta máquina dejó en la caché que el cliente de Sigstore mantiene en .sigstore dentro de tu directorio personal, por mucho tiempo que haga de esa descarga, y no descarga nada; en una máquina que nunca la ha descargado, la comprobación no puede ejecutarse sin conexión, la copia no se sirve y el flujo de registro lo indica. Esa verificación se ejecuta una vez por cada copia y cada comprobación mientras el servidor está en marcha, y las páginas que se leen después se sirven según lo que admitió: una copia descargada desde entonces, un espacio de trabajo cuya comprobación es distinta —incluida una raíz de confianza fijada editada en el sitio—, una lectura hecha sin conexión, o una lectura sin conexión que encuentra otra raíz de confianza en la máquina se verifica por sí misma. Una copia que tu comprobación rechazó se vuelve a comprobar en la siguiente lectura, así que una descarga que la haya admitido desde entonces no queda anulada. Si el paquete no puede adquirirse, o la única copia es una que tu comprobación rechaza y volver a descargarla con esa comprobación falla, el servidor se inicia igualmente y todas las demás superficies funcionan; las solicitudes de documentación responden not-found, y el flujo de registro del servidor dice por qué.
Compilar a partir del contenido que una Release ya fija
build renderiza en memoria una Release en sus artefactos, y un renderizado puede pedir contenido de una URL remota — el esquema de values de un chart con una referencia remota, por ejemplo. Las entradas externas quedan congeladas durante la llamada. Una referencia que el lockfile de la Release ya fija se sirve desde el almacén direccionado por contenido, lo que es una lectura de contenido que ya está en disco y no una descarga. Una referencia que el lockfile no fija se descarta y se nombra en lugar de descargarse: lo que pediste es un renderizado, y adquirir una referencia supondría tanto llegar a la red como escribir un blob en el almacén como efecto secundario de producir bytes. Ese congelamiento es una propiedad del renderizado. La resolución es el paso que adquiere: renderiza la Release para averiguar qué referencias remotas pide ese renderizado, las descarga y las registra en la misma escritura del lockfile que contiene las fijaciones de las dependencias. Así que lo que cambia la resolución es qué referencias están fijadas en el momento en que se ejecuta un renderizado, nunca lo que un renderizado puede alcanzar — y una referencia que ninguna resolución fijó se descarta en una llamada que resolvió primero exactamente igual que en una que no lo hizo.
Los archivos vuelven como los bytes que emite una compilación real, y son dos cosas juntas las que lo hacen cierto. Una es el congelamiento descrito arriba: una referencia fijada se lee del almacén en lugar de descargarse. La otra es que el lockfile del que se lee sigue describiendo aquello a lo que se resuelve la Release — por eso build lo comprueba y rechaza un lockfile que ya no coincide, exactamente como hace aggrega build en una terminal. Leer bytes fijados no dice nada por sí solo sobre si eran los bytes correctos que leer.
Los tres estados del lockfile, para que el comportamiento sea explícito. Sin ningún lockfile, build renderiza a partir de lo que el espacio de trabajo ya fija y descarta cada referencia externa que no puede servir, nombrándolas una por una; por sí solo no exige un lockfile ni escribe uno, y la comprobación descrita arriba no cambia eso — no hay lockfile que comparar, así que no se rechaza nada. Con un lockfile que coincide, renderiza. Con un lockfile que ya no coincide, rechaza, y el rechazo indica cómo solucionarlo: llama a pull con la misma release y sin upgrade_targets, lo que concilia el lockfile con aquello a lo que se resuelve hoy la Release. El rechazo incluye también la forma de terminal de esa misma operación, aggrega pull --release <release>. Cualquiera de las dos invocaciones lo soluciona; son una sola operación accesible desde dos lugares, no dos instrucciones entre las que elegir. Cuando pull se completa y el rechazo vuelve, las dos llamadas resolvieron sobre entradas distintas — casi siempre catalog_dirs pasado a una y no a la otra, o una configuración del espacio de trabajo editada entre ambas — y el rechazo lo dice: llama a las dos con las mismas.
validate y describe, cuando reciben solo una release, quedan sujetos al mismo lockfile. Sobre un lockfile que ya no coincide con aquello a lo que se resuelve la Release, cada uno rechaza en lugar de responder, y su texto incluye la detención por deriva con la que rechaza build y la misma forma de solucionarla — como rechazan en un terminal aggrega validate --release y aggrega inspect --closure. Con un lockfile que coincide, o sin ninguno, cada uno responde como lo haría de otro modo.
Pedir a una compilación que resuelva primero sus dependencias
Envía auto_pull y la compilación resuelve antes de renderizar. Realiza la misma resolución que realiza pull — la operación en sí, no una segunda escrita para una compilación, de modo que un espacio de trabajo llenado por una compilación y uno llenado por una llamada a pull quedan llenados de forma idéntica —, escribe el lockfile de la Release y luego renderiza a partir de lo que escribió. Ese paso llega a un registro y escribe, algo que nada más en build hace salvo write, y write no llega a ningún registro — por eso está desactivado a menos que se pida.
Responde a los dos rechazos descritos arriba sin salir del protocolo. Una Release que nadie ha resuelto todavía renderiza a partir de las fijaciones que haya y descarta el resto; un lockfile que ha derivado detiene la compilación sin más. Enviar auto_pull resuelve primero y renderiza a partir de un lockfile derivado de la clausura de la que trata esta compilación, de modo que ambos casos vuelven como un renderizado y no como algo que haya que ir a arreglar. Si quieres la resolución y el renderizado como pasos separados — para leer lo que se fijó antes de renderizarlo —, llama a pull y luego a build, que son las mismas dos operaciones con un vistazo entre ellas.
Una llamada renderiza la Release una sola vez. Averiguar qué referencias remotas consume una Release es en sí un renderizado, así que una resolución ya ha renderizado la Release de la que trata la compilación — a partir de las mismas fijaciones que acaba de escribir, con cada comprobación que ejecuta una compilación. La compilación se responde a partir de ese renderizado en lugar de repetirlo, y por eso enviar auto_pull cuesta una resolución y no un segundo renderizado. Solo un renderizado que terminó se usa así: cuando una resolución fijó sus dependencias pero no pudo terminar de descubrir las referencias externas, la compilación renderiza por su cuenta a partir de las fijaciones que sí se escribieron, y una referencia sin fijar la detiene entonces por su nombre en lugar de volver como una lista de archivos que se queda corta respecto a lo que emite una compilación.
Lo que vuelve dice qué se resolvió. Una compilación que llenó lleva dependency_resolution en su respuesta, con la forma con la que responde pull: el lockfile que escribió, cada referencia que alcanzó la resolución con la versión a la que se resolvió cada una y de dónde la tomó la resolución de esta compilación, los recuentos que contiene después el lockfile, y el informe que la resolución da de sí misma línea por línea. Una compilación que no llenó no lleva ese campo en absoluto, así que su presencia es la forma de distinguir ambas sin leer el disco. Los archivos renderizados se informan exactamente igual que en cualquier otra compilación, y se siguen devolviendo en memoria a menos que la llamada también haya recibido write — la resolución escribe el lockfile y la caché de artefactos, nunca un artefacto.
Un espacio de trabajo puede pedirlo de forma permanente, y una llamada no puede desactivarlo. El ajuste auto_pull del propio espacio de trabajo activa el mismo paso para cada compilación de ese espacio de trabajo, y auto_pull en una llamada se suma a ese ajuste en lugar de reemplazarlo: basta con cualquiera de los dos, y no hay ningún argumento que suprima una resolución que el espacio de trabajo pidió. Es la misma forma en que el ajuste y aggrega build --auto-pull se combinan en una terminal, de modo que un espacio de trabajo responde igual sea cual sea la superficie por la que llegue una compilación.
El descarte se informa en lugar de absorberse, y con los proveedores que incluye este binario un descarte detiene el renderizado: el proveedor que pidió la referencia devuelve el rechazo, así que la llamada responde con ese fallo y no devuelve ningún archivo. La referencia se nombra donde un lector puede actuar sobre ella, junto al comando que la fija: aggrega pull --release <path>. La misma fijación es accesible en esta superficie como la herramienta pull, descrita más abajo en Resolver de qué depende una Release, de modo que un asistente que se encuentre con este rechazo puede actuar sin salir del protocolo. Un renderizado completamente fijado no dice nada de todo esto. Consulta aggrega pull para saber qué descarga y registra la fijación, y aggrega build, donde una referencia sin fijar se informa y detiene la ejecución de la misma manera.
Escribir los artefactos donde los escribe aggrega build
Envía write y el renderizado terminado también se escribe en dist/ en la raíz del espacio de trabajo, donde lo escribe aggrega build. El directorio es el que compone la línea de comandos bajo la misma raíz del espacio de trabajo, y la escritura es la que realiza, de modo que para una Release en un espacio de trabajo, aggrega build, el aggrega/build del servidor de lenguaje sin outputParent y esta llamada escriben un único árbol, byte a byte, y nombran ese directorio igual — la línea final del comando, el outputDirectory del servidor de lenguaje y el output_dir de esta respuesta. Un dist que es un enlace que lleva fuera del espacio de trabajo se rechaza antes de que se elimine o escriba nada en él, como en una terminal. Si se omite, que es el valor predeterminado, los artefactos se devuelven en memoria y no se escribe nada.
La raíz del espacio de trabajo es la de la propia llamada. Por la entrada y la salida estándar es la raíz del espacio de trabajo que resolvió la llamada, como expone En qué espacio de trabajo se responde una llamada: la raíz que nombra workspace_root, si no la raíz con la que se lanzó el servidor, si no el espacio de trabajo encontrado a partir del directorio en el que se inició el servidor — y, cuando una Release nombrada por una ruta absoluta traslada la llamada al espacio de trabajo propio de esa Release, la raíz de ese espacio de trabajo. Es la raíz bajo la que escribe aggrega build para la misma Release y la misma raíz nombrada, de modo que la carpeta en la que se esté ejecutando el servidor recibe un dist solo cuando esa carpeta es la raíz que resolvió la llamada, como ocurriría en una terminal abierta allí. Por HTTP es el espacio de trabajo que sirve el servidor, y no se escribe nada fuera de él.
La escritura llega al espacio de trabajo, así que por HTTP necesita aggrega:workspace-write. Una llamada que recibió write llega al espacio de trabajo para esa llamada, exactamente como una compilación que resuelve primero sus dependencias: una credencial que solo lleva aggrega:read recibe como respuesta 403 nombrando aggrega:workspace-write, y no se escribe nada, y un servidor cuyo mcp.deny_reach nombra workspace rechaza la llamada nombrando ese ajuste. La herramienta sigue en la lista de herramientas de cada llamante, y una compilación que no recibió write sigue disponible para un llamante con ámbito de solo lectura.
Escribe en último lugar. También con auto_pull, la llamada resuelve, renderiza y luego escribe, en ese orden. Una llamada rechazada en cualquier punto anterior — su Release, su espacio de trabajo, un directorio de catálogo, la resolución, el renderizado — no escribe ningún artefacto.
La respuesta nombra lo que se escribió. output_dir es el directorio — completo por la entrada y la salida estándar, dist por HTTP — y files enumera cada archivo escrito, relativo a él, con su contenido bajo response_format: detailed y solo su ruta bajo concise; el texto dice cuántos archivos se escribieron y dónde. Una llamada que no recibió write no lleva ningún output_dir, así que su ausencia es la forma de saber que no se escribió nada. Una escritura que falla una vez terminado el renderizado — en una raíz del espacio de trabajo en la que nadie puede escribir, por ejemplo — responde como un fallo que nombra el directorio y la causa, y no enumera ningún archivo como escrito: parte de la escritura puede estar en disco, y nombrar como escritos los archivos renderizados afirmaría más de lo que ocurrió.
Ningún argumento nombra un directorio, y ninguno pide una traza. Adónde van los artefactos lo decide el espacio de trabajo que resolvió la llamada, nunca la llamada, y una compilación escrita desde aquí no deja ningún directorio .trace junto a su salida; una compilación con traza es aggrega build --trace.
Lo que te dice una compilación además de sus archivos
Una compilación lleva cada aviso que generó, en la propia respuesta. Son los hallazgos que aggrega build imprime mientras trabaja: un nombre a una sola edición de uno declarado, un parámetro que nada lee, un destino que no puede respetar un campo escrito por el autor, un veredicto de gobernanza que no detiene la compilación, un directorio de frontera que una Release heredó de la Release que extiende y que se resuelve en la misma ruta, una propiedad que un Component o una Feature que alcanza la Release declara tanto en su pilar values como en su pilar infra. Ninguno de ellos cambia el resultado: una compilación que lleva avisos ha tenido éxito igualmente, y los archivos que devuelve son los que produjo. Llegan en el orden en que los imprime una terminal, así que quien compare ambos encuentra una sola secuencia y no dos: primero todo lo que generó el renderizado, en el orden en que lo generó; después los hallazgos sobre la Release y lo que alcanza, que aggrega build imprime una vez que el renderizado ha terminado; y por último, en una compilación enviada con write, la advertencia que nombra cada archivo que la escritura encontró junto a los suyos y que no escribió, y que deja en su sitio: la misma que aggrega build imprime una vez escritos sus archivos (Archivos que la compilación no escribió).
Están en la respuesta y no solo en el texto de resumen porque un asistente que maneja esta superficie no lee ninguna terminal, y un hallazgo del que no se informa a nadie es un hallazgo que no se hizo. Cada uno lleva una severity — warn para algo que requiere atención, info para una observación registrada — y un message; un code cuando su clase le asigna uno, para que puedas reaccionar a una condición concreta sin comparar texto; y un key_path que nombra la clave del documento escrito por el autor a la que se refiere el hallazgo, cuando se refiere a una. Un hallazgo sobre la forma de la topología desplegada no nombra ninguna clave, porque sus coordenadas son las del despliegue y no las de un documento, y en su lugar dice en su mensaje a qué se refiere.
Dos tipos de hallazgo que imprime una terminal llegan a esta respuesta en un lugar distinto de advisories, porque cada uno tiene un sitio que dice más. Un marcador de obsolescencia registrado está en deprecations, ya lo haya registrado el lockfile para una referencia fijada o el registro de confianza de plugins que está junto a él para un plugin adjuntado en un rol que devuelve un veredicto de aceptar o rechazar. describe de una Release nombra el mismo conjunto en sus propias deprecations, y validate de una Release entre sus notices, cada uno dejando el veredicto como está; un registro de confianza que existe y no puede leerse hace que se rechace cualquiera de las dos llamadas en lugar de pasar por uno que no registra nada. Un padre del que hereda una entidad y que no se pudo resolver detiene la compilación, así que se nombra en el texto del rechazo en lugar de enumerarse como un hallazgo que no cambió nada. Un tipo está limitado por lo que carga esta herramienta y no por lo que lleva su respuesta: aggrega build carga cada directorio de catálogo configurado antes de resolver una Release, y un aviso sobre una forma de catálogo obsoleta provendría de esa carga, mientras que esta herramienta solo lee lo que alcanza la Release y no realiza tal carga, así que no informa de ningún aviso de ese tipo. Actualmente ninguna compilación emite uno, así que ambos informan de los mismos hallazgos.
Una Release que no emite nada no dice nada: la clave está ausente en lugar de presente y vacía, así que su sola presencia te dice que hay algo que leer.
Lo que devuelve una compilación rechazada
Una compilación que rechaza responde en los mismos campos en los que responde una compilación que tuvo éxito, rellenados hasta donde llegó la ejecución. Vuelve marcada como fallo con la corrección como texto, y la carga estructurada está junto a ese texto en lugar de ser reemplazada por él. Un rechazo emitido mientras se renderiza la Release se lee en las palabras del compilador, como describe más abajo Un rechazo emitido durante el renderizado, y añade un campo propio. Los avisos están en ella: las fases que se ejecutaron emitieron lo que emitieron, y esos son los hallazgos sobre los que tienes que actuar para superar el rechazo, así que llegan como entradas con las que puedes hacer coincidencias y no como prosa que tendrías que analizar. deprecations y declined_external_inputs están en ella por la misma razón — un marcador registrado se informa porque se registró un marcador, y una referencia descartada porque se descartó una referencia, y ninguno de esos hechos es consecuencia de cómo terminó la ejecución.
files no informa de nada en un rechazo, y no es el campo del que leer el resultado. No se emitió nada, así que no hay artefactos que nombrar. No bifurques según si la clave está presente: se informa en ambos casos, y un files vacío no puede por sí solo distinguir una compilación que rechazó de una que se ejecutó y no emitió nada. Lee el indicador de fallo del resultado — ese es el discriminador propio del protocolo — y lee files por lo que es, la lista de lo que se renderizó, y también se escribió cuando la llamada recibió write.
Lo que limita los avisos en un rechazo es hasta dónde llegó la ejecución, no lo que la respuesta es capaz de llevar. Un rechazo procedente de una comprobación que se ejecuta antes de que la Release se haya resuelto — una entrada fijada en la caché ya no coincide con el digest registrado para ella y ningún directorio de catálogo contiene los bytes fijados, o no se pudo resolver aquello de lo que depende la Release — no informa de ningún aviso, porque todavía no se había emitido nada. Los hallazgos sobre cómo se compone una Release con la Release que extiende se emiten en el momento en que se resuelve, antes de cada comprobación posterior, así que cada rechazo posterior los lleva: el Manifest asigna un tipo a una receta que no lo implementa, una entidad que alcanza la Release no cumple su esquema, el lockfile ya no coincide con aquello a lo que se resuelve la Release. Los hallazgos propios del renderizado se emiten a medida que se ejecuta el renderizado, así que un rechazo de una de esas comprobaciones anteriores no lleva ninguno de ellos, y un rechazo del renderizado lleva todo lo emitido antes. Así que lee advisories en un rechazo exactamente como lo lees en un éxito: lo que encontró esta ejecución, en el orden en que lo imprime una terminal.
Un rechazo porque una entidad hereda de un padre que no se pudo resolver nombra cada una de esas herencias en su texto, con las palabras que aggrega build imprime para ello, para que sepas cuál reparar. Ese detalle es el motivo por el que se detuvo la compilación, y por eso está en el texto y no entre los hallazgos que no cambiaron nada; los hallazgos de composición emitidos antes están en advisories como en cualquier rechazo posterior.
Un directorio de catálogo que lee la Release y que no se puede recorrer se rechaza antes de que se escriba nada, como lo rechaza aggrega build. Se trata de un directorio que la llamada nombra en catalog_dirs y que no existe, como aggrega build rechaza un directorio --catalog que no existe, o de uno que existe y no se puede leer. aggrega build carga cada directorio que lee la Release antes de resolver la Release, y se detiene en uno que no puede recorrer; build recorre primero los mismos directorios, sin leer ningún documento en ellos, antes de cualquier resolución de dependencias y antes del renderizado — de modo que una compilación que recibió auto_pull no escribe ningún lockfile, y no se renderiza nada. El texto nombra el directorio como lo informa la línea de comandos, en una línea: el directorio, catalog load y el motivo que dio el sistema de archivos. La carga nombra la Release, con un files vacío y ningún hallazgo, porque no se había ejecutado nada. Un directorio que la configuración del espacio de trabajo enumera y que no es un directorio — no existe nada allí, por ejemplo — se rechaza antes de ese recorrido, con la misma forma, y el texto lleva el rechazo que le da aggrega build, nombrando la entrada y el archivo de configuración y la línea que la enumeran (De dónde se leen las entidades locales). Un directorio de catálogo que contiene un enlace que lleva fuera del directorio dentro del cual deben quedarse sus lecturas se rechaza en el mismo momento, sin escribir nada, con el texto nombrando el enlace y adónde lleva — aggrega build lo rechaza de la misma manera.
Un ejemplo desarrollado, para que las dos mitades sean concretas. Una Release que declara un parámetro que ninguna referencia lee, y cuyo renderizado luego no puede completarse, vuelve como un fallo cuyo texto lleva el rechazo del renderizado y cuya carga lleva el aviso de parámetro no leído con su severity, su message, su code y su key_path — la misma entrada, con los mismos valores, que la misma Release informa en la respuesta cuando el renderizado sí se completa — junto a la entrada refusal de lo que detuvo el renderizado. Una Release que extiende otra y hereda un directorio de frontera sin ninguna variable de plantilla, y cuyo Manifest asigna un tipo a una receta que no lo implementa, vuelve como ese rechazo con una entrada de advisories por cada directorio heredado, cada una con code inherited-boundary-directory-is-literal. Una Release cuyas dependencias no se pueden resolver, en un espacio de trabajo cuyos directorios de catálogo enumerados existen todos, vuelve como un fallo sin ninguna clave advisories, porque no se había emitido nada cuando se detuvo.
Un rechazo emitido durante el renderizado
Una Release que el compilador rechaza mientras renderiza — un Workload que nombra un slot que su Component no declara, una aserción que falla, una plantilla que no se puede evaluar — vuelve con el rechazo en las palabras del compilador y con cada causa debajo, las palabras que cli-build devuelve para la misma Release: el nodo que se está renderizando y luego lo que en él rechazó. Cuando el rechazo nombra una condición registrada, el texto añade cómo se llama esa condición — el código corto y el código descriptivo con los que hacer coincidencias —, como haría explain-error. El texto empieza diciendo qué etapa rechazó: The build failed during rendering; nothing was written to disk. para un rechazo emitido por el renderizado, y The build refused before rendering anything; nothing was written to disk. para uno emitido por la ejecución del compilador antes de que se renderizara nada — la composición del grafo sobre el que trabaja el renderizado que rechaza, o una aserción que declara un Component o una Feature.
La carga lleva el mismo rechazo como una sola entrada, refusal, de modo que un llamante que tiene que cambiar un documento lee cuál, y dónde, sin analizar la frase:
file— el documento al que apunta el rechazo: la Recipe de un Workload, la Recipe o la FeatureRecipe que declara una aserción que falla, la Release o el Aggregate que escribió una entrada que rechaza la composición del grafo, o el Aggregate de la Release para un rechazo que no apunta a ningún documento.key_path— la clave en ese documento, cuando el rechazo nombra una:.spec.workloadpara un rechazo sobre un Workload, la propia clave de la aserción bajo.spec.assertionspara una aserción que falla, la propia clave de la entrada para el rechazo de una entrada. Un rechazo sobre un Workload se sitúa en su claveworkloady no con más detalle, porque el Workload que juzga una comprobación es lo que produjo su plantilla, y una plantilla escribe líneas que su autor nunca escribió; las rutas que el rechazo nombra dentro de ese Workload renderizado permanecen en sumessage.lineycolumn— la posición de esa clave, contada a partir de uno, la columna en unidades UTF-16. Ausentes cuando el rechazo no nombra ninguna clave o el documento no la contiene: solo se da una posición donde se encontró una.severity—halt, la gravedad del hallazgo que detuvo una compilación.codeyshort_code— los dos identificadores de la condición, cuando el rechazo nombra una condición registrada.message— el texto del rechazo, exactamente como aparece en el texto de la respuesta.findings— presente solo cuando el rechazo reúne varios hallazgos, como hace la composición del grafo con cada infracción que encontró: una entrada por hallazgo, en el orden en que los enuncia el rechazo, cada una con esta misma forma — con sus propiosfile,key_path,line,column,severity,code,short_codeymessage. Los campos propios del rechazo nombran entonces adónde apunta su primer hallazgo, y sumessagelleva cada hallazgo, como el texto; la línea de comandos imprime cada hallazgo como un diagnóstico propio.
La entrada está presente siempre que la propia ejecución del compilador rechazó — mientras renderizaba, o antes de renderizar: en la composición del grafo, o en una aserción que declara un Component o una Feature, que no nombra ningún documento, por lo que su entrada nombra el Aggregate. Una compilación que tiene éxito no lleva ninguna, y tampoco una rechazada por una comprobación que se ejecuta antes de que arranque el compilador — el lockfile, las asignaciones del Manifest, aquello de lo que depende la Release —, cuyo rechazo es solo el texto. Un valor que un autor declaró sensible se retiene del rechazo donde lo emite el compilador, de modo que la entrada y el texto llevan lo que llevan cli-build y la terminal — consulta lo que dice un rechazo sobre un valor declarado.
Resolver de qué depende una Release
pull resuelve las dependencias de catálogo y de origen de una Release en la caché local y escribe el lockfile de esa Release. Está en esta superficie por una razón que merece la pena decir: los dos rechazos descritos arriba — un renderizado que descartó una referencia externa sin fijar, y una compilación que se detuvo porque el lockfile ya no coincide con aquello a lo que se resuelve la Release — se responden ambos fijando, y un asistente que tiene que pedirte que ejecutes un comando no tiene forma de responderlos por sí mismo. Lee Qué puede hacer un asistente sin preguntarte antes para saber qué escribe y hasta dónde llega.
Pasa release, la ruta de la Release, absoluta o relativa a la raíz del espacio de trabajo — el mismo contrato que usa cada uno de los demás argumentos de ruta aquí. workspace_root y catalog_dirs reemplazan la detección del espacio de trabajo y del catálogo exactamente como lo hacen en build. Ambos valen en un servidor al que se llega por la entrada y la salida estándar; por HTTPS esos dos argumentos se rechazan y la ruta debe resolverse dentro del espacio de trabajo que sirve el proceso, como expone Un proceso, un espacio de trabajo.
De forma predeterminada concilia en lugar de volver a resolver. Una fijación que el lockfile ya registra se respeta y se descarga en esa versión, y se rechaza en lugar de volver a fijarse en silencio si el registro ya no sirve esos bytes. Una referencia sin fijación — recién añadida, o eliminada a mano del lockfile — se resuelve desde cero y se añade. Una referencia que ya no está entre las dependencias resueltas se poda. Por tanto, un conjunto de dependencias sin cambios deja el archivo idéntico byte a byte, incluida su marca de tiempo registrada, de modo que una llamada que no cambió ninguna fijación no produce ninguna diferencia para quien revise después el espacio de trabajo.
verify compara y deja el lockfile como está. Comprueba el lockfile registrado frente a la resolución que realizaría ahora la llamada de conciliación descrita arriba, respetando las fijaciones registradas exactamente como lo hace esa llamada, y vuelve como un fallo cuando hay deriva, o cuando no hay ningún lockfile con el que comparar — así es como un asistente averigua si hace falta fijar antes de que nada reescriba el lockfile. No se escribe nada de lo que registra esa llamada — ni el lockfile, ni las identidades de plugins registradas junto a él, ni un entity.lock —, mientras que la caché de contenido se lee y se llena exactamente como esa llamada la lee y la llena. También informa de la cadena de herramientas que registra el lockfile: la versión del compilador que escribió el archivo y la versión de cada plugin central que incluía ese compilador. Esto se informa para auditoría y nunca se compara con el binario en ejecución, porque la cadena de herramientas no forma parte de lo que fija el lockfile y comprobarla fijaría el compilador de forma indirecta — una diferencia en la cadena de herramientas no es una deriva.
upgrade_targets vuelve a resolver las referencias que nombras, y nada más. Pásale uno o varios URI de entidad en la forma escrita simple — core/database, no una forma con versión. Cada fijación nombrada se descarta y se vuelve a resolver a la versión más alta disponible, mientras que todas las demás fijaciones y las entradas externas registradas se mantienen sin cambios. Un URI que no coincide ni con una fijación registrada ni con un adjunto configurado se rechaza en lugar de ignorarse.
No existe deliberadamente ningún argumento que vuelva a resolverlo todo a la vez. La línea de comandos tiene esa forma, y descarta el lockfile completo antes de volver a resolver a partir del estado actual del registro. En esta superficie el argumento no existe, así que la llamada no puede componerse en absoluto en lugar de aceptarse y luego rechazarse: nadie está observando un flujo de protocolo, así que un descarte total no tiene a nadie que lo confirme. Si lo quieres, y solo por la entrada y la salida estándar, cli-pull ejecuta el comando, y esa es la superficie en la que hay una persona presente; un llamante que llega a este servidor por HTTP lo ejecuta en su lugar en una terminal del host. verify no se puede combinar con upgrade_targets — uno deja el lockfile como está y el otro lo reescribe — ni con pin_sources, tenga el valor que tenga: ese argumento decide si una resolución registra las fijaciones que le faltan a un entity.lock o rechaza por ellas, y una comparación no escribe ningún entity.lock, así que no haría ni lo uno ni lo otro. Una llamada que envía cualquiera de los dos pares se rechaza antes de que se resuelva nada, con una frase que nombra el par. El esquema anunciado de la herramienta no indica estas dos exclusiones, porque un cliente que muestre una de ellas puede leerla como un requisito de enviar verify; el rechazo es donde un cliente las conoce. La línea de comandos y el daemon rechazan los mismos pares.
El resultado nombra lo que se resolvió, no solo que algo se resolvió. Lleva el lockfile que escribió o con el que comparó; resolved, cada referencia que alcanzó la resolución con la versión a la que se resolvió cada una, el tipo que escribe un autor cuando la resolución registra uno, y su source — de dónde tomó esta ejecución la referencia, con la palabra que aggrega pull --detail imprime para la misma resolución: fetched-fresh, cache-reuse, local, in-binary o external; los recuentos de artefactos de origen, entradas externas e identidades de plugins de confianza que contiene después el lockfile; y diagnostics, el informe que la resolución da de sí misma en el orden en que emitió cada línea — qué fijación se reutilizó, qué firma se comprobó, qué versión se omitió por estar retirada. Esas líneas llegan a una terminal cuando ejecutas el comando; aquí están en la respuesta, porque un llamante que no lee ninguna terminal no tiene otra forma de recibirlas. verified solo está presente en una comparación, así que su ausencia es la forma de distinguir una ejecución que escribió de una que solo comparó. Una source describe esta ejecución en esta máquina, así que el lockfile no la registra, y describe, que informa de qué depende una Release, no nombra ninguna.
Un rechazo responde en los mismos campos, rellenados hasta donde llegó la ejecución. Una vez calculada la resolución, resolved se lleva sea cual sea el veredicto — un veredicto de deriva más que ninguno, ya que es el rechazo sobre el que un llamante tiene que decidir qué cambiar. Un rechazo anterior a ese punto, como una ruta de Release que no se resuelve, lleva la corrección como texto y ninguna resolución, porque no había ninguna que llevar.
Cuando las fijaciones están completas y las entradas externas no, la llamada tiene éxito igualmente y lo dice. Averiguar qué entradas externas consume una Release es un renderizado, y un renderizado puede fallar después de que las fijaciones de las dependencias ya sean correctas y estén en disco. Informar de que toda la llamada falló te diría que rehicieras un trabajo que está bien, así que en su lugar se establece incomplete_external_inputs en el resultado correcto, nombrando lo que se detuvo: las fijaciones de las dependencias están completas, las de las entradas externas puede que no.
Esta es la herramienta más lenta de aquí, y la conciliación sin cambios no es una vía rápida. Una resolución paga su coste completo para establecer que un conjunto de dependencias no ha cambiado, así que una llamada que no reescribe nada cuesta lo mismo que una primera resolución — en una Release pequeña, segundos en lugar de milisegundos, y crece con el tamaño del conjunto de dependencias. Un verify es la más barata de las dos formas, porque una comparación se salta el descenso a los orígenes de cada componente que realiza una ejecución que escribe. Si tu cliente impone un tiempo de espera por llamada, esta es la herramienta con la que comprobarlo. Pedir que se te informe de cómo va, más abajo, significa que llega algo mientras la llamada se ejecuta en lugar de nada hasta que termina — lo que responde a un tiempo de espera por inactividad en tu cliente, o en lo que haya entre tú y un servidor al que se llega por HTTP, pero no a un límite de cuánto puede durar en total una llamada.
Una entidad cuyo entity.lock no registra ninguna fijación para una entrada que lee rechaza el pull, y el rechazo nombra el paso que la registra. Se espera que una Recipe o una FeatureRecipe que la Release compila a partir de tus directorios de catálogo, y que lee un origen remoto escrito por completo o importa un archivo a través de sus artefactos, lleve ya esas fijaciones a su lado — su autor las registra con pin, más abajo. pin_sources pide a esta llamada que ejecute ese paso en nombre del autor sobre cada una de esas entidades en lugar de rechazar, escribiendo el entity.lock junto a cada una; es el mismo paso que ejecuta la herramienta pin, y escribe los mismos bytes. Omítelo y decide el pin_sources_at_pull del espacio de trabajo; envíalo y decide en cualquiera de los dos sentidos, de modo que pin_sources: false rechaza incluso en un espacio de trabajo configurado para fijar. Una entidad que la resolución alcanzó en la caché y no en uno de tus directorios de catálogo no tiene aquí un lugar donde escribir y esta llamada nunca la fija.
Fijar las entradas propias de una entidad
pin registra, en el entity.lock junto a una Recipe o una FeatureRecipe, la fijación de contenido de cada entrada que la entidad lee desde fuera de su propio documento: un origen remoto cuyas coordenadas están escritas por completo, y un archivo que importa una entrada de artefactos. Es el mismo paso que aggrega pin ejecuta en una terminal, y el lock que escribe es idéntico byte a byte al que escribe ese comando. Pasa entity, el documento de la entidad, absoluto o relativo a la raíz del espacio de trabajo con el mismo contrato que siguen todos los demás argumentos de ruta aquí; por HTTPS debe resolverse dentro del espacio de trabajo que sirve el proceso.
No se nombra ninguna Release, porque no hace falta ninguna. Un origen cuyas coordenadas no llevan ninguna plantilla nombra un único artefacto para cada Release que usa la entidad, así que el paso lo resuelve y lo fija sin nada que aporte una Release. Un origen cuyas coordenadas provienen de una plantilla no se fija aquí: qué artefacto nombra lo decide cada Release, y pull fija cada identidad a la que se resuelve en el lockfile de esa Release.
El resultado dice qué hizo el paso con el lock. Lleva la entity, su kind y su name, y pinnable, que es false para un tipo que no lee nada de lo que registra un lock — un Component o una Feature —, en cuyo caso no se tocó nada junto a la entidad y los demás campos están ausentes. En caso contrario lleva el lock que escribió, changed, false cuando el lock ya registraba cada fijación y se dejó idéntico byte a byte, removed cuando la entidad ya no lee nada de lo que registra un lock y su lock se eliminó, y pins, una entrada por clase de fijación con el recuento que contiene después el lock. dry_run responde con el lock que escribiría el paso como content y no escribe nada junto a la entidad; la caché de contenido se llena igualmente, porque las entradas se resuelven exactamente como se resolverían de otro modo.
Escribe dentro del espacio de trabajo y llega a los hosts que nombran los orígenes de la entidad — un repositorio de charts, un host de Git, una URL —, así que por HTTP se admite para una credencial que lleva el ámbito que admite pull, y se rechaza para una que solo puede leer. Por la entrada y la salida estándar la misma capacidad también es accesible como cli-pin, que ejecuta el comando; por HTTP esa herramienta no existe.
Recibir información sobre cómo va una llamada larga
Una llamada informa de su progreso cuando pides que se te informe, y pedirlo es un solo campo. Pon progressToken en el _meta de la llamada — una cadena o un número, a tu elección. Vuelve en cada informe exactamente como lo escribiste, y es lo único de un informe que remite a tu llamada: un informe no responde a nada, así que no lleva ningún id. No envíes ningún token, o envíalo como null, y nada cambia — la llamada se responde igual que sin él. Un token de cualquier otra forma se rechaza, antes de que la llamada haga nada, nombrando las dos formas que puede adoptar en lugar de pasarse por alto: un llamante que pidió que se le informara y luego se encuentra con silencio no tiene nada sobre lo que actuar.
Lo que llega es notifications/progress, con tu token y un recuento que aumenta con cada uno. No hay total ni mensaje, y ninguno de los dos es una omisión pendiente de trabajo: lo que informa el trabajo es que ha entrado en otra fase, así que un total solo podría inventarse y una frase solo podría componerse aquí en lugar de transmitirse. Dibuja un indicador indeterminado a partir del recuento creciente; no hay ninguna fracción con la que llenar una barra.
Por HTTP la respuesta se convierte en un flujo de eventos, y solo una vez que algo ha informado realmente. Se sirve como text/event-stream, marcada para no almacenarse en caché, y con X-Accel-Buffering: no para un intermediario que de otro modo retendría cada evento hasta que terminara el trabajo y convertiría el flujo en una única respuesta lenta. Cada informe es un evento, y la propia respuesta de la llamada es el último evento antes de que se cierre el flujo. Mientras el trabajo está en silencio, el flujo lleva a intervalos una línea de comentario, que llega a lo que haya en medio como bytes en una conexión activa y no le llega a tu cliente en absoluto. Una llamada que pidió progreso y llegó a un trabajo que no informa de ninguno se responde igualmente con un único objeto JSON, porque lo que abre el flujo es el primer informe y no el token.
En un flujo, lee el resultado de ese último evento y no del código de estado. El estado y las cabeceras se escriben cuando se abre el flujo, es decir, antes de que termine el trabajo, así que una llamada que informa y luego rechaza lleva su rechazo como último evento bajo el estado ya enviado. Cerrar la conexión a mitad del flujo termina el trabajo y no se escribe nada más para él, exactamente como Cómo termina una llamada describe para cualquier otra llamada.
Por la entrada y la salida estándar los informes son líneas que preceden a la línea de respuesta, enmarcadas como cualquier otro mensaje de ese flujo — un objeto JSON por línea, en el orden en que se escribieron —, y la línea de respuesta las sigue. No se informa de nada una vez que una llamada ha terminado, en ninguno de los dos transportes.
Resolver las dependencias de una Release es lo que informa aquí. pull informa cada vez que la resolución entra en una fase. build informa solo cuando resuelve primero — porque enviaste auto_pull, o porque el ajuste propio del espacio de trabajo pide a cada compilación que contiene que resuelva —, ya que el informe pertenece a ese paso: una compilación que renderiza a partir de las fijaciones que ya tiene no llega a nada y no informa de nada, así que un token en esa llamada no cambia nada en cómo se responde. Cualquier llamada informa además de cada paso en el que entra su trabajo y que espera —leer un registro, obtener un artefacto o un paquete de documentación, compilar un plugin por primera vez—, los pasos que la línea de comandos muestra a una persona junto a su indicador de progreso. Una llamada cuyo trabajo no espera ninguno de ellos no informa de nada, lo cual es inofensivo y no un error: la respuesta es la que habrías recibido sin él.
Preguntar qué conexión está escrita en un lugar de un documento
connection-at-position responde a la pregunta previa a la mitad de conexiones de las dos herramientas anteriores, para cuando tienes un lugar en un documento en vez de un nodo en un grafo — una línea que estás viendo en un Aggregate o en una Release. Pasa file, el documento, relativo a la raíz del espacio de trabajo o absoluto y leído del disco del mismo modo en que insertion-point lee uno; position, una line y un character, ambos contados desde cero, medidos en las unidades que indica position_encoding exactamente como insertion-point lee ese argumento; y release, la Release cuyo grafo compilado registra las conexiones. La Release es obligatoria también para un lugar en el Aggregate: un nodo del grafo y una conexión solo existen en un grafo compilado.
La respuesta es una de dos mitades. Donde el lugar está en la entrada de una conexión, contiene graphNode y connection — su socket, su alias y el document en el que se leyó el lugar —, que son exactamente lo que attach-candidates recibe junto a graph_node y release, y lo que attachment-container recibe para indicar dónde va una vinculación en esa conexión; ese contenedor está dentro de la misma entrada en la que cayó el lugar. En caso contrario, contiene noConnectionReason, de un conjunto cerrado: no-connection-entry (el lugar no está en ninguna entrada en la que se escriba una vinculación), feature-created-connection (el lugar está en la entrada de la Release para una conexión que trazó una Feature) o unknown-connection (el lugar está en una entrada que la Release escribe para una conexión que el grafo compilado no contiene). La respuesta legible expone el motivo con palabras.
Un lugar en cualquier parte dentro de una entrada está dentro de ella — en el alias, en su target, dentro de sus features — y, donde las entradas se anidan, gana la más interna. Un lugar en la propia clave de un socket, por encima de los alias que hay debajo, no está dentro de ninguno de ellos. Las entradas son las que registra el grafo compilado: en el Aggregate, cada conexión que traza un componente, en su entrada bajo el alias de la conexión en el documento en el que se escribió el componente, que, para un componente que aporta un módulo importado, es el propio documento de ese módulo; en la Release, cada entrada por arista que escribe. Una conexión escrita como lista de destinos, y una que traza el propio bloque de dependencias de una Feature, no tienen ninguna entrada en la que se escriba una vinculación. Si una clave es una conexión nunca se deduce de cómo se llama.
Responde y se detiene. No escribe nada en ningún archivo. Un documento que no está en el espacio de trabajo, no se puede leer o no es YAML bien formado vuelve como resultado fallido que indica qué cambiar, igual que con insertion-point; lo mismo ocurre con un lugar al que le falta su line o su character, y con un position_encoding fuera de los tres.
Preguntar en qué contenedor va una vinculación
attachment-container responde a la pregunta que hay entre una respuesta de candidatura y un punto de inserción. Has decidido qué vincular a un nodo; antes de poder preguntar en qué lugar de un archivo escribirlo, necesitas saber qué archivo y qué contenedor dentro de él. Pasa graph_node — el id de un nodo en un grafo compilado, tal como el grafo lo usa como clave — y release, la Release a la que pertenece el grafo. Ambos son obligatorios: el id de un nodo es una clave del grafo de una Release y no significa nada sin ella.
No construyas esa ruta tú mismo. El id de un nodo y la ruta del subsistema que lo contiene se escriben ambos con puntos entre sus partes, y el punto es un carácter válido en un nombre que escribe un autor — así que desde fuera del documento no hay forma de distinguir un punto estructural de uno que forma parte de un nombre. Una ruta que compusieras se leería correctamente y apuntaría a una clave que nadie escribió, y la edición posterior crearía esa clave en lugar de ser rechazada. Peor aún, el id de un nodo no lleva rastro alguno del subsistema que lo contiene: un componente escrito dentro de subsystems.billing.subsystems.payments tiene como clave ledger, exactamente igual que un componente de nivel superior. Pide el contenedor.
La respuesta contiene node, el nodo al que se refiere; file, el documento en el que se escribió ese nodo; y container, la ruta estructural desde la raíz de ese documento como lista de segmentos — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Es una lista y no una cadena unida a propósito: una ruta unida tendría que volver a dividirla quien la recibiera, lo que reintroduciría la ambigüedad anterior una llamada más tarde. Pasa file y container a insertion-point sin cambios.
file forma parte de la respuesta en lugar de ser algo que ya sabes. Un nodo que aportó un módulo importado se escribió en el propio documento de ese módulo con el nombre que el módulo le dio, así que tanto el archivo como el último segmento del contenedor difieren de cualquier cosa que hayas enviado.
Para una vinculación en una conexión que traza el nodo, añade connection con su socket, su alias y su document, que aquí es obligatorio porque cualquiera de los dos documentos puede contener una. Con aggregate, la respuesta es la propia entrada de la conexión en el documento en el que se escribió el nodo, con su bloque features al final; una conexión que trazó la Release no tiene allí ninguna entrada y se rechaza. Con release, es la entrada por arista bajo la entrada de la Release para el nodo — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] —, que se indica tanto si la Release ya escribe esa entrada por arista como si no, de modo que insertion-point indica las claves que faltan por escribir; una Release que no escribe ninguna entrada para el nodo se rechaza, ya que no le corresponde a esta herramienta decidir dónde se coloca el nodo. Una conexión que trazó una Feature se rechaza en ambos documentos.
Responde y se detiene. No crea ninguna vinculación, no escribe nada en ningún archivo y no compone ningún texto. Tampoco decide qué se puede vincular — eso es attach-candidates. Un nodo que el grafo no contiene, o uno para el que no registra ningún documento, vuelve como resultado fallido que indica qué cambiar en lugar de como una respuesta con un campo vacío.
Localizar dónde va una entrada en un documento
insertion-point responde a la pregunta que sigue a una respuesta de candidatura. Has decidido qué vincular o conectar; ahora necesitas saber en qué lugar del archivo escribirlo. Devuelve una posición y las columnas en las que sangrar, para que puedas aplicar la edición sin analizar tú mismo el documento. Como lo que lee es la estructura propia de un documento y no la forma de un tipo concreto, describe-capabilities lo indexa bajo cualquier tipo de entidad al que restrinjas la consulta.
Pasa file — el documento, relativo a la raíz del espacio de trabajo o absoluto, y dentro del espacio de trabajo: uno al que se llega mediante un enlace que sale de él, hacia el archivo o hacia un directorio del camino, no lo está, y se rechaza en ambos transportes — y container, la ruta estructural desde la raíz del documento hasta el contenedor en el que va la entrada, donde cada elemento es una clave de mapping o una posición de secuencia escrita en decimal.
La ruta del contenedor la proporcionas tú. La herramienta lee la estructura del documento y nunca deduce dónde va algo por cómo se llama, qué tipo lleva o qué parece significar. Tú dices qué clave; ella dice dónde van las entradas de esa clave en este documento — qué segmentos de la ruta contiene ya el archivo, en qué columnas están sus entradas y la última línea a la que llega su bloque más interno. Para vincular una Feature a un nodo de un grafo compilado no necesitas conocer tú mismo esa clave: attachment-container, descrito arriba, indica el documento y el contenedor, y ambos van aquí sin cambios.
La respuesta es una position de ancho cero, cuyos line y character cuentan ambos desde cero; entryIndent e indentStep, las columnas en las que escribir; y missingContainerKeys, las claves de contenedor que este documento aún no contiene, empezando por la más externa, que escribes antes de la entrada. entryShape indica si el contenedor contiene un mapping o una sequence, e indica unknown donde el contenedor aún no existe o no contiene nada, porque el documento no lo ha dicho — la forma la eliges entonces tú. indentStepMeasured indica si el paso se midió a partir del anidamiento propio de este documento o es un valor de reserva para un documento que no presenta ninguno. Donde precededByLineBreak está establecido, empieza tu texto con un salto de línea: la posición se encuentra al final de la línea a la que sigue la entrada, que es válida tanto si el archivo termina en un salto de línea como si no, y no altera ningún byte ya escrito. Lee missingContainerKeys incluso donde esperes que el contenedor exista — una posición aplicada sin las claves que deben precederla produce un documento que ya no se puede analizar.
position_encoding indica las unidades en las que se mide el desplazamiento de caracteres indicado: utf-8, utf-16 o utf-32. Aquí es un argumento porque ninguna de las dos revisiones de este protocolo negocia una, y su valor predeterminado es utf-16, que es lo que adopta una sesión de editor cuando un cliente no negocia nada — de modo que a quien llama sin indicar nada se le responde de forma idéntica en ambas superficies. Un valor que no es ninguno de los tres se rechaza en lugar de sustituirse en silencio por el predeterminado, porque los desplazamientos medidos de una forma y aplicados en un búfer medido de otra corrompen el documento en el primer carácter fuera de ASCII.
Responde y se detiene. No escribe nada en ningún archivo, no compone ningún texto de entrada y no aplica ninguna edición; componer el texto y decidir si aplicarlo te corresponde a ti. Una solicitud que no apunta a un lugar en el que pueda ir una entrada vuelve como resultado fallido que indica qué cambiar — un documento que no está en el espacio de trabajo, no se puede leer o no es YAML bien formado; una ruta de contenedor sin segmentos o con uno vacío; una ruta que atraviesa un escalar, dentro del cual no se puede añadir nada; una ruta que llega a una colección escrita en estilo flow, donde añadir reescribiría bytes que el autor ya escribió en lugar de agregar una línea; o una ruta que apunta a una secuencia de bloque con algo que no es uno de sus índices. Si prefieres que la edición se aplique en lugar de aplicarla tú, Aplicar una única edición acotada a un documento es la herramienta que lo hace.
Aplicar una única edición acotada a un documento
edit-document aplica lo que localizan las dos herramientas anteriores. Una llamada añade una entrada bajo un contenedor, o establece un escalar, y no puede hacer nada más. Escribe el documento que indicas, dentro del espacio de trabajo, así que por HTTPS necesita aggrega:workspace-write: quien llama con solo aggrega:read la encuentra en la lista de herramientas, y una llamada suya se rechaza indicando ese alcance.
Indica la edición en edit; el conjunto es cerrado. add-component añade una instancia de componente bajo un contenedor de componentes; attach-feature vincula una Feature al nodo que indicas; wire-edge cablea una conexión dentro de uno de los sockets de ese nodo; set-value establece un valor en ese nodo. Un nombre fuera de esos cuatro se rechaza en lugar de interpretarse. No hay ninguna edición que elimine, reemplace un bloque que ya escribiste, reordene algo o escriba literalmente bytes que proporcionas — así que esto no es un escritor de archivos y no se puede usar como tal.
Pasa file, el documento — relativo a la raíz del espacio de trabajo o absoluto, y dentro del espacio de trabajo: uno fuera de él, tal como está escrito o mediante un enlace que sale de él, se rechaza en ambos transportes sin que se lea ni se escriba nada; node, la ruta estructural desde la raíz del documento como lista de segmentos; name, la clave bajo la que se escribe la entrada; y value, lo que contiene esa entrada. node es una lista por la misma razón por la que attachment-container responde con una: un punto es válido dentro de un nombre que escribe un autor, así que una ruta unida podría apuntar a una clave que nadie escribió y la entrada se crearía allí en lugar de rechazarse. Para add-component, la ruta indica el propio contenedor de componentes, porque la entrada que se añade es el nodo; para las otras tres, indica el nodo al que se refiere la edición, y el contenedor se deriva de la edición. socket se lee para wire-edge y se ignora en los demás casos. Lo que significa value se deriva de edit — la entidad que solicita la entrada, el nodo al que apunta una conexión o el escalar al que se establece un valor — y es un valor JSON de su propio tipo, así que un número sigue siendo un número, un dígito entre comillas sigue siendo texto, y omitirlo no establece nada en absoluto. Un mapping o una secuencia se rechaza, porque escribir un bloque no es una de estas ediciones.
Todo byte que la edición no toca se conserva. El documento solo se analiza para localizar el contenedor y la línea en la que termina su bloque, así que los comentarios, las líneas en blanco, el estilo de comillas, los escalares plegados y literales y la forma del salto de línea final se mantienen, y el paso de anidamiento se mide a partir de la sangría propia del documento en lugar de imponerse. La misma solicitud sobre el mismo documento produce los mismos bytes.
El resultado tiene que ser un documento que podrías haber escrito tú, y de eso depende la escritura. El documento compuesto se comprueba con el esquema de su propio tipo y solo llega al disco si supera esa comprobación. Una solicitud que produciría algo que el esquema rechaza se rechaza, indicando la propiedad que el esquema no admitiría y dónde, y el archivo queda byte a byte como estaba — de modo que una edición rechazada no se distingue de una que nunca se intentó, y puedes reintentar una solicitud corregida sobre el documento con el que empezaste. Una entrada que ya existe con lo que pediste no tiene ningún efecto; una entrada con ese nombre que contiene otra cosa se rechaza en lugar de reemplazarse.
La respuesta contiene container, la ruta estructural en la que quedó la entrada; created_containers, los niveles de contenedor que esta edición tuvo que crear, empezando por el más externo, vacío en el caso habitual en que toda la ruta ya existía; y written, el documento que llegó al disco, vacío donde no llegó ninguno. Lee created_containers: una edición que escribió sin avisar dos bloques anidados que el documento no contenía es, de otro modo, indistinguible de una que añadió una sola entrada a un bloque que escribiste tú.
dry_run hace todo excepto escribir. El documento editado vuelve como content, no se crea nada y written está vacío — para un cliente que muestra el resultado al autor antes de guardarlo. Todo otro comportamiento es el de la escritura, incluida la comprobación del esquema, así que una solicitud que la escritura rechazaría también se rechaza con él. Sin él, el documento se escribe y content está ausente, porque el documento ya está en el disco y written lo indica.
Si lo que cableas es semánticamente admisible — si un socket es uno de los que declara el productor, o si se cumple la aplicabilidad de una Feature — no se decide aquí. Eso es lo que responde validate.
En la entrada y salida estándar, la misma capacidad también está disponible como cli-edit-document, que ejecuta el comando y devuelve el texto que imprimió; por HTTP esa herramienta no existe, y allí se accede a la capacidad mediante esta.
Convertir una descripción externa en borradores de entidades
import convierte una descripción que produjo otra herramienta — por ejemplo, un flujo exportado desde un constructor de agentes — en borradores de archivos de autoría de Aggrega. Escribe esos archivos en el espacio de trabajo que sirve este servidor, así que por HTTPS necesita aggrega:workspace-write: quien llama con solo aggrega:read la encuentra en la lista de herramientas, y una llamada suya se rechaza indicando ese alcance.
Pasa source, el archivo o el directorio que se va a convertir. Es absoluto o relativo a la raíz del espacio de trabajo, el mismo contrato que usa cualquier otro argumento de ruta en esta superficie, y en un servidor al que se accede por HTTPS se resuelve dentro del espacio de trabajo que sirve ese servidor.
De un directorio se leen exactamente los archivos que seleccionan los patrones de archivo de su importador. Un chart o un proyecto es un directorio, y source puede indicar uno. Al importador se le entregan entonces los archivos de este, a cualquier profundidad, que selecciona alguno de los patrones de archivo que declaran sus firmas, cada uno nombrado por su ruta dentro del directorio escrita con barras normales, en orden, junto con los archivos que su vinculación plugins.importer indica bajo with.sources, con sus nombres base; un archivo del directorio y un archivo de with.sources con el mismo nombre se rechazan en lugar de que uno oculte al otro. Un importador que no declara patrones de archivo lee un solo archivo y rechaza un directorio, bajo la condición An importer that declares no file patterns is handed a directory (A un importador que no declara patrones de archivo se le entrega un directorio), y un directorio que no contiene ningún archivo que seleccionen sus patrones también se rechaza. El directorio queda limitado a sí mismo dondequiera que esté: un enlace entre los archivos que leería la importación, o hacia un directorio, que sale de él se rechaza antes de leer nada, y nunca se entra en un enlace a un directorio — como expone Un directorio que importas. En un servidor al que se accede por HTTPS, el directorio mismo se resuelve dentro del espacio de trabajo, y por tanto también todo archivo que se lea de él.
El importador es uno que contiene el catálogo de tu espacio de trabajo, o uno de los importadores básicos del compilador. La traducción es obra del plugin importador que anuncia el formato de la fuente: uno que contiene el catálogo de tu espacio de trabajo, o uno de los importadores básicos del compilador, que sirven sus formatos en todo espacio de trabajo sin ninguna entrada de catálogo. Esta herramienta lo selecciona, lo ejecuta y escribe lo que produjo. Una vinculación plugins.importer cuyo uri indica un importador por su identidad y versión — importer/<name>:<version>, tal como lo escribe aggrega plugin add importer — vincula ese importador: donde anuncia el formato de la fuente, es el que se ejecuta, en esa versión, sea cual sea el otro importador que también anuncie el formato, y recibe las fuentes y la configuración with de esa vinculación, que ningún otro importador recibe. Donde varios importadores anuncian el formato y ninguno de ellos por sí solo está vinculado — entre ellos un importador básico y un importador de otro nombre que tu catálogo contiene para el mismo formato —, la llamada se rechaza indicándolos, como describe Configuración. Un formato que indicas y que ningún importador anuncia se rechaza indicando la capacidad que un importador tendría que anunciar — import:langflow para una fuente de Langflow —, que es lo que declara un importador que añades al catálogo, en lugar de con un fallo genérico que luego tendrías que interpretar.
Un importador básico que la máquina del servidor no tiene se descarga una sola vez, en la primera importación que lo necesita. La importación lo descarga del registro predeterminado del espacio de trabajo servido, lo contrasta con el módulo que publica la versión del compilador, verifica su firma según la política de confianza de ese registro y las funciones de host que usa, igual que un pull verifica un plugin que descarga, y lo guarda en la caché de contenido del espacio de trabajo, de modo que cada importación posterior lo lee de allí y no contacta con ningún registro. No se escribe nada más para él — ningún lockfile ni ninguna lista de plugins de confianza. Por HTTPS, este es el único registro con el que una llamada a esta herramienta puede hacer que el servidor contacte, dentro del límite que establece Qué credenciales gasta una llamada para una lectura de registro: el registro es el predeterminado del espacio de trabajo que sirve este servidor, por lo que es uno con el que está configurado ese espacio de trabajo; nada en la llamada indica un registro ni lleva una credencial; y la descarga gasta el inicio de sesión y la política de confianza propios de este host. La herramienta sigue llegando al espacio de trabajo y a nada más, así que aggrega:workspace-write es todo lo que necesita una llamada: lo que deja la descarga es un módulo en la caché de contenido propia del espacio de trabajo. Un módulo que no supera la verificación se rechaza igual que en una terminal, y no se guarda nada. Donde el módulo no se puede descargar — el espacio de trabajo está sin conexión, no se puede acceder a su registro o el registro no lo contiene —, la llamada se rechaza bajo A plugin’s .wasm is not on this machine (El .wasm de un plugin no está en esta máquina), indicando el importador, su versión y lo que pone su módulo en la máquina.
Donde el espacio de trabajo no indica ninguna carpeta de catálogo, la importación lee el catálogo que publica su registro predeterminado. Un espacio de trabajo cuyos workspace.catalog_dirs, AGGREGA_CATALOG_DIRS y raíz no indican ninguna carpeta de catálogo lee el catálogo de la biblioteca estándar como una única instantánea firmada, en catalog/snapshot en el registro predeterminado del espacio de trabajo servido — el mismo registro del que se obtiene un importador del núcleo, alcanzado en las mismas condiciones, sin que nada en la llamada nombre un registro ni lleve una credencial. Una instantánea se obtiene una sola vez: su firma se verifica según la política de confianza de ese registro, y se guarda en la caché de contenido del espacio de trabajo y se lee allí como una carpeta de catálogo, sujeta a su resumen criptográfico, sin volver a pedírsela a ningún registro. Qué instantánea lee una llamada: con upgrade, la más reciente; si no, la que nombra el historial en el directorio de salida, obtenida por su resumen criptográfico cuando la máquina no la tiene; si no, la que el espacio de trabajo obtuvo por última vez como la más reciente; si no, la más reciente. El historial que escribe la importación nombra la instantánea que leyó, por su resumen criptográfico, de modo que una llamada posterior que redacte borradores en el mismo directorio lee el mismo catálogo. Sin conexión, una llamada que tendría que obtener una instantánea se rechaza indicando qué ejecutar, y upgrade se rechaza tenga lo que tenga la máquina, ya que solo el registro puede decir qué instantánea es la más reciente. Un registro que no publica ninguna instantánea deja la importación sin catálogo, y una entrada warn en diagnostics lo indica. Un espacio de trabajo que indica una carpeta de catálogo importa a partir de ella y no obtiene ninguna instantánea, y allí upgrade no cambia nada.
Si omites format, el formato se reconoce por las firmas que declaran los importadores — tanto las de tu catálogo como las de los importadores básicos. La entidad Plugin de cada importador las registra: la sintaxis en la que se lee una fuente, los nombres de archivo a los que se aplica una firma y las rutas que el árbol analizado debe o no debe contener. La fuente se analiza, mediante el parser que el catálogo de tu espacio de trabajo sirve para una sintaxis — o, para una sintaxis para la que tu catálogo no sirve ningún parser, el que incluye el propio compilador —, una vez por cada sintaxis en la que la lee una firma que se aplica a su nombre, y el formato que se usa es el del único importador cuya firma coincide. El importador lee después la fuente mediante el mismo parser. Las firmas de los importadores básicos leen un archivo como JSON o YAML, y las que no indican ningún archivo lo leen como JSON — la del importador de Dify, como YAML —, así que reconocer un archivo importado por sí solo lo lee en ambos y no necesita ningún parser en el catálogo de tu espacio de trabajo: el compilador incluye un parser de JSON y uno de YAML, y uno que sirva tu catálogo se usa en su lugar. Un directorio se reconoce de la misma forma sobre sus archivos: cada firma se prueba con los archivos de este que seleccionan sus patrones, y una firma que no declara ningún patrón no se aplica a ninguno de ellos. El reconocimiento lee el archivo que indicaste — o, de un directorio, solo los archivos que seleccionan los patrones de una firma — y ninguna red. Una fuente con la que no coincide ninguna firma se rechaza pidiendo format e indicando los formatos que anuncian los importadores — o, para un directorio, pidiendo uno de sus archivos enviado por sí solo como source o un format cuyo importador declare patrones de archivo, indicando solo esos formatos —, bajo la condición No importer recognises the source (Ningún importador reconoce la fuente); una fuente con la que coinciden firmas de más de un formato se rechaza indicándolos, bajo la condición More than one importer recognises the source (Más de un importador reconoce la fuente); ninguna de las dos se entrega a un importador elegido por suposición. Envía format para indicar el formato explícitamente en cualquiera de los dos casos — para un directorio, uno cuyo importador declare patrones de archivo, ya que un directorio solo se lee a través de ellos. Un format vacío se rechaza en lugar de leerse como si lo hubieras omitido, porque son solicitudes distintas.
Envía target para redactar en borrador el Manifest con el que se construye la Release en borrador para un proveedor. target es una capacidad de proveedor — la palabra a la que se vincula el spec.capability de una Recipe, como compose o helm — y es el --target de aggrega import, compuesto por la misma operación, de modo que una llamada y el comando redactan los mismos archivos a partir de la misma fuente. Para cada tipo de componente y cada tipo de funcionalidad que necesitan los borradores — en los componentes del Aggregate en borrador, sus conexiones y sus subsistemas, en los Aggregates del catálogo que compone y en las vinculaciones de la Release en borrador —, en el orden en que los borradores lo declaran por primera vez, la importación busca en el catálogo del espacio de trabajo las Recipes, o para un tipo de funcionalidad las recetas de funcionalidad, que implementan el tipo y se vinculan a esa capacidad. Donde hay exactamente una — varias versiones de una cuentan como una —, el Manifest asigna el tipo a ella por su nombre calificado por la capacidad, sin versión, como compose/postgres, que el primer pull fija en el lockfile en la versión más alta disponible. Donde hay varias de nombres distintos, asigna la que lleva el nombre del propio tipo, como helm/postgres para core/datastore/postgres. Donde no hay ninguna, o hay varias y ninguna se llama así, el tipo queda sin asignar y una entrada warn en diagnostics lo indica junto con el motivo — las varias, cada una por su nombre —, de modo que una compilación de los borradores se detiene indicando cada instancia o vinculación suya, bajo No Recipe is mapped for a component or feature instance (No hay ninguna Recipe asignada para una instancia de componente o de funcionalidad), hasta que se añada la asignación. Donde el propio importador redacta el Manifest, para elegir la Recipe a través de la cual se renderiza una instancia o una receta de funcionalidad entre varias, cada asignación que escribió y que el catálogo ofrece para ese tipo y esa capacidad se conserva, cualquier otra se descarta con una entrada warn, y los tipos que deja se asignan como se indica arriba. El Manifest se redacta como manifest.yaml junto a la Release en borrador, con el mismo nombre y versión que la Release, y el spec.manifest de la Release se establece en ese nombre — el comentario que el importador escribió en su lugar se reemplaza, y nada más cambia en la Release. Una Release que ya indica un Manifest se deja como está, y donde la importación no redacta ninguna Release, el Manifest se redacta junto al Aggregate, con su nombre y versión, y una entrada info indica que nada hace referencia a él. El Manifest y la Release editada son borradores como los demás: en written, en el historial y devueltos bajo dry_run. Un target al que no se vincula ninguna Recipe del catálogo se rechaza antes de que se ejecute el importador, bajo An import’s target names a capability no Recipe in the catalog binds to (El destino de una importación indica una capacidad a la que no se vincula ninguna Recipe del catálogo), indicándolo tal como lo enviaste junto con las capacidades a las que se vinculan las Recipes del catálogo, y no se escribe nada. Si omites target, no se redacta ningún Manifest — excepto bajo sync, que redacta para el destino con el que se envió la importación anterior; un target vacío se rechaza en lugar de leerse como si lo hubieras omitido.
Envía output_dir para indicar el directorio en el que van los borradores. Si lo omites, quedan bajo la raíz del espacio de trabajo que resolvió la llamada — el lugar en el que aggrega import los escribe cuando no indicas ningún destino, dondequiera que lo ejecutes, y el lugar en el que aggrega/import del servidor de lenguaje los escribe cuando su solicitud no indica ninguno. El destino es opcional en los tres, y se indica del mismo modo que cualquier ruta que envíes a este servidor. Por HTTP es un directorio dentro del espacio de trabajo que sirve este servidor, escrito de forma relativa a su raíz: un valor que sube fuera de la raíz, una ubicación absoluta fuera de ella y un directorio que sale de ella mediante un enlace — incluido un directorio aún no creado bajo un enlace así — se rechazan cada uno indicando output_dir, y no se lee ni se escribe nada. En la entrada y salida estándar se toma tal como se indica, como toda ruta allí: un valor relativo se resuelve respecto a la raíz del espacio de trabajo que resolvió la llamada, y uno absoluto puede indicar un directorio fuera del espacio de trabajo, en el que se redacta igual que aggrega import --output-dir redacta en él. Lo que se escribe allí queda limitado, con sus enlaces resueltos, al espacio de trabajo — o, para un directorio que indicaste fuera de él, a ese directorio —, de modo que un enlace dentro de él que sale de él se rechaza y no se escribe nada. Un output_dir vacío se rechaza en lugar de leerse como si lo hubieras omitido. En la entrada y salida estándar, cli-import también lleva el --output-dir del comando como su propio output_dir; allí, un valor relativo se resuelve en la carpeta en la que se ejecuta el comando: la raíz del espacio de trabajo que indica la llamada; si no, aquella con la que se inició el servidor; y si no, la carpeta en la que se ejecuta el servidor.
Cada ruta de borrador se comprueba con el directorio de salida antes de escribir nada. Una ruta que sale de él se rechaza indicando tanto la ruta como el directorio, y no se escribe absolutamente nada — ni siquiera los archivos del mismo conjunto cuyas rutas propias eran correctas, porque una importación rechazada que dejara parte de sí misma sería un resultado que nadie pidió. Una ruta de borrador procede del plugin importador y no de ti, y por eso se comprueba por la misma razón que una ruta que envías tú.
Toda importación que redacta algo escribe también .aggrega-import.json junto a sus borradores: el historial de lo que escribió — el target con el que se envió, cuando se envió con uno, la instantánea del catálogo que leyó, cuando leyó una, y cada archivo en borrador y, en un Aggregate o una Release en borrador, cada clave a cualquier profundidad, con un resumen criptográfico del texto escrito allí; cualquier otro archivo en borrador se registra completo. El texto de una clave es su línea, las líneas de su valor cuando su valor no es un mapping de claves, y las líneas de comentario escritas justo encima de ella con su misma sangría. written indica el historial junto con los borradores, y bajo dry_run está entre los borradores devueltos. El historial es JSON, así que nada que lea los documentos YAML del espacio de trabajo lo lee.
Una llamada nunca sobrescribe un Aggregate que ya está en el directorio de salida. Un Aggregate es el documento que un autor sigue editando una vez redactado, así que una llamada uno de cuyos borradores caería en un archivo que se lee como un Aggregate se rechaza, indicando el borrador y el directorio, y no se escribe absolutamente nada — también bajo dry_run, ya que una ejecución de prueba rechaza lo que rechaza la escritura. Cualquier otro archivo que ya esté en una ruta de borrador se sobrescribe, y un archivo que redactó una importación anterior y que esta no redacta se deja donde está.
Envía sync para, en cambio, poner al día con la fuente lo que redactó una importación anterior, cambiando solo lo que escribió la importación. Una sincronización a la que no se envía ningún target redacta para el destino que indica el historial, así que redacta el Manifest que redactó la importación anterior; una a la que se envía un target redacta para él, y después el historial lo indica. Un destino registrado al que no se vincula ninguna Recipe del catálogo se rechaza igual que uno enviado, y el rechazo indica que el destino es el registrado. Cada parte se juzga de tres maneras — lo que el historial dice que la importación escribió allí por última vez, lo que hay en el disco y lo que la fuente redacta ahora. Una parte que la fuente dejó tal como la importación la escribió por última vez queda exactamente como está en el disco, la haya editado un autor o no. Una parte que la fuente cambió se reescribe, una parte que eliminó se quita — un archivo en borrador se borra completo —, y una parte que ganó se añade junto a las partes que el borrador indica a su alrededor, cada una solo donde lo que hay en el disco es lo que la importación escribió por última vez y no contiene nada que haya añadido un autor. Todo lo demás se conserva byte a byte: una clave que un autor añadió en cualquier lugar — un parámetro, una Feature, también bajo una instancia de Component en borrador, otro Component, el entorno que una Release en borrador deja a su autor —, un comentario que no está escrito justo encima de una clave en borrador, y todo archivo que el historial no enumera. El drift de la respuesta enumera cada parte puesta al día — o, bajo dry_run, cada parte que lo sería — en el orden en que el borrador las nombra, cada una como change (added, removed o changed), file, el archivo en borrador en el que está, y key, las claves que llevan a ella en un Aggregate o una Release en borrador, como lista, vacía donde la parte es el archivo completo; la respuesta de texto nombra cada una en una línea propia con las palabras que aggrega import escribe en la salida de error estándar, <change> <key> in <file> o <change> <file>. Un drift vacío bajo dry_run indica que los borradores están al día con la fuente. Bajo dry_run, los borradores devueltos son los archivos que escribiría la sincronización, con el contenido que les daría. Una sincronización que cambiaría o quitaría una parte que editó un autor, añadiría una parte donde un autor ya escribió una, o quitaría una parte que contiene algo que añadió un autor se rechaza, indicando cada una de esas partes y el motivo, y no se escribe nada; un comentario escrito justo encima de una clave en borrador edita esa clave. Una sincronización sobre un Aggregate que ningún historial enumera se rechaza indicándolo, al igual que una cuyo historial no se puede leer, y una sincronización cuyo importador no pudo terminar no escribe nada. Una sincronización en un directorio que no contiene ningún historial ni nada en sus rutas de borrador escribe el borrador completo. drift es una lista vacía para una llamada que no es una sincronización.
La respuesta contiene source, tal como la indicaste; format, cómo se leyó la fuente; workspace_root, la raíz del espacio de trabajo que resolvió la llamada; output_dir, el directorio respecto al cual son relativas las rutas de borrador; written, los archivos que llegaron al disco; drift, lo que puso al día una sincronización; diagnostics, una entrada por cada construcción que el importador no pudo traducir; decisions, cómo asignó el importador cada nodo de la fuente; y halted. output_dir es el directorio que enviaste, o esa raíz cuando no enviaste ninguno, tomado de lo que la importación usó realmente, y se indica también bajo dry_run, donde no se escribe nada pero cada ruta de borrador sigue siendo relativa a él. Por HTTP, workspace_root se retiene y se marca con workspace_root_withheld, porque la raíz es un lugar en el host del servidor, como expone Qué dice una respuesta sobre el sistema de archivos del servidor; output_dir se retiene y se marca con output_dir_withheld cuando es esa raíz, y en otro caso se indica por su nombre relativo a la raíz — la forma que tienen tus propias rutas —, de modo que adónde fueron los borradores sigue estando en la respuesta. Una importación que el importador no pudo terminar redacta igualmente lo que pudo, y vuelve marcada como fallo con esa respuesta completa — halted en true, los archivos que sí llegaron al disco indicados en written y, junto a ellos, los diagnósticos que indican lo que falta. Es un resultado parcial que puedes conservar o descartar, no una llamada que no hizo nada.
decisions indica dónde adivinó la importación. Contiene una entrada por cada nodo de la fuente que asignó el importador, en el orden del importador: source_node, el id, el type y el params_summary del nodo; candidates, cada Component del catálogo que el importador sopesó para él, como component, score, tier y signals — lo que aportó cada una de sus señales, bajo table, category, domain_labels, shape y name; chosen, el target que eligió, el mode en que lo escribió — una reference a un Component existente o un draft — y el tier de la elección; rationale, el porqué; y swap_hint, cómo elegir de otra forma. candidates está ausente donde el importador no sopesó ninguno, chosen donde no hizo ninguna elección, y rationale y swap_hint donde no escribió ninguno. Cada valor es del propio importador — cómo puntúa un candidato y dónde caen sus niveles son decisiones suyas —, así que lee una entrada como su explicación de la asignación. decisions está en la respuesta tanto bajo dry_run como cuando la importación se detuvo, y es una lista vacía para un importador que no informa de ninguna. La respuesta de texto nombra cada decisión en una línea propia después de los diagnósticos, con las palabras que aggrega import escribe en la salida de error estándar: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, siendo la puntuación la del mejor candidato.
dry_run hace todo excepto escribir. Cada archivo en borrador vuelve bajo drafts con su ruta, relativa a output_dir, y su contenido, y no se crea nada — para un cliente que te muestra el resultado antes de guardarlo. Todo otro comportamiento es el de la escritura, el mismo importador sobre la misma fuente informando de los mismos diagnósticos, así que una fuente que la escritura rechazaría también se rechaza con él. Sin él, los archivos están en el disco y written los indica, y drafts está ausente en lugar de repetir bytes que pediste que se escribieran.
Los borradores son un punto de partida que te pertenece y que sigues editando. Si lo que dicen es admisible — si un socket es uno de los que declara el productor, o si se cumple la aplicabilidad de una Feature — no se decide aquí. Eso es lo que responde validate.
En la entrada y salida estándar, la misma capacidad también está disponible como cli-import, que ejecuta el comando y devuelve el texto que imprimió; por HTTP esa herramienta no existe, y allí se accede a la capacidad mediante esta.
Publicar, firmar y retirar
Cuatro herramientas colocan algo donde otras personas lo resolverán. publish-entity empaqueta una entidad del catálogo y la publica; publish-artifact publica un archivo independiente, como un paquete de documentación, con sus bytes opacos y sin analizar ningún sobre de entidad; sign-artifacts firma referencias ya publicadas y adjunta cada firma, dejando tal como está una referencia que ya lleva una que la política de confianza de su registry verifica; deprecate-artifact adjunta a una referencia un marcador de retirada firmado. Lee Qué puede hacer un asistente sin preguntarte primero antes de permitir cualquiera de ellas: son las herramientas cuyos efectos salen de la máquina.
publish-entity recibe entity, el documento que se publica, y un Plugin necesita además plugin, el ejecutable publicado dentro de su manifiesto. publish-artifact recibe file con el name y el tag con los que se publica. Aquí cada argumento de ruta es absoluto o relativo a la raíz del workspace, el mismo contrato que usa cualquier otra herramienta de esta superficie, y workspace_root indica el workspace al que se refiere la llamada, en un servidor al que se llega por la entrada y la salida estándar. Un servidor al que se llega por HTTPS rechaza workspace_root y exige que cada una de esas rutas se resuelva dentro del workspace que sirve, como explica Un proceso, un workspace. registry es el destino y su valor predeterminado es el configurado en el workspace; no enviar ni lo uno ni lo otro, sin ningún valor predeterminado configurado, se rechaza indicando qué enviar. sign-artifacts recibe references, una o más direcciones de registry en lugar de rutas, y opcionalmente jobs, cuántas de ellas se firman a la vez: si se omite, se firman una tras otra, y un valor inferior a 1 se rechaza indicando qué enviar. Cada una se firma de todos modos exactamente como se firmaría sola, como describe aggrega sign. deprecate-artifact recibe o bien reference con severity y reason, o bien from que indica un archivo de lote, y rechaza los argumentos de contenido enviados junto con un archivo de lote en lugar de descartarlos, porque un archivo de lote aporta los suyos y un argumento ignorado en silencio parece uno que se ha respetado.
Las dos herramientas de publicación reciben dry_run, que muestra lo que enviaría una publicación sin contactar con ningún registry. Calcula el paquete, informa de lo que habría publicado y responde con beyond_this_machine en false y el destino al que se habría dirigido en registries; publish-entity responde además con el digest que produciría esa publicación, el mismo que imprime aggrega push --dry-run. Es la forma de mostrarle a alguien una publicación propuesta antes de que se convierta en una. Firmar y retirar no tienen una forma así: ambas actúan sobre algo ya publicado, de modo que no hay nada que previsualizar.
publish-entity responde con windows_unusable_entries cuando el archivo comprimido que publica contiene entradas que Windows no puede guardar tal como están escritas —una ruta con una parte que lleva el nombre de un dispositivo, como CON, AUX o NUL, con cualquier combinación de mayúsculas y minúsculas y sea cual sea la extensión que siga, o una parte que termina en punto o en espacio—, nombrando cada una, primero el nombre de archivo del propio documento de la entidad y luego los archivos que lleva. El campo no aparece cuando no hay ninguna, lo que incluye una entidad publicada como su documento solo. aggrega ejecutado en Windows se niega a desempaquetar una entrada así, de modo que un workspace de Windows no puede usar la versión; son las entradas sobre las que advierte aggrega push, y el texto de la respuesta también las nombra. No rechazan nada: la llamada sigue adelante o se rechaza exactamente como ocurriría sin ellas, dry_run incluido.
publish-entity recibe pin_sources, que ejecuta sobre la entidad el paso de pin del autor de la entidad antes de empaquetarla, de modo que el entity.lock que el paso escribe junto a ella forma parte de lo que se publica. Es el mismo paso que ejecuta la herramienta pin, que escribe los mismos bytes, y se ejecuta antes de cualquier rechazo que juzgue la entidad, así que una publicación rechazada en ese punto, por ejemplo por falta de una firma, deja igualmente el lock escrito junto a la entidad. Un rechazo sobre la propia llamada, como un workspace sin conexión o la falta de destino, llega primero y no fija nada. Si lo omites decide pin_sources_at_push del workspace; si lo envías, decide él en cualquiera de los dos sentidos. Una publicación que fija escribe dentro del workspace además de en el registry, por lo que sobre HTTP necesita una credencial que lleve ambos scopes, y una que solo lleve el scope que permite publicar se rechaza indicando el otro. El resultado lleva pin, con la forma con la que responde la herramienta pin, cuando el paso se ha ejecutado; con dry_run el paso informa del lock que escribiría y no escribe nada. Cuando el paso no se ejecuta, se rechaza una Recipe o FeatureRecipe cuyo entity.lock no registra ningún pin para una entrada que lee —o una con la que la entrada ya no coincide— antes de empaquetar nada, dry_run incluido, indicando aggrega pin, pin_sources y pin_sources_at_push. Es el rechazo que pull genera sobre el mismo lock, y comprobarlo descarga cada fuente remota que la entidad escribe completa, como haría el paso.
Firmar es donde se gasta la credencial, y tres de las cuatro herramientas lo hacen: la publicación de un artefacto de datos no firma nada y se firma después por referencia. identity_token aporta una identidad sin clave para la llamada. En un servidor al que se llega por la entrada y la salida estándar, omitirlo hace recurrir a la identidad que lleva el propio entorno de ese servidor, y key_path selecciona en su lugar una clave guardada sin conexión. A través de un listener no se llega a ninguna de las dos: el entorno no se lee, key_path se rechaza y se retira de lo que anuncian estas tres herramientas, y no se llega a una clave que nombre la configuración del workspace servido, así que solo firma un token enviado en la llamada, como explica Qué credenciales gasta una llamada. Una llamada firma con una sola credencial. Cada referencia enviada a sign-artifacts, y cada entrada de un archivo de lote que lee deprecate-artifact, se firma con la misma clave guardada o la misma identidad sin clave; cuando la configuración del workspace servido nombra una clave para el registry de una referencia y ninguna para el de otra, o dos claves distintas, la llamada no firma nada y se rechaza indicando los registries de cada lado, antes de que se resuelva ninguna identidad o se lea ningún registry: envía una llamada por credencial, o un único key_path para todas por la entrada y la salida estándar. A través de un listener no se llega a ninguna clave configurada, así que allí cada referencia se firma con la identidad que envía la llamada y la llamada nunca se rechaza por este motivo. El rechazo se describe en References signed together need different signing credentials (Las referencias firmadas juntas necesitan credenciales de firma distintas). fulcio_url, rekor_url y timestamp_url sustituyen los endpoints sin clave que configura el workspace, en cualquiera de los dos transportes. Cuando no se resuelve ninguna identidad, la llamada se rechaza e indica qué enviar: nada de esto abre un navegador ni espera a una persona, porque nadie está observando un flujo de protocolo, y una llamada que se quedara colgada sería justo el fallo silencioso que ese rechazo existe para evitar. En publish-entity, que se adjunte o no una firma sigue la política del registry de destino, salvo que sign diga otra cosa, y un registry que exige firmas rechaza una publicación sin firmar envíes lo que envíes: no hay ningún argumento que eluda ese rechazo. Consulta aggrega sign para los dos modos de firma y lo que contacta cada uno.
Cada resultado lleva los hechos en lugar de una transcripción: dónde ha quedado el artefacto, su tag, el digest publicado —o, para la ejecución de prueba de una entidad del catálogo, el digest que produciría una publicación—, si el tag ya apuntaba a un contenido idéntico byte a byte, si una publicación se ha firmado, y su reach. Un lote de firma informa de cada referencia firmada con el digest con el que se compromete su firma, en el orden en que se dieron las referencias, y un lote en el que ha fallado alguna referencia vuelve como un fallo que nombra cada una en lugar de como un resultado con una lista recortada: un lote parcial notificado como éxito es la forma en que un rechazo acaba leyéndose como un aprobado. Una deprecación informa de cada marcador con su propio digest, ya que un marcador se adjunta como referrer sin tag del artefacto que retira y nada más lo direcciona. Firmar o retirar una referencia que nada ha publicado se rechaza en lugar de adjuntarse a nada.
Las dos partes de una respuesta
Cada herramienta responde con un texto legible y, junto a él, con un resultado estructurado siempre que la operación tenga uno. El texto está escrito para una persona que lee la conversación. El resultado estructurado lleva la misma respuesta como campos que lee un programa —un veredicto, una lista de archivos, un diagnóstico—, y un rechazo también lleva uno cuando la operación tenía hallazgos en la mano al rechazar, como describe Qué devuelve una build rechazada para una build.
El resultado estructurado también lleva el texto, como text_answer. El resultado estructurado de cada herramienta tiene un campo text_answer que contiene el texto de la respuesta exactamente como lo lleva el texto: cada frase, en orden, sin cambios. Así, un cliente que pasa a su modelo el resultado estructurado en lugar del texto, como hace Claude Desktop, le pasa igualmente cada frase del texto: la línea con la que se abre la respuesta de describe-capabilities sin argumentos, la configuración vigente que informa config-show, la frase que nombra la carpeta que usó una respuesta cuando no se encontró ningún workspace. text_answer se escribe primero, antes de los campos con los que responde la herramienta, y es el texto que recibe quien llama: sobre HTTP nombra cada ubicación del host del servidor como lo hace el texto, como explica Qué dice una respuesta sobre el sistema de archivos del servidor. El propio texto sigue siendo la prosa que es, para los clientes que lo leen, de modo que las mismas palabras viajan dos veces en cada respuesta.
Ninguna herramienta es una excepción, lint incluida. Ninguna herramienta responde con un campo propio llamado text_answer, así que el campo nunca ocupa el lugar de uno. El resultado estructurado de lint conserva su summary —el número de entidades comprobadas y de hallazgos, en total y por gravedad, con los nombres que escribe aggrega lint con -o json— y lleva text_answer junto a él. describe-capabilities también conserva sus propios campos: version_summary, la línea de versión sola, cuando no recibe argumentos, y en cada entrada de su index un summary, el propósito de esa herramienta en una línea.
Ninguna herramienta anuncia un esquema de salida. La descripción de una herramienta lleva un esquema para los argumentos que recibe y ninguno para su resultado, por lo que text_answer se nombra aquí en lugar de en un esquema.
Una respuesta sin resultado estructurado es solo su texto. El rechazo de los argumentos de una llamada, y cualquier otro fallo para el que la operación no tenía nada estructurado que informar, vuelve como su texto y nada más, y el texto es entonces la única parte que un cliente puede mostrar a su modelo.
Cuando una llamada no tiene éxito
Dónde llega la respuesta depende de una sola cosa: si quien llama puede corregirlo cambiando los argumentos de una herramienta que existe.
Todo lo que se puede corregir de esa manera vuelve como el propio resultado de la herramienta, marcado como fallo y con la corrección como texto: una combinación de selectores que la herramienta no acepta, un argumento obligatorio omitido, un argumento enviado con el tipo JSON equivocado, una ruta que no se resuelve, un diagnóstico del compilador. Ese es el canal que se muestra a un asistente, que así lee qué ha fallado y vuelve a llamar con el argumento corregido.
El canal de errores del protocolo se reserva para lo que no tiene un resultado de herramienta en el que estar: un nombre de herramienta que el servidor no sirve, una solicitud cuyos parámetros no puede leer, un método que no implementa y un mensaje que no es JSON válido en absoluto. Leer un recurso y renderizar un prompt también responden ahí, porque ninguno de esos resultados lleva un indicador de fallo propio.
El esquema anunciado de una herramienta también declara la mayoría de las reglas que deben cumplir sus argumentos —qué selectores se excluyen mutuamente, qué argumento solo tiene sentido junto con otro y cuáles son obligatorios—, de modo que un cliente que compone llamadas según el esquema declarado rara vez tiene que hacer la llamada para conocerlas. Una regla que el esquema no indica se rechaza igualmente, con una frase que la nombra; la regla de pull de que verify no se combina con upgrade_targets ni con pin_sources se deja al rechazo a propósito, por la razón que se da en Resolver de qué depende una Release.
Qué detiene el servidor
Por la entrada y la salida estándar, cerrar la conexión lo detiene. El servidor lee un mensaje por línea y termina limpiamente cuando su entrada estándar llega al final del flujo, de modo que un cliente que cierra la conexión apaga el servidor. Es el caso habitual en ese transporte, porque nunca lanzas el comando tú mismo: el cliente que lo inició es lo que lo termina, así que salir del editor, o desactivar este servidor para un proyecto, es como suele verse detenerlo.
Pedir al propio proceso que se detenga llega al servidor en cualquiera de los dos transportes. Una interrupción desde un terminal, o una solicitud de terminación de un supervisor o de un runtime de contenedores, lo apaga a la primera solicitud, tanto si un cliente está enviando algo como si no: deja de aceptar mensajes, termina el trabajo que está haciendo una llamada en curso y sale limpiamente. Una segunda solicitud termina el proceso de inmediato. Por tanto, por la entrada y la salida estándar una llamada que sigue en ejecución cuando se pide al proceso que se detenga no termina; un listener, en cambio, se vacía y deja que una llamada que ya se está respondiendo termine dentro de un plazo acotado antes de que el proceso salga.
Un cliente también puede detener una sola llamada sin detener el servidor, y cómo lo hace depende del transporte. Las llamadas se responden de forma concurrente, así que la terminación de una se atiende mientras esa llamada sigue en ejecución en lugar de esperar detrás de ella. Por la entrada y la salida estándar un cliente indica el id de la llamada; cancelar una llamada que ya se ha respondido, o una en la que el servidor no está trabajando, no hace nada, y eso es lo que hace seguro enviar un mensaje así sin saber antes si la respuesta ya va de camino. Sobre HTTP no hay ningún mensaje que enviar: cerrar la conexión que llevó la llamada la termina. En ambos casos se indica a la llamada que se detenga —su trabajo termina en el siguiente punto en que la operación lo comprueba, y una operación que nunca lo comprueba llega hasta el final—, no se envía nada más para esa llamada, cualquier otra llamada en curso continúa y el servidor sigue sirviendo.
Cuándo usarlo
Usa aggrega mcp cuando quieras que un asistente de IA te ayude a escribir entidades de Aggrega con los esquemas y la referencia reales, para que sus sugerencias se basen en la estructura exacta que acepta el compilador en lugar de ser conjeturas. Encaja directamente en el ciclo de autoría: el asistente lee el esquema y la referencia de un tipo, genera un esqueleto, rellena los campos que corresponden a tu rol y valida antes de devolver el borrador. Consulta Escribir archivos de Aggrega para ese ciclo.
Por la entrada y la salida estándar normalmente nunca escribes aggrega mcp tú mismo. En su lugar, lo nombras una vez en la configuración MCP de tu cliente, y el cliente lo inicia y lo detiene por ti. Un listener es el otro caso: ahí eres tú quien ejecuta el proceso, y sigue ejecutándose para quienes llaman sin haberlo iniciado.
Ejemplo: configuración del cliente por la entrada y la salida estándar
Apunta un cliente MCP al comando con una entrada de servidor stdio:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}El único requisito previo es el binario aggrega instalado en el PATH del cliente. Para las rutas de configuración de cada cliente y la solución de problemas, consulta Conectar el servidor MCP. Para obtener un esquema directamente desde la línea de comandos sin un cliente, consulta aggrega get-schema.