使用说明

MCP Visualizer

A lightweight, modern, and highly visual web application that showcases how an MCP (Model Context Protocol) server operates: streaming messages, tool calls, and agent actions with rich motion and theme customization.

✨ Features

🎬 Cinematic UI: Smooth animations with Framer Motion and glassmorphism aesthetics
📡 Real-time Streaming: WebSocket-based event streaming for live updates
🎨 Theme Customization: Multiple presets (Neon, Terminal, Minimal, Glass) with runtime controls
🔧 Tool Visualization: Beautiful cards for tool calls, results, and progress tracking
🔍 Event Inspector: Detailed inspection pane for debugging and exploration
📊 Mock & Live Modes: Test with scripted sessions or connect to a live MCP server
⚡ Performance: Built with Vite for lightning-fast development and builds

🏗️ Architecture

mcp_demo/
├── apps/
│   ├── web/          # React + Vite frontend
│   └── server/       # Node.js + Express + WebSocket backend
├── packages/
│   ├── types/        # Shared TypeScript types
│   ├── mocks/        # Mock data generator & session player
│   └── mcp-client/   # MCP protocol client library
└── pnpm-workspace.yaml

Tech Stack

Frontend:

React 18 with TypeScript
Vite for blazing-fast builds
Tailwind CSS for styling
Framer Motion for animations
Zustand for state management
Lucide React for icons

Backend:

Node.js 20+
Express for HTTP API
ws (WebSocket) for real-time communication
TypeScript for type safety

🚀 Quick Start

Prerequisites

Node.js 20 or higher
pnpm 8 or higher

# Install pnpm if you don't have it
npm install -g pnpm

Installation

Clone or navigate to the repository:

cd /Users/josemoreno/Desktop/repos/mcp_demo

Install dependencies:

pnpm install

Build packages:

pnpm build

Development

Start both frontend and backend in development mode:

# Terminal 1: Start backend server
cd apps/server
pnpm dev

# Terminal 2: Start frontend
cd apps/web
pnpm dev

Or use the root command to run both in parallel:

pnpm dev

The app will be available at:

Frontend: http://localhost:5173
Backend API: http://localhost:3002
WebSocket: ws://localhost:3002/stream

📖 Usage

Starting a Session

Mock Mode (Recommended for Demo):
- Click "Start Mock" in the header
- Watch the scripted demo session play out automatically
- Shows weather queries, search, and file writing tools
Live Mode:
- Click "Connect Live" to connect to a live MCP server
- Requires an MCP server running on the configured endpoint

Controls

Play/Pause: Control mock session playback
Stop: End the current session
Reset: Clear all events and stop the session
Theme: Click the palette icon to customize appearance
Inspector: Toggle the right panel to inspect event details

Exploring Events

Click any event in the timeline to view details in the Inspector
Expand tool results to see full output
View raw JSON for debugging

🎨 Theming

Styled with Labelbox Brand Guidelines
This app uses the official Labelbox brand identity:

Logo: Custom Labelbox wordmark with theme-adaptive variants (see LOGO_INTEGRATION.md)

Colors: Blue (#93C5FD), Amber (#FBBF24), Orange (#FB923C), Black (#262626), Neutral (#F5F5F5)

Typography: IBM Plex Sans and IBM Plex Mono from Google Fonts

Favicon: Branded icon using official color palette

Available Presets

Labelbox (Default): Official Labelbox brand colors and styling
Default: Clean modern design with blue accents
Neon: Dark theme with vibrant purple/pink accents
Terminal: Matrix-inspired green on black
Minimal: Ultra-clean monochrome design
Glass: Light theme with glassmorphism effects

Runtime Customization

Mode: Switch between light and dark
Preset: Choose from built-in themes
Font: Inter, System, or Monospace
Size: Scale UI from 80% to 120%

🔧 Configuration

Environment Variables

Backend (apps/server/.env):

PORT=3001
CORS_ORIGIN=http://localhost:5173

Frontend (Vite proxy configured in vite.config.ts):

API requests to /api/* are proxied to http://localhost:3001
WebSocket connects directly to ws://localhost:3001/stream

📦 Building for Production

Build all packages and apps:

pnpm build

Individual builds:

# Build frontend only
cd apps/web
pnpm build

# Build backend only
cd apps/server
pnpm build

Deployment

Frontend (Static Site):

Deploy the apps/web/dist folder to Vercel, Netlify, or any static host
Set the WebSocket URL to your production backend

Backend (Node.js Server):

Deploy the apps/server folder to any Node.js hosting service
Ensure WebSocket support is enabled
Set appropriate CORS origins

🧪 Example Tools

The demo includes three example tools:

1. get_weather

{
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA",
    "units": "fahrenheit"
  },
  "output": {
    "temperature": 62,
    "conditions": "Partly Cloudy",
    "humidity": 65,
    "wind_speed": 12
  }
}

2. search

{
  "name": "search",
  "input": {
    "query": "best restaurants in San Francisco",
    "limit": 5
  },
  "output": {
    "results": [
      { "name": "State Bird Provisions", "rating": 4.5 },
      { "name": "Gary Danko", "rating": 4.7 }
    ]
  }
}

3. write_file

{
  "name": "write_file",
  "input": {
    "path": "hello.py",
    "content": "print('Hello, World!')"
  },
  "output": {
    "path": "hello.py",
    "bytesWritten": 24,
    "success": true
  }
}

🔌 Connecting to a Real MCP Server

To connect to an actual MCP server:

Update the MCP client in packages/mcp-client/src/index.ts
Implement the protocol-specific connection logic
Configure the endpoint in the backend server
Use "Connect Live" mode in the UI

The current implementation is a placeholder that can be extended for real MCP protocol communication.

📝 API Reference

REST Endpoints

POST /api/session/start

{
  "mode": "mock" | "live",
  "metadata": {}
}

Response:

{
  "sessionId": "session_123",
  "tools": [...],
  "status": "success"
}

POST /api/session/:id/stop

Stops the session and unsubscribes from events

POST /api/session/:id/message

{
  "content": "What's the weather?"
}

POST /api/tools/call

{
  "sessionId": "session_123",
  "toolName": "get_weather",
  "input": { "location": "NYC" }
}

GET /api/tools

Returns available tool schemas

WebSocket

Connect to ws://localhost:3001/stream

Subscribe to Session:

{
  "type": "control",
  "data": { "action": "subscribe", "sessionId": "session_123" }
}

Receive Events:

{
  "type": "event",
  "data": {
    "id": "evt_123",
    "type": "message",
    "ts": 1234567890,
    "sessionId": "session_123",
    "payload": { ... }
  }
}

🎯 Project Structure

Packages

@mcp-demo/types - Shared TypeScript types

Event types (Message, ToolCall, ToolResult, SystemEvent)
Session and tool schema definitions
WebSocket message types

@mcp-demo/mocks - Mock data generation

MockSessionPlayer: Plays scripted sessions with timing
Predefined demo sessions (weather, search, file operations)
Random event generator for testing

@mcp-demo/mcp-client - MCP protocol client

Placeholder implementation for MCP connection
Event emitter for session events
Reconnection and heartbeat logic

Apps

@mcp-demo/web - React frontend

store/: Zustand state management
components/: UI components (Timeline, Inspector, etc.)
lib/: Utilities and WebSocket client

@mcp-demo/server - Express backend

routes/: API endpoints
websocket.ts: WebSocket server setup
session-manager.ts: Session state and event distribution

🎨 Customization Guide

Adding New Themes

Add CSS variables in apps/web/src/index.css:

.theme-custom {
  --background: ...;
  --foreground: ...;
  --primary: ...;
  /* etc */
}

Add to preset list in ThemeSelector.tsx

Adding New Tools

Define schema in session-manager.ts:

{
  name: 'my_tool',
  description: '...',
  inputSchema: { /* JSON Schema */ }
}

Implement execution logic in callTool() method

Creating Custom Sessions

Create in packages/mocks/src/sessions.ts:

export const mySession: MockSession = {
  name: 'My Session',
  description: '...',
  events: [
    {
      delay: 1000,
      event: { type: 'message', payload: { ... } }
    }
  ]
}

🐛 Troubleshooting

WebSocket won't connect:

Ensure backend is running on port 3001
Check CORS settings in apps/server/src/index.ts
Verify WebSocket URL in apps/web/src/store/app-store.ts

Events not appearing:

Check browser console for errors
Verify session is active (green "Connected" status)
Try clicking "Reset" and starting a new session

Build errors:

Run pnpm install to ensure all dependencies are installed
Try pnpm clean followed by pnpm build
Check Node.js version (requires 20+)

📄 License

This is a demo project for showcasing MCP functionality. Feel free to use and modify as needed.

🤝 Contributing

This is a demonstration project. Feel free to fork and customize for your needs!

🔮 Future Enhancements

[ ] Timeline minimap with event type visualization
[ ] Multi-session tabs for comparing runs
[ ] Export session as GIF/MP4 for presentations
[ ] Prompt playground for crafting agent prompts
[ ] Offline support with IndexedDB persistence
[ ] Mobile-optimized responsive design
[ ] Authentication and session sharing

Built with ❤️ using React, TypeScript, and Framer Motion