@synergy-design-system/mcp 2.14.1 → 3.0.0

package/dist/transports/index.js

@@ -0,0 +1,23 @@
+/**
+ * Creates and returns a transport instance based on the runtime configuration.
+ *
+ * For stdio mode, a single server instance is used.
+ * For HTTP mode, the factory is called once per client session so each client
+ * gets an isolated server with its own tool registrations.
+ *
+ * @param serverFactory A factory function that creates a new MCP server instance
+ * @param config The runtime configuration
+ * @returns A transport instance ready to start
+ */
+export async function createTransport(serverFactory, config) {
+    // Determine transport type based on config.interface
+    // Note we have to use dynamic imports here to avoid importing all transport modules upfront,
+    // which can cause issues in certain environments (like when using stdio transport in a CLI tool)
+    if (config.interface === 'http') {
+        const { createHttpTransport } = await import('./http.js');
+        return createHttpTransport(serverFactory, config);
+    }
+    // Default to stdio — create the single server instance here
+    const { createStdioTransport } = await import('./stdio.js');
+    return createStdioTransport(serverFactory());
+}

package/dist/transports/stdio.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { TransportInstance } from './index.js';
+/**
+ * Creates a stdio transport for the MCP server.
+ * Communicates via stdin/stdout with the parent process.
+ *
+ * @param server The MCP server instance
+ * @returns A transport instance
+ */
+export declare function createStdioTransport(server: McpServer): Promise<TransportInstance>;

package/dist/transports/stdio.js

@@ -0,0 +1,21 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { runWithLoggingContext } from '../utilities/logging-context.js';
+/**
+ * Creates a stdio transport for the MCP server.
+ * Communicates via stdin/stdout with the parent process.
+ *
+ * @param server The MCP server instance
+ * @returns A transport instance
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function createStdioTransport(server) {
+    const transport = new StdioServerTransport();
+    return {
+        start: async () => {
+            await runWithLoggingContext({
+                sessionId: 'stdio',
+                transport: 'stdio',
+            }, async () => server.connect(transport));
+        },
+    };
+}

package/dist/types/tool-response.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared types for MCP tool responses.
+ * These are intentionally separated from middleware/metadata utilities to avoid
+ * circular dependencies as different domains (logging, token-counting, response
+ * formatting) need to work with the same response shape.
+ */
+export type ToolResponseContentEntry = {
+    text: string;
+    type: 'text';
+};
+export type ToolResponse = {
+    content: ToolResponseContentEntry[];
+};

package/dist/types/tool-response.js

@@ -0,0 +1,7 @@
+/**
+ * Shared types for MCP tool responses.
+ * These are intentionally separated from middleware/metadata utilities to avoid
+ * circular dependencies as different domains (logging, token-counting, response
+ * formatting) need to work with the same response shape.
+ */
+export {};

package/dist/utilities/cli.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Gets the current version of the MCP server.
+ * @returns The version string from package.json
+ */
+export declare const getVersion: () => string;
+/**
+ * Parsed command line arguments
+ */
+export interface ParsedArgs {
+    action: 'version' | 'help' | 'continue';
+    compression?: 'none' | 'toon';
+    configPath?: string;
+    host?: string;
+    interface?: 'stdio' | 'http';
+    logPath?: string | null;
+    port?: number;
+    tlsKeyPath?: string;
+    tlsCertPath?: string;
+}
+/**
+ * Parses command line arguments and returns the action to take
+ */
+export declare const parseCommandLineArgs: (args?: string[]) => ParsedArgs;
+/**
+ * Handles command line arguments and exits if necessary
+ */
+export declare const handleCommandLineArgs: () => void;

package/dist/utilities/cli.js

@@ -0,0 +1,170 @@
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+/**
+ * Gets the current version of the MCP server.
+ * @returns The version string from package.json
+ */
+export const getVersion = () => {
+    const filename = fileURLToPath(import.meta.url);
+    const directoryName = dirname(filename);
+    const packageJsonPath = join(directoryName, '..', '..', 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    return packageJson.version;
+};
+/**
+ * Parses command line arguments and returns the action to take
+ */
+// eslint-disable-next-line complexity
+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' };
+    }
+    const result = { action: 'continue' };
+    const configIndex = args.indexOf('--config');
+    if (configIndex >= 0 && configIndex + 1 < args.length) {
+        result.configPath = args[configIndex + 1];
+    }
+    const interfaceIndex = args.indexOf('--interface');
+    if (interfaceIndex >= 0 && interfaceIndex + 1 < args.length) {
+        const value = args[interfaceIndex + 1];
+        if (value === 'stdio' || value === 'http') {
+            result.interface = value;
+        }
+        else {
+            throw new Error(`Invalid --interface value: "${value}". Must be "stdio" or "http".`);
+        }
+    }
+    const portIndex = args.indexOf('--port');
+    if (portIndex >= 0 && portIndex + 1 < args.length) {
+        const portValue = args[portIndex + 1];
+        const port = parseInt(portValue, 10);
+        if (Number.isNaN(port) || port < 1 || port > 65535) {
+            throw new Error(`Invalid --port value: "${portValue}". Must be an integer between 1 and 65535.`);
+        }
+        result.port = port;
+    }
+    const hostIndex = args.indexOf('--host');
+    if (hostIndex >= 0 && hostIndex + 1 < args.length) {
+        const hostValue = args[hostIndex + 1]?.trim();
+        if (!hostValue) {
+            throw new Error('Invalid --host value. Must be a non-empty host or IP address.');
+        }
+        result.host = hostValue;
+    }
+    const logIndex = args.indexOf('--log');
+    if (logIndex >= 0 && logIndex + 1 < args.length) {
+        const rawValue = args[logIndex + 1]?.trim();
+        if (!rawValue) {
+            throw new Error('Invalid --log value. Must be a non-empty directory path, "false" or "null".');
+        }
+        const normalized = rawValue.toLowerCase();
+        result.logPath = normalized === 'false' || normalized === 'null'
+            ? null
+            : rawValue;
+    }
+    const tlsKeyIndex = args.indexOf('--tls-key');
+    if (tlsKeyIndex >= 0 && tlsKeyIndex + 1 < args.length) {
+        result.tlsKeyPath = args[tlsKeyIndex + 1];
+    }
+    const tlsCertIndex = args.indexOf('--tls-cert');
+    if (tlsCertIndex >= 0 && tlsCertIndex + 1 < args.length) {
+        result.tlsCertPath = args[tlsCertIndex + 1];
+    }
+    const compressionIndex = args.indexOf('--compression');
+    if (compressionIndex >= 0 && compressionIndex + 1 < args.length) {
+        const value = args[compressionIndex + 1];
+        if (value === 'none' || value === 'toon') {
+            result.compression = value;
+        }
+        else {
+            throw new Error(`Invalid --compression value: "${value}". Must be "none" or "toon".`);
+        }
+    }
+    return result;
+};
+/**
+ * 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
+    --config <path>         Path to a synergy-mcp.json configuration file
+    --interface <type>      Server interface: stdio (default) or http
+    --host <address>        HTTP bind address (default: 127.0.0.1)
+    --port <number>         HTTP server port (default: 9119, used with --interface http)
+    --log <value>           Tool-call logs directory path, or "false"/"null" to disable
+    --tls-key <path>        Path to TLS private key file (enables HTTPS)
+    --tls-cert <path>       Path to TLS certificate file (enables HTTPS)
+    --compression <mode>    Response compression: none (default) or toon
+
+EXAMPLES:
+    syn-mcp                              # Start the MCP server via stdio (default)
+    syn-mcp --version                    # Show version
+    syn-mcp --help                       # Show this help
+    syn-mcp --config ./synergy-mcp.json  # Start with a custom config
+    syn-mcp --interface http             # Start HTTP server on port 9119
+    syn-mcp --interface http --port 3000 # Start HTTP server on port 3000
+    syn-mcp --interface http --host 0.0.0.0  # Listen on all IPv4 interfaces
+    syn-mcp --log ./logs                  # Write tool-call logs to ./logs
+    syn-mcp --log false                   # Disable tool-call logging
+    syn-mcp --interface http --tls-key ./key.pem --tls-cert ./cert.pem  # Start HTTPS server
+
+CONFIGURATION FILE:
+    A synergy-mcp.json file can specify interface, port, host, and TLS settings:
+
+    {
+      "interface": "http",
+      "port": 3000,
+      "host": "0.0.0.0",
+      "logging": {
+        "localFile": {
+          "path": "./logs"
+        }
+      },
+      "tls": {
+        "keyPath": "./key.pem",
+        "certPath": "./cert.pem"
+      }
+    }
+
+    CLI flags override config file values.
+
+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/compression.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Encodes an unknown value using toon format.
+ * Returns the original value as JSON string if toon is unavailable.
+ * @param value The value to encode
+ * @returns The encoded toon format string, or JSON stringified value if encoder unavailable
+ */
+export declare const encodeToToon: (value: unknown) => Promise<string>;

package/dist/utilities/compression.js

@@ -0,0 +1,45 @@
+const hasToonEncode = (module) => {
+    if (typeof module !== 'object' || module === null) {
+        return false;
+    }
+    return ('encode' in module
+        && typeof module.encode === 'function');
+};
+let encoderPromise;
+/**
+ * Loads the toon encoder from the optional @toon-format/toon dependency.
+ * If the package is not available, returns null.
+ * @returns The toon.encode function, or null if unavailable
+ */
+const loadEncoder = async () => {
+    if (!encoderPromise) {
+        encoderPromise = (async () => {
+            try {
+                const module = await import('@toon-format/toon');
+                if (!hasToonEncode(module)) {
+                    return null;
+                }
+                return module.encode;
+            }
+            catch {
+                // Package not installed or import failed
+                return null;
+            }
+        })();
+    }
+    return encoderPromise;
+};
+/**
+ * Encodes an unknown value using toon format.
+ * Returns the original value as JSON string if toon is unavailable.
+ * @param value The value to encode
+ * @returns The encoded toon format string, or JSON stringified value if encoder unavailable
+ */
+export const encodeToToon = async (value) => {
+    const encoder = await loadEncoder();
+    if (!encoder) {
+        // Graceful fallback: return as JSON
+        return JSON.stringify(value);
+    }
+    return encoder(value);
+};

package/dist/utilities/config.d.ts

@@ -1,80 +1,122 @@
-/**
- * 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;
-/**
- * Path to the fonts directory, relative to the MCP directory.
- */
-export declare const fontsPath: string;
-/**
- * List of supported frameworks.
- */
-export type Framework = 'react' | 'vue' | 'angular' | 'vanilla';
+import { z } from 'zod';
+/**
+ * Zod schema for the synergy-mcp.json configuration file.
+ * All fields are optional and fall back to built-in defaults when absent.
+ */
+export declare const McpRuntimeConfigSchema: z.ZodObject<{
+    compression: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        toon: "toon";
+    }>>;
+    host: z.ZodDefault<z.ZodString>;
+    includeAiRules: z.ZodDefault<z.ZodBoolean>;
+    interface: z.ZodDefault<z.ZodEnum<{
+        stdio: "stdio";
+        http: "http";
+    }>>;
+    logging: z.ZodDefault<z.ZodObject<{
+        localFile: z.ZodDefault<z.ZodObject<{
+            path: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    port: z.ZodDefault<z.ZodNumber>;
+    tls: z.ZodDefault<z.ZodObject<{
+        certPath: z.ZodOptional<z.ZodString>;
+        keyPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    tools: z.ZodDefault<z.ZodObject<{
+        assetInfo: z.ZodDefault<z.ZodObject<{
+            iconset: z.ZodDefault<z.ZodEnum<{
+                default: "default";
+                new: "new";
+                next: "next";
+                v2: "v2";
+                v3: "v3";
+                legacy: "legacy";
+                synergy2018: "synergy2018";
+                brand2018: "brand2018";
+                sick2018: "sick2018";
+                current: "current";
+                brand2025: "brand2025";
+                sick2025: "sick2025";
+                synergy2025: "synergy2025";
+            }>>;
+        }, z.core.$strip>>;
+        componentInfo: z.ZodDefault<z.ZodObject<{
+            framework: z.ZodDefault<z.ZodEnum<{
+                angular: "angular";
+                react: "react";
+                vue: "vue";
+                vanilla: "vanilla";
+            }>>;
+            layer: z.ZodDefault<z.ZodEnum<{
+                full: "full";
+                examples: "examples";
+                interface: "interface";
+            }>>;
+        }, z.core.$strip>>;
+        davinciMigrationInfo: z.ZodDefault<z.ZodObject<{
+            package: z.ZodDefault<z.ZodEnum<{
+                "basic-elements": "basic-elements";
+                "dashboard-elements": "dashboard-elements";
+            }>>;
+        }, z.core.$strip>>;
+        davinciMigrationList: z.ZodDefault<z.ZodObject<{
+            package: z.ZodDefault<z.ZodEnum<{
+                "basic-elements": "basic-elements";
+                "dashboard-elements": "dashboard-elements";
+            }>>;
+        }, z.core.$strip>>;
+        migrationInfo: z.ZodDefault<z.ZodObject<{
+            synergyPackage: z.ZodDefault<z.ZodEnum<{
+                components: "components";
+                assets: "assets";
+                styles: "styles";
+                tokens: "tokens";
+            }>>;
+        }, z.core.$strip>>;
+        migrationList: z.ZodDefault<z.ZodObject<{
+            synergyPackage: z.ZodDefault<z.ZodEnum<{
+                components: "components";
+                assets: "assets";
+                styles: "styles";
+                tokens: "tokens";
+            }>>;
+        }, z.core.$strip>>;
+        setup: z.ZodDefault<z.ZodObject<{
+            includeLimitations: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        tokenInfo: z.ZodDefault<z.ZodObject<{
+            type: z.ZodDefault<z.ZodEnum<{
+                css: "css";
+                javascript: "javascript";
+                sass: "sass";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type McpRuntimeConfig = z.infer<typeof McpRuntimeConfigSchema>;
+/**
+ * Replaces the in-memory runtime configuration.
+ * Useful when startup code applies CLI overrides after file/default resolution.
+ *
+ * @param config The fully resolved runtime configuration to use globally.
+ */
+export declare const setRuntimeConfig: (config: McpRuntimeConfig) => void;
+/**
+ * Loads the runtime configuration from a JSON file at the given path, validates
+ * it against the schema, and caches the result.  Each configured field is
+ * deep-merged with built-in defaults so partial configs are always safe.
+ *
+ * If no path is given, or if loading / validation fails, the built-in defaults
+ * are (re-)applied and a warning is written to stderr.
+ *
+ * @param configPath Optional absolute or relative path to a synergy-mcp.json file.
+ */
+export declare const initializeRuntimeConfig: (configPath?: string) => Promise<void>;
+/**
+ * Returns the current runtime configuration.
+ * Falls back to built-in defaults if {@link initializeRuntimeConfig} has not
+ * been called yet.
+ */
+export declare const getRuntimeConfig: () => McpRuntimeConfig;