8c338f6da7
* fix: lots of fixes and name refactoring * feat: Add workbench preferences * fix: MCP bridge status widget and just command fixes * fix(tests): Use the correct mesa-glx package * fix(ci): Add fontconfig to GUI test dependencies FreeCAD GUI was failing to start with: "Fontconfig error: Cannot load default config file: No such file" Added fontconfig and fonts-dejavu-core packages to the GUI test job dependencies to resolve the font configuration issue. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(addon): Extract path utilities into shared module Create path_utils.py module that consolidates duplicated path-finding logic from commands.py and InitGui.py: - get_addon_path(): Find addon directory with caching and fallbacks - get_icon_path(): Get full path to an icon file - get_icons_dir(): Get path to icons directory - get_workbench_icon(): Get path to workbench main icon This removes ~100 lines of duplicated code while preserving the same behavior including _addon_path_cache and all fallback methods. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(addon): Prevent stale plugin state on startup failure The StartMCPBridgeCommand.Activated method could leave _mcp_plugin in a partially initialized state if FreecadMCPPlugin.start() failed after the plugin was instantiated. Changes: - Create plugin in a local variable first - Only assign to _mcp_plugin after start() succeeds - Explicitly clear _mcp_plugin and _running_config in exception handlers to ensure clean state for subsequent retry attempts Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: Lot of broad improvements * fix(ci): Use blocking headless_server.py for GUI tests The GUI test was using startup_bridge.py which is non-blocking (designed for interactive use). For CI, even in GUI mode, we need the blocking headless_server.py that calls run_forever() to keep FreeCAD running. GUI features are still available since we use the 'freecad' executable instead of 'freecadcmd'. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor(addon): Rename headless_server.py to blocking_bridge.py The old name was misleading because: - It works with both GUI (freecad) and headless (freecadcmd) modes - The key characteristic is that it BLOCKS with run_forever() New naming convention clarifies the difference: - blocking_bridge.py: Starts bridge and blocks (for CI, servers) - startup_bridge.py: Starts bridge and returns (for interactive GUI) Updated all references across: - GitHub workflow (macro-test.yaml) - Just commands (freecad.just) - Unit tests (test_addon_structure.py) - Documentation (5 files) - CLAUDE.md Also improved the script to detect GUI mode dynamically using FreeCAD.GuiUp and display the appropriate status message. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(just): Remove erroneous rm of startup_bridge.py on error The startup script is now a permanent source file in the repository, not a generated temporary file. The rm -f would have deleted source code if FreeCAD wasn't found. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: General improvements * fix: Lots of general fixes and only stable to PyPi * fix: small cleanup * fix: Small fixes and hopefully fixes the GUI tests * fix: Add proper library paths for FreeCAD GUI in CI - Create wrapper scripts instead of symlinks for AppImage binaries - Set LD_LIBRARY_PATH, QT_PLUGIN_PATH for GUI mode - Add diagnostic output to identify startup failures * fix: Use apprun for GUI tests in CI * fix: Improving Xvfb tests * fix: GUI tests worlk * chore: remove invalid --no-splash comments * fix: ARM64 architecture support and other fixes * fix: cleanup * test: just commands test suite * test: improve just command tests * fix: more general improvements * fix: more cleanup * fix: more updates * fix: small tweaks --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
3.6 KiB
3.6 KiB
Quick Start
Get up and running with AI-assisted FreeCAD modeling in minutes.
Prerequisites
Before starting, ensure you have:
- FreeCAD installed with the Robust MCP Bridge workbench
- The MCP server installed (
pip install freecad-robust-mcp) - Your MCP client configured (see Configuration)
Step 1: Start FreeCAD with the MCP Bridge
Option A: GUI Mode (Recommended for getting started)
- Open FreeCAD
- Switch to the Robust MCP Bridge workbench
- Click Start Bridge in the toolbar
- You should see: "MCP Bridge started! XML-RPC: localhost:9875, Socket: localhost:9876"
Option B: Headless Mode (For automation)
# If installed via Addon Manager (Linux)
FreeCADCmd ~/.local/share/FreeCAD/Mod/FreecadRobustMCP/freecad_mcp_bridge/blocking_bridge.py
# If working from source
just freecad::run-headless
Step 2: Connect Your AI Assistant
With FreeCAD and the MCP server configured, open your AI assistant (Claude Code, Cursor, etc.) and verify the connection:
"Check the FreeCAD connection status"
The AI should respond with information about the connection mode, FreeCAD version, and whether GUI is available.
Step 3: Create Your First Model
Try these example prompts with your AI assistant:
Simple Box
"Create a new FreeCAD document and add a box that is 20mm x 10mm x 5mm"
Parametric Part with Fillet
"Create a parametric bracket:
1. Start with a 50x30mm rectangular sketch
2. Extrude it 10mm
3. Add a 3mm fillet to all edges"
Export for 3D Printing
"Export the current model to STL format for 3D printing"
Step 4: Explore Available Tools
The MCP server provides 82+ tools organized into categories:
| Category | Examples |
|---|---|
| Primitives | create_box, create_cylinder, create_sphere |
| PartDesign | create_sketch, pad_sketch, pocket_sketch |
| Operations | boolean_operation, fillet_edges, chamfer_edges |
| Export | export_stl, export_step, export_3mf |
| View (GUI) | get_screenshot, set_object_color |
See the Tools Reference for the complete list.
Example Workflows
Create a Mounting Bracket
"Help me create a mounting bracket with:
- 60x40mm base plate, 5mm thick
- Two mounting holes (5mm diameter) at the corners
- A vertical wall 30mm tall on one edge
- 2mm fillets on all external edges"
Modify an Existing Model
"Open my_part.FCStd and:
1. List all the objects in the document
2. Change the height of the Pad feature from 10mm to 15mm
3. Save the document"
Debug a Macro
"Read the macro 'MyMacro' and explain what it does.
Then run it and show me any errors."
Tips for Effective AI-Assisted Modeling
- Be specific about dimensions - Include units (mm, cm, inches) in your requests
- Use parametric approaches - Ask for PartDesign workflows instead of direct Part operations for parts you'll modify
- Check console output - If something goes wrong, ask the AI to check the FreeCAD console for errors
- Take screenshots - In GUI mode, ask for screenshots to verify the model looks correct
- Save frequently - Ask the AI to save your document after significant changes
Next Steps
- Tools Reference - Complete API reference for all tools
- User Guide - Detailed workflows and best practices
- Connection Modes - Understanding connection modes