コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

aggrega mcp

AI アシスタント統合のため、標準入出力または HTTP 上で Model Context Protocol サーバーを実行します

概要

aggrega mcp [flags]

説明

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

フラグ

フラグデフォルト説明
--listen—HTTP トランスポートが待ち受けるアドレスです。host:port、または unix: に続けてファイルシステムパスを指定する、2 つの形式のいずれかを取ります。待ち受ける場所を指定するだけで、トランスポートは選択しません。—transport http、またはワークスペース設定の mcp.transport: http とともに読み取られ、stdio トランスポートとともに指定すると拒否されます。証明書のないリスナーは平文で提供し、ループバック(127.0.0.1、::1、localhost)または Unix ソケット上でのみ許可されます。これは終端プロキシの背後にあるサーバーが取る形です。それ以外のアドレスには mcp.tls.cert_file と mcp.tls.key_file が必要で、このプロセスはそれらを使って自身で TLS を終端します。設定すると、mcp.listen 設定キーを上書きします。
--transport—サーバーへの到達方法です。stdio は標準入出力上でプロトコルを話します。これは、このコマンドをサブプロセスとして起動するクライアントがサーバーに到達する方法です。http は、—listen または mcp.listen が指定するアドレスで HTTP 上でプロトコルを提供し、mcp.tls が証明書と鍵を指定している場合は HTTPS 上で提供します。設定すると、mcp.transport 設定キーを上書きします。このキーのデフォルトは stdio です。

動作

aggrega mcp は Model Context Protocol サーバーを実行します。サーバーへの到達には 2 つのトランスポートがあり、--transport でいずれかを選択します:stdio または http です。ワークスペース設定の mcp.transport がこのフラグで上書きされるキーであり、デフォルトは stdio です。

デフォルトの stdio では、プロセスの標準入出力を介して通信します。この形態では対話的に実行するコマンドではなく、MCP 対応クライアントがサブプロセスとして起動し、stdio 上でプロトコルを話します。各クライアントがそれを起動するエントリをどこに保持するかは、MCP サーバーの接続に記載されています。これを実行すると、CLI がエディターやチャットクライアント内で Aggrega を理解するオーサリングアシスタントになります。

http では、代わりに HTTP 上でプロトコルを提供します。ホスト上で長時間動作する 1 つのプロセスであり、そのキーボードの前にいない呼び出し元から到達され、--listen が指定するアドレス、フラグがない場合は mcp.listen のアドレスで待ち受けます。このリスナーの設定方法と受け付ける内容については、HTTPS 経由でサーバーに到達するを参照してください。

サーバーはプロトコルの 2 つのリビジョン 2026-07-28 と 2025-06-18 を話すため、どちらのクライアントも接続でき、同じサーフェスに到達します。 呼び出しがどちらを話すかは、接続ごとに一度合意するのではなく、その呼び出しごとに示されます。2026-07-28 のクライアントは、話すプロトコルバージョンと自身の機能をすべてのリクエストで送信し、サーバーがサポートする内容を server/discover に問い合わせます。2025-06-18 のクライアントは、initialize ハンドシェイクで接続を開くことで、同じ事柄を一度だけ決定します。いずれの場合もサーバーはメッセージ間で何も保持しないため、最初に送る内容が後の呼び出しへの応答方法を決めることはありません。サーバーが話さないリビジョンを指定したリクエストは、どちらかを要求したものとして応答されるのではなく拒否され、要求できる 2 つのリビジョンが伝えられます。

サーバーは接続されたアシスタントに 3 つのサーフェスを公開します:

  • プロンプト — 2 つのファミリーがあり、違いはそれぞれが何に答えるかです。オーサリングプロンプトは「何を書いているのか」に答えます。ロール(開発者、アーキテクト、運用)ごとに 1 つのペルソナと、エンティティごとの特化テンプレートがあります。それぞれがロールを設定し、アシスタントを適切なスキーマ、リファレンスページ、オーサリングガイドに向けるため、提案はそのロールが所有する柱の範囲内にとどまります。ワークフロープロンプトは「どの呼び出しを、どの順序で」に答えます。それぞれが、複数の操作にまたがる目標に到達するツール呼び出しの順序付きシーケンスを、その間の判断ポイントとともに示します。たとえば、新しい Aggregate とその Release をゼロから構成すること、既存のチャート、インフラストラクチャモジュール、コンテナ compose ファイルを Aggrega に取り込むこと、ビルドがコンパイルされない理由や誤った成果物をレンダリングする理由を突き止めることです。prompts/list は両方のファミリーを列挙し、prompts/get はその 1 つをレンダリングするため、セットはこのページではなくサーバーから読み取られます。

    ワークフロープロンプトは呼び出しを指定し、それを実行するのは利用者自身であり、各結果を読んでから次を 1 つずつ実行します。目標全体を実行する呼び出しはありません。各ツールは確認可能な 1 つの操作をラップしているため、そこに到達させるのはシーケンスです。オーサリングペルソナは焦点を当てる任意の kind を受け取り、エンティティごとのテンプレートはそれを必須とします。どのスキーマにも対応しない kind は、黙って無視されるのではなく、受け付けられるセットを列挙したうえで拒否されます。

  • リソース — インラインで提供される読み取り専用の参照資料です。エンティティの JSON Schema には schema://<kind>、言語リファレンスの任意のページには langref://<path>、オーサリングガイドには authoring://<topic>、カタログエンティティの作成済み YAML には catalog://<kind>/<name>、コマンド自身のヘルプには cli://<command> を使い、cli:// 単体がそのエントリーポイントです。このヘルプはサーバー自身が持つコマンドから応答されるため、読み取ってもプロセスは起動せず、コマンドが --help で出力するのと同じテキストが返されます。カタログが保持していないエンティティの catalog:// 読み取りには、見つからないと応答します。それが、そのエンティティを宣言するカタログファイルがちょうど 1 つロード時にスキップされたためである場合、応答のメッセージは URI だけでなく、そのファイル、それが破っている制約、その条件の短いコードを示します。これは、同じファイルについて aggrega build が最初に示す拒否と同じです。resources/list はパラメーターなしでアドレス指定できるものを列挙し、resources/templates/list はすべてのファミリーの URI 形式を通知します。

  • ツール — ワークスペースに対するアクションであり、tools/list はそのすべてを応答します。

    アシスタントが最初に出会うツールは、オーサリングのループに合わせた形になっています。ワークスペースが何を保持しているかを調べる list-entities と list-releases、その kind が必須とするフィールドを持ち、値が必要な箇所すべてにプレースホルダーを置いたスケルトンを作る scaffold(example を送ると、ドキュメントの実行可能な例の 1 つを新しいディレクトリに書き出し、そのディレクトリの場所、書き出したファイル、それをビルドするコマンドを応答します。list: true を送ると、例を一覧表示します)、エンティティの JSON Schema を得る get-schema、ドラフトを検証する validate(ドラフトにまだ残っているプレースホルダーすべてと、それぞれが受け取るものを示します)、カタログエンティティ(またはレジストリから参照によって読み込んだエンティティ)を説明する describe、Release の依存関係をローカルキャッシュに解決してそのロックファイルを書き出す pull、Release をレンダリングされたアーティファクトにビルドする build(デフォルトではメモリ上で行い、アーティファクトはディスクに書き出されません。write を送ると、aggrega build が書き出すのと同じワークスペースルートの dist/ に書き出されます。依存関係が先に解決されるのは auto_pull を送った場合だけです)、Wasm ゲストから Plugin エンティティを生成する gen-catalog、そしてコンパイラの診断を実行可能なガイダンスに展開する explain-error です。診断が停止条件の短いコードで始まる場合、その展開にはその条件と、オーサリング上の修正について公開されている手順解説が含まれます。これは、ターミナルで aggrega explain が同じコードに対して行う展開と同じものです。

    サーフェスの残りは、後回しにされるのではなく同じ応答に含まれています。サーバー内で動作するその他のツール — lint、ドキュメント内のある位置に書かれた接続を示すツール、2 つの候補ツール、アタッチメントコンテナと挿入位置のツール、ドキュメントに 1 つの限定された編集を適用するツール、エンティティ自身の入力を固定するで説明するとおりエンティティの入力のコンテンツピンを記録する pin、後述する 4 つの公開ツール、さらにキャッシュと設定済みレジストリのインベントリ — に加え、標準入出力でこのサーバーを起動したクライアントに対しては、本来入力できる各コマンドのツールが、その呼び出しパスにちなんだ名前で提供されます。これらのコマンドツールはそのトランスポートにのみ存在します。HTTP 経由で到達したサーバーは、HTTPS 経由でサーバーに到達するで説明する理由により、いずれも提供しません。後の呼び出しのために保留されるものはありません。 ツールリストのどれだけをモデルに提示するかはクライアントが決めることです。クライアントは定義を取得し、何を読み込むかを選びます。クライアントが受け取らなかった定義は、そのツール名がワイヤー上でどれほど到達可能であっても、モデルが決して呼び出せない操作です。リスト全体がクライアントの受け入れられる量を超える場合は、サーバーが通知する内容を絞り込むの方法で短くします。describe-capabilities は、そのサーフェスをオーサリング中のエンティティの種類に絞り込みます。 kind を送ると、その種類に対応するツールを、説明文の語句ではなく各ツールが宣言する種類から読み取って応答します。引数なしで送ると、このサーバーが提供するすべてのツールについて同じインデックスを応答します。各ツールの名前、1 行の目的、対応する種類、書き込みを行うかどうかを含み、引数スキーマは含まないため、サーフェス全体が 1 つの読みやすい応答で届きます。cli- ツールについては、書き込みを行うかどうかは実行するコマンドが書き込むかどうかで決まります。cli-build は、コマンドがレンダリング済み成果物をワークスペースルート配下に保存するため書き込みありと報告されます。cli-scaffold も同様に書き込みありと報告されます。example を送ると、コマンドがドキュメントの実行可能な例の 1 つを新しいディレクトリに書き出すためです。一方、読み取りのみのコマンドは、途中でマシン上のすべてのプロジェクトが共有するキャッシュを満たす場合でも、サーバー内で同じ操作を実行するツールと同様に読み取りのみと報告されます。tools で 1 つ以上を指定して送ると、まさにそれらのツールの完全な定義と引数スキーマを応答します。cli- ツールは種類によって絞り込まれることはありません。コマンドがどのエンティティの種類に対応するかを記録するものがないため、種類で絞った応答にはそれらが含まれず、引数なしのインデックスで参照します。コマンドツールの引数はコマンド自身のフラグにちなんで命名されるため、--output-dir は output_dir として送ります。認識されない名前は、黙って破棄されるのではなく、受け付けられる綴りを列挙したうえで拒否されます。

    標準入出力では、一部の機能が二重に提供されます。オーサリングループ向けのツールはその操作をサーバー内で実行し、同じ機能を持つコマンドにちなんで名付けられたツールはそのコマンドを実行します。両者の動作は同じではないため、その transport では互いに相手を名指しして違いを述べます。HTTP ではコマンドツールが存在しないため、呼び出し側が到達できないツールを指すことのないよう、この対応関係を示す文は省かれます。使うべきはサーバー内で実行されるほうです。読みやすいテキストに加えて機械可読な結果を返すため、アシスタントは判定、ファイル一覧、診断を、解析が必要なトランスクリプトとしてではなくフィールドとして受け取れます。コマンドツールは実際のコマンドを別プロセスで起動するため、実行されるマシン上でそのコマンドが行うことをすべて行います。コマンドが書き込む場所へのディスク書き込みも含みます。cli-build はレンダリングされた成果物をワークスペースルートの dist/ に、トレース付きビルドのファイルをその隣の .trace/ に書き込み、返す最終行ではそのディレクトリをフルパスで示します。そして、実行したコマンドラインとそのコマンドが出力したテキストだけを返します。コマンドが宣言しているフラグのうち、もう一方のツールが受け付けないものが必要な場合に使用します。

    そのコマンドラインは、このサーバーの起動時に指定された、設定を決めるグローバルフラグ(指定した場合の --config と --offline)で始まり、その後にコマンドと呼び出し自身のフラグが続きます。 そのため、コマンドはここにある他のすべてのツールが読むのと同じ設定を読みます。--offline 付きで起動したサーバーはコマンドをオフラインで実行し、--config 付きで起動したサーバーはそのグローバルファイルのもとでコマンドを実行します。呼び出しが自ら送るフラグはそれらの後に置かれて優先されるため、ある呼び出しで offline: false を指定すると、その呼び出しに限りネットワークにアクセスし、返されるコマンドラインには両方が示されます。サーバーがワークスペースルート付きで起動された場合(--workspace-root または AGGREGA_WORKSPACE_ROOT による)、コマンドラインはその 2 つよりも前に、そのルートを --workspace-root として先頭に置きます。 そのため、コマンドはサーバーの起動ディレクトリからワークスペースを探すのではなく、同じフラグを付けて入力した場合と同様に、またサーバー内で実行されるすべてのツールと同様に、そのディレクトリをワークスペースルートとして扱います。workspace_root を送る呼び出しは独自のルートを指定し、コマンドラインにはそれだけが含まれます。空の値も含まれ、コマンドはそれをターミナルで --workspace-root "" を読むのと同じく、サーバーの起動ディレクトリからワークスペースを探す指示として読みます。どちらも指定されずに起動したサーバーはルートを渡さないため、そのコマンドは Which workspace a call is answered in(呼び出しがどのワークスペースで応答されるか) がすべてのツールについて定める規則に従い、そのディレクトリからワークスペースを探します。ただし、デスクトップバンドルの起動で Workspace folder 設定が空の場合は例外で、独自のワークスペースを指定しない呼び出しはコマンドを起動せず、その設定に関する拒否で応答されます。コマンドは、呼び出しまたは起動が指定するワークスペースルートで起動します。 すなわち、呼び出し自身の workspace_root(すべてのツールと同じように読み取ったもの。絶対パスは送られたまま、相対パスはルートを指定しない呼び出しが応答されるルートを基準とし、その絶対形式でコマンドに渡します)、それがなければサーバー起動時のルートです。そのため、呼び出しが読み込むファイルとして渡す相対パス(validate するドキュメント、--release や --catalog)は、そこで開いたターミナルと同様にそのワークスペース内で読まれ、コマンドが実行するビルドはそのルートの下に dist/ を書き込みます。ルートが何も指定されていない場合(起動時のルートがなく、workspace_root もないか空の場合)、コマンドはサーバーの起動ディレクトリで起動し、そこから相対パスを読みます。存在しないフォルダを指す workspace_root は読み取られたとおりに(絶対パスは送られたまま、相対パスは完全な形式で)渡され、コマンドが独自の文言で拒否します。コマンド拡張プラグインが登録するコマンドには、これらはいずれも渡されません。そのコマンドはグローバルフラグを解析せず、すべての引数を読まずにプラグインへ渡すためで、これはターミナルでもここでも同じです。起動するフォルダは他のすべてのコマンドと同じです。

    いくつかのコマンドは、コマンドツールが存在する標準入出力でさえ意図的に除外されています。HTTP ではすべてが存在せず、これは個々のコマンドではなく transport の性質です。標準入出力では、それぞれ理由があって除外されています。デーモンとこのサーバー自身は結果を返すことがありません。ターミナルからパスワードを読むコマンドには読み取り元がありません。シェル補完スクリプトを書き出すコマンドにはインストール先のシェルがありません。保存済みの認証情報の削除は、指定したワークスペースではなくマシン全体のストアに作用します。そして、対話的な ID トークンの取得には提供できる非対話形式がありません。同じくマシン全体に関わるという理由で除外されているのが aggrega plugin run-local で、これは指定したパスから .wasm ゲストを読み込みます。このコマンドの目的は置いた場所にあるファイルを読むことなので、限定できるワークスペースがなく、読み込みはゲストが存在する前にプロセス自体で行われます。ゲストは実行時に何も付与されません(ディレクトリもソケットも環境もありません)が、それは読み込みではなくモジュールに対する制限なので、除外を決める理由ではありません。パスを指定するのが自分自身となるターミナルで実行してください。署名と公開はまったく別のケースであり、その違いによってこのリストに含まれていません。 いずれも与えられた入力または環境の入力から ID を解決し、利用できるものがない場合は明示的に拒否するため、誰も見ていなくても完了する形式があります。一方、対話的なトークン取得は、原理的にもどの入力でも満たせない動作です。そのため、これらは二重に提供されます。コマンドとして、そして Publishing, signing and withdrawing で説明する 4 つのプロセス内ツールとしてです。コマンドラインであればブラウザを開く場面では、その場にいない人を待つのではなく、拒否して代わりに何を指定すべきかを示します。

呼び出しがどのワークスペースで応答されるか

呼び出しは workspace_root でワークスペースを指定します。指定しない場合は、サーバーの起動対象となったワークスペースで応答されます。 起動時に --workspace-root または AGGREGA_WORKSPACE_ROOT でルートが指定された場合、そのルートは、すべてのコマンドでのこのフラグと同様に、ワークスペースルートそのものになります。それより上位で囲んでいるワークスペースは探索されないため、起動時にはワークスペースの .aggrega-config.yaml を含むフォルダーを指定します。呼び出しは、サーバー内で動作するツールでもコマンドツールでも、そこで応答されます。起動時にルートが指定されなかった場合、ワークスペースはサーバーが起動されたディレクトリから見つけられます。これは、そこでターミナルに入力したコマンドがワークスペースを発見するのとまったく同じです。その順序は The other ways a project root is recognised で説明しています。ただし、デスクトップバンドルの起動で Workspace folder 設定が空の場合は例外で、後述のとおり、そのような呼び出しを代わりに拒否します。相対パスの workspace_root は、ワークスペースを指定しない呼び出しが応答されるルートを基準に読み取られます。 これは、起動時に指定されたルート、指定がなかった場合はサーバーが起動されたディレクトリから解決されるワークスペースルートです。そのため、呼び出しはワークスペースがマシン上のどこにあるかを知らなくても、quickstart-ai/1 のようにワークスペース内のフォルダーを指定できます。絶対パスは指定されたとおりに使われます。コマンドツールを含め、すべてのツールがこのように読み取ります。相対パスを読み取る基準となるルートがない場合(既存のフォルダーではない起動ルート、または Workspace folder が空のデスクトップ起動)、相対パスは、ワークスペースを指定しない呼び出しと同様に拒否されます。存在しないフォルダーやファイルを指す workspace_root は、ツールが他の処理を行う前に拒否されます。その際、コマンドが --workspace-root を拒否するのと同様に、引数の名前を示し、値を引用します(絶対パスは送信されたとおり、相対パスは読み取られた完全な形式で)。

既存のフォルダーではない起動ルートは、標準入出力では拒否として提供されます。 --workspace-root または AGGREGA_WORKSPACE_ROOT が存在しないフォルダーやファイルを指している場合、サーバーは拒否をエラーストリームに書き出したうえで、それでも起動します。そのため、そのストリームをユーザーに一切表示しないクライアントでも、理由は表示されます。サーバーは initialize と、ツール、リソース、プロンプトの一覧に応答し、そのワークスペースで動作するはずのすべての呼び出しには拒否で応答します。ツール呼び出しには失敗した結果として、catalog:// エンティティやドキュメントページの読み取りにはエラーとして応答します。拒否には、フラグ、または変数とそれを設定するデスクトップアプリケーションの Workspace folder 設定(Claude Desktop で説明している設定)が示され、値は与えられたとおりに引用されます。クライアントが値を埋めずに送信した値は、届いたとおりに引用され、その中の何も解釈されません。コマンドを実行するツールは、独自のワークスペースを指定しない呼び出しに対してはコマンドを一切起動せず、同じ拒否で応答します。そのコマンドが起動するはずのフォルダーが存在しないためです。独自のワークスペースを絶対パスで指定する呼び出しはそこで応答されます。相対パスで指定する呼び出しには、それを読み取る基準となるフォルダーがないため、同じ拒否で応答されます。どのワークスペースでも動作しないもの(スキーマ、プロンプト、コマンドのヘルプ)は、どのサーバーでも同じように応答されます。リスナーの場合は、代わりに起動時、何もバインドされる前に同じ拒否で拒否されるため、監視する側は失敗を通常確認する場所で読み取れます。

Workspace folder 設定が空のデスクトップ起動も、同じように拒否として提供されます。 デスクトップバンドルは常に、Workspace folder の内容を保持した AGGREGA_WORKSPACE_ROOT をサーバーに渡し、その横に AGGREGA_BUNDLE_VERSION を設定します。一方、アプリケーションはサーバーをプロジェクト内ではなく、自身が選んだフォルダー(多くの場合システムフォルダー)で起動します。そのため、--workspace-root なしで起動され、環境に AGGREGA_BUNDLE_VERSION があり、AGGREGA_WORKSPACE_ROOT が空または存在しない標準入出力のサーバーは、起動されたフォルダーからワークスペースを探しません。拒否をエラーストリームに書き出したうえで、それでも起動し、存在しない起動ルートの場合と同じように応答します。ワークスペースで動作するはずで独自のワークスペースを指定しないすべての呼び出しには、デスクトップアプリケーションが Workspace folder 設定を空にしてサーバーを起動したため AGGREGA_WORKSPACE_ROOT がワークスペースルートを指していないことを述べ、Workspace folder をワークスペースの .aggrega-config.yaml を含むフォルダーに設定するよう伝え、さらにサーバーの起動後に設定したフォルダーは拡張機能をオフにしてから再びオンにするかアプリケーションを再起動すると有効になることを述べる拒否で応答します。アプリケーションが設定をサーバーに渡すのは、サーバーを起動するときだけだからです。コマンドを実行するツールは、そのような呼び出しに対してコマンドを一切起動しません。独自のワークスペースを絶対パスで指定する呼び出しはそこで応答され、相対パスで指定する呼び出しは、それを読み取る基準となる Workspace folder がないため、同じ拒否で応答されます。どのワークスペースでも動作しないものは、どのサーバーでも同じように応答されます。サーバーはこの起動を AGGREGA_BUNDLE_VERSION だけで識別します。この変数を設定しないバンドルでは、空の設定はルートなしとして読まれ、変数を手動で設定してルートを指定しない起動は、バンドルの場合と同様に拒否されます。それ以外の空の値は引き続きルートを指定しません。AGGREGA_BUNDLE_VERSION を持たない起動での空の AGGREGA_WORKSPACE_ROOT、空で入力された --workspace-root、リスナー、aggrega serve、その他すべてのコマンドは、いずれもそれを未設定として読みます。

ワークスペースが見つからず、指定もされなかった場合、ワークスペースに関する応答はどのフォルダーを使用したかを示します。 起動ルートがなく、呼び出しに workspace_root がなく、呼び出しが応答されたフォルダーからワークスペースを特定するものが何もない場合、呼び出しはそのフォルダーで応答されます。ツールの結果がワークスペースによって変わる場合(コマンドラインでコマンドが警告を出すのと同じツール)、そのテキストの末尾には、コマンドラインの警告 <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace と、ワークスペースの .aggrega-config.yaml を含むフォルダーを指す workspace_root を送信するよう伝える 1 行が付きます。設定の読み取りやプラグインの一覧など、ワークスペースによって決まらない応答は、ワークスペースについて何も示しません。この一文は構造化された結果に独自のフィールドを追加しません。構造化された結果では、The two parts of an answer で説明しているとおり、テキストを保持する text_answer にこの一文が含まれます。別プロセスでコマンドを実行するツールには、同じ内容を伝えるコマンド自身の行が、コマンドが出力したとおりに含まれます。そのようなフォルダーでは、アーティファクトキャッシュには何も書き込まれません。そこでの pull や、先に依存関係の解決を求めるビルドは、何かが取得される前に拒否され、そのフォルダーと 2 つの解決方法(workspace_root を送信するか、フォルダーに workspace: ブロックを含む .aggrega-config.yaml を用意する)が示されます。Recipe や FeatureRecipe の pin や公開も、エンティティが完全に記述しているリモートソースを取得する場合(pin するため、または pin を比較するため)には、そのソースが取得される前に同じように拒否されます。エンティティにソースがない、ローカルソースである、または各 Release が座標を埋めるソースであるために何も取得しない場合は、他の場所と同じように応答されます。そこで先に何も解決しないビルドはレンダリングを行いますが、ロックファイルが pin していてキャッシュにもう保持されていない外部入力は再取得されません。レンダリングには、オフライン状態のときと同様に、入力の代わりにその同じ一文が伝えられます。HTTP 経由の応答には、この一文は含まれません。リスナーは常に、与えられたか見つけたワークスペースを提供するためです。Workspace folder 設定が空のデスクトップバンドルの起動でも含まれません。この起動では、独自のワークスペースを指定しない呼び出しは、起動されたフォルダーで応答されるのではなく拒否されるためです。

絶対パスで指定された Release またはドキュメントに関する呼び出しは、ほかに何もワークスペースを決めていない場合、そのファイル自身のワークスペースで応答されます。 起動時にルートが指定されておらず、呼び出しが workspace_root を送らず、サーバーが起動されたディレクトリがどのワークスペースにも定まらない場合、ワークスペースはそのファイルが置かれているフォルダーから改めて探索され、そこで見つかったもの(ファイルが属するプロジェクト、あるいは何も見つからなければそのフォルダー)が、呼び出しに応答するワークスペースになります。これはターミナルで入力したコマンドが従う規則と同じであるため、呼び出しが指定する Release またはエンティティドキュメントに関するすべてのツールに当てはまります。ビルド、pull、検証、lint、説明、Release の観点での一覧、Release のグラフのノードについての問い合わせ、pin、エンティティの公開、編集、ドキュメント内の位置の読み取りがこれに該当します。呼び出しが Release とドキュメントの両方を指定する場合は、Release が決め手になります。そのため、プロジェクトの外でサーバーを起動したクライアントでも、プロジェクト自身の設定からビルドされた Release をそのプロジェクト内に得られます。呼び出しが指定するほかのパスは通常どおりに読み取られ(相対パスはサーバーが起動されたディレクトリから)、別プロセスでコマンドを実行するツールも同じワークスペースから応答されます。コマンドがその同じディレクトリで同じ規則に従うためです。起動時に指定されたルート、呼び出しが送る workspace_root、それ自体がワークスペース内にある起動ディレクトリ、および相対パスで指定された Release やドキュメントは、そのまま使われます。HTTP ではこうした状況は生じません。リスナーは常に、与えられたか見つけたワークスペースを提供し、呼び出しが指定するパスはすべてそこからの相対パスになります。Workspace folder 設定が空のデスクトップバンドルの起動でも生じません。この場合、独自のワークスペースを指定しない呼び出しは、どのファイルを指定していても拒否されます。

サーバーが公開するツールを絞り込む

mcp.announce_tools は、このサーバーが公開するツールを、ツール一覧が報告するとおりの綴りで指定します。 このキーを省略すると、このサーバーが持つすべてのツールが公開されます。これがデフォルトであり、プロトコルに従うクライアントが想定する形です。リストを書くと、そのツールだけが公開されます。リストから外したツールはツール一覧に現れず、describe-capabilities の応答にも現れず、それでも名前を指定して呼び出された場合は拒否され、その拒否にはこの設定の名前が示されます。空のリストを書くと、何も公開されません。したがって、キーを省略することと [] を書くことは異なる意味を持ち、この設定には自動で補われるデフォルト値はありません。

接続先のクライアントが登録するツールの数に上限を設けている場合に設定してください。 上限は、接続しているすべてのサーバーにまたがって課されることもあります。そのクライアントが必要とするツールを指定します。この上限こそがこの設定の存在する理由であり、上限が適用されるクライアントは通常、自身の標準入出力を介してこのサーバーを起動したクライアントです。そのため、http トランスポートが起動するリスナーを設定する mcp ブロックの他の項目とは異なり、このキーはサーバーがどのトランスポートを使う場合でも読み込まれます。

この設定は公開する範囲を絞り込むだけで、それ以上のことはしません。 ここでツールを指定しても、何も広がりません。機能そのものを取り下げる mcp.deny_reach を解除することはないため、ここで指定したツールでも、その設定が取り下げる種類のものであれば一覧に含まれず、その設定の名前を示して拒否されます。呼び出し元のトークンが持つスコープを解除することもありません。ここで指定したツールは、スコープに関係なく一覧に表示されますが、スコープが許可しない呼び出しはやはり拒否され、許可に必要なスコープの名前が示されます。いずれの場合も、呼び出し元が受ける拒否はこの設定ではなく、もう一方の制約によるものです。この設定による拒否はチャレンジを含まず、スコープも示しません。どのような資格情報も、サーバーが提供すると決めたものを変えることはないからです。代わりに示されるのはこの設定であり、拒否を読む人が対処できるのはこの設定だけです。

すべての名前は、このバイナリが持つツールのものである必要があります。 どのツールにも該当しない名前があると、サーバーは何も提供する前に停止し、その拒否には実際に持っているツールが列挙されます。そのため、綴りの誤りは、指定したより黙って狭くなった公開範囲としてではなく、起動時に判明します。aggrega コマンドを別プロセスで実行する cli- ファミリーの名前は、どちらのトランスポートでも受け付けられますが、HTTP では何も公開しません。HTTP では、そもそもそのようなツールはどの呼び出し元にも提供されないからです。

公開されるツールの集合はプロセスの起動時に固定されます。 そのため、変更するには再起動が必要であり、すでに接続しているクライアントの一覧が途中で増えることはありません。

サーバーがどのリリースに由来するか

引数なしで送られた describe-capabilities は、このサーバーがどのリリースに由来するかを示します。 その構造化された応答には server_version が含まれます。これは aggrega 実行ファイルが自身について報告するバージョンであり、同じファイルに対して aggrega version が出力するものと同じです。また、そのテキストはインデックスの前に、そのバージョンを示す 1 行で始まります。構造化された応答はその同じ行を version_summary として一字一句そのまま含むため、構造化された応答だけをモデルに渡すクライアントも、その行をモデルに渡すことになります。

デスクトップバンドルがサーバーを起動した場合、同じ応答はその横にバンドルのバージョンも示します。 バンドルはプログラムを含みません。バンドルは Path to the aggrega executable 設定が指定する aggrega 実行ファイル(デフォルトではコマンド名 aggrega で、アプリケーションはそれを自身の PATH から探します)を起動するため、バンドルと実行ファイルは別々にインストールされ、異なるリリースに由来することがあります。また、バンドルを一覧表示するアプリケーションはバンドル自身のバージョンしか表示しません。バンドルはサーバーの環境に AGGREGA_BUNDLE_VERSION としてバージョンを渡します。サーバーは起動時に一度だけそれを読み取り、応答は bundle_version としてそれを含みます。2 つは書かれたとおりに厳密に比較されます。1 つのリリースのバンドルと実行ファイルにはそのリリースのバージョンが同じ形式で刻まれ、開発ビルドはどのリリースとも異なる表記になるため、これは妥当な比較です。2 つが等しい場合、その行は両方を示し、それ以上は何も述べません。異なる場合、その行は両方を示したうえで、実行ファイルとバンドルが異なるリリースに由来することを述べます。また、接続時にサーバーがモデルに提供するガイダンスも同じ文で始まるため、モデルが尋ねる前にその違いがモデルに提示されます。

バンドルが起動していないサーバーは、自身のバージョンのみを報告します。 ターミナルから、エディタの設定から、またはリスナーとして起動されたサーバーは、環境に何かがその変数を設定しない限り、bundle_version を含みません。標準入出力上のサーバーがその変数を持つ場合、さらにもう 1 つの点でバンドルによる起動とみなされます。ルートが指定されていない場合、呼び出しがどのワークスペースで応答されるかで説明するとおり、空の Workspace folder 設定を拒否します。kind または tools を送られた describe-capabilities の呼び出しは、サーバーではなくツールについて応答するため、server_version、bundle_version、version_summary のいずれも含まず、そのような行もありません。

違いは報告されますが、拒否されることはありません。 サーバーは起動し、2 つが一致している場合とまったく同じようにすべての呼び出しに応答します。デスクトップへのインストールにとって違いが何を意味するか、また 2 つをどのように揃えるかは、MCP サーバーの接続にあります。

HTTPS 経由でサーバーに接続する

aggrega mcp --transport http は、標準入出力の代わりに HTTP でプロトコルを提供します。ワークスペース設定の mcp.transport はこのフラグが上書きするキーで、そのデフォルト値 stdio は、コマンドを起動するクライアントが想定する値です。そのため、他の人が接続するサーバーは設定に transport: http を持ち、その設定が適用されるディレクトリから起動されたクライアントは、引き続き自身のストリーム経由でサーバーに接続します。どちらの場合も同じサーバーであり、同じワークスペース、同じプロトコルの機能を持ちます。変わるのは、メッセージがサーバーに届く方法、呼び出しの終わり方、そして運用者が保持すべきものです。このセクションは運用者が設定する内容を扱います。稼働中のサーバーに接続するためにクライアントが必要とするエントリはMCP サーバーの接続にあります。

アドレスはトランスポートを選択しません。 --listen <address>、またはフラグがない場合の mcp.listen は、http が選択されたときにリスナーがバインドする場所を指定するだけで、それ以上の意味はありません。そのため、どちらからもアドレスが与えられない http は、何もバインドされる前に拒否され、その拒否メッセージは両方を挙げます。トランスポートが stdio のとき(--transport stdio と入力された場合、mcp.transport: stdio と設定された場合、またはデフォルトのままの場合)に入力された --listen も拒否され、そのアドレスで提供するフラグとして --transport http を挙げます。空の値を与えられた --listen は、トランスポートにかかわらず、アドレスを指定していないものとして拒否されます。また、設定だけが指定するアドレスは、自身のストリーム経由で通信するサーバーでは使用されず、サーバーはそのことをエラーストリームに 1 行で示し、それを設定したファイルと mcp.transport: http を挙げます。この最後のケースは意図的にどこでも拒否されません。これは、リスナーの設定を持つディレクトリでクライアントがコマンドを起動するときに行う起動であり、transport: http を書き忘れたリスナーの設定はリスナーをまったく起動しないので、そこで問題が明らかになります。

HTTP 経由で接続されるサーバーは、別プロセスで aggrega コマンドを実行するツールを提供しません。 これらのツールは、標準入出力経由でこのサーバーを起動したクライアントのためだけに、そのクライアント自身のマシン上に存在します。そこでは、フォルダーやフラグを指定しても、呼び出し元がすでに持っていない権限は何も与えられません。HTTP 経由でサーバーに接続する呼び出し元は、サーバーが動作するホストを所有していないため、サーバー自身の権限でそのホストのファイルシステムに作用するコマンドは、代わりにホスト上の端末で実行します。これらのツールは、提供されたうえで拒否されるのではなく、一覧からも describe-capabilities からも除かれており、それを指定する呼び出しにはその旨を示すエラーが返されます。これはトランスポートの性質であり、設定ではありません。これらを元に戻す設定はありません。

デプロイする前に Nothing is served without a credential をお読みください。 エンドポイントへのすべてのリクエストは認証情報を持ち、認証情報のないリクエストを処理する設定はありません。設定で選択するのは、このサーバー自身がベアラートークンを検証するか、前段のプロキシがすでに検証した呼び出し元を読み取るかです。

2 つのデプロイ形態

プロセス自身が TLS を終端します。 mcp.tls.cert_file に PEM 証明書チェーンを、mcp.tls.key_file にその秘密鍵を設定すると、リスナーは指定されたアドレスで直接 HTTPS を提供します。両方のファイルはプロセスの起動時に読み込まれるため、差し替えた証明書はプロセスを再起動することで反映されます。一方だけを設定すると、フォールバックせずに起動時に拒否されます。鍵のない証明書は提示できず、証明書のない鍵は何も示さず、また一方のパスの入力ミスは暗号化されていない通信を提供し始める理由にはならないからです。

前段のプロキシが TLS を終端し、限定されたリスナーに転送します。 両方のキーを未設定のままにすると、リスナーは平文で提供し、これはループバックまたは Unix ソケット上でのみ受け入れられます。そのため、そのホスト上にすでにあるもの以外は接続できません。これはリバースプロキシ、サイドカー、サービスメッシュが使う形態であり、証明書がこのプロセスの中ではなく前段に置かれる形態です。

それ以外のアドレスでの平文リスナーは、何もバインドされる前に拒否され、その拒否メッセージは両方の TLS キーを挙げます。これを解除する設定も、例外となるアドレスもありません。自身の証明書を持たずにネットワークから受け付けるリスナーは決して安全ではないため、プロセスはその形態で起動するのではなく、起動を拒否します。

アドレスの形式

--listen と mcp.listen は、次の 2 つの形式のいずれかを取ります。

  • host:port — 127.0.0.1:7777 や 0.0.0.0:8443 などの TCP アドレスです。ループバックとは 127.0.0.1、::1、または名前が解決されるすべてのアドレスがループバックアドレスである場合の localhost を意味します。それ以外はすべてネットワークアドレスであり、証明書が必要です。マシンが持つすべてのインターフェースを意味する空のホスト、特定のインターフェースのアドレス、そしてその他の名前(現時点でループバックアドレスに解決されるものも含む)が該当します。リスナーがバインドできる場所は、変わりうる名前解決に依存すべきではないからです。
  • unix: に続くファイルシステムパス — unix:/run/aggrega/mcp.sock などの Unix ドメインソケットです。ソケットは、それが置かれたホストからしか到達できないため、証明書は不要です。

ソケットのパスは、相対パスも含め、書かれたとおりに扱われます。それを宣言した設定ファイルを基準に解決されないのは意図的です。同じアドレスは、宣言元のファイルを持たない --listen からも渡されるためです。相対パスが指す場所を参照してください。

リスナーが受け付けるもの

エンドポイントは /mcp の 1 つで、POST を受け付けます。 JSON-RPC メッセージはそれぞれが独立したリクエストであり、いかなる種類のセッションも保持されません。クライアントが先に送った内容によって後のリクエストへの応答が決まることはなく、セッション識別子が発行されることもなく、クライアントが送るセッションやストリーム再開のヘッダーは無視されます。そのエンドポイントに対するそれ以外のメソッドには Allow: POST を付けて 405 で応答し、それ以外のパスには 404 で応答します。どちらも認証情報の確認より前に決まるため、どのみち何も提供しないパスやメソッドへのチャレンジから、探査によって得られる情報はありません。

リクエストには 1 つの JSON オブジェクトとステータスコードで応答します。また、呼び出しがそのオブジェクトに至るまでに進捗を報告した場合は、そのオブジェクトで終わるイベントのストリームで応答します。これについては 長い呼び出しの進み具合を知らされる で説明します。通知、つまり id を持たないメッセージには、空のボディで 202 を返します。そのどちらでもないメッセージは、JSON-RPC のレスポンスも含めて 400 で応答します。クライアントがこのサーバーに送るのはリクエストと通知だけだからです。

両方のプロトコルリビジョンが、標準入出力の場合とまったく同じようにここでも提供されます。 2026-07-28 のリクエストはボディの内容をトランスポートヘッダーに反映するため、中継者はボディを解析せずにルーティングできます。MCP-Protocol-Version はボディが示すリビジョンを、Mcp-Method はボディが指定するメソッドを、Mcp-Name は名前で対象を指定するメソッドについてその対象を運びます。ボディと食い違うヘッダーには 400 で応答します。2025-06-18 のクライアントは initialize ハンドシェイクで開始し、これにはステートレスに応答します。このクライアントは、そのリビジョンを示すバージョンヘッダーを付けても省略してもかまいません。サーバーが話さないリビジョンを指定するリクエストには、対応する 2 つのリビジョンを列挙して 400 で応答し、提供していないメソッドを指定するリクエストには 404 で応答します。

mcp.allowed_origins は、リクエストが Origin ヘッダーを持つ場合にのみ参照されます。これは実際にはブラウザが送信したことを意味します。リストにないオリジンを示すリクエストには 403 で応答し、そのヘッダーを持たないリクエストは処理されます。ブラウザでないクライアントはそのヘッダーを送らないため、エントリは不要です。ブラウザベースのクライアントには必ずエントリが必要です。リストはオペレーターが書くまで空であるため、それまではどのオリジンも含まれず、すべてのブラウザリクエストに 403 で応答します。エンドポイント自身のアドレスで提供されるページからのリクエストも例外ではありません。エントリはヘッダーと完全一致で比較されるため、ブラウザがオリジンを送る形式で書きます。すなわち、小文字のスキーム、://、小文字のホスト、そしてスキームのデフォルトでない場合は : とポートです(例: https://app.example.com)。パスを含むエントリ、末尾に / があるエントリ、スキームのないエントリ、大文字を含むエントリは、決して一致し得ないため、設定の読み込み時にそのエントリを示して拒否されます。

mcp.limits は受け付けるトラフィックを制限します。 max_body_bytes を超えるボディには 413 で応答し、上限を超えて読み込むことはありません。すでに max_concurrent_requests 件が処理中のときに届いたリクエストは、見えない処理の後ろに並べられるのではなく、503 で応答します。1 分間に requests_per_minute を超えて送信する呼び出し元には 429 で応答します。これはその呼び出し元だけに対してカウントされるため、ある呼び出し元が大量に送信しても、別の呼び出し元が影響を受けることはありません。各上限のデフォルトは 設定リファレンス でそれぞれのキーの横に記載されており、どの上限にも無効にする値はありません。

1 プロセスにつき 1 ワークスペース

サービスを提供するプロセスが応答するワークスペースは、起動時に固定されます。 --workspace-root がそれを指定し、フラグがない場合は AGGREGA_WORKSPACE_ROOT 変数がそれを与えます。指定されたフォルダがワークスペースルートそのものであり、その上位は探索されません。存在しないフォルダは拒否され、その際には 2 つのうちどちらがそれを与えたかを示し、与えられた値をそのまま引用します。リスナーの場合はバインド前に、標準入出力上のサーバーの場合はそのワークスペースで動作するすべての呼び出しへの応答の中で拒否されます。これは 呼び出しがどのワークスペースで応答されるか で説明するとおりです。そのため、入力されたのではなくクライアントが組み立てた起動でも、何を渡されたかが示されます。どちらもない場合、標準入出力上のサーバーは起動されたディレクトリからワークスペースを解決します。そこにワークスペースを固定するものが何もない場合は、ワークスペースに関する各応答がどのフォルダを使用したかを示し、Workspace folder 設定が空のデスクトップバンドルの起動では、代わりに自身のワークスペースを指定しない呼び出しを拒否します。これは 呼び出しがどのワークスペースで応答されるか で説明するとおりです。一方リスナーは、そこでワークスペースが解決されない限りバインド前に拒否されます。HTTP 経由で到達されるプロセスはそのマシンを見ることのできない呼び出し元に応答するため、たまたま起動されたディレクトリではなく、オペレーターが選んだワークスペースを提供します。複数のプロジェクトを提供するには、プロジェクトルートごとに 1 つのプロセスを実行します。

HTTP 経由で届く呼び出しは、独自のワークスペースを指定できません。 workspace_root と catalog_dirs は黙って破棄されるのではなく、送られた引数を示して拒否されます。黙って無視された引数は、送信者にとって受け入れられた引数とまったく同じに見えるためです。提供されるワークスペースと並んで探索されるカタログディレクトリは、そのワークスペース自身の workspace.catalog_dirs 設定であり、workspace.releases の下で独自のディレクトリを与えられた Release の場合はその Release の設定です。これらはオペレーターが記述します。標準入出力上では両方の引数が受け入れられます。サーバーを起動したクライアントは呼び出し元自身のマシン上で動作しているためです。その場合、catalog_dirs のエントリは絶対パスであるか、相対の release が読み取られるワークスペースルートからの相対パスです。このルートは、呼び出し自身の workspace_root、起動、またはサーバーが起動されたディレクトリによって最初に確定したルートであり、絶対パスで指定された Release が呼び出しをその Release 自身のワークスペースに移す場合でも、引き続き読み取りの基準となるルートです。サーバーが動作するディレクトリがそれと異なる場所であっても、そのディレクトリからの相対パスにはなりません。

呼び出しが指定するパスも、そのワークスペースの内側にとどまります。 HTTP 上では、パス引数はワークスペースルートに対して解決され、その外側に到達する場合は拒否されます。ワークスペースの外へ上がっていく相対パス、別の場所を指す絶対パス、ワークスペース内にあるファイルやディレクトリへのリンクを通じてワークスペースの外へ出る相対パスは、いずれも引数を示す失敗として返され、ワークスペースルートもパスが到達したはずの場所も示されません。相対パスは送ったとおりに引用して返されます。すべてのパス引数は、ツールがそれを読み取るか書き込むかにかかわらず、ワークスペース境界 が示す内側の定義に従い、その行き先によって判断されます。gen-catalog が出力を書き込むディレクトリ、edit-document が書き戻すドキュメント、pin がロックをその隣に書き込むエンティティも、ツールが読み取るドキュメントと同様です。そのため、ワークスペースの外へ出るリンクの下にあるまだ作成されていないパスは、そのリンクと同様に拒否され、何も読み書きされません。提供されるワークスペースの設定が build.authoring_release として、または workspace.releases のキーとして指定する Release を指す release は、その設定を通じて到達されるため、ファイルがどこにあってもリンクを通じて受け入れられます。この例外を持つ引数は他にありません。意図したパスがそのワークスペースの内側にあるものの絶対パスで書かれていた場合、拒否の際には代わりに送るべきルート相対の表記が示されます。そのため、誤った形式を推測した呼び出し元には、誤っていたことだけでなく正しい形式が伝えられます。これは、呼び出しが対象として指定するパス(検証するドキュメント、ビルドする Release、生成が出力を書き込むディレクトリ)に当てはまり、ツールが読み取るパスと同様に書き込むパスにも当てはまります。ネットワーク経由でサーバーに到達する呼び出し元は、自分から見えないマシンにファイルの読み書きを依頼しているのであり、その読み書きはオペレーターが選んだワークスペースの中に保たれます。標準入出力上では、各ツールのパス引数は以下のそのツールの説明にある契約に従い、パスは絶対パスでもよく、ワークスペースの外を指してもかまいません。呼び出す人はサーバーが動作しているマシンの所有者であり、自分で選んだディレクトリに閉じ込めても何の得にもならないためです。操作そのものがワークスペースに含まれるドキュメントについてのみ応答する 2 つのツール、insertion-point と edit-document は、両方のトランスポートでこれを維持し、ワークスペース外のドキュメントを、そのように書かれている場合も、外へ出るリンクを通じて到達される場合も拒否します。標準入出力上で受け入れられるのは呼び出しが指定するパスだけであり、それ以上のものではありません。操作がその後自らの判断で読み書きするものは、両方のトランスポートで、同じコマンドをターミナルで入力した場合とまったく同じように扱われます。走査や検索はワークスペースの外へ出るリンクを通じて読み取らず、ワークスペース内の Release やその Manifest がパスで指定するファイルはワークスペースの外から読み取られず(呼び出しがワークスペースの外で指定した Release が指定するファイルは、その Release を含むディレクトリの外から読み取られません)、ディレクトリ(ワークスペース、または呼び出しが指定したディレクトリ)の下に書き込まれるファイルはそのディレクトリの内側にとどまります。ワークスペース境界 では、2 つのトランスポートをコマンドラインやエディターと並べて説明し、標準入出力上で開かれたままのものを示しています。クローンしたワークスペース内のドキュメントは、アシスタントを誘導してワークスペース外のパスを指定させることができ、そのパスは指定どおりに受け入れられます。

応答がサーバーのファイルシステムについて示すこと

HTTP 経由では、応答はサーバーのファイルシステム上の場所をワークスペースルートからの相対で示すか、伏せます。 サーバーを起動したクライアントはサーバーと同じ場所で動作するため、標準入出力経由ではすべての応答が各場所を操作が保持しているとおりに示します。保持の形が絶対パスであれば絶対パスで示し、いずれもその呼び出し元がすでに所有している場所です。リスナーにアクセスする呼び出し元はそれらの場所を選んでおらず、開くこともできません。また、一度公開してしまったサーバーはそれを取り消せません。そのため HTTP 経由では、応答は場所について次の 2 つのいずれかを呼び出し元に伝えます。

  • ワークスペース内の場所は、ワークスペースルートからの相対で示されます。 これは送信するパスと同じ形式であるため、ある応答で読み取った名前を次の呼び出しでそのまま送り返せます。ルートにある Release は release.yaml であり、そのロックファイルは release.lock です。
  • ワークスペース外の場所は伏せられ、ワークスペースルート自体も伏せられます。 そのフィールドは値を持たず、null になるか省略されます。attachment-container では、応答がすべてのサーフェスで報告されるのと同じ形を保つため、file が空のままになります。その横には、フィールド名に _withheld を付けた名前の印が置かれ、未設定ではなく伏せられたことを示します。たとえば workspace_root の横に workspace_root_withheld、file の横に file_withheld が置かれます。印は何かが伏せられた場合にのみ存在します。ルートが伏せられるのは、リスナーがちょうど 1 つのワークスペースを提供するためです。そのワークスペースがどこにあるかは、その中のものを示すために必要な情報ではありません。

場所が内側かどうかは、到達するファイルではなく、その書き方で判断されます。 サーバーの起動時のルートではなくシンボリックリンクのリンク先を経由して書かれたパスや、ルートの外に出てから戻ってくるパスは、いずれもワークスペース外と見なされ、伏せられます。この判断は伝える情報を少なくする方向に倒れ、ワークスペース外の場所を示す方向には決して倒れません。

HTTP 経由では、応答の可読テキストも同じ規則に従います。 テキスト、診断行、または失敗のメッセージがワークスペースの保持する場所(そのルートやその配下のもの、設定の読み込み元である設定ファイル、カタログの読み込み元であるディレクトリ)を示す場合、その場所はルートからの相対で書かれます。ワークスペース外にあるかルートそのものである場合は (location withheld) と表示されます。応答が自身のワークスペースについて組み立てるテキストでは、それを「このサーバーが提供するワークスペース」と呼びます。これらのいずれにも当たらない場所を操作がメッセージに書き込んだ場合、それは場所として認識されず、書かれたとおりに届きます。

HTTP 経由でこの規則が及ぶ応答:

  • list-entities、list-releases、cache-status、registry-list、search、attach-candidates、connection-candidates、insertion-point、attachment-container、connection-at-position、edit-document は workspace_root を伏せます。これらがもともとルートからの相対で示すパス(エンティティのソースファイル、Release のパスと lockfiles 配下のそのロックファイル、挿入位置や編集の対象となるドキュメント、編集が書き込んだファイル)は、どちらのトランスポートでも同じ表示になります。
  • cache-status は、サーバーがホスト上のファイルから読み込んだプラグインを示すものも伏せます。そのような識別子は provenance[].identities 内の該当位置で null になり、他の識別子はそれぞれの位置を保ち、エントリには identities_withheld の印が付きます。コンパイル済みモジュールの note は、そのモジュールのビルド対象となった識別子を示す 1 文であるため、そのいずれかがそのようなファイルを示す場合は note 全体が省略され、note_withheld の印が付きます。モジュールの digest はそのまま残ります。レジストリ参照や Plugin エンティティを示す識別子はそのまま返され、それらのみを示す note も同様です。ソースアーティファクトの label はキャッシュ内でのその場所であり、解決元の URL のホストとパスから組み立てられます。そのため、サーバー自身のファイルシステムから(file:// URL またはパスを通じて)読み込まれたリポジトリでは label が省略されて label_withheld の印が付き、size と digest はそのまま残ります。ネットワークホストを示す label はそのまま返されます。一覧のテキストでは、そうした場所を示すはずの箇所が (location withheld) と表示されます。
  • validate は target と、Release の場合は release をルートからの相対で示します。カタログ全体の場合、target はルートであるため伏せられます。diagnostics や notices 内の場所はテキストの規則に従います。
  • build は release をルートからの相対で示し、先に依存関係を解決したビルドは pull が返すとおりの dependency_resolution を含みます。write を送られたビルドは書き込んだディレクトリを output_dir として示し、これは(ルートからの相対で)dist となります。files 内の各パスはそのディレクトリからの相対です。refusal とその findings の各エントリは、file をルートからの相対で示すか、ドキュメントがワークスペース外にある場合は伏せます。advisories、deprecations、declined_external_inputs、および refusal の各 message はテキストの規則に従います。
  • pull は release と lockfile をルートからの相対で示します。diagnostics と incomplete_external_inputs はテキストの規則に従います。各 resolved エントリの source はどちらのトランスポートでもそのまま返されます。これは実行した内容を示すものであり、ホスト上の場所を示すことはありません。
  • describe は Release の release をルートからの相対で示し、エンティティの file は、そのドキュメントがワークスペース内にある場合にルートからの相対で示します。ワークスペース外のカタログディレクトリから読み込まれたエンティティでは file が伏せられます。mapping_diagnostics と deprecations はテキストの規則に従います。
  • lint は各検出結果の location.file をルートからの相対で示すか、エンティティがワークスペース外にある場合は伏せます。検出結果の message と suggest はテキストの規則に従います。
  • pin は entity と lock をルートからの相対で示し、公開に含まれる pin も同様です。
  • gen-catalog は output に列挙される各ファイルをルートからの相対で示します。
  • import は workspace_root を伏せ、下書きがそのルートに出力された場合は output_dir も伏せます。output_dir で指定したディレクトリは、ルートからの相対名で示されます。written と drafts 内の下書きのパスはすべて output_dir からの相対であるため、いずれの場合も下書きの出力先は応答に含まれます。診断の message、および判断の params_summary、rationale、swap_hint はインポーターが組み立てた文章であり、テキストの規則に従います。
  • config-show と plugin-list は、報告する内容の大半が場所を示す設定であるため、ルート以外にも多くを伏せます。詳細はリスナーがホストについて伝えないことで説明します。
  • 例を書き出す scaffold は、dir を送ったとおりにルートからの相対で示し、files 内の各パスをそのディレクトリからの相対で示します。下書きの作成と一覧表示は場所を示しません。
  • 公開ツール、sign-artifacts、deprecate-artifact、get-schema、explain-error、describe-capabilities は、それ自体としてはホスト上の場所を示しません。これらのいずれかの失敗メッセージはテキストの規則に従います。オフラインのワークスペースが発する拒否は、その .aggrega-config.yaml をルートからの相対で示します。
  • ワークスペース外に及ぶために拒否されたパス引数は、前述のとおり、ルートも到達先の場所も示さずに拒否されます。

呼び出しの終了

接続を閉じると、その接続が運んでいた呼び出しはキャンセルされます。 これがこのトランスポートのキャンセル信号です。サーバーは呼び出し元の切断をそのリクエストのキャンセルとして扱い、実行中の処理を終了し、そのリクエストに対してそれ以上何も書き込みません。ここではキャンセルメッセージは必要なく、想定もされていません。これは標準入出力とは逆です。標準入出力にはリクエストごとに閉じるストリームがないため、クライアントは id を指定して呼び出しを終了します。HTTP 経由で届いたキャンセルメッセージは受け付けられますが、何も終了しません。

プロセスを停止すると、リスナーはドレインされます。 割り込み、またはスーパーバイザーやコンテナランタイムからの終了要求によって、リスナーは受け付けを停止し、すでに応答中の呼び出しを一定の猶予内で完了させます。そのため、停止前に要求した呼び出し元は応答を受け取れます。猶予内に完了しなかった呼び出しは接続を失います。2 回目の停止要求でプロセスは即座に終了します。

Liveness と readiness(専用のアドレスで)

mcp.health.listen は、このプロセスが起動しているか、呼び出しに応答できるかをスーパーバイザーが問い合わせる場所です。 上記のいずれかの形式でアドレスを指定すると、2 つ目のリスナーがそこで GET /healthz と GET /readyz に応答します。省略した場合(これがデフォルトです)、2 つ目のリスナーは起動されず、どちらのチェックもどこでも応答されません。

2 つの応答は異なることを示しており、その違いこそが 2 つある理由です。 /healthz はプロセスが動作を始めた時点から 200 で応答されます。これが liveness の主張のすべてです。つまりプロセスは起動しており、まったく応答を得られないスーパーバイザーはプロセスを再起動すべきだということです。/readyz は、このプロセスが提供するワークスペースが解決され、エンドポイントがバインドされるまでは 503 で応答され、それ以降は 200 で応答されます。そのため、ロードバランサーはまだ起動中のプロセスに最初のリクエストを送るのではなく、プロセスが実際に呼び出しに応答できるようになるまでトラフィックを保留します。すべての応答は本文が空のステータスコードです。資格情報は求められず、呼び出し元が送ったものは何も読まれません。

エンドポイントはこの 2 つのパスに決して応答しません。 mcp.listen が指定するアドレス上の GET /healthz と GET /readyz は、トークンの有無にかかわらず、そのエンドポイントが提供しない他のすべてのパスとまったく同じく 404 で応答されます。そこでプローブに応答すると、エンドポイントに到達できるあらゆるものに、プロセスが起動しているかどうかを無償で読み取る手段と、プロセスに処理をさせる無償の手段を与えることになります。しかもそれは、本来なら資格情報を持たないすべてのリクエストを拒否するリスナー上でのことです。

ヘルスチェック用アドレスの置き場所は自由に選べ、mcp.listen のような制限はありません。 このアドレスに対して拒否されるアドレスはありません。ループバックまたは Unix ソケットを指定してください。それが本来の用途であり、同じホスト上でこのプロセスの隣で動作するスーパーバイザー、ロードバランサー、コンテナランタイムのためのものです。選んだアドレスに到達できるものは何でもこの 2 つの応答を読めるため、オープンなネットワークから到達できるアドレスは、それらをオープンなネットワークに公開することになります。

資格情報なしでは何も提供されない

エンドポイントへのすべてのリクエストは資格情報を伴い、それがどの種類になるかは、前段のプロキシがすでにそれを検査しているかどうかによります。 デフォルトでは、このサーバー自身が検証する bearer トークンであり、このセクションの残りで説明します。mcp.authorization.trusted_proxy を設定すると、代わりにそのプロキシが設定するヘッダーとなり、前段のプロキシから呼び出し元を読み取るで説明します。この場合、トークンは一切読まれません。どちらの形態でも、何も提示しないリクエストには何も提供されません。

デフォルトでは、サーバーは bearer トークンを自ら検査します。 Authorization ヘッダーからトークンを読み取り、次の条件をすべて満たす場合にのみ受け入れます。署名が認可サーバーの公開する鍵に対して検証されること、トークンが発行者として mcp.authorization.issuer を示していること、オーディエンスにこのデプロイメント自身の mcp.authorization.resource を含んでいること、有効期間内であること、そして提示した者が誰かを示していること。いずれかを満たさないトークンには 401 で応答し、何も持たない呼び出し元が受け取るのと同じチャレンジに error="invalid_token" が追加されます。どのチェックで拒否されたかにかかわらず応答は同一であるため、呼び出し元にわかるのは別のトークンが必要だということだけで、送ったトークンのどの部分が誤っていたかはわかりません。受け入れられるのは非対称署名アルゴリズムのみです。署名のないトークンと対称アルゴリズムを示すトークンは、何かが読み取られる前に拒否されます。

トークンは自身の種類を示すことができ、受け入れられる形式は 4 つです。 JWT は自身の種類を示す typ ヘッダーを持つことができます。このサーバーが受け入れるのは、アクセストークン用に登録された 2 つの表記である at+jwt と application/at+jwt、トークンが JWT であることだけを示す JWT、そして種類をまったく宣言しないトークンです。それ以外は、他の拒否されるトークンとまったく同じく 401 で応答されます。この集合は固定されており、広げたり狭めたりする設定はありません。そこにどの形式が現れるかは、トークンを受け取るデプロイメントではなく、トークンを発行した認可サーバーが決めるからです。JWT を受け入れると、宣言された種類だけではアクセストークンと ID トークンを区別できなくなります。両者を区別するのはオーディエンスのチェックであり、それがこのチェックが要となる理由です。ID トークンのオーディエンスは発行先のクライアントであり、このデプロイメント自身の mcp.authorization.resource になることは決してないため、このデプロイメント以外に向けて発行されたトークンは、自身を何と称していても拒否されます。

これにより受け入れられる認可サーバー。 Microsoft Entra ID は種類 JWT のアクセストークンを発行します。Keycloak は at+jwt を発行し、OpenID Connect 互換モードが有効な場合は JWT を発行します。Auth0 は独自のトークンプロファイルでは JWT を、RFC 9068 プロファイルでは at+jwt を発行します。これらいずれのトークンも、2 つの形式のどちらを持っていてもこのチェックを満たします。Okta はサポートされていません。Okta のアクセストークンは上記 4 つのいずれでもない独自の種類を宣言するため、このサーバーはそれを拒否します。

拒否されたトークンの理由はサーバー自身のエラーストリームに残ります。 呼び出し元には提示したものが受け入れられなかったことだけが伝えられ、サーバープロセスはトークンを拒否したチェック(オーディエンス、発行者、有効期間、署名、鍵識別子、宣言された種類、その他それぞれ)を示す 1 行を書き込みます。この行があることで、すべてのリクエストを拒否しているデプロイメントを、呼び出している側だけでなく運用している側が診断できます。この行にはトークンのどの部分も含まれません。資格情報をまったく提示しないリクエストは行を書き込みません。チャレンジを受けることは、クライアントがそもそもトークンの取得先を知る方法であり、行儀のよいクライアントが最初に必ず行うことだからです。

トークンはヘッダーにのみ置くものです。 access_token クエリパラメーターとして送られたトークンには 400 で応答し、決して読み取りません。アドレスは、リクエストが通過するすべてのプロキシログ、ブラウザー履歴、referrer ヘッダーに記録されるため、その方法で届いたトークンはすでに漏洩しているからです。サーバーはトークンをログに書き込まず、どこにも送らず、呼び出し元に代わってトークンを取得したり交換したりすることもありません。提示されたものを読み、判断し、何も保持しません。トークンが示すサブジェクトは記録されますが、何とも比較されません。

検証鍵は認可サーバー、または指定したファイルから取得します。 mcp.authorization.jwks_file が未設定の場合、サーバーは認可サーバーのメタデータを well-known アドレスで読み取り、そこで公開されている jwks_uri をたどり、見つかった鍵を保持します。それらの鍵に含まれない鍵識別子で署名されたトークンは再読み込みを 1 回促しますが、短い間隔内では 1 回までです。そのため、架空の鍵識別子を送る呼び出し元が、リクエストごとに外向きのリクエストを発生させることはできません。認可サーバーから鍵を読み取るには https の鍵アドレスが必要です。このマシン上であれば平文の http でもかまいません。別のホスト上の平文 http の jwks_uri には問い合わせず、どちらの読み取りであれ別のホスト上の平文 http へ送るリダイレクトには従いません。鍵への保護されていない経路上にいる者が、自分の鍵で応答できてしまうからです。その場合、それらの鍵を必要とするトークンには、鍵を読み取れない場合とまったく同じく 503 で応答し、そのリクエストについてサーバーが書き込む行は、認可サーバーに到達できなかったのではなく、平文 http のために読み取りが拒否されたことを示します。修正は認可サーバー側で行う必要があり、メタデータと鍵を https で公開しなければなりません。jwks_file が設定されている場合、鍵はそのファイルから読み取られ、認可サーバーには一切接続しません。これは offline: true を宣言するワークスペースに必要なものであり、そのようなワークスペースは、ファイルが指定されていない限り、リスナーがバインドする前に拒否されます。鍵をまったく読み取れない場合、リクエストにはチャレンジなしで 503 で応答します。呼び出し元が提示したものに不備が見つかったわけではないため、別のトークンを取得して送っても解決しないからです。

資格情報を求めずに返される唯一の応答は、保護リソースのメタデータドキュメントです。 クライアントはトークンを保持する前にこれを読む必要があるため、ここで資格情報を要求すると唯一の入口を閉ざすことになります。このドキュメントは /.well-known/oauth-protected-resource で応答され、さらに mcp.authorization.resource が指定するアドレスが独自のパスを持つ場合は、その well-known パスにそのパスを付加した場所でも応答されます。この 2 つがクライアントの参照する場所であり、付加した形式がチャレンジの示すアドレスです。ドキュメントには、このデプロイメントの呼び名となるリソースとしてそのアドレス、トークンの取得先となる認可サーバーとして mcp.authorization.issuer、トークンを提示する唯一の方法として header、そして以下の 3 つのスコープ名が含まれます。

発行者は、認可サーバーがこのマシン上で動作する場合を除き、https のアドレスです。 平文の http は、localhost、127.0.0.1、::1 の発行者に対しては受け入れられます。これはローカルの認可サーバーを使ったローカルテストの形態です。それ以外のホスト上の平文 http の発行者は、リスナーがバインドする前に拒否され、その拒否は mcp.authorization.issuer を示して https のアドレスを求めます。これは発行者から鍵を読み取る場合、mcp.authorization.jwks_file を使う場合、前段にプロキシがある場合のすべてのモードで成り立ちます。どのモードでもこのドキュメントで発行者を公開するからです。これに従うクライアントはそのアドレスに対して認可フローを実行するため、平文 http では、このサーバーがそこから鍵を読み取るかどうかにかかわらず、認可コードと取得されるトークンが保護されないままネットワークを通過します。そこから鍵を読み取る場合は、その経路上にいる者が自分の鍵で応答することもでき、その鍵で署名されたすべてのトークンが受け入れられてしまいます。

このデプロイメントが公開するスコープ名は aggrega:read、aggrega:workspace-write、aggrega:registry-write です。 これらは認可サーバーに登録する名前であり、クライアントが認可サーバーに要求する名前です。拒否された呼び出し元が受け取るチャレンジは、最初に取得すべきものとして aggrega:read を示します。それぞれが何を許可するか、そして 2 つ目の境界、つまりこのデプロイメントが自らに設定する境界については、以下の呼び出し元が到達できるものを参照してください。

前段のプロキシから呼び出し元を読み取る

前段のプロキシがすでにトークンを検証している場合、mcp.authorization.trusted_proxy は、トークンを再度検査する代わりに、そのプロキシから呼び出し元を読み取るようこのサーバーに指示します。 principal_header(呼び出し元が誰かを示すためにプロキシが設定するヘッダー)を指定し、必要に応じて scopes_header(その呼び出し元のスコープをスペース区切りで持つ 2 つ目のヘッダー)を指定します。それぞれは X-Forwarded-User のような HTTP ヘッダー名で、スペースやコロンを含みません。それ以外の形の名前は設定の読み込み時にキーを示して拒否され、空の principal_header も同様です。このモードを無効にするにはブロックを省略してください。読み取られるのはこの 2 つのヘッダーのみで、転送アドレスのヘッダーやその他のヘッダーは関与しません。principal ヘッダーなしで届いたリクエストには 401 で応答し、このモードではトークンは一切読み取られません。このサーバーが本来なら拒否したはずのトークンを持つリクエストも、principal ヘッダーがあれば提供され、受け入れたはずのトークンを持つリクエストも、そのヘッダーがなければ拒否されます。

このモードはループバックまたは Unix ソケット上でのみ受け入れられ、それ以外の場所ではバインドする前にプロセスが拒否されます。 ヘッダーが信頼できるのは、プロキシ以外の何もそれを設定できない場合に限られます。ネットワークから到達できるアドレスでは何でもそれを設定できるため、そのようなアドレス上のこのモードのリスナーは、すべての呼び出し元に好きな名前を名乗らせてしまいます。拒否は競合する両方の設定を示すため、アドレスを移すかブロックを削除することで解除できます。

プロキシが主張するものをこのサーバーはそのまま信じます。それがこの取り決めです。 このモードでは、このサーバーは署名を一切検査せず、トークンのサブジェクトを何とも比較しないのとまったく同じく、主張された呼び出し元を何とも比較しません。プロキシが転送したものを検証したかどうか、そしてプロキシを経由せずにそのリスナーに到達できるものがないかどうかは、デプロイメント側が正しく整えるべきことです。上記の制限はそれらを正しく整えることを可能にするものであり、整えられていることを保証するものではありません。

mcp.authorization.trusted_proxy を設定しても、他の要件はなくなりません。 メタデータドキュメントは引き続き公開され、チャレンジも引き続きそれを示すため、issuer と resource は依然として必要です。プロキシの背後にいるクライアントも、プロキシが検査するトークンの取得先を知る必要があるからです。同じ理由で、発行者はこのマシン上で動作する場合を除き、依然として https のアドレスです。そのクライアントは発行者からトークンを取得するため、このサーバーが発行者から何も読み取らなくても、別のホスト上の平文 http の発行者は、他のすべてのモードとまったく同じく、このモードでもリスナーがバインドする前に拒否されます。

呼び出し元が到達できるもの

HTTP 経由で呼び出し元が到達できるものは 2 つの境界によって決まり、それらは異なる人によって設定されます。1 つ目は呼び出し元自身の資格情報であり、2 つ目はこのサーバーがそもそも何を持っているかです。どちらも、各操作が自身について行う宣言から、何かが実行される前に読み取られ、クライアントには異なる場所で伝わります。ツールリストはこのサーバーが持ち告知するものを示し、各呼び出しが受け取る応答は資格情報が許可するものを示します。

すべての操作は自身の効果がどこまで及ぶかを宣言し、その種類は 4 つあります(後になるほど広くなります)。

  • 何にも到達しない — 定義を読み取り、Release が固定するものを調べ、成果物をメモリ上でレンダリングして返します。何も残しません。何も書き込まれず、応答が生成物のすべてです。
  • ワークスペースに到達する — このプロセスが提供するワークスペース内に書き込みます。Release のロックファイル、成果物キャッシュ、生成されたエンティティ、編集されたドキュメントなどです。
  • レジストリに到達する — 公開、署名、またはすでに公開されたものへの取り下げマーカーの付与を行います。これが変更するのは、そのレジストリのすべての利用者が解決するものであり、すでに取得した者から何一つ取り戻すことはできません。
  • マシンに到達する — ホスト上のすべてのワークスペースが共有するものを変更します。コンパイル済みモジュールストア、すべてに共通の設定ファイル、資格情報ストアなどです。単一のプロジェクトが自身のキャッシュディレクトリに保持するキャッシュはこの種類ではなく、cache-status は一覧表示する各キャッシュがこれらのどの種類に当たるかを報告します。

種類は、それを提供するツールではなく操作の性質であり、操作が残すものを対象とします。サーフェスが返す応答をどこに置くかではありません。Release のレンダリングは応答として成果物を生成するため、何にも到達しません。その後に成果物を指定したディレクトリに保存するコマンドラインは、さらに到達しているのではなく、その応答を届けているのです。逆に解釈すると、内容を返すすべての操作が、たまたまそれを保存したサーフェスの種類を帯びることになり、種類はもはや操作の性質ではなくなってしまいます。同じ理由で、レジストリ参照によってエンティティを読み取る describe は何にも到達しません。応答を取得するためにそのレジストリに接続しますが、レジストリにもこのマシンにも何も残さないからです。どのレジストリに接続できるかは呼び出しが消費する資格情報で説明します。ただし、呼び出し自体が書き込みを求める場合、1 つの呼び出しが操作の種類より先まで到達することがあります。write を送ったビルドは、このサーバーが提供するワークスペースに成果物を保存するため、その呼び出しはワークスペースに到達します。先に依存関係を解決するビルドも同様です。

スコープは種類を許可し、各書き込みスコープは読み取りスコープを含意します。 aggrega:read は何にも到達しない操作を許可します。aggrega:workspace-write はワークスペースに到達する操作を許可し、読み取りスコープを含意します。aggrega:registry-write はレジストリに到達する操作を許可し、これも読み取りスコープを含意します。そのため、クライアントは必要な書き込みスコープを認可サーバーに要求すればよく、読み取りスコープを別途要求する必要はありません。

machine の種類を許可するスコープはなく、それを追加する設定もありません。 この種類の操作は、aggrega コマンドを別プロセスで実行するツールだけが持っており、HTTP 経由で到達するサーバーは、上記のHTTPS 経由でサーバーに到達するで述べた理由により、それらのツールを一切提供しません。これらはホスト上のターミナルで実行してください。

ツール一覧には、呼び出し元のクレデンシャルがどのスコープを持つかにかかわらず、このサーバーが持ち告知するすべてのツールが表示され、呼び出しがそのうちどれを実行できるかはクレデンシャルが決めます。 describe-capabilities は、それと同じ集合を索引化し定義します。クレデンシャルが許可しない呼び出しには、チャレンジに error="insufficient_scope" を付けた 403 が返され、それを許可する唯一のスコープが示されます。呼び出しが求めたものは何も実行されていません。この拒否は、プロトコルのステップアップが応答する対象です。ステップアップを実装するクライアントは、チャレンジが示すスコープのために再度サインインするよう求めます。一覧はクレデンシャルによって変わらないため、再度サインインしたクライアントはすでに正しいツールを把握しています。3 つのスコープのいずれも持たないクレデンシャルは、同じツール一覧を受け取りますが、describe-capabilities を含め、そのどのツールも呼び出せません。

ビルドは知っておくべきケースです。 ビルドはそれ自体では何も変更しないため aggrega:read だけで済みますが、書き込むビルドには aggrega:workspace-write が必要です。write を送られたビルドは成果物をワークスペースルートの dist/ に保存し、先に依存関係を解決するビルドはロックファイルを書き込みます。これは、呼び出しが auto_pull でそれを求めた場合も、ワークスペース自身の auto_pull 設定がそうした場合も同じです。このツールは、他のすべてのツールと同様に read スコープの呼び出し元にも一覧表示され、メモリ内にとどまるビルドは実際にその呼び出し元が利用できます。拒否され、aggrega:workspace-write が示されるのは、書き込む呼び出しです。

ステップアップしないクライアントにも write スコープを与えることはでき、それは認可サーバー側で決まります。 認可サーバーを運用する人が、write スコープをそのクライアントのデフォルトスコープ、つまりクライアントが求めたかどうかにかかわらず、そのクライアントに発行するすべてのトークンに含めるスコープにすると、最初のサインインで得たトークンがすでにそれを持つようになります。接続のたびに認可サーバーへ新たに自身を登録するクライアントは、毎回そこで新しいクライアントとなり、以前の登録で行った設定は引き継がれません。そのようなクライアントでは、効力を持つ設定は、認可サーバーが登録するすべてのクライアントに与えるデフォルトスコープです。その代償として、そのクライアントを通じたすべてのサインインが、手元の作業に必要かどうかにかかわらず書き込みの到達範囲を持つことになります。また、デフォルトが登録時に与えられるものである場合は、そのように登録されたすべてのクライアントもその到達範囲を持ちます。デフォルトにするのは、その作業に必要な write スコープだけにしてください。aggrega:workspace-write と aggrega:registry-write は異なる種類を許可し、どちらも他方を含みません。

mcp.deny_reach は、このサーバーを運用する人がサーバーから種類を取り除く場所であり、ツール一覧を短くする 2 つの設定のひとつです。 このサーバーが持たない種類(none、workspace、registry、machine)を列挙すると、そのいずれかに到達するすべてのツールは、呼び出し元のトークンが何を示していても、すべての呼び出し元のツール一覧と describe-capabilities から除かれ、それでも呼び出された場合はこの設定を示すエラーで拒否されます。これは呼び出し元ではなくサーバー自身の制限であるため、どのクレデンシャルでも解除できず、拒否にはチャレンジが付きません。読み取りだけを提供するサーバーは、ここに workspace、registry、machine を列挙し、そうすると 3 つのスコープすべてを持つトークンの呼び出し元に対しても公開できなくなります。デフォルトのとおりこれを省略すると、このサーバーはどの種類も取り除かず、呼び出しがどの種類に到達するかは呼び出し元自身のスコープで決まります。machine を指定することは受け付けられますが何も変わりません。その種類のものはそもそもここでは提供されないためです。4 つのいずれでもない値は、無視されるのではなく、設定の読み込み時に拒否されます。種類の綴りを誤った運用者は制限を求めたのであり、制限なしで黙ってサービスすることはその求めへの誤った応え方だからです。

mcp.announce_tools はツール一覧を短くするもうひとつの設定であり、この 2 つは同じ制限ではありません。 deny_reach は機能を取り除きます。そこで指定された種類の操作は、誰に対してもここでは一切提供されません。announce_tools は告知だけを取り除きます。これが除外するツールはこのサーバーがまだ持つ機能であり、これが応えるのは、クライアントが登録するツール数に設ける独自の上限です。両方が設定されている場合は取り除きが優先されるため、取り除かれた種類のツールは announce_tools がどう指定しても除かれたままで、呼び出し元が受ける拒否はその取り除きを示します。一覧を短くするものはいずれも呼び出し元のスコープを読みません。呼び出し元が持たないスコープは呼び出しを拒否しますが、一覧からツールを除くことはありません。残りはサーバーが告知するものを絞り込むで説明しています。

呼び出しが使用する資格情報

リスナー経由のキーレス署名は、呼び出しが運ぶ identity_token からのみ ID を取得し、それ以外からは取得しません。 呼び出しで送られるトークンは呼び出し元が保持する資格情報です。呼び出し元はそれを取得する必要があり、トークンは呼び出し元に結び付けられ、それによる署名は呼び出し元に帰属します。ID の取得元になり得るほかの場所はすべて、このプロセスを起動した者に属するため、このトランスポートでは解決処理に何も応答しない環境が渡されます。サーバーの環境にある AGGREGA_IDENTITY_TOKEN と SIGSTORE_ID_TOKEN は読み取られず、周囲の GitHub Actions OIDC エンドポイントにもアクセスしません。これらは推奨されないのではなく、到達できません。解決処理が見つけられるものは何もありません。identity_token を送らない呼び出しは拒否され、その拒否は送るべきものとして identity_token を示し、変数やエンドポイントは示しません。このマシンのキーボードの前にいない呼び出し元はここで何も export できないため、それらを示すことは、応答を変えられない準備を求めることになるからです。

このマシンに保持された署名鍵は、どちらの経路でも選択できません。 key_path は何かが解決される前に拒否され、ここで publish-entity、sign-artifacts、deprecate-artifact が公開する引数スキーマにも含まれないため、成功し得ない引数が呼び出し元に提示されることはありません。提供されるワークスペース自身の設定が指定する署名鍵にも到達しません。これは signing.key_path が、ワークスペース全体に設定されている場合も、1 つのレジストリに対して設定されている場合も、環境から与えられる場合も同様です。理由は両者に共通です。鍵のパスは資格情報ではなく、このサーバーが保持するシークレットの名前です。それを与える呼び出し元は何も証明せず、このアドレスに到達した者なら誰でも同じ名前を与えられ、その後の署名は呼び出し元ではなく運用者がアーティファクトを保証したことを示してしまいます。引数を閉じて設定を開いたままにすれば、一方の扉を閉じても、もう一方の扉から同じ部屋に入れることになります。そのため、鍵による署名はリスナー経由では到達できず、呼び出しで送られたトークンだけが署名します。

fulcio_url、rekor_url、timestamp_url は影響を受けず、両方のトランスポートで有効なままです。 これらはこのマシンが保持するものではなく接続先のサービスを指すため、鍵を選択できない呼び出し元でも、このデプロイメントが設定したエンドポイントに対して署名できます。

署名鍵を指定するワークスペース上で起動されたリスナーは、起動時に一度だけそのことを伝えます。 プロセスは自身のエラーストリームに 1 行を書き出し、その設定を示して、このリスナーに到達する呼び出し元はその鍵を使用できないことを伝えます。これにより運用者は、予期しない署名からではなく、自分が起動したプロセスからそれを知ることができます。鍵を指定しないワークスペースでは、伝えることが何もないため、このような行は出力されません。この行には設定名が含まれ、鍵そのものや、それが指すファイルに関する情報は含まれません。

標準入出力経由では、上記のいずれも適用されません。 その場合は環境が読み取られ、key_path はこのマシンに保持された鍵を選択します。このサーバーを起動したクライアントは呼び出し元自身のマシンで動作しており、そのプロセスが到達できるものは呼び出し元自身が使用してよいものだからです。

レジストリ参照によるエンティティの読み取りは、このホスト自身のログインで 1 つのレジストリに接続し、リスナー経由では提供されるワークスペースに設定されたレジストリのみに接続します。 name として oci:// 参照を送られた describe は、その座標に公開されたエンティティを読み取ります。これは aggrega inspect が行うのと同じ読み取りで、参照が示す 1 つのレジストリから、このホストがそのレジストリに対してすでに保持しているログインを使って行われます。呼び出しは資格情報を運ばず、describe も受け取りません。HTTP 経由では、レジストリは提供されるワークスペースに設定されたものである必要があります。つまり default_registry が示すホスト、または registries に列挙されたホストで、ポートを含めて完全一致で比較されます。それ以外のホストへの参照は、このマシン上のアドレスも含め、そのホストに接続する前に拒否され、拒否にはそのホストが示されます。そのため呼び出し元は、このサーバーを任意の宛先に向けることはできません。到達可能なまま残るものは意図的なものです。aggrega:read を持つ呼び出し元は、ワークスペースに設定されたレジストリ上で、このホストのログインが読み取れるものを読み取れます。これはこのホストの端末にいる人も読み取れるものです。標準入出力経由では、コマンドラインと同様に、任意のレジストリへの参照が読み取られます。カタログ名によるエンティティの記述は影響を受けません。

レジストリ呼び出しは、このプロセスを実行している OS ユーザーの資格情報ストアを使用します。これはこのホストの端末で同じ呼び出しを行う場合とまったく同じです。ワークスペースごとの資格情報ソースはなく、それを追加する設定もありません。そのため registry-list は、このマシン上のすべてのワークスペースで、ホストの資格情報の状態を同じように報告します。ワークスペースごとに異なるレジストリ資格情報を持たせたいデプロイメントでは、それらを異なる OS ユーザーとして実行します。ワークスペースごとに 1 つのプロセスを、それぞれ独自のユーザーとして起動します。分離はそこから生まれ、その準備は運用者が行います。

サーバーが記録するもの

このエンドポイントが応答するすべてのリクエストは、プロセスのエラーストリームに 1 行を残し、その行は単一の JSON オブジェクトです。 その行には、書き込まれた time、このプロセスが呼び出しのために発行し呼び出し元には返さない request_id、提示された資格情報が主張したとおりの subject と issuer(資格情報がクライアントを指定した場合は client_id も)、このプロセスが提供するワークスペースである workspace_root、method(メソッドが名前で何かを指定する場合は target も)、操作が宣言する種類である reach(呼び出しがそれより先に到達した場合は reach_escalated_to も)、outcome、duration_ms、そして transport が含まれます。記載する内容のないフィールドは空で書かれるのではなく省略されるため、client_id がない場合はクライアントを指定しなかった資格情報であり、reach_escalated_to がない場合は操作が宣言するとおりの範囲にのみ到達した呼び出しです。

outcome は呼び出しがどうなったかを示し、値はそれぞれ区別して数えられるように異なっています。 ok は実行されて成功したことを示します。tool-failure は実行されたものの、呼び出し元が修正できる失敗としてフラグ付きで返されたことを示します。これはサーバーが拒否したのではなく処理した呼び出しなので、拒否には含まれません。error はプロトコルのエラーエンベロープとして返された拒否です。unauthenticated、forbidden、rate-capped は、それぞれ資格情報、オリジンまたはスコープの制限、呼び出し元ごとのレート上限によってリクエストが退けられたことを示します。cancelled は、応答を受け取る前に呼び出し元が接続を閉じたことを示します。

拒否された資格情報が退けられた理由は、独立した行ではなく同じ行のフィールドとして記録されます。 拒否されたリクエストも他と同様に 1 件の記録を残し、refusal がそれを退けたチェックを示します。資格情報は、その一部であっても、どの行にも記録されません。拒否の場合も、処理された呼び出しの場合も同様です。

何も提示しなかった呼び出し元は行を残しません。 チャレンジを受けることは、クライアントがトークンの取得先を知る方法であり、行儀のよいクライアントが最初に必ず行うことです。そのたびに行を残すと、意味のある拒否が埋もれてしまいます。このエンドポイントが提供しないパスやメソッドを指定したリクエストも行を残しません。どちらも呼び出し元に関する情報を読む前に決着するため、アドレスをスキャンしてもストリームを収集する仕組みには何も書き込まれません。

クライアントが送信したトレースコンテキストは、そのまま行にコピーされます。 traceparent、および送信されている場合はそれと並ぶ tracestate と baggage が、受け取ったとおりに引き継がれるため、このストリームを収集する仕組みは呼び出し元自身の記録と結合できます。何も送信しないリクエスト、または正しい形式の W3C トレースコンテキストではないものを送信したリクエストでは、これらのキーを持たない行が生成されます。何かが作り出されることも、途中で変更されることもありません。

プロセスは自身のライフサイクルも同じ形式で同じストリームに記録します。それらの各行は、リクエストの行がメソッドと呼び出し元を示す代わりに event を示します。開始時の startup、バインドしたアドレスを伴う listening、提供開始前に起動が拒否された理由を伴う startup-refused、提供するワークスペースがこのリスナーに到達する呼び出し元には使えない署名鍵を指定している場合の signing-key-ignored、ドキュメントバンドルの取得結果を伴う docs-bundle、そして実行終了時の shutdown です。2 種類の行は event の有無で見分けます。

これらはすべてプロセスのエラーストリームから収集するものであり、配信手段はそれだけです。 設定するエクスポーターも、指定するファイルもなく、記録を有効化、無効化、あるいは別の場所に送る設定もありません。このプロセスを監視するもの(コンテナランタイム、サービスマネージャー、ログシッパーなど)がそのストリームを収集し、後から照会する場所となります。標準入出力では、同じストリームに代わりに読みやすい文章が流れます。それを読むクライアントがプロセスを起動し、同じマシン上にあるためです。

これらは呼び出し元には一切送信されません。 サーバーはどちらのトランスポートでもプロトコル上でログストリームを公開せず、プロトコルのリクエストごとのログレベルフィールドを含むリクエストにも、含まないリクエストとまったく同じように応答します。ここに記録されるものはオペレーターのものであり、オペレーターのストリームにのみ送られます。

接続時にサーバーがモデルに伝えること

サーバーはモデル向けのガイダンスのブロックを提供し、クライアントは最初の呼び出しの前にそれをモデルに提示できます。2026-07-28 のクライアントは server/discover の応答からそれを読み取り、2025-06-18 のクライアントは initialize ハンドシェイクへの応答からそれを読み取ります。どちらの経路でも同じテキストで、バイト単位で同一です。また、1 つのプロセスに接続するすべてのクライアントに対して同じテキストです。その中には交渉されるものはなく、クライアントが送信した内容や提示した資格情報から導かれるものもありません。そのため、接続時にモデルが伝えられる内容はセッション間でもクライアント間でも変わりません。

変わるものは 2 つあり、どちらもクライアントによるものではありません。 締めくくりの段落はプロセスが提供するトランスポートに合わせて構成されるため、標準入出力で通信するサーバーとリスナーとでは、モデルに渡す締めくくりのテキストが異なります。また、サーバーを起動したデスクトップバンドルが、起動した aggrega 実行ファイルとは異なるリリースのものである場合、ガイダンスはその旨を述べ、両方のバージョンを示す 1 文で始まります。これは、Which release the server comes from で説明しているとおり、引数なしの describe-capabilities の応答の冒頭にある文と同じです。バンドルによらない起動や、バンドルが実行ファイル自身のリリースのものである起動では、この文のないガイダンスが渡されます。どちらもプロセスの起動時に確定し、いずれのプロセス内でも、2 つのリビジョンはそのプロセス自身のテキストを同一に提供します。

このガイダンスは、ツールの引数スキーマだけでは伝えられないメンタルモデルを教えます。

  • コンパイラが行うこと、そして意図的に行わないこと:値の意味を解釈するのではなくテキストをルーティングしてラベルの一致を評価すること、ドキュメントに記述する内容について主張を持たないこと、そしてコンパイル中に provider で認証することも、クラスターの状態を読み取ることも、シークレットを平文に変換することも決してないこと。インフラストラクチャが稼働して初めて存在する値は、ターゲット環境が後で埋めるポインター文字列として受け渡されます。
  • オーサリングの語彙と、種類同士の関係:各種類が何のためにあり、実際にビルドの対象となるのはどれか。これにより、アシスタントはツール一覧からデプロイメントの形を推測する必要がなくなります。
  • オーサリングループの実行順序:コントラクトを読み、それをもとに雛形を作成し、接続先を調べ、レンダリングの前にチェックします。
  • ツールではなくプロンプトを使うべきとき:操作にはツール、タスクの枠組みにはプロンプトを使います。
  • ツール一覧がサーフェスのすべてであること:このサーバーが提供するツールはすべてその一覧にあり、サーバーがどのツールを提供するかはその設定方法によって決まります。そのため、アシスタントは別の一覧を探しに行くのではなく、その一覧と describe-capabilities から何があるかを読み取ります。接続が資格情報を提示した場合は、その資格情報が決めるのは呼び出しがどのツールを実行できるかであり、どのツールが一覧に表示されるかでは決してないことを伝えます。資格情報が許可しない呼び出しは、それを許可するスコープを示して拒否され、クライアントはそのスコープのために再度サインインできます。
  • 空のワークスペースが何を意味し、それに対してモデルが何をしてよいか:トランスポートによって異なる段落で、以下で説明します。

ガイダンスはサーフェスを再記述するのではなく、名前を挙げます。 各ツールは tools/list に独自の説明と引数スキーマをすでに持っており、各種類のコントラクトはそのスキーマとリファレンスページにすでに記載されています。そのため、ガイダンスはそれらを指し示すだけにとどめます。1 つの記述につき 1 つの置き場所です。ガイダンスが名前を挙げるツールはサーバーが提供するツールであり、読み取りサーフェスが解決するすべてのリソースファミリーを指し示すため、アシスタントを案内した先が行き止まりになることはありません。

ガイダンスにはツール自体の索引は含まれていませんが、これは同じ原則によるものであり、その原則からの抜け落ちではありません。クライアントはこのテキストを読む前に tools/list からすべてのツールの定義を受け取っているため、ここにツールごとの行を置けば、すでに持っている目的の 2 つ目のコピーになります。それはすべてのセッションで、すべてのクライアントが負担するものであり、どちらかが編集された時点でツール一覧と食い違う可能性があります。

また、ガイダンスは何を列挙しないか、そしてその理由も述べます。利用可能なレンダーターゲットとインストールされているライブラリの種類はプラグインとスキーマセットの性質であるため、ガイダンスが食い違う可能性のあるコピーを持つのではなく、リソースサーフェスがそれらを直接報告します。

空のワークスペースについてモデルに伝えられること

締めくくりの段落は、何も含まないワークスペースでモデルが最初に直面する問い、つまり空の list-entities が何を意味し、それに対して何をしてよいかに答えます。その冒頭は両方のトランスポートで同じです。空の一覧は、このプロセスが解決したワークスペースに読み取れる Aggrega ドキュメントがなく、その横に設定されたカタログディレクトリも何も宣言していないことを意味します。その後に続く内容は、このプロセスがどちらのトランスポートを提供するかによって異なります。正直な答えが 2 つで同じではないからです。

標準入出力では、ワークスペースはモデルが調べて修復してよいものだと伝えられます。 ワークスペースを指定しない呼び出しがどこで応答されるかが伝えられます。サーバーがフォルダーを指定して起動された場合はそのフォルダー、そうでない場合は起動時のフォルダーから見つかったワークスペース(そのフォルダー自体である場合もあります)です。また、呼び出しの workspace_root で別のワークスペースを指定できることも伝えられます。有効な設定と、各設定をどのレイヤーが決定したかについては config-show を、動作する設定の初期作成については cli-config-init を案内されます。どちらもこのトランスポートではツール一覧にあります。サーバーを実行するクライアントは呼び出し元自身のマシン上にあるため、そのプロセスが到達できるものは呼び出し元自身が使ってよいものです。境界を設定する場所は他のすべてのツールと同じく MCP クライアントであり、What an assistant can do without asking you first で説明しています。

HTTP では、モデルは設定するのではなく報告するよう伝えられます。 ワークスペースはプロセスを起動したときのもので、プロセスの存続期間中は固定されます。workspace_root または catalog_dirs を指定する呼び出しは、その引数を示して拒否されます。また、資格情報がどのスコープを持っていても、ここでは設定を書き込むツールはどの呼び出し元にも提供されません。そうした操作を担うのは、別プロセスで aggrega コマンドを実行するツールだけであり、HTTP 経由のセッションはそれらを含まずに構成されます。したがって、境界はスコープではなく構成によるものであり、どのトークンもそれを広げることはできません。そのため、リスナー経由でデプロイメントに接続するモデルは、ホスト上でレジストリを初期作成したり信頼ポリシーを書き換えたりできず、この段落は、試させて拒否を読ませるのではなく、そのことをモデルに伝えます。

アシスタントが事前に確認せずに実行できること

標準入出力でこのサーバーに接続したアシスタントは、クライアントで拒否するよう設定していない限り、確認を求めることなくサーバーが公開するすべてのツールを呼び出せます。 このトランスポートでは、サーバーはツールを提供するだけで、個々の呼び出しがどのツールを使ってよいかは判断しません。その判断はクライアントが行うものであり、そこで決めるのは利用者自身です。HTTP では事情が異なります。サーバーは保持し告知するすべてのツールを一覧に載せ、呼び出し元トークンのスコープが許可しない呼び出しを拒否するため、境界はクライアントだけでなくサーバーにもあります。

これが重要なのは、ツールの表面がコマンドラインそのものだからです。入力できることはすべて、アシスタントも呼び出せます。マシンを変更する操作も含まれます。

これらの操作の一部は作業中のワークスペースを越えて影響を及ぼし、別の何かを実行しても元に戻せません。 名前を把握しておくべきものを、影響範囲の広い順に挙げます。

  • publish-entity、publish-artifact、sign-artifacts、deprecate-artifact は、マシンの外にまで完全に影響を及ぼします。 これらはバイト列、署名、または取り下げマーカーをレジストリに置くため、変更されるのはそのレジストリのすべての利用者が解決する内容であり、このマシンが解決する内容だけではありません。タグに異なる内容を再公開することは受け付けられず拒否されるため、ここには公開を取り消す手段はありません。対処法は新しいバージョンを公開することです。署名と取り下げマーカーはアーティファクトのバイト列には手を加えませんが、その後にそのアーティファクトを取得する人は誰でもそれらも取得し、すでに取得した人から回収することはどちらもできません。標準入出力では、同じ 4 つの機能はコマンドを実行する cli-push、cli-push-artifact、cli-sign、cli-deprecate としても利用できます。HTTP ではこれら 4 つのツールは存在しません。
  • 署名には資格情報が使われます。 標準入出力では、キーレス署名は呼び出しの identity_token 引数、サーバー環境の AGGREGA_IDENTITY_TOKEN または SIGSTORE_ID_TOKEN、あるいは到達可能な場合は周囲の GitHub Actions OIDC エンドポイントから ID トークンを取得します。key_path を指定すると、代わりにオフラインで保持された鍵が選択されます。したがって、これらのツールを呼び出せるアシスタントは、サーバーを実行しているマシンがすでに持っている ID で利用者として署名できます。署名はアーティファクトを誰が保証するかを示す表明であり、そのため許可する前に最も慎重に検討すべき操作です。リスナー経由では、呼び出しで送られたトークンだけが署名に使われます。サーバー環境は一切読み取られず、ホストに保持された鍵を引数や提供中のワークスペースの設定で選択することもできません。詳しくは 呼び出しが使用する資格情報 を参照してください。
  • aggrega cache evict はコンパイル済みモジュールのストアを削減し、aggrega cache clear はそれを消去します。このストアはマシン上のすべての Aggrega プロジェクトで共有されています。ストアから削除されたモジュールは必要に応じて再コンパイルされるため、永久に失われるものはありませんが、どのプロジェクトでも次のビルドでそのコストがかかります。aggrega cache clear はマシン上のすべてのプロジェクトが読み取るドキュメントバンドルも削除し、これはいずれかのプロジェクトが次に取得する際に再度フェッチされます。
  • aggrega cache prune は、どのロックファイルからも参照されていないアーティファクトキャッシュのエントリを回収します。プロジェクトのロックファイルが読み取れる場所にない場合、そのピン留めされたアーティファクトはロックファイルによって保護されず、回収すると再度フェッチすることになります。
  • aggrega registry add と aggrega registry remove は、デフォルトではすべてのワークスペースで共有される設定に書き込むため、ここだけでなくマシン上のあらゆる場所で解決される内容を変更します。aggrega registry add は、ターミナルで実行した場合とまったく同じく、指定したレジストリにそのレジストリが公開する信頼ポリシーを問い合わせ、受け取った内容をピン留めします。オフラインのワークスペースでは、そのフェッチは接続を試みる前に拒否されるため、呼び出しが identity または key を指定しない限り、公式ハブ以外のレジストリの追加は拒否されます(ショートコード E0310、同じ文言)。どちらも受け取らない aggrega config init は、オフラインではハブしか初期設定できません。標準入出力では、これらはコマンドを実行する cli-registry-add と cli-registry-remove として、初期設定は cli-config-init として利用できます。HTTP ではこれらのツールは存在しません。
  • pull はレジストリから読み取り、指定されたワークスペース内に書き込みます。 その Release のロックファイルを書き込み、解決した内容でアーティファクトキャッシュを満たし、ワークスペースが付加する判定を返す各プラグインの ID をロックファイルの横に記録します。pin_sources を送った場合、または pin_sources_at_pull が有効なワークスペースで呼び出しがそれを false として送らない場合は、Release がカタログディレクトリからビルドする Recipes と FeatureRecipes に対してエンティティ作成者のピン留め手順も実行し、それぞれの横に entity.lock を書き込みます。これがない場合、読み取る入力のピンをロックが記録していないエンティティに対する pull は、その手順を示して拒否されます。エンティティファイル自体が書き込まれることはありません。いずれもマシンの外には出ず、記録された内容を変えるには再度解決すればよいため、ここで挙げる書き込み操作の中では最も穏やかなものです。これは、ワークスペース内に書き込む、作成ループ向けのツールの一つです。pin は指定した Recipe または FeatureRecipe の横に entity.lock を書き込みます(エンティティ自身の入力のピン留め を参照)。gen-catalog は生成した Plugin エンティティを指定したディレクトリの下に書き込みます。edit-document は既存のドキュメントに範囲を限定した構造化編集を 1 つ適用して書き戻し、編集が触れないバイトはすべて保持します(ドキュメントへの範囲を限定した編集の適用 を参照)。import は別のツールが生成した記述を作成用のドラフトファイルに変換し、ワークスペースに書き込みます(外部の記述からドラフトエンティティへの変換 を参照)。example を送った scaffold は、aggrega scaffold --example と同様に、ドキュメントの実行可能な例の 1 つを新しいディレクトリまたは空のディレクトリ dir に書き出します。HTTP では workspace-write スコープがこれを許可します。その出力ディレクトリ、gen-catalog が読み取るゲスト、および指定したオーバーレイは、いずれもワークスペースルートからの相対パス、または標準入出力では絶対パスであり、この表面の他のすべてのパス引数と同じ取り決めに従います。標準入出力では、同じ機能はコマンドを実行する cli-pull としても利用できます。HTTP ではこのツールは存在しません。
  • build は、auto_pull を送った場合に限り、同じレジストリを読み取り同じ書き込みを行います。 Release の依存関係の解決はどこで要求されても一つの操作であるため、先に解決するよう指示されたビルドは pull とまったく同じことを行い、その後書き込んだ内容に対してレンダリングします。そのため、より小さい範囲ではなく同じ影響範囲を持ちます。write を送ると、レンダリングされたアーティファクトもワークスペースルートの dist/ に書き込みます。 これは aggrega build が書き込む場所であり、同じ書き込み処理を通るため、その呼び出しではワークスペースに影響が及びます。それ以外の場所には書き込まず、ワークスペースの外を指すリンクである dist は、その中の何かが削除または書き込まれる前に拒否されます。どちらの引数もない場合(これがデフォルトです)、build はワークスペースがすでに保持しているピンからレンダリングし、何にも影響を及ぼしません。引数が何を変え、何を変えないかについては Release がすでにピン留めしている内容に対するビルド を参照してください。

インベントリ系のツールは、そのことを自身の回答の中で示します。cache-status は各キャッシュクラスにその到達範囲を示します。このプロジェクト自身のキャッシュディレクトリ配下にあるアーティファクトキャッシュには workspace、すべてのプロジェクトが共有するストアには machine を付け、マシン全体に及ぶものは明示的に名前を挙げます。そのため、回収を提案する前にインベントリを読むアシスタントは、そのうちどの部分がこのプロジェクトだけのものではないかを知ることができます。メンテナンス操作も、削除した要素ごとに同じ到達範囲を報告します。4 つの公開系の結果はそれぞれ独自の reach を持ち、その中に registries と beyond_this_machine を保持します。前者は呼び出しが宛先としたすべてのレジストリホストを、それぞれ 1 回ずつ、最初に宛先とした順に並べたものです。後者は呼び出しが要求した内容ではなく、実際に付与した内容から読み取られます。コンテンツをアップロードした時点、または署名、公開日、非推奨マーカーのいずれかを付与した時点で true になり、ドライランの場合や、すべてがすでに存在していた呼び出しの場合は false になります。後者の例としては、完全なバージョンに対して再度実行した公開や、参照がすべてすでに署名済みだった署名バッチがあります。

境界を設定する場所。 プロトコル自体はツールごとの権限を定義していません。その認証は、クライアントがそもそも接続できるかどうかに関するものであり、接続後にどのツールを呼び出せるかに関するものではありません。権限の判断は MCP クライアント側にあります。広く使われているクライアントでは、一般に単一のサーバーが提供する個々のツールを名前で許可・拒否でき、特定のプロジェクトに対してサーバー全体を無効にすることもできます。設定の名前と場所はクライアントごとに異なるため、ツールの権限についてはお使いのクライアント自身のドキュメントを参照してください。読み取りは許可し書き込みは許可したくない場合は、そこで必要なツールを許可し、残りを拒否します。許容的な設定や、そのような設定を持たないクライアントでは、公開されているすべてのツールが呼び出し可能なままになります。

ワークスペースの内容を調べる

ほとんどのツールは対象を受け取ります。対象とはエンティティ名、または Release のパスです。以下の 2 つは対象を受け取らず、接続したばかりのアシスタントはこれらを使って対象を得ます。

list-entities はワークスペースに何があるかに答え、list-releases はサーフェスの他の部分が繰り返し問う、より狭い問い、すなわちどの Releases があるかに答えます。どちらも対象を受け取りません。ワークスペースが何を含むかはワークスペース自体の性質であり、呼び出し側が先に知っておくべき何かの性質ではないためです。

どちらも 2 つの形のいずれかで答え、形を指定しない呼び出しには要約が返ります。 この既定はこの 2 つだけのものであり、build、describe、validate の既定とは逆です。これらは呼び出し側がすでに指定した対象について問われるため、詳しい回答が求められたものであり、簡潔な回答はオプトインです。一方この 2 つは、まだ指定できるものを持たず、回答が届く前にそのコストを知る手段もない呼び出し側から、何があるかを問われます。そのため、まずワークスペースの規模と構成を報告し、求められて初めてレコードを渡します。

要約は、何がどれだけあるかを示します。 list-entities はワークスペースルート(回答がサーバーのファイルシステムについて示す内容で説明するとおり、HTTP では伏せられます)、エンティティの総数、種類ごとの件数を報告します。list-releases は総数とトップレベルディレクトリごとの件数を報告するため、Releases がいくつあり、ツリーのどの部分にあるかがわかります。どちらの内訳もドキュメント自体から読み取られるため、誰も想定しなかった配置のワークスペースも、そうでないワークスペースと同じく正確に要約されます。どちらも種類ごと、またはトップレベルディレクトリごとに 1 行を持つため、その大きさはワークスペースが保持するドキュメント数ではなく、宣言する種類の数と Releases が置かれたディレクトリの数に従います。種類を変えずにドキュメントを 100 倍にしても、要約は大きくなった数値を書くための数バイトしか増えません。要約が長くなるのは、宣言する種類を増やしたときです。どちらもレコードの最初のページではなく、その違いこそが要点です。「エンティティの一部はこちらです」と「ワークスペースはこれで構成されています」は別の回答であり、レコードがそもそも必要か、必要ならどれかを教えてくれるのは後者だけです。

レコードを得るには response_format: detailed を送ります。レコードは 1 ページずつ届きます。 このとき list-entities は、各エンティティの種類、名前、apiVersion、説明、ラベル、ソースファイルを、それを宣言するドキュメントから直接読み取って報告します。設定されたカタログディレクトリが宣言する Features も報告するため、アタッチ可能として提示された Feature は検索することもできます。これらにはソースファイルがありません。持ちうるパスはサーバーが動作するマシン上のものだけだからです。また、それぞれ出所を示すため、空のファイルは値の欠落ではなく「カタログから解決された」と読めます。list-releases は各 Release のパスを報告し、lockfiles は返した各パスを、その Release のロックファイルのパスへ同じ座標で対応付けます。これは pull が書き込み、build が読み込むファイルであり、言語サーバーの Release に関する回答が示すファイルと同じです。この対応表はこの回答が持つパスを記述するためページに従い、要約では空になります。

response_format が取る値は detailed と concise だけであり、厳密に照合されます。 それ以外の表記(別の単語、大文字小文字の違い、前後の空白)は拒否され、拒否では送られた値と、引数が受け付ける値が示されます。既定を求めるには response_format を省略します。この 2 つのツールでは既定は要約です。この引数が現れる場所ではどこでも同じです。build、describe、validate も同じ条件で同じ 2 つの値を受け取り、その既定は簡潔な形ではなく詳しい形です。

レコードは、上限を指定してもしなくても制限されます。 limit は 1 回の回答が持つ件数で、1 から 500 の間、既定は 50 です。そのため、レコードを求めてページサイズを指定しない呼び出しも制限され、どちらのツールのどの呼び出しも、ワークスペース自体の規模で決まる回答を返すことはありません。offset は一覧のどこから始めるかで、0 から数えます。どちらもレコードを制限するものなので、レコードを持たない要約には影響しません。範囲外の limit は拒否され、その境界が示されます。一覧の末尾を越える offset は空で返ります。問いに誤りがあるのではなく、そこに何もないためです。

一覧を続けるには、回答から 3 つのフィールドを読み取ります。 count はワークスペースが持つレコード数、offset と returned はこの回答がどこから始まり何件持つか、more_remaining は残りがあるかを示します。more_remaining が true の間は、offset に returned を加えた値で再度呼び出します。このシグナルは回答に書き込まれるのではなく、ページと総数から計算されるため、レコードが残っているのに何も残っていないと報告することはありません。

これらが重要なのは、名前を受け取るツールが、解決できない名前に対して空の結果で答えるのではなく拒否するためです。この拒否は意図的なものです。空の回答では、打ち間違えた名前が、提供するものが何もない対象として報告されてしまいます。しかしその結果、名前を持たない呼び出し側は推測で名前を得ることができません。名前を得る方法は列挙です。

この 2 つは互いに、またサーフェスの他の部分とも組み合わせられます。

  • list-entities を呼び出して要約を得て、ワークスペースにどの種類がそれぞれいくつあるかを確認し、次に response_format: detailed を付けて再度呼び出してレコードを得ます。結果から名前を取り出して describe に渡すと、そのエンティティの完全に解決された定義を確認できます。これは言語サーバーの aggrega/entityDefinition が返す定義を JSON で表したものです。各キーは作成者が書く名前で、定義が保持する順序で並び、スキーマは作成者が書いたスキーマのまま示され、エンティティが宣言しないスキーマは省かれます。たとえば Component のソケットは、それぞれ接続が埋めうるスロットとともに示されます。
  • list-releases でも同様にし、詳しい結果からパスを取り出して、作業対象の Release として describe または build に渡します。
  • list-releases が返すパスはワークスペースルートからの相対パスで、list-entities がファイルを報告する座標と同じです。そのため 2 つの回答はファイル上で一致し、合わせて読むことができます。lockfiles にあるそのロックファイルも同じルートからの相対パスなので、場所を割り出さずにそのファイルを読んだり比較したりできます。

どちらも、何を数えるかをファイル名ではなく各ドキュメント自身の kind を読んで決めます。慣例的な接頭辞なしで名付けられた Release は一覧に含まれます。単に Release のように名付けられただけのファイルは含まれず、実際に宣言している kind の下に現れます。kind をまったく宣言しない YAML(チャートの values ファイルや、たまたまツリー内にある設定ファイルなど)はエンティティではなく報告されません。レンダリングされた Kubernetes マニフェストのような、別のプロジェクトに属するドキュメントも同様です。ドキュメントがエンティティとして数えられるのは、kind と名前の両方を宣言し(この 2 つが揃うことで後からアドレス指定できるようになるためです)、かつ Aggrega 自身のグループ以外の apiVersion を宣言していない場合です。apiVersion をまったく宣言しないドキュメントは、別プロジェクトのファイルではなくフィールドが欠けた Aggrega ドキュメントであるため報告されます。list-releases はワークスペースルートの外のディレクトリを検索しないため、エディタ上でルート外へのリンクの下に表示される Release は一覧に含まれません。unread_linked_dirs は、一覧がディレクトリを読むはずの位置にありルートの外へ通じる各リンクを、リンク先ではなくルートからの相対パスで示したリンク自身のパスによって挙げます。これは両方の形式、両方のトランスポートで行われ、該当がなければ空です。また、リンクを通じてルート外のファイルを読むこともありません。unread_linked_files は、自身の名前が .yaml または .yml で終わりルート外のファイルへ通じる各リンクを、そのファイルの内容にかかわらず同じ方法で挙げるため、そうしたリンク経由でしか到達できない Release は一覧に含まれません。ただし、ワークスペース設定がその Release を build.authoring_release として、または workspace.releases のキーとして指定している場合は例外で、リンク自身の位置で読まれて一覧に含まれ、リンクとしては挙げられません。list-entities もワークスペースの外へ通じるリンクの先のドキュメントを読みません。ルート外のディレクトリを検索せず、ルート外のファイルも宣言内容にかかわらず読まず、そうしたリンクをそれぞれ自身の unread_linked_dirs と unread_linked_files に同じ方法で、両方の形式、両方のトランスポートで挙げます。これはドキュメントが何を宣言していても成り立ちますが、list-releases と同じ例外が 1 つあります。ワークスペース設定が build.authoring_release として、または workspace.releases のキーとして指定する Release は、リンク自身の位置で読まれて一覧に含まれ、リンクとしては挙げられません。一方、これらの設定が指定するファイルが Release 以外を宣言している場合、一覧には含まれず、そのリンクが挙げられます。設定されたカタログディレクトリは、ワークスペースが別の場所に置かれた他のエンティティを読むための手段であるため、設定が catalog_dirs に挙げるディレクトリ、またはその配下のディレクトリへのリンクは、どちらの一覧でも挙げられません。設定がそこに到達しているからです。list-entities がカタログディレクトリから取得する Features には、カタログディレクトリの読み取りがとどまるべきディレクトリ(ワークスペース内のカタログディレクトリならワークスペース、設定がワークスペース外に指定するものならそのディレクトリ自体)の外へ通じるリンクの先にあるものは決して含まれません。そのため、読まれなかったリンクの先にあるとして名前が挙げられたエンティティが、その名前と並んで一覧に含まれることはありません。名前、位置、または .gitignore によって一覧から除外されるリンクは挙げられません。また release を指定した場合、他の Releases だけが読むカタログディレクトリの下にあるリンクも挙げられません。それ自体がワークスペースの外へ通じるリンクである .gitignore は読まれません。これらのリストのいずれかがリンクを挙げる場合、テキストの回答はその旨を述べる独立した行で締めくくられます。

設定ファイルが外へ通じているワークスペースも一覧は返されますが、それ以外には何も回答されません。 ワークスペース自身の .aggrega-config.yaml、またはその隣にある CI 所有のオーバーレイが、ワークスペースの外へ通じるリンクである場合、ターミナルと同様にその設定は読まれず、それが設定するはずだったものも代わりに読まれることはありません。サーバーは標準入出力上で引き続き起動し、その旨をエラーストリームに 1 行で出力します。list-entities と list-releases は、何も設定されていない状態で読んだワークスペース自身のドキュメントで回答するため、カタログディレクトリの Features は一覧に含まれません。どちらも、一覧がそのファイルに出会ったかどうかにかかわらず、保留されたファイルを unread_linked_files とテキストを締めくくる行に挙げます。その名前によって、ワークスペースの設定が外へ通じていることがわかります。release または catalog_dirs を送った一覧の要求、およびそのワークスペースを指定する他のすべてのツールは、読まれなかった設定によって決まるため、それぞれ E0321 で拒否され、リンクとそのリンク先が示されます。コマンドラインで待ち受けを指示されたサーバー(--transport http または --listen)は、そのようなワークスペースでは起動しません。バインドするアドレス、証明書、呼び出しを許可する相手は、その設定が決めるものだからです。リンクを削除するか、ワークスペース内のファイルへ通じるようにすれば、次の呼び出しで設定が読まれます。ワークスペースの境界を参照してください。

1 つの Release の観点で問い合わせる

ワークスペースは各 Release に独自のカタログディレクトリを与えることができ(Release に独自のカタログディレクトリを与えるを参照)、これにより 1 つのエンティティのバリアントを Release ごとに並べて保持できます。通常はワークスペース自身のカタログディレクトリを対象に応答する 3 つのツールは、省略可能な release(Release ファイルのパス)を受け取り、その場合はその Release の観点で応答します。

  • release を指定した list-entities は、その Release から見えるエンティティを一覧にします。一覧に含まれる Features はその Release のカタログディレクトリが宣言するものであり、他の Releases だけが読むカタログディレクトリ配下のワークスペースドキュメントは除外されます。そのため、各バリアントはそれを使ってビルドする Release に対してのみ一覧に含まれます。どのカタログディレクトリ配下にもないドキュメント(カタログの横に書かれた Release、その Aggregate、その Manifest など)は、すべての Release に対して一覧に含まれます。
  • name と release を指定した describe は、その Release のカタログディレクトリを通して名前を解決します。そのため、複数のバリアントが宣言している名前は、その Release がビルドに使うものに解決されます。それらのディレクトリで解決できない名前は、workspace.releases 配下のその Release のエントリを示す説明とともに拒否されます。レジストリ参照は、どの Release が指定されていてもそのレジストリから読まれるため、release と併せて指定すると拒否されます。name なしで送られた release は、従来どおり describe が要約する Release です。
  • entity と release を指定した validate は、単一エンティティのチェックをその Release の観点で実行します。エンティティの参照(Recipe が実装する Component、ピラーが参照する SchemaLibrary など)はその Release のカタログディレクトリを通して解決され、応答ではエンティティの横にその Release が示されます。クロージャは検証されません。entity なしで送られた release は、従来どおり Release スコープです。ここでも他の場所と同様に、catalog_dirs は Release のディレクトリの前に追加されます。ワークスペース設定が列挙しているのにディレクトリではないもの(たとえばそこに何も存在しない場合)は、その Release について、または release が送られない場合はワークスペースについて、何かがチェックされる前に呼び出しを拒否させます。テキストには、すべてのコマンドが返すのと同じ拒否が含まれ、そのエントリと、それを列挙している設定ファイルおよび行が示されます(ローカルエンティティの読み込み元)。これは aggrega validate が拒否するのと同様です。

存在しないファイルやディレクトリを指す release は、3 つのツールのいずれでも、ワークスペースの観点で応答されることなく拒否されます。何も送らない場合は、ワークスペース自身のカタログディレクトリを対象に応答します。

名前を検索する describe は、名前の解決に使うカタログディレクトリを走査できない場合、aggrega inspect と同様にそれを拒否します。対象は、release が送られた場合はその Release のディレクトリ、送られない場合はワークスペース自身のディレクトリ、そして呼び出しが catalog_dirs で指定したディレクトリです。呼び出しが指定したディレクトリが存在しない場合、または存在しても読めない場合は、名前の検索前に拒否されます。テキストには、残りのディレクトリから名前を解決する代わりに、コマンドラインが報告するのと同じ形で、そのディレクトリ、catalog load、ファイルシステムが返した理由が 1 行で示されます。ワークスペース設定が列挙しているのにディレクトリではないものは、同じ時点で拒否され、テキストにはすべてのコマンドが返すのと同じ拒否が含まれます(ローカルエンティティの読み込み元)。存在しないファイルを指す release は、前述のとおりそれより先に拒否されます。読み込みが留まるべきディレクトリの外へ出るリンクを含むカタログディレクトリも同様に拒否され、テキストにはそのリンクとリンク先が示されます。そのディレクトリなしで名前を解決すると、代わりに同名の別のエンティティに解決される可能性があるためです。Release の依存クロージャの記述は、走査できないディレクトリの影響を受けず、aggrega inspect --closure と同様に走査できるディレクトリを対象に応答します。ただし、ワークスペース設定がその Release について列挙しているのにディレクトリではないものは例外で、aggrega inspect --closure が拒否するのと同様に拒否します。カタログディレクトリの読み込み範囲、または Release の横にあるドキュメントの範囲から外へ出るリンクは、ビルドを停止するのと同様にこれを停止します。

entity を指定した validate は、判定できないレンダリングを、Release の観点の有無にかかわらず、未試行として報告します。 これは Recipe の Component を、接続を配線せず Feature もアタッチしない合成ビルドに配置します。そのため、テンプレート(インポートするファイルやライブラリエントリを含む)が .context.inject、.context.uses、.features 配下の値を読んでいる間にレンダリングが停止する Recipe は、diagnostics が空のまま valid: true と応答します。そのテキストには、Render: not attempted (this Recipe reads values a build of one cannot supply)、保留の理由となった読み込み、レンダリングが停止した文が含まれます。判定を決めるのは Recipe が読むものです。そのため、そのような読み込みと並ぶ Recipe 自身の不具合も一緒に保留されますが、パースできないテンプレートやレンダリングが拒否する参照は、引き続き valid: false と応答します。aggrega validate は同じ入力に対して同じ判定を下します。

entity を指定した validate は、失敗したアサーションを、Release の観点の有無にかかわらず、警告として報告します。 fail を呼び出すアサーション(Recipe 自身のもの、または実装する Component が宣言するもの)は、diagnostics が空のまま valid: true と応答します。合成ビルドには、実際の Release が設定する値の代わりにプレースホルダーとスキーマのデフォルト値が入るため、そうした値に対するアサーションは Recipe が健全かどうかにかかわらずそこで失敗し、チェックでは Release を待っているアサーションと壊れているアサーションを区別できません。失敗は他の notices の後に、文 A Release must satisfy this assertion before a build of it can pass. で締めくくられたアサーションの完全なメッセージとして示され、テキストでは実行の停止位置を示すレポート行の横に、warning: で始まる行として示されます。読み込むキーが見つからずに停止するアサーションは、失敗したアサーションではなくそれ自身のテキストの不具合であり、他の停止と同様に判定されます。アサーションを満たさない Release のビルドは、引き続きそのアサーションを理由に拒否されます。aggrega validate は同じ入力に対して同じ判定を下します。

有効な設定と、このサーバーが解決するプラグインを読み取る

config-show は、有効な設定と、各設定をどのレイヤーが決定したかを報告します。plugin-list は、このサーバーが解決できるプラグインと、それぞれが自身について述べる内容を報告します。どちらも何も読み書きしないため、どちらも何にも到達せず、aggrega:read で許可されます。また、どちらも対象の指定を求めません。何が設定され、何が解決されるかは、事前に知っておく必要のある何かの性質ではなく、このサーバーの性質だからです。どちらも標準入出力では省略可能な workspace_root を受け取ります。HTTP ではこの引数は拒否されます。詳しくは 1 つのプロセス、1 つのワークスペース を参照してください。

この 2 つは合わせて、1 つの問いに 2 つの側面から答えます。つまり、ある機能が存在しないのか、それとも単にここで設定されていないだけなのか、という問いです。 設定は、プロバイダー、インポーター、ガバナンスチェックがそもそもアタッチされているかどうかを示します。プラグインの読み取りは、アタッチメントが、解決され、自身を記述し、主張するものを提供するゲストに到達するかどうかを示します。このサーフェスの他のどこから見てもこの 2 つは同じに見えますが、求められる次の手順は正反対です。

config-show は設定ごとに 1 つのエントリを報告します。その field、有効な value、そしてそれを決定した source(設定ファイル、環境変数、コマンドラインフラグ、または組み込みのデフォルト)です。これらに加えて、layers は寄与したレイヤーを優先順位の低いものから順に保持します。設定の source は layers 内の対応するエントリとまったく同じ表記なので、両者は直接結び付けられます。デフォルトが決定した設定はレイヤーを一切示しません。デフォルトは寄与したレイヤーではないからです。グローバルレイヤーは、サーバー自身のコマンドラインが選択するファイルです。つまり、起動時に --config が指定したファイル、それがなければ環境変数 AGGREGA_CONFIG が指定するファイル、それもなければデフォルトの場所です。そのため、そのファイルが決定した設定は、aggrega config show --origin が帰属させるのとまったく同じように、そのファイルに帰属します。また、サーバーに与えられた --offline などのフラグは、そのフラグとして報告されます。response_format もページサイズも受け取りません。設定はこのバイナリが扱う固定の集合であり、どの解決でもそのすべてが報告されるため、回答のサイズは設定内容ではなくバイナリによって決まります。

plugin-list はワークスペースの一覧と同じ 2 つの形で回答し、形を指定しない呼び出しには要約が返されます。 要約はグループごとの件数で、グループは 2 つあります。embedded はこのバイナリにコンパイルされたゲストで、ファイルシステム、キャッシュ、ネットワークへのアクセスなしに解決されます。configured はワークスペース自身のバインディングです。レコードを得るには response_format: detailed を送信します。各プラグインのグループ、見つかったときの参照、その参照がバインドされた場所、自己申告の型、バージョン、コミット、提供する機能、レンダリングする入力の種類、境界アセンブリとエクスポート、レディネス(ある場合)、そして解決されたかどうかが含まれます。レコードはエンティティ一覧と同じ条件で limit と offset によって範囲が制限され、続きを取得するための count、returned、more_remaining が付きます。この回答は設定内容に応じて大きくなります。組み込みは固定ですが、バインディングは利用者のものだからです。これが、この回答はページングされ、設定の読み取りはページングされない理由です。

失敗したプラグインは一覧から除外されず、その失敗とともに報告されます。 resolved は参照がそもそもモジュールのバイトに到達したかどうかを示し、解決されたものの自身を記述できなかったプラグインはまさにそのとおりに報告されます。そのため、存在するが使用できないアタッチメントと、一度も作成されなかったアタッチメントを区別できます。

リスナーがそのホストについて伝えないこと

HTTP では、どちらの読み取りもサーバーのファイルシステム上の場所を示す値を報告しません。 サーバーを起動したクライアントはサーバーと同じ場所で動作するため、どちらの回答が示しうる場所も、その呼び出し元がすでに所有し、実際に見に行ける場所です。リスナーに到達する呼び出し元はそのどれも選んでおらず、それを知っても何もできません。また、そのような呼び出し元に一度公開したサーバーは、それを取り消せません。そのトランスポートではそれらの値は存在せず、標準入出力ではすべて存在します。これは 回答がサーバーのファイルシステムについて述べること で説明するとおり、このサーフェスのすべての回答が従う規則であり、この 2 つの読み取りはその影響が最も大きい箇所です。報告する内容の大半が場所を示す設定だからです。

伏せられるもの。 config-show からは、設定自体の値が場所である場合の設定の value。つまり、サービングアドレスやヘルスアドレス(ソケットファイルの場合があります)、証明書、秘密鍵、キーセットのファイル、カタログディレクトリ、そして workspace.releases 配下の Release 固有のカタログディレクトリ(各エントリが Release ファイルをキーとします)、プラグイン参照、オーサリング用の Release です。また、設定を決定したレイヤーが設定ファイルである場合の設定の source。そのようなレイヤーはそのファイル自身のパスで示されるからです。同じ表記で同じ理由により、layers の設定ファイルのエントリも伏せられます。plugin-list からは、参照自体がファイルシステムパスである場合のプラグインの uri、そして解決または記述の失敗のテキスト。これは試行された場所から構成されるため、参照自体が示さない場所を示すからです。両方からは workspace_root です。

両方のトランスポートで完全に報告されるもの。 レジストリ参照、バージョン、コミット、ダイジェスト、提供する機能、レディネスのラベル、環境変数やフラグの名前、そしてファイルではないレイヤーです。プラグインレコードの origin はこれに該当します。これはバインディングが書かれた設定キー、またはインストールされたコマンド拡張が持つ固定されたダイジェストであり、組み込みには何もありません。そのため、プラグインがどこから読み取られても同じ文字列になります。resolved もこれに該当します。プラグインが失敗したかどうかは、その理由が報告されない場合でも、すべての呼び出し元に報告されます。

存在しない値は常に伏せられたことを示し、それが回答を使えるものにしています。 伏せられた値は、横に目印を付けて存在しないものとして報告されます。設定では value_withheld と source_withheld、レイヤーのエントリでは withheld、プラグインレコードでは uri_withheld と error_withheld、回答では workspace_root_withheld です。誰も設定していない設定は、その形が表す空の値を持ち、目印は付きません。「このサーバーは署名鍵の場所を伝えていない」と「署名鍵が設定されていない」は、異なる次の手順を求める異なる回答であり、両者を同じように報告する読み取りでは、行動につながる情報は何も得られません。各回答には常に host_locations_withheld も含まれ、どちらの回答を手にしているかを示します。これがなければ、目印のない回答は、この規則が適用されたうえでホストに伏せるものがなかった場合と、規則がまったく適用されなかった場合とで同じになってしまいます。フィールドに添えられた可読テキストも、同じことを言葉で述べます。

この規則はフィールド名のリストではなく性質です。値は、誰が設定したか、どのレイヤーから来たかにかかわらず、ホストのファイルシステム上の場所を示す場合に伏せられます。後からどちらかの読み取りに追加される値も、同じ性質に従います。

標準入出力では、各機能はそのコマンドにちなんだ名前のツール(cli-config-show と cli-plugin-list)としても利用できます。これらはそのコマンドを別プロセスで実行し、出力されたテキストを返します。HTTP ではこれらのツールは存在しません。ここで説明した 2 つは代わりに値そのものを返すため、列レイアウトを元のデータに解析し直すことなく、機能がアタッチされているかどうかを読み取ったり、プラグインのバージョンを取り出したりできます。

何がアタッチでき、何が何に接続できるかを問い合わせる

2 つのツールが、アシスタントが本来なら推測するしかない問いに答えます。どの Features がノードにアタッチできるか、そしてノードが何に接続できるかです。どちらもコンパイラが実行するのと同じラベルマッチを実行するため、アシスタントが提示するのは、スキーマから推測した集合ではなく、ビルドがマッチする集合です。

attach-candidates は、宣言された適用条件をノードのラベルが満たす Features を報告します。ノードは次の 3 つの方法のうち、ちょうど 1 つで指定します。

  • node — list-entities が報告するとおりの、ワークスペースエンティティの metadata.name です。マッチはそのドキュメントが宣言するラベルに対して実行されます。
  • graph_node と release — コンパイル済みグラフ上のノードで、グラフがキーとする形式で指定します。サブアグリゲートが寄与したノードが持つ修飾形式も含みます。マッチはそのノードの確定済みラベル、つまりビルドが評価するラベルに対して実行されます。
  • labels — ノードを指定しない、単独のラベルセットです。座標をまったく必要としないため、ノードのラベルをすでに持っている場合はこの形式を使います。何も検索せず、グラフも再構築しません。

回答には、マッチの対象となったラベルと、それがこの 3 つのどのセットから来たかが含まれます。そのため、どの候補についても、あるいは候補がないことについても、改めて導き出すことなく回答そのものから説明できます。ラベルを別の方法で読み直すと、ノードのラベルについての理解とコンパイラの理解が食い違う原因になります。

ノードが引く 1 本の接続に何をアタッチできるかを問うには、graph_node と release に connection を添えます — 作成者が書いたとおりの socket と alias です。接続は、そのソケットが消費側の Component 上で宣言するスロットを埋めるアタッチメントを持つため、回答にはさらに slots が含まれます。ソケットが宣言する各スロットについて、Component が宣言するとおりの selector、required、inject、sensitive、description と、そのスロットを埋めうる candidates が示されます。これらは、ノードのラベルが適用条件を満たし、かつ自身のラベルがスロットのセレクタに受け入れられる Features です。これはビルドがそのようなアタッチメントに課す 2 つの規則であるため、スロットの候補は常にノード自身の候補に含まれます。何も埋められない場合、slots は空になり、noSlotReason がその理由を示します。feature-created-connection(Feature が接続を引いたもので、そのような接続には何もアタッチされません)、ad-hoc-socket(Component が宣言していないソケット)、no-slot-declared(ソケットがスロットを宣言していない)のいずれかです。空の slots を「何も一致しなかった」と読まないでください。それを排除するために理由があり、スロットが存在する場合は理由は含まれません。並んでいる candidates の意味は変わらず、ノード自身にアタッチできるものを示します。また document を送っても、ここでは何も変わりません。node や labels と併せて指定した場合、またはソケットやエイリアスを指定しない場合の connection は拒否され、ノードが引いていない接続も同様に拒否されます。これらは言語サーバーが返すのと同じ回答であり、条件も同じです。

connection-candidates は、エンティティが宣言する依存ソケットと、ソケットごとに、そのソケットがターゲットに対して宣言する制約を宣言済みラベルが満たすワークスペースの Components を報告します。エンティティの metadata.name を node で受け取ります。attach-candidates と異なり、座標を使わない形式はありません。ソケットは指定されたエンティティ自身の宣言から読み取られるため、ここにはラベルセットの形式がないのです。

2 つの部分は同じように完全ではなく、回答はどちらがどちらかを示します。1 つのリストとして提示しないでください。 ターゲットは完全です。ビルド中に同じ制約が受け入れるコンポーネントそのものです。ソケットは完全ではなく、完全にはなり得ません。消費側は接続を作り出すことができますが、消費できるのは提供側が宣言したものだけです。そのため、作成者はカタログのエンティティが宣言していないソケットを正当に書くことができ、宣言済みソケットは正当な名前の集合ではなく、手がかりとなる出発点です。したがって各ソケットは declared か ad-hoc かを示し、回答はそのエンティティで未宣言のソケットがそもそも受け入れられるかを示します。Component 自身の依存サーフェスは受け入れます。作成者が自分のアプリケーションのトポロジーを所有しているからです。Feature のアタッチメントサーフェスは受け入れません。アタッチメントはトポロジーを作成するのではなく、アタッチ先の Feature が宣言するトポロジーに参加するからです。この開放性は作成の自由の帰結であり、欠落ではありません。エンティティが宣言していない名前について問い合わせるには、その名前を socket に渡します。

どちらも答えて止まります。どちらもアタッチメントやエッジを作成せず、どのファイルにも書き込まず、その記述内容を提案することもしません。続く編集を組み立てて適用するのは利用者の役割です。

どちらも、ここでの他のすべての回答と同じ最小限の識別情報 — kind、名前、ソースファイル — を返し、それ以上は返しません。エンティティについて表示したい他の情報はすべて、同じ 3 つのフィールドで list-entities にすでにあるため、食い違う可能性のある 2 つのコピーを読むのではなく、2 つの回答を結合します。どちらも、解決できない名前に対しては空のリストで答えるのではなく拒否します。サーフェスの他の部分と同じ理由で、空の回答はタイプミスを、提示するものが何もない対象として報告してしまうからです。labels の呼び出しには打ち間違える名前がないため、そこでの空の結果は文字どおりの意味です。

サーバーが参照のために読むものはすべてこのマシンから提供されます。JSON Schema はバイナリに組み込まれており、ドキュメントは後述のとおりマシンが保持するドキュメントバンドルのキャッシュから読み込まれます。スターター文書の作成、検証、describe、ビルド、lint はすべてワークスペースとローカルキャッシュに対して実行され、いずれも自らレジストリにアクセスすることはありません。レンダリングは、ピン留めされた外部参照をコンテンツアドレス型ストアから提供し、ピン留めされていない参照は取得せずに拒否します。これにより、検査とレンダリングのループ全体がオフラインに保たれます。要求できるレジストリ読み取りは 2 つあります。1 つはレジストリ参照を与えた describe で、その 1 つの座標を取得し、何も書き込まず、HTTP 経由では提供中のワークスペースに設定されたレジストリにのみアクセスします。もう 1 つは example または list を送った scaffold で、ワークスペースの署名ポリシーが認めるコピーをマシンが保持していない場合に、ワークスペースのデフォルトレジストリからドキュメントバンドルを取得し、保持する前に検証します。これは aggrega scaffold --example と同じ動作です。公開と署名はその意図的な反対側であり、上で説明しています。

その中間にあるのが Release の依存関係の解決で、ここで取得を行う唯一の操作です。依存関係の解決を求められることは、それを取得するよう求められることなので、レジストリにアクセスします。これは要求したときにのみ行われ、要求する方法はちょうど 2 つです — それ自体が役割である pull を呼び出すか、build に auto_pull を送るかです。後者はビルドの最初のステップとして同じ解決を実行します。それ以外に代わりに pull するものはなく、auto_pull を送らなかったビルドはレジストリにアクセスしません。これを変える唯一の設定はワークスペース自身の auto_pull です。そのように設定されたワークスペースは、どこから実行されたかにかかわらず、その中のすべてのビルドに先に解決するよう求めています。これについては後述します。

これらの参照読み取りの中で唯一の例外は、ドキュメントバンドル自体の取得であり、これはどの読み取りからも離れたところで行われます。バンドルはマシンごとに 1 回、すべての Aggrega プロジェクトが共有するキャッシュに、レジストリとバージョンごとに 1 コピーずつ保持されます。そのため、ワークスペースキャッシュを作成できないフォルダでサーバーを起動しても、バンドルは同様に保持されます(aggrega cache を参照)。サーバーは起動時、送られたものに応答する前に、ワークスペース自身の署名チェック — バンドルの pull が従うのと同じチェック — が受け入れるコピーをそこで探し、ない場合にのみ、CLI の他の部分と同じ egress 設定を通じてバンドルを pull します。探すバンドルは、サーバーが実行している aggrega のバージョン向けに公開されたものであり、そのバージョン向けに公開されたものがない場合は、それより前のバージョン向けに公開された最新のものです。これは aggrega explain と aggrega scaffold --example が行うのと同じ選択であり、サーバーが提供するすべてのページとすべての説明は、取得したそのバンドルから読み込まれます。そのため、クライアントが最初に何を送るかにかかわらず、何かがページを求める時点でページはすでに用意されており、別のサーバーや別のプロジェクトの aggrega explain も、再度ダウンロードするのではなく同じコピーを見つけます。

その後のページの提供はそのコピーの読み取りであり、レジストリには到達しません。ページを提供する前に、コピーの横に保持されている署名がワークスペースのチェックのもとで再度検証されるため、別のプロジェクトのより緩い設定によって取り込まれたコピーが提供されることはありません。チェックが鍵またはトラストルートを固定している場合、その検証はオフラインで実行されます。どちらも固定していない場合(公式ハブの組み込みチェックはその一例です)、pull と同様に公開 Sigstore トラストルートを取得します。オフラインのワークスペースはそのトラストルートを取得できないため、オフライン時には、このマシン上で以前にオンラインで取得したトラストルート(ホームディレクトリの .sigstore 配下に Sigstore クライアントが保持するキャッシュに残されたもの)に対して、その取得がどれほど前であっても検証を行い、何も取得しません。一度も取得したことのないマシンではチェックをオフラインで実行できず、コピーは提供されず、ログストリームにその旨が出力されます。この検証はサーバーの実行中、コピーとチェックの組み合わせごとに一度実行され、その後に読み取られるページは検証が許可した内容に基づいて提供されます。その後に取得されたコピー、チェックが異なるワークスペース(固定されたトラストルートがその場で編集された場合を含む)、オフラインで行われた読み取り、あるいはマシン上に残された別のトラストルートを見つけたオフライン読み取りは、それぞれ個別に検証されます。チェックが拒否したコピーは次の読み取り時に再度チェックされるため、その後の取得によって許可された場合にそれが覆されることはありません。バンドルを取得できない場合、または唯一のコピーがチェックで拒否され、そのチェックのもとでの再取得にも失敗した場合でも、サーバーは起動し、他のすべての機能は動作します。ドキュメントのリクエストは not-found を返し、サーバーのログストリームにその理由が出力されます。

Release がすでに固定しているコンテンツに対してビルドする

build は Release をメモリ上でアーティファクトにレンダリングします。レンダリングはリモート URL のコンテンツを要求することがあります。たとえば、リモート参照を含むチャートの values スキーマです。外部入力はその呼び出しの間凍結されます。 Release のロックファイルがすでに固定している参照は、コンテンツアドレス指定ストアから提供されます。これは取得ではなく、すでにディスク上にあるコンテンツの読み取りです。ロックファイルが固定していない参照は、取得されずに拒否され、その名前が示されます。要求されたのはレンダリングであり、参照を取得すると、バイトを生成する副作用としてネットワークに到達し、ストアに blob を書き込むことになるためです。この凍結はレンダリングの性質です。解決は取得を行うステップです。Release をレンダリングしてそのレンダリングがどのリモート参照を要求するかを調べ、それらを取得し、依存関係の固定を記録するのと同じロックファイルの書き込みで記録します。したがって、解決によって変わるのはレンダリングの実行時点でどの参照が固定されているかであり、レンダリングが到達できる範囲は決して変わりません。どの解決でも固定されなかった参照は、先に解決を行った呼び出しでも、行わなかった呼び出しとまったく同じように拒否されます。

ファイルは実際のビルドが出力するバイトとして返されます。それを成り立たせているのは、次の 2 つの組み合わせです。 1 つは上記の凍結で、固定された参照は取得されずにストアから読み取られます。もう 1 つは、読み取り元のロックファイルが今も Release の解決結果を表していることです。そのため build はこれを確認し、もはや一致しないロックファイルを、端末での aggrega build とまったく同じように拒否します。固定されたバイトを読み取るだけでは、それが読み取るべき正しいバイトだったかどうかは何もわかりません。

姿勢を明確にするため、ロックファイルの 3 つの状態すべてを示します。 ロックファイルがまったくない場合、build はワークスペースがすでに固定しているものからレンダリングし、提供できない外部参照をすべて拒否して、それぞれの名前を示します。そのままではロックファイルを要求することも書き込むこともなく、これは上記の確認によっても変わりません。比較するロックファイルがないため、何も拒否されません。ロックファイルが一致する場合は、レンダリングします。ロックファイルがもはや一致しない場合は拒否し、その拒否は解消方法を示します。同じ release を指定し、upgrade_targets を指定せずに pull を呼び出してください。これにより、ロックファイルが現在の Release の解決結果に合わせて調整されます。拒否には、同じ操作の端末での形式である aggrega pull --release <release> も含まれます。どちらの呼び出し方でも解消されます。これらは 2 か所から到達できる 1 つの操作であり、どちらかを選ぶ 2 つの指示ではありません。pull が完了しても拒否が返ってくる場合、2 つの呼び出しは異なる入力に対して解決しています。多くの場合、一方にだけ catalog_dirs を指定したか、その間にワークスペース設定が編集されたかです。拒否はそのことを示します。両方を同じ入力で呼び出してください。

release だけを指定した validate と describe も、同じロックファイルに従います。 Release の解決結果ともはや一致しないロックファイルに対しては、どちらも応答せずに拒否し、そのテキストには build が拒否するときのドリフト停止と、同じ解消方法が含まれます。これは aggrega validate --release と aggrega inspect --closure が端末で拒否するのと同じです。ロックファイルが一致する場合、またはロックファイルがない場合は、どちらも通常どおり応答します。

ビルドに先に依存関係を解決させる

auto_pull を送ると、ビルドはレンダリングの前に解決を行います。 pull が行うのと同じ解決を行い(ビルド用に別途書かれたものではなく操作そのものなので、ビルドで満たされたワークスペースと pull 呼び出しで満たされたワークスペースは同一に満たされます)、Release のロックファイルを書き込み、書き込んだ内容に対してレンダリングします。このステップはレジストリに到達し、書き込みを行います。build で他にこれを行うのは write だけであり、write はレジストリに到達しません。そのため、要求されない限りオフです。

これにより、プロトコルを離れずに上記の 2 つの拒否に対応できます。 まだ誰も解決していない Release は、たまたまある固定からレンダリングし、残りを拒否します。ずれたロックファイルはビルドを即座に停止させます。auto_pull を送ると先に解決を行い、このビルドが対象とするクロージャから導かれたロックファイルに対してレンダリングするため、どちらの場合も修正すべきものとしてではなくレンダリングとして返ってきます。解決とレンダリングを別々のステップとして行いたい場合(レンダリングの前に何が固定されたかを読むため)は、pull を呼び出してから build を呼び出してください。これは同じ 2 つの操作の間に確認を挟んだものです。

1 回の呼び出しで Release は 1 回だけレンダリングされます。 Release がどのリモート参照を使用するかを調べること自体がレンダリングなので、解決の時点で、ビルドの対象となる Release はすでにレンダリングされています。それも書き込んだばかりの固定に対して、ビルドが実行するすべてのゲートを伴ってです。ビルドはそのレンダリングを繰り返さずにその結果から応答します。そのため、auto_pull を送るコストは解決 1 回分であり、2 回目のレンダリングではありません。このように使われるのは完了したレンダリングだけです。解決が依存関係を固定したものの外部参照の検出を完了できなかった場合、ビルドは実際に反映された固定に対して自らレンダリングし、固定されていない参照があれば、ビルドが出力するものに満たないファイル一覧として返すのではなく、その名前を示して停止します。

返される内容は、何が解決されたかを示します。 依存関係を満たしたビルドは、応答に pull の応答と同じ形の dependency_resolution を含みます。書き込んだロックファイル、解決が到達したすべての参照とそれぞれの解決先バージョンおよびこのビルドの解決がそれを取得した場所、その後ロックファイルが保持する件数、そして解決自身による 1 行ごとの記録です。満たさなかったビルドにはこのフィールドがまったくないため、その有無によって、ディスクを読まずに両者を区別できます。レンダリングされたファイルは他のビルドとまったく同じように報告され、呼び出しに write も送られていない限り、引き続きメモリ上で返されます。解決が書き込むのはロックファイルとアーティファクトキャッシュであり、アーティファクトは決して書き込みません。

ワークスペースはこれを常時要求でき、呼び出しでそれをオフにすることはできません。 ワークスペース自身の auto_pull 設定は、そのワークスペースのすべてのビルドで同じステップをオンにします。呼び出しの auto_pull はその設定を上書きするのではなく追加されます。どちらか一方で十分であり、ワークスペースが要求した解決を抑止する引数はありません。これは端末で設定と aggrega build --auto-pull が組み合わさるのと同じ方法なので、1 つのワークスペースは、ビルドがどのサーフェスから届いても同じように応答します。

拒否は吸収されずに報告され、このバイナリに含まれる provider では、拒否によってレンダリングが停止します。参照を要求した provider が拒否を返すため、呼び出しはその失敗で応答し、ファイルを返しません。参照は、読み手が対処できる場所で、それを固定するコマンド aggrega pull --release <path> とともに名前が示されます。同じ固定は、このサーフェスでは pull ツールとして利用できます。 これは後述の Release が依存するものを解決するで説明しており、この拒否に遭遇したアシスタントはプロトコルを離れずに対処できます。完全に固定されたレンダリングでは、これらについて何も示されません。固定が何を取得して記録するかについては aggrega pull を、固定されていない参照が同じように報告されて実行を停止させる点については aggrega build を参照してください。

aggrega build が書き込む場所への成果物の書き込み

write を送ると、完了したレンダリングはワークスペースのルートにある dist/、つまり aggrega build が書き込む場所にも書き込まれます。 このディレクトリはコマンドラインが同じワークスペースルートの下に構成するものと同一であり、書き込みもコマンドラインが行うものと同一です。そのため、1 つのワークスペース内の 1 つの Release について、aggrega build、outputParent を指定しない言語サーバーの aggrega/build、そしてこの呼び出しは、バイト単位で同一の 1 つのツリーを書き込み、そのディレクトリを同じように示します。すなわち、コマンドの最終行、言語サーバーの outputDirectory、この応答の output_dir です。ワークスペースの外を指すリンクである dist は、ターミナルの場合と同様に、その中の何かが削除または書き込まれる前に拒否されます。省略した場合(これが既定です)、成果物はメモリ上で返され、何も書き込まれません。

ワークスペースルートは呼び出し自身のものです。 標準入出力経由では、呼び出しがどのワークスペースで応答されるかで説明しているとおり、呼び出しが解決したワークスペースのルートです。すなわち、workspace_root が指定するルート、それがなければサーバーの起動時に指定されたルート、それもなければサーバーが起動されたディレクトリから見つかったワークスペースです。さらに、絶対パスで指定された Release によって呼び出しがその Release 自身のワークスペースに移る場合は、そのワークスペースのルートになります。これは、同じ Release と同じ指定ルートに対して aggrega build が書き込む先のルートと同じです。そのため、サーバーがたまたま実行されているフォルダに dist が作られるのは、そのフォルダが呼び出しの解決したルートである場合に限られ、そこで開いたターミナルの場合と同じです。HTTP 経由では、サーバーが提供するワークスペースであり、その外には何も書き込まれません。

書き込みはワークスペースに及ぶため、HTTP 経由では aggrega:workspace-write が必要です。 write を送った呼び出しは、依存関係を先に解決するビルドとまったく同様に、その呼び出しのためにワークスペースに及びます。aggrega:read のみを持つ資格情報には aggrega:workspace-write を示す 403 が返され、何も書き込まれません。また、mcp.deny_reach に workspace を指定しているサーバーは、その設定を示して呼び出しを拒否します。このツールはすべての呼び出し元のツール一覧に残り、write を送らないビルドは読み取りスコープの呼び出し元でも引き続き利用できます。

書き込みは最後に行われます。 auto_pull も指定した場合、呼び出しは解決、レンダリング、書き込みの順に処理します。それより前のいずれかの時点(Release、ワークスペース、カタログディレクトリ、解決、レンダリング)で拒否された呼び出しは、成果物を一切書き込みません。

応答は書き込まれたものを示します。 output_dir はそのディレクトリ(標準入出力経由ではフルパス、HTTP 経由では dist)であり、files は書き込まれた各ファイルをそのディレクトリからの相対パスで列挙します。response_format: detailed では内容も含み、concise ではパスのみです。テキストには、書き込まれたファイルの数と場所が記されます。write を送らなかった呼び出しには output_dir が含まれないため、その有無によって何も書き込まれなかったことがわかります。レンダリングの完了後に書き込みが失敗した場合(たとえば誰も書き込めないワークスペースルートへの書き込み)、ディレクトリと原因を示す失敗として応答し、書き込まれたファイルを一切列挙しません。書き込みの一部がディスク上に残っている可能性があり、レンダリングされたファイルを書き込み済みとして示すと、実際に起きた以上のことを主張することになるためです。

ディレクトリを指定する引数も、トレースを要求する引数もありません。 成果物の出力先は呼び出しが解決したワークスペースによって決まり、呼び出しによって決まることはありません。また、ここから書き込まれたビルドは出力の横に .trace ディレクトリを残しません。トレース付きのビルドは aggrega build --trace です。

ビルドがファイル以外に伝えること

ビルドは、発生させたすべてのアドバイザリを回答そのものに含めます。 これらは aggrega build が処理中に出力する検出事項です。たとえば、宣言済みの名前と 1 文字違いの名前、どこからも読まれないパラメータ、作成されたフィールドを反映できないターゲット、停止を伴わないガバナンスの判定、Release が拡張元の Release から継承し同じパスに解決される境界ディレクトリ、Release が到達する Component または Feature がその values と infra の両方の柱で宣言しているプロパティなどです。これらはいずれも結果を変えません。アドバイザリを含むビルドも成功しており、返されるファイルはそのビルドが生成したファイルです。アドバイザリはターミナルが出力するのと同じ順序で届くため、両者を比較する読み手は 2 つではなく 1 つの並びを目にします。まず、レンダリングが発生させたすべてのものが発生順に並びます。次に、Release とそれが到達するものに関する検出事項で、これは aggrega build がレンダリングの完了後に出力します。最後に、write を送ったビルドでは、書き込み時に自身のファイルの横で見つかった、自身が書き込んでいない各ファイルを示す警告で、それらのファイルはそのまま残されます。これは aggrega build がファイルを書き込み終えた後に出力する警告です(ビルドが書き込まなかったファイル)。

これらが要約テキストだけでなく回答に含まれるのは、このサーフェスを操作するアシスタントはターミナルを読まず、誰にも伝えられない検出事項は検出されなかったのと同じだからです。各エントリには severity(注意を要するものには warn、記録された観察には info)と message があります。クラスが割り当てる場合は code もあり、テキストを照合せずに特定の状態に対応できます。また、検出事項が作成済みドキュメント内の特定のキーに関するものである場合は、そのキーを示す key_path があります。デプロイされたトポロジーの形状に関する検出事項は、その座標がドキュメントではなくデプロイメントのものであるため、キーを示さず、代わりに対象をメッセージで説明します。

ターミナルが出力する検出事項のうち 2 種類は、より多くを伝えられる場所があるため、advisories 以外の場所でこの回答に届きます。記録された非推奨マーカーは、ロックファイルがピン留めされた参照に対して記録したものであっても、その隣にあるプラグイン信頼記録が受理または拒否の判定を返すロールでアタッチされたプラグインに対して記録したものであっても、deprecations にあります。Release に対する describe は同じ集合を自身の deprecations で示し、Release に対する validate は notices の中で示します。いずれも判定はそのままです。存在するものの読み取れない信頼記録がある場合は、何も記録していない記録として扱われるのではなく、どちらの呼び出しも拒否されます。エンティティの継承元である親が解決できない場合はビルドが停止するため、何も変えなかった検出事項として列挙されるのではなく、拒否のテキストで示されます。また 1 種類は、回答が含めるものではなく、このツールが読み込むものによって範囲が決まります。aggrega build は Release を解決する前に設定済みのすべてのカタログディレクトリを読み込み、非推奨のカタログ形状に関する通知はその読み込みから生じます。一方、このツールは Release が到達するものだけを読み、そのような読み込みを行わないため、そのような通知は報告しません。現時点ではそのような通知を発生させるビルドはないため、両者は同じ検出事項を報告します。

何も発生させない Release は何も伝えません。キーは空の状態で存在するのではなく存在しないため、キーが存在すること自体が読むべきものがあることを示します。

拒否されたビルドが返すもの

拒否したビルドは、成功したビルドと同じフィールドで応答し、実行が進んだところまでが埋められます。 応答は失敗としてフラグが立てられ、修正内容をテキストとして持ち、構造化ペイロードはそのテキストに置き換えられるのではなく、その横に置かれます。Release のレンダリング中に発生した拒否は、後述のレンダリング中に発生した拒否で説明するとおりコンパイラの言葉で記述され、独自のフィールドを 1 つ追加します。アドバイザリもそこに含まれます。実行されたフェーズはそれぞれが発したものを発しており、それらは拒否を乗り越えるために対処すべき所見であるため、解析が必要な文章としてではなく、照合できるエントリとして届きます。deprecations と declined_external_inputs も同じ理由で含まれます。記録されたマーカーはマーカーが記録されたから報告され、却下された参照は参照が却下されたから報告されるのであり、どちらの事実も実行がどう終わったかの結果ではありません。

files は拒否時には何も報告せず、結果を読み取るためのフィールドではありません。 何も出力されていないため、名前を挙げるアーティファクトはありません。キーの有無で分岐しないでください。キーはどちらの場合も報告され、空の files だけでは、拒否したビルドと、実行されて何も出力しなかったビルドとを区別できません。結果の失敗フラグを読んでください。それがプロトコル自体の判別子です。そして files はその本来の意味、つまりレンダリングされたもの(呼び出しに write が送られた場合は書き込まれたものでもある)の一覧として読んでください。

拒否時のアドバイザリの範囲を決めるのは、実行がどこまで進んだかであり、応答が何を運べるかではありません。 Release の解決前に実行されるチェックによる拒否(キャッシュ内のピン留めされたエントリが記録されたダイジェストと一致せず、どのカタログディレクトリにもピン留めされたバイトがない場合や、Release の依存関係を解決できなかった場合)は、アドバイザリを報告しません。まだ何も発生していないためです。Release が拡張元の Release とどのように合成されるかに関する所見は、解決された時点で、後続のすべてのチェックに先立って発生するため、それ以降のすべての拒否はそれらを持ちます。たとえば、Manifest が型を、それを実装していない recipe にマッピングしている場合、Release が到達するエンティティがそのスキーマを満たさない場合、ロックファイルが Release の解決結果と一致しなくなった場合です。レンダー自身の所見はレンダーの実行中に発生するため、それらの前段のチェックによる拒否にはまったく含まれず、レンダーによる拒否にはそれ以前に発生したすべてが含まれます。したがって、拒否時の advisories は成功時とまったく同じように読んでください。この実行で見つかったものが、ターミナルが出力する順序で並んでいます。

エンティティが解決できない親から継承していることによる拒否は、そうした継承をすべてテキストに挙げます。その文言は aggrega build が出力するものと同じであるため、どれを修正すべきかがわかります。その詳細はビルドが停止した理由であり、だからこそ何も変えなかった所見の中ではなくテキストに含まれます。それより前に発生した合成の所見は、以降の他の拒否と同様に advisories にあります。

Release が読み込むカタログディレクトリを走査できない場合は、aggrega build が拒否するのと同様に、何かが書き込まれる前に拒否されます。 これは、呼び出しが catalog_dirs で指定した存在しないディレクトリ(aggrega build が存在しない --catalog ディレクトリを拒否するのと同様)、または存在するが読み取れないディレクトリです。aggrega build は Release を解決する前に Release が読み込むすべてのディレクトリをロードし、走査できないディレクトリで停止します。build は依存関係の解決やレンダーに先立って、同じディレクトリを最初に走査します(中のドキュメントは読みません)。そのため、auto_pull を送られたビルドはロックファイルを書き込まず、何もレンダリングされません。テキストは、コマンドラインが報告するとおりにディレクトリを 1 行で示します。ディレクトリ、catalog load、そしてファイルシステムが返した理由です。ペイロードは Release を示し、files は空で、所見はありません。何も実行されていないためです。ワークスペース設定に一覧されているディレクトリがディレクトリではない場合(たとえばそこに何も存在しない場合)、その走査に先立って同じ形で拒否されます。テキストには aggrega build がそれに対して出す拒否が含まれ、そのエントリと、それを一覧している設定ファイルおよび行が示されます(ローカルエンティティの読み込み元)。読み込みがその内側にとどまらなければならないディレクトリの外を指すリンクを含むカタログディレクトリも、同じ時点で何も書き込まれずに拒否され、テキストはそのリンクとリンク先を示します。aggrega build も同じ方法で拒否します。

両方の部分を具体的にするための例です。どの参照も読まないパラメーターを宣言し、その後レンダーを完了できない Release は、失敗として返されます。そのテキストにはレンダーの拒否が含まれ、ペイロードには、レンダーを停止させたものを示す refusal エントリの横に、severity、message、code、key_path を持つ未読パラメーターのアドバイザリが含まれます。これは、レンダーが完了した場合に同じ Release が応答で報告するのと同じ値を持つ同じエントリです。別の Release を拡張してテンプレート変数を含まない境界ディレクトリを継承し、その Manifest が型を、それを実装していない recipe にマッピングしている Release は、その拒否として返され、継承したディレクトリごとに 1 つの advisories エントリを持ち、それぞれの code は inherited-boundary-directory-is-literal です。一覧にあるカタログディレクトリがすべて存在するワークスペースで、依存関係を解決できない Release は、advisories キーをまったく持たない失敗として返されます。停止した時点で何も発生していなかったためです。

レンダリング中に発生した拒否

コンパイラがレンダリング中に拒否した Release(Component が宣言していないスロットを指定する Workload、失敗するアサーション、評価できないテンプレートなど)は、コンパイラの言葉による拒否と、その下にあるすべての原因を伴って返されます。これは同じ Release に対して cli-build が返す文言と同じで、レンダリング中のノード、続いてその中で拒否したものを示します。拒否が登録済みの条件を指す場合、テキストにはその条件の名前(照合に使う短いコードと説明的なコード)が explain-error と同様に追加されます。テキストの冒頭では、どの段階で拒否されたかを示します。レンダリングが発生させた拒否には The build failed during rendering; nothing was written to disk.、何かがレンダリングされる前にコンパイラの実行が発生させた拒否(レンダリングの元となるグラフの合成による拒否、または Component や Feature が宣言するアサーション)には The build refused before rendering anything; nothing was written to disk. が使われます。

ペイロードは同じ拒否を 1 つのエントリ refusal として持ちます。そのため、ドキュメントを変更する必要がある呼び出し元は、文を解析せずに、どのドキュメントのどこかを読み取れます。

  • file — 拒否が指すドキュメント。Workload の Recipe、失敗するアサーションを宣言している Recipe または FeatureRecipe、グラフの合成が拒否するエントリを記述した Release または Aggregate、あるいはどのドキュメントも指さない拒否の場合は Release の Aggregate です。
  • key_path — 拒否がキーを指す場合の、そのドキュメント内のキー。Workload に関する拒否では .spec.workload、失敗するアサーションでは .spec.assertions 配下のそのアサーション自身のキー、エントリの拒否ではそのエントリ自身のキーです。Workload に関する拒否は、その workload キーに置かれ、それより細かくはなりません。チェックが判定する Workload はテンプレートが生成したものであり、テンプレートは作成者が書いていない行を書き出すためです。拒否がそのレンダリング済み Workload の内部で指すパスは message に残ります。
  • line と column — そのキーの位置で、1 から数え、列は UTF-16 単位です。拒否がキーを指さない場合や、ドキュメントにそのキーがない場合は存在しません。位置は見つかった場合にのみ示されます。
  • severity — halt。ビルドを停止させた検出結果の重大度です。
  • code と short_code — 拒否が登録済みの条件を指す場合の、その条件の 2 つの識別子です。
  • message — 拒否のテキストで、回答のテキストに現れるものとまったく同じです。
  • findings — 拒否が複数の検出結果をまとめる場合にのみ存在します。グラフの合成が、見つけたすべての違反をまとめる場合がこれにあたります。検出結果ごとに 1 エントリで、拒否が述べる順に並び、それぞれがこれと同じ形、つまり独自の file、key_path、line、column、severity、code、short_code、message を持ちます。このとき拒否自身のフィールドは最初の検出結果が指す場所を示し、その message はテキストと同様にすべての検出結果を含みます。コマンドラインは各検出結果をそれぞれ個別の診断として出力します。

このエントリは、コンパイラ自身の実行が拒否した場合には常に存在します。レンダリング中、またはレンダリング前(グラフの合成時、あるいは Component や Feature が宣言するアサーション時。後者はドキュメントを指さないため、そのエントリは Aggregate を示します)です。成功したビルドはこれを持たず、コンパイラの開始前に実行されるチェック(lockfile、Manifest のマッピング、Release の依存関係)で拒否されたビルドも持ちません。その拒否はテキストのみです。作成者が機密として宣言した値は、コンパイラが拒否を発生させる時点で拒否から伏せられるため、エントリとテキストには cli-build と端末が示すものと同じ内容が含まれます。詳しくは宣言された値について拒否が述べることを参照してください。

Release が依存するものの解決

pull は、Release のカタログ依存とソース依存をローカルキャッシュに解決し、その Release のロックファイルを書き出します。このツールがこのサーフェスにあるのには、述べておく価値のある理由があります。上記の 2 つの拒否、すなわち固定されていない外部参照を拒んだレンダリングと、ロックファイルが Release の解決結果と一致しなくなったために停止したビルドは、どちらも固定によって解消されます。そして、コマンドの実行を依頼しなければならないアシスタントには、それを自力で解消する手段がありません。何を書き込み、それがどこまで及ぶかについては、アシスタントが事前に確認せずに行えることを参照してください。

release に Release のパスを、絶対パスまたはワークスペースルートからの相対パスで渡します。これはここでの他のすべてのパス引数と同じ取り決めです。workspace_root と catalog_dirs は、build の場合とまったく同じようにワークスペースとカタログの探索を上書きします。どちらも標準入出力経由で接続されたサーバーでは有効です。HTTPS 経由ではこの 2 つの引数は拒否され、パスはプロセスが提供するワークスペース内に解決されなければなりません。詳しくは1 つのプロセス、1 つのワークスペースで説明しています。

デフォルトでは、再解決ではなく照合を行います。 ロックファイルにすでに記録されている固定は尊重され、そのバージョンで取得されます。レジストリがそのバイト列をもう提供していない場合は、黙って固定し直すのではなく拒否されます。固定のない参照(新たに追加されたもの、または手作業でロックファイルから削除されたもの)は新たに解決されて追加されます。解決された依存関係にもう含まれない参照は削除されます。したがって、依存関係の集合が変わらなければファイルは記録されたタイムスタンプも含めてバイト単位で同一のまま残り、固定を何も変更しなかった呼び出しは、後でワークスペースをレビューする誰に対しても差分を生みません。

verify は比較を行い、ロックファイルはそのまま残します。 記録済みのロックファイルを、上記の照合する呼び出しが現時点で行う解決と照らし合わせます。その際、記録済みの固定をその呼び出しとまったく同じように尊重します。ずれがある場合、または比較対象のロックファイルがない場合は失敗として返ります。このため、何かがロックファイルを書き換える前に固定が必要かどうかをアシスタントが確認する手段となります。その呼び出しが記録するものは何も書き込まれません。ロックファイルも、その横に記録されるプラグインの識別情報も、entity.lock も書き込まれません。一方、コンテンツキャッシュは、その呼び出しが読み込み、満たすのとまったく同じように読み込まれ、満たされます。また、ロックファイルが記録しているツールチェーン、すなわちファイルを書き出したコンパイラのバージョンと、そのコンパイラが同梱していた各コアプラグインのバージョンも報告します。これは監査のために報告されるもので、実行中のバイナリとは決して比較されません。ツールチェーンはロックファイルが固定するものの一部ではなく、それを検査すると間接的にコンパイラを固定することになるためです。ツールチェーンの違いはずれではありません。

upgrade_targets は指定した参照だけを再解決し、それ以外は何もしません。 1 つ以上のエンティティ URI を、作成時の素の形式で渡します。バージョン付きの形式ではなく core/database のように指定します。指定された各固定は破棄され、利用可能な最も高いバージョンに再解決されます。その他の固定と記録済みの外部入力はすべて変更されずに保持されます。記録済みの固定にも設定済みのアタッチメントにも一致しない URI は、無視されるのではなく拒否されます。

すべてを一度に再解決する引数は、意図的に用意していません。 コマンドラインにはその形式があり、ロックファイル全体を破棄してから現在のレジストリの状態をもとに再解決します。このサーフェスにはその引数が存在しないため、そうした呼び出しは受け付けられた後に拒否されるのではなく、そもそも組み立てることができません。プロトコルのストリームを見ている人はいないため、全体の破棄を確認する人がいないからです。必要な場合は、標準入出力でのみ、cli-pull がそのコマンドを実行します。これは人がその場にいるサーフェスです。HTTP 経由でこのサーバーに接続する呼び出し元は、代わりにホストのターミナルでそれを実行します。verify は upgrade_targets と組み合わせることはできません。一方はロックファイルをそのまま残し、もう一方は書き換えるからです。また、pin_sources とも、その値にかかわらず組み合わせることはできません。この引数は、解決時に entity.lock に欠けている固定を記録するか、それを理由に拒否するかを決めるものですが、比較は entity.lock を書き込まないため、どちらも行わないことになるからです。いずれかの組を送った呼び出しは、何かが解決される前に、その組を示す文とともに拒否されます。ツールが公開するスキーマにはこの 2 つの排他条件は記載されていません。スキーマを表示するクライアントが、それを verify を送る必要があるという要件として読み取る可能性があるためです。クライアントは拒否によってこれらを知ることになります。コマンドラインとデーモンも同じ組を拒否します。

結果は、何かが解決されたことだけでなく、何が解決されたかを示します。 結果には、書き込んだ lockfile または比較対象とした lockfile が含まれます。resolved は、解決が到達したすべての参照について、それぞれが解決されたバージョン、解決が記録する場合には作成者が書く kind、そしてその source を示します。これは今回の実行がその参照をどこから取得したかを、同じ解決について aggrega pull --detail が出力する語で表したもので、fetched-fresh、cache-reuse、local、in-binary、external のいずれかです。さらに、処理後に lockfile が保持するソースアーティファクト、外部入力、信頼されたプラグイン ID の数と、diagnostics が含まれます。これは解決自身による経過の記録で、各行を出力した順に並び、どのピンが再利用されたか、どの署名が検証されたか、どのバージョンが取り下げ済みとしてスキップされたかを示します。これらの行はコマンドを実行するとターミナルに表示されますが、ここでは回答に含まれます。ターミナルを読まない呼び出し元には、ほかにそれらを受け取る手段がないためです。verified は比較の場合にのみ存在するため、その有無によって書き込んだ実行と比較だけを行った実行を区別できます。source はこのマシン上での今回の実行を表すものなので、lockfile はそれを記録せず、Release の依存先を報告する describe もそれを示しません。

拒否も同じフィールドで回答し、実行が進んだところまでが埋められます。 解決が計算された後であれば、判定にかかわらず resolved が含まれます。とりわけずれの判定ではそうです。これは、呼び出し元が何を変更するかを判断しなければならない拒否だからです。それより前の時点での拒否、たとえば解決できない Release パスなどは、修正内容をテキストとして含み、解決は含みません。含めるべき解決が存在しないためです。

固定は完全でも外部入力が完全でない場合、呼び出しはそれでも成功し、その旨を伝えます。 Release がどの外部入力を使用するかを調べることはレンダリングであり、レンダリングは依存関係の固定がすでに正しくディスク上にある状態で失敗することがあります。呼び出し全体を失敗と報告すると、正しい作業をやり直すよう伝えることになります。そのため、代わりに成功した結果に incomplete_external_inputs が設定され、何が停止したかを示します。依存関係の固定は完全ですが、外部入力の固定は完全でない可能性があります。

これはここで最も遅いツールであり、照合による何もしない実行も高速な経路ではありません。 解決は、依存関係の集合が変わっていないことを確かめるために全コストを払います。そのため、何も書き換えない呼び出しも初回の解決と同じだけのコストがかかります。小さな Release でもミリ秒ではなく秒単位であり、依存関係の集合の大きさに応じて増加します。verify は 2 つの形のうち安価なほうです。比較では、書き込む実行が行うコンポーネントごとのソースの探索を省略するためです。クライアントが呼び出しごとのタイムアウトを課している場合は、このツールに対して確認してください。後述する進捗の通知を求めると、呼び出しが終わるまで何も届かないのではなく、実行中に何かが届くようになります。これはクライアント、または HTTP 経由で接続するサーバーとの間にあるものでのアイドルタイムアウトには対処できますが、1 回の呼び出しにかかる合計時間の上限には対処できません。

読み取る入力の pin を entity.lock が記録していないエンティティは pull を拒否させ、その拒否は pin を記録するステップを示します。 Release がカタログディレクトリから構築する Recipe または FeatureRecipe のうち、完全に書き出されたリモートソースを読み取るもの、または artifacts を通じてファイルをインポートするものは、それらの pin をすでに自身の隣に持っていることが想定されます。その作成者は後述の pin でそれらを記録します。pin_sources は、拒否する代わりに、そのようなすべてのエンティティについて作成者に代わってこのステップを実行し、それぞれの隣に entity.lock を書き込むようこの呼び出しに求めます。これは pin ツールが実行するのと同じステップであり、同じバイト列を書き込みます。省略するとワークスペースの pin_sources_at_pull が決定します。送信するとどちらの方向にも決定するため、pin_sources: false は pin するよう設定されたワークスペースでも拒否します。解決がカタログディレクトリではなくキャッシュ内で到達したエンティティは、ここに書き込み可能な置き場所がなく、この呼び出しで pin されることはありません。

エンティティ自身の入力を pin する

pin は、Recipe または FeatureRecipe の隣にある entity.lock に、そのエンティティが自身のドキュメント外から読み取るすべての入力のコンテンツ pin を記録します。対象は、座標が完全に書き出されたリモートソースと、artifacts エントリがインポートするファイルです。これは aggrega pin がターミナルで実行するのと同じステップであり、書き込まれるロックはそのコマンドが書き込むものとバイト単位で同一です。entity にエンティティドキュメントを、ここでの他のすべてのパス引数と同じ契約に従い、絶対パスまたはワークスペースルートからの相対パスで渡します。HTTPS 経由では、プロセスが提供するワークスペース内に解決される必要があります。

Release は指定しません。必要ないためです。 座標にテンプレートを含まないソースは、そのエンティティを使用するすべての Release に対して 1 つのアーティファクトを指すため、このステップは Release が提供するものなしにそれを解決して pin します。座標がテンプレートから来るソースはここでは pin されません。それが指すアーティファクトは各 Release が決定し、pull が解決先の各識別子をその Release のロックファイルに pin します。

結果は、このステップがロックに対して何を行ったかを示します。 結果には entity、その kind と name、そして pinnable が含まれます。これは、ロックが記録するものを何も読み込まない kind(Component または Feature)では false になり、その場合エンティティの横にあるものには何も手が加えられておらず、他のフィールドは存在しません。それ以外の場合は、書き込んだ lock、changed(ロックがすでにすべてのピンを記録しており、バイト単位で同一のまま残された場合は false)、removed(エンティティがロックの記録するものを何も読み込まなくなり、そのロックが削除された場合)、そして pins(ピンの種類ごとに 1 エントリで、その後ロックが保持する数を示す)が含まれます。dry_run を指定すると、ステップが書き込むはずのロックを content として返し、エンティティの横には何も書き込みません。入力は通常とまったく同じように解決されるため、コンテンツキャッシュはそれでも満たされます。

ワークスペース内に書き込み、エンティティのソースが指すホスト(チャートリポジトリ、Git ホスト、URL)に到達します。 そのため HTTP 経由では、pull を許可するスコープを持つ認証情報には許可され、読み取りしかできない認証情報には拒否されます。標準入出力では、同じ機能がコマンドを実行する cli-pin としても利用できます。HTTP 経由ではこのツールは存在しません。

長い呼び出しの進行状況を知らせてもらう

呼び出しは、求めれば進行状況を報告し、求めるにはフィールド 1 つで済みます。 呼び出しの _meta に progressToken を入れます。文字列または数値で、値は自由に選べます。これはすべての報告に記述したとおりの形で返され、報告の中で呼び出しを指し示す唯一のものです。報告は何にも応答しないため、id を持ちません。トークンを送らない、または null として送ると何も変わらず、呼び出しはトークンなしの場合と同じように応答されます。それ以外の形のトークンは拒否されます。呼び出しが何かを行う前に、無視されるのではなく、取り得る 2 つの形を示して拒否されます。知らせを求めたのに沈黙で返された呼び出し元には、行動の手がかりがないためです。

届くのは notifications/progress で、トークンと、届くたびに増えるカウントを持ちます。 合計もメッセージもなく、どちらも今後の対応を待つ欠落ではありません。処理が報告するのは別のフェーズに入ったことであるため、合計は捏造するしかなく、文はそのまま渡すのではなくここで作文するしかないからです。増えていくカウントから不確定のインジケーターを描画してください。バーを埋める割合はありません。

HTTP 経由では、実際に何かが報告された時点で初めて、応答はイベントストリームになります。 text/event-stream として提供され、キャッシュしないよう指定され、X-Accel-Buffering: no を含みます。これは、そうしなければ処理が終わるまですべてのイベントを保持し、ストリームを遅い単一の応答に変えてしまう中間装置のためです。各報告は 1 つのイベントであり、呼び出し自身の応答はストリームが閉じる前の最後のイベントです。処理が静かな間、ストリームは一定間隔でコメント行を送ります。これは間にあるものには生きた接続上のバイトとして届き、クライアントには何も届きません。進行状況を求めたものの、何も報告しない処理に到達した呼び出しは、引き続き 1 つの JSON オブジェクトで応答されます。ストリームを開くのはトークンではなく最初の報告だからです。

ストリームでは、ステータスコードではなく最後のイベントから結果を読み取ってください。 ステータスとヘッダーはストリームが開いたとき、つまり処理が終わる前に書き込まれるため、報告した後に拒否する呼び出しは、すでに送信されたステータスのもとで最後のイベントとして拒否を伝えます。ストリームの途中で接続を閉じると処理は終了し、それ以上何も書き込まれません。これは How a call ends が他のすべての呼び出しについて説明しているとおりです。

標準入出力では、報告は応答行の前の行として送られ、そのストリーム上の他のすべてのメッセージと同じ形式(1 行に 1 つの JSON オブジェクトを、書き込まれた順に)でフレーム化され、その後に応答行が続きます。どちらのトランスポートでも、呼び出しが終わった後には何も報告されません。

ここで報告を行うのは、Release の依存関係の解決です。 pull は、解決がフェーズに入るたびに報告します。build は、auto_pull を送った場合、またはワークスペース自身の設定がその中のすべてのビルドに解決を求めている場合に、先に解決を行うときだけ報告します。報告はそのステップに属するためです。すでに保持している pin からレンダリングするビルドは何にも到達せず何も報告しないため、その呼び出しのトークンは応答のされ方を何も変えません。また、どの呼び出しも、その処理が入って待機する各ステップ — レジストリの読み取り、アーティファクトやドキュメントバンドルの取得、プラグインの初回コンパイル — を報告します。これらは、コマンドラインがスピナーの横に表示するステップです。処理がこれらのどれも待たない呼び出しは何も報告しません。これはエラーではなく無害であり、応答はトークンなしで受け取るものと同じです。

ドキュメント内のある位置にどの接続が書かれているかを問い合わせる

connection-at-position は、上の 2 つのツールのうち接続を扱う側に先立つ問いに答えます。グラフ上のノードではなくドキュメント内の位置を手にしている場合、たとえば Aggregate や Release で見ている行がある場合に使います。file にはドキュメントを、ワークスペースルートからの相対パスまたは絶対パスで渡します。これは insertion-point と同じ方法でディスクから読み込まれます。position には、どちらも 0 から数える line と character を渡します。単位は position_encoding が指定するもので、insertion-point がこの引数を読むのとまったく同じです。さらに、コンパイル済みグラフに接続が記録されている release を渡します。Aggregate 内の位置であっても Release は必須です。グラフノードと接続は、コンパイル済みグラフの上にしか存在しないためです。

回答は 2 つのうちどちらか一方です。位置が接続のエントリ上にある場合、回答は graphNode と connection(その socket、alias、および位置が読み取られた document)を含みます。これらは、attach-candidates が graph_node と release とともに受け取るものそのものであり、attachment-container がその接続上のアタッチメントの置き場所を指定するために受け取るものでもあります。そのコンテナは、位置が含まれていたまさにそのエントリの内側にあります。それ以外の場合、回答は閉じた集合から取られる noConnectionReason を含みます。no-connection-entry(位置がアタッチメントを書くどのエントリ上にもない)、feature-created-connection(位置が、Feature が引いた接続に対する Release のエントリ上にある)、または unknown-connection(位置が、コンパイル済みグラフに存在しない接続に対して Release が書いたエントリ上にある)のいずれかです。読みやすい形式の回答では、理由を文章で述べます。

エントリ内のどこにある位置も、そのエントリの内側です。エイリアス上、その target 上、その features の内側のいずれも該当し、エントリが入れ子になっている場合は最も内側のエントリが優先されます。ソケット自体のキー上、つまりその下のエイリアスより上にある位置は、どのエイリアスの内側でもありません。対象となるエントリは、コンパイル済みグラフが記録しているものです。Aggregate では、コンポーネントが引くすべての接続について、そのコンポーネントが記述されたドキュメント内で接続のエイリアスの下にあるエントリが該当します。インポートされたモジュールが提供するコンポーネントの場合、それはそのモジュール自身のドキュメントです。Release では、Release が書くすべてのエッジごとのエントリが該当します。ターゲットのリストとして書かれた接続や、Feature 自身の依存ブロックが引く接続には、アタッチメントを書くエントリがありません。キーが接続かどうかを、その名前から判断することはありません。

回答するだけで終わります。 どのファイルにも何も書き込みません。ワークスペース内にないドキュメント、読み込めないドキュメント、または整形式の YAML ではないドキュメントは、insertion-point の場合と同様に、変更すべき点を示す失敗結果として返されます。line または character が欠けている位置や、3 つ以外の position_encoding も同様です。

アタッチメントがどのコンテナに属するかを問い合わせる

attachment-container は、候補判定の回答と挿入位置の間にある問いに答えます。ノードに何をアタッチするかは決まっていても、ファイルのどこに書くかを問い合わせる前に、どのファイルのどのコンテナかを知る必要があります。graph_node(コンパイル済みグラフ上のノード ID で、グラフがキーとする形のもの)と、そのグラフを持つ release を渡します。どちらも必須です。ノード ID は 1 つの Release のグラフのキーであり、その Release なしでは意味を持ちません。

そのパスを自分で組み立てないでください。 ノードの ID とそれを囲むサブシステムのパスは、どちらも各部分の間をドットで区切って書かれます。しかしドットは作成者が入力する名前の中でも有効な文字であるため、ドキュメントの外からは、構造上のドットと名前の中のドットを区別する方法がありません。自分で組み立てたパスは正しく見えても誰も書いていないキーを指し、続く編集は拒否されずにそのキーを作成してしまいます。さらに、ノード ID には囲んでいるサブシステムの痕跡がまったく残りません。subsystems.billing.subsystems.payments の中で作成された component は、トップレベルの component とまったく同じく ledger というキーになります。コンテナは問い合わせてください。

回答には、対象のノードである node、そのノードが作成されたドキュメントである file、そしてそのドキュメントのルートからの構造パスをセグメントのリストとして表した container(["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"])が含まれます。連結した文字列ではなくリストであるのは意図的です。連結したパスは受け取った側が再び分割しなければならず、上記の曖昧さが 1 回の呼び出し後に再び持ち込まれることになります。file と container はそのまま insertion-point に渡してください。

file は既に知っているものではなく、回答の一部です。インポートされたモジュールが提供したノードは、そのモジュール自身のドキュメントの中で、モジュールが付けた名前で作成されています。そのため、ファイルもコンテナの最後のセグメントも、送ったものとは異なります。

ノードが引く 1 つの接続へのアタッチメントには、connection を追加します。その socket、alias、document を指定します。どちらのドキュメントにも接続が存在しうるため、ここではこれが必須です。aggregate の場合、答えはノードが記述されたドキュメント内にある接続自体のエントリで、その features ブロックが末尾になります。Release が引いた接続はそこにエントリを持たないため、拒否されます。release の場合は、ノードに対する Release のエントリの下にあるエッジごとのエントリ(["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"])になります。これは Release がそのエッジごとのエントリをすでに書いているかどうかにかかわらず報告されるため、insertion-point がまだ書く必要のあるキーを示します。ノードのエントリを書いていない Release は拒否されます。ノードをどこに配置するかは、このツールが決めることではないためです。Feature が引いた接続は、どちらのドキュメントでも拒否されます。

回答するだけで終わります。 アタッチメントを作成せず、どのファイルにも何も書き込まず、テキストも組み立てません。何をアタッチできるかも判定しません。それは attach-candidates の役割です。グラフが持たないノードや、ドキュメントが記録されていないノードは、空のフィールドを持つ回答としてではなく、変更すべき点を示す失敗結果として返されます。

ドキュメント内でエントリを置く場所を特定する

insertion-point は、候補の回答に続く問いに答えます。何を付与または接続するか(what)は決まっており、次にファイル内のどこに書くかを知る必要があります。このツールは位置とインデントすべき桁を返すので、ドキュメントを自分でパースせずに編集を適用できます。読み取るのは特定の種類の形ではなくドキュメント自体の構造であるため、describe-capabilities は絞り込んだどのエンティティ種類の下にもこのツールを掲載します。

file — ドキュメントで、ワークスペースのルートからの相対パスまたは絶対パスで指定し、ワークスペース内にある必要があります。ワークスペース外へ通じるリンクを経由して到達するもの(ファイル自体へのリンクでも途中のディレクトリへのリンクでも)はワークスペース内とはみなされず、どちらのトランスポートでも拒否されます — と、container(ドキュメントのルートからエントリを入れるコンテナまでの構造パスで、各要素はマッピングのキーまたは 10 進数で書いたシーケンスの位置)を渡します。

コンテナのパスは呼び出し側が指定します。 このツールはドキュメントの構造を読み取るだけで、名前や型、意味しているように見える内容から、何がどこに属するかを推測することはありません。どのキーかを指定すると、このドキュメントでそのキーのエントリがどこに入るかを答えます。つまり、パスのどのセグメントがファイルにすでに存在するか、そのエントリが置かれている桁、最も内側のブロックが到達する最後の行です。コンパイル済みグラフのノードへの Feature の付与であれば、そのキーを自分で知っている必要はありません。上記の attachment-container がドキュメントとコンテナを報告するので、両方をそのままここに渡します。

回答には、幅ゼロの position(line と character はどちらも 0 から数えます)、書き込む桁である entryIndent と indentStep、そしてこのドキュメントにまだ存在しないコンテナのキーを外側から順に並べた missingContainerKeys(エントリより先に書き込みます)が含まれます。entryShape はコンテナが mapping と sequence のどちらを保持するかを報告し、コンテナがまだ存在しないか何も保持していない場合は、ドキュメントが何も示していないため unknown を報告します。その場合、形は呼び出し側が選びます。indentStepMeasured は、ステップがこのドキュメント自体の入れ子から測定されたものか、入れ子をまったく持たないドキュメント向けのフォールバックかを示します。precededByLineBreak が設定されている場合は、テキストを改行で始めてください。位置はエントリの直前の行の末尾にあり、ファイルが改行で終わっているかどうかにかかわらず範囲内で、すでに書き込まれたバイトを乱しません。コンテナが存在すると思われる場合でも missingContainerKeys を確認してください。先行すべきキーを書かずに位置を適用すると、パースできなくなったドキュメントが生成されます。

position_encoding は、報告される文字オフセットを測る単位を指定します: utf-8、utf-16、utf-32 のいずれかです。このプロトコルのどちらのリビジョンも単位をネゴシエートしないため、ここでは引数になっており、デフォルトは utf-16 です。これはクライアントが何もネゴシエートしないときにエディタのセッションが採用する単位なので、何も指定しない呼び出し元にはどちらのインターフェースでも同じ回答が返ります。3 つのいずれでもない値は、黙ってデフォルトに置き換えられるのではなく拒否されます。ある単位で測ったオフセットを別の単位で測るバッファに適用すると、ASCII 以外の最初の文字でドキュメントが破損するためです。

回答するだけで終わります。 ファイルには何も書き込まず、エントリのテキストを組み立てることも、編集を適用することもありません。テキストの組み立てと適用するかどうかの判断は呼び出し側が行います。エントリを置ける場所を指していないリクエストは、何を変更すべきかを示す失敗結果として返ります。たとえば、ワークスペース内にない、読み取れない、または整形式の YAML ではないドキュメント、セグメントを持たないか空のセグメントを含むコンテナパス、内部に何も追加できないスカラーを通るパス、フロースタイルで書かれたコレクションに到達するパス(追加すると行を加えるのではなく作成者がすでに書いたバイトを書き換えることになります)、またはブロックシーケンスをそのインデックスではないもので指すパスです。編集を自分で適用するより適用してもらいたい場合は、ドキュメントに 1 つの限定された編集を適用するがそれを行うツールです。

ドキュメントに範囲を限定した編集を 1 つ適用する

edit-document は、上の 2 つのツールが特定した場所に編集を適用します。1 回の呼び出しで、1 つのコンテナの下に 1 つのエントリを追加するか、1 つのスカラーを設定します。それ以外のことはできません。指定したドキュメントをワークスペース内で書き込むため、HTTPS 経由では aggrega:workspace-write が必要です。aggrega:read のみを持つ呼び出し元にもツール一覧には表示されますが、その呼び出し元による呼び出しは、そのスコープを示して拒否されます。

編集は edit で指定し、その種類は閉じた集合です。 add-component は components コンテナの下にコンポーネントインスタンスを追加します。attach-feature は指定したノードに Feature をアタッチします。wire-edge はそのノードのソケットの 1 つの中で接続を配線します。set-value はそのノードに値を 1 つ設定します。この 4 つ以外の名前は解釈されずに拒否されます。削除する編集、既に書かれたブロックを置き換える編集、何かを並べ替える編集、指定したバイト列をそのまま書き込む編集は存在しません。したがって、これはファイル書き込みツールではなく、その用途には使えません。

file にはドキュメントを渡します。ワークスペースのルートからの相対パスまたは絶対パスで、ワークスペース内にある必要があります。ワークスペースの外にあるもの(記述どおりの場合も、外へ出るリンクを経由する場合も)は、どちらのトランスポートでも拒否され、何も読み書きされません。node にはドキュメントのルートからの構造パスをセグメントのリストとして、name にはエントリを書き込むキーを、value にはそのエントリが持つ内容を渡します。node がリストであるのは、attachment-container が 1 つのリストで答えるのと同じ理由です。作成者が入力する名前の中ではドットが有効なため、連結したパスでは誰も書いていないキーを指してしまい、エントリが拒否されずにそこへ作成されることがあります。add-component では、追加されるエントリがノードそのものであるため、パスは components コンテナ自体を指します。他の 3 つでは、パスは編集の対象となるノードを指し、コンテナは編集の種類から決まります。socket は wire-edge の場合に読み取られ、それ以外では無視されます。value の意味は edit によって決まります。エントリが要求するエンティティ、接続の参照先ノード、または値として設定されるスカラーのいずれかです。これはそれ自体の型を持つ JSON 値であるため、数値は数値のまま、引用符で囲んだ数字はテキストのままとなり、省略した場合は何も設定されません。マッピングやシーケンスは拒否されます。ブロックの書き込みはこれらの編集に含まれないためです。

編集が触れないバイトはすべてそのまま残ります。 ドキュメントはコンテナとそのブロックが終わる行を特定するためだけに解析されるため、コメント、空行、引用スタイル、折り返しスカラーとリテラルスカラー、末尾改行の形はすべて引き継がれます。また、ネストの段幅は押し付けられるのではなく、ドキュメント自身のインデントから測定されます。同じドキュメントに対する同じリクエストは、同じバイト列を生成します。

結果は、手で入力することもできたはずのドキュメントでなければならず、書き込みはその条件で制御されます。 組み立てられたドキュメントはそのドキュメント自身の種類のスキーマに照らして検査され、それに合格した場合にのみディスクに書き込まれます。スキーマが拒否するものを生成するリクエストは、スキーマが受け入れないプロパティとその位置を示して拒否され、ファイルはバイト単位で元のまま残ります。したがって、拒否された編集は一度も試みられなかった編集と区別がつかず、修正したリクエストを元のドキュメントに対して再試行できます。要求した内容を既に持つエントリが存在する場合は何も行われません。同じ名前で別の内容を持つエントリは、置き換えられずに拒否されます。

回答には、エントリが配置された構造パスである container、この編集が新たに作成する必要があったコンテナの階層である created_containers(最も外側から順に並び、パス全体が既に存在していた通常の場合は空)、ディスクに書き込まれたドキュメントである written(何も書き込まれなかった場合は空)が含まれます。created_containers を確認してください。ドキュメントになかった 2 つのネストしたブロックを黙って書き込んだ編集は、それ以外の方法では、自分で書いたブロックにエントリを 1 つ追加しただけの編集と区別がつきません。

dry_run は書き込み以外のすべてを行います。 編集後のドキュメントが content として返され、何も作成されず、written は空になります。これは、保存前に結果を作成者に提示するクライアントのためのものです。それ以外の動作はスキーマによる制御も含めて書き込み時と同じであるため、書き込み時に拒否されるリクエストはこのモードでも拒否されます。指定しない場合はドキュメントが書き込まれ、content は含まれません。その時点でドキュメントはディスク上にあり、written がそれを示すためです。

配線するものが意味的に許容されるかどうか、つまりソケットがプロデューサーの宣言するものであるか、Feature の適用条件が満たされているかは、ここでは判断されません。それに答えるのは validate です。

標準入出力では、同じ機能に cli-edit-document としてもアクセスできます。これはコマンドを実行し、その出力テキストを返します。HTTP ではそのツールは存在せず、そこではこのツールがこの機能にアクセスする手段となります。

外部の記述をドラフトのエンティティに変換する

import は、別のツールが生成した記述(たとえばエージェントビルダーからエクスポートされたフロー)を、Aggrega のドラフトのオーサリングファイルに変換します。このサーバーが提供するワークスペースにそれらのファイルを書き込むため、HTTPS 経由では aggrega:workspace-write が必要です。aggrega:read のみを持つ呼び出し元はツール一覧でこのツールを見つけられますが、その呼び出しはそのスコープを示して拒否されます。

変換するファイルまたはディレクトリを source に渡します。これは絶対パス、またはワークスペースルートからの相対パスで、このインターフェイスの他のすべてのパス引数と同じ取り決めに従います。HTTPS 経由で到達するサーバーでは、そのサーバーが提供するワークスペース内で解決されます。

ディレクトリは、そのインポーターのファイルパターンが選択するファイルだけが正確に読み込まれます。 チャートやプロジェクトはディレクトリであり、source でディレクトリを指定できます。その場合インポーターには、そのシグネチャが宣言するファイルパターンのいずれかが選択する、任意の深さにあるそのディレクトリのファイルが、ディレクトリ内のパスをスラッシュ区切りで書いた名前で、ソート順に渡されます。あわせて、その plugins.importer アタッチメントが with.sources に指定するファイルがベース名で渡されます。同じ名前のディレクトリ内ファイルと with.sources のファイルがある場合は、一方が他方を隠すのではなく拒否されます。ファイルパターンを宣言しないインポーターは 1 つのファイルを読み、ディレクトリは条件 An importer that declares no file patterns is handed a directory(ファイルパターンを宣言しないインポーターにディレクトリが渡された) のもとで拒否します。また、パターンが選択するファイルを 1 つも含まないディレクトリも拒否されます。ディレクトリはどこにあってもその内部に限定されます。インポートが読むファイルの中、またはディレクトリへのリンクのうち、その外へ出るものは何かを読む前に拒否され、ディレクトリへのリンクの中に入ることはありません。詳細は A directory you import に記載されています。HTTPS 経由で到達するサーバーでは、ディレクトリ自体がワークスペース内で解決されるため、そこから読まれるすべてのファイルもワークスペース内になります。

インポーターは、ワークスペースのカタログが保持するもの、またはコンパイラのコアインポーターのいずれかです。 変換は、ソースの形式を公開しているインポーターのプラグインが行います。これはワークスペースのカタログが保持するもの、またはコンパイラのコアインポーターのいずれかで、コアインポーターはカタログエントリなしにすべてのワークスペースでその形式を処理します。このツールはインポーターを選択して実行し、生成されたものを書き込みます。uri がインポーターを識別子とバージョン(aggrega plugin add importer が書き込む形式の importer/<name>:<version>)で指定する plugins.importer アタッチメントは、そのインポーターをアタッチします。そのインポーターがソースの形式を公開している場合、他のインポーターが同じ形式を公開していても、そのバージョンのそのインポーターが実行され、そのアタッチメントの with のソースと設定が渡されます。これは他のインポーターには渡されません。複数のインポーターがその形式を公開し、そのうちどれか 1 つがアタッチされていない場合(たとえば同じ形式についてコアインポーターと、カタログが保持する別名のインポーターがある場合)、呼び出しはそれらを示して拒否されます。これは Configuration の説明どおりです。指定した形式をどのインポーターも公開していない場合は、汎用的な不一致として解釈を委ねるのではなく、インポーターが公開すべきケイパビリティ(Langflow のソースなら import:langflow)を示して拒否されます。これはカタログに追加するインポーターが宣言するものです。

サーバーのマシンが保持していないコアインポーターは、それを必要とする最初のインポートによって一度だけ取得されます。 インポートは、提供されるワークスペースのデフォルトレジストリからそれを取得し、コンパイラのリリースが公開するモジュールと一致することを確認し、pull が取得したプラグインを検証するのと同様に、そのレジストリの信頼ポリシーのもとで署名と使用するホスト関数を検証して、ワークスペースのコンテンツキャッシュに保存します。以降のインポートはすべてそこから読み、どのレジストリにもアクセスしません。それ以外には何も書き込まれません。ロックファイルも、信頼済みプラグインの記録も書き込まれません。HTTPS 経由では、これがこのツールの呼び出しによってサーバーが接続しうる唯一のレジストリであり、Which credentials a call spends がレジストリの読み取りに定める範囲に従います。このレジストリはこのサーバーが提供するワークスペースのデフォルトレジストリなので、そのワークスペースに設定されたものです。呼び出しの中でレジストリを指定したり資格情報を渡したりすることはなく、取得にはこのホスト自身のログインと信頼ポリシーが使われます。ツールが到達するのは引き続きワークスペースだけなので、呼び出しに必要なのは aggrega:workspace-write だけです。取得が残すのは、ワークスペース自身のコンテンツキャッシュ内のモジュールです。検証に失敗したモジュールは、ターミナルで実行した場合と同様に拒否され、何も保存されません。モジュールを取得できない場合(ワークスペースがオフライン、レジストリに到達できない、またはレジストリがそれを保持していない場合)、呼び出しは A plugin’s .wasm is not on this machine(プラグインの .wasm がこのマシンにない) のもとで拒否され、インポーター、そのバージョン、およびそのモジュールをマシンに配置する方法が示されます。

ワークスペースがカタログフォルダーを指定していない場合、インポートはそのデフォルトレジストリが公開するカタログを読み込みます。 workspace.catalog_dirs、AGGREGA_CATALOG_DIRS、ルートのいずれもカタログフォルダーを指定していないワークスペースは、標準ライブラリのカタログを 1 つの署名付きスナップショットとして読み込みます。このスナップショットは、提供対象のワークスペースのデフォルトレジストリ上の catalog/snapshot にあります。これはコアインポーターの取得元と同じレジストリで、同じ条件でアクセスされ、呼び出しの中にレジストリを指定したり資格情報を運んだりするものは何もありません。スナップショットの取得は 1 回だけです。その署名はそのレジストリの信頼ポリシーのもとで検証され、スナップショットはワークスペースのコンテンツキャッシュに保持されて、そこでカタログフォルダーとして、そのダイジェストに固定された状態で読み込まれ、再びレジストリに要求されることはありません。呼び出しがどのスナップショットを読み込むか:upgrade を指定した場合は最新のもの。そうでなければ出力ディレクトリ内の記録が示すもので、マシンが保持していない場合はそのダイジェストによって取得されます。そうでなければワークスペースが最後に最新として取得したもの。そうでなければ最新のものです。インポートが書き込む記録は読み込んだスナップショットをそのダイジェストで示すため、後で同じディレクトリにドラフトする呼び出しは同じカタログを読み込みます。オフラインでは、スナップショットを取得する必要がある呼び出しは、実行すべきものを示して拒否されます。また、どのスナップショットが最新かを示せるのはレジストリだけなので、マシンが何を保持していても upgrade は拒否されます。スナップショットを公開しないレジストリでは、インポートはカタログなしになり、diagnostics 内の warn エントリがそのことを示します。カタログフォルダーを指定しているワークスペースはそのフォルダーに対してインポートし、スナップショットを取得しません。そこでは upgrade は何も変えません。

format を省略すると、形式はインポーターが宣言するシグネチャによって認識されます。カタログのインポーターもコアインポーターも同様です。各インポーターの Plugin エンティティがシグネチャを記録しています。ソースを読む構文、シグネチャが適用されるファイル名、およびパース結果のツリーが持つべき、または持ってはならないパスです。ソースは、その名前に適用されるシグネチャが読む構文ごとに一度、ワークスペースのカタログがその構文に提供するパーサー(カタログがパーサーを提供しない構文の場合はコンパイラ自身が持つパーサー)でパースされ、シグネチャが一致する唯一のインポーターの形式が使われます。その後インポーターは同じパーサーでソースを読みます。コアインポーターのシグネチャはファイルを JSON または YAML として読み、ファイルを指定しないものは JSON として読みます(Dify インポーターのものは YAML)。そのため、単独でインポートされるファイルの認識は両方で読み、ワークスペースのカタログにパーサーを必要としません。コンパイラは JSON と YAML のパーサーを持ち、カタログが提供するパーサーがあればそれが代わりに使われます。ディレクトリも、そのファイルに対して同じ方法で認識されます。各シグネチャは、そのパターンが選択するファイルに対して試され、パターンを宣言しないシグネチャはどのファイルにも適用されません。認識が読むのは指定したファイル(ディレクトリの場合はシグネチャのパターンが選択するファイルのみ)だけで、ネットワークにはアクセスしません。どのシグネチャにも一致しないソースは、条件 No importer recognises the source(どのインポーターもソースを認識しない) のもとで、format を求め、インポーターが公開する形式を示して拒否されます。ディレクトリの場合は、そのファイルの 1 つを単独で source として送るか、インポーターがファイルパターンを宣言している format を送るよう求め、それらの形式のみを示します。複数の形式のシグネチャに一致するソースは、条件 More than one importer recognises the source(複数のインポーターがソースを認識した) のもとで、それらを示して拒否されます。どちらの場合も、推測したインポーターに渡されることはありません。いずれの場合も、format を送って形式を直接指定します。ディレクトリの場合は、インポーターがファイルパターンを宣言している形式を指定します。ディレクトリはそれらのパターンを通じてのみ読まれるためです。空の format は、省略した場合と同じには扱われず拒否されます。これらは異なるリクエストだからです。

target を送ると、ドラフトされた Release が 1 つの provider に対してビルドする Manifest がドラフトされます。 target は provider の capability、つまり Recipe の spec.capability が結び付く語(compose や helm など)であり、aggrega import の --target と同じもので、同じ操作によって組み立てられます。そのため、呼び出しとコマンドは同じソースから同じファイルをドラフトします。ドラフトが必要とする component の型と feature の型ごとに(ドラフトされた Aggregate の component、それらの接続とそのサブシステム、それが構成するカタログの Aggregates、ドラフトされた Release のアタッチメントについて)、ドラフトで最初に宣言された順で、インポートはワークスペースのカタログから、その型を実装しその capability に結び付く Recipes(feature の型については feature recipe)を探します。ちょうど 1 つある場合(そのいずれかの複数バージョンは 1 つとして数えます)、Manifest はその型を、バージョンなしの capability 修飾名(compose/postgres など)でそれに対応付けます。この名前は最初の pull が lockfile に、利用可能な最も高いバージョンで固定します。名前の異なるものが複数ある場合は、型そのものにちなんで名付けられたもの(core/datastore/postgres に対する helm/postgres など)に対応付けます。1 つもない場合、または複数あってもそのように名付けられたものがない場合、その型は対応付けられないまま残り、diagnostics の warn エントリがその型と理由(複数ある場合はそれぞれの名前)を示します。そのため、ドラフトのビルドは対応付けが追加されるまで、その型の各インスタンスまたはアタッチメントを示して No Recipe is mapped for a component or feature instance(component または feature のインスタンスに Recipe が対応付けられていません) のもとで停止します。importer 自身が Manifest をドラフトし、あるインスタンスのレンダリングに使う Recipe や、複数ある feature recipe のうちの 1 つを選ぶ場合、importer が書いた対応付けのうち、カタログがその型と capability に対して提供するものはそれぞれ保持され、それ以外は warn エントリとともに破棄されます。importer が残した型は上記のとおり対応付けられます。Manifest はドラフトされた Release の隣に manifest.yaml としてドラフトされ、Release と同じ名前とバージョンが付けられます。また Release の spec.manifest はその名前に設定されます。importer がその位置に書いたコメントは置き換えられ、Release のそれ以外の部分は変わりません。すでに Manifest を指定している Release はそのまま残されます。インポートが Release をドラフトしない場合、Manifest は Aggregate の隣にその名前とバージョンでドラフトされ、info エントリがそれを参照するものがないことを示します。Manifest と編集された Release は他のドラフトと同じく、written に含まれ、記録に載り、dry_run のもとでは返されます。カタログ内のどの Recipe も結び付かない target は、importer の実行前に An import’s target names a capability no Recipe in the catalog binds to(インポートの target が、カタログ内のどの Recipe も結び付かない capability を指定しています) のもとで拒否されます。その際、送られたとおりの target と、カタログの Recipes が結び付く capability が示され、何も書き込まれません。target を省略すると Manifest はドラフトされません。ただし sync のもとでは、以前のインポートに送られた target に対してドラフトします。空の target は、省略したものとして読まれるのではなく拒否されます。

output_dir を送ると、ドラフトを置くディレクトリを指定できます。 省略すると、ドラフトは呼び出しが解決したワークスペースのルートの下に置かれます。これは、出力先を指定しないときに aggrega import がどこで実行しても書き込む場所であり、language server の aggrega/import がリクエストで出力先を指定しないときに書き込む場所でもあります。出力先は 3 つすべてで任意であり、このサーバーに送るすべてのパスと同じ方法で指定します。HTTP 経由では、このサーバーが提供するワークスペース内のディレクトリを、そのルートからの相対で書きます。ルートの外へ出る値、ルート外の絶対位置、リンクを通じてルートの外へ通じるディレクトリ(そのようなリンクの下にまだ作られていないディレクトリも含む)は、いずれも output_dir を示して拒否され、何も読み書きされません。標準入出力経由では、そこでのすべてのパスと同じく、指定されたとおりに扱われます。相対値は呼び出しが解決したワークスペースルートを基準に解決され、絶対値はワークスペース外のディレクトリを指定でき、そこへは aggrega import --output-dir と同じようにドラフトされます。そこに書き込まれるものは、リンクを解決したうえでワークスペース内(ワークスペース外に指定したディレクトリの場合はそのディレクトリ内)に制限されるため、その中から外へ通じるリンクは拒否され、何も書き込まれません。空の output_dir は、省略したものとして読まれるのではなく拒否されます。標準入出力では、cli-import もコマンドの --output-dir を独自の output_dir として受け取ります。そこでの相対値は、コマンドが実行されるフォルダ、すなわち呼び出しが指定するワークスペースルート、なければサーバーの起動時に与えられたもの、それもなければサーバーが実行されているフォルダを基準に解決されます。

ドラフトされるすべてのパスは、何かが書き込まれる前に出力ディレクトリに照らして検査されます。 その外へ出るパスは、パスとディレクトリの両方を示して拒否され、何ひとつ書き込まれません。同じセット内で自身のパスに問題のなかったファイルも書き込まれません。拒否されたインポートが一部を残すことは、誰も求めていない結果だからです。ドラフトされるパスは利用者からではなく importer プラグインから来るものであり、そのため送られたパスと同じ理由で検査されます。

何かをドラフトするインポートは、すべてドラフトの隣に .aggrega-import.json も書き込みます。これは書き込んだ内容の記録です。送られた場合は送られた target、読み込んだ場合は読み込んだカタログスナップショット、そしてドラフトされた各ファイルと、ドラフトされた Aggregate または Release ではあらゆる深さの各キーが、そこに書き込まれたテキストのダイジェストとともに記録されます。その他のドラフトされたファイルは全体として記録されます。キーのテキストとは、その行、値がキーのマッピングでない場合は値の行、そしてそのキーの直上に同じインデントで書かれたコメント行です。written はドラフトとともに記録を示し、dry_run のもとでは記録は返されるドラフトに含まれます。記録は JSON なので、ワークスペースの YAML ドキュメントを読むものがこれを読むことはありません。

呼び出しが、出力ディレクトリにすでにある Aggregate を上書きすることはありません。 Aggregate はドラフトされた後も作成者が編集し続けるドキュメントです。そのため、ドラフトのいずれかが Aggregate として読めるファイルの上に置かれることになる呼び出しは、そのドラフトとディレクトリを示して拒否され、何ひとつ書き込まれません。dry_run のもとでも同様です。ドライランは書き込みが拒否するものを拒否するからです。ドラフトされるパスにすでにあるその他のファイルは上書きされ、以前のインポートがドラフトし今回はドラフトしないファイルはそのまま残されます。

代わりに sync を送ると、以前のインポートがドラフトしたものをソースに合わせて最新にします。変更するのはインポートが書いたものだけです。target を送らない sync は記録が示すターゲットに対してドラフトするため、以前のインポートがドラフトした Manifest をドラフトします。target を送った sync はそのターゲットに対してドラフトし、その後は記録がそのターゲットを示します。カタログ内のどの Recipe もバインドしない記録済みターゲットは、送られたターゲットと同様に拒否され、その拒否はターゲットが記録済みのものであることを示します。各部分は三つの観点で判断されます。記録が示す、インポートが前回そこに書いた内容、ディスク上の内容、そしてソースが現在ドラフトする内容です。ソースがインポートの前回の書き込みどおりに残した部分は、作成者が編集したかどうかにかかわらず、ディスク上のとおりにそのまま残ります。ソースが変更した部分は新たに書き込まれ、ソースが削除した部分は取り除かれ(ドラフトされたファイルはファイルごと削除されます)、ソースが追加した部分はドラフト内で周囲に位置する部分の隣に追加されます。いずれも、ディスク上の内容がインポートの前回の書き込みと一致し、作成者が追加したものを含まない場合に限ります。それ以外はすべてバイト単位でそのまま残ります。作成者がどこかに追加したキー(パラメータ、Feature、ドラフトされた Component インスタンスの下のものも含みます、別の Component、ドラフトされた Release が作成者に委ねる環境)、ドラフトされたキーの直上に書かれていないコメント、そして記録に載っていないすべてのファイルです。回答の drift は、最新化された各部分(dry_run では最新化されるはずの各部分)をドラフトが示す順に列挙します。各部分は change(added、removed または changed)、file(その部分が含まれるドラフトされたファイル)、key(ドラフトされた Aggregate または Release 内でその部分に至るキーのリスト。部分がファイル全体の場合は空)で表されます。テキストの回答は、aggrega import が標準エラーに書くのと同じ文言で、各部分をそれぞれ一行に <change> <key> in <file> または <change> <file> の形で示します。dry_run での空の drift は、ドラフトがソースと一致していることを示します。dry_run で返されるドラフトは、sync が書き込むはずのファイルと、それに与えるはずの内容です。作成者が編集した部分を変更または削除する sync、作成者がすでに書いた場所に部分を追加する sync、作成者が追加したものを含む部分を削除する sync は拒否されます。その際、該当する各部分とその理由が示され、何も書き込まれません。ドラフトされたキーの直上に書かれたコメントは、そのキーの編集とみなされます。どの記録にも載っていない Aggregate に対する sync はその旨を示して拒否され、記録を読み取れない sync も同様です。インポーターが完了できなかった sync は何も書き込みません。記録がなく、ドラフトされるパスに何もないディレクトリへの sync は、ドラフト全体を書き込みます。sync ではない呼び出しでは、drift は空のリストです。

回答には、指定したとおりの source、ソースの読み取り方を示す format、呼び出しが解決したワークスペースのルートである workspace_root、ドラフトされたパスの基準となるディレクトリである output_dir、ディスクに書き込まれたファイルである written、sync が最新化したものである drift、インポーターが変換できなかった構成要素ごとに一件の diagnostics、インポーターが各ソースノードをどうマッピングしたかを示す decisions、そして halted が含まれます。output_dir は送ったディレクトリ、送らなかった場合はそのルートであり、インポートが実際に使用したものから読み取られます。何も書き込まれない dry_run でも、ドラフトされた各パスはこれを基準とするため報告されます。HTTP 経由では、ルートはサーバーのホスト上の場所であるため、回答がサーバーのファイルシステムについて示すことで説明するとおり、workspace_root は伏せられ workspace_root_withheld が付けられます。output_dir はそれがルートである場合に伏せられて output_dir_withheld が付けられ、それ以外の場合はルートからの相対名(送るパスと同じ形式)で示されるため、ドラフトの出力先は回答から引き続きわかります。インポーターが完了できなかったインポートでも、可能な分はドラフトされます。その場合は失敗としてフラグが立てられ、回答全体を伴って返されます。halted は true となり、実際にディスクに書き込まれたファイルが written に示され、その横の diagnostics が不足しているものを示します。これは何もしなかった呼び出しではなく、保持も破棄もできる部分的な結果です。

decisions は、インポートが推測した箇所を示します。 インポーターがマッピングしたソースノードごとに一件のエントリを、インポーターの順序で含みます。source_node はノードの id、type、params_summary です。candidates は、インポーターがそのノードについて検討した各カタログ Component で、component、score、tier、signals(各シグナルの寄与を table、category、domain_labels、shape、name の下に示します)として表されます。chosen は、選んだ target、それを書いた mode(既存の Component への reference または draft)、および選択の tier です。rationale はその理由、swap_hint は別の選択をする方法です。インポーターが何も検討しなかった場合は candidates が、選択しなかった場合は chosen が、何も書かなかった場合は rationale と swap_hint が省略されます。すべての値はインポーター自身のものであり、候補の採点方法や tier の区切りはインポーターの選択です。そのため、エントリはマッピングについてのインポーターの説明として読んでください。decisions は dry_run でもインポートが停止した場合でも回答に含まれ、何も報告しないインポーターでは空のリストです。テキストの回答は、diagnostics の後に、aggrega import が標準エラーに書くのと同じ文言で各決定をそれぞれ一行に示します。mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score> の形で、score は最良の候補のものです。

dry_run は書き込み以外のすべてを行います。 ドラフトされた各ファイルは、output_dir からの相対パスと内容を伴って drafts の下に返され、何も作成されません。保存前に結果を提示するクライアント向けです。それ以外の動作はすべて書き込み時と同じで、同じソースに対して同じインポーターが同じ diagnostics を報告するため、書き込みで拒否されるソースはこの場合も拒否されます。指定しない場合、ファイルはディスクに書き込まれて written に示され、書き込みを依頼したバイトを繰り返さないよう drafts は省略されます。

ドラフトは、自分で所有し編集を続けていく出発点です。その内容が許容されるかどうか(ソケットがプロデューサーの宣言するものかどうか、Feature の適用条件が満たされているかどうか)はここでは判断されません。それに答えるのは validate です。

標準入出力では、同じ機能に cli-import からも到達できます。これはコマンドを実行し、その出力テキストを返します。HTTP 経由ではこのツールは存在せず、そこではこのツールが機能への到達手段です。

公開、署名、取り下げ

4 つのツールは、他の人が解決する場所に何かを置きます。publish-entity はカタログエンティティをバンドルして公開します。publish-artifact はドキュメントバンドルなどの単独ファイルを公開し、そのバイトは不透明なまま扱われ、エンティティのエンベロープは解析されません。sign-artifacts は公開済みの参照に署名して各署名を添付し、レジストリのトラストポリシーが検証する署名をすでに持つ参照はそのまま残します。deprecate-artifact は署名付きの取り下げマーカーを参照に添付します。いずれかを許可する前に アシスタントが事前の確認なしにできること を読んでください。これらは、その効果がマシンの外に及ぶツールです。

publish-entity は公開するドキュメントである entity を受け取り、Plugin の場合はそのマニフェスト内で公開される実行ファイルである plugin も必要です。publish-artifact は file と、それを公開する name および tag を受け取ります。ここでのパス引数はすべて絶対パスかワークスペースルートからの相対パスで、このサーフェス上の他のすべてのツールと同じ取り決めです。また workspace_root は、標準入出力経由で到達するサーバーにおいて、呼び出しが対象とするワークスペースを指定します。HTTPS 経由で到達するサーバーは workspace_root を拒否し、1 プロセス、1 ワークスペース で説明するとおり、それらの各パスが提供中のワークスペース内に解決されることを要求します。registry は宛先で、既定値はワークスペースに設定されたものです。どちらも送らず既定値も設定されていない場合は、送るべきものを示して拒否されます。sign-artifacts は、パスではなく 1 つ以上のレジストリアドレスである references を受け取り、任意で、同時に署名する数である jobs を受け取ります。省略すると 1 つずつ順に署名され、1 未満の値は送るべきものを示して拒否されます。それぞれの参照は、aggrega sign で説明するとおり、単独の場合とまったく同じように署名されます。deprecate-artifact は、severity と reason を伴う reference、またはバッチファイルを指定する from のいずれかを受け取ります。バッチファイルと一緒に送られた内容引数は破棄せずに拒否します。バッチファイルは独自の内容を提供するため、黙って無視された引数は受け入れられたように読めてしまうからです。

2 つの公開ツールは dry_run を受け取り、レジストリに接続せずに公開で送信される内容を示します。 バンドルを計算し、公開したであろう内容を報告し、beyond_this_machine を false とし、宛先としたであろうものを registries に入れて応答します。publish-entity はさらに、その公開で得られる digest も返します。これは aggrega push --dry-run が出力するものと同じです。提案された公開を、実際に公開する前に誰かに見せるための方法です。署名と取り下げにはこのような形式はありません。どちらも公開済みのものに作用するため、プレビューするものがないからです。

publish-entity は、公開するアーカイブに Windows がそのままでは保持できないエントリが含まれる場合、windows_unusable_entries を返します。これは、大文字小文字を問わず、後に続く拡張子にかかわらず CON、AUX、NUL などのデバイス名を持つ部分を含むパス、またはピリオドや空白で終わる部分を含むパスです。エンティティドキュメント自身のファイル名を最初に、続いてそれが運ぶファイルを、それぞれ示します。該当がない場合は存在せず、ドキュメント単体として公開されたエンティティもこれに含まれます。Windows 上で動作する aggrega はそのようなエントリの展開を拒否するため、Windows のワークスペースではそのバージョンを使用できません。これらは aggrega push が警告するエントリであり、応答のテキストもこれらを示します。これらは何も拒否しません。呼び出しは、dry_run を含め、これらがない場合とまったく同じように続行または拒否されます。

publish-entity は pin_sources を受け取り、バンドル前にエンティティに対してエンティティ作成者のピン留めステップを実行します。これにより、ステップがその横に書き込む entity.lock も公開内容に含まれます。これは pin ツールが実行するのと同じステップで、同じバイトを書き込み、エンティティを判定するいかなる拒否よりも前に実行されます。そのため、たとえば署名の欠如でそこで拒否された公開でも、ロックはエンティティの横に書き込まれたまま残ります。オフラインのワークスペースや宛先なしなど、呼び出し自体に関する拒否は先に行われ、何もピン留めしません。省略するとワークスペースの pin_sources_at_push が決定し、送ればどちらの方向にもそれが決定します。ピン留めする公開はレジストリだけでなくワークスペース内にも書き込むため、HTTP 経由では両方のスコープを持つ資格情報が必要で、公開を許可するスコープのみを持つものは、もう一方を示して拒否されます。ステップが実行された場合、結果は pin ツールの応答と同じ形で pin を含みます。dry_run の下では、ステップは書き込むであろうロックを報告し、何も書き込みません。ステップが実行されない場合、読み取る入力のピンを entity.lock に記録していない Recipe または FeatureRecipe は拒否されます。入力がもはや一致しないものも同様で、dry_run を含め、何かがバンドルされる前に、aggrega pin、pin_sources、pin_sources_at_push を示して拒否されます。これは同じロックに対して pull が発する拒否であり、その確認ではステップと同様に、エンティティが書き出す各リモートソースを完全に取得します。

署名は資格情報が使われる場面であり、4 つのツールのうち 3 つがこれを行います。データアーティファクトの公開は何にも署名せず、後から参照によって署名されます。identity_token は呼び出しにキーレスのアイデンティティを提供します。標準入出力経由で到達するサーバーでは、これを省略するとそのサーバー自身の環境が持つアイデンティティにフォールバックし、key_path は代わりにオフラインで保持された鍵を選択します。リスナー経由ではそのどちらにも到達できません。環境は読み取られず、key_path は拒否されてこれら 3 つのツールが通知する内容から除かれ、提供中のワークスペースの設定が指定する鍵にも到達しません。そのため、呼び出しが使う資格情報 で説明するとおり、呼び出しで送られたトークンのみが署名します。1 回の呼び出しは 1 つの資格情報で署名します。 sign-artifacts に送られるすべての参照と、deprecate-artifact が読み取るバッチファイルのすべてのエントリは、同じ保持鍵または同じキーレスアイデンティティで署名されます。提供中のワークスペースの設定が、ある参照のレジストリには鍵を指定し別の参照のレジストリには指定していない場合、または 2 つの異なる鍵を指定している場合、呼び出しは何にも署名せず、アイデンティティが解決されたりレジストリが読み取られたりする前に、それぞれの側のレジストリを示して拒否されます。資格情報ごとに 1 回呼び出すか、標準入出力ではすべてに 1 つの key_path を送ってください。リスナー経由では設定された鍵に到達しないため、そこではすべての参照が呼び出しで送られたアイデンティティで署名され、この理由で拒否されることはありません。この拒否は References signed together need different signing credentials(一緒に署名される参照に異なる署名資格情報が必要です) で説明しています。fulcio_url、rekor_url、timestamp_url は、どちらのトランスポートでも、ワークスペースが設定するキーレスのエンドポイントを上書きします。アイデンティティがまったく解決されない場合、呼び出しは拒否され、送るべきものを示します。ここではブラウザを開いたり人を待ったりすることはありません。プロトコルストリームを見ている人はおらず、ハングする呼び出しは、拒否が防ぐために存在する無言の失敗そのものになるからです。publish-entity では、署名を添付するかどうかは sign が別途指定しない限り宛先レジストリのポリシーに従い、署名を要求するレジストリは何を送っても署名なしの公開を拒否します。その拒否を回避する引数はありません。2 つの署名モードとそれぞれの接続先については aggrega sign を参照してください。

各結果はやり取りの記録ではなく事実を保持します。アーティファクトが置かれた場所、そのタグ、公開されたダイジェスト(カタログエンティティのドライランの場合は、公開した場合に置かれるはずのダイジェスト)、タグがすでにバイト単位で同一の内容を指していたかどうか、公開物が署名されたかどうか、そして reach です。署名のバッチは、署名されたすべての参照を、参照が与えられた順に、その署名がコミットするダイジェストとともに報告します。いずれかの参照が失敗したバッチは、短いリストを持つ結果としてではなく、失敗した参照をそれぞれ挙げる失敗として返されます。部分的なバッチが成功として報告されると、拒否が合格として読まれてしまうからです。非推奨化は各マーカーをそれぞれのダイジェストとともに報告します。マーカーは取り下げるアーティファクトのタグなしリファラーとして添付され、ほかに何もそれを指し示さないためです。何も公開されていない参照への署名や取り下げは、何もないものに添付されるのではなく、拒否されます。

回答の 2 つの部分

すべてのツールは読みやすいテキストで回答し、操作に構造化された結果がある場合はその横に構造化された結果も添えます。 テキストは会話を読む人のために書かれています。構造化された結果は、同じ回答をプログラムが読むフィールド(判定、ファイルの一覧、診断)として運びます。拒否の場合も、操作が拒否した時点で検出結果を手にしていたときは構造化された結果を運びます。ビルドについては 拒否されたビルドが返すもの で説明しています。

構造化された結果は、テキストも text_answer として運びます。 すべてのツールの構造化された結果には text_answer フィールドがあり、回答のテキストをテキストが運ぶとおりに、すべての文を順序どおり、変更せずに保持します。そのため、Claude Desktop のようにテキストではなく構造化された結果をモデルに渡すクライアントでも、テキストが述べるすべての文をモデルに渡すことになります。たとえば、引数なしの describe-capabilities の回答の冒頭の行、config-show が報告する有効な設定、ワークスペースが見つからなかった場合に回答が使用したフォルダを示す文などです。text_answer は、ツールが回答するフィールドより前に最初に書かれ、呼び出し元が受け取るテキストそのものです。HTTP 経由では、回答がサーバーのファイルシステムについて述べること で説明するとおり、テキストと同様にサーバーのホスト上の各場所を示します。テキスト自体は、それを読むクライアントのために本来の文章のまま残るため、各回答では同じ言葉が 2 回送られます。

lint を含め、例外となるツールはありません。 text_answer という名前の独自フィールドで回答するツールはないため、このフィールドが他のフィールドの代わりになることはありません。lint の構造化された結果は、その summary(チェックしたエンティティの数と検出結果の数を、合計および重大度別に、aggrega lint が -o json で書き出す名前で示したもの)を保持し、その横に text_answer を運びます。describe-capabilities も独自のフィールドを保持します。引数なしで呼び出された場合はバージョン行のみである version_summary を、また index の各エントリにはそのツールの 1 行の目的である summary を保持します。

出力スキーマを公開するツールはありません。 ツールの一覧には受け取る引数のスキーマが含まれますが、結果のスキーマは含まれません。そのため、text_answer はスキーマではなくここで名前を示しています。

構造化された結果のない回答は、テキストのみです。 呼び出しの引数の拒否や、操作が報告する構造化された内容を持たなかったその他の失敗は、テキストのみで返されます。その場合、クライアントがモデルに示せるのはテキストだけです。

呼び出しが成功しなかったとき

回答がどこに届くかは、ひとつの点で決まります。存在するツールの引数を変えることで、呼び出し側がそれを修正できるかどうかです。

そのようにして修正できるものはすべて、ツール自身の結果として返され、失敗としてフラグが立てられ、修正内容をテキストとして持ちます。ツールが受け付けないセレクタの組み合わせ、省略された必須引数、誤った JSON 型で送られた引数、解決できないパス、コンパイラからの診断などです。これはアシスタントに示されるチャネルであるため、アシスタントは何が問題だったかを読み取り、引数を修正して再度呼び出します。

プロトコルのエラーチャネルは、ツール結果に収まる場所のないもののために確保されています。サーバーが提供していないツール名、パラメータを読み取れないリクエスト、実装していないメソッド、そもそも有効な JSON でないメッセージです。リソースの読み取りとプロンプトのレンダリングもそこで回答します。これらの結果はいずれも独自の失敗フラグを持たないためです。

ツールが公開するスキーマは、その引数が満たすべき規則の大部分も宣言しています。どのセレクタが互いに排他的か、どの引数が別の引数と併用したときにのみ意味を持つか、どれが必須か、です。そのため、宣言されたスキーマに沿って呼び出しを組み立てるクライアントが、それらを知るために実際に呼び出す必要はほとんどありません。スキーマに記述されていない規則も拒否され、その規則を示す文が返されます。pull の、verify を upgrade_targets や pin_sources と組み合わせないという規則は、Release が依存するものの解決で述べる理由により、意図的に拒否に委ねられています。

サーバーを停止させるもの

標準入出力では、接続を閉じるとサーバーは停止します。 サーバーは 1 行につき 1 つのメッセージを読み取り、標準入力がストリームの終端に達するとクリーンに終了します。そのため、接続を閉じたクライアントはサーバーをシャットダウンさせます。このトランスポートではこれが通常のケースです。コマンドを自分で起動することはなく、起動したクライアントがそれを終了させるからです。したがって、エディタを終了すること、またはプロジェクトでこのサーバーを無効にすることが、通常の停止方法になります。

プロセス自体に停止を求めると、どちらのトランスポートでもサーバーに届きます。 ターミナルからの割り込み、またはスーパーバイザーやコンテナランタイムからの終了要求を受けると、クライアントが何かを送信しているかどうかにかかわらず、最初の要求でサーバーはシャットダウンします。メッセージの受け付けを止め、処理中の呼び出しが行っている作業を終わらせ、クリーンに終了します。2 回目の要求でプロセスは即座に終了します。したがって標準入出力では、プロセスに停止が求められた時点でまだ実行中の呼び出しは完了しません。一方リスナーはドレインを行い、すでに応答中の呼び出しを、上限のある猶予の範囲内で完了させてからプロセスを終了します。

クライアントはサーバーを停止させずに 1 つの呼び出しだけを停止することもでき、その方法はトランスポートによって決まります。 呼び出しは並行して応答されるため、1 つの呼び出しの終了は、その後ろで待つのではなく、その呼び出しがまだ実行中のうちに処理されます。標準入出力では、クライアントは呼び出しの id を指定します。すでに応答済みの呼び出しや、サーバーが処理していない呼び出しをキャンセルしても何も起こりません。そのため、応答がすでに返送中かどうかを先に知らなくても、このようなメッセージを安全に送信できます。HTTP では送信するメッセージはなく、呼び出しを運んだ接続を閉じるとその呼び出しが終了します。いずれの場合も呼び出しには停止が伝えられ(その作業は操作が次に確認する時点で終了し、一度も確認しない操作は最後まで実行されます)、その呼び出しについてはそれ以上何も送信されず、処理中の他のすべての呼び出しは継続し、サーバーはサービスを続けます。

使用する場面

aggrega mcp は、AI アシスタントに実際のスキーマとリファレンスに基づいて Aggrega のエンティティの作成を手伝わせたい場合に使用します。これにより、アシスタントの提案は推測ではなく、コンパイラが受け付ける正確な構造に基づいたものになります。これは作成のループにそのまま組み込めます。アシスタントは kind のスキーマとリファレンスを読み、スケルトンを生成し、自分のロールが担当するフィールドを埋め、ドラフトを返す前に検証します。このループについてはAggrega ファイルの作成を参照してください。

標準入出力を使う場合、通常 aggrega mcp を自分で入力することはありません。代わりにクライアントの MCP 設定で一度指定すれば、クライアントが起動と停止を行います。リスナーはもう一方のケースです。この場合はプロセスを自分で実行し、プロセスはそれを起動していない呼び出し元のために動作し続けます。

例: 標準入出力を使うクライアントの設定

stdio サーバーのエントリで MCP クライアントにこのコマンドを指定します。

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

前提条件は、インストール済みの aggrega バイナリがクライアントの PATH 上にあることだけです。クライアントごとの設定ファイルのパスとトラブルシューティングについては、MCP サーバーの接続を参照してください。クライアントを使わずにコマンドラインから直接スキーマを取得するには、aggrega get-schema を参照してください。