@synergy-design-system/mcp 3.7.0 → 3.8.0

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.8.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.8.0",
   "scripts": {
     "debug": "npx @modelcontextprotocol/inspector",
     "build": "pnpm run clean && tsc",