@plurnk/plurnk-mcp 1.6.1 → 1.8.0

package/.env.defaults

@@ -5,15 +5,42 @@
 PLURNK_MCP_CONNECT_TIMEOUT=30000
 PLURNK_MCP_REQUEST_TIMEOUT=86400000
 
-# Each configured server becomes `## EXEC0 [server]` and server://.
+# Configured servers are available to clients. Only this exact JSON-array
+# subset connects and becomes model-visible by default; workspaces may override it.
+PLURNK_MCP_ENABLED=[]
+
+# Turn 0 surveys enabled tool FAMILIES (one row per server, summary = its
+# one-liner). Servers named here also expand their complete tool tree into
+# the turn-0 survey:
+# PLURNK_MCP_EXPANDED=[]
+
+# Each configured server contributes its enabled `[server] (tool)` rows and server:// resources.
 #
 # Streamable HTTP:
 # PLURNK_MCP_github=https://example.test/mcp
-# PLURNK_MCP_github_HEADERS={"Authorization":"Bearer ${GITHUB_TOKEN}"}
+# PLURNK_MCP_github_BEARER=${GITHUB_TOKEN}
+# PLURNK_MCP_github_TOOLS=["issue_read","issue_search"]
+# PLURNK_MCP_github_READ=["issue_read","issue_search"]
 #
-# stdio: the target is one executable. Arguments are a JSON array so Plurnk
-# does not invent or interpret a shell command language.
+# stdio: the target is one exact executable path/name, including whitespace.
+# Arguments are a JSON array so Plurnk does not invent or interpret a shell.
 # PLURNK_MCP_atlas=node
 # PLURNK_MCP_atlas_ARGS=["/absolute/path/to/atlas-server.mjs"]
 # PLURNK_MCP_atlas_CWD=/absolute/working/directory
 # PLURNK_MCP_atlas_ENV={"TOKEN":"${ATLAS_TOKEN}"}
+#
+# npx (installed-on-demand executables) — the documented Brave Search fixture,
+# demo-tier only; credentials stay one ${NAME} reference in the operator env:
+# 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"]
+#
+# _SUMMARY companions are fallbacks only — declare one when the server's own
+# summary metadata is missing, confusing, or garbage. The family row can carry
+# its flagship invocation form directly:
+# PLURNK_MCP_BRAVE_SUMMARY=EXEC [brave] (brave_web_search) <!-- Retrieve web results -->
+# PLURNK_MCP_BRAVE_BRAVE_WEB_SEARCH_SUMMARY=General web search.
+#
+# Then list it above to make it model-visible, e.g. PLURNK_MCP_ENABLED=["brave"].

package/README.md

@@ -1,35 +1,128 @@
 # @plurnk/plurnk-mcp
 
 The current [Model Context Protocol](https://modelcontextprotocol.io/) host
-module for [Plurnk](https://github.com/plurnk/plurnk-service).
+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 module's own wire authority is protocol revision `2026-07-28`
+({§mcp-authority}). Connection setup negotiates-and-degrades: a server that
+offers the pinned revision and `server/discover` gets the complete extension
+wire; a server the SDK negotiated below the pin is an ordinary MCP peer that
+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
+
+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 workspace servers without restarting the daemon. An
+existing AG-UI connection sends the ordinary management-action form under
+`forwardedProps.plurnk.action`:
+
+```json
+{
+  "forwardedProps": {
+    "plurnk": {
+      "workspace": "example",
+      "action": {
+        "kind": "workspace.mcp.add",
+        "alias": "project",
+        "target": "/opt/mcp/current-server",
+        "options": {
+          "args": ["--stdio"],
+          "env": { "PROJECT_TOKEN": "${PROJECT_TOKEN}" },
+          "tools": ["issue_read", "issue_write"],
+          "read": ["issue_read"]
+        }
+      }
+    }
+  }
+}
+```
+
+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.
 
-Each configured MCP server becomes a model-facing executor and resource
-authority:
+Available workspace actions are:
 
-```plurnk
-## READ0 (github:///)
+| Action | Parameters |
+|---|---|
+| `workspace.mcp.list` | optional client `overlay` |
+| `workspace.mcp.add` | `alias`, `target`; optional `options` |
+| `workspace.mcp.enable` | `alias`; optional client `overlay` and explicit `options` |
+| `workspace.mcp.disable` | `alias` |
+| `workspace.mcp.remove` | `alias` |
+| `workspace.mcp.oauth.complete` | `alias`, complete `callbackUrl` |
+| `workspace.mcp.complete` | `server`, completion `ref` and `argument`; optional `context` |
 
-## EXEC0 [github] (create_issue)
-{"title":"Bug"}
+The owning [specification](./SPEC.md) defines the complete action and server
+definition contracts.
 
-## FIND0 (github:///resources/**)
+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:
 
-## READ0 (github:///resources/https%3A%2F%2Fexample.test%2Fdocument)
+```text
+# $XDG_CONFIG_HOME/plurnk/.env, read by the service
+PLURNK_MCP_GITEA=/usr/local/bin/possumtech-gitea-mcp
+PLURNK_MCP_ENABLED=[]
+
+# <project>/.env, read by the client
+PLURNK_MCP_GITEA_ARGS=["plurnk_pk"]
 ```
 
-The module requires protocol revision `2026-07-28`. It does not negotiate or
-fall back to a legacy revision.
+The client carries its raw declarations while listing and enabling. Listing is
+inert. `/mcp enable gitea` (or `plurnk mcp enable gitea` in a named workspace)
+composes service, durable workspace, client, and optional command-file fields
+in that order, prepares the connection, then persists the complete unexpanded
+workspace specialization. Arrays and maps replace rather than append or merge.
+
+## 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 (above) 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=[]
+```
 
-## Configuration
+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.
 
-Configuration is daemon-owned. One `PLURNK_MCP_<server>` variable declares
-each server; the suffix case-folds to the executor and URI authority name.
+**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 — verified live: the demo story
+`{§web-search-retrieval}` researched through the real Brave MCP tool and
+answered from it.
+
+## Service defaults
+
+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.
 
 Streamable HTTP:
 
 ```text
 PLURNK_MCP_github=https://example.test/mcp
-PLURNK_MCP_github_HEADERS={"Authorization":"Bearer ${GITHUB_TOKEN}"}
+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:
@@ -41,33 +134,59 @@ PLURNK_MCP_local_CWD=/absolute/working/directory
 PLURNK_MCP_local_ENV={"TOKEN":"${LOCAL_TOKEN}"}
 ```
 
-The stdio target is exactly one executable. Arguments are a JSON array; the
-module never parses or invokes a shell command. `${NAME}` references read the
-daemon's inherited environment at startup, so secrets do not need to be copied
-into Plurnk environment files.
-
-Portable timeout defaults and complete examples live in
-[`.env.defaults`](./.env.defaults).
-
-## Current surface
-
-- `## READ0 (server:///)` returns the live tools, resources, resource templates, and
-  prompts catalog.
-- `## EXEC0 [server] (tool)` calls a tool with one JSON object in the body.
-- `server:///resources` exposes the resource catalog through ordinary Plurnk
-  `FIND` and `READ` sections.
-- `server:///resources/<encoded-uri>` reads a concrete MCP resource and stores
-  it as an ordinary entry, after which normal projection and slicing apply.
-- A tool's `readOnlyHint` selects Plurnk's read effect. Unknown or mutating
-  tools retain the host effect.
-
-Prompt retrieval, resource subscriptions, current multi-round-trip input,
-current task methods, and OAuth/OIDC authorization are not part of this
-vertical slice. They will use the same module and connection seams; no legacy
-protocol surface is retained as a fallback.
+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.
+
+`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).
+
+## Plurnk projection
+
+| MCP surface | Plurnk surface |
+|---|---|
+| Server tools | `worker://plurnk/tools/<server>.md` family summary |
+| Enabled tool | Exact `worker://plurnk/tools/<server>/<encoded-tool>.md` document and `## EXEC0 [server] (tool)` |
+| Resource catalog | `server:///` or `server:///resources` |
+| Resource | `server:///resources/<encoded-uri>` through ordinary `FIND` and `READ` |
+| Prompt catalog | `server:///prompts` |
+| Prompt retrieval | `server:///prompts/<encoded-name>?argument=value` through ordinary `READ` |
+| Completion | Client-owned `workspace.mcp.complete` action |
+
+Tool results, resource bodies, prompt messages, and failures become ordinary
+Plurnk entries and channels. Disabled tools appear in neither teaching nor
+admission. There is no MCP-specific model discovery grammar.
+
+Current pagination, cache hints, unified subscriptions, progress,
+cancellation, multi-round-trip input, elicitation, and negotiated Tasks remain
+inside the owning operation. Client input uses the standard AG-UI interrupt and
+resume lifecycle; protocol continuation state is never exposed to the model or
+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.
 
 ## Verification
 
-`npm test` type-checks the module and exercises exact current-version
-negotiation, configuration, tool calls, resource reads, runtime registration,
-and rejection of ambiguous shell and secret configuration.
+```sh
+npm test -w @plurnk/plurnk-mcp
+npm run test:mcp:dogfood -w @plurnk/plurnk-service
+```
+
+The package gate runs the exact current SDK and official conformance
+requirements. The opt-in dogfood gate composes representative current stdio
+and Streamable HTTP servers through the assembled daemon and AG-UI product.