@neuctra/ui-mcp 0.4.6 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuctra/ui-mcp",
-  "version": "0.4.6",
+  "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",
@@ -30,8 +30,10 @@
     ".": "./src/server.mjs",
     "./data/components.json": "./data/components.json",
     "./data/theme.json": "./data/theme.json",
-    "./data/aiDesignRules.json": "./data/aiDesignRules.json",
-    "./data/seoGuide.json": "./data/seoGuide.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");
@@ -13,8 +13,9 @@ export function loadDataFromDisk() {
   return {
     registry: readJson("components.json"),
     theme: readJson("theme.json"),
-    aiDesignRules: readJson("aiDesignRules.json"),
-    seoGuide: readJson("seoGuide.json"),
+    aiDesignRules: readJson("design-rules.json"),
+    seoGuide: readJson("seo-guide.json"),
     layouts: readJson("layouts.json"),
+    variants: readJson("variants.json"),
   };
 }

package/src/tools/get-design-rules/index.mjs

@@ -1,21 +1,45 @@
 import { z } from "zod";
 
-export function getDesignRulesContext(theme, aiDesignRules, sectionNumbers) {
+const BLOCK_NAMES = [
+  "core",
+  "layout",
+  "components",
+  "accessibilityInteraction",
+  "modernDesign",
+  "antiAiDesignRules",
+];
+
+function makeProductDesignRules(aiDesignRules, blockNames, sectionNumbers) {
+  const selected = sectionNumbers ? new Set(sectionNumbers) : null;
+  return Object.fromEntries(
+    blockNames
+      .filter((name) => name !== "antiAiDesignRules")
+      .map((name) => [
+        name,
+        (aiDesignRules.blocks?.[name] ?? []).filter((section) => !selected || selected.has(section.number)),
+      ])
+      .filter(([, sections]) => sections.length),
+  );
+}
+
+export function getDesignRulesContext(theme, aiDesignRules, sectionNumbers, requestedBlocks) {
   const { rules, antiAiLookRules } = theme;
-  if (!sectionNumbers) {
-    return { stylingRules: rules, antiAiLookRules, productDesignGuide: aiDesignRules };
-  }
+  const availableBlocks = aiDesignRules.blocks ?? {};
+  const requested = requestedBlocks?.length
+    ? requestedBlocks
+    : sectionNumbers
+      ? BLOCK_NAMES.filter((name) => name === "antiAiDesignRules" || (availableBlocks[name] ?? []).some((section) => sectionNumbers.includes(section.number)))
+      : ["core", "antiAiDesignRules"];
+  const blockNames = [...new Set(requested)];
 
-  const selected = new Set(sectionNumbers);
   return {
     stylingRules: rules,
-    antiAiLookRules,
-    productDesignGuide: {
-      title: aiDesignRules.title,
-      intro: aiDesignRules.intro,
-      sections: aiDesignRules.sections.filter((section) => selected.has(section.number)),
-      goldenRule: aiDesignRules.goldenRule,
+    antiAiDesignRules: {
+      ...(availableBlocks.antiAiDesignRules?.length && { productDesign: availableBlocks.antiAiDesignRules }),
+      theme: antiAiLookRules,
     },
+    productDesignRules: makeProductDesignRules(aiDesignRules, blockNames, sectionNumbers),
+    ...(aiDesignRules.goldenRule && { goldenRule: aiDesignRules.goldenRule }),
   };
 }
 
@@ -25,18 +49,16 @@ export function registerGetDesignRulesTool(server, { theme, aiDesignRules }) {
     {
       title: "Get Neuctra UI design rules",
       description:
-        "Get every design rule generated UI must follow when using @neuctra/ui. Covers two levels: (1) styling rules — token usage, surface/background conventions, component composition requirements like CardBody being compulsory whenever Card has body content, component-specific gotchas like Dropdown's trigger propagation, and the full set of rules for avoiding the visual tells that make UI look AI-generated (gradients, decorative shadows/blurs/glows, emoji-as-icons, etc.); (2) product/UX design rules — a numbered 63-section guide covering design philosophy, visual hierarchy, page/sidebar/navigation structure, per-component usage guidance (when to use Card, Modal vs Drawer, Table vs List, etc.), spacing/color/border/radius/shadow conventions, responsive design, accessibility, interaction design, a final UI quality checklist, the rule against overwriting a component's built-in design, paragraph text color (text-secondary for paragraphs, text-muted-foreground only for metadata/hints), and modern layout guidance: a fixed responsive type scale, readable measure, spacing rhythm, grid and hero patterns, focal point and section variety, a breakpoint checklist, imagery, iconography, motion timing and microcopy. Call this before generating any UI — not just neuctra-ui-theme-setup.",
-      inputSchema: {},
-    },
-    async () => {
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(getDesignRulesContext(theme, aiDesignRules), null, 2),
-          },
-        ],
-      };
+        "Return structured Neuctra UI design guidance in focused blocks: core, layout, components, accessibilityInteraction, modernDesign, and antiAiDesignRules. By default returns core guidance and anti-AI rules; request additional blocks when needed. The page builder supplies only the sections relevant to its selected layout.",
+      inputSchema: {
+        blocks: z.array(z.enum(BLOCK_NAMES)).optional().describe("Named design rule blocks to return. Defaults to core and antiAiDesignRules."),
+      },
     },
-  )
+    async ({ blocks }) => ({
+      content: [{
+        type: "text",
+        text: JSON.stringify(getDesignRulesContext(theme, aiDesignRules, undefined, blocks), null, 2),
+      }],
+    }),
+  );
 }

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

@@ -3,36 +3,47 @@ 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) =>
+    (group.layouts ?? []).map((layout) => ({ ...layout, category: layout.category ?? group.id, categoryName: group.name })),
+  );
+  const legacy = layoutData?.layouts ?? [];
+  return [...grouped, ...legacy];
+}
 
 function resolveLayout(request, requestedType, layoutData) {
-  const layouts = layoutData?.layouts ?? [];
+  const layouts = getLayouts(layoutData);
   if (requestedType !== "auto") {
     const explicit = layouts.find((layout) => layout.id === requestedType);
     if (explicit) return { layout: explicit, confidence: 1, evidence: [`Explicit page type: ${requestedType}`] };
   }
 
-  const normalized = request.toLowerCase();
+  const normalized = request.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
   const scored = layouts
     .filter((layout) => layout.id !== "custom")
     .map((layout) => {
       let score = 0;
       const evidence = [];
       for (const alias of layout.aliases ?? []) {
-        if (normalized.includes(alias.toLowerCase())) {
-          score += alias.includes(" ") ? 5 : 3;
-          evidence.push(alias);
+        const phrase = alias.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+        if (phrase && (` ${normalized} `).includes(` ${phrase} `)) {
+          const weight = 5 + Math.min(phrase.split(" ").length, 4) * 2;
+          score += weight;
+          evidence.push(`layout phrase: ${alias}`);
         }
       }
       for (const keyword of layout.keywords ?? []) {
-        const pattern = new RegExp(`\\b${keyword}\\b`, "i");
-        if (pattern.test(normalized)) {
-          score += 1;
-          evidence.push(keyword);
+        const term = keyword.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+        if (term && (` ${normalized} `).includes(` ${term} `)) {
+          score += 2;
+          evidence.push(`topic: ${keyword}`);
         }
       }
-      return { layout, score, evidence };
+      return { layout, score, evidence, specificity: Math.max(...(layout.aliases ?? []).map((alias) => alias.split(/\s+/).length), 0) };
     })
-    .sort((a, b) => b.score - a.score);
+    .sort((a, b) => b.score - a.score || b.specificity - a.specificity);
 
   const best = scored[0];
   const custom = layouts.find((layout) => layout.id === "custom") ?? layouts[0];
@@ -71,7 +82,7 @@ function getComponentGuidance(registry, request, layout) {
 }
 
 export function registerNeuctraUiPageBuilderTool(server, data) {
-  const layouts = data.layouts?.layouts ?? [];
+  const layouts = getLayouts(data.layouts);
   const pageTypeOptions = ["auto", ...layouts.map((layout) => layout.id)];
 
   server.registerTool(
@@ -79,10 +90,10 @@ export function registerNeuctraUiPageBuilderTool(server, data) {
     {
       title: "Analyze and plan a Neuctra UI page",
       description:
-        "Analyze a page request, infer its page type (for example tool, blog, dashboard, form, ecommerce, or docs), select a matching editable recipe from data/layouts.json, then compose matching @neuctra/ui component specs, design rules, and framework-aware SEO rules. Use this as the page-planning entry point. It plans the page; the assistant implements it using the returned layout and exact component APIs. Layout recipes can be added or edited in data/layouts.json.",
+        "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("Page type or auto to infer the closest layout from the request."),
+        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.`),
         framework: z.enum(["auto", ...FRAMEWORKS, "remix"]).default("auto").describe("Framework and router for framework-specific SEO implementation guidance."),
         preferences: z.object({
           visualDirection: z.string().optional(),
@@ -90,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."),
       },
     },
@@ -106,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");
@@ -116,6 +134,7 @@ export function registerNeuctraUiPageBuilderTool(server, data) {
           request,
           inferredPageType: layout.id,
           layoutName: layout.name,
+          layoutCategory: layout.categoryName ?? layout.category ?? "general",
           confidence,
           evidence,
           detectedTaskSignals: signals,
@@ -135,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,
@@ -145,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,
+  };
+}

package/src/tools/neuctra-ui-seo-setup/index.mjs

@@ -1,28 +1,67 @@
 import { z } from "zod";
 import { FRAMEWORKS } from "../../seo.mjs";
 
+const FRAMEWORK_OPTIONS = ["auto", ...FRAMEWORKS, "remix"];
+
+const RULE_GROUPS = {
+  "on-page": ["on_page_checklist"],
+  technical: ["technical_seo"],
+  performance: ["on_page_checklist"],
+  frameworks: ["technical_seo"],
+  "launch-checklist": ["validation", "reporting"],
+  geo: ["geo_checklist", "off_page_seo"],
+  aeo: ["aeo_checklist"],
+  local: ["local_seo"],
+};
+
+function selectGuideSections(seoGuide, ruleIds) {
+  if (!ruleIds?.length) return {};
+  const keys = new Set(ruleIds.flatMap((id) => RULE_GROUPS[id] ?? []));
+  return Object.fromEntries([...keys].filter((key) => seoGuide[key] !== undefined).map((key) => [key, seoGuide[key]]));
+}
+
+/** Builds context from the current SEO Agent Rules schema. */
 export function buildSeoGuideContext(seoGuide, { framework = "auto", ruleIds } = {}) {
   if (!seoGuide) return null;
-  const selectedRules = ruleIds
-    ? seoGuide.seoRules.filter((rule) => ruleIds.includes(rule.id))
-    : seoGuide.seoRules;
-  const knownFramework = ["nextjs-app", "nextjs-pages", "react-vite", "react-router", "remix"].includes(framework);
-  const implementation = knownFramework
-    ? seoGuide.implementationSteps.frameworkSpecific[framework]
-    : framework === "auto"
-      ? seoGuide.implementationSteps.frameworkSpecific
-      : seoGuide.implementationSteps.frameworkSpecific.other;
+
+  const selected = ruleIds?.length ? selectGuideSections(seoGuide, ruleIds) : {
+    on_page_checklist: seoGuide.on_page_checklist,
+    technical_seo: seoGuide.technical_seo,
+    off_page_seo: seoGuide.off_page_seo,
+    local_seo: seoGuide.local_seo,
+    geo_checklist: seoGuide.geo_checklist,
+    aeo_checklist: seoGuide.aeo_checklist,
+    validation: seoGuide.validation,
+    reporting: seoGuide.reporting,
+  };
+
+  const checklists = [
+    ...(selected.on_page_checklist ?? []),
+    ...(selected.geo_checklist ?? []),
+    ...(selected.aeo_checklist ?? []),
+  ];
 
   return {
-    title: seoGuide.title,
-    intro: seoGuide.intro,
-    seoRules: selectedRules,
-    implementationSteps: seoGuide.implementationSteps.steps,
+    version: seoGuide.version,
+    name: seoGuide.name,
+    role: seoGuide.role,
+    workflow: seoGuide.workflow,
+    mode: seoGuide.mode,
     framework: {
       requested: framework,
-      implementation,
-      assistantGuidance: seoGuide.implementationSteps.assistantGuidance,
+      detectedFromProjectContext: framework === "auto",
+      projectContextRequiredForDetection: framework === "auto",
+      frameworkSpecificImplementation: "Follow the detected framework's existing metadata, rendering, routing, and asset conventions. This guide does not prescribe framework-specific code snippets.",
     },
+    ...selected,
+    // Kept for the page builder's existing response contract.
+    seoRules: checklists,
+    implementationSteps: seoGuide.workflow,
+    safeImplementation: seoGuide.safe_implementation,
+    validation: selected.validation ?? seoGuide.validation,
+    reporting: selected.reporting ?? seoGuide.reporting,
+    references: seoGuide.references,
+    principle: seoGuide.principle,
   };
 }
 
@@ -30,18 +69,18 @@ export function registerNeuctraUiSeoSetupTool(server, { seoGuide }) {
   server.registerTool(
     "neuctra-ui-seo-setup",
     {
-      title: "Neuctra UI SEO rules and implementation guide",
+      title: "Neuctra UI SEO setup guide",
       description:
-        "Return one complete SEO, AEO, and GEO guide for a Neuctra UI project. The guide has two portions: comprehensive SEO rules and ordered implementation steps, including framework-specific metadata, rendering, JSON-LD, sitemap, and robots guidance. This is an assistant reference tool: inspect the project and apply the rules to its actual framework; it does not generate a single page snippet or audit input.",
+        "Return the current SEO Agent Rules for planning or carrying out an evidence-based SEO review in a Neuctra UI project. Covers technical and on-page SEO, GEO, AEO, local and off-page SEO, safe implementation, validation, and reporting. The default mode is read-only audit; implementation should follow the guide and existing project conventions. It does not guarantee rankings, indexing, rich results, or AI citations.",
       inputSchema: {
         framework: z
-          .enum(["auto", ...FRAMEWORKS, "remix"])
+          .enum(FRAMEWORK_OPTIONS)
           .default("auto")
-          .describe("Project framework. Use auto to inspect repository context and infer it; framework changes how metadata and rendering are implemented."),
+          .describe("Project framework. With auto, inspect projectContext and repository files before choosing framework-specific implementation details."),
         projectContext: z
           .string()
           .optional()
-          .describe("Optional package.json/framework config or brief project details to help select the right implementation steps."),
+          .describe("Optional package.json, framework/router configuration, or brief project details. Used as evidence when framework is auto."),
       },
     },
     async ({ framework, projectContext }) => {