aura-components-mcp 1.7.0 → 1.7.2
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/CHANGELOG.md +183 -0
- package/README.md +177 -51
- package/SETUP.md +15 -6
- package/THIRD_PARTY_NOTICES.md +33 -0
- package/dist/server.js +2195 -38
- package/package.json +5 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `aura-components-mcp`.
|
|
4
|
+
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
## [1.7.2] — 2026-10-15
|
|
8
|
+
|
|
9
|
+
35 tools: the six award-intelligence tools below join the 29 catalogue tools
|
|
10
|
+
in the published package (no new npm dependencies).
|
|
11
|
+
|
|
12
|
+
### Added — award-website intelligence (6 new MCP tools, 29 → 35)
|
|
13
|
+
|
|
14
|
+
- `aura_award_search` (`sites`/`categories`/`elements`/`motion`): ranked
|
|
15
|
+
Awwwards references with preview links and match reasons, real taxonomy
|
|
16
|
+
from the index/source (never invented counts), element-gallery search, and
|
|
17
|
+
stored-motion search with empty-corpus vs zero-match distinguished.
|
|
18
|
+
- `aura_award_inspect`
|
|
19
|
+
(`site_details`/`site_elements`/`element`/`compare_sites`): source-backed
|
|
20
|
+
design DNA (palette, technologies, elements, awards, score), element media
|
|
21
|
+
URLs with attribution, and 2–3-site comparisons that mark missing fields as
|
|
22
|
+
unknown evidence, never negative proof.
|
|
23
|
+
- `aura_design_blueprint`: goal + 2–5 refs → Markdown brief plus versioned
|
|
24
|
+
JSON (`spec.version: 1`), mapped to real free Aura components/systems
|
|
25
|
+
(free-only enforced, catalogue failures reported as unavailable evidence).
|
|
26
|
+
Original plans only — never copied third-party source.
|
|
27
|
+
- `aura_visual_audit` (`capture`/`structure`/`compare`): real browser
|
|
28
|
+
screenshots and live-DOM band maps when Chrome is present; labeled
|
|
29
|
+
`static-html` estimates otherwise; reference-vs-build mismatch reports
|
|
30
|
+
without pixel-perfect claims. Loopback only with `allowLocal: true`.
|
|
31
|
+
- `aura_motion_study` (`inspect`/`record`/`search`): live runtime scans
|
|
32
|
+
(libraries, easing vocab, scroll model, ScrollTrigger counts), bounded
|
|
33
|
+
frame studies (2–16 frames, ≤30s), `.webm` only when a system ffmpeg
|
|
34
|
+
exists — otherwise frame JPEGs plus an honest hint.
|
|
35
|
+
- `aura_award_index`
|
|
36
|
+
(`status`/`rebuild`/`resume`/`refresh`/`new_winners`/`watch_add`/`watch_list`/`watch_remove`):
|
|
37
|
+
file-based JSON index in `~/.aura-mcp/awards` (override
|
|
38
|
+
`AURA_AWARDS_DIR`): atomic writes, schema versioning, corrupt quarantine
|
|
39
|
+
+ recovery, stale-lock single-writer, resume checkpoints, bounded growth
|
|
40
|
+
(5000 sites/5000 elements/200 motion), winner baselines with seed-then-delta,
|
|
41
|
+
studio/tag/url watches. Polite ~1 req/s crawl, bounded `maxPages` per call
|
|
42
|
+
(default 5, max 20). Nothing crawls automatically on server startup.
|
|
43
|
+
|
|
44
|
+
### Fixed — field-report pass (12 issues, P0–P2)
|
|
45
|
+
|
|
46
|
+
- CDP attach uses `/json/list` page targets instead of browser-endpoint
|
|
47
|
+
`Target.createTarget` (which hangs on several headless builds); every setup
|
|
48
|
+
failure normalizes to `BROWSER_UNAVAILABLE` with per-operation fallback
|
|
49
|
+
guidance. Fixed a worse latent bug the tests caught: the CDP response
|
|
50
|
+
handler was never installed on setter-only transports, so *every* command
|
|
51
|
+
would have timed out even against a healthy browser.
|
|
52
|
+
- `aura_visual_audit` degrades any live-dom failure to labeled `static-html`
|
|
53
|
+
estimates (`fallbackFrom`/`fallbackWhy`); local builds audit directly from
|
|
54
|
+
`file://`/local paths with `allowLocal:true` (`source:local-file`);
|
|
55
|
+
`capture` of a file path errors with serve-it guidance.
|
|
56
|
+
- `aura_design_blueprint` queries the catalogue once per proposed section
|
|
57
|
+
(up to 12 slim matches, sections covered reported), always emits
|
|
58
|
+
`## Evidence gaps` (motion/structure/catalogue), and synthesizes goal-named
|
|
59
|
+
hexes as `proposed` palette tokens against observed luminance bands.
|
|
60
|
+
- Search relevance: design-vocabulary aliases (`glassy`→`glassmorphism`,
|
|
61
|
+
`3d`→`webgl`, …) + `theme:dark/light` tag boost; reasons name the query
|
|
62
|
+
word; zero-token rows still score 0 (honest-empty preserved).
|
|
63
|
+
- Catalogue matcher stems inflections (`glassy`→`glass`, plural→singular) in
|
|
64
|
+
both ranking and the refusal gate — `features glass bento` style queries
|
|
65
|
+
stop dead-ending while nonsense queries still refuse honestly.
|
|
66
|
+
- Empty Technologies sections backfill from listing tags, labeled
|
|
67
|
+
`technologiesInferred:true` with evidence note.
|
|
68
|
+
- `compare_sites` adds fuzzy element-keyword overlap, per-site luminance
|
|
69
|
+
bands, and `directionHints`.
|
|
70
|
+
- `categories` honors `limit`/`offset` (`filtersTotal` disclosed); every
|
|
71
|
+
search response carries `source` + `corpusNote` documenting the
|
|
72
|
+
seed-once-then-local rule.
|
|
73
|
+
|
|
74
|
+
### Polish — deep-module cleanup (skill 16-codebase-design)
|
|
75
|
+
|
|
76
|
+
- Removed dead surface: unused `awardNormalizeUrl`, `AWARD_ELEMENT_CATS`,
|
|
77
|
+
`AWARD_SCORE_VERSION` exports and seven unreferenced names from the
|
|
78
|
+
`tools.mjs` import lists.
|
|
79
|
+
- One section list: `AWARD_SECTIONS` is the single source both the blueprint
|
|
80
|
+
handler and builder share (was duplicated verbatim).
|
|
81
|
+
- Static-cue rendering moved next to its data shape (`awardStaticSummary`);
|
|
82
|
+
the handler just maps it. Tautological test assertion replaced with real
|
|
83
|
+
ones (no `total` key; `filtersTotal` consistency).
|
|
84
|
+
|
|
85
|
+
### Fixed — refusal gate, hex tokens, static motion, fallback evidence
|
|
86
|
+
|
|
87
|
+
- Refusal gate judges the global best row, not the first: theme-first
|
|
88
|
+
ordering re-ranks but can no longer let a 0-hit leader veto matching rows
|
|
89
|
+
below it; `fallback_score` refreshes to the best row. Empty means zero rows
|
|
90
|
+
matched, honestly.
|
|
91
|
+
- Scaffold discloses `system_note` when no design system matches instead of
|
|
92
|
+
shipping silent empty `tokens_css`.
|
|
93
|
+
- Hex codes (`#0a0a0b`, bare 6-hex with a digit) are excluded from catalogue
|
|
94
|
+
search tokens — titles never contain them, so they poisoned overlap counts
|
|
95
|
+
and emptied scaffolds. Real words (`red`, `face`, `decade`) are kept via a
|
|
96
|
+
digit rule. Goals with hexes now match instead of refusing.
|
|
97
|
+
- `site_details` returns browserless motion evidence: `motion_static`
|
|
98
|
+
(library scripts, keyframe/transition counts, scroll cues, canvases,
|
|
99
|
+
`prefers-reduced-motion` — all labeled static-markup, never runtime) plus
|
|
100
|
+
a runtime-visible `ideas_contract`. Blueprints cite static cues when no
|
|
101
|
+
study is recorded; confidence still requires recorded evidence.
|
|
102
|
+
- Blueprint matches record `matchEvidence.fallback` and the markdown marks
|
|
103
|
+
`(via fallback …)` rows; `search_all` fallback flags stay per-surface
|
|
104
|
+
(regression-locked). Technologies section titles tolerate `&`.
|
|
105
|
+
|
|
106
|
+
### Fixed — PostgREST escaping, ideas contract, evidence-scored confidence
|
|
107
|
+
|
|
108
|
+
- Goals containing `#`, `(`, `)`, `"`, `'`, `%`, `,` no longer crash
|
|
109
|
+
catalogue queries (PGRST100): `ilike` values percent-encode significant
|
|
110
|
+
chars while `*` wildcards survive, and `eq`/`in`/`neq` id/slug filters use
|
|
111
|
+
the same hardened encoder. Matching is preserved (server-side decode).
|
|
112
|
+
- `site_details ideas` contract: 0–6 by evidence, 1 on thin evidence is
|
|
113
|
+
valid, every entry `status:suggested` with an observed `basis`.
|
|
114
|
+
- Blueprint `confidence` is evidence-scored (usable refs + matched sections
|
|
115
|
+
+ recorded motion + measured structure + fully-parsed tech → low …
|
|
116
|
+
low-medium … medium … high, with `confidenceWhy`).
|
|
117
|
+
|
|
118
|
+
- `aura_design_blueprint` details (≤5 refs), all 9 section queries, `compare`
|
|
119
|
+
refs, and `includeStructure` targets now fetch concurrently (order
|
|
120
|
+
preserved; award client still spaces requests 1/s; `NOT_FOUND` still
|
|
121
|
+
throws). `search{full:true}` enriches max 5 hits with disclosure.
|
|
122
|
+
- Search hits carry tag-derived `try_for` cues; `site_details` carries
|
|
123
|
+
rule-based `ideas` (every one `status:suggested` + evidence `basis`).
|
|
124
|
+
- Blueprints return executable `next_calls` (`aura_get_component`,
|
|
125
|
+
`aura_scaffold_page`, `aura_motion_study`) built only from gathered
|
|
126
|
+
ids/urls, plus paste-ready `:root` tokens (`spec.tokens_css`).
|
|
127
|
+
|
|
128
|
+
- `aura_award_search{mode:elements}` no longer crashes in `dist`: the build
|
|
129
|
+
renamer rewrote `Array.sort(` into `.toolFn_sort(` (src tests stayed green,
|
|
130
|
+
only the bundle crashed). The renamer now excludes `.`-prefixed method
|
|
131
|
+
calls; a dist-level test (renamer assertion + bundled-server elements
|
|
132
|
+
smoke) guards it.
|
|
133
|
+
- Weak-consensus blueprints fill from human-grade editorial picks (<3
|
|
134
|
+
section matches → `editorial:true` matches + disclosure) instead of
|
|
135
|
+
shipping a 1-match brief.
|
|
136
|
+
- `compare_sites` canonicalizes technology families (`WebGL`≈`Three.js`,
|
|
137
|
+
`GSAP`≈`GreenSock`) for overlap + hints; raw per-site values stay verbatim.
|
|
138
|
+
- Browser-less environments get more than an error code: motion errors carry
|
|
139
|
+
a generic (explicitly unobserved) motion plan; dead-server + dead-browser
|
|
140
|
+
audits name both fixes (serve the build / pass the file); Chrome launches
|
|
141
|
+
with `--no-sandbox` for Windows admin shells.
|
|
142
|
+
|
|
143
|
+
### Zero-dependency behavior
|
|
144
|
+
|
|
145
|
+
- No new npm dependencies (`package.json` gains none). New modules use only
|
|
146
|
+
Node builtins via `process.getBuiltinModule` (works in source and in the
|
|
147
|
+
concatenated `dist` bundle, which stays `import`-free): `fetch`,
|
|
148
|
+
global `WebSocket` for CDP, `node:fs`/`path`/`os`/`child_process`.
|
|
149
|
+
- Optional system programs only: Chrome/Chromium (`AURA_CHROME_PATH`) for
|
|
150
|
+
live capture/structure/motion; ffmpeg (`AURA_FFMPEG_PATH`) for `.webm`
|
|
151
|
+
encoding. Core search/index/blueprint work without either; absence yields
|
|
152
|
+
`BROWSER_UNAVAILABLE` + setup guidance, never fake output.
|
|
153
|
+
|
|
154
|
+
### Security
|
|
155
|
+
|
|
156
|
+
- URL safety on every browser/capture path: http(s) only, no credentials,
|
|
157
|
+
private/cloud-metadata hosts blocked unless `allowLocal: true`, redirect
|
|
158
|
+
hosts revalidated against the award allowlist.
|
|
159
|
+
- Award fetching only touches `www.awwwards.com` / `assets.awwwards.com`;
|
|
160
|
+
markup-derived URLs are never followed as trusted.
|
|
161
|
+
- Bounded everything: 10s page timeout, 2MB response cap, one transient
|
|
162
|
+
retry (blocks never retried), CDP command timeouts, temp-profile cleanup,
|
|
163
|
+
child-process termination, no secrets in errors.
|
|
164
|
+
|
|
165
|
+
### Tests
|
|
166
|
+
|
|
167
|
+
- 66 new hermetic tests (no network, no browser): `test/awards.test.mjs`
|
|
168
|
+
(21: parsers, ranking, client errors), `test/awards-index.test.mjs` (15:
|
|
169
|
+
lifecycle, locks, corruption, winners, watches), `test/browser-cdp.test.mjs`
|
|
170
|
+
(14: CDP framing, bands, motion reduce, honest unavailability),
|
|
171
|
+
`test/award-tools.test.mjs` (16: 35-tool registry, JSON-RPC dispatch,
|
|
172
|
+
blueprint honesty, error mapping). Full suite: 188 tests.
|
|
173
|
+
- `scripts/verify.mjs`: 38 live checks + 6 award validation checks (43 total).
|
|
174
|
+
|
|
175
|
+
## [1.7.1] — hardening release (published)
|
|
176
|
+
|
|
177
|
+
Bug-fix release, no new tools. Central free-only enforcement, theme-isolated
|
|
178
|
+
search cache, bundle-8 end-to-end, disclosed counts, malformed-row gate,
|
|
179
|
+
no-retry 4xx, Node `>=22` with CI matrix 22.x/24.x. See README for details.
|
|
180
|
+
|
|
181
|
+
## [1.7.0] — 29 tools (published)
|
|
182
|
+
|
|
183
|
+
Inspo bridge, docs helpers, `aura_icon`, `aura_version`, `aura_prompt`.
|
package/README.md
CHANGED
|
@@ -1,42 +1,63 @@
|
|
|
1
|
-
<h1 align="center">
|
|
1
|
+
<h1 align="center">Aura Components MCP</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center"><sub>FREE MCP SERVER · STDIO · ZERO DEPS · MIT</sub></p>
|
|
2
4
|
|
|
3
5
|
<p align="center">
|
|
4
6
|
<a href="https://www.npmjs.com/package/aura-components-mcp"><img src="https://img.shields.io/npm/v/aura-components-mcp" alt="npm version"></a>
|
|
5
7
|
<a href="https://www.npmjs.com/package/aura-components-mcp"><img src="https://img.shields.io/npm/dm/aura-components-mcp" alt="npm downloads"></a>
|
|
6
|
-
<a href="
|
|
7
|
-
<a href="
|
|
8
|
-
<a href="
|
|
8
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license: MIT"></a>
|
|
9
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/package.json"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen" alt="node >= 22"></a>
|
|
10
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/dist/server.js"><img src="https://img.shields.io/badge/MCP-stdio-blue" alt="MCP stdio"></a>
|
|
11
|
+
<a href="#the-35-tools"><img src="https://img.shields.io/badge/tools-35-blueviolet" alt="35 tools"></a>
|
|
12
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/actions"><img src="https://github.com/swastiksingh-dev/Aura-Components-MCP/actions/workflows/verify.yml/badge.svg" alt="verify CI"></a>
|
|
13
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP"><img src="https://img.shields.io/github/stars/swastiksingh-dev/Aura-Components-MCP?style=social" alt="GitHub stars"></a>
|
|
9
14
|
</p>
|
|
10
15
|
|
|
11
16
|
<p align="center"><i>Every free thing on Aura, one call away — no account, no key, no browser.</i></p>
|
|
12
17
|
|
|
13
18
|
<p align="center">
|
|
14
|
-
<
|
|
19
|
+
<a href="#install"><b>Install</b></a> ·
|
|
20
|
+
<a href="#the-35-tools"><b>Tools</b></a> ·
|
|
21
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md"><b>Client setup</b></a> ·
|
|
22
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/CHANGELOG.md"><b>Changelog</b></a> ·
|
|
23
|
+
<a href="#credits"><b>Credits</b></a>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
<p align="center">
|
|
27
|
+
<a href="https://raw.githubusercontent.com/swastiksingh-dev/Aura-Components-MCP/main/assets/heart-demo.mp4"><b>▲ WATCH THE 10-SECOND TOUR (MP4) ▲</b></a>
|
|
15
28
|
</p>
|
|
16
29
|
|
|
17
30
|
> I got tired of opening twenty Aura tabs every time I started a landing page. So I built the MCP server I wanted: every free thing on aura.build, one stdio call away, no account, no key, no browser.
|
|
18
31
|
|
|
19
32
|
<p align="center">
|
|
20
33
|
<b>2,495</b> free components · <b>192</b> skills · <b>30,688</b> assets · <b>725</b> design systems<br>
|
|
21
|
-
<b>
|
|
34
|
+
<b>35</b> tools · <b>0</b> dependencies · <b>226</b> hermetic tests + <b>45</b> live checks green · version-checked hourly against npm
|
|
22
35
|
</p>
|
|
23
36
|
|
|
24
|
-
---
|
|
25
|
-
|
|
37
|
+
---
|
|
38
|
+
## Contents
|
|
39
|
+
|
|
26
40
|
|
|
27
41
|
- [Why not the official MCP](#why-i-built-this-instead-of-using-the-official-mcp)
|
|
28
42
|
- [What is inside](#what-is-inside)
|
|
29
43
|
- [Install](#install)
|
|
30
44
|
- [Demo](#demo)
|
|
31
|
-
- [The
|
|
45
|
+
- [The 35 tools](#the-35-tools)
|
|
32
46
|
- [Fallback rules](#fallback-rules-read-this-once)
|
|
33
|
-
- [Prompt for AI agents](
|
|
47
|
+
- [Prompt for AI agents](#prompt-for-ai-agents-start-here)
|
|
34
48
|
- [Free only, no login](#free-only-no-login)
|
|
35
49
|
- [Develop](#develop)
|
|
36
50
|
- [Credits](#credits)
|
|
37
51
|
|
|
52
|
+
> **v1.7.1** — bug-fix release, no new tools. Central free-only enforcement: Pro components/assets by direct ID are now refused (`-32602`, fail-closed on ambiguous entitlement) instead of returned in full — search, install, bundle, scaffold, and related all inherit it. Search cache isolates explicit `theme` (dark/light no longer share entries). Bundles honor all 8 refs end-to-end with `dropped_refs` disclosure. New `min_views_filtered_out` count (`total` stays upstream). Full icon outages surface as upstream errors, not misses. Upstream hardening: malformed rows disclosed via `malformed_dropped` (single fetch fails loud), non-429 4xx never retried. Node floor raised to maintained releases (engines `>=22`, CI matrix 22.x/24.x). Dead code removed, scaffold merge extracted, verify extended.
|
|
53
|
+
|
|
54
|
+
<details>
|
|
55
|
+
<summary><b>v1.7.0 changelog (29 tools)</b> — click to expand</summary>
|
|
56
|
+
|
|
38
57
|
> **v1.7.0** — 29 tools: 5 pure `aura_inspo_*` mappers (recommend/components/reference/system/compare) bridge Inspo evidence to Aura calls with zero extra deps — strict macro gate (`need_macro`), palette priority brand > Inspo > Aura, enforced tokens-first, mandated image srcset plan, fast preview-URL look gate — plus 2 pure `aura_docs_*` helpers (plan/check) wiring Context7 fresh docs for tailwind/gsap/lenis/iconify, with `docs_stamp` on every install/scaffold and a look-preserving conflict rule (fresh API wins, look stays identical) — plus live `aura_icon` (Font Awesome Free + HackerNoon pixel SVGs, auto-fallback, CC BY 4.0 credit always) — plus `aura_version` (hourly npm check, prefer-latest notice, verdict inside every `aura_status`). `aura_prompt` now asks 6 questions (+macrostructure, +vibe) and leads Pass 2 with `inspo.recommend`. `aura_scaffold_page` refuses explicit Pro ids (`pro_filtered_out`). Build hardened for CRLF checkouts.
|
|
39
58
|
|
|
59
|
+
</details>
|
|
60
|
+
|
|
40
61
|
<details>
|
|
41
62
|
<summary><b>v1.6.3 changelog (20 tools)</b> — click to expand</summary>
|
|
42
63
|
|
|
@@ -48,8 +69,9 @@ Point any MCP client at `dist/server.js` and your agent can search 2,495 free co
|
|
|
48
69
|
|
|
49
70
|
Built by [swastiksingh-dev](https://github.com/swastiksingh-dev). Catalogue content belongs to Aura (aura.build, by Meng To / DesignCode). This project is not affiliated with Aura.
|
|
50
71
|
|
|
51
|
-
---
|
|
52
|
-
|
|
72
|
+
---
|
|
73
|
+
## Why I built this instead of using the official MCP
|
|
74
|
+
|
|
53
75
|
|
|
54
76
|
Aura already ships an official MCP at `https://mcp.aura.build/mcp`. It is good at what it does: your Canvases, your projects, publishing, all behind OAuth. This server does the other half. It covers the public catalogue, and it skips the parts that slow an agent down: no OAuth dance, no account, no per-project scopes. A few things the official one does not do:
|
|
55
77
|
|
|
@@ -59,24 +81,27 @@ Aura already ships an official MCP at `https://mcp.aura.build/mcp`. It is good a
|
|
|
59
81
|
- `aura_recommend` builds a starter kit across all four surfaces in one parallel call.
|
|
60
82
|
- Everything defaults to free. Pro rows never sneak into results.
|
|
61
83
|
|
|
62
|
-
---
|
|
63
|
-
|
|
84
|
+
---
|
|
85
|
+
## What is inside
|
|
86
|
+
|
|
64
87
|
|
|
65
88
|
- 2,495 free components with HTML/Tailwind source, preview images, tags, and author credit
|
|
66
89
|
- 192 agent skills with full SKILL.md bodies (GSAP, Tailwind v4, Anime.js, copywriting, and more)
|
|
67
90
|
- 30,688 images and clips with direct CDN URLs at multiple widths
|
|
68
91
|
- 725 DESIGN.md systems with tokens, type rules, layout notes, and preview HTML
|
|
69
|
-
-
|
|
92
|
+
- 35 tools over stdio (29 catalogue + 6 award-intelligence), one bundle, 60-second LRU cache (300 keys) with request coalescing, author memo, category-count cache, retries with jittered backoff
|
|
93
|
+
- Award corpus: file-based JSON index (`~/.aura-mcp/awards`) with atomic writes, resume checkpoints, winner baselines, watches; polite ~1 req/s Awwwards fetching with distinct 404/403+429/5xx/timeout handling
|
|
70
94
|
- Honest search: AND-phrase misses retry as OR-tokens (2 passes) plus a labeled safety net — but zero title-overlap fallbacks are refused as `total:0` + `no_match` + `suggested_queries` instead of masking with popular rows; `exact_match:true` skips fallbacks entirely
|
|
71
95
|
- Agent accelerators: `aura_prompt` (2-pass prompt with user confirmation), `aura_bulk_fetch`/`aura_bundle` (8 details/turn, any of 3 kinds), `aura_scaffold_page` (tokens + system + markup in dependency order), `aura_related`, `aura_install_asset` (license-aware)
|
|
72
96
|
- Faceted lists: every component carries `facets { theme, weight, code_chars, needsTailwind, needsIcons, fonts }`; filter `theme: dark|light` server-side
|
|
73
97
|
|
|
74
98
|
Start with `aura_status`, then `aura_search_all`. That order matters: status confirms the catalogue is reachable, search_all shows which surface has the best match before you spend calls on details.
|
|
75
99
|
|
|
76
|
-
---
|
|
77
|
-
|
|
100
|
+
---
|
|
101
|
+
## Install
|
|
102
|
+
|
|
78
103
|
|
|
79
|
-
Needs Node
|
|
104
|
+
Needs Node 22 or newer. No other dependency. Pick one:
|
|
80
105
|
|
|
81
106
|
```bash
|
|
82
107
|
# Option A — from source (GitHub)
|
|
@@ -98,7 +123,15 @@ aura-components-mcp
|
|
|
98
123
|
npx -y aura-components-mcp@latest
|
|
99
124
|
```
|
|
100
125
|
|
|
101
|
-
Then register it in your client. Full per-client steps live in [SETUP.md](
|
|
126
|
+
Then register it in your client. Full per-client steps live in [SETUP.md](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md) — Claude Code, Cursor, Codex, Windsurf, OpenCode, Cline, Roo Code, DeepSeek Harness, generic stdio.
|
|
127
|
+
|
|
128
|
+
<p align="center">
|
|
129
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md#claude-code"><img src="https://img.shields.io/badge/Claude_Code-setup-black" alt="Claude Code setup"></a>
|
|
130
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md#cursor"><img src="https://img.shields.io/badge/Cursor-setup-black" alt="Cursor setup"></a>
|
|
131
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md#codex"><img src="https://img.shields.io/badge/Codex-setup-black" alt="Codex setup"></a>
|
|
132
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md#opencode"><img src="https://img.shields.io/badge/OpenCode-setup-black" alt="OpenCode setup"></a>
|
|
133
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md#any-other-mcp-client"><img src="https://img.shields.io/badge/any_stdio_client-setup-black" alt="Any stdio client setup"></a>
|
|
134
|
+
</p>
|
|
102
135
|
|
|
103
136
|
```bash
|
|
104
137
|
# Claude Code
|
|
@@ -115,21 +148,25 @@ claude mcp add aura-components -- node ./dist/server.js
|
|
|
115
148
|
{ "$schema": "https://opencode.ai/config.json", "mcp": { "aura-components": { "type": "local", "command": ["node", "./dist/server.js"], "enabled": true } } }
|
|
116
149
|
```
|
|
117
150
|
|
|
118
|
-
---
|
|
119
|
-
|
|
151
|
+
---
|
|
152
|
+
## Demo
|
|
153
|
+
|
|
120
154
|
|
|
121
155
|
<p align="center">
|
|
122
|
-
<a href="https://raw.githubusercontent.com/swastiksingh-dev/Aura-Components-MCP/main/assets/heart-demo.mp4"><
|
|
123
|
-
<br><em>
|
|
156
|
+
<a href="https://raw.githubusercontent.com/swastiksingh-dev/Aura-Components-MCP/main/assets/heart-demo.mp4"><b>▲ CLICK TO WATCH THE 10-SECOND FLOW TOUR (MP4) ▲</b></a>
|
|
157
|
+
<br><em>Same file as <a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/assets/heart-demo.mp4">assets/heart-demo.mp4</a></em>
|
|
124
158
|
</p>
|
|
125
159
|
|
|
126
160
|
*`aura_prompt` turns one sentence into a confirmed prompt, `aura_recommend` turns it into a starter kit with links. Full clip in [`assets/`](assets/).*
|
|
127
161
|
|
|
128
|
-
---
|
|
129
|
-
|
|
162
|
+
---
|
|
163
|
+
## The 35 tools
|
|
164
|
+
|
|
130
165
|
|
|
131
166
|
Start with `aura_status`, then `aura_search_all`. That order matters: status confirms the catalogue is reachable, search_all shows which surface has the best match before you spend calls on details.
|
|
132
167
|
|
|
168
|
+
> **v1.7.2** — 35 tools: the six award-intelligence tools (`aura_award_search`, `aura_award_inspect`, `aura_design_blueprint`, `aura_visual_audit`, `aura_motion_study`, `aura_award_index`) join the 29 catalogue tools — ranked Awwwards references with `try_for` cues, design DNA with suggested `ideas`, blueprints with paste-ready tokens + executable `next_calls`, graceful browserless fallbacks, and a persistent local corpus. See [CHANGELOG.md](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/CHANGELOG.md).
|
|
169
|
+
|
|
133
170
|
### Find
|
|
134
171
|
|
|
135
172
|
| Tool | What it returns |
|
|
@@ -161,7 +198,7 @@ Start with `aura_status`, then `aura_search_all`. That order matters: status con
|
|
|
161
198
|
| `aura_install_skill` | Where to save SKILL.md so the agent can load it, plus upstream link. |
|
|
162
199
|
| `aura_install_asset` | Legal drop-in: download + preview URLs, license (all-rights-reserved per [Aura Terms §4](https://www.aura.build/terms)), file path. |
|
|
163
200
|
| `aura_use_design_system` | Token starter CSS plus the order to apply things in. |
|
|
164
|
-
| `aura_scaffold_page` | One-turn page build: tokens.css + system preview + markup in order, combined deps + files. `components: ["732","1364"]` or `[{id:"732"}]`. |
|
|
201
|
+
| `aura_scaffold_page` | One-turn page build: tokens.css + system preview + markup in order, combined deps + files. `components: ["732","1364"]` or `[{id:"732"}]`. Goals with `#hex`/punctuation are escaped safely; an unmatched system is disclosed via `system_note` instead of silent empty CSS. |
|
|
165
202
|
| `aura_prompt` | Need-based prompt in 2 passes: draft + 6 questions (theme, sections, system, assets, macrostructure, vibe), then copy-paste final. Confirm with user first. Pass 2 leads with `inspo.recommend` + `aura_inspo_recommend`. |
|
|
166
203
|
|
|
167
204
|
### Bridge (Inspo · fresh docs · icons)
|
|
@@ -179,20 +216,72 @@ Start with `aura_status`, then `aura_search_all`. That order matters: status con
|
|
|
179
216
|
| `aura_version` | Running vs npm-published version (live, hourly cache). `update_available` + prefer-latest notice. `aura_status` carries the verdict on every call. |
|
|
180
217
|
| `aura_version` | Running vs npm-published version (live, hourly cache). `update_available` + prefer-latest notice. `aura_status` carries the verdict on every call. |
|
|
181
218
|
|
|
219
|
+
### Award intelligence (new in v1.7.2 — 6 tools, zero npm deps)
|
|
220
|
+
|
|
221
|
+
Search → inspect → blueprint → audit → motion. Core search/index work with no
|
|
222
|
+
browser; live capture needs Chrome (see setup below).
|
|
223
|
+
|
|
224
|
+
| Tool | Modes | What it returns |
|
|
225
|
+
| --- | --- | --- |
|
|
226
|
+
| `aura_award_search` | `sites` / `categories` / `elements` / `motion` | Ranked Awwwards refs (title, source URL, tags, awards, studio, preview link, relevance + reasons). Multiword queries get alias expansion (`glassy`→`glassmorphism`, `3d`→`webgl`) plus a `theme:dark/light` boost — reasons always name your word, never the alias. `categories` returns real taxonomy from the index/source, filters paged by `limit`/`offset` (`filtersTotal` tells the full size). `motion` searches stored studies (`emptyCorpus:true` when none recorded yet). Every response carries `source` + `corpusNote`: first run on an empty index seeds from one polite live fetch (`source:live`); after that everything ranks from the local index until you `rebuild`/`refresh`. Empty results carry `suggestions`; upstream failures carry `liveError` instead of fake hits. |
|
|
227
|
+
| `aura_award_inspect` | `site_details` / `site_elements` / `element` / `compare_sites` | Design DNA (palette, tech, elements, awards, score). Empty Technologies sections are backfilled from listing tags and labeled `technologiesInferred:true` (never presented as parsed). Rule-based `ideas` (0–6 by evidence, always `status:suggested` + observed `basis`, contract in `ideas_contract`). Browserless motion evidence in `motion_static` (scripts, keyframes, scroll cues — labeled static-markup, never runtime). Element media URLs with attribution. 2–3-site comparisons with shared signals, fuzzy element-keyword overlap, tech-family canonicalization, luminance-band agreement, `directionHints`, and gaps (missing = unknown, never negative proof). |
|
|
228
|
+
| `aura_design_blueprint` | goal + 2–5 refs | Markdown brief + versioned JSON (`spec.version: 1`): shared patterns, outliers, palette evidence, one catalogue query PER proposed section (tokens/hero/proof/…/footer, capped at 12 matches — slim rows, not full code dumps), real free Aura matches (IDs + page URLs, free-only enforced, fallback-sourced rows marked `(via fallback …)` with `matchEvidence`), requested hexes from your goal synthesized as `proposed` tokens against the refs' observed bands, executable `next_calls` (get/scaffold/motion with real gathered IDs), evidence-scored `confidence` + `confidenceWhy`, sections, motion/a11y/performance guidance, checklist, and an always-present Evidence gaps section. Catalogue failures surface as unavailable evidence. |
|
|
229
|
+
| `aura_visual_audit` | `capture` / `structure` / `compare` | Real browser screenshots + live-DOM band maps when Chrome works (`source: live-browser`, attached via `/json/list` page targets). Any live-dom failure degrades to labeled `static-html` estimates (`fallbackFrom` + `fallbackWhy` disclosed) instead of erroring. Local builds: pass a `file://` path or local file with `allowLocal:true` for direct file estimates (`source: local-file`); screenshots still need a served `http://127.0.0.1` URL. `compare` reports section-count/order, height, palette mismatches + manual-judgment items, with an `estimateNote` when offsets aren't measured. |
|
|
230
|
+
| `aura_motion_study` | `inspect` / `record` / `search` | Live runtime scans (libs, easing vocab, scroll model, ScrollTrigger counts — only what was observed), bounded frame studies (2–16 frames, ≤30s), `.webm` only when system ffmpeg exists. Stored studies are searchable by library/easing/scroll. |
|
|
231
|
+
| `aura_award_index` | `status` / `rebuild` / `resume` / `refresh` / `new_winners` / `watch_add` / `watch_list` / `watch_remove` | Persistent corpus in `~/.aura-mcp/awards` (`AURA_AWARDS_DIR` overrides): counts/freshness/lock, polite ~1 req/s crawl bounded by `maxPages` (default 5, max 20 — `resume` continues), winner baseline-then-delta, studio/tag/url watches. Never auto-crawls on startup. |
|
|
232
|
+
|
|
233
|
+
**Browser setup (optional, capture/motion only):** install Chrome/Chromium, or set
|
|
234
|
+
`AURA_CHROME_PATH` to its executable. For `.webm` motion video, also install
|
|
235
|
+
ffmpeg or set `AURA_FFMPEG_PATH`. Without them the six tools still search,
|
|
236
|
+
inspect (via polite HTML fetch), blueprint, index, and report
|
|
237
|
+
`BROWSER_UNAVAILABLE` with setup guidance where a live browser is required.
|
|
238
|
+
CDP setup failures (refused socket, hung attach) normalize to the same
|
|
239
|
+
`BROWSER_UNAVAILABLE` code with a per-operation fallback hint — never a raw
|
|
240
|
+
CDP timeout.
|
|
241
|
+
|
|
242
|
+
```mermaid
|
|
243
|
+
%%{init: {'theme': 'base', 'themeVariables': {'fontFamily': 'Inter, system-ui, -apple-system, sans-serif', 'fontSize': '15px', 'lineColor': '#ff2a2a', 'edgeLabelBackground': '#0a0a0b'}}}%%
|
|
244
|
+
flowchart LR
|
|
245
|
+
S["🔍 aura_award_search<br/>ranked refs + try_for"] --> I["🧬 aura_award_inspect<br/>design DNA + ideas"]
|
|
246
|
+
I --> B["📐 aura_design_blueprint<br/>brief + tokens + next_calls"]
|
|
247
|
+
B --> A["📸 aura_visual_audit<br/>capture / bands / compare"]
|
|
248
|
+
A --> M["🎞️ aura_motion_study<br/>scans + studies"]
|
|
249
|
+
B -.-> X["🗂️ aura_award_index<br/>corpus · winners · watches"]
|
|
250
|
+
X -.-> S
|
|
251
|
+
classDef core fill:#111318,stroke:#8b949e,color:#f5f5f5,stroke-width:2px;
|
|
252
|
+
classDef hot fill:#1c0606,stroke:#ff2a2a,color:#ffffff,stroke-width:2px;
|
|
253
|
+
classDef idx fill:#161a08,stroke:#d4a017,color:#ffffff,stroke-width:2px;
|
|
254
|
+
class S,I,A,M core;
|
|
255
|
+
class B hot;
|
|
256
|
+
class X idx;
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
> The 6-call award loop (fast: details + section queries run concurrently):
|
|
260
|
+
> `search → inspect → blueprint → follow its next_calls → audit → motion`
|
|
261
|
+
|
|
262
|
+
**Two award servers?** If you also run `awwwards-mcp`, keep both or pick one:
|
|
263
|
+
`aura_award_*` is canonical here — it's the only path that maps references to
|
|
264
|
+
Aura's free catalogue inside `aura_design_blueprint`. The standalone server
|
|
265
|
+
can't do that mapping.
|
|
266
|
+
|
|
182
267
|
Every row carries `page_url` (open it to see the design) and `author` where Aura credits one.
|
|
183
268
|
|
|
184
|
-
---
|
|
185
|
-
|
|
269
|
+
---
|
|
270
|
+
## Fallback rules (read this once)
|
|
271
|
+
|
|
186
272
|
|
|
187
273
|
- **Per surface, not global.** `aura_search_all` fans out to four independent pipelines (phrase → OR-tokens → safety net → kind-aware refusal). Mixed outcomes are normal and correct: skills may return `fallback:or-tokens:...` while components return `total:0, no_match:true`. Read `isFallback` / `no_match` on each surface — never assume one flag covers all four.
|
|
188
274
|
- **Recommend fills the kit.** If components come back `no_match`, `aura_recommend` auto-retries once with `suggested_queries[0]` (`retried:true, retried_from:<query>`), then falls back to human-grade editorial picks (`editorial_fallback:true`). The starter kit is never left empty on a text goal.
|
|
189
275
|
- **Big code in one call.** Search rows are slim excerpts by design. Skip the 3-chunk manual concat: `aura_get_component {id, full:true}` and `aura_scaffold_page {goal, full:true}` return complete bodies (33,897-char component verified in one call). Default stays chunked to protect context.
|
|
190
276
|
- **Counts are live upstream.** `aura_status` counts mirror the Aura catalogue right now; `freshness` shows max `updated_at` per surface. Counts only grow when Aura publishes — a freshness bump with flat counts means metadata moved, not new components.
|
|
277
|
+
- **`total` means upstream matches** (for limit/offset paging), not post-filter rows. Local drops are disclosed, never silent: `min_views_filtered_out`, `negative_theme_filtered_out`, `deduped`, bundle `dropped_refs`.
|
|
278
|
+
- **Award errors are labeled, never masked.** `NOT_FOUND` (−32004) = unknown slug; `UPSTREAM_ERROR` (−32000) = blocked/failing source (blocks are never retried); `BROWSER_UNAVAILABLE` = install Chrome; `INDEX_BUSY` = crawl already running (`resume` continues); `INDEX_CORRUPT` = file quarantined + rebuilt empty. Empty award results carry `suggestions` or `emptyCorpus:true`; failures carry `liveError`. Refusal means zero rows matched (best-row gate, theme-first ordering kept). Site `ideas` run 0–6 by evidence (1 on thin evidence is valid) and are always `status:suggested` with an observed `basis`. Blueprint `confidence` is evidence-scored (refs + matched sections + recorded motion + measured structure + fully-parsed tech → low…high, with `confidenceWhy`). Known limits: taxonomy/element depth follows the polite crawl (rebuild `maxPages`, `resume` for more); palettes come only from observable page evidence; tech labels are inferences with triggers shown; `static-html` bands have no measured offsets.
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
## Prompt for AI agents (start here)
|
|
191
282
|
|
|
192
|
-
---
|
|
193
|
-
|
|
194
283
|
|
|
195
|
-
> The fastest way to a shippable page. Two passes, one confirmation.
|
|
284
|
+
> ✨ The fastest way to a shippable page. Two passes, one confirmation.
|
|
196
285
|
|
|
197
286
|
```text
|
|
198
287
|
Pass 1 — agent calls:
|
|
@@ -226,8 +315,9 @@ Sources: [tips-for-prompting](https://www.aura.build/learn/tips-for-prompting),
|
|
|
226
315
|
[introduction](https://www.aura.build/learn/introduction),
|
|
227
316
|
[design-systems](https://www.aura.build/design-systems).
|
|
228
317
|
|
|
229
|
-
---
|
|
230
|
-
|
|
318
|
+
---
|
|
319
|
+
## How I use it
|
|
320
|
+
|
|
231
321
|
|
|
232
322
|
New landing page, dark cinematic portfolio, SaaS pricing section. The shape is the same each time:
|
|
233
323
|
|
|
@@ -237,12 +327,13 @@ New landing page, dark cinematic portfolio, SaaS pricing section. The shape is t
|
|
|
237
327
|
4. `aura_install_component` on the winner. Follow the file map.
|
|
238
328
|
5. `aura_use_design_system` once, before any markup, so tokens land first.
|
|
239
329
|
|
|
240
|
-
Prompts that work well are in [SETUP.md](
|
|
330
|
+
Prompts that work well are in [SETUP.md](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md#prompts-that-work).
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
## Free only, no login
|
|
241
334
|
|
|
242
|
-
---
|
|
243
|
-
|
|
244
335
|
|
|
245
|
-
There is no auth in this server. No OAuth, no API key to paste, no account to create. Reads go to the same public catalogue endpoints the Aura website uses. The `premium` flag stays on every component row, free-only is the default, and
|
|
336
|
+
There is no auth in this server. No OAuth, no API key to paste, no account to create. Reads go to the same public catalogue endpoints the Aura website uses. The `premium` flag stays on every component row, free-only is the default, and Pro rows are refused everywhere — search filters them, and direct ID lookup, install, bundle, and scaffold refuse them (`-32602`, fail-closed) instead of guessing. If Aura rotates its public key, set `AURA_SUPABASE_ANON_KEY` and rebuild; nothing else changes.
|
|
246
337
|
|
|
247
338
|
Optional tuning (all with defaults):
|
|
248
339
|
|
|
@@ -260,36 +351,68 @@ Optional tuning (all with defaults):
|
|
|
260
351
|
|
|
261
352
|
</details>
|
|
262
353
|
|
|
263
|
-
---
|
|
264
|
-
|
|
354
|
+
---
|
|
355
|
+
## Develop
|
|
356
|
+
|
|
265
357
|
|
|
266
358
|
```bash
|
|
267
|
-
npm test # hermetic tests, no network
|
|
268
|
-
npm run verify #
|
|
359
|
+
npm test # hermetic tests, no network (226 tests)
|
|
360
|
+
npm run verify # 45 live checks against the real catalogue + award validation
|
|
269
361
|
npm run build # rebundle src/*.mjs into dist/server.js
|
|
270
362
|
```
|
|
271
363
|
|
|
272
|
-
Layout: `src/config.mjs` holds env parsing. `src/http.mjs` hides timeouts and retries behind an injectable fetch. `src/catalog.mjs` is the deep module (queries, cache, shaping, counts). `src/icons.mjs` fetches free icons (FA + pixel lib) with its own 24h cache. `src/guide.mjs` turns rows into install plans plus pure mappers (`buildPrompt`, `combineScaffold`, `buildInspo*`, `buildDocs*` — same seam for tools + tests + docs). `src/tools.mjs` validates args. `src/protocol.mjs` speaks JSON-RPC. `src/server.mjs` only wires stdio.
|
|
364
|
+
Layout: `src/config.mjs` holds env parsing. `src/http.mjs` hides timeouts and retries behind an injectable fetch. `src/catalog.mjs` is the deep module (queries, cache, shaping, counts). `src/icons.mjs` fetches free icons (FA + pixel lib) with its own 24h cache. `src/guide.mjs` turns rows into install plans plus pure mappers (`buildPrompt`, `combineScaffold`, `buildInspo*`, `buildDocs*` — same seam for tools + tests + docs). `src/awards.mjs` parses/ranks Awwwards references (pure) plus a polite fetch client. `src/awards-index.mjs` persists the award corpus (atomic JSON, locks, checkpoints, winners, watches). `src/browser-cdp.mjs` drives optional Chrome over native CDP (screenshots, band scans, motion) with honest unavailability. `src/tools.mjs` validates args. `src/protocol.mjs` speaks JSON-RPC. `src/server.mjs` only wires stdio.
|
|
273
365
|
|
|
274
|
-
---
|
|
275
|
-
|
|
366
|
+
---
|
|
367
|
+
## Share
|
|
276
368
|
|
|
277
|
-
|
|
369
|
+
|
|
370
|
+
Star it if it saved you a tab or twenty: [github.com/swastiksingh-dev/Aura-Components-MCP](https://github.com/swastiksingh-dev/Aura-Components-MCP). Reposits welcome — see [DIRECTION.md](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/DIRECTION.md) for where this is headed.
|
|
278
371
|
|
|
279
372
|
[](https://star-history.com/#swastiksingh-dev/Aura-Components-MCP&Date)
|
|
280
373
|
|
|
281
374
|
```text
|
|
282
|
-
built a free design MCP on aura.build: 2495 components, 192 skills, 30k assets,
|
|
375
|
+
built a free design MCP on aura.build: 2495 components, 192 skills, 30k assets, 35 tools. no login. resources are @MengTo's
|
|
283
376
|
|
|
284
377
|
npx -y aura-components-mcp@latest
|
|
285
378
|
https://github.com/swastiksingh-dev/Aura-Components-MCP
|
|
286
379
|
```
|
|
287
380
|
|
|
288
|
-
---
|
|
289
|
-
|
|
381
|
+
---
|
|
382
|
+
## Credits
|
|
383
|
+
|
|
384
|
+
|
|
385
|
+
<p align="center"><sub>Standing on the shoulders of open work — every source below is linked, licensed, and honored in the code.</sub></p>
|
|
386
|
+
|
|
387
|
+
<table align="center">
|
|
388
|
+
<tr>
|
|
389
|
+
<td align="center" width="200">
|
|
390
|
+
<a href="https://github.com/swastiksingh-dev"><img src="https://github.com/swastiksingh-dev.png?size=100" width="80" alt="swastiksingh-dev"><br><b>swastiksingh-dev</b></a><br><sub>Built this server · MIT</sub>
|
|
391
|
+
</td>
|
|
392
|
+
<td align="center" width="200">
|
|
393
|
+
<a href="https://www.aura.build"><img src="https://github.com/MengTo.png?size=100" width="80" alt="Meng To"><br><b>Meng To / Aura</b></a><br><sub>The entire catalogue</sub>
|
|
394
|
+
</td>
|
|
395
|
+
<td align="center" width="200">
|
|
396
|
+
<a href="https://github.com/INSANE0777/Awwwards-mcp"><img src="https://github.com/INSANE0777.png?size=100" width="80" alt="INSANE0777"><br><b>INSANE0777</b></a><br><sub><a href="https://github.com/INSANE0777/Awwwards-mcp">awwwards-mcp</a> · award-layer inspiration · MIT</sub>
|
|
397
|
+
</td>
|
|
398
|
+
</tr>
|
|
399
|
+
</table>
|
|
290
400
|
|
|
291
401
|
Server code by [swastiksingh-dev](https://github.com/swastiksingh-dev), MIT. Free to fork, use, and sell with. If you fork this, keep the credit line and point people at the original repo.
|
|
292
402
|
|
|
403
|
+
### Contributors
|
|
404
|
+
|
|
405
|
+
<p align="center">
|
|
406
|
+
<a href="https://github.com/swastiksingh-dev"><img src="https://github.com/swastiksingh-dev.png?size=80" width="60" alt="swastiksingh-dev"></a>
|
|
407
|
+
<a href="https://github.com/INSANE0777"><img src="https://github.com/INSANE0777.png?size=80" width="60" alt="INSANE0777"></a>
|
|
408
|
+
<a href="https://github.com/MengTo"><img src="https://github.com/MengTo.png?size=80" width="60" alt="Meng To"></a>
|
|
409
|
+
<br><sub><b><a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/graphs/contributors?from=7%2F11%2F2026">swastiksingh-dev</a></b> — builder & maintainer · <b><a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/graphs/contributors?from=7%2F11%2F2026">INSANE0777</a></b> — awwwards-mcp inspiration · <b><a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/graphs/contributors?from=7%2F11%2F2026">MengTo</a></b> — the Aura catalogue</sub>
|
|
410
|
+
</p>
|
|
411
|
+
|
|
412
|
+
<p align="center">
|
|
413
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/graphs/contributors"><img src="https://contrib.rocks/image?repo=swastiksingh-dev/Aura-Components-MCP" alt="All contributors"></a>
|
|
414
|
+
</p>
|
|
415
|
+
|
|
293
416
|
| Source | Used for | License / terms |
|
|
294
417
|
| --- | --- | --- |
|
|
295
418
|
| [Aura](https://www.aura.build) (Meng To / DesignCode) | The entire catalogue: components, skills, assets, design systems | Belongs to Aura and credited authors; assets all-rights-reserved per [Aura Terms §4](https://www.aura.build/terms) |
|
|
@@ -298,9 +421,12 @@ Server code by [swastiksingh-dev](https://github.com/swastiksingh-dev), MIT. Fre
|
|
|
298
421
|
| [Context7](https://context7.com) | Fresh library docs behind `aura_docs_*` (trusted: Tailwind CSS, GSAP, Lenis, Iconify) | Docs belong to their projects |
|
|
299
422
|
| [Font Awesome Free](https://fontawesome.com) | Icons via `aura_icon` (served from jsDelivr + cdnjs) | [CC BY 4.0](https://fontawesome.com/license/free) — credit on every hit, enforced by the tool |
|
|
300
423
|
| [HackerNoon Pixel Icon Library](https://github.com/hackernoon/pixel-icon-library) ([site](https://pixeliconlibrary.com)) | Pixel icons via `aura_icon` (served from jsDelivr) | Icons CC BY 4.0, other files MIT — credit on every hit, enforced by the tool |
|
|
424
|
+
| [Awwwards](https://www.awwwards.com) | Award-website references behind `aura_award_*` (metadata + Awwwards-CDN media URLs, never mirrored) | Screenshots/designs belong to Awwwards + credited creators — personal-inspiration use at ~1 req/s, honor robots.txt; see [THIRD_PARTY_NOTICES.md](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/THIRD_PARTY_NOTICES.md) |
|
|
425
|
+
| [awwwards-mcp](https://github.com/INSANE0777/Awwwards-mcp) by [INSANE0777](https://github.com/INSANE0777) | Behavioral inspiration for the six award tools (site discovery, design DNA, elements, briefs, indexing, capture, motion, winners, watches) — reimplemented natively, zero code copied | [MIT](https://github.com/INSANE0777/Awwwards-mcp/blob/main/LICENSE) © 2026 Afjal — permission notice preserved in [THIRD_PARTY_NOTICES.md](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/THIRD_PARTY_NOTICES.md) |
|
|
301
426
|
| Upstream libraries (Tailwind CSS, GSAP, Lenis, Iconify) | The code this server's guides point at | Each project's own license — check before shipping |
|
|
302
427
|
|
|
303
|
-
---
|
|
304
|
-
|
|
428
|
+
---
|
|
429
|
+
## License
|
|
430
|
+
|
|
305
431
|
|
|
306
|
-
MIT — see [LICENSE](
|
|
432
|
+
MIT — see [LICENSE](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/LICENSE).
|
package/SETUP.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Setup
|
|
2
2
|
|
|
3
|
-
One server, every client below. No account, no key, nothing to log into. If Node
|
|
3
|
+
One server, every client below. No account, no key, nothing to log into. If Node 22+ runs `node ./dist/server.js`, the client can use this.
|
|
4
4
|
|
|
5
5
|
Build once:
|
|
6
6
|
|
|
@@ -9,7 +9,7 @@ git clone https://github.com/swastiksingh-dev/Aura-Components-MCP.git
|
|
|
9
9
|
cd Aura-Components-MCP
|
|
10
10
|
npm install
|
|
11
11
|
npm run build
|
|
12
|
-
node ./dist/server.js # prints: aura-components-mcp v1.7.
|
|
12
|
+
node ./dist/server.js # prints: aura-components-mcp v1.7.2 listening on stdio (Ctrl+C to stop)
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
```bash
|
|
@@ -69,11 +69,11 @@ Restart Windsurf, open Cascade, allow the server when asked.
|
|
|
69
69
|
|
|
70
70
|
1. Open Cline settings, MCP Servers section.
|
|
71
71
|
2. Add server: command `node`, arg `/absolute/path/to/aura-components-mcp/dist/server.js`, name `aura-components`.
|
|
72
|
-
3. It lists
|
|
72
|
+
3. It lists 35 tools starting with `aura_`. Approve them once.
|
|
73
73
|
|
|
74
74
|
## Roo Code (VS Code)
|
|
75
75
|
|
|
76
|
-
Same as Cline: Add MCP server, command `node`, args `["/absolute/path/to/aura-components-mcp/dist/server.js"]`. Roo shows the
|
|
76
|
+
Same as Cline: Add MCP server, command `node`, args `["/absolute/path/to/aura-components-mcp/dist/server.js"]`. Roo shows the 35 `aura_` tools in its tool list after reload.
|
|
77
77
|
|
|
78
78
|
## DeepSeek Harness
|
|
79
79
|
|
|
@@ -102,7 +102,16 @@ Add to `opencode.json` (or `opencode.jsonc`) in your project root or `~/.config/
|
|
|
102
102
|
}
|
|
103
103
|
```
|
|
104
104
|
|
|
105
|
-
Restart OpenCode (or run `/mcp` to reload). The
|
|
105
|
+
Restart OpenCode (or run `/mcp` to reload). The 35 `aura_*` tools show up in the TUI. Same first prompt as Claude Code above. A copy-paste file lives at `examples/opencode.json`.
|
|
106
|
+
|
|
107
|
+
## Award tools (optional system programs)
|
|
108
|
+
|
|
109
|
+
Core award search/index/blueprint needs nothing extra. Live capture, structure,
|
|
110
|
+
and motion need Chrome/Chromium (or `AURA_CHROME_PATH` to its executable);
|
|
111
|
+
`.webm` motion video additionally needs ffmpeg (or `AURA_FFMPEG_PATH`).
|
|
112
|
+
Corpus lives in `~/.aura-mcp/awards` (`AURA_AWARDS_DIR` overrides). Build it with
|
|
113
|
+
`aura_award_index {action:rebuild}` (bounded `maxPages`, `resume` continues) —
|
|
114
|
+
the server never crawls on startup.
|
|
106
115
|
|
|
107
116
|
## Any other MCP client
|
|
108
117
|
|
|
@@ -120,7 +129,7 @@ Transport is stdio, no auth. Command `node`, args `["/absolute/path/to/aura-comp
|
|
|
120
129
|
|
|
121
130
|
## Troubleshooting
|
|
122
131
|
|
|
123
|
-
- Server exits instantly: check `node --version` (needs
|
|
132
|
+
- Server exits instantly: check `node --version` (needs 22+), then `npm run build` again.
|
|
124
133
|
- Client shows 0 tools: absolute path wrong, or the client needs a restart after config edit.
|
|
125
134
|
- `upstream` errors on every call: outbound network blocked. `npm run verify` from the same machine tells you in seconds.
|
|
126
135
|
- Counts look stale: 60-second cache. Wait a minute or set `AURA_CACHE_TTL_MS=0`.
|