Portable MCP Toolkit

# Windows MCP Fix - Implementation Summary ## Changes Applied ### 1. Enhanced Server Error Handling (`mcp_intelligence_server.py`) **Added:** - Platform detection (`platform.system()`) - Windows-specific warnings and guidance - Comprehensive error handling with full traceback - Exit codes for proper error reporting - Better logging for diagnostic purposes **Key improvements:** ```python # Now includes: - Platform information in startup logs - Windows-specific warnings - Try-catch around mcp.run() with detailed error messages - Exit code 1 on failure (helps Cursor detect issues) ``` ### 2. Configuration Examples (`.cursor/`) **Created three example configurations:** 1. **`mcp.json.example`** - cmd /c wrapper (RECOMMENDED) - Fastest fix for Windows STDIO issues - Works immediately without additional setup 2. **`mcp.json.example.virtualenv`** - Full Python path - For users with virtual environments - More reliable than system Python 3. **`mcp.json.example.uv`** - uv package manager - Modern approach recommended by FastMCP - Better dependency management **Usage:** ```powershell # Copy the appropriate example to mcp.json Copy-Item .cursor\mcp.json.example .cursor\mcp.json # Edit and update paths as needed notepad .cursor\mcp.json ``` ### 3. Comprehensive Documentation **Created `docs/troubleshooting/WINDOWS_MCP_FIX.md`:** - Root cause analysis - Three proven solutions with explanations - Diagnostic steps - Verification procedures - Known issue references **Updated `README.md`:** - Added prominent Windows troubleshooting section - Links to detailed fix guide ## How to Use ### Quick Start (Recommended) 1. **Copy the example config:** ```powershell Copy-Item .cursor\mcp.json.example .cursor\mcp.json ``` 2. **Edit `.cursor/mcp.json` and update paths:** - Change `C:\\AIStack-MCP\\` to your actual installation path - Update workspace path if needed 3. **Restart Cursor completely** 4. **Verify it works:** - Open a workspace - Check if MCP tools appear in AI chat - Try using `semantic_search` tool ### If It Still Doesn't Work 1. **Test server directly:** ```powershell python mcp_intelligence_server.py --workspace C:\YourWorkspace ``` - If this fails, fix errors before configuring Cursor 2. **Check Cursor logs:** - Help → Toggle Developer Tools → Console - Filter for "code-intelligence" or "mcp" 3. **Try alternative solutions:** - Use virtualenv config (`.cursor/mcp.json.example.virtualenv`) - Use uv config (`.cursor/mcp.json.example.uv`) ## Technical Details ### Why cmd /c Works Windows requires a command interpreter to properly initialize STDIO pipes for child processes. When Cursor launches Python directly, the STDIO pipes fail to initialize correctly, causing: - FastMCP to hang waiting for handshake - Cursor to timeout and crash - Silent failures with no error messages Using `cmd /c`: - Launches cmd.exe as parent process - cmd.exe properly initializes STDIO pipes - Python runs as child with working pipes - MCP handshake completes successfully ### Error Handling Improvements The server now: - Detects Windows platform and warns users - Catches all exceptions with full traceback - Provides Windows-specific troubleshooting hints - Exits with proper error codes - Logs comprehensive diagnostic information ## Files Modified 1. `mcp_intelligence_server.py` - Added error handling and Windows detection 2. `README.md` - Added Windows troubleshooting section 3. `.cursor/mcp.json.example` - cmd /c wrapper config 4. `.cursor/mcp.json.example.virtualenv` - Virtualenv config 5. `.cursor/mcp.json.example.uv` - uv config 6. `docs/troubleshooting/WINDOWS_MCP_FIX.md` - Complete fix guide ## Next Steps 1. **Test the fix** with your Cursor installation 2. **Report results** - does cmd /c wrapper work? 3. **Update paths** in example configs if needed 4. **Share feedback** on which solution works best ## References - [FastMCP GitHub](https://github.com/jlowin/fastmcp) - [MCP Protocol Documentation](https://modelcontextprotocol.io) - [Cursor Forum - Windows Issues](https://forum.cursor.com)