# 🦥 Lazy Calculator MCP Server

A **Model Context Protocol (MCP)** server that creates a hilariously wrong calculator - it always doubles the actual answer! Built as a learning exercise for understanding MCP server implementation with Claude Desktop.

## 📋 Table of Contents
- [Overview](#overview)
- [What You'll Learn](#what-youll-learn)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Claude Desktop Configuration](#claude-desktop-configuration)
- [Troubleshooting Guide](#troubleshooting-guide)
- [Developer Cheat Sheet](#developer-cheat-sheet)
- [Architecture Deep Dive](#architecture-deep-dive)
- [Common Issues & Solutions](#common-issues--solutions)

## 🎯 Overview

The Lazy Calculator is an MCP server that:
- Parses natural language math questions
- Calculates the correct answer
- Returns **double** the actual result (because it's "lazy")
- Demonstrates proper MCP server implementation patterns

### Example Usage
- **Input:** "What is 5 + 5?"
- **Output:** "The answer is 20 (definitely not 10... *wink*)"

## 🎓 What You'll Learn

This repository demonstrates:
1. **MCP Server Implementation** - Using the standard MCP SDK (not FastMCP)
2. **Python Virtual Environments** - Required for macOS due to system Python restrictions
3. **Safe Math Expression Evaluation** - Using Python's AST module
4. **Natural Language Processing** - Basic pattern matching for math questions
5. **Claude Desktop Integration** - Proper configuration and debugging

## 📦 Prerequisites

### System Requirements
- **macOS** (tested) or Linux/Windows (may need path adjustments)
- **Python 3.8+** (Python 3.13 tested)
- **Claude Desktop** app installed
- **Homebrew** (for macOS users)

### Required Software
```bash
# Check Python version
python3 --version

# Install Python via Homebrew if needed (macOS)
brew install python@3.13
```

## 🚀 Installation

### Step 1: Clone the Repository
```bash
git clone https://github.com/YOUR_USERNAME/lazy-calculator-mcp.git
cd lazy-calculator-mcp
```

### Step 2: Create Virtual Environment
```bash
# Create virtual environment (REQUIRED on macOS)
python3 -m venv mcp_venv

# Activate the virtual environment
source mcp_venv/bin/activate

# Install dependencies
pip install mcp
```

### Step 3: Make Scripts Executable
```bash
chmod +x lazy_calculator_server.py
chmod +x run_lazy_calculator.sh
```

### Step 4: Update the Wrapper Script
Edit `run_lazy_calculator.sh` and update the path to match your installation:
```bash
#!/bin/bash
cd "/path/to/your/lazy-calculator-mcp"  # UPDATE THIS PATH
source mcp_venv/bin/activate
exec python lazy_calculator_server.py
```

## ⚙️ Claude Desktop Configuration

### Configuration File Location
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

### Add to Configuration
```json
{
  "mcpServers": {
    "lazy-calculator": {
      "command": "/path/to/your/lazy-calculator-mcp/run_lazy_calculator.sh",
      "args": [],
      "env": {}
    }
  }
}
```

**⚠️ IMPORTANT:** Update the path to match where you cloned this repository!

### Restart Claude Desktop
After updating the configuration, completely quit and restart Claude Desktop.

## 🔍 Troubleshooting Guide

### Critical Log File Locations

When debugging MCP servers with Claude Desktop, these are the essential files:

#### 1. Main Application Log
```bash
# macOS
~/Library/Logs/Claude/main.log

# View recent entries
tail -f ~/Library/Logs/Claude/main.log
```

#### 2. MCP Server Specific Log
```bash
# macOS - Each MCP server gets its own log
~/Library/Logs/Claude/mcp-server-lazy-calculator.log

# Monitor in real-time
tail -f ~/Library/Logs/Claude/mcp-server-lazy-calculator.log
```

#### 3. Configuration File
```bash
# View current configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Edit configuration
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

### Common Error Messages & Solutions

#### Error: "spawn python ENOENT"
**Problem:** System can't find `python` command
**Solution:** Use `python3` or full path `/opt/homebrew/bin/python3`

#### Error: "ModuleNotFoundError: No module named 'mcp'"
**Problem:** MCP not installed or wrong Python environment
**Solution:** Ensure virtual environment is activated and mcp is installed

#### Error: "unhandled errors in a TaskGroup"
**Problem:** FastMCP compatibility issue or missing initialization parameters
**Solution:** Use standard MCP SDK with proper `capabilities` field

#### Error: "Extension lazy-calculator not found in installed extensions"
**Problem:** Normal warning - custom servers aren't "extensions"
**Solution:** This can be safely ignored

### Testing Your Server Manually

```bash
# Test the server directly
cd /path/to/lazy-calculator-mcp
source mcp_venv/bin/activate
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}' | python lazy_calculator_server.py
```

Expected response:
```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"lazy-calculator","version":"1.0.0"}}}
```

## 🛠️ Developer Cheat Sheet

### Quick Commands for Claude Code Assistance

When working with Claude Code to debug MCP servers, provide these paths:

```markdown
## Paths for Claude Code Debugging

### View MCP Server Log
/Users/YOUR_USERNAME/Library/Logs/Claude/mcp-server-lazy-calculator.log

### View Main Application Log
/Users/YOUR_USERNAME/Library/Logs/Claude/main.log

### Edit Configuration
/Users/YOUR_USERNAME/Library/Application Support/Claude/claude_desktop_config.json

### Server Location
/path/to/your/lazy-calculator-mcp/lazy_calculator_server.py
```

### Debugging Workflow

1. **Check if server is listed in Claude Desktop**
   - Look for "lazy-calculator" in the MCP servers section

2. **Monitor logs during connection**
   ```bash
   # Terminal 1: Watch main log
   tail -f ~/Library/Logs/Claude/main.log | grep lazy-calculator
   
   # Terminal 2: Watch server log
   tail -f ~/Library/Logs/Claude/mcp-server-lazy-calculator.log
   ```

3. **Test server independently**
   ```bash
   cd /path/to/lazy-calculator-mcp
   ./run_lazy_calculator.sh
   # Should run without errors
   ```

## 🏗️ Architecture Deep Dive

### File Structure
```
lazy-calculator-mcp/
├── lazy_calculator_server.py  # Main MCP server implementation
├── run_lazy_calculator.sh     # Wrapper script for virtual environment
├── requirements.txt           # Python dependencies (just 'mcp')
├── mcp_venv/                 # Virtual environment (created during setup)
└── README.md                 # This file
```

### Key Components

#### 1. **Server Initialization**
```python
from mcp.server import Server
from mcp.server.models import InitializationOptions
from mcp.types import ServerCapabilities

server = Server("lazy-calculator")

# Critical: Must include capabilities field
InitializationOptions(
    server_name="lazy-calculator",
    server_version="1.0.0",
    capabilities=ServerCapabilities(tools={})
)
```

#### 2. **Tool Registration**
```python
@server.list_tools()
async def handle_list_tools() -> list[Tool]:
    return [Tool(...)]

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[TextContent]:
    # Handle tool execution
```

#### 3. **Safe Math Evaluation**
- Uses Python's `ast` module for safe expression parsing
- No `eval()` or `exec()` - prevents code injection
- Whitelist of allowed operations and functions

#### 4. **Natural Language Processing**
- Regex-based pattern matching
- Word-to-number conversion
- Operation keyword detection

### MCP Protocol Flow

1. **Initialize** → Server receives protocol version and capabilities
2. **List Tools** → Server returns available tools
3. **Call Tool** → Server executes requested tool with arguments
4. **Return Result** → Server sends formatted response

## 🐛 Common Issues & Solutions

### Issue 1: Python Path Problems on macOS

**The Journey:**
- macOS uses system Python which is protected
- `pip install` fails with "externally-managed-environment"
- Must use virtual environments

**Solution:**
Always use virtual environment with full path in wrapper script

### Issue 2: FastMCP vs Standard MCP

**The Journey:**
- FastMCP has simpler syntax but caused "TaskGroup" errors
- Standard MCP requires more boilerplate but is more stable

**Solution:**
Use standard MCP SDK with proper initialization

### Issue 3: Configuration Not Taking Effect

**The Journey:**
- Claude Desktop caches configurations
- Hot-reload doesn't always work

**Solution:**
Completely quit Claude Desktop (Cmd+Q) and restart

### Issue 4: Server Connects but Immediately Disconnects

**The Journey:**
- Missing required fields in initialization
- Incorrect protocol version

**Solution:**
Ensure `capabilities` field is included in `InitializationOptions`

## 📝 Lessons Learned

1. **Always use virtual environments on macOS** - System Python is protected
2. **Log files are your best friend** - Check both main.log and server-specific logs
3. **Test servers independently first** - Use echo/pipe to test before Claude Desktop
4. **FastMCP isn't always faster to implement** - Standard SDK is more reliable
5. **Wrapper scripts solve environment issues** - Activate venv before running Python
6. **Configuration requires full restart** - Claude Desktop doesn't hot-reload MCP servers

## 🤝 Contributing

Feel free to submit issues and enhancement requests!

## 📄 License

MIT License - See LICENSE file for details

## 🙏 Acknowledgments

- Built while learning MCP with Claude Code
- Thanks to Anthropic for the MCP protocol
- Inspired by the need to understand MCP server implementation

---

**Remember:** This calculator is intentionally wrong! It's a learning tool, not for actual calculations. 🦥

## Quick Start for Claude Code Users

If you're using Claude Code to work with this repository:

1. **Clone the repo**
2. **Tell Claude Code these paths:**
   ```
   Config: ~/Library/Application Support/Claude/claude_desktop_config.json
   Logs: ~/Library/Logs/Claude/mcp-server-lazy-calculator.log
   ```
3. **Let Claude Code handle the debugging!**