feat: Add workbench and major cleanup, refactor, and updates (#21)
* 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
This commit is contained in:
Sean P. Kane
@@ -0,0 +1,34 @@
|
||||
# Bridge API Reference
|
||||
|
||||
The bridge module provides the communication layer between the MCP server and FreeCAD.
|
||||
|
||||
## Base Classes
|
||||
|
||||
::: freecad_mcp.bridge.base
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_source: true
|
||||
|
||||
## XML-RPC Bridge
|
||||
|
||||
::: freecad_mcp.bridge.xmlrpc
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_source: true
|
||||
|
||||
## Socket Bridge
|
||||
|
||||
::: freecad_mcp.bridge.socket
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_source: true
|
||||
|
||||
## Embedded Bridge
|
||||
|
||||
!!! warning "Linux Only"
|
||||
The embedded bridge only works on Linux. See [Connection Modes](../guide/connection-modes.md) for details.
|
||||
|
||||
::: freecad_mcp.bridge.embedded
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_source: true
|
||||
@@ -0,0 +1,6 @@
|
||||
# Configuration API Reference
|
||||
|
||||
::: freecad_mcp.config
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_source: true
|
||||
@@ -0,0 +1,11 @@
|
||||
# Server API Reference
|
||||
|
||||
::: freecad_mcp.server
|
||||
options:
|
||||
show_root_heading: true
|
||||
show_source: true
|
||||
members:
|
||||
\- mcp
|
||||
\- get_bridge
|
||||
\- startup
|
||||
\- shutdown
|
||||
@@ -0,0 +1,259 @@
|
||||
# Architecture
|
||||
|
||||
This document provides a technical overview of the FreeCAD MCP Server architecture.
|
||||
|
||||
For the full architecture document with design decisions and rationale, see [ARCHITECTURE-MCP.md](https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/ARCHITECTURE-MCP.md).
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The FreeCAD MCP Server follows a **Bridge with Adapter** pattern:
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ MCP Server Layer │
|
||||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ FastMCP Application │ │
|
||||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
||||
│ │ │ Tools │ │ Resources│ │ Prompts │ │ Lifecycle│ │ │
|
||||
│ │ │ (82+) │ │ │ │ │ │ Manager │ │ │
|
||||
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ FreeCAD Bridge Interface │ │
|
||||
│ │ (Abstract Base Class) │ │
|
||||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||||
│ ╱ │ ╲ │
|
||||
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
|
||||
│ │ EmbeddedBridge │ │ SocketBridge │ │ XMLRPCBridge │ │
|
||||
│ │ (Linux only) │ │ (JSON-RPC) │ │ (Recommended) │ │
|
||||
│ └────────────────┘ └────────────────┘ └────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Structure
|
||||
|
||||
```text
|
||||
src/freecad_mcp/
|
||||
├── __init__.py
|
||||
├── server.py # Main MCP server entry point
|
||||
├── config.py # Configuration management
|
||||
│
|
||||
├── bridge/ # FreeCAD communication layer
|
||||
│ ├── __init__.py # Bridge factory
|
||||
│ ├── base.py # Abstract bridge interface
|
||||
│ ├── embedded.py # In-process FreeCAD (Linux only)
|
||||
│ ├── socket.py # JSON-RPC socket bridge
|
||||
│ ├── xmlrpc.py # XML-RPC bridge (recommended)
|
||||
│ └── protocol.py # Wire protocol definitions
|
||||
│
|
||||
├── tools/ # MCP tool implementations
|
||||
│ ├── __init__.py
|
||||
│ ├── execution.py # Python execution & debugging
|
||||
│ ├── documents.py # Document management
|
||||
│ ├── objects.py # Object creation/manipulation
|
||||
│ ├── partdesign.py # PartDesign parametric modeling
|
||||
│ ├── view.py # View, camera, display
|
||||
│ ├── export.py # Export/import operations
|
||||
│ └── macros.py # Macro management
|
||||
│
|
||||
├── resources/ # MCP resource implementations
|
||||
│ ├── __init__.py
|
||||
│ └── freecad.py # Document, console, capabilities
|
||||
│
|
||||
├── prompts/ # MCP prompt templates
|
||||
│ ├── __init__.py
|
||||
│ └── freecad.py # Modeling and debugging prompts
|
||||
│
|
||||
└── freecad_workbench_addon/ # Workbench addon (deprecated location)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bridge Architecture
|
||||
|
||||
### Base Interface
|
||||
|
||||
All bridges implement `FreecadBridge`:
|
||||
|
||||
```python
|
||||
class FreecadBridge(ABC):
|
||||
@abstractmethod
|
||||
async def connect(self) -> None: ...
|
||||
|
||||
@abstractmethod
|
||||
async def disconnect(self) -> None: ...
|
||||
|
||||
@abstractmethod
|
||||
async def is_connected(self) -> bool: ...
|
||||
|
||||
@abstractmethod
|
||||
async def execute_python(
|
||||
self, code: str, timeout_ms: int = 30000
|
||||
) -> ExecutionResult: ...
|
||||
```
|
||||
|
||||
### XML-RPC Bridge (Recommended)
|
||||
|
||||
- Connects to FreeCAD via XML-RPC on port 9875
|
||||
- Proven, reliable protocol
|
||||
- Works on all platforms
|
||||
|
||||
### Socket Bridge
|
||||
|
||||
- Uses JSON-RPC over TCP sockets on port 9876
|
||||
- Lower overhead than XML-RPC
|
||||
- Easier to debug (JSON format)
|
||||
|
||||
### Embedded Bridge
|
||||
|
||||
- Imports FreeCAD directly into the MCP server process
|
||||
- **Linux only** (crashes on macOS/Windows)
|
||||
- Fastest execution (no IPC overhead)
|
||||
- Headless mode only
|
||||
|
||||
---
|
||||
|
||||
## Workbench Addon Architecture
|
||||
|
||||
The workbench addon runs inside FreeCAD:
|
||||
|
||||
```text
|
||||
addon/FreecadRobustMCP/
|
||||
├── package.xml # FreeCAD addon metadata
|
||||
├── Init.py # Module initialization
|
||||
├── InitGui.py # GUI initialization (workbench)
|
||||
├── FreecadRobustMCP.svg # Workbench icon
|
||||
└── freecad_mcp_bridge/ # Bridge plugin
|
||||
├── __init__.py
|
||||
├── server.py # XML-RPC/JSON-RPC server
|
||||
└── headless_server.py # Headless mode launcher
|
||||
```
|
||||
|
||||
### Thread Safety
|
||||
|
||||
The workbench uses a queue-based system for thread-safe GUI operations:
|
||||
|
||||
```python
|
||||
# Operations queued from network thread
|
||||
request_queue.put(operation)
|
||||
|
||||
# Executed on main GUI thread via QTimer
|
||||
def process_queue():
|
||||
while not request_queue.empty():
|
||||
op = request_queue.get()
|
||||
result = op()
|
||||
response_queue.put(result)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Tool Execution
|
||||
|
||||
```text
|
||||
1. AI Assistant sends tool request
|
||||
↓
|
||||
2. MCP Server receives request
|
||||
↓
|
||||
3. Tool handler prepares Python code
|
||||
↓
|
||||
4. Bridge.execute_python() sends code
|
||||
↓
|
||||
5. FreeCAD executes code (main thread)
|
||||
↓
|
||||
6. Result returned via bridge
|
||||
↓
|
||||
7. MCP Server formats response
|
||||
↓
|
||||
8. AI Assistant receives result
|
||||
```
|
||||
|
||||
### Code Execution Pattern
|
||||
|
||||
Tools generate Python code that runs in FreeCAD:
|
||||
|
||||
```python
|
||||
@mcp.tool()
|
||||
async def create_box(length: float = 10.0, ...) -> dict:
|
||||
bridge = await get_bridge()
|
||||
|
||||
code = f'''
|
||||
doc = FreeCAD.ActiveDocument or FreeCAD.newDocument("Unnamed")
|
||||
obj = doc.addObject("Part::Box", "Box")
|
||||
obj.Length = {length}
|
||||
doc.recompute()
|
||||
_result_ = {{"name": obj.Name, "volume": obj.Shape.Volume}}
|
||||
'''
|
||||
|
||||
result = await bridge.execute_python(code)
|
||||
return result.result
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GUI Detection
|
||||
|
||||
Tools check `FreeCAD.GuiUp` to handle headless mode:
|
||||
|
||||
```python
|
||||
code = f'''
|
||||
if not FreeCAD.GuiUp:
|
||||
_result_ = {{"success": False, "error": "GUI not available"}}
|
||||
else:
|
||||
# GUI-only operations
|
||||
obj.ViewObject.Visibility = True
|
||||
_result_ = {{"success": True}}
|
||||
'''
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration via environment variables:
|
||||
|
||||
| Variable | Default | Description |
|
||||
| --------------------- | ----------- | --------------------------- |
|
||||
| `FREECAD_MODE` | `xmlrpc` | Connection mode |
|
||||
| `FREECAD_PATH` | auto | FreeCAD lib path (embedded) |
|
||||
| `FREECAD_SOCKET_HOST` | `localhost` | Socket/XML-RPC host |
|
||||
| `FREECAD_SOCKET_PORT` | `9876` | JSON-RPC socket port |
|
||||
| `FREECAD_XMLRPC_PORT` | `9875` | XML-RPC port |
|
||||
| `FREECAD_TIMEOUT_MS` | `30000` | Execution timeout |
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Mock FreeCAD module
|
||||
- Test bridge logic in isolation
|
||||
- Run on all platforms
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Use FreeCAD AppImage in CI
|
||||
- Test actual FreeCAD operations
|
||||
- Run in headless mode
|
||||
|
||||
### Embedded Mode Testing
|
||||
|
||||
Embedded mode receives **minimal testing**:
|
||||
|
||||
- Unit tests with mocked FreeCAD
|
||||
- No CI integration tests (would require Linux + FreeCAD in-process)
|
||||
- Recommended to use xmlrpc/socket modes for production
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Contributing](contributing.md) - How to contribute
|
||||
- [Full Architecture Document](https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/ARCHITECTURE-MCP.md) - Complete design details
|
||||
@@ -0,0 +1,223 @@
|
||||
# Contributing
|
||||
|
||||
Thank you for your interest in contributing to FreeCAD MCP Server!
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.11 (must match FreeCAD's bundled version)
|
||||
- [mise](https://mise.jdx.dev/) for tool management
|
||||
- FreeCAD 0.21+ or 1.0+ installed
|
||||
|
||||
### Initial Setup
|
||||
|
||||
```bash
|
||||
git clone https://github.com/spkane/freecad-robust-mcp-and-more.git
|
||||
cd freecad-robust-mcp-and-more
|
||||
|
||||
# Install mise if not already installed
|
||||
curl https://mise.run | sh
|
||||
|
||||
# Install project tools and dependencies
|
||||
mise trust
|
||||
mise install
|
||||
just setup
|
||||
```
|
||||
|
||||
### Safety CLI Account (Required for Security Scanning)
|
||||
|
||||
This project uses [Safety CLI](https://safetycli.com/) for dependency vulnerability scanning. Safety requires a **free account** for the `safety scan` command used in pre-commit hooks.
|
||||
|
||||
```bash
|
||||
# Register for a free account (interactive)
|
||||
uv run safety auth
|
||||
|
||||
# Or login if you already have an account
|
||||
uv run safety auth --login
|
||||
```
|
||||
|
||||
**Note:** Authentication is stored locally and only needs to be done once per machine. If you skip this step, the `safety` pre-commit hook will fail with an authentication prompt.
|
||||
|
||||
**CI/CD:** Safety runs in CI using the `SAFETY_API_KEY` repository secret.
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
just test
|
||||
|
||||
# Run unit tests only
|
||||
just testing::unit
|
||||
|
||||
# Run with coverage
|
||||
just testing::cov
|
||||
|
||||
# Run type checking
|
||||
uv run mypy src/
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
# Run all pre-commit checks
|
||||
just check
|
||||
|
||||
# Run linting
|
||||
just lint
|
||||
|
||||
# Format code
|
||||
just format
|
||||
|
||||
# Run security checks
|
||||
just quality::secrets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```text
|
||||
freecad-robust-mcp-and-more/
|
||||
├── src/freecad_mcp/ # Main package
|
||||
│ ├── bridge/ # FreeCAD connection bridges
|
||||
│ ├── tools/ # MCP tool implementations
|
||||
│ ├── resources/ # MCP resource implementations
|
||||
│ ├── prompts/ # MCP prompt templates
|
||||
│ └── server.py # Main server entry point
|
||||
├── addon/ # FreeCAD workbench addon
|
||||
│ └── FreecadRobustMCP/ # Workbench files
|
||||
├── macros/ # Standalone FreeCAD macros
|
||||
├── tests/ # Test suite
|
||||
│ ├── unit/ # Unit tests
|
||||
│ └── integration/ # Integration tests
|
||||
├── docs/ # Documentation
|
||||
└── just/ # Justfile modules
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Contribution Guidelines
|
||||
|
||||
### Code Style
|
||||
|
||||
- Follow PEP 8 with 88-character line length (ruff/black)
|
||||
- Use type hints for all function signatures
|
||||
- Write Google-style docstrings
|
||||
- Run `just format` before committing
|
||||
|
||||
### Testing
|
||||
|
||||
- Write tests for all new functionality
|
||||
- Maintain test coverage
|
||||
- Run `just test` before submitting PRs
|
||||
- Integration tests require FreeCAD (run via CI)
|
||||
|
||||
### Documentation
|
||||
|
||||
- Update docstrings for API changes
|
||||
- Update user docs for feature changes
|
||||
- Run `just docs` to build and verify
|
||||
|
||||
### Commits
|
||||
|
||||
- Use conventional commit format
|
||||
- Keep commits focused and atomic
|
||||
- Reference issues when applicable
|
||||
|
||||
---
|
||||
|
||||
## Adding New MCP Tools
|
||||
|
||||
1. **Choose the right module** in `src/freecad_mcp/tools/`
|
||||
1. **Add the tool function** with proper docstring:
|
||||
|
||||
```python
|
||||
@mcp.tool()
|
||||
async def my_new_tool(
|
||||
param1: str,
|
||||
param2: int = 10,
|
||||
doc_name: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Short description of what the tool does.
|
||||
|
||||
Args:
|
||||
param1: Description of param1.
|
||||
param2: Description of param2.
|
||||
doc_name: Document name. Uses active if None.
|
||||
|
||||
Returns:
|
||||
Dictionary with result information.
|
||||
"""
|
||||
bridge = await get_bridge()
|
||||
code = f'''
|
||||
# FreeCAD Python code here
|
||||
_result_ = {{"success": True}}
|
||||
'''
|
||||
result = await bridge.execute_python(code)
|
||||
return result.result or {"success": False}
|
||||
```
|
||||
|
||||
1. **Add tests** in the appropriate test file
|
||||
1. **Update documentation** in `docs/guide/tools.md`
|
||||
1. **Update capabilities resource** in `src/freecad_mcp/resources/freecad.py`
|
||||
|
||||
---
|
||||
|
||||
## Adding New Connection Modes
|
||||
|
||||
1. Create a new bridge class in `src/freecad_mcp/bridge/`
|
||||
1. Inherit from `FreecadBridge` base class
|
||||
1. Implement all abstract methods
|
||||
1. Add to bridge factory in `src/freecad_mcp/bridge/__init__.py`
|
||||
1. Add configuration option in `src/freecad_mcp/config.py`
|
||||
1. Update documentation
|
||||
|
||||
---
|
||||
|
||||
## Release Process
|
||||
|
||||
Releases are automated via GitHub Actions:
|
||||
|
||||
1. Update `CHANGELOG.md`
|
||||
1. Create a GitHub Release with a version tag
|
||||
1. CI builds and publishes:
|
||||
- PyPI package
|
||||
- Docker images
|
||||
- Macro release archives
|
||||
|
||||
---
|
||||
|
||||
## Future Work
|
||||
|
||||
The following items are on the roadmap and welcome contributions:
|
||||
|
||||
### Embedded Mode Integration Tests
|
||||
|
||||
<!-- TODO: Add live FreeCAD integration tests for embedded mode -->
|
||||
|
||||
Currently, embedded mode has only mocked unit tests. Adding live integration tests would require:
|
||||
|
||||
1. CI workflow that runs on Linux (embedded mode is Linux-only)
|
||||
1. Uses FreeCAD AppImage's bundled Python interpreter
|
||||
1. Sets up `PYTHONPATH` and `LD_LIBRARY_PATH` to point to AppImage libs
|
||||
1. Runs tests with `FREECAD_MODE=embedded`
|
||||
|
||||
**Challenge:** The AppImage bundles Python 3.11, so tests must run using that interpreter (not the system Python) to avoid ABI incompatibility.
|
||||
|
||||
**Reference:** See `macro-test.yaml` for how integration tests currently work with xmlrpc mode.
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Issues:** [GitHub Issues](https://github.com/spkane/freecad-robust-mcp-and-more/issues)
|
||||
- **Discussions:** [GitHub Discussions](https://github.com/spkane/freecad-robust-mcp-and-more/discussions)
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License. See [LICENSE](https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/LICENSE) for details.
|
||||
@@ -0,0 +1,162 @@
|
||||
# Configuration
|
||||
|
||||
Configure the FreeCAD MCP Server using environment variables and MCP client settings.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
| --------------------- | ---------------------------------------------------- | ----------- |
|
||||
| `FREECAD_MODE` | Connection mode: `xmlrpc`, `socket`, or `embedded` | `xmlrpc` |
|
||||
| `FREECAD_PATH` | Path to FreeCAD's lib directory (embedded mode only) | Auto-detect |
|
||||
| `FREECAD_SOCKET_HOST` | Socket/XML-RPC server hostname | `localhost` |
|
||||
| `FREECAD_SOCKET_PORT` | JSON-RPC socket server port | `9876` |
|
||||
| `FREECAD_XMLRPC_PORT` | XML-RPC server port | `9875` |
|
||||
| `FREECAD_TIMEOUT_MS` | Execution timeout in ms | `30000` |
|
||||
|
||||
---
|
||||
|
||||
## Connection Modes
|
||||
|
||||
The MCP server supports three connection modes:
|
||||
|
||||
| Mode | Description | Platform Support |
|
||||
| ---------- | ------------------------------------------- | --------------------------------- |
|
||||
| `xmlrpc` | Connects to FreeCAD via XML-RPC (port 9875) | **All platforms** (recommended) |
|
||||
| `socket` | Connects via JSON-RPC socket (port 9876) | **All platforms** |
|
||||
| `embedded` | Imports FreeCAD directly into process | **Linux only** (crashes on macOS) |
|
||||
|
||||
### XML-RPC Mode (Recommended)
|
||||
|
||||
The default and recommended mode. Works on all platforms.
|
||||
|
||||
```bash
|
||||
export FREECAD_MODE=xmlrpc
|
||||
freecad-mcp
|
||||
```
|
||||
|
||||
### Socket Mode
|
||||
|
||||
Alternative to XML-RPC using JSON-RPC over TCP sockets.
|
||||
|
||||
```bash
|
||||
export FREECAD_MODE=socket
|
||||
freecad-mcp
|
||||
```
|
||||
|
||||
### Embedded Mode (Linux Only)
|
||||
|
||||
!!! warning "Linux Only"
|
||||
Embedded mode only works on Linux. On macOS and Windows, it will crash because FreeCAD's `FreeCAD.so` library links to its bundled Python, which conflicts with external Python interpreters.
|
||||
|
||||
Embedded mode imports FreeCAD directly into the MCP server process for fastest execution.
|
||||
|
||||
```bash
|
||||
export FREECAD_MODE=embedded
|
||||
export FREECAD_PATH=/usr/lib/freecad/lib
|
||||
freecad-mcp
|
||||
```
|
||||
|
||||
**Note:** Embedded mode testing is minimal. For production use, prefer `xmlrpc` or `socket` modes.
|
||||
|
||||
---
|
||||
|
||||
## MCP Client Configuration
|
||||
|
||||
### Claude Code / Claude Desktop
|
||||
|
||||
Add to `~/.claude/claude_desktop_config.json` or a project `.mcp.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"freecad": {
|
||||
"command": "freecad-mcp",
|
||||
"env": {
|
||||
"FREECAD_MODE": "xmlrpc"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If installed from source with mise/uv:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"freecad": {
|
||||
"command": "/path/to/mise/shims/uv",
|
||||
"args": ["run", "--project", "/path/to/freecad-robust-mcp-and-more", "freecad-mcp"],
|
||||
"env": {
|
||||
"FREECAD_MODE": "xmlrpc"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Docker Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"freecad": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run", "--rm", "-i",
|
||||
"-e", "FREECAD_MODE=xmlrpc",
|
||||
"-e", "FREECAD_SOCKET_HOST=host.docker.internal",
|
||||
"spkane/freecad-robust-mcp"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GUI vs Headless Mode
|
||||
|
||||
FreeCAD can run in two modes, and the MCP server works with both:
|
||||
|
||||
| Feature | Headless Mode | GUI Mode |
|
||||
| ------------------------ | ------------- | -------- |
|
||||
| Object creation | Yes | Yes |
|
||||
| Boolean operations | Yes | Yes |
|
||||
| Export (STEP, STL, etc.) | Yes | Yes |
|
||||
| Save documents | Yes | Yes |
|
||||
| Screenshots | No | Yes |
|
||||
| Object colors | No | Yes |
|
||||
| Object visibility | No | Yes |
|
||||
| Camera control | No | Yes |
|
||||
| Interactive selection | No | Yes |
|
||||
|
||||
### Starting FreeCAD
|
||||
|
||||
**GUI Mode** (for interactive work with visual feedback):
|
||||
|
||||
```bash
|
||||
# Using just commands (from source)
|
||||
just freecad::run-gui
|
||||
|
||||
# Or start FreeCAD normally and click "Start Bridge" in the workbench
|
||||
```
|
||||
|
||||
**Headless Mode** (for automation, CI/CD, or when you don't need visual feedback):
|
||||
|
||||
```bash
|
||||
# Using just commands (from source)
|
||||
just freecad::run-headless
|
||||
|
||||
# Or run directly with FreeCADCmd
|
||||
FreeCADCmd ~/.local/share/FreeCAD/Mod/FreecadRobustMCP/freecad_mcp_bridge/headless_server.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Quick Start](quickstart.md) - Create your first model with AI assistance
|
||||
- [Connection Modes](../guide/connection-modes.md) - Detailed guide on different connection modes
|
||||
@@ -0,0 +1,126 @@
|
||||
# Installation
|
||||
|
||||
This guide covers installing the FreeCAD MCP Server and connecting it to your AI assistant.
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
- **FreeCAD** 0.21+ or 1.0+ (with Python 3.11)
|
||||
- **Python 3.11** (must match FreeCAD's bundled Python version)
|
||||
- An **MCP-compatible AI assistant** (Claude Code, Cursor, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Method 1: pip (Recommended)
|
||||
|
||||
The simplest way to install the MCP server:
|
||||
|
||||
```bash
|
||||
pip install freecad-robust-mcp
|
||||
```
|
||||
|
||||
### Method 2: From Source (for Development)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/spkane/freecad-robust-mcp-and-more.git
|
||||
cd freecad-robust-mcp-and-more
|
||||
|
||||
# Install mise (if not already installed)
|
||||
curl https://mise.run | sh
|
||||
|
||||
mise trust
|
||||
mise install
|
||||
just setup
|
||||
```
|
||||
|
||||
### Method 3: Docker
|
||||
|
||||
Run the MCP server in a container:
|
||||
|
||||
```bash
|
||||
# Pull from Docker Hub
|
||||
docker pull spkane/freecad-robust-mcp
|
||||
|
||||
# Or build locally
|
||||
docker build -t freecad-robust-mcp .
|
||||
```
|
||||
|
||||
**Note:** The Docker container runs the MCP server only—it does not include FreeCAD itself. You must run FreeCAD with the MCP Bridge workbench on your host machine (or in a separate container) and configure the MCP server to connect via `xmlrpc` or `socket` mode.
|
||||
|
||||
**Why embedded mode doesn't work with Docker:** Embedded mode requires FreeCAD and the MCP server to run in the same process, which is impossible when FreeCAD runs on the host and the MCP server runs inside a Docker container. Additionally, embedded mode fails on macOS due to ABI incompatibility with FreeCAD's bundled Python libraries (`libpython3.11.dylib`). Always use `xmlrpc` or `socket` mode for Docker deployments.
|
||||
|
||||
---
|
||||
|
||||
## Installing the MCP Bridge Workbench
|
||||
|
||||
The MCP Bridge Workbench runs inside FreeCAD and provides the connection point for the MCP server.
|
||||
|
||||
### 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
|
||||
|
||||
1. Download the latest release from [GitHub Releases](https://github.com/spkane/freecad-robust-mcp-and-more/releases)
|
||||
1. Extract to your FreeCAD Mod directory:
|
||||
- **Linux:** `~/.local/share/FreeCAD/Mod/`
|
||||
- **macOS:** `~/Library/Application Support/FreeCAD/Mod/`
|
||||
- **Windows:** `%APPDATA%\FreeCAD\Mod\`
|
||||
1. Restart FreeCAD
|
||||
|
||||
---
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
After installation, verify everything is working:
|
||||
|
||||
### Step 1: Start FreeCAD with the MCP Bridge
|
||||
|
||||
1. **Start FreeCAD** and select the **MCP Bridge** workbench from the workbench selector dropdown
|
||||
1. **Click "Start MCP Bridge"** in the toolbar (or use the MCP Bridge menu)
|
||||
1. Check the FreeCAD console for confirmation messages:
|
||||
|
||||
```text
|
||||
MCP Bridge started!
|
||||
- XML-RPC: localhost:9875
|
||||
- Socket: localhost:9876
|
||||
```
|
||||
|
||||
### Step 2: Verify the MCP Server
|
||||
|
||||
Test that the MCP server command is available:
|
||||
|
||||
```bash
|
||||
# With pip installation
|
||||
freecad-mcp --help
|
||||
|
||||
# With source installation
|
||||
uv run freecad-mcp --help
|
||||
```
|
||||
|
||||
### Step 3: Test the Connection
|
||||
|
||||
With FreeCAD running and the bridge started, you can verify connectivity:
|
||||
|
||||
```bash
|
||||
# Quick connectivity test using curl (XML-RPC)
|
||||
curl -X POST http://localhost:9875 \
|
||||
-H "Content-Type: text/xml" \
|
||||
-d '<?xml version="1.0"?><methodCall><methodName>ping</methodName></methodCall>'
|
||||
```
|
||||
|
||||
A successful response indicates the bridge is working correctly.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Configuration](configuration.md) - Set up environment variables and MCP client settings
|
||||
- [Quick Start](quickstart.md) - Create your first model with AI assistance
|
||||
@@ -0,0 +1,137 @@
|
||||
# Quick Start
|
||||
|
||||
Get up and running with AI-assisted FreeCAD modeling in minutes.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting, ensure you have:
|
||||
|
||||
1. FreeCAD installed with the 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 **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/headless_server.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
|
||||
@@ -0,0 +1,202 @@
|
||||
# Connection Modes
|
||||
|
||||
The FreeCAD MCP Server supports multiple ways to connect to FreeCAD. Choose the mode that best fits your workflow.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
| Mode | Description | Platform | Best For |
|
||||
| ---------- | --------------------------------- | ------------- | -------------------------------- |
|
||||
| `xmlrpc` | XML-RPC protocol (port 9875) | All platforms | Production use (recommended) |
|
||||
| `socket` | JSON-RPC over TCP sockets | All platforms | Alternative to XML-RPC |
|
||||
| `embedded` | FreeCAD imported into MCP process | Linux only | Fastest execution, CI/automation |
|
||||
|
||||
---
|
||||
|
||||
## XML-RPC Mode (Recommended)
|
||||
|
||||
XML-RPC mode is the **default and recommended** connection method. It works on all platforms and provides robust, reliable communication.
|
||||
|
||||
### How It Works
|
||||
|
||||
```text
|
||||
MCP Client <--stdio--> MCP Server <--XML-RPC:9875--> FreeCAD
|
||||
```
|
||||
|
||||
The MCP server communicates with FreeCAD via XML-RPC protocol on port 9875.
|
||||
|
||||
### Setup
|
||||
|
||||
1. Start FreeCAD with the MCP Bridge workbench
|
||||
1. Click **Start Bridge** (or it auto-starts if configured)
|
||||
1. Configure the MCP server:
|
||||
|
||||
```bash
|
||||
export FREECAD_MODE=xmlrpc
|
||||
export FREECAD_XMLRPC_PORT=9875 # default
|
||||
freecad-mcp
|
||||
```
|
||||
|
||||
### Advantages
|
||||
|
||||
- Works on all platforms (macOS, Linux, Windows)
|
||||
- Process isolation (FreeCAD crash doesn't affect MCP server)
|
||||
- Supports both GUI and headless FreeCAD
|
||||
|
||||
---
|
||||
|
||||
## Socket Mode
|
||||
|
||||
Socket mode uses JSON-RPC over TCP sockets instead of XML-RPC.
|
||||
|
||||
### How It Works
|
||||
|
||||
```text
|
||||
MCP Client <--stdio--> MCP Server <--JSON-RPC:9876--> FreeCAD
|
||||
```
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
export FREECAD_MODE=socket
|
||||
export FREECAD_SOCKET_HOST=localhost
|
||||
export FREECAD_SOCKET_PORT=9876
|
||||
freecad-mcp
|
||||
```
|
||||
|
||||
### Advantages
|
||||
|
||||
- JSON-based protocol (easier to debug)
|
||||
- Lower overhead than XML-RPC
|
||||
- Works on all platforms
|
||||
|
||||
---
|
||||
|
||||
## Embedded Mode (Linux Only)
|
||||
|
||||
!!! danger "Platform Limitation"
|
||||
Embedded mode **only works on Linux**. On macOS and Windows, it causes crashes due to Python ABI incompatibility.
|
||||
|
||||
Embedded mode imports FreeCAD directly into the MCP server process, providing the fastest execution.
|
||||
|
||||
### Why It Crashes on macOS/Windows
|
||||
|
||||
FreeCAD's `FreeCAD.so` library links to `@rpath/libpython3.11.dylib` (FreeCAD's bundled Python). When you try to import it from a different Python interpreter (even the same version), it causes a crash because the Python runtime state is incompatible.
|
||||
|
||||
### Setup (Linux Only)
|
||||
|
||||
```bash
|
||||
export FREECAD_MODE=embedded
|
||||
export FREECAD_PATH=/usr/lib/freecad/lib # Adjust for your system
|
||||
freecad-mcp
|
||||
```
|
||||
|
||||
### Advantages
|
||||
|
||||
- Fastest execution (no IPC overhead)
|
||||
- No need to start FreeCAD separately
|
||||
- Works in CI/CD environments on Linux
|
||||
|
||||
### Limitations
|
||||
|
||||
- **Linux only** - crashes on macOS and Windows
|
||||
- Headless only (no GUI features)
|
||||
- **Minimal testing** - embedded mode receives less testing than xmlrpc/socket modes
|
||||
- Cannot access FreeCAD GUI features (screenshots, colors, etc.)
|
||||
|
||||
### Testing Status
|
||||
|
||||
Embedded mode is tested in the CI pipeline with unit tests that mock FreeCAD. However, full integration testing with actual FreeCAD is limited compared to the xmlrpc and socket modes which are tested with the FreeCAD AppImage.
|
||||
|
||||
---
|
||||
|
||||
## Choosing a Mode
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Need FreeCAD MCP?] --> B{Platform?}
|
||||
B -->|macOS/Windows| C[Use xmlrpc or socket]
|
||||
B -->|Linux| D{Need GUI features?}
|
||||
D -->|Yes| C
|
||||
D -->|No| E{Need fastest execution?}
|
||||
E -->|Yes| F[Consider embedded]
|
||||
E -->|No| C
|
||||
```
|
||||
|
||||
### Recommendations
|
||||
|
||||
| Use Case | Recommended Mode |
|
||||
| ----------------------------- | ---------------- |
|
||||
| General development | `xmlrpc` |
|
||||
| Interactive modeling with GUI | `xmlrpc` |
|
||||
| CI/CD pipelines on Linux | `embedded` |
|
||||
| Docker containers | `xmlrpc` |
|
||||
| Remote FreeCAD instance | `xmlrpc` |
|
||||
| Debugging connection issues | `socket` |
|
||||
|
||||
---
|
||||
|
||||
## Headless vs GUI Mode
|
||||
|
||||
Independent of connection mode, FreeCAD itself can run in GUI or 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 |
|
||||
|
||||
### Starting FreeCAD
|
||||
|
||||
**GUI Mode:**
|
||||
|
||||
```bash
|
||||
# Using workbench - just start FreeCAD and click "Start Bridge"
|
||||
just freecad::run-gui # From source
|
||||
```
|
||||
|
||||
**Headless Mode:**
|
||||
|
||||
```bash
|
||||
FreeCADCmd /path/to/headless_server.py
|
||||
just freecad::run-headless # From source
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Refused
|
||||
|
||||
```text
|
||||
Error: Connection refused on localhost:9875
|
||||
```
|
||||
|
||||
**Solution:** Ensure FreeCAD is running with the MCP Bridge started. Check the bridge status in FreeCAD's toolbar.
|
||||
|
||||
### Embedded Mode Crash on macOS
|
||||
|
||||
```text
|
||||
SIGSEGV: Segmentation fault
|
||||
```
|
||||
|
||||
**Solution:** Embedded mode doesn't work on macOS. Switch to `xmlrpc` or `socket` mode.
|
||||
|
||||
### Timeout Errors
|
||||
|
||||
```text
|
||||
Error: Execution timed out after 30000ms
|
||||
```
|
||||
|
||||
**Solution:** Increase the timeout with `FREECAD_TIMEOUT_MS=60000` or optimize your operation.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Tools Reference](tools.md) - Complete API for all 82+ tools
|
||||
- [MCP Resources](resources.md) - Query FreeCAD state via MCP resources
|
||||
@@ -0,0 +1,218 @@
|
||||
# FreeCAD Macros
|
||||
|
||||
This project includes standalone FreeCAD macros that work independently of the MCP server, plus MCP tools for creating and managing macros programmatically.
|
||||
|
||||
---
|
||||
|
||||
## Included Macros
|
||||
|
||||
### CutObjectForMagnets
|
||||
|
||||
Cut an object along a plane and add aligned magnet holes with surface collision detection. Perfect for creating 3D printed parts that snap together with embedded magnets.
|
||||
|
||||
**Features:**
|
||||
|
||||
- Interactive plane selection via GUI
|
||||
- Automatic magnet hole placement with configurable grid
|
||||
- Surface collision detection to avoid invalid hole positions
|
||||
- Configurable magnet dimensions and tolerances
|
||||
|
||||
**Usage:**
|
||||
|
||||
1. Select an object in FreeCAD
|
||||
1. Run the macro
|
||||
1. Define the cutting plane interactively
|
||||
1. Configure magnet parameters
|
||||
1. The macro creates two halves with aligned magnet holes
|
||||
|
||||
See [CutObjectForMagnets documentation](https://github.com/spkane/freecad-robust-mcp-and-more/tree/main/macros/Cut_Object_for_Magnets) for detailed usage.
|
||||
|
||||
### MultiExport
|
||||
|
||||
Export selected bodies to multiple file formats simultaneously with configurable mesh options.
|
||||
|
||||
**Supported Formats:**
|
||||
|
||||
- STL (ASCII and Binary)
|
||||
- STEP
|
||||
- 3MF
|
||||
- OBJ
|
||||
- IGES
|
||||
- BREP
|
||||
- PLY
|
||||
- AMF
|
||||
|
||||
**Usage:**
|
||||
|
||||
1. Select one or more bodies/parts
|
||||
1. Run the macro
|
||||
1. Select output formats and configure mesh options
|
||||
1. Choose output directory
|
||||
1. All exports are created with consistent naming
|
||||
|
||||
See [MultiExport documentation](https://github.com/spkane/freecad-robust-mcp-and-more/tree/main/macros/Multi_Export) for detailed usage.
|
||||
|
||||
---
|
||||
|
||||
## Installing Macros
|
||||
|
||||
### Via FreeCAD Addon Manager
|
||||
|
||||
When you install the "FreeCAD MCP and More" addon, the macros are installed automatically.
|
||||
|
||||
### Manual Installation
|
||||
|
||||
1. Download macros from [GitHub Releases](https://github.com/spkane/freecad-robust-mcp-and-more/releases)
|
||||
1. Copy `.FCMacro` files to your macro directory:
|
||||
- **Linux:** `~/.local/share/FreeCAD/Macro/`
|
||||
- **macOS:** `~/Library/Application Support/FreeCAD/Macro/`
|
||||
- **Windows:** `%APPDATA%\FreeCAD\Macro\`
|
||||
|
||||
---
|
||||
|
||||
## MCP Macro Tools
|
||||
|
||||
The MCP server provides tools for working with macros programmatically:
|
||||
|
||||
### list_macros
|
||||
|
||||
List available macros in FreeCAD's macro directories.
|
||||
|
||||
```python
|
||||
list_macros() -> list[dict]
|
||||
```
|
||||
|
||||
**Returns:** List of macros with name, path, description, and whether it's a system macro.
|
||||
|
||||
### run_macro
|
||||
|
||||
Execute a macro by name with optional arguments.
|
||||
|
||||
```python
|
||||
run_macro(
|
||||
macro_name: str,
|
||||
args: dict | None = None
|
||||
) -> dict
|
||||
```
|
||||
|
||||
**Example prompt:**
|
||||
|
||||
```text
|
||||
"Run the MultiExport macro"
|
||||
```
|
||||
|
||||
### create_macro
|
||||
|
||||
Create a new macro programmatically.
|
||||
|
||||
```python
|
||||
create_macro(
|
||||
name: str,
|
||||
code: str,
|
||||
description: str = ""
|
||||
) -> dict
|
||||
```
|
||||
|
||||
**Example prompt:**
|
||||
|
||||
```text
|
||||
"Create a macro called 'CreateBox' that makes a 10x10x10 box"
|
||||
```
|
||||
|
||||
### read_macro
|
||||
|
||||
Read the source code of an existing macro.
|
||||
|
||||
```python
|
||||
read_macro(macro_name: str) -> dict
|
||||
```
|
||||
|
||||
**Example prompt:**
|
||||
|
||||
```text
|
||||
"Show me the code for the MultiExport macro"
|
||||
```
|
||||
|
||||
### delete_macro
|
||||
|
||||
Delete a user macro (system macros are protected).
|
||||
|
||||
```python
|
||||
delete_macro(macro_name: str) -> dict
|
||||
```
|
||||
|
||||
### create_macro_from_template
|
||||
|
||||
Create a macro from predefined templates.
|
||||
|
||||
```python
|
||||
create_macro_from_template(
|
||||
name: str,
|
||||
template: str = "basic",
|
||||
description: str = ""
|
||||
) -> dict
|
||||
```
|
||||
|
||||
**Available templates:**
|
||||
|
||||
| Template | Description |
|
||||
| ----------- | --------------------------- |
|
||||
| `basic` | Minimal macro with imports |
|
||||
| `part` | Part workbench operations |
|
||||
| `sketch` | Sketcher operations |
|
||||
| `gui` | GUI/dialog template |
|
||||
| `selection` | Selection handling template |
|
||||
|
||||
**Example prompt:**
|
||||
|
||||
```text
|
||||
"Create a new macro from the 'sketch' template called 'DrawGear'"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Macro Development with AI
|
||||
|
||||
The MCP server excels at helping develop FreeCAD macros. Example workflows:
|
||||
|
||||
### Debugging an Existing Macro
|
||||
|
||||
```text
|
||||
"Read the macro 'MyMacro' and explain what it does"
|
||||
```
|
||||
|
||||
```text
|
||||
"Run the macro and show me any errors from the FreeCAD console"
|
||||
```
|
||||
|
||||
### Creating a New Macro
|
||||
|
||||
```text
|
||||
"Create a macro that:
|
||||
1. Gets all selected objects
|
||||
2. Calculates their combined bounding box
|
||||
3. Creates a box around them with 5mm clearance"
|
||||
```
|
||||
|
||||
### Modifying a Macro
|
||||
|
||||
```text
|
||||
"Read the 'ExportSTL' macro and modify it to also export STEP files"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices for Macro Development
|
||||
|
||||
1. **Use templates** - Start from `create_macro_from_template` for proper imports
|
||||
1. **Test incrementally** - Use `execute_python` for testing snippets before creating full macros
|
||||
1. **Check console output** - Use `get_console_output` to debug issues
|
||||
1. **Document your macros** - Add docstrings that explain parameters and usage
|
||||
1. **Handle errors gracefully** - Wrap operations in try/except blocks
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Tools Reference](tools.md) - Complete API for all MCP tools
|
||||
- [Workbench](workbench.md) - MCP Bridge Workbench details
|
||||
@@ -0,0 +1,335 @@
|
||||
# MCP Resources
|
||||
|
||||
The FreeCAD MCP server exposes several resources that allow AI assistants to query FreeCAD's state without executing code.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
MCP Resources are read-only endpoints that provide context about FreeCAD's current state. They're useful for:
|
||||
|
||||
- Understanding what documents and objects exist
|
||||
- Getting system information
|
||||
- Discovering available capabilities
|
||||
|
||||
---
|
||||
|
||||
## Available Resources
|
||||
|
||||
The MCP server provides 12 resources for querying FreeCAD state:
|
||||
|
||||
### freecad://capabilities
|
||||
|
||||
Returns a comprehensive JSON catalog of all available tools, resources, and prompts.
|
||||
|
||||
**Use case:** Understanding what the MCP server can do.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"execution": ["execute_python", "get_freecad_version", ...],
|
||||
"documents": ["create_document", "open_document", ...],
|
||||
...
|
||||
},
|
||||
"resources": ["freecad://capabilities", "freecad://documents", ...],
|
||||
"prompts": ["freecad-help", "create-parametric-part", ...]
|
||||
}
|
||||
```
|
||||
|
||||
### freecad://version
|
||||
|
||||
Gets FreeCAD version and build information.
|
||||
|
||||
**Use case:** Checking FreeCAD compatibility and environment.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"build_date": "2024-01-15",
|
||||
"python_version": "3.11.6",
|
||||
"gui_available": true
|
||||
}
|
||||
```
|
||||
|
||||
### freecad://status
|
||||
|
||||
Gets current FreeCAD connection and runtime status.
|
||||
|
||||
**Use case:** Verifying connection health and mode.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"connected": true,
|
||||
"mode": "xmlrpc",
|
||||
"freecad_version": "1.0.0",
|
||||
"gui_available": true,
|
||||
"last_ping_ms": 12.5,
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
### freecad://documents
|
||||
|
||||
Lists all open FreeCAD documents with basic information.
|
||||
|
||||
**Use case:** Seeing what documents are currently open.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "MyPart",
|
||||
"label": "My Part Design",
|
||||
"path": "/home/user/projects/mypart.FCStd",
|
||||
"is_modified": true,
|
||||
"object_count": 15,
|
||||
"active_object": "Pad"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### freecad://documents/{name}
|
||||
|
||||
Gets detailed information about a specific document.
|
||||
|
||||
**Use case:** Examining a document's contents.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "MyPart",
|
||||
"label": "My Part Design",
|
||||
"path": "/home/user/projects/mypart.FCStd",
|
||||
"objects": ["Body", "Sketch", "Pad", "Fillet"],
|
||||
"is_modified": true,
|
||||
"active_object": "Fillet"
|
||||
}
|
||||
```
|
||||
|
||||
### freecad://documents/{name}/objects
|
||||
|
||||
Gets list of objects in a specific document.
|
||||
|
||||
**Use case:** Listing all objects in a document with their types.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "Body",
|
||||
"label": "Body",
|
||||
"type_id": "PartDesign::Body",
|
||||
"visibility": true
|
||||
},
|
||||
{
|
||||
"name": "Sketch",
|
||||
"label": "Sketch",
|
||||
"type_id": "Sketcher::SketchObject",
|
||||
"visibility": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### freecad://objects/{doc_name}/{obj_name}
|
||||
|
||||
Gets detailed information about a specific object including properties and shape data.
|
||||
|
||||
**Use case:** Inspecting object properties and geometry.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Pad",
|
||||
"label": "Pad",
|
||||
"type_id": "PartDesign::Pad",
|
||||
"properties": {
|
||||
"Length": 10.0,
|
||||
"Type": "Length",
|
||||
"Symmetric": false
|
||||
},
|
||||
"shape_info": {
|
||||
"shape_type": "Solid",
|
||||
"volume": 1000.0,
|
||||
"area": 600.0,
|
||||
"is_valid": true
|
||||
},
|
||||
"children": [],
|
||||
"parents": ["Sketch"],
|
||||
"visibility": true
|
||||
}
|
||||
```
|
||||
|
||||
### freecad://active-document
|
||||
|
||||
Gets the currently active document.
|
||||
|
||||
**Use case:** Quick access to the document the user is working on.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "MyPart",
|
||||
"label": "My Part Design",
|
||||
"path": "/home/user/projects/mypart.FCStd",
|
||||
"objects": ["Body", "Sketch", "Pad"],
|
||||
"is_modified": false,
|
||||
"active_object": "Pad"
|
||||
}
|
||||
```
|
||||
|
||||
### freecad://workbenches
|
||||
|
||||
Gets list of available FreeCAD workbenches.
|
||||
|
||||
**Use case:** Understanding what workbenches are available.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "PartDesignWorkbench",
|
||||
"label": "Part Design",
|
||||
"is_active": true
|
||||
},
|
||||
{
|
||||
"name": "SketcherWorkbench",
|
||||
"label": "Sketcher",
|
||||
"is_active": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### freecad://workbenches/active
|
||||
|
||||
Gets the currently active workbench.
|
||||
|
||||
**Use case:** Knowing which workbench context is active.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "PartDesignWorkbench",
|
||||
"label": "Part Design"
|
||||
}
|
||||
```
|
||||
|
||||
### freecad://macros
|
||||
|
||||
Gets list of available FreeCAD macros.
|
||||
|
||||
**Use case:** Discovering available automation macros.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "MultiExport",
|
||||
"path": "/home/user/.local/share/FreeCAD/Macro/MultiExport.FCMacro",
|
||||
"description": "Export objects to multiple formats",
|
||||
"is_system": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### freecad://console
|
||||
|
||||
Gets recent FreeCAD console output.
|
||||
|
||||
**Use case:** Debugging and seeing FreeCAD messages.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"lines": [
|
||||
"MCP Bridge started!",
|
||||
" - XML-RPC: localhost:9875",
|
||||
" - Socket: localhost:9876",
|
||||
"Document created: MyPart"
|
||||
],
|
||||
"count": 4
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using Resources in Prompts
|
||||
|
||||
When talking to an AI assistant connected via MCP, resources are automatically available. The AI can read them to understand context.
|
||||
|
||||
**Example conversation:**
|
||||
|
||||
```text
|
||||
User: "What documents do I have open?"
|
||||
|
||||
AI: [Reads freecad://documents resource]
|
||||
"You have two documents open:
|
||||
1. 'Bracket' - modified, 12 objects
|
||||
2. 'Housing' - saved, 8 objects"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resources vs Tools
|
||||
|
||||
| Aspect | Resources | Tools |
|
||||
| ------------ | ----------------------- | -------------------- |
|
||||
| Purpose | Query state (read-only) | Perform actions |
|
||||
| Side effects | None | May modify documents |
|
||||
| Response | Data/text | Operation result |
|
||||
| Example | `freecad://documents` | `create_document()` |
|
||||
|
||||
---
|
||||
|
||||
## Resource URI Summary
|
||||
|
||||
| URI | Description |
|
||||
| ----------------------------------------- | ---------------------------------------- |
|
||||
| `freecad://capabilities` | All available tools, resources, prompts |
|
||||
| `freecad://version` | FreeCAD version and build info |
|
||||
| `freecad://status` | Connection status and mode |
|
||||
| `freecad://documents` | List of open documents |
|
||||
| `freecad://documents/{name}` | Single document details |
|
||||
| `freecad://documents/{name}/objects` | Objects in a document |
|
||||
| `freecad://objects/{doc_name}/{obj_name}` | Detailed object information |
|
||||
| `freecad://active-document` | Currently active document |
|
||||
| `freecad://workbenches` | Available workbenches |
|
||||
| `freecad://workbenches/active` | Currently active workbench |
|
||||
| `freecad://macros` | Available macros |
|
||||
| `freecad://console` | Recent console output |
|
||||
|
||||
---
|
||||
|
||||
## Implementing Custom Resources
|
||||
|
||||
If you're extending the MCP server, you can add custom resources:
|
||||
|
||||
```python
|
||||
@mcp.resource("freecad://custom/{param}")
|
||||
async def my_custom_resource(param: str) -> str:
|
||||
"""Return custom data based on param."""
|
||||
# Query FreeCAD and return data
|
||||
result = await bridge.execute_python(f"...")
|
||||
return json.dumps(result)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Tools Reference](tools.md) - Complete API for MCP tools
|
||||
- [Connection Modes](connection-modes.md) - How to connect to FreeCAD
|
||||
@@ -0,0 +1,219 @@
|
||||
# Tools Reference
|
||||
|
||||
The FreeCAD MCP server provides 82+ tools for CAD operations. This page provides a quick reference organized by category.
|
||||
|
||||
For detailed documentation including parameters and examples, see [MCP Tools Reference](../MCP_TOOLS_REFERENCE.md).
|
||||
|
||||
---
|
||||
|
||||
## Tool Categories
|
||||
|
||||
| Category | Tools | Description |
|
||||
| ------------------------------- | ----- | ------------------------------------ |
|
||||
| [Execution](#execution-tools) | 5 | Python execution, debugging |
|
||||
| [Documents](#document-tools) | 7 | Document management |
|
||||
| [Primitives](#primitive-tools) | 8 | Basic 3D shapes |
|
||||
| [Objects](#object-tools) | 12 | Object manipulation |
|
||||
| [PartDesign](#partdesign-tools) | 19 | Parametric modeling |
|
||||
| [View & Display](#view-tools) | 11 | View control, screenshots (GUI only) |
|
||||
| [Export/Import](#export-tools) | 7 | File format conversion |
|
||||
| [Macros](#macro-tools) | 6 | Macro management |
|
||||
| [Utility](#utility-tools) | 7 | Undo/redo, parts library |
|
||||
|
||||
---
|
||||
|
||||
## Execution Tools
|
||||
|
||||
| Tool | Description |
|
||||
| ---------------------------- | ----------------------------------- |
|
||||
| `execute_python` | Execute arbitrary Python in FreeCAD |
|
||||
| `get_freecad_version` | Get FreeCAD version and build info |
|
||||
| `get_connection_status` | Check MCP bridge connection |
|
||||
| `get_console_output` | Get recent console output |
|
||||
| `get_mcp_server_environment` | Get MCP server environment info |
|
||||
|
||||
---
|
||||
|
||||
## Document Tools
|
||||
|
||||
| Tool | Description |
|
||||
| --------------------- | ----------------------------- |
|
||||
| `list_documents` | List all open documents |
|
||||
| `get_active_document` | Get currently active document |
|
||||
| `create_document` | Create a new document |
|
||||
| `open_document` | Open an existing .FCStd file |
|
||||
| `save_document` | Save a document |
|
||||
| `close_document` | Close a document |
|
||||
| `recompute_document` | Recompute all features |
|
||||
|
||||
---
|
||||
|
||||
## Primitive Tools
|
||||
|
||||
| Tool | Description |
|
||||
| ----------------- | ---------------------------- |
|
||||
| `create_box` | Create a parametric box |
|
||||
| `create_cylinder` | Create a parametric cylinder |
|
||||
| `create_sphere` | Create a parametric sphere |
|
||||
| `create_cone` | Create a parametric cone |
|
||||
| `create_torus` | Create a torus (donut) |
|
||||
| `create_wedge` | Create a tapered wedge |
|
||||
| `create_helix` | Create a helix curve |
|
||||
| `create_object` | Create any object by type ID |
|
||||
|
||||
---
|
||||
|
||||
## Object Tools
|
||||
|
||||
| Tool | Description |
|
||||
| ------------------- | -------------------------------- |
|
||||
| `list_objects` | List objects in a document |
|
||||
| `inspect_object` | Get detailed object information |
|
||||
| `edit_object` | Modify object properties |
|
||||
| `delete_object` | Delete an object |
|
||||
| `boolean_operation` | Union, cut, or intersect objects |
|
||||
| `set_placement` | Set position and rotation |
|
||||
| `rotate_object` | Rotate around an axis |
|
||||
| `scale_object` | Scale uniformly or non-uniformly |
|
||||
| `copy_object` | Create a copy |
|
||||
| `mirror_object` | Mirror across a plane |
|
||||
| `get_selection` | Get selected objects (GUI) |
|
||||
| `set_selection` | Select objects (GUI) |
|
||||
| `clear_selection` | Clear selection (GUI) |
|
||||
|
||||
---
|
||||
|
||||
## PartDesign Tools
|
||||
|
||||
### Bodies and Sketches
|
||||
|
||||
| Tool | Description |
|
||||
| ------------------------ | ------------------------------- |
|
||||
| `create_partdesign_body` | Create a PartDesign body |
|
||||
| `create_sketch` | Create a sketch on a plane/face |
|
||||
|
||||
### Sketch Geometry
|
||||
|
||||
| Tool | Description |
|
||||
| ---------------------- | ----------------------- |
|
||||
| `add_sketch_rectangle` | Add rectangle to sketch |
|
||||
| `add_sketch_circle` | Add circle to sketch |
|
||||
| `add_sketch_line` | Add line to sketch |
|
||||
| `add_sketch_arc` | Add arc to sketch |
|
||||
| `add_sketch_point` | Add point to sketch |
|
||||
|
||||
### Additive Features
|
||||
|
||||
| Tool | Description |
|
||||
| ------------------- | ------------------------------ |
|
||||
| `pad_sketch` | Extrude sketch (additive) |
|
||||
| `revolution_sketch` | Revolve sketch around axis |
|
||||
| `loft_sketches` | Loft through multiple sketches |
|
||||
| `sweep_sketch` | Sweep profile along path |
|
||||
|
||||
### Subtractive Features
|
||||
|
||||
| Tool | Description |
|
||||
| --------------- | ----------------------- |
|
||||
| `pocket_sketch` | Cut by extruding sketch |
|
||||
| `groove_sketch` | Cut by revolving sketch |
|
||||
| `create_hole` | Create parametric holes |
|
||||
|
||||
### Edge Operations & Patterns
|
||||
|
||||
| Tool | Description |
|
||||
| ------------------ | --------------------------- |
|
||||
| `fillet_edges` | Add rounded edges |
|
||||
| `chamfer_edges` | Add beveled edges |
|
||||
| `linear_pattern` | Repeat feature linearly |
|
||||
| `polar_pattern` | Repeat feature circularly |
|
||||
| `mirrored_feature` | Mirror feature across plane |
|
||||
|
||||
---
|
||||
|
||||
## View Tools
|
||||
|
||||
!!! warning "GUI Mode Required"
|
||||
Tools marked with **GUI** only work when FreeCAD is running in GUI mode.
|
||||
|
||||
| Tool | Mode | Description |
|
||||
| ----------------------- | ---- | ---------------------------------- |
|
||||
| `get_screenshot` | GUI | Capture 3D view screenshot |
|
||||
| `set_view_angle` | Both | Set camera angle |
|
||||
| `fit_all` | Both | Fit all objects in view |
|
||||
| `zoom_in` | GUI | Zoom in |
|
||||
| `zoom_out` | GUI | Zoom out |
|
||||
| `set_camera_position` | GUI | Set exact camera position |
|
||||
| `set_object_visibility` | GUI | Show/hide objects |
|
||||
| `set_display_mode` | GUI | Set display mode (wireframe, etc.) |
|
||||
| `set_object_color` | GUI | Change object color |
|
||||
| `list_workbenches` | Both | List available workbenches |
|
||||
| `activate_workbench` | Both | Switch workbench |
|
||||
|
||||
---
|
||||
|
||||
## Export Tools
|
||||
|
||||
| Tool | Description |
|
||||
| ------------- | ---------------------------------- |
|
||||
| `export_step` | Export to STEP format |
|
||||
| `export_stl` | Export to STL (3D printing) |
|
||||
| `export_3mf` | Export to 3MF (modern 3D printing) |
|
||||
| `export_obj` | Export to OBJ format |
|
||||
| `export_iges` | Export to IGES format |
|
||||
| `import_step` | Import STEP files |
|
||||
| `import_stl` | Import STL files |
|
||||
|
||||
---
|
||||
|
||||
## Macro Tools
|
||||
|
||||
| Tool | Description |
|
||||
| ---------------------------- | ------------------------------- |
|
||||
| `list_macros` | List available macros |
|
||||
| `run_macro` | Execute a macro |
|
||||
| `create_macro` | Create a new macro |
|
||||
| `read_macro` | Read macro source code |
|
||||
| `delete_macro` | Delete a user macro |
|
||||
| `create_macro_from_template` | Create from predefined template |
|
||||
|
||||
---
|
||||
|
||||
## Utility Tools
|
||||
|
||||
| Tool | Description |
|
||||
| -------------------------- | --------------------------- |
|
||||
| `undo` | Undo last operation |
|
||||
| `redo` | Redo undone operation |
|
||||
| `get_undo_redo_status` | Get undo/redo availability |
|
||||
| `recompute` | Force recompute all objects |
|
||||
| `get_console_log` | Get console log with levels |
|
||||
| `list_parts_library` | List parts library |
|
||||
| `insert_part_from_library` | Insert part from library |
|
||||
|
||||
---
|
||||
|
||||
## GUI vs Headless Mode
|
||||
|
||||
When running in headless mode, GUI-only tools return structured errors instead of crashing:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "GUI not available - screenshots cannot be captured in headless mode"
|
||||
}
|
||||
```
|
||||
|
||||
To check the current mode programmatically:
|
||||
|
||||
```python
|
||||
result = await execute_python("_result_ = FreeCAD.GuiUp")
|
||||
is_gui_mode = result["result"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [MCP Tools Reference](../MCP_TOOLS_REFERENCE.md) - Detailed documentation with parameters and examples
|
||||
- [MCP Resources](resources.md) - Query FreeCAD state via MCP resources
|
||||
@@ -0,0 +1,220 @@
|
||||
# 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.
|
||||
+61
-32
@@ -4,47 +4,35 @@ Welcome to the FreeCAD MCP Server documentation.
|
||||
|
||||
This project provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that enables integration between AI assistants (Claude, GPT, and other MCP-compatible tools) and [FreeCAD](https://www.freecadweb.org/), allowing AI-assisted development and debugging of 3D models, macros, and workbenches.
|
||||
|
||||
## Documentation
|
||||
---
|
||||
|
||||
| Document | Description |
|
||||
| --------------------------------------------- | ------------------------------------------------------ |
|
||||
| [README](../README.md) | Project overview, installation, and configuration |
|
||||
| [User Guide](USER_GUIDE.md) | How to use AI assistants with FreeCAD for CAD modeling |
|
||||
| [MCP Tools Reference](MCP_TOOLS_REFERENCE.md) | Complete API reference for all 82+ MCP tools |
|
||||
| [Architecture](../ARCHITECTURE-MCP.md) | Technical design and module structure |
|
||||
| [Comparison](COMPARISON.md) | Analysis of other FreeCAD MCP implementations |
|
||||
| [CLAUDE.md](../CLAUDE.md) | AI assistant guidelines for this project |
|
||||
## 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 MCP server
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Clone and setup
|
||||
git clone https://github.com/spkane/freecad-robust-mcp-and-more.git
|
||||
cd freecad-robust-mcp-and-more
|
||||
# Install the MCP server
|
||||
pip install freecad-robust-mcp
|
||||
|
||||
# Install mise via the Official mise installer script (if not already installed)
|
||||
curl https://mise.run | sh
|
||||
# Install the workbench via FreeCAD Addon Manager
|
||||
# (search for "FreeCAD MCP and More")
|
||||
|
||||
mise install
|
||||
just setup
|
||||
# Start FreeCAD and click "Start Bridge" in the MCP Bridge workbench
|
||||
|
||||
# Start FreeCAD with MCP bridge
|
||||
just install-bridge-macro
|
||||
just run-gui
|
||||
|
||||
# Run the MCP server (in another terminal or via your MCP client)
|
||||
FREECAD_MODE=xmlrpc freecad-mcp
|
||||
# Configure your MCP client and start building!
|
||||
```
|
||||
|
||||
See the [README](../README.md) for detailed installation and configuration instructions.
|
||||
See [Installation](getting-started/installation.md) for detailed setup instructions.
|
||||
|
||||
## Features
|
||||
|
||||
- **82+ MCP Tools**: Comprehensive CAD operations including primitives, PartDesign, booleans, export
|
||||
- **Multiple Connection Modes**: XML-RPC (recommended), JSON-RPC socket, or embedded
|
||||
- **GUI & Headless Support**: Full modeling in headless mode, plus screenshots/colors in GUI mode
|
||||
- **Macro Development**: Create, edit, run, and template FreeCAD macros
|
||||
- **PartDesign Workflow**: Parametric modeling with sketches, pads, pockets, fillets, patterns
|
||||
---
|
||||
|
||||
## Connection Modes
|
||||
|
||||
@@ -54,9 +42,50 @@ See the [README](../README.md) for detailed installation and configuration instr
|
||||
| `socket` | JSON-RPC socket (port 9876) | All platforms |
|
||||
| `embedded` | In-process FreeCAD | Linux only |
|
||||
|
||||
See [Connection Modes](guide/connection-modes.md) for details on choosing the right mode.
|
||||
|
||||
---
|
||||
|
||||
## GUI vs Headless Mode
|
||||
|
||||
The 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:
|
||||
|
||||
- **[StartMCPBridge](../macros/Start_MCP_Bridge/)** - Starts the MCP bridge server for AI assistant integration
|
||||
- **[CutObjectForMagnets](../macros/Cut_Object_for_Magnets/)** - Cuts objects along planes with automatic magnet hole placement
|
||||
- **[CutObjectForMagnets](guide/macros.md#cutobjectformagnets)** - Cuts objects along planes with automatic magnet hole placement
|
||||
- **[MultiExport](guide/macros.md#multiexport)** - Export objects to multiple formats simultaneously
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
| Section | Description |
|
||||
| -------------------------------------------------- | ------------------------------------------------- |
|
||||
| [Getting Started](getting-started/installation.md) | Installation, configuration, and quick start |
|
||||
| [User Guide](guide/connection-modes.md) | Connection modes, workbench, macros, and tools |
|
||||
| [Tools Reference](MCP_TOOLS_REFERENCE.md) | Complete API reference for all 82+ MCP tools |
|
||||
| [API Reference](api/server.md) | Python API documentation |
|
||||
| [Development](development/contributing.md) | Contributing, architecture, and development setup |
|
||||
| [Comparison](COMPARISON.md) | Analysis of other FreeCAD MCP implementations |
|
||||
|
||||
---
|
||||
|
||||
## Links
|
||||
|
||||
- [GitHub Repository](https://github.com/spkane/freecad-robust-mcp-and-more)
|
||||
- [PyPI Package](https://pypi.org/project/freecad-robust-mcp/)
|
||||
- [Docker Hub](https://hub.docker.com/r/spkane/freecad-robust-mcp)
|
||||
- [Issue Tracker](https://github.com/spkane/freecad-robust-mcp-and-more/issues)
|
||||
|
||||
Reference in New Issue
Block a user