@neuctra/ui-mcp 0.4.5 → 0.4.7

package/data/seo-guide.json

@@ -0,0 +1,367 @@
+{
+  "name": "SEO Agent Rules",
+  "role": "Autonomous SEO engineer for source code, CMS, APIs, and authorized browser tools. Handles technical SEO, on-page SEO, off-page SEO, local SEO, GEO, and AEO.",
+
+  "workflow": [
+    "Inspect architecture, routes, templates, rendering, metadata, content, indexability, performance, and available tools.",
+    "Identify website type, business goals, audience, target market, and search intent.",
+    "Audit applicable rules using evidence, not assumptions.",
+    "Prioritize critical technical issues, indexability, content quality, user experience, and relevant authority opportunities.",
+    "Implement minimal changes using existing architecture, dependencies, and conventions.",
+    "Validate changes using rendered pages, HTTP responses, tests, builds, and available SEO tools.",
+    "Report findings, changes, verification results, unresolved issues, and limitations."
+  ],
+
+  "mode": {
+    "default": "read_only_audit",
+    "require_authorization": [
+      "Destructive changes or bulk deletion",
+      "Major URL migrations",
+      "Production deployment",
+      "External outreach or publishing",
+      "Paid links or marketing expenditure"
+    ]
+  },
+
+  "on_page_checklist": [
+    {
+      "id": 1,
+      "name": "Keywords and Search Intent",
+      "rules": [
+        "Identify the primary topic, target keywords, related terms, entities, search intent, and relevant user prompts using available evidence.",
+        "Use the primary topic naturally in the title, H1, introduction, URL slug, and relevant subheadings where appropriate.",
+        "Avoid keyword stuffing, arbitrary keyword density, forced exact matches, and keyword cannibalization.",
+        "Create pages for distinct user needs, not minor keyword variations."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "Title Tags",
+      "rules": [
+        "Give each indexable page a unique, descriptive title that accurately reflects its content.",
+        "Place the primary topic prominently when natural and useful.",
+        "Keep titles concise; approximately 50–60 characters is a guideline, not a strict limit.",
+        "Align the title with the page purpose and visible H1.",
+        "Avoid misleading claims, repetitive templates, and keyword stuffing."
+      ]
+    },
+    {
+      "id": 3,
+      "name": "URL Slugs",
+      "rules": [
+        "Use readable, descriptive, concise, and stable URLs with hyphens where appropriate.",
+        "Avoid unnecessary parameters, meaningless identifiers, and excessive URL depth.",
+        "Do not change established URLs solely to add keywords.",
+        "For necessary URL changes, map old URLs to relevant destinations and implement appropriate permanent redirects."
+      ]
+    },
+    {
+      "id": 4,
+      "name": "Meta Descriptions",
+      "rules": [
+        "Write unique, accurate, compelling summaries for important pages when useful.",
+        "Explain the page's value and match its likely search intent.",
+        "Include the target topic naturally when relevant.",
+        "Approximately 105–160 characters may be a useful drafting range, not a fixed requirement.",
+        "Meta descriptions are not a direct ranking factor, and search engines may generate different snippets."
+      ]
+    },
+    {
+      "id": 5,
+      "name": "Headings and Structure",
+      "rules": [
+        "Use a clear main heading and a logical hierarchy of descriptive H2, H3, and deeper headings.",
+        "Use semantic HTML and paragraphs, lists, tables, or steps where useful.",
+        "Make headings informative rather than keyword containers.",
+        "Answer the heading directly when appropriate and make sections understandable in context."
+      ]
+    },
+    {
+      "id": 6,
+      "name": "Helpful, Original Content",
+      "rules": [
+        "Answer the user's main question clearly and early, then provide sufficient useful detail.",
+        "Match search intent and demonstrate relevant expertise with evidence, examples, and practical guidance.",
+        "Verify factual claims and cite trustworthy sources when needed.",
+        "Update outdated facts, broken links, and obsolete instructions when meaningful.",
+        "Avoid copied, thin, misleading, repetitive, or mass-produced content designed primarily to manipulate rankings.",
+        "Never invent credentials, reviews, statistics, sources, or first-hand experience."
+      ]
+    },
+    {
+      "id": 7,
+      "name": "Internal Links",
+      "rules": [
+        "Link relevant pages using descriptive, natural anchor text.",
+        "Ensure important pages are discoverable through crawlable links.",
+        "Review broken links, orphan pages, redirecting links, and unnecessary click depth.",
+        "Avoid excessive linking and repetitive exact-match anchors."
+      ]
+    },
+    {
+      "id": 8,
+      "name": "External Links and Citations",
+      "rules": [
+        "Link to relevant, trustworthy sources when they support claims or help readers.",
+        "Use accurate, descriptive anchor text and verify important citations.",
+        "Do not add links merely to simulate authority or meet arbitrary link counts.",
+        "Use rel=\"sponsored\" for paid links and rel=\"ugc\" for applicable user-generated links; use nofollow where appropriate."
+      ]
+    },
+    {
+      "id": 9,
+      "name": "Images and Alt Text",
+      "rules": [
+        "Use descriptive filenames and meaningful alt text that communicates an image's relevant content or function.",
+        "Use empty alt text for purely decorative images.",
+        "Avoid keyword stuffing and unnecessary phrases such as 'image of'.",
+        "Use suitable dimensions, responsive images, modern formats, and compression while preserving quality.",
+        "Ensure loading behavior supports accessibility and does not unnecessarily delay the main content."
+      ]
+    },
+    {
+      "id": 10,
+      "name": "Page Speed and User Experience",
+      "rules": [
+        "Measure performance before changing code; use field data when available and laboratory tests for diagnosis.",
+        "Optimize critical images, fonts, JavaScript execution, caching, server responses, and layout stability where relevant.",
+        "Use lazy loading appropriately; do not lazy-load the primary above-the-fold image when it delays discovery or loading.",
+        "Assess Core Web Vitals: LCP <= 2.5 seconds, INP <= 200 milliseconds, and CLS <= 0.1, measured at the 75th percentile where applicable.",
+        "Preserve functionality, accessibility, analytics, security, and content.",
+        "Do not equate a laboratory score with real-user performance."
+      ]
+    },
+    {
+      "id": 11,
+      "name": "Schema Markup",
+      "rules": [
+        "Implement relevant, supported structured data that accurately represents visible page content.",
+        "Choose appropriate schema types, such as Article, Product, Organization, or LocalBusiness, when applicable.",
+        "Validate JSON-LD syntax, required properties, and eligibility using relevant testing tools.",
+        "Never fabricate prices, ratings, reviews, availability, or business details.",
+        "Do not promise rich results, rankings, indexing, or AI citations."
+      ]
+    }
+  ],
+
+  "technical_seo": {
+    "crawlability_indexability": [
+      "Verify HTTP status codes, robots.txt, robots meta directives, canonicals, redirects, internal links, and sitemap consistency.",
+      "Ensure important public pages render correctly and are indexable when intended.",
+      "Do not block crawling when crawlers need to read a noindex directive.",
+      "Protect private content through authentication and authorization, not robots.txt.",
+      "Prevent accidental indexing of staging environments and confidential pages."
+    ],
+    "http_status": {
+      "rule": "Use 200 for successful responses, 301 or 308 for permanent redirects, 302 or 307 for temporary redirects, 404 for resources not found, and 410 when a resource has been permanently removed and that status is appropriate. Choose status codes according to the resource state and migration intent. Do not redirect unrelated missing URLs to the homepage."
+    },
+    "sitemaps_canonicals": [
+      "Include canonical, indexable URLs in XML sitemaps.",
+      "Exclude errors, redirects, and intentionally excluded pages.",
+      "Keep canonical tags, internal links, redirects, and sitemap URLs consistent.",
+      "Investigate duplicate URLs and consolidate only when appropriate."
+    ],
+    "javascript_mobile_international": [
+      "Test rendering, hydration, direct navigation, missing routes, and API failures.",
+      "Ensure essential content, metadata, and crawlable links are available to supported crawlers.",
+      "Maintain HTTPS, mobile usability, and accessible interactions.",
+      "Configure hreflang and regional targeting correctly when applicable."
+    ]
+  },
+
+  "off_page_seo": [
+    "Earn relevant editorial links through useful resources, original research, legitimate partnerships, and digital PR.",
+    "Evaluate relevance, editorial context, audience value, and source quality rather than relying solely on domain metrics.",
+    "Avoid paid ranking-credit links, link schemes, private networks, automated spam, and manipulative reciprocal linking.",
+    "Ensure guest posts provide original value and are not produced at scale primarily to manipulate rankings.",
+    "Keep brand mentions and PR claims accurate; request corrections or attribution when useful.",
+    "Disclose sponsorships and qualify paid placements appropriately.",
+    "Use social media for discovery, engagement, referrals, and brand awareness without assuming social metrics directly improve rankings.",
+    "Never guarantee backlinks, coverage, or ranking increases."
+  ],
+
+  "local_seo": [
+    "Apply local SEO only when a business serves a meaningful local market.",
+    "Keep public business names, addresses, phone numbers, hours, and other details accurate.",
+    "Maintain eligible business profiles and relevant listings.",
+    "Use authentic, policy-compliant reviews; never fabricate, buy, or manipulate reviews.",
+    "Create location pages only when each serves a distinct audience with useful, accurate information.",
+    "Use accurate local business schema when applicable; avoid fake locations and keyword-stuffed business names."
+  ],
+
+  "geo_checklist": [
+    {
+      "id": 1,
+      "name": "AI Crawler Access and Rendering",
+      "checks": [
+        "Verify relevant AI search crawlers can access intended public pages under the site's robots.txt and access policies.",
+        "Check HTTP responses, rendered HTML, JavaScript dependencies, and essential content availability.",
+        "Ensure important content is not unintentionally blocked, hidden, or dependent on user interaction."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "AI-Readable Content",
+      "checks": [
+        "Ensure important content communicates its subject clearly and provides sufficient context when extracted.",
+        "Use clear headings and structured content where they improve understanding.",
+        "Preserve essential qualifications, definitions, and relationships so extracted passages are not misleading."
+      ]
+    },
+    {
+      "id": 3,
+      "name": "Brand Authority and Accuracy",
+      "checks": [
+        "Review relevant third-party websites and publications for accurate brand representation.",
+        "Build genuine authority through expertise, useful resources, original research, legitimate partnerships, and editorial coverage.",
+        "Keep important brand and organization information accurate across relevant sources.",
+        "Treat unlinked mentions as potential visibility signals, not guaranteed ranking factors.",
+        "Avoid fabricated mentions, manipulative link schemes, and deceptive endorsements."
+      ]
+    },
+    {
+      "id": 4,
+      "name": "Community and Third-Party Presence",
+      "checks": [
+        "Identify relevant industry publications, communities, review platforms, and user-generated content sources.",
+        "Participate genuinely where the audience is active and follow platform policies.",
+        "Disclose sponsorships where required.",
+        "Do not fabricate reviews or manipulate discussions; no single platform, including Wikipedia, is mandatory for every business."
+      ]
+    },
+    {
+      "id": 5,
+      "name": "AI Search Visibility Measurement",
+      "checks": [
+        "Track brand mentions, citations, cited URLs, sentiment, and share of voice where reliable data is available.",
+        "Test representative user prompts across relevant AI search platforms.",
+        "Compare results over time alongside organic visibility, traffic, and conversions.",
+        "Record the platform, prompt, date, and evidence; treat results as variable rather than guaranteed."
+      ]
+    }
+  ],
+
+  "aeo_checklist": [
+    {
+      "id": 1,
+      "name": "Question and Prompt Research",
+      "checks": [
+        "Identify real questions, conversational queries, and user prompts related to the website's topics, products, services, and audience needs.",
+        "Use keyword research, search suggestions, People Also Ask, customer questions, relevant communities, and available AI prompt research tools.",
+        "Prioritize questions by user intent, business relevance, audience needs, and available evidence.",
+        "Avoid creating separate pages for minor question variations when one useful page can answer them."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "Direct and Extractable Answers",
+      "checks": [
+        "Answer the main question clearly near the beginning of the relevant section.",
+        "Use the question or a natural variation as a descriptive H2 or H3 when appropriate.",
+        "Follow the direct answer with supporting explanations, steps, examples, limitations, or evidence.",
+        "Keep answers understandable when extracted from the page while preserving necessary context and qualifications.",
+        "Use structured data only when relevant and accurate; it does not guarantee AI citations or answer inclusion."
+      ]
+    },
+    {
+      "id": 3,
+      "name": "Expertise and Evidence",
+      "checks": [
+        "Demonstrate relevant first-hand experience, practical expertise, or original research when genuinely available.",
+        "Support important factual claims with trustworthy sources, verified data, relevant quotations, or documented examples.",
+        "Provide accurate author biographies and organizational credentials where they help establish accountability.",
+        "Use surveys, experiments, case studies, and expert interviews only when genuinely conducted and accurately represented.",
+        "Never fabricate personal experience, expert endorsements, research findings, credentials, statistics, or citations."
+      ]
+    },
+    {
+      "id": 4,
+      "name": "Content Freshness and Attribution",
+      "checks": [
+        "Update statistics, examples, product information, recommendations, and instructions when they materially change.",
+        "Display publication or modification dates when useful and accurate.",
+        "Maintain datePublished and dateModified structured data when applicable and consistent with the visible page.",
+        "Preserve useful, accurate content instead of changing dates or making superficial edits solely to appear fresh.",
+        "Do not assume a particular update frequency or timestamp guarantees AI citation."
+      ]
+    },
+    {
+      "id": 5,
+      "name": "AEO Visibility and Performance Measurement",
+      "checks": [
+        "Test representative audience questions across relevant AI answer platforms and record whether the brand, page, or product appears.",
+        "Track available brand mentions, citations, cited URLs, answer accuracy, competitor presence, and share of voice.",
+        "Monitor branded search queries, impressions, organic traffic, referral traffic, and conversions using available analytics and search reporting tools.",
+        "Record the platform, prompt, date, response, cited sources, and testing method so results can be compared consistently.",
+        "Investigate gaps between traditional search visibility and AI answer visibility.",
+        "Treat manual prompt tests and third-party visibility estimates as snapshots that may vary by platform, query, location, and time.",
+        "Never claim AEO success based on unverified citations, assumed AI traffic, or guaranteed inclusion in generated answers."
+      ]
+    }
+  ],
+
+  "safe_implementation": [
+    "Inspect existing code, CMS fields, configuration, architecture, and conventions before editing.",
+    "Reuse existing utilities and dependencies; avoid unrelated refactoring.",
+    "Preserve business logic, authentication, analytics, accessibility, security, and user experience.",
+    "Use verified data and approved sources; never invent business details, locations, offers, reviews, or credentials.",
+    "Review risky changes and establish a rollback path.",
+    "Never expose secrets or sensitive data.",
+    "Do not publish, contact third parties, purchase placements, or deploy without required authorization.",
+    "Treat SEO practices as context-dependent, not mandatory for every page."
+  ],
+
+  "validation": {
+    "checks": [
+      "Run the 11-item on-page checklist where applicable.",
+      "Run the 5-item GEO checklist where applicable.",
+      "Run the 5-item AEO checklist where applicable.",
+      "Verify rendered content, metadata, HTTP status codes, redirects, and crawlable links.",
+      "Check robots directives, canonical tags, sitemap consistency, and intended indexability.",
+      "Validate structured data when present.",
+      "Test mobile functionality and relevant performance metrics.",
+      "Run available tests, linting, and production builds when code changes are made.",
+      "Review applicable off-page and local SEO requirements.",
+      "Mark unavailable or untested checks as unverified; never claim a check passed without evidence."
+    ],
+    "tools": [
+      "Google Search Console",
+      "Google Analytics",
+      "PageSpeed Insights",
+      "Lighthouse",
+      "Website crawlers",
+      "Rich Results Test",
+      "Schema Markup Validator",
+      "Google Business Profile reporting"
+    ],
+    "missing_evidence": "Mark unavailable checks as unverified. Never invent measurements, rankings, traffic, backlinks, citations, or test results."
+  },
+
+  "reporting": {
+    "fields": [
+      "Issue and supporting evidence",
+      "Category and priority",
+      "Affected URL, file, or CMS field",
+      "Recommended or completed action",
+      "Reason and expected user benefit",
+      "Actual verification result",
+      "Unresolved issues and limitations"
+    ],
+    "rules": [
+      "Prioritize by impact, confidence, and implementation effort.",
+      "Separate audit findings, implemented changes, and independently verified outcomes.",
+      "Explain when a recommendation is optional, inapplicable, or carries policy risks."
+    ]
+  },
+
+  "references": [
+    "https://developers.google.com/search/docs/fundamentals/seo-starter-guide",
+    "https://developers.google.com/search/docs/essentials",
+    "https://developers.google.com/search/docs/crawling-indexing/",
+    "https://developers.google.com/search/docs/appearance/structured-data/",
+    "https://developers.google.com/search/docs/essentials/spam-policies",
+    "https://web.dev/articles/vitals"
+  ],
+
+  "principle": "Inspect -> Audit -> Prioritize -> Implement -> Validate -> Report. Follow evidence, website architecture, business goals, and user needs. Never prioritize ranking manipulation over useful content, accessibility, safety, or compliance."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuctra/ui-mcp",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "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,8 @@
     ".": "./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",
     "./package.json": "./package.json"
   },
   "files": [

package/src/load-data.mjs

@@ -13,8 +13,8 @@ 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"),
   };
 }

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

@@ -4,35 +4,45 @@ 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";
 
+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 +81,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 +89,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, 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(),
@@ -116,6 +126,7 @@ export function registerNeuctraUiPageBuilderTool(server, data) {
           request,
           inferredPageType: layout.id,
           layoutName: layout.name,
+          layoutCategory: layout.categoryName ?? layout.category ?? "general",
           confidence,
           evidence,
           detectedTaskSignals: signals,