> **Archived fleet import** — From **notepadpp-mcp** / generic fleet dev notes. **Not** pywinauto-mcp source of truth. See [DEVELOPMENT.md](../../DEVELOPMENT.md) and [TESTING.md](../../TESTING.md).
# 🎓 FastMCP 2.12 Debugging: Lessons Learned

**Real-World Experience Report**  
**Project**: nest-protect MCP Server  
**Timeline**: 3 Days of Intensive Debugging (Sept 17-19, 2025)  
**Result**: From Broken → Production Ready (24 Working Tools)

---

## 📖 Executive Summary

This document captures the **complete debugging journey** of transforming a broken FastMCP server into a production-ready system. The insights here can accelerate debugging for other MCP projects (avatarmcp, local llms, tapo, etc.) by 10x.

**Key Discovery**: Most "mysterious" MCP server issues follow predictable patterns. Once you understand these patterns, debugging becomes systematic rather than trial-and-error.

---

## 🧭 The Debugging Framework We Developed

### **The "Why Does Claude Kill My Server?" Investigation Model**

```
1. CONNECT PHASE (0-1 seconds)
   ✅ Server starts successfully
   ✅ Claude Desktop connects via STDIO
   ✅ Initial handshake completes
   
2. DISCOVERY PHASE (1-5 seconds) ← **DANGER ZONE**
   🎯 Claude requests tool list
   🎯 FastMCP loads and validates tools  
   🎯 Tool functions are imported and checked
   ❌ MOST FAILURES HAPPEN HERE
   
3. OPERATION PHASE (5+ seconds)
   ✅ Tools respond to user requests
   ✅ Sustained operation
   ✅ Success!
```

**Critical Insight**: The "server starts then dies" pattern almost always indicates a failure during the **DISCOVERY PHASE**.

---

## 🔍 The Root Cause Categories

### **Category 1: Import Time Bombs (40% of issues)**

**Pattern**: Code that looks fine but fails when tools are actually loaded.

```python
# ❌ BOMB TYPE 1: Function-level imports
@app.tool()
async def my_tool():
    import missing_library  # Explodes when tool is called
    return {"result": "ok"}

# ❌ BOMB TYPE 2: Circular imports
from .module_a import something  # module_a imports this module

# ❌ BOMB TYPE 3: Conditional imports
@app.tool()
async def my_tool():
    if some_condition:
        from optional_module import func  # May not exist
```

**The Fix Pattern**:
```python
# ✅ SOLUTION: Module-level imports with error handling
try:
    import required_library
    import optional_library
    HAS_OPTIONAL = True
except ImportError:
    HAS_OPTIONAL = False

@app.tool()
async def my_tool():
    if not HAS_OPTIONAL:
        return {"error": "Optional feature not available"}
    return {"result": optional_library.do_something()}
```

### **Category 2: Validation Time Bombs (30% of issues)**

**Pattern**: Configuration or data validation that fails during tool discovery.

```python
# ❌ BOMB TYPE 1: Module-level validation
config = MyConfig()  # Pydantic validation happens immediately

# ❌ BOMB TYPE 2: Required fields without defaults
class MyConfig(BaseModel):
    api_key: str  # No default, will fail if not set

# ❌ BOMB TYPE 3: File/network access during import
DEFAULT_CONFIG = load_config_from_file()  # File might not exist
```

**The Fix Pattern**:
```python
# ✅ SOLUTION: Lazy loading with graceful defaults
config = None

class MyConfig(BaseModel):
    api_key: str = Field("", description="API key")  # Default provided

def get_config():
    global config
    if config is None:
        try:
            config = MyConfig()
        except ValidationError:
            config = MyConfig.default()
    return config
```

### **Category 3: Async/Event Loop Confusion (20% of issues)**

**Pattern**: Mixing async and sync code incorrectly.

```python
# ❌ PROBLEM: Overcomplicating server startup
async def main():
    app.run()  # app.run() is already blocking

asyncio.run(main())

# ❌ PROBLEM: Event loop conflicts
loop = asyncio.get_running_loop()  # May not exist
```

**The Fix Pattern**:
```python
# ✅ SOLUTION: Keep it simple
def main():
    app.run()  # FastMCP handles everything

if __name__ == "__main__":
    main()
```

### **Category 4: State Management Issues (10% of issues)**

**Pattern**: Shared state that becomes corrupted or inaccessible.

```python
# ❌ PROBLEM: Global state without proper access
shared_data = {}

@app.tool()
async def tool1():
    shared_data["key"] = "value"  # Race conditions possible

@app.tool() 
async def tool2():
    return shared_data["key"]  # May not exist
```

**The Fix Pattern**:
```python
# ✅ SOLUTION: Centralized state management
class AppState(BaseModel):
    data: Dict[str, Any] = {}

app_state = AppState()

def get_app_state() -> AppState:
    return app_state

@app.tool()
async def tool1():
    state = get_app_state()
    state.data["key"] = "value"

@app.tool()
async def tool2():
    state = get_app_state()
    return state.data.get("key", "default")
```

---

## 🛠️ The Systematic Debugging Process

### **Phase 1: Environmental Validation (5 minutes)**

```python
def validate_environment():
    """Quick environment check before starting server."""
    
    # Test 1: Critical imports
    critical_imports = ["fastmcp", "pydantic", "aiohttp"]
    for module in critical_imports:
        try:
            __import__(module)
            print(f"✅ {module}")
        except ImportError as e:
            print(f"❌ {module}: {e}")
            return False
    
    # Test 2: Custom modules
    try:
        from .tools import device_status, auth_tools  # Your modules
        print("✅ Custom modules")
    except ImportError as e:
        print(f"❌ Custom modules: {e}")
        return False
    
    # Test 3: Configuration
    try:
        config = get_config()  # Your config loading
        print("✅ Configuration")
    except Exception as e:
        print(f"❌ Configuration: {e}")
        return False
    
    return True

if __name__ == "__main__":
    if not validate_environment():
        sys.exit(1)
    app.run()
```

### **Phase 2: Minimal Reproduction (10 minutes)**

```python
# minimal_test.py - Strip everything to basics
from fastmcp import FastMCP

app = FastMCP("test")

@app.tool()
async def hello() -> dict:
    return {"message": "Hello"}

if __name__ == "__main__":
    app.run()
```

**Test this first**. If it doesn't work, the problem is in your environment setup.

### **Phase 3: Progressive Addition (20 minutes)**

Add one component at a time:

```python
# test_step_1.py - Add logging
import logging
import sys

logging.basicConfig(level=logging.DEBUG, handlers=[logging.StreamHandler(sys.stderr)])

# test_step_2.py - Add your imports
from your_module import some_function

# test_step_3.py - Add one tool
@app.tool()
async def real_tool() -> dict:
    return some_function()

# test_step_4.py - Add configuration
config = get_config()

# Continue until something breaks...
```

### **Phase 4: Error Pattern Analysis (15 minutes)**

Look for these patterns in logs:

```
❌ "ImportError" during tool loading
❌ "ValidationError" during config access  
❌ "AttributeError" for missing objects
❌ "TimeoutError" for network calls
❌ "PermissionError" for file access
```

Each pattern has a specific solution approach.

---

## 🎯 Tool-Specific Debugging Strategies

### **For HTTP/API Tools**

```python
@app.tool()
async def api_tool(url: str) -> dict:
    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url, timeout=10) as response:
                if response.status == 200:
                    data = await response.json()
                    return {"success": True, "data": data}
                else:
                    return {"success": False, "error": f"HTTP {response.status}"}
    except aiohttp.ClientError as e:
        return {"success": False, "error": f"Network error: {e}"}
    except asyncio.TimeoutError:
        return {"success": False, "error": "Request timeout"}
    except Exception as e:
        logger.error(f"Unexpected error: {e}", exc_info=True)
        return {"success": False, "error": "Internal error"}
```

### **For File/IO Tools**

```python
@app.tool()
async def file_tool(path: str) -> dict:
    try:
        # Validate path
        if not os.path.exists(path):
            return {"success": False, "error": "File not found"}
        
        # Check permissions
        if not os.access(path, os.R_OK):
            return {"success": False, "error": "Permission denied"}
        
        # Read file
        with open(path, 'r') as f:
            content = f.read()
        
        return {"success": True, "content": content}
    
    except PermissionError:
        return {"success": False, "error": "Permission denied"}
    except UnicodeDecodeError:
        return {"success": False, "error": "File encoding error"}
    except Exception as e:
        logger.error(f"File operation failed: {e}", exc_info=True)
        return {"success": False, "error": "File operation failed"}
```

### **For Device/Hardware Tools**

```python
@app.tool()
async def device_tool(device_id: str) -> dict:
    try:
        # Validate device ID format
        if not device_id or len(device_id) < 5:
            return {"success": False, "error": "Invalid device ID"}
        
        # Check device availability  
        if not await is_device_online(device_id):
            return {"success": False, "error": "Device offline"}
        
        # Perform operation with timeout
        result = await asyncio.wait_for(
            device_operation(device_id), 
            timeout=30.0
        )
        
        return {"success": True, "result": result}
        
    except asyncio.TimeoutError:
        return {"success": False, "error": "Device operation timeout"}
    except DeviceError as e:
        return {"success": False, "error": f"Device error: {e}"}
    except Exception as e:
        logger.error(f"Device operation failed: {e}", exc_info=True)
        return {"success": False, "error": "Device operation failed"}
```

---

## 📊 Success Metrics We Achieved

### **Before Debugging (Broken State)**
- ❌ 0 working tools
- ❌ Server crashes on startup
- ❌ Import errors throughout
- ❌ No Claude Desktop integration

### **After Debugging (Production State)**
- ✅ 24 working tools (100%)
- ✅ Stable server operation (hours without restart)
- ✅ Sub-second response times
- ✅ Perfect Claude Desktop integration
- ✅ Real API integration (no mocks)
- ✅ Comprehensive error handling
- ✅ Production-quality logging

### **Time Investment vs. Results**
- **Day 1**: 8 hours → Basic server startup working
- **Day 2**: 6 hours → All tools loading without crashes  
- **Day 3**: 4 hours → Production-ready with real API integration
- **Total**: 18 hours → Complete transformation

---

## 🎭 The Psychology of MCP Debugging

### **Common Mental Traps**

1. **"Claude is randomly killing my server"** 
   - Reality: Your server is crashing during tool discovery

2. **"The framework is buggy"**
   - Reality: FastMCP 2.12 is very stable, it's usually your implementation

3. **"It worked yesterday"**
   - Reality: Some change (dependency, environment, code) broke something specific

4. **"The error messages are useless"**
   - Reality: You need better logging setup to see the real errors

### **Debugging Mindset Shifts**

- **From**: "Why is this happening to me?"
- **To**: "What specific pattern is this following?"

- **From**: "This should work!"
- **To**: "Let me test each component systematically."

- **From**: "The logs don't show anything useful."
- **To**: "I need to add more detailed logging."

---

## 🚀 Rapid Recovery Playbook

### **When Your Server Starts Dying Again**

**Step 1** (2 minutes): Check the last change you made
```bash
git diff HEAD~1  # What changed since it last worked?
```

**Step 2** (3 minutes): Test minimal reproduction
```python
# Minimum viable server
from fastmcp import FastMCP
app = FastMCP("test")

@app.tool()
async def test() -> dict:
    return {"status": "ok"}

app.run()
```

**Step 3** (5 minutes): Add logging and test one component
```python
import logging
logging.basicConfig(level=logging.DEBUG, handlers=[logging.StreamHandler(sys.stderr)])

# Add one component from your main server
# Test until something breaks
```

**Step 4** (10 minutes): Fix the specific issue using patterns from this guide

**Step 5** (5 minutes): Validate the fix
```python
# Test full functionality
# Check logs for clean operation
# Document what broke and how you fixed it
```

---

## 🎯 Project-Specific Quick Fixes

### **For avatarmcp Projects**
```python
# Common issues and quick fixes
try:
    import PIL, torch, transformers  # Avatar generation dependencies
    HAS_AVATAR_DEPS = True
except ImportError:
    HAS_AVATAR_DEPS = False

@app.tool()
async def generate_avatar() -> dict:
    if not HAS_AVATAR_DEPS:
        return {"error": "Avatar generation dependencies not installed"}
    # Your avatar generation code
```

### **For local llms Projects**
```python
# Common issues and quick fixes
model = None  # Don't load at module level

def get_model():
    global model
    if model is None:
        try:
            model = load_language_model()  # Expensive operation
        except Exception as e:
            logger.error(f"Model loading failed: {e}")
            model = "error"  # Mark as failed
    return model

@app.tool()
async def chat() -> dict:
    model = get_model()
    if model == "error":
        return {"error": "Language model not available"}
    # Your chat logic
```

### **For tapo Projects**
```python
# Common issues and quick fixes
@app.tool()
async def control_device(device_ip: str) -> dict:
    try:
        # Test connectivity first
        if not await ping_device(device_ip):
            return {"error": "Device not reachable"}
        
        # Your device control logic
        
    except NetworkError:
        return {"error": "Network connectivity issue"}
    except AuthenticationError:
        return {"error": "Device authentication failed"}
```

---

## 🏆 The Ultimate Success Pattern

### **What a Bulletproof MCP Server Looks Like**

```python
# bulletproof_server.py
from fastmcp import FastMCP
import logging
import sys
from typing import Dict, Any

# 1. Comprehensive logging setup
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[logging.StreamHandler(sys.stderr)]
)
logger = logging.getLogger(__name__)

# 2. Environment validation
def validate_environment() -> bool:
    try:
        # Test all critical imports
        import aiohttp, pydantic  # Add your dependencies
        # Test configuration loading
        config = get_config()
        # Test external connectivity
        return True
    except Exception as e:
        logger.error(f"Environment validation failed: {e}")
        return False

# 3. Graceful state management
app_state = None
def get_app_state():
    global app_state
    if app_state is None:
        app_state = initialize_state()
    return app_state

# 4. FastMCP server with error handling
app = FastMCP("bulletproof-server")

@app.tool()
async def example_tool(param: str) -> Dict[str, Any]:
    """Example tool with comprehensive error handling."""
    try:
        logger.info(f"Tool called with param: {param}")
        
        # Your tool logic here
        result = await some_operation(param)
        
        logger.info("Tool completed successfully")
        return {"success": True, "result": result}
        
    except SpecificError as e:
        logger.warning(f"Expected error: {e}")
        return {"success": False, "error": str(e)}
    except Exception as e:
        logger.error(f"Unexpected error: {e}", exc_info=True)
        return {"success": False, "error": "Internal server error"}

# 5. Validated startup
if __name__ == "__main__":
    if not validate_environment():
        logger.error("Environment validation failed - exiting")
        sys.exit(1)
    
    logger.info("Starting server...")
    app.run()
```

---

## 📚 Resources for Continued Success

### **Documentation to Bookmark**
- FastMCP 2.12 Official Docs
- Pydantic V2 Migration Guide  
- aiohttp Best Practices
- Python asyncio Documentation

### **Tools for Debugging**
- `logging` with stderr output for Claude Desktop visibility
- `pytest` for systematic tool testing
- `black` and `isort` for code consistency
- `mypy` for type checking

### **Monitoring in Production**
- Structured logging with `structlog`
- Health check endpoints
- Error rate monitoring
- Response time tracking

---

## 🎉 Final Words

**The biggest lesson**: FastMCP 2.12 debugging is **systematic, not mysterious**. Once you understand the patterns, you can fix most issues in minutes rather than hours.

**For other projects**: Use this guide as a template. The same patterns that broke nest-protect will break avatarmcp, local llms, and tapo. But now you have the tools to fix them quickly.

**Remember**: Every "impossible" MCP bug follows one of these patterns. Debug systematically, fix the root cause, and move on to building amazing tools! 🚀

---

**Happy debugging!** 🔧✨