@fragments-sdk/cli 0.15.9 → 0.15.10

package/src/mcp/server.ts

@@ -14,6 +14,10 @@ import {
   type Theme,
 } from '../core/index.js';
 import { buildMcpTools, buildToolNames, CLI_TOOL_EXTENSIONS } from '@fragments-sdk/context/mcp-tools';
+import type { CompiledBlock, CompiledTokenData } from '@fragments-sdk/context/types';
+import { ComponentGraphEngine, deserializeGraph } from '@fragments-sdk/context/graph';
+import type { GraphEdgeType } from '@fragments-sdk/context/graph';
+import type { EngineOptions as GovernEngineOptions, McpGovernInput } from '@fragments-sdk/govern';
 // ../service is lazy-imported to avoid requiring playwright at startup.
 // Visual tools (render, fix) load it on first use.
 type ServiceModule = typeof import('../service/index.js');
@@ -35,11 +39,12 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { projectFields } from './utils.js';
+import { MCP_SERVER_VERSION } from './version.js';
 
 /**
  * MCP Tool names & definitions (from shared source of truth)
  */
-const TOOL_NAMES = buildToolNames(BRAND.nameLower) as Record<string, string> & {
+const TOOL_NAMES = buildToolNames() as Record<string, string> & {
   discover: string;
   inspect: string;
   blocks: string;
@@ -47,8 +52,92 @@ const TOOL_NAMES = buildToolNames(BRAND.nameLower) as Record<string, string> & {
   implement: string;
   render: string;
   fix: string;
+  graph: string;
+  a11y: string;
+  perf: string;
+  generate_ui: string;
+  govern: string;
 };
 
+const TOOLS = buildMcpTools(undefined, CLI_TOOL_EXTENSIONS) as Tool[];
+
+type McpVerbosity = 'compact' | 'standard' | 'full';
+type TokenCategorySummary = { category: string; count: number };
+
+const DISCOVER_SYNONYM_MAP: Record<string, string[]> = {
+  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'],
+};
+
+const TOKEN_CATEGORY_ALIASES: Record<string, string[]> = {
+  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'],
+};
+
+const FRIENDLY_TOKEN_CATEGORY_ORDER = [
+  'colors',
+  'spacing',
+  'typography',
+  'surfaces',
+  'shadows',
+  'radius',
+  'borders',
+  'text',
+  'focus',
+  'layout',
+  'code',
+  'component-sizing',
+] as const;
+
+const STYLE_QUERY_TERMS = new Set([
+  'color',
+  'colors',
+  'spacing',
+  'padding',
+  'margin',
+  'font',
+  'border',
+  'radius',
+  'shadow',
+  'variable',
+  'token',
+  'css',
+  'theme',
+  'background',
+  'hover',
+  'surface',
+  'focus',
+]);
+
 /**
  * Placeholder patterns to filter out from usage text.
  * These are auto-generated and provide no value to AI agents.
@@ -69,6 +158,231 @@ function filterPlaceholders(items: string[] | undefined): string[] {
   );
 }
 
+function parsePositiveLimit(
+  value: unknown,
+  defaultValue: number | undefined,
+  max: number
+): number | undefined {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    return defaultValue;
+  }
+
+  return Math.min(Math.max(Math.floor(value), 1), max);
+}
+
+function resolveVerbosity(value: unknown, compactAlias = false): McpVerbosity {
+  if (value === 'compact' || value === 'standard' || value === 'full') {
+    return value;
+  }
+
+  return compactAlias ? 'compact' : 'standard';
+}
+
+function normalizeSearchText(value: string | undefined): string {
+  return (value ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function splitSearchTerms(value: string | undefined): string[] {
+  return Array.from(new Set(normalizeSearchText(value).split(/\s+/).filter(Boolean)));
+}
+
+function expandSearchTerms(terms: string[]): string[] {
+  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: string, terms: string[]): number {
+  return terms.reduce((count, term) => count + (haystack.includes(term) ? 1 : 0), 0);
+}
+
+function truncateCodePreview(code: string, previewLines = 20, threshold = 30): string {
+  const lines = code.split('\n');
+  if (lines.length <= threshold) {
+    return code;
+  }
+
+  return `${lines.slice(0, previewLines).join('\n')}\n// ... truncated (${lines.length} lines total)`;
+}
+
+function assignConfidence(score: number): 'high' | 'medium' | 'low' {
+  if (score >= 25) return 'high';
+  if (score >= 15) return 'medium';
+  return 'low';
+}
+
+function canonicalizeTokenCategory(categoryKey: string): string | undefined {
+  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 undefined;
+}
+
+function resolveTokenCategoryKeys(
+  tokenData: CompiledTokenData,
+  requestedCategory: string | undefined
+): { keys: string[]; canonical?: string } {
+  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: CompiledTokenData): TokenCategorySummary[] {
+  const counts = new Map<string, number>();
+
+  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: TokenCategorySummary[] = [];
+  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<T>(
+  categories: Record<string, T[]>,
+  limit: number | undefined
+): { categories: Record<string, T[]>; total: number } {
+  if (limit === undefined) {
+    return {
+      categories,
+      total: Object.values(categories).reduce((sum, entries) => sum + entries.length, 0),
+    };
+  }
+
+  const limited: Record<string, T[]> = {};
+  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: CompiledBlock,
+  query: string,
+  preferredComponents: string[] = []
+): number {
+  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: CompiledBlock[],
+  query: string,
+  preferredComponents: string[] = []
+): Array<{ block: CompiledBlock; score: number }> {
+  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));
+}
+
 /**
  * Resolve workspace directory globs (e.g. "apps/*") into actual paths.
  */
@@ -278,9 +592,6 @@ export interface McpServerConfig {
   /** Diff threshold percentage */
   threshold?: number;
 }
-
-const TOOLS = buildMcpTools(BRAND.nameLower, CLI_TOOL_EXTENSIONS) as Tool[];
-
 /**
  * Create and configure the MCP server
  */
@@ -288,7 +599,7 @@ export function createMcpServer(config: McpServerConfig): Server {
   const server = new Server(
     {
       name: `${BRAND.nameLower}-mcp`,
-      version: '0.0.1',
+      version: MCP_SERVER_VERSION,
     },
     {
       capabilities: {
@@ -482,24 +793,27 @@ export function createMcpServer(config: McpServerConfig): Server {
           const data = await loadFragments();
           const useCase = (args?.useCase as string) ?? undefined;
           const componentForAlts = (args?.component as string) ?? undefined;
-          const category = (args?.category as string) ?? undefined;
-          const search = (args?.search as string)?.toLowerCase() ?? undefined;
+          const category = normalizeSearchText(args?.category as string | undefined) || undefined;
+          const search = normalizeSearchText(args?.search as string | undefined) || undefined;
           const status = (args?.status as string) ?? undefined;
           const format = (args?.format as 'markdown' | 'json') ?? 'markdown';
           const compact = (args?.compact as boolean) ?? false;
           const includeCode = (args?.includeCode as boolean) ?? false;
           const includeRelations = (args?.includeRelations as boolean) ?? false;
+          const verbosity = resolveVerbosity(args?.verbosity, compact);
+          const listLimit = parsePositiveLimit(args?.limit, undefined, 50);
+          const suggestLimit = parsePositiveLimit(args?.limit, 10, 25) ?? 10;
 
-          // --- Context mode: compact or format specified with no specific query ---
-          if (compact || (args?.format && !useCase && !componentForAlts && !category && !search && !status)) {
+          // --- Context mode: explicit format request with no specific query ---
+          if (args?.format && !useCase && !componentForAlts && !category && !search && !status) {
             const fragments = Object.values(data.fragments);
             const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
 
             const { content: ctxContent, tokenEstimate } = generateContext(fragments, {
               format,
-              compact,
+              compact: verbosity === 'compact',
               include: {
-                code: includeCode,
+                code: includeCode || verbosity === 'full',
                 relations: includeRelations,
               },
             }, allBlocks);
@@ -517,31 +831,9 @@ export function createMcpServer(config: McpServerConfig): Server {
           if (useCase) {
             const useCaseLower = useCase.toLowerCase();
             const context = ((args as Record<string, unknown>)?.context as string)?.toLowerCase() ?? '';
-            const searchTerms = `${useCaseLower} ${context}`.split(/\s+/).filter(Boolean);
-
-            const synonymMap: Record<string, string[]> = {
-              '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;
@@ -551,7 +843,7 @@ export function createMcpServer(config: McpServerConfig): Server {
               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`);
               }
@@ -579,9 +871,7 @@ export function createMcpServer(config: McpServerConfig): Server {
                 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(', ')}"`);
@@ -648,7 +938,7 @@ export function createMcpServer(config: McpServerConfig): Server {
               if (count < 2 || suggestions.length < 3) {
                 suggestions.push(item);
                 categoryCount[cat] = count + 1;
-                if (suggestions.length >= 5) break;
+                if (suggestions.length >= suggestLimit) break;
               }
             }
 
@@ -657,8 +947,7 @@ export function createMcpServer(config: McpServerConfig): Server {
               : undefined;
 
             // Detect if query is about styling/tokens rather than components
-            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));
 
             // Determine no-match quality
             const noMatch = suggestions.length === 0;
@@ -669,7 +958,7 @@ export function createMcpServer(config: McpServerConfig): Server {
             if (noMatch) {
               recommendation = isStyleQuery
                 ? `No matching components found. Your query seems styling-related — try ${TOOL_NAMES.tokens} to find CSS custom properties.`
-                : 'No matching components found. Try different keywords or browse all components with fragments_discover.';
+                : `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.`
                 : undefined;
@@ -681,13 +970,23 @@ export function createMcpServer(config: McpServerConfig): Server {
               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' as const,
                 text: JSON.stringify({
                   useCase,
                   context: context || undefined,
-                  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,
@@ -705,7 +1004,7 @@ export function createMcpServer(config: McpServerConfig): Server {
             );
 
             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 ?? [];
@@ -755,7 +1054,7 @@ export function createMcpServer(config: McpServerConfig): Server {
           // --- Default: list mode ---
           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);
@@ -764,27 +1063,54 @@ export function createMcpServer(config: McpServerConfig): Server {
                 if (!nameMatch && !descMatch && !tagMatch) return false;
               }
               return true;
-            })
-            .map((s) => ({
+            });
+
+          const total = fragments.length;
+          const limitedFragments = listLimit === undefined ? 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' as const,
               text: JSON.stringify({
-                total: fragments.length,
-                fragments,
-                categories: [...new Set(fragments.map((s) => s.category))],
-                hint: fragments.length === 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.'
-                  : fragments.length > 5
-                    ? 'Use fragments_discover with useCase for recommendations, or fragments_inspect for details on a specific component.'
+                  : total > 5
+                    ? `Use ${TOOL_NAMES.discover} with useCase for recommendations, or ${TOOL_NAMES.inspect} for details on a specific component.`
                     : undefined,
               }, null, 2),
             }],
@@ -811,7 +1137,7 @@ export function createMcpServer(config: McpServerConfig): Server {
           );
 
           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.`);
           }
 
           // Build the full inspect result combining get + guidelines + example
@@ -937,9 +1263,11 @@ export function createMcpServer(config: McpServerConfig): Server {
         case TOOL_NAMES.blocks: {
           const data = await loadFragments();
           const blockName = args?.name as string | undefined;
-          const search = (args?.search as string)?.toLowerCase() ?? undefined;
+          const search = (args?.search as string) ?? undefined;
           const component = (args?.component as string)?.toLowerCase() ?? undefined;
-          const category = (args?.category as string)?.toLowerCase() ?? undefined;
+          const category = normalizeSearchText(args?.category as string | undefined) || undefined;
+          const blocksLimit = parsePositiveLimit(args?.limit, undefined, 50);
+          const verbosity = resolveVerbosity(args?.verbosity);
 
           const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
 
@@ -959,22 +1287,11 @@ export function createMcpServer(config: McpServerConfig): Server {
           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) {
@@ -985,16 +1302,48 @@ export function createMcpServer(config: McpServerConfig): Server {
 
           if (category) {
             filtered = filtered.filter(b =>
-              b.category.toLowerCase() === category
+              normalizeSearchText(b.category) === category
             );
           }
 
+          if (!search) {
+            filtered = [...filtered].sort((a, b) => a.name.localeCompare(b.name));
+          }
+
+          const total = filtered.length;
+          if (blocksLimit !== undefined) {
+            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' as const,
               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),
             }],
           };
@@ -1005,8 +1354,9 @@ export function createMcpServer(config: McpServerConfig): Server {
         // ================================================================
         case TOOL_NAMES.tokens: {
           const data = await loadFragments();
-          const category = (args?.category as string)?.toLowerCase() ?? undefined;
-          const search = (args?.search as string)?.toLowerCase() ?? undefined;
+          const category = (args?.category as string) ?? undefined;
+          const search = normalizeSearchText(args?.search as string | undefined) || undefined;
+          const tokensLimit = parsePositiveLimit(args?.limit, search ? 25 : undefined, 100);
 
           const tokenData = data.tokens;
 
@@ -1025,35 +1375,43 @@ export function createMcpServer(config: McpServerConfig): Server {
 
           // Filter by category and/or search
           const filteredCategories: Record<string, Array<{ name: string; description?: string }>> = {};
-          let filteredTotal = 0;
+          const resolvedCategory = resolveTokenCategoryKeys(tokenData, category);
+          const searchCategoryKeys = search ? resolveTokenCategoryKeys(tokenData, search).keys : [];
 
           for (const [cat, tokens] of Object.entries(tokenData.categories)) {
-            // Filter by category
-            if (category && cat !== category) continue;
+            if (category && !resolvedCategory.keys.includes(cat)) continue;
 
-            // Filter by search term within this category
             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);
+
           // Build usage hint based on context
           let hint: string | undefined;
           if (filteredTotal === 0) {
-            const availableCategories = Object.keys(tokenData.categories);
             hint = search
-              ? `No tokens matching "${search}". Try: ${availableCategories.join(', ')}`
+              ? `No tokens matching "${search}". Try categories like: ${availableCategoryNames.join(', ')}`
               : category
-                ? `Category "${category}" not found. Available: ${availableCategories.join(', ')}`
+                ? `Category "${category}" not found. Try categories like: ${availableCategoryNames.join(', ')}`
                 : undefined;
           } else if (!category && !search) {
             hint = `Use var(--token-name) in your CSS/styles. Filter by category or search to narrow results.`;
@@ -1066,12 +1424,10 @@ export function createMcpServer(config: McpServerConfig): Server {
                 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),
             }],
@@ -1089,41 +1445,24 @@ export function createMcpServer(config: McpServerConfig): Server {
           }
 
           const useCaseLower = useCase.toLowerCase();
-          const searchTerms = useCaseLower.split(/\s+/).filter(Boolean);
-
-          // 1. Score all fragments (same logic as discover suggest)
-          const synonymMap: Record<string, string[]> = {
-            '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(args?.verbosity);
+          const componentLimit = parsePositiveLimit(args?.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;
@@ -1133,24 +1472,38 @@ export function createMcpServer(config: McpServerConfig): Server {
           const topMatches = scored
             .filter((s) => s.score >= 8)
             .sort((a, b) => b.score - a.score)
-            .slice(0, 3);
+            .slice(0, componentLimit);
 
           // 2. Build component details for top matches
           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(
                 ([name, p]) => `${name}${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,
@@ -1162,27 +1515,46 @@ export function createMcpServer(config: McpServerConfig): Server {
 
           // 3. Find relevant blocks
           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()));
-            })
+          const preferredComponents = topMatches.map(({ fragment }) => fragment.meta.name);
+          const matchingBlocks = rankBlocks(allBlocks, useCase, preferredComponents)
             .slice(0, 2)
-            .map((b) => ({ name: b.name, description: b.description, components: b.components, code: b.code }));
+            .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),
+              };
+            });
 
           // 4. Find relevant tokens
           const tokenData = data.tokens;
           let relevantTokens: Record<string, string[]> | undefined;
           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 = undefined;
@@ -1196,7 +1568,7 @@ export function createMcpServer(config: McpServerConfig): Server {
                 useCase,
                 components,
                 blocks: matchingBlocks.length > 0 ? matchingBlocks : undefined,
-                tokens: relevantTokens,
+                tokens: verbosity === 'compact' ? undefined : 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).` : ''}`
@@ -1474,7 +1846,7 @@ export function createMcpServer(config: McpServerConfig): Server {
           );
 
           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';
@@ -1520,7 +1892,7 @@ export function createMcpServer(config: McpServerConfig): Server {
                   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.'
+                    ? `Apply patches using your editor or \`patch\` command, then run ${TOOL_NAMES.render} with baseline:true to confirm fixes.`
                     : undefined,
                 }, null, 2),
               }],
@@ -1536,6 +1908,420 @@ export function createMcpServer(config: McpServerConfig): Server {
           }
         }
 
+        // ================================================================
+        // GRAPH — query component relationship graph
+        // ================================================================
+        case TOOL_NAMES.graph: {
+          const data = await loadFragments();
+          const mode = (args?.mode as string) ?? 'health';
+          const componentName = args?.component as string | undefined;
+          const target = args?.target as string | undefined;
+          const edgeTypes = args?.edgeTypes as GraphEdgeType[] | undefined;
+          const maxDepth = (args?.maxDepth as number | undefined) ?? 3;
+
+          if (!data.graph) {
+            return {
+              content: [{
+                type: 'text' as const,
+                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 }])
+              )
+            : undefined;
+          const engine = new ComponentGraphEngine(graph, blocks);
+
+          const requireComponent = (modeName: string): string | undefined => {
+            if (!componentName) {
+              return `component is required for ${modeName} mode`;
+            }
+            if (!engine.hasNode(componentName)) {
+              return `Component "${componentName}" not found in graph.`;
+            }
+            return undefined;
+          };
+
+          switch (mode) {
+            case 'health': {
+              const health = engine.getHealth();
+              return {
+                content: [{
+                  type: 'text' as const,
+                  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' as const,
+                  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' as const,
+                  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' as const,
+                  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' as const,
+                  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' as const,
+                  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' as const,
+                  text: JSON.stringify({
+                    mode,
+                    component: componentName,
+                    count: alternatives.length,
+                    alternatives,
+                  }, null, 2),
+                }],
+              };
+            }
+
+            case 'islands': {
+              const islands = engine.islands();
+              return {
+                content: [{
+                  type: 'text' as const,
+                  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 = args?.component as string;
+          const variantName = (args?.variant as string) ?? undefined;
+          const standard = (args?.standard as 'AA' | 'AAA') ?? '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() as {
+              results?: Array<{
+                variant: string;
+                violations: number;
+                passes: number;
+                incomplete: number;
+                summary: {
+                  total: number;
+                  critical: number;
+                  serious: number;
+                  moderate: number;
+                  minor: number;
+                };
+                violationDetails?: Array<{
+                  id: string;
+                  impact?: string;
+                  description: string;
+                  helpUrl: string;
+                  nodes: number;
+                }>;
+              }>;
+              error?: string;
+            };
+
+            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' as const,
+                text: JSON.stringify({
+                  component: componentName,
+                  standard,
+                  wcagScore,
+                  passed: summary.critical === 0 && summary.serious === 0,
+                  summary,
+                  variants,
+                }, null, 2),
+              }],
+            };
+          } catch (error) {
+            return {
+              content: [{
+                type: 'text' as const,
+                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 = args?.prompt as string;
+          if (!prompt) {
+            throw new Error('prompt is required');
+          }
+
+          const currentTree = args?.currentTree as Record<string, unknown> | undefined;
+          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' as const,
+              text: await response.text(),
+            }],
+          };
+        }
+
+        // ================================================================
+        // GOVERN — validate generated UI specs against governance policies
+        // ================================================================
+        case TOOL_NAMES.govern: {
+          const data = await loadFragments();
+          const spec = args?.spec;
+          if (!spec || typeof spec !== 'object') {
+            return {
+              content: [{
+                type: 'text' as const,
+                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 = args?.policy as Record<string, unknown> | undefined;
+          const format = (args?.format as 'json' | 'summary') ?? 'json';
+          const tokenPrefix = data.tokens?.prefix;
+          const basePolicy =
+            tokenPrefix && tokenPrefix.includes('fui')
+              ? { rules: fragmentsPreset().rules }
+              : { rules: universal().rules };
+          const engineOptions: GovernEngineOptions | undefined = data.tokens
+            ? { tokenData: data.tokens }
+            : undefined;
+
+          const input: McpGovernInput = {
+            spec,
+            policy: policyOverrides as McpGovernInput['policy'],
+            format,
+          };
+
+          try {
+            const verdict = await handleGovernTool(input, basePolicy, engineOptions);
+            return {
+              content: [{
+                type: 'text' as const,
+                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' as const,
+                text: JSON.stringify({
+                  error: message,
+                }),
+              }],
+              isError: true,
+            };
+          }
+        }
+
         // ================================================================
         // PERF — query performance data
         // ================================================================