Registry

A registry is a static JSON file that catalogues components so lumeo-cli and the MCP server can install them, search them, and help LLMs author code against them. Lumeo ships one out of the box, but anyone can publish their own so lumeo add and Claude / Cursor work against a third-party library.

Our built-in registry

Lumeo maintains a reference registry for the components in this site. It's the same file lumeo add hits by default, and the same file our MCP server indexes at build time.

Raw JSON: /registry.json
Source on GitHub: src/Lumeo/registry/registry.json

The registry is produced by tools/Lumeo.RegistryGen/ — a small .NET CLI that walks src/Lumeo/UI/ and emits a JSON file. If you want to auto-produce your own registry instead of hand-authoring one, it's a reasonable reference implementation to fork.

Schema reference

The file has two top-level fields and an open-ended map of component entries.

{
  "$schema": "https://lumeo.nativ.sh/registry-schema.json",
  "version": "2.0.0",
  "components": {
    "<slug>": { ... }
  }
}

Top-level fields

Field	Type	Required	Description
$schema	string (URL)	recommended	Pointer to the JSON schema for editor tooling.
version	string (SemVer)	yes	Registry version. Bump on breaking field changes so consumers can guard.
components	object	yes	Map of component slug → entry. The slug is what `lumeo add <slug>` uses.

Per-component entry

Each value in components is a JSON object that looks like this:

{
  "name": "Button",
  "category": "Forms",
  "description": "Versatile button with variants, sizes, icons, loading states.",
  "files": ["UI/Button/Button.razor"],
  "dependencies": ["icon"],
  "cssVars": ["--color-primary", "--color-primary-foreground"],
  "registryUrl": "https://example.com/registry/button.json"
}

Field	Type	Required	Description
name	string	yes	PascalCase component name (used in docs and code examples).
category	string	yes	Grouping for `lumeo list` and the MCP catalog (Forms, Layout, Feedback, etc.). Pick from a short controlled set or invent your own.
description	string	yes	One-line blurb shown by `lumeo list` and in MCP search results. Keep it under 120 chars.
files	string[]	yes	Relative paths to every file needed for this component. `lumeo add` fetches each one.
dependencies	string[]	no	Slugs of other components this one needs. `lumeo add` resolves them recursively.
cssVars	string[]	no	Lumeo theme tokens the component reads. Helps `lumeo doctor` check the consumer's theme.
registryUrl	string (URL)	no	Per-component pointer useful when you split entries across multiple JSON files.
requiresRuntime	bool	no	New: set `true` if this component depends on Lumeo's runtime (services, interop, source generators). `lumeo-cli` will warn when installing without the `Lumeo` NuGet. Defaults to false.

Tip

Keep description under 120 chars — LLMs and lumeo list truncate longer blurbs.

How `lumeo-cli` consumes it

The CLI treats your registry URL as the single source of truth. The install flow:

lumeo init saves registry: "<url>" in lumeo.json.
lumeo add <slug> fetches registry.json, finds the slug's entry, downloads each files[] entry (base URL derived from the registry URL — see next bullet), recursively installs dependencies[], and rewrites @namespace Lumeo to the consumer's namespace.
File URLs: by convention, lumeo-cli takes the registry URL, strips the filename, and joins each relative files[] path against that base.

https://example.com/lumeo/registry.json  +  UI/Button/Button.razor
  →  https://example.com/lumeo/UI/Button/Button.razor

Self-hosters

Serve your raw .razor files from the same origin as the registry JSON. Relative paths won't work across origins.

How the MCP server consumes it

tools/lumeo-mcp/ reads the registry at build time (via its prebuild script) and exposes every entry through lumeo_list_components / lumeo_get_component / lumeo_search plus the lumeo://component/{name} resource.
For third-party registries you want exposed to LLMs, fork tools/lumeo-mcp/, update the sync-registry.mjs URL, and publish your own npm package — the protocol stays the same.

Build your own — 5-step quickstart

The registry format is a contract, not a framework — any static host will do.

1. Create your component library

Author a normal Blazor class library that targets net10.0 with the Razor SDK. Each component is a regular .razor file — no special conventions required.

2. Author `registry.json`

Hand-write it for small libraries, or generate it. For a reference generator, see tools/Lumeo.RegistryGen/Program.cs — it scans a components directory and emits a schema-compliant registry.

3. Host the registry + raw files

Any static host works: GitHub Pages, Cloudflare Pages, Netlify, a CDN, your own bucket. Make sure CORS allows fetches from arbitrary origins so lumeo-cli can hit it cross-origin if needed.

4. Test with `lumeo-cli`

Point a consumer project at your registry and run lumeo add my-slug. Verify files land with the right namespace and that dependencies resolve recursively.

lumeo init --registry https://example.com/lumeo/registry.json
lumeo add my-slug

5. (Optional) Publish your own MCP server

Fork tools/lumeo-mcp/, point its sync-registry.mjs at your hosted JSON, build, and publish to npm. Claude / Cursor users can then install your server and get completions, docs, and examples for your components.

JSON Schema

The registry at /registry.json is $schema-compatible with https://lumeo.nativ.sh/registry-schema.json. Hosting that URL is planned; for now, the schema lives alongside the generator in tools/Lumeo.RegistryGen/ in the repo, so you can copy it locally and validate with any standard JSON Schema tool.