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.7 KiB
3.7 KiB
FreeCAD Robust MCP Server
Welcome to the FreeCAD Robust MCP Server documentation.
This project provides an MCP (Model Context Protocol) server that enables integration between AI assistants (Claude, GPT, and other MCP-compatible tools) and FreeCAD, allowing AI-assisted development and debugging of 3D models, macros, and workbenches.
Features
- 82+ MCP Tools - Comprehensive CAD operations including primitives, PartDesign, booleans, export
- Multiple Connection Modes - XML-RPC (recommended), JSON-RPC socket, or embedded (Linux only)
- GUI & Headless Support - Full modeling in headless mode, plus screenshots/colors in GUI mode
- Macro Development - Create, edit, run, and template FreeCAD macros via MCP
- Standalone Macros - Useful FreeCAD macros that work independently of the Robust MCP Server
Quick Start
# Install the Robust MCP Server
pip install freecad-robust-mcp
# Install the workbench via FreeCAD Addon Manager
# (search for "FreeCAD MCP and More")
# Start FreeCAD and click "Start Bridge" in the Robust MCP Bridge workbench
# Configure your MCP client and start building!
See Installation for detailed setup instructions.
Connection Modes
| Mode | Description | Platform |
|---|---|---|
xmlrpc |
XML-RPC protocol (port 9875) | All platforms (recommended) |
socket |
JSON-RPC socket (port 9876) | All platforms |
embedded |
In-process FreeCAD | Linux only |
See Connection Modes for details on choosing the right mode.
GUI vs Headless Mode
The Robust MCP Server works with FreeCAD in both GUI and headless mode:
| Feature | Headless | GUI |
|---|---|---|
| Object creation | Yes | Yes |
| Boolean operations | Yes | Yes |
| Export (STEP, STL, etc.) | Yes | Yes |
| Screenshots | No | Yes |
| Object colors/visibility | No | Yes |
| Camera control | No | Yes |
FreeCAD Macros
This project includes standalone FreeCAD macros:
- CutObjectForMagnets - Cuts objects along planes with automatic magnet hole placement
- MultiExport - Export objects to multiple formats simultaneously
Documentation
| Section | Description |
|---|---|
| Getting Started | Installation, configuration, and quick start |
| User Guide | Connection modes, workbench, macros, and tools |
| Tools Reference | Complete API reference for all 82+ MCP tools |
| API Reference | Python API documentation |
| Development | Contributing, architecture, and development setup |
| Comparison | Analysis of other FreeCAD MCP implementations |