# MCP System Design — live architecture + scaffolding

A web app you drive **through Claude over MCP**. Prompt Claude to design a
system → the browser draws the architecture live (interactive D3 nodes & edges).
Say "develop" → Claude scaffolds a minimal Python + Docker MVP into a folder.

```
┌─────────┐   MCP (stdio)    ┌───────────────────────┐   SSE    ┌─────────┐
│ Claude  │ ───────────────▶ │ server.py             │ ───────▶ │ Browser │
│ (client)│  visualize_...   │  MCP tools + FastAPI  │  /events │  D3 UI  │
└─────────┘  scaffold_...    │  + shared state       │          └─────────┘
                             └───────────────────────┘
                                        │ writes
                                        ▼
                              generated/<project>/  (FastAPI services + Docker)
```

## What's inside

| File | Role |
|------|------|
| `server.py` | MCP server (stdio) + embedded FastAPI web server + SSE endpoint |
| `scaffolder.py` | Turns a design into FastAPI services + Dockerfiles + docker-compose |
| `state.py` | Thread-safe shared state watched by the SSE stream |
| `web/index.html` | D3 force-graph UI, live via `EventSource("/events")` |

## MCP tools Claude can call

- `visualize_architecture(title, components, connections)` — draw the diagram.
  `components`: `[{id, label, type?, description?}]` (`type` colors the node:
  `service`, `queue`, `db`/`store`, `sse`, `cache`, `gateway`).
  `connections`: `[{source, target, label?}]`.
- `scaffold_implementation(project_name, base_port=8001)` — generate the MVP
  from whatever is currently on screen. Writes to `generated/<project_name>/`.
- `get_current_design()` — return the design currently displayed.

## Run it

### 1. Start the web UI

```bash
pip install -r requirements.txt
APP_MODE=web python server.py        # UI at http://localhost:8765
```

or with Docker:

```bash
docker compose up --build            # UI at http://localhost:8765
```

### 2. Connect Claude to the MCP server

Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`).
This launches the server over stdio; the web UI comes up automatically on 8765.

```json
{
  "mcpServers": {
    "sysdesign": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-sysdesign/server.py"]
    }
  }
}
```

> Note: the MCP client owns stdio, so let it launch `server.py` (default
> `APP_MODE=mcp` runs MCP **and** the web UI). Don't also run `APP_MODE=web`
> on the same port, or 8765 will be taken.

### 3. Use it

Open http://localhost:8765, then in Claude:

> "Design a URL crawler system that stores page text keyed by URL, with an SSE
> monitoring channel."

Claude calls `visualize_architecture(...)` and the graph appears. Then:

> "develop"

Claude calls `scaffold_implementation("crawler")` and `generated/crawler/`
appears with runnable services:

```bash
cd generated/crawler && docker compose up --build
```

## Notes / MVP scope

- SSE (not WebSocket) powers the live UI: it's a one-way server→browser push,
  which is exactly what a live diagram needs, and it auto-reconnects.
- The scaffold is a **skeleton** — each service builds, starts, and can reach its
  declared dependencies over the Docker network. Business logic is left as TODO.
- State is in-memory (single process). Restarting the server clears the diagram.