design-architect-mcp

A stateless Model Context Protocol (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

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.

Related MCP server: ds-pilot

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

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:

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

Test a tool call directly against the MCP endpoint:

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:

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:

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

Check health:

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

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

# 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.