# design-architect-mcp

A stateless [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes a custom
**design system and UX rulebook** as MCP tools. Connect it to **Figma Make** (or any MCP-compatible client)
as a custom connector so that generated UI follows your design language — tokens, components, layout rules,
accessibility guidance, and page templates — instead of inventing random styles.

## What it exposes

| Tool | Purpose |
|---|---|
| `get_design_tokens` | Colors, spacing, radius, shadow, and typography tokens |
| `get_design_principles` | High-level design principles (modern, minimal, mobile-first, etc.) |
| `get_layout_rules` | Grid columns per breakpoint, max content width, preferred navigation |
| `get_component_library` | Purpose/variants/sizing/states/accessibility for 14 core components |
| `get_accessibility_rules` | WCAG-oriented contrast, keyboard, focus, semantics, and ARIA guidance |
| `review_ui_proposal` | Scores a generated UI description (0-100) against the design system, with issues + recommendations |
| `get_dashboard_template` | Standard SaaS dashboard layout (Sidebar, Header, Stats, Table, Filters, Actions) |
| `get_form_template` | Standard form page layout (Header, Description, Sections, Inputs, Actions) |
| `get_landing_page_template` | Standard landing page layout (Hero, Features, Benefits, Testimonials, CTA, Footer) |
| `get_design_system` | Loads a full vertical-specific design system: `saas`, `fintech`, `healthcare`, or `ecommerce` |

All data is loaded from JSON files (`design-system.json` and `designs/*.json`), **not hardcoded**, so you can
tune tokens and rules without touching any TypeScript.

## Architecture

```
/src
  /tools     one file per MCP tool, each exports a register*Tool(server) function
  /data      loader.ts reads and caches the JSON design system files
  /types     shared TypeScript interfaces
  server.ts  Express app exposing the MCP server over stateless Streamable HTTP
design-system.json   default design system used by the "base" tools
/designs
  saas.json
  fintech.json
  healthcare.json
  ecommerce.json
```

The server is **stateless**: every `POST /mcp` request creates a brand-new `McpServer` + transport pair
with no session ID. This keeps horizontal scaling trivial (no session affinity or shared state needed) and
matches how most PaaS platforms (Railway, Render, Fly.io, Azure Container Apps) run containers behind a load
balancer.

## Prerequisites

- Node.js 18+
- npm 9+

## 1. Local setup

```bash
git clone <your-repo-url> design-architect-mcp
cd design-architect-mcp
cp .env.example .env
npm install
npm run dev
```

This starts the server with `tsx watch` on `http://localhost:3000`. Verify it's alive:

```bash
curl http://localhost:3000/health
# {"status":"ok","service":"design-architect-mcp"}
```

Test a tool call directly against the MCP endpoint:

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "get_design_tokens", "arguments": {} }
  }'
```

For a production-style run:

```bash
npm run build
npm start
```

### Connecting to Figma Make

In Figma Make, add a **custom MCP connector** and point it at:

```
https://<your-deployed-domain>/mcp
```

(For local testing, expose your local port with a tunneling tool such as `ngrok http 3000` and use the
resulting HTTPS URL, since most external tools require HTTPS.)

## 2. Docker setup

Build and run the container locally:

```bash
docker build -t design-architect-mcp .
docker run --rm -p 3000:3000 --env-file .env design-architect-mcp
```

Check health:

```bash
curl http://localhost:3000/health
```

The image is a multi-stage build: dependencies and TypeScript compilation happen in a `build` stage, and
only the compiled `dist/`, production `node_modules`, and the JSON data files are copied into the final
`production` stage, which runs as a non-root user.

## 3. Deploying to Railway

1. Push this repository to GitHub (or your Git host of choice).
2. In Railway: **New Project → Deploy from GitHub repo**, select this repo.
3. Railway will detect the `Dockerfile` and build it automatically. If it instead tries to use Nixpacks,
   explicitly set the builder to **Dockerfile** in the service's **Settings → Build**.
4. Under **Variables**, add:
   - `PORT` — Railway injects its own `PORT`; the server already reads `process.env.PORT`, so no change is
     needed, but you can override `NODE_ENV=production` and `ALLOWED_ORIGINS` if desired.
5. Deploy. Railway will give you a public URL like `https://design-architect-mcp.up.railway.app`.
6. Your MCP endpoint is `https://design-architect-mcp.up.railway.app/mcp`.

## 4. Deploying to Render

1. Push this repository to GitHub.
2. In Render: **New → Web Service**, connect the repo.
3. Set:
   - **Environment**: Docker
   - **Dockerfile Path**: `Dockerfile` (default)
   - **Health Check Path**: `/health`
4. Add environment variables from `.env.example` under **Environment → Environment Variables**.
5. Deploy. Render will expose the service on `https://<service-name>.onrender.com`.
6. Your MCP endpoint is `https://<service-name>.onrender.com/mcp`.

## 5. Deploying to Fly.io

```bash
fly launch --no-deploy   # generates fly.toml, detects the Dockerfile
fly secrets set NODE_ENV=production
fly deploy
```

Make sure `fly.toml` has an `[http_service]` section with `internal_port = 3000` (matching the `PORT` the
container listens on) and that health checks point at `/health`.

## 6. Deploying to Azure Container Apps

```bash
# 1. Build and push the image to Azure Container Registry (ACR)
az acr create --resource-group <rg> --name <acrName> --sku Basic
az acr build --registry <acrName> --image design-architect-mcp:latest .

# 2. Create (or reuse) a Container Apps environment
az containerapp env create \
  --name design-architect-env \
  --resource-group <rg> \
  --location <region>

# 3. Deploy the container app
az containerapp create \
  --name design-architect-mcp \
  --resource-group <rg> \
  --environment design-architect-env \
  --image <acrName>.azurecr.io/design-architect-mcp:latest \
  --target-port 3000 \
  --ingress external \
  --registry-server <acrName>.azurecr.io \
  --env-vars NODE_ENV=production
```

Azure Container Apps will give you a public FQDN, e.g. `https://design-architect-mcp.<hash>.<region>.azurecontainerapps.io`.
Your MCP endpoint is that URL + `/mcp`.

## Customizing the design system

- Edit `design-system.json` to change the defaults returned by `get_design_tokens`, `get_design_principles`,
  `get_layout_rules`, `get_component_library`, `get_accessibility_rules`, and the three template tools.
- Edit or add files under `/designs` to change or extend the vertical-specific systems returned by
  `get_design_system` (currently `saas`, `fintech`, `healthcare`, `ecommerce`). To add a new vertical, add
  a `designs/<name>.json` file with the same shape and add `<name>` to the `system` enum in
  `src/tools/designSystem.ts` and `DESIGN_SYSTEM_NAMES` in `src/types/index.ts`.
- No rebuild is required for JSON changes when running with `npm run dev` — the loader re-reads on first
  use per process start. In production, redeploy (or restart the container) to pick up JSON changes, since
  values are cached in memory per instance for performance.

## Notes on statelessness

Because `sessionIdGenerator` is left `undefined` when constructing `StreamableHTTPServerTransport`, this
server does not support the SSE resumable-stream or session-based parts of the Streamable HTTP spec
(`GET /mcp` and `DELETE /mcp` both return `405`). Every `POST /mcp` call is fully self-contained, which is
the right tradeoff for a read-mostly, rules/reference server like this one.