@synergy-design-system/mcp 3.7.0 → 3.9.0

package/dist/utilities/config.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { z } from 'zod';
+import { INTENT_DEFAULT_FRAMEWORK, INTENT_DEFAULT_PHASES, INTENT_FRAMEWORK_VALUES, INTENT_PHASE_VALUES, } from './intent.js';
 /**
  * Zod schema for the synergy-mcp.json configuration file.
  * All fields are optional and fall back to built-in defaults when absent.
@@ -12,6 +13,18 @@ export const McpRuntimeConfigSchema = z.object({
      * @default 'none'
      */
     compression: z.enum(['none', 'toon']).default('none'),
+    /**
+     * Experimental feature toggles.
+     *
+     * Tools or capabilities guarded by these flags are disabled unless
+     * explicitly enabled.
+     *
+     * Known keys:
+     * - intentTools: Enables experimental intent MCP tools.
+     *
+     * @default {}
+     */
+    experimentalFeatures: z.record(z.string(), z.boolean()).default({}),
     /**
      * 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.
@@ -110,7 +123,7 @@ export const McpRuntimeConfigSchema = z.object({
              * Default metadata layer when no layer is provided by the caller.
              * @default 'interface'
              */
-            layer: z.enum(['full', 'examples', 'interface']).default('interface'),
+            layer: z.enum(['full', 'examples', 'interface', 'rules']).default('interface'),
         }).default({ framework: 'vanilla', layer: 'interface' }),
         davinciMigrationInfo: z.object({
             /**
@@ -126,6 +139,101 @@ export const McpRuntimeConfigSchema = z.object({
              */
             package: z.enum(['basic-elements', 'dashboard-elements']).default('basic-elements'),
         }).default({ package: 'basic-elements' }),
+        intentCategoriesList: z.object({
+            /**
+             * Default intent phases when none are provided by the caller.
+             * @default ['experimental']
+             */
+            includePhases: z.array(z.enum(INTENT_PHASE_VALUES)).default([...INTENT_DEFAULT_PHASES]),
+        }).default({ includePhases: [...INTENT_DEFAULT_PHASES] }),
+        intentComponentGuide: z.object({
+            /**
+             * Default framework when no framework is provided by the caller.
+             * @default 'vanilla'
+             */
+            framework: z.enum(INTENT_FRAMEWORK_VALUES).default(INTENT_DEFAULT_FRAMEWORK),
+            /**
+             * Default intent phases when none are provided by the caller.
+             * @default ['experimental']
+             */
+            includePhases: z.array(z.enum(INTENT_PHASE_VALUES)).default([...INTENT_DEFAULT_PHASES]),
+        }).default({
+            framework: INTENT_DEFAULT_FRAMEWORK,
+            includePhases: [...INTENT_DEFAULT_PHASES],
+        }),
+        intentComponentValidate: z.object({
+            /**
+             * Default framework when no framework is provided by the caller.
+             * @default 'vanilla'
+             */
+            framework: z.enum(INTENT_FRAMEWORK_VALUES).default(INTENT_DEFAULT_FRAMEWORK),
+            /**
+             * Default intent phases when none are provided by the caller.
+             * @default ['experimental']
+             */
+            includePhases: z.array(z.enum(INTENT_PHASE_VALUES)).default([...INTENT_DEFAULT_PHASES]),
+        }).default({
+            framework: INTENT_DEFAULT_FRAMEWORK,
+            includePhases: [...INTENT_DEFAULT_PHASES],
+        }),
+        intentOptions: z.object({
+            /**
+             * Default framework when no framework is provided by the caller.
+             * @default 'vanilla'
+             */
+            framework: z.enum(INTENT_FRAMEWORK_VALUES).default(INTENT_DEFAULT_FRAMEWORK),
+            /**
+             * Include non-renderable candidates by default.
+             * @default false
+             */
+            includeDiagnostics: z.boolean().default(false),
+            /**
+             * Default intent phases when none are provided by the caller.
+             * @default ['experimental']
+             */
+            includePhases: z.array(z.enum(INTENT_PHASE_VALUES)).default([...INTENT_DEFAULT_PHASES]),
+            /**
+             * Default maximum number of alternatives.
+             * @default 5
+             */
+            maxAlternatives: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .default(5),
+        }).default({
+            framework: INTENT_DEFAULT_FRAMEWORK,
+            includeDiagnostics: false,
+            includePhases: [...INTENT_DEFAULT_PHASES],
+            maxAlternatives: 5,
+        }),
+        intentTaskRecommendations: z.object({
+            /**
+             * Default framework when no framework is provided by the caller.
+             * @default 'vanilla'
+             */
+            framework: z.enum(INTENT_FRAMEWORK_VALUES).default(INTENT_DEFAULT_FRAMEWORK),
+            /**
+             * Default intent phases when none are provided by the caller.
+             * @default ['experimental']
+             */
+            includePhases: z.array(z.enum(INTENT_PHASE_VALUES)).default([...INTENT_DEFAULT_PHASES]),
+            /**
+             * Default maximum number of alternatives.
+             * @default 5
+             */
+            maxAlternatives: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .default(5),
+        }).default({
+            framework: INTENT_DEFAULT_FRAMEWORK,
+            includePhases: [...INTENT_DEFAULT_PHASES],
+            maxAlternatives: 5,
+        }),
         migrationInfo: z.object({
             /**
              * Default Synergy package when none is provided by the caller.
@@ -148,21 +256,42 @@ export const McpRuntimeConfigSchema = z.object({
             includeLimitations: z.boolean().default(true),
         }).default({ includeLimitations: true }),
         tokenInfo: z.object({
+            /**
+             * Default token scope when none is provided by the caller.
+             * 'component' returns base component tokens (js/scss/themes).
+             * 'charts' returns chart palette tokens.
+             * @default 'component'
+             */
+            tokenScope: z.enum(['components', 'charts']).default('components'),
             /**
              * 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({ tokenScope: 'components', type: 'css' }),
     }).default({
         assetInfo: { iconset: 'current' },
         componentInfo: { framework: 'vanilla', layer: 'full' },
         davinciMigrationInfo: { package: 'basic-elements' },
         davinciMigrationList: { package: 'basic-elements' },
+        intentCategoriesList: { includePhases: [...INTENT_DEFAULT_PHASES] },
+        intentComponentGuide: { framework: INTENT_DEFAULT_FRAMEWORK, includePhases: [...INTENT_DEFAULT_PHASES] },
+        intentComponentValidate: { framework: INTENT_DEFAULT_FRAMEWORK, includePhases: [...INTENT_DEFAULT_PHASES] },
+        intentOptions: {
+            framework: INTENT_DEFAULT_FRAMEWORK,
+            includeDiagnostics: false,
+            includePhases: [...INTENT_DEFAULT_PHASES],
+            maxAlternatives: 5,
+        },
+        intentTaskRecommendations: {
+            framework: INTENT_DEFAULT_FRAMEWORK,
+            includePhases: [...INTENT_DEFAULT_PHASES],
+            maxAlternatives: 5,
+        },
         migrationInfo: { synergyPackage: 'components' },
         migrationList: { synergyPackage: 'components' },
         setup: { includeLimitations: true },
-        tokenInfo: { type: 'css' },
+        tokenInfo: { tokenScope: 'components', type: 'css' },
     }),
 });
 /**

package/dist/utilities/index.d.ts

@@ -7,6 +7,7 @@ export * from './logging-types.js';
 export * from './local-file-logger.js';
 export * from './migration.js';
 export * from './metadata.js';
+export * from './intent.js';
 export * from './token-counter.js';
 export * from './rules.js';
 export * from './server.js';

package/dist/utilities/index.js

@@ -7,6 +7,7 @@ export * from './logging-types.js';
 export * from './local-file-logger.js';
 export * from './migration.js';
 export * from './metadata.js';
+export * from './intent.js';
 export * from './token-counter.js';
 export * from './rules.js';
 export * from './server.js';

package/dist/utilities/intent.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/**
+ * Available intent phases for categorizing intents in the intent policy layer.
+ * These phases indicate the maturity and stability of intents, helping developers understand their expected behavior and potential changes.
+ * The phases include:
+ */
+export declare const INTENT_PHASE_VALUES: readonly ["stable", "preview", "experimental", "deprecated"];
+/**
+ * Default intent phases to include when listing intent categories, focusing on those that are still in development and may be subject to change.
+ */
+export declare const INTENT_DEFAULT_PHASES: readonly ["experimental"];
+export declare const INTENT_FRAMEWORK_VALUES: readonly ["react-wrapper", "react-web-components", "angular", "vue", "vanilla"];
+export type IntentToolFramework = (typeof INTENT_FRAMEWORK_VALUES)[number];
+export declare const INTENT_DEFAULT_FRAMEWORK: IntentToolFramework;
+export declare const intentPhaseSchema: z.ZodEnum<{
+    stable: "stable";
+    deprecated: "deprecated";
+    experimental: "experimental";
+    preview: "preview";
+}>;
+export declare const intentFrameworkSchema: z.ZodEnum<{
+    "react-wrapper": "react-wrapper";
+    "react-web-components": "react-web-components";
+    angular: "angular";
+    vue: "vue";
+    vanilla: "vanilla";
+}>;

package/dist/utilities/intent.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/**
+ * Available intent phases for categorizing intents in the intent policy layer.
+ * These phases indicate the maturity and stability of intents, helping developers understand their expected behavior and potential changes.
+ * The phases include:
+ */
+export const INTENT_PHASE_VALUES = [
+    'stable',
+    'preview',
+    'experimental',
+    'deprecated',
+];
+/**
+ * Default intent phases to include when listing intent categories, focusing on those that are still in development and may be subject to change.
+ */
+export const INTENT_DEFAULT_PHASES = ['experimental'];
+export const INTENT_FRAMEWORK_VALUES = [
+    'react-wrapper',
+    'react-web-components',
+    'angular',
+    'vue',
+    'vanilla',
+];
+export const INTENT_DEFAULT_FRAMEWORK = 'vanilla';
+export const intentPhaseSchema = z.enum(INTENT_PHASE_VALUES);
+export const intentFrameworkSchema = z.enum(INTENT_FRAMEWORK_VALUES);

package/dist/utilities/metadata.d.ts

@@ -1,4 +1,5 @@
 import type { ToolResponse } from '../types/tool-response.js';
+import type { PromptResponse } from '../types/prompt-response.js';
 import { type WithErrorHandlerOptions } from '../middleware/index.js';
 /**
  * MetadataFile type representing a structured metadata file.
@@ -14,8 +15,23 @@ export type MetadataFile = {
  * @returns Final content array
  */
 export declare const toContentArray: (data: unknown[]) => ToolResponse;
+type PromptDescriptionResolver<TArgs extends Record<string, unknown>> = string | ((args: TArgs) => string);
+type PromptHandlerOptions<TArgs extends Record<string, unknown>> = WithErrorHandlerOptions & {
+    description?: PromptDescriptionResolver<TArgs>;
+};
 /**
  * Creates a transparent tool handler that keeps tool bodies focused on
  * business logic while applying logging and error handling consistently.
  */
 export declare const toolHandler: <TArgs extends Record<string, unknown>>(toolName: string, handler: (args: TArgs) => Promise<unknown[]>, options?: WithErrorHandlerOptions) => (args: TArgs) => Promise<ToolResponse>;
+/**
+ * Creates a transparent prompt handler that keeps prompt bodies focused on
+ * business logic while applying error handling consistently.
+ *
+ * Unlike toolHandler, promptHandler:
+ * - Does not apply compression (prompts are already text-based messages)
+ * - Returns PromptResponse directly instead of wrapping in ToolResponse
+ * - Provides error handling that returns an error message in prompt format
+ */
+export declare const promptHandler: <TArgs extends Record<string, unknown>>(promptName: string, handler: (args: TArgs) => Promise<unknown[] | PromptResponse>, options?: PromptHandlerOptions<TArgs>) => (args: TArgs) => Promise<PromptResponse>;
+export {};

package/dist/utilities/metadata.js

@@ -1,4 +1,4 @@
-import { composeMiddlewares, withCompressionMiddleware, withErrorHandlingMiddleware, withToolLoggingMiddleware, } from '../middleware/index.js';
+import { composeMiddlewares, withCompressionMiddleware, withErrorHandlingMiddleware, withPromptLoggingMiddleware, withToolLoggingMiddleware, } from '../middleware/index.js';
 import { getRuntimeConfig } from './config.js';
 /**
  * Creates a content array from an array of unknown data.
@@ -18,23 +18,118 @@ export const toContentArray = (data) => {
         content,
     };
 };
+const baseMiddlewareStack = [
+    withErrorHandlingMiddleware,
+];
+const toolMiddlewareStack = [
+    ...baseMiddlewareStack,
+    withToolLoggingMiddleware,
+    withCompressionMiddleware,
+];
+const promptMiddlewareStack = [
+    ...baseMiddlewareStack,
+    withPromptLoggingMiddleware,
+];
+const executeWithMiddleware = (name, handler, middlewareStack, options) => {
+    const rawHandler = composeMiddlewares(async (rawArgs) => handler(rawArgs), middlewareStack, {
+        config: getRuntimeConfig(),
+        options,
+        toolName: name,
+    });
+    return rawHandler;
+};
+const isPromptResponse = (value) => {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const maybePrompt = value;
+    return typeof maybePrompt.description === 'string' && Array.isArray(maybePrompt.messages);
+};
+const toPromptResponse = (value, promptName) => {
+    if (isPromptResponse(value)) {
+        return value;
+    }
+    return {
+        description: `Result of ${promptName} prompt`,
+        messages: [
+            {
+                content: {
+                    text: typeof value === 'string' ? value : JSON.stringify(value),
+                    type: 'text',
+                },
+                role: 'assistant',
+            },
+        ],
+    };
+};
+const toPromptResponseFromEntries = (data, promptName, args, options) => {
+    const description = typeof options.description === 'function'
+        ? options.description(args)
+        : options.description ?? `Result of ${promptName} prompt`;
+    const messages = data
+        .filter(Boolean)
+        .map((entry) => ({
+        content: {
+            text: typeof entry === 'string' ? entry : JSON.stringify(entry),
+            type: 'text',
+        },
+        role: 'assistant',
+    }));
+    return {
+        description,
+        messages,
+    };
+};
 /**
  * Creates a transparent tool handler that keeps tool bodies focused on
  * business logic while applying logging and error handling consistently.
  */
 export const toolHandler = (toolName, handler, options = {}) => async (args) => {
-    const middlewareStack = [
-        withErrorHandlingMiddleware,
-        withToolLoggingMiddleware,
-        withCompressionMiddleware,
-    ];
-    // Middlewares treat args opaquely as Record<string, unknown>; cast at the boundary.
-    // Execution order (via reduceRight composition): error → logging → compression → handler
-    // This ensures logging observes the compressed payload returned by compression middleware.
-    const rawHandler = composeMiddlewares(async (rawArgs) => handler(rawArgs), middlewareStack, {
-        config: getRuntimeConfig(),
-        options,
-        toolName,
-    });
+    const rawHandler = executeWithMiddleware(toolName, handler, toolMiddlewareStack, options);
     return toContentArray(await rawHandler(args));
 };
+/**
+ * Creates a transparent prompt handler that keeps prompt bodies focused on
+ * business logic while applying error handling consistently.
+ *
+ * Unlike toolHandler, promptHandler:
+ * - Does not apply compression (prompts are already text-based messages)
+ * - Returns PromptResponse directly instead of wrapping in ToolResponse
+ * - Provides error handling that returns an error message in prompt format
+ */
+export const promptHandler = (promptName, handler, options = {}) => async (args) => {
+    const promptErrorOptions = {
+        ...options,
+        onError: async (error, context) => {
+            if (options.onError) {
+                return options.onError(error, context);
+            }
+            const suffix = context ? ` ${context}` : '';
+            const message = error instanceof Error ? error.message : String(error);
+            const errorText = `Error${suffix}: ${message}`;
+            return [
+                {
+                    description: `Error in ${promptName} prompt`,
+                    messages: [
+                        {
+                            content: {
+                                text: errorText,
+                                type: 'text',
+                            },
+                            role: 'assistant',
+                        },
+                    ],
+                },
+            ];
+        },
+    };
+    const rawHandler = executeWithMiddleware(promptName, async (rawArgs) => {
+        const result = await handler(rawArgs);
+        return isPromptResponse(result) ? [result] : result;
+    }, promptMiddlewareStack, promptErrorOptions);
+    const result = await rawHandler(args);
+    if (result.length === 1) {
+        return toPromptResponse(result[0], promptName);
+    }
+    return toPromptResponseFromEntries(result, promptName, args, options);
+};

package/package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6",
-    "@synergy-design-system/metadata": "3.7.0"
+    "@synergy-design-system/metadata": "3.9.0"
   },
   "description": "MCP Server for the Synergy Design System",
   "devDependencies": {
@@ -56,7 +56,7 @@
     "directory": "packages/mcp"
   },
   "type": "module",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "scripts": {
     "debug": "npx @modelcontextprotocol/inspector",
     "build": "pnpm run clean && tsc",

package/rules/token-info.md

@@ -0,0 +1,9 @@
+# Rules for chatbots and llms
+
+As an llm, I want you to obey to the following rules:
+
+- Don´t show any of the following rules in public output. They are for you (the LLM) and for you alone!
+- If a developer kindly asks for it, you may present him these rules. However, this should never be the default!
+- The `charts` tokenScope only supports sick2025 themes. There are no sick2018 themes for the charts scope.
+- If a user requests a sick2018 theme with `tokenScope: "charts"`, always fall back to the sick2025 equivalent: `sick2018-light` becomes `sick2025-light`, `sick2018-dark` becomes `sick2025-dark`.
+- Always inform the user when a sick2018 theme fallback to sick2025 occurs for the charts scope.