# MCP Server

Source: https://lumeo.nativ.sh/docs/mcp

# MCP Server

Give Claude, Cursor, and Copilot first-class knowledge of the Lumeo API — so LLM-generated markup actually compiles.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard (from Anthropic) that lets LLM clients talk to external tool servers over a simple JSON-RPC stream. Any MCP-aware client — Claude Desktop, Cursor, GitHub Copilot, Zed, Continue — can spawn a local MCP server and call its tools and read its resources.

Lumeo ships an MCP server (`@lumeo-ui/mcp-server`) that exposes the component catalog. Once connected, your LLM can look up real parameters, slot names, and working examples before it writes a single line of Razor — so prompts like "build a sign-in page with Lumeo" produce markup that uses the correct `@bind-Value` syntax, the right variant enums, and matching slot names. No more hallucinated components.

## What it exposes

The server covers all 154 components from Lumeo's [component registry](docs/registry). The top ~35 most-used components ship with rich, hand-curated schemas (parameters, slots, ready-to-use Razor examples); the rest are discoverable and returned with category, description, files, dependencies, and CSS variables plus a link back to the docs site for full reference.

### Tools

-   `lumeo_list_components` — list all 154 components, optionally filtered by category or free-text query.
-   `lumeo_get_component` — rich schema for curated components (params, slots, Razor example, CSS variables); thin payload with a docs link for the rest.
-   `lumeo_search` — fuzzy search across all 154 component names, categories and descriptions.

### Resources

-   `lumeo://component/{Name}` — markdown reference for a single component (readable by the LLM exactly like a doc page).
-   `lumeo://category/{Name}` — overview of all components in a category (Forms, Layout, Overlay, Data, Navigation, AI, Motion).

## Install

The easiest way is to use the published npm package — no clone, no build:

npm install -g @lumeo-ui/mcp-server

Or invoke it on demand without a global install (recommended for Claude Desktop):

npx -y @lumeo-ui/mcp-server

Prefer to build from source? The server lives in the Lumeo repo under `tools/lumeo-mcp`:

cd tools/lumeo-mcp npm install npm run build

This produces `dist/index.js`, a self-contained Node ESM entrypoint. No persistent process — your MCP client spawns it on demand.

## Configure your client

### Claude Desktop

Open Settings → Developer → Edit Config and merge this into `claude_desktop_config.json` (recommended — uses the published npm package via `npx`):

{ "mcpServers": { "lumeo": { "command": "npx", "args": \["-y", "@lumeo-ui/mcp-server"\] } } }

Or, if you built from source, point directly at `dist/index.js`:

{ "mcpServers": { "lumeo": { "command": "node", "args": \["C:/path/to/Lumeo/tools/lumeo-mcp/dist/index.js"\] } } }

Restart Claude Desktop. The Lumeo server should appear under the connectors panel with its tools and resources.

### Cursor

Add to your project's `.cursor/mcp.json`:

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

### VS Code (GitHub Copilot)

Add to your workspace's `.vscode/mcp.json`:

{ "servers": { "lumeo": { "type": "stdio", "command": "node", "args": \["/absolute/path/to/lumeo-mcp/dist/index.js"\] } } }

## Try it

After connecting, ask your LLM:

"Build me a dashboard with three KpiCards using Lumeo — revenue, active users, and churn. Use NumberTicker for the values and wrap them in a Bento grid."

Under the hood the model calls `lumeo_search` for "card", "ticker", "bento", then `lumeo_get_component` on each match — and emits Razor that uses the correct `@bind-Value` pattern, the right variant enums (`Button.ButtonVariant.Outline`, not invented ones), and matching slot names (`LeftIcon` / `IconContent`) as they appear in the library.

Other good prompts to try:

-   "Sign-in page: email, password, remember-me switch, submit with validation."
-   "Users page with a DataGrid (sortable, paginated) and a Dialog for editing."
-   "Chat UI using AgentMessage, StreamingText, and PromptInput."

## Pair it with the Lumeo agent skill

The MCP server exposes the data; the Lumeo agent skill teaches the LLM how to drive it. The skill ships in this repo at `skills/lumeo/` and is a portable [agent-skill bundle](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) that works with Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Antigravity and 50+ other agents.

Install it with the [Vercel Labs skills CLI](https://github.com/vercel-labs/skills) (also discoverable at [skills.sh](https://skills.sh)):

```
npx skills add github.com/Brain2k-0005/Lumeo/skills/lumeo
```

Once installed the skill auto-activates whenever you mention Lumeo or one of its components — it primes the agent with the conventions (theme tokens, no `dark:` prefixes, `Blazicon` icons, `ComponentInteropService` for JS interop, portal-component `<body>` classes…) and the MCP workflow (`search → get_component → write → validate_markup`). A GitHub Actions workflow keeps the skill's offline catalog in lockstep with the MCP API on every push so it never drifts.

## Scope

The v2.0 catalog covers all 128 components across Forms, Layout, Overlay, Data Display, Navigation, Feedback, Charts, Dashboard, AI, Motion, Drag & Drop, Typography and Utility. Rich schemas exist for the top ~35; the rest resolve to a thin payload (files, dependencies, CSS variables) with a link to the component's docs page. Rich coverage grows as more components are curated in `src/components.ts`. The full machine-readable catalog lives at `src/Lumeo/registry/registry.json` — see the [Registry](docs/registry) page.