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

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

or with Docker:

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.

{
  "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:

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.