@fragments-sdk/mcp 0.7.0 → 0.8.0

package/dist/{chunk-LZW5KUXV.js → chunk-6JMX4AMO.js}

@@ -4,12 +4,13 @@ import {
 } from "./chunk-4SVS3AA3.js";
 import {
   componentNames,
+  findComponent,
   findComponentByName,
   getGuidanceWhen,
   getGuidanceWhenNot,
   listBlocks,
   listComponents
-} from "./chunk-3IHXJEMM.js";
+} from "./chunk-YSRGQDEB.js";
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -19,7 +20,7 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { existsSync as existsSync9 } from "fs";
-import { readFileSync as readFileSync7 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { join as join8 } from "path";
 import { fileURLToPath } from "url";
 
@@ -653,17 +654,20 @@ function buildLocalSearchData(data, indexes) {
 }
 async function buildImportStatements(components, resolvePackageName) {
   const grouped = /* @__PURE__ */ new Map();
-  for (const component of components) {
-    if (!component) continue;
-    const packageName = await resolvePackageName(component);
+  const uniqueComponents = [...new Set(components.filter(Boolean))];
+  const resolvedPackages = await Promise.all(
+    uniqueComponents.map(async (component) => ({
+      component,
+      packageName: await resolvePackageName(component)
+    }))
+  );
+  for (const { component, packageName } of resolvedPackages) {
     const existing = grouped.get(packageName);
     if (!existing) {
       grouped.set(packageName, [component]);
       continue;
     }
-    if (!existing.includes(component)) {
-      existing.push(component);
-    }
+    existing.push(component);
   }
   return Array.from(grouped.entries()).map(
     ([packageName, componentNames2]) => `import { ${componentNames2.join(", ")} } from '${packageName}';`
@@ -687,6 +691,56 @@ function limitTokensPerCategory(categories, limit) {
   return { categories: limited, total };
 }
 
+// src/search-helpers.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "bar",
+  "build",
+  "button",
+  "for",
+  "form",
+  "i",
+  "login",
+  "me",
+  "need",
+  "of",
+  "or",
+  "the",
+  "to",
+  "use",
+  "with"
+]);
+function normalizeTerms(value) {
+  return value.toLowerCase().split(/[^a-z0-9]+/g).filter((term) => term.length > 1 && !STOP_WORDS.has(term));
+}
+function hasDirectQueryOverlap(query, component) {
+  const queryTerms = normalizeTerms(query);
+  if (queryTerms.length === 0) return true;
+  const haystack = new Set(
+    normalizeTerms(
+      [
+        component.name,
+        component.description,
+        component.category,
+        component.tags.join(" "),
+        getGuidanceWhen(component).join(" "),
+        getGuidanceWhenNot(component).join(" "),
+        component.propsSummary.join(" ")
+      ].join(" ")
+    )
+  );
+  return queryTerms.some((term) => haystack.has(term));
+}
+function getRankingBonus(component) {
+  let bonus = 0;
+  if (component.isCanonical) bonus += 30;
+  if (component.tier === "core") bonus += 20;
+  if (component.status === "stable") bonus += 5;
+  return bonus;
+}
+
 // src/tools/discover.ts
 function renderContextMarkdown(args) {
   const lines = ["# Design System Context", ""];
@@ -769,11 +823,13 @@ var discoverHandler = async (args, ctx) => {
   const compact = args?.compact ?? false;
   const includeCode = args?.includeCode ?? false;
   const includeRelations = args?.includeRelations ?? false;
+  const depth = args?.depth ?? "quick";
   const suggestLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 25) : 10;
   const listLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 25) : void 0;
   const verbosity = args?.verbosity ?? (compact ? "compact" : "standard");
-  if (args?.format && !useCase && !componentForAlts) {
-    let components2 = listComponents(data.snapshot);
+  const allSnapshotComponents = listComponents(data.snapshot);
+  if (!useCase && !componentForAlts && (args?.format || includeCode || includeRelations)) {
+    let components2 = allSnapshotComponents;
     const allBlocks = listBlocks(data.snapshot);
     if (category) {
       components2 = components2.filter(
@@ -781,12 +837,16 @@ var discoverHandler = async (args, ctx) => {
       );
     }
     if (search2) {
-      components2 = components2.filter((component) => {
-        const tagMatch = component.tags.some(
-          (tag) => tag.toLowerCase().includes(search2)
-        );
-        return component.name.toLowerCase().includes(search2) || component.description.toLowerCase().includes(search2) || tagMatch;
-      });
+      const scored = keywordScoreComponents(
+        search2,
+        components2,
+        ctx.indexes.componentIndex ?? void 0
+      );
+      const allowedNames = new Set(components2.map((component) => component.name));
+      const sortedNames = scored.filter((result) => allowedNames.has(result.name)).map((result) => result.name.toLowerCase());
+      components2 = components2.filter((component) => sortedNames.includes(component.name.toLowerCase())).sort(
+        (a, b) => sortedNames.indexOf(a.name.toLowerCase()) - sortedNames.indexOf(b.name.toLowerCase())
+      );
     }
     if (status) {
       components2 = components2.filter((component) => component.status === status);
@@ -838,6 +898,14 @@ var discoverHandler = async (args, ctx) => {
       "component",
       ctx.config.searchApiKey
     );
+    const filteredSearchResults = searchResults.filter((result) => {
+      const component = componentsByName.get(result.name.toLowerCase());
+      if (!component) return false;
+      if (category && !categoryMatches(component.category, category)) return false;
+      if (status && component.status !== status) return false;
+      result.score += getRankingBonus(component);
+      return true;
+    });
     const blockMatches = keywordScoreBlocks(
       fullQuery,
       allBlocks,
@@ -848,10 +916,10 @@ var discoverHandler = async (args, ctx) => {
         (match) => allBlocks.find((block) => block.name.toLowerCase() === match.name.toLowerCase())
       ).filter(Boolean);
       const blockFreq = buildBlockComponentFrequency(matchedBlocks);
-      boostByBlockFrequency(searchResults, blockFreq);
+      boostByBlockFrequency(filteredSearchResults, blockFreq);
     }
-    const maxScore = searchResults.length > 0 ? searchResults[0].score : 0;
-    const scored = searchResults.map((result) => {
+    const maxScore = filteredSearchResults.length > 0 ? filteredSearchResults[0].score : 0;
+    const scored = filteredSearchResults.map((result) => {
       const component = componentsByName.get(result.name.toLowerCase());
       if (!component) return null;
       return {
@@ -864,6 +932,11 @@ var discoverHandler = async (args, ctx) => {
           when: getGuidanceWhen(component).slice(0, 3),
           whenNot: getGuidanceWhenNot(component).slice(0, 2)
         },
+        publicRef: component.publicRef,
+        componentKey: component.id,
+        tier: component.tier,
+        isCanonical: component.isCanonical ?? false,
+        sourcePath: component.sourcePath,
         exampleCount: component.examples.length,
         status: component.status
       };
@@ -902,7 +975,10 @@ var discoverHandler = async (args, ctx) => {
     const isStyleQuery = styleKeywords.some(
       (keyword) => useCaseLower.includes(keyword)
     );
-    const noMatch = suggestions.length === 0;
+    const noMatch = suggestions.length === 0 || !suggestions.some((item) => {
+      const component = componentsByName.get(item.component.toLowerCase());
+      return component ? hasDirectQueryOverlap(useCase, component) : false;
+    });
     const belowThreshold = !noMatch && maxScore > 1 && !meetsMinimumThreshold(maxScore);
     const weakMatch = !noMatch && (belowThreshold || suggestions.every((item) => item.confidence === "low"));
     let recommendation;
@@ -922,6 +998,80 @@ var discoverHandler = async (args, ctx) => {
       (match) => allBlocks.find((block) => block.name.toLowerCase() === match.name.toLowerCase())
     ).filter(Boolean).slice(0, 3).map((block) => block.name);
     const blockHint = blockNames.length > 0 ? `Related blocks: ${blockNames.join(", ")}. Use ${ctx.toolNames.blocks}(search: "${useCase}") for ready-to-use patterns.` : void 0;
+    let fullBlocks;
+    let fullTokens;
+    let fullImports;
+    if (depth === "full" && !noMatch) {
+      const tokenData = ctx.data.tokens;
+      const [blockSearchResults, tokenSearchResults] = await Promise.all([
+        hybridSearch(fullQuery, localData, 5, "block", ctx.config.searchApiKey),
+        tokenData ? hybridSearch(fullQuery, localData, 10, "token", ctx.config.searchApiKey) : Promise.resolve([])
+      ]);
+      const topBlockScore = blockSearchResults.length > 0 ? blockSearchResults[0].score : 0;
+      const relevantBlockResults = blockSearchResults.filter(
+        (result) => result.score >= topBlockScore * 0.3
+      );
+      if (relevantBlockResults.length > 0) {
+        fullBlocks = (await Promise.all(
+          relevantBlockResults.slice(0, 5).map(async (result) => {
+            const block = allBlocks.find(
+              (entry) => entry.name.toLowerCase() === result.name.toLowerCase()
+            );
+            if (!block) return null;
+            const imports = await buildImportStatements(
+              block.components,
+              async (componentName) => ctx.resolvePackageName(componentName)
+            );
+            const codeLines = block.code.split("\n");
+            const code = codeLines.length > 30 ? `${codeLines.slice(0, 20).join("\n")}
+// ... truncated (${codeLines.length} lines total)` : block.code;
+            return {
+              name: block.name,
+              description: block.description,
+              components: block.components,
+              code,
+              imports
+            };
+          })
+        )).filter(Boolean);
+      }
+      if (tokenSearchResults.length > 0 && tokenData) {
+        fullTokens = {};
+        const tokensByName = /* @__PURE__ */ new Map();
+        for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+          for (const token of tokens) {
+            tokensByName.set(token.name, cat);
+          }
+        }
+        for (const result of tokenSearchResults) {
+          const cat = tokensByName.get(result.name);
+          if (cat) {
+            if (!fullTokens[cat]) fullTokens[cat] = [];
+            fullTokens[cat].push(result.name);
+          }
+        }
+        if (Object.keys(fullTokens).length === 0) fullTokens = void 0;
+      }
+      if (!fullTokens && tokenData) {
+        const categories = extractTokenCategories(fullQuery);
+        fullTokens = {};
+        for (const cat of categories) {
+          const tokens = tokenData.categories[cat];
+          if (tokens && tokens.length > 0) {
+            fullTokens[cat] = tokens.slice(0, 5).map((token) => token.name);
+          }
+        }
+        if (Object.keys(fullTokens).length === 0) fullTokens = void 0;
+      }
+      if (suggestions.length > 0) {
+        fullImports = {};
+        for (const item of suggestions) {
+          if (!item) continue;
+          const pkgName = ctx.resolvePackageName(item.component);
+          fullImports[item.component] = `import { ${item.component} } from '${pkgName}';`;
+        }
+      }
+    }
     const suggestResponse = verbosity === "compact" ? {
       useCase,
       suggestions: suggestions.map((item) => ({
@@ -933,14 +1083,19 @@ var discoverHandler = async (args, ctx) => {
     } : {
       useCase,
       context: context || void 0,
-      suggestions,
+      suggestions: depth === "full" ? suggestions.map((item) => ({
+        ...item,
+        import: fullImports?.[item.component]
+      })) : suggestions,
       noMatch,
       weakMatch,
       recommendation,
       compositionHint,
       ...tokenHint && { tokenHint },
       ...blockHint && { blockHint },
-      nextStep
+      nextStep,
+      ...fullBlocks && fullBlocks.length > 0 && { blocks: fullBlocks },
+      ...fullTokens && { tokens: fullTokens }
     };
     return {
       content: [
@@ -952,33 +1107,39 @@ var discoverHandler = async (args, ctx) => {
     };
   }
   if (componentForAlts) {
-    const component = findComponentByName(data.snapshot, componentForAlts);
+    const component = findComponent(data.snapshot, componentForAlts);
     if (!component) {
       const closest = findClosestMatch(
         componentForAlts,
         componentNames(data.snapshot)
       );
       const suggestion = closest ? ` Did you mean "${closest}"?` : "";
-      throw new Error(
-        `Component "${componentForAlts}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`
-      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: `Component "${componentForAlts}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`
+            })
+          }
+        ],
+        isError: true
+      };
     }
     const relations = component.relations;
-    const referencedBy = listComponents(data.snapshot).filter(
-      (entry) => entry.relations.some(
-        (relation) => relation.componentName.toLowerCase() === componentForAlts.toLowerCase()
-      )
-    ).map((entry) => ({
-      component: entry.name,
-      relationship: entry.relations.find(
-        (relation) => relation.componentName.toLowerCase() === componentForAlts.toLowerCase()
-      )?.relationship,
-      note: entry.relations.find(
-        (relation) => relation.componentName.toLowerCase() === componentForAlts.toLowerCase()
-      )?.note
-    }));
-    const sameCategory = listComponents(data.snapshot).filter(
-      (entry) => entry.category === component.category && entry.name.toLowerCase() !== componentForAlts.toLowerCase()
+    const referencedBy = allSnapshotComponents.map((entry) => {
+      const relation = entry.relations.find(
+        (candidate) => candidate.componentName.toLowerCase() === component.name.toLowerCase()
+      );
+      if (!relation) return null;
+      return {
+        component: entry.name,
+        relationship: relation.relationship,
+        note: relation.note
+      };
+    }).filter(Boolean);
+    const sameCategory = allSnapshotComponents.filter(
+      (entry) => entry.category === component.category && entry.name.toLowerCase() !== component.name.toLowerCase()
     ).map((entry) => ({
       component: entry.name,
       description: entry.description
@@ -1001,25 +1162,44 @@ var discoverHandler = async (args, ctx) => {
       ]
     };
   }
-  const filteredComponents = listComponents(data.snapshot).filter((component) => {
+  let filteredComponents = allSnapshotComponents.filter((component) => {
     if (category && !categoryMatches(component.category, category)) return false;
     if (status && (component.status ?? "stable") !== status) return false;
-    if (search2) {
-      const nameMatch = component.name.toLowerCase().includes(search2);
-      const descMatch = component.description.toLowerCase().includes(search2);
-      const tagMatch = component.tags.some(
-        (tag) => tag.toLowerCase().includes(search2)
-      );
-      if (!nameMatch && !descMatch && !tagMatch) return false;
-    }
     return true;
   });
+  if (search2) {
+    const scored = keywordScoreComponents(
+      search2,
+      filteredComponents,
+      ctx.indexes.componentIndex ?? void 0
+    ).map((result) => {
+      const component = filteredComponents.find(
+        (entry) => entry.name.toLowerCase() === result.name.toLowerCase()
+      );
+      if (!component) return null;
+      return {
+        component,
+        score: result.score + getRankingBonus(component)
+      };
+    }).filter(Boolean);
+    filteredComponents = scored.sort((a, b) => b.score - a.score).map((entry) => entry.component);
+  } else {
+    filteredComponents = filteredComponents.sort((a, b) => {
+      const bonusDiff = getRankingBonus(b) - getRankingBonus(a);
+      if (bonusDiff !== 0) return bonusDiff;
+      return a.name.localeCompare(b.name);
+    });
+  }
   const limitedComponents = listLimit === void 0 ? filteredComponents : filteredComponents.slice(0, listLimit);
   const components = limitedComponents.map((component) => {
     if (verbosity === "compact") {
       return {
         name: component.name,
         category: component.category,
+        publicRef: component.publicRef,
+        componentKey: component.id,
+        tier: component.tier,
+        isCanonical: component.isCanonical ?? false,
         ...component.propsSummary.length > 0 && {
           propsSummary: component.propsSummary
         }
@@ -1030,6 +1210,11 @@ var discoverHandler = async (args, ctx) => {
       category: component.category,
       description: component.description,
       status: component.status ?? "stable",
+      publicRef: component.publicRef,
+      componentKey: component.id,
+      tier: component.tier,
+      isCanonical: component.isCanonical ?? false,
+      sourcePath: component.sourcePath,
       exampleCount: component.examples.length,
       tags: component.tags,
       ...(includeCode || verbosity === "full") && component.examples[0]?.code ? {
@@ -1054,7 +1239,8 @@ var discoverHandler = async (args, ctx) => {
 };
 
 // src/tools/inspect.ts
-import { readFileSync as readFileSync3, existsSync as existsSync2 } from "fs";
+import { promises as fs } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { join as join2 } from "path";
 
 // src/utils.ts
@@ -1090,13 +1276,13 @@ function projectFields(obj, fields) {
 }
 
 // src/tools/inspect.ts
-function getSourceCode(component, projectRoot) {
+async function getSourceCode(component, projectRoot) {
   const sourcePath = component.sourcePath;
   if (!sourcePath) return void 0;
   const fullPath = join2(projectRoot, sourcePath);
   if (!existsSync2(fullPath)) return { path: sourcePath, code: null };
   try {
-    const code = readFileSync3(fullPath, "utf-8");
+    const code = await fs.readFile(fullPath, "utf-8");
     return { path: sourcePath, code };
   } catch {
     return { path: sourcePath, code: null };
@@ -1110,18 +1296,34 @@ var inspectHandler = async (args, ctx) => {
   const maxLines = args?.maxLines;
   const verbosity = args?.verbosity ?? "standard";
   if (!componentName) {
-    throw new Error("component is required");
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: "component is required" })
+        }
+      ],
+      isError: true
+    };
   }
-  const component = findComponentByName(ctx.data.snapshot, componentName);
+  const component = findComponent(ctx.data.snapshot, componentName);
   if (!component) {
     const closest = findClosestMatch(
       componentName,
       componentNames(ctx.data.snapshot)
     );
     const suggestion = closest ? ` Did you mean "${closest}"? Use ${ctx.toolNames.inspect}("${closest}") to inspect it.` : "";
-    throw new Error(
-      `Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`
-    );
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: `Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`
+          })
+        }
+      ],
+      isError: true
+    };
   }
   const pkgName = ctx.resolvePackageName(component.name);
   let examples = component.examples;
@@ -1141,25 +1343,41 @@ var inspectHandler = async (args, ctx) => {
     if (filtered.length > 0) {
       examples = filtered;
     } else {
-      throw new Error(
-        `Example "${exampleName}" not found for ${componentName}. Available: ${component.examples.map((example) => example.name).join(", ")}`
-      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: `Example "${exampleName}" not found for ${componentName}. Available: ${component.examples.map((example) => example.name).join(", ")}`
+            })
+          }
+        ],
+        isError: true
+      };
     }
   }
   if (maxExamples && maxExamples > 0) {
     examples = examples.slice(0, maxExamples);
   }
   const truncateCode = (code) => {
-    if (!maxLines || maxLines <= 0) return code;
+    if (!maxLines || maxLines <= 0) {
+      return { code, truncated: false, remainingLines: 0 };
+    }
     const lines = code.split("\n");
-    if (lines.length <= maxLines) return code;
-    return `${lines.slice(0, maxLines).join("\n")}
-// ... truncated`;
+    if (lines.length <= maxLines) {
+      return { code, truncated: false, remainingLines: 0 };
+    }
+    return {
+      code: lines.slice(0, maxLines).join("\n"),
+      truncated: true,
+      remainingLines: lines.length - maxLines
+    };
   };
   const renderedExamples = examples.map((example) => ({
+    ...example.code ? truncateCode(example.code) : { truncated: false, remainingLines: 0 },
     variant: example.name,
     description: example.description,
-    code: example.code ? truncateCode(example.code) : `<${component.name} />`,
+    code: example.code ? truncateCode(example.code).code : `<${component.name} />`,
     ...example.code ? {} : {
       note: "No code example provided. Refer to props for customization."
     }
@@ -1189,13 +1407,13 @@ var inspectHandler = async (args, ctx) => {
       status: component.status,
       publicRef: component.publicRef,
       publicSlug: component.publicSlug,
+      isCanonical: component.isCanonical ?? false,
       tier: component.tier
     },
-    props: component.props,
+    props: propsReference,
     examples: {
       import: `import { ${component.name} } from '${pkgName}';`,
-      code: renderedExamples,
-      propsReference
+      code: renderedExamples
     },
     relations: component.relations,
     compoundChildren: component.compoundChildren,
@@ -1215,7 +1433,7 @@ var inspectHandler = async (args, ctx) => {
       })) ?? []
     },
     metadata: component.metadata,
-    source: getSourceCode(component, ctx.config.projectRoot)
+    source: await getSourceCode(component, ctx.config.projectRoot)
   };
   const aliasMap = { usage: "guidance" };
   const resolvedFields = fields?.map((field) => {
@@ -1395,6 +1613,44 @@ function resolveCategoryKeys(categories, requestedCategory) {
   }
   return keys.filter((key) => (normalizeCategoryValue(key) ?? "").includes(normalized));
 }
+function canonicalizeCategory(category, tokens) {
+  const normalizedCategory = normalizeCategoryValue(category);
+  const candidates = [
+    normalizedCategory,
+    ...tokens.flatMap((token) => [
+      normalizeCategoryValue(token.category),
+      normalizeCategoryValue(token.path?.[0]),
+      normalizeCategoryValue(token.name.split(/[.:/-]/)[0])
+    ])
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    for (const [canonical, aliases] of Object.entries(TOKEN_CATEGORY_ALIASES)) {
+      if (candidate === canonical || aliases.some(
+        (alias) => candidate === alias || candidate.includes(alias) || alias.includes(candidate)
+      )) {
+        return canonical;
+      }
+    }
+  }
+  return normalizedCategory || "other";
+}
+function normalizeTokenCategories(categories) {
+  const normalized = {};
+  for (const [category, tokens] of Object.entries(categories)) {
+    const canonical = canonicalizeCategory(category, tokens);
+    if (!normalized[canonical]) normalized[canonical] = [];
+    normalized[canonical].push(
+      ...tokens.map((token) => ({
+        ...token,
+        category: canonical
+      }))
+    );
+  }
+  for (const tokens of Object.values(normalized)) {
+    tokens.sort((a, b) => a.name.localeCompare(b.name));
+  }
+  return normalized;
+}
 var tokensHandler = async (args, ctx) => {
   const category = args?.category;
   const search2 = args?.search?.toLowerCase() ?? void 0;
@@ -1412,12 +1668,13 @@ var tokensHandler = async (args, ctx) => {
       }]
     };
   }
+  const normalizedCategories = normalizeTokenCategories(tokenData.categories);
   let filteredCategories = {};
   let filteredTotal = 0;
-  const resolvedCategoryKeys = resolveCategoryKeys(tokenData.categories, category);
+  const resolvedCategoryKeys = resolveCategoryKeys(normalizedCategories, category);
   const friendlyCategories = Object.keys(TOKEN_CATEGORY_ALIASES);
-  const searchMatchesCategory = search2 ? resolveCategoryKeys(tokenData.categories, search2) : [];
-  for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+  const searchMatchesCategory = search2 ? resolveCategoryKeys(normalizedCategories, search2) : [];
+  for (const [cat, tokens] of Object.entries(normalizedCategories)) {
     if (category && !resolvedCategoryKeys.includes(cat)) continue;
     let filtered = tokens;
     if (search2) {
@@ -1425,7 +1682,7 @@ var tokensHandler = async (args, ctx) => {
         filtered = tokens;
       } else {
         filtered = tokens.filter(
-          (t) => t.name.toLowerCase().includes(search2) || t.description && t.description.toLowerCase().includes(search2) || (normalizeCategoryValue(cat) ?? "").includes(search2)
+          (t) => t.name.toLowerCase().includes(search2) || t.description && t.description.toLowerCase().includes(search2) || (normalizeCategoryValue(cat) ?? "").includes(search2) || t.value && t.value.toLowerCase().includes(search2) || t.path && t.path.join(" ").toLowerCase().includes(search2)
         );
       }
     }
@@ -1443,7 +1700,7 @@ var tokensHandler = async (args, ctx) => {
   if (filteredTotal === 0) {
     if (category && search2) {
       const categoryTotal = resolvedCategoryKeys.reduce(
-        (sum, key) => sum + (tokenData.categories[key]?.length ?? 0),
+        (sum, key) => sum + (normalizedCategories[key]?.length ?? 0),
         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. Try categories like: ${friendlyCategories.join(", ")}.`;
@@ -1465,7 +1722,7 @@ var tokensHandler = async (args, ctx) => {
         categories: filteredCategories,
         ...hint && { hint },
         ...!category && !search2 && {
-          availableCategories: Object.entries(tokenData.categories).map(([cat, tokens]) => ({
+          availableCategories: Object.entries(normalizedCategories).map(([cat, tokens]) => ({
             category: cat,
             count: tokens.length
           }))
@@ -1475,177 +1732,6 @@ var tokensHandler = async (args, ctx) => {
   };
 };
 
-// src/tools/implement.ts
-var implementHandler = async (args, ctx) => {
-  const useCase = args?.useCase;
-  if (!useCase) {
-    throw new Error("useCase is required");
-  }
-  const verbosity = args?.verbosity ?? "standard";
-  const snapshotComponents = listComponents(ctx.data.snapshot);
-  const componentsByName = new Map(
-    snapshotComponents.map((component) => [
-      component.name.toLowerCase(),
-      component
-    ])
-  );
-  const { allBlocks, localData } = buildLocalSearchData(
-    {
-      components: ctx.data.components,
-      blocks: ctx.data.blocks,
-      tokens: ctx.data.tokens,
-      graph: ctx.data.graph
-    },
-    {
-      componentIndex: ctx.indexes.componentIndex,
-      blockIndex: ctx.indexes.blockIndex,
-      tokenIndex: ctx.indexes.tokenIndex
-    }
-  );
-  const tokenData = ctx.data.tokens;
-  const implLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 15) : 5;
-  const [componentResults, blockResults, tokenResults] = await Promise.all([
-    hybridSearch(
-      useCase,
-      localData,
-      implLimit * 3,
-      "component",
-      ctx.config.searchApiKey
-    ),
-    hybridSearch(
-      useCase,
-      localData,
-      implLimit,
-      "block",
-      ctx.config.searchApiKey
-    ),
-    hybridSearch(
-      useCase,
-      localData,
-      implLimit,
-      "token",
-      ctx.config.searchApiKey
-    )
-  ]);
-  const topBlockScore = blockResults.length > 0 ? blockResults[0].score : 0;
-  const filteredBlockResults = blockResults.filter(
-    (result) => result.score >= topBlockScore * 0.3
-  );
-  if (filteredBlockResults.length > 0) {
-    const matchedBlocks = filteredBlockResults.map(
-      (result) => allBlocks.find((block) => block.name.toLowerCase() === result.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 component = componentsByName.get(result.name.toLowerCase());
-    return component ? { component, score: result.score } : null;
-  }).filter(Boolean);
-  const components = await Promise.all(
-    topMatches.map(async ({ component, score }) => {
-      const pkgName = ctx.resolvePackageName(component.name);
-      if (verbosity === "compact") {
-        return {
-          name: component.name,
-          description: component.description,
-          confidence: assignConfidence(score, maxCompScore),
-          import: `import { ${component.name} } from '${pkgName}';`
-        };
-      }
-      const exampleLimit = verbosity === "full" ? component.examples.length : 2;
-      const propsLimit = verbosity === "full" ? Object.keys(component.props ?? {}).length : 5;
-      const examples = component.examples.slice(0, exampleLimit).map((example) => ({
-        variant: example.name,
-        code: example.code ?? `<${component.name} />`
-      }));
-      const propsSummary = Object.entries(component.props ?? {}).slice(0, propsLimit).map(
-        ([propName, prop]) => `${propName}${prop.required ? " (required)" : ""}: ${prop.type}${prop.values ? ` = ${prop.values.join("|")}` : ""}`
-      );
-      return {
-        name: component.name,
-        category: component.category,
-        description: component.description,
-        confidence: assignConfidence(score, maxCompScore),
-        import: `import { ${component.name} } from '${pkgName}';`,
-        props: propsSummary,
-        examples,
-        guidelines: getGuidanceWhen(component).slice(0, 3),
-        accessibility: component.guidance.accessibility.slice(0, 2)
-      };
-    })
-  );
-  const matchingBlocks = (await Promise.all(
-    filteredBlockResults.slice(0, 5).map(async (result) => {
-      const block = allBlocks.find(
-        (entry) => entry.name.toLowerCase() === result.name.toLowerCase()
-      );
-      if (!block) return null;
-      const imports = await buildImportStatements(
-        block.components,
-        async (componentName) => ctx.resolvePackageName(componentName)
-      );
-      const codeLines = block.code.split("\n");
-      const code = codeLines.length > 30 ? `${codeLines.slice(0, 20).join("\n")}
-// ... truncated (${codeLines.length} lines total)` : block.code;
-      return {
-        name: block.name,
-        description: block.description,
-        components: block.components,
-        code,
-        import: imports.join("\n"),
-        imports
-      };
-    })
-  )).filter(Boolean);
-  let relevantTokens;
-  if (tokenResults.length > 0 && tokenData) {
-    relevantTokens = {};
-    for (const result of tokenResults) {
-      for (const [category, tokens] of Object.entries(tokenData.categories)) {
-        if (tokens.some((token) => token.name === result.name)) {
-          if (!relevantTokens[category]) relevantTokens[category] = [];
-          relevantTokens[category].push(result.name);
-          break;
-        }
-      }
-    }
-    if (Object.keys(relevantTokens).length === 0) {
-      relevantTokens = void 0;
-    }
-  }
-  if (!relevantTokens && tokenData) {
-    const categories = extractTokenCategories(useCase);
-    relevantTokens = {};
-    for (const category of categories) {
-      const tokens = tokenData.categories[category];
-      if (tokens && tokens.length > 0) {
-        relevantTokens[category] = tokens.slice(0, 5).map((token) => token.name);
-      }
-    }
-    if (Object.keys(relevantTokens).length === 0) {
-      relevantTokens = void 0;
-    }
-  }
-  return {
-    content: [
-      {
-        type: "text",
-        text: JSON.stringify({
-          useCase,
-          components,
-          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 ${ctx.toolNames.discover} with different terms${tokenData ? ` or ${ctx.toolNames.tokens} for tokens` : ""}.`
-        })
-      }
-    ]
-  };
-};
-
 // src/service.ts
 var DEFAULT_ENDPOINTS = {
   render: "/fragments/render",
@@ -2327,8 +2413,18 @@ var governHandler = async (args, ctx) => {
   }
   const policyOverrides = args?.policy;
   const format = args?.format ?? "json";
+  const allowedComponents = Object.values(ctx.data.components).map(
+    (component) => component.name
+  );
   const tokenPrefix = ctx.data.tokens?.prefix;
   const basePolicy = tokenPrefix === "fui-" ? { rules: fragmentsPreset().rules } : { rules: universal().rules };
+  basePolicy.rules["components/allow"] = {
+    enabled: true,
+    severity: "serious",
+    options: {
+      components: allowedComponents
+    }
+  };
   const engineOptions = ctx.data.tokens ? { tokenData: ctx.data.tokens } : void 0;
   const input = {
     spec,
@@ -2366,6 +2462,205 @@ var governHandler = async (args, ctx) => {
   }
 };
 
+// src/tools/validate-and-fix.ts
+import {
+  formatVerdict as formatVerdict2,
+  fragments as fragmentsPreset2,
+  handleGovernTool as handleGovernTool2,
+  universal as universal2
+} from "@fragments-sdk/govern";
+function classifyComponent(component) {
+  if (component.status === "deprecated") return "discouraged";
+  if (component.isCanonical && component.tier === "core") return "preferred";
+  return "allowed";
+}
+function buildEffectiveComponents(ctx) {
+  const selectionByKey = new Map(
+    (ctx.data.validateFixContext?.components ?? []).map((component) => [
+      component.componentKey,
+      component.selection
+    ])
+  );
+  return Object.entries(ctx.data.components).map(([componentKey, component]) => ({
+    component,
+    selection: selectionByKey.get(componentKey) ?? classifyComponent(component)
+  }));
+}
+function cloneSpec(spec) {
+  return structuredClone(spec);
+}
+function getSelectionNames(effectiveComponents, selection) {
+  const selections = Array.isArray(selection) ? selection : [selection];
+  return Array.from(
+    new Set(
+      effectiveComponents.filter((entry) => selections.includes(entry.selection)).map((entry) => entry.component.name)
+    )
+  );
+}
+function buildBasePolicy(ctx) {
+  const tokenPrefix = ctx.data.tokens?.prefix;
+  const basePolicy = tokenPrefix === "fui-" ? { rules: fragmentsPreset2().rules } : { rules: universal2().rules };
+  const allowedComponents = buildEffectiveComponents(ctx).filter(({ selection }) => selection === "preferred" || selection === "allowed").map(({ component }) => component.name);
+  basePolicy.rules["components/allow"] = {
+    enabled: true,
+    severity: "serious",
+    options: {
+      components: allowedComponents
+    }
+  };
+  return basePolicy;
+}
+async function runGovern(spec, ctx, policyOverrides) {
+  const input = {
+    spec,
+    policy: policyOverrides,
+    format: "json"
+  };
+  const engineOptions = ctx.data.tokens ? { tokenData: ctx.data.tokens } : void 0;
+  return handleGovernTool2(input, buildBasePolicy(ctx), engineOptions);
+}
+function applyDeterministicReplacements(spec, ctx) {
+  const effectiveComponents = buildEffectiveComponents(ctx);
+  const byName = /* @__PURE__ */ new Map();
+  const preferredByCategory = /* @__PURE__ */ new Map();
+  for (const entry of effectiveComponents) {
+    const list = byName.get(entry.component.name) ?? [];
+    list.push(entry);
+    byName.set(entry.component.name, list);
+    if (entry.selection !== "preferred") continue;
+    const category = entry.component.category ?? "uncategorized";
+    const names = preferredByCategory.get(category) ?? [];
+    if (!names.includes(entry.component.name)) {
+      names.push(entry.component.name);
+    }
+    preferredByCategory.set(category, names);
+  }
+  const fixedSpec = cloneSpec(spec);
+  const nodes = Array.isArray(fixedSpec.nodes) ? fixedSpec.nodes : [];
+  const replacements = [];
+  for (const node of nodes) {
+    if (!node.type) continue;
+    const componentEntries = byName.get(node.type) ?? [];
+    const component = componentEntries[0];
+    if (!component || component.selection !== "discouraged" && component.selection !== "forbidden") {
+      continue;
+    }
+    const candidates = (preferredByCategory.get(component.component.category ?? "uncategorized") ?? []).filter((candidate) => candidate !== component.component.name);
+    if (candidates.length !== 1) continue;
+    const replacement = candidates[0];
+    replacements.push({
+      nodeId: node.id ?? node.type,
+      from: component.component.name,
+      to: replacement,
+      reason: "deprecated_component"
+    });
+    node.type = replacement;
+  }
+  return {
+    fixedSpec,
+    replacements
+  };
+}
+function buildSummary(args) {
+  const lines = [
+    `status: ${args.status}`,
+    `original: ${formatVerdict2(args.originalVerdict, "summary")}`
+  ];
+  if (args.replacements.length > 0) {
+    lines.push(
+      `replacements: ${args.replacements.map((item) => `${item.from} -> ${item.to}`).join(", ")}`
+    );
+    lines.push(`final: ${formatVerdict2(args.finalVerdict, "summary")}`);
+  }
+  return lines.join("\n");
+}
+var validateAndFixHandler = async (args, ctx) => {
+  const spec = args?.spec;
+  if (!spec || typeof spec !== "object") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "spec is required and must be an object with { nodes: [{ id, type, props, children }] }"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  const policyOverrides = args?.policy;
+  const applyFixes = args?.applyFixes !== false;
+  const format = args?.format ?? "json";
+  try {
+    const effectiveComponents = buildEffectiveComponents(ctx);
+    const originalVerdict = await runGovern(spec, ctx, policyOverrides);
+    let finalVerdict = originalVerdict;
+    let fixedSpec;
+    let replacements = [];
+    if (!originalVerdict.passed && applyFixes) {
+      const result = applyDeterministicReplacements(
+        spec,
+        ctx
+      );
+      replacements = result.replacements;
+      fixedSpec = result.fixedSpec;
+      if (replacements.length > 0) {
+        finalVerdict = await runGovern(fixedSpec, ctx, policyOverrides);
+      }
+    }
+    const status = originalVerdict.passed ? "pass" : replacements.length > 0 ? "fixed" : "fail";
+    const payload = {
+      status,
+      applyFixes,
+      replacements,
+      originalVerdict,
+      finalVerdict,
+      ...fixedSpec ? { fixedSpec } : {},
+      preferredComponents: getSelectionNames(
+        effectiveComponents,
+        "preferred"
+      ),
+      discouragedComponents: getSelectionNames(effectiveComponents, [
+        "discouraged",
+        "forbidden"
+      ])
+    };
+    return {
+      content: [
+        {
+          type: "text",
+          text: format === "summary" ? buildSummary({
+            status,
+            originalVerdict,
+            finalVerdict,
+            replacements
+          }) : JSON.stringify(payload)
+        }
+      ],
+      _meta: {
+        status,
+        replacementCount: replacements.length,
+        passed: finalVerdict.passed
+      }
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const isSpecError = message.includes("Expected") || message.includes("Required");
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: isSpecError ? `Invalid spec format: ${message}. Expected: { nodes: [{ id: string, type: string, props: object, children?: string[] }] }` : message
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+
 // src/tools/generate-ui.ts
 var generateUiHandler = async (args, ctx) => {
   const prompt = args?.prompt;
@@ -2395,16 +2690,154 @@ var generateUiHandler = async (args, ctx) => {
   };
 };
 
+// src/findings-service.ts
+var DEFAULT_CLOUD_URL = "https://app.usefragments.com";
+function normalizeCloudUrl(url) {
+  if (!url) return DEFAULT_CLOUD_URL;
+  return url.replace(/\/+$/, "");
+}
+async function fetchFindings(apiKey, params, cloudUrl) {
+  const base = normalizeCloudUrl(cloudUrl);
+  const url = new URL(`${base}/api/findings`);
+  if (params.status) url.searchParams.set("status", params.status);
+  if (params.severity) url.searchParams.set("severity", params.severity);
+  if (params.category) url.searchParams.set("category", params.category);
+  if (params.ruleId) url.searchParams.set("ruleId", params.ruleId);
+  if (params.filePath) url.searchParams.set("filePath", params.filePath);
+  if (params.limit != null) url.searchParams.set("limit", String(params.limit));
+  const response = await fetch(url.toString(), {
+    headers: { "X-API-Key": apiKey }
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    let message;
+    try {
+      const parsed = JSON.parse(body);
+      message = parsed.error ?? body;
+    } catch {
+      message = body;
+    }
+    throw new Error(
+      `Cloud findings API error (${response.status}): ${message}`
+    );
+  }
+  return await response.json();
+}
+async function fetchFindingsForFile(apiKey, filePath, cloudUrl) {
+  return fetchFindings(
+    apiKey,
+    { status: "open", filePath, limit: 200 },
+    cloudUrl
+  );
+}
+
+// src/tools/findings.ts
+function resolveCloudApiKey(ctx) {
+  return ctx.config.cloudApiKey ?? ctx.config.fileConfig?.cloud?.apiKey ?? process.env.FRAGMENTS_API_KEY;
+}
+function resolveCloudUrl(ctx) {
+  return ctx.config.fileConfig?.cloud?.url ?? process.env.FRAGMENTS_CLOUD_URL;
+}
+function missingKeyError() {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          error: "Cloud API key required. Set FRAGMENTS_API_KEY env var, pass --cloud-api-key, or configure cloud.apiKey in ds-mcp.config.json."
+        })
+      }
+    ],
+    isError: true
+  };
+}
+var findingsListHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const cloudUrl = resolveCloudUrl(ctx);
+  const params = {};
+  if (args.status) params.status = args.status;
+  if (args.severity)
+    params.severity = args.severity;
+  if (args.category) params.category = String(args.category);
+  if (args.ruleId) params.ruleId = String(args.ruleId);
+  if (args.filePath) params.filePath = String(args.filePath);
+  if (args.limit != null) params.limit = Number(args.limit);
+  try {
+    const result = await fetchFindings(apiKey, params, cloudUrl);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result) }],
+      _meta: { count: result.findings.length }
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+var findingsForFileHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const filePath = args.filePath;
+  if (!filePath || typeof filePath !== "string") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: "filePath is required." })
+        }
+      ],
+      isError: true
+    };
+  }
+  const cloudUrl = resolveCloudUrl(ctx);
+  try {
+    const result = await fetchFindingsForFile(apiKey, filePath, cloudUrl);
+    const findings = result.findings.filter((f) => f.filePath === filePath);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ findings, filePath })
+        }
+      ],
+      _meta: { count: findings.length, filePath }
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+
 // src/tools/index.ts
 var CORE_TOOLS = {
   discover: discoverHandler,
   inspect: inspectHandler,
   blocks: blocksHandler,
   tokens: tokensHandler,
-  implement: implementHandler,
   graph: graphHandler,
   perf: perfHandler,
-  govern: governHandler
+  govern: governHandler,
+  validate_and_fix: validateAndFixHandler,
+  findings_list: findingsListHandler,
+  findings_for_file: findingsForFileHandler
 };
 var VIEWER_TOOLS = {
   render: renderHandler,
@@ -2424,9 +2857,9 @@ var TOOL_CAPABILITIES = {
   inspect: ["components"],
   blocks: ["blocks"],
   tokens: ["tokens"],
-  implement: ["components"],
   graph: ["graph"],
   perf: ["performance"],
+  validate_and_fix: ["components"],
   render: ["components"],
   fix: ["components"],
   a11y: ["components"]
@@ -2576,7 +3009,7 @@ import { join as join7 } from "path";
 import { readFile } from "fs/promises";
 
 // src/discovery.ts
-import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync } from "fs";
 import { join as join3, dirname, resolve } from "path";
 import { createRequire } from "module";
 function resolveWorkspaceGlob(baseDir, pattern) {
@@ -2609,7 +3042,7 @@ function getWorkspaceDirs(rootDir) {
   const rootPkgPath = join3(rootDir, "package.json");
   if (existsSync3(rootPkgPath)) {
     try {
-      const rootPkg = JSON.parse(readFileSync4(rootPkgPath, "utf-8"));
+      const rootPkg = JSON.parse(readFileSync3(rootPkgPath, "utf-8"));
       const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : rootPkg.workspaces?.packages;
       if (Array.isArray(workspaces)) {
         for (const pattern of workspaces) {
@@ -2623,7 +3056,7 @@ function getWorkspaceDirs(rootDir) {
   const pnpmWsPath = join3(rootDir, "pnpm-workspace.yaml");
   if (existsSync3(pnpmWsPath)) {
     try {
-      const content = readFileSync4(pnpmWsPath, "utf-8");
+      const content = readFileSync3(pnpmWsPath, "utf-8");
       const lines = content.split("\n");
       let inPackages = false;
       for (const line of lines) {
@@ -2656,7 +3089,7 @@ function resolveDepPackageJson(localRequire, depName) {
     while (true) {
       const candidate = join3(dir, "package.json");
       if (existsSync3(candidate)) {
-        const pkg = JSON.parse(readFileSync4(candidate, "utf-8"));
+        const pkg = JSON.parse(readFileSync3(candidate, "utf-8"));
         if (pkg.name === depName) return candidate;
       }
       const parent = dirname(dir);
@@ -2671,7 +3104,7 @@ function findFragmentsInDeps(dir, found, depField) {
   const pkgJsonPath = join3(dir, "package.json");
   if (!existsSync3(pkgJsonPath)) return;
   try {
-    const pkgJson = JSON.parse(readFileSync4(pkgJsonPath, "utf-8"));
+    const pkgJson = JSON.parse(readFileSync3(pkgJsonPath, "utf-8"));
     const allDeps = {
       ...pkgJson.dependencies,
       ...pkgJson.devDependencies
@@ -2681,7 +3114,7 @@ function findFragmentsInDeps(dir, found, depField) {
       try {
         const depPkgPath = resolveDepPackageJson(localRequire, depName);
         if (!depPkgPath) continue;
-        const depPkg = JSON.parse(readFileSync4(depPkgPath, "utf-8"));
+        const depPkg = JSON.parse(readFileSync3(depPkgPath, "utf-8"));
         if (depPkg[depField]) {
           const fragmentsPath = join3(dirname(depPkgPath), depPkg[depField]);
           if (existsSync3(fragmentsPath) && !found.includes(fragmentsPath)) {
@@ -2757,6 +3190,26 @@ function valueToString(value) {
     return void 0;
   }
 }
+function buildCompoundChildren(contract, ai) {
+  const contractChildren = Object.entries(contract?.compoundChildren ?? {});
+  if (contractChildren.length > 0) {
+    return contractChildren.map(([childName, child]) => ({
+      name: childName,
+      description: child.description,
+      required: child.required,
+      accepts: child.accepts,
+      visibility: "public"
+    }));
+  }
+  const subs = ai?.subComponents;
+  if (!subs || subs.length === 0) return [];
+  const requiredSet = new Set(ai?.requiredChildren ?? []);
+  return subs.map((name) => ({
+    name,
+    required: requiredSet.has(name) || void 0,
+    visibility: "public"
+  }));
+}
 function componentFromCompiledFragment(args) {
   const { fragment, sourceType } = args;
   const name = fragment.meta.name;
@@ -2806,15 +3259,7 @@ function componentFromCompiledFragment(args) {
       relationship: relation.relationship,
       note: relation.note
     })),
-    compoundChildren: Object.entries(contract?.compoundChildren ?? {}).map(
-      ([childName, child]) => ({
-        name: childName,
-        description: child.description,
-        required: child.required,
-        accepts: child.accepts,
-        visibility: "public"
-      })
-    ),
+    compoundChildren: buildCompoundChildren(contract, ai),
     guidance: {
       when: usage.when ?? [],
       whenNot: usage.whenNot ?? [],
@@ -3010,7 +3455,7 @@ If you're a library author, run \`${BRAND.cliCommand} build\` first.`
 };
 
 // src/adapters/auto-extract.ts
-import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
 import { join as join6, relative, sep } from "path";
 
 // src/adapters/discover-components.ts
@@ -3098,7 +3543,7 @@ function inferComponentName(fileName, dirPath) {
 }
 
 // src/adapters/scan-tokens.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
+import { readdirSync as readdirSync3, readFileSync as readFileSync4, existsSync as existsSync5 } from "fs";
 import { join as join5, extname as extname2 } from "path";
 function scanTokens(projectRoot) {
   const cssFiles = discoverCssFiles(projectRoot);
@@ -3107,7 +3552,7 @@ function scanTokens(projectRoot) {
   let prefix = "";
   for (const filePath of cssFiles) {
     try {
-      const content = readFileSync5(filePath, "utf-8");
+      const content = readFileSync4(filePath, "utf-8");
       const tokens = extractCustomProperties(content);
       allTokens.push(...tokens);
     } catch {
@@ -3274,7 +3719,7 @@ var AutoExtractionAdapter = class {
   async load(projectRoot) {
     let extractMod;
     try {
-      extractMod = await import("./dist-V7D67NXS.js");
+      extractMod = await loadExtractorModule();
     } catch (e) {
       throw new Error(
         "Auto-extraction requires @fragments-sdk/extract and TypeScript.\n\nIf you see this error, the MCP server may not be installed correctly.\nAlternative: pre-build your design system with `npx fragments build`"
@@ -3390,6 +3835,13 @@ Check that your tsconfig.json includes the component directories.`
     }
   }
 };
+var extractorModulePromise = null;
+async function loadExtractorModule() {
+  if (!extractorModulePromise) {
+    extractorModulePromise = import("./dist-V7D67NXS.js");
+  }
+  return extractorModulePromise;
+}
 var UNIVERSAL_INHERITED = /* @__PURE__ */ new Set(["children", "className", "id", "disabled"]);
 var FORM_INPUT_INHERITED = /* @__PURE__ */ new Set([
   "placeholder",
@@ -3661,7 +4113,7 @@ function readPackageName(projectRoot) {
   try {
     const pkgPath = join6(projectRoot, "package.json");
     if (!existsSync6(pkgPath)) return void 0;
-    const pkg = JSON.parse(readFileSync6(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
     return pkg.name;
   } catch {
     return void 0;
@@ -3669,16 +4121,53 @@ function readPackageName(projectRoot) {
 }
 
 // src/adapters/cloud-catalog.ts
-var DEFAULT_CLOUD_URL = "https://app.usefragments.com/api/catalog";
+var DEFAULT_CLOUD_URL2 = "https://app.usefragments.com/api/catalog";
+var TOKEN_CATEGORY_ALIASES2 = {
+  color: ["color", "colors", "accent", "background", "foreground", "danger", "brand"],
+  spacing: ["spacing", "space", "padding", "margin", "gap", "inset"],
+  typography: ["typography", "font", "text", "copy", "line-height", "letter"],
+  border: ["border", "borders", "stroke", "outline"],
+  radius: ["radius", "radii", "corner", "corners", "rounded"],
+  shadow: ["shadow", "shadows", "elevation"],
+  layout: ["layout", "grid", "container", "breakpoint"],
+  focus: ["focus", "ring", "focus-ring"],
+  surface: ["surface", "surfaces", "canvas", "card", "background"]
+};
 function normalizeCatalogUrl(url) {
-  if (!url) return DEFAULT_CLOUD_URL;
+  if (!url) return DEFAULT_CLOUD_URL2;
   if (url.endsWith("/api/catalog")) return url;
   return `${url.replace(/\/+$/, "")}/api/catalog`;
 }
+function normalizeValidateFixUrl(url) {
+  const base = normalizeCatalogUrl(url).replace(/\/api\/catalog$/, "");
+  return `${base}/api/context?target=validate-fix`;
+}
+function normalizeValue(value) {
+  return value?.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim() ?? "";
+}
+function canonicalizeTokenCategory(token) {
+  const candidates = [
+    token.category,
+    token.path?.[0],
+    token.name.split(/[.:/-]/)[0]
+  ].map(normalizeValue).filter(Boolean);
+  for (const candidate of candidates) {
+    for (const [canonical, aliases] of Object.entries(
+      TOKEN_CATEGORY_ALIASES2
+    )) {
+      if (candidate === canonical || aliases.some(
+        (alias) => candidate === alias || candidate.includes(alias) || alias.includes(candidate)
+      )) {
+        return canonical;
+      }
+    }
+  }
+  return candidates[0] || "other";
+}
 function groupTokens(flat) {
   const categories = {};
   const normalizedFlat = (flat ?? []).map((token) => {
-    const category = token.category?.trim() || "other";
+    const category = canonicalizeTokenCategory(token);
     const normalized = {
       name: token.name,
       category,
@@ -3761,6 +4250,7 @@ function mapComponent(component, designSystem) {
     importPath: designSystem?.importPath ?? designSystem?.packageName ?? void 0,
     publicRef: component.publicRef,
     publicSlug: component.publicSlug ?? null,
+    isCanonical: component.isCanonical ?? false,
     tier: component.tier,
     parentComponentId: component.parentComponentKey,
     parentComponentName: component.parentComponentName,
@@ -3770,17 +4260,54 @@ function mapComponent(component, designSystem) {
     }
   };
 }
+function normalizeValidateFixContext(raw) {
+  const content = raw.content;
+  if (!content || !Array.isArray(content.components)) {
+    return void 0;
+  }
+  const components = content.components.filter(
+    (component) => Boolean(component?.componentKey) && Boolean(component?.publicRef) && Boolean(component?.name) && Boolean(component?.selection)
+  ).map((component) => ({
+    componentKey: component.componentKey,
+    publicRef: component.publicRef,
+    name: component.name,
+    category: component.category ?? "uncategorized",
+    status: component.status ?? "stable",
+    tier: component.tier ?? "composition",
+    isCanonical: component.isCanonical ?? false,
+    isActive: component.isActive ?? true,
+    selection: component.selection ?? "allowed",
+    reasons: component.reasons ?? [],
+    usageGuidance: component.usageGuidance,
+    dos: component.dos ?? [],
+    donts: component.donts ?? []
+  }));
+  return {
+    version: 1,
+    catalogRevision: content.catalogRevision,
+    updatedAt: content.updatedAt,
+    policy: {
+      mode: "cloud",
+      endpoint: content.policy?.endpoint ?? "/api/govern/policy"
+    },
+    components
+  };
+}
 var CloudCatalogAdapter = class {
   constructor(options) {
     this.options = options;
   }
   name = "cloud";
   async load(_projectRoot) {
-    const response = await fetch(normalizeCatalogUrl(this.options.url), {
-      headers: {
-        Authorization: `Bearer ${this.options.apiKey}`
-      }
-    });
+    const headers = {
+      "X-API-Key": this.options.apiKey
+    };
+    const [response, validateFixResponse] = await Promise.all([
+      fetch(normalizeCatalogUrl(this.options.url), { headers }),
+      fetch(normalizeValidateFixUrl(this.options.url), { headers }).catch(
+        () => null
+      )
+    ]);
     if (!response.ok) {
       throw new Error(
         `Failed to load Cloud catalog (${response.status} ${response.statusText}).`
@@ -3822,15 +4349,31 @@ var CloudCatalogAdapter = class {
       packageMap,
       defaultPackageName: packageName
     });
+    const validateFixContext = validateFixResponse && validateFixResponse.ok ? normalizeValidateFixContext(
+      await validateFixResponse.json()
+    ) : void 0;
+    const hydratedComponents = Object.fromEntries(
+      Object.entries(snapshot.components).map(([componentId, component]) => [
+        componentId,
+        {
+          ...component,
+          isCanonical: components[componentId]?.isCanonical ?? false
+        }
+      ])
+    );
     return {
-      snapshot,
-      components: snapshot.components,
+      snapshot: {
+        ...snapshot,
+        components: hydratedComponents
+      },
+      components: hydratedComponents,
       blocks: snapshot.blocks,
       tokens: snapshot.tokens,
       graph: void 0,
       performanceSummary: void 0,
       packageMap: snapshot.packageMap,
       defaultPackageName: snapshot.defaultPackageName,
+      validateFixContext,
       capabilities: new Set(snapshot.capabilities)
     };
   }
@@ -3908,6 +4451,7 @@ function normalizeRelations(relations, fallback) {
 function buildComponent(manifest, entry, shard) {
   const sourcePackage = manifest.designSystem.importPath ?? manifest.designSystem.packageName ?? void 0;
   const component = shard.component;
+  const componentRecord = component;
   const props = normalizeProps(component.props);
   return {
     id: shard.componentId,
@@ -3944,6 +4488,7 @@ function buildComponent(manifest, entry, shard) {
     importPath: sourcePackage,
     publicRef: component.publicRef,
     publicSlug: component.publicSlug,
+    isCanonical: componentRecord.isCanonical ?? component.tier === "core",
     tier: component.tier,
     parentComponentName: component.parentComponentName,
     metadata: {
@@ -4036,9 +4581,21 @@ var BundleAdapter = class {
       packageMap,
       defaultPackageName: packageName
     });
+    const hydratedComponents = Object.fromEntries(
+      Object.entries(snapshot.components).map(([componentId, component]) => [
+        componentId,
+        {
+          ...component,
+          isCanonical: components[componentId]?.isCanonical ?? component.tier === "core"
+        }
+      ])
+    );
     return {
-      snapshot,
-      components: snapshot.components,
+      snapshot: {
+        ...snapshot,
+        components: hydratedComponents
+      },
+      components: hydratedComponents,
       blocks: snapshot.blocks,
       tokens: snapshot.tokens,
       graph: snapshot.graph,
@@ -4051,10 +4608,10 @@ var BundleAdapter = class {
 };
 
 // src/source-selection.ts
-function resolveCloudApiKey(config, fileConfig) {
+function resolveCloudApiKey2(config, fileConfig) {
   return config.cloudApiKey ?? fileConfig?.cloud?.apiKey ?? process.env.FRAGMENTS_API_KEY;
 }
-function resolveCloudUrl(fileConfig) {
+function resolveCloudUrl2(fileConfig) {
   return fileConfig?.cloud?.url ?? process.env.FRAGMENTS_CLOUD_URL;
 }
 function hasTsProject(projectRoot) {
@@ -4064,8 +4621,8 @@ function resolveDataAdapter(config, fileConfig) {
   const source = config.source ?? fileConfig?.source ?? "auto";
   const fragmentsJsonPaths = findFragmentsJson(config.projectRoot);
   const bundleManifestPaths = findBundleManifest(config.projectRoot);
-  const cloudApiKey = resolveCloudApiKey(config, fileConfig);
-  const cloudUrl = resolveCloudUrl(fileConfig);
+  const cloudApiKey = resolveCloudApiKey2(config, fileConfig);
+  const cloudUrl = resolveCloudUrl2(fileConfig);
   switch (source) {
     case "fragments-json":
       return { adapter: new FragmentsJsonAdapter(), mode: "fragments-json" };
@@ -4122,6 +4679,9 @@ function resolveSearchApiKey(config, fileConfig) {
 // src/server.ts
 var TOOL_NAMES = buildToolNames();
 var TOOLS = buildMcpTools();
+var TOOL_DEFINITION_BY_KEY = new Map(
+  MCP_TOOL_DEFINITIONS.map((definition) => [definition.key, definition])
+);
 function createMcpServer(config) {
   const server = new Server(
     {
@@ -4157,38 +4717,53 @@ function createMcpServer(config) {
     }
   }
   let cachedData = null;
+  let loadDataPromise = null;
   let resolvedRoot = null;
+  let resolveProjectRootPromise = null;
   let componentIndex = null;
   let blockIndex = null;
   let tokenIndex = null;
   async function resolveProjectRoot() {
     if (resolvedRoot) return resolvedRoot;
-    try {
-      const result = await server.listRoots();
-      if (result.roots?.length > 0) {
-        const rootUri = result.roots[0].uri;
-        resolvedRoot = fileURLToPath(rootUri);
-        return resolvedRoot;
+    if (resolveProjectRootPromise) return resolveProjectRootPromise;
+    resolveProjectRootPromise = (async () => {
+      try {
+        const result = await server.listRoots();
+        if (result.roots?.length > 0) {
+          const rootUri = result.roots[0].uri;
+          resolvedRoot = fileURLToPath(rootUri);
+          return resolvedRoot;
+        }
+      } catch {
       }
-    } catch {
+      resolvedRoot = config.projectRoot;
+      return resolvedRoot;
+    })();
+    try {
+      return await resolveProjectRootPromise;
+    } finally {
+      resolveProjectRootPromise = null;
     }
-    resolvedRoot = config.projectRoot;
-    return resolvedRoot;
   }
   async function loadData() {
     if (cachedData) return cachedData;
-    const projectRoot = await resolveProjectRoot();
-    cachedData = await adapter.load(projectRoot);
-    const allFragments = Object.values(cachedData.components);
-    const allBlocks = Object.values(cachedData.blocks ?? {});
-    componentIndex = buildComponentIndex(allFragments);
-    if (allBlocks.length > 0) {
-      blockIndex = buildBlockIndex(allBlocks);
-    }
-    if (cachedData.tokens && cachedData.tokens.total > 0) {
-      tokenIndex = buildTokenIndex(cachedData.tokens);
+    if (loadDataPromise) return loadDataPromise;
+    loadDataPromise = (async () => {
+      const projectRoot = await resolveProjectRoot();
+      const loaded = await adapter.load(projectRoot);
+      const allFragments = Object.values(loaded.components);
+      const allBlocks = Object.values(loaded.blocks ?? {});
+      componentIndex = buildComponentIndex(allFragments);
+      blockIndex = allBlocks.length > 0 ? buildBlockIndex(allBlocks) : null;
+      tokenIndex = loaded.tokens && loaded.tokens.total > 0 ? buildTokenIndex(loaded.tokens) : null;
+      cachedData = loaded;
+      return loaded;
+    })();
+    try {
+      return await loadDataPromise;
+    } finally {
+      loadDataPromise = null;
     }
-    return cachedData;
   }
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     const data = await loadData();
@@ -4220,7 +4795,7 @@ function createMcpServer(config) {
         const packageJsonPath = join8(root, "package.json");
         if (existsSync9(packageJsonPath)) {
           try {
-            const content = readFileSync7(packageJsonPath, "utf-8");
+            const content = readFileSync6(packageJsonPath, "utf-8");
             const pkg = JSON.parse(content);
             if (pkg.name) {
               return pkg.name;
@@ -4234,6 +4809,23 @@ function createMcpServer(config) {
     };
     try {
       const toolKey = registry.resolveKey(name);
+      const definition = TOOL_DEFINITION_BY_KEY.get(toolKey);
+      const argumentKeys = Object.keys(args ?? {});
+      const allowedKeys = new Set(Object.keys(definition?.params ?? {}));
+      const unknownKeys = definition ? argumentKeys.filter((key) => !allowedKeys.has(key)) : [];
+      if (unknownKeys.length > 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: `Unknown argument(s) for ${toolKey}: ${unknownKeys.join(", ")}`
+              })
+            }
+          ],
+          isError: true
+        };
+      }
       const mCtx = {
         toolName: name,
         toolKey,
@@ -4290,4 +4882,4 @@ export {
   startMcpServer,
   createSandboxServer
 };
-//# sourceMappingURL=chunk-LZW5KUXV.js.map
+//# sourceMappingURL=chunk-6JMX4AMO.js.map