@synergy-design-system/mcp 2.14.1 → 3.0.0

package/dist/utilities/config.js

@@ -1,81 +1,212 @@
-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');
-/**
- * Path to the fonts directory, relative to the MCP directory.
- */
-export const fontsPath = join(currentDirname, '../../metadata/packages/fonts');
+import { readFile } from 'node:fs/promises';
+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 const McpRuntimeConfigSchema = z.object({
+    /**
+     * Compression mode for tool response payloads.
+     * 'none': No compression (default)
+     * 'toon': Use toon format encoding for structured data
+     * @default 'none'
+     */
+    compression: z.enum(['none', 'toon']).default('none'),
+    /**
+     * HTTP server host/interface when interface is 'http'.
+     * Use 127.0.0.1 for local-only access or 0.0.0.0 to listen on all IPv4 interfaces.
+     * @default '127.0.0.1'
+     */
+    host: z
+        .string()
+        .min(1)
+        .default('127.0.0.1'),
+    /**
+     * Whether to prepend AI guidance rules to tool responses.
+     * Set to false to strip the rules preface from all tool outputs.
+     * @default true
+     */
+    includeAiRules: z.boolean().default(true),
+    /**
+     * Server interface/transport mode.
+     * 'stdio': Run over stdin/stdout (default, for editor/CLI integration)
+     * 'http': Run as HTTP/HTTPS server (requires --port or config.port)
+     * @default 'stdio'
+     */
+    interface: z.enum(['stdio', 'http']).default('stdio'),
+    /**
+     * Logging configuration.
+     * Providers are opt-in; by default no provider is enabled.
+     */
+    logging: z.object({
+        localFile: z.object({
+            /**
+             * Base directory for local tool call logs.
+             * If null, local file logging is disabled.
+             * @default null
+             */
+            path: z.string().min(1).nullable().default(null),
+        }).default({ path: null }),
+    }).default({
+        localFile: { path: null },
+    }),
+    /**
+     * HTTP server port when interface is 'http'.
+     * Must be between 1 and 65535.
+     * @default 9119
+     */
+    port: z
+        .number()
+        .int()
+        .min(1)
+        .max(65535)
+        .default(9119),
+    /**
+     * TLS configuration for HTTPS mode.
+     * Both keyPath and certPath must be provided together to enable HTTPS.
+     * If provided, the HTTP server will use HTTPS instead.
+     */
+    tls: z.object({
+        /**
+         * Path to the TLS certificate file (PEM format).
+         */
+        certPath: z.string().optional(),
+        /**
+         * Path to the TLS private key file (PEM format).
+         */
+        keyPath: z.string().optional(),
+    }).default({}).refine(val => {
+        // Both must be present or both must be absent
+        const hasKey = val.keyPath !== undefined;
+        const hasCert = val.certPath !== undefined;
+        return hasKey === hasCert;
+    }, {
+        message: 'Both tls.keyPath and tls.certPath must be provided together',
+        path: ['tls'],
+    }),
+    /**
+     * Per-tool default overrides.
+     * Each key corresponds to a tool and contains the subset of that tool's
+     * parameters that have configurable defaults.
+     */
+    tools: z.object({
+        assetInfo: z.object({
+            /**
+             * Default iconset used when no iconset is provided by the caller.
+             * @default 'current'
+             */
+            iconset: z.enum([
+                'legacy', 'v2', 'synergy2018', 'brand2018', 'sick2018',
+                'current', 'default', 'brand2025', 'sick2025', 'synergy2025', 'new', 'next', 'v3',
+            ]).default('current'),
+        }).default({ iconset: 'current' }),
+        componentInfo: z.object({
+            /**
+             * Default framework when no framework is provided by the caller.
+             * @default 'vanilla'
+             */
+            framework: z.enum(['react', 'vue', 'angular', 'vanilla']).default('vanilla'),
+            /**
+             * Default metadata layer when no layer is provided by the caller.
+             * @default 'interface'
+             */
+            layer: z.enum(['full', 'examples', 'interface']).default('interface'),
+        }).default({ framework: 'vanilla', layer: 'interface' }),
+        davinciMigrationInfo: z.object({
+            /**
+             * Default migration package when none is provided by the caller.
+             * @default 'basic-elements'
+             */
+            package: z.enum(['basic-elements', 'dashboard-elements']).default('basic-elements'),
+        }).default({ package: 'basic-elements' }),
+        davinciMigrationList: z.object({
+            /**
+             * Default migration package when none is provided by the caller.
+             * @default 'basic-elements'
+             */
+            package: z.enum(['basic-elements', 'dashboard-elements']).default('basic-elements'),
+        }).default({ package: 'basic-elements' }),
+        migrationInfo: z.object({
+            /**
+             * Default Synergy package when none is provided by the caller.
+             * @default 'components'
+             */
+            synergyPackage: z.enum(['assets', 'components', 'styles', 'tokens']).default('components'),
+        }).default({ synergyPackage: 'components' }),
+        migrationList: z.object({
+            /**
+             * Default Synergy package when none is provided by the caller.
+             * @default 'components'
+             */
+            synergyPackage: z.enum(['assets', 'components', 'styles', 'tokens']).default('components'),
+        }).default({ synergyPackage: 'components' }),
+        setup: z.object({
+            /**
+             * Whether to include limitations in setup output by default.
+             * @default true
+             */
+            includeLimitations: z.boolean().default(true),
+        }).default({ includeLimitations: true }),
+        tokenInfo: z.object({
+            /**
+             * Default token output type when none is provided by the caller.
+             * @default 'css'
+             */
+            type: z.enum(['javascript', 'css', 'sass']).default('css'),
+        }).default({ type: 'css' }),
+    }).default({
+        assetInfo: { iconset: 'current' },
+        componentInfo: { framework: 'vanilla', layer: 'full' },
+        davinciMigrationInfo: { package: 'basic-elements' },
+        davinciMigrationList: { package: 'basic-elements' },
+        migrationInfo: { synergyPackage: 'components' },
+        migrationList: { synergyPackage: 'components' },
+        setup: { includeLimitations: true },
+        tokenInfo: { type: 'css' },
+    }),
+});
+/**
+ * Built-in defaults — identical to parsing an empty object through the schema.
+ */
+const DEFAULT_CONFIG = McpRuntimeConfigSchema.parse({});
+let resolvedConfig = DEFAULT_CONFIG;
+/**
+ * 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 const setRuntimeConfig = (config) => {
+    resolvedConfig = config;
+};
+/**
+ * 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 const initializeRuntimeConfig = async (configPath) => {
+    if (!configPath) {
+        resolvedConfig = DEFAULT_CONFIG;
+        return;
+    }
+    try {
+        const raw = await readFile(configPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        resolvedConfig = McpRuntimeConfigSchema.parse(parsed);
+    }
+    catch (error) {
+        process.stderr.write(`[synergy-mcp] Warning: Failed to load config from "${configPath}". Using built-in defaults.\n  Reason: ${error instanceof Error ? error.message : String(error)}\n`);
+        resolvedConfig = DEFAULT_CONFIG;
+    }
+};
+/**
+ * Returns the current runtime configuration.
+ * Falls back to built-in defaults if {@link initializeRuntimeConfig} has not
+ * been called yet.
+ */
+export const getRuntimeConfig = () => resolvedConfig;

package/dist/utilities/davinci.d.ts

@@ -0,0 +1,12 @@
+export declare const SUPPORTED_PACKAGES: readonly ["basic-elements", "dashboard-elements"];
+export type DavinciMigrationPackage = (typeof SUPPORTED_PACKAGES)[number];
+/**
+ * Resolves a package alias to its official DaVinci migration package name.
+ * @param alias The user-provided package alias or official name.
+ * @returns The resolved official package name.
+ * @throws Error if the alias is not recognized.
+ */
+export declare const resolveDavinciPackageAlias: (alias: string) => DavinciMigrationPackage;
+export declare const getMigrationGuideContent: (packageName: DavinciMigrationPackage) => Promise<string>;
+export declare const extractDavinciComponents: (content: string) => string[];
+export declare const extractMigrationSection: (content: string, component: string) => string | undefined;

package/dist/utilities/davinci.js

@@ -0,0 +1,55 @@
+import { getDataForSetup } from '@synergy-design-system/metadata';
+export const SUPPORTED_PACKAGES = ['basic-elements', 'dashboard-elements'];
+/**
+ * Alias mapping for DaVinci migration packages.
+ * Maps user-friendly names to official package names.
+ */
+const davinciPackageAliases = {
+    'basic-elements': [
+        'basic-elements',
+        'components',
+    ],
+    'dashboard-elements': [
+        'dashboard-elements',
+        'charts',
+    ],
+};
+/**
+ * Resolves a package alias to its official DaVinci migration package name.
+ * @param alias The user-provided package alias or official name.
+ * @returns The resolved official package name.
+ * @throws Error if the alias is not recognized.
+ */
+export const resolveDavinciPackageAlias = (alias) => {
+    const resolved = Object
+        .entries(davinciPackageAliases)
+        .find(([, aliases]) => aliases.includes(alias.toLowerCase()))?.[0];
+    if (!resolved) {
+        const validOptions = Object.keys(davinciPackageAliases).join(', ');
+        throw new Error(`Unknown DaVinci package "${alias}". Valid options: ${validOptions}`);
+    }
+    return resolved;
+};
+const getGuidePathSuffix = (packageName) => `/davinci/${packageName}.md`;
+export const getMigrationGuideContent = async (packageName) => {
+    const response = await getDataForSetup({
+        package: 'migrations',
+    });
+    if (!response.data) {
+        throw new Error(response.errors?.[0]?.message ?? 'No migration setup data found.');
+    }
+    const guide = response.data.setups
+        .flatMap((entry) => entry.text)
+        .find((entry) => entry.path.toLowerCase().endsWith(getGuidePathSuffix(packageName)));
+    if (!guide) {
+        throw new Error(`No DaVinci migration guide found for package "${packageName}".`);
+    }
+    return guide.content;
+};
+export const extractDavinciComponents = (content) => {
+    const matches = Array.from(content.matchAll(/^### (davinci-[\w-]+)/gm), match => match[1]);
+    return [...new Set(matches)].toSorted((a, b) => a.localeCompare(b));
+};
+export const extractMigrationSection = (content, component) => content
+    .split(/\n(?=###\s)/)
+    .find(section => section.startsWith(`### ${component}`));

package/dist/utilities/index.d.ts

@@ -1,13 +1,13 @@
-export * from './assets.js';
-export * from './checksum.js';
-export * from './components.js';
 export * from './config.js';
-export * from './file.js';
-export * from './fonts.js';
+export * from './davinci.js';
+export * from './logger.js';
+export * from './logging-context.js';
+export * from './logging-service.js';
+export * from './logging-types.js';
+export * from './local-file-logger.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';
+export * from './token-counter.js';
+export * from './rules.js';
+export * from './server.js';
+export * from './cli.js';

package/dist/utilities/index.js

@@ -1,13 +1,13 @@
-export * from './assets.js';
-export * from './checksum.js';
-export * from './components.js';
 export * from './config.js';
-export * from './file.js';
-export * from './fonts.js';
+export * from './davinci.js';
+export * from './logger.js';
+export * from './logging-context.js';
+export * from './logging-service.js';
+export * from './logging-types.js';
+export * from './local-file-logger.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';
+export * from './token-counter.js';
+export * from './rules.js';
+export * from './server.js';
+export * from './cli.js';

package/dist/utilities/local-file-logger.d.ts

@@ -0,0 +1,2 @@
+import type { LoggerProvider } from './logging-types.js';
+export declare const createLocalFileLoggerProvider: (baseDirectory: string) => LoggerProvider;

package/dist/utilities/local-file-logger.js

@@ -0,0 +1,22 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+const sanitizeSessionId = (sessionId) => sessionId
+    .trim()
+    .replace(/[^a-zA-Z0-9_.-]/g, '_') || 'unknown-session';
+const toDateFolder = (isoTimestamp) => {
+    const date = new Date(isoTimestamp);
+    const year = String(date.getUTCFullYear()).slice(-2);
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+};
+export const createLocalFileLoggerProvider = (baseDirectory) => ({
+    log: async (event) => {
+        const dateFolder = toDateFolder(event.timestamp);
+        const filename = `${sanitizeSessionId(event.sessionId)}.json`;
+        const directory = join(baseDirectory, dateFolder);
+        const filePath = join(directory, filename);
+        await mkdir(directory, { recursive: true });
+        await appendFile(filePath, `${JSON.stringify(event)}\n`, 'utf8');
+    },
+});

package/dist/utilities/logger.d.ts

@@ -0,0 +1,12 @@
+import type { McpRuntimeConfig } from './config.js';
+export declare const initializeLogger: (config: McpRuntimeConfig) => void;
+type LogToolCallInput = {
+    durationMs: number;
+    errorMessage?: string;
+    parameters: Record<string, unknown>;
+    success: boolean;
+    tokenCount?: number;
+    toolName: string;
+};
+export declare const logToolCall: (input: LogToolCallInput) => Promise<void>;
+export {};

package/dist/utilities/logger.js

@@ -0,0 +1,30 @@
+import { createLocalFileLoggerProvider } from './local-file-logger.js';
+import { createLoggerService } from './logging-service.js';
+import { getLoggingContext } from './logging-context.js';
+let loggerService = createLoggerService([]);
+export const initializeLogger = (config) => {
+    const providerFactories = [];
+    const localPath = config.logging.localFile.path;
+    if (localPath) {
+        providerFactories.push(createLocalFileLoggerProvider(localPath));
+    }
+    loggerService = createLoggerService(providerFactories);
+};
+export const logToolCall = async (input) => {
+    if (!loggerService.enabled) {
+        return;
+    }
+    const context = getLoggingContext();
+    const event = {
+        durationMs: input.durationMs,
+        errorMessage: input.errorMessage,
+        parameters: input.parameters,
+        sessionId: context.sessionId,
+        success: input.success,
+        timestamp: new Date().toISOString(),
+        tokenCount: input.tokenCount,
+        toolName: input.toolName,
+        transport: context.transport,
+    };
+    await loggerService.log(event);
+};

package/dist/utilities/logging-context.d.ts

@@ -0,0 +1,8 @@
+import type { LoggingTransport } from './logging-types.js';
+type LoggingContext = {
+    sessionId: string;
+    transport: LoggingTransport;
+};
+export declare const runWithLoggingContext: <T>(context: LoggingContext, fn: () => Promise<T>) => Promise<T>;
+export declare const getLoggingContext: () => LoggingContext;
+export {};

package/dist/utilities/logging-context.js

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const loggingContextStore = new AsyncLocalStorage();
+export const runWithLoggingContext = async (context, fn) => loggingContextStore.run(context, fn);
+export const getLoggingContext = () => (loggingContextStore.getStore() ?? {
+    sessionId: 'stdio',
+    transport: 'stdio',
+});

package/dist/utilities/logging-service.d.ts

@@ -0,0 +1,2 @@
+import type { LoggerProvider, LoggerService } from './logging-types.js';
+export declare const createLoggerService: (providers: LoggerProvider[]) => LoggerService;

package/dist/utilities/logging-service.js

@@ -0,0 +1,24 @@
+const providerError = (index, error) => {
+    process.stderr.write(`[synergy-mcp] Warning: logger provider #${index + 1} failed: ${error instanceof Error ? error.message : String(error)}\n`);
+};
+export const createLoggerService = (providers) => {
+    if (providers.length === 0) {
+        return {
+            enabled: false,
+            log: async () => {
+                // No-op logger keeps call sites simple.
+            },
+        };
+    }
+    return {
+        enabled: true,
+        log: async (event) => {
+            const results = await Promise.allSettled(providers.map(provider => provider.log(event)));
+            results.forEach((result, index) => {
+                if (result.status === 'rejected') {
+                    providerError(index, result.reason);
+                }
+            });
+        },
+    };
+};

package/dist/utilities/logging-types.d.ts

@@ -0,0 +1,19 @@
+export type LoggingTransport = 'http' | 'stdio';
+export type ToolLogEvent = {
+    durationMs: number;
+    errorMessage?: string;
+    parameters: Record<string, unknown>;
+    sessionId: string;
+    success: boolean;
+    timestamp: string;
+    tokenCount?: number;
+    toolName: string;
+    transport: LoggingTransport;
+};
+export interface LoggerProvider {
+    log: (event: ToolLogEvent) => Promise<void>;
+}
+export interface LoggerService {
+    enabled: boolean;
+    log: (event: ToolLogEvent) => Promise<void>;
+}

package/dist/utilities/metadata.d.ts

@@ -1,7 +1,5 @@
-/**
- * Filter function type for filtering metadata files.
- */
-export type Filter = (fileName: string) => boolean;
+import type { ToolResponse } from '../types/tool-response.js';
+import { type WithErrorHandlerOptions } from '../middleware/index.js';
 /**
  * MetadataFile type representing a structured metadata file.
  */
@@ -10,19 +8,14 @@ export type MetadataFile = {
     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.
+ * Creates a content array from an array of unknown data.
+ * This is useful for converting raw data into a format that can be returned by MCP tools.
+ * @param data The original data to convert into a content array. Each entry will be converted to a string if it is not already a string.
+ * @returns Final content array
  */
-export declare const getStructuredMetaData: (folder: string, filter?: Filter) => Promise<(MetadataFile | null)[]>;
+export declare const toContentArray: (data: unknown[]) => ToolResponse;
 /**
- * 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'.
+ * Creates a transparent tool handler that keeps tool bodies focused on
+ * business logic while applying logging and error handling consistently.
  */
-export declare const getStructuredMetaDataForComponent: (componentName: string, filter?: Filter, source?: "package" | "static") => Promise<(MetadataFile | null)[]>;
+export declare const toolHandler: <TArgs extends Record<string, unknown>>(toolName: string, handler: (args: TArgs) => Promise<unknown[]>, options?: WithErrorHandlerOptions) => (args: TArgs) => Promise<ToolResponse>;