# Demo MCP Server

A simple but complete MCP (Model Context Protocol) server built for presentations and demonstrations. This server showcases all three core MCP primitives: Tools, Resources, and Prompts in under 240 lines of Python code.

> **For Presenters:** See [DEMO_CHEATSHEET.md](DEMO_CHEATSHEET.md) for a detailed 5-minute presentation script with timing guide.

## What This Demonstrates

This demo server showcases:

1. **Tools** (Model-controlled functions)
   - `calculate_tip` - Financial calculations
   - `analyze_text` - Text analysis and statistics
   - `convert_temperature` - Temperature conversion

2. **Resources** (Application-controlled data)
   - `demo://server-info` - Server metadata and capabilities
   - `demo://example-data` - Sample data for testing
   - `demo://statistics` - Usage statistics

3. **Prompts** (User-controlled templates)
   - `demo_workflow` - Guided walkthrough of all capabilities
   - `quick_demo` - 2-minute quick demonstration

## Quick Start

### Prerequisites

```bash
pip install fastmcp
```

For MCP Inspector (requires Node.js):
```bash
npm install -g @modelcontextprotocol/inspector
```

### Option 1: Interactive Demo with MCP Inspector (Recommended)

**Linux/Mac:**
```bash
cd mcp-demo
./demo.sh
# Choose option 1 for interactive demo
```

**Windows/Direct:**
```bash
npx @modelcontextprotocol/inspector python demo_server.py
```

This opens a web UI where you can:
- Browse available tools, resources, and prompts
- Test tools with custom inputs
- See real-time JSON responses
- Perfect for live presentation demos

### Option 2: Use with Claude Desktop

1. Add to your Claude Desktop config:
   - **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "demo-server": {
      "command": "python",
      "args": ["D:\\Demo\\mcp-demo\\demo_server.py"]
    }
  }
}
```

2. Restart Claude Desktop completely
3. Look for the hammer icon - server tools will be available in conversations
4. The server should auto-start when Claude Desktop launches

### Option 3: Standalone Server

```bash
python demo_server.py
```

The server will start and display:
- 3 available tools
- 3 resources
- 2 prompts

Connect via any MCP-compatible client (Claude Desktop, Cursor, VS Code with MCP extension).

## Demo Script for Presentation

### Setup (30 seconds before demo)
```bash
cd mcp-demo
npx @modelcontextprotocol/inspector python3 demo_server.py
```

### Demo Flow (5 minutes)

#### 1. Introduction (30 seconds)
**Show the code:**
- Open `demo_server.py`
- Highlight the decorators: `@mcp.tool()`, `@mcp.resource()`, `@mcp.prompt()`
- Point out: "150 lines of Python, zero boilerplate"

**Say:**
> "This is a complete MCP server. Notice how simple it is - just Python functions with decorators. Type hints automatically generate schemas, docstrings become descriptions for the LLM."

#### 2. Tools Demo (2 minutes)
**In MCP Inspector:**
- Click on "Tools" tab
- Show the three available tools

**Live Demo - calculate_tip:**
```json
{
  "bill_amount": 100,
  "tip_percentage": 20
}
```

**Say:**
> "Tools are model-controlled - the LLM decides when to invoke them based on user requests. Here we calculate a 20% tip on $100. See the structured JSON response."

**Live Demo - analyze_text:**
```json
{
  "text": "The Model Context Protocol enables AI applications to seamlessly connect with external tools and data sources."
}
```

**Say:**
> "Same pattern - clean input, structured output. The LLM can use this data to provide intelligent responses."

#### 3. Resources Demo (1 minute)
**In MCP Inspector:**
- Click on "Resources" tab
- Fetch `demo://server-info`

**Say:**
> "Resources are application-controlled data sources. Unlike tools where the LLM decides, here the client application determines when to fetch data. Think of them like REST GET endpoints - they provide context to the AI."

**Show the JSON response with server capabilities**

#### 4. Prompts Demo (1 minute)
**In MCP Inspector:**
- Click on "Prompts" tab
- Show `demo_workflow` and `quick_demo`

**Say:**
> "Prompts are user-controlled templates. In a real application, these would appear as slash commands or menu items. They help users accomplish common tasks without remembering exact phrasing."

**Trigger the quick_demo prompt and show how it structures the interaction**

#### 5. Wrap Up (30 seconds)

**Say:**
> "From concept to working server: minutes, not hours. This same server works with Claude Desktop, Cursor, VS Code - any MCP-compatible client. Build once, use everywhere. That's the power of MCP."

## Key Talking Points

### During Code Review
- "Type hints auto-generate JSON schemas"
- "Docstrings become LLM-readable descriptions"
- "Zero configuration - just decorators and functions"

### During Tool Demo
- "LLM autonomously decides when to call these"
- "Structured inputs and outputs"
- "Error handling built into the protocol"

### During Resources Demo
- "Application controls when to fetch"
- "Real-time data without tool invocation overhead"
- "Perfect for context that changes frequently"

### During Prompts Demo
- "User initiates via UI or commands"
- "Reusable templates for common workflows"
- "Guides users through complex interactions"

### Closing
- "Three primitives cover all integration needs"
- "Build once, deploy everywhere"
- "10,000+ servers in the ecosystem already"

## Testing the Demo

### Test calculate_tip
```bash
# In MCP Inspector or programmatically
calculate_tip(85.50, 18)

# Expected output:
{
  "bill_amount": 85.5,
  "tip_percentage": 18,
  "tip_amount": 15.39,
  "total": 100.89,
  "split_2_people": 50.45
}
```

### Test analyze_text
```bash
analyze_text("Building MCP servers is straightforward with official SDKs.")

# Expected output:
{
  "word_count": 8,
  "character_count": 60,
  "character_count_no_spaces": 52,
  "estimated_reading_time_minutes": 0.0,
  "analyzed_at": "2025-01-23T..."
}
```

### Test convert_temperature
```bash
convert_temperature(25, "C", "F")

# Expected output:
{
  "original_value": 25,
  "original_unit": "C",
  "converted_value": 77.0,
  "converted_unit": "F",
  "formula_used": "C → C → F"
}
```

Supports conversion between Celsius (C), Fahrenheit (F), and Kelvin (K) in any direction.

## Requirements

**Python Dependencies:**
```bash
pip install fastmcp
```

**For MCP Inspector (Optional):**
- Node.js 16+ required
- Install: `npm install -g @modelcontextprotocol/inspector`
- Or use directly: `npx @modelcontextprotocol/inspector`

**Tested with:**
- Python 3.10+
- FastMCP 0.2.0+
- Claude Desktop (latest)

## Learning Points for Audience

After this demo, your audience will understand:

1. **How simple MCP servers are to build** - Less than 200 lines for a full-featured server
2. **The three core primitives** - Tools, Resources, Prompts and when to use each
3. **Type-driven development** - Python types become API contracts
4. **Instant testing** - MCP Inspector provides immediate feedback
5. **Portability** - Same server works across all MCP clients

## Troubleshooting

### "ModuleNotFoundError: No module named 'fastmcp'"
```bash
pip install fastmcp
```

### "npx command not found"
Install Node.js from https://nodejs.org/

### Server not appearing in Claude Desktop
1. **Check config path:**
   - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. **Verify Python path:** Use absolute path to `demo_server.py`
3. **Check Python command:** Use `python` or `python3` depending on your system
4. **Restart Claude Desktop:** Completely quit and relaunch
5. **Check logs:** Look for errors in Claude Desktop developer console

### Server starts but tools not available
- Look for the hammer icon in Claude Desktop chat interface
- Server must successfully connect (check for errors in terminal)
- Try manually running: `python demo_server.py` to see startup messages

## Notes for Presenter

- **Timing**: Practice to keep it under 5 minutes
- **Backup**: Have screenshots ready if live demo has issues
- **Questions**: Be ready to show the source code on request
- **Transition**: After demo, move to CV-Forge as "more complex real-world example"

## Additional Resources

- **Official MCP Documentation:** https://modelcontextprotocol.io
- **FastMCP GitHub:** https://github.com/jlowin/fastmcp
- **MCP Specification:** https://spec.modelcontextprotocol.io
- **MCP Servers Registry:** https://github.com/modelcontextprotocol/servers
- **Claude Desktop:** https://claude.ai/download

## Project Structure

```
mcp-demo/
├── demo_server.py           # Main MCP server implementation
├── requirements.txt         # Python dependencies
├── demo.sh                  # Interactive demo launcher (Linux/Mac)
├── claude_desktop_config.json  # Example Claude Desktop config
├── README.md                # This file
├── DEMO_CHEATSHEET.md       # Presentation script with timing
└── .groupcode/              # Code organization metadata
```

## License

MIT License - Feel free to use this as a template for your own MCP servers.

---

**Demo Server Version:** 1.0.0  
**Built with:** FastMCP + Python 3.10+  
**Created for:** MCP Presentations and Learning