design-system-mcp

A standalone Model Context Protocol (MCP) server that exposes design system component documentation to LLM clients. It reads Markdown files with YAML frontmatter from contexts/ and serves them over three MCP tools — get_guidelines, list_components, and get_component_context — so an LLM can look up the cross-cutting API/styling rules and a real component's props and events before generating code against it.

This guide covers deploying it standalone (no Docker) to a fresh AWS EC2 instance, running under PM2.

1. What this service is

• An MCP server, reachable over HTTP, that answers three questions for an LLM client: "what rules and practices apply to every component, regardless of which one I use?" (get_guidelines), "what components are documented?" (list_components), and "give me everything you know about component X" (get_component_context).

• get_guidelines takes no arguments and returns contexts/_guidelines.md verbatim — three things in one call: component API conventions (event handling via CustomEvent/.detail, boolean prop syntax, element-vs-service APIs, item/group component pairs, theming), styling practices (e.g. dimension/background defaults, typography tokens being composite font shorthand values rather than standalone font-size/font-weight, no margin tokens — use padding/gap instead), and the full contextual (--ion-cont-*) design token catalog for color, spacing, sizing, border-radius, border-width, shadow, typography, motion, opacity, and layout. It exists so components get built against real API conventions and styling work never falls back to raw values (hex, px), literal (--ion-lit-*) tokens, or a token applied the wrong way. Some token entries are marked (auto) in the source file — their description was generated from the token name because the underlying CSS had no comment for it (mostly in the spacing/sizing/layout sections). The token names are exact and verified; treat (auto) descriptions as unverified until a human reviews them against Figma/source.

• get_guidelines merges what used to be two separate tools (get_conventions and get_styling_rules/get_tokens) — both were "call once per session before writing code," and splitting them only helps if some sessions need one but not the other, which isn't the case here. It's meant to be called once per session, before any component-specific lookup or styling work — list_components' and get_guidelines' own tool descriptions say so, so a well-behaved client calls it first without being told.

• Stateless: every /mcp request spins up a fresh MCP server + transport internally, so it's safe to run behind a load balancer with multiple concurrent clients and no session affinity required.

• Read-only against contexts/ — there's no database, no write path; updating documentation means editing/adding a Markdown file in that directory (see §9). contexts/_guidelines.md is the exception to "every file in contexts/ is a component" — it's a shared reference doc, not a component, and is excluded from list_components' output and from validate_component.py's per-component schema checks (any file starting with _ is skipped by both).

Related MCP server: Markdown RAG MCP

2. Prerequisites

• Node.js 18 or later (LTS recommended — 20.x or newer). The build uses NodeNext module resolution and ES2022 target, which need a reasonably current Node.

• npm (ships with Node).

• PM2, installed globally on the instance:

  npm install -g pm2

3. Environment variables

Copy .env.example to .env and fill in real values — or export the same variables directly in the shell/systemd unit that starts PM2 (PM2 does not read .env files itself unless you load them into the shell first; see §5).

4. Install and build

From the repo root, in order:

npm install
npm run build

npm run build runs tsc and compiles src/ to dist/. Confirm it produced output:

ls dist/
# expect: http.js  index.js  server.js  tools/

The HTTP entrypoint is dist/http.js.

5. Starting the server under PM2

Export the environment variables from §3 into the shell before starting PM2 — PM2 captures and persists the environment of the process that starts it, reusing it on subsequent restart/resurrect:

export API_KEY=$(cat /path/to/your/secret)   # or however you're sourcing it
export PORT=3000

pm2 start ecosystem.config.cjs

The config file is ecosystem.config.cjs (not .js) — this package is "type": "module" in package.json, and PM2's config loader needs CommonJS, so .cjs is required, not a style choice.

Confirm it's actually running:

pm2 list
# expect a row for "design-system-mcp" with status "online"

pm2 logs design-system-mcp --lines 20
# expect: "design-system-mcp (Streamable HTTP) listening on port 3000"

Surviving an instance reboot

Starting it once isn't enough — by default PM2 doesn't survive a reboot. Set up both of these, once:

pm2 save                # snapshots the current process list
pm2 startup              # prints an OS-specific command
# copy/paste and run the command pm2 startup prints, as root (e.g. via sudo) —
# this registers a systemd (or equivalent) service that resurrects
# "pm2 save"'s snapshot on boot

After any future change to what's running under PM2 (new app, changed env, etc.), re-run pm2 save so the snapshot stays current.

Other PM2 commands you'll use

Logs also land in logs/out.log and logs/error.log in the repo root (gitignored), independent of pm2 logs.

6. Verifying it's working

A process showing "online" in pm2 list only proves Node is alive — it doesn't prove the service actually works. Do both of these:

Health check (confirms contexts/ is present and readable, not just that the process exists):

curl -s http://localhost:3000/health
# expect: {"status":"ok","components":20}
# (component count will match whatever's actually in contexts/)

A 503 here means contexts/ is missing or unreadable — investigate before moving on.

A real end-to-end MCP call — this exercises the actual tool logic, not just connectivity:

curl -s -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_component_context",
      "arguments": { "componentName": "button" }
    }
  }'

Expect a text/event-stream response containing the button component's frontmatter, body, and raw content.

get_guidelines — same idea, no arguments:

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

Expect the full contents of contexts/_guidelines.md back verbatim — API conventions (events/.detail, boolean props, apiTypes, relatedComponents, theming), styling practices (dimension/background defaults, typography-shorthand and no-margin-tokens notes), and the token catalog (border-radius/width, color, shadow, motion, opacity, sizing, spacing, layout, typography). Also confirm list_components doesn't include _guidelines in its output — it's a shared reference doc, not a component.

As a functional check, ask the connected coding assistant to build a form or similar UI and confirm: (a) it calls get_guidelines exactly once, without being reminded; (b) it doesn't set an explicit width/max-width/height/background-color on the outer container (those should come from the design system's own defaults per the styling practices in _guidelines.md, not be hardcoded); and (c) it uses the typography shorthand token and a padding/gap token for text sizing and vertical spacing — not raw font-size/margin values, and not a token named margin-* (there isn't one).

If you'd rather click through any of these interactively, point the MCP Inspector at http://localhost:3000/mcp with the same bearer token.

Also confirm auth is actually enforced — this should return 401, not the component data:

curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
# expect: 401

7. TLS/HTTPS — required before any public exposure

This server speaks plain HTTP only. It does not terminate TLS itself. Do not point a public DNS record or security-group rule directly at port 3000 — put a reverse proxy in front that handles HTTPS, and only expose that.

The simplest option is Caddy: it gets you automatic HTTPS via Let's Encrypt with a few lines of config and no manual certificate renewal.

# Install Caddy (Debian/Ubuntu example — see caddyserver.com for other distros)
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

Minimal Caddyfile (typically /etc/caddy/Caddyfile):

component-docs.yourdomain.com {
    reverse_proxy localhost:3000
}

Reload Caddy after editing:

sudo systemctl reload caddy

That's it — Caddy provisions and renews the Let's Encrypt certificate automatically as long as the domain's DNS points at this instance and ports 80/443 are open in your security group. Clients then connect to https://component-docs.yourdomain.com/mcp, never to the bare Node port.

8. Security notes

• Rate limiting is enabled: /mcp allows 100 requests/minute per IP; /health allows 300/minute (it's expected to be polled more often by uptime checks).

• Bearer token auth is required on all /mcp requests (POST, GET, DELETE) — a missing or incorrect Authorization header gets a 401, never a peek at component data. /health does not require auth (it reveals no component content, just a readiness signal).

• The API_KEY value is the shared secret every consuming team needs. Distribute it out-of-band (a secrets manager, a password manager entry, a DM) — never in a committed config file, a Slack message that gets indexed, or a public repo. Rotate it by updating the deployed environment variable and restarting PM2 with pm2 restart design-system-mcp --update-env (after re-exporting the new API_KEY — see §5), then redistributing the new value to consumers.

  --update-env is not optional here. PM2 caches the environment a process was originally started with and reuses it on a plain restart, even if you've re-exported a new value in your shell first — the old key keeps working and the new one is rejected until you pass --update-env to force PM2 to reread the environment. Confirmed by testing directly: after re-exporting API_KEY and running plain pm2 restart, the old key still returned 200 and the new key returned 401; re-running with pm2 restart design-system-mcp --update-env reversed both — old key 401, new key 200.

9. Adding or updating a component

1. Gather the component's full source material (Angular source, TS interfaces, design tokens, docs, Storybook stories, usage samples).

2. Feed extraction-prompt.md to an LLM along with that material. It produces a single Markdown file (YAML frontmatter + body) in the format the rest of contexts/ uses.

3. Save it as contexts/<componentName>.md.

4. Run the validator — this is mandatory, not optional:

   python3 validate_component.py contexts/<componentName>.md

   A new or updated component file is not considered done until this exits 0. Fix every blocking issue it reports and re-run. Review warnings too — they're not always errors, but each should be a deliberate, explainable choice, not something overlooked.

5. No deploy or restart needed — contexts/ is read at request time, so the change is live as soon as the file is saved on the running instance.

10. How teams connect once deployed

The server speaks MCP Streamable HTTP at POST https://<your-deployed-host>/mcp (through the reverse proxy from §7), authenticated with the shared bearer token from §8.

Claude Code

claude mcp add --transport http component-docs https://<your-deployed-host>/mcp \
  --header "Authorization: Bearer <API_KEY>"

Or directly in .mcp.json:

{
  "mcpServers": {
    "component-docs": {
      "type": "http",
      "url": "https://<your-deployed-host>/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

opencode

{
  "mcp": {
    "component-docs": {
      "type": "remote",
      "url": "https://<your-deployed-host>/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      },
      "enabled": true
    }
  }
}

Replace <your-deployed-host> with the real domain from §7 and <API_KEY> with the real token from §3 — never commit either into a shared config file.