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.
