AnkusDrive

A CLI + MCP server that drives FreeCAD 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).

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). 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.

# 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).

AnkusDrive is published on PyPI at
pypi.org/project/ankusdrive; the
distribution roadmap beyond it (marketplace listings, hosted transport) is
tracked in epic #303; the
original phase plan is kept as a design record at
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:

# 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:

# 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.

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:

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:

So a stock installer on any of the three needs no configuration. For a
non-default install, point AnkusDrive at the binary directly:

export ANKUSDRIVE_FREECADCMD=/path/to/freecadcmd            # macOS/Linux

$env:ANKUSDRIVE_FREECADCMD = "D:\Apps\FreeCAD\bin\freecadcmd.exe"   # Windows

ankusdrive doctor prints which of the three layers (env / PATH / auto) actually
resolved FreeCAD, plus every candidate it checked — the fastest way to debug a
"FreeCAD not found" on a new box.

Drawing export (PDF/SVG)

export_drawing builds 2-D mechanical drawings (multi-view PDF/SVG/DXF with
dimensions) entirely headless. DXF uses FreeCAD's own writer and needs
nothing extra. PDF and SVG are composed and rasterised with reportlab +
svglib, and because that runs inside the worker — FreeCAD's bundled Python,
not the host venv — the two packages must be installed into FreeCAD's Python:

# Resolve FreeCAD's bundled Python from freecadcmd itself (portable across the
# macOS .app, a Linux distro package, and an extracted AppImage). freecadcmd
# prints a startup banner after the script output, so match a marker line
# rather than taking the last line:
printf 'import sys; print("DPREFIX="+sys.prefix)\n' > /tmp/_fcprefix.py
FREECAD_PREFIX="$(freecadcmd /tmp/_fcprefix.py 2>/dev/null | sed -n 's/^DPREFIX=//p')"
FREECAD_PY="$FREECAD_PREFIX/bin/python"      # some builds: $FREECAD_PREFIX/bin/python3

# Pin svglib<1.6 — newer svglib pulls rlPyCairo -> pycairo, a native build we
# don't use (our drawings are line art, no gradients).
"$FREECAD_PY" -m pip install reportlab "svglib<1.6"

# Verify:
"$FREECAD_PY" -c "import reportlab, svglib; print('drawing export ready')"

Without this, export_drawing still produces .dxf; .pdf/.svg raise a clear
ModuleNotFoundError. FreeCAD already bundles Pillow (reportlab needs it), so
no separate install is required.

Wiring it into an MCP host

The MCP server speaks stdio. Point your host at the ankusdrive binary and
let it run the mcp subcommand.

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ankusdrive": {
      "command": "ankusdrive",
      "args": ["mcp"]
    }
  }
}

If ankusdrive isn't on the host process's PATH, use an absolute path —
e.g. /Users/<you>/.local/bin/ankusdrive (pipx default) or
/absolute/path/to/AnkusDrive/.venv/bin/ankusdrive (clone+venv).

Claude Desktop, one click — download ankusdrive-<version>.mcpb from the
latest release and open it.
Claude Desktop sets up its Python environment with uv, so no pipx step is needed
— FreeCAD 1.1 still is. The install dialog has one optional field, the FreeCAD
command path, for a FreeCAD that auto-discovery cannot find.

Claude Code — register once:

claude mcp add ankusdrive -- ankusdrive mcp

Other hosts (Cursor, Continue, custom MCP clients) — same shape: stdio
transport, command = ankusdrive, args = ["mcp"].

After restarting the host, you should see 280+ ankusdrive__* tools become
available. If startup hangs or the host reports a closed connection, run
ankusdrive ping directly — that exercises the same worker boot path with
cleaner error messages.

Tool families (toolsets). Every tool definition takes up the client's context, and
all 281 come to roughly 114k tokens. Tools are grouped into families you can switch on
and off: core (always on), drawings, fem, components, sheet_metal, assembly,
intent, manufacturing, hand_calcs, simulation, plm, rendering.

• pip / pipx / uvx / clone: every family is on unless you set
  ANKUSDRIVE_TOOLSETS, e.g. ANKUSDRIVE_TOOLSETS=drawings,fem,simulation, or
  toolsets = "..." in config.toml.
• Claude Desktop extension: core, drawings and fem are on by default
  (~31k tokens); turn others on in the extension's settings.

setup_status lists the families that are off and exactly how to enable each one.

run_script executes Python the agent writes, with full access to your files and
processes. It's controlled by ANKUSDRIVE_ALLOW_RUN_SCRIPT (env, or allow_run_script
in config.toml):

• pip / pipx / uvx / clone: allowed unless set to false.
• Claude Desktop extension: off by default; turn it on in the extension's
  settings.

When it's off, the tool isn't offered at all, and setup_status says how to enable it.

Simulation solvers & review-video demos

The base install (FreeCAD + pip install ankusdrive) covers geometry, the analytic
oracles, and the MCP surface. The heavy simulation families each shell out to an
external solver, discovered at runtime by ankusdrive/solvers.py
($ANKUSDRIVE_<SOLVER>_PATH → PATH → standard install dirs). A family whose solver is
absent degrades to a clean {ok: false, reason, install} dict instead of crashing — check
what currently resolves with ankusdrive doctor (cross-platform, no server boot needed),
the solve_capabilities MCP tool, or the install script's list. The install script
installs the pip-wheel solvers and provisions the native ones —
scripts/install-solvers.sh on Linux/macOS (apt/conda + source builds), and
scripts/install-solvers.ps1 on Windows (pip extras +
portable SU2/Elmer/PrusaSlicer downloads; CalculiX auto-detected from FreeCAD's bundle).

Persistent config: every ANKUSDRIVE_* path can instead live in
~/.config/ankusdrive/config.toml (%APPDATA%\ankusdrive\config.toml on Windows;
ANKUSDRIVE_CONFIG overrides): freecadcmd = "..." at top level, one lowercased key per
solver var under [solvers] (su2_path, elmer_path, openfoam_bashrc, ...). Env vars
still win when set; the file is the layer that survives an MCP host's minimal launch
environment. ankusdrive doctor reports the file and which layer resolved each value.

Platform note: the solver discovery layer is fully cross-platform (per-OS install
dirs, Windows PATHEXT/.exe, env overrides), so ankusdrive doctor gives an honest report
on macOS/Linux/Windows. The pip-wheel families (MBD, topology, optics, fluids) install
identically everywhere. The native-binary families differ by OS — CalculiX ships inside
every FreeCAD install; SU2 and PrusaSlicer have good Windows/macOS binaries; Elmer has a
portable Windows zip but no macOS binaries; the
OpenFOAM-backed families (CFD, FSI, injection molding) still rely on a Linux shell +
linker glue and are Linux/WSL/Docker for now. See
docs/WINDOWS.md and docs/MACOS.md for the full
per-solver reality and setup on each OS.

The review-video demos under scratch/ turn a solver result into a GIF a human
can watch — the real exported geometry in motion with the matching oracle overlaid on
the frame (written to artifacts/). Each needs its family's solver plus matplotlib, and
the CFD one needs meshio (on top of the base numpy/Pillow):

pip install matplotlib meshio        # frame rendering + reading OpenFOAM's VTK output

All of them also use FreeCAD for the geometry/meshing, so run each with the same
interpreter that launches the worker — e.g. .venv/bin/python3 scratch/cfd_field_video.py.

Optics

Two optics engines sit behind the MCP surface, in two licensing/runtime lanes:

The sequential engines import in-process, so install the optics extra into the same
interpreter that launches the worker (like the other wheels). The non-sequential engine
is GPL-3.0 and is therefore never imported by AnkusDrive — it runs in a separate
subprocess (ankusdrive/optics_gpl_runner.py), the same
arm's-length boundary used for the GPL Elmer/OpenFOAM binaries. The worker locates a
Python that can import KrakenOS automatically (from where the wheel is installed); override
with ANKUSDRIVE_OPTICS_GPL_PYTHON=/path/to/python. Because of that isolation the GPL extra
is opt-in: the no-argument install-solvers.sh run installs only the permissive
extras and prints how to add optics_gpl. Rendered examples for both lanes (lens layout,
spot diagram, optimization, prism TIR, and a ball-lens spherical-aberration study) live in
examples/optics_gallery/ — regenerate with
.venv/bin/python examples/optics_gallery.py (and …_3d.py, optics_ball_lens.py), or
bootstrap everything in one shot (installs both lanes, then renders every figure):

scripts/install-solvers.sh --optics-gallery

Architecture sketch

 ┌────────────┐      ┌────────────┐      ┌──────────────────────┐
 │  MCP host  │ ───► │ AnkusDrive   │ ───► │  freecadcmd worker   │
 │  (Claude)  │      │ (Python)   │ IPC  │  (long-lived Python) │
 └────────────┘      └────────────┘      └──────────────────────┘
       ▲                    ▲                        │
       │                    │                        ▼
       └── CLI user ────────┘               .FCStd / .inp / .vtk

Key decision: long-lived worker with JSON-over-stdin/stdout, not subprocess-per-call. FreeCAD startup is ~1–2s; re-paying that per tool call is unacceptable for an interactive agent. The worker is a small Python loop launched under freecadcmd, reading commands, dispatching to handlers, returning structured results (including object IDs so follow-up calls can reference created geometry).

FreeCAD API surface we care about

Notes gathered from the scripting docs and the FEM Python tutorial:

Core (App):

• App.newDocument(name) / App.ActiveDocument / doc.recompute() / doc.save(path)
• doc.addObject("Part::Box", "name") — typed object creation; properties set after (box.Height = 5)
• doc.supportedTypes() for introspection; obj.TypeId, obj.isDerivedFrom("Part::Feature")

Modeling:

• Part — makeBox, makeCylinder, makeSphere, boolean cut/common/fuse, fillets, lofts (OpenCASCADE under the hood)
• Draft — 2D primitives, move, arrays
• Sketcher + PartDesign — parametric sketch-driven solids (most "real" mechanical design happens here)
• FreeCAD.Vector, Placement for positioning

FEM (ObjectsFem + femtools):

• ObjectsFem.makeAnalysis(doc, "Analysis") — container
• makeSolverCalculixCcxTools / makeSolverElmer — solver objects with tunables (GeometricalNonlinearity, ThermoMechSteadyState, …)
• makeMaterialSolid — assign YoungsModulus, PoissonRatio, Density
• Constraints: makeConstraintFixed, makeConstraintForce, makeConstraintPressure, makeConstraintDisplacement, contact/tie/spring, thermal
• Mesh: makeMeshGmsh + femmesh.gmshtools.GmshTools(...).create_mesh() (or Netgen)
• Run: femtools.ccxtools.FemToolsCcx().run()
• Results: iterate analysis.Group for Fem::FemResultObject; read .DisplacementVectors, stress fields

Headless invocation:

• freecadcmd script.py — runs script then exits
• freecadcmd with no args — interactive Python REPL (what the worker will drive)
• --console, -M <moddir>, -P <pypath>, --pass <args>, FreeCAD.ConfigGet(...) for env info
• FreeCADGui is not available headless — keep design logic in App/Part/Fem only

How an agent reaches FreeCAD: three layers

AnkusDrive exposes FreeCAD through three layers, each with a different audience
and a different cost-of-use. Knowing which layer a feature lives in tells you
how to invoke it.

Layer 1 — typed MCP tools (the agent surface)

280+ first-class MCP tools span the core mechanical-design surface, a broad
engineering-analysis / simulation surface, and a design-control (PLM)
layer. They have validated parameters, structured returns, and stable handles
for chaining. This is the happy path — what an agent uses for things people do
every day.

All tools return JSON; geometry-creating tools return a handle (e.g.
pad_1) that subsequent calls reference. The heavy simulation families return
a {ok: false, reason, install} dict (rather than crashing) when their solver
isn't installed — see Simulation solvers.

Layer 2 — generic property reflection

For the long tail of "I just need to tweak this one property" without a
dedicated tool:

• get_object(handle) — dump every entry in obj.PropertiesList with
  Quantities → float (mm/deg), Vectors → list, Placements → dict.
• set_property(handle, name, value) — set any single property by name.

Use this when a typed tool exists for the object kind but doesn't expose the
exact property you need (e.g. Refine on a Pad, Sections ordering on a
Loft, internal tunables on a CCX solver).

Layer 3 — run_script (the universal escape hatch)

For features that have no first-class MCP tool at all — e.g. Path
workbench (CAM toolpaths), Surface workbench, Arch/BIM, Spreadsheet,
TechDraw dimensions, contact/spring FEM constraints, B-spline sketcher
operations, expression-engine bindings, anything in a workbench AnkusDrive
doesn't wrap.

run_script(code='''
import Path
job = Path.Job.Create("Job", [_resolve("pad_1")])
__result__ = {"job_name": job.Name}
''')

Inside the script, the worker pre-injects: App / FreeCAD, Part,
ObjectsFem, plus _register(prefix, obj) / _resolve(handle) /
_handles so scripts can register new objects into the same handle
registry that typed tools use. Set __result__ = ... to a JSON-serializable
value to return data; print statements go to /dev/null.

The escape hatch costs more (the agent has to write FreeCAD Python) but
makes the entire FreeCAD API reachable. The Phase 2 plan's "After Phase 2"
section calls out which run_script patterns deserve promotion to typed
tools — that's how the surface grows over time.

What the CLI is (and isn't)

The CLI is not the agent surface — it's a human-debugging + transport
tool. Seven subcommands:

Agents do not invoke the CLI. They speak MCP via stdio after the host has
launched ankusdrive mcp. The CLI's job is (a) to start that server and
(b) to give a human a way to poke at the worker without writing an MCP
client.

Decision rule

Multi-agent design

The roadmap above is about deepening what one agent can do. The
orchestration/ layer is about many agents sharing the
work: split a product into components and subassemblies, build those in
parallel (each agent cold, seeing only its own contract slice), then merge the
whole back up with the joints actually fitting. The design is written up in
docs/MULTI_AGENT.md; it targets partition + merge,
not shared co-editing of one live document (a single worker = one
App.ActiveDocument, so concurrent mutation is a non-goal for now).

Concurrent agents on one MCP server — workspaces. FastMCP runs sync tools in
a thread pool, so a host can have several tool calls in flight at once. The
server keeps a pool of named workspaces, each its own freecadcmd process
with its own App.ActiveDocument and handle registry. Each concurrent agent
claims its own workspace with use_workspace(name) at the start of its session;
handles and documents do not cross workspaces. A client that never calls
use_workspace sees the historical single-worker behavior byte-for-byte
(everything routes to the default workspace). Worker.call() is internally
serialized so two threads can never interleave the stdin/stdout protocol on one
process. The pool is capped (ANKUSDRIVE_MAX_WORKSPACES, default 4) and idle
workspaces are reaped (ANKUSDRIVE_WORKSPACE_IDLE_S, default 900s) so abandoned
sessions don't leak processes; list_workspaces / close_workspace manage it.

The split of responsibilities is deliberate:

• AnkusDrive ships the thin, tool-agnostic primitives that make a merge
  verifiable — publish_interface (declare a component's mating frames),
  merge_assembly (combine component files into one assembly), and the
  gates that decide whether a merge is sound: interface_align_check
  (do published frames line up?), interference_check (do solids collide?),
  envelope_check (does it fit its bounding budget?), plus an
  assembly_lock / assembly_lock_check contract lockfile. These are real
  MCP tools usable by any host.
• orchestration/ is the host-side reference coordinator — explicitly
  not part of the ankusdrive package. Given a free-text brief it
  decomposes it into a validated manifest, fans out one builder agent per
  component, merge_assemblys them, reads the gates, and on failure
  renegotiates — re-dispatching only the components implicated by the
  failing gate — up to a round budget. It runs against a real Anthropic client
  or a scripted stub (ScriptedClient) for free dry runs; the merge and gates
  are real worker calls either way. Any host (Claude, another tool, a human)
  can use it, replace it, or ignore it — the only contract that matters is the
  manifest + the component files on disk.

How well partition+merge holds up is measured by a dedicated eval ladder
(tests/test_multiagent_m1.py / _m2.py, runnable in CI) with hard-oracle
merge gates and a single-agent baseline — see
tests/MULTI_AGENT_EVAL.md. Early experiments have
partition performing at or above the single-agent baseline on the harder toys.

Designs, not just parts — the design-control layer

Multi-agent orchestration partitions one product across a team. A separate
axis makes a design (not just a part) something you can parameterize, vary,
and evolve under control — the mechanisms a PLM/PDM workflow expects, mapped
onto AnkusDrive's deterministic, headless, git-diffable grain. The keystone
insight: the build recipe is the feature tree; the parameters are its inputs;
regeneration is re-running the recipe — so AnkusDrive gets parametric regen and
family tables without a live in-file expression engine. The full scoping and
rationale is in docs/DESIGN_HIERARCHY.md; the
agent-facing judgment lives in the design-modularly
skill.

• Parametric hierarchy — recipes (recipe, recipe_validate) are named,
  declared-input build templates (AnkusDrive's PowerCopy/UDF and its intra-part
  parametric model); a relations DAG drives driven dimensions from master
  parameters by formula (pitch_d = module * teeth, arithmetic only — no
  iterative solve, no double-driving); feature templates (feature_instantiate)
  graft reusable features onto reference geometry by name; the typed
  units layer rejects dimensionally-wrong inputs at the
  door ("5 N" for a length is an error, not a silent mis-scale).
• Variant families — family_materialize expands a row × column design
  table into a set of variants deterministically, running the recipe per row and
  allocating part numbers in table order.
• Identity & lifecycle — items (items_new) give a part a stable
  part-number identity decoupled from its file path; a lifecycle state machine
  (lifecycle_transition: in_work → in_review → released → obsolete) enforces
  released-immutability, and a Form/Fit/Function predicate decides revision bump
  vs. new part number on a change.
• Change control — ECOs (eco_create) are first-class change records;
  where_used / change_impact compute blast radius over the dependency graph
  before you commit; baseline_create / baseline_verify pin reproducible
  snapshots.
• Versioned interfaces — an interface-type registry (get_interface,
  nema17_face@1-style named/versioned types) plus a Liskov
  substitutability_check gate enforce Form/Fit/Function compatibility as code,
  so a swapped part is verified to actually mate.
• Projects — scaffold_project + project_validate /
  project_check_references promote the multi-agent directory convention to a
  first-class project.json (manifest-of-manifests) with a master/skeleton
  single-source-of-truth slot and reference-integrity guards.

Like the merge gates, these are thin, deterministic, mostly FreeCAD-free
primitives — the logic layers import and test without launching a worker.

Status

Phase 3 closed 2026-05-10 (v0.3.0). The core mechanical-design surface from
Phase 2 (2026-04-25) is intact; Phase 3 layered intent-encoding APIs on top of
it. Since then the tool surface has grown from ~100 to 280+ tools across
several waves: a command-tier expansion (parametric components + direct feature
ops + metrology), the multi-agent orchestration layer, a broad
engineering-analysis + external-solver simulation surface (thermal/CFD/CHT/
EM/acoustics/FSI/molding/granular/optics/multibody), and a design-control
(PLM) layer (items, recipes, variant families, lifecycle, ECO/change,
versioned interfaces, projects).

• Worker + transport — long-lived freecadcmd worker, newline-JSON over stdio with stdio hygiene (FreeCAD C++ chatter redirected off the protocol fd).
• CLI — ping, version, box, cylinder, export, run, mcp, fem cantilever, plus top-level --version.
• MCP server — FastMCP over stdio, 280+ typed tools across document lifecycle, primitives, selection (face/edge tags), full PartDesign (sketcher + pad/pocket/revolve/hole/loft/sweep/helix/fillet/chamfer/pattern/mirror/thickness/draft), direct-modeling feature ops, parametric components, metrology/inspection, generic property reflection, mass properties, assembly + interface gates, TechDraw (incl. headless PDF/SVG/DXF export, dimensions, gates), multi-view + photoreal rendering, FEM (static + modal + buckling + thermal + nonlinear + result-probe), the engineering-analysis oracles and external-solver simulation families (sync + async *_submit/job_*), the materials/fluids corpora, Design-for-X / manufacturing checks, the design-control (PLM) layer, and transactions.
• Command tiers 1–3 — 21 new tools: parametric components (add_gear, add_rack, add_sprocket, add_pulley, add_spring, add_fastener, add_bearing, add_thread), direct feature ops (fillet_edges, chamfer_edges, shell_solid, add_rib, engrave_text, oring_groove, transform, scale_shape, copy_shape), and metrology/inspection (measure_distance, measure_angle, bounding_box, check_shape, section_view, min_clearance).
• Multi-agent orchestration — AnkusDrive ships the thin merge primitives + gates (publish_interface, merge_assembly, interface_align_check, envelope_check, assembly_lock/_check); the host-side reference coordinator (orchestration/) decomposes a brief, fans out per-component builders, merges, gates, and renegotiates. See Multi-agent design and docs/MULTI_AGENT.md.
• Phase 3 intent-encoding additions — direction='into_body'|'away_from_body' and through='wall'|'body' on pocket/hole (ray-cast wall depth handles hollow shells correctly); intended_for='print'|'machine'|'drawing' on hole drives ModelThread; verify_feature diffs actual-vs-expected volume change to catch silent failures; visibility hygiene at save hides consumed inputs; register_handle + run_script auto_register close the escape-hatch one-way trapdoor; list_thread_options surfaces the coupled ThreadType/ThreadSize enums dynamically; revolve has an OCCT pre-check that flags axis-coincident edges with an actionable error.
• Selection layer — list_faces / list_edges / query_faces / resolve_* produce stable geometric tags that survive edits; FEM constraints take tags directly.
• Rendering — host-side software rasterizer (ankusdrive/render.py) with per-pixel z-buffer (render_view / render_views return PNGs as MCP ImageContent), plus photoreal render_photoreal via the FreeCAD Render addon + an external renderer (POV-Ray / LuxCore / Appleseed / Cycles / OSPRay / PBRT). Support matrix, install, and limitations: docs/RENDERING.md.
• Simulation surface — engineering-analysis oracles (machine elements, structural, durability, thermal, tolerance/GD&T) plus external-solver families that shell out to OpenFOAM / Elmer / CalculiX / openEMS / YADE / KrakenOS, discovered at runtime by ankusdrive/solvers.py and degrading cleanly when absent. Long solves use an async submit→poll job pattern (*_submit + job_status/job_result/job_list). Catalog and result schemas: docs/SIMULATION_TOOLS.md; proof harness: docs/SIMULATION_EXAMPLES.md. Materials/fluids back these via material_* and fluid_props (mechanical-property / molding / CoolProp corpora).
• Design-control (PLM) layer — recipes + a relations DAG (parametric regen), feature templates, variant families from a design table, item/part-number identity, a lifecycle/revision state machine, ECO change records with where-used/impact + baselines, a versioned interface registry + Liskov substitutability gate, and project containers with reference-integrity guards. Scoping + rationale: docs/DESIGN_HIERARCHY.md. See Designs, not just parts.
• Tests — ~980 test functions across ~90 files (worker / MCP / CLI / render / determinism / edit stability / negative paths / perf / multi-agent / simulation families / molding / PLM layer), runnable via tests/run_all.sh (Linux/macOS) or tests/run_all.ps1 (Windows — single-interpreter, skips the Linux-only solver families; see docs/WINDOWS.md). Reliability harness (Layer A classification, B diff-detection, C agent-loop closure) is gated behind RUN_RELIABILITY=1; see tests/RELIABILITY.md.

See docs/ROADMAP.md for the Phase 1/2 per-slice record — a
changelog of how the surface above was built, frozen at the close of Phase 2. Open
work (FEM contact/spring/tie refinements, fully async fem_run, feature_tree
introspection, deeper external-solver integrations) lives on the
issue tracker, not in that file.

The committed showcase — every GIF, render, drawing and exported solid the docs point
at, with the script that regenerates each one — is indexed in
artifacts/README.md.

Open questions

• Error model: FreeCAD raises plain Python exceptions from C++; worker catches and serializes them, but stack context across the JSON boundary is still lossy.
• Async / concurrency: multi-doc shipped (list_documents / set_active_document / close_document), and the long-running external solvers run off the channel via the *_submit + job_* pattern, but the in-worker fem_run itself is still synchronous and blocks the MCP channel for the duration of a CalculiX/Elmer solve.
• macOS Gatekeeper / sandboxing: freecadcmd launched from a non-interactive context may hit quarantine issues. This has never been confirmed either way — tracked in #310, which will either document the fix or delete this caveat.

Privacy Policy

AnkusDrive runs entirely on your computer and collects nothing: no telemetry, no
analytics, no accounts, and no network requests from its own code. It reads and writes
only the files you point it at, plus its config file and temp working directories. Your
MCP host (e.g. Claude Desktop) sends tool inputs and results to its AI model provider
under the host's own policy. The full policy, including exactly what is stored where, is
in PRIVACY.md.

Evaluating the Claude Desktop extension? The reviewer guide
covers installation, a setup check, and three example prompts with expected results.

License

Licensed under the Apache License, Version 2.0. Contributions
submitted to this project are licensed under the same terms (Apache 2.0
§5: inbound = outbound), which means contributors retain copyright but
grant the project — and everyone downstream — a perpetual, irrevocable
license to use their work, including a patent grant. The intent is to keep
the project welcoming to contributors while ensuring nobody can later
re-proprietize what they contributed.

The code is Apache-2.0; the name is not. Apache-2.0 §6 grants no trademark
rights, so the AnkusDrive word mark and the brand assets in
logo/
are covered separately — see
TRADEMARKS.md
for what you may do without asking (referring to the project, compatibility
claims, redistribution, packaging, and forking all qualify) and
NOTICE for the
attribution a redistributor must carry.

References

• FreeCAD Scripting Basics
• Python scripting tutorial
• Start up and Configuration
• FEM Workbench
• FEM Tutorial Python — full cantilever example
• Model Context Protocol