# ui-mcp

MCP server that renders flexible, shadcn-styled UI in your **local browser**. Agents call `render_ui` to show dashboards, forms, charts, comparisons, and factual answers with numbers or spatial concepts — not just when building apps.

## Quick start

```bash
npx ui-mcp init
```

This will:

1. Register the MCP server in `.cursor/mcp.json` (and `.mcp.json` for Claude Code)
2. Append agent instructions to `AGENTS.md` / `CLAUDE.md` so the model **defaults to rendering** (re-run `init` to refresh existing snippets)

Reload your editor MCP settings, then ask your agent to render something visual.

## Tools

| Tool | Description |
|------|-------------|
| `render_ui` | Create and open a UI view in the browser |
| `update_ui` | Update an existing view by id |
| `list_ui_views` | List active views and URLs |
| `close_ui_view` | Remove a view |

## Modes

- **`html`** — HTML fragment, wrapped in shadcn/Tailwind shell
- **`jsx`** — React component (`App` or `Component`), compiled in-browser via Babel
- **`page`** — Full HTML document (you control everything)

## Style

The shell applies shadcn CSS variables and Tailwind semantic colors (`bg-background`, `text-primary`, etc.). The model is free to build any layout — no component whitelist.

## Manual MCP config

```json
{
  "mcpServers": {
    "ui-mcp": {
      "command": "npx",
      "args": ["-y", "ui-mcp"]
    }
  }
}
```

## Environment

| Variable | Default | Description |
|----------|---------|-------------|
| `UI_MCP_PORT` | `3847` | Preferred backend port |

## When should agents render?

There is no universal "after final answer" lifecycle hook across MCP clients. The reliable pattern is project instructions:

1. **`npx ui-mcp init`** — writes AGENTS.md / CLAUDE.md with a **render-by-default** policy
2. **Cursor rules / project instructions** — reinforce the behavior

Agents should call `render_ui` for most answers — especially numbers, measurements, comparisons, architecture, and workflows. Skip only for truly single-value replies (e.g. a port number) or when the user asks for text only. Re-run `npx ui-mcp init` to update an existing project's snippet in place.

## Development

```bash
npm install
npm run build
node dist/bin/ui-mcp.js init
```

## License

MIT