forkless/freecad-robust-mcp-fc111
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor (#37)

Browse Source 
* refactor: remove macros

* refactor: additional cleanup

* chore: small cleanup

* refactor: update .coderabbit.yaml configuration

* docs: update CLAUDE.md with new documentation

* docs: table alignment
This commit is contained in:
Sean P. Kane
2026-01-17 21:24:37 -08:00
committed by GitHub
parent 62f6f4dbcf
commit 47e80f1bc7
46 changed files with 356 additions and 7425 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/development/architecture.md
+83
View File
@@ -259,6 +259,89 @@ Embedded mode receives **minimal testing**:
---
## Future Considerations
### Bundled vs. Separate Server Architecture
The current architecture keeps the MCP server separate from the FreeCAD addon/workbench. This section documents the trade-offs and potential future directions.
#### Current Approach: Separate Components
```text
┌─────────────────┐ XML-RPC/Socket ┌─────────────────┐
│ MCP Server │◄──────────────────────►│ FreeCAD │
│ (separate venv) │ │ (+ Workbench) │
└─────────────────┘ └─────────────────┘
```
**Advantages:**
- Server runs in its own Python environment with full control over dependencies
- Allows remote server scenarios (AI/server on powerful machine, FreeCAD on workstation)
- Server can be updated independently of the addon
- No dependency conflicts with FreeCAD's embedded Python
- Easier testing and development
**Disadvantages:**
- Users must install two components separately
- More complex setup process
- Need to manage version compatibility between server and workbench
#### Potential Future: Bundled Server in Addon
```text
┌─────────────────────────────────────────┐
│ FreeCAD Addon │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ Workbench │◄──►│ Bundled Server │ │
│ │ (GUI) │ │ (subprocess) │ │
│ └─────────────┘ └─────────────────┘ │
└─────────────────────────────────────────┘
```
A bundled approach could:
- Provide single-install experience from FreeCAD Addon Manager
- Auto-start server when workbench loads
- Still support "Remote Server" mode for advanced users via preferences
**Implementation considerations:**
1. **Dependency management**: Server requires `fastmcp`, `httpx`, `uvicorn`, etc. These may conflict with FreeCAD's Python. Options:
- Bundle dependencies in addon (vendor them)
- Use subprocess with bundled `requirements.txt` and pip install on first run
- Create a minimal server that uses only stdlib
2. **Startup modes**:
```python
if preferences.use_remote_server:
connect_to(preferences.server_url)
else:
# Start bundled server in subprocess
subprocess.Popen([sys.executable, "-m", "robust_mcp_server"])
```
3. **Hybrid approach**: Default to bundled local server, but expose preferences for remote server URL (host:port) for advanced deployments.
#### Decision
Currently maintaining separate components because:
- Cleaner separation of concerns
- Proven reliability across platforms
- Easier to develop and test independently
- Remote server use case, while less common, is valuable for some workflows
May revisit bundling in a future major version when:
- Dependency requirements stabilize
- User feedback indicates strong preference for single-install
- A clean subprocess-based bundling approach is validated
---
## Next Steps
- [Contributing](contributing.md) - How to contribute
docs/development/contributing.md
-1
View File
@@ -89,7 +89,6 @@ freecad-robust-mcp-and-more/
│ └── server.py # Main server entry point
├── addon/ # FreeCAD workbench addon
│ └── FreecadRobustMCPBridge/ # Workbench files
├── macros/ # Standalone FreeCAD macros
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
docs/development/releasing.md
+20 -145
View File
@@ -1,6 +1,6 @@
# Release Process
This project uses **component-specific versioning**. Each component (MCP Server, Workbench, Macros) has its own version and release cycle, allowing independent updates without affecting other components.
This project uses **component-specific versioning**. Each component (MCP Server, Workbench) has its own version and release cycle, allowing independent updates without affecting other components.
## Quick Start
@@ -9,46 +9,39 @@ The complete release workflow in order:
```bash
# 1. Pre-release checks
just release::status # Check which components have unreleased changes
just release::changes-since mcp-server # View specific changes (or workbench, macro-magnets, macro-export)
just release::changes-since mcp-server # View specific changes (or workbench)
just all # Run all quality checks (must pass)
# 2. Update release notes
just release::draft-notes mcp-server # Generate draft notes from commits
# Then edit the component's RELEASE_NOTES.md file (see "Release Notes Files" below)
# 3. Version bump (workbench & macros only - MCP Server uses setuptools-scm)
just release::bump-workbench 1.0.0 # or bump-macro-magnets, bump-macro-export
# 3. Version bump (workbench only - MCP Server uses setuptools-scm)
just release::bump-workbench 1.0.0
# 4. Commit changes
git add -A
git commit -m "chore: bump workbench to 1.0.0" # or appropriate component/message
# 5. Create & push tag (triggers CI/CD automatically)
just release::tag-workbench 1.0.0 # or tag-mcp-server, tag-macro-magnets, tag-macro-export
just release::tag-workbench 1.0.0 # or tag-mcp-server
# 6. Monitor release at GitHub Actions, then verify
just release::list-tags
just release::latest-versions
# 7. Update FreeCAD wiki (macros only)
just release::wiki-update macro-magnets # Copies content to clipboard & opens wiki edit page
```
| Component | Bump Command | Tag Command |
| ------------- | ---------------------------------------- | --------------------------------------- |
| MCP Server | *(none - uses setuptools-scm)* | `just release::tag-mcp-server X.Y.Z` |
| Workbench | `just release::bump-workbench X.Y.Z` | `just release::tag-workbench X.Y.Z` |
| Magnets Macro | `just release::bump-macro-magnets X.Y.Z` | `just release::tag-macro-magnets X.Y.Z` |
| Export Macro | `just release::bump-macro-export X.Y.Z` | `just release::tag-macro-export X.Y.Z` |
| Component | Bump Command | Tag Command |
| ---------- | ------------------------------------ | ------------------------------------ |
| MCP Server | *(none - uses setuptools-scm)* | `just release::tag-mcp-server X.Y.Z` |
| Workbench | `just release::bump-workbench X.Y.Z` | `just release::tag-workbench X.Y.Z` |
## Components and Their Release Targets
| Component | Tag Format | Releases To |
| ---------------------------- | ------------------------------------- | ------------------------------------------ |
| MCP Server | `robust-mcp-server-vX.Y.Z` | PyPI/TestPyPI*, Docker Hub, GitHub Release |
| Robust MCP Bridge Workbench | `robust-mcp-workbench-vX.Y.Z` | GitHub Release (archive) |
| Cut Object for Magnets Macro | `macro-cut-object-for-magnets-vX.Y.Z` | GitHub Release (archive) |
| Multi Export Macro | `macro-multi-export-vX.Y.Z` | GitHub Release (archive) |
| Component | Tag Format | Releases To |
| --------------------------- | ----------------------------- | ------------------------------------------ |
| MCP Server | `robust-mcp-server-vX.Y.Z` | PyPI/TestPyPI*, Docker Hub, GitHub Release |
| Robust MCP Bridge Workbench | `robust-mcp-workbench-vX.Y.Z` | GitHub Release (archive) |
*Stable releases (`X.Y.Z`) publish to PyPI; non-stable releases (alpha, beta, rc) publish to TestPyPI only.
@@ -110,10 +103,6 @@ just release::changes-since mcp-server
# For Workbench
just release::changes-since workbench
# For Macros
just release::changes-since macro-magnets
just release::changes-since macro-export
```
### 3. Run All Quality Checks
@@ -136,12 +125,10 @@ Each component has its own `RELEASE_NOTES.md` file. Release workflows automatica
#### Release Notes Files
| Component | Release Notes File |
| ---------------------------- | ----------------------------------------------------- |
| MCP Server | `src/freecad_mcp/RELEASE_NOTES.md` |
| Robust MCP Bridge Workbench | `addon/FreecadRobustMCPBridge/RELEASE_NOTES.md` |
| Cut Object for Magnets Macro | `macros/Cut_Object_for_Magnets/RELEASE_NOTES.md` |
| Multi Export Macro | `macros/Multi_Export/RELEASE_NOTES.md` |
| Component | Release Notes File |
| --------------------------- | ----------------------------------------------- |
| MCP Server | `src/freecad_mcp/RELEASE_NOTES.md` |
| Robust MCP Bridge Workbench | `addon/FreecadRobustMCPBridge/RELEASE_NOTES.md` |
#### Draft Release Notes
@@ -151,8 +138,6 @@ Use the `draft-notes` command to generate a starting point from conventional com
# Generate draft notes for a component
just release::draft-notes mcp-server
just release::draft-notes workbench
just release::draft-notes macro-magnets
just release::draft-notes macro-export
```
This categorizes commits by type (feat, fix, refactor, etc.) to help you write the release notes.
@@ -256,61 +241,13 @@ just release::tag-workbench 1.0.0
3. Creates archive (tar.gz and zip)
4. Creates GitHub Release with the archives
### Macro Releases
Each macro can be released independently.
**Cut Object for Magnets Macro:**
```bash
# 1. Bump version in source files
just release::bump-macro-magnets 1.0.0
# 2. Review and commit the changes
git diff # Review changes
git add -A
git commit -m "chore: bump Cut Object for Magnets macro to 1.0.0"
# 3. Create and push the release tag
just release::tag-macro-magnets 1.0.0
```
**Multi Export Macro:**
```bash
# 1. Bump version in source files
just release::bump-macro-export 1.0.0
# 2. Review and commit the changes
git diff # Review changes
git add -A
git commit -m "chore: bump Multi Export macro to 1.0.0"
# 3. Create and push the release tag
just release::tag-macro-export 1.0.0
```
**Files updated by macro bump commands:**
- `macros/<MacroDir>/<Macro>.FCMacro` (`__Version__` and `__Date__`)
- `macros/<MacroDir>/README-<Macro>.md` (`**Version:**`)
- `macros/<MacroDir>/wiki-source.txt` (`|Version=` and `|Date=`)
- `package.xml` (macro section: `<version>` and `<date>`)
**What happens automatically:**
1. GitHub Actions validates the tag format
2. Verifies version in source files matches tag
3. Creates archive (tar.gz and zip)
4. Creates GitHub Release with the archives
## Verifying a Release
### Check GitHub Actions
After pushing a tag, monitor the release workflow:
1. Go to [GitHub Actions](https://github.com/spkane/freecad-robust-mcp-and-more/actions)
1. Go to [GitHub Actions](https://github.com/spkane/freecad-addon-robust-mcp-server/actions)
2. Find the workflow run triggered by your tag
3. Verify all steps complete successfully
@@ -326,7 +263,7 @@ pip index versions freecad-robust-mcp
docker pull spkane/freecad-robust-mcp:1.0.0
```
**For Workbench/Macros:**
**For Workbench:**
- Check the GitHub Releases page for the archive downloads
- Verify the `package.xml` version was updated
@@ -361,7 +298,6 @@ To see what a release tag would look like without creating it:
```bash
just release::dry-run-tag mcp-server 1.0.0
just release::dry-run-tag workbench 1.0.0
just release::dry-run-tag macro-magnets 1.0.0
```
## Troubleshooting
@@ -416,56 +352,6 @@ just release::tag-mcp-server 1.0.0
- **MCP Server**: Release when there are significant new features or important bug fixes
- **Workbench**: Release in sync with server changes that affect the bridge protocol
- **Macros**: Release independently when macro functionality changes
## Updating the FreeCAD Wiki
After releasing a macro, you should update its FreeCAD wiki page. The `wiki-source.txt` files are automatically updated by the `bump-macro-*` commands with the new version and date.
### Wiki Update Commands
```bash
# Check differences between local and live wiki
just release::wiki-diff macro-magnets
just release::wiki-diff macro-export
# View the wiki source content locally
just release::wiki-show macro-magnets
just release::wiki-show macro-export
# Update the wiki (copies to clipboard and opens edit page)
just release::wiki-update macro-magnets
just release::wiki-update macro-export
```
### Wiki Update Workflow
The `wiki-update` command provides a safe, assisted workflow:
1. Copies the updated wiki-source.txt content to your clipboard
2. Opens the FreeCAD wiki edit page in your browser
3. Displays step-by-step instructions
**Manual steps after running the command:**
1. Log in to your FreeCAD wiki account if prompted
2. Select all content in the edit box (Ctrl+A / Cmd+A)
3. Paste the new content (Ctrl+V / Cmd+V)
4. Add an edit summary like "Update to version X.Y.Z"
5. Click "Show preview" to verify changes
6. Click "Save changes" when satisfied
!!! note "Wiki Account Required"
You need a FreeCAD wiki account to edit pages. Register at [wiki.freecad.org](https://wiki.freecad.org) if you don't have one.
### Macro Shortcuts
The wiki commands accept multiple aliases for convenience:
| Macro | Aliases |
| ------------------------ | -------------------------------- |
| Cut Object for Magnets | `macro-magnets`, `magnets`, `cut`|
| Multi Export | `macro-export`, `export`, `multi`|
## Quick Reference
@@ -479,13 +365,9 @@ just release::changes-since mcp-server
# Draft release notes from commits
just release::draft-notes mcp-server
just release::draft-notes workbench
just release::draft-notes macro-magnets
just release::draft-notes macro-export
# Bump versions (for workbench and macros)
# Bump versions (for workbench only)
just release::bump-workbench 1.0.0
just release::bump-macro-magnets 1.0.0
just release::bump-macro-export 1.0.0
# Commit version changes
git add -A && git commit -m "chore: bump <component> to X.Y.Z"
@@ -493,8 +375,6 @@ git add -A && git commit -m "chore: bump <component> to X.Y.Z"
# Create releases (verifies versions, creates and pushes tag)
just release::tag-mcp-server 1.0.0
just release::tag-workbench 1.0.0
just release::tag-macro-magnets 1.0.0
just release::tag-macro-export 1.0.0
# List existing releases
just release::list-tags
@@ -503,11 +383,6 @@ just release::latest-versions
# Extract changelog for a version (used by CI)
just release::extract-changelog mcp-server 1.0.0
# Update FreeCAD wiki for macros (after release)
just release::wiki-diff macro-magnets # Check differences
just release::wiki-update macro-magnets # Copy to clipboard & open edit page
just release::wiki-update macro-export
# Delete a tag if needed
just release::delete-tag <full-tag-name>
```
docs/guide/macros.md
+5 -73
View File
@@ -1,78 +1,10 @@
# FreeCAD Macros
# MCP Macro Tools
This project includes standalone FreeCAD macros that work independently of the MCP server, plus MCP tools for creating and managing macros programmatically.
The MCP server provides tools for working with FreeCAD 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 Robust MCP Suite" 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:
## Available Tools
### list_macros
@@ -98,7 +30,7 @@ run_macro(
**Example prompt:**
```text
"Run the MultiExport macro"
"Run the ExportSTL macro"
```
### create_macro
@@ -130,7 +62,7 @@ read_macro(macro_name: str) -> dict
**Example prompt:**
```text
"Show me the code for the MultiExport macro"
"Show me the code for my custom macro"
```
### delete_macro
docs/guide/resources.md
+3 -3
View File
@@ -237,9 +237,9 @@ Gets list of available FreeCAD macros.
```json
[
{
"name": "MultiExport",
"path": "/home/user/.local/share/FreeCAD/Macro/MultiExport.FCMacro",
"description": "Export objects to multiple formats",
"name": "ExportSTL",
"path": "/home/user/.local/share/FreeCAD/Macro/ExportSTL.FCMacro",
"description": "Export selected objects to STL",
"is_system": false
}
]
docs/guide/workbench.md
+2 -7
View File
@@ -255,11 +255,6 @@ The workbench uses a **queue-based thread safety system** to ensure FreeCAD oper
---
## Included Macros
## Macro Tools
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.
The MCP server provides tools for working with FreeCAD macros. See [Macros](macros.md) for details on using macro tools.
docs/index.md
+7 -5
View File
@@ -2,7 +2,7 @@
Welcome to the FreeCAD Robust MCP Suite documentation.
This project provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, FreeCAD workbench, and standalone macros that enable 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.
This project provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server and FreeCAD workbench that enable 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.
---
@@ -12,7 +12,6 @@ This project provides an [MCP (Model Context Protocol)](https://modelcontextprot
- **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
---
@@ -64,10 +63,13 @@ The Robust MCP Server works with FreeCAD in both GUI and headless mode:
## FreeCAD Macros
This project includes standalone FreeCAD macros:
The MCP server provides tools for working with FreeCAD macros:
- **[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
- **List macros** - Discover available macros in your FreeCAD installation
- **Run macros** - Execute macros with parameter passing
- **Create macros** - Generate new macros from templates or custom code
See [Macros Guide](guide/macros.md) for details on using macros with the MCP server.
---