aggrega mcp
Esegue un server Model Context Protocol su standard input e output, o su HTTP, per l’integrazione con assistenti IA
Sinossi
aggrega mcp [flags]Descrizione
Run Aggrega as a Model Context Protocol (MCP) server, so an AIassistant can discover and drive Aggrega operations through a structuredprotocol instead of scraping command output.
Two transports reach the same server, and --transport chooses betweenthem, with mcp.transport in the workspace configuration as the key itoverrides. The default, stdio, speaks newline-delimited JSON-RPC 2.0 overthe process's standard input and output, which is how an MCP-capableclient runs it: spawned as a subprocess, not typed by hand. http servesthe protocol over HTTP instead — one long-running process on a host,reached by callers who are not at its keyboard — on the address --listennames, or mcp.listen when the flag is absent.
An address chooses no transport. --listen given with the stdio transportis refused, whether stdio was typed, configured or left as the default,because it names where to listen for a transport that does not listen.An address mcp.listen names is left unused by a server on standard inputand output, which says so in one line on stderr, so a client can launchthis command in a directory whose configuration is written for alistener. And the http transport with no address from either is refusedbefore anything binds.
It speaks two MCP protocol revisions on both transports, 2026-07-28 and2025-06-18, so a client of either connects. In 2026-07-28 nothing issettled for the connection as a whole: every request states the protocolversion it speaks and the capabilities its sender offers, and the serverreads both from the request it is answering rather than holding anythingbetween messages. In 2025-06-18 a client settles those same facts once,by opening the connection with an initialize handshake.
Both revisions reach the same server, and a client learns the samethings about it either way. A client on 2026-07-28 calls server/discoverfor the revisions the server speaks, the capabilities it advertises —tools, resources, and prompts — and the guidance it offers a modelbefore the first call. A client on 2025-06-18 receives those samecapabilities, and that same guidance, in the reply to its handshake.
From there the client discovers the server's surface through the listmethods (tools, resources, resource templates, and prompts) and invokesit through tools/call and resources/read. The server exposes Aggregaoperations — compiling and inspecting a Release, reading catalogentities — as tools and resources an assistant can call directly.
On standard input and output, stream discipline is strict: stdout carriesonly protocol messages, one JSON object per line, so the client can parsethe stream without heuristics. Every log, warning, and diagnostic iswritten to stderr instead. The server reads one message per line andexits cleanly when stdin reaches end of stream, so a client that closesthe connection shuts the server down. A client ends one call by namingits id, and every other call carries on.
Over HTTP there is one endpoint, /mcp, accepting POST. Every message isits own request and no session of any kind is kept, so nothing a clientsends first decides how a later request is answered. Closing theconnection ends the call it carried. A request carrying an Origin headeris checked against mcp.allowed_origins, and mcp.limits bounds how largeone request body may be, how many requests are answered at once, and howmany one caller may send in a minute. A caller sending faster thanmcp.limits.requests_per_minute is answered 429, counted against thatcaller alone.
Every request to /mcp carries a credential, and which one depends onwhether a proxy in front has already checked it. By default it is abearer token the server verifies itself, against the keysmcp.authorization.issuer publishes: it must come from that issuer, namemcp.authorization.resource among its audiences, be inside its validitywindow, and be signed with an asymmetric algorithm. A request carrying notoken is answered 401 with a challenge, and so is one whose token failsany of those. A token is never accepted from the address, never forwardedanywhere, never exchanged, and never written to any log; the subject itnames is recorded and compared to nothing.
Set mcp.authorization.trusted_proxy instead and the caller is read from aheader the proxy sets rather than from a token, with its scopes from asecond header; no token is read at all in that mode, and a requestwithout the principal header is answered 401. Because that header is thenthe whole credential, it is trustworthy only where nothing else can setit: the process is refused before it binds unless mcp.listen is loopbackor a Unix socket.
The challenge names where to obtain a token. A listener publishes anOAuth protected-resource metadata document, with no credential asked for,naming the authorization server, this deployment's own address and thescopes that exist; it is served at /.well-known/oauth-protected-resourceand at that path followed by the endpoint path, which are the two placesa client looks. A client reads it before it can hold a token, which iswhy it is the one answer given without one. What that document publishescomes from mcp.authorization.issuer and mcp.authorization.resource, and alistener is refused before it binds unless both are set.
The issuer is an https address unless the authorization server runs onthis machine (localhost, 127.0.0.1 or ::1), and that holds in everymode: with the keys read from the issuer, with a key file, and with aproxy in front. Every client is sent to the issuer to obtain its token,so a plain http issuer on another host would carry each client'sauthorization code and token across the network unprotected, and alistener naming one is refused before it binds.
The verification keys are read from the issuer itself, by asking it whereit publishes them and fetching them from the address it names, and readagain once when a token arrives signed by a key identifier the held setdoes not carry. That address is held to the same rule as the issuer, andso is every redirect either read is answered with: a plain http addresson another host is never asked, and a token needing those keys isanswered 503 until the authorization server publishes its metadata andkeys over https. A workspace that is offline makes no such request, sothere mcp.authorization.jwks_file names a file holding those keys and alistener is refused before it binds without it.
Liveness and readiness are answered on a second address, and only there.Set mcp.health.listen and a GET of /healthz reports that the process isrunning while a GET of /readyz reports whether it can answer a call yet,each a status code with an empty body and no credential asked for. Theaddress opens before the workspace is resolved, so a supervisor sees theprocess alive while it is still deciding whether it can serve at all.Leave the key unset and no second listener exists. The endpoint itselfanswers both paths the same not-found it gives every path it does notserve, with a token and without one, so reaching this process over thenetwork is never a way to probe it.
The workspace this process serves is fixed when it starts, on eithertransport: --workspace-root names it, and AGGREGA_WORKSPACE_ROOT suppliesit when the flag is absent. The folder named is the workspace rootitself, as it is for every command: a call naming no workspace of itsown is answered there, and nothing above it is searched for a workspace,so name the folder that holds the workspace's .aggrega-config.yaml. Anamed folder that does not exist is refused, naming the flag or thevariable that supplied it and the value as it was given: a listener isrefused before it binds, while a server on standard input and outputwrites the refusal to stderr and starts all the same, answering everycall that acts in that workspace with it, so a client that showsnothing of stderr still shows the refusal. An emptyAGGREGA_WORKSPACE_ROOT is read as unset, but for one launch: a serveron standard input and output given no --workspace-root, whoseenvironment carries the AGGREGA_BUNDLE_VERSION the desktop bundle sets,was started with the desktop application's Workspace folder settingempty. It is served the same way, the refusal naming that setting, sono call naming no workspace of its own is answered in the directory itwas started in. In every other case where neither names a root, aserver on standard input and output resolves the workspace from thedirectory it was started in, while a listener is refused before itbinds unless a workspace resolves there: one reachedover HTTP serves a workspace an operator chose rather thanwhichever directory it happened to be started in. Where that directoryanchors no workspace, a call naming no workspace of its own that namesits Release or document by an absolute path is answered in the workspacethat file's folder resolves, as the same command typed at a terminal inthat directory would be.
For the same reason a call arriving over HTTP cannot name a workspace ofits own. Sending workspace_root or catalog_dirs is refused, naming theargument, and the directories searched for catalog entities beside theserved workspace are the ones that workspace itself resolves: its ownworkspace.catalog_dirs setting — or, for a Release it gives directoriesof its own under workspace.releases, that Release's — then its catalogdirectory. Overstandard input and output both arguments are honoured: the client thatlaunched the server is running on this machine.
A workspace_root such a call sends is read the same way by every tool,the tools that run a command included. An absolute one is used asgiven. A relative one is read from the root a call naming no workspaceof its own is answered in — the folder --workspace-root orAGGREGA_WORKSPACE_ROOT names, which the desktop application sets fromits Workspace folder, or, where neither names one, the workspace rootthe directory the server was started in resolves to — so a client thatcannot see where that folder sits on the machine still names a folderinside it, as quickstart-ai/1. Where there is no such root to read itfrom, a relative one is refused as a call naming none is refused, andan absolute one is answered as it always is.
Asking the process itself to stop — an interrupt from the terminal, or atermination request from a supervisor or container runtime — shuts theserver down on the first request, whether or not a client is sendinganything: it stops accepting messages, ends the work a call in progressis doing, and exits cleanly. A listener stops accepting and lets a callalready being answered finish, within a bounded budget, before theprocess exits. A second request ends the process at once.Flag
| Flag | Predefinito | Descrizione |
|---|---|---|
--listen | — | L’indirizzo su cui ascolta il trasporto HTTP, in una di due forme: host:port, oppure unix: seguito da un percorso del filesystem. Indica dove ascoltare e non sceglie alcun trasporto: viene letto con —transport http, o con mcp.transport: http nella configurazione del workspace, e se fornito con il trasporto stdio viene rifiutato. Un listener senza certificato serve in chiaro ed è consentito solo su loopback (127.0.0.1, ::1, localhost) o su un socket Unix, che è la forma assunta da un server dietro un proxy di terminazione; qualsiasi altro indirizzo richiede mcp.tls.cert_file e mcp.tls.key_file, che questo processo usa poi per terminare TLS da sé. Se impostato, sovrascrive la chiave di configurazione mcp.listen. |
--transport | — | Come si raggiunge il server: stdio parla il protocollo su standard input e output, ed è così che lo raggiunge un client che avvia questo comando come sottoprocesso; http lo serve su HTTP all’indirizzo indicato da —listen o mcp.listen, e su HTTPS dove mcp.tls indica un certificato e una chiave. Se impostato, sovrascrive la chiave di configurazione mcp.transport, il cui valore predefinito è stdio. |
Cosa fa
aggrega mcp esegue un server Model Context Protocol. Due trasporti lo raggiungono, e --transport sceglie tra i due: stdio o http, con mcp.transport nella configurazione del workspace come chiave che il flag sovrascrive, e stdio come predefinito.
Su stdio, il predefinito, comunica attraverso lo standard input e output del processo. In questa forma non è un comando da eseguire in modo interattivo — un client compatibile con MCP lo avvia come sottoprocesso e parla il protocollo su stdio; Collegare il server MCP elenca dove ciascun client conserva la voce che lo avvia. Eseguirlo trasforma la CLI in un assistente di authoring che conosce Aggrega all’interno del tuo editor o client di chat.
Su http serve invece il protocollo su HTTP: un unico processo di lunga durata su un host, raggiunto da chiamanti che non sono alla sua tastiera, in ascolto sull’indirizzo indicato da --listen, o da mcp.listen quando il flag è assente. Consulta Raggiungere il server su HTTPS per sapere come si configura quel listener e cosa accetta.
Parla due revisioni del protocollo, 2026-07-28 e 2025-06-18, quindi un client dell’una o dell’altra si connette e raggiunge le stesse superfici. Quale delle due parli una chiamata è dichiarato su quella chiamata anziché concordato una volta per tutta la connessione. Un client su 2026-07-28 invia con ogni richiesta la versione del protocollo che parla e le proprie capacità, e chiede a server/discover cosa supporta il server; un client su 2025-06-18 stabilisce queste stesse cose una volta sola, aprendo la connessione con un handshake initialize. In entrambi i casi il server non conserva nulla tra un messaggio e l’altro, quindi ciò che invii per primo non decide nulla su come si risponde a una chiamata successiva. Una richiesta che nomina una revisione che il server non parla viene rifiutata e le viene indicato quali due può chiedere, anziché ricevere una risposta come se ne avesse chiesta una delle due.
Il server espone tre superfici all’assistente connesso:
-
Prompt — due famiglie, e la differenza sta in ciò a cui ciascuna risponde. I prompt di authoring rispondono a «cosa sto scrivendo»: una persona per ruolo (sviluppatore, architetto, operazioni), più un modello mirato per entità. Ciascuno inquadra il ruolo e indirizza l’assistente verso lo schema, la pagina di riferimento e la guida di authoring giusti, così che i suoi suggerimenti restino entro i pilastri di cui quel ruolo è responsabile. I prompt di workflow rispondono a «quali chiamate, in che ordine»: ciascuno espone la sequenza ordinata di chiamate agli strumenti che raggiunge un obiettivo che abbraccia diverse operazioni, con i punti di decisione tra di esse — comporre da zero un nuovo Aggregate e la sua Release, portare in Aggrega un chart, un modulo di infrastruttura o un file container-compose esistente, capire perché una build non compila o renderizza gli artefatti sbagliati.
prompts/listenumera entrambe le famiglie eprompts/getne renderizza uno, quindi l’insieme si legge dal server anziché da questa pagina.Un prompt di workflow nomina le chiamate e sei tu a farle, una alla volta, leggendo ogni risultato prima del successivo. Non esiste una chiamata che realizzi un intero obiettivo: ogni strumento racchiude un’operazione che puoi verificare, quindi è la sequenza a portarti a destinazione. Le persona di authoring accettano un
kindfacoltativo su cui concentrarsi, il modello per entità ne richiede uno, e unkinda cui nessuno schema corrisponde viene rifiutato con l’elenco dei valori accettati anziché essere ignorato silenziosamente. -
Risorse — materiale di riferimento in sola lettura servito inline:
schema://<kind>per il JSON Schema di un’entità,langref://<path>per qualsiasi pagina del riferimento del linguaggio,authoring://<topic>per la guida di authoring,catalog://<kind>/<name>per lo YAML scritto di un’entità del catalogo, ecli://<command>per l’help di un comando, concli://da solo come punto di ingresso — quell’help viene fornito a partire dai comandi che il server stesso contiene, quindi leggerne uno non avvia alcun processo e restituisce lo stesso testo che il comando stampa per--help. Una letturacatalog://di un’entità che il catalogo non contiene riceve come risposta che l’entità non è stata trovata; quando ciò accade perché esattamente un file del catalogo che dichiara l’entità è stato saltato al caricamento, il messaggio della risposta indica quel file, il vincolo che viola e il codice breve della condizione anziché solo l’URI — il rifiuto con cuiaggrega buildapre per lo stesso file.resources/listenumera quelle indirizzabili senza parametro eresources/templates/listpubblicizza la forma dell’URI di ogni famiglia. -
Strumenti — azioni sul tuo workspace, e
tools/listrisponde con tutti.Gli strumenti che un assistente incontra per primi sono pensati per il ciclo di authoring:
list-entitieselist-releasesper scoprire cosa contiene il workspace,scaffoldper uno scheletro che porta i campi richiesti dal suo kind, con un segnaposto ovunque sia dovuto un valore — oppure, se riceveexample, per scrivere uno degli esempi eseguibili della documentazione in una nuova directory, rispondendo con la posizione di quella directory, i file scritti e i comandi per compilarlo, e, se ricevelist: true, per elencare gli esempi —get-schemaper il JSON Schema di un’entità,validateper convalidare una bozza (nomina ogni segnaposto che la bozza contiene ancora, e cosa accetta ciascuno),describeper descrivere un’entità del catalogo — o un’entità letta dal suo registry per riferimento —pullper risolvere le dipendenze di una Release nella cache locale e scriverne il lockfile,buildper compilare una Release nei suoi artefatti renderizzati — in memoria per impostazione predefinita, senza alcun artefatto scritto su disco, oppure scritti indist/nella radice del workspace, dove li scriveaggrega build, quando inviiwrite(e le dipendenze vengono risolte prima solo se inviiauto_pull),gen-catalogper generare entità Plugin da guest Wasm, eexplain-errorper espandere una diagnostica del compilatore in indicazioni operative — inclusa, dove la diagnostica si apre con il codice breve di una condizione di arresto, quella condizione e la guida pubblicata alla correzione da apportare, la stessa espansione cheaggrega explainfornisce per lo stesso codice in un terminale.Il resto della superficie è nella stessa risposta anziché dietro di essa: ulteriori strumenti che vengono eseguiti all’interno del server —
lint, lo strumento che nomina la connessione scritta in un punto di un documento, i due strumenti di candidatura, gli strumenti del contenitore di allegati e del punto di inserimento, lo strumento che applica una modifica delimitata a un documento,pin, che registra i pin di contenuto per gli input di un’entità come descrive Fissare gli input propri di un’entità, e i quattro strumenti di pubblicazione descritti più avanti, più gli inventari delle cache e dei registry configurati — e, per un client che ha avviato questo server sul proprio standard input e output, uno strumento per ogni comando che potresti altrimenti digitare, chiamato secondo il suo percorso di invocazione. Questi strumenti di comando esistono solo su quel trasporto: un server raggiunto su HTTP non ne offre nessuno, per il motivo spiegato in Raggiungere il server su HTTPS. Nulla viene trattenuto per una chiamata successiva. Quanta parte di un elenco di strumenti mettere davanti a un modello è una decisione che spetta al client — recupera le definizioni e sceglie cosa caricare — e una definizione che un client non ha mai ricevuto è un’operazione che un modello non può mai chiamare, per quanto raggiungibile sia il nome di quello strumento sul wire. Dove l’elenco completo supera ciò che il tuo client accetta, Restringere ciò che il server annuncia è il modo per accorciarlo.describe-capabilitiesrestringe quella superficie al kind di entità che stai scrivendo. Se riceve unkind, risponde con gli strumenti che servono quel kind, letti dai kind che ogni strumento dichiara anziché dalle parole di una descrizione; senza argomenti, risponde con lo stesso indice su ogni strumento che questo server ti offre — il nome di ciascuno, uno scopo in una riga, i kind che serve e se scrive, senza schemi degli argomenti, così l’intera superficie arriva in un’unica risposta leggibile. Per uno strumentocli-, se scrive dipende da se scrive il comando che esegue:cli-buildviene riportato come strumento che scrive, perché il comando salva gli artefatti renderizzati sotto la radice del workspace, e così anchecli-scaffold, perché, se riceveexample, il comando scrive uno degli esempi eseguibili della documentazione in una nuova directory, mentre un comando che si limita a leggere viene riportato come di sola lettura, anche dove lungo il percorso riempie una cache condivisa da tutti i progetti sulla macchina, come lo strumento che esegue la stessa operazione all’interno del server; se ricevetoolsche ne nomina uno o più, risponde esattamente con le definizioni complete e gli schemi degli argomenti di quegli strumenti. Gli strumenticli-non vengono mai ristretti per kind, perché nulla registra quale kind di entità serve un comando, quindi una risposta limitata a un kind li esclude e l’indice senza argomenti è dove leggerli. Gli argomenti di uno strumento di comando prendono il nome dai flag del comando stesso, quindi--output-dirviene inviato comeoutput_dir, e un nome non riconosciuto viene rifiutato con l’elenco delle grafie accettate anziché essere scartato silenziosamente.Alcune capacità sono presenti due volte su standard input e output: uno strumento pensato per il ciclo di authoring esegue l’operazione all’interno del server, e lo strumento che prende il nome dal comando che offre la stessa capacità esegue quel comando. I due non si comportano allo stesso modo, quindi su quel trasporto ciascuno nomina l’altro e ne indica la differenza; su HTTP gli strumenti di comando sono assenti, e la frase di abbinamento viene omessa anziché indicare uno strumento che il chiamante non può raggiungere. Quello eseguito all’interno del server è quello da preferire — risponde con un risultato leggibile dalla macchina accanto al testo leggibile, così un assistente ottiene un verdetto, un elenco di file o una diagnostica come campi anziché come trascrizione da analizzare. Lo strumento di comando avvia il comando reale in un processo separato, quindi fa tutto ciò che quel comando fa sulla macchina su cui gira, inclusa la scrittura su disco dove il comando scrive —
cli-buildscrive gli artefatti renderizzati indist/nella radice del workspace, e i file di una build tracciata in.trace/accanto a essa, e la riga finale che restituisce nomina quella directory per intero — e restituisce solo la riga di comando che ha eseguito e il testo che quel comando ha stampato. Usalo quando ti serve un flag che il comando dichiara e che l’altro strumento non accetta.Quella riga di comando si apre con i flag globali con cui questo server è stato avviato e che decidono la configurazione —
--confige--offline, dove li hai forniti — prima del comando e dei flag propri della chiamata. Così il comando legge la configurazione che legge ogni altro strumento qui: un server avviato con--offlineesegue i suoi comandi offline, e uno avviato con--configli esegue su quel file globale. Un flag che la chiamata invia per sé viene dopo di essi e prevale, quindioffline: falsesu una chiamata raggiunge la rete solo per quella chiamata, e la riga di comando restituita mostra entrambi. Dove il server è stato avviato con una radice del workspace — tramite--workspace-rooto tramiteAGGREGA_WORKSPACE_ROOT— la riga di comando si apre con quella radice come--workspace-root, prima di quei due, così il comando prende quella directory come radice del workspace, come farebbe se digitato con lo stesso flag e come la prende ogni strumento eseguito all’interno del server, anziché trovare il proprio workspace a partire dalla directory in cui il server è stato avviato. Una chiamata che inviaworkspace_rootnomina la propria, e la riga di comando porta solo quella — incluso un valore vuoto, che il comando legge come legge--workspace-root ""in un terminale: trovare il workspace a partire dalla directory in cui il server è stato avviato. Un server avviato senza nessuno dei due non passa alcuna radice, quindi i suoi comandi trovano il workspace a partire da quella directory, secondo la regola che In quale workspace riceve risposta una chiamata stabilisce per ogni strumento — salvo l’avvio del bundle desktop con l’impostazione Workspace folder vuota, nel quale una chiamata che non nomina un proprio workspace non avvia alcun comando e riceve come risposta il rifiuto di quell’impostazione. Il comando parte nella radice del workspace indicata dalla chiamata o dall’avvio: ilworkspace_rootdella chiamata stessa, letto come lo legge ogni strumento — uno assoluto così come è stato inviato, uno relativo a partire dalla radice in cui riceve risposta una chiamata che non ne nomina alcuno — e passato al comando nella sua forma assoluta, altrimenti la radice con cui il server è stato avviato. Così un percorso relativo che una chiamata passa come file da leggere — un documento da sottoporre avalidate, un--releaseo un--catalog— viene letto all’interno di quel workspace, come in un terminale aperto lì, e una build eseguita dal comando scrivedist/sotto quella radice. Dove nulla indica una radice — nessuna radice di avvio, e nessunworkspace_rooto uno vuoto — il comando parte nella directory in cui il server è stato avviato e legge un percorso relativo da lì; unworkspace_rootche non nomina alcuna cartella esistente viene passato così come è stato letto — uno assoluto così come è stato inviato, uno relativo nella sua forma completa — e il comando lo rifiuta con parole proprie. Un comando registrato da un plugin di estensione dei comandi non riceve nessuno di essi, perché passa ogni argomento al plugin senza leggerlo anziché analizzare un flag globale, in un terminale come qui; parte nella stessa cartella di ogni altro comando.Alcuni comandi sono deliberatamente assenti anche su standard input e output, dove gli strumenti di comando esistono — su HTTP sono assenti tutti, e questa è una proprietà del trasporto anziché di un comando. Su standard input e output, ciascuno di questi è escluso per un motivo dichiarato: il daemon e questo stesso server non restituirebbero mai un risultato; un comando che legge una password dal terminale non ha da dove leggerla; uno che scrive uno script di completamento della shell non ha alcuna shell in cui installarlo; rimuovere una credenziale memorizzata agisce sull’archivio dell’intera macchina anziché su un workspace che hai nominato; e acquisire un token di identità in modo interattivo non ha alcuna forma non interattiva da offrire. Assente per lo stesso motivo legato all’intera macchina è
aggrega plugin run-local, che carica un guest.wasmda un percorso che gli fornisci: ciò a cui serve il comando è leggere un file ovunque tu lo metta, quindi non c’è alcun workspace a cui possa essere confinato, e la lettura avviene nel processo stesso prima che il guest esista. Al guest non viene concesso nulla quando viene eseguito — nessuna directory, nessun socket, nessun ambiente — ma questo è un limite sul modulo anziché sulla lettura, quindi non è ciò che decide la questione. Eseguilo nel tuo terminale, dove sei tu a nominare il percorso. La firma e la pubblicazione sono un caso del tutto diverso, ed è questa differenza a tenerle fuori da quell’elenco. Ciascuna risolve un’identità da un input fornito o dall’ambiente e rifiuta esplicitamente quando nessuna è disponibile, quindi ciascuna ha una forma che si completa senza che nessuno guardi — mentre acquisire un token in modo interattivo è un verbo che nessun input può soddisfare, nemmeno in linea di principio. Quindi sono presenti due volte: come comandi, e come i quattro strumenti in-process descritti in Pubblicare, firmare e ritirare. Dove la riga di comando aprirebbe un browser, rifiutano e nominano cosa fornire invece, anziché attendere una persona che non c’è.
In quale workspace riceve risposta una chiamata
Una chiamata nomina il proprio workspace con workspace_root; altrimenti riceve risposta nel workspace su cui il server è stato avviato. Dove l’avvio ha nominato una radice, con --workspace-root o AGGREGA_WORKSPACE_ROOT, quella radice è la radice del workspace stessa, come lo è il flag su ogni comando: al di sopra di essa non si cerca alcun workspace che la racchiuda, quindi un avvio nomina la cartella che contiene il .aggrega-config.yaml del workspace, e una chiamata riceve risposta lì sia dagli strumenti eseguiti all’interno del server sia dagli strumenti di comando. Dove l’avvio non ne ha nominata nessuna, il workspace viene trovato a partire dalla directory in cui il server è stato avviato, esattamente come lo individua un comando digitato in un terminale lì — l’ordine è descritto in Gli altri modi in cui viene riconosciuta la radice di un progetto — tranne nell’avvio del bundle desktop con l’impostazione Workspace folder vuota, che invece rifiuta una tale chiamata, come descritto più avanti. Un workspace_root relativo viene letto a partire dalla radice in cui riceve risposta una chiamata che non ne nomina alcuno — la radice nominata dall’avvio o, dove non ne ha nominata nessuna, la radice del workspace a cui si risolve la directory in cui il server è stato avviato — così una chiamata nomina una cartella all’interno del workspace, come quickstart-ai/1, senza sapere dove si trovi il workspace sulla macchina; uno assoluto viene usato così come è dato. Ogni strumento lo legge così, compresi gli strumenti di comando. Dove non c’è alcuna radice da cui leggere uno relativo — una radice di avvio che non è una cartella esistente, o l’avvio desktop con Workspace folder vuoto — uno relativo viene rifiutato come lo è una chiamata che non ne nomina alcuno. Un workspace_root che non nomina alcuna cartella esistente, o che nomina un file, viene rifiutato prima che lo strumento faccia qualsiasi altra cosa, nominando l’argomento e citando il valore — uno assoluto così come è stato inviato, uno relativo nella forma completa in cui è stato letto — come un comando rifiuta --workspace-root.
Una radice di avvio che non è una cartella esistente viene servita come rifiuto su standard input e output. Dove --workspace-root o AGGREGA_WORKSPACE_ROOT nomina una cartella che non esiste, o nomina un file, il server scrive il rifiuto nel proprio flusso di errore e si avvia comunque, così un client che non mostra al proprio utente nulla di quel flusso mostra comunque il perché. Risponde a initialize e ai propri elenchi di strumenti, risorse e prompt, e ogni chiamata che agirebbe in quel workspace riceve come risposta il rifiuto: una chiamata a uno strumento come risultato di errore, una lettura di un’entità catalog:// o di una pagina della documentazione come errore. Il rifiuto nomina il flag, oppure la variabile insieme all’impostazione Workspace folder dell’applicazione desktop che la imposta — l’impostazione descritta in Claude Desktop — e cita il valore esattamente come è stato fornito; un valore che il client ha inviato senza compilarlo viene citato così come è arrivato, e nulla al suo interno viene interpretato. Uno strumento che esegue un comando non ne avvia alcuno per una chiamata che non nomina un proprio workspace, poiché la cartella in cui quel comando partirebbe non c’è, e risponde con lo stesso rifiuto. Una chiamata che nomina un proprio workspace tramite un percorso assoluto riceve risposta lì; una che lo nomina tramite un percorso relativo non ha alcuna cartella da cui leggerlo, e riceve come risposta lo stesso rifiuto. Ciò che non agisce in alcun workspace — uno schema, un prompt, l’help di un comando — riceve risposta come su qualsiasi server. Un listener viene invece rifiutato all’avvio, prima che si effettui qualsiasi binding, con lo stesso rifiuto, così chi lo supervisiona legge l’errore dove lo cerca.
Un avvio desktop con l’impostazione Workspace folder vuota viene servito come rifiuto allo stesso modo. Il bundle desktop passa sempre al server AGGREGA_WORKSPACE_ROOT, con qualunque valore contenga Workspace folder, e imposta accanto AGGREGA_BUNDLE_VERSION, mentre l’applicazione avvia il server in una cartella di sua scelta — spesso una cartella di sistema — anziché nel tuo progetto. Così un server su standard input e output avviato senza --workspace-root, il cui ambiente porta AGGREGA_BUNDLE_VERSION e un AGGREGA_WORKSPACE_ROOT vuoto o assente, non cerca un workspace a partire dalla cartella in cui è stato avviato. Scrive il rifiuto nel proprio flusso di errore e si avvia comunque, rispondendo come fa con una radice di avvio che non esiste: ogni chiamata che agirebbe in un workspace e non ne nomina uno proprio riceve come risposta un rifiuto che dice che l’applicazione desktop ha avviato il server con l’impostazione Workspace folder vuota, quindi AGGREGA_WORKSPACE_ROOT non nomina alcuna radice del workspace, ti dice di impostare Workspace folder sulla cartella che contiene il .aggrega-config.yaml del tuo workspace e precisa che una cartella impostata dopo l’avvio del server ha effetto una volta che l’estensione viene disattivata e riattivata o l’applicazione viene riavviata, perché l’applicazione passa l’impostazione al server solo quando lo avvia. Uno strumento che esegue un comando non ne avvia alcuno per una tale chiamata. Una chiamata che nomina un proprio workspace tramite un percorso assoluto riceve risposta lì, e una che lo nomina tramite un percorso relativo riceve come risposta lo stesso rifiuto, poiché non c’è alcun Workspace folder da cui leggerlo; ciò che non agisce in alcun workspace riceve risposta come su qualsiasi server. Il server riconosce l’avvio solo da AGGREGA_BUNDLE_VERSION: un bundle che non imposta tale variabile ha un’impostazione vuota letta come nessuna radice, e un avvio che imposta la variabile a mano e non nomina alcuna radice viene rifiutato come quello del bundle. Ogni altro valore vuoto continua a non nominare alcuna radice — un AGGREGA_WORKSPACE_ROOT vuoto su un avvio che non porta alcun AGGREGA_BUNDLE_VERSION, un --workspace-root digitato vuoto, un listener, aggrega serve e ogni altro comando lo leggono ciascuno come non impostato.
Dove nessun workspace è stato trovato e nessuno è stato nominato, una risposta che riguarda il workspace dice quale cartella ha usato. Senza radice di avvio, senza workspace_root nella chiamata e senza nulla che ancori un workspace a partire dalla cartella in cui la chiamata ha ricevuto risposta, la chiamata riceve risposta in quella cartella. Dove il risultato dello strumento dipende dal workspace — gli stessi strumenti i cui comandi emettono un avviso sulla riga di comando — il suo testo termina con l’avviso della riga di comando, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, e con una riga che ti dice di inviare workspace_root indicando la cartella che contiene il .aggrega-config.yaml del tuo workspace; una risposta che il workspace non determina, come la lettura della configurazione o l’elenco dei plugin, non dice nulla sui workspace. La frase non aggiunge alcun campo proprio al risultato strutturato; il risultato strutturato la riporta in text_answer, che contiene il testo, come descritto in Le due parti di una risposta. Uno strumento che esegue un comando in un processo separato riporta la riga del comando stesso che dice la stessa cosa, così come il comando l’ha stampata. Nulla viene scritto in una cache di artefatti in una tale cartella: un pull, o una build a cui si chiede di risolvere prima le proprie dipendenze, viene lì rifiutato prima che si scarichi qualsiasi cosa, nominando la cartella e le due soluzioni — inviare workspace_root, oppure dare alla cartella un .aggrega-config.yaml con un blocco workspace:. Un pin, o una pubblicazione di una Recipe o di una FeatureRecipe, viene rifiutato allo stesso modo dove scaricherebbe una sorgente remota che l’entità scrive per intero — per fissarla, o per confrontarne il pin — prima che quella sorgente venga scaricata; dove non ne scarica alcuna, perché l’entità non ha sorgente, ne ha una locale o una le cui coordinate vengono fornite da ogni Release, riceve risposta come altrove. Una build lì che non risolve nulla prima viene comunque renderizzata, ma un input esterno che il suo lockfile fissa e che la cache non contiene più non viene scaricato di nuovo: al render viene comunicata quella stessa frase al posto dell’input, come gli viene comunicata quella di una modalità offline. Nessuna risposta su HTTP porta la frase: un listener serve sempre un workspace che gli è stato dato o che ha trovato. Né la porta l’avvio del bundle desktop con l’impostazione Workspace folder vuota, che rifiuta una chiamata che non nomina un proprio workspace anziché risponderle nella cartella in cui è stato avviato.
Una chiamata su una Release o su un documento che nomina con un percorso assoluto riceve risposta nel workspace proprio di quel file quando nient’altro ne ha stabilito uno. Dove l’avvio non ha nominato alcuna radice, la chiamata non invia alcun workspace_root e la directory in cui il server è stato avviato non fa da ancora per alcun workspace, il workspace viene individuato di nuovo a partire dalla cartella in cui si trova quel file, e qualunque cosa trovi — il progetto a cui il file appartiene o, in mancanza di tutto, quella cartella — è quello in cui la chiamata riceve risposta. È la regola che segue un comando digitato in un terminale, quindi vale per ogni strumento la cui chiamata riguarda una Release o un documento di entità che nomina: una build, un pull, una convalida, un lint, una descrizione, un elenco nei termini di una Release, una domanda su un nodo del grafo di una Release, un pin, la pubblicazione di un’entità, una modifica e una posizione letta in un documento. Dove una chiamata nomina sia una Release sia un documento, decide la Release. Così un client che ha avviato il server fuori dal tuo progetto vede comunque una Release al suo interno compilata con la configurazione del progetto stesso. Gli altri percorsi che la chiamata nomina vengono letti come sempre — uno relativo a partire dalla directory in cui il server è stato avviato — e uno strumento che esegue un comando in un processo separato riceve risposta dallo stesso workspace, perché il comando segue la stessa regola in quella stessa directory. Una radice nominata dall’avvio, un workspace_root inviato dalla chiamata, una directory di partenza che si trova essa stessa all’interno di un workspace e una Release o un documento nominati con un percorso relativo vengono usati così come sono. Su HTTP nulla di tutto ciò si presenta: un listener serve sempre un workspace che gli è stato dato o che ha trovato, e ogni percorso nominato da una chiamata è relativo a esso. Né si presenta nell’avvio del bundle desktop con l’impostazione Workspace folder vuota, che rifiuta una chiamata che non nomina un proprio workspace, qualunque file essa nomini.
Restringere ciò che il server annuncia
mcp.announce_tools elenca i tool che questo server annuncia, scritti esattamente come li riporta l’elenco dei tool. Se ometti la chiave viene annunciato ogni tool di cui il server dispone, che è il valore predefinito e la forma che si aspetta un client che segue il protocollo. Se scrivi un elenco vengono annunciati esattamente quei tool: uno escluso è assente dall’elenco dei tool, assente da ciò che risponde describe-capabilities e rifiutato se viene comunque chiamato per nome, con un rifiuto che cita questa impostazione. Se scrivi un elenco vuoto non viene annunciato nulla — quindi omettere la chiave e scrivere [] sono affermazioni diverse, e l’impostazione non ha un valore predefinito compilato al posto tuo.
Impostala dove il client all’altro capo limita il numero di tool che registrerà, a volte sommando tutti i server a cui è connesso contemporaneamente, e indica i tool di cui quel client ha bisogno. Quel limite è il caso per cui l’impostazione esiste, e il client a cui si applica è di solito quello che ha avviato questo server sul proprio standard input e output — quindi, a differenza del resto del blocco mcp, che configura il listener avviato dal trasporto http, questa chiave viene letta qualunque sia il trasporto usato dal server.
Restringe ciò che viene annunciato e nient’altro. Indicare qui un tool non allarga nulla. Non scavalca mcp.deny_reach, che revoca del tutto una capacità, quindi un tool indicato qui di un tipo che quell’impostazione revoca resta fuori dall’elenco e viene rifiutato citando quell’impostazione. Né scavalca gli scope del token di un chiamante: un tool indicato qui compare nell’elenco quali che siano quegli scope, e una chiamata che essi non ammettono viene comunque rifiutata, citando lo scope che la ammetterebbe. In entrambi i casi il rifiuto che il chiamante riceve è quello dell’altro limite e non di questo. Un rifiuto dovuto a questa impostazione non porta alcuna challenge e non cita alcuno scope, perché nessuna credenziale cambia ciò che un server ha scelto di offrire — ciò che cita invece è l’impostazione, che è l’unica cosa su cui chi legge il rifiuto può intervenire.
Ogni nome deve essere uno di quelli presenti in questo binario. Un nome a cui non risponde alcun tool arresta il server prima che serva qualsiasi cosa, e il rifiuto elenca i tool che possiede — così un errore di battitura emerge all’avvio anziché attraverso una superficie silenziosamente più ristretta di quella richiesta. Un nome della famiglia cli-, che esegue un comando aggrega in un processo separato, è accettato su entrambi i trasporti e su HTTP non annuncia nulla, perché lì nessun tool di questo tipo viene offerto ad alcun chiamante.
L’insieme annunciato è fissato all’avvio del processo, quindi modificarlo richiede un riavvio e nulla fa crescere l’elenco sotto un client già connesso.
Da quale release proviene il server
describe-capabilities inviato senza argomenti indica da quale release proviene questo server. La sua risposta strutturata contiene server_version, la versione che l’eseguibile aggrega riporta per sé stesso — quella che aggrega version stampa per lo stesso file — e il suo testo si apre con una riga che la indica, prima dell’indice. La risposta strutturata contiene la stessa riga come version_summary, parola per parola, così un client che passa a un modello solo la risposta strutturata gli passa anche la riga.
Se il server è stato avviato dal bundle desktop, la stessa risposta indica accanto anche la versione del bundle. Il bundle non contiene alcun programma: avvia l’eseguibile aggrega indicato dalla sua impostazione Path to the aggrega executable — per impostazione predefinita il nome di comando aggrega, che l’applicazione cerca nel proprio PATH — quindi bundle ed eseguibile si installano separatamente e possono provenire da release diverse, e l’applicazione che elenca il bundle mostra solo la versione del bundle stesso. Il bundle passa al server la propria versione come AGGREGA_BUNDLE_VERSION nel suo ambiente; il server la legge una volta, all’avvio, e la risposta la riporta come bundle_version. Le due versioni si confrontano esattamente come sono scritte, e il confronto è corretto perché il bundle e l’eseguibile di una stessa release sono marcati con la versione di quella release nella stessa forma, mentre una build di sviluppo si legge diversamente da ogni release. Se coincidono, la riga le indica entrambe e non aggiunge altro. Se differiscono, la riga dice, indicandole entrambe, che l’eseguibile e il bundle provengono da release diverse, e le indicazioni che il server offre a un modello quando si connette si aprono con la stessa frase, così la differenza è davanti al modello prima che chieda.
Un server non avviato da un bundle riporta solo la propria versione. Avviato da un terminale, dalla configurazione di un editor o come listener, non contiene bundle_version, a meno che qualcosa non imposti la variabile nel suo ambiente. Un server su standard input e output che ha la variabile viene considerato avviato dal bundle anche sotto un altro aspetto: se non gli è stata indicata alcuna radice, rifiuta l’impostazione Workspace folder vuota, come spiega In quale workspace riceve risposta una chiamata. Una chiamata a describe-capabilities inviata con kind o tools non contiene server_version, bundle_version né version_summary né quella riga, perché risponde sui tool e non sul server.
Una differenza viene segnalata e mai rifiutata. Il server si avvia e risponde a ogni chiamata esattamente come farebbe con le due versioni allineate. Cosa comporta una differenza per un’installazione desktop, e come riallineare le due, è spiegato in Collegare il server MCP.
Raggiungere il server via HTTPS
aggrega mcp --transport http serve il protocollo su HTTP anziché su standard input e output. mcp.transport nella configurazione del workspace è la chiave che quel flag sovrascrive, e il suo valore predefinito, stdio, è ciò che si aspetta un client che avvia il comando — quindi un server raggiunto da altre persone ha transport: http nella propria configurazione, e un client avviato da una directory coperta da quella configurazione raggiunge comunque il server sui propri flussi. Il server è lo stesso in entrambi i casi — lo stesso workspace e le stesse superfici di protocollo — e ciò che cambia è il modo in cui un messaggio lo raggiunge, il modo in cui una chiamata termina e ciò che deve possedere chi lo esegue. Questa sezione descrive ciò che configura un operatore; la voce di cui un client ha bisogno per raggiungere un server in esecuzione è in Collegare il server MCP.
Un indirizzo non sceglie alcun trasporto. --listen <address>, oppure mcp.listen in assenza del flag, indica dove il listener si mette in ascolto una volta scelto http, e nient’altro. Quindi http senza un indirizzo da nessuno dei due viene rifiutato prima di qualsiasi bind, e il rifiuto li cita entrambi. Anche --listen digitato mentre il trasporto è stdio — digitato come --transport stdio, configurato come mcp.transport: stdio o lasciato al valore predefinito — viene rifiutato, indicando --transport http come il flag che servirebbe su quell’indirizzo; un --listen con un valore vuoto viene rifiutato perché non indica alcun indirizzo, qualunque sia il trasporto. E un indirizzo indicato solo dalla configurazione resta inutilizzato da un server che comunica sui propri flussi, che lo segnala con una riga sul proprio flusso di errore, citando il file che l’ha impostato e mcp.transport: http. Quest’ultimo caso non viene rifiutato da nessuna parte, di proposito: è l’avvio che fa un client quando lancia il comando in una directory la cui configurazione contiene le impostazioni di un listener, e una configurazione di listener che dimentica transport: http non avvia alcun listener, ed è lì che il problema si vede.
Un server raggiunto via HTTP non offre alcun tool che esegua un comando aggrega in un processo separato. Quei tool esistono solo per un client che ha avviato questo server sul suo standard input e output, sulla macchina di quel client, dove indicare una cartella o un flag non concede al chiamante nulla che non avesse già. Un chiamante che raggiunge il server via HTTP non possiede l’host su cui gira, quindi un comando che agirebbe sul filesystem di quell’host con l’autorità del server va eseguito invece da un terminale sull’host. I tool sono assenti dall’elenco e da describe-capabilities anziché essere offerti e poi rifiutati, e una chiamata che ne indica uno riceve un errore che lo dice. È una proprietà del trasporto, non un’impostazione: non esiste configurazione che li ripristini.
Leggi Nulla viene servito senza una credenziale prima di distribuirne uno. Ogni richiesta all’endpoint porta una credenziale, e non esiste impostazione che serva una richiesta che ne è priva — ciò che un’impostazione sceglie è se questo server verifica da sé un bearer token o legge un chiamante che un proxy posto davanti ha già verificato.
Le due forme di distribuzione
Il processo termina TLS da sé. Imposta mcp.tls.cert_file su una catena di certificati PEM e mcp.tls.key_file sulla relativa chiave privata, e il listener serve HTTPS direttamente su qualunque indirizzo tu gli abbia dato. Entrambi i file vengono letti all’avvio del processo, quindi un certificato sostituito viene recepito riavviando il processo. Impostarne uno senza l’altro viene rifiutato all’avvio anziché ripiegare su altro: un certificato senza chiave non può essere presentato, una chiave senza certificato non identifica nulla, e un errore di battitura in un percorso non è un motivo per iniziare a servire traffico non cifrato.
Un proxy posto davanti termina TLS e inoltra a un listener confinato. Lascia entrambe le chiavi non impostate e il listener serve in chiaro, cosa accettata solo su loopback o su un socket Unix — così nulla che non sia già su quell’host può raggiungerlo. È la forma usata da un reverse proxy, da un sidecar o da una service mesh, ed è quella in cui il certificato sta davanti a questo processo anziché al suo interno.
Un listener in chiaro su qualsiasi altro indirizzo viene rifiutato prima di qualsiasi bind, e il rifiuto cita entrambe le chiavi TLS. Non esiste impostazione che lo consenta né indirizzo che faccia eccezione: un listener che accetta connessioni dalla rete senza un certificato proprio non è mai sicuro, quindi il processo si rifiuta di avviarsi anziché avviarsi in quella forma.
Le forme di indirizzo
--listen e mcp.listen accettano una di due forme:
host:port— un indirizzo TCP, come127.0.0.1:7777o0.0.0.0:8443. Loopback significa127.0.0.1,::1, oppurelocalhostquando ogni indirizzo in cui quel nome si risolve è un indirizzo di loopback. Qualsiasi altra cosa è un indirizzo di rete e richiede un certificato: un host vuoto, che corrisponde a tutte le interfacce della macchina; l’indirizzo di un’interfaccia specifica; e qualsiasi altro nome, anche uno che in questo momento si risolve in un indirizzo di loopback, perché dove un listener può mettersi in ascolto non dovrebbe dipendere da una risoluzione che può cambiare sotto di lui.unix:seguito da un percorso del filesystem — un socket di dominio Unix, comeunix:/run/aggrega/mcp.sock. Un socket è raggiungibile solo dall’host su cui si trova, quindi non richiede alcun certificato.
Un percorso di socket viene preso esattamente come è scritto, anche se relativo. Di proposito non viene risolto rispetto al file di configurazione che lo ha dichiarato, perché lo stesso indirizzo arriva anche da --listen, che non ha alcun file dichiarante — vedi dove punta un percorso relativo.
Cosa accetta il listener
Un solo endpoint, /mcp, che accetta POST. Ogni messaggio JSON-RPC è una richiesta a sé e non viene mantenuta alcuna sessione di alcun tipo: nulla di ciò che un client invia per primo decide come si risponderà a una richiesta successiva, nessun identificatore di sessione viene mai generato, e un header di sessione o di ripresa dello stream inviato da un client viene ignorato. A qualsiasi altro metodo su quell’endpoint si risponde 405 con Allow: POST, e a qualsiasi altro percorso 404 — entrambi decisi prima della verifica della credenziale, così chi sonda non apprende nulla da una challenge su un percorso o un metodo che comunque non servirebbe nulla.
A una richiesta si risponde con un oggetto JSON e un codice di stato — oppure, quando la chiamata ha segnalato l’avanzamento prima di arrivare a quell’oggetto, con uno stream di eventi che termina con esso, come spiega Sapere come procede una chiamata lunga. A una notifica — un messaggio senza id — si risponde 202 con un corpo vuoto. A un messaggio che non è né l’una né l’altra, compresa una risposta JSON-RPC, si risponde 400, perché un client invia a questo server richieste e notifiche e nient’altro.
Entrambe le revisioni del protocollo sono servite qui esattamente come su standard input e output. Una richiesta 2026-07-28 riporta il proprio corpo negli header di trasporto, così un intermediario può instradarla senza analizzare il corpo: MCP-Protocol-Version contiene la revisione dichiarata dal corpo, Mcp-Method il metodo che indica e Mcp-Name la destinazione, per i metodi che ne indirizzano una per nome. A un header in disaccordo con il corpo si risponde 400. Un client 2025-06-18 apre con un handshake initialize, a cui si risponde senza stato; può includere l’header di versione che indica quella revisione oppure ometterlo. A una richiesta che indica una revisione che il server non parla si risponde 400 elencando le due che parla, e a una che indica un metodo che non serve si risponde 404.
mcp.allowed_origins viene consultato solo quando una richiesta porta un header Origin, il che in pratica significa che l’ha inviata un browser: a una richiesta che indica un’origine non presente nell’elenco si risponde 403, e una senza tale header viene servita. Un client che non è un browser non invia tale header e non ha bisogno di alcuna voce. Uno basato su browser ha sempre bisogno di una voce: l’elenco è vuoto finché un operatore non lo scrive, quindi fino ad allora non è presente alcuna origine e a ogni richiesta del browser si risponde 403 — compresa una da una pagina servita all’indirizzo dell’endpoint stesso. La voce viene confrontata esattamente con l’header, quindi si scrive come un browser invia un’origine — uno schema in minuscolo, ://, un host in minuscolo e, se non è quella predefinita dello schema, : e la porta, come https://app.example.com — e una voce con un percorso, una / finale, senza schema o con una lettera maiuscola viene rifiutata al caricamento della configurazione, citando la voce, perché non potrebbe mai corrispondere.
mcp.limits limita il traffico accettato. A un corpo oltre max_body_bytes si risponde 413 e non viene letto oltre il limite. A una richiesta che arriva mentre sono già in corso max_concurrent_requests richieste si risponde 503 anziché metterla in coda dietro un lavoro che non può vedere. A un chiamante che invia più di requests_per_minute richieste in un minuto si risponde 429, conteggiato solo per quel chiamante, così un chiamante che invia molto non costa nulla a un altro. Il valore predefinito di ciascun limite è indicato accanto alla sua chiave nel riferimento della configurazione, e nessuno di essi ha un valore che lo disattiva.
Un processo, un workspace
Il workspace per cui risponde un processo in servizio è fissato al suo avvio. --workspace-root lo indica; la variabile AGGREGA_WORKSPACE_ROOT lo fornisce in assenza del flag. La cartella indicata è la radice stessa del workspace, senza ricerche al di sopra, e una cartella che non esiste viene rifiutata, citando quale dei due l’ha fornita e riportando il valore così come è stato dato — da un listener prima del bind, e da un server su standard input e output nella risposta a ogni chiamata che agisce in quel workspace, come spiega In quale workspace riceve risposta una chiamata — così un avvio composto da un client anziché digitato dice comunque cosa ha ricevuto. In assenza di entrambi, un server su standard input e output risolve il workspace dalla directory in cui è stato avviato — dove nulla vi ancora un workspace, ogni risposta che riguarda il workspace dice quale cartella ha usato, e l’avvio del bundle desktop con l’impostazione Workspace folder vuota rifiuta invece una chiamata che non indica un workspace proprio, come spiega In quale workspace riceve risposta una chiamata — e un listener viene rifiutato prima del bind a meno che lì non si risolva un workspace — un processo raggiunto via HTTP risponde a chiamanti che non vedono la macchina, quindi serve un workspace scelto da un operatore anziché la directory in cui si è trovato ad essere avviato. Per servire più progetti, esegui un processo per ogni radice di progetto.
Una chiamata che arriva via HTTP non può indicare un workspace proprio. workspace_root e catalog_dirs vengono rifiutati, citando l’argomento inviato, anziché essere scartati in silenzio: un argomento ignorato silenziosamente appare a chi lo invia esattamente come uno rispettato. Le directory di catalogo cercate accanto al workspace servito sono quelle dell’impostazione workspace.catalog_dirs di quel workspace — oppure, per una Release a cui assegna directory proprie sotto workspace.releases, quelle di quella Release — scritte dall’operatore. Su standard input e output entrambi gli argomenti vengono rispettati, perché il client che ha avviato il server gira sulla macchina del chiamante. Lì una voce di catalog_dirs è assoluta, oppure relativa alla radice del workspace da cui viene letta una release relativa — la radice stabilita per prima dal workspace_root della chiamata stessa, dall’avvio o dalla directory in cui il server è stato avviato, e quella da cui continua a essere letta quando una Release indicata in modo assoluto sposta la chiamata nel workspace di quella Release — e non alla directory in cui gira il server, se questa si trova altrove.
Anche un percorso indicato da una chiamata resta dentro quel workspace. Via HTTP un argomento di percorso viene risolto rispetto alla radice del workspace e rifiutato se esce da essa — un percorso relativo che risale fuori dal workspace, un percorso assoluto che indica un altro luogo e un percorso relativo che esce dal workspace attraverso un link a un file o a una directory che vi si trova tornano ciascuno come un errore che cita l’argomento, senza citare né la radice del workspace né il luogo che il percorso avrebbe raggiunto; un percorso relativo viene riportato così come l’hai inviato. Ogni argomento di percorso viene giudicato in base a dove conduce, secondo la definizione di interno che dà Il confine del workspace, che il tool lo legga o lo scriva — la directory in cui gen-catalog scrive il proprio output, il documento che edit-document riscrive e l’entità accanto a cui pin scrive il proprio lock quanto un documento che un tool legge — quindi un percorso non ancora creato sotto un link che esce dal workspace viene rifiutato come quel link, senza che nulla venga letto o scritto. Una release che indica una Release indicata dalla configurazione del workspace servito, come build.authoring_release o come chiave di workspace.releases, viene raggiunta attraverso quella configurazione ed è accettata attraverso un link ovunque si trovi il suo file; nessun altro argomento ha questa eccezione. Se il percorso che intendevi è dentro quel workspace ma è stato scritto in forma assoluta, il rifiuto ti dà la forma relativa alla radice da inviare al suo posto, così un chiamante che ha indovinato la forma sbagliata viene informato di quella giusta anziché solo del fatto che era sbagliata. Ciò vale per i percorsi che una chiamata indica come proprio oggetto — il documento da validare, la Release da compilare, la directory in cui una generazione scrive il proprio output — e per quelli su cui un tool scrive non meno che per quelli che legge: un chiamante che raggiunge un server dalla rete chiede a una macchina che non vede di leggere e scrivere file, e il workspace scelto dall’operatore è dove quella lettura e scrittura viene contenuta. Su standard input e output gli argomenti di percorso di ogni tool mantengono il contratto descritto sotto quel tool più avanti, dove un percorso può essere assoluto e può puntare fuori dal workspace — la persona che chiama possiede la macchina su cui gira il server, quindi confinarla in una directory scelta da lei stessa non porterebbe nulla. I due tool la cui operazione risponde di per sé solo su un documento contenuto nel workspace, insertion-point e edit-document, mantengono questo comportamento su entrambi i trasporti, e rifiutano un documento fuori dal workspace sia che sia scritto così sia che sia raggiunto attraverso un link che ne esce. Ciò che viene rispettato su standard input e output è il percorso indicato da una chiamata e nulla oltre. Ciò che l’operazione legge e scrive poi per conto proprio è vincolato su entrambi i trasporti esattamente come quando lo stesso comando viene digitato in un terminale: una visita o una ricerca non legge attraverso un link che esce dal workspace, un file che una Release nel workspace o il suo Manifest indica con un percorso non viene letto da fuori del workspace — e uno indicato da una Release che la chiamata ha indicato fuori dal workspace non viene letto da fuori della directory che contiene quella Release — e un file scritto sotto una directory — il workspace, o una indicata dalla chiamata — resta dentro quella directory. Il confine del workspace mette a confronto i due trasporti con la riga di comando e l’editor, e indica ciò che resta aperto su standard input e output: un documento in un workspace che hai clonato può indurre un assistente a indicare un percorso fuori dal workspace, e quel percorso viene rispettato così come è indicato.
Cosa dice una risposta sul filesystem del server
Via HTTP una risposta indica un luogo nel filesystem del server in modo relativo alla radice del workspace, oppure lo trattiene. Un client che ha avviato il server gira dove gira il server, quindi su standard input e output ogni risposta indica ciascun luogo così come l’operazione lo detiene — in forma assoluta, se è così che lo detiene — e ciascuno è un luogo che quel chiamante possiede già. Un chiamante che raggiunge un listener non ha scelto nessuno di quei luoghi e non può aprirli, e un server che glieli ha pubblicati non può ritirarli. Quindi via HTTP una risposta dice a quel chiamante una di due cose su un luogo:
- Un luogo dentro il workspace è indicato in modo relativo alla radice del workspace — la stessa forma che prende un percorso che invii, così un nome letto da una risposta può essere rinviato invariato nella chiamata successiva. Una Release alla radice è
release.yaml, e il suo lockfile èrelease.lock. - Un luogo fuori dal workspace viene trattenuto, e così la radice del workspace stessa. Il campo non contiene alcun valore — è
nullo omesso, e suattachment-container, la cui risposta mantiene la forma in cui ogni superficie la riporta,fileresta vuoto — e un indicatore accanto, chiamato come il campo con_withheldin coda, dice che è stato trattenuto anziché non impostato:workspace_root_withheldaccanto aworkspace_root,file_withheldaccanto afile. Un indicatore è presente solo dove qualcosa è stato trattenuto. La radice viene trattenuta perché un listener serve esattamente un workspace, quindi dove si trova quel workspace non indica nulla di cui hai bisogno per indicare ciò che contiene.
Se un luogo sia dentro viene giudicato da come è scritto, non dal file che raggiunge. Un percorso scritto attraverso la destinazione di un link simbolico anziché attraverso la radice su cui è stato avviato il server, e un percorso che esce dalla radice e vi rientra, risultano ciascuno fuori dal workspace e vengono trattenuti. Il giudizio tende a dirti di meno, mai a indicare un luogo fuori dal workspace.
Via HTTP il testo leggibile di una risposta segue la stessa regola. Dove il testo, una riga di diagnostica o il messaggio di un errore indica un luogo che il workspace contiene — la sua radice o qualsiasi cosa sotto di essa, un file di configurazione da cui è stata letta la sua configurazione, una directory da cui viene letto il suo catalogo — quel luogo è scritto in modo relativo alla radice, oppure si legge (location withheld) dove si trova fuori dal workspace o è la radice. Il testo che una risposta compone sul proprio workspace lo chiama il workspace servito da questo server. Un luogo al di fuori di tutti questi che un’operazione scrive in un messaggio non viene riconosciuto come tale, e ti arriva così come è stato scritto.
Le risposte a cui si applica, via HTTP:
list-entities,list-releases,cache-status,registry-list,search,attach-candidates,connection-candidates,insertion-point,attachment-container,connection-at-positioneedit-documenttrattengonoworkspace_root. I percorsi che già forniscono in modo relativo alla radice — il file sorgente di un’entità, il percorso di una Release e il suo lockfile sottolockfiles, il documento a cui si riferisce un punto di inserimento o una modifica, i file scritti da una modifica — si leggono allo stesso modo su entrambi i trasporti.cache-statustrattiene anche ciò che indica un plugin che il server ha caricato da un file sul proprio host. Una tale identità ènullal suo posto inprovenance[].identities, ogni altra identità mantiene la propria posizione, e la voce è marcataidentities_withheld. Lanotedi un modulo compilato è una frase che indica le identità per cui il modulo è stato compilato, quindi dove una di esse indica un tale file lanoteviene omessa per intero e marcatanote_withheld; ildigestdel modulo è comunque presente. Un’identità che indica un riferimento di registry o un’entità Plugin riceve risposta per intero, e così unanoteche indica solo quelli. Lalabeldi un artefatto sorgente è il suo posto nella cache, composto dall’host e dal percorso dell’URL da cui è stato risolto, quindi per un repository letto dal filesystem del server stesso — tramite un URLfile://o un percorso — lalabelviene omessa e marcatalabel_withheld, la suasizee il suodigestsono comunque presenti, e unalabelche indica un host di rete riceve risposta per intero. Il testo dell’elenco riporta(location withheld)dove ne avrebbe indicato uno.validateindicatarget, ereleaseper una Release, in modo relativo alla radice; per l’intero catalogo,targetè la radice e viene trattenuto. Un luogo indiagnosticsonoticessegue la regola del testo.buildindicareleasein modo relativo alla radice, e una build che ha prima risolto le proprie dipendenze contienedependency_resolutioncosì come lo rispondepull. Una build inviata conwriteindica la directory in cui ha scritto comeoutput_dir, che valedist— relativa alla radice — e ogni percorso infilesè relativo a quella directory. Unrefusal, e ogni voce dei suoifindings, indica il propriofilein modo relativo alla radice, oppure lo trattiene dove il documento si trova fuori dal workspace.advisories,deprecations,declined_external_inputse ognimessagedelrefusalseguono la regola del testo.pullindicareleaseelockfilein modo relativo alla radice.diagnosticseincomplete_external_inputsseguono la regola del testo. Lasourcedi ogni voce diresolvedriceve risposta per intero su entrambi i trasporti: indica ciò che l’esecuzione ha fatto, mai un luogo sull’host.describeindica lareleasedi una Release in modo relativo alla radice, e ilfiledi un’entità in modo relativo alla radice dove il suo documento si trova dentro il workspace; un’entità letta da una directory di catalogo fuori dal workspace ha il propriofiletrattenuto.mapping_diagnosticsedeprecationsseguono la regola del testo.lintindica illocation.filedi ogni segnalazione in modo relativo alla radice, oppure lo trattiene dove l’entità si trova fuori dal workspace. Ilmessagee ilsuggestdi una segnalazione seguono la regola del testo.pinindicaentityelockin modo relativo alla radice, e così fa ilpincontenuto in una pubblicazione.gen-catalogindica ogni file elencato inoutputin modo relativo alla radice.importtrattieneworkspace_root, eoutput_dirdove le bozze sono andate in quella radice; una directory che hai indicato inoutput_dirviene comunicata con il suo nome relativo alla radice. Ogni percorso di bozza inwrittenedraftsè relativo aoutput_dir, quindi dove sono andate le bozze è comunque nella risposta. Ilmessagedi una diagnostica, e iparams_summary,rationaleeswap_hintdi una decisione, sono prosa composta dall’importatore e seguono la regola del testo.config-showeplugin-listtrattengono più della radice, perché la maggior parte di ciò che riportano è configurazione che indica luoghi, come spiega Cosa un listener non ti dice del suo host.scaffold, quando scrive un esempio, indicadircosì come l’hai inviato, in modo relativo alla radice, e ogni percorso infilesin modo relativo a quella directory; la stesura di bozze e l’elenco non indicano alcun luogo.- I tool di pubblicazione,
sign-artifacts,deprecate-artifact,get-schema,explain-erroredescribe-capabilitiesnon indicano di per sé alcun luogo sull’host. Il messaggio di errore di ciascuno di essi segue la regola del testo: il rifiuto sollevato da un workspace offline indica il suo.aggrega-config.yamlin modo relativo alla radice. - Un argomento di percorso rifiutato perché esce dal workspace viene rifiutato senza indicare la radice né il luogo che avrebbe raggiunto, come sopra.
Come termina una chiamata
Chiudere la connessione annulla la chiamata che trasportava. È il segnale di annullamento di questo trasporto: il server tratta la disconnessione di un chiamante come annullamento di quella richiesta, interrompe il lavoro che stava facendo e non scrive più nulla per essa. Qui non serve né ci si aspetta alcun messaggio di annullamento — l’opposto di standard input e output, dove non c’è uno stream per richiesta da chiudere e un client termina una chiamata indicandone invece l’id. Un messaggio di annullamento che arriva comunque via HTTP viene accettato e non termina nulla.
Arrestare il processo svuota il listener. Un’interruzione, o una richiesta di terminazione da un supervisore o da un runtime di container, fa smettere al listener di accettare e lascia terminare una chiamata a cui si sta già rispondendo, entro un margine limitato, così un chiamante che ha chiesto qualcosa prima dell’arresto riceve comunque la sua risposta. Una chiamata che non è terminata entro quel margine perde la connessione. Una seconda richiesta di arresto termina subito il processo.
Liveness e readiness, su un indirizzo dedicato
mcp.health.listen è dove un supervisore chiede se questo processo è attivo e se può rispondere a una chiamata. Assegnagli un indirizzo in una delle forme sopra e un secondo listener risponde lì a GET /healthz e GET /readyz. Omettilo — è il valore predefinito — e non viene avviato alcun secondo listener e nessuno dei due controlli riceve risposta da nessuna parte.
Le due risposte dicono cose diverse, ed è per questa differenza che sono due. A /healthz si risponde 200 dal momento in cui il processo è in esecuzione, che è tutto ciò che la liveness afferma: è attivo, e un supervisore che non riceve alcuna risposta dovrebbe riavviarlo. A /readyz si risponde 503 finché il workspace servito da questo processo non è stato risolto e l’endpoint non ha fatto il bind, e 200 da quel momento in poi — così un bilanciatore trattiene il traffico finché il processo non può davvero rispondere a una chiamata, anziché inviare la prima richiesta a uno che si sta ancora avviando. Ogni risposta è un codice di stato con corpo vuoto; non viene chiesta alcuna credenziale e non viene letto nulla di ciò che il chiamante ha inviato.
L’endpoint non risponde mai a quei due percorsi. A GET /healthz e GET /readyz sull’indirizzo indicato da mcp.listen si risponde 404, esattamente come per ogni altro percorso che quell’endpoint non serve, con un token come senza. Rispondere lì a una sonda darebbe a qualunque cosa raggiunga l’endpoint una lettura gratuita dello stato del processo, insieme a un modo gratuito per fargli svolgere lavoro — su un listener che altrimenti rifiuta ogni richiesta priva di credenziale.
Dove si trova l’indirizzo di health lo scegli tu, e non è confinato come lo è mcp.listen. Nessun indirizzo viene rifiutato per esso. Puntalo su loopback o su un socket Unix, che è lo scopo per cui esiste: un supervisore, un bilanciatore o un runtime di container in esecuzione accanto a questo processo sullo stesso host. Qualunque cosa possa raggiungere l’indirizzo che scegli può leggere quelle due risposte, quindi un indirizzo raggiunto dalla rete aperta le pubblica alla rete aperta.
Nulla viene servito senza una credenziale
Ogni richiesta all’endpoint porta una credenziale, e quale dipende dal fatto che un proxy posto davanti l’abbia già verificata. Per impostazione predefinita è un bearer token che questo server verifica da sé, descritto nel resto di questa sezione. Imposta mcp.authorization.trusted_proxy e diventa invece un header impostato da quel proxy, descritto in Leggere il chiamante da un proxy posto davanti — dove non viene letto alcun token. Nessuna delle due forme serve una richiesta che non presenta nulla.
Per impostazione predefinita il server verifica da sé un bearer token. Legge il token dall’header Authorization e lo accetta solo se la firma si verifica con una chiave pubblicata dal server di autorizzazione, il token indica mcp.authorization.issuer come emittente, indica il mcp.authorization.resource di questa distribuzione tra i suoi destinatari, è dentro il suo periodo di validità e dice chi lo ha presentato. A un token che non supera uno qualsiasi di questi controlli si risponde 401, con error="invalid_token" aggiunto alla stessa challenge che riceve un chiamante che non porta nulla — e la risposta è identica qualunque controllo l’abbia respinto, così un chiamante apprende che gli serve un token diverso anziché quale parte di quello inviato era sbagliata. Sono accettati solo algoritmi di firma asimmetrici: un token non firmato, e uno che indica un algoritmo simmetrico, vengono rifiutati prima che se ne legga qualcosa.
Un token può dire che tipo di token è, e sono accettate quattro forme. Un JWT può portare un header typ che ne indica il tipo. Questo server accetta at+jwt e application/at+jwt, le due grafie registrate per un access token; JWT, che dice solo che il token è un JWT; e un token che non dichiara alcun tipo. A qualsiasi altra cosa si risponde 401 esattamente come a ogni altro token rifiutato. L’insieme è fisso e nessuna impostazione lo allarga o lo restringe, perché quale forma compare lì lo decide il server di autorizzazione che ha emesso il token, non la distribuzione che lo riceve. Accettare JWT significa che il tipo dichiarato da solo non distingue più un access token da un identity token — è il controllo del destinatario a distinguerli, ed è per questo che quel controllo è quello portante: il destinatario di un identity token è il client a cui è stato emesso, mai il mcp.authorization.resource di questa distribuzione, quindi un token emesso per qualcosa che non sia questa distribuzione viene rifiutato comunque si definisca.
Quali server di autorizzazione ciò ammette. Microsoft Entra ID emette access token di tipo JWT. Keycloak emette at+jwt, e JWT quando è attiva la sua modalità di compatibilità OpenID Connect. Auth0 emette JWT con il proprio profilo di token e at+jwt con il suo profilo RFC 9068. Un token di uno qualsiasi di questi supera questo controllo qualunque delle due forme porti. Okta non è supportato: i suoi access token dichiarano un tipo proprio che non è nessuno dei quattro sopra, quindi questo server li rifiuta.
Un token rifiutato lascia il motivo sul flusso di errore del server. Al chiamante viene detto solo che ciò che ha presentato non è stato accettato; il processo in servizio scrive una riga che indica il controllo che ha respinto il token — il destinatario, l’emittente, il periodo di validità, la firma, l’identificatore di chiave, il tipo dichiarato e ciascuno degli altri. Quella riga è ciò che rende diagnosticabile una distribuzione che rifiuta ogni richiesta da parte di chi la gestisce, e non solo da parte di chi la chiama. Non contiene alcuna parte del token. Una richiesta che non presenta alcuna credenziale non scrive alcuna riga, perché ricevere una challenge è il modo in cui un client scopre dove ottenere un token, quindi è la prima cosa che fa ogni client corretto.
Un token va nell’header e da nessun’altra parte. A uno inviato come parametro di query access_token si risponde 400 e non viene mai letto, perché un indirizzo viene registrato da ogni log di proxy, cronologia del browser e header referrer attraverso cui passa la richiesta, quindi un token arrivato in quel modo è già stato esposto. Il server non scrive mai un token in un log, non lo invia mai da nessuna parte e non ne ottiene né ne scambia mai uno per conto di un chiamante: legge ciò che è stato presentato, decide e non ne conserva nulla. Il soggetto indicato dal token viene registrato e non viene confrontato con nulla.
Le chiavi di verifica provengono dal server di autorizzazione, o da un file che indichi. Con mcp.authorization.jwks_file non impostato, il server legge i metadati del server di autorizzazione al suo indirizzo well-known, segue il jwks_uri pubblicato lì e conserva le chiavi che trova; un token firmato con un identificatore di chiave che quelle chiavi non contengono provoca una rilettura, e non più di una in un breve intervallo, così un chiamante che invia identificatori di chiave inventati non può provocare una richiesta in uscita per ogni richiesta. Leggerle dal server di autorizzazione richiede un indirizzo delle chiavi https, oppure uno http in chiaro su questa macchina: un jwks_uri in chiaro http su un altro host non viene mai interrogato, e un redirect che manderebbe una delle due letture verso http in chiaro su un altro host non viene seguito, perché chiunque si trovi su un percorso non protetto verso le chiavi potrebbe rispondere con chiavi proprie. A un token che richiede quelle chiavi si risponde allora 503, esattamente come per chiavi che non si riescono a leggere, e la riga che il server scrive per quella richiesta dice che la lettura è stata rifiutata perché in chiaro http anziché che il server di autorizzazione non era raggiungibile — la correzione spetta al server di autorizzazione, che deve pubblicare metadati e chiavi su https. Con jwks_file impostato, le chiavi vengono lette da quel file e il server di autorizzazione non viene mai contattato — ciò che serve a un workspace che dichiara offline: true, e un tale workspace viene rifiutato prima che il suo listener faccia il bind a meno che il file non sia indicato. Dove le chiavi non si riescono a leggere affatto, alle richieste si risponde 503 senza challenge: nulla di ciò che un chiamante ha presentato è stato trovato carente, quindi inviarlo di nuovo con un altro token non servirebbe.
L’unica risposta data senza richiedere una credenziale è il documento dei metadati della risorsa protetta. Un client deve leggerlo prima di poter possedere un token, quindi richiederne uno lì chiuderebbe l’unica porta d’accesso. Viene servito su /.well-known/oauth-protected-resource e — dove l’indirizzo indicato da mcp.authorization.resource ha un percorso proprio — anche su quel percorso well-known con quel percorso aggiunto in coda. Sono i due punti in cui un client guarda, e la forma con il percorso aggiunto è l’indirizzo che la challenge indica. Il documento riporta quell’indirizzo come la risorsa con cui si chiama questo deployment, mcp.authorization.issuer come server di autorizzazione da cui ottenere un token, header come unico modo di presentare un token, e i tre nomi di scope riportati sotto.
L’issuer è un indirizzo https, a meno che il server di autorizzazione non giri su questa macchina. Il semplice http è accettato per un issuer su localhost, 127.0.0.1 o ::1, che è la forma di un test locale con un server di autorizzazione locale; un issuer in semplice http su qualsiasi altro host viene rifiutato prima che il listener esegua il bind, e il rifiuto indica mcp.authorization.issuer e chiede un indirizzo https. Questo vale in ogni modalità — con le chiavi lette dall’issuer, con mcp.authorization.jwks_file e con un proxy davanti — perché ogni modalità pubblica l’issuer in questo documento: un client che lo segue esegue il proprio flusso di autorizzazione verso quell’indirizzo, quindi su semplice http il codice di autorizzazione e il token che ottiene attraverserebbero la rete senza protezione, indipendentemente dal fatto che questo server legga mai una chiave da lì. Dove invece legge le proprie chiavi da lì, chiunque si trovi su quel percorso potrebbe anche rispondere con chiavi proprie, e ogni token firmato con esse verrebbe ammesso.
I nomi di scope che questo deployment pubblica sono aggrega:read, aggrega:workspace-write e aggrega:registry-write. Sono i nomi da registrare presso il server di autorizzazione e i nomi che un client gli richiede, e la challenge ricevuta da un chiamante rifiutato indica aggrega:read come quello da ottenere per primo. Cosa ammette ciascuno di essi — e il secondo limite, quello che questo deployment impone a sé stesso — è descritto in Cosa può raggiungere un chiamante più avanti.
Leggere il chiamante da un proxy davanti
Dove un proxy davanti convalida già i token, mcp.authorization.trusted_proxy dice a questo server di leggere il chiamante da esso invece di controllare un token una seconda volta. Indica principal_header, l’header che quel proxy imposta per dire chi è il chiamante, e facoltativamente scopes_header, un secondo header che riporta gli scope di quel chiamante separati da spazi. Ciascuno è un nome di header HTTP come X-Forwarded-User, senza spazi né due punti; un nome di qualsiasi altra forma viene rifiutato al caricamento della configurazione, indicando la chiave, e così anche un principal_header vuoto — ometti il blocco per lasciare disattivata questa modalità. Quei due header sono gli unici letti: nessun header di indirizzo inoltrato né alcun altro header vi partecipa. Una richiesta che arriva senza l’header del principal riceve 401, e in questa modalità non viene letto alcun token — una richiesta con un token che questo server avrebbe altrimenti rifiutato viene servita quando il suo header del principal è presente, e una con un token che questo server avrebbe accettato viene comunque rifiutata quando quell’header è assente.
Quella modalità è accettata solo su loopback o su un socket Unix, e il processo viene rifiutato prima di eseguire il bind altrove. Un header è affidabile esattamente quando nient’altro che il proxy può impostarlo. Su un indirizzo raggiungibile dalla rete, chiunque può impostarlo — quindi un listener in questa modalità su un indirizzo del genere permetterebbe a ogni chiamante di dichiararsi chi vuole. Il rifiuto indica entrambe le impostazioni in conflitto, così puoi rimuoverlo spostando l’indirizzo o eliminando il blocco.
Ciò che il proxy afferma è ciò che questo server crede, e questo è il patto. In questa modalità questo server non controlla alcuna firma e non confronta il chiamante dichiarato con nulla, esattamente come non confronta con nulla il subject di un token. Se il proxy ha convalidato ciò che ha inoltrato, e se qualcosa può raggiungere quel listener senza passare dal proxy, spetta al deployment farlo correttamente; il confinamento descritto sopra è ciò che rende possibile farlo correttamente, non una garanzia che sia stato fatto.
Impostare mcp.authorization.trusted_proxy non elimina gli altri requisiti. issuer e resource restano necessari, perché il documento dei metadati viene comunque pubblicato e la challenge continua a indicarlo — un client dietro il proxy deve comunque sapere dove ottenere il token che il proxy controllerà. Per lo stesso motivo l’issuer resta un indirizzo https a meno che non giri su questa macchina: quel client ottiene il proprio token dall’issuer, quindi un issuer in semplice http su un altro host viene rifiutato prima che il listener esegua il bind in questa modalità esattamente come in ogni altra, anche se questo server non legge nulla da esso.
Cosa può raggiungere un chiamante
Due limiti decidono cosa raggiunge un chiamante via HTTP, e sono fissati da persone diverse. La credenziale del chiamante è il primo; ciò che questo server offre in assoluto è il secondo. Entrambi vengono letti prima che venga eseguito qualsiasi cosa, da una dichiarazione che ogni operazione fa su sé stessa, e raggiungono un client in punti diversi: l’elenco dei tool mostra ciò che questo server offre e annuncia, e la risposta ricevuta da ogni chiamata mostra ciò che la credenziale ammette.
Ogni operazione dichiara fin dove arrivano i propri effetti, e i tipi sono quattro, con il più ampio per ultimo:
- Non raggiunge nulla — legge una definizione, ispeziona ciò che una Release fissa, esegue il rendering degli artefatti in memoria e li restituisce. Non lascia nulla dietro di sé: non viene scritto nulla, e la risposta è tutto ciò che produce.
- Raggiunge il workspace — scrive all’interno del workspace servito da questo processo: il lockfile di una Release, la cache degli artefatti, entità generate, un documento modificato.
- Raggiunge un registry — pubblica, firma o allega un marcatore di ritiro a qualcosa di già pubblicato. Ciò che modifica è ciò che risolve ogni consumatore di quel registry, e nulla di ciò può essere richiamato da chi lo ha già scaricato.
- Raggiunge la macchina — modifica ciò che condividono tutti i workspace sull’host, tra cui lo store dei moduli compilati, il file di configurazione comune a tutti e lo store delle credenziali. Una cache che un singolo progetto tiene nella propria directory di cache non è di questo tipo, e
cache-statusriporta quale di questi tipi ha ciascuna cache che elenca.
Il tipo è una proprietà dell’operazione e non del tool che la offre, e copre ciò che l’operazione lascia dietro di sé — non dove una superficie mette la risposta che restituisce. Il rendering di una Release produce artefatti come risposta, quindi non raggiunge nulla; una riga di comando che poi salva quegli artefatti in una directory da te indicata sta consegnando quella risposta, non sta raggiungendo più lontano. Letto al contrario, ogni operazione che risponde con contenuti assumerebbe il tipo della superficie che si trovasse a salvarli, e il tipo smetterebbe del tutto di essere una proprietà dell’operazione. Per lo stesso motivo describe che legge un’entità tramite il suo riferimento di registry non raggiunge nulla: contatta quel registry per recuperare la risposta e non lascia nulla dietro di sé, né nel registry né su questa macchina, e quali registry può contattare è spiegato in Quali credenziali consuma una chiamata. Una singola chiamata può comunque spingersi oltre il tipo della sua operazione, quando è la chiamata stessa a richiedere una scrittura: una build inviata con write salva i propri artefatti nel workspace servito da questo server, quindi quella chiamata raggiunge il workspace, come fa una build che prima risolve le proprie dipendenze.
Uno scope ammette un tipo, e ogni scope di scrittura implica lo scope di lettura. aggrega:read ammette un’operazione che non raggiunge nulla. aggrega:workspace-write ne ammette una che raggiunge il workspace, e implica lo scope di lettura. aggrega:registry-write ne ammette una che raggiunge un registry, e implica anch’esso lo scope di lettura. Quindi un client chiede al proprio server di autorizzazione lo scope di scrittura di cui ha bisogno e non deve chiedere anche lo scope di lettura.
Nessuno scope ammette il tipo macchina, e nessuna impostazione ne aggiunge uno. Le operazioni di quel tipo sono offerte solo dai tool che eseguono un comando aggrega in un processo separato, e un server raggiunto via HTTP non ne offre nessuno, per il motivo spiegato in Raggiungere il server via HTTPS sopra. Eseguile da un terminale sull’host.
L’elenco dei tool mostra ogni tool che questo server offre e annuncia, qualunque siano gli scope della credenziale chiamante, e la credenziale decide quali di essi una chiamata può eseguire. describe-capabilities indicizza e definisce lo stesso insieme. Una chiamata che la credenziale non ammette riceve 403 con error="insufficient_scope" nella challenge, che indica l’unico scope che la ammetterebbe, e nulla di ciò che la chiamata ha richiesto è stato eseguito. Quel rifiuto è quello a cui risponde lo step-up del protocollo: un client che implementa lo step-up ti chiede di accedere di nuovo per lo scope indicato dalla challenge. L’elenco non cambia con la credenziale, quindi un client che ha effettuato di nuovo l’accesso possiede già quello giusto. Una credenziale che non riporta nessuno dei tre scope riceve lo stesso elenco di tool e non può chiamare nessuno dei tool che contiene, describe-capabilities compreso.
Una build è il caso da conoscere. Di per sé non modifica nulla e quindi richiede solo aggrega:read, ma una build che scrive richiede aggrega:workspace-write: una inviata con write salva i propri artefatti in dist/ nella radice del workspace, e una che prima risolve le proprie dipendenze scrive il lockfile — sia che la chiamata lo abbia chiesto con auto_pull, sia che lo abbia fatto l’impostazione auto_pull del workspace stesso. Il tool è elencato a un chiamante con scope di lettura come ogni altro tool, e le build che restano in memoria sono effettivamente disponibili per lui; ciò che viene rifiutato, indicando aggrega:workspace-write, è la chiamata che scrive.
A un client che non fa step-up si possono comunque concedere gli scope di scrittura, e la questione si risolve presso il server di autorizzazione. Chi gestisce il server di autorizzazione rende gli scope di scrittura scope predefiniti per quel client — scope che inserisce in ogni token emesso per quel client, che il client li abbia richiesti o no — così il token ottenuto al suo primo accesso li riporta già. Un client che si registra di nuovo presso il server di autorizzazione ogni volta che si connette è lì ogni volta un client nuovo, e un’impostazione fatta su una registrazione precedente non viene mantenuta; per un client del genere, l’impostazione che ha effetto sono gli scope predefiniti che il server di autorizzazione assegna a ogni client che registra. Il costo è che ogni accesso tramite quel client porta poi con sé una portata di scrittura, che il lavoro in corso ne abbia bisogno o no — e dove i predefiniti sono quelli assegnati alla registrazione, ogni client registrato in quel modo porta con sé anche quella portata. Rendi predefinito solo lo scope di scrittura di cui quel lavoro ha bisogno: aggrega:workspace-write e aggrega:registry-write ammettono tipi diversi, e nessuno dei due implica l’altro.
mcp.deny_reach è il punto in cui chi gestisce questo server gli sottrae un tipo, ed è una delle due impostazioni che accorciano l’elenco dei tool. Elenca i tipi — none, workspace, registry, machine — che questo server non offre, e ogni tool che ne raggiunge uno è assente dall’elenco dei tool di ogni chiamante e da describe-capabilities qualunque cosa dica il token di quel chiamante, e viene rifiutato se chiamato comunque, con un errore che indica questa impostazione. È il limite del server stesso e non del chiamante, quindi nessuna credenziale lo rimuove e il rifiuto non riporta alcuna challenge: un server pensato per servire letture e nient’altro elenca qui workspace, registry e machine, e allora non può pubblicare nemmeno per un chiamante il cui token riporta tutti e tre gli scope. Omettila, che è il comportamento predefinito, e questo server non sottrae alcun tipo, quindi quali tipi raggiunge una chiamata è deciso dagli scope del chiamante stesso. Indicare machine è accettato e non cambia nulla, poiché qui nulla di quel tipo è offerto fin dall’inizio. Un valore che non è uno dei quattro viene rifiutato al caricamento della configurazione, anziché essere ignorato — un operatore che scrive male un tipo ha chiesto un limite, ed essere servito silenziosamente senza di esso è il modo sbagliato di rispondere.
mcp.announce_tools è l’altra impostazione che accorcia l’elenco dei tool, e le due non sono lo stesso limite. deny_reach sottrae una capacità: un’operazione di un tipo indicato lì non è affatto offerta qui, per nessuno. announce_tools sottrae solo un annuncio: i tool che esclude sono capacità che questo server possiede ancora, e ciò a cui risponde è il limite che un client stesso pone a quanti tool registrerà. Dove sono impostate entrambe prevale la sottrazione, quindi un tool di un tipo sottratto resta assente comunque announce_tools lo indichi, e il rifiuto che un chiamante incontra indica la sottrazione. Nulla di ciò che accorcia l’elenco legge gli scope del chiamante: uno scope che manca al chiamante rifiuta una chiamata e non rimuove mai un tool dall’elenco. Restringere ciò che il server annuncia descrive il resto.
Quali credenziali consuma una chiamata
La firma keyless su un listener prende la propria identità dall’identity_token che la chiamata riporta, e da nient’altro. Un token inviato nella chiamata è una credenziale che il chiamante possiede: ha dovuto ottenerlo, è legato a lui, e la firma che produce gli è attribuibile. Ogni altra fonte da cui potrebbe provenire un’identità appartiene a chi ha avviato questo processo, quindi su questo trasporto la risoluzione riceve un ambiente che non risponde nulla. AGGREGA_IDENTITY_TOKEN e SIGSTORE_ID_TOKEN nell’ambiente del server non vengono letti, e l’endpoint OIDC ambientale di GitHub Actions non viene raggiunto. Sono fuori portata, non sconsigliati — non c’è nulla che la risoluzione possa trovare. Una chiamata che non invia alcun identity_token viene rifiutata, e il rifiuto indica identity_token come ciò da inviare e non indica alcuna variabile né alcun endpoint: un chiamante che non è alla tastiera di questa macchina non può esportare nulla qui, quindi indicarne una significherebbe dirgli di predisporre qualcosa che non può cambiare la risposta.
Una chiave di firma conservata su questa macchina non può essere selezionata, per nessuna delle due vie. key_path viene rifiutato prima che venga risolto qualsiasi cosa, ed è assente dagli schemi degli argomenti che publish-entity, sign-artifacts e deprecate-artifact pubblicizzano qui, così a un chiamante non viene mai offerto un argomento che non potrebbe avere successo. Non viene raggiunta nemmeno la chiave di firma indicata dalla configurazione del workspace servito — signing.key_path, sia che sia impostata per il workspace nel suo insieme, impostata per un singolo registry o fornita dall’ambiente. Un unico motivo copre entrambi i casi: un percorso di chiave non è una credenziale, è un nome per un segreto che questo server conserva. Un chiamante che ne fornisce uno non dimostra nulla, chiunque abbia raggiunto questo indirizzo potrebbe fornire lo stesso nome, e la firma che ne seguirebbe direbbe che è l’operatore a garantire per l’artefatto e non il chiamante. Chiudere l’argomento lasciando aperta la configurazione significherebbe chiudere una porta su una stanza che l’altra apre ancora. Quindi la firma con chiave è irraggiungibile su un listener: firma solo un token inviato nella chiamata.
fulcio_url, rekor_url e timestamp_url non sono interessati e restano disponibili su entrambi i trasporti. Indicano servizi da contattare e non qualcosa che questa macchina conserva, quindi un chiamante che non può selezionare una chiave firma comunque verso gli endpoint configurati da questo deployment.
Un listener avviato su un workspace che indica una chiave di firma lo segnala una volta, all’avvio. Il processo scrive una riga sul proprio flusso di errore indicando l’impostazione e dicendo che un chiamante che raggiunge questo listener non può usare quella chiave — così un operatore lo apprende dal processo che ha avviato e non da una firma che non si aspettava. Un workspace che non indica alcuna chiave non produce una riga del genere, perché non c’è nulla da dire al riguardo. La riga riporta il nome dell’impostazione e né la chiave né alcuna informazione sul file a cui punta.
Su standard input e output nulla di quanto sopra si applica. Lì l’ambiente viene letto e key_path seleziona una chiave conservata su questa macchina, perché il client che ha avviato questo server gira sulla macchina del chiamante stesso, e ciò che quel processo può raggiungere spetta a quel chiamante usarlo.
Leggere un’entità tramite il suo riferimento di registry contatta un solo registry, con il login di questo host, e su un listener solo un registry con cui il workspace servito è configurato. describe inviato con un riferimento oci:// come name legge l’entità pubblicata a quella coordinata — la stessa lettura che esegue aggrega inspect — dall’unico registry indicato dal riferimento, usando il login che questo host possiede già per quel registry. La chiamata non riporta alcuna credenziale, e describe non ne accetta. Via HTTP il registry deve essere uno con cui il workspace servito è configurato: l’host indicato dal suo default_registry, o un host elencato in registries, confrontato esattamente e con la porta. Un riferimento a qualsiasi altro host — compreso un indirizzo su questa macchina — viene rifiutato prima che quell’host venga contattato, e il rifiuto indica l’host, così un chiamante non può puntare questo server verso una destinazione di sua scelta. Ciò che resta raggiungibile è voluto: un chiamante che possiede aggrega:read può leggere tutto ciò che il login di questo host può leggere su un registry con cui il workspace è configurato, che è ciò che può leggere anche una persona al terminale di questo host. Su standard input e output viene letto un riferimento a qualsiasi registry, come alla riga di comando. Descrivere un’entità tramite il suo nome di catalogo non è interessato.
Una chiamata a un registry usa lo store delle credenziali dell’utente del sistema operativo con cui gira questo processo, esattamente come fa la stessa chiamata da un terminale su questo host. Non esiste una fonte di credenziali per workspace né un’impostazione che ne aggiunga una, ed è per questo che registry-list riporta lo stato delle credenziali di un host allo stesso modo in ogni workspace su questa macchina. Un deployment che vuole che workspace diversi abbiano credenziali di registry diverse li esegue come utenti diversi del sistema operativo — un processo per workspace, ciascuno avviato come utente proprio. È da lì che viene la separazione, e predisporla spetta all’operatore.
Cosa registra il server
Ogni richiesta a cui questo endpoint risponde lascia una riga sul flusso di errore del processo, e quella riga è un singolo oggetto JSON. Riporta il time in cui è stata scritta e un request_id che questo processo ha generato per la chiamata e che non rimanda al chiamante; subject e issuer come li ha asseriti la credenziale presentata, con client_id dove ne indicava uno; workspace_root, il workspace servito da questo processo; method, e target dove il metodo indirizza qualcosa per nome; reach, il tipo che l’operazione dichiara, e reach_escalated_to dove la chiamata si è spinta oltre; outcome; duration_ms; e transport. Un campo senza nulla da dire viene omesso anziché scritto vuoto, quindi un client_id assente è una credenziale che non indicava alcun client, e un reach_escalated_to assente è una chiamata che ha raggiunto esattamente ciò che la sua operazione dichiara.
outcome dice cosa è stato della chiamata, e i valori sono distinti così puoi contarli separatamente. ok è stata eseguita e ha avuto successo. tool-failure è stata eseguita ed è tornata segnalata come un errore che il chiamante può correggere — una chiamata che questo server ha servito e non una che ha rifiutato, quindi non va contata tra i tuoi rifiuti. error è un rifiuto riportato come envelope di errore del protocollo. unauthenticated, forbidden e rate-capped sono la credenziale, il limite di origine o di scope e il limite di frequenza per chiamante che respingono una richiesta. cancelled è un chiamante che ha chiuso la connessione prima di ricevere risposta.
Il motivo per cui una credenziale rifiutata è stata respinta è un campo di quella stessa riga e non una riga a sé. Una richiesta rifiutata lascia un record come ogni altra, con refusal che indica il controllo che l’ha respinta. Nessuna credenziale, né alcuna sua parte, arriva in alcuna riga — né in un rifiuto, né in una chiamata servita.
Un chiamante che non ha presentato nulla non lascia alcuna riga. Ricevere una challenge è il modo in cui un client scopre dove ottenere un token, quindi è la prima cosa che fa ogni client ben fatto, e una riga per ciascuna di esse seppellirebbe i rifiuti che significano qualcosa. Nemmeno una richiesta che indica un percorso o un metodo non servito da questo endpoint ne lascia: entrambi vengono risolti prima che venga letto qualsiasi cosa sul chiamante, quindi scansionare l’indirizzo non scrive nulla in ciò che raccoglie il flusso.
Il contesto di trace inviato da un client viene copiato sulla riga alla lettera. traceparent, e accanto tracestate e baggage dove vengono inviati anche questi, sono riportati esattamente come ricevuti, così ciò che raccoglie questo flusso può collegarlo ai record del chiamante stesso. Una richiesta che non ne invia nessuno, o ne invia uno che non è un trace context W3C ben formato, produce una riga senza quelle chiavi: nulla viene inventato, e nulla viene alterato lungo il percorso.
Il processo registra la propria vita nella stessa forma e sullo stesso flusso, e ognuna di quelle righe indica un event dove una riga di richiesta indica un metodo e un chiamante: startup all’avvio, listening con l’indirizzo su cui ha eseguito il bind, startup-refused con il motivo per cui un avvio è stato rifiutato prima di servire, signing-key-ignored dove il workspace servito indica una chiave di firma che nessun chiamante che raggiunge questo listener può usare, docs-bundle con l’esito dell’acquisizione del bundle della documentazione, e shutdown al termine dell’esecuzione. È la presenza di event a distinguere i due tipi di riga.
Raccogli tutto dal flusso di errore del processo, e questa è l’intera consegna. Non c’è alcun exporter da configurare, nessun file da indicare e nessuna impostazione che attivi, disattivi o sposti altrove qualcosa di tutto ciò: ciò che supervisiona questo processo — un container runtime, un service manager, un log shipper — è ciò che raccoglie quel flusso, e dove lo interroghi in seguito. Su standard input e output lo stesso flusso riporta invece prosa leggibile, perché il client che lo legge ha avviato il processo e si trova sulla stessa macchina.
Nulla di tutto ciò viene inviato al chiamante. Il server non pubblica alcun flusso di log tramite il protocollo su nessuno dei due trasporti, e una richiesta che riporta il campo del livello di log per richiesta del protocollo riceve esattamente la stessa risposta di una che non lo riporta: ciò che viene registrato qui è dell’operatore, e va soltanto al flusso dell’operatore.
Cosa dice il server al modello quando si connette
Il server offre un blocco di indicazioni per il modello, che il tuo client può presentargli prima della prima chiamata. Un client su 2026-07-28 lo legge dalla risposta a server/discover; un client su 2025-06-18 lo legge dalla risposta al suo handshake initialize. È lo stesso testo su entrambi i percorsi, byte per byte, e lo stesso testo per ogni client che raggiunge un processo: nulla in esso viene negoziato, e nulla deriva da ciò che il client ha inviato o dalla credenziale che ha presentato, quindi ciò che viene detto a un modello alla connessione non varia tra sessioni né tra client.
Due cose variano, e nessuna delle due è il client. Il paragrafo conclusivo è composto per il trasporto servito da un processo, quindi un server che comunica su standard input e output e un listener consegnano al modello un testo conclusivo diverso. E dove il bundle desktop che ha avviato un server proviene da una versione diversa da quella dell’eseguibile aggrega che ha avviato, le indicazioni si aprono con l’unica frase che lo dice, indicando entrambe le versioni — la frase con cui si apre la risposta di describe-capabilities senza argomenti, come spiega Da quale versione proviene il server; un avvio non fatto da alcun bundle, e uno il cui bundle proviene dalla versione dell’eseguibile stesso, consegnano le indicazioni senza di essa. Entrambe sono fissate all’avvio del processo, e all’interno di ciascun processo le due revisioni servono comunque il testo proprio di quel processo in modo identico.
Insegna il modello mentale che lo schema degli argomenti di un tool non può trasmettere da solo:
- Cosa fa il compilatore, e cosa deliberatamente non fa — che instrada testo e valuta corrispondenze di label anziché interpretare cosa significa un valore, che è privo di opinioni sul contenuto che metti nei tuoi documenti, e che durante la compilazione non si autentica mai con un provider, non legge mai lo stato di un cluster e non trasforma mai un segreto in testo in chiaro. Un valore che esiste solo una volta che l’infrastruttura è in esecuzione viene trasportato come stringa puntatore che l’ambiente di destinazione compila in seguito.
- Il vocabolario di authoring, e come si relazionano i tipi — a cosa serve ciascun tipo e su quale viene effettivamente eseguita una build, così un assistente non deve dedurre la forma di un deployment dall’elenco dei tool.
- L’ordine in cui procede il ciclo di authoring — leggi il contratto, crea lo scaffold a partire da esso, ispeziona ciò a cui ti stai collegando, poi verifica prima del rendering.
- Quando ricorrere a un prompt anziché a un tool — un tool per agire, un prompt per inquadrare un’attività.
- Che l’elenco dei tool è l’intera superficie — ogni tool offerto da questo server è lì, e quali tool offre un server dipende da come è stato configurato, quindi un assistente legge ciò che c’è da quell’elenco e da
describe-capabilitiesanziché andare a cercarne un secondo. Dove la connessione ha presentato una credenziale, dice che la credenziale decide quali di quei tool una chiamata può eseguire e mai quali di essi sono elencati: una chiamata che non ammette viene rifiutata indicando lo scope che la ammetterebbe, e il client può accedere di nuovo per quello scope. - Cosa significa un workspace vuoto, e cosa può farne il modello — il paragrafo che varia in base al trasporto, più avanti.
Indica le superfici anziché ripeterle. Ogni tool riporta già la propria descrizione e il proprio schema degli argomenti in tools/list, e il contratto di ogni tipo vive già nel suo schema e nella sua pagina di riferimento, quindi le indicazioni rimandano a questi e si fermano — una sola sede per ogni affermazione. Un tool che nomina è un tool che il server serve, e rimanda a ogni famiglia di risorse che la superficie di lettura risolve, così nulla verso cui manda un assistente è un vicolo cieco.
Non contiene alcun indice dei tool stessi, e questa è la stessa regola, non un’omissione rispetto a essa. Un client possiede la definizione di ogni tool da tools/list prima di leggere una sola parola di questo testo, quindi una riga per tool qui sarebbe una seconda copia di scopi che ha già — pagata in ogni sessione, da ogni client, e libera di divergere dall’elenco dei tool nel momento in cui uno dei due venisse modificato.
Dichiara anche ciò che non enumera, e perché: i target di rendering disponibili e i tipi di libreria installati sono proprietà dei tuoi plugin e del tuo insieme di schemi, quindi le superfici delle risorse li riportano direttamente anziché far contenere alle indicazioni una copia che potrebbe divergere.
Cosa viene detto a un modello su un workspace vuoto
Il paragrafo conclusivo risponde alla domanda che un modello incontra per prima su un workspace che non contiene nulla: cosa significa un list-entities vuoto, e cosa può farne. La sua apertura è la stessa su entrambi i trasporti — un elenco vuoto significa che il workspace risolto da questo processo non contiene documenti Aggrega che possa leggere e che nemmeno le directory di catalogo configurate accanto a esso ne dichiarano — e ciò che segue dipende dal trasporto servito da questo processo, perché la risposta onesta non è la stessa sui due.
Su standard input e output al modello viene detto che il workspace è suo da ispezionare e riparare. Gli viene detto dove riceve risposta una chiamata che non indica alcun workspace — nella cartella con cui il server è stato avviato, dove è stato avviato con una, e altrimenti nel workspace trovato a partire dalla cartella in cui è stato avviato, che può essere quella cartella stessa — e che workspace_root su una chiamata ne indica un altro. Viene indirizzato a config-show per la configurazione in vigore e per quale livello ha deciso ciascuna impostazione, e a cli-config-init per inizializzarne una funzionante; entrambi sono nell’elenco dei tool su quel trasporto. Il client che esegue il server si trova sulla macchina del chiamante stesso, quindi ciò che quel processo può raggiungere spetta a quel chiamante usarlo — e dove fissi il confine è dove è fissato per ogni altro tool, nel tuo client MCP, come spiega Cosa può fare un assistente senza chiedertelo prima.
Via HTTP al modello viene detto di riferire anziché configurare. Il workspace è quello su cui hai avviato il processo ed è fisso per tutta la sua vita; una chiamata che indica workspace_root o catalog_dirs viene rifiutata, indicando l’argomento; e nessun tool che scrive configurazione viene offerto qui ad alcun chiamante, qualunque scope riporti la sua credenziale. Quelle operazioni sono offerte solo dai tool che eseguono un comando aggrega in un processo separato, e una sessione raggiunta via HTTP è composta senza di essi — quindi il limite è la composizione e non uno scope, e nessun token lo allarga. Un modello che raggiunge il tuo deployment tramite un listener non può quindi inizializzare un registry o riscrivere una trust policy sul tuo host, e il paragrafo glielo dice invece di lasciarlo tentare e leggere il rifiuto.
Cosa può fare un assistente senza chiedertelo prima
Un assistente connesso a questo server tramite standard input e output può chiamare ogni tool che il server espone, senza chiedertelo, a meno che il tuo client non sia configurato per negarlo. Su quel trasporto il server offre i tool e non decide quali di essi una determinata chiamata possa usare: quella decisione spetta al tuo client, e sta a te prenderla lì. Via HTTP non è lo stesso: il server elenca ogni tool che offre e annuncia, e rifiuta una chiamata che gli scope del token chiamante non ammettono, quindi il limite è del server oltre che del client.
Questo conta perché la superficie dei tool è la riga di comando. Tutto ciò che puoi digitare, un assistente può chiamarlo — comprese le operazioni che modificano la tua macchina.
Alcune di queste operazioni si spingono oltre il workspace in cui stai lavorando, e non possono essere annullate eseguendo qualcos’altro. Queste sono quelle da conoscere per nome, a partire da quella di portata più ampia:
publish-entity,publish-artifact,sign-artifactsedeprecate-artifactsi spingono del tutto oltre la macchina. Mettono byte, una firma o un marcatore di ritiro in un registry, quindi ciò che modificano è ciò che risolve ogni consumatore di quel registry — non solo ciò che fa questa macchina. Ripubblicare contenuti diversi su un tag viene rifiutato anziché offerto, quindi nulla qui annulla una pubblicazione; la risposta è pubblicare una nuova versione. Una firma e un marcatore di ritiro lasciano intatti i byte dell’artefatto, ma chiunque scarichi quell’artefatto in seguito scarica anche loro, e nessuno dei due può essere richiamato da chi lo possiede già. Su standard input e output le stesse quattro capacità sono raggiungibili anche comecli-push,cli-push-artifact,cli-signecli-deprecate, che eseguono i comandi; via HTTP quei quattro tool non esistono.- La firma usa credenziali. Su standard input e output, la firma keyless prende un token di identità dall’argomento
identity_tokendella chiamata, daAGGREGA_IDENTITY_TOKENoSIGSTORE_ID_TOKENnell’ambiente del server, o dall’endpoint OIDC ambientale di GitHub Actions dove ne è raggiungibile uno;key_pathseleziona invece una chiave conservata offline. Un assistente che può chiamare questi tool può quindi firmare a tuo nome, con qualunque identità la macchina che esegue il server possieda già — e una firma è una dichiarazione su chi garantisce per un artefatto, ed è per questo che questa è l’operazione su cui riflettere di più prima di consentirla. Su un listener firma solo un token inviato nella chiamata: nulla nell’ambiente del server viene letto, e nessuna chiave conservata sull’host può essere selezionata da un argomento o dalla configurazione del workspace servito, come spiega Quali credenziali consuma una chiamata. aggrega cache evictriduce lo store dei moduli compilati, eaggrega cache clearlo svuota. Quello store è condiviso da ogni progetto Aggrega sulla macchina. I moduli rimossi vengono ricompilati su richiesta, quindi nulla va perso in modo permanente — ma la build successiva di qualsiasi progetto ne paga il costo.aggrega cache clearrimuove anche il bundle della documentazione letto da ogni progetto sulla macchina, che viene scaricato di nuovo la volta successiva che uno di essi lo acquisisce.aggrega cache prunelibera le voci della cache degli artefatti a cui nessun lockfile fa riferimento. Dove il lockfile di un progetto non è presente per essere letto, i suoi artefatti fissati non sono protetti da esso, e liberarli significa doverli scaricare di nuovo.aggrega registry addeaggrega registry removescrivono per impostazione predefinita nella configurazione condivisa tra tutti i workspace, quindi modificano ciò che viene risolto ovunque sulla macchina, non solo qui.aggrega registry addchiede inoltre al registry che indica la trust policy che quel registry pubblicizza e fissa ciò che riceve, esattamente come fa da un terminale. In un workspace offline quel recupero viene rifiutato prima di qualsiasi connessione, quindi aggiungere un registry diverso dall’hub ufficiale viene rifiutato — codice breveE0310, con le stesse parole — a meno che la chiamata non forniscaidentityokey;aggrega config init, che non accetta nessuno dei due, può inizializzare offline solo l’hub. Su standard input e output sono raggiungibili comecli-registry-addecli-registry-remove, e l’inizializzazione comecli-config-init, che eseguono i comandi; via HTTP quei tool non esistono.pulllegge da un registry e scrive all’interno del workspace a cui è puntato. Scrive il lockfile di quella Release, riempie la cache degli artefatti con ciò che ha risolto, e registra accanto al lockfile l’identità di ogni plugin che restituisce verdetti collegato al tuo workspace. Inviato conpin_sources— o in un workspace in cuipin_sources_at_pullè attivo e con una chiamata che non lo invia come false — esegue anche il passaggio di pin dell’autore dell’entità sulle Recipes e sulle FeatureRecipes che la Release compila dalle tue directory di catalogo, scrivendo l’entity.lockaccanto a ciascuna; senza di esso, un pull su un’entità del genere il cui lock non registra alcun pin per un input che legge viene rifiutato, indicando il passaggio. I file delle entità stessi non vengono mai scritti. Nulla di tutto ciò lascia la macchina, e risolvere di nuovo è il modo per cambiare ciò che ha registrato, quindi questa è la più lieve tra le operazioni qui descritte che scrivono. È uno dei tool pensati per il ciclo di authoring che scrivono all’interno del workspace:pinscrive l’entity.lockaccanto alla Recipe o alla FeatureRecipe che indichi, come spiega Fissare gli input propri di un’entità;gen-catalogscrive entità Plugin generate nella directory che indichi;edit-documentapplica una modifica strutturata e delimitata a un documento che hai già e lo riscrive, preservando ogni byte che la modifica non tocca, come spiega Applicare una modifica delimitata a un documento; eimporttrasforma una descrizione prodotta da un altro tool in file di authoring in bozza e li scrive nel workspace, come spiega Trasformare una descrizione esterna in entità in bozza; escaffold, inviato conexample, scrive uno degli esempi eseguibili della documentazione in una directory nuova o vuota,dir, come faaggrega scaffold --example, cosa che via HTTP lo scope di scrittura nel workspace ammette. Quella directory di output, il guest chegen-cataloglegge e qualsiasi overlay tu gli fornisca sono ciascuno relativi alla radice del workspace, o assoluti su standard input e output, lo stesso contratto usato da ogni altro argomento di percorso su questa superficie. Su standard input e output la stessa capacità è raggiungibile anche comecli-pull, che esegue il comando; via HTTP quel tool non esiste.buildlegge lo stesso registry ed esegue la stessa scrittura quando gli inviiauto_pull, e solo allora. Risolvere le dipendenze di una Release è un’unica operazione ovunque venga richiesta, quindi una build a cui si chiede di risolvere prima fa esattamente ciò che fapulle poi esegue il rendering su ciò che ha scritto — ed è per questo che ha la stessa portata e non una minore. Inviato conwrite, scrive anche gli artefatti renderizzati indist/nella radice del workspace, dove li scriveaggrega builde tramite la stessa scrittura, quindi per quella chiamata raggiunge il workspace; non scrive altrove, e undistche è un link che porta fuori dal workspace viene rifiutato prima che qualsiasi cosa al suo interno venga rimossa o scritta. Senza nessuno dei due argomenti, che è il comportamento predefinito,buildesegue il rendering a partire dai pin che il workspace possiede già e non raggiunge nulla. Leggi Eseguire una build sul contenuto che una Release fissa già per sapere cosa cambia l’argomento e cosa lascia invariato.
I tool di inventario lo dicono nelle proprie risposte. cache-status contrassegna ogni classe di cache con la sua portata — workspace per la cache degli artefatti nella directory di cache del progetto stesso, machine per gli store condivisi da tutti i progetti — e indica esplicitamente quelli a livello di macchina, così un assistente che legge l’inventario prima di proporre una pulizia sa quali parti di esso non sono solo tue. Le operazioni di manutenzione riportano la stessa portata per ogni elemento che hanno rimosso. Ciascuno dei quattro risultati di pubblicazione riporta un proprio reach, che contiene registries — ogni host di registry a cui la chiamata si è rivolta, ciascuno indicato una volta, nell’ordine in cui vi si è rivolta per la prima volta — e beyond_this_machine, che si ricava da ciò che la chiamata ha effettivamente allegato e non da ciò che ha chiesto: true una volta che ha caricato contenuti o allegato una firma, una data di pubblicazione o un marcatore di deprecazione, e false per un dry run e per una chiamata che ha trovato tutto già presente, come una pubblicazione eseguita di nuovo su una versione completa o un batch di firma i cui riferimenti erano già tutti firmati.
Dove fissi il confine. Il protocollo stesso non definisce permessi per singolo tool — la sua autenticazione riguarda se un client può connettersi, non quali tool può poi chiamare. La decisione sui permessi risiede nel tuo client MCP. I client più diffusi possono in genere consentire e negare singoli tool per nome di un singolo server, e disattivare del tutto un server per un determinato progetto; il nome e la posizione dell’impostazione variano da client a client, quindi consulta la documentazione del tuo client sui permessi dei tool. Se vuoi le letture e non le scritture, consenti lì i tool che vuoi e nega il resto. Una configurazione permissiva, o un client senza un’impostazione del genere, lascia chiamabile ogni tool esposto.
Scoprire cosa contiene un workspace
La maggior parte degli strumenti accetta un soggetto: il nome di un’entità o il percorso di una Release. I due seguenti non ne accettano nessuno, e sono il modo in cui un assistente appena arrivato ne ottiene uno.
list-entities risponde a cosa contiene il workspace e list-releases risponde alla domanda più ristretta che il resto della superficie continua a porre: quali Releases ci sono. Nessuno dei due accetta un soggetto, perché ciò che un workspace contiene è una proprietà del workspace e non di qualcosa che il chiamante deve conoscere prima.
Ciascuno risponde in una di due forme, e una chiamata che non indica alcuna forma riceve il riepilogo. Questa impostazione predefinita è propria di questi due soli, ed è l’opposto di quella adottata da build, describe e validate. A quelli si chiede di un soggetto che il chiamante ha già nominato, quindi la risposta più completa è quella richiesta e quella sintetica è facoltativa. A questi due si chiede cosa c’è qui, da parte di un chiamante che non ha ancora nulla da nominare e nessun modo di sapere quanto costerà la risposta prima che arrivi — quindi riportano prima la dimensione e la forma del workspace e consegnano i record solo quando vengono richiesti.
Il riepilogo dice cosa c’è qui e in che quantità. list-entities riporta la radice del workspace — trattenuta su HTTP, come illustra Cosa dice una risposta sul filesystem del server — il numero totale di entità e un conteggio per tipo; list-releases riporta il totale e un conteggio per directory di primo livello, così scopri quante Releases ci sono e in quale parte dell’albero si trovano. Entrambe le suddivisioni sono lette dai documenti stessi, quindi un workspace organizzato in un modo che nessuno aveva previsto viene riepilogato con la stessa accuratezza di uno che non lo è. Entrambe contengono una riga per tipo, o per directory di primo livello, quindi la loro dimensione segue quanti tipi dichiara un workspace e in quante directory si trovano le sue Releases, non quanti documenti contiene: moltiplica per cento i documenti di un workspace, lasciandone invariati i tipi, e il riepilogo cresce solo dei pochi byte che servono a scrivere i numeri più grandi. È dichiarare più tipi che lo allunga. Nessuno dei due è una prima pagina di record, e la differenza è proprio questa: «ecco alcune delle entità» è una risposta diversa da «ecco di cosa è fatto il workspace», e solo la seconda ti dice se vuoi dei record e quali.
Invia response_format: detailed per ottenere i record, che arrivano una pagina alla volta. list-entities riporta allora tipo, nome, apiVersion, descrizione, etichette e file sorgente di ogni entità, letti direttamente dal documento che la dichiara. Riporta anche le Features dichiarate dalle directory di catalogo configurate, in modo che una Feature che ti viene proposta come agganciabile sia una che puoi anche consultare; queste non hanno file sorgente, perché l’unico percorso che hanno è uno sulla macchina su cui gira il server, e ciascuna dice da dove proviene, così un file vuoto si legge come «risolto dal catalogo» e non come un valore mancante. list-releases riporta il percorso di ogni Release, e lockfiles associa ogni percorso restituito al percorso del lockfile di quella Release, nella stessa coordinata: il file che pull scrive per essa e che build legge, lo stesso file indicato dalle risposte del language server sulle Release. La mappa descrive i percorsi contenuti in questa risposta, quindi segue la pagina, e il riepilogo la contiene vuota.
detailed e concise sono gli unici valori che response_format accetta, e vengono confrontati in modo esatto. Qualsiasi altra grafia — una parola diversa, un uso diverso di maiuscole e minuscole, o spazi attorno a uno dei due — viene rifiutata, e il rifiuto indica cosa è stato inviato insieme ai valori che l’argomento accetta. Omettere response_format è il modo per chiedere il valore predefinito, che per questi due strumenti è il riepilogo. Lo stesso vale ovunque compaia l’argomento: build, describe e validate accettano gli stessi due valori alle stesse condizioni, e il loro valore predefinito è la forma più completa anziché quella sintetica.
I record sono limitati che tu li limiti o no. limit è quanti ne contiene una risposta, tra 1 e 500, e il valore predefinito è 50 — quindi una chiamata che chiede record senza indicare una dimensione di pagina è comunque limitata, e nessuna invocazione di uno dei due strumenti restituisce una risposta la cui dimensione dipende da quella del workspace. offset indica da dove iniziare nell’elenco, contando da 0. Entrambi limitano i record, quindi nessuno dei due ha effetto sul riepilogo, che non ne contiene. Un limit fuori da quell’intervallo viene rifiutato e il rifiuto indica il limite; un offset oltre la fine dell’elenco torna vuoto, perché lì non c’è nulla, non perché la domanda sia sbagliata.
Continua un elenco leggendo tre campi dalla risposta. count è quanti record contiene il workspace, offset e returned dicono dove inizia questa risposta e quanti ne contiene, e more_remaining dice se ne restano. Finché more_remaining è true, chiama di nuovo con offset più returned. Quel segnale è calcolato dalla pagina rispetto al totale anziché scritto nella risposta, quindi non può riportare che non resta nulla mentre restano dei record.
Tutto questo conta perché gli strumenti che accettano un nome rifiutano quello che non riescono a risolvere anziché rispondere con un risultato vuoto. Il rifiuto è voluto — una risposta vuota presenterebbe un nome digitato male come un soggetto senza nulla da offrire — ma significa che un chiamante che non ha un nome non può ottenerne uno tirando a indovinare. Elencare è il modo per ottenerne uno.
I due si combinano, tra loro e con il resto della superficie:
- Chiama
list-entitiesper il riepilogo per vedere quali tipi contiene il workspace e quanti di ciascuno, poi chiamalo di nuovo conresponse_format: detailedper i record, prendi un nome dal risultato e passalo adescribeper vedere la definizione completamente risolta di quell’entità. È la definizione con cui rispondeaggrega/entityDefinitiondel language server, trasportata come JSON: ogni chiave con il nome che scrive il suo autore, nell’ordine in cui la definizione la contiene, uno schema come lo schema scritto dall’autore, e uno schema che l’entità non dichiara omesso — i socket di un Component, ciascuno con gli slot che le sue connessioni possono riempire. - Fai lo stesso con
list-releases, prendi un percorso dal risultato dettagliato e passalo adescribeobuildcome la Release su cui lavorare. - Il percorso restituito da
list-releasesè relativo alla radice del workspace, che è la stessa coordinata sotto cuilist-entitiesriporta un file, quindi le due risposte si allineano sul file e si possono leggere insieme. Il suo lockfile, sottolockfiles, è relativo alla stessa radice, quindi puoi leggere o confrontare quel file senza dover capire dove si trova.
Entrambi decidono cosa conta leggendo il kind di ciascun documento, mai il nome del file. Una Release nominata senza un prefisso convenzionale viene elencata; un file che si limita a chiamarsi come tale no, e compare sotto qualunque tipo dichiari effettivamente. Uno YAML che non dichiara alcun kind — il file dei valori di un chart, un file di configurazione che si trova per caso nell’albero — non è un’entità e non viene riportato, e nemmeno un documento appartenente a un altro progetto, come un manifest Kubernetes renderizzato. Un documento conta come entità quando dichiara sia un kind sia un nome, perché sono questi due insieme a renderlo indirizzabile in seguito, e non dichiara alcun apiVersion al di fuori del gruppo proprio di Aggrega. Uno che non dichiara alcun apiVersion viene riportato, essendo un documento Aggrega con un campo mancante e non il file di un altro progetto. list-releases non cerca in alcuna directory fuori dalla radice del workspace, quindi una Release che il tuo editor mostra sotto un link che porta a una di queste directory non viene elencata; unread_linked_dirs indica ogni link che si trova dove l’elenco leggerebbe una directory e che porta fuori dalla radice — con il percorso del link stesso relativo alla radice, mai con la sua destinazione — in entrambe le forme e su entrambi i trasporti, ed è vuoto dove non ce ne sono. Né legge un file fuori dalla radice attraverso un link: unread_linked_files indica, allo stesso modo, ogni link il cui nome termina in .yaml o .yml e che porta a un file fuori dalla radice, qualunque cosa contenga quel file, quindi una Release raggiunta solo attraverso un tale link non viene elencata — a meno che la configurazione del workspace non nomini quella Release, come build.authoring_release o come chiave di workspace.releases, nel qual caso viene letta ed elencata nella posizione del link stesso e non indicata. Nemmeno list-entities legge alcun documento dietro un link che porta fuori dal workspace — non cerca in alcuna directory fuori dalla radice e non legge alcun file fuori da essa, qualunque cosa dichiari quel file — e indica ciascuno di questi link allo stesso modo, nei propri unread_linked_dirs e unread_linked_files, in entrambe le forme e su entrambi i trasporti. Ciò vale qualunque cosa dichiari il documento, con l’unica eccezione che fa list-releases: una Release che la configurazione del workspace nomina, come build.authoring_release o come chiave di workspace.releases, viene letta ed elencata nella posizione del link stesso e non indicata, mentre un file nominato da una di queste impostazioni che dichiara qualcosa di diverso da una Release non viene elencato, e il suo link viene indicato. Le directory di catalogo configurate sono il modo in cui un workspace legge altre entità conservate altrove, quindi un link a una directory che la configurazione elenca sotto catalog_dirs, o a una directory al suo interno, non viene indicato da nessuno dei due elenchi: la configurazione l’ha raggiunta. Le Features che list-entities prende dalle directory di catalogo non ne includono mai una dietro un link che porta fuori dalla directory entro cui devono restare le letture di una directory di catalogo — il workspace, per una directory di catalogo al suo interno, o la directory stessa, per una che la configurazione nomina al di fuori di esso — quindi un’entità indicata come dietro un link non letto non viene mai elencata accanto a quel nome. Un link che l’elenco esclude — per il suo nome, per la sua posizione o per un .gitignore — non viene indicato, e con release nemmeno uno sotto una directory di catalogo che leggono solo altre Releases; un .gitignore che è esso stesso un link che porta fuori dal workspace non viene letto. Dove uno di questi elenchi indica un link, la risposta testuale si chiude con una riga a sé che lo segnala.
Un workspace il cui file di configurazione porta fuori da esso viene comunque elencato, e per esso non si risponde a nient’altro. Dove il .aggrega-config.yaml del workspace stesso, o l’overlay gestito dalla CI accanto a esso, è un link che porta fuori dal workspace, la sua configurazione non viene letta, come in un terminale, e nulla di ciò che avrebbe configurato viene letto al suo posto. Il server si avvia comunque su standard input e output, e lo segnala con una riga sul suo flusso di errore. list-entities e list-releases rispondono con i documenti del workspace stesso, letti senza nulla di configurato, quindi non vengono elencate le Features di alcuna directory di catalogo. Ciascuno indica il file trattenuto in unread_linked_files, e nella riga che chiude il suo testo, che l’elenco lo abbia incontrato o no — quel nome è il modo per capire che la configurazione del workspace porta fuori da esso. Un elenco a cui è stato inviato release o catalog_dirs, e ogni altro strumento che nomina quel workspace, dipende dalla configurazione che non è stata letta, quindi ciascuno viene rifiutato con E0321, che indica il link e dove porta. Un server a cui la riga di comando dice di mettersi in ascolto — --transport http, o --listen — non si avvia su un workspace del genere, perché l’indirizzo a cui si collegherebbe, il suo certificato e chi può chiamarlo sono ciò che quella configurazione decide. Rimuovi il link, o fallo puntare a un file all’interno del workspace, e la chiamata successiva legge la configurazione. Vedi il confine del workspace.
Chiedere nei termini di una Release
Un workspace può assegnare a ogni Release directory di catalogo proprie — vedi Assegnare a una Release directory di catalogo proprie — e mantenere così una variante di un’entità per ogni Release, una accanto all’altra. Tre strumenti che altrimenti rispondono sulle directory di catalogo del workspace stesso accettano un release opzionale, il percorso di un file di Release, e rispondono allora nei termini di quella Release:
list-entitiesconreleaseelenca le entità che quella Release vede. Le Features elencate sono quelle dichiarate dalle sue directory di catalogo, e un documento del workspace sotto una directory di catalogo che leggono solo altre Releases viene escluso, quindi ogni variante viene elencata per la Release che la usa nel build e per nessun’altra. Un documento che non si trova sotto alcuna directory di catalogo — una Release, il suo Aggregate e il suo Manifest scritti accanto ai cataloghi — viene elencato per ogni Release.describecon unnamee unreleaserisolve il nome attraverso le directory di catalogo di quella Release, quindi un nome dichiarato da più varianti si risolve in quella con cui quella Release esegue il build. Un nome che quelle directory non risolvono viene rifiutato con una spiegazione che indica la voce di quella Release sottoworkspace.releases. Un riferimento a un registry viene letto dal suo registry qualunque sia la Release nominata, quindi viene rifiutato accanto a unrelease. Unreleaseinviato senzanameè comunque la Release chedescriberiepiloga.validatecon unentitye unreleaseesegue i controlli sulla singola entità nei termini di quella Release: i riferimenti dell’entità — il Component che una Recipe implementa, una SchemaLibrary a cui fa riferimento un pilastro — si risolvono attraverso le directory di catalogo di quella Release, e la risposta indica la Release accanto all’entità. Non viene validata alcuna chiusura; unreleaseinviato senzaentityè comunque l’ambito della Release.catalog_dirsviene anteposto alle directory della Release qui come ovunque. Una directory che la configurazione del workspace elenca e che non è una directory — perché lì non esiste nulla, per esempio — per quella Release, o per il workspace quando non viene inviato alcunrelease, fa rifiutare la chiamata prima che venga controllato alcunché, con il testo che riporta il rifiuto che le dà ogni comando, indicando la voce e il file e la riga di configurazione che la elencano (Da dove vengono lette le entità locali), come la rifiutaaggrega validate.
Un release che nomina un file inesistente, o una directory, viene rifiutato da tutti e tre anziché ricevere risposta nei termini del workspace. Se non se ne invia nessuno, la risposta riguarda le directory di catalogo del workspace stesso.
describe, quando cerca un nome, rifiuta una directory di catalogo attraverso cui risolverebbe il nome e che non può essere percorsa, come la rifiuta aggrega inspect — le directory di quella Release se viene inviato un release, quelle del workspace stesso se non ne viene inviato nessuno, e quelle che la chiamata indica in catalog_dirs. Una directory indicata dalla chiamata che non esiste, o che esiste ma non può essere letta, viene rifiutata prima che il nome venga cercato, e il testo indica la directory come la riporta la riga di comando, su una sola riga — la directory, catalog load e il motivo fornito dal filesystem — anziché risolvere il nome dalle directory rimanenti. Una directory che la configurazione del workspace elenca e che non è una directory viene rifiutata nello stesso momento, con il testo che riporta il rifiuto che le dà ogni comando (Da dove vengono lette le entità locali). Un release che nomina un file inesistente viene rifiutato prima di questo, come sopra. Una directory di catalogo che contiene un link che porta fuori dalla directory entro cui devono restare le sue letture viene rifiutata allo stesso modo, con il testo che indica il link e dove porta, perché un nome risolto senza di essa potrebbe risolversi al suo posto in un’altra entità con lo stesso nome. Descrivere la chiusura delle dipendenze di una Release non risente di una directory che non può essere percorsa, e risponde sulle directory che possono esserlo, come fa aggrega inspect --closure — tranne una directory che la configurazione del workspace elenca per quella Release e che non è una directory, che rifiuta come la rifiuta aggrega inspect --closure; un link che porta fuori dalle letture di una directory di catalogo, o fuori dai documenti accanto alla Release, la interrompe, come interrompe un build.
validate con un entity riporta un rendering che non può giudicare come non tentato, nei termini di una Release o senza. Colloca il Component di una Recipe in un build sintetizzato che non collega alcuna connessione e non aggancia alcuna Feature, quindi una Recipe il cui rendering si interrompe mentre i suoi template — inclusi i file e le voci di libreria che importano — leggono qualcosa sotto .context.inject, .context.uses o .features risponde valid: true senza nulla in diagnostics; il suo testo riporta Render: not attempted (this Recipe reads values a build of one cannot supply), le letture per cui è stato accantonato e la frase su cui il rendering si è fermato. Ciò che decide è ciò che la Recipe legge, quindi un difetto proprio della Recipe accanto a una tale lettura viene accantonato con essa, mentre un template che non viene analizzato e un riferimento che il rendering rifiuta rispondono comunque valid: false. aggrega validate dà lo stesso verdetto sugli stessi input.
validate con un entity riporta un’asserzione fallita come avviso, nei termini di una Release o senza. Un’asserzione che chiama fail — quella della Recipe stessa, o una dichiarata dal Component che implementa — risponde valid: true senza nulla in diagnostics. Il build sintetizzato contiene segnaposto e valori predefiniti dello schema al posto dei valori che imposta una Release reale, quindi un’asserzione su un tale valore lì fallisce che la Recipe sia corretta o no, e il controllo non può distinguere un’asserzione che attende una Release da una che è difettosa. Il fallimento segue le altre notices, con il messaggio completo dell’asserzione chiuso dalla frase A Release must satisfy this assertion before a build of it can pass., e il testo lo riporta su una riga aperta da warning:, accanto alla riga di report che dice dove si è fermata l’esecuzione. Un’asserzione che si ferma su una chiave che legge ma non trova è un difetto nel suo stesso testo e non un’asserzione fallita, e viene giudicata come qualsiasi altra interruzione; il build di una Release che non soddisfa un’asserzione viene comunque rifiutato a causa di essa. aggrega validate dà lo stesso verdetto sugli stessi input.
Leggere la configurazione in vigore e i plugin che questo server risolve
config-show riporta la configurazione in vigore e quale livello ha deciso ogni impostazione. plugin-list riporta i plugin che questo server può risolvere e ciò che ciascuno dice di sé. Entrambi non leggono né scrivono nulla, quindi nessuno dei due raggiunge alcunché e aggrega:read li ammette — e nessuno dei due ti chiede di nominare un soggetto, perché ciò che è configurato e ciò che si risolve sono proprietà di questo server e non di qualcosa che devi conoscere prima. Ciascuno accetta un workspace_root opzionale su standard input e output; su HTTP quell’argomento viene rifiutato, come illustra Un processo, un workspace.
Insieme rispondono a una domanda in due metà: se una capacità è assente o semplicemente non configurata qui. La configurazione dice se un provider, un importer o un controllo di governance sia agganciato o no; la lettura dei plugin dice se un aggancio raggiunge un guest che si risolve, si descrive e serve ciò che dichiara. Da qualunque altro punto di questa superficie le due cose sembrano uguali, e richiedono passi successivi opposti.
config-show riporta una voce per impostazione: il suo field, il suo value effettivo e la source che l’ha decisa — un file di configurazione, una variabile d’ambiente, un flag della riga di comando o i valori predefiniti integrati. Accanto a esse, layers contiene i livelli che hanno contribuito in ordine di precedenza, dal più basso. La source di un’impostazione è scritta esattamente come la voce corrispondente in layers, quindi le due si uniscono direttamente, e un’impostazione decisa dai valori predefiniti non indica alcun livello, perché i valori predefiniti non sono un livello che ha contribuito. Il livello globale è il file che seleziona la riga di comando del server stesso — quello indicato da --config all’avvio, altrimenti quello indicato dalla variabile d’ambiente AGGREGA_CONFIG, altrimenti la posizione predefinita — quindi un’impostazione decisa da quel file viene attribuita a quel file, esattamente come la attribuisce aggrega config show --origin, e un flag come --offline passato al server viene riportato come quel flag. Non accetta né response_format né una dimensione di pagina: le impostazioni sono l’insieme fisso di cui questo binario tiene conto e ogni risoluzione le riporta tutte, quindi la dimensione della risposta segue il binario e non ciò che configuri.
plugin-list risponde nelle due forme usate dagli elenchi del workspace, e una chiamata che non indica alcuna forma riceve il riepilogo. Il riepilogo è un conteggio per gruppo, e i gruppi sono due — embedded, i guest compilati in questo binario, che si risolvono senza accesso a filesystem, cache o rete, e configured, i binding del workspace stesso. Invia response_format: detailed per i record: il gruppo di ogni plugin, il riferimento sotto cui è stato trovato, dove quel riferimento è stato associato, il tipo, la versione, il commit, le capacità servite, i tipi di input renderizzati, l’assembly di confine e gli export che dichiara di sé, il suo stato di prontezza dove ne ha uno, e se si è risolto. I record sono limitati da limit e offset alle stesse condizioni dell’elenco delle entità, con count, returned e more_remaining per proseguire. Questa risposta cresce invece con ciò che configuri — quelli integrati sono fissi, i binding sono tuoi — ed è per questo che è paginata, mentre la lettura della configurazione non lo è.
Un plugin che fallisce viene riportato con il suo errore anziché essere escluso dall’elenco. resolved dice se il riferimento ha raggiunto dei byte di modulo, e un plugin che si è risolto ma non è riuscito a descriversi viene riportato esattamente come tale — quindi un aggancio presente e inutilizzabile è distinguibile da uno mai effettuato.
Cosa un listener non ti dice del suo host
Su HTTP nessuna delle due letture riporta un valore che indica una posizione nel filesystem del server. Un client che ha avviato il server gira dove gira il server, quindi ogni posizione che una delle due risposte potrebbe indicare è una che quel chiamante possiede già e può andare a vedere. Un chiamante che raggiunge un listener non ne ha scelta nessuna, non può agire sapendole, e un server che le ha pubblicate a un tale chiamante non può ritirarle. Su quel trasporto quei valori sono assenti; su standard input e output sono tutti presenti. È la regola che segue ogni risposta di questa superficie, come illustra Cosa dice una risposta sul filesystem del server, e queste due letture sono dove arriva più lontano, perché la maggior parte di ciò che riportano è configurazione che indica posizioni.
Cosa viene trattenuto. Da config-show: il value di un’impostazione dove il valore stesso di quell’impostazione è una posizione — un indirizzo di servizio o di health check, che può essere un file socket; un file di certificato, di chiave privata o di set di chiavi; una directory di catalogo, e le directory di catalogo proprie di una Release sotto workspace.releases, ogni voce delle quali ha come chiave un file di Release; un riferimento a un plugin; una Release di authoring. Anche la source di un’impostazione dove il livello che l’ha decisa è un file di configurazione, poiché un tale livello è indicato dal percorso stesso di quel file — e, con la stessa grafia e per lo stesso motivo, le voci di layers relative a file di configurazione. Da plugin-list: l’uri di un plugin dove quel riferimento è esso stesso un percorso del filesystem, e il testo di un errore di risoluzione o di descrizione, che è composto dalle posizioni tentate e quindi indica posizioni che il riferimento stesso non indica. Da entrambi: workspace_root.
Cosa viene riportato per intero, su entrambi i trasporti. Un riferimento a un registry, una versione, un commit, un digest, una capacità servita, un’etichetta di prontezza, il nome di una variabile d’ambiente o di un flag, e un livello che non è un file. origin in un record di plugin è uno di questi: è la chiave di configurazione in cui è stato scritto un binding, o il digest fissato che porta un’estensione di comando installata, e un plugin integrato non ne porta alcuno — quindi è la stessa stringa ovunque venga letto il plugin. resolved è un altro: se un plugin è fallito viene riportato a ogni chiamante, anche dove il motivo non lo è.
Un valore assente dice sempre di essere stato trattenuto, ed è questo che rende la risposta utilizzabile. Un valore trattenuto viene riportato come assente con un contrassegno accanto — value_withheld e source_withheld su un’impostazione, withheld su una voce di livello, uri_withheld e error_withheld su un record di plugin, e workspace_root_withheld sulla risposta. Un’impostazione che nessuno ha impostato porta il valore vuoto in cui si rende la sua forma, e non porta alcun contrassegno. «Questo server non ti dice dove si trova la chiave di firma» e «non è configurata alcuna chiave di firma» sono risposte diverse che richiedono passi successivi diversi, e una lettura che le riportasse in modo identico non ti direbbe nulla su cui agire. Ogni risposta porta anche host_locations_withheld, sempre, che dice quale delle due risposte hai in mano: una risposta senza contrassegni è altrimenti la stessa sia che questa regola l’abbia plasmata e sull’host non ci fosse nulla da trattenere, sia che non sia mai stata applicata. Il testo leggibile accanto ai campi dice la stessa cosa a parole.
La regola è una proprietà e non un elenco di nomi di campo: un valore viene trattenuto quando indica una posizione nel filesystem dell’host, chiunque l’abbia impostato e da qualunque livello provenga. Un valore aggiunto in seguito a una delle due letture è soggetto a quella stessa proprietà.
Su standard input e output ogni capacità è raggiungibile anche come lo strumento che porta il nome del suo comando — cli-config-show e cli-plugin-list — che esegue quel comando in un processo separato e restituisce il testo che ha stampato; su HTTP quegli strumenti non esistono. I due descritti qui portano invece i valori, così puoi leggere se una capacità è agganciata, o individuare la versione di un plugin, senza dover ricostruire da un layout a colonne ciò da cui è stato reso.
Chiedere cosa può agganciarsi e cosa può connettersi a cosa
Due strumenti rispondono alle domande su cui altrimenti un assistente dovrebbe tirare a indovinare: quali Features possono agganciarsi a un nodo e a cosa può connettersi un nodo. Entrambi eseguono lo stesso abbinamento di etichette che esegue il compilatore, quindi ciò che l’assistente ti propone è l’insieme che un build abbinerebbe e non un insieme dedotto dallo schema.
attach-candidates riporta le Features la cui applicabilità dichiarata è soddisfatta dalle etichette di un nodo. Indica il nodo in esattamente uno di tre modi:
node— ilmetadata.namedi un’entità del workspace, come lo riportalist-entities. L’abbinamento viene eseguito sulle etichette che quel documento dichiara.graph_nodeconrelease— un nodo di un grafo compilato, con la chiave che gli dà il grafo, inclusa la forma qualificata che porta un nodo fornito da un sotto-aggregato. L’abbinamento viene eseguito sulle etichette finalizzate di quel nodo, che sono quelle valutate da un build.labels— un insieme di etichette a sé, che non nomina alcun nodo. Non richiede alcuna coordinata, quindi se hai già le etichette di un nodo questa è la forma da usare; non cerca nulla e non ricostruisce alcun grafo.
La risposta riporta le etichette su cui è stato eseguito l’abbinamento e da quale di questi tre insiemi provengono, così puoi spiegare qualsiasi candidato — o la sua assenza — a partire dalla risposta stessa, senza doverlo ricostruire. Rileggerle in un secondo modo è il punto in cui la tua idea delle etichette di un nodo e quella del compilatore divergono.
Per chiedere cosa può agganciarsi a una connessione tracciata da un nodo, aggiungi connection accanto a graph_node e release — il suo socket e il suo alias, come li ha scritti l’autore. Una connessione porta agganci che riempiono gli slot che il suo socket dichiara sul Component consumatore, quindi la risposta porta allora anche slots: ogni slot che il socket dichiara, con i suoi selector, required, inject, sensitive e description esattamente come li dichiara il Component, e i candidates che possono riempirlo. Sono le Features la cui applicabilità è soddisfatta dalle etichette del nodo e le cui etichette sono ammesse dal selettore dello slot — le due regole a cui un build sottopone un tale aggancio — quindi i candidati di uno slot sono sempre tra quelli del nodo stesso. Dove non può essere riempito nulla, slots è vuoto e noSlotReason dice perché: feature-created-connection (la connessione l’ha tracciata una Feature, e a una tale connessione non viene agganciato nulla), ad-hoc-socket (il socket non è dichiarato dal Component) o no-slot-declared (il socket non ne dichiara alcuno). Non leggere un slots vuoto come «non è stato abbinato nulla»; è proprio ciò che il motivo serve a escludere, ed è assente ovunque esista uno slot. candidates accanto a essi mantiene il suo significato — ciò che può agganciarsi al nodo stesso — e document, se ne invii uno, qui non cambia nulla. connection accanto a node o labels, o senza nominare alcun socket o alias, viene rifiutato, e lo stesso vale per una connessione che il nodo non traccia. Sono le stesse risposte che dà il language server, alle stesse condizioni.
connection-candidates riporta i socket di dipendenza che un’entità dichiara e, per ogni socket, i Components del workspace le cui etichette dichiarate soddisfano il vincolo che quel socket dichiara sui suoi target. Accetta il metadata.name dell’entità in node. A differenza di attach-candidates non ha una forma priva di coordinate: qui non esiste una forma con insieme di etichette, perché i socket sono letti dalla dichiarazione dell’entità nominata stessa.
Le sue due metà non sono ugualmente complete, e la risposta dice quale è quale — non presentarle come un unico elenco. I target sono completi: sono i componenti che lo stesso vincolo ammette durante un build. I socket non lo sono, e non possono esserlo. Un consumatore può inventare una connessione ma può consumare solo ciò che un produttore dichiara, quindi un autore può legittimamente scrivere un socket che l’entità del catalogo non ha mai dichiarato, e i socket dichiarati sono un utile punto di partenza e non l’insieme dei nomi ammessi. Ogni socket dice quindi se è declared o ad-hoc, e la risposta dice se un socket non dichiarato è accettato o no su quell’entità — la superficie di dipendenza di un Component ne accetta uno, perché un autore è proprietario della topologia della propria applicazione; la superficie di aggancio di una Feature no, perché un aggancio partecipa alla topologia che la Feature agganciata dichiara anziché crearne una. Questa apertura è una conseguenza della tua libertà di authoring, non una lacuna: passa socket con un nome che l’entità non dichiara per chiedere di esso.
Entrambi rispondono e si fermano. Nessuno dei due crea un aggancio, crea un arco, scrive in alcun file o propone il testo di uno; comporre e applicare qualsiasi modifica ne segua spetta a te.
Entrambi restituiscono la stessa identità minima usata da ogni altra risposta qui — tipo, nome e file sorgente — e niente di più. Tutto il resto che vorresti mostrare su un’entità si trova già in list-entities per gli stessi tre campi, quindi unisci le due risposte anziché leggere due copie che potrebbero non concordare. Entrambi rifiutano un nome che non riescono a risolvere anziché rispondere con un elenco vuoto, per lo stesso motivo del resto della superficie: una risposta vuota presenterebbe un errore di battitura come un soggetto senza nulla da offrire. Una chiamata con labels non ha alcun nome da digitare male, quindi un risultato vuoto lì significa ciò che dice.
Tutto ciò che il server legge come riferimento viene servito da questa macchina — gli JSON Schema sono integrati nel binario e la documentazione viene letta dalla cache dei bundle di documentazione che la macchina mantiene, come descritto di seguito. La stesura di un documento iniziale, la validazione, la descrizione, la build e il linting vengono eseguiti tutti sul tuo workspace e sulle cache locali, e nessuno di essi raggiunge un registry di propria iniziativa: un rendering serve un riferimento esterno fissato dallo store indirizzato per contenuto e declina uno non fissato anziché scaricarlo, ed è questo che mantiene offline l’intero ciclo di ispezione e rendering. Le letture da registry che puoi chiedere sono due: describe con un riferimento a un registry, che scarica quell’unica coordinata, non scrive nulla e su HTTP raggiunge solo un registry con cui il workspace servito è configurato; e scaffold inviato con example o list, che acquisisce il bundle di documentazione dal registry predefinito del workspace quando la macchina non ne conserva alcuna copia ammessa dalla policy di firma del workspace, verificandolo prima di conservarlo, come fa aggrega scaffold --example. Pubblicazione e firma sono il deliberato rovescio di tutto ciò, e sono trattate sopra.
Tra le due cose si colloca la risoluzione delle dipendenze di una Release, che è l’unica cosa qui che acquisisce: raggiunge un registry perché chiedere di risolvere le dipendenze significa chiedere di scaricarle. Avviene solo quando lo chiedi, e ci sono esattamente due modi per chiederlo — chiamare pull, il cui unico compito è questo, oppure inviare auto_pull a build, che esegue quella stessa risoluzione come primo passo del build. Nient’altro esegue un pull per conto tuo, e un build a cui non hai inviato auto_pull non raggiunge alcun registry. L’unica impostazione che cambia questo è l’auto_pull del workspace stesso: un workspace configurato in quel modo chiede a ogni build al suo interno di risolvere prima, ovunque quel build venga eseguito, come descritto di seguito.
L’unica eccezione tra queste letture di riferimento è l’acquisizione del bundle di documentazione stesso, e avviene lontano da ogni lettura. Il bundle è conservato una volta per macchina, nella cache condivisa da ogni progetto Aggrega, una copia per ogni registry e versione — quindi un server avviato in una cartella in cui non è possibile creare una cache del workspace lo conserva comunque (vedi aggrega cache). Quando il server si avvia, prima di rispondere a qualsiasi cosa tu invii, cerca lì una copia ammessa dal controllo di firma del tuo workspace — lo stesso controllo a cui risponde un pull del bundle — e scarica il bundle, attraverso le stesse impostazioni di egress usate dal resto della CLI, solo quando non ce n’è nessuna. Il bundle che cerca è quello pubblicato per la versione di aggrega eseguita dal server o, dove per essa non ne è pubblicato nessuno, il più recente pubblicato per una versione precedente — la stessa scelta che fanno aggrega explain e aggrega scaffold --example — e ogni pagina che serve, e ogni spiegazione, viene letta da quello che ha ottenuto. Così le pagine sono già presenti quando qualcosa ne chiede una, qualunque cosa il tuo client invii per prima, e un altro server, o aggrega explain in un altro progetto, trova la stessa copia anziché scaricarla di nuovo.
Servire una pagina è poi una lettura di quella copia, e non raggiunge alcun registry. Prima che una pagina venga servita, le firme conservate accanto alla copia vengono verificate di nuovo con il controllo del tuo workspace, così una copia ammessa dall’impostazione più permissiva di un altro progetto non ti viene servita: dove il controllo fissa una chiave o una trust root quella verifica avviene offline, e dove non fissa né l’una né l’altra — il controllo integrato dell’hub ufficiale è uno di questi — ottiene la trust root pubblica di Sigstore, come fa un pull. Un workspace offline non può scaricare quella trust root, quindi offline verifica rispetto alla trust root che un precedente download online su questa macchina ha lasciato nella cache che il client Sigstore mantiene sotto .sigstore nella tua home directory, per quanto tempo fa sia avvenuto quel download, e non scarica nulla; su una macchina che non l’ha mai scaricata il controllo non può essere eseguito offline, la copia non viene servita e il flusso di log lo segnala. Quella verifica viene eseguita una volta per ogni copia e ogni controllo mentre il server è in esecuzione, e le pagine lette dopo vengono servite in base a ciò che ha ammesso: una copia scaricata nel frattempo, un workspace il cui controllo è diverso — inclusa una trust root fissata modificata sul posto — una lettura effettuata offline, o una lettura offline che trova sulla macchina una trust root diversa viene verificata per conto suo. Una copia rifiutata dal tuo controllo viene ricontrollata alla lettura successiva, così un download che nel frattempo l’ha ammessa non viene scavalcato. Se il bundle non può essere acquisito, o l’unica copia è una che il tuo controllo rifiuta e scaricarla di nuovo con quel controllo fallisce, il server si avvia comunque e ogni altra superficie funziona; le richieste di documentazione rispondono not-found, e il flusso di log del server dice perché.
Compilare in base ai contenuti che una Release fissa già
build esegue il rendering di una Release nei suoi artefatti in memoria, e un rendering può richiedere contenuti da un URL remoto — lo schema dei values di un chart con un riferimento remoto, per esempio. Gli input esterni sono congelati per la durata della chiamata. Un riferimento che il lockfile della Release fissa già viene servito dallo store indirizzato per contenuto, il che è una lettura di contenuti già su disco anziché un recupero dalla rete. Un riferimento che il lockfile non fissa viene respinto e nominato anziché recuperato: ciò che hai chiesto è un rendering, e acquisire un riferimento significherebbe sia raggiungere la rete sia scrivere un blob nello store come effetto collaterale della produzione di byte. Quel congelamento è una proprietà del rendering. La risoluzione è il passo che acquisisce: esegue il rendering della Release per scoprire quali riferimenti remoti richiede quel rendering, li recupera e li registra nella stessa scrittura del lockfile che contiene i pin delle dipendenze. Quindi ciò che la risoluzione cambia è quali riferimenti sono fissati nel momento in cui un rendering viene eseguito, mai ciò che un rendering può raggiungere — e un riferimento che nessuna risoluzione ha fissato viene respinto in una chiamata che ha prima risolto esattamente come in una che non lo ha fatto.
I file tornano come i byte che emette una build reale, e sono due cose insieme a renderlo vero. Una è il congelamento descritto sopra: un riferimento fissato viene letto dallo store anziché recuperato. L’altra è che il lockfile da cui si legge descrive ancora ciò a cui la Release si risolve — quindi build lo verifica, e rifiuta un lockfile che non corrisponde più, esattamente come fa aggrega build in un terminale. Leggere byte fissati non dice nulla, da solo, sul fatto che fossero i byte giusti da leggere.
Tutti e tre gli stati del lockfile, così che il comportamento sia esplicito. Senza alcun lockfile, build esegue il rendering da ciò che il workspace fissa già e respinge ogni riferimento esterno che non può servire, nominandoli uno per uno; lasciato a sé stesso non richiede un lockfile né ne scrive uno, e questo non cambia con la verifica descritta sopra — non c’è alcun lockfile da confrontare, quindi nulla viene rifiutato. Con un lockfile che corrisponde, esegue il rendering. Con un lockfile che non corrisponde più, rifiuta, e il rifiuto indica come superarlo: chiama pull con la stessa release e senza upgrade_targets, che riconcilia il lockfile con ciò a cui la Release si risolve oggi. Il rifiuto riporta anche la forma da terminale di quella stessa operazione, aggrega pull --release <release>. Entrambe le invocazioni lo superano; sono un’unica operazione raggiungibile da due punti, non due istruzioni tra cui scegliere. Dove pull va a buon fine e il rifiuto si ripresenta, le due chiamate hanno risolto su input diversi — il più delle volte catalog_dirs passato a una e non all’altra, o una configurazione del workspace modificata tra l’una e l’altra — e il rifiuto lo dice: chiamale entrambe con gli stessi.
validate e describe, se ricevono solo una release, sono vincolati allo stesso lockfile. Su un lockfile che non corrisponde più a ciò a cui la Release si risolve, ciascuno rifiuta anziché rispondere, con un testo che riporta l’arresto per drift con cui build rifiuta e lo stesso modo per superarlo — come rifiutano da terminale aggrega validate --release e aggrega inspect --closure. Con un lockfile che corrisponde, o senza lockfile, ciascuno risponde come farebbe altrimenti.
Chiedere a una build di risolvere prima le sue dipendenze
Invia auto_pull e la build risolve prima di eseguire il rendering. Esegue la stessa risoluzione che esegue pull — l’operazione stessa, non una seconda scritta per una build, così un workspace riempito da una build e uno riempito da una chiamata pull sono riempiti in modo identico — scrive il lockfile della Release e poi esegue il rendering in base a ciò che ha scritto. Quel passo raggiunge un registry e scrive, cosa che nient’altro in build fa tranne write, e write non raggiunge alcun registry — perciò è disattivato a meno che non venga richiesto.
Risponde ai due rifiuti descritti sopra senza uscire dal protocollo. Una Release che nessuno ha ancora risolto esegue il rendering da qualunque pin si trovi lì e respinge il resto; un lockfile che ha subito una deriva ferma la build senza appello. Inviare auto_pull risolve prima ed esegue il rendering in base a un lockfile derivato dalla chiusura di cui tratta questa build, così entrambi i casi tornano come un rendering anziché come qualcosa da andare a correggere. Dove vuoi la risoluzione e il rendering come passi separati — per leggere cosa è stato fissato prima di eseguirne il rendering — chiama pull e poi build, che sono le stesse due operazioni con uno sguardo in mezzo.
Una chiamata esegue il rendering della Release una sola volta. Scoprire quali riferimenti remoti consuma una Release è esso stesso un rendering, quindi una risoluzione ha già eseguito il rendering della Release di cui tratta la build — in base proprio ai pin che ha appena scritto, con ogni controllo che una build esegue. La build riceve risposta da quel rendering anziché ripeterlo, ed è per questo che inviare auto_pull costa una risoluzione e non un secondo rendering. Solo un rendering che è terminato viene usato in quel modo: dove una risoluzione ha fissato le sue dipendenze ma non è riuscita a finire di scoprire i riferimenti esterni, la build esegue il rendering per conto suo in base ai pin effettivamente scritti, e un riferimento non fissato la arresta allora per nome anziché tornare come un elenco di file che si ferma prima di ciò che una build emette.
Ciò che torna dice cosa è stato risolto. Una build che ha riempito porta dependency_resolution nella sua risposta, nella forma con cui risponde pull: il lockfile che ha scritto, ogni riferimento raggiunto dalla risoluzione con la versione a cui ciascuno si è risolto e da dove la risoluzione di questa build lo ha preso, i conteggi che il lockfile contiene in seguito, e il resoconto che la risoluzione dà di sé riga per riga. Una build che non ha riempito non porta affatto quel campo, quindi la sua presenza è il modo per distinguere le due senza leggere il disco. I file di cui è stato eseguito il rendering sono riportati esattamente come per qualsiasi altra build, e vengono comunque restituiti in memoria a meno che alla chiamata non sia stato inviato anche write — la risoluzione scrive il lockfile e la cache degli artefatti, mai un artefatto.
Un workspace può richiederlo in modo permanente, e una chiamata non può disattivarlo. L’impostazione auto_pull del workspace attiva lo stesso passo per ogni build in quel workspace, e auto_pull su una chiamata si aggiunge a quell’impostazione anziché sovrascriverla: basta l’una o l’altra, e non esiste alcun argomento che sopprima una risoluzione richiesta dal workspace. È lo stesso modo in cui l’impostazione e aggrega build --auto-pull si combinano in un terminale, così un workspace risponde allo stesso modo su qualunque superficie arrivi una build.
Il respingimento viene segnalato anziché assorbito, e con i provider inclusi in questo binario un respingimento ferma il rendering: il provider che ha richiesto il riferimento restituisce il rifiuto, quindi la chiamata risponde con quell’errore e non restituisce alcun file. Il riferimento viene nominato dove un lettore può agire di conseguenza, accanto al comando che lo fissa: aggrega pull --release <path>. Lo stesso fissaggio è raggiungibile su questa superficie come strumento pull, descritto più avanti in Risolvere ciò da cui dipende una Release, così un assistente che incontra questo rifiuto può agire senza uscire dal protocollo. Un rendering con tutti i pin fissati non dice nulla di tutto questo. Vedi aggrega pull per ciò che il fissaggio recupera e registra, e aggrega build, dove un riferimento non fissato viene segnalato e arresta l’esecuzione allo stesso modo.
Scrivere gli artefatti dove li scrive aggrega build
Invia write e il rendering finito viene anche scritto in dist/ nella radice del workspace, dove lo scrive aggrega build. La directory è quella che la riga di comando compone sotto la stessa radice del workspace, e la scrittura è quella che esegue, così per una Release in un workspace aggrega build, aggrega/build del language server senza outputParent e questa chiamata scrivono un unico albero, byte per byte, e nominano quella directory allo stesso modo — la riga finale del comando, outputDirectory del language server e output_dir di questa risposta. Un dist che è un link che porta fuori dal workspace viene rifiutato prima che qualcosa al suo interno venga rimosso o scritto, come in un terminale. Se omesso, che è il valore predefinito, gli artefatti vengono restituiti in memoria e non viene scritto nulla.
La radice del workspace è quella della chiamata stessa. Su standard input e output è la radice del workspace che la chiamata ha risolto, come spiega In quale workspace riceve risposta una chiamata: la radice indicata da workspace_root, altrimenti la radice con cui è stato avviato il server, altrimenti il workspace trovato a partire dalla directory in cui è stato avviato il server — e, dove una Release indicata con un percorso assoluto sposta la chiamata nel workspace di quella Release, la radice di quel workspace. È la radice sotto cui scrive aggrega build per la stessa Release e la stessa radice indicata, così la cartella in cui il server si trova a girare riceve un dist solo dove quella cartella è la radice che la chiamata ha risolto, come accadrebbe in un terminale aperto lì. Su HTTP è il workspace servito dal server, e nulla viene scritto al di fuori di esso.
La scrittura raggiunge il workspace, quindi su HTTP richiede aggrega:workspace-write. Una chiamata a cui è stato inviato write raggiunge il workspace per quella chiamata, esattamente come fa una build che risolve prima le sue dipendenze: una credenziale che porta solo aggrega:read riceve come risposta 403 con il nome di aggrega:workspace-write, e nulla viene scritto, e un server il cui mcp.deny_reach indica workspace rifiuta la chiamata nominando quell’impostazione. Lo strumento resta nell’elenco degli strumenti di ogni chiamante, e una build a cui non è stato inviato write resta disponibile a un chiamante con ambito di sola lettura.
Scrive per ultimo. Anche con auto_pull, la chiamata risolve, esegue il rendering e poi scrive, in quest’ordine. Una chiamata rifiutata in qualsiasi punto precedente — la sua Release, il suo workspace, una directory di catalogo, la risoluzione, il rendering — non scrive alcun artefatto.
La risposta nomina ciò che è stato scritto. output_dir è la directory — per intero su standard input e output, dist su HTTP — e files elenca ogni file scritto, relativo a essa, con il suo contenuto sotto response_format: detailed e il solo percorso sotto concise; il testo dice quanti file sono stati scritti e dove. Una chiamata a cui non è stato inviato write non porta alcun output_dir, quindi la sua assenza è il modo per capire che non è stato scritto nulla. Una scrittura che fallisce dopo che il rendering è terminato — in una radice del workspace in cui nessuno può scrivere, per esempio — risponde come un errore che nomina la directory e la causa, e non elenca alcun file come scritto: parte della scrittura può trovarsi su disco, e nominare come scritti i file di cui è stato eseguito il rendering affermerebbe più di quanto è accaduto.
Nessun argomento nomina una directory, e nessuno chiede una traccia. Dove vanno gli artefatti lo decide il workspace che la chiamata ha risolto, mai la chiamata, e una build scritta da qui non lascia alcuna directory .trace accanto al suo output; una build con traccia è aggrega build --trace.
Cosa ti dice una build oltre ai suoi file
Una build riporta ogni avviso che ha sollevato, nella risposta stessa. Sono i rilievi che aggrega build stampa mentre lavora — un nome a una sola modifica di distanza da uno dichiarato, un parametro che nulla legge, un target che non può rispettare un campo scritto dall’autore, un verdetto di governance che non interrompe la build, una directory di confine che una Release ha ereditato dalla Release che estende e che si risolve nello stesso percorso, una proprietà che un Component o una Feature raggiunti dalla Release dichiarano sia nel pilastro values sia nel pilastro infra. Nessuno di essi cambia l’esito: una build che riporta avvisi è comunque riuscita, e i file che restituisce sono i file che ha prodotto. Arrivano nell’ordine in cui li stampa un terminale, così chi confronta i due trova una sola sequenza anziché due: prima tutto ciò che il rendering ha sollevato, nell’ordine in cui l’ha sollevato, poi i rilievi sulla Release e su ciò che raggiunge, che aggrega build stampa una volta terminato il rendering, e per ultimo, in una build inviata con write, l’avviso che indica ogni file che la scrittura ha trovato accanto ai propri e che non ha scritto, e che lascia al suo posto — quello che aggrega build stampa una volta scritti i suoi file (File che la build non ha scritto).
Sono nella risposta anziché solo nel testo di riepilogo perché un assistente che guida questa superficie non legge alcun terminale, e un rilievo di cui nessuno viene informato è un rilievo che non è stato fatto. Ciascuno porta una severity — warn per qualcosa che richiede attenzione, info per un’osservazione registrata — e un message; un code dove la sua classe ne assegna uno, così puoi reagire a una condizione specifica senza confrontare testo; e un key_path che nomina la chiave nel documento scritto dall’autore a cui si riferisce il rilievo, dove si riferisce a una. Un rilievo sulla forma della topologia distribuita non nomina alcuna chiave, perché le sue coordinate sono quelle del deployment anziché di un documento, e dice invece nel suo messaggio ciò che riguarda.
Due tipi di rilievo che un terminale stampa raggiungono questa risposta in un punto diverso da advisories, perché ciascuno ha una collocazione che dice di più. Un marcatore di deprecazione registrato si trova in deprecations, sia che il lockfile l’abbia registrato rispetto a un riferimento fissato, sia che il record di fiducia dei plugin accanto a esso l’abbia registrato rispetto a un plugin collegato in un ruolo che restituisce un verdetto di accettazione o rifiuto. describe di una Release indica lo stesso insieme nelle proprie deprecations, e validate di una Release tra le sue notices, ciascuno lasciando il verdetto com’è; un record di fiducia presente ma illeggibile fa rifiutare l’una o l’altra chiamata anziché passare per uno che non registra nulla. Un genitore da cui un’entità eredita e che non è stato possibile risolvere ferma la build, quindi viene nominato nel testo del rifiuto anziché elencato come un rilievo che non ha cambiato nulla. Un tipo è limitato da ciò che questo strumento carica anziché da ciò che la sua risposta riporta: aggrega build carica ogni directory di catalogo configurata prima di risolvere una Release, e un avviso su una forma di catalogo deprecata proverrebbe da quel caricamento, mentre questo strumento legge solo ciò che la Release raggiunge e non esegue tale caricamento, quindi non segnala alcun avviso di quel tipo. Al momento nessuna build ne solleva uno, quindi i due segnalano gli stessi rilievi.
Una Release che non solleva nulla non dice nulla: la chiave è assente anziché presente e vuota, quindi la sua sola presenza ti dice che c’è qualcosa da leggere.
Cosa restituisce una build rifiutata
Una build che rifiuta risponde negli stessi campi in cui risponde una build riuscita, popolati fin dove è arrivata l’esecuzione. Torna contrassegnata come errore con la correzione come testo, e il payload strutturato si trova accanto a quel testo anziché esserne sostituito. Un rifiuto sollevato durante il rendering della Release si legge nelle parole del compilatore, come descrive più avanti Un rifiuto sollevato durante il rendering, e aggiunge un campo proprio. Gli avvisi vi sono inclusi: le fasi eseguite hanno sollevato ciò che hanno sollevato, e quelli sono i rilievi su cui devi agire per superare il rifiuto, quindi arrivano come voci su cui puoi fare corrispondenze anziché come prosa che dovresti analizzare. deprecations e declined_external_inputs vi sono inclusi per lo stesso motivo — un marcatore registrato viene segnalato perché un marcatore è stato registrato, e un riferimento respinto perché un riferimento è stato respinto, e nessuno di questi fatti è una conseguenza di come è terminata l’esecuzione.
files non riporta nulla in caso di rifiuto, e non è il campo da cui leggere l’esito. Non è stato emesso nulla, quindi non ci sono artefatti da nominare. Non basare la logica sulla presenza della chiave: viene riportata in entrambi i casi, e un files vuoto non può da solo distinguere una build che ha rifiutato da una che è stata eseguita e non ha emesso nulla. Leggi il flag di errore sul risultato — è il discriminante del protocollo stesso — e leggi files per ciò che è, l’elenco di ciò di cui è stato eseguito il rendering, e anche scritto dove alla chiamata è stato inviato write.
Ciò che limita gli avvisi in caso di rifiuto è fin dove è arrivata l’esecuzione, non ciò che la risposta è in grado di riportare. Un rifiuto da un controllo che viene eseguito prima che la Release sia stata risolta — una voce fissata nella cache non corrisponde più al digest registrato per essa e nessuna directory di catalogo contiene i byte fissati, oppure non è stato possibile risolvere ciò da cui dipende la Release — non riporta avvisi, perché nulla era ancora stato sollevato. I rilievi su come una Release si compone con la Release che estende vengono sollevati nel momento in cui si risolve, prima di ogni controllo successivo, quindi ogni rifiuto successivo li riporta: il Manifest mappa un tipo su una ricetta che non lo implementa, un’entità raggiunta dalla Release non soddisfa il suo schema, il lockfile non corrisponde più a ciò a cui la Release si risolve. I rilievi del rendering stesso vengono sollevati mentre il rendering procede, quindi un rifiuto da uno di quei controlli precedenti non ne riporta nessuno, e un rifiuto dal rendering riporta tutto ciò che è stato sollevato prima. Leggi quindi advisories in caso di rifiuto esattamente come lo leggi in caso di successo: ciò che questa esecuzione ha trovato, nell’ordine in cui lo stampa un terminale.
Un rifiuto dovuto a un’entità che eredita da un genitore che non è stato possibile risolvere nomina ogni ereditarietà di questo tipo nel suo testo, con le parole che aggrega build stampa per essa, così sai quale riparare. Quel dettaglio è il motivo per cui la build si è fermata, ed è per questo che si trova nel testo anziché tra i rilievi che non hanno cambiato nulla; i rilievi di composizione sollevati prima di esso si trovano in advisories come per qualsiasi rifiuto successivo.
Una directory di catalogo letta dalla Release che non può essere percorsa viene rifiutata prima che venga scritto qualcosa, come la rifiuta aggrega build. Si tratta di una directory che la chiamata nomina in catalog_dirs e che non esiste, come aggrega build rifiuta una directory --catalog che non esiste, oppure di una che esiste e non può essere letta. aggrega build carica ogni directory letta dalla Release prima di risolvere la Release, e si ferma a una che non può percorrere; build percorre per prime le stesse directory, senza leggere alcun documento al loro interno, prima di qualsiasi risoluzione delle dipendenze e prima del rendering — così una build a cui è stato inviato auto_pull non scrive alcun lockfile, e non viene eseguito alcun rendering. Il testo nomina la directory come la riporta la riga di comando, su una riga: la directory, catalog load e il motivo fornito dal filesystem. Il payload nomina la Release, con un files vuoto e nessun rilievo, perché nulla era stato eseguito. Una directory elencata dalla configurazione del workspace che non è una directory — perché lì non esiste nulla, ad esempio — viene rifiutata prima di quel percorso, nella stessa forma, con il testo che riporta il rifiuto che le dà aggrega build, nominando la voce e il file di configurazione e la riga che la elencano (Da dove vengono lette le entità locali). Una directory di catalogo che contiene un link che porta fuori dalla directory entro cui devono restare le sue letture viene rifiutata nello stesso momento, senza scrivere nulla, con il testo che nomina il link e dove porta — aggrega build la rifiuta allo stesso modo.
Una forma concreta, così che le due metà siano tangibili. Una Release che dichiara un parametro che nessun riferimento legge, e il cui rendering poi non può completarsi, torna come un errore il cui testo riporta il rifiuto del rendering e il cui payload riporta l’avviso di parametro non letto con i suoi severity, message, code e key_path — la stessa voce, con gli stessi valori, che la stessa Release segnala nella risposta quando il rendering si completa — accanto alla voce refusal per ciò che ha fermato il rendering. Una Release che ne estende un’altra ed eredita una directory di confine priva di variabili di template, il cui Manifest mappa un tipo su una ricetta che non lo implementa, torna come quel rifiuto con una voce advisories per ogni directory ereditata, ciascuna con code inherited-boundary-directory-is-literal. Una Release le cui dipendenze non possono essere risolte, in un workspace le cui directory di catalogo elencate esistono tutte, torna come un errore senza alcuna chiave advisories, perché nulla era stato sollevato quando si è fermata.
Un rifiuto sollevato durante il rendering
Una Release che il compilatore rifiuta durante il rendering — un Workload che nomina uno slot che il suo Component non dichiara, un’asserzione che fallisce, un template che non può essere valutato — torna con il rifiuto nelle parole del compilatore e con ogni causa sotto di esso, le parole che cli-build restituisce per la stessa Release: il nodo di cui si sta eseguendo il rendering, poi ciò che al suo interno ha rifiutato. Dove il rifiuto nomina una condizione registrata, il testo aggiunge come si chiama quella condizione — il codice breve e il codice descrittivo su cui fare corrispondenze — come farebbe explain-error. Il testo si apre dicendo quale fase ha rifiutato: The build failed during rendering; nothing was written to disk. per un rifiuto sollevato dal rendering, e The build refused before rendering anything; nothing was written to disk. per uno sollevato dall’esecuzione del compilatore prima che venisse eseguito il rendering di qualcosa — il rifiuto della composizione del grafo su cui lavora il rendering, o un’asserzione dichiarata da un Component o da una Feature.
Il payload riporta lo stesso rifiuto come un’unica voce, refusal, così un chiamante che deve modificare un documento legge quale, e dove, senza analizzare la frase:
file— il documento a cui punta il rifiuto: la Recipe di un Workload, la Recipe o la FeatureRecipe che dichiara un’asserzione che fallisce, la Release o l’Aggregate che ha scritto una voce rifiutata dalla composizione del grafo, oppure l’Aggregate della Release per un rifiuto che non punta ad alcun documento.key_path— la chiave in quel documento, dove il rifiuto ne nomina una:.spec.workloadper un rifiuto relativo a un Workload, la chiave stessa dell’asserzione sotto.spec.assertionsper un’asserzione che fallisce, la chiave stessa della voce per il rifiuto di una voce. Un rifiuto relativo a un Workload viene collocato sulla sua chiaveworkloade non più in dettaglio, perché il Workload che un controllo giudica è ciò che il suo template ha prodotto, e un template scrive righe che il suo autore non ha mai scritto; i percorsi che il rifiuto nomina all’interno di quel Workload risultante dal rendering restano nel suomessage.lineecolumn— la posizione di quella chiave, contata a partire da uno, la colonna in unità UTF-16. Assenti dove il rifiuto non nomina alcuna chiave o il documento non la contiene: una posizione viene fornita solo dove ne è stata trovata una.severity—halt, la gravità del rilievo che ha fermato una build.codeeshort_code— i due identificatori della condizione, dove il rifiuto nomina una condizione registrata.message— il testo del rifiuto, esattamente come appare nel testo della risposta.findings— presente solo dove il rifiuto riunisce più rilievi, come fa la composizione del grafo con ogni violazione che ha trovato: una voce per rilievo, nell’ordine in cui il rifiuto li enuncia, ciascuna in questa stessa forma — con i proprifile,key_path,line,column,severity,code,short_codeemessage. I campi del rifiuto stesso nominano allora dove punta il suo primo rilievo, e il suomessageriporta ogni rilievo, come fa il testo; la riga di comando stampa ogni rilievo come una diagnostica a sé.
La voce è presente ogni volta che l’esecuzione stessa del compilatore ha rifiutato — durante il rendering, o prima di esso: alla composizione del grafo, oppure a un’asserzione dichiarata da un Component o da una Feature, che non nomina alcun documento, per cui la sua voce nomina l’Aggregate. Una build che riesce non ne riporta alcuna, e nemmeno una rifiutata da un controllo eseguito prima che il compilatore parta — il lockfile, le mappature del Manifest, ciò da cui dipende la Release — il cui rifiuto è il solo testo. Un valore che un autore ha dichiarato sensibile viene omesso dal rifiuto dove il compilatore lo solleva, così la voce e il testo riportano ciò che riportano cli-build e il terminale — vedi cosa dice un rifiuto su un valore dichiarato.
Risolvere ciò da cui dipende una Release
pull risolve le dipendenze di catalogo e di sorgente di una Release nella cache locale e scrive il lockfile di quella Release. Si trova su questa superficie per un motivo che vale la pena dichiarare: i due rifiuti descritti sopra — un rendering che ha respinto un riferimento esterno non fissato, e una build che si è fermata perché il lockfile non corrisponde più a ciò a cui la Release si risolve — trovano entrambi risposta nel fissaggio, e un assistente che deve chiederti di eseguire un comando non ha modo di rispondervi da solo. Leggi Cosa può fare un assistente senza chiedertelo prima per ciò che scrive e fin dove arriva.
Passa release, il percorso della Release, assoluto o relativo alla radice del workspace — lo stesso contratto usato da ogni altro argomento di percorso qui. workspace_root e catalog_dirs sovrascrivono il rilevamento del workspace e del catalogo esattamente come fanno su build. Entrambi valgono su un server raggiunto tramite standard input e output; su HTTPS quei due argomenti vengono rifiutati e il percorso deve risolversi all’interno del workspace servito dal processo, come spiega Un processo, un workspace.
Per impostazione predefinita riconcilia anziché risolvere di nuovo. Un pin che il lockfile registra già viene rispettato e recuperato a quella versione, e rifiutato anziché fissato di nuovo in silenzio se il registry non serve più quei byte. Un riferimento senza pin — appena aggiunto, o rimosso a mano dal lockfile — viene risolto da zero e aggiunto. Un riferimento che non è più tra le dipendenze risolte viene eliminato. Un insieme di dipendenze invariato lascia quindi il file identico byte per byte, compreso il timestamp registrato, così una chiamata che non ha cambiato alcun pin non produce alcuna differenza per chi esamina il workspace in seguito.
verify confronta, e lascia il lockfile com’è. Verifica il lockfile registrato rispetto alla risoluzione che la chiamata di riconciliazione descritta sopra eseguirebbe ora, rispettando i pin registrati esattamente come fa quella chiamata, e torna come errore in caso di deriva, o quando non c’è alcun lockfile con cui confrontare — è quindi il modo in cui un assistente scopre se il fissaggio è necessario prima che qualcosa riscriva il lockfile. Nulla di ciò che quella chiamata registra viene scritto — né il lockfile, né le identità dei plugin registrate accanto a esso, né un entity.lock — mentre la cache dei contenuti viene letta e riempita esattamente come quella chiamata la legge e la riempie. Segnala anche la toolchain registrata dal lockfile: la versione del compilatore che ha scritto il file e la versione di ogni plugin principale incluso in quel compilatore. Viene segnalata a fini di audit e mai confrontata con il binario in esecuzione, perché la toolchain non fa parte di ciò che il lockfile fissa e verificarla fisserebbe il compilatore per via indiretta — una differenza di toolchain non è una deriva.
upgrade_targets risolve di nuovo i riferimenti che nomini, e nient’altro. Passagli uno o più URI di entità nella forma semplice scritta dall’autore — core/database, non una forma con versione. Ogni pin nominato viene scartato e risolto di nuovo alla versione più alta disponibile, mentre ogni altro pin e gli input esterni registrati restano invariati. Un URI che non corrisponde né a un pin registrato né a un allegato configurato viene rifiutato anziché ignorato.
Non esiste deliberatamente alcun argomento che risolva di nuovo tutto in una volta. La riga di comando ha quella forma, e scarta l’intero lockfile prima di risolvere di nuovo a partire dallo stato attuale del registry. Su questa superficie l’argomento non esiste, quindi la chiamata non può essere composta affatto anziché essere accettata e poi rifiutata: nessuno sta osservando un flusso di protocollo, quindi uno scarto totale non ha nessuno che lo confermi. Dove lo vuoi, e solo su standard input e output, cli-pull esegue il comando, che è la superficie in cui è presente una persona; un chiamante che raggiunge questo server tramite HTTP lo esegue invece in un terminale sull’host. verify non può essere combinato con upgrade_targets — uno lascia il lockfile com’è e l’altro lo riscrive — né con pin_sources, qualunque valore abbia: quell’argomento decide se una risoluzione registra i pin che mancano a un entity.lock o rifiuta a causa loro, e un confronto non scrive alcun entity.lock, quindi non farebbe né l’una né l’altra cosa. Una chiamata che invia una delle due coppie viene rifiutata prima che venga risolto qualcosa, con una frase che nomina la coppia. Lo schema dichiarato dello strumento non enuncia queste due esclusioni, perché un client che ne visualizza una può leggerla come un requisito di inviare verify; il rifiuto è il punto in cui un client le apprende. La riga di comando e il daemon rifiutano le stesse coppie.
Il risultato nomina ciò che è stato risolto, non solo che qualcosa lo è stato. Riporta il lockfile che ha scritto o con cui ha confrontato; resolved, ogni riferimento raggiunto dalla risoluzione con la versione a cui ciascuno si è risolto, il tipo che un autore scrive dove la risoluzione ne registra uno, e la sua source — da dove questa esecuzione ha preso il riferimento, con la parola che aggrega pull --detail stampa per la stessa risoluzione: fetched-fresh, cache-reuse, local, in-binary o external; i conteggi degli artefatti sorgente, degli input esterni e delle identità di plugin attendibili che il lockfile contiene in seguito; e diagnostics, il resoconto che la risoluzione dà di sé nell’ordine in cui ha sollevato ciascuna riga — quale pin è stato riutilizzato, quale firma è stata verificata, quale versione è stata saltata perché ritirata. Quelle righe raggiungono un terminale quando esegui il comando; qui si trovano nella risposta, perché un chiamante che non legge alcun terminale non ha altro modo di riceverle. verified è presente solo in un confronto, quindi la sua assenza è il modo per distinguere un’esecuzione che ha scritto da una che ha solo confrontato. Una source descrive questa esecuzione su questa macchina, quindi il lockfile non la registra, e describe, che riporta ciò da cui dipende una Release, non ne nomina alcuna.
Un rifiuto risponde negli stessi campi, popolati fin dove è arrivata l’esecuzione. Una volta calcolata la risoluzione, resolved viene riportato qualunque sia il verdetto — soprattutto un verdetto di deriva, poiché è il rifiuto riguardo al quale un chiamante deve decidere cosa cambiare. Un rifiuto precedente a quel punto, come un percorso di Release che non si risolve, riporta la correzione come testo e nessuna risoluzione, perché non ce n’era alcuna da riportare.
Dove i pin sono completi e gli input esterni no, la chiamata riesce comunque e lo dice. Scoprire quali input esterni consuma una Release è un rendering, e un rendering può fallire dopo che i pin delle dipendenze sono già corretti e su disco. Segnalare l’intera chiamata come fallita ti direbbe di rifare un lavoro che è corretto, quindi viene invece impostato incomplete_external_inputs sul risultato riuscito, nominando ciò che si è fermato: i pin delle dipendenze sono completi, quelli degli input esterni potrebbero non esserlo.
Questo è lo strumento più lento qui, e la riconciliazione senza modifiche non è un percorso rapido. Una risoluzione paga il suo costo pieno per stabilire che un insieme di dipendenze è invariato, quindi una chiamata che non riscrive nulla costa quanto una prima risoluzione — su una Release piccola, secondi anziché millisecondi, e cresce con la dimensione dell’insieme di dipendenze. Un verify è la più economica delle due forme, perché un confronto salta la discesa nei sorgenti per ogni componente che un’esecuzione con scrittura compie. Se il tuo client impone un timeout per chiamata, questo è lo strumento con cui verificarlo. Chiedere di essere informati sull’andamento, più avanti, significa che qualcosa arriva mentre la chiamata è in corso anziché nulla fino alla sua fine — il che risponde a un timeout di inattività nel tuo client, o in qualunque cosa si trovi tra te e un server raggiunto tramite HTTP, ma non a un limite sulla durata totale di una chiamata.
Un’entità il cui entity.lock non registra alcun pin per un input che legge rifiuta il pull, e il rifiuto nomina il passo che lo registra. Una Recipe o una FeatureRecipe che la Release compila dalle tue directory di catalogo e che legge una sorgente remota scritta per intero, o importa un file tramite i suoi artefatti, dovrebbe già avere quei pin accanto a sé — il suo autore li registra con pin, descritto più avanti. pin_sources chiede a questa chiamata di eseguire quel passo per conto dell’autore su ogni entità di questo tipo anziché rifiutare, scrivendo l’entity.lock accanto a ciascuna; è lo stesso passo che esegue lo strumento pin, e scrive gli stessi byte. Omettilo e decide il pin_sources_at_pull del workspace; invialo e decide in entrambe le direzioni, così pin_sources: false rifiuta anche in un workspace configurato per fissare. Un’entità che la risoluzione ha raggiunto nella cache anziché in una delle tue directory di catalogo non ha qui una collocazione scrivibile e non viene mai fissata da questa chiamata.
Fissare gli input propri di un’entità
pin registra, nell’entity.lock accanto a una Recipe o a una FeatureRecipe, il pin di contenuto per ogni input che l’entità legge dall’esterno del proprio documento: una sorgente remota le cui coordinate sono scritte per intero, e un file importato da una voce degli artefatti. È lo stesso passo che aggrega pin esegue in un terminale, e il lock che scrive è identico byte per byte a quello scritto da quel comando. Passa entity, il documento dell’entità, assoluto o relativo alla radice del workspace secondo lo stesso contratto di ogni altro argomento di percorso qui; su HTTPS deve risolversi all’interno del workspace servito dal processo.
Nessuna Release viene nominata, perché non ne serve alcuna. Una sorgente le cui coordinate non contengono alcun template nomina un solo artefatto per ogni Release che usa l’entità, quindi il passo la risolve e la fissa senza nulla che una Release fornisca. Una sorgente le cui coordinate provengono da un template non viene fissata qui: quale artefatto nomina lo decide ciascuna Release, e pull fissa ogni identità a cui si risolve nel lockfile di quella Release.
Il risultato dice cosa ha fatto il passo al lock. Riporta l’entity, il suo kind e il suo name, e pinnable, che è false per un tipo che non legge nulla di ciò che un lock registra — un Component o una Feature — nel qual caso nulla accanto all’entità è stato toccato e gli altri campi sono assenti. Altrimenti riporta il lock che ha scritto, changed, false quando il lock registrava già ogni pin ed è stato lasciato identico byte per byte, removed dove l’entità ora non legge nulla di ciò che un lock registra e il suo lock è stato eliminato, e pins, una voce per ogni classe di pin con il conteggio che il lock contiene in seguito. dry_run risponde con il lock che il passo scriverebbe come content e non scrive nulla accanto all’entità; la cache dei contenuti si riempie comunque, perché gli input vengono risolti esattamente come lo sarebbero altrimenti.
Scrive all’interno del workspace e raggiunge gli host nominati dalle sorgenti dell’entità — un repository di chart, un host Git, un URL — quindi su HTTP è ammesso per una credenziale che porta l’ambito che ammette pull, e rifiutato per una che può solo leggere. Su standard input e output la stessa capacità è raggiungibile anche come cli-pin, che esegue il comando; su HTTP quello strumento non esiste.
Essere informati sull’andamento di una chiamata lunga
Una chiamata segnala il proprio avanzamento quando chiedi di esserne informato, e chiederlo è un solo campo. Metti progressToken nel _meta della chiamata — una stringa o un numero, a tua scelta. Torna in ogni segnalazione esattamente come l’hai scritto, ed è l’unica cosa in una segnalazione che rimanda alla tua chiamata: una segnalazione non risponde a nulla, quindi non porta alcun id. Non inviare alcun token, o invialo come null, e non cambia nulla — la chiamata riceve la stessa risposta che riceve senza. Un token di qualsiasi altra forma viene rifiutato, prima che la chiamata faccia qualsiasi cosa, nominando le due forme che può assumere anziché essere ignorato: un chiamante che ha chiesto di essere informato e incontra poi il silenzio non ha nulla su cui agire.
Ciò che arriva è notifications/progress, con il tuo token e un conteggio che cresce a ogni notifica. Non c’è alcun totale né alcun messaggio, e nessuno dei due è un’omissione in attesa di lavoro: ciò che il lavoro segnala è di essere entrato in un’altra fase, quindi un totale potrebbe solo essere inventato e una frase potrebbe solo essere composta qui anziché trasmessa. Disegna un indicatore indeterminato a partire dal conteggio crescente; non c’è alcuna frazione con cui riempire una barra.
Su HTTP la risposta diventa un flusso di eventi, e solo una volta che qualcosa ha effettivamente segnalato. Viene servita come text/event-stream, contrassegnata come da non memorizzare nella cache, e con X-Accel-Buffering: no per un intermediario che altrimenti tratterrebbe ogni evento fino alla fine del lavoro, trasformando il flusso in un’unica risposta lenta. Ogni segnalazione è un evento, e la risposta della chiamata stessa è l’ultimo evento prima che il flusso si chiuda. Mentre il lavoro è silenzioso, il flusso trasporta a intervalli una riga di commento, che raggiunge qualunque cosa si trovi in mezzo come byte su una connessione attiva e non raggiunge il tuo client affatto. Una chiamata che ha chiesto l’avanzamento e ha raggiunto un lavoro che non ne segnala alcuno riceve comunque risposta con un unico oggetto JSON, perché ciò che apre il flusso è la prima segnalazione anziché il token.
In un flusso, leggi l’esito da quell’ultimo evento anziché dal codice di stato. Lo stato e le intestazioni vengono scritti quando il flusso si apre, cioè prima che il lavoro sia terminato, quindi una chiamata che segnala e poi rifiuta riporta il suo rifiuto come ultimo evento sotto lo stato già inviato. Chiudere la connessione a metà flusso termina il lavoro e non viene scritto nient’altro per esso, esattamente come Come termina una chiamata descrive per ogni altra chiamata.
Su standard input e output le segnalazioni sono righe che precedono la riga di risposta, delimitate come ogni altro messaggio su quel flusso — un oggetto JSON per riga, nell’ordine in cui sono state scritte — e la riga di risposta le segue. Non viene segnalato nulla una volta terminata una chiamata, su nessuno dei due trasporti.
La risoluzione delle dipendenze di una Release è ciò che segnala qui. pull segnala ogni volta che la risoluzione entra in una fase. build segnala solo quando risolve prima — perché hai inviato auto_pull, o perché l’impostazione del workspace stesso chiede a ogni build al suo interno di risolvere — poiché la segnalazione appartiene a quel passo: una build che esegue il rendering dai pin che ha già non raggiunge nulla e non segnala nulla, quindi un token su quella chiamata non cambia nulla nel modo in cui riceve risposta. Qualsiasi chiamata segnala inoltre ogni passo in cui entra il suo lavoro e su cui resta in attesa — la lettura di un registry, il recupero di un artefatto o di un bundle di documentazione, la compilazione di un plugin per la prima volta —, i passi che la riga di comando mostra a una persona accanto al suo indicatore di attesa. Una chiamata il cui lavoro non attende nessuno di questi non segnala nulla, il che è innocuo anziché un errore: la risposta è quella che avresti ricevuto senza.
Chiedere quale connessione è scritta in un punto di un documento
connection-at-position risponde alla domanda che precede la metà relativa alle connessioni dei due strumenti descritti sopra, per quando hai un punto in un documento anziché un nodo su un grafo — una riga che stai guardando in un Aggregate o in una Release. Passa file, il documento, relativo alla radice del workspace o assoluto e letto dal disco come lo legge insertion-point; position, una line e un character entrambi contati da zero, misurati nelle unità indicate da position_encoding esattamente come insertion-point legge quell’argomento; e release, la Release il cui grafo compilato registra le connessioni. La Release è richiesta anche per un punto nell’Aggregate: un nodo del grafo e una connessione esistono solo su un grafo compilato.
La risposta è una di due metà. Dove il punto si trova sulla voce di una connessione, contiene graphNode e connection — il suo socket, il suo alias e il document in cui il punto è stato letto — che sono esattamente ciò che attach-candidates accetta accanto a graph_node e release, e ciò che attachment-container accetta per indicare dove va un’associazione su quella connessione; quel contenitore si trova all’interno della stessa voce in cui cadeva il punto. Altrimenti contiene noConnectionReason, da un insieme chiuso: no-connection-entry (il punto non si trova su alcuna voce in cui si scriva un’associazione), feature-created-connection (il punto si trova sulla voce della Release per una connessione tracciata da una Feature) oppure unknown-connection (il punto si trova su una voce che la Release scrive per una connessione che il grafo compilato non contiene). La risposta leggibile espone il motivo a parole.
Un punto in qualsiasi posizione all’interno di una voce è dentro di essa — sull’alias, sul suo target, dentro le sue features — e, dove le voci sono annidate, vince la più interna. Un punto sulla chiave stessa di un socket, sopra gli alias che contiene, non è dentro nessuno di essi. Le voci sono quelle registrate dal grafo compilato: nell’Aggregate, ogni connessione tracciata da un componente, nella sua voce sotto l’alias della connessione nel documento in cui il componente è stato scritto, che per un componente fornito da un modulo importato è il documento stesso di quel modulo; nella Release, ogni voce per arco che essa scrive. Una connessione scritta come elenco di destinazioni, e una tracciata dal blocco di dipendenze di una Feature, non hanno alcuna voce in cui si scriva un’associazione. Se una chiave sia una connessione non viene mai dedotto da come si chiama.
Risponde e si ferma. Non scrive nulla in alcun file. Un documento che non si trova nel workspace, non può essere letto o non è YAML ben formato torna come risultato non riuscito che indica cosa cambiare, come avviene con insertion-point; lo stesso vale per un punto privo della sua line o del suo character, e per un position_encoding diverso dai tre.
Chiedere a quale contenitore appartiene un’associazione
attachment-container risponde alla domanda che si pone tra una risposta di candidabilità e un punto di inserimento. Hai stabilito cosa associare a un nodo; prima di poter chiedere in quale punto di un file scriverlo, devi sapere quale file e quale contenitore al suo interno. Passa graph_node — l’id di un nodo su un grafo compilato, così come il grafo lo usa come chiave — e release, la Release a cui appartiene il grafo. Entrambi sono obbligatori: l’id di un nodo è una chiave del grafo di una Release e senza di essa non significa nulla.
Non comporre quel percorso da solo. L’id di un nodo e il percorso del sottosistema che lo racchiude sono entrambi scritti con punti tra le loro parti, e il punto è un carattere ammesso in un nome digitato da un autore — quindi dall’esterno del documento non c’è modo di distinguere un punto strutturale da uno interno a un nome. Un percorso composto da te si leggerebbe correttamente e indirizzerebbe una chiave che nessuno ha scritto, e la modifica successiva creerebbe quella chiave invece di essere rifiutata. Peggio ancora, l’id di un nodo non porta alcuna traccia del sottosistema che lo racchiude: un componente scritto dentro subsystems.billing.subsystems.payments ha come chiave ledger, esattamente come l’avrebbe un componente di primo livello. Chiedi il contenitore.
La risposta contiene node, il nodo a cui si riferisce; file, il documento in cui quel nodo è stato scritto; e container, il percorso strutturale dalla radice di quel documento come elenco di segmenti — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. È di proposito un elenco anziché una stringa unita: un percorso unito dovrebbe essere diviso di nuovo da chi lo riceve, il che reintrodurrebbe l’ambiguità descritta sopra una chiamata più tardi. Passa file e container a insertion-point senza modifiche.
file fa parte della risposta anziché essere qualcosa che conosci già. Un nodo fornito da un modulo importato è stato scritto nel documento stesso di quel modulo con il nome che il modulo gli ha dato, quindi sia il file sia l’ultimo segmento del contenitore differiscono da qualsiasi cosa tu abbia inviato.
Per un’associazione su una connessione tracciata dal nodo, aggiungi connection con il suo socket, il suo alias e il suo document, che qui è obbligatorio perché ciascuno dei due documenti può contenerne una. Con aggregate la risposta è la voce della connessione stessa nel documento in cui il nodo è stato scritto, con il suo blocco features per ultimo; una connessione tracciata dalla Release non ha lì alcuna voce e viene rifiutata. Con release è la voce per arco sotto la voce della Release per il nodo — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — riportata indipendentemente dal fatto che la Release scriva già quella voce per arco, così insertion-point indica le chiavi ancora da scrivere; una Release che non scrive alcuna voce per il nodo viene rifiutata, poiché non spetta a questo strumento decidere dove viene collocato il nodo. Una connessione tracciata da una Feature viene rifiutata in entrambi i documenti.
Risponde e si ferma. Non crea alcuna associazione, non scrive nulla in alcun file e non compone alcun testo. Non stabilisce nemmeno cosa possa essere associato — questo è compito di attach-candidates. Un nodo che il grafo non contiene, o uno per cui non registra alcun documento, torna come risultato non riuscito che indica cosa cambiare anziché come risposta con un campo vuoto.
Individuare dove va una voce in un documento
insertion-point risponde alla domanda che segue una risposta di candidabilità. Hai stabilito cosa associare o connettere; ora devi sapere in quale punto del file scriverlo. Restituisce una posizione e le colonne a cui indentare, così puoi applicare la modifica senza analizzare tu stesso il documento. Poiché ciò che legge è la struttura propria di un documento anziché la forma di un singolo tipo, describe-capabilities lo indicizza sotto qualunque tipo di entità tu restringa la ricerca.
Passa file — il documento, relativo alla radice del workspace o assoluto, e all’interno del workspace: uno raggiunto tramite un link che porta fuori da esso, verso il file o verso una directory lungo il percorso, non lo è, e viene rifiutato su entrambi i trasporti — e container, il percorso strutturale dalla radice del documento al contenitore in cui va la voce, in cui ogni elemento è una chiave di mapping o una posizione in una sequenza scritta in decimale.
Il percorso del contenitore spetta a te. Lo strumento legge la struttura del documento e non deduce mai dove vada qualcosa da come si chiama, dal tipo che porta o da ciò che sembra significare. Tu dici quale chiave; lo strumento dice dove vanno le voci di quella chiave in questo documento — quali segmenti del percorso il file contiene già, le colonne a cui si trovano le sue voci e l’ultima riga raggiunta dal suo blocco più interno. Per associare una Feature a un nodo di un grafo compilato non devi conoscere tu stesso quella chiave: attachment-container, descritto sopra, riporta il documento e il contenitore, ed entrambi vanno qui senza modifiche.
La risposta è una position di larghezza zero, la cui line e il cui character contano entrambi da zero; entryIndent e indentStep, le colonne a cui scrivere; e missingContainerKeys, le chiavi del contenitore che questo documento non contiene ancora, a partire dalla più esterna, da scrivere prima della voce. entryShape riporta se il contenitore contiene un mapping o una sequence, e riporta unknown dove il contenitore non c’è ancora o non contiene nulla, perché il documento non lo ha detto — in quel caso la forma la scegli tu. indentStepMeasured dice se il passo è stato misurato dall’annidamento proprio di questo documento o è un valore di ripiego per un documento che non ne presenta alcuno. Dove precededByLineBreak è impostato, inizia il tuo testo con un’interruzione di riga: la posizione si trova alla fine della riga che la voce segue, che è valida indipendentemente dal fatto che il file termini con un carattere di nuova riga e non altera alcun byte già scritto. Leggi missingContainerKeys anche dove ti aspetti che il contenitore ci sia — una posizione applicata senza le chiavi che devono precederla produce un documento che non è più analizzabile.
position_encoding indica le unità in cui è misurato l’offset di carattere riportato: utf-8, utf-16 o utf-32. Qui è un argomento perché nessuna delle due revisioni di questo protocollo ne negozia una, e il valore predefinito è utf-16, che è ciò che adotta una sessione di editor quando un client non negozia nulla — così un chiamante che non indica nulla riceve la stessa risposta su entrambe le superfici. Un valore diverso dai tre viene rifiutato anziché sostituito silenziosamente con il predefinito, perché offset misurati in un modo e applicati a un buffer misurato in un altro corrompono il documento al primo carattere al di fuori di ASCII.
Risponde e si ferma. Non scrive nulla in alcun file, non compone alcun testo di voce e non applica alcuna modifica; comporre il testo e decidere se applicarlo spetta a te. Una richiesta che non indirizza un punto in cui può andare una voce torna come risultato non riuscito che indica cosa cambiare — un documento che non si trova nel workspace, non può essere letto o non è YAML ben formato; un percorso del contenitore privo di segmenti o con un segmento vuoto; un percorso che attraversa uno scalare, dentro cui non si può accodare nulla; un percorso che raggiunge una collezione scritta in stile flow, dove accodare riscriverebbe byte già scritti dall’autore invece di aggiungere una riga; oppure un percorso che indirizza una sequenza a blocchi con qualcosa che non è uno dei suoi indici. Se preferisci che la modifica venga applicata anziché applicarla tu, Applicare una singola modifica delimitata a un documento è lo strumento che lo fa.
Applicare una singola modifica delimitata a un documento
edit-document applica ciò che i due strumenti descritti sopra individuano. Una chiamata aggiunge una voce sotto un contenitore, o imposta uno scalare, e non può fare altro. Scrive il documento che indichi, all’interno del workspace, quindi su HTTPS richiede aggrega:workspace-write: un chiamante che possiede solo aggrega:read lo trova nell’elenco degli strumenti, e una sua chiamata viene rifiutata indicando quello scope.
Indica la modifica in edit: l’insieme è chiuso. add-component aggiunge un’istanza di componente sotto un contenitore di componenti; attach-feature associa una Feature al nodo che indichi; wire-edge collega una connessione all’interno di uno dei socket di quel nodo; set-value imposta un valore su quel nodo. Un nome diverso da questi quattro viene rifiutato anziché interpretato. Non esiste alcuna modifica che elimini, sostituisca un blocco già scritto, riordini qualcosa o scriva alla lettera byte forniti da te — quindi questo non è uno strumento per scrivere file e non può essere usato come tale.
Passa file, il documento — relativo alla radice del workspace o assoluto, e all’interno del workspace: uno al di fuori, così come è scritto o tramite un link che porta fuori da esso, viene rifiutato su entrambi i trasporti senza che nulla venga letto o scritto; node, il percorso strutturale dalla radice del documento come elenco di segmenti; name, la chiave sotto cui è scritta la voce; e value, ciò che quella voce contiene. node è un elenco per la stessa ragione per cui attachment-container risponde con un elenco: un punto è ammesso in un nome digitato da un autore, quindi un percorso unito potrebbe indirizzare una chiave che nessuno ha scritto e la voce verrebbe creata lì anziché essere rifiutata. Per add-component il percorso indica il contenitore dei componenti stesso, perché la voce aggiunta è il nodo; per le altre tre indica il nodo a cui si riferisce la modifica, e il contenitore deriva dalla modifica. socket viene letto per wire-edge e ignorato negli altri casi. Il significato di value deriva da edit — l’entità richiesta dalla voce, il nodo a cui punta una connessione o lo scalare a cui viene impostato un valore — ed è un valore JSON del proprio tipo, quindi un numero resta un numero, una cifra tra virgolette resta testo, e ometterlo non imposta nulla. Un mapping o una sequenza viene rifiutato, perché scrivere un blocco non è una di queste modifiche.
Ogni byte che la modifica non tocca sopravvive. Il documento viene analizzato solo per individuare il contenitore e la riga in cui termina il suo blocco, quindi commenti, righe vuote, stile delle virgolette, scalari folded e literal e la forma del carattere di nuova riga finale si conservano tutti, e il passo di annidamento viene misurato dall’indentazione propria del documento anziché imposto. La stessa richiesta sullo stesso documento produce gli stessi byte.
Il risultato deve essere un documento che avresti potuto digitare tu, ed è a questo che è subordinata la scrittura. Il documento composto viene verificato rispetto allo schema del proprio tipo e arriva su disco solo se supera la verifica. Una richiesta che produrrebbe qualcosa che lo schema rifiuta viene rifiutata, indicando la proprietà che lo schema non ammetterebbe e dove, e il file resta byte per byte com’era — quindi una modifica rifiutata è indistinguibile da una mai tentata, e puoi ritentare una richiesta corretta sul documento da cui sei partito. Una voce già presente che contiene ciò che hai chiesto non ha alcun effetto; una voce con quel nome che contiene qualcos’altro viene rifiutata anziché sostituita.
La risposta contiene container, il percorso strutturale in cui è finita la voce; created_containers, i livelli di contenitore che questa modifica ha dovuto creare, a partire dal più esterno, vuoto nel caso ordinario in cui l’intero percorso c’era già; e written, il documento arrivato su disco, vuoto dove non è arrivato nulla. Leggi created_containers: una modifica che ha scritto silenziosamente due blocchi annidati che il documento non conteneva è altrimenti indistinguibile da una che ha aggiunto una singola voce a un blocco scritto da te.
dry_run fa tutto tranne scrivere. Il documento modificato torna come content, non viene creato nulla e written è vuoto — per un client che mostra il risultato all’autore prima che venga salvato. Ogni altro comportamento è quello della scrittura, verifica dello schema inclusa, quindi una richiesta che la scrittura rifiuterebbe viene rifiutata anche con esso. Senza di esso il documento viene scritto e content è assente, perché il documento è allora su disco e written lo indica.
Se ciò che colleghi sia semanticamente ammissibile — se un socket sia uno di quelli dichiarati dal produttore, o se l’applicabilità di una Feature sia soddisfatta — non viene deciso qui. È a questo che risponde validate.
Su input e output standard la stessa capacità è raggiungibile anche come cli-edit-document, che esegue il comando e restituisce il testo che ha stampato; su HTTP quello strumento non esiste, e lì la capacità si raggiunge tramite questo.
Trasformare una descrizione esterna in entità in bozza
import converte una descrizione prodotta da un altro strumento — per esempio un flusso esportato da un agent builder — in file di authoring Aggrega in bozza. Scrive quei file nel workspace servito da questo server, quindi su HTTPS richiede aggrega:workspace-write: un chiamante che possiede solo aggrega:read lo trova nell’elenco degli strumenti, e una sua chiamata viene rifiutata indicando quello scope.
Passa source, il file o la directory da convertire. È assoluto o relativo alla radice del workspace, lo stesso contratto usato da ogni altro argomento di percorso su questa superficie, e su un server raggiunto tramite HTTPS si risolve all’interno del workspace servito da quel server.
Di una directory vengono letti esattamente i file selezionati dai pattern di file del suo importatore. Un chart o un progetto è una directory, e source può indicarne una. All’importatore vengono allora passati i file della directory, a qualsiasi profondità, selezionati da uno dei pattern di file dichiarati dalle sue firme, ciascuno indicato dal proprio percorso all’interno della directory scritto con barre normali, in ordine, insieme ai file che la sua associazione plugins.importer indica sotto with.sources, con i loro nomi base; un file della directory e un file di with.sources con lo stesso nome vengono rifiutati anziché lasciare che uno nasconda l’altro. Un importatore che non dichiara pattern di file legge un solo file e rifiuta una directory, nella condizione An importer that declares no file patterns is handed a directory (A un importatore che non dichiara pattern di file viene passata una directory), e anche una directory che non contiene alcun file selezionato dai suoi pattern viene rifiutata. La directory è vincolata a se stessa ovunque si trovi: un link tra i file che l’importazione leggerebbe, o verso una directory, che porta fuori da essa viene rifiutato prima che si legga qualsiasi cosa, e in un link a una directory non si entra mai — come illustra Una directory che importi. Su un server raggiunto tramite HTTPS la directory stessa si risolve all’interno del workspace, e quindi anche ogni file letto da essa.
L’importatore è uno contenuto nel catalogo del tuo workspace, oppure uno degli importatori core del compilatore. La traduzione è opera del plugin importatore che annuncia il formato della sorgente: uno contenuto nel catalogo del tuo workspace, oppure uno degli importatori core del compilatore, che servono i propri formati in ogni workspace senza alcuna voce di catalogo. Questo strumento lo seleziona, lo esegue e scrive ciò che ha prodotto. Un’associazione plugins.importer il cui uri indica un importatore tramite la sua identità e versione — importer/<name>:<version>, come lo scrive aggrega plugin add importer — associa quell’importatore: dove annuncia il formato della sorgente è quello che viene eseguito, in quella versione, qualunque altro importatore annunci anch’esso il formato, e gli vengono passate le sorgenti e le impostazioni with di quell’associazione, che nessun altro importatore riceve. Dove più importatori annunciano il formato e nessuno di essi da solo è associato — tra cui un importatore core e un importatore di altro nome contenuto nel tuo catalogo per lo stesso formato — la chiamata viene rifiutata indicandoli, come descrive Configurazione. Un formato che indichi e che nessun importatore annuncia viene rifiutato indicando la capacità che un importatore dovrebbe annunciare — import:langflow per una sorgente Langflow — che è ciò che dichiara un importatore che aggiungi al catalogo, anziché un generico mancato riscontro che dovresti poi interpretare.
Un importatore core che la macchina del server non possiede viene scaricato una sola volta, dalla prima importazione che ne ha bisogno. L’importazione lo scarica dal registry predefinito del workspace servito, lo confronta con il modulo pubblicato dalla release del compilatore, ne verifica la firma secondo la policy di fiducia di quel registry e le funzioni host che usa, come un pull verifica un plugin che scarica, e lo conserva nella cache dei contenuti del workspace, così ogni importazione successiva lo legge da lì e non contatta alcun registry. Non viene scritto nient’altro per esso — nessun lockfile e nessun record di plugin attendibili. Su HTTPS questo è l’unico registry che una chiamata a questo strumento può far contattare al server, entro il limite che Quali credenziali spende una chiamata fissa per una lettura dal registry: il registry è quello predefinito del workspace servito da questo server, quindi è uno con cui quel workspace è configurato; nulla nella chiamata indica un registry o porta una credenziale; e lo scaricamento spende il login e la policy di fiducia propri di questo host. Lo strumento continua a raggiungere il workspace e nient’altro, quindi aggrega:workspace-write è tutto ciò di cui una chiamata ha bisogno: ciò che lo scaricamento lascia è un modulo nella cache dei contenuti propria del workspace. Un modulo che non supera la verifica viene rifiutato come lo è in un terminale, e non viene conservato nulla. Dove il modulo non può essere scaricato — il workspace è offline, il suo registry non è raggiungibile o il registry non lo contiene — la chiamata viene rifiutata nella condizione A plugin’s .wasm is not on this machine (Il .wasm di un plugin non si trova su questa macchina), indicando l’importatore, la sua versione e ciò che mette il suo modulo sulla macchina.
Dove il workspace non indica alcuna cartella di catalogo, l’importazione legge il catalogo pubblicato dal suo registry predefinito. Un workspace in cui workspace.catalog_dirs, AGGREGA_CATALOG_DIRS e la radice non indicano alcuna cartella di catalogo legge il catalogo della libreria standard come un unico snapshot firmato, in catalog/snapshot sul registry predefinito del workspace servito — lo stesso registry da cui viene recuperato un importer core, raggiunto alle stesse condizioni, senza che nulla nella chiamata indichi un registry o porti una credenziale. Uno snapshot viene recuperato una sola volta: la sua firma viene verificata secondo la policy di fiducia di quel registry, e lo snapshot viene conservato nella cache dei contenuti del workspace e letto lì come una cartella di catalogo, vincolato al suo digest, senza che venga più richiesto ad alcun registry. Quale snapshot legge una chiamata: con upgrade, il più recente; altrimenti quello indicato dal record nella directory di output, recuperato tramite il suo digest dove la macchina non lo possiede; altrimenti quello che il workspace ha recuperato per ultimo come il più recente; altrimenti il più recente. Il record scritto dall’importazione indica lo snapshot che ha letto, tramite il suo digest, così una chiamata successiva che produce bozze nella stessa directory legge lo stesso catalogo. Offline, una chiamata che dovrebbe recuperare uno snapshot viene rifiutata indicando cosa eseguire, e upgrade viene rifiutato qualunque cosa possieda la macchina, poiché solo il registry può dire quale snapshot è il più recente. Un registry che non pubblica alcuno snapshot lascia l’importazione senza catalogo, e una voce warn in diagnostics lo segnala. Un workspace che indica una cartella di catalogo importa rispetto a essa e non recupera alcuno snapshot, e lì upgrade non cambia nulla.
Se ometti format, il formato viene riconosciuto dalle firme dichiarate dagli importatori — quelle del tuo catalogo e quelle degli importatori core allo stesso modo. L’entità Plugin di ogni importatore le registra: la sintassi in cui si legge una sorgente, i nomi di file a cui si applica una firma e i percorsi che l’albero analizzato deve o non deve contenere. La sorgente viene analizzata, tramite il parser che il catalogo del tuo workspace serve per una sintassi — oppure, per una sintassi per cui il tuo catalogo non serve alcun parser, quello incluso nel compilatore stesso — una volta per ogni sintassi in cui la legge una firma che si applica al suo nome, e il formato usato è quello dell’unico importatore la cui firma corrisponde. L’importatore legge poi la sorgente tramite lo stesso parser. Le firme degli importatori core leggono un file come JSON o YAML, e quelle che non indicano alcun file lo leggono come JSON — quella dell’importatore Dify come YAML — quindi riconoscere un file importato da solo lo legge in entrambi e non richiede alcun parser nel catalogo del tuo workspace: il compilatore include un parser JSON e uno YAML, e quello servito dal tuo catalogo viene usato al loro posto. Una directory viene riconosciuta allo stesso modo sui suoi file: ogni firma viene provata sui file della directory selezionati dai suoi pattern, e una firma che non dichiara alcun pattern non si applica a nessuno di essi. Il riconoscimento legge il file che hai indicato — oppure, di una directory, solo i file selezionati dai pattern di una firma — e nessuna rete. Una sorgente a cui non corrisponde alcuna firma viene rifiutata chiedendo format e indicando i formati annunciati dagli importatori — oppure, per una directory, chiedendo uno dei suoi file inviato da solo come source o un format il cui importatore dichiara pattern di file, indicando solo quei formati — nella condizione No importer recognises the source (Nessun importatore riconosce la sorgente); una sorgente a cui corrispondono firme di più di un formato viene rifiutata indicandoli, nella condizione More than one importer recognises the source (Più di un importatore riconosce la sorgente); nessuna delle due viene passata a un importatore scelto per supposizione. Invia format per indicare esplicitamente il formato in entrambi i casi — per una directory, un formato il cui importatore dichiara pattern di file, poiché una directory viene letta solo tramite quelli. Un format vuoto viene rifiutato anziché essere letto come se lo avessi omesso, perché si tratta di richieste diverse.
Invia target per redigere in bozza il Manifest su cui si compila la Release in bozza per un provider. target è una capacità di provider — la parola a cui si lega lo spec.capability di una Recipe, come compose o helm — ed è il --target di aggrega import, composto dalla stessa operazione, quindi una chiamata e il comando producono gli stessi file in bozza dalla stessa sorgente. Per ogni tipo di componente e ogni tipo di funzionalità di cui le bozze hanno bisogno — sui componenti dell’Aggregate in bozza, sulle loro connessioni e sui suoi sottosistemi, sugli Aggregates del catalogo che compone e sulle associazioni della Release in bozza — nell’ordine in cui le bozze lo dichiarano per la prima volta, l’importazione cerca nel catalogo del workspace le Recipes, o per un tipo di funzionalità le ricette di funzionalità, che implementano il tipo e si legano a quella capacità. Dove ce n’è esattamente una — più versioni di una contano come una — il Manifest mappa il tipo su di essa tramite il suo nome qualificato dalla capacità, senza versione, come compose/postgres, che il primo pull fissa nel lockfile alla versione più alta disponibile. Dove ce ne sono diverse con nomi differenti, mappa quella che porta il nome del tipo stesso, come helm/postgres per core/datastore/postgres. Dove non ce n’è nessuna, o ce ne sono diverse e nessuna ha quel nome, il tipo resta non mappato e una voce warn in diagnostics lo indica e ne spiega il motivo — le diverse ciascuna per nome — così una build delle bozze si ferma indicando ogni sua istanza o associazione, nella condizione No Recipe is mapped for a component or feature instance (Nessuna Recipe è mappata per un’istanza di componente o di funzionalità), finché la mappatura non viene aggiunta. Dove è l’importatore stesso a redigere il Manifest, per scegliere la Recipe attraverso cui viene renderizzata un’istanza o una ricetta di funzionalità tra diverse, ogni mappatura che ha scritto e che il catalogo offre per quel tipo e quella capacità viene mantenuta, ogni altra viene scartata con una voce warn, e i tipi che lascia vengono mappati come sopra. Il Manifest viene redatto come manifest.yaml accanto alla Release in bozza, con lo stesso nome e la stessa versione della Release, e lo spec.manifest della Release viene impostato su quel nome — il commento che l’importatore aveva scritto al suo posto viene sostituito, e nient’altro nella Release cambia. Una Release che indica già un Manifest resta com’è, e dove l’importazione non produce alcuna Release in bozza il Manifest viene redatto accanto all’Aggregate, con il suo nome e la sua versione, e una voce info dice che nulla vi fa riferimento. Il Manifest e la Release modificata sono bozze come le altre: in written, nel record e restituiti con dry_run. Un target a cui non si lega alcuna Recipe del catalogo viene rifiutato prima che l’importatore venga eseguito, nella condizione An import’s target names a capability no Recipe in the catalog binds to (Il target di un’importazione indica una capacità a cui non si lega alcuna Recipe del catalogo), indicandolo così come l’hai inviato insieme alle capacità a cui si legano le Recipes del catalogo, e non viene scritto nulla. Se ometti target non viene redatto alcun Manifest — tranne con sync, che redige per il target con cui era stata inviata l’importazione precedente; un target vuoto viene rifiutato anziché essere letto come se lo avessi omesso.
Invia output_dir per indicare la directory in cui vanno le bozze. Se lo ometti, finiscono sotto la radice del workspace risolto dalla chiamata — il punto in cui aggrega import le scrive quando non indichi alcuna destinazione, ovunque tu lo esegua, e il punto in cui aggrega/import del language server le scrive quando la sua richiesta non ne indica alcuna. La destinazione è facoltativa in tutti e tre i casi, e si indica allo stesso modo di ogni percorso che invii a questo server. Su HTTP è una directory all’interno del workspace servito da questo server, scritta in modo relativo alla sua radice: un valore che risale fuori dalla radice, una posizione assoluta al di fuori di essa e una directory che porta fuori da essa tramite un link — compresa una directory non ancora creata sotto un link del genere — vengono ciascuno rifiutati indicando output_dir, e non viene letto né scritto nulla. Su input e output standard viene preso così come è indicato, come ogni percorso lì: un valore relativo si risolve rispetto alla radice del workspace risolto dalla chiamata, e uno assoluto può indicare una directory al di fuori del workspace, in cui le bozze vengono scritte come vi scrive aggrega import --output-dir. Ciò che viene scritto lì è vincolato, con i suoi link risolti, al workspace — oppure, per una directory indicata al di fuori di esso, a quella directory — quindi un link al suo interno che porta fuori da essa viene rifiutato e non viene scritto nulla. Un output_dir vuoto viene rifiutato anziché essere letto come se lo avessi omesso. Su input e output standard cli-import porta anche il --output-dir del comando come proprio output_dir; lì un valore relativo si risolve nella cartella in cui viene eseguito il comando: la radice del workspace indicata dalla chiamata, altrimenti quella con cui è stato avviato il server, altrimenti la cartella in cui il server è in esecuzione.
Ogni percorso in bozza viene verificato rispetto alla directory di output prima che venga scritto qualsiasi cosa. Un percorso che esce da essa viene rifiutato indicando sia il percorso sia la directory, e non viene scritto assolutamente nulla — nemmeno i file dello stesso insieme i cui percorsi erano corretti, perché un’importazione rifiutata che lasciasse dietro di sé una parte di sé sarebbe un risultato che nessuno ha chiesto. Un percorso in bozza proviene dal plugin importatore anziché da te, ed è per questo che viene verificato per la stessa ragione per cui lo è un percorso che invii tu.
Ogni importazione che produce qualche bozza scrive anche .aggrega-import.json accanto alle sue bozze: il record di ciò che ha scritto — il target con cui è stata inviata, quando ne è stato inviato uno, lo snapshot del catalogo che ha letto, quando ne ha letto uno, e ogni file in bozza e, in un Aggregate o in una Release in bozza, ogni chiave a ogni profondità, con un digest del testo scritto lì; ogni altro file in bozza viene registrato per intero. Il testo di una chiave è la sua riga, le righe del suo valore dove il valore non è un mapping di chiavi, e le righe di commento scritte direttamente sopra di essa alla sua stessa indentazione. written indica il record insieme alle bozze, e con dry_run è tra le bozze restituite. Il record è JSON, quindi nulla di ciò che legge i documenti YAML del workspace lo legge.
Una chiamata non sovrascrive mai un Aggregate già presente nella directory di output. Un Aggregate è il documento che un autore continua a modificare una volta redatto, quindi una chiamata una delle cui bozze finirebbe su un file che si legge come un Aggregate viene rifiutata, indicando la bozza e la directory, e non viene scritto assolutamente nulla — anche con dry_run, poiché un dry run rifiuta ciò che la scrittura rifiuta. Ogni altro file già presente in un percorso in bozza viene sovrascritto, e un file redatto da un’importazione precedente che questa non redige resta dov’è.
Invia sync per aggiornare invece rispetto alla sorgente ciò che un’importazione precedente ha redatto, cambiando solo ciò che l’importazione ha scritto. Una sync a cui non viene inviato alcun target redige per il target indicato dal record, quindi redige il Manifest redatto dall’importazione precedente; una a cui viene inviato un target redige per esso, e il record poi lo indica. Un target registrato a cui non si lega alcuna Recipe del catalogo viene rifiutato come uno inviato, e il rifiuto dice che il target è quello registrato. Ogni parte viene valutata in tre modi — ciò che il record dice che l’importazione ha scritto lì l’ultima volta, ciò che si trova su disco e ciò che la sorgente produce ora. Una parte che la sorgente ha lasciato come l’importazione l’aveva scritta l’ultima volta resta esattamente com’è su disco, che un autore l’abbia modificata o no. Una parte che la sorgente ha cambiato viene riscritta, una parte che ha eliminato viene rimossa — un file in bozza viene cancellato per intero — e una parte che ha acquisito viene aggiunta accanto alle parti che la bozza indica attorno a essa, ciascuna solo dove ciò che si trova su disco è ciò che l’importazione ha scritto l’ultima volta e non contiene nulla aggiunto da un autore. Tutto il resto resta byte per byte: una chiave aggiunta da un autore in qualsiasi punto — un parametro, una Feature, anche sotto un’istanza di Component in bozza, un altro Component, l’ambiente che una Release in bozza lascia al suo autore — un commento non scritto direttamente sopra una chiave in bozza, e ogni file che il record non elenca. Il drift della risposta elenca ogni parte aggiornata — oppure, con dry_run, ogni parte che lo sarebbe — nell’ordine in cui la bozza le indica, ciascuna come change (added, removed o changed), file, il file in bozza in cui si trova, e key, le chiavi che vi conducono in un Aggregate o in una Release in bozza, come elenco, vuoto dove la parte è l’intero file; la risposta testuale indica ciascuna su una riga propria con le parole che aggrega import scrive sullo standard error, <change> <key> in <file> o <change> <file>. Un drift vuoto con dry_run dice che le bozze sono allineate alla sorgente. Con dry_run le bozze restituite sono i file che la sync scriverebbe, con il contenuto che darebbe loro. Una sync che cambierebbe o rimuoverebbe una parte modificata da un autore, aggiungerebbe una parte dove un autore ne ha già scritta una, o rimuoverebbe una parte che contiene qualcosa aggiunto da un autore viene rifiutata, indicando ciascuna di tali parti e il motivo, e non viene scritto nulla; un commento scritto direttamente sopra una chiave in bozza modifica quella chiave. Una sync su un Aggregate che nessun record elenca viene rifiutata dicendolo, così come una il cui record non può essere letto, e una sync il cui importatore non è riuscito a terminare non scrive nulla. Una sync in una directory che non contiene alcun record e nulla nei suoi percorsi in bozza scrive l’intera bozza. drift è un elenco vuoto per una chiamata che non è una sync.
La risposta contiene source, come l’hai indicata; format, come è stata letta la sorgente; workspace_root, la radice del workspace risolto dalla chiamata; output_dir, la directory rispetto a cui sono relativi i percorsi in bozza; written, i file arrivati su disco; drift, ciò che una sync ha aggiornato; diagnostics, una voce per ogni costrutto che l’importatore non è riuscito a tradurre; decisions, come l’importatore ha mappato ogni nodo della sorgente; e halted. output_dir è la directory che hai inviato, o quella radice dove non ne hai inviata alcuna, ricavata da ciò che l’importazione ha effettivamente usato, e viene riportata anche con dry_run, dove non viene scritto nulla ma ogni percorso in bozza è comunque relativo a essa. Su HTTP workspace_root viene trattenuto e contrassegnato con workspace_root_withheld, perché la radice è un luogo sull’host del server, come illustra Cosa dice una risposta sul filesystem del server; output_dir viene trattenuto e contrassegnato con output_dir_withheld dove è quella radice, e altrimenti viene indicato con il suo nome relativo alla radice — la forma che assumono i tuoi percorsi — così la destinazione delle bozze resta nella risposta. Un’importazione che l’importatore non è riuscito a terminare produce comunque le bozze che ha potuto, e torna contrassegnata come fallimento con quell’intera risposta — halted a true, i file effettivamente arrivati su disco indicati in written e, accanto a essi, le diagnostiche che indicano cosa manca. È un risultato parziale che puoi conservare o scartare, non una chiamata che non ha fatto nulla.
decisions dice dove l’importazione ha tirato a indovinare. Contiene una voce per ogni nodo della sorgente mappato dall’importatore, nell’ordine dell’importatore: source_node, l’id, il type e il params_summary del nodo; candidates, ogni Component del catalogo che l’importatore ha valutato per esso, come component, score, tier e signals — il contributo di ciascuno dei suoi segnali, sotto table, category, domain_labels, shape e name; chosen, il target scelto, il mode in cui lo ha scritto — un reference a un Component esistente o un draft — e il tier della scelta; rationale, il perché; e swap_hint, come scegliere diversamente. candidates è assente dove l’importatore non ne ha valutato alcuno, chosen dove non ha fatto alcuna scelta, e rationale e swap_hint dove non ne ha scritto alcuno. Ogni valore è dell’importatore stesso — come assegna un punteggio a un candidato e dove cadono i suoi livelli sono scelte sue — quindi leggi una voce come il suo resoconto della mappatura. decisions è nella risposta sia con dry_run sia quando l’importazione si è interrotta, ed è un elenco vuoto per un importatore che non ne riporta alcuna. La risposta testuale indica ciascuna decisione su una riga propria dopo le diagnostiche, con le parole che aggrega import scrive sullo standard error: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, dove il punteggio è quello del candidato migliore.
dry_run fa tutto tranne scrivere. Ogni file in bozza torna sotto drafts con il suo percorso, relativo a output_dir, e il suo contenuto, e non viene creato nulla — per un client che ti mostra il risultato prima che venga salvato. Ogni altro comportamento è quello della scrittura, lo stesso importatore sulla stessa sorgente che riporta le stesse diagnostiche, quindi una sorgente che la scrittura rifiuterebbe viene rifiutata anche con esso. Senza di esso i file sono su disco e written li indica, e drafts è assente anziché ripetere byte che hai chiesto di scrivere.
Le bozze sono un punto di partenza che ti appartiene e che continui a modificare. Se ciò che dicono sia ammissibile — se un socket sia uno di quelli dichiarati dal produttore, o se l’applicabilità di una Feature sia soddisfatta — non viene deciso qui. È a questo che risponde validate.
Su input e output standard la stessa capacità è raggiungibile anche come cli-import, che esegue il comando e restituisce il testo che ha stampato; su HTTP quello strumento non esiste, e lì la capacità si raggiunge tramite questo.
Pubblicazione, firma e ritiro
Quattro strumenti mettono qualcosa dove altre persone lo risolveranno. publish-entity crea il bundle di un’entità del catalogo e la pubblica; publish-artifact pubblica un file autonomo, come un bundle di documentazione, con i suoi byte opachi e senza analizzare alcun envelope di entità; sign-artifacts firma riferimenti già pubblicati e allega ciascuna firma, lasciando com’è un riferimento che ne porta già una verificata dalla policy di attendibilità del suo registry; deprecate-artifact allega a un riferimento un marcatore di ritiro firmato. Leggi Cosa può fare un assistente senza chiederti prima prima di consentirne uno qualsiasi: sono gli strumenti i cui effetti escono dalla macchina.
publish-entity accetta entity, il documento da pubblicare, e un Plugin richiede anche plugin, l’eseguibile pubblicato all’interno del suo manifest. publish-artifact accetta file con il name e il tag sotto cui viene pubblicato. Ogni argomento di percorso qui è assoluto o relativo alla radice del workspace, lo stesso contratto usato da ogni altro strumento di questa superficie, e workspace_root indica il workspace a cui la chiamata si riferisce — su un server raggiunto tramite standard input e output. Un server raggiunto tramite HTTPS rifiuta workspace_root e richiede che ciascuno di quei percorsi si risolva all’interno del workspace che serve, come spiega Un processo, un workspace. registry è la destinazione e il suo valore predefinito è quello configurato nel workspace; non inviare né l’uno né l’altro, senza alcun valore predefinito configurato, viene rifiutato indicando cosa inviare. sign-artifacts accetta references, uno o più indirizzi di registry anziché percorsi, e facoltativamente jobs, quanti di essi vengono firmati contemporaneamente: se omesso, vengono firmati uno dopo l’altro, e un valore inferiore a 1 viene rifiutato indicando cosa inviare. Ciascuno viene comunque firmato esattamente come lo sarebbe da solo, come descrive aggrega sign. deprecate-artifact accetta reference con severity e reason, oppure from che indica un file batch — e rifiuta gli argomenti di contenuto inviati insieme a un file batch anziché scartarli, perché un file batch fornisce i propri e un argomento ignorato silenziosamente sembra un argomento rispettato.
I due strumenti di pubblicazione accettano dry_run, che mostra cosa invierebbe una pubblicazione senza contattare alcun registry. Calcola il bundle, riporta cosa avrebbe pubblicato e risponde con beyond_this_machine false e la destinazione a cui si sarebbe rivolto in registries; publish-entity risponde anche con il digest che quella pubblicazione produrrebbe, lo stesso che stampa aggrega push --dry-run. È il modo per mostrare a qualcuno una pubblicazione proposta prima che lo diventi. Firma e ritiro non hanno una forma simile: entrambi agiscono su qualcosa di già pubblicato, quindi non c’è nulla da mostrare in anteprima.
publish-entity risponde con windows_unusable_entries quando l’archivio che pubblica contiene voci che Windows non può conservare così come sono scritte — un percorso con una parte che porta il nome di un dispositivo, come CON, AUX o NUL, in qualsiasi combinazione di maiuscole e minuscole e con qualunque estensione segua, oppure una parte che termina con un punto o uno spazio — indicandole una per una, prima il nome del file del documento dell’entità, poi i file che porta con sé. Il campo è assente quando non ce ne sono, il che include un’entità pubblicata come solo documento. aggrega eseguito su Windows rifiuta di estrarre una voce simile, quindi un workspace Windows non può usare quella versione; sono le voci per cui aggrega push emette un avviso, e anche il testo della risposta le indica. Non rifiutano nulla: la chiamata procede o viene rifiutata esattamente come accadrebbe senza di esse, dry_run compreso.
publish-entity accetta pin_sources, che esegue sull’entità il passaggio di pin dell’autore dell’entità prima che ne venga creato il bundle, così l’entity.lock che il passaggio scrive accanto a essa fa parte di ciò che viene pubblicato. È lo stesso passaggio eseguito dallo strumento pin, che scrive gli stessi byte, e viene eseguito prima di qualsiasi rifiuto che giudichi l’entità — quindi una pubblicazione rifiutata in quel punto, per esempio per una firma mancante, lascia comunque il lock scritto accanto all’entità. Un rifiuto che riguarda la chiamata stessa, come un workspace offline o l’assenza di una destinazione, arriva prima e non esegue alcun pin. Se lo ometti decide pin_sources_at_push del workspace; se lo invii decide lui, in entrambe le direzioni. Una pubblicazione che esegue il pin scrive all’interno del workspace oltre che nel registry, quindi su HTTP richiede una credenziale che porti entrambi gli scope, e una che porti solo lo scope che consente la pubblicazione viene rifiutata indicando l’altro. Il risultato contiene pin, nella forma con cui risponde lo strumento pin, quando il passaggio è stato eseguito; con dry_run il passaggio riporta il lock che scriverebbe e non scrive nulla. Quando il passaggio non viene eseguito, una Recipe o una FeatureRecipe il cui entity.lock non registra alcun pin per un input che legge viene rifiutata — o una a cui l’input non corrisponde più — prima che venga creato qualsiasi bundle, dry_run compreso, indicando aggrega pin, pin_sources e pin_sources_at_push. È il rifiuto che pull solleva sullo stesso lock, e verificarlo scarica per intero ogni sorgente remota che l’entità scrive per esteso, come farebbe il passaggio.
La firma è il punto in cui la credenziale viene spesa, e tre dei quattro strumenti la eseguono — la pubblicazione di un artefatto di dati non firma nulla e viene firmata in seguito tramite riferimento. identity_token fornisce un’identità keyless per la chiamata. Su un server raggiunto tramite standard input e output, ometterlo fa ricadere sull’identità che porta l’ambiente di quel server, e key_path seleziona invece una chiave conservata offline. Su un listener nessuna delle due è raggiungibile: l’ambiente non viene letto, key_path viene rifiutato ed escluso da ciò che questi tre strumenti dichiarano, e una chiave indicata dalla configurazione del workspace servito non viene raggiunta — quindi firma solo un token inviato nella chiamata, come spiega Quali credenziali spende una chiamata. Una chiamata firma con una sola credenziale. Ogni riferimento inviato a sign-artifacts, e ogni voce di un file batch letto da deprecate-artifact, viene firmato con la stessa chiave conservata o con la stessa identità keyless; quando la configurazione del workspace servito indica una chiave per il registry di un riferimento e nessuna per quello di un altro, oppure due chiavi diverse, la chiamata non firma nulla e viene rifiutata indicando i registry di ciascuna parte, prima che venga risolta qualsiasi identità o letto qualsiasi registry — invia una chiamata per credenziale, oppure un solo key_path per tutti su standard input e output. Su un listener non viene raggiunta alcuna chiave configurata, quindi lì ogni riferimento viene firmato con l’identità inviata dalla chiamata e la chiamata non viene mai rifiutata per questo motivo. Il rifiuto è descritto in References signed together need different signing credentials (I riferimenti firmati insieme richiedono credenziali di firma diverse). fulcio_url, rekor_url e timestamp_url sostituiscono gli endpoint keyless configurati dal workspace, su entrambi i trasporti. Quando non si risolve alcuna identità la chiamata rifiuta e indica cosa inviare — nulla qui apre un browser o attende una persona, perché nessuno sta osservando un flusso di protocollo, e una chiamata rimasta bloccata sarebbe proprio il fallimento silenzioso che quel rifiuto esiste per impedire. Su publish-entity, se una firma venga allegata o meno segue la policy del registry di destinazione, a meno che sign non dica altrimenti, e un registry che richiede le firme rifiuta una pubblicazione non firmata qualunque cosa tu invii: non esiste alcun argomento che aggiri quel rifiuto. Vedi aggrega sign per le due modalità di firma e cosa contatta ciascuna.
Ogni risultato riporta i fatti anziché una trascrizione: dove è finito l’artefatto, il suo tag, il digest pubblicato — oppure, per il dry run di un’entità del catalogo, il digest che una pubblicazione produrrebbe — se il tag puntava già a contenuto identico byte per byte, se una pubblicazione è stata firmata, e il suo reach. Un batch di firma riporta ogni riferimento firmato con il digest a cui la sua firma si impegna, nell’ordine in cui sono stati forniti i riferimenti, e un batch in cui un qualsiasi riferimento non è riuscito torna come un fallimento che li indica uno per uno anziché come un risultato con un elenco ridotto — un batch parziale riportato come successo è il modo in cui un rifiuto finisce per essere letto come un via libera. Una deprecazione riporta ciascun marcatore con il proprio digest, poiché un marcatore viene allegato come referrer senza tag dell’artefatto che ritira e nient’altro vi fa riferimento. Firmare o ritirare un riferimento che nulla ha pubblicato viene rifiutato anziché allegato al nulla.
Le due parti di una risposta
Ogni strumento risponde con un testo leggibile e, accanto a esso, con un risultato strutturato ovunque l’operazione ne abbia uno. Il testo è scritto per una persona che legge la conversazione. Il risultato strutturato porta la stessa risposta sotto forma di campi letti da un programma — un verdetto, un elenco di file, una diagnostica — e anche un rifiuto ne porta uno quando l’operazione aveva dei risultati in mano al momento del rifiuto, come descrive Cosa restituisce una build rifiutata per una build.
Il risultato strutturato porta anche il testo, come text_answer. Il risultato strutturato di ogni strumento ha un campo text_answer che contiene il testo della risposta esattamente come lo riporta il testo: ogni frase, in ordine, invariata. Così un client che passa al suo modello il risultato strutturato anziché il testo, come fa Claude Desktop, gli passa comunque ogni frase del testo — la riga con cui si apre la risposta di describe-capabilities senza argomenti, la configurazione in vigore riportata da config-show, la frase che indica la cartella usata da una risposta quando non è stato trovato alcun workspace. text_answer viene scritto per primo, prima dei campi con cui risponde lo strumento, ed è il testo che il chiamante riceve: su HTTP indica ogni posizione sull’host del server come fa il testo, come spiega Cosa dice una risposta sul filesystem del server. Il testo stesso resta la prosa che è, per i client che lo leggono, quindi le stesse parole viaggiano due volte in ogni risposta.
Nessuno strumento fa eccezione, lint compreso. Nessuno strumento risponde con un proprio campo chiamato text_answer, quindi il campo non ne sostituisce mai uno. Il risultato strutturato di lint mantiene il suo summary — il numero di entità controllate e di rilevamenti, in totale e per gravità, con i nomi che aggrega lint scrive con -o json — e porta text_answer accanto a esso. Anche describe-capabilities mantiene i propri campi: version_summary, la sola riga della versione, quando non riceve argomenti, e in ciascuna voce del suo index un summary, lo scopo di quello strumento in una riga.
Nessuno strumento dichiara uno schema di output. L’elenco di uno strumento porta uno schema per gli argomenti che accetta e nessuno per il suo risultato, quindi text_answer è descritto qui anziché in uno schema.
Una risposta senza risultato strutturato è il solo testo. Il rifiuto degli argomenti di una chiamata, e qualsiasi altro fallimento per cui l’operazione non aveva nulla di strutturato da riportare, torna come testo e nient’altro, e il testo è allora l’unica parte che un client può mostrare al suo modello.
Quando una chiamata non riesce
Dove arriva la risposta dipende da una sola cosa: se il chiamante può correggere il problema cambiando gli argomenti di uno strumento che esiste.
Tutto ciò che si può correggere in questo modo torna come risultato dello strumento stesso, contrassegnato come fallimento e con la correzione come testo — una combinazione di selettori che lo strumento non accetta, un argomento obbligatorio omesso, un argomento inviato con il tipo JSON sbagliato, un percorso che non si risolve, una diagnostica del compilatore. È il canale che viene mostrato a un assistente, che quindi legge cosa è andato storto e chiama di nuovo con l’argomento corretto.
Il canale di errore del protocollo è riservato a ciò che non ha un risultato di strumento in cui stare: un nome di strumento che il server non serve, una richiesta i cui parametri non riesce a leggere, un metodo che non implementa e un messaggio che non è affatto JSON valido. Anche la lettura di una risorsa e il rendering di un prompt rispondono lì, perché nessuno di quei risultati porta un proprio flag di fallimento.
Lo schema dichiarato da uno strumento dichiara anche la maggior parte delle regole che i suoi argomenti devono rispettare — quali selettori si escludono a vicenda, quale argomento ha senso solo insieme a un altro e quali sono obbligatori — quindi un client che compone chiamate in base allo schema dichiarato raramente deve effettuare la chiamata per scoprirle. Una regola che lo schema non indica viene comunque rifiutata, con una frase che la nomina; la regola di pull per cui verify non si combina con upgrade_targets o pin_sources è lasciata di proposito al rifiuto, per il motivo spiegato in Risolvere ciò da cui dipende una Release.
Cosa arresta il server
Su standard input e output, chiudere la connessione lo arresta. Il server legge un messaggio per riga ed esce in modo pulito quando il suo standard input raggiunge la fine del flusso, quindi un client che chiude la connessione spegne il server. È il caso normale su quel trasporto, perché non avvii mai il comando tu stesso: è il client che lo ha avviato a terminarlo, quindi chiudere l’editor, o disabilitare questo server per un progetto, è di solito il modo in cui lo si arresta.
Chiedere al processo stesso di fermarsi raggiunge il server su entrambi i trasporti. Un’interruzione da un terminale, o una richiesta di terminazione da un supervisore o da un runtime di container, lo spegne alla prima richiesta, che un client stia inviando qualcosa o meno: smette di accettare messaggi, termina il lavoro che sta svolgendo una chiamata in corso ed esce in modo pulito. Una seconda richiesta termina subito il processo. Su standard input e output, quindi, una chiamata ancora in esecuzione quando si chiede al processo di fermarsi non si completa; un listener invece si svuota, lasciando che una chiamata a cui sta già rispondendo si completi entro un tempo limitato prima che il processo esca.
Un client può anche fermare una singola chiamata senza fermare il server, e il modo in cui lo fa dipende dal trasporto. Le chiamate ricevono risposta in modo concorrente, quindi la terminazione di una viene gestita mentre quella chiamata è ancora in esecuzione anziché attendere dietro di essa. Su standard input e output un client indica l’id della chiamata; annullare una chiamata che ha già ricevuto risposta, o una su cui il server non sta lavorando, non fa nulla — ed è ciò che rende sicuro inviare un messaggio simile senza sapere prima se la risposta è già in arrivo. Su HTTP non c’è alcun messaggio da inviare: chiudere la connessione che ha trasportato la chiamata la termina. In entrambi i casi alla chiamata viene detto di fermarsi — il suo lavoro termina al successivo punto in cui l’operazione esegue un controllo, e un’operazione che non controlla mai arriva fino in fondo — non viene inviato nient’altro per quella chiamata, ogni altra chiamata in corso prosegue e il server continua a servire.
Quando usarlo
Usa aggrega mcp quando vuoi che un assistente AI aiuti a scrivere entità Aggrega in base agli schemi e al riferimento reali — così i suoi suggerimenti si fondano sulla struttura esatta che il compilatore accetta anziché essere indovinati. Si inserisce direttamente nel ciclo di authoring: l’assistente legge lo schema e il riferimento di un tipo, genera uno scheletro, compila i campi di competenza del tuo ruolo e convalida prima di restituire la bozza. Vedi Scrivere file Aggrega per quel ciclo.
Su standard input e output di solito non digiti mai aggrega mcp tu stesso. Lo indichi invece una volta nella configurazione MCP del tuo client, e il client lo avvia e lo arresta per te. Un listener è l’altro caso: lì sei tu a eseguire il processo, che continua a girare per chiamanti che non lo hanno avviato.
Esempio: configurazione del client su standard input e output
Indica il comando a un client MCP con una voce di server stdio:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}L’unico prerequisito è il binario aggrega installato nel PATH del client. Per i percorsi di configurazione di ciascun client e la risoluzione dei problemi, vedi Collegare il server MCP. Per ottenere uno schema direttamente dalla riga di comando senza un client, vedi aggrega get-schema.