Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

aggrega mcp

Executar um servidor Model Context Protocol sobre a entrada e a saída padrão, ou sobre HTTP, para integração com assistentes de IA

Sinopse

aggrega mcp [flags]

Descrição

Run Aggrega as a Model Context Protocol (MCP) server, so an AI
assistant can discover and drive Aggrega operations through a structured
protocol instead of scraping command output.
Two transports reach the same server, and --transport chooses between
them, with mcp.transport in the workspace configuration as the key it
overrides. The default, stdio, speaks newline-delimited JSON-RPC 2.0 over
the process's standard input and output, which is how an MCP-capable
client runs it: spawned as a subprocess, not typed by hand. http serves
the protocol over HTTP instead — one long-running process on a host,
reached by callers who are not at its keyboard — on the address --listen
names, or mcp.listen when the flag is absent.
An address chooses no transport. --listen given with the stdio transport
is 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 input
and output, which says so in one line on stderr, so a client can launch
this command in a directory whose configuration is written for a
listener. And the http transport with no address from either is refused
before anything binds.
It speaks two MCP protocol revisions on both transports, 2026-07-28 and
2025-06-18, so a client of either connects. In 2026-07-28 nothing is
settled for the connection as a whole: every request states the protocol
version it speaks and the capabilities its sender offers, and the server
reads both from the request it is answering rather than holding anything
between 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 same
things about it either way. A client on 2026-07-28 calls server/discover
for the revisions the server speaks, the capabilities it advertises —
tools, resources, and prompts — and the guidance it offers a model
before the first call. A client on 2025-06-18 receives those same
capabilities, and that same guidance, in the reply to its handshake.
From there the client discovers the server's surface through the list
methods (tools, resources, resource templates, and prompts) and invokes
it through tools/call and resources/read. The server exposes Aggrega
operations — compiling and inspecting a Release, reading catalog
entities — as tools and resources an assistant can call directly.
On standard input and output, stream discipline is strict: stdout carries
only protocol messages, one JSON object per line, so the client can parse
the stream without heuristics. Every log, warning, and diagnostic is
written to stderr instead. The server reads one message per line and
exits cleanly when stdin reaches end of stream, so a client that closes
the connection shuts the server down. A client ends one call by naming
its id, and every other call carries on.
Over HTTP there is one endpoint, /mcp, accepting POST. Every message is
its own request and no session of any kind is kept, so nothing a client
sends first decides how a later request is answered. Closing the
connection ends the call it carried. A request carrying an Origin header
is checked against mcp.allowed_origins, and mcp.limits bounds how large
one request body may be, how many requests are answered at once, and how
many one caller may send in a minute. A caller sending faster than
mcp.limits.requests_per_minute is answered 429, counted against that
caller alone.
Every request to /mcp carries a credential, and which one depends on
whether a proxy in front has already checked it. By default it is a
bearer token the server verifies itself, against the keys
mcp.authorization.issuer publishes: it must come from that issuer, name
mcp.authorization.resource among its audiences, be inside its validity
window, and be signed with an asymmetric algorithm. A request carrying no
token is answered 401 with a challenge, and so is one whose token fails
any of those. A token is never accepted from the address, never forwarded
anywhere, never exchanged, and never written to any log; the subject it
names is recorded and compared to nothing.
Set mcp.authorization.trusted_proxy instead and the caller is read from a
header the proxy sets rather than from a token, with its scopes from a
second header; no token is read at all in that mode, and a request
without the principal header is answered 401. Because that header is then
the whole credential, it is trustworthy only where nothing else can set
it: the process is refused before it binds unless mcp.listen is loopback
or a Unix socket.
The challenge names where to obtain a token. A listener publishes an
OAuth protected-resource metadata document, with no credential asked for,
naming the authorization server, this deployment's own address and the
scopes that exist; it is served at /.well-known/oauth-protected-resource
and at that path followed by the endpoint path, which are the two places
a client looks. A client reads it before it can hold a token, which is
why it is the one answer given without one. What that document publishes
comes from mcp.authorization.issuer and mcp.authorization.resource, and a
listener is refused before it binds unless both are set.
The issuer is an https address unless the authorization server runs on
this machine (localhost, 127.0.0.1 or ::1), and that holds in every
mode: with the keys read from the issuer, with a key file, and with a
proxy 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's
authorization code and token across the network unprotected, and a
listener naming one is refused before it binds.
The verification keys are read from the issuer itself, by asking it where
it publishes them and fetching them from the address it names, and read
again once when a token arrives signed by a key identifier the held set
does not carry. That address is held to the same rule as the issuer, and
so is every redirect either read is answered with: a plain http address
on another host is never asked, and a token needing those keys is
answered 503 until the authorization server publishes its metadata and
keys over https. A workspace that is offline makes no such request, so
there mcp.authorization.jwks_file names a file holding those keys and a
listener 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 is
running 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. The
address opens before the workspace is resolved, so a supervisor sees the
process alive while it is still deciding whether it can serve at all.
Leave the key unset and no second listener exists. The endpoint itself
answers both paths the same not-found it gives every path it does not
serve, with a token and without one, so reaching this process over the
network is never a way to probe it.
The workspace this process serves is fixed when it starts, on either
transport: --workspace-root names it, and AGGREGA_WORKSPACE_ROOT supplies
it when the flag is absent. The folder named is the workspace root
itself, as it is for every command: a call naming no workspace of its
own is answered there, and nothing above it is searched for a workspace,
so name the folder that holds the workspace's .aggrega-config.yaml. A
named folder that does not exist is refused, naming the flag or the
variable that supplied it and the value as it was given: a listener is
refused before it binds, while a server on standard input and output
writes the refusal to stderr and starts all the same, answering every
call that acts in that workspace with it, so a client that shows
nothing of stderr still shows the refusal. An empty
AGGREGA_WORKSPACE_ROOT is read as unset, but for one launch: a server
on standard input and output given no --workspace-root, whose
environment carries the AGGREGA_BUNDLE_VERSION the desktop bundle sets,
was started with the desktop application's Workspace folder setting
empty. It is served the same way, the refusal naming that setting, so
no call naming no workspace of its own is answered in the directory it
was started in. In every other case where neither names a root, a
server on standard input and output resolves the workspace from the
directory it was started in, while a listener is refused before it
binds unless a workspace resolves there: one reached
over HTTP serves a workspace an operator chose rather than
whichever directory it happened to be started in. Where that directory
anchors no workspace, a call naming no workspace of its own that names
its Release or document by an absolute path is answered in the workspace
that file's folder resolves, as the same command typed at a terminal in
that directory would be.
For the same reason a call arriving over HTTP cannot name a workspace of
its own. Sending workspace_root or catalog_dirs is refused, naming the
argument, and the directories searched for catalog entities beside the
served workspace are the ones that workspace itself resolves: its own
workspace.catalog_dirs setting — or, for a Release it gives directories
of its own under workspace.releases, that Release's — then its catalog
directory. Over
standard input and output both arguments are honoured: the client that
launched 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 as
given. A relative one is read from the root a call naming no workspace
of its own is answered in — the folder --workspace-root or
AGGREGA_WORKSPACE_ROOT names, which the desktop application sets from
its Workspace folder, or, where neither names one, the workspace root
the directory the server was started in resolves to — so a client that
cannot see where that folder sits on the machine still names a folder
inside it, as quickstart-ai/1. Where there is no such root to read it
from, a relative one is refused as a call naming none is refused, and
an absolute one is answered as it always is.
Asking the process itself to stop — an interrupt from the terminal, or a
termination request from a supervisor or container runtime — shuts the
server down on the first request, whether or not a client is sending
anything: it stops accepting messages, ends the work a call in progress
is doing, and exits cleanly. A listener stops accepting and lets a call
already being answered finish, within a bounded budget, before the
process exits. A second request ends the process at once.

Flags

FlagPadrãoDescrição
--listen—O endereço em que o transporte HTTP escuta, em uma de duas formas: host:port, ou unix: seguido de um caminho do sistema de arquivos. Ele indica onde escutar e não escolhe nenhum transporte: é lido com —transport http, ou com mcp.transport: http na configuração do workspace, e, se fornecido com o transporte stdio, é recusado. Um listener sem certificado serve em texto puro e só é permitido em loopback (127.0.0.1, ::1, localhost) ou em um socket Unix, que é a forma que um servidor atrás de um proxy de terminação assume; qualquer outro endereço precisa de mcp.tls.cert_file e mcp.tls.key_file, que este processo então usa para terminar o TLS por conta própria. Quando definido, substitui a chave de configuração mcp.listen.
--transport—Como o servidor é alcançado: stdio fala o protocolo pela entrada e saída padrão, que é como um cliente que inicia este comando como subprocesso o alcança; http o serve por HTTP no endereço que —listen ou mcp.listen indica, e por HTTPS onde mcp.tls indica um certificado e uma chave. Quando definido, substitui a chave de configuração mcp.transport, cujo padrão é stdio.

O que ele faz

aggrega mcp executa um servidor Model Context Protocol. Dois transportes o alcançam, e --transport escolhe entre eles: stdio ou http, com mcp.transport na configuração do workspace como a chave que o flag substitui, e stdio como padrão.

Sobre stdio, o padrão, ele se comunica pela entrada e saída padrão do processo. Nessa forma, ele não é um comando que você executa interativamente — um cliente compatível com MCP o inicia como subprocesso e fala o protocolo por stdio; Conectar o servidor MCP lista onde cada cliente guarda a entrada que o inicia. Executá-lo transforma a CLI em um assistente de autoria que conhece o Aggrega dentro do seu editor ou cliente de chat.

Sobre http, ele serve o protocolo por HTTP: um único processo de longa duração em um host, alcançado por chamadores que não estão diante do seu teclado, escutando no endereço que --listen indica, ou mcp.listen quando o flag está ausente. Consulte Alcançando o servidor por HTTPS para saber como esse listener é configurado e o que ele aceita.

Ele fala duas revisões do protocolo, 2026-07-28 e 2025-06-18, então um cliente de qualquer uma delas se conecta e alcança as mesmas superfícies. Qual delas uma chamada fala é declarado naquela chamada em vez de combinado uma vez para a conexão. Um cliente em 2026-07-28 envia com cada solicitação a versão do protocolo que fala e suas próprias capacidades, e pergunta a server/discover o que o servidor suporta; um cliente em 2025-06-18 define essas mesmas coisas uma única vez, abrindo a conexão com um handshake initialize. De qualquer forma, o servidor não guarda nada entre mensagens, então o que você envia primeiro não decide nada sobre como uma chamada posterior é respondida. Uma solicitação que nomeia uma revisão que o servidor não fala é recusada e informada de quais duas pode pedir, em vez de ser respondida como se tivesse pedido uma delas.

O servidor expõe três superfícies ao assistente conectado:

  • Prompts — duas famílias, e a diferença está no que cada uma responde. Os prompts de autoria respondem a “o que estou escrevendo”: uma persona por papel (desenvolvimento, arquitetura, operações), mais um template focado por entidade. Cada um enquadra o papel e direciona o assistente para o schema, a página de referência e o guia de autoria certos, de modo que suas sugestões fiquem dentro dos pilares pelos quais esse papel é responsável. Os prompts de workflow respondem a “quais chamadas, em que ordem”: cada um apresenta a sequência ordenada de chamadas de ferramentas que atinge um objetivo que abrange várias operações, com os pontos de decisão entre elas — compor do zero um novo Aggregate e sua Release, trazer para o Aggrega um chart, um módulo de infraestrutura ou um arquivo container-compose existente, descobrir por que um build não compila ou renderiza os artefatos errados. prompts/list enumera as duas famílias e prompts/get renderiza um, então o conjunto é lido do servidor e não desta página.

    Um prompt de workflow nomeia as chamadas e você as faz, uma de cada vez, lendo cada resultado antes do próximo. Não existe uma chamada que realize um objetivo inteiro: cada ferramenta encapsula uma operação que você pode verificar, então é a sequência que leva você até lá. As personas de autoria aceitam um kind opcional no qual se concentrar, o template por entidade exige um, e um kind ao qual nenhum schema corresponde é recusado com a lista dos valores aceitos em vez de ser ignorado silenciosamente.

  • Recursos — material de referência somente leitura servido inline: schema://<kind> para o JSON Schema de uma entidade, langref://<path> para qualquer página da referência da linguagem, authoring://<topic> para o guia de autoria, catalog://<kind>/<name> para o YAML escrito de uma entidade do catálogo, e cli://<command> para a ajuda própria de um comando, com cli:// sozinho como ponto de entrada — essa ajuda é respondida a partir dos comandos que o próprio servidor traz, então ler uma não inicia nenhum processo e retorna o mesmo texto que o comando imprime para --help. Uma leitura catalog:// de uma entidade que o catálogo não contém é respondida como não encontrada; quando isso acontece porque exatamente um arquivo de catálogo que declara a entidade foi ignorado no carregamento, a mensagem da resposta nomeia esse arquivo, a restrição que ele viola e o código curto da condição, em vez de apenas o URI — a recusa com que aggrega build começa para o mesmo arquivo. resources/list enumera os que são endereçáveis sem parâmetro e resources/templates/list anuncia o formato de URI de cada família.

  • Ferramentas — ações sobre o seu workspace, e tools/list responde com todas elas.

    As ferramentas que um assistente encontra primeiro são pensadas para o ciclo de autoria: list-entities e list-releases para descobrir o que o workspace contém, scaffold para um esqueleto com os campos que seu tipo exige, com um placeholder onde quer que um valor seja devido — ou, ao receber example, para escrever um dos exemplos executáveis da documentação em um diretório novo, respondendo com onde fica esse diretório, os arquivos escritos e os comandos para construí-lo, e, ao receber list: true, para listar os exemplos — get-schema para o JSON Schema de uma entidade, validate para validar um rascunho (ele nomeia cada placeholder que o rascunho ainda tem, e o que cada um aceita), describe para descrever uma entidade do catálogo — ou uma entidade lida do seu registry por referência — pull para resolver as dependências de uma Release no cache local e escrever seu lockfile, build para construir uma Release em seus artefatos renderizados — em memória por padrão, sem nenhum artefato escrito em disco, ou escritos em dist/ na raiz do workspace, onde aggrega build os escreve, quando você envia write (e as dependências só são resolvidas antes se você enviar auto_pull), gen-catalog para gerar entidades Plugin a partir de guests Wasm, e explain-error para expandir um diagnóstico do compilador em orientações práticas — incluindo, onde o diagnóstico começa com o código curto de uma condição de parada, essa condição e o passo a passo publicado da correção de autoria, a mesma expansão que aggrega explain dá para o mesmo código em um terminal.

    O restante da superfície está na mesma resposta e não por trás dela: outras ferramentas que são executadas dentro do servidor — lint, a ferramenta que nomeia a conexão escrita em um ponto de um documento, as duas ferramentas de candidatura, as ferramentas de contêiner de anexos e de ponto de inserção, a ferramenta que aplica uma edição delimitada a um documento, pin, que registra os pins de conteúdo das entradas de uma entidade como Fixando as entradas próprias de uma entidade expõe, e as quatro ferramentas de publicação descritas abaixo, além de inventários dos caches e dos registries configurados — e, para um cliente que iniciou este servidor pela sua entrada e saída padrão, uma ferramenta para cada comando que você poderia digitar de outra forma, nomeada segundo seu caminho de invocação. Essas ferramentas de comando existem apenas nesse transporte: um servidor alcançado por HTTP não oferece nenhuma delas, pelo motivo dado em Alcançando o servidor por HTTPS. Nada é retido para uma chamada posterior. Quanto de uma lista de ferramentas colocar diante de um modelo é uma decisão que cabe ao cliente — ele busca as definições e escolhe o que carregar — e uma definição que um cliente nunca recebeu é uma operação que um modelo nunca pode chamar, por mais alcançável que seja o nome dessa ferramenta no wire. Onde a lista inteira é maior do que o seu cliente aceita, Restringindo o que o servidor anuncia é a forma de encurtá-la. describe-capabilities restringe essa superfície ao tipo de entidade que você está escrevendo. Ao receber um kind, ele responde com as ferramentas que servem esse tipo, obtidas dos tipos que cada ferramenta declara e não das palavras de uma descrição; sem argumentos, ele responde com esse mesmo índice sobre cada ferramenta que este servidor oferece a você — o nome de cada uma, um propósito em uma linha, os tipos que serve e se escreve, sem schemas de argumentos, de modo que a superfície inteira chega em uma única resposta legível. Para uma ferramenta cli-, se ela escreve depende de se o comando que ela executa escreve: cli-build é indicada como de escrita, porque o comando salva os artefatos renderizados sob a raiz do workspace, assim como cli-scaffold, porque, ao receber example, o comando escreve um dos exemplos executáveis da documentação em um diretório novo, enquanto um comando que apenas lê é indicado como somente leitura, mesmo onde, no caminho, preenche um cache que todos os projetos da máquina compartilham, como a ferramenta que executa a mesma operação dentro do servidor; ao receber tools nomeando uma ou mais, ele responde exatamente com as definições completas e os schemas de argumentos dessas ferramentas. As ferramentas cli- nunca são restringidas por tipo, porque nada registra qual tipo de entidade um comando serve, então uma resposta restrita a um tipo as deixa de fora e o índice sem argumentos é onde você as lê. Os argumentos de uma ferramenta de comando são nomeados segundo os flags próprios do comando, então --output-dir é enviado como output_dir, e um nome não reconhecido é recusado com a lista das grafias aceitas em vez de ser descartado silenciosamente.

    Algumas capacidades estão presentes duas vezes na entrada e saída padrão: uma ferramenta pensada para o ciclo de autoria executa a operação dentro do servidor, e a ferramenta nomeada segundo o comando que oferece a mesma capacidade executa esse comando. As duas não se comportam da mesma forma, então nesse transporte cada uma nomeia a outra e indica a diferença; por HTTP, as ferramentas de comando estão ausentes, e a frase de pareamento é omitida em vez de apontar para uma ferramenta que o chamador não consegue alcançar. A que é executada dentro do servidor é a preferível — ela responde com um resultado legível por máquina ao lado do texto legível, de modo que um assistente recebe um veredito, uma lista de arquivos ou um diagnóstico como campos em vez de como uma transcrição a ser analisada. A ferramenta de comando inicia o comando real em um processo separado, então faz tudo o que esse comando faz na máquina em que é executado, incluindo escrever em disco onde o comando escreve — cli-build escreve os artefatos renderizados em dist/ na raiz do workspace, e os arquivos de um build rastreado em .trace/ ao lado, e a linha final que ela retorna nomeia esse diretório por completo — e retorna apenas a linha de comando que executou e o texto que esse comando imprimiu. Use-a quando você precisar de um flag que o comando declara e que a outra ferramenta não aceita.

    Essa linha de comando começa com os flags globais com que este servidor foi iniciado e que decidem a configuração — --config e --offline, onde você os forneceu — antes do comando e dos flags próprios da chamada. Assim, o comando lê a configuração que toda outra ferramenta aqui lê: um servidor iniciado com --offline executa seus comandos offline, e um iniciado com --config os executa sobre esse arquivo global. Um flag que a chamada envia para si mesma vem depois deles e prevalece, então offline: false em uma chamada acessa a rede apenas para essa chamada, e a linha de comando retornada mostra ambos. Onde o servidor foi iniciado com uma raiz de workspace — por --workspace-root ou por AGGREGA_WORKSPACE_ROOT — a linha de comando começa com essa raiz como --workspace-root, antes daqueles dois, de modo que o comando toma esse diretório como raiz do workspace, como faria se digitado com o mesmo flag e como toda ferramenta executada dentro do servidor o toma, em vez de encontrar seu workspace a partir do diretório em que o servidor foi iniciado. Uma chamada que envia workspace_root nomeia a sua, e a linha de comando leva apenas essa — incluindo um valor vazio, que o comando lê como --workspace-root "" é lido em um terminal: encontrar o workspace a partir do diretório em que o servidor foi iniciado. Um servidor iniciado sem nenhum dos dois não passa nenhuma raiz, então seus comandos encontram seu workspace a partir desse diretório, pela regra que Em qual workspace uma chamada é respondida estabelece para toda ferramenta — exceto na inicialização do bundle desktop com a configuração Workspace folder vazia, na qual uma chamada que não nomeia um workspace próprio não inicia nenhum comando e é respondida com a recusa dessa configuração. O comando é iniciado na raiz do workspace que a chamada ou a inicialização nomeia: o workspace_root próprio da chamada, lido como toda ferramenta o lê — um absoluto tal como foi enviado, um relativo a partir da raiz em que é respondida uma chamada que não nomeia nenhum — e passado ao comando em sua forma absoluta, ou então a raiz com que o servidor foi iniciado. Assim, um caminho relativo que uma chamada passa como arquivo a ser lido — um documento para validate, um --release ou um --catalog — é lido dentro desse workspace, como em um terminal aberto ali, e um build que o comando executa escreve dist/ sob essa raiz. Onde nada nomeia uma raiz — nenhuma raiz de inicialização, e nenhum workspace_root ou um vazio — o comando é iniciado no diretório em que o servidor foi iniciado e lê um caminho relativo a partir dali; um workspace_root que não nomeia nenhuma pasta existente é repassado tal como foi lido — um absoluto tal como foi enviado, um relativo em sua forma completa — e o comando o recusa com suas próprias palavras. Um comando que um plugin de extensão de comandos registra não recebe nenhum deles, porque repassa cada argumento ao plugin sem lê-lo em vez de analisar um flag global, em um terminal como aqui; ele é iniciado na mesma pasta que qualquer outro comando.

    Alguns comandos estão deliberadamente ausentes mesmo na entrada e saída padrão, onde as ferramentas de comando existem — por HTTP, todos eles estão ausentes, e isso é uma propriedade do transporte e não de algum comando. Na entrada e saída padrão, cada um destes fica de fora por um motivo declarado: o daemon e este próprio servidor nunca retornariam um resultado; um comando que lê uma senha do terminal não tem de onde lê-la; um que escreve um script de autocompletar do shell não tem nenhum shell onde instalá-lo; remover uma credencial armazenada age sobre o armazenamento da máquina inteira em vez de sobre um workspace que você nomeou; e obter um token de identidade interativamente não tem nenhuma forma não interativa a oferecer. Ausente por esse mesmo motivo de máquina inteira está aggrega plugin run-local, que carrega um guest .wasm a partir de um caminho que você fornece: aquilo para que serve o comando é ler um arquivo onde quer que você o coloque, então não existe nenhum workspace ao qual ele possa ser confinado, e a leitura acontece no próprio processo antes que o guest exista. Nada é concedido ao guest quando ele é executado — nenhum diretório, nenhum socket, nenhum ambiente — mas isso é um limite sobre o módulo e não sobre a leitura, então não é o que decide a questão. Execute-o no seu terminal, onde é você quem nomeia o caminho. Assinar e publicar são um caso totalmente diferente, e é essa diferença que os mantém fora dessa lista. Cada um resolve uma identidade a partir de uma entrada fornecida ou do ambiente e recusa explicitamente quando nenhuma está disponível, então cada um tem uma forma que se completa sem ninguém observando — ao passo que obter um token interativamente é um verbo que nenhuma entrada pode satisfazer, nem mesmo em princípio. Então eles estão presentes duas vezes: como os comandos, e como as quatro ferramentas internas ao processo descritas em Publicando, assinando e retirando. Onde a linha de comando abriria um navegador, eles recusam e nomeiam o que fornecer em vez disso, em vez de esperar por uma pessoa que não está lá.

Em qual workspace uma chamada é respondida

Uma chamada nomeia seu workspace com workspace_root; caso contrário, ela é respondida no workspace sobre o qual o servidor foi iniciado. Onde a inicialização nomeou uma raiz, com --workspace-root ou AGGREGA_WORKSPACE_ROOT, essa raiz é a própria raiz do workspace, como o flag é em todo comando: nada acima dela é procurado em busca de um workspace que a contenha, então uma inicialização nomeia a pasta que contém o .aggrega-config.yaml do workspace, e uma chamada é respondida ali tanto pelas ferramentas executadas dentro do servidor quanto pelas ferramentas de comando. Onde a inicialização não nomeou nenhuma, o workspace é encontrado a partir do diretório em que o servidor foi iniciado, exatamente como um comando digitado em um terminal ali o descobre — a ordem é exposta em As outras formas como a raiz de um projeto é reconhecida — exceto na inicialização do bundle desktop com a configuração Workspace folder vazia, que em vez disso recusa uma chamada assim, como exposto abaixo. Um workspace_root relativo é lido a partir da raiz em que é respondida uma chamada que não nomeia nenhum — a raiz que a inicialização nomeou ou, onde ela não nomeou nenhuma, a raiz do workspace à qual o diretório em que o servidor foi iniciado é resolvido — de modo que uma chamada nomeia uma pasta dentro do workspace, como quickstart-ai/1, sem saber onde o workspace fica na máquina; um absoluto é usado tal como é fornecido. Toda ferramenta o lê assim, incluindo as ferramentas de comando. Onde não há nenhuma raiz a partir da qual ler um relativo — uma raiz de inicialização que não é uma pasta existente, ou a inicialização desktop com Workspace folder vazio — um relativo é recusado como é uma chamada que não nomeia nenhum. Um workspace_root que não nomeia nenhuma pasta existente, ou que nomeia um arquivo, é recusado antes que a ferramenta faça qualquer outra coisa, nomeando o argumento e citando o valor — um absoluto tal como foi enviado, um relativo na forma completa em que foi lido — como um comando recusa --workspace-root.

Uma raiz de inicialização que não é uma pasta existente é servida como uma recusa na entrada e saída padrão. Onde --workspace-root ou AGGREGA_WORKSPACE_ROOT nomeia uma pasta que não existe, ou nomeia um arquivo, o servidor escreve a recusa no seu fluxo de erro e é iniciado mesmo assim, de modo que um cliente que não mostra ao seu usuário nada desse fluxo ainda mostra o porquê. Ele responde a initialize e às suas listas de ferramentas, recursos e prompts, e toda chamada que agiria nesse workspace é respondida com a recusa: uma chamada de ferramenta como resultado com falha, uma leitura de uma entidade catalog:// ou de uma página da documentação como erro. A recusa nomeia o flag, ou a variável junto com a configuração Workspace folder do aplicativo desktop que a define — a configuração que Claude Desktop descreve — e cita o valor exatamente como foi fornecido; um valor que o cliente enviou sem preenchê-lo é citado tal como chegou, e nada nele é interpretado. Uma ferramenta que executa um comando não inicia nenhum para uma chamada que não nomeia um workspace próprio, já que a pasta em que esse comando seria iniciado não existe, e responde com a mesma recusa. Uma chamada que nomeia um workspace próprio por um caminho absoluto é respondida ali; uma que o nomeia por um caminho relativo não tem nenhuma pasta a partir da qual lê-lo, e é respondida com a mesma recusa. O que não age em nenhum workspace — um schema, um prompt, a ajuda de um comando — é respondido como em qualquer servidor. Um listener, em vez disso, é recusado na inicialização, antes que qualquer coisa faça bind, com a mesma recusa, de modo que quem o supervisiona lê a falha onde a procura.

Uma inicialização desktop com a configuração Workspace folder vazia é servida como uma recusa da mesma forma. O bundle desktop sempre passa ao servidor AGGREGA_WORKSPACE_ROOT, com o que quer que Workspace folder contenha, e define AGGREGA_BUNDLE_VERSION ao lado dela, enquanto o aplicativo inicia o servidor em uma pasta de sua escolha — muitas vezes uma pasta do sistema — em vez de no seu projeto. Assim, um servidor na entrada e saída padrão iniciado sem --workspace-root, cujo ambiente traz AGGREGA_BUNDLE_VERSION e um AGGREGA_WORKSPACE_ROOT vazio ou ausente, não procura um workspace a partir da pasta em que foi iniciado. Ele escreve a recusa no seu fluxo de erro e é iniciado mesmo assim, respondendo como faz com uma raiz de inicialização que não existe: toda chamada que agiria em um workspace e não nomeia um próprio é respondida com uma recusa que diz que o aplicativo desktop iniciou o servidor com a configuração Workspace folder vazia, de modo que AGGREGA_WORKSPACE_ROOT não nomeia nenhuma raiz de workspace, que pede que você defina Workspace folder como a pasta que contém o .aggrega-config.yaml do seu workspace, e que diz que uma pasta definida depois que o servidor foi iniciado passa a valer quando a extensão é desativada e ativada novamente ou o aplicativo é reiniciado, porque o aplicativo passa a configuração ao servidor somente quando o inicia. Uma ferramenta que executa um comando não inicia nenhum para uma chamada assim. Uma chamada que nomeia um workspace próprio por um caminho absoluto é respondida ali, e uma que o nomeia por um caminho relativo é respondida com a mesma recusa, já que não há nenhum Workspace folder a partir do qual lê-lo; o que não age em nenhum workspace é respondido como em qualquer servidor. O servidor reconhece a inicialização apenas por AGGREGA_BUNDLE_VERSION: em um bundle que não define essa variável, uma configuração vazia é lida como nenhuma raiz, e uma inicialização que define a variável manualmente e não nomeia nenhuma raiz é recusada como a do bundle. Todo outro valor vazio continua não nomeando nenhuma raiz — um AGGREGA_WORKSPACE_ROOT vazio em uma inicialização que não traz nenhum AGGREGA_BUNDLE_VERSION, um --workspace-root digitado vazio, um listener, aggrega serve e todo outro comando o leem, cada um, como não definido.

Onde nenhum workspace foi encontrado e nenhum foi nomeado, uma resposta sobre o workspace diz qual pasta usou. Sem raiz de inicialização, sem workspace_root na chamada e sem nada que ancore um workspace a partir da pasta em que a chamada foi respondida, a chamada é respondida nessa pasta. Quando o resultado da ferramenta depende do workspace — as mesmas ferramentas cujos comandos emitem um aviso na linha de comando —, seu texto termina com o aviso da linha de comando, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, e uma linha que pede que você envie workspace_root nomeando a pasta que contém o .aggrega-config.yaml do seu workspace; uma resposta que o workspace não determina, como a leitura da configuração ou a listagem de plugins, não diz nada sobre workspaces. A frase não adiciona nenhum campo próprio ao resultado estruturado; o resultado estruturado a traz em text_answer, que contém o texto, como As duas partes de uma resposta expõe. Uma ferramenta que executa um comando em um processo separado traz a própria linha do comando dizendo o mesmo, tal como o comando a imprimiu. Nada é escrito em um cache de artefatos em uma pasta assim: um pull, ou um build ao qual se pede que resolva primeiro suas dependências, é recusado ali antes que qualquer coisa seja buscada, nomeando a pasta e as duas alternativas — enviar workspace_root, ou dar à pasta um .aggrega-config.yaml com um bloco workspace:. Um pin, ou uma publicação de uma Recipe ou FeatureRecipe, é recusado da mesma forma onde buscaria uma fonte remota que a entidade escreve por completo — para fixá-la, ou para comparar seu pin — antes que essa fonte seja buscada; onde não busca nenhuma, porque a entidade não tem fonte, tem uma local ou uma cujas coordenadas cada Release preenche, é respondido como em qualquer outro lugar. Um build ali que não resolve nada antes ainda renderiza, mas uma entrada externa que seu lockfile fixa e que o cache não contém mais não é buscada novamente: o render recebe essa mesma frase no lugar da entrada, como recebe a de um modo offline. Nenhuma resposta por HTTP traz a frase: um listener sempre serve um workspace que lhe foi dado ou que ele encontrou. Tampouco a traz a inicialização do bundle desktop com uma configuração Workspace folder vazia, que recusa uma chamada que não nomeia um workspace próprio em vez de respondê-la na pasta em que foi iniciado.

Uma chamada sobre uma Release ou um documento que ela nomeia por um caminho absoluto é respondida no workspace próprio desse arquivo quando nada mais definiu um. Onde a inicialização não nomeou nenhuma raiz, a chamada não envia nenhum workspace_root e o diretório em que o servidor foi iniciado não ancora nenhum workspace, o workspace é descoberto novamente a partir da pasta em que esse arquivo está, e o que quer que isso encontre — o projeto ao qual o arquivo pertence ou, na falta de tudo, essa pasta — é aquele em que a chamada é respondida. Essa é a regra que um comando digitado em um terminal segue, então ela vale para toda ferramenta cuja chamada é sobre uma Release ou um documento de entidade que ela nomeia: um build, um pull, uma validação, um lint, uma descrição, uma listagem nos termos de uma Release, uma pergunta sobre um nó do grafo de uma Release, um pin, a publicação de uma entidade, uma edição e uma posição lida em um documento. Onde uma chamada nomeia tanto uma Release quanto um documento, a Release decide. Assim, para um cliente que iniciou o servidor fora do seu projeto, uma Release desse projeto ainda é construída a partir da configuração própria do projeto. Os outros caminhos que a chamada nomeia são lidos como sempre — um relativo, a partir do diretório em que o servidor foi iniciado — e uma ferramenta que executa um comando em um processo separado é respondida a partir do mesmo workspace, porque o comando segue a mesma regra nesse mesmo diretório. Uma raiz que a inicialização nomeou, um workspace_root que a chamada envia, um diretório inicial que está ele próprio dentro de um workspace, e uma Release ou um documento nomeado por um caminho relativo são usados como estão. Por HTTP nada disso ocorre: um listener sempre serve um workspace que lhe foi dado ou que ele encontrou, e todo caminho que uma chamada nomeia é relativo a ele. Tampouco ocorre na inicialização do bundle desktop com uma configuração Workspace folder vazia, que recusa uma chamada que não nomeia um workspace próprio, qualquer que seja o arquivo que ela nomeie.

Restringir o que o servidor anuncia

mcp.announce_tools nomeia as ferramentas que este servidor anuncia, escritas exatamente como a lista de ferramentas as informa. Omita a chave e toda ferramenta que este servidor traz é anunciada, que é o padrão e o formato que um cliente que segue o protocolo espera. Escreva uma lista e exatamente essas ferramentas são anunciadas: uma que fique de fora está ausente da lista de ferramentas, ausente do que describe-capabilities responde e é recusada se for chamada pelo nome mesmo assim, com a recusa nomeando esta configuração. Escreva uma lista vazia e nada é anunciado — portanto omitir a chave e escrever [] são afirmações diferentes, e a configuração não tem nenhum padrão preenchido por você.

Defina-a onde o cliente do outro lado limita quantas ferramentas vai registrar, às vezes somando todos os servidores aos quais está conectado ao mesmo tempo, e nomeie as ferramentas de que esse cliente precisa. Esse limite é o caso para o qual a configuração existe, e o cliente ao qual ela se aplica costuma ser o que iniciou este servidor pela própria entrada e saída padrão — portanto, diferentemente do restante do bloco mcp, que configura o listener que o transporte http inicia, esta chave é lida qualquer que seja o transporte que o servidor fala.

Ela restringe o que é anunciado e nada mais. Nomear uma ferramenta aqui não amplia nada. Ela não suspende mcp.deny_reach, que retira uma capacidade por completo, então uma ferramenta nomeada aqui de um tipo que essa configuração retira fica fora da lista e é recusada nomeando essa configuração. Também não suspende os scopes que o token de um chamador carrega: uma ferramenta nomeada aqui é listada quaisquer que sejam esses scopes, e uma chamada que eles não admitem ainda é recusada, nomeando o scope que a admitiria. Em ambos os casos, a recusa que o chamador encontra é a desse outro limite, e não a deste. Uma recusa desta configuração não traz nenhum challenge e não nomeia nenhum scope, porque nenhuma credencial muda o que um servidor escolheu oferecer — o que ela nomeia em vez disso é a configuração, que é a única coisa sobre a qual quem lê a recusa pode agir.

Todo nome tem que ser um que este binário traz. Um nome ao qual nenhuma ferramenta responde interrompe o servidor antes que ele sirva qualquer coisa, e a recusa lista as ferramentas que ele tem — assim um erro de digitação é detectado na inicialização em vez de por uma superfície silenciosamente mais estreita do que a que você pediu. Um nome da família cli-, que executa um comando aggrega em um processo separado, é aceito nos dois transportes e não anuncia nada por HTTP, onde nenhuma ferramenta desse tipo é oferecida a nenhum chamador, para começar.

O conjunto anunciado é fixado quando o processo inicia, então alterá-lo exige uma reinicialização, e nada faz a lista crescer sob um cliente que já se conectou.

De qual versão o servidor vem

describe-capabilities enviado sem argumentos diz de qual versão este servidor vem. Sua resposta estruturada traz server_version, a versão que o executável aggrega informa sobre si mesmo — a que aggrega version imprime para o mesmo arquivo — e seu texto começa com uma linha que a nomeia, antes do índice. A resposta estruturada traz essa mesma linha como version_summary, palavra por palavra, de modo que um cliente que entrega a um modelo apenas a resposta estruturada também lhe entrega a linha.

Onde o pacote de desktop iniciou o servidor, a mesma resposta nomeia ao lado a versão do pacote. O pacote não traz nenhum programa: ele inicia o executável aggrega que sua configuração Path to the aggrega executable nomeia — por padrão, o nome de comando aggrega, que o aplicativo procura no seu PATH —, então o pacote e o executável são instalados separadamente e podem vir de versões diferentes, e o aplicativo que lista o pacote mostra apenas a versão do próprio pacote. O pacote entrega ao servidor sua versão como AGGREGA_BUNDLE_VERSION no ambiente dele; o servidor a lê uma vez, quando inicia, e a resposta a traz como bundle_version. As duas são comparadas exatamente como estão escritas, o que é uma comparação justa porque o pacote e o executável de uma mesma versão recebem a marca dessa versão na mesma forma, enquanto uma build de desenvolvimento é lida de forma diferente de qualquer versão publicada. Quando são iguais, a linha nomeia ambas e não diz mais nada. Quando diferem, a linha diz, nomeando ambas, que o executável e o pacote vêm de versões diferentes, e a orientação que o servidor oferece a um modelo quando ele se conecta começa com essa mesma frase, de modo que a diferença está diante do modelo antes que ele pergunte.

Um servidor que nenhum pacote iniciou informa apenas a própria versão. Iniciado de um terminal, da configuração de um editor ou como listener, ele não traz bundle_version, a menos que algo defina a variável em seu ambiente. Um servidor por entrada e saída padrão que traz a variável é tomado como iniciado pelo pacote em mais um aspecto: sem nenhuma raiz nomeada, ele recusa a configuração Workspace folder vazia, como Em qual workspace uma chamada é respondida expõe. Uma chamada a describe-capabilities enviada com kind ou tools não traz server_version, bundle_version nem version_summary, nem essa linha, porque responde sobre ferramentas e não sobre o servidor.

Uma diferença é informada e nunca recusada. O servidor inicia e responde a cada chamada exatamente como faria com as duas alinhadas. O que uma diferença significa para uma instalação de desktop, e como alinhar as duas, está em Conectar o servidor MCP.

Acessar o servidor por HTTPS

aggrega mcp --transport http serve o protocolo por HTTP em vez de pela entrada e saída padrão. mcp.transport na configuração do workspace é a chave que esse flag substitui, e seu padrão, stdio, é o que um cliente que inicia o comando espera — portanto um servidor que outras pessoas acessam traz transport: http em sua configuração, e um cliente iniciado a partir de um diretório que essa configuração abrange ainda acessa o servidor pelos próprios fluxos. É o mesmo servidor nos dois casos — o mesmo workspace e as mesmas superfícies de protocolo — e o que muda é como uma mensagem chega a ele, como uma chamada termina e o que quem o executa precisa ter. Esta seção descreve o que um operador configura; a entrada de que um cliente precisa para acessar um servidor em execução está em Conectar o servidor MCP.

Um endereço não escolhe nenhum transporte. --listen <address>, ou mcp.listen quando o flag está ausente, nomeia onde o listener faz o bind depois que http é escolhido, e nada mais. Assim, http sem endereço de nenhum dos dois é recusado antes de qualquer bind, e a recusa nomeia ambos. --listen digitado enquanto o transporte é stdio — digitado como --transport stdio, configurado como mcp.transport: stdio ou deixado no padrão — também é recusado, nomeando --transport http como o flag que serviria nesse endereço; um --listen com valor vazio é recusado por não nomear nenhum endereço, qualquer que seja o transporte. E um endereço que apenas a configuração nomeia fica sem uso por um servidor que fala pelos próprios fluxos, que informa isso em uma linha em seu fluxo de erro, nomeando o arquivo que o definiu e mcp.transport: http. Esse último caso não é recusado em lugar nenhum, de propósito: é a inicialização que um cliente faz quando inicia o comando em um diretório cuja configuração traz as configurações de um listener, e uma configuração de listener que esquece transport: http não inicia listener nenhum, que é onde isso se percebe.

Um servidor acessado por HTTP não oferece nenhuma ferramenta que execute um comando aggrega em um processo separado. Essas ferramentas existem apenas para um cliente que iniciou este servidor pela entrada e saída padrão, na própria máquina desse cliente, onde nomear uma pasta ou um flag não concede ao chamador nada que ele já não tivesse. Um chamador que acessa o servidor por HTTP não é dono do host em que ele é executado, então um comando que agiria sobre o sistema de arquivos desse host com a autoridade do próprio servidor é executado em vez disso em um terminal no host. As ferramentas estão ausentes da lista e de describe-capabilities em vez de serem oferecidas e recusadas, e uma chamada que nomeia uma delas recebe um erro dizendo isso. Essa é uma propriedade do transporte, não uma configuração: não há configuração que as traga de volta.

Leia Nada é servido sem uma credencial antes de implantar um. Toda solicitação ao endpoint traz uma credencial, e não há configuração que sirva uma solicitação sem ela — o que uma configuração escolhe é se este servidor verifica ele mesmo um bearer token ou lê um chamador que um proxy à frente já verificou.

Os dois formatos de implantação

O próprio processo termina o TLS. Defina mcp.tls.cert_file como uma cadeia de certificados PEM e mcp.tls.key_file como sua chave privada, e o listener serve HTTPS diretamente em qualquer endereço que você lhe tenha dado. Os dois arquivos são lidos quando o processo inicia, então um certificado substituído passa a valer ao reiniciar o processo. Definir um sem o outro é recusado na inicialização em vez de recorrer a outra coisa: um certificado sem chave não pode ser apresentado, uma chave sem certificado não nomeia nada, e um erro de digitação em um caminho não é motivo para começar a servir tráfego não criptografado.

Um proxy à frente termina o TLS e encaminha para um listener confinado. Deixe as duas chaves sem definir e o listener serve em texto simples, o que só é aceito em loopback ou em um socket Unix — assim nada que já não esteja nesse host consegue acessá-lo. Esse é o formato que um proxy reverso, um sidecar ou uma service mesh usa, e é aquele em que o certificado fica à frente deste processo, e não nele.

Um listener em texto simples em qualquer outro endereço é recusado antes de qualquer bind, e a recusa nomeia as duas chaves TLS. Não há configuração que suspenda isso nem endereço que seja exceção: um listener que aceita conexões da rede sem um certificado próprio nunca é seguro, então o processo se recusa a iniciar em vez de iniciar nesse formato.

Os formatos de endereço

--listen e mcp.listen aceitam um de dois formatos:

  • host:port — um endereço TCP, como 127.0.0.1:7777 ou 0.0.0.0:8443. Loopback significa 127.0.0.1, ::1, ou localhost quando todo endereço para o qual esse nome é resolvido é um endereço de loopback. Qualquer outra coisa é um endereço de rede e precisa de um certificado: um host vazio, que é toda interface que a máquina tem; o endereço de uma interface específica; e qualquer outro nome, mesmo um que neste momento seja resolvido para um endereço de loopback, porque onde um listener pode fazer o bind não deveria depender de uma resolução que pode mudar sob ele.
  • unix: seguido de um caminho do sistema de arquivos — um socket de domínio Unix, como unix:/run/aggrega/mcp.sock. Um socket só pode ser acessado a partir do host em que está, então não precisa de certificado.

Um caminho de socket é tomado exatamente como está escrito, inclusive um relativo. Ele deliberadamente não é resolvido em relação ao arquivo de configuração que o declarou, porque o mesmo endereço também chega por --listen, que não tem arquivo declarante — veja para onde aponta um caminho relativo.

O que o listener aceita

Um único endpoint, /mcp, que aceita POST. Cada mensagem JSON-RPC é uma solicitação própria e nenhuma sessão de nenhum tipo é mantida: nada que um cliente envie primeiro decide como uma solicitação posterior é respondida, nenhum identificador de sessão é gerado, e um cabeçalho de sessão ou de retomada de stream que um cliente envie é ignorado. Qualquer outro método nesse endpoint recebe 405 com Allow: POST, e qualquer outro caminho 404 — ambos decididos antes da verificação da credencial, de modo que uma sondagem não aprende nada com um challenge em um caminho ou método que não serviria nada de qualquer forma.

Uma solicitação é respondida com um objeto JSON e um código de status — ou, quando a chamada informou progresso a caminho desse objeto, com um stream de eventos que termina nele, como Ser informado de como está uma chamada longa expõe. Uma notificação — uma mensagem sem id — recebe 202 com corpo vazio. Uma mensagem que não é nenhuma das duas, incluindo uma resposta JSON-RPC, recebe 400, porque um cliente envia a este servidor solicitações e notificações e nada mais.

As duas revisões do protocolo são servidas aqui exatamente como pela entrada e saída padrão. Uma solicitação 2026-07-28 espelha seu corpo em cabeçalhos de transporte para que um intermediário possa roteá-la sem analisar o corpo: MCP-Protocol-Version traz a revisão que o corpo declara, Mcp-Method o método que ele nomeia e Mcp-Name o alvo, para os métodos que endereçam um pelo nome. Um cabeçalho que discorda do corpo recebe 400. Um cliente 2025-06-18 começa com um handshake initialize, que é respondido sem estado; ele pode trazer o cabeçalho de versão nomeando essa revisão ou omiti-lo. Uma solicitação que nomeia uma revisão que o servidor não fala recebe 400 listando as duas que ele fala, e uma que nomeia um método que ele não serve recebe 404.

mcp.allowed_origins só é consultado quando uma solicitação traz um cabeçalho Origin, o que na prática significa que um navegador a enviou: uma solicitação que nomeia uma origem que a lista não contém recebe 403, e uma sem esse cabeçalho é servida. Um cliente que não é um navegador não envia esse cabeçalho e não precisa de entrada. Um baseado em navegador sempre precisa de uma entrada: a lista fica vazia até que um operador a escreva, então até lá nenhuma origem está presente e toda solicitação de navegador recebe 403 — inclusive uma de uma página servida no próprio endereço do endpoint. A entrada é comparada exatamente com o cabeçalho, então é escrita como um navegador envia uma origem — um esquema em minúsculas, ://, um host em minúsculas e, quando não for a padrão do esquema, : e a porta, como https://app.example.com — e uma entrada com um caminho, uma / final, sem esquema ou com uma letra maiúscula é recusada quando a configuração é carregada, nomeando a entrada, porque ela nunca poderia corresponder.

mcp.limits limita o tráfego aceito. Um corpo acima de max_body_bytes recebe 413 e não é lido além do limite. Uma solicitação que chega enquanto max_concurrent_requests já estão em andamento recebe 503 em vez de ficar na fila atrás de um trabalho que ela não pode ver. Um chamador que envia mais de requests_per_minute em um minuto recebe 429, contabilizado apenas para esse chamador, de modo que um chamador que envia muito não custa nada a outro. O padrão de cada limite está indicado ao lado de sua chave na referência de configuração, e nenhum deles tem um valor que o desative.

Um processo, um workspace

O workspace pelo qual um processo em serviço responde é fixado quando ele inicia. --workspace-root o nomeia; a variável AGGREGA_WORKSPACE_ROOT o fornece quando o flag está ausente. A pasta nomeada é a própria raiz do workspace, sem busca acima dela, e uma pasta que não existe é recusada, nomeando qual dos dois a forneceu e citando o valor como foi dado — por um listener antes do bind, e por um servidor por entrada e saída padrão na resposta a cada chamada que atua nesse workspace, como Em qual workspace uma chamada é respondida expõe — de modo que uma inicialização composta por um cliente em vez de digitada ainda diz o que recebeu. Sem nenhum dos dois, um servidor por entrada e saída padrão resolve o workspace a partir do diretório em que foi iniciado — onde nada ancora ali um workspace, cada resposta sobre o workspace diz qual pasta usou, e a inicialização do pacote de desktop com a configuração Workspace folder vazia recusa em vez disso uma chamada que não nomeia um workspace próprio, como Em qual workspace uma chamada é respondida expõe — e um listener é recusado antes do bind a menos que um workspace seja resolvido ali — um processo acessado por HTTP responde a chamadores que não podem ver a máquina, então serve um workspace que um operador escolheu, e não o diretório em que por acaso foi iniciado. Para servir vários projetos, execute um processo por raiz de projeto.

Uma chamada que chega por HTTP não pode nomear um workspace próprio. workspace_root e catalog_dirs são recusados, nomeando o argumento enviado, em vez de serem descartados silenciosamente: um argumento ignorado em silêncio parece ao remetente exatamente igual a um respeitado. Os diretórios de catálogo pesquisados ao lado do workspace servido são os da própria configuração workspace.catalog_dirs desse workspace — ou, para uma Release à qual ele dá diretórios próprios em workspace.releases, os dessa Release — que o operador escreve. Pela entrada e saída padrão, os dois argumentos são respeitados, porque o cliente que iniciou o servidor está sendo executado na própria máquina do chamador. Ali uma entrada de catalog_dirs é absoluta, ou relativa à raiz do workspace a partir da qual uma release relativa é lida — a raiz que o próprio workspace_root da chamada, a inicialização ou o diretório em que o servidor foi iniciado estabeleceu primeiro, e aquela a partir da qual a leitura continua quando uma Release nomeada de forma absoluta move a chamada para o próprio workspace dessa Release — e não ao diretório em que o servidor é executado, quando este está em outro lugar.

Um caminho que uma chamada nomeia também permanece dentro desse workspace. Por HTTP, um argumento de caminho é resolvido em relação à raiz do workspace e recusado se sair dela — um caminho relativo que sobe para fora do workspace, um caminho absoluto que nomeia outro lugar e um caminho relativo que sai do workspace por um link para um arquivo ou diretório que está lá voltam, cada um, como uma falha que nomeia o argumento, sem nomear nem a raiz do workspace nem o lugar que o caminho teria alcançado; um caminho relativo é devolvido como você o enviou. Cada argumento de caminho é julgado por onde ele leva, pela definição de “dentro” que O limite do workspace estabelece, quer a ferramenta o leia, quer o escreva — o diretório em que gen-catalog grava sua saída, o documento que edit-document regrava e a entidade ao lado da qual pin grava seu lock tanto quanto um documento que uma ferramenta lê — de modo que um caminho ainda não criado sob um link que sai do workspace é recusado como esse link, sem que nada seja lido ou gravado. Uma release que nomeia uma Release que a configuração do workspace servido nomeia, como build.authoring_release ou como chave de workspace.releases, é alcançada por essa configuração e aceita através de um link onde quer que seu arquivo esteja; nenhum outro argumento tem essa exceção. Quando o caminho que você pretendia está dentro desse workspace mas foi escrito de forma absoluta, a recusa lhe dá a forma relativa à raiz para enviar em vez dela, de modo que um chamador que adivinhou a forma errada fica sabendo da certa, e não só de que estava errada. Isso vale para os caminhos que uma chamada nomeia como seu objeto — o documento a validar, a Release a compilar, o diretório em que uma geração grava sua saída — e para aqueles em que uma ferramenta grava não menos do que para os que ela lê: um chamador que acessa um servidor pela rede está pedindo a uma máquina que não pode ver que leia e grave arquivos, e o workspace que o operador escolheu é onde essa leitura e gravação ficam contidas. Pela entrada e saída padrão, os argumentos de caminho de cada ferramenta mantêm o contrato descrito abaixo para essa ferramenta, em que um caminho pode ser absoluto e pode apontar para fora do workspace — a pessoa que chama é dona da máquina em que o servidor é executado, então confiná-la a um diretório que ela mesma escolheu não traria nada. As duas ferramentas cuja própria operação responde apenas sobre um documento que o workspace contém, insertion-point e edit-document, mantêm isso nos dois transportes, e recusam um documento fora do workspace, seja ele escrito assim ou alcançado por um link que sai dele. O que é respeitado pela entrada e saída padrão é o caminho que uma chamada nomeia e nada além dele. O que a operação então lê e grava por conta própria é contido nos dois transportes exatamente como quando o mesmo comando é digitado em um terminal: uma varredura ou uma consulta não lê através de um link que sai do workspace, um arquivo que uma Release no workspace ou seu Manifest nomeia por um caminho não é lido de fora do workspace — e um que uma Release nomeada pela chamada fora do workspace nomeia não é lido de fora do diretório que contém essa Release — e um arquivo gravado sob um diretório — o workspace, ou um que a chamada nomeou — permanece dentro desse diretório. O limite do workspace coloca os dois transportes ao lado da linha de comando e do editor, e expõe o que permanece aberto pela entrada e saída padrão: um documento em um workspace que você clonou pode levar um assistente a nomear um caminho fora do workspace, e esse caminho é respeitado como nomeado.

O que uma resposta diz sobre o sistema de arquivos do servidor

Por HTTP, uma resposta nomeia um lugar no sistema de arquivos do servidor em relação à raiz do workspace, ou o retém. Um cliente que iniciou o servidor é executado onde o servidor é executado, então pela entrada e saída padrão cada resposta nomeia cada lugar como a operação o mantém — de forma absoluta, quando é assim que ela o mantém — e cada um é um lugar que esse chamador já possui. Um chamador que acessa um listener não escolheu nenhum desses lugares e não pode abri-los, e um servidor que os revelou a ele não pode retirá-los. Assim, por HTTP, uma resposta diz a esse chamador uma de duas coisas sobre um lugar:

  • Um lugar dentro do workspace é nomeado em relação à raiz do workspace — a mesma forma que um caminho que você envia assume, de modo que um nome lido de uma resposta pode ser enviado de volta sem alteração na próxima chamada. Uma Release na raiz é release.yaml, e seu lockfile é release.lock.
  • Um lugar fora do workspace é retido, assim como a própria raiz do workspace. O campo não traz valor — é null ou omitido, e em attachment-container, cuja resposta mantém o formato em que toda superfície a informa, file fica vazio — e uma marca ao lado, com o nome do campo seguido de _withheld, diz que ele foi retido, e não deixado sem definir: workspace_root_withheld ao lado de workspace_root, file_withheld ao lado de file. Uma marca só está presente onde algo foi retido. A raiz é retida porque um listener serve exatamente um workspace, então onde esse workspace fica não nomeia nada de que você precise para nomear o que está dentro dele.

Se um lugar está dentro é julgado pela forma como está escrito, não pelo arquivo que alcança. Um caminho escrito pelo destino de um link simbólico em vez de pela raiz sobre a qual o servidor foi iniciado, e um caminho que sai da raiz e volta para ela, são cada um considerados fora do workspace e são retidos. O julgamento erra para o lado de lhe dizer menos, nunca para o lado de nomear um lugar fora do workspace.

Por HTTP, o texto legível de uma resposta segue a mesma regra. Onde o texto, uma linha de diagnóstico ou a mensagem de uma falha nomeia um lugar que o workspace contém — sua raiz ou qualquer coisa abaixo dela, um arquivo de configuração do qual sua configuração foi lida, um diretório do qual seu catálogo é lido — esse lugar é escrito em relação à raiz, ou aparece como (location withheld) quando está fora do workspace ou é a raiz. O texto que uma resposta compõe sobre o próprio workspace o chama de workspace que este servidor serve. Um lugar fora de todos esses que uma operação escreve em uma mensagem não é reconhecido como tal, e chega a você como foi escrito.

As respostas que isso alcança, por HTTP:

  • list-entities, list-releases, cache-status, registry-list, search, attach-candidates, connection-candidates, insertion-point, attachment-container, connection-at-position e edit-document retêm workspace_root. Os caminhos que eles já dão em relação à raiz — o arquivo de origem de uma entidade, o caminho de uma Release e seu lockfile em lockfiles, o documento de que trata um ponto de inserção ou uma edição, os arquivos que uma edição gravou — são lidos da mesma forma nos dois transportes.
  • cache-status também retém o que nomeia um plugin que o servidor carregou de um arquivo em seu host. Uma identidade assim é null em seu lugar em provenance[].identities, toda outra identidade mantém sua posição, e a entrada é marcada com identities_withheld. A note de um módulo compilado é uma frase que nomeia as identidades para as quais o módulo foi compilado, então, quando alguma delas nomeia um arquivo assim, a note é omitida por inteiro e marcada com note_withheld; o digest do módulo continua presente. Uma identidade que nomeia uma referência de registry ou uma entidade Plugin é respondida por inteiro, assim como uma note que nomeia apenas essas. O label de um artefato de origem é seu lugar no cache, formado a partir do host e do caminho da URL da qual foi resolvido, então, para um repositório lido do próprio sistema de arquivos do servidor — por uma URL file:// ou um caminho — o label é omitido e marcado com label_withheld, seu size e seu digest continuam presentes, e um label que nomeia um host de rede é respondido por inteiro. O texto da listagem mostra (location withheld) onde teria nomeado um.
  • validate nomeia target, e release para uma Release, em relação à raiz; para o catálogo inteiro, target é a raiz e é retido. Um lugar em diagnostics ou notices segue a regra do texto.
  • build nomeia release em relação à raiz, e uma build que resolveu primeiro suas dependências traz dependency_resolution como pull o responde. Uma build enviada com write nomeia o diretório em que gravou como output_dir, que é dist — relativo à raiz — e cada caminho em files é relativo a esse diretório. Um refusal, e cada entrada de seus findings, nomeia seu file em relação à raiz, ou o retém quando o documento está fora do workspace. advisories, deprecations, declined_external_inputs e cada message do refusal seguem a regra do texto.
  • pull nomeia release e lockfile em relação à raiz. diagnostics e incomplete_external_inputs seguem a regra do texto. O source de cada entrada de resolved é respondido por inteiro nos dois transportes: ele nomeia o que a execução fez, nunca um lugar no host.
  • describe nomeia a release de uma Release em relação à raiz, e o file de uma entidade em relação à raiz quando seu documento está dentro do workspace; uma entidade lida de um diretório de catálogo fora do workspace tem seu file retido. mapping_diagnostics e deprecations seguem a regra do texto.
  • lint nomeia o location.file de cada achado em relação à raiz, ou o retém quando a entidade está fora do workspace. A message e o suggest de um achado seguem a regra do texto.
  • pin nomeia entity e lock em relação à raiz, e o mesmo faz o pin que uma publicação traz.
  • gen-catalog nomeia cada arquivo listado em output em relação à raiz.
  • import retém workspace_root, e output_dir quando os rascunhos foram para essa raiz; um diretório que você nomeou em output_dir é informado pelo nome relativo à raiz. Todo caminho de rascunho em written e drafts é relativo a output_dir, então para onde os rascunhos foram está na resposta de qualquer forma. A message de um diagnóstico, e os params_summary, rationale e swap_hint de uma decisão, são prosa que o importador compôs e seguem a regra do texto.
  • config-show e plugin-list retêm mais do que a raiz, porque a maior parte do que informam é configuração que nomeia lugares, como O que um listener não lhe diz sobre seu host expõe.
  • scaffold, ao gravar um exemplo, nomeia dir como você o enviou, em relação à raiz, e cada caminho em files em relação a esse diretório; a criação de rascunhos e a listagem não nomeiam nenhum lugar.
  • As ferramentas de publicação, sign-artifacts, deprecate-artifact, get-schema, explain-error e describe-capabilities não nomeiam por si nenhum lugar no host. A mensagem de falha de qualquer uma delas segue a regra do texto: a recusa que um workspace offline gera nomeia seu .aggrega-config.yaml em relação à raiz.
  • Um argumento de caminho recusado por sair do workspace é recusado sem nomear a raiz nem o lugar que teria alcançado, como acima.

Como uma chamada termina

Fechar a conexão cancela a chamada que ela transportava. Esse é o sinal de cancelamento deste transporte: o servidor trata a desconexão de um chamador como cancelamento daquela solicitação, encerra o trabalho que estava fazendo e não grava mais nada para ela. Nenhuma mensagem de cancelamento é necessária ou esperada aqui — o oposto da entrada e saída padrão, onde não há stream por solicitação para fechar e um cliente encerra uma chamada nomeando seu id. Uma mensagem de cancelamento que chega mesmo assim por HTTP é aceita e não encerra nada.

Parar o processo drena o listener. Uma interrupção, ou uma solicitação de término de um supervisor ou de um runtime de contêineres, faz o listener parar de aceitar e deixa terminar uma chamada que já está sendo respondida, dentro de um prazo limitado, de modo que um chamador que pediu algo antes da parada ainda recebe sua resposta. Uma chamada que não terminou dentro desse prazo perde a conexão. Uma segunda solicitação de parada encerra o processo imediatamente.

Liveness e readiness, em um endereço próprio

mcp.health.listen é onde um supervisor pergunta se este processo está ativo e se pode responder a uma chamada. Dê a ele um endereço em qualquer um dos formatos acima e um segundo listener responde ali a GET /healthz e GET /readyz. Omita-o — que é o padrão — e nenhum segundo listener é iniciado e nenhuma das duas verificações é respondida em lugar nenhum.

As duas respostas dizem coisas diferentes, e essa diferença é o motivo de haver duas. /healthz recebe 200 a partir do momento em que o processo está em execução, que é tudo o que a liveness afirma: ele está ativo, e um supervisor que não recebe nenhuma resposta deveria reiniciá-lo. /readyz recebe 503 até que o workspace que este processo serve tenha sido resolvido e o endpoint tenha feito o bind, e 200 a partir daí — assim um balanceador segura o tráfego até que o processo possa de fato responder a uma chamada, em vez de enviar a primeira solicitação a um que ainda está iniciando. Toda resposta é um código de status com corpo vazio; nenhuma credencial é pedida, e nada do que o chamador enviou é lido.

O endpoint nunca responde a esses dois caminhos. GET /healthz e GET /readyz no endereço que mcp.listen nomeia recebem 404, exatamente como qualquer outro caminho que esse endpoint não serve, com token ou sem. Responder ali a uma sonda daria a qualquer coisa que alcance o endpoint uma leitura gratuita de se o processo está ativo, junto com uma forma gratuita de fazê-lo trabalhar — em um listener que, de resto, recusa toda solicitação que não traz credencial.

Onde fica o endereço de health é escolha sua, e ele não é confinado como mcp.listen é. Nenhum endereço é recusado para ele. Aponte-o para loopback ou para um socket Unix, que é para o que ele serve: um supervisor, um balanceador ou um runtime de contêineres executando ao lado deste processo no mesmo host. Qualquer coisa que consiga alcançar o endereço que você escolher pode ler essas duas respostas, então um endereço que a rede aberta alcança as publica para a rede aberta.

Nada é servido sem uma credencial

Toda solicitação ao endpoint traz uma credencial, e qual depende de um proxy à frente já a ter verificado. Por padrão, é um bearer token que este servidor verifica ele mesmo, descrito no restante desta seção. Defina mcp.authorization.trusted_proxy e passa a ser um cabeçalho que esse proxy define, descrito em Ler o chamador de um proxy à frente — onde nenhum token é lido. Nenhum dos dois formatos serve uma solicitação que não apresenta nada.

Por padrão, o servidor verifica ele mesmo um bearer token. Ele lê o token do cabeçalho Authorization e só o aceita quando a assinatura é verificada com uma chave que o servidor de autorização publica, o token nomeia mcp.authorization.issuer como emissor, nomeia o próprio mcp.authorization.resource desta implantação entre seus públicos, está dentro de sua janela de validade e diz quem o apresentou. Um token que falha em qualquer uma dessas verificações recebe 401, com error="invalid_token" acrescentado ao mesmo challenge que recebe um chamador que não traz nada — e a resposta é idêntica qualquer que seja a verificação que o rejeitou, de modo que um chamador fica sabendo que precisa de outro token, e não qual parte do que enviou estava errada. Apenas algoritmos de assinatura assimétricos são aceitos: um token não assinado, e um que nomeia um algoritmo simétrico, são recusados antes que qualquer coisa seja lida dele.

Um token pode dizer que tipo de token é, e quatro formas são aceitas. Um JWT pode trazer um cabeçalho typ que nomeia seu próprio tipo. Este servidor aceita at+jwt e application/at+jwt, as duas grafias registradas para um access token; JWT, que diz apenas que o token é um JWT; e um token que não declara tipo nenhum. Qualquer outra coisa recebe 401 exatamente como qualquer outro token recusado. O conjunto é fixo e nenhuma configuração o amplia ou o restringe, porque qual forma aparece ali é decidido pelo servidor de autorização que emitiu o token, e não pela implantação que o recebe. Aceitar JWT significa, sim, que o tipo declarado sozinho já não distingue um access token de um identity token — é a verificação de público que os distingue, e é por isso que essa verificação é a que sustenta tudo: o público de um identity token é o cliente para o qual ele foi emitido, nunca o próprio mcp.authorization.resource desta implantação, então um token emitido para qualquer coisa que não seja esta implantação é recusado, chame-se ele como se chamar.

Quais servidores de autorização isso admite. O Microsoft Entra ID emite access tokens do tipo JWT. O Keycloak emite at+jwt, e JWT quando seu modo de compatibilidade com OpenID Connect está ativado. O Auth0 emite JWT em seu próprio perfil de token e at+jwt em seu perfil RFC 9068. Um token de qualquer um deles passa por esta verificação qualquer que seja a das duas formas que traga. O Okta não é suportado: seus access tokens declaram um tipo próprio que não é nenhuma das quatro formas acima, então este servidor os recusa.

Um token recusado deixa o motivo no próprio fluxo de erro do servidor. Ao chamador é dito apenas que o que ele apresentou não foi aceito; o processo em serviço grava uma linha que nomeia a verificação que rejeitou o token — o público, o emissor, a janela de validade, a assinatura, o identificador de chave, o tipo declarado e cada uma das outras. Essa linha é o que permite que uma implantação que recusa toda solicitação seja diagnosticada por quem a executa, e não apenas por quem a chama. Ela não traz nenhuma parte do token. Uma solicitação que não apresenta credencial nenhuma não grava linha nenhuma, porque receber um challenge é como um cliente descobre, para começar, onde obter um token, então essa é a primeira coisa que todo cliente bem-comportado faz.

Um token pertence ao cabeçalho e a nenhum outro lugar. Um enviado como parâmetro de consulta access_token recebe 400 e nunca é lido, porque um endereço é registrado por todo log de proxy, histórico de navegador e cabeçalho referrer pelos quais a solicitação passa, então um token que chegou assim já foi exposto. O servidor nunca grava um token em um log, nunca envia um a lugar nenhum e nunca obtém nem troca um em nome de um chamador: ele lê o que foi apresentado, decide e não guarda nada disso. O sujeito que o token nomeia é registrado e não é comparado com nada.

As chaves de verificação vêm do servidor de autorização, ou de um arquivo que você nomeia. Com mcp.authorization.jwks_file não definido, o servidor lê os metadados do servidor de autorização em seu endereço well-known, segue o jwks_uri publicado ali e guarda as chaves que encontra; um token assinado com um identificador de chave que essas chaves não contêm provoca uma nova leitura, e não mais de uma dentro de um intervalo curto, de modo que um chamador que envia identificadores de chave inventados não consegue provocar uma solicitação de saída por solicitação. Lê-las do servidor de autorização exige um endereço de chaves https, ou um http simples nesta máquina: um jwks_uri que seja http simples em outro host nunca é consultado, e um redirecionamento que enviaria qualquer uma das leituras para http simples em outro host não é seguido, porque quem estiver em um caminho desprotegido até as chaves poderia responder com chaves próprias. Um token que precisa dessas chaves recebe então 503, exatamente como para chaves que não podem ser lidas, e a linha que o servidor grava para essa solicitação diz que a leitura foi recusada por ser http simples, e não que o servidor de autorização não pôde ser alcançado — a correção cabe ao servidor de autorização, que tem que publicar seus metadados e chaves por https. Com jwks_file definido, as chaves são lidas desse arquivo e o servidor de autorização nunca é contatado — que é o que um workspace que declara offline: true precisa, e um workspace assim é recusado antes que seu listener faça o bind a menos que o arquivo seja nomeado. Quando as chaves não podem ser lidas de forma alguma, as solicitações recebem 503 sem challenge: nada do que um chamador apresentou foi considerado insuficiente, então enviá-lo de novo com outro token não ajudaria.

A única resposta dada sem que nenhuma credencial seja exigida é o documento de metadados do recurso protegido. Um cliente precisa lê-lo antes de poder ter um token, então exigir um ali fecharia a única porta de entrada. Ele é respondido em /.well-known/oauth-protected-resource e — onde o endereço que mcp.authorization.resource indica tem um caminho próprio — também nesse caminho well-known com esse caminho acrescentado ao final. Esses são os dois lugares onde um cliente procura, e a forma com o caminho acrescentado é o endereço que o challenge indica. O documento traz esse endereço como o recurso pelo qual este deployment é chamado, mcp.authorization.issuer como o servidor de autorização do qual obter um token, header como a única forma de apresentar um token, e os três nomes de scope abaixo.

O issuer é um endereço https, a menos que o servidor de autorização seja executado nesta máquina. http simples é aceito para um issuer em localhost, 127.0.0.1 ou ::1, que é a forma de um teste local com um servidor de autorização local; um issuer em http simples em qualquer outro host é recusado antes que o listener faça o bind, e a recusa indica mcp.authorization.issuer e pede um endereço https. Isso vale em todos os modos — com as chaves lidas do issuer, com mcp.authorization.jwks_file e com um proxy na frente — porque todo modo publica o issuer neste documento: um cliente que o segue executa seu fluxo de autorização contra esse endereço, então sobre http simples o código de autorização e o token que ele obtém atravessariam a rede sem proteção, quer este servidor leia alguma vez uma chave de lá, quer não. Onde ele de fato lê suas chaves de lá, quem estiver nesse caminho também poderia responder com chaves próprias, e todo token assinado com elas seria admitido.

Os nomes de scope que este deployment publica são aggrega:read, aggrega:workspace-write e aggrega:registry-write. São os nomes a registrar no servidor de autorização e os nomes que um cliente pede a ele, e o challenge que um chamador recusado recebe indica aggrega:read como o que deve ser obtido primeiro. O que cada um deles admite — e o segundo limite, aquele que este deployment impõe a si mesmo — está descrito abaixo em O que um chamador pode alcançar.

Ler o chamador a partir de um proxy na frente

Onde um proxy na frente já valida tokens, mcp.authorization.trusted_proxy diz a este servidor para ler o chamador a partir dele em vez de verificar um token uma segunda vez. Informe principal_header, o header que esse proxy define para dizer quem é o chamador, e opcionalmente scopes_header, um segundo header que traz os scopes desse chamador separados por espaços. Cada um é um nome de header HTTP como X-Forwarded-User, sem espaço nem dois-pontos; um nome em qualquer outra forma é recusado quando a configuração é carregada, indicando a chave, e o mesmo vale para um principal_header vazio — omita o bloco para deixar este modo desativado. Esses dois headers são os únicos lidos: nenhum header de endereço encaminhado nem qualquer outro header participa. Uma requisição que chega sem o header do principal recebe 401, e nenhum token é lido neste modo — uma requisição com um token que este servidor teria recusado de outra forma é atendida quando seu header do principal está presente, e uma com um token que este servidor teria aceitado é recusada mesmo assim quando esse header está ausente.

Esse modo só é aceito em loopback ou em um socket Unix, e o processo é recusado antes de fazer o bind em qualquer outro lugar. Um header é confiável exatamente quando nada além do proxy pode defini-lo. Em um endereço que a rede alcança, qualquer coisa pode defini-lo — então um listener neste modo em um endereço assim deixaria cada chamador se identificar como quisesse. A recusa indica as duas configurações em conflito, para que você possa suspendê-la mudando o endereço ou removendo o bloco.

O que o proxy afirma é o que este servidor acredita, e esse é o acordo. Neste modo este servidor não verifica nenhuma assinatura e não compara o chamador afirmado com nada, exatamente como não compara com nada o subject de um token. Se o proxy validou o que encaminhou, e se algo pode alcançar esse listener sem passar pelo proxy, cabe ao deployment acertar; o confinamento acima é o que torna possível acertar, não uma garantia de que se acertou.

Definir mcp.authorization.trusted_proxy não remove os outros requisitos. issuer e resource continuam necessários, porque o documento de metadados continua sendo publicado e o challenge continua a indicá-lo — um cliente atrás do proxy ainda precisa saber onde obter o token que o proxy vai verificar. Pelo mesmo motivo o issuer continua sendo um endereço https, a menos que seja executado nesta máquina: esse cliente obtém seu token do issuer, então um issuer em http simples em outro host é recusado antes que o listener faça o bind neste modo exatamente como em qualquer outro, mesmo que este servidor não leia nada dele.

O que um chamador pode alcançar

Dois limites decidem o que um chamador alcança via HTTP, e eles são definidos por pessoas diferentes. A credencial do próprio chamador é o primeiro; o que este servidor oferece em absoluto é o segundo. Ambos são lidos antes que qualquer coisa seja executada, a partir de uma declaração que cada operação faz sobre si mesma, e chegam a um cliente em lugares diferentes: a lista de tools mostra o que este servidor oferece e anuncia, e a resposta que cada chamada recebe mostra o que a credencial admite.

Cada operação declara até onde vão seus próprios efeitos, e há quatro tipos, o mais amplo por último:

  • Não alcança nada — lê uma definição, inspeciona o que uma Release fixa, renderiza artefatos em memória e os devolve. Não deixa nada para trás: nada é gravado, e a resposta é tudo o que produz.
  • Alcança o workspace — grava dentro do workspace que este processo atende: o lockfile de uma Release, o cache de artefatos, entidades geradas, um documento editado.
  • Alcança um registry — publica, assina ou anexa um marcador de retirada a algo já publicado. O que muda é o que todo consumidor desse registry resolve, e nada disso pode ser recolhido de quem já o baixou.
  • Alcança a máquina — muda o que todos os workspaces do host compartilham, entre eles o armazenamento de módulos compilados, o arquivo de configuração comum a todos eles e o armazenamento de credenciais. Um cache que um único projeto mantém em seu próprio diretório de cache não é desse tipo, e cache-status informa qual desses tipos cada cache que ele lista tem.

O tipo é uma propriedade da operação e não do tool que a oferece, e abrange o que a operação deixa para trás — não onde uma superfície coloca a resposta que devolve. Renderizar uma Release produz artefatos como resposta, então não alcança nada; uma linha de comando que depois salva esses artefatos em um diretório que você indicou está entregando essa resposta, não indo mais longe. Lido ao contrário, toda operação que responde com conteúdo assumiria o tipo da superfície que por acaso o salvasse, e o tipo deixaria totalmente de ser uma propriedade da operação. Pelo mesmo motivo, describe lendo uma entidade pela sua referência de registry não alcança nada: contata esse registry para buscar sua resposta e não deixa nada para trás, nem no registry nem nesta máquina, e quais registries ele pode contatar está descrito em Quais credenciais uma chamada gasta. Uma chamada ainda pode ir além do tipo de sua operação, quando a própria chamada pede uma gravação: um build enviado com write salva seus artefatos no workspace que este servidor atende, então essa chamada alcança o workspace, assim como um build que primeiro resolve suas dependências.

Um scope admite um tipo, e cada scope de gravação implica o scope de leitura. aggrega:read admite uma operação que não alcança nada. aggrega:workspace-write admite uma que alcança o workspace, e implica o scope de leitura. aggrega:registry-write admite uma que alcança um registry, e também implica o scope de leitura. Assim, um cliente pede ao seu servidor de autorização o scope de gravação de que precisa e não precisa pedir também o scope de leitura.

Nenhum scope admite o tipo máquina, e nenhuma configuração acrescenta um. As operações desse tipo só são oferecidas pelos tools que executam um comando aggrega em um processo separado, e um servidor alcançado via HTTP não oferece nenhum deles, pelo motivo dado acima em Alcançar o servidor via HTTPS. Execute-as em um terminal no host.

A lista de tools mostra cada tool que este servidor oferece e anuncia, quaisquer que sejam os scopes que a credencial chamadora tenha, e a credencial decide quais deles uma chamada pode executar. describe-capabilities indexa e define esse mesmo conjunto. Uma chamada que a credencial não admite recebe 403 com error="insufficient_scope" no challenge, indicando o único scope que a admitiria, e nada do que a chamada pediu foi executado. Essa recusa é a que o step-up do protocolo responde: um cliente que implementa step-up pede que você entre novamente para o scope que o challenge indica. A lista não muda com a credencial, então um cliente que entrou novamente já tem a correta. Uma credencial que não traz nenhum dos três scopes recebe a mesma lista de tools e não pode chamar nenhum dos tools nela, describe-capabilities incluído.

Um build é o caso que vale conhecer. Por si só ele não muda nada e por isso só precisa de aggrega:read, mas um build que grava precisa de aggrega:workspace-write: um enviado com write salva seus artefatos em dist/ na raiz do workspace, e um que primeiro resolve suas dependências grava o lockfile — quer a chamada tenha pedido isso com auto_pull, quer a própria configuração auto_pull do workspace o tenha feito. O tool é listado para um chamador com scope de leitura como qualquer tool, e os builds que ficam em memória estão de fato disponíveis para ele; o que é recusado, indicando aggrega:workspace-write, é a chamada que grava.

Um cliente que não faz step-up ainda pode receber os scopes de gravação, e isso é resolvido no servidor de autorização. Quem opera o servidor de autorização torna os scopes de gravação scopes padrão para esse cliente — scopes que ele coloca em todo token que emite para esse cliente, quer o cliente os tenha pedido, quer não — de modo que o token que seu primeiro login obtém já os traz. Um cliente que se registra de novo no servidor de autorização a cada vez que se conecta é ali um cliente novo a cada vez, e uma configuração feita em um registro anterior não é mantida; para um cliente assim, a configuração que vale é o conjunto de scopes padrão que o servidor de autorização dá a todo cliente que registra. O custo é que todo login por esse cliente passa a trazer alcance de gravação, quer o trabalho em andamento precise dele, quer não — e onde os padrões são os dados no registro, todo cliente registrado dessa forma também traz esse alcance. Torne padrão apenas o scope de gravação de que esse trabalho precisa: aggrega:workspace-write e aggrega:registry-write admitem tipos diferentes, e nenhum implica o outro.

mcp.deny_reach é onde quem opera este servidor retira dele um tipo, e é uma das duas configurações que encurtam a lista de tools. Liste os tipos — none, workspace, registry, machine — que este servidor não oferece, e todo tool que alcança um deles fica ausente da lista de tools de todo chamador e de describe-capabilities, não importa o que o token desse chamador diga, e é recusado se chamado mesmo assim, com um erro que indica esta configuração. É o limite do próprio servidor e não o do chamador, então nenhuma credencial o suspende e a recusa não traz challenge: um servidor destinado a atender leituras e nada mais lista aqui workspace, registry e machine, e então não pode publicar nem mesmo para um chamador cujo token traz os três scopes. Omita-a, que é o padrão, e este servidor não retira nenhum tipo, então quais tipos uma chamada alcança é decidido pelos próprios scopes do chamador. Indicar machine é aceito e não muda nada, já que nada desse tipo é oferecido aqui de qualquer forma. Um valor que não seja um dos quatro é recusado quando a configuração é carregada, em vez de ser ignorado — um operador que escreve um tipo errado pediu um limite, e ser atendido silenciosamente sem ele é a forma errada de responder a isso.

mcp.announce_tools é a outra configuração que encurta a lista de tools, e as duas não são o mesmo limite. deny_reach retira uma capacidade: uma operação de um tipo indicado ali não é oferecida aqui de forma alguma, para ninguém. announce_tools retira apenas um anúncio: os tools que ele deixa de fora são capacidades que este servidor ainda tem, e o que ele atende é o limite que o próprio cliente impõe a quantos tools vai registrar. Onde ambas estão definidas, a retirada prevalece, então um tool de um tipo retirado continua ausente não importa como announce_tools o indique, e a recusa que um chamador encontra indica a retirada. Nada que encurta a lista lê os scopes do chamador: um scope que falta ao chamador recusa uma chamada e nunca remove um tool da lista. Restringir o que o servidor anuncia descreve o restante.

Quais credenciais uma chamada gasta

A assinatura keyless sobre um listener obtém sua identidade do identity_token que a chamada traz, e de nada mais. Um token enviado na chamada é uma credencial que o chamador tem: ele precisou obtê-lo, está vinculado a ele, e a assinatura que produz é atribuível a ele. Qualquer outro lugar de onde uma identidade pudesse vir pertence a quem iniciou este processo, então neste transporte a resolução recebe um ambiente que não responde nada. AGGREGA_IDENTITY_TOKEN e SIGSTORE_ID_TOKEN no ambiente do servidor não são lidos, e o endpoint OIDC ambiente do GitHub Actions não é alcançado. Eles estão fora de alcance, e não apenas desaconselhados — não há nada para a resolução encontrar. Uma chamada que não envia nenhum identity_token é recusada, e a recusa indica identity_token como o que deve ser enviado e não indica nenhuma variável nem nenhum endpoint: um chamador que não está ao teclado desta máquina não pode exportar nada aqui, então indicar uma seria dizer a ele que providenciasse algo que não pode mudar a resposta.

Uma chave de assinatura mantida nesta máquina não pode ser selecionada, por nenhuma das duas vias. key_path é recusado antes que qualquer coisa seja resolvida, e está ausente dos esquemas de argumentos que publish-entity, sign-artifacts e deprecate-artifact anunciam aqui, de modo que nunca se oferece a um chamador um argumento que não poderia ter sucesso. A chave de assinatura que a própria configuração do workspace atendido indica também não é alcançada — signing.key_path, quer esteja definida para o workspace como um todo, definida para um registry ou fornecida pelo ambiente. Um único motivo cobre ambos: um caminho de chave não é uma credencial, é um nome para um segredo que este servidor mantém. Um chamador que fornece um não prova nada, qualquer pessoa que alcançasse este endereço poderia fornecer o mesmo nome, e a assinatura resultante diria que é o operador quem responde pelo artefato, e não o chamador. Fechar o argumento deixando a configuração aberta seria fechar uma porta para um cômodo que a outra ainda abre. Assim, a assinatura com chave é inalcançável sobre um listener: só um token enviado na chamada assina.

fulcio_url, rekor_url e timestamp_url não são afetados e continuam disponíveis em ambos os transportes. Eles indicam serviços a contatar e não algo que esta máquina mantém, então um chamador que não pode selecionar uma chave ainda assina contra os endpoints que este deployment configura.

Um listener iniciado sobre um workspace que indica uma chave de assinatura avisa uma vez, ao iniciar. O processo grava uma linha em seu próprio fluxo de erro indicando a configuração e dizendo que um chamador que alcança este listener não pode gastar essa chave — assim um operador fica sabendo pelo processo que iniciou, e não por uma assinatura que não esperava. Um workspace que não indica nenhuma chave não produz essa linha, porque não há nada a dizer sobre isso. A linha traz o nome da configuração e nem a chave nem nada sobre o arquivo para o qual ela aponta.

Sobre a entrada e a saída padrão nada disso se aplica. Ali o ambiente é lido e key_path seleciona uma chave mantida nesta máquina, porque o cliente que iniciou este servidor está sendo executado na própria máquina do chamador, e o que esse processo pode alcançar cabe a esse mesmo chamador gastar.

Ler uma entidade pela sua referência de registry contata um único registry, com o próprio login deste host, e sobre um listener apenas um registry com o qual o workspace atendido está configurado. describe enviado com uma referência oci:// como seu name lê a entidade publicada nessa coordenada — a mesma leitura que aggrega inspect realiza — do único registry que a referência indica, usando o login que este host já tem para esse registry. A chamada não traz nenhuma credencial, e describe não aceita nenhuma. Via HTTP o registry precisa ser um com o qual o workspace atendido está configurado: o host que seu default_registry indica, ou um host listado em registries, comparado exatamente e com a porta. Uma referência a qualquer outro host — incluindo um endereço nesta máquina — é recusada antes que esse host seja contatado, e a recusa indica o host, então um chamador não pode apontar este servidor para um destino de sua escolha. O que continua alcançável é deliberado: um chamador que tem aggrega:read pode ler tudo o que o login deste host pode ler em um registry com o qual o workspace está configurado, que é o que uma pessoa no terminal deste host também pode ler. Sobre a entrada e a saída padrão uma referência a qualquer registry é lida, como na linha de comando. Descrever uma entidade pelo seu nome de catálogo não é afetado.

Uma chamada a um registry usa o armazenamento de credenciais do usuário do sistema operacional com o qual este processo é executado, exatamente como a mesma chamada faz em um terminal neste host. Não há fonte de credenciais por workspace nem configuração que acrescente uma, e é por isso que registry-list informa o estado das credenciais de um host da mesma forma em todo workspace desta máquina. Um deployment que quer que workspaces diferentes tenham credenciais de registry diferentes os executa como usuários diferentes do sistema operacional — um processo por workspace, cada um iniciado como seu próprio usuário. É daí que vem a separação, e providenciá-la cabe ao operador.

O que o servidor registra

Toda requisição que este endpoint responde deixa uma linha no fluxo de erro do processo, e essa linha é um único objeto JSON. Ela traz o time em que foi gravada e um request_id que este processo gerou para a chamada e não devolve ao chamador; subject e issuer como a credencial apresentada os afirmou, com client_id onde ela indicava um; workspace_root, o workspace que este processo atende; method, e target onde o método se refere a algo pelo nome; reach, o tipo que a operação declara, e reach_escalated_to onde a chamada foi além disso; outcome; duration_ms; e transport. Um campo sem nada a dizer é omitido em vez de gravado vazio, então um client_id ausente é uma credencial que não indicava nenhum cliente, e um reach_escalated_to ausente é uma chamada que alcançou exatamente o que sua operação declara.

outcome diz o que aconteceu com a chamada, e os valores são distintos para que você possa contá-los separadamente. ok foi executada e teve sucesso. tool-failure foi executada e voltou marcada como uma falha que o chamador pode corrigir — uma chamada que este servidor atendeu, e não uma que recusou, então ela não pertence às suas recusas. error é uma recusa devolvida como envelope de erro do protocolo. unauthenticated, forbidden e rate-capped são a credencial, o limite de origem ou de scope e o limite de taxa por chamador recusando uma requisição. cancelled é um chamador que fechou sua conexão antes de receber resposta.

O motivo pelo qual uma credencial recusada foi rejeitada é um campo dessa mesma linha, e não uma linha própria. Uma requisição recusada deixa um registro como qualquer outra, com refusal indicando a verificação que a rejeitou. Nenhuma credencial, nem parte de uma, chega a nenhuma linha — nem em uma recusa, nem em uma chamada atendida.

Um chamador que não apresentou nada não deixa nenhuma linha. Receber um challenge é a forma como um cliente descobre onde obter um token, então é a primeira coisa que todo cliente bem-comportado faz, e uma linha para cada um desses enterraria as recusas que significam algo. Uma requisição que indica um caminho ou um método que este endpoint não atende também não deixa nenhuma: ambos são resolvidos antes que qualquer coisa sobre um chamador seja lida, então varrer o endereço não grava nada no que coleta o fluxo.

O contexto de trace que um cliente envia é copiado literalmente na linha. traceparent, e ao lado dele tracestate e baggage onde também são enviados, são repassados exatamente como recebidos, de modo que o que coleta este fluxo pode juntá-lo aos próprios registros do chamador. Uma requisição que não envia nenhum, ou envia um que não é um contexto de trace W3C bem formado, produz uma linha sem essas chaves: nada é inventado, e nada é alterado no caminho.

O processo registra sua própria vida no mesmo formato e no mesmo fluxo, e cada uma dessas linhas indica um event onde uma linha de requisição indica um método e um chamador: startup quando começa, listening com o endereço em que fez o bind, startup-refused com o motivo pelo qual uma inicialização foi recusada antes de atender, signing-key-ignored onde o workspace que ele atende indica uma chave de assinatura que nenhum chamador que alcança este listener pode gastar, docs-bundle com o resultado da obtenção do pacote de documentação, e shutdown quando a execução termina. A presença de event é o que distingue os dois tipos de linha.

Você coleta tudo isso do fluxo de erro do processo, e essa é toda a entrega. Não há exportador a configurar, nenhum arquivo a indicar e nenhuma configuração que ative, desative ou redirecione qualquer parte disso: o que supervisiona este processo — um runtime de contêineres, um gerenciador de serviços, um enviador de logs — é o que coleta esse fluxo, e onde você o consulta depois. Sobre a entrada e a saída padrão o mesmo fluxo traz, em vez disso, prosa legível, porque o cliente que o lê iniciou o processo e está na mesma máquina.

Nada disso é enviado ao chamador. O servidor não publica nenhum fluxo de log pelo protocolo em nenhum dos dois transportes, e uma requisição que traz o campo de nível de log por requisição do protocolo recebe exatamente a mesma resposta que uma que não o traz: o que é registrado aqui é do operador, e vai apenas para o fluxo do operador.

O que o servidor diz ao modelo quando ele se conecta

O servidor oferece um bloco de orientações para o modelo, que seu cliente pode apresentar a ele antes da primeira chamada. Um cliente em 2026-07-28 o lê da resposta de server/discover; um cliente em 2025-06-18 o lê da resposta ao seu handshake initialize. É o mesmo texto nos dois caminhos, byte a byte, e o mesmo texto para todo cliente que alcança um processo: nada nele é negociado, e nada é derivado do que o cliente enviou nem da credencial que apresentou, então o que é dito a um modelo ao se conectar não varia entre sessões nem entre clientes.

Duas coisas variam, e nenhuma delas é o cliente. O parágrafo final é composto para o transporte que um processo atende, então um servidor que fala pela entrada e saída padrão e um listener entregam a um modelo um texto final diferente. E onde o pacote de desktop que iniciou um servidor vem de uma versão diferente da do executável aggrega que ele iniciou, as orientações começam com a única frase que diz isso, indicando as duas versões — a frase com que começa a resposta de describe-capabilities sem argumentos, como descreve De qual versão o servidor vem; uma inicialização que nenhum pacote fez, e uma cujo pacote vem da própria versão do executável, entregam as orientações sem ela. Ambas são fixadas quando o processo inicia, e dentro de cada processo as duas revisões ainda servem de forma idêntica o texto próprio daquele processo.

Ele ensina o modelo mental que o esquema de argumentos de um tool não consegue transmitir sozinho:

  • O que o compilador faz, e o que ele deliberadamente não faz — que ele encaminha texto e avalia correspondências de labels em vez de interpretar o que um valor significa, que ele é sem opiniões próprias sobre o conteúdo que você coloca nos seus documentos, e que durante a compilação ele nunca se autentica com um provedor, nunca lê o estado de um cluster e nunca transforma um segredo em texto puro. Um valor que só existe quando a infraestrutura está em execução trafega como uma string de ponteiro que o ambiente de destino preenche depois.
  • O vocabulário de autoria, e como os tipos se relacionam — para que serve cada tipo e contra qual deles um build é de fato executado, para que um assistente não precise inferir a forma de um deployment a partir da lista de tools.
  • A ordem em que o ciclo de autoria acontece — ler o contrato, gerar a estrutura a partir dele, inspecionar aquilo a que você está se conectando e depois verificar antes de renderizar.
  • Quando recorrer a um prompt em vez de um tool — um tool para agir, um prompt para enquadrar uma tarefa.
  • Que a lista de tools é a superfície inteira — todo tool que este servidor oferece está nela, e quais tools um servidor oferece depende de como ele foi configurado, então um assistente lê o que há aqui nessa lista e em describe-capabilities em vez de sair procurando uma segunda. Onde a conexão apresentou uma credencial, ele diz que a credencial decide quais desses tools uma chamada pode executar e nunca quais deles são listados: uma chamada que ela não admite é recusada indicando o scope que a admitiria, e o cliente pode entrar novamente para esse scope.
  • O que um workspace vazio significa, e o que o modelo pode fazer a respeito — o parágrafo que difere conforme o transporte, abaixo.

Ele indica as superfícies em vez de repeti-las. Cada tool já traz sua própria descrição e seu esquema de argumentos em tools/list, e o contrato de cada tipo já está em seu esquema e em sua página de referência, então as orientações apontam para eles e param — um único lugar por afirmação. Um tool que elas indicam é um tool que o servidor atende, e elas apontam para cada família de recursos que a superfície de leitura resolve, de modo que nada para onde enviam um assistente é um beco sem saída.

Ele não traz nenhum índice dos próprios tools, e essa é a mesma regra, não uma omissão dela. Um cliente tem a definição de cada tool a partir de tools/list antes de ler uma palavra deste texto, então uma linha por tool aqui seria uma segunda cópia de propósitos que ele já tem — paga em cada sessão, por cada cliente, e livre para divergir da lista de tools no momento em que qualquer uma das duas fosse editada.

Ele também diz o que não enumera, e por quê: os destinos de renderização disponíveis e os tipos de biblioteca instalados são propriedades dos seus plugins e do seu conjunto de esquemas, então as superfícies de recursos os informam diretamente em vez de as orientações trazerem uma cópia que poderia divergir.

O que é dito a um modelo sobre um workspace vazio

O parágrafo final responde à pergunta que um modelo encontra primeiro em um workspace que não contém nada: o que significa um list-entities vazio, e o que ele pode fazer a respeito. Sua abertura é a mesma nos dois transportes — uma listagem vazia significa que o workspace que este processo resolveu não contém documentos Aggrega que ele possa ler e que os diretórios de catálogo configurados ao lado dele também não declaram nenhum — e o que vem depois depende de qual transporte este processo atende, porque a resposta honesta não é a mesma nos dois.

Sobre a entrada e a saída padrão, diz-se ao modelo que o workspace é dele para inspecionar e reparar. Diz-se a ele onde uma chamada que não indica nenhum workspace é respondida — na pasta com a qual o servidor foi iniciado, onde ele foi iniciado com uma, e caso contrário no workspace encontrado a partir da pasta em que ele foi iniciado, que pode ser essa própria pasta — e que workspace_root em uma chamada indica outro. Ele é direcionado a config-show para a configuração em vigor e qual camada decidiu cada configuração, e a cli-config-init para inicializar uma que funcione; ambos estão na lista de tools nesse transporte. O cliente que executa o servidor está na própria máquina do chamador, então o que esse processo pode alcançar cabe a esse mesmo chamador gastar — e onde você define o limite é onde ele é definido para todo outro tool, no seu cliente MCP, como descreve O que um assistente pode fazer sem perguntar a você antes.

Via HTTP, diz-se ao modelo para relatar em vez de configurar. O workspace é aquele sobre o qual você iniciou o processo e é fixo durante toda a vida dele; uma chamada que indica workspace_root ou catalog_dirs é recusada, indicando o argumento; e nenhum tool que grava configuração é oferecido aqui a nenhum chamador, quaisquer que sejam os scopes que sua credencial traga. Essas operações só são oferecidas pelos tools que executam um comando aggrega em um processo separado, e uma sessão alcançada via HTTP é composta sem eles — então o limite é a composição e não um scope, e nenhum token o amplia. Um modelo que alcança seu deployment por um listener, portanto, não pode inicializar um registry nem reescrever uma política de confiança no seu host, e o parágrafo diz isso a ele em vez de deixá-lo tentar e ler a recusa.

O que um assistente pode fazer sem perguntar a você antes

Um assistente conectado a este servidor pela entrada e saída padrão pode chamar todo tool que o servidor expõe, sem perguntar a você, a menos que seu cliente esteja configurado para negá-lo. Nesse transporte o servidor oferece os tools e não decide quais deles uma determinada chamada pode usar: essa decisão é do seu cliente, e cabe a você tomá-la ali. Via HTTP não é o mesmo: o servidor lista todo tool que oferece e anuncia, e recusa uma chamada que os scopes do token chamador não admitem, então o limite é do servidor e também do cliente.

Isso importa porque a superfície de tools é a linha de comando. Tudo o que você pode digitar, um assistente pode chamar — incluindo as operações que mudam sua máquina.

Algumas dessas operações vão além do workspace em que você está trabalhando, e não podem ser desfeitas executando outra coisa. Estas são as que vale conhecer pelo nome, começando pela de maior alcance:

  • publish-entity, publish-artifact, sign-artifacts e deprecate-artifact vão totalmente além da máquina. Eles colocam bytes, uma assinatura ou um marcador de retirada em um registry, então o que mudam é o que todo consumidor desse registry resolve — não apenas o que esta máquina faz. Republicar conteúdo diferente sobre uma tag é recusado em vez de oferecido, então nada aqui desfaz uma publicação; a resposta é publicar uma nova versão. Uma assinatura e um marcador de retirada deixam os bytes do artefato intactos, mas quem baixar esse artefato depois os baixa também, e nenhum dos dois pode ser recolhido de quem já o tem. Sobre a entrada e a saída padrão as mesmas quatro capacidades também são alcançáveis como cli-push, cli-push-artifact, cli-sign e cli-deprecate, que executam os comandos; via HTTP esses quatro tools não existem.
  • A assinatura usa credenciais. Sobre a entrada e a saída padrão, a assinatura keyless obtém um token de identidade do argumento identity_token da chamada, de AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN no ambiente do servidor, ou do endpoint OIDC ambiente do GitHub Actions onde houver um alcançável; key_path seleciona em vez disso uma chave mantida offline. Um assistente que pode chamar esses tools pode, portanto, assinar como você, com qualquer identidade que a máquina que executa o servidor já tenha — e uma assinatura é uma declaração sobre quem responde por um artefato, e é por isso que esta é a operação sobre a qual pensar com mais cuidado antes de permiti-la. Sobre um listener só um token enviado na chamada assina: nada no ambiente do servidor é lido, e nenhuma chave mantida no host pode ser selecionada por um argumento ou pela configuração do workspace atendido, como descreve Quais credenciais uma chamada gasta.
  • aggrega cache evict reduz o armazenamento de módulos compilados, e aggrega cache clear o esvazia. Esse armazenamento é compartilhado por todo projeto Aggrega na máquina. Os módulos removidos dele são recompilados sob demanda, então nada se perde permanentemente — mas o próximo build de qualquer projeto paga esse custo. aggrega cache clear também remove o pacote de documentação que todo projeto na máquina lê, que é baixado novamente na próxima vez que um deles o obtém.
  • aggrega cache prune libera entradas do cache de artefatos que nenhum lockfile referencia. Onde o lockfile de um projeto não está presente para ser lido, seus artefatos fixados não são protegidos por ele, e liberá-los significa ter de baixá-los novamente.
  • aggrega registry add e aggrega registry remove gravam por padrão na configuração compartilhada entre todos os workspaces, então mudam o que é resolvido em toda a máquina, não apenas aqui. aggrega registry add também pede ao registry que indica a política de confiança que esse registry anuncia e fixa o que recebe, exatamente como faz em um terminal. Em um workspace offline essa busca é recusada antes de qualquer conexão, então adicionar um registry diferente do hub oficial é recusado — código curto E0310, com as mesmas palavras — a menos que a chamada forneça identity ou key; aggrega config init, que não aceita nenhum dos dois, só pode inicializar o hub offline. Sobre a entrada e a saída padrão eles são alcançáveis como cli-registry-add e cli-registry-remove, e a inicialização como cli-config-init, que executam os comandos; via HTTP esses tools não existem.
  • pull lê de um registry e grava dentro do workspace para o qual é apontado. Ele grava o lockfile dessa Release, preenche o cache de artefatos com o que resolveu, e registra ao lado do lockfile a identidade de cada plugin que retorna veredictos anexado ao seu workspace. Enviado com pin_sources — ou em um workspace cujo pin_sources_at_pull está ativado e com uma chamada que não o envia como false — ele também executa a etapa de pin do autor da entidade sobre as Recipes e FeatureRecipes que a Release constrói a partir dos seus diretórios de catálogo, gravando o entity.lock ao lado de cada uma; sem isso, um pull sobre uma entidade assim cujo lock não registra nenhum pin para uma entrada que ela lê é recusado, indicando a etapa. Os próprios arquivos de entidade nunca são gravados. Nada disso sai da máquina, e resolver novamente é a forma de mudar o que foi registrado, então esta é a mais branda das operações daqui que gravam. É um dos tools pensados para o ciclo de autoria que gravam dentro do workspace: pin grava o entity.lock ao lado da Recipe ou FeatureRecipe que você indicar, como descreve Fixar as entradas próprias de uma entidade; gen-catalog grava entidades Plugin geradas no diretório que você indicar; edit-document aplica uma edição estruturada e delimitada a um documento que você já tem e o grava de volta, preservando cada byte que a edição não toca, como descreve Aplicar uma edição delimitada a um documento; e import transforma uma descrição produzida por outra ferramenta em arquivos de autoria em rascunho e os grava no workspace, como descreve Transformar uma descrição externa em entidades em rascunho; e scaffold, enviado com example, grava um dos exemplos executáveis da documentação em um diretório novo ou vazio, dir, como faz aggrega scaffold --example, o que via HTTP o escopo de gravação no workspace admite. Esse diretório de saída, o guest que gen-catalog lê e qualquer overlay que você der a ele são cada um relativos à raiz do workspace, ou absolutos sobre a entrada e a saída padrão, o mesmo contrato que todo outro argumento de caminho nesta superfície usa. Sobre a entrada e a saída padrão a mesma capacidade também é alcançável como cli-pull, que executa o comando; via HTTP esse tool não existe.
  • build lê o mesmo registry e realiza a mesma gravação quando você envia auto_pull a ele, e somente então. Resolver as dependências de uma Release é uma única operação onde quer que seja pedida, então um build instruído a resolver primeiro faz exatamente o que pull faz e depois renderiza contra o que gravou — e é por isso que ele traz o mesmo alcance, e não um menor. Enviado com write, ele também grava os artefatos renderizados em dist/ na raiz do workspace, onde aggrega build os grava e pela mesma gravação, então ele alcança o workspace nessa chamada; não grava em nenhum outro lugar, e um dist que seja um link que leva para fora do workspace é recusado antes que qualquer coisa nele seja removida ou gravada. Sem nenhum dos dois argumentos, que é o padrão, build renderiza a partir dos pins que o workspace já tem e não alcança nada. Leia Fazer build contra o conteúdo que uma Release já fixa para saber o que o argumento muda e o que ele deixa como está.

Os tools de inventário dizem isso nas próprias respostas. cache-status marca cada classe de cache com seu alcance — workspace para o cache de artefatos no próprio diretório de cache deste projeto, machine para os armazenamentos que todos os projetos compartilham — e indica explicitamente os que abrangem a máquina inteira, de modo que um assistente que lê o inventário antes de propor uma limpeza fica sabendo quais partes dele não são só suas. As operações de manutenção informam o mesmo alcance para cada elemento que removeram. Cada um dos quatro resultados de publicação traz seu próprio reach, contendo registries — cada host de registry ao qual a chamada se dirigiu, cada um indicado uma vez, na ordem em que se dirigiu a eles pela primeira vez — e beyond_this_machine, que é lido a partir do que a chamada de fato anexou, e não do que ela pediu: true assim que tiver enviado conteúdo ou anexado uma assinatura, uma data de publicação ou um marcador de descontinuação, e false para uma execução de teste e para uma chamada que encontrou tudo já presente, como uma publicação executada novamente sobre uma versão completa ou um lote de assinatura cujas referências já estavam todas assinadas.

Onde você define o limite. O próprio protocolo não define permissão por tool — sua autenticação trata de se um cliente pode se conectar, e não de quais tools ele pode chamar depois. A decisão de permissão fica no seu cliente MCP. Clientes amplamente usados geralmente conseguem permitir e negar tools individuais pelo nome a partir de um mesmo servidor, e desativar um servidor inteiramente para um determinado projeto; o nome e o local da configuração diferem de cliente para cliente, então consulte a documentação do seu cliente sobre permissões de tools. Se você quer as leituras e não as gravações, permita ali os tools que quiser e negue o restante. Uma configuração permissiva, ou um cliente sem essa configuração, deixa todo tool exposto invocável.

Descobrir o que um workspace contém

A maioria das ferramentas recebe um sujeito: um nome de entidade ou o caminho de uma Release. As duas abaixo não recebem nenhum, e são a forma pela qual um assistente que acabou de chegar obtém um.

list-entities responde o que o workspace contém e list-releases responde à pergunta mais restrita que o resto da superfície continua fazendo: quais Releases existem. Nenhuma das duas recebe um sujeito, porque o que um workspace contém é uma propriedade do workspace, e não de algo que quem chama precise conhecer primeiro.

Cada uma responde em um de dois formatos, e uma chamada que não indica nenhum formato recebe o resumo. Esse padrão pertence apenas a essas duas, e é o oposto do adotado por build, describe e validate. A essas se pergunta sobre um sujeito que quem chama já nomeou, então a resposta mais completa é a que foi pedida e a concisa é a opcional. A estas duas se pergunta o que existe aqui, por alguém que ainda não tem nada para nomear e nenhum modo de saber quanto a resposta vai custar antes que ela chegue — por isso elas informam primeiro o tamanho e o formato do workspace e só entregam registros quando solicitados.

O resumo diz o que existe aqui e em que quantidade. list-entities informa a raiz do workspace — retida via HTTP, como explica O que uma resposta diz sobre o sistema de arquivos do servidor —, o número total de entidades e uma contagem por tipo; list-releases informa o total e uma contagem por diretório de nível superior, para que você saiba quantas Releases existem e em que parte da árvore elas estão. As duas divisões são lidas dos próprios documentos, então um workspace organizado de um jeito que ninguém previu é resumido com a mesma precisão que qualquer outro. As duas trazem uma linha por tipo, ou por diretório de nível superior, então seu tamanho acompanha quantos tipos um workspace declara e em quantos diretórios suas Releases estão, e não quantos documentos ele contém: multiplique por cem os documentos de um workspace, sem alterar seus tipos, e o resumo cresce apenas os poucos bytes necessários para escrever os números maiores. Declarar mais tipos é o que o torna mais longo. Nenhuma das duas é uma primeira página de registros, e a diferença é justamente essa: “aqui estão algumas das entidades” é uma resposta diferente de “é disto que o workspace é feito”, e só a segunda diz se você quer algum registro, e quais.

Envie response_format: detailed para obter os registros, que chegam uma página por vez. list-entities informa então o tipo, o nome, a apiVersion, a descrição, os rótulos e o arquivo de origem de cada entidade, lidos diretamente do documento que a declara. Também informa as Features que seus diretórios de catálogo configurados declaram, para que uma Feature oferecida a você como anexável seja também uma que você pode consultar; essas não têm arquivo de origem, porque o único caminho que têm fica na máquina em que o servidor é executado, e cada uma diz de onde veio, para que um arquivo vazio seja lido como “resolvido a partir do catálogo” e não como um valor ausente. list-releases informa o caminho de cada Release, e lockfiles associa cada caminho retornado ao caminho do lockfile dessa Release, na mesma coordenada: o arquivo que pull grava para ela e que build lê, o mesmo arquivo que as respostas do servidor de linguagem sobre a Release nomeiam. O mapa descreve os caminhos que esta resposta traz, então acompanha a página, e o resumo o traz vazio.

detailed e concise são os únicos valores que response_format aceita, e são comparados de forma exata. Qualquer outra grafia — uma palavra diferente, maiúsculas e minúsculas diferentes ou espaços em volta de um deles — é recusada, e a recusa nomeia o que foi enviado ao lado dos valores que o argumento aceita. Omitir response_format é a forma de pedir o padrão, que para estas duas ferramentas é o resumo. O mesmo vale onde quer que o argumento apareça: build, describe e validate aceitam os mesmos dois valores nas mesmas condições, e o padrão delas é o formato mais completo, e não o conciso.

Os registros são limitados, quer você os limite ou não. limit é quantos uma resposta traz, entre 1 e 500, e o padrão é 50 — então uma chamada que pede registros sem indicar um tamanho de página continua limitada, e nenhuma invocação de nenhuma das duas ferramentas retorna uma resposta cujo tamanho seja decidido pelo tamanho do workspace. offset é onde começar na listagem, contando a partir de 0. Ambos limitam os registros, então nenhum deles tem efeito sobre o resumo, que não traz nenhum. Um limit fora desse intervalo é recusado e nomeia o limite; um offset além do fim da listagem volta vazio, porque não há nada ali, e não porque haja algo errado com a pergunta.

Continue uma listagem lendo três campos da resposta. count é quantos registros o workspace contém, offset e returned dizem onde esta resposta começa e quantos ela traz, e more_remaining diz se ainda resta algum. Enquanto more_remaining for true, chame de novo com offset mais returned. Esse sinal é calculado a partir da página em relação ao total, em vez de ser escrito na resposta, então não pode informar que nada resta enquanto ainda restam registros.

Tudo isso importa porque as ferramentas que recebem um nome recusam um nome que não conseguem resolver, em vez de responder com um resultado vazio. A recusa é deliberada — uma resposta vazia apresentaria um nome digitado errado como um sujeito sem nada a oferecer —, mas significa que quem chama sem ter um nome não consegue obter um tentando adivinhar. Enumerar é a forma de obter um.

As duas se combinam, entre si e com o resto da superfície:

  • Chame list-entities para obter o resumo e ver quais tipos o workspace contém e quantos de cada, depois chame de novo com response_format: detailed para obter os registros, pegue um nome do resultado e passe-o para describe para ver a definição totalmente resolvida dessa entidade. É a definição com que aggrega/entityDefinition do servidor de linguagem responde, transmitida como JSON: cada chave sob o nome que seu autor escreve, na ordem em que a definição a contém, um schema tal como o autor o escreveu, e um schema que a entidade não declara omitido — os sockets de um Component, cada um com os slots que suas conexões podem preencher.
  • Faça o mesmo com list-releases, pegue um caminho do resultado detalhado e passe-o para describe ou build como a Release com que trabalhar.
  • O caminho que list-releases retorna é relativo à raiz do workspace, que é a mesma coordenada sob a qual list-entities informa um arquivo, então as duas respostas se alinham pelo arquivo e podem ser lidas juntas. O lockfile dela, em lockfiles, é relativo à mesma raiz, então você pode ler ou comparar esse arquivo sem precisar descobrir onde ele fica.

Ambas decidem o que conta lendo o próprio kind de cada documento, nunca o nome do arquivo. Uma Release nomeada sem um prefixo convencional é listada; um arquivo apenas nomeado como tal não é, e aparece sob o tipo que realmente declara. Um YAML que não declara nenhum kind — o arquivo de valores de um chart, um arquivo de configuração que por acaso está na árvore — não é uma entidade e não é informado, assim como não o é um documento pertencente a outro projeto, como um manifesto do Kubernetes renderizado. Um documento conta como entidade quando declara tanto um kind quanto um nome, porque são esses dois juntos que o tornam endereçável depois, e não declara nenhuma apiVersion fora do grupo próprio do Aggrega. Um que não declara nenhuma apiVersion é informado, por ser um documento do Aggrega com um campo faltando, e não um arquivo de outro projeto. list-releases não procura em nenhum diretório fora da raiz do workspace, então uma Release que seu editor mostra sob um link que leva a um desses diretórios não é listada; unread_linked_dirs nomeia cada link que está onde a listagem leria um diretório e que leva para fora da raiz — pelo próprio caminho do link relativo à raiz, nunca pelo destino —, nos dois formatos e nos dois transportes, e fica vazio onde não há nenhum. Ela também não lê um arquivo fora da raiz por meio de um link: unread_linked_files nomeia, da mesma forma, cada link cujo próprio nome termina em .yaml ou .yml e que leva a um arquivo fora da raiz, seja qual for o conteúdo desse arquivo, então uma Release alcançada apenas por meio de um desses links não é listada — a menos que a configuração do workspace nomeie essa Release, como build.authoring_release ou como chave de workspace.releases, caso em que ela é lida e listada no próprio local do link e não é nomeada. list-entities também não lê nenhum documento atrás de um link que leva para fora do workspace — não procura em nenhum diretório fora da raiz e não lê nenhum arquivo fora dela, seja o que for que esse arquivo declare — e nomeia cada um desses links da mesma forma, em seus próprios unread_linked_dirs e unread_linked_files, nos dois formatos e nos dois transportes. Isso vale seja o que for que o documento declare, com a única exceção que list-releases faz: uma Release que a configuração do workspace nomeia, como build.authoring_release ou como chave de workspace.releases, é lida e listada no próprio local do link e não é nomeada, enquanto um arquivo nomeado por uma dessas configurações que declara algo diferente de uma Release não é listado, e seu link é nomeado. Os diretórios de catálogo configurados são a forma pela qual um workspace lê outras entidades mantidas em outro lugar, então um link para um diretório que a configuração lista em catalog_dirs, ou para um diretório abaixo de um deles, não é nomeado por nenhuma das duas listagens: a configuração chegou até ele. As Features que list-entities obtém dos diretórios de catálogo nunca incluem uma atrás de um link que leva para fora do diretório dentro do qual as leituras de um diretório de catálogo devem permanecer — o workspace, para um diretório de catálogo dentro dele, ou o próprio diretório, para um que a configuração nomeia fora dele —, então uma entidade nomeada como estando atrás de um link que não foi lido nunca é listada ao lado desse nome. Um link que a listagem deixa de fora — pelo nome, pela localização ou por um .gitignore — não é nomeado, e com release também não o é um que esteja sob um diretório de catálogo que só outras Releases leem; um .gitignore que seja ele próprio um link que leva para fora do workspace não é lido. Onde qualquer uma dessas listas nomeia um link, a resposta em texto termina com uma linha própria dizendo isso.

Um workspace cujo arquivo de configuração leva para fora dele continua sendo listado, e nada mais é respondido para ele. Onde o próprio .aggrega-config.yaml do workspace, ou o overlay gerenciado pela CI ao lado dele, é um link que leva para fora do workspace, sua configuração não é lida, como em um terminal, e nada do que ela teria configurado é lido em seu lugar. O servidor ainda assim é iniciado via entrada e saída padrão, e informa isso em uma linha em seu fluxo de erros. list-entities e list-releases respondem com os próprios documentos do workspace, lidos sem nada configurado, então nenhuma Feature de diretório de catálogo é listada. Cada uma nomeia o arquivo retido em unread_linked_files, e na linha que fecha seu texto, quer a listagem o tenha encontrado ou não — esse nome é como você percebe que a configuração do workspace leva para fora dele. Uma listagem que recebeu release ou catalog_dirs, e qualquer outra ferramenta que nomeie esse workspace, depende da configuração que não foi lida, então cada uma é recusada com E0321, nomeando o link e para onde ele leva. Um servidor instruído por sua linha de comando a escutar — --transport http ou --listen — não é iniciado sobre um workspace assim, porque o endereço ao qual ele se vincularia, seu certificado e quem pode chamá-lo são justamente o que essa configuração decide. Remova o link, ou faça-o levar a um arquivo dentro do workspace, e a próxima chamada lê a configuração. Veja o limite do workspace.

Perguntar nos termos de uma Release

Um workspace pode dar a cada Release seus próprios diretórios de catálogo — veja Dar a uma Release seus próprios diretórios de catálogo — e assim manter lado a lado uma variante de uma entidade por Release. Três ferramentas que, de outra forma, respondem sobre os próprios diretórios de catálogo do workspace aceitam um release opcional, o caminho de um arquivo de Release, e então respondem nos termos dessa Release:

  • list-entities com release lista as entidades que essa Release enxerga. As Features listadas são as que seus diretórios de catálogo declaram, e um documento do workspace sob um diretório de catálogo que só outras Releases leem fica de fora, então cada variante é listada para a Release que faz o build com ela e para nenhuma outra. Um documento que não está sob nenhum diretório de catálogo — uma Release, seu Aggregate e seu Manifest escritos ao lado dos catálogos — é listado para cada Release.
  • describe com um name e um release resolve o nome por meio dos diretórios de catálogo dessa Release, então um nome que várias variantes declaram é resolvido para aquela com que essa Release faz o build. Um nome que esses diretórios não resolvem é recusado com uma explicação que nomeia a entrada dessa Release em workspace.releases. Uma referência de registro é lida do seu registro seja qual for a Release nomeada, então é recusada ao lado de um release. Um release enviado sem name continua sendo a Release que describe resume.
  • validate com um entity e um release executa as verificações de entidade única nos termos dessa Release: as referências da entidade — o Component que uma Recipe implementa, uma SchemaLibrary a que um pilar se refere — são resolvidas por meio dos diretórios de catálogo dessa Release, e a resposta nomeia a Release ao lado da entidade. Nenhum fechamento é validado; um release enviado sem entity continua sendo o escopo da Release. catalog_dirs é colocado antes dos diretórios da Release aqui, como em todo lugar. Um diretório que a configuração do workspace lista e que não é um diretório — porque nada existe ali, por exemplo —, para essa Release, ou para o workspace quando nenhum release é enviado, faz a chamada ser recusada antes de qualquer verificação, com o texto trazendo a recusa que todo comando lhe dá e nomeando a entrada e o arquivo e a linha de configuração que a listam (De onde as entidades locais são lidas), assim como aggrega validate o recusa.

Um release que nomeia um arquivo que não existe, ou que nomeia um diretório, é recusado pelas três em vez de ser respondido nos termos do workspace. Não enviar nenhum faz a resposta ser dada sobre os próprios diretórios de catálogo do workspace.

describe, ao procurar um nome, recusa um diretório de catálogo pelo qual resolveria o nome e que não pode ser percorrido, assim como aggrega inspect o recusa — os diretórios dessa Release quando um release é enviado, os do próprio workspace quando nenhum é enviado, e quaisquer que a chamada nomeie em catalog_dirs. Um diretório nomeado pela chamada que não existe, ou um que existe e não pode ser lido, é recusado antes de o nome ser procurado, e o texto nomeia o diretório como a linha de comando o informa, em uma única linha — o diretório, catalog load e o motivo dado pelo sistema de arquivos — em vez de resolver o nome a partir dos diretórios restantes. Um diretório que a configuração do workspace lista e que não é um diretório é recusado no mesmo momento, com o texto trazendo a recusa que todo comando lhe dá (De onde as entidades locais são lidas). Um release que nomeia um arquivo que não existe é recusado antes disso, como acima. Um diretório de catálogo que contém um link que leva para fora do diretório dentro do qual suas leituras devem permanecer é recusado da mesma forma, com o texto nomeando o link e para onde ele leva, porque um nome resolvido sem ele poderia ser resolvido, em seu lugar, para outra entidade de mesmo nome. Descrever o fechamento de dependências de uma Release não é afetado por um diretório que não pode ser percorrido, e responde sobre os diretórios que podem, como faz aggrega inspect --closure — exceto um diretório que a configuração do workspace lista para essa Release e que não é um diretório, que essa descrição recusa assim como aggrega inspect --closure o recusa; um link que leva para fora das leituras de um diretório de catálogo, ou para fora dos documentos ao lado da Release, interrompe essa descrição, assim como interrompe um build.

validate com um entity informa uma renderização que não consegue julgar como não tentada, nos termos de uma Release ou sem eles. Ele coloca o Component de uma Recipe em um build sintetizado que não conecta nenhuma conexão e não anexa nenhuma Feature, então uma Recipe cuja renderização para enquanto seus templates — incluindo os arquivos e as entradas de biblioteca que eles importam — leem qualquer coisa sob .context.inject, .context.uses ou .features responde valid: true sem nada em diagnostics; seu texto traz Render: not attempted (this Recipe reads values a build of one cannot supply), as leituras pelas quais ela foi deixada de lado e a frase em que a renderização parou. O que decide é o que a Recipe lê, então uma falha própria da Recipe ao lado de uma leitura assim é deixada de lado junto com ela, enquanto um template que não pode ser analisado e uma referência que a renderização recusa continuam respondendo valid: false. aggrega validate dá o mesmo veredito para as mesmas entradas.

validate com um entity informa uma asserção com falha como um aviso, nos termos de uma Release ou sem eles. Uma asserção que chama fail — a da própria Recipe, ou uma que o Component que ela implementa declara — responde valid: true sem nada em diagnostics. O build sintetizado traz placeholders e padrões do schema no lugar dos valores que uma Release real define, então uma asserção sobre um desses valores falha ali, esteja a Recipe correta ou não, e a verificação não consegue distinguir uma asserção que aguarda uma Release de uma que está quebrada. A falha vem depois das outras notices, na mensagem completa da asserção encerrada pela frase A Release must satisfy this assertion before a build of it can pass., e o texto a traz em uma linha iniciada por warning:, ao lado da linha de relatório que diz onde a execução parou. Uma asserção que para em uma chave que lê mas não encontra é uma falha no seu próprio texto, e não uma asserção com falha, e é julgada como qualquer outra parada; um build de uma Release que não satisfaz uma asserção continua sendo recusado por causa dela. aggrega validate dá o mesmo veredito para as mesmas entradas.

Ler a configuração em vigor e os plugins que este servidor resolve

config-show informa a configuração em vigor e qual camada decidiu cada configuração. plugin-list informa os plugins que este servidor consegue resolver e o que cada um deles diz sobre si mesmo. Nenhum dos dois lê ou grava nada, então nenhum alcança nada e aggrega:read os admite — e nenhum pede que você nomeie um sujeito, porque o que está configurado e o que é resolvido são propriedades deste servidor, e não de algo que você precise conhecer primeiro. Cada um aceita um workspace_root opcional via entrada e saída padrão; via HTTP esse argumento é recusado, como explica Um processo, um workspace.

Juntos, eles respondem a uma pergunta em duas metades: se uma capacidade está ausente ou apenas não está configurada aqui. A configuração diz se um provider, um importador ou uma verificação de governança está anexado ou não; a leitura dos plugins diz se um anexo alcança um guest que é resolvido, se descreve e serve o que afirma servir. De qualquer outro ponto desta superfície essas duas situações parecem iguais, e pedem próximos passos opostos.

config-show informa uma entrada por configuração: seu field, seu value efetivo e a source que a decidiu — um arquivo de configuração, uma variável de ambiente, uma flag de linha de comando ou os padrões embutidos. Ao lado deles, layers traz as camadas que contribuíram, em ordem de precedência, da mais baixa para a mais alta. A source de uma configuração é escrita exatamente como a entrada correspondente em layers, então as duas se juntam diretamente, e uma configuração decidida pelos padrões não nomeia nenhuma camada, porque os padrões não são uma camada que contribuiu. A camada global é o arquivo que a própria linha de comando do servidor seleciona — o que --config nomeou quando ele foi iniciado, senão o que a variável de ambiente AGGREGA_CONFIG nomeia, senão o local padrão —, então uma configuração decidida por esse arquivo é atribuída a esse arquivo, exatamente como aggrega config show --origin a atribui, e uma flag como --offline passada ao servidor é informada como essa flag. Ele não aceita response_format nem tamanho de página: as configurações são o conjunto fixo de que este binário dá conta e toda resolução informa todas elas, então o tamanho da resposta acompanha o binário, e não o que você configura.

plugin-list responde nos dois formatos que as listagens do workspace usam, e uma chamada que não indica nenhum formato recebe o resumo. O resumo é uma contagem por grupo, e há dois grupos — embedded, os guests compilados neste binário, que são resolvidos sem acesso a sistema de arquivos, cache ou rede, e configured, os bindings do próprio workspace. Envie response_format: detailed para obter os registros: o grupo de cada plugin, a referência sob a qual ele foi encontrado, onde essa referência foi vinculada, seu tipo, versão, commit, capacidades servidas, tipos de entrada renderizados, assembly de fronteira e exports conforme ele mesmo os informa, sua prontidão, quando tiver uma, e se ele foi resolvido. Os registros são limitados por limit e offset nas mesmas condições que a listagem de entidades usa, com count, returned e more_remaining para continuar. Esta resposta, sim, cresce com o que você configura — os embutidos são fixos, os bindings são seus —, e é por isso que ela é paginada e a leitura da configuração não é.

Um plugin que falha é informado com sua falha, em vez de ser removido da listagem. resolved diz se a referência chegou a alcançar bytes de módulo, e um plugin que foi resolvido mas não conseguiu se descrever é informado exatamente assim — de modo que um anexo presente e inutilizável se distingue de um que nunca foi feito.

O que um listener não informa sobre seu host

Via HTTP, nenhuma das duas leituras informa um valor que nomeie um local no sistema de arquivos do servidor. Um cliente que iniciou o servidor é executado onde o servidor é executado, então todo local que qualquer uma das respostas poderia nomear é um que esse chamador já possui e pode ir ver. Um chamador que alcança um listener não escolheu nenhum deles, não pode agir sabendo deles, e um servidor que os publicou a um chamador assim não pode retirá-los. Nesse transporte esses valores ficam ausentes; via entrada e saída padrão todos estão presentes. É a regra que toda resposta desta superfície segue, como explica O que uma resposta diz sobre o sistema de arquivos do servidor, e essas duas leituras são onde ela vai mais longe, porque a maior parte do que informam é configuração que nomeia locais.

O que é retido. De config-show: o value de uma configuração quando o próprio valor dessa configuração é um local — um endereço de serviço ou de health check, que pode ser um arquivo de socket; um arquivo de certificado, de chave privada ou de conjunto de chaves; um diretório de catálogo, e os próprios diretórios de catálogo de uma Release em workspace.releases, cujas entradas têm, cada uma, um arquivo de Release como chave; uma referência de plugin; uma Release de autoria. Também a source de uma configuração quando a camada que a decidiu é um arquivo de configuração, já que essa camada é nomeada pelo próprio caminho desse arquivo — e, com a mesma grafia e pelo mesmo motivo, as entradas de arquivo de configuração de layers. De plugin-list: a uri de um plugin quando essa referência é ela própria um caminho do sistema de arquivos, e o texto de uma falha de resolução ou de descrição, que é composto a partir dos locais tentados e, portanto, nomeia locais que a própria referência não nomeia. De ambos: workspace_root.

O que é informado por inteiro, nos dois transportes. Uma referência de registro, uma versão, um commit, um digest, uma capacidade servida, um rótulo de prontidão, o nome de uma variável de ambiente ou de uma flag, e uma camada que não é um arquivo. origin em um registro de plugin é um desses: é a chave de configuração em que um binding foi escrito, ou o digest fixado que uma extensão de comando instalada carrega, e um embutido não carrega nenhum — então é a mesma string onde quer que o plugin seja lido. resolved é outro: se um plugin falhou é informado a todo chamador, mesmo onde o motivo não é.

Um valor ausente sempre diz que foi retido, e é isso que torna a resposta utilizável. Um valor retido é informado como ausente com uma marca ao lado — value_withheld e source_withheld em uma configuração, withheld em uma entrada de camada, uri_withheld e error_withheld em um registro de plugin, e workspace_root_withheld na resposta. Uma configuração que ninguém definiu traz o valor vazio com que seu formato é renderizado, e não traz nenhuma marca. “Este servidor não está dizendo onde está a chave de assinatura” e “nenhuma chave de assinatura está configurada” são respostas diferentes, que pedem próximos passos diferentes, e uma leitura que as informasse de forma idêntica não diria nada sobre o que você pudesse agir. Cada resposta também traz host_locations_withheld, sempre, que diz qual das duas respostas você tem em mãos: uma resposta sem marcas é, de resto, a mesma, quer esta regra a tenha moldado e não houvesse nada no host para reter, quer ela nunca tenha sido aplicada. O texto legível ao lado dos campos diz o mesmo em palavras.

A regra é uma propriedade, e não uma lista de nomes de campos: um valor é retido quando nomeia um local no sistema de arquivos do host, seja quem for que o definiu e seja qual for a camada de onde veio. Um valor adicionado mais tarde a qualquer uma das leituras está sujeito a essa mesma propriedade.

Via entrada e saída padrão, cada capacidade também pode ser alcançada como a ferramenta com o nome do seu comando — cli-config-show e cli-plugin-list —, que executa esse comando em um processo separado e devolve o texto que ele imprimiu; via HTTP essas ferramentas não existem. As duas descritas aqui trazem os valores em vez disso, para que você leia se uma capacidade está anexada, ou extraia a versão de um plugin, sem precisar converter um layout em colunas de volta naquilo a partir do qual ele foi renderizado.

Perguntar o que pode ser anexado e o que pode se conectar a quê

Duas ferramentas respondem às perguntas que, de outra forma, um assistente teria de adivinhar: quais Features podem ser anexadas a um nó e a que um nó pode se conectar. Ambas executam a mesma correspondência de rótulos que o compilador executa, então o que o assistente oferece a você é o conjunto que um build faria corresponder, e não um conjunto inferido do schema.

attach-candidates informa as Features cuja aplicabilidade declarada os rótulos de um nó satisfazem. Indique o nó de exatamente uma de três formas:

  • node — o metadata.name de uma entidade do workspace, como list-entities o informa. A correspondência é feita sobre os rótulos que esse documento declara.
  • graph_node com release — um nó em um grafo compilado, com a chave que o grafo lhe dá, incluindo a forma qualificada que um nó contribuído por um subagregado carrega. A correspondência é feita sobre os rótulos finalizados desse nó, que são os que um build avalia.
  • labels — um conjunto de rótulos por si só, sem nomear nenhum nó. Não precisa de nenhuma coordenada, então, se você já tem os rótulos de um nó, esta é a forma a usar; ela não procura nada e não reconstrói nenhum grafo.

A resposta traz os rótulos sobre os quais a correspondência foi feita e de qual desses três conjuntos eles vieram, para que você possa explicar qualquer candidato — ou a ausência de um — a partir da própria resposta, em vez de deduzi-lo de novo. Lê-los de volta por um segundo caminho é justamente onde a sua ideia dos rótulos de um nó e a do compilador se separam.

Para perguntar o que pode ser anexado a uma conexão que um nó traça, adicione connection ao lado de graph_node e release — seu socket e seu alias, como o autor os escreveu. Uma conexão traz anexos que preenchem os slots que seu socket declara no Component consumidor, então a resposta passa a trazer também slots: cada slot que o socket declara, com seus selector, required, inject, sensitive e description exatamente como o Component os declara, e os candidates que podem preenchê-lo. Essas são as Features cuja aplicabilidade os rótulos do nó satisfazem e cujos próprios rótulos o seletor do slot admite — as duas regras a que um build submete um anexo assim —, então os candidatos de um slot estão sempre entre os do próprio nó. Onde nada pode ser preenchido, slots fica vazio e noSlotReason diz por quê: feature-created-connection (uma Feature traçou a conexão, e nada é anexado a uma conexão assim), ad-hoc-socket (o socket é um que o Component não declara) ou no-slot-declared (o socket não declara nenhum). Não leia um slots vazio como “nada correspondeu”; é justamente isso que o motivo existe para descartar, e ele fica ausente onde quer que exista um slot. candidates ao lado deles mantém seu significado — o que pode ser anexado ao próprio nó — e document, se você enviar um, não muda nada aqui. connection ao lado de node ou labels, ou sem nomear nenhum socket ou alias, é recusado, assim como uma conexão que o nó não traça. São as mesmas respostas que o servidor de linguagem dá, nas mesmas condições.

connection-candidates informa os sockets de dependência que uma entidade declara e, por socket, os Components do workspace cujos rótulos declarados satisfazem a restrição que esse socket declara sobre seus alvos. Ele recebe o metadata.name da entidade em node. Diferentemente de attach-candidates, ele não tem uma forma sem coordenada: aqui não há um formato de conjunto de rótulos, porque os sockets são lidos da própria declaração da entidade nomeada.

Suas duas metades não são igualmente completas, e a resposta diz qual é qual — não as apresente como uma única lista. Os alvos são completos: são os componentes que a mesma restrição admite durante um build. Os sockets não são, e não podem ser. Um consumidor pode inventar uma conexão, mas só pode consumir o que um produtor declara, então um autor pode legitimamente escrever um socket que a entidade do catálogo nunca declarou, e os sockets declarados são um ponto de partida útil, e não o conjunto de nomes válidos. Cada socket diz, portanto, se é declared ou ad-hoc, e a resposta diz se um socket não declarado é sequer aceito nessa entidade — a superfície de dependências de um Component aceita um, porque um autor é dono da topologia da sua aplicação; a superfície de anexos de uma Feature não, porque um anexo participa da topologia que a Feature anexada declara, em vez de criar uma. Essa abertura é uma consequência da sua liberdade de autoria, não uma lacuna: passe socket com um nome que a entidade não declara para perguntar sobre ele.

Ambas respondem e param. Nenhuma das duas cria um anexo, cria uma aresta, grava em qualquer arquivo ou propõe o texto de uma alteração; compor e aplicar a edição que vier depois cabe a você.

Ambas retornam a mesma identidade mínima que todas as outras respostas aqui usam — tipo, nome e arquivo de origem — e nada mais. Todo o resto que você quiser exibir sobre uma entidade já está em list-entities para esses mesmos três campos, então você junta as duas respostas em vez de ler duas cópias que poderiam divergir. Ambas recusam um nome que não conseguem resolver em vez de responder com uma lista vazia, pelo mesmo motivo que o resto da superfície: uma resposta vazia apresentaria um erro de digitação como um sujeito sem nada a oferecer. Uma chamada com labels não tem nenhum nome para digitar errado, então um resultado vazio ali significa o que diz.

Tudo o que o servidor lê como referência é servido a partir desta máquina — os JSON Schema são embutidos no binário e a documentação é lida do cache de pacotes de documentação que a máquina mantém, como descrito abaixo. A criação de um documento inicial, a validação, a descrição, o build e o linting são todos executados sobre o seu workspace e os caches locais, e nenhum deles alcança um registro por iniciativa própria: uma renderização serve uma referência externa fixada a partir do armazenamento endereçado por conteúdo e declina uma não fixada em vez de buscá-la, que é o que mantém offline todo o ciclo de inspeção e renderização. Há duas leituras de registro que você pode pedir: describe com uma referência de registro, que busca essa única coordenada, não grava nada e, via HTTP, só alcança um registro com o qual o workspace servido está configurado; e scaffold enviado com example ou list, que obtém o pacote de documentação do registro padrão do workspace quando a máquina não tem nenhuma cópia que a política de assinatura do workspace admita, verificando-o antes de guardá-lo, como faz aggrega scaffold --example. Publicar e assinar são o outro lado deliberado disso, e são tratados acima.

Entre os dois está a resolução das dependências de uma Release, que é a única coisa aqui que adquire: ela alcança um registro porque pedir para resolver dependências é pedir para buscá-las. Isso só acontece quando você pede, e há exatamente duas formas de pedir — chamar pull, cuja função é justamente essa, ou enviar auto_pull para build, que realiza essa mesma resolução como primeiro passo do build. Nada mais faz pull em seu nome, e um build ao qual você não enviou auto_pull não alcança nenhum registro. A única configuração que muda isso é o próprio auto_pull do workspace: um workspace configurado assim pede a todo build nele que resolva primeiro, de onde quer que esse build seja executado, o que é tratado abaixo.

A única exceção entre essas leituras de referência é a aquisição do próprio pacote de documentação, e ela acontece longe de qualquer leitura. O pacote é mantido uma vez por máquina, no cache que todo projeto Aggrega compartilha, uma cópia para cada registro e versão — então um servidor iniciado em uma pasta onde nenhum cache de workspace pode ser criado o mantém mesmo assim (veja aggrega cache). Quando o servidor é iniciado, antes de responder a qualquer coisa que você envie, ele procura ali uma cópia que a verificação de assinatura do seu próprio workspace admita — a mesma verificação a que um pull do pacote se submete — e busca o pacote, pelas mesmas configurações de egress que o resto da CLI usa, somente quando não há nenhuma. O pacote que ele procura é o publicado para a versão do aggrega que o servidor executa ou, quando nenhum é publicado para ela, o mais recente publicado para uma versão anterior — a mesma escolha que aggrega explain e aggrega scaffold --example fazem —, e cada página que ele serve, e cada explicação, é lida daquele que ele obteve. Assim, as páginas já estão lá quando algo pede uma, seja o que for que o seu cliente envie primeiro, e outro servidor, ou aggrega explain em outro projeto, encontra a mesma cópia em vez de baixá-la de novo.

Servir uma página é então uma leitura dessa cópia, e não alcança nenhum registro. Antes de uma página ser servida, as assinaturas mantidas ao lado da cópia são verificadas novamente sob a verificação do seu workspace, então uma cópia que a configuração mais permissiva de outro projeto deixou entrar não é servida a você: onde a verificação fixa uma chave ou uma trust root, essa verificação é feita offline, e onde não fixa nenhuma das duas — a verificação embutida do hub oficial é uma delas — ela obtém a trust root pública do Sigstore, como faz um pull. Um workspace offline não consegue buscar essa trust root, então, offline, ele verifica com base na trust root que uma busca online anterior nesta máquina deixou no cache que o cliente Sigstore mantém em .sigstore no seu diretório home, por mais antiga que seja essa busca, e não busca nada; em uma máquina que nunca a buscou, a verificação não pode ser executada offline, a cópia não é servida e o fluxo de log informa isso. Essa verificação é executada uma vez para cada cópia e cada verificação enquanto o servidor está em execução, e as páginas lidas depois dela são servidas com base no que ela admitiu: uma cópia buscada desde então, um workspace cuja verificação é diferente — incluindo uma trust root fixada editada no local —, uma leitura feita offline, ou uma leitura offline que encontra uma trust root diferente deixada na máquina é verificada por si só. Uma cópia que a sua verificação recusou é verificada novamente na próxima leitura, então uma busca que a tenha admitido desde então não é anulada. Se o pacote não puder ser adquirido, ou se a única cópia for uma que a sua verificação recusa e buscá-la de novo sob essa verificação falhar, o servidor é iniciado mesmo assim e todas as outras superfícies funcionam; as solicitações de documentação respondem not-found, e o fluxo de log do servidor diz por quê.

Compilar com base no conteúdo que uma Release já fixa

build renderiza em memória uma Release em seus artefatos, e uma renderização pode pedir conteúdo de uma URL remota — o schema de values de um chart com uma referência remota, por exemplo. As entradas externas ficam congeladas durante a chamada. Uma referência que o lockfile da Release já fixa é servida a partir do armazenamento endereçado por conteúdo, o que é uma leitura de conteúdo que já está em disco, e não um download. Uma referência que o lockfile não fixa é descartada e nomeada em vez de baixada: o que você pediu foi uma renderização, e adquirir uma referência significaria tanto alcançar a rede quanto gravar um blob no armazenamento como efeito colateral da produção de bytes. Esse congelamento é uma propriedade da renderização. A resolução é a etapa que adquire: ela renderiza a Release para descobrir quais referências remotas essa renderização pede, baixa-as e registra-as na mesma gravação do lockfile que contém as fixações das dependências. Portanto, o que a resolução muda é quais referências estão fixadas no momento em que uma renderização é executada, nunca o que uma renderização pode alcançar — e uma referência que nenhuma resolução fixou é descartada em uma chamada que resolveu primeiro exatamente como em uma que não resolveu.

Os arquivos voltam como os bytes que uma compilação real emite, e são duas coisas juntas que tornam isso verdade. Uma é o congelamento descrito acima: uma referência fixada é lida do armazenamento em vez de baixada. A outra é que o lockfile do qual se lê ainda descreve aquilo para o que a Release é resolvida — por isso build verifica isso e recusa um lockfile que não corresponde mais, exatamente como aggrega build faz em um terminal. Ler bytes fixados não diz nada, por si só, sobre se eram os bytes certos a ler.

Os três estados do lockfile, para que o comportamento seja explícito. Sem nenhum lockfile, build renderiza a partir do que o espaço de trabalho já fixa e descarta cada referência externa que não consegue servir, nomeando cada uma; por conta própria, não exige um lockfile nem grava um, e a verificação descrita acima não muda isso — não há lockfile para comparar, então nada é recusado. Com um lockfile que corresponde, renderiza. Com um lockfile que não corresponde mais, recusa, e a recusa indica como resolver a situação: chame pull com a mesma release e sem upgrade_targets, o que reconcilia o lockfile com aquilo para o que a Release é resolvida hoje. A recusa também traz a forma de terminal dessa mesma operação, aggrega pull --release <release>. Qualquer uma das invocações a elimina; são uma única operação acessível a partir de dois lugares, não duas instruções entre as quais escolher. Quando pull é concluído e a recusa volta, as duas chamadas resolveram sobre entradas diferentes — na maioria das vezes catalog_dirs passado a uma e não à outra, ou uma configuração do espaço de trabalho editada entre elas — e a recusa diz isso: chame ambas com as mesmas.

validate e describe, quando recebem apenas um release, ficam sujeitos ao mesmo lockfile. Sobre um lockfile que não corresponde mais àquilo para o que a Release é resolvida, cada um recusa em vez de responder, com um texto que traz a parada por desvio com que build recusa e a mesma forma de resolvê-la — como aggrega validate --release e aggrega inspect --closure recusam no terminal. Com um lockfile que corresponde, ou sem nenhum, cada um responde como faria normalmente.

Pedir a uma compilação que resolva primeiro suas dependências

Envie auto_pull e a compilação resolve antes de renderizar. Ela executa a mesma resolução que pull executa — a própria operação, não uma segunda escrita para uma compilação, de modo que um espaço de trabalho preenchido por uma compilação e um preenchido por uma chamada pull ficam preenchidos de forma idêntica —, grava o lockfile da Release e depois renderiza com base no que gravou. Essa etapa alcança um registry e grava, algo que nada mais em build faz além de write, e write não alcança nenhum registry — por isso ela fica desativada a menos que seja pedida.

Ela responde às duas recusas descritas acima sem sair do protocolo. Uma Release que ninguém resolveu ainda renderiza a partir das fixações que por acaso existam e descarta o resto; um lockfile que derivou interrompe a compilação de imediato. Enviar auto_pull resolve primeiro e renderiza com base em um lockfile derivado do fechamento de que trata esta compilação, de modo que ambos os casos voltam como uma renderização em vez de algo que é preciso ir corrigir. Quando você quiser a resolução e a renderização como etapas separadas — para ler o que foi fixado antes de renderizá-lo —, chame pull e depois build, que são as mesmas duas operações com uma olhada entre elas.

Uma chamada renderiza a Release uma única vez. Descobrir quais referências remotas uma Release consome é em si uma renderização, então uma resolução já renderizou a Release de que trata a compilação — com base nas mesmas fixações que acabou de gravar, com cada verificação que uma compilação executa. A compilação é respondida a partir dessa renderização em vez de repeti-la, e é por isso que enviar auto_pull custa uma resolução e não uma segunda renderização. Somente uma renderização que terminou é usada assim: quando uma resolução fixou suas dependências mas não conseguiu terminar de descobrir as referências externas, a compilação renderiza por conta própria com base nas fixações que de fato foram gravadas, e uma referência não fixada então a interrompe pelo nome em vez de voltar como uma lista de arquivos que fica aquém do que uma compilação emite.

O que volta diz o que foi resolvido. Uma compilação que preencheu traz dependency_resolution em sua resposta, no formato com que pull responde: o lockfile que gravou, cada referência que a resolução alcançou com a versão para a qual cada uma foi resolvida e de onde a resolução desta compilação a obteve, as contagens que o lockfile contém em seguida e o relato que a resolução faz de si mesma linha por linha. Uma compilação que não preencheu não traz esse campo de forma alguma, então a presença dele é como você distingue as duas sem ler o disco. Os arquivos renderizados são informados exatamente como em qualquer outra compilação, e continuam sendo retornados em memória, a menos que a chamada também tenha recebido write — a resolução grava o lockfile e o cache de artefatos, nunca um artefato.

Um espaço de trabalho pode pedir isso de forma permanente, e uma chamada não pode desativá-lo. A configuração auto_pull do próprio espaço de trabalho ativa a mesma etapa para cada compilação nesse espaço de trabalho, e auto_pull em uma chamada se soma a essa configuração em vez de substituí-la: qualquer uma das duas basta, e não há argumento que suprima uma resolução que o espaço de trabalho pediu. É da mesma forma que a configuração e aggrega build --auto-pull se combinam em um terminal, de modo que um espaço de trabalho responde da mesma maneira seja qual for a superfície pela qual chega uma compilação.

O descarte é informado em vez de absorvido, e com os provedores que este binário inclui um descarte interrompe a renderização: o provedor que pediu a referência devolve a recusa, então a chamada responde com essa falha e não retorna nenhum arquivo. A referência é nomeada onde um leitor pode agir sobre ela, ao lado do comando que a fixa: aggrega pull --release <path>. A mesma fixação é acessível nesta superfície como a ferramenta pull, descrita abaixo em Resolver aquilo de que uma Release depende, de modo que um assistente que encontre essa recusa pode agir sem sair do protocolo. Uma renderização totalmente fixada não diz nada disso. Consulte aggrega pull para saber o que a fixação baixa e registra, e aggrega build, onde uma referência não fixada é informada e interrompe a execução da mesma forma.

Gravar os artefatos onde aggrega build os grava

Envie write e a renderização concluída também é gravada em dist/ na raiz do espaço de trabalho, onde aggrega build a grava. O diretório é aquele que a linha de comando compõe sob a mesma raiz do espaço de trabalho, e a gravação é a que ela executa, de modo que, para uma Release em um espaço de trabalho, aggrega build, o aggrega/build do servidor de linguagem sem outputParent e esta chamada gravam uma única árvore, byte a byte, e nomeiam esse diretório da mesma forma — a linha final do comando, o outputDirectory do servidor de linguagem e o output_dir desta resposta. Um dist que é um link que leva para fora do espaço de trabalho é recusado antes que qualquer coisa nele seja removida ou gravada, como em um terminal. Se omitido, que é o padrão, os artefatos são retornados em memória e nada é gravado.

A raiz do espaço de trabalho é a da própria chamada. Pela entrada e saída padrão, é a raiz do espaço de trabalho que a chamada resolveu, como expõe Em qual espaço de trabalho uma chamada é respondida: a raiz que workspace_root nomeia, senão a raiz com que o servidor foi iniciado, senão o espaço de trabalho encontrado a partir do diretório em que o servidor foi iniciado — e, quando uma Release nomeada por um caminho absoluto move a chamada para o espaço de trabalho dessa Release, a raiz desse espaço de trabalho. É a raiz sob a qual aggrega build grava para a mesma Release e a mesma raiz nomeada, de modo que a pasta em que o servidor por acaso é executado recebe um dist somente quando essa pasta é a raiz que a chamada resolveu, como aconteceria em um terminal aberto ali. Por HTTP, é o espaço de trabalho que o servidor serve, e nada é gravado fora dele.

A gravação alcança o espaço de trabalho, então por HTTP ela precisa de aggrega:workspace-write. Uma chamada que recebeu write alcança o espaço de trabalho para essa chamada, exatamente como uma compilação que resolve primeiro suas dependências: uma credencial que traz apenas aggrega:read recebe como resposta 403 nomeando aggrega:workspace-write, e nada é gravado, e um servidor cujo mcp.deny_reach nomeia workspace recusa a chamada nomeando essa configuração. A ferramenta permanece na lista de ferramentas de cada chamador, e uma compilação que não recebeu write continua disponível para um chamador com escopo somente de leitura.

Ela grava por último. Também com auto_pull, a chamada resolve, renderiza e depois grava, nessa ordem. Uma chamada recusada em qualquer ponto anterior — sua Release, seu espaço de trabalho, um diretório de catálogo, a resolução, a renderização — não grava nenhum artefato.

A resposta nomeia o que foi gravado. output_dir é o diretório — completo pela entrada e saída padrão, dist por HTTP — e files lista cada arquivo gravado, relativo a ele, com seu conteúdo em response_format: detailed e apenas seu caminho em concise; o texto diz quantos arquivos foram gravados e onde. Uma chamada que não recebeu write não traz nenhum output_dir, então a ausência dele é como você sabe que nada foi gravado. Uma gravação que falha depois que a renderização terminou — em uma raiz do espaço de trabalho na qual ninguém pode gravar, por exemplo — responde como uma falha que nomeia o diretório e a causa, e não lista nenhum arquivo como gravado: parte da gravação pode estar em disco, e nomear os arquivos renderizados como gravados afirmaria mais do que aconteceu.

Nenhum argumento nomeia um diretório, e nenhum pede um trace. Para onde vão os artefatos é decidido pelo espaço de trabalho que a chamada resolveu, nunca pela chamada, e uma compilação gravada a partir daqui não deixa nenhum diretório .trace ao lado de sua saída; uma compilação com trace é aggrega build --trace.

O que uma compilação informa além de seus arquivos

Um build traz cada aviso que emitiu, na própria resposta. São as constatações que aggrega build imprime enquanto trabalha — um nome a uma única edição de distância de um declarado, um parâmetro que nada lê, um destino que não consegue respeitar um campo escrito pelo autor, um veredito de governança que não interrompe o build, um diretório de fronteira que uma Release herdou da Release que estende e que se resolve para o mesmo caminho, uma propriedade que um Component ou uma Feature alcançado pela Release declara tanto no pilar values quanto no pilar infra. Nenhum deles muda o resultado: um build que traz avisos ainda assim teve sucesso, e os arquivos que retorna são os arquivos que produziu. Eles chegam na ordem em que um terminal os imprime, de modo que quem compara os dois encontra uma única sequência, e não duas: primeiro tudo o que a renderização emitiu, na ordem em que emitiu, depois as constatações sobre a Release e o que ela alcança, que aggrega build imprime assim que a renderização retorna, e por último, em um build enviado com write, o aviso que nomeia cada arquivo que a gravação encontrou ao lado dos seus e que não gravou, e que deixa no lugar — o mesmo que aggrega build imprime assim que seus arquivos são gravados (Arquivos que o build não gravou).

Elas estão na resposta, e não apenas no texto de resumo, porque um assistente que conduz esta superfície não lê nenhum terminal, e uma constatação da qual ninguém é informado é uma constatação que não foi feita. Cada uma traz uma severity — warn para algo que requer atenção, info para uma observação registrada — e uma message; um code quando sua classe atribui um, para que você possa reagir a uma condição específica sem comparar texto; e um key_path que nomeia a chave no documento escrito pelo autor a que a constatação se refere, quando se refere a uma. Uma constatação sobre a forma da topologia implantada não nomeia nenhuma chave, porque suas coordenadas são as da implantação e não as de um documento, e diz em sua mensagem, em vez disso, a que se refere.

Dois tipos de constatação que um terminal imprime chegam a esta resposta em um lugar diferente de advisories, porque cada um tem um lugar que diz mais. Um marcador de descontinuação registrado fica em deprecations, quer o lockfile o tenha registrado para uma referência fixada, quer o registro de confiança de plugins ao lado dele o tenha registrado para um plugin anexado em um papel que retorna um veredito de aceitar ou rejeitar. describe de uma Release nomeia o mesmo conjunto em suas próprias deprecations, e validate de uma Release entre suas notices, cada um deixando o veredito como está; um registro de confiança que existe e não pode ser lido faz qualquer das duas chamadas ser recusada em vez de passar por um que não registra nada. Um pai do qual uma entidade herda e que não pôde ser resolvido interrompe a compilação, por isso é nomeado no texto da recusa em vez de listado como uma constatação que não mudou nada. Um tipo é limitado pelo que esta ferramenta carrega e não pelo que sua resposta traz: aggrega build carrega cada diretório de catálogo configurado antes de resolver uma Release, e um aviso sobre uma forma de catálogo descontinuada viria desse carregamento, enquanto esta ferramenta lê apenas o que a Release alcança e não realiza esse carregamento, então não informa nenhum aviso desse tipo. No momento nenhuma compilação emite um, então os dois informam as mesmas constatações.

Uma Release que não emite nada não diz nada: a chave fica ausente em vez de presente e vazia, então a simples presença dela indica que há algo a ler.

O que uma compilação recusada devolve

Uma compilação que recusa responde nos mesmos campos em que responde uma compilação bem-sucedida, preenchidos até onde a execução chegou. Ela volta marcada como falha, com a correção como texto, e o payload estruturado fica ao lado desse texto em vez de ser substituído por ele. Uma recusa emitida enquanto a Release é renderizada é lida nas palavras do compilador, como descreve abaixo Uma recusa emitida durante a renderização, e acrescenta um campo próprio. Os avisos estão nele: as fases executadas emitiram o que emitiram, e essas são as constatações sobre as quais você precisa agir para superar a recusa, então elas chegam como entradas com as quais você pode fazer correspondência em vez de prosa que você teria de analisar. deprecations e declined_external_inputs estão nele pelo mesmo motivo — um marcador registrado é informado porque um marcador foi registrado, e uma referência descartada porque uma referência foi descartada, e nenhum desses fatos é consequência de como a execução terminou.

files não informa nada em uma recusa, e não é o campo do qual ler o resultado. Nada foi emitido, então não há artefatos a nomear. Não ramifique com base na presença da chave: ela é informada em ambos os casos, e um files vazio não consegue, por si só, distinguir uma compilação que recusou de uma que foi executada e não emitiu nada. Leia o indicador de falha no resultado — esse é o discriminador do próprio protocolo — e leia files pelo que ele é, a lista do que foi renderizado, e também gravado quando a chamada recebeu write.

O que limita os avisos em uma recusa é até onde a execução chegou, não o que a resposta é capaz de trazer. Uma recusa de uma verificação executada antes de a Release ser resolvida — uma entrada fixada no cache não corresponde mais ao digest registrado para ela e nenhum diretório de catálogo contém os bytes fixados, ou aquilo de que a Release depende não pôde ser resolvido — não informa nenhum aviso, porque nada havia sido emitido ainda. As constatações sobre como uma Release se compõe com a Release que estende são emitidas no momento em que ela é resolvida, antes de cada verificação seguinte, então toda recusa posterior as traz: o Manifest mapeia um tipo para uma receita que não o implementa, uma entidade que a Release alcança não satisfaz seu schema, o lockfile não corresponde mais àquilo para o que a Release é resolvida. As constatações da própria renderização são emitidas à medida que a renderização é executada, então uma recusa de uma dessas verificações anteriores não traz nenhuma delas, e uma recusa da renderização traz tudo o que foi emitido antes dela. Portanto, leia advisories em uma recusa exatamente como você o lê em um sucesso: o que esta execução encontrou, na ordem em que um terminal o imprime.

Uma recusa porque uma entidade herda de um pai que não pôde ser resolvido nomeia cada herança desse tipo em seu texto, nas palavras que aggrega build imprime para ela, para que você saiba qual corrigir. Esse detalhe é o motivo pelo qual a compilação parou, e é por isso que ele está no texto e não entre as constatações que não mudaram nada; as constatações de composição emitidas antes dele estão em advisories, como em qualquer recusa posterior.

Um diretório de catálogo que a Release lê e que não pode ser percorrido é recusado antes que qualquer coisa seja gravada, como aggrega build o recusa. Trata-se de um diretório que a chamada nomeia em catalog_dirs e que não existe, assim como aggrega build recusa um diretório --catalog que não existe, ou de um que existe e não pode ser lido. aggrega build carrega cada diretório que a Release lê antes de resolver a Release, e para em um que não consegue percorrer; build percorre primeiro os mesmos diretórios, sem ler nenhum documento neles, antes de qualquer resolução de dependências e antes da renderização — de modo que uma compilação que recebeu auto_pull não grava nenhum lockfile, e nada é renderizado. O texto nomeia o diretório como a linha de comando o informa, em uma linha: o diretório, catalog load e o motivo informado pelo sistema de arquivos. O payload nomeia a Release, com um files vazio e nenhuma constatação, porque nada havia sido executado. Um diretório que a configuração do espaço de trabalho lista e que não é um diretório — nada existe lá, por exemplo — é recusado antes desse percurso, da mesma forma, com o texto trazendo a recusa que aggrega build dá a ele, nomeando a entrada e o arquivo de configuração e a linha que a listam (De onde as entidades locais são lidas). Um diretório de catálogo que contém um link que leva para fora do diretório dentro do qual suas leituras devem permanecer é recusado no mesmo momento, sem nada gravado, com o texto nomeando o link e para onde ele leva — aggrega build o recusa da mesma forma.

Um exemplo concreto, para que as duas metades fiquem tangíveis. Uma Release que declara um parâmetro que nenhuma referência lê, e cuja renderização depois não consegue ser concluída, volta como uma falha cujo texto traz a recusa da renderização e cujo payload traz o aviso de parâmetro não lido com sua severity, sua message, seu code e seu key_path — a mesma entrada, com os mesmos valores, que a mesma Release informa na resposta quando a renderização é concluída — ao lado da entrada refusal para o que interrompeu a renderização. Uma Release que estende outra e herda um diretório de fronteira sem nenhuma variável de template, e cujo Manifest mapeia um tipo para uma receita que não o implementa, volta como essa recusa com uma entrada de advisories por diretório herdado, cada uma com code inherited-boundary-directory-is-literal. Uma Release cujas dependências não podem ser resolvidas, em um espaço de trabalho cujos diretórios de catálogo listados existem todos, volta como uma falha sem nenhuma chave advisories, porque nada havia sido emitido quando ela parou.

Uma recusa emitida durante a renderização

Uma Release que o compilador recusa durante a renderização — um Workload que nomeia um slot que seu Component não declara, uma asserção que falha, um template que não pode ser avaliado — volta com a recusa nas palavras do compilador e com cada causa abaixo dela, as palavras que cli-build devolve para a mesma Release: o nó sendo renderizado e, em seguida, o que nele recusou. Quando a recusa nomeia uma condição registrada, o texto acrescenta como essa condição se chama — o código curto e o código descritivo com os quais fazer correspondência —, como explain-error faria. O texto começa dizendo qual etapa recusou: The build failed during rendering; nothing was written to disk. para uma recusa emitida pela renderização, e The build refused before rendering anything; nothing was written to disk. para uma emitida pela execução do compilador antes que qualquer coisa fosse renderizada — a composição do grafo com o qual a renderização trabalha recusando, ou uma asserção que um Component ou uma Feature declara.

O payload traz a mesma recusa como uma única entrada, refusal, de modo que um chamador que precisa alterar um documento lê qual, e onde, sem analisar a frase:

  • file — o documento para o qual a recusa aponta: a Recipe de um Workload, a Recipe ou a FeatureRecipe que declara uma asserção que falha, a Release ou o Aggregate que gravou uma entrada que a composição do grafo recusa, ou o Aggregate da Release para uma recusa que não aponta para nenhum documento.
  • key_path — a chave nesse documento, quando a recusa nomeia uma: .spec.workload para uma recusa sobre um Workload, a própria chave da asserção sob .spec.assertions para uma asserção que falha, a própria chave da entrada para a recusa de uma entrada. Uma recusa sobre um Workload é colocada em sua chave workload e não em um nível mais fino, porque o Workload que uma verificação julga é o que seu template produziu, e um template grava linhas que seu autor nunca escreveu; os caminhos que a recusa nomeia dentro desse Workload renderizado permanecem em sua message.
  • line e column — a posição dessa chave, contada a partir de um, a coluna em unidades UTF-16. Ausentes quando a recusa não nomeia nenhuma chave ou o documento não a contém: uma posição só é fornecida onde uma foi encontrada.
  • severity — halt, a severidade da constatação que interrompeu uma compilação.
  • code e short_code — os dois identificadores da condição, quando a recusa nomeia uma condição registrada.
  • message — o texto da recusa, exatamente como aparece no texto da resposta.
  • findings — presente somente quando a recusa reúne várias constatações, como a composição do grafo faz com cada violação que encontrou: uma entrada por constatação, na ordem em que a recusa as enuncia, cada uma neste mesmo formato — com seus próprios file, key_path, line, column, severity, code, short_code e message. Os campos da própria recusa nomeiam então para onde aponta sua primeira constatação, e sua message traz cada constatação, como o texto; a linha de comando imprime cada constatação como um diagnóstico próprio.

A entrada está presente sempre que a própria execução do compilador recusou — durante a renderização, ou antes dela: na composição do grafo, ou em uma asserção que um Component ou uma Feature declara, que não nomeia nenhum documento, de modo que sua entrada nomeia o Aggregate. Uma compilação bem-sucedida não traz nenhuma, nem uma recusada por uma verificação executada antes de o compilador iniciar — o lockfile, os mapeamentos do Manifest, aquilo de que a Release depende —, cuja recusa é apenas o texto. Um valor que um autor declarou sensível é omitido da recusa onde o compilador a emite, de modo que a entrada e o texto trazem o que cli-build e o terminal trazem — consulte o que uma recusa diz sobre um valor declarado.

Resolver aquilo de que uma Release depende

pull resolve as dependências de catálogo e de origem de uma Release no cache local e grava o lockfile dessa Release. Ela está nesta superfície por um motivo que vale a pena dizer: as duas recusas descritas acima — uma renderização que descartou uma referência externa não fixada, e uma compilação que parou porque o lockfile não corresponde mais àquilo para o que a Release é resolvida — são ambas respondidas pela fixação, e um assistente que precisa pedir a você que execute um comando não tem como respondê-las sozinho. Leia O que um assistente pode fazer sem perguntar a você antes para saber o que ela grava e até onde isso alcança.

Passe release, o caminho da Release, absoluto ou relativo à raiz do espaço de trabalho — o mesmo contrato que todos os outros argumentos de caminho aqui usam. workspace_root e catalog_dirs substituem a descoberta do espaço de trabalho e do catálogo exatamente como fazem em build. Ambos valem em um servidor alcançado pela entrada e saída padrão; por HTTPS, esses dois argumentos são recusados e o caminho precisa ser resolvido dentro do espaço de trabalho que o processo serve, como expõe Um processo, um espaço de trabalho.

Por padrão, ela reconcilia em vez de resolver de novo. Uma fixação que o lockfile já registra é respeitada e baixada nessa versão, e recusada em vez de fixada de novo silenciosamente se o registry não servir mais esses bytes. Uma referência sem fixação — recém-adicionada, ou removida manualmente do lockfile — é resolvida do zero e adicionada. Uma referência que não está mais entre as dependências resolvidas é podada. Um conjunto de dependências inalterado, portanto, deixa o arquivo idêntico byte a byte, incluindo seu timestamp registrado, de modo que uma chamada que não alterou nenhuma fixação não produz nenhum diff para quem revisar o espaço de trabalho depois.

verify compara e deixa o lockfile como está. Ele verifica o lockfile registrado em relação à resolução que a chamada de reconciliação descrita acima executaria agora, respeitando as fixações registradas exatamente como essa chamada faz, e volta como falha quando há deriva, ou quando não há lockfile com que comparar — então é assim que um assistente descobre se a fixação é necessária antes que qualquer coisa reescreva o lockfile. Nada do que essa chamada registra é gravado — nem o lockfile, nem as identidades de plugins registradas ao lado dele, nem um entity.lock —, enquanto o cache de conteúdo é lido e preenchido exatamente como essa chamada o lê e o preenche. Ele também informa o conjunto de ferramentas que o lockfile registra: a versão do compilador que gravou o arquivo e a versão de cada plugin principal que esse compilador incluía. Isso é informado para auditoria e nunca comparado com o binário em execução, porque o conjunto de ferramentas não faz parte do que o lockfile fixa, e verificá-lo fixaria o compilador indiretamente — uma diferença no conjunto de ferramentas não é uma deriva.

upgrade_targets resolve de novo as referências que você nomeia, e nada mais. Passe a ele um ou mais URIs de entidade na forma escrita simples — core/database, não uma forma com versão. Cada fixação nomeada é descartada e resolvida de novo para a versão mais alta disponível, enquanto todas as outras fixações e as entradas externas registradas permanecem inalteradas. Um URI que não corresponde nem a uma fixação registrada nem a um anexo configurado é recusado em vez de ignorado.

Deliberadamente não existe argumento que resolva tudo de novo de uma só vez. A linha de comando tem essa forma, e ela descarta o lockfile inteiro antes de resolver de novo a partir do estado atual do registry. Nesta superfície o argumento não existe, então a chamada não pode sequer ser composta, em vez de ser aceita e depois recusada: ninguém está observando um fluxo de protocolo, então um descarte total não tem ninguém para confirmá-lo. Quando você quiser isso, e apenas pela entrada e saída padrão, cli-pull executa o comando, e essa é a superfície em que há uma pessoa presente; um chamador que alcança este servidor por HTTP o executa em um terminal no host. verify não pode ser combinado com upgrade_targets — um deixa o lockfile como está e o outro o reescreve — nem com pin_sources, seja qual for o valor que traga: esse argumento decide se uma resolução registra as fixações que faltam a um entity.lock ou recusa por causa delas, e uma comparação não grava nenhum entity.lock, então não faria nem uma coisa nem outra. Uma chamada que envia qualquer um dos dois pares é recusada antes que qualquer coisa seja resolvida, com uma frase que nomeia o par. O schema anunciado da ferramenta não declara essas duas exclusões, porque um cliente que exiba uma delas pode lê-la como uma exigência de enviar verify; a recusa é onde um cliente as aprende. A linha de comando e o daemon recusam os mesmos pares.

O resultado nomeia o que foi resolvido, não apenas que algo foi. Ele traz o lockfile que gravou ou com o qual comparou; resolved, cada referência que a resolução alcançou com a versão para a qual cada uma foi resolvida, o tipo que um autor escreve quando a resolução registra um, e sua source — de onde esta execução obteve a referência, na palavra que aggrega pull --detail imprime para a mesma resolução: fetched-fresh, cache-reuse, local, in-binary ou external; as contagens dos artefatos de origem, das entradas externas e das identidades de plugins confiáveis que o lockfile contém em seguida; e diagnostics, o relato que a resolução faz de si mesma na ordem em que emitiu cada linha — qual fixação foi reutilizada, qual assinatura foi verificada, qual versão foi ignorada por ter sido retirada. Essas linhas chegam a um terminal quando você executa o comando; aqui elas estão na resposta, porque um chamador que não lê nenhum terminal não tem outra forma de recebê-las. verified está presente somente em uma comparação, então a ausência dele é como você distingue uma execução que gravou de uma que apenas comparou. Uma source descreve esta execução nesta máquina, então o lockfile não a registra, e describe, que informa aquilo de que uma Release depende, não nomeia nenhuma.

Uma recusa responde nos mesmos campos, preenchidos até onde a execução chegou. Depois que a resolução é calculada, resolved é trazido qualquer que seja o veredito — um veredito de deriva acima de tudo, já que essa é a recusa sobre a qual um chamador precisa decidir o que mudar. Uma recusa anterior a esse ponto, como um caminho de Release que não é resolvido, traz a correção como texto e nenhuma resolução, porque não havia nenhuma a trazer.

Quando as fixações estão completas e as entradas externas não, a chamada ainda assim é bem-sucedida e diz isso. Descobrir quais entradas externas uma Release consome é uma renderização, e uma renderização pode falhar depois que as fixações das dependências já estão corretas e em disco. Informar a chamada inteira como falha diria a você para refazer um trabalho que está certo, então, em vez disso, incomplete_external_inputs é definido no resultado bem-sucedido, nomeando o que parou: as fixações das dependências estão completas, as das entradas externas podem não estar.

Esta é a ferramenta mais lenta aqui, e a reconciliação sem alterações não é um caminho rápido. Uma resolução paga seu custo integral para estabelecer que um conjunto de dependências está inalterado, então uma chamada que não reescreve nada custa o mesmo que uma primeira resolução — em uma Release pequena, segundos em vez de milissegundos, e isso cresce com o tamanho do conjunto de dependências. Um verify é a mais barata das duas formas, porque uma comparação pula a descida nas origens de cada componente que uma execução com gravação realiza. Se o seu cliente impõe um timeout por chamada, esta é a ferramenta com a qual verificá-lo. Pedir para ser informado do andamento, abaixo, significa que algo chega enquanto a chamada é executada em vez de nada até ela terminar — o que responde a um timeout de inatividade no seu cliente, ou em qualquer coisa que esteja entre você e um servidor alcançado por HTTP, mas não a um limite de quanto tempo uma chamada pode levar no total.

Uma entidade cujo entity.lock não registra nenhuma fixação para uma entrada que ela lê recusa o pull, e a recusa nomeia a etapa que a registra. Espera-se que uma Recipe ou FeatureRecipe que a Release compila a partir dos seus diretórios de catálogo e que lê uma origem remota escrita por completo, ou importa um arquivo por meio de seus artefatos, já traga essas fixações ao lado dela — seu autor as registra com pin, abaixo. pin_sources pede a esta chamada que execute essa etapa em nome do autor sobre cada entidade desse tipo em vez de recusar, gravando o entity.lock ao lado de cada uma; é a mesma etapa que a ferramenta pin executa, e ela grava os mesmos bytes. Omita-o e quem decide é o pin_sources_at_pull do espaço de trabalho; envie-o e ele decide em qualquer das duas direções, de modo que pin_sources: false recusa mesmo em um espaço de trabalho configurado para fixar. Uma entidade que a resolução alcançou no cache, e não em um dos seus diretórios de catálogo, não tem aqui um lugar gravável e nunca é fixada por esta chamada.

Fixar as entradas próprias de uma entidade

pin registra, no entity.lock ao lado de uma Recipe ou FeatureRecipe, a fixação de conteúdo de cada entrada que a entidade lê de fora do próprio documento: uma origem remota cujas coordenadas estão escritas por completo, e um arquivo que uma entrada de artefatos importa. É a mesma etapa que aggrega pin executa em um terminal, e o lock que ela grava é idêntico byte a byte ao que esse comando grava. Passe entity, o documento da entidade, absoluto ou relativo à raiz do espaço de trabalho sob o mesmo contrato que todos os outros argumentos de caminho aqui seguem; por HTTPS, ele precisa ser resolvido dentro do espaço de trabalho que o processo serve.

Nenhuma Release é nomeada, porque nenhuma é necessária. Uma origem cujas coordenadas não trazem nenhum template nomeia um único artefato para cada Release que usa a entidade, então a etapa a resolve e a fixa sem nada que uma Release forneça. Uma origem cujas coordenadas vêm de um template não é fixada aqui: qual artefato ela nomeia é decidido por cada Release, e pull fixa cada identidade para a qual ela é resolvida no lockfile dessa Release.

O resultado diz o que a etapa fez com o lock. Ele traz a entity, seu kind e seu name, e pinnable, que é false para um tipo que não lê nada que um lock registre — um Component ou uma Feature —, caso em que nada ao lado da entidade foi tocado e os outros campos estão ausentes. Caso contrário, traz o lock que gravou, changed, false quando o lock já registrava cada fixação e foi deixado idêntico byte a byte, removed quando a entidade agora não lê nada que um lock registre e seu lock foi excluído, e pins, uma entrada por classe de fixação com a contagem que o lock contém em seguida. dry_run responde com o lock que a etapa gravaria como content e não grava nada ao lado da entidade; o cache de conteúdo ainda assim é preenchido, porque as entradas são resolvidas exatamente como seriam de outra forma.

Ela grava dentro do espaço de trabalho e alcança os hosts que as origens da entidade nomeiam — um repositório de charts, um host Git, uma URL —, então por HTTP ela é admitida para uma credencial que traz o escopo que admite pull, e recusada para uma que só pode ler. Pela entrada e saída padrão, a mesma capacidade também é acessível como cli-pin, que executa o comando; por HTTP, essa ferramenta não existe.

Ser informado do andamento de uma chamada longa

Uma chamada informa seu progresso quando você pede para ser informado, e pedir é um único campo. Coloque progressToken no _meta da chamada — uma string ou um número, à sua escolha. Ele volta em cada relatório exatamente como você o escreveu, e é a única coisa em um relatório que aponta de volta para a sua chamada: um relatório não responde a nada, então não traz nenhum id. Não envie nenhum token, ou envie-o como null, e nada muda — a chamada é respondida da mesma forma que seria sem ele. Um token de qualquer outra forma é recusado, antes que a chamada faça qualquer coisa, nomeando as duas formas que ele pode ter em vez de ser ignorado: um chamador que pediu para ser informado e depois encontra silêncio não tem nada sobre o que agir.

O que chega é notifications/progress, trazendo o seu token e uma contagem que aumenta a cada um. Não há total nem mensagem, e nenhum dos dois é uma omissão aguardando trabalho: o que o trabalho informa é que entrou em outra fase, então um total só poderia ser inventado e uma frase só poderia ser composta aqui em vez de repassada. Desenhe um indicador indeterminado a partir da contagem crescente; não há fração com que preencher uma barra.

Por HTTP, a resposta se torna um fluxo de eventos, e somente depois que algo de fato informou. Ela é servida como text/event-stream, marcada para não ser armazenada em cache, e traz X-Accel-Buffering: no para um intermediário que, de outra forma, reteria cada evento até o trabalho terminar e transformaria o fluxo em uma única resposta lenta. Cada relatório é um evento, e a própria resposta da chamada é o último evento antes de o fluxo se fechar. Enquanto o trabalho está em silêncio, o fluxo traz a intervalos uma linha de comentário, que chega ao que quer que esteja no meio como bytes em uma conexão ativa e não chega ao seu cliente de forma alguma. Uma chamada que pediu progresso e alcançou um trabalho que não informa nenhum ainda assim é respondida com um único objeto JSON, porque o que abre o fluxo é o primeiro relatório, e não o token.

Em um fluxo, leia o resultado nesse último evento, e não no código de status. O status e os cabeçalhos são gravados quando o fluxo se abre, ou seja, antes de o trabalho terminar, então uma chamada que informa e depois recusa traz sua recusa como último evento sob o status já enviado. Fechar a conexão no meio do fluxo encerra o trabalho, e nada mais é gravado para ele, exatamente como Como uma chamada termina descreve para qualquer outra chamada.

Pela entrada e saída padrão, os relatórios são linhas antes da linha de resposta, enquadradas da mesma forma que qualquer outra mensagem nesse fluxo — um objeto JSON por linha, na ordem em que foram gravados —, e a linha de resposta vem depois deles. Nada é informado depois que uma chamada termina, em nenhum dos dois transportes.

Resolver as dependências de uma Release é o que informa aqui. pull informa cada vez que a resolução entra em uma fase. build informa somente quando está resolvendo primeiro — porque você enviou auto_pull, ou porque a configuração do próprio espaço de trabalho pede a cada compilação nele que resolva —, já que o relatório pertence a essa etapa: uma compilação que renderiza a partir das fixações que já tem não alcança nada e não informa nada, então um token nessa chamada não muda nada na forma como ela é respondida. Qualquer chamada também informa cada etapa em que seu trabalho entra e pela qual espera — ler um registro, buscar um artefato ou um pacote de documentação, compilar um plugin pela primeira vez —, as etapas que a linha de comando mostra a uma pessoa ao lado do seu indicador de atividade. Uma chamada cujo trabalho não espera por nenhuma delas não informa nada, o que é inofensivo e não um erro: a resposta é a que você teria recebido sem ele.

Perguntar qual conexão está escrita em um ponto de um documento

connection-at-position responde à pergunta anterior à metade de conexões das duas ferramentas acima, para quando você tem um ponto em um documento em vez de um nó em um grafo — uma linha que você está vendo em um Aggregate ou em uma Release. Passe file, o documento, relativo à raiz do espaço de trabalho ou absoluto e lido do disco da mesma forma que insertion-point lê um; position, uma line e um character, ambos contados a partir de zero, medidos nas unidades que position_encoding indica exatamente como insertion-point lê esse argumento; e release, a Release cujo grafo compilado registra as conexões. A Release é obrigatória também para um ponto no Aggregate: um nó do grafo e uma conexão só existem em um grafo compilado.

A resposta é uma de duas metades. Onde o ponto está na entrada de uma conexão, ela contém graphNode e connection — seu socket, seu alias e o document em que o ponto foi lido —, que são exatamente o que attach-candidates recebe junto com graph_node e release, e o que attachment-container recebe para indicar onde vai uma vinculação nessa conexão; esse contêiner fica dentro da mesma entrada em que o ponto caiu. Caso contrário, ela contém noConnectionReason, de um conjunto fechado: no-connection-entry (o ponto não está em nenhuma entrada em que se escreva uma vinculação), feature-created-connection (o ponto está na entrada da Release para uma conexão traçada por uma Feature) ou unknown-connection (o ponto está em uma entrada que a Release escreve para uma conexão que o grafo compilado não contém). A resposta legível apresenta o motivo em palavras.

Um ponto em qualquer lugar dentro de uma entrada está dentro dela — no alias, no seu target, dentro das suas features — e, onde as entradas se aninham, vence a mais interna. Um ponto na própria chave de um socket, acima dos aliases sob ela, não está dentro de nenhum deles. As entradas são as que o grafo compilado registra: no Aggregate, cada conexão que um componente traça, na sua entrada sob o alias da conexão no documento em que o componente foi escrito, que, para um componente fornecido por um módulo importado, é o próprio documento desse módulo; na Release, cada entrada por aresta que ela escreve. Uma conexão escrita como lista de destinos, e uma traçada pelo próprio bloco de dependências de uma Feature, não têm nenhuma entrada em que se escreva uma vinculação. Se uma chave é uma conexão nunca é deduzido a partir do seu nome.

Responde e para. Não escreve nada em nenhum arquivo. Um documento que não está no espaço de trabalho, não pode ser lido ou não é YAML bem formado volta como resultado com falha que indica o que mudar, como acontece com insertion-point; o mesmo vale para um ponto sem a sua line ou o seu character, e para um position_encoding fora dos três.

Perguntar em qual contêiner vai uma vinculação

attachment-container responde à pergunta que fica entre uma resposta de candidatura e um ponto de inserção. Você já decidiu o que vincular a um nó; antes de poder perguntar em que lugar de um arquivo escrevê-lo, você precisa saber qual arquivo e qual contêiner dentro dele. Passe graph_node — o id de um nó em um grafo compilado, tal como o grafo o usa como chave — e release, a Release a que o grafo pertence. Ambos são obrigatórios: o id de um nó é uma chave do grafo de uma Release e não significa nada sem ela.

Não monte esse caminho você mesmo. O id de um nó e o caminho do subsistema que o contém são ambos escritos com pontos entre suas partes, e o ponto é um caractere válido em um nome que um autor digita — então, de fora do documento, não há como distinguir um ponto estrutural de um que faz parte de um nome. Um caminho que você compusesse pareceria correto e apontaria para uma chave que ninguém escreveu, e a edição seguinte criaria essa chave em vez de ser recusada. Pior ainda, o id de um nó não traz nenhum vestígio do subsistema que o contém: um componente escrito dentro de subsystems.billing.subsystems.payments tem como chave ledger, exatamente como um componente de nível superior. Peça o contêiner.

A resposta contém node, o nó a que se refere; file, o documento em que esse nó foi escrito; e container, o caminho estrutural a partir da raiz desse documento como lista de segmentos — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. É uma lista e não uma string unida de propósito: um caminho unido teria de ser dividido de novo por quem o recebesse, o que reintroduziria a ambiguidade acima uma chamada depois. Passe file e container para insertion-point sem alterações.

file faz parte da resposta em vez de ser algo que você já sabe. Um nó fornecido por um módulo importado foi escrito no próprio documento desse módulo com o nome que o módulo lhe deu, de modo que tanto o arquivo quanto o último segmento do contêiner diferem de qualquer coisa que você tenha enviado.

Para uma vinculação em uma conexão que o nó traça, adicione connection com seu socket, seu alias e seu document, que aqui é obrigatório porque qualquer um dos dois documentos pode conter uma. Com aggregate, a resposta é a própria entrada da conexão no documento em que o nó foi escrito, com seu bloco features por último; uma conexão traçada pela Release não tem entrada ali e é recusada. Com release, é a entrada por aresta sob a entrada da Release para o nó — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] —, informada independentemente de a Release já escrever essa entrada por aresta, para que insertion-point indique as chaves que ainda faltam escrever; uma Release que não escreve nenhuma entrada para o nó é recusada, já que não cabe a esta ferramenta decidir onde o nó é colocado. Uma conexão traçada por uma Feature é recusada em ambos os documentos.

Responde e para. Não cria nenhuma vinculação, não escreve nada em nenhum arquivo e não compõe nenhum texto. Também não decide o que pode ser vinculado — isso é attach-candidates. Um nó que o grafo não contém, ou um para o qual ele não registra nenhum documento, volta como resultado com falha que indica o que mudar, em vez de como uma resposta com um campo vazio.

Localizar onde uma entrada vai em um documento

insertion-point responde à pergunta que vem depois de uma resposta de candidatura. Você já decidiu o que vincular ou conectar; agora precisa saber em que lugar do arquivo escrevê-lo. Ele devolve uma posição e as colunas de indentação, para que você possa aplicar a edição sem analisar o documento você mesmo. Como o que ele lê é a estrutura própria de um documento e não a forma de um tipo específico, describe-capabilities o indexa sob qualquer tipo de entidade a que você restrinja a consulta.

Passe file — o documento, relativo à raiz do espaço de trabalho ou absoluto, e dentro do espaço de trabalho: um alcançado por meio de um link que sai dele, para o arquivo ou para um diretório no caminho, não está, e é recusado em ambos os transportes — e container, o caminho estrutural da raiz do documento até o contêiner em que a entrada vai, em que cada elemento é uma chave de mapping ou uma posição de sequência escrita em decimal.

O caminho do contêiner é você quem fornece. A ferramenta lê a estrutura do documento e nunca deduz onde algo vai pelo seu nome, pelo tipo que carrega ou pelo que parece significar. Você diz qual chave; ela diz onde vão as entradas dessa chave neste documento — quais segmentos do caminho o arquivo já contém, as colunas em que ficam suas entradas e a última linha que seu bloco mais interno alcança. Para vincular uma Feature a um nó de um grafo compilado, você não precisa conhecer essa chave: attachment-container, acima, informa o documento e o contêiner, e ambos vão aqui sem alterações.

A resposta é uma position de largura zero, cujos line e character contam ambos a partir de zero; entryIndent e indentStep, as colunas em que escrever; e missingContainerKeys, as chaves de contêiner que este documento ainda não contém, a partir da mais externa, que você escreve antes da entrada. entryShape informa se o contêiner contém um mapping ou uma sequence, e informa unknown onde o contêiner ainda não existe ou não contém nada, porque o documento não disse — a forma fica então a seu critério. indentStepMeasured diz se o passo foi medido a partir do aninhamento próprio deste documento ou é um valor de reserva para um documento que não apresenta nenhum. Onde precededByLineBreak está definido, comece seu texto com uma quebra de linha: a posição fica no fim da linha que a entrada segue, o que é válido quer o arquivo termine ou não com uma quebra de linha e não altera nenhum byte já escrito. Leia missingContainerKeys mesmo onde você espera que o contêiner exista — uma posição aplicada sem as chaves que devem precedê-la produz um documento que não pode mais ser analisado.

position_encoding indica as unidades em que o deslocamento de caractere informado é medido: utf-8, utf-16 ou utf-32. Aqui ele é um argumento porque nenhuma das duas revisões deste protocolo negocia uma, e seu valor padrão é utf-16, que é o que uma sessão de editor adota quando um cliente não negocia nada — assim, quem chama sem indicar nada recebe a mesma resposta nas duas superfícies. Um valor que não é nenhum dos três é recusado em vez de ser substituído silenciosamente pelo padrão, porque deslocamentos medidos de uma forma e aplicados em um buffer medido de outra corrompem o documento no primeiro caractere fora do ASCII.

Responde e para. Não escreve nada em nenhum arquivo, não compõe nenhum texto de entrada e não aplica nenhuma edição; compor o texto e decidir se deve aplicá-lo cabe a você. Uma solicitação que não aponta para um lugar em que uma entrada possa ir volta como resultado com falha que indica o que mudar — um documento que não está no espaço de trabalho, não pode ser lido ou não é YAML bem formado; um caminho de contêiner sem segmentos ou com um segmento vazio; um caminho que atravessa um escalar, dentro do qual nada pode ser acrescentado; um caminho que chega a uma coleção escrita em estilo flow, em que acrescentar reescreveria bytes que o autor já escreveu em vez de adicionar uma linha; ou um caminho que aponta para uma sequência em bloco com algo que não é um de seus índices. Se você preferir que a edição seja aplicada em vez de aplicá-la você mesmo, Aplicar uma única edição delimitada a um documento é a ferramenta que faz isso.

Aplicar uma única edição delimitada a um documento

edit-document aplica o que as duas ferramentas acima localizam. Uma chamada adiciona uma entrada sob um contêiner, ou define um escalar, e não pode fazer mais nada. Ela escreve o documento que você indica, dentro do espaço de trabalho, então, por HTTPS, ela precisa de aggrega:workspace-write: quem chama tendo apenas aggrega:read a encontra na lista de ferramentas, e uma chamada que faz é recusada indicando esse escopo.

Indique a edição em edit; o conjunto é fechado. add-component adiciona uma instância de componente sob um contêiner de componentes; attach-feature vincula uma Feature ao nó que você indica; wire-edge liga uma conexão dentro de um dos sockets desse nó; set-value define um valor nesse nó. Um nome fora desses quatro é recusado em vez de interpretado. Não existe nenhuma edição que exclua, substitua um bloco que você já escreveu, reordene algo ou escreva literalmente bytes que você fornece — portanto, isto não é um gravador de arquivos e não pode ser usado como tal.

Passe file, o documento — relativo à raiz do espaço de trabalho ou absoluto, e dentro do espaço de trabalho: um fora dele, como escrito ou por meio de um link que sai dele, é recusado em ambos os transportes sem que nada seja lido ou escrito; node, o caminho estrutural a partir da raiz do documento como lista de segmentos; name, a chave sob a qual a entrada é escrita; e value, o que essa entrada contém. node é uma lista pelo mesmo motivo pelo qual attachment-container responde com uma: um ponto é válido dentro de um nome que um autor digita, então um caminho unido poderia apontar para uma chave que ninguém escreveu e a entrada seria criada ali em vez de recusada. Para add-component, o caminho indica o próprio contêiner de componentes, porque a entrada adicionada é o nó; para as outras três, indica o nó a que a edição se refere, e o contêiner decorre da edição. socket é lido para wire-edge e ignorado nos demais casos. O que value significa decorre de edit — a entidade que a entrada solicita, o nó para o qual uma conexão aponta ou o escalar para o qual um valor é definido — e é um valor JSON do seu próprio tipo, então um número continua sendo um número, um dígito entre aspas continua sendo texto, e omiti-lo não define nada. Um mapping ou uma sequência é recusado, porque escrever um bloco não é uma destas edições.

Todo byte que a edição não toca é preservado. O documento só é analisado para localizar o contêiner e a linha em que seu bloco termina, então comentários, linhas em branco, estilo de aspas, escalares dobrados e literais e a forma da quebra de linha final são todos mantidos, e o passo de aninhamento é medido a partir da indentação própria do documento em vez de imposto. A mesma solicitação sobre o mesmo documento produz os mesmos bytes.

O resultado tem de ser um documento que você poderia ter digitado, e é disso que a escrita depende. O documento composto é verificado em relação ao esquema do seu próprio tipo e só chega ao disco se passar nessa verificação. Uma solicitação que produziria algo que o esquema recusa é recusada, indicando a propriedade que o esquema não admitiria e onde, e o arquivo fica byte a byte como estava — então uma edição recusada é indistinguível de uma nunca tentada, e você pode repetir uma solicitação corrigida sobre o documento com que começou. Uma entrada que já existe contendo o que você pediu não tem efeito; uma entrada com esse nome contendo outra coisa é recusada em vez de substituída.

A resposta contém container, o caminho estrutural em que a entrada ficou; created_containers, os níveis de contêiner que esta edição teve de criar, a partir do mais externo, vazio no caso comum em que todo o caminho já existia; e written, o documento que chegou ao disco, vazio onde nada chegou. Leia created_containers: uma edição que escreveu silenciosamente dois blocos aninhados que o documento não continha é, de outra forma, indistinguível de uma que adicionou uma única entrada a um bloco que você mesmo escreveu.

dry_run faz tudo menos escrever. O documento editado volta como content, nada é criado e written fica vazio — para um cliente que mostra o resultado ao autor antes de ser salvo. Todo outro comportamento é o da escrita, incluindo a verificação do esquema, então uma solicitação que a escrita recusaria também é recusada com ele. Sem ele, o documento é escrito e content fica ausente, porque o documento já está no disco e written o indica.

Se o que você liga é semanticamente admissível — se um socket é um dos que o produtor declara, ou se a aplicabilidade de uma Feature é satisfeita — não é decidido aqui. É isso que validate responde.

Na entrada e saída padrão, a mesma capacidade também está disponível como cli-edit-document, que executa o comando e devolve o texto que ele imprimiu; por HTTP essa ferramenta não existe, e ali a capacidade é acessada por esta.

Transformar uma descrição externa em rascunhos de entidades

import converte uma descrição que outra ferramenta produziu — por exemplo, um fluxo exportado de um construtor de agentes — em rascunhos de arquivos de autoria do Aggrega. Ela escreve esses arquivos no espaço de trabalho que este servidor serve, então, por HTTPS, ela precisa de aggrega:workspace-write: quem chama tendo apenas aggrega:read a encontra na lista de ferramentas, e uma chamada que faz é recusada indicando esse escopo.

Passe source, o arquivo ou o diretório a converter. Ele é absoluto ou relativo à raiz do espaço de trabalho, o mesmo contrato que todo outro argumento de caminho nesta superfície usa, e em um servidor acessado por HTTPS ele é resolvido dentro do espaço de trabalho que esse servidor serve.

De um diretório são lidos exatamente os arquivos que os padrões de arquivo do seu importador selecionam. Um chart ou um projeto é um diretório, e source pode indicar um. O importador recebe então os arquivos dele, em qualquer profundidade, que um dos padrões de arquivo declarados por suas assinaturas seleciona, cada um nomeado pelo seu caminho dentro do diretório escrito com barras normais, em ordem, junto com os arquivos que sua vinculação plugins.importer indica sob with.sources, com seus nomes base; um arquivo do diretório e um arquivo de with.sources com o mesmo nome são recusados em vez de um esconder o outro. Um importador que não declara padrões de arquivo lê um único arquivo e recusa um diretório, sob a condição An importer that declares no file patterns is handed a directory (Um diretório é entregue a um importador que não declara padrões de arquivo), e um diretório que não contém nenhum arquivo que seus padrões selecionem também é recusado. O diretório fica restrito a si mesmo onde quer que esteja: um link entre os arquivos que a importação leria, ou para um diretório, que sai dele é recusado antes de qualquer leitura, e nunca se entra em um link para um diretório — como expõe Um diretório que você importa. Em um servidor acessado por HTTPS, o próprio diretório é resolvido dentro do espaço de trabalho, e portanto também todo arquivo lido dele.

O importador é um que o catálogo do seu espaço de trabalho contém, ou um dos importadores nativos do compilador. A tradução é obra do plugin importador que anuncia o formato da fonte: um que o catálogo do seu espaço de trabalho contém, ou um dos importadores nativos do compilador, que servem seus formatos em todo espaço de trabalho sem nenhuma entrada de catálogo. Esta ferramenta o seleciona, o executa e escreve o que ele produziu. Uma vinculação plugins.importer cujo uri indica um importador pela sua identidade e versão — importer/<name>:<version>, como aggrega plugin add importer o escreve — vincula esse importador: onde ele anuncia o formato da fonte, é ele que é executado, nessa versão, seja qual for o outro importador que também anuncie o formato, e ele recebe as fontes e as configurações with dessa vinculação, que nenhum outro importador recebe. Onde vários importadores anunciam o formato e nenhum deles sozinho está vinculado — entre eles um importador nativo e um importador de outro nome que seu catálogo contém para o mesmo formato —, a chamada é recusada indicando-os, como descreve Configuração. Um formato que você indica e que nenhum importador anuncia é recusado indicando a capacidade que um importador teria de anunciar — import:langflow para uma fonte do Langflow —, que é o que declara um importador que você adiciona ao catálogo, em vez de com uma falha genérica que você então teria de interpretar.

Um importador nativo que a máquina do servidor não tem é baixado uma única vez, pela primeira importação que precisa dele. A importação o baixa do registro padrão do espaço de trabalho servido, o confronta com o módulo que a versão do compilador publica, verifica sua assinatura segundo a política de confiança desse registro e as funções de host que ele usa, assim como um pull verifica um plugin que baixa, e o guarda no cache de conteúdo do espaço de trabalho, de modo que toda importação posterior o lê dali e não contata nenhum registro. Nada mais é escrito para ele — nenhum lockfile e nenhuma lista de plugins confiáveis. Por HTTPS, este é o único registro que uma chamada a esta ferramenta pode fazer o servidor contatar, dentro do limite que Quais credenciais uma chamada gasta define para uma leitura de registro: o registro é o padrão do espaço de trabalho que este servidor serve, portanto é um com o qual esse espaço de trabalho está configurado; nada na chamada indica um registro ou carrega uma credencial; e o download gasta o login e a política de confiança próprios deste host. A ferramenta continua alcançando o espaço de trabalho e nada além dele, então aggrega:workspace-write é tudo de que uma chamada precisa: o que o download deixa para trás é um módulo no cache de conteúdo próprio do espaço de trabalho. Um módulo que não passa na verificação é recusado como seria em um terminal, e nada é guardado. Onde o módulo não pode ser baixado — o espaço de trabalho está offline, seu registro não pode ser alcançado ou o registro não o contém —, a chamada é recusada sob A plugin’s .wasm is not on this machine (O .wasm de um plugin não está nesta máquina), indicando o importador, sua versão e o que coloca seu módulo na máquina.

Onde o espaço de trabalho não indica nenhuma pasta de catálogo, a importação lê o catálogo que o seu registro padrão publica. Um espaço de trabalho cujos workspace.catalog_dirs, AGGREGA_CATALOG_DIRS e raiz não indicam nenhuma pasta de catálogo lê o catálogo da biblioteca padrão como um único snapshot assinado, em catalog/snapshot no registro padrão do espaço de trabalho servido — o mesmo registro do qual um importador do núcleo é obtido, acessado nas mesmas condições, sem que nada na chamada indique um registro ou carregue uma credencial. Um snapshot é obtido uma única vez: sua assinatura é verificada segundo a política de confiança desse registro, e ele é guardado no cache de conteúdo do espaço de trabalho e lido ali como uma pasta de catálogo, vinculado ao seu digest, sem que nenhum registro seja consultado de novo. Qual snapshot uma chamada lê: com upgrade, o mais recente; caso contrário, o que o histórico no diretório de saída indica, obtido pelo seu digest quando a máquina não o tem; caso contrário, o que o espaço de trabalho obteve por último como o mais recente; caso contrário, o mais recente. O histórico que a importação escreve indica o snapshot que ela leu, pelo seu digest, de modo que uma chamada posterior que rascunhe no mesmo diretório lê o mesmo catálogo. Offline, uma chamada que precisaria obter um snapshot é recusada indicando o que executar, e upgrade é recusado independentemente do que a máquina tenha, já que só o registro pode dizer qual snapshot é o mais recente. Um registro que não publica nenhum snapshot deixa a importação sem catálogo, e uma entrada warn em diagnostics informa isso. Um espaço de trabalho que indica uma pasta de catálogo importa com base nela e não obtém nenhum snapshot, e ali upgrade não muda nada.

Se você omitir format, o formato é reconhecido pelas assinaturas que os importadores declaram — tanto as do seu catálogo quanto as dos importadores nativos. A entidade Plugin de cada importador as registra: a sintaxe em que uma fonte é lida, os nomes de arquivo a que uma assinatura se aplica e os caminhos que a árvore analisada deve ou não deve conter. A fonte é analisada, por meio do parser que o catálogo do seu espaço de trabalho serve para uma sintaxe — ou, para uma sintaxe para a qual seu catálogo não serve nenhum parser, aquele que o próprio compilador inclui —, uma vez para cada sintaxe em que uma assinatura que se aplica ao seu nome a lê, e o formato usado é o do único importador cuja assinatura corresponde. O importador então lê a fonte por meio do mesmo parser. As assinaturas dos importadores nativos leem um arquivo como JSON ou YAML, e as que não indicam nenhum arquivo o leem como JSON — a do importador do Dify, como YAML —, de modo que reconhecer um arquivo importado sozinho o lê nos dois e não precisa de nenhum parser no catálogo do seu espaço de trabalho: o compilador inclui um parser de JSON e um de YAML, e um que seu catálogo sirva é usado no lugar dele. Um diretório é reconhecido da mesma forma sobre seus arquivos: cada assinatura é testada com os arquivos dele que seus padrões selecionam, e uma assinatura que não declara nenhum padrão não se aplica a nenhum deles. O reconhecimento lê o arquivo que você indicou — ou, de um diretório, apenas os arquivos que os padrões de uma assinatura selecionam — e nenhuma rede. Uma fonte com a qual nenhuma assinatura corresponde é recusada pedindo format e indicando os formatos que os importadores anunciam — ou, para um diretório, pedindo um de seus arquivos enviado sozinho como source ou um format cujo importador declare padrões de arquivo, indicando apenas esses formatos —, sob a condição No importer recognises the source (Nenhum importador reconhece a fonte); uma fonte com a qual correspondem assinaturas de mais de um formato é recusada indicando-os, sob a condição More than one importer recognises the source (Mais de um importador reconhece a fonte); nenhuma das duas é entregue a um importador escolhido por palpite. Envie format para indicar o formato explicitamente em qualquer um dos casos — para um diretório, um cujo importador declare padrões de arquivo, já que um diretório só é lido por meio deles. Um format vazio é recusado em vez de ser lido como se você o tivesse omitido, porque são solicitações diferentes.

Envie target para rascunhar o Manifest com base no qual a Release rascunhada é construída para um provedor. target é uma capacidade de provedor — a palavra à qual o spec.capability de uma Recipe se vincula, como compose ou helm — e é o --target de aggrega import, composto pela mesma operação, de modo que uma chamada e o comando rascunham os mesmos arquivos a partir da mesma fonte. Para cada tipo de componente e cada tipo de funcionalidade de que os rascunhos precisam — nos componentes do Aggregate rascunhado, nas conexões deles e nos subsistemas dele, nos Aggregates do catálogo que ele compõe e nas vinculações da Release rascunhada —, na ordem em que os rascunhos o declaram pela primeira vez, a importação procura no catálogo do espaço de trabalho as Recipes, ou, para um tipo de funcionalidade, as receitas de funcionalidade, que implementam o tipo e se vinculam a essa capacidade. Onde há exatamente uma — várias versões de uma contam como uma —, o Manifest mapeia o tipo para ela pelo seu nome qualificado pela capacidade, sem versão, como compose/postgres, que o primeiro pull fixa no lockfile na versão mais alta disponível. Onde há várias de nomes diferentes, ele mapeia aquela com o nome do próprio tipo, como helm/postgres para core/datastore/postgres. Onde não há nenhuma, ou há várias sem nenhuma com esse nome, o tipo fica sem mapeamento e uma entrada warn em diagnostics o indica junto com o motivo — as várias, cada uma pelo nome —, de modo que um build dos rascunhos para indicando cada instância ou vinculação dele, sob No Recipe is mapped for a component or feature instance (Nenhuma Recipe está mapeada para uma instância de componente ou de funcionalidade), até que o mapeamento seja adicionado. Onde o próprio importador rascunha o Manifest, para escolher a Recipe pela qual uma instância é renderizada ou uma receita de funcionalidade entre várias, cada mapeamento que ele escreveu e que o catálogo oferece para esse tipo e essa capacidade é mantido, qualquer outro é descartado com uma entrada warn, e os tipos que ele deixa são mapeados como acima. O Manifest é rascunhado como manifest.yaml ao lado da Release rascunhada, com o mesmo nome e a mesma versão da Release, e o spec.manifest da Release é definido com esse nome — o comentário que o importador escreveu no lugar dele é substituído, e nada mais muda na Release. Uma Release que já indica um Manifest é deixada como está, e onde a importação não rascunha nenhuma Release, o Manifest é rascunhado ao lado do Aggregate, com o nome e a versão dele, e uma entrada info diz que nada faz referência a ele. O Manifest e a Release editada são rascunhos como os outros: em written, no histórico e devolvidos sob dry_run. Um target ao qual nenhuma Recipe do catálogo se vincula é recusado antes de o importador ser executado, sob An import’s target names a capability no Recipe in the catalog binds to (O destino de uma importação indica uma capacidade à qual nenhuma Recipe do catálogo se vincula), indicando-o como você o enviou e as capacidades às quais as Recipes do catálogo se vinculam, e nada é escrito. Se você omitir target, nenhum Manifest é rascunhado — exceto sob sync, que rascunha para o destino com que a importação anterior foi enviada; um target vazio é recusado em vez de ser lido como se você o tivesse omitido.

Envie output_dir para indicar o diretório em que os rascunhos vão. Se você o omitir, eles vão para baixo da raiz do espaço de trabalho que a chamada resolveu — o lugar em que aggrega import os escreve quando você não indica nenhum destino, onde quer que você o execute, e o lugar em que aggrega/import do servidor de linguagem os escreve quando sua solicitação não indica nenhum. O destino é opcional nos três, e é indicado da mesma forma que todo caminho que você envia a este servidor. Por HTTP ele é um diretório dentro do espaço de trabalho que este servidor serve, escrito de forma relativa à sua raiz: um valor que sobe para fora da raiz, um local absoluto fora dela e um diretório que sai dela por meio de um link — incluindo um diretório ainda não criado sob um link desses — são cada um recusados indicando output_dir, e nada é lido nem escrito. Na entrada e saída padrão ele é tomado como indicado, como todo caminho ali: um valor relativo é resolvido em relação à raiz do espaço de trabalho que a chamada resolveu, e um absoluto pode indicar um diretório fora do espaço de trabalho, no qual se rascunha como aggrega import --output-dir rascunha nele. O que é escrito ali fica restrito, com seus links resolvidos, ao espaço de trabalho — ou, para um diretório que você indicou fora dele, a esse diretório —, de modo que um link dentro dele que sai dele é recusado e nada é escrito. Um output_dir vazio é recusado em vez de ser lido como se você o tivesse omitido. Na entrada e saída padrão, cli-import também leva o --output-dir do comando como seu próprio output_dir; ali, um valor relativo é resolvido na pasta em que o comando é executado: a raiz do espaço de trabalho que a chamada indica; senão, aquela com que o servidor foi iniciado; e senão, a pasta em que o servidor é executado.

Todo caminho rascunhado é verificado em relação ao diretório de saída antes que qualquer coisa seja escrita. Um caminho que sai dele é recusado indicando tanto o caminho quanto o diretório, e absolutamente nada é escrito — nem mesmo os arquivos do mesmo conjunto cujos próprios caminhos estavam corretos, porque uma importação recusada que deixasse parte de si para trás seria um resultado que ninguém pediu. Um caminho rascunhado vem do plugin importador e não de você, e é por isso que é verificado pelo mesmo motivo que um caminho que você envia.

Toda importação que rascunha algo também escreve .aggrega-import.json ao lado dos seus rascunhos: o histórico do que ela escreveu — o target com que foi enviada, quando foi enviada com um, o snapshot do catálogo que ela leu, quando leu um, e cada arquivo rascunhado e, em um Aggregate ou uma Release rascunhados, cada chave em qualquer profundidade, com um digest do texto escrito ali; qualquer outro arquivo rascunhado é registrado por inteiro. O texto de uma chave é a sua linha, as linhas do seu valor onde esse valor não é um mapping de chaves, e as linhas de comentário escritas logo acima dela na sua própria indentação. written indica o histórico junto com os rascunhos, e sob dry_run ele está entre os rascunhos devolvidos. O histórico é JSON, então nada que lê os documentos YAML do espaço de trabalho o lê.

Uma chamada nunca sobrescreve um Aggregate que já está no diretório de saída. Um Aggregate é o documento que um autor continua editando depois de rascunhado, então uma chamada em que um dos rascunhos cairia em um arquivo que se lê como um Aggregate é recusada, indicando o rascunho e o diretório, e absolutamente nada é escrito — também sob dry_run, já que uma execução de teste recusa o que a escrita recusa. Todo outro arquivo que já está em um caminho rascunhado é sobrescrito, e um arquivo que uma importação anterior rascunhou e que esta não rascunha é deixado onde está.

Envie sync para, em vez disso, atualizar em relação à fonte o que uma importação anterior rascunhou, alterando apenas o que a importação escreveu. Uma sincronização sem target enviado rascunha para o destino que o histórico indica, de modo que rascunha o Manifest que a importação anterior rascunhou; uma com um target enviado rascunha para ele, e o histórico passa a indicá-lo. Um destino registrado ao qual nenhuma Recipe do catálogo se vincula é recusado como um enviado, e a recusa diz que o destino é o registrado. Cada parte é avaliada de três formas — o que o histórico diz que a importação escreveu ali por último, o que está no disco e o que a fonte rascunha agora. Uma parte que a fonte deixou como a importação a escreveu por último fica exatamente como está no disco, tenha um autor a editado ou não. Uma parte que a fonte alterou é reescrita, uma parte que ela descartou é removida — um arquivo rascunhado é excluído por inteiro —, e uma parte que ela ganhou é adicionada ao lado das partes que o rascunho indica ao redor dela, cada uma apenas onde o que está no disco é o que a importação escreveu por último e não contém nada que um autor tenha adicionado. Todo o resto é preservado byte a byte: uma chave que um autor adicionou em qualquer lugar — um parâmetro, uma Feature, também sob uma instância de Component rascunhada, outro Component, o ambiente que uma Release rascunhada deixa para seu autor —, um comentário não escrito logo acima de uma chave rascunhada, e todo arquivo que o histórico não lista. O drift da resposta lista cada parte atualizada — ou, sob dry_run, cada parte que seria atualizada — na ordem em que o rascunho as indica, cada uma como change (added, removed ou changed), file, o arquivo rascunhado em que ela está, e key, as chaves que levam a ela em um Aggregate ou uma Release rascunhados, como lista, vazia onde a parte é o arquivo inteiro; a resposta em texto indica cada uma em uma linha própria com as palavras que aggrega import escreve na saída de erro padrão, <change> <key> in <file> ou <change> <file>. Um drift vazio sob dry_run diz que os rascunhos estão em dia com a fonte. Sob dry_run, os rascunhos devolvidos são os arquivos que a sincronização escreveria, com o conteúdo que lhes daria. Uma sincronização que alteraria ou removeria uma parte que um autor editou, adicionaria uma parte onde um autor já escreveu uma, ou removeria uma parte que contém algo que um autor adicionou é recusada, indicando cada uma dessas partes e o motivo, e nada é escrito; um comentário escrito logo acima de uma chave rascunhada edita essa chave. Uma sincronização sobre um Aggregate que nenhum histórico lista é recusada informando isso, assim como uma cujo histórico não pode ser lido, e uma sincronização cujo importador não conseguiu terminar não escreve nada. Uma sincronização em um diretório que não contém nenhum histórico e nada nos seus caminhos rascunhados escreve o rascunho inteiro. drift é uma lista vazia para uma chamada que não é uma sincronização.

A resposta contém source, como você a indicou; format, como a fonte foi lida; workspace_root, a raiz do espaço de trabalho que a chamada resolveu; output_dir, o diretório em relação ao qual os caminhos rascunhados são relativos; written, os arquivos que chegaram ao disco; drift, o que uma sincronização atualizou; diagnostics, uma entrada por construção que o importador não conseguiu traduzir; decisions, como o importador mapeou cada nó da fonte; e halted. output_dir é o diretório que você enviou, ou essa raiz onde você não enviou nenhum, obtido do que a importação realmente usou, e é informado também sob dry_run, em que nada é escrito, mas cada caminho rascunhado continua relativo a ele. Por HTTP, workspace_root é retido e marcado com workspace_root_withheld, porque a raiz é um lugar no host do servidor, como expõe O que uma resposta diz sobre o sistema de arquivos do servidor; output_dir é retido e marcado com output_dir_withheld onde ele é essa raiz, e caso contrário é informado pelo seu nome relativo à raiz — a forma que seus próprios caminhos têm —, de modo que para onde foram os rascunhos continua na resposta. Uma importação que o importador não conseguiu terminar ainda assim rascunha o que pôde, e volta marcada como falha contendo essa resposta inteira — halted como true, os arquivos que de fato chegaram ao disco indicados em written e, ao lado deles, os diagnósticos que indicam o que falta. É um resultado parcial que você pode manter ou descartar, não uma chamada que não fez nada.

decisions diz onde a importação deu um palpite. Ele contém uma entrada por nó da fonte que o importador mapeou, na ordem do importador: source_node, o id, o type e o params_summary do nó; candidates, cada Component do catálogo que o importador considerou para ele, como component, score, tier e signals — o que cada um dos seus sinais contribuiu, sob table, category, domain_labels, shape e name; chosen, o target que ele escolheu, o mode em que o escreveu — uma reference a um Component existente ou um draft — e o tier da escolha; rationale, o porquê; e swap_hint, como escolher de outra forma. candidates fica ausente onde o importador não considerou nenhum, chosen onde ele não fez nenhuma escolha, e rationale e swap_hint onde ele não escreveu nenhum. Todo valor é do próprio importador — como ele pontua um candidato e onde caem seus níveis são escolhas dele —, então leia uma entrada como o relato dele sobre o mapeamento. decisions está na resposta tanto sob dry_run quanto quando a importação foi interrompida, e é uma lista vazia para um importador que não informa nenhuma. A resposta em texto indica cada decisão em uma linha própria depois dos diagnósticos, com as palavras que aggrega import escreve na saída de erro padrão: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, sendo a pontuação a do melhor candidato.

dry_run faz tudo menos escrever. Cada arquivo rascunhado volta sob drafts com seu caminho, relativo a output_dir, e seu conteúdo, e nada é criado — para um cliente que mostra o resultado a você antes de ser salvo. Todo outro comportamento é o da escrita, o mesmo importador sobre a mesma fonte informando os mesmos diagnósticos, então uma fonte que a escrita recusaria também é recusada com ele. Sem ele, os arquivos estão no disco e written os indica, e drafts fica ausente em vez de repetir bytes que você pediu para serem escritos.

Os rascunhos são um ponto de partida que pertence a você e que você continua editando. Se o que eles dizem é admissível — se um socket é um dos que o produtor declara, ou se a aplicabilidade de uma Feature é satisfeita — não é decidido aqui. É isso que validate responde.

Na entrada e saída padrão, a mesma capacidade também está disponível como cli-import, que executa o comando e devolve o texto que ele imprimiu; por HTTP essa ferramenta não existe, e ali a capacidade é acessada por esta.

Publicação, assinatura e retirada

Quatro ferramentas colocam algo onde outras pessoas vão resolvê-lo. publish-entity empacota uma entidade do catálogo e a publica; publish-artifact publica um arquivo independente, como um pacote de documentação, com seus bytes opacos e sem analisar nenhum envelope de entidade; sign-artifacts assina referências já publicadas e anexa cada assinatura, deixando como está uma referência que já tem uma que a política de confiança do seu registry verifica; deprecate-artifact anexa a uma referência um marcador de retirada assinado. Leia O que um assistente pode fazer sem perguntar a você antes antes de permitir qualquer uma delas: estas são as ferramentas cujos efeitos saem da máquina.

publish-entity recebe entity, o documento a publicar, e um Plugin também precisa de plugin, o executável publicado dentro do seu manifesto. publish-artifact recebe file com o name e a tag sob os quais ele é publicado. Todo argumento de caminho aqui é absoluto ou relativo à raiz do workspace, o mesmo contrato que todas as outras ferramentas desta superfície usam, e workspace_root indica o workspace a que a chamada se refere — em um servidor acessado por entrada e saída padrão. Um servidor acessado por HTTPS recusa workspace_root e exige que cada um desses caminhos seja resolvido dentro do workspace que ele atende, como explica Um processo, um workspace. registry é o destino e tem como padrão o configurado no workspace; não enviar nenhum dos dois, sem padrão configurado, é recusado indicando o que enviar. sign-artifacts recebe references, um ou mais endereços de registry em vez de caminhos, e opcionalmente jobs, quantos deles são assinados ao mesmo tempo: se omitido, eles são assinados um após o outro, e um valor abaixo de 1 é recusado indicando o que enviar. Cada um ainda é assinado exatamente como seria sozinho, como descreve aggrega sign. deprecate-artifact recebe ou reference com severity e reason, ou from indicando um arquivo de lote — e recusa argumentos de conteúdo enviados junto com um arquivo de lote em vez de descartá-los, porque um arquivo de lote fornece os seus próprios e um argumento ignorado silenciosamente parece um que foi respeitado.

As duas ferramentas de publicação recebem dry_run, que mostra o que uma publicação enviaria sem contatar nenhum registry. Ele calcula o pacote, informa o que teria publicado e responde com beyond_this_machine false e o destino ao qual teria se dirigido em registries; publish-entity também responde com o digest que essa publicação geraria, o mesmo que aggrega push --dry-run imprime. É a forma de mostrar a alguém uma publicação proposta antes que ela se torne uma. Assinatura e retirada não têm essa forma: ambas atuam sobre algo já publicado, então não há nada para pré-visualizar.

publish-entity responde com windows_unusable_entries quando o arquivo compactado que publica contém entradas que o Windows não consegue armazenar como estão escritas — um caminho com uma parte que tem o nome de um dispositivo, como CON, AUX ou NUL, em qualquer combinação de maiúsculas e minúsculas e com qualquer extensão em seguida, ou uma parte que termina em ponto ou espaço — nomeando cada uma, primeiro o nome de arquivo do próprio documento da entidade, depois os arquivos que ele carrega. O campo fica ausente quando não há nenhuma, o que inclui uma entidade publicada apenas como seu documento. aggrega executado no Windows se recusa a descompactar uma entrada assim, então um workspace Windows não pode usar a versão; estas são as entradas sobre as quais aggrega push emite um aviso, e o texto da resposta também as nomeia. Elas não recusam nada: a chamada prossegue ou é recusada exatamente como seria sem elas, dry_run incluído.

publish-entity recebe pin_sources, que executa na entidade a etapa de pin do autor da entidade antes que ela seja empacotada, de modo que o entity.lock que a etapa grava ao lado dela faz parte do que é publicado. É a mesma etapa que a ferramenta pin executa, gravando os mesmos bytes, e ela é executada antes de qualquer recusa que avalie a entidade — então uma publicação recusada nesse ponto, por falta de uma assinatura, por exemplo, ainda deixa o lock gravado ao lado da entidade. Uma recusa sobre a própria chamada, como um workspace offline ou a falta de destino, vem primeiro e não fixa nada. Se você o omitir, pin_sources_at_push do workspace decide; se enviá-lo, ele decide em qualquer direção. Uma publicação que fixa grava dentro do workspace além de no registry, então sobre HTTP ela precisa de uma credencial com os dois scopes, e uma que tenha apenas o scope que permite publicar é recusada nomeando o outro. O resultado traz pin, no formato com que a ferramenta pin responde, quando a etapa foi executada; com dry_run a etapa informa o lock que gravaria e não grava nada. Quando a etapa não é executada, uma Recipe ou FeatureRecipe cujo entity.lock não registra nenhum pin para uma entrada que ela lê é recusada — ou uma à qual a entrada não corresponde mais — antes que qualquer coisa seja empacotada, dry_run incluído, nomeando aggrega pin, pin_sources e pin_sources_at_push. É a recusa que pull gera sobre o mesmo lock, e verificá-la baixa cada fonte remota que a entidade escreve por completo, como a etapa faria.

A assinatura é onde a credencial é gasta, e três das quatro ferramentas a fazem — a publicação de um artefato de dados não assina nada e é assinada depois por referência. identity_token fornece uma identidade sem chave para a chamada. Em um servidor acessado por entrada e saída padrão, omiti-lo faz recorrer à identidade que o próprio ambiente desse servidor carrega, e key_path seleciona em vez disso uma chave mantida offline. Por um listener nenhuma das duas é acessível: o ambiente não é lido, key_path é recusado e retirado do que essas três ferramentas anunciam, e uma chave que a configuração do workspace atendido nomeia não é alcançada — então só assina um token enviado na chamada, como explica Quais credenciais uma chamada gasta. Uma chamada assina com uma única credencial. Toda referência enviada a sign-artifacts, e toda entrada de um arquivo de lote que deprecate-artifact lê, é assinada com a mesma chave mantida ou a mesma identidade sem chave; quando a configuração do workspace atendido nomeia uma chave para o registry de uma referência e nenhuma para o de outra, ou duas chaves diferentes, a chamada não assina nada e é recusada nomeando os registries de cada lado, antes que qualquer identidade seja resolvida ou qualquer registry seja lido — envie uma chamada por credencial, ou um único key_path para todas por entrada e saída padrão. Por um listener nenhuma chave configurada é alcançada, então ali cada referência é assinada com a identidade que a chamada envia e a chamada nunca é recusada por esse motivo. A recusa é descrita em References signed together need different signing credentials (Referências assinadas juntas precisam de credenciais de assinatura diferentes). fulcio_url, rekor_url e timestamp_url substituem os endpoints sem chave que o workspace configura, em qualquer um dos transportes. Quando nenhuma identidade é resolvida, a chamada recusa e indica o que enviar — nada aqui abre um navegador ou espera por uma pessoa, porque ninguém está observando um fluxo de protocolo, e uma chamada travada seria justamente a falha silenciosa que essa recusa existe para evitar. Em publish-entity, se uma assinatura é anexada ou não segue a política do registry de destino, a menos que sign diga o contrário, e um registry que exige assinaturas recusa uma publicação não assinada não importa o que você envie: não há argumento que contorne essa recusa. Consulte aggrega sign para os dois modos de assinatura e o que cada um contata.

Cada resultado traz os fatos em vez de uma transcrição: onde o artefato foi parar, sua tag, o digest publicado — ou, para o dry run de uma entidade do catálogo, o digest que uma publicação geraria — se a tag já apontava para um conteúdo idêntico byte a byte, se uma publicação foi assinada, e seu reach. Um lote de assinatura informa cada referência assinada com o digest com que sua assinatura se compromete, na ordem em que as referências foram dadas, e um lote em que alguma referência falhou volta como uma falha que nomeia cada uma em vez de como um resultado com uma lista reduzida — um lote parcial informado como sucesso é a forma como uma recusa acaba sendo lida como aprovação. Uma descontinuação informa cada marcador com seu próprio digest, já que um marcador é anexado como referrer sem tag do artefato que ele retira e nada mais o endereça. Assinar ou retirar uma referência que nada publicou é recusado em vez de anexado a nada.

As duas partes de uma resposta

Toda ferramenta responde com um texto legível e, ao lado dele, com um resultado estruturado sempre que a operação tiver um. O texto é escrito para uma pessoa que lê a conversa. O resultado estruturado traz a mesma resposta como campos que um programa lê — um veredito, uma lista de arquivos, um diagnóstico — e uma recusa também traz um quando a operação tinha constatações em mãos ao recusar, como O que uma build recusada devolve descreve para uma build.

O resultado estruturado também traz o texto, como text_answer. O resultado estruturado de toda ferramenta tem um campo text_answer que contém o texto da resposta exatamente como o texto o traz: cada frase, em ordem, sem alterações. Assim, um cliente que entrega ao seu modelo o resultado estruturado em vez do texto, como faz o Claude Desktop, ainda lhe entrega cada frase do texto — a linha com que abre a resposta de describe-capabilities sem argumentos, a configuração em vigor que config-show informa, a frase que nomeia a pasta que uma resposta usou quando nenhum workspace foi encontrado. text_answer é escrito primeiro, antes dos campos com que a ferramenta responde, e é o texto que quem chama recebe: sobre HTTP ele nomeia cada local no host do servidor como o texto faz, como explica O que uma resposta diz sobre o sistema de arquivos do servidor. O próprio texto continua sendo a prosa que é, para os clientes que o leem, de modo que as mesmas palavras viajam duas vezes em cada resposta.

Nenhuma ferramenta é exceção, lint incluída. Nenhuma ferramenta responde com um campo próprio chamado text_answer, então o campo nunca substitui um. O resultado estruturado de lint mantém seu summary — o número de entidades verificadas e de constatações, no total e por gravidade, com os nomes que aggrega lint escreve com -o json — e traz text_answer ao lado. describe-capabilities também mantém seus próprios campos: version_summary, a linha de versão sozinha, quando não recebe argumentos, e em cada entrada do seu index um summary, o propósito dessa ferramenta em uma linha.

Nenhuma ferramenta anuncia um schema de saída. A listagem de uma ferramenta traz um schema para os argumentos que ela recebe e nenhum para seu resultado, por isso text_answer é nomeado aqui e não em um schema.

Uma resposta sem resultado estruturado é apenas seu texto. A recusa dos argumentos de uma chamada, e qualquer outra falha para a qual a operação não tinha nada estruturado a informar, volta como seu texto e nada mais, e o texto é então a única parte que um cliente pode mostrar ao seu modelo.

Quando uma chamada não é bem-sucedida

Onde a resposta chega depende de uma única coisa: se quem chama pode corrigir o problema mudando os argumentos de uma ferramenta que existe.

Tudo o que pode ser corrigido dessa forma volta como o próprio resultado da ferramenta, marcado como falha e trazendo a correção como texto — uma combinação de seletores que a ferramenta não aceita, um argumento obrigatório omitido, um argumento enviado com o tipo JSON errado, um caminho que não é resolvido, um diagnóstico do compilador. Esse é o canal mostrado a um assistente, que então lê o que deu errado e chama de novo com o argumento corrigido.

O canal de erro do protocolo é reservado para o que não tem um resultado de ferramenta em que caber: um nome de ferramenta que o servidor não atende, uma solicitação cujos parâmetros ele não consegue ler, um método que ele não implementa e uma mensagem que não é JSON válido de forma alguma. A leitura de um recurso e a renderização de um prompt também respondem ali, porque nenhum desses resultados tem um indicador de falha próprio.

O schema anunciado de uma ferramenta também declara a maioria das regras que seus argumentos precisam cumprir — quais seletores são mutuamente exclusivos, qual argumento só faz sentido junto com outro e quais são obrigatórios —, de modo que um cliente que compõe chamadas com base no schema declarado raramente precisa fazer a chamada para conhecê-las. Uma regra que o schema não declara ainda é recusada, com uma frase que a nomeia; a regra de pull de que verify não é combinado com upgrade_targets nem com pin_sources fica a cargo da recusa de propósito, pelo motivo dado em Resolvendo aquilo de que uma Release depende.

O que interrompe o servidor

Por entrada e saída padrão, fechar a conexão o interrompe. O servidor lê uma mensagem por linha e encerra de forma limpa quando sua entrada padrão chega ao fim do fluxo, então um cliente que fecha a conexão desliga o servidor. Esse é o caso comum nesse transporte, porque você nunca inicia o comando por conta própria: o cliente que o iniciou é quem o encerra, então sair do editor, ou desativar este servidor para um projeto, é como normalmente se interrompe o servidor.

Pedir ao próprio processo que pare alcança o servidor em qualquer um dos transportes. Uma interrupção de um terminal, ou uma solicitação de término de um supervisor ou de um runtime de contêineres, o desliga na primeira solicitação, esteja um cliente enviando algo ou não: ele para de aceitar mensagens, encerra o trabalho que uma chamada em andamento está fazendo e sai de forma limpa. Uma segunda solicitação encerra o processo imediatamente. Por entrada e saída padrão, portanto, uma chamada ainda em execução quando se pede ao processo que pare não termina; um listener, por outro lado, é drenado, deixando uma chamada que já está sendo respondida terminar dentro de um prazo limitado antes que o processo saia.

Um cliente também pode interromper uma única chamada sem interromper o servidor, e a forma de fazer isso depende do transporte. As chamadas são respondidas de forma concorrente, então o encerramento de uma é tratado enquanto essa chamada ainda está em execução, em vez de esperar atrás dela. Por entrada e saída padrão, um cliente informa o id da chamada; cancelar uma chamada que já foi respondida, ou uma em que o servidor não está trabalhando, não faz nada — e é isso que torna seguro enviar essa mensagem sem saber antes se a resposta já está a caminho. Sobre HTTP não há mensagem a enviar: fechar a conexão que levou a chamada a encerra. Em ambos os casos, a chamada recebe a ordem de parar — seu trabalho termina no próximo ponto em que a operação verifica, e uma operação que nunca verifica vai até o fim —, nada mais é enviado para essa chamada, todas as outras chamadas em andamento continuam e o servidor continua atendendo.

Quando usá-lo

Use aggrega mcp quando quiser que um assistente de IA ajude a criar entidades do Aggrega com base nos schemas e na referência reais — para que as sugestões dele se baseiem na estrutura exata que o compilador aceita, em vez de serem palpites. Ele se encaixa diretamente no ciclo de criação: o assistente lê o schema e a referência de um tipo, gera um esqueleto, preenche os campos que cabem à sua função e valida antes de devolver o rascunho. Consulte Escrever arquivos do Aggrega para esse ciclo.

Por entrada e saída padrão, você normalmente nunca digita aggrega mcp por conta própria. Em vez disso, você o indica uma vez na configuração MCP do seu cliente, e o cliente o inicia e o interrompe por você. Um listener é o outro caso: ali é você quem executa o processo, e ele continua em execução para quem chama sem tê-lo iniciado.

Exemplo: configuração do cliente por entrada e saída padrão

Aponte um cliente MCP para o comando com uma entrada de servidor stdio:

{
"mcpServers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

O único pré-requisito é o binário aggrega instalado no PATH do cliente. Para os caminhos de configuração de cada cliente e a solução de problemas, consulte Conectar o servidor MCP. Para obter um schema diretamente pela linha de comando sem um cliente, consulte aggrega get-schema.