@neuctra/ui-mcp 0.4.4 → 0.4.5

package/README.md

@@ -47,7 +47,9 @@ neuctra-ui-mcp/data/components.json                 (this package's local copy)
         │
         │  read once at server startup
         ▼
-neuctra-ui-mcp/src/server.mjs                        (defines 5 MCP tools over that data)
+neuctra-ui-mcp/src/server.mjs                        (loads data and composes tool modules)
+        │
+        └── neuctra-ui-mcp/src/tools/*/                (one folder per MCP tool)
         │
         │  spoken over stdio (stdin/stdout), JSON-RPC under the hood
         ▼
@@ -76,8 +78,10 @@ Three independently-regenerable files feed the server:
   engine and generative engine optimisation, schema weaving, FAQs, the per-page meta
   checklist, where metadata goes in each framework plus Next.js metadata gotchas, page
   templates for tool/category/home pages, site-wide essentials, ads readiness, off-page
-  and monitoring, and a launch checklist). Served by `get_seo_guide`; the logic behind `generate_page_seo` and
-  `audit_page_seo` lives in `src/seo.mjs`.
+  and monitoring, and a launch checklist). The `neuctra-ui-seo-setup` tool returns the
+  complete rules plus framework-specific implementation steps.
+- **`data/layouts.json`** — editable page-layout recipes consumed by
+  `neuctra-ui-page-builder`. Add a recipe there to support a new page type.
 
 ---
 
@@ -95,7 +99,7 @@ The host starts your server as a subprocess and talks to it over **stdio** — y
 server's stdout carries JSON-RPC messages, not human-readable logs (that's why
 `bin/cli.mjs` prints nothing except protocol traffic; use `console.error`, never
 `console.log`, if you ever add debug output). On connect, the client asks "what tools do
-you have?", gets back the 5 tool definitions below, and adds them to the AI's available
+you have?", gets back the tool definitions below, and adds them to the AI's available
 actions — the same way the tools listed in *this* conversation's system prompt work.
 From then on, the AI decides on its own when a tool call would help, calls it, and reads
 the result back into its context before continuing.
@@ -104,131 +108,76 @@ the result back into its context before continuing.
 
 ## 4. Recommended workflow
 
+For project initialization, call **`neuctra-ui-setup`** first with `action: "analyze"`.
+It detects Next.js, Vite React, Remix, and React Router, then guides a separate setup
+call. Setup can run the Neuctra UI CLI and install `lucide-react`, or return manual
+instructions. Existing supported projects are kept in place; clearing a populated
+directory requires explicit confirmation. An unspecified framework defaults to Next.js
+App Router with JavaScript, Tailwind, and static export.
+
 The tools are designed to be called in roughly this order when generating UI, not
 grabbed ad hoc:
 
-1. **`neuctra-ui-builder`** — use this for routine UI generation. It infers the UI
-   category, returns a focused UX plan, core styling and accessibility rules, relevant
-   design-guide sections, component candidates, and preference questions when useful.
-2. Ask any high-impact questions returned in `uxPlan.preferenceQuestions`, then pass
-   answers back through `preferences` if they change the implementation.
-3. **`list_components`** (filtered by category) or **`search_components`** (keyword) —
-   confirm which real components exist for what you need. This matters specifically
-   because the design guide can describe a *pattern* (e.g. a sidebar nav item) without
-   there being a dedicated component for it — don't assume one exists, confirm here.
-4. **`get_component`** — full spec for every unfamiliar component before writing code against it.
-   Do this every time you touch a component you haven't already pulled specs for in the
-   current conversation, not just once at the start. Never guess prop names from memory.
-5. **Write the UI**, applying the design rules, the tokens, and the exact props from
-   step 4.
-6. **Self-check** against the "Final UI Quality Checklist" section (§49, found by
-   its `number` field in `productDesignGuide.sections` — not by array index) and
-   `antiAiLookRules` from `get_design_rules` before considering the UI
-   done — reread them, don't just rely on having read them once at the start.
-
-7. **For public pages**, call **`get_seo_guide`** once, then **`generate_page_seo`** for
-   each page (meta, OpenGraph and a woven JSON-LD graph in the project's framework) and
-   **`audit_page_seo`** to check the finished page.
-
-Call `get_design_rules` for broad design reviews or unresolved edge cases, and `get_theme`
+1. **`neuctra-ui-page-builder`** — describe the page and its goal. It infers the page type,
+   selects a recipe from `data/layouts.json`, and combines matching component specs,
+   design rules, and framework-specific SEO guidance.
+2. Resolve any high-impact preferences the builder flags, then implement the returned
+   page outline using the exact Neuctra UI imports and props it supplies.
+3. **Self-check** against the returned responsive, accessibility, and visual rules.
+4. For detailed component discovery outside a page plan, use **`get-neuctra-ui-component`**.
+5. For design or SEO reference material, use **`get_design_rules`**,
+   **`neuctra-ui-theme-setup`**, or **`neuctra-ui-seo-setup`** as needed.
+
+Call `get_design_rules` for broad design reviews or unresolved edge cases, and `neuctra-ui-theme-setup`
 when the complete token/setup reference is needed. The full guide remains the source of
-truth; the builder selects relevant sections for each request.
+truth; `neuctra-ui-page-builder` selects relevant sections for each request.
 
 ---
 
-## 5. The nine tools, in detail
+## 5. The six tools, in detail
 
-### `neuctra-ui-builder`
+### `neuctra-ui-page-builder`
 
-Creates a compact, category-aware brief for the host model. It infers or accepts a UI
-category, selects relevant UX rules and component candidates, includes essential Neuctra
-styling rules and semantic token names, and asks about visual direction, density, or the
-primary action when those preferences are missing. It plans and curates context; the host
-model writes the UI. Use `get_component` for exact props before implementing an unfamiliar
-component.
+Analyzes the request, infers a page type, and selects its layout recipe from
+`data/layouts.json`. It combines the layout outline with matching full component specs,
+relevant Neuctra UI design rules, and SEO rules/implementation steps for the selected
+framework. Recipes can be edited or added to `layouts.json` without changing tool code.
 
-**Input:** `{ request: string, category?: "auto" | "dashboard" | "landing-page" | "form" | "settings" | "authentication" | "data-table" | "ecommerce" | "documentation" | "custom", preferences?: { visualDirection?, density?, primaryAction?, platform?, audience? } }`
+**Input:** `{ request: string, pageType?: "auto" | layout id, framework?: "auto" | framework id, preferences?: { visualDirection?, density?, primaryAction?, platform?, audience? } }`
 
 ```json
 {
-  "request": "Build a project dashboard where a team can review activity and invite members.",
-  "category": "auto",
-  "preferences": { "density": "balanced", "platform": "responsive" }
+  "request": "Build an online image compressor with upload, preview, and download steps.",
+  "pageType": "auto",
+  "framework": "auto"
 }
 ```
 
-### `list_components`
-
-Lists every exported component, optionally filtered to one category. Cheap and compact
-(no props) — meant for browsing, not for writing code against.
-
-**Input:** `{ category?: "layout" | "typography" | "form" | "actions" | "data-display" | "feedback" | "overlay" | "navigation" }`
-
-**Example call → response:**
-```jsonc
-// list_components({ category: "form" })
-[
-  { "name": "Calendar", "category": "form", "description": "", "propCount": 9 },
-  { "name": "Checkbox", "category": "form", "description": "A flexible checkbox component...", "propCount": 29 },
-  { "name": "DatePicker", "category": "form", "description": "", "propCount": 15 }
-  // ...
-]
-```
-
-### `get_component`
+The result includes page classification and evidence, the chosen section outline,
+component imports/props/examples, relevant design rules, and public-page SEO guidance.
 
-The main tool. Full spec for exactly one component — every prop's name, TypeScript
-type, whether it's required, its default value, its JSDoc description if it has one,
-and a real usage snippet. The AI is instructed (via the tool's own description) to call
-this before writing code against any component it hasn't already used in the
-conversation.
-
-**Input:** `{ name: string }` — exact component name, e.g. `"Input"`, `"CardHeader"`.
-
-**Example call → response** (trimmed):
-```jsonc
-// get_component({ name: "Button" })
-{
-  "name": "Button",
-  "category": "actions",
-  "description": "The Button component is a flexible, highly customizable UI primitive...",
-  "props": [
-    { "name": "children", "type": "React.ReactNode", "required": false, "default": null,
-      "description": "Optional so icon-only buttons are possible — pair with `aria-label`." },
-    { "name": "loading", "type": "boolean", "required": false, "default": "false", "description": "" },
-    { "name": "variant", "type": "\"default\" | \"outline\" | \"ghost\" | \"secondary\" | \"destructive\" | \"success\" | \"warning\" | \"info\"", "required": false, "default": null, "description": "" }
-    // ...
-  ],
-  "example": "import { Button } from '@neuctra/ui';\n\nfunction BasicExample() {\n  return (\n    <Button onClick={() => console.log('Button clicked')}>\n      Click Me\n    </Button>\n  );\n}"
-}
-```
+### `get-neuctra-ui-component`
 
-If the name doesn't match, it doesn't just fail — it returns an error result with
-substring-matched suggestions (e.g. asking for `"Inpu"` suggests `"Input"`), so the AI
-can self-correct instead of giving up.
+One component discovery and retrieval tool for the prebuilt `@neuctra/ui` library. Give
+it a natural-language need such as `"responsive container for a page layout"`,
+`"input fields for a signup form"`, `"product image carousel"`, or `"confirmation drawer"`.
+It ranks matching components and returns each exact package import, full prop spec, and
+documented example. Use `componentName` for an exact component, `category` to narrow or
+browse, and `limit` to control how many full specs are returned.
 
-### `search_components`
+**Input:** `{ request?: string, componentName?: string, category?: ComponentCategory, limit?: number }`
 
-For when the AI knows what it needs but not the exact name — "date picker", "loading
-state", "icon button". Matches against name, category, description, and prop names.
-
-**Example:**
-```jsonc
-// search_components({ query: "date" })
-[
-  { "name": "Calendar", ... },
-  { "name": "DatePicker", ... },
-  { "name": "TagInput", ... }  // matched because it has an "updatedAt"-style prop, etc.
-]
+```json
+{ "request": "responsive carousel for product images", "limit": 3 }
 ```
 
-### `get_theme`
+### `neuctra-ui-theme-setup`
 
 Returns the semantic color token system: the token list itself, a **setup** block
 pointing the AI at the `@neuctra/ui-cli` `init` command instead of hand-writing token CSS
 or a theme context, and a **toastNote** explaining the standalone `toast()` import.
-Without `get_theme`, an AI would happily write `className="bg-blue-500"`, ignoring the
-consumer's actual theme. `get_theme` does **not** carry the design/anti-AI-look rules —
+Without `neuctra-ui-theme-setup`, an AI would happily write `className="bg-blue-500"`, ignoring the
+consumer's actual theme. `neuctra-ui-theme-setup` does **not** carry the design/anti-AI-look rules —
 see `get_design_rules` below for those; call both together, not one instead of the other.
 
 **Response shape:**
@@ -266,7 +215,7 @@ per-component usage guidance (when to reach for `Card` vs plain whitespace, `Mod
 responsive design, accessibility, interaction design, and a final UI quality checklist.
 
 Use this for full-guide reviews and edge cases. For routine generation, use
-`neuctra-ui-builder` to retrieve the rules relevant to the request.
+`neuctra-ui-page-builder` to retrieve the layout-specific rules and context.
 
 **Response shape (trimmed):**
 ```jsonc
@@ -295,51 +244,20 @@ Use this for full-guide reviews and edge cases. For routine generation, use
 }
 ```
 
-### `get_seo_guide`
-
-Returns the SEO / AEO / GEO playbook from `data/seoGuide.json`: the whole guide, or one
-topic via `topic` (`technical`, `performance`, `on-page`, `keywords-intent`, `eeat`,
-`aeo`, `geo`, `schema`, `faq`, `meta-checklist`, `frameworks`, `page-templates`,
-`site-wide`, `ads-readiness`, `off-page-monitoring`, `launch-checklist`).
-
-```json
-{ "topic": "geo" }
-```
-
-### `generate_page_seo`
-
-Deterministic generator (no LLM, never invents facts) for everything one page needs:
-a meta title (60 chars max) and description (155 max), canonical, robots, OpenGraph
-and Twitter tags, and one JSON-LD `@graph` weaving Organization, WebSite, WebPage,
-BreadcrumbList, the page-type node (TechArticle, BlogPosting, SoftwareApplication for
-tool and product pages, Product with offers), HowTo (from the visible `steps`), ItemList
-(from a category's `items`) and FAQPage together by stable `@id`s (the same scheme as
-`neuctra-ui-docs-v2/lib/seo/schemas`). Returns a ready-to-paste snippet for
-`nextjs-app`, `nextjs-pages`, `react-vite`, `react-router`, `astro`, `tanstack-start`,
-`gatsby` or `html`, plus warnings and AEO/GEO follow-ups.
-
-```json
-{
-  "framework": "nextjs-app",
-  "pageType": "docs",
-  "siteName": "Neuctra UI",
-  "siteUrl": "https://ui.neuctra.com",
-  "path": "/docs/card",
-  "primaryKeyword": "react card component",
-  "description": "Composable React card component with header, body and footer sections...",
-  "faqs": [{ "question": "Does Card support dark mode?", "answer": "Yes. ..." }]
-}
-```
+### `neuctra-ui-seo-setup`
 
-### `audit_page_seo`
+Returns the complete SEO/AEO/GEO rules and practical implementation steps from
+`data/seoGuide.json`. The JSON contains two main portions: `seoRules` (the full rules
+covering technical SEO, keywords, titles, descriptions, headings, content, JSON-LD,
+FAQs, performance, trust, and launch checks) and `implementationSteps` (ordered shared
+steps plus framework-specific instructions).
 
-Rule-based check of one page. The easiest input is the page's built HTML (`html`, from
-view-source or the `out/` / `dist/` folder): title, description, canonical, headings,
-og:image, JSON-LD types, alt text and word count are extracted from it. Explicit fields
-override the extracted ones, and checks without input are skipped. It catches doubled or
-missing brand suffixes (with `brandName`), duplicate schema nodes, JSON-LD that doesn't
-parse, and pages that render client-only (no H1 in the HTML). Returns a 0–100 score and a sorted
-list of `fail` / `warn` / `pass` items, each with the exact fix.
+Pass `framework` as `auto`, `nextjs-app`, `nextjs-pages`, `react-vite`, `react-router`,
+`remix`, or another supported framework. With `auto`, inspect project files and select
+steps that match the detected router and rendering mode. You can pass `projectContext`
+with relevant project configuration when helpful. The tool returns the complete rules
+alongside the applicable framework instructions; it does not emit a one-off metadata
+snippet or accept a page audit payload.
 
 ---
 
@@ -439,15 +357,16 @@ neuctra-ui-mcp/
 ├── bin/
 │   └── cli.mjs              # entry point: connects the server to a stdio transport
 ├── src/
-│   ├── server.mjs           # defines the 9 tools and their handlers
-│   └── seo.mjs              # pure builders behind generate_page_seo / audit_page_seo
+│   ├── server.mjs           # registers the MCP tool modules
+│   └── seo.mjs              # pure SEO builders used by neuctra-ui-seo-setup
 ├── scripts/
 │   └── sync-registry.mjs    # copies registry/components.json from neuctra-ui-package
 ├── data/
 │   ├── components.json      # synced (generated) — don't edit by hand
 │   ├── theme.json           # hand-curated token + styling/anti-AI-look rules
 │   ├── aiDesignRules.json   # hand-curated 63-section product/UX design guide
-│   └── seoGuide.json        # hand-curated SEO / AEO / GEO playbook
+│   ├── seoGuide.json        # SEO / AEO / GEO rules and implementation steps
+│   └── layouts.json         # editable page layout recipes
 └── package.json
 ```