@santi020k/lumen-mcp 1.6.0 → 1.7.0

package/README.md

@@ -131,11 +131,37 @@ 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
+`http://127.0.0.1:3000/mcp`, a liveness check at `/health`, and a catalog readiness check at
+`/ready`. Readiness returns the loaded catalog hash and server version, or a safe 503 response when
+the catalog cannot initialize. Configure the transport 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.
+`LUMEN_MCP_ALLOWED_HOSTS`. The transport applies safe response headers and a
+fixed-window request limit of 120 requests per minute by default. Malformed request bodies and
+initialization failures return bounded JSON errors without stack traces or local paths.
+
+Public deployments can also set:
+
+- `LUMEN_MCP_OPENAI_CHALLENGE` to serve the exact single-line verification token at
+  `/.well-known/openai-apps-challenge`.
+- `LUMEN_MCP_RATE_LIMIT_MAX` and `LUMEN_MCP_RATE_LIMIT_WINDOW_MS` to tune positive integer rate
+  limits.
+- `LUMEN_MCP_TRUST_PROXY=true` only behind a controlled proxy that sanitizes forwarded headers.
+
+The process listens over HTTP. Public hosting must terminate TLS, configure the exact allowed host,
+and add authentication when the deployed data or operating model requires it. The public Lumen
+catalog does not require user authentication.
+
+## AI plugin package
+
+The repository includes a submission-ready plugin package in [`plugins/lumen-ui`](../../plugins/lumen-ui).
+It combines the portable `lumen-ui` skill with this MCP server for Codex, ChatGPT, and Claude Code.
+The public OpenAI Plugins Directory submission uses a hosted Streamable HTTP endpoint; see the
+[submission checklist](../../docs/openai-plugin-submission.md) for deployment requirements, listing
+copy, annotation justifications, and reviewer test cases.
+
+Claude Code uses the package's stdio configuration and the repository marketplace in
+[`.claude-plugin/marketplace.json`](../../.claude-plugin/marketplace.json). See the
+[Claude Code plugin guide](../../docs/claude-code-plugin.md) for installation and validation.
 
 ## Recommended agent workflow
 

package/bin/lumen-mcp-http.mjs

@@ -4,13 +4,42 @@ 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 parsePositiveInteger = (value, fallback, name) => {
+  const parsed = Number.parseInt(value ?? String(fallback), 10)
+
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer.`)
+  }
+
+  return parsed
+}
+
 const allowedHosts = process.env.LUMEN_MCP_ALLOWED_HOSTS
   ?.split(',')
   .map(value => value.trim())
   .filter(Boolean)
 
 try {
-  const { url } = await startLumenMcpHttp({ allowedHosts, host, port })
+  const maxRequests = parsePositiveInteger(
+    process.env.LUMEN_MCP_RATE_LIMIT_MAX,
+    120,
+    'LUMEN_MCP_RATE_LIMIT_MAX'
+  )
+
+  const windowMs = parsePositiveInteger(
+    process.env.LUMEN_MCP_RATE_LIMIT_WINDOW_MS,
+    60_000,
+    'LUMEN_MCP_RATE_LIMIT_WINDOW_MS'
+  )
+
+  const { url } = await startLumenMcpHttp({
+    allowedHosts,
+    host,
+    openAiChallenge: process.env.LUMEN_MCP_OPENAI_CHALLENGE,
+    port,
+    rateLimit: { maxRequests, windowMs },
+    trustProxy: process.env.LUMEN_MCP_TRUST_PROXY === 'true'
+  })
 
   process.stderr.write(`lumen-mcp listening at ${url.href}\n`)
 } catch (error) {