@synergy-design-system/mcp 2.15.0 → 3.0.1

package/dist/tools/migration-list.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getMigrationMetaData } from '../utilities/index.js';
+import { createToolAnnotations, getMigrationMetaData, getRuntimeConfig, toolHandler, } from '../utilities/index.js';
 const extractHeadingMetadata = (content) => {
     const result = {};
     // Try to find the first level‑1 heading.
@@ -69,6 +69,7 @@ const extractSummaryMetadata = (content) => {
  */
 export const migrationListTool = (server) => {
     server.registerTool('migration-list', {
+        annotations: createToolAnnotations(),
         description: 'List available migration documents for a Synergy package in a compact, token-efficient format.',
         inputSchema: {
             synergyPackage: z.enum([
@@ -76,11 +77,11 @@ export const migrationListTool = (server) => {
                 'components',
                 'styles',
                 'tokens',
-            ]).default('components').optional().describe('The package to list migration documents for.'),
+            ]).optional().describe('The package to list migration documents for.'),
         },
         title: 'Package Migration Document Index',
-    }, async ({ synergyPackage }) => {
-        const selectedPackage = (synergyPackage ?? 'components');
+    }, toolHandler('migration-list', async ({ synergyPackage }) => {
+        const selectedPackage = (synergyPackage ?? getRuntimeConfig().tools.migrationList.synergyPackage);
         const metadata = await getMigrationMetaData(selectedPackage);
         const index = metadata
             .filter(Boolean)
@@ -110,13 +111,6 @@ export const migrationListTool = (server) => {
                 ...extra,
             };
         });
-        return {
-            content: [
-                {
-                    text: JSON.stringify(index, null, 2),
-                    type: 'text',
-                },
-            ],
-        };
-    });
+        return [JSON.stringify(index, null, 2)];
+    }));
 };

package/dist/tools/setup.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Setup entrypoint for Synergy packages and framework-specific setup guidance.
+ * @param server - The MCP server instance to register the tool on.
+ */
+export declare const setupTool: (server: McpServer) => void;

package/dist/tools/setup.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { getDataForSetup } from '@synergy-design-system/metadata';
+import { createToolAnnotations, getRuntimeConfig, toolHandler, } from '../utilities/index.js';
+/**
+ * Setup entrypoint for Synergy packages and framework-specific setup guidance.
+ * @param server - The MCP server instance to register the tool on.
+ */
+export const setupTool = (server) => {
+    server.registerTool('setup', {
+        annotations: createToolAnnotations(),
+        description: 'Get setup information for a Synergy package. Framework packages (react, vue, angular) automatically include base components setup.',
+        inputSchema: {
+            includeLimitations: z.boolean().optional().describe('Add a list of known limitations and issues to the output.'),
+            package: z.enum(['components', 'react', 'vue', 'angular', 'tokens', 'styles', 'fonts', 'assets', 'migrations']).describe('Synergy package to retrieve setup instructions for.'),
+        },
+        title: 'Setup info',
+    }, toolHandler('setup', async ({ includeLimitations, package: packageName, }) => {
+        const resolvedIncludeLimitations = includeLimitations ?? getRuntimeConfig().tools.setup.includeLimitations;
+        const response = await getDataForSetup({
+            includeLimitations: resolvedIncludeLimitations,
+            package: packageName,
+        });
+        if (!response.data) {
+            return [response.errors?.[0]?.message ?? `No setup data found for package "${packageName}".`];
+        }
+        const setupContent = response.data.setups
+            .flatMap((entry) => entry.text)
+            .map((entry) => entry.content);
+        return setupContent;
+    }));
+};

package/dist/tools/styles-info.d.ts

@@ -1,7 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**
- * Simple tool to list all available tokens in the Synergy Design System.
- * This tool fetches the token data from the Synergy package and formats it for display.
+ * Simple tool to retrieve information about a given style in the Synergy Design System.
  * @param server - The MCP server instance to register the tool on.
  */
 export declare const stylesInfoTool: (server: McpServer) => void;

package/dist/tools/styles-info.js

@@ -1,28 +1,32 @@
-import { getStructuredMetaData, getStylesMetaData, } from '../utilities/index.js';
+import { z } from 'zod';
+import { getDataForStyle, } from '@synergy-design-system/metadata';
+import { createToolAnnotations, getToolRule, toolHandler, } from '../utilities/index.js';
 /**
- * Simple tool to list all available tokens in the Synergy Design System.
- * This tool fetches the token data from the Synergy package and formats it for display.
+ * Simple tool to retrieve information about a given style in the Synergy Design System.
  * @param server - The MCP server instance to register the tool on.
  */
 export const stylesInfoTool = (server) => {
     server.registerTool('styles-info', {
+        annotations: createToolAnnotations(),
         description: 'Get information about css utilities available in the Synergy Design System',
-        inputSchema: {},
+        inputSchema: {
+            style: z.string().describe('The name of the style to get information about.'),
+        },
         title: 'Styles info',
-    }, async () => {
-        const metadata = await getStylesMetaData();
-        const aiRules = await getStructuredMetaData('../../metadata/static/styles');
-        return {
-            content: [
-                {
-                    text: JSON.stringify(aiRules, null, 2),
-                    type: 'text',
-                },
-                {
-                    text: JSON.stringify(metadata, null, 2),
-                    type: 'text',
-                },
-            ],
-        };
-    });
+    }, toolHandler('styles-info', async ({ style, }) => {
+        const response = await getDataForStyle(style, { layer: 'examples' });
+        if (!response.data) {
+            return [
+                `No style found: ${style}`,
+            ];
+        }
+        const aiRules = await getToolRule('styles-info');
+        const markdownContent = response.data.examples
+            ?.map((entry) => entry.content)
+            .join('\n\n') ?? '';
+        return [
+            aiRules,
+            markdownContent,
+        ];
+    }));
 };

package/dist/tools/styles-list.js

@@ -1,4 +1,5 @@
-import { getAvailableStyles, getStructuredMetaData, } from '../utilities/index.js';
+import { listStyles } from '@synergy-design-system/metadata';
+import { createToolAnnotations, getToolRule, toolHandler, } from '../utilities/index.js';
 /**
  * Simple tool to list all available styles in the Synergy Design System.
  * This tool fetches the styles data from the Synergy package and formats it for display.
@@ -6,37 +7,22 @@ import { getAvailableStyles, getStructuredMetaData, } from '../utilities/index.j
  */
 export const stylesList = (server) => {
     server.registerTool('styles-list', {
-        description: 'Outputs a list of available styles in the Synergy Design System',
+        annotations: createToolAnnotations(),
+        description: 'Outputs a list of available css classes and styles in the Synergy Design System',
         inputSchema: {},
-        title: 'List Synergy Styles',
-    }, async () => {
-        // Get the package data for styles
-        try {
-            const styles = await getAvailableStyles();
-            const styleNames = styles.map(style => `- ${style}`);
-            const aiRules = await getStructuredMetaData('../../metadata/static/styles');
-            return {
-                content: [
-                    {
-                        text: JSON.stringify(aiRules, null, 2),
-                        type: 'text',
-                    },
-                    {
-                        text: styleNames.join('\n'),
-                        type: 'text',
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        text: `Error fetching components: ${error.message}`,
-                        type: 'text',
-                    },
-                ],
-            };
-        }
-    });
+        title: 'Styles list',
+    }, toolHandler('styles-list', async () => {
+        const aiRules = await getToolRule('styles-list');
+        const styles = await listStyles({
+            includeLayerRefs: false,
+            includeSources: false,
+        });
+        const styleNames = styles.data
+            .map(c => c.name)
+            .toSorted();
+        return [
+            aiRules,
+            styleNames,
+        ];
+    }));
 };

package/dist/tools/template-info.js

@@ -1,33 +1,32 @@
 import { z } from 'zod';
-import { getInfoForTemplate, getStructuredMetaData, } from '../utilities/index.js';
+import { getDataForTemplate, } from '@synergy-design-system/metadata';
+import { createToolAnnotations, getToolRule, toolHandler, } from '../utilities/index.js';
 /**
  * Simple tool to retrieve information about a given template in the Synergy Design System.
  * @param server - The MCP server instance to register the tool on.
  */
 export const templateInfoTool = (server) => {
     server.registerTool('template-info', {
+        annotations: createToolAnnotations(),
         description: 'Get a specific template in the Synergy Design System',
         inputSchema: {
             template: z.string().describe('The name of the template to get information about.'),
         },
         title: 'Template info',
-    }, async ({ template, }) => {
-        const data = await getInfoForTemplate(template);
-        const text = data && data.length > 0
-            ? JSON.stringify(data, null, 2)
-            : `No metadata found for template ${template}`;
-        const aiRules = await getStructuredMetaData('../../metadata/static/templates', file => file === 'index.md');
-        return {
-            content: [
-                {
-                    text: JSON.stringify(aiRules, null, 2),
-                    type: 'text',
-                },
-                {
-                    text,
-                    type: 'text',
-                },
-            ],
-        };
-    });
+    }, toolHandler('template-info', async ({ template, }) => {
+        const response = await getDataForTemplate(template, { layer: 'examples' });
+        if (!response.data) {
+            return [
+                `No template found: ${template}`,
+            ];
+        }
+        const aiRules = await getToolRule('template-info');
+        const markdownContent = response.data.examples
+            ?.map((entry) => entry.content)
+            .join('\n\n') ?? '';
+        return [
+            aiRules,
+            markdownContent,
+        ];
+    }));
 };

package/dist/tools/template-list.d.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**
  * Simple tool to list all available templates in the Synergy Design System.
- * This tool fetches the templates data from the Synergy package and formats it for display.
+ * This tool fetches the templates data from the metadata store and formats it for display.
  * @param server - The MCP server instance to register the tool on.
  */
 export declare const templateList: (server: McpServer) => void;

package/dist/tools/template-list.js

@@ -1,42 +1,27 @@
-import { getAvailableTemplates, getStructuredMetaData, } from '../utilities/index.js';
+import { listTemplates, } from '@synergy-design-system/metadata';
+import { createToolAnnotations, getToolRule, toolHandler, } from '../utilities/index.js';
 /**
  * Simple tool to list all available templates in the Synergy Design System.
- * This tool fetches the templates data from the Synergy package and formats it for display.
+ * This tool fetches the templates data from the metadata store and formats it for display.
  * @param server - The MCP server instance to register the tool on.
  */
 export const templateList = (server) => {
     server.registerTool('template-list', {
+        annotations: createToolAnnotations(),
         description: 'Outputs a list of available static templates built with the Synergy Design System',
         inputSchema: {},
         title: 'List Synergy Templates',
-    }, async () => {
-        // Get the package data for templates
-        try {
-            const templates = await getAvailableTemplates();
-            const templateNames = templates.map(template => `- ${template}`);
-            const aiRules = await getStructuredMetaData('../../metadata/static/templates', file => file === 'index.md');
-            return {
-                content: [
-                    {
-                        text: JSON.stringify(aiRules, null, 2),
-                        type: 'text',
-                    },
-                    {
-                        text: templateNames.join('\n'),
-                        type: 'text',
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        text: `Error fetching templates: ${error.message}`,
-                        type: 'text',
-                    },
-                ],
-            };
-        }
-    });
+    }, toolHandler('template-list', async () => {
+        const response = await listTemplates();
+        const templateNames = response.data
+            .map(template => template.name)
+            .sort()
+            .map(name => `- ${name}`)
+            .join('\n');
+        const aiRules = await getToolRule('template-list');
+        return [
+            aiRules,
+            templateNames,
+        ];
+    }));
 };

package/dist/tools/{tokens.d.ts → token-info.d.ts}

@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**
- * Simple tool to list all available tokens in the Synergy Design System.
- * This tool fetches the token data from the Synergy package and formats it for display.
+ * Simple tool to return raw token file contents from the Synergy Design System.
+ * This tool fetches the filtered token artifact content and returns the content blocks directly.
  * @param server - The MCP server instance to register the tool on.
  */
 export declare const tokenInfoTool: (server: McpServer) => void;

package/dist/tools/token-info.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { getDataForTokens, } from '@synergy-design-system/metadata';
+import { createToolAnnotations, getRuntimeConfig, toolHandler, } from '../utilities/index.js';
+/**
+ * Simple tool to return raw token file contents from the Synergy Design System.
+ * This tool fetches the filtered token artifact content and returns the content blocks directly.
+ * @param server - The MCP server instance to register the tool on.
+ */
+export const tokenInfoTool = (server) => {
+    server.registerTool('token-info', {
+        annotations: createToolAnnotations(),
+        description: 'Get raw design token file contents from the Synergy Design System',
+        inputSchema: {
+            theme: z.enum(['sick2025-light', 'sick2025-dark', 'sick2018-light', 'sick2018-dark']).optional().describe('Theme variant for CSS tokens. Ignored for javascript and sass.'),
+            type: z.enum(['javascript', 'css', 'sass']).optional().describe('The type of token output to retrieve.'),
+        },
+        title: 'Token info',
+    }, toolHandler('token-info', async ({ theme, type, }) => {
+        const resolvedType = type ?? getRuntimeConfig().tools.tokenInfo.type;
+        const response = await getDataForTokens({
+            format: resolvedType,
+            theme,
+        });
+        if (response.data.tokens.length === 0) {
+            return [
+                `No tokens found for type "${resolvedType}"${theme ? ` and theme "${theme}"` : ''}.`,
+            ];
+        }
+        return response.data.tokens.map((item) => item.content);
+    }));
+};

package/dist/tools/tokens-list.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Simple tool to list available token output types and theme variants.
+ * @param server - The MCP server instance to register the tool on.
+ */
+export declare const tokenListTool: (server: McpServer) => void;

package/dist/tools/tokens-list.js

@@ -0,0 +1,52 @@
+import { getDataForTokens, } from '@synergy-design-system/metadata';
+import { createToolAnnotations, toolHandler, } from '../utilities/index.js';
+/**
+ * Simple tool to list available token output types and theme variants.
+ * @param server - The MCP server instance to register the tool on.
+ */
+export const tokenListTool = (server) => {
+    server.registerTool('tokens-list', {
+        annotations: createToolAnnotations(),
+        description: 'Outputs a list of available token output types and css themes in the Synergy Design System',
+        inputSchema: {},
+        title: 'Tokens list',
+    }, toolHandler('tokens-list', async () => {
+        const cssCandidates = ['sick2018-dark', 'sick2018-light', 'sick2025-dark', 'sick2025-light'];
+        const cssChecks = await Promise.all(cssCandidates.map(async (theme) => {
+            const result = await getDataForTokens({
+                format: 'css',
+                theme,
+            });
+            return {
+                hasTokens: result.data.tokens.length > 0,
+                theme,
+            };
+        }));
+        const javascriptResult = await getDataForTokens({
+            format: 'javascript',
+        });
+        const sassResult = await getDataForTokens({
+            format: 'sass',
+        });
+        const cssThemes = cssChecks
+            .filter(entry => entry.hasTokens)
+            .map(entry => entry.theme)
+            .sort();
+        const hasJavascript = javascriptResult.data.tokens.length > 0;
+        const hasSass = sassResult.data.tokens.length > 0;
+        return [{
+                defaults: {
+                    tokenInfo: {
+                        theme: 'sick2025-light',
+                        type: 'css',
+                    },
+                },
+                supportedTypes: [
+                    ...(cssThemes.length > 0 ? ['css'] : []),
+                    ...(hasJavascript ? ['javascript'] : []),
+                    ...(hasSass ? ['sass'] : []),
+                ],
+                themes: [...cssThemes].sort(),
+            }];
+    }));
+};

package/dist/transports/http.d.ts

@@ -0,0 +1,14 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpRuntimeConfig } from '../utilities/config.js';
+import type { TransportInstance } from './index.js';
+/**
+ * Creates an HTTP or HTTPS transport for the MCP server.
+ * Serves the MCP protocol on a fixed /mcp endpoint.
+ * Each client session gets its own transport + server instance,
+ * tracked by the mcp-session-id header.
+ *
+ * @param serverFactory A factory function that creates a new MCP server instance per session
+ * @param config The runtime configuration with interface, port, and optional TLS settings
+ * @returns A transport instance
+ */
+export declare function createHttpTransport(serverFactory: () => McpServer, config: McpRuntimeConfig): Promise<TransportInstance>;

package/dist/transports/http.js

@@ -0,0 +1,157 @@
+/* eslint-disable complexity */
+/* eslint-disable @typescript-eslint/no-misused-promises */
+import { randomUUID } from 'node:crypto';
+import { createServer as createHttpServer, } from 'node:http';
+import { createServer as createHttpsServer, } from 'node:https';
+import { readFileSync } from 'node:fs';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { getMetadataInfo } from '@synergy-design-system/metadata';
+import { runWithLoggingContext } from '../utilities/logging-context.js';
+/**
+ * Creates an HTTP or HTTPS transport for the MCP server.
+ * Serves the MCP protocol on a fixed /mcp endpoint.
+ * Each client session gets its own transport + server instance,
+ * tracked by the mcp-session-id header.
+ *
+ * @param serverFactory A factory function that creates a new MCP server instance per session
+ * @param config The runtime configuration with interface, port, and optional TLS settings
+ * @returns A transport instance
+ */
+export async function createHttpTransport(serverFactory, config) {
+    const { host, port, tls } = config;
+    const hasValidTls = tls?.keyPath && tls?.certPath;
+    // Resolve metadata version info once at startup for use in response headers
+    let metadataVersion;
+    let metadataBuildDate;
+    try {
+        const info = await getMetadataInfo();
+        metadataVersion = info.version;
+        metadataBuildDate = info.builtAt;
+    }
+    catch {
+        process.stderr.write('[synergy-mcp] Warning: could not read metadata version info\n');
+    }
+    // Read TLS files if HTTPS is enabled
+    let keyContent;
+    let certContent;
+    if (hasValidTls) {
+        try {
+            keyContent = readFileSync(tls.keyPath);
+            certContent = readFileSync(tls.certPath);
+        }
+        catch (error) {
+            throw new Error(`Failed to read TLS files: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Create the appropriate server
+    let nodeServer;
+    let protocol = 'http';
+    if (hasValidTls && keyContent && certContent) {
+        protocol = 'https';
+        nodeServer = createHttpsServer({
+            cert: certContent,
+            key: keyContent,
+        });
+    }
+    else {
+        nodeServer = createHttpServer();
+    }
+    // Session store: maps mcp-session-id -> transport for that client
+    const sessions = new Map();
+    // Create request handler that routes to the transport
+    nodeServer.on('request', async (req, res) => {
+        // Route only /mcp requests to the transport
+        const url = req.url || '/';
+        if (!url.startsWith('/mcp')) {
+            res.statusCode = 404;
+            res.setHeader('Content-Type', 'text/plain');
+            res.end('Not Found\n');
+            return;
+        }
+        // Expose metadata version info on every /mcp response
+        if (metadataVersion !== undefined) {
+            res.setHeader('x-synergy-metadata-version', metadataVersion);
+        }
+        if (metadataBuildDate !== undefined) {
+            res.setHeader('x-synergy-metadata-build-date', metadataBuildDate);
+        }
+        try {
+            const sessionId = req.headers['mcp-session-id'];
+            if (sessionId) {
+                // Route to existing session
+                const existing = sessions.get(sessionId);
+                if (!existing) {
+                    res.statusCode = 400;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify({
+                        error: { code: -32000, message: 'Unknown session ID' },
+                        id: null,
+                        jsonrpc: '2.0',
+                    }));
+                    return;
+                }
+                await runWithLoggingContext({
+                    sessionId,
+                    transport: 'http',
+                }, async () => existing.handleRequest(req, res));
+                return;
+            }
+            // New client — create a dedicated server + transport pair
+            const newServer = serverFactory();
+            const transport = new StreamableHTTPServerTransport({
+                onsessioninitialized: sid => {
+                    sessions.set(sid, transport);
+                },
+                sessionIdGenerator: () => randomUUID(),
+            });
+            transport.onclose = () => {
+                if (transport.sessionId) {
+                    sessions.delete(transport.sessionId);
+                }
+            };
+            await newServer.connect(transport);
+            await runWithLoggingContext({
+                sessionId: transport.sessionId ?? 'pending-http',
+                transport: 'http',
+            }, async () => transport.handleRequest(req, res));
+        }
+        catch (error) {
+            // Only write error response if headers haven't been sent yet
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader('Content-Type', 'text/plain');
+                res.end('Internal Server Error\n');
+            }
+            process.stderr.write(`[synergy-mcp] HTTP handler error: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    });
+    return {
+        start: async () => new Promise((resolve, reject) => {
+            nodeServer.on('error', (error) => {
+                if (error.code === 'EADDRINUSE') {
+                    reject(new Error(`Port ${port} is already in use. Please choose a different port.`));
+                }
+                else {
+                    reject(new Error(`Server error: ${error instanceof Error ? error.message : String(error)}`));
+                }
+            });
+            nodeServer.on('listening', () => {
+                process.stdout.write(`[synergy-mcp] ✓ ${protocol.toUpperCase()} server started at ${protocol}://${host}:${port}\n`);
+                process.stdout.write(`[synergy-mcp] ✓ MCP endpoint: ${protocol}://${host}:${port}/mcp\n`);
+                resolve();
+            });
+            nodeServer.listen(port, host);
+        }),
+        stop: async () => new Promise((resolve, reject) => {
+            nodeServer.close((error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    process.stdout.write('[synergy-mcp] ✓ Server stopped\n');
+                    resolve();
+                }
+            });
+        }),
+    };
+}

package/dist/transports/index.d.ts

@@ -0,0 +1,23 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpRuntimeConfig } from '../utilities/config.js';
+/**
+ * Common interface for all transport implementations.
+ */
+export interface TransportInstance {
+    /** Start listening for connections. */
+    start: () => Promise<void>;
+    /** Optional: Stop listening for connections. */
+    stop?: () => Promise<void>;
+}
+/**
+ * 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 declare function createTransport(serverFactory: () => McpServer, config: McpRuntimeConfig): Promise<TransportInstance>;