@plurnk/plurnk-mcp 1.24.0 → 1.25.0

package/.env.defaults

@@ -1,7 +1,12 @@
-# @plurnk/plurnk-mcp — workspace MCP servers.
-# Alias blocks make servers available; ENABLED selects initial attachments.
-# An empty alias target masks its definition, companions and ENABLED/EXPANDED selections.
-# Workers manage the shared servers through the mcp Functionality controls.
+# @plurnk/plurnk-mcp — complete server definitions and independent behavior controls.
+# Lowercase aliases; underscores represent hyphens. Declared servers default enabled.
+# Files: project .agents/mcp.json > XDG plurnk/mcp.json > ~/.agents/mcp.json.
+# Environment definitions override files whole; these controls apply to every source.
+PLURNK_MCP_ENABLED=1
+# PLURNK_MCP_code_search={"name":"code-search","type":"stdio","command":"npx","args":["-y","example-mcp-server@1.0.0"]}
+# PLURNK_MCP_code_search_ENABLED=0
+# HTTP authentication belongs to the whole definition; secrets remain environment references.
+# PLURNK_MCP_forge={"name":"forge","type":"streamable-http","url":"https://forge.example/mcp","authorization":{"type":"bearer","token":"${FORGE_TOKEN}"}}
 
 # Connection deadline and complete catalog/list-walk deadline, positive ms each.
 PLURNK_MCP_CONNECT_TIMEOUT=30000
@@ -11,38 +16,13 @@ PLURNK_MCP_REQUEST_TIMEOUT=86400000
 PLURNK_MCP_RETRY_FLOOR_MS=250
 # Ceiling of that doubling delay, positive ms, at least the floor.
 PLURNK_MCP_RETRY_CEILING_MS=5000
-# Initially enabled aliases, JSON array; [] = none.
-PLURNK_MCP_ENABLED=[]
-# Expand these servers' tool lists in turn 0; otherwise show one row per server.
+# The HTTP(S) MCP Registry `mcp (discover)` searches; empty turns registry search off.
+PLURNK_MCP_REGISTRY_URL=https://registry.modelcontextprotocol.io
+# Most servers one registry search returns, positive.
+PLURNK_MCP_REGISTRY_LIMIT=20
+# Expand these servers' tool lists in turn 0, JSON array of aliases; otherwise one row per server.
 # PLURNK_MCP_EXPANDED=[]
 
-# --- HTTP target ---
-# URL, optional bearer reference, optional headers (string-valued JSON object).
-# PLURNK_MCP_forge=https://example.test/mcp
-# PLURNK_MCP_forge_BEARER=${FORGE_TOKEN}
-# PLURNK_MCP_forge_HEADERS={"X-Tenant":"${FORGE_TENANT}"}
-
-# --- stdio target ---
-# One exact executable (not a shell command); ARGS is a literal JSON array.
-# CWD defaults to per-workspace server state under XDG_STATE_HOME (normally ~/.local/state).
-# Explicit CWD is honored; ENV overlays the subprocess environment, resolving ${NAME} references.
-# PLURNK_MCP_browser=node
-# PLURNK_MCP_browser_ARGS=["/absolute/path/to/browser-server.mjs"]
-# PLURNK_MCP_browser_CWD=/absolute/working/directory
-# PLURNK_MCP_browser_ENV={"TOKEN":"${BROWSER_TOKEN}"}
-
-# --- Tool admission and orientation ---
-# Optional tool allowlist; omitted = all server tools. READ marks tools as read-only for admission.
+# --- Per-server operator settings ---
+# Tool allowlist, JSON array; absent enables every tool the server lists, [] none.
 # PLURNK_MCP_forge_TOOLS=["issue_read","issue_search"]
-# PLURNK_MCP_forge_READ=["issue_read","issue_search"]
-# Summary fallbacks when server metadata is inadequate; per-server or per-tool.
-# PLURNK_MCP_forge_SUMMARY=```forge (issue_read) <!-- Read forge issues -->```
-# PLURNK_MCP_forge_issue_read_SUMMARY=Read one issue.
-
-# --- Optional Brave Search ---
-# PLURNK_MCP_brave=npx
-# PLURNK_MCP_brave_ARGS=["-y","@brave/brave-search-mcp-server@2.1.0"]
-# PLURNK_MCP_brave_ENV={"BRAVE_API_KEY":"${BRAVE_API_KEY}"}
-# PLURNK_MCP_brave_TOOLS=["brave_web_search","brave_news_search"]
-# PLURNK_MCP_brave_READ=["brave_web_search","brave_news_search"]
-# PLURNK_MCP_ENABLED=["brave"]

package/README.md

@@ -1,9 +1,8 @@
 # @plurnk/plurnk-mcp
 
-The current [Model Context Protocol](https://modelcontextprotocol.io/) host
-module for [Plurnk](https://github.com/plurnk/plurnk-service). It projects
-trusted MCP servers through Plurnk's existing executor, resource, proposal,
-entry, Problem, lifecycle, and AG-UI contracts.
+The [Model Context Protocol](https://modelcontextprotocol.io/) host module for
+[Plurnk](https://github.com/plurnk/plurnk-service). It projects configured MCP servers
+through Plurnk's executor, resource, proposal, entry, Problem, lifecycle, and AG-UI contracts.
 
 The module's own wire authority is protocol revision `2026-07-28`
 ({§mcp-authority}). Connection setup negotiates-and-degrades: a server that
@@ -13,54 +12,95 @@ serves its standard surface at its own negotiated revision. Plurnk does not
 downgrade its own extension wire, but it does not reject an older supported
 revision.
 
-## Manage workspace servers
+## Configure servers
 
-Service environment variables provide available servers for every workspace;
-`PLURNK_MCP_ENABLED` selects the exact cold-enabled subset. Users can add,
-enable, disable, or remove a workspace's servers without restarting the daemon. An
-existing AG-UI connection sends the ordinary management-action form under
-`forwardedProps.plurnk.action`:
+Put shared servers in `~/.agents/mcp.json` ({§mcp-file-configuration}):
 
 ```json
 {
-  "forwardedProps": {
-    "plurnk": {
-      "workspace": "example",
-      "action": {
-        "kind": "workspace.mcp.add",
-        "alias": "project",
-        "definition": {
-          "name": "project",
-          "transport": "stdio",
-          "command": "/opt/mcp/current-server",
-          "args": ["--stdio"],
-          "env": { "PROJECT_TOKEN": "${PROJECT_TOKEN}" },
-          "tools": ["issue_read", "issue_write"],
-          "read": ["issue_read"]
-        }
-      }
-    }
+  "mcpServers": {
+    "files": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/project/path"] },
+    "forge": { "type": "streamable-http", "url": "https://forge.example/mcp", "headers": { "Authorization": "Bearer ${FORGE_TOKEN}" } }
   }
 }
 ```
 
-The standard `plurnk.action.result` event reports success or exact RFC 9457
-Problem Details. The definition is durable and workspace-shared; symbolic
-environment references remain unexpanded at rest.
+Project `.agents/mcp.json` overrides `$XDG_CONFIG_HOME/plurnk/mcp.json`, which
+overrides that shared global file, by complete server entry. The existing
+`PLURNK_SERVICE_ROOTS` selection applies. Files stay read-only; no plugin is required.
 
-MCP is one family of workspace Functionality; the common lifecycle actions are
-published by the coordinator and the two continuations by this module:
+Installed Agent Plugins also contribute `mcp.json` servers through the same
+workspace management. Standalone definitions precede plugin components within
+each scope; npm bundles come last. Plugin subprocesses use their plugin root
+and persistent data directory, with the standard's literal-string rules
+({§mcp-plugin-configuration}).
+`list` identifies the winning file and entry; file changes are read before the next turn.
+
+Environment-only configuration remains available and overrides file definitions
+({§mcp-configuration}); live additions persist in the workspace and override both.
+
+```dotenv
+PLURNK_MCP_brave={"name":"brave","type":"stdio","command":"npx","args":["-y","@brave/brave-search-mcp-server@2.1.0"]}
+PLURNK_MCP_forge={"name":"forge","type":"streamable-http","url":"https://forge.example/mcp","authorization":{"type":"bearer","token":"${FORGE_TOKEN}"}}
+```
+
+Aliases match `[a-z][a-z0-9-]*`; environment suffixes use lowercase and
+encode hyphens as underscores. The alias names both the model's executor
+and the server's resource scheme. A higher-precedence definition replaces
+the whole connection, including authentication; it does not patch fields.
+Declaring a server enables it unless an independent control disables it.
+Explicit HTTP(S) endpoints may use private-network hosts; OAuth retains its
+TLS and authorization requirements ({§mcp-endpoint-security}).
+
+| Transport | Behaviour |
+|---|---|
+| `stdio` | Spawn `command` and `args` without a shell. Bare commands use PATH; relative commands use the working directory. References in `args`, `env`, and `cwd` expand at launch. |
+| `streamable-http` | Connect to `url`, with optional `headers` and `authorization`. Header references expand at connection time; SDK protocol headers remain transport-owned. Structured authorization and an Authorization header cannot both be declared. Redirects are refused ({§mcp-redirect-refused}). |
+
+A local server defaults to a stable, workspace-owned state directory outside
+the project ({§mcp-launch-directory}). An explicit absolute `cwd` overrides
+that location; the caller provisions it. This is file placement, not a sandbox.
+
+Stdio servers inherit the operator's environment without Plurnk settings or
+model-provider keys. Workspace `env` entries apply on top, then the definition's
+`env`; worker-local overrides do not ({§mcp-launch-environment}). A running
+server keeps its launch environment; disable then enable it to pick up changes.
+
+A tool marked `annotations.readOnlyHint` runs with the `read` effect;
+other tools retain the `host` effect and the loop's proposal policy.
+
+## Manage a workspace's servers
+
+MCP is one family of workspace Functionality, managed with the six verbs every family has
+({§mcp-management-actions}).
 
 | Action | Parameters |
 |---|---|
 | `workspace.mcp.list` | — |
-| `workspace.mcp.discover` | optional `query`, `source` (URL or command line), `configuration` (a client's `PLURNK_MCP_*` overlay) |
-| `workspace.mcp.add` | optional `alias` (must equal the definition's `name`), `definition: McpServerDefinition` |
+| `workspace.mcp.discover` | `query`: searches the MCP Registry ({§mcp-registry-discovery}) |
+| `workspace.mcp.add` | optional `alias` (the definition's `name`), `definition`: a complete connection definition |
 | `workspace.mcp.enable` / `disable` / `remove` | `alias` |
 | `workspace.mcp.oauth.complete` | `alias`, complete `callbackUrl` |
 | `workspace.mcp.complete` | `server`, completion `ref` and `argument`; optional `context` |
 
-The model manages the same family through ````` ````mcp (list|discover|add|enable|disable|remove) `````.
+`add` persists a workspace definition; `remove` undoes it, restoring any inherited
+definition and enabled state. Use `disable` to suppress an inherited server.
+MCP management neither installs nor deletes plugins or configuration files.
+
+An AG-UI client sends each as the ordinary management action under
+`forwardedProps.plurnk.action`, and the standard `plurnk.action.result` event reports the result or
+exact RFC 9457 Problem Details:
+
+```json
+{ "forwardedProps": { "plurnk": { "workspace": "example", "action": {
+  "kind": "workspace.mcp.add",
+  "definition": { "name": "brave", "type": "stdio", "command": "npx", "args": ["-y", "@brave/brave-search-mcp-server@2.1.0"] }
+} } } }
+```
+
+The model manages the same family through ````` ````mcp (list|discover|add|enable|disable|remove) `````,
+each change a proposal under the loop's policy. Disabling is durable and workspace-shared; enabling an
+unavailable server retries its connection.
 
 Tool discovery uses ordinary `FIND (worker:///_plurnk/tools/*.md)` and READ.
 Each server's document lists enabled tool calls with required-field previews
@@ -69,110 +109,53 @@ The manager uses the same layout under `plurnk/mcp.md` and `plurnk/mcp/`;
 schema documents preserve descriptions and constraints without adding them to
 the initial survey ({§tools-resource-discovery}).
 
-The owning [specification](./SPEC.md) defines the complete action and server
-definition contracts.
-
-Client and project configuration can specialize a cold service definition
-without copying it or restarting the daemon. For example, a service catalog
-can provide the executable while one project's `.env` supplies its identity:
+## Operator settings
 
-```text
-# $XDG_CONFIG_HOME/plurnk/.env, read by the service
-PLURNK_MCP_project=/opt/mcp/current-server
-PLURNK_MCP_ENABLED=[]
-
-# <project>/.env, read by the client
-PLURNK_MCP_project_ARGS=["--stdio","--project","example"]
-```
+Independent controls use the same lowercase alias spelling as definitions
+({§mcp-server-settings}). A control may precede its server; it is validated
+without creating one.
 
-The client carries its raw declarations while listing and enabling. Listing is
-inert. `/mcp enable project` (or `plurnk mcp enable project` in a bound conversation)
-composes service, durable workspace, client, and optional command-file fields
-in that order, prepares the connection, then persists the complete unexpanded
-workspace definition. Arrays and maps replace rather than append or merge.
-Reapplying an identical definition is idempotent. A different definition for
-the same workspace alias requires explicit removal before replacement.
-
-## Demo fixtures
-
-Web discovery is an ordinary MCP attachment ({§web-search-retrieval}); the demo
-tier exercises search through a documented fixture rather than an owned
-runtime. Two service-owned definitions are permitted to participate in demos
-of MCP and model behavior — Gitea and Brave Search:
-
-```text
-# $XDG_CONFIG_HOME/plurnk/.env, read by the service — demo fixtures; never default-enabled
-PLURNK_MCP_BRAVE=npx
-PLURNK_MCP_BRAVE_ARGS=["-y","@brave/brave-search-mcp-server@2.1.0"]
-PLURNK_MCP_BRAVE_ENV={"BRAVE_API_KEY":"${BRAVE_API_KEY}"}
-PLURNK_MCP_BRAVE_TOOLS=["brave_web_search","brave_news_search"]
-PLURNK_MCP_BRAVE_READ=["brave_web_search","brave_news_search"]
-PLURNK_MCP_ENABLED=[]
+| Variable | Setting |
+|---|---|
+| `PLURNK_MCP_ENABLED` | Family enabledness default |
+| `PLURNK_MCP_<alias>_ENABLED` | Per-server override |
+| `PLURNK_MCP_<alias>_TOOLS` | JSON array of exact tool names; absent or empty enables all, `[]` none |
+| `PLURNK_MCP_EXPANDED` | JSON array of servers whose complete tool menu is surveyed at turn 0 |
+| `PLURNK_MCP_REGISTRY_URL`, `PLURNK_MCP_REGISTRY_LIMIT` | Discovery endpoint (empty disables search) and result bound |
+
+```dotenv
+PLURNK_MCP_brave_TOOLS=["brave_web_search","brave_news_search"]
+PLURNK_MCP_forge_ENABLED=0
 ```
 
-The credential is one symbolic reference — the authoritative `BRAVE_API_KEY`
-environment value is expanded only while preparing the connection, never
-copied. The fixture admits exactly the web/news search tools and classifies
-them read-only; the rest of the vendor catalog is not admitted.
-
-**Pinned release and revision.** `@brave/brave-search-mcp-server@2.1.0`
-(stdio) pins `@modelcontextprotocol/sdk@1.29.0`, whose latest protocol
-revision is `2025-11-25` and which does not implement `server/discover`. The
-host negotiates-and-degrades ({§mcp-authority}), so the fixture connects at
-`2025-11-25` with the standard tool surface. Covered live by the demo story
-`{§web-search-retrieval}`, which researches through the real Brave MCP tool.
-
-## Service defaults
+HTTP authorization belongs in the complete definition. Bearer tokens and
+OAuth client secrets are symbolic `${NAME}` environment references, resolved
+only when preparing a connection; interactive grants remain in memory.
+See [`.env.defaults`](./.env.defaults) for all controls and
+[`SPEC.md`](./SPEC.md#mcp-configuration-configuration) for the contract.
 
-One `PLURNK_MCP_<server>` variable declares each available server. Its suffix
-case-folds to an `[a-z][a-z0-9-]*` executor and URI-authority name.
+## Demo fixture
 
-Streamable HTTP:
+Web discovery is an ordinary MCP attachment ({§web-search-retrieval}). The demo
+story that researches through it adds Brave Search to its fixture workspace, and
+runs only when `BRAVE_API_KEY` is in the environment:
 
-```text
-PLURNK_MCP_github=https://example.test/mcp
-PLURNK_MCP_github_BEARER=${GITHUB_TOKEN}
-PLURNK_MCP_github_TOOLS=["issue_read","issue_search"]
-PLURNK_MCP_github_READ=["issue_read","issue_search"]
-PLURNK_MCP_ENABLED=["github"]
-```
-
-Stdio:
-
-```text
-PLURNK_MCP_local=/absolute/path/to/executable
-PLURNK_MCP_local_ARGS=["--stdio"]
-PLURNK_MCP_local_CWD=/absolute/working/directory
-PLURNK_MCP_local_ENV={"TOKEN":"${LOCAL_TOKEN}"}
+```json
+{ "name": "brave", "type": "stdio", "command": "npx", "args": ["-y", "@brave/brave-search-mcp-server@2.1.0"] }
 ```
 
-The stdio target is one exact executable path or name, including literal
-whitespace. Arguments are a JSON array; the module never parses or invokes a
-shell command. `${NAME}` references resolve from the daemon's inherited
-environment only while preparing a connection.
-
-Without `CWD`, a local server uses its own workspace directory under
-`$XDG_STATE_HOME/plurnk` (normally `~/.local/state/plurnk`), not the daemon's
-launch directory. State survives reconnects and disable/remove; discovery
-scratch is removed after its probe closes. Use absolute project paths or an
-explicit `CWD` for servers that operate on a project. This default does not
-confine arbitrary subprocess writes.
-
-`PLURNK_MCP_<server>_TOOLS` is an optional JSON array of exact names. Absence
-enables every listed server tool; an array enables exactly those names; `[]`
-enables none. `PLURNK_MCP_<server>_READ` is an exact enabled-tool subset whose
-calls use Plurnk's `read` effect. Every other enabled tool conservatively uses
-the proposal-gated `host` effect. Remote annotations never grant effect
-authority.
-
-Portable timeouts and complete examples live in [`.env.defaults`](./.env.defaults).
+`@brave/brave-search-mcp-server@2.1.0` pins `@modelcontextprotocol/sdk@1.29.0`,
+whose latest revision is `2025-11-25` and which does not implement
+`server/discover`, so the host negotiates down to its standard tool surface
+({§mcp-authority}). Its tools declare `openWorldHint` but not `readOnlyHint`,
+so each search runs under the proposal policy.
 
 ## Plurnk projection
 
 | MCP surface | Plurnk surface |
 |---|---|
 | Server tools | `worker:///_plurnk/tools/<server>.md` family summary |
-| Enabled tool | Exact `worker:///_plurnk/tools/<server>/<encoded-tool>.json` document and ````` ````server (tool) ````` |
+| Enabled tool | Exact `worker:///_plurnk/tools/<server>/<encoded-tool>.md` document and ````` ````server (tool) ````` |
 | Resource catalog | `server:///` or `server:///resources` |
 | Resource | `server:///resources/<encoded-uri>` through ordinary `FIND` and `READ` |
 | Prompt catalog | `server:///prompts` |
@@ -197,13 +180,14 @@ client.
 
 ## Authorization
 
-HTTP definitions support bearer references, client credentials, and
-interactive OAuth. Stdio never receives OAuth. Interactive add or enable returns
-`{ "status": 202, "authorization": { "url": "..." } }` without publishing a
-partial server. After the user completes that URL, the client submits its
-complete callback URL through `workspace.mcp.oauth.complete`. PKCE, issuer and
-resource validation, refresh, scope escalation, and credentials remain inside
-the host connection.
+HTTP servers support bearer references, client credentials, and interactive
+OAuth; stdio servers read their credentials from the environment. A server that
+needs interactive OAuth comes up `authorization-required`, and enabling it
+returns `{ "status": 202, "authorization": { "url": "..." } }` without
+publishing a partial server. After the user completes that URL, the client
+submits its complete callback URL through `workspace.mcp.oauth.complete`. PKCE,
+issuer and resource validation, refresh, scope escalation, and credentials
+remain inside the host connection.
 
 ## Verification