@santi020k/lumen-mcp 0.1.0 → 0.3.0

package/README.md

@@ -15,7 +15,11 @@ not need a checkout of the Lumen repository.
 | `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_search` | Rank tolerant natural-language matches across component descriptions, curated collections, framework contracts, props, attributes, recipes, tokens, and agent rules. Optionally filter component contracts by framework. |
+| `lumen_get_meta` | Return deterministic snapshot provenance, package versions, schema version, component count, and catalog hash. |
+| `lumen_get_catalog_manifest` | Return stable per-component and per-recipe fingerprints that clients can retain between upgrades. |
+| `lumen_diff_catalog` | Compare a retained manifest with the current snapshot and report added, changed, removed, and unchanged entries. |
+| `lumen_diagnose` | Verify snapshot integrity and report framework coverage when testing a connection. |
 | `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`. |
 
@@ -25,6 +29,9 @@ Every tool returns both readable text and validated `structuredContent`.
 
 | Resource | Contents |
 | --- | --- |
+| `lumen://meta` | Snapshot provenance, package versions, and deterministic catalog hash. |
+| `lumen://catalog-manifest` | Stable component and recipe fingerprints for change detection. |
+| `lumen://diagnostics` | Snapshot integrity results and framework coverage. |
 | `lumen://rules` | Agent rules as Markdown. |
 | `lumen://tokens` | Structured design tokens. |
 | `lumen://components` | Compact component catalog. |
@@ -39,6 +46,8 @@ The stdio command for any MCP client is:
 npx -y @santi020k/lumen-mcp
 ```
 
+Node.js 20.20 or newer is supported.
+
 ### Codex
 
 Register it from the Codex CLI:
@@ -108,19 +117,38 @@ Use the equivalent of this generic configuration:
 Client configuration envelopes differ, but the command and arguments remain
 the same.
 
+### Streamable HTTP
+
+For local network clients or a self-hosted deployment, start the included
+Streamable HTTP transport:
+
+```bash
+npx -y --package @santi020k/lumen-mcp lumen-mcp-http
+```
+
+It binds to `127.0.0.1:3000` by default and exposes MCP at
+`http://127.0.0.1:3000/mcp` plus a health check at `/health`. Configure it with
+`LUMEN_MCP_HOST`, `LUMEN_MCP_PORT`, and a comma-separated
+`LUMEN_MCP_ALLOWED_HOSTS`. Binding to a public interface requires the
+deployment's authentication, TLS, rate limiting, and host allowlist; the
+package does not provide those infrastructure controls.
+
 ## 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.
+1. Read `lumen://meta` and call `lumen_diagnose` to identify and verify the bundled snapshot.
+2. Read `lumen://rules`.
+3. Call `lumen_search` with the requested use case and target framework.
+4. Call `lumen_get_component` with `detail: "usage"`.
+5. Follow the returned framework behavior section: mount Astro `UIPrimitives` once, use the named React hook/controller, or register custom elements once.
+6. Inspect a related recipe with `lumen_get_recipe` when the UI needs multiple primitives.
+7. Request `detail: "source"` only when the usage contract is insufficient.
+8. Use `lumen_get_tokens` before adding custom styling.
+9. Cache `lumen://catalog-manifest`; after an upgrade, pass it to `lumen_diff_catalog` to refresh only changed contracts.
 
 Example calls:
 
 ```json
-{ "name": "lumen_search", "arguments": { "query": "accessible date input", "limit": 5 } }
+{ "name": "lumen_search", "arguments": { "query": "accessible date input", "framework": "react", "limit": 5 } }
 ```
 
 ```json
@@ -163,6 +191,9 @@ 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
+pnpm --filter @santi020k/lumen-mcp check:snapshot
+pnpm --filter @santi020k/lumen-mcp eval
+pnpm --filter @santi020k/lumen-mcp smoke:package
 ```
 
 ## Programmatic use
@@ -172,11 +203,13 @@ The reusable handlers return readable text plus typed data:
 ```ts
 import {
   getComponent,
+  getMeta,
   getRecipe,
   search
 } from '@santi020k/lumen-mcp/tools'
 
 const matches = search({ limit: 5, query: 'date input' }).data.results
+const snapshot = getMeta().data.meta
 
 const component = getComponent({
   detail: 'usage',
@@ -209,7 +242,18 @@ const server = createLumenServer()
 - 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.
+initialization response. It also includes every framework package version, a
+schema version, and a SHA-256 catalog hash. CI regenerates the snapshot and
+fails when the committed file is stale. The release group versions the MCP
+alongside Lumen framework packages, and the package smoke test installs the
+packed artifact into a temporary consumer project before making a real stdio
+handshake.
+
+The evaluation gate also runs a curated natural-language search benchmark,
+calls every available component/framework contract through MCP, parses all
+Astro and custom-element examples, and type-checks every React example against
+the built React package. A generated example that is syntactically valid but
+uses an unsupported React prop therefore fails before release.
 
 ## License
 

package/bin/lumen-mcp-http.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { startLumenMcpHttp } from '../dist/index.js'
+
+const port = Number.parseInt(process.env.LUMEN_MCP_PORT ?? '3000', 10)
+const host = process.env.LUMEN_MCP_HOST ?? '127.0.0.1'
+
+const allowedHosts = process.env.LUMEN_MCP_ALLOWED_HOSTS
+  ?.split(',')
+  .map((value) => value.trim())
+  .filter(Boolean)
+
+try {
+  const { url } = await startLumenMcpHttp({ allowedHosts, host, port })
+
+  process.stderr.write(`lumen-mcp listening at ${url.href}\n`)
+} catch (error) {
+  process.stderr.write('lumen-mcp HTTP transport failed to start: ' + String(error) + '\n')
+
+  process.exitCode = 1
+}

package/bin/lumen-mcp-local.mjs

@@ -1,6 +1,4 @@
-
 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'
 
@@ -9,7 +7,8 @@ const repoRoot = resolve(packageRoot, '../..')
 const distEntry = join(packageRoot, 'dist/index.js')
 
 const filesIn = async (directory) => {
-  const entries = await readDirectory(directory, { withFileTypes: true })
+  const fs = await import('node:fs/promises')
+  const entries = await fs.readdir(directory, { withFileTypes: true })
 
   const nested = await Promise.all(entries.map((entry) => {
     const path = join(directory, entry.name)
@@ -21,15 +20,17 @@ const filesIn = async (directory) => {
 }
 
 const needsBuild = async () => {
+  const fs = await import('node:fs/promises')
+
   try {
-    await access(distEntry)
+    await fs.access(distEntry)
   } catch {
     return true
   }
 
-  const outputTime = (await getStat(distEntry)).mtimeMs
+  const outputTime = (await fs.stat(distEntry)).mtimeMs
   const sourceFiles = await filesIn(join(packageRoot, 'src'))
-  const sourceTimes = await Promise.all(sourceFiles.map(async (path) => (await getStat(path)).mtimeMs))
+  const sourceTimes = await Promise.all(sourceFiles.map(async (path) => (await fs.stat(path)).mtimeMs))
 
   return sourceTimes.some((modifiedTime) => modifiedTime > outputTime)
 }