# 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

```bash
npm install
npm run build
```

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

**opencode** — add to your MCP config:

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

**Claude Code / Claude Desktop**:

```bash
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](https://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`:

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

**opencode** — `opencode.json`:

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

## Push to GitHub

```bash
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.