Claude Imagine

A visual UI builder powered by Claude AI using the Model Context Protocol (MCP).

Claude connects to an MCP server via HTTP transport, which relays UI commands to a browser via WebSocket. This enables Claude to build and update web interfaces in real-time.

Architecture

┌─────────────┐         ┌──────────────────┐         ┌─────────┐
│ Claude CLI  │──HTTP──►│  server-mcp.js   │◄──WS───│ Browser │
└─────────────┘         │  (MCP Server)    │         └─────────┘
                        │                  │
                        │  Tools:          │
                        │  - update_ui     │
                        │  - log_thought   │
                        └──────────────────┘

Quick Start

1. Install Dependencies

npm install

2. Start the MCP Server

npm run server:mcp

Server runs at http://localhost:3000

3. Add MCP Server to Claude (one-time)

claude mcp add --transport http imagine http://localhost:3000/mcp

4. Open Browser

Navigate to http://localhost:3000 in your browser.

5. Use Claude

# Interactive mode
claude

# Or non-interactive
claude --print --dangerously-skip-permissions \
  "Use update_ui to create a hello world page"

MCP Tools

Tool	Description
update_ui	Updates HTML content in the browser
log_thought	Displays status/thinking messages

Project Structure

ClaudeImagine/
├── src/
│   └── server-mcp.js      # MCP server (HTTP transport)
├── public/
│   └── index.html         # Browser UI
├── scripts/
│   └── create-isolated-claude.js
├── tests/
│   ├── prerequisites/     # Unit tests
│   └── e2e/              # Integration tests
├── docs/
│   ├── CLAUDE-LEARNING.md # Key discoveries
│   ├── ROADMAP.md        # Development plan
│   └── ...
├── claude_config.json     # MCP configuration
└── package.json

Configuration

claude_config.json

{
  "mcpServers": {
    "imagine": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Environment Variables

Variable	Default	Description
PORT	3000	Server port
HOST	127.0.0.1	Server host

Development

# Start server
npm run server:mcp

# Run tests
npm test

# Check MCP connection
claude mcp list

Documentation

• CLAUDE-LEARNING.md - Key technical discoveries
• ROADMAP.md - Development roadmap
• LESSONS-LEARNED.md - Project insights

Key Learnings

1. HTTP Transport - Claude connects to a running server (not spawned)
2. Tool Naming - Tools become mcp__imagine__<tool_name>
3. Session Management - Each Claude session creates an MCP session
4. WebSocket Bridge - Single server handles both MCP and browser

See docs/CLAUDE-LEARNING.md for full details.

License

MIT