aura-components-mcp 1.7.1 → 1.7.3
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 +235 -0
- package/README.md +152 -22
- package/SETUP.md +15 -4
- package/THIRD_PARTY_NOTICES.md +33 -0
- package/dist/server.js +2652 -23
- package/package.json +4 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `aura-components-mcp`.
|
|
4
|
+
|
|
5
|
+
## [1.7.3] — 2026-10-18
|
|
6
|
+
|
|
7
|
+
Hardening pass over the six award tools and shared infrastructure. No public
|
|
8
|
+
tool/contract changes, no new dependencies. Test suite: 275 hermetic
|
|
9
|
+
(226 before + 49 new) + 45 live checks green.
|
|
10
|
+
|
|
11
|
+
### Security
|
|
12
|
+
|
|
13
|
+
- Fixed `awardParseIpv6` compressed-form (`::`) fill count: every compressed
|
|
14
|
+
IPv6 was classified invalid, which mis-blocked public AAAA/dual-stack hosts
|
|
15
|
+
and broke `[::1]` under `allowLocal`. Classification now matches the literal
|
|
16
|
+
ranges (`::1` loopback, `fe80::/10`, `fc00::/7`, …), and `[::ffff:127.0.0.1]`
|
|
17
|
+
counts as loopback while mapped private/link-local/metadata addresses stay
|
|
18
|
+
blocked.
|
|
19
|
+
- All award HTML fetches (search, inspect, index crawl, static audit) run
|
|
20
|
+
through one guarded client: scheme + literal host policy, bounded best-effort
|
|
21
|
+
DNS check (positive-blocking only, ~1.5 s cap), redirect targets re-validated,
|
|
22
|
+
streamed body size cap (`/exceeds/`), 404 → `NOT_FOUND`, 429 → no retry.
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
|
|
26
|
+
- `aura_award_index` lifecycle: `rebuild` continues an unfinished same-plan
|
|
27
|
+
cycle and starts a new cycle only after completion; `resume` finishes
|
|
28
|
+
pending work and then returns an explicit complete no-op; `refresh` starts a
|
|
29
|
+
new cycle only after lock acquisition; `maxPages` (1–20) is enforced inside
|
|
30
|
+
the index layer as a per-call fetch budget.
|
|
31
|
+
- `new_winners` drift guard: an empty/failed upstream listing returns
|
|
32
|
+
`degraded: true` + parser stamp and never overwrites a non-empty baseline;
|
|
33
|
+
filtered-empty listings never count as empty; a genuinely empty but
|
|
34
|
+
understood listing on a fresh index seeds an explicit empty baseline.
|
|
35
|
+
- Watches: `kind:"url"` records normalize canonical `/sites/<slug>` URLs or
|
|
36
|
+
bare slugs; legacy raw-URL records still match at check time and
|
|
37
|
+
`watch_remove` accepts either form.
|
|
38
|
+
- Browser flows: after navigation settles the page URL is re-checked
|
|
39
|
+
(`location.href`, http(s) only); blocked/non-http(s) targets abort with
|
|
40
|
+
`UNSUPPORTED_OPERATION` + `blockedUrl` instead of reading page state.
|
|
41
|
+
- Artifact honesty: `capture` reports `artifactPath` only when the file was
|
|
42
|
+
actually written (`artifactNote` otherwise) and prunes old temp captures
|
|
43
|
+
(newest 20 kept) with a `retentionNote`; `recordFrames` prunes
|
|
44
|
+
`aura-motion-*` dirs older than 24 h; `encodeWebm` validates frames first
|
|
45
|
+
and reports `framesUsed`.
|
|
46
|
+
- `aura_design_blueprint` confidence gains its motion point only from recorded
|
|
47
|
+
motion studies (`motionRecorded: true`) — static markup cues never raise it.
|
|
48
|
+
- `aura_visual_audit` capture/motion rethrow `BROWSER_UNAVAILABLE` /
|
|
49
|
+
`UNSUPPORTED_OPERATION` instead of degrading to static estimates (browserless
|
|
50
|
+
modes still degrade, with `fallbackFrom`/`fallbackWhy`).
|
|
51
|
+
|
|
52
|
+
### Tests
|
|
53
|
+
|
|
54
|
+
- 6 new hermetic suites (49 checks): URL/IPv6 security matrix, bounded client
|
|
55
|
+
limits, index lifecycle (resume/refresh/lock), watch normalization, output
|
|
56
|
+
quality (confidence/notes/fragments), artifact retention + `encodeWebm`
|
|
57
|
+
validation. 275 hermetic total, all green.
|
|
58
|
+
|
|
59
|
+
## [1.7.2] — 2026-10-15
|
|
60
|
+
|
|
61
|
+
35 tools: the six award-intelligence tools below join the 29 catalogue tools
|
|
62
|
+
in the published package (no new npm dependencies).
|
|
63
|
+
|
|
64
|
+
### Added — award-website intelligence (6 new MCP tools, 29 → 35)
|
|
65
|
+
|
|
66
|
+
- `aura_award_search` (`sites`/`categories`/`elements`/`motion`): ranked
|
|
67
|
+
Awwwards references with preview links and match reasons, real taxonomy
|
|
68
|
+
from the index/source (never invented counts), element-gallery search, and
|
|
69
|
+
stored-motion search with empty-corpus vs zero-match distinguished.
|
|
70
|
+
- `aura_award_inspect`
|
|
71
|
+
(`site_details`/`site_elements`/`element`/`compare_sites`): source-backed
|
|
72
|
+
design DNA (palette, technologies, elements, awards, score), element media
|
|
73
|
+
URLs with attribution, and 2–3-site comparisons that mark missing fields as
|
|
74
|
+
unknown evidence, never negative proof.
|
|
75
|
+
- `aura_design_blueprint`: goal + 2–5 refs → Markdown brief plus versioned
|
|
76
|
+
JSON (`spec.version: 1`), mapped to real free Aura components/systems
|
|
77
|
+
(free-only enforced, catalogue failures reported as unavailable evidence).
|
|
78
|
+
Original plans only — never copied third-party source.
|
|
79
|
+
- `aura_visual_audit` (`capture`/`structure`/`compare`): real browser
|
|
80
|
+
screenshots and live-DOM band maps when Chrome is present; labeled
|
|
81
|
+
`static-html` estimates otherwise; reference-vs-build mismatch reports
|
|
82
|
+
without pixel-perfect claims. Loopback only with `allowLocal: true`.
|
|
83
|
+
- `aura_motion_study` (`inspect`/`record`/`search`): live runtime scans
|
|
84
|
+
(libraries, easing vocab, scroll model, ScrollTrigger counts), bounded
|
|
85
|
+
frame studies (2–16 frames, ≤30s), `.webm` only when a system ffmpeg
|
|
86
|
+
exists — otherwise frame JPEGs plus an honest hint.
|
|
87
|
+
- `aura_award_index`
|
|
88
|
+
(`status`/`rebuild`/`resume`/`refresh`/`new_winners`/`watch_add`/`watch_list`/`watch_remove`):
|
|
89
|
+
file-based JSON index in `~/.aura-mcp/awards` (override
|
|
90
|
+
`AURA_AWARDS_DIR`): atomic writes, schema versioning, corrupt quarantine
|
|
91
|
+
+ recovery, stale-lock single-writer, resume checkpoints, bounded growth
|
|
92
|
+
(5000 sites/5000 elements/200 motion), winner baselines with seed-then-delta,
|
|
93
|
+
studio/tag/url watches. Polite ~1 req/s crawl, bounded `maxPages` per call
|
|
94
|
+
(default 5, max 20). Nothing crawls automatically on server startup.
|
|
95
|
+
|
|
96
|
+
### Fixed — field-report pass (12 issues, P0–P2)
|
|
97
|
+
|
|
98
|
+
- CDP attach uses `/json/list` page targets instead of browser-endpoint
|
|
99
|
+
`Target.createTarget` (which hangs on several headless builds); every setup
|
|
100
|
+
failure normalizes to `BROWSER_UNAVAILABLE` with per-operation fallback
|
|
101
|
+
guidance. Fixed a worse latent bug the tests caught: the CDP response
|
|
102
|
+
handler was never installed on setter-only transports, so *every* command
|
|
103
|
+
would have timed out even against a healthy browser.
|
|
104
|
+
- `aura_visual_audit` degrades any live-dom failure to labeled `static-html`
|
|
105
|
+
estimates (`fallbackFrom`/`fallbackWhy`); local builds audit directly from
|
|
106
|
+
`file://`/local paths with `allowLocal:true` (`source:local-file`);
|
|
107
|
+
`capture` of a file path errors with serve-it guidance.
|
|
108
|
+
- `aura_design_blueprint` queries the catalogue once per proposed section
|
|
109
|
+
(up to 12 slim matches, sections covered reported), always emits
|
|
110
|
+
`## Evidence gaps` (motion/structure/catalogue), and synthesizes goal-named
|
|
111
|
+
hexes as `proposed` palette tokens against observed luminance bands.
|
|
112
|
+
- Search relevance: design-vocabulary aliases (`glassy`→`glassmorphism`,
|
|
113
|
+
`3d`→`webgl`, …) + `theme:dark/light` tag boost; reasons name the query
|
|
114
|
+
word; zero-token rows still score 0 (honest-empty preserved).
|
|
115
|
+
- Catalogue matcher stems inflections (`glassy`→`glass`, plural→singular) in
|
|
116
|
+
both ranking and the refusal gate — `features glass bento` style queries
|
|
117
|
+
stop dead-ending while nonsense queries still refuse honestly.
|
|
118
|
+
- Empty Technologies sections backfill from listing tags, labeled
|
|
119
|
+
`technologiesInferred:true` with evidence note.
|
|
120
|
+
- `compare_sites` adds fuzzy element-keyword overlap, per-site luminance
|
|
121
|
+
bands, and `directionHints`.
|
|
122
|
+
- `categories` honors `limit`/`offset` (`filtersTotal` disclosed); every
|
|
123
|
+
search response carries `source` + `corpusNote` documenting the
|
|
124
|
+
seed-once-then-local rule.
|
|
125
|
+
|
|
126
|
+
### Polish — deep-module cleanup (skill 16-codebase-design)
|
|
127
|
+
|
|
128
|
+
- Removed dead surface: unused `awardNormalizeUrl`, `AWARD_ELEMENT_CATS`,
|
|
129
|
+
`AWARD_SCORE_VERSION` exports and seven unreferenced names from the
|
|
130
|
+
`tools.mjs` import lists.
|
|
131
|
+
- One section list: `AWARD_SECTIONS` is the single source both the blueprint
|
|
132
|
+
handler and builder share (was duplicated verbatim).
|
|
133
|
+
- Static-cue rendering moved next to its data shape (`awardStaticSummary`);
|
|
134
|
+
the handler just maps it. Tautological test assertion replaced with real
|
|
135
|
+
ones (no `total` key; `filtersTotal` consistency).
|
|
136
|
+
|
|
137
|
+
### Fixed — refusal gate, hex tokens, static motion, fallback evidence
|
|
138
|
+
|
|
139
|
+
- Refusal gate judges the global best row, not the first: theme-first
|
|
140
|
+
ordering re-ranks but can no longer let a 0-hit leader veto matching rows
|
|
141
|
+
below it; `fallback_score` refreshes to the best row. Empty means zero rows
|
|
142
|
+
matched, honestly.
|
|
143
|
+
- Scaffold discloses `system_note` when no design system matches instead of
|
|
144
|
+
shipping silent empty `tokens_css`.
|
|
145
|
+
- Hex codes (`#0a0a0b`, bare 6-hex with a digit) are excluded from catalogue
|
|
146
|
+
search tokens — titles never contain them, so they poisoned overlap counts
|
|
147
|
+
and emptied scaffolds. Real words (`red`, `face`, `decade`) are kept via a
|
|
148
|
+
digit rule. Goals with hexes now match instead of refusing.
|
|
149
|
+
- `site_details` returns browserless motion evidence: `motion_static`
|
|
150
|
+
(library scripts, keyframe/transition counts, scroll cues, canvases,
|
|
151
|
+
`prefers-reduced-motion` — all labeled static-markup, never runtime) plus
|
|
152
|
+
a runtime-visible `ideas_contract`. Blueprints cite static cues when no
|
|
153
|
+
study is recorded; confidence still requires recorded evidence.
|
|
154
|
+
- Blueprint matches record `matchEvidence.fallback` and the markdown marks
|
|
155
|
+
`(via fallback …)` rows; `search_all` fallback flags stay per-surface
|
|
156
|
+
(regression-locked). Technologies section titles tolerate `&`.
|
|
157
|
+
|
|
158
|
+
### Fixed — PostgREST escaping, ideas contract, evidence-scored confidence
|
|
159
|
+
|
|
160
|
+
- Goals containing `#`, `(`, `)`, `"`, `'`, `%`, `,` no longer crash
|
|
161
|
+
catalogue queries (PGRST100): `ilike` values percent-encode significant
|
|
162
|
+
chars while `*` wildcards survive, and `eq`/`in`/`neq` id/slug filters use
|
|
163
|
+
the same hardened encoder. Matching is preserved (server-side decode).
|
|
164
|
+
- `site_details ideas` contract: 0–6 by evidence, 1 on thin evidence is
|
|
165
|
+
valid, every entry `status:suggested` with an observed `basis`.
|
|
166
|
+
- Blueprint `confidence` is evidence-scored (usable refs + matched sections
|
|
167
|
+
+ recorded motion + measured structure + fully-parsed tech → low …
|
|
168
|
+
low-medium … medium … high, with `confidenceWhy`).
|
|
169
|
+
|
|
170
|
+
- `aura_design_blueprint` details (≤5 refs), all 9 section queries, `compare`
|
|
171
|
+
refs, and `includeStructure` targets now fetch concurrently (order
|
|
172
|
+
preserved; award client still spaces requests 1/s; `NOT_FOUND` still
|
|
173
|
+
throws). `search{full:true}` enriches max 5 hits with disclosure.
|
|
174
|
+
- Search hits carry tag-derived `try_for` cues; `site_details` carries
|
|
175
|
+
rule-based `ideas` (every one `status:suggested` + evidence `basis`).
|
|
176
|
+
- Blueprints return executable `next_calls` (`aura_get_component`,
|
|
177
|
+
`aura_scaffold_page`, `aura_motion_study`) built only from gathered
|
|
178
|
+
ids/urls, plus paste-ready `:root` tokens (`spec.tokens_css`).
|
|
179
|
+
|
|
180
|
+
- `aura_award_search{mode:elements}` no longer crashes in `dist`: the build
|
|
181
|
+
renamer rewrote `Array.sort(` into `.toolFn_sort(` (src tests stayed green,
|
|
182
|
+
only the bundle crashed). The renamer now excludes `.`-prefixed method
|
|
183
|
+
calls; a dist-level test (renamer assertion + bundled-server elements
|
|
184
|
+
smoke) guards it.
|
|
185
|
+
- Weak-consensus blueprints fill from human-grade editorial picks (<3
|
|
186
|
+
section matches → `editorial:true` matches + disclosure) instead of
|
|
187
|
+
shipping a 1-match brief.
|
|
188
|
+
- `compare_sites` canonicalizes technology families (`WebGL`≈`Three.js`,
|
|
189
|
+
`GSAP`≈`GreenSock`) for overlap + hints; raw per-site values stay verbatim.
|
|
190
|
+
- Browser-less environments get more than an error code: motion errors carry
|
|
191
|
+
a generic (explicitly unobserved) motion plan; dead-server + dead-browser
|
|
192
|
+
audits name both fixes (serve the build / pass the file); Chrome launches
|
|
193
|
+
with `--no-sandbox` for Windows admin shells.
|
|
194
|
+
|
|
195
|
+
### Zero-dependency behavior
|
|
196
|
+
|
|
197
|
+
- No new npm dependencies (`package.json` gains none). New modules use only
|
|
198
|
+
Node builtins via `process.getBuiltinModule` (works in source and in the
|
|
199
|
+
concatenated `dist` bundle, which stays `import`-free): `fetch`,
|
|
200
|
+
global `WebSocket` for CDP, `node:fs`/`path`/`os`/`child_process`.
|
|
201
|
+
- Optional system programs only: Chrome/Chromium (`AURA_CHROME_PATH`) for
|
|
202
|
+
live capture/structure/motion; ffmpeg (`AURA_FFMPEG_PATH`) for `.webm`
|
|
203
|
+
encoding. Core search/index/blueprint work without either; absence yields
|
|
204
|
+
`BROWSER_UNAVAILABLE` + setup guidance, never fake output.
|
|
205
|
+
|
|
206
|
+
### Security
|
|
207
|
+
|
|
208
|
+
- URL safety on every browser/capture path: http(s) only, no credentials,
|
|
209
|
+
private/cloud-metadata hosts blocked unless `allowLocal: true`, redirect
|
|
210
|
+
hosts revalidated against the award allowlist.
|
|
211
|
+
- Award fetching only touches `www.awwwards.com` / `assets.awwwards.com`;
|
|
212
|
+
markup-derived URLs are never followed as trusted.
|
|
213
|
+
- Bounded everything: 10s page timeout, 2MB response cap, one transient
|
|
214
|
+
retry (blocks never retried), CDP command timeouts, temp-profile cleanup,
|
|
215
|
+
child-process termination, no secrets in errors.
|
|
216
|
+
|
|
217
|
+
### Tests
|
|
218
|
+
|
|
219
|
+
- 66 new hermetic tests (no network, no browser): `test/awards.test.mjs`
|
|
220
|
+
(21: parsers, ranking, client errors), `test/awards-index.test.mjs` (15:
|
|
221
|
+
lifecycle, locks, corruption, winners, watches), `test/browser-cdp.test.mjs`
|
|
222
|
+
(14: CDP framing, bands, motion reduce, honest unavailability),
|
|
223
|
+
`test/award-tools.test.mjs` (16: 35-tool registry, JSON-RPC dispatch,
|
|
224
|
+
blueprint honesty, error mapping). Full suite: 188 tests.
|
|
225
|
+
- `scripts/verify.mjs`: 38 live checks + 6 award validation checks (43 total).
|
|
226
|
+
|
|
227
|
+
## [1.7.1] — hardening release (published)
|
|
228
|
+
|
|
229
|
+
Bug-fix release, no new tools. Central free-only enforcement, theme-isolated
|
|
230
|
+
search cache, bundle-8 end-to-end, disclosed counts, malformed-row gate,
|
|
231
|
+
no-retry 4xx, Node `>=22` with CI matrix 22.x/24.x. See README for details.
|
|
232
|
+
|
|
233
|
+
## [1.7.0] — 29 tools (published)
|
|
234
|
+
|
|
235
|
+
Inspo bridge, docs helpers, `aura_icon`, `aura_version`, `aura_prompt`.
|
package/README.md
CHANGED
|
@@ -1,17 +1,31 @@
|
|
|
1
|
-
<
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/swastiksingh-dev/Aura-Components-MCP/main/assets/banner.png" alt="Aura Components MCP — every free thing on aura.build, one stdio call away. 2,495 components · 192 skills · 30,688 assets · 725 design systems · 35 tools · zero dependencies.">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
5
|
<p align="center"><sub>FREE MCP SERVER · STDIO · ZERO DEPS · MIT</sub></p>
|
|
4
6
|
|
|
5
7
|
<p align="center">
|
|
6
8
|
<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>
|
|
7
9
|
<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>
|
|
8
|
-
<a href="
|
|
9
|
-
<a href="
|
|
10
|
-
<a href="
|
|
10
|
+
<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>
|
|
11
|
+
<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>
|
|
12
|
+
<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>
|
|
13
|
+
<a href="#the-35-tools"><img src="https://img.shields.io/badge/tools-35-blueviolet" alt="35 tools"></a>
|
|
14
|
+
<a href="#develop"><img src="https://img.shields.io/badge/live_checks-45-brightgreen" alt="45 live checks"></a>
|
|
15
|
+
<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>
|
|
16
|
+
<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>
|
|
11
17
|
</p>
|
|
12
18
|
|
|
13
19
|
<p align="center"><i>Every free thing on Aura, one call away — no account, no key, no browser.</i></p>
|
|
14
20
|
|
|
21
|
+
<p align="center">
|
|
22
|
+
<a href="#install"><b>Install</b></a> ·
|
|
23
|
+
<a href="#the-35-tools"><b>Tools</b></a> ·
|
|
24
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md"><b>Client setup</b></a> ·
|
|
25
|
+
<a href="https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/CHANGELOG.md"><b>Changelog</b></a> ·
|
|
26
|
+
<a href="#credits"><b>Credits</b></a>
|
|
27
|
+
</p>
|
|
28
|
+
|
|
15
29
|
<p align="center">
|
|
16
30
|
<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>
|
|
17
31
|
</p>
|
|
@@ -20,27 +34,40 @@
|
|
|
20
34
|
|
|
21
35
|
<p align="center">
|
|
22
36
|
<b>2,495</b> free components · <b>192</b> skills · <b>30,688</b> assets · <b>725</b> design systems<br>
|
|
23
|
-
<b>
|
|
37
|
+
<b>35</b> tools · <b>0</b> dependencies · <b>275</b> hermetic tests + <b>45</b> live checks green · version-checked hourly against npm
|
|
24
38
|
</p>
|
|
25
39
|
|
|
26
40
|
---
|
|
41
|
+
## Contents
|
|
27
42
|
|
|
28
43
|
|
|
29
44
|
- [Why not the official MCP](#why-i-built-this-instead-of-using-the-official-mcp)
|
|
30
45
|
- [What is inside](#what-is-inside)
|
|
31
46
|
- [Install](#install)
|
|
32
47
|
- [Demo](#demo)
|
|
33
|
-
- [The
|
|
48
|
+
- [The 35 tools](#the-35-tools)
|
|
34
49
|
- [Fallback rules](#fallback-rules-read-this-once)
|
|
35
|
-
- [Prompt for AI agents](
|
|
50
|
+
- [Prompt for AI agents](#prompt-for-ai-agents-start-here)
|
|
36
51
|
- [Free only, no login](#free-only-no-login)
|
|
37
52
|
- [Develop](#develop)
|
|
38
53
|
- [Credits](#credits)
|
|
39
54
|
|
|
55
|
+
> **v1.7.3** — hardening release, no new tools, no new dependencies. The whole award layer now fetches through one guarded path (scheme/host/DNS policy, re-checked redirects, size-capped bodies) plus the IPv6 parser fix that had mis-blocked public AAAA/dual-stack hosts. Plan-based index lifecycle (`rebuild` continues, `resume` finishes, `refresh` forces), drift-guarded winner baselines that an empty listing can't wipe, normalized URL watches, and artifact-honest capture/motion. 49 new hermetic tests lock it in: **275 hermetic + 45 live checks, all green**.
|
|
56
|
+
|
|
57
|
+
<details>
|
|
58
|
+
<summary><b>v1.7.1 changelog</b> — click to expand</summary>
|
|
59
|
+
|
|
40
60
|
> **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.
|
|
41
61
|
|
|
62
|
+
</details>
|
|
63
|
+
|
|
64
|
+
<details>
|
|
65
|
+
<summary><b>v1.7.0 changelog (29 tools)</b> — click to expand</summary>
|
|
66
|
+
|
|
42
67
|
> **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.
|
|
43
68
|
|
|
69
|
+
</details>
|
|
70
|
+
|
|
44
71
|
<details>
|
|
45
72
|
<summary><b>v1.6.3 changelog (20 tools)</b> — click to expand</summary>
|
|
46
73
|
|
|
@@ -53,6 +80,7 @@ Point any MCP client at `dist/server.js` and your agent can search 2,495 free co
|
|
|
53
80
|
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.
|
|
54
81
|
|
|
55
82
|
---
|
|
83
|
+
## Why I built this instead of using the official MCP
|
|
56
84
|
|
|
57
85
|
|
|
58
86
|
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:
|
|
@@ -64,13 +92,15 @@ Aura already ships an official MCP at `https://mcp.aura.build/mcp`. It is good a
|
|
|
64
92
|
- Everything defaults to free. Pro rows never sneak into results.
|
|
65
93
|
|
|
66
94
|
---
|
|
95
|
+
## What is inside
|
|
67
96
|
|
|
68
97
|
|
|
69
98
|
- 2,495 free components with HTML/Tailwind source, preview images, tags, and author credit
|
|
70
99
|
- 192 agent skills with full SKILL.md bodies (GSAP, Tailwind v4, Anime.js, copywriting, and more)
|
|
71
100
|
- 30,688 images and clips with direct CDN URLs at multiple widths
|
|
72
101
|
- 725 DESIGN.md systems with tokens, type rules, layout notes, and preview HTML
|
|
73
|
-
-
|
|
102
|
+
- 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
|
|
103
|
+
- 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
|
|
74
104
|
- 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
|
|
75
105
|
- 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)
|
|
76
106
|
- Faceted lists: every component carries `facets { theme, weight, code_chars, needsTailwind, needsIcons, fonts }`; filter `theme: dark|light` server-side
|
|
@@ -78,6 +108,7 @@ Aura already ships an official MCP at `https://mcp.aura.build/mcp`. It is good a
|
|
|
78
108
|
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.
|
|
79
109
|
|
|
80
110
|
---
|
|
111
|
+
## Install
|
|
81
112
|
|
|
82
113
|
|
|
83
114
|
Needs Node 22 or newer. No other dependency. Pick one:
|
|
@@ -92,7 +123,7 @@ node ./dist/server.js
|
|
|
92
123
|
```
|
|
93
124
|
|
|
94
125
|
```bash
|
|
95
|
-
# Option B — npm
|
|
126
|
+
# Option B — npm
|
|
96
127
|
npm i -g aura-components-mcp
|
|
97
128
|
aura-components-mcp
|
|
98
129
|
```
|
|
@@ -102,7 +133,15 @@ aura-components-mcp
|
|
|
102
133
|
npx -y aura-components-mcp@latest
|
|
103
134
|
```
|
|
104
135
|
|
|
105
|
-
Then register it in your client. Full per-client steps live in [SETUP.md](
|
|
136
|
+
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.
|
|
137
|
+
|
|
138
|
+
<p align="center">
|
|
139
|
+
<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>
|
|
140
|
+
<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>
|
|
141
|
+
<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>
|
|
142
|
+
<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>
|
|
143
|
+
<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>
|
|
144
|
+
</p>
|
|
106
145
|
|
|
107
146
|
```bash
|
|
108
147
|
# Claude Code
|
|
@@ -120,20 +159,24 @@ claude mcp add aura-components -- node ./dist/server.js
|
|
|
120
159
|
```
|
|
121
160
|
|
|
122
161
|
---
|
|
162
|
+
## Demo
|
|
123
163
|
|
|
124
164
|
|
|
125
165
|
<p align="center">
|
|
126
166
|
<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>
|
|
127
|
-
<br><em>Same file as <a href="
|
|
167
|
+
<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>
|
|
128
168
|
</p>
|
|
129
169
|
|
|
130
170
|
*`aura_prompt` turns one sentence into a confirmed prompt, `aura_recommend` turns it into a starter kit with links. Full clip in [`assets/`](assets/).*
|
|
131
171
|
|
|
132
172
|
---
|
|
173
|
+
## The 35 tools
|
|
133
174
|
|
|
134
175
|
|
|
135
176
|
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.
|
|
136
177
|
|
|
178
|
+
> **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).
|
|
179
|
+
|
|
137
180
|
### Find
|
|
138
181
|
|
|
139
182
|
| Tool | What it returns |
|
|
@@ -165,7 +208,7 @@ Start with `aura_status`, then `aura_search_all`. That order matters: status con
|
|
|
165
208
|
| `aura_install_skill` | Where to save SKILL.md so the agent can load it, plus upstream link. |
|
|
166
209
|
| `aura_install_asset` | Legal drop-in: download + preview URLs, license (all-rights-reserved per [Aura Terms §4](https://www.aura.build/terms)), file path. |
|
|
167
210
|
| `aura_use_design_system` | Token starter CSS plus the order to apply things in. |
|
|
168
|
-
| `aura_scaffold_page` | One-turn page build: tokens.css + system preview + markup in order, combined deps + files. `components: ["732","1364"]` or `[{id:"732"}]`. |
|
|
211
|
+
| `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. |
|
|
169
212
|
| `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`. |
|
|
170
213
|
|
|
171
214
|
### Bridge (Inspo · fresh docs · icons)
|
|
@@ -181,11 +224,59 @@ Start with `aura_status`, then `aura_search_all`. That order matters: status con
|
|
|
181
224
|
| `aura_docs_check` | Pasted code vs fresh docs (pure): verdict current\|needs-update, look-preserving fixes, pin checks. |
|
|
182
225
|
| `aura_icon` | One free icon as ready SVG (live): FA Free + HackerNoon pixel lib, auto-fallback, license + credit always, font alternative, 24h cache. |
|
|
183
226
|
| `aura_version` | Running vs npm-published version (live, hourly cache). `update_available` + prefer-latest notice. `aura_status` carries the verdict on every call. |
|
|
184
|
-
|
|
227
|
+
|
|
228
|
+
### Award intelligence (new in v1.7.2 — 6 tools, zero npm deps)
|
|
229
|
+
|
|
230
|
+
Search → inspect → blueprint → audit → motion. Core search/index work with no
|
|
231
|
+
browser; live capture needs Chrome (see setup below).
|
|
232
|
+
|
|
233
|
+
| Tool | Modes | What it returns |
|
|
234
|
+
| --- | --- | --- |
|
|
235
|
+
| `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. |
|
|
236
|
+
| `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). |
|
|
237
|
+
| `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. |
|
|
238
|
+
| `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. Capture never claims an `artifactPath` it didn't write (see `artifactNote`) and prunes old temp captures (newest 20 kept) with a `retentionNote` when no `saveDir` is set; a navigation to a blocked/non-http(s) URL after settle aborts with `UNSUPPORTED_OPERATION` + `blockedUrl`. |
|
|
239
|
+
| `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. `record` validates frames before encoding and reports `framesUsed`; temp `aura-motion-*` dirs older than 24h are pruned with a `retentionNote` when no `saveDir` is set. |
|
|
240
|
+
| `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` per call (default 5, max 20). `rebuild` continues an unfinished cycle (starts a new one after completion), `resume` finishes pending work, `refresh` forces a new crawl. Winner baseline-then-delta is drift-guarded (an empty upstream listing reports `degraded:true` instead of overwriting the baseline). Watches accept studio/tag or canonical `/sites/<slug>` URLs/slugs (legacy raw URLs still match). Never auto-crawls on startup. |
|
|
241
|
+
|
|
242
|
+
**Browser setup (optional, capture/motion only):** install Chrome/Chromium, or set
|
|
243
|
+
`AURA_CHROME_PATH` to its executable. For `.webm` motion video, also install
|
|
244
|
+
ffmpeg or set `AURA_FFMPEG_PATH`. Without them the six tools still search,
|
|
245
|
+
inspect (via polite HTML fetch), blueprint, index, and report
|
|
246
|
+
`BROWSER_UNAVAILABLE` with setup guidance where a live browser is required.
|
|
247
|
+
CDP setup failures (refused socket, hung attach) normalize to the same
|
|
248
|
+
`BROWSER_UNAVAILABLE` code with a per-operation fallback hint — never a raw
|
|
249
|
+
CDP timeout.
|
|
250
|
+
|
|
251
|
+
```mermaid
|
|
252
|
+
%%{init: {'theme': 'base', 'themeVariables': {'fontFamily': 'Inter, system-ui, -apple-system, sans-serif', 'fontSize': '15px', 'lineColor': '#ff2a2a', 'edgeLabelBackground': '#0a0a0b'}}}%%
|
|
253
|
+
flowchart LR
|
|
254
|
+
S["🔍 aura_award_search<br/>ranked refs + try_for"] --> I["🧬 aura_award_inspect<br/>design DNA + ideas"]
|
|
255
|
+
I --> B["📐 aura_design_blueprint<br/>brief + tokens + next_calls"]
|
|
256
|
+
B --> A["📸 aura_visual_audit<br/>capture / bands / compare"]
|
|
257
|
+
A --> M["🎞️ aura_motion_study<br/>scans + studies"]
|
|
258
|
+
B -.-> X["🗂️ aura_award_index<br/>corpus · winners · watches"]
|
|
259
|
+
X -.-> S
|
|
260
|
+
classDef core fill:#111318,stroke:#8b949e,color:#f5f5f5,stroke-width:2px;
|
|
261
|
+
classDef hot fill:#1c0606,stroke:#ff2a2a,color:#ffffff,stroke-width:2px;
|
|
262
|
+
classDef idx fill:#161a08,stroke:#d4a017,color:#ffffff,stroke-width:2px;
|
|
263
|
+
class S,I,A,M core;
|
|
264
|
+
class B hot;
|
|
265
|
+
class X idx;
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
> The 6-call award loop (fast: details + section queries run concurrently):
|
|
269
|
+
> `search → inspect → blueprint → follow its next_calls → audit → motion`
|
|
270
|
+
|
|
271
|
+
**Two award servers?** If you also run `awwwards-mcp`, keep both or pick one:
|
|
272
|
+
`aura_award_*` is canonical here — it's the only path that maps references to
|
|
273
|
+
Aura's free catalogue inside `aura_design_blueprint`. The standalone server
|
|
274
|
+
can't do that mapping.
|
|
185
275
|
|
|
186
276
|
Every row carries `page_url` (open it to see the design) and `author` where Aura credits one.
|
|
187
277
|
|
|
188
278
|
---
|
|
279
|
+
## Fallback rules (read this once)
|
|
189
280
|
|
|
190
281
|
|
|
191
282
|
- **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.
|
|
@@ -193,11 +284,13 @@ Every row carries `page_url` (open it to see the design) and `author` where Aura
|
|
|
193
284
|
- **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.
|
|
194
285
|
- **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.
|
|
195
286
|
- **`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`.
|
|
287
|
+
- **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`. Award fetches pass a URL policy (http(s) only; private/loopback/link-local/metadata ranges blocked; bounded best-effort DNS check; redirect targets re-checked; bodies size-capped) — `allowLocal` relaxes loopback only. 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 (`maxPages` is a per-call budget, `resume` continues); palettes come only from observable page evidence; tech labels are inferences with triggers shown; `static-html` bands have no measured offsets.
|
|
196
288
|
|
|
197
289
|
---
|
|
290
|
+
## Prompt for AI agents (start here)
|
|
198
291
|
|
|
199
292
|
|
|
200
|
-
> The fastest way to a shippable page. Two passes, one confirmation.
|
|
293
|
+
> ✨ The fastest way to a shippable page. Two passes, one confirmation.
|
|
201
294
|
|
|
202
295
|
```text
|
|
203
296
|
Pass 1 — agent calls:
|
|
@@ -232,6 +325,7 @@ Sources: [tips-for-prompting](https://www.aura.build/learn/tips-for-prompting),
|
|
|
232
325
|
[design-systems](https://www.aura.build/design-systems).
|
|
233
326
|
|
|
234
327
|
---
|
|
328
|
+
## How I use it
|
|
235
329
|
|
|
236
330
|
|
|
237
331
|
New landing page, dark cinematic portfolio, SaaS pricing section. The shape is the same each time:
|
|
@@ -242,9 +336,10 @@ New landing page, dark cinematic portfolio, SaaS pricing section. The shape is t
|
|
|
242
336
|
4. `aura_install_component` on the winner. Follow the file map.
|
|
243
337
|
5. `aura_use_design_system` once, before any markup, so tokens land first.
|
|
244
338
|
|
|
245
|
-
Prompts that work well are in [SETUP.md](
|
|
339
|
+
Prompts that work well are in [SETUP.md](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/SETUP.md#prompts-that-work).
|
|
246
340
|
|
|
247
341
|
---
|
|
342
|
+
## Free only, no login
|
|
248
343
|
|
|
249
344
|
|
|
250
345
|
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.
|
|
@@ -266,35 +361,67 @@ Optional tuning (all with defaults):
|
|
|
266
361
|
</details>
|
|
267
362
|
|
|
268
363
|
---
|
|
364
|
+
## Develop
|
|
269
365
|
|
|
270
366
|
|
|
271
367
|
```bash
|
|
272
|
-
npm test # hermetic tests, no network
|
|
273
|
-
npm run verify #
|
|
368
|
+
npm test # hermetic tests, no network (275 tests)
|
|
369
|
+
npm run verify # 45 live checks against the real catalogue + award validation
|
|
274
370
|
npm run build # rebundle src/*.mjs into dist/server.js
|
|
275
371
|
```
|
|
276
372
|
|
|
277
|
-
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.
|
|
373
|
+
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.
|
|
278
374
|
|
|
279
375
|
---
|
|
376
|
+
## Share
|
|
280
377
|
|
|
281
378
|
|
|
282
|
-
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](
|
|
379
|
+
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.
|
|
283
380
|
|
|
284
|
-
[](https://star-history.com/#swastiksingh-dev/Aura-Components-MCP&Date)
|
|
381
|
+
[](https://star-history.com/#swastiksingh-dev/Aura-Components-MCP&Date)
|
|
285
382
|
|
|
286
383
|
```text
|
|
287
|
-
built a free design MCP on aura.build: 2495 components, 192 skills, 30k assets,
|
|
384
|
+
built a free design MCP on aura.build: 2495 components, 192 skills, 30k assets, 35 tools. no login. resources are @MengTo's
|
|
288
385
|
|
|
289
386
|
npx -y aura-components-mcp@latest
|
|
290
387
|
https://github.com/swastiksingh-dev/Aura-Components-MCP
|
|
291
388
|
```
|
|
292
389
|
|
|
293
390
|
---
|
|
391
|
+
## Credits
|
|
392
|
+
|
|
294
393
|
|
|
394
|
+
<p align="center"><sub>Standing on the shoulders of open work — every source below is linked, licensed, and honored in the code.</sub></p>
|
|
395
|
+
|
|
396
|
+
<table align="center">
|
|
397
|
+
<tr>
|
|
398
|
+
<td align="center" width="200">
|
|
399
|
+
<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>
|
|
400
|
+
</td>
|
|
401
|
+
<td align="center" width="200">
|
|
402
|
+
<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>
|
|
403
|
+
</td>
|
|
404
|
+
<td align="center" width="200">
|
|
405
|
+
<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>
|
|
406
|
+
</td>
|
|
407
|
+
</tr>
|
|
408
|
+
</table>
|
|
295
409
|
|
|
296
410
|
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.
|
|
297
411
|
|
|
412
|
+
### Contributors
|
|
413
|
+
|
|
414
|
+
<p align="center">
|
|
415
|
+
<a href="https://github.com/swastiksingh-dev"><img src="https://github.com/swastiksingh-dev.png?size=80" width="60" alt="swastiksingh-dev"></a>
|
|
416
|
+
<a href="https://github.com/INSANE0777"><img src="https://github.com/INSANE0777.png?size=80" width="60" alt="INSANE0777"></a>
|
|
417
|
+
<a href="https://github.com/MengTo"><img src="https://github.com/MengTo.png?size=80" width="60" alt="Meng To"></a>
|
|
418
|
+
<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>
|
|
419
|
+
</p>
|
|
420
|
+
|
|
421
|
+
<p align="center">
|
|
422
|
+
<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>
|
|
423
|
+
</p>
|
|
424
|
+
|
|
298
425
|
| Source | Used for | License / terms |
|
|
299
426
|
| --- | --- | --- |
|
|
300
427
|
| [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) |
|
|
@@ -303,9 +430,12 @@ Server code by [swastiksingh-dev](https://github.com/swastiksingh-dev), MIT. Fre
|
|
|
303
430
|
| [Context7](https://context7.com) | Fresh library docs behind `aura_docs_*` (trusted: Tailwind CSS, GSAP, Lenis, Iconify) | Docs belong to their projects |
|
|
304
431
|
| [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 |
|
|
305
432
|
| [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 |
|
|
433
|
+
| [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) |
|
|
434
|
+
| [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) |
|
|
306
435
|
| Upstream libraries (Tailwind CSS, GSAP, Lenis, Iconify) | The code this server's guides point at | Each project's own license — check before shipping |
|
|
307
436
|
|
|
308
437
|
---
|
|
438
|
+
## License
|
|
309
439
|
|
|
310
440
|
|
|
311
|
-
MIT — see [LICENSE](
|
|
441
|
+
MIT — see [LICENSE](https://github.com/swastiksingh-dev/Aura-Components-MCP/blob/main/LICENSE).
|