aura-components-mcp 1.7.0 → 1.7.1

package/README.md

@@ -1,40 +1,44 @@
-<h1 align="center">aura-components-mcp</h1>
+<h1 align="center">Aura Components MCP</h1>
+
+<p align="center"><sub>FREE MCP SERVER · STDIO · ZERO DEPS · MIT</sub></p>
 
 <p align="center">
   <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>
   <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>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license: MIT"></a>
-  <a href="./package.json"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node >= 18"></a>
+  <a href="./package.json"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen" alt="node >= 22"></a>
   <a href="./dist/server.js"><img src="https://img.shields.io/badge/MCP-stdio-blue" alt="MCP stdio"></a>
 </p>
 
 <p align="center"><i>Every free thing on Aura, one call away — no account, no key, no browser.</i></p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/swastiksingh-dev/Aura-Components-MCP/main/assets/site-tour.gif" alt="aura-components-mcp demo: dark WebGL hero, 28 grouped tools, one-minute setup" width="100%">
+  <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>
 </p>
 
 > 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.
 
 <p align="center">
   <b>2,495</b> free components · <b>192</b> skills · <b>30,688</b> assets · <b>725</b> design systems<br>
-  <b>29</b> tools · <b>0</b> dependencies · <b>94</b> hermetic tests + <b>35</b> live checks green · version-checked hourly against npm
+  <b>29</b> tools · <b>0</b> dependencies · <b>112</b> hermetic tests + <b>38</b> live checks green · version-checked hourly against npm
 </p>
 
----
-
+---
+
 
 - [Why not the official MCP](#why-i-built-this-instead-of-using-the-official-mcp)
 - [What is inside](#what-is-inside)
 - [Install](#install)
 - [Demo](#demo)
-- [The 29 tools](#the-28-tools)
+- [The 29 tools](#the-29-tools)
 - [Fallback rules](#fallback-rules-read-this-once)
 - [Prompt for AI agents](#-prompt-for-ai-agents--start-here)
 - [Free only, no login](#free-only-no-login)
 - [Develop](#develop)
 - [Credits](#credits)
 
+> **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.
+
 > **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.
 
 <details>
@@ -48,8 +52,8 @@ Point any MCP client at `dist/server.js` and your agent can search 2,495 free co
 
 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.
 
----
-
+---
+
 
 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:
 
@@ -59,8 +63,8 @@ Aura already ships an official MCP at `https://mcp.aura.build/mcp`. It is good a
 - `aura_recommend` builds a starter kit across all four surfaces in one parallel call.
 - Everything defaults to free. Pro rows never sneak into results.
 
----
-
+---
+
 
 - 2,495 free components with HTML/Tailwind source, preview images, tags, and author credit
 - 192 agent skills with full SKILL.md bodies (GSAP, Tailwind v4, Anime.js, copywriting, and more)
@@ -73,10 +77,10 @@ Aura already ships an official MCP at `https://mcp.aura.build/mcp`. It is good a
 
 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.
 
----
-
+---
+
 
-Needs Node 18 or newer. No other dependency. Pick one:
+Needs Node 22 or newer. No other dependency. Pick one:
 
 ```bash
 # Option A — from source (GitHub)
@@ -115,18 +119,18 @@ claude mcp add aura-components -- node ./dist/server.js
 { "$schema": "https://opencode.ai/config.json", "mcp": { "aura-components": { "type": "local", "command": ["node", "./dist/server.js"], "enabled": true } } }
 ```
 
----
-
+---
+
 
 <p align="center">
-  <a href="https://raw.githubusercontent.com/swastiksingh-dev/Aura-Components-MCP/main/assets/heart-demo.mp4"><img src="https://raw.githubusercontent.com/swastiksingh-dev/Aura-Components-MCP/main/assets/site-tour.gif" alt="Watch the 10-second flow tour (MP4) — click to play" width="100%"></a>
-  <br><em>Click the preview to watch the 10-second flow tour (MP4, 1918x936, ~8MB) — same file as <a href="./assets/heart-demo.mp4">assets/heart-demo.mp4</a></em>
+  <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>
+  <br><em>Same file as <a href="./assets/heart-demo.mp4">assets/heart-demo.mp4</a></em>
 </p>
 
 *`aura_prompt` turns one sentence into a confirmed prompt, `aura_recommend` turns it into a starter kit with links. Full clip in [`assets/`](assets/).*
 
----
-
+---
+
 
 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.
 
@@ -181,16 +185,17 @@ Start with `aura_status`, then `aura_search_all`. That order matters: status con
 
 Every row carries `page_url` (open it to see the design) and `author` where Aura credits one.
 
----
-
+---
+
 
 - **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.
 - **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.
 - **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.
 - **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.
+- **`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`.
+
+---
 
----
-
 
 > The fastest way to a shippable page. Two passes, one confirmation.
 
@@ -226,8 +231,8 @@ Sources: [tips-for-prompting](https://www.aura.build/learn/tips-for-prompting),
 [introduction](https://www.aura.build/learn/introduction),
 [design-systems](https://www.aura.build/design-systems).
 
----
-
+---
+
 
 New landing page, dark cinematic portfolio, SaaS pricing section. The shape is the same each time:
 
@@ -239,10 +244,10 @@ New landing page, dark cinematic portfolio, SaaS pricing section. The shape is t
 
 Prompts that work well are in [SETUP.md](./SETUP.md#prompts-that-work).
 
----
-
+---
+
 
-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 `aura_install_component` refuses Pro ids instead of guessing. If Aura rotates its public key, set `AURA_SUPABASE_ANON_KEY` and rebuild; nothing else changes.
+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.
 
 Optional tuning (all with defaults):
 
@@ -260,8 +265,8 @@ Optional tuning (all with defaults):
 
 </details>
 
----
-
+---
+
 
 ```bash
 npm test      # hermetic tests, no network
@@ -271,8 +276,8 @@ npm run build   # rebundle src/*.mjs into dist/server.js
 
 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.
 
----
-
+---
+
 
 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](./DIRECTION.md) for where this is headed.
 
@@ -285,8 +290,8 @@ npx -y aura-components-mcp@latest
 https://github.com/swastiksingh-dev/Aura-Components-MCP
 ```
 
----
-
+---
+
 
 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.
 
@@ -300,7 +305,7 @@ Server code by [swastiksingh-dev](https://github.com/swastiksingh-dev), MIT. Fre
 | [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 |
 | Upstream libraries (Tailwind CSS, GSAP, Lenis, Iconify) | The code this server's guides point at | Each project's own license — check before shipping |
 
----
-
+---
+
 
 MIT — see [LICENSE](./LICENSE).

package/SETUP.md

@@ -1,6 +1,6 @@
 # Setup
 
-One server, every client below. No account, no key, nothing to log into. If Node 18+ runs `node ./dist/server.js`, the client can use this.
+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.
 
 Build once:
 
@@ -120,7 +120,7 @@ Transport is stdio, no auth. Command `node`, args `["/absolute/path/to/aura-comp
 
 ## Troubleshooting
 
-- Server exits instantly: check `node --version` (needs 18+), then `npm run build` again.
+- Server exits instantly: check `node --version` (needs 22+), then `npm run build` again.
 - Client shows 0 tools: absolute path wrong, or the client needs a restart after config edit.
 - `upstream` errors on every call: outbound network blocked. `npm run verify` from the same machine tells you in seconds.
 - Counts look stale: 60-second cache. Wait a minute or set `AURA_CACHE_TTL_MS=0`.

package/dist/server.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// aura-components-mcp v1.7.0 — bundled (zero deps). Built by swastiksingh-dev.
+// aura-components-mcp v1.7.1 — bundled (zero deps). Built by swastiksingh-dev.
 
 // ---- config.mjs ----
 // Module: config — one small interface (loadConfig) over all env parsing.
@@ -30,7 +30,7 @@ function loadConfig(env = process.env) {
     codeChars: num(env.AURA_CODE_CHARS, 12_000, { min: 1_000, max: 60_000 }),
     contentChars: num(env.AURA_CONTENT_CHARS, 12_000, { min: 1_000, max: 60_000 }),
     freeOnlyDefault: bool(env.AURA_FREE_ONLY_DEFAULT, true),
-    userAgent: env.AURA_USER_AGENT ?? "aura-components-mcp/1.7.0",
+    userAgent: env.AURA_USER_AGENT ?? "aura-components-mcp/1.7.1",
   };
 }
 
@@ -59,6 +59,9 @@ function createFetcher({ fetchImpl, timeoutMs, retries, userAgent }) {
   }
 
   // GET JSON over PostgREST. Returns { rows, total } (total from content-range).
+  // Retryable: 429/5xx, network errors, timeouts (except AbortError: hung
+  // requests are not retried). Non-retryable: other 4xx (invalid requests
+  // never succeed on retry) — thrown immediately with noRetry set.
   async function getJson(url, headers) {
     let lastErr;
     for (let attempt = 0; attempt <= retries; attempt++) {
@@ -68,7 +71,9 @@ function createFetcher({ fetchImpl, timeoutMs, retries, userAgent }) {
           lastErr = new Error("transient upstream status " + res.status);
         } else if (!res.ok) {
           const body = await res.text().catch(() => "");
-          throw new Error("upstream " + res.status + ": " + body.slice(0, 300));
+          const e = new Error("upstream " + res.status + ": " + body.slice(0, 300));
+          if (res.status >= 400 && res.status < 500) e.noRetry = true;
+          throw e;
         } else {
           const range = res.headers?.get?.("content-range") ?? null;
           const total = range && range.includes("/") ? Number(range.split("/").pop()) : null;
@@ -76,8 +81,8 @@ function createFetcher({ fetchImpl, timeoutMs, retries, userAgent }) {
           return { rows: Array.isArray(rows) ? rows : [rows], total: Number.isFinite(total) ? total : null };
         }
       } catch (err) {
+        if (err && (err.noRetry || err.name === "AbortError")) throw err;
         lastErr = err;
-        if (err && err.name === "AbortError") break; // timeout: retrying rarely helps
       }
       if (attempt < retries) await sleep(120 * 2 ** attempt + Math.floor(Math.random() * 60));
     }
@@ -280,6 +285,39 @@ function slimRows(kind, items) {
   });
 }
 
+// Central access policy: only components/assets carry a premium flag, and a
+// row is free ⟺ premium === false (fail-closed: missing or ambiguous
+// entitlement is refused, never assumed public). Skills/design_systems
+// have no premium concept and are always allowed. Every retrieval path
+// (getItem, and therefore bundle/bulk/scaffold/related/install) funnels
+// through assertFreeRow, so callers cannot reach restricted content by ID.
+function isFreeRow(kind, row) {
+  if (kind !== "components" && kind !== "assets") return true;
+  return !!row && row.premium === false;
+}
+
+function assertFreeRow(kind, row) {
+  if (isFreeRow(kind, row)) return;
+  const what = kind === "assets" ? "asset" : "component";
+  const e = new Error("that " + what + " is Pro (paid). Search with freeOnly or pick a free one.");
+  e.code = "BAD_ARGS";
+  throw e;
+}
+
+// Row-shape gate: the minimum fields every surface needs to build a usable
+// item (identity for page_url + title for display/matching). Rows that fail
+// are upstream schema drift, not empty results: listings disclose them via
+// malformed_dropped, single-record fetch fails loud. Never silently shaped
+// into "undefined" URLs or untitled items.
+function isWellFormedRow(kind, row) {
+  if (!row || typeof row !== "object") return false;
+  if (typeof row.title !== "string" || !row.title) return false;
+  const hasId = row.id !== undefined && row.id !== null;
+  const hasSlug = typeof row.slug === "string" && !!row.slug;
+  if (kind === "components" || kind === "design_systems") return hasId || hasSlug;
+  return hasId;
+}
+
 function pageUrl(kind, row) {
   if (kind === "components") return SITE + "/component/" + row.slug;
   if (kind === "skills") return SITE + "/skills/" + row.id;
@@ -364,7 +402,7 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
   const authorCache = new Map(); // created_by -> profile (shared across searches)
   const inflight = new Map(); // cacheKey -> Promise (coalesce concurrent identical calls)
 
-  const clampLimit = (l) => Math.min(config.maxLimit, Math.max(1, l ?? config.defaultLimit));
+  const clampLimit = (l) => Math.min(config.maxLimit, Math.max(1, Math.floor(l ?? config.defaultLimit)));
 
   async function enrichAuthors(rows) {
     const ids = [...new Set(rows.map((r) => r.created_by).filter(Boolean).filter((id) => !authorCache.has(id)))];
@@ -384,12 +422,15 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
     const sort = CATALOG_SORTS[kind][q.sort] ? q.sort : "popular";
     const freeOnly = q.freeOnly ?? config.freeOnlyDefault;
     // Gap 1: negative_theme (exclude a theme) + min_views (quality floor). Both ride
-    // the cache key so filtered/unfiltered variants never collide.
+    // the cache key so filtered/unfiltered variants never collide. Explicit
+    // theme also rides the key: it re-ranks results, so dark/light variants
+    // must never share a cache entry or an in-flight request.
+    const themeKey = q.theme ? String(q.theme).toLowerCase() : "";
     const negTheme = q.negative_theme ? String(q.negative_theme).toLowerCase() : "";
     const minViews = Math.max(0, q.min_views ?? 0);
     const slim = q.slim ?? true;
     const exactFlag = q.exact_match === true ? "exact" : "fuzzy";
-    const key = ["search", kind, q.query ?? "", q.tag ?? "", q.mediaType ?? "", sort, limit, offset, freeOnly, negTheme, minViews, slim ? "slim" : "full", exactFlag].join("|");
+    const key = ["search", kind, q.query ?? "", q.tag ?? "", q.mediaType ?? "", sort, limit, offset, freeOnly, themeKey, negTheme, minViews, slim ? "slim" : "full", exactFlag].join("|");
     const hit = cacheGet(key);
     if (hit) return { ...hit, cached: true };
     if (inflight.has(key)) return inflight.get(key);
@@ -490,11 +531,28 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
         } catch { /* snippets are best-effort; rows still return */ }
       }
       const enriched = await enrichAuthors(rows);
-      const out = { kind, total, limit, offset, items: enriched.map((r) => shapeRow(kind, r, config, facetsFn)), cached: false };
+      // Schema-drift gate: malformed rows are disclosed, never shaped into
+      // untitled items or ".../undefined" page URLs, and never counted as
+      // successful empty results (total keeps its upstream meaning).
+      const formed = [];
+      let malformed = 0;
+      for (const r of enriched) {
+        if (isWellFormedRow(kind, r)) formed.push(r);
+        else malformed++;
+      }
+      const out = { kind, total, limit, offset, items: formed.map((r) => shapeRow(kind, r, config, facetsFn)), cached: false };
+      if (malformed) out.malformed_dropped = malformed;
       if (deduped) out.deduped = deduped;
       // Gap 1: min_views quality floor (views-gated surfaces only) + negative_theme
       // hard exclusion. Both apply before theme re-rank so counts stay honest.
-      if (minViews > 0) out.items = out.items.filter((it) => (it.views || 0) >= minViews);
+      // total keeps its upstream meaning (all matches for limit/offset paging);
+      // local drops are disclosed via min_views_filtered_out / deduped /
+      // negative_theme_filtered_out instead of rewriting total.
+      if (minViews > 0) {
+        const beforeViews = out.items.length;
+        out.items = out.items.filter((it) => (it.views || 0) >= minViews);
+        if (out.items.length < beforeViews) out.min_views_filtered_out = beforeViews - out.items.length;
+      }
       if (negTheme && kind === "components") {
         const before = out.items.length;
         out.items = out.items.filter((it) => !it.facets || it.facets.theme !== negTheme);
@@ -580,6 +638,8 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
     const url = base + "/rest/v1/" + kind + "?select=" + encodeURIComponent(sel) + "&" + filt + "&limit=1";
     const { rows } = await fetcher.getJson(url, headers);
     if (!rows.length) { const e = new Error("not found: " + kind + " " + idOrSlug); e.code = "NOT_FOUND"; throw e; }
+    assertFreeRow(kind, rows[0]); // before enrich/cache: refusals are never cached
+    if (!isWellFormedRow(kind, rows[0])) throw new Error("malformed upstream row for " + kind + " " + idOrSlug + ": missing identity/title fields");
     const enriched = await enrichAuthors(rows);
     const full = enriched[0];
     // Chunked fetch: re-slice full blobs per requested chunk so agents can page
@@ -690,13 +750,15 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
     try {
       const { rows } = await fetcher.getJson(url, headers);
       const enriched = await enrichAuthors(rows);
-      return enriched.map((r) => slimRows("components", [shapeRow("components", r, config, facetsFn)])[0]);
+      return enriched.filter((r) => isWellFormedRow("components", r)).map((r) => slimRows("components", [shapeRow("components", r, config, facetsFn)])[0]);
     } catch { return []; }
   }
 
   // Bulk fetch: N details in one parallel round (backs aura_bundle + aura_scaffold_page).
-  // Per-id errors are captured, never thrown: { ok:true, item } or { ok:false, id, error }.
-  async function bundleItems(kind, ids, max = 5, opts = {}) {
+  // Limit is 8 end-to-end (matches normRefs validation and the 2–8 docs):
+  // duplicates collapse to one fetch, order follows the request, and
+  // per-id errors are captured, never thrown: { ok:true, item } or { ok:false, id, error }.
+  async function bundleItems(kind, ids, max = 8, opts = {}) {
     const list = [...new Set((ids || []).map(String))].slice(0, Math.max(1, Math.min(max, 8)));
     const out = await Promise.all(list.map(async (id) => {
       try { const got = await getItem(kind, id, { full: !!opts.full }); return { ok: true, id, item: got.item }; }
@@ -722,7 +784,8 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
     try {
       const { rows } = await fetcher.getJson(url, headers);
       const enriched = await enrichAuthors(rows);
-      return { item: shapeRow(kind, item, config), related: slimRows(kind, enriched.map((r) => shapeRow(kind, r, config))) };
+      const wellFormed = enriched.filter((r) => isWellFormedRow(kind, r));
+      return { item: shapeRow(kind, item, config), related: slimRows(kind, wellFormed.map((r) => shapeRow(kind, r, config))) };
     } catch { return { item: shapeRow(kind, item, config), related: [] }; }
   }
 
@@ -730,7 +793,7 @@ function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = nul
 }
 
 // ---- protocol.mjs ----
-const SERVER_INFO = { name: "aura-components-mcp", version: "1.7.0" };
+const SERVER_INFO = { name: "aura-components-mcp", version: "1.7.1" };
 // Module: protocol — stdio JSON-RPC framing + MCP handshake + error codes.
 // One interface: createSession(send) -> { dispatch(msg) }. No business logic.
 
@@ -1484,11 +1547,17 @@ function createIcons({ fetcher, now = () => Date.now() }) {
     if (hit) cache.delete(key);
 
     const tried = [];
+    let lastFetchErr = null;
     for (const c of iconCandidates(raw, source, style)) {
       let body = null;
       try {
         body = await fetcher.getText(c.url, {});
-      } catch {
+      } catch (e) {
+        // Network-level failure is not a miss: remember it, keep walking the
+        // chain in case only one host is down, and rethrow at the end if
+        // nothing else explains the failure (never disguise an outage as
+        // "not found").
+        lastFetchErr = e instanceof Error ? e : new Error(String(e));
         tried.push({ url: c.url, ok: false, why: "fetch-error" });
         continue;
       }
@@ -1510,6 +1579,7 @@ function createIcons({ fetcher, now = () => Date.now() }) {
       while (cache.size > ICON_MAX_KEYS) cache.delete(cache.keys().next().value);
       return out;
     }
+    if (lastFetchErr && tried.every((t) => t.why === "fetch-error")) throw lastFetchErr;
     iconMissing("icon not found: '" + raw + "' (" + source + "/" + style + ") — checked " + tried.length + " URLs; check spelling (FA names use dashes, e.g. 'arrow-down')");
   }
 
@@ -1744,7 +1814,7 @@ function createHandlers(catalog, icons, version) {
     aura_install_component: async (a) => { a = a || {}; const id = a.id !== undefined ? a.id : a.slug;
       if (id === undefined || (typeof id !== 'string' && typeof id !== 'number')) toolFn_bad('provide id (number) or slug (string)');
       const got = await catalog.getItem('components', id);
-      if (got.item && got.item.premium !== false) toolFn_bad('that component is Pro (paid). Search with freeOnly or pick a free one.');
+      // Pro refusal enforced centrally in catalog.getItem (fail-closed).
       const compInstall = installGuide('components', got.item);
       return textResult({ item: got.item, install: compInstall, docs_stamp: docsStampFor(compInstall.deps) }); },
     aura_install_skill: async (a) => { a = a || {}; if (typeof a.id !== 'string' || !a.id) toolFn_bad('id (string) is required');
@@ -1799,17 +1869,18 @@ function createHandlers(catalog, icons, version) {
       const compRefs = normRefs(a.components, 'components') || [];
       const full = a.full === undefined ? undefined : toolFn_bool(a.full, 'full');
       const fullOpt = full === undefined ? {} : { full };
-      const [sys, comps] = await Promise.all([
+      const [sys, bundle] = await Promise.all([
         sysRef ? catalog.getItem('design_systems', sysRef, fullOpt).catch(() => null) : catalog.searchCatalog('design_systems', { query: a.goal, limit: 1 }).then((r) => (r.items[0] ? { item: r.items[0] } : null)),
-        compRefs.length ? catalog.bundleItems('components', compRefs, 5, fullOpt).then((rs) => rs.filter((x) => x.ok).map((x) => x.item)) : catalog.searchCatalog('components', { query: a.goal, freeOnly: true, limit: 3 }).then((r) => r.items),
+        compRefs.length ? catalog.bundleItems('components', compRefs, 8, fullOpt).then((rs) => ({ items: rs.filter((x) => x.ok).map((x) => x.item), dropped: rs.filter((x) => !x.ok).length })) : catalog.searchCatalog('components', { query: a.goal, freeOnly: true, limit: 3 }).then((r) => ({ items: r.items, dropped: 0 })),
       ]);
+      const comps = bundle.items;
       // Pro guard: explicit-id bundles can name Pro rows — free flows never ship them.
       const freeComps = (comps || []).filter((c) => c && c.premium === false);
       const proFiltered = (comps || []).length - freeComps.length;
       const sysItem = sys && sys.item ? sys.item : null;
       const toks = sysItem ? tokenHints(sysItem.content || '') : { tokens: {}, css: '' };
       const { guides, combined_deps: deps, files } = combineScaffold(sysItem, freeComps);
-      return textResult({ goal: a.goal, order: ['1 tokens.css', '2 system preview_html', '3 component markup in listed order'], tokens_css: toks.css || '', system: sysItem, components: freeComps || [], guides, combined_deps: deps, files, docs_stamp: docsStampFor(deps), ...(proFiltered ? { pro_filtered_out: proFiltered, pro_note: 'Pro (paid) components were refused — free-only scaffold ships free rows.' } : {}), license_note: 'Markup and any pulled assets are all-rights-reserved per Aura Terms §4 — fine to prototype, check each page_url before commercial ship.' }); },
+      return textResult({ goal: a.goal, order: ['1 tokens.css', '2 system preview_html', '3 component markup in listed order'], tokens_css: toks.css || '', system: sysItem, components: freeComps || [], guides, combined_deps: deps, files, docs_stamp: docsStampFor(deps), ...(bundle.dropped ? { dropped_refs: bundle.dropped, dropped_note: 'Some requested refs resolved to missing or Pro (paid) components and were omitted — see per-id errors via aura_bundle.' } : {}), ...(proFiltered ? { pro_filtered_out: proFiltered, pro_note: 'Pro (paid) components were refused — free-only scaffold ships free rows.' } : {}), license_note: 'Markup and any pulled assets are all-rights-reserved per Aura Terms §4 — fine to prototype, check each page_url before commercial ship.' }); },
   };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aura-components-mcp",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Free-only MCP server for the Aura (aura.build) public catalogue: 2,495 components, 192 skills, 30,688 assets, 725 design systems. No login. Built by swastiksingh-dev.",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,7 @@
     "verify": "node ./scripts/verify.mjs"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "keywords": [
     "mcp",