@plurnk/plurnk-mcp 1.7.0 → 1.9.0

package/.env.defaults

@@ -5,6 +5,15 @@
 PLURNK_MCP_CONNECT_TIMEOUT=30000
 PLURNK_MCP_REQUEST_TIMEOUT=86400000
 
+# 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:
@@ -19,3 +28,19 @@ PLURNK_MCP_REQUEST_TIMEOUT=86400000
 # 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

@@ -5,16 +5,21 @@ 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 accepts only protocol revision `2026-07-28`. A legacy endpoint is
-rejected with a `protocol-revision-unsupported` Problem that names the required
-revision and `server/discover`; Plurnk does not negotiate a downgrade.
-
-## Attach a server
-
-Service environment variables provide optional defaults for every workspace.
-Users can also attach, replace, reconnect, or detach a server in one workspace
-without restarting the daemon. An existing AG-UI connection sends the ordinary
-management-action form under `forwardedProps.plurnk.action`:
+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 Worker servers
+
+Service environment variables provide available servers for every Worker;
+`PLURNK_MCP_ENABLED` selects the exact cold-enabled subset. Users can add,
+enable, disable, or remove one Worker's servers without restarting the daemon. An
+existing AG-UI connection sends the ordinary management-action form under
+`forwardedProps.plurnk.action`:
 
 ```json
 {
@@ -22,8 +27,9 @@ management-action form under `forwardedProps.plurnk.action`:
     "plurnk": {
       "workspace": "example",
       "action": {
-        "kind": "workspace.mcp.attach",
-        "server": {
+        "kind": "worker.mcp.add",
+        "alias": "project",
+        "definition": {
           "name": "project",
           "transport": "stdio",
           "command": "/opt/mcp/current-server",
@@ -39,27 +45,78 @@ management-action form under `forwardedProps.plurnk.action`:
 ```
 
 The standard `plurnk.action.result` event reports success or exact RFC 9457
-Problem Details. The definition is durable and workspace-shared; symbolic
+Problem Details. The definition is durable and Worker-private; symbolic
 environment references remain unexpanded at rest.
 
-Available workspace actions are:
+MCP is one family of Worker Functionality; the common lifecycle actions are
+published by the coordinator and the two continuations by this module:
 
 | Action | Parameters |
 |---|---|
-| `workspace.mcp.list` | none |
-| `workspace.mcp.attach` | `server` definition |
-| `workspace.mcp.replace` | `server` definition with the existing name |
-| `workspace.mcp.detach` | `name` |
-| `workspace.mcp.reconnect` | `name` |
-| `workspace.mcp.oauth.complete` | `name`, complete `callbackUrl` |
-| `workspace.mcp.complete` | `server`, completion `ref` and `argument`; optional `context` |
+| `worker.mcp.list` | — |
+| `worker.mcp.discover` | optional `query`, `source` (URL or command line), `configuration` (a client's `PLURNK_MCP_*` overlay) |
+| `worker.mcp.add` | optional `alias` (must equal the definition's `name`), `definition: McpServerDefinition` |
+| `worker.mcp.enable` / `disable` / `remove` | `alias` |
+| `worker.mcp.oauth.complete` | `alias`, complete `callbackUrl` |
+| `worker.mcp.complete` | `server`, completion `ref` and `argument`; optional `context` |
+
+The model manages the same family through `EXEC [mcp] (list|discover|add|enable|disable|remove)`.
 
 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:
+
+```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 client carries its raw declarations while listing and enabling. Listing is
+inert. `/mcp enable gitea` (or `plurnk mcp enable gitea` in a bound conversation)
+composes service, durable worker, client, and optional command-file fields
+in that order, prepares the connection, then persists the complete unexpanded
+worker 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=[]
+```
+
+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 — 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 default server. Its suffix
+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:
@@ -69,6 +126,7 @@ 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:
@@ -98,13 +156,13 @@ Portable timeouts and complete examples live in [`.env.defaults`](./.env.default
 
 | MCP surface | Plurnk surface |
 |---|---|
-| Enabled tool | Exact Registered Tools row and `## EXEC0 [server] (tool)` |
-| Tool schemas | `worker://plurnk/docs/<server>.md` |
+| 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 |
+| Completion | Client-owned `worker.mcp.complete` action |
 
 Tool results, resource bodies, prompt messages, and failures become ordinary
 Plurnk entries and channels. Disabled tools appear in neither teaching nor
@@ -119,10 +177,10 @@ client.
 ## Authorization
 
 HTTP definitions support bearer references, client credentials, and
-interactive OAuth. Stdio never receives OAuth. Interactive attachment returns
+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
+complete callback URL through `worker.mcp.oauth.complete`. PKCE, issuer and
 resource validation, refresh, scope escalation, and credentials remain inside
 the host connection.