@frontmcp/sdk 0.4.0 → 0.5.0

package/src/tool/ui/platform-adapters.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Platform Adapters
+ *
+ * Re-exports platform adapter functions from @frontmcp/ui/adapters for SDK consumers.
+ * This provides a single source of truth for platform-specific metadata building
+ * while maintaining backwards compatibility.
+ *
+ * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOpenAICSP = exports.buildToolDiscoveryMeta = exports.buildUIMeta = void 0;
+// Re-export platform adapter types and functions from @frontmcp/ui
+var adapters_1 = require("@frontmcp/ui/adapters");
+Object.defineProperty(exports, "buildUIMeta", { enumerable: true, get: function () { return adapters_1.buildUIMeta; } });
+Object.defineProperty(exports, "buildToolDiscoveryMeta", { enumerable: true, get: function () { return adapters_1.buildToolDiscoveryMeta; } });
+Object.defineProperty(exports, "buildOpenAICSP", { enumerable: true, get: function () { return adapters_1.buildOpenAICSP; } });
+//# sourceMappingURL=platform-adapters.js.map

package/src/tool/ui/platform-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-adapters.js","sourceRoot":"","sources":["../../../../src/tool/ui/platform-adapters.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,mEAAmE;AACnE,kDAQ+B;AAH7B,uGAAA,WAAW,OAAA;AACX,kHAAA,sBAAsB,OAAA;AACtB,0GAAA,cAAc,OAAA","sourcesContent":["/**\n * Platform Adapters\n *\n * Re-exports platform adapter functions from @frontmcp/ui/adapters for SDK consumers.\n * This provides a single source of truth for platform-specific metadata building\n * while maintaining backwards compatibility.\n *\n * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}\n */\n\n// Re-export platform adapter types and functions from @frontmcp/ui\nexport {\n  type AIPlatformType,\n  type UIMetadata,\n  type BuildUIMetaOptions,\n  type BuildToolDiscoveryMetaOptions,\n  buildUIMeta,\n  buildToolDiscoveryMeta,\n  buildOpenAICSP,\n} from '@frontmcp/ui/adapters';\n"]}

package/src/tool/ui/template-helpers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Template Helpers
+ *
+ * Re-exports template helper utilities from @frontmcp/ui/runtime.
+ * Also provides individual helper functions for backwards compatibility.
+ *
+ * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}
+ */
+import type { TemplateHelpers } from '../../common/metadata/tool-ui.metadata';
+export { createTemplateHelpers } from '@frontmcp/ui/runtime';
+/**
+ * Escape HTML special characters to prevent XSS.
+ */
+export declare function escapeHtml(str: string): string;
+/**
+ * Format a date for display.
+ * @param date - Date object or ISO string
+ * @param format - Optional format: 'iso', 'time', 'datetime', or default (localized date)
+ */
+export declare function formatDate(date: Date | string, format?: string): string;
+/**
+ * Format a number as currency.
+ * @param amount - The numeric amount
+ * @param currency - ISO 4217 currency code (default: 'USD')
+ */
+export declare function formatCurrency(amount: number, currency?: string): string;
+/**
+ * Generate a unique ID for DOM elements.
+ * @param prefix - Optional prefix for the ID
+ */
+export declare function uniqueId(prefix?: string): string;
+/**
+ * Safely embed JSON data in HTML.
+ * Escapes characters that could break out of script tags or HTML.
+ */
+export declare function jsonEmbed(data: unknown): string;
+/**
+ * Create a TemplateHelpers object with all helper functions.
+ * @deprecated Use createTemplateHelpers from @frontmcp/ui/runtime instead
+ */
+export declare function createTemplateHelpersLocal(): TemplateHelpers;
+/**
+ * Reset the ID counter (useful for testing).
+ * @internal
+ */
+export declare function resetIdCounter(): void;

package/src/tool/ui/template-helpers.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Template Helpers
+ *
+ * Re-exports template helper utilities from @frontmcp/ui/runtime.
+ * Also provides individual helper functions for backwards compatibility.
+ *
+ * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTemplateHelpers = void 0;
+exports.escapeHtml = escapeHtml;
+exports.formatDate = formatDate;
+exports.formatCurrency = formatCurrency;
+exports.uniqueId = uniqueId;
+exports.jsonEmbed = jsonEmbed;
+exports.createTemplateHelpersLocal = createTemplateHelpersLocal;
+exports.resetIdCounter = resetIdCounter;
+// Re-export createTemplateHelpers from @frontmcp/ui
+var runtime_1 = require("@frontmcp/ui/runtime");
+Object.defineProperty(exports, "createTemplateHelpers", { enumerable: true, get: function () { return runtime_1.createTemplateHelpers; } });
+// ============================================
+// Individual Helper Functions (Backwards Compatibility)
+// ============================================
+// These are exported individually for SDK consumers who import them directly.
+// For new code, prefer using createTemplateHelpers() instead.
+let idCounter = 0;
+/**
+ * Escape HTML special characters to prevent XSS.
+ */
+function escapeHtml(str) {
+    if (typeof str !== 'string') {
+        return String(str ?? '');
+    }
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}
+/**
+ * Format a date for display.
+ * @param date - Date object or ISO string
+ * @param format - Optional format: 'iso', 'time', 'datetime', or default (localized date)
+ */
+function formatDate(date, format) {
+    const d = typeof date === 'string' ? new Date(date) : date;
+    if (isNaN(d.getTime())) {
+        return String(date);
+    }
+    switch (format) {
+        case 'iso':
+            return d.toISOString();
+        case 'time':
+            return d.toLocaleTimeString();
+        case 'datetime':
+            return d.toLocaleString();
+        default:
+            return d.toLocaleDateString();
+    }
+}
+/**
+ * Format a number as currency.
+ * @param amount - The numeric amount
+ * @param currency - ISO 4217 currency code (default: 'USD')
+ */
+function formatCurrency(amount, currency = 'USD') {
+    return new Intl.NumberFormat('en-US', {
+        style: 'currency',
+        currency,
+    }).format(amount);
+}
+/**
+ * Generate a unique ID for DOM elements.
+ * @param prefix - Optional prefix for the ID
+ */
+function uniqueId(prefix = 'mcp') {
+    return `${prefix}-${++idCounter}-${Date.now().toString(36)}`;
+}
+/**
+ * Safely embed JSON data in HTML.
+ * Escapes characters that could break out of script tags or HTML.
+ */
+function jsonEmbed(data) {
+    return JSON.stringify(data)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/'/g, '\\u0027');
+}
+/**
+ * Create a TemplateHelpers object with all helper functions.
+ * @deprecated Use createTemplateHelpers from @frontmcp/ui/runtime instead
+ */
+function createTemplateHelpersLocal() {
+    return {
+        escapeHtml,
+        formatDate,
+        formatCurrency,
+        uniqueId,
+        jsonEmbed,
+    };
+}
+/**
+ * Reset the ID counter (useful for testing).
+ * @internal
+ */
+function resetIdCounter() {
+    idCounter = 0;
+}
+//# sourceMappingURL=template-helpers.js.map

package/src/tool/ui/template-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-helpers.js","sourceRoot":"","sources":["../../../../src/tool/ui/template-helpers.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAkBH,gCAUC;AAOD,gCAgBC;AAOD,wCAKC;AAMD,4BAEC;AAMD,8BAMC;AAMD,gEAQC;AAMD,wCAEC;AArGD,oDAAoD;AACpD,gDAA6D;AAApD,gHAAA,qBAAqB,OAAA;AAE9B,+CAA+C;AAC/C,wDAAwD;AACxD,+CAA+C;AAC/C,8EAA8E;AAC9E,8DAA8D;AAE9D,IAAI,SAAS,GAAG,CAAC,CAAC;AAElB;;GAEG;AACH,SAAgB,UAAU,CAAC,GAAW;IACpC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG;SACP,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAgB,UAAU,CAAC,IAAmB,EAAE,MAAe;IAC7D,MAAM,CAAC,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3D,IAAI,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,KAAK;YACR,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QACzB,KAAK,MAAM;YACT,OAAO,CAAC,CAAC,kBAAkB,EAAE,CAAC;QAChC,KAAK,UAAU;YACb,OAAO,CAAC,CAAC,cAAc,EAAE,CAAC;QAC5B;YACE,OAAO,CAAC,CAAC,kBAAkB,EAAE,CAAC;IAClC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,MAAc,EAAE,QAAQ,GAAG,KAAK;IAC7D,OAAO,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE;QACpC,KAAK,EAAE,UAAU;QACjB,QAAQ;KACT,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,SAAgB,QAAQ,CAAC,MAAM,GAAG,KAAK;IACrC,OAAO,GAAG,MAAM,IAAI,EAAE,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,SAAgB,SAAS,CAAC,IAAa;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SACxB,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC;SACxB,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC;SACxB,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC;SACxB,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,SAAgB,0BAA0B;IACxC,OAAO;QACL,UAAU;QACV,UAAU;QACV,cAAc;QACd,QAAQ;QACR,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,cAAc;IAC5B,SAAS,GAAG,CAAC,CAAC;AAChB,CAAC","sourcesContent":["/**\n * Template Helpers\n *\n * Re-exports template helper utilities from @frontmcp/ui/runtime.\n * Also provides individual helper functions for backwards compatibility.\n *\n * @see {@link https://docs.agentfront.dev/docs/servers/tools#tool-ui | Tool UI Documentation}\n */\n\nimport type { TemplateHelpers } from '../../common/metadata/tool-ui.metadata';\n\n// Re-export createTemplateHelpers from @frontmcp/ui\nexport { createTemplateHelpers } from '@frontmcp/ui/runtime';\n\n// ============================================\n// Individual Helper Functions (Backwards Compatibility)\n// ============================================\n// These are exported individually for SDK consumers who import them directly.\n// For new code, prefer using createTemplateHelpers() instead.\n\nlet idCounter = 0;\n\n/**\n * Escape HTML special characters to prevent XSS.\n */\nexport function escapeHtml(str: string): string {\n  if (typeof str !== 'string') {\n    return String(str ?? '');\n  }\n  return str\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;')\n    .replace(/'/g, '&#039;');\n}\n\n/**\n * Format a date for display.\n * @param date - Date object or ISO string\n * @param format - Optional format: 'iso', 'time', 'datetime', or default (localized date)\n */\nexport function formatDate(date: Date | string, format?: string): string {\n  const d = typeof date === 'string' ? new Date(date) : date;\n  if (isNaN(d.getTime())) {\n    return String(date);\n  }\n\n  switch (format) {\n    case 'iso':\n      return d.toISOString();\n    case 'time':\n      return d.toLocaleTimeString();\n    case 'datetime':\n      return d.toLocaleString();\n    default:\n      return d.toLocaleDateString();\n  }\n}\n\n/**\n * Format a number as currency.\n * @param amount - The numeric amount\n * @param currency - ISO 4217 currency code (default: 'USD')\n */\nexport function formatCurrency(amount: number, currency = 'USD'): string {\n  return new Intl.NumberFormat('en-US', {\n    style: 'currency',\n    currency,\n  }).format(amount);\n}\n\n/**\n * Generate a unique ID for DOM elements.\n * @param prefix - Optional prefix for the ID\n */\nexport function uniqueId(prefix = 'mcp'): string {\n  return `${prefix}-${++idCounter}-${Date.now().toString(36)}`;\n}\n\n/**\n * Safely embed JSON data in HTML.\n * Escapes characters that could break out of script tags or HTML.\n */\nexport function jsonEmbed(data: unknown): string {\n  return JSON.stringify(data)\n    .replace(/</g, '\\\\u003c')\n    .replace(/>/g, '\\\\u003e')\n    .replace(/&/g, '\\\\u0026')\n    .replace(/'/g, '\\\\u0027');\n}\n\n/**\n * Create a TemplateHelpers object with all helper functions.\n * @deprecated Use createTemplateHelpers from @frontmcp/ui/runtime instead\n */\nexport function createTemplateHelpersLocal(): TemplateHelpers {\n  return {\n    escapeHtml,\n    formatDate,\n    formatCurrency,\n    uniqueId,\n    jsonEmbed,\n  };\n}\n\n/**\n * Reset the ID counter (useful for testing).\n * @internal\n */\nexport function resetIdCounter(): void {\n  idCounter = 0;\n}\n"]}

package/src/tool/ui/ui-resource-template.d.ts

@@ -0,0 +1,34 @@
+/**
+ * UI Resource Template for ui:// URIs
+ *
+ * Single URI pattern for widget resources:
+ *
+ * Static Widget URI: ui://widget/{toolName}.html
+ *   - Used by OpenAI at discovery/listing time
+ *   - Returns the pre-compiled static HTML for the tool
+ *   - Widget reads tool output from platform context (e.g., window.openai.toolOutput)
+ *
+ * The actual read logic is handled by ReadResourceFlow's ui:// interception
+ * in read-resource.flow.ts.
+ *
+ * IMPORTANT: Resources MUST be visible in resources/list for OpenAI ChatGPT
+ * to discover and render widgets.
+ */
+/**
+ * Static Widget Resource Template for OpenAI discovery.
+ *
+ * URI format: ui://widget/{toolName}.html
+ *
+ * This is the format OpenAI expects in tools/list _meta.openai/outputTemplate.
+ * When OpenAI fetches this resource, we return the pre-compiled static HTML for the tool.
+ *
+ * The widget includes:
+ * - FrontMCP Bridge for reading tool output from platform context
+ * - CDN scripts for React/MDX/etc (based on uiType)
+ * - Pre-transpiled component embedded in HTML
+ *
+ * At runtime, the widget reads tool output from:
+ * - OpenAI: window.openai.toolOutput
+ * - Generic: window.__mcpToolOutput
+ */
+export declare const StaticWidgetResourceTemplate: () => import("../../common/decorators/resource.decorator").FrontMcpResourceTemplateExecuteHandler;

package/src/tool/ui/ui-resource-template.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * UI Resource Template for ui:// URIs
+ *
+ * Single URI pattern for widget resources:
+ *
+ * Static Widget URI: ui://widget/{toolName}.html
+ *   - Used by OpenAI at discovery/listing time
+ *   - Returns the pre-compiled static HTML for the tool
+ *   - Widget reads tool output from platform context (e.g., window.openai.toolOutput)
+ *
+ * The actual read logic is handled by ReadResourceFlow's ui:// interception
+ * in read-resource.flow.ts.
+ *
+ * IMPORTANT: Resources MUST be visible in resources/list for OpenAI ChatGPT
+ * to discover and render widgets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StaticWidgetResourceTemplate = void 0;
+const resource_decorator_1 = require("../../common/decorators/resource.decorator");
+const template_helpers_1 = require("./template-helpers");
+/**
+ * Static Widget Resource Template for OpenAI discovery.
+ *
+ * URI format: ui://widget/{toolName}.html
+ *
+ * This is the format OpenAI expects in tools/list _meta.openai/outputTemplate.
+ * When OpenAI fetches this resource, we return the pre-compiled static HTML for the tool.
+ *
+ * The widget includes:
+ * - FrontMCP Bridge for reading tool output from platform context
+ * - CDN scripts for React/MDX/etc (based on uiType)
+ * - Pre-transpiled component embedded in HTML
+ *
+ * At runtime, the widget reads tool output from:
+ * - OpenAI: window.openai.toolOutput
+ * - Generic: window.__mcpToolOutput
+ */
+exports.StaticWidgetResourceTemplate = (0, resource_decorator_1.resourceTemplate)({
+    name: 'static-widget',
+    description: 'Static widget HTML for tool UI (OpenAI discovery)',
+    uriTemplate: 'ui://widget/{toolName}.html',
+    mimeType: 'text/html+skybridge',
+})((uri, params) => {
+    // This handler should NOT be called because ReadResourceFlow
+    // intercepts ui:// URIs before reaching the resource instance.
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: 'text/html+skybridge',
+                text: `<!DOCTYPE html>
+<html>
+<head><title>Widget Placeholder</title></head>
+<body>
+  <p>Widget for tool: ${(0, template_helpers_1.escapeHtml)(String(params['toolName'] || 'unknown'))}</p>
+  <p>This is a placeholder. The actual widget HTML is served from the ToolUIRegistry cache.</p>
+</body>
+</html>`,
+            },
+        ],
+    };
+});
+//# sourceMappingURL=ui-resource-template.js.map

package/src/tool/ui/ui-resource-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-resource-template.js","sourceRoot":"","sources":["../../../../src/tool/ui/ui-resource-template.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,mFAA8E;AAC9E,yDAAgD;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,4BAA4B,GAAG,IAAA,qCAAgB,EAAC;IAC3D,IAAI,EAAE,eAAe;IACrB,WAAW,EAAE,mDAAmD;IAChE,WAAW,EAAE,6BAA6B;IAC1C,QAAQ,EAAE,qBAAqB;CAChC,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;IACjB,6DAA6D;IAC7D,+DAA+D;IAC/D,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,GAAG;gBACH,QAAQ,EAAE,qBAAqB;gBAC/B,IAAI,EAAE;;;;wBAIU,IAAA,6BAAU,EAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,SAAS,CAAC,CAAC;;;QAGnE;aACD;SACF;KACF,CAAC;AACJ,CAAC,CAAC,CAAC","sourcesContent":["/**\n * UI Resource Template for ui:// URIs\n *\n * Single URI pattern for widget resources:\n *\n * Static Widget URI: ui://widget/{toolName}.html\n *   - Used by OpenAI at discovery/listing time\n *   - Returns the pre-compiled static HTML for the tool\n *   - Widget reads tool output from platform context (e.g., window.openai.toolOutput)\n *\n * The actual read logic is handled by ReadResourceFlow's ui:// interception\n * in read-resource.flow.ts.\n *\n * IMPORTANT: Resources MUST be visible in resources/list for OpenAI ChatGPT\n * to discover and render widgets.\n */\n\nimport { resourceTemplate } from '../../common/decorators/resource.decorator';\nimport { escapeHtml } from './template-helpers';\n\n/**\n * Static Widget Resource Template for OpenAI discovery.\n *\n * URI format: ui://widget/{toolName}.html\n *\n * This is the format OpenAI expects in tools/list _meta.openai/outputTemplate.\n * When OpenAI fetches this resource, we return the pre-compiled static HTML for the tool.\n *\n * The widget includes:\n * - FrontMCP Bridge for reading tool output from platform context\n * - CDN scripts for React/MDX/etc (based on uiType)\n * - Pre-transpiled component embedded in HTML\n *\n * At runtime, the widget reads tool output from:\n * - OpenAI: window.openai.toolOutput\n * - Generic: window.__mcpToolOutput\n */\nexport const StaticWidgetResourceTemplate = resourceTemplate({\n  name: 'static-widget',\n  description: 'Static widget HTML for tool UI (OpenAI discovery)',\n  uriTemplate: 'ui://widget/{toolName}.html',\n  mimeType: 'text/html+skybridge',\n})((uri, params) => {\n  // This handler should NOT be called because ReadResourceFlow\n  // intercepts ui:// URIs before reaching the resource instance.\n  return {\n    contents: [\n      {\n        uri,\n        mimeType: 'text/html+skybridge',\n        text: `<!DOCTYPE html>\n<html>\n<head><title>Widget Placeholder</title></head>\n<body>\n  <p>Widget for tool: ${escapeHtml(String(params['toolName'] || 'unknown'))}</p>\n  <p>This is a placeholder. The actual widget HTML is served from the ToolUIRegistry cache.</p>\n</body>\n</html>`,\n      },\n    ],\n  };\n});\n"]}

package/src/tool/ui/ui-resource.handler.d.ts

@@ -0,0 +1,74 @@
+/**
+ * UI Resource Handler
+ *
+ * Handles resources/read requests for ui:// URIs, serving widget HTML
+ * from the ToolUIRegistry.
+ *
+ * Supported URI format:
+ * - ui://widget/{toolName}.html - Static widget HTML (pre-compiled at startup)
+ *
+ * The static widget is registered at server startup for tools with
+ * `servingMode: 'static'`. The widget HTML includes the FrontMCP Bridge
+ * which reads tool output from the platform context at runtime.
+ *
+ * @example
+ * ```typescript
+ * // Client requests widget HTML (OpenAI discovery)
+ * const result = await client.readResource({
+ *   uri: 'ui://widget/get_weather.html'
+ * });
+ *
+ * // Returns pre-compiled widget with FrontMCP Bridge
+ * // Widget reads tool output from window.openai.toolOutput at runtime
+ * ```
+ */
+import type { ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import type { AIPlatformType } from '../../notification/notification.service';
+import { type ToolUIRegistry } from '@frontmcp/ui/registry';
+/**
+ * Result of handling a UI resource request
+ */
+export interface UIResourceHandleResult {
+    /** Whether the URI was handled */
+    handled: boolean;
+    /** The resource result if handled successfully */
+    result?: ReadResourceResult;
+    /** Error message if handling failed */
+    error?: string;
+}
+/**
+ * Options for handling a UI resource read request
+ */
+export interface HandleUIResourceOptions {
+    /** The UI resource URI */
+    uri: string;
+    /** The ToolUIRegistry containing cached HTML */
+    registry: ToolUIRegistry;
+    /** Platform type of the connected client */
+    platformType?: AIPlatformType;
+}
+/**
+ * Handle a UI resource read request
+ *
+ * @param uri - The UI resource URI
+ * @param registry - The ToolUIRegistry containing cached HTML
+ * @param platformType - Optional platform type for dynamic MIME type selection
+ * @returns Handle result with content or error
+ */
+export declare function handleUIResourceRead(uri: string, registry: ToolUIRegistry, platformType?: AIPlatformType): UIResourceHandleResult;
+/**
+ * Options for creating a UI resource handler
+ */
+export interface UIResourceHandlerOptions {
+    /** ToolUIRegistry instance */
+    registry: ToolUIRegistry;
+    /** Optional custom error handler */
+    onError?: (error: string, uri: string) => void;
+}
+/**
+ * Create a UI resource handler function
+ *
+ * @param options - Handler options
+ * @returns Handler function that can be used in the read-resource flow
+ */
+export declare function createUIResourceHandler(options: UIResourceHandlerOptions): (uri: string) => UIResourceHandleResult;

package/src/tool/ui/ui-resource.handler.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * UI Resource Handler
+ *
+ * Handles resources/read requests for ui:// URIs, serving widget HTML
+ * from the ToolUIRegistry.
+ *
+ * Supported URI format:
+ * - ui://widget/{toolName}.html - Static widget HTML (pre-compiled at startup)
+ *
+ * The static widget is registered at server startup for tools with
+ * `servingMode: 'static'`. The widget HTML includes the FrontMCP Bridge
+ * which reads tool output from the platform context at runtime.
+ *
+ * @example
+ * ```typescript
+ * // Client requests widget HTML (OpenAI discovery)
+ * const result = await client.readResource({
+ *   uri: 'ui://widget/get_weather.html'
+ * });
+ *
+ * // Returns pre-compiled widget with FrontMCP Bridge
+ * // Widget reads tool output from window.openai.toolOutput at runtime
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleUIResourceRead = handleUIResourceRead;
+exports.createUIResourceHandler = createUIResourceHandler;
+const ui_1 = require("@frontmcp/ui");
+const registry_1 = require("@frontmcp/ui/registry");
+/**
+ * Generate a placeholder widget HTML that reads from window.openai.toolOutput.
+ *
+ * Delegates to @frontmcp/ui's createDefaultBaseTemplate which provides:
+ * - Tailwind CSS with @theme configuration
+ * - Platform polyfills (callTool, detectMcpSession, getToolOutput)
+ * - Polling for toolOutput injection
+ * - Default JSON renderer (data-type-specific renderers are in @frontmcp/ui)
+ *
+ * This is returned when the static widget URI is fetched before the tool is called.
+ * OpenAI caches this HTML, so it must be dynamic (read toolOutput at runtime).
+ *
+ * @param toolName - The name of the tool
+ * @returns HTML string with a dynamic widget that renders toolOutput
+ */
+function generatePlaceholderWidget(toolName) {
+    return (0, ui_1.createDefaultBaseTemplate)({ toolName });
+}
+/**
+ * Handle a UI resource read request
+ *
+ * @param uri - The UI resource URI
+ * @param registry - The ToolUIRegistry containing cached HTML
+ * @param platformType - Optional platform type for dynamic MIME type selection
+ * @returns Handle result with content or error
+ */
+function handleUIResourceRead(uri, registry, platformType) {
+    // Check if this is a UI resource URI
+    if (!(0, registry_1.isUIResourceUri)(uri)) {
+        return { handled: false };
+    }
+    // Get the platform-appropriate MIME type
+    const mimeType = (0, registry_1.getUIResourceMimeType)(platformType);
+    // Try static widget URI (ui://widget/{toolName}.html)
+    // This is used by OpenAI at discovery time
+    const widgetParsed = (0, registry_1.parseWidgetUri)(uri);
+    if (widgetParsed) {
+        // Check for pre-compiled static widget from the developer's template
+        // Static widgets are compiled at server startup for tools with servingMode: 'static'
+        const cachedWidget = registry.getStaticWidget(widgetParsed.toolName);
+        if (cachedWidget) {
+            // Return the developer's actual template (SSR'd React/MDX component)
+            // This template includes the FrontMCP Bridge for runtime data access
+            return {
+                handled: true,
+                result: {
+                    contents: [
+                        {
+                            uri,
+                            mimeType,
+                            text: cachedWidget,
+                        },
+                    ],
+                },
+            };
+        }
+        // Fallback to dynamic placeholder widget if no pre-compiled template.
+        // This is returned when the tool doesn't have a UI template configured
+        // or uses a different serving mode.
+        //
+        // OpenAI caches widget HTML from outputTemplate URI, so we must return
+        // a template that reads from window.openai.toolOutput at runtime.
+        const html = generatePlaceholderWidget(widgetParsed.toolName);
+        return {
+            handled: true,
+            result: {
+                contents: [
+                    {
+                        uri,
+                        mimeType,
+                        text: html,
+                    },
+                ],
+            },
+        };
+    }
+    // Unknown UI resource URI format
+    return {
+        handled: true,
+        error: `Invalid UI resource URI format: ${uri}. Expected: ui://widget/{toolName}.html`,
+    };
+}
+/**
+ * Create a UI resource handler function
+ *
+ * @param options - Handler options
+ * @returns Handler function that can be used in the read-resource flow
+ */
+function createUIResourceHandler(options) {
+    const { registry, onError } = options;
+    return function handleUIResource(uri) {
+        const result = handleUIResourceRead(uri, registry);
+        if (result.handled && result.error && onError) {
+            onError(result.error, uri);
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=ui-resource.handler.js.map

package/src/tool/ui/ui-resource.handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-resource.handler.js","sourceRoot":"","sources":["../../../../src/tool/ui/ui-resource.handler.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;AAkEH,oDAgEC;AAkBD,0DAYC;AA5JD,qCAAyD;AACzD,oDAQ+B;AA0B/B;;;;;;;;;;;;;;GAcG;AACH,SAAS,yBAAyB,CAAC,QAAgB;IACjD,OAAO,IAAA,8BAAyB,EAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,oBAAoB,CAClC,GAAW,EACX,QAAwB,EACxB,YAA6B;IAE7B,qCAAqC;IACrC,IAAI,CAAC,IAAA,0BAAe,EAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,yCAAyC;IACzC,MAAM,QAAQ,GAAG,IAAA,gCAAqB,EAAC,YAAY,CAAC,CAAC;IAErD,sDAAsD;IACtD,2CAA2C;IAC3C,MAAM,YAAY,GAAG,IAAA,yBAAc,EAAC,GAAG,CAAC,CAAC;IACzC,IAAI,YAAY,EAAE,CAAC;QACjB,qEAAqE;QACrE,qFAAqF;QACrF,MAAM,YAAY,GAAG,QAAQ,CAAC,eAAe,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACrE,IAAI,YAAY,EAAE,CAAC;YACjB,qEAAqE;YACrE,qEAAqE;YACrE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE;oBACN,QAAQ,EAAE;wBACR;4BACE,GAAG;4BACH,QAAQ;4BACR,IAAI,EAAE,YAAY;yBACnB;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,uEAAuE;QACvE,oCAAoC;QACpC,EAAE;QACF,uEAAuE;QACvE,kEAAkE;QAClE,MAAM,IAAI,GAAG,yBAAyB,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAE9D,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM,EAAE;gBACN,QAAQ,EAAE;oBACR;wBACE,GAAG;wBACH,QAAQ;wBACR,IAAI,EAAE,IAAI;qBACX;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,OAAO;QACL,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,mCAAmC,GAAG,yCAAyC;KACvF,CAAC;AACJ,CAAC;AAYD;;;;;GAKG;AACH,SAAgB,uBAAuB,CAAC,OAAiC;IACvE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEtC,OAAO,SAAS,gBAAgB,CAAC,GAAW;QAC1C,MAAM,MAAM,GAAG,oBAAoB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAEnD,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,IAAI,OAAO,EAAE,CAAC;YAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC7B,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * UI Resource Handler\n *\n * Handles resources/read requests for ui:// URIs, serving widget HTML\n * from the ToolUIRegistry.\n *\n * Supported URI format:\n * - ui://widget/{toolName}.html - Static widget HTML (pre-compiled at startup)\n *\n * The static widget is registered at server startup for tools with\n * `servingMode: 'static'`. The widget HTML includes the FrontMCP Bridge\n * which reads tool output from the platform context at runtime.\n *\n * @example\n * ```typescript\n * // Client requests widget HTML (OpenAI discovery)\n * const result = await client.readResource({\n *   uri: 'ui://widget/get_weather.html'\n * });\n *\n * // Returns pre-compiled widget with FrontMCP Bridge\n * // Widget reads tool output from window.openai.toolOutput at runtime\n * ```\n */\n\nimport type { ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';\nimport type { AIPlatformType } from '../../notification/notification.service';\nimport { createDefaultBaseTemplate } from '@frontmcp/ui';\nimport {\n  type ToolUIRegistry,\n  UI_RESOURCE_SCHEME,\n  isUIResourceUri,\n  isStaticWidgetUri,\n  parseWidgetUri,\n  getUIResourceMimeType,\n  type ParsedWidgetUri,\n} from '@frontmcp/ui/registry';\n\n/**\n * Result of handling a UI resource request\n */\nexport interface UIResourceHandleResult {\n  /** Whether the URI was handled */\n  handled: boolean;\n  /** The resource result if handled successfully */\n  result?: ReadResourceResult;\n  /** Error message if handling failed */\n  error?: string;\n}\n\n/**\n * Options for handling a UI resource read request\n */\nexport interface HandleUIResourceOptions {\n  /** The UI resource URI */\n  uri: string;\n  /** The ToolUIRegistry containing cached HTML */\n  registry: ToolUIRegistry;\n  /** Platform type of the connected client */\n  platformType?: AIPlatformType;\n}\n\n/**\n * Generate a placeholder widget HTML that reads from window.openai.toolOutput.\n *\n * Delegates to @frontmcp/ui's createDefaultBaseTemplate which provides:\n * - Tailwind CSS with @theme configuration\n * - Platform polyfills (callTool, detectMcpSession, getToolOutput)\n * - Polling for toolOutput injection\n * - Default JSON renderer (data-type-specific renderers are in @frontmcp/ui)\n *\n * This is returned when the static widget URI is fetched before the tool is called.\n * OpenAI caches this HTML, so it must be dynamic (read toolOutput at runtime).\n *\n * @param toolName - The name of the tool\n * @returns HTML string with a dynamic widget that renders toolOutput\n */\nfunction generatePlaceholderWidget(toolName: string): string {\n  return createDefaultBaseTemplate({ toolName });\n}\n\n/**\n * Handle a UI resource read request\n *\n * @param uri - The UI resource URI\n * @param registry - The ToolUIRegistry containing cached HTML\n * @param platformType - Optional platform type for dynamic MIME type selection\n * @returns Handle result with content or error\n */\nexport function handleUIResourceRead(\n  uri: string,\n  registry: ToolUIRegistry,\n  platformType?: AIPlatformType,\n): UIResourceHandleResult {\n  // Check if this is a UI resource URI\n  if (!isUIResourceUri(uri)) {\n    return { handled: false };\n  }\n\n  // Get the platform-appropriate MIME type\n  const mimeType = getUIResourceMimeType(platformType);\n\n  // Try static widget URI (ui://widget/{toolName}.html)\n  // This is used by OpenAI at discovery time\n  const widgetParsed = parseWidgetUri(uri);\n  if (widgetParsed) {\n    // Check for pre-compiled static widget from the developer's template\n    // Static widgets are compiled at server startup for tools with servingMode: 'static'\n    const cachedWidget = registry.getStaticWidget(widgetParsed.toolName);\n    if (cachedWidget) {\n      // Return the developer's actual template (SSR'd React/MDX component)\n      // This template includes the FrontMCP Bridge for runtime data access\n      return {\n        handled: true,\n        result: {\n          contents: [\n            {\n              uri,\n              mimeType,\n              text: cachedWidget,\n            },\n          ],\n        },\n      };\n    }\n\n    // Fallback to dynamic placeholder widget if no pre-compiled template.\n    // This is returned when the tool doesn't have a UI template configured\n    // or uses a different serving mode.\n    //\n    // OpenAI caches widget HTML from outputTemplate URI, so we must return\n    // a template that reads from window.openai.toolOutput at runtime.\n    const html = generatePlaceholderWidget(widgetParsed.toolName);\n\n    return {\n      handled: true,\n      result: {\n        contents: [\n          {\n            uri,\n            mimeType,\n            text: html,\n          },\n        ],\n      },\n    };\n  }\n\n  // Unknown UI resource URI format\n  return {\n    handled: true,\n    error: `Invalid UI resource URI format: ${uri}. Expected: ui://widget/{toolName}.html`,\n  };\n}\n\n/**\n * Options for creating a UI resource handler\n */\nexport interface UIResourceHandlerOptions {\n  /** ToolUIRegistry instance */\n  registry: ToolUIRegistry;\n  /** Optional custom error handler */\n  onError?: (error: string, uri: string) => void;\n}\n\n/**\n * Create a UI resource handler function\n *\n * @param options - Handler options\n * @returns Handler function that can be used in the read-resource flow\n */\nexport function createUIResourceHandler(options: UIResourceHandlerOptions) {\n  const { registry, onError } = options;\n\n  return function handleUIResource(uri: string): UIResourceHandleResult {\n    const result = handleUIResourceRead(uri, registry);\n\n    if (result.handled && result.error && onError) {\n      onError(result.error, uri);\n    }\n\n    return result;\n  };\n}\n"]}

package/src/transport/adapters/transport.local.adapter.d.ts

@@ -6,7 +6,7 @@ import { InMemoryEventStore } from '../transport.event-store';
 import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { SSEServerTransport } from '../legacy/legacy.sse.tranporter';
-import { ZodObject } from 'zod';
+import { ZodType } from 'zod';
 import { FrontMcpLogger, ServerResponse } from '../../common';
 import { Scope } from '../../scope';
 export declare abstract class LocalTransportAdapter<T extends StreamableHTTPServerTransport | SSEServerTransport> {
@@ -26,7 +26,7 @@ export declare abstract class LocalTransportAdapter<T extends StreamableHTTPServ
     constructor(scope: Scope, key: TransportKey, onDispose: () => void, res: ServerResponse);
     abstract createTransport(sessionId: string, response: ServerResponse): T;
     abstract initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
-    abstract sendElicitRequest<T extends ZodObject<any>>(relatedRequestId: RequestId, message: string, requestedSchema: T): Promise<TypedElicitResult<T>>;
+    abstract sendElicitRequest<T extends ZodType>(relatedRequestId: RequestId, message: string, requestedSchema: T): Promise<TypedElicitResult<T>>;
     abstract handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     connectServer(): Promise<void>;
     get newRequestId(): RequestId;

package/src/transport/adapters/transport.local.adapter.js

@@ -27,17 +27,30 @@ class LocalTransportAdapter {
     }
     connectServer() {
         const { info } = this.scope.metadata;
-        // TODO: collect server options from scope
+        // Check if completions capability should be enabled (when prompts or resources are present)
+        const hasPrompts = this.scope.prompts.hasAny();
+        const hasResources = this.scope.resources.hasAny();
+        const hasTools = this.scope.tools.hasAny();
+        const completionsCapability = hasPrompts || hasResources ? { completions: {} } : {};
         const serverOptions = {
             instructions: '',
             capabilities: {
-                tools: {
-                    subscribe: true,
-                    listChanged: true,
-                },
+                ...this.scope.tools.getCapabilities(),
+                ...this.scope.resources.getCapabilities(),
+                ...this.scope.prompts.getCapabilities(),
+                ...completionsCapability,
+                // MCP logging protocol support - allows clients to set log level via logging/setLevel
+                logging: {},
             },
             serverInfo: info,
         };
+        this.logger.info('connectServer: advertising capabilities', {
+            hasTools,
+            hasResources,
+            hasPrompts,
+            capabilities: JSON.stringify(serverOptions.capabilities),
+            serverInfo: JSON.stringify(serverOptions.serverInfo),
+        });
         this.server = new index_js_1.Server(info, serverOptions);
         const handlers = (0, mcp_handlers_1.createMcpHandlers)({
             scope: this.scope,
@@ -46,6 +59,8 @@ class LocalTransportAdapter {
         for (const handler of handlers) {
             this.server.setRequestHandler(handler.requestSchema, handler.handler);
         }
+        // Register server with notification service for server→client notifications
+        this.scope.notifications.registerServer(this.key.sessionId, this.server);
         return this.server.connect(this.transport);
     }
     get newRequestId() {
@@ -53,6 +68,8 @@ class LocalTransportAdapter {
     }
     async destroy(reason) {
         console.log('destroying transporter, reason:', reason);
+        // Unregister server from notification service
+        this.scope.notifications.unregisterServer(this.key.sessionId);
         try {
             // if(!this.transport.closed){
             //   this.transport.close();
@@ -92,11 +109,15 @@ class LocalTransportAdapter {
     }
     ensureAuthInfo(req, transport) {
         const { token, user, session } = req[common_1.ServerRequestTokens.auth];
+        // Session should always exist now (created in session.verify for public mode)
+        // But add defensive fallback for safety in case session is undefined
+        const sessionId = session?.id ?? `fallback:${Date.now()}`;
+        const sessionPayload = session?.payload ?? { protocol: 'streamable-http' };
         req.auth = {
             token,
             user,
-            sessionId: session.id,
-            sessionIdPayload: session.payload,
+            sessionId,
+            sessionIdPayload: sessionPayload,
             scopes: [],
             clientId: user.sub ?? '',
             transport,