feat: support metadata in Python SDK

examples/python-server-demo/README.md

@@ -4,11 +4,13 @@ A Python MCP server implementation inspired by the TypeScript server demo. This
 
 ## Features
 
-This server provides three tools that create different types of UI resources:
+This server provides multiple tools that demonstrate different types of UI resources and metadata capabilities:
 
-- **showExternalUrl** - Creates a UI resource displaying an external URL (example.com)
-- **showRawHtml** - Creates a UI resource with raw HTML content
-- **showRemoteDom** - Creates a UI resource with remote DOM script using React framework
+### Basic UI Resources
+- **show_external_url** - Creates a UI resource displaying an external URL (example.com) with preferred frame size metadata
+- **show_raw_html** - Creates a UI resource with raw HTML content
+- **show_remote_dom** - Creates a UI resource with remote DOM script using React framework
+- **show_action_html** - Creates a UI resource with interactive buttons demonstrating intent actions
 
 ## Installation
 
@@ -50,6 +52,54 @@ Each tool returns an MCP resource that can be rendered by MCP UI clients:
 - **Raw HTML**: Returns a resource with HTML content `<h1>Hello from Raw HTML</h1>`
 - **Remote DOM**: Returns a resource with JavaScript that creates UI elements dynamically
 
+## UI Metadata
+
+The SDK supports UI metadata through the `uiMetadata` parameter in `create_ui_resource()`.
+
+### Metadata Keys
+
+Use the `UIMetadataKey` constants for type-safe metadata keys:
+
+- **`UIMetadataKey.PREFERRED_FRAME_SIZE`**: CSS dimensions for the iframe
+  - Type: `list[str, str]` - [width, height] as CSS dimension strings
+  - Examples: `["800px", "600px"]`, `["100%", "50vh"]`, `["50rem", "80%"]`
+  - Must include CSS units (px, %, vh, vw, rem, em, etc.)
+
+- **`UIMetadataKey.INITIAL_RENDER_DATA`**: Initial data for the UI component
+  - Type: `dict[str, Any]` - Any JSON-serializable dictionary
+
+### How It Works
+
+1. All `uiMetadata` keys are automatically prefixed with `mcpui.dev/ui-`
+2. Prefixed metadata is merged with any custom `metadata`
+3. The combined metadata is added to the resource's `_meta` field
+4. Custom metadata keys are preserved as-is (not prefixed)
+
+### Example Usage
+
+```python
+from mcp_ui_server import create_ui_resource, UIMetadataKey
+
+ui_resource = create_ui_resource({
+    "uri": "ui://my-component",
+    "content": {
+        "type": "rawHtml",
+        "htmlString": "<h1>Hello</h1>"
+    },
+    "encoding": "text",
+    "uiMetadata": {
+        UIMetadataKey.PREFERRED_FRAME_SIZE: ["1200px", "800px"],
+        # Or use string literal: "preferred-frame-size": ["1200px", "800px"]
+    },
+    # Optional: custom metadata (not prefixed)
+    "metadata": {
+        "custom.author": "My Server",
+        "custom.version": "1.0.0"
+    }
+})
+```
+
+
 ## Development
 
 ```bash

examples/python-server-demo/python_server_demo.py

@@ -12,22 +12,25 @@
 import argparse
 from mcp.server.fastmcp import FastMCP
 
-from mcp_ui_server import create_ui_resource
+from mcp_ui_server import create_ui_resource, UIMetadataKey
 from mcp_ui_server.core import UIResource
 
 # Create FastMCP instance
 mcp = FastMCP("python-server-demo")
 
 @mcp.tool()
 def show_external_url() -> list[UIResource]:
-    """Creates a UI resource displaying an external URL (example.com)."""
+    """Creates a UI resource displaying an external URL (example.com) with preferred frame size."""
     ui_resource = create_ui_resource({
         "uri": "ui://greeting",
         "content": {
             "type": "externalUrl",
             "iframeUrl": "https://example.com"
         },
-        "encoding": "text"
+        "encoding": "text",
+        "uiMetadata": {
+            UIMetadataKey.PREFERRED_FRAME_SIZE: ["800px", "600px"]  # CSS dimension strings (can be px, %, vh, etc.)
+        }
     })
     return [ui_resource]
 

sdks/python/server/README.md

@@ -133,6 +133,110 @@ blob_resource = create_ui_resource({
 })
 ```
 
+### UI Metadata
+
+Enhance resources with metadata for client-side handling. The SDK automatically prefixes UI-specific metadata with `mcpui.dev/ui-` to distinguish it from custom metadata.
+
+#### Preferred Frame Size
+
+Specify preferred dimensions for UI rendering:
+
+```python
+resource = create_ui_resource({
+    "uri": "ui://chart",
+    "content": {
+        "type": "externalUrl",
+        "iframeUrl": "https://charts.example.com/widget"
+    },
+    "encoding": "text",
+    "uiMetadata": {
+        "preferred-frame-size": [800, 600]  # width, height in pixels or css units
+    }
+})
+```
+
+#### Initial Render Data
+
+Provide data to components at initialization:
+
+```python
+resource = create_ui_resource({
+    "uri": "ui://dashboard",
+    "content": {
+        "type": "remoteDom",
+        "script": """
+            function Dashboard({ theme, userId }) {
+                // Component receives initial data
+                return <div>Dashboard for user {userId}</div>;
+            }
+        """,
+        "framework": "react"
+    },
+    "encoding": "text",
+    "uiMetadata": {
+        "initial-render-data": {
+            "theme": "dark",
+            "userId": "123"
+        }
+    }
+})
+```
+
+#### Multiple Metadata Fields
+
+Combine multiple metadata fields:
+
+```python
+resource = create_ui_resource({
+    "uri": "ui://data-viz",
+    "content": {
+        "type": "rawHtml",
+        "htmlString": "<canvas id='chart'></canvas>"
+    },
+    "encoding": "text",
+    "uiMetadata": {
+        "preferred-frame-size": ["800px", "600px"],
+        "initial-render-data": {
+            "chartType": "bar",
+            "dataSet": "quarterly-sales"
+        }
+    }
+})
+```
+
+#### Custom Metadata
+
+Add custom metadata alongside UI metadata:
+
+```python
+resource = create_ui_resource({
+    "uri": "ui://custom-widget",
+    "content": {
+        "type": "rawHtml",
+        "htmlString": "<div>Widget</div>"
+    },
+    "encoding": "text",
+    "uiMetadata": {
+        "preferred-frame-size": [640, 480]
+    },
+    "metadata": {
+        "customKey": "customValue",
+        "version": "1.0.0"
+    }
+})
+
+# Result includes both prefixed UI metadata and custom metadata:
+# {
+#   "resource": {
+#     "meta": {
+#       "mcpui.dev/ui-preferred-frame-size": [640, 480],
+#       "customKey": "customValue",
+#       "version": "1.0.0"
+#     }
+#   }
+# }
+```
+
 ### UI Actions
 
 Create action results for user interactions:
@@ -266,7 +370,9 @@ Creates a UI resource from the given options.
 {
     "uri": str,  # Must start with "ui://"
     "content": Union[RawHtmlPayload, ExternalUrlPayload, RemoteDomPayload],
-    "encoding": Literal["text", "blob"]
+    "encoding": Literal["text", "blob"],
+    "uiMetadata": Optional[dict[str, Any]],  # UI-specific metadata (auto-prefixed)
+    "metadata": Optional[dict[str, Any]]     # Custom metadata
 }
 ```
 

sdks/python/server/src/mcp_ui_server/__init__.py

@@ -24,6 +24,7 @@
     UIActionResultPrompt,
     UIActionResultToolCall,
     UIActionType,
+    UIMetadataKey,
 )
 
 __version__ = "5.2.0"
@@ -40,6 +41,7 @@
     "UIActionResultLink",
     "UIActionResultIntent",
     "UIActionResultNotification",
+    "UIMetadataKey",
     "UIResource",
     "create_ui_resource",
     "ui_action_result_tool_call",

sdks/python/server/src/mcp_ui_server/core.py

@@ -8,6 +8,7 @@
 
 from .exceptions import InvalidContentError, InvalidURIError
 from .types import (
+    UI_METADATA_PREFIX,
     CreateUIResourceOptions,
     MimeType,
     UIActionResultIntent,
@@ -30,21 +31,72 @@ def __init__(self, resource: TextResourceContents | BlobResourceContents, **kwar
         )
 
 
+def _get_additional_resource_props(options: CreateUIResourceOptions) -> dict[str, Any]:
+    """Get additional resource properties including metadata.
+
+    Prefixes UI-specific metadata with the UI metadata prefix to be recognized by the client.
+
+    Args:
+        options: The UI resource options
+
+    Returns:
+        Dictionary of additional properties to merge into the resource
+    """
+    additional_props: dict[str, Any] = {}
+
+    # Prefix ui specific metadata with the prefix to be recognized by the client
+    if options.uiMetadata or options.metadata:
+        ui_prefixed_metadata: dict[str, Any] = {}
+
+        if options.uiMetadata:
+            for key, value in options.uiMetadata.items():
+                ui_prefixed_metadata[f"{UI_METADATA_PREFIX}{key}"] = value
+
+        # Allow user defined metadata to override ui metadata
+        _meta: dict[str, Any] = {
+            **ui_prefixed_metadata,
+            **(options.metadata or {}),
+        }
+
+        if _meta:
+            additional_props["_meta"] = _meta
+
+    return additional_props
+
+
 def create_ui_resource(options_dict: dict[str, Any]) -> UIResource:
     """Create a UIResource.
 
     This is the object that should be included in the 'content' array of a toolResult.
 
     Args:
-        options: Configuration for the interactive resource
+        options_dict: Configuration dictionary for the interactive resource. Keys:
+            - uri (str): Resource identifier starting with 'ui://'
+            - content (dict): Content payload (type: rawHtml, externalUrl, or remoteDom)
+            - encoding (str): 'text' or 'blob'
+            - uiMetadata (dict, optional): UI metadata. Use UIMetadataKey constants:
+                * UIMetadataKey.PREFERRED_FRAME_SIZE: list[str, str] - CSS dimensions like ["800px", "600px"]
+                * UIMetadataKey.INITIAL_RENDER_DATA: dict - Initial data for the UI
+            - metadata (dict, optional): Custom metadata (not prefixed)
 
     Returns:
-        A UIResource instance
+        A UIResource instance ready to be included in tool results
 
     Raises:
         InvalidURIError: If the URI doesn't start with 'ui://'
         InvalidContentError: If content validation fails
         MCPUIServerError: For other errors
+
+    Example:
+        >>> from mcp_ui_server import create_ui_resource, UIMetadataKey
+        >>> resource = create_ui_resource({
+        ...     "uri": "ui://my-widget",
+        ...     "content": {"type": "rawHtml", "htmlString": "<h1>Hello</h1>"},
+        ...     "encoding": "text",
+        ...     "uiMetadata": {
+        ...         UIMetadataKey.PREFERRED_FRAME_SIZE: ["800px", "600px"]
+        ...     }
+        ... })
     """
     options = CreateUIResourceOptions.model_validate(options_dict)
     # Validate URI
@@ -108,17 +160,22 @@ def create_ui_resource(options_dict: dict[str, Any]) -> UIResource:
     # Create resource based on encoding type
     encoding = options.encoding
 
+    # Get additional properties including metadata
+    additional_props = _get_additional_resource_props(options)
+
     if encoding == "text":
         resource: TextResourceContents | BlobResourceContents = TextResourceContents(
             uri=AnyUrl(options.uri),
             mimeType=mime_type,
             text=actual_content_string,
+            **additional_props,
         )
     elif encoding == "blob":
         resource = BlobResourceContents(
             uri=AnyUrl(options.uri),
             mimeType=mime_type,
             blob=base64.b64encode(actual_content_string.encode('utf-8')).decode('ascii'),
+            **additional_props,
         )
     else:
         raise InvalidContentError(f"Invalid encoding type: {encoding}")