Design Bridge

The Design Bridge connects AI agents to a live browser preview. When an AI agent creates or modifies a design through MCP tools, the changes appear instantly in your browser — no page reload, no polling.

Key Features

• Real-time preview — See every change as the AI makes it, streamed to the browser via Yjs CRDT sync
• Operation-based updates — Granular spec operations (add element, set prop, reorder children) instead of full replacements
• Collaborative — Multiple browser tabs and AI agents can view and edit the same session simultaneously
• Conflict-free — Yjs CRDT merges concurrent edits automatically, even across agents
• Agent presence — See which AI agent is editing what, with live status indicators
• Theme-aware — Full OKLCH theme system with natural language descriptions and presets
• Export to code — When the design is ready, export as a React component with theme CSS

Quick Start

1. Start the bridge server

bunx @prototyperco/mcp@latest

The MCP server auto-starts the bridge on http://localhost:4321 when the first design tool is called.

2. Create a session from your AI assistant

Use the design_create MCP tool in Claude Code, Cursor, or any MCP-compatible client:

Create a login page with email and password fields

The AI calls design_create, which returns a previewUrl. Open it in your browser.

3. Watch it build

As the AI calls design_update to add components, change props, and adjust the theme, you see every change live in the browser.

Architecture

AI Agent (MCP)              Bridge Server                 Browser
┌──────────────┐          ┌────────────────────┐       ┌──────────────────┐
│              │          │                    │       │                  │
│ design_create├──HTTP──> │ REST API           │       │ /design?session  │
│ design_update├──HTTP──> │ POST /api/sessions │       │                  │
│ design_theme ├──HTTP──> │ POST /sessions/    │       │ ┌──────────────┐ │
│ design_get   ├──HTTP──> │   :id/ops          │       │ │ Y.Doc (CRDT) │ │
│ design_export│<──HTTP── │ POST /sessions/    │       │ │ ├─ spec      │ │
│              │          │   :id/presence     │       │ │ ├─ theme     │ │
│              │          │                    │       │ │ └─ meta      │ │
│              │          │ Yjs / Hocuspocus   │       │ └──────┬───────┘ │
│              │          │ (WebSocket CRDT)   │<─WSS─>│ HocuspocusProvider│
│              │          │                    │       │                  │
│              │          │ Persistence        │       │ Live Renderer    │
│              │          │ ~/.prototyper-     │       │ Agent Presence UI│
│              │          │   sessions/        │       │                  │
└──────────────┘          └────────────────────┘       └──────────────────┘

The bridge server holds a Yjs Y.Doc per session. AI agents write via the REST API, which mutates the Y.Doc. Browsers connect over WebSocket and receive CRDT updates in real time. Because both sides operate on the same CRDT document, there is no state drift.

Data Model

Each session stores its state in a Yjs document:

Elements inside spec.elements are themselves Y.Maps with type, props (Y.Map), and children (Y.Array), so concurrent edits to different props on the same element merge automatically.

Next Steps

• Getting Started — Set up the bridge and create your first session
• MCP Tools Reference — Full reference for all 7 design tools
• API Reference — REST endpoints, WebSocket protocol, and curl examples