@hybridlabor-api/aos 4.3.0 → 4.4.0

package/mcps/windows-computer-use-mcp/docs/_stale/development/archive/DEBUGGING_LESSONS_LEARNED.md

@@ -1,635 +0,0 @@
-> **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!** 🔧✨