MCP-UI Demo App

A comprehensive demonstration application showcasing the capabilities of MCP-UI - a framework for building dynamic UIs for Model Context Protocol (MCP) applications.

📖 Table of Contents

What is MCP-UI?
Features
Getting Started
Project Structure
MCP Tools
Architecture
Configuration
Usage Examples
Learn More

🎯 What is MCP-UI?

MCP-UI is a framework that enables developers to build interactive user interfaces for Model Context Protocol (MCP) applications. It allows MCP servers to return rich UI resources instead of just text, enabling:

Interactive Visualizations: Charts, graphs, and data visualizations
Rich User Interfaces: Full-featured web applications embedded as UI resources
Dynamic Content: Real-time updates and interactive components
Seamless Integration: Works with MCP-compatible AI assistants and clients

This demo application demonstrates these capabilities through a task management system with:

Text-based data tools
Interactive charts
Full kanban board interface

✨ Features

1. Text-Based Data Tools

Standard MCP tool that returns textual task status information:

Task counts by status
Priority breakdowns
Detailed task listings

2. Interactive Data Visualizations

UI resources that render dynamic charts:

Task status distribution (pie chart)
Priority breakdown (pie chart)
Real-time data visualization

3. Full-Featured Kanban Board

Complete task management interface as a UI resource:

Visual kanban workflow
Task cards with priority indicators
Status-based columns

4. Responsive Dashboard

Overview page with task statistics and recent activity

🚀 Getting Started

Prerequisites

Node.js 18+ or npm/yarn/pnpm package manager
Basic understanding of Next.js and React

Installation

Clone the repository:

git clone https://github.com/dataGriff/learn-mcpui.git
cd learn-mcpui

Install dependencies:

npm install
# or
yarn install
# or
pnpm install

Start the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
```'

Open your browser and navigate to:
- Main app: http://localhost:3000
- MCP endpoint: http://localhost:3000/mcp

Building for Production

npm run build
npm start

📁 Project Structure

learn-mcpui/
├── app/                      # Next.js app directory
│   ├── chart/               # Chart visualization pages
│   ├── dashboard/           # Dashboard overview page
│   ├── task/                # Kanban board page
│   ├── mcp/                 # MCP server route handler
│   ├── globals.css          # Global styles
│   ├── layout.tsx           # Root layout
│   └── page.tsx             # Home page
├── components/              # React components
│   └── ui/                  # UI components (Card, etc.)
├── lib/                     # Utility libraries
│   ├── mock-data.ts         # Sample task data
│   └── utils.ts             # Helper functions
├── tools/                   # MCP tool implementations
│   ├── get_tasks_status.ts          # Text-based data tool
│   ├── get_kanban_board.ts          # Kanban UI resource
│   ├── get_task_status_chart.ts     # Status chart UI resource
│   └── get_task_priority_chart.ts   # Priority chart UI resource
├── xmcp.config.ts           # xmcp configuration
├── next.config.ts           # Next.js configuration
├── tailwind.config.ts       # Tailwind CSS configuration
└── package.json             # Project dependencies

🛠️ MCP Tools

Note: The /mcp endpoint in this demo returns a placeholder response. The MCP tools are defined and would work with proper xmcp integration. This demo focuses on showcasing the UI capabilities that would be delivered by MCP-UI resources.

This application defines 4 MCP tools that would be exposed via the /mcp endpoint with full xmcp integration:

1. `get_tasks_status` (Text Tool)

Returns a textual representation of all task statuses.

Type: Standard text-based MCP tool
Returns: Formatted string with task counts and details

Example Response:

Kanban Board Task Status:

TASK STATUS BREAKDOWN:
📋 To Do: 3 tasks
⚡ In Progress: 3 tasks
✅ Done: 3 tasks
📦 Archived: 1 tasks
📊 Total Tasks: 10

PRIORITY BREAKDOWN:
🔴 High Priority: 4 tasks
🟡 Medium Priority: 4 tasks
🟢 Low Priority: 2 tasks
...

2. `get_kanban_board` (UI Resource)

Returns a UI resource that renders the full kanban board interface.

Type: UI Resource (External URL)
Renders: Interactive kanban board at /task

3. `get_task_status_chart` (UI Resource)

Returns a UI resource with a pie chart showing task status distribution.

Type: UI Resource (External URL)
Renders: Status distribution chart at /chart?type=status

4. `get_task_priority_chart` (UI Resource)

Returns a UI resource with a pie chart showing task priority distribution.

Type: UI Resource (External URL)
Renders: Priority distribution chart at /chart?type=priority

🏗️ Architecture

Technology Stack

Next.js 15: React framework for production
React 19: UI component library
TypeScript: Type-safe development
Tailwind CSS: Utility-first styling
xmcp: MCP server framework
@mcp-ui/server: UI resource creation utilities
Recharts: Data visualization library

How It Works

MCP Server Setup:
- The app uses xmcp to create an MCP server
- Tools are defined in the /tools directory
- The MCP endpoint is exposed at /app/mcp/route.ts
UI Resources:
- Tools use createUIResource() from @mcp-ui/server
- Each UI resource points to a Next.js page via externalUrl
- MCP clients render these URLs as embedded iframes

Data Flow:

MCP Client → Calls Tool → Returns UI Resource → Renders in iframe

xmcp Configuration

The xmcp.config.ts file configures the MCP server:

import { type XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  http: true,                    // Enable HTTP transport
  experimental: {
    adapter: "nextjs",           // Use Next.js adapter
  },
  paths: {
    tools: "tools",              // Tools directory
    prompts: false,              // No prompts directory
  },
};

export default config;

⚙️ Configuration

Connecting to MCP Clients

For Cursor

Add to your Cursor settings:

{
  "mcpServers": {
    "learn-mcpui": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

For Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "learn-mcpui": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

Environment Variables

For production deployments, the app automatically detects the host:

Local: Uses localhost:3000
Vercel: Uses VERCEL_PROJECT_PRODUCTION_URL
Can be customized in tool implementations

💡 Usage Examples

Example 1: Get Task Status (Text Tool)

When an MCP client calls get_tasks_status, it receives:

Kanban Board Task Status:

TASK STATUS BREAKDOWN:
📋 To Do: 3 tasks
⚡ In Progress: 3 tasks
✅ Done: 3 tasks
...

Example 2: Display Kanban Board (UI Resource)

When an MCP client calls get_kanban_board, it receives:

{
  "content": [{
    "uri": "ui://kanban-board/1234567890",
    "mimeType": "text/html",
    "iframeUrl": "http://localhost:3000/task"
  }]
}

The client then renders http://localhost:3000/task as an embedded iframe, showing the full interactive kanban board.

Example 3: Show Charts (UI Resource)

Calling get_task_status_chart or get_task_priority_chart returns UI resources that render interactive pie charts with task breakdowns.

📚 Learn More

MCP-UI Resources

MCP-UI Website: https://mcpui.dev
xmcp Framework: https://xmcp.dev
Model Context Protocol: https://modelcontextprotocol.io

Key Concepts

Model Context Protocol (MCP)

An open standard that enables AI assistants to securely connect with external data sources and tools. MCP provides:

Standardized tool calling
Resource management
Prompt templates
Extensible architecture

UI Resources

MCP-UI extends MCP by allowing tools to return UI resources instead of just text:

External URL: Points to a web page to be rendered in an iframe
Inline HTML: Embedded HTML content
Interactive: Full JavaScript/React applications

xmcp Framework

A TypeScript framework for building MCP servers with:

Type-safe tool definitions
Multiple transport layers (HTTP, stdio)
Framework adapters (Next.js, Express)
Hot reloading for development

🤝 Contributing

Contributions are welcome! This is a demo/learning project to help understand MCP-UI capabilities.

📝 License

This project is for educational purposes. See individual dependencies for their licenses.

🙏 Acknowledgments

Built with xmcp
Powered by MCP-UI
Based on the Model Context Protocol
Inspired by the xmcp-mcpui-nextjs-demo project

Happy coding with MCP-UI! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
app		app
components/ui		components/ui
docs		docs
lib		lib
tools		tools
.gitignore		.gitignore
.nojekyll		.nojekyll
README.md		README.md
SUMMARY.md		SUMMARY.md
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
xmcp-env.d.ts		xmcp-env.d.ts
xmcp.config.ts		xmcp.config.ts

Folders and files

Latest commit

History

Repository files navigation

MCP-UI Demo App

📖 Table of Contents

🎯 What is MCP-UI?

✨ Features

1. Text-Based Data Tools

2. Interactive Data Visualizations

3. Full-Featured Kanban Board

4. Responsive Dashboard

🚀 Getting Started

Prerequisites

Installation

Building for Production

📁 Project Structure

🛠️ MCP Tools

1. get_tasks_status (Text Tool)

2. get_kanban_board (UI Resource)

3. get_task_status_chart (UI Resource)

4. get_task_priority_chart (UI Resource)

🏗️ Architecture

Technology Stack

How It Works

xmcp Configuration

⚙️ Configuration

Connecting to MCP Clients

For Cursor

For Claude Desktop

Environment Variables

💡 Usage Examples

Example 1: Get Task Status (Text Tool)

Example 2: Display Kanban Board (UI Resource)

Example 3: Show Charts (UI Resource)

📚 Learn More

MCP-UI Resources

Related Documentation

Key Concepts

Model Context Protocol (MCP)

UI Resources

xmcp Framework

🤝 Contributing

📝 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `get_tasks_status` (Text Tool)

2. `get_kanban_board` (UI Resource)

3. `get_task_status_chart` (UI Resource)

4. `get_task_priority_chart` (UI Resource)

Packages