@plurnk/plurnk-mcp 1.20.0 → 1.21.1

package/SPEC.md

@@ -265,7 +265,7 @@ remain in the linked input-contract documents. With tools, the runtime declares
 complete effective menu in the family Summary and survey row
 ({§scheme-catalog-aside}). Without authored 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
+```` ```server (tool) <!-- one-liner --> ````, so the discovery row teaches the
 call ({§tools-resource-materialization}). Summary companions expand `${NAME}`
 references like every other companion.
 

package/docs/mcp.md

@@ -1,82 +1,70 @@
 # mcp
 
 An MCP server publishes tools, and an enabled server is a runtime here under
-its own name. You run a tool the way you run `sh` or `node`: a fenced call
-names the server and the tool, and its body is the tool's JSON arguments.
+its own name. A tool runs the way `sh` or `node` runs: a fenced call names the
+server and the tool, and its body is the tool's JSON arguments.
 
-````files (list_directory) <!-- server (tool) -->
+```files (list_directory) <!-- server (tool) -->
 {"path": "/absolute/project/path"}
-````
+```
 
 One fenced call runs one tool, and the result is that call's output.
 `worker:///_plurnk/tools/<server>.md` lists a server's invocations and their
 required top-level inputs; each invocation links to the complete raw input
-schema when you need more detail.
-
-## When to reach for a server
-
-- The turn-0 catalog lists every enabled server's document. Prefer a published
-  tool over reimplementing the same capability in `sh` or `node`.
-- The user names a server or a tool that is not listed: `list` shows every
-  configured server, including disabled ones and unavailable ones with their
-  exact Problem; `enable` turns a configured server on.
-- Nothing configured fits: `discover` inspects a server before anything is
-  attached.
+schema. The turn-0 catalog lists every enabled server's document. `list`
+shows every configured server, including disabled ones and unavailable ones
+with their exact Problem; `enable` turns a configured server on; `discover`
+inspects a server before anything is attached.
 
 ## discover, then add
 
 `discover` takes `{"source": "<URL or command line>"}`: the server is
 connected once, its tool list is read, and one inert candidate comes back
-carrying the exact definition to add. Discovery never persists or enables a server definition.
+carrying the exact definition to add. Discovery never persists or enables a
+server definition.
 
-````mcp (discover) <!-- inspect before adding -->
+```mcp (discover) <!-- inspect before adding -->
 {"source": "npx -y @modelcontextprotocol/server-filesystem /absolute/project/path"}
-````
+```
 
 `add` persists the definition for this workspace, connects, and enables it
-atomically. It is a host effect: it proposes and runs only on acceptance.
+atomically. It is a host effect, admitted under the loop's policy.
 
-````mcp (add)
+```mcp (add)
 {"alias": "files", "definition": {"name": "files", "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/project/path"]}}
-````
+```
 
-A `stdio` definition carries `command` and optional `args`, `cwd`; an
-`http` definition carries `url` and optional `headers`. `tools` narrows the
-enabled tool set and `read` names the tools that are read-only (every other
-tool keeps the conservative `host` effect and proposes before it runs). A
-credential is a symbolic reference such as `"${TOKEN}"` to the operator's
-environment, never a pasted secret.
+A `stdio` definition carries `command` and optional `args`, `cwd`; an `http`
+definition carries `url` and optional `headers`. `tools` narrows the enabled
+tool set and `read` names the tools that are read-only; every other tool keeps
+the conservative `host` effect. A credential is a symbolic reference such as
+`"${TOKEN}"` to the operator's environment, never a pasted secret.
 
-Local servers start in their workspace's server directory under `XDG_STATE_HOME`
-(normally `~/.local/state/plurnk`), not in the project. Use absolute paths for
-project inputs and outputs, or set `cwd` explicitly when a server requires it.
-State survives reconnects and disable/remove; a discovery probe uses a temporary
-directory removed after it closes. This is file placement, not a sandbox.
+Local servers start in their workspace's server directory under
+`XDG_STATE_HOME` (normally `~/.local/state/plurnk`), not in the project:
+project inputs and outputs are absolute paths, or `cwd` is set explicitly when
+a server requires it. State survives reconnects and disable/remove; a discovery
+probe uses a temporary directory removed after it closes. This is file
+placement, not a sandbox.
 
 ## Environment
 
-Set workspace variables with the `env` family (`worker:///_plurnk/plurnk/env.md`)
-before discovering or adding a local server. Worker-local overrides do not configure
-shared MCP processes.
-
-````env (add)
-{"scope":"workspace","alias":"NODE_ENV","definition":{"value":"production"}}
-````
-
-A running server keeps its launch environment; `disable` then `enable` restarts
-that server with the current workspace values. No daemon restart is needed.
+Workspace variables, set with the `env` family (`env.md`) before discovering
+or adding a local server, reach every server launch; worker-local overrides do
+not. A running server keeps its launch environment; `disable` then `enable`
+restarts it with the current workspace values, without a daemon restart.
 
 ## Authorization
 
 An `http` server that needs OAuth comes up `authorization-required` with an
-authorization URL. Only the user can complete that step, from
-their client; afterwards `enable` retries and the tools appear. Do not try to
-fetch the authorization URL or supply credentials in a body.
+authorization URL. That step is the user's, from their client; a body carries
+no credentials and the URL is not a resource to READ. Afterwards `enable`
+retries and the tools appear.
 
 ## Lifecycle
 
 `disable` withdraws a server's tools while keeping its definition; `remove`
 deletes a workspace definition. Operator-configured servers
-(`PLURNK_MCP_<server>` in the service environment) can only be disabled. When
-a server's published tools change, its document is regenerated; `FIND` the
-reference again after enabling before relying on a tool's signature.
+(`PLURNK_MCP_<server>` in the service environment) are disable-only. The
+family document projects the enabled-tool snapshot: after `enable`, FIND the
+reference again before relying on a tool's signature.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plurnk/plurnk-mcp",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "description": "Current Model Context Protocol host module for Plurnk.",
   "keywords": [
     "plurnk",
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/client": "2.0.0",
-    "@plurnk/plurnk-contracts": "1.20.0"
+    "@plurnk/plurnk-contracts": "1.21.1"
   },
   "devDependencies": {
     "@modelcontextprotocol/conformance": "0.2.0-alpha.11",
@@ -64,7 +64,7 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@plurnk/plurnk-execs": "^1.20.0",
-    "@plurnk/plurnk-schemes": "^1.20.0"
+    "@plurnk/plurnk-execs": "^1.21.1",
+    "@plurnk/plurnk-schemes": "^1.21.1"
   }
 }