@fragments-sdk/mcp 0.2.0 → 0.2.1

package/dist/chunk-RUZV6VLE.js

@@ -0,0 +1,1264 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+import {
+  BRAND,
+  DEFAULTS,
+  generateContext
+} from "./chunk-7OMNY6JX.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+
+// src/utils.ts
+function projectFields(obj, fields) {
+  if (!fields || fields.length === 0) {
+    return obj;
+  }
+  const result = {};
+  for (const field of fields) {
+    const parts = field.split(".");
+    let source = obj;
+    let target = result;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const isLast = i === parts.length - 1;
+      if (source === null || source === void 0 || typeof source !== "object") {
+        break;
+      }
+      const sourceObj = source;
+      const value = sourceObj[part];
+      if (isLast) {
+        target[part] = value;
+      } else {
+        if (!(part in target)) {
+          target[part] = {};
+        }
+        target = target[part];
+        source = value;
+      }
+    }
+  }
+  return result;
+}
+
+// src/server.ts
+var _service = null;
+async function getService() {
+  if (!_service) {
+    try {
+      _service = await import("./dist-6B7Z5QLH.js");
+    } catch {
+      throw new Error(
+        "Visual tools require playwright. Install it with: npm install playwright"
+      );
+    }
+  }
+  return _service;
+}
+var TOOL_NAMES = {
+  list: `${BRAND.nameLower}_list`,
+  suggest: `${BRAND.nameLower}_suggest`,
+  get: `${BRAND.nameLower}_get`,
+  guidelines: `${BRAND.nameLower}_guidelines`,
+  alternatives: `${BRAND.nameLower}_alternatives`,
+  example: `${BRAND.nameLower}_example`,
+  verify: `${BRAND.nameLower}_verify`,
+  context: `${BRAND.nameLower}_context`,
+  render: `${BRAND.nameLower}_render`,
+  compare: `${BRAND.nameLower}_compare`,
+  fix: `${BRAND.nameLower}_fix`,
+  recipe: `${BRAND.nameLower}_recipe`
+};
+var PLACEHOLDER_PATTERNS = [
+  /^\w+ component is needed$/i,
+  /^Alternative component is more appropriate$/i,
+  /^Use \w+ when you need/i
+];
+function filterPlaceholders(items) {
+  if (!items) return [];
+  return items.filter(
+    (item) => !PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(item.trim()))
+  );
+}
+var TOOLS = [
+  {
+    name: TOOL_NAMES.list,
+    description: `List all available component fragments in the design system. Returns component names, categories, descriptions, and variant counts. Use this FIRST to discover what components exist before implementing any UI.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        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"
+        }
+      }
+    }
+  },
+  {
+    name: TOOL_NAMES.suggest,
+    description: `Given a use case or UI requirement, suggest the most appropriate component(s) from the design system. Use this when you're unsure which component to use for a specific task. Returns ranked suggestions with explanations.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        useCase: {
+          type: "string",
+          description: 'Description of what you want to build (e.g., "form for user email input", "button to submit data", "display a list of items")'
+        },
+        context: {
+          type: "string",
+          description: 'Additional context (e.g., "in a modal", "for mobile", "destructive action")'
+        }
+      },
+      required: ["useCase"]
+    }
+  },
+  {
+    name: TOOL_NAMES.get,
+    description: `Get detailed information about a specific component fragment including props, usage guidelines, and variants. Use this AFTER fragments_list or fragments_suggest to understand a component's API and best practices before implementing. Use 'fields' to request only specific data for token efficiency.`,
+    inputSchema: {
+      type: "object",
+      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"]). If omitted, returns all fields. Supports dot notation for nested fields.'
+        }
+      },
+      required: ["component"]
+    }
+  },
+  {
+    name: TOOL_NAMES.guidelines,
+    description: `Get the usage guidelines for a component - when to use it, when NOT to use it, and best practices. Use this to make the right component choice and avoid common mistakes. Use 'fields' to request only specific data for token efficiency.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        component: {
+          type: "string",
+          description: 'Component name (e.g., "Button", "Input")'
+        },
+        fields: {
+          type: "array",
+          items: { type: "string" },
+          description: 'Specific fields to return (e.g., ["when", "whenNot", "accessibility"]). If omitted, returns all guideline fields.'
+        }
+      },
+      required: ["component"]
+    }
+  },
+  {
+    name: TOOL_NAMES.alternatives,
+    description: `Get alternative and related components for a given component. Use this when a component might not be the right fit, or to understand the component ecosystem.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        component: {
+          type: "string",
+          description: "Component name to find alternatives for"
+        }
+      },
+      required: ["component"]
+    }
+  },
+  {
+    name: TOOL_NAMES.example,
+    description: `Get example code for a component variant. Returns ready-to-use code with props demonstrated. Use this when you need to see HOW to implement a component, not just what props it accepts.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        component: {
+          type: "string",
+          description: 'Component name (e.g., "Button", "Input")'
+        },
+        variant: {
+          type: "string",
+          description: 'Variant name (e.g., "Default", "Primary"). If omitted, returns all variants.'
+        },
+        maxExamples: {
+          type: "number",
+          description: "Maximum number of examples to return (default: all)"
+        },
+        maxLines: {
+          type: "number",
+          description: "Maximum lines per code example (truncates longer examples)"
+        }
+      },
+      required: ["component"]
+    }
+  },
+  {
+    name: TOOL_NAMES.verify,
+    description: `Verify a component render against the baseline screenshot. Use this AFTER implementing or modifying a component to ensure visual consistency with the design system. Returns a diff percentage and visual comparison.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        component: {
+          type: "string",
+          description: "Component name to verify"
+        },
+        variant: {
+          type: "string",
+          description: "Variant name to verify"
+        },
+        theme: {
+          type: "string",
+          enum: ["light", "dark"],
+          description: "Theme to verify (default: light)"
+        },
+        threshold: {
+          type: "number",
+          description: "Diff threshold percentage (default: 5)"
+        }
+      },
+      required: ["component", "variant"]
+    }
+  },
+  {
+    name: TOOL_NAMES.context,
+    description: `Get the complete design system context in a single call. Use this FIRST before any implementation to understand all available components in a token-efficient format. Returns a summary of all components with their categories, usage guidelines, props, and variants.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        format: {
+          type: "string",
+          enum: ["markdown", "json"],
+          description: "Output format (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.render,
+    description: `Render a design system component with specific props and return a screenshot. Use this to VERIFY your UI implementation looks correct. The AI can see what the component looks like and iterate until it's right.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        component: {
+          type: "string",
+          description: 'Component name (e.g., "Button", "Card", "Input")'
+        },
+        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"
+        }
+      },
+      required: ["component"]
+    }
+  },
+  {
+    name: TOOL_NAMES.compare,
+    description: `Compare a rendered component against its Figma design. Returns diff percentage and highlighted differences. Use this to verify your implementation matches the design spec. If the component has a figma URL in its fragment definition, no URL is needed.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        component: {
+          type: "string",
+          description: 'Component name (e.g., "Button", "Input")'
+        },
+        variant: {
+          type: "string",
+          description: "Variant name (optional, uses first variant if not specified)"
+        },
+        props: {
+          type: "object",
+          description: "Props to render with"
+        },
+        figmaUrl: {
+          type: "string",
+          description: "Figma frame URL (optional if segment has figma link)"
+        },
+        threshold: {
+          type: "number",
+          description: "Max acceptable diff percentage (default: 1.0)"
+        }
+      },
+      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_verify identifies issues to automatically fix them.`,
+    inputSchema: {
+      type: "object",
+      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\u2192token replacements, "all" for all available fixes (default: "all")'
+        }
+      },
+      required: ["component"]
+    }
+  },
+  {
+    name: TOOL_NAMES.recipe,
+    description: `Search and retrieve composition recipes \u2014 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",
+      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")'
+        }
+      }
+    }
+  }
+];
+function createMcpServer(config) {
+  const server = new Server(
+    {
+      name: `${BRAND.nameLower}-mcp`,
+      version: "0.0.1"
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  let segmentsData = null;
+  let packageName = null;
+  let browserPool = null;
+  let storageManager = null;
+  let diffEngine = null;
+  let isPoolWarming = false;
+  async function loadSegments() {
+    if (segmentsData) {
+      return segmentsData;
+    }
+    const segmentsPath = join(config.projectRoot, BRAND.outFile);
+    if (!existsSync(segmentsPath)) {
+      throw new Error(
+        `No ${BRAND.outFile} found. Run \`${BRAND.cliCommand} build\` first.`
+      );
+    }
+    const content = await readFile(segmentsPath, "utf-8");
+    segmentsData = JSON.parse(content);
+    return segmentsData;
+  }
+  async function getPackageName() {
+    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);
+        if (pkg.name) {
+          packageName = pkg.name;
+          return packageName;
+        }
+      } catch {
+      }
+    }
+    packageName = "your-component-library";
+    return packageName;
+  }
+  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 * 1e3,
+        poolSize: 2
+        // Keep 2 contexts warm for faster captures
+      });
+    }
+    return browserPool;
+  }
+  function warmBrowserPool() {
+    if (isPoolWarming || browserPool?.isReady) {
+      return;
+    }
+    isPoolWarming = true;
+    getBrowserPool().then((pool) => {
+      pool.warmup().then(() => {
+        isPoolWarming = false;
+      }).catch(() => {
+        isPoolWarming = false;
+      });
+    }).catch(() => {
+      isPoolWarming = false;
+    });
+  }
+  async function getStorageManager() {
+    if (!storageManager) {
+      const { StorageManager } = await getService();
+      storageManager = new StorageManager({
+        projectRoot: config.projectRoot
+      });
+      await storageManager.initialize();
+    }
+    return storageManager;
+  }
+  async function getDiffEngine() {
+    if (!diffEngine) {
+      const { DiffEngine } = await getService();
+      diffEngine = new DiffEngine(config.threshold ?? DEFAULTS.diffThreshold);
+    }
+    return diffEngine;
+  }
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      switch (name) {
+        case TOOL_NAMES.list: {
+          const data = await loadSegments();
+          const category = args?.category ?? void 0;
+          const search = args?.search?.toLowerCase() ?? void 0;
+          const status = args?.status ?? void 0;
+          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",
+                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_suggest for use-case based recommendations, or fragments_get for details on a specific component." : void 0
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        case TOOL_NAMES.suggest: {
+          const data = await loadSegments();
+          const useCase = args?.useCase?.toLowerCase() ?? "";
+          const context = args?.context?.toLowerCase() ?? "";
+          if (!useCase) {
+            throw new Error("useCase is required");
+          }
+          const searchTerms = `${useCase} ${context}`.split(/\s+/).filter(Boolean);
+          const synonymMap = {
+            "form": ["input", "field", "submit", "validation"],
+            "input": ["form", "field", "text", "entry"],
+            "button": ["action", "click", "submit", "trigger"],
+            "action": ["button", "click", "trigger"],
+            "alert": ["notification", "message", "warning", "error", "feedback"],
+            "notification": ["alert", "message", "toast"],
+            "card": ["container", "panel", "box", "content"],
+            "toggle": ["switch", "checkbox", "boolean", "on/off"],
+            "switch": ["toggle", "checkbox", "boolean"],
+            "badge": ["tag", "label", "status", "indicator"],
+            "status": ["badge", "indicator", "state"],
+            "login": ["auth", "signin", "authentication", "form"],
+            "auth": ["login", "signin", "authentication"]
+          };
+          const expandedTerms = new Set(searchTerms);
+          searchTerms.forEach((term) => {
+            const synonyms = synonymMap[term];
+            if (synonyms) {
+              synonyms.forEach((syn) => expandedTerms.add(syn));
+            }
+          });
+          const scored = Object.values(data.segments).map((s) => {
+            let score = 0;
+            const reasons = [];
+            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 category = s.meta.category?.toLowerCase() ?? "";
+            if (searchTerms.some((term) => category.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;
+            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 = [];
+          const categoryCount = {};
+          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 ")}.` : void 0;
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    useCase,
+                    context: context || void 0,
+                    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_list.",
+                    compositionHint,
+                    nextStep: suggestions.length > 0 ? `Use fragments_get("${suggestions[0].component}") for full details, or fragments_guidelines("${suggestions[0].component}") for usage rules.` : void 0
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        case TOOL_NAMES.get: {
+          const data = await loadSegments();
+          const componentName = args?.component;
+          const fields = args?.fields;
+          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_list to see available components.`);
+          }
+          const result = fields && fields.length > 0 ? projectFields(segment, fields) : segment;
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result, null, 2)
+              }
+            ]
+          };
+        }
+        case TOOL_NAMES.guidelines: {
+          const data = await loadSegments();
+          const componentName = args?.component;
+          const fields = args?.fields;
+          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_list to see available components.`);
+          }
+          const guidelines = {
+            component: segment.meta.name,
+            description: segment.meta.description,
+            status: segment.meta.status ?? "stable",
+            when: filterPlaceholders(segment.usage?.when),
+            whenNot: filterPlaceholders(segment.usage?.whenNot),
+            guidelines: segment.usage?.guidelines ?? [],
+            accessibility: segment.usage?.accessibility ?? [],
+            // Include prop constraints as they're often important guidelines
+            propConstraints: Object.entries(segment.props ?? {}).filter(([, prop]) => prop.constraints && prop.constraints.length > 0).map(([name2, prop]) => ({
+              prop: name2,
+              constraints: prop.constraints
+            })),
+            // Include alternatives from relations
+            alternatives: segment.relations?.filter((r) => r.relationship === "alternative").map((r) => ({
+              component: r.component,
+              note: r.note
+            })) ?? []
+          };
+          const result = fields && fields.length > 0 ? projectFields(guidelines, fields) : guidelines;
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result, null, 2)
+              }
+            ]
+          };
+        }
+        case TOOL_NAMES.alternatives: {
+          const data = await loadSegments();
+          const componentName = args?.component;
+          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_list to see available components.`);
+          }
+          const relations = segment.relations ?? [];
+          const referencedBy = Object.values(data.segments).filter(
+            (s) => s.relations?.some((r) => r.component.toLowerCase() === componentName.toLowerCase())
+          ).map((s) => ({
+            component: s.meta.name,
+            relationship: s.relations?.find(
+              (r) => r.component.toLowerCase() === componentName.toLowerCase()
+            )?.relationship,
+            note: s.relations?.find(
+              (r) => r.component.toLowerCase() === componentName.toLowerCase()
+            )?.note
+          }));
+          const sameCategory = Object.values(data.segments).filter(
+            (s) => s.meta.category === segment.meta.category && s.meta.name.toLowerCase() !== componentName.toLowerCase()
+          ).map((s) => ({
+            component: s.meta.name,
+            description: s.meta.description
+          }));
+          return {
+            content: [
+              {
+                type: "text",
+                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}` : void 0
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        case TOOL_NAMES.example: {
+          const data = await loadSegments();
+          const componentName = args?.component;
+          const variantName = args?.variant ?? void 0;
+          const maxExamples = args?.maxExamples;
+          const maxLines = args?.maxLines;
+          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_list to see available components.`);
+          }
+          let variants = segment.variants;
+          if (variantName) {
+            const filtered = variants.filter(
+              (v) => v.name.toLowerCase() === variantName.toLowerCase()
+            );
+            if (filtered.length === 0) {
+              throw new Error(
+                `Variant "${variantName}" not found for ${componentName}. Available: ${variants.map((v) => v.name).join(", ")}`
+              );
+            }
+            variants = filtered;
+          }
+          if (maxExamples && maxExamples > 0) {
+            variants = variants.slice(0, maxExamples);
+          }
+          const truncateCode = (code) => {
+            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)
+              };
+            }
+            const basicCode = `<${segment.meta.name} />`;
+            return {
+              variant: variant.name,
+              description: variant.description,
+              code: basicCode,
+              note: "No code example provided in fragment. Refer to props for customization."
+            };
+          });
+          const pkgName = await getPackageName();
+          const importStatement = `import { ${segment.meta.name} } from '${pkgName}';`;
+          const propsReference = Object.entries(segment.props ?? {}).map(([propName, prop]) => ({
+            name: propName,
+            type: prop.type,
+            required: prop.required,
+            default: prop.default,
+            description: prop.description
+          }));
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    component: segment.meta.name,
+                    import: importStatement,
+                    examples,
+                    propsReference,
+                    tip: "Use the propsReference to customize components. Examples show documented variants."
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        case TOOL_NAMES.context: {
+          const data = await loadSegments();
+          const format = args?.format ?? "markdown";
+          const compact = args?.compact ?? false;
+          const includeCode = args?.includeCode ?? false;
+          const includeRelations = args?.includeRelations ?? false;
+          const segments = Object.values(data.segments);
+          const recipes = Object.values(data.recipes ?? {});
+          const { content, tokenEstimate } = generateContext(segments, {
+            format,
+            compact,
+            include: {
+              code: includeCode,
+              relations: includeRelations
+            }
+          }, recipes);
+          return {
+            content: [
+              {
+                type: "text",
+                text: content
+              }
+            ],
+            // Include token estimate in a way that doesn't pollute the main content
+            _meta: {
+              tokenEstimate
+            }
+          };
+        }
+        case TOOL_NAMES.render: {
+          const componentName = args?.component;
+          const props = args?.props ?? {};
+          const viewport = args?.viewport;
+          if (!componentName) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: "Error: component name is required"
+                }
+              ],
+              isError: true
+            };
+          }
+          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();
+            if (!response.ok || result.error) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: `Render error: ${result.error ?? "Unknown error"}`
+                  }
+                ],
+                isError: true
+              };
+            }
+            return {
+              content: [
+                {
+                  type: "image",
+                  data: result.screenshot.replace("data:image/png;base64,", ""),
+                  mimeType: "image/png"
+                },
+                {
+                  type: "text",
+                  text: `Successfully rendered ${componentName} with props: ${JSON.stringify(props)}`
+                }
+              ]
+            };
+          } catch (error) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Failed to render component: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+        case TOOL_NAMES.compare: {
+          const componentName = args?.component;
+          const variantName = args?.variant;
+          const props = args?.props ?? {};
+          const figmaUrl = args?.figmaUrl;
+          const threshold = args?.threshold ?? 1;
+          if (!componentName) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: "Error: component name is required"
+                }
+              ],
+              isError: true
+            };
+          }
+          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
+              })
+            });
+            const result = await response.json();
+            if (!response.ok || result.error) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: `Compare error: ${result.error ?? "Unknown error"}${result.suggestion ? `
+Suggestion: ${result.suggestion}` : ""}`
+                  }
+                ],
+                isError: true
+              };
+            }
+            const content = [];
+            const summaryText = result.match ? `\u2705 MATCH: ${componentName} matches Figma design (${result.diffPercentage}% diff, threshold: ${result.threshold}%)` : `\u274C MISMATCH: ${componentName} differs from Figma design by ${result.diffPercentage}% (threshold: ${result.threshold}%)`;
+            content.push({
+              type: "text",
+              text: summaryText
+            });
+            if (result.diff && !result.match) {
+              content.push({
+                type: "image",
+                data: result.diff.replace("data:image/png;base64,", ""),
+                mimeType: "image/png"
+              });
+              content.push({
+                type: "text",
+                text: `Diff image above shows visual differences (red highlights). Changed regions: ${result.changedRegions?.length ?? 0}`
+              });
+            }
+            content.push({
+              type: "text",
+              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",
+                  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
+            };
+          }
+        }
+        case TOOL_NAMES.fix: {
+          const data = await loadSegments();
+          const componentName = args?.component;
+          const variantName = args?.variant ?? void 0;
+          const fixType = args?.fixType ?? "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_list 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
+              })
+            });
+            const result = await response.json();
+            if (!response.ok || result.error) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: `Fix generation error: ${result.error ?? "Unknown error"}`
+                  }
+                ],
+                isError: true
+              };
+            }
+            return {
+              content: [
+                {
+                  type: "text",
+                  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_verify to confirm fixes." : void 0
+                  }, null, 2)
+                }
+              ]
+            };
+          } catch (error) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Failed to generate fixes: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+        case TOOL_NAMES.recipe: {
+          const data = await loadSegments();
+          const recipeName = args?.name;
+          const search = args?.search?.toLowerCase() ?? void 0;
+          const component = args?.component?.toLowerCase() ?? void 0;
+          const allRecipes = Object.values(data.recipes ?? {});
+          if (allRecipes.length === 0) {
+            return {
+              content: [{
+                type: "text",
+                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",
+              text: JSON.stringify({
+                total: filtered.length,
+                recipes: filtered
+              }, null, 2)
+            }]
+          };
+        }
+        case TOOL_NAMES.verify: {
+          const { Timer, CaptureEngine: CE, bufferToBase64Url: toBase64 } = await getService();
+          const timer = new Timer();
+          const componentName = args?.component;
+          const variantName = args?.variant;
+          const theme = args?.theme ?? config.theme ?? DEFAULTS.theme;
+          const threshold = args?.threshold ?? config.threshold ?? DEFAULTS.diffThreshold;
+          if (!componentName || !variantName) {
+            throw new Error("component and variant are required");
+          }
+          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",
+                  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() }
+                    },
+                    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 = {
+            verdict: matches ? "pass" : "fail",
+            matches,
+            diffPercentage: diffResult.diffPercentage,
+            screenshot: toBase64(current.data),
+            baseline: toBase64(baseline.data),
+            diffImage: diffResult.diffImage ? toBase64(diffResult.diffImage) : void 0,
+            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",
+                text: JSON.stringify(result, null, 2)
+              }
+            ]
+          };
+        }
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: error instanceof Error ? error.message : String(error)
+            })
+          }
+        ],
+        isError: true
+      };
+    }
+  });
+  server.onclose = async () => {
+    if (browserPool) {
+      await browserPool.shutdown();
+    }
+  };
+  return server;
+}
+async function startMcpServer(config) {
+  const server = createMcpServer(config);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+export {
+  createMcpServer,
+  startMcpServer
+};
+//# sourceMappingURL=chunk-RUZV6VLE.js.map