@vibevibes/mcp 0.2.0 → 0.3.1

package/LICENSE

@@ -1,21 +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.
+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

@@ -1,201 +1,69 @@
-# @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
+# @vibevibes/mcp
+
+Runtime engine + MCP server for [vibevibes](https://github.com/vibevibes/sdk) experiences.
+
+Agents connect via MCP. Humans connect via browser. Same room, same state, same tools.
+
+[![npm](https://img.shields.io/npm/v/@vibevibes/mcp)](https://www.npmjs.com/package/@vibevibes/mcp)
+[![license](https://img.shields.io/npm/l/@vibevibes/mcp)](./LICENSE)
+
+## Install
+
+```bash
+npm install @vibevibes/mcp
+```
+
+## Quick Start
+
+```bash
+# Serve an experience (Express + WebSocket + browser viewer)
+npx vibevibes-serve ./my-experience
+
+# Or run as an MCP server (for AI agents to connect)
+npx vibevibes-mcp
+```
+
+Open http://localhost:4321 in the browser. Connect an agent via MCP. Both are in the same room.
+
+## How It Works
+
+1. You define an experience with [@vibevibes/sdk](https://github.com/vibevibes/sdk) (tools + canvas)
+2. This server loads and runs it
+3. Agents connect via MCP tools (`connect`, `act`, `look`)
+4. Humans open the browser viewer to see the canvas
+5. Everyone shares the same state — tools are the only mutation path
+
+```
+Browser (Canvas)  <--WebSocket-->  vibevibes-serve  <--MCP-->  AI Agent
+```
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `connect` | Join the room. Returns available tools, current state, browser URL |
+| `act` | Execute a tool — same tools the human uses via the canvas |
+| `look` | Observe current state and recent events |
+| `disconnect` | Leave the room |
+
+## Features
+
+- **Hot reload** — edit `src/index.tsx`, save, see changes instantly
+- **TypeScript bundling** — esbuild compiles experiences on the fly
+- **Tick engine** — optional fixed-rate game loop (`netcode: "tick"`)
+- **Protocol mode** — load experiences from `manifest.json` + subprocess
+- **Ephemeral state** — per-actor transient data (cursors, typing indicators)
+- **Agent memory** — persistent per-session key-value store
+
+## Ecosystem
+
+| Package | Description |
+|---------|-------------|
+| [@vibevibes/sdk](https://github.com/vibevibes/sdk) | Define experiences — tools, canvas, state |
+| **@vibevibes/mcp** | Runtime engine — MCP server + WebSocket + viewer |
+| [@vibevibes/create](https://github.com/vibevibes/create) | `npx @vibevibes/create` — scaffold in seconds |
+| [experiences](https://github.com/vibevibes/experiences) | Example experiences — fork and remix |
+
+## License
+
+MIT

package/bin/cli.js

@@ -1,11 +1,11 @@
-#!/usr/bin/env node
-
-/**
- * @vibevibes/mcp CLI
- *
- * Usage:
- *   npx @vibevibes/mcp                                    # localhost:4321
- *   npx @vibevibes/mcp https://xyz.trycloudflare.com      # remote shared room
- */
-
-import "../dist/index.js";
+#!/usr/bin/env node
+
+/**
+ * @vibevibes/mcp CLI
+ *
+ * Usage:
+ *   npx @vibevibes/mcp                                    # localhost:4321
+ *   npx @vibevibes/mcp https://xyz.trycloudflare.com      # remote shared room
+ */
+
+import "../dist/index.js";

package/bin/postinstall.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall: writes .mcp.json into the project root so Claude Code
+ * can discover the vibevibes MCP server automatically.
+ *
+ * Skipped during self-install (e.g. when building the monorepo).
+ */
+
+import { writeFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+// npm sets INIT_CWD to the directory where `npm install` was run
+const projectRoot = process.env.INIT_CWD;
+if (!projectRoot) process.exit(0);
+
+// Skip if we're installing inside the vibevibes monorepo itself
+const isMonorepo = existsSync(resolve(projectRoot, "sdk")) && existsSync(resolve(projectRoot, "mcp"));
+if (isMonorepo) process.exit(0);
+
+const mcpJsonPath = resolve(projectRoot, ".mcp.json");
+
+// Don't overwrite an existing .mcp.json
+if (existsSync(mcpJsonPath)) process.exit(0);
+
+const config = {
+  mcpServers: {
+    vibevibes: {
+      command: "npx",
+      args: ["vibevibes-mcp"],
+      env: {
+        VIBEVIBES_SERVER_URL: "http://localhost:4321",
+      },
+    },
+  },
+};
+
+writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + "\n");
+console.log("vibevibes: wrote .mcp.json for Claude Code");

package/bin/serve.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * Start the vibevibes server for an experience.
+ *
+ * Usage:
+ *   npx vibevibes-serve              # serves from current directory
+ *   npx vibevibes-serve ./my-exp     # serves from a specific path
+ */
+
+import { resolve } from "node:path";
+import { writeFileSync, existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { startServer } from "../dist/server.js";
+
+const projectRoot = resolve(process.argv[2] || ".");
+const port = parseInt(process.env.PORT || "4321", 10);
+
+// Find git root (where Claude Code reads .mcp.json from)
+let mcpJsonDir = projectRoot;
+try {
+  mcpJsonDir = execSync("git rev-parse --show-toplevel", { cwd: projectRoot, encoding: "utf-8" }).trim();
+} catch {}
+
+// Auto-generate .mcp.json so Claude Code can connect via /mcp
+const mcpJsonPath = resolve(mcpJsonDir, ".mcp.json");
+if (!existsSync(mcpJsonPath)) {
+  const config = {
+    mcpServers: {
+      vibevibes: {
+        command: "npx",
+        args: ["vibevibes-mcp"],
+        env: { VIBEVIBES_SERVER_URL: `http://localhost:${port}` },
+      },
+    },
+  };
+  writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + "\n");
+  console.log(`  .mcp.json: wrote ${mcpJsonPath}`);
+}
+
+startServer({ projectRoot, port });

package/dist/bundler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Experience bundler — produces server and client bundles from src/index.tsx.
+ *
+ * Server bundle: CJS, eval'd via new Function() to extract tools + manifest.
+ * Client bundle: ESM, loaded in browser via blob URL + dynamic import().
+ *
+ * Extracted from create-experience/runtime/bundler.ts into @vibevibes/runtime.
+ */
+/**
+ * Bundle for server-side tool execution (Node.js eval).
+ * Returns the raw ExperienceModule extracted via new Function().
+ */
+export declare function bundleForServer(entryPath: string): Promise<string>;
+/**
+ * Evaluate a server bundle and extract the ExperienceModule.
+ */
+export declare function evalServerBundle(serverCode: string): Promise<unknown>;
+/**
+ * Bundle for client-side Canvas rendering (browser).
+ * Returns pure ESM. External imports (react, zod, etc.) are left as-is —
+ * the viewer's import map resolves them in the browser.
+ */
+export declare function bundleForClient(entryPath: string): Promise<string>;
+/**
+ * Build both bundles from an entry file.
+ */
+export declare function buildExperience(entryPath: string): Promise<{
+    serverCode: string;
+    clientCode: string;
+}>;
+/**
+ * Validate a client bundle for common issues.
+ * Lightweight — esbuild already validates syntax. This just checks the output exists.
+ * Returns null if OK, or an error message string.
+ */
+export declare function validateClientBundle(code: string): string | null;