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

docs: update repository name and add clear acknowledgements section to primary README (#12)

Browse Source 
* docs: Update git repo name

* docs: add acknowledgements section

* docs: clarifications and consistency improvements

* ci: Update CodeRabbit configuration

* Update README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* docs: Fix repo path everywhere

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
This commit is contained in:
Sean P. Kane
2026-01-05 06:26:06 -08:00
committed by GitHub
co-authored by coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
parent 1e7fa38cf4
commit e11ba127cd
14 changed files with 89 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.coderabbit.yaml
+13 -3
View File
@@ -5,10 +5,10 @@
language: en-US language: en-US
# Tone instructions for reviews # Tone instructions for reviews
tone_instructions: > tone_instructions: |
Be concise and direct. Focus on actionable feedback. Be concise and direct. Focus on actionable feedback.
This is a Python project using modern tooling (uv, ruff, mypy). Python project using modern tooling (uv, ruff, mypy).
The codebase integrates with FreeCAD CAD software via MCP protocol. Integrates with FreeCAD CAD software via MCP protocol.
early_access: false early_access: false
@@ -96,6 +96,16 @@ reviews:
CRITICAL: Python 3.11 is required - FreeCAD bundles libpython3.11. CRITICAL: Python 3.11 is required - FreeCAD bundles libpython3.11.
Using a different Python version causes ABI incompatibility crashes. Using a different Python version causes ABI incompatibility crashes.
- path: "README.md"
instructions: >
INTENTIONAL NAMING: The repo is "freecad-robust-mcp-and-more" but Docker
image and PyPI package are "freecad-robust-mcp". This is documented and
intentional - do NOT flag as a naming mismatch or inconsistency.
- path: "Dockerfile"
instructions: >
INTENTIONAL NAMING: Image name "freecad-robust-mcp" differs from repo name
"freecad-robust-mcp-and-more". This is intentional and documented in README.
Do NOT flag as a naming mismatch.
- path: ".mise.toml" - path: ".mise.toml"
instructions: > instructions: >
Tool version management via mise. All versions use fuzzy matching: Tool version management via mise. All versions use fuzzy matching:
.github/ISSUE_TEMPLATE/config.yaml
+2 -2
View File
@@ -1,8 +1,8 @@
blank_issues_enabled: false blank_issues_enabled: false
contact_links: contact_links:
- name: Documentation - name: Documentation
url: https://github.com/spkane/freecad-mcp#readme url: https://github.com/spkane/freecad-robust-mcp-and-more#readme
about: Check the README for usage instructions and troubleshooting about: Check the README for usage instructions and troubleshooting
- name: Discussions - name: Discussions
url: https://github.com/spkane/freecad-mcp/discussions url: https://github.com/spkane/freecad-robust-mcp-and-more/discussions
about: Ask questions and discuss ideas with the community about: Ask questions and discuss ideas with the community
.github/workflows/docker-release.yaml
+2 -2
View File
@@ -14,7 +14,7 @@ concurrency:
cancel-in-progress: true cancel-in-progress: true
env: env:
DOCKERHUB_REPO: spkane/freecad-mcp DOCKERHUB_REPO: spkane/freecad-robust-mcp
jobs: jobs:
release: release:
@@ -87,7 +87,7 @@ jobs:
# Latest tag - only for stable releases # Latest tag - only for stable releases
type=raw,value=latest,enable=${{ steps.version.outputs.is_prerelease == 'false' }} type=raw,value=latest,enable=${{ steps.version.outputs.is_prerelease == 'false' }}
labels: | labels: |
org.opencontainers.image.title=FreeCAD MCP Server org.opencontainers.image.title=FreeCAD Robust MCP Server
org.opencontainers.image.description=Model Context Protocol server for FreeCAD integration org.opencontainers.image.description=Model Context Protocol server for FreeCAD integration
org.opencontainers.image.vendor=spkane org.opencontainers.image.vendor=spkane
org.opencontainers.image.version=${{ steps.version.outputs.version }} org.opencontainers.image.version=${{ steps.version.outputs.version }}
.github/workflows/docker.yaml
+3 -3
View File
@@ -27,7 +27,7 @@ concurrency:
env: env:
REGISTRY: ghcr.io REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }} IMAGE_NAME: freecad-robust-mcp
jobs: jobs:
build: build:
@@ -103,13 +103,13 @@ jobs:
- name: Test Docker image - name: Test Docker image
run: | run: |
# Build for current platform only for testing # Build for current platform only for testing
docker build --build-arg VERSION=${{ steps.version.outputs.VERSION }} -t freecad-mcp:test . docker build --build-arg VERSION=${{ steps.version.outputs.VERSION }} -t ${{ env.IMAGE_NAME }}:test .
# Test that the container starts and responds to MCP initialize # Test that the container starts and responds to MCP initialize
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \ echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | \
timeout 30 docker run --rm -i \ timeout 30 docker run --rm -i \
-e FREECAD_MODE=xmlrpc \ -e FREECAD_MODE=xmlrpc \
freecad-mcp:test 2>&1 | \ ${{ env.IMAGE_NAME }}:test 2>&1 | \
grep -q '"result"' && echo "Container test passed" || echo "Container test completed" grep -q '"result"' && echo "Container test passed" || echo "Container test completed"
- name: Scan for vulnerabilities - name: Scan for vulnerabilities
.github/workflows/macro-release.yaml
+1 -1
View File
@@ -111,7 +111,7 @@ jobs:
## More Information ## More Information
For full documentation, visit: For full documentation, visit:
https://github.com/spkane/freecad-mcp https://github.com/spkane/freecad-robust-mcp-and-more
## License ## License
CHANGELOG.md
+1 -1
View File
@@ -53,7 +53,7 @@ Initial public beta release of the FreeCAD MCP Server and Macros.
#### Installation Options #### Installation Options
- **PyPI**: `pip install freecad-robust-mcp` - **PyPI**: `pip install freecad-robust-mcp`
- **Docker**: `docker pull ghcr.io/spkane/freecad-mcp` - **Docker**: `docker pull ghcr.io/spkane/freecad-robust-mcp`
- **Source**: Clone and install with `uv sync --all-extras` - **Source**: Clone and install with `uv sync --all-extras`
#### CI/CD & Tooling #### CI/CD & Tooling
CLAUDE.md
+1 -1
View File
@@ -54,7 +54,7 @@ FreeCAD's `FreeCAD.so` library links to `@rpath/libpython3.11.dylib` (FreeCAD's
This project uses [`mise`](https://mise.jdx.dev/) for local development tool management. All tool versions are pinned in `.mise.toml`. This project uses [`mise`](https://mise.jdx.dev/) for local development tool management. All tool versions are pinned in `.mise.toml`.
```bash ```bash
# Install mise (if not already installed) # Install mise via the Official mise installer script (if not already installed)
curl https://mise.run | sh curl https://mise.run | sh
# Install all project tools # Install all project tools
Dockerfile
+3 -3
View File
@@ -59,9 +59,9 @@ FROM python:3.11-slim AS runtime
# Note: version, revision, and created are set dynamically in CI/CD workflows # Note: version, revision, and created are set dynamically in CI/CD workflows
LABEL org.opencontainers.image.title="FreeCAD MCP Server" \ LABEL org.opencontainers.image.title="FreeCAD MCP Server" \
org.opencontainers.image.description="MCP (Model Context Protocol) server for FreeCAD integration with AI assistants" \ org.opencontainers.image.description="MCP (Model Context Protocol) server for FreeCAD integration with AI assistants" \
org.opencontainers.image.url="https://github.com/spkane/freecad-mcp" \ org.opencontainers.image.url="https://github.com/spkane/freecad-robust-mcp-and-more" \
org.opencontainers.image.source="https://github.com/spkane/freecad-mcp" \ org.opencontainers.image.source="https://github.com/spkane/freecad-robust-mcp-and-more" \
org.opencontainers.image.documentation="https://github.com/spkane/freecad-mcp#readme" \ org.opencontainers.image.documentation="https://github.com/spkane/freecad-robust-mcp-and-more#readme" \
org.opencontainers.image.licenses="MIT" \ org.opencontainers.image.licenses="MIT" \
org.opencontainers.image.vendor="Sean P. Kane" \ org.opencontainers.image.vendor="Sean P. Kane" \
org.opencontainers.image.authors="Sean P. Kane <spkane@gmail.com>" \ org.opencontainers.image.authors="Sean P. Kane <spkane@gmail.com>" \
README.md
+46 -19
View File
@@ -59,6 +59,8 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that
- [CutObjectForMagnets Macro](#cutobjectformagnets-macro) - [CutObjectForMagnets Macro](#cutobjectformagnets-macro)
- [MultiExport Macro](#multiexport-macro) - [MultiExport Macro](#multiexport-macro)
- [Architecture](#architecture) - [Architecture](#architecture)
- [Acknowledgements](#acknowledgements)
- [Related Projects](#related-projects)
- [License](#license) - [License](#license)
<!--TOC--> <!--TOC-->
@@ -84,6 +86,8 @@ This section covers installation and usage for end users who want to use the MCP
## MCP Server ## MCP Server
> **Note**: Since this repository has more than just the MCP server in it, the Linux container and PyPi projects releases are both simply named `freecad-robust-mcp` which differs from the name of this git repository.
### Installation ### Installation
#### Using pip (recommended) #### Using pip (recommended)
@@ -95,8 +99,12 @@ pip install freecad-robust-mcp
#### Using mise and just (from source) #### Using mise and just (from source)
```bash ```bash
git clone https://github.com/spkane/freecad-mcp.git git clone https://github.com/spkane/freecad-robust-mcp-and-more.git
cd freecad-mcp cd freecad-robust-mcp-and-more
# Install mise via the Official mise installer script (if not already installed)
curl https://mise.run | sh
mise trust mise trust
mise install mise install
just setup just setup
@@ -108,12 +116,12 @@ Run the MCP server in a container. This is useful for isolated environments or w
```bash ```bash
# Pull from Docker Hub (when published) # Pull from Docker Hub (when published)
docker pull spkane/freecad-mcp docker pull spkane/freecad-robust-mcp
# Or build locally # Or build locally
git clone https://github.com/spkane/freecad-mcp.git git clone https://github.com/spkane/freecad-robust-mcp-and-more.git
cd freecad-mcp cd freecad-robust-mcp-and-more
docker build -t freecad-mcp . docker build -t freecad-robust-mcp .
# Or use just commands (if you have mise/just installed) # Or use just commands (if you have mise/just installed)
just docker::build # Build for local architecture just docker::build # Build for local architecture
@@ -169,7 +177,7 @@ If installed from source with mise/uv:
"mcpServers": { "mcpServers": {
"freecad": { "freecad": {
"command": "/path/to/mise/shims/uv", "command": "/path/to/mise/shims/uv",
"args": ["run", "--project", "/path/to/freecad-mcp", "freecad-mcp"], "args": ["run", "--project", "/path/to/freecad-robust-mcp-and-more", "freecad-mcp"],
"env": { "env": {
"FREECAD_MODE": "xmlrpc" "FREECAD_MODE": "xmlrpc"
} }
@@ -420,7 +428,7 @@ This project includes standalone FreeCAD macros that can be used independently o
Pre-packaged macro archives are available with each release: Pre-packaged macro archives are available with each release:
1. Go to the [Releases page](https://github.com/spkane/freecad-mcp/releases) 1. Go to the [Releases page](https://github.com/spkane/freecad-robust-mcp-and-more/releases)
1. Download the macro archive for your platform: 1. Download the macro archive for your platform:
- `freecad-macros-X.Y.Z.tar.gz` (Linux/macOS) - `freecad-macros-X.Y.Z.tar.gz` (Linux/macOS)
- `freecad-macros-X.Y.Z.zip` (Windows) - `freecad-macros-X.Y.Z.zip` (Windows)
@@ -553,10 +561,10 @@ This section covers development setup, contributing, and working with the codeba
```bash ```bash
# Clone the repository # Clone the repository
git clone https://github.com/spkane/freecad-mcp.git git clone https://github.com/spkane/freecad-robust-mcp-and-more.git
cd freecad-mcp cd freecad-robust-mcp-and-more
# Install mise (if not already installed) # Install mise via the Official mise installer script (if not already installed)
curl https://mise.run | sh curl https://mise.run | sh
# Install all tools (Python 3.11, uv, just, pre-commit) # Install all tools (Python 3.11, uv, just, pre-commit)
@@ -583,7 +591,7 @@ Create a `.mcp.json` file in the project directory:
"mcpServers": { "mcpServers": {
"freecad": { "freecad": {
"command": "/path/to/mise/shims/uv", "command": "/path/to/mise/shims/uv",
"args": ["run", "--project", "/path/to/freecad-mcp", "freecad-mcp"], "args": ["run", "--project", "/path/to/freecad-robust-mcp-and-more", "freecad-mcp"],
"env": { "env": {
"FREECAD_MODE": "xmlrpc", "FREECAD_MODE": "xmlrpc",
"FREECAD_SOCKET_HOST": "localhost", "FREECAD_SOCKET_HOST": "localhost",
@@ -597,18 +605,17 @@ Create a `.mcp.json` file in the project directory:
**Replace the paths with your actual paths:** **Replace the paths with your actual paths:**
| Placeholder | Description | Example (macOS) | | Placeholder | Description | Example |
| ------------------------ | ------------------------------ | ------------------------------ | | -------------------------------------- | ------------------------------ | ------------------------------------------ |
| `/path/to/mise/shims/uv` | Full path to uv via mise shims | `~/.local/share/mise/shims/uv` | | `/path/to/mise/shims/uv` | Full path to uv via mise shims | `~/.local/share/mise/shims/uv` |
| `/path/to/freecad-mcp` | Project directory | `~/dev/freecad-mcp` | | `/path/to/freecad-robust-mcp-and-more` | Project directory | `/home/me/dev/freecad-robust-mcp-and-more` |
| `/path/to/mise/shims` | mise shims directory for PATH | `~/.local/share/mise/shims` | | `/path/to/mise/shims` | mise shims directory for PATH | `~/.local/share/mise/shims` |
**Finding your mise shims path:** **Finding your mise shims path:**
```bash ```bash
mise where uv | sed 's|/installs/.*|/shims|' mise where uv | sed 's|/installs/.*|/shims|'
# Or simply: # Example: /home/user/.local/share/mise/shims (on Linux) or ~/.local/share/mise/shims (on macOS)
echo ~/.local/share/mise/shims
``` ```
### Development Workflow ### Development Workflow
@@ -785,6 +792,26 @@ See [ARCHITECTURE-MCP.md](ARCHITECTURE-MCP.md) for detailed design documentation
--- ---
## Acknowledgements
This project was developed after analyzing several existing FreeCAD MCP implementations. We are grateful to these projects for their pioneering work and the ideas they contributed to the FreeCAD + AI ecosystem:
### Related Projects
- **[neka-nat/freecad-mcp](https://github.com/neka-nat/freecad-mcp)** (MIT License) - The queue-based thread safety pattern and XML-RPC protocol design (port 9875) were directly inspired by this project. Our implementation maintains protocol compatibility while being a complete rewrite with additional features.
- **[jango-blockchained/mcp-freecad](https://github.com/jango-blockchained/mcp-freecad)** - Inspired our connection recovery mechanisms and multi-mode architecture approach.
- **[contextform/freecad-mcp](https://github.com/contextform/freecad-mcp)** - Informed our comprehensive PartDesign and Part workbench tool coverage.
- **[ATOI-Ming/FreeCAD-MCP](https://github.com/ATOI-Ming/FreeCAD-MCP)** - Inspired our macro development toolkit including templates, validation, and automatic imports.
- **[bonninr/freecad_mcp](https://github.com/bonninr/freecad_mcp)** - Influenced our simple socket-based communication approach.
See [docs/COMPARISON.md](docs/COMPARISON.md) for a detailed analysis of these implementations and the design decisions they informed.
---
## License ## License
MIT License - see [LICENSE](LICENSE) for details. MIT License - see [LICENSE](LICENSE) for details.
docs/index.md
+6 -2
View File
@@ -19,8 +19,12 @@ This project provides an [MCP (Model Context Protocol)](https://modelcontextprot
```bash ```bash
# Clone and setup # Clone and setup
git clone https://github.com/spkane/freecad-mcp.git git clone https://github.com/spkane/freecad-robust-mcp-and-more.git
cd freecad-mcp cd freecad-robust-mcp-and-more
# Install mise via the Official mise installer script (if not already installed)
curl https://mise.run | sh
mise install mise install
just setup just setup
macros/Start_MCP_Bridge/README-StartMCPBridge.md
+1 -1
View File
@@ -43,7 +43,7 @@ After starting the bridge, configure your MCP client (e.g., Claude Code) with:
"mcpServers": { "mcpServers": {
"freecad": { "freecad": {
"command": "uv", "command": "uv",
"args": ["run", "--project", "/path/to/freecad-mcp", "freecad-mcp"], "args": ["run", "--project", "/path/to/freecad-robust-mcp-and-more", "freecad-mcp"],
"env": { "env": {
"FREECAD_MODE": "xmlrpc" "FREECAD_MODE": "xmlrpc"
} }
mkdocs.yaml
+3 -3
View File
@@ -1,8 +1,8 @@
site_name: FreeCAD MCP Server site_name: FreeCAD MCP Server
site_description: MCP server for FreeCAD integration with AI assistants site_description: MCP server for FreeCAD integration with AI assistants
site_url: https://github.com/spkane/freecad-mcp site_url: https://github.com/spkane/freecad-robust-mcp-and-more
repo_url: https://github.com/spkane/freecad-mcp repo_url: https://github.com/spkane/freecad-robust-mcp-and-more
repo_name: spkane/freecad-mcp repo_name: spkane/freecad-robust-mcp-and-more
theme: theme:
name: material name: material
pyproject.toml
+6 -6
View File
@@ -82,12 +82,12 @@ dev = [
freecad-mcp = "freecad_mcp.server:main" freecad-mcp = "freecad_mcp.server:main"
[project.urls] [project.urls]
Homepage = "https://github.com/spkane/freecad-mcp" Homepage = "https://github.com/spkane/freecad-robust-mcp-and-more"
Documentation = "https://github.com/spkane/freecad-mcp#readme" Documentation = "https://github.com/spkane/freecad-robust-mcp-and-more#readme"
Repository = "https://github.com/spkane/freecad-mcp.git" Repository = "https://github.com/spkane/freecad-robust-mcp-and-more.git"
Issues = "https://github.com/spkane/freecad-mcp/issues" Issues = "https://github.com/spkane/freecad-robust-mcp-and-more/issues"
Changelog = "https://github.com/spkane/freecad-mcp/blob/main/CHANGELOG.md" Changelog = "https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/CHANGELOG.md"
"Docker Hub" = "https://hub.docker.com/r/spkane/freecad-mcp" "Docker Hub" = "https://hub.docker.com/r/spkane/freecad-robust-mcp"
[tool.hatch.version] [tool.hatch.version]
source = "vcs" source = "vcs"
src/freecad_mcp/bridge/xmlrpc.py
+1 -1
View File
@@ -121,7 +121,7 @@ The FreeCAD MCP bridge server is not running. To fix this:
2. In FreeCAD's Python console (View → Panels → Python console), run: 2. In FreeCAD's Python console (View → Panels → Python console), run:
import sys import sys
sys.path.insert(0, "/path/to/freecad-mcp/src") sys.path.insert(0, "/path/to/freecad-robust-mcp-and-more/src")
from freecad_mcp.freecad_plugin.server import FreecadMCPPlugin from freecad_mcp.freecad_plugin.server import FreecadMCPPlugin
plugin = FreecadMCPPlugin() plugin = FreecadMCPPlugin()
plugin.start() plugin.start()