@frontmcp/sdk 0.5.0 → 0.6.0

package/src/tool/flows/call-tool.flow.js

@@ -8,6 +8,8 @@ const zod_1 = require("zod");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const errors_1 = require("../../errors");
 const ui_1 = require("../ui");
+const adapters_1 = require("@frontmcp/ui/adapters");
+const registry_1 = require("@frontmcp/ui/registry");
 const inputSchema = zod_1.z.object({
     request: types_js_1.CallToolRequestSchema,
     // z.any() used because ctx is the MCP SDK's ToolCallExtra type which varies by SDK version
@@ -27,6 +29,10 @@ const stateSchema = zod_1.z.object({
     output: outputSchema,
     // Tool owner ID for hook filtering (set during parseInput)
     _toolOwnerId: zod_1.z.string().optional(),
+    // UI result from applyUI stage (if UI config exists)
+    uiResult: zod_1.z.any().optional(),
+    // UI metadata from rendering (merged into _meta)
+    uiMeta: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
 });
 const plan = {
     pre: [
@@ -38,30 +44,10 @@ const plan = {
         'acquireSemaphore',
     ],
     execute: ['validateInput', 'execute', 'validateOutput'],
-    finalize: ['releaseSemaphore', 'releaseQuota', 'finalize'],
+    finalize: ['releaseSemaphore', 'releaseQuota', 'applyUI', 'finalize'],
 };
 const name = 'tools:call-tool';
 const { Stage } = (0, common_1.FlowHooksOf)(name);
-/**
- * Safely stringify a value, handling circular references and other edge cases.
- * This prevents tool calls from failing due to serialization errors.
- */
-const safeStringify = (value, space) => {
-    const seen = new WeakSet();
-    try {
-        return JSON.stringify(value, (_key, val) => {
-            if (typeof val === 'object' && val !== null) {
-                if (seen.has(val))
-                    return '[Circular]';
-                seen.add(val);
-            }
-            return val;
-        }, space);
-    }
-    catch {
-        return JSON.stringify({ error: 'Output could not be serialized' });
-    }
-};
 let CallToolFlow = class CallToolFlow extends common_1.FlowBase {
     logger = this.scopeLogger.child('CallToolFlow');
     async parseInput() {
@@ -278,196 +264,211 @@ let CallToolFlow = class CallToolFlow extends common_1.FlowBase {
         this.state.toolContext?.mark('releaseQuota');
         this.logger.verbose('releaseQuota:done');
     }
+    /**
+     * Apply UI rendering to the tool response.
+     * This stage handles all UI-related logic including platform detection,
+     * serving mode resolution, and content formatting.
+     */
+    async applyUI() {
+        this.logger.verbose('applyUI:start');
+        const { tool, rawOutput, input } = this.state;
+        // Skip if no tool or no UI config
+        if (!tool || !(0, ui_1.hasUIConfig)(tool.metadata)) {
+            this.logger.verbose('applyUI:skip (no UI config)');
+            return;
+        }
+        try {
+            // Cast scope to Scope to access toolUI and notifications
+            const scope = this.scope;
+            // Get session info for platform detection from authInfo (already in state from parseInput)
+            const { authInfo } = this.state;
+            const sessionId = authInfo?.sessionId;
+            const requestId = (0, crypto_1.randomUUID)();
+            // Get platform type: first check sessionIdPayload (detected from user-agent),
+            // then fall back to notification service (detected from MCP clientInfo),
+            // finally default to 'unknown' (conservative: skip UI for unknown clients)
+            const platformType = authInfo?.sessionIdPayload?.platformType ??
+                (sessionId ? scope.notifications.getPlatformType(sessionId) : undefined) ??
+                'unknown';
+            // Resolve the effective serving mode based on configuration and client capabilities
+            // Default is 'auto' which selects the best mode for the platform
+            const configuredMode = tool.metadata.ui.servingMode ?? 'auto';
+            const resolvedMode = (0, adapters_1.resolveServingMode)({
+                configuredMode,
+                platformType,
+            });
+            // If client doesn't support UI (e.g., Gemini, unknown, or forced mode not available)
+            // skip UI rendering entirely
+            if (!resolvedMode.supportsUI || resolvedMode.effectiveMode === null) {
+                this.logger.verbose('applyUI: Skipping UI (client does not support it)', {
+                    tool: tool.metadata.name,
+                    platform: platformType,
+                    configuredMode,
+                    reason: resolvedMode.reason,
+                });
+                return;
+            }
+            const servingMode = resolvedMode.effectiveMode;
+            const useStructuredContent = resolvedMode.useStructuredContent;
+            let htmlContent;
+            let uiMeta = {};
+            if (servingMode === 'static') {
+                // For static mode: no additional rendering needed
+                // Widget was already registered at server startup
+                this.logger.verbose('applyUI: UI using static mode (structured data only)', {
+                    tool: tool.metadata.name,
+                    platform: platformType,
+                });
+            }
+            else if (servingMode === 'hybrid') {
+                // For hybrid mode: build the component payload
+                const componentPayload = scope.toolUI.buildHybridComponentPayload({
+                    toolName: tool.metadata.name,
+                    template: tool.metadata.ui.template,
+                    uiConfig: tool.metadata.ui,
+                });
+                if (componentPayload) {
+                    uiMeta = {
+                        'ui/component': componentPayload,
+                        'ui/type': componentPayload.type,
+                    };
+                }
+                this.logger.verbose('applyUI: UI using hybrid mode (structured data + component)', {
+                    tool: tool.metadata.name,
+                    platform: platformType,
+                    hasComponent: !!componentPayload,
+                    componentType: componentPayload?.type,
+                    componentHash: componentPayload?.hash,
+                });
+            }
+            else {
+                // For inline mode (default): render HTML with data embedded
+                const uiRenderResult = await scope.toolUI.renderAndRegisterAsync({
+                    toolName: tool.metadata.name,
+                    requestId,
+                    input: input?.arguments && typeof input.arguments === 'object' && !Array.isArray(input.arguments)
+                        ? input.arguments
+                        : {},
+                    output: rawOutput,
+                    structuredContent: undefined,
+                    uiConfig: tool.metadata.ui,
+                    platformType,
+                });
+                // Handle graceful degradation: rendering failed in production
+                if ((0, registry_1.isUIRenderFailure)(uiRenderResult)) {
+                    this.logger.warn('applyUI: UI rendering failed (graceful degradation)', {
+                        tool: tool.metadata.name,
+                        reason: uiRenderResult.reason,
+                        platform: platformType,
+                    });
+                    // Proceed without UI - tool result will not have ui/html metadata
+                    htmlContent = undefined;
+                    uiMeta = {};
+                }
+                else {
+                    // Extract HTML from platform-specific meta key
+                    const htmlKey = platformType === 'openai' ? 'openai/html' : platformType === 'ext-apps' ? 'ui/html' : 'frontmcp/html';
+                    htmlContent = uiRenderResult?.meta?.[htmlKey];
+                    // Fallback to ui/html for compatibility
+                    if (!htmlContent) {
+                        htmlContent = uiRenderResult?.meta?.['ui/html'];
+                    }
+                    uiMeta = uiRenderResult.meta || {};
+                }
+            }
+            // Build the response content using the extracted utility
+            const uiResult = (0, adapters_1.buildToolResponseContent)({
+                rawOutput,
+                htmlContent,
+                servingMode,
+                useStructuredContent,
+                platformType,
+            });
+            // Store UI result and metadata in state for finalize stage
+            this.state.set('uiResult', uiResult);
+            this.state.set('uiMeta', uiMeta);
+            this.logger.verbose('applyUI: UI processed', {
+                tool: tool.metadata.name,
+                platform: platformType,
+                servingMode,
+                useStructuredContent,
+                format: uiResult.format,
+                contentCleared: uiResult.contentCleared,
+            });
+        }
+        catch (error) {
+            // UI rendering failure should not fail the tool call
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            const uiConfig = tool.metadata.ui;
+            this.logger.error('applyUI: UI rendering failed', {
+                tool: tool.metadata.name,
+                error: errorMessage,
+                stack: errorStack,
+                templateType: uiConfig?.template
+                    ? typeof uiConfig.template === 'function'
+                        ? 'react-component'
+                        : typeof uiConfig.template === 'string'
+                            ? uiConfig.template.endsWith('.tsx') || uiConfig.template.endsWith('.jsx')
+                                ? 'react-file'
+                                : 'html-file'
+                            : 'unknown'
+                    : 'none',
+            });
+            // In debug mode, also log to console for immediate visibility
+            if (process.env['DEBUG'] || process.env['NODE_ENV'] === 'development') {
+                console.error('[FrontMCP] UI Rendering Error:', {
+                    tool: tool.metadata.name,
+                    error: errorMessage,
+                    stack: errorStack,
+                });
+            }
+        }
+        this.logger.verbose('applyUI:done');
+    }
+    /**
+     * Finalize the tool response.
+     * Validates output, applies UI result from applyUI stage, and sends the response.
+     *
+     * Note: This stage runs even when execute fails (as part of cleanup).
+     * If rawOutput is undefined, it means an error occurred during execution
+     * and the error will be propagated by the flow framework - we should not
+     * throw a new error here.
+     */
     async finalize() {
         this.logger.verbose('finalize:start');
-        const { tool, rawOutput, input } = this.state;
+        const { tool, rawOutput, uiResult, uiMeta } = this.state;
         if (!tool) {
-            this.logger.error('finalize: tool not found in state');
-            throw new errors_1.ToolExecutionError('unknown', new Error('Tool not found in state'));
+            // No tool found - this is an early failure, just skip finalization
+            this.logger.verbose('finalize: skipping (no tool in state)');
+            return;
         }
         if (rawOutput === undefined) {
-            this.logger.error('finalize: tool output not found in state');
-            throw new errors_1.ToolExecutionError(tool.metadata.name, new Error('Tool output not found'));
+            // No output means execute stage failed - skip finalization
+            // The original error will be propagated by the flow framework
+            this.logger.verbose('finalize: skipping (no output - execute stage likely failed)');
+            return;
         }
         // Parse and construct the MCP-compliant output using safeParseOutput
         const parseResult = tool.safeParseOutput(rawOutput);
         if (!parseResult.success) {
-            // add support for request id in error messages
             this.logger.error('finalize: output validation failed', {
                 tool: tool.metadata.name,
                 errors: parseResult.error,
             });
-            // Use InvalidOutputError, which hides internal details in production
             throw new errors_1.InvalidOutputError();
         }
         const result = parseResult.data;
-        // If tool has UI config, render and add to _meta
-        if ((0, ui_1.hasUIConfig)(tool.metadata)) {
-            try {
-                // Cast scope to Scope to access toolUI and notifications
-                const scope = this.scope;
-                // Get session info for platform detection from authInfo (already in state from parseInput)
-                const { authInfo } = this.state;
-                const sessionId = authInfo?.sessionId;
-                const requestId = (0, crypto_1.randomUUID)();
-                // Get platform type: first check sessionIdPayload (detected from user-agent),
-                // then fall back to notification service (detected from MCP clientInfo),
-                // finally default to 'openai'
-                const platformType = authInfo?.sessionIdPayload?.platformType ??
-                    (sessionId ? scope.notifications.getPlatformType(sessionId) : undefined) ??
-                    'openai';
-                // Get the serving mode (default to 'inline' for backward compatibility)
-                const servingMode = tool.metadata.ui.servingMode ?? 'inline';
-                if (servingMode === 'static') {
-                    // For static mode: return ONLY structured data
-                    // The static widget was already registered at server startup and advertised in tools/list
-                    // Widget reads tool output from platform context (e.g., window.openai.toolOutput)
-                    // NO UI _meta fields needed - the client uses the outputTemplate URI from tools/list
-                    // Return structured data as JSON text content
-                    result.content = [
-                        {
-                            type: 'text',
-                            text: safeStringify(rawOutput),
-                        },
-                    ];
-                    // Do NOT add any UI _meta fields - widget reads from platform context
-                    // The outputTemplate URI (ui://widget/{toolName}.html) was already provided in tools/list
-                    this.logger.verbose('finalize: UI using static mode (structured data only)', {
-                        tool: tool.metadata.name,
-                        platform: platformType,
-                        outputKeys: rawOutput && typeof rawOutput === 'object' && !Array.isArray(rawOutput) ? Object.keys(rawOutput) : [],
-                    });
-                }
-                else if (servingMode === 'hybrid') {
-                    // For hybrid mode: return structured data + transpiled component code
-                    // The hybrid shell (React runtime + renderer) was pre-compiled at server startup
-                    // and advertised via outputTemplate URI in tools/list.
-                    // The shell dynamically imports the component code from _meta['ui/component']
-                    // and renders it with toolOutput data from the platform context.
-                    // Build the component payload with transpiled code
-                    const componentPayload = scope.toolUI.buildHybridComponentPayload({
-                        toolName: tool.metadata.name,
-                        template: tool.metadata.ui.template,
-                        uiConfig: tool.metadata.ui,
-                    });
-                    // Return structured data as JSON text content
-                    result.content = [
-                        {
-                            type: 'text',
-                            text: safeStringify(rawOutput),
-                        },
-                    ];
-                    // Add component payload to _meta for the hybrid shell's dynamic renderer
-                    if (componentPayload) {
-                        result._meta = {
-                            ...result._meta,
-                            'ui/component': componentPayload,
-                            'ui/type': componentPayload.type,
-                        };
-                    }
-                    this.logger.verbose('finalize: UI using hybrid mode (structured data + component)', {
-                        tool: tool.metadata.name,
-                        platform: platformType,
-                        hasComponent: !!componentPayload,
-                        componentType: componentPayload?.type,
-                        componentHash: componentPayload?.hash,
-                        outputKeys: rawOutput && typeof rawOutput === 'object' && !Array.isArray(rawOutput) ? Object.keys(rawOutput) : [],
-                    });
-                }
-                else {
-                    // For inline mode (default): render HTML with data embedded in each response
-                    // Use async version to support React component templates via SSR
-                    const uiResult = await scope.toolUI.renderAndRegisterAsync({
-                        toolName: tool.metadata.name,
-                        requestId,
-                        input: input?.arguments && typeof input.arguments === 'object' && !Array.isArray(input.arguments)
-                            ? input.arguments
-                            : {},
-                        output: rawOutput,
-                        structuredContent: result.structuredContent,
-                        uiConfig: tool.metadata.ui,
-                        platformType,
-                    });
-                    // Merge UI metadata into result._meta
-                    result._meta = {
-                        ...result._meta,
-                        ...uiResult.meta,
-                    };
-                    // For platforms that support widgets (OpenAI, ext-apps), clear content since widget displays data
-                    // For Claude and other platforms, keep the text content as they don't support _meta UI fields
-                    const supportsWidgets = platformType === 'openai' || platformType === 'ext-apps';
-                    if (supportsWidgets) {
-                        // Clear content - widget will display from _meta['ui/html']
-                        result.content = [];
-                    }
-                    else {
-                        // For Claude and other platforms without widget support:
-                        // Return JSON data + HTML template as artifact hint
-                        const htmlContent = uiResult?.meta?.['ui/html'];
-                        if (htmlContent) {
-                            // Include HTML template as artifact hint for Claude
-                            // Claude can use this to create an HTML artifact for visual display
-                            result.content = [
-                                {
-                                    type: 'text',
-                                    text: `## Data\n\`\`\`json\n${safeStringify(rawOutput, 2)}\n\`\`\`\n\n## Visual Template (for artifact rendering)\n\`\`\`html\n${htmlContent}\n\`\`\``,
-                                },
-                            ];
-                        }
-                        else {
-                            // Fallback: JSON only
-                            result.content = [
-                                {
-                                    type: 'text',
-                                    text: safeStringify(rawOutput, 2),
-                                },
-                            ];
-                        }
-                    }
-                    this.logger.verbose('finalize: UI metadata added (inline mode)', {
-                        tool: tool.metadata.name,
-                        platform: platformType,
-                        supportsWidgets,
-                        contentCleared: supportsWidgets,
-                        htmlHintIncluded: !supportsWidgets && !!uiResult?.meta?.['ui/html'],
-                    });
-                }
+        // Apply UI result if available (from applyUI stage)
+        if (uiResult) {
+            result.content = uiResult.content;
+            // Set structuredContent from UI result (contains raw tool output)
+            // Cast to Record<string, unknown> since MCP protocol expects object type
+            if (uiResult.structuredContent !== undefined && uiResult.structuredContent !== null) {
+                result.structuredContent = uiResult.structuredContent;
             }
-            catch (error) {
-                // UI rendering failure should not fail the tool call
-                // Log with full context to help debugging
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                const errorStack = error instanceof Error ? error.stack : undefined;
-                const uiConfig = tool.metadata.ui;
-                this.logger.error('finalize: UI rendering failed', {
-                    tool: tool.metadata.name,
-                    error: errorMessage,
-                    stack: errorStack,
-                    templateType: uiConfig?.template
-                        ? typeof uiConfig.template === 'function'
-                            ? 'react-component'
-                            : typeof uiConfig.template === 'string'
-                                ? uiConfig.template.endsWith('.tsx') || uiConfig.template.endsWith('.jsx')
-                                    ? 'react-file'
-                                    : 'html-file'
-                                : 'unknown'
-                        : 'none',
-                    hasStructuredContent: result.structuredContent !== undefined,
-                    structuredContentKeys: result.structuredContent &&
-                        typeof result.structuredContent === 'object' &&
-                        result.structuredContent !== null &&
-                        !Array.isArray(result.structuredContent)
-                        ? Object.keys(result.structuredContent)
-                        : [],
-                });
-                // In debug mode, also log to console for immediate visibility
-                if (process.env['DEBUG'] || process.env['NODE_ENV'] === 'development') {
-                    console.error('[FrontMCP] UI Rendering Error:', {
-                        tool: tool.metadata.name,
-                        error: errorMessage,
-                        stack: errorStack,
-                    });
-                }
+            if (uiMeta) {
+                result._meta = { ...result._meta, ...uiMeta };
             }
         }
         // Log the final result being sent
@@ -480,6 +481,45 @@ let CallToolFlow = class CallToolFlow extends common_1.FlowBase {
             metaKeys: result._meta ? Object.keys(result._meta) : [],
             isError: result.isError,
         });
+        // Debug: Write full response to file if DEBUG_TOOL_RESPONSE is set
+        if (process.env['DEBUG_TOOL_RESPONSE']) {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const fs = require('fs').promises;
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const os = require('os');
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const path = require('path');
+            const debugOutput = {
+                timestamp: new Date().toISOString(),
+                tool: tool.metadata.name,
+                rawOutput,
+                uiResult,
+                uiMeta,
+                finalResult: result,
+            };
+            // Use os.tmpdir() for cross-platform compatibility (works on Windows, macOS, Linux)
+            const tempDir = os.tmpdir();
+            const defaultPath = path.join(tempDir, 'tool-response-debug.json');
+            let outputPath = process.env['DEBUG_TOOL_RESPONSE_PATH'] || defaultPath;
+            // Path traversal protection: ensure custom path is within allowed directories
+            if (process.env['DEBUG_TOOL_RESPONSE_PATH']) {
+                const resolvedPath = path.resolve(outputPath);
+                const resolvedTempDir = path.resolve(tempDir);
+                const cwd = path.resolve(process.cwd());
+                // Only allow paths within temp directory or current working directory
+                const isInTempDir = resolvedPath.startsWith(resolvedTempDir + path.sep) || resolvedPath === resolvedTempDir;
+                const isInCwd = resolvedPath.startsWith(cwd + path.sep) || resolvedPath === cwd;
+                if (!isInTempDir && !isInCwd) {
+                    console.error(`[DEBUG] DEBUG_TOOL_RESPONSE_PATH must be within temp directory (${tempDir}) or current working directory (${cwd}). ` +
+                        `Falling back to default path.`);
+                    outputPath = defaultPath;
+                }
+            }
+            // Use async write to avoid blocking the event loop (fire-and-forget)
+            fs.writeFile(outputPath, JSON.stringify(debugOutput, null, 2))
+                .then(() => console.log(`[DEBUG] Tool response written to: ${outputPath}`))
+                .catch((err) => console.error(`[DEBUG] Failed to write tool response: ${err.message}`));
+        }
         // Respond with the properly formatted MCP result
         this.respond(result);
         this.logger.verbose('finalize:done');
@@ -551,6 +591,12 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:paramtypes", []),
     tslib_1.__metadata("design:returntype", Promise)
 ], CallToolFlow.prototype, "releaseQuota", null);
+tslib_1.__decorate([
+    Stage('applyUI'),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", []),
+    tslib_1.__metadata("design:returntype", Promise)
+], CallToolFlow.prototype, "applyUI", null);
 tslib_1.__decorate([
     Stage('finalize'),
     tslib_1.__metadata("design:type", Function),