@mindot/will 0.1.1 → 0.2.0

package/README.md

@@ -114,6 +114,40 @@ const revived = await Will.wake(pma, { name: 'Aria' })
 
 `will.state()` returns a compact read of the mind (energy, mood, goals, beliefs, self-narrative). Drop to `will.stem` for the full `WillStem` contract at any time. Runnable: [`examples/effectors.ts`](examples/effectors.ts).
 
+### The MCP server — a persistent mind in Claude Desktop / Claude Code
+
+Host a Will over the [Model Context Protocol](https://modelcontextprotocol.io) — any MCP client can then live alongside a persistent mind that **remembers across sessions** (it hibernates to a Persistent Mind Artifact on shutdown and wakes as the same self on the next boot):
+
+```json
+{
+  "mcpServers": {
+    "will": {
+      "command": "npx",
+      "args": ["-y", "@mindot/will", "mcp"],
+      "env": {
+        "WILL_NAME": "Aria",
+        "WILL_IDENTITY": "I am Aria, a calm, precise research assistant."
+      }
+    }
+  }
+}
+```
+
+The surface keeps the paradigm: `perceive` delivers a stimulus (it returns when *delivered*, not answered), `next_utterance` awaits the mind's next words (**silence is a valid outcome**, reported — never an error), `state` reads its inner life, and `save` checkpoints it without stopping it. There is deliberately no `ask()`-shaped tool. Config via env: `WILL_TIER` (basic|standard|full), `WILL_LLM` (mock|anthropic — defaults to the zero-key mock unless `ANTHROPIC_API_KEY` is set), `WILL_TICK_MS`, `WILL_PMA_PATH`.
+
+**The other direction — a Will *employing* MCP tools.** Any MCP server's tools can become the Will's own *abilities*: each tool registers as a learnable affordance (its description is the ability's meaning, surfaced to the mind's deliberation), the **Will decides when to enact one** — nothing dispatches tools at it — and outcomes feed its reafference loop, so it gets *skilled* at the tools it uses. Arguments come from conscious intent: the executive supplies them in an action's `args`.
+
+```typescript
+import { connectMcpEffectors } from '@mindot/will/mcp'
+
+const { names } = await connectMcpEffectors(will, {
+  command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+})
+// the Will can now choose to read/write files — when IT wants to
+```
+
+The hosted server composes with this: set `WILL_MCP_SERVERS` (a JSON array of `{command,args}` or `{url}` entries) and the mind you host in Claude Desktop itself employs those servers' tools.
+
 ### The `WillStem` contract — full control
 
 The lower-level engine surface the facade wraps (explicit tick listeners, the outbox drain, the effector ack loop, PMA distill/load) — for hosts that manage many Wills, custom transports, or replay. The rest of this section walks it end to end.
@@ -677,7 +711,7 @@ src/
 bun run build          # tsup → dist/index.js + dist/index.d.ts
 bun run dev:build      # tsup --watch (auto-rebuilds on save)
 bun run typecheck      # tsc --noEmit
-bun test               # unit tests (Vitest)
+bun test               # unit tests (Bun runner — what CI runs); `bun run test` = Vitest
 ```
 
 The build uses [tsup](https://tsup.egoist.dev) (esbuild). All `#`-prefixed internal path aliases (`#core`, `#cognition`, `#stem`, …) are resolved at build time. The LLM and vector layers are in-house — no Mastra / ai-sdk runtime dependency.
@@ -738,8 +772,9 @@ The provider layer is an in-house `fetch` client (`src/llm/index.ts`) with a glo
 ```bash
 bun dev            # Start the standalone runner (hot-reloads via Bun)
 bun run typecheck  # tsc --noEmit
-bun test           # Unit tests (Vitest)
-bun test:watch     # Watch mode
+bun test           # Unit tests (Bun runner — what CI runs)
+bun run test       # Same suite under Vitest
+bun test:watch     # Watch mode (Vitest)
 ```
 
 Debug prompts are written to `data/wills/<id>/debug/` on every executive call — inspect the full prompt + raw LLM output at each tick.