# ui-mcp

> A local MCP server that gives Claude Code (and any MCP client) access to a curated registry of **elite UI patterns, components, and motion configs** — so it pulls real, copy-pasteable implementations mid-build instead of defaulting to generic layouts.

Magnetic cursors, scroll-jacked sections, reactive particle grids, clip-path page transitions, text-scramble reveals, glassmorphic navs, spring modals, bento grids, and more — every entry ships **real working React/TSX**, valid Tailwind classes, and Framer Motion / GSAP / CSS motion values.

- **30** UI patterns (clean · elevated · insane)
- **20** components keyed by type (hero, nav, card, modal, scroll-section, cursor, overlay, loader, text-reveal, background)
- **15** ready-to-paste motion configs (Framer Motion, GSAP, CSS)
- Fuzzy natural-language search via [Fuse.js](https://www.fusejs.io/)

---

## Install & setup

```bash
git clone https://github.com/maahigoel/ui-elite-patterns.git
cd ui-elite-patterns
npm install
npm run build
```

This compiles `src/` → `dist/`. The server entry is `dist/server.js`.

### Add to Claude Code

A ready-to-use [`.mcp.json`](./.mcp.json) is included:

```json
{
  "mcpServers": {
    "ui-mcp": {
      "command": "node",
      "args": ["dist/server.js"]
    }
  }
}
```

- **Project scope:** copy `.mcp.json` into your project root and run Claude Code from there. (If `args` is a relative path, run Claude Code from the `ui-mcp` directory, or change it to the absolute path of `dist/server.js`.)
- **CLI:** `claude mcp add ui-mcp -- node /absolute/path/to/ui-mcp/dist/server.js`

Restart Claude Code, then ask it to use the `ui-mcp` tools. Verify the server boots:

```bash
npm run smoke   # builds, boots the server in-memory, and exercises every tool
```

---

## Live demo site

A local showcase website that renders **every pattern and component live** lives in [`demo/`](./demo). It uses a codegen script that pulls each component straight from this registry, so it always reflects exactly what the MCP server hands to Claude Code.

```bash
cd demo
npm install
npm run dev        # generates components from the registry, then starts Vite at http://localhost:5173
```

- Browse all 50 patterns + components in a filterable gallery (search, complexity, kind).
- Click any card to view it **full-screen, running live**, with a slide-in source panel + copy button.
- `npm run generate` re-syncs the demo with the registry after you add patterns. (`npm run dev`/`build` run it automatically.)

Built with Vite + React + Tailwind + Framer Motion. Local only — no hosting required.

---

## Tools

### 1. `get_ui_pattern`

Fuzzy-search the registry by natural language.

**Input**

| field | type | required | description |
| --- | --- | --- | --- |
| `query` | string | ✅ | What you want, e.g. `"magnetic cursor"` |
| `framework` | `"react" \| "vue" \| "html"` | – | Filter by framework support |
| `complexity` | `"clean" \| "elevated" \| "insane"` | – | Filter by complexity |

**Example**

```jsonc
// input
{ "query": "scroll reveal headline", "complexity": "insane" }
```

```md
// output (truncated)
Found 3 matching patterns for "scroll reveal headline". Showing the top 3:

## Text Scramble Reveal on Scroll
**Complexity:** insane • **Frameworks:** react • **Interaction:** scroll
**Tags:** text, scramble, decode, scroll, reveal, monospace, raf
...
### Code
```tsx
import { useEffect, useRef, useState } from "react";
...
```
```

### 2. `get_component`

Get component(s) of a given type.

**Input**

| field | type | required | description |
| --- | --- | --- | --- |
| `type` | `hero \| nav \| card \| modal \| scroll-section \| cursor \| overlay \| loader \| text-reveal \| background` | ✅ | Component kind |
| `interaction` | `scroll \| hover \| entrance \| ambient` | – | Preferred interaction |
| `complexity` | `clean \| elevated \| insane` | – | Preferred complexity (nearest returned if exact missing) |

**Example**

```jsonc
// input
{ "type": "modal", "complexity": "elevated" }
```

Returns the **Spring Modal with Blur Backdrop** with full TSX and its Framer Motion config. Omit `complexity` to get every variant of that type (clean → insane).

### 3. `get_motion_config`

Get a paste-ready motion configuration.

**Input**

| field | type | required | description |
| --- | --- | --- | --- |
| `type` | `page-transition \| entrance \| scroll-reveal \| hover \| stagger \| magnetic` | ✅ | Motion kind |
| `library` | `framer-motion \| gsap \| css` | – | Filter by library |

**Example**

```jsonc
// input
{ "type": "stagger", "library": "framer-motion" }
```

```md
// output (truncated)
## Framer Motion Stagger Children (0.08s)
**Type:** stagger • **Library:** framer-motion
### Config
```json
{ "config": { "staggerChildren": 0.08, "delayChildren": 0.1 }, "variants": { ... } }
```
### Code
```tsx
const container = { hidden: {}, visible: { transition: { staggerChildren: 0.08, delayChildren: 0.1 } } };
...
```
**Usage:** Put `container` on the parent and `item` on each child; the parent drives timing.
```

---

## Example prompts inside Claude Code

- *"Use ui-mcp to find a magnetic cursor pattern and add it to my landing page."*
- *"Get me an `insane` complexity background component from ui-mcp for the hero."*
- *"Build a pricing section — grab the pricing card pattern from ui-mcp first."*
- *"I need a page transition. Pull the Framer Motion `page-transition` config from ui-mcp."*
- *"Find a scroll-jacked horizontal section in ui-mcp and wire it up with my project's content."*
- *"Get the `text-reveal` component (elevated) from ui-mcp and use it for the section heading."*

---

## Contributing — add a pattern

The registry lives in `src/registry/`:

- `patterns.ts` — patterns surfaced by `get_ui_pattern`
- `components.ts` — components surfaced by `get_component` (must set `componentType`)
- `motion.ts` — configs surfaced by `get_motion_config`

Add a new entry to the relevant array following the `RegistryEntry` shape (`src/types.ts`):

```ts
{
  id: "my-pattern",                 // unique kebab-case id
  name: "My Pattern",
  tags: ["..."],                    // drives fuzzy search — be generous
  complexity: "elevated",           // "clean" | "elevated" | "insane"
  framework: ["react"],
  componentType: "card",            // components only — enables get_component
  interaction: "hover",             // optional
  description: "One sentence on what it is.",
  implementation_notes: "How it works / gotchas.",
  code: `/* full, standalone, copy-pasteable TSX */`,
  tailwind: "the key classes used",
  motion: {                          // optional, if animated
    library: "framer-motion",
    config: { /* ... */ },
    variants: { /* ... */ },
  },
  sources: ["aceternity", "godly"],
}
```

Guidelines:

1. **Code must actually run.** Full component with imports and a `default export`, valid Tailwind, correct Framer Motion / GSAP APIs. No `// add animation here` placeholders.
2. **Tag generously** — tags are weighted heavily in search.
3. Run `npm run smoke` (it builds + type-checks + exercises the tools) before opening a PR.
4. Keep snippets self-contained (inline SVGs over icon deps; scoped `<style>` for keyframes).

---

## Credits

Patterns are original implementations inspired by the craft of the design-engineering community:

- [Aceternity UI](https://ui.aceternity.com/)
- [Godly](https://godly.website/)
- [Mobbin](https://mobbin.com/)
- [Refero](https://refero.design/)

Built on the [Model Context Protocol](https://modelcontextprotocol.io/) TypeScript SDK.

## License

[MIT](./LICENSE)