mcp-ui 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

mcp_ui/__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/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.dist-info → mcp_ui-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-ui
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -14,7 +14,6 @@ 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
@@ -22,29 +21,30 @@ 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.
+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
 
-\`\`\`bash
+```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).
 
 ---
@@ -55,7 +55,7 @@ A **UI action result** represents an action the MCP client should take (e.g., op
 
 #### Raw HTML
 
-\`\`\`python
+```python
 from mcp_ui import RawHtmlContent, CreateUIResourceOptions, create_ui_resource
 
 options = CreateUIResourceOptions(
@@ -66,11 +66,11 @@ options = CreateUIResourceOptions(
 
 resource = create_ui_resource(options)
 print(resource)
-\`\`\`
+```
 
 **Output:**
 
-\`\`\`json
+```json
 {
   "type": "resource",
   "resource": {
@@ -81,11 +81,11 @@ print(resource)
     "_meta": null
   }
 }
-\`\`\`
+```
 
 #### External URL (iframe)
 
-\`\`\`python
+```python
 from mcp_ui import ExternalUrlContent, CreateUIResourceOptions, create_ui_resource
 
 options = CreateUIResourceOptions(
@@ -95,11 +95,11 @@ options = CreateUIResourceOptions(
 )
 
 iframe_res = create_ui_resource(options)
-\`\`\`
+```
 
 **Output:**
 
-\`\`\`json
+```json
 {
   "type": "resource",
   "resource": {
@@ -110,11 +110,11 @@ iframe_res = create_ui_resource(options)
     "_meta": null
   }
 }
-\`\`\`
+```
 
 #### Remote DOM (React)
 
-\`\`\`python
+```python
 from mcp_ui import RemoteDomContent, CreateUIResourceOptions, create_ui_resource
 
 options = CreateUIResourceOptions(
@@ -124,11 +124,11 @@ options = CreateUIResourceOptions(
 )
 
 remote_res = create_ui_resource(options)
-\`\`\`
+```
 
 **Output (blob is Base64-encoded):**
 
-\`\`\`json
+```json
 {
   "type": "resource",
   "resource": {
@@ -139,7 +139,7 @@ remote_res = create_ui_resource(options)
     "_meta": null
   }
 }
-\`\`\`
+```
 
 ---
 
@@ -147,7 +147,7 @@ remote_res = create_ui_resource(options)
 
 You can attach metadata to resources. Keys are automatically prefixed with \`mcpui.dev/ui-\`.
 
-\`\`\`python
+```python
 options = CreateUIResourceOptions(
     uri="ui://demo/meta",
     content=RawHtmlContent(type="rawHtml", htmlString="<p>Meta Example</p>"),
@@ -156,11 +156,11 @@ options = CreateUIResourceOptions(
 )
 
 meta_res = create_ui_resource(options)
-\`\`\`
+```
 
-**Output includes \`_meta\`:**
+**Output includes \`\_meta\`:**
 
-\`\`\`json
+```json
 {
   "type": "resource",
   "resource": {
@@ -173,7 +173,7 @@ meta_res = create_ui_resource(options)
     }
   }
 }
-\`\`\`
+```
 
 ---
 
@@ -181,14 +181,14 @@ meta_res = create_ui_resource(options)
 
 #### Tool Call
 
-\`\`\`python
+```python
 from mcp_ui import ui_action_result_tool_call
 action = ui_action_result_tool_call("searchTool", {"query": "MCP SDK"})
-\`\`\`
+```
 
 **Output:**
 
-\`\`\`json
+```json
 {
   "type": "tool",
   "payload": {
@@ -196,50 +196,50 @@ action = ui_action_result_tool_call("searchTool", {"query": "MCP SDK"})
     "params": { "query": "MCP SDK" }
   }
 }
-\`\`\`
+```
 
 #### Prompt
 
-\`\`\`python
+```python
 from mcp_ui import ui_action_result_prompt
 action = ui_action_result_prompt("Please confirm your choice")
-\`\`\`
+```
 
 **Output:**
 
-\`\`\`json
+```json
 {
   "type": "prompt",
   "payload": { "prompt": "Please confirm your choice" }
 }
-\`\`\`
+```
 
 #### Link
 
-\`\`\`python
+```python
 from mcp_ui import ui_action_result_link
 action = ui_action_result_link("https://example.com")
-\`\`\`
+```
 
 **Output:**
 
-\`\`\`json
+```json
 {
   "type": "link",
   "payload": { "url": "https://example.com" }
 }
-\`\`\`
+```
 
 #### Intent
 
-\`\`\`python
+```python
 from mcp_ui import ui_action_result_intent
 action = ui_action_result_intent("share", {"platform": "twitter"})
-\`\`\`
+```
 
 **Output:**
 
-\`\`\`json
+```json
 {
   "type": "intent",
   "payload": {
@@ -247,40 +247,43 @@ action = ui_action_result_intent("share", {"platform": "twitter"})
     "params": { "platform": "twitter" }
   }
 }
-\`\`\`
+```
 
 #### Notification
 
-\`\`\`python
+```python
 from mcp_ui import ui_action_result_notification
 action = ui_action_result_notification("Saved successfully!")
-\`\`\`
+```
 
 **Output:**
 
-\`\`\`json
+```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
+
+- `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)
@@ -296,11 +299,11 @@ Creates a UI resource for MCP. Returns a JSON-serializable dict.
 ## ⚙️ Notes
 
 - Internally uses dataclasses for type safety, but always returns dicts (via \`asdict()\`) for MCP compatibility.
-- Enforces URI format (\`ui://\` prefix).
+- Enforces URI format (`ui://` prefix).
 - Auto-encodes blob resources in Base64.
 
 ---
 
 ## 📄 License
 
-MIT – same as the original MCP-UI SDK.
+MIT – Similar to the original MCP-UI Typescript server SDK.

mcp_ui-0.1.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+mcp_ui/__init__.py,sha256=j0sF9vVV2kw0NUoeLImJIcJQjjuVrgpcKJ5Al70tUgQ,225
+mcp_ui/core.py,sha256=zU3sVHe05TmnHVdswUdoOFGS9f4hHvyhYA9cLD1OJZw,6192
+mcp_ui-0.1.2.dist-info/METADATA,sha256=SSdgIy-bymElwWXkW0cpSx4w9kLffJncXVwGpJqnuk0,6533
+mcp_ui-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_ui-0.1.2.dist-info/licenses/LICENSE,sha256=pAZXnNE2dxxwXFIduGyn1gpvPefJtUYOYZOi3yeGG94,1068
+mcp_ui-0.1.2.dist-info/RECORD,,

mcp_ui-0.1.0.dist-info/RECORD

@@ -1,4 +0,0 @@
-mcp_ui-0.1.0.dist-info/METADATA,sha256=AdeUTQHlblMMQdW8JJ7CzsbVY0a0PbPQCV7G01UN0mc,6724
-mcp_ui-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mcp_ui-0.1.0.dist-info/licenses/LICENSE,sha256=pAZXnNE2dxxwXFIduGyn1gpvPefJtUYOYZOi3yeGG94,1068
-mcp_ui-0.1.0.dist-info/RECORD,,