@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/dist/index.js

@@ -1,23 +1,2522 @@
 #!/usr/bin/env node
-/**
- * Nimbus MCP Server — stdio entry point.
- *
- * Connects the MCP server to stdin/stdout so it can be used with any MCP
- * client (e.g. Claude Desktop, Claude Code) via the stdio transport.
- *
- * Usage:
- *   node dist/index.js
- *   # or via package bin:
- *   nimbus-mcp
- */
+
+// src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createServer } from "./server.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/get-component.ts
+import { readdir } from "fs/promises";
+import { resolve as resolve3 } from "path";
+import { z } from "zod";
+
+// src/data-loader.ts
+import { readFile as readFile2 } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve as resolve2, dirname as dirname2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+
+// src/processors/flatten-tokens.ts
+import { readFile } from "fs/promises";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function normaliseValue(value) {
+  return value.trim().toLowerCase();
+}
+function reverseLookup(data, value) {
+  return data.reverseLookup[normaliseValue(value)] ?? [];
+}
+
+// src/data-loader.ts
+var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
+function findPackageRoot() {
+  let dir = __dirname2;
+  while (dir !== dirname2(dir)) {
+    if (existsSync(resolve2(dir, "package.json"))) {
+      return dir;
+    }
+    dir = dirname2(dir);
+  }
+  return __dirname2;
+}
+var PACKAGE_ROOT = findPackageRoot();
+var DATA_DIR = resolve2(PACKAGE_ROOT, "data");
+function getDataDir() {
+  return DATA_DIR;
+}
+async function readJson(filePath) {
+  const raw = await readFile2(filePath, "utf-8");
+  return JSON.parse(raw);
+}
+function lazyJson(relativePath) {
+  let cached;
+  return async () => {
+    if (cached === void 0) {
+      const fullPath = resolve2(getDataDir(), relativePath);
+      cached = await readJson(fullPath);
+    }
+    return cached;
+  };
+}
+var getRouteManifest = lazyJson(
+  "docs/route-manifest.json"
+);
+var routeDataCache = /* @__PURE__ */ new Map();
+async function getRouteData(slug) {
+  const cached = routeDataCache.get(slug);
+  if (cached) return cached;
+  const fullPath = resolve2(getDataDir(), "docs/routes", `${slug}.json`);
+  const data = await readJson(fullPath);
+  routeDataCache.set(slug, data);
+  return data;
+}
+async function getTypeData(componentName) {
+  const fullPath = resolve2(getDataDir(), "docs/types", `${componentName}.json`);
+  return readJson(fullPath);
+}
+var getTypesIndex = lazyJson("docs/types.json");
+var getSearchIndex = lazyJson(
+  "docs/search-index.json"
+);
+var getDocsManifest = lazyJson("docs/docs.json");
+var getIconCatalog = lazyJson("icons.json");
+var getFlatTokenData = lazyJson("tokens.json");
+
+// src/utils/markdown.ts
+function stripMarkdown(text) {
+  const codeBlocks = [];
+  const withPlaceholders = text.replace(
+    /^```[^\n]*\n([\s\S]*?)^```[ \t]*$/gm,
+    (_, content) => {
+      codeBlocks.push(content.trimEnd());
+      return `\uE000CODE${codeBlocks.length - 1}\uE000`;
+    }
+  );
+  const stripped = withPlaceholders.replace(/^---[\s\S]*?---\n?/, "").replace(/<[A-Z][^>]*\/>/g, "").replace(/<[A-Z][^>]*>[\s\S]*?<\/[A-Z][^>]*>/g, "").replace(/<[a-z][^>]*\/>/g, "").replace(/<\/?[a-z][^>]*>/g, "").replace(/#{1,6}\s/g, "").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/\*([^*]+)\*/g, "$1").replace(/!\[([^\]]*)\]\([^)]+\)/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\n{3,}/g, "\n\n").trim();
+  return stripped.replace(
+    /\uE000CODE(\d+)\uE000/g,
+    (_, i) => codeBlocks[Number(i)]
+  );
+}
+
+// src/utils/relevance.ts
+var WEIGHTS = { title: 8, description: 4, tags: 4, content: 1 };
+function filterAndRankPreLowered(items, tokens, getLowered) {
+  if (items.length === 0 || tokens.length === 0) return items;
+  const scored = [];
+  const tokenCount = tokens.length;
+  if (tokenCount === 1) {
+    const t = tokens[0];
+    for (const item of items) {
+      const { title, description, tags, content } = getLowered(item);
+      let score = 0;
+      if (title.includes(t)) score += WEIGHTS.title;
+      if (description.includes(t)) score += WEIGHTS.description;
+      if (tags.includes(t)) score += WEIGHTS.tags;
+      if (content.includes(t)) score += WEIGHTS.content;
+      if (score > 0) scored.push({ item, score });
+    }
+  } else {
+    for (const item of items) {
+      const fields = getLowered(item);
+      const { title, description, tags, content, combined } = fields;
+      let allPresent = true;
+      for (let i = 0; i < tokenCount; i++) {
+        if (!combined.includes(tokens[i])) {
+          allPresent = false;
+          break;
+        }
+      }
+      if (!allPresent) continue;
+      let score = 0;
+      for (let i = 0; i < tokenCount; i++) {
+        const t = tokens[i];
+        if (title.includes(t)) score += WEIGHTS.title;
+        if (description.includes(t)) score += WEIGHTS.description;
+        if (tags.includes(t)) score += WEIGHTS.tags;
+        if (content.includes(t)) score += WEIGHTS.content;
+      }
+      scored.push({ item, score });
+    }
+  }
+  return scored.sort((a, b) => b.score - a.score).map(({ item }) => item);
+}
+function scorePreLowered(fields, tokens) {
+  let score = 0;
+  for (const t of tokens) {
+    if (fields.title.includes(t)) score += WEIGHTS.title;
+    if (fields.description.includes(t)) score += WEIGHTS.description;
+    if (fields.tags.includes(t)) score += WEIGHTS.tags;
+    if (fields.content.includes(t)) score += WEIGHTS.content;
+  }
+  return score;
+}
+function boundedLevenshtein(a, b, maxDist) {
+  if (Math.abs(a.length - b.length) > maxDist) return -1;
+  if (a === b) return 0;
+  if (a.length > b.length) [a, b] = [b, a];
+  const m = a.length;
+  const n = b.length;
+  let prev = new Array(m + 1);
+  let curr = new Array(m + 1);
+  for (let i = 0; i <= m; i++) prev[i] = i;
+  for (let j = 1; j <= n; j++) {
+    curr[0] = j;
+    let rowMin = j;
+    for (let i = 1; i <= m; i++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[i] = Math.min(prev[i] + 1, curr[i - 1] + 1, prev[i - 1] + cost);
+      if (curr[i] < rowMin) rowMin = curr[i];
+    }
+    if (rowMin > maxDist) return -1;
+    [prev, curr] = [curr, prev];
+  }
+  return prev[m] <= maxDist ? prev[m] : -1;
+}
+function fuzzyScorePreLowered(fields, tokens) {
+  let score = 0;
+  const FUZZY_WEIGHTS = {
+    title: WEIGHTS.title / 2,
+    description: WEIGHTS.description / 2,
+    tags: WEIGHTS.tags / 2,
+    content: WEIGHTS.content / 2
+  };
+  const fieldData = [
+    {
+      text: fields.title,
+      noSpaces: fields.titleNoSpaces ?? fields.title.replace(/\s+/g, ""),
+      words: fields.titleWords ?? fields.title.split(/\s+/).filter(Boolean),
+      weight: FUZZY_WEIGHTS.title
+    },
+    {
+      text: fields.description,
+      noSpaces: fields.descriptionNoSpaces ?? fields.description.replace(/\s+/g, ""),
+      words: fields.descriptionWords ?? fields.description.split(/\s+/).filter(Boolean),
+      weight: FUZZY_WEIGHTS.description
+    },
+    {
+      text: fields.tags,
+      noSpaces: fields.tagsNoSpaces ?? fields.tags.replace(/\s+/g, ""),
+      words: fields.tagsWords ?? fields.tags.split(/\s+/).filter(Boolean),
+      weight: FUZZY_WEIGHTS.tags
+    }
+  ];
+  for (const token of tokens) {
+    if (token.length < 3) continue;
+    const maxDist = token.length <= 4 ? 1 : token.length <= 7 ? 2 : 3;
+    for (const { text, noSpaces, words, weight } of fieldData) {
+      if (text.includes(token)) {
+        score += weight;
+        continue;
+      }
+      if (noSpaces.includes(token)) {
+        score += weight;
+        continue;
+      }
+      let matched = false;
+      for (const word of words) {
+        if (boundedLevenshtein(token, word, maxDist) >= 0) {
+          matched = true;
+          break;
+        }
+        if (token.startsWith(word) || word.startsWith(token)) {
+          matched = true;
+          break;
+        }
+      }
+      if (matched) score += weight;
+    }
+  }
+  return score;
+}
+function fuzzyResolveName(needle, candidates, getNames) {
+  if (needle.length < 2) return void 0;
+  const lower = needle.toLowerCase();
+  const maxDist = lower.length <= 4 ? 1 : lower.length <= 7 ? 2 : 3;
+  let bestItem;
+  let bestDist = maxDist + 1;
+  let bestLen = Infinity;
+  for (const item of candidates) {
+    for (const name of getNames(item)) {
+      const nameLower = name.toLowerCase();
+      const dist = boundedLevenshtein(lower, nameLower, maxDist);
+      if (dist >= 0 && (dist < bestDist || dist === bestDist && nameLower.length < bestLen)) {
+        bestDist = dist;
+        bestLen = nameLower.length;
+        bestItem = item;
+      }
+    }
+  }
+  return bestItem;
+}
+
+// src/tools/get-component.ts
+var SECTION_KEYS = [
+  "overview",
+  "guidelines",
+  "implementation",
+  "accessibility",
+  "props"
+];
+var VIEW_KEY_MAP = {
+  overview: "overview",
+  guidelines: "guidelines",
+  implementation: "dev",
+  accessibility: "a11y"
+};
+var INHERITED_PARENT_NAMES = /* @__PURE__ */ new Set([
+  // Low-level HTML / DOM
+  "HTMLAttributes",
+  "DOMAttributes",
+  "ButtonHTMLAttributes",
+  "GlobalDOMEvents",
+  "GlobalDOMAttributes",
+  "AriaAttributes",
+  "HtmlProps",
+  // Chakra system internals
+  "SystemProperties",
+  "Conditions"
+]);
+var EXCLUDED_PROP_NAMES = /* @__PURE__ */ new Set(["key"]);
+function filterProps(typeData) {
+  return Object.values(typeData.props).filter(
+    (p) => !EXCLUDED_PROP_NAMES.has(p.name) && (!p.parent || !INHERITED_PARENT_NAMES.has(p.parent.name))
+  ).map((p) => {
+    const prop = {
+      name: p.name,
+      type: p.type.name,
+      required: p.required,
+      description: p.description
+    };
+    if (p.defaultValue) prop.defaultValue = p.defaultValue.value;
+    return prop;
+  });
+}
+var resolveCatalogCache;
+var resolveCatalogRoutesRef;
+var topLevelNamesCache;
+var topLevelNamesRoutesRef;
+async function aggregateSubComponentProps(exportName) {
+  const typesDir = resolve3(getDataDir(), "docs/types");
+  let files;
+  try {
+    files = await readdir(typesDir);
+  } catch {
+    return [];
+  }
+  const manifest = await getRouteManifest();
+  if (!topLevelNamesCache || topLevelNamesRoutesRef !== manifest.routes) {
+    topLevelNamesCache = new Set(
+      manifest.routes.filter((r) => CATALOG_CATEGORIES.has(r.category)).map((r) => (r.exportName ?? r.title).toLowerCase())
+    );
+    topLevelNamesRoutesRef = manifest.routes;
+  }
+  const topLevelNames = topLevelNamesCache;
+  const prefix = exportName.toLowerCase();
+  const subFiles = files.filter((f) => {
+    const base = f.replace(/\.json$/, "");
+    const baseLower = base.toLowerCase();
+    return f.endsWith(".json") && baseLower.startsWith(prefix) && baseLower !== prefix && // exclude the top-level file itself
+    !base.includes(".") && // exclude method exports (e.g. FieldErrors.getBuiltInMessage)
+    !base.endsWith("Props") && // exclude type-only duplicates (e.g. StepsRootProps)
+    !topLevelNames.has(baseLower);
+  });
+  const settled = await Promise.allSettled(
+    subFiles.map(async (file) => {
+      const subName = file.replace(/\.json$/, "");
+      const typeData = await getTypeData(subName);
+      return filterProps(typeData).map((p) => ({
+        ...p,
+        subComponent: subName
+      }));
+    })
+  );
+  return settled.filter((r) => r.status === "fulfilled").flatMap((r) => r.value);
+}
+var CATALOG_CATEGORIES = /* @__PURE__ */ new Set(["Components", "Patterns"]);
+async function resolveComponent(name) {
+  const manifest = await getRouteManifest();
+  const needle = name.toLowerCase();
+  if (!resolveCatalogCache || resolveCatalogRoutesRef !== manifest.routes) {
+    resolveCatalogCache = manifest.routes.filter(
+      (r) => CATALOG_CATEGORIES.has(r.category) && r.menu.length === 3
+    );
+    resolveCatalogRoutesRef = manifest.routes;
+  }
+  const catalog = resolveCatalogCache;
+  const exact = catalog.find((r) => {
+    if (r.exportName?.toLowerCase() === needle) return true;
+    if (r.title.toLowerCase() === needle) return true;
+    const idName = r.id.replace(/^(Components|Patterns)-/, "");
+    return idName.toLowerCase() === needle;
+  });
+  if (exact) return exact;
+  return fuzzyResolveName(name, catalog, (r) => {
+    const names = [r.title];
+    if (r.exportName) names.push(r.exportName);
+    return names;
+  });
+}
+function pathToSlug(path) {
+  return path.replace(/^\//, "").replace(/\//g, "-");
+}
+function buildMetadataResponse(entry, availableSections) {
+  const meta = {
+    name: entry.title,
+    description: entry.description,
+    path: entry.path,
+    sections: availableSections
+  };
+  if (entry.exportName) meta.exportName = entry.exportName;
+  const subcategory = entry.menu[1];
+  if (subcategory) meta.subcategory = subcategory;
+  if (entry.tags.length > 0) meta.tags = entry.tags;
+  return meta;
+}
+function registerGetComponent(server) {
+  server.registerTool(
+    "get_component",
+    {
+      title: "Get Component",
+      description: "Returns detailed information about a Nimbus component or pattern. With name only: returns metadata and available sections. With name + section: returns section content (overview, guidelines, implementation, accessibility, props).",
+      inputSchema: {
+        name: z.string().describe(
+          'Component or pattern name, e.g. "Button", "TextInput", "MoneyInputField". Case-insensitive.'
+        ),
+        section: z.enum(SECTION_KEYS).optional().describe(
+          "Section to retrieve. Omit to get metadata + section list."
+        )
+      }
+    },
+    async ({ name, section }) => {
+      try {
+        const entry = await resolveComponent(name);
+        if (!entry) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Component "${name}" not found. Use list_components to see available components.`
+              }
+            ],
+            isError: true
+          };
+        }
+        const slug = pathToSlug(entry.path);
+        const routeData = await getRouteData(slug);
+        const viewSections = Object.keys(routeData.views ?? {}).map((key) => {
+          const canonical = Object.entries(VIEW_KEY_MAP).find(
+            ([, v]) => v === key
+          );
+          return canonical ? canonical[0] : key;
+        });
+        const availableSections = [...viewSections, "props"];
+        if (!section) {
+          const metadata = buildMetadataResponse(entry, availableSections);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(metadata)
+              }
+            ]
+          };
+        }
+        if (section === "props") {
+          const exportName = entry.exportName ?? entry.title;
+          try {
+            const typeData = await getTypeData(exportName);
+            let filtered = filterProps(typeData);
+            if (filtered.length === 0) {
+              filtered = await aggregateSubComponentProps(exportName);
+            }
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    component: exportName,
+                    propCount: filtered.length,
+                    props: filtered
+                  })
+                }
+              ]
+            };
+          } catch {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Type data not available for "${exportName}".`
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+        const viewKey = VIEW_KEY_MAP[section];
+        if (!viewKey) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Unknown section "${section}". Available: ${availableSections.join(", ")}`
+              }
+            ],
+            isError: true
+          };
+        }
+        const view = routeData.views?.[viewKey];
+        if (!view) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Section "${section}" is not available for "${entry.title}". Available: ${availableSections.join(", ")}`
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: stripMarkdown(view.mdx)
+            }
+          ]
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Component data is not available in this environment."
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/get-tokens.ts
+import { z as z2 } from "zod";
+var LARGE_CATEGORY_THRESHOLD = 55;
+var DEFAULT_PAGE_SIZE = 20;
+var CATEGORY_PRIORITY = [
+  "color",
+  "colorPalettes",
+  "spacing",
+  "fontSize",
+  "fontWeight",
+  "lineHeight",
+  "borderRadius",
+  "shadow",
+  "size",
+  "borderWidth",
+  "border",
+  "zIndex",
+  "opacity",
+  "textStyle"
+];
+function listCategories(data, virtualCategories = []) {
+  const priorityIndex = new Map(CATEGORY_PRIORITY.map((c, i) => [c, i]));
+  return Object.entries(data.byCategory).map(([category, tokens]) => ({ category, count: tokens.length })).concat(virtualCategories).sort((a, b) => {
+    const pa = priorityIndex.get(a.category) ?? CATEGORY_PRIORITY.length;
+    const pb = priorityIndex.get(b.category) ?? CATEGORY_PRIORITY.length;
+    if (pa !== pb) return pa - pb;
+    return a.category.localeCompare(b.category);
+  });
+}
+function findCategoryKey(data, category) {
+  const needle = category.toLowerCase();
+  return Object.keys(data.byCategory).find((k) => k.toLowerCase() === needle);
+}
+var PALETTE_GROUP_ORDER = [
+  "semantic-palettes",
+  "brand-palettes",
+  "system-palettes",
+  "blacks-and-whites"
+];
+function isExcludedAlphaPalette(token) {
+  return token.path[2]?.endsWith("Alpha") === true && token.path[1] !== "blacks-and-whites";
+}
+function extractPalettes(tokens) {
+  const groups = {};
+  for (const token of tokens) {
+    const group = token.path[1];
+    const palette = token.path[2];
+    const step = token.path[3];
+    if (!group || !palette || step !== "9" || isExcludedAlphaPalette(token))
+      continue;
+    if (!groups[group]) groups[group] = /* @__PURE__ */ new Map();
+    groups[group].set(palette, { name: palette, solid: token.value });
+  }
+  const toSorted = (group) => [...groups[group]?.values() ?? []].sort(
+    (a, b) => a.name.localeCompare(b.name)
+  );
+  return Object.fromEntries(
+    PALETTE_GROUP_ORDER.map((group) => [group, toSorted(group)])
+  );
+}
+var cachedPalettes;
+function getCachedPalettes(colorTokens) {
+  if (!cachedPalettes) {
+    cachedPalettes = extractPalettes(colorTokens);
+  }
+  return cachedPalettes;
+}
+function toResponseTokens(tokens) {
+  return tokens.map(({ name, value }) => ({ name, value }));
+}
+function buildCategoryResponse(matchKey, tokens, offset, limit) {
+  const isLarge = tokens.length > LARGE_CATEGORY_THRESHOLD;
+  const pageSize = limit ?? (isLarge ? DEFAULT_PAGE_SIZE : void 0);
+  const page = pageSize ? tokens.slice(offset, offset + pageSize) : tokens.slice(offset);
+  const response = {
+    category: matchKey,
+    total: tokens.length,
+    showing: page.length,
+    tokens: toResponseTokens(page)
+  };
+  const nextOffset = offset + page.length;
+  if (nextOffset < tokens.length) {
+    response.hint = `Use \`offset: ${nextOffset}\` to retrieve more, or \`limit: ${tokens.length}\` to retrieve all`;
+  }
+  return response;
+}
+function registerGetTokens(server) {
+  server.registerTool(
+    "get_tokens",
+    {
+      title: "Get Tokens",
+      description: 'Returns Nimbus design tokens. No params: lists all categories with counts. With category: returns tokens in that category (large categories are paginated by default). With value: reverse-lookup to find which tokens resolve to that value (e.g. "16px" \u2192 spacing.400).',
+      inputSchema: {
+        category: z2.string().optional().describe(
+          'Token category to retrieve, e.g. "spacing", "color", "fontSize". Use "colorPalettes" to list available palette names for the colorPalette prop. Case-insensitive.'
+        ),
+        value: z2.string().optional().describe(
+          'Reverse-lookup: find tokens whose resolved value matches this string, e.g. "16px" or "#0969DA". Case-insensitive.'
+        ),
+        offset: z2.number().int().min(0).default(0).describe(
+          "Starting index for paginated results. Only applies when category is provided. Omit or pass 0 for the first page."
+        ),
+        limit: z2.number().int().positive().optional().describe(
+          `Maximum number of tokens to return per page. Only applies when category is provided. Defaults to all for small categories, ${DEFAULT_PAGE_SIZE} for large categories (> ${LARGE_CATEGORY_THRESHOLD} tokens).`
+        )
+      }
+    },
+    async ({ category, value, offset, limit }) => {
+      try {
+        const data = await getFlatTokenData();
+        if (value !== void 0) {
+          const matches = reverseLookup(data, value);
+          if (matches.length === 0) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `No tokens found for value "${value}".`
+                }
+              ]
+            };
+          }
+          const payload2 = {
+            value,
+            tokens: matches
+          };
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload2) }]
+          };
+        }
+        if (category !== void 0 && category.toLowerCase() === "colorpalettes") {
+          const colorTokens2 = data.byCategory["color"];
+          if (!colorTokens2) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: "No color tokens available."
+                }
+              ],
+              isError: true
+            };
+          }
+          const palettes = getCachedPalettes(colorTokens2);
+          return {
+            content: [
+              { type: "text", text: JSON.stringify(palettes) }
+            ]
+          };
+        }
+        if (category !== void 0) {
+          const matchKey = findCategoryKey(data, category);
+          if (!matchKey) {
+            const available = Object.keys(data.byCategory).sort().join(", ");
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Category "${category}" not found. Available categories: ${available}`
+                }
+              ],
+              isError: true
+            };
+          }
+          let tokens = data.byCategory[matchKey];
+          if (matchKey === "color") {
+            tokens = tokens.filter((t) => !isExcludedAlphaPalette(t));
+          }
+          const payload2 = buildCategoryResponse(
+            matchKey,
+            tokens,
+            offset,
+            limit
+          );
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload2) }]
+          };
+        }
+        const virtualCategories = [];
+        const colorTokens = data.byCategory["color"];
+        if (colorTokens) {
+          const palettes = getCachedPalettes(colorTokens);
+          const paletteCount = Object.values(palettes).reduce(
+            (sum, group) => sum + group.length,
+            0
+          );
+          virtualCategories.push({
+            category: "colorPalettes",
+            count: paletteCount
+          });
+        }
+        const payload = listCategories(data, virtualCategories);
+        return {
+          content: [{ type: "text", text: JSON.stringify(payload) }]
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Token data is not available in this environment."
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/list-components.ts
+import { z as z3 } from "zod";
+function toSummary(route) {
+  const summary = {
+    title: route.title,
+    description: route.description,
+    path: route.path
+  };
+  if (route.exportName) summary.exportName = route.exportName;
+  const subcategory = route.menu[1];
+  if (subcategory) summary.subcategory = subcategory;
+  if (route.tags.length > 0) summary.tags = route.tags;
+  return summary;
+}
+function toLowered(r) {
+  const title = r.title.toLowerCase();
+  const description = r.description.toLowerCase();
+  const tags = [...r.tags, r.exportName ?? ""].join(" ").toLowerCase();
+  return {
+    title,
+    description,
+    tags,
+    content: "",
+    combined: title + " " + description + " " + tags
+  };
+}
+function registerListComponents(server) {
+  server.registerTool(
+    "list_components",
+    {
+      title: "List Components",
+      description: "Returns Nimbus components. Optionally filter by subcategory or fuzzy-search by name, description, or tags.",
+      inputSchema: {
+        category: z3.string().optional().describe(
+          'Filter by subcategory, e.g. "Inputs", "Buttons", "Navigation". Case-insensitive.'
+        ),
+        query: z3.string().optional().describe(
+          "Fuzzy search query over component name, description, and tags."
+        )
+      }
+    },
+    async ({ category, query }) => {
+      try {
+        const manifest = await getRouteManifest();
+        let routes = manifest.routes.filter(
+          (r) => r.category === "Components" && r.menu.length === 3
+        );
+        if (category) {
+          const needle = category.toLowerCase();
+          routes = routes.filter((r) => r.menu[1]?.toLowerCase() === needle);
+        }
+        if (query) {
+          const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+          const loweredMap = /* @__PURE__ */ new Map();
+          for (const r of routes) {
+            loweredMap.set(r, toLowered(r));
+          }
+          const exactMatches = filterAndRankPreLowered(
+            routes,
+            tokens,
+            (r) => loweredMap.get(r)
+          );
+          if (exactMatches.length > 0) {
+            routes = exactMatches;
+          } else {
+            const fuzzyScored = [];
+            for (const r of routes) {
+              const score = fuzzyScorePreLowered(loweredMap.get(r), tokens);
+              if (score > 0) {
+                fuzzyScored.push({ route: r, score });
+              }
+            }
+            fuzzyScored.sort((a, b) => b.score - a.score);
+            routes = fuzzyScored.map(({ route }) => route);
+          }
+        }
+        const summaries = routes.map(toSummary);
+        return {
+          content: [
+            {
+              type: "text",
+              text: summaries.length > 0 ? JSON.stringify(summaries) : "No components found."
+            }
+          ]
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Component data is not available in this environment."
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/search-docs.ts
+import { z as z4 } from "zod";
+var MAX_RESULTS = 10;
+function deriveToolHint(route) {
+  if (route.includes("design-tokens")) return "get_tokens";
+  if (route.startsWith("components/") || route.startsWith("patterns/"))
+    return "get_component";
+  if (route.startsWith("icons")) return "search_icons";
+  return void 0;
+}
+var SNIPPET_LENGTH = 200;
+var SNIPPET_LEAD = 80;
+var PHASE2_CANDIDATE_LIMIT = 30;
+var MIN_CANDIDATES = 10;
+var loweredFieldsCache;
+var loweredFieldsIndexRef;
+function getLoweredFields(index) {
+  if (loweredFieldsCache && loweredFieldsIndexRef === index)
+    return loweredFieldsCache;
+  const map = /* @__PURE__ */ new Map();
+  for (const entry of index) {
+    if (entry._lower) {
+      map.set(entry, entry._lower);
+    } else {
+      const title = entry.title.toLowerCase();
+      const description = entry.description.toLowerCase();
+      const tags = entry.tags.join(" ").toLowerCase();
+      const content = entry.content?.toLowerCase() ?? "";
+      map.set(entry, {
+        title,
+        description,
+        tags,
+        content,
+        combined: title + " " + description + " " + tags + " " + content,
+        titleNoSpaces: title.replace(/\s+/g, ""),
+        descriptionNoSpaces: description.replace(/\s+/g, ""),
+        tagsNoSpaces: tags.replace(/\s+/g, ""),
+        titleWords: title.split(/\s+/).filter(Boolean),
+        descriptionWords: description.split(/\s+/).filter(Boolean),
+        tagsWords: tags.split(/\s+/).filter(Boolean)
+      });
+    }
+  }
+  loweredFieldsCache = map;
+  loweredFieldsIndexRef = index;
+  return map;
+}
+function extractSnippet(content, tokens) {
+  const lower = content.toLowerCase();
+  let bestIndex = -1;
+  for (const token of tokens) {
+    const idx = lower.indexOf(token);
+    if (idx !== -1 && (bestIndex === -1 || idx < bestIndex)) {
+      bestIndex = idx;
+    }
+  }
+  if (bestIndex === -1) {
+    return content.slice(0, SNIPPET_LENGTH).trim() + (content.length > SNIPPET_LENGTH ? "\u2026" : "");
+  }
+  const start = Math.max(0, bestIndex - SNIPPET_LEAD);
+  const end = Math.min(content.length, start + SNIPPET_LENGTH);
+  let snippet = content.slice(start, end).trim();
+  if (start > 0) snippet = "\u2026" + snippet;
+  if (end < content.length) snippet = snippet + "\u2026";
+  return snippet;
+}
+function routeToSlug(route) {
+  return route.replace(/\//g, "-");
+}
+var viewContentCache = /* @__PURE__ */ new WeakMap();
+function getCachedViewContent(viewObj) {
+  let cached = viewContentCache.get(viewObj);
+  if (!cached) {
+    const stripped = stripMarkdown(viewObj.mdx);
+    cached = { stripped, lower: stripped.toLowerCase() };
+    viewContentCache.set(viewObj, cached);
+  }
+  return cached;
+}
+function findCandidates(index, query, tokens, loweredMap) {
+  const exactMatches = filterAndRankPreLowered(
+    index,
+    tokens,
+    (entry) => loweredMap.get(entry)
+  );
+  if (exactMatches.length >= MIN_CANDIDATES) {
+    return { matched: exactMatches, expanded: [] };
+  }
+  const seen = new Set(exactMatches.map((e) => e.id));
+  const partialScored = [];
+  for (const entry of index) {
+    if (seen.has(entry.id)) continue;
+    const fields = loweredMap.get(entry);
+    const score = scorePreLowered(fields, tokens);
+    if (score > 0) {
+      partialScored.push({ entry, score });
+    }
+  }
+  partialScored.sort((a, b) => b.score - a.score);
+  const matched = [...exactMatches];
+  for (const { entry } of partialScored) {
+    seen.add(entry.id);
+    matched.push(entry);
+  }
+  if (matched.length < MIN_CANDIDATES) {
+    const fuzzyScored = [];
+    for (const entry of index) {
+      if (seen.has(entry.id)) continue;
+      const fields = loweredMap.get(entry);
+      const score = fuzzyScorePreLowered(fields, tokens);
+      if (score > 0) {
+        fuzzyScored.push({ entry, score });
+      }
+    }
+    fuzzyScored.sort((a, b) => b.score - a.score);
+    for (const { entry } of fuzzyScored) {
+      seen.add(entry.id);
+      matched.push(entry);
+    }
+  }
+  const expanded = [];
+  if (matched.length < MIN_CANDIDATES) {
+    for (const entry of index) {
+      if (!seen.has(entry.id) && entry.tags.includes("component")) {
+        seen.add(entry.id);
+        expanded.push(entry);
+      }
+    }
+  }
+  return { matched, expanded };
+}
+var routeViewsCache = /* @__PURE__ */ new Map();
+async function getRouteViews(route) {
+  const slug = routeToSlug(route);
+  const cached = routeViewsCache.get(slug);
+  if (cached) return cached;
+  let routeData;
+  try {
+    routeData = await getRouteData(slug);
+  } catch {
+    const empty = { views: [], combinedLower: "" };
+    routeViewsCache.set(slug, empty);
+    return empty;
+  }
+  const MATCH_LIMIT = 2048;
+  const rawViews = [];
+  if (routeData.views) {
+    for (const [key, view] of Object.entries(routeData.views)) {
+      if (view.mdx) {
+        const { stripped, lower } = getCachedViewContent(view);
+        rawViews.push({
+          key,
+          content: stripped,
+          lower,
+          matchLower: lower.length > MATCH_LIMIT ? lower.slice(0, MATCH_LIMIT) : lower
+        });
+      }
+    }
+  } else if (routeData.mdx) {
+    const { stripped, lower } = getCachedViewContent({ mdx: routeData.mdx });
+    rawViews.push({
+      key: "overview",
+      content: stripped,
+      lower,
+      matchLower: lower.length > MATCH_LIMIT ? lower.slice(0, MATCH_LIMIT) : lower
+    });
+  }
+  rawViews.sort((a, b) => a.matchLower.length - b.matchLower.length);
+  const views = rawViews;
+  const result = {
+    views,
+    combinedLower: views.map((v) => v.lower.slice(0, MATCH_LIMIT)).join(" ")
+  };
+  routeViewsCache.set(slug, result);
+  return result;
+}
+function searchRouteViewsSync(route, tokens) {
+  const slug = routeToSlug(route);
+  const cached = routeViewsCache.get(slug);
+  if (!cached) return null;
+  const { views } = cached;
+  if (views.length === 0) return null;
+  const tokenCount = tokens.length;
+  let bestView = null;
+  let bestHits = 0;
+  for (const view of views) {
+    let hits = 0;
+    for (let i = 0; i < tokenCount; i++) {
+      if (view.matchLower.includes(tokens[i])) hits++;
+    }
+    if (hits === tokenCount) {
+      return { viewKey: view.key, content: view.content };
+    }
+    if (hits > bestHits) {
+      bestHits = hits;
+      bestView = view;
+    }
+  }
+  return bestView && bestHits > 0 ? { viewKey: bestView.key, content: bestView.content } : null;
+}
+async function warmAndSearchViews(candidates, tokens) {
+  await Promise.all(candidates.map((e) => getRouteViews(e.route)));
+  const results = /* @__PURE__ */ new Map();
+  for (const entry of candidates) {
+    results.set(entry.id, searchRouteViewsSync(entry.route, tokens));
+  }
+  return results;
+}
+function registerSearchDocs(server) {
+  server.registerTool(
+    "search_docs",
+    {
+      title: "Search Docs",
+      description: "Search all Nimbus docs (components, patterns, hooks, icons, tokens) including guidelines and accessibility views. Returns matching pages with content snippets. Props are not searchable here \u2014 use get_component with section='props' for prop details. Results include a toolHint field indicating which tool to call for deeper info (e.g. get_component, get_tokens, search_icons).",
+      inputSchema: {
+        query: z4.string().describe(
+          'Search query to find relevant documentation pages. e.g. "form validation", "color tokens", "accessibility", "onChange".'
+        )
+      }
+    },
+    async ({ query }) => {
+      try {
+        const index = await getSearchIndex();
+        const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+        const loweredMap = getLoweredFields(index);
+        const { matched, expanded } = findCandidates(
+          index,
+          query,
+          tokens,
+          loweredMap
+        );
+        const matchedCapped = matched.slice(0, PHASE2_CANDIDATE_LIMIT);
+        const expandedCapped = expanded.slice(
+          0,
+          Math.max(0, PHASE2_CANDIDATE_LIMIT - matchedCapped.length)
+        );
+        const allCandidates = [...matchedCapped, ...expandedCapped];
+        const matchedIds = new Set(matched.map((e) => e.id));
+        const phase1Scores = /* @__PURE__ */ new Map();
+        for (const entry of allCandidates) {
+          phase1Scores.set(
+            entry.id,
+            scorePreLowered(loweredMap.get(entry), tokens)
+          );
+        }
+        const viewResults = await warmAndSearchViews(allCandidates, tokens);
+        const loaded = allCandidates.map((entry) => ({
+          entry,
+          viewMatch: viewResults.get(entry.id) ?? null,
+          wasMatched: matchedIds.has(entry.id),
+          phase1Score: phase1Scores.get(entry.id)
+        }));
+        const relevant = loaded.filter(
+          ({ viewMatch, wasMatched }) => wasMatched || viewMatch !== null
+        );
+        relevant.sort((a, b) => {
+          const aScore = (a.viewMatch ? 1e3 : 0) + a.phase1Score;
+          const bScore = (b.viewMatch ? 1e3 : 0) + b.phase1Score;
+          return bScore - aScore;
+        });
+        const output = relevant.slice(0, MAX_RESULTS).map(({ entry, viewMatch }) => {
+          const category = entry.menu[0];
+          const toolHint = deriveToolHint(entry.route);
+          return {
+            title: entry.title,
+            description: entry.description,
+            path: entry.route,
+            ...category ? { category } : {},
+            ...viewMatch && viewMatch.viewKey !== "overview" ? { matchedView: viewMatch.viewKey } : {},
+            snippet: viewMatch ? extractSnippet(viewMatch.content, tokens) : extractSnippet(stripMarkdown(entry.content), tokens),
+            ...toolHint ? { toolHint } : {}
+          };
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: output.length > 0 ? JSON.stringify(output) : "No matching documentation found."
+            }
+          ]
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Search index is not available in this environment."
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/search-icons.ts
+import { z as z5 } from "zod";
+var PAGE_SIZE = 10;
+var MIN_KEYWORD_LENGTH = 2;
+var MIN_CANDIDATES2 = 10;
+var loweredCache;
+var loweredCacheIcons;
+async function getLoweredIconFields() {
+  const catalog = await getIconCatalog();
+  if (loweredCache && loweredCacheIcons === catalog.icons) {
+    return { icons: catalog.icons, loweredMap: loweredCache };
+  }
+  const map = /* @__PURE__ */ new Map();
+  for (const icon of catalog.icons) {
+    const title = icon.name.toLowerCase();
+    const tags = icon.keywords.filter((kw) => kw.length >= MIN_KEYWORD_LENGTH).join(" ").toLowerCase();
+    map.set(icon, {
+      title,
+      description: "",
+      tags,
+      content: "",
+      combined: title + " " + tags
+    });
+  }
+  loweredCache = map;
+  loweredCacheIcons = catalog.icons;
+  return { icons: catalog.icons, loweredMap: map };
+}
+async function searchIcons(query) {
+  const { icons, loweredMap } = await getLoweredIconFields();
+  const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const exactMatches = filterAndRankPreLowered(
+    icons,
+    tokens,
+    (icon) => loweredMap.get(icon)
+  );
+  if (exactMatches.length >= MIN_CANDIDATES2) {
+    return exactMatches;
+  }
+  const seen = new Set(exactMatches.map((e) => e.name));
+  const fuzzyScored = [];
+  for (const icon of icons) {
+    if (seen.has(icon.name)) continue;
+    const fields = loweredMap.get(icon);
+    const score = fuzzyScorePreLowered(fields, tokens);
+    if (score > 0) {
+      fuzzyScored.push({ icon, score });
+    }
+  }
+  fuzzyScored.sort((a, b) => b.score - a.score);
+  return [...exactMatches, ...fuzzyScored.map(({ icon }) => icon)];
+}
+function registerSearchIcons(server) {
+  server.registerTool(
+    "search_icons",
+    {
+      title: "Search Icons",
+      description: `Fuzzy-search Nimbus icons by name or keyword. Returns matching icon names with import paths from @commercetools/nimbus-icons. Results are paginated (${PAGE_SIZE} per page). Use the offset parameter to retrieve additional results.`,
+      inputSchema: {
+        query: z5.string().min(1).describe(
+          'Search query to match against icon names and keywords, e.g. "checkmark", "arrow", "settings".'
+        ),
+        offset: z5.number().int().min(0).default(0).describe(
+          "Starting index for paginated results. Omit or pass 0 for the first page."
+        )
+      }
+    },
+    async ({ query, offset }) => {
+      try {
+        const allResults = await searchIcons(query);
+        const page = allResults.slice(offset, offset + PAGE_SIZE);
+        const hasMore = offset + PAGE_SIZE < allResults.length;
+        const payload = {
+          query,
+          importPath: "@commercetools/nimbus-icons",
+          totalResults: allResults.length,
+          offset,
+          pageSize: PAGE_SIZE,
+          hasMore,
+          results: page.map(({ name, category, keywords }) => ({
+            name,
+            category,
+            keywords
+          }))
+        };
+        if (hasMore) {
+          payload.hint = `Use \`offset: ${offset + PAGE_SIZE}\` for more results (${allResults.length} total).`;
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(payload)
+            }
+          ]
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Icon catalog is not available in this environment."
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/migrate-from-uikit.ts
+import { readFile as readFile3 } from "fs/promises";
+import { z as z6 } from "zod";
+
+// src/data/uikit-migration.ts
+var MIGRATION_DATA = [
+  // -------------------------------------------------------------------------
+  // Buttons
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "AccessibleButton",
+    nimbusEquivalent: "Button",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Use <Button> directly. Nimbus Button is accessible by default; no wrapper needed. UI Kit used a required label prop for button text; Nimbus uses children.",
+    breakingChanges: [
+      "Remove AccessibleButton wrapper, use <Button> directly",
+      "label prop replaced by children"
+    ]
+  },
+  {
+    uiKitName: "FlatButton",
+    nimbusEquivalent: "Button",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: `Use <Button variant="ghost"> for flat styling. UI Kit tone prop ('primary'|'secondary'|'inverted'|'critical') maps to Nimbus colorPalette/variant.`,
+    breakingChanges: [
+      "Replace FlatButton with <Button>",
+      "label prop replaced by children",
+      "tone prop replaced by variant/colorPalette",
+      "iconPosition prop removed; pass icon as a child of <Button>"
+    ]
+  },
+  {
+    uiKitName: "LinkButton",
+    nimbusEquivalent: "Button",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Button variant="link" asChild> wrapping a router Link, or use <Button as="a" href="...">. UI Kit used a to prop (React Router LocationDescriptor); Nimbus uses href or asChild pattern.',
+    breakingChanges: [
+      "Replace LinkButton with <Button asChild> or <Button as='a'>",
+      "label prop replaced by children",
+      "to prop replaced by href (or use asChild with router Link)",
+      "isExternal prop replaced by target='_blank' rel='noopener noreferrer'",
+      "iconLeft prop removed; pass icon as a child of <Button>"
+    ]
+  },
+  {
+    uiKitName: "PrimaryButton",
+    nimbusEquivalent: "Button",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Button variant="solid">. Note: the default Button variant is "subtle", so variant="solid" must be set explicitly. UI Kit used a required label prop; Nimbus uses children for button text.',
+    breakingChanges: [
+      "Replace PrimaryButton with <Button variant='solid'>",
+      "label prop replaced by children",
+      "iconLeft/iconRight props removed; pass icon as a child of <Button>",
+      "tone prop ('urgent'|'primary'|'critical') replaced by colorPalette"
+    ]
+  },
+  {
+    uiKitName: "SecondaryButton",
+    nimbusEquivalent: "Button",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Button variant="outline"> for the secondary style. UI Kit used a required label prop; Nimbus uses children.',
+    breakingChanges: [
+      "Replace SecondaryButton with <Button variant='outline'>",
+      "label prop replaced by children",
+      "iconLeft/iconRight props removed; pass icon as a child of <Button>",
+      "theme prop ('default'|'info') replaced by colorPalette"
+    ]
+  },
+  {
+    uiKitName: "IconButton",
+    nimbusEquivalent: "IconButton",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. UI Kit passed the icon via an icon prop and used label for accessibility; Nimbus passes icon as children and uses aria-label.",
+    breakingChanges: [
+      "label prop replaced by aria-label",
+      "icon prop replaced by icon as children",
+      "theme prop replaced by variant/colorPalette"
+    ]
+  },
+  {
+    uiKitName: "SecondaryIconButton",
+    nimbusEquivalent: "IconButton",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: `Use <IconButton variant="outline"> or equivalent. UI Kit used a color prop ('solid'|'primary'|'info'); Nimbus uses variant/colorPalette.`,
+    breakingChanges: [
+      "Replace SecondaryIconButton with <IconButton>",
+      "color prop ('solid'|'primary'|'info') replaced by variant/colorPalette",
+      "icon prop replaced by icon as children",
+      "label prop replaced by aria-label"
+    ]
+  },
+  {
+    uiKitName: "PrimaryActionDropdown",
+    nimbusEquivalent: "SplitButton",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "SplitButton combines a primary action button with a dropdown menu. Compose using SplitButton + Menu.",
+    breakingChanges: [
+      "Rename to SplitButton",
+      "Menu items now use Nimbus Menu composition pattern"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Form inputs — text
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "TextInput",
+    nimbusEquivalent: "TextInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. UI Kit onChange was ChangeEvent<HTMLInputElement>; Nimbus (React Aria) onChange receives a string value directly. hasError/hasWarning replaced by isInvalid. isAutofocussed replaced by autoFocus.",
+    breakingChanges: [
+      "onChange now receives a string value instead of ChangeEvent<HTMLInputElement>",
+      "hasError prop replaced by isInvalid",
+      "hasWarning prop removed",
+      "isAutofocussed replaced by autoFocus",
+      "isCondensed prop replaced by size='sm'"
+    ]
+  },
+  {
+    uiKitName: "TextField",
+    nimbusEquivalent: "TextInputField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "TextInputField wraps TextInput with label, description, and error message slots. UI Kit used title for the label text, hint for helper text, and errors (Record) for validation.",
+    breakingChanges: [
+      "Rename to TextInputField",
+      "title prop renamed to label",
+      "hint prop renamed to description",
+      "errors (Record<string, boolean>) replaced by passing <FieldErrors> to the errorMessage prop",
+      "warnings prop removed",
+      "touched prop removed",
+      "onChange now receives a string value instead of ChangeEvent<HTMLInputElement>"
+    ]
+  },
+  {
+    uiKitName: "MultilineTextInput",
+    nimbusEquivalent: "MultilineTextInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. UI Kit onChange was ChangeEvent<HTMLTextAreaElement>; Nimbus onChange receives a string value. hasError replaced by isInvalid.",
+    breakingChanges: [
+      "onChange now receives a string value instead of ChangeEvent<HTMLTextAreaElement>",
+      "hasError prop replaced by isInvalid",
+      "hasWarning prop removed",
+      "isAutofocussed replaced by autoFocus"
+    ]
+  },
+  {
+    uiKitName: "MultilineTextField",
+    nimbusEquivalent: "MultilineTextInputField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Wraps MultilineTextInput with label, description, and error message. UI Kit used title for the label text and hint for helper text.",
+    breakingChanges: [
+      "Rename to MultilineTextInputField",
+      "title prop renamed to label",
+      "hint prop renamed to description",
+      "errors (Record) replaced by passing <FieldErrors> to the errorMessage prop",
+      "warnings prop removed",
+      "onChange now receives a string value instead of ChangeEvent<HTMLTextAreaElement>"
+    ]
+  },
+  {
+    uiKitName: "PasswordInput",
+    nimbusEquivalent: "PasswordInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Toggle visibility button is built in. UI Kit onChange was ChangeEvent<HTMLInputElement>; Nimbus onChange receives a string.",
+    breakingChanges: [
+      "onChange now receives a string value instead of ChangeEvent<HTMLInputElement>",
+      "hasError prop replaced by isInvalid",
+      "isAutofocussed replaced by autoFocus"
+    ]
+  },
+  {
+    uiKitName: "PasswordField",
+    nimbusEquivalent: "PasswordInputField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Wraps PasswordInput with label and error message slots.",
+    breakingChanges: [
+      "Rename to PasswordInputField",
+      "title prop renamed to label",
+      "hint prop renamed to description",
+      "errors (Record) replaced by passing <FieldErrors> to the errorMessage prop"
+    ]
+  },
+  {
+    uiKitName: "SearchSelectInput",
+    nimbusEquivalent: "ComboBox",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Use ComboBox for a searchable select dropdown. Pass options via the items prop and render each with ComboBox.Item. ComboBox handles filtering natively.",
+    breakingChanges: [
+      "Rename to ComboBox",
+      "options array replaced by items prop with ComboBox.Item render function",
+      "onChange received TCustomEvent; now receives selected key directly"
+    ]
+  },
+  {
+    uiKitName: "SearchSelectField",
+    nimbusEquivalent: "ComboBox + FormField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "compound",
+    notes: "Wrap ComboBox in a FormField to add label, description, and error message. There is no standalone ComboBoxField component.",
+    breakingChanges: [
+      "Compose FormField + ComboBox manually",
+      "title prop replaced by FormField label",
+      "hint prop replaced by FormField description",
+      "errors (Record) replaced by passing <FieldErrors> as a child of FormField.Error"
+    ]
+  },
+  {
+    uiKitName: "SelectableSearchInput",
+    nimbusEquivalent: "ScopedSearchInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "ScopedSearchInput adds a scope/category selector alongside the search field.",
+    breakingChanges: [
+      "Rename to ScopedSearchInput",
+      "scope options now use items prop with ScopedSearchInput.Item children"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Form inputs — select / combobox
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "SelectInput",
+    nimbusEquivalent: "Select",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Select accepts an items prop with a Select.Item render function. UI Kit onChange received a TCustomEvent with target.value (string); Nimbus onChange receives the selected key directly. UI Kit option shape: { value: string, label: ReactNode, isDisabled?: boolean }.",
+    breakingChanges: [
+      "Rename to Select",
+      "options array ({value, label}) replaced by items prop with Select.Item render function",
+      "onChange received TCustomEvent (target.value); now receives selected key directly",
+      "isMulti support changed; check Nimbus Select API for multi-select",
+      "appearance prop ('default'|'quiet'|'filter') replaced by variant"
+    ]
+  },
+  {
+    uiKitName: "CreatableSelectInput",
+    nimbusEquivalent: "ComboBox",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "ComboBox supports both selection and free-text entry. Use allowsCustomOptions prop for creatable behavior. UI Kit onCreateOption callback is replaced by handling new values in onInputChange.",
+    breakingChanges: [
+      "Rename to ComboBox",
+      "options array replaced by items prop with ComboBox.Item render function",
+      "onCreateOption replaced by allowsCustomOptions + custom onInputChange logic",
+      "onChange received TCustomEvent; now receives selected key directly"
+    ]
+  },
+  {
+    uiKitName: "AsyncCreatableSelectInput",
+    nimbusEquivalent: "ComboBox",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Use ComboBox with allowsCustomOptions and manage async loading via onInputChange + external state. UI Kit provided a loadOptions callback; in Nimbus this is managed externally.",
+    breakingChanges: [
+      "Rename to ComboBox",
+      "loadOptions callback replaced by onInputChange + external async fetch + items state",
+      "onCreateOption replaced by allowsCustomOptions + custom logic",
+      "onChange received TCustomEvent; now receives selected key directly"
+    ]
+  },
+  {
+    uiKitName: "AsyncSelectInput",
+    nimbusEquivalent: "ComboBox",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Use ComboBox and manage async options loading via onInputChange + external state. UI Kit provided a loadOptions callback; in Nimbus this is managed externally.",
+    breakingChanges: [
+      "Rename to ComboBox",
+      "loadOptions callback replaced by onInputChange + external async fetch + items state",
+      "onChange received TCustomEvent; now receives selected key directly"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Form inputs — number / money
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "NumberInput",
+    nimbusEquivalent: "NumberInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. UI Kit value was string|number and onChange was ChangeEvent<HTMLInputElement>; Nimbus value is a number and onChange receives a number directly. min/max/step prop names unchanged.",
+    breakingChanges: [
+      "onChange now receives a number instead of ChangeEvent<HTMLInputElement>",
+      "value was string|number; now must be a number",
+      "hasError prop replaced by isInvalid",
+      "isAutofocussed replaced by autoFocus"
+    ]
+  },
+  {
+    uiKitName: "NumberField",
+    nimbusEquivalent: "NumberInputField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Wraps NumberInput with label, description, and error message. UI Kit used title for the label text and hint for helper text.",
+    breakingChanges: [
+      "Rename to NumberInputField",
+      "title prop renamed to label",
+      "hint prop renamed to description",
+      "errors (Record) replaced by passing <FieldErrors> to the errorMessage prop"
+    ]
+  },
+  {
+    uiKitName: "MoneyInput",
+    nimbusEquivalent: "MoneyInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Currency selector and amount field are composed internally. UI Kit value shape was { amount: string, currencyCode: string }; Nimbus keeps the same shape. UI Kit onChange received a TCustomEvent (not a plain object); check Nimbus onChange signature.",
+    breakingChanges: [
+      "onChange received TCustomEvent; now receives { amount, currencyCode } directly",
+      "currencies prop for available currency options unchanged",
+      "hasError prop replaced by isInvalid"
+    ]
+  },
+  {
+    uiKitName: "MoneyField",
+    nimbusEquivalent: "MoneyInputField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Wraps MoneyInput with label, description, and error message. UI Kit used title for the label text and hint for helper text.",
+    breakingChanges: [
+      "Rename to MoneyInputField",
+      "title prop renamed to label",
+      "hint prop renamed to description",
+      "errors (Record) replaced by passing <FieldErrors> to the errorMessage prop"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Form inputs — date / time
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "DateInput",
+    nimbusEquivalent: "DatePicker",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "DatePicker uses @internationalized/date value types (CalendarDate). UI Kit value was a string ('YYYY-MM-DD' or ''); onChange received a TCustomEvent with a string value. Nimbus value is a CalendarDate object and onChange receives a CalendarDate.",
+    breakingChanges: [
+      "Rename to DatePicker",
+      "value changed from 'YYYY-MM-DD' string to CalendarDate from @internationalized/date",
+      "onChange received TCustomEvent with string; now receives CalendarDate directly",
+      "minValue/maxValue changed from strings to CalendarDate objects"
+    ]
+  },
+  {
+    uiKitName: "DateTimeInput",
+    nimbusEquivalent: "DatePicker",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Use DatePicker with granularity='minute' or 'second' to include time selection.",
+    breakingChanges: [
+      "Rename to DatePicker",
+      "value must be a ZonedDateTime or CalendarDateTime",
+      "Use granularity prop to enable time fields"
+    ]
+  },
+  {
+    uiKitName: "DateRangeInput",
+    nimbusEquivalent: "DateRangePicker",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "DateRangePicker uses { start: CalendarDate, end: CalendarDate } value shape.",
+    breakingChanges: [
+      "Rename to DateRangePicker",
+      "value shape changed to { start, end } using CalendarDate"
+    ]
+  },
+  {
+    uiKitName: "DateRangeField",
+    nimbusEquivalent: "DateRangePickerField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Wraps DateRangePicker with label and error message.",
+    breakingChanges: ["Rename to DateRangePickerField"]
+  },
+  {
+    uiKitName: "TimeInput",
+    nimbusEquivalent: "TimeInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. value must be a Time object from @internationalized/date.",
+    breakingChanges: ["value must be a Time from @internationalized/date"]
+  },
+  // -------------------------------------------------------------------------
+  // Form inputs — checkbox / radio / toggle
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "CheckboxInput",
+    nimbusEquivalent: "Checkbox",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Rename to Checkbox. UI Kit used isChecked and onChange: ChangeEventHandler<HTMLInputElement>; Nimbus uses isSelected and onChange receives a boolean directly.",
+    breakingChanges: [
+      "Rename to Checkbox",
+      "isChecked prop renamed to isSelected",
+      "onChange received ChangeEvent<HTMLInputElement>; now receives boolean isSelected directly"
+    ]
+  },
+  {
+    uiKitName: "RadioInput",
+    nimbusEquivalent: "RadioInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Group radios with RadioGroup parent for accessible keyboard navigation.",
+    breakingChanges: ["Wrap in RadioGroup for group behavior"]
+  },
+  {
+    uiKitName: "ToggleInput",
+    nimbusEquivalent: "Switch",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Rename to Switch. UI Kit used isChecked and onChange: ChangeEventHandler<HTMLInputElement> (target.checked); Nimbus Switch uses isSelected and onChange receives a boolean directly.",
+    breakingChanges: [
+      "Rename to Switch",
+      "isChecked prop renamed to isSelected",
+      "onChange received ChangeEvent (target.checked); now receives boolean isSelected directly",
+      "size prop ('small'|'big') replaced by Nimbus size tokens"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Form inputs — localized
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "LocalizedTextInput",
+    nimbusEquivalent: "LocalizedField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <LocalizedField type="text"> (the default type). LocalizedField manages all locale inputs internally via its type prop.',
+    breakingChanges: [
+      "Replace LocalizedTextInput with <LocalizedField> (type='text' is the default)",
+      "selectedLanguage prop replaced by defaultLocaleOrCurrency",
+      "value per locale replaced by valuesByLocaleOrCurrency object",
+      "onChange receives a LocalizedFieldChangeEvent with target.locale"
+    ]
+  },
+  {
+    uiKitName: "LocalizedTextField",
+    nimbusEquivalent: "LocalizedField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <LocalizedField type="text"> with label, description, and error props. LocalizedField is already a field-level component with built-in label and error slots.',
+    breakingChanges: [
+      "Replace LocalizedTextField with <LocalizedField> (type='text' is the default)",
+      "title prop renamed to label",
+      "hint prop renamed to description",
+      "errors (Record) replaced by errorsByLocaleOrCurrency",
+      "onChange receives a LocalizedFieldChangeEvent with target.locale"
+    ]
+  },
+  {
+    uiKitName: "LocalizedMultilineTextInput",
+    nimbusEquivalent: "LocalizedField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <LocalizedField type="multiLine">. The type prop controls the input variant; no child composition needed.',
+    breakingChanges: [
+      "Replace LocalizedMultilineTextInput with <LocalizedField type='multiLine'>",
+      "selectedLanguage prop replaced by defaultLocaleOrCurrency",
+      "value per locale replaced by valuesByLocaleOrCurrency object",
+      "onChange receives a LocalizedFieldChangeEvent with target.locale"
+    ]
+  },
+  {
+    uiKitName: "LocalizedMultilineTextField",
+    nimbusEquivalent: "LocalizedField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <LocalizedField type="multiLine"> with label, description, and error props. LocalizedField is already a field-level component with built-in label and error slots.',
+    breakingChanges: [
+      "Replace LocalizedMultilineTextField with <LocalizedField type='multiLine'>",
+      "title prop renamed to label",
+      "hint prop renamed to description",
+      "errors (Record) replaced by errorsByLocaleOrCurrency",
+      "onChange receives a LocalizedFieldChangeEvent with target.locale"
+    ]
+  },
+  {
+    uiKitName: "LocalizedMoneyInput",
+    nimbusEquivalent: "LocalizedField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <LocalizedField type="money">. valuesByLocaleOrCurrency accepts a LocalizedCurrency object keyed by currency code.',
+    breakingChanges: [
+      "Replace LocalizedMoneyInput with <LocalizedField type='money'>",
+      "selectedLanguage prop replaced by defaultLocaleOrCurrency (currency code)",
+      "value per currency replaced by valuesByLocaleOrCurrency object",
+      "onChange receives a LocalizedFieldChangeEvent with target.currency"
+    ]
+  },
+  {
+    uiKitName: "LocalizedRichTextInput",
+    nimbusEquivalent: "LocalizedField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <LocalizedField type="richText">. The type prop controls the input variant; no child composition needed.',
+    breakingChanges: [
+      "Replace LocalizedRichTextInput with <LocalizedField type='richText'>",
+      "selectedLanguage prop replaced by defaultLocaleOrCurrency",
+      "value per locale replaced by valuesByLocaleOrCurrency object",
+      "onChange receives a LocalizedFieldChangeEvent with target.locale"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Form structure
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "FieldErrors",
+    nimbusEquivalent: "FieldErrors",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Used inside *Field components for error display.",
+    breakingChanges: []
+  },
+  {
+    uiKitName: "AdditionalInfoMessage",
+    nimbusEquivalent: "Text + FormField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "compound",
+    notes: "Compose FormField with a description prop, or use <Text size='sm' color='neutral.500'>.",
+    breakingChanges: [
+      "Replace AdditionalInfoMessage with FormField description prop or Text component"
+    ]
+  },
+  {
+    uiKitName: "ErrorMessage",
+    nimbusEquivalent: "Text + FormField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "compound",
+    notes: "Use <FieldErrors> passed to a *Field component's errorMessage prop, or as a child of FormField.Error.",
+    breakingChanges: [
+      "Replace ErrorMessage with <FieldErrors> inside a Field errorMessage prop or FormField.Error"
+    ]
+  },
+  {
+    uiKitName: "WarningMessage",
+    nimbusEquivalent: "Text + FormField",
+    importPath: "@commercetools/nimbus",
+    mappingType: "compound",
+    notes: "Use <Text color='warning.500'> or a FormField description for warnings.",
+    breakingChanges: [
+      "Replace WarningMessage with Text + appropriate color token"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Rich text
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "RichTextInput",
+    nimbusEquivalent: "RichTextInput",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Editor toolbar configuration API has changed.",
+    breakingChanges: [
+      "toolbar configuration prop shape has changed; consult Nimbus docs"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Data display
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "Avatar",
+    nimbusEquivalent: "Avatar",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. name prop is still used for initials fallback.",
+    breakingChanges: []
+  },
+  {
+    uiKitName: "Stamp",
+    nimbusEquivalent: "Badge",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Rename to Badge. Both use a tone prop, but the tone values differ. UI Kit tones: 'critical'|'warning'|'positive'|'information'|'primary'|'secondary'. Nimbus tones: 'danger'|'warning'|'success'|'info'.",
+    breakingChanges: [
+      "Rename to Badge",
+      "tone value 'critical' \u2192 'danger'",
+      "tone value 'positive' \u2192 'success'",
+      "tone value 'information' \u2192 'info'",
+      "tone values 'primary' and 'secondary' have no direct equivalent; use 'neutral' or default",
+      "isCondensed prop replaced by size='sm'"
+    ]
+  },
+  {
+    uiKitName: "Tag",
+    nimbusEquivalent: "TagGroup",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Use TagGroup.Root with TagGroup.TagList and a single TagGroup.Tag for a standalone tag. TagGroup manages selection/removal state.",
+    breakingChanges: [
+      "Wrap single Tag in <TagGroup.Root><TagGroup.TagList><TagGroup.Tag>...</TagGroup.Tag></TagGroup.TagList></TagGroup.Root>",
+      "onRemove now receives a key-based Set"
+    ]
+  },
+  {
+    uiKitName: "TagList",
+    nimbusEquivalent: "TagGroup",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Replace TagList with TagGroup.Root + TagGroup.TagList. Each tag becomes a TagGroup.Tag child.",
+    breakingChanges: [
+      "Rename to TagGroup (use TagGroup.Root, TagGroup.TagList, TagGroup.Tag)",
+      "items array replaced by TagGroup.Tag children inside TagGroup.TagList"
+    ]
+  },
+  {
+    uiKitName: "ProgressBar",
+    nimbusEquivalent: "ProgressBar",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. value is a 0\u2013100 number.",
+    breakingChanges: []
+  },
+  {
+    uiKitName: "LoadingSpinner",
+    nimbusEquivalent: "LoadingSpinner",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement.",
+    breakingChanges: []
+  },
+  {
+    uiKitName: "DataTable",
+    nimbusEquivalent: "DataTable",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Column definitions use the new columns prop with accessor keys.",
+    breakingChanges: [
+      "columns prop shape changed to use accessor and header fields",
+      "Row selection API updated to use onSelectionChange with a Set of keys"
+    ]
+  },
+  {
+    uiKitName: "DataTableManager",
+    nimbusEquivalent: "DataTableManager",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Works alongside DataTable for column management.",
+    breakingChanges: []
+  },
+  // -------------------------------------------------------------------------
+  // Navigation
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "Link",
+    nimbusEquivalent: "Link",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Use asChild for router library integration.",
+    breakingChanges: [
+      "isExternal prop renamed to target='_blank' + rel='noopener'"
+    ]
+  },
+  {
+    uiKitName: "DropdownMenu",
+    nimbusEquivalent: "Menu",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Rename to Menu. Uses composable Menu.Root, Menu.Trigger, Menu.Content, and Menu.Item.",
+    breakingChanges: [
+      "Rename to Menu (use Menu.Root, Menu.Trigger, Menu.Content, Menu.Item)",
+      "options array replaced by Menu.Item children inside Menu.Content",
+      "onSelect replaced by onAction on Menu.Item or Menu"
+    ]
+  },
+  {
+    uiKitName: "Pagination",
+    nimbusEquivalent: "Pagination",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. page/totalPages prop names are unchanged.",
+    breakingChanges: ["onPageChange receives a page number directly"]
+  },
+  // -------------------------------------------------------------------------
+  // Overlays
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "Tooltip",
+    nimbusEquivalent: "Tooltip",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Tooltip wraps a trigger element. Use Tooltip.Root (wraps the trigger child) and Tooltip.Content composition.",
+    breakingChanges: [
+      "Compositional API: replace single prop with Tooltip.Root + Tooltip.Content"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Feedback
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "ContentNotification",
+    nimbusEquivalent: "Alert",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Rename to Alert. tone prop replaces type prop for semantic intent.",
+    breakingChanges: [
+      "Rename to Alert",
+      "type prop replaced by tone ('info', 'success', 'warning', 'danger')"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Layout
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "Grid",
+    nimbusEquivalent: "Grid",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Uses Chakra UI Grid props (columns, gap, etc.).",
+    breakingChanges: []
+  },
+  {
+    uiKitName: "Constraints.Horizontal",
+    nimbusEquivalent: "Design tokens",
+    importPath: "@commercetools/nimbus-tokens",
+    mappingType: "pattern",
+    notes: "Replace Constraints.Horizontal with maxWidth design tokens or the Box/Container component.",
+    breakingChanges: [
+      "Remove Constraints.Horizontal",
+      "Use maxWidth prop with design token values on Box or Container"
+    ]
+  },
+  {
+    uiKitName: "Spacings.Inline",
+    nimbusEquivalent: "Stack",
+    importPath: "@commercetools/nimbus",
+    mappingType: "pattern",
+    notes: 'Use <Stack direction="row" gap={...}> with nimbus spacing tokens.',
+    breakingChanges: [
+      "Replace Spacings.Inline with <Stack direction='row'>",
+      "Spacing values use design token scale (e.g. gap='300')"
+    ]
+  },
+  {
+    uiKitName: "Spacings.Inset",
+    nimbusEquivalent: "Box",
+    importPath: "@commercetools/nimbus",
+    mappingType: "pattern",
+    notes: "Use <Box padding={...}> with nimbus spacing tokens for inset padding.",
+    breakingChanges: [
+      "Replace Spacings.Inset with padding prop on Box",
+      "Spacing values use design token scale"
+    ]
+  },
+  {
+    uiKitName: "Spacings.InsetSquish",
+    nimbusEquivalent: "Box",
+    importPath: "@commercetools/nimbus",
+    mappingType: "pattern",
+    notes: "Use <Box paddingX={...} paddingY={...}> with asymmetric nimbus spacing tokens.",
+    breakingChanges: [
+      "Replace Spacings.InsetSquish with paddingX/paddingY props on Box"
+    ]
+  },
+  {
+    uiKitName: "Spacings.Stack",
+    nimbusEquivalent: "Stack",
+    importPath: "@commercetools/nimbus",
+    mappingType: "pattern",
+    notes: 'Use <Stack direction="column" gap={...}> with nimbus spacing tokens.',
+    breakingChanges: [
+      "Replace Spacings.Stack with <Stack direction='column'>",
+      "Spacing values use design token scale"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Structure / containers
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "Card",
+    nimbusEquivalent: "Card",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement. Composable with Card.Root, Card.Header, Card.Content.",
+    breakingChanges: [
+      "Adopt compositional slot API (Card.Root, Card.Header, Card.Content)"
+    ]
+  },
+  {
+    uiKitName: "CollapsiblePanel",
+    nimbusEquivalent: "Accordion",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Rename to Accordion. Uses Accordion.Root, Accordion.Item, Accordion.Header, Accordion.Content composition. UI Kit used isClosed (controlled) + onToggle; the header was a prop, not a child slot.",
+    breakingChanges: [
+      "Rename to Accordion",
+      "Adopt compositional slot API (Accordion.Root, Accordion.Item, Accordion.Header, Accordion.Content)",
+      "isClosed prop replaced by React Aria controlled/uncontrolled pattern",
+      "header prop replaced by Accordion.Header child",
+      "condensed prop removed",
+      "tone prop ('urgent'|'primary') replaced by Nimbus design tokens"
+    ]
+  },
+  {
+    uiKitName: "CollapsibleMotion",
+    nimbusEquivalent: "CollapsibleMotion",
+    importPath: "@commercetools/nimbus",
+    mappingType: "compound",
+    notes: "Uses compound pattern: CollapsibleMotion.Root, CollapsibleMotion.Trigger, CollapsibleMotion.Content. UI Kit used a render prop with isClosed/toggle; Nimbus manages state internally.",
+    breakingChanges: [
+      "Adopt compositional API (CollapsibleMotion.Root, CollapsibleMotion.Trigger, CollapsibleMotion.Content)",
+      "Render prop pattern replaced by compound component children"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Typography
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "Text.Body",
+    nimbusEquivalent: "Text",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Text size="md"> (default size).',
+    breakingChanges: ["Replace Text.Body with <Text> (default size is body)"]
+  },
+  {
+    uiKitName: "Text.Caption",
+    nimbusEquivalent: "Text",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Text size="xs"> for caption-sized text.',
+    breakingChanges: ["Replace Text.Caption with <Text size='xs'>"]
+  },
+  {
+    uiKitName: "Text.Detail",
+    nimbusEquivalent: "Text",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Text size="sm"> for detail/small text.',
+    breakingChanges: ["Replace Text.Detail with <Text size='sm'>"]
+  },
+  {
+    uiKitName: "Text.Headline",
+    nimbusEquivalent: "Text",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Text size="2xl" fontWeight="bold"> or the Heading component.',
+    breakingChanges: [
+      "Replace Text.Headline with <Text size='2xl' fontWeight='bold'> or <Heading>"
+    ]
+  },
+  {
+    uiKitName: "Text.Subheadline",
+    nimbusEquivalent: "Text",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Text size="xl">.',
+    breakingChanges: ["Replace Text.Subheadline with <Text size='xl'>"]
+  },
+  {
+    uiKitName: "Text.Wrap",
+    nimbusEquivalent: "Text",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Use <Text> with the wrapping element set via the as prop.",
+    breakingChanges: [
+      "Replace Text.Wrap with <Text> and control wrapping via CSS/props"
+    ]
+  },
+  {
+    uiKitName: "Label",
+    nimbusEquivalent: "Text",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: 'Use <Text as="label" size="sm" fontWeight="medium"> or FormField label prop.',
+    breakingChanges: [
+      "Replace Label with <Text as='label'> or use FormField label prop"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Icons
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "CustomIcon",
+    nimbusEquivalent: "Icon",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Use <Icon> component wrapping an SVG, or use InlineSvg for custom SVGs.",
+    breakingChanges: [
+      "Replace CustomIcon with <Icon> or <InlineSvg>",
+      "SVG must be passed as a child or via as prop"
+    ]
+  },
+  {
+    uiKitName: "LeadingIcon",
+    nimbusEquivalent: "Icon",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Pass icon as a child to the parent component (e.g. as a child of <Button>) rather than using a wrapper.",
+    breakingChanges: [
+      "Remove LeadingIcon wrapper",
+      "Pass icon directly to the parent component's icon slot"
+    ]
+  },
+  {
+    uiKitName: "InlineSvg",
+    nimbusEquivalent: "InlineSvg",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Direct replacement for custom SVG icons not in the icon library.",
+    breakingChanges: []
+  },
+  {
+    uiKitName: "Icon Library",
+    nimbusEquivalent: "Material Icon Library",
+    importPath: "@commercetools/nimbus-icons",
+    mappingType: "pattern",
+    notes: "Import icons from @commercetools/nimbus-icons. Icons are named SvgIconName (e.g. SvgAccountCircle).",
+    breakingChanges: [
+      "Update import paths to @commercetools/nimbus-icons",
+      "Icon names follow Svg prefix convention"
+    ]
+  },
+  // -------------------------------------------------------------------------
+  // Accessibility utilities
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "HiddenInput",
+    nimbusEquivalent: "VisuallyHidden",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "VisuallyHidden renders content that is visually hidden but accessible to screen readers.",
+    breakingChanges: ["Rename to VisuallyHidden"]
+  },
+  {
+    uiKitName: "AccessibleHidden",
+    nimbusEquivalent: "VisuallyHidden",
+    importPath: "@commercetools/nimbus",
+    mappingType: "variant",
+    notes: "Use VisuallyHidden for content that should be screen-reader accessible only.",
+    breakingChanges: ["Replace AccessibleHidden with VisuallyHidden"]
+  },
+  // -------------------------------------------------------------------------
+  // Provider
+  // -------------------------------------------------------------------------
+  {
+    uiKitName: "ThemeProvider",
+    nimbusEquivalent: "NimbusProvider",
+    importPath: "@commercetools/nimbus",
+    mappingType: "direct",
+    notes: "Rename to NimbusProvider. Wrap your app root once; passes theme and i18n context.",
+    breakingChanges: [
+      "Rename to NimbusProvider",
+      "theme prop configuration has changed; see NimbusProvider docs"
+    ]
+  }
+];
+var MIGRATION_MAP = new Map(
+  MIGRATION_DATA.map((entry) => [entry.uiKitName, entry])
+);
+function getUiKitMigration(uiKitName) {
+  return MIGRATION_MAP.get(uiKitName);
+}
+function getAllUiKitMigrations() {
+  return MIGRATION_DATA;
+}
+var COMPOUND_ROOT_MAP = /* @__PURE__ */ new Map();
+for (const entry of MIGRATION_DATA) {
+  const dotIdx = entry.uiKitName.indexOf(".");
+  if (dotIdx > 0) {
+    const root = entry.uiKitName.slice(0, dotIdx);
+    const existing = COMPOUND_ROOT_MAP.get(root);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      COMPOUND_ROOT_MAP.set(root, [entry]);
+    }
+  }
+}
+function getUiKitCompoundMigrations(rootName) {
+  return COMPOUND_ROOT_MAP.get(rootName);
+}
+
+// src/tools/migrate-from-uikit.ts
+var UIKIT_IMPORT_REGEX = /import\s+(?!type\s)(?:(\w+)(?:\s*,\s*\{([^}]*?)\})?\s+from\s+|\{([^}]*?)\}\s+from\s+)['"]@commercetools-uikit\/([^'"]+)['"]/gs;
+var UIKIT_BARREL_IMPORT_REGEX = /import\s+(?!type\s)\{([^}]+)\}\s+from\s+['"]@commercetools-frontend\/ui-kit['"]/g;
+var PACKAGE_TO_COMPONENT = {
+  // Packages whose name differs from the exported component
+  buttons: "PrimaryButton",
+  // multi-export; we'll use named imports instead
+  "flat-button": "FlatButton",
+  "link-button": "LinkButton",
+  "primary-button": "PrimaryButton",
+  "secondary-button": "SecondaryButton",
+  "icon-button": "IconButton",
+  "text-input": "TextInput",
+  "number-input": "NumberInput",
+  "money-input": "MoneyInput",
+  "password-input": "PasswordInput",
+  "multiline-text-input": "MultilineTextInput",
+  "rich-text-input": "RichTextInput",
+  "date-input": "DateInput",
+  "date-time-input": "DateTimeInput",
+  "date-range-input": "DateRangeInput",
+  "time-input": "TimeInput",
+  "search-text-input": "SearchTextInput",
+  "checkbox-input": "CheckboxInput",
+  "radio-input": "RadioInput",
+  "toggle-input": "ToggleInput",
+  "localized-text-input": "LocalizedTextInput",
+  "localized-multiline-text-input": "LocalizedMultilineTextInput",
+  "localized-rich-text-input": "LocalizedRichTextInput",
+  "loading-spinner": "LoadingSpinner",
+  "progress-bar": "ProgressBar",
+  "data-table": "DataTable",
+  "data-table-manager": "DataTableManager",
+  "dropdown-menu": "DropdownMenu",
+  "content-notification": "ContentNotification",
+  "accessible-button": "AccessibleButton",
+  "accessible-hidden": "AccessibleHidden",
+  "hidden-input": "HiddenInput",
+  "collapsible-panel": "CollapsiblePanel",
+  "collapsible-motion": "CollapsibleMotion",
+  "field-errors": "FieldErrors",
+  text: "Text",
+  label: "Label",
+  tag: "Tag",
+  stamp: "Stamp",
+  link: "Link",
+  card: "Card",
+  grid: "Grid",
+  avatar: "Avatar",
+  tooltip: "Tooltip",
+  pagination: "Pagination",
+  spacings: "Spacings",
+  constraints: "Constraints",
+  icons: "Icon Library",
+  "inline-svg": "InlineSvg"
+};
+function extractUiKitComponents(fileContent) {
+  const components = /* @__PURE__ */ new Set();
+  let match;
+  UIKIT_IMPORT_REGEX.lastIndex = 0;
+  while ((match = UIKIT_IMPORT_REGEX.exec(fileContent)) !== null) {
+    const defaultImport = match[1];
+    const namedImports = match[2] || match[3];
+    const packageName = match[4];
+    if (defaultImport) {
+      const mapped = PACKAGE_TO_COMPONENT[packageName];
+      if (mapped) {
+        components.add(mapped);
+      } else {
+        components.add(defaultImport);
+      }
+    }
+    if (namedImports) {
+      for (const name of namedImports.split(",")) {
+        const trimmed = name.trim().split(/\s+as\s+/)[0].trim();
+        if (trimmed && !trimmed.startsWith("type ")) components.add(trimmed);
+      }
+    }
+  }
+  UIKIT_BARREL_IMPORT_REGEX.lastIndex = 0;
+  while ((match = UIKIT_BARREL_IMPORT_REGEX.exec(fileContent)) !== null) {
+    for (const name of match[1].split(",")) {
+      const trimmed = name.trim().split(/\s+as\s+/)[0].trim();
+      if (trimmed) components.add(trimmed);
+    }
+  }
+  return [...components];
+}
+var _caseInsensitiveMap;
+function getCaseInsensitiveMap() {
+  if (!_caseInsensitiveMap) {
+    _caseInsensitiveMap = new Map(
+      getAllUiKitMigrations().map((e) => [
+        e.uiKitName.toLowerCase(),
+        e.uiKitName
+      ])
+    );
+  }
+  return _caseInsensitiveMap;
+}
+function deriveToolHint2(uiKitName, nimbusEquivalent, importPath, notes) {
+  if (importPath === "@commercetools/nimbus-icons") {
+    return 'Use the search_icons tool to find Nimbus icons by name (e.g. search_icons(query: "arrow"))';
+  }
+  if (uiKitName === "CustomIcon" || uiKitName === "LeadingIcon" || uiKitName === "InlineSvg") {
+    return 'Use the search_icons tool to find the Nimbus equivalent icon (e.g. search_icons(query: "checkmark"))';
+  }
+  if (importPath === "@commercetools/nimbus-tokens") {
+    return 'Use the get_tokens tool to browse available design tokens (e.g. get_tokens(category: "spacing"))';
+  }
+  if (notes.includes("spacing token") || notes.includes("design token")) {
+    return 'Use the get_tokens tool to find the correct token values (e.g. get_tokens(category: "spacing"))';
+  }
+  if (importPath === "@commercetools/nimbus" && nimbusEquivalent) {
+    return `Use the get_component tool to see full API docs (e.g. get_component(name: "${nimbusEquivalent}"))`;
+  }
+  return void 0;
+}
+function buildComponentResult(uiKitName) {
+  const entry = getUiKitMigration(uiKitName);
+  if (!entry) return null;
+  const result = {
+    uiKitName: entry.uiKitName,
+    nimbusEquivalent: entry.nimbusEquivalent,
+    importPath: entry.importPath,
+    mappingType: entry.mappingType,
+    notes: entry.notes,
+    breakingChanges: entry.breakingChanges
+  };
+  const hint = deriveToolHint2(
+    uiKitName,
+    entry.nimbusEquivalent,
+    entry.importPath,
+    entry.notes
+  );
+  if (hint) result.hint = hint;
+  return result;
+}
+function registerMigrateFromUiKit(server) {
+  server.registerTool(
+    "migrate_from_uikit",
+    {
+      title: "Migrate from UI Kit",
+      description: "Returns migration mapping data for UI Kit components to their Nimbus equivalents. Use componentName for a single lookup, or filePath to extract all UI Kit imports from a file and get mappings for each. The MCP provides data; the LLM does the actual code rewriting.",
+      inputSchema: {
+        componentName: z6.string().optional().describe(
+          'UI Kit component name to look up, e.g. "PrimaryButton", "TextInput", "CollapsiblePanel".'
+        ),
+        filePath: z6.string().optional().describe(
+          "Absolute path to a source file. Extracts @commercetools-uikit/* imports and returns mappings for all found components."
+        )
+      }
+    },
+    async ({ componentName, filePath }) => {
+      if (!componentName && !filePath) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: 'Either "componentName" or "filePath" must be provided.'
+            }
+          ],
+          isError: true
+        };
+      }
+      if (componentName) {
+        const result = buildComponentResult(componentName);
+        if (result) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result)
+              }
+            ]
+          };
+        }
+        const compoundEntries = getUiKitCompoundMigrations(componentName);
+        if (compoundEntries) {
+          const response2 = {
+            compoundRoot: componentName,
+            note: `"${componentName}" is used as a namespace (e.g. ${compoundEntries.map((e) => e.uiKitName).join(", ")}). Each sub-component has its own mapping.`,
+            mappings: compoundEntries.map(
+              (e) => buildComponentResult(e.uiKitName)
+            )
+          };
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(response2)
+              }
+            ]
+          };
+        }
+        const fuzzy = getCaseInsensitiveMap().get(componentName.toLowerCase());
+        if (fuzzy) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(buildComponentResult(fuzzy))
+              }
+            ]
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No migration mapping found for "${componentName}". Use a UI Kit component name like "PrimaryButton", "TextInput", etc.`
+            }
+          ],
+          isError: true
+        };
+      }
+      let fileContent;
+      try {
+        fileContent = await readFile3(filePath, "utf-8");
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Could not read file "${filePath}".`
+            }
+          ],
+          isError: true
+        };
+      }
+      const componentNames = extractUiKitComponents(fileContent);
+      if (componentNames.length === 0) {
+        const emptyResponse = {
+          filePath,
+          mappings: [],
+          unmapped: []
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(emptyResponse)
+            }
+          ]
+        };
+      }
+      const mappings = [];
+      const unmapped = [];
+      for (const name of componentNames) {
+        const result = buildComponentResult(name);
+        if (result) {
+          mappings.push(result);
+          continue;
+        }
+        const compoundEntries = getUiKitCompoundMigrations(name);
+        if (compoundEntries) {
+          const used = compoundEntries.filter(
+            (entry) => fileContent.includes(entry.uiKitName)
+          );
+          const toInclude = used.length > 0 ? used : compoundEntries;
+          for (const entry of toInclude) {
+            mappings.push(buildComponentResult(entry.uiKitName));
+          }
+          continue;
+        }
+        unmapped.push(name);
+      }
+      const response = {
+        filePath,
+        mappings,
+        unmapped
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(response)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/server.ts
+function createServer() {
+  const server = new McpServer(
+    {
+      name: "nimbus-mcp",
+      version: "0.1.0"
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  registerGetComponent(server);
+  registerGetTokens(server);
+  registerListComponents(server);
+  registerSearchDocs(server);
+  registerSearchIcons(server);
+  registerMigrateFromUiKit(server);
+  return server;
+}
+
+// src/index.ts
 async function main() {
-    const server = createServer();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
 }
 main().catch((error) => {
-    console.error("Nimbus MCP server error:", error);
-    process.exit(1);
+  console.error("Nimbus MCP server error:", error);
+  process.exit(1);
 });