design-mcp

MCP server for design decisions during a build. Three things:

1. Multi-library docs — live-fetches and caches the official llms.txt indexes of many UI and animation libraries, so your agent can look up real component APIs instead of guessing.
2. UX laws & UI conventions — a local, curated knowledge base (Fitts's Law, Hick's Law, Jakob's Law, Gestalt principles, Nielsen heuristics, plus practical placement conventions like "where does the primary button go in a modal").
3. Runs locally (stdio) or hosted on Vercel (Streamable HTTP) — same tools, two transports.

Supported libraries

Category	Libraries
UI	Base UI, shadcn/ui, Mantine, Chakra UI, Ant Design, HeroUI, Ark UI, React Spectrum, daisyUI
Animation	Motion (framer-motion's successor), GSAP
Reference	React

Add more by editing src/data/doc-sources.json (any site publishing llms.txt) and rebuilding — no code changes needed.

Local setup

npm install
npm run build

This compiles src/ to dist/ and copies the JSON knowledge bases alongside it.

opencode — add to your MCP config:

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

Claude Code / Claude Desktop:

claude mcp add design-mcp -- node /absolute/path/to/design-mcp/dist/index.js

Restart the client after registering.

Host on Vercel

The api/mcp.ts function serves the same server over Streamable HTTP (sessions, JSON or SSE responses). Just push the repo to GitHub and import it in Vercel:

1. Push to GitHub (below).
2. In vercel.com/new, Import the repo.
3. Framework preset: Other. Build command: npm run build. Everything else default.
4. Deploy. Your MCP endpoint is https://<your-project>.vercel.app/api/mcp.

Then point any MCP client at the URL:

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "design-mcp": {
      "url": "https://<your-project>.vercel.app/api/mcp"
    }
  }
}

opencode — opencode.json:

{
  "mcp": {
    "design-mcp": {
      "type": "remote",
      "url": "https://<your-project>.vercel.app/api/mcp",
      "enabled": true
    }
  }
}

Push to GitHub

git add -A
git commit -m "Add multi-library docs, animations, and Vercel hosting"
git push origin main

Tools exposed

Tool	What it does
search_ux_principles	Keyword search across UX laws/heuristics
get_ux_principle	Full detail on one named law
list_ux_principles	Full list of everything in the local KB
check_ui_pattern	Placement conventions (button position, back/close, FAB, forms, destructive actions, progress bars)
list_doc_libraries	List all supported UI/animation libraries
list_library_docs	Full docs index for one library
search_library_docs	Keyword search inside one library, returns matching page content
get_library_doc	Full docs for one named page/component in a library
list_baseui_components	Shortcut for list_library_docs (base-ui)
search_baseui_docs	Shortcut for search_library_docs (base-ui)
get_baseui_component	Shortcut for get_library_doc (base-ui)

Notes

• Library indexes/pages are cached 24h (.cache/ on local, in-memory on Vercel) to avoid hammering doc sites.
• If a doc site is unreachable, the doc tools return an error message rather than crashing; the UX/convention tools work fully offline.
• On Vercel, sessions live per serverless instance — if a new instance spins up, the client simply re-initializes a new session.
• To extend the knowledge base, edit src/data/ux-principles.json, src/data/ui-conventions.json, or src/data/doc-sources.json and rebuild.