{mcpResponse.content.map((item) => (
-
{
+ onUIAction={(result) => {
console.log('Action:', result);
return { status: 'handled' };
}}
@@ -99,6 +99,5 @@ function App({ mcpResponse }) {
## Philosophy
-Returning snippets of UI as responses from MCP servers is a powerful way to create interactive experiences. However, it can be difficult to get right.
-This is an ongoing discussion in the MCP community and the [UI Community Working Group](https://github.com/modelcontextprotocol-community/working-groups/issues/35).
-This project is an experimental playground for MCP-UI ideas, as explore ways to make it easier.
\ No newline at end of file
+Allowing MCP servers to respond with UI snippets is a powerful way to create interactive experiences in hosts. Nailing down the best way to do it is challenging, and is an ongoing discussion in the MCP community and the [UI Community Working Group](https://github.com/modelcontextprotocol-community/working-groups/issues/35).
+This project is an experimental playground for MCP-UI ideas, that aims to test out philosophies in the wild.
\ No newline at end of file
diff --git a/docs/src/guide/protocol-details.md b/docs/src/guide/protocol-details.md
index d97bbee4..7801935c 100644
--- a/docs/src/guide/protocol-details.md
+++ b/docs/src/guide/protocol-details.md
@@ -1,15 +1,15 @@
# Protocol Details
-This section dives deeper into the `HtmlResourceBlock` and its intended usage.
+This section dives deeper into the `UIResource` and its intended usage.
-## `HtmlResourceBlock` Recap
+## `UIResource` Recap
```typescript
-export interface HtmlResourceBlock {
+export interface UIResource {
type: 'resource';
resource: {
uri: string;
- mimeType: 'text/html' | 'text/uri-list';
+ mimeType: 'text/html' | 'text/uri-list' | 'application/vnd.mcp-ui.remote-dom';
text?: string;
blob?: string;
};
@@ -70,7 +70,7 @@ if (
mcpResource.type === 'resource' &&
mcpResource.resource.uri?.startsWith('ui://')
) {
- return ;
+ return ;
}
// ❌ Not recommended: Check mimeType first
@@ -78,14 +78,14 @@ if (
mcpResource.type === 'resource' &&
(mcpResource.resource.mimeType === 'text/html' || mcpResource.resource.mimeType === 'text/uri-list')
) {
- return ;
+ return ;
}
```
**Benefits of URI-first checking:**
- Future-proof: Works with new content types like `application/javascript`
- Semantic clarity: `ui://` clearly indicates this is a UI resource
-- Simpler logic: Let the `ResourceRenderer` component handle mimeType-based rendering internally
+- Simpler logic: Let the `UIResourceRenderer` component handle mimeType-based rendering internally
## Communication (Client <-> Iframe)
@@ -114,7 +114,7 @@ For `ui://` resources, you can use `window.parent.postMessage` to send data or a
window.addEventListener('message', (event) => {
// Add origin check for security: if (event.origin !== "expectedOrigin") return;
if (event.data && event.data.tool) {
- // Call the onUiAction prop of ResourceRenderer
+ // Call the onUIAction prop of UIResourceRenderer
}
});
```
diff --git a/docs/src/guide/server/overview.md b/docs/src/guide/server/overview.md
index 26eff76c..8bf77e24 100644
--- a/docs/src/guide/server/overview.md
+++ b/docs/src/guide/server/overview.md
@@ -1,15 +1,15 @@
# @mcp-ui/server Overview
-The `@mcp-ui/server` package provides server-side utilities to help construct `HtmlResource` objects, which can then be sent to a client as part of an MCP response.
+The `@mcp-ui/server` package provides server-side utilities to help construct `UIResource` objects, which can then be sent to a client as part of an MCP response.
## Key Exports
-- **`createHtmlResource(options: CreateHtmlResourceOptions): HtmlResource`**:
- The primary function for creating resource blocks. It takes an options object to define the URI, content (direct HTML or external URL), and delivery method (text or blob).
+- **`createUIResource(options: CreateUIResourceOptions): UIResource`**:
+ The primary function for creating UI snippets. It takes an options object to define the URI, content (direct HTML or external URL), and delivery method (text or blob).
## Purpose
-- **Ease of Use**: Simplifies the creation of valid `HtmlResource` objects.
+- **Ease of Use**: Simplifies the creation of valid `UIResource` objects.
- **Validation**: Includes basic validation (e.g., URI prefixes matching content type).
- **Encoding**: Handles Base64 encoding when `delivery: 'blob'` is specified.
diff --git a/docs/src/guide/server/usage-examples.md b/docs/src/guide/server/usage-examples.md
index 9ccb05fb..1387c2e8 100644
--- a/docs/src/guide/server/usage-examples.md
+++ b/docs/src/guide/server/usage-examples.md
@@ -12,18 +12,18 @@ npm i @mcp-ui/server
## Basic Usage
-The core function is `createHtmlResource`.
+The core function is `createUIResource`.
```typescript
import {
- createHtmlResource,
+ createUIResource,
} from '@mcp-ui/server';
// Using a shared enum value (just for demonstration)
console.log('Shared Enum from server usage:', PlaceholderEnum.FOO);
// Example 1: Direct HTML, delivered as text
-const resource1 = createHtmlResource({
+const resource1 = createUIResource({
uri: 'ui://my-component/instance-1',
content: { type: 'rawHtml', htmlString: 'Hello World
' },
delivery: 'text',
@@ -41,7 +41,7 @@ console.log('Resource 1:', JSON.stringify(resource1, null, 2));
*/
// Example 2: Direct HTML, delivered as a Base64 blob
-const resource2 = createHtmlResource({
+const resource2 = createUIResource({
uri: 'ui://my-component/instance-2',
content: { type: 'rawHtml', htmlString: 'Complex HTML
' },
delivery: 'blob',
@@ -63,7 +63,7 @@ console.log(
// Example 3: External URL, text delivery
const dashboardUrl = 'https://my.analytics.com/dashboard/123';
-const resource3 = createHtmlResource({
+const resource3 = createUIResource({
uri: 'ui://analytics-dashboard/main',
content: { type: 'externalUrl', iframeUrl: dashboardUrl },
delivery: 'text',
@@ -82,7 +82,7 @@ console.log('Resource 3:', JSON.stringify(resource3, null, 2));
// Example 4: External URL, blob delivery (URL is Base64 encoded)
const chartApiUrl = 'https://charts.example.com/api?type=pie&data=1,2,3';
-const resource4 = createHtmlResource({
+const resource4 = createUIResource({
uri: 'ui://live-chart/session-xyz',
content: { type: 'externalUrl', iframeUrl: chartApiUrl },
delivery: 'blob',
@@ -120,7 +120,7 @@ https://backup.dashboard.example.com/main
# Emergency fallback (will be logged but not used)
https://emergency.dashboard.example.com/main`;
-const resource5 = createHtmlResource({
+const resource5 = createUIResource({
uri: 'ui://dashboard-with-fallbacks/session-123',
content: { type: 'externalUrl', iframeUrl: multiUrlContent },
delivery: 'text',
@@ -135,14 +135,14 @@ const resource5 = createHtmlResource({
## Error Handling
-The `createHtmlResource` function will throw errors if invalid combinations are provided, for example:
+The `createUIResource` function will throw errors if invalid combinations are provided, for example:
- URI not starting with `ui://` for any content type
- Invalid content type specified
```typescript
try {
- createHtmlResource({
+ createUIResource({
uri: 'invalid://should-be-ui',
content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
delivery: 'text',
diff --git a/docs/src/guide/shared/overview.md b/docs/src/guide/shared/overview.md
deleted file mode 100644
index f6796c48..00000000
--- a/docs/src/guide/shared/overview.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# @mcp-ui/shared Overview\n\nThe `@mcp-ui/shared` package is the foundation of the MCP-UI SDK, providing common types, enums, and utility functions used by both the server and client packages.\n\n## Key Exports\n\n- **`HtmlResourceBlock` (Interface)**: The core data structure for defining interactive HTML resources. (See [Protocol Details](../protocol-details.md) for more information).\n- **`ResourceContentPayload` (Type)**: Defines the structure for `content` within `CreateHtmlResourceOptions`, discriminating between direct HTML and external URLs.\n- **`CreateHtmlResourceOptions` (Interface)**: Options for the `createHtmlResource` function in `@mcp-ui/server`.\n- **`PlaceholderEnum` (Enum)**: An example enum: `export enum PlaceholderEnum { FOO = \'FOO\', BAR = \'BAR\' }`.\n- **`greet` (Function)**: An example utility function: `export const greet = (name: string): string => \`Hello, ${name}!\`;`\n\n## Purpose\n\n- **Consistency**: Ensures that client and server components operate on the same data structures.\n- **Reusability**: Offers common utilities that can be used across different parts of an MCP application.\n- **Type Safety**: Provides TypeScript definitions for better development experience.\n\n## Building\n\nThis package is built using Vite in library mode. It outputs ESM (`.mjs`) and UMD (`.js`) formats, along with TypeScript declaration files (`.d.ts`).\n\nTo build specifically this package from the monorepo root:\n```bash
-
-pnpm build --filter @mcp-ui/shared
-
-```
-
-```
diff --git a/docs/src/index.md b/docs/src/index.md
index 1fce8aec..b3c7cb6b 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -4,7 +4,7 @@ layout: home
hero:
name: MCP-UI
text: Interactive UI Components for MCP
- tagline: Build rich, dynamic user interfaces for your MCP applications with TypeScript SDKs that bring UI snippets to AI interactions.
+ tagline: Build rich, dynamic user interfaces for your MCP applications with TypeScript SDKs that bring UI to AI interactions.
image:
light: /logo-lg-black.png
dark: /logo-lg.png
@@ -22,9 +22,9 @@ hero:
features:
- title: ⚛️ Client SDK
- details: React components and hooks for seamless frontend integration. Render interactive UI resources with the ResourceRenderer component and handle UI actions effortlessly.
+ details: React components and hooks for seamless frontend integration. Render interactive UI resources with the UIResourceRenderer component and handle UI actions effortlessly.
- title: 🛠️ Server SDK
- details: Powerful utilities to construct interactive resource blocks for MCP servers. Create HTML, React, Web Components, and external app UI with ergonomic API.
+ details: Powerful utilities to construct interactive UI for MCP servers. Create HTML, React, Web Components, and external app UI with ergonomic API.
- title: 🔒 Secure
details: All remote code executes in sandboxed iframes, ensuring host and user security while maintaining rich interactivity.
- title: 🎨 Flexible
@@ -48,9 +48,9 @@ features:
**Server Side** - Create interactive resources to return in your MCP tool results:
```typescript
-import { createHtmlResource } from '@mcp-ui/server';
+import { createUIResource } from '@mcp-ui/server';
-const interactiveForm = createHtmlResource({
+const interactiveForm = createUIResource({
uri: 'ui://user-form/1',
content: {
type: 'externalUrl',
@@ -63,13 +63,13 @@ const interactiveForm = createHtmlResource({
**Client Side** - Render with one component:
```tsx
-import { ResourceRenderer } from '@mcp-ui/client';
+import { UIResourceRenderer } from '@mcp-ui/client';
function MyApp({ mcpResource }) {
return (
- {
+ onUIAction={(action) => {
console.log('User action:', action);
return { status: 'ok' };
}}
diff --git a/examples/remote-dom-demo/README.md b/examples/remote-dom-demo/README.md
index 42559f7b..b47c35f6 100644
--- a/examples/remote-dom-demo/README.md
+++ b/examples/remote-dom-demo/README.md
@@ -9,9 +9,9 @@ https://github.com/user-attachments/assets/cace78be-7ac5-47bc-bb41-d722e3e28304
The demo is split into two main concepts:
-1. **UI Script (The "Server" or "Remote" side):** This is a piece of JavaScript that declaratively defines the UI structure and behavior using a set of standard elements (e.g., ``, ``). In a real-world scenario, this script would be generated and served by an MCP server inside an EmbeddedResource (through the `mcp-ui` server SDK). In this demo, you can directly edit this script in the text area at the bottom of the page.
+1. **UI Script (The "Server"/"Remote" side):** This is a piece of JavaScript that declaratively defines the UI structure and behavior using a set of standard elements (e.g., ``, ``). In a real-world scenario, this script would be generated and served by an MCP server inside an EmbeddedResource (through the `mcp-ui` server SDK). In this demo, you can directly edit this script in the text area at the bottom of the page.
-2. **Component Library (The "Host" or "Client" side):** This is a set of UI components (e.g., React components, Web Components) that know how to render the elements defined in the UI script. The host application receives the UI script and uses its component library to render the actual UI to the user. This demo showcases three different component libraries running in parallel.
+2. **Component Library (The "Host"/"Client" side):** This is a set of UI components (e.g., React components, Web Components) that know how to render the elements defined in the UI script. The host application receives the UI script and uses its component library to render the actual UI to the user. This demo showcases three different component libraries running in parallel.
## How to Use the Demo
@@ -38,7 +38,7 @@ If you are building a host application that needs to render remote UI, you can u
* `radix.tsx`: A library that maps remote elements to styled React components from Radix UI.
* `webcomponents.ts`: A library that defines and registers standard custom elements.
2. **Create your library:** Create a new file in `src/libraries` for your own component library. You will need to provide mappings from the remote element definitions (e.g., `remoteButtonDefinition`) to your actual components.
-3. **Integrate your library:** In `src/App.tsx`, import your new library and add a new `` instance inside the grid. Pass your component library to the `library` prop.
+3. **Integrate your library:** In `src/App.tsx`, import your new library and add a new `` instance inside the grid. Pass your component library to the `library` prop.
4. **Test:** Run the demo and use the script editor to test how your component library handles various UI scenarios.
## Running the Demo Locally
diff --git a/examples/remote-dom-demo/src/App.tsx b/examples/remote-dom-demo/src/App.tsx
index 3825860f..a0ec05e1 100644
--- a/examples/remote-dom-demo/src/App.tsx
+++ b/examples/remote-dom-demo/src/App.tsx
@@ -1,5 +1,5 @@
import {
- ResourceRenderer,
+ UIResourceRenderer,
basicComponentLibrary,
remoteTextDefinition,
remoteButtonDefinition,
@@ -18,7 +18,7 @@ const remoteElements = [
remoteImageDefinition,
];
-const defaultRemoteDomScript = `let isDarkMode = false;
+const defaultRemoteDOMScript = `let isDarkMode = false;
// Create the main container stack with centered alignment
const stack = document.createElement('ui-stack');
@@ -74,8 +74,8 @@ root.appendChild(stack);
`;
function App() {
- const [scriptContent, setScriptContent] = useState(defaultRemoteDomScript);
- const [inputValue, setInputValue] = useState(defaultRemoteDomScript);
+ const [scriptContent, setScriptContent] = useState(defaultRemoteDOMScript);
+ const [inputValue, setInputValue] = useState(defaultRemoteDOMScript);
const [isPending, startTransition] = useTransition();
useEffect(() => {
@@ -143,7 +143,7 @@ function App() {
>
Basic React Components
-
Radix React Components
-
Web Components
-
-
-
-
-
-
- What's mcp-ui? •
- Installation •
- Quickstart •
- Examples •
- Roadmap •
- Contributing •
- License
-
-
-----
-
-**`mcp-ui`** brings interactive web components to the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP). Deliver rich, dynamic UI resources directly from your MCP server to be rendered by the client. Take AI interaction to the next level!
-
-> *This project is an experimental community playground for MCP UI ideas. Expect rapid iteration and enhancements!*
-
-
-
-## 💡 What's `mcp-ui`?
-
-`mcp-ui` is a TypeScript SDK comprising two packages:
-
-* **`@mcp-ui/server`**: Utilities to generate UI resource objects (`HtmlResourceBlock`) on your MCP server.
-* **`@mcp-ui/client`**: UI components (e.g., ``) to render those blocks in the browser and handle their events.
-
-Together, they let you define reusable UI resource blocks on the server side, seamlessly display them in the client, and react to their actions in the MCP host environment.
-
-**North star** -
-* Enable servers to deliver rich, interactive UIs with ergonomic APIs
-* Allow any host to support UI with its own look-and-feel
-* Eliminate security concerns (limit/remove local code execution)
-
-
-## ✨ Core Concepts
-
-The primary component for rendering MCP resources is ``. It automatically detects the resource type and renders the appropriate component.
-
-### Supported Resource Types
-
-#### HTML (`text/html` and `text/uri-list`)
-
-Rendered using the `` component, which displays content inside an `