@fragments-sdk/cli 0.2.2

package/src/mcp/server.ts

@@ -0,0 +1,1310 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  BRAND,
+  DEFAULTS,
+  generateContext,
+  type CompiledSegmentsFile,
+  type VerifyResult,
+  type Theme,
+} from '../core/index.js';
+// ../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');
+let _service: ServiceModule | null = null;
+async function getService(): Promise<ServiceModule> {
+  if (!_service) {
+    try {
+      _service = await import('../service/index.js');
+    } catch {
+      throw new Error(
+        'Visual tools require playwright. Install it with: npm install playwright'
+      );
+    }
+  }
+  return _service;
+}
+import { readFile } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { projectFields } from './utils.js';
+
+/**
+ * MCP Tool names - derived from BRAND constants
+ */
+const TOOL_NAMES = {
+  discover: `${BRAND.nameLower}_discover`,
+  inspect: `${BRAND.nameLower}_inspect`,
+  recipe: `${BRAND.nameLower}_recipe`,
+  render: `${BRAND.nameLower}_render`,
+  fix: `${BRAND.nameLower}_fix`,
+} as const;
+
+/**
+ * Placeholder patterns to filter out from usage text.
+ * These are auto-generated and provide no value to AI agents.
+ */
+const PLACEHOLDER_PATTERNS = [
+  /^\w+ component is needed$/i,
+  /^Alternative component is more appropriate$/i,
+  /^Use \w+ when you need/i,
+];
+
+/**
+ * Filter out placeholder text from usage arrays
+ */
+function filterPlaceholders(items: string[] | undefined): string[] {
+  if (!items) return [];
+  return items.filter(item =>
+    !PLACEHOLDER_PATTERNS.some(pattern => pattern.test(item.trim()))
+  );
+}
+
+/**
+ * MCP Server configuration
+ */
+export interface McpServerConfig {
+  /** Project root directory */
+  projectRoot: string;
+
+  /** Viewer base URL */
+  viewerUrl?: string;
+
+  /** Default theme for verification */
+  theme?: Theme;
+
+  /** Diff threshold percentage */
+  threshold?: number;
+}
+
+/**
+ * Tool definitions for the MCP server — 5 consolidated tools
+ */
+const TOOLS: Tool[] = [
+  {
+    name: TOOL_NAMES.discover,
+    description: `Discover components in the design system. Use with no params to list all components. Use 'useCase' for AI-powered suggestions. Use 'component' to find alternatives. Use 'compact' for a token-efficient overview.`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        useCase: {
+          type: 'string',
+          description: 'Description of what you want to build — returns ranked suggestions (e.g., "form for user email input", "button to submit data")',
+        },
+        component: {
+          type: 'string',
+          description: 'Component name to find alternatives for (e.g., "Button")',
+        },
+        category: {
+          type: 'string',
+          description: 'Filter by category (e.g., "actions", "forms", "layout")',
+        },
+        search: {
+          type: 'string',
+          description: 'Search term to filter by name, description, or tags',
+        },
+        status: {
+          type: 'string',
+          enum: ['stable', 'beta', 'deprecated', 'experimental'],
+          description: 'Filter by component status',
+        },
+        format: {
+          type: 'string',
+          enum: ['markdown', 'json'],
+          description: 'Output format for context mode (default: markdown)',
+        },
+        compact: {
+          type: 'boolean',
+          description: 'If true, returns minimal output (just component names and categories)',
+        },
+        includeCode: {
+          type: 'boolean',
+          description: 'If true, includes code examples for each variant',
+        },
+        includeRelations: {
+          type: 'boolean',
+          description: 'If true, includes component relationships',
+        },
+      },
+    },
+  },
+  {
+    name: TOOL_NAMES.inspect,
+    description: `Get detailed information about a specific component: props, usage guidelines, code examples, accessibility — all in one call. Use 'fields' to request only specific data for token efficiency.`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        component: {
+          type: 'string',
+          description: 'Component name (e.g., "Button", "Input")',
+        },
+        fields: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Specific fields to return (e.g., ["meta", "usage.when", "contract.propsSummary", "props", "examples", "guidelines"]). If omitted, returns everything. Supports dot notation.',
+        },
+        variant: {
+          type: 'string',
+          description: 'Filter examples to a specific variant name (e.g., "Default", "Primary")',
+        },
+        maxExamples: {
+          type: 'number',
+          description: 'Maximum number of code examples to return (default: all)',
+        },
+        maxLines: {
+          type: 'number',
+          description: 'Maximum lines per code example (truncates longer examples)',
+        },
+      },
+      required: ['component'],
+    },
+  },
+  {
+    name: TOOL_NAMES.recipe,
+    description: `Search and retrieve composition recipes — named patterns showing how design system components wire together for common use cases (e.g., "Login Form", "Settings Page"). Returns the recipe with its code pattern.`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Exact recipe name to retrieve (e.g., "Login Form")',
+        },
+        search: {
+          type: 'string',
+          description: 'Free-text search across recipe names, descriptions, tags, and components',
+        },
+        component: {
+          type: 'string',
+          description: 'Filter recipes that use a specific component (e.g., "Button")',
+        },
+      },
+    },
+  },
+  {
+    name: TOOL_NAMES.render,
+    description: `Render a component and return a screenshot. Optionally compare against a stored baseline ('baseline: true') or against a Figma design ('figmaUrl'). Use this to verify your implementation looks correct.`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        component: {
+          type: 'string',
+          description: 'Component name (e.g., "Button", "Card", "Input")',
+        },
+        variant: {
+          type: 'string',
+          description: 'Variant name for baseline/compare modes',
+        },
+        props: {
+          type: 'object',
+          description: 'Props to pass to the component (e.g., { "variant": "primary", "children": "Click me" })',
+        },
+        viewport: {
+          type: 'object',
+          properties: {
+            width: { type: 'number', description: 'Viewport width (default: 800)' },
+            height: { type: 'number', description: 'Viewport height (default: 600)' },
+          },
+          description: 'Optional viewport size for the render',
+        },
+        baseline: {
+          type: 'boolean',
+          description: 'If true, compares the render against the stored baseline screenshot (requires variant)',
+        },
+        figmaUrl: {
+          type: 'string',
+          description: 'Figma frame URL — if provided, compares the render against the Figma design',
+        },
+        theme: {
+          type: 'string',
+          enum: ['light', 'dark'],
+          description: 'Theme for baseline verification (default: light)',
+        },
+        threshold: {
+          type: 'number',
+          description: 'Diff threshold percentage (default: 5 for baseline, 1 for Figma)',
+        },
+      },
+      required: ['component'],
+    },
+  },
+  {
+    name: TOOL_NAMES.fix,
+    description: `Generate patches to fix token compliance issues in a component. Returns unified diff patches that replace hardcoded CSS values with design token references. Use this after fragments_render identifies issues to automatically fix them.`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        component: {
+          type: 'string',
+          description: 'Component name to generate fixes for (e.g., "Button", "Card")',
+        },
+        variant: {
+          type: 'string',
+          description: 'Specific variant to fix (optional, fixes all variants if omitted)',
+        },
+        fixType: {
+          type: 'string',
+          enum: ['token', 'all'],
+          description: 'Type of fixes to generate: "token" for hardcoded→token replacements, "all" for all available fixes (default: "all")',
+        },
+      },
+      required: ['component'],
+    },
+  },
+];
+
+/**
+ * Create and configure the MCP server
+ */
+export function createMcpServer(config: McpServerConfig): Server {
+  const server = new Server(
+    {
+      name: `${BRAND.nameLower}-mcp`,
+      version: '0.0.1',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Lazy-loaded resources
+  let segmentsData: CompiledSegmentsFile | null = null;
+  let packageName: string | null = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- lazy-loaded from service
+  let browserPool: any = null;
+  let storageManager: any = null;
+  let diffEngine: any = null;
+  let isPoolWarming = false;
+
+  /**
+   * Find fragments.json files:
+   * 1. Walk up from projectRoot (for library authors with a local build)
+   * 2. Read package.json deps and resolve packages with a "fragments" field
+   */
+  function findFragmentsJson(startDir: string): string[] {
+    const found: string[] = [];
+    const resolvedStart = resolve(startDir);
+
+    // 1. Walk upward from startDir (library author flow)
+    let dir = resolvedStart;
+    while (true) {
+      const candidate = join(dir, BRAND.outFile);
+      if (existsSync(candidate)) {
+        found.push(candidate);
+        break;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+
+    // 2. Read package.json and resolve deps with "fragments" field
+    const pkgJsonPath = join(resolvedStart, 'package.json');
+    if (existsSync(pkgJsonPath)) {
+      try {
+        const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+        const allDeps = {
+          ...pkgJson.dependencies,
+          ...pkgJson.devDependencies,
+        };
+        for (const depName of Object.keys(allDeps)) {
+          const depPkgPath = join(resolvedStart, 'node_modules', depName, 'package.json');
+          if (!existsSync(depPkgPath)) continue;
+          try {
+            const depPkg = JSON.parse(readFileSync(depPkgPath, 'utf-8'));
+            if (depPkg.fragments) {
+              const fragmentsPath = join(resolvedStart, 'node_modules', depName, depPkg.fragments);
+              if (existsSync(fragmentsPath) && !found.includes(fragmentsPath)) {
+                found.push(fragmentsPath);
+              }
+            }
+          } catch {
+            // Skip unreadable package
+          }
+        }
+      } catch {
+        // No package.json or unreadable
+      }
+    }
+
+    return found;
+  }
+
+  async function loadSegments(): Promise<CompiledSegmentsFile> {
+    if (segmentsData) {
+      return segmentsData;
+    }
+
+    const paths = findFragmentsJson(config.projectRoot);
+
+    if (paths.length === 0) {
+      throw new Error(
+        `No ${BRAND.outFile} found. Searched ${config.projectRoot} and package.json dependencies. ` +
+        `Either run \`${BRAND.cliCommand} build\` or install a package with a "fragments" field in its package.json.`
+      );
+    }
+
+    // Load and merge all found fragments files
+    const content = await readFile(paths[0], 'utf-8');
+    segmentsData = JSON.parse(content) as CompiledSegmentsFile;
+
+    for (let i = 1; i < paths.length; i++) {
+      const extra = JSON.parse(await readFile(paths[i], 'utf-8')) as CompiledSegmentsFile;
+      Object.assign(segmentsData.segments, extra.segments);
+      if (extra.recipes) {
+        segmentsData.recipes = { ...segmentsData.recipes, ...extra.recipes };
+      }
+    }
+
+    return segmentsData;
+  }
+
+  /**
+   * Get the package name from package.json for import statements
+   */
+  async function getPackageName(): Promise<string> {
+    if (packageName) {
+      return packageName;
+    }
+
+    const packageJsonPath = join(config.projectRoot, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      try {
+        const content = await readFile(packageJsonPath, 'utf-8');
+        const pkg = JSON.parse(content) as { name?: string };
+        if (pkg.name) {
+          packageName = pkg.name;
+          return packageName;
+        }
+      } catch {
+        // Fall through to default
+      }
+    }
+
+    // Default fallback
+    packageName = 'your-component-library';
+    return packageName;
+  }
+
+  /**
+   * Get or create browser pool with extended idle timeout for MCP
+   */
+  async function getBrowserPool() {
+    if (!browserPool) {
+      const { BrowserPool } = await getService();
+      browserPool = new BrowserPool({
+        viewport: DEFAULTS.viewport,
+        // 30 minute idle timeout for MCP - server runs continuously
+        idleTimeoutMs: 30 * 60 * 1000,
+        poolSize: 2, // Keep 2 contexts warm for faster captures
+      });
+    }
+    return browserPool;
+  }
+
+  /**
+   * Pre-warm browser pool in background (non-blocking)
+   */
+  function warmBrowserPool(): void {
+    if (isPoolWarming || browserPool?.isReady) {
+      return;
+    }
+    isPoolWarming = true;
+
+    // Warm in background - don't await
+    getBrowserPool().then((pool) => {
+      pool.warmup().then(() => {
+        isPoolWarming = false;
+      }).catch(() => {
+        isPoolWarming = false;
+      });
+    }).catch(() => {
+      isPoolWarming = false;
+    });
+  }
+
+  /**
+   * Get or create storage manager
+   */
+  async function getStorageManager() {
+    if (!storageManager) {
+      const { StorageManager } = await getService();
+      storageManager = new StorageManager({
+        projectRoot: config.projectRoot,
+      });
+      await storageManager.initialize();
+    }
+    return storageManager;
+  }
+
+  /**
+   * Get or create diff engine
+   */
+  async function getDiffEngine() {
+    if (!diffEngine) {
+      const { DiffEngine } = await getService();
+      diffEngine = new DiffEngine(config.threshold ?? DEFAULTS.diffThreshold);
+    }
+    return diffEngine;
+  }
+
+  // Register tool listing
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  // Register tool execution
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      switch (name) {
+        // ================================================================
+        // DISCOVER — list, suggest, context, alternatives
+        // ================================================================
+        case TOOL_NAMES.discover: {
+          const data = await loadSegments();
+          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 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;
+
+          // --- Context mode: compact or format specified with no specific query ---
+          if (compact || (args?.format && !useCase && !componentForAlts && !category && !search && !status)) {
+            const segments = Object.values(data.segments);
+            const recipes = Object.values(data.recipes ?? {});
+
+            const { content: ctxContent, tokenEstimate } = generateContext(segments, {
+              format,
+              compact,
+              include: {
+                code: includeCode,
+                relations: includeRelations,
+              },
+            }, recipes);
+
+            return {
+              content: [{
+                type: 'text' as const,
+                text: ctxContent,
+              }],
+              _meta: { tokenEstimate },
+            };
+          }
+
+          // --- Suggest mode: useCase provided ---
+          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 scored = Object.values(data.segments).map((s) => {
+              let score = 0;
+              const reasons: string[] = [];
+
+              const nameLower = s.meta.name.toLowerCase();
+              if (searchTerms.some((term) => nameLower.includes(term))) {
+                score += 15;
+                reasons.push(`Name matches search`);
+              } else if (Array.from(expandedTerms).some((term) => nameLower.includes(term))) {
+                score += 8;
+                reasons.push(`Name matches related term`);
+              }
+
+              const desc = s.meta.description?.toLowerCase() ?? '';
+              const descMatches = searchTerms.filter((term) => desc.includes(term));
+              if (descMatches.length > 0) {
+                score += descMatches.length * 6;
+                reasons.push(`Description matches: ${descMatches.join(', ')}`);
+              }
+
+              const tags = s.meta.tags?.map((t) => t.toLowerCase()) ?? [];
+              const tagMatches = searchTerms.filter((term) =>
+                tags.some((tag) => tag.includes(term))
+              );
+              if (tagMatches.length > 0) {
+                score += tagMatches.length * 4;
+                reasons.push(`Tags match: ${tagMatches.join(', ')}`);
+              }
+
+              const whenUsed = s.usage?.when?.join(' ').toLowerCase() ?? '';
+              const whenMatches = searchTerms.filter((term) => whenUsed.includes(term));
+              if (whenMatches.length > 0) {
+                score += whenMatches.length * 10;
+                reasons.push(`Use cases match: "${whenMatches.join(', ')}"`);
+              }
+
+              const expandedWhenMatches = Array.from(expandedTerms).filter(
+                (term) => !searchTerms.includes(term) && whenUsed.includes(term)
+              );
+              if (expandedWhenMatches.length > 0) {
+                score += expandedWhenMatches.length * 5;
+                reasons.push(`Related use cases: "${expandedWhenMatches.join(', ')}"`);
+              }
+
+              const cat = s.meta.category?.toLowerCase() ?? '';
+              if (searchTerms.some((term) => cat.includes(term))) {
+                score += 8;
+                reasons.push(`Category: ${s.meta.category}`);
+              }
+
+              const variantText = s.variants
+                .map(v => `${v.name} ${v.description || ''}`.toLowerCase())
+                .join(' ');
+              const variantMatches = searchTerms.filter(term => variantText.includes(term));
+              if (variantMatches.length > 0) {
+                score += variantMatches.length * 3;
+                reasons.push(`Variants match: ${variantMatches.join(', ')}`);
+              }
+
+              if (s.meta.status === 'stable') {
+                score += 5;
+                reasons.push('Stable component');
+              } else if (s.meta.status === 'beta') {
+                score += 2;
+              }
+
+              if (s.meta.status === 'deprecated') {
+                score -= 25;
+                reasons.push('Deprecated - consider alternatives');
+              }
+
+              const filteredWhen = filterPlaceholders(s.usage?.when).slice(0, 3);
+              const filteredWhenNot = filterPlaceholders(s.usage?.whenNot).slice(0, 2);
+
+              let confidence: 'high' | 'medium' | 'low';
+              if (score >= 25) confidence = 'high';
+              else if (score >= 15) confidence = 'medium';
+              else confidence = 'low';
+
+              return {
+                component: s.meta.name,
+                category: s.meta.category,
+                description: s.meta.description,
+                score,
+                confidence,
+                reasons,
+                usage: { when: filteredWhen, whenNot: filteredWhenNot },
+                variantCount: s.variants.length,
+                status: s.meta.status,
+              };
+            });
+
+            const MIN_SCORE = 8;
+            const filtered = scored
+              .filter((s) => s.score >= MIN_SCORE)
+              .sort((a, b) => b.score - a.score);
+
+            const suggestions: typeof filtered = [];
+            const categoryCount: Record<string, number> = {};
+            for (const item of filtered) {
+              const cat = item.category || 'uncategorized';
+              const count = categoryCount[cat] || 0;
+              if (count < 2 || suggestions.length < 3) {
+                suggestions.push(item);
+                categoryCount[cat] = count + 1;
+                if (suggestions.length >= 5) 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 ')}.`
+              : undefined;
+
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify({
+                  useCase,
+                  context: context || undefined,
+                  suggestions: suggestions.map(({ score, ...rest }) => rest),
+                  recommendation: suggestions.length > 0
+                    ? `Best match: ${suggestions[0].component} (${suggestions[0].confidence} confidence) - ${suggestions[0].description}`
+                    : 'No matching components found. Try different keywords or browse with fragments_discover.',
+                  compositionHint,
+                  nextStep: suggestions.length > 0
+                    ? `Use fragments_inspect("${suggestions[0].component}") for full details.`
+                    : undefined,
+                }, null, 2),
+              }],
+            };
+          }
+
+          // --- Alternatives mode: component provided (no useCase) ---
+          if (componentForAlts) {
+            const segment = Object.values(data.segments).find(
+              (s) => s.meta.name.toLowerCase() === componentForAlts.toLowerCase()
+            );
+
+            if (!segment) {
+              throw new Error(`Component "${componentForAlts}" not found. Use fragments_discover to see available components.`);
+            }
+
+            const relations = segment.relations ?? [];
+
+            const referencedBy = Object.values(data.segments)
+              .filter((s) =>
+                s.relations?.some((r) => r.component.toLowerCase() === componentForAlts.toLowerCase())
+              )
+              .map((s) => ({
+                component: s.meta.name,
+                relationship: s.relations?.find(
+                  (r) => r.component.toLowerCase() === componentForAlts.toLowerCase()
+                )?.relationship,
+                note: s.relations?.find(
+                  (r) => r.component.toLowerCase() === componentForAlts.toLowerCase()
+                )?.note,
+              }));
+
+            const sameCategory = Object.values(data.segments)
+              .filter(
+                (s) =>
+                  s.meta.category === segment.meta.category &&
+                  s.meta.name.toLowerCase() !== componentForAlts.toLowerCase()
+              )
+              .map((s) => ({
+                component: s.meta.name,
+                description: s.meta.description,
+              }));
+
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify({
+                  component: segment.meta.name,
+                  category: segment.meta.category,
+                  directRelations: relations,
+                  referencedBy,
+                  sameCategory,
+                  suggestion: relations.find((r) => r.relationship === 'alternative')
+                    ? `Consider ${relations.find((r) => r.relationship === 'alternative')?.component}: ${relations.find((r) => r.relationship === 'alternative')?.note}`
+                    : undefined,
+                }, null, 2),
+              }],
+            };
+          }
+
+          // --- Default: list mode ---
+          const segments = Object.values(data.segments)
+            .filter((s) => {
+              if (category && s.meta.category !== category) return false;
+              if (status && (s.meta.status ?? 'stable') !== status) return false;
+              if (search) {
+                const nameMatch = s.meta.name.toLowerCase().includes(search);
+                const descMatch = s.meta.description?.toLowerCase().includes(search);
+                const tagMatch = s.meta.tags?.some((t) => t.toLowerCase().includes(search));
+                if (!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 ?? [],
+            }));
+
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                total: segments.length,
+                segments,
+                categories: [...new Set(segments.map((s) => s.category))],
+                hint: segments.length === 0
+                  ? 'No components found. Try broader search terms or check available categories.'
+                  : segments.length > 5
+                    ? 'Use fragments_discover with useCase for recommendations, or fragments_inspect for details on a specific component.'
+                    : undefined,
+              }, null, 2),
+            }],
+          };
+        }
+
+        // ================================================================
+        // INSPECT — get + guidelines + example in one call
+        // ================================================================
+        case TOOL_NAMES.inspect: {
+          const data = await loadSegments();
+          const componentName = args?.component as string;
+          const fields = args?.fields as string[] | undefined;
+          const variantName = (args?.variant as string) ?? undefined;
+          const maxExamples = args?.maxExamples as number | undefined;
+          const maxLines = args?.maxLines as number | undefined;
+
+          if (!componentName) {
+            throw new Error('component is required');
+          }
+
+          const segment = Object.values(data.segments).find(
+            (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
+          );
+
+          if (!segment) {
+            throw new Error(`Component "${componentName}" not found. Use fragments_discover to see available components.`);
+          }
+
+          // Build the full inspect result combining get + guidelines + example
+          const pkgName = await getPackageName();
+
+          // Filter variants for examples
+          let variants = segment.variants;
+          if (variantName) {
+            const filtered = variants.filter(
+              (v) => v.name.toLowerCase() === variantName.toLowerCase()
+            );
+            if (filtered.length > 0) {
+              variants = filtered;
+            }
+          }
+          if (maxExamples && maxExamples > 0) {
+            variants = variants.slice(0, maxExamples);
+          }
+
+          const truncateCode = (code: string): string => {
+            if (!maxLines || maxLines <= 0) return code;
+            const lines = code.split('\n');
+            if (lines.length <= maxLines) return code;
+            return lines.slice(0, maxLines).join('\n') + '\n// ... truncated';
+          };
+
+          const examples = variants.map((variant) => {
+            if (variant.code) {
+              return {
+                variant: variant.name,
+                description: variant.description,
+                code: truncateCode(variant.code),
+              };
+            }
+            return {
+              variant: variant.name,
+              description: variant.description,
+              code: `<${segment.meta.name} />`,
+              note: 'No code example provided in fragment. Refer to props for customization.',
+            };
+          });
+
+          const propsReference = Object.entries(segment.props ?? {}).map(([propName, prop]) => ({
+            name: propName,
+            type: prop.type,
+            required: prop.required,
+            default: prop.default,
+            description: prop.description,
+          }));
+
+          const propConstraints = Object.entries(segment.props ?? {})
+            .filter(([, prop]) => prop.constraints && prop.constraints.length > 0)
+            .map(([pName, prop]) => ({
+              prop: pName,
+              constraints: prop.constraints,
+            }));
+
+          const fullResult = {
+            // Component data (from old "get")
+            meta: segment.meta,
+            props: segment.props,
+            variants: segment.variants,
+            relations: segment.relations,
+            contract: segment.contract,
+            generated: segment._generated,
+            // Guidelines (from old "guidelines")
+            guidelines: {
+              when: filterPlaceholders(segment.usage?.when),
+              whenNot: filterPlaceholders(segment.usage?.whenNot),
+              guidelines: segment.usage?.guidelines ?? [],
+              accessibility: segment.usage?.accessibility ?? [],
+              propConstraints,
+              alternatives: segment.relations
+                ?.filter((r) => r.relationship === 'alternative')
+                .map((r) => ({
+                  component: r.component,
+                  note: r.note,
+                })) ?? [],
+            },
+            // Examples (from old "example")
+            examples: {
+              import: `import { ${segment.meta.name} } from '${pkgName}';`,
+              code: examples,
+              propsReference,
+            },
+          };
+
+          // Apply field projection if specified
+          const result = fields && fields.length > 0
+            ? projectFields(fullResult as unknown as Record<string, unknown>, fields)
+            : fullResult;
+
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            }],
+          };
+        }
+
+        // ================================================================
+        // RECIPE — unchanged
+        // ================================================================
+        case TOOL_NAMES.recipe: {
+          const data = await loadSegments();
+          const recipeName = args?.name as string | undefined;
+          const search = (args?.search as string)?.toLowerCase() ?? undefined;
+          const component = (args?.component as string)?.toLowerCase() ?? undefined;
+
+          const allRecipes = Object.values(data.recipes ?? {});
+
+          if (allRecipes.length === 0) {
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify({
+                  total: 0,
+                  recipes: [],
+                  hint: `No recipes found. Run \`${BRAND.cliCommand} build\` after adding .recipe.ts files.`,
+                }, null, 2),
+              }],
+            };
+          }
+
+          let filtered = allRecipes;
+
+          if (recipeName) {
+            filtered = filtered.filter(
+              r => r.name.toLowerCase() === recipeName.toLowerCase()
+            );
+          }
+
+          if (search) {
+            filtered = filtered.filter(r => {
+              const haystack = [
+                r.name,
+                r.description,
+                ...(r.tags ?? []),
+                ...r.components,
+                r.category,
+              ].join(' ').toLowerCase();
+              return haystack.includes(search);
+            });
+          }
+
+          if (component) {
+            filtered = filtered.filter(r =>
+              r.components.some(c => c.toLowerCase() === component)
+            );
+          }
+
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                total: filtered.length,
+                recipes: filtered,
+              }, null, 2),
+            }],
+          };
+        }
+
+        // ================================================================
+        // RENDER — render + verify + compare
+        // ================================================================
+        case TOOL_NAMES.render: {
+          const componentName = args?.component as string;
+          const variantName = args?.variant as string | undefined;
+          const props = (args?.props as Record<string, unknown>) ?? {};
+          const viewport = args?.viewport as { width?: number; height?: number } | undefined;
+          const useBaseline = (args?.baseline as boolean) ?? false;
+          const figmaUrl = args?.figmaUrl as string | undefined;
+          const theme = (args?.theme as Theme) ?? config.theme ?? DEFAULTS.theme;
+          const threshold = (args?.threshold as number) ?? (figmaUrl ? 1.0 : config.threshold ?? DEFAULTS.diffThreshold);
+
+          if (!componentName) {
+            return {
+              content: [{
+                type: 'text' as const,
+                text: 'Error: component name is required',
+              }],
+              isError: true,
+            };
+          }
+
+          // --- Baseline verify mode ---
+          if (useBaseline) {
+            if (!variantName) {
+              throw new Error('variant is required when baseline is true');
+            }
+
+            const { Timer, CaptureEngine: CE, bufferToBase64Url: toBase64 } = await getService();
+            const timer = new Timer();
+
+            const storage = await getStorageManager();
+            const pool = await getBrowserPool();
+            const diff = await getDiffEngine();
+
+            const baseline = await storage.loadBaseline(componentName, variantName, theme);
+
+            if (!baseline) {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: JSON.stringify({
+                    verdict: 'error',
+                    matches: false,
+                    diffPercentage: 0,
+                    screenshot: '',
+                    baseline: '',
+                    notes: [],
+                    error: `No baseline found for ${componentName}/${variantName}. Run \`${BRAND.cliCommand} screenshot\` first.`,
+                    timing: { renderMs: 0, captureMs: 0, diffMs: 0, totalMs: timer.elapsed() },
+                  } satisfies VerifyResult, null, 2),
+                }],
+              };
+            }
+
+            const viewerUrl = config.viewerUrl ?? `http://localhost:${DEFAULTS.port}`;
+            const captureEngine = new CE(pool, viewerUrl);
+
+            const current = await captureEngine.captureVariant(componentName, variantName, {
+              theme,
+              delay: DEFAULTS.captureDelayMs,
+            });
+
+            let diffResult;
+            let matches = false;
+
+            if (diff.areIdentical(current, baseline)) {
+              matches = true;
+              diffResult = {
+                matches: true,
+                diffPercentage: 0,
+                diffPixelCount: 0,
+                totalPixels: current.viewport.width * current.viewport.height,
+                changedRegions: [],
+                diffTimeMs: 0,
+              };
+            } else {
+              diffResult = diff.compare(current, baseline, { threshold });
+              matches = diffResult.matches;
+            }
+
+            const result: VerifyResult = {
+              verdict: matches ? 'pass' : 'fail',
+              matches,
+              diffPercentage: diffResult.diffPercentage,
+              screenshot: toBase64(current.data),
+              baseline: toBase64(baseline.data),
+              diffImage: diffResult.diffImage
+                ? toBase64(diffResult.diffImage)
+                : undefined,
+              notes: matches
+                ? ['Screenshot matches baseline within threshold']
+                : [
+                    `Diff percentage (${diffResult.diffPercentage}%) exceeds threshold (${threshold}%)`,
+                    `${diffResult.changedRegions.length} changed region(s) detected`,
+                  ],
+              timing: {
+                renderMs: current.metadata.renderTimeMs,
+                captureMs: current.metadata.captureTimeMs,
+                diffMs: diffResult.diffTimeMs,
+                totalMs: timer.elapsed(),
+              },
+            };
+
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify(result, null, 2),
+              }],
+            };
+          }
+
+          // --- Figma compare mode ---
+          if (figmaUrl) {
+            const baseUrl = config.viewerUrl ?? 'http://localhost:6006';
+            const compareUrl = `${baseUrl}/fragments/compare`;
+
+            try {
+              const response = await fetch(compareUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                  component: componentName,
+                  variant: variantName,
+                  props,
+                  figmaUrl,
+                  threshold,
+                }),
+              });
+
+              interface CompareResult {
+                match?: boolean;
+                diffPercentage?: number;
+                threshold?: number;
+                rendered?: string;
+                figma?: string;
+                diff?: string;
+                figmaUrl?: string;
+                changedRegions?: Array<{ x: number; y: number; width: number; height: number }>;
+                error?: string;
+                suggestion?: string;
+              }
+
+              const result = await response.json() as CompareResult;
+
+              if (!response.ok || result.error) {
+                return {
+                  content: [{
+                    type: 'text' as const,
+                    text: `Compare error: ${result.error ?? 'Unknown error'}${result.suggestion ? `\nSuggestion: ${result.suggestion}` : ''}`,
+                  }],
+                  isError: true,
+                };
+              }
+
+              const content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> = [];
+
+              const summaryText = result.match
+                ? `MATCH: ${componentName} matches Figma design (${result.diffPercentage}% diff, threshold: ${result.threshold}%)`
+                : `MISMATCH: ${componentName} differs from Figma design by ${result.diffPercentage}% (threshold: ${result.threshold}%)`;
+
+              content.push({ type: 'text' as const, text: summaryText });
+
+              if (result.diff && !result.match) {
+                content.push({
+                  type: 'image' as const,
+                  data: result.diff.replace('data:image/png;base64,', ''),
+                  mimeType: 'image/png',
+                });
+                content.push({
+                  type: 'text' as const,
+                  text: `Diff image above shows visual differences (red highlights). Changed regions: ${result.changedRegions?.length ?? 0}`,
+                });
+              }
+
+              content.push({
+                type: 'text' as const,
+                text: JSON.stringify({
+                  match: result.match,
+                  diffPercentage: result.diffPercentage,
+                  threshold: result.threshold,
+                  figmaUrl: result.figmaUrl,
+                  changedRegions: result.changedRegions,
+                }, null, 2),
+              });
+
+              return { content };
+            } catch (error) {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: `Failed to compare component: ${error instanceof Error ? error.message : 'Unknown error'}. Make sure the Fragments dev server is running and FIGMA_ACCESS_TOKEN is set.`,
+                }],
+                isError: true,
+              };
+            }
+          }
+
+          // --- Default: pure render mode ---
+          const baseUrl = config.viewerUrl ?? 'http://localhost:6006';
+          const renderUrl = `${baseUrl}/fragments/render`;
+
+          try {
+            const response = await fetch(renderUrl, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                component: componentName,
+                props,
+                viewport: viewport ?? { width: 800, height: 600 },
+              }),
+            });
+
+            const result = await response.json() as { screenshot?: string; error?: string };
+
+            if (!response.ok || result.error) {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: `Render error: ${result.error ?? 'Unknown error'}`,
+                }],
+                isError: true,
+              };
+            }
+
+            return {
+              content: [
+                {
+                  type: 'image' as const,
+                  data: result.screenshot!.replace('data:image/png;base64,', ''),
+                  mimeType: 'image/png',
+                },
+                {
+                  type: 'text' as const,
+                  text: `Successfully rendered ${componentName} with props: ${JSON.stringify(props)}`,
+                },
+              ],
+            };
+          } catch (error) {
+            return {
+              content: [{
+                type: 'text' as const,
+                text: `Failed to render component: ${error instanceof Error ? error.message : 'Unknown error'}. Make sure the Fragments dev server is running.`,
+              }],
+              isError: true,
+            };
+          }
+        }
+
+        // ================================================================
+        // FIX — unchanged
+        // ================================================================
+        case TOOL_NAMES.fix: {
+          const data = await loadSegments();
+          const componentName = args?.component as string;
+          const variantName = (args?.variant as string) ?? undefined;
+          const fixType = (args?.fixType as 'token' | 'all') ?? 'all';
+
+          if (!componentName) {
+            throw new Error('component is required');
+          }
+
+          const segment = Object.values(data.segments).find(
+            (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
+          );
+
+          if (!segment) {
+            throw new Error(`Component "${componentName}" not found. Use fragments_discover to see available components.`);
+          }
+
+          const baseUrl = config.viewerUrl ?? 'http://localhost:6006';
+          const fixUrl = `${baseUrl}/fragments/fix`;
+
+          try {
+            const response = await fetch(fixUrl, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                component: componentName,
+                variant: variantName,
+                fixType,
+              }),
+            });
+
+            interface FixResult {
+              patches: Array<{ file: string; diff: string }>;
+              summary: string;
+              error?: string;
+            }
+
+            const result = await response.json() as FixResult;
+
+            if (!response.ok || result.error) {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: `Fix generation error: ${result.error ?? 'Unknown error'}`,
+                }],
+                isError: true,
+              };
+            }
+
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify({
+                  component: componentName,
+                  variant: variantName ?? 'all',
+                  fixType,
+                  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.'
+                    : undefined,
+                }, null, 2),
+              }],
+            };
+          } catch (error) {
+            return {
+              content: [{
+                type: 'text' as const,
+                text: `Failed to generate fixes: ${error instanceof Error ? error.message : 'Unknown error'}. Make sure the Fragments dev server is running.`,
+              }],
+              isError: true,
+            };
+          }
+        }
+
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: JSON.stringify({
+              error: error instanceof Error ? error.message : String(error),
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // Cleanup on close
+  server.onclose = async () => {
+    if (browserPool) {
+      await browserPool.shutdown();
+    }
+  };
+
+  return server;
+}
+
+/**
+ * Start the MCP server with stdio transport
+ */
+export async function startMcpServer(config: McpServerConfig): Promise<void> {
+  const server = createMcpServer(config);
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+}