@santi020k/lumen-mcp 0.1.0 → 0.3.0

package/dist/data.d.ts

@@ -1,3 +1,7 @@
+export interface LumenCatalogManifest {
+    components: Record<string, string>;
+    recipes: Record<string, string>;
+}
 export interface LumenComponentSnapshot {
     apiReference: {
         attribute: string;
@@ -46,16 +50,20 @@ export interface LumenComponentSnapshot {
     }[];
 }
 export interface LumenData {
+    catalogManifest: LumenCatalogManifest;
     components: LumenComponentSnapshot[];
     docs: {
         aiUsage: string;
         readme: string;
     };
     meta: {
+        catalogHash: string;
         componentCount: number;
         packages: string[];
+        packageVersions: Record<string, string>;
         registryName: string;
         registryVersion: number;
+        schemaVersion: number;
         serverVersion: string;
     };
     recipes: LumenRecipeSnapshot[];
@@ -71,6 +79,24 @@ export type LumenFramework = 'astro' | 'elements' | 'react';
 export interface LumenFrameworkSnapshot {
     attributes?: string[];
     available: boolean;
+    behavior?: {
+        controller?: {
+            defaultValue: string;
+            description: string;
+            name: string;
+            type: string;
+        }[];
+        description?: string;
+        hook?: string;
+        mode: 'adapter' | 'built-in' | 'hook' | 'registration' | 'runtime';
+        options?: {
+            defaultValue: string;
+            description: string;
+            name: string;
+            type: string;
+        }[];
+        setup: string;
+    };
     example: string;
     importStatement: string;
     language: 'astro' | 'html' | 'tsx';

package/dist/data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"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"}

package/dist/data.js

@@ -1,10 +1,11 @@
-import { readFileSync as readFsFile } from 'node:fs';
+import * as fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 const dataUrl = new URL('../data/lumen-data.json', import.meta.url);
 let cached;
 export const loadLumenData = () => {
     if (cached)
         return cached;
+    const readFsFile = Reflect.get(fs, 'readFileSync');
     const raw = readFsFile(fileURLToPath(dataUrl), 'utf8');
     cached = JSON.parse(raw);
     return cached;

package/dist/index.d.ts

@@ -1,7 +1,21 @@
+import type { Server as HttpServer } from 'node:http';
 export { loadLumenData } from './data.js';
 export type { LumenData } from './data.js';
 export { createLumenServer } from './server.js';
 export * from './tools.js';
 /** Start the Lumen MCP server over stdio. Called by the `lumen-mcp` bin. */
 export declare const startLumenMcp: () => Promise<void>;
+export interface LumenMcpHttpOptions {
+    allowedHosts?: string[] | undefined;
+    endpoint?: string | undefined;
+    host?: string | undefined;
+    port?: number | undefined;
+}
+export interface LumenMcpHttpServer {
+    close: () => Promise<void>;
+    httpServer: HttpServer;
+    url: URL;
+}
+/** Start a self-hostable Streamable HTTP transport. Defaults to loopback for safety. */
+export declare const startLumenMcpHttp: (options?: LumenMcpHttpOptions) => Promise<LumenMcpHttpServer>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,cAAc,YAAY,CAAA;AAE1B,4EAA4E;AAC5E,eAAO,MAAM,aAAa,QAAa,OAAO,CAAC,IAAI,CAKlD,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAA;AAYrD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,cAAc,YAAY,CAAA;AAE1B,4EAA4E;AAC5E,eAAO,MAAM,aAAa,QAAa,OAAO,CAAC,IAAI,CAKlD,CAAA;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,UAAU,EAAE,UAAU,CAAA;IACtB,GAAG,EAAE,GAAG,CAAA;CACT;AAoDD,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,GAC5B,UAAS,mBAAwB,KAChC,OAAO,CAAC,kBAAkB,CA+F5B,CAAA"}

package/dist/index.js

@@ -1,4 +1,6 @@
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 import { createLumenServer } from './server.js';
 export { loadLumenData } from './data.js';
 export { createLumenServer } from './server.js';
@@ -9,3 +11,115 @@ export const startLumenMcp = async () => {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 };
+const toWebRequest = (request, host, options) => {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+            if (item !== undefined)
+                headers.append(name, item);
+        }
+    }
+    const hostHeader = request.headers.host ?? `${host}:${options.port ?? 3000}`;
+    const method = request.method;
+    return new Request(`http://${hostHeader}${request.url}`, {
+        headers,
+        method,
+        ...(['GET', 'HEAD'].includes(method) ? {} : { body: JSON.stringify(request.body) })
+    });
+};
+const streamResponse = async (webResponse, response) => {
+    response.statusCode = webResponse.status;
+    for (const [name, value] of webResponse.headers.entries())
+        response.setHeader(name, value);
+    if (!webResponse.body) {
+        response.end();
+        return;
+    }
+    const reader = webResponse.body.getReader();
+    response.once('close', () => {
+        reader.cancel().catch(() => { });
+    });
+    while (!response.destroyed) {
+        const chunk = await reader.read();
+        if (chunk.done)
+            break;
+        response.write(Buffer.from(chunk.value));
+    }
+    if (!response.writableEnded)
+        response.end();
+};
+/** Start a self-hostable Streamable HTTP transport. Defaults to loopback for safety. */
+export const startLumenMcpHttp = async (options = {}) => {
+    const host = options.host ?? '127.0.0.1';
+    const endpoint = options.endpoint ?? '/mcp';
+    const app = createMcpExpressApp({
+        host,
+        ...(options.allowedHosts ? { allowedHosts: options.allowedHosts } : {})
+    });
+    const activeServers = new Set();
+    app.all(endpoint, async (request, response) => {
+        const mcpServer = createLumenServer();
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            enableJsonResponse: true
+        });
+        activeServers.add(mcpServer);
+        try {
+            await mcpServer.connect(transport);
+            const webRequest = toWebRequest(request, host, options);
+            const webResponse = await transport.handleRequest(webRequest, {
+                parsedBody: request.body
+            });
+            await streamResponse(webResponse, response);
+        }
+        catch (error) {
+            if (response.headersSent)
+                throw error;
+            response.statusCode = 500;
+            response.setHeader('content-type', 'application/json');
+            response.end(JSON.stringify({
+                error: 'Lumen MCP HTTP request failed.',
+                message: String(error)
+            }));
+        }
+        finally {
+            if (mcpServer.isConnected())
+                await mcpServer.close();
+            activeServers.delete(mcpServer);
+        }
+    });
+    app.get('/health', (_request, response) => {
+        response.setHeader('content-type', 'application/json');
+        response.end(JSON.stringify({ status: 'ok' }));
+    });
+    const httpServer = await new Promise((resolve, reject) => {
+        const listener = app.listen(options.port ?? 3000, host);
+        listener.once('error', reject);
+        listener.once('listening', () => {
+            resolve(listener);
+        });
+    });
+    const address = httpServer.address();
+    if (!address || typeof address === 'string') {
+        httpServer.close();
+        throw new Error('Could not resolve the Lumen MCP HTTP listening address.');
+    }
+    const url = new URL(`http://${host.includes(':') ? `[${host}]` : host}:${address.port}${endpoint}`);
+    return {
+        close: async () => {
+            await Promise.all([...activeServers].map(async (server) => {
+                if (server.isConnected())
+                    await server.close();
+            }));
+            await new Promise((resolve, reject) => {
+                httpServer.close((error) => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                });
+            });
+        },
+        httpServer,
+        url
+    };
+};

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAA;AAmGrF,eAAO,MAAM,iBAAiB,QAAO,SAwNpC,CAAA"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAA;AA2JrF,eAAO,MAAM,iBAAiB,QAAO,SAgTpC,CAAA"}

package/dist/server.js

@@ -1,7 +1,7 @@
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import * as z from 'zod';
 import { loadLumenData } from './data.js';
-import { getComponent, getRecipe, getRules, getTokens, listComponents, search } from './tools.js';
+import { diagnose, diffCatalog, getCatalogManifest, getComponent, getMeta, getRecipe, getRules, getTokens, listComponents, search } from './tools.js';
 const readOnlyAnnotations = {
     idempotentHint: true,
     openWorldHint: false,
@@ -55,6 +55,52 @@ const tokensOutputSchema = z.strictObject({
 const rulesOutputSchema = z.strictObject({
     rules: z.string().trim()
 });
+const metaOutputSchema = z.strictObject({
+    meta: z.strictObject({
+        catalogHash: z.string().trim().regex(/^[a-f0-9]{64}$/),
+        componentCount: z.int().min(0),
+        packages: z.array(z.string().trim()),
+        packageVersions: z.record(z.string(), z.string().trim()),
+        registryName: z.string().trim(),
+        registryVersion: z.int().min(1),
+        schemaVersion: z.int().min(1),
+        serverVersion: z.string().trim()
+    })
+});
+const catalogManifestSchema = z.strictObject({
+    components: z.record(z.string(), z.string().trim().regex(/^[a-f0-9]{64}$/)),
+    recipes: z.record(z.string(), z.string().trim().regex(/^[a-f0-9]{64}$/))
+});
+const catalogChangesSchema = z.strictObject({
+    added: z.array(z.string().trim()),
+    changed: z.array(z.string().trim()),
+    removed: z.array(z.string().trim()),
+    unchanged: z.array(z.string().trim())
+});
+const catalogManifestOutputSchema = z.strictObject({
+    catalogHash: z.string().trim().regex(/^[a-f0-9]{64}$/),
+    manifest: catalogManifestSchema,
+    schemaVersion: z.int().min(1)
+});
+const catalogDiffOutputSchema = z.strictObject({
+    components: catalogChangesSchema,
+    currentCatalogHash: z.string().trim().regex(/^[a-f0-9]{64}$/),
+    recipes: catalogChangesSchema,
+    unchanged: z.boolean()
+});
+const diagnosticsOutputSchema = z.strictObject({
+    checks: z.array(z.strictObject({
+        message: z.string().trim(),
+        name: z.string().trim(),
+        status: z.enum(['fail', 'pass'])
+    })),
+    frameworkCoverage: z.strictObject({
+        astro: z.int().min(0),
+        elements: z.int().min(0),
+        react: z.int().min(0)
+    }),
+    status: z.enum(['healthy', 'issues'])
+});
 const structuredData = (data) => typeof data === 'object' && data !== null
     ? data
     : { value: data };
@@ -73,8 +119,8 @@ const jsonResource = (uri, data, mimeType = 'application/json') => ({
 export const createLumenServer = () => {
     const data = loadLumenData();
     const server = new McpServer({ name: '@santi020k/lumen-mcp', version: data.meta.serverVersion }, {
-        instructions: 'Read lumen://rules before generating Lumen code. Search or list the catalog, then inspect ' +
-            'the selected component for the target framework at usage detail before requesting source.'
+        instructions: 'Read lumen://meta, lumen://diagnostics, and lumen://rules before generating Lumen code. Search or list the catalog, ' +
+            'then inspect the selected component for the target framework at usage detail before requesting source.'
     });
     server.registerTool('lumen_list_components', {
         annotations: readOnlyAnnotations,
@@ -129,6 +175,9 @@ export const createLumenServer = () => {
         description: 'Rank natural-language matches across descriptions, categories, curated collections, ' +
             'framework contracts, props, attributes, recipes, tokens, and agent rules.',
         inputSchema: z.strictObject({
+            framework: z.enum(['astro', 'react', 'elements'])
+                .optional()
+                .meta({ description: 'Only search framework-specific component contracts for this target.' }),
             limit: z.int().min(1).max(100)
                 .optional()
                 .meta({ description: 'Maximum results to return (1-100, default 20).' }),
@@ -137,6 +186,37 @@ export const createLumenServer = () => {
         }),
         outputSchema: searchOutputSchema
     }, (args) => toMcpResult(search(args)));
+    server.registerTool('lumen_get_meta', {
+        annotations: readOnlyAnnotations,
+        description: 'Return snapshot provenance: server and package versions, schema version, component count, ' +
+            'and a deterministic catalog hash for freshness checks.',
+        inputSchema: z.strictObject({}),
+        outputSchema: metaOutputSchema
+    }, () => toMcpResult(getMeta()));
+    server.registerTool('lumen_get_catalog_manifest', {
+        annotations: readOnlyAnnotations,
+        description: 'Return stable per-component and per-recipe fingerprints that a client can retain for later change detection.',
+        inputSchema: z.strictObject({}),
+        outputSchema: catalogManifestOutputSchema
+    }, () => toMcpResult(getCatalogManifest()));
+    server.registerTool('lumen_diff_catalog', {
+        annotations: readOnlyAnnotations,
+        description: 'Compare a previously retained Lumen catalog manifest with the current snapshot and report added, changed, removed, and unchanged entries.',
+        inputSchema: z.strictObject({
+            baseline: catalogManifestSchema
+                .meta({ description: 'Manifest previously returned by lumen_get_catalog_manifest.' }),
+            baselineCatalogHash: z.string().trim().regex(/^[a-f0-9]{64}$/)
+                .optional()
+                .meta({ description: 'Optional previous catalog hash for a fast unchanged check.' })
+        }),
+        outputSchema: catalogDiffOutputSchema
+    }, (args) => toMcpResult(diffCatalog(args)));
+    server.registerTool('lumen_diagnose', {
+        annotations: readOnlyAnnotations,
+        description: 'Run deterministic snapshot integrity checks and report framework coverage. Useful when testing a new MCP connection.',
+        inputSchema: z.strictObject({}),
+        outputSchema: diagnosticsOutputSchema
+    }, () => toMcpResult(diagnose()));
     server.registerTool('lumen_get_tokens', {
         annotations: readOnlyAnnotations,
         description: 'Return structured Lumen semantic tokens, base color values, glass tokens, and theme attribute.',
@@ -149,6 +229,18 @@ export const createLumenServer = () => {
         inputSchema: z.strictObject({}),
         outputSchema: rulesOutputSchema
     }, () => toMcpResult(getRules()));
+    server.registerResource('lumen-meta', 'lumen://meta', {
+        description: 'Lumen MCP snapshot provenance and package versions.',
+        mimeType: 'application/json'
+    }, (uri) => jsonResource(uri, getMeta().data));
+    server.registerResource('lumen-catalog-manifest', 'lumen://catalog-manifest', {
+        description: 'Stable component and recipe fingerprints for catalog change detection.',
+        mimeType: 'application/json'
+    }, (uri) => jsonResource(uri, getCatalogManifest().data));
+    server.registerResource('lumen-diagnostics', 'lumen://diagnostics', {
+        description: 'Lumen MCP snapshot integrity checks and framework coverage.',
+        mimeType: 'application/json'
+    }, (uri) => jsonResource(uri, diagnose().data));
     server.registerResource('lumen-rules', 'lumen://rules', {
         description: 'Lumen agent rules (llms.txt).',
         mimeType: 'text/markdown'

package/dist/tools.d.ts

@@ -1,4 +1,10 @@
-import type { LumenComponentSnapshot, LumenData, LumenFramework, LumenRecipeSnapshot } from './data.js';
+import type { LumenCatalogManifest, LumenComponentSnapshot, LumenData, LumenFramework, LumenRecipeSnapshot } from './data.js';
+export interface CatalogChanges {
+    added: string[];
+    changed: string[];
+    removed: string[];
+    unchanged: string[];
+}
 export type ComponentDetailLevel = 'source' | 'summary' | 'usage';
 export interface ComponentSummary {
     category: string;
@@ -46,6 +52,24 @@ declare const componentDetail: (component: LumenComponentSnapshot, framework: Lu
     framework: {
         attributes?: string[];
         available: boolean;
+        behavior?: {
+            controller?: {
+                defaultValue: string;
+                description: string;
+                name: string;
+                type: string;
+            }[];
+            description?: string;
+            hook?: string;
+            mode: "adapter" | "built-in" | "hook" | "registration" | "runtime";
+            options?: {
+                defaultValue: string;
+                description: string;
+                name: string;
+                type: string;
+            }[];
+            setup: string;
+        };
         example: string;
         importStatement: string;
         language: "astro" | "html" | "tsx";
@@ -119,6 +143,7 @@ export declare const getRecipe: (args: {
     recipe?: LumenRecipeSnapshot;
 }>;
 export declare const search: (args: {
+    framework?: FrameworkFilter | undefined;
     limit?: number | undefined;
     query: string;
 }, data?: LumenData) => LumenToolResult<{
@@ -126,6 +151,32 @@ export declare const search: (args: {
     results: SearchResult[];
     total: number;
 }>;
+export declare const getMeta: (data?: LumenData) => LumenToolResult<{
+    meta: LumenData["meta"];
+}>;
+export declare const getCatalogManifest: (data?: LumenData) => LumenToolResult<{
+    catalogHash: string;
+    manifest: LumenCatalogManifest;
+    schemaVersion: number;
+}>;
+export declare const diffCatalog: (args: {
+    baseline: LumenCatalogManifest;
+    baselineCatalogHash?: string | undefined;
+}, data?: LumenData) => LumenToolResult<{
+    components: CatalogChanges;
+    currentCatalogHash: string;
+    recipes: CatalogChanges;
+    unchanged: boolean;
+}>;
+export declare const diagnose: (data?: LumenData) => LumenToolResult<{
+    checks: {
+        message: string;
+        name: string;
+        status: "fail" | "pass";
+    }[];
+    frameworkCoverage: Record<LumenFramework, number>;
+    status: "healthy" | "issues";
+}>;
 export declare const getTokens: (data?: LumenData) => LumenToolResult<{
     tokens: LumenData["tokens"];
 }>;

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}