# MCP Elite Design Architect Hub

An advanced Model Context Protocol server plus a live frontend canvas for multi-agent design sessions.

## What It Implements

- Mandatory `get_session_context` handoff before any agent can mutate session state
- Persistent session state with optimistic concurrency via `context_version`
- Strict staged workflow from voice definition through passes 1-5
- Radically distinct direction generation across spatial, typography, temperature, and motion axes
- Triple validation gate before UI elements are committed:
  - `critique_current_design`
  - `evaluate_design_quality`
  - `wow_factor_audit`
- Snapshot and restore support
- Feedback memory that flags recurring issues
- Token mutation dependency alerts
- `read_session_state` for full canvas state reads
- `read_user_suggestions` so agents can consume live user feedback pins
- React/Tailwind/Motion export with zipped artifacts and Storybook stories
- WebSocket canvas bridge for real-time frontend updates

## Projects

- MCP server: [src/server.js](C:\Users\zyr9s\Downloads\mcp ai design\src\server.js)
- Frontend canvas app: [mcp-canvas-app](C:\Users\zyr9s\Downloads\mcp ai design\mcp-canvas-app)

## Install

```bash
npm.cmd install
```

## Run The Canvas Server

```bash
node src/server.js
```

This starts:

- stdio MCP transport for tool calls
- WebSocket canvas bridge at `ws://127.0.0.1:3210/ws`
- health endpoint at `http://127.0.0.1:3210/health`

Session state is persisted to `.mcp-elite-design-state.json`.

## Run The MCP Stdio Server

```bash
node src/server-stdio.js
```

This entry point is for MCP clients such as Antigravity. It does not start the WebSocket or HTTP canvas bridge, so it avoids port `3210` entirely.

The canvas/live entry and the stdio entry are intentionally separate:

- Canvas/live server: [src/server.js](C:\Users\zyr9s\Downloads\mcp ai design\src\server.js)
- MCP stdio server: [src/server-stdio.js](C:\Users\zyr9s\Downloads\mcp ai design\src\server-stdio.js)

If someone still launches `src/server.js` in stdio mode, it now respects these environment overrides and will skip the live server:

- `MCP_TRANSPORT=stdio`
- `MCP_MODE=stdio`
- `MCP_DISABLE_LIVE_SERVER=1`

## Run The Canvas App

```bash
npm.cmd run dev --workspace mcp-canvas-app
```

## One-Click Startup

Double-click [start.bat](C:\Users\zyr9s\Downloads\mcp ai design\start.bat) from the project root.

It will:

- open the canvas server in one terminal window
- open the frontend dev server in a second terminal window
- wait for both services to respond
- open `http://localhost:5173` in your default browser

Optional frontend env vars:

- `VITE_MCP_WS_URL` default: `ws://127.0.0.1:3210/ws`
- `VITE_SESSION_ID` default: `default-design-session`
- `VITE_CANVAS_AGENT_ID` default: `canvas-user`

You can also open a specific session via query string:

- `http://localhost:5173/?session=my-session-id`

## Tool Flow

1. `get_session_context`
2. `define_designer_voice`
3. `load_design_references`
4. `generate_design_directions`
5. `approve_design_direction`
6. `apply_design_system`
7. `define_site_structure`
8. `set_design_phase`
9. `create_ui_element`
10. `read_user_suggestions`
11. `export_artifacts`

## Antigravity MCP Config

Use the stdio entry point, not `src/server.js`.

Example config: [mcp.antigravity.config.example.json](C:\Users\zyr9s\Downloads\mcp ai design\mcp.antigravity.config.example.json)

Equivalent `args` change:

```json
{
  "command": "node",
  "args": [
    "C:\\Users\\zyr9s\\Downloads\\mcp ai design\\src\\server-stdio.js"
  ]
}
```

## Notes

- `load_design_references` supports `provided_analysis` so the workflow can continue in offline or sandboxed environments.
- `mutate_design_tokens` updates tokens and reports which generated elements are likely affected.
- `export_artifacts` writes generated files and a zip archive to `artifacts/<session_id>/` by default.
- The canvas listens for live session updates over WebSocket, so agent mutations appear without a page refresh.