mcp-ui 0.1.0__tar.gz

mcp_ui-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

mcp_ui-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

mcp_ui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_ui-0.1.0/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: mcp-ui
+Version: 0.1.0
+Summary: A Python SDK for building MCP UI resources (iframe, panels, text blocks, etc.) in a type-safe way.
+Project-URL: Homepage, https://github.com/jameszokah/mcp-ui
+Project-URL: Repository, https://github.com/jameszokah/mcp-ui
+Project-URL: Issues, https://github.com/jameszokah/mcp-ui/issues
+Project-URL: Documentation, https://github.com/jameszokah/mcp-ui#readme
+Author-email: James Zokah <jameszokah@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,chat,iframe,mcp,python,sdk,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+
+# 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 DX (developer experience), type safety, and MCP-compatible JSON output.
+
+---
+
+## 📦 Installation
+
+\`\`\`bash
+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
+
+\`\`\`python
+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:**
+
+\`\`\`json
+{
+  "type": "resource",
+  "resource": {
+    "uri": "ui://demo/html",
+    "mimeType": "text/html",
+    "text": "<h1>Hello MCP</h1>",
+    "blob": null,
+    "_meta": null
+  }
+}
+\`\`\`
+
+#### External URL (iframe)
+
+\`\`\`python
+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:**
+
+\`\`\`json
+{
+  "type": "resource",
+  "resource": {
+    "uri": "ui://demo/frame",
+    "mimeType": "text/uri-list",
+    "text": "https://example.com",
+    "blob": null,
+    "_meta": null
+  }
+}
+\`\`\`
+
+#### Remote DOM (React)
+
+\`\`\`python
+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):**
+
+\`\`\`json
+{
+  "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-\`.
+
+\`\`\`python
+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\`:**
+
+\`\`\`json
+{
+  "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
+
+\`\`\`python
+from mcp_ui import ui_action_result_tool_call
+action = ui_action_result_tool_call("searchTool", {"query": "MCP SDK"})
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "type": "tool",
+  "payload": {
+    "toolName": "searchTool",
+    "params": { "query": "MCP SDK" }
+  }
+}
+\`\`\`
+
+#### Prompt
+
+\`\`\`python
+from mcp_ui import ui_action_result_prompt
+action = ui_action_result_prompt("Please confirm your choice")
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "type": "prompt",
+  "payload": { "prompt": "Please confirm your choice" }
+}
+\`\`\`
+
+#### Link
+
+\`\`\`python
+from mcp_ui import ui_action_result_link
+action = ui_action_result_link("https://example.com")
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "type": "link",
+  "payload": { "url": "https://example.com" }
+}
+\`\`\`
+
+#### Intent
+
+\`\`\`python
+from mcp_ui import ui_action_result_intent
+action = ui_action_result_intent("share", {"platform": "twitter"})
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "type": "intent",
+  "payload": {
+    "intent": "share",
+    "params": { "platform": "twitter" }
+  }
+}
+\`\`\`
+
+#### Notification
+
+\`\`\`python
+from mcp_ui import ui_action_result_notification
+action = ui_action_result_notification("Saved successfully!")
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "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 – same as the original MCP-UI SDK.

mcp_ui-0.1.0/README.md

@@ -0,0 +1,282 @@
+
+# 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 DX (developer experience), type safety, and MCP-compatible JSON output.
+
+---
+
+## 📦 Installation
+
+\`\`\`bash
+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
+
+\`\`\`python
+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:**
+
+\`\`\`json
+{
+  "type": "resource",
+  "resource": {
+    "uri": "ui://demo/html",
+    "mimeType": "text/html",
+    "text": "<h1>Hello MCP</h1>",
+    "blob": null,
+    "_meta": null
+  }
+}
+\`\`\`
+
+#### External URL (iframe)
+
+\`\`\`python
+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:**
+
+\`\`\`json
+{
+  "type": "resource",
+  "resource": {
+    "uri": "ui://demo/frame",
+    "mimeType": "text/uri-list",
+    "text": "https://example.com",
+    "blob": null,
+    "_meta": null
+  }
+}
+\`\`\`
+
+#### Remote DOM (React)
+
+\`\`\`python
+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):**
+
+\`\`\`json
+{
+  "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-\`.
+
+\`\`\`python
+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\`:**
+
+\`\`\`json
+{
+  "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
+
+\`\`\`python
+from mcp_ui import ui_action_result_tool_call
+action = ui_action_result_tool_call("searchTool", {"query": "MCP SDK"})
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "type": "tool",
+  "payload": {
+    "toolName": "searchTool",
+    "params": { "query": "MCP SDK" }
+  }
+}
+\`\`\`
+
+#### Prompt
+
+\`\`\`python
+from mcp_ui import ui_action_result_prompt
+action = ui_action_result_prompt("Please confirm your choice")
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "type": "prompt",
+  "payload": { "prompt": "Please confirm your choice" }
+}
+\`\`\`
+
+#### Link
+
+\`\`\`python
+from mcp_ui import ui_action_result_link
+action = ui_action_result_link("https://example.com")
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "type": "link",
+  "payload": { "url": "https://example.com" }
+}
+\`\`\`
+
+#### Intent
+
+\`\`\`python
+from mcp_ui import ui_action_result_intent
+action = ui_action_result_intent("share", {"platform": "twitter"})
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "type": "intent",
+  "payload": {
+    "intent": "share",
+    "params": { "platform": "twitter" }
+  }
+}
+\`\`\`
+
+#### Notification
+
+\`\`\`python
+from mcp_ui import ui_action_result_notification
+action = ui_action_result_notification("Saved successfully!")
+\`\`\`
+
+**Output:**
+
+\`\`\`json
+{
+  "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 – same as the original MCP-UI SDK.

mcp_ui-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "mcp-ui"
+version = "0.1.0"
+description = "A Python SDK for building MCP UI resources (iframe, panels, text blocks, etc.) in a type-safe way."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "James Zokah", email = "jameszokah@gmail.com" }]
+requires-python = ">=3.9"
+keywords = ["mcp", "ui", "sdk", "python", "iframe", "chat", "agents"]
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[tool.uv]
+dev-dependencies = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/jameszokah/mcp-ui"
+Repository = "https://github.com/jameszokah/mcp-ui"
+Issues = "https://github.com/jameszokah/mcp-ui/issues"
+Documentation = "https://github.com/jameszokah/mcp-ui#readme"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# ✅ Tell Hatchling to include the package inside `src/mcp_ui`
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_ui"]
+
+
+[tool.pyright]
+include = ["src"]
+extraPaths = ["src"]

mcp_ui-0.1.0/src/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("mcp-ui")
+except PackageNotFoundError:
+    # fallback for local dev without install
+    __version__ = "0.0.0"
+
+from .core import * 

mcp_ui-0.1.0/src/core.py

@@ -0,0 +1,234 @@
+
+
+from __future__ import annotations
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, Literal, Optional, Union
+import base64
+
+# --------------------------
+# Types & Constants
+# --------------------------
+
+URI = str  # Must start with "ui://"
+
+MimeType = Literal[
+    "text/html",
+    "text/uri-list",
+    "application/vnd.mcp-ui.remote-dom+javascript; framework=react",
+    "application/vnd.mcp-ui.remote-dom+javascript; framework=webcomponents",
+]
+
+UIMetadataKey = {
+    "PREFERRED_FRAME_SIZE": "preferred-frame-size",
+    "INITIAL_RENDER_DATA": "initial-render-data",
+}
+
+UI_METADATA_PREFIX = "mcpui.dev/ui-"
+
+InternalMessageType = {
+    "UI_MESSAGE_RECEIVED": "ui-message-received",
+    "UI_MESSAGE_RESPONSE": "ui-message-response",
+    "UI_SIZE_CHANGE": "ui-size-change",
+    "UI_LIFECYCLE_IFRAME_READY": "ui-lifecycle-iframe-ready",
+    "UI_LIFECYCLE_IFRAME_RENDER_DATA": "ui-lifecycle-iframe-render-data",
+}
+
+ReservedUrlParams = {
+    "WAIT_FOR_RENDER_DATA": "waitForRenderData",
+}
+
+
+# --------------------------
+# Resource Content Payloads
+# --------------------------
+
+@dataclass
+class RawHtmlContent:
+    type: Literal["rawHtml"]
+    htmlString: str
+
+
+@dataclass
+class ExternalUrlContent:
+    type: Literal["externalUrl"]
+    iframeUrl: str
+
+
+@dataclass
+class RemoteDomContent:
+    type: Literal["remoteDom"]
+    script: str
+    framework: Literal["react", "webcomponents"]
+
+
+ResourceContentPayload = Union[RawHtmlContent, ExternalUrlContent, RemoteDomContent]
+
+
+# --------------------------
+# Resource Representations
+# --------------------------
+
+@dataclass
+class HTMLTextContent:
+    uri: URI
+    mimeType: MimeType
+    text: str
+    blob: Optional[str] = None
+    _meta: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Base64BlobContent:
+    uri: URI
+    mimeType: MimeType
+    blob: str
+    text: Optional[str] = None
+    _meta: Optional[Dict[str, Any]] = None
+
+
+UIResource = Dict[str, Union[str, HTMLTextContent, Base64BlobContent]]
+
+
+@dataclass
+class CreateUIResourceOptions:
+    uri: URI
+    content: ResourceContentPayload
+    encoding: Literal["text", "blob"]
+    uiMetadata: Optional[Dict[str, Any]] = None
+    metadata: Optional[Dict[str, Any]] = None
+    resourceProps: Optional[Dict[str, Any]] = None
+
+
+# --------------------------
+# Utils
+# --------------------------
+
+def utf8_to_base64(s: str) -> str:
+    return base64.b64encode(s.encode("utf-8")).decode("utf-8")
+
+
+def get_additional_resource_props(options: CreateUIResourceOptions) -> Dict[str, Any]:
+    props = dict(options.resourceProps or {})
+
+    if options.uiMetadata or options.metadata:
+        ui_prefixed_metadata = {
+            f"{UI_METADATA_PREFIX}{k}": v for k, v in (options.uiMetadata or {}).items()
+        }
+        props["_meta"] = {
+            **ui_prefixed_metadata,
+            **(options.metadata or {}),
+            **props.get("_meta", {}),
+        }
+
+    return props
+
+
+# --------------------------
+# Resource Factory
+# --------------------------
+
+def create_ui_resource(options: CreateUIResourceOptions) -> Dict[str, Any]:
+    if not options.uri.startswith("ui://"):
+        raise ValueError("MCP-UI SDK: URI must start with 'ui://'.")
+
+    if isinstance(options.content, RawHtmlContent):
+        actual_content = options.content.htmlString
+        mime_type: MimeType = "text/html"
+
+    elif isinstance(options.content, ExternalUrlContent):
+        actual_content = options.content.iframeUrl
+        mime_type = "text/uri-list"
+
+    elif isinstance(options.content, RemoteDomContent):
+        actual_content = options.content.script
+        mime_type = (
+            f"application/vnd.mcp-ui.remote-dom+javascript; framework={options.content.framework}"  # type: ignore
+        )
+
+    else:
+        raise ValueError(f"MCP-UI SDK: Invalid content.type: {options.content}")
+
+    if options.encoding == "text":
+        resource = HTMLTextContent(
+            uri=options.uri,
+            mimeType=mime_type,
+            text=actual_content,
+            **get_additional_resource_props(options),
+        )
+    elif options.encoding == "blob":
+        resource = Base64BlobContent(
+            uri=options.uri,
+            mimeType=mime_type,
+            blob=utf8_to_base64(actual_content),
+            **get_additional_resource_props(options),
+        )
+    else:
+        raise ValueError(f"MCP-UI SDK: Invalid encoding type: {options.encoding}")
+
+    # ✅ return a dict so MCP can consume it
+    return {
+        "type": "resource",
+        "resource": asdict(resource),
+    }
+
+# --------------------------
+# UI Action Results
+# --------------------------
+
+@dataclass
+class UIActionResultToolCall:
+    type: Literal["tool"] = "tool"
+    payload: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class UIActionResultPrompt:
+    type: Literal["prompt"] = "prompt"
+    payload: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class UIActionResultLink:
+    type: Literal["link"] = "link"
+    payload: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class UIActionResultIntent:
+    type: Literal["intent"] = "intent"
+    payload: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class UIActionResultNotification:
+    type: Literal["notify"] = "notify"
+    payload: Dict[str, str] = field(default_factory=dict)
+
+
+UIActionResult = Union[
+    UIActionResultToolCall,
+    UIActionResultPrompt,
+    UIActionResultLink,
+    UIActionResultIntent,
+    UIActionResultNotification,
+]
+
+
+def ui_action_result_tool_call(tool_name: str, params: Dict[str, Any]) -> UIActionResultToolCall:
+    return UIActionResultToolCall(payload={"toolName": tool_name, "params": params})
+
+
+def ui_action_result_prompt(prompt: str) -> UIActionResultPrompt:
+    return UIActionResultPrompt(payload={"prompt": prompt})
+
+
+def ui_action_result_link(url: str) -> UIActionResultLink:
+    return UIActionResultLink(payload={"url": url})
+
+
+def ui_action_result_intent(intent: str, params: Dict[str, Any]) -> UIActionResultIntent:
+    return UIActionResultIntent(payload={"intent": intent, "params": params})
+
+
+def ui_action_result_notification(message: str) -> UIActionResultNotification:
+    return UIActionResultNotification(payload={"message": message})

mcp_ui-0.1.0/src/mcp_ui.py

@@ -0,0 +1,234 @@
+
+
+from __future__ import annotations
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, Literal, Optional, Union
+import base64
+
+# --------------------------
+# Types & Constants
+# --------------------------
+
+URI = str  # Must start with "ui://"
+
+MimeType = Literal[
+    "text/html",
+    "text/uri-list",
+    "application/vnd.mcp-ui.remote-dom+javascript; framework=react",
+    "application/vnd.mcp-ui.remote-dom+javascript; framework=webcomponents",
+]
+
+UIMetadataKey = {
+    "PREFERRED_FRAME_SIZE": "preferred-frame-size",
+    "INITIAL_RENDER_DATA": "initial-render-data",
+}
+
+UI_METADATA_PREFIX = "mcpui.dev/ui-"
+
+InternalMessageType = {
+    "UI_MESSAGE_RECEIVED": "ui-message-received",
+    "UI_MESSAGE_RESPONSE": "ui-message-response",
+    "UI_SIZE_CHANGE": "ui-size-change",
+    "UI_LIFECYCLE_IFRAME_READY": "ui-lifecycle-iframe-ready",
+    "UI_LIFECYCLE_IFRAME_RENDER_DATA": "ui-lifecycle-iframe-render-data",
+}
+
+ReservedUrlParams = {
+    "WAIT_FOR_RENDER_DATA": "waitForRenderData",
+}
+
+
+# --------------------------
+# Resource Content Payloads
+# --------------------------
+
+@dataclass
+class RawHtmlContent:
+    type: Literal["rawHtml"]
+    htmlString: str
+
+
+@dataclass
+class ExternalUrlContent:
+    type: Literal["externalUrl"]
+    iframeUrl: str
+
+
+@dataclass
+class RemoteDomContent:
+    type: Literal["remoteDom"]
+    script: str
+    framework: Literal["react", "webcomponents"]
+
+
+ResourceContentPayload = Union[RawHtmlContent, ExternalUrlContent, RemoteDomContent]
+
+
+# --------------------------
+# Resource Representations
+# --------------------------
+
+@dataclass
+class HTMLTextContent:
+    uri: URI
+    mimeType: MimeType
+    text: str
+    blob: Optional[str] = None
+    _meta: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Base64BlobContent:
+    uri: URI
+    mimeType: MimeType
+    blob: str
+    text: Optional[str] = None
+    _meta: Optional[Dict[str, Any]] = None
+
+
+UIResource = Dict[str, Union[str, HTMLTextContent, Base64BlobContent]]
+
+
+@dataclass
+class CreateUIResourceOptions:
+    uri: URI
+    content: ResourceContentPayload
+    encoding: Literal["text", "blob"]
+    uiMetadata: Optional[Dict[str, Any]] = None
+    metadata: Optional[Dict[str, Any]] = None
+    resourceProps: Optional[Dict[str, Any]] = None
+
+
+# --------------------------
+# Utils
+# --------------------------
+
+def utf8_to_base64(s: str) -> str:
+    return base64.b64encode(s.encode("utf-8")).decode("utf-8")
+
+
+def get_additional_resource_props(options: CreateUIResourceOptions) -> Dict[str, Any]:
+    props = dict(options.resourceProps or {})
+
+    if options.uiMetadata or options.metadata:
+        ui_prefixed_metadata = {
+            f"{UI_METADATA_PREFIX}{k}": v for k, v in (options.uiMetadata or {}).items()
+        }
+        props["_meta"] = {
+            **ui_prefixed_metadata,
+            **(options.metadata or {}),
+            **props.get("_meta", {}),
+        }
+
+    return props
+
+
+# --------------------------
+# Resource Factory
+# --------------------------
+
+def create_ui_resource(options: CreateUIResourceOptions) -> Dict[str, Any]:
+    if not options.uri.startswith("ui://"):
+        raise ValueError("MCP-UI SDK: URI must start with 'ui://'.")
+
+    if isinstance(options.content, RawHtmlContent):
+        actual_content = options.content.htmlString
+        mime_type: MimeType = "text/html"
+
+    elif isinstance(options.content, ExternalUrlContent):
+        actual_content = options.content.iframeUrl
+        mime_type = "text/uri-list"
+
+    elif isinstance(options.content, RemoteDomContent):
+        actual_content = options.content.script
+        mime_type = (
+            f"application/vnd.mcp-ui.remote-dom+javascript; framework={options.content.framework}"  # type: ignore
+        )
+
+    else:
+        raise ValueError(f"MCP-UI SDK: Invalid content.type: {options.content}")
+
+    if options.encoding == "text":
+        resource = HTMLTextContent(
+            uri=options.uri,
+            mimeType=mime_type,
+            text=actual_content,
+            **get_additional_resource_props(options),
+        )
+    elif options.encoding == "blob":
+        resource = Base64BlobContent(
+            uri=options.uri,
+            mimeType=mime_type,
+            blob=utf8_to_base64(actual_content),
+            **get_additional_resource_props(options),
+        )
+    else:
+        raise ValueError(f"MCP-UI SDK: Invalid encoding type: {options.encoding}")
+
+    # ✅ return a dict so MCP can consume it
+    return {
+        "type": "resource",
+        "resource": asdict(resource),
+    }
+
+# --------------------------
+# UI Action Results
+# --------------------------
+
+@dataclass
+class UIActionResultToolCall:
+    type: Literal["tool"] = "tool"
+    payload: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class UIActionResultPrompt:
+    type: Literal["prompt"] = "prompt"
+    payload: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class UIActionResultLink:
+    type: Literal["link"] = "link"
+    payload: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class UIActionResultIntent:
+    type: Literal["intent"] = "intent"
+    payload: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class UIActionResultNotification:
+    type: Literal["notify"] = "notify"
+    payload: Dict[str, str] = field(default_factory=dict)
+
+
+UIActionResult = Union[
+    UIActionResultToolCall,
+    UIActionResultPrompt,
+    UIActionResultLink,
+    UIActionResultIntent,
+    UIActionResultNotification,
+]
+
+
+def ui_action_result_tool_call(tool_name: str, params: Dict[str, Any]) -> UIActionResultToolCall:
+    return UIActionResultToolCall(payload={"toolName": tool_name, "params": params})
+
+
+def ui_action_result_prompt(prompt: str) -> UIActionResultPrompt:
+    return UIActionResultPrompt(payload={"prompt": prompt})
+
+
+def ui_action_result_link(url: str) -> UIActionResultLink:
+    return UIActionResultLink(payload={"url": url})
+
+
+def ui_action_result_intent(intent: str, params: Dict[str, Any]) -> UIActionResultIntent:
+    return UIActionResultIntent(payload={"intent": intent, "params": params})
+
+
+def ui_action_result_notification(message: str) -> UIActionResultNotification:
+    return UIActionResultNotification(payload={"message": message})

mcp_ui-0.1.0/tests/test_ui.py

@@ -0,0 +1,72 @@
+
+import pytest
+
+from mcp_ui import (
+    create_ui_resource,
+    RawHtmlContent,
+    ExternalUrlContent,
+    RemoteDomContent,
+    ui_action_result_tool_call,
+    ui_action_result_prompt,
+    ui_action_result_link,
+    ui_action_result_intent,
+    ui_action_result_notification,
+    CreateUIResourceOptions,
+)
+
+
+def test_create_ui_resource_with_html():
+    options = CreateUIResourceOptions(
+        uri="ui://test-html",
+        content=RawHtmlContent(type="rawHtml", htmlString="<h1>Hello</h1>"),
+        encoding="text",
+    )
+    resource = create_ui_resource(options)
+
+    assert resource["type"] == "resource"
+    assert resource["resource"]["mimeType"] == "text/html"
+    assert resource["resource"]["text"] == "<h1>Hello</h1>"
+
+
+def test_create_ui_resource_with_external_url():
+    options = CreateUIResourceOptions(
+        uri="ui://test-url",
+        content=ExternalUrlContent(type="externalUrl", iframeUrl="https://example.com"),
+        encoding="text",
+    )
+    resource = create_ui_resource(options)
+
+    assert resource["resource"]["mimeType"] == "text/uri-list"
+    assert resource["resource"]["text"] == "https://example.com"
+
+
+def test_create_ui_resource_with_remote_dom_blob():
+    options = CreateUIResourceOptions(
+        uri="ui://test-remote",
+        content=RemoteDomContent(type="remoteDom", script="console.log('hi')", framework="react"),
+        encoding="blob",
+    )
+    resource = create_ui_resource(options)
+
+    assert resource["resource"]["mimeType"].startswith(
+        "application/vnd.mcp-ui.remote-dom+javascript; framework=react"
+    )
+    assert "blob" in resource["resource"]
+
+
+def test_ui_action_results():
+    tool_call = ui_action_result_tool_call("myTool", {"param": 1})
+    assert tool_call.payload["toolName"] == "myTool"
+
+    prompt = ui_action_result_prompt("Enter value")
+    assert prompt.payload["prompt"] == "Enter value"
+
+    link = ui_action_result_link("https://example.com")
+    assert link.payload["url"] == "https://example.com"
+
+    intent = ui_action_result_intent("open", {"id": 123})
+    assert intent.payload["intent"] == "open"
+    assert intent.payload["params"]["id"] == 123
+
+    notification = ui_action_result_notification("Done!")
+    assert notification.payload["message"] == "Done!"

mcp_ui-0.1.0/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 1
+requires-python = ">=3.8"
+
+[[package]]
+name = "mcp-ui"
+version = "0.1.0"
+source = { editable = "." }