121
GitHub
Documentation
AI integration

Give agents the Lumen contract.

A Model Context Protocol server that gives AI agents structured access to Lumen component contracts, framework usage, recipes, design tokens, resources, and generation rules.

View on npmRead the README

lumen_list_componentsDiscover primitives

lumen_get_componentFramework contracts

lumen_get_rulesStay on-system

Tools
6
Resources
5
Components
121

What agents can do

Six focused tools

Every tool returns readable text plus validated structured content, grounded in the same catalog, docs, framework source, tokens, and rules the packages ship.

lumen_list_components

List every component with its framework availability and recipe membership. Filter by framework, recipe, or a name query.

lumen_get_component

Return framework-specific imports, styles, props or attributes, examples, accessibility behavior, events, and optional source.

lumen_get_recipe

Return a recipe’s purpose, categories, components, files, and framework-specific install command.

lumen_search

Rank natural-language matches across descriptions, collections, props, attributes, recipes, tokens, and rules.

lumen_get_tokens

Return semantic token names, base color values, glass tokens, and the theme attribute for generated code.

lumen_get_rules

Return the Lumen agent rules (llms.txt) to read before producing Lumen code.

Connect a client

Run over stdio with npx

The server ships a self-contained snapshot of the catalog, so no repository checkout is required. Point any MCP client at npx -y @santi020k/lumen-mcp.

Codex.codex/config.toml
[mcp_servers.lumen]
enabled = true
command = "npx"
args = ["-y", "@santi020k/lumen-mcp"]
startup_timeout_sec = 10.0
tool_timeout_sec = 30.0

Or run codex mcp add lumen -- npx -y @santi020k/lumen-mcp.

Claude Desktopclaude_desktop_config.json
{
  "mcpServers": {
    "lumen": {
      "command": "npx",
      "args": ["-y", "@santi020k/lumen-mcp"]
    }
  }
}
Cursor.cursor/mcp.json
{
  "mcpServers": {
    "lumen": {
      "command": "npx",
      "args": ["-y", "@santi020k/lumen-mcp"]
    }
  }
}
Any stdio clientgeneric shape
{
  "name": "lumen",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@santi020k/lumen-mcp"]
}

Stable context

Browsable MCP resources

Clients can read or cache stable catalog context without calling a tool. Component and recipe templates are enumerable and support name completion.

lumen://rules

Agent generation rules as Markdown.

lumen://tokens

Structured semantic, color, glass, and theme tokens.

lumen://components

Compact structured component catalog.

lumen://components/{name}

One component’s metadata and default Astro usage.

lumen://recipes/{name}

Recipe metadata and framework install commands.

How agents use it

Discover, read, and stay on-system

Start compact, read the target framework’s usage contract, and request full source only when the imports, examples, accessibility notes, and API rows are insufficient.

  1. 01

    Discover

    The agent calls lumen_list_components or lumen_search to find the right primitive for the task.

  2. 02

    Read framework usage

    lumen_get_component returns imports, styles, examples, props or attributes, accessibility behavior, and events for Astro, React, or Elements.

  3. 03

    Compose a recipe

    lumen_get_recipe explains multi-component patterns and gives the correct framework install command.

  4. 04

    Follow the system

    Structured tokens, resources, and rules keep generated code on Lumen’s semantic contract.

npm package

@santi020k/lumen-mcp

The deterministic snapshot is generated from the component registry, documentation API rows and examples, Astro and React declarations, Web Component definitions, tokens, recipes, accessibility interactions, runtime events, and llms.txt.

npx -y @santi020k/lumen-mcpOpen on npm