@santi020k/lumen-mcp 0.1.0 → 0.3.0

package/dist/tools.js

@@ -1,6 +1,23 @@
 import { loadLumenData } from './data.js';
 const normalize = (value) => value.replaceAll(/([a-z0-9])([A-Z])/g, '$1-$2').replaceAll(/[\s_]+/g, '-').toLowerCase();
 const tokenize = (value) => normalize(value).split(/[^a-z0-9]+/).filter(Boolean);
+const searchStopWords = new Set([
+    'a', 'accessibility', 'accessible', 'admin', 'an', 'and', 'app', 'application', 'component', 'for',
+    'in', 'lumen', 'not', 'of', 'or', 'the', 'to', 'ui', 'with'
+]);
+const searchTermAliases = {
+    booking: ['booking', 'schedule', 'calendar', 'appointment', 'date'],
+    dark: ['dark', 'theme'],
+    dashboard: ['dashboard', 'data-table', 'sidebar', 'chart', 'stat', 'metric'],
+    mode: ['mode', 'theme'],
+    pagination: ['pagination', 'paginated'],
+    sortable: ['sortable', 'sort']
+};
+const meaningfulSearchTerms = (value) => {
+    const terms = tokenize(value);
+    const meaningful = terms.filter((term) => !searchStopWords.has(term));
+    return meaningful.length > 0 ? meaningful : terms;
+};
 const availableFrameworks = (component) => Object.entries(component.frameworks)
     .filter(([, available]) => available)
     .map(([framework]) => framework);
@@ -23,22 +40,33 @@ export const resolveRecipe = (name, data = loadLumenData()) => {
     const target = normalize(name);
     return data.recipes.find((recipe) => normalize(recipe.name) === target);
 };
-const frameworkSearchText = (component) => Object.values(component.frameworkDetails)
-    .flatMap((framework) => [
+const frameworkBehaviorSearchText = (behavior) => [
+    behavior?.description ?? '',
+    behavior?.hook ?? '',
+    behavior?.mode ?? '',
+    behavior?.setup ?? ''
+];
+const frameworkDetailsSearchText = (framework) => [
     framework.packageName,
+    ...frameworkBehaviorSearchText(framework.behavior),
+    framework.example,
     framework.propsExtends ?? '',
     framework.props.map((prop) => `${prop.name} ${prop.type}`).join(' '),
     framework.attributes?.join(' ') ?? '',
     framework.tagName ?? ''
-])
+];
+const frameworkSearchText = (component, framework) => (framework
+    ? [Reflect.get(component.frameworkDetails, framework)]
+    : Object.values(component.frameworkDetails))
+    .flatMap(frameworkDetailsSearchText)
     .join(' ');
-const componentSearchText = (component) => [
+const componentSearchText = (component, framework) => [
     component.name,
     component.kebab,
-    'accessible accessibility',
     component.description,
     component.category,
     component.collections.join(' '),
+    component.recipes.map((recipe) => recipe.name).join(' '),
     component.keywords.join(' '),
     component.dependencies.join(' '),
     component.guidance?.when ?? '',
@@ -46,16 +74,23 @@ const componentSearchText = (component) => [
     component.apiReference
         .map((row) => `${row.attribute} ${row.values} ${row.description}`)
         .join(' '),
-    frameworkSearchText(component)
+    frameworkSearchText(component, framework)
 ].join(' ');
 const scoreCandidate = (query, terms, searchableText, primaryName = '') => {
     const normalizedText = normalize(searchableText);
-    const matchedTerms = terms.filter((term) => normalizedText.includes(term));
-    if (matchedTerms.length !== terms.length)
+    const matchedTerms = terms.filter((term) => (Reflect.get(searchTermAliases, term) ?? [term]).some((candidate) => normalizedText.includes(candidate)));
+    if (matchedTerms.length === 0)
         return { matchedTerms, score: 0 };
-    const normalizedQuery = normalize(query);
+    const normalizedQuery = terms.join('-');
     const normalizedName = normalize(primaryName);
-    let score = terms.reduce((total, term) => total + (normalizedName.includes(term) ? 20 : 5), 0);
+    const coverage = matchedTerms.length / terms.length;
+    let score = matchedTerms.reduce((total, term) => total + ((Reflect.get(searchTermAliases, term) ?? [term]).some((candidate) => normalizedName.includes(candidate))
+        ? 20
+        : 5), 0);
+    score += Math.round(coverage * 80);
+    score -= (terms.length - matchedTerms.length) * 3;
+    if (terms.includes(normalizedName))
+        score += 50;
     if (normalizedText.includes(normalizedQuery))
         score += 100;
     if (normalizedName === normalizedQuery)
@@ -63,20 +98,22 @@ const scoreCandidate = (query, terms, searchableText, primaryName = '') => {
     return { matchedTerms, score };
 };
 const appendSearchResult = (results, candidate, query, terms, searchableText) => {
-    const match = scoreCandidate(query, terms, searchableText, candidate.name);
+    const match = scoreCandidate(query, terms, searchableText, candidate.kind === 'rule' ? '' : candidate.name);
     if (match.score > 0)
         results.push({ ...candidate, ...match });
 };
-const collectSearchResults = (query, terms, data) => {
+const collectSearchResults = (query, terms, data, framework) => {
     const results = [];
     for (const component of data.components) {
+        if (framework && !Reflect.get(component.frameworks, framework))
+            continue;
         appendSearchResult(results, {
             category: component.category,
             description: component.description,
             frameworks: availableFrameworks(component),
             kind: 'component',
             name: component.name
-        }, query, terms, componentSearchText(component));
+        }, query, terms, componentSearchText(component, framework));
     }
     for (const recipe of data.recipes) {
         appendSearchResult(results, {
@@ -104,14 +141,17 @@ const collectSearchResults = (query, terms, data) => {
 };
 export const listComponents = (args = {}, data = loadLumenData()) => {
     const query = args.query?.trim();
-    const queryTerms = query ? tokenize(query) : [];
+    const queryTerms = query ? meaningfulSearchTerms(query) : [];
+    const recipe = args.recipe ? resolveRecipe(args.recipe, data) : undefined;
+    const recipeName = recipe?.name ?? (args.recipe ? normalize(args.recipe) : undefined);
     const matches = data.components.filter((component) => {
         if (args.framework && !component.frameworks[args.framework])
             return false;
-        if (args.recipe && !component.recipes.some((recipe) => recipe.name === args.recipe))
+        if (recipeName &&
+            !component.recipes.some((componentRecipe) => normalize(componentRecipe.name) === recipeName))
             return false;
         if (query &&
-            scoreCandidate(query, queryTerms, componentSearchText(component), component.name).score === 0)
+            scoreCandidate(query, queryTerms, componentSearchText(component, args.framework), component.name).score === 0)
             return false;
         return true;
     });
@@ -181,6 +221,9 @@ const componentDetail = (component, framework, detail) => {
         : usage;
 };
 const formatProps = (framework) => {
+    if (framework.attributes && framework.attributes.length > 0) {
+        return `Attributes:\n${framework.attributes.map((attribute) => `- ${attribute}`).join('\n')}`;
+    }
     if (framework.props.length === 0) {
         return framework.propsExtends
             ? `Props extend ${framework.propsExtends}; no additional local props were detected.`
@@ -192,25 +235,35 @@ const formatProps = (framework) => {
         : 'Props:';
     return `${header}\n${lines.join('\n')}`;
 };
-const formatComponentUsage = (component, frameworkName, detail) => {
-    const framework = getFrameworkDetail(component.frameworkDetails, frameworkName);
-    const sections = [
-        `# ${component.name}`,
-        component.description,
-        `Category: ${component.category}`,
-        `Framework: ${frameworkName}`,
-        `Package: ${framework.packageName}`,
-        `Import: ${framework.importStatement}`,
-        `Styles: ${framework.styleImport}`,
-        framework.tagName ? `Custom element: <${framework.tagName}>` : '',
-        component.recipes.length > 0
-            ? `Recipes: ${component.recipes.map((recipe) => recipe.name).join(', ')}`
-            : 'Recipes: none'
-    ].filter(Boolean);
-    if (detail === 'summary')
-        return sections.join('\n');
-    sections.push('', formatProps(framework), '', '## Example', `\`\`\`${framework.language}`);
-    sections.push(framework.example, '```');
+const buildSummarySections = (component, frameworkName, framework) => [
+    `# ${component.name}`,
+    component.description,
+    `Category: ${component.category}`,
+    `Framework: ${frameworkName}`,
+    `Package: ${framework.packageName}`,
+    `Import: ${framework.importStatement}`,
+    `Styles: ${framework.styleImport}`,
+    framework.tagName ? `Custom element: <${framework.tagName}>` : '',
+    component.recipes.length > 0
+        ? `Recipes: ${component.recipes.map((recipe) => recipe.name).join(', ')}`
+        : 'Recipes: none'
+].filter(Boolean);
+const appendBehaviorSections = (sections, behavior) => {
+    if (!behavior)
+        return;
+    sections.push('', '## Framework behavior', behavior.setup);
+    if (behavior.hook)
+        sections.push(`Hook: ${behavior.hook}`);
+    if (behavior.description)
+        sections.push(behavior.description);
+    if (behavior.options && behavior.options.length > 0) {
+        sections.push('', 'Hook options:', ...behavior.options.map((option) => `- ${option.name}: ${option.type} — ${option.description}`));
+    }
+    if (behavior.controller && behavior.controller.length > 0) {
+        sections.push('', 'Controller values:', ...behavior.controller.map((value) => `- ${value.name}: ${value.type} — ${value.description}`));
+    }
+};
+const appendGuidanceSections = (sections, component) => {
     if (component.guidance) {
         sections.push('', '## Guidance', component.guidance.when);
         if (component.guidance.distinction)
@@ -218,15 +271,27 @@ const formatComponentUsage = (component, frameworkName, detail) => {
     }
     if (component.keyboardInteractions.length > 0) {
         sections.push('', '## Keyboard interactions');
-        sections.push(...component.keyboardInteractions.map((row) => `- ${row.key}: ${row.action}`));
+        sections.push(...component.keyboardInteractions.map((interaction) => `- ${interaction.key}: ${interaction.action}`));
+    }
+    if (component.apiReference.length > 0) {
+        sections.push('', '## API reference');
+        sections.push(...component.apiReference.map((row) => `- \`${row.attribute}\` ${row.values} — ${row.description}`));
     }
     if (component.runtimeEvents.length > 0) {
         sections.push('', '## Runtime events');
         sections.push(...component.runtimeEvents.map((event) => `- ${event.name}: ${event.when}`));
     }
+};
+const formatComponentUsage = (component, frameworkName, detail) => {
+    const framework = getFrameworkDetail(component.frameworkDetails, frameworkName);
+    const sections = buildSummarySections(component, frameworkName, framework);
+    if (detail === 'summary')
+        return sections.join('\n');
+    sections.push('', formatProps(framework), '', '## Example', `\`\`\`${framework.language}`, framework.example, '```');
+    appendBehaviorSections(sections, framework.behavior);
+    appendGuidanceSections(sections, component);
     if (detail === 'source') {
-        sections.push('', `## ${frameworkName} reference source`);
-        sections.push(`\`\`\`${framework.language}`, framework.source.trimEnd(), '```');
+        sections.push('', `## ${frameworkName} reference source`, `\`\`\`${framework.language}`, framework.source.trimEnd(), '```');
     }
     return sections.join('\n');
 };
@@ -298,8 +363,16 @@ export const search = (args, data = loadLumenData()) => {
         };
     }
     const limit = Math.max(1, Math.min(args.limit ?? 20, 100));
-    const results = collectSearchResults(query, tokenize(query), data);
-    results.sort((left, right) => right.score - left.score || left.name.localeCompare(right.name));
+    const results = collectSearchResults(query, meaningfulSearchTerms(query), data, args.framework);
+    const kindPriority = {
+        component: 0,
+        recipe: 1,
+        rule: 3,
+        token: 2
+    };
+    results.sort((left, right) => right.score - left.score ||
+        kindPriority[left.kind] - kindPriority[right.kind] ||
+        left.name.localeCompare(right.name));
     const shown = results.slice(0, limit);
     if (results.length === 0) {
         return {
@@ -312,6 +385,125 @@ export const search = (args, data = loadLumenData()) => {
         text: `${results.length} match(es) for "${args.query}"${results.length > shown.length ? ` (showing ${shown.length})` : ''}:\n\n${shown.map((result) => `${result.kind}: ${result.name} — ${result.description} [matched: ${result.matchedTerms.join(', ')}]`).join('\n')}`
     };
 };
+export const getMeta = (data = loadLumenData()) => ({
+    data: { meta: data.meta },
+    text: [
+        '# Lumen MCP snapshot',
+        `Server version: ${data.meta.serverVersion}`,
+        `Schema version: ${data.meta.schemaVersion}`,
+        `Catalog hash: ${data.meta.catalogHash}`,
+        `Components: ${data.meta.componentCount}`,
+        '',
+        '## Package versions',
+        ...Object.entries(data.meta.packageVersions).map(([name, version]) => `- ${name}: ${version}`)
+    ].join('\n')
+});
+const diffManifestSection = (current, baseline) => {
+    const currentNames = Object.keys(current);
+    const baselineNames = Object.keys(baseline);
+    return {
+        added: currentNames.filter((name) => Reflect.get(baseline, name) === undefined).sort(),
+        changed: currentNames
+            .filter((name) => Reflect.get(baseline, name) !== undefined && Reflect.get(baseline, name) !== Reflect.get(current, name))
+            .sort(),
+        removed: baselineNames.filter((name) => Reflect.get(current, name) === undefined).sort(),
+        unchanged: currentNames.filter((name) => Reflect.get(baseline, name) === Reflect.get(current, name)).sort()
+    };
+};
+export const getCatalogManifest = (data = loadLumenData()) => ({
+    data: {
+        catalogHash: data.meta.catalogHash,
+        manifest: data.catalogManifest,
+        schemaVersion: data.meta.schemaVersion
+    },
+    text: [
+        '# Lumen catalog manifest',
+        `Catalog hash: ${data.meta.catalogHash}`,
+        `Components: ${Object.keys(data.catalogManifest.components).length}`,
+        `Recipes: ${Object.keys(data.catalogManifest.recipes).length}`,
+        '',
+        'Keep this structured result and pass its manifest to lumen_diff_catalog after an MCP update.'
+    ].join('\n')
+});
+export const diffCatalog = (args, data = loadLumenData()) => {
+    const components = diffManifestSection(data.catalogManifest.components, args.baseline.components);
+    const recipes = diffManifestSection(data.catalogManifest.recipes, args.baseline.recipes);
+    const changedCount = [
+        ...components.added,
+        ...components.changed,
+        ...components.removed,
+        ...recipes.added,
+        ...recipes.changed,
+        ...recipes.removed
+    ].length;
+    const unchanged = changedCount === 0 &&
+        (args.baselineCatalogHash === undefined ||
+            args.baselineCatalogHash === data.meta.catalogHash);
+    return {
+        data: {
+            components,
+            currentCatalogHash: data.meta.catalogHash,
+            recipes,
+            unchanged
+        },
+        text: unchanged
+            ? `The Lumen catalog is unchanged (${data.meta.catalogHash}).`
+            : [
+                '# Lumen catalog changes',
+                `Current catalog hash: ${data.meta.catalogHash}`,
+                `Changed entries: ${changedCount}`,
+                `Components — added: ${components.added.length}, changed: ${components.changed.length}, removed: ${components.removed.length}`,
+                `Recipes — added: ${recipes.added.length}, changed: ${recipes.changed.length}, removed: ${recipes.removed.length}`
+            ].join('\n')
+    };
+};
+export const diagnose = (data = loadLumenData()) => {
+    const componentNames = data.components.map((component) => component.name);
+    const frameworkCoverage = {
+        astro: data.components.filter((component) => component.frameworks.astro).length,
+        elements: data.components.filter((component) => component.frameworks.elements).length,
+        react: data.components.filter((component) => component.frameworks.react).length
+    };
+    const checks = [
+        {
+            message: `${data.components.length} component records match metadata.`,
+            name: 'component-count',
+            status: data.components.length === data.meta.componentCount ? 'pass' : 'fail'
+        },
+        {
+            message: 'Component names are unique.',
+            name: 'unique-components',
+            status: new Set(componentNames).size === componentNames.length ? 'pass' : 'fail'
+        },
+        {
+            message: 'Every component has a manifest fingerprint.',
+            name: 'component-manifest',
+            status: componentNames.every((name) => Reflect.get(data.catalogManifest.components, name)) ? 'pass' : 'fail'
+        },
+        {
+            message: 'Every available framework contract has an example and import statement.',
+            name: 'framework-contracts',
+            status: data.components.every((component) => Object.entries(component.frameworks).every(([framework, available]) => {
+                if (!available)
+                    return true;
+                const details = Reflect.get(component.frameworkDetails, framework);
+                return Boolean(details?.example.trim()) && Boolean(details?.importStatement.trim());
+            })) ? 'pass' : 'fail'
+        }
+    ];
+    const status = checks.every((check) => check.status === 'pass') ? 'healthy' : 'issues';
+    return {
+        data: { checks, frameworkCoverage, status },
+        isError: status === 'issues',
+        text: [
+            `# Lumen MCP diagnostics: ${status}`,
+            `Catalog hash: ${data.meta.catalogHash}`,
+            `Framework coverage — Astro: ${frameworkCoverage.astro}, React: ${frameworkCoverage.react}, Elements: ${frameworkCoverage.elements}`,
+            '',
+            ...checks.map((check) => `- ${check.status.toUpperCase()} ${check.name}: ${check.message}`)
+        ].join('\n')
+    };
+};
 export const getTokens = (data = loadLumenData()) => {
     const { tokens } = data;
     const colorLines = Object.entries(tokens.colors).map(([name, value]) => `- ${name}: hsl(${value})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@santi020k/lumen-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -29,20 +29,23 @@
     "LICENSE"
   ],
   "bin": {
-    "lumen-mcp": "./bin/lumen-mcp.mjs"
+    "lumen-mcp": "./bin/lumen-mcp.mjs",
+    "lumen-mcp-http": "./bin/lumen-mcp-http.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@astrojs/compiler": "^3.0.1",
+    "@types/express": "^5.0.6",
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.10",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "engines": {
-    "node": ">=22.18.0"
+    "node": ">=20.20.0"
   },
   "repository": {
     "type": "git",
@@ -69,9 +72,14 @@
   "license": "MIT",
   "scripts": {
     "generate": "node scripts/generate-data.mjs",
+    "check:snapshot": "node scripts/generate-data.mjs --check",
     "build": "pnpm run generate && tsc -p tsconfig.build.json",
     "dev": "pnpm run generate && tsc -p tsconfig.build.json --watch --preserveWatchOutput",
     "local": "node bin/lumen-mcp-local.mjs",
+    "eval": "pnpm --filter @santi020k/lumen-react... run build && pnpm run build && node scripts/evaluate.mjs && node scripts/validate-examples.mjs",
+    "eval:examples": "pnpm --filter @santi020k/lumen-react... run build && pnpm run build && node scripts/validate-examples.mjs",
+    "eval:search": "pnpm run build && node scripts/evaluate.mjs --search-only",
+    "smoke:package": "pnpm run build && node scripts/smoke-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --config ../../vitest.config.ts --project mcp",
     "test:coverage": "vitest run --config ../../vitest.config.ts --project mcp --coverage",