@plurnk/plurnk-mcp 1.23.0 → 1.25.0

package/SPEC.md

@@ -172,11 +172,21 @@ conformance stays a separate named gate, never folded into a matrix row.
 | stdio | Spawn one exact executable with an explicit argument array and no shell; newline-delimited JSON-RPC is the only stdout/stdin traffic; stderr is diagnostic; shutdown closes stdin, waits, then terminates if necessary |
 | Streamable HTTP | Send one POST per request or notification; accept JSON or SSE responses; close the response stream to cancel; modern connections never open the removed general GET stream |
 
+§mcp-endpoint-security **Configured MCP and registry endpoints accept HTTP or HTTPS,
+including private-network hosts.** Transport admission does not relax OAuth:
+the SDK retains token-endpoint TLS enforcement (with its loopback exception),
+issuer/resource binding, PKCE and redirect validation. No transport-policy bypass is supplied.
+
 §mcp-stdio-process-ownership A stdio connection owns the complete process group
 created for its server. Ordinary closure forwards stdin EOF and permits a
 bounded graceful exit; an expired shutdown bound or disappearance of the host
 process forcibly terminates the group, including descendants.
 
+§mcp-redirect-refused **An HTTP endpoint is never redirected.** Every Streamable HTTP request,
+authorization discovery included, sets `redirect: "manual"`; a 301, 302, 303, 307, or 308 fails the
+connection naming the `Location`. Configured headers therefore never reach another origin
+and the endpoint URL is corrected where it is configured.
+
 At the pinned revision, HTTP requests carry matching `MCP-Protocol-Version` and `Mcp-Method`
 headers. Named requests also carry `Mcp-Name`; declared primitive tool
 parameters carry validated `Mcp-Param-*` headers. Header names compare
@@ -204,169 +214,183 @@ originating distinction in its canonical Problem/result path.
 
 ## §mcp-configuration Configuration
 
-Service configuration and workspace state produce one available set and one
-enabled subset per workspace. Every `PLURNK_MCP_<server>` declares an available
-service-owned definition. `PLURNK_MCP_ENABLED` names the exact subset enabled
-when a workspace has no override. Workspace state may positively override a
-service definition's enabledness or own an added definition and its enabledness.
-Disabled definitions remain client-visible but contribute no connection,
-Registry, documentation, or resource authority.
+MCP servers are complete connection definitions ({§mcp-server-definition}). Standalone files, plugin components, and environment declarations
+supply the service baseline; live additions belong to the workspace. All use the common resolution
+and lifecycle ({§configuration-definition-resolution}, {§functionality-coordinator}). Disabled definitions remain
+client-visible but contribute no connection, Registry, documentation, or resource authority.
 
-§mcp-activation-isolation **Cold endpoint failure is capability-local.** Invalid
-service configuration or durable state fails admission, but an enabled server
+§mcp-file-configuration **Standalone `mcp.json` files are read-only configuration inputs, not plugins.**
+The module reads `mcp.json` in the directories supplied by {§agent-roots}. Definitions resolve
+by alias, highest precedence first:
+
+| Source | Location |
+|---|---|
+| Workspace overlay | Ordinary `mcp (add)` state |
+| Environment | `PLURNK_MCP_<alias>` |
+| Project | `<project>/.agents/mcp.json`, then selected project plugins |
+| Plurnk-only | `$XDG_CONFIG_HOME/plurnk/mcp.json`, then selected Plurnk plugins |
+| Shared global | `~/.agents/mcp.json`, then selected global plugins |
+| Installed npm plugins | Selected plugin bundles in the installed graph |
+
+- The document is an object with required `mcpServers`, an object keyed by server alias,
+  and an optional string `$schema` editor hint. No schema is fetched. No other top-level fields.
+- Each entry is the owning connection definition without `name`; its map key supplies the name.
+  An omitted `type` is inferred from `command` (stdio) or `url` (Streamable HTTP).
+  Ambiguous, unsupported, or incomplete entries fail the same definition validator as environment/live inputs.
+- Select the whole winning entry before validating it; never merge fields or fall back from an invalid winner.
+  Environment enabledness and tool controls apply independently to file-backed aliases.
+- Missing files contribute nothing. Invalid/unreadable files or selected entries produce a named
+  configuration diagnostic under {§configuration-repair-path}, not a daemon exit or an empty catalog.
+- Inspection reports `kind: file`, the absolute file `source`, and the entry's JSON Pointer `reference`.
+  Normal pre-turn refresh observes file edits and deletion; `list` never starts a server or writes a file.
+  Workspace removal restores the current inherited definition and controls.
+- File entries retain {§mcp-launch-directory} and {§mcp-launch-environment}; a file's location is
+  not a subprocess working directory. Plugin-root configuration and packaging are separate.
+
+`mcpServers` follows the common MCP catalog shape, also used by
+[MCP Inspector](https://github.com/modelcontextprotocol/inspector/blob/main/docs/mcp-server-configuration.md).
+The discovery locations are Plurnk's supported cross-client convention, not an MCP wire requirement.
+
+§mcp-plugin-configuration **Plugin MCP components use their format's interpretation, not the native file dialect.**
+The validated components supplied by {§agent-plugins-hosting} become ordinary configured MCP
+definitions. The adapter carries the canonical plugin root and persistent data directory as
+interpretation context under {§functionality-adapter}; inspection preserves symbolic definitions.
+
+| Field or boundary | Agent Plugins v1 behavior |
+|---|---|
+| `command` | Bare executable or plugin-root-relative `./` path; no expansion |
+| `args`, `env`, `cwd` | One nonrecursive expansion of `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` only; all other placeholder-like text stays literal |
+| Omitted `cwd` | Plugin root; explicit plugin/data cwd is contained within its corresponding resolved root |
+| Subprocess environment | Ordinary admitted operator/workspace environment, then configured values, then authoritative `PLUGIN_ROOT` and `PLUGIN_DATA` |
+| Data | Created before launch; preserved across disable, removal of an override, and in-place plugin updates |
+| Filesystem containment | Rechecked before each subprocess launch, including existing parents of missing paths |
+| HTTP URL and headers | Literal; client-owned protocol headers win; existing no-redirect rule applies |
+| Unsupported transport or name | Skip the entry with a configuration notice; never rename, reinterpret, or disable independent entries |
+
+Supported transports are stdio and Streamable HTTP, not legacy SSE. Server names must meet
+Plurnk's runtime alias grammar `[a-z][a-z0-9-]*`; other standard map keys are explicitly unsupported.
+The standard loader owns component validation and narrow failure boundaries
+({§agent-plugins-mcp-entries}, {§agent-plugins-components}). Connection failures remain ordinary
+unavailable outcomes. Current adapter notices join client/model configuration diagnostics;
+source repair replaces them, rather than retaining a historical warning.
+
+§mcp-activation-isolation **Cold endpoint failure is capability-local.** An enabled server
 that cannot connect or complete discovery during workspace activation remains
 enabled and client-visible as `unavailable`. It publishes no runtime, tools,
 resources, or documentation and cannot prevent other capabilities or the daemon
 from starting or serving dormant workers. Enabling that already-enabled alias is an explicit reconnect
 attempt; failure preserves the unavailable snapshot, while success atomically
-replaces it. Interactive add and enable mutations continue to reject an
-unavailable candidate without changing durable state.
+replaces it. An interactive enable continues to reject an unavailable candidate
+without changing durable state.
 
 | Variable | Contract |
 |---|---|
-| `PLURNK_MCP_<server>` | HTTP(S) URL or exact stdio executable; empty masks the definition ({§mcp-configuration-cascade}) |
-| `PLURNK_MCP_<server>_ARGS` | JSON string array for stdio |
-| `PLURNK_MCP_<server>_CWD` | Working directory for stdio |
-| `PLURNK_MCP_<server>_ENV` | JSON string map for stdio |
-| `PLURNK_MCP_<server>_BEARER` | HTTP bearer credential; use `${TOKEN}` expansion to retain the authoritative environment value |
-| `PLURNK_MCP_<server>_HEADERS` | JSON string map for supplementary HTTP headers |
-| `PLURNK_MCP_<server>_TOOLS` | Optional JSON array of exact enabled tool names; absent enables all listed server tools, while `[]` enables none |
-| `PLURNK_MCP_<server>_READ` | JSON string array forming an exact subset of enabled tools that the operator classifies as read-only; every other enabled tool retains the conservative `host` effect |
-| `PLURNK_MCP_<server>_SUMMARY` | Authored one-line server orientation ({§mcp-summary-derivation}) |
-| `PLURNK_MCP_<server>_<tool>_SUMMARY` | Authored one-line tool orientation; tool names fold the same way and may contain underscores |
-| `PLURNK_MCP_ENABLED` | JSON array of exact configured server aliases enabled by default. `[]` is the one spelling of none: the panel states it, and an absent or empty key is refused by name |
-| `PLURNK_MCP_EXPANDED` | JSON array subset of enabled servers whose every tool is surveyed at turn 0 — one FIND row per executable block of the family document, with aside and signature ({§tools-resource-materialization}); never a document delivered unasked; absent or `[]` expands none |
-| `PLURNK_MCP_CONNECT_TIMEOUT` | Positive integer milliseconds |
-| `PLURNK_MCP_REQUEST_TIMEOUT` | Positive integer milliseconds |
-
-Configured server names match `[a-z][a-z0-9-]*` after case-folding and share
-the executor and URI-authority namespace. Duplicate names, reserved-name
-collisions, orphan companions, wrong-transport companions, missing environment
-references, and invalid JSON fail startup. A stdio target is one exact
-executable string even when its path contains whitespace; arguments never hide
-inside it. Bearer authentication and a case-insensitive `Authorization` entry
-in `_HEADERS` are mutually exclusive.
-
-§mcp-summary-derivation **Orientation prefers authored purpose over display
+| `PLURNK_MCP_<alias>` | Complete `McpServerDefinition` JSON; transport and authentication replace together |
+| `PLURNK_MCP_ENABLED`, `PLURNK_MCP_<alias>_ENABLED` | Shared default and per-alias flags ({§resource-environment}); declared servers default enabled |
+| `PLURNK_MCP_<alias>_TOOLS` | Optional JSON array of exact enabled tool names; absent or empty enables every listed tool, and `[]` enables none |
+| `PLURNK_MCP_EXPANDED` | JSON array of aliases whose tool invocations are surveyed at turn 0 ({§tools-resource-materialization}); absent or `[]` expands none |
+| `PLURNK_MCP_CONNECT_TIMEOUT` | Positive integer milliseconds for setup and each complete catalog walk |
+| `PLURNK_MCP_REQUEST_TIMEOUT` | Positive integer milliseconds for the whole operation |
+| `PLURNK_MCP_REGISTRY_URL` | HTTP(S) registry discovery endpoint; empty disables registry search |
+| `PLURNK_MCP_REGISTRY_LIMIT` | Positive integer result bound |
+
+Aliases and controls follow {§resource-environment}. Malformed definitions or controls fail
+configuration by variable name, even when disabled or not yet associated with a resource.
+Authentication belongs in the definition, never in separate bearer/OAuth environment companions.
+The package's offline validator composes these same readers
+({§operator-config-offline-validation}); it performs no connection or secret resolution.
+Runtime configuration errors leave the manager inspectable without publishing MCP
+capabilities or preventing unrelated model work ({§configuration-repair-path}).
+
+§mcp-definitions **A server is not a plugin installation.** `add` persists a workspace
+connection definition; `remove` removes that definition through the common coordinator.
+Neither writes nor deletes project, user or global configuration files. MCP management
+and preparation do not enumerate or install Agent Plugins. Plugin integration is a separate
+configuration-source concern, not an MCP definition or lifecycle.
+
+| Transport | Launch or connection |
+|---|---|
+| `stdio` | Spawn `command` with `args`, without a shell. Bare executable names use PATH; relative executable paths use the working directory. `args`, `env` and explicit `cwd` expand `${NAME}` references once against the workspace-composed operator environment. |
+| `streamable-http` | Connect to `url` with `headers` and `authorization` from that same definition. Header references expand at connection time. Protocol-generated headers are transport-owned; application authentication headers are retained. Declaring both structured authorization and an Authorization header is invalid. No redirect is followed ({§mcp-redirect-refused}). |
+
+§mcp-launch-directory **An implicit working directory is workspace-owned state, not the project.**
+Core's {§module-workspace-directory} supplies a stable directory isolated by workspace and MCP alias.
+An explicit `cwd` must resolve to an absolute path and overrides that directory; it is not confined
+to an installation root. The caller owns provisioning an explicit directory. Runtime paths and
+resolved environment values are never copied back into a stored definition. Disabling or removing
+a server closes its connection, not its retained state directory or saved results.
+
+A tool whose `annotations.readOnlyHint` is true takes the `read` effect; every other tool keeps the
+conservative `host` effect ({§mcp-model-projection}).
+
+§mcp-summary-derivation **Orientation prefers the server's own purpose over display
 labels; no capabilities are inferred.** Blank values fall through:
 
 | Summary | Precedence, highest first |
 |---|---|
-| Server | `_SUMMARY` → `serverInfo.description` → `instructions` → `serverInfo.title` → effective admitted tool-name list → server alias |
-| Tool | `_<server>_<tool>_SUMMARY` → `description` → `title` → `annotations.title` → tool name |
+| Server | `serverInfo.description` → `instructions` → `serverInfo.title` → effective admitted tool-name list → server alias |
+| Tool | `description` → `title` → `annotations.title` → tool name |
 
 Derived prose is whitespace-normalized, limited to its first sentence, and
-clipped within 80 characters plus an ellipsis, preferring a word boundary. Explicit
-one-line overrides remain intact. Full server instructions remain authored
+clipped within 80 characters plus an ellipsis, preferring a word boundary. Full server instructions remain authored
 Markdown in the family document's runtime `details`, available on demand;
 turn0 surveys only the compact summary/invocations. Full tool descriptions
 remain in the linked input-contract documents. With tools, the runtime declares
 `{ from: "tools", description }`: purpose annotates rather than replaces the
 complete effective menu in the family Summary and survey row
-({§scheme-catalog-aside}). Without authored purpose the menu stands alone. The tool
+({§scheme-catalog-aside}). Without a stated purpose the menu stands alone. The tool
 doc's Summary section IS the invocation form
 ```` ```server (tool) <!-- one-liner --> ````, so the discovery row teaches the
-call ({§tools-resource-materialization}). Summary companions expand `${NAME}`
-references like every other companion.
+call ({§tools-resource-materialization}).
 
-§mcp-definition-wire The contracts-owned `McpServerDefinition` JSON Schema is
-the normalized durable definition shape. It is a closed discriminated union:
-
-| Transport / authorization | Required definition | Optional definition |
-|---|---|---|
-| `stdio` | `name`, `transport`, `command` | `args`, `cwd`, `env`, `tools`, `read` |
-| `http` + none | `name`, `transport`, `url` | `headers`, `tools`, `read` |
-| `http` + bearer | above plus `authorization: { type: "bearer", token: "${NAME}" }` | — |
-| `http` + interactive OAuth / CIMD preferred | above plus `authorization: { type: "oauth", redirectUrl, clientMetadataUrl }` | `scope`; DCR remains the server-advertised fallback when CIMD is unavailable |
-| `http` + interactive OAuth / pre-registered | above plus `authorization: { type: "oauth", redirectUrl, clientId, clientSecret: "${NAME}" }` | `scope` |
-| `http` + interactive OAuth / DCR fallback only | above plus `authorization: { type: "oauth", redirectUrl }` | `scope` |
-| `http` + client credentials | above plus `authorization: { type: "client-credentials", clientId, clientSecret: "${NAME}" }` | `scope`; `issuer` binds the credential to its authorization server ({§oauth-client-credentials}) |
-
-`tools` absent enables the complete listed set; `[]` enables none. `read` is an
-exact subset of the enabled set. A credential field is one complete symbolic
-environment reference, not a copied token. Other string-valued `headers`,
-`env`, `cwd`, and argument values may contain symbolic references and are
-expanded only while preparing a connection. The unexpanded definition is the
-only durable form. Interactive OAuth tokens, PKCE verifier, issuer-bound
-discovery state, and authorization callback state remain process-memory
-credentials; a restart reconstructs the attachment as authorization-required
-instead of writing secrets into SQLite.
-
-The contracts-owned `McpServerDefinition` is the exact definition one `add`
-accepts and the coordinator persists; a client composes it from its target
-(an absolute HTTP(S) URL selects Streamable HTTP, anything else is one exact
-stdio executable) and its options (`args`, `cwd`, `env`, `headers`,
-`authorization`, `tools`, `read`). The normalized definition rejects
-transport-inapplicable options before any connection work.
-
-§mcp-configuration-cascade MCP server configuration has one field-wise
-precedence order: service environment, then the workspace's durable definition.
-Arrays and maps replace their lower value instead of appending or merging.
-An explicitly empty environment target omits that service definition, its
-companions (including summaries), and its inherited `ENABLED`/`EXPANDED`
-selections. Companion values are neither parsed nor expanded. It does not
-remove a workspace-owned definition or prohibit adding one. Genuinely undeclared
-aliases and case-fold collisions still fail validation.
-Client configuration is not a live layer: the contracts-owned
-`{§mcp-configuration-overlay}` enters only as the `configuration` of a
-`discover` query, is parsed by the same owner and path as service environment
-declarations, and yields inert candidates with client-configuration provenance
-({§mcp-discovery}); adding one persists a complete, normalized, unexpanded
-workspace definition. Thus later enablement needs neither the originating client
-nor its configuration file, and symbolic credentials remain resolvable only by
-the service at connection preparation.
+§mcp-server-settings **Independent behavior settings do not change connection definitions.**
+`<alias>_TOOLS` narrows the effective tool catalog. A valid control may precede its definition,
+without creating a server; all control values are validated immediately ({§resource-environment}).
+Bearer and OAuth settings belong to the whole HTTP definition. Secrets in structured authorization
+are `${NAME}` references expanded only while preparing the connection. Interactive tokens,
+PKCE verifiers and callback state remain in memory; restart reconstructs an authorization-required
+attachment, never a stored credential.
 
 ### §mcp-module The MCP family beneath the coordinator
 
-§mcp-launch-environment Discovery and stdio connection preparation use the workspace
-environment supplied by Core ({§workspace-env}), never the invoking worker's overrides.
-The admitted workspace environment reaches the actual subprocess; explicit definition
-launch options override it. Symbolic references resolve against the operator environment
-with the same workspace entries and masks applied. Resolved ambient values are never
-copied into durable definitions.
-
-An `env` header option on `mcp (add)` becomes that definition's retained stdio launch
-override, with the definition's existing symbolic-reference semantics. On `discover`
-it applies to the probe and its returned candidate. HTTP servers
-have no local process environment and refuse these stdio launch overrides; ordinary
-HTTP authorization/header references may use workspace values. A running server keeps
-its launch environment. Use ordinary `disable` and `enable` to restart it after an env
-change; there is no automatic restart or stale-configuration state.
-
-§mcp-working-storage **A local server never implicitly inherits the daemon's
-working directory.** The common connection boundary requires an explicit CWD
-or a host-supplied default. Missing or unusable storage fails connection
-preparation; it never falls back to the project.
-
-| Connection | Working directory and lifetime |
-| --- | --- |
-| Attached stdio server without `cwd` | `servers/<alias>` under the module directory from {§module-workspace-directory}; created lazily with mode `0700`, retained across disable/enable, removal, cooling, and daemon restart. |
-| Direct stdio discovery | A unique `discover-*` directory beneath that same module root; removed only after the probe connection closes, including unsuccessful probes. It is never persisted in the candidate definition. |
-| Explicit `cwd` | Honored without creation or cleanup. Relative values resolve against the launcher's CWD, not the default storage directory. |
-| HTTP | No local working directory is allocated. |
-
-Host-owned storage does not replace `HOME`, credentials, XDG environment values,
-tool arguments, or the project CWD of ordinary executors. Executables and file
-arguments needing a particular project must name it explicitly or configure
-`cwd`. Stored streams/resources retain their existing ownership. This is a
-default-placement contract, not filesystem confinement or a promise to
-redirect a third-party server's absolute writes. No server-specific flags or
-deprecated roots capability are introduced.
-
-§mcp-management-actions MCP is one family of workspace Functionality
-({§functionality-coordinator}): the coordinator publishes `workspace.mcp.list |
-discover | add | enable | disable | remove` and the model's `mcp` executable fence
-family with the common semantics, durable state, and publication; this module
-registers the family adapter and owns protocol truth beneath it. `available`
-is the service environment with its `PLURNK_MCP_ENABLED` defaults; `admit`
-validates one exact definition and binds the alias to its `name`; `prepare`
-connects the enabled set, reusing unchanged live attachments, and returns one
-executor family and resource facet per connected server, one outcome per alias
-(`active` with catalog detail — negotiated protocol version, server identity,
-capabilities, tool names, resource and prompt counts — `unavailable` with its
-exact Problem, or `authorization-required` with its URL), and a two-phase
-snapshot: `commit` closes connections the new set no longer uses and records
-pending authorizations; `abort` closes only what the attempt opened.
+§mcp-launch-environment **A server inherits the operator's environment.** A stdio server
+starts with the operator's environment without plurnk's own secrets ({§exec-env-scoped}), as every MCP
+client launches one: stdio servers read their credentials from the environment. The model's command
+ceiling is not its base. The workspace layer ({§workspace-env}) applies on top, its values and
+withholdings included, never the invoking worker's overrides; the definition's `env` follows. Definition references resolve against the operator environment with the same workspace
+entries and masks applied, and resolved ambient values are never copied into definitions. A running server keeps its launch environment:
+`disable` and `enable` restart it after an environment change, and there is no automatic restart or
+stale-configuration state. HTTP servers have no local process environment.
+
+§mcp-management-actions MCP is one family of workspace Functionality ({§functionality-coordinator}). The
+coordinator publishes `workspace.mcp.list | discover | add | enable | disable | remove` and the model's
+`mcp` executable fence family with the common semantics, durable state, and publication; this module
+registers the family adapter and owns protocol truth beneath it. `available` is the configured service baseline; `add` and `remove` change workspace state ({§mcp-definitions}), and
+`discover` searches the MCP Registry ({§mcp-registry-discovery}). `prepare` connects the enabled set, reusing
+unchanged live attachments, and returns one executor family and resource facet per connected server,
+one outcome per alias (`active` with catalog detail — negotiated protocol version, server identity,
+capabilities, tool names, resource and prompt counts — `unavailable` with its exact Problem, or
+`authorization-required` with its URL), and a two-phase snapshot: `commit` closes connections the new
+set no longer uses and records pending authorizations; `abort` closes only what the attempt opened.
+
+§mcp-registry-discovery **`discover` searches the MCP Registry.** `{ query }` asks
+`PLURNK_MCP_REGISTRY_URL` (API v0.1) for one page of at most `PLURNK_MCP_REGISTRY_LIMIT` servers, each at
+its latest version, whose names match. Each npm, PyPI, NuGet or OCI package with a stdio transport
+becomes a stdio entry run as the registry's own examples run it (`npx -y`, `uvx`, `dnx`, or
+`docker run -i --rm` passing each declared variable through), and each Streamable HTTP remote becomes a
+URL entry with its non-secret literal headers. An entry that needs a person's input first, such as a
+template variable or a required argument with no value, has none. A candidate is a complete definition;
+its summary names the environment variables and headers the
+server needs, and its provenance names the registry and the server's `name@version`. `source` and
+`configuration` are not registry queries and are refused.
+
+| Discovery, admission, or installation condition | Problem | Status |
+|---|---|---|
+| No registry is configured | `registry-not-configured` | 501 |
+| The registry is unreachable, fails, or answers malformed | `discover-failed`, retryable | 502 |
+| `discover` names a `source` or client `configuration` | `source-unsupported`, `configuration-unsupported` | 400 |
+| The complete connection definition is invalid | `definition-invalid` | 400 |
+| The alias differs from the definition's name | `alias-mismatch` | 400 |
 
 Two protocol continuations remain MCP-registered workspace actions beneath the
 common grammar:
@@ -376,15 +400,6 @@ common grammar:
 | `workspace.mcp.oauth.complete` | `alias`, `callbackUrl` | State- and issuer-validates one pending interactive callback through the SDK, completes connection preparation, and re-enables the alias through the coordinator ({§oauth-continuation}); the result is the common mutation result. |
 | `workspace.mcp.complete` | `server`, `ref`, `argument`; optional `context` | Requests negotiated prompt/resource-template argument completion for a client-owned interaction. |
 
-§mcp-discovery Discovery is inert. `configuration` (a client's own
-`PLURNK_MCP_*` overlay) becomes candidates without connecting; `source` — an
-absolute HTTP(S) URL or one whitespace-separated command line — is probed at the
-negotiated revision for its catalog and released, yielding one candidate with
-direct-target provenance (an authorization challenge yields the candidate with
-that fact in its summary); a bare `query` requires a configured downstream
-registry and is `501 registry-not-configured` until one exists. No candidate
-is installed, persisted, enabled, or executed by discovery.
-
 Expected preparation failures cross the boundary as MCP-management Problems
 rather than generic failures; an explicit client action rejects them and a
 Worker's own accepted mutation publishes them as unavailable
@@ -392,7 +407,9 @@ Worker's own accepted mutation publishes them as unavailable
 
 | Endpoint condition | Problem |
 |---|---|
-| Cannot connect or complete discovery/catalog preparation at the negotiated revision | `502 server-unavailable`, retryable; names the server and transport without exposing credentials |
+| Cannot connect or complete discovery/catalog preparation at the negotiated revision | `502 server-unavailable`, retryable; names the server and its `type` without exposing credentials |
+| The endpoint answers with a redirect | `502 server-redirected`, non-retryable ({§mcp-redirect-refused}) |
+| An operator setting of the alias is invalid | `422 server-settings-invalid`, non-retryable ({§mcp-server-settings}) |
 | Client-credentials grant rejected by the authorization server | `502 oauth-client-credentials-failed`, non-retryable; names the server and client id, never the secret ({§oauth-client-credentials}) |
 
 Resource and prompt failures retain one caught remote diagnostic only through
@@ -429,32 +446,32 @@ as an accidental failure.
 
 | Journey point | Behaviour |
 |---|---|
-| Pending authorization | One pending candidate per `(workspace, alias)`; a new add or customized enable cancels and replaces it. A callback from a superseded attempt fails state validation instead of cross-completing. |
+| Pending authorization | One pending candidate per `(workspace, alias)`; a new challenge or customized enable cancels and replaces it. A callback from a superseded attempt fails state validation instead of cross-completing. |
 | Client disconnect | Does not touch the pending candidate; it can still be completed, or replaced by a fresh request. |
 | Daemon restart during pending | The candidate is lost: nothing was durable, no attachment publishes, and `oauth.complete` answers `404 oauth-not-pending`. Start authorization again. |
 | Daemon restart after authorization | The durable definition rehydrates but tokens are gone; the attachment publishes `authorization-required` and enable returns status `202` with `definition.authorization.url` in the common mutation result. The operator reauthorizes. |
 | Token expiry | An expired access token surfaces as one unauthorized response; the SDK re-acquires via `refresh_token` when one was issued, otherwise re-enters interactive authorization. |
 | Refresh | Happens only against the issuer bound during the original authorization; the refreshed token replaces the in-memory token. |
 | Workspace disable/remove | Closes the attachment and clears its pending candidate; no durable secret deletion is needed because nothing secret is durable. |
-| Server replacement | Completion compares the pending candidate's expected definition with the current one; drift of the same server fails `409 oauth-target-conflict` instead of replaying a stale snapshot. |
+| Server replacement | Publication discards any superseded pending connection and releases its residency, including replacement by a definition without OAuth. Completion of an unpublished configuration drift fails `409 oauth-target-conflict` instead of replaying a stale snapshot. |
 | Cross-authorization protection | Candidates are keyed by `(workspace, alias)`; callback state, PKCE, and issuer are validated by the SDK against the attempt that created them, so no other workspace, alias, or attempt can complete this authorization. |
 
 ## §oauth-client-credentials Client-credentials grant adoption
 
 The `client-credentials` arm of `McpServerDefinition.authorization` adopts the
 official `io.modelcontextprotocol/oauth-client-credentials` extension's
-client-secret form faithfully: an MCP connection whose definition holds a
-client-credentials grant advertises the extension capability in
+client-secret form faithfully: a connection whose definition holds a
+client-credentials grant ({§mcp-server-settings}) advertises the extension capability in
 `clientCapabilities.extensions`; connections without one never claim it. The
 grant uses `client_secret_basic` authentication with `grant_type
-client_credentials`. Scope from the definition's optional `scope` is passed to
+client_credentials`. The setting's optional `scope` is passed to
 the token request. The credential itself is one complete symbolic environment
 reference (`clientSecret: "${NAME}"`), expanded only while preparing the
 connection; it is never stored in SQLite, logged, or echoed in Problems.
 
 | Aspect | Behaviour |
 |---|---|
-| Issuer binding | The definition's optional `issuer` is passed as the SDK provider's `expectedIssuer`, stamping the credential with its authorization server so SEP-2352 issuer checks refuse to send it elsewhere. Absent, the SDK's legacy no-binding behaviour applies. |
+| Issuer binding | The setting's optional `issuer` is passed as the SDK provider's `expectedIssuer`, stamping the credential with its authorization server so SEP-2352 issuer checks refuse to send it elsewhere. Absent, the SDK's legacy no-binding behaviour applies. |
 | Token lifetime | Token refresh is 401-triggered by the SDK client: an expired access token surfaces as one unauthorized response, the provider re-fetches with the stored credential, and the request is retried. Proactive expiry scheduling is a client-internal optimization, not a wire requirement; Plurnk does not wrap the SDK with its own scheduler. |
 | Rotation | `clientSecret` resolution happens per connection preparation, so rotating the operator environment value takes effect on the next preparation of the server. |
 | Errors | A rejected grant crosses the action boundary as `502 oauth-client-credentials-failed`, non-retryable, naming the server and client id only; SDK OAuth error text is never echoed. Other connection failures keep the generic `server-unavailable` allocation. |
@@ -513,6 +530,9 @@ boundaries; neither closes or replaces the committed connection.
 | Disable/remove, workspace cooling, or shutdown | Retires obsolete refresh timers and invalidations. |
 
 MCP participates in core Functionality residency ({§module-workspace-residency}).
+Preparation reports the current server alias through the coordinator's activity
+contract ({§functionality-preparation-visibility}); inspection never starts a
+connection ({§functionality-inspection}).
 Every tool call and Task retains the workspace from executor entry through its
 terminal result; an interactive OAuth candidate retains it until completion,
 replacement, cancellation, or module shutdown. Catalog refresh timers are
@@ -533,8 +553,11 @@ commit leaves the durable definition, connection, Registry, docs, and resource
 authority unchanged. Materialization and registration inspect the complete
 owning operation result; a non-success preserves its original Problem.
 
-§mcp-connection-shutdown Shutdown prevents new work and aborts each connection's
-active requests, including client-input waits. Their protocol cleanup settles
+§mcp-connection-shutdown Module `stop()` prevents new work and aborts each connection's
+active requests, including client-input waits. Discovery and preparation recheck
+admission after asynchronous environment resolution, before owning a new connection;
+connection startup rechecks after asynchronous directory resolution before opening
+its transport. Their protocol cleanup settles
 before the extension channel or connected transport closes, so a created Task
 can receive `tasks/cancel`. Concurrent closers await the same settlement.
 Candidates still negotiating and standalone OAuth transports close immediately.
@@ -586,6 +609,11 @@ does not weaken this uncertain-outcome boundary.
 remote diagnostic as structured extensions. Their prose states only the failed
 boundary fact; it neither repeats those fields nor infers whether the remote
 effect occurred.
+For `isError: true`, nonblank text content blocks, in order and joined by
+newlines, supply `diagnostic` under the existing executor error-detail bound.
+Nontext parts and structured data are not interpreted as explanations. With no
+text explanation the extension is absent; successful results do not acquire one.
+The complete result and passive output remain unchanged ({§mcp-result-content}).
 
 §mcp-trailing-aside A tool call's body is one JSON object. HTML comments after
 that object are the writer's aside, not arguments: when the body does not parse
@@ -696,7 +724,7 @@ shallow required-field previews and alias-scoped schema links. Each linked child
 preserves the complete remote description and raw input schema, without
 reconstructing property tables or expanding nested constraints into the preview.
 Output schemas do not enter model teaching; the returned value remains ordinary evidence. Disabled names
-appear in neither discovery nor admission, and there is no MCP-specific FIND,
+appear in no model teaching, and there is no MCP-specific FIND,
 READ, authority-root, or other model discovery mechanism for tools.
 
 Core validates the exact target and the selected tool's invocation before
@@ -707,10 +735,9 @@ contain resources and resource templates, never tools. Tool results become
 ordinary Plurnk entries and channels, so slicing, tags, curation, notices, and
 Problems need no MCP-specific parallel mechanism.
 
-MCP tool annotations remain untrusted metadata, not admission authority. The
-operator-owned `_READ` subset classifies enabled observations as the executor
-`read` effect; every other enabled tool remains `host` and therefore uses the
-ordinary proposal policy. Effect classification receiving an unregistered
+A configured server's `annotations.readOnlyHint` supplies its tool's declared effect:
+a tool marked read-only takes the executor `read` effect; every other enabled
+tool remains `host` and therefore uses the ordinary proposal policy. Effect classification receiving an unregistered
 target is an internal contract violation rather than a conservative guess.
 
 ## §mcp-conformance Conformance authority
@@ -736,12 +763,7 @@ stdio/Streamable HTTP servers are composition evidence only.
 | `invalid-tool-arguments` | 400 | The tool arguments are not one JSON object. Recovery: One JSON object per MCP tool call; a second call is a second fence. |
 | `oauth-client-credentials-failed` | 502 | MCP server '*name*' rejected the client-credentials grant; check the configured client credentials and issuer. |
 | `parameters-invalid` | 400 | Unsupported parameter(s): *names*. |
-| `configuration-invalid` | 400 | The supplied MCP configuration is invalid. |
-| `discover-failed` | 502 | MCP target '*source*' could not be inspected. |
-| `registry-not-configured` | 501 | MCP registry search requires a configured downstream registry; none is configured. Recovery: Discover an explicit source (URL or command) or configure a registry. |
-| `env-transport` | 400 | An HTTP MCP server has no local process environment. |
-| `definition-invalid` | 400 | The MCP server definition is invalid. |
-| `alias-mismatch` | 400 | Alias '*alias*' must equal the definition's name '*name*'. |
+| `server-settings-invalid` | 422 | MCP server '*name*' has invalid operator settings: *cause*. |
 | `server-busy` | 409 | MCP server '*name*' has *n* active request(s). |
 | `obsolete-connection-close-failed` | 500 | The MCP capability change committed, but an obsolete connection did not close cleanly. |
 | `oauth-not-pending` | 404 | MCP server '*alias*' has no pending OAuth authorization. |
@@ -750,3 +772,4 @@ stdio/Streamable HTTP servers are composition evidence only.
 | `server-not-connected` | 409 | MCP server '*name*' is not connected for this workspace. |
 | `completion-parameters-invalid` | 400 | MCP completion requires 'ref' and 'argument' objects. |
 | `server-unavailable` | 502 | Configured MCP server '*name*' is unavailable. |
+| `server-redirected` | 502 | MCP endpoint *url* redirected to *location*; plurnk follows no redirect, so the server's url must be the endpoint itself ({§mcp-redirect-refused}). |

package/dist/McpExecutor.d.ts

@@ -3,8 +3,8 @@ import type { ChannelDecl, Effect, ExecArgs, ExecResult, RuntimeAvailability, Ru
 import ServerConnection, { type ServerCatalog } from "./client.ts";
 import type { ContentBlock } from "@modelcontextprotocol/client";
 import type { ToolPolicy } from "./config.ts";
-export declare const serverSummary: (name: string, catalog: ServerCatalog | undefined, override: string | undefined) => string;
-export declare const runtimeServerSummary: (name: string, catalog: ServerCatalog | undefined, override: string | undefined) => RuntimeSummaryDecl;
+export declare const serverSummary: (name: string, catalog: ServerCatalog | undefined) => string;
+export declare const runtimeServerSummary: (name: string, catalog: ServerCatalog | undefined) => RuntimeSummaryDecl;
 export type ToolResultShape = {
     readonly content?: readonly ContentBlock[];
     readonly structuredContent?: unknown;
@@ -20,7 +20,7 @@ export default class McpExecutor extends BaseExecutor {
     constructor(metadata: {
         runtime: string;
         glyph: string;
-    }, connection: ServerConnection, retainWorkspace: () => () => void, policy?: Partial<ToolPolicy>, toolSummaries?: ReadonlyMap<string, string>);
+    }, connection: ServerConnection, retainWorkspace: () => () => void, policy?: Partial<ToolPolicy>);
     get channels(): Readonly<Record<string, ChannelDecl>>;
     effect(target: string | null): Effect;
     get publishedChannel(): string;

package/dist/McpExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"McpExecutor.d.ts","sourceRoot":"","sources":["../src/McpExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EAIf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACR,WAAW,EACX,MAAM,EACN,QAAQ,EACR,UAAU,EAEV,mBAAmB,EACnB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,gBAAgB,EAAE,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,8BAA8B,CAAC;AAGjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiB9C,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,aAAa,GAAG,SAAS,YACxB,MAAM,GAAG,SAAS,KAC7B,MAOF,CAAC;AAGF,eAAO,MAAM,oBAAoB,SACvB,MAAM,WACH,aAAa,GAAG,SAAS,YACxB,MAAM,GAAG,SAAS,KAC7B,kBAKF,CAAC;AAMF,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,eAAO,MAAM,cAAc,WAAkB,eAAe,WAAW,MAAM,UAAU,QAAQ,CAAC,OAAO,CAAC,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAqBvJ,CAAC;AAwBF,eAAO,MAAM,WAAW,SAAU,MAAM,WAAW,kBAAkB,eAAe,OAAO,iBAAiB,MAAM,KAAG,WAenH,CAAC;AAuBH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,YAAY;;IAoBjD,YACI,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAC5C,UAAU,EAAE,gBAAgB,EAC5B,eAAe,EAAE,MAAM,MAAM,IAAI,EACjC,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM,EAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAQ9C;IAED,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAOpD;IAEQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAK7C;IAED,IAAa,gBAAgB,IAAI,MAAM,CAEtC;IAgCD,YAAY,IAAI,mBAAmB,CAKlC;IAED,IAAI,OAAO,IAAI,aAAa,CAK3B;IAEc,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CASvE;IAEK,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqBzE;IAEK,GAAG,CAAC,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAsHhC;CACJ"}
+{"version":3,"file":"McpExecutor.d.ts","sourceRoot":"","sources":["../src/McpExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,YAAY,EAIf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACR,WAAW,EACX,MAAM,EACN,QAAQ,EACR,UAAU,EAEV,mBAAmB,EACnB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,gBAAgB,EAAE,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,8BAA8B,CAAC;AAGjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAY9C,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,aAAa,GAAG,SAAS,KACnC,MAOF,CAAC;AAGF,eAAO,MAAM,oBAAoB,SACvB,MAAM,WACH,aAAa,GAAG,SAAS,KACnC,kBAKF,CAAC;AAMF,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,eAAO,MAAM,cAAc,WAAkB,eAAe,WAAW,MAAM,UAAU,QAAQ,CAAC,OAAO,CAAC,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAqBvJ,CAAC;AAwBF,eAAO,MAAM,WAAW,SAAU,MAAM,WAAW,kBAAkB,eAAe,OAAO,iBAAiB,MAAM,KAAG,WAenH,CAAC;AAuBH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,YAAY;;IAoBjD,YACI,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAC5C,UAAU,EAAE,gBAAgB,EAC5B,eAAe,EAAE,MAAM,MAAM,IAAI,EACjC,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM,EAMnC;IAED,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAOpD;IAEQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAK7C;IAED,IAAa,gBAAgB,IAAI,MAAM,CAEtC;IAyBD,YAAY,IAAI,mBAAmB,CAKlC;IAED,IAAI,OAAO,IAAI,aAAa,CAK3B;IAEc,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CASvE;IAEK,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsBzE;IAEK,GAAG,CAAC,EACN,OAAO,EACP,IAAI,EACJ,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,GACR,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CA0HhC;CACJ"}