@commercetools/nimbus-mcp 3.5.1 → 3.6.0

package/dist/index.js

@@ -84,6 +84,9 @@ var getDocsManifest = lazyJson("docs/docs.json");
 var getIconCatalog = lazyJson("icons.json");
 var getFlatTokenData = lazyJson("tokens.json");
 var getUiKitTokenMap = lazyJson("uikit-tokens.json");
+var getStylePropsSummary = lazyJson(
+  "style-props-summary.json"
+);
 
 // src/utils/markdown.ts
 function stripMarkdown(text) {
@@ -282,6 +285,24 @@ function routePathToSlug(path) {
 }
 
 // src/tools/get-component.ts
+var STYLE_PROPS_HINT = 'Also accepts style props. Use get_docs_page(path: "home/style-props") for full reference.';
+async function componentSupportsStyleProps(exportName) {
+  try {
+    const typeData = await getTypeData(exportName);
+    if (typeData.supportsStyleProps) return true;
+  } catch {
+  }
+  const subFiles = await findSubComponentFiles(exportName);
+  for (const file of subFiles) {
+    try {
+      const subName = file.replace(/\.json$/, "");
+      const subData = await getTypeData(subName);
+      if (subData.supportsStyleProps) return true;
+    } catch {
+    }
+  }
+  return false;
+}
 var SECTION_KEYS = [
   "overview",
   "guidelines",
@@ -327,7 +348,7 @@ var resolveCatalogCache;
 var resolveCatalogRoutesRef;
 var topLevelNamesCache;
 var topLevelNamesRoutesRef;
-async function aggregateSubComponentProps(exportName) {
+async function findSubComponentFiles(exportName) {
   const typesDir = resolve3(getDataDir(), "docs/types");
   let files;
   try {
@@ -344,7 +365,7 @@ async function aggregateSubComponentProps(exportName) {
   }
   const topLevelNames = topLevelNamesCache;
   const prefix = exportName.toLowerCase();
-  const subFiles = files.filter((f) => {
+  return 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
@@ -352,17 +373,25 @@ async function aggregateSubComponentProps(exportName) {
     !base.endsWith("Props") && // exclude type-only duplicates (e.g. StepsRootProps)
     !topLevelNames.has(baseLower);
   });
+}
+async function aggregateSubComponentPropsWithStyleInfo(exportName) {
+  const subFiles = await findSubComponentFiles(exportName);
+  const stylePropsSubComponents = [];
   const settled = await Promise.allSettled(
     subFiles.map(async (file) => {
       const subName = file.replace(/\.json$/, "");
       const typeData = await getTypeData(subName);
+      if (typeData.supportsStyleProps) {
+        stylePropsSubComponents.push(subName);
+      }
       return filterProps(typeData).map((p) => ({
         ...p,
         subComponent: subName
       }));
     })
   );
-  return settled.filter((r) => r.status === "fulfilled").flatMap((r) => r.value);
+  const props = settled.filter((r) => r.status === "fulfilled").flatMap((r) => r.value);
+  return { props, stylePropsSubComponents: stylePropsSubComponents.sort() };
 }
 var CATALOG_CATEGORIES = /* @__PURE__ */ new Set(["Components", "Patterns"]);
 async function resolveComponent(name) {
@@ -441,6 +470,10 @@ function registerGetComponent(server) {
         const availableSections = [...viewSections, "props"];
         if (!section) {
           const metadata = buildMetadataResponse(entry, availableSections);
+          const exportName = entry.exportName ?? entry.title;
+          if (await componentSupportsStyleProps(exportName)) {
+            metadata.styleProps = STYLE_PROPS_HINT;
+          }
           return {
             content: [
               {
@@ -455,18 +488,27 @@ function registerGetComponent(server) {
           try {
             const typeData = await getTypeData(exportName);
             let filtered = filterProps(typeData);
+            const response = {
+              component: exportName,
+              propCount: filtered.length,
+              props: filtered
+            };
             if (filtered.length === 0) {
-              filtered = await aggregateSubComponentProps(exportName);
+              const { props, stylePropsSubComponents } = await aggregateSubComponentPropsWithStyleInfo(exportName);
+              filtered = props;
+              response.propCount = filtered.length;
+              response.props = filtered;
+              if (stylePropsSubComponents.length > 0) {
+                response.styleProps = `${stylePropsSubComponents.join(", ")} also accept style props. Use get_docs_page(path: "home/style-props") for full reference.`;
+              }
+            } else if (typeData.supportsStyleProps) {
+              response.styleProps = STYLE_PROPS_HINT;
             }
             return {
               content: [
                 {
                   type: "text",
-                  text: JSON.stringify({
-                    component: exportName,
-                    propCount: filtered.length,
-                    props: filtered
-                  })
+                  text: JSON.stringify(response)
                 }
               ]
             };
@@ -1261,6 +1303,8 @@ function registerSearchIcons(server) {
 
 // src/tools/get-docs-page.ts
 import { z as z6 } from "zod";
+var STYLE_PROPS_HINT2 = 'Also accepts style props. Use get_docs_page(path: "home/style-props") for full reference.';
+var COMPONENT_ROUTE_PREFIX = "components/";
 var viewContentCache2 = /* @__PURE__ */ new WeakMap();
 function getCachedStripped(viewObj) {
   let cached = viewContentCache2.get(viewObj);
@@ -1270,6 +1314,36 @@ function getCachedStripped(viewObj) {
   }
   return cached;
 }
+async function enrichStylePropsLanding(content) {
+  try {
+    const summary = await getStylePropsSummary();
+    const lines = summary.categories.map(
+      (c) => `${c.name} (${c.path}): ${c.props.join(", ")}`
+    );
+    return content + "\n\n--- Style Props Index ---\n" + lines.join("\n") + `
+
+${summary.hint}`;
+  } catch {
+    return content;
+  }
+}
+async function resolveExportName(route) {
+  if (!route.startsWith(COMPONENT_ROUTE_PREFIX)) return void 0;
+  try {
+    const manifest = await getRouteManifest();
+    const entry = manifest.routes.find((r) => r.path === `/${route}`);
+    return entry?.exportName ?? entry?.title;
+  } catch {
+    return void 0;
+  }
+}
+async function maybeAddStylePropsHint(result, route) {
+  const exportName = await resolveExportName(route);
+  if (!exportName) return;
+  if (await componentSupportsStyleProps(exportName)) {
+    result.styleProps = STYLE_PROPS_HINT2;
+  }
+}
 function registerGetDocsPage(server) {
   server.registerTool(
     "get_docs_page",
@@ -1325,6 +1399,7 @@ function registerGetDocsPage(server) {
             sections: availableSections,
             content: getCachedStripped(view)
           };
+          await maybeAddStylePropsHint(result2, meta.route);
           return {
             content: [{ type: "text", text: JSON.stringify(result2) }]
           };
@@ -1338,6 +1413,9 @@ ${getCachedStripped(view)}`).join("\n\n");
         } else {
           content = meta.description;
         }
+        if (meta.route === "home/style-props") {
+          content = await enrichStylePropsLanding(content);
+        }
         const result = {
           title: meta.title,
           description: meta.description,
@@ -1345,6 +1423,7 @@ ${getCachedStripped(view)}`).join("\n\n");
           sections: availableSections,
           content
         };
+        await maybeAddStylePropsHint(result, meta.route);
         return {
           content: [{ type: "text", text: JSON.stringify(result) }]
         };
@@ -1416,9 +1495,9 @@ var MIGRATION_DATA = [
     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.`,
+    notes: `Use <Button variant="ghost" size="sm"> for flat styling. FlatButton renders compact \u2014 set size='sm' to match. UI Kit tone prop ('primary'|'secondary'|'inverted'|'critical') maps to Nimbus colorPalette/variant.`,
     breakingChanges: [
-      "Replace FlatButton with <Button>",
+      "Replace FlatButton with <Button variant='ghost' size='sm'>",
       "Default color changed: UI Kit FlatButton was blue (tone='primary') by default; Nimbus Button defaults to colorPalette='neutral' (gray). Add colorPalette='primary' to preserve the blue appearance.",
       "label prop replaced by children",
       "tone prop replaced by variant/colorPalette",
@@ -2142,7 +2221,7 @@ var MIGRATION_DATA = [
     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.",
+    notes: "Use NumberInputField (not NumberInput) when a label is needed \u2014 it's a pre-composed field with built-in label, description, and error handling (like TextInputField). 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",
@@ -2508,12 +2587,13 @@ var MIGRATION_DATA = [
     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.',
+    notes: `Use <LocalizedField type="text"> (the default type). LocalizedField manages all locale inputs internally via its type prop. It collapses non-default locales by default (matching UIKit's behavior) \u2014 do NOT set displayAllLocalesOrCurrencies unless you explicitly want all locales visible. LocalizedField supports style props \u2014 set width='100%' to fill its container (it doesn't stretch by default).`,
     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"
+      "onChange receives a LocalizedFieldChangeEvent with target.locale",
+      "Collapse behavior is built in \u2014 do not add displayAllLocalesOrCurrencies"
     ],
     propMappings: [
       {
@@ -2584,11 +2664,12 @@ var MIGRATION_DATA = [
     nimbusEquivalent: "LocalizedField",
     importPath: "@commercetools/nimbus",
     mappingType: "variant",
-    notes: 'Use <LocalizedField type="multiLine">. The type prop controls the input variant; no child composition needed.',
+    notes: `Use <LocalizedField type="multiLine">. The type prop controls the input variant; no child composition needed. Collapses non-default locales by default \u2014 do NOT set displayAllLocalesOrCurrencies. Set width='100%' to fill container (it doesn't stretch by default).`,
     breakingChanges: [
       "Replace LocalizedMultilineTextInput with <LocalizedField type='multiLine'>",
       "selectedLanguage prop replaced by defaultLocaleOrCurrency",
       "value per locale replaced by valuesByLocaleOrCurrency object",
+      "Collapse behavior is built in \u2014 do not add displayAllLocalesOrCurrencies",
       "onChange receives a LocalizedFieldChangeEvent with target.locale"
     ],
     propMappings: [
@@ -2846,7 +2927,7 @@ var MIGRATION_DATA = [
     nimbusEquivalent: "Badge",
     importPath: "@commercetools/nimbus",
     mappingType: "direct",
-    notes: "Rename to Badge. UI Kit used a tone prop; Nimbus uses colorPalette instead. UI Kit tones: 'critical'|'warning'|'positive'|'information'|'primary'|'secondary'. Nimbus colorPalette values: 'critical'|'warning'|'positive'|'info'|'primary'|'neutral'.",
+    notes: "Rename to Badge. UI Kit used a tone prop; Nimbus uses colorPalette instead. UI Kit tones: 'critical'|'warning'|'positive'|'information'|'primary'|'secondary'. Nimbus colorPalette values: 'critical'|'warning'|'positive'|'info'|'primary'|'neutral'. Badge supports style props \u2014 use size='sm' or size='2xs' for compact contexts like table cells, and style props like px, py, fontSize for further tuning.",
     breakingChanges: [
       "Rename to Badge",
       "Default color changed: UI Kit Stamp was blue (tone='information') by default; Nimbus Badge defaults to colorPalette='neutral' (gray). Add colorPalette='info' to preserve the blue appearance.",
@@ -2955,7 +3036,7 @@ var MIGRATION_DATA = [
     nimbusEquivalent: "DataTable",
     importPath: "@commercetools/nimbus",
     mappingType: "direct",
-    notes: "Direct replacement. Column definitions require DataTableColumnItem<RowType>[] generic typing. Sort and selection callbacks have new signatures.",
+    notes: "Direct replacement. Column definitions require DataTableColumnItem<RowType>[] generic typing. Sort and selection callbacks have new signatures. Set allowsPinning={false} unless you need row pinning (UIKit DataTable had no pin column). For sticky header with vertical scrolling, set maxHeight on the DataTable. Horizontal scroll shadows are automatic \u2014 they appear when the table overflows its container width. DataTable supports style props, so set maxW directly on it to constrain width and trigger horizontal scrolling.",
     breakingChanges: [
       "columns prop shape changed: key\u2192id, label\u2192header, accessor required (returns cell content, can be string or JSX)",
       "DataTableColumnItem<T> is generic \u2014 without <T> accessors return unknown and TS rejects them as ReactNode",
@@ -3176,10 +3257,10 @@ var MIGRATION_DATA = [
     nimbusEquivalent: "Design tokens",
     importPath: "@commercetools/nimbus-tokens",
     mappingType: "pattern",
-    notes: "Replace Constraints.Horizontal with maxWidth design tokens or the Box/Container component.",
+    notes: `Replace <Constraints.Horizontal max={N}> with maxW on the appropriate container. Three approaches depending on context: (1) Single child: <Box maxW="TOKEN"> wrapper or maxW style prop on the child. (2) Multiple constrained siblings in a row: put maxW on the parent <Stack direction="row"> and use flex props on children to share the space proportionally (e.g. flex="2" for wider, flex="1" for narrower). (3) Page-level constraint: maxW on the outermost container. UIKit max value \u2192 Nimbus size token: max=3\u2192'3xs' (224px), max=4\u2192'2xs' (256px), max=5\u2192'xs' (320px), max=6\u2192'xs' (320px), max=7\u2192'sm' (384px), max=8\u2192'sm' (384px), max=9\u2192'md' (448px), max=10\u2192'lg' (512px), max=11\u2192'lg' (512px), max=12\u2192'xl' (576px), max=13\u2192'2xl' (672px), max=14\u2192'2xl' (672px), max=15\u2192'3xl' (768px), max=16\u2192'3xl' (768px).`,
     breakingChanges: [
-      "Remove Constraints.Horizontal",
-      "Use maxWidth prop with design token values on Box or Container"
+      "Remove Constraints.Horizontal wrapper",
+      "Use maxW with Nimbus size tokens (see notes for lookup table and three approaches)"
     ],
     layoutGuidance: LAYOUT_NESTING_GUIDANCE
   },
@@ -3188,10 +3269,11 @@ var MIGRATION_DATA = [
     nimbusEquivalent: "Stack",
     importPath: "@commercetools/nimbus",
     mappingType: "pattern",
-    notes: 'Use <Stack direction="row" gap={...}> with nimbus spacing tokens.',
+    notes: `Use <Stack direction="row" gap={...}> with nimbus spacing tokens. Add flexWrap='wrap' when the row contains multiple form inputs or constrained children that may overflow at narrow viewport widths.`,
     breakingChanges: [
       "Replace Spacings.Inline with <Stack direction='row'>",
-      "Spacing values use design token scale (e.g. gap='300')"
+      "Spacing values use design token scale (e.g. gap='300')",
+      "Add flexWrap='wrap' for rows with multiple inputs to prevent overflow"
     ],
     layoutGuidance: LAYOUT_NESTING_GUIDANCE
   },
@@ -3256,7 +3338,7 @@ var MIGRATION_DATA = [
     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.",
+    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. Set size="sm" on Accordion.Root to match UIKit CollapsiblePanel's compact header sizing.`,
     breakingChanges: [
       "Rename to Accordion",
       "Adopt compositional slot API (Accordion.Root, Accordion.Item, Accordion.Header, Accordion.Content)",
@@ -3366,36 +3448,55 @@ var MIGRATION_DATA = [
   },
   {
     uiKitName: "Text.Headline",
-    nimbusEquivalent: "Text",
+    nimbusEquivalent: "Heading",
     importPath: "@commercetools/nimbus",
-    mappingType: "variant",
-    notes: 'Use <Text size="2xl" fontWeight="bold"> or the Heading component.',
+    mappingType: "direct",
+    notes: 'Use <Heading as="h1" size="lg"> for page titles, or <Heading as="h2" size="md"> for section headings. Heading supports style props \u2014 use them for spacing (e.g. mb, mt) instead of wrapper elements.',
     breakingChanges: [
-      "Replace Text.Headline with <Text size='2xl' fontWeight='bold'> or <Heading>"
+      "Replace Text.Headline with <Heading>",
+      "Set the appropriate heading level via the as prop (h1\u2013h6) for semantic HTML",
+      "Set size prop to match visual hierarchy: 'lg' for page titles, 'md' for sections"
     ],
     propMappings: [
       {
         uiKitProp: "_component",
-        nimbusProp: null,
+        nimbusProp: "size",
         changeType: "value-mapping",
-        fixedValue: "2xl",
-        notes: "Also set fontWeight='bold', or use <Heading> instead."
+        fixedValue: "lg",
+        notes: "Use size='lg' for page titles, 'md' for section headings."
+      },
+      {
+        uiKitProp: "as",
+        nimbusProp: "as",
+        changeType: "rename",
+        notes: "Keep the same heading level (h1, h2, etc.)."
       }
     ]
   },
   {
     uiKitName: "Text.Subheadline",
-    nimbusEquivalent: "Text",
+    nimbusEquivalent: "Heading",
     importPath: "@commercetools/nimbus",
-    mappingType: "variant",
-    notes: 'Use <Text size="xl">.',
-    breakingChanges: ["Replace Text.Subheadline with <Text size='xl'>"],
+    mappingType: "direct",
+    notes: 'Use <Heading as="h4" size="xs" fontWeight="medium"> for subheadings like card titles and accordion labels. UIKit Subheadline used a medium weight \u2014 Heading defaults to bold, so set fontWeight explicitly. Heading supports style props \u2014 use them for spacing instead of wrapper elements.',
+    breakingChanges: [
+      "Replace Text.Subheadline with <Heading>",
+      "Set the appropriate heading level via the as prop",
+      "Set size='xs' and fontWeight='medium' for subheading-level text"
+    ],
     propMappings: [
       {
         uiKitProp: "_component",
-        nimbusProp: null,
+        nimbusProp: "size",
         changeType: "value-mapping",
-        fixedValue: "xl"
+        fixedValue: "xs",
+        notes: "Use size='xs' for subheadings, 'md' if slightly larger is needed."
+      },
+      {
+        uiKitProp: "as",
+        nimbusProp: "as",
+        changeType: "rename",
+        notes: "Keep the same heading level (h3, h4, etc.)."
       }
     ]
   },
@@ -5358,7 +5459,8 @@ function buildTokenRedirect(name) {
     hint: `Use the get_tokens tool with the uikitToken parameter to resolve each ${name} token (e.g. get_tokens(uikitToken: "constraint3"))`
   };
 }
-function buildComponentResult(uiKitName) {
+var STYLE_PROPS_HINT3 = 'Also accepts style props. Use get_docs_page(path: "home/style-props") for full reference.';
+async function buildComponentResult(uiKitName) {
   const entry = getUiKitMigration(uiKitName);
   if (!entry) return null;
   const result = {
@@ -5385,6 +5487,11 @@ function buildComponentResult(uiKitName) {
     entry.notes
   );
   if (hint) result.hint = hint;
+  if (entry.importPath === "@commercetools/nimbus" && entry.nimbusEquivalent) {
+    if (await componentSupportsStyleProps(entry.nimbusEquivalent)) {
+      result.styleProps = STYLE_PROPS_HINT3;
+    }
+  }
   return result;
 }
 function hoistLayoutGuidance(mappings) {
@@ -5530,7 +5637,7 @@ function registerMigrateFromUiKit(server) {
             ]
           };
         }
-        const result = buildComponentResult(componentName);
+        const result = await buildComponentResult(componentName);
         if (result) {
           return {
             content: [
@@ -5543,8 +5650,10 @@ function registerMigrateFromUiKit(server) {
         }
         const compoundEntries = getUiKitCompoundMigrations(componentName);
         if (compoundEntries) {
-          const mappings2 = compoundEntries.map(
-            (e) => buildComponentResult(e.uiKitName)
+          const mappings2 = await Promise.all(
+            compoundEntries.map((e) => buildComponentResult(e.uiKitName))
+          ).then(
+            (results) => results.filter(Boolean)
           );
           const response2 = {
             compoundRoot: componentName,
@@ -5568,7 +5677,7 @@ function registerMigrateFromUiKit(server) {
             content: [
               {
                 type: "text",
-                text: JSON.stringify(buildComponentResult(fuzzy))
+                text: JSON.stringify(await buildComponentResult(fuzzy))
               }
             ]
           };
@@ -5636,7 +5745,7 @@ function registerMigrateFromUiKit(server) {
           mappings.push(buildTokenRedirect(name));
           continue;
         }
-        const result = buildComponentResult(name);
+        const result = await buildComponentResult(name);
         if (result) {
           mappings.push(result);
           continue;
@@ -5648,7 +5757,8 @@ function registerMigrateFromUiKit(server) {
           );
           const toInclude = used.length > 0 ? used : compoundEntries;
           for (const entry of toInclude) {
-            mappings.push(buildComponentResult(entry.uiKitName));
+            const entryResult = await buildComponentResult(entry.uiKitName);
+            if (entryResult) mappings.push(entryResult);
           }
           continue;
         }
@@ -5709,3 +5819,6 @@ main().catch((error) => {
   console.error("Nimbus MCP server error:", error);
   process.exit(1);
 });
+export {
+  createServer
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercetools/nimbus-mcp",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "MCP server for the Nimbus design system",
   "type": "module",
   "publishConfig": {
@@ -25,19 +25,19 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@commercetools-frontend/ui-kit": "^20.6.7",
     "@commercetools-uikit/design-system": "^20.6.4",
-    "@modelcontextprotocol/inspector": "^0.22.0",
-    "@types/node": "^24.13.3",
+    "@modelcontextprotocol/inspector": "^2.5.0",
+    "@types/node": "^26.5.0",
     "tsup": "^8.5.1",
-    "tsx": "^4.23.5",
+    "tsx": "^4.23.13",
     "typescript": "~5.9.3",
-    "@commercetools/nimbus": "^3.5.1",
-    "@commercetools/nimbus-icons": "^3.5.1",
-    "@commercetools/nimbus-tokens": "^3.5.1"
+    "@commercetools/nimbus": "^3.6.0",
+    "@commercetools/nimbus-icons": "^3.6.0",
+    "@commercetools/nimbus-tokens": "^3.6.0"
   },
   "scripts": {
     "prebuild": "tsx scripts/prebuild.ts",