@neuctra/ui-mcp 0.4.7 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuctra/ui-mcp",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "MCP server exposing the @neuctra/ui component registry (props, defaults, examples, theme tokens) so AI coding tools generate accurate Neuctra UI code, plus SEO/AEO/GEO tools (per-page meta, woven JSON-LD, audits).",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,8 @@
     "./data/theme.json": "./data/theme.json",
     "./data/design-rules.json": "./data/design-rules.json",
     "./data/seo-guide.json": "./data/seo-guide.json",
+    "./data/layouts.json": "./data/layouts.json",
+    "./data/variants.json": "./data/variants.json",
     "./package.json": "./package.json"
   },
   "files": [

package/src/load-data.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 // Disk loading is for Node, Bun, and Deno. Edge callers should pass imported
-// data to createServer({ registry, theme, aiDesignRules, seoGuide, layouts }).
+// data to createServer({ registry, theme, aiDesignRules, seoGuide, layouts, variants }).
 export function loadDataFromDisk() {
   const directory = path.dirname(fileURLToPath(import.meta.url));
   const dataDirectory = path.resolve(directory, "..", "data");
@@ -16,5 +16,6 @@ export function loadDataFromDisk() {
     aiDesignRules: readJson("design-rules.json"),
     seoGuide: readJson("seo-guide.json"),
     layouts: readJson("layouts.json"),
+    variants: readJson("variants.json"),
   };
 }

package/src/tools/neuctra-ui-page-builder/index.mjs

@@ -3,6 +3,7 @@ import { FRAMEWORKS } from "../../seo.mjs";
 import { findNeuctraUiComponents } from "../get-neuctra-ui-component/index.mjs";
 import { getDesignRulesContext } from "../get-design-rules/index.mjs";
 import { buildSeoGuideContext } from "../neuctra-ui-seo-setup/index.mjs";
+import { selectDesignVariants } from "./variants.mjs";
 
 function getLayouts(layoutData) {
   const grouped = (layoutData?.layoutGroups ?? []).flatMap((group) =>
@@ -89,7 +90,7 @@ export function registerNeuctraUiPageBuilderTool(server, data) {
     {
       title: "Analyze and plan a Neuctra UI page",
       description:
-        "Analyze a page request and choose from every layout in the grouped real-world catalog in data/layouts.json, including marketing, SaaS dashboards, commerce, publishing, support, portfolios, communities, events, and system pages. Use pageType=auto to select the closest specific layout from the request, or choose an explicit pageType. Returns the selected recipe, matching @neuctra/ui component specs, relevant design rules, and SEO guidance.",
+        "Analyze a page request and choose from every layout in the grouped real-world catalog in data/layouts.json, including marketing, SaaS dashboards, commerce, publishing, support, portfolios, communities, events, and system pages. Use pageType=auto to select the closest specific layout from the request, or choose an explicit pageType. Returns the selected recipe, context-matched design variants (navigation shell, page header, stat cards, dashboard grid), matching @neuctra/ui component specs, relevant design rules, and SEO guidance.",
       inputSchema: {
         request: z.string().min(8).describe("Describe the page to create and the main user task."),
         pageType: z.enum(pageTypeOptions).default("auto").describe(`Layout ID from the full catalog (${layouts.map((layout) => layout.id).join(", ")}) or auto to infer the best match from the request.`),
@@ -100,6 +101,12 @@ export function registerNeuctraUiPageBuilderTool(server, data) {
           primaryAction: z.string().optional(),
           platform: z.enum(["desktop", "mobile", "responsive"]).default("responsive"),
           audience: z.string().optional(),
+          variants: z.object({
+            navigationShell: z.string(),
+            pageHeader: z.string(),
+            statCard: z.string(),
+            dashboardBody: z.string(),
+          }).partial().optional().describe("Force a specific variant id per group (see designVariants in the response for ids). Use this to keep an existing app's shell consistent."),
         }).default({}).describe("Optional design and audience preferences."),
       },
     },
@@ -116,6 +123,7 @@ export function registerNeuctraUiPageBuilderTool(server, data) {
         ruleIds: layout.seoRuleIds,
       });
       const signals = detectTaskSignals(request);
+      const designVariants = selectDesignVariants(data.variants, { request, layoutId: layout.id, preferences });
       const preferencesToClarify = [];
       if (!preferences.visualDirection) preferencesToClarify.push("visual direction");
       if (!preferences.density) preferencesToClarify.push("content density");
@@ -146,6 +154,7 @@ export function registerNeuctraUiPageBuilderTool(server, data) {
           matches: components,
           instruction: "Use these exact exports and documented props. If a required component is absent from the matches, call get-neuctra-ui-component for that need before inventing a pattern.",
         },
+        ...(designVariants && { designVariants }),
         designRules: design,
         seoGuidance: seo ? {
           framework: seo.framework,
@@ -156,6 +165,7 @@ export function registerNeuctraUiPageBuilderTool(server, data) {
         implementationInstructions: [
           "Use the selected layout as a starting structure and adapt its sections to the exact request.",
           "Keep the primary task visually clear; do not add sections that do not serve the request.",
+          ...(designVariants ? ["Build the navigation shell, page header, stat cards and dashboard grid from designVariants.selections. Use the recommended variant unless an alternative clearly fits the brief better; if the project already has an app shell, keep that instead."] : []),
           "Use Neuctra UI components with the exact props and semantic theme tokens from the supplied context.",
           "Apply the SEO steps only when the page is public and indexable; protect private application pages.",
           "When framework is auto, inspect the project files and choose metadata and rendering APIs for the installed framework and router.",

package/src/tools/neuctra-ui-page-builder/variants.mjs

@@ -0,0 +1,102 @@
+// Scores the design variants in data/variants.json against a page request so
+// the page builder recommends a context-appropriate navigation shell, header,
+// stat card and dashboard grid instead of the same default every time.
+
+const normalize = (text) => ` ${text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim()} `;
+
+// Small deterministic tie-breaker (0..1) so equally-scored variants rotate
+// with the request text instead of always resolving to the first entry.
+function tieBreak(seed) {
+  let hash = 2166136261;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash ^= seed.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return ((hash >>> 0) % 1000) / 1000;
+}
+
+function resolvePlatform(request, platform) {
+  if (platform !== "responsive") return platform;
+  return /\bmobile[ -]?(app|first|only)\b|\bpwa\b/i.test(request) ? "mobile" : platform;
+}
+
+function scoreVariant(variant, { text, layoutId, density, platform, seed }) {
+  let score = 0;
+  const reasons = [];
+  for (const signal of variant.signals ?? []) {
+    const phrase = normalize(signal);
+    if (phrase.trim() && text.includes(phrase)) {
+      score += phrase.trim().includes(" ") ? 4 : 3;
+      reasons.push(`request mentions "${signal}"`);
+    }
+  }
+  if (variant.layouts?.includes(layoutId)) {
+    score += 3;
+    reasons.push(`suits the ${layoutId} layout`);
+  }
+  if (density) {
+    if (variant.density?.includes(density)) {
+      score += 2;
+      reasons.push(`fits ${density} density`);
+    } else {
+      score -= 1;
+    }
+  }
+  const platforms = variant.platforms ?? [];
+  if (platform === "mobile") {
+    if (platforms.includes("mobile")) {
+      score += 4;
+      reasons.push("works on mobile-first products");
+    } else {
+      score -= 3;
+    }
+  } else if (!platforms.includes(platform) && !platforms.includes("responsive")) {
+    score -= 10;
+  }
+  return { score: score + tieBreak(`${seed}:${variant.id}`), reasons };
+}
+
+const summarize = ({ id, name, bestFor, structure }) => ({ id, name, bestFor, structure });
+
+export function selectDesignVariants(variantData, { request, layoutId, preferences = {} }) {
+  const groups = variantData?.groups ?? {};
+  const text = normalize(request);
+  const platform = resolvePlatform(request, preferences.platform ?? "responsive");
+  const overrides = preferences.variants ?? {};
+  const selections = {};
+
+  for (const [groupId, group] of Object.entries(groups)) {
+    if (!group.appliesTo?.includes(layoutId)) continue;
+    const ranked = (group.variants ?? [])
+      .map((variant) => ({
+        variant,
+        ...scoreVariant(variant, { text, layoutId, density: preferences.density, platform, seed: `${request}:${groupId}` }),
+      }))
+      .sort((a, b) => b.score - a.score);
+
+    const override = overrides[groupId] && ranked.find(({ variant }) => variant.id === overrides[groupId]);
+    const chosen = override ?? ranked[0];
+    if (!chosen) continue;
+
+    selections[groupId] = {
+      title: group.title,
+      recommended: {
+        ...chosen.variant,
+        why: override
+          ? ["explicitly requested in preferences.variants"]
+          : chosen.reasons.length
+            ? chosen.reasons
+            : ["no strong context signal; chosen to avoid repeating the default, confirm it fits the brief"],
+      },
+      alternatives: ranked.filter((entry) => entry !== chosen).slice(0, 2).map(({ variant }) => summarize(variant)),
+      otherOptions: ranked.filter((entry) => entry !== chosen).slice(2).map(({ variant }) => variant.id),
+    };
+  }
+
+  if (!Object.keys(selections).length) return null;
+  return {
+    principles: variantData.principles ?? [],
+    effectivePlatform: platform,
+    selections,
+  };
+}