Give agents the Lumen contract.
A Model Context Protocol server that gives AI agents structured access to Lumen web and native contracts, platform usage, recipes, design tokens, resources, and generation rules.
lumen_list_componentsDiscover primitives
lumen_get_native_componentNative contracts
lumen_get_rulesStay on-system
- Tools
- 12
- Resources
- 10
- Web components
- 161
- Native components
- 79
What agents can do
Focused MCP tools
Every tool returns readable text plus validated structured content, grounded in the same catalog, docs, web and native source, tokens, and rules the packages ship.
lumen_list_componentsList every component with its framework availability and recipe membership. Filter by framework, recipe, or a name query.
lumen_get_componentReturn framework-specific imports, styles, props or attributes, examples, accessibility behavior, events, and optional source.
lumen_list_native_componentsList native components with React Native, SwiftUI, and Compose availability, accessibility, category, and contract tier.
lumen_get_native_componentReturn native install and setup steps, imports, API rows, examples, accessibility guidance, and optional adapter source.
lumen_get_recipeReturn a recipe’s purpose, categories, components, files, and framework-specific install command.
lumen_searchRank natural-language matches across web or native platform contracts, recipes, tokens, and rules.
lumen_get_metaReturn the schema version, package versions, component count, and deterministic catalog hash.
lumen_get_catalog_manifestReturn stable fingerprints for every web component, native component, and recipe.
lumen_diff_catalogCompare a retained manifest with the current catalog and identify exactly which entries changed.
lumen_diagnoseVerify snapshot integrity and report web framework plus native platform coverage.
lumen_get_tokensReturn semantic token names, base color values, glass tokens, and the theme attribute for generated code.
lumen_get_rulesReturn the Lumen agent rules (llms.txt) to read before producing Lumen code.
Connect a client
Run with npx over stdio or HTTP
The server ships a self-contained snapshot of the catalog, so no repository checkout is required. With Node.js 20.20 or newer, point any MCP client atnpx -y @santi020k/lumen-mcp.
[mcp_servers.lumen]
enabled = true
command = "npx"
args = ["-y", "@santi020k/lumen-mcp"]
startup_timeout_sec = 10.0
tool_timeout_sec = 30.0Or run codex mcp add lumen -- npx -y @santi020k/lumen-mcp.
{
"mcpServers": {
"lumen": {
"command": "npx",
"args": ["-y", "@santi020k/lumen-mcp"]
}
}
}{
"mcpServers": {
"lumen": {
"command": "npx",
"args": ["-y", "@santi020k/lumen-mcp"]
}
}
}{
"name": "lumen",
"transport": "stdio",
"command": "npx",
"args": ["-y", "@santi020k/lumen-mcp"]
}npx -y --package @santi020k/lumen-mcp lumen-mcp-http
# MCP endpoint: http://127.0.0.1:3000/mcp
# Health check: http://127.0.0.1:3000/health
# Default limit: 120 requests per minuteThe transport includes safe response headers and bounded request rates. Public hosting must terminate TLS, set the exact allowed host, and configure authentication if the deployed data requires it.
Skill plus live catalog
Lumen UI 1.0.0 has been submitted to the OpenAI Plugins Directory for Codex and ChatGPT and is currently under review. Until OpenAI approves it and the publisher completes publication, install the portable skill or connect the MCP server directly; the plugin is not yet available from the directory.
plugins/lumen-uiInspect the pluginInstall the skill and live catalog together
Add Lumen's repository marketplace, then install one plugin that bundles the portable workflow skill with the latest published read-only MCP catalog.
/plugin marketplace add santi020k/lumen
/plugin install lumen-ui@lumen/plugin marketplace add santi020k/lumen
/plugin install lumen-ui@lumenStable 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://metaSnapshot provenance, package versions, and deterministic catalog hash.
lumen://catalog-manifestStable web, native, and recipe fingerprints for change detection.
lumen://diagnosticsSnapshot integrity checks and web plus native coverage.
lumen://rulesAgent generation rules as Markdown.
lumen://tokensStructured semantic, color, glass, and theme tokens.
lumen://componentsCompact structured component catalog.
lumen://components/{name}One component’s metadata and default Astro usage.
lumen://native-componentsNative component catalog with platform availability.
lumen://native-components/{name}One native component’s metadata and platform 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 or platform usage contract, and request full source only when the imports, examples, accessibility notes, and API rows are insufficient.
- 01
Verify the snapshot
lumen_get_meta identifies the snapshot and lumen_diagnose verifies web and native coverage.
- 02
Discover
The agent lists web or native components, or searches with a target framework or platform.
- 03
Read target usage
The matching get tool returns installation, setup, imports, API, examples, accessibility, and runtime guidance.
- 04
Compose a recipe
lumen_get_recipe explains multi-component patterns and gives the correct framework install command.
- 05
Track changes
Retain lumen://catalog-manifest and compare it after upgrades to refresh only contracts that changed.
@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