@fragments-sdk/cli 0.15.9 → 0.15.10

package/dist/mcp-bin.js

@@ -18,10 +18,26 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { buildMcpTools, buildToolNames, CLI_TOOL_EXTENSIONS } from "@fragments-sdk/context/mcp-tools";
+import { ComponentGraphEngine, deserializeGraph } from "@fragments-sdk/context/graph";
 import { readFile } from "fs/promises";
-import { existsSync, readFileSync, readdirSync } from "fs";
+import { existsSync, readFileSync as readFileSync2, readdirSync } from "fs";
 import { join, dirname, resolve } from "path";
 import { createRequire } from "module";
+
+// src/mcp/version.ts
+import { readFileSync } from "fs";
+function readPackageVersion() {
+  try {
+    const raw = readFileSync(new URL("../../package.json", import.meta.url), "utf-8");
+    const pkg = JSON.parse(raw);
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var MCP_SERVER_VERSION = readPackageVersion();
+
+// src/mcp/server.ts
 var _service = null;
 async function getService() {
   if (!_service) {
@@ -35,7 +51,78 @@ async function getService() {
   }
   return _service;
 }
-var TOOL_NAMES = buildToolNames(BRAND.nameLower);
+var TOOL_NAMES = buildToolNames();
+var TOOLS = buildMcpTools(void 0, CLI_TOOL_EXTENSIONS);
+var DISCOVER_SYNONYM_MAP = {
+  form: ["input", "field", "submit", "validation"],
+  input: ["form", "field", "text", "entry"],
+  button: ["action", "click", "submit", "trigger"],
+  action: ["button", "click", "trigger"],
+  submit: ["button", "form", "action", "send"],
+  alert: ["notification", "message", "warning", "error", "feedback"],
+  notification: ["alert", "message", "toast"],
+  feedback: ["form", "comment", "review", "rating"],
+  card: ["container", "panel", "box", "content"],
+  toggle: ["switch", "checkbox", "boolean", "on/off"],
+  switch: ["toggle", "checkbox", "boolean"],
+  badge: ["tag", "label", "status", "indicator"],
+  status: ["badge", "indicator", "state"],
+  login: ["auth", "signin", "authentication", "form"],
+  auth: ["login", "signin", "authentication"],
+  chat: ["message", "conversation", "ai"],
+  table: ["data", "grid", "list", "rows"],
+  layout: ["stack", "grid", "box", "container", "page"],
+  landing: ["page", "hero", "marketing", "section", "layout"],
+  hero: ["landing", "marketing", "banner", "headline", "section"],
+  marketing: ["landing", "hero", "pricing", "testimonial", "cta"]
+};
+var TOKEN_CATEGORY_ALIASES = {
+  colors: ["color", "colors", "accent", "background", "foreground", "semantic", "theme"],
+  spacing: ["spacing", "space", "spaces", "padding", "margin", "gap", "inset"],
+  typography: ["typography", "type", "font", "fonts", "letter", "line-height"],
+  surfaces: ["surface", "surfaces", "canvas", "backgrounds"],
+  shadows: ["shadow", "shadows", "elevation"],
+  radius: ["radius", "radii", "corner", "corners", "round", "rounded", "rounding"],
+  borders: ["border", "borders", "stroke", "outline"],
+  text: ["text", "copy", "content"],
+  focus: ["focus", "ring", "focus-ring"],
+  layout: ["layout", "container", "grid", "breakpoint"],
+  code: ["code"],
+  "component-sizing": ["component-sizing", "sizing", "size", "sizes"]
+};
+var FRIENDLY_TOKEN_CATEGORY_ORDER = [
+  "colors",
+  "spacing",
+  "typography",
+  "surfaces",
+  "shadows",
+  "radius",
+  "borders",
+  "text",
+  "focus",
+  "layout",
+  "code",
+  "component-sizing"
+];
+var STYLE_QUERY_TERMS = /* @__PURE__ */ new Set([
+  "color",
+  "colors",
+  "spacing",
+  "padding",
+  "margin",
+  "font",
+  "border",
+  "radius",
+  "shadow",
+  "variable",
+  "token",
+  "css",
+  "theme",
+  "background",
+  "hover",
+  "surface",
+  "focus"
+]);
 var PLACEHOLDER_PATTERNS = [
   /^\w+ component is needed$/i,
   /^Alternative component is more appropriate$/i,
@@ -47,6 +134,168 @@ function filterPlaceholders(items) {
     (item) => !PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(item.trim()))
   );
 }
+function parsePositiveLimit(value, defaultValue, max) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return defaultValue;
+  }
+  return Math.min(Math.max(Math.floor(value), 1), max);
+}
+function resolveVerbosity(value, compactAlias = false) {
+  if (value === "compact" || value === "standard" || value === "full") {
+    return value;
+  }
+  return compactAlias ? "compact" : "standard";
+}
+function normalizeSearchText(value) {
+  return (value ?? "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+function splitSearchTerms(value) {
+  return Array.from(new Set(normalizeSearchText(value).split(/\s+/).filter(Boolean)));
+}
+function expandSearchTerms(terms) {
+  const expanded = new Set(terms);
+  for (const term of terms) {
+    for (const synonym of DISCOVER_SYNONYM_MAP[term] ?? []) {
+      expanded.add(synonym);
+    }
+  }
+  return Array.from(expanded);
+}
+function countTermMatches(haystack, terms) {
+  return terms.reduce((count, term) => count + (haystack.includes(term) ? 1 : 0), 0);
+}
+function truncateCodePreview(code, previewLines = 20, threshold = 30) {
+  const lines = code.split("\n");
+  if (lines.length <= threshold) {
+    return code;
+  }
+  return `${lines.slice(0, previewLines).join("\n")}
+// ... truncated (${lines.length} lines total)`;
+}
+function assignConfidence(score) {
+  if (score >= 25) return "high";
+  if (score >= 15) return "medium";
+  return "low";
+}
+function canonicalizeTokenCategory(categoryKey) {
+  const normalized = normalizeSearchText(categoryKey);
+  for (const canonical of FRIENDLY_TOKEN_CATEGORY_ORDER) {
+    if (normalized === canonical) {
+      return canonical;
+    }
+    const aliases = TOKEN_CATEGORY_ALIASES[canonical] ?? [];
+    if (normalized.includes(canonical) || aliases.some((alias) => normalized.includes(alias))) {
+      return canonical;
+    }
+  }
+  return void 0;
+}
+function resolveTokenCategoryKeys(tokenData, requestedCategory) {
+  if (!requestedCategory) {
+    return { keys: Object.keys(tokenData.categories) };
+  }
+  const normalized = normalizeSearchText(requestedCategory);
+  if (!normalized) {
+    return { keys: Object.keys(tokenData.categories) };
+  }
+  const keys = Object.keys(tokenData.categories);
+  const exactRawMatches = keys.filter((key) => normalizeSearchText(key) === normalized);
+  if (exactRawMatches.length > 0) {
+    return { keys: exactRawMatches, canonical: canonicalizeTokenCategory(exactRawMatches[0]) };
+  }
+  const canonical = FRIENDLY_TOKEN_CATEGORY_ORDER.find((candidate) => {
+    if (candidate === normalized) return true;
+    return (TOKEN_CATEGORY_ALIASES[candidate] ?? []).includes(normalized);
+  });
+  if (canonical) {
+    const aliases = [canonical, ...TOKEN_CATEGORY_ALIASES[canonical] ?? []];
+    const aliasMatches = keys.filter((key) => {
+      const normalizedKey = normalizeSearchText(key);
+      return aliases.some((alias) => normalizedKey.includes(alias));
+    });
+    if (aliasMatches.length > 0) {
+      return { keys: aliasMatches, canonical };
+    }
+  }
+  const partialMatches = keys.filter((key) => normalizeSearchText(key).includes(normalized));
+  return { keys: partialMatches, canonical };
+}
+function summarizeFriendlyTokenCategories(tokenData) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const [rawCategory, tokens] of Object.entries(tokenData.categories)) {
+    const canonical = canonicalizeTokenCategory(rawCategory) ?? rawCategory;
+    counts.set(canonical, (counts.get(canonical) ?? 0) + tokens.length);
+  }
+  const ordered = [];
+  for (const category of FRIENDLY_TOKEN_CATEGORY_ORDER) {
+    const count = counts.get(category);
+    if (count) {
+      ordered.push({ category, count });
+      counts.delete(category);
+    }
+  }
+  for (const [category, count] of counts) {
+    ordered.push({ category, count });
+  }
+  return ordered;
+}
+function limitTokensPerCategory(categories, limit) {
+  if (limit === void 0) {
+    return {
+      categories,
+      total: Object.values(categories).reduce((sum, entries) => sum + entries.length, 0)
+    };
+  }
+  const limited = {};
+  let total = 0;
+  for (const [category, entries] of Object.entries(categories)) {
+    const sliced = entries.slice(0, limit);
+    if (sliced.length === 0) continue;
+    limited[category] = sliced;
+    total += sliced.length;
+  }
+  return { categories: limited, total };
+}
+function scoreBlockMatch(block, query, preferredComponents = []) {
+  const normalizedQuery = normalizeSearchText(query);
+  if (!normalizedQuery) {
+    return 0;
+  }
+  const terms = splitSearchTerms(query);
+  const expandedTerms = expandSearchTerms(terms);
+  const synonymOnlyTerms = expandedTerms.filter((term) => !terms.includes(term));
+  const nameText = normalizeSearchText(block.name);
+  const descriptionText = normalizeSearchText(block.description);
+  const tagsText = normalizeSearchText((block.tags ?? []).join(" "));
+  const componentsText = normalizeSearchText(block.components.join(" "));
+  const categoryText = normalizeSearchText(block.category);
+  let score = 0;
+  if (nameText === normalizedQuery) score += 120;
+  else if (nameText.includes(normalizedQuery)) score += 90;
+  if (tagsText.includes(normalizedQuery)) score += 70;
+  if (descriptionText.includes(normalizedQuery)) score += 55;
+  if (categoryText.includes(normalizedQuery)) score += 40;
+  if (componentsText.includes(normalizedQuery)) score += 25;
+  score += countTermMatches(nameText, terms) * 30;
+  score += countTermMatches(tagsText, terms) * 22;
+  score += countTermMatches(descriptionText, terms) * 16;
+  score += countTermMatches(categoryText, terms) * 14;
+  score += countTermMatches(componentsText, terms) * 10;
+  score += countTermMatches(nameText, synonymOnlyTerms) * 12;
+  score += countTermMatches(tagsText, synonymOnlyTerms) * 10;
+  score += countTermMatches(descriptionText, synonymOnlyTerms) * 6;
+  const preferredMatches = block.components.filter(
+    (component) => preferredComponents.some((preferred) => preferred.toLowerCase() === component.toLowerCase())
+  );
+  score += preferredMatches.length * 18;
+  return score;
+}
+function rankBlocks(blocks, query, preferredComponents = []) {
+  return blocks.map((block) => ({
+    block,
+    score: scoreBlockMatch(block, query, preferredComponents)
+  })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score || a.block.name.localeCompare(b.block.name));
+}
 function resolveWorkspaceGlob(baseDir, pattern) {
   const parts = pattern.split("/");
   let dirs = [baseDir];
@@ -77,7 +326,7 @@ function getWorkspaceDirs(rootDir) {
   const rootPkgPath = join(rootDir, "package.json");
   if (existsSync(rootPkgPath)) {
     try {
-      const rootPkg = JSON.parse(readFileSync(rootPkgPath, "utf-8"));
+      const rootPkg = JSON.parse(readFileSync2(rootPkgPath, "utf-8"));
       const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : rootPkg.workspaces?.packages;
       if (Array.isArray(workspaces)) {
         for (const pattern of workspaces) {
@@ -91,7 +340,7 @@ function getWorkspaceDirs(rootDir) {
   const pnpmWsPath = join(rootDir, "pnpm-workspace.yaml");
   if (existsSync(pnpmWsPath)) {
     try {
-      const content = readFileSync(pnpmWsPath, "utf-8");
+      const content = readFileSync2(pnpmWsPath, "utf-8");
       const lines = content.split("\n");
       let inPackages = false;
       for (const line of lines) {
@@ -124,7 +373,7 @@ function resolveDepPackageJson(localRequire, depName) {
     while (true) {
       const candidate = join(dir, "package.json");
       if (existsSync(candidate)) {
-        const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+        const pkg = JSON.parse(readFileSync2(candidate, "utf-8"));
         if (pkg.name === depName) return candidate;
       }
       const parent = dirname(dir);
@@ -139,7 +388,7 @@ function findFragmentsInDeps(dir, found) {
   const pkgJsonPath = join(dir, "package.json");
   if (!existsSync(pkgJsonPath)) return;
   try {
-    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+    const pkgJson = JSON.parse(readFileSync2(pkgJsonPath, "utf-8"));
     const allDeps = {
       ...pkgJson.dependencies,
       ...pkgJson.devDependencies
@@ -149,7 +398,7 @@ function findFragmentsInDeps(dir, found) {
       try {
         const depPkgPath = resolveDepPackageJson(localRequire, depName);
         if (!depPkgPath) continue;
-        const depPkg = JSON.parse(readFileSync(depPkgPath, "utf-8"));
+        const depPkg = JSON.parse(readFileSync2(depPkgPath, "utf-8"));
         if (depPkg.fragments) {
           const fragmentsPath = join(dirname(depPkgPath), depPkg.fragments);
           if (existsSync(fragmentsPath) && !found.includes(fragmentsPath)) {
@@ -185,12 +434,11 @@ function findFragmentsJson(startDir) {
   }
   return found;
 }
-var TOOLS = buildMcpTools(BRAND.nameLower, CLI_TOOL_EXTENSIONS);
 function createMcpServer(config) {
   const server = new Server(
     {
       name: `${BRAND.nameLower}-mcp`,
-      version: "0.0.1"
+      version: MCP_SERVER_VERSION
     },
     {
       capabilities: {
@@ -327,21 +575,24 @@ function createMcpServer(config) {
           const data = await loadFragments();
           const useCase = args2?.useCase ?? void 0;
           const componentForAlts = args2?.component ?? void 0;
-          const category = args2?.category ?? void 0;
-          const search = args2?.search?.toLowerCase() ?? void 0;
+          const category = normalizeSearchText(args2?.category) || void 0;
+          const search = normalizeSearchText(args2?.search) || void 0;
           const status = args2?.status ?? void 0;
           const format = args2?.format ?? "markdown";
           const compact = args2?.compact ?? false;
           const includeCode = args2?.includeCode ?? false;
           const includeRelations = args2?.includeRelations ?? false;
-          if (compact || args2?.format && !useCase && !componentForAlts && !category && !search && !status) {
+          const verbosity = resolveVerbosity(args2?.verbosity, compact);
+          const listLimit = parsePositiveLimit(args2?.limit, void 0, 50);
+          const suggestLimit = parsePositiveLimit(args2?.limit, 10, 25) ?? 10;
+          if (args2?.format && !useCase && !componentForAlts && !category && !search && !status) {
             const fragments2 = Object.values(data.fragments);
             const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
             const { content: ctxContent, tokenEstimate } = generateContext(fragments2, {
               format,
-              compact,
+              compact: verbosity === "compact",
               include: {
-                code: includeCode,
+                code: includeCode || verbosity === "full",
                 relations: includeRelations
               }
             }, allBlocks);
@@ -356,29 +607,9 @@ function createMcpServer(config) {
           if (useCase) {
             const useCaseLower = useCase.toLowerCase();
             const context = args2?.context?.toLowerCase() ?? "";
-            const searchTerms = `${useCaseLower} ${context}`.split(/\s+/).filter(Boolean);
-            const synonymMap = {
-              "form": ["input", "field", "submit", "validation"],
-              "input": ["form", "field", "text", "entry"],
-              "button": ["action", "click", "submit", "trigger"],
-              "action": ["button", "click", "trigger"],
-              "alert": ["notification", "message", "warning", "error", "feedback"],
-              "notification": ["alert", "message", "toast"],
-              "card": ["container", "panel", "box", "content"],
-              "toggle": ["switch", "checkbox", "boolean", "on/off"],
-              "switch": ["toggle", "checkbox", "boolean"],
-              "badge": ["tag", "label", "status", "indicator"],
-              "status": ["badge", "indicator", "state"],
-              "login": ["auth", "signin", "authentication", "form"],
-              "auth": ["login", "signin", "authentication"]
-            };
-            const expandedTerms = new Set(searchTerms);
-            searchTerms.forEach((term) => {
-              const synonyms = synonymMap[term];
-              if (synonyms) {
-                synonyms.forEach((syn) => expandedTerms.add(syn));
-              }
-            });
+            const searchTerms = splitSearchTerms(`${useCaseLower} ${context}`);
+            const expandedTerms = expandSearchTerms(searchTerms);
+            const synonymOnlyTerms = expandedTerms.filter((term) => !searchTerms.includes(term));
             const scored = Object.values(data.fragments).map((s) => {
               let score = 0;
               const reasons = [];
@@ -386,7 +617,7 @@ function createMcpServer(config) {
               if (searchTerms.some((term) => nameLower.includes(term))) {
                 score += 15;
                 reasons.push(`Name matches search`);
-              } else if (Array.from(expandedTerms).some((term) => nameLower.includes(term))) {
+              } else if (expandedTerms.some((term) => nameLower.includes(term))) {
                 score += 8;
                 reasons.push(`Name matches related term`);
               }
@@ -410,9 +641,7 @@ function createMcpServer(config) {
                 score += whenMatches.length * 10;
                 reasons.push(`Use cases match: "${whenMatches.join(", ")}"`);
               }
-              const expandedWhenMatches = Array.from(expandedTerms).filter(
-                (term) => !searchTerms.includes(term) && whenUsed.includes(term)
-              );
+              const expandedWhenMatches = synonymOnlyTerms.filter((term) => whenUsed.includes(term));
               if (expandedWhenMatches.length > 0) {
                 score += expandedWhenMatches.length * 5;
                 reasons.push(`Related use cases: "${expandedWhenMatches.join(", ")}"`);
@@ -466,18 +695,17 @@ function createMcpServer(config) {
               if (count < 2 || suggestions.length < 3) {
                 suggestions.push(item);
                 categoryCount[cat] = count + 1;
-                if (suggestions.length >= 5) break;
+                if (suggestions.length >= suggestLimit) 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;
-            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 isStyleQuery = splitSearchTerms(useCaseLower).some((term) => STYLE_QUERY_TERMS.has(term));
             const noMatch = suggestions.length === 0;
             const weakMatch = !noMatch && suggestions.every((s) => s.confidence === "low");
             let recommendation;
             let nextStep;
             if (noMatch) {
-              recommendation = isStyleQuery ? `No matching components found. Your query seems styling-related \u2014 try ${TOOL_NAMES.tokens} to find CSS custom properties.` : "No matching components found. Try different keywords or browse all components with fragments_discover.";
+              recommendation = isStyleQuery ? `No matching components found. Your query seems styling-related \u2014 try ${TOOL_NAMES.tokens} to find CSS custom properties.` : `No matching components found. Try different keywords or browse all components with ${TOOL_NAMES.discover}.`;
               nextStep = isStyleQuery ? `Use ${TOOL_NAMES.tokens}(search: "${searchTerms[0]}") to find design tokens.` : void 0;
             } else if (weakMatch) {
               recommendation = `Weak matches only \u2014 ${suggestions[0].component} might work but confidence is low.${isStyleQuery ? ` If you need a CSS variable, try ${TOOL_NAMES.tokens}.` : ""}`;
@@ -486,13 +714,20 @@ function createMcpServer(config) {
               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 suggestionResults = suggestions.map(
+              ({ score, ...rest }) => verbosity === "full" ? { ...rest, score } : rest
+            );
             return {
               content: [{
                 type: "text",
                 text: JSON.stringify({
                   useCase,
                   context: context || void 0,
-                  suggestions: suggestions.map(({ score, ...rest }) => rest),
+                  suggestions: verbosity === "compact" ? suggestionResults.map((suggestion) => ({
+                    component: suggestion.component,
+                    description: suggestion.description,
+                    confidence: suggestion.confidence
+                  })) : suggestionResults,
                   noMatch,
                   weakMatch,
                   recommendation,
@@ -507,7 +742,7 @@ function createMcpServer(config) {
               (s) => s.meta.name.toLowerCase() === componentForAlts.toLowerCase()
             );
             if (!fragment) {
-              throw new Error(`Component "${componentForAlts}" not found. Use fragments_discover to see available components.`);
+              throw new Error(`Component "${componentForAlts}" not found. Use ${TOOL_NAMES.discover} to see available components.`);
             }
             const relations = fragment.relations ?? [];
             const referencedBy = Object.values(data.fragments).filter(
@@ -542,7 +777,7 @@ function createMcpServer(config) {
             };
           }
           const fragments = Object.values(data.fragments).filter((s) => {
-            if (category && s.meta.category !== category) return false;
+            if (category && normalizeSearchText(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);
@@ -551,22 +786,46 @@ function createMcpServer(config) {
               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 ?? []
-          }));
+          });
+          const total = fragments.length;
+          const limitedFragments = listLimit === void 0 ? fragments : fragments.slice(0, listLimit);
+          const formattedFragments = limitedFragments.map((s) => {
+            const base = {
+              name: s.meta.name,
+              category: s.meta.category,
+              description: s.meta.description,
+              status: s.meta.status ?? "stable",
+              variantCount: s.variants.length
+            };
+            if (verbosity === "compact") {
+              return base;
+            }
+            if (verbosity === "full") {
+              return {
+                ...base,
+                tags: s.meta.tags ?? [],
+                usage: {
+                  when: filterPlaceholders(s.usage?.when).slice(0, 3),
+                  whenNot: filterPlaceholders(s.usage?.whenNot).slice(0, 2)
+                },
+                relations: s.relations ?? [],
+                codeExample: s.variants[0]?.code
+              };
+            }
+            return {
+              ...base,
+              tags: s.meta.tags ?? []
+            };
+          });
           return {
             content: [{
               type: "text",
               text: JSON.stringify({
-                total: fragments.length,
-                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
+                total,
+                returned: formattedFragments.length,
+                fragments: formattedFragments,
+                categories: [...new Set(fragments.map((s) => s.meta.category))],
+                hint: total === 0 ? "No components found. Try broader search terms or check available categories." : total > 5 ? `Use ${TOOL_NAMES.discover} with useCase for recommendations, or ${TOOL_NAMES.inspect} for details on a specific component.` : void 0
               }, null, 2)
             }]
           };
@@ -588,7 +847,7 @@ function createMcpServer(config) {
             (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
           );
           if (!fragment) {
-            throw new Error(`Component "${componentName}" not found. Use fragments_discover to see available components.`);
+            throw new Error(`Component "${componentName}" not found. Use ${TOOL_NAMES.discover} to see available components.`);
           }
           const pkgName = await getPackageName(fragment.meta.name);
           let variants = fragment.variants;
@@ -691,9 +950,11 @@ function createMcpServer(config) {
         case TOOL_NAMES.blocks: {
           const data = await loadFragments();
           const blockName = args2?.name;
-          const search = args2?.search?.toLowerCase() ?? void 0;
+          const search = args2?.search ?? void 0;
           const component = args2?.component?.toLowerCase() ?? void 0;
-          const category = args2?.category?.toLowerCase() ?? void 0;
+          const category = normalizeSearchText(args2?.category) || void 0;
+          const blocksLimit = parsePositiveLimit(args2?.limit, void 0, 50);
+          const verbosity = resolveVerbosity(args2?.verbosity);
           const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
           if (allBlocks.length === 0) {
             return {
@@ -709,21 +970,10 @@ function createMcpServer(config) {
           }
           let filtered = allBlocks;
           if (blockName) {
-            filtered = filtered.filter(
-              (b) => b.name.toLowerCase() === blockName.toLowerCase()
-            );
+            filtered = filtered.filter((b) => b.name.toLowerCase() === blockName.toLowerCase());
           }
           if (search) {
-            filtered = filtered.filter((b) => {
-              const haystack = [
-                b.name,
-                b.description,
-                ...b.tags ?? [],
-                ...b.components,
-                b.category
-              ].join(" ").toLowerCase();
-              return haystack.includes(search);
-            });
+            filtered = rankBlocks(filtered, search).map(({ block }) => block);
           }
           if (component) {
             filtered = filtered.filter(
@@ -732,15 +982,42 @@ function createMcpServer(config) {
           }
           if (category) {
             filtered = filtered.filter(
-              (b) => b.category.toLowerCase() === category
+              (b) => normalizeSearchText(b.category) === category
             );
           }
+          if (!search) {
+            filtered = [...filtered].sort((a, b) => a.name.localeCompare(b.name));
+          }
+          const total = filtered.length;
+          if (blocksLimit !== void 0) {
+            filtered = filtered.slice(0, blocksLimit);
+          }
+          const blocks = filtered.map((block) => {
+            const base = {
+              name: block.name,
+              description: block.description,
+              category: block.category,
+              components: block.components,
+              tags: block.tags
+            };
+            if (verbosity === "compact") {
+              return base;
+            }
+            return {
+              ...base,
+              code: verbosity === "full" ? block.code : truncateCodePreview(block.code)
+            };
+          });
           return {
             content: [{
               type: "text",
               text: JSON.stringify({
-                total: filtered.length,
-                blocks: filtered
+                total,
+                returned: blocks.length,
+                blocks,
+                ...total === 0 && {
+                  hint: "No blocks matching your query. Try broader search terms."
+                }
               }, null, 2)
             }]
           };
@@ -750,8 +1027,9 @@ function createMcpServer(config) {
         // ================================================================
         case TOOL_NAMES.tokens: {
           const data = await loadFragments();
-          const category = args2?.category?.toLowerCase() ?? void 0;
-          const search = args2?.search?.toLowerCase() ?? void 0;
+          const category = args2?.category ?? void 0;
+          const search = normalizeSearchText(args2?.search) || void 0;
+          const tokensLimit = parsePositiveLimit(args2?.limit, search ? 25 : void 0, 100);
           const tokenData = data.tokens;
           if (!tokenData || tokenData.total === 0) {
             return {
@@ -766,24 +1044,31 @@ function createMcpServer(config) {
             };
           }
           const filteredCategories = {};
-          let filteredTotal = 0;
+          const resolvedCategory = resolveTokenCategoryKeys(tokenData, category);
+          const searchCategoryKeys = search ? resolveTokenCategoryKeys(tokenData, search).keys : [];
           for (const [cat, tokens] of Object.entries(tokenData.categories)) {
-            if (category && cat !== category) continue;
+            if (category && !resolvedCategory.keys.includes(cat)) continue;
             let filtered = tokens;
             if (search) {
-              filtered = tokens.filter(
-                (t) => t.name.toLowerCase().includes(search) || t.description && t.description.toLowerCase().includes(search)
-              );
+              const normalizedCategory = normalizeSearchText(cat);
+              const searchMatchesCategory = searchCategoryKeys.includes(cat);
+              if (!searchMatchesCategory) {
+                filtered = tokens.filter(
+                  (token) => token.name.toLowerCase().includes(search) || token.description && token.description.toLowerCase().includes(search) || normalizedCategory.includes(search)
+                );
+              }
             }
             if (filtered.length > 0) {
               filteredCategories[cat] = filtered;
-              filteredTotal += filtered.length;
             }
           }
+          const limited = limitTokensPerCategory(filteredCategories, tokensLimit);
+          const filteredTotal = limited.total;
+          const friendlyCategories = summarizeFriendlyTokenCategories(tokenData);
+          const availableCategoryNames = friendlyCategories.map((entry) => entry.category);
           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;
+            hint = search ? `No tokens matching "${search}". Try categories like: ${availableCategoryNames.join(", ")}` : category ? `Category "${category}" not found. Try categories like: ${availableCategoryNames.join(", ")}` : void 0;
           } else if (!category && !search) {
             hint = `Use var(--token-name) in your CSS/styles. Filter by category or search to narrow results.`;
           }
@@ -794,12 +1079,10 @@ function createMcpServer(config) {
                 prefix: tokenData.prefix,
                 total: filteredTotal,
                 totalAvailable: tokenData.total,
-                categories: filteredCategories,
+                categories: limited.categories,
                 ...hint && { hint },
                 ...!category && !search && {
-                  availableCategories: Object.entries(tokenData.categories).map(
-                    ([cat, tokens]) => ({ category: cat, count: tokens.length })
-                  )
+                  availableCategories: friendlyCategories
                 }
               }, null, 2)
             }]
@@ -815,58 +1098,55 @@ function createMcpServer(config) {
             throw new Error("useCase is required");
           }
           const useCaseLower = useCase.toLowerCase();
-          const searchTerms = useCaseLower.split(/\s+/).filter(Boolean);
-          const synonymMap = {
-            "form": ["input", "field", "submit", "validation"],
-            "input": ["form", "field", "text", "entry"],
-            "button": ["action", "click", "submit", "trigger"],
-            "alert": ["notification", "message", "warning", "error", "feedback"],
-            "notification": ["alert", "message", "toast"],
-            "card": ["container", "panel", "box", "content"],
-            "toggle": ["switch", "checkbox", "boolean"],
-            "badge": ["tag", "label", "status", "indicator"],
-            "login": ["auth", "signin", "authentication", "form"],
-            "chat": ["message", "conversation", "ai"],
-            "table": ["data", "grid", "list", "rows"]
-          };
-          const expandedTerms = new Set(searchTerms);
-          searchTerms.forEach((term) => {
-            const synonyms = synonymMap[term];
-            if (synonyms) synonyms.forEach((syn) => expandedTerms.add(syn));
-          });
+          const searchTerms = splitSearchTerms(useCaseLower);
+          const expandedTerms = expandSearchTerms(searchTerms);
+          const synonymOnlyTerms = expandedTerms.filter((term) => !searchTerms.includes(term));
+          const verbosity = resolveVerbosity(args2?.verbosity);
+          const componentLimit = parsePositiveLimit(args2?.limit, 5, 15) ?? 5;
           const scored = Object.values(data.fragments).map((s) => {
             let score = 0;
             const nameLower = s.meta.name.toLowerCase();
             if (searchTerms.some((t) => nameLower.includes(t))) score += 15;
-            else if (Array.from(expandedTerms).some((t) => nameLower.includes(t))) score += 8;
+            else if (expandedTerms.some((t) => nameLower.includes(t))) score += 8;
             const desc = s.meta.description?.toLowerCase() ?? "";
             score += searchTerms.filter((t) => desc.includes(t)).length * 6;
             const tags = s.meta.tags?.map((t) => t.toLowerCase()) ?? [];
             score += searchTerms.filter((t) => tags.some((tag) => tag.includes(t))).length * 4;
             const whenUsed = s.usage?.when?.join(" ").toLowerCase() ?? "";
             score += searchTerms.filter((t) => whenUsed.includes(t)).length * 10;
-            score += Array.from(expandedTerms).filter((t) => !searchTerms.includes(t) && whenUsed.includes(t)).length * 5;
+            score += synonymOnlyTerms.filter((t) => whenUsed.includes(t)).length * 5;
             if (s.meta.category && searchTerms.some((t) => s.meta.category.toLowerCase().includes(t))) score += 8;
             if (s.meta.status === "stable") score += 5;
             if (s.meta.status === "deprecated") score -= 25;
             return { fragment: s, score };
           });
-          const topMatches = scored.filter((s) => s.score >= 8).sort((a, b) => b.score - a.score).slice(0, 3);
+          const topMatches = scored.filter((s) => s.score >= 8).sort((a, b) => b.score - a.score).slice(0, componentLimit);
           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) => ({
+              const confidence = assignConfidence(score);
+              if (verbosity === "compact") {
+                return {
+                  name: s.meta.name,
+                  description: s.meta.description,
+                  confidence,
+                  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(
                 ([name2, p]) => `${name2}${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 >= 25 ? "high" : score >= 15 ? "medium" : "low",
+                confidence,
                 import: `import { ${s.meta.name} } from '${pkgName}';`,
                 props: propsSummary,
                 examples,
@@ -876,21 +1156,39 @@ function createMcpServer(config) {
             })
           );
           const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
-          const matchingBlocks = allBlocks.filter((b) => {
-            const haystack = [b.name, b.description, ...b.tags ?? [], ...b.components, b.category].join(" ").toLowerCase();
-            return searchTerms.some((t) => haystack.includes(t)) || topMatches.some(({ fragment }) => b.components.some((c) => c.toLowerCase() === fragment.meta.name.toLowerCase()));
-          }).slice(0, 2).map((b) => ({ name: b.name, description: b.description, components: b.components, code: b.code }));
+          const preferredComponents = topMatches.map(({ fragment }) => fragment.meta.name);
+          const matchingBlocks = rankBlocks(allBlocks, useCase, preferredComponents).slice(0, 2).map(({ block }) => {
+            const base = {
+              name: block.name,
+              description: block.description,
+              components: block.components
+            };
+            if (verbosity === "compact") {
+              return base;
+            }
+            return {
+              ...base,
+              code: verbosity === "full" ? block.code : truncateCodePreview(block.code)
+            };
+          });
           const tokenData = data.tokens;
           let relevantTokens;
           if (tokenData) {
-            const STYLE_KEYWORDS = ["color", "spacing", "padding", "margin", "font", "border", "radius", "shadow", "background", "hover", "theme"];
-            const styleTerms = searchTerms.filter((t) => STYLE_KEYWORDS.includes(t));
-            if (styleTerms.length > 0) {
+            const styleCategories = Array.from(new Set(searchTerms.flatMap((term) => {
+              return FRIENDLY_TOKEN_CATEGORY_ORDER.filter((categoryName) => {
+                if (categoryName === term) return true;
+                return (TOKEN_CATEGORY_ALIASES[categoryName] ?? []).includes(term);
+              });
+            })));
+            if (styleCategories.length > 0) {
               relevantTokens = {};
-              for (const [cat, tokens] of Object.entries(tokenData.categories)) {
-                const matching = tokens.filter((t) => styleTerms.some((st) => t.name.includes(st) || cat.includes(st)));
-                if (matching.length > 0) {
-                  relevantTokens[cat] = matching.map((t) => t.name);
+              for (const categoryName of styleCategories) {
+                const matchingCategoryKeys = resolveTokenCategoryKeys(tokenData, categoryName).keys;
+                for (const key of matchingCategoryKeys) {
+                  const tokens = tokenData.categories[key];
+                  if (tokens && tokens.length > 0) {
+                    relevantTokens[key] = tokens.slice(0, 5).map((token) => token.name);
+                  }
                 }
               }
               if (Object.keys(relevantTokens).length === 0) relevantTokens = void 0;
@@ -903,7 +1201,7 @@ function createMcpServer(config) {
                 useCase,
                 components,
                 blocks: matchingBlocks.length > 0 ? matchingBlocks : void 0,
-                tokens: relevantTokens,
+                tokens: verbosity === "compact" ? void 0 : relevantTokens,
                 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)
@@ -1126,7 +1424,7 @@ 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.`);
+            throw new Error(`Component "${componentName}" not found. Use ${TOOL_NAMES.discover} to see available components.`);
           }
           const baseUrl = config.viewerUrl ?? "http://localhost:6006";
           const fixUrl = `${baseUrl}/fragments/fix`;
@@ -1160,7 +1458,7 @@ Suggestion: ${result.suggestion}` : ""}`
                   patches: result.patches,
                   summary: result.summary,
                   patchCount: result.patches.length,
-                  nextStep: result.patches.length > 0 ? "Apply patches using your editor or `patch` command, then run fragments_render with baseline:true to confirm fixes." : void 0
+                  nextStep: result.patches.length > 0 ? `Apply patches using your editor or \`patch\` command, then run ${TOOL_NAMES.render} with baseline:true to confirm fixes.` : void 0
                 }, null, 2)
               }]
             };
@@ -1175,6 +1473,355 @@ Suggestion: ${result.suggestion}` : ""}`
           }
         }
         // ================================================================
+        // GRAPH — query component relationship graph
+        // ================================================================
+        case TOOL_NAMES.graph: {
+          const data = await loadFragments();
+          const mode = args2?.mode ?? "health";
+          const componentName = args2?.component;
+          const target = args2?.target;
+          const edgeTypes = args2?.edgeTypes;
+          const maxDepth = args2?.maxDepth ?? 3;
+          if (!data.graph) {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  error: "No graph data available. Run `fragments build` to generate the component graph.",
+                  hint: "The graph is built automatically during `fragments build` and embedded in fragments.json."
+                })
+              }],
+              isError: true
+            };
+          }
+          const graph = deserializeGraph(data.graph);
+          const blocks = data.blocks ? Object.fromEntries(
+            Object.entries(data.blocks).map(([key, value]) => [key, { components: value.components }])
+          ) : void 0;
+          const engine = new ComponentGraphEngine(graph, blocks);
+          const requireComponent = (modeName) => {
+            if (!componentName) {
+              return `component is required for ${modeName} mode`;
+            }
+            if (!engine.hasNode(componentName)) {
+              return `Component "${componentName}" not found in graph.`;
+            }
+            return void 0;
+          };
+          switch (mode) {
+            case "health": {
+              const health = engine.getHealth();
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    mode,
+                    ...health,
+                    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": {
+              const error = requireComponent(mode);
+              if (error) throw new Error(error);
+              const dependencies = engine.dependencies(componentName, edgeTypes);
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    mode,
+                    component: componentName,
+                    count: dependencies.length,
+                    dependencies: dependencies.map((edge) => ({
+                      component: edge.target,
+                      type: edge.type,
+                      weight: edge.weight,
+                      note: edge.note,
+                      provenance: edge.provenance
+                    }))
+                  }, null, 2)
+                }]
+              };
+            }
+            case "dependents": {
+              const error = requireComponent(mode);
+              if (error) throw new Error(error);
+              const dependents = engine.dependents(componentName, edgeTypes);
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    mode,
+                    component: componentName,
+                    count: dependents.length,
+                    dependents: dependents.map((edge) => ({
+                      component: edge.source,
+                      type: edge.type,
+                      weight: edge.weight,
+                      note: edge.note,
+                      provenance: edge.provenance
+                    }))
+                  }, null, 2)
+                }]
+              };
+            }
+            case "impact": {
+              const error = requireComponent(mode);
+              if (error) throw new Error(error);
+              const impact = engine.impact(componentName, maxDepth);
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    mode,
+                    ...impact,
+                    summary: `Changing ${componentName} affects ${impact.totalAffected} component(s) and ${impact.affectedBlocks.length} block(s)`
+                  }, null, 2)
+                }]
+              };
+            }
+            case "path": {
+              if (!componentName || !target) {
+                throw new Error("component and target are required for path mode");
+              }
+              const path = engine.path(componentName, target);
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    mode,
+                    from: componentName,
+                    to: target,
+                    ...path,
+                    edges: path.edges.map((edge) => ({
+                      source: edge.source,
+                      target: edge.target,
+                      type: edge.type
+                    }))
+                  }, null, 2)
+                }]
+              };
+            }
+            case "composition": {
+              const error = requireComponent(mode);
+              if (error) throw new Error(error);
+              const composition = engine.composition(componentName);
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    mode,
+                    ...composition
+                  }, null, 2)
+                }]
+              };
+            }
+            case "alternatives": {
+              const error = requireComponent(mode);
+              if (error) throw new Error(error);
+              const alternatives = engine.alternatives(componentName);
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    mode,
+                    component: componentName,
+                    count: alternatives.length,
+                    alternatives
+                  }, null, 2)
+                }]
+              };
+            }
+            case "islands": {
+              const islands = engine.islands();
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    mode,
+                    count: islands.length,
+                    islands: islands.map((island, index) => ({
+                      id: index + 1,
+                      size: island.length,
+                      components: island
+                    }))
+                  }, null, 2)
+                }]
+              };
+            }
+            default:
+              throw new Error(`Unknown mode: "${mode}". Valid modes: dependencies, dependents, impact, path, composition, alternatives, islands, health`);
+          }
+        }
+        // ================================================================
+        // A11Y — run accessibility audit against viewer endpoint
+        // ================================================================
+        case TOOL_NAMES.a11y: {
+          const data = await loadFragments();
+          const componentName = args2?.component;
+          const variantName = args2?.variant ?? void 0;
+          const standard = args2?.standard ?? "AA";
+          if (!componentName) {
+            throw new Error("component is required");
+          }
+          const fragment = Object.values(data.fragments).find(
+            (entry) => entry.meta.name.toLowerCase() === componentName.toLowerCase()
+          );
+          if (!fragment) {
+            throw new Error(`Component "${componentName}" not found. Use ${TOOL_NAMES.discover} to see available components.`);
+          }
+          const baseUrl = config.viewerUrl ?? "http://localhost:6006";
+          const auditUrl = `${baseUrl}/fragments/a11y`;
+          try {
+            const response = await fetch(auditUrl, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                component: componentName,
+                variant: variantName,
+                standard
+              })
+            });
+            const result = await response.json();
+            if (!response.ok || result.error) {
+              throw new Error(result.error ?? "A11y audit failed");
+            }
+            const variants = result.results ?? [];
+            const summary = variants.reduce(
+              (acc, variant) => {
+                acc.totalViolations += variant.violations;
+                acc.totalPasses += variant.passes;
+                acc.totalIncomplete += variant.incomplete;
+                acc.critical += variant.summary.critical;
+                acc.serious += variant.summary.serious;
+                acc.moderate += variant.summary.moderate;
+                acc.minor += variant.summary.minor;
+                return acc;
+              },
+              {
+                totalViolations: 0,
+                totalPasses: 0,
+                totalIncomplete: 0,
+                critical: 0,
+                serious: 0,
+                moderate: 0,
+                minor: 0
+              }
+            );
+            const totalChecks = summary.totalPasses + summary.totalViolations + summary.totalIncomplete;
+            const wcagScore = totalChecks > 0 ? Math.round(summary.totalPasses / totalChecks * 100) : 100;
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  component: componentName,
+                  standard,
+                  wcagScore,
+                  passed: summary.critical === 0 && summary.serious === 0,
+                  summary,
+                  variants
+                }, null, 2)
+              }]
+            };
+          } catch (error) {
+            return {
+              content: [{
+                type: "text",
+                text: `Failed to run accessibility audit: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
+              }],
+              isError: true
+            };
+          }
+        }
+        // ================================================================
+        // GENERATE_UI — delegate to playground generation endpoint
+        // ================================================================
+        case TOOL_NAMES.generate_ui: {
+          const prompt = args2?.prompt;
+          if (!prompt) {
+            throw new Error("prompt is required");
+          }
+          const currentTree = args2?.currentTree;
+          const playgroundUrl = "https://usefragments.com";
+          const response = await fetch(`${playgroundUrl}/api/playground/generate`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              prompt,
+              ...currentTree && { currentSpec: currentTree }
+            })
+          });
+          if (!response.ok) {
+            throw new Error(`Playground API error (${response.status}): ${await response.text()}`);
+          }
+          return {
+            content: [{
+              type: "text",
+              text: await response.text()
+            }]
+          };
+        }
+        // ================================================================
+        // GOVERN — validate generated UI specs against governance policies
+        // ================================================================
+        case TOOL_NAMES.govern: {
+          const data = await loadFragments();
+          const spec = args2?.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 {
+            handleGovernTool,
+            formatVerdict,
+            universal,
+            fragments: fragmentsPreset
+          } = await import("@fragments-sdk/govern");
+          const policyOverrides = args2?.policy;
+          const format = args2?.format ?? "json";
+          const tokenPrefix = data.tokens?.prefix;
+          const basePolicy = tokenPrefix && tokenPrefix.includes("fui") ? { rules: fragmentsPreset().rules } : { rules: universal().rules };
+          const engineOptions = data.tokens ? { tokenData: data.tokens } : void 0;
+          const input = {
+            spec,
+            policy: policyOverrides,
+            format
+          };
+          try {
+            const verdict = await handleGovernTool(input, basePolicy, engineOptions);
+            return {
+              content: [{
+                type: "text",
+                text: format === "summary" ? formatVerdict(verdict, "summary") : JSON.stringify(verdict)
+              }],
+              _meta: {
+                score: verdict.score,
+                passed: verdict.passed,
+                violationCount: verdict.results.reduce((sum, result) => sum + result.violations.length, 0)
+              }
+            };
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  error: message
+                })
+              }],
+              isError: true
+            };
+          }
+        }
+        // ================================================================
         // PERF — query performance data
         // ================================================================
         case TOOL_NAMES.perf: {