@solid-design-system/mcp 0.0.1

package/dist/build/templates.js

@@ -0,0 +1,239 @@
+import fs from 'node:fs/promises';
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname, join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ora from 'ora';
+import { componentPath, createPath, templatesPackagePath, stylesPath } from '../utilities/index.js';
+/** Absolute path to the docs stories/templates directory */
+const DOCS_TEMPLATES_DIR = join(dirname(fileURLToPath(import.meta.url)), '../../../docs/src/stories/templates');
+const extractComponents = (source) => {
+    const matches = [...source.matchAll(/\bsd-[\w-]+/g)].map(m => m[0]);
+    return [...new Set(matches)].sort();
+};
+const extractTemplateLiteralContent = (source, startIndex) => {
+    let i = startIndex;
+    let depth = 0;
+    while (i < source.length) {
+        const c = source[i];
+        if (depth === 0 && c === '`')
+            return source.slice(startIndex, i);
+        if (c === '$' && source[i + 1] === '{') {
+            depth++;
+            i += 2;
+            continue;
+        }
+        if (depth > 0) {
+            if (c === '{')
+                depth++;
+            else if (c === '}')
+                depth--;
+        }
+        i++;
+    }
+    return source.slice(startIndex);
+};
+const dedent = (str) => {
+    const lines = str.split('\n');
+    while (lines.length && !lines[0].trim())
+        lines.shift();
+    while (lines.length && !lines[lines.length - 1].trim())
+        lines.pop();
+    if (!lines.length)
+        return '';
+    const indent = Math.min(...lines.filter(l => l.trim()).map(l => l.match(/^(\s*)/)?.[1].length ?? 0));
+    return lines.map(l => l.slice(indent)).join('\n');
+};
+const exportNameToTitle = (name) => name.replace(/([A-Z])/g, ' $1').trim();
+const extractDefaultTitle = (source) => {
+    const match = source.match(/title:\s*['"]Templates\/([^'"]+)['"]/);
+    return match ? match[1] : null;
+};
+const extractExamples = (source) => {
+    const examples = [];
+    const exportPattern = /^export const (\w+) = \{/gm;
+    let match;
+    while ((match = exportPattern.exec(source)) !== null) {
+        const exportName = match[1];
+        const blockStart = match.index + match[0].length;
+        const nameMatch = source.slice(blockStart, blockStart + 500).match(/name:\s*['"]([^'"]+)['"]/);
+        const exampleName = nameMatch ? nameMatch[1] : exportNameToTitle(exportName);
+        const blockSlice = source.slice(blockStart);
+        const htmlIdx = blockSlice.indexOf('html`');
+        if (htmlIdx === -1)
+            continue;
+        const rawHtml = extractTemplateLiteralContent(source, blockStart + htmlIdx + 5);
+        const html = dedent(rawHtml);
+        if (!html)
+            continue;
+        examples.push({ name: exampleName, html });
+    }
+    return examples;
+};
+const extractSection = (docs, heading) => {
+    const re = new RegExp(`###\\s+${heading}\\n+([\\s\\S]*?)(?=\\n+###(?!#)|$)`, 'i');
+    const m = docs.match(re);
+    return m ? m[1].trim() : '';
+};
+const promoteSubheadings = (block) => block.replace(/^####\s+/gm, '### ');
+export const buildTemplates = async () => {
+    const spinner = ora({ prefixText: 'Templates:', text: 'Generating static metadata...' }).start();
+    try {
+        spinner.text = 'Cleaning up old metadata...';
+        rmSync(templatesPackagePath, { recursive: true, force: true });
+        spinner.succeed('Old metadata cleaned up.');
+        await createPath(templatesPackagePath);
+        spinner.text = 'Generating templates metadata...';
+        const storyFiles = (await fs.readdir(DOCS_TEMPLATES_DIR)).filter(f => f.endsWith('.stories.ts'));
+        await Promise.all(storyFiles.map(async (file) => {
+            const name = basename(file, '.stories.ts');
+            const source = await fs.readFile(join(DOCS_TEMPLATES_DIR, file), 'utf-8');
+            const components = extractComponents(source);
+            const examples = extractExamples(source);
+            const title = extractDefaultTitle(source) ?? name;
+            const frontmatter = [
+                '---',
+                `name: ${name}`,
+                `title: ${title}`,
+                'components:',
+                ...components.map(c => `  - ${c}`),
+                'version: 1.0.0',
+                '---'
+            ].join('\n');
+            const content = [
+                frontmatter,
+                ...examples.map(example => `## Template: ${example.name}\n\n\`\`\`html\n${example.html}\n\`\`\``)
+            ].join('\n\n');
+            await fs.writeFile(join(templatesPackagePath, `${name}.md`), content);
+        }));
+        spinner.succeed('Templates metadata generated successfully.');
+        spinner.text = 'Finalising component metadata into subdirectories...';
+        const compFiles = (await fs.readdir(componentPath)).filter(f => f.endsWith('.json'));
+        // Write final metadata
+        await Promise.all(compFiles.map(async (file) => {
+            const tagName = basename(file, '.json');
+            const raw = await fs.readFile(join(componentPath, file), 'utf-8').catch(() => null);
+            if (!raw)
+                return;
+            const { api, docs, stories: examples } = JSON.parse(raw);
+            const exampleSlugList = examples.map(example => example.slug);
+            // Create component subdirectory and stories subfolder
+            const compDir = join(componentPath, tagName);
+            const storiesDir = join(compDir, 'stories');
+            mkdirSync(storiesDir, { recursive: true });
+            // Write per-story files into stories/ subfolder
+            await Promise.all(examples.map(example => {
+                const lines = [];
+                if (example.description)
+                    lines.push(example.description, '');
+                lines.push('```html', example.html, '```');
+                return fs.writeFile(join(storiesDir, `${example.slug}.md`), lines.join('\n'));
+            }));
+            // CSS parts — names only, no descriptions
+            const partNames = api.parts
+                ? api.parts
+                    .split('\n')
+                    .map(line => line.replace(/^part\.([\w-]+):.*/, 'part.$1'))
+                    .filter(Boolean)
+                : [];
+            // Build info.md sections
+            const sections = [];
+            // Overview
+            sections.push(`## Overview\n\n\`<${tagName}>\` — ${api.summary}`);
+            // API section with sub-headings
+            const apiSubSections = [];
+            if (exampleSlugList.length) {
+                apiSubSections.push(`### Examples\n\nUse the components tool by passing the args \`component\` and \`example\` for any of these combinations:\n\n${exampleSlugList.map(example => `- component: ${tagName}, example: ${example}`).join('\n')}`);
+            }
+            if (api.props)
+                apiSubSections.push(`### Key Properties\n\n${api.props}`);
+            if (api.events)
+                apiSubSections.push(`### Events\n\n${api.events}`);
+            if (api.slots)
+                apiSubSections.push(`### Slots\n\n${api.slots}`);
+            if (partNames.length)
+                apiSubSections.push(`### CSS Parts\n\n${partNames.join('\n')}`);
+            if (apiSubSections.length)
+                sections.push(`## API\n\n${apiSubSections.join('\n\n')}`);
+            // Guidelines section
+            if (docs) {
+                const guideSubSections = [];
+                const useCases = extractSection(docs, 'Common Use Cases');
+                if (useCases)
+                    guideSubSections.push(`### Use Cases\n\n${useCases}`);
+                const guidelines = extractSection(docs, 'Usage Guidelines');
+                if (guidelines)
+                    guideSubSections.push(`### Rules\n\n${promoteSubheadings(guidelines)}`);
+                const accessibility = extractSection(docs, 'Accessibility Information');
+                if (accessibility)
+                    guideSubSections.push(`### Accessibility\n\n${accessibility}`);
+                if (guideSubSections.length)
+                    sections.push(`## Guidelines\n\n${guideSubSections.join('\n\n')}`);
+            }
+            await fs.writeFile(join(compDir, 'info.md'), sections.join('\n\n'));
+            // Remove intermediate JSON
+            await fs.unlink(join(componentPath, file)).catch(() => null);
+        }));
+        spinner.succeed('Component subdirectories finalised.');
+        // Finalize styles metadata: convert intermediate JSON to subdirectories with info.md + stories/
+        spinner.text = 'Finalising style metadata into subdirectories...';
+        const styleFiles = (await fs.readdir(stylesPath)).filter(f => f.endsWith('.json'));
+        await Promise.all(styleFiles.map(async (file) => {
+            const styleName = basename(file, '.json');
+            const raw = await fs.readFile(join(stylesPath, file), 'utf-8').catch(() => null);
+            if (!raw)
+                return;
+            const { summary, docs, relatedTemplates, stories: examples } = JSON.parse(raw);
+            const exampleSlugList = examples.map(example => example.slug);
+            // Create style subdirectory and stories subfolder
+            const styleDir = join(stylesPath, styleName);
+            const storiesDir = join(styleDir, 'stories');
+            mkdirSync(storiesDir, { recursive: true });
+            // Write per-story files into stories/ subfolder
+            await Promise.all(examples.map(example => {
+                const lines = [];
+                if (example.description)
+                    lines.push(example.description, '');
+                lines.push('```html', example.html, '```');
+                return fs.writeFile(join(storiesDir, `${example.slug}.md`), lines.join('\n'));
+            }));
+            // Build info.md sections
+            const sections = [];
+            // Overview
+            sections.push(`## Overview\n\n\`${styleName}\`${summary ? ` – ${summary}` : ' style utility'}`);
+            // API section with sub-headings
+            const apiSubSections = [];
+            if (exampleSlugList.length) {
+                apiSubSections.push(`### Examples\n\nUse the styles tool (with \`style\` + \`example\` args) to retrieve the HTML for any of these examples:\n\n${exampleSlugList.map(example => `- ${styleName}/${example}`).join('\n')}`);
+            }
+            if (apiSubSections.length)
+                sections.push(`## API\n\n${apiSubSections.join('\n\n')}`);
+            // Guidelines section
+            if (docs) {
+                const guideSubSections = [];
+                const useCases = extractSection(docs, 'Common Use Cases');
+                if (useCases)
+                    guideSubSections.push(`### Use Cases\n\n${useCases}`);
+                const guidelines = extractSection(docs, 'Usage Guidelines');
+                if (guidelines)
+                    guideSubSections.push(`### Rules\n\n${promoteSubheadings(guidelines)}`);
+                const accessibility = extractSection(docs, 'Accessibility Information');
+                if (accessibility)
+                    guideSubSections.push(`### Accessibility\n\n${accessibility}`);
+                if (guideSubSections.length)
+                    sections.push(`## Guidelines\n\n${guideSubSections.join('\n\n')}`);
+            }
+            // Related Templates
+            if (relatedTemplates.length) {
+                sections.push(`### Related Templates\n\n${relatedTemplates.map(t => `- ${t}`).join('\n')}\n\nUse the templates tool (with \`template\` arg) to retrieve the full code for any of these templates.`);
+            }
+            await fs.writeFile(join(styleDir, 'info.md'), sections.join('\n\n'));
+            // Remove intermediate JSON
+            await fs.unlink(join(stylesPath, file)).catch(() => null);
+        }));
+        spinner.succeed('Style subdirectories finalised.');
+    }
+    catch (error) {
+        spinner.fail(`Failed to generate templates metadata. Error: ${error}`);
+        throw error;
+    }
+};

package/dist/build/tokens.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Sets up all wanted data from the tokens package and adds it to the static metadata.
+ */
+export declare const buildTokens: () => Promise<void>;

package/dist/build/tokens.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs/promises';
+import { rmSync } from 'node:fs';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import { globby } from 'globby';
+import ora from 'ora';
+import { createPath, tokensPath } from '../utilities/index.js';
+/**
+ * Minimal list of token metadata files to copy.
+ * Keep only essential docs; token/theme indexes are generated as compact JSON.
+ */
+const filesToCopy = [];
+const extractTokenNamesFromTailwind = (content) => {
+    const themeMatch = content.match(/@theme\s+inline\s*\{([\s\S]*?)\n\}/);
+    if (!themeMatch)
+        return [];
+    const themeBlock = themeMatch[1];
+    const propertyNames = [];
+    const propRegex = /^\s*(--[\w\\/.-]+)\s*:/gm;
+    let match;
+    while ((match = propRegex.exec(themeBlock)) !== null) {
+        propertyNames.push(match[1]);
+    }
+    return propertyNames;
+};
+const getAvailableThemes = async (moduleDir) => {
+    const candidates = ['dist/themes', 'themes'];
+    for (const relPath of candidates) {
+        const absPath = path.join(moduleDir, relPath);
+        try {
+            const entries = await fs.readdir(absPath, { withFileTypes: true });
+            const themes = entries
+                .filter(entry => entry.isDirectory())
+                .map(entry => entry.name)
+                .sort();
+            if (themes.length)
+                return themes;
+        }
+        catch {
+            // Try next candidate path.
+        }
+    }
+    return [];
+};
+const readTailwindThemeFile = async (moduleDir) => {
+    const candidates = ['dist/themes/tailwind.css', 'themes/tailwind.css', 'dist/tailwind.css', 'tailwind.css'];
+    for (const relPath of candidates) {
+        try {
+            return await fs.readFile(path.join(moduleDir, relPath), 'utf-8');
+        }
+        catch {
+            // Try next candidate path.
+        }
+    }
+    throw new Error(`Could not find tailwind.css in tokens package. Checked: ${candidates.map(candidate => `'${candidate}'`).join(', ')}`);
+};
+/**
+ * Sets up all wanted data from the tokens package and adds it to the static metadata.
+ */
+export const buildTokens = async () => {
+    const spinner = ora({
+        prefixText: 'Tokens:',
+        text: 'Generating static metadata...'
+    }).start();
+    try {
+        spinner.text = 'Cleaning up old metadata...';
+        rmSync(tokensPath, { recursive: true, force: true });
+        spinner.succeed('Old metadata cleaned up.');
+        spinner.text = 'Creating new metadata directory...';
+        // Create the tokens directory if it doesn't exist
+        await createPath(tokensPath);
+        spinner.succeed('New metadata directory created.');
+        spinner.text = 'Copying files to metadata directory...';
+        // Get the module's root directory
+        // Use dist/theme.js as the resolve anchor (it's a valid export of the package).
+        // dirname gives us dist/, so one '../' reaches the package root.
+        const moduleUrl = import.meta.resolve('@solid-design-system/tokens/dist/theme.js');
+        const modulePath = fileURLToPath(moduleUrl);
+        const moduleDir = path.join(path.dirname(modulePath), '../');
+        // Process the files (placeholder for actual logic)
+        const contents = await globby(filesToCopy, {
+            cwd: moduleDir,
+            onlyFiles: true
+        });
+        // Write files sequentially because multiple theme files share the same basename
+        // (e.g. `icons.css`), and parallel copy operations can corrupt output.
+        for (const file of contents) {
+            const sourcePath = path.join(moduleDir, file);
+            const destPath = path.join(tokensPath, path.basename(file));
+            await fs.copyFile(sourcePath, destPath);
+        }
+        // Persist a compact token index instead of shipping full Tailwind metadata file.
+        const tailwindContent = await readTailwindThemeFile(moduleDir);
+        const tokens = extractTokenNamesFromTailwind(tailwindContent);
+        await fs.writeFile(path.join(tokensPath, 'tokens.json'), JSON.stringify({ tokens }, null, 2));
+        // Persist an explicit list of available themes without copying every theme CSS file.
+        const themes = await getAvailableThemes(moduleDir);
+        await fs.writeFile(path.join(tokensPath, 'themes.json'), JSON.stringify({ themes }, null, 2));
+        spinner.succeed('Tokens metadata generated successfully.');
+    }
+    catch (error) {
+        spinner.fail(`Failed to generate tokens metadata. Error: ${error}`);
+        throw error; // Re-throw to handle it in the calling function
+    }
+};

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Creates a new instance of the MCP server configured for the Solid Design System.
+ * @returns A new instance of the MCP server configured for the Solid Design System.
+ */
+export declare const createServer: () => McpServer;

package/dist/server.js

@@ -0,0 +1,20 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import * as tools from './tools/index.js';
+import { getVersion } from './utilities/version.js';
+/**
+ * Creates a new instance of the MCP server configured for the Solid Design System.
+ * @returns A new instance of the MCP server configured for the Solid Design System.
+ */
+export const createServer = () => {
+    const version = getVersion();
+    const server = new McpServer({
+        description: 'A server for the Solid Design System that provides tools to interact with components and resources.',
+        name: 'solid design system',
+        title: 'Solid Design System MCP Server',
+        version
+    });
+    Object.values(tools).forEach(tool => {
+        tool(server);
+    });
+    return server;
+};

package/dist/tools/components.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Tool: components
+ *
+ * Unified entry point for everything component-related.
+ *
+ * - No args → list all sd-* components + list all package docs topics
+ * - `component` only → full spec (usage guidelines + API)
+ * - `component` + `example` → HTML example for that example
+ * - `doc` → package-level guide (Installation, Localization, Customization, …)
+ */
+export declare const componentsTool: (server: McpServer) => void;

package/dist/tools/components.js

@@ -0,0 +1,175 @@
+import fs from 'node:fs/promises';
+import { join, basename, extname } from 'node:path';
+import { z } from 'zod';
+import { componentPath, componentPackageDocsPath, getAvailableComponents } from '../utilities/index.js';
+import { normalizeSafeSlug } from '../utilities/input.js';
+const readIfExists = async (filePath) => {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+};
+/** Lists all package-level doc slugs (e.g. "installation", "localization"). */
+const getAvailablePackageDocs = async () => {
+    try {
+        const entries = await fs.readdir(componentPackageDocsPath, { withFileTypes: true });
+        return entries
+            .filter(d => d.isFile() && extname(d.name) === '.md')
+            .map(d => basename(d.name, '.md'))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Tool: components
+ *
+ * Unified entry point for everything component-related.
+ *
+ * - No args → list all sd-* components + list all package docs topics
+ * - `component` only → full spec (usage guidelines + API)
+ * - `component` + `example` → HTML example for that example
+ * - `doc` → package-level guide (Installation, Localization, Customization, …)
+ */
+export const componentsTool = (server) => {
+    server.registerTool('components', {
+        description: `Solid Design System components. 
+        - Call without arguments to list all sd-* components and available package docs. 
+        - Pass \`component\` (e.g. "sd-button" or "button") to get the full component specification, including API, events, slots, examples, and guidelines. 
+        - Pass \`component\` + \`example\` (e.g. component="sd-button", example="inverted") to get one HTML usage example. 
+        - Pass \`doc\` (e.g. "localization") to get a package-level guide. 
+        - Do not combine \`doc\` with \`component\` or \`example\`.`,
+        inputSchema: {
+            component: z
+                .string()
+                .optional()
+                .describe('Component tag name (e.g. "sd-button" or "button"). Omit to see the full list.'),
+            example: z
+                .string()
+                .optional()
+                .describe('Slug for an HTML usage example (e.g. "inverted" or "no-shadow"). ' +
+                'Requires `component`. Use component alone first to see available example slugs.'),
+            doc: z
+                .string()
+                .optional()
+                .describe('Package-level guide slug (e.g. "localization", "installation", "customization"). ' +
+                'Omit to see all available topics.')
+        },
+        title: 'Components'
+    }, async ({ component, example, doc }) => {
+        // Validate if doc is combined with component/example - not allowed
+        if (doc && (component || example)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Invalid arguments: `doc` cannot be combined with `component` or `example`. Use either `doc` alone or a component query.'
+                    }
+                ]
+            };
+        }
+        // Validate if `example` is provided without `component` - not allowed
+        if (example && !component) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Invalid arguments: `example` requires `component`. Use both together, e.g. component="sd-button", example="inverted".'
+                    }
+                ]
+            };
+        }
+        // --- package-level doc ---
+        if (doc) {
+            const safeDoc = normalizeSafeSlug(doc);
+            if (!safeDoc) {
+                return {
+                    content: [
+                        { type: 'text', text: 'Invalid arguments: `doc` contains an invalid path. Use a listed doc slug.' }
+                    ]
+                };
+            }
+            const content = await readIfExists(join(componentPackageDocsPath, `${safeDoc}.md`));
+            if (!content) {
+                const available = await getAvailablePackageDocs();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No package doc found for "${safeDoc}". Available docs:\n` + available.map(d => `- ${d}`).join('\n')
+                        }
+                    ]
+                };
+            }
+            return { content: [{ type: 'text', text: content }] };
+        }
+        // --- specific component example (HTML example) ---
+        if (component && example) {
+            component = component.trim().toLowerCase();
+            component = component.startsWith('sd-') ? component : `sd-${component}`;
+            const safeExample = normalizeSafeSlug(example);
+            if (!safeExample) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Invalid arguments: `example` contains an invalid path. Use a listed example slug.'
+                        }
+                    ]
+                };
+            }
+            const exampleMd = await readIfExists(join(componentPath, component, 'stories', `${safeExample}.md`));
+            if (!exampleMd) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No example "${safeExample}" found for "${component}". Use \`component\` alone to see available examples.`
+                        }
+                    ]
+                };
+            }
+            return { content: [{ type: 'text', text: exampleMd }] };
+        }
+        // --- specific component spec ---
+        if (component) {
+            component = component.trim().toLowerCase();
+            component = component.startsWith('sd-') ? component : `sd-${component}`;
+            const infoMd = await readIfExists(join(componentPath, component, 'info.md'));
+            if (!infoMd) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No metadata found for "${component}". Call \`components\` without arguments to see all available components.`
+                        }
+                    ]
+                };
+            }
+            const text = '> IMPORTANT: Only use properties, events and slots listed in the API below.\n' +
+                '> Never invent attributes not present in this specification.\n\n' +
+                infoMd;
+            return { content: [{ type: 'text', text }] };
+        }
+        // --- no args: index ---
+        const [components, packageDocs] = await Promise.all([getAvailableComponents(), getAvailablePackageDocs()]);
+        const text = [
+            '## Solid Design System Components',
+            '',
+            'These are the ONLY valid sd-* components — never invent components not in this list.',
+            'Use `component` to get the full spec for any specific component.',
+            '',
+            components.map(c => (c.description ? `- ${c.name} – ${c.description}` : `- ${c.name}`)).join('\n'),
+            '',
+            '## Package Docs',
+            '',
+            'Use `doc` to retrieve any of the following guides:',
+            '',
+            packageDocs.map(d => `- ${d}`).join('\n')
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+};

package/dist/tools/icon-search.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Tool: icon-search
+ * Searches the Solid Design System icon library by multiple keywords (EN + DE).
+ * Deduplicates and ranks results across all keywords so the LLM can pick the best fit.
+ */
+export declare const iconSearchTool: (server: McpServer) => void;