feat: support metadata in Python SDK

[Copilot]

Problem

The Python SDK was missing support for the uiMetadata field when creating UI resources, causing metadata like preferred-frame-size to be ignored and resulting in meta: null in the output. This prevented users from specifying important UI hints such as preferred dimensions or initial render data.

# This was being ignored, resulting in meta: null
resource = create_ui_resource({
    "uri": "ui://chart",
    "uiMetadata": {
        "preferred-frame-size": [800, 600],
    },
    "content": {"type": "rawHtml", "htmlString": "<div>...</div>"},
    "encoding": "text"
})

Solution

Implemented full metadata support in the Python SDK to match the TypeScript implementation:

• Added uiMetadata and metadata optional fields to CreateUIResourceOptions
• UI-specific metadata is automatically prefixed with mcpui.dev/ui- for client recognition
• Custom metadata can be provided alongside UI metadata without prefixing
• Metadata is properly included in the resource's _meta field for MCP protocol compliance

Usage

from mcp_ui_server import create_ui_resource

# Specify preferred frame size
resource = create_ui_resource({
    "uri": "ui://visualization",
    "content": {
        "type": "externalUrl",
        "iframeUrl": "https://charts.example.com"
    },
    "encoding": "text",
    "uiMetadata": {
        "preferred-frame-size": [800, 600]
    }
})

# Provide initial render data
resource = create_ui_resource({
    "uri": "ui://dashboard",
    "content": {
        "type": "remoteDom",
        "script": "function Dashboard({ theme }) { ... }",
        "framework": "react"
    },
    "encoding": "text",
    "uiMetadata": {
        "initial-render-data": {
            "theme": "dark",
            "userId": "123"
        }
    }
})

# Combine UI and custom metadata
resource = create_ui_resource({
    "uri": "ui://widget",
    "content": {"type": "rawHtml", "htmlString": "<div>Widget</div>"},
    "encoding": "text",
    "uiMetadata": {
        "preferred-frame-size": [640, 480]
    },
    "metadata": {
        "version": "1.0.0",
        "customKey": "value"
    }
})

Changes

• types.py: Added uiMetadata and metadata fields, metadata constants
• core.py: Implemented _get_additional_resource_props() helper for metadata processing
• test_metadata.py: Added 11 comprehensive test cases covering all metadata scenarios
• README.md: Added extensive documentation with examples
• python_server_demo.py: Updated example to demonstrate metadata usage

Testing

• All 32 tests pass (21 existing + 11 new metadata tests)
• Covers all content types (rawHtml, externalUrl, remoteDom)
• Covers both encodings (text, blob)
• Tests metadata prefixing, override behavior, and serialization
• Linting (Ruff) and type checking (Pyright) clean
• Security scan (CodeQL) clean - 0 vulnerabilities

Compatibility

• Matches TypeScript SDK implementation
• No breaking changes - purely additive
• Works with all existing code without modification
• Compatible with MCP protocol specifications

Fixes #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>python SDK and metadata</issue_title>
<issue_description>I tried passing in the preferred-frame-size as metadata from python sdk's create_ui_resource as shown below

@mcp.tool
def some_ui_resource():
    """plot a dataframe"""
    df = fetch_a_dataframe()
    axes = df.plot()
    #convert matplotlib plot to base64 string
    import io
    import base64
    buf = io.BytesIO()
    fig = axes.get_figure()
    fig.savefig(buf, format='png')
    buf.seek(0)
    plot_data = base64.b64encode(buf.read()).decode('utf-8')
    buf.close()
    return create_ui_resource({
        "uri": f"ui://some/ui/path",
        "uiMetadata": {
            "preferred-frame-size": [800, 600],
        },
        "content": {
            "type": "rawHtml",
            "htmlString": f"""
                <img src="data:image/jpeg;base64,{plot_data}" alt="plot"/>
            """
        },
        "encoding": "text"
    })

I tried a model_dump of the created resource object and seems like the metadata is null.

{
    "type": "resource",
    "resource": {
        "uri": "ui://some/uipath",
        "mimeType": "text/html",
        "meta": null,
        "text": "\n                <img src=\"data:image/jpeg;base64,some_data_here\" alt=\"plot\"/>\n            "
    },
    "annotations": null,
    "meta": null
}

is this a missing feature in python sdk?</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #133

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[cloudflare-workers-and-pages]

Deploying mcp-ui with    Cloudflare Pages

Latest commit:	b3d50a1
Status:	✅  Deploy successful!
Preview URL:	https://b9ab52d7.mcp-ui.pages.dev
Branch Preview URL:	https://copilot-fix-preferred-frame.mcp-ui.pages.dev

View logs

[Copilot]

Pull Request Overview

This PR adds comprehensive metadata support to the Python SDK, enabling UI resources to include metadata like preferred-frame-size and initial-render-data. The implementation matches the TypeScript SDK's approach by automatically prefixing UI-specific metadata with mcpui.dev/ui- while allowing custom metadata to be provided alongside without prefixing.

Key changes:

• Added uiMetadata and metadata optional fields to CreateUIResourceOptions
• Implemented metadata processing with automatic UI prefix application
• Added 11 comprehensive test cases covering all metadata scenarios

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
types.py	Added UI metadata constants, keys, and optional metadata fields to CreateUIResourceOptions
core.py	Implemented _get_additional_resource_props() helper for metadata processing and integration
test_metadata.py	Added comprehensive test suite with 11 test cases for all metadata scenarios
__init__.py	Exported UIMetadataKey class for external use
README.md	Added extensive documentation section with metadata usage examples
python_server_demo.py	Updated example to demonstrate metadata usage with UIMetadataKey
python-server-demo/README.md	Added metadata documentation and usage examples

[Copilot]

Using UIMetadataKey.PREFERRED_FRAME_SIZE as a dictionary key follows Python best practices, but the comment suggests this can accept CSS unit strings while the constant is defined as a plain string 'preferred-frame-size'. Consider documenting the expected value types (e.g., list of strings or list of numbers) in the UIMetadataKey class docstring to clarify the API contract.

[Copilot]

The UIMetadataKey class lacks documentation about the expected value types for each metadata key. For example, PREFERRED_FRAME_SIZE should clarify whether it expects a list of integers (pixels) or strings (CSS units), and INITIAL_RENDER_DATA should specify that it expects a dictionary. This would improve API usability and prevent type confusion.

Suggested change

	"""Keys for UI metadata."""
	"""
	Keys for UI metadata.
	- PREFERRED_FRAME_SIZE: expects a list of two integers [width, height] in pixels, e.g. [800, 600].
	- INITIAL_RENDER_DATA: expects a dictionary containing initial render data for the UI component.
	"""

[Copilot]

The comment indicates 'pixels or css units' but the example shows numeric values without units. This creates ambiguity about whether clients should pass [800, 600] (integers) or ['800px', '600px'] (strings). Consider providing examples for both cases or clarifying which format is preferred and how they differ in behavior.

[cubic-dev-ai]

1 issue found across 7 files

Prompt for AI agents (all 1 issues)

Understand the root cause of the following 1 issues and fix them.


<file name="examples/python-server-demo/README.md">

<violation number="1" location="examples/python-server-demo/README.md:76">
The example sets `preferred-frame-size` to string numbers (&quot;1200&quot;, &quot;800&quot;), but UI clients expect either numeric pixels or CSS values with units. Update the example to use integers or unit-suffixed strings so the metadata actually applies.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

The example sets preferred-frame-size to string numbers ("1200", "800"), but UI clients expect either numeric pixels or CSS values with units. Update the example to use integers or unit-suffixed strings so the metadata actually applies.

Prompt for AI agents

Address the following comment on examples/python-server-demo/README.md at line 76:

<comment>The example sets `preferred-frame-size` to string numbers (&quot;1200&quot;, &quot;800&quot;), but UI clients expect either numeric pixels or CSS values with units. Update the example to use integers or unit-suffixed strings so the metadata actually applies.</comment>

<file context>
@@ -50,6 +52,38 @@ Each tool returns an MCP resource that can be rendered by MCP UI clients:
+    },
+    &quot;encoding&quot;: &quot;text&quot;,
+    &quot;uiMetadata&quot;: {
+        &quot;preferred-frame-size&quot;: [&quot;1200&quot;, &quot;800&quot;],
+    },
+    # Optional: custom metadata (not prefixed)
</file context>

Suggested change

	"preferred-frame-size": ["1200", "800"],
	"preferred-frame-size": [1200, 800],