@synergy-design-system/mcp 2.15.0 → 3.0.1

package/dist/bin/start.js

@@ -1,8 +1,59 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from '../server.js';
-import { handleCommandLineArgs } from '../utilities/index.js';
-handleCommandLineArgs();
-const server = createServer();
-const transport = new StdioServerTransport();
-await server.connect(transport);
+import { createTransport } from '../transports/index.js';
+import { getRuntimeConfig, initializeRuntimeConfig, setRuntimeConfig, } from '../utilities/config.js';
+import { handleCommandLineArgs, initializeLogger, parseCommandLineArgs, } from '../utilities/index.js';
+try {
+    handleCommandLineArgs();
+    const parsedArgs = parseCommandLineArgs();
+    await initializeRuntimeConfig(parsedArgs.configPath);
+    // Get config from file (or defaults if not provided)
+    const initialConfig = getRuntimeConfig();
+    let config = { ...initialConfig };
+    // Apply CLI overrides to config (CLI has highest precedence)
+    if (parsedArgs.interface !== undefined) {
+        config = { ...config, interface: parsedArgs.interface };
+    }
+    if (parsedArgs.port !== undefined) {
+        config = { ...config, port: parsedArgs.port };
+    }
+    if (parsedArgs.host !== undefined) {
+        config = { ...config, host: parsedArgs.host };
+    }
+    if (parsedArgs.tlsKeyPath !== undefined || parsedArgs.tlsCertPath !== undefined) {
+        config = {
+            ...config,
+            tls: {
+                certPath: parsedArgs.tlsCertPath ?? config.tls?.certPath,
+                keyPath: parsedArgs.tlsKeyPath ?? config.tls?.keyPath,
+            },
+        };
+    }
+    if (parsedArgs.logPath !== undefined) {
+        config = {
+            ...config,
+            logging: {
+                ...config.logging,
+                localFile: {
+                    ...config.logging.localFile,
+                    path: parsedArgs.logPath,
+                },
+            },
+        };
+    }
+    if (parsedArgs.compression !== undefined) {
+        config = {
+            ...config,
+            compression: parsedArgs.compression,
+        };
+    }
+    // Persist the final resolved config (including CLI overrides) for middleware/tool runtime.
+    setRuntimeConfig(config);
+    initializeLogger(config);
+    const transport = await createTransport(createServer, config);
+    await transport.start();
+}
+catch (error) {
+    process.stderr.write(`[synergy-mcp] Error: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+}

package/dist/middleware/compose.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Middleware composition utility using reduceRight pattern.
+ * This keeps middlewares flexible for reordering while maintaining clear
+ * execution semantics (right-to-left composition, left-to-right execution).
+ */
+import type { RawToolHandler, ToolMiddleware, ToolMiddlewareContext } from './types.js';
+/**
+ * Applies an array of middlewares to a raw tool handler, returning a new handler with all middleware applied.
+ * Middlewares are applied in right-to-left order, meaning the last middleware in the array will be the outermost wrapper around the handler.
+ * @param handler The original raw tool handler function to wrap with middleware.
+ * @param middlewares An array of middleware functions to apply to the handler.
+ * @param context The context object to pass to each middleware, containing configuration and options.
+ * @returns A new raw tool handler function with all middleware applied.
+ */
+export declare const composeMiddlewares: <TArgs extends Record<string, unknown>>(handler: RawToolHandler<TArgs>, middlewares: ToolMiddleware<TArgs>[], context: ToolMiddlewareContext) => RawToolHandler<TArgs>;

package/dist/middleware/compose.js

@@ -0,0 +1,10 @@
+/**
+ * Applies an array of middlewares to a raw tool handler, returning a new handler with all middleware applied.
+ * Middlewares are applied in right-to-left order, meaning the last middleware in the array will be the outermost wrapper around the handler.
+ * @param handler The original raw tool handler function to wrap with middleware.
+ * @param middlewares An array of middleware functions to apply to the handler.
+ * @param context The context object to pass to each middleware, containing configuration and options.
+ * @returns A new raw tool handler function with all middleware applied.
+ */
+export const composeMiddlewares = (handler, middlewares, context) => middlewares
+    .reduceRight((next, middleware) => middleware(next, context), handler);

package/dist/middleware/compression.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Compression middleware for MCP tool responses.
+ * Encodes structured data (objects, arrays) into toon format when enabled.
+ * String entries (like AI rules) pass through unchanged.
+ */
+import type { ToolMiddleware } from './types.js';
+/**
+ * Middleware that compresses tool response payloads using toon format encoding.
+ *
+ * When `compression` is set to `'toon'`, non-string entries in the tool response
+ * are encoded to a compact toon text format. String entries (e.g., AI rules prefix)
+ * pass through unchanged. This reduces response size significantly for structured data.
+ *
+ * When `compression` is `'none'` or unavailable, responses pass through unmodified.
+ *
+ * This middleware should run before the logging middleware so that token counts
+ * reflect the compressed payload size.
+ */
+export declare const withCompressionMiddleware: ToolMiddleware<Record<string, unknown>>;

package/dist/middleware/compression.js

@@ -0,0 +1,35 @@
+/**
+ * Compression middleware for MCP tool responses.
+ * Encodes structured data (objects, arrays) into toon format when enabled.
+ * String entries (like AI rules) pass through unchanged.
+ */
+import { encodeToToon } from '../utilities/compression.js';
+/**
+ * Middleware that compresses tool response payloads using toon format encoding.
+ *
+ * When `compression` is set to `'toon'`, non-string entries in the tool response
+ * are encoded to a compact toon text format. String entries (e.g., AI rules prefix)
+ * pass through unchanged. This reduces response size significantly for structured data.
+ *
+ * When `compression` is `'none'` or unavailable, responses pass through unmodified.
+ *
+ * This middleware should run before the logging middleware so that token counts
+ * reflect the compressed payload size.
+ */
+export const withCompressionMiddleware = (next, context) => async (args) => {
+    const result = await next(args);
+    // Early exit if compression is disabled
+    if (!context.config.compression || context.config.compression === 'none') {
+        return result;
+    }
+    // Compression mode is 'toon': process each entry
+    const compressed = await Promise.all(result.map(async (entry) => {
+        // Strings (e.g., AI rules prefix) pass through unchanged
+        if (typeof entry === 'string') {
+            return entry;
+        }
+        // Non-strings get encoded to toon format
+        return encodeToToon(entry);
+    }));
+    return compressed;
+};

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Error handling middleware for tool execution.
+ * Wraps handler with try/catch to provide consistent fallback behavior.
+ */
+import type { ToolMiddleware } from './types.js';
+/**
+ * Middleware that applies error handling to tool execution, using the withErrorHandler function to wrap the next handler in the chain.
+ * This ensures that any errors thrown during tool execution are caught and handled according to the provided options or default behavior.
+ * @param next The next handler in the middleware chain, which executes the actual tool logic.
+ * @param context The middleware context, containing configuration and options for error handling.
+ * @returns A new handler function that wraps the original tool logic with error handling functionality.
+ */
+export declare const withErrorHandlingMiddleware: ToolMiddleware<Record<string, unknown>>;

package/dist/middleware/error-handler.js

@@ -0,0 +1,42 @@
+/**
+ * Default error content generator for tool responses.
+ * This can be used in the onError callback of withErrorHandler to provide a consistent error message format.
+ * @param error - The error object that was thrown.
+ * @param context - Optional context string to provide additional information about where the error occurred.
+ * @returns An array of content objects suitable for MCP tool responses.
+ */
+const defaultErrorContent = (error, context) => {
+    const suffix = context ? ` ${context}` : '';
+    const message = error instanceof Error ? error.message : String(error);
+    return [
+        {
+            text: `Error${suffix}: ${message}`,
+            type: 'text',
+        },
+    ];
+};
+/**
+ * Wraps raw tool execution with fallback behavior.
+ * Use this as middleware in the tool pipeline.
+ * @param fn - Raw tool handler function.
+ * @param options - Optional context and custom error fallback behavior.
+ */
+const withErrorHandler = (fn, options = {}) => async (args) => {
+    try {
+        return await fn(args);
+    }
+    catch (error) {
+        const fallback = options.onError
+            ? await options.onError(error, options.context)
+            : defaultErrorContent(error, options.context);
+        return fallback;
+    }
+};
+/**
+ * Middleware that applies error handling to tool execution, using the withErrorHandler function to wrap the next handler in the chain.
+ * This ensures that any errors thrown during tool execution are caught and handled according to the provided options or default behavior.
+ * @param next The next handler in the middleware chain, which executes the actual tool logic.
+ * @param context The middleware context, containing configuration and options for error handling.
+ * @returns A new handler function that wraps the original tool logic with error handling functionality.
+ */
+export const withErrorHandlingMiddleware = (next, context) => withErrorHandler(next, context.options);

package/dist/middleware/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Middleware module entrypoint.
+ * Exports middleware types, composition, and built-in middleware implementations.
+ */
+export type * from './types.js';
+export { composeMiddlewares } from './compose.js';
+export { withCompressionMiddleware } from './compression.js';
+export { withErrorHandlingMiddleware } from './error-handler.js';
+export { withToolLoggingMiddleware } from './logging.js';

package/dist/middleware/index.js

@@ -0,0 +1,8 @@
+/**
+ * Middleware module entrypoint.
+ * Exports middleware types, composition, and built-in middleware implementations.
+ */
+export { composeMiddlewares } from './compose.js';
+export { withCompressionMiddleware } from './compression.js';
+export { withErrorHandlingMiddleware } from './error-handler.js';
+export { withToolLoggingMiddleware } from './logging.js';

package/dist/middleware/logging.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Logging middleware for tool execution.
+ * Records tool call duration, token count, success/error state, and parameters.
+ * Respects logging config: early-exits if logging is disabled to avoid token counting overhead.
+ */
+import type { ToolMiddleware } from './types.js';
+/**
+ * Middleware that logs details about tool execution, including duration, success/failure, token count, and parameters.
+ * It checks the logging configuration and skips logging (and token counting) if logging is disabled to optimize performance.
+ * @param next The next handler in the middleware chain, which executes the actual tool logic.
+ * @param context The middleware context, containing configuration and options for logging.
+ * @returns A new handler function that wraps the original tool logic with logging functionality.
+ */
+export declare const withToolLoggingMiddleware: ToolMiddleware<Record<string, unknown>>;

package/dist/middleware/logging.js

@@ -0,0 +1,64 @@
+/**
+ * Logging middleware for tool execution.
+ * Records tool call duration, token count, success/error state, and parameters.
+ * Respects logging config: early-exits if logging is disabled to avoid token counting overhead.
+ */
+import { logToolCall } from '../utilities/logger.js';
+import { countTextTokens, toTextPayload, } from '../utilities/token-counter.js';
+import { toContentArray } from '../utilities/metadata.js';
+/**
+ * Middleware that logs details about tool execution, including duration, success/failure, token count, and parameters.
+ * It checks the logging configuration and skips logging (and token counting) if logging is disabled to optimize performance.
+ * @param next The next handler in the middleware chain, which executes the actual tool logic.
+ * @param context The middleware context, containing configuration and options for logging.
+ * @returns A new handler function that wraps the original tool logic with logging functionality.
+ */
+export const withToolLoggingMiddleware = (next, context) => async (args) => {
+    // Early exit if logging is not enabled to avoid token counting overhead.
+    if (context.config.logging.localFile.path === null) {
+        return next(args);
+    }
+    const startedAt = process.hrtime.bigint();
+    let success = false;
+    let errorMessage;
+    let tokenCount;
+    try {
+        const content = await next(args);
+        success = true;
+        // Normalize to ToolResponse content before token counting so metrics match the final response shape.
+        // This keeps logging robust even if middleware order changes later.
+        const textPayload = toTextPayload(toContentArray(content).content);
+        tokenCount = await countTextTokens(textPayload);
+        return content;
+    }
+    catch (error) {
+        errorMessage = error instanceof Error ? error.message : String(error);
+        throw error;
+    }
+    finally {
+        const durationMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+        // MCP SDK may add internal context properties to the args object
+        // (requestId, signal, requestInfo, sessionId). Create a new object
+        // with only the non-internal properties for logging.
+        const internalProps = new Set([
+            'requestId',
+            'signal',
+            'requestInfo',
+            'sessionId',
+        ]);
+        const loggableParameters = {};
+        Object.entries(args).forEach(([key, value]) => {
+            if (!internalProps.has(key)) {
+                loggableParameters[key] = value;
+            }
+        });
+        await logToolCall({
+            durationMs,
+            errorMessage,
+            parameters: loggableParameters,
+            success,
+            tokenCount,
+            toolName: context.toolName,
+        });
+    }
+};

package/dist/middleware/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Middleware pipeline types and contracts.
+ */
+import type { McpRuntimeConfig } from '../utilities/config.js';
+export type RawToolHandler<TArgs extends Record<string, unknown>> = (args: TArgs) => Promise<unknown[]>;
+export type ToolMiddlewareContext = {
+    config: McpRuntimeConfig;
+    options: WithErrorHandlerOptions;
+    toolName: string;
+};
+/**
+ * ToolMiddleware defines the shape of middleware functions that can be applied to tool handlers.
+ * Each middleware receives the next handler in the chain and a context object, and returns a new handler function.
+ * This allows for flexible composition of cross-cutting concerns like logging, error handling, and more.
+ */
+export type ToolMiddleware<TArgs extends Record<string, unknown>> = (next: RawToolHandler<TArgs>, context: ToolMiddlewareContext) => RawToolHandler<TArgs>;
+export type WithErrorHandlerOptions = {
+    context?: string;
+    onError?: (error: unknown, context?: string) => unknown[] | Promise<unknown[]>;
+};

package/dist/middleware/types.js

@@ -0,0 +1,4 @@
+/**
+ * Middleware pipeline types and contracts.
+ */
+export {};

package/dist/resources/asset-list.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers a static MCP resource that lists all available icon sets in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export declare const assetListResource: (server: McpServer) => void;

package/dist/resources/asset-list.js

@@ -0,0 +1,34 @@
+import { listAssets } from '@synergy-design-system/metadata';
+const RESOURCE_URI = 'synergy://assets/list';
+/**
+ * Registers a static MCP resource that lists all available icon sets in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export const assetListResource = (server) => {
+    server.registerResource('asset-list', RESOURCE_URI, {
+        description: 'All available icon sets in the Synergy Design System, including theme metadata.',
+        mimeType: 'application/json',
+        title: 'Available icon sets',
+    }, async (_uri) => {
+        const allAssets = await listAssets();
+        const assets = allAssets.data
+            .map(asset => ({
+            iconCount: asset.custom?.iconCount,
+            id: asset.id,
+            name: asset.name,
+            since: asset.since,
+            theme: asset.custom?.theme ?? 'default',
+        }))
+            .toSorted((a, b) => a.name.localeCompare(b.name));
+        return {
+            contents: [
+                {
+                    mimeType: 'application/json',
+                    text: JSON.stringify(assets, null, 2),
+                    uri: RESOURCE_URI,
+                },
+            ],
+        };
+    });
+};

package/dist/resources/component-cluster-list.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers a static MCP resource that lists all available component clusters in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export declare const componentClustersListRessource: (server: McpServer) => void;

package/dist/resources/component-cluster-list.js

@@ -0,0 +1,30 @@
+import { listComponentClusters } from '@synergy-design-system/metadata';
+const RESOURCE_URI = 'synergy://component-clusters/list';
+/**
+ * Registers a static MCP resource that lists all available component clusters in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export const componentClustersListRessource = (server) => {
+    server.registerResource('component-clusters-list', RESOURCE_URI, {
+        description: 'Available component clusters in the Synergy Design System.',
+        mimeType: 'application/json',
+        title: 'Available component clusters',
+    }, async (_uri) => {
+        const clusters = await listComponentClusters();
+        const data = clusters.data.map(cluster => ({
+            description: cluster.description,
+            id: cluster.id,
+            name: cluster.name,
+        }));
+        return {
+            contents: [
+                {
+                    mimeType: 'application/json',
+                    text: JSON.stringify(data, null, 2),
+                    uri: RESOURCE_URI,
+                },
+            ],
+        };
+    });
+};

package/dist/resources/component-list.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers a static MCP resource that lists all available components in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export declare const componentListResource: (server: McpServer) => void;

package/dist/resources/component-list.js

@@ -0,0 +1,31 @@
+import { listComponents } from '@synergy-design-system/metadata';
+const RESOURCE_URI = 'synergy://components/list';
+/**
+ * Registers a static MCP resource that lists all available components in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export const componentListResource = (server) => {
+    server.registerResource('component-list', RESOURCE_URI, {
+        description: 'A list of all available component names in the Synergy Design System.',
+        mimeType: 'application/json',
+        title: 'Component list',
+    }, async (_uri) => {
+        const components = await listComponents({
+            includeLayerRefs: false,
+            includeSources: false,
+        });
+        const componentNames = components.data
+            .map(c => c.name)
+            .toSorted();
+        return {
+            contents: [
+                {
+                    mimeType: 'application/json',
+                    text: JSON.stringify(componentNames, null, 2),
+                    uri: RESOURCE_URI,
+                },
+            ],
+        };
+    });
+};

package/dist/resources/index.d.ts

@@ -0,0 +1,5 @@
+export * from './asset-list.js';
+export * from './component-cluster-list.js';
+export * from './component-list.js';
+export * from './styles-list.js';
+export * from './templates-list.js';

package/dist/resources/index.js

@@ -0,0 +1,5 @@
+export * from './asset-list.js';
+export * from './component-cluster-list.js';
+export * from './component-list.js';
+export * from './styles-list.js';
+export * from './templates-list.js';

package/dist/resources/styles-list.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers a static MCP resource that lists all available styles in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export declare const stylesListResource: (server: McpServer) => void;

package/dist/resources/styles-list.js

@@ -0,0 +1,31 @@
+import { listStyles } from '@synergy-design-system/metadata';
+const RESOURCE_URI = 'synergy://styles/list';
+/**
+ * Registers a static MCP resource that lists all available styles in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export const stylesListResource = (server) => {
+    server.registerResource('styles-list', RESOURCE_URI, {
+        description: 'All available styles in the Synergy Design System, including theme metadata.',
+        mimeType: 'application/json',
+        title: 'Available styles',
+    }, async (_uri) => {
+        const styles = await listStyles({
+            includeLayerRefs: false,
+            includeSources: false,
+        });
+        const styleNames = styles.data
+            .map(c => c.name)
+            .toSorted();
+        return {
+            contents: [
+                {
+                    mimeType: 'application/json',
+                    text: JSON.stringify(styleNames, null, 2),
+                    uri: RESOURCE_URI,
+                },
+            ],
+        };
+    });
+};

package/dist/resources/templates-list.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Registers a static MCP resource that lists all available templates in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export declare const templatesListResource: (server: McpServer) => void;

package/dist/resources/templates-list.js

@@ -0,0 +1,28 @@
+import { listTemplates } from '@synergy-design-system/metadata';
+const RESOURCE_URI = 'synergy://templates/list';
+/**
+ * Registers a static MCP resource that lists all available templates in the Synergy Design System.
+ * Clients that support resources can read this directly without calling a tool.
+ * @param server - The MCP server instance to register the resource on.
+ */
+export const templatesListResource = (server) => {
+    server.registerResource('templates-list', RESOURCE_URI, {
+        description: 'All available templates in the Synergy Design System, including theme metadata.',
+        mimeType: 'application/json',
+        title: 'Available templates',
+    }, async (_uri) => {
+        const response = await listTemplates();
+        const templates = response.data
+            .map(template => template.name)
+            .toSorted();
+        return {
+            contents: [
+                {
+                    mimeType: 'application/json',
+                    text: JSON.stringify(templates, null, 2),
+                    uri: RESOURCE_URI,
+                },
+            ],
+        };
+    });
+};

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import * as resources from './resources/index.js';
 import * as tools from './tools/index.js';
-import { getVersion } from './utilities/version.js';
+import { getVersion } from './utilities/cli.js';
 /**
  * Creates a new instance of the MCP server configured for the Synergy Design System.
  * @returns A new instance of the MCP server configured for the Synergy Design System.
@@ -16,5 +17,8 @@ export const createServer = () => {
     Object.values(tools).forEach(tool => {
         tool(server);
     });
+    Object.values(resources).forEach(resource => {
+        resource(server);
+    });
     return server;
 };