npm package: @prototyperco/mcp
Description: MCP server for Prototyper UI — exposes component docs, source code, and design tokens to AI assistants
Author: Protochase, Inc.
Latest version: 0.5.3

# @prototyperco/mcp

[Model Context Protocol](https://modelcontextprotocol.io) server for [Prototyper UI](https://prototyper-ui.com). Exposes component docs, source code, design tokens, and a hosted **Live Canvas** to AI assistants. No local servers needed.

## Quick Start

### Claude Code

```bash
claude mcp add prototyper-ui -- npx -y @prototyperco/mcp@latest
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "prototyper-ui": {
      "command": "npx",
      "args": ["-y", "@prototyperco/mcp@latest"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "prototyper-ui": {
      "command": "npx",
      "args": ["-y", "@prototyperco/mcp@latest"]
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "prototyper-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@prototyperco/mcp@latest"]
    }
  }
}
```

## Environment Variables

| Variable                      | Default                              | Description                |
| ----------------------------- | ------------------------------------ | -------------------------- |
| `PROTOTYPER_BRIDGE_URL`       | `https://prototyper-bridge.fly.dev`  | Bridge server URL          |
| `PROTOTYPER_PREVIEW_BASE_URL` | `https://prototyper-ui.com`          | Base URL for preview links |

## Available Tools

### Component Library (read-only)

| Tool                   | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `list_components`      | List all available components with descriptions     |
| `get_component`        | Get full docs, source, and examples for a component |
| `get_theme`            | Get complete CSS design tokens (OKLCH, light/dark)  |
| `search_docs`          | Full-text search across all documentation           |
| `get_install_command`  | Get CLI install command for components              |
| `get_ui_catalog`       | Get the full Compose component catalog              |
| `get_ui_prompt`        | Get a system prompt for UI generation               |
| `validate_ui_spec`     | Validate a Compose spec against the catalog         |
| `get_ui_schema`        | Get the Compose spec JSON schema                    |
| `get_ui_helpers`       | Get utility functions and patterns                  |
| `generate_ui_code`     | Generate a React component from a prompt            |
| `suggest_components`   | Suggest components for a given use case             |
| `debug_component`      | Debug component rendering issues                    |
| `get_local_components` | Detect locally installed Prototyper components      |
| `resolve_dependencies` | Resolve component dependency trees                  |

### Live Canvas

| Tool             | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| `design_create`  | Create a new live design session with optional spec and theme  |
| `design_update`  | Update a session's spec (full replacement or JSON Patch)       |
| `design_theme`   | Update theme via natural language, presets, or explicit params |
| `design_get`     | Get session details at varying levels of detail                |
| `design_export`  | Export a session as a React component with theme CSS           |
| `design_extract` | Extract a design from a preview URL (spec, theme, React code)  |
| `design_list`    | List all active design sessions                                |
| `design_close`   | Close a session, optionally exporting first                    |

## Live Canvas

The Live Canvas lets AI assistants create and iterate on UI designs with a live browser preview. The bridge is hosted — just call `design_create` and it works.

### Architecture

```
AI Assistant (Claude / Cursor)
       |
       | MCP protocol (stdio)
       v
+------------------+        +-------------------+        +----------+
|   MCP Server     | -----> |  Hosted Bridge    | <----> |  Browser |
| (this package)   |  HTTP  | (Yjs/Hocuspocus)  |   WS   | (preview)|
+------------------+        +-------------------+        +----------+
```

- **MCP Server** handles AI tool calls and communicates with the Bridge via HTTP
- **Hosted Bridge** (`prototyper-bridge.fly.dev`) manages Yjs documents and WebSocket connections
- **Browser** connects via WebSocket for real-time CRDT sync

### Example Workflow

```
User: "Build me a login page with email, password, and a submit button"

AI: [calls design_create with name "Login Page"]
    → Session created, preview at https://prototyper-ui.com/design?session=abc123

AI: [calls design_update with Compose spec]
    → Browser updates live

User: "Make it feel warmer, with rounded corners"

AI: [calls design_theme with description "warm sunset palette, large radius"]
    → Theme updates live in browser

User: "Export it"

AI: [calls design_export]
    → Returns React component + theme CSS
```

### Local Bridge (optional)

For offline use or lower latency, you can run a local bridge:

```bash
bunx @prototyperco/bridge@latest
```

Then set `PROTOTYPER_BRIDGE_URL=http://localhost:4321` in your environment.

## License

MIT