MCP-UI Python SDK

This library is a Python port of the MCP-UI TypeScript SDK.
It provides strongly typed helpers for creating UI resources and UI actions in MCP servers, with good type safety, and MCP-compatible JSON output.

---

📦 Installation

pip install mcp-ui

---

🚀 Core Concepts

What is a UI Resource?

A UI resource is a unit of UI data (e.g., an HTML snippet, iframe, or Remote DOM script) that MCP clients can render.
This SDK helps you create them consistently with correct metadata and encodings.

What is a UI Action?

A UI action result represents an action the MCP client should take (e.g., open a link, show a prompt, call a tool).

---

🔧 Usage

1. Creating a UI Resource

Raw HTML

from mcp_ui import RawHtmlContent, CreateUIResourceOptions, create_ui_resource

options = CreateUIResourceOptions(
    uri="ui://demo/html",
    content=RawHtmlContent(type="rawHtml", htmlString="<h1>Hello MCP</h1>"),
    encoding="text"
)

resource = create_ui_resource(options)
print(resource)

Output:

{
  "type": "resource",
  "resource": {
    "uri": "ui://demo/html",
    "mimeType": "text/html",
    "text": "<h1>Hello MCP</h1>",
    "blob": null,
    "_meta": null
  }
}

External URL (iframe)

from mcp_ui import ExternalUrlContent, CreateUIResourceOptions, create_ui_resource

options = CreateUIResourceOptions(
    uri="ui://demo/frame",
    content=ExternalUrlContent(type="externalUrl", iframeUrl="https://example.com"),
    encoding="text"
)

iframe_res = create_ui_resource(options)

Output:

{
  "type": "resource",
  "resource": {
    "uri": "ui://demo/frame",
    "mimeType": "text/uri-list",
    "text": "https://example.com",
    "blob": null,
    "_meta": null
  }
}

Remote DOM (React)

from mcp_ui import RemoteDomContent, CreateUIResourceOptions, create_ui_resource

options = CreateUIResourceOptions(
    uri="ui://demo/react",
    content=RemoteDomContent(type="remoteDom", script="console.log('Hello')", framework="react"),
    encoding="blob"
)

remote_res = create_ui_resource(options)

Output (blob is Base64-encoded):

{
  "type": "resource",
  "resource": {
    "uri": "ui://demo/react",
    "mimeType": "application/vnd.mcp-ui.remote-dom+javascript; framework=react",
    "blob": "Y29uc29sZS5sb2coJ0hlbGxvJyk=",
    "text": null,
    "_meta": null
  }
}

---

2. Adding Metadata

You can attach metadata to resources. Keys are automatically prefixed with `mcpui.dev/ui-`.

options = CreateUIResourceOptions(
    uri="ui://demo/meta",
    content=RawHtmlContent(type="rawHtml", htmlString="<p>Meta Example</p>"),
    encoding="text",
    uiMetadata={"PREFERRED_FRAME_SIZE": {"width": 500, "height": 300}}
)

meta_res = create_ui_resource(options)

Output includes `_meta`:

{
  "type": "resource",
  "resource": {
    "uri": "ui://demo/meta",
    "mimeType": "text/html",
    "text": "<p>Meta Example</p>",
    "blob": null,
    "_meta": {
      "mcpui.dev/ui-preferred-frame-size": { "width": 500, "height": 300 }
    }
  }
}

---

3. UI Action Results

Tool Call

from mcp_ui import ui_action_result_tool_call
action = ui_action_result_tool_call("searchTool", {"query": "MCP SDK"})

Output:

{
  "type": "tool",
  "payload": {
    "toolName": "searchTool",
    "params": { "query": "MCP SDK" }
  }
}

Prompt

from mcp_ui import ui_action_result_prompt
action = ui_action_result_prompt("Please confirm your choice")

Output:

{
  "type": "prompt",
  "payload": { "prompt": "Please confirm your choice" }
}

Link

from mcp_ui import ui_action_result_link
action = ui_action_result_link("https://example.com")

Output:

{
  "type": "link",
  "payload": { "url": "https://example.com" }
}

Intent

from mcp_ui import ui_action_result_intent
action = ui_action_result_intent("share", {"platform": "twitter"})

Output:

{
  "type": "intent",
  "payload": {
    "intent": "share",
    "params": { "platform": "twitter" }
  }
}

Notification

from mcp_ui import ui_action_result_notification
action = ui_action_result_notification("Saved successfully!")

Output:

{
  "type": "notify",
  "payload": { "message": "Saved successfully!" }
}

---

📖 API Reference

create_ui_resource(options: CreateUIResourceOptions) → Dict[str, Any]

Creates a UI resource for MCP. Returns a JSON-serializable dict.

Parameters:

• uri: must start with ui://
• content: one of RawHtmlContent, ExternalUrlContent, RemoteDomContent
• encoding: "text" or "blob"
• uiMetadata: UI-specific metadata (auto-prefixed)
• metadata: General metadata
• resourceProps: Extra resource fields

Type System:

• Content payloads:
  • RawHtmlContent(htmlString)
  • ExternalUrlContent(iframeUrl)
  • RemoteDomContent(script, framework)
• Resource encodings:
  • HTMLTextContent (text string)
  • Base64BlobContent (blob string, base64)
• UI Action Results:
  • tool, prompt, link, intent, notify

---

⚙️ Notes

• Internally uses dataclasses for type safety, but always returns dicts (via `asdict()`) for MCP compatibility.
• Enforces URI format (ui:// prefix).
• Auto-encodes blob resources in Base64.

---

📄 License

MIT – Similar to the original MCP-UI Typescript server SDK.