MCP Demo UI & Server Suite

A comprehensive interactive UI and demo server suite for learning and experimenting with the Model Context Protocol (MCP). This project includes:

• 🖥️ Interactive Web UI - Visual MCP architecture explorer and server manager

• 🔧 4 Demo MCP Servers - Calculator, Database, API Integration, and File System servers

• 📚 Educational Content - Learn MCP concepts through hands-on examples

• 🛠️ Tool Testing Interface - Execute MCP tools in real-time

• 📡 Protocol Inspector - Monitor MCP communication messages

• 🎯 Production-Ready Code - Async/await patterns with proper error handling

🚀 Quick Start

1. Install Dependencies

uv sync

2. Start the Demo UI

uv run python ui_backend.py

3. Open in Browser

Navigate to: http://localhost:8000

4. Explore & Learn

• View MCP architecture diagrams

• Start/stop demo servers

• Test tools interactively

• Monitor protocol messages

• Learn MCP concepts

📖 What is MCP?

Model Context Protocol (MCP) is an open protocol that enables AI assistants and applications to securely access external data sources and tools. It provides a standardized way for AI models to:

• 🔌 Connect to External APIs - Weather, news, databases, etc.

• 💾 Access File Systems - Read/write files and directories

• 🛠️ Execute Custom Functions - Domain-specific business logic

• 📊 Query Databases - SQL operations and data retrieval

• 🤖 Extend AI Capabilities - Beyond training data limitations

MCP acts as a bridge between AI applications and external resources, allowing models to extend their capabilities through secure, standardized interfaces.

🎯 Why MCP Matters

MCP solves critical challenges in AI application development:

🔒 Security & Control

• Problem: Direct API access from AI models raises security concerns

• Solution: MCP servers act as controlled gateways with proper authentication

📊 Real-Time Data Access

• Problem: AI models have training cutoffs and can't access live data

• Solution: MCP servers provide access to live APIs, databases, and services

🏗️ Standardization

• Problem: Each AI application needs custom integration code

• Solution: Standardized MCP protocol works across different AI applications

🛠️ Custom Business Logic

• Problem: Generic AI models don't know your specific business processes

• Solution: MCP servers expose domain-specific tools and workflows

⚡ Action Execution

• Problem: AI models can only generate text, not perform actions

• Solution: MCP servers execute tools on behalf of the AI model

🏛️ MCP Architecture

MCP follows a client-server architecture with multiple transport options:

Visual Architecture

┌─────────────┐         MCP Protocol         ┌─────────────┐
│             │ ◄──────────────────────────► │             │
│ MCP Client  │     (JSON-RPC over stdio)   │ MCP Server  │
│  (AI App)   │                              │  (This App) │
│             │                              │             │
└─────────────┘                              └─────────────┘
                                                      │
                                                      │
                                              ┌───────┴───────┐
                                              │               │
                                         External APIs    Databases
                                         File Systems    Services

Key Components

Transport Mechanisms

1. Stdio (Standard I/O)

• Use Case: Local development, Claude Desktop integration

• Communication: Direct process stdin/stdout

• Pros: Low latency, simple, secure

• Cons: Single client, local only

2. HTTP

• Use Case: Production, multiple clients, remote access

• Communication: HTTP requests/responses

• Pros: Network-based, scalable, multiple clients

• Cons: Higher latency, network configuration needed

Communication Flow

1. Client sends JSON-RPC request

2. Server processes request (calls tools/fetches resources)

3. Server sends JSON-RPC response

4. Client uses response in AI context

🔄 MCP Server Lifecycle

1. Initialization

• Server starts and listens on transport (stdio/HTTP)

• Server registers available tools, resources, and prompts

• Server sends initialization message to client

2. Handshake

• Client and server exchange capabilities

• Client requests server information (name, version, available tools)

• Server responds with its capabilities

3. Operation

• Client sends tool execution requests

• Server processes requests and executes tools

• Server returns results to client

• This cycle repeats for each interaction

4. Shutdown

• Client sends shutdown signal

• Server cleans up resources

• Server terminates gracefully

Start Server → Initialize FastMCP → Register Tools → Listen on stdio/HTTP
                                                                          │
                                                                          ▼
Client Connects → Handshake → Request Tool → Execute Tool → Return Result
                                                                          │
                                                                          ▼
                                                              Continue Listening...

🛠️ Demo MCP Servers

The suite includes 4 comprehensive demo servers showcasing different MCP use cases:

1. 🧮 Calculator Server (Port 8081)

Basic arithmetic operations with async/await patterns

• add(a, b) - Addition

• subtract(a, b) - Subtraction

• multiply(a, b) - Multiplication

• divide(a, b) - Division

• power(base, exponent) - Exponentiation

• square_root(number) - Square root calculation

2. 💾 Database Server (Port 8082)

Expense tracking with SQLite and proper error handling

• add_expense(description, amount, category, ...) - Add expense

• list_expenses(limit) - List expenses

• get_expense(expense_id) - Get specific expense

• delete_expense(expense_id) - Delete expense

• get_expense_summary() - Get expense statistics

3. 🌐 API Integration Server (Port 8083)

External API integrations (mock implementations)

• get_weather(city) - Weather data

• get_news(category, limit) - News articles

• search_github(query, limit) - GitHub repository search

• get_crypto_price(symbol) - Cryptocurrency prices

• translate_text(text, target_language) - Text translation

4. 📁 File System Server (Port 8084)

Safe file system operations within project directory

• list_directory(path) - List directory contents

• read_file(path, max_lines) - Read text files

• write_file(path, content, append) - Write to files

• search_files(query, path, file_types) - Search file contents

• get_file_info(path) - Get file/directory metadata

🎮 Using the Demo UI

Prerequisites

• Python 3.12 or higher

• uv package manager (recommended)

Installation

# Clone or navigate to project directory
cd fastmcp-demo-server

# Install dependencies
uv sync

Start the Interactive UI

# Start the demo UI server
uv run python ui_backend.py

Access the UI at: http://localhost:8000

UI Features

🏗️ Architecture Tab

• Interactive MCP architecture diagram

• Key components explanation

• Transport mechanism comparison

• Communication flow visualization

🖥️ Servers Tab

• Server Management: Start/stop individual demo servers

• Real-time Status: See which servers are running and their ports

• Auto-refresh: Server status updates automatically

🔧 Tools Tab

• Tool Selection: Choose from available tools across servers

• Parameter Input: Dynamic form generation for tool parameters

• Live Execution: Execute tools and see results in real-time

• Execution History: Track previous tool calls and responses

📡 Protocol Tab

• Message Inspector: Monitor JSON-RPC communication

• Protocol Viewer: See raw MCP protocol messages

• Debugging Tools: Clear logs and refresh monitoring

📚 Learn Tab

• Educational Content: MCP concepts and best practices

• Code Examples: Working implementations with explanations

• Use Cases: Real-world applications of MCP

• Further Reading: Links to documentation and resources

Testing Individual Servers

You can also test servers individually:

# Test Calculator Server
uv run python demo_servers/calculator_server.py

# Test Database Server
uv run python demo_servers/database_server.py

# Test API Server
uv run python demo_servers/api_server.py

# Test File System Server
uv run python demo_servers/filesystem_server.py

Using with Claude Desktop

1. Configure MCP Server:

uv run fastmcp install claude-desktop main.py

2. Restart Claude Desktop to load the new server

3. Use tools in chat - Claude will now have access to your MCP tools

✨ Key Features & Benefits

🎓 Educational Value

• Interactive Learning: Hands-on experience with MCP concepts

• Visual Architecture: See how MCP components work together

• Protocol Inspection: Understand JSON-RPC communication

• Best Practices: Learn production-ready patterns

🛠️ Development Features

• Async/Await Patterns: Modern Python concurrency

• Error Handling: Comprehensive try/except blocks

• Type Safety: Proper parameter validation

• Resource Management: Safe database and file operations

🔧 Practical Applications

• Database Integration: SQLite operations with async support

• API Orchestration: Multiple external service integrations

• File System Operations: Safe file manipulation within project bounds

• Mathematical Computing: Calculator with advanced operations

🌐 Production Ready

• Scalable Architecture: HTTP transport for multiple clients

• Security Considerations: Controlled file access, input validation

• Monitoring: Logging and error reporting

• Documentation: Comprehensive code comments and docstrings

📁 Project Structure

fastmcp-demo-server/
├── ui_backend.py                 # FastAPI backend for the demo UI
├── main.py                       # Original expense tracker server
├── local-guide.md                # Development and deployment guide
├── pyproject.toml               # Project dependencies and metadata
├── uv.lock                      # Dependency lock file
├── expenses.db                  # SQLite database (auto-created)
├── .gitignore                   # Git ignore rules
└── demo_servers/                # Individual demo MCP servers
    ├── calculator_server.py    # Arithmetic operations server
    ├── database_server.py      # Expense tracking server
    ├── api_server.py          # External API integrations
    └── filesystem_server.py   # File system operations server

🏗️ Architecture Overview

UI Backend (FastAPI)

• Purpose: Serves the interactive web UI and manages demo servers

• Features: Server lifecycle management, tool testing, protocol inspection

• Endpoints: REST API for server control and tool execution

• Frontend: Bootstrap-based responsive web interface

Demo Servers (FastMCP)

• Framework: FastMCP for simplified MCP server development

• Transport: HTTP for network access and multiple clients

• Async Support: Full async/await implementation with error handling

• Security: Controlled access boundaries (especially for file operations)

Key Implementation Details

Async/Await Patterns

@mcp.tool
async def add_expense(description: str, amount: float, category: str) -> dict:
    try:
        async with aiosqlite.connect(DB_PATH) as conn:
            # Async database operations
            await conn.execute(...)
            await conn.commit()
            return {"status": "success"}
    except Exception as e:
        return {"status": "error", "message": str(e)}

Error Handling Strategy

• Database Errors: aiosqlite.Error for connection/query issues

• Validation Errors: Custom validation with descriptive messages

• System Errors: General Exception handling with logging

• Graceful Degradation: Return structured error responses

Security Measures

• File Operations: Restricted to project directory only

• Input Validation: Type checking and parameter validation

• Resource Limits: Connection pooling, timeout handling

• Access Control: Path traversal prevention

🚀 Advanced Usage

Development Workflow

1. Using uv Package Manager

# Initialize new MCP project
mkdir my-mcp-server
cd my-mcp-server
uv init .
uv add fastmcp aiosqlite aiofiles aiohttp

# Create server
# ... add your server code ...

# Run in development mode
uv run fastmcp dev main.py

# Run production server
uv run fastmcp run main.py

# Install to Claude Desktop
uv run fastmcp install claude-desktop main.py

2. MCP Inspector for Debugging

# Start inspector (usually at http://localhost:8000)
uv run fastmcp dev main.py

# Test tools and inspect protocol messages
# Monitor server behavior in real-time

Production Deployment

Environment Configuration

# Set environment variables
export MCP_SERVER_PORT=8080
export MCP_SERVER_HOST=0.0.0.0
export DATABASE_URL=sqlite:///production.db

# Run with production settings
uv run python main.py

Docker Deployment

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install uv && uv sync --no-dev
EXPOSE 8080
CMD ["uv", "run", "python", "main.py"]

📚 Learning Path

Beginner Level

1. Start the Demo UI - Explore the interactive interface

2. Run Individual Servers - Test each demo server separately

3. Examine Code - Read through the implementations

4. Modify Tools - Add your own simple tools

Intermediate Level

1. Add New Tools - Extend existing servers with new functionality

2. Create Resources - Implement MCP resources (not just tools)

3. Add Prompts - Create reusable prompt templates

4. Error Handling - Improve error handling and validation

Advanced Level

1. Custom Transport - Implement custom transport mechanisms

2. Authentication - Add authentication and authorization

3. Monitoring - Add metrics and logging

4. Scaling - Handle multiple concurrent clients

5. Production Deployment - Deploy to cloud platforms

🔗 Resources

Official Documentation

• Model Context Protocol Specification

• FastMCP Framework

• MCP GitHub Repository

Community Resources

• Claude Desktop MCP Guide

• MCP Server Examples

• Community MCP Servers

Development Tools

• MCP Inspector: Built-in tool for debugging MCP servers

• uv: Fast Python package manager and project manager

• FastAPI: Modern async web framework (used in UI backend)

🤝 Contributing

Ways to Contribute

1. Add New Demo Servers - Create servers for different use cases

2. Improve UI Features - Enhance the interactive interface

3. Add Educational Content - Create more learning materials

4. Fix Bugs - Report and fix issues

5. Documentation - Improve guides and examples

Development Setup

# Fork and clone
git clone https://github.com/yourusername/fastmcp-demo-server.git
cd fastmcp-demo-server

# Install dependencies
uv sync

# Start development
uv run python ui_backend.py

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Anthropic for creating the Model Context Protocol

• FastMCP team for the excellent framework

• uv team for the amazing package manager

• Bootstrap team for the UI framework

Happy MCP Development! 🎉

Learn, experiment, and build amazing AI-powered applications with the Model Context Protocol.