AnkusDrive

# AnkusDrive

<!-- mcp-name: io.github.gchen19/ankusdrive -->
<!-- ↑ Ownership proof for the official MCP Registry (#201): the registry reads it
     from the README *as uploaded to PyPI*, so it must survive every release and
     match `name` in server.json. tests/test_mcp_registry.py holds both to that. -->

<!-- Absolute raw.githubusercontent URLs, not repo-relative paths: this README is
     also the PyPI project page, which resolves relative links against pypi.org.
     PNG rather than the SVG because raw.githubusercontent serves SVG as
     text/plain, so browsers refuse to render it as an image. The <picture> gives
     GitHub a dark variant; PyPI strips <source> and falls through to <img>. -->
<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gchen19/AnkusDrive/main/logo/wordmark/ankusdrive-wordmark-dark-1280.png">
    <img src="https://raw.githubusercontent.com/gchen19/AnkusDrive/main/logo/wordmark/ankusdrive-wordmark-1280.png" alt="AnkusDrive — align generative intent with the CAD kernel" width="640">
  </picture>
</p>

A CLI + MCP server that drives [FreeCAD](https://www.freecad.org/) through its Python API so LLMs (and humans at a terminal) can design mechanical parts and run FEM simulations without clicking through the GUI.

## Why

FreeCAD exposes almost everything it does through a Python API — create documents, build sketches, extrude solids, mesh them, run CalculiX/Elmer FEM solves, read back stress/displacement fields. But that API lives inside FreeCAD's embedded Python (`freecadcmd`), which is awkward to call from anywhere else. AnkusDrive wraps it behind two surfaces:

- **CLI** — one-shot commands (`ankusdrive run script.py`, `ankusdrive box --w 10 --d 20 --h 5 -o part.FCStd`) for scripts, CI, and quick iteration.
- **MCP server** — 280+ structured tools (`new_document`, `add_primitive`, `boolean_op`, `pad`, `add_gear`, `fem_new_analysis`, `fem_run`, `fem_results`) so an LLM agent can model, inspect, and simulate iteratively. Beyond core CAD/FEM this now spans a broad **simulation surface** (thermal, CFD/CHT, EM, acoustics, FSI, injection molding, granular/DEM, optics, multibody) and a **design-control layer** (item/part numbers, recipes, variant families, lifecycle/revision, ECO change orders, versioned interfaces).
- **Multi-agent orchestration** — a host-side reference layer that lets a *team* of agents partition one product into components, build them in parallel, and merge the pieces back together with the joints actually fitting (see [Multi-agent design](#multi-agent-design)).

## Target environment

- FreeCAD 1.1.x. The `freecadcmd` binary is auto-discovered per-OS (macOS `.app` bundle, Linux `/usr/bin` etc., **Windows** `C:\Program Files\FreeCAD 1.1\bin\freecadcmd.exe` — version-globbed); override via `$ANKUSDRIVE_FREECADCMD` or rely on PATH. Run `ankusdrive doctor` to see exactly what resolved.
- Bundled Python, `ccx` (CalculiX), and `gmsh` already ship **inside every FreeCAD install** — the macOS `.app`, the Linux package, and the Windows `bin\` — so core CAD + structural FEM work on all three with no extra install.
- Host-side rendering needs `Pillow` and `numpy`; both are installed by AnkusDrive as regular pip deps.
- **One optional exception:** drawing **PDF/SVG** export (`export_drawing`) renders inside FreeCAD's *bundled* Python, so it needs `reportlab` + `svglib` installed **there** — see [Drawing export (PDF/SVG)](#drawing-export-pdfsvg). DXF export and everything else leave FreeCAD's Python untouched.

## Setup

AnkusDrive is a `pip`-installable package; FreeCAD itself is the only thing you
install separately. The host-side dependencies (`mcp`, `Pillow`, `numpy`) come
along with the install. `freecadcmd` is launched as a subprocess and uses its
own bundled Python — AnkusDrive doesn't touch it.

```bash
# 1. Install FreeCAD 1.1.x from https://www.freecad.org/
#    (macOS: drag to /Applications; Linux: distro package or AppImage;
#     Windows: run the installer — default C:\Program Files\FreeCAD 1.1)

# 2. Install AnkusDrive. Pick one:
pipx install ankusdrive                                       # from PyPI — isolated app, `ankusdrive` on PATH
pip install ankusdrive                                        # or into an env you manage yourself
# unreleased main, or for development from a clone:
pipx install git+https://github.com/gchen19/AnkusDrive.git
git clone https://github.com/gchen19/AnkusDrive.git && cd AnkusDrive
python3 -m venv .venv && .venv/bin/pip install -e .         # `.venv/bin/ankusdrive`

# 3. Smoke-test that the worker can reach FreeCAD, and see the full setup report
ankusdrive ping        # → ping=pong freecad=1.1.1
ankusdrive doctor      # per-item FreeCAD + solver checklist with the exact fix each
```

> **On Windows, don't follow the block above by hand** — there is one scripted path
> that does all of it including the MCP registration:
> [Windows quickstart (PowerShell)](#windows-quickstart-powershell).

AnkusDrive is published on PyPI at
[pypi.org/project/ankusdrive](https://pypi.org/project/ankusdrive/); the
distribution roadmap beyond it (marketplace listings, hosted transport) is
tracked in [epic #303](https://github.com/gchen19/AnkusDrive/issues/303); the
original phase plan is kept as a design record at
[`docs/archive/PUBLISHING_PLAN.md`](https://github.com/gchen19/AnkusDrive/blob/main/docs/archive/PUBLISHING_PLAN.md).

### Windows quickstart (PowerShell)

Windows is a first-class target (core CAD + CalculiX FEM run natively against a stock
FreeCAD 1.1 install), and the whole core install is one script — venv, pinned
dependencies, `doctor`, and the MCP registration line with **resolved absolute paths**:

```powershell
# 1. Install FreeCAD 1.1.x from https://www.freecad.org/ (default C:\Program Files\FreeCAD 1.1).
#    Nothing needs to go on PATH — AnkusDrive globs the versioned install dir itself.

# 2. Clone and run the core installer. Windows PowerShell 5.1 is enough; no admin needed.
git clone https://github.com/gchen19/AnkusDrive.git
cd AnkusDrive
powershell -ExecutionPolicy Bypass -File scripts\install-core.ps1
```

That creates `.venv`, installs AnkusDrive with the pins that matter (notably `mcp<2` —
`mcp` 2.x installs cleanly and then breaks `ankusdrive mcp`), verifies the resolved
`mcp`/`numpy`/`Pillow`, runs `ankusdrive doctor` + `ankusdrive ping`, completes a real MCP
stdio handshake, and finally prints your registration block. Useful switches:
`-Python 'C:\Program Files\Python313\python.exe'` to pick an interpreter,
`-Extras mbd,fluids` for the pip-wheel solver families, `-Persist` to write the FreeCAD
path into `%APPDATA%\ankusdrive\config.toml` (MCP hosts launch with a minimal
environment, so a `$env:` set in your terminal will **not** reach them).

**3. Register it with your MCP host.** The script prints these with your real paths
filled in — a GUI host doesn't inherit your shell `PATH`, so the absolute path matters:

```powershell
# Claude Code
claude mcp add ankusdrive -- C:\Users\you\AnkusDrive\.venv\Scripts\ankusdrive.exe mcp

# Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json
#   { "mcpServers": { "ankusdrive": {
#       "command": "C:\\Users\\you\\AnkusDrive\\.venv\\Scripts\\ankusdrive.exe",
#       "args": ["mcp"] } } }
```

Then restart the host; you should see the `ankusdrive__*` tools appear.

Supported Python: **3.10 – 3.14** (3.14 verified end-to-end on Windows 11 —
`pip install`, MCP stdio handshake, and `ankusdrive ping` → `freecad=1.1.1`). The script
checks your interpreter *before* pip runs, so a too-new CPython says so instead of
failing inside the resolver.

Optional solvers (SU2, Elmer, PrusaSlicer, WSL-backed OpenFOAM) come afterwards via
`scripts\install-solvers.ps1`. Full per-solver reality, the test suite, and the WSL2
route: [`docs/WINDOWS.md`](docs/WINDOWS.md).

### Ubuntu 24.04+ / containers (apt has no FreeCAD)

FreeCAD was **dropped from Ubuntu 24.04's `universe` repo**, so `apt install
freecad` finds no candidate there, and upstream's snap/flatpak both fail in a
container or sandboxed agent environment (no snapd session, no FUSE). The path
that works everywhere is the official **AppImage, extracted**:

```bash
scripts/install-freecad-appimage.sh          # or: scripts/install-solvers.sh freecad
```

It downloads the pinned release AppImage, checks its SHA-256, unpacks it with
`--appimage-extract` (a userspace squashfs unpack — **no FUSE, no root, no
snapd**, which is why it works in a container), symlinks `freecadcmd`, `freecad`,
`ccx` and `gmsh` into `/usr/local/bin`, and then **live-verifies** the result with
`ankusdrive ping` plus a real CalculiX solve (`ankusdrive fem cantilever`). Without a
writable `/opt` it installs to `~/.local/opt/freecad` instead; `--prefix` /
`--bindir` override both, `--appimage FILE` reuses a download you already have.

The symlink step is optional: AnkusDrive also probes
`/opt/freecad/squashfs-root/usr/bin` (and `~/.local/opt/freecad*/…`) directly, so
a hand-extracted AppImage in either prefix is auto-discovered. `ccx` and `gmsh`
ride along inside the AppImage, so structural FEM works off this one download.

### Telling AnkusDrive where FreeCAD lives

AnkusDrive auto-discovers `freecadcmd` in this order: `$ANKUSDRIVE_FREECADCMD`,
then `shutil.which(...)` on PATH (trying `freecadcmd`, `FreeCADCmd`, and
`freecad.cmd`), then a **per-OS** list of standard install locations:

| OS | Auto-discovered locations (newest version wins) |
|---|---|
| macOS | `/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd` |
| Linux | `/usr/bin`, `/usr/local/bin`, `/snap/bin/freecad.cmd`, extracted AppImage under `/opt/freecad*/squashfs-root/usr/bin` or `~/.local/opt/freecad*/…`, `~/.local/bin` |
| Windows | `C:\Program Files\FreeCAD *\bin\freecadcmd.exe` (version-globbed), `C:\Program Files (x86)\…`, `%LOCALAPPDATA%\Programs\FreeCAD *\bin\…` |

So a stock installer on any of the three needs **no configurati