frontend-inspo-mcp 0.2.0 β†’ 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,301 +1,328 @@
1
- # frontend-inspo-mcp 🎨
2
-
3
- > **A local MCP server that lets AI coding agents discover and pull real frontend code, UI components, design mockups, and design-system tokens** β€” from FreeFrontend, shadcn/ui, Magic UI, Aceternity UI, React Bits, Fancy Components, VengeanceUI, Refero Styles, three.js, drei, React Three Fiber, react-spring, zustand, glyph, postprocessing, detect-gpu, ShaderGradient, liquid-logo, liquid-glass-js, ThreeUI, img2threejs, GSAP, Two.js, scrollama, Watermelon UI, and LS.GRAPHICS.
4
-
5
- [![npm version](https://img.shields.io/npm/v/frontend-inspo-mcp.svg)](https://www.npmjs.com/package/frontend-inspo-mcp)
6
- [![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-blue)](https://modelcontextprotocol.io)
7
- [![TypeScript](https://img.shields.io/badge/TypeScript-7.0-3178c6)](https://www.typescriptlang.org/)
8
- [![Node](https://img.shields.io/badge/Node-18%2B-339933)](https://nodejs.org/)
9
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](#license)
10
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
11
-
12
- Give Claude, Cursor, Kiro, or any MCP-compatible agent instant access to **thousands of
13
- copy-paste UI components and free design assets** β€” with the **actual source code**, not
14
- just links. Ask for "a glassmorphism card" or "an animated shadcn button" and get real,
15
- usable code back.
16
-
17
- ## πŸ“¦ Install from npm (no clone needed)
18
-
19
- Add this to your MCP client config and restart it; `npx` fetches and runs the server for you:
20
-
21
- ```json
22
- {
23
- "mcpServers": {
24
- "frontend-inspo": {
25
- "command": "npx",
26
- "args": ["-y", "frontend-inspo-mcp"]
27
- }
28
- }
29
- }
30
- ```
31
-
32
- - **Claude Desktop** β€” paste it into `claude_desktop_config.json`
33
- (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`).
34
- - **Claude Code** β€” run `claude mcp add frontend-inspo -- npx -y frontend-inspo-mcp`,
35
- or put the same JSON in a project-level `.mcp.json`.
36
- - **Cursor** β€” paste it into `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project).
37
-
38
- Prefer to hack on it? See [Quick start](#-quick-start) to run from source.
39
-
40
- ## 🎬 Demo
41
-
42
- <!-- TODO: replace with recorded demo video -->
43
- Demo video coming soon.
44
-
45
- ---
46
-
47
- ## ✨ Why use this?
48
-
49
- Most component galleries are built for humans clicking around a browser. This server makes
50
- them **agent-readable**, so your AI assistant can search, compare, and paste real code
51
- directly into your project.
52
-
53
- - πŸ” **Search 27 sources** through one consistent set of tools
54
- - πŸ“‹ **Get real code** β€” React/TSX, Tailwind, vanilla HTML/CSS/JS
55
- - 🎭 **Free design mockups** with direct, un-gated download links (Figma / Sketch / PSD)
56
- - ⚑ **Fast** β€” in-memory caching + polite per-host rate limiting
57
- - 🧩 **Pluggable** β€” add a new source in one small adapter file
58
-
59
- ## πŸ“š Sources
60
-
61
- | Source | What it gives you | Inline code? | Access |
62
- | --- | --- | :---: | --- |
63
- | **[FreeFrontend](https://freefrontend.com/)** | HTML / CSS / JS / Bootstrap / Tailwind snippets | βœ… | HTML parse + base64 |
64
- | **[shadcn/ui](https://ui.shadcn.com/)** | React + Tailwind + Radix components | βœ… | Registry JSON |
65
- | **[Magic UI](https://magicui.design/)** | Animated React + Framer Motion components | βœ… | Registry JSON |
66
- | **[Aceternity UI](https://ui.aceternity.com/)** | Bold animated React + Tailwind components | βœ… | Registry JSON |
67
- | **[React Bits](https://reactbits.dev/)** | Animated React components (JS/TS, CSS/Tailwind) | βœ… | Registry JSON |
68
- | **[Fancy Components](https://fancycomponents.dev/)** | Motion, scroll, text-physics & 2D effect React components | βœ… | Registry JSON |
69
- | **[VengeanceUI](https://github.com/Ashutoshx7/VengeanceUI)** | Animated React + Tailwind + Framer Motion components | βœ… | Registry JSON (GitHub) |
70
- | **[Canvas UI](https://canvasui.dev/)** | React WebGL/canvas & animated components | βœ… | Registry JSON |
71
- | **[Refero Styles](https://styles.refero.design/)** | Design systems from real sites β€” DESIGN.md, Tailwind, CSS vars, tokens | βœ… | Public API (no login) |
72
- | **[three.js](https://threejs.org/)** | Official examples β€” GLSL shaders, post-fx, loaders, controls | βœ… | jsdelivr CDN |
73
- | **[drei](https://github.com/pmndrs/drei)** | React Three Fiber helper components | βœ… | GitHub source |
74
- | **[React Three Fiber](https://r3f.docs.pmnd.rs/)** | Curated R3F guidance (Canvas/hooks, geometry, scroll storytelling) | βœ… | Bundled offline |
75
- | **[react-spring](https://github.com/pmndrs/react-spring)** | Spring-physics animation library for React | βœ… | GitHub source |
76
- | **[zustand](https://github.com/pmndrs/zustand)** | Minimal state management for React (core + middleware) | βœ… | GitHub source |
77
- | **[glyph](https://github.com/pmndrs/glyph)** | GPU text/geometry glyph baking utilities (TSL, typegpu) | βœ… | GitHub source |
78
- | **[postprocessing](https://github.com/pmndrs/postprocessing)** | Post-processing effects + EffectComposer for three.js | βœ… | GitHub source |
79
- | **[detect-gpu](https://github.com/pmndrs/detect-gpu)** | Classify a device's GPU tier via benchmarks | βœ… | GitHub source |
80
- | **[ShaderGradient](https://github.com/ruucm/shadergradient)** | Animated customizable gradient meshes for R3F/three.js | βœ… | GitHub source |
81
- | **[liquid-logo](https://github.com/collidingScopes/liquid-logo)** | Animated liquid-metal WebGL effect from a logo/image (GLSL) | βœ… | GitHub source |
82
- | **[liquid-glass-js](https://github.com/dashersw/liquid-glass-js)** | Apple-style "liquid glass" refraction effect for the web | βœ… | GitHub source |
83
- | **[ThreeUI](https://threeui.com/browse)** | Community Three.js/WebGL components & landing pages | βœ… | GitHub manifest |
84
- | **[img2threejs](https://github.com/img2threejs/img2threejs)** | Image β†’ three.js/GLB 3D scene pipeline (Python) | βœ… | GitHub source |
85
- | **[GSAP Skills](https://github.com/greensock/gsap-skills)** | Official GSAP agent guidance + runnable examples | βœ… | GitHub source |
86
- | **[Two.js](https://two.js.org/)** | 2D drawing / animation library source | βœ… | jsdelivr CDN |
87
- | **[scrollama](https://github.com/russellsamora/scrollama)** | Scrollytelling / scroll-storytelling library source | βœ… | jsdelivr CDN |
88
- | **[Watermelon UI](https://ui.watermelon.sh/)** | React components, blocks, dashboards, templates | β€” | Official JSON API |
89
- | **[LS.GRAPHICS](https://www.ls.graphics/free-mockups)** | Free design mockups (Figma / Sketch / PSD) | β€” | HTML parse |
90
-
91
- ## πŸš€ Quick start
92
-
93
- ```bash
94
- git clone https://github.com/notsointresting/frontend-inspo-mcp.git
95
- cd frontend-inspo-mcp
96
- npm install
97
- npm run build
98
- ```
99
-
100
- Requires **Node 18+** (uses the built-in `fetch`).
101
-
102
- Verify every source is live:
103
-
104
- ```bash
105
- npm run smoke # hits all 27 sources and asserts parsing β†’ prints ALL PASS
106
- ```
107
-
108
- ## πŸ”Œ Add it to your MCP client
109
-
110
- The server speaks MCP over **stdio**. Point your client at the built `dist/index.js`.
111
-
112
- ### Claude Desktop / Cursor / generic (`claude_desktop_config.json`)
113
-
114
- ```json
115
- {
116
- "mcpServers": {
117
- "frontend-inspo": {
118
- "command": "node",
119
- "args": ["/absolute/path/to/frontend-inspo-mcp/dist/index.js"]
120
- }
121
- }
122
- }
123
- ```
124
-
125
- ### Claude Code (`~/.claude.json`, global `mcpServers`)
126
-
127
- ```json
128
- {
129
- "mcpServers": {
130
- "frontend-inspo": {
131
- "type": "stdio",
132
- "command": "node",
133
- "args": ["/absolute/path/to/frontend-inspo-mcp/dist/index.js"]
134
- }
135
- }
136
- }
137
- ```
138
-
139
- > On Windows use escaped backslashes, e.g. `"C:\\path\\to\\dist\\index.js"`.
140
-
141
- ## πŸ› οΈ Tools
142
-
143
- Every tool takes a `source` argument:
144
- `freefrontend` Β· `shadcn` Β· `magicui` Β· `aceternity` Β· `reactbits` Β· `fancy` Β· `vengeanceui` Β· `canvasui` Β· `refero` Β· `threejs` Β· `drei` Β· `r3f` Β· `reactspring` Β· `zustand` Β· `glyph` Β· `postprocessing` Β· `detectgpu` Β· `shadergradient` Β· `liquidlogo` Β· `liquidglass` Β· `threeui` Β· `img2threejs` Β· `gsap` Β· `twojs` Β· `scrollama` Β· `watermelon` Β· `lsgraphics`
145
-
146
- | Tool | Description |
147
- | --- | --- |
148
- | `list_sources` | List all sources and whether each returns inline code |
149
- | `list_categories` | Categories/collections/kinds for a source |
150
- | `search_resources` | Search by `query`, `category`, `tech`, `limit` β€” returns lightweight summaries |
151
- | `search_all` | Search **many sources at once** and merge results (parallel; per-source failures are reported, not fatal) |
152
- | `get_resource` | Full detail for one item (metadata, license, code, formats, downloads) |
153
- | `get_code` | Raw source code for code-bearing sources, keyed by language |
154
-
155
- ### Examples
156
-
157
- Search animated React components:
158
-
159
- ```json
160
- { "source": "magicui", "query": "marquee", "limit": 5 }
161
- ```
162
-
163
- Get a shadcn button's real source:
164
-
165
- ```json
166
- { "source": "shadcn", "id": "button" }
167
- ```
168
-
169
- Grab a CSS hover effect with code:
170
-
171
- ```json
172
- { "source": "freefrontend", "category": "css-hover-effects", "limit": 5 }
173
- ```
174
-
175
- Find a free device mockup:
176
-
177
- ```json
178
- { "source": "lsgraphics", "id": "macbook-mockup" }
179
- ```
180
-
181
- ## πŸ’¬ Try it in one prompt
182
-
183
- > *"Build me a personal portfolio landing page. Use the frontend-inspo MCP: pull an
184
- > animated hero text effect from Magic UI, a shadcn card for the projects grid, a CSS
185
- > hover effect from FreeFrontend, and a free laptop mockup from LS.GRAPHICS β€” then
186
- > assemble it into a single `index.html`."*
187
-
188
- ## 🧭 How it works
189
-
190
- - **Registry sources** (shadcn, Magic UI, Aceternity, React Bits) share one adapter that
191
- reads the [shadcn registry schema](https://ui.shadcn.com/docs/registry) β€” an index of
192
- items plus per-item JSON containing the real component source.
193
- - **FreeFrontend** parses server-rendered collection pages and base64-decodes the inline
194
- code blocks; pagination follows `/<collection>/page/N/`.
195
- - **Watermelon UI** calls its documented public API (`/api/v1/catalog/*`).
196
- - **Refero Styles** calls the **public** `styles.refero.design/api/styles` endpoints and
197
- synthesizes a DESIGN.md, Tailwind theme, CSS variables, and design-token JSON from the
198
- returned design-system data β€” **no Refero subscription is required**.
199
- - **three.js** lists the published npm package file tree via jsdelivr and fetches raw
200
- source (GLSL shaders, post-processing, loaders, controls) from the CDN.
201
- - **drei** reads the `pmndrs/drei` GitHub source tree and raw files. Set an optional
202
- `GITHUB_TOKEN` env var to lift GitHub's unauthenticated rate limit (60 req/hr).
203
- - **GitHub source-tree libraries** (react-spring, zustand, glyph, postprocessing,
204
- detect-gpu, ShaderGradient, liquid-logo, liquid-glass-js, img2threejs, GSAP Skills, drei)
205
- share one adapter that lists a repo's git tree on its default branch, keeps the relevant
206
- files, and serves raw source. Branches vary (`main`/`master`/`next`) and are configured
207
- per source. The same optional `GITHUB_TOKEN` applies.
208
- - **VengeanceUI** uses the registry adapter, reading its shadcn-schema `registry.json` and
209
- per-item JSON directly from raw GitHub.
210
- - **React Three Fiber (r3f)** serves a bundled, offline R3F guidance skill (no network).
211
- - **ThreeUI** fetches the `MengTo/threeui` Community `source-code.json` manifest once and
212
- caches the parsed catalog in-process (the manifest is large), then returns each
213
- component's inline HTML/JS/GLSL/CSS.
214
- - **LS.GRAPHICS** parses the free-mockups listing and each asset page for formats and
215
- download links.
216
-
217
- Requests are cached in memory (10-min TTL) and throttled per host to stay polite.
218
-
219
- ### Optional: persistent cache
220
-
221
- By default the cache is in-memory (cleared on restart). To persist responses across
222
- restarts, set an env var pointing at a writable directory:
223
-
224
- ```bash
225
- FRONTEND_INSPO_CACHE_DIR=/path/to/cache
226
- ```
227
-
228
- When set, responses are stored on disk (same 10-min TTL) so repeated runs skip the network.
229
-
230
- ## πŸ—‚οΈ Project layout
231
-
232
- ```
233
- src/
234
- index.ts server + tool registration
235
- smoke.ts live per-adapter checks
236
- lib/
237
- types.ts shared types + SourceAdapter contract
238
- fetch.ts cached, throttled HTTP + base64 decode
239
- sources/
240
- freefrontend.ts HTML parse + base64 code decode
241
- watermelon.ts JSON API client
242
- lsgraphics.ts HTML parse (mockups)
243
- registry.ts shadcn-schema registry factory (shadcn/magicui/aceternity/reactbits)
244
- refero.ts Refero public API -> synthesized DESIGN.md / tokens
245
- packages.ts code libraries via jsdelivr (three.js) + GitHub (drei)
246
- ```
247
-
248
- ## 🀝 Contributing
249
-
250
- New sources are welcome β€” most fit in one small adapter file implementing the
251
- `SourceAdapter` contract in `src/lib/types.ts`. Open a PR.
252
-
253
- ## πŸ™ Credits & acknowledgements
254
-
255
- This project is a **discovery layer** over third-party resources. All content, code
256
- snippets, components, and mockups belong to their original creators. Please respect each
257
- source's license before reusing anything.
258
-
259
- - **[FreeFrontend](https://freefrontend.com/)** β€” curated frontend code snippets (per-item licenses, often MIT)
260
- - **[shadcn/ui](https://ui.shadcn.com/)** by [@shadcn](https://github.com/shadcn) β€” MIT
261
- - **[Magic UI](https://magicui.design/)** β€” MIT
262
- - **[Aceternity UI](https://ui.aceternity.com/)** by [Manu Arora](https://twitter.com/mannupaaji)
263
- - **[React Bits](https://reactbits.dev/)** by [David Haz](https://github.com/DavidHDev) β€” MIT
264
- - **[Refero](https://refero.design/)** β€” design-system references extracted from public websites (data served via Refero's public API; each referenced site owns its brand)
265
- - **[three.js](https://threejs.org/)** by [mrdoob](https://github.com/mrdoob) & contributors β€” MIT
266
- - **[drei](https://github.com/pmndrs/drei)** by [pmndrs](https://github.com/pmndrs) β€” MIT
267
- - **[react-spring](https://github.com/pmndrs/react-spring)** by [pmndrs](https://github.com/pmndrs) β€” MIT
268
- - **[zustand](https://github.com/pmndrs/zustand)** by [pmndrs](https://github.com/pmndrs) β€” MIT
269
- - **[glyph](https://github.com/pmndrs/glyph)** by [pmndrs](https://github.com/pmndrs) β€” MIT
270
- - **[postprocessing](https://github.com/pmndrs/postprocessing)** by [Raoul van RΓΌschen](https://github.com/vanruesc) β€” Zlib
271
- - **[detect-gpu](https://github.com/pmndrs/detect-gpu)** by [pmndrs](https://github.com/pmndrs) β€” MIT
272
- - **[ShaderGradient](https://github.com/ruucm/shadergradient)** by [ruucm](https://github.com/ruucm)
273
- - **[liquid-logo](https://github.com/collidingScopes/liquid-logo)** by [collidingScopes](https://github.com/collidingScopes) β€” MIT
274
- - **[liquid-glass-js](https://github.com/dashersw/liquid-glass-js)** by [Armagan Amcalar](https://github.com/dashersw) β€” MIT
275
- - **[ThreeUI](https://github.com/MengTo/threeui)** by [Meng To](https://github.com/MengTo) β€” MIT
276
- - **[img2threejs](https://github.com/img2threejs/img2threejs)** β€” Apache-2.0
277
- - **[GSAP](https://github.com/greensock/gsap-skills)** by [GreenSock](https://github.com/greensock) β€” MIT
278
- - **[VengeanceUI](https://github.com/Ashutoshx7/VengeanceUI)** by [Ashutosh](https://github.com/Ashutoshx7) β€” MIT
279
- - **[Canvas UI](https://canvasui.dev/)** by [David Haz](https://github.com/DavidHDev) β€” MIT
280
- - **[Fancy Components](https://fancycomponents.dev/)** by [Daniel Petho](https://github.com/danielpetho) β€” MIT
281
- - **[Two.js](https://two.js.org/)** by [jonobr1](https://github.com/jonobr1) β€” MIT
282
- - **[scrollama](https://github.com/russellsamora/scrollama)** by [Russell Samora](https://github.com/russellsamora) β€” MIT
283
- - **[Watermelon UI](https://ui.watermelon.sh/)** β€” open-source React platform
284
- - **[LS.GRAPHICS](https://www.ls.graphics/)** β€” free & premium design mockups
285
-
286
- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol) and
287
- [cheerio](https://cheerio.js.org/).
288
-
289
- ## πŸ“„ License
290
-
291
- MIT Β© [notsointresting](https://github.com/notsointresting) β€” for the server code.
292
- Third-party resources retrieved through it remain under their respective licenses.
293
-
294
- ---
295
-
296
- <sub>**Keywords:** MCP server Β· Model Context Protocol Β· AI coding agent Β· UI components Β·
297
- React components Β· Tailwind CSS Β· shadcn/ui Β· Magic UI Β· Aceternity UI Β· React Bits Β·
298
- FreeFrontend Β· design mockups Β· Figma Β· component library Β· copy-paste UI Β·
299
- design tokens Β· DESIGN.md Β· design system Β· Refero Β· three.js Β· GLSL shaders Β· WebGL Β·
300
- React Three Fiber Β· drei Β·
301
- Claude Β· Cursor Β· frontend design Β· CSS snippets Β· Watermelon UI Β· LS.GRAPHICS.</sub>
1
+ # frontend-inspo-mcp 🎨
2
+
3
+ > **A local MCP server that lets AI coding agents discover and pull real frontend code, UI components, design mockups, and design-system tokens** β€” from FreeFrontend, shadcn/ui, Magic UI, Aceternity UI, React Bits, Fancy Components, VengeanceUI, Refero Styles, three.js, drei, React Three Fiber, react-spring, zustand, glyph, postprocessing, detect-gpu, ShaderGradient, liquid-logo, liquid-glass-js, ThreeUI, img2threejs, GSAP, Two.js, scrollama, Watermelon UI, and LS.GRAPHICS.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/frontend-inspo-mcp.svg)](https://www.npmjs.com/package/frontend-inspo-mcp)
6
+ [![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-blue)](https://modelcontextprotocol.io)
7
+ [![TypeScript](https://img.shields.io/badge/TypeScript-7.0-3178c6)](https://www.typescriptlang.org/)
8
+ [![Node](https://img.shields.io/badge/Node-20.18%2B-339933)](https://nodejs.org/)
9
+ [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15252/badge)](https://www.bestpractices.dev/projects/15252)
10
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](#license)
11
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
12
+
13
+ Give Claude, Cursor, Kiro, or any MCP-compatible agent instant access to **thousands of
14
+ copy-paste UI components and free design assets** β€” with the **actual source code**, not
15
+ just links. Ask for "a glassmorphism card" or "an animated shadcn button" and get real,
16
+ usable code back.
17
+
18
+ ## πŸ“¦ Install from npm (no clone needed)
19
+
20
+ Add this to your MCP client config and restart it; `npx` fetches and runs the server for you:
21
+
22
+ ```json
23
+ {
24
+ "mcpServers": {
25
+ "frontend-inspo": {
26
+ "command": "npx",
27
+ "args": ["-y", "frontend-inspo-mcp"]
28
+ }
29
+ }
30
+ }
31
+ ```
32
+
33
+ - **Claude Desktop** β€” paste it into `claude_desktop_config.json`
34
+ (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`).
35
+ - **Claude Code** β€” run `claude mcp add frontend-inspo -- npx -y frontend-inspo-mcp`,
36
+ or put the same JSON in a project-level `.mcp.json`.
37
+ - **Cursor** β€” paste it into `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project).
38
+
39
+ Prefer to hack on it? See [Quick start](#-quick-start) to run from source.
40
+
41
+ ## 🎬 Demo
42
+
43
+ <!-- TODO: replace with recorded demo video -->
44
+ Demo video coming soon.
45
+
46
+ ---
47
+
48
+ ## ✨ Why use this?
49
+
50
+ Most component galleries are built for humans clicking around a browser. This server makes
51
+ them **agent-readable**, so your AI assistant can search, compare, and paste real code
52
+ directly into your project.
53
+
54
+ - πŸ” **Search 27 sources** through one consistent set of tools
55
+ - πŸ“‹ **Get real code** β€” React/TSX, Tailwind, vanilla HTML/CSS/JS
56
+ - 🎭 **Free design mockups** with direct, un-gated download links (Figma / Sketch / PSD)
57
+ - ⚑ **Fast** β€” in-memory caching + polite per-host rate limiting
58
+ - 🧩 **Pluggable** β€” add a new source in one small adapter file
59
+
60
+ ## πŸ“š Sources
61
+
62
+ | Source | What it gives you | Inline code? | Access |
63
+ | --- | --- | :---: | --- |
64
+ | **[FreeFrontend](https://freefrontend.com/)** | HTML / CSS / JS / Bootstrap / Tailwind snippets | βœ… | HTML parse + base64 |
65
+ | **[shadcn/ui](https://ui.shadcn.com/)** | React + Tailwind + Radix components | βœ… | Registry JSON |
66
+ | **[Magic UI](https://magicui.design/)** | Animated React + Framer Motion components | βœ… | Registry JSON |
67
+ | **[Aceternity UI](https://ui.aceternity.com/)** | Bold animated React + Tailwind components | βœ… | Registry JSON |
68
+ | **[React Bits](https://reactbits.dev/)** | Animated React components (JS/TS, CSS/Tailwind) | βœ… | Registry JSON |
69
+ | **[Fancy Components](https://fancycomponents.dev/)** | Motion, scroll, text-physics & 2D effect React components | βœ… | Registry JSON |
70
+ | **[VengeanceUI](https://github.com/Ashutoshx7/VengeanceUI)** | Animated React + Tailwind + Framer Motion components | βœ… | Registry JSON (GitHub) |
71
+ | **[Canvas UI](https://canvasui.dev/)** | React WebGL/canvas & animated components | βœ… | Registry JSON |
72
+ | **[Refero Styles](https://styles.refero.design/)** | Design systems from real sites β€” DESIGN.md, Tailwind, CSS vars, tokens | βœ… | Public pages (no login) |
73
+ | **[three.js](https://threejs.org/)** | Official examples β€” GLSL shaders, post-fx, loaders, controls | βœ… | jsdelivr CDN |
74
+ | **[drei](https://github.com/pmndrs/drei)** | React Three Fiber helper components | βœ… | GitHub source |
75
+ | **[React Three Fiber](https://r3f.docs.pmnd.rs/)** | Curated R3F guidance (Canvas/hooks, geometry, scroll storytelling) | βœ… | Bundled offline |
76
+ | **[react-spring](https://github.com/pmndrs/react-spring)** | Spring-physics animation library for React | βœ… | GitHub source |
77
+ | **[zustand](https://github.com/pmndrs/zustand)** | Minimal state management for React (core + middleware) | βœ… | GitHub source |
78
+ | **[glyph](https://github.com/pmndrs/glyph)** | GPU text/geometry glyph baking utilities (TSL, typegpu) | βœ… | GitHub source |
79
+ | **[postprocessing](https://github.com/pmndrs/postprocessing)** | Post-processing effects + EffectComposer for three.js | βœ… | GitHub source |
80
+ | **[detect-gpu](https://github.com/pmndrs/detect-gpu)** | Classify a device's GPU tier via benchmarks | βœ… | GitHub source |
81
+ | **[ShaderGradient](https://github.com/ruucm/shadergradient)** | Animated customizable gradient meshes for R3F/three.js | βœ… | GitHub source |
82
+ | **[liquid-logo](https://github.com/collidingScopes/liquid-logo)** | Animated liquid-metal WebGL effect from a logo/image (GLSL) | βœ… | GitHub source |
83
+ | **[liquid-glass-js](https://github.com/dashersw/liquid-glass-js)** | Apple-style "liquid glass" refraction effect for the web | βœ… | GitHub source |
84
+ | **[ThreeUI](https://threeui.com/browse)** | Community Three.js/WebGL components & landing pages | βœ… | GitHub manifest |
85
+ | **[img2threejs](https://github.com/img2threejs/img2threejs)** | Image β†’ three.js/GLB 3D scene pipeline (Python) | βœ… | GitHub source |
86
+ | **[GSAP Skills](https://github.com/greensock/gsap-skills)** | Official GSAP agent guidance + runnable examples | βœ… | GitHub source |
87
+ | **[Two.js](https://two.js.org/)** | 2D drawing / animation library source | βœ… | jsdelivr CDN |
88
+ | **[scrollama](https://github.com/russellsamora/scrollama)** | Scrollytelling / scroll-storytelling library source | βœ… | jsdelivr CDN |
89
+ | **[Watermelon UI](https://ui.watermelon.sh/)** | React components, blocks, dashboards, templates | β€” | Official JSON API |
90
+ | **[LS.GRAPHICS](https://www.ls.graphics/free-mockups)** | Free design mockups (Figma / Sketch / PSD) | β€” | HTML parse |
91
+
92
+ ## πŸš€ Quick start
93
+
94
+ ```bash
95
+ git clone https://github.com/notsointresting/frontend-inspo-mcp.git
96
+ cd frontend-inspo-mcp
97
+ npm install
98
+ npm run build
99
+ ```
100
+
101
+ Requires **Node 20.18.1+** (uses the built-in `fetch`).
102
+
103
+ Run the offline unit tests (no network needed):
104
+
105
+ ```bash
106
+ npm test
107
+ ```
108
+
109
+ Verify every source is live:
110
+
111
+ ```bash
112
+ npm run smoke # hits all 27 sources and asserts parsing β†’ prints ALL PASS
113
+ ```
114
+
115
+ ## πŸ”Œ Add it to your MCP client
116
+
117
+ The server speaks MCP over **stdio**. Point your client at the built `dist/index.js`.
118
+
119
+ ### Claude Desktop / Cursor / generic (`claude_desktop_config.json`)
120
+
121
+ ```json
122
+ {
123
+ "mcpServers": {
124
+ "frontend-inspo": {
125
+ "command": "node",
126
+ "args": ["/absolute/path/to/frontend-inspo-mcp/dist/index.js"]
127
+ }
128
+ }
129
+ }
130
+ ```
131
+
132
+ ### Claude Code (`~/.claude.json`, global `mcpServers`)
133
+
134
+ ```json
135
+ {
136
+ "mcpServers": {
137
+ "frontend-inspo": {
138
+ "type": "stdio",
139
+ "command": "node",
140
+ "args": ["/absolute/path/to/frontend-inspo-mcp/dist/index.js"]
141
+ }
142
+ }
143
+ }
144
+ ```
145
+
146
+ > On Windows use escaped backslashes, e.g. `"C:\\path\\to\\dist\\index.js"`.
147
+
148
+ ## πŸ› οΈ Tools
149
+
150
+ Every tool takes a `source` argument:
151
+ `freefrontend` Β· `shadcn` Β· `magicui` Β· `aceternity` Β· `reactbits` Β· `fancy` Β· `vengeanceui` Β· `canvasui` Β· `refero` Β· `threejs` Β· `drei` Β· `r3f` Β· `reactspring` Β· `zustand` Β· `glyph` Β· `postprocessing` Β· `detectgpu` Β· `shadergradient` Β· `liquidlogo` Β· `liquidglass` Β· `threeui` Β· `img2threejs` Β· `gsap` Β· `twojs` Β· `scrollama` Β· `watermelon` Β· `lsgraphics`
152
+
153
+ | Tool | Description |
154
+ | --- | --- |
155
+ | `list_sources` | List all sources and whether each returns inline code |
156
+ | `list_categories` | Categories/collections/kinds for a source |
157
+ | `search_resources` | Search by `query`, `category`, `tech`, `limit` β€” returns lightweight summaries |
158
+ | `search_all` | Search **many sources at once** and merge results (parallel; per-source failures are reported, not fatal) |
159
+ | `get_resource` | Full detail for one item (metadata, license, code, formats, downloads) |
160
+ | `get_code` | Raw source code for code-bearing sources, keyed by language |
161
+
162
+ ### Examples
163
+
164
+ Search animated React components:
165
+
166
+ ```json
167
+ { "source": "magicui", "query": "marquee", "limit": 5 }
168
+ ```
169
+
170
+ Get a shadcn button's real source:
171
+
172
+ ```json
173
+ { "source": "shadcn", "id": "button" }
174
+ ```
175
+
176
+ Grab a CSS hover effect with code:
177
+
178
+ ```json
179
+ { "source": "freefrontend", "category": "css-hover-effects", "limit": 5 }
180
+ ```
181
+
182
+ Find a free device mockup:
183
+
184
+ ```json
185
+ { "source": "lsgraphics", "id": "macbook-mockup" }
186
+ ```
187
+
188
+ ## πŸ’¬ Try it in one prompt
189
+
190
+ > *"Build me a personal portfolio landing page. Use the frontend-inspo MCP: pull an
191
+ > animated hero text effect from Magic UI, a shadcn card for the projects grid, a CSS
192
+ > hover effect from FreeFrontend, and a free laptop mockup from LS.GRAPHICS β€” then
193
+ > assemble it into a single `index.html`."*
194
+
195
+ ## 🧭 How it works
196
+
197
+ - **Registry sources** (shadcn, Magic UI, Aceternity, React Bits, Fancy Components, VengeanceUI, Canvas UI) share one adapter that
198
+ reads the [shadcn registry schema](https://ui.shadcn.com/docs/registry) β€” an index of
199
+ items plus per-item JSON containing the real component source.
200
+ - **FreeFrontend** parses server-rendered collection pages and base64-decodes the inline
201
+ code blocks; pagination follows `/<collection>/page/N/`.
202
+ - **Watermelon UI** calls its documented public API (`/api/v1/catalog/*`).
203
+ - **Refero Styles** reads the public, server-rendered gallery and `/style/<id>` pages of
204
+ `styles.refero.design` (its `/api/` path is disallowed by `robots.txt`, so it is not used)
205
+ and synthesizes a DESIGN.md, Tailwind theme, CSS variables, and design-token JSON from the
206
+ embedded design-system data β€” **no Refero subscription is required**.
207
+ - **three.js** lists the published npm package file tree via jsdelivr and fetches raw
208
+ source (GLSL shaders, post-processing, loaders, controls) from the CDN.
209
+ - **drei** reads the `pmndrs/drei` GitHub source tree and raw files. Set an optional
210
+ `GITHUB_TOKEN` env var to lift GitHub's unauthenticated rate limit (60 req/hr).
211
+ - **GitHub source-tree libraries** (react-spring, zustand, glyph, postprocessing,
212
+ detect-gpu, ShaderGradient, liquid-logo, liquid-glass-js, img2threejs, GSAP Skills, drei)
213
+ share one adapter that lists a repo's git tree on its default branch, keeps the relevant
214
+ files, and serves raw source. Branches vary (`main`/`master`/`next`) and are configured
215
+ per source. The same optional `GITHUB_TOKEN` applies.
216
+ - **VengeanceUI** uses the registry adapter, reading its shadcn-schema `registry.json` and
217
+ per-item JSON directly from raw GitHub.
218
+ - **React Three Fiber (r3f)** serves a bundled, offline R3F guidance skill (no network).
219
+ - **ThreeUI** fetches the `MengTo/threeui` Community `source-code.json` manifest once and
220
+ caches the parsed catalog in-process (the manifest is large), then returns each
221
+ component's inline HTML/JS/GLSL/CSS.
222
+ - **LS.GRAPHICS** parses the free-mockups listing and each asset page for formats and
223
+ download links.
224
+
225
+ Requests use HTTPS only, are cached in memory (10-min TTL), throttled per host to stay polite, and retried with backoff on rate limits.
226
+
227
+ ### Optional: persistent cache
228
+
229
+ By default the cache is in-memory (cleared on restart). To persist responses across
230
+ restarts, set an env var pointing at a writable directory:
231
+
232
+ ```bash
233
+ FRONTEND_INSPO_CACHE_DIR=/path/to/cache
234
+ ```
235
+
236
+ When set, responses are stored on disk (same 10-min TTL) so repeated runs skip the network.
237
+
238
+ ## πŸ—‚οΈ Project layout
239
+
240
+ ```
241
+ src/
242
+ index.ts stdio launcher (npm bin)
243
+ server.ts the six MCP tools, input validation, response size cap
244
+ smoke.ts live per-source checks (npm run smoke)
245
+ lib/
246
+ types.ts shared types + SourceAdapter contract
247
+ validate.ts allowlist schemas for tool arguments
248
+ fetch.ts HTTPS-only, cached, throttled HTTP with retry/backoff
249
+ sources/
250
+ registry.ts shadcn-schema registry factory (7 sources)
251
+ packages.ts source trees via jsDelivr + GitHub (14 sources)
252
+ freefrontend.ts HTML parse + base64 code decode
253
+ watermelon.ts JSON API client
254
+ lsgraphics.ts HTML parse (mockups)
255
+ refero.ts Refero public pages -> synthesized DESIGN.md / tokens
256
+ threeui.ts ThreeUI manifest
257
+ r3f.ts bundled React Three Fiber guide (offline)
258
+ tests/ offline unit tests (node:test), network faked
259
+ scripts/ build helpers + reproducible-build check
260
+ ```
261
+
262
+ How the pieces fit together is described in [ARCHITECTURE.md](ARCHITECTURE.md).
263
+
264
+ ## 🀝 Contributing
265
+
266
+ New sources are welcome β€” most fit in one small adapter file implementing the
267
+ `SourceAdapter` contract in `src/lib/types.ts`. Open a PR.
268
+
269
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for the step-by-step guide, code standards, and the checks a PR must pass.
270
+
271
+ Project documents:
272
+
273
+ - [ROADMAP.md](ROADMAP.md): what is planned for the next year, and what is out of scope
274
+ - [GOVERNANCE.md](GOVERNANCE.md): how decisions are made, roles, and releases
275
+ - [ARCHITECTURE.md](ARCHITECTURE.md): how the server is built
276
+ - [SECURITY.md](SECURITY.md) and [the security assurance case](docs/security-assurance-case.md): reporting vulnerabilities, and what to expect
277
+ - [RELEASING.md](RELEASING.md): how releases are signed and how to verify them
278
+ - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
279
+
280
+ ## πŸ™ Credits & acknowledgements
281
+
282
+ This project is a **discovery layer** over third-party resources. All content, code
283
+ snippets, components, and mockups belong to their original creators. Please respect each
284
+ source's license before reusing anything.
285
+
286
+ - **[FreeFrontend](https://freefrontend.com/)** β€” curated frontend code snippets (per-item licenses, often MIT)
287
+ - **[shadcn/ui](https://ui.shadcn.com/)** by [@shadcn](https://github.com/shadcn) β€” MIT
288
+ - **[Magic UI](https://magicui.design/)** β€” MIT
289
+ - **[Aceternity UI](https://ui.aceternity.com/)** by [Manu Arora](https://twitter.com/mannupaaji)
290
+ - **[React Bits](https://reactbits.dev/)** by [David Haz](https://github.com/DavidHDev) β€” MIT
291
+ - **[Refero](https://refero.design/)** β€” design-system references extracted from public websites (data read from Refero's public pages; each referenced site owns its brand)
292
+ - **[three.js](https://threejs.org/)** by [mrdoob](https://github.com/mrdoob) & contributors β€” MIT
293
+ - **[drei](https://github.com/pmndrs/drei)** by [pmndrs](https://github.com/pmndrs) β€” MIT
294
+ - **[react-spring](https://github.com/pmndrs/react-spring)** by [pmndrs](https://github.com/pmndrs) β€” MIT
295
+ - **[zustand](https://github.com/pmndrs/zustand)** by [pmndrs](https://github.com/pmndrs) β€” MIT
296
+ - **[glyph](https://github.com/pmndrs/glyph)** by [pmndrs](https://github.com/pmndrs) β€” MIT
297
+ - **[postprocessing](https://github.com/pmndrs/postprocessing)** by [Raoul van RΓΌschen](https://github.com/vanruesc) β€” Zlib
298
+ - **[detect-gpu](https://github.com/pmndrs/detect-gpu)** by [pmndrs](https://github.com/pmndrs) β€” MIT
299
+ - **[ShaderGradient](https://github.com/ruucm/shadergradient)** by [ruucm](https://github.com/ruucm)
300
+ - **[liquid-logo](https://github.com/collidingScopes/liquid-logo)** by [collidingScopes](https://github.com/collidingScopes) β€” MIT
301
+ - **[liquid-glass-js](https://github.com/dashersw/liquid-glass-js)** by [Armagan Amcalar](https://github.com/dashersw) β€” MIT
302
+ - **[ThreeUI](https://github.com/MengTo/threeui)** by [Meng To](https://github.com/MengTo) β€” MIT
303
+ - **[img2threejs](https://github.com/img2threejs/img2threejs)** β€” Apache-2.0
304
+ - **[GSAP](https://github.com/greensock/gsap-skills)** by [GreenSock](https://github.com/greensock) β€” MIT
305
+ - **[VengeanceUI](https://github.com/Ashutoshx7/VengeanceUI)** by [Ashutosh](https://github.com/Ashutoshx7) β€” MIT
306
+ - **[Canvas UI](https://canvasui.dev/)** by [David Haz](https://github.com/DavidHDev) β€” MIT
307
+ - **[Fancy Components](https://fancycomponents.dev/)** by [Daniel Petho](https://github.com/danielpetho) β€” MIT
308
+ - **[Two.js](https://two.js.org/)** by [jonobr1](https://github.com/jonobr1) β€” MIT
309
+ - **[scrollama](https://github.com/russellsamora/scrollama)** by [Russell Samora](https://github.com/russellsamora) β€” MIT
310
+ - **[Watermelon UI](https://ui.watermelon.sh/)** β€” open-source React platform
311
+ - **[LS.GRAPHICS](https://www.ls.graphics/)** β€” free & premium design mockups
312
+
313
+ Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol) and
314
+ [cheerio](https://cheerio.js.org/).
315
+
316
+ ## πŸ“„ License
317
+
318
+ MIT Β© [notsointresting](https://github.com/notsointresting) β€” for the server code.
319
+ Third-party resources retrieved through it remain under their respective licenses.
320
+
321
+ ---
322
+
323
+ <sub>**Keywords:** MCP server Β· Model Context Protocol Β· AI coding agent Β· UI components Β·
324
+ React components Β· Tailwind CSS Β· shadcn/ui Β· Magic UI Β· Aceternity UI Β· React Bits Β·
325
+ FreeFrontend Β· design mockups Β· Figma Β· component library Β· copy-paste UI Β·
326
+ design tokens Β· DESIGN.md Β· design system Β· Refero Β· three.js Β· GLSL shaders Β· WebGL Β·
327
+ React Three Fiber Β· drei Β·
328
+ Claude Β· Cursor Β· frontend design Β· CSS snippets Β· Watermelon UI Β· LS.GRAPHICS.</sub>