@hybridlabor-api/aos 4.3.0 → 4.4.0

package/mcps/windows-computer-use-mcp/docs/_stale/mcp-technical/CLAUDE_DESKTOP_DEBUGGING.md

@@ -1,561 +0,0 @@
-# 🔍 Claude Desktop MCP Server Debugging Guide
-
-**The Mystery of "Server Starts, Then Dies"**  
-**Real-World Debugging Experience from nest-protect MCP**
-
----
-
-## 🎭 The Mysterious Behavior
-
-### **What Users Experience**
-
-You see this pattern in Claude Desktop logs:
-```
-2025-09-19T19:52:08.612Z [your-server] [info] Server started and connected successfully
-2025-09-19T19:52:08.760Z [your-server] [info] Message from client: {"method":"initialize"...}
-[... normal operation for 5-10 seconds ...]
-2025-09-19 21:52:13,700 - your_server - INFO - Kill argument received - exiting gracefully  
-2025-09-19T19:52:14.266Z [your-server] [info] Server transport closed
-2025-09-19T19:52:14.266Z [your-server] [error] Server disconnected
-```
-
-### **What Users Think**
-- "Claude is randomly killing my server!"
-- "The connection is unstable!"  
-- "Something is wrong with my Claude Desktop installation!"
-
-### **The Reality**
-**Claude Desktop NEVER randomly kills servers.** The `--kill` signal is always a response to the server crashing or becoming unresponsive during normal operation.
-
----
-
-## 🕵️ The Investigation Process
-
-### **Step 1: Understanding the Timeline**
-
-```
-T+0s:    Server process starts
-T+0.1s:  Claude Desktop connects via STDIO
-T+0.2s:  Initial handshake (method: "initialize")
-T+0.3s:  Claude Desktop requests tool list (method: "tools/list")  ← **CRITICAL MOMENT**
-T+0.5s:  Tool discovery and validation happens
-T+?s:    Something crashes during tool loading/validation
-T+5-10s: Claude Desktop detects server is unresponsive
-T+10s:   Claude Desktop sends --kill to cleanup zombie process
-```
-
-**The crash usually happens at the "CRITICAL MOMENT" - during tool discovery.**
-
-### **Step 2: The Real Culprits**
-
-#### **Culprit #1: Import Errors During Tool Loading**
-
-**The Trap**:
-```python
-# This looks innocent but is a time bomb
-@app.tool()
-async def my_tool():
-    from some_module import missing_function  # ❌ Import happens when tool is called
-    return {"result": "ok"}
-```
-
-**What happens**:
-1. ✅ Server starts (import not triggered yet)
-2. ✅ Claude connects successfully
-3. ✅ Tool registration appears to work
-4. ❌ Claude tries to validate tools → import error!
-5. ❌ Unhandled ImportError crashes the server
-6. ❌ Claude detects dead server, sends --kill
-
-**The Fix**:
-```python
-# Import at module level
-from some_module import missing_function
-
-@app.tool()
-async def my_tool():
-    return {"result": missing_function()}  # ✅ Import already validated
-```
-
-#### **Culprit #2: Configuration Validation Bombs**
-
-**The Trap**:
-```python
-# Module-level instantiation with validation
-config = MyConfig()  # ❌ Validates immediately on import
-
-@app.tool()
-async def my_tool():
-    value = config.some_field  # ❌ If config validation failed, this crashes
-    return {"result": value}
-```
-
-**What happens**:
-1. ✅ Server starts (but config validation might fail silently)
-2. ✅ Claude connects
-3. ❌ Tool access triggers Pydantic validation error
-4. ❌ ValidationError crashes the server
-5. ❌ Claude sends --kill
-
-**The Fix**:
-```python
-config = None  # ✅ Defer instantiation
-
-def get_config():
-    global config
-    if config is None:
-        try:
-            config = MyConfig()
-        except ValidationError as e:
-            # Handle gracefully
-            config = MyConfig.default()
-    return config
-
-@app.tool()
-async def my_tool():
-    cfg = get_config()
-    return {"result": cfg.some_field}
-```
-
-#### **Culprit #3: Missing Dependencies in Tool Functions**
-
-**The Trap**:
-```python
-@app.tool()
-async def network_tool():
-    import aiohttp  # ❌ What if aiohttp isn't installed?
-    async with aiohttp.ClientSession() as session:
-        # ...
-```
-
-**The Fix**:
-```python
-# Test imports at startup
-try:
-    import aiohttp
-    import requests
-    # ... other dependencies
-except ImportError as e:
-    print(f"Missing dependency: {e}", file=sys.stderr)
-    sys.exit(1)
-
-@app.tool()
-async def network_tool():
-    # ✅ We know aiohttp is available
-    async with aiohttp.ClientSession() as session:
-        # ...
-```
-
----
-
-## 🔬 Debugging Techniques
-
-### **Technique 1: Comprehensive Logging**
-
-```python
-import logging
-import sys
-
-# Set up logging that appears in Claude Desktop logs
-logging.basicConfig(
-    level=logging.DEBUG,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-    handlers=[
-        logging.StreamHandler(sys.stderr),  # ← This is key!
-        logging.FileHandler('debug.log')    # ← Also save to file
-    ]
-)
-
-logger = logging.getLogger(__name__)
-
-@app.tool()
-async def my_tool():
-    logger.info("Tool called - starting execution")
-    try:
-        # Your logic here
-        result = await some_operation()
-        logger.info(f"Tool completed successfully: {result}")
-        return {"success": True, "result": result}
-    except Exception as e:
-        logger.error(f"Tool failed with exception: {e}", exc_info=True)
-        return {"success": False, "error": str(e)}
-```
-
-### **Technique 2: Startup Validation**
-
-```python
-def validate_environment():
-    """Validate all dependencies and configuration before starting."""
-    logger.info("Starting environment validation...")
-    
-    # Test imports
-    try:
-        import aiohttp
-        import pydantic
-        import your_custom_module
-        logger.info("✅ All imports successful")
-    except ImportError as e:
-        logger.error(f"❌ Import failed: {e}")
-        raise
-    
-    # Test configuration
-    try:
-        config = MyConfig()
-        logger.info("✅ Configuration validation passed")
-    except Exception as e:
-        logger.error(f"❌ Configuration validation failed: {e}")
-        raise
-    
-    # Test external connections
-    try:
-        # Test API connectivity, file access, etc.
-        logger.info("✅ External dependencies validated")
-    except Exception as e:
-        logger.error(f"❌ External validation failed: {e}")
-        raise
-    
-    logger.info("🎉 Environment validation complete")
-
-if __name__ == "__main__":
-    validate_environment()  # ✅ Fail fast if something is wrong
-    app.run()
-```
-
-### **Technique 3: Tool Function Testing**
-
-```python
-async def test_all_tools():
-    """Test that every tool can be called without import/validation errors."""
-    tools_to_test = [
-        ("tool1", {}),
-        ("tool2", {"param": "test"}),
-        ("tool3", {"device_id": "test-device"}),
-    ]
-    
-    for tool_name, test_params in tools_to_test:
-        try:
-            logger.info(f"Testing tool: {tool_name}")
-            # Get the tool function
-            tool_func = globals().get(tool_name)
-            if tool_func:
-                result = await tool_func(**test_params)
-                logger.info(f"✅ {tool_name}: {result}")
-            else:
-                logger.error(f"❌ {tool_name}: Tool function not found")
-        except Exception as e:
-            logger.error(f"❌ {tool_name}: {e}", exc_info=True)
-            raise  # Fail fast on tool issues
-
-# Call this during development/testing
-# await test_all_tools()
-```
-
-### **Technique 4: Minimal Reproduction**
-
-When debugging, create a minimal version:
-
-```python
-# minimal_server.py
-from fastmcp import FastMCP
-import logging
-import sys
-
-logging.basicConfig(level=logging.DEBUG, handlers=[logging.StreamHandler(sys.stderr)])
-logger = logging.getLogger(__name__)
-
-app = FastMCP("minimal-test")
-
-@app.tool()
-async def hello() -> dict:
-    """Simple test tool."""
-    logger.info("Hello tool called")
-    return {"message": "Hello, World!"}
-
-@app.tool()
-async def test_import() -> dict:
-    """Test importing your problematic module."""
-    try:
-        from your_module import your_function  # ← Test your specific import
-        logger.info("Import successful")
-        return {"status": "import_ok"}
-    except Exception as e:
-        logger.error(f"Import failed: {e}")
-        return {"status": "import_failed", "error": str(e)}
-
-if __name__ == "__main__":
-    logger.info("Starting minimal server...")
-    app.run()
-```
-
-If this works but your main server doesn't, you've isolated the problem to your specific implementation.
-
----
-
-## 🎯 Real Examples from Our Debugging
-
-### **Example 1: The state_manager.py Import Bomb**
-
-**What we had**:
-```python
-# state_manager.py
-def get_app_state():
-    import time  # ❌ This import was failing silently
-    import os
-    # ... rest of function
-```
-
-**The problem**: When tools tried to call `get_app_state()`, the import inside the function failed, but the error wasn't properly handled.
-
-**The symptom**: Server started fine, crashed when first tool was called.
-
-**The fix**:
-```python
-# state_manager.py
-import time  # ✅ Move to top of file
-import os
-from typing import Optional
-
-def get_app_state():
-    # Function body without imports
-```
-
-### **Example 2: The Pydantic Validation Time Bomb**
-
-**What we had**:
-```python
-# models.py
-class ProtectConfig(BaseModel):
-    project_id: str  # ❌ Required field, no default
-    client_id: str   # ❌ Required field, no default
-
-# server.py  
-config = ProtectConfig()  # ❌ Instant validation error if fields missing
-```
-
-**The problem**: Server started, but when tools tried to access config, Pydantic validation failed.
-
-**The fix**:
-```python
-# models.py
-class ProtectConfig(BaseModel):
-    project_id: str = Field("", description="Project ID")  # ✅ Default value
-    client_id: str = Field("", description="Client ID")    # ✅ Default value
-
-# server.py
-config = None  # ✅ Defer instantiation
-
-def get_config():
-    global config
-    if config is None:
-        config = ProtectConfig()  # ✅ Instantiate when needed
-    return config
-```
-
-### **Example 3: The Async/Sync Confusion**
-
-**What we had**:
-```python
-# __main__.py
-async def main():
-    app.run()  # ❌ app.run() is blocking, doesn't need async
-
-asyncio.run(main())  # ❌ Creates event loop conflicts
-```
-
-**The symptom**: Server appeared to start but had weird async behavior issues.
-
-**The fix**:
-```python
-# __main__.py
-def main():  # ✅ Keep it simple
-    app.run()
-
-if __name__ == "__main__":
-    main()  # ✅ Direct call
-```
-
----
-
-## 🚨 Warning Signs to Watch For
-
-### **In Your Code**
-
-- ✅ **Module-level imports** - Good
-- ❌ **Function-level imports** - Danger zone
-- ✅ **Deferred instantiation** - Good
-- ❌ **Module-level object creation with validation** - Danger zone
-- ✅ **Comprehensive error handling** - Good
-- ❌ **Naked try/except or no error handling** - Danger zone
-
-### **In Claude Desktop Logs**
-
-- ✅ **Long-running sessions** - Good
-- ❌ **5-10 second pattern** - Something crashes during tool discovery
-- ✅ **Detailed error messages** - Good
-- ❌ **Generic "Server disconnected"** - Hidden crash, needs better logging
-
-### **In Your Testing**
-
-- ✅ **Tools work individually** - Good
-- ❌ **Tools fail when called from Claude** - Integration issue
-- ✅ **Consistent behavior** - Good
-- ❌ **Intermittent failures** - Timing or state issues
-
----
-
-## 🛠️ Emergency Debugging Kit
-
-### **Quick Diagnostic Server**
-
-```python
-# diagnostic_server.py
-from fastmcp import FastMCP
-import logging
-import sys
-import traceback
-
-logging.basicConfig(level=logging.DEBUG, handlers=[logging.StreamHandler(sys.stderr)])
-logger = logging.getLogger(__name__)
-
-app = FastMCP("diagnostic")
-
-@app.tool()
-async def test_imports() -> dict:
-    """Test all your imports."""
-    results = {}
-    imports_to_test = [
-        "aiohttp",
-        "pydantic", 
-        "your_custom_module",
-        # Add your specific imports here
-    ]
-    
-    for module in imports_to_test:
-        try:
-            __import__(module)
-            results[module] = "✅ OK"
-        except Exception as e:
-            results[module] = f"❌ FAILED: {e}"
-    
-    return {"import_results": results}
-
-@app.tool()
-async def test_config() -> dict:
-    """Test your configuration loading."""
-    try:
-        # Your config loading logic here
-        from your_module import YourConfig
-        config = YourConfig()
-        return {"config_status": "✅ OK", "config": str(config)}
-    except Exception as e:
-        return {"config_status": f"❌ FAILED: {e}", "traceback": traceback.format_exc()}
-
-if __name__ == "__main__":
-    logger.info("Starting diagnostic server...")
-    app.run()
-```
-
-### **Logging Configuration Template**
-
-```python
-import logging
-import sys
-from datetime import datetime
-
-def setup_debug_logging():
-    """Set up comprehensive logging for debugging."""
-    
-    # Create formatter
-    formatter = logging.Formatter(
-        '%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s'
-    )
-    
-    # Console handler (appears in Claude Desktop)
-    console_handler = logging.StreamHandler(sys.stderr)
-    console_handler.setLevel(logging.DEBUG)
-    console_handler.setFormatter(formatter)
-    
-    # File handler (for detailed analysis)
-    file_handler = logging.FileHandler(f'debug_{datetime.now().strftime("%Y%m%d_%H%M%S")}.log')
-    file_handler.setLevel(logging.DEBUG)
-    file_handler.setFormatter(formatter)
-    
-    # Configure root logger
-    root_logger = logging.getLogger()
-    root_logger.setLevel(logging.DEBUG)
-    root_logger.addHandler(console_handler)
-    root_logger.addHandler(file_handler)
-    
-    return logging.getLogger(__name__)
-
-# Use in your server
-logger = setup_debug_logging()
-```
-
----
-
-## 🎯 Action Plan for Troubled Servers
-
-### **Phase 1: Isolate the Problem (15 minutes)**
-
-1. **Create minimal server** with just one simple tool
-2. **Test minimal server** in Claude Desktop
-3. **If minimal works**: Problem is in your tool implementation
-4. **If minimal fails**: Problem is in your environment/setup
-
-### **Phase 2: Add Complexity Gradually (30 minutes)**
-
-1. **Add logging** to your minimal server
-2. **Add one tool at a time** from your main server
-3. **Test after each addition** 
-4. **When it breaks**: You've found the problematic tool
-
-### **Phase 3: Fix the Root Cause (Variable)**
-
-1. **Import issues**: Move imports to module level
-2. **Validation issues**: Add default values or defer instantiation
-3. **Dependency issues**: Add proper error handling
-4. **State issues**: Centralize state management
-
-### **Phase 4: Validate the Fix (10 minutes)**
-
-1. **Test full functionality** in Claude Desktop
-2. **Verify logs show no errors**
-3. **Test edge cases** that previously failed
-4. **Document the fix** for future reference
-
----
-
-## 📚 Resources for Other Projects
-
-### **For avatarmcp Issues**
-- Check image processing library imports
-- Validate model file paths exist
-- Add timeout handling for generation
-- Test with minimal avatar requests first
-
-### **For local llms Issues**  
-- Verify model loading doesn't happen at import time
-- Add memory monitoring for large models
-- Test model inference separately
-- Handle model download/cache issues
-
-### **For tapo Issues**
-- Test device discovery separately 
-- Add network connectivity validation
-- Handle device offline scenarios
-- Test authentication before tool registration
-
----
-
-## 🏆 Success Indicators
-
-**You've fixed the "start and kill" issue when**:
-
-✅ Server runs for minutes/hours without disconnection  
-✅ All tools respond correctly in Claude Desktop  
-✅ Logs show normal operation, not error patterns  
-✅ Tool discovery happens without crashes  
-✅ Error handling gracefully manages edge cases  
-
-**Remember**: Claude Desktop is not the enemy. It's trying to help by cleaning up crashed servers. Fix the crash, and the killing stops! 🔧🎯