@fragments-sdk/mcp 0.6.0 → 0.6.2

package/dist/chunk-WBOVO43F.js

@@ -0,0 +1,2481 @@
+import {
+  BRAND,
+  DEFAULTS
+} from "./chunk-4SVS3AA3.js";
+import {
+  loadConfigFile
+} from "./chunk-FGIBLPSU.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { existsSync as existsSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
+import { join as join3 } from "path";
+import { fileURLToPath } from "url";
+import { buildMcpTools, buildToolNames, MCP_TOOL_DEFINITIONS } from "@fragments-sdk/context/mcp-tools";
+
+// src/orama-index.ts
+import { create, insertMultiple, search } from "@orama/orama";
+var SYNONYM_MAP = {
+  "form": ["input", "field", "submit", "validation"],
+  "input": ["form", "field", "text", "entry"],
+  "button": ["action", "click", "submit", "trigger"],
+  "action": ["button", "click", "trigger"],
+  "submit": ["button", "form", "action", "send"],
+  "alert": ["notification", "message", "warning", "error", "feedback"],
+  "notification": ["alert", "message", "toast"],
+  "feedback": ["form", "comment", "review", "rating"],
+  "card": ["container", "panel", "box", "content"],
+  "toggle": ["switch", "checkbox", "boolean", "on/off"],
+  "switch": ["toggle", "checkbox", "boolean"],
+  "badge": ["tag", "label", "status", "indicator"],
+  "status": ["badge", "indicator", "state"],
+  "login": ["auth", "signin", "authentication", "form"],
+  "auth": ["login", "signin", "authentication"],
+  "chat": ["message", "conversation", "ai"],
+  "table": ["data", "grid", "list", "rows"],
+  "textarea": ["text", "input", "multiline", "area", "comment"],
+  "area": ["textarea", "multiline", "text"],
+  "landing": ["page", "hero", "marketing", "section", "layout"],
+  "hero": ["landing", "marketing", "banner", "headline", "section"],
+  "marketing": ["landing", "hero", "pricing", "testimonial", "cta"],
+  "cta": ["marketing", "banner", "action", "button"],
+  "testimonial": ["marketing", "review", "quote", "feedback"],
+  "layout": ["stack", "grid", "box", "container", "page"],
+  "page": ["layout", "landing", "section", "container"],
+  "section": ["hero", "feature", "testimonial", "cta", "faq"],
+  "pricing": ["card", "plan", "tier", "marketing"],
+  "plan": ["pricing", "card", "tier", "subscription"],
+  "dashboard": ["metrics", "stats", "chart", "card", "grid"],
+  "metrics": ["dashboard", "stats", "progress", "number"],
+  "stats": ["metrics", "dashboard", "progress", "badge"],
+  "chart": ["dashboard", "metrics", "data", "graph"]
+};
+function expandQuery(query) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const expanded = new Set(terms);
+  for (const term of terms) {
+    const synonyms = SYNONYM_MAP[term];
+    if (synonyms) {
+      for (const syn of synonyms) expanded.add(syn);
+    }
+  }
+  return Array.from(expanded).join(" ");
+}
+function twoPassSearch(config) {
+  const { index, query, properties, boost, limit, kind } = config;
+  const baseConfig = {
+    mode: "fulltext",
+    properties,
+    boost,
+    limit
+  };
+  const originalTermsQuery = query.toLowerCase().split(/\s+/).filter(Boolean).join(" ");
+  const expandedQuery = expandQuery(query);
+  const originalResults = search(index, { term: originalTermsQuery, ...baseConfig, threshold: 0.8 });
+  const expandedResults = search(index, { term: expandedQuery, ...baseConfig, threshold: 1 });
+  const origHits = originalResults.hits;
+  const expHits = expandedResults.hits;
+  const scoreMap = /* @__PURE__ */ new Map();
+  for (const hit of origHits) {
+    scoreMap.set(hit.document.name, (hit.score || 0) * 2);
+  }
+  for (const hit of expHits) {
+    const name = hit.document.name;
+    const existing = scoreMap.get(name) ?? 0;
+    scoreMap.set(name, existing + (hit.score || 0));
+  }
+  const scored = [];
+  for (const [name, score] of scoreMap) {
+    if (score > 0) {
+      scored.push({ name, kind, rank: scored.length, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  scored.forEach((s, i) => {
+    s.rank = i;
+  });
+  return scored;
+}
+var componentSchema = {
+  name: "string",
+  description: "string",
+  category: "string",
+  tags: "string",
+  whenUsed: "string",
+  variants: "string",
+  status: "string"
+};
+function buildComponentIndex(fragments) {
+  const db = create({ schema: componentSchema, language: "english" });
+  const docs = fragments.map((f) => ({
+    name: f.meta.name,
+    description: f.meta.description ?? "",
+    category: f.meta.category ?? "",
+    tags: (f.meta.tags ?? []).join(" "),
+    whenUsed: (f.usage?.when ?? []).join(" "),
+    variants: f.variants.map((v) => `${v.name} ${v.description || ""}`).join(" "),
+    status: f.meta.status ?? "stable"
+  }));
+  insertMultiple(db, docs);
+  return db;
+}
+function searchComponents(query, index, fragments, limit = 50) {
+  const boostConfig = {
+    mode: "fulltext",
+    properties: ["name", "whenUsed", "description", "category", "tags", "variants"],
+    boost: {
+      name: 3,
+      whenUsed: 2.5,
+      description: 2,
+      category: 1.5,
+      tags: 1.5,
+      variants: 1
+    },
+    limit
+  };
+  const originalTermsList = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const originalTermsQuery = originalTermsList.join(" ");
+  const expandedQuery = expandQuery(query);
+  const originalResults = search(index, { term: originalTermsQuery, ...boostConfig, threshold: 0.8 });
+  const expandedResults = search(index, { term: expandedQuery, ...boostConfig, threshold: 1 });
+  const origHits = originalResults.hits;
+  const expHits = expandedResults.hits;
+  const scoreMap = /* @__PURE__ */ new Map();
+  for (const hit of origHits) {
+    scoreMap.set(hit.document.name, (hit.score || 0) * 2);
+  }
+  for (const hit of expHits) {
+    const name = hit.document.name;
+    const existing = scoreMap.get(name) ?? 0;
+    scoreMap.set(name, existing + (hit.score || 0));
+  }
+  const fragmentMap = /* @__PURE__ */ new Map();
+  for (const f of fragments) {
+    fragmentMap.set(f.meta.name.toLowerCase(), f);
+  }
+  const originalTermsSet = new Set(originalTermsList);
+  const scored = [];
+  for (const [name, rawScore] of scoreMap) {
+    let score = rawScore;
+    const nameLower = name.toLowerCase();
+    const fragment = fragmentMap.get(nameLower);
+    if (originalTermsSet.has(nameLower)) {
+      score += 25;
+    }
+    if (fragment) {
+      if (fragment.meta.status === "stable") score += 5;
+      else if (fragment.meta.status === "beta") score += 2;
+      if (fragment.meta.status === "deprecated") score -= 25;
+    }
+    if (score > 0) {
+      scored.push({ name, kind: "component", rank: scored.length, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  scored.forEach((s, i) => {
+    s.rank = i;
+  });
+  return scored;
+}
+var blockSchema = {
+  name: "string",
+  description: "string",
+  category: "string",
+  tags: "string",
+  components: "string"
+};
+function buildBlockIndex(blocks) {
+  const db = create({ schema: blockSchema, language: "english" });
+  const docs = blocks.map((b) => ({
+    name: b.name,
+    description: b.description ?? "",
+    category: b.category ?? "",
+    tags: (b.tags ?? []).join(" "),
+    components: b.components.join(" ")
+  }));
+  insertMultiple(db, docs);
+  return db;
+}
+function searchBlocks(query, index, limit = 50) {
+  return twoPassSearch({
+    index,
+    query,
+    properties: ["name", "description", "components", "tags", "category"],
+    boost: {
+      name: 3,
+      description: 2,
+      components: 1.5,
+      tags: 1.5,
+      category: 1.5
+    },
+    limit,
+    kind: "block"
+  });
+}
+var tokenSchema = {
+  name: "string",
+  category: "string",
+  description: "string"
+};
+function buildTokenIndex(tokenData) {
+  const db = create({ schema: tokenSchema, language: "english" });
+  const docs = [];
+  for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+    for (const token of tokens) {
+      docs.push({
+        name: token.name,
+        category: cat,
+        description: token.description ?? ""
+      });
+    }
+  }
+  insertMultiple(db, docs);
+  return db;
+}
+function searchTokens(query, index, limit = 50) {
+  return twoPassSearch({
+    index,
+    query,
+    properties: ["name", "category", "description"],
+    boost: {
+      name: 2.5,
+      category: 2,
+      description: 1.5
+    },
+    limit,
+    kind: "token"
+  });
+}
+var USE_CASE_TOKEN_CATEGORIES = {
+  "table": ["spacing", "borders", "surfaces", "text"],
+  "data": ["spacing", "borders", "surfaces"],
+  "grid": ["spacing", "layout"],
+  "form": ["spacing", "borders", "radius", "focus"],
+  "input": ["spacing", "borders", "radius", "focus"],
+  "card": ["surfaces", "shadows", "radius", "borders", "spacing"],
+  "button": ["colors", "radius", "spacing", "focus"],
+  "layout": ["spacing", "layout", "surfaces"],
+  "dashboard": ["spacing", "surfaces", "borders", "shadows"],
+  "chat": ["spacing", "surfaces", "radius", "shadows"],
+  "modal": ["shadows", "surfaces", "radius", "spacing"],
+  "dialog": ["shadows", "surfaces", "radius", "spacing"],
+  "navigation": ["spacing", "surfaces", "borders"],
+  "sidebar": ["spacing", "surfaces", "borders"],
+  "hero": ["spacing", "typography", "colors"],
+  "landing": ["spacing", "typography", "colors"],
+  "pricing": ["spacing", "surfaces", "borders", "radius"],
+  "auth": ["spacing", "borders", "radius", "focus"],
+  "login": ["spacing", "borders", "radius", "focus"],
+  "dark": ["colors", "surfaces"],
+  "theme": ["colors", "surfaces", "text"]
+};
+function extractTokenCategories(query) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const categories = /* @__PURE__ */ new Set();
+  for (const term of terms) {
+    const cats = USE_CASE_TOKEN_CATEGORIES[term];
+    if (cats) {
+      for (const cat of cats) categories.add(cat);
+    }
+  }
+  if (categories.size === 0) {
+    return ["spacing", "colors", "surfaces"];
+  }
+  return Array.from(categories);
+}
+
+// src/adapters/fragments-json.ts
+import { readFile } from "fs/promises";
+
+// src/discovery.ts
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join, 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(join(d, entry.name));
+            }
+          }
+        } catch {
+        }
+      } else {
+        const candidate = join(d, part);
+        if (existsSync(candidate)) next.push(candidate);
+      }
+    }
+    dirs = next;
+  }
+  return dirs;
+}
+function getWorkspaceDirs(rootDir) {
+  const dirs = [];
+  const rootPkgPath = join(rootDir, "package.json");
+  if (existsSync(rootPkgPath)) {
+    try {
+      const rootPkg = JSON.parse(readFileSync(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 = join(rootDir, "pnpm-workspace.yaml");
+  if (existsSync(pnpmWsPath)) {
+    try {
+      const content = readFileSync(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 = join(dir, "package.json");
+      if (existsSync(candidate)) {
+        const pkg = JSON.parse(readFileSync(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 = join(dir, "package.json");
+  if (!existsSync(pkgJsonPath)) return;
+  try {
+    const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+    const allDeps = {
+      ...pkgJson.dependencies,
+      ...pkgJson.devDependencies
+    };
+    const localRequire = createRequire(join(dir, "noop.js"));
+    for (const depName of Object.keys(allDeps)) {
+      try {
+        const depPkgPath = resolveDepPackageJson(localRequire, depName);
+        if (!depPkgPath) continue;
+        const depPkg = JSON.parse(readFileSync(depPkgPath, "utf-8"));
+        if (depPkg[depField]) {
+          const fragmentsPath = join(dirname(depPkgPath), depPkg[depField]);
+          if (existsSync(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 = join(dir, outFile);
+    if (existsSync(candidate)) {
+      found.push(candidate);
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  findFragmentsInDeps(resolvedStart, found, depField);
+  if (found.length === 0 || existsSync(join(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");
+}
+
+// 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 = /* @__PURE__ */ new Map();
+    if (primary.packageName) {
+      for (const name of Object.keys(primary.fragments)) {
+        packageMap.set(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.set(name, extra.packageName);
+        }
+      }
+      Object.assign(primary.fragments, extra.fragments);
+      const extraBlocks = extra.blocks ?? extra.recipes;
+      if (extraBlocks) {
+        primary.blocks = { ...primary.blocks, ...extraBlocks };
+      }
+    }
+    return {
+      components: primary.fragments,
+      blocks: primary.blocks,
+      tokens: primary.tokens,
+      graph: primary.graph,
+      performanceSummary: primary.performanceSummary,
+      packageMap,
+      defaultPackageName: primary.packageName
+    };
+  }
+};
+
+// 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/tools/discover.ts
+import { generateContext, filterPlaceholders } from "@fragments-sdk/context/generate";
+
+// src/search.ts
+var CONVEX_SEARCH_URL = "https://combative-jay-834.convex.site/search";
+var CONVEX_TIMEOUT_MS = 3e3;
+async function searchConvex(query, apiKey, limit = 10, kind) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CONVEX_TIMEOUT_MS);
+    const response = await fetch(CONVEX_SEARCH_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({ query, limit, ...kind && { kind } }),
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    if (!response.ok) {
+      return [];
+    }
+    const data = await response.json();
+    return data.results.map((r, i) => ({
+      name: r.name,
+      kind: r.kind ?? "component",
+      rank: i,
+      score: r.score
+    }));
+  } catch {
+    return [];
+  }
+}
+function keywordScoreComponents(query, fragments, componentIndex) {
+  const index = componentIndex ?? buildComponentIndex(fragments);
+  return searchComponents(query, index, fragments);
+}
+function keywordScoreBlocks(query, blocks, blockIndex) {
+  const index = blockIndex ?? buildBlockIndex(blocks);
+  return searchBlocks(query, index);
+}
+function keywordScoreTokens(query, tokenData, tokenIndex) {
+  const index = tokenIndex ?? buildTokenIndex(tokenData);
+  return searchTokens(query, index);
+}
+function reciprocalRankFusion(resultSets, k = 60) {
+  const scoreMap = /* @__PURE__ */ new Map();
+  for (const { results } of resultSets) {
+    for (let rank = 0; rank < results.length; rank++) {
+      const result = results[rank];
+      const key = `${result.kind}:${result.name}`;
+      const rrfScore = 1 / (k + rank + 1);
+      const existing = scoreMap.get(key);
+      if (existing) {
+        existing.score += rrfScore;
+      } else {
+        scoreMap.set(key, { score: rrfScore, kind: result.kind, name: result.name });
+      }
+    }
+  }
+  const fused = [];
+  for (const [, { score, kind, name }] of scoreMap) {
+    fused.push({ name, kind, rank: 0, score });
+  }
+  fused.sort((a, b) => b.score - a.score);
+  fused.forEach((r, i) => {
+    r.rank = i;
+  });
+  return fused;
+}
+async function hybridSearch(query, data, limit = 10, kind, apiKey) {
+  const keywordResults = [];
+  if (!kind || kind === "component") {
+    keywordResults.push(...keywordScoreComponents(query, data.fragments, data.componentIndex));
+  }
+  if ((!kind || kind === "block") && data.blocks) {
+    keywordResults.push(...keywordScoreBlocks(query, data.blocks, data.blockIndex));
+  }
+  if ((!kind || kind === "token") && data.tokenData) {
+    keywordResults.push(...keywordScoreTokens(query, data.tokenData, data.tokenIndex));
+  }
+  keywordResults.sort((a, b) => b.score - a.score);
+  keywordResults.forEach((r, i) => {
+    r.rank = i;
+  });
+  if (!apiKey) {
+    return keywordResults.slice(0, limit);
+  }
+  const vectorResults = await searchConvex(query, apiKey, limit, kind);
+  if (vectorResults.length === 0) {
+    return keywordResults.slice(0, limit);
+  }
+  const graphBoostResults = [];
+  if (data.graph) {
+    try {
+      const { ComponentGraphEngine: ComponentGraphEngine2, deserializeGraph: deserializeGraph2 } = await import("@fragments-sdk/context/graph");
+      const graph = deserializeGraph2(data.graph);
+      const engine = new ComponentGraphEngine2(graph);
+      const topComponents = [...keywordResults, ...vectorResults].filter((r) => r.kind === "component").slice(0, 5);
+      const neighborSet = /* @__PURE__ */ new Set();
+      for (const result of topComponents) {
+        const neighbors = engine.neighbors(result.name, 1);
+        for (const n of neighbors.neighbors) {
+          if (!neighborSet.has(n.component)) {
+            neighborSet.add(n.component);
+            graphBoostResults.push({
+              name: n.component,
+              kind: "component",
+              rank: graphBoostResults.length,
+              score: 1
+              // Will be normalized through RRF
+            });
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  const resultSets = [
+    { label: "vector", results: vectorResults },
+    { label: "keyword", results: keywordResults }
+  ];
+  if (graphBoostResults.length > 0) {
+    resultSets.push({ label: "graph", results: graphBoostResults });
+  }
+  const fused = reciprocalRankFusion(resultSets);
+  return fused.slice(0, limit);
+}
+
+// src/scoring.ts
+var MINIMUM_SCORE_THRESHOLD = 5;
+function assignConfidence(score, maxScore) {
+  if (maxScore <= 0) return "low";
+  const ratio = score / maxScore;
+  if (ratio >= 0.7) return "high";
+  if (ratio >= 0.4) return "medium";
+  return "low";
+}
+function meetsMinimumThreshold(maxScore) {
+  return maxScore >= MINIMUM_SCORE_THRESHOLD;
+}
+function levenshtein(a, b) {
+  const la = a.length;
+  const lb = b.length;
+  const dp = Array.from({ length: lb + 1 }, (_, i) => i);
+  for (let i = 1; i <= la; i++) {
+    let prev = i - 1;
+    dp[0] = i;
+    for (let j = 1; j <= lb; j++) {
+      const temp = dp[j];
+      dp[j] = a[i - 1] === b[j - 1] ? prev : 1 + Math.min(prev, dp[j], dp[j - 1]);
+      prev = temp;
+    }
+  }
+  return dp[lb];
+}
+function findClosestMatch(input, candidates, maxDistance = 3) {
+  const inputLower = input.toLowerCase();
+  let bestMatch = null;
+  let bestDist = maxDistance + 1;
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+    const dist = levenshtein(inputLower, candidateLower);
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestMatch = candidate;
+    } else if (dist === bestDist && bestMatch) {
+      const currentLenDiff = Math.abs(bestMatch.length - input.length);
+      const newLenDiff = Math.abs(candidate.length - input.length);
+      if (newLenDiff < currentLenDiff) {
+        bestMatch = candidate;
+      }
+    }
+  }
+  return bestDist <= maxDistance ? bestMatch : null;
+}
+var BLOCK_BOOST_PER_OCCURRENCE = 5;
+function buildBlockComponentFrequency(blocks) {
+  const freq = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    for (const comp of block.components) {
+      const key = comp.toLowerCase();
+      freq.set(key, (freq.get(key) ?? 0) + 1);
+    }
+  }
+  return freq;
+}
+function boostByBlockFrequency(results, freq) {
+  for (const result of results) {
+    const count = freq.get(result.name.toLowerCase()) ?? 0;
+    if (count > 0) {
+      result.score += count * BLOCK_BOOST_PER_OCCURRENCE;
+    }
+  }
+  results.sort((a, b) => b.score - a.score);
+  results.forEach((r, i) => {
+    r.rank = i;
+  });
+  return results;
+}
+
+// src/server-helpers.ts
+function normalizeFilter(value) {
+  const normalized = value?.trim().toLowerCase();
+  return normalized && normalized.length > 0 ? normalized : void 0;
+}
+function categoryMatches(category, categoryFilter) {
+  if (!categoryFilter) return true;
+  return normalizeFilter(category) === categoryFilter;
+}
+function buildLocalSearchData(data, indexes) {
+  const allFragments = Object.values(data.fragments);
+  const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
+  const localData = {
+    fragments: allFragments,
+    blocks: allBlocks,
+    tokenData: data.tokens,
+    graph: data.graph,
+    componentIndex: indexes.componentIndex ?? void 0,
+    blockIndex: indexes.blockIndex ?? void 0,
+    tokenIndex: indexes.tokenIndex ?? void 0
+  };
+  return { allFragments, allBlocks, localData };
+}
+async function buildImportStatements(components, resolvePackageName) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const component of components) {
+    if (!component) continue;
+    const packageName = await resolvePackageName(component);
+    const existing = grouped.get(packageName);
+    if (!existing) {
+      grouped.set(packageName, [component]);
+      continue;
+    }
+    if (!existing.includes(component)) {
+      existing.push(component);
+    }
+  }
+  return Array.from(grouped.entries()).map(
+    ([packageName, componentNames]) => `import { ${componentNames.join(", ")} } from '${packageName}';`
+  );
+}
+function limitTokensPerCategory(categories, limit) {
+  if (limit === void 0) {
+    return {
+      categories,
+      total: Object.values(categories).reduce((sum, tokens) => sum + tokens.length, 0)
+    };
+  }
+  const limited = {};
+  let total = 0;
+  for (const [category, tokens] of Object.entries(categories)) {
+    const sliced = tokens.slice(0, limit);
+    if (sliced.length === 0) continue;
+    limited[category] = sliced;
+    total += sliced.length;
+  }
+  return { categories: limited, total };
+}
+
+// src/tools/discover.ts
+var discoverHandler = async (args, ctx) => {
+  const data = ctx.data;
+  const useCase = args?.useCase ?? void 0;
+  const componentForAlts = args?.component ?? void 0;
+  const category = normalizeFilter(args?.category);
+  const search2 = args?.search?.toLowerCase() ?? void 0;
+  const status = args?.status ?? void 0;
+  const format = args?.format ?? "markdown";
+  const compact = args?.compact ?? false;
+  const includeCode = args?.includeCode ?? false;
+  const includeRelations = args?.includeRelations ?? false;
+  const limit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 25) : 10;
+  const verbosity = args?.verbosity ?? "standard";
+  if (compact || args?.format && !useCase && !componentForAlts) {
+    let fragments2 = Object.values(data.components);
+    const allBlocks = Object.values(data.blocks ?? {});
+    if (category) {
+      fragments2 = fragments2.filter((f) => categoryMatches(f.meta.category, category));
+    }
+    if (search2) {
+      fragments2 = fragments2.filter(
+        (f) => f.meta.name.toLowerCase().includes(search2) || f.meta.description?.toLowerCase().includes(search2) || f.meta.tags?.some((t) => t.toLowerCase().includes(search2))
+      );
+    }
+    if (status) {
+      fragments2 = fragments2.filter((f) => f.meta.status === status);
+    }
+    const { content: ctxContent, tokenEstimate } = generateContext(fragments2, {
+      format,
+      compact,
+      include: {
+        code: includeCode,
+        relations: includeRelations
+      }
+    }, allBlocks);
+    return {
+      content: [{ type: "text", text: ctxContent }],
+      _meta: { tokenEstimate }
+    };
+  }
+  if (useCase) {
+    const { allFragments, allBlocks, localData } = buildLocalSearchData(
+      {
+        fragments: data.components,
+        blocks: data.blocks,
+        tokens: data.tokens,
+        graph: data.graph
+      },
+      {
+        componentIndex: ctx.indexes.componentIndex,
+        blockIndex: ctx.indexes.blockIndex,
+        tokenIndex: ctx.indexes.tokenIndex
+      }
+    );
+    const context = args?.context?.toLowerCase() ?? "";
+    const fullQuery = context ? `${useCase} ${context}` : useCase;
+    const searchResults = await hybridSearch(fullQuery, localData, limit, "component", ctx.config.apiKey);
+    const blockMatches = keywordScoreBlocks(fullQuery, allBlocks, ctx.indexes.blockIndex ?? void 0).slice(0, 5);
+    if (blockMatches.length > 0) {
+      const matchedBlocks = blockMatches.map((bm) => allBlocks.find((b) => b.name.toLowerCase() === bm.name.toLowerCase())).filter(Boolean);
+      const blockFreq = buildBlockComponentFrequency(matchedBlocks);
+      boostByBlockFrequency(searchResults, blockFreq);
+    }
+    const maxScore = searchResults.length > 0 ? searchResults[0].score : 0;
+    const scored = searchResults.map((result) => {
+      const fragment = allFragments.find(
+        (s) => s.meta.name.toLowerCase() === result.name.toLowerCase()
+      );
+      if (!fragment) return null;
+      const filteredWhen = filterPlaceholders(fragment.usage?.when).slice(0, 3);
+      const filteredWhenNot = filterPlaceholders(fragment.usage?.whenNot).slice(0, 2);
+      return {
+        component: fragment.meta.name,
+        category: fragment.meta.category,
+        description: fragment.meta.description,
+        confidence: assignConfidence(result.score, maxScore),
+        reasons: [`Matched via hybrid search (score: ${result.score.toFixed(4)})`],
+        usage: { when: filteredWhen, whenNot: filteredWhenNot },
+        variantCount: fragment.variants.length,
+        status: fragment.meta.status
+      };
+    }).filter(Boolean);
+    const suggestions = [];
+    const categoryCount = {};
+    for (const item of scored) {
+      if (!item) continue;
+      const cat = item.category || "uncategorized";
+      const count = categoryCount[cat] || 0;
+      if (count < 2 || suggestions.length < 3) {
+        suggestions.push(item);
+        categoryCount[cat] = count + 1;
+        if (suggestions.length >= limit) break;
+      }
+    }
+    const compositionHint = suggestions.length >= 2 ? `These components work well together. For example, ${suggestions[0].component} can be combined with ${suggestions.slice(1, 3).map((s) => s.component).join(" and ")}.` : void 0;
+    const useCaseLower = useCase.toLowerCase();
+    const STYLE_KEYWORDS = ["color", "spacing", "padding", "margin", "font", "border", "radius", "shadow", "variable", "token", "css", "theme", "dark mode", "background", "hover"];
+    const isStyleQuery = STYLE_KEYWORDS.some((kw) => useCaseLower.includes(kw));
+    const noMatch = suggestions.length === 0;
+    const belowThreshold = !noMatch && maxScore > 1 && !meetsMinimumThreshold(maxScore);
+    const weakMatch = !noMatch && (belowThreshold || suggestions.every((s) => s.confidence === "low"));
+    let recommendation;
+    let nextStep;
+    if (noMatch) {
+      recommendation = isStyleQuery ? `No matching components found. Your query seems styling-related \u2014 try ${ctx.toolNames.tokens} to find CSS custom properties.` : `No matching components found. Try different keywords or browse all components with ${ctx.toolNames.discover}.`;
+      nextStep = isStyleQuery ? `Use ${ctx.toolNames.tokens}(search: "${useCaseLower.split(/\s+/)[0]}") to find design tokens.` : void 0;
+    } else if (weakMatch) {
+      recommendation = `Weak matches only \u2014 ${suggestions[0].component} might work but confidence is low.${isStyleQuery ? ` If you need a CSS variable, try ${ctx.toolNames.tokens}.` : ""}`;
+      nextStep = `Use ${ctx.toolNames.inspect}("${suggestions[0].component}") to check if it fits, or try broader search terms.`;
+    } else {
+      recommendation = `Best match: ${suggestions[0].component} (${suggestions[0].confidence} confidence) - ${suggestions[0].description}`;
+      nextStep = `Use ${ctx.toolNames.inspect}("${suggestions[0].component}") for full details.`;
+    }
+    const tokenHint = isStyleQuery && !noMatch ? `Your query includes styling terms. For CSS custom properties, also try ${ctx.toolNames.tokens}(search: "${useCaseLower.split(/\s+/)[0]}").` : void 0;
+    const blockNames = blockMatches.map((bm) => allBlocks.find((b) => b.name.toLowerCase() === bm.name.toLowerCase())).filter(Boolean).slice(0, 3).map((b) => b.name);
+    const blockHint = blockNames.length > 0 ? `Related blocks: ${blockNames.join(", ")}. Use ${ctx.toolNames.blocks}(search: "${useCase}") for ready-to-use patterns.` : void 0;
+    const suggestResponse = verbosity === "compact" ? {
+      useCase,
+      suggestions: suggestions.map((s) => ({
+        component: s.component,
+        description: s.description,
+        confidence: s.confidence
+      })),
+      recommendation
+    } : {
+      useCase,
+      context: context || void 0,
+      suggestions,
+      noMatch,
+      weakMatch,
+      recommendation,
+      compositionHint,
+      ...tokenHint && { tokenHint },
+      ...blockHint && { blockHint },
+      nextStep
+    };
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify(suggestResponse)
+      }]
+    };
+  }
+  if (componentForAlts) {
+    const fragment = Object.values(data.components).find(
+      (s) => s.meta.name.toLowerCase() === componentForAlts.toLowerCase()
+    );
+    if (!fragment) {
+      const allNames = Object.values(data.components).map((s) => s.meta.name);
+      const closest = findClosestMatch(componentForAlts, allNames);
+      const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+      throw new Error(`Component "${componentForAlts}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`);
+    }
+    const relations = fragment.relations ?? [];
+    const referencedBy = Object.values(data.components).filter(
+      (s) => s.relations?.some((r) => r.component.toLowerCase() === componentForAlts.toLowerCase())
+    ).map((s) => ({
+      component: s.meta.name,
+      relationship: s.relations?.find(
+        (r) => r.component.toLowerCase() === componentForAlts.toLowerCase()
+      )?.relationship,
+      note: s.relations?.find(
+        (r) => r.component.toLowerCase() === componentForAlts.toLowerCase()
+      )?.note
+    }));
+    const sameCategory = Object.values(data.components).filter(
+      (s) => s.meta.category === fragment.meta.category && s.meta.name.toLowerCase() !== componentForAlts.toLowerCase()
+    ).map((s) => ({
+      component: s.meta.name,
+      description: s.meta.description
+    }));
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          component: fragment.meta.name,
+          category: fragment.meta.category,
+          directRelations: relations,
+          referencedBy,
+          sameCategory,
+          suggestion: relations.find((r) => r.relationship === "alternative") ? `Consider ${relations.find((r) => r.relationship === "alternative")?.component}: ${relations.find((r) => r.relationship === "alternative")?.note}` : void 0
+        })
+      }]
+    };
+  }
+  const fragments = Object.values(data.components).filter((s) => {
+    if (category && !categoryMatches(s.meta.category, category)) return false;
+    if (status && (s.meta.status ?? "stable") !== status) return false;
+    if (search2) {
+      const nameMatch = s.meta.name.toLowerCase().includes(search2);
+      const descMatch = s.meta.description?.toLowerCase().includes(search2);
+      const tagMatch = s.meta.tags?.some((t) => t.toLowerCase().includes(search2));
+      if (!nameMatch && !descMatch && !tagMatch) return false;
+    }
+    return true;
+  }).map((s) => {
+    if (verbosity === "compact") {
+      return {
+        name: s.meta.name,
+        category: s.meta.category,
+        ...s.propsSummary?.length && { propsSummary: s.propsSummary },
+        ...s.contract?.propsSummary?.length && !s.propsSummary?.length && { propsSummary: s.contract.propsSummary }
+      };
+    }
+    return {
+      name: s.meta.name,
+      category: s.meta.category,
+      description: s.meta.description,
+      status: s.meta.status ?? "stable",
+      variantCount: s.variants.length,
+      tags: s.meta.tags ?? [],
+      ...(includeCode || verbosity === "full") && s.variants[0]?.code && {
+        example: s.variants[0].code
+      }
+    };
+  });
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        total: fragments.length,
+        fragments,
+        categories: [...new Set(fragments.map((s) => s.category))],
+        hint: fragments.length === 0 ? "No components found. Try broader search terms or check available categories." : fragments.length > 5 ? `Use ${ctx.toolNames.discover} with useCase for recommendations, or ${ctx.toolNames.inspect} for details on a specific component.` : void 0
+      })
+    }]
+  };
+};
+
+// src/tools/inspect.ts
+import { readFileSync as readFileSync3, existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/utils.ts
+function projectFields(obj, fields) {
+  if (!fields || fields.length === 0) {
+    return obj;
+  }
+  const result = {};
+  for (const field of fields) {
+    const parts = field.split(".");
+    let source = obj;
+    let target = result;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const isLast = i === parts.length - 1;
+      if (source === null || source === void 0 || typeof source !== "object") {
+        break;
+      }
+      const sourceObj = source;
+      const value = sourceObj[part];
+      if (isLast) {
+        target[part] = value;
+      } else {
+        if (!(part in target)) {
+          target[part] = {};
+        }
+        target = target[part];
+        source = value;
+      }
+    }
+  }
+  return result;
+}
+
+// src/tools/inspect.ts
+import { filterPlaceholders as filterPlaceholders2 } from "@fragments-sdk/context/generate";
+function getSourceCode(fragment, projectRoot) {
+  const sourcePath = fragment.sourcePath;
+  if (!sourcePath) return void 0;
+  const fullPath = join2(projectRoot, sourcePath);
+  if (!existsSync2(fullPath)) return { path: sourcePath, code: null };
+  try {
+    const code = readFileSync3(fullPath, "utf-8");
+    return { path: sourcePath, code };
+  } catch {
+    return { path: sourcePath, code: null };
+  }
+}
+var inspectHandler = async (args, ctx) => {
+  const componentName = args?.component;
+  const fields = args?.fields;
+  const variantName = args?.variant ?? void 0;
+  const maxExamples = args?.maxExamples;
+  const maxLines = args?.maxLines;
+  const verbosity = args?.verbosity ?? "standard";
+  if (!componentName) {
+    throw new Error("component is required");
+  }
+  const fragment = Object.values(ctx.data.components).find(
+    (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
+  );
+  if (!fragment) {
+    const allNames = Object.values(ctx.data.components).map((s) => s.meta.name);
+    const closest = findClosestMatch(componentName, allNames);
+    const suggestion = closest ? ` Did you mean "${closest}"? Use ${ctx.toolNames.inspect}("${closest}") to inspect it.` : "";
+    throw new Error(`Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`);
+  }
+  const pkgName = ctx.resolvePackageName(fragment.meta.name);
+  let variants = fragment.variants;
+  if (variantName) {
+    const query = variantName.toLowerCase();
+    let filtered = variants.filter((v) => v.name.toLowerCase() === query);
+    if (filtered.length === 0) {
+      filtered = variants.filter((v) => v.name.toLowerCase().startsWith(query));
+    }
+    if (filtered.length === 0) {
+      filtered = variants.filter((v) => v.name.toLowerCase().includes(query));
+    }
+    if (filtered.length > 0) {
+      variants = filtered;
+    } else {
+      throw new Error(
+        `Variant "${variantName}" not found for ${componentName}. Available: ${fragment.variants.map((v) => v.name).join(", ")}`
+      );
+    }
+  }
+  if (maxExamples && maxExamples > 0) {
+    variants = variants.slice(0, maxExamples);
+  }
+  const truncateCode = (code) => {
+    if (!maxLines || maxLines <= 0) return code;
+    const lines = code.split("\n");
+    if (lines.length <= maxLines) return code;
+    return lines.slice(0, maxLines).join("\n") + "\n// ... truncated";
+  };
+  const examples = variants.map((variant) => {
+    if (variant.code) {
+      return {
+        variant: variant.name,
+        description: variant.description,
+        code: truncateCode(variant.code)
+      };
+    }
+    return {
+      variant: variant.name,
+      description: variant.description,
+      code: `<${fragment.meta.name} />`,
+      note: "No code example provided in fragment. Refer to props for customization."
+    };
+  });
+  const propsReference = Object.entries(fragment.props ?? {}).map(([propName, prop]) => ({
+    name: propName,
+    type: prop.type,
+    required: prop.required,
+    default: prop.default,
+    description: prop.description
+  }));
+  const propConstraints = Object.entries(fragment.props ?? {}).filter(([, prop]) => prop.constraints && prop.constraints.length > 0).map(([pName, prop]) => ({
+    prop: pName,
+    constraints: prop.constraints
+  }));
+  const fullResult = {
+    meta: fragment.meta,
+    props: fragment.props,
+    variants: fragment.variants,
+    relations: fragment.relations,
+    contract: fragment.contract,
+    generated: fragment._generated,
+    guidelines: {
+      when: filterPlaceholders2(fragment.usage?.when),
+      whenNot: filterPlaceholders2(fragment.usage?.whenNot),
+      guidelines: fragment.usage?.guidelines ?? [],
+      accessibility: fragment.usage?.accessibility ?? [],
+      propConstraints,
+      alternatives: fragment.relations?.filter((r) => r.relationship === "alternative").map((r) => ({
+        component: r.component,
+        note: r.note
+      })) ?? []
+    },
+    examples: {
+      import: `import { ${fragment.meta.name} } from '${pkgName}';`,
+      code: examples,
+      propsReference
+    },
+    source: getSourceCode(fragment, ctx.config.projectRoot)
+  };
+  const aliasMap = { "usage": "guidelines" };
+  const resolvedFields = fields?.map((f) => {
+    const parts = f.split(".");
+    if (aliasMap[parts[0]]) parts[0] = aliasMap[parts[0]];
+    return parts.join(".");
+  });
+  let result;
+  if (verbosity === "compact" && !resolvedFields?.length) {
+    result = {
+      meta: fullResult.meta,
+      propsSummary: fragment.propsSummary ?? fragment.contract?.propsSummary ?? Object.keys(fragment.props ?? {}),
+      ...fragment.provenance && { provenance: fragment.provenance }
+    };
+  } else if (verbosity === "full") {
+    result = resolvedFields && resolvedFields.length > 0 ? projectFields(fullResult, resolvedFields) : fullResult;
+  } else {
+    if (resolvedFields && resolvedFields.length > 0) {
+      result = projectFields(fullResult, resolvedFields);
+    } else {
+      const { source: _source, ...withoutSource } = fullResult;
+      result = {
+        ...withoutSource,
+        ...fragment.provenance && { provenance: fragment.provenance },
+        ...fragment.ai && { ai: fragment.ai }
+      };
+    }
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify(result) }]
+  };
+};
+
+// src/tools/blocks.ts
+var blocksHandler = async (args, ctx) => {
+  const blockName = args?.name;
+  const search2 = args?.search?.toLowerCase() ?? void 0;
+  const component = args?.component?.toLowerCase() ?? void 0;
+  const category = args?.category?.toLowerCase() ?? void 0;
+  const blocksLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 50) : search2 ? 10 : void 0;
+  const allBlocks = Object.values(ctx.data.blocks ?? {});
+  if (allBlocks.length === 0) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          total: 0,
+          blocks: [],
+          hint: `No composition blocks found. Blocks are reusable patterns showing how components wire together (e.g., "Login Form", "Settings Page"). Create .block.ts files and run \`${BRAND.cliCommand} build\`.`
+        })
+      }]
+    };
+  }
+  let filtered = allBlocks;
+  if (blockName) {
+    filtered = filtered.filter(
+      (b) => b.name.toLowerCase() === blockName.toLowerCase()
+    );
+    if (filtered.length === 0) {
+      const allBlockNames = allBlocks.map((b) => b.name);
+      const closest = findClosestMatch(blockName, allBlockNames);
+      const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+      throw new Error(`Block "${blockName}" not found.${suggestion} Use ${ctx.toolNames.blocks} to see available blocks.`);
+    }
+  }
+  if (search2) {
+    if (ctx.indexes.blockIndex) {
+      const ranked = searchBlocks(search2, ctx.indexes.blockIndex, 50);
+      const rankedNames = new Set(ranked.map((r) => r.name.toLowerCase()));
+      filtered = filtered.filter((b) => rankedNames.has(b.name.toLowerCase()));
+      filtered.sort((a, b) => {
+        const aIdx = ranked.findIndex((r) => r.name.toLowerCase() === a.name.toLowerCase());
+        const bIdx = ranked.findIndex((r) => r.name.toLowerCase() === b.name.toLowerCase());
+        return (aIdx === -1 ? Infinity : aIdx) - (bIdx === -1 ? Infinity : bIdx);
+      });
+    } else {
+      filtered = filtered.filter((b) => {
+        const haystack = [
+          b.name,
+          b.description,
+          ...b.tags ?? [],
+          ...b.components,
+          b.category
+        ].join(" ").toLowerCase();
+        return haystack.includes(search2);
+      });
+    }
+  }
+  if (component) {
+    filtered = filtered.filter(
+      (b) => b.components.some((c) => c.toLowerCase() === component)
+    );
+  }
+  if (category) {
+    filtered = filtered.filter(
+      (b) => b.category.toLowerCase() === category
+    );
+  }
+  const blocksUseIcons = filtered.some(
+    (b) => b.components.some((c) => c === "Icon") || b.code && /\bIcon\b/.test(b.code)
+  );
+  const iconHint = blocksUseIcons ? "Icon components in block code are from @phosphor-icons/react. Import them as: import { IconName } from '@phosphor-icons/react';" : void 0;
+  if (blocksLimit !== void 0) {
+    filtered = filtered.slice(0, blocksLimit);
+  }
+  const verbosity = args?.verbosity ?? "standard";
+  const blocksWithImports = await Promise.all(filtered.map(async (b) => {
+    const imports = await buildImportStatements(
+      b.components,
+      async (componentName) => ctx.resolvePackageName(componentName)
+    );
+    const base = {
+      name: b.name,
+      description: b.description,
+      category: b.category,
+      components: b.components,
+      tags: b.tags,
+      import: imports.join("\n"),
+      imports
+    };
+    if (verbosity === "compact") return base;
+    if (verbosity === "full") return { ...base, code: b.code };
+    const codeLines = b.code.split("\n");
+    const code = codeLines.length > 30 ? codeLines.slice(0, 20).join("\n") + "\n// ... truncated (" + codeLines.length + " lines total)" : b.code;
+    return { ...base, code };
+  }));
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        total: blocksWithImports.length,
+        blocks: blocksWithImports,
+        ...iconHint && { iconHint },
+        ...blocksWithImports.length === 0 && allBlocks.length > 0 && {
+          hint: "No blocks matching your query. Try broader search terms."
+        }
+      })
+    }]
+  };
+};
+
+// src/tools/tokens.ts
+var tokensHandler = async (args, ctx) => {
+  const category = args?.category?.toLowerCase() ?? void 0;
+  const search2 = args?.search?.toLowerCase() ?? void 0;
+  const tokensLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 100) : search2 ? 25 : void 0;
+  const tokenData = ctx.data.tokens;
+  if (!tokenData || tokenData.total === 0) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          total: 0,
+          categories: {},
+          hint: `No design tokens found. Add a tokens.include pattern to your ${BRAND.configFile} and run \`${BRAND.cliCommand} build\`.`
+        })
+      }]
+    };
+  }
+  let filteredCategories = {};
+  let filteredTotal = 0;
+  const searchMatchesCategory = search2 ? Object.keys(tokenData.categories).find((cat) => cat.toLowerCase() === search2) : void 0;
+  for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+    if (category && cat !== category) continue;
+    let filtered = tokens;
+    if (search2) {
+      if (searchMatchesCategory && cat.toLowerCase() === search2) {
+        filtered = tokens;
+      } else {
+        filtered = tokens.filter(
+          (t) => t.name.toLowerCase().includes(search2) || t.description && t.description.toLowerCase().includes(search2) || cat.toLowerCase().includes(search2)
+        );
+      }
+    }
+    if (filtered.length > 0) {
+      filteredCategories[cat] = filtered;
+      filteredTotal += filtered.length;
+    }
+  }
+  if (tokensLimit !== void 0) {
+    const limited = limitTokensPerCategory(filteredCategories, tokensLimit);
+    filteredCategories = limited.categories;
+    filteredTotal = limited.total;
+  }
+  let hint;
+  if (filteredTotal === 0) {
+    const availableCategories = Object.keys(tokenData.categories);
+    if (category && search2) {
+      const categoryTotal = tokenData.categories[category]?.length ?? 0;
+      hint = categoryTotal > 0 ? `No tokens matching "${search2}" in category "${category}" (${categoryTotal} tokens in this category). Try a broader search or remove the search term.` : `Category "${category}" not found. Available: ${availableCategories.join(", ")}`;
+    } else if (search2) {
+      hint = `No tokens matching "${search2}". Available categories: ${availableCategories.join(", ")}`;
+    } else if (category) {
+      hint = `Category "${category}" not found. Available: ${availableCategories.join(", ")}`;
+    }
+  } else if (!category && !search2) {
+    hint = `Use var(--token-name) in your CSS/styles. Filter by category or search to narrow results.`;
+  }
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        prefix: tokenData.prefix,
+        total: filteredTotal,
+        totalAvailable: tokenData.total,
+        categories: filteredCategories,
+        ...hint && { hint },
+        ...!category && !search2 && {
+          availableCategories: Object.entries(tokenData.categories).map(
+            ([cat, tokens]) => ({ category: cat, count: tokens.length })
+          )
+        }
+      })
+    }]
+  };
+};
+
+// src/tools/implement.ts
+import { filterPlaceholders as filterPlaceholders3 } from "@fragments-sdk/context/generate";
+var implementHandler = async (args, ctx) => {
+  const useCase = args?.useCase;
+  if (!useCase) {
+    throw new Error("useCase is required");
+  }
+  const verbosity = args?.verbosity ?? "standard";
+  const { allFragments, allBlocks, localData } = buildLocalSearchData(
+    {
+      fragments: ctx.data.components,
+      blocks: ctx.data.blocks,
+      tokens: ctx.data.tokens,
+      graph: ctx.data.graph
+    },
+    {
+      componentIndex: ctx.indexes.componentIndex,
+      blockIndex: ctx.indexes.blockIndex,
+      tokenIndex: ctx.indexes.tokenIndex
+    }
+  );
+  const tokenData = ctx.data.tokens;
+  const implLimit = typeof args?.limit === "number" ? Math.min(Math.max(args.limit, 1), 15) : 5;
+  const [componentResults, blockResults, tokenResults] = await Promise.all([
+    hybridSearch(useCase, localData, implLimit * 3, "component", ctx.config.apiKey),
+    hybridSearch(useCase, localData, implLimit, "block", ctx.config.apiKey),
+    hybridSearch(useCase, localData, implLimit, "token", ctx.config.apiKey)
+  ]);
+  const topBlockScore = blockResults.length > 0 ? blockResults[0].score : 0;
+  const filteredBlockResults = blockResults.filter((r) => r.score >= topBlockScore * 0.3);
+  if (filteredBlockResults.length > 0) {
+    const matchedBlocks = filteredBlockResults.map((r) => allBlocks.find((b) => b.name.toLowerCase() === r.name.toLowerCase())).filter(Boolean);
+    const blockFreq = buildBlockComponentFrequency(matchedBlocks);
+    boostByBlockFrequency(componentResults, blockFreq);
+  }
+  const topComponentResults = componentResults.slice(0, implLimit);
+  const maxCompScore = topComponentResults.length > 0 ? topComponentResults[0].score : 0;
+  const topMatches = topComponentResults.map((result) => {
+    const fragment = allFragments.find(
+      (s) => s.meta.name.toLowerCase() === result.name.toLowerCase()
+    );
+    return fragment ? { fragment, score: result.score } : null;
+  }).filter(Boolean);
+  const components = await Promise.all(
+    topMatches.map(async ({ fragment: s, score }) => {
+      const pkgName = ctx.resolvePackageName(s.meta.name);
+      if (verbosity === "compact") {
+        return {
+          name: s.meta.name,
+          description: s.meta.description,
+          confidence: assignConfidence(score, maxCompScore),
+          import: `import { ${s.meta.name} } from '${pkgName}';`
+        };
+      }
+      const exampleLimit = verbosity === "full" ? s.variants.length : 2;
+      const propsLimit = verbosity === "full" ? Object.keys(s.props ?? {}).length : 5;
+      const examples = s.variants.slice(0, exampleLimit).map((v) => ({
+        variant: v.name,
+        code: v.code ?? `<${s.meta.name} />`
+      }));
+      const propsSummary = Object.entries(s.props ?? {}).slice(0, propsLimit).map(
+        ([pName, p]) => `${pName}${p.required ? " (required)" : ""}: ${p.type}${p.values ? ` = ${p.values.join("|")}` : ""}`
+      );
+      return {
+        name: s.meta.name,
+        category: s.meta.category,
+        description: s.meta.description,
+        confidence: assignConfidence(score, maxCompScore),
+        import: `import { ${s.meta.name} } from '${pkgName}';`,
+        props: propsSummary,
+        examples,
+        guidelines: filterPlaceholders3(s.usage?.when).slice(0, 3),
+        accessibility: s.usage?.accessibility?.slice(0, 2) ?? []
+      };
+    })
+  );
+  const matchingBlocks = (await Promise.all(filteredBlockResults.slice(0, 5).map(async (result) => {
+    const block = allBlocks.find(
+      (b) => b.name.toLowerCase() === result.name.toLowerCase()
+    );
+    if (!block) return null;
+    const imports = await buildImportStatements(
+      block.components,
+      async (componentName) => ctx.resolvePackageName(componentName)
+    );
+    const codeLines = block.code.split("\n");
+    const code = codeLines.length > 30 ? codeLines.slice(0, 20).join("\n") + "\n// ... truncated (" + codeLines.length + " lines total)" : block.code;
+    return {
+      name: block.name,
+      description: block.description,
+      components: block.components,
+      code,
+      import: imports.join("\n"),
+      imports
+    };
+  }))).filter(Boolean);
+  let relevantTokens;
+  if (tokenResults.length > 0 && tokenData) {
+    relevantTokens = {};
+    for (const result of tokenResults) {
+      for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+        if (tokens.some((t) => t.name === result.name)) {
+          if (!relevantTokens[cat]) relevantTokens[cat] = [];
+          relevantTokens[cat].push(result.name);
+          break;
+        }
+      }
+    }
+    if (Object.keys(relevantTokens).length === 0) relevantTokens = void 0;
+  }
+  if (!relevantTokens && tokenData) {
+    const categories = extractTokenCategories(useCase);
+    relevantTokens = {};
+    for (const cat of categories) {
+      const tokens = tokenData.categories[cat];
+      if (tokens && tokens.length > 0) {
+        relevantTokens[cat] = tokens.slice(0, 5).map((t) => t.name);
+      }
+    }
+    if (Object.keys(relevantTokens).length === 0) relevantTokens = void 0;
+  }
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        useCase,
+        components,
+        blocks: verbosity !== "compact" && matchingBlocks.length > 0 ? matchingBlocks : void 0,
+        tokens: verbosity !== "compact" ? relevantTokens : void 0,
+        noMatch: components.length === 0,
+        summary: components.length > 0 ? `Found ${components.length} component(s) for "${useCase}". ${matchingBlocks.length > 0 ? `Plus ${matchingBlocks.length} ready-to-use block(s).` : ""}` : `No components match "${useCase}". Try ${ctx.toolNames.discover} with different terms${tokenData ? ` or ${ctx.toolNames.tokens} for CSS variables` : ""}.`
+      })
+    }]
+  };
+};
+
+// src/service.ts
+var DEFAULT_ENDPOINTS = {
+  render: "/fragments/render",
+  compare: "/fragments/compare",
+  fix: "/fragments/fix",
+  a11y: "/fragments/a11y"
+};
+async function renderComponent(viewerUrl, request, endpoints) {
+  const renderUrl = `${viewerUrl}${endpoints?.render ?? DEFAULT_ENDPOINTS.render}`;
+  const response = await fetch(renderUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      component: request.component,
+      props: request.props ?? {},
+      variant: request.variant,
+      viewport: request.viewport ?? { width: 800, height: 600 }
+    })
+  });
+  return await response.json();
+}
+async function compareComponent(viewerUrl, request, endpoints) {
+  const compareUrl = `${viewerUrl}${endpoints?.compare ?? DEFAULT_ENDPOINTS.compare}`;
+  const response = await fetch(compareUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request)
+  });
+  return await response.json();
+}
+async function fixComponent(viewerUrl, request, endpoints) {
+  const fixUrl = `${viewerUrl}${endpoints?.fix ?? DEFAULT_ENDPOINTS.fix}`;
+  const response = await fetch(fixUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request)
+  });
+  return await response.json();
+}
+async function auditComponent(viewerUrl, request, endpoints) {
+  const a11yUrl = `${viewerUrl}${endpoints?.a11y ?? DEFAULT_ENDPOINTS.a11y}`;
+  const response = await fetch(a11yUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      component: request.component,
+      variant: request.variant,
+      standard: request.standard,
+      includeFixPatches: request.includeFixPatches
+    })
+  });
+  const raw = await response.json();
+  if (raw.error) {
+    return {
+      component: request.component,
+      results: [],
+      score: 0,
+      aaPercent: 0,
+      aaaPercent: 0,
+      passed: false,
+      standard: request.standard ?? "AA",
+      error: raw.error
+    };
+  }
+  const results = raw.results ?? [];
+  const standard = request.standard ?? "AA";
+  let totalCritical = 0;
+  let totalSerious = 0;
+  let totalModerate = 0;
+  let totalMinor = 0;
+  for (const r of results) {
+    totalCritical += r.summary.critical;
+    totalSerious += r.summary.serious;
+    totalModerate += r.summary.moderate;
+    totalMinor += r.summary.minor;
+  }
+  const deductions = totalCritical * 10 + totalSerious * 5 + totalModerate * 2 + totalMinor * 1;
+  const score = Math.max(0, 100 - deductions);
+  const variantCount = results.length;
+  const aaPassCount = results.filter((r) => {
+    const critical = r.summary.critical;
+    const serious = r.summary.serious;
+    return critical === 0 && serious === 0;
+  }).length;
+  const aaaPassCount = results.filter((r) => {
+    const total = r.summary.critical + r.summary.serious + r.summary.moderate + r.summary.minor;
+    return total === 0;
+  }).length;
+  const totalPasses = results.reduce((sum, r) => sum + r.passes, 0);
+  const totalViolations = totalCritical + totalSerious + totalModerate + totalMinor;
+  const emptyAudit = results.length > 0 && totalPasses === 0 && totalViolations === 0;
+  const aaPercent = variantCount > 0 ? Math.round(aaPassCount / variantCount * 100) : 100;
+  const aaaPercent = variantCount > 0 ? Math.round(aaaPassCount / variantCount * 100) : 100;
+  const aaPass = !emptyAudit && totalCritical === 0 && totalSerious === 0;
+  const aaaPass = !emptyAudit && totalViolations === 0;
+  const passed = standard === "AAA" ? aaaPass : aaPass;
+  return {
+    component: request.component,
+    results,
+    score: emptyAudit ? 0 : score,
+    aaPercent: emptyAudit ? 0 : aaPercent,
+    aaaPercent: emptyAudit ? 0 : aaaPercent,
+    ...emptyAudit && { emptyAudit },
+    passed,
+    standard
+  };
+}
+
+// src/tools/render.ts
+var NO_VIEWER_MSG = "This tool requires a running dev server. Add --viewer-url http://localhost:PORT to this server's config args. Start the viewer with 'fragments dev' in your component library directory.";
+var renderHandler = async (args, ctx) => {
+  const componentName = args?.component;
+  const variantName = args?.variant;
+  const props = args?.props ?? {};
+  const viewport = args?.viewport;
+  const figmaUrl = args?.figmaUrl;
+  const threshold = args?.threshold ?? (figmaUrl ? 1 : ctx.config.threshold ?? DEFAULTS.diffThreshold);
+  if (!componentName) {
+    return {
+      content: [{ type: "text", text: "Error: component name is required" }],
+      isError: true
+    };
+  }
+  {
+    const fragment = Object.values(ctx.data.components).find(
+      (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
+    );
+    if (!fragment) {
+      const allNames = Object.values(ctx.data.components).map((s) => s.meta.name);
+      const closest = findClosestMatch(componentName, allNames);
+      const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+      throw new Error(`Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`);
+    }
+  }
+  const viewerUrl = ctx.config.viewerUrl;
+  if (!viewerUrl) {
+    return {
+      content: [{
+        type: "text",
+        text: NO_VIEWER_MSG
+      }],
+      isError: true
+    };
+  }
+  if (figmaUrl) {
+    try {
+      const result = await compareComponent(viewerUrl, {
+        component: componentName,
+        variant: variantName,
+        props,
+        figmaUrl,
+        threshold
+      }, ctx.config.fileConfig?.endpoints);
+      if (result.error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Compare error: ${result.error}${result.suggestion ? `
+Suggestion: ${result.suggestion}` : ""}`
+          }],
+          isError: true
+        };
+      }
+      const content = [];
+      const summaryText = result.match ? `MATCH: ${componentName} matches Figma design (${result.diffPercentage}% diff, threshold: ${result.threshold}%)` : `MISMATCH: ${componentName} differs from Figma design by ${result.diffPercentage}% (threshold: ${result.threshold}%)`;
+      content.push({ type: "text", text: summaryText });
+      if (result.diff && !result.match) {
+        content.push({
+          type: "image",
+          data: result.diff.replace("data:image/png;base64,", ""),
+          mimeType: "image/png"
+        });
+        content.push({
+          type: "text",
+          text: `Diff image above shows visual differences (red highlights). Changed regions: ${result.changedRegions?.length ?? 0}`
+        });
+      }
+      content.push({
+        type: "text",
+        text: JSON.stringify({
+          match: result.match,
+          diffPercentage: result.diffPercentage,
+          threshold: result.threshold,
+          figmaUrl: result.figmaUrl,
+          changedRegions: result.changedRegions
+        })
+      });
+      return { content };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `Failed to compare component: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running and FIGMA_ACCESS_TOKEN is set.`
+        }],
+        isError: true
+      };
+    }
+  }
+  try {
+    const result = await renderComponent(viewerUrl, {
+      component: componentName,
+      props,
+      variant: variantName,
+      viewport: viewport ?? { width: 800, height: 600 }
+    }, ctx.config.fileConfig?.endpoints);
+    if (result.error) {
+      return {
+        content: [{ type: "text", text: `Render error: ${result.error}` }],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "image",
+          data: result.screenshot.replace("data:image/png;base64,", ""),
+          mimeType: "image/png"
+        },
+        {
+          type: "text",
+          text: `Successfully rendered ${componentName}${variantName ? ` (variant: "${variantName}")` : ""}${Object.keys(props).length > 0 ? ` with props: ${JSON.stringify(props)}` : ""}`
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [{
+        type: "text",
+        text: `Failed to render component: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
+      }],
+      isError: true
+    };
+  }
+};
+
+// src/tools/fix.ts
+var NO_VIEWER_MSG2 = "This tool requires a running dev server. Add --viewer-url http://localhost:PORT to this server's config args. Start the viewer with 'fragments dev' in your component library directory.";
+var fixHandler = async (args, ctx) => {
+  const componentName = args?.component;
+  const variantName = args?.variant ?? void 0;
+  const fixType = args?.fixType ?? "all";
+  if (!componentName) {
+    throw new Error("component is required");
+  }
+  const fragment = Object.values(ctx.data.components).find(
+    (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
+  );
+  if (!fragment) {
+    const allNames = Object.values(ctx.data.components).map((s) => s.meta.name);
+    const closest = findClosestMatch(componentName, allNames);
+    const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+    throw new Error(`Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`);
+  }
+  const viewerUrl = ctx.config.viewerUrl;
+  if (!viewerUrl) {
+    return {
+      content: [{
+        type: "text",
+        text: NO_VIEWER_MSG2
+      }],
+      isError: true
+    };
+  }
+  try {
+    const result = await fixComponent(viewerUrl, {
+      component: componentName,
+      variant: variantName,
+      fixType
+    }, ctx.config.fileConfig?.endpoints);
+    if (result.error) {
+      return {
+        content: [{
+          type: "text",
+          text: `Fix generation error: ${result.error}`
+        }],
+        isError: true
+      };
+    }
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          component: componentName,
+          variant: variantName ?? "all",
+          fixType,
+          patches: result.patches,
+          summary: result.summary,
+          patchCount: result.patches.length,
+          nextStep: result.patches.length > 0 ? `Apply patches using your editor or \`patch\` command, then run ${ctx.toolNames.render} to confirm fixes.` : void 0
+        })
+      }]
+    };
+  } catch (error) {
+    return {
+      content: [{
+        type: "text",
+        text: `Failed to generate fixes: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
+      }],
+      isError: true
+    };
+  }
+};
+
+// src/tools/a11y.ts
+var NO_VIEWER_MSG3 = "This tool requires a running dev server. Add --viewer-url http://localhost:PORT to this server's config args. Start the viewer with 'fragments dev' in your component library directory.";
+var a11yHandler = async (args, ctx) => {
+  const componentName = args?.component;
+  const variantName = args?.variant ?? void 0;
+  const standard = args?.standard ?? "AA";
+  const includeFixPatches = args?.includeFixPatches ?? false;
+  if (!componentName) {
+    throw new Error("component is required");
+  }
+  {
+    const fragment = Object.values(ctx.data.components).find(
+      (s) => s.meta.name.toLowerCase() === componentName.toLowerCase()
+    );
+    if (!fragment) {
+      const allNames = Object.values(ctx.data.components).map((s) => s.meta.name);
+      const closest = findClosestMatch(componentName, allNames);
+      const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+      throw new Error(`Component "${componentName}" not found.${suggestion} Use ${ctx.toolNames.discover} to see available components.`);
+    }
+  }
+  const viewerUrl = ctx.config.viewerUrl;
+  if (!viewerUrl) {
+    return {
+      content: [{
+        type: "text",
+        text: NO_VIEWER_MSG3
+      }],
+      isError: true
+    };
+  }
+  try {
+    const result = await auditComponent(viewerUrl, {
+      component: componentName,
+      variant: variantName,
+      standard,
+      includeFixPatches
+    }, ctx.config.fileConfig?.endpoints);
+    if (result.error) {
+      return {
+        content: [{
+          type: "text",
+          text: `A11y audit error: ${result.error}`
+        }],
+        isError: true
+      };
+    }
+    let nextStep;
+    if (result.emptyAudit) {
+      nextStep = `No testable elements found for ${variantName ? `variant "${variantName}"` : componentName}. The variant may not exist or renders no accessible content. Check available variants with ${ctx.toolNames.inspect}("${componentName}").`;
+    } else if (result.passed) {
+      nextStep = 'All accessibility checks passed. Consider running with standard: "AAA" for enhanced compliance.';
+    } else {
+      nextStep = `Fix the violations above, then re-run ${ctx.toolNames.a11y} to verify. Use ${ctx.toolNames.fix} for automated fixes.`;
+    }
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          component: componentName,
+          variant: variantName ?? "all",
+          standard,
+          totalViolations: result.results.reduce((sum, r) => sum + r.summary.total, 0),
+          variantsPassingAA: `${result.aaPercent}%`,
+          variantsPassingAAA: `${result.aaaPercent}%`,
+          passed: result.passed,
+          ...result.emptyAudit && { emptyAudit: true },
+          results: result.results,
+          nextStep
+        })
+      }]
+    };
+  } catch (error) {
+    return {
+      content: [{
+        type: "text",
+        text: `Failed to audit component: ${error instanceof Error ? error.message : "Unknown error"}. Make sure the Fragments dev server is running.`
+      }],
+      isError: true
+    };
+  }
+};
+
+// src/graph-handler.ts
+import {
+  ComponentGraphEngine,
+  deserializeGraph
+} from "@fragments-sdk/context/graph";
+function handleGraphTool(args, serializedGraph, blocks, componentNames) {
+  if (!serializedGraph) {
+    return {
+      text: JSON.stringify({
+        error: "No graph data available. Run `fragments build` to generate the component graph.",
+        hint: "The graph is built automatically during `fragments build` and embedded in fragments.json."
+      }),
+      isError: true
+    };
+  }
+  const graph = deserializeGraph(serializedGraph);
+  const blockData = blocks ? Object.fromEntries(
+    Object.entries(blocks).map(([k, v]) => [k, { components: v.components }])
+  ) : void 0;
+  const engine = new ComponentGraphEngine(graph, blockData);
+  const edgeTypes = args.edgeTypes;
+  switch (args.mode) {
+    case "health": {
+      const health = engine.getHealth();
+      const blockCount = blocks ? Object.keys(blocks).length : 0;
+      return {
+        text: JSON.stringify({
+          mode: "health",
+          ...health,
+          ...health.compositionCoverage === 0 && blockCount === 0 && {
+            compositionNote: "No composition blocks defined yet \u2014 compositionCoverage will increase as blocks are added"
+          },
+          summary: `${health.nodeCount} components, ${health.edgeCount} edges, ${health.connectedComponents.length} island(s), ${health.orphans.length} orphan(s), ${health.compositionCoverage}% in blocks`
+        })
+      };
+    }
+    case "dependencies": {
+      if (!args.component) {
+        return { text: JSON.stringify({ error: "component is required for dependencies mode" }), isError: true };
+      }
+      if (!engine.hasNode(args.component)) {
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
+      }
+      const deps = engine.dependencies(args.component, edgeTypes);
+      return {
+        text: JSON.stringify({
+          mode: "dependencies",
+          component: args.component,
+          count: deps.length,
+          dependencies: deps.map((e) => ({
+            component: e.target,
+            type: e.type,
+            weight: e.weight,
+            note: e.note,
+            provenance: e.provenance
+          }))
+        })
+      };
+    }
+    case "dependents": {
+      if (!args.component) {
+        return { text: JSON.stringify({ error: "component is required for dependents mode" }), isError: true };
+      }
+      if (!engine.hasNode(args.component)) {
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
+      }
+      const deps = engine.dependents(args.component, edgeTypes);
+      return {
+        text: JSON.stringify({
+          mode: "dependents",
+          component: args.component,
+          count: deps.length,
+          dependents: deps.map((e) => ({
+            component: e.source,
+            type: e.type,
+            weight: e.weight,
+            note: e.note,
+            provenance: e.provenance
+          }))
+        })
+      };
+    }
+    case "impact": {
+      if (!args.component) {
+        return { text: JSON.stringify({ error: "component is required for impact mode" }), isError: true };
+      }
+      if (!engine.hasNode(args.component)) {
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
+      }
+      const result = engine.impact(args.component, args.maxDepth ?? 3);
+      return {
+        text: JSON.stringify({
+          mode: "impact",
+          ...result,
+          summary: `Changing ${args.component} affects ${result.totalAffected} component(s) and ${result.affectedBlocks.length} block(s)`
+        })
+      };
+    }
+    case "path": {
+      if (!args.component || !args.target) {
+        return { text: JSON.stringify({ error: "component and target are required for path mode" }), isError: true };
+      }
+      const result = engine.path(args.component, args.target);
+      return {
+        text: JSON.stringify({
+          mode: "path",
+          from: args.component,
+          to: args.target,
+          ...result,
+          edges: result.edges.map((e) => ({
+            source: e.source,
+            target: e.target,
+            type: e.type
+          }))
+        })
+      };
+    }
+    case "composition": {
+      if (!args.component) {
+        return { text: JSON.stringify({ error: "component is required for composition mode" }), isError: true };
+      }
+      if (!engine.hasNode(args.component)) {
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
+      }
+      const tree = engine.composition(args.component);
+      return {
+        text: JSON.stringify({
+          mode: "composition",
+          ...tree
+        })
+      };
+    }
+    case "alternatives": {
+      if (!args.component) {
+        return { text: JSON.stringify({ error: "component is required for alternatives mode" }), isError: true };
+      }
+      if (!engine.hasNode(args.component)) {
+        const closest = componentNames ? findClosestMatch(args.component, componentNames) : null;
+        const suggestion = closest ? ` Did you mean "${closest}"?` : "";
+        return { text: JSON.stringify({ error: `Component "${args.component}" not found in graph.${suggestion}` }), isError: true };
+      }
+      const alts = engine.alternatives(args.component);
+      return {
+        text: JSON.stringify({
+          mode: "alternatives",
+          component: args.component,
+          count: alts.length,
+          alternatives: alts
+        })
+      };
+    }
+    case "islands": {
+      const islands = engine.islands();
+      return {
+        text: JSON.stringify({
+          mode: "islands",
+          count: islands.length,
+          islands: islands.map((island, i) => ({
+            id: i + 1,
+            size: island.length,
+            components: island
+          }))
+        })
+      };
+    }
+    default:
+      return {
+        text: JSON.stringify({
+          error: `Unknown mode: "${args.mode}". Valid modes: dependencies, dependents, impact, path, composition, alternatives, islands, health`
+        }),
+        isError: true
+      };
+  }
+}
+
+// src/tools/graph.ts
+var graphHandler = async (args, ctx) => {
+  const graphArgs = {
+    mode: args?.mode ?? "health",
+    component: args?.component,
+    target: args?.target,
+    edgeTypes: args?.edgeTypes,
+    maxDepth: args?.maxDepth
+  };
+  const data = ctx.data;
+  const allNames = Object.values(data.components).map((s) => s.meta.name);
+  const result = handleGraphTool(
+    graphArgs,
+    data.graph,
+    data.blocks,
+    allNames
+  );
+  if (result.isError) {
+    return {
+      content: [{ type: "text", text: result.text }],
+      isError: true
+    };
+  }
+  return {
+    content: [{ type: "text", text: result.text }]
+  };
+};
+
+// src/tools/govern.ts
+import {
+  handleGovernTool,
+  formatVerdict,
+  universal,
+  fragments as fragmentsPreset
+} from "@fragments-sdk/govern";
+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 }] }"
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+  const policyOverrides = args?.policy;
+  const format = args?.format ?? "json";
+  const tokenPrefix = ctx.data.tokens?.prefix;
+  const basePolicy = tokenPrefix === "fui-" ? { rules: fragmentsPreset().rules } : { rules: universal().rules };
+  const engineOptions = ctx.data.tokens ? { tokenData: ctx.data.tokens } : void 0;
+  const input = {
+    spec,
+    policy: policyOverrides,
+    format
+  };
+  try {
+    const verdict = await handleGovernTool(input, basePolicy, engineOptions);
+    const text = format === "summary" ? formatVerdict(verdict, "summary") : JSON.stringify(verdict);
+    return {
+      content: [{ type: "text", text }],
+      _meta: {
+        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?: string[] }] }` : message
+          })
+        }
+      ],
+      isError: true
+    };
+  }
+};
+
+// src/tools/generate-ui.ts
+var generateUiHandler = async (args, ctx) => {
+  const prompt = args?.prompt;
+  if (!prompt) {
+    throw new Error("prompt is required");
+  }
+  const currentTree = args?.currentTree;
+  const playgroundUrl = ctx.config.playgroundUrl ?? "https://usefragments.com";
+  const response = await fetch(`${playgroundUrl}/api/playground/generate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      prompt,
+      ...currentTree && { currentSpec: currentTree }
+    })
+  });
+  if (!response.ok) {
+    const errorBody = await response.text();
+    throw new Error(`Playground API error (${response.status}): ${errorBody}`);
+  }
+  const text = await response.text();
+  return {
+    content: [{
+      type: "text",
+      text
+    }]
+  };
+};
+
+// src/tools/index.ts
+var CORE_TOOLS = {
+  discover: discoverHandler,
+  inspect: inspectHandler,
+  blocks: blocksHandler,
+  tokens: tokensHandler,
+  implement: implementHandler,
+  graph: graphHandler,
+  govern: governHandler
+};
+var VIEWER_TOOLS = {
+  render: renderHandler,
+  fix: fixHandler,
+  a11y: a11yHandler
+};
+var INFRA_TOOLS = {
+  generate_ui: generateUiHandler
+};
+var BUILTIN_TOOLS = {
+  ...CORE_TOOLS,
+  ...VIEWER_TOOLS,
+  ...INFRA_TOOLS
+};
+
+// 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") {
+    this.tools.set(key, { key, handler, definition, availability });
+    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) {
+    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" });
+    }
+    for (const [key, handler] of Object.entries(toolSets.viewer)) {
+      this.tools.set(key, { key, handler, definition: defMap.get(key), availability: "viewer" });
+    }
+    for (const [key, handler] of Object.entries(toolSets.infra)) {
+      this.tools.set(key, { key, handler, definition: defMap.get(key), availability: "playground" });
+    }
+  }
+  /** 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) {
+      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 result = await next();
+    logger(`${mCtx.toolKey}: ${Date.now() - start}ms`);
+    return result;
+  };
+}
+
+// src/server.ts
+var TOOL_NAMES = buildToolNames();
+var TOOLS = buildMcpTools();
+function createMcpServer(config) {
+  const server = new Server(
+    {
+      name: `${BRAND.nameLower}-mcp`,
+      version: MCP_SERVER_VERSION
+    },
+    {
+      capabilities: {
+        tools: { listChanged: true }
+      }
+    }
+  );
+  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
+  );
+  const adapter = config.adapter ?? new FragmentsJsonAdapter();
+  const fileConfig = config.fileConfig ?? loadConfigFile(config.projectRoot) ?? void 0;
+  const mergedConfig = fileConfig ? { ...config, fileConfig } : config;
+  config.onRegistry?.(registry);
+  if (fileConfig?.tools?.exclude) {
+    for (const key of fileConfig.tools.exclude) {
+      registry.unregister(key);
+    }
+  }
+  let cachedData = null;
+  let resolvedRoot = null;
+  let componentIndex = null;
+  let blockIndex = null;
+  let tokenIndex = null;
+  async function resolveProjectRoot() {
+    if (resolvedRoot) return resolvedRoot;
+    try {
+      const result = await server.listRoots();
+      if (result.roots?.length > 0) {
+        const rootUri = result.roots[0].uri;
+        resolvedRoot = fileURLToPath(rootUri);
+        return resolvedRoot;
+      }
+    } catch {
+    }
+    resolvedRoot = config.projectRoot;
+    return resolvedRoot;
+  }
+  async function loadData() {
+    if (cachedData) return cachedData;
+    const projectRoot = await resolveProjectRoot();
+    cachedData = await adapter.load(projectRoot);
+    const allFragments = Object.values(cachedData.components);
+    const allBlocks = Object.values(cachedData.blocks ?? {});
+    componentIndex = buildComponentIndex(allFragments);
+    if (allBlocks.length > 0) {
+      blockIndex = buildBlockIndex(allBlocks);
+    }
+    if (cachedData.tokens && cachedData.tokens.total > 0) {
+      tokenIndex = buildTokenIndex(cachedData.tokens);
+    }
+    return cachedData;
+  }
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: registry.listTools(
+        { hasViewer: !!config.viewerUrl, hasPlayground: !!(config.playgroundUrl ?? fileConfig?.playgroundUrl) },
+        TOOLS
+      )
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const data = await loadData();
+    const toolContext = {
+      data,
+      config: mergedConfig,
+      indexes: { componentIndex, blockIndex, tokenIndex },
+      resolvePackageName: (name2) => {
+        if (name2) {
+          const pkg = data.packageMap.get(name2);
+          if (pkg) return pkg;
+        }
+        if (data.defaultPackageName) return data.defaultPackageName;
+        const root = resolvedRoot ?? config.projectRoot;
+        const packageJsonPath = join3(root, "package.json");
+        if (existsSync3(packageJsonPath)) {
+          try {
+            const content = readFileSync4(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 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 {
+  SYNONYM_MAP,
+  USE_CASE_TOKEN_CATEGORIES,
+  findFragmentsJson,
+  FragmentsJsonAdapter,
+  MINIMUM_SCORE_THRESHOLD,
+  BLOCK_BOOST_PER_OCCURRENCE,
+  DEFAULT_ENDPOINTS,
+  CORE_TOOLS,
+  VIEWER_TOOLS,
+  INFRA_TOOLS,
+  BUILTIN_TOOLS,
+  ToolRegistry,
+  executeWithMiddleware,
+  telemetryMiddleware,
+  createMcpServer,
+  startMcpServer,
+  createSandboxServer
+};
+//# sourceMappingURL=chunk-WBOVO43F.js.map