mcp-use 1.9.0 → 1.9.1-canary.0

package/dist/src/server/widgets/widget-helpers.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Widget helper utilities
+ *
+ * This module provides utility functions for widget registration, URI generation,
+ * and prop handling.
+ */
+import type { Hono as HonoType } from "hono";
+import type { UIResourceContent, UIResourceDefinition, InputDefinition, WidgetProps } from "../types/index.js";
+/**
+ * Generate a widget URI with optional build ID for cache busting
+ *
+ * @param widgetName - Widget name/identifier
+ * @param buildId - Optional build ID for cache busting
+ * @param extension - Optional file extension (e.g., '.html')
+ * @param suffix - Optional suffix (e.g., random ID for dynamic URIs)
+ * @returns Widget URI with build ID if available
+ *
+ * @example
+ * ```typescript
+ * generateWidgetUri('kanban-board', 'abc123', '.html')
+ * // Returns: 'ui://widget/kanban-board-abc123.html'
+ * ```
+ */
+export declare function generateWidgetUri(widgetName: string, buildId: string | undefined, extension?: string, suffix?: string): string;
+/**
+ * Convert widget props definition to tool input schema
+ *
+ * Transforms the widget props configuration into the format expected by
+ * the tool registration system, mapping types and handling defaults.
+ *
+ * @param props - Widget props configuration
+ * @returns Array of InputDefinition objects for tool registration
+ *
+ * @example
+ * ```typescript
+ * const props = {
+ *   title: { type: 'string', required: true, description: 'Board title' },
+ *   color: { type: 'string', default: 'blue' }
+ * };
+ * const inputs = convertPropsToInputs(props);
+ * // Returns: [
+ * //   { name: 'title', type: 'string', required: true, description: 'Board title' },
+ * //   { name: 'color', type: 'string', default: 'blue' }
+ * // ]
+ * ```
+ */
+export declare function convertPropsToInputs(props?: WidgetProps): InputDefinition[];
+/**
+ * Apply default values to widget props
+ *
+ * Extracts default values from the props configuration to use when
+ * the resource is accessed without parameters.
+ *
+ * @param props - Widget props configuration
+ * @returns Object with default values for each prop
+ *
+ * @example
+ * ```typescript
+ * const props = {
+ *   title: { type: 'string', default: 'My Board' },
+ *   color: { type: 'string', default: 'blue' },
+ *   size: { type: 'number' } // no default
+ * };
+ * const defaults = applyDefaultProps(props);
+ * // Returns: { title: 'My Board', color: 'blue' }
+ * ```
+ */
+export declare function applyDefaultProps(props?: WidgetProps): Record<string, any>;
+/**
+ * Read build manifest file
+ *
+ * @returns Build manifest or null if not found
+ *
+ * @example
+ * ```typescript
+ * const manifest = await readBuildManifest();
+ * if (manifest) {
+ *   console.log('Build ID:', manifest.buildId);
+ *   console.log('Widgets:', manifest.widgets);
+ * }
+ * ```
+ */
+export declare function readBuildManifest(): Promise<{
+    includeInspector: boolean;
+    widgets: string[] | Record<string, any>;
+    buildTime?: string;
+    buildId?: string;
+} | null>;
+/**
+ * Server configuration for widget UI resource creation
+ */
+export interface WidgetServerConfig {
+    /** Server host */
+    serverHost: string;
+    /** Server port */
+    serverPort: number;
+    /** Server base URL (if configured) */
+    serverBaseUrl?: string;
+    /** Build ID for cache busting */
+    buildId?: string;
+}
+/**
+ * Create a UIResource object for a widget with the given parameters
+ *
+ * This function creates a consistent UIResource structure that can be rendered
+ * by MCP-UI compatible clients. It handles URL configuration, build IDs, and
+ * metadata merging.
+ *
+ * @param definition - UIResource definition
+ * @param params - Parameters to pass to the widget via URL
+ * @param serverConfig - Server configuration (host, port, baseUrl, buildId)
+ * @returns UIResource object compatible with MCP-UI
+ *
+ * @example
+ * ```typescript
+ * const serverConfig = {
+ *   serverHost: 'localhost',
+ *   serverPort: 3000,
+ *   serverBaseUrl: 'http://localhost:3000',
+ *   buildId: 'abc123'
+ * };
+ *
+ * const definition = {
+ *   type: 'appsSdk',
+ *   name: 'kanban-board',
+ *   title: 'Kanban Board',
+ *   htmlTemplate: '<div>...</div>',
+ *   appsSdkMetadata: { ... }
+ * };
+ *
+ * const uiResource = await createWidgetUIResource(definition, { title: 'My Board' }, serverConfig);
+ * ```
+ */
+/**
+ * Get content type for a file based on its extension
+ *
+ * @param filename - The filename or path
+ * @returns MIME type string
+ *
+ * @example
+ * ```typescript
+ * getContentType('script.js') // Returns: 'application/javascript'
+ * getContentType('styles.css') // Returns: 'text/css'
+ * ```
+ */
+export declare function getContentType(filename: string): string;
+/**
+ * Process widget HTML with base URL injection and path conversion
+ *
+ * @param html - Original HTML content
+ * @param widgetName - Widget identifier
+ * @param baseUrl - Server base URL
+ * @returns Processed HTML with injected base tag and absolute URLs
+ *
+ * @example
+ * ```typescript
+ * const html = '<html><head></head><body>...</body></html>';
+ * const processed = processWidgetHtml(html, 'kanban-board', 'http://localhost:3000');
+ * ```
+ */
+export declare function processWidgetHtml(html: string, widgetName: string, baseUrl: string): string;
+/**
+ * Create a widget registration object with standard metadata
+ *
+ * @param widgetName - Widget identifier
+ * @param metadata - Widget metadata from file or manifest
+ * @param html - Processed HTML template
+ * @param serverConfig - Server configuration for CSP and URLs
+ * @param isDev - Whether this is development mode
+ * @returns Widget registration object
+ *
+ * @example
+ * ```typescript
+ * const registration = createWidgetRegistration(
+ *   'kanban-board',
+ *   { title: 'Kanban Board', description: 'Task board' },
+ *   '<html>...</html>',
+ *   { serverBaseUrl: 'http://localhost:3000', cspUrls: [] },
+ *   true
+ * );
+ * ```
+ */
+export declare function createWidgetRegistration(widgetName: string, metadata: any, html: string, serverConfig: {
+    serverBaseUrl: string;
+    cspUrls: string[];
+}, isDev?: boolean): {
+    name: string;
+    title: string;
+    description: string;
+    type: "appsSdk";
+    props: any;
+    _meta: Record<string, any>;
+    htmlTemplate: string;
+    appsSdkMetadata: Record<string, any>;
+};
+export declare function createWidgetUIResource(definition: UIResourceDefinition, params: Record<string, any>, serverConfig: WidgetServerConfig): Promise<UIResourceContent>;
+/**
+ * Ensure widget metadata has proper fallback values
+ *
+ * @param metadata - Widget metadata object
+ * @param widgetName - Widget identifier for fallback description
+ * @param widgetDescription - Optional custom description
+ * @returns Metadata with ensured description
+ *
+ * @example
+ * ```typescript
+ * const metadata = ensureWidgetMetadata({}, 'kanban-board');
+ * // Returns: { description: 'Widget: kanban-board' }
+ * ```
+ */
+export declare function ensureWidgetMetadata(metadata: any, widgetName: string, widgetDescription?: string): any;
+/**
+ * Read widget HTML file with consistent error handling
+ *
+ * @param filePath - Path to the HTML file
+ * @param widgetName - Widget identifier for error messages
+ * @returns HTML content or empty string on error
+ *
+ * @example
+ * ```typescript
+ * const html = await readWidgetHtml('/path/to/widget/index.html', 'kanban-board');
+ * ```
+ */
+export declare function readWidgetHtml(filePath: string, widgetName: string): Promise<string>;
+/**
+ * Register a widget from its HTML template and metadata
+ *
+ * This function encapsulates the common pattern of registering a widget:
+ * - Read and process HTML template
+ * - Ensure metadata has proper fallbacks
+ * - Create widget registration object
+ * - Call the registration callback
+ *
+ * @param widgetName - Widget identifier
+ * @param htmlPath - Path to the HTML template file
+ * @param metadata - Widget metadata
+ * @param serverConfig - Server configuration for CSP and URLs
+ * @param registerWidget - Callback to register the widget
+ * @param isDev - Whether this is development mode
+ * @returns Promise that resolves when widget is registered
+ *
+ * @example
+ * ```typescript
+ * await registerWidgetFromTemplate(
+ *   'kanban-board',
+ *   './dist/resources/widgets/kanban-board/index.html',
+ *   { title: 'Kanban Board' },
+ *   serverConfig,
+ *   registerWidget,
+ *   false
+ * );
+ * ```
+ */
+export declare function registerWidgetFromTemplate(widgetName: string, htmlPath: string, metadata: any, serverConfig: {
+    serverBaseUrl: string;
+    cspUrls: string[];
+}, registerWidget: (widgetDef: any) => void, isDev?: boolean): Promise<void>;
+/**
+ * Setup static file serving routes for public files
+ *
+ * Creates an HTTP route to serve files from the public/ or dist/public/ directory.
+ * This function encapsulates the common pattern of serving static files.
+ *
+ * @param app - Hono app instance to mount routes on
+ * @param useDistDirectory - Whether to serve from dist/public (production) or public (dev)
+ *
+ * @example
+ * ```typescript
+ * // For development mode
+ * setupPublicRoutes(app, false);
+ *
+ * // For production mode
+ * setupPublicRoutes(app, true);
+ * ```
+ */
+export declare function setupPublicRoutes(app: HonoType, useDistDirectory?: boolean): void;
+//# sourceMappingURL=widget-helpers.d.ts.map

package/dist/src/server/widgets/widget-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-helpers.d.ts","sourceRoot":"","sources":["../../../../src/server/widgets/widget-helpers.ts"],"names":[],"mappings":"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"}

package/dist/src/server/widgets/widget-types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared type definitions for widget mounting and serving
+ *
+ * This module consolidates common types used across widget-related modules
+ * to avoid duplication and ensure consistency.
+ */
+/**
+ * Server configuration for widget mounting
+ *
+ * Unified interface used by both development and production widget mounting,
+ * as well as static route setup.
+ */
+export interface ServerConfig {
+    /** Base URL of the server */
+    serverBaseUrl: string;
+    /** Server port (optional for production) */
+    serverPort?: number | string;
+    /** Additional CSP URLs for widget security */
+    cspUrls: string[];
+    /** Build ID from manifest for cache busting (optional) */
+    buildId?: string;
+}
+/**
+ * Widget mounting options
+ *
+ * Common options used for both development and production widget mounting.
+ */
+export interface MountWidgetsOptions {
+    /** Base route for widgets (defaults to '/mcp-use/widgets') */
+    baseRoute?: string;
+    /** Resources directory path (defaults to 'resources') */
+    resourcesDir?: string;
+}
+/**
+ * Widget registration callback function type
+ *
+ * Used to register discovered widgets with the MCP server.
+ */
+export type RegisterWidgetCallback = (widgetDefinition: {
+    name: string;
+    title: string;
+    description: string;
+    type: "appsSdk";
+    props: any;
+    _meta: Record<string, any>;
+    htmlTemplate: string;
+    appsSdkMetadata: Record<string, any>;
+}) => void;
+//# sourceMappingURL=widget-types.d.ts.map

package/dist/src/server/widgets/widget-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-types.d.ts","sourceRoot":"","sources":["../../../../src/server/widgets/widget-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,gBAAgB,EAAE;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,GAAG,CAAC;IACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACtC,KAAK,IAAI,CAAC"}

package/dist/tool-execution-helpers-IVUDHXMK.js

@@ -0,0 +1,23 @@
+import {
+  createElicitMethod,
+  createEnhancedContext,
+  createReportProgressMethod,
+  createSampleMethod,
+  findSessionContext,
+  parseElicitParams,
+  sendProgressNotification,
+  withTimeout
+} from "./chunk-KHTTBIRP.js";
+import "./chunk-KUEVOU4M.js";
+import "./chunk-MTHLLDCX.js";
+import "./chunk-3GQAWCBQ.js";
+export {
+  createElicitMethod,
+  createEnhancedContext,
+  createReportProgressMethod,
+  createSampleMethod,
+  findSessionContext,
+  parseElicitParams,
+  sendProgressNotification,
+  withTimeout
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-use",
   "type": "module",
-  "version": "1.9.0",
+  "version": "1.9.1-canary.0",
   "description": "Opinionated MCP Framework for TypeScript (@modelcontextprotocol/sdk compatible) - Build MCP Agents, Clients and Servers with support for ChatGPT Apps, Code Mode, OAuth, Notifications, Sampling, Observability and more.",
   "author": "mcp-use, Inc.",
   "license": "MIT",
@@ -105,15 +105,16 @@
     "@hono/node-server": "^1.19.6",
     "@langchain/core": "^1.1.0",
     "@mcp-ui/server": "^5.15.0",
-    "@modelcontextprotocol/sdk": "https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1194",
+    "@modelcontextprotocol/sdk": "https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1209",
+    "express": "^5.2.0",
     "hono": "^4.10.7",
     "jose": "^6.1.2",
     "langchain": "^1.1.1",
     "posthog-node": "^5.14.1",
     "ws": "^8.18.3",
     "zod": "^4.1.13",
-    "@mcp-use/cli": "2.4.8",
-    "@mcp-use/inspector": "0.11.0"
+    "@mcp-use/cli": "2.4.9-canary.0",
+    "@mcp-use/inspector": "0.11.1-canary.0"
   },
   "optionalDependencies": {
     "chalk": "^5.6.2",
@@ -193,7 +194,7 @@
     "example:server:sampling": "tsx examples/server/sampling/src/server.ts",
     "example:client:sampling": "tsx examples/client/sampling-client.ts",
     "example:server:elicitation": "tsx examples/server/elicitation/src/server.ts",
-    "example:sampling": "lsof -ti:3001 | xargs kill -9 2>/dev/null; tsx examples/server/sampling/src/server.ts & sleep 3 && tsx examples/client/sampling-client.ts",
+    "example:sampling": "lsof -ti:3000 | xargs kill -9 2>/dev/null; tsx examples/server/sampling/src/server.ts & sleep 3 && tsx examples/client/sampling-client.ts",
     "example:server:oauth:supabase": "tsx examples/server/oauth/supabase/src/server.ts",
     "example:client:oauth:auth0": "tsx examples/server/oauth/auth0/src/server.ts",
     "example:client:oauth:workos": "tsx examples/server/oauth/workos/src/server.ts",