Notepad++ MCP Server

# 🔧 FastMCP 2.12 Troubleshooting Guide **Based on Real-World Debugging Experience** **Project**: nest-protect MCP Server **Timeline**: September 17-20, 2025 **Framework**: FastMCP 2.12.3 **Status**: ✅ **PRODUCTION READY** This guide documents the **complete debugging journey** from a broken MCP server to a production-ready system. Use this to troubleshoot similar issues in other MCP projects like avatarmcp, local llms, and tapo. --- ## 🎯 The Journey: From Broken to Production ### **Initial Problem** - ✅ **Symptom**: `ImportError: cannot import name 'Tool' from 'fastmcp'` - ✅ **Impact**: Server wouldn't start at all - ✅ **Root Cause**: FastMCP 2.12 changed the import structure ### **Final Result** - ✅ **Status**: Production-ready server with 20 working tools - ✅ **Performance**: Sub-second response times - ✅ **Integration**: Perfect Claude Desktop compatibility - ✅ **Quality**: Real API integration, no mock data - ✅ **Logging**: Enhanced debugging and monitoring - ✅ **Compatibility**: Pydantic V2 patterns throughout --- ## 🆕 **Latest Fixes (September 20, 2025)** ### **✅ Pydantic V2 Migration Complete** - **Issue**: `PydanticDeprecatedSince20` warnings causing server instability - **Solution**: Updated all models to use `field_validator` and `ConfigDict` - **Impact**: Eliminated deprecation warnings, improved stability ### **✅ Enhanced Logging System** - **Issue**: Difficult to debug server lifecycle and crashes - **Solution**: Comprehensive logging with detailed startup/shutdown tracking - **Impact**: Easy identification of issues and server state ### **✅ Claude Desktop Configuration Fix** - **Issue**: Server disconnecting after a few seconds - **Root Cause**: `--kill` argument hardcoded in `claude_desktop_config.json` - **Solution**: Removed `--kill` from production configuration - **Impact**: Server now stays connected and operational ### **⚠️ CRITICAL: Never Use Print Statements in FastMCP** #### **Stdout vs Stderr Rules** - **Issue**: Server crashes with stdio transport errors - **Root Cause**: `print()` to stdout breaks FastMCP's stdio protocol - **Solution**: Use proper logging calls OR stderr for extra info - **Impact**: Stdio communication remains intact **Code Examples:** ```python import sys # ❌ WRONG - Breaks stdio protocol (stdout) print("Server started") print(f"Error: {error}") # ✅ CORRECT - FastMCP 2.12 compatible (logging) logger.info("Server started") logger.error(f"Error: {error}") # ✅ ACCEPTABLE - Extra debug info (stderr) print("Debug: Processing request...", file=sys.stderr) sys.stderr.write(f"Debug: User ID {user_id}\n") sys.stderr.flush() # Important for immediate output ``` #### **Stderr Usage Guidelines** - **✅ Stderr is safe** for Claude Desktop MCP logs - **✅ Appears in MCP server logs** without breaking protocol - **✅ Use for debugging** and additional information - **✅ Always flush** stderr buffer for immediate output - **❌ Don't overuse** - can clutter logs - **❌ Avoid for normal operation** - use logging instead **Why This Matters**: FastMCP uses stdin/stdout for Claude Desktop communication. Stdout must remain clean for MCP protocol messages, but stderr is available for logging and debugging. --- ## 🆕 **Pydantic V2 Migration Issues** ### **❌ Problem**: `PydanticDeprecatedSince20` Warnings **Symptoms**: ``` PydanticDeprecatedSince20: Pydantic V1 style `@validator` validators are deprecated PydanticDeprecatedSince20: Support for class-based `config` is deprecated PydanticDeprecatedSince20: `json_encoders` is deprecated ``` **Root Cause**: Using Pydantic V1 patterns in V2 environment **✅ SOLUTION - Complete Migration**: #### **1. Update Validators** ```python # ❌ Old (Pydantic V1) from pydantic import BaseModel, validator class MyModel(BaseModel): @validator('field_name') def validate_field(cls, v): return v # ✅ New (Pydantic V2) from pydantic import BaseModel, field_validator class MyModel(BaseModel): @field_validator('field_name') @classmethod def validate_field(cls, v): return v ``` #### **2. Update Config Classes** ```python # ❌ Old (Pydantic V1) class MyModel(BaseModel): class Config: env_prefix = "MY_" json_encoders = {datetime: lambda v: v.isoformat()} # ✅ New (Pydantic V2) from pydantic import ConfigDict class MyModel(BaseModel): model_config = ConfigDict( env_prefix="MY_", json_encoders={datetime: lambda v: v.isoformat()} ) ``` #### **3. Files Updated** - ✅ `src/nest_protect_mcp/models.py` - Main model definitions - ✅ `src/nest_protect_mcp/mcp_compliant_server.py` - Server models - ✅ `src/nest_protect_mcp/state_manager.py` - State management models **Impact**: Eliminated all deprecation warnings, improved server stability --- ## 🐛 Common FastMCP 2.12 Issues & Solutions ### **1. Import Errors - The Starting Point** #### **❌ Problem**: `ImportError: cannot import name 'Tool' from 'fastmcp'` **What we tried first (WRONG)**: ```python from fastmcp import FastMCP, Tool # ❌ This doesn't work in 2.12 ``` **✅ SOLUTION**: ```python from fastmcp import FastMCP from fastmcp.tools import Tool # ✅ Tool moved to separate module ``` **Files affected**: `server.py`, `mcp_compliant_server.py`, `mcp_server.py` #### **❌ Problem**: `TypeError: FastMCP.__init__() got an unexpected keyword argument 'description'` **What we tried first (WRONG)**: ```python app = FastMCP("nest-protect", description="...") # ❌ Parameter renamed ``` **✅ SOLUTION**: ```python app = FastMCP("nest-protect", instructions="...") # ✅ Use 'instructions' instead ``` --- ### **2. Tool Registration - The Core Challenge** #### **❌ Problem**: Tools not showing up in Claude Desktop **What we tried first (WRONG)**: ```python # Old pattern - separate tool registry self._tool_registry = ToolRegistry() # ❌ Not needed in 2.12 @tool # ❌ Decorator from custom module def my_tool(): pass ``` **✅ SOLUTION - The FastMCP 2.12 Way**: ```python app = FastMCP("server-name") @app.tool() # ✅ Use app.tool() decorator async def my_tool() -> Dict[str, Any]: """Tool description here.""" return {"result": "data"} # That's it! No manual registration needed ``` **Key insight**: FastMCP 2.12 handles tool registration automatically when you use `@app.tool()`. --- ### **3. Server Startup - Getting It Right** #### **❌ Problem**: Various server startup errors **What we tried first (WRONG)**: ```python # Complex server setup server = NestProtectMCP() server_task = asyncio.create_task(server.start_stdio()) # ❌ Old API ``` **✅ SOLUTION**: ```python app = FastMCP("server-name") # Register tools with @app.tool() @app.tool() async def some_tool(): return {"status": "ok"} # Simple startup if __name__ == "__main__": app.run() # ✅ That's it! ``` **Key insight**: Don't overcomplicate it. FastMCP 2.12 handles the complexity for you. --- ### **4. Pydantic Model Integration** #### **❌ Problem**: Parameter validation not working **What we tried first (WRONG)**: ```python @app.tool(parameters=SomeModel) # ❌ Wrong parameter name async def tool_func(data: dict): pass ``` **✅ SOLUTION**: ```python class ToolParams(BaseModel): device_id: str = Field(..., description="Device identifier") timeout: int = Field(30, description="Timeout in seconds") @app.tool() async def tool_func(device_id: str, timeout: int = 30) -> Dict[str, Any]: """Tool description.""" # FastMCP automatically validates parameters based on function signature return {"device_id": device_id, "timeout": timeout} ``` **Key insight**: FastMCP 2.12 infers validation from function type hints. Keep it simple! --- ## 🔥 The Claude Desktop "Start & Kill" Mystery ### **🎭 The Behavior** **What You See in Logs**: ``` 2025-09-19T19:52:08.612Z [nest protect] [info] Server started and connected successfully 2025-09-19T19:52:08.760Z [nest protect] [info] Message from client: {"method":"initialize"...} [... 5-10 seconds of normal operation ...] 2025-09-19 21:52:13,700 - nest_protect_mcp - INFO - Kill argument received - exiting gracefully 2025-09-19T19:52:14.266Z [nest protect] [info] Server transport closed 2025-09-19T19:52:14.266Z [nest protect] [error] Server disconnected ``` **What Users Think**: "Claude is randomly killing my server!" ### **🕵️ The Real Cause** **Claude Desktop doesn't randomly kill servers.** Here's what's actually happening: #### **Scenario 1: Import Errors During Tool Loading** ```python # This looks fine at startup... @app.tool() async def my_tool(): from some_module import missing_function # ❌ Import error! return {"result": "ok"} ``` **What happens**: 1. ✅ Server starts successfully 2. ✅ Claude connects and initializes 3. ❌ Claude tries to list tools → import error occurs 4. ❌ Server crashes due to unhandled import error 5. ❌ Claude detects disconnect and sends `--kill` to cleanup #### **Scenario 2: Configuration Validation Errors** ```python # Server starts, but then... def some_tool(): config = ProtectConfig() # ❌ Validation error on missing required fields! ``` **What happens**: 1. ✅ Server starts (no config loaded yet) 2. ✅ Claude connects 3. ❌ Tool execution triggers config validation 4. ❌ Pydantic validation fails → unhandled exception 5. ❌ Server crashes, Claude sends `--kill` #### **Scenario 3: Missing Dependencies in Tool Functions** ```python @app.tool() async def my_tool(): import missing_library # ❌ Library not installed! return {"result": "ok"} ``` ### **🔍 How to Debug the "Start & Kill" Issue** #### **Step 1: Add Comprehensive Logging** ```python import logging import sys # Add this to your main server file logging.basicConfig( level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', handlers=[ logging.StreamHandler(sys.stderr) # ← This appears in Claude Desktop logs! ] ) logger = logging.getLogger(__name__) @app.tool() async def my_tool(): try: logger.info("Tool starting...") # Your tool logic here logger.info("Tool completed successfully") return {"status": "ok"} except Exception as e: logger.error(f"Tool failed: {e}", exc_info=True) raise ``` #### **Step 2: Test Tool Registration** ```python # Add this debug function def test_tool_registration(): """Test that all tools can be imported without errors.""" try: # Import all your tool modules from .tools import device_status, device_control, auth_tools logger.info("All tool modules imported successfully") # Test that required dependencies are available import aiohttp import pydantic logger.info("All dependencies available") except Exception as e: logger.error(f"Tool registration test failed: {e}", exc_info=True) raise # Call this before app.run() if __name__ == "__main__": test_tool_registration() app.run() ``` #### **Step 3: Minimal Reproduction** ```python # Create a minimal server to test from fastmcp import FastMCP app = FastMCP("test-server") @app.tool() async def hello_world() -> dict: """Simple test tool.""" return {"message": "Hello, World!"} if __name__ == "__main__": app.run() ``` If this works but your full server doesn't, you have an issue in your tool implementations. --- ## 🔧 Specific Fixes We Applied ### **Fix 1: State Manager Import Errors** #### **❌ Problem**: ```python # state_manager.py was missing imports def get_app_state(): import time # ❌ Import inside function import os # ❌ These should be at module level ``` #### **✅ Solution**: ```python # Put imports at the top of the file import time import os from typing import Optional from pydantic import BaseModel def get_app_state(): # Now the imports are available return app_state ``` ### **Fix 2: Module-Level Server Instantiation** #### **❌ Problem**: ```python # server.py server = NestProtectMCP() # ❌ Instantiated at import time → validation errors ``` #### **✅ Solution**: ```python # server.py server = None # ✅ Defer instantiation def create_server(): global server if server is None: server = NestProtectMCP() return server ``` ### **Fix 3: Async Function Confusion** #### **❌ Problem**: ```python # __main__.py async def main(): # ❌ Made it async but app.run() is blocking app.run() asyncio.run(main()) # ❌ This creates issues ``` #### **✅ Solution**: ```python # __main__.py def main(): # ✅ Keep it simple and synchronous app.run() # ✅ This is blocking and handles its own event loop if __name__ == "__main__": main() # ✅ Direct call ``` ### **Fix 4: Tool Function Imports** #### **❌ Problem**: ```python @app.tool() async def list_devices(): from .tools.device_status import list_devices as tool_func # ❌ Import inside tool return await tool_func() ``` This worked but created issues with tool discovery. #### **✅ Solution**: ```python # Import at module level from .tools.device_status import list_devices as device_list_func @app.tool() async def list_devices(): return await device_list_func() # ✅ Clean function call ``` --- ## 🎯 Debugging Checklist for Other MCP Projects ### **Phase 1: Import & Startup Issues** - [ ] **Check imports**: Is `Tool` imported from `fastmcp.tools`? - [ ] **Check constructor**: Using `instructions` instead of `description`? - [ ] **Check dependencies**: Are all imports at module level? - [ ] **Test minimal server**: Does a simple "hello world" tool work? ### **Phase 2: Tool Registration Issues** - [ ] **Using `@app.tool()`**: Not custom decorators or manual registration? - [ ] **Function signatures**: Proper type hints for parameters? - [ ] **Return types**: All tools return `Dict[str, Any]` or similar? - [ ] **Async consistency**: All tools marked `async` if they do I/O? ### **Phase 3: Runtime Issues** - [ ] **Error handling**: Try/catch blocks in tool functions? - [ ] **Logging setup**: stderr logging for Claude Desktop visibility? - [ ] **State management**: No circular imports or initialization issues? - [ ] **Dependencies**: All required packages installed and importable? ### **Phase 4: Claude Desktop Integration** - [ ] **STDIO transport**: Not trying to use WebSocket or HTTP? - [ ] **Entry point**: Correct command in Claude Desktop config? - [ ] **Working directory**: Path accessible and correct? - [ ] **Environment variables**: All required config available? --- ## 🚀 Pro Tips from Our Experience ### **1. Start Simple, Add Complexity Gradually** ```python # Step 1: Get this working first @app.tool() async def test_tool() -> dict: return {"status": "working"} # Step 2: Add real functionality @app.tool() async def real_tool(param: str) -> dict: # Your actual logic here return {"result": param} ``` ### **2. Use Comprehensive Error Handling** ```python @app.tool() async def robust_tool(device_id: str) -> dict: try: # Your tool logic result = await some_api_call(device_id) return {"success": True, "data": result} except aiohttp.ClientError as e: return {"success": False, "error": f"Network error: {e}"} except ValidationError as e: return {"success": False, "error": f"Invalid input: {e}"} except Exception as e: logger.error(f"Unexpected error in tool: {e}", exc_info=True) return {"success": False, "error": "Internal server error"} ``` ### **3. Validate Your Tool Chain** ```python # Add this test function to validate everything works async def validate_all_tools(): """Test that all tools can be called without errors.""" tools = [ ("test_tool", {}), ("real_tool", {"param": "test"}), ] for tool_name, params in tools: try: result = await globals()[tool_name](**params) print(f"✅ {tool_name}: {result}") except Exception as e: print(f"❌ {tool_name}: {e}") raise ``` ### **4. Monitor Claude Desktop Logs** - Look for stderr output in Claude Desktop logs - Watch for the 5-10 second pattern (startup → kill) - Pay attention to the last successful operation before disconnect --- ## 🏆 Success Patterns ### **What Works Reliably** 1. **Simple FastMCP Pattern**: ```python app = FastMCP("name") @app.tool() async def tool() -> dict: return {"result": "data"} app.run() ``` 2. **Clean State Management**: ```python # Global state object app_state = AppState() def get_app_state() -> AppState: return app_state ``` 3. **Module-Level Imports**: ```python # At top of file import aiohttp import pydantic from typing import Dict, Any # Not inside functions ``` 4. **Robust Error Handling**: ```python try: # Operation pass except SpecificError: # Handle specific case pass except Exception as e: logger.error("Unexpected error", exc_info=True) return {"error": str(e)} ``` ### **What Breaks Reliably** 1. **Complex server inheritance and custom MCP handling** 2. **Import errors inside tool functions** 3. **Module-level object instantiation with validation** 4. **Missing error handling in async functions** 5. **Circular imports between modules** --- ## 📞 Quick Fixes for Common Projects ### **For avatarmcp** - Check if using FastMCP 2.12 import pattern - Verify avatar generation dependencies are installed - Add error handling for image processing failures ### **For local llms** - Ensure model loading doesn't happen at import time - Add timeout handling for slow model responses - Check memory usage doesn't cause crashes ### **For tapo** - Verify network connectivity to devices - Add retry logic for device communication - Handle device discovery failures gracefully --- ## 🎯 Final Advice **The key insight**: Claude Desktop doesn't kill servers randomly. It kills them because they crash during normal operation, usually during tool discovery or execution. The "start and kill after a few seconds" pattern almost always indicates: 1. **Import errors** when tools are loaded 2. **Validation errors** when configuration is accessed 3. **Missing dependencies** when tools try to execute 4. **Unhandled exceptions** in async functions **Debug strategy**: Start with the minimal working example and add complexity gradually. Use comprehensive logging and error handling throughout. **Remember**: FastMCP 2.12 is designed to be simple. If you're fighting the framework, you're probably doing it wrong. 🔧✨