Sean P. KaneandGitHub
6a6cad9e65
* FreeCAD addon support for Workbench and Plugins * docs: refactor docs and clean up linters, etc. * Remove mdformat * test: improve test coverage * test:Lots of general fixes * chore: more general fixes
221 lines
8.1 KiB
Markdown
221 lines
8.1 KiB
Markdown
# MCP Bridge Workbench
|
|
|
|
The MCP Bridge Workbench is a FreeCAD addon that provides the server-side connection point for the MCP server. It runs inside FreeCAD and exposes XML-RPC and JSON-RPC interfaces.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The workbench provides:
|
|
|
|
- **Toolbar controls** for starting/stopping the MCP bridge
|
|
- **Status indicator** showing connection state
|
|
- **XML-RPC server** on port 9875 (default)
|
|
- **JSON-RPC socket server** on port 9876 (default)
|
|
- **Headless mode support** for automation and CI/CD
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Via FreeCAD Addon Manager (Recommended)
|
|
|
|
1. Open FreeCAD
|
|
1. Go to **Tools > Addon Manager**
|
|
1. Search for "FreeCAD MCP and More" or "MCP Bridge"
|
|
1. Click **Install**
|
|
1. Restart FreeCAD
|
|
|
|
### Manual Installation
|
|
|
|
Download from [GitHub Releases](https://github.com/spkane/freecad-robust-mcp-and-more/releases) and extract to your FreeCAD Mod directory:
|
|
|
|
- **Linux:** `~/.local/share/FreeCAD/Mod/FreecadRobustMCP/`
|
|
- **macOS:** `~/Library/Application Support/FreeCAD/Mod/FreecadRobustMCP/`
|
|
- **Windows:** `%APPDATA%\FreeCAD\Mod\FreecadRobustMCP\`
|
|
|
|
---
|
|
|
|
## GUI Mode Usage
|
|
|
|
### Starting the Bridge
|
|
|
|
1. Switch to the **MCP Bridge** workbench in FreeCAD
|
|
1. Click **Start Bridge** in the toolbar
|
|
1. The status indicator turns green when running
|
|
|
|
You'll see a confirmation message:
|
|
|
|
```text
|
|
MCP Bridge started!
|
|
- XML-RPC: localhost:9875
|
|
- Socket: localhost:9876
|
|
```
|
|
|
|
### Stopping the Bridge
|
|
|
|
Click **Stop Bridge** in the toolbar. The status indicator turns red.
|
|
|
|
### Status Indicator
|
|
|
|
| Color | Status |
|
|
| ------ | ------------------------------------- |
|
|
| Green | Bridge running, accepting connections |
|
|
| Red | Bridge stopped |
|
|
| Yellow | Bridge starting/stopping |
|
|
|
|
---
|
|
|
|
## Headless Mode Usage
|
|
|
|
The workbench includes a headless server script for running without the FreeCAD GUI.
|
|
|
|
### Starting Headless Mode
|
|
|
|
**Linux:**
|
|
|
|
```bash
|
|
freecadcmd ~/.local/share/FreeCAD/Mod/FreecadRobustMCP/freecad_mcp_bridge/headless_server.py
|
|
```
|
|
|
|
**macOS:**
|
|
|
|
```bash
|
|
/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd \
|
|
~/Library/Application\ Support/FreeCAD/Mod/FreecadRobustMCP/freecad_mcp_bridge/headless_server.py
|
|
```
|
|
|
|
**Using just commands (from source):**
|
|
|
|
```bash
|
|
just freecad::run-headless
|
|
```
|
|
|
|
### Headless Output
|
|
|
|
```text
|
|
FreeCAD version: 1.0.0
|
|
============================================================
|
|
MCP Bridge started in headless mode!
|
|
- XML-RPC: localhost:9875
|
|
- Socket: localhost:9876
|
|
|
|
Note: Screenshot and view features are not available in headless mode.
|
|
Press Ctrl+C to stop.
|
|
============================================================
|
|
```
|
|
|
|
---
|
|
|
|
## Features Available by Mode
|
|
|
|
| Feature | GUI Mode | Headless Mode |
|
|
| ------------------------ | -------- | ------------- |
|
|
| Object creation | Yes | Yes |
|
|
| Boolean operations | Yes | Yes |
|
|
| Export (STEP, STL, etc.) | Yes | Yes |
|
|
| Macro execution | Yes | Yes |
|
|
| Document management | Yes | Yes |
|
|
| Screenshots | Yes | **No** |
|
|
| Object colors | Yes | **No** |
|
|
| Object visibility | Yes | **No** |
|
|
| Camera/view control | Yes | **No** |
|
|
| Interactive selection | Yes | **No** |
|
|
|
|
!!! info "GUI-Only Features"
|
|
When a GUI-only feature is requested in headless mode, the MCP server returns a structured error response instead of crashing: `{"success": false, "error": "GUI not available - screenshots cannot be captured in headless mode"}`
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
The workbench uses default ports that can be customized in the MCP server configuration:
|
|
|
|
| Server | Default Port | Environment Variable |
|
|
| ------- | ------------ | --------------------- |
|
|
| XML-RPC | 9875 | `FREECAD_XMLRPC_PORT` |
|
|
| Socket | 9876 | `FREECAD_SOCKET_PORT` |
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ FreeCAD (GUI or Headless) │
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|
│ │ MCP Bridge Workbench/Plugin │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ │ │
|
|
│ │ │ XML-RPC Server │ │ Socket Server │ │ │
|
|
│ │ │ (port 9875) │ │ (port 9876) │ │ │
|
|
│ │ └────────┬────────┘ └────────┬────────┘ │ │
|
|
│ │ │ │ │ │
|
|
│ │ └────────┬───────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ┌────────▼────────┐ │ │
|
|
│ │ │ FreecadMCPPlugin│ │ │
|
|
│ │ │ (Thread-safe │ │ │
|
|
│ │ │ queue system) │ │ │
|
|
│ │ └────────┬────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ┌────────▼────────┐ │ │
|
|
│ │ │ FreeCAD Python │ │ │
|
|
│ │ │ Console │ │ │
|
|
│ │ └─────────────────┘ │ │
|
|
│ └───────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
▲
|
|
│ Network (localhost)
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ FreeCAD MCP Server (External Process) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
The workbench uses a **queue-based thread safety system** to ensure FreeCAD operations run on the main GUI thread, preventing crashes from thread-unsafe operations.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Bridge Won't Start
|
|
|
|
**Problem:** Clicking "Start Bridge" does nothing or shows an error.
|
|
|
|
**Solution:**
|
|
|
|
1. Check the FreeCAD Python console for error messages
|
|
1. Ensure no other process is using ports 9875/9876
|
|
1. Try restarting FreeCAD
|
|
|
|
### Connection Refused from MCP Server
|
|
|
|
**Problem:** MCP server reports "Connection refused"
|
|
|
|
**Solution:**
|
|
|
|
1. Verify the bridge is running (green status indicator)
|
|
1. Check that ports match between workbench and MCP server config
|
|
1. If using Docker, ensure you're using `host.docker.internal` as the host
|
|
|
|
### Headless Mode Hangs
|
|
|
|
**Problem:** `FreeCADCmd` with headless server never outputs anything
|
|
|
|
**Solution:**
|
|
|
|
1. Ensure you're using `FreeCADCmd` (not `freecad`)
|
|
1. Check the script path is correct
|
|
1. Try running with `-c "print('test')"` first to verify FreeCAD works
|
|
|
|
---
|
|
|
|
## Included Macros
|
|
|
|
The addon bundle also includes standalone FreeCAD macros:
|
|
|
|
- **MultiExport** - Export objects to multiple formats simultaneously
|
|
- **CutObjectForMagnets** - Cut objects with aligned magnet holes for 3D printing
|
|
|
|
See [Macros](macros.md) for details.
|