@fragments-sdk/mcp 0.5.5 → 0.5.7

package/dist/{chunk-WEHZRM4L.js → chunk-FEUUOMWK.js}

@@ -312,7 +312,7 @@ function estimateTokens(text) {
   return Math.ceil(text.length / 4);
 }
 
-// ../context/dist/chunk-HAJWPNLU.js
+// ../context/dist/chunk-NECSN43I.js
 var MCP_TOOL_DEFINITIONS = [
   {
     key: "discover",
@@ -352,9 +352,18 @@ var MCP_TOOL_DEFINITIONS = [
         type: "boolean",
         description: "If true, includes code examples for each variant"
       },
+      limit: {
+        type: "number",
+        description: "Maximum number of results to return (default: 10 for useCase mode)"
+      },
       includeRelations: {
         type: "boolean",
         description: "If true, includes component relationships"
+      },
+      verbosity: {
+        type: "string",
+        enum: ["compact", "standard", "full"],
+        description: 'Response detail level: "compact" (names only), "standard" (default), "full" (everything including code)'
       }
     }
   },
@@ -369,7 +378,7 @@ var MCP_TOOL_DEFINITIONS = [
       fields: {
         type: "array",
         items: { type: "string" },
-        description: 'Specific fields to return (e.g., ["meta", "usage.when", "contract.propsSummary", "props", "examples", "guidelines"]). If omitted, returns everything. Supports dot notation.'
+        description: 'Specific fields to return (e.g., ["meta", "guidelines.when", "contract.propsSummary", "props", "examples"]). If omitted, returns everything. Supports dot notation. Aliases: "usage" \u2192 "guidelines".'
       },
       variant: {
         type: "string",
@@ -382,6 +391,11 @@ var MCP_TOOL_DEFINITIONS = [
       maxLines: {
         type: "number",
         description: "Maximum lines per code example (truncates longer examples)"
+      },
+      verbosity: {
+        type: "string",
+        enum: ["compact", "standard", "full"],
+        description: 'Response detail level: "compact" (meta + prop names), "standard" (default), "full" (everything)'
       }
     },
     required: ["component"]
@@ -405,6 +419,15 @@ var MCP_TOOL_DEFINITIONS = [
       category: {
         type: "string",
         description: 'Filter by category (e.g., "authentication", "marketing", "dashboard", "settings", "ecommerce", "ai")'
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of blocks to return (default: all matching)"
+      },
+      verbosity: {
+        type: "string",
+        enum: ["compact", "standard", "full"],
+        description: 'Response detail level: "compact" (no code), "standard" (default, code preview for long blocks), "full" (full code)'
       }
     }
   },
@@ -419,6 +442,10 @@ var MCP_TOOL_DEFINITIONS = [
       search: {
         type: "string",
         description: 'Search token names (e.g., "accent", "hover", "padding")'
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of tokens to return per category (default: 25 for search, unlimited for category browsing)"
       }
     }
   },
@@ -429,6 +456,15 @@ var MCP_TOOL_DEFINITIONS = [
       useCase: {
         type: "string",
         description: 'What you want to implement (e.g., "login form", "data table with sorting", "streaming chat messages")'
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of components to return (default: 5)"
+      },
+      verbosity: {
+        type: "string",
+        enum: ["compact", "standard", "full"],
+        description: 'Response detail level: "compact" (names only), "standard" (default), "full" (all props + examples + full block code)'
       }
     },
     required: ["useCase"]
@@ -465,7 +501,7 @@ var MCP_TOOL_DEFINITIONS = [
       },
       variant: {
         type: "string",
-        description: "Variant name for compare mode"
+        description: "Variant name to render (uses the variant's render function from the fragment definition). Works in both render and compare modes."
       },
       threshold: {
         type: "number",
@@ -496,7 +532,7 @@ var MCP_TOOL_DEFINITIONS = [
   },
   {
     key: "graph",
-    description: 'Query the component relationship graph. Understand dependencies, impact analysis, composition trees, alternatives, and design system health. Use "health" for an overview, "dependencies"/"dependents" for direct relationships, "impact" for change analysis, "composition" for compound component trees.',
+    description: 'Query the component relationship graph. Understand dependencies, impact analysis, composition trees, alternatives, and design system health. Use "health" for an overview, "dependencies"/"dependents" for composition and declared relationships (not code-level imports), "impact" for change analysis, "composition" for compound component trees.',
     params: {
       mode: {
         type: "string",
@@ -737,9 +773,8 @@ function findFragmentsJson(startDir) {
   return found;
 }
 
-// src/search.ts
-var CONVEX_SEARCH_URL = "https://combative-jay-834.convex.site/search";
-var CONVEX_TIMEOUT_MS = 3e3;
+// src/orama-index.ts
+import { create, insertMultiple, search } from "@orama/orama";
 var SYNONYM_MAP = {
   "form": ["input", "field", "submit", "validation"],
   "input": ["form", "field", "text", "entry"],
@@ -759,8 +794,259 @@ var SYNONYM_MAP = {
   "chat": ["message", "conversation", "ai"],
   "table": ["data", "grid", "list", "rows"],
   "textarea": ["text", "input", "multiline", "area", "comment"],
-  "area": ["textarea", "multiline", "text"]
+  "area": ["textarea", "multiline", "text"],
+  "landing": ["page", "hero", "marketing", "section", "layout"],
+  "hero": ["landing", "marketing", "banner", "headline", "section"],
+  "marketing": ["landing", "hero", "pricing", "testimonial", "cta"],
+  "cta": ["marketing", "banner", "action", "button"],
+  "testimonial": ["marketing", "review", "quote", "feedback"],
+  "layout": ["stack", "grid", "box", "container", "page"],
+  "page": ["layout", "landing", "section", "container"],
+  "section": ["hero", "feature", "testimonial", "cta", "faq"],
+  "pricing": ["card", "plan", "tier", "marketing"],
+  "plan": ["pricing", "card", "tier", "subscription"],
+  "dashboard": ["metrics", "stats", "chart", "card", "grid"],
+  "metrics": ["dashboard", "stats", "progress", "number"],
+  "stats": ["metrics", "dashboard", "progress", "badge"],
+  "chart": ["dashboard", "metrics", "data", "graph"]
+};
+function expandQuery(query) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const expanded = new Set(terms);
+  for (const term of terms) {
+    const synonyms = SYNONYM_MAP[term];
+    if (synonyms) {
+      for (const syn of synonyms) expanded.add(syn);
+    }
+  }
+  return Array.from(expanded).join(" ");
+}
+function twoPassSearch(config) {
+  const { index, query, properties, boost, limit, kind } = config;
+  const baseConfig = {
+    mode: "fulltext",
+    properties,
+    boost,
+    limit
+  };
+  const originalTermsQuery = query.toLowerCase().split(/\s+/).filter(Boolean).join(" ");
+  const expandedQuery = expandQuery(query);
+  const originalResults = search(index, { term: originalTermsQuery, ...baseConfig, threshold: 0.8 });
+  const expandedResults = search(index, { term: expandedQuery, ...baseConfig, threshold: 1 });
+  const origHits = originalResults.hits;
+  const expHits = expandedResults.hits;
+  const scoreMap = /* @__PURE__ */ new Map();
+  for (const hit of origHits) {
+    scoreMap.set(hit.document.name, (hit.score || 0) * 2);
+  }
+  for (const hit of expHits) {
+    const name = hit.document.name;
+    const existing = scoreMap.get(name) ?? 0;
+    scoreMap.set(name, existing + (hit.score || 0));
+  }
+  const scored = [];
+  for (const [name, score] of scoreMap) {
+    if (score > 0) {
+      scored.push({ name, kind, rank: scored.length, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  scored.forEach((s, i) => {
+    s.rank = i;
+  });
+  return scored;
+}
+var componentSchema = {
+  name: "string",
+  description: "string",
+  category: "string",
+  tags: "string",
+  whenUsed: "string",
+  variants: "string",
+  status: "string"
+};
+function buildComponentIndex(fragments) {
+  const db = create({ schema: componentSchema, language: "english" });
+  const docs = fragments.map((f) => ({
+    name: f.meta.name,
+    description: f.meta.description ?? "",
+    category: f.meta.category ?? "",
+    tags: (f.meta.tags ?? []).join(" "),
+    whenUsed: (f.usage?.when ?? []).join(" "),
+    variants: f.variants.map((v) => `${v.name} ${v.description || ""}`).join(" "),
+    status: f.meta.status ?? "stable"
+  }));
+  insertMultiple(db, docs);
+  return db;
+}
+function searchComponents(query, index, fragments, limit = 50) {
+  const boostConfig = {
+    mode: "fulltext",
+    properties: ["name", "whenUsed", "description", "category", "tags", "variants"],
+    boost: {
+      name: 3,
+      whenUsed: 2.5,
+      description: 2,
+      category: 1.5,
+      tags: 1.5,
+      variants: 1
+    },
+    limit
+  };
+  const originalTermsList = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const originalTermsQuery = originalTermsList.join(" ");
+  const expandedQuery = expandQuery(query);
+  const originalResults = search(index, { term: originalTermsQuery, ...boostConfig, threshold: 0.8 });
+  const expandedResults = search(index, { term: expandedQuery, ...boostConfig, threshold: 1 });
+  const origHits = originalResults.hits;
+  const expHits = expandedResults.hits;
+  const scoreMap = /* @__PURE__ */ new Map();
+  for (const hit of origHits) {
+    scoreMap.set(hit.document.name, (hit.score || 0) * 2);
+  }
+  for (const hit of expHits) {
+    const name = hit.document.name;
+    const existing = scoreMap.get(name) ?? 0;
+    scoreMap.set(name, existing + (hit.score || 0));
+  }
+  const fragmentMap = /* @__PURE__ */ new Map();
+  for (const f of fragments) {
+    fragmentMap.set(f.meta.name.toLowerCase(), f);
+  }
+  const originalTermsSet = new Set(originalTermsList);
+  const scored = [];
+  for (const [name, rawScore] of scoreMap) {
+    let score = rawScore;
+    const nameLower = name.toLowerCase();
+    const fragment = fragmentMap.get(nameLower);
+    if (originalTermsSet.has(nameLower)) {
+      score += 25;
+    }
+    if (fragment) {
+      if (fragment.meta.status === "stable") score += 5;
+      else if (fragment.meta.status === "beta") score += 2;
+      if (fragment.meta.status === "deprecated") score -= 25;
+    }
+    if (score > 0) {
+      scored.push({ name, kind: "component", rank: scored.length, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  scored.forEach((s, i) => {
+    s.rank = i;
+  });
+  return scored;
+}
+var blockSchema = {
+  name: "string",
+  description: "string",
+  category: "string",
+  tags: "string",
+  components: "string"
+};
+function buildBlockIndex(blocks) {
+  const db = create({ schema: blockSchema, language: "english" });
+  const docs = blocks.map((b) => ({
+    name: b.name,
+    description: b.description ?? "",
+    category: b.category ?? "",
+    tags: (b.tags ?? []).join(" "),
+    components: b.components.join(" ")
+  }));
+  insertMultiple(db, docs);
+  return db;
+}
+function searchBlocks(query, index, limit = 50) {
+  return twoPassSearch({
+    index,
+    query,
+    properties: ["name", "description", "components", "tags", "category"],
+    boost: {
+      name: 3,
+      description: 2,
+      components: 1.5,
+      tags: 1.5,
+      category: 1.5
+    },
+    limit,
+    kind: "block"
+  });
+}
+var tokenSchema = {
+  name: "string",
+  category: "string",
+  description: "string"
 };
+function buildTokenIndex(tokenData) {
+  const db = create({ schema: tokenSchema, language: "english" });
+  const docs = [];
+  for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+    for (const token of tokens) {
+      docs.push({
+        name: token.name,
+        category: cat,
+        description: token.description ?? ""
+      });
+    }
+  }
+  insertMultiple(db, docs);
+  return db;
+}
+function searchTokens(query, index, limit = 50) {
+  return twoPassSearch({
+    index,
+    query,
+    properties: ["name", "category", "description"],
+    boost: {
+      name: 2.5,
+      category: 2,
+      description: 1.5
+    },
+    limit,
+    kind: "token"
+  });
+}
+var USE_CASE_TOKEN_CATEGORIES = {
+  "table": ["spacing", "borders", "surfaces", "text"],
+  "data": ["spacing", "borders", "surfaces"],
+  "grid": ["spacing", "layout"],
+  "form": ["spacing", "borders", "radius", "focus"],
+  "input": ["spacing", "borders", "radius", "focus"],
+  "card": ["surfaces", "shadows", "radius", "borders", "spacing"],
+  "button": ["colors", "radius", "spacing", "focus"],
+  "layout": ["spacing", "layout", "surfaces"],
+  "dashboard": ["spacing", "surfaces", "borders", "shadows"],
+  "chat": ["spacing", "surfaces", "radius", "shadows"],
+  "modal": ["shadows", "surfaces", "radius", "spacing"],
+  "dialog": ["shadows", "surfaces", "radius", "spacing"],
+  "navigation": ["spacing", "surfaces", "borders"],
+  "sidebar": ["spacing", "surfaces", "borders"],
+  "hero": ["spacing", "typography", "colors"],
+  "landing": ["spacing", "typography", "colors"],
+  "pricing": ["spacing", "surfaces", "borders", "radius"],
+  "auth": ["spacing", "borders", "radius", "focus"],
+  "login": ["spacing", "borders", "radius", "focus"],
+  "dark": ["colors", "surfaces"],
+  "theme": ["colors", "surfaces", "text"]
+};
+function extractTokenCategories(query) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const categories = /* @__PURE__ */ new Set();
+  for (const term of terms) {
+    const cats = USE_CASE_TOKEN_CATEGORIES[term];
+    if (cats) {
+      for (const cat of cats) categories.add(cat);
+    }
+  }
+  if (categories.size === 0) {
+    return ["spacing", "colors", "surfaces"];
+  }
+  return Array.from(categories);
+}
+
+// src/search.ts
+var CONVEX_SEARCH_URL = "https://combative-jay-834.convex.site/search";
+var CONVEX_TIMEOUT_MS = 3e3;
 async function searchConvex(query, apiKey, limit = 10, kind) {
   try {
     const controller = new AbortController();
@@ -789,94 +1075,17 @@ async function searchConvex(query, apiKey, limit = 10, kind) {
     return [];
   }
 }
-function keywordScoreComponents(query, fragments) {
-  const searchTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  const expandedTerms = new Set(searchTerms);
-  for (const term of searchTerms) {
-    const synonyms = SYNONYM_MAP[term];
-    if (synonyms) {
-      for (const syn of synonyms) expandedTerms.add(syn);
-    }
-  }
-  const scored = fragments.map((s) => {
-    let score = 0;
-    const nameLower = s.meta.name.toLowerCase();
-    if (searchTerms.some((term) => nameLower.includes(term))) {
-      score += 15;
-    } else if (Array.from(expandedTerms).some((term) => nameLower.includes(term))) {
-      score += 8;
-    }
-    const desc = s.meta.description?.toLowerCase() ?? "";
-    score += searchTerms.filter((term) => desc.includes(term)).length * 6;
-    const tags = s.meta.tags?.map((t) => t.toLowerCase()) ?? [];
-    score += searchTerms.filter((term) => tags.some((tag) => tag.includes(term))).length * 4;
-    const whenUsed = s.usage?.when?.join(" ").toLowerCase() ?? "";
-    score += searchTerms.filter((term) => whenUsed.includes(term)).length * 10;
-    score += Array.from(expandedTerms).filter((term) => !searchTerms.includes(term) && whenUsed.includes(term)).length * 5;
-    const cat = s.meta.category?.toLowerCase() ?? "";
-    if (searchTerms.some((term) => cat.includes(term))) {
-      score += 8;
-    }
-    const variantText = s.variants.map((v) => `${v.name} ${v.description || ""}`.toLowerCase()).join(" ");
-    score += searchTerms.filter((term) => variantText.includes(term)).length * 3;
-    if (s.meta.status === "stable") score += 5;
-    else if (s.meta.status === "beta") score += 2;
-    if (s.meta.status === "deprecated") score -= 25;
-    return { name: s.meta.name, kind: "component", score };
-  });
-  return scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score).map((s, i) => ({ ...s, rank: i }));
+function keywordScoreComponents(query, fragments, componentIndex) {
+  const index = componentIndex ?? buildComponentIndex(fragments);
+  return searchComponents(query, index, fragments);
 }
-function keywordScoreBlocks(query, blocks) {
-  const searchTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  const expandedTerms = new Set(searchTerms);
-  for (const term of searchTerms) {
-    const synonyms = SYNONYM_MAP[term];
-    if (synonyms) {
-      for (const syn of synonyms) expandedTerms.add(syn);
-    }
-  }
-  const scored = blocks.map((b) => {
-    let score = 0;
-    const nameLower = b.name.toLowerCase();
-    if (searchTerms.some((term) => nameLower.includes(term))) {
-      score += 15;
-    } else if (Array.from(expandedTerms).some((term) => nameLower.includes(term))) {
-      score += 8;
-    }
-    const desc = b.description.toLowerCase();
-    score += searchTerms.filter((term) => desc.includes(term)).length * 6;
-    const tags = b.tags?.map((t) => t.toLowerCase()) ?? [];
-    score += searchTerms.filter((term) => tags.some((tag) => tag.includes(term))).length * 4;
-    const componentText = b.components.join(" ").toLowerCase();
-    score += searchTerms.filter((term) => componentText.includes(term)).length * 5;
-    const cat = b.category.toLowerCase();
-    if (searchTerms.some((term) => cat.includes(term))) {
-      score += 8;
-    }
-    return { name: b.name, kind: "block", score };
-  });
-  return scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score).map((s, i) => ({ ...s, rank: i }));
+function keywordScoreBlocks(query, blocks, blockIndex) {
+  const index = blockIndex ?? buildBlockIndex(blocks);
+  return searchBlocks(query, index);
 }
-function keywordScoreTokens(query, tokenData) {
-  const searchTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  const scored = [];
-  for (const [cat, tokens] of Object.entries(tokenData.categories)) {
-    const catLower = cat.toLowerCase();
-    const catBonus = searchTerms.some((term) => catLower.includes(term)) ? 8 : 0;
-    for (const token of tokens) {
-      let score = catBonus;
-      const nameLower = token.name.toLowerCase();
-      score += searchTerms.filter((term) => nameLower.includes(term)).length * 10;
-      if (token.description) {
-        const descLower = token.description.toLowerCase();
-        score += searchTerms.filter((term) => descLower.includes(term)).length * 6;
-      }
-      if (score > 0) {
-        scored.push({ name: token.name, kind: "token", score });
-      }
-    }
-  }
-  return scored.sort((a, b) => b.score - a.score).map((s, i) => ({ ...s, rank: i }));
+function keywordScoreTokens(query, tokenData, tokenIndex) {
+  const index = tokenIndex ?? buildTokenIndex(tokenData);
+  return searchTokens(query, index);
 }
 function reciprocalRankFusion(resultSets, k = 60) {
   const scoreMap = /* @__PURE__ */ new Map();
@@ -906,13 +1115,13 @@ function reciprocalRankFusion(resultSets, k = 60) {
 async function hybridSearch(query, data, limit = 10, kind, apiKey) {
   const keywordResults = [];
   if (!kind || kind === "component") {
-    keywordResults.push(...keywordScoreComponents(query, data.fragments));
+    keywordResults.push(...keywordScoreComponents(query, data.fragments, data.componentIndex));
   }
   if ((!kind || kind === "block") && data.blocks) {
-    keywordResults.push(...keywordScoreBlocks(query, data.blocks));
+    keywordResults.push(...keywordScoreBlocks(query, data.blocks, data.blockIndex));
   }
   if ((!kind || kind === "token") && data.tokenData) {
-    keywordResults.push(...keywordScoreTokens(query, data.tokenData));
+    keywordResults.push(...keywordScoreTokens(query, data.tokenData, data.tokenIndex));
   }
   keywordResults.sort((a, b) => b.score - a.score);
   keywordResults.forEach((r, i) => {
@@ -962,6 +1171,78 @@ async function hybridSearch(query, data, limit = 10, kind, apiKey) {
   return fused.slice(0, limit);
 }
 
+// src/scoring.ts
+var MINIMUM_SCORE_THRESHOLD = 5;
+function assignConfidence(score, maxScore) {
+  if (maxScore <= 0) return "low";
+  const ratio = score / maxScore;
+  if (ratio >= 0.7) return "high";
+  if (ratio >= 0.4) return "medium";
+  return "low";
+}
+function meetsMinimumThreshold(maxScore) {
+  return maxScore >= MINIMUM_SCORE_THRESHOLD;
+}
+function levenshtein(a, b) {
+  const la = a.length;
+  const lb = b.length;
+  const dp = Array.from({ length: lb + 1 }, (_, i) => i);
+  for (let i = 1; i <= la; i++) {
+    let prev = i - 1;
+    dp[0] = i;
+    for (let j = 1; j <= lb; j++) {
+      const temp = dp[j];
+      dp[j] = a[i - 1] === b[j - 1] ? prev : 1 + Math.min(prev, dp[j], dp[j - 1]);
+      prev = temp;
+    }
+  }
+  return dp[lb];
+}
+function findClosestMatch(input, candidates, maxDistance = 3) {
+  const inputLower = input.toLowerCase();
+  let bestMatch = null;
+  let bestDist = maxDistance + 1;
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+    const dist = levenshtein(inputLower, candidateLower);
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestMatch = candidate;
+    } else if (dist === bestDist && bestMatch) {
+      const currentLenDiff = Math.abs(bestMatch.length - input.length);
+      const newLenDiff = Math.abs(candidate.length - input.length);
+      if (newLenDiff < currentLenDiff) {
+        bestMatch = candidate;
+      }
+    }
+  }
+  return bestDist <= maxDistance ? bestMatch : null;
+}
+var BLOCK_BOOST_PER_OCCURRENCE = 5;
+function buildBlockComponentFrequency(blocks) {
+  const freq = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    for (const comp of block.components) {
+      const key = comp.toLowerCase();
+      freq.set(key, (freq.get(key) ?? 0) + 1);
+    }
+  }
+  return freq;
+}
+function boostByBlockFrequency(results, freq) {
+  for (const result of results) {
+    const count = freq.get(result.name.toLowerCase()) ?? 0;
+    if (count > 0) {
+      result.score += count * BLOCK_BOOST_PER_OCCURRENCE;
+    }
+  }
+  results.sort((a, b) => b.score - a.score);
+  results.forEach((r, i) => {
+    r.rank = i;
+  });
+  return results;
+}
+
 // src/service.ts
 async function renderComponent(viewerUrl, request) {
   const renderUrl = `${viewerUrl}/fragments/render`;
@@ -971,6 +1252,7 @@ async function renderComponent(viewerUrl, request) {
     body: JSON.stringify({
       component: request.component,
       props: request.props ?? {},
+      variant: request.variant,
       viewport: request.viewport ?? { width: 800, height: 600 }
     })
   });
@@ -1001,7 +1283,9 @@ async function auditComponent(viewerUrl, request) {
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       component: request.component,
-      variant: request.variant
+      variant: request.variant,
+      standard: request.standard,
+      includeFixPatches: request.includeFixPatches
     })
   });
   const raw = await response.json();
@@ -1031,18 +1315,31 @@ async function auditComponent(viewerUrl, request) {
   }
   const deductions = totalCritical * 10 + totalSerious * 5 + totalModerate * 2 + totalMinor * 1;
   const score = Math.max(0, 100 - deductions);
+  const variantCount = results.length;
+  const aaPassCount = results.filter((r) => {
+    const critical = r.summary.critical;
+    const serious = r.summary.serious;
+    return critical === 0 && serious === 0;
+  }).length;
+  const aaaPassCount = results.filter((r) => {
+    const total = r.summary.critical + r.summary.serious + r.summary.moderate + r.summary.minor;
+    return total === 0;
+  }).length;
+  const totalPasses = results.reduce((sum, r) => sum + r.passes, 0);
   const totalViolations = totalCritical + totalSerious + totalModerate + totalMinor;
-  const aaPass = totalCritical === 0 && totalSerious === 0;
-  const aaaPass = totalViolations === 0;
-  const aaPercent = aaPass ? 100 : 0;
-  const aaaPercent = aaaPass ? 100 : 0;
+  const emptyAudit = results.length > 0 && totalPasses === 0 && totalViolations === 0;
+  const aaPercent = variantCount > 0 ? Math.round(aaPassCount / variantCount * 100) : 100;
+  const aaaPercent = variantCount > 0 ? Math.round(aaaPassCount / variantCount * 100) : 100;
+  const aaPass = !emptyAudit && totalCritical === 0 && totalSerious === 0;
+  const aaaPass = !emptyAudit && totalViolations === 0;
   const passed = standard === "AAA" ? aaaPass : aaPass;
   return {
     component: request.component,
     results,
-    score,
-    aaPercent,
-    aaaPercent,
+    score: emptyAudit ? 0 : score,
+    aaPercent: emptyAudit ? 0 : aaPercent,
+    aaaPercent: emptyAudit ? 0 : aaaPercent,
+    ...emptyAudit && { emptyAudit },
     passed,
     standard
   };
@@ -1081,7 +1378,7 @@ function projectFields(obj, fields) {
 }
 
 // src/graph-handler.ts
-function handleGraphTool(args, serializedGraph, blocks) {
+function handleGraphTool(args, serializedGraph, blocks, componentNames) {
   if (!serializedGraph) {
     return {
       text: JSON.stringify({
@@ -1109,7 +1406,7 @@ function handleGraphTool(args, serializedGraph, blocks) {
             compositionNote: "No composition blocks defined yet \u2014 compositionCoverage will increase as blocks are added"
           },
           summary: `${health.nodeCount} components, ${health.edgeCount} edges, ${health.connectedComponents.length} island(s), ${health.orphans.length} orphan(s), ${health.compositionCoverage}% in blocks`
-        }, null, 2)
+        })
       };
     }
     case "dependencies": {
@@ -1117,7 +1414,9 @@ function handleGraphTool(args, serializedGraph, blocks) {
         return { text: JSON.stringify({ error: "component is required for dependencies mode" }), isError: true };
       }
       if (!engine.hasNode(args.component)) {
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph` }), isError: true };
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
       }
       const deps = engine.dependencies(args.component, edgeTypes);
       return {
@@ -1132,7 +1431,7 @@ function handleGraphTool(args, serializedGraph, blocks) {
             note: e.note,
             provenance: e.provenance
           }))
-        }, null, 2)
+        })
       };
     }
     case "dependents": {
@@ -1140,7 +1439,9 @@ function handleGraphTool(args, serializedGraph, blocks) {
         return { text: JSON.stringify({ error: "component is required for dependents mode" }), isError: true };
       }
       if (!engine.hasNode(args.component)) {
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph` }), isError: true };
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
       }
       const deps = engine.dependents(args.component, edgeTypes);
       return {
@@ -1155,7 +1456,7 @@ function handleGraphTool(args, serializedGraph, blocks) {
             note: e.note,
             provenance: e.provenance
           }))
-        }, null, 2)
+        })
       };
     }
     case "impact": {
@@ -1163,7 +1464,9 @@ function handleGraphTool(args, serializedGraph, blocks) {
         return { text: JSON.stringify({ error: "component is required for impact mode" }), isError: true };
       }
       if (!engine.hasNode(args.component)) {
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph` }), isError: true };
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
       }
       const result = engine.impact(args.component, args.maxDepth ?? 3);
       return {
@@ -1171,7 +1474,7 @@ function handleGraphTool(args, serializedGraph, blocks) {
           mode: "impact",
           ...result,
           summary: `Changing ${args.component} affects ${result.totalAffected} component(s) and ${result.affectedBlocks.length} block(s)`
-        }, null, 2)
+        })
       };
     }
     case "path": {
@@ -1190,7 +1493,7 @@ function handleGraphTool(args, serializedGraph, blocks) {
             target: e.target,
             type: e.type
           }))
-        }, null, 2)
+        })
       };
     }
     case "composition": {
@@ -1198,14 +1501,16 @@ function handleGraphTool(args, serializedGraph, blocks) {
         return { text: JSON.stringify({ error: "component is required for composition mode" }), isError: true };
       }
       if (!engine.hasNode(args.component)) {
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph` }), isError: true };
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
       }
       const tree = engine.composition(args.component);
       return {
         text: JSON.stringify({
           mode: "composition",
           ...tree
-        }, null, 2)
+        })
       };
     }
     case "alternatives": {
@@ -1213,7 +1518,9 @@ function handleGraphTool(args, serializedGraph, blocks) {
         return { text: JSON.stringify({ error: "component is required for alternatives mode" }), isError: true };
       }
       if (!engine.hasNode(args.component)) {
-        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph` }), isError: true };
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
       }
       const alts = engine.alternatives(args.component);
       return {
@@ -1222,7 +1529,7 @@ function handleGraphTool(args, serializedGraph, blocks) {
           component: args.component,
           count: alts.length,
           alternatives: alts
-        }, null, 2)
+        })
       };
     }
     case "islands": {
@@ -1236,7 +1543,7 @@ function handleGraphTool(args, serializedGraph, blocks) {
             size: island.length,
             components: island
           }))
-        }, null, 2)
+        })
       };
     }
     default:
@@ -1251,7 +1558,7 @@ function handleGraphTool(args, serializedGraph, blocks) {
 
 // src/server.ts
 var TOOL_NAMES = buildToolNames(BRAND.nameLower);
-var NO_VIEWER_MSG = "This tool requires a running dev server. Pass --viewer-url to the MCP server, or use the fragments-dev MCP config which connects to your local dev server.";
+var NO_VIEWER_MSG = "This tool requires a running dev server. Add --viewer-url http://localhost:PORT to this server's config args. Start the viewer with 'fragments dev' in your component library directory.";
 var TOOLS = buildMcpTools(BRAND.nameLower);
 function createMcpServer(config) {
   const server = new Server(
@@ -1269,6 +1576,9 @@ function createMcpServer(config) {
   const fragmentPackageMap = /* @__PURE__ */ new Map();
   let defaultPackageName = null;
   let resolvedRoot = null;
+  let componentIndex = null;
+  let blockIndex = null;
+  let tokenIndex = null;
   async function resolveProjectRoot() {
     if (resolvedRoot) return resolvedRoot;
     try {
@@ -1326,6 +1636,15 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
         fragmentsData.blocks = { ...fragmentsData.blocks, ...extraBlocks };
       }
     }
+    const allFragments = Object.values(fragmentsData.fragments);
+    const allBlocks = Object.values(fragmentsData.blocks ?? fragmentsData.recipes ?? {});
+    componentIndex = buildComponentIndex(allFragments);
+    if (allBlocks.length > 0) {
+      blockIndex = buildBlockIndex(allBlocks);
+    }
+    if (fragmentsData.tokens && fragmentsData.tokens.total > 0) {
+      tokenIndex = buildTokenIndex(fragmentsData.tokens);
+    }
     return fragmentsData;
   }
   async function getPackageName(fragmentName) {
@@ -1355,8 +1674,15 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
     defaultPackageName = "your-component-library";
     return defaultPackageName;
   }
+  const VIEWER_TOOL_KEYS = /* @__PURE__ */ new Set(["render", "fix", "a11y"]);
   server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools: TOOLS };
+    if (config.viewerUrl) {
+      return { tools: TOOLS };
+    }
+    const availableTools = TOOLS.filter(
+      (t) => !VIEWER_TOOL_KEYS.has(t.name.replace(`${BRAND.nameLower}_`, ""))
+    );
+    return { tools: availableTools };
   });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
@@ -1370,15 +1696,28 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
           const useCase = args?.useCase ?? void 0;
           const componentForAlts = args?.component ?? void 0;
           const category = args?.category ?? void 0;
-          const search = args?.search?.toLowerCase() ?? void 0;
+          const search2 = args?.search?.toLowerCase() ?? void 0;
           const status = args?.status ?? void 0;
           const format = args?.format ?? "markdown";
           const compact = args?.compact ?? false;
           const includeCode = args?.includeCode ?? false;
           const includeRelations = args?.includeRelations ?? false;
-          if (compact || args?.format && !useCase && !componentForAlts && !category && !search && !status) {
-            const fragments2 = Object.values(data.fragments);
+          const limit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 25) : 10;
+          const verbosity = args?.verbosity ?? "standard";
+          if (compact || args?.format && !useCase && !componentForAlts) {
+            let fragments2 = Object.values(data.fragments);
             const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
+            if (category) {
+              fragments2 = fragments2.filter((f) => f.meta.category?.toLowerCase() === category);
+            }
+            if (search2) {
+              fragments2 = fragments2.filter(
+                (f) => f.meta.name.toLowerCase().includes(search2) || f.meta.description?.toLowerCase().includes(search2) || f.meta.tags?.some((t) => t.toLowerCase().includes(search2))
+              );
+            }
+            if (status) {
+              fragments2 = fragments2.filter((f) => f.meta.status === status);
+            }
             const { content: ctxContent, tokenEstimate } = generateContext(fragments2, {
               format,
               compact,
@@ -1400,9 +1739,19 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
             const localData = {
               fragments: allFragments,
               blocks: allBlocks,
-              tokenData: data.tokens
+              tokenData: data.tokens,
+              componentIndex: componentIndex ?? void 0,
+              blockIndex: blockIndex ?? void 0,
+              tokenIndex: tokenIndex ?? void 0
             };
-            const searchResults = await hybridSearch(fullQuery, localData, 10, "component", config.apiKey);
+            const searchResults = await hybridSearch(fullQuery, localData, limit, "component", config.apiKey);
+            const blockMatches = keywordScoreBlocks(fullQuery, allBlocks, blockIndex ?? void 0).slice(0, 5);
+            if (blockMatches.length > 0) {
+              const matchedBlocks = blockMatches.map((bm) => allBlocks.find((b) => b.name.toLowerCase() === bm.name.toLowerCase())).filter(Boolean);
+              const blockFreq = buildBlockComponentFrequency(matchedBlocks);
+              boostByBlockFrequency(searchResults, blockFreq);
+            }
+            const maxScore = searchResults.length > 0 ? searchResults[0].score : 0;
             const scored = searchResults.map((result) => {
               const fragment = allFragments.find(
                 (s) => s.meta.name.toLowerCase() === result.name.toLowerCase()
@@ -1410,15 +1759,11 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
               if (!fragment) return null;
               const filteredWhen = filterPlaceholders(fragment.usage?.when).slice(0, 3);
               const filteredWhenNot = filterPlaceholders(fragment.usage?.whenNot).slice(0, 2);
-              let confidence;
-              if (result.score >= 0.025) confidence = "high";
-              else if (result.score >= 0.015) confidence = "medium";
-              else confidence = "low";
               return {
                 component: fragment.meta.name,
                 category: fragment.meta.category,
                 description: fragment.meta.description,
-                confidence,
+                confidence: assignConfidence(result.score, maxScore),
                 reasons: [`Matched via hybrid search (score: ${result.score.toFixed(4)})`],
                 usage: { when: filteredWhen, whenNot: filteredWhenNot },
                 variantCount: fragment.variants.length,
@@ -1434,7 +1779,7 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
               if (count < 2 || suggestions.length < 3) {
                 suggestions.push(item);
                 categoryCount[cat] = count + 1;
-                if (suggestions.length >= 5) break;
+                if (suggestions.length >= limit) break;
               }
             }
             const compositionHint = suggestions.length >= 2 ? `These components work well together. For example, ${suggestions[0].component} can be combined with ${suggestions.slice(1, 3).map((s) => s.component).join(" and ")}.` : void 0;
@@ -1442,7 +1787,8 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
             const STYLE_KEYWORDS = ["color", "spacing", "padding", "margin", "font", "border", "radius", "shadow", "variable", "token", "css", "theme", "dark mode", "background", "hover"];
             const isStyleQuery = STYLE_KEYWORDS.some((kw) => useCaseLower.includes(kw));
             const noMatch = suggestions.length === 0;
-            const weakMatch = !noMatch && suggestions.every((s) => s.confidence === "low");
+            const belowThreshold = !noMatch && maxScore > 1 && !meetsMinimumThreshold(maxScore);
+            const weakMatch = !noMatch && (belowThreshold || suggestions.every((s) => s.confidence === "low"));
             let recommendation;
             let nextStep;
             if (noMatch) {
@@ -1455,19 +1801,33 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
               recommendation = `Best match: ${suggestions[0].component} (${suggestions[0].confidence} confidence) - ${suggestions[0].description}`;
               nextStep = `Use ${TOOL_NAMES.inspect}("${suggestions[0].component}") for full details.`;
             }
+            const tokenHint = isStyleQuery && !noMatch ? `Your query includes styling terms. For CSS custom properties, also try ${TOOL_NAMES.tokens}(search: "${useCaseLower.split(/\s+/)[0]}").` : void 0;
+            const blockNames = blockMatches.map((bm) => allBlocks.find((b) => b.name.toLowerCase() === bm.name.toLowerCase())).filter(Boolean).slice(0, 3).map((b) => b.name);
+            const blockHint = blockNames.length > 0 ? `Related blocks: ${blockNames.join(", ")}. Use ${TOOL_NAMES.blocks}(search: "${useCase}") for ready-to-use patterns.` : void 0;
+            const suggestResponse = verbosity === "compact" ? {
+              useCase,
+              suggestions: suggestions.map((s) => ({
+                component: s.component,
+                description: s.description,
+                confidence: s.confidence
+              })),
+              recommendation
+            } : {
+              useCase,
+              context: context || void 0,
+              suggestions,
+              noMatch,
+              weakMatch,
+              recommendation,
+              compositionHint,
+              ...tokenHint && { tokenHint },
+              ...blockHint && { blockHint },
+              nextStep
+            };
             return {
               content: [{
                 type: "text",
-                text: JSON.stringify({
-                  useCase,
-                  context: context || void 0,
-                  suggestions,
-                  noMatch,
-                  weakMatch,
-                  recommendation,
-                  compositionHint,
-                  nextStep
-                }, null, 2)
+                text: JSON.stringify(suggestResponse)
               }]
             };
           }
@@ -1476,7 +1836,10 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
               (s) => s.meta.name.toLowerCase() === componentForAlts.toLowerCase()
             );
             if (!fragment) {
-              throw new Error(`Component "${componentForAlts}" not found. Use fragments_discover to see available components.`);
+              const allNames = Object.values(data.fragments).map((s) => s.meta.name);
+              const closest = findClosestMatch(componentForAlts, allNames);
+              const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+              throw new Error(`Component "${componentForAlts}" not found.${suggestion} Use ${TOOL_NAMES.discover} to see available components.`);
             }
             const relations = fragment.relations ?? [];
             const referencedBy = Object.values(data.fragments).filter(
@@ -1506,31 +1869,36 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
                   referencedBy,
                   sameCategory,
                   suggestion: relations.find((r) => r.relationship === "alternative") ? `Consider ${relations.find((r) => r.relationship === "alternative")?.component}: ${relations.find((r) => r.relationship === "alternative")?.note}` : void 0
-                }, null, 2)
+                })
               }]
             };
           }
           const fragments = Object.values(data.fragments).filter((s) => {
             if (category && s.meta.category !== category) return false;
             if (status && (s.meta.status ?? "stable") !== status) return false;
-            if (search) {
-              const nameMatch = s.meta.name.toLowerCase().includes(search);
-              const descMatch = s.meta.description?.toLowerCase().includes(search);
-              const tagMatch = s.meta.tags?.some((t) => t.toLowerCase().includes(search));
+            if (search2) {
+              const nameMatch = s.meta.name.toLowerCase().includes(search2);
+              const descMatch = s.meta.description?.toLowerCase().includes(search2);
+              const tagMatch = s.meta.tags?.some((t) => t.toLowerCase().includes(search2));
               if (!nameMatch && !descMatch && !tagMatch) return false;
             }
             return true;
-          }).map((s) => ({
-            name: s.meta.name,
-            category: s.meta.category,
-            description: s.meta.description,
-            status: s.meta.status ?? "stable",
-            variantCount: s.variants.length,
-            tags: s.meta.tags ?? [],
-            ...includeCode && s.variants[0]?.code && {
-              example: s.variants[0].code
+          }).map((s) => {
+            if (verbosity === "compact") {
+              return { name: s.meta.name, category: s.meta.category };
             }
-          }));
+            return {
+              name: s.meta.name,
+              category: s.meta.category,
+              description: s.meta.description,
+              status: s.meta.status ?? "stable",
+              variantCount: s.variants.length,
+              tags: s.meta.tags ?? [],
+              ...(includeCode || verbosity === "full") && s.variants[0]?.code && {
+                example: s.variants[0].code
+              }
+            };
+          });
           return {
             content: [{
               type: "text",
@@ -1539,7 +1907,7 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
                 fragments,
                 categories: [...new Set(fragments.map((s) => s.category))],
                 hint: fragments.length === 0 ? "No components found. Try broader search terms or check available categories." : fragments.length > 5 ? "Use fragments_discover with useCase for recommendations, or fragments_inspect for details on a specific component." : void 0
-              }, null, 2)
+              })
             }]
           };
         }
@@ -1553,6 +1921,7 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
           const variantName = args?.variant ?? void 0;
           const maxExamples = args?.maxExamples;
           const maxLines = args?.maxLines;
+          const verbosity = args?.verbosity ?? "standard";
           if (!componentName) {
             throw new Error("component is required");
           }
@@ -1560,7 +1929,10 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
             (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
           );
           if (!fragment) {
-            throw new Error(`Component "${componentName}" not found. Use fragments_discover to see available components.`);
+            const allNames = Object.values(data.fragments).map((s) => s.meta.name);
+            const closest = findClosestMatch(componentName, allNames);
+            const suggestion = closest ? ` Did you mean "${closest}"? Use ${TOOL_NAMES.inspect}("${closest}") to inspect it.` : "";
+            throw new Error(`Component "${componentName}" not found.${suggestion} Use ${TOOL_NAMES.discover} to see available components.`);
           }
           const pkgName = await getPackageName(fragment.meta.name);
           let variants = fragment.variants;
@@ -1640,9 +2012,24 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
               propsReference
             }
           };
-          const result = fields && fields.length > 0 ? projectFields(fullResult, fields) : fullResult;
+          const aliasMap = { "usage": "guidelines" };
+          const resolvedFields = fields?.map((f) => {
+            const parts = f.split(".");
+            if (aliasMap[parts[0]]) parts[0] = aliasMap[parts[0]];
+            return parts.join(".");
+          });
+          let result;
+          if (verbosity === "compact" && !resolvedFields?.length) {
+            result = {
+              meta: fullResult.meta,
+              propNames: Object.keys(fragment.props ?? {}),
+              variantNames: fragment.variants.map((v) => v.name)
+            };
+          } else {
+            result = resolvedFields && resolvedFields.length > 0 ? projectFields(fullResult, resolvedFields) : fullResult;
+          }
           return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            content: [{ type: "text", text: JSON.stringify(result) }]
           };
         }
         // ================================================================
@@ -1651,9 +2038,10 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
         case TOOL_NAMES.blocks: {
           const data = await loadFragments();
           const blockName = args?.name;
-          const search = args?.search?.toLowerCase() ?? void 0;
+          const search2 = args?.search?.toLowerCase() ?? void 0;
           const component = args?.component?.toLowerCase() ?? void 0;
           const category = args?.category?.toLowerCase() ?? void 0;
+          const blocksLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 50) : search2 ? 10 : void 0;
           const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
           if (allBlocks.length === 0) {
             return {
@@ -1663,7 +2051,7 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
                   total: 0,
                   blocks: [],
                   hint: `No composition blocks found. Blocks are reusable patterns showing how components wire together (e.g., "Login Form", "Settings Page"). Create .block.ts files and run \`${BRAND.cliCommand} build\`.`
-                }, null, 2)
+                })
               }]
             };
           }
@@ -1672,18 +2060,35 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
             filtered = filtered.filter(
               (b) => b.name.toLowerCase() === blockName.toLowerCase()
             );
+            if (filtered.length === 0) {
+              const allBlockNames = allBlocks.map((b) => b.name);
+              const closest = findClosestMatch(blockName, allBlockNames);
+              const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+              throw new Error(`Block "${blockName}" not found.${suggestion} Use ${TOOL_NAMES.blocks} to see available blocks.`);
+            }
           }
-          if (search) {
-            filtered = filtered.filter((b) => {
-              const haystack = [
-                b.name,
-                b.description,
-                ...b.tags ?? [],
-                ...b.components,
-                b.category
-              ].join(" ").toLowerCase();
-              return haystack.includes(search);
-            });
+          if (search2) {
+            if (blockIndex) {
+              const ranked = searchBlocks(search2, blockIndex, 50);
+              const rankedNames = new Set(ranked.map((r) => r.name.toLowerCase()));
+              filtered = filtered.filter((b) => rankedNames.has(b.name.toLowerCase()));
+              filtered.sort((a, b) => {
+                const aIdx = ranked.findIndex((r) => r.name.toLowerCase() === a.name.toLowerCase());
+                const bIdx = ranked.findIndex((r) => r.name.toLowerCase() === b.name.toLowerCase());
+                return (aIdx === -1 ? Infinity : aIdx) - (bIdx === -1 ? Infinity : bIdx);
+              });
+            } else {
+              filtered = filtered.filter((b) => {
+                const haystack = [
+                  b.name,
+                  b.description,
+                  ...b.tags ?? [],
+                  ...b.components,
+                  b.category
+                ].join(" ").toLowerCase();
+                return haystack.includes(search2);
+              });
+            }
           }
           if (component) {
             filtered = filtered.filter(
@@ -1695,16 +2100,41 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
               (b) => b.category.toLowerCase() === category
             );
           }
+          const blocksUseIcons = filtered.some(
+            (b) => b.components.some((c) => c === "Icon") || b.code && /\bIcon\b/.test(b.code)
+          );
+          const iconHint = blocksUseIcons ? "Icon components in block code are from @phosphor-icons/react. Import them as: import { IconName } from '@phosphor-icons/react';" : void 0;
+          if (blocksLimit !== void 0) {
+            filtered = filtered.slice(0, blocksLimit);
+          }
+          const pkgName = fragmentPackageMap.values().next().value ?? "your-component-library";
+          const verbosity = args?.verbosity ?? "standard";
+          const blocksWithImports = filtered.map((b) => {
+            const base = {
+              name: b.name,
+              description: b.description,
+              category: b.category,
+              components: b.components,
+              tags: b.tags,
+              import: `import { ${b.components.join(", ")} } from '${pkgName}';`
+            };
+            if (verbosity === "compact") return base;
+            if (verbosity === "full") return { ...base, code: b.code };
+            const codeLines = b.code.split("\n");
+            const code = codeLines.length > 30 ? codeLines.slice(0, 20).join("\n") + "\n// ... truncated (" + codeLines.length + " lines total)" : b.code;
+            return { ...base, code };
+          });
           return {
             content: [{
               type: "text",
               text: JSON.stringify({
-                total: filtered.length,
-                blocks: filtered,
-                ...filtered.length === 0 && allBlocks.length > 0 && {
+                total: blocksWithImports.length,
+                blocks: blocksWithImports,
+                ...iconHint && { iconHint },
+                ...blocksWithImports.length === 0 && allBlocks.length > 0 && {
                   hint: "No blocks matching your query. Try broader search terms."
                 }
-              }, null, 2)
+              })
             }]
           };
         }
@@ -1714,7 +2144,8 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
         case TOOL_NAMES.tokens: {
           const data = await loadFragments();
           const category = args?.category?.toLowerCase() ?? void 0;
-          const search = args?.search?.toLowerCase() ?? void 0;
+          const search2 = args?.search?.toLowerCase() ?? void 0;
+          const tokensLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 100) : search2 ? 25 : void 0;
           const tokenData = data.tokens;
           if (!tokenData || tokenData.total === 0) {
             return {
@@ -1724,30 +2155,53 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
                   total: 0,
                   categories: {},
                   hint: `No design tokens found. Add a tokens.include pattern to your ${BRAND.configFile} and run \`${BRAND.cliCommand} build\`.`
-                }, null, 2)
+                })
               }]
             };
           }
           let filteredCategories = {};
           let filteredTotal = 0;
+          const searchMatchesCategory = search2 ? Object.keys(tokenData.categories).find((cat) => cat.toLowerCase() === search2) : void 0;
           for (const [cat, tokens] of Object.entries(tokenData.categories)) {
             if (category && cat !== category) continue;
             let filtered = tokens;
-            if (search) {
-              filtered = tokens.filter(
-                (t) => t.name.toLowerCase().includes(search) || t.description && t.description.toLowerCase().includes(search)
-              );
+            if (search2) {
+              if (searchMatchesCategory && cat.toLowerCase() === search2) {
+                filtered = tokens;
+              } else {
+                filtered = tokens.filter(
+                  (t) => t.name.toLowerCase().includes(search2) || t.description && t.description.toLowerCase().includes(search2) || cat.toLowerCase().includes(search2)
+                );
+              }
             }
             if (filtered.length > 0) {
               filteredCategories[cat] = filtered;
               filteredTotal += filtered.length;
             }
           }
+          if (tokensLimit !== void 0) {
+            let remaining = tokensLimit;
+            const limited = {};
+            for (const [cat, tokens] of Object.entries(filteredCategories)) {
+              if (remaining <= 0) break;
+              limited[cat] = tokens.slice(0, remaining);
+              remaining -= limited[cat].length;
+            }
+            filteredCategories = limited;
+            filteredTotal = Math.min(filteredTotal, tokensLimit);
+          }
           let hint;
           if (filteredTotal === 0) {
             const availableCategories = Object.keys(tokenData.categories);
-            hint = search ? `No tokens matching "${search}". Try: ${availableCategories.join(", ")}` : category ? `Category "${category}" not found. Available: ${availableCategories.join(", ")}` : void 0;
-          } else if (!category && !search) {
+            if (category && search2) {
+              const categoryTotal = tokenData.categories[category]?.length ?? 0;
+              hint = categoryTotal > 0 ? `No tokens matching "${search2}" in category "${category}" (${categoryTotal} tokens in this category). Try a broader search or remove the search term.` : `Category "${category}" not found. Available: ${availableCategories.join(", ")}`;
+            } else if (search2) {
+              hint = `No tokens matching "${search2}". Available categories: ${availableCategories.join(", ")}`;
+            } else if (category) {
+              hint = `Category "${category}" not found. Available: ${availableCategories.join(", ")}`;
+            }
+          } else if (!category && !search2) {
             hint = `Use var(--token-name) in your CSS/styles. Filter by category or search to narrow results.`;
           }
           return {
@@ -1759,12 +2213,12 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
                 totalAvailable: tokenData.total,
                 categories: filteredCategories,
                 ...hint && { hint },
-                ...!category && !search && {
+                ...!category && !search2 && {
                   availableCategories: Object.entries(tokenData.categories).map(
                     ([cat, tokens]) => ({ category: cat, count: tokens.length })
                   )
                 }
-              }, null, 2)
+              })
             }]
           };
         }
@@ -1777,19 +2231,34 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
           if (!useCase) {
             throw new Error("useCase is required");
           }
+          const verbosity = args?.verbosity ?? "standard";
           const allFragments = Object.values(data.fragments);
           const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
           const tokenData = data.tokens;
+          const implLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 15) : 5;
           const localData = {
             fragments: allFragments,
             blocks: allBlocks,
-            tokenData
+            tokenData,
+            componentIndex: componentIndex ?? void 0,
+            blockIndex: blockIndex ?? void 0,
+            tokenIndex: tokenIndex ?? void 0
           };
-          const searchResults = await hybridSearch(useCase, localData, 15, void 0, config.apiKey);
-          const componentResults = searchResults.filter((r) => r.kind === "component").slice(0, 3);
-          const blockResults = searchResults.filter((r) => r.kind === "block").slice(0, 2);
-          const tokenResults = searchResults.filter((r) => r.kind === "token").slice(0, 5);
-          const topMatches = componentResults.map((result) => {
+          const [componentResults, blockResults, tokenResults] = await Promise.all([
+            hybridSearch(useCase, localData, implLimit * 3, "component", config.apiKey),
+            hybridSearch(useCase, localData, implLimit, "block", config.apiKey),
+            hybridSearch(useCase, localData, implLimit, "token", config.apiKey)
+          ]);
+          const topBlockScore = blockResults.length > 0 ? blockResults[0].score : 0;
+          const filteredBlockResults = blockResults.filter((r) => r.score >= topBlockScore * 0.3);
+          if (filteredBlockResults.length > 0) {
+            const matchedBlocks = filteredBlockResults.map((r) => allBlocks.find((b) => b.name.toLowerCase() === r.name.toLowerCase())).filter(Boolean);
+            const blockFreq = buildBlockComponentFrequency(matchedBlocks);
+            boostByBlockFrequency(componentResults, blockFreq);
+          }
+          const topComponentResults = componentResults.slice(0, implLimit);
+          const maxCompScore = topComponentResults.length > 0 ? topComponentResults[0].score : 0;
+          const topMatches = topComponentResults.map((result) => {
             const fragment = allFragments.find(
               (s) => s.meta.name.toLowerCase() === result.name.toLowerCase()
             );
@@ -1798,18 +2267,28 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
           const components = await Promise.all(
             topMatches.map(async ({ fragment: s, score }) => {
               const pkgName = await getPackageName(s.meta.name);
-              const examples = s.variants.slice(0, 2).map((v) => ({
+              if (verbosity === "compact") {
+                return {
+                  name: s.meta.name,
+                  description: s.meta.description,
+                  confidence: assignConfidence(score, maxCompScore),
+                  import: `import { ${s.meta.name} } from '${pkgName}';`
+                };
+              }
+              const exampleLimit = verbosity === "full" ? s.variants.length : 2;
+              const propsLimit = verbosity === "full" ? Object.keys(s.props ?? {}).length : 5;
+              const examples = s.variants.slice(0, exampleLimit).map((v) => ({
                 variant: v.name,
                 code: v.code ?? `<${s.meta.name} />`
               }));
-              const propsSummary = Object.entries(s.props ?? {}).slice(0, 10).map(
+              const propsSummary = Object.entries(s.props ?? {}).slice(0, propsLimit).map(
                 ([pName, p]) => `${pName}${p.required ? " (required)" : ""}: ${p.type}${p.values ? ` = ${p.values.join("|")}` : ""}`
               );
               return {
                 name: s.meta.name,
                 category: s.meta.category,
                 description: s.meta.description,
-                confidence: score >= 0.025 ? "high" : score >= 0.015 ? "medium" : "low",
+                confidence: assignConfidence(score, maxCompScore),
                 import: `import { ${s.meta.name} } from '${pkgName}';`,
                 props: propsSummary,
                 examples,
@@ -1818,11 +2297,21 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
               };
             })
           );
-          const matchingBlocks = blockResults.map((result) => {
+          const matchingBlocks = filteredBlockResults.slice(0, 5).map((result) => {
             const block = allBlocks.find(
               (b) => b.name.toLowerCase() === result.name.toLowerCase()
             );
-            return block ? { name: block.name, description: block.description, components: block.components, code: block.code } : null;
+            if (!block) return null;
+            const pkgName = fragmentPackageMap.values().next().value ?? "your-component-library";
+            const codeLines = block.code.split("\n");
+            const code = codeLines.length > 30 ? codeLines.slice(0, 20).join("\n") + "\n// ... truncated (" + codeLines.length + " lines total)" : block.code;
+            return {
+              name: block.name,
+              description: block.description,
+              components: block.components,
+              code,
+              import: `import { ${block.components.join(", ")} } from '${pkgName}';`
+            };
           }).filter(Boolean);
           let relevantTokens;
           if (tokenResults.length > 0 && tokenData) {
@@ -1838,17 +2327,28 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
             }
             if (Object.keys(relevantTokens).length === 0) relevantTokens = void 0;
           }
+          if (!relevantTokens && tokenData) {
+            const categories = extractTokenCategories(useCase);
+            relevantTokens = {};
+            for (const cat of categories) {
+              const tokens = tokenData.categories[cat];
+              if (tokens && tokens.length > 0) {
+                relevantTokens[cat] = tokens.slice(0, 5).map((t) => t.name);
+              }
+            }
+            if (Object.keys(relevantTokens).length === 0) relevantTokens = void 0;
+          }
           return {
             content: [{
               type: "text",
               text: JSON.stringify({
                 useCase,
                 components,
-                blocks: matchingBlocks.length > 0 ? matchingBlocks : void 0,
-                tokens: relevantTokens,
+                blocks: verbosity !== "compact" && matchingBlocks.length > 0 ? matchingBlocks : void 0,
+                tokens: verbosity !== "compact" ? relevantTokens : void 0,
                 noMatch: components.length === 0,
                 summary: components.length > 0 ? `Found ${components.length} component(s) for "${useCase}". ${matchingBlocks.length > 0 ? `Plus ${matchingBlocks.length} ready-to-use block(s).` : ""}` : `No components match "${useCase}". Try ${TOOL_NAMES.discover} with different terms${tokenData ? ` or ${TOOL_NAMES.tokens} for CSS variables` : ""}.`
-              }, null, 2)
+              })
             }]
           };
         }
@@ -1868,6 +2368,18 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
               isError: true
             };
           }
+          {
+            const data = await loadFragments();
+            const fragment = Object.values(data.fragments).find(
+              (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
+            );
+            if (!fragment) {
+              const allNames = Object.values(data.fragments).map((s) => s.meta.name);
+              const closest = findClosestMatch(componentName, allNames);
+              const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+              throw new Error(`Component "${componentName}" not found.${suggestion} Use ${TOOL_NAMES.discover} to see available components.`);
+            }
+          }
           const viewerUrl = config.viewerUrl;
           if (!viewerUrl) {
             return {
@@ -1919,7 +2431,7 @@ Suggestion: ${result.suggestion}` : ""}`
                   threshold: result.threshold,
                   figmaUrl: result.figmaUrl,
                   changedRegions: result.changedRegions
-                }, null, 2)
+                })
               });
               return { content };
             } catch (error) {
@@ -1936,6 +2448,7 @@ Suggestion: ${result.suggestion}` : ""}`
             const result = await renderComponent(viewerUrl, {
               component: componentName,
               props,
+              variant: variantName,
               viewport: viewport ?? { width: 800, height: 600 }
             });
             if (result.error) {
@@ -1953,7 +2466,7 @@ Suggestion: ${result.suggestion}` : ""}`
                 },
                 {
                   type: "text",
-                  text: `Successfully rendered ${componentName} with props: ${JSON.stringify(props)}`
+                  text: `Successfully rendered ${componentName}${variantName ? ` (variant: "${variantName}")` : ""}${Object.keys(props).length > 0 ? ` with props: ${JSON.stringify(props)}` : ""}`
                 }
               ]
             };
@@ -1982,7 +2495,10 @@ Suggestion: ${result.suggestion}` : ""}`
             (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
           );
           if (!fragment) {
-            throw new Error(`Component "${componentName}" not found. Use fragments_discover to see available components.`);
+            const allNames = Object.values(data.fragments).map((s) => s.meta.name);
+            const closest = findClosestMatch(componentName, allNames);
+            const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+            throw new Error(`Component "${componentName}" not found.${suggestion} Use ${TOOL_NAMES.discover} to see available components.`);
           }
           const viewerUrl = config.viewerUrl;
           if (!viewerUrl) {
@@ -2020,7 +2536,7 @@ Suggestion: ${result.suggestion}` : ""}`
                   summary: result.summary,
                   patchCount: result.patches.length,
                   nextStep: result.patches.length > 0 ? "Apply patches using your editor or `patch` command, then run fragments_render to confirm fixes." : void 0
-                }, null, 2)
+                })
               }]
             };
           } catch (error) {
@@ -2044,6 +2560,18 @@ Suggestion: ${result.suggestion}` : ""}`
           if (!componentName) {
             throw new Error("component is required");
           }
+          {
+            const data = await loadFragments();
+            const fragment = Object.values(data.fragments).find(
+              (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
+            );
+            if (!fragment) {
+              const allNames = Object.values(data.fragments).map((s) => s.meta.name);
+              const closest = findClosestMatch(componentName, allNames);
+              const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+              throw new Error(`Component "${componentName}" not found.${suggestion} Use ${TOOL_NAMES.discover} to see available components.`);
+            }
+          }
           const viewerUrl = config.viewerUrl;
           if (!viewerUrl) {
             return {
@@ -2070,6 +2598,14 @@ Suggestion: ${result.suggestion}` : ""}`
                 isError: true
               };
             }
+            let nextStep;
+            if (result.emptyAudit) {
+              nextStep = `No testable elements found for ${variantName ? `variant "${variantName}"` : componentName}. The variant may not exist or renders no accessible content. Check available variants with ${TOOL_NAMES.inspect}("${componentName}").`;
+            } else if (result.passed) {
+              nextStep = 'All accessibility checks passed. Consider running with standard: "AAA" for enhanced compliance.';
+            } else {
+              nextStep = `Fix the violations above, then re-run ${TOOL_NAMES.a11y} to verify. Use ${TOOL_NAMES.fix} for automated fixes.`;
+            }
             return {
               content: [{
                 type: "text",
@@ -2077,13 +2613,14 @@ Suggestion: ${result.suggestion}` : ""}`
                   component: componentName,
                   variant: variantName ?? "all",
                   standard,
-                  score: result.score,
-                  aaCompliance: `${result.aaPercent}%`,
-                  aaaCompliance: `${result.aaaPercent}%`,
+                  totalViolations: result.results.reduce((sum, r) => sum + r.summary.total, 0),
+                  variantsPassingAA: `${result.aaPercent}%`,
+                  variantsPassingAAA: `${result.aaaPercent}%`,
                   passed: result.passed,
+                  ...result.emptyAudit && { emptyAudit: true },
                   results: result.results,
-                  nextStep: result.passed ? 'All accessibility checks passed. Consider running with standard: "AAA" for enhanced compliance.' : `Fix the violations above, then re-run ${TOOL_NAMES.a11y} to verify. Use ${TOOL_NAMES.fix} for automated fixes.`
-                }, null, 2)
+                  nextStep
+                })
               }]
             };
           } catch (error) {
@@ -2108,10 +2645,12 @@ Suggestion: ${result.suggestion}` : ""}`
             edgeTypes: args?.edgeTypes,
             maxDepth: args?.maxDepth
           };
+          const allNames = Object.values(data.fragments).map((s) => s.meta.name);
           const result = handleGraphTool(
             graphArgs,
             data.graph,
-            data.blocks ?? data.recipes
+            data.blocks ?? data.recipes,
+            allNames
           );
           if (result.isError) {
             return {
@@ -2150,4 +2689,4 @@ export {
   createMcpServer,
   startMcpServer
 };
-//# sourceMappingURL=chunk-WEHZRM4L.js.map
+//# sourceMappingURL=chunk-FEUUOMWK.js.map