snapUI-v3 MCP Server

MCP (Model Context Protocol) server that serves SnapUI v3 design systems to AI coding agents. Foundation + Variants architecture — markdown specifications delivered over stdio.

Quick Start

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run the server
npm start

The server communicates over stdio (JSON-RPC). It doesn't start an HTTP server — it runs as a subprocess managed by a host application (e.g., Claude Desktop).

Installing on Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "snapui-v3": {
      "command": "node",
      "args": ["/absolute/path/to/snapUI-v3/dist/index.js"]
    }
  }
}

Restart the Claude Desktop app. The hammer icon in the chat input confirms the tools are loaded.

Project Structure

snapUI-v3/
├── src/
│   ├── index.ts        ← Server entry point — tool definitions and MCP setup
│   └── registry.ts     ← Design system configs, discovery, and file readers
├── dist/               ← Compiled JS (generated by `npm run build`)
├── package.json
├── tsconfig.json
└── README.md           ← You are here

src/registry.ts — Registry & Discovery

The registry is the core data layer. It has two parts:

1. Explicit configs (DESIGN_SYSTEM_CONFIGS)

Each design system has a hand-written config object with:

| Field | Purpose | |-------|---------| | id, name | Identifier and display name | | status | "production" or "experimental" | | description | One-paragraph visual identity summary | | stack | Tech stack (Next.js + Tailwind v4 + shadcn/ui) | | dependencies | npm packages needed (production + dev) | | setup_snippets | Code snippets for Tailwind config, font imports, etc. | | conventions.color_system | Color token reference table | | conventions.key_patterns | Bullet list of critical design rules |

This metadata is what powers the get_design_system_overview tool — it gives agents a structured onboarding guide they can save as DESIGN_SYSTEM.md in their project.

2. Filesystem discovery

The registry validates configs against what actually exists in ../design-systems/. It:

• Checks that foundation/FOUNDATION.md exists for each registered system
• Scans variants/ for subdirectories containing .md files
• Caches results after first read

This means adding a new design system requires both: (a) creating the folder in design-systems/, and (b) adding a config entry in registry.ts.

src/index.ts — Server & Tools

Sets up the MCP server with 5 tools. The tools are numbered 0–4 and designed to be called in sequence:

| # | Tool | What it returns | |---|------|-----------------| | 0 | how_to_use | Usage guide — tool sequence, rules, status definitions | | 1 | list_design_systems | All available systems with status, description, variants | | 2 | get_design_system_overview | Structured setup guide — deps, config snippets, conventions, key patterns | | 3 | get_foundation | Full Foundation markdown — tokens, rules, anti-patterns | | 4 | get_variant | Full variant markdown — components, blueprints, reference implementations |

The intended agent workflow:

how_to_use → list_design_systems → get_design_system_overview → get_foundation → get_variant

Steps 0–2 are lightweight (metadata). Steps 3–4 return the full markdown specs (can be 15–40KB each).

How It Relates to design-systems/

This server reads from the sibling design-systems/ directory:

design-system-v3/
├── design-systems/          ← The actual specs (Foundation + Variant markdown files)
│   ├── zed/                 ← Production
│   ├── supabase/            ← Experimental
│   ├── twenty/              ← Experimental
│   └── _template/           ← Ignored by the server (starts with _)
├── snapUI-v3/               ← This server (reads from design-systems/)
├── guides/
└── learnings/

The path resolution is relative: dist/index.js → ../../design-systems/. This means the server works from its compiled location without any absolute paths or env vars.

Adding a New Design System

1. Create the folder in design-systems/ following the Foundation + Variants architecture
2. Add a config entry in src/registry.ts under DESIGN_SYSTEM_CONFIGS
3. Rebuild: npm run build

The config is where you define the metadata that agents see before reading the full Foundation — description, setup instructions, conventions, and key patterns. Think of it as the "quick reference card" while the Foundation is the "full manual."

Dependencies

| Package | Purpose | |---------|---------| | @modelcontextprotocol/sdk | MCP server framework (stdio transport, tool registration) | | zod | Schema validation for tool parameters | | typescript | Build toolchain | | @types/node | Node.js type definitions |

Zero runtime dependencies beyond the MCP SDK and Zod. The server reads markdown files from disk — no database, no network calls, no API keys.