aura-components-mcp 1.5.2

package/dist/server.js

@@ -0,0 +1,786 @@
+#!/usr/bin/env node
+// aura-components-mcp v1.0.0 — bundled (zero deps). Built by swastiksingh-dev.
+
+// ---- config.mjs ----
+// Module: config — one small interface (loadConfig) over all env parsing.
+// Callers learn one function; env names, defaults, and clamping live here.
+
+const num = (raw, fallback, { min = 1, max = 100 } = {}) => {
+  const n = Number.parseInt(String(raw ?? ""), 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, n));
+};
+
+const bool = (raw, fallback) => {
+  if (raw === undefined) return fallback;
+  return /^(1|true|yes|on)$/i.test(String(raw));
+};
+
+function loadConfig(env = process.env) {
+  const defaultKey =
+    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImhvaXJxcmtkZ2JtdnB3dXR3dXdqIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NDM2Nzc2NTAsImV4cCI6MjA1OTI1MzY1MH0._UsCSHsTELn7m54tOhX3ySm67WEhcyHAPbuxEQZsl3c";
+  return {
+    supabaseUrl: env.AURA_SUPABASE_URL ?? "https://hoirqrkdgbmvpwutwuwj.supabase.co",
+    anonKey: env.AURA_SUPABASE_ANON_KEY ?? defaultKey,
+    timeoutMs: num(env.AURA_TIMEOUT_MS, 12_000, { min: 1_000, max: 60_000 }),
+    retries: num(env.AURA_RETRIES, 2, { min: 0, max: 5 }),
+    cacheTtlMs: num(env.AURA_CACHE_TTL_MS, 60_000, { min: 0, max: 3_600_000 }),
+    defaultLimit: num(env.AURA_DEFAULT_LIMIT, 10, { min: 1, max: 50 }),
+    maxLimit: num(env.AURA_MAX_LIMIT, 25, { min: 1, max: 50 }),
+    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.0.0",
+  };
+}
+
+// ---- http.mjs ----
+// Module: http — one small interface (createFetcher) hiding timeout,
+// retry-with-backoff, error mapping, and the injectable fetch seam.
+// Tests inject a stub fetch; production passes globalThis.fetch.
+
+function createFetcher({ fetchImpl, timeoutMs, retries, userAgent }) {
+  if (typeof fetchImpl !== "function") throw new Error("fetchImpl must be a function");
+
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+  async function once(url, init) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(new Error("timeout after " + timeoutMs + "ms")), timeoutMs);
+    try {
+      return await fetchImpl(url, {
+        ...init,
+        signal: ctrl.signal,
+        headers: { "user-agent": userAgent, ...(init?.headers ?? {}) },
+      });
+    } finally {
+      clearTimeout(t);
+    }
+  }
+
+  // GET JSON over PostgREST. Returns { rows, total } (total from content-range).
+  async function getJson(url, headers) {
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const res = await once(url, { headers });
+        if (res.status === 429 || (res.status >= 500 && res.status < 600)) {
+          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));
+        } else {
+          const range = res.headers?.get?.("content-range") ?? null;
+          const total = range && range.includes("/") ? Number(range.split("/").pop()) : null;
+          const rows = await res.json();
+          return { rows: Array.isArray(rows) ? rows : [rows], total: Number.isFinite(total) ? total : null };
+        }
+      } catch (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));
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+  }
+
+  return { getJson };
+}
+
+// ---- catalog.mjs ----
+// Module: catalog — the deep module. Small interface (searchCatalog,
+// getItem, getStatus) over query building, caching, truncation, author
+// enrichment, and page-URL derivation. Adapters: PostgREST via fetcher.
+
+const SITE = "https://www.aura.build";
+
+const CATALOG_SORTS = {
+  components: { popular: "views.desc", recent: "created_at.desc", trending: "views.desc", updated: "updated_at.desc" },
+  skills: { popular: "views.desc", recent: "created_at.desc", trending: "views.desc", updated: "updated_at.desc" },
+  assets: { popular: "views.desc", recent: "created_at.desc", trending: "views.desc", updated: "updated_at.desc" },
+  design_systems: { popular: "views.desc", recent: "created_at.desc", trending: "views.desc", updated: "updated_at.desc" },
+};
+
+const LIST_COLS = {
+  // Lists exclude code (13KB/row): theme falls back to background + tags heuristics.
+  // Full code loads only on get/bundle, where facets recompute exactly.
+  components: "id,title,description,tags,premium,views,forks,slug,background,created_by,created_at,updated_at",
+  skills: "id,title,description,source_url,views,forks,featured,created_by,created_at,updated_at",
+  assets: "id,title,description,keywords,media_type,premium,views,forks,image_800w,video_url,video_poster_url,created_by,created_at",
+  design_systems: "id,slug,title,description,views,forks,featured,created_by,created_at,updated_at",
+};
+
+const DETAIL_COLS = {
+  components: "id,title,description,tags,code,premium,views,forks,slug,image_url,background,credit_name,credit_url,created_by,created_at,updated_at",
+  skills: "id,title,description,content,source_url,views,forks,featured,created_by,created_at,updated_at",
+  assets: "id,title,description,keywords,resolution,colors,media_type,premium,views,forks,image_320w,image_800w,image_1600w,image_3840w,image_original,image_url,video_url,video_poster_url,video_duration,slug,created_by,created_at,updated_at",
+  design_systems: "id,slug,title,description,content,preview_html,thumbnail_url,source_name,views,forks,featured,created_by,created_at,updated_at",
+};
+
+const esc = (s) => String(s).replaceAll('"', '""');
+const ilike = (v) => "*" + String(v).replaceAll("*", "").replaceAll(",", " ").trim() + "*";
+
+// Split a goal sentence into significant tokens for OR fallback (stop-word filtered).
+const STOP = new Set("a,an,the,for,with,and,or,of,to,in,on,my,new,free,dark,also,that,this,from,into,plus,vs,top,best,up".split(","));
+function queryTokens(q, max = 4) {
+  return String(q ?? "").toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).map((t) => t.trim()).filter((t) => t.length > 2 && !STOP.has(t)).slice(0, max);
+}
+
+function windowAgoIso(days) {
+  const d = new Date();
+  d.setDate(d.getDate() - days);
+  return d.toISOString();
+}
+function weekAgoIso() { return windowAgoIso(7); }
+function trendingIso() { return windowAgoIso(90); } // 7d window is empty: newest DS row is ~12 weeks old; 90d keeps "trending" meaningful
+
+function buildSearchParams(kind, q = {}) {
+  const p = new URLSearchParams();
+  p.set("select", LIST_COLS[kind]);
+  const limit = q.limit;
+  const offset = q.offset ?? 0;
+  p.set("limit", String(limit));
+  p.set("offset", String(offset));
+  const sort = CATALOG_SORTS[kind][q.sort] ?? CATALOG_SORTS[kind].popular;
+  p.set("order", sort);
+  const filters = [];
+  if (kind === "components" || kind === "assets") {
+    filters.push("private=eq.false");
+    if (q.freeOnly) filters.push("premium=eq.false");
+  } else if (kind === "skills" || kind === "design_systems") {
+    filters.push("private=eq.false");
+  }
+  if (q.tag && kind === "components") filters.push("tags=cs.{" + q.tag.toLowerCase() + "}");
+  if (q.mediaType && kind === "assets") filters.push("media_type=eq." + q.mediaType);
+  const ors = [];
+  if (q.query && q.query.trim()) {
+    const v = ilike(q.query);
+    if (kind === "components") ors.push("title.ilike." + v + ",description.ilike." + v);
+    else if (kind === "skills") ors.push("title.ilike." + v + ",description.ilike." + v);
+    else if (kind === "assets") ors.push("title.ilike." + v + ",description.ilike." + v);
+    else ors.push("title.ilike." + v + ",description.ilike." + v);
+  }
+  if (q.sort === "trending") filters.push("created_at=gte." + trendingIso());
+  return { params: p, filters, ors };
+}
+
+function buildUrl(base, table, params, filters, ors) {
+  let qs = params.toString();
+  for (const f of filters) qs += "&" + f;
+  if (ors.length) qs += "&or=(" + ors.join(",") + ")";
+  return base + "/rest/v1/" + table + "?" + qs;
+}
+
+const trunc = (s, n) => (s && s.length > n ? s.slice(0, n) + "…[truncated]" : s);
+
+function pageUrl(kind, row) {
+  if (kind === "components") return SITE + "/component/" + row.slug;
+  if (kind === "skills") return SITE + "/skills/" + row.id;
+  if (kind === "assets") return SITE + "/assets?q=" + encodeURIComponent(row.title ?? "");
+  return SITE + "/design-systems/" + (row.slug ?? row.id);
+}
+
+function shapeRow(kind, row, cfg, withFacets) {
+  const base = { ...row };
+  if (kind === "components" && typeof base.code === "string") { base.code_chars = base.code.length; base.code = trunc(base.code, cfg.codeChars); }
+  if (kind === "skills" && typeof base.content === "string") base.content = trunc(base.content, cfg.contentChars);
+  if (kind === "design_systems") {
+    if (typeof base.content === "string") base.content = trunc(base.content, cfg.contentChars);
+    if (typeof base.preview_html === "string") base.preview_html = trunc(base.preview_html, cfg.codeChars);
+  }
+  base.page_url = pageUrl(kind, row);
+  if (withFacets) { try { base.facets = withFacets(kind, base); } catch { /* facets never break rows */ } }
+  return base;
+}
+
+function createCatalog({ fetcher, config, now = () => Date.now(), facetsFn = null }) {
+  const base = config.supabaseUrl.replace(/\/$/, "");
+  const headers = { apikey: config.anonKey, Authorization: "Bearer " + config.anonKey, Prefer: "count=exact" };
+  const cache = new Map();
+  const MAX_KEYS = 300;
+  const cacheGet = (k) => {
+    if (!config.cacheTtlMs) return null;
+    const e = cache.get(k);
+    if (!e) return null;
+    if (now() - e.t > config.cacheTtlMs) { cache.delete(k); return null; }
+    cache.delete(k); cache.set(k, e); // LRU refresh
+    return e.v;
+  };
+  const cacheSet = (k, v) => {
+    if (!config.cacheTtlMs) return;
+    if (cache.has(k)) cache.delete(k);
+    cache.set(k, { t: now(), v });
+    while (cache.size > MAX_KEYS) cache.delete(cache.keys().next().value);
+  };
+  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));
+
+  async function enrichAuthors(rows) {
+    const ids = [...new Set(rows.map((r) => r.created_by).filter(Boolean).filter((id) => !authorCache.has(id)))];
+    if (ids.length) {
+      try {
+        const url = base + "/rest/v1/public_author_profiles?select=id,full_name,avatar_url,slug&id=in.(" + ids.map(esc).join(",") + ")";
+        const { rows: authors } = await fetcher.getJson(url, headers);
+        for (const a of authors) { authorCache.set(a.id, a); if (authorCache.size > 500) break; }
+      } catch { /* authors stay null, rows still return */ }
+    }
+    return rows.map((r) => ({ ...r, author: (r.created_by && authorCache.get(r.created_by)) || null }));
+  }
+
+  async function searchCatalog(kind, q = {}) {
+    const limit = clampLimit(q.limit);
+    const offset = Math.max(0, q.offset ?? 0);
+    const sort = CATALOG_SORTS[kind][q.sort] ? q.sort : "popular";
+    const freeOnly = q.freeOnly ?? config.freeOnlyDefault;
+    const key = ["search", kind, q.query ?? "", q.tag ?? "", q.mediaType ?? "", sort, limit, offset, freeOnly].join("|");
+    const hit = cacheGet(key);
+    if (hit) return { ...hit, cached: true };
+    if (inflight.has(key)) return inflight.get(key);
+    const p = (async () => {
+      const runOnce = async (qq) => {
+        const { params, filters, ors } = buildSearchParams(kind, { ...qq, limit, offset, sort, freeOnly });
+        const url = buildUrl(base, kind, params, filters, ors);
+        return fetcher.getJson(url, headers);
+      };
+      let { rows, total } = await runOnce(q);
+      let fallback = null;
+      // AND-phrase queries like "dark cinematic portfolio" match nothing literally:
+      // retry as OR over significant tokens so every surface degrades instead of emptying.
+      // Single-token queries that miss also retry bare (drops tag/media filters) + suggest queries.
+      const toks = (q.query && q.query.trim() && !q.tag) ? queryTokens(q.query) : [];
+      const suggest = (t) => {
+        const s = [];
+        if (t.length > 1) s.push(t.slice(0, Math.min(3, t.length)).join(" "));
+        for (const x of t.slice(0, 3)) s.push(x);
+        return [...new Set(s)].slice(0, 4);
+      };
+      if ((!rows || !rows.length) && toks.length) {
+        // Pass 1: OR over tokens, same filters (drops the AND-phrase requirement).
+        const orParts = [];
+        for (const t of toks) {
+          const v = ilike(t);
+          orParts.push("title.ilike." + v + ",description.ilike." + v);
+        }
+        const b1 = buildSearchParams(kind, { ...q, query: "", limit, offset, sort, freeOnly });
+        try {
+          const fb = await fetcher.getJson(buildUrl(base, kind, b1.params, b1.filters, orParts), headers);
+          if (fb.rows && fb.rows.length) { rows = fb.rows; total = fb.total; fallback = "or-tokens:" + toks.join(","); }
+        } catch { /* try pass 2 */ }
+        // Pass 2: still empty (e.g. trending window + rare tokens): drop sort window,
+        // keep OR tokens, rank by views. Guarantees aggregators return something useful.
+        if ((!rows || !rows.length)) {
+          const b2 = buildSearchParams(kind, { ...q, query: "", limit, offset, sort: "popular", freeOnly });
+          try {
+            const fb2 = await fetcher.getJson(buildUrl(base, kind, b2.params, b2.filters, orParts), headers);
+            if (fb2.rows && fb2.rows.length) { rows = fb2.rows; total = fb2.total; fallback = "or-tokens-unwindowed:" + toks.join(","); }
+          } catch { /* keep original empty result */ }
+        }
+      }
+      const enriched = await enrichAuthors(rows);
+      const out = { kind, total, limit, offset, items: enriched.map((r) => shapeRow(kind, r, config, facetsFn)), cached: false };
+      // Post-filter: theme (dark|light) is derived, not a column — filter shaped rows.
+      if (q.theme && (kind === "components")) {
+        const want = String(q.theme).toLowerCase();
+        out.items = out.items.filter((it) => (it.facets && it.facets.theme) === want);
+      }
+      if (fallback) out.fallback = fallback;
+      else if ((!rows || !rows.length) && toks.length) out.suggested_queries = suggest(toks);
+      cacheSet(key, out);
+      return out;
+    })();
+    inflight.set(key, p);
+    try { return await p; } finally { inflight.delete(key); }
+  }
+
+  async function getItem(kind, idOrSlug) {
+    const key = ["get", kind, String(idOrSlug)].join("|");
+    const hit = cacheGet(key);
+    if (hit) return { ...hit, cached: true };
+    const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(idOrSlug));
+    const isNum = /^\d+$/.test(String(idOrSlug));
+    const sel = DETAIL_COLS[kind];
+    // design_systems + skills: uuid id vs slug; components: numeric id vs slug
+    const filt = (kind === "design_systems" || kind === "skills")
+      ? (isUuid ? "id=eq." + encodeURIComponent(String(idOrSlug)) : "slug=eq." + encodeURIComponent(String(idOrSlug)))
+      : (kind === "components" && !isNum
+        ? "slug=eq." + encodeURIComponent(String(idOrSlug))
+        : "id=eq." + encodeURIComponent(String(idOrSlug)));
+    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; }
+    const enriched = await enrichAuthors(rows);
+    const out = { kind, item: shapeRow(kind, enriched[0], config, facetsFn), cached: false };
+    cacheSet(key, out);
+    return out;
+  }
+
+  async function getStatus() {
+    const key = "status";
+    const hit = cacheGet(key);
+    if (hit) return { ...hit, cached: true };
+    const counts = {};
+    const jobs = [
+      ["components_free", "components?select=id&private=eq.false&premium=eq.false&limit=1"],
+      ["components_pro", "components?select=id&private=eq.false&premium=eq.true&limit=1"],
+      ["skills", "skills?select=id&private=eq.false&limit=1"],
+      ["assets", "assets?select=id&private=eq.false&limit=1"],
+      ["design_systems", "design_systems?select=id&private=eq.false&limit=1"],
+    ];
+    await Promise.all(jobs.map(async ([k, path]) => {
+      try { const { total } = await fetcher.getJson(base + "/rest/v1/" + path, headers); counts[k] = total; }
+      catch { counts[k] = null; }
+    }));
+    const out = { site: SITE, catalogue: "aura.build public catalogue (PostgREST, anon)", counts, cached: false };
+    cacheSet(key, out);
+    return out;
+  }
+
+  async function categoryCounts() {
+    const key = 'categories';
+    const hit = cacheGet(key);
+    if (hit) return hit.categories;
+    const cats = ['hero','section','button','card','background','header','logo','feature','pricing','testimonial','footer','form','heading'];
+    const out = await Promise.all(cats.map(async (c) => {
+      try {
+        const url = base + '/rest/v1/components?select=id&private=eq.false&premium=eq.false&tags=cs.{' + c + '}&limit=1';
+        const { total } = await fetcher.getJson(url, headers);
+        return { category: c, free: total };
+      } catch { return { category: c, free: null }; }
+    }));
+    cacheSet(key, { categories: out });
+    return out;
+  }
+
+  // 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) {
+    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); return { ok: true, id, item: got.item }; }
+      catch (e) { return { ok: false, id, error: (e && e.code === "NOT_FOUND") ? "not found" : String((e && e.message) || e).slice(0, 160) }; }
+    }));
+    return out;
+  }
+
+  // Related: same-tag / same-text overlap, views-ranked, excluding self.
+  async function relatedItems(kind, idOrSlug, limit = 3) {
+    const got = await getItem(kind, idOrSlug);
+    const item = got.item;
+    const toks = queryTokens(item.title + " " + (item.description || "")).slice(0, 3);
+    const orParts = toks.map((t) => { const v = ilike(t); return "title.ilike." + v + ",description.ilike." + v; });
+    const tagF = (kind === "components" && item.tags && item.tags.length) ? "&tags=cs.{" + String(item.tags[0]).toLowerCase() + "}" : "";
+    const lim = Math.max(1, Math.min(limit || 3, 8));
+    const sel = LIST_COLS[kind];
+    const idCol = (kind === "components") ? "id" : "id";
+    const selfId = encodeURIComponent(String(item.id));
+    const url = base + "/rest/v1/" + kind + "?select=" + encodeURIComponent(sel) + "&private=eq.false" + (kind === "components" || kind === "assets" ? "" : "") + tagF + "&" + idCol + "=neq." + selfId + (orParts.length ? "&or=(" + orParts.join(",") + ")" : "") + "&order=views.desc&limit=" + lim;
+    try {
+      const { rows } = await fetcher.getJson(url, headers);
+      const enriched = await enrichAuthors(rows);
+      return { item: shapeRow(kind, item, config), related: enriched.map((r) => shapeRow(kind, r, config)) };
+    } catch { return { item: shapeRow(kind, item, config), related: [] }; }
+  }
+
+  return { searchCatalog, getItem, getStatus, categoryCounts, bundleItems, relatedItems };
+}
+
+// ---- protocol.mjs ----
+// Module: protocol — stdio JSON-RPC framing + MCP handshake + error codes.
+// One interface: createSession(send) -> { dispatch(msg) }. No business logic.
+
+const SERVER_INFO = { name: "aura-components-mcp", version: "1.0.0" };
+const PROTOCOL_VERSION = "2024-11-05";
+
+const protocolFn_err = (code, message, data) => ({ code, message, ...(data === undefined ? {} : { data }) });
+const Errors = {
+  parse: (m) => protocolFn_err(-32700, "Parse error" + (m ? ": " + m : "")),
+  invalidRequest: (m) => protocolFn_err(-32600, "Invalid Request" + (m ? ": " + m : "")),
+  methodNotFound: (m) => protocolFn_err(-32601, "Method not found: " + m),
+  invalidParams: (m) => protocolFn_err(-32602, "Invalid params" + (m ? ": " + m : "")),
+  upstream: (m) => protocolFn_err(-32000, "Upstream error" + (m ? ": " + m : "")),
+  notFound: (m) => protocolFn_err(-32004, m || "Not found"),
+};
+
+function textResult(obj) {
+  return { content: [{ type: "text", text: JSON.stringify(obj, null, 2) }] };
+}
+
+function createSession(send, { tools, handlers }) {
+  let initialized = false;
+  const ok = (id, result) => send({ jsonrpc: "2.0", id, result });
+  const fail = (id, e) => send({ jsonrpc: "2.0", id, error: e });
+
+  async function dispatch(msg) {
+    if (!msg || typeof msg !== "object" || msg.jsonrpc !== "2.0") {
+      if (msg && "id" in msg && msg.id !== undefined && msg.id !== null) fail(msg.id, Errors.invalidRequest("bad envelope"));
+      return;
+    }
+    const { id, method, params } = msg;
+    const isCall = id !== undefined && id !== null;
+    try {
+      if (method === "initialize") {
+        initialized = true;
+        if (!isCall) return;
+        return ok(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });
+      }
+      if (method === "notifications/initialized") return;
+      if (method === "ping") { if (isCall) return ok(id, {}); return; }
+      if (!initialized) { if (isCall) fail(id, Errors.invalidRequest("not initialized")); return; }
+      if (method === "tools/list") { if (isCall) return ok(id, { tools }); return; }
+      if (method === "tools/call") {
+        if (!isCall) return;
+        const name = params?.name;
+        const args = params?.arguments ?? {};
+        const h = handlers[name];
+        if (!h) return fail(id, Errors.methodNotFound("tool " + name));
+        try {
+          const result = await h(args);
+          return ok(id, result);
+        } catch (e) {
+          if (e && e.code === "NOT_FOUND") return fail(id, Errors.notFound(e.message));
+          if (e && e.code === "BAD_ARGS") return fail(id, Errors.invalidParams(e.message));
+          return fail(id, Errors.upstream(e?.message ?? String(e)));
+        }
+      }
+      if (isCall) return fail(id, Errors.methodNotFound(method));
+    } catch (e) {
+      if (isCall) fail(id, Errors.upstream(e?.message ?? String(e)));
+    }
+  }
+
+  return { dispatch };
+}
+
+// ---- guide.mjs ----
+// Module: guide — small interface (installGuide, tokenHints, detectNeeds)
+// turning raw catalogue rows into paste-ready help: setup steps, file map,
+// dependency list, token starter. Derived from row fields, no extra fetches.
+
+const GUIDE_CDN = {
+  tailwind: 'https://cdn.tailwindcss.com',
+  iconify: 'https://code.iconify.design/iconify-icon/1.0.7/iconify-icon.min.js',
+};
+
+function detectNeeds(code, tags) {
+  const c = String(code || '').toLowerCase();
+  const t = new Set((tags || []).map((x) => String(x).toLowerCase()));
+  const needsTailwind = c.includes('class=') || t.has('tailwind');
+  const needsIcons = c.includes('iconify') || c.includes('svg');
+  const needsKeyframes = c.includes('keyframes') || c.includes('animation:');
+  const fonts = new Set();
+  for (const m of c.matchAll(/font-([a-z0-9-]+)/g)) fonts.add(m[1]);
+  return { needsTailwind, needsIcons, needsKeyframes, fonts: [...fonts].slice(0, 6) };
+};
+
+// Facets: cheap derived signals so search lists answer "dark? heavy? pro?" without a get.
+// theme: dark|light|mixed|unknown from background field + code palette probes.
+// weight: code_chars bucket (s/m/l) so agents can prefer light embeds.
+function facets(kind, row) {
+  const f = {};
+  if (kind === 'components') {
+    const bg = String(row.background || '').toLowerCase();
+    const tags = (row.tags || []).map((x) => String(x).toLowerCase());
+    const code = String(row.code || '').toLowerCase();
+    const tagDark = tags.includes('dark');
+    const tagLight = tags.includes('light');
+    const darkHits = (code.match(/#0{3,6}\b|#1[0-9a-f]{5}\b|bg-black|bg-neutral-9|bg-zinc-9|bg-slate-9|text-white|slate-300/g) || []).length;
+    const lightHits = (code.match(/bg-white|bg-neutral-50|bg-slate-50|bg-gray-50|text-black|text-neutral-9/g) || []).length;
+    const bgDark = bg.includes('000') && !bg.includes('fff');
+    const bgLight = bg.includes('fff') && !bg.includes('000');
+    f.theme = bgDark || tagDark ? 'dark' : (bgLight || tagLight ? 'light' : (code ? (darkHits > lightHits * 2 ? 'dark' : (lightHits > darkHits * 2 ? 'light' : (darkHits || lightHits ? 'mixed' : 'unknown'))) : (tags.includes('saas') || tags.includes('minimal') ? 'light' : 'unknown')));
+    const n = String(row.code || '').length;
+    f.weight = n > 20000 ? 'l' : (n > 8000 ? 'm' : 's');
+    f.code_chars = n;
+    const needs = detectNeeds(row.code || '', row.tags || []);
+    f.needsTailwind = needs.needsTailwind;
+    f.needsIcons = needs.needsIcons;
+    f.fonts = needs.fonts;
+  }
+  if (kind === 'assets' || row.image_800w || row.image_original || row.video_url) {
+    // Resolved 2026-09-13 from primary source https://www.aura.build/terms §4-5:
+    // catalogue content is the exclusive property of DESIGNCODE IO PTE. LTD.;
+    // no per-asset license column exists, so commercial reuse needs Aura's permission.
+    f.license = 'all-rights-reserved (Aura Terms §4: DESIGNCODE IO PTE. LTD.) — personal/preview use via page_url; commercial reuse needs Aura permission (support@designcode.io)';
+    f.download = row.image_original || row.image_1600w || row.image_800w || row.video_url || null;
+    f.preview = row.image_800w || row.video_poster_url || null;
+  }
+  if (kind === 'design_systems') f.has_preview = Boolean(row.preview_html);
+  return f;
+}
+
+function installGuide(kind, row) {
+  const steps = [];
+  const files = [];
+  const deps = [];
+  const url = row.page_url || '';
+  if (kind === 'components') {
+    const needs = detectNeeds(row.code || '', row.tags || []);
+    if (needs.needsTailwind) {
+      deps.push({ name: 'tailwindcss', via: 'CDN or project setup', cdn: GUIDE_CDN.tailwind });
+      steps.push('Add the Tailwind CDN script to head for a quick preview, or paste the markup into a Tailwind project.');
+    }
+    if (needs.needsIcons) {
+      deps.push({ name: 'iconify-icon', via: 'CDN', cdn: GUIDE_CDN.iconify });
+      steps.push('Add the iconify-icon CDN script so the icon tags render.');
+    }
+    if (needs.needsKeyframes) steps.push('Keep the embedded style block with the markup: that is where the keyframes live.');
+    steps.push('Paste the markup where the section belongs and update the CTA link (it ships as #).');
+    if (url) steps.push('Preview first: ' + url);
+    files.push({ path: 'components/' + (row.slug || row.id) + '.html', contains: 'section markup plus its style block' });
+    if (needs.fonts.length) files.push({ path: 'styles/fonts.css', contains: 'font families referenced: ' + needs.fonts.join(', ') });
+    return { kind, title: row.title, page_url: url, free: row.premium === false, steps, deps, files, needs };
+  }
+  if (kind === 'skills') {
+    steps.push('Read the SKILL.md content from aura_get_skill first: it names its own triggers and pitfalls.');
+    steps.push('Save it as SKILL.md inside your agent skills folder so the agent can load it.');
+    if (row.source_url) steps.push('Upstream source: ' + row.source_url);
+    return { kind, title: row.title, page_url: url, steps, deps, files: [{ path: 'skills/' + row.id + '/SKILL.md', contains: 'full skill content' }] };
+  }
+  if (kind === 'design_systems') {
+    steps.push('Copy the DESIGN.md content into your repo as DESIGN.md and treat it as the source of truth.');
+    steps.push('Apply the color, type, and spacing tokens before copying any component markup.');
+    return { kind, title: row.title, page_url: url, steps, deps, files: [{ path: 'DESIGN.md', contains: 'tokens and rules' }] };
+  }
+  steps.push('Use the image_800w URL for previews and image_original for production.');
+  return { kind, title: row.title, page_url: url, steps, deps, files };
+};
+
+function tokenHints(content) {
+  const Q = String.fromCharCode(39);
+  const lines = String(content || '').split(Q + 'n' === Q + 'n' ? '\n' : '\n');
+  const get = (key) => {
+    const line = lines.find((l) => { const t = l.trim().toLowerCase(); return t === key + ':' || t.startsWith(key + ': ') || t.startsWith(key + ' :') || t.startsWith(key + ':\"') || t.startsWith(key + ":'"); });
+    if (!line) return null;
+    const t = line.trim();
+    const ci = t.toLowerCase().indexOf(key);
+    let v = t.slice(ci + key.length).trim();
+    if (v.startsWith(':')) v = v.slice(1).trim();
+    while (v.startsWith(Q) || v.startsWith('"')) v = v.slice(1);
+    while (v.endsWith(Q) || v.endsWith('"')) v = v.slice(0, -1);
+    return v.trim() || null;
+  };
+  const tokens = {
+    primary: get('primary'),
+    background: get('background'),
+    surface: get('surface'),
+    text: get('text-primary') || get('text_primary'),
+  };
+  const rows = Object.entries(tokens).filter((e) => e[1]).map((e) => '  --aura-' + e[0] + ': ' + e[1] + ';');
+  const css = rows.length ? ':root{' + '\n' + rows.join('\n') + '\n}' : '';
+  return { tokens, css };
+};
+
+// ---- tools.mjs ----
+// Module: tools — thin adapters. Each tool validates args at the seam,
+// calls one catalog/guide method, wraps textResult. No retries/caching here.
+
+
+const TOOL_KINDS = ['components', 'skills', 'assets', 'design_systems'];
+const TOOL_SORTS = ['popular', 'recent', 'trending', 'updated'];
+const TOOL_CATS = ['hero','section','button','card','background','header','logo','feature','pricing','testimonial','footer','form','heading'];
+
+function toolFn_bad(msg) { const e = new Error(msg); e.code = 'BAD_ARGS'; throw e; }
+function toolFn_str(v, name) { if (v !== undefined && typeof v !== 'string') toolFn_bad(name + ' must be a string'); return v; }
+function toolFn_num(v, name) { if (v !== undefined && typeof v !== 'number') toolFn_bad(name + ' must be a number'); return v; }
+function toolFn_bool(v, name) { if (v !== undefined && typeof v !== 'boolean') toolFn_bad(name + ' must be a boolean'); return v; }
+function toolFn_sort(v) { if (v !== undefined && !TOOL_SORTS.includes(v)) toolFn_bad('sort must be one of ' + TOOL_SORTS.join('|')); return v; }
+function theme(v) { if (v !== undefined && v !== 'dark' && v !== 'light') toolFn_bad('theme must be dark|light'); return v; }
+function idList(v, name) { if (v === undefined) return v; if (!Array.isArray(v) || !v.length || v.length > 8 || v.some((x) => typeof x !== 'string' && typeof x !== 'number')) toolFn_bad(name + ' must be an array of 1-8 ids'); return v; }
+function toolFn_cat(v) { if (v !== undefined && !TOOL_CATS.includes(v)) toolFn_bad('category must be one of ' + TOOL_CATS.join('|')); return v; }
+
+const TOOL_DEFS = [
+  { name: 'aura_status', description: 'Catalogue health plus free counts (components, skills, assets, design systems). Free only, no login. Start here.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  { name: 'aura_search_components', description: 'Search free Aura UI components (2,495). Text over title and description, optional category tag, theme dark|light filter, sorts. Items carry facets (theme/weight/needs).', inputSchema: { type: 'object', properties: { query: { type: 'string' }, category: { type: 'string', enum: TOOL_CATS }, theme: { type: 'string', enum: ['dark', 'light'] }, sort: { type: 'string', enum: TOOL_SORTS }, limit: { type: 'number' }, offset: { type: 'number' } }, additionalProperties: false } },
+  { name: 'aura_get_component', description: 'Full free component detail with HTML/Tailwind source, preview image, page URL. Numeric id or slug.', inputSchema: { type: 'object', properties: { id: {}, slug: { type: 'string' } }, additionalProperties: false } },
+  { name: 'aura_search_skills', description: 'Search free Aura agent skills (187). Metadata only; use aura_get_skill for the full SKILL.md content.', inputSchema: { type: 'object', properties: { query: { type: 'string' }, sort: { type: 'string', enum: TOOL_SORTS }, limit: { type: 'number' }, offset: { type: 'number' } }, additionalProperties: false } },
+  { name: 'aura_get_skill', description: 'Full free agent-skill content (SKILL.md body) plus source_url and page URL. Skill id.', inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false } },
+  { name: 'aura_search_assets', description: 'Search free Aura assets (images and video). Keywords, media_type image or video.', inputSchema: { type: 'object', properties: { query: { type: 'string' }, mediaType: { type: 'string', enum: ['image', 'video'] }, sort: { type: 'string', enum: TOOL_SORTS }, limit: { type: 'number' }, offset: { type: 'number' } }, additionalProperties: false } },
+  { name: 'aura_search_design_systems', description: 'Search free Aura DESIGN.md systems (725). Metadata only; use aura_get_design_system for content.', inputSchema: { type: 'object', properties: { query: { type: 'string' }, sort: { type: 'string', enum: TOOL_SORTS }, limit: { type: 'number' }, offset: { type: 'number' } }, additionalProperties: false } },
+  { name: 'aura_get_design_system', description: 'Full free DESIGN.md content plus preview_html, tokens, and page URL. System id or slug.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, slug: { type: 'string' } }, additionalProperties: false } },
+  { name: 'aura_search_all', description: 'One call across components, skills, assets, and design systems in parallel. Free only.', inputSchema: { type: 'object', properties: { query: { type: 'string' }, limit: { type: 'number' } }, additionalProperties: false } },
+  { name: 'aura_recommend', description: 'Starter kit for a goal: top free components, skills, design systems, and assets with page URLs and rationale.', inputSchema: { type: 'object', properties: { goal: { type: 'string' } }, required: ['goal'], additionalProperties: false } },
+  { name: 'aura_install_component', description: 'Paste-ready setup for a free component: dependency list, setup steps, file map, fonts. Goes beyond the official Aura MCP, which only reads project source.', inputSchema: { type: 'object', properties: { id: {}, slug: { type: 'string' } }, additionalProperties: false } },
+  { name: 'aura_install_skill', description: 'Save-and-load plan for a free skill: where to put SKILL.md per client plus upstream source.', inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false } },
+  { name: 'aura_use_design_system', description: 'Apply a free DESIGN.md system: token starter CSS plus copy order (tokens first, then markup).', inputSchema: { type: 'object', properties: { id: { type: 'string' }, slug: { type: 'string' } }, additionalProperties: false } },
+  { name: 'aura_trending', description: 'What is new and popular across the free catalogue: top components, skills, assets, design systems in one call.', inputSchema: { type: 'object', properties: { limit: { type: 'number' } }, additionalProperties: false } },
+  { name: 'aura_bundle', description: 'Bulk-fetch 2-8 component details in one call (ids or slugs). Per-item errors never fail the batch.', inputSchema: { type: 'object', properties: { ids: { type: 'array', items: {} }, slugs: { type: 'array', items: { type: 'string' } } }, additionalProperties: false } },
+  { name: 'aura_scaffold_page', description: 'One ordered page build: DESIGN.md tokens.css + system preview + component markup in dependency order, combined deps + files[]. Merges install_* + use_* in a single turn.', inputSchema: { type: 'object', properties: { goal: { type: 'string' }, system: { type: 'string' }, components: { type: 'array', items: {} } }, required: ['goal'], additionalProperties: false } },
+  { name: 'aura_related', description: 'More-like-this: 3 related items for a component/skill/design-system by tag + text overlap. Discovery never dead-ends.', inputSchema: { type: 'object', properties: { kind: { type: 'string', enum: ['components', 'skills', 'design_systems'] }, id: {} }, required: ['kind', 'id'], additionalProperties: false } },
+  { name: 'aura_bulk_fetch', description: 'Bulk-fetch 2-8 details in one call for components, design_systems, or assets. Alias-friendly name for aura_bundle. Per-item errors never fail the batch.', inputSchema: { type: 'object', properties: { kind: { type: 'string', enum: ['components', 'design_systems', 'assets'] }, ids: { type: 'array', items: {} } }, required: ['kind', 'ids'], additionalProperties: false } },
+  { name: 'aura_install_asset', description: 'Legal drop-in plan for an asset: direct download URL, preview URL, license (all-rights-reserved per Aura Terms §4 — check page before commercial use), suggested file path.', inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'], additionalProperties: false } },
+  { name: 'aura_categories', description: 'The 13 component categories with live free counts. Pick one, then search within it.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+];
+
+function createHandlers(catalog) {
+  const free = { freeOnly: true };
+  return {
+    aura_status: async () => textResult(await catalog.getStatus()),
+    aura_search_components: async (a) => { a = a || {}; return textResult(await catalog.searchCatalog('components', {
+      query: toolFn_str(a.query, 'query'), tag: toolFn_cat(a.category), freeOnly: true, theme: theme(a.theme),
+      sort: toolFn_sort(a.sort), limit: toolFn_num(a.limit, 'limit'), offset: toolFn_num(a.offset, 'offset'),
+    })); },
+    aura_get_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)');
+      return textResult(await catalog.getItem('components', id)); },
+    aura_search_skills: async (a) => { a = a || {}; return textResult(await catalog.searchCatalog('skills', {
+      query: toolFn_str(a.query, 'query'), sort: toolFn_sort(a.sort), limit: toolFn_num(a.limit, 'limit'), offset: toolFn_num(a.offset, 'offset'),
+    })); },
+    aura_get_skill: async (a) => { a = a || {}; if (typeof a.id !== 'string' || !a.id) toolFn_bad('id (string) is required');
+      return textResult(await catalog.getItem('skills', a.id)); },
+    aura_search_assets: async (a) => { a = a || {}; return textResult(await catalog.searchCatalog('assets', {
+      query: toolFn_str(a.query, 'query'),
+      mediaType: a.mediaType === undefined ? undefined : (a.mediaType === 'image' || a.mediaType === 'video' ? a.mediaType : toolFn_bad('mediaType must be image|video')),
+      freeOnly: true, sort: toolFn_sort(a.sort), limit: toolFn_num(a.limit, 'limit'), offset: toolFn_num(a.offset, 'offset'),
+    })); },
+    aura_search_design_systems: async (a) => { a = a || {}; return textResult(await catalog.searchCatalog('design_systems', {
+      query: toolFn_str(a.query, 'query'), sort: toolFn_sort(a.sort), limit: toolFn_num(a.limit, 'limit'), offset: toolFn_num(a.offset, 'offset'),
+    })); },
+    aura_get_design_system: async (a) => { a = a || {}; const id = a.id !== undefined ? a.id : a.slug;
+      if (typeof id !== 'string' || !id) toolFn_bad('provide id or slug (string)');
+      return textResult(await catalog.getItem('design_systems', id)); },
+    aura_search_all: async (a) => { a = a || {}; const query = toolFn_str(a.query, 'query'), limit = toolFn_num(a.limit, 'limit') || 5;
+      const r = await Promise.all([
+        catalog.searchCatalog('components', { query, freeOnly: true, limit }),
+        catalog.searchCatalog('skills', { query, limit }),
+        catalog.searchCatalog('assets', { query, freeOnly: true, limit }),
+        catalog.searchCatalog('design_systems', { query, limit }),
+      ]);
+      return textResult({ query: query || null, components: r[0], skills: r[1], assets: r[2], design_systems: r[3] }); },
+    aura_recommend: async (a) => { a = a || {}; if (typeof a.goal !== 'string' || !a.goal.trim()) toolFn_bad('goal (string) is required');
+      const r = await Promise.all([
+        catalog.searchCatalog('components', { query: a.goal, freeOnly: true, limit: 5 }),
+        catalog.searchCatalog('skills', { query: a.goal, limit: 5 }),
+        catalog.searchCatalog('assets', { query: a.goal, freeOnly: true, limit: 3 }),
+        catalog.searchCatalog('design_systems', { query: a.goal, limit: 3 }),
+      ]);
+      const pick = (x) => (x.items || []).slice(0, 3).map((i) => ({ title: i.title, page_url: i.page_url }));
+      return textResult({ goal: a.goal, freeOnly: true,
+        rationale: 'Top free catalogue hits per surface, ranked by Aura views. Open the page_url previews, then fetch full source or content for finalists.',
+        components: r[0], skills: r[1], assets: r[2], design_systems: r[3],
+        starter_kit: { components: pick(r[0]), skills: pick(r[1]), assets: pick(r[2]), design_systems: pick(r[3]) } }); },
+    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.');
+      return textResult({ item: got.item, install: installGuide('components', got.item) }); },
+    aura_install_skill: async (a) => { a = a || {}; if (typeof a.id !== 'string' || !a.id) toolFn_bad('id (string) is required');
+      const got = await catalog.getItem('skills', a.id);
+      return textResult({ item: got.item, install: installGuide('skills', got.item) }); },
+    aura_use_design_system: async (a) => { a = a || {}; const id = a.id !== undefined ? a.id : a.slug;
+      if (typeof id !== 'string' || !id) toolFn_bad('provide id or slug (string)');
+      const got = await catalog.getItem('design_systems', id);
+      return textResult({ item: got.item, install: installGuide('design_systems', got.item), tokens: tokenHints(got.item.content || '') }); },
+    aura_trending: async (a) => { a = a || {}; const limit = toolFn_num(a.limit, 'limit') || 5;
+      const r = await Promise.all([
+        catalog.searchCatalog('components', { freeOnly: true, sort: 'trending', limit }),
+        catalog.searchCatalog('skills', { sort: 'trending', limit }),
+        catalog.searchCatalog('assets', { freeOnly: true, sort: 'trending', limit }),
+        catalog.searchCatalog('design_systems', { sort: 'trending', limit }),
+      ]);
+      return textResult({ window: 'last 90 days by views (7-day seed is empty: newest catalogue rows are months old)', components: r[0], skills: r[1], assets: r[2], design_systems: r[3] }); },
+    aura_categories: async () => textResult({ categories: await catalog.categoryCounts() }),
+    aura_bundle: async (a) => { a = a || {}; const ids = idList(a.ids, 'ids') || idList(a.slugs, 'slugs');
+      if (!ids || !ids.length) toolFn_bad('provide ids (array of 1-8 numbers/strings) or slugs (array of strings)');
+      return textResult({ kind: 'components', results: await catalog.bundleItems('components', ids) }); },
+    aura_related: async (a) => { a = a || {}; const k = a.kind;
+      if (k !== 'components' && k !== 'skills' && k !== 'design_systems') toolFn_bad('kind must be components|skills|design_systems');
+      const id = a.id; if (typeof id !== 'string' && typeof id !== 'number') toolFn_bad('id is required');
+      return textResult(await catalog.relatedItems(k, id, 3)); },
+    aura_install_asset: async (a) => { a = a || {}; if (typeof a.id !== 'number') toolFn_bad('id (number) is required');
+      const got = await catalog.getItem('assets', a.id);
+      const it = got.item; const fx = (it.facets || {});
+      return textResult({ item: it, install: { kind: 'assets', title: it.title, page_url: it.page_url, license: fx.license || 'all-rights-reserved (Aura Terms §4)', terms_url: 'https://www.aura.build/terms', download: fx.download || null, preview: fx.preview || null, files: [{ path: 'assets/' + it.id + '-' + String(it.title || 'asset').toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40) + '.jpg', contains: 'downloaded original' }], steps: ['Check the license on the Aura asset page before commercial use — this server reports unknown, never assumes free-to-sell.', 'Download the download URL into the suggested path.', 'Use the preview URL for <img> srcset while drafting.'] } }); },
+    aura_bulk_fetch: async (a) => { a = a || {}; const kind = a.kind;
+      if (kind !== 'components' && kind !== 'design_systems' && kind !== 'assets') toolFn_bad('kind must be components|design_systems|assets');
+      const ids = idList(a.ids, 'ids');
+      if (!ids || !ids.length) toolFn_bad('provide ids (array of 1-8)');
+      return textResult({ kind, results: await catalog.bundleItems(kind, ids) }); },
+    aura_scaffold_page: async (a) => { a = a || {}; if (typeof a.goal !== 'string' || !a.goal.trim()) toolFn_bad('goal (string) is required');
+      const sysRef = (typeof a.system === 'string' && a.system) ? a.system : null;
+      const compRefs = idList(a.components, 'components') || [];
+      const [sys, comps] = await Promise.all([
+        sysRef ? catalog.getItem('design_systems', sysRef).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).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),
+      ]);
+      const sysItem = sys && sys.item ? sys.item : null;
+      const toks = sysItem ? tokenHints(sysItem.content || '') : { tokens: {}, css: '' };
+      const guides = (comps || []).map((c) => installGuide('components', c));
+      const deps = []; const seen = new Set();
+      for (const g of guides) for (const d of (g.deps || [])) if (!seen.has(d.name)) { seen.add(d.name); deps.push(d); }
+      const files = [{ path: 'styles/tokens.css', contains: 'tokens.css from use_design_system' }];
+      if (sysItem) files.push({ path: 'DESIGN.md', contains: 'system rules' });
+      for (const g of guides) for (const f of (g.files || [])) files.push(f);
+      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: comps || [], guides, combined_deps: deps, files }); },
+  };
+};
+
+// ---- server.mjs (main) ----
+// Module: server — composition root. Wires config -> fetcher -> catalog ->
+// tools -> protocol session over stdio. Only framing + wiring lives here.
+
+
+
+
+
+
+
+const config = loadConfig();
+const fetcher = createFetcher({ fetchImpl: globalThis.fetch, timeoutMs: config.timeoutMs, retries: config.retries, userAgent: config.userAgent });
+const catalog = createCatalog({ fetcher, config, facetsFn: facets });
+const handlers = createHandlers(catalog);
+
+let buffer = "";
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const { dispatch } = createSession(send, { tools: TOOL_DEFS, handlers });
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let i;
+  while ((i = buffer.indexOf("\n")) >= 0) {
+    const line = buffer.slice(0, i).trim();
+    buffer = buffer.slice(i + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); }
+    catch { send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }); continue; }
+    dispatch(msg);
+  }
+});
+process.stdin.on("end", () => process.exit(0));
+process.stdin.resume();
+
+// Startup cinematics live on stderr only: stdout is reserved for JSON-RPC.
+// Sequence: aura moment -> catalogue credit -> builder credit -> running.
+const BANNER = [
+  "  <<<  aura-components-mcp  >>>",
+  "  free Aura catalogue, every AI agent",
+];
+const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+const paint = (s) => process.stderr.write(s + "\n");
+async function typeLine(text, cps = 90) {
+  for (const ch of text) { process.stderr.write(ch); await sleepMs(1000 / cps); }
+  process.stderr.write("\n");
+}
+async function dots(label, n = 3) {
+  process.stderr.write(label);
+  for (let i = 0; i < n; i++) { await sleepMs(160); process.stderr.write("."); }
+  process.stderr.write("\n");
+}
+async function boot() {
+  if (process.env.AURA_QUIET === "1" || process.argv.includes("--quiet")) {
+    paint(SERVER_INFO.name + " v" + SERVER_INFO.version + " listening on stdio");
+    return;
+  }
+  for (const l of BANNER) paint(l);
+  await typeLine("starting your aura for designing...");
+  await dots("warming catalogue cache");
+  paint("catalogue credit: Aura (aura.build) — components, skills, assets, systems");
+  await sleepMs(180);
+  paint("built by swastiksingh-dev — free to use, MIT, no paywall");
+  await sleepMs(180);
+  paint(SERVER_INFO.name + " v" + SERVER_INFO.version + " running — 15 tools on stdio");
+}
+boot();