@solid-design-system/mcp 0.0.1

package/dist/tools/tokens.js

@@ -0,0 +1,198 @@
+import fs from 'node:fs/promises';
+import { join, basename, extname } from 'node:path';
+import { z } from 'zod';
+import { getAvailableTokenThemes, getTailwindThemeTokenNames, tokenPackageDocsPath } from '../utilities/index.js';
+import { normalizeSafeSlug } from '../utilities/input.js';
+const TAILWIND_MAPPING = `
+CSS variable prefix → Tailwind utility
+--background-color-*  →  bg-*
+--text-color-*        →  text-*
+--border-color-*      →  border-*
+--fill-*              →  fill-*
+--outline-color-*     →  outline-*
+--spacing-*           →  p-*, m-*, gap-*, inset-*, …
+--sizing-*            →  w-*, h-*, size-*
+--text-{size}         →  text-{size}
+--font-weight-*       →  font-*
+--border-width-*      →  border-*
+--radius-*            →  rounded-*
+--aspect-*            →  aspect-*
+--opacity-*           →  opacity-*
+--shadow-*            →  shadow-*
+--drop-shadow-*       →  drop-shadow-*
+--transition-duration-*  →  duration-*
+--animate-*           →  animate-*
+`.trim();
+const scoreMatch = (keyword, token) => {
+    const q = keyword.toLowerCase();
+    const t = token.toLowerCase();
+    const normalized = t.replace(/^--/, '');
+    if (t === q || normalized === q)
+        return 100;
+    if (normalized.startsWith(q) || t.startsWith(q))
+        return 80;
+    if (normalized.includes(q) || t.includes(q))
+        return 60;
+    return 0;
+};
+const readIfExists = async (filePath) => {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+};
+/** Lists all package-level token doc slugs (e.g. "installation", "usage"). */
+const getAvailablePackageDocs = async () => {
+    try {
+        const entries = await fs.readdir(tokenPackageDocsPath, { withFileTypes: true });
+        return entries
+            .filter(d => d.isFile() && extname(d.name) === '.md')
+            .map(d => basename(d.name, '.md'))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * 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 const tokenInfoTool = (server) => {
+    server.registerTool('tokens', {
+        description: `Solid Design System tokens. ` +
+            `Call without arguments to list all tokens, usage guidance, and package docs. ` +
+            `Pass \`token\` (e.g. "--background-color-neutral-100" or "background") to search matching tokens. ` +
+            `Pass \`doc\` (e.g. "installation" or "usage") to get a package-level guide. ` +
+            `Do not combine \`doc\` with \`token\`.`,
+        inputSchema: {
+            token: z
+                .string()
+                .optional()
+                .describe('Token name or partial token text (e.g. "--background-color-neutral-100" or "spacing").'),
+            doc: z
+                .string()
+                .optional()
+                .describe('Package-level guide slug (e.g. "installation", "usage"). Omit to see available topics.')
+        },
+        title: 'Tokens'
+    }, async ({ token, doc }) => {
+        if (doc && token) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Invalid arguments: `doc` cannot be combined with `token`. Use either `doc` alone or a token query.'
+                    }
+                ]
+            };
+        }
+        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(tokenPackageDocsPath, `${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 }] };
+        }
+        const tokenNames = getTailwindThemeTokenNames();
+        const themes = getAvailableTokenThemes();
+        const packageDocs = await getAvailablePackageDocs();
+        if (!tokenNames.length) {
+            return {
+                content: [
+                    {
+                        text: 'No design tokens found. Token metadata may not be built yet.',
+                        type: 'text'
+                    }
+                ]
+            };
+        }
+        if (token) {
+            const sorted = tokenNames
+                .map(name => ({ token: name, score: scoreMatch(token, name) }))
+                .filter(item => item.score > 0)
+                .sort((a, b) => b.score - a.score || a.token.localeCompare(b.token));
+            if (!sorted.length) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No tokens found matching "${token}".`
+                        }
+                    ]
+                };
+            }
+            const lines = sorted.map(({ token: tokenName }) => `- \`${tokenName}\``);
+            return {
+                content: [
+                    {
+                        text: [
+                            `Found ${sorted.length} token(s) matching "${token}":`,
+                            '',
+                            lines.join('\n'),
+                            '',
+                            'Use Tailwind utility classes directly where available; use CSS variables via `var(--token-name)` in CSS.'
+                        ].join('\n'),
+                        type: 'text'
+                    }
+                ]
+            };
+        }
+        return {
+            content: [
+                {
+                    text: [
+                        `These are the design tokens of the Solid Design System. Each token is available both as a CSS custom property (CSS variable) and as a TailwindCSS utility class.`,
+                        ``,
+                        `## How to use`,
+                        ``,
+                        `### TailwindCSS (preferred)`,
+                        `Use the semantic Tailwind utility classes directly. Do NOT use arbitrary value syntax like \`bg-[rgb(var(--sd-color-neutral-100))]\` or \`bg-[var(--sd-color-neutral-100)]\`.`,
+                        `Instead, always use the mapped Tailwind class (e.g. \`bg-neutral-100\`).`,
+                        ``,
+                        `### CSS`,
+                        `Use the CSS custom properties via \`var(--property-name)\` (e.g. \`background-color: var(--sd-color-neutral-100)\`).`,
+                        ``,
+                        `## CSS variable → Tailwind utility mapping`,
+                        ``,
+                        TAILWIND_MAPPING,
+                        ``,
+                        `## Available tokens (CSS variable names)`,
+                        ``,
+                        tokenNames.join('\n'),
+                        ``,
+                        `## Available Themes`,
+                        ``,
+                        themes.length ? themes.map(theme => `- ${theme}`).join('\n') : '- none found',
+                        ``,
+                        `## Package Docs`,
+                        ``,
+                        `Use \`doc\` to retrieve any of the following guides:`,
+                        ``,
+                        packageDocs.map(d => `- ${d}`).join('\n')
+                    ].join('\n'),
+                    type: 'text'
+                }
+            ]
+        };
+    });
+};

package/dist/tools/version.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Tool to get version information about the Solid Design System MCP Server.
+ * This allows LLMs to query the current version and basic information about this MCP server.
+ * @param server - The MCP server instance to register the tool on.
+ */
+export declare const versionTool: (server: McpServer) => void;

package/dist/tools/version.js

@@ -0,0 +1,50 @@
+import { getPackageInfo } from '../utilities/version.js';
+/**
+ * Tool to get version information about the Solid Design System MCP Server.
+ * This allows LLMs to query the current version and basic information about this MCP server.
+ * @param server - The MCP server instance to register the tool on.
+ */
+export const versionTool = (server) => {
+    server.registerTool('version', {
+        description: 'Get version and basic information about the Solid Design System MCP Server.',
+        inputSchema: {},
+        title: 'Solid MCP Version Information'
+    }, 
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async () => {
+        const packageJson = getPackageInfo();
+        const versionInfo = {
+            author: packageJson.author,
+            description: packageJson.description,
+            homepage: packageJson.homepage,
+            license: packageJson.license,
+            name: packageJson.name,
+            repository: packageJson.repository,
+            version: packageJson.version
+        };
+        return {
+            content: [
+                {
+                    text: `Solid Design System MCP Server Information:
+              **Version:** ${versionInfo.version}
+              **Name:** ${versionInfo.name}
+              **Description:** ${versionInfo.description}
+
+              **Author:** ${versionInfo.author?.name || 'N/A'}
+              **License:** ${versionInfo.license || 'N/A'}
+              **Repository:** ${versionInfo.repository?.url || 'N/A'}
+              **Homepage:** ${versionInfo.homepage || 'N/A'}
+
+              This MCP server provides tools to interact with the Solid Design System, including:
+              - Component information and documentation
+              - Design tokens and styling information
+              - CSS utility styles information
+              - Template and pattern information
+
+              For more information about available tools, you can explore the other MCP tools provided by this server.`,
+                    type: 'text'
+                }
+            ]
+        };
+    });
+};

package/dist/utilities/components.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Get a list of all available components in the Solid Design System.
+ * @returns A list of all sd-* tag names with built metadata.
+ */
+export declare const getAvailableComponents: () => Promise<{
+    name: string;
+    description: string;
+}[]>;

package/dist/utilities/components.js

@@ -0,0 +1,24 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { componentPath } from './config.js';
+function extractDescription(infoContent) {
+    const match = infoContent.match(/`<[^>]+>`\s*[\u2014\u2013-]+\s*(.+)/);
+    if (match)
+        return match[1].trim();
+    return '';
+}
+/**
+ * Get a list of all available components in the Solid Design System.
+ * @returns A list of all sd-* tag names with built metadata.
+ */
+export const getAvailableComponents = async () => {
+    const entries = await fs.readdir(componentPath, { withFileTypes: true });
+    const dirs = entries
+        .filter(d => d.isDirectory() && d.name.startsWith('sd-'))
+        .map(d => d.name)
+        .sort();
+    return Promise.all(dirs.map(async (name) => {
+        const infoMd = await fs.readFile(join(componentPath, name, 'info.md'), 'utf-8').catch(() => '');
+        return { name, description: extractDescription(infoMd) };
+    }));
+};

package/dist/utilities/config.d.ts

@@ -0,0 +1,40 @@
+/** Base metadata directory */
+export declare const metaDataPath: string;
+/**
+ * Components package metadata — one sub-directory per sd-* component.
+ * Each component dir contains: docs.md, api.json, templates.json
+ */
+export declare const componentPath: string;
+/** Package-level docs for the components package (Installation, Localization, etc.) */
+export declare const componentPackageDocsPath: string;
+/**
+ * Styles package metadata — one sub-directory per style utility (e.g. sd-chip).
+ * Each style dir contains: docs.md, classes.txt
+ */
+export declare const stylesPath: string;
+/** Package-level docs for the styles package (Installation, Usage, etc.) */
+export declare const stylePackageDocsPath: string;
+/** Package-level docs for quickstart entrypoint */
+export declare const quickstartPackageDocsPath: string;
+/**
+ * Templates package metadata — one sub-directory per template (e.g. button, forms).
+ * Each template dir contains: stories.ts, components.json
+ */
+export declare const templatesPackagePath: string;
+/** Tokens package metadata */
+export declare const tokensPath: string;
+/** Icons package metadata */
+export declare const iconsPath: string;
+/** Docs package source stories (MD/MDX) */
+export declare const docsSourceStoriesPath: string;
+/** Docs package generated markdown metadata */
+export declare const docsPackagePath: string;
+/** Package-level docs for the tokens package (Installation, Usage, etc.) */
+export declare const tokenPackageDocsPath: string;
+/** Root of all static AI-rule markdown files */
+export declare const staticPath: string;
+/** Static AI rules for styles */
+export declare const staticStylesPath: string;
+/** Static AI rules for templates */
+export declare const templatesPath: string;
+export type Framework = 'vanilla';

package/dist/utilities/config.js

@@ -0,0 +1,44 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// Get the current file's directory
+const currentFilename = fileURLToPath(import.meta.url);
+const currentDirname = dirname(currentFilename);
+/** Base metadata directory */
+export const metaDataPath = join(currentDirname, '../../metadata');
+/**
+ * Components package metadata — one sub-directory per sd-* component.
+ * Each component dir contains: docs.md, api.json, templates.json
+ */
+export const componentPath = join(currentDirname, '../../metadata/packages/components');
+/** Package-level docs for the components package (Installation, Localization, etc.) */
+export const componentPackageDocsPath = join(currentDirname, '../../metadata/packages/components/docs');
+/**
+ * Styles package metadata — one sub-directory per style utility (e.g. sd-chip).
+ * Each style dir contains: docs.md, classes.txt
+ */
+export const stylesPath = join(currentDirname, '../../metadata/packages/styles');
+/** Package-level docs for the styles package (Installation, Usage, etc.) */
+export const stylePackageDocsPath = join(currentDirname, '../../metadata/packages/styles/docs');
+/** Package-level docs for quickstart entrypoint */
+export const quickstartPackageDocsPath = join(currentDirname, '../../metadata/packages/quickstart/docs');
+/**
+ * Templates package metadata — one sub-directory per template (e.g. button, forms).
+ * Each template dir contains: stories.ts, components.json
+ */
+export const templatesPackagePath = join(currentDirname, '../../metadata/packages/templates');
+/** Tokens package metadata */
+export const tokensPath = join(currentDirname, '../../metadata/packages/tokens');
+/** Icons package metadata */
+export const iconsPath = join(currentDirname, '../../metadata/packages/icons');
+/** Docs package source stories (MD/MDX) */
+export const docsSourceStoriesPath = join(currentDirname, '../../../docs/src/stories');
+/** Docs package generated markdown metadata */
+export const docsPackagePath = join(currentDirname, '../../metadata/packages/docs');
+/** Package-level docs for the tokens package (Installation, Usage, etc.) */
+export const tokenPackageDocsPath = join(currentDirname, '../../metadata/packages/tokens/docs');
+/** Root of all static AI-rule markdown files */
+export const staticPath = join(currentDirname, '../../metadata/static');
+/** Static AI rules for styles */
+export const staticStylesPath = join(currentDirname, '../../metadata/static/styles');
+/** Static AI rules for templates */
+export const templatesPath = join(currentDirname, '../../metadata/static/templates');

package/dist/utilities/file.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Get the absolute path to the wanted file or directory, relative from the current one.
+ * @param path - The relative path to the file or directory.
+ * @returns The absolute path to the file or directory.
+ */
+export declare const getAbsolutePath: (fileName?: string) => string;
+/**
+ * Create a new directory.
+ * @param dirName - The name of the directory to create, relative to the current file.
+ * @returns The absolute path to the created directory.
+ */
+export declare const createPath: (dirName: string) => Promise<string>;

package/dist/utilities/file.js

@@ -0,0 +1,28 @@
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs/promises';
+/**
+ * Get the absolute path to the wanted file or directory, relative from the current one.
+ * @param path - The relative path to the file or directory.
+ * @returns The absolute path to the file or directory.
+ */
+export const getAbsolutePath = (fileName = '') => {
+    const filename = fileURLToPath(import.meta.url);
+    const dirname = path.dirname(filename);
+    return path.isAbsolute(fileName) ? fileName : path.resolve(dirname, fileName);
+};
+/**
+ * Create a new directory.
+ * @param dirName - The name of the directory to create, relative to the current file.
+ * @returns The absolute path to the created directory.
+ */
+export const createPath = async (dirName) => {
+    const absolutePath = getAbsolutePath(dirName);
+    try {
+        await fs.mkdir(absolutePath, { recursive: true });
+    }
+    catch (error) {
+        console.error(`Failed to create directory at ${absolutePath}:`, error);
+    }
+    return absolutePath;
+};

package/dist/utilities/index.d.ts

@@ -0,0 +1,10 @@
+export * from './components.js';
+export * from './config.js';
+export * from './file.js';
+export * from './input.js';
+export * from './metadata.js';
+export * from './stdio.js';
+export * from './styles.js';
+export * from './templates.js';
+export * from './tokens.js';
+export * from './version.js';

package/dist/utilities/index.js

@@ -0,0 +1,10 @@
+export * from './components.js';
+export * from './config.js';
+export * from './file.js';
+export * from './input.js';
+export * from './metadata.js';
+export * from './stdio.js';
+export * from './styles.js';
+export * from './templates.js';
+export * from './tokens.js';
+export * from './version.js';

package/dist/utilities/input.d.ts

@@ -0,0 +1,9 @@
+/** Trim leading/trailing slashes from a slug-like value. */
+export declare const trimSlashes: (value: string) => string;
+/**
+ * Validates a path-like slug made of one or multiple segments.
+ * Prevents path traversal and null-byte based bypasses.
+ */
+export declare const isSafePathSlug: (value: string) => boolean;
+/** Normalizes and validates a user-provided slug. Returns null if invalid. */
+export declare const normalizeSafeSlug: (value: string) => string | null;

package/dist/utilities/input.js

@@ -0,0 +1,19 @@
+const INVALID_SEGMENTS = new Set(['.', '..']);
+/** Trim leading/trailing slashes from a slug-like value. */
+export const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, '');
+/**
+ * Validates a path-like slug made of one or multiple segments.
+ * Prevents path traversal and null-byte based bypasses.
+ */
+export const isSafePathSlug = (value) => {
+    const parts = value.split('/').filter(Boolean);
+    return parts.length > 0 && parts.every(part => !INVALID_SEGMENTS.has(part) && !part.includes('\0'));
+};
+/** Normalizes and validates a user-provided slug. Returns null if invalid. */
+export const normalizeSafeSlug = (value) => {
+    const normalized = trimSlashes(value.trim());
+    if (!normalized || !isSafePathSlug(normalized)) {
+        return null;
+    }
+    return normalized;
+};

package/dist/utilities/metadata.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Filter function type for filtering metadata files.
+ */
+export type Filter = (fileName: string) => boolean;
+/**
+ * MetadataFile type representing a structured metadata file.
+ */
+export interface MetadataFile {
+    content: string;
+    filename: string;
+}
+/**
+ * Get structured metadata for a specific metadata folder.
+ * Will NOT crawl recursively, but will return all files in the metadata directory.
+ * @param folder - The name of the folder to get metadata for.
+ * @param filter - Optional filter function to apply to the filenames.
+ *                 If provided, only files that pass the filter will be included in the result.
+ */
+export declare const getStructuredMetaData: (folder: string, filter?: Filter) => Promise<({
+    content: string;
+    filename: string;
+} | null)[]>;
+/**
+ * Get structured metadata for a specific component.
+ * Will NOT crawl recursively, but will return all files in the component's metadata directory.
+ * @param componentName - The name of the component to get metadata for.
+ * @param filter - Optional filter function to apply to the filenames.
+ *                 If provided, only files that pass the filter will be included in the result.
+ */
+export declare const getStructuredMetaDataForComponent: (componentName: string, filter?: Filter) => Promise<({
+    content: string;
+    filename: string;
+} | null)[]>;

package/dist/utilities/metadata.js

@@ -0,0 +1,55 @@
+import fs from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { componentPath } from './config.js';
+import { getAbsolutePath } from './file.js';
+const defaultFilter = () => true;
+/**
+ * Get structured metadata for a specific metadata folder.
+ * Will NOT crawl recursively, but will return all files in the metadata directory.
+ * @param folder - The name of the folder to get metadata for.
+ * @param filter - Optional filter function to apply to the filenames.
+ *                 If provided, only files that pass the filter will be included in the result.
+ */
+export const getStructuredMetaData = async (folder, filter = defaultFilter) => {
+    const absolutePath = getAbsolutePath(folder);
+    // If the directory does not exist, return an empty array
+    if (!existsSync(absolutePath)) {
+        return [];
+    }
+    const files = await fs.readdir(absolutePath);
+    const metadata = await Promise.all(files
+        .filter(file => {
+        // We only allow entries that are
+        // 1. are files
+        // 2. pass the filter function
+        const stats = statSync(join(absolutePath, file));
+        return stats.isFile() && filter(file);
+    })
+        .map(async (file) => {
+        const filename = basename(file);
+        const exists = await fs.stat(`${absolutePath}/${file}`);
+        if (!exists.isFile()) {
+            return null;
+        }
+        const content = await fs.readFile(`${absolutePath}/${file}`, 'utf-8');
+        return {
+            content,
+            filename
+        };
+    })
+        // Makes sure we only return valid metadata files
+        .filter(Boolean));
+    return metadata;
+};
+/**
+ * Get structured metadata for a specific component.
+ * Will NOT crawl recursively, but will return all files in the component's metadata directory.
+ * @param componentName - The name of the component to get metadata for.
+ * @param filter - Optional filter function to apply to the filenames.
+ *                 If provided, only files that pass the filter will be included in the result.
+ */
+export const getStructuredMetaDataForComponent = (componentName, filter = defaultFilter) => {
+    const absolutePath = getAbsolutePath(`${componentPath}/${componentName}`);
+    return getStructuredMetaData(absolutePath, filter);
+};

package/dist/utilities/stdio.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses command line arguments and returns the action to take
+ */
+export declare const parseCommandLineArgs: (args?: string[]) => {
+    action: "version";
+} | {
+    action: "help";
+} | {
+    action: "continue";
+};
+/**
+ * Handles command line arguments and exits if necessary
+ */
+export declare const handleCommandLineArgs: () => void;

package/dist/utilities/stdio.js

@@ -0,0 +1,57 @@
+import { getVersion } from './version.js';
+/**
+ * Parses command line arguments and returns the action to take
+ */
+export const parseCommandLineArgs = (args = process.argv.slice(2)) => {
+    if (args.includes('--version') || args.includes('-v')) {
+        return { action: 'version' };
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        return { action: 'help' };
+    }
+    return { action: 'continue' };
+};
+/**
+ * Handles command line arguments and exits if necessary
+ */
+export const handleCommandLineArgs = () => {
+    const result = parseCommandLineArgs();
+    if (result.action === 'version') {
+        const version = getVersion();
+        process.stdout.write(`Solid Design System MCP Server v${version}\n`);
+        process.exit(0);
+    }
+    if (result.action === 'help') {
+        const version = getVersion();
+        process.stdout.write(`Solid Design System MCP Server v${version}
+
+USAGE:
+    solid-mcp [OPTIONS]
+
+DESCRIPTION:
+    Model Context Protocol (MCP) server for the Solid Design System.
+    Provides tools for LLMs to interact with Solid components, design tokens,
+    styles, and template guidance.
+
+OPTIONS:
+    -h, --help       Show this help message and exit
+    -v, --version    Show version information and exit
+
+EXAMPLES:
+    solid-mcp                    # Start the MCP server
+    solid-mcp --version          # Show version
+    solid-mcp --help             # Show this help
+
+ABOUT:
+    This server provides the following tools for LLMs:
+    • Component information and documentation
+    • Design tokens and styling information
+    • Template and pattern information
+
+    For more information, visit:
+    https://github.com/solid-design-system/solid
+
+`);
+        process.exit(0);
+    }
+};

package/dist/utilities/styles.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Get a list of all available style utilities in the Solid Design System.
+ * @returns Sorted list of style entries (name + description).
+ */
+export declare const getAvailableStyles: () => Promise<{
+    name: string;
+    description: string;
+}[]>;
+/**
+ * Get info for a specific style utility.
+ * @param name Style name with or without the "sd-" prefix.
+ */
+export declare const getStyleInfo: (name: string) => Promise<{
+    docs: string | null;
+    classes: string[];
+}>;