@fragments-sdk/mcp 0.8.1 → 0.10.0

package/dist/chunk-YJTMK4JY.js

@@ -0,0 +1,4270 @@
+import {
+  BRAND
+} from "./chunk-4SVS3AA3.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { existsSync as existsSync8 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
+import { join as join7 } from "path";
+import { fileURLToPath } from "url";
+
+// src/config.ts
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+function loadConfigFile(projectRoot) {
+  const configPath = join(projectRoot, "ds-mcp.config.json");
+  if (existsSync(configPath)) {
+    try {
+      const content = readFileSync(configPath, "utf-8");
+      return JSON.parse(content);
+    } catch (e) {
+      throw new Error(`Failed to parse ${configPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  const pkgPath = join(projectRoot, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const content = readFileSync(pkgPath, "utf-8");
+      const pkg = JSON.parse(content);
+      if (pkg.dsMcp) return pkg.dsMcp;
+    } catch {
+    }
+  }
+  return null;
+}
+
+// src/server.ts
+import { buildMcpTools, buildToolNames, MCP_TOOL_DEFINITIONS } from "@fragments-sdk/context/mcp-tools";
+
+// src/version.ts
+import { readFileSync as readFileSync2 } from "fs";
+function readPackageVersion() {
+  try {
+    const raw = readFileSync2(new URL("../package.json", import.meta.url), "utf-8");
+    const pkg = JSON.parse(raw);
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var MCP_SERVER_VERSION = readPackageVersion();
+
+// src/catalog-meta.ts
+function getCatalogMeta(data) {
+  const rawUpdatedAt = data.validateFixContext?.updatedAt ?? data.snapshot.metadata.updatedAt;
+  const updatedAt = typeof rawUpdatedAt === "number" ? new Date(rawUpdatedAt).toISOString() : rawUpdatedAt;
+  return {
+    catalogRevision: data.validateFixContext?.catalogRevision ?? data.snapshot.metadata.revision,
+    updatedAt
+  };
+}
+
+// src/token-suggestions.ts
+function propertyFamilyFor(property, value) {
+  const prop = property.toLowerCase().trim();
+  const normalizedValue = value?.toLowerCase().trim();
+  if (prop.includes("shadow")) return "shadow";
+  if (prop.includes("z-index")) return "z-index";
+  if (prop.includes("transition") || prop.includes("duration") || prop.includes("animation")) {
+    return "duration";
+  }
+  if (prop.includes("font") || prop.includes("line-height") || prop === "letter-spacing") {
+    return "typography";
+  }
+  if (prop.includes("radius")) return "radius";
+  if (prop.endsWith("border-width") || prop === "border-width" || prop === "outline-width" || prop === "stroke-width") {
+    return "border-width";
+  }
+  if (prop.includes("color") || prop === "background" || prop.startsWith("background-") || prop === "fill" || prop === "stroke" || prop === "caret-color" || prop === "accent-color" || (prop === "border" || prop === "outline") && normalizedValue && looksLikeColor(normalizedValue)) {
+    return "color";
+  }
+  if (prop === "margin" || prop.startsWith("margin-") || prop === "padding" || prop.startsWith("padding-") || prop === "gap" || prop === "row-gap" || prop === "column-gap" || prop === "inset" || prop === "top" || prop === "right" || prop === "bottom" || prop === "left" || prop.endsWith("width") || prop.endsWith("height")) {
+    return "spacing";
+  }
+  return "other";
+}
+function suggestToken(input) {
+  const family = propertyFamilyFor(input.property, input.value);
+  const limit = Math.min(Math.max(input.limit ?? 5, 1), 10);
+  const candidates = input.tokens ? scoreCandidates(input.tokens, family, input) : [];
+  const top = candidates.slice(0, limit).map(
+    (candidate) => presentCandidate(candidate, input.tokens)
+  );
+  const meta = {
+    propertyFamily: family,
+    catalogRevision: input.catalogRevision,
+    updatedAt: input.updatedAt,
+    candidateCount: candidates.length
+  };
+  if (family === "other") {
+    return {
+      alternatives: [],
+      noSuggestion: true,
+      noSuggestionReason: `No token family is known for CSS property "${input.property}".`,
+      _meta: meta
+    };
+  }
+  if (!input.tokens || input.tokens.total === 0) {
+    return {
+      alternatives: [],
+      noSuggestion: true,
+      noSuggestionReason: "No design tokens are available in the active catalog.",
+      _meta: meta
+    };
+  }
+  if (top.length === 0) {
+    return {
+      alternatives: [],
+      noSuggestion: true,
+      noSuggestionReason: `No ${family} tokens are available for CSS property "${input.property}".`,
+      _meta: meta
+    };
+  }
+  const [recommended, ...alternatives] = top;
+  return {
+    recommended,
+    alternatives,
+    _meta: meta
+  };
+}
+function scoreCandidates(tokenData, family, input) {
+  if (family === "other") return [];
+  const value = normalizeComparableValue(input.value);
+  const flatTokens = tokenData.flat.length > 0 ? tokenData.flat : Object.values(tokenData.categories).flat();
+  const familyTokens = flatTokens.filter((token) => !isGarbageToken(token)).map((token) => ({ token, family: tokenFamily(token) })).filter((entry) => entry.family === family);
+  const scored = familyTokens.map(({ token }) => {
+    const tokenValue = normalizeComparableValue(token.value);
+    let score = 50;
+    let reason = "family-match";
+    if (value && tokenValue && value === tokenValue) {
+      score += 60;
+      reason = "exact-value-match";
+    } else if (value && tokenValue && family !== "color") {
+      const distanceScore = lengthDistanceScore(value, tokenValue);
+      if (distanceScore > 0) {
+        score += distanceScore;
+        reason = "nearest-neighbor";
+      }
+    }
+    score += nameRelevanceScore(token, input.property, input.context);
+    return { token, family, score, reason };
+  });
+  return scored.filter((candidate) => candidate.score > 0).sort((a, b) => b.score - a.score || a.token.name.localeCompare(b.token.name));
+}
+function presentCandidate(candidate, tokenData) {
+  const cssVar = cssVarForToken(candidate.token);
+  const resolvedValue = resolvedValueForToken(candidate.token);
+  const confidence = candidate.score >= 105 ? "high" : candidate.score >= 65 ? "medium" : "low";
+  return {
+    name: dottedNameForToken(candidate.token, tokenData),
+    ...cssVar && { cssVar },
+    ...cssVar && {
+      cssValue: resolvedValue ? `var(${cssVar}, ${resolvedValue})` : `var(${cssVar})`
+    },
+    ...resolvedValue && { resolvedValue },
+    confidence,
+    reason: candidate.reason
+  };
+}
+function isGarbageToken(token) {
+  const value = token.value?.trim();
+  if (!value) return false;
+  if (value.includes("#{") || value.includes("$")) return true;
+  if (/^\$[\w-]+/.test(token.name)) return true;
+  return false;
+}
+function tokenFamily(token) {
+  const haystack = [
+    token.type,
+    token.category,
+    ...token.path ?? [],
+    token.name
+  ].filter(Boolean).join(" ").toLowerCase();
+  if (/\b(color|colour|background|foreground|surface|palette)\b/.test(haystack)) {
+    return "color";
+  }
+  if (/\b(radius|radii|rounded|corner)\b/.test(haystack)) return "radius";
+  if (/\b(border-width|border width|stroke-width|stroke width)\b/.test(haystack)) {
+    return "border-width";
+  }
+  if (/\b(shadow|elevation)\b/.test(haystack)) return "shadow";
+  if (/\b(font|type|typography|line-height|letter-spacing)\b/.test(haystack)) {
+    return "typography";
+  }
+  if (/\b(duration|transition|animation)\b/.test(haystack)) return "duration";
+  if (/\b(z-index|zindex)\b/.test(haystack)) return "z-index";
+  if (/\b(space|spacing|size|sizing|width|height|gap|padding|margin|inset)\b/.test(haystack)) {
+    return "spacing";
+  }
+  if (/\bborder\b/.test(haystack)) return "border-width";
+  return "other";
+}
+function cssVarForToken(token) {
+  if (token.name.startsWith("--")) return token.name;
+  const match = token.value?.match(/var\((--[\w-]+)/);
+  return match?.[1];
+}
+function dottedNameForToken(token, tokenData) {
+  if (!token.name.startsWith("--")) return token.name;
+  let name = token.name.slice(2);
+  const prefix = tokenData?.prefix?.replace(/^--/, "").replace(/-$/, "");
+  if (prefix && name.startsWith(`${prefix}-`)) {
+    name = name.slice(prefix.length + 1);
+  }
+  return name.replace(/-/g, ".");
+}
+function resolvedValueForToken(token) {
+  const value = token.value?.trim();
+  if (!value) return void 0;
+  const fallback = value.match(/var\(--[\w-]+,\s*([^)]+)\)/)?.[1]?.trim();
+  if (fallback) return fallback;
+  if (value.startsWith("var(")) return void 0;
+  return value;
+}
+function normalizeComparableValue(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim().toLowerCase();
+  const color = normalizeColor(trimmed);
+  if (color) return color;
+  const length = parseLength(trimmed);
+  if (length) return `${length.value}${length.unit}`;
+  return trimmed.replace(/\s+/g, " ");
+}
+function looksLikeColor(value) {
+  return /^#([\da-f]{3,8})$/i.test(value) || /^rgba?\(/i.test(value) || /^hsla?\(/i.test(value);
+}
+function normalizeColor(value) {
+  const hex = value.match(/^#([\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i);
+  if (!hex) return void 0;
+  const body = hex[1].toLowerCase();
+  if (body.length === 3) {
+    return `#${body[0]}${body[0]}${body[1]}${body[1]}${body[2]}${body[2]}`;
+  }
+  return `#${body}`;
+}
+function parseLength(value) {
+  const match = value.match(/^(-?\d+(?:\.\d+)?)(px|rem|em|%)$/);
+  if (!match) return void 0;
+  return { value: Number(match[1]), unit: match[2] };
+}
+function lengthDistanceScore(inputValue, tokenValue) {
+  const input = parseLength(inputValue);
+  const token = parseLength(tokenValue);
+  if (!input || !token || input.unit !== token.unit) return 0;
+  const distance = Math.abs(input.value - token.value);
+  if (distance === 0) return 60;
+  if (distance <= 2) return 35;
+  if (distance <= 4) return 20;
+  if (distance <= 8) return 10;
+  return 0;
+}
+function nameRelevanceScore(token, property, context) {
+  const haystack = [token.name, token.category, ...token.path ?? []].join(" ").toLowerCase();
+  const prop = property.toLowerCase();
+  let score = 0;
+  for (const part of prop.split(/[^a-z0-9]+/).filter((part2) => part2.length > 2)) {
+    if (haystack.includes(part)) score += 4;
+  }
+  if (context === "component" && haystack.includes("component")) score += 3;
+  if (context === "global" && haystack.includes("global")) score += 3;
+  return score;
+}
+
+// src/tools/tokens-suggest.ts
+var tokensSuggestHandler = async (args, ctx) => {
+  const property = args.property;
+  if (!property || typeof property !== "string") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: "property is required." })
+        }
+      ],
+      isError: true
+    };
+  }
+  const context = args.context;
+  const catalogMeta = getCatalogMeta(ctx.data);
+  const result2 = suggestToken({
+    tokens: ctx.data.tokens,
+    property,
+    value: typeof args.value === "string" ? args.value : void 0,
+    context: context === "component" || context === "block" || context === "global" ? context : void 0,
+    catalogRevision: catalogMeta.catalogRevision,
+    updatedAt: catalogMeta.updatedAt
+  });
+  return {
+    content: [{ type: "text", text: JSON.stringify(result2) }],
+    _meta: result2._meta
+  };
+};
+
+// src/tools/spec-govern.ts
+var SEVERITY_WEIGHTS = {
+  critical: 10,
+  serious: 5,
+  moderate: 2,
+  minor: 1
+};
+function isRuleEnabled(rule, defaultEnabled = true) {
+  if (rule === void 0) return defaultEnabled;
+  if (typeof rule === "boolean") return rule;
+  return rule.enabled ?? defaultEnabled;
+}
+function ruleSeverity(rule, fallback) {
+  return typeof rule === "object" && rule?.severity ? rule.severity : fallback;
+}
+function ruleOptions(rule) {
+  return typeof rule === "object" && rule?.options ? rule.options : {};
+}
+function nodeId(node, fallback) {
+  return typeof node.id === "string" ? node.id : `node-${fallback}`;
+}
+function nodeType(node) {
+  return typeof node.type === "string" ? node.type : "_unknown";
+}
+function parentType(type) {
+  const dotIndex = type.indexOf(".");
+  return dotIndex > 0 ? type.slice(0, dotIndex) : type;
+}
+function walkNodes(nodes, visitor) {
+  if (!Array.isArray(nodes)) return;
+  for (const [index, node] of nodes.entries()) {
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+      continue;
+    }
+    const specNode = node;
+    visitor(specNode, index);
+    walkNodes(specNode.children, visitor);
+  }
+}
+function flattenNodes(spec) {
+  const flattened = [];
+  walkNodes(spec.nodes, (node) => flattened.push(node));
+  return flattened;
+}
+function worstSeverity(violations) {
+  const order = ["critical", "serious", "moderate", "minor"];
+  return violations.reduce(
+    (worst, violation) => order.indexOf(violation.severity) < order.indexOf(worst) ? violation.severity : worst,
+    "minor"
+  );
+}
+function result(validator, violations) {
+  return {
+    validator,
+    severity: violations.length > 0 ? worstSeverity(violations) : "minor",
+    passed: violations.length === 0,
+    violations
+  };
+}
+var SEVERITY_SCORE_CAPS = {
+  critical: 25,
+  serious: 50,
+  moderate: 80,
+  minor: 95
+};
+function verdictFor(violations) {
+  if (violations.length === 0) return "pass";
+  const worst = worstSeverity(violations);
+  return worst === "critical" || worst === "serious" ? "fail" : "warn";
+}
+function computeScore(violations) {
+  if (violations.length === 0) return 100;
+  const penalty = violations.reduce(
+    (sum, violation) => sum + SEVERITY_WEIGHTS[violation.severity],
+    0
+  );
+  const cap = SEVERITY_SCORE_CAPS[worstSeverity(violations)];
+  return Math.min(cap, Math.max(0, 100 - penalty));
+}
+function validateComponents(nodes, options) {
+  const rules = options.policy?.rules ?? {};
+  const allowRule = rules["components/allow"];
+  const denyRule = rules["components/deny"];
+  const allowOptions = ruleOptions(allowRule);
+  const denyOptions = ruleOptions(denyRule);
+  const allowed = new Set(
+    (allowOptions.components ?? options.allowedComponents).filter(Boolean)
+  );
+  const denied = new Set(denyOptions.components ?? []);
+  const violations = [];
+  for (const [index, node] of nodes.entries()) {
+    const type = nodeType(node);
+    const parent = parentType(type);
+    if (allowed.size > 0 && isRuleEnabled(allowRule) && !allowed.has(type) && !allowed.has(parent)) {
+      violations.push({
+        nodeId: nodeId(node, index),
+        nodeType: type,
+        rule: "components/allow",
+        severity: ruleSeverity(allowRule, "serious"),
+        message: `Component "${type}" is not in the allowed list`,
+        suggestion: `Use one of the allowed components: ${[...allowed].slice(0, 10).join(", ")}${allowed.size > 10 ? "..." : ""}`
+      });
+    }
+    if (denied.size > 0 && isRuleEnabled(denyRule) && (denied.has(type) || denied.has(parent))) {
+      violations.push({
+        nodeId: nodeId(node, index),
+        nodeType: type,
+        rule: "components/deny",
+        severity: ruleSeverity(denyRule, "serious"),
+        message: `Component "${type}" is blocked by the deny list`,
+        suggestion: `Remove "${type}" or replace it with an allowed alternative`
+      });
+    }
+  }
+  return result("components", violations);
+}
+function isEventHandlerProp(prop) {
+  return /^on[A-Z]/.test(prop);
+}
+function validateSafety(nodes) {
+  const violations = [];
+  const dangerousProps = /* @__PURE__ */ new Set(["dangerouslySetInnerHTML", "innerHTML"]);
+  for (const [index, node] of nodes.entries()) {
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+      if (dangerousProps.has(prop)) {
+        violations.push({
+          nodeId: nodeId(node, index),
+          nodeType: nodeType(node),
+          rule: "safety/no-dangerous-props",
+          severity: "critical",
+          message: `Dangerous prop "${prop}" is not allowed`,
+          suggestion: `Remove "${prop}" or use a safe rendering pattern`,
+          prop
+        });
+      }
+      if (isEventHandlerProp(prop) && typeof value === "string") {
+        violations.push({
+          nodeId: nodeId(node, index),
+          nodeType: nodeType(node),
+          rule: "safety/no-string-handlers",
+          severity: "serious",
+          message: `Event handler prop "${prop}" must not be a string`,
+          suggestion: `Remove "${prop}" from generated specs`,
+          prop
+        });
+      }
+    }
+  }
+  return result("safety", violations);
+}
+function editDistance(a, b) {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const distances = Array.from({ length: rows }, () => Array(cols).fill(0));
+  for (let i = 0; i < rows; i++) distances[i][0] = i;
+  for (let j = 0; j < cols; j++) distances[0][j] = j;
+  for (let i = 1; i < rows; i++) {
+    for (let j = 1; j < cols; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      distances[i][j] = Math.min(
+        distances[i - 1][j] + 1,
+        distances[i][j - 1] + 1,
+        distances[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return distances[a.length][b.length];
+}
+function normalizePropValue(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function closestAllowedValue(rawValue, allowedValues) {
+  const normalizedRaw = normalizePropValue(rawValue);
+  const ranked = allowedValues.map((value) => {
+    const normalizedValue = normalizePropValue(value);
+    const distance = editDistance(normalizedRaw, normalizedValue);
+    const prefixMatch = normalizedRaw.length >= 4 && (normalizedValue.startsWith(normalizedRaw) || normalizedRaw.startsWith(normalizedValue));
+    return { value, distance, prefixMatch };
+  }).sort((a, b) => {
+    if (a.prefixMatch !== b.prefixMatch) return a.prefixMatch ? -1 : 1;
+    return a.distance - b.distance || a.value.localeCompare(b.value);
+  });
+  const best = ranked[0];
+  if (!best) return void 0;
+  if (best.prefixMatch || best.distance <= 2) return best.value;
+  return void 0;
+}
+function validateProps(nodes, options) {
+  const rules = options.policy?.rules ?? {};
+  const propRule = rules["props/valid-values"];
+  const componentProps = options.componentProps ?? {};
+  const violations = [];
+  if (!isRuleEnabled(propRule)) {
+    return result("props", violations);
+  }
+  for (const [index, node] of nodes.entries()) {
+    const type = nodeType(node);
+    const propSchema = componentProps[type] ?? componentProps[parentType(type)];
+    if (!propSchema) continue;
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+      const allowedValues = propSchema[prop]?.values?.filter(Boolean) ?? [];
+      if (allowedValues.length === 0) continue;
+      const rawValue = typeof value === "string" ? value : void 0;
+      if (!rawValue || allowedValues.includes(rawValue)) continue;
+      const closest = closestAllowedValue(rawValue, allowedValues);
+      violations.push({
+        nodeId: nodeId(node, index),
+        nodeType: type,
+        rule: "props/invalid-value",
+        severity: ruleSeverity(propRule, "moderate"),
+        message: `Prop "${prop}" on ${type} has invalid value "${rawValue}"`,
+        suggestion: closest ? `Use "${closest}" for prop "${prop}" on ${type}.` : `Use one of: ${allowedValues.join(", ")}`,
+        prop,
+        rawValue
+      });
+    }
+  }
+  return result("props", violations);
+}
+function hasHardcodedCssValue(value) {
+  if (value.includes("var(")) return false;
+  return /#[0-9a-f]{3,8}\b/i.test(value) || /\b\d+(?:px|rem|em)\b/.test(value);
+}
+function validateTokens(nodes, options) {
+  const rules = options.policy?.rules ?? {};
+  const requireRule = rules["tokens/require-design-tokens"];
+  const prefixRule = rules["tokens/allowed-prefixes"];
+  const requireTokens = isRuleEnabled(requireRule);
+  const defaultTokenPrefix = options.tokenPrefix?.replace(/^--/, "");
+  const allowedPrefixes = ruleOptions(prefixRule).prefixes ?? (defaultTokenPrefix ? [defaultTokenPrefix] : []);
+  const violations = [];
+  for (const [index, node] of nodes.entries()) {
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+      if (typeof value !== "string") continue;
+      if (requireTokens && hasHardcodedCssValue(value)) {
+        violations.push({
+          nodeId: nodeId(node, index),
+          nodeType: nodeType(node),
+          rule: "tokens/require-design-tokens",
+          severity: ruleSeverity(requireRule, "moderate"),
+          message: `Hardcoded CSS value "${value}" in prop "${prop}" - use a design token instead`,
+          suggestion: "Use a design token instead of a hardcoded CSS value",
+          prop,
+          rawValue: value
+        });
+      }
+      if (allowedPrefixes.length > 0 && isRuleEnabled(prefixRule, Boolean(options.tokenPrefix))) {
+        const matches = value.matchAll(/var\(--([^)]+)\)/g);
+        for (const match of matches) {
+          const tokenName = match[1];
+          if (allowedPrefixes.some((prefix) => tokenName.startsWith(prefix))) {
+            continue;
+          }
+          violations.push({
+            nodeId: nodeId(node, index),
+            nodeType: nodeType(node),
+            rule: "tokens/allowed-prefixes",
+            severity: ruleSeverity(prefixRule, "moderate"),
+            message: `Token "--${tokenName}" does not use an allowed prefix (${allowedPrefixes.join(", ")})`,
+            suggestion: `Use a token with one of the allowed prefixes: ${allowedPrefixes.map((prefix) => `--${prefix}*`).join(", ")}`,
+            prop,
+            rawValue: value
+          });
+        }
+      }
+    }
+  }
+  return result("tokens", violations);
+}
+function textFromUnknown(value) {
+  if (typeof value === "string") return value.trim();
+  if (Array.isArray(value)) return textFromChildren(value);
+  if (typeof value === "object" && value !== null) {
+    return textFromNode(value);
+  }
+  return "";
+}
+function textFromNode(node) {
+  const type = nodeType(node).toLowerCase();
+  const props = node.props ?? {};
+  const propText = [
+    textFromUnknown(props.children),
+    type === "text" ? textFromUnknown(props.value) : ""
+  ].filter(Boolean);
+  const childText = textFromChildren(node.children);
+  return [...propText, childText].join(" ").trim();
+}
+function textFromChildren(children) {
+  if (typeof children === "string") return children.trim();
+  if (!Array.isArray(children)) return "";
+  return children.map((child) => {
+    return textFromUnknown(child);
+  }).join(" ").trim();
+}
+function validateA11y(nodes) {
+  const violations = [];
+  for (const [index, node] of nodes.entries()) {
+    const type = nodeType(node);
+    if (!/button/i.test(type)) continue;
+    const props = node.props ?? {};
+    const label = props["aria-label"] ?? props["aria-labelledby"] ?? props.title;
+    const childText = textFromNode(node);
+    if (typeof label === "string" && label.trim().length > 0) continue;
+    if (childText.length > 0) continue;
+    violations.push({
+      nodeId: nodeId(node, index),
+      nodeType: type,
+      rule: "button-name",
+      severity: "serious",
+      message: "Buttons must have discernible text (button-name)",
+      suggestion: "Add visible text or an aria-label"
+    });
+  }
+  return result("a11y", violations);
+}
+function runSpecGovern(spec, options) {
+  const startedAt = Date.now();
+  const nodes = flattenNodes(spec);
+  const results = [
+    validateSafety(nodes),
+    validateComponents(nodes, options),
+    validateProps(nodes, options),
+    validateTokens(nodes, options),
+    validateA11y(nodes)
+  ];
+  const violations = results.flatMap((entry) => entry.violations);
+  const componentTypes = Array.from(
+    new Set(nodes.map((node) => nodeType(node)))
+  );
+  return {
+    verdict: verdictFor(violations),
+    passed: results.every((entry) => entry.passed),
+    score: computeScore(violations),
+    results,
+    metadata: {
+      runner: "mcp",
+      duration: Date.now() - startedAt,
+      nodeCount: nodes.length,
+      componentTypes
+    }
+  };
+}
+function formatVerdict(verdict, format = "summary") {
+  if (format === "json") {
+    return JSON.stringify(verdict, null, 2);
+  }
+  const lines = [];
+  const icon = verdict.passed ? "ok" : "fail";
+  lines.push(`${icon} Governance check: verdict ${verdict.verdict}, score ${verdict.score}/100`);
+  lines.push("");
+  for (const entry of verdict.results) {
+    const resultIcon = entry.passed ? "ok" : "fail";
+    const count = entry.violations.length;
+    lines.push(`  ${resultIcon} ${entry.validator}: ${count === 0 ? "passed" : `${count} violation(s)`}`);
+    for (const violation of entry.violations) {
+      lines.push(`    - [${violation.severity}] ${violation.nodeType}#${violation.nodeId}: ${violation.message}`);
+      if (violation.suggestion) {
+        lines.push(`      -> ${violation.suggestion}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push(`Duration: ${verdict.metadata.duration.toFixed(0)}ms | Nodes: ${verdict.metadata.nodeCount}`);
+  return lines.join("\n");
+}
+
+// src/tools/govern.ts
+function buildComponentProps(ctx) {
+  return Object.fromEntries(
+    Object.values(ctx.data.components).map((component) => [
+      component.name,
+      component.props
+    ])
+  );
+}
+var governHandler = async (args, ctx) => {
+  const spec = args?.spec;
+  if (!spec || typeof spec !== "object") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "spec is required and must be an object with { nodes: [{ id, type, props, children }], root?, metadata? }. See the govern.schema MCP resource for the full schema."
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  const policyOverrides = args?.policy;
+  const format = args?.format ?? "json";
+  const allowedComponents = Object.values(ctx.data.components).map(
+    (component) => component.name
+  );
+  try {
+    const verdict = runSpecGovern(spec, {
+      allowedComponents,
+      tokenPrefix: ctx.data.tokens?.prefix,
+      policy: policyOverrides,
+      componentProps: buildComponentProps(ctx)
+    });
+    const text = format === "summary" ? formatVerdict(verdict, "summary") : JSON.stringify(verdict);
+    return {
+      content: [{ type: "text", text }],
+      _meta: {
+        ...getCatalogMeta(ctx.data),
+        verdict: verdict.verdict,
+        score: verdict.score,
+        passed: verdict.passed,
+        violationCount: verdict.results.reduce(
+          (sum, r) => sum + r.violations.length,
+          0
+        )
+      }
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const isSpecError = message.includes("Expected") || message.includes("Required");
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: isSpecError ? `Invalid spec format: ${message}. Expected: { nodes: [{ id?: string, type: string, props?: object, children?: array|string }], root?: string, metadata?: object }. See the govern.schema MCP resource for examples.` : message
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+
+// src/tools/validate-and-fix.ts
+function classifyComponent(component) {
+  if (component.status === "deprecated") return "discouraged";
+  if (component.isCanonical && component.tier === "core") return "preferred";
+  return "allowed";
+}
+function buildEffectiveComponents(ctx) {
+  const validateFixByKey = new Map(
+    (ctx.data.validateFixContext?.components ?? []).map((component) => [
+      component.componentKey,
+      component
+    ])
+  );
+  return Object.entries(ctx.data.components).map(([componentKey, component]) => ({
+    component,
+    selection: validateFixByKey.get(componentKey)?.selection ?? classifyComponent(component),
+    isActive: validateFixByKey.get(componentKey)?.isActive ?? true,
+    reasons: validateFixByKey.get(componentKey)?.reasons ?? []
+  }));
+}
+function cloneSpec(spec) {
+  return structuredClone(spec);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateNodeShape(node, path) {
+  if (!isPlainObject(node)) {
+    return `${path} must be an object`;
+  }
+  if ("id" in node && node.id !== void 0 && typeof node.id !== "string") {
+    return `${path}.id must be a string`;
+  }
+  if ("type" in node && node.type !== void 0 && typeof node.type !== "string") {
+    return `${path}.type must be a string`;
+  }
+  if ("props" in node && node.props !== void 0 && !isPlainObject(node.props)) {
+    return `${path}.props must be an object`;
+  }
+  if ("children" in node && node.children !== void 0) {
+    if (typeof node.children === "string") {
+      return null;
+    }
+    if (!Array.isArray(node.children)) {
+      return `${path}.children must be an array or string`;
+    }
+    for (const [index, child] of node.children.entries()) {
+      if (!isPlainObject(child)) continue;
+      const childError = validateNodeShape(
+        child,
+        `${path}.children[${index}]`
+      );
+      if (childError) return childError;
+    }
+  }
+  return null;
+}
+function validateSpecShape(spec) {
+  if (!isPlainObject(spec)) {
+    return "spec must be an object";
+  }
+  if ("root" in spec && spec.root !== void 0 && typeof spec.root !== "string") {
+    return "spec.root must be a string";
+  }
+  if ("metadata" in spec && spec.metadata !== void 0 && !isPlainObject(spec.metadata)) {
+    return "spec.metadata must be an object";
+  }
+  if ("nodes" in spec && spec.nodes !== void 0) {
+    if (!Array.isArray(spec.nodes)) {
+      return "spec.nodes must be an array";
+    }
+    for (const [index, node] of spec.nodes.entries()) {
+      const error = validateNodeShape(node, `spec.nodes[${index}]`);
+      if (error) return error;
+    }
+  }
+  return null;
+}
+function getSelectionNames(effectiveComponents, selection) {
+  const selections = Array.isArray(selection) ? selection : [selection];
+  return Array.from(
+    new Set(
+      effectiveComponents.filter((entry) => selections.includes(entry.selection)).map((entry) => entry.component.name)
+    )
+  );
+}
+function normalizeTokens(value) {
+  return value.toLowerCase().split(/[^a-z0-9]+/g).map((token) => token.trim()).filter((token) => token.length >= 3);
+}
+function buildComponentText(component) {
+  return [
+    component.name,
+    component.category,
+    component.description,
+    component.guidance.usageGuidance,
+    ...component.guidance.when,
+    ...component.guidance.whenNot,
+    ...component.guidance.dos,
+    ...component.guidance.donts
+  ].filter(Boolean).join(" ");
+}
+function rankReplacementCandidates(args) {
+  const nodePropKeys = Object.keys(args.node.props ?? {});
+  const sourcePropKeys = new Set(Object.keys(args.source.component.props ?? {}));
+  const sourceTokens = new Set(normalizeTokens(buildComponentText(args.source.component)));
+  return args.candidates.map((candidate) => {
+    let score = 0;
+    const reasons = [];
+    const candidatePropKeys = new Set(Object.keys(candidate.component.props ?? {}));
+    if (candidate.selection === "preferred") {
+      score += 12;
+      reasons.push("preferred selection");
+    }
+    if (candidate.component.isCanonical) {
+      score += 6;
+      reasons.push("canonical component");
+    }
+    if (candidate.component.tier === "core") {
+      score += 4;
+      reasons.push("core tier");
+    }
+    if (candidate.isActive) {
+      score += 3;
+      reasons.push("active component");
+    }
+    const supportedNodeProps = nodePropKeys.filter(
+      (key) => candidatePropKeys.has(key)
+    );
+    if (supportedNodeProps.length > 0) {
+      score += supportedNodeProps.length * 5;
+      reasons.push(`supports node props: ${supportedNodeProps.join(", ")}`);
+    }
+    const missingNodeProps = nodePropKeys.filter(
+      (key) => !candidatePropKeys.has(key)
+    );
+    if (missingNodeProps.length > 0) {
+      score -= missingNodeProps.length * 6;
+      reasons.push(`missing node props: ${missingNodeProps.join(", ")}`);
+    }
+    const sharedContractProps = [...sourcePropKeys].filter(
+      (key) => candidatePropKeys.has(key)
+    );
+    if (sharedContractProps.length > 0) {
+      score += sharedContractProps.length * 2;
+      reasons.push(`shares source props: ${sharedContractProps.join(", ")}`);
+    }
+    const candidateTokens = new Set(
+      normalizeTokens(buildComponentText(candidate.component))
+    );
+    const tokenOverlap = [...candidateTokens].filter(
+      (token) => sourceTokens.has(token)
+    );
+    if (tokenOverlap.length > 0) {
+      score += Math.min(tokenOverlap.length, 4);
+      reasons.push(`guidance overlap: ${tokenOverlap.join(", ")}`);
+    }
+    if (candidate.component.parentComponentId && candidate.component.parentComponentId === args.source.component.parentComponentId) {
+      score += 2;
+      reasons.push("matches parent component");
+    }
+    return {
+      name: candidate.component.name,
+      score,
+      reasons
+    };
+  }).sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+}
+function chooseDeterministicCandidate(rankedCandidates) {
+  if (rankedCandidates.length === 0) return null;
+  if (rankedCandidates.length === 1) return rankedCandidates[0].name;
+  const [first, second] = rankedCandidates;
+  if (first.score <= 0) return null;
+  if (first.score - second.score < 4) return null;
+  return first.name;
+}
+function countViolations(verdict) {
+  return verdict.results.reduce(
+    (sum, result2) => sum + result2.violations.length,
+    0
+  );
+}
+function getNextAction(status, replacements, unresolvedAmbiguityCount) {
+  if (status === "pass") return "none";
+  if (status === "fixed") return "apply_fixed_spec";
+  if (status === "partial_fix") return "review_partial_fix";
+  if (unresolvedAmbiguityCount > 0) return "resolve_ambiguities";
+  if (replacements.length > 0) return "review_partial_fix";
+  return "revise_input";
+}
+function authorizationForAmbiguity(args) {
+  const required = [];
+  if (!args.applyFixes) {
+    required.push("applyFixes");
+  }
+  if (!args.allowElicitation) {
+    required.push("allowElicitation");
+  } else if (!args.supportsElicitation) {
+    required.push("clientCapabilities.elicitation.form");
+  }
+  if (!args.allowSampling) {
+    required.push("allowSampling");
+  } else if (!args.supportsSampling) {
+    required.push("clientCapabilities.sampling");
+  }
+  return required;
+}
+function buildWouldFixIfAuthorized(args) {
+  const entries = [];
+  if (!args.applyFixes) {
+    entries.push(
+      ...args.deterministicPreview.map((replacement) => ({
+        action: "replace_component",
+        nodeId: replacement.nodeId,
+        from: replacement.from,
+        to: replacement.to,
+        reason: replacement.reason,
+        requiredAuthorization: ["applyFixes"]
+      }))
+    );
+  }
+  const requiredAuthorization = authorizationForAmbiguity({
+    applyFixes: args.applyFixes,
+    allowElicitation: args.allowElicitation,
+    allowSampling: args.allowSampling,
+    supportsElicitation: args.supportsElicitation,
+    supportsSampling: args.supportsSampling
+  });
+  if (requiredAuthorization.length > 0) {
+    entries.push(
+      ...args.unresolvedAmbiguities.map((ambiguity) => ({
+        action: "resolve_ambiguous_component",
+        nodeId: ambiguity.nodeId,
+        from: ambiguity.from,
+        candidates: ambiguity.candidates,
+        rankedCandidates: ambiguity.rankedCandidates,
+        reason: ambiguity.reason,
+        requiredAuthorization
+      }))
+    );
+  }
+  return entries;
+}
+async function emitValidateAndFixTelemetry(args) {
+  if (!args.ctx.mcp?.server) return;
+  try {
+    await args.ctx.mcp.server.sendLoggingMessage({
+      level: "info",
+      data: JSON.stringify({
+        tool: "validate_and_fix",
+        status: args.status,
+        nextAction: args.nextAction,
+        resolutionPath: args.resolutionPath,
+        evaluation: args.evaluation,
+        attestation: args.attestation
+      }),
+      logger: "fragments-mcp"
+    });
+  } catch {
+  }
+}
+function buildAllowedComponents(ctx) {
+  return buildEffectiveComponents(ctx).filter(({ selection }) => selection === "preferred" || selection === "allowed").map(({ component }) => component.name);
+}
+function buildComponentProps2(ctx) {
+  return Object.fromEntries(
+    Object.values(ctx.data.components).map((component) => [
+      component.name,
+      component.props
+    ])
+  );
+}
+function runGovern(spec, ctx, policyOverrides) {
+  return runSpecGovern(spec, {
+    allowedComponents: buildAllowedComponents(ctx),
+    tokenPrefix: ctx.data.tokens?.prefix,
+    policy: policyOverrides,
+    componentProps: buildComponentProps2(ctx)
+  });
+}
+function walkNodes2(nodes, visitor, path = "nodes") {
+  for (const [index, node] of nodes.entries()) {
+    if (!isPlainObject(node)) continue;
+    const nodeRef = `${path}[${index}]`;
+    visitor(node, nodeRef);
+    if (Array.isArray(node.children)) {
+      walkNodes2(node.children, visitor, `${nodeRef}.children`);
+    }
+  }
+}
+function applyDeterministicReplacements(spec, ctx) {
+  const effectiveComponents = buildEffectiveComponents(ctx);
+  const byName = /* @__PURE__ */ new Map();
+  const preferredByCategory = /* @__PURE__ */ new Map();
+  for (const entry of effectiveComponents) {
+    const list = byName.get(entry.component.name) ?? [];
+    list.push(entry);
+    byName.set(entry.component.name, list);
+    if (entry.selection !== "preferred") continue;
+    const category = entry.component.category ?? "uncategorized";
+    const names = preferredByCategory.get(category) ?? [];
+    if (!names.includes(entry.component.name)) {
+      names.push(entry.component.name);
+    }
+    preferredByCategory.set(category, names);
+  }
+  const fixedSpec = cloneSpec(spec);
+  const nodes = Array.isArray(fixedSpec.nodes) ? fixedSpec.nodes : [];
+  const replacements = [];
+  const ambiguities = [];
+  walkNodes2(nodes, (node, nodeRef) => {
+    if (!node.type) return;
+    const componentEntries = byName.get(node.type) ?? [];
+    const component = componentEntries[0];
+    if (!component || component.selection !== "discouraged" && component.selection !== "forbidden") {
+      return;
+    }
+    const candidateEntries = (preferredByCategory.get(component.component.category ?? "uncategorized") ?? []).filter((candidate) => candidate !== component.component.name).map(
+      (candidateName) => effectiveComponents.find(
+        (entry) => entry.component.name === candidateName
+      )
+    ).filter((entry) => Boolean(entry));
+    const rankedCandidates = rankReplacementCandidates({
+      source: component,
+      candidates: candidateEntries,
+      node
+    });
+    const replacement = chooseDeterministicCandidate(rankedCandidates);
+    if (!replacement) {
+      if (rankedCandidates.length > 1) {
+        ambiguities.push({
+          nodeId: node.id ?? node.type,
+          nodeRef,
+          from: component.component.name,
+          candidates: rankedCandidates.map((candidate) => candidate.name),
+          rankedCandidates,
+          reason: "ambiguous_preferred_components"
+        });
+      }
+      return;
+    }
+    replacements.push({
+      nodeId: node.id ?? node.type,
+      from: component.component.name,
+      to: replacement,
+      reason: "deprecated_component",
+      mode: "deterministic"
+    });
+    node.type = replacement;
+  });
+  return {
+    fixedSpec,
+    replacements,
+    ambiguities
+  };
+}
+function applyReplacementAtRef(spec, nodeRef, replacement) {
+  const nodes = Array.isArray(spec.nodes) ? spec.nodes : [];
+  let applied = false;
+  walkNodes2(nodes, (node, currentRef) => {
+    if (applied || currentRef !== nodeRef) return;
+    node.type = replacement;
+    applied = true;
+  });
+  return applied;
+}
+function supportsFormElicitation(ctx) {
+  const capabilities = ctx.mcp?.clientCapabilities?.elicitation;
+  if (!capabilities) return false;
+  return capabilities.form !== void 0 || capabilities.url === void 0;
+}
+function supportsSampling(ctx) {
+  return Boolean(ctx.mcp?.clientCapabilities?.sampling);
+}
+function getSamplingText(response) {
+  if (Array.isArray(response.content)) {
+    return response.content.find((item) => item.type === "text")?.text;
+  }
+  return response.content.type === "text" ? response.content.text : void 0;
+}
+function buildComponentGuidanceMap(ctx) {
+  return new Map(
+    Object.values(ctx.data.components).map((component) => {
+      const guidance = [];
+      if (component.description) {
+        guidance.push(`description: ${component.description}`);
+      }
+      if (component.guidance.usageGuidance) {
+        guidance.push(`usage: ${component.guidance.usageGuidance}`);
+      }
+      if (component.guidance.dos.length > 0) {
+        guidance.push(`dos: ${component.guidance.dos.join("; ")}`);
+      }
+      if (component.guidance.donts.length > 0) {
+        guidance.push(`donts: ${component.guidance.donts.join("; ")}`);
+      }
+      return [component.name, guidance];
+    })
+  );
+}
+function buildAmbiguityGuidanceLines(candidates, guidanceByName) {
+  return candidates.map((candidate) => {
+    const guidance = guidanceByName.get(candidate) ?? [];
+    return guidance.length > 0 ? `${candidate}: ${guidance.join(" | ")}` : `${candidate}: no additional guidance available`;
+  });
+}
+async function resolveAmbiguitiesWithElicitation(ambiguities, spec, ctx) {
+  if (!ctx.mcp?.server || ambiguities.length === 0) return [];
+  const replacements = [];
+  const guidanceByName = buildComponentGuidanceMap(ctx);
+  for (const ambiguity of ambiguities) {
+    const guidanceLines = buildAmbiguityGuidanceLines(
+      ambiguity.candidates,
+      guidanceByName
+    );
+    const result2 = await ctx.mcp.server.elicitInput({
+      mode: "form",
+      message: [
+        `Fragments found multiple safe replacements for ${ambiguity.from} on node ${ambiguity.nodeId}.`,
+        "Choose the best replacement, or skip this change.",
+        "Candidate guidance:",
+        ...guidanceLines
+      ].join("\n"),
+      requestedSchema: {
+        type: "object",
+        properties: {
+          replacement: {
+            type: "string",
+            title: "Replacement",
+            description: [
+              "Select the best replacement for this node.",
+              ...guidanceLines,
+              "Choose Skip to leave this component unchanged."
+            ].join("\n"),
+            oneOf: [
+              ...ambiguity.candidates.map((candidate) => ({
+                const: candidate,
+                title: candidate
+              })),
+              {
+                const: "__skip__",
+                title: "Skip"
+              }
+            ],
+            default: "__skip__"
+          }
+        },
+        required: ["replacement"]
+      }
+    });
+    if (result2.action !== "accept" || !result2.content || typeof result2.content.replacement !== "string" || result2.content.replacement === "__skip__") {
+      continue;
+    }
+    if (!ambiguity.candidates.includes(result2.content.replacement)) {
+      continue;
+    }
+    if (!applyReplacementAtRef(spec, ambiguity.nodeRef, result2.content.replacement)) {
+      continue;
+    }
+    replacements.push({
+      nodeId: ambiguity.nodeId,
+      from: ambiguity.from,
+      to: result2.content.replacement,
+      reason: "deprecated_component",
+      mode: "elicitation"
+    });
+  }
+  return replacements;
+}
+async function resolveAmbiguitiesWithSampling(ambiguities, spec, ctx) {
+  if (!ctx.mcp?.server || ambiguities.length === 0) return [];
+  const guidanceByName = buildComponentGuidanceMap(ctx);
+  const prompt = [
+    "You are choosing design-system component replacements.",
+    'Return strict JSON only in the form {"choices":[{"nodeId":"...","replacement":"...|__skip__"}]}.',
+    "Only choose from the provided candidates.",
+    "Prefer the option whose guidance best matches the original component intent.",
+    JSON.stringify(
+      {
+        ambiguities: ambiguities.map((ambiguity) => ({
+          nodeId: ambiguity.nodeId,
+          from: ambiguity.from,
+          candidates: ambiguity.candidates.map((candidate) => ({
+            name: candidate,
+            guidance: guidanceByName.get(candidate) ?? []
+          }))
+        }))
+      },
+      null,
+      2
+    )
+  ].join("\n\n");
+  const response = await ctx.mcp.server.createMessage({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: prompt
+        }
+      }
+    ],
+    maxTokens: 600
+  });
+  const text = getSamplingText(response);
+  if (!text) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [];
+  }
+  const replacements = [];
+  for (const choice of parsed.choices ?? []) {
+    if (!choice.nodeId || !choice.replacement || choice.replacement === "__skip__") {
+      continue;
+    }
+    const ambiguity = ambiguities.find((entry) => entry.nodeId === choice.nodeId);
+    if (!ambiguity || !ambiguity.candidates.includes(choice.replacement)) {
+      continue;
+    }
+    if (!applyReplacementAtRef(spec, ambiguity.nodeRef, choice.replacement)) {
+      continue;
+    }
+    replacements.push({
+      nodeId: ambiguity.nodeId,
+      from: ambiguity.from,
+      to: choice.replacement,
+      reason: "deprecated_component",
+      mode: "sampling"
+    });
+  }
+  return replacements;
+}
+function buildSummary(args) {
+  const lines = [
+    `status: ${args.status}`,
+    `original: ${formatVerdict(args.originalVerdict, "summary")}`
+  ];
+  if (args.replacements.length > 0) {
+    lines.push(
+      `replacements: ${args.replacements.map((item) => `${item.from} -> ${item.to}`).join(", ")}`
+    );
+    lines.push(`final: ${formatVerdict(args.finalVerdict, "summary")}`);
+  }
+  return lines.join("\n");
+}
+var validateAndFixHandler = async (args, ctx) => {
+  const spec = args?.spec;
+  if (!spec || typeof spec !== "object") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "spec is required and must be an object with { nodes: [{ id, type, props, children }] }"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  const specError = validateSpecShape(spec);
+  if (specError) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: `Invalid spec format: ${specError}. Expected: { nodes: [{ id?: string, type?: string, props?: object, children?: object[] }] }`
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  const policyOverrides = args?.policy;
+  const applyFixes = args?.applyFixes !== false;
+  const allowElicitation = args?.allowElicitation !== false;
+  const allowSampling = args?.allowSampling !== false;
+  const format = args?.format ?? "json";
+  const startedAt = Date.now();
+  try {
+    const effectiveComponents = buildEffectiveComponents(ctx);
+    const originalVerdict = await runGovern(spec, ctx, policyOverrides);
+    let finalVerdict = originalVerdict;
+    let workingSpec;
+    let fixedSpec;
+    let replacements = [];
+    let ambiguities = [];
+    const resolutionPath = [];
+    const supportsElicitation = supportsFormElicitation(ctx);
+    const supportsModelSampling = supportsSampling(ctx);
+    const preview = !originalVerdict.passed ? applyDeterministicReplacements(spec, ctx) : void 0;
+    if (!applyFixes && preview) {
+      ambiguities = preview.ambiguities;
+    }
+    if (!originalVerdict.passed && applyFixes) {
+      const result2 = preview ?? applyDeterministicReplacements(spec, ctx);
+      replacements = result2.replacements;
+      ambiguities = result2.ambiguities;
+      if (replacements.length > 0) {
+        workingSpec = result2.fixedSpec;
+        resolutionPath.push("deterministic");
+      }
+      const unresolvedAmbiguities2 = ambiguities.filter(
+        (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
+      );
+      if (unresolvedAmbiguities2.length > 0 && allowElicitation && supportsElicitation) {
+        workingSpec ??= cloneSpec(spec);
+        const elicitedReplacements = await resolveAmbiguitiesWithElicitation(
+          unresolvedAmbiguities2,
+          workingSpec,
+          ctx
+        );
+        if (elicitedReplacements.length > 0) {
+          resolutionPath.push("elicitation");
+        }
+        replacements.push(...elicitedReplacements);
+      }
+      const remainingAmbiguities = ambiguities.filter(
+        (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
+      );
+      if (remainingAmbiguities.length > 0 && allowSampling && supportsModelSampling) {
+        workingSpec ??= cloneSpec(spec);
+        const sampledReplacements = await resolveAmbiguitiesWithSampling(
+          remainingAmbiguities,
+          workingSpec,
+          ctx
+        );
+        if (sampledReplacements.length > 0) {
+          resolutionPath.push("sampling");
+        }
+        replacements.push(...sampledReplacements);
+      }
+      fixedSpec = replacements.length > 0 ? workingSpec : void 0;
+      if (fixedSpec) {
+        finalVerdict = await runGovern(fixedSpec, ctx, policyOverrides);
+      }
+    }
+    const status = originalVerdict.passed ? "pass" : replacements.length > 0 ? finalVerdict.passed ? "fixed" : "partial_fix" : "fail";
+    const unresolvedAmbiguities = ambiguities.filter(
+      (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
+    ).map(({ nodeRef: _nodeRef, ...ambiguity }) => ambiguity);
+    const unresolvedAmbiguitiesWithRefs = ambiguities.filter(
+      (ambiguity) => !replacements.some((replacement) => replacement.nodeId === ambiguity.nodeId)
+    );
+    const wouldFixIfAuthorized = buildWouldFixIfAuthorized({
+      deterministicPreview: preview?.replacements ?? [],
+      unresolvedAmbiguities: unresolvedAmbiguitiesWithRefs,
+      applyFixes,
+      allowElicitation,
+      allowSampling,
+      supportsElicitation,
+      supportsSampling: supportsModelSampling
+    });
+    const attestation = {
+      sourceType: ctx.data.snapshot.sourceType,
+      sourceLabel: ctx.data.snapshot.sourceLabel,
+      designSystemName: ctx.data.snapshot.metadata.designSystemName,
+      packageName: ctx.data.snapshot.metadata.packageName,
+      importPath: ctx.data.snapshot.metadata.importPath,
+      catalogRevision: ctx.data.validateFixContext?.catalogRevision ?? ctx.data.snapshot.metadata.revision,
+      catalogUpdatedAt: ctx.data.validateFixContext?.updatedAt ?? ctx.data.snapshot.metadata.updatedAt,
+      policy: {
+        mode: ctx.data.validateFixContext?.policy.mode ?? "embedded",
+        endpoint: ctx.data.validateFixContext?.policy.endpoint,
+        overrideApplied: Boolean(policyOverrides)
+      },
+      clientCapabilities: {
+        sampling: supportsModelSampling,
+        samplingTools: Boolean(ctx.mcp?.clientCapabilities?.sampling?.tools),
+        elicitationForm: supportsElicitation,
+        roots: Boolean(ctx.mcp?.clientCapabilities?.roots)
+      },
+      capabilitiesUsed: {
+        deterministic: replacements.some((replacement) => replacement.mode === "deterministic"),
+        elicitation: replacements.some((replacement) => replacement.mode === "elicitation"),
+        sampling: replacements.some((replacement) => replacement.mode === "sampling")
+      }
+    };
+    const evaluation = {
+      durationMs: Date.now() - startedAt,
+      originalViolationCount: countViolations(originalVerdict),
+      finalViolationCount: countViolations(finalVerdict),
+      originalPassed: originalVerdict.passed,
+      finalPassed: finalVerdict.passed,
+      replacementCount: replacements.length,
+      replacementsByMode: {
+        deterministic: replacements.filter((replacement) => replacement.mode === "deterministic").length,
+        elicitation: replacements.filter((replacement) => replacement.mode === "elicitation").length,
+        sampling: replacements.filter((replacement) => replacement.mode === "sampling").length
+      },
+      ambiguityCount: ambiguities.length,
+      unresolvedAmbiguityCount: unresolvedAmbiguities.length,
+      candidateRankingUsed: true
+    };
+    const nextAction = getNextAction(
+      status,
+      replacements,
+      unresolvedAmbiguities.length
+    );
+    const catalogMeta = getCatalogMeta(ctx.data);
+    const payload = {
+      status,
+      nextAction,
+      applyFixes,
+      allowElicitation,
+      allowSampling,
+      resolutionPath,
+      replacements,
+      originalVerdict,
+      finalVerdict,
+      ...fixedSpec ? { fixedSpec } : {},
+      attestation,
+      evaluation,
+      preferredComponents: getSelectionNames(
+        effectiveComponents,
+        "preferred"
+      ),
+      discouragedComponents: getSelectionNames(
+        effectiveComponents,
+        "discouraged"
+      ),
+      forbiddenComponents: getSelectionNames(
+        effectiveComponents,
+        "forbidden"
+      ),
+      unresolvedAmbiguities,
+      wouldFixIfAuthorized
+    };
+    await emitValidateAndFixTelemetry({
+      ctx,
+      status,
+      resolutionPath,
+      evaluation,
+      attestation,
+      nextAction
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: format === "summary" ? buildSummary({
+            status,
+            originalVerdict,
+            finalVerdict,
+            replacements
+          }) : JSON.stringify(payload)
+        }
+      ],
+      _meta: {
+        ...catalogMeta,
+        status,
+        nextAction,
+        replacementCount: replacements.length,
+        passed: finalVerdict.passed,
+        unresolvedAmbiguityCount: unresolvedAmbiguities.length,
+        wouldFixIfAuthorizedCount: wouldFixIfAuthorized.length,
+        resolutionPath
+      }
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: message
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+
+// src/cloud-http.ts
+var DEFAULT_CLOUD_URL = "https://app.usefragments.com";
+function normalizeCloudUrl(url) {
+  if (!url) return DEFAULT_CLOUD_URL;
+  return url.replace(/\/+$/, "");
+}
+async function cloudFetchJson(args) {
+  const base = normalizeCloudUrl(args.cloudUrl);
+  const url = new URL(`${base}${args.path}`);
+  if (args.query) {
+    for (const [key, value] of Object.entries(args.query)) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+  }
+  const response = await fetch(url.toString(), {
+    headers: { "X-API-Key": args.apiKey }
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    let message;
+    try {
+      const parsed = JSON.parse(body);
+      message = parsed.error ?? body;
+    } catch {
+      message = body;
+    }
+    throw new Error(
+      `Cloud ${args.resource} API error (${response.status}): ${message}`
+    );
+  }
+  return await response.json();
+}
+
+// src/findings-service.ts
+async function fetchFindings(apiKey, params, cloudUrl) {
+  return cloudFetchJson({
+    apiKey,
+    cloudUrl,
+    path: "/api/findings",
+    resource: "findings",
+    query: {
+      status: params.status,
+      severity: params.severity,
+      category: params.category,
+      ruleId: params.ruleId,
+      filePath: params.filePath,
+      limit: params.limit
+    }
+  });
+}
+async function fetchFindingsForFile(apiKey, filePath, cloudUrl) {
+  return fetchFindings(
+    apiKey,
+    { status: "open", filePath, limit: 200 },
+    cloudUrl
+  );
+}
+function buildFindingSourceUrl(finding) {
+  const { repoFullName, commitSha, filePath, line } = finding;
+  if (!repoFullName || !commitSha || !filePath) return void 0;
+  if (!/^[-\w.]+\/[-\w.]+$/.test(repoFullName)) return void 0;
+  if (!/^[a-fA-F0-9]{7,64}$/.test(commitSha)) return void 0;
+  const normalizedPath = filePath.replace(/^\/+/, "");
+  if (!normalizedPath) return void 0;
+  const encodedPath = normalizedPath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  const lineSuffix = line != null && line > 0 ? `#L${Math.floor(line)}` : "";
+  return `https://github.com/${repoFullName}/blob/${commitSha}/${encodedPath}${lineSuffix}`;
+}
+async function fetchFindingsSummary(apiKey, params, cloudUrl) {
+  const { findings } = await fetchFindings(
+    apiKey,
+    { ...params, limit: params.limit ?? 200 },
+    cloudUrl
+  );
+  return summarizeFindings(findings, params);
+}
+function summarizeFindings(findings, params) {
+  const bySeverity = { error: 0, warning: 0, info: 0 };
+  const byStatus = { open: 0, resolved: 0, ignored: 0 };
+  const byCategory = {};
+  const byRuleId = {};
+  const byFilePath = {};
+  for (const finding of findings) {
+    bySeverity[finding.severity] += 1;
+    byStatus[finding.status] += 1;
+    increment(byRuleId, finding.ruleId);
+    if (finding.category) increment(byCategory, finding.category);
+    if (finding.filePath) increment(byFilePath, finding.filePath);
+  }
+  const { limit: _limit, ...filters } = params;
+  return {
+    total: findings.length,
+    filters,
+    bySeverity,
+    byStatus,
+    byCategory,
+    byRuleId,
+    byFilePath,
+    topFiles: topEntries(byFilePath, "filePath"),
+    topRules: topEntries(byRuleId, "ruleId")
+  };
+}
+function increment(counts, key) {
+  counts[key] = (counts[key] ?? 0) + 1;
+}
+function topEntries(counts, keyName) {
+  return Object.entries(counts).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 10).map(([key, count]) => ({ [keyName]: key, count }));
+}
+
+// src/tools/cloud-auth.ts
+function resolveCloudApiKey(ctx) {
+  return ctx.config.cloudApiKey ?? ctx.config.fileConfig?.cloud?.apiKey ?? process.env.FRAGMENTS_API_KEY;
+}
+function resolveCloudUrl(ctx) {
+  return ctx.config.fileConfig?.cloud?.url ?? process.env.FRAGMENTS_CLOUD_URL;
+}
+function missingKeyError() {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          error: "Cloud API key required. Set FRAGMENTS_API_KEY env var, pass --cloud-api-key, or configure cloud.apiKey in ds-mcp.config.json."
+        })
+      }
+    ],
+    isError: true
+  };
+}
+
+// src/tools/findings.ts
+function enrichFindings(findings, ctx) {
+  return findings.map((finding) => {
+    const sourceUrl = finding.sourceUrl ?? buildFindingSourceUrl(finding);
+    const withSourceUrl = sourceUrl ? { ...finding, sourceUrl } : finding;
+    if (!finding.prop || !finding.rawValue || !ctx.data.tokens) {
+      return withSourceUrl;
+    }
+    const catalogMeta = getCatalogMeta(ctx.data);
+    const suggestion = suggestToken({
+      tokens: ctx.data.tokens,
+      property: finding.prop,
+      value: finding.rawValue,
+      catalogRevision: catalogMeta.catalogRevision,
+      updatedAt: catalogMeta.updatedAt
+    });
+    if (!suggestion.recommended) {
+      const {
+        suggestedToken: _discarded,
+        suggestedTokenDetails: _details,
+        ...rest
+      } = withSourceUrl;
+      return rest;
+    }
+    return {
+      ...withSourceUrl,
+      suggestedToken: suggestion.recommended.cssVar ?? suggestion.recommended.name,
+      suggestedTokenDetails: suggestion.recommended
+    };
+  });
+}
+var findingsListHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const cloudUrl = resolveCloudUrl(ctx);
+  const params = {};
+  if (args.status) params.status = args.status;
+  if (args.severity)
+    params.severity = args.severity;
+  if (args.category) params.category = String(args.category);
+  if (args.ruleId) params.ruleId = String(args.ruleId);
+  if (args.filePath) params.filePath = String(args.filePath);
+  if (args.limit != null) params.limit = Number(args.limit);
+  try {
+    const result2 = await fetchFindings(apiKey, params, cloudUrl);
+    const findings = enrichFindings(result2.findings, ctx);
+    const catalogMeta = getCatalogMeta(ctx.data);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ ...result2, findings })
+        }
+      ],
+      _meta: {
+        ...catalogMeta,
+        count: findings.length,
+        tokenSuggestionCount: findings.filter(
+          (finding) => finding.suggestedTokenDetails
+        ).length
+      }
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+var findingsSummaryHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const cloudUrl = resolveCloudUrl(ctx);
+  const params = {};
+  if (args.status) params.status = args.status;
+  if (args.severity)
+    params.severity = args.severity;
+  if (args.category) params.category = String(args.category);
+  if (args.ruleId) params.ruleId = String(args.ruleId);
+  if (args.filePath) params.filePath = String(args.filePath);
+  if (args.limit != null) params.limit = Number(args.limit);
+  try {
+    const summary = await fetchFindingsSummary(apiKey, params, cloudUrl);
+    const catalogMeta = getCatalogMeta(ctx.data);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(summary)
+        }
+      ],
+      _meta: {
+        ...catalogMeta,
+        total: summary.total,
+        topFileCount: summary.topFiles.length,
+        topRuleCount: summary.topRules.length
+      }
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+var findingsForFileHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const filePath = args.filePath;
+  if (!filePath || typeof filePath !== "string") {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: "filePath is required." })
+        }
+      ],
+      isError: true
+    };
+  }
+  const cloudUrl = resolveCloudUrl(ctx);
+  try {
+    const result2 = await fetchFindingsForFile(apiKey, filePath, cloudUrl);
+    const findings = enrichFindings(
+      result2.findings.filter((f) => f.filePath === filePath),
+      ctx
+    );
+    const catalogMeta = getCatalogMeta(ctx.data);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ findings, filePath })
+        }
+      ],
+      _meta: {
+        ...catalogMeta,
+        count: findings.length,
+        filePath,
+        tokenSuggestionCount: findings.filter(
+          (finding) => finding.suggestedTokenDetails
+        ).length
+      }
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: error instanceof Error ? error.message : String(error)
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+
+// src/tools/swap-to-canonical.ts
+import * as ts from "typescript";
+import {
+  resolveCanonicalForHtmlElement,
+  formatRawHtmlElement
+} from "@fragments-sdk/classifier";
+
+// src/canonical-mappings-service.ts
+async function fetchCanonicalMappings(apiKey, cloudUrl) {
+  const catalog = await cloudFetchJson({
+    apiKey,
+    cloudUrl,
+    path: "/api/catalog",
+    resource: "catalog"
+  });
+  return catalog.canonicalMappings ?? [];
+}
+
+// src/tools/swap-to-canonical.ts
+function errorResult(message) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ error: message })
+      }
+    ],
+    isError: true
+  };
+}
+var resolveCanonicalForElement = resolveCanonicalForHtmlElement;
+function walkRawJsxElements(source) {
+  const results = [];
+  const visit = (node) => {
+    let opening;
+    if (ts.isJsxSelfClosingElement(node)) {
+      opening = node;
+    } else if (ts.isJsxElement(node)) {
+      opening = node.openingElement;
+    }
+    if (opening) {
+      const tagNameNode = opening.tagName;
+      if (ts.isIdentifier(tagNameNode)) {
+        const tagName = tagNameNode.text;
+        if (/^[a-z]/.test(tagName)) {
+          const attrs = /* @__PURE__ */ new Map();
+          for (const attr of opening.attributes.properties) {
+            if (!ts.isJsxAttribute(attr)) continue;
+            if (!attr.name || !ts.isIdentifier(attr.name)) continue;
+            const name = attr.name.text;
+            if (!attr.initializer) {
+              attrs.set(name, { value: "", dynamic: false });
+              continue;
+            }
+            if (ts.isStringLiteral(attr.initializer)) {
+              attrs.set(name, {
+                value: attr.initializer.text,
+                dynamic: false
+              });
+            } else if (ts.isJsxExpression(attr.initializer)) {
+              attrs.set(name, { value: "", dynamic: true });
+            }
+          }
+          const start = opening.getStart(source);
+          const { line } = source.getLineAndCharacterOfPosition(start);
+          results.push({ tagName, attrs, line: line + 1 });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return results;
+}
+var formatRawElement = formatRawHtmlElement;
+function buildPropMapping(attrs, rowMapping) {
+  const transforms = new Map(
+    rowMapping.map((m) => [m.rawProp, m])
+  );
+  const mapping = [];
+  for (const rawProp of attrs.keys()) {
+    if (rawProp === "type") continue;
+    mapping.push(
+      transforms.get(rawProp) ?? { rawProp, canonicalProp: rawProp }
+    );
+  }
+  return mapping;
+}
+function groupMappingsByCanonical(mappings) {
+  const out = /* @__PURE__ */ new Map();
+  for (const m of mappings) {
+    if (!m.importPath) continue;
+    const list = out.get(m.canonical) ?? [];
+    list.push(m);
+    out.set(m.canonical, list);
+  }
+  for (const list of out.values()) {
+    list.sort((a, b) => {
+      const ac = a.confidence ?? 0;
+      const bc = b.confidence ?? 0;
+      if (ac !== bc) return bc - ac;
+      return a.name.localeCompare(b.name);
+    });
+  }
+  return out;
+}
+function buildSwapSuggestions(args) {
+  const eligible = args.mappings.filter(
+    (m) => m.canonicalConfidence === "auto" || m.canonicalConfidence === "overridden"
+  );
+  if (eligible.length === 0) return [];
+  const byCanonical = groupMappingsByCanonical(eligible);
+  if (byCanonical.size === 0) return [];
+  const source = ts.createSourceFile(
+    args.filePath,
+    args.fileContent,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */
+    true,
+    ts.ScriptKind.TSX
+  );
+  const elements = walkRawJsxElements(source);
+  const suggestions = [];
+  for (const el of elements) {
+    const canonical = resolveCanonicalForElement(el.tagName, el.attrs);
+    if (!canonical) continue;
+    const candidates = byCanonical.get(canonical);
+    if (!candidates || candidates.length === 0) continue;
+    const primary = candidates[0];
+    const importPath = primary.importPath;
+    if (!importPath) continue;
+    const suggestion = {
+      rawElement: formatRawElement(el.tagName, el.attrs),
+      canonical,
+      componentName: primary.name,
+      importPath,
+      propMapping: buildPropMapping(el.attrs, primary.propMapping),
+      line: el.line
+    };
+    if (candidates.length > 1) {
+      suggestion.alternates = candidates.slice(1).filter((c) => c.importPath).map((c) => ({
+        name: c.name,
+        importPath: c.importPath,
+        confidence: c.confidence ?? 0
+      }));
+    }
+    suggestions.push(suggestion);
+  }
+  return suggestions;
+}
+var swapToCanonicalHandler = async (args, ctx) => {
+  const apiKey = resolveCloudApiKey(ctx);
+  if (!apiKey) return missingKeyError();
+  const filePath = typeof args.filePath === "string" ? args.filePath : "";
+  const fileContent = typeof args.fileContent === "string" ? args.fileContent : "";
+  if (!filePath || !fileContent) {
+    return errorResult("filePath and fileContent are required.");
+  }
+  const cloudUrl = resolveCloudUrl(ctx);
+  let mappings;
+  try {
+    mappings = await fetchCanonicalMappings(apiKey, cloudUrl);
+  } catch (error) {
+    return errorResult(error instanceof Error ? error.message : String(error));
+  }
+  const suggestions = buildSwapSuggestions({
+    filePath,
+    fileContent,
+    mappings
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ suggestions, filePath })
+      }
+    ],
+    _meta: {
+      count: suggestions.length,
+      mappingCount: mappings.length,
+      filePath
+    }
+  };
+};
+
+// src/tools/index.ts
+var CORE_TOOLS = {
+  "tokens.suggest": tokensSuggestHandler,
+  govern: governHandler,
+  validate_and_fix: validateAndFixHandler,
+  findings_list: findingsListHandler,
+  findings_summary: findingsSummaryHandler,
+  findings_for_file: findingsForFileHandler,
+  swap_to_canonical: swapToCanonicalHandler
+};
+var VIEWER_TOOLS = {};
+var INFRA_TOOLS = {};
+var BUILTIN_TOOLS = {
+  ...CORE_TOOLS,
+  ...VIEWER_TOOLS,
+  ...INFRA_TOOLS
+};
+var TOOL_CAPABILITIES = {
+  "tokens.suggest": ["tokens"],
+  validate_and_fix: ["components"]
+};
+
+// src/registry.ts
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  prefix;
+  onChanged;
+  constructor(prefix, opts) {
+    this.prefix = prefix;
+    this.onChanged = opts?.onChanged;
+  }
+  /** Register a single tool */
+  register(key, handler, definition, availability = "always", requiredCapabilities = []) {
+    this.tools.set(key, {
+      key,
+      handler,
+      definition,
+      availability,
+      requiredCapabilities
+    });
+    this.onChanged?.();
+  }
+  /** Unregister a tool by key */
+  unregister(key) {
+    if (this.tools.delete(key)) {
+      this.onChanged?.();
+    }
+  }
+  /** Bulk register built-in tools with availability metadata */
+  registerBuiltins(toolSets, definitions, capabilityByKey = {}) {
+    const defMap = new Map(definitions.map((d) => [d.key, d]));
+    for (const [key, handler] of Object.entries(toolSets.core)) {
+      this.tools.set(key, {
+        key,
+        handler,
+        definition: defMap.get(key),
+        availability: "always",
+        requiredCapabilities: capabilityByKey[key] ?? []
+      });
+    }
+    for (const [key, handler] of Object.entries(toolSets.viewer)) {
+      this.tools.set(key, {
+        key,
+        handler,
+        definition: defMap.get(key),
+        availability: "viewer",
+        requiredCapabilities: capabilityByKey[key] ?? []
+      });
+    }
+    for (const [key, handler] of Object.entries(toolSets.infra)) {
+      this.tools.set(key, {
+        key,
+        handler,
+        definition: defMap.get(key),
+        availability: "playground",
+        requiredCapabilities: capabilityByKey[key] ?? []
+      });
+    }
+  }
+  /** Get handler for a tool (by unprefixed key or prefixed name) */
+  getHandler(nameOrKey) {
+    const direct = this.tools.get(nameOrKey);
+    if (direct) return direct.handler;
+    if (!this.prefix) return void 0;
+    const prefixStr = this.prefix + "_";
+    if (nameOrKey.startsWith(prefixStr)) {
+      const key = nameOrKey.slice(prefixStr.length);
+      return this.tools.get(key)?.handler;
+    }
+    return void 0;
+  }
+  /** Resolve unprefixed key from a potentially prefixed tool name */
+  resolveKey(name) {
+    if (!this.prefix) return name;
+    const prefixStr = this.prefix + "_";
+    return name.startsWith(prefixStr) ? name.slice(prefixStr.length) : name;
+  }
+  /** List available tools as MCP Tool[] based on current availability context */
+  listTools(ctx, allToolSchemas) {
+    const availableKeys = /* @__PURE__ */ new Set();
+    for (const [key, tool] of this.tools) {
+      const hasCapabilities = tool.requiredCapabilities.every(
+        (capability) => ctx.capabilities.has(capability)
+      );
+      if (!hasCapabilities) continue;
+      if (tool.availability === "always") {
+        availableKeys.add(key);
+      } else if (tool.availability === "viewer" && ctx.hasViewer) {
+        availableKeys.add(key);
+      } else if (tool.availability === "playground" && ctx.hasPlayground) {
+        availableKeys.add(key);
+      }
+    }
+    if (!this.prefix) {
+      return allToolSchemas.filter((t) => availableKeys.has(t.name));
+    }
+    const prefixStr = this.prefix + "_";
+    return allToolSchemas.filter((t) => {
+      const key = t.name.startsWith(prefixStr) ? t.name.slice(prefixStr.length) : t.name;
+      return availableKeys.has(key);
+    });
+  }
+  /** Execute a tool by name, dispatching to its handler */
+  async execute(name, args, ctx) {
+    const key = this.resolveKey(name);
+    const registered = this.tools.get(key);
+    if (!registered) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+    return registered.handler(args, ctx);
+  }
+  /** Get the number of registered tools */
+  get size() {
+    return this.tools.size;
+  }
+  /** Get all registered keys */
+  keys() {
+    return Array.from(this.tools.keys());
+  }
+};
+
+// src/middleware.ts
+function executeWithMiddleware(middlewares, mCtx, handler) {
+  const chain = [...middlewares].reverse().reduce(
+    (next, mw) => () => mw(mCtx, next),
+    handler
+  );
+  return chain();
+}
+function telemetryMiddleware(logger) {
+  return async (mCtx, next) => {
+    const start = Date.now();
+    const result2 = await next();
+    logger(`${mCtx.toolKey}: ${Date.now() - start}ms`);
+    return result2;
+  };
+}
+
+// src/source-selection.ts
+import { existsSync as existsSync7 } from "fs";
+import { join as join6 } from "path";
+
+// src/adapters/fragments-json.ts
+import { readFile } from "fs/promises";
+
+// src/discovery.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync } from "fs";
+import { join as join2, dirname, resolve } from "path";
+import { createRequire } from "module";
+function resolveWorkspaceGlob(baseDir, pattern) {
+  const parts = pattern.split("/");
+  let dirs = [baseDir];
+  for (const part of parts) {
+    if (part === "**") continue;
+    const next = [];
+    for (const d of dirs) {
+      if (part === "*") {
+        try {
+          for (const entry of readdirSync(d, { withFileTypes: true })) {
+            if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+              next.push(join2(d, entry.name));
+            }
+          }
+        } catch {
+        }
+      } else {
+        const candidate = join2(d, part);
+        if (existsSync2(candidate)) next.push(candidate);
+      }
+    }
+    dirs = next;
+  }
+  return dirs;
+}
+function getWorkspaceDirs(rootDir) {
+  const dirs = [];
+  const rootPkgPath = join2(rootDir, "package.json");
+  if (existsSync2(rootPkgPath)) {
+    try {
+      const rootPkg = JSON.parse(readFileSync3(rootPkgPath, "utf-8"));
+      const workspaces = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : rootPkg.workspaces?.packages;
+      if (Array.isArray(workspaces)) {
+        for (const pattern of workspaces) {
+          dirs.push(...resolveWorkspaceGlob(rootDir, pattern));
+        }
+        return dirs;
+      }
+    } catch {
+    }
+  }
+  const pnpmWsPath = join2(rootDir, "pnpm-workspace.yaml");
+  if (existsSync2(pnpmWsPath)) {
+    try {
+      const content = readFileSync3(pnpmWsPath, "utf-8");
+      const lines = content.split("\n");
+      let inPackages = false;
+      for (const line of lines) {
+        if (/^packages\s*:/.test(line)) {
+          inPackages = true;
+          continue;
+        }
+        if (inPackages) {
+          const match = line.match(/^\s+-\s+['"]?([^'"#\n]+)['"]?/);
+          if (match) {
+            dirs.push(...resolveWorkspaceGlob(rootDir, match[1].trim()));
+          } else if (/^\S/.test(line) && line.trim()) {
+            break;
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return dirs;
+}
+function resolveDepPackageJson(localRequire, depName) {
+  try {
+    return localRequire.resolve(`${depName}/package.json`);
+  } catch {
+  }
+  try {
+    const mainPath = localRequire.resolve(depName);
+    let dir = dirname(mainPath);
+    while (true) {
+      const candidate = join2(dir, "package.json");
+      if (existsSync2(candidate)) {
+        const pkg = JSON.parse(readFileSync3(candidate, "utf-8"));
+        if (pkg.name === depName) return candidate;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+  }
+  return null;
+}
+function findFragmentsInDeps(dir, found, depField) {
+  const pkgJsonPath = join2(dir, "package.json");
+  if (!existsSync2(pkgJsonPath)) return;
+  try {
+    const pkgJson = JSON.parse(readFileSync3(pkgJsonPath, "utf-8"));
+    const allDeps = {
+      ...pkgJson.dependencies,
+      ...pkgJson.devDependencies
+    };
+    const localRequire = createRequire(join2(dir, "noop.js"));
+    for (const depName of Object.keys(allDeps)) {
+      try {
+        const depPkgPath = resolveDepPackageJson(localRequire, depName);
+        if (!depPkgPath) continue;
+        const depPkg = JSON.parse(readFileSync3(depPkgPath, "utf-8"));
+        if (depPkg[depField]) {
+          const fragmentsPath = join2(dirname(depPkgPath), depPkg[depField]);
+          if (existsSync2(fragmentsPath) && !found.includes(fragmentsPath)) {
+            found.push(fragmentsPath);
+          }
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+function findDesignSystemJson(startDir, outFile, depField) {
+  const found = [];
+  const resolvedStart = resolve(startDir);
+  let dir = resolvedStart;
+  while (true) {
+    const candidate = join2(dir, outFile);
+    if (existsSync2(candidate)) {
+      found.push(candidate);
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  findFragmentsInDeps(resolvedStart, found, depField);
+  if (found.length === 0 || existsSync2(join2(resolvedStart, "pnpm-workspace.yaml"))) {
+    const workspaceDirs = getWorkspaceDirs(resolvedStart);
+    for (const wsDir of workspaceDirs) {
+      findFragmentsInDeps(wsDir, found, depField);
+    }
+  }
+  return found;
+}
+function findFragmentsJson(startDir) {
+  return findDesignSystemJson(startDir, BRAND.outFile, "fragments");
+}
+function findBundleManifest(startDir) {
+  const found = [];
+  let dir = resolve(startDir);
+  while (true) {
+    const candidate = join2(dir, BRAND.dataDir, BRAND.manifestFile);
+    if (existsSync2(candidate)) {
+      found.push(candidate);
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return found;
+}
+
+// src/adapters/snapshot-converters.ts
+import { mcpSnapshotSchema } from "@fragments-sdk/core";
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+}
+function buildComponentId(args) {
+  const base = args.filePath ?? args.packageName ?? args.name;
+  return `${slugify(args.name)}:${base}`;
+}
+function valueToString(value) {
+  if (value === void 0) return void 0;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || value === null) {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return void 0;
+  }
+}
+function buildCompoundChildren(contract, ai) {
+  const contractChildren = Object.entries(contract?.compoundChildren ?? {});
+  if (contractChildren.length > 0) {
+    return contractChildren.map(([childName, child]) => ({
+      name: childName,
+      description: child.description,
+      required: child.required,
+      accepts: child.accepts,
+      visibility: "public"
+    }));
+  }
+  const subs = ai?.subComponents;
+  if (!subs || subs.length === 0) return [];
+  const requiredSet = new Set(ai?.requiredChildren ?? []);
+  return subs.map((name) => ({
+    name,
+    required: requiredSet.has(name) || void 0,
+    visibility: "public"
+  }));
+}
+function componentFromCompiledFragment(args) {
+  const { fragment, sourceType } = args;
+  const name = fragment.meta.name;
+  const description = fragment.meta.description ?? "";
+  const usage = fragment.usage ?? { when: [], whenNot: [] };
+  const contract = fragment.contract;
+  const ai = fragment.ai;
+  const guidancePatterns = (fragment._cloudPatterns ?? []).map((pattern) => ({
+    name: pattern.name ?? "Pattern",
+    description: pattern.description
+  }));
+  return {
+    id: args.id ?? buildComponentId({
+      name,
+      filePath: fragment.sourcePath ?? fragment.filePath,
+      packageName: args.packageName
+    }),
+    name,
+    description,
+    category: fragment.meta.category ?? "uncategorized",
+    status: fragment.meta.status ?? "stable",
+    tags: fragment.meta.tags ?? [],
+    props: Object.fromEntries(
+      Object.entries(fragment.props ?? {}).map(([propName, prop]) => [
+        propName,
+        {
+          type: prop.type,
+          description: prop.description ?? "",
+          required: prop.required ?? false,
+          default: prop.default,
+          values: prop.values ? [...prop.values] : void 0,
+          constraints: prop.constraints ? [...prop.constraints] : void 0
+        }
+      ])
+    ),
+    propsSummary: fragment.propsSummary ?? contract?.propsSummary ?? Object.entries(fragment.props ?? {}).map(
+      ([propName, prop]) => `${propName}${prop.required ? " (required)" : ""}: ${prop.type}`
+    ),
+    examples: (fragment.variants ?? []).map((variant) => ({
+      name: variant.name,
+      description: variant.description,
+      code: variant.code,
+      kind: "example"
+    })),
+    relations: (fragment.relations ?? []).map((relation) => ({
+      componentName: relation.component,
+      relationship: relation.relationship,
+      note: relation.note
+    })),
+    compoundChildren: buildCompoundChildren(contract, ai),
+    guidance: {
+      when: usage.when ?? [],
+      whenNot: usage.whenNot ?? [],
+      guidelines: usage.guidelines ?? [],
+      accessibility: usage.accessibility ?? [],
+      dos: usage.when ?? [],
+      donts: usage.whenNot ?? [],
+      patterns: guidancePatterns.length > 0 ? guidancePatterns : (ai?.commonPatterns ?? []).map((pattern) => ({
+        name: pattern
+      }))
+    },
+    sourceType,
+    sourcePath: fragment.sourcePath ?? fragment.filePath,
+    packageName: args.packageName,
+    importPath: args.importPath ?? args.packageName,
+    performance: fragment.performance ? {
+      bundleSize: fragment.performance.bundleSize,
+      rawSize: fragment.performance.rawSize,
+      complexity: fragment.performance.complexity,
+      budgetPercent: fragment.performance.budgetPercent,
+      overBudget: fragment.performance.overBudget,
+      measuredAt: fragment.performance.measuredAt,
+      imports: fragment.performance.imports?.map((entry) => ({
+        path: entry.path,
+        bytes: entry.bytes,
+        percent: entry.percent
+      }))
+    } : void 0,
+    metadata: {
+      a11yRules: contract?.a11yRules ?? [],
+      scenarioTags: contract?.scenarioTags ?? []
+    }
+  };
+}
+function blockFromCompiledBlock(key, block) {
+  return {
+    id: key,
+    name: block.name,
+    description: block.description ?? "",
+    category: block.category ?? "uncategorized",
+    components: block.components ?? [],
+    tags: block.tags ?? [],
+    code: block.code ?? ""
+  };
+}
+function tokensFromCompiledTokenData(tokens) {
+  const flat = [];
+  const categories = {};
+  for (const [category, entries] of Object.entries(tokens.categories)) {
+    const normalized = entries.map((entry) => ({
+      name: entry.name,
+      category,
+      value: valueToString(entry.value),
+      description: entry.description
+    })).filter((token) => !isGarbageToken(token));
+    if (normalized.length > 0) {
+      categories[category] = normalized;
+      flat.push(...normalized);
+    }
+  }
+  return {
+    prefix: tokens.prefix,
+    total: flat.length,
+    categories,
+    flat
+  };
+}
+function buildCapabilities(args) {
+  const capabilities = /* @__PURE__ */ new Set();
+  if (Object.keys(args.components).length > 0) {
+    capabilities.add("components");
+  }
+  if (args.tokens && args.tokens.total > 0) {
+    capabilities.add("tokens");
+  }
+  if (args.blocks && Object.keys(args.blocks).length > 0) {
+    capabilities.add("blocks");
+  }
+  if (args.graph) {
+    capabilities.add("graph");
+  }
+  const hasPerformance = Boolean(args.performanceSummary) || Object.values(args.components).some((component) => Boolean(component.performance));
+  if (hasPerformance) {
+    capabilities.add("performance");
+  }
+  return Array.from(capabilities);
+}
+function validateSnapshot(snapshot) {
+  return mcpSnapshotSchema.parse(snapshot);
+}
+
+// src/adapters/fragments-json.ts
+var FragmentsJsonAdapter = class {
+  name = "fragments-json";
+  discover(startDir) {
+    return findFragmentsJson(startDir);
+  }
+  async load(projectRoot) {
+    const paths = this.discover(projectRoot);
+    if (paths.length === 0) {
+      throw new Error(
+        `No ${BRAND.outFile} found. Searched ${projectRoot} and package.json dependencies.
+
+Fix: Add a project-level MCP config so the server runs from your workspace root:
+
+  Cursor:    .cursor/mcp.json
+  VS Code:   .vscode/mcp.json
+  Claude:    claude mcp add ${BRAND.nameLower} -- npx @fragments-sdk/mcp
+  Windsurf:  .windsurf/mcp.json
+
+Or pass --project-root: npx @fragments-sdk/mcp -p /path/to/project
+
+If you're a library author, run \`${BRAND.cliCommand} build\` first.`
+      );
+    }
+    const content = await readFile(paths[0], "utf-8");
+    const primary = JSON.parse(content);
+    if (!primary.blocks && primary.recipes) {
+      primary.blocks = primary.recipes;
+    }
+    const packageMap = {};
+    if (primary.packageName) {
+      for (const name of Object.keys(primary.fragments)) {
+        packageMap[name] = primary.packageName;
+      }
+    }
+    for (let i = 1; i < paths.length; i++) {
+      const extra = JSON.parse(await readFile(paths[i], "utf-8"));
+      if (extra.packageName) {
+        for (const name of Object.keys(extra.fragments)) {
+          packageMap[name] = extra.packageName;
+        }
+      }
+      Object.assign(primary.fragments, extra.fragments);
+      const extraBlocks = extra.blocks ?? extra.recipes;
+      if (extraBlocks) {
+        primary.blocks = { ...primary.blocks, ...extraBlocks };
+      }
+    }
+    const components = Object.fromEntries(
+      Object.entries(primary.fragments).map(([key, fragment]) => [
+        key,
+        componentFromCompiledFragment({
+          id: key,
+          fragment,
+          sourceType: "fragments-json",
+          packageName: packageMap[fragment.meta.name] ?? primary.packageName,
+          importPath: packageMap[fragment.meta.name] ?? primary.packageName
+        })
+      ])
+    );
+    const blocks = primary.blocks ? Object.fromEntries(
+      Object.entries(primary.blocks).map(([key, block]) => [
+        key,
+        blockFromCompiledBlock(key, block)
+      ])
+    ) : void 0;
+    const tokens = primary.tokens ? tokensFromCompiledTokenData(primary.tokens) : void 0;
+    const snapshot = validateSnapshot({
+      schemaVersion: 1,
+      sourceType: "fragments-json",
+      sourceLabel: BRAND.outFile,
+      capabilities: buildCapabilities({
+        components,
+        blocks,
+        tokens,
+        graph: primary.graph,
+        performanceSummary: primary.performanceSummary
+      }),
+      metadata: {
+        designSystemName: primary.packageName,
+        packageName: primary.packageName,
+        importPath: primary.packageName
+      },
+      components,
+      blocks,
+      tokens,
+      graph: primary.graph,
+      performanceSummary: primary.performanceSummary,
+      packageMap,
+      defaultPackageName: primary.packageName
+    });
+    return {
+      snapshot,
+      components: snapshot.components,
+      blocks: snapshot.blocks,
+      tokens: snapshot.tokens,
+      graph: primary.graph,
+      performanceSummary: primary.performanceSummary,
+      packageMap: snapshot.packageMap,
+      defaultPackageName: snapshot.defaultPackageName,
+      capabilities: new Set(snapshot.capabilities)
+    };
+  }
+};
+
+// src/adapters/auto-extract.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { join as join5, relative, sep } from "path";
+
+// src/adapters/discover-components.ts
+import { readdirSync as readdirSync2, existsSync as existsSync3 } from "fs";
+import { join as join3, extname, basename } from "path";
+var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".next",
+  ".nuxt",
+  "coverage",
+  "__tests__",
+  "__mocks__",
+  ".git",
+  ".cache",
+  ".turbo",
+  "out"
+]);
+var EXCLUDED_PATTERNS = [
+  /\.test\./,
+  /\.spec\./,
+  /\.stories\./,
+  /\.story\./,
+  /\.fragment\./,
+  /\.d\.ts$/,
+  /\.config\./,
+  /\.mock\./,
+  /\.fixture\./
+];
+function discoverComponentFiles(projectRoot) {
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  const scanDirs = [
+    "src/components",
+    "components",
+    "lib/components",
+    "src/ui",
+    "lib/ui",
+    "packages"
+  ].map((d) => join3(projectRoot, d)).filter((d) => existsSync3(d));
+  if (scanDirs.length === 0) {
+    const srcDir = join3(projectRoot, "src");
+    if (existsSync3(srcDir)) scanDirs.push(srcDir);
+  }
+  for (const dir of scanDirs) {
+    walkDir(dir, results, seen);
+  }
+  return results;
+}
+function walkDir(dir, results, seen, depth = 0) {
+  if (depth > 6) return;
+  let entries;
+  try {
+    entries = readdirSync2(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) continue;
+      walkDir(join3(dir, entry.name), results, seen, depth + 1);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const ext = extname(entry.name);
+    if (ext !== ".tsx" && ext !== ".jsx") continue;
+    if (EXCLUDED_PATTERNS.some((p) => p.test(entry.name))) continue;
+    const filePath = join3(dir, entry.name);
+    if (seen.has(filePath)) continue;
+    seen.add(filePath);
+    const name = inferComponentName(entry.name, dir);
+    if (name) {
+      results.push({ filePath, componentName: name });
+    }
+  }
+}
+function inferComponentName(fileName, dirPath) {
+  const withoutExt = fileName.replace(/\.(tsx|jsx)$/, "");
+  if (withoutExt === "index") {
+    return basename(dirPath);
+  }
+  return withoutExt;
+}
+
+// src/adapters/scan-tokens.ts
+import { readdirSync as readdirSync3, readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+import { join as join4, extname as extname2 } from "path";
+function scanTokens(projectRoot) {
+  const cssFiles = discoverCssFiles(projectRoot);
+  if (cssFiles.length === 0) return void 0;
+  const allTokens = [];
+  let prefix = "";
+  for (const filePath of cssFiles) {
+    try {
+      const content = readFileSync4(filePath, "utf-8");
+      const tokens = extractCustomProperties(content);
+      allTokens.push(...tokens);
+    } catch {
+      continue;
+    }
+  }
+  if (allTokens.length === 0) return void 0;
+  prefix = detectPrefix(allTokens.map((t) => t.name));
+  const categories = {};
+  for (const token of allTokens) {
+    const category = inferTokenCategory(token.name);
+    if (!categories[category]) categories[category] = [];
+    if (!categories[category].some((t) => t.name === token.name)) {
+      categories[category].push(token);
+    }
+  }
+  return {
+    prefix,
+    total: Object.values(categories).reduce((sum, arr) => sum + arr.length, 0),
+    categories
+  };
+}
+function discoverCssFiles(projectRoot) {
+  const files = [];
+  const searchDirs = [
+    "src",
+    "styles",
+    "css",
+    "app"
+  ].map((d) => join4(projectRoot, d)).filter((d) => existsSync4(d));
+  searchDirs.push(projectRoot);
+  for (const dir of searchDirs) {
+    try {
+      const entries = readdirSync3(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const ext = extname2(entry.name);
+        if (ext === ".css" || ext === ".scss") {
+          files.push(join4(dir, entry.name));
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  const srcDir = join4(projectRoot, "src");
+  if (existsSync4(srcDir)) {
+    try {
+      for (const subEntry of readdirSync3(srcDir, { withFileTypes: true })) {
+        if (subEntry.isDirectory() && ["styles", "css", "theme", "tokens"].includes(subEntry.name)) {
+          const subDir = join4(srcDir, subEntry.name);
+          for (const file of readdirSync3(subDir, { withFileTypes: true })) {
+            if (file.isFile() && (file.name.endsWith(".css") || file.name.endsWith(".scss"))) {
+              files.push(join4(subDir, file.name));
+            }
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return [...new Set(files)];
+}
+function extractCustomProperties(content) {
+  const tokens = [];
+  let inRelevantBlock = false;
+  let braceDepth = 0;
+  const relevantSelectors = [":root", ".dark", "[data-theme", "@theme"];
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!inRelevantBlock && braceDepth === 0) {
+      if (relevantSelectors.some((sel) => trimmed.startsWith(sel) || trimmed.includes(sel))) {
+        if (trimmed.includes("{")) {
+          inRelevantBlock = true;
+          braceDepth = 1;
+        }
+      }
+    }
+    if (inRelevantBlock) {
+      for (const ch of trimmed) {
+        if (ch === "{") braceDepth++;
+        else if (ch === "}") {
+          braceDepth--;
+          if (braceDepth <= 0) {
+            inRelevantBlock = false;
+            braceDepth = 0;
+          }
+        }
+      }
+    }
+    if (!inRelevantBlock && braceDepth === 0) continue;
+    const match = trimmed.match(/^(--[\w-]+)\s*:\s*(.+?)\s*;/);
+    if (match) {
+      const [, name, value] = match;
+      const commentMatch = value.match(/\/\*\s*(.+?)\s*\*\//);
+      const cleanValue = value.replace(/\/\*.*?\*\//, "").trim();
+      tokens.push({
+        name,
+        value: cleanValue,
+        description: commentMatch?.[1]
+      });
+    }
+  }
+  return tokens;
+}
+function detectPrefix(names) {
+  if (names.length === 0) return "--";
+  const stripped = names.map((n) => n.slice(2));
+  let prefix = "";
+  const first = stripped[0];
+  for (let i = 0; i < first.length; i++) {
+    const ch = first[i];
+    if (stripped.every((n) => n[i] === ch)) {
+      prefix += ch;
+    } else {
+      break;
+    }
+  }
+  const lastDash = prefix.lastIndexOf("-");
+  if (lastDash > 0) {
+    return "--" + prefix.slice(0, lastDash + 1);
+  }
+  return "--";
+}
+function inferTokenCategory(name) {
+  const n = name.toLowerCase();
+  if (n.includes("color") || n.includes("background") || n.includes("foreground") || n.includes("primary") || n.includes("secondary") || n.includes("accent") || n.includes("muted") || n.includes("destructive") || n.includes("popover") || n.includes("card") && !n.includes("card-") || n.includes("chart")) {
+    return "colors";
+  }
+  if (n.includes("font") || n.includes("text") || n.includes("letter") || n.includes("line-height")) {
+    return "typography";
+  }
+  if (n.includes("space") || n.includes("gap") || n.includes("padding") || n.includes("margin")) {
+    return "spacing";
+  }
+  if (n.includes("radius")) {
+    return "radius";
+  }
+  if (n.includes("shadow")) {
+    return "shadows";
+  }
+  if (n.includes("border")) {
+    return "borders";
+  }
+  if (n.includes("ring")) {
+    return "focus";
+  }
+  if (n.includes("sidebar")) {
+    return "sidebar";
+  }
+  if (n.includes("input")) {
+    return "forms";
+  }
+  return "other";
+}
+
+// src/adapters/auto-extract.ts
+var AutoExtractionAdapter = class {
+  name = "auto-extract";
+  discover(startDir) {
+    return discoverComponentFiles(startDir).map((f) => f.filePath);
+  }
+  async load(projectRoot) {
+    let extractMod;
+    try {
+      extractMod = await loadExtractorModule();
+    } catch (e) {
+      throw new Error(
+        "Auto-extraction requires @fragments-sdk/extract and TypeScript.\n\nIf you see this error, the MCP server may not be installed correctly.\nAlternative: pre-build your design system with `npx fragments build`"
+      );
+    }
+    const tsconfigPath = findTsConfig(projectRoot);
+    const extractor = extractMod.createComponentExtractor(tsconfigPath ?? void 0);
+    try {
+      const discovered = discoverComponentFiles(projectRoot);
+      if (discovered.length === 0) {
+        throw new Error(
+          `No component files found in ${projectRoot}.
+Searched: src/components/, components/, lib/components/, src/ui/
+
+If your components are elsewhere, create a fragments.json with:
+  npx fragments build`
+        );
+      }
+      const components = {};
+      const packageMap = /* @__PURE__ */ new Map();
+      const defaultPackageName = readPackageName(projectRoot);
+      let extractedCount = 0;
+      const fileToComponents = /* @__PURE__ */ new Map();
+      for (const { filePath, componentName } of discovered) {
+        try {
+          const metas = extractor.extractAll(filePath);
+          for (const meta of metas) {
+            const fragment = mapToCompiledFragment(meta, filePath, projectRoot);
+            components[meta.name] = fragment;
+            if (defaultPackageName) {
+              packageMap.set(meta.name, defaultPackageName);
+            }
+            extractedCount++;
+            const relPath = relative(projectRoot, filePath);
+            if (!fileToComponents.has(relPath)) fileToComponents.set(relPath, []);
+            fileToComponents.get(relPath).push(meta.name);
+          }
+          if (metas.length === 0) {
+            const meta = extractor.extract(filePath, componentName);
+            if (meta) {
+              const fragment = mapToCompiledFragment(meta, filePath, projectRoot);
+              components[meta.name] = fragment;
+              if (defaultPackageName) {
+                packageMap.set(meta.name, defaultPackageName);
+              }
+              extractedCount++;
+              const relPath = relative(projectRoot, filePath);
+              if (!fileToComponents.has(relPath)) fileToComponents.set(relPath, []);
+              fileToComponents.get(relPath).push(meta.name);
+            }
+          }
+        } catch {
+          continue;
+        }
+      }
+      inferRelations(components, fileToComponents);
+      console.error(`[fragments-mcp] Extracted ${extractedCount} components from ${discovered.length} files.`);
+      if (extractedCount === 0) {
+        throw new Error(
+          `Found ${discovered.length} component files but could not extract any props.
+This usually means TypeScript cannot parse the files.
+Check that your tsconfig.json includes the component directories.`
+        );
+      }
+      const tokens = scanTokens(projectRoot);
+      if (tokens) {
+        console.error(`[fragments-mcp] Found ${tokens.total} design tokens across ${Object.keys(tokens.categories).length} categories.`);
+      }
+      const snapshotComponents = Object.fromEntries(
+        Object.entries(components).map(([key, fragment]) => [
+          key,
+          componentFromCompiledFragment({
+            id: key,
+            fragment,
+            sourceType: "auto-extract",
+            packageName: packageMap.get(fragment.meta.name) ?? defaultPackageName,
+            importPath: packageMap.get(fragment.meta.name) ?? defaultPackageName
+          })
+        ])
+      );
+      const snapshotTokens = tokens ? tokensFromCompiledTokenData(tokens) : void 0;
+      const packageMapRecord = Object.fromEntries(packageMap.entries());
+      const snapshot = validateSnapshot({
+        schemaVersion: 1,
+        sourceType: "auto-extract",
+        sourceLabel: "Auto-extracted source files",
+        capabilities: buildCapabilities({
+          components: snapshotComponents,
+          tokens: snapshotTokens
+        }),
+        metadata: {
+          packageName: defaultPackageName,
+          importPath: defaultPackageName
+        },
+        components: snapshotComponents,
+        tokens: snapshotTokens,
+        packageMap: packageMapRecord,
+        defaultPackageName
+      });
+      return {
+        snapshot,
+        components: snapshot.components,
+        blocks: snapshot.blocks,
+        tokens: snapshot.tokens,
+        graph: void 0,
+        performanceSummary: void 0,
+        packageMap: snapshot.packageMap,
+        defaultPackageName: snapshot.defaultPackageName,
+        capabilities: new Set(snapshot.capabilities)
+      };
+    } finally {
+      extractor.dispose();
+    }
+  }
+};
+var extractorModulePromise = null;
+async function loadExtractorModule() {
+  if (!extractorModulePromise) {
+    extractorModulePromise = import("./dist-TTCI6TME.js");
+  }
+  return extractorModulePromise;
+}
+var UNIVERSAL_INHERITED = /* @__PURE__ */ new Set(["children", "className", "id", "disabled"]);
+var FORM_INPUT_INHERITED = /* @__PURE__ */ new Set([
+  "placeholder",
+  "value",
+  "defaultValue",
+  "onChange",
+  "name",
+  "required",
+  "autoFocus",
+  "autoComplete",
+  "checked",
+  "defaultChecked",
+  "type"
+]);
+var LABEL_INHERITED = /* @__PURE__ */ new Set(["htmlFor"]);
+var INPUT_LIKE_NAMES = /input|select|textarea|checkbox|radio|switch|slider|combobox/i;
+var LABEL_LIKE_NAMES = /label/i;
+function getRelevantInheritedProps(componentName) {
+  const allowed = new Set(UNIVERSAL_INHERITED);
+  if (INPUT_LIKE_NAMES.test(componentName)) {
+    for (const p of FORM_INPUT_INHERITED) allowed.add(p);
+  }
+  if (LABEL_LIKE_NAMES.test(componentName)) {
+    for (const p of LABEL_INHERITED) allowed.add(p);
+  }
+  return allowed;
+}
+function mapToCompiledFragment(meta, filePath, projectRoot) {
+  const relevantInherited = getRelevantInheritedProps(meta.name);
+  const props = {};
+  for (const [name, propMeta] of Object.entries(meta.props)) {
+    if (propMeta.source === "inherited" && !relevantInherited.has(name)) continue;
+    props[name] = {
+      type: propMeta.type,
+      description: propMeta.description ?? "",
+      required: propMeta.required,
+      ...propMeta.values && { values: propMeta.values },
+      ...propMeta.default !== void 0 && { default: propMeta.default }
+    };
+  }
+  const relativePath = relative(projectRoot, filePath);
+  const category = inferCategory(relativePath);
+  const importPath = buildImportPath(relativePath);
+  const description = buildDescription(meta, props);
+  const propsSummary = buildPropsSummary(props);
+  const codeExample = buildCodeExample(meta.name, props);
+  const fragmentMeta = {
+    name: meta.name,
+    description,
+    category
+  };
+  return {
+    filePath: relativePath,
+    meta: fragmentMeta,
+    usage: {
+      when: [`Use ${meta.name} when you need a ${category} ${meta.name.toLowerCase()} element.`],
+      whenNot: [],
+      guidelines: importPath ? [`import { ${meta.name} } from "${importPath}"`] : []
+    },
+    props,
+    propsSummary,
+    variants: codeExample ? [{ name: "Default", description: `Basic ${meta.name} usage`, code: codeExample }] : [],
+    sourcePath: relativePath,
+    exportName: meta.name,
+    _generated: {
+      source: "extracted",
+      verified: false,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    ...meta.composition && {
+      ai: {
+        compositionPattern: meta.composition.pattern
+      }
+    }
+  };
+}
+function buildImportPath(relativePath) {
+  const withoutExt = relativePath.replace(/\.(tsx|jsx|ts|js)$/, "");
+  if (withoutExt.startsWith(`src${sep}`)) {
+    return "@/" + withoutExt.slice(4).split(sep).join("/");
+  }
+  return "./" + withoutExt.split(sep).join("/");
+}
+function buildDescription(meta, localProps) {
+  if (meta.description && meta.description !== meta.name && !meta.description.endsWith(" component")) {
+    return meta.description;
+  }
+  const propEntries = Object.entries(localProps);
+  if (propEntries.length === 0) {
+    return `${meta.name} component`;
+  }
+  const details = [];
+  for (const [name, prop] of propEntries) {
+    if (prop.values && prop.values.length > 0) {
+      details.push(`${prop.values.length} ${name} options`);
+    }
+  }
+  if (details.length > 0) {
+    return `${meta.name} component with ${details.join(" and ")}.`;
+  }
+  return `${meta.name} component with ${propEntries.length} configurable prop${propEntries.length === 1 ? "" : "s"}.`;
+}
+function buildPropsSummary(props) {
+  const summaries = [];
+  for (const [name, prop] of Object.entries(props)) {
+    let summary = `${name}`;
+    if (prop.values && prop.values.length > 0) {
+      summary += `: ${prop.values.map((v) => `"${v}"`).join(" | ")}`;
+    } else {
+      summary += `: ${prop.type}`;
+    }
+    if (prop.default !== void 0) {
+      summary += ` (default: ${JSON.stringify(prop.default)})`;
+    }
+    if (prop.required) {
+      summary += " (required)";
+    }
+    summaries.push(summary);
+  }
+  return summaries;
+}
+function buildCodeExample(name, props) {
+  const propsStr = [];
+  for (const [pName, prop] of Object.entries(props)) {
+    if (pName === "children" || pName === "asChild" || pName === "className") continue;
+    if (pName === "onChange" || pName === "onSubmit" || pName === "value" || pName === "defaultValue" || pName === "checked" || pName === "defaultChecked" || pName === "autoFocus" || pName === "autoComplete" || pName === "required" || pName === "disabled" || pName === "name") continue;
+    if (prop.default !== void 0) {
+      if (prop.values && prop.values.length > 1) {
+        const nonDefault = prop.values.find((v) => v !== String(prop.default));
+        if (nonDefault) {
+          propsStr.push(`${pName}="${nonDefault}"`);
+          continue;
+        }
+      }
+    }
+    if (pName === "placeholder" && INPUT_LIKE_NAMES.test(name)) {
+      propsStr.push(`placeholder="Enter ${name.toLowerCase()}..."`);
+      continue;
+    }
+    if (pName === "htmlFor" && LABEL_LIKE_NAMES.test(name)) {
+      propsStr.push(`htmlFor="field-id"`);
+      continue;
+    }
+    if (pName === "id" || pName === "className" || pName === "children") continue;
+    if (prop.required) {
+      if (prop.values && prop.values.length > 0) {
+        propsStr.push(`${pName}="${prop.values[0]}"`);
+      } else if (prop.type === "string") {
+        propsStr.push(`${pName}="..."`);
+      }
+    }
+  }
+  const propsJsx = propsStr.length > 0 ? " " + propsStr.join(" ") : "";
+  const nameLower = name.toLowerCase();
+  const selfClosing = nameLower.includes("input") || nameLower.includes("separator") || nameLower.includes("slider") || nameLower.includes("switch");
+  if (selfClosing) {
+    return `<${name}${propsJsx} />`;
+  }
+  return `<${name}${propsJsx}>${name}</${name}>`;
+}
+function buildCompositionExample(root, subs) {
+  const header = subs.filter((s) => s.includes("Header"));
+  const title = subs.filter((s) => s.includes("Title"));
+  const description = subs.filter((s) => s.includes("Description"));
+  const content = subs.filter((s) => s.includes("Content") || s.includes("Body"));
+  const footer = subs.filter((s) => s.includes("Footer"));
+  const action = subs.filter((s) => s.includes("Action"));
+  const other = subs.filter(
+    (s) => !header.includes(s) && !title.includes(s) && !description.includes(s) && !content.includes(s) && !footer.includes(s) && !action.includes(s)
+  );
+  const lines = [`<${root}>`];
+  if (header.length > 0) {
+    lines.push(`  <${header[0]}>`);
+    for (const t of title) lines.push(`    <${t}>Title</${t}>`);
+    for (const d of description) lines.push(`    <${d}>Description</${d}>`);
+    lines.push(`  </${header[0]}>`);
+  } else {
+    for (const t of title) lines.push(`  <${t}>Title</${t}>`);
+    for (const d of description) lines.push(`  <${d}>Description</${d}>`);
+  }
+  for (const c of content) lines.push(`  <${c}>Content</${c}>`);
+  for (const o of other) lines.push(`  <${o}>...</${o}>`);
+  if (footer.length > 0) {
+    lines.push(`  <${footer[0]}>`);
+    for (const a of action) lines.push(`    <${a}>Action</${a}>`);
+    lines.push(`  </${footer[0]}>`);
+  } else {
+    for (const a of action) lines.push(`  <${a}>Action</${a}>`);
+  }
+  lines.push(`</${root}>`);
+  return lines.join("\n");
+}
+function inferRelations(components, fileToComponents) {
+  for (const [_file, names] of fileToComponents) {
+    if (names.length <= 1) continue;
+    const sorted = [...names].sort((a, b) => a.length - b.length);
+    const root = sorted[0];
+    const subs = sorted.slice(1).filter((n) => n.startsWith(root));
+    if (subs.length === 0) continue;
+    const rootComp = components[root];
+    if (rootComp) {
+      rootComp.ai = {
+        ...rootComp.ai,
+        compositionPattern: "compound",
+        subComponents: subs
+      };
+      rootComp.relations = subs.map((sub) => ({
+        component: sub,
+        relationship: "parent-of",
+        note: `${sub} is a sub-component of ${root}`
+      }));
+      const compositionCode = buildCompositionExample(root, subs);
+      rootComp.variants = [
+        ...rootComp.variants ?? [],
+        { name: "Composition", description: `${root} with all sub-components`, code: compositionCode }
+      ];
+    }
+    const rootImportPath = rootComp?.usage?.guidelines?.[0];
+    for (const sub of subs) {
+      const subComp = components[sub];
+      if (subComp) {
+        subComp.relations = [{
+          component: root,
+          relationship: "child-of",
+          note: `Use inside <${root}>`
+        }];
+        if (rootImportPath) {
+          const allNames = [root, ...subs].join(", ");
+          const fromPath = rootImportPath.match(/from\s+"([^"]+)"/)?.[1] ?? "";
+          if (fromPath) {
+            subComp.usage = {
+              ...subComp.usage,
+              guidelines: [`import { ${allNames} } from "${fromPath}"`]
+            };
+          }
+        }
+      }
+    }
+    if (rootComp && rootComp.usage?.guidelines?.[0]) {
+      const fromPath = rootComp.usage.guidelines[0].match(/from\s+"([^"]+)"/)?.[1] ?? "";
+      if (fromPath) {
+        const allNames = [root, ...subs].join(", ");
+        rootComp.usage.guidelines = [`import { ${allNames} } from "${fromPath}"`];
+      }
+    }
+  }
+}
+function inferCategory(relativePath) {
+  const parts = relativePath.split(sep);
+  const componentsIdx = parts.findIndex(
+    (p) => p === "components" || p === "ui"
+  );
+  if (componentsIdx >= 0 && componentsIdx + 1 < parts.length - 1) {
+    const nextPart = parts[componentsIdx + 1];
+    if (/^[A-Z]/.test(nextPart)) return parts[componentsIdx] || "uncategorized";
+    return nextPart;
+  }
+  return "uncategorized";
+}
+function findTsConfig(projectRoot) {
+  const candidates = ["tsconfig.json", "tsconfig.app.json"];
+  for (const name of candidates) {
+    const p = join5(projectRoot, name);
+    if (existsSync5(p)) return p;
+  }
+  return null;
+}
+function readPackageName(projectRoot) {
+  try {
+    const pkgPath = join5(projectRoot, "package.json");
+    if (!existsSync5(pkgPath)) return void 0;
+    const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
+    return pkg.name;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/adapters/cloud-catalog.ts
+var DEFAULT_CLOUD_URL2 = "https://app.usefragments.com/api/catalog";
+function mergeDesignSystemMetadata(catalogDesignSystem, contextDesignSystem) {
+  return {
+    name: catalogDesignSystem?.name ?? contextDesignSystem?.name,
+    packageName: catalogDesignSystem?.packageName ?? contextDesignSystem?.packageName ?? null,
+    importPath: catalogDesignSystem?.importPath ?? contextDesignSystem?.importPath ?? catalogDesignSystem?.packageName ?? contextDesignSystem?.packageName ?? null
+  };
+}
+function chooseComponentSource(args) {
+  if (args.contextComponents.length > args.catalogComponents.length) {
+    return args.contextComponents;
+  }
+  return args.catalogComponents;
+}
+function dominantString(values) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    if (!trimmed) continue;
+    counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);
+  }
+  const ranked = [...counts.entries()].sort(
+    (a, b) => b[1] - a[1] || a[0].localeCompare(b[0])
+  );
+  if (ranked.length === 0) return void 0;
+  if (ranked[1] && ranked[1][1] === ranked[0][1]) return void 0;
+  return ranked[0][0];
+}
+function inferDesignSystemMetadataFromComponents(components) {
+  const packageName = dominantString(
+    components.map((component) => component.packageName)
+  );
+  const packageComponents = packageName ? components.filter((component) => component.packageName === packageName) : components;
+  const importPath = dominantString(
+    packageComponents.map(
+      (component) => component.importPath ?? component.packageName
+    )
+  );
+  return {
+    packageName: packageName ?? null,
+    importPath: importPath ?? packageName ?? null
+  };
+}
+var TOKEN_CATEGORY_ALIASES = {
+  color: ["color", "colors", "accent", "background", "foreground", "danger", "brand"],
+  spacing: ["spacing", "space", "padding", "margin", "gap", "inset"],
+  typography: ["typography", "font", "text", "copy", "line-height", "letter"],
+  border: ["border", "borders", "stroke", "outline"],
+  radius: ["radius", "radii", "corner", "corners", "rounded"],
+  shadow: ["shadow", "shadows", "elevation"],
+  layout: ["layout", "grid", "container", "breakpoint"],
+  focus: ["focus", "ring", "focus-ring"],
+  surface: ["surface", "surfaces", "canvas", "card", "background"]
+};
+function normalizeCatalogUrl(url) {
+  if (!url) return DEFAULT_CLOUD_URL2;
+  if (url.endsWith("/api/catalog")) return url;
+  return `${url.replace(/\/+$/, "")}/api/catalog`;
+}
+function normalizeValidateFixUrl(url) {
+  const base = normalizeCatalogUrl(url).replace(/\/api\/catalog$/, "");
+  return `${base}/api/context?target=validate-fix`;
+}
+function normalizeValue(value) {
+  return value?.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim() ?? "";
+}
+function canonicalizeTokenCategory(token) {
+  const candidates = [
+    token.category,
+    token.path?.[0],
+    token.name.split(/[.:/-]/)[0]
+  ].map(normalizeValue).filter(Boolean);
+  for (const candidate of candidates) {
+    for (const [canonical, aliases] of Object.entries(
+      TOKEN_CATEGORY_ALIASES
+    )) {
+      if (candidate === canonical || aliases.some(
+        (alias) => candidate === alias || candidate.includes(alias) || alias.includes(candidate)
+      )) {
+        return canonical;
+      }
+    }
+  }
+  return candidates[0] || "other";
+}
+function groupTokens(flat) {
+  const categories = {};
+  const normalizedFlat = (flat ?? []).filter((token) => !isGarbageToken(token)).map((token) => {
+    const category = canonicalizeTokenCategory(token);
+    const normalized = {
+      name: token.name,
+      category,
+      value: token.value,
+      description: token.description,
+      path: token.path,
+      type: token.type
+    };
+    if (!categories[category]) {
+      categories[category] = [];
+    }
+    categories[category].push(normalized);
+    return normalized;
+  });
+  return {
+    prefix: "",
+    total: normalizedFlat.length,
+    categories,
+    flat: normalizedFlat
+  };
+}
+function mapComponent(component, designSystem) {
+  return {
+    id: component.componentKey,
+    name: component.name,
+    description: component.description ?? "",
+    category: component.category ?? "uncategorized",
+    status: component.status ?? "stable",
+    tags: [],
+    props: Object.fromEntries(
+      Object.entries(component.props ?? {}).map(([propName, prop]) => [
+        propName,
+        {
+          type: prop.type ?? "unknown",
+          description: prop.description ?? "",
+          required: prop.required ?? false,
+          default: prop.default,
+          values: prop.values
+        }
+      ])
+    ),
+    propsSummary: Object.entries(component.props ?? {}).map(
+      ([propName, prop]) => `${propName}${prop.required ? " (required)" : ""}: ${prop.type ?? "unknown"}`
+    ),
+    examples: (component.examples ?? []).map((example) => ({
+      name: example.title ?? "Example",
+      description: example.kind,
+      code: example.code,
+      kind: example.kind
+    })),
+    relations: (component.relations ?? []).map((relation) => ({
+      componentName: relation.component ?? relation.componentKey ?? "Unknown",
+      componentId: relation.componentKey,
+      relationship: relation.relationship ?? relation.type ?? "related",
+      note: relation.note,
+      description: relation.description
+    })),
+    compoundChildren: (component.compoundChildren ?? []).filter((child) => child.subcomponentVisibility !== "internal").map((child) => ({
+      name: child.name,
+      componentId: child.componentKey,
+      description: child.description,
+      required: child.required,
+      accepts: child.accepts,
+      visibility: child.subcomponentVisibility === "internal" ? "internal" : "public"
+    })),
+    guidance: {
+      when: component.usageGuidance ? [component.usageGuidance] : [],
+      whenNot: component.donts ?? [],
+      guidelines: component.usageGuidance ? [component.usageGuidance] : [],
+      accessibility: [],
+      usageGuidance: component.usageGuidance,
+      dos: component.dos ?? [],
+      donts: component.donts ?? [],
+      patterns: []
+    },
+    sourceType: "cloud",
+    sourcePath: component.sourcePath,
+    sourceRepoFullName: component.sourceRepoFullName ?? void 0,
+    packageName: component.packageName ?? designSystem?.packageName ?? void 0,
+    importPath: component.importPath ?? component.packageName ?? designSystem?.importPath ?? designSystem?.packageName ?? void 0,
+    publicRef: component.publicRef,
+    publicSlug: component.publicSlug ?? null,
+    isCanonical: component.isCanonical ?? false,
+    tier: component.tier,
+    parentComponentId: component.parentComponentKey,
+    parentComponentName: component.parentComponentName,
+    metadata: {
+      a11yRules: [],
+      scenarioTags: []
+    }
+  };
+}
+function normalizeValidateFixContext(raw) {
+  const content = raw.content;
+  if (!content || !Array.isArray(content.components)) {
+    return void 0;
+  }
+  const components = content.components.filter(
+    (component) => Boolean(component?.componentKey) && Boolean(component?.publicRef) && Boolean(component?.name) && Boolean(component?.selection)
+  ).map((component) => ({
+    componentKey: component.componentKey,
+    publicRef: component.publicRef,
+    name: component.name,
+    category: component.category ?? "uncategorized",
+    status: component.status ?? "stable",
+    tier: component.tier ?? "composition",
+    isCanonical: component.isCanonical ?? false,
+    isActive: component.isActive ?? true,
+    selection: component.selection ?? "allowed",
+    reasons: component.reasons ?? [],
+    usageGuidance: component.usageGuidance,
+    dos: component.dos ?? [],
+    donts: component.donts ?? []
+  }));
+  return {
+    version: 1,
+    catalogRevision: content.catalogRevision,
+    updatedAt: content.updatedAt,
+    policy: {
+      mode: "cloud",
+      endpoint: content.policy?.endpoint ?? "/api/govern/policy"
+    },
+    components
+  };
+}
+var CloudCatalogAdapter = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  name = "cloud";
+  async load(_projectRoot) {
+    const headers = {
+      "X-API-Key": this.options.apiKey
+    };
+    const [response, validateFixResponse] = await Promise.all([
+      fetch(normalizeCatalogUrl(this.options.url), { headers }),
+      fetch(normalizeValidateFixUrl(this.options.url), { headers }).catch(
+        () => null
+      )
+    ]);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to load Cloud catalog (${response.status} ${response.statusText}).`
+      );
+    }
+    const raw = await response.json();
+    const validateFixRaw = validateFixResponse && validateFixResponse.ok ? await validateFixResponse.json() : void 0;
+    const sourceComponents = chooseComponentSource({
+      catalogComponents: raw.components ?? [],
+      contextComponents: validateFixRaw?.content?.components ?? []
+    });
+    const inferredDesignSystem = inferDesignSystemMetadataFromComponents(sourceComponents);
+    const designSystem = mergeDesignSystemMetadata(
+      {
+        ...raw.designSystem,
+        packageName: raw.designSystem?.packageName ?? inferredDesignSystem.packageName,
+        importPath: raw.designSystem?.importPath ?? inferredDesignSystem.importPath
+      },
+      validateFixRaw?.content?.designSystem
+    );
+    const components = Object.fromEntries(
+      sourceComponents.map((component) => [
+        component.componentKey,
+        mapComponent(component, designSystem)
+      ])
+    );
+    const tokens = raw.tokens?.flat ? groupTokens(raw.tokens.flat) : void 0;
+    const packageName = designSystem?.packageName ?? void 0;
+    const importPath = designSystem?.importPath ?? designSystem?.packageName ?? void 0;
+    const packageMap = Object.fromEntries(
+      Object.values(components).map((component) => [
+        component.name,
+        component.importPath ?? component.packageName ?? packageName
+      ]).filter(
+        (entry) => typeof entry[1] === "string" && entry[1].length > 0
+      )
+    );
+    const snapshot = validateSnapshot({
+      schemaVersion: 1,
+      sourceType: "cloud",
+      sourceLabel: "Fragments Cloud catalog",
+      capabilities: buildCapabilities({
+        components,
+        tokens
+      }),
+      metadata: {
+        designSystemName: designSystem?.name ?? raw.org.name,
+        packageName,
+        importPath,
+        revision: raw.revision,
+        updatedAt: typeof raw.updatedAt === "number" ? new Date(raw.updatedAt).toISOString() : void 0
+      },
+      components,
+      tokens,
+      packageMap,
+      defaultPackageName: packageName
+    });
+    const validateFixContext = validateFixRaw ? normalizeValidateFixContext(validateFixRaw) : void 0;
+    const hydratedComponents = Object.fromEntries(
+      Object.entries(snapshot.components).map(([componentId, component]) => [
+        componentId,
+        {
+          ...component,
+          isCanonical: components[componentId]?.isCanonical ?? false
+        }
+      ])
+    );
+    return {
+      snapshot: {
+        ...snapshot,
+        components: hydratedComponents
+      },
+      components: hydratedComponents,
+      blocks: snapshot.blocks,
+      tokens: snapshot.tokens,
+      graph: void 0,
+      performanceSummary: void 0,
+      packageMap: snapshot.packageMap,
+      defaultPackageName: snapshot.defaultPackageName,
+      validateFixContext,
+      capabilities: new Set(snapshot.capabilities)
+    };
+  }
+};
+
+// src/adapters/bundle.ts
+import { existsSync as existsSync6 } from "fs";
+import { readFile as readFile2 } from "fs/promises";
+import { dirname as dirname3, resolve as resolve2 } from "path";
+import {
+  bundleComponentShardSchema,
+  bundleManifestSchema,
+  bundleTokenFileSchema
+} from "@fragments-sdk/core";
+async function readJsonFile(path, parser, label) {
+  const content = await readFile2(path, "utf-8");
+  try {
+    return parser.parse(JSON.parse(content));
+  } catch (error) {
+    throw new Error(
+      `Invalid ${label} at ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function normalizeProps(props) {
+  return Object.fromEntries(
+    Object.entries(props ?? {}).map(([propName, value]) => {
+      const prop = value && typeof value === "object" ? value : {};
+      return [
+        propName,
+        {
+          type: typeof prop.type === "string" && prop.type.length > 0 ? prop.type : "unknown",
+          description: typeof prop.description === "string" ? prop.description : "",
+          required: Boolean(prop.required),
+          default: prop.default,
+          values: Array.isArray(prop.values) ? prop.values.filter((entry) => typeof entry === "string") : void 0,
+          constraints: Array.isArray(prop.constraints) ? prop.constraints.filter(
+            (entry) => typeof entry === "string"
+          ) : void 0
+        }
+      ];
+    })
+  );
+}
+function normalizeExamples(examples) {
+  return examples.map((example) => {
+    const record = example && typeof example === "object" ? example : {};
+    return {
+      name: typeof record.title === "string" && record.title || typeof record.name === "string" && record.name || "Example",
+      description: typeof record.description === "string" ? record.description : void 0,
+      code: typeof record.code === "string" ? record.code : void 0,
+      kind: typeof record.kind === "string" ? record.kind : void 0
+    };
+  });
+}
+function normalizeRelations(relations, fallback) {
+  if (relations.length > 0) {
+    return relations.map((relation) => {
+      const record = relation && typeof relation === "object" ? relation : {};
+      return {
+        componentName: typeof record.component === "string" && record.component || typeof record.name === "string" && record.name || typeof record.componentName === "string" && record.componentName || typeof record.componentId === "string" && record.componentId || "Unknown",
+        componentId: typeof record.componentId === "string" ? record.componentId : void 0,
+        relationship: typeof record.relationship === "string" && record.relationship || typeof record.type === "string" && record.type || "related",
+        note: typeof record.note === "string" ? record.note : void 0,
+        description: typeof record.description === "string" ? record.description : void 0
+      };
+    });
+  }
+  return fallback.map((relation) => ({
+    componentName: relation.name,
+    componentId: relation.componentId,
+    relationship: relation.type
+  }));
+}
+function buildComponent(manifest, entry, shard) {
+  const sourcePackage = manifest.designSystem.importPath ?? manifest.designSystem.packageName ?? void 0;
+  const component = shard.component;
+  const componentRecord = component;
+  const props = normalizeProps(component.props);
+  return {
+    id: shard.componentId,
+    name: component.name,
+    description: component.description,
+    category: component.category,
+    status: component.status,
+    tags: [],
+    props,
+    propsSummary: Object.entries(props).map(
+      ([propName, prop]) => `${propName}${prop.required ? " (required)" : ""}: ${prop.type}`
+    ),
+    examples: normalizeExamples(component.examples),
+    relations: normalizeRelations(component.relations, entry.relations),
+    compoundChildren: entry.compoundChildren.map((child) => ({
+      name: child.name,
+      componentId: child.componentId,
+      visibility: "public"
+    })),
+    guidance: {
+      when: component.usageGuidance ? [component.usageGuidance] : [],
+      whenNot: component.donts,
+      guidelines: component.usageGuidance ? [component.usageGuidance] : [],
+      accessibility: [],
+      usageGuidance: component.usageGuidance || void 0,
+      dos: component.dos,
+      donts: component.donts,
+      patterns: []
+    },
+    sourceType: "bundle",
+    sourcePath: component.sourcePath,
+    sourceRepoFullName: component.sourceRepoFullName,
+    packageName: manifest.designSystem.packageName ?? void 0,
+    importPath: sourcePackage,
+    publicRef: component.publicRef,
+    publicSlug: component.publicSlug,
+    isCanonical: componentRecord.isCanonical ?? component.tier === "core",
+    tier: component.tier,
+    parentComponentName: component.parentComponentName,
+    metadata: {
+      a11yRules: [],
+      scenarioTags: []
+    }
+  };
+}
+var BundleAdapter = class {
+  name = "bundle";
+  discover(startDir) {
+    return findBundleManifest(startDir);
+  }
+  async load(projectRoot) {
+    const manifests = this.discover(projectRoot);
+    if (manifests.length === 0) {
+      throw new Error(
+        `No ${BRAND.dataDir}/${BRAND.manifestFile} found. Run \`${BRAND.cliCommand} context install --cloud\` or commit a Fragments bundle into your workspace.`
+      );
+    }
+    const manifestPath = manifests[0];
+    const manifest = await readJsonFile(
+      manifestPath,
+      bundleManifestSchema,
+      "bundle manifest"
+    );
+    const bundleDir = dirname3(manifestPath);
+    const repoRoot = dirname3(bundleDir);
+    const tokensPath = resolve2(bundleDir, "tokens.json");
+    const tokensFile = existsSync6(tokensPath) ? await readJsonFile(tokensPath, bundleTokenFileSchema, "bundle tokens") : void 0;
+    const components = Object.fromEntries(
+      await Promise.all(
+        Object.values(manifest.components).map(async (entry) => {
+          const shardPath = resolve2(repoRoot, entry.file);
+          const shard = await readJsonFile(
+            shardPath,
+            bundleComponentShardSchema,
+            `bundle component shard (${entry.name})`
+          );
+          return [entry.componentId, buildComponent(manifest, entry, shard)];
+        })
+      )
+    );
+    const packageName = manifest.designSystem.importPath ?? manifest.designSystem.packageName ?? void 0;
+    const packageMap = packageName ? Object.fromEntries(
+      Object.values(components).map((component) => [component.name, packageName])
+    ) : {};
+    const tokens = tokensFile ? {
+      prefix: "",
+      total: tokensFile.flat.length,
+      categories: Object.fromEntries(
+        Object.entries(tokensFile.categories).map(([category, value]) => [
+          category,
+          value.tokens.map((token) => ({
+            name: token.name,
+            category: token.category,
+            value: token.value,
+            description: token.description,
+            path: token.path,
+            type: token.type
+          }))
+        ])
+      ),
+      flat: tokensFile.flat.map((token) => ({
+        name: token.name,
+        category: token.category,
+        value: token.value,
+        description: token.description,
+        path: token.path,
+        type: token.type
+      }))
+    } : void 0;
+    const snapshot = validateSnapshot({
+      schemaVersion: 1,
+      sourceType: "bundle",
+      sourceLabel: `${BRAND.dataDir}/${BRAND.manifestFile}`,
+      capabilities: buildCapabilities({
+        components,
+        tokens
+      }),
+      metadata: {
+        designSystemName: manifest.designSystem.name,
+        packageName: manifest.designSystem.packageName ?? void 0,
+        importPath: manifest.designSystem.importPath ?? void 0,
+        revision: manifest.catalogRevision,
+        updatedAt: manifest.catalogUpdatedAt
+      },
+      components,
+      tokens,
+      packageMap,
+      defaultPackageName: packageName
+    });
+    const hydratedComponents = Object.fromEntries(
+      Object.entries(snapshot.components).map(([componentId, component]) => [
+        componentId,
+        {
+          ...component,
+          isCanonical: components[componentId]?.isCanonical ?? component.tier === "core"
+        }
+      ])
+    );
+    return {
+      snapshot: {
+        ...snapshot,
+        components: hydratedComponents
+      },
+      components: hydratedComponents,
+      blocks: snapshot.blocks,
+      tokens: snapshot.tokens,
+      graph: snapshot.graph,
+      performanceSummary: snapshot.performanceSummary,
+      packageMap: snapshot.packageMap,
+      defaultPackageName: snapshot.defaultPackageName,
+      capabilities: new Set(snapshot.capabilities)
+    };
+  }
+};
+
+// src/source-selection.ts
+function resolveCloudApiKey2(config, fileConfig) {
+  return config.cloudApiKey ?? fileConfig?.cloud?.apiKey ?? process.env.FRAGMENTS_API_KEY;
+}
+function resolveCloudUrl2(fileConfig) {
+  return fileConfig?.cloud?.url ?? process.env.FRAGMENTS_CLOUD_URL;
+}
+function hasTsProject(projectRoot) {
+  return existsSync7(join6(projectRoot, "tsconfig.json")) || existsSync7(join6(projectRoot, "tsconfig.app.json"));
+}
+function resolveDataAdapter(config, fileConfig) {
+  const source = config.source ?? fileConfig?.source ?? "auto";
+  const fragmentsJsonPaths = findFragmentsJson(config.projectRoot);
+  const bundleManifestPaths = findBundleManifest(config.projectRoot);
+  const cloudApiKey = resolveCloudApiKey2(config, fileConfig);
+  const cloudUrl = resolveCloudUrl2(fileConfig);
+  switch (source) {
+    case "fragments-json":
+      return { adapter: new FragmentsJsonAdapter(), mode: "fragments-json" };
+    case "cloud":
+      if (!cloudApiKey) {
+        throw new Error(
+          "Cloud source requires a Cloud API key. Pass --cloud-api-key, set FRAGMENTS_API_KEY, or configure cloud.apiKey in ds-mcp.config.json."
+        );
+      }
+      return {
+        adapter: new CloudCatalogAdapter({ apiKey: cloudApiKey, url: cloudUrl }),
+        mode: "cloud"
+      };
+    case "bundle":
+      return { adapter: new BundleAdapter(), mode: "bundle" };
+    case "extract":
+      return { adapter: new AutoExtractionAdapter(), mode: "extract" };
+    case "auto":
+    default:
+      if (fragmentsJsonPaths.length > 0) {
+        return {
+          adapter: new FragmentsJsonAdapter(),
+          mode: "fragments-json"
+        };
+      }
+      if (cloudApiKey) {
+        return {
+          adapter: new CloudCatalogAdapter({
+            apiKey: cloudApiKey,
+            url: cloudUrl
+          }),
+          mode: "cloud"
+        };
+      }
+      if (bundleManifestPaths.length > 0) {
+        return {
+          adapter: new BundleAdapter(),
+          mode: "bundle"
+        };
+      }
+      if (hasTsProject(config.projectRoot)) {
+        return { adapter: new AutoExtractionAdapter(), mode: "extract" };
+      }
+      return {
+        adapter: new FragmentsJsonAdapter(),
+        mode: "fragments-json"
+      };
+  }
+}
+function resolveSearchApiKey(config, fileConfig) {
+  return config.searchApiKey ?? fileConfig?.vectorSearch?.apiKey;
+}
+
+// src/spec-schema.ts
+var UI_SPEC_SCHEMA_URI = "fragments://schemas/govern.schema";
+var UI_SPEC_SCHEMA_NAME = "govern.schema";
+var UI_SPEC_SCHEMA_MIME_TYPE = "application/schema+json";
+var UI_SPEC_SCHEMA_RESOURCE = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: UI_SPEC_SCHEMA_URI,
+  title: "Fragments UI Spec",
+  description: "Input shape accepted by the Fragments govern and validate_and_fix MCP tools.",
+  type: "object",
+  required: ["nodes"],
+  additionalProperties: false,
+  properties: {
+    root: {
+      type: "string",
+      description: "Optional node id to treat as the root. When omitted, top-level nodes are evaluated in order."
+    },
+    metadata: {
+      type: "object",
+      description: "Optional caller metadata. The validator stores and echoes only fields that downstream tools understand.",
+      additionalProperties: true
+    },
+    nodes: {
+      type: "array",
+      description: "Top-level UI nodes. Each node names a component type and may carry props plus nested children.",
+      items: { $ref: "#/$defs/node" }
+    }
+  },
+  $defs: {
+    node: {
+      type: "object",
+      required: ["type"],
+      additionalProperties: false,
+      properties: {
+        id: {
+          type: "string",
+          description: "Stable caller-provided id. Used in violations and fixedSpec patches."
+        },
+        type: {
+          type: "string",
+          description: 'Design-system component name, including compound names such as "DatePicker.Trigger".'
+        },
+        props: {
+          type: "object",
+          description: 'Component props. Put simple text labels in props.children, e.g. { "children": "Save" }.',
+          additionalProperties: true
+        },
+        children: {
+          description: "Nested child nodes, or a string text child for leaf content. Prefer props.children for simple button labels.",
+          oneOf: [
+            { type: "string" },
+            {
+              type: "array",
+              items: {
+                oneOf: [{ type: "string" }, { $ref: "#/$defs/node" }]
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  examples: {
+    valid: [
+      {
+        nodes: [
+          {
+            id: "save",
+            type: "Button",
+            props: { variant: "primary", children: "Save" }
+          }
+        ]
+      },
+      {
+        root: "card",
+        metadata: { source: "agent-draft" },
+        nodes: [
+          {
+            id: "card",
+            type: "Card",
+            props: {},
+            children: [
+              {
+                id: "title",
+                type: "Heading",
+                props: { level: 2, children: "Billing" }
+              },
+              {
+                id: "submit",
+                type: "Button",
+                props: { children: "Update plan" }
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    invalid: [
+      {
+        reason: "String event handlers are blocked by safety/no-string-handlers.",
+        spec: {
+          nodes: [
+            {
+              id: "danger",
+              type: "Button",
+              props: { children: "Save", onClick: 'alert("saved")' }
+            }
+          ]
+        }
+      },
+      {
+        reason: "Raw CSS values should use design tokens; call tokens.suggest before writing them.",
+        spec: {
+          nodes: [
+            {
+              id: "panel",
+              type: "Box",
+              props: { style: { padding: "6px" } }
+            }
+          ]
+        }
+      }
+    ]
+  },
+  notes: [
+    "Use component names from the active catalog; unknown components fail components/allow.",
+    "Use props.children for simple text labels, especially Button text.",
+    "Do not put JavaScript source strings in event handler props.",
+    "Run validate_and_fix after govern when the verdict asks for revision or deterministic repair."
+  ]
+};
+function serializeUiSpecSchema() {
+  return JSON.stringify(UI_SPEC_SCHEMA_RESOURCE, null, 2);
+}
+
+// src/server.ts
+var TOOL_NAMES = buildToolNames();
+var TOOLS = buildMcpTools();
+var TOOL_DEFINITION_BY_KEY = new Map(
+  MCP_TOOL_DEFINITIONS.map((definition) => [definition.key, definition])
+);
+function createMcpServer(config) {
+  const server = new Server(
+    {
+      name: `${BRAND.nameLower}-mcp`,
+      version: MCP_SERVER_VERSION
+    },
+    {
+      capabilities: {
+        tools: { listChanged: true },
+        resources: { listChanged: false },
+        logging: {}
+      }
+    }
+  );
+  const registry = new ToolRegistry("", {
+    onChanged: () => {
+      server.notification({ method: "notifications/tools/list_changed", params: {} });
+    }
+  });
+  registry.registerBuiltins(
+    { core: CORE_TOOLS, viewer: VIEWER_TOOLS, infra: INFRA_TOOLS },
+    MCP_TOOL_DEFINITIONS,
+    TOOL_CAPABILITIES
+  );
+  const fileConfig = config.fileConfig ?? loadConfigFile(config.projectRoot) ?? void 0;
+  const mergedConfig = {
+    ...fileConfig ? { ...config, fileConfig } : config,
+    searchApiKey: resolveSearchApiKey(config, fileConfig)
+  };
+  const adapter = config.adapter ?? resolveDataAdapter(mergedConfig, fileConfig).adapter;
+  config.onRegistry?.(registry);
+  if (fileConfig?.tools?.exclude) {
+    for (const key of fileConfig.tools.exclude) {
+      registry.unregister(key);
+    }
+  }
+  let cachedData = null;
+  let loadDataPromise = null;
+  let resolvedRoot = null;
+  let resolveProjectRootPromise = null;
+  async function resolveProjectRoot() {
+    if (resolvedRoot) return resolvedRoot;
+    if (resolveProjectRootPromise) return resolveProjectRootPromise;
+    resolveProjectRootPromise = (async () => {
+      if (server.getClientCapabilities()?.roots) {
+        try {
+          const result2 = await server.listRoots();
+          if (result2.roots?.length > 0) {
+            const rootUri = result2.roots[0].uri;
+            resolvedRoot = fileURLToPath(rootUri);
+            return resolvedRoot;
+          }
+        } catch {
+        }
+      }
+      resolvedRoot = config.projectRoot;
+      return resolvedRoot;
+    })();
+    try {
+      return await resolveProjectRootPromise;
+    } finally {
+      resolveProjectRootPromise = null;
+    }
+  }
+  async function loadData() {
+    if (cachedData) return cachedData;
+    if (loadDataPromise) return loadDataPromise;
+    loadDataPromise = (async () => {
+      const projectRoot = await resolveProjectRoot();
+      const loaded = await adapter.load(projectRoot);
+      cachedData = loaded;
+      return loaded;
+    })();
+    try {
+      return await loadDataPromise;
+    } finally {
+      loadDataPromise = null;
+    }
+  }
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const data = await loadData();
+    return {
+      tools: registry.listTools(
+        {
+          hasViewer: false,
+          hasPlayground: false,
+          capabilities: data.capabilities
+        },
+        TOOLS
+      )
+    };
+  });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+      {
+        uri: UI_SPEC_SCHEMA_URI,
+        name: UI_SPEC_SCHEMA_NAME,
+        title: "Fragments govern UI spec schema",
+        description: "JSON schema and examples for the spec argument accepted by govern and validate_and_fix.",
+        mimeType: UI_SPEC_SCHEMA_MIME_TYPE
+      }
+    ]
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri !== UI_SPEC_SCHEMA_URI) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `Unknown resource URI: ${request.params.uri}`
+      );
+    }
+    return {
+      contents: [
+        {
+          uri: UI_SPEC_SCHEMA_URI,
+          mimeType: UI_SPEC_SCHEMA_MIME_TYPE,
+          text: serializeUiSpecSchema()
+        }
+      ]
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const data = await loadData();
+    const toolContext = {
+      data,
+      config: mergedConfig,
+      indexes: { componentIndex: null, blockIndex: null, tokenIndex: null },
+      mcp: {
+        server,
+        clientCapabilities: server.getClientCapabilities()
+      },
+      resolvePackageName: (name2) => {
+        if (name2) {
+          const pkg = data.packageMap[name2];
+          if (pkg) return pkg;
+        }
+        if (data.defaultPackageName) return data.defaultPackageName;
+        if (data.snapshot.sourceType === "cloud") {
+          return "your-component-library";
+        }
+        const root = resolvedRoot ?? config.projectRoot;
+        const packageJsonPath = join7(root, "package.json");
+        if (existsSync8(packageJsonPath)) {
+          try {
+            const content = readFileSync6(packageJsonPath, "utf-8");
+            const pkg = JSON.parse(content);
+            if (pkg.name) {
+              return pkg.name;
+            }
+          } catch {
+          }
+        }
+        return "your-component-library";
+      },
+      toolNames: TOOL_NAMES
+    };
+    try {
+      const toolKey = registry.resolveKey(name);
+      const definition = TOOL_DEFINITION_BY_KEY.get(toolKey);
+      const argumentKeys = Object.keys(args ?? {});
+      const allowedKeys = new Set(Object.keys(definition?.params ?? {}));
+      const unknownKeys = definition ? argumentKeys.filter((key) => !allowedKeys.has(key)) : [];
+      if (unknownKeys.length > 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: `Unknown argument(s) for ${toolKey}: ${unknownKeys.join(", ")}`
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const mCtx = {
+        toolName: name,
+        toolKey,
+        args: args ?? {},
+        ctx: toolContext
+      };
+      return await executeWithMiddleware(
+        config.middleware ?? [],
+        mCtx,
+        () => registry.execute(name, args ?? {}, toolContext)
+      );
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: error instanceof Error ? error.message : String(error) }) }],
+        isError: true
+      };
+    }
+  });
+  return server;
+}
+async function startMcpServer(config) {
+  const server = createMcpServer(config);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+function createSandboxServer() {
+  return createMcpServer({ projectRoot: process.cwd() });
+}
+
+export {
+  loadConfigFile,
+  CORE_TOOLS,
+  VIEWER_TOOLS,
+  INFRA_TOOLS,
+  BUILTIN_TOOLS,
+  ToolRegistry,
+  executeWithMiddleware,
+  telemetryMiddleware,
+  componentFromCompiledFragment,
+  blockFromCompiledBlock,
+  tokensFromCompiledTokenData,
+  buildCapabilities,
+  validateSnapshot,
+  FragmentsJsonAdapter,
+  AutoExtractionAdapter,
+  resolveDataAdapter,
+  resolveSearchApiKey,
+  createMcpServer,
+  startMcpServer,
+  createSandboxServer
+};
+//# sourceMappingURL=chunk-YJTMK4JY.js.map