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

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

Related MCP server: ds-pilot

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

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.