@synergy-design-system/mcp 0.1.0 → 1.1.0

package/dist/utilities/checksum.js

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { globby } from 'globby';
+/**
+ * Creates a checksum from folder contents, replicating the behavior of:
+ * find ./folder ! -name '.*' ! -name 'checksum.txt' -type f -print0 | sort -z | xargs -0 cat | md5
+ *
+ * @param folderPath - Path to the folder to process
+ * @param options - Configuration options
+ * @returns Promise<string> - The generated checksum
+ */
+export async function createFolderChecksum(folderPath, options = {}) {
+    const { excludePatterns = ['.*', 'checksum.txt'], algorithm = 'md5', } = options;
+    // Use default 'checksum.txt' if outputFile is not specified, but respect explicit undefined
+    const outputFile = 'outputFile' in options ? options.outputFile : 'checksum.txt';
+    try {
+        // Build glob patterns to exclude specified patterns
+        const includePattern = join(folderPath, '**', '*');
+        const excludeGlobs = excludePatterns.map(pattern => join(folderPath, '**', pattern));
+        // Find all files, excluding specified patterns
+        const files = await globby([includePattern], {
+            absolute: true,
+            ignore: excludeGlobs,
+            onlyFiles: true,
+        });
+        // Sort files by their relative paths (to match shell script behavior)
+        const sortedFiles = files.sort((a, b) => {
+            const relativeA = relative(folderPath, a);
+            const relativeB = relative(folderPath, b);
+            return relativeA.localeCompare(relativeB);
+        });
+        // Create hash instance
+        const hash = createHash(algorithm);
+        // Read and concatenate all file contents (equivalent to xargs -0 cat)
+        // Note: Sequential reading to maintain order consistency with shell script
+        // eslint-disable-next-line no-await-in-loop
+        for (const filePath of sortedFiles) {
+            // eslint-disable-next-line no-await-in-loop
+            const content = await readFile(filePath);
+            hash.update(content);
+        }
+        // Generate the final checksum
+        const checksum = hash.digest('hex');
+        // Write checksum to output file if specified
+        if (outputFile) {
+            const outputPath = join(folderPath, outputFile);
+            await writeFile(outputPath, `${checksum}\n`, 'utf8');
+        }
+        return checksum;
+    }
+    catch (error) {
+        throw new Error(`Failed to create folder checksum: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Verifies if the current folder contents match the stored checksum
+ *
+ * @param folderPath - Path to the folder to verify
+ * @param options - Configuration options
+ * @returns Promise<boolean> - True if checksum matches, false otherwise
+ */
+export async function verifyFolderChecksum(folderPath, options = {}) {
+    const { outputFile = 'checksum.txt' } = options;
+    try {
+        // Read stored checksum
+        const checksumPath = join(folderPath, outputFile);
+        const storedChecksum = (await readFile(checksumPath, 'utf8')).trim();
+        // Calculate current checksum (without writing to file)
+        const currentChecksum = await createFolderChecksum(folderPath, {
+            ...options,
+            outputFile: undefined, // Don't write to file during verification
+        });
+        return storedChecksum === currentChecksum;
+    }
+    catch (error) {
+        // If we can't read the checksum file, consider it invalid
+        return false;
+    }
+}
+/**
+ * Get the current checksum without writing it to a file
+ *
+ * @param folderPath - Path to the folder to process
+ * @param options - Configuration options (outputFile will be ignored)
+ * @returns Promise<string> - The generated checksum
+ */
+export async function getFolderChecksum(folderPath, options = {}) {
+    return createFolderChecksum(folderPath, {
+        ...options,
+        outputFile: undefined,
+    });
+}

package/dist/utilities/components.d.ts

@@ -0,0 +1,25 @@
+import { type Framework } from './config.js';
+/**
+ * Get dynamic information about the usage of a specific framework in the Synergy Design System.
+ * @param framework The framework to get information about
+ * @returns List of structured metadata for the specified framework.
+ */
+export declare const getDynamicMetaDataForFramework: (framework?: Framework) => Promise<(import("./metadata.js").MetadataFile | null)[]>;
+/**
+ * Get additional information about the usage of a specific framework in the Synergy Design System.
+ * @param framework The framework to get information about
+ * @returns List of structured metadata for the specified framework.
+ */
+export declare const getStaticMetaDataForFramework: (framework?: Framework) => Promise<(import("./metadata.js").MetadataFile | null)[]>;
+/**
+ * Get information about the usage of a specific component in the Synergy Design System.
+ * @param component The name of the component to get information about, e.g., 'syn-button'.
+ * @param framework The framework to filter the component usage information by.
+ * @returns The structured metadata for the specified component.
+ */
+export declare const getInfoForComponent: (component: string, framework?: Framework) => Promise<(import("./metadata.js").MetadataFile | null)[]>;
+/**
+ * Get a list of all available components in the Synergy Design System.
+ * @returns A list of all available components in the Synergy Design System.
+ */
+export declare const getAvailableComponents: () => Promise<string[]>;

package/dist/utilities/components.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs/promises';
+import { angularPath, componentPath, componentStaticPath, reactPath, staticPath, vuePath, } from './config.js';
+import { getAbsolutePath } from './file.js';
+import { getStructuredMetaData, getStructuredMetaDataForComponent, } from './metadata.js';
+/**
+ * Get dynamic information about the usage of a specific framework in the Synergy Design System.
+ * @param framework The framework to get information about
+ * @returns List of structured metadata for the specified framework.
+ */
+export const getDynamicMetaDataForFramework = async (framework = 'vanilla') => {
+    let frameworkPath;
+    switch (framework) {
+        case 'angular':
+            frameworkPath = angularPath;
+            break;
+        case 'react':
+            frameworkPath = reactPath;
+            break;
+        case 'vue':
+            frameworkPath = vuePath;
+            break;
+        default:
+            frameworkPath = componentStaticPath;
+    }
+    return getStructuredMetaData(frameworkPath);
+};
+/**
+ * Get additional information about the usage of a specific framework in the Synergy Design System.
+ * @param framework The framework to get information about
+ * @returns List of structured metadata for the specified framework.
+ */
+export const getStaticMetaDataForFramework = async (framework = 'vanilla') => {
+    const frameworkPath = framework === 'vanilla' ? 'components' : framework;
+    return getStructuredMetaData(getAbsolutePath(`${staticPath}/${frameworkPath}`));
+};
+/**
+ * Get additional information for a specific component from the static metadata.
+ * @param component The name of the component to get information about, e.g., 'syn-button'.
+ * @returns The structured metadata for the specified component, taken from the static metadata.
+ */
+const getAdditionalInformationForComponent = async (component) => getStructuredMetaDataForComponent(component, undefined, 'static');
+/**
+ * Get information about the usage of a specific component in the Synergy Design System.
+ * @param component The name of the component to get information about, e.g., 'syn-button'.
+ * @param framework The framework to filter the component usage information by.
+ * @returns The structured metadata for the specified component.
+ */
+export const getInfoForComponent = async (component, framework = 'vanilla') => {
+    // Filter function to select specific files based on the framework
+    const namePatterns = [
+        'component.ts',
+        'component.styles.ts',
+        'component.custom.styles.ts',
+    ];
+    switch (framework) {
+        case 'react':
+            namePatterns.push('component.react.ts');
+            break;
+        case 'vue':
+            namePatterns.push('component.vue');
+            break;
+        case 'angular':
+            namePatterns.push('component.angular.ts');
+            break;
+        default:
+    }
+    const finalPattern = namePatterns.map(pattern => pattern.toLowerCase());
+    const data = await getStructuredMetaDataForComponent(component, fileName => finalPattern.some(pattern => fileName.toLowerCase().includes(pattern)));
+    const additionalData = await getAdditionalInformationForComponent(component);
+    return [
+        ...data,
+        ...additionalData,
+    ].filter(Boolean);
+};
+/**
+ * Get a list of all available components in the Synergy Design System.
+ * @returns A list of all available components in the Synergy Design System.
+ */
+export const getAvailableComponents = async () => {
+    const absolutePath = getAbsolutePath(`${componentPath}`);
+    const folders = await fs.readdir(absolutePath, { withFileTypes: true });
+    const components = folders
+        .filter((dirent) => dirent.isDirectory())
+        .map((dirent) => dirent.name);
+    return components;
+};

package/dist/utilities/config.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Path where metadata is stored, relative to the MCP directory.
+ */
+export declare const metaDataPath: string;
+/**
+ * Path to the assets directory, relative to the MCP directory.
+ */
+export declare const assetsPath: string;
+/**
+ * Path to the components base directory, relative to the MCP directory.
+ */
+export declare const componentBasePath: string;
+/**
+ * Path to the components code directory, relative to the MCP directory.
+ */
+export declare const componentPath: string;
+/**
+ * Path to the components static directory, relative to the MCP directory.
+ */
+export declare const componentStaticPath: string;
+/**
+ * Path to the components migration directory, relative to the MCP directory.
+ */
+export declare const componentMigrationPath: string;
+/**
+ * The path where static information about components is stored, relative to the MCP directory.
+ */
+export declare const staticComponentPath: string;
+/**
+ * The path where setup related information is stored.
+ */
+export declare const setupPath: string;
+/**
+ * Path to the styles directory, relative to the MCP directory.
+ */
+export declare const stylesPath: string;
+/**
+ * Path to the angular directory, relative to the MCP directory.
+ */
+export declare const angularPath: string;
+/**
+ * Path to the react directory, relative to the MCP directory.
+ */
+export declare const reactPath: string;
+/**
+ * Path to the vue directory, relative to the MCP directory.
+ */
+export declare const vuePath: string;
+/**
+ * The path where static information about styles is stored, relative to the MCP directory.
+ */
+export declare const staticStylesPath: string;
+/**
+ * Path to the templates directory, relative to the MCP directory.
+ */
+export declare const templatesPath: string;
+/**
+ * Path to the tokens directory, relative to the MCP directory.
+ */
+export declare const tokensPath: string;
+/**
+ * Path to the davinci migration directory, relative to the MCP directory.
+ */
+export declare const davinciMigrationPath: string;
+/**
+ * Path to the static files directory, relative to the MCP directory.
+ */
+export declare const staticPath: string;
+/**
+ * Path to the migration directory, relative to the MCP directory.
+ */
+export declare const staticMigrationPath: string;
+/**
+ * List of supported frameworks.
+ */
+export type Framework = 'react' | 'vue' | 'angular' | 'vanilla';

package/dist/utilities/config.js

@@ -0,0 +1,77 @@
+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);
+/**
+ * Path where metadata is stored, relative to the MCP directory.
+ */
+export const metaDataPath = join(currentDirname, '../../metadata');
+/**
+ * Path to the assets directory, relative to the MCP directory.
+ */
+export const assetsPath = join(currentDirname, '../../metadata/packages/assets');
+/**
+ * Path to the components base directory, relative to the MCP directory.
+ */
+export const componentBasePath = join(currentDirname, '../../metadata/packages/components');
+/**
+ * Path to the components code directory, relative to the MCP directory.
+ */
+export const componentPath = join(componentBasePath, '/components');
+/**
+ * Path to the components static directory, relative to the MCP directory.
+ */
+export const componentStaticPath = join(componentBasePath, '/static');
+/**
+ * Path to the components migration directory, relative to the MCP directory.
+ */
+export const componentMigrationPath = join(componentBasePath, '/migration');
+/**
+ * The path where static information about components is stored, relative to the MCP directory.
+ */
+export const staticComponentPath = join(currentDirname, '../../metadata/static/components');
+/**
+ * The path where setup related information is stored.
+ */
+export const setupPath = join(currentDirname, '../../metadata/static/setup');
+/**
+ * Path to the styles directory, relative to the MCP directory.
+ */
+export const stylesPath = join(currentDirname, '../../metadata/packages/styles');
+/**
+ * Path to the angular directory, relative to the MCP directory.
+ */
+export const angularPath = join(currentDirname, '../../metadata/packages/angular');
+/**
+ * Path to the react directory, relative to the MCP directory.
+ */
+export const reactPath = join(currentDirname, '../../metadata/packages/react');
+/**
+ * Path to the vue directory, relative to the MCP directory.
+ */
+export const vuePath = join(currentDirname, '../../metadata/packages/vue');
+/**
+ * The path where static information about styles is stored, relative to the MCP directory.
+ */
+export const staticStylesPath = join(currentDirname, '../../metadata/static/styles');
+/**
+ * Path to the templates directory, relative to the MCP directory.
+ */
+export const templatesPath = join(currentDirname, '../../metadata/static/templates');
+/**
+ * Path to the tokens directory, relative to the MCP directory.
+ */
+export const tokensPath = join(currentDirname, '../../metadata/packages/tokens');
+/**
+ * Path to the davinci migration directory, relative to the MCP directory.
+ */
+export const davinciMigrationPath = join(currentDirname, '../../metadata/davinci-migration');
+/**
+ * Path to the static files directory, relative to the MCP directory.
+ */
+export const staticPath = join(currentDirname, '../../metadata/static');
+/**
+ * Path to the migration directory, relative to the MCP directory.
+ */
+export const staticMigrationPath = join(currentDirname, '../../metadata/static/migration');

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,31 @@
+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) {
+        // eslint-disable-next-line no-console
+        console.error(`Failed to create directory at ${absolutePath}:`, error);
+    }
+    return absolutePath;
+};

package/dist/utilities/index.d.ts

@@ -0,0 +1,12 @@
+export * from './assets.js';
+export * from './checksum.js';
+export * from './components.js';
+export * from './config.js';
+export * from './file.js';
+export * from './migration.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,12 @@
+export * from './assets.js';
+export * from './checksum.js';
+export * from './components.js';
+export * from './config.js';
+export * from './file.js';
+export * from './migration.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/metadata.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Filter function type for filtering metadata files.
+ */
+export type Filter = (fileName: string) => boolean;
+/**
+ * MetadataFile type representing a structured metadata file.
+ */
+export type 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<(MetadataFile | 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.
+ * @param source - The source of the metadata, either 'package' or 'static'.
+ */
+export declare const getStructuredMetaDataForComponent: (componentName: string, filter?: Filter, source?: "package" | "static") => Promise<(MetadataFile | null)[]>;

package/dist/utilities/metadata.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { componentPath, staticComponentPath } 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.
+ * @param source - The source of the metadata, either 'package' or 'static'.
+ */
+export const getStructuredMetaDataForComponent = (componentName, filter = defaultFilter, source = 'package') => {
+    const root = source === 'static' ? staticComponentPath : componentPath;
+    const absolutePath = getAbsolutePath(`${root}/${componentName}`);
+    return getStructuredMetaData(absolutePath, filter);
+};

package/dist/utilities/migration.d.ts

@@ -0,0 +1 @@
+export declare const getMigrationMetaData: () => Promise<(import("./metadata.js").MetadataFile | null)[]>;

package/dist/utilities/migration.js

@@ -0,0 +1,10 @@
+import { componentMigrationPath, staticMigrationPath, } from './config.js';
+import { getStructuredMetaData, } from './metadata.js';
+export const getMigrationMetaData = async () => {
+    const data = await getStructuredMetaData(componentMigrationPath);
+    const additionalData = await getStructuredMetaData(staticMigrationPath);
+    return [
+        ...data,
+        ...additionalData,
+    ];
+};

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,60 @@
+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(`Synergy Design System MCP Server v${version}\n`);
+        process.exit(0);
+    }
+    if (result.action === 'help') {
+        const version = getVersion();
+        process.stdout.write(`Synergy Design System MCP Server v${version}
+
+USAGE:
+    syn-mcp [OPTIONS]
+
+DESCRIPTION:
+    Model Context Protocol (MCP) server for the Synergy Design System.
+    Provides tools for LLMs to interact with Synergy components, design tokens,
+    styles, and framework-specific guidance.
+
+OPTIONS:
+    -h, --help       Show this help message and exit
+    -v, --version    Show version information and exit
+
+EXAMPLES:
+    syn-mcp                    # Start the MCP server
+    syn-mcp --version          # Show version
+    syn-mcp --help             # Show this help
+
+ABOUT:
+    This server provides the following tools for LLMs:
+    • Component information and documentation
+    • Framework-specific guidance (React, Vue, Angular, Vanilla)
+    • Design tokens and styling information
+    • Asset and icon information
+    • Migration guides from DaVinci to Synergy
+    • Template and pattern information
+
+    For more information, visit:
+    https://github.com/synergy-design-system/synergy-design-system
+
+`);
+        process.exit(0);
+    }
+};

package/dist/utilities/storybook/build-docs.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/utilities/storybook/build-docs.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+import { runDocsScraper } from './docs-scraper.js';
+import { StaticServerManager } from './storybook-manager.js';
+// Parse command line arguments
+const args = process.argv.slice(2);
+const type = args[0] || 'all';
+console.log(`Starting documentation scraping for: ${type}`);
+const serverManager = new StaticServerManager();
+async function main() {
+    try {
+        // Start the static server
+        console.log('Starting static file server...');
+        const server = await serverManager.start();
+        // Run the docs scraper
+        console.log('Starting documentation scraping...');
+        await runDocsScraper(type, server.url);
+        console.log('Documentation scraping completed successfully!');
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Documentation scraping failed:', error);
+        process.exit(1);
+    }
+    finally {
+        // Always clean up the server
+        await serverManager.stop();
+        console.log('✓ Server stopped');
+    }
+}
+// Handle process termination to clean up server
+process.on('SIGINT', async () => {
+    console.log('\nReceived SIGINT, cleaning up...');
+    await serverManager.stop();
+    process.exit(0);
+});
+process.on('SIGTERM', async () => {
+    console.log('\nReceived SIGTERM, cleaning up...');
+    await serverManager.stop();
+    process.exit(0);
+});
+main();

package/dist/utilities/storybook/configs.d.ts

@@ -0,0 +1,13 @@
+import { ScrapingConfig } from './types.js';
+/**
+ * Configuration for scraping component documentation
+ */
+export declare const componentScrapingConfig: ScrapingConfig;
+/**
+ * Configuration for scraping styles documentation
+ */
+export declare const stylesScrapingConfig: ScrapingConfig;
+/**
+ * Configuration for scraping template documentation
+ */
+export declare const templateScrapingConfig: ScrapingConfig;