@neuctra/ui-mcp 0.4.5 → 0.4.7

package/README.md

@@ -1,382 +1,186 @@
 # @neuctra/ui-mcp
 
-An MCP server that gives AI coding assistants (Claude Code, Claude Desktop, Cursor,
-Antigravity, or anything else that speaks MCP) ground-truth knowledge of the
-[`@neuctra/ui`](../neuctra-ui-package) component library, so they write correct code
-instead of guessing.
+Give your AI coding assistant accurate, ready-to-use knowledge of [`@neuctra/ui`](https://www.npmjs.com/package/@neuctra/ui). The Neuctra UI MCP server helps an assistant set up a project, plan pages, find components with their real props, apply Neuctra design rules, and follow framework-specific SEO guidance.
 
-This document explains what that means, why it exists, and how every piece of it works.
+## What you can do
 
----
+- Set up Neuctra UI in a React project with the guided setup tool.
+- Plan a tool page, blog, dashboard, form, store page, and more with the page builder.
+- Find the right prebuilt component from a natural-language description and get its exact import, props, and example.
+- Retrieve Neuctra UI theme tokens and design rules.
+- Get SEO, AEO, and GEO rules with implementation guidance for your framework.
 
-## 1. The problem this solves
+## Install and connect
 
-Ask an AI assistant to "build a login form with Neuctra UI" and it has two options:
+You do not need to install this package into your app. Add it as an MCP server in your AI coding client; the client runs it with `npx`.
 
-- **Recall from training data.** If Neuctra UI wasn't in its training set (likely — it's
-  a small library), it has nothing to recall. It will pattern-match against libraries it
-  *does* know (shadcn/ui, MUI, Chakra) and invent plausible-looking but wrong props —
-  `<Input variant="outline" />` when your `Input` has no `variant` prop, or
-  `<Button color="blue">` when colors come from `bg-primary`-style tokens, not a `color`
-  prop.
-- **Read your source files.** Possible, but slow (it has to find and open several
-  `.tsx` files), token-expensive, and it still has to reverse-engineer the API from
-  implementation code rather than being told it directly.
+### Claude Code
 
-This package gives it a third option: **ask**. It exposes a small set of tools an AI can
-call mid-conversation — "what props does `Select` take?", "what components exist for
-forms?", "what color classes should I use?" — and gets back exact, structured answers
-generated from your actual TypeScript source. No guessing, no file-spelunking.
+```bash
+claude mcp add neuctra-ui -- npx -y @neuctra/ui-mcp
+```
 
----
+### Cursor
 
-## 2. How the pieces fit together
+Add this server to your project’s `.cursor/mcp.json` (create the file if needed):
 
+```json
+{
+  "mcpServers": {
+    "neuctra-ui": {
+      "command": "npx",
+      "args": ["-y", "@neuctra/ui-mcp"]
+    }
+  }
+}
 ```
-neuctra-ui-package/src/components/basic/*.tsx     (your actual component source)
-        │
-        │  npm run registry:generate  (ts-morph reads props/JSDoc/defaults,
-        │                               scrapes one description + example per
-        │                               component from neuctra-ui-docs-v2)
-        ▼
-neuctra-ui-package/registry/components.json        (source of truth)
-        │
-        │  npm run sync-registry  (plain file copy)
-        ▼
-neuctra-ui-mcp/data/components.json                 (this package's local copy)
-        │
-        │  read once at server startup
-        ▼
-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
-        ▼
-   Claude Code / Cursor / Antigravity / any MCP client
-```
-
-Three independently-regenerable files feed the server:
-
-- **`data/components.json`** — synced from `neuctra-ui-package/registry/components.json`.
-  Never edit this by hand; run `npm run sync-registry` after the upstream file changes.
-- **`data/theme.json`** — hand-curated from `neuctra-ui-cli/lib/update-css.js` (the CSS
-  the setup CLI generates for consumers). Update it manually if the token set changes —
-  it doesn't have an automated generator because it also encodes *rules*, not just data:
-  the color-token rules ("never hardcode colors"), the anti-AI-look rules ("no
-  gradients/shadows/blurs/glows/emoji-icons"), the recommended `@neuctra/ui-cli init`
-  setup command, and how the standalone `toast()` API works.
-- **`data/aiDesignRules.json`** — also hand-curated, no generator. A 63-section
-  product/UX design guide (design philosophy, visual hierarchy, page/sidebar/navigation
-  structure, per-component usage guidance, spacing/color/border/radius/shadow
-  conventions, responsive design, accessibility, and a final UI quality checklist).
-  `theme.json`'s `rules`/`antiAiLookRules` are the mechanical, CSS-level rules; this file
-  is the higher-level product-design layer — both are served together by
-  `get_design_rules`.
-- **`data/seoGuide.json`** — hand-curated, no generator. A 16-topic SEO / AEO / GEO
-  playbook (technical SEO, Core Web Vitals, on-page, keywords and intent, E-E-A-T, answer
-  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). 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.
-
----
-
-## 3. What MCP actually is (30-second primer)
-
-MCP (**M**odel **C**ontext **P**rotocol) is a standard for connecting an AI assistant to
-external tools. Three roles:
-
-- **Host** — the AI app itself (Claude Code, Cursor, Antigravity).
-- **Client** — the part of the host that manages a connection to one server.
-- **Server** — a small program (this package) that exposes **tools** (named actions with
-  typed inputs) the AI can decide to call.
-
-The host starts your server as a subprocess and talks to it over **stdio** — your
-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 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.
-
----
-
-## 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-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; `neuctra-ui-page-builder` selects relevant sections for each request.
-
----
-
-## 5. The six tools, in detail
-
-### `neuctra-ui-page-builder`
 
-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.
+### Other MCP clients
 
-**Input:** `{ request: string, pageType?: "auto" | layout id, framework?: "auto" | framework id, preferences?: { visualDirection?, density?, primaryAction?, platform?, audience? } }`
+Add a server with command `npx` and arguments `-y`, `@neuctra/ui-mcp`. If your client uses JSON configuration, the server entry is:
 
 ```json
 {
-  "request": "Build an online image compressor with upload, preview, and download steps.",
-  "pageType": "auto",
-  "framework": "auto"
+  "command": "npx",
+  "args": ["-y", "@neuctra/ui-mcp"]
 }
 ```
 
-The result includes page classification and evidence, the chosen section outline,
-component imports/props/examples, relevant design rules, and public-page SEO guidance.
+Restart or reload your AI client after changing its MCP settings. On first launch, `npx` downloads the package from npm.
 
-### `get-neuctra-ui-component`
+## Recommended workflow
 
-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.
+1. Ask your assistant to analyze the current project with `neuctra-ui-setup`.
+2. Use `neuctra-ui-page-builder` to plan a page from its goal and user needs.
+3. Use the returned component specs and examples to implement the page. For additional component discovery, call `get-neuctra-ui-component`.
+4. Use `neuctra-ui-theme-setup` and `get_design_rules` for theme tokens, composition guidance, accessibility, and visual rules.
+5. For public pages, use `neuctra-ui-seo-setup` with the project’s framework so the assistant can apply the right SEO steps.
 
-**Input:** `{ request?: string, componentName?: string, category?: ComponentCategory, limit?: number }`
+The assistant writes the application code. The page builder supplies a layout plan and verified component guidance; it does not generate an entire page file by itself.
 
-```json
-{ "request": "responsive carousel for product images", "limit": 3 }
-```
+## Available tools
 
-### `neuctra-ui-theme-setup`
+### `neuctra-ui-setup`
+
+Analyze a project and guide or run Neuctra UI setup.
+
+- First call with `action: "analyze"` to detect the existing framework and project state.
+- Then call with `action: "setup"` and choose `setupMode: "cli"` or `"manual"`.
+- Supported setup frameworks: `nextjs`, `vite`, `remix`, and `react-router`.
+- If no framework is specified, Next.js App Router with JavaScript, Tailwind, and static export is the recommended default.
+- Existing matching projects are initialized in place. Replacing or clearing files requires explicit confirmation.
+- CLI setup runs `npx @neuctra/ui-cli@latest init` and installs `lucide-react`.
 
-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 `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.
+Example analyze request:
 
-**Response shape:**
-```jsonc
+```json
 {
-  "system": "Tailwind CSS v4, semantic CSS-variable tokens mapped via @theme, toggled by a .dark class...",
-  "tokens": [
-    { "token": "primary", "className": "bg-primary / text-primary / border-primary",
-      "pairsWith": "primary-foreground", "light": "#00c214", "dark": "#00c214",
-      "usage": "Brand color: primary buttons, active states, links, focus accents." },
-    // ...23 tokens total
-  ],
-  "note": "Values shown are the CLI-generated defaults...",
-  "setup": {
-    "recommendedCommand": "npx @neuctra/ui-cli@latest init",
-    "whatItDoes": ["Installs @neuctra/ui.", "Checks/upgrades React and Tailwind CSS.", "..."],
-    "whenToSuggestIt": "..."
-  },
-  "toastNote": "@neuctra/ui's toast notification system is a standalone function..."
+  "action": "analyze"
 }
 ```
 
-### `get_design_rules`
+Example setup request after selecting Next.js and CLI setup:
 
-Returns every design rule generated UI must follow, at two levels: the mechanical
-**`stylingRules`** (token usage, surface/background conventions, component composition
-requirements — e.g. `CardBody` is compulsory whenever `Card` has body content, since
-`Card` itself renders no padding — and component-specific gotchas like Dropdown's
-trigger already stopping propagation internally) and **`antiAiLookRules`** (no
-gradients/shadows/blurs/glows/emoji-icons/em-dashes — the visual tells that make UI read
-as AI-generated), plus **`productDesignGuide`** — a 63-section product/UX design guide
-covering design philosophy, visual hierarchy, page/sidebar/navigation structure,
-per-component usage guidance (when to reach for `Card` vs plain whitespace, `Modal` vs
-`Drawer`, `Table` vs `List`, etc.), spacing/color/border/radius/shadow conventions,
-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-page-builder` to retrieve the layout-specific rules and context.
-
-**Response shape (trimmed):**
-```jsonc
+```json
 {
-  "stylingRules": [
-    "Theme colors only, compulsory, no exceptions...",
-    "Use the Card component, not a hand-rolled lookalike...",
-    // ...9 rules total
-  ],
-  "antiAiLookRules": [
-    "No gradients, compulsory...",
-    "No shadows, compulsory...",
-    "No blur effects, compulsory...",
-    // ...17 rules total
-  ],
-  "productDesignGuide": {
-    "title": "Neuctra UI — AI Design Rules",
-    "intro": "You are a senior product designer and frontend UI engineer using `@neuctra/ui`...",
-    "sections": [
-      { "number": 1, "title": "Core Design Philosophy", "content": "..." },
-      { "number": 7, "title": "Cards", "content": "..." },
-      // ...63 sections total
-    ],
-    "goldenRule": { "title": "Golden Rule", "content": "..." }
-  }
+  "action": "setup",
+  "framework": "nextjs",
+  "setupMode": "cli"
 }
 ```
 
-### `neuctra-ui-seo-setup`
-
-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).
-
-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.
+### `neuctra-ui-page-builder`
 
----
+Describe the page and the task it should support. The tool infers a page type, selects a matching layout recipe, and combines it with relevant Neuctra UI component specs, design rules, and framework-aware SEO guidance.
 
-## 6. Local development
+Supported page recipes include tool pages, blog pages, dashboards, landing pages, forms, authentication, settings, data tables, ecommerce, documentation, and custom pages.
 
-```bash
-npm install
-npm run sync-registry   # pulls the latest registry.json from neuctra-ui-package
-npm start                # runs the server on stdio — it will sit there silently, that's correct
+```json
+{
+  "request": "Build an online image compressor with upload, preview, and download steps.",
+  "pageType": "auto",
+  "framework": "auto"
+}
 ```
 
-`npm start` alone won't show you anything (it's waiting for a client to speak JSON-RPC
-to it, not for a human to type at it). To actually exercise it, either wire it into a
-real client (section 7) or write a small script using
-`@modelcontextprotocol/sdk`'s `Client` + `StdioClientTransport` to spawn `bin/cli.mjs`
-and call the tools programmatically — that's how this server was verified while building
-it.
+Use `pageType: "auto"` to infer the closest specific layout from the request, or choose any layout ID from the grouped catalog in `data/layouts.json`. The catalog covers marketing, SaaS applications, e-commerce, publishing, support, portfolios, communities, events, forms, and system pages. Use `framework: "auto"` to have the assistant identify the project framework, or provide a framework such as `nextjs-app`, `react-vite`, `react-router`, or `remix`.
 
----
-
-## 7. Connecting it to a client
+### `get-neuctra-ui-component`
 
-All MCP clients use the same JSON shape — the differences are just *where* the config
-file lives.
+Find components by describing what the interface needs. Results include the component’s exact package import, full prop definitions, and documented usage example.
 
-**Claude Code** — project-scoped, via CLI:
-```bash
-claude mcp add neuctra-ui -- npx -y @neuctra/ui-mcp
-```
-or by hand in `.mcp.json` at the repo root:
 ```json
 {
-  "mcpServers": {
-    "neuctra-ui": { "command": "npx", "args": ["-y", "@neuctra/ui-mcp"] }
-  }
+  "request": "A responsive carousel for product images",
+  "limit": 3
 }
 ```
 
-**Cursor** — Settings → MCP → "Add new MCP server", or edit `.cursor/mcp.json`
-(project) / `~/.cursor/mcp.json` (global) with the same JSON shape as above.
+You can also provide an exact `componentName` such as `Container`, `Input`, `Carousel`, `Card`, `Modal`, or `Drawer`. Use `category` to browse a component group (`layout`, `typography`, `form`, `actions`, `data-display`, `feedback`, `overlay`, or `navigation`).
 
-**Antigravity** — Settings → search "MCP" → "Manage MCP Servers" opens a JSON config
-using the same `mcpServers` shape (or a form asking for command + args — use `npx` and
-`-y @neuctra/ui-mcp`).
+Example component usage:
 
-**Local development, any client** (before publishing, or to test changes):
-```json
-{
-  "mcpServers": {
-    "neuctra-ui": {
-      "command": "node",
-      "args": ["/absolute/path/to/neuctra-ui-mcp/bin/cli.mjs"]
-    }
-  }
+```jsx
+import { Container } from "@neuctra/ui";
+
+function BasicExample() {
+  return (
+    <Container size="md" center className="bg-zinc-800 p-4 rounded-lg">
+      Hello Developer! I am a container.
+    </Container>
+  );
 }
 ```
 
-Restart the client after editing its config — servers are only launched on startup.
+Check the returned props and example before using a component. Component APIs can differ from similarly named components in other libraries.
 
----
+### `neuctra-ui-theme-setup`
 
-## 8. Keeping the registry in sync
+Returns the Neuctra UI semantic theme tokens, Tailwind theme mappings, and theme setup guidance. Use these tokens (such as `bg-primary` and `text-foreground`) so components work with the configured light and dark themes. The tool also explains the `toast()` API.
 
-The registry is generated, not hand-maintained. Whenever a component's props change:
+### `get_design_rules`
 
-```bash
-cd neuctra-ui-package
-npm run registry:generate     # re-parses source, re-scrapes docs examples
+Returns Neuctra UI’s design guidance, including component composition requirements, theme usage, accessibility, responsive behavior, spacing, hierarchy, and visual consistency. Use it when planning or reviewing an interface. The page builder includes the rules most relevant to its selected page layout.
+
+### `neuctra-ui-seo-setup`
 
-cd ../neuctra-ui-mcp
-npm run sync-registry         # copies the updated file in
+Returns the complete SEO, AEO, and GEO rules and ordered implementation steps. Framework matters: Next.js metadata APIs differ from Vite React, Remix, and React Router. Pass a framework or use `auto` and give the assistant the project context when useful.
+
+```json
+{
+  "framework": "auto",
+  "projectContext": "React Router app using server rendering"
+}
 ```
 
-`registry:generate` also runs automatically as part of `neuctra-ui-package`'s
-`prepublishOnly`, and `sync-registry` runs automatically as part of this package's own
-`prepublishOnly` — so a normal `npm publish` in each package keeps things current without
-remembering these steps by hand. `data/theme.json` and `data/aiDesignRules.json` are the
-two files with no generator; edit them directly — `theme.json` if the token set in
-`neuctra-ui-cli/lib/update-css.js` ever changes or a rule needs adding, `aiDesignRules.json`
-if the product-design guidance itself needs revising.
+The guidance covers titles and descriptions, keyword and search intent, heading structure, canonical URLs, robots directives, sitemaps, structured data (JSON-LD), visible FAQs, performance, trust signals, and framework-specific implementation. It is a reference for the assistant; it does not generate a one-off metadata snippet or audit a page.
 
----
+## Tips for better results
 
-## 9. Publishing
+- Describe the page’s purpose and the user’s main task, not just its visual style.
+- Mention the framework and router when you know them.
+- Include important constraints such as mobile-first layout, primary actions, or existing project conventions.
+- Ask the assistant to inspect component specs before writing code with unfamiliar components.
+- For public pages, ask it to keep metadata and JSON-LD consistent with content that is actually visible.
 
-```bash
-npm run sync-registry
-npm publish --access public   # --access public is required: scoped packages default to private
-```
+## Troubleshooting
 
----
+**The tools do not appear in my client**
 
-## 10. Project structure
+Check that the MCP server entry uses command `npx` with arguments `-y` and `@neuctra/ui-mcp`, then restart or reload the client. Confirm that Node.js and npm are installed and available to the client process.
 
-```
-neuctra-ui-mcp/
-├── bin/
-│   └── cli.mjs              # entry point: connects the server to a stdio transport
-├── src/
-│   ├── 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        # SEO / AEO / GEO rules and implementation steps
-│   └── layouts.json         # editable page layout recipes
-└── package.json
-```
+**The assistant selected the wrong page layout**
+
+Specify `pageType` directly (for example, `tool-page`, `blog-page`, or `dashboard`) and describe the main user task more clearly.
+
+**The assistant is unsure which component to use**
+
+Call `get-neuctra-ui-component` with a concrete need, such as “date input with calendar selection” or “drawer for mobile filters.” Review the returned component names and props before implementation.
+
+**SEO instructions do not match my app**
 
----
+Pass the actual framework and router, such as `nextjs-app`, `react-vite`, `react-router`, or `remix`. For `auto`, provide relevant project details or ask the assistant to inspect the project configuration first.
 
-## 11. Extending it
+## License
 
-To add a new tool (e.g. `get_example` returning just the code snippet, or
-`list_categories`), open `src/server.mjs` and add another `server.registerTool(...)`
-call following the existing pattern: a name, a `title`/`description` (the description is
-what the AI reads to decide *when* to call it — be specific), a `zod` input schema, and
-an async handler returning `{ content: [{ type: "text", text: ... }] }`. No other file
-needs to change — `bin/cli.mjs` just connects whatever `createServer()` returns.
+MIT