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>
138 lines
3.6 KiB
Markdown
138 lines
3.6 KiB
Markdown
# Quick Start
|
|
|
|
Get up and running with AI-assisted FreeCAD modeling in minutes.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
Before starting, ensure you have:
|
|
|
|
1. FreeCAD installed with the Robust MCP Bridge workbench
|
|
1. The MCP server installed (`pip install freecad-robust-mcp`)
|
|
1. Your MCP client configured (see [Configuration](configuration.md))
|
|
|
|
---
|
|
|
|
## Step 1: Start FreeCAD with the MCP Bridge
|
|
|
|
### Option A: GUI Mode (Recommended for getting started)
|
|
|
|
1. Open FreeCAD
|
|
1. Switch to the **Robust MCP Bridge** workbench
|
|
1. Click **Start Bridge** in the toolbar
|
|
1. You should see: "MCP Bridge started! XML-RPC: localhost:9875, Socket: localhost:9876"
|
|
|
|
### Option B: Headless Mode (For automation)
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```text
|
|
"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
|
|
|
|
```text
|
|
"Create a new FreeCAD document and add a box that is 20mm x 10mm x 5mm"
|
|
```
|
|
|
|
### Parametric Part with Fillet
|
|
|
|
```text
|
|
"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
|
|
|
|
```text
|
|
"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](../guide/tools.md) for the complete list.
|
|
|
|
---
|
|
|
|
## Example Workflows
|
|
|
|
### Create a Mounting Bracket
|
|
|
|
```text
|
|
"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
|
|
|
|
```text
|
|
"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
|
|
|
|
```text
|
|
"Read the macro 'MyMacro' and explain what it does.
|
|
Then run it and show me any errors."
|
|
```
|
|
|
|
---
|
|
|
|
## Tips for Effective AI-Assisted Modeling
|
|
|
|
1. **Be specific about dimensions** - Include units (mm, cm, inches) in your requests
|
|
1. **Use parametric approaches** - Ask for PartDesign workflows instead of direct Part operations for parts you'll modify
|
|
1. **Check console output** - If something goes wrong, ask the AI to check the FreeCAD console for errors
|
|
1. **Take screenshots** - In GUI mode, ask for screenshots to verify the model looks correct
|
|
1. **Save frequently** - Ask the AI to save your document after significant changes
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- [Tools Reference](../guide/tools.md) - Complete API reference for all tools
|
|
- [User Guide](../USER_GUIDE.md) - Detailed workflows and best practices
|
|
- [Connection Modes](../guide/connection-modes.md) - Understanding connection modes
|