@solid-design-system/mcp 0.0.1

package/dist/tools/icon-search.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { iconsPath } from '../utilities/index.js';
+const categoriesByLibrary = {
+    default: ['content', 'system'],
+    'sd-multi-theming': ['content', 'system'],
+    'sd-status-assets': ['status']
+};
+const loadIcons = async (library, category) => {
+    const load = async (cat) => {
+        try {
+            const filePath = join(iconsPath, library, `${cat}.json`);
+            const raw = await fs.readFile(filePath, 'utf-8');
+            const icons = JSON.parse(raw);
+            return icons.map(icon => ({ name: `${cat}/${icon.technicalId}`, icon }));
+        }
+        catch {
+            return [];
+        }
+    };
+    const cats = categoriesByLibrary[library];
+    if (category === 'all') {
+        const loaded = await Promise.all(cats.map(load));
+        return loaded.flat();
+    }
+    if (!cats.includes(category)) {
+        return [];
+    }
+    return load(category);
+};
+/**
+ * Scores how well a single keyword matches an icon entry.
+ * Higher = better match.
+ */
+const scoreMatch = (keyword, entry) => {
+    const q = keyword.toLowerCase();
+    const { technicalId, displayNameDe, tags } = entry.icon;
+    if (technicalId === q)
+        return 100;
+    if (technicalId.includes(q))
+        return 80;
+    if (displayNameDe.toLowerCase().includes(q))
+        return 60;
+    if (tags.some(t => t.toLowerCase().includes(q)))
+        return 40;
+    return 0;
+};
+/**
+ * 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 const iconSearchTool = (server) => {
+    server.registerTool('icon-search', {
+        description: `Solid Design System icon libraries search by keywords.
+        - Pass multiple keywords, English and/or German synonyms, to find icons.
+        - Returns icon names in the exact format for <sd-icon name="..."> (e.g. "system/download").
+        - Choose a library: \`default\` (default library), \`sd-status-assets\`, or \`sd-multi-theming\`.
+        - Choose a category, where applicable: \`content\` (illustrative), \`system\` (UI/navigation), \`status\` (status indicators), or \`all\`.
+        - Use the icon documentation tool if you need guidance on when to use each library or category.`,
+        inputSchema: {
+            keywords: z
+                .array(z.string().min(1))
+                .default([])
+                .describe('One or more search keywords in English and/or German. ' +
+                'Example: ["download", "herunterladen", "save", "speichern"]. ' +
+                'Prefer 3-6 synonyms across both languages for best results.'),
+            library: z
+                .enum(['default', 'sd-status-assets', 'sd-multi-theming'])
+                .default('default')
+                .describe('Icon library to search: "default" (default library), "sd-status-assets" (status indicators for components like sd-status-badge), or "sd-multi-theming" (multi-theme compatible icons).'),
+            category: z
+                .enum(['content', 'system', 'status', 'all'])
+                .default('all')
+                .describe(`Search scope within the selected library:
+            - \`default\`: \`content\` or \`system\`
+            - \`sd-multi-theming\`: \`content\` or \`system\`
+            - \`sd-status-assets\`: \`status\`
+            - \`all\` searches all categories available for the selected library.`)
+        },
+        title: 'Icon search'
+    }, async ({ keywords, library = 'default', category = 'all' }) => {
+        if (!keywords.length) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Please provide at least one keyword to search for icons.'
+                    }
+                ]
+            };
+        }
+        const selectedLibrary = library;
+        const allowedCategories = categoriesByLibrary[selectedLibrary];
+        if (category !== 'all' && !allowedCategories.includes(category)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Invalid category "${category}" for library "${library}". ` +
+                            `Allowed categories: ${allowedCategories.map(c => `"${c}"`).join(', ')} or "all".`
+                    }
+                ]
+            };
+        }
+        let all;
+        try {
+            all = await loadIcons(selectedLibrary, category);
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Unable to load icons from library "${library}". Try library="default" or use the icons documentation tool.`
+                    }
+                ]
+            };
+        }
+        if (!all.length) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No icons found in library "${library}"${category !== 'all' ? ` category "${category}"` : ''}. The library may be empty or icon metadata may not be populated yet.`
+                    }
+                ]
+            };
+        }
+        // Collect best score and matched keywords per icon
+        const resultMap = new Map();
+        for (const keyword of keywords) {
+            for (const entry of all) {
+                const score = scoreMatch(keyword, entry);
+                if (score === 0)
+                    continue;
+                const existing = resultMap.get(entry.name);
+                if (existing) {
+                    existing.bestScore = Math.max(existing.bestScore, score);
+                    if (!existing.matchedBy.includes(keyword))
+                        existing.matchedBy.push(keyword);
+                }
+                else {
+                    resultMap.set(entry.name, { entry, bestScore: score, matchedBy: [keyword] });
+                }
+            }
+        }
+        if (!resultMap.size) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No icons found matching any of: ${keywords.map(k => `"${k}"`).join(', ')}` +
+                            (category !== 'all' ? ` in category "${category}"` : '') +
+                            '.'
+                    }
+                ]
+            };
+        }
+        const sorted = [...resultMap.values()].sort((a, b) => {
+            // Primary: best score descending; secondary: more keyword matches first
+            if (b.bestScore !== a.bestScore)
+                return b.bestScore - a.bestScore;
+            return b.matchedBy.length - a.matchedBy.length;
+        });
+        const lines = sorted.map(({ entry, matchedBy }) => {
+            const { displayNameDe, tags } = entry.icon;
+            const tagStr = tags.length ? ` — tags: ${tags.slice(0, 3).join(', ')}` : '';
+            const matchStr = matchedBy.length > 1 ? ` [matched: ${matchedBy.join(', ')}]` : '';
+            return `- \`${entry.name}\`  ${displayNameDe}${tagStr}${matchStr}`;
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${sorted.length} icon(s) across keywords ${keywords.map(k => `"${k}"`).join(', ')}:\n\n` +
+                        lines.join('\n') +
+                        '\n\nUse the name value directly in <sd-icon name="...">.'
+                }
+            ]
+        };
+    });
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,7 @@
+export * from './quickstart.js';
+export * from './components.js';
+export * from './icon-search.js';
+export * from './styles.js';
+export * from './templates.js';
+export * from './tokens.js';
+export * from './version.js';

package/dist/tools/index.js

@@ -0,0 +1,7 @@
+export * from './quickstart.js';
+export * from './components.js';
+export * from './icon-search.js';
+export * from './styles.js';
+export * from './templates.js';
+export * from './tokens.js';
+export * from './version.js';

package/dist/tools/quickstart.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const quickstartTool: (server: McpServer) => void;

package/dist/tools/quickstart.js

@@ -0,0 +1,104 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { componentPackageDocsPath, quickstartPackageDocsPath, stylePackageDocsPath, tokenPackageDocsPath } from '../utilities/index.js';
+const QUICKSTART_DOCS = [
+    { slug: 'Quickstart', filePath: join(quickstartPackageDocsPath, 'quickstart.md') },
+    { slug: 'components/Installation', filePath: join(componentPackageDocsPath, 'installation.md') },
+    { slug: 'components/Usage', filePath: join(componentPackageDocsPath, 'usage.md') },
+    { slug: 'styles/Installation', filePath: join(stylePackageDocsPath, 'installation.md') },
+    { slug: 'styles/Usage', filePath: join(stylePackageDocsPath, 'usage.md') },
+    { slug: 'tokens/Installation', filePath: join(tokenPackageDocsPath, 'installation.md') },
+    { slug: 'tokens/Usage', filePath: join(tokenPackageDocsPath, 'usage.md') }
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, '');
+const isSafePath = (value) => {
+    const parts = value.split('/').filter(Boolean);
+    return parts.length > 0 && parts.every(part => part !== '.' && part !== '..' && !part.includes('\0'));
+};
+const readIfExists = async (filePath) => {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+};
+/** Extract the first H1 heading from raw MDX, falling back to the slug basename. */
+const extractHeading = (raw, fallback) => {
+    const match = raw.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : fallback;
+};
+async function discoverDocs() {
+    const entries = [];
+    for (const source of QUICKSTART_DOCS) {
+        const content = await readIfExists(source.filePath);
+        if (!content)
+            continue;
+        entries.push({
+            slug: source.slug,
+            filePath: source.filePath,
+            description: extractHeading(content, source.slug)
+        });
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export const quickstartTool = (server) => {
+    server.registerTool('quickstart', {
+        title: 'Quick Start',
+        description: `Solid Design System quick-start documentation. 
+        - Call without arguments to list available docs. 
+        - Pass \`doc\` to retrieve one quick-start page.`,
+        inputSchema: {
+            doc: z.string().optional().describe('Documentation name. Omit to see the full list.')
+        }
+    }, async ({ doc }) => {
+        const docs = await discoverDocs();
+        if (!doc) {
+            if (docs.length === 0) {
+                return { content: [{ type: 'text', text: 'No quick-start docs found.' }] };
+            }
+            const lines = ['## Available Quick Start Docs', ''];
+            for (const item of docs) {
+                lines.push(`- ${item.slug}`);
+            }
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        const normalizedDoc = trimSlashes(doc);
+        if (!normalizedDoc) {
+            return {
+                content: [{ type: 'text', text: '`doc` must not be empty. Omit it to list available slugs.' }]
+            };
+        }
+        if (!isSafePath(normalizedDoc)) {
+            return {
+                content: [{ type: 'text', text: '`doc` contains an invalid path. Use a listed slug.' }]
+            };
+        }
+        const selectedDoc = docs.find(item => item.slug.toLowerCase() === normalizedDoc.toLowerCase());
+        if (!selectedDoc) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No documentation found for "${doc}". Available slugs:\n` +
+                            docs.map(item => `- ${item.slug}`).join('\n')
+                    }
+                ]
+            };
+        }
+        const content = await readIfExists(selectedDoc.filePath);
+        if (!content) {
+            return {
+                content: [{ type: 'text', text: `Unable to read documentation for "${selectedDoc.slug}".` }]
+            };
+        }
+        return { content: [{ type: 'text', text: content }] };
+    });
+};

package/dist/tools/styles.d.ts

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

package/dist/tools/styles.js

@@ -0,0 +1,167 @@
+import fs from 'node:fs/promises';
+import { join, basename, extname } from 'node:path';
+import { z } from 'zod';
+import { stylesPath, stylePackageDocsPath, getAvailableStyles } 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", "usage"). */
+const getAvailablePackageDocs = async () => {
+    try {
+        const entries = await fs.readdir(stylePackageDocsPath, { withFileTypes: true });
+        return entries
+            .filter(d => d.isFile() && extname(d.name) === '.md')
+            .map(d => basename(d.name, '.md'))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Tool: styles
+ *
+ * Unified entry point for everything styles-related.
+ *
+ * - No args → list all style utilities + list all package docs topics
+ * - `style` only → full spec (usage guidelines + class names)
+ * - `style` + `example` → HTML example for that story
+ * - `doc` → package-level guide (Installation, Usage, …)
+ */
+export const stylesTool = (server) => {
+    server.registerTool('styles', {
+        description: `Solid Design System CSS style utilities. 
+        - Call without arguments to list all style utilities and available package docs. 
+        - Pass \`style\` (e.g. "sd-chip" or "chip") to get the full specification, including guidelines and class names. 
+        - Pass \`style\` + \`example\` (e.g. style="sd-chip", example="inverted") to get one HTML usage example. 
+        - Pass \`doc\` (e.g. "installation") to get a package-level guide. 
+        - Do not combine \`doc\` with \`style\` or \`example\`.`,
+        inputSchema: {
+            style: z.string().optional().describe('Style name (e.g. "sd-chip" or "chip"). Omit to see all.'),
+            example: z
+                .string()
+                .optional()
+                .describe('Example slug for an HTML usage example (e.g. "inverted" or "size"). ' +
+                'Requires `style`. Use `style` alone first to see available slugs.'),
+            doc: z
+                .string()
+                .optional()
+                .describe('Package-level guide slug (e.g. "installation", "usage"). Omit to see all available topics.')
+        },
+        title: 'Styles'
+    }, async ({ style, example, doc }) => {
+        // Validate if doc is combined with style/example - not allowed
+        if (doc && (style || example)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Invalid arguments: `doc` cannot be combined with `style` or `example`. Use either `doc` alone or a style query.'
+                    }
+                ]
+            };
+        }
+        // Validate if `example` is provided without `style` - not allowed
+        if (example && !style) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Invalid arguments: `example` requires `style`. Use both together, e.g. style="sd-chip", 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(stylePackageDocsPath, `${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 style story (HTML example) ---
+        if (style && example) {
+            style = style.trim().toLowerCase();
+            style = style.startsWith('sd-') ? style : `sd-${style}`;
+            const safeExample = normalizeSafeSlug(example);
+            if (!safeExample) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Invalid arguments: `example` contains an invalid path. Use a listed example slug.'
+                        }
+                    ]
+                };
+            }
+            const storyMd = await readIfExists(join(stylesPath, style, 'stories', `${safeExample}.md`));
+            if (!storyMd) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No example "${safeExample}" found for "${style}". Use \`style\` alone to see available examples.`
+                        }
+                    ]
+                };
+            }
+            return { content: [{ type: 'text', text: storyMd }] };
+        }
+        // --- specific style spec ---
+        if (style) {
+            style = style.trim().toLowerCase();
+            style = style.startsWith('sd-') ? style : `sd-${style}`;
+            const infoMd = await readIfExists(join(stylesPath, style, 'info.md'));
+            if (!infoMd) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No metadata found for "${style}". Call \`styles\` without arguments to see all available styles.`
+                        }
+                    ]
+                };
+            }
+            return { content: [{ type: 'text', text: infoMd }] };
+        }
+        // --- no args: index ---
+        const [styles, packageDocs] = await Promise.all([getAvailableStyles(), getAvailablePackageDocs()]);
+        const text = [
+            '## Solid Design System Style Utilities',
+            '',
+            'Use `style` to get the full spec for any specific style utility.',
+            '',
+            styles.map(s => (s.description ? `- ${s.name} – ${s.description}` : `- ${s.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/templates.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Tool: templates
+ *
+ * Unified entry point for all Solid Design System templates.
+ *
+ * - No args → list all templates
+ * - `template` → source code + component inventory for that template
+ * - `component` or `style` → filter the list to templates that use that component/style
+ */
+export declare const templatesTool: (server: McpServer) => void;

package/dist/tools/templates.js

@@ -0,0 +1,146 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { templatesPackagePath } 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;
+    }
+};
+const listTemplateNames = async () => {
+    try {
+        return (await fs.readdir(templatesPackagePath, { withFileTypes: true }))
+            .filter(d => d.isFile() && d.name.endsWith('.md'))
+            .map(d => d.name.replace(/\.md$/, ''))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Tool: templates
+ *
+ * Unified entry point for all Solid Design System templates.
+ *
+ * - No args → list all templates
+ * - `template` → source code + component inventory for that template
+ * - `component` or `style` → filter the list to templates that use that component/style
+ */
+export const templatesTool = (server) => {
+    server.registerTool('templates', {
+        description: `Solid Design System templates — real-world compositions of multiple sd-* components. 
+        - Call without arguments to list all templates. 
+        - Pass \`template\` (e.g. "forms") to get the source code and component inventory for one template. 
+        - Pass \`component\` (e.g. "sd-button" or "button") or \`style\` (e.g. "sd-chip" or "chip") to list templates that use that tag. 
+        - Use either \`component\` or \`style\` for filtering, not both together. 
+        - Do not combine \`template\` with \`component\` or \`style\`.`,
+        inputSchema: {
+            template: z
+                .string()
+                .optional()
+                .describe('Template name as returned by the list (e.g. "forms" or "button"). Omit to list all.'),
+            component: z.string().optional().describe('Optional component tag name (e.g. "sd-button" or "button").'),
+            style: z
+                .string()
+                .optional()
+                .describe('Optional style name to filter the template list (e.g. "sd-chip" or "chip").')
+        },
+        title: 'Templates'
+    }, async ({ template, component, style }) => {
+        // Validate if `template` is combined with `component`/`style` - not allowed
+        if (template && (component || style)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Invalid arguments: `template` cannot be combined with `component` or `style`. Use either `template` alone or a filter query.'
+                    }
+                ]
+            };
+        }
+        // Validate if both `component` and `style` are provided - not allowed
+        if (component && style) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Invalid arguments: `component` and `style` cannot be combined. Use one filter at a time.'
+                    }
+                ]
+            };
+        }
+        // --- specific template ---
+        if (template) {
+            const safeTemplate = normalizeSafeSlug(template);
+            if (!safeTemplate) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Invalid arguments: `template` contains an invalid path. Use a listed template slug.'
+                        }
+                    ]
+                };
+            }
+            const content = await readIfExists(join(templatesPackagePath, `${safeTemplate}.md`));
+            if (!content) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No template found named "${safeTemplate}". Call \`templates\` without arguments to see all available templates.`
+                        }
+                    ]
+                };
+            }
+            return { content: [{ type: 'text', text: content }] };
+        }
+        // --- list (optionally filtered) ---
+        const allNames = await listTemplateNames();
+        if (!allNames.length) {
+            return {
+                content: [{ type: 'text', text: 'Template metadata not yet built. Run build:metadata first.' }]
+            };
+        }
+        const filterTag = component
+            ? (() => {
+                component = component.trim().toLowerCase();
+                return component.startsWith('sd-') ? component : `sd-${component}`;
+            })()
+            : style
+                ? (() => {
+                    style = style.trim().toLowerCase();
+                    return style.startsWith('sd-') ? style : `sd-${style}`;
+                })()
+                : undefined;
+        let entries = allNames;
+        if (filterTag) {
+            const filtered = [];
+            await Promise.all(allNames.map(async (name) => {
+                const raw = await readIfExists(join(templatesPackagePath, `${name}.md`));
+                if (!raw)
+                    return;
+                const yamlMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+                if (yamlMatch) {
+                    const tags = [...yamlMatch[1].matchAll(/^ {2}- (sd-[\w-]+)$/gm)].map(m => m[1]);
+                    if (tags.includes(filterTag))
+                        filtered.push(name);
+                }
+            }));
+            entries = filtered.sort();
+        }
+        if (!entries.length) {
+            const filter = filterTag ? ` that use "${filterTag}"` : '';
+            return { content: [{ type: 'text', text: `No templates found${filter}.` }] };
+        }
+        const header = filterTag ? `Templates that use \`${filterTag}\`:` : 'Available Solid Design System templates:';
+        return {
+            content: [{ type: 'text', text: `${header}\n${entries.map(t => `- ${t}`).join('\n')}` }]
+        };
+    });
+};

package/dist/tools/tokens.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Simple tool to list all available tokens in the Solid Design System.
+ * This tool fetches the token data from the Solid package and formats it for display.
+ * @param server - The MCP server instance to register the tool on.
+ */
+export declare const tokenInfoTool: (server: McpServer) => void;