jaytoday/mcp-ui-server-demo

MCP-UI Server Demo

This comprehensive MCP-UI server demonstrates all aspects of interactive UI components using the Model Context Protocol (MCP) and MCP-UI framework. It showcases iframe-to-host communication, various UI resource types, and all supported MCP-UI message types.

🚀 Features Overview

The server provides 8 tools that demonstrate different aspects of MCP-UI functionality:

Core MCP-UI Demo Tools

showMCPUIDemo

The Flagship Demo Tool

• Purpose: Interactive demonstration of ALL MCP-UI message types and capabilities
• Features Demonstrated:
  • Tool Calls: Direct tool execution from iframe (getTasksStatus, handleIntent, handleDataRequest, nudgeTeamMember)
  • Prompt Requests: Sending prompts to be processed by the host
  • Intent Handling: Custom intents that trigger automatic tool calls (create-task, navigate-to-user, view-profile)
  • Notifications: One-way messages to notify the host of actions (task-completed, system-alert)
  • External Links: Opening URLs in new tabs (MCP Specification, Claude Documentation)
  • Asynchronous Data Requests: Requesting data with message ID tracking and response handling
  • Lifecycle Events: iframe ready signals and size change notifications
  • Interactive Scenarios: Multi-step workflows combining different message types
• UI Elements: Beautiful responsive interface with stats, activity logging, and real-time feedback

MCP-UI Message Handler Tools

handleIntent

• Purpose: Processes intent messages from MCP-UI interfaces
• Message Type: Handles intent messages
• Input: intent (string), params (object)
• Example Intents: create-task, navigate-to-user, view-profile, delete-item
• Response: Contextual actions based on the intent type

handleDataRequest

• Purpose: Processes asynchronous data requests with message ID tracking
• Message Type: Handles ui-request-data messages
• Input: requestType (string), params (object)
• Example Requests: get-current-user, get-team-status, get-user-profile
• Response: Structured data responses that get sent back to the requesting iframe

getTasksStatus

• Purpose: Retrieves comprehensive task status information
• Features: Returns task counts, completion rates, recent activity, team metrics
• Use Case: Demonstrates tool calls from iframe interfaces

nudgeTeamMember

• Purpose: Sends reminders to team members about pending tasks
• Input: teamMember (string) - team member to nudge
• Features: Simulates team communication and task management
• Use Case: Shows practical business logic executed via MCP-UI

Basic UI Resource Tools

showExternalUrl

• Purpose: Creates iframe pointing to external URL (example.com)
• UI Resource Type: External URL
• Features: Basic iframe embedding

showRawHtml

• Purpose: Displays static HTML content
• UI Resource Type: Raw HTML
• Features: Static content rendering

showRemoteDom

• Purpose: Executes remote script with custom components
• UI Resource Type: Remote DOM
• Features: Custom <ui-text> component usage, dynamic script execution

🎯 MCP-UI Message Types Demonstrated

1. Tool Messages (type: "tool")

window.parent.postMessage({
  type: "tool",
  payload: {
    toolName: "getTasksStatus",
    params: {}
  }
}, "*");

• Tools Available: getTasksStatus, handleIntent, handleDataRequest, nudgeTeamMember
• Demo Features: Dropdown selection, parameter input, real-time execution

2. Prompt Messages (type: "prompt")

window.parent.postMessage({
  type: "prompt",
  payload: {
    prompt: "What is the current status of all team tasks?"
  }
}, "*");

• Demo Features: Text input for custom prompts, predefined examples
• Use Cases: Integration with LLMs, natural language processing

3. Intent Messages (type: "intent")

window.parent.postMessage({
  type: "intent",
  payload: {
    intent: "create-task",
    params: { title: "New Task", priority: "high" }
  }
}, "*");

• Available Intents: create-task, navigate-to-user, view-profile, delete-item
• Auto-Integration: Automatically calls handleIntent tool when received
• Demo Features: Button-based intent triggering with context

4. Notification Messages (type: "notify")

window.parent.postMessage({
  type: "notify",
  payload: {
    message: "Task has been completed successfully"
  }
}, "*");

• Notification Types: task-completed, system-alert, user-action, data-sync
• Demo Features: One-click notifications with different severity levels

5. Link Messages (type: "link")

window.parent.postMessage({
  type: "link",
  payload: {
    url: "https://modelcontextprotocol.io/specification"
  }
}, "*");

• External Links: MCP Specification, Claude Documentation, GitHub repos
• Demo Features: Automatic new tab opening with security attributes

6. Data Request Messages (type: "ui-request-data")

window.parent.postMessage({
  type: "ui-request-data",
  messageId: "req-123",
  payload: {
    requestType: "get-current-user",
    params: {}
  }
}, "*");

• Request Types: get-current-user, get-team-status, get-user-profile
• Features: Message ID tracking, asynchronous response handling
• Auto-Integration: Automatically calls handleDataRequest tool

7. Lifecycle Messages

• UI Size Change (type: "ui-size-change"): Automatic ResizeObserver integration
• Iframe Ready (type: "ui-lifecycle-iframe-ready"): Initialization signal
• Demo Features: Automatic size detection, manual size change triggers

🛠️ Running the Server

Development Mode

# Install dependencies
npm install
# or
pnpm install

# Start development server
npm run dev
# or  
pnpm dev

The server will be available at http://localhost:3003.

Production Mode

# Build the project
npm run build

# Start production server
npm start

🔗 Integration with MCP Inspector

Connect to this server using the MCP Inspector:

1. Server URL: http://localhost:3003/mcp
2. Transport Type: Streamable HTTP Transport
3. Server Name: MCP-UI Server Demo

Testing Steps

1. Connect to the server in the Inspector
2. Navigate to the "Tools" tab
3. Execute showMCPUIDemo to launch the comprehensive demo
4. Test all message types through the interactive interface
5. Monitor activity logs and MCP tool execution in real-time

📚 MCP-UI Architecture

Message Flow

┌─────────────────┐    postMessage    ┌──────────────────┐
│   MCP-UI        │ ──────────────── │   MCP Inspector  │
│   Iframe        │                   │   (Host)         │
│                 │ ←──────────────── │                  │
└─────────────────┘    response       └──────────────────┘
                                              │
                                              ▼
                                      ┌──────────────────┐
                                      │   MCP Server     │
                                      │   (This Demo)    │
                                      └──────────────────┘

Security Features

• Sandboxed Execution: All iframe content runs in isolated sandbox
• Message Validation: Structured message format with type safety
• CORS Protection: Proper origin handling and security headers
• Content Security: No direct DOM access between iframe and host

Asynchronous Tracking

• Message IDs: Unique identifiers for request/response correlation
• Response Types: ui-message-received (acknowledgment) and ui-message-response (final result)
• Error Handling: Graceful failure handling and user feedback

🎨 Demo Interface Features

The showMCPUIDemo tool provides:

• 📊 Statistics Dashboard: Live metrics and counters
• 🎮 Interactive Controls: Buttons, dropdowns, and input fields for testing
• 📝 Activity Log: Real-time logging of all message exchanges
• 🔄 Scenario Testing: Multi-step workflows demonstrating real-world use cases
• 📱 Responsive Design: Works on desktop and mobile devices
• 🎯 Message ID Tracking: Visual feedback for asynchronous operations

🔍 Advanced Features

Real-World Integration Patterns

• Task Management: Create, update, and track tasks
• Team Communication: Nudging and notifications
• Data Synchronization: Requesting and updating shared data
• Navigation: Intent-based routing and deep linking
• Status Monitoring: Real-time status updates and metrics

Development Best Practices

• TypeScript Support: Full type safety throughout
• Error Boundaries: Graceful error handling
• Performance Optimization: Efficient message passing
• Testing Integration: Built-in logging and debugging tools
• Documentation: Comprehensive inline documentation

For detailed implementation guidance, see the MCP-UI Documentation and MCP Specification.