@vibevibes/mcp

Runtime engine + MCP server for vibevibes experiences.

Agents connect via MCP. Humans connect via browser. Same room, same state, same tools.

Install

npm install @vibevibes/mcp

Quick Start

# 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 (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 | Define experiences — tools, canvas, state | | @vibevibes/mcp | Runtime engine — MCP server + WebSocket + viewer | | @vibevibes/create | npx @vibevibes/create — scaffold in seconds | | experiences | Example experiences — fork and remix |

License

MIT