freecad-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# uv lives in ~/.local/bin, which is NOT on the default shell PATH here —
# start Bash work with: export PATH="$HOME/.local/bin:$PATH"
uv sync --extra dev              # install deps (uv is the package manager; pytest lives in the "dev" extra)
uv run pytest                    # run the test suite
uv run pytest tests/test_ip_filter.py -k allowed   # single file / single test
uv run ruff check .              # lint (CI enforces this; config in pyproject.toml)
uv run freecad-mcp               # run the MCP server (stdio transport; needs FreeCAD running with the RPC server started)

The eval harness is separate from the tests and needs a live FreeCAD instance: python -m eval.run_eval --repeat 3 --case plate-holes (see eval/README.md).

Architecture

Two processes talk over XML-RPC on port 9875:

MCP client (Claude) <--MCP/stdio--> src/freecad_mcp/ server <--XML-RPC--> addon/FreeCADMCP/ (inside FreeCAD's Python)

• src/freecad_mcp/ — the MCP server, installed via uvx freecad-mcp. server.py declares the tools (thin wrappers), operations/core.py implements them, freecad_client.py is the XML-RPC client. corpus.py transparently logs every mutating call (via the _CorpusLoggingConnection wrapper in server.py) to build a corpus of successful build sequences (begin_build/finish_build/find_similar_builds tools).
• addon/FreeCADMCP/rpc_server/ — runs inside FreeCAD's own interpreter with full access to the native API (FreeCAD, Part, Sketcher, …). rpc_server.py registers the RPC methods; the real logic lives in the per-domain modules (sketch_ops.py, feature_ops.py, placement_ops.py, object_factory.py, …). FreeCAD API calls must run on the GUI thread — that's what gui_dispatch.py is for.
• Version skew is a supported configuration: users update the MCP server (uvx) without reinstalling the addon, so the server must degrade gracefully when the addon side lacks a newer RPC method (see place's fallback for an example). Never assume both sides are the same version.