Notepad++ MCP Server

# 🔍 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! 🔧🎯