npm package: @fuselabcreative/ui9000-client
Description: UI 9000 Client SDK - A powerful client library for Model Context Protocol with React components and web components
Author: FuseLab Creative
Latest version: 1.0.5

## 📦 Model Context Protocol UI SDK

<p align="center">
  <img width="250" alt="image" src="https://github.com/user-attachments/assets/65b9698f-990f-4846-9b2d-88de91d53d4d" />
</p>

<p align="center">
  <a href="#-whats-ui9000-client">What's ui9000-client?</a> •
  <a href="#-core-concepts">Core Concepts</a> •
  <a href="#-installation">Installation</a> •
  <a href="#-getting-started">Getting Started</a> •
  <a href="#-walkthrough">Walkthrough</a> •
  <a href="#-examples">Examples</a> •
  <a href="#-security">Security</a> •
  <a href="#-roadmap">Roadmap</a> •
  <a href="#-contributing">Contributing</a> •
  <a href="#-license">License</a>
  <a href="#-deploy">Deploy</a>
</p>

----

**`ui9000-client`** 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!*

<p align="center">
  <video src="https://github.com/user-attachments/assets/7180c822-2dd9-4f38-9d3e-b67679509483"></video>
</p>

## 💡 What's `ui9000-client`?

`ui9000-client` is a collection of SDKs comprising:

* **`@fuselabcreative/ui9000-client` (TypeScript)**: UI components (e.g., `<UIResourceRenderer />`) to render the UI resources and handle their events.

Together, they let you define reusable UI snippets on the server side, seamlessly and securely render them in the client, and react to their actions in the MCP host environment.

## ✨ Core Concepts

In essence, by using `ui9000-client` SDKs can agree on contracts that enable them to create and render interactive UI snippets (as a path to a standardized UI approach in MCP).

### UI Resource
The primary payload returned from the server to the client is the `UIResource`:

```ts
interface UIResource {
  type: 'resource';
  resource: {
    uri: string;       // e.g., ui://component/id
    mimeType: 'text/html' | 'text/uri-list' | 'application/vnd.ui9000-client.remote-dom'; // text/html for HTML content, text/uri-list for URL content, application/vnd.ui9000-client.remote-dom for remote-dom content (Javascript)
    text?: string;      // Inline HTML, external URL, or remote-dom script
    blob?: string;      // Base64-encoded HTML, URL, or remote-dom script
  };
}
```

* **`uri`**: Unique identifier for caching and routing
  * `ui://…` — UI resources (rendering method determined by mimeType)
* **`mimeType`**: `text/html` for HTML content (iframe srcDoc), `text/uri-list` for URL content (iframe src), `application/vnd.ui9000-client.remote-dom` for remote-dom content (Javascript)
  * **ui9000-client requires a single URL**: While `text/uri-list` format supports multiple URLs, ui9000-client uses only the first valid `http/s` URL and warns if additional URLs are found
* **`text` vs. `blob`**: Choose `text` for simple strings; use `blob` for larger or encoded content.

### Resource Renderer

The UI Resource is rendered in the `<UIResourceRenderer />` component. It automatically detects the resource type and renders the appropriate component.

It is available as a React component and as a Web Component.

**React Component**

It accepts the following props:
- **`resource`**: The resource object from an MCP Tool response. It must include `uri`, `mimeType`, and content (`text`, `blob`)
- **`onUIAction`**: Optional callback for handling UI actions from the resource:
  ```typescript
  { type: 'tool', payload: { toolName: string, params: Record<string, unknown> }, messageId?: string } |
  { type: 'intent', payload: { intent: string, params: Record<string, unknown> }, messageId?: string } |
  { type: 'prompt', payload: { prompt: string }, messageId?: string } |
  { type: 'notify', payload: { message: string }, messageId?: string } |
  { type: 'link', payload: { url: string }, messageId?: string }
  ```
  When actions include a `messageId`, the iframe automatically receives response messages for asynchronous handling.
- **`supportedContentTypes`**: Optional array to restrict which content types are allowed (`['rawHtml', 'externalUrl', 'remoteDom']`)
- **`htmlProps`**: Optional props for the internal `<HTMLResourceRenderer>`
  - **`style`**: Optional custom styles for the iframe
  - **`iframeProps`**: Optional props passed to the iframe element
- **`remoteDomProps`**: Optional props for the internal `<RemoteDOMResourceRenderer>`
  - **`library`**: Optional component library for Remote DOM resources (defaults to `basicComponentLibrary`)
  - **`remoteElements`**: remote element definitions for Remote DOM resources.

**Web Component**

The Web Component is available as `<ui-resource-renderer>`. It accepts the same props as the React component, but they must be passed as strings.

Example:
```html
<ui-resource-renderer
  resource='{ "mimeType": "text/html", "text": "<h2>Hello from the Web Component!</h2>" }'
></ui-resource-renderer>
```

The `onUIAction` prop can be handled by attaching an event listener to the component:
```javascript
const renderer = document.querySelector('ui-resource-renderer');
renderer.addEventListener('onUIAction', (event) => {
  console.log('Action:', event.detail);
});
```

The Web Component is available in the `@fuselabcreative/ui9000-client` package at `dist/ui-resource-renderer.wc.js`.

### Supported Resource Types

#### HTML (`text/html` and `text/uri-list`)

Rendered using the internal `<HTMLResourceRenderer />` component, which displays content inside an `<iframe>`. This is suitable for self-contained HTML or embedding external apps.

*   **`mimeType`**:
    *   `text/html`: Renders inline HTML content.
    *   `text/uri-list`: Renders an external URL. ui9000-client uses the first valid `http/s` URL.

#### Remote DOM (`application/vnd.ui9000-client.remote-dom`)

Rendered using the internal `<RemoteDOMResourceRenderer />` component, which utilizes Shopify's [`remote-dom`](https://github.com/Shopify/remote-dom). The server responds with a script that describes the UI and events. On the host, the script is securely rendered in a sandboxed iframe, and the UI changes are communicated to the host in JSON, where they're rendered using the host's component library. This is more flexible than iframes and allows for UIs that match the host's look-and-feel.

* **`mimeType`**: `application/vnd.ui9000-client.remote-dom+javascript; framework={react | webcomponents}`

### UI Action

UI snippets must be able to interact with the agent. In `ui9000-client`, this is done by hooking into events sent from the UI snippet and reacting to them in the host (see `onUIAction` prop). For example, an HTML may trigger a tool call when a button is clicked by sending an event which will be caught handled by the client.

## 🏗️ Installation

### TypeScript

```bash
# using npm
npm i @fuselabcreative/ui9000-client

# or pnpm
pnpm add @fuselabcreative/ui9000-client

# or yarn
yarn add @fuselabcreative/ui9000-client
```

### TypeScript


1. **Client-side**: Render in your MCP host

   ```tsx
   import React from 'react';
   import { UIResourceRenderer } from '@fuselabcreative/ui9000-client';

   function App({ mcpResource }) {
     if (
       mcpResource.type === 'resource' &&
       mcpResource.resource.uri?.startsWith('ui://')
     ) {
       return (
         <UIResourceRenderer
           resource={mcpResource.resource}
           onUIAction={(result) => {
             console.log('Action:', result);
           }}
         />
       );
     }
     return <p>Unsupported resource</p>;
   }
   ```

## 🔒 Security
Host and user security is one of `ui9000-client`'s primary concerns. In all content types, the remote code is executed in a sandboxed iframe.


## 🛣️ Roadmap

- [X] Add online playground
- [X] Expand UI Action API (beyond tool calls)
- [X] Support Web Components
- [X] Support Remote-DOM
- [ ] Add component libraries (in progress)
- [ ] Add SDKs for additional programming languages (in progress; Ruby available)
- [ ] Support additional frontend frameworks
- [ ] Add declarative UI content type
- [ ] Support generative UI?

## 📄 License

Apache License 2.0 © [The ui9000-client Authors](LICENSE)

## Disclaimer

This project is provided "as is", without warranty of any kind. The `ui9000-client` authors and contributors shall not be held liable for any damages, losses, or issues arising from the use of this software. Use at your own risk.

## Deploy

To deploy the package to npm:

1. **Ensure you are authenticated with npm**  
   If you haven't already, log in to npm with:
   ```sh
   npm login
   ```
   or, if using pnpm:
   ```sh
   pnpm login
   ```

2. **Build the package and publish to npm**  
   Run the build script to generate the production-ready files:
   ```sh
   npm run publish:lib
   ```
   or, if using pnpm:
   ```sh
   pnpm publish:lib
   ```

**Notes:**
- The package is configured to be public (`"publishConfig": { "access": "public" }`).
- Only the files listed in the `files` array (`dist`, `README.md`, `LICENSE`) will be published.
- Make sure you have the necessary permissions to publish to the `@fuselabcreative` scope.

For more details, see the [npm publishing docs](https://docs.npmjs.com/cli/v9/commands/npm-publish).