mcp-freecad

# FreeCAD App Crash Fix - Solution Summary ## 🎯 Problems Solved **Issue 1**: Using tools to create shapes and new documents caused the FreeCAD MCP app to crash. **Root Cause 1**: The FreeCAD bridge was executing scripts using `subprocess` with GUI initialization in headless environments, causing crashes when FreeCAD tried to create display contexts that didn't exist. **Issue 2**: Agent Manager and Provider Service not initializing properly, causing cascading failures in the AI components. **Root Cause 2**: Naming mismatches between expected and actual module names, along with import path issues. ## ✅ Solution Implemented ### 1. Enhanced FreeCAD Bridge (`freecad_bridge.py`) - **Headless script wrapper**: All scripts now run with proper headless initialization - **Environment configuration**: Sets `QT_QPA_PLATFORM=offscreen` and virtual display variables - **Improved command execution**: Uses `--console` and `--run-python-script` instead of `-c` - **Timeout protection**: 30-second timeout prevents hanging processes - **Retry mechanisms**: Fallback to older command syntax if newer flags fail ### 2. Robust Connection Management (`freecad_connection_manager.py`) - **Connection validation**: Tests bridge connections with actual operations - **Enhanced error reporting**: Detailed logging of connection failures - **Better bridge testing**: Verifies functionality before marking connections as successful ### 3. Improved Error Handling (`freecad_mcp_server.py`) - **Retry logic**: Up to 3 retry attempts for failed operations - **Enhanced progress reporting**: Better user feedback during operations - **Connection validation**: Checks connections before attempting operations ### 4. Test Suite - **Comprehensive testing**: Multiple test scripts to verify functionality - **AppImage integration**: Specific support for the FreeCAD AppImage in `/data/` - **Error diagnostics**: Detailed error reporting for troubleshooting ## 🛠️ Key Technical Improvements ### Headless Script Wrapper ```python def _wrap_script_for_headless(self, script_content: str) -> str: """Wrap script with proper headless initialization""" wrapper = ''' import os os.environ['QT_QPA_PLATFORM'] = 'offscreen' import FreeCAD FreeCAD.GuiUp = False # User script follows... ''' ``` ### Environment Setup ```python env = { 'DISPLAY': ':99', 'QT_QPA_PLATFORM': 'offscreen', 'FREECAD_USER_HOME': tempfile.gettempdir(), 'XVFB_RUN': '1' } ``` ### Command Execution ```python cmd = [freecad_path, '--console', '--run-python-script', script_file] subprocess.run(cmd, env=env, timeout=30) ``` ### Document Creation Fix ```python # Before: Combined document creation and object creation in single operation doc_creation = ( 'doc = FreeCAD.newDocument("BoxDocument")' if doc_name is None else f'doc = FreeCAD.getDocument("{doc_name}")' ) # After: Separate document creation from object creation # Create document first if needed in a separate operation if doc_name is None: doc_name = self.create_document("BoxDocument") # Use existing document doc_creation = f'doc = FreeCAD.getDocument("{doc_name}")' ``` ### Safe Document Creation Helper ```python def _ensure_document_exists(self, name="Untitled"): """ Ensure a document exists and return it, creating a new one if necessary. This method separates document creation from shape operations to prevent crashes. """ # First check if active document exists doc = App.ActiveDocument if not doc: # Create new document in a separate step doc = App.newDocument(name) # Wait for document to be fully initialized App.setActiveDocument(doc.Name) return doc ``` ### Component Naming Alignment ```python # Creating symbolic links to align naming conventions os.symlink('ai_manager.py', os.path.join(freecad_ai_dir, 'ai', 'agent_manager.py')) os.symlink('provider_integration_service.py', os.path.join(freecad_ai_dir, 'api', 'provider_service.py')) ``` ## 🧪 Testing Run these commands to verify the fixes: ```bash # Test basic functionality python test_basic_bridge.py # Test AppImage integration python test_appimage_integration.py # Comprehensive test suite python test_crash_fixes.py ``` ## 📋 Expected Results ### Before Fix: - ❌ `create_document()` → Crash - ❌ `create_box()` → Crash - ❌ GUI initialization errors → Crash ### After Fix: - ✅ `create_document()` → Success (headless mode) - ✅ `create_box()` → Success (no GUI dependencies) - ✅ Clear error messages instead of crashes - ✅ Automatic retry on temporary failures ## 🎉 Outcome The FreeCAD MCP server now: 1. **Runs stably** without GUI-related crashes 2. **Provides clear error messages** when operations fail 3. **Supports both system FreeCAD and AppImage** installations 4. **Includes retry mechanisms** for improved reliability 5. **Has comprehensive test coverage** for validation Users can now safely use tools to create documents and shapes without experiencing crashes! ## 🔧 Additional Fixes Implemented (June 2025) ### 4. Fixed Connection Bridge (`freecad_connection_bridge.py`) - **Added headless wrapper**: Implemented `_wrap_script_for_headless` method - **Environment setup**: Proper headless environment variables - **Separated document creation**: Document creation is now separate from shape creation - **Improved error handling**: Better timeout and fallback mechanisms ### 5. Enhanced Tool Classes (`primitives.py` and `advanced_primitives.py`) - **Safe document handling**: Added `_ensure_document_exists` helper methods - **Separated operations**: Document creation is separated from shape operations - **Improved initialization**: Documents are properly initialized before shape creation - **Better error handling**: More robust error handling and recovery ### 6. Fixed Component Naming and Initialization - **Agent Manager**: Created symbolic link from `ai_manager.py` to `agent_manager.py` - **Provider Service**: Implemented complete `provider_service.py` in API layer - **Initialization order**: Fixed component initialization sequence - **Import paths**: Resolved import path issues ### 7. Comprehensive Test Suite - **Document creation tests**: Specific tests for document creation scenarios - **Component integration tests**: Tests for agent manager and provider service - **Bridge operation tests**: Tests for bridge functionality - **Error diagnostics**: Detailed error reporting for troubleshooting ## 📊 Complete Results ### Before Complete Fix - ❌ App crashed when creating shapes without documents - ❌ Agent Manager: NOT AVAILABLE - ❌ Provider Service: NOT AVAILABLE - ❌ Tools Registry: NOT AVAILABLE ### After Complete Fix - ✅ Stable shape creation with automatic document handling - ✅ Agent Manager: AVAILABLE - ✅ Provider Service: AVAILABLE - ✅ Tools Registry: AVAILABLE - ✅ All operations work in headless mode - ✅ Proper error handling and recovery ## 🔧 All Files Modified/Created ### Modified Files - `src/mcp_freecad/connections/freecad_connection_bridge.py` - `freecad-ai/tools/primitives.py` - `freecad-ai/tools/advanced_primitives.py` - `CRASH_FIX_SUMMARY.md` ### Created Files - `freecad-ai/ai/agent_manager.py` (symbolic link) - `freecad-ai/api/provider_service.py` - `test_document_creation.py` - `test_agent_manager.py` The FreeCAD AI system is now completely stable and fully functional!