@mindot/will 0.1.1 → 0.3.0

package/README.md

@@ -19,6 +19,8 @@ Regulatory → Perceptual → Affective → Memory → Executive → Meta-cognit
 
 The mind is not re-derived from a prompt each run. It **accretes**: traits develop from experience, beliefs consolidate, skills proceduralise, and a coherent self carries across restarts as a portable, eval-verified artifact.
 
+Embed it four ways — [**SDK facade**](#the-will-sdk-facade--recommended) (Node/TS) · [**Claude Desktop via MCP**](#the-mcp-server--a-persistent-mind-in-claude-desktop--claude-code) · [**MCP tools as its abilities**](#employing-mcp-tools--the-mind-gets-abilities) · [**HTTP sidecar / Docker**](#the-http-sidecar--will-serve-any-language-or-docker) (any language). [Pick a surface →](#use-it-in-your-project)
+
 ---
 
 ## What makes it different
@@ -82,7 +84,16 @@ ticks — or earlier when physiology demands it.
 
 ## Use it in your project
 
-Runs anywhere **Node 18+ or Bun** runs (the engine is Node-compatible; Bun is the primary target). Two entry points:
+Runs anywhere **Node 18+ or Bun** runs (the engine is Node-compatible; Bun is the primary target). **Four surfaces**, one paradigm — you *perceive* things to a mind and *observe what it projects*; it may act, speak, or stay silent, and it persists across restarts via its [PMA artifact](#pma--the-persistent-mind-artifact):
+
+| Surface | You are… | Start with |
+|---|---|---|
+| [**SDK facade**](#the-will-sdk-facade--recommended) | a Node/TypeScript app embedding a mind | `import { Will } from '@mindot/will'` |
+| [**MCP host**](#the-mcp-server--a-persistent-mind-in-claude-desktop--claude-code) | Claude Desktop / Claude Code / an IDE | `npx -y @mindot/will mcp` |
+| [**MCP tools as abilities**](#employing-mcp-tools--the-mind-gets-abilities) | giving the mind tools it *chooses* to use | `import { connectMcpEffectors } from '@mindot/will/mcp'` |
+| [**HTTP sidecar**](#the-http-sidecar--will-serve-any-language-or-docker) | Python, Go, a game server — any language, or Docker | `npx -y @mindot/will serve` |
+
+(Power users can drop below all four to the [`WillStem` contract](#the-willstem-contract--full-control).)
 
 ### The `Will` SDK facade — recommended
 
@@ -114,6 +125,61 @@ 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`.
+
+### Employing MCP tools — the mind gets abilities
+
+The other direction from hosting: 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 HTTP sidecar — `will serve` (any language, or Docker)
+
+Not on Node? Host the mind as a sidecar and speak to it over HTTP from Python, Go, a game server — anything:
+
+```bash
+npx -y @mindot/will serve          # http://127.0.0.1:7777, or: docker build -t will . && docker run -p 7777:7777 -v will-data:/data will
+```
+
+```bash
+curl -X POST localhost:7777/perceive -H 'content-type: application/json' \
+     -d '{"text":"Hello there.","from":"sam","speaker":"Sam"}'   # 202 — delivered, not answered
+curl 'localhost:7777/next-utterance?within_ms=8000&from=sam'     # its next words, or {"silence":true}
+curl localhost:7777/state                                        # its inner life
+curl -N localhost:7777/utterances                                # SSE: utterance / emotion / action projections
+curl -X POST localhost:7777/save                                 # checkpoint without stopping
+```
+
+Same paradigm, same env config, same persistence as the MCP host: the mind hibernates to its PMA artifact on shutdown and wakes as the same self on the next start (in Docker, mount `/data` to keep it across container restarts). There is deliberately no `/ask` route.
+
 ### 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 +743,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 +804,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.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node