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]

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.