From e11ba127cdaf18318d4aa2812d77cf1363c03247 Mon Sep 17 00:00:00 2001 From: "Sean P. Kane" Date: Mon, 5 Jan 2026 06:26:06 -0800 Subject: [PATCH] docs: update repository name and add clear acknowledgements section to primary README (#12) * 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> --- .coderabbit.yaml | 16 ++++- .github/ISSUE_TEMPLATE/config.yaml | 4 +- .github/workflows/docker-release.yaml | 4 +- .github/workflows/docker.yaml | 6 +- .github/workflows/macro-release.yaml | 2 +- CHANGELOG.md | 2 +- CLAUDE.md | 2 +- Dockerfile | 6 +- README.md | 65 +++++++++++++------ docs/index.md | 8 ++- .../Start_MCP_Bridge/README-StartMCPBridge.md | 2 +- mkdocs.yaml | 6 +- pyproject.toml | 12 ++-- src/freecad_mcp/bridge/xmlrpc.py | 2 +- 14 files changed, 89 insertions(+), 48 deletions(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index f3d7db6..ecbc8c4 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -5,10 +5,10 @@ language: en-US # Tone instructions for reviews -tone_instructions: > +tone_instructions: | Be concise and direct. Focus on actionable feedback. - This is a Python project using modern tooling (uv, ruff, mypy). - The codebase integrates with FreeCAD CAD software via MCP protocol. + Python project using modern tooling (uv, ruff, mypy). + Integrates with FreeCAD CAD software via MCP protocol. early_access: false @@ -96,6 +96,16 @@ reviews: CRITICAL: Python 3.11 is required - FreeCAD bundles libpython3.11. 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" instructions: > Tool version management via mise. All versions use fuzzy matching: diff --git a/.github/ISSUE_TEMPLATE/config.yaml b/.github/ISSUE_TEMPLATE/config.yaml index f91b2b0..3434255 100644 --- a/.github/ISSUE_TEMPLATE/config.yaml +++ b/.github/ISSUE_TEMPLATE/config.yaml @@ -1,8 +1,8 @@ blank_issues_enabled: false contact_links: - 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 - 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 diff --git a/.github/workflows/docker-release.yaml b/.github/workflows/docker-release.yaml index 989e71a..05ac3bb 100644 --- a/.github/workflows/docker-release.yaml +++ b/.github/workflows/docker-release.yaml @@ -14,7 +14,7 @@ concurrency: cancel-in-progress: true env: - DOCKERHUB_REPO: spkane/freecad-mcp + DOCKERHUB_REPO: spkane/freecad-robust-mcp jobs: release: @@ -87,7 +87,7 @@ jobs: # Latest tag - only for stable releases type=raw,value=latest,enable=${{ steps.version.outputs.is_prerelease == 'false' }} 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.vendor=spkane org.opencontainers.image.version=${{ steps.version.outputs.version }} diff --git a/.github/workflows/docker.yaml b/.github/workflows/docker.yaml index 00b638f..ca7c1b9 100644 --- a/.github/workflows/docker.yaml +++ b/.github/workflows/docker.yaml @@ -27,7 +27,7 @@ concurrency: env: REGISTRY: ghcr.io - IMAGE_NAME: ${{ github.repository }} + IMAGE_NAME: freecad-robust-mcp jobs: build: @@ -103,13 +103,13 @@ jobs: - name: Test Docker image run: | # 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 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 \ -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" - name: Scan for vulnerabilities diff --git a/.github/workflows/macro-release.yaml b/.github/workflows/macro-release.yaml index 2926791..a7d7689 100644 --- a/.github/workflows/macro-release.yaml +++ b/.github/workflows/macro-release.yaml @@ -111,7 +111,7 @@ jobs: ## More Information For full documentation, visit: - https://github.com/spkane/freecad-mcp + https://github.com/spkane/freecad-robust-mcp-and-more ## License diff --git a/CHANGELOG.md b/CHANGELOG.md index 209aced..bf57f32 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,7 +53,7 @@ Initial public beta release of the FreeCAD MCP Server and Macros. #### Installation Options - **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` #### CI/CD & Tooling diff --git a/CLAUDE.md b/CLAUDE.md index 6329b85..ae28aca 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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`. ```bash -# Install mise (if not already installed) +# Install mise via the Official mise installer script (if not already installed) curl https://mise.run | sh # Install all project tools diff --git a/Dockerfile b/Dockerfile index e35680d..20d4f1f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -59,9 +59,9 @@ FROM python:3.11-slim AS runtime # Note: version, revision, and created are set dynamically in CI/CD workflows 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.url="https://github.com/spkane/freecad-mcp" \ - org.opencontainers.image.source="https://github.com/spkane/freecad-mcp" \ - org.opencontainers.image.documentation="https://github.com/spkane/freecad-mcp#readme" \ + org.opencontainers.image.url="https://github.com/spkane/freecad-robust-mcp-and-more" \ + org.opencontainers.image.source="https://github.com/spkane/freecad-robust-mcp-and-more" \ + org.opencontainers.image.documentation="https://github.com/spkane/freecad-robust-mcp-and-more#readme" \ org.opencontainers.image.licenses="MIT" \ org.opencontainers.image.vendor="Sean P. Kane" \ org.opencontainers.image.authors="Sean P. Kane " \ diff --git a/README.md b/README.md index 1986232..7791bf7 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,8 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that - [CutObjectForMagnets Macro](#cutobjectformagnets-macro) - [MultiExport Macro](#multiexport-macro) - [Architecture](#architecture) + - [Acknowledgements](#acknowledgements) + - [Related Projects](#related-projects) - [License](#license) @@ -84,6 +86,8 @@ This section covers installation and usage for end users who want to use the MCP ## 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 #### Using pip (recommended) @@ -95,8 +99,12 @@ pip install freecad-robust-mcp #### Using mise and just (from source) ```bash -git clone https://github.com/spkane/freecad-mcp.git -cd freecad-mcp +git clone https://github.com/spkane/freecad-robust-mcp-and-more.git +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 install just setup @@ -108,12 +116,12 @@ Run the MCP server in a container. This is useful for isolated environments or w ```bash # Pull from Docker Hub (when published) -docker pull spkane/freecad-mcp +docker pull spkane/freecad-robust-mcp # Or build locally -git clone https://github.com/spkane/freecad-mcp.git -cd freecad-mcp -docker build -t freecad-mcp . +git clone https://github.com/spkane/freecad-robust-mcp-and-more.git +cd freecad-robust-mcp-and-more +docker build -t freecad-robust-mcp . # Or use just commands (if you have mise/just installed) just docker::build # Build for local architecture @@ -169,7 +177,7 @@ If installed from source with mise/uv: "mcpServers": { "freecad": { "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": { "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: -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: - `freecad-macros-X.Y.Z.tar.gz` (Linux/macOS) - `freecad-macros-X.Y.Z.zip` (Windows) @@ -553,10 +561,10 @@ This section covers development setup, contributing, and working with the codeba ```bash # Clone the repository -git clone https://github.com/spkane/freecad-mcp.git -cd freecad-mcp +git clone https://github.com/spkane/freecad-robust-mcp-and-more.git +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 # Install all tools (Python 3.11, uv, just, pre-commit) @@ -583,7 +591,7 @@ Create a `.mcp.json` file in the project directory: "mcpServers": { "freecad": { "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": { "FREECAD_MODE": "xmlrpc", "FREECAD_SOCKET_HOST": "localhost", @@ -597,18 +605,17 @@ Create a `.mcp.json` file in the project directory: **Replace the paths with your actual paths:** -| Placeholder | Description | Example (macOS) | -| ------------------------ | ------------------------------ | ------------------------------ | -| `/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/mise/shims` | mise shims directory for PATH | `~/.local/share/mise/shims` | +| Placeholder | Description | Example | +| -------------------------------------- | ------------------------------ | ------------------------------------------ | +| `/path/to/mise/shims/uv` | Full path to uv via mise shims | `~/.local/share/mise/shims/uv` | +| `/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` | **Finding your mise shims path:** ```bash mise where uv | sed 's|/installs/.*|/shims|' -# Or simply: -echo ~/.local/share/mise/shims +# Example: /home/user/.local/share/mise/shims (on Linux) or ~/.local/share/mise/shims (on macOS) ``` ### 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 MIT License - see [LICENSE](LICENSE) for details. diff --git a/docs/index.md b/docs/index.md index 78a18a1..2501a63 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,8 +19,12 @@ This project provides an [MCP (Model Context Protocol)](https://modelcontextprot ```bash # Clone and setup -git clone https://github.com/spkane/freecad-mcp.git -cd freecad-mcp +git clone https://github.com/spkane/freecad-robust-mcp-and-more.git +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 just setup diff --git a/macros/Start_MCP_Bridge/README-StartMCPBridge.md b/macros/Start_MCP_Bridge/README-StartMCPBridge.md index 2f6e746..b9716dd 100644 --- a/macros/Start_MCP_Bridge/README-StartMCPBridge.md +++ b/macros/Start_MCP_Bridge/README-StartMCPBridge.md @@ -43,7 +43,7 @@ After starting the bridge, configure your MCP client (e.g., Claude Code) with: "mcpServers": { "freecad": { "command": "uv", - "args": ["run", "--project", "/path/to/freecad-mcp", "freecad-mcp"], + "args": ["run", "--project", "/path/to/freecad-robust-mcp-and-more", "freecad-mcp"], "env": { "FREECAD_MODE": "xmlrpc" } diff --git a/mkdocs.yaml b/mkdocs.yaml index 8d648ca..cc3574e 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -1,8 +1,8 @@ site_name: FreeCAD MCP Server site_description: MCP server for FreeCAD integration with AI assistants -site_url: https://github.com/spkane/freecad-mcp -repo_url: https://github.com/spkane/freecad-mcp -repo_name: spkane/freecad-mcp +site_url: https://github.com/spkane/freecad-robust-mcp-and-more +repo_url: https://github.com/spkane/freecad-robust-mcp-and-more +repo_name: spkane/freecad-robust-mcp-and-more theme: name: material diff --git a/pyproject.toml b/pyproject.toml index dfe24f8..cdad5fd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -82,12 +82,12 @@ dev = [ freecad-mcp = "freecad_mcp.server:main" [project.urls] -Homepage = "https://github.com/spkane/freecad-mcp" -Documentation = "https://github.com/spkane/freecad-mcp#readme" -Repository = "https://github.com/spkane/freecad-mcp.git" -Issues = "https://github.com/spkane/freecad-mcp/issues" -Changelog = "https://github.com/spkane/freecad-mcp/blob/main/CHANGELOG.md" -"Docker Hub" = "https://hub.docker.com/r/spkane/freecad-mcp" +Homepage = "https://github.com/spkane/freecad-robust-mcp-and-more" +Documentation = "https://github.com/spkane/freecad-robust-mcp-and-more#readme" +Repository = "https://github.com/spkane/freecad-robust-mcp-and-more.git" +Issues = "https://github.com/spkane/freecad-robust-mcp-and-more/issues" +Changelog = "https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/CHANGELOG.md" +"Docker Hub" = "https://hub.docker.com/r/spkane/freecad-robust-mcp" [tool.hatch.version] source = "vcs" diff --git a/src/freecad_mcp/bridge/xmlrpc.py b/src/freecad_mcp/bridge/xmlrpc.py index 0ed5778..6f0766f 100644 --- a/src/freecad_mcp/bridge/xmlrpc.py +++ b/src/freecad_mcp/bridge/xmlrpc.py @@ -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: 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 plugin = FreecadMCPPlugin() plugin.start()