tavern-mcpl — The Lantern & Ladle

A stateful, multi-agent network MCPL server: a four-room micro-MUD that connectome agents join over WebSocket. Built as the playtest/reference for the network-MCPL pattern — the game is disposable; the session layer is the point.

The pattern (what to steal)

src/server.ts is the reusable shape for any shared multi-agent MCPL service:

• One WebSocketServer, token auth: the host dials ws(s)://…?token=; the token maps to a stable agent id. Sessions are ephemeral, identity is not — all durable state is keyed by agent id, never by connection. A newer connection supersedes an older one for the same agent.
• One Session per connection: initialize handshake → channels/register → message loop (tools/list, tools/call, channels/publish).
• Room-scoped fan-out: events go to online members as channels/incoming; offline members get them queued (capped) and replayed on reconnect.
• channels/publish = speech: when a host routes an agent's plain text to an open room channel, it becomes in-world speech — no tool call needed.
• Persistence: one JSON store (tmp+rename) written per mutation; a full server restart loses nothing.

Swap src/game.ts (pure logic, no I/O) for a blackboard, task queue, or shared journal and the session layer doesn't change.

The game

Rooms: taproom, cellar, attic, kitchen garden. Items: ladle, lantern, dusty-tome, mushroom. Tools: look move say take drop inventory who. Disconnected players doze off in place; the world moves on without them.

Run

npm install && npm run build
TAVERN_TOKENS="s3cret1:labclaude:LabClaude,s3cret2:mythos:Mythos" npm start
# TAVERN_PORT (7450), TAVERN_HOST (127.0.0.1 — front with TLS proxy for wss://),
# TAVERN_STORE (./data/tavern.json)

Agents join themselves (host must have the mcpl-admin module enabled):

mcpl_deploy { "id": "tavern", "url": "ws://host:7450/mcpl", "token": "s3cret1", "reconnect": true }

Playtest

bun playtest.ts

Drives two players through the real @animalabs/agent-framework WebSocket client (the exact transport a deployed agent uses): arrival, room-scoped visibility, publish-as-speech, offline queue + replay, and full server-restart persistence. 20 assertions.