mcp-freecad

# FreeCAD AI Conversation Analysis ## Current State ### 1. **AI Conversation Limitations (Before Enhancement)** The AI conversation tab originally had these limitations: - **Text-only responses**: AI could only provide textual guidance, not execute operations - **No tool access**: AI providers couldn't access FreeCAD tools or resources - **No context awareness**: AI didn't have access to current document state, objects, or materials - **Manual operations required**: Users had to manually execute all operations suggested by AI ### 2. **MCP Server External Only** The MCP server (`mcp_server.py`) was designed for external clients only: - Intended for Claude Desktop App connection - Not accessible to the internal AI conversation - Required separate configuration and setup - Created a disconnect between internal and external AI capabilities ## Enhanced Solution: MCP Integrated Provider ### Implementation 1. **New MCPIntegratedProvider class** (`ai/providers/mcp_integrated_provider.py`) - Wraps any AI provider (Claude, Gemini, OpenRouter) - Intercepts AI responses and processes tool calls - Executes FreeCAD operations directly - Returns enhanced responses with execution results 2. **Tool Registration System** - Automatically discovers and registers available tools: - Basic tools: primitives, operations, measurements, export/import - Advanced tools: assembly, CAM, rendering, smithery - Provides tool descriptions and parameters to AI 3. **Enhanced System Prompt** - Instructs AI on available tools and how to use them - Defines tool call format using XML-like tags - Encourages proactive tool usage for CAD operations 4. **MCP Integration Toggle** - New checkbox in Models tab: "Enable MCP Tool Integration" - When enabled, wraps the selected AI provider with MCPIntegratedProvider - Settings are saved/loaded from FreeCAD parameters ### How It Works 1. **User asks AI to create something**: "Create a box 10x5x3mm" 2. **AI generates response with tool call**: ``` I'll create a box with those dimensions for you. <tool_use> <tool_name>create_box</tool_name> <parameters> {"length": 10, "width": 5, "height": 3} </parameters> </tool_use> ``` 3. **MCPIntegratedProvider**: - Detects the tool call in the response - Executes `PrimitivesTool.create_box(length=10, width=5, height=3)` - Replaces tool_use block with actual result: ``` <tool_result> <tool_name>create_box</tool_name> <status>success</status> <result>{"success": true, "message": "Created box: Box"}</result> </tool_result> ``` 4. **User sees**: Both the AI explanation and the actual execution result ## Benefits of This Approach 1. **Unified Experience**: Same tools available internally and externally 2. **Direct Execution**: AI can perform operations, not just describe them 3. **Immediate Feedback**: Users see results instantly 4. **Flexible Architecture**: Any AI provider can be enhanced with MCP tools 5. **Progressive Enhancement**: Works with or without MCP integration enabled ## Available Tool Categories ### 1. **Primitives** (via `tools/primitives.py`) - create_box, create_cylinder, create_sphere, create_cone - Create basic 3D shapes with parameters ### 2. **Operations** (via `tools/operations.py`) - boolean_union, boolean_cut, boolean_intersection - Combine or subtract objects ### 3. **Measurements** (via `tools/measurements.py`) - measure_distance, measure_volume, measure_area - Analyze object properties ### 4. **Export/Import** (via `tools/export_import.py`) - export_stl, export_step, import_stl - File operations for 3D models ### 5. **Advanced Tools** (if available) - **Assembly**: Create assemblies, add parts, constraints - **CAM**: Create jobs, tools, operations, G-code - **Rendering**: Scene setup, camera, lighting, materials - **Smithery**: Fun blacksmith-themed tools ### 6. **Resources** (for future enhancement) - Materials library access - Constraint information - Measurement data - CAD model analysis ## Future Enhancements ### 1. **Resource Integration** Currently, resources (materials, constraints, etc.) are registered but not fully utilized. Future work: - Allow AI to query available materials - Apply materials to objects - Access constraint information - Provide measurement context ### 2. **Context Awareness** Enhance AI with current document context: - List of current objects - Selected objects - Object properties and relationships - Document state ### 3. **Tool Discovery** - Dynamic tool discovery from FreeCAD workbenches - Automatic parameter extraction - Tool documentation generation ### 4. **Advanced Tool Patterns** - Multi-step operations - Conditional execution - Error handling and recovery - Undo/redo support ### 5. **Visual Feedback** - Highlight created/modified objects - Show operation preview - Progress indicators for long operations ## Usage Instructions ### For Users 1. **Enable MCP Integration**: - Go to Models tab - Check "Enable MCP Tool Integration" - Save settings 2. **Use Natural Language**: - "Create a cylinder with radius 5mm and height 10mm" - "Boolean union the box and cylinder" - "Measure the volume of Box001" - "Export all objects to model.stl" 3. **AI Will Execute**: - See tool execution in the response - Objects appear in FreeCAD immediately - Results shown in tool_result blocks ### For Developers 1. **Add New Tools**: - Create tool provider in `tools/` directory - Follow the pattern of existing tools - Register in MCPIntegratedProvider._initialize_tools() 2. **Enhance AI Behavior**: - Modify system prompt for better tool usage - Add examples of tool patterns - Improve parameter extraction 3. **Extend Resources**: - Implement resource methods in providers - Add resource queries to tool calls - Provide richer context to AI ## Technical Architecture ``` User Input ↓ AI Provider (Claude/Gemini/OpenRouter) ↓ MCPIntegratedProvider (wrapper) ├── Sends to base AI provider ├── Receives AI response ├── Extracts tool calls ├── Executes tools via FreeCAD API └── Returns enhanced response ↓ User sees result + execution ``` ## Conclusion The MCP integration transforms the AI conversation from a passive advisor to an active CAD assistant. By giving the AI direct access to FreeCAD tools, users get a much more powerful and efficient workflow. The architecture is extensible, allowing for continuous improvement and addition of new capabilities.