@santi020k/lumen-mcp 0.1.0

package/dist/tools.js

@@ -0,0 +1,346 @@
+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 availableFrameworks = (component) => Object.entries(component.frameworks)
+    .filter(([, available]) => available)
+    .map(([framework]) => framework);
+const componentSummary = (component) => ({
+    category: component.category,
+    collections: component.collections,
+    description: component.description,
+    frameworks: availableFrameworks(component),
+    kebab: component.kebab,
+    name: component.name,
+    recipes: component.recipes.map((recipe) => recipe.name)
+});
+export const resolveComponent = (name, data = loadLumenData()) => {
+    const target = normalize(name);
+    return data.components.find((component) => component.name === name) ??
+        data.components.find((component) => component.kebab === target) ??
+        data.components.find((component) => normalize(component.name) === target);
+};
+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) => [
+    framework.packageName,
+    framework.propsExtends ?? '',
+    framework.props.map((prop) => `${prop.name} ${prop.type}`).join(' '),
+    framework.attributes?.join(' ') ?? '',
+    framework.tagName ?? ''
+])
+    .join(' ');
+const componentSearchText = (component) => [
+    component.name,
+    component.kebab,
+    'accessible accessibility',
+    component.description,
+    component.category,
+    component.collections.join(' '),
+    component.keywords.join(' '),
+    component.dependencies.join(' '),
+    component.guidance?.when ?? '',
+    component.guidance?.distinction ?? '',
+    component.apiReference
+        .map((row) => `${row.attribute} ${row.values} ${row.description}`)
+        .join(' '),
+    frameworkSearchText(component)
+].join(' ');
+const scoreCandidate = (query, terms, searchableText, primaryName = '') => {
+    const normalizedText = normalize(searchableText);
+    const matchedTerms = terms.filter((term) => normalizedText.includes(term));
+    if (matchedTerms.length !== terms.length)
+        return { matchedTerms, score: 0 };
+    const normalizedQuery = normalize(query);
+    const normalizedName = normalize(primaryName);
+    let score = terms.reduce((total, term) => total + (normalizedName.includes(term) ? 20 : 5), 0);
+    if (normalizedText.includes(normalizedQuery))
+        score += 100;
+    if (normalizedName === normalizedQuery)
+        score += 500;
+    return { matchedTerms, score };
+};
+const appendSearchResult = (results, candidate, query, terms, searchableText) => {
+    const match = scoreCandidate(query, terms, searchableText, candidate.name);
+    if (match.score > 0)
+        results.push({ ...candidate, ...match });
+};
+const collectSearchResults = (query, terms, data) => {
+    const results = [];
+    for (const component of data.components) {
+        appendSearchResult(results, {
+            category: component.category,
+            description: component.description,
+            frameworks: availableFrameworks(component),
+            kind: 'component',
+            name: component.name
+        }, query, terms, componentSearchText(component));
+    }
+    for (const recipe of data.recipes) {
+        appendSearchResult(results, {
+            category: recipe.categories.join(', '),
+            description: recipe.description,
+            kind: 'recipe',
+            name: recipe.name
+        }, query, terms, `${recipe.name} ${recipe.description} ${recipe.categories.join(' ')} ${(recipe.components ?? []).join(' ')}`);
+    }
+    for (const token of data.tokens.semantic) {
+        appendSearchResult(results, {
+            description: 'Lumen semantic design token.',
+            kind: 'token',
+            name: token
+        }, query, terms, token);
+    }
+    for (const line of data.rules.split('\n').filter((rule) => rule.trim())) {
+        appendSearchResult(results, {
+            description: line.trim(),
+            kind: 'rule',
+            name: line.trim()
+        }, query, terms, line);
+    }
+    return results;
+};
+export const listComponents = (args = {}, data = loadLumenData()) => {
+    const query = args.query?.trim();
+    const queryTerms = query ? tokenize(query) : [];
+    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))
+            return false;
+        if (query &&
+            scoreCandidate(query, queryTerms, componentSearchText(component), component.name).score === 0)
+            return false;
+        return true;
+    });
+    const summaries = matches.map(componentSummary);
+    if (summaries.length === 0) {
+        return {
+            data: { components: [], count: 0 },
+            text: 'No components matched the given filters.'
+        };
+    }
+    const lines = summaries.map((component) => {
+        const recipeNote = component.recipes.length > 0
+            ? ` [recipes: ${component.recipes.join(', ')}]`
+            : '';
+        return `${component.name} (${component.kebab}) — ${component.description} — ${component.frameworks.join(', ')}${recipeNote}`;
+    });
+    return {
+        data: { components: summaries, count: summaries.length },
+        text: `${summaries.length} component(s):\n\n${lines.join('\n')}`
+    };
+};
+const frameworkWithoutSource = (framework) => {
+    const { source: _source, ...usage } = framework;
+    return usage;
+};
+const getFrameworkDetail = (details, framework) => {
+    if (framework === 'astro')
+        return details.astro;
+    if (framework === 'elements')
+        return details.elements;
+    return details.react;
+};
+const getRecipeInstall = (install, framework) => {
+    if (framework === 'astro')
+        return install.astro;
+    if (framework === 'elements')
+        return install.elements;
+    return install.react;
+};
+const componentDetail = (component, framework, detail) => {
+    const selectedFramework = getFrameworkDetail(component.frameworkDetails, framework);
+    const summary = componentSummary(component);
+    if (detail === 'summary') {
+        return {
+            ...summary,
+            dependencies: component.dependencies,
+            framework: {
+                available: selectedFramework.available,
+                packageName: selectedFramework.packageName,
+                tagName: selectedFramework.tagName
+            },
+            guidance: component.guidance
+        };
+    }
+    const usage = {
+        ...summary,
+        apiReference: component.apiReference,
+        dependencies: component.dependencies,
+        files: component.files,
+        framework: frameworkWithoutSource(selectedFramework),
+        guidance: component.guidance,
+        keyboardInteractions: component.keyboardInteractions,
+        runtimeEvents: component.runtimeEvents
+    };
+    return detail === 'source'
+        ? { ...usage, framework: selectedFramework }
+        : usage;
+};
+const formatProps = (framework) => {
+    if (framework.props.length === 0) {
+        return framework.propsExtends
+            ? `Props extend ${framework.propsExtends}; no additional local props were detected.`
+            : 'No typed props detected.';
+    }
+    const lines = framework.props.map((prop) => `- ${prop.name}${prop.optional ? '?' : ''}: ${prop.type}`);
+    const header = framework.propsExtends
+        ? `Props (extends ${framework.propsExtends}):`
+        : '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, '```');
+    if (component.guidance) {
+        sections.push('', '## Guidance', component.guidance.when);
+        if (component.guidance.distinction)
+            sections.push(component.guidance.distinction);
+    }
+    if (component.keyboardInteractions.length > 0) {
+        sections.push('', '## Keyboard interactions');
+        sections.push(...component.keyboardInteractions.map((row) => `- ${row.key}: ${row.action}`));
+    }
+    if (component.runtimeEvents.length > 0) {
+        sections.push('', '## Runtime events');
+        sections.push(...component.runtimeEvents.map((event) => `- ${event.name}: ${event.when}`));
+    }
+    if (detail === 'source') {
+        sections.push('', `## ${frameworkName} reference source`);
+        sections.push(`\`\`\`${framework.language}`, framework.source.trimEnd(), '```');
+    }
+    return sections.join('\n');
+};
+export const getComponent = (args, data = loadLumenData()) => {
+    const component = resolveComponent(args.name, data);
+    if (!component) {
+        const message = `Unknown component "${args.name}". Use lumen_list_components to see available names.`;
+        return {
+            data: { found: false, message },
+            isError: true,
+            text: message
+        };
+    }
+    const framework = args.framework ?? 'astro';
+    const detail = args.detail ?? (args.includeSource ? 'source' : 'usage');
+    const selectedFramework = getFrameworkDetail(component.frameworkDetails, framework);
+    if (!selectedFramework.available) {
+        const message = `${component.name} is not available for ${framework}.`;
+        return {
+            data: { found: false, message },
+            isError: true,
+            text: message
+        };
+    }
+    return {
+        data: {
+            component: componentDetail(component, framework, detail),
+            found: true
+        },
+        text: formatComponentUsage(component, framework, detail)
+    };
+};
+export const getRecipe = (args, data = loadLumenData()) => {
+    const recipe = resolveRecipe(args.name, data);
+    if (!recipe) {
+        const message = `Unknown recipe "${args.name}". Use lumen_search or lumen_list_components to discover recipes.`;
+        return {
+            data: { found: false, message },
+            isError: true,
+            text: message
+        };
+    }
+    const framework = args.framework ?? 'astro';
+    const componentLines = (recipe.components ?? []).map((name) => {
+        const component = resolveComponent(name, data);
+        return component ? `- ${component.name}: ${component.description}` : `- ${name}`;
+    });
+    return {
+        data: { found: true, recipe },
+        text: [
+            `# ${recipe.name}`,
+            recipe.description,
+            `Type: ${recipe.type}`,
+            `Categories: ${recipe.categories.join(', ') || 'all'}`,
+            `Install for ${framework}: ${getRecipeInstall(recipe.install, framework)}`,
+            '',
+            '## Components',
+            ...componentLines
+        ].join('\n')
+    };
+};
+export const search = (args, data = loadLumenData()) => {
+    const query = args.query.trim();
+    if (!query) {
+        return {
+            data: { query, results: [], total: 0 },
+            isError: true,
+            text: 'Provide a non-empty query.'
+        };
+    }
+    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 shown = results.slice(0, limit);
+    if (results.length === 0) {
+        return {
+            data: { query, results: [], total: 0 },
+            text: `No matches for "${args.query}".`
+        };
+    }
+    return {
+        data: { query, results: shown, total: results.length },
+        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 getTokens = (data = loadLumenData()) => {
+    const { tokens } = data;
+    const colorLines = Object.entries(tokens.colors).map(([name, value]) => `- ${name}: hsl(${value})`);
+    const glassLines = Object.entries(tokens.glass).map(([name, value]) => `- ${name}: ${value}`);
+    const text = [
+        '# Lumen design tokens',
+        `Theme attribute: ${tokens.themeAttribute} (values: light, dark)`,
+        '',
+        '## Semantic token names (use as `text-ink`, `bg-surface`, `border-line`, etc.)',
+        tokens.semantic.map((token) => `- ${token}`).join('\n'),
+        '',
+        '## Base color values',
+        colorLines.join('\n'),
+        '',
+        '## Glass surface tokens',
+        glassLines.join('\n')
+    ].join('\n');
+    return { data: { tokens }, text };
+};
+export const getRules = (data = loadLumenData()) => {
+    if (!data.rules) {
+        return {
+            data: { rules: '' },
+            isError: true,
+            text: 'No agent rules (llms.txt) were bundled.'
+        };
+    }
+    return {
+        data: { rules: data.rules.trimEnd() },
+        text: data.rules.trimEnd()
+    };
+};

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@santi020k/lumen-mcp",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Model Context Protocol server for the Lumen multi-framework primitive UI system. Lets AI agents list components, read real component source, and follow Lumen tokens and rules.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "lumen-mcp": "./bin/lumen-mcp.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/santi020k/lumen.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://lumen.santi020k.com",
+  "bugs": {
+    "url": "https://github.com/santi020k/lumen/issues"
+  },
+  "keywords": [
+    "lumen",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "ui",
+    "design-system",
+    "astro"
+  ],
+  "author": {
+    "name": "Santiago Molina",
+    "url": "https://santi020k.com"
+  },
+  "license": "MIT",
+  "scripts": {
+    "generate": "node scripts/generate-data.mjs",
+    "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",
+    "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",
+    "lint": "eslint . --no-warn-ignored",
+    "lint:fix": "eslint . --fix --no-warn-ignored",
+    "clean": "rm -rf dist coverage"
+  }
+}