# ui-react-mcp

An [MCP](https://modelcontextprotocol.io) server that gives AI assistants accurate, up-to-date documentation for [`@alexcruzgargallo/ui-react`](https://github.com/AlexCruzGargallo/ui-react), my React component library.

## Why

When an AI assistant writes code with a component library it doesn't know, it guesses: it invents props, variants that don't exist, or wrong import paths. This server lets the assistant ask the library directly which components exist, which props they take and which values are allowed, so the code it writes actually works.

## Tools

| Tool | What it does |
| --- | --- |
| `list_components` | Lists every component with a short description. |
| `search_components` | Finds components for a need, e.g. `"loading"` or `"form field"`. |
| `get_component` | Full docs for one component: import, props, allowed values, defaults and an example. |
| `get_usage_example` | Generates JSX for a component and **validates the props**: an invalid value like `size="huge"` is reported with the allowed options instead of being used. |

Example of what the assistant gets back from `get_usage_example` with `{ "name": "Badge", "props": { "variant": "success", "size": "huge" } }`:

````md
```tsx
import { Badge } from "@alexcruzgargallo/ui-react";

<Badge variant="success">
  Badge content
</Badge>
```

Warnings:
- Invalid value "huge" for "size". Allowed values: small, medium.
````

## How it works

```
ui-react                                   ui-react-mcp
─────────                                  ────────────
lib/components/*/index.tsx
   │  (TypeScript types + JSDoc)
   ▼
scripts/generate-metadata.ts
   │  react-docgen-typescript
   ▼
lib/metadata/components.json  ──sync──▶  data/components.json
                                               │
                                               ▼
                                         Catalog (search, docs, examples)
                                               │
                                               ▼
                                         MCP tools over stdio  ◀──  AI assistant
```

- The component docs come from the library's own TypeScript types and JSDoc comments, so there is a single source of truth: change a prop in `ui-react`, regenerate the metadata, and the assistant sees the change.
- `src/catalog.ts` holds all the logic (lookup, search ranking, docs, example generation and validation) with no dependency on MCP, so it is easy to test.
- `src/server.ts` registers the tools with the official MCP TypeScript SDK and uses `zod` to validate their input.
- `src/index.ts` connects the server over stdio.

## Getting started

Requires Node.js 20 or later.

```bash
git clone https://github.com/AlexCruzGargallo/ui-react-mcp.git
cd ui-react-mcp
npm install
npm run build
```

Then add it to your AI client, replacing the path with the absolute path to your clone.

**Claude Code**

```bash
claude mcp add ui-react -- node /absolute/path/to/ui-react-mcp/dist/src/index.js
```

**Claude Desktop, Cursor and other clients** (`mcpServers` config)

```json
{
  "mcpServers": {
    "ui-react": {
      "command": "node",
      "args": ["/absolute/path/to/ui-react-mcp/dist/src/index.js"]
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "ui-react": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/ui-react-mcp/dist/src/index.js"]
    }
  }
}
```

Now ask your assistant something like *"Build a login form with ui-react"* and it will look up the components before writing the code.

To use a local checkout of `ui-react` instead of the bundled metadata, set `UI_REACT_METADATA` to the path of its `lib/metadata/components.json`.

## Development

```bash
npm test               # build and run the tests (node:test)
npm run inspect        # open the server in the MCP Inspector
npm run sync-metadata  # pull the latest components.json from ui-react
```

The tests cover the catalog logic and run the real MCP client against the server through an in-memory transport.

## License

MIT