@santi020k/lumen-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Molina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @santi020k/lumen-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for the Lumen
+multi-framework primitive UI system. It gives AI agents structured access to
+components, real framework contracts, recipes, design tokens, accessibility
+behavior, runtime events, and Lumen's generation rules.
+
+The published server ships a self-contained catalog snapshot, so consumers do
+not need a checkout of the Lumen repository.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `lumen_list_components` | List components with descriptions, categories, framework availability, collections, and recipe membership. Filter by `framework`, `recipe`, or natural-language `query`. |
+| `lumen_get_component` | Get a component for `astro`, `react`, or `elements` at `summary`, `usage`, or `source` detail. Usage includes imports, styles, props or attributes, examples, accessibility, guidance, and events. |
+| `lumen_get_recipe` | Get a recipe or component set with its purpose, components, files, categories, and framework-specific install command. |
+| `lumen_search` | Rank natural-language matches across component descriptions, curated collections, props, attributes, recipes, tokens, and agent rules. |
+| `lumen_get_tokens` | Return semantic token names, base colors, glass tokens, and the theme attribute. |
+| `lumen_get_rules` | Return the Lumen agent rules from `llms.txt`. |
+
+Every tool returns both readable text and validated `structuredContent`.
+
+## Resources
+
+| Resource | Contents |
+| --- | --- |
+| `lumen://rules` | Agent rules as Markdown. |
+| `lumen://tokens` | Structured design tokens. |
+| `lumen://components` | Compact component catalog. |
+| `lumen://components/{name}` | Component metadata and default Astro usage. |
+| `lumen://recipes/{name}` | Recipe metadata and install commands. |
+
+## Install and connect
+
+The stdio command for any MCP client is:
+
+```bash
+npx -y @santi020k/lumen-mcp
+```
+
+### Codex
+
+Register it from the Codex CLI:
+
+```bash
+codex mcp add lumen -- npx -y @santi020k/lumen-mcp
+codex mcp list
+```
+
+Or add a project-scoped `.codex/config.toml`:
+
+```toml
+[mcp_servers.lumen]
+enabled = true
+command = "npx"
+args = ["-y", "@santi020k/lumen-mcp"]
+startup_timeout_sec = 10.0
+tool_timeout_sec = 30.0
+```
+
+Start or resume a Codex task after changing MCP configuration so the new tools
+are loaded.
+
+### Claude Desktop
+
+Add this server to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "lumen": {
+      "command": "npx",
+      "args": ["-y", "@santi020k/lumen-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add this server to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "lumen": {
+      "command": "npx",
+      "args": ["-y", "@santi020k/lumen-mcp"]
+    }
+  }
+}
+```
+
+### Any stdio MCP client
+
+Use the equivalent of this generic configuration:
+
+```json
+{
+  "name": "lumen",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@santi020k/lumen-mcp"]
+}
+```
+
+Client configuration envelopes differ, but the command and arguments remain
+the same.
+
+## Recommended agent workflow
+
+1. Read `lumen://rules`.
+2. Call `lumen_search` with the requested use case and target framework.
+3. Call `lumen_get_component` with `detail: "usage"`.
+4. Inspect a related recipe with `lumen_get_recipe` when the UI needs multiple primitives.
+5. Request `detail: "source"` only when the usage contract is insufficient.
+6. Use `lumen_get_tokens` before adding custom styling.
+
+Example calls:
+
+```json
+{ "name": "lumen_search", "arguments": { "query": "accessible date input", "limit": 5 } }
+```
+
+```json
+{
+  "name": "lumen_get_component",
+  "arguments": {
+    "name": "DateRangePicker",
+    "framework": "react",
+    "detail": "usage"
+  }
+}
+```
+
+```json
+{
+  "name": "lumen_get_recipe",
+  "arguments": {
+    "name": "advanced-fields",
+    "framework": "react"
+  }
+}
+```
+
+## Local repository usage
+
+This repository includes a project-scoped Codex configuration that launches:
+
+```bash
+pnpm --filter @santi020k/lumen-mcp local
+```
+
+The local launcher builds the MCP package when `dist` is missing or older than
+the TypeScript source, then starts the server without writing build logs to the
+MCP stdout channel.
+
+Useful development commands:
+
+```bash
+pnpm --filter @santi020k/lumen-mcp generate
+pnpm --filter @santi020k/lumen-mcp build
+pnpm --filter @santi020k/lumen-mcp test
+pnpm --filter @santi020k/lumen-mcp test:coverage
+```
+
+## Programmatic use
+
+The reusable handlers return readable text plus typed data:
+
+```ts
+import {
+  getComponent,
+  getRecipe,
+  search
+} from '@santi020k/lumen-mcp/tools'
+
+const matches = search({ limit: 5, query: 'date input' }).data.results
+
+const component = getComponent({
+  detail: 'usage',
+  framework: 'react',
+  name: 'DateRangePicker'
+}).data.component
+
+const recipe = getRecipe({
+  framework: 'react',
+  name: 'advanced-fields'
+}).data.recipe
+```
+
+You can also embed the server:
+
+```ts
+import { createLumenServer } from '@santi020k/lumen-mcp'
+
+const server = createLumenServer()
+```
+
+## Snapshot generation
+
+`scripts/generate-data.mjs` builds `data/lumen-data.json` from:
+
+- The shared component catalog and registry metadata.
+- Astro and React component declarations.
+- The Web Component definition registry.
+- Documentation examples, API rows, guidance, keyboard interactions, and runtime events.
+- Design tokens, recipes, `docs/ai-usage.md`, and `llms.txt`.
+
+The output is deterministic and carries the package version used by the MCP
+initialization response.
+
+## License
+
+MIT © Santiago Molina

package/bin/lumen-mcp-local.mjs

@@ -0,0 +1,56 @@
+
+import { spawnSync } from 'node:child_process'
+import { access, readdir as readDirectory, stat as getStat } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const repoRoot = resolve(packageRoot, '../..')
+const distEntry = join(packageRoot, 'dist/index.js')
+
+const filesIn = async (directory) => {
+  const entries = await readDirectory(directory, { withFileTypes: true })
+
+  const nested = await Promise.all(entries.map((entry) => {
+    const path = join(directory, entry.name)
+
+    return entry.isDirectory() ? filesIn(path) : [path]
+  }))
+
+  return nested.flat()
+}
+
+const needsBuild = async () => {
+  try {
+    await access(distEntry)
+  } catch {
+    return true
+  }
+
+  const outputTime = (await getStat(distEntry)).mtimeMs
+  const sourceFiles = await filesIn(join(packageRoot, 'src'))
+  const sourceTimes = await Promise.all(sourceFiles.map(async (path) => (await getStat(path)).mtimeMs))
+
+  return sourceTimes.some((modifiedTime) => modifiedTime > outputTime)
+}
+
+if (await needsBuild()) {
+  const build = spawnSync(
+    'pnpm',
+    ['--filter', '@santi020k/lumen-mcp', 'build'],
+    {
+      cwd: repoRoot,
+      stdio: ['ignore', process.stderr, process.stderr]
+    }
+  )
+
+  if (build.status !== 0) {
+    process.exitCode = build.status ?? 1
+  }
+}
+
+if (!process.exitCode) {
+  const { startLumenMcp } = await import('../dist/index.js')
+
+  await startLumenMcp()
+}

package/bin/lumen-mcp.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { startLumenMcp } from '../dist/index.js'
+
+startLumenMcp().catch((error) => {
+  process.stderr.write('lumen-mcp failed to start: ' + String(error) + '\n')
+
+  process.exitCode = 1
+})