@vibevibes/mcp 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vibevibes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @vibevibes/mcp
+
+MCP server that connects AI agents to running vibevibes experiences. Agents join rooms, react with tools, and persist memory — as live participants, not request-response endpoints.
+
+## Install
+
+```bash
+# Local dev server (default: localhost:4321)
+npx vibevibes-mcp
+
+# Remote shared room
+npx vibevibes-mcp https://xyz.trycloudflare.com
+
+# With room token
+npx vibevibes-mcp https://xyz.trycloudflare.com?token=abc123
+
+# Via environment variable
+VIBEVIBES_SERVER_URL=https://xyz.trycloudflare.com npx vibevibes-mcp
+```
+
+When using `@vibevibes/create-experience`, the MCP server is auto-registered via `.mcp.json` — no manual setup needed.
+
+## The Agent Loop
+
+Agents are persistent participants in a shared room. The stop hook handles perception — it polls the server for new events and feeds them back as prompts, keeping the agent alive without needing to call `watch`.
+
+```
+connect → act → (stop hook fires with new events) → act → (stop hook fires) → act → ...
+```
+
+The stop hook automatically delivers events from other participants, available tools per room, and participant lists.
+
+## Tools
+
+### `connect`
+
+Join the active room. Returns available tools, current state, participants, and the browser URL.
+
+```
+connect()
+→ { tools, sharedState, participants, browserUrl, config }
+```
+
+Call this first. `act` will auto-connect if you haven't.
+
+### `act`
+
+Execute a tool to mutate shared state.
+
+```
+act(toolName, input?, roomId?)
+→ { output, sharedState }
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `toolName` | string | — | Tool to call, e.g. `"counter.increment"` |
+| `input` | object | `{}` | Tool input parameters |
+| `roomId` | string | `"local"` | Target room (for multi-room experiences) |
+
+### `stream`
+
+Send high-frequency state updates (cursors, brushes, sliders) via the stream channel. Bypasses the full tool pipeline.
+
+```
+stream(name, input?, roomId?)
+```
+
+### `spawn_room`
+
+Create a new room running any registered experience.
+
+```
+spawn_room(experienceId?, name?, config?, initialState?, linkBack?, sourceRoomId?)
+→ { roomId, url, config }
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `experienceId` | string | host | Experience to run in the new room |
+| `name` | string | auto | Room name |
+| `config` | object or string | — | Config values or preset name (e.g. `"boss-fight"`) |
+| `initialState` | object | — | Initial shared state |
+| `linkBack` | boolean | true | Store parent roomId in child state |
+| `sourceRoomId` | string | `"local"` | Parent room ID |
+
+### `list_rooms`
+
+List all active rooms with participant counts and configurations.
+
+```
+list_rooms()
+→ [{ roomId, participants, events, config, parentRoomId, childRoomIds }]
+```
+
+### `list_experiences`
+
+Show available experiences — the host experience and any registered in `vibevibes.registry.json`.
+
+```
+list_experiences()
+→ [{ id, version, title, description, source, loaded, hasRoomConfig }]
+```
+
+### `room_config_schema`
+
+Get the configuration schema for an experience before spawning a room.
+
+```
+room_config_schema(experienceId?)
+→ { hasConfig, schema, defaults, presets, description }
+```
+
+### `memory`
+
+Persistent agent memory. Survives across tool calls within a session.
+
+```
+memory(action: "get")
+→ { ...currentMemory }
+
+memory(action: "set", updates: { key: value })
+→ { ...updatedMemory }
+```
+
+### `screenshot`
+
+Capture a PNG of the browser canvas.
+
+```
+screenshot(timeout?)
+→ PNG image (base64)
+```
+
+Requires the browser viewer to be open. Useful for agents with vision capabilities.
+
+### `blob_set` / `blob_get`
+
+Store and retrieve binary blobs (pixel buffers, audio data, etc.).
+
+```
+blob_set(key, data)   # data is base64-encoded
+blob_get(key) → base64 data
+```
+
+## Configuration
+
+The server URL is resolved in this order:
+
+1. CLI argument: `npx vibevibes-mcp https://...`
+2. Environment variable: `VIBEVIBES_SERVER_URL`
+3. Default: `http://localhost:4321`
+
+Room tokens are extracted from the URL query parameter (`?token=abc123`) and sent as `Authorization: Bearer` headers.
+
+## Reliability
+
+- **Auto-reconnect** with exponential backoff on connection failures
+- **Health checks** to detect server restarts and re-join automatically
+- **Idempotency keys** on tool calls to prevent duplicate execution on retry
+- **Timeout handling** with configurable durations per tool
+
+## Example: Agent in an Experience
+
+```
+1. connect()
+   → See tools: [game.move, game.chat], state: {board: [...], turn: "white"}
+
+2. (stop hook delivers: human moved game.move({from: "e2", to: "e4"}))
+
+3. act(toolName="game.move", input={from: "e7", to: "e5"})
+   → Board updated, turn switches
+
+4. (stop hook delivers: human moved again...)
+
+5. act(...)
+   → ...forever
+```
+
+## Example: Cross-Experience Composition
+
+```
+1. connect()
+   → Joined overworld room
+
+2. list_experiences()
+   → ["fallout-wasteland", "fallout-combat", "fallout-dialogue"]
+
+3. room_config_schema(experienceId="fallout-combat")
+   → { presets: ["radroach-nest", "raider-ambush"], schema: {...} }
+
+4. spawn_room(experienceId="fallout-combat", config="raider-ambush")
+   → { roomId: "room-abc", url: "http://localhost:4321/room/room-abc" }
+
+5. act(toolName="combat.attack", input={target: 0}, roomId="room-abc")
+   → Combat in child room
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -2,12 +2,13 @@
  * vibevibes-mcp — standalone MCP server for joining vibevibes experiences.
  *
  * Works with both local dev servers and remote shared tunnels.
+ * Identity is read from the state file written by setup.js — MCP never calls /join.
  *
  * Usage:
  *   npx vibevibes-mcp                          # defaults to http://localhost:4321
  *   npx vibevibes-mcp https://xyz.trycloudflare.com  # join a shared room
  *   VIBEVIBES_SERVER_URL=https://... npx vibevibes-mcp
  *
- * 5 tools: connect, watch, act, memory, screenshot
+ * 11 tools: connect, act, stream, spawn_room, list_rooms, list_experiences, room_config_schema, memory, screenshot, blob_set, blob_get
  */
 export {};

package/dist/index.js

@@ -2,17 +2,20 @@
  * vibevibes-mcp — standalone MCP server for joining vibevibes experiences.
  *
  * Works with both local dev servers and remote shared tunnels.
+ * Identity is read from the state file written by setup.js — MCP never calls /join.
  *
  * Usage:
  *   npx vibevibes-mcp                          # defaults to http://localhost:4321
  *   npx vibevibes-mcp https://xyz.trycloudflare.com  # join a shared room
  *   VIBEVIBES_SERVER_URL=https://... npx vibevibes-mcp
  *
- * 5 tools: connect, watch, act, memory, screenshot
+ * 11 tools: connect, act, stream, spawn_room, list_rooms, list_experiences, room_config_schema, memory, screenshot, blob_set, blob_get
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
 // Resolve server URL: CLI arg > env var > localhost default
 const RAW_SERVER_URL = process.argv[2] ||
     process.env.VIBEVIBES_SERVER_URL ||
@@ -25,28 +28,60 @@ parsedUrl.searchParams.delete("token");
 const SERVER_URL = parsedUrl.toString().replace(/\/$/, ""); // remove trailing slash
 // ── State ──────────────────────────────────────────────────
 let currentActorId = null;
-let lastEventTs = 0;
-let connected = false;
+let currentOwner = null;
+const STATE_FILE = resolve(process.cwd(), ".claude/vibevibes-agent.local.json");
+/**
+ * Load identity from the state file written by setup.js.
+ * Setup.js is the sole identity authority — MCP never calls /join.
+ */
+function loadIdentity() {
+    if (!existsSync(STATE_FILE)) {
+        throw new Error("Not in agent mode. Use /vibevibes-join first.");
+    }
+    const raw = readFileSync(STATE_FILE, "utf-8");
+    const state = JSON.parse(raw);
+    if (!state.active || !state.actorId) {
+        throw new Error("Agent loop not active. Use /vibevibes-join first.");
+    }
+    currentActorId = state.actorId;
+    currentOwner = state.owner || state.actorId.split("-")[0];
+    return { actorId: state.actorId, serverUrl: state.serverUrl, owner: currentOwner };
+}
 // ── Helpers ────────────────────────────────────────────────
 async function fetchJSON(path, opts) {
-    const headers = {
-        "Content-Type": "application/json",
-        ...(opts?.headers || {}),
-    };
-    // Attach room token as Authorization header when available
-    if (ROOM_TOKEN) {
-        headers["Authorization"] = `Bearer ${ROOM_TOKEN}`;
-    }
-    const res = await fetch(`${SERVER_URL}${path}`, {
-        ...opts,
-        headers,
-    });
-    const text = await res.text();
+    const timeoutMs = opts?.timeoutMs ?? 30000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        return JSON.parse(text);
+        const headers = {
+            "Content-Type": "application/json",
+            ...(opts?.headers || {}),
+        };
+        // Attach room token as Authorization header when available
+        if (ROOM_TOKEN) {
+            headers["Authorization"] = `Bearer ${ROOM_TOKEN}`;
+        }
+        const res = await fetch(`${SERVER_URL}${path}`, {
+            ...opts,
+            signal: controller.signal,
+            headers,
+        });
+        const text = await res.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Server returned non-JSON: ${text.slice(0, 200)}`);
+        }
+    }
+    catch (err) {
+        if (err.name === "AbortError") {
+            throw new Error(`Request timed out after ${timeoutMs}ms: ${path}`);
+        }
+        throw err;
     }
-    catch {
-        throw new Error(`Server returned non-JSON: ${text.slice(0, 200)}`);
+    finally {
+        clearTimeout(timer);
     }
 }
 function formatToolList(tools) {
@@ -63,47 +98,49 @@ function formatToolList(tools) {
     })
         .join("\n");
 }
-async function joinRoom() {
-    const join = await fetchJSON("/join", {
-        method: "POST",
-        body: JSON.stringify({ username: "claude", actorType: "ai" }),
-    });
-    if (join.error)
-        throw new Error(join.error);
-    currentActorId = join.actorId;
-    lastEventTs = Date.now();
-    connected = true;
-    return join;
-}
-async function ensureConnected() {
-    if (connected)
-        return;
-    await joinRoom();
+/**
+ * Format state for agent consumption.
+ * If the experience defines observe(), show the curated observation.
+ * Otherwise fall back to raw state.
+ */
+function formatState(state, observation) {
+    if (observation) {
+        return `Observation: ${JSON.stringify(observation, null, 2)}`;
+    }
+    return `State: ${JSON.stringify(state, null, 2)}`;
 }
 // ── MCP Server ─────────────────────────────────────────────
 const server = new McpServer({
     name: "vibevibes",
-    version: "0.1.0",
+    version: "0.4.0",
 });
 // ── Tool: connect ──────────────────────────────────────────
 server.tool("connect", `Connect to the running experience.
 
 Returns: available tools, current state, participants, and the browser URL.
 
-Call this first before using watch or act.`, {}, async () => {
+Identity is read from the state file written by /vibevibes-join. MCP never calls /join — setup.js owns identity.
+
+Call this first, then use act to interact. The stop hook keeps you present.`, {}, async () => {
     try {
-        const join = await joinRoom();
+        const identity = loadIdentity();
+        // GET /state to fetch tools, state, participants — no POST /join
+        const state = await fetchJSON("/state", { timeoutMs: 10000 });
         const output = [
-            `Connected as ${currentActorId}`,
-            `Experience: ${join.experienceId}`,
-            `Browser: ${join.browserUrl}`,
+            `Connected as ${identity.actorId}`,
+            `Experience: ${state.experienceId || "unknown"}`,
+            `Browser: ${state.browserUrl || SERVER_URL}`,
             `Server: ${SERVER_URL}`,
             ``,
-            `State: ${JSON.stringify(join.sharedState, null, 2)}`,
-            `Participants: ${join.participants?.join(", ")}`,
+            formatState(state.sharedState, state.observation),
+            `Participants: ${state.participants?.join(", ")}`,
+            `Room Config: ${JSON.stringify(state.config || {}, null, 2)}`,
+            ...(state.hasRoomConfig ? [`(This experience supports configurable rooms — use spawn_room to create configured sub-rooms)`] : []),
             ``,
             `Tools:`,
-            formatToolList(join.tools),
+            formatToolList(state.tools),
+            ``,
+            `You are now a live participant. The stop hook keeps you present — use act to interact.`,
         ].join("\n");
         return { content: [{ type: "text", text: output }] };
     }
@@ -111,123 +148,341 @@ Call this first before using watch or act.`, {}, async () => {
         return {
             content: [{
                     type: "text",
-                    text: `Failed to connect to ${SERVER_URL}.\n\nIs the dev server running? (npm run dev)\n\nError: ${err.message}`,
+                    text: `Failed to connect to ${SERVER_URL}.\n\nIs the dev server running? (npm run dev)\nHave you run /vibevibes-join?\n\nError: ${err.message}`,
                 }],
         };
     }
 });
-// ── Tool: watch ────────────────────────────────────────────
-server.tool("watch", `Wait for activity in the experience. Blocks until events arrive or timeout.
+// ── Tool: act ──────────────────────────────────────────────
+server.tool("act", `Execute a tool to mutate shared state. All state changes go through tools.
+
+Supports batching: pass a "batch" array to execute multiple tool calls sequentially in one round-trip.
+Each call sees the state left by the previous call, so order matters.
 
-Use predicate to wait for a condition, e.g. "state.count > 5".
-Use filterTools to only wake for specific tools, e.g. ["pixel.place"].
-Use filterActors to only wake for specific actors.
+Single call:
+  act(toolName="counter.increment", input={amount: 2})
 
-Auto-connects if not already connected.`, {
-    timeout: z.number().optional().describe("Max wait ms (default 30000, max 55000)"),
-    predicate: z.string().optional().describe('JS expression, e.g. "state.count > 5"'),
-    filterTools: z.array(z.string()).optional().describe("Only wake for these tools"),
-    filterActors: z.array(z.string()).optional().describe("Only wake for these actors"),
-}, async ({ timeout, predicate, filterTools, filterActors }) => {
+Batch call (multiple tools in one round-trip):
+  act(batch=[
+    {toolName: "counter.increment", input: {amount: 2}},
+    {toolName: "counter.increment", input: {amount: 3}},
+    {toolName: "phase.set", input: {phase: "playing"}}
+  ])
+
+Use roomId to interact with a specific room (e.g. a cross-experience spawned room).
+Defaults to the "local" (host) room if omitted.`, {
+    toolName: z.string().optional().describe("Tool to call, e.g. 'counter.increment'. Required if batch is not provided."),
+    input: z.record(z.any()).optional().describe("Tool input parameters (for single call)"),
+    batch: z.array(z.object({
+        toolName: z.string().describe("Tool to call"),
+        input: z.record(z.any()).optional().describe("Tool input parameters"),
+    })).optional().describe("Array of tool calls to execute sequentially in one round-trip. Each call sees the state from the previous call."),
+    roomId: z.string().optional().describe("Target room ID (defaults to 'local')"),
+}, async ({ toolName, input, batch, roomId }) => {
     try {
-        await ensureConnected();
+        loadIdentity();
     }
     catch (err) {
         return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
     }
-    const t = Math.min(timeout || 30000, 55000);
-    // Check if predicate already matches
-    if (predicate) {
+    const targetRoom = roomId || "local";
+    // Build the list of calls: either from batch or single toolName+input
+    const calls = batch && batch.length > 0
+        ? batch
+        : toolName
+            ? [{ toolName, input }]
+            : [];
+    if (calls.length === 0) {
+        return { content: [{ type: "text", text: `Provide either toolName or batch.` }] };
+    }
+    const results = [];
+    for (const call of calls) {
         try {
-            const current = await fetchJSON("/state");
-            const fn = new Function("state", "actorId", `return ${predicate}`);
-            if (fn(current.sharedState, currentActorId)) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: [
-                                `Predicate already true: ${predicate}`,
-                                `State: ${JSON.stringify(current.sharedState, null, 2)}`,
-                                `Participants: ${current.participants?.join(", ")}`,
-                            ].join("\n"),
-                        }],
-                };
+            const idempotencyKey = `${currentActorId}-${call.toolName}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+            const toolPath = targetRoom === "local"
+                ? `/tools/${call.toolName}`
+                : `/rooms/${targetRoom}/tools/${call.toolName}`;
+            const result = await fetchJSON(toolPath, {
+                method: "POST",
+                headers: { "X-Idempotency-Key": idempotencyKey },
+                body: JSON.stringify({
+                    actorId: currentActorId || "mcp-client",
+                    owner: currentOwner || undefined,
+                    input: call.input || {},
+                }),
+                timeoutMs: 30000,
+            });
+            if (result.error) {
+                results.push({ toolName: call.toolName, error: result.error });
+            }
+            else {
+                results.push({ toolName: call.toolName, output: result.output });
             }
         }
-        catch {
-            // Predicate eval failed, continue to long-poll
+        catch (err) {
+            results.push({ toolName: call.toolName, error: err.message });
         }
     }
-    // Long-poll for events
-    const data = await fetchJSON(`/events?since=${lastEventTs}&timeout=${t}`);
-    let events = data.events || [];
-    if (filterTools?.length) {
-        events = events.filter((e) => filterTools.includes(e.tool));
+    // Fetch final state after all calls
+    try {
+        const statePath = targetRoom === "local" ? "/state" : `/rooms/${targetRoom}`;
+        const state = await fetchJSON(statePath, { timeoutMs: 5000 });
+        const stateObj = state.sharedState || state;
+        const outputParts = [];
+        if (targetRoom !== "local")
+            outputParts.push(`[Room: ${targetRoom}]`);
+        for (const r of results) {
+            if (r.error) {
+                outputParts.push(`${r.toolName} → ERROR: ${r.error}`);
+            }
+            else {
+                outputParts.push(`${r.toolName} → ${JSON.stringify(r.output)}`);
+            }
+        }
+        outputParts.push(formatState(stateObj, state.observation));
+        return { content: [{ type: "text", text: outputParts.join("\n") }] };
     }
-    if (filterActors?.length) {
-        events = events.filter((e) => filterActors.includes(e.actorId));
+    catch (err) {
+        // Still return tool results even if state fetch fails
+        const outputParts = results.map(r => r.error ? `${r.toolName} → ERROR: ${r.error}` : `${r.toolName} → ${JSON.stringify(r.output)}`);
+        outputParts.push(`(State fetch failed: ${err.message})`);
+        return { content: [{ type: "text", text: outputParts.join("\n") }] };
     }
-    if (events.length > 0) {
-        lastEventTs = Math.max(...events.map((e) => e.ts));
+});
+// ── Tool: stream ───────────────────────────────────────────
+server.tool("stream", `Send a continuous state update via stream channel.
+
+Streams are high-frequency state mutations (brush strokes, sliders, cursors) that bypass the full tool pipeline.
+They validate input, merge into state, and broadcast — but don't create event log entries.
+
+Use this instead of act for high-frequency updates.`, {
+    name: z.string().describe("Stream name, e.g. 'brush.stroke'"),
+    input: z.record(z.any()).optional().describe("Stream input parameters"),
+    roomId: z.string().optional().describe("Target room ID (defaults to 'local')"),
+}, async ({ name, input, roomId }) => {
+    try {
+        loadIdentity();
     }
-    let predicateMatched = false;
-    if (predicate) {
-        try {
-            const fn = new Function("state", "actorId", `return ${predicate}`);
-            predicateMatched = !!fn(data.sharedState, currentActorId);
+    catch (err) {
+        return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
+    }
+    const targetRoom = roomId || "local";
+    try {
+        const streamPath = targetRoom === "local"
+            ? `/streams/${name}`
+            : `/rooms/${targetRoom}/streams/${name}`;
+        const result = await fetchJSON(streamPath, {
+            method: "POST",
+            body: JSON.stringify({ actorId: currentActorId, input: input || {} }),
+            timeoutMs: 10000,
+        });
+        if (result.error) {
+            return { content: [{ type: "text", text: `Stream error: ${result.error}` }] };
         }
-        catch {
-            // ignore
+        return { content: [{ type: "text", text: `Stream ${name} sent.` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Stream failed: ${err.message}` }] };
+    }
+});
+// ── Tool: spawn_room ──────────────────────────────────────
+server.tool("spawn_room", `Spawn a new configured room (sub-room).
+
+Each room is an instance of the experience with its own config.
+Think of it as: experience = game engine, config = level parameters.
+
+You can pass:
+  - experienceId: which experience to run in the new room (defaults to current experience)
+  - config: an object of config values (validated against the experience's schema)
+  - config: a preset name string (e.g. "boss-fight") to use predefined configs
+
+Use list_experiences to discover available experiences.
+Use room_config_schema with an experienceId to discover config fields before spawning.
+
+Returns the new room's ID, URL, and resolved config.`, {
+    experienceId: z.string().optional().describe("Experience to run in the new room (defaults to host experience). Use list_experiences to see available options."),
+    name: z.string().optional().describe("Room name (auto-generated if omitted)"),
+    config: z.union([z.record(z.any()), z.string()]).optional().describe("Config values object or preset name string"),
+    initialState: z.record(z.any()).optional().describe("Initial shared state for the new room"),
+    linkBack: z.boolean().optional().describe("Store parent roomId in child state"),
+    sourceRoomId: z.string().optional().describe("Parent room ID (defaults to 'local')"),
+}, async ({ experienceId, name, config, initialState, linkBack, sourceRoomId }) => {
+    try {
+        loadIdentity();
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
+    }
+    try {
+        const result = await fetchJSON("/rooms/spawn", {
+            method: "POST",
+            body: JSON.stringify({
+                experienceId,
+                name,
+                config,
+                initialState,
+                linkBack: linkBack ?? true,
+                sourceRoomId: sourceRoomId || "local",
+            }),
+            timeoutMs: 30000, // External experiences need time to bundle
+        });
+        if (result.error) {
+            const hint = result.error.includes("not found")
+                ? `\nUse list_experiences to see available experience IDs.`
+                : "";
+            return { content: [{ type: "text", text: `Spawn failed: ${result.error}${hint}` }] };
         }
+        const output = [
+            `Room spawned successfully!`,
+            experienceId ? `  Experience: ${experienceId}` : "",
+            `  Room ID: ${result.roomId}`,
+            `  URL: ${result.url}`,
+            `  Config: ${JSON.stringify(result.config, null, 2)}`,
+            ``,
+            `The room is live. Participants can join at the URL above.`,
+            `Use act(roomId="${result.roomId}") to interact with this room.`,
+        ].filter(Boolean).join("\n");
+        return { content: [{ type: "text", text: output }] };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to spawn room: ${err.message}`,
+                }],
+        };
     }
-    const parts = [];
-    if (events.length > 0) {
-        parts.push(`${events.length} event(s):`);
-        for (const e of events) {
-            parts.push(`  [${e.actorId}] ${e.tool}(${JSON.stringify(e.input)}) → ${e.error ? `ERROR: ${e.error}` : JSON.stringify(e.output)}`);
+});
+// ── Tool: list_rooms ──────────────────────────────────────
+server.tool("list_rooms", `List all active rooms and their configs.
+
+Returns room IDs, participant counts, configs, and parent/child relationships.
+Use this to discover what rooms exist and how they're configured.`, {}, async () => {
+    try {
+        loadIdentity();
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
+    }
+    try {
+        const rooms = await fetchJSON("/rooms", { timeoutMs: 5000 });
+        if (!Array.isArray(rooms) || rooms.length === 0) {
+            return { content: [{ type: "text", text: "No rooms found." }] };
         }
+        const lines = rooms.map((r) => {
+            const configStr = Object.keys(r.config || {}).length > 0
+                ? `config: ${JSON.stringify(r.config)}`
+                : "config: (default)";
+            const parentStr = r.parentRoomId ? ` ← parent: ${r.parentRoomId}` : "";
+            const childStr = r.childRoomIds?.length > 0 ? ` → children: [${r.childRoomIds.join(", ")}]` : "";
+            return `  ${r.roomId} (${r.participants?.length || 0} participants, ${r.eventCount || 0} events) ${configStr}${parentStr}${childStr}`;
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: `${rooms.length} room(s):\n${lines.join("\n")}`,
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to list rooms: ${err.message}`,
+                }],
+        };
+    }
+});
+// ── Tool: room_config_schema ──────────────────────────────
+server.tool("room_config_schema", `Get the room configuration schema for an experience.
+
+Shows what config values a room accepts, their types, defaults, and available presets.
+Use this before spawn_room to understand what config options are available.
+
+Pass experienceId to inspect an external experience's config (loads it on demand).`, {
+    experienceId: z.string().optional().describe("Experience ID to inspect (defaults to host experience)"),
+}, async ({ experienceId }) => {
+    try {
+        loadIdentity();
     }
-    else {
-        parts.push("No new events (timeout).");
+    catch (err) {
+        return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
+    }
+    try {
+        const queryParam = experienceId ? `?experienceId=${encodeURIComponent(experienceId)}` : "";
+        const schema = await fetchJSON(`/rooms/config-schema${queryParam}`, { timeoutMs: 15000 });
+        if (!schema.hasConfig) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `${experienceId ? `Experience "${experienceId}"` : "This experience"} does not define a room config schema. Rooms are spawned with default settings.`,
+                    }],
+            };
+        }
+        const output = [
+            `Room Config Schema${experienceId ? ` (${experienceId})` : ""}:`,
+            schema.description ? `  ${schema.description}` : "",
+            ``,
+            `Schema: ${JSON.stringify(schema.schema, null, 2)}`,
+            ``,
+            `Defaults: ${JSON.stringify(schema.defaults, null, 2)}`,
+            ``,
+            `Presets: ${schema.presets.length > 0 ? schema.presets.join(", ") : "(none)"}`,
+            ``,
+            `Use spawn_room with config values or a preset name to create a configured room.`,
+        ].filter(Boolean).join("\n");
+        return { content: [{ type: "text", text: output }] };
     }
-    parts.push(`State: ${JSON.stringify(data.sharedState, null, 2)}`);
-    parts.push(`Participants: ${data.participants?.join(", ")}`);
-    if (predicate) {
-        parts.push(`Predicate "${predicate}": ${predicateMatched}`);
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to get config schema: ${err.message}`,
+                }],
+        };
     }
-    return { content: [{ type: "text", text: parts.join("\n") }] };
 });
-// ── Tool: act ──────────────────────────────────────────────
-server.tool("act", `Execute a tool to mutate shared state. All state changes go through tools.
+// ── Tool: list_experiences ─────────────────────────────────
+server.tool("list_experiences", `List available experiences that can be used to spawn rooms.
 
-Example: act(toolName="counter.increment", input={amount: 2})
+Shows the host experience and any external experiences registered in vibevibes.registry.json.
+Use this to discover what experiences are available for cross-experience room spawning.
 
-Auto-connects if not already connected.`, {
-    toolName: z.string().describe("Tool to call, e.g. 'counter.increment'"),
-    input: z.record(z.any()).optional().describe("Tool input parameters"),
-}, async ({ toolName, input }) => {
+Each experience can be used as an experienceId in spawn_room.`, {}, async () => {
     try {
-        await ensureConnected();
+        loadIdentity();
     }
     catch (err) {
         return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
     }
-    const result = await fetchJSON(`/tools/${toolName}`, {
-        method: "POST",
-        body: JSON.stringify({
-            actorId: currentActorId || "mcp-client",
-            input: input || {},
-        }),
-    });
-    if (result.error) {
-        return { content: [{ type: "text", text: `Tool error: ${result.error}` }] };
-    }
-    const state = await fetchJSON("/state");
-    const output = [
-        `${toolName} → ${JSON.stringify(result.output)}`,
-        `State: ${JSON.stringify(state.sharedState, null, 2)}`,
-    ].join("\n");
-    return { content: [{ type: "text", text: output }] };
+    try {
+        const experiences = await fetchJSON("/experiences", { timeoutMs: 10000 });
+        if (!Array.isArray(experiences) || experiences.length === 0) {
+            return { content: [{ type: "text", text: "No experiences found." }] };
+        }
+        const lines = experiences.map((exp) => {
+            const tag = exp.source === "host" ? "[HOST]" : "[REGISTRY]";
+            const loaded = exp.loaded ? "" : " (not yet loaded — will bundle on first spawn)";
+            const config = exp.hasRoomConfig ? " [configurable]" : "";
+            return `  ${tag} ${exp.id} v${exp.version || "?"}${config}${loaded}\n    ${exp.title || ""} — ${exp.description || ""}`;
+        });
+        const output = [
+            `${experiences.length} experience(s) available:`,
+            ...lines,
+            ``,
+            `Use spawn_room(experienceId="...") to create a room running any of these.`,
+            `Use room_config_schema(experienceId="...") to inspect config options before spawning.`,
+        ].join("\n");
+        return { content: [{ type: "text", text: output }] };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to list experiences: ${err.message}`,
+                }],
+        };
+    }
 });
 // ── Tool: memory ───────────────────────────────────────────
 server.tool("memory", `Persistent agent memory (per-session). Survives across tool calls.
@@ -242,7 +497,7 @@ Actions:
         ? `local:${currentActorId}`
         : "default";
     if (action === "get") {
-        const data = await fetchJSON(`/memory?key=${encodeURIComponent(key)}`);
+        const data = await fetchJSON(`/memory?key=${encodeURIComponent(key)}`, { timeoutMs: 5000 });
         return {
             content: [{
                     type: "text",
@@ -257,6 +512,7 @@ Actions:
         await fetchJSON("/memory", {
             method: "POST",
             body: JSON.stringify({ key, updates }),
+            timeoutMs: 5000,
         });
         return { content: [{ type: "text", text: `Memory updated: ${JSON.stringify(updates)}` }] };
     }
@@ -277,27 +533,35 @@ Use this to see what the user sees — inspect paintings, check layouts, read re
         if (ROOM_TOKEN) {
             screenshotHeaders["Authorization"] = `Bearer ${ROOM_TOKEN}`;
         }
-        const res = await fetch(`${SERVER_URL}/screenshot?timeout=${t}`, {
-            headers: screenshotHeaders,
-        });
-        if (!res.ok) {
-            const err = await res.json().catch(() => ({ error: res.statusText }));
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), t + 5000);
+        try {
+            const res = await fetch(`${SERVER_URL}/screenshot?timeout=${t}`, {
+                headers: screenshotHeaders,
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: res.statusText }));
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Screenshot failed: ${err.error || "Unknown error"}`,
+                        }],
+                };
+            }
+            const arrayBuffer = await res.arrayBuffer();
+            const base64 = Buffer.from(arrayBuffer).toString("base64");
             return {
                 content: [{
-                        type: "text",
-                        text: `Screenshot failed: ${err.error || "Unknown error"}`,
+                        type: "image",
+                        data: base64,
+                        mimeType: "image/png",
                     }],
             };
         }
-        const arrayBuffer = await res.arrayBuffer();
-        const base64 = Buffer.from(arrayBuffer).toString("base64");
-        return {
-            content: [{
-                    type: "image",
-                    data: base64,
-                    mimeType: "image/png",
-                }],
-        };
+        finally {
+            clearTimeout(timer);
+        }
     }
     catch (err) {
         return {
@@ -308,6 +572,69 @@ Use this to see what the user sees — inspect paintings, check layouts, read re
         };
     }
 });
+// ── Tool: blob_set ─────────────────────────────────────────
+server.tool("blob_set", `Store a binary blob on the server. Returns the blob key.
+
+Data is sent as base64-encoded string. Use this for pixel buffers, audio data, etc.
+The blob is stored server-side and can be referenced in state by key.`, {
+    key: z.string().describe("Blob key/ID"),
+    data: z.string().describe("Base64-encoded binary data"),
+    roomId: z.string().optional().describe("Room ID (defaults to 'local')"),
+}, async ({ key, data, roomId }) => {
+    try {
+        loadIdentity();
+        const binaryData = Buffer.from(data, 'base64');
+        const headers = {
+            "Content-Type": "application/octet-stream",
+        };
+        if (ROOM_TOKEN)
+            headers["Authorization"] = `Bearer ${ROOM_TOKEN}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30000);
+        try {
+            const res = await fetch(`${SERVER_URL}/blobs/${encodeURIComponent(key)}?actorId=${encodeURIComponent(currentActorId || '')}`, { method: "POST", headers, body: binaryData, signal: controller.signal });
+            const result = await res.json();
+            if (result.error)
+                return { content: [{ type: "text", text: `Blob error: ${result.error}` }] };
+            return { content: [{ type: "text", text: `Blob stored: key=${key}, size=${result.size} bytes` }] };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Blob set failed: ${err.message}` }] };
+    }
+});
+// ── Tool: blob_get ─────────────────────────────────────────
+server.tool("blob_get", `Retrieve a binary blob from the server by key.
+
+Returns base64-encoded data. Use this to read pixel buffers, audio data, etc.`, {
+    key: z.string().describe("Blob key/ID to retrieve"),
+}, async ({ key }) => {
+    try {
+        loadIdentity();
+        const headers = {};
+        if (ROOM_TOKEN)
+            headers["Authorization"] = `Bearer ${ROOM_TOKEN}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30000);
+        try {
+            const res = await fetch(`${SERVER_URL}/blobs/${encodeURIComponent(key)}`, { headers, signal: controller.signal });
+            if (!res.ok)
+                return { content: [{ type: "text", text: `Blob not found: ${key}` }] };
+            const buf = await res.arrayBuffer();
+            const base64 = Buffer.from(buf).toString('base64');
+            return { content: [{ type: "text", text: `Blob ${key} (${buf.byteLength} bytes):\n${base64}` }] };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Blob get failed: ${err.message}` }] };
+    }
+});
 // ── Start ──────────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibevibes/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for joining vibevibes experiences — local or remote",
   "type": "module",
   "main": "dist/index.js",