ui-react-mcp

An MCP server that gives AI assistants accurate, up-to-date documentation for @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.

Related MCP server: CDS Components MCP Server

Tools

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

```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.

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

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

Claude Desktop, Cursor and other clients (mcpServers config)

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

VS Code (.vscode/mcp.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

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