mcp-ui 0.1.0__py3-none-any.whl

mcp_ui-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,4 @@
+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,,

mcp_ui-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_ui-0.1.0.dist-info/licenses/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.