@neuctra/ui-mcp 0.1.0 → 0.2.1

package/README.md

@@ -1,57 +1,228 @@
 # @neuctra/ui-mcp
 
-An MCP (Model Context Protocol) server that gives AI coding assistants ground-truth
-knowledge of the [`@neuctra/ui`](../neuctra-ui-package) component library — real prop
-names, types, defaults, and usage examples straight from source, plus the semantic
-theming rules — so generated code doesn't guess or hallucinate.
-
-## Tools
-
-- **`list_components`** — list all components, optionally filtered by category
-  (`layout`, `typography`, `form`, `actions`, `data-display`, `feedback`, `overlay`,
-  `navigation`).
-- **`get_component`** — full spec for one component: every prop (type, required,
-  default, description) plus a real usage example scraped from the docs site.
-- **`search_components`** — keyword search across name/category/description/prop names.
-- **`get_theme`** — the semantic color token system (`bg-primary`, `text-foreground`, ...)
-  and the rule set for using it instead of hardcoded Tailwind colors, so generated UI
-  respects the consumer's light/dark theme.
-
-## Data source
-
-`data/components.json` is a synced copy of
-[`neuctra-ui-package/registry/components.json`](../neuctra-ui-package/registry/components.json),
-which is generated from the TypeScript source via `npm run registry:generate` in that
-package (parses prop interfaces + JSDoc with `ts-morph`, plus scrapes one usage example
-per component from the docs site). Run `npm run sync-registry` here after regenerating it
-there. `data/theme.json` is hand-curated from the CLI's CSS template
-(`neuctra-ui-cli/lib/update-css.js`) and updated manually if the token set changes.
-
-## Local development
+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.
+
+This document explains what that means, why it exists, and how every piece of it works.
+
+---
+
+## 1. The problem this solves
+
+Ask an AI assistant to "build a login form with Neuctra UI" and it has two options:
+
+- **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.
+
+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.
+
+---
+
+## 2. How the pieces fit together
+
+```
+neuctra-ui-package/src/components/basic/*.tsx     (your actual component source)
+        │
+        │  npm run registry:generate  (ts-morph reads props/JSDoc/defaults,
+        │                               scrapes one example per component
+        │                               from neuctra-ui-docs)
+        ▼
+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                        (defines 4 MCP tools over that data)
+        │
+        │  spoken over stdio (stdin/stdout), JSON-RPC under the hood
+        ▼
+   Claude Code / Cursor / Antigravity / any MCP client
+```
+
+Two 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* ("never
+  hardcode colors"), not just data.
+
+---
+
+## 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 4 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. The four tools, in detail
+
+### `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 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\"", "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}"
+}
+```
+
+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.
+
+### `search_components`
+
+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.
+]
+```
+
+### `get_theme`
+
+Returns the semantic color token system and the styling rules for using it. This is the
+piece that stops generated UI from looking "off-brand" or breaking in dark mode —
+without it, an AI would happily write `className="bg-blue-500"`, which ignores whatever
+theme the consumer's project has configured.
+
+**Response shape:**
+```jsonc
+{
+  "system": "Tailwind CSS v4, semantic CSS-variable tokens mapped via @theme, toggled by a .dark class...",
+  "rules": [
+    "Never use hardcoded Tailwind palette colors...",
+    "Always use the semantic token classes below...",
+    // ...
+  ],
+  "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
+  ]
+}
+```
+
+---
+
+## 5. Local development
 
 ```bash
 npm install
 npm run sync-registry   # pulls the latest registry.json from neuctra-ui-package
-npm start                # runs the server on stdio
+npm start                # runs the server on stdio — it will sit there silently, that's correct
 ```
 
-## Using with Claude Code / Claude Desktop
+`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 6) 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.
+
+---
+
+## 6. Connecting it to a client
 
-Add to your MCP config (`.mcp.json` for a project, or Claude Desktop's config file):
+All MCP clients use the same JSON shape — the differences are just *where* the config
+file lives.
 
+**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"]
-    }
+    "neuctra-ui": { "command": "npx", "args": ["-y", "@neuctra/ui-mcp"] }
   }
 }
 ```
 
-Or, for local development against this repo:
+**Cursor** — Settings → MCP → "Add new MCP server", or edit `.cursor/mcp.json`
+(project) / `~/.cursor/mcp.json` (global) with the same JSON shape as above.
 
+**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`).
+
+**Local development, any client** (before publishing, or to test changes):
 ```json
 {
   "mcpServers": {
@@ -63,9 +234,62 @@ Or, for local development against this repo:
 }
 ```
 
-## Publishing
+Restart the client after editing its config — servers are only launched on startup.
+
+---
+
+## 7. Keeping the registry in sync
+
+The registry is generated, not hand-maintained. Whenever a component's props change:
+
+```bash
+cd neuctra-ui-package
+npm run registry:generate     # re-parses source, re-scrapes docs examples
+
+cd ../neuctra-ui-mcp
+npm run sync-registry         # copies the updated file in
+```
+
+`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` is the one file with no generator;
+edit it directly if the token set in `neuctra-ui-cli/lib/update-css.js` ever changes.
+
+---
+
+## 8. Publishing
 
 ```bash
-npm run sync-registry   # or rely on prepublishOnly, which does this automatically
-npm publish --access public
+npm run sync-registry
+npm publish --access public   # --access public is required: scoped packages default to private
 ```
+
+---
+
+## 9. Project structure
+
+```
+neuctra-ui-mcp/
+├── bin/
+│   └── cli.mjs              # entry point: connects the server to a stdio transport
+├── src/
+│   └── server.mjs           # defines the 4 tools and their handlers
+├── 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/rules data
+└── package.json
+```
+
+---
+
+## 10. Extending it
+
+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.

package/data/components.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema#",
   "package": "@neuctra/ui",
-  "version": "0.5.1",
-  "generatedAt": "2026-08-14T05:17:59.722Z",
+  "version": "0.5.2",
+  "generatedAt": "2026-08-14T05:45:27.177Z",
   "componentCount": 76,
   "components": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuctra/ui-mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "MCP server exposing the @neuctra/ui component registry (props, defaults, examples, theme tokens) so AI coding tools generate accurate Neuctra UI code.",
   "type": "module",
   "license": "MIT",