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>
2026-01-05 06:26:06 -08:00
parent 1e7fa38cf4
commit e11ba127cd
14 changed files with 89 additions and 48 deletions
@@ -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:
@@ -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
@@ -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 }}
@@ -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
@@ -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

@@ -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
@@ -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
@@ -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 <spkane@gmail.com>" \
@@ -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)

 <!--TOC-->
@@ -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.
@@ -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

@@ -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"
      }
@@ -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
@@ -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"
@@ -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()