MCP-UI-Org · idosal · Jul 4, 2025 · Jul 4, 2025 · Jul 4, 2025 · Jul 4, 2025
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -1,6 +1,6 @@
-# Contributing to MCP UI
+# Contributing to MCP-UI
 
-First of all, thank you for your interest in contributing to MCP UI! We appreciate the time and effort you're willing to invest in improving the project. This document provides guidelines and information to make the contribution process as smooth as possible.
+First of all, thank you for your interest in contributing to MCP-UI! We appreciate the time and effort you're willing to invest in improving the project. This document provides guidelines and information to make the contribution process as smooth as possible.
 
 ## Table of Contents
 
@@ -32,7 +32,7 @@ First of all, thank you for your interest in contributing to MCP UI! We apprecia
 
 ### Prerequisites
 
-Before you start working on MCP UI, make sure you have the following installed:
+Before you start working on MCP-UI, make sure you have the following installed:
 
 - [Node.js](https://nodejs.org/) (version 18 or higher recommended)
 - [pnpm](https://pnpm.io/) (version 8.15.7 or higher)
@@ -81,11 +81,11 @@ To run tests:
 pnpm test
 ```
 
-MCP UI uses Vitest as the testing framework. When adding new features, please include appropriate tests.
+MCP-UI uses Vitest as the testing framework. When adding new features, please include appropriate tests.
 
 ### Code Formatting
 
-MCP UI uses Prettier for code formatting and lint-staged to ensure code is properly formatted before committing. Pre-commit hooks are set up with Husky to run these checks automatically.
+MCP-UI uses Prettier for code formatting and lint-staged to ensure code is properly formatted before committing. Pre-commit hooks are set up with Husky to run these checks automatically.
 
 To manually format your code:
 
@@ -116,7 +116,7 @@ pnpm prettier --write .
 
 ### Reporting Bugs
 
-If you encounter a bug or issue while using MCP UI, please open a new issue on the [GitHub Issues](https://github.com/idosal/mcp-ui/issues) page. Provide a clear and concise description of the problem, steps to reproduce it, and any relevant error messages or logs.
+If you encounter a bug or issue while using MCP-UI, please open a new issue on the [GitHub Issues](https://github.com/idosal/mcp-ui/issues) page. Provide a clear and concise description of the problem, steps to reproduce it, and any relevant error messages or logs.
 
 ### Suggesting Enhancements
 
@@ -135,7 +135,7 @@ We welcome ideas for improvements and new features. To suggest an enhancement, o
 
 ### Code Style
 
-MCP UI uses [ESLint](https://eslint.org/) as its code style guide. Please ensure that your code follows these guidelines.
+MCP-UI uses [ESLint](https://eslint.org/) as its code style guide. Please ensure that your code follows these guidelines.
 
 ### Commit Messages
 

diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 ## 📦 Model Context Protocol UI SDK
 
 <p align="center">
-  <img width="300" alt="image" src="https://github.com/user-attachments/assets/65b9698f-990f-4846-9b2d-88de91d53d4d" />
+  <img width="250" alt="image" src="https://github.com/user-attachments/assets/65b9698f-990f-4846-9b2d-88de91d53d4d" />
 </p>
 
 <p align="center">
@@ -36,21 +36,31 @@
 
 `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., `<ResourceRenderer />`) 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)
+* **`@mcp-ui/server`**: Utilities to generate UI snippets (`HtmlResourceBlock`) on your MCP server.
+* **`@mcp-ui/client`**: UI components (e.g., `<ResourceRenderer />`) to render those snippets 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
 
 The primary component for rendering MCP resources is `<ResourceRenderer />`. It automatically detects the resource type and renders the appropriate component.
 
+It accepts the following props:
+- **`resource`**: The resource object from an MCP response. Should include `uri`, `mimeType`, and content (`text`, `blob`, or `content`)
+- **`onUiAction`**: Optional callback for handling UI actions from the resource:
+  ```typescript
+  { type: 'tool', payload: { toolName: string, params: Record<string, unknown> } } |
+  { type: 'intent', payload: { intent: string, params: Record<string, unknown> } } |
+  { type: 'prompt', payload: { prompt: string } } |
+  { type: 'notification', payload: { message: string } } |
+  { type: 'link', payload: { url: string } }
+  ```
+- **`supportedContentTypes`**: Optional array to restrict which content types are allowed (`['rawHtml', 'externalUrl', 'remoteDom']`)
+- **`style`**: Optional custom styles for iframe-based resources
+- **`iframeProps`**: Optional props passed to iframe elements (for HTML/URL resources)
+- **`library`**: Optional component library for Remote DOM resources (defaults to `basicComponentLibrary`)
+- **`remoteElements`**: Optional remote element definitions for Remote DOM resources. REQUIRED for Remote DOM snippets.
+
 ### Supported Resource Types
 
 #### HTML (`text/html` and `text/uri-list`)
@@ -60,26 +70,16 @@ Rendered using the `<HtmlResource />` component, which displays content inside a
 *   **`mimeType`**:
     *   `text/html`: Renders inline HTML content.
     *   `text/uri-list`: Renders an external URL. MCP-UI uses the first valid URL.
-*   **Props**:
-    *   **`resource`**: The `resource` object from an MCP message.
-    *   **`onUiAction`**: A callback function to handle events.
-    *   **`supportedContentTypes`**: (Optional) Array to filter content types (`'rawHtml'`, `'externalUrl'`).
-    *   **`style`**: (Optional) Custom styles for the iframe.
-    *   **`iframeProps`**: (Optional) Custom iframe props.
 
-#### Remote DOM (`application/vnd.mcp-ui.remote-dom+javascript`)
+#### Remote DOM (`application/vnd.mcp-ui.remote-dom`)
 
 Rendered using the `<RemoteDomResource />` component, which uses 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.mcp-ui.remote-dom; flavor={react | webcomponents}`
-* **Props**:
-    * **`resource`**: The `resource` object from an MCP message.
-    * **`library`**: A component library that maps remote element names (e.g., "button") to actual React or web components. `mcp-ui` provides a `basicComponentLibrary` for common HTML elements, and you can provide your own for custom components.
-    * **`onUiAction`**: A callback function to handle events.
 
 ### UI Action
 
-UI blocks must be able to interact with the agent. In `mcp-ui`, this is done by hooking into events sent from the UI block and reacting to them in the host. 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.
+UI snippets must be able to interact with the agent. In `mcp-ui`, this is done by hooking into events sent from the UI snippet and reacting to them in the host. 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
 
@@ -146,7 +146,7 @@ yarn add @mcp-ui/server @mcp-ui/client
    }
    ```
 
-3. **Enjoy** interactive MCP UIs — no extra configuration required.
+3. **Enjoy** interactive MCP UI snippets — no extra configuration required.
 
 ## 🌍 Examples
 
@@ -185,7 +185,7 @@ Contributions, ideas, and bug reports are welcome! See the [contribution guideli
 
 ## 📄 License
 
-Apache License 2.0 © [The MCP UI Authors](LICENSE)
+Apache License 2.0 © [The MCP-UI Authors](LICENSE)
 
 ## Disclaimer
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,124 @@
+# MCP-UI Documentation
+
+This directory contains the enhanced documentation for MCP UI, built with VitePress and featuring a professional, modern design.
+
+## 🎨 Design Enhancements
+
+The documentation has been significantly improved with:
+
+### Visual Design
+- **Modern Color Scheme**: Blue to green gradient branding with excellent contrast
+- **Professional Typography**: Inter font family with proper font weights and spacing
+- **Enhanced Shadows**: Subtle depth and visual hierarchy
+- **Smooth Animations**: Fade-in effects and hover transitions
+- **Responsive Design**: Mobile-first approach with breakpoint optimizations
+
+### Content Improvements
+- **Video Integration**: Demo video from README prominently featured on landing page
+- **Rich Feature Cards**: Six detailed feature cards with icons and descriptions
+- **Code Examples**: Syntax-highlighted examples with proper formatting
+- **Call-to-Action Buttons**: Professional buttons with hover effects
+- **Better Navigation**: Improved sidebar with collapsible sections
+
+### Technical Features
+- **Local Search**: Built-in search functionality
+- **Dark Mode**: Full dark mode support with proper color schemes
+- **SEO Optimization**: Meta tags, OpenGraph, and Twitter cards
+- **Performance**: Optimized loading and rendering
+- **Accessibility**: Proper ARIA labels and keyboard navigation
+
+## 🚀 Getting Started
+
+To run the documentation locally:
+
+```bash
+cd docs
+npm install
+npm run dev
+```
+
+To build for production:
+
+```bash
+npm run build
+```
+
+## 📁 Structure
+
+```
+docs/
+├── src/
+│   ├── .vitepress/
+│   │   ├── config.ts          # VitePress configuration
+│   │   └── theme/
+│   │       ├── index.ts       # Custom theme setup
+│   │       └── custom.css     # Enhanced styling
+│   ├── guide/                 # Documentation pages
+│   ├── public/                # Static assets
+│   │   ├── logo.svg          # Brand logo
+│   │   └── favicon.png       # Site favicon
+│   └── index.md              # Enhanced landing page
+└── README.md                 # This file
+```
+
+## 🎯 Key Features
+
+### Landing Page
+- Hero section with gradient text and compelling tagline
+- Demo video integration from the main README
+- Six feature cards highlighting key capabilities
+- Code examples showing quick usage
+- Call-to-action buttons linking to guides and demos
+
+### Navigation
+- Clean, organized sidebar with collapsible sections
+- Breadcrumb navigation
+- "Edit on GitHub" links
+- Social media links (GitHub, npm, Discord)
+
+### Content
+- Professional typography with proper hierarchy
+- Enhanced code blocks with syntax highlighting
+- Improved tables with hover effects
+- Styled blockquotes and badges
+- Responsive images and media
+
+### Performance
+- Optimized bundle size
+- Fast loading times
+- Efficient caching
+- Mobile-optimized assets
+
+## 🔧 Customization
+
+The documentation uses CSS custom properties for easy theming:
+
+```css
+:root {
+  --vp-c-brand-1: #3c82f6;      /* Primary brand color */
+  --vp-c-brand-2: #2563eb;      /* Secondary brand color */
+  --vp-c-accent-1: #10b981;     /* Accent color */
+  /* ... more variables */
+}
+```
+
+## 📝 Content Guidelines
+
+When adding new content:
+
+1. Use proper markdown headers (##, ###) for structure
+2. Include code examples with language tags
+3. Add screenshots or diagrams where helpful
+4. Keep paragraphs concise and scannable
+5. Use callouts for important information
+
+## 🤝 Contributing
+
+To contribute to the documentation:
+
+1. Edit files in the `src/` directory
+2. Test locally with `npm run dev`
+3. Build with `npm run build` to verify
+4. Submit a pull request
+
+The documentation automatically rebuilds on changes to the main branch.