cadpilot: Instructions file for Codex

CADPilot — Workspace Guide

Purpose

MCP (Model Context Protocol) server that lets AI clients (Claude Desktop, LangChain, etc.) control FreeCAD remotely. Two main components communicate over XML-RPC:

1. MCP server (src/cadpilot/) — Python package run via uvx cadpilot or uv run cadpilot. Speaks MCP to the AI client and XML-RPC to FreeCAD.
2. FreeCAD addon (addon/CADPilot/) — Installed into FreeCAD's Mod/ directory. Hosts the XML-RPC server inside the FreeCAD process and dispatches all document/GUI work onto the main thread.

Directory Layout

src/cadpilot/          # MCP server package (published to PyPI)
  server.py               # FastMCP tool definitions & CLI entry point (main())
  freecad_client.py       # XML-RPC client proxy to FreeCAD addon
  operations/core.py      # Tool operation implementations (one function per tool)
  operations/__init__.py  # Re-exports all operations
  responses.py            # ToolResponse type alias, text/json helpers + screenshot file delivery
  server_state.py         # ServerState dataclass (connection, host, text-only/auto-audit flags)
  session_state.py        # ModelingSession/Step dataclasses, JSON persistence, current-session registry
  assembly_state.py       # AssemblySession/AssemblyStep dataclasses, JSON persistence (~/.cadpilot/assembly/), precomputed-undo rollback
  operations/assembly.py  # assembly_session tool: spec validation → RPC assembly_op → session recording
  pattern_store.py        # Pattern memory (reusable workflows), keyword retrieval
  guidance.py             # Lightweight next-step suggestions & risk heuristics (incl. primitive_without_sketch / absolute_placement / assembly-mode steer)
  diagnostics.py          # diagnose tool: cross-platform fault probing that works with FreeCAD down (no FreeCAD import)
  prompt_text.py          # ASSET_CREATION_STRATEGY prompt template
  tool_docs.py            # Long per-operation reference docs served by the operation_help tool

addon/CADPilot/             # FreeCAD workbench addon (copied to FreeCAD's Mod/ dir)
  InitGui.py              # Workbench registration, toolbar/menu, auto-start
  Init.py                 # Path setup
  rpc_server/
    rpc_server.py         # FreeCADRPC class — XML-RPC handler, server start/stop
    gui_dispatch.py       # dispatch_to_gui() — queues work onto the GUI thread
    commands.py           # FreeCAD Command classes for toolbar buttons
    object_factory.py     # create_object_gui() — object creation logic
    property_mapper.py    # set_object_property() — recursive property assignment
    serialize.py          # serialize_object() — object → dict for RPC responses
    view_manager.py       # save_active_screenshot() — camera/view screenshot logic
    geometry_query.py     # Read-only Shape queries — measure/topology/interference
    assembly_ops.py       # Anchor-based assembly — anchors (auto/explicit), assemble (mates), verify_assembly
    joint_ops.py          # Persistent-joint assembly — FreeCAD 1.1 Assembly WB lifecycle (Link wrap, joints, preSolve+solve, rollback, verify+gap profile)
    trim_ops.py           # Declarative priority trimming — non-destructive baked cut in loser-link frame
    feature_ops.py        # Parametric feature creation (boolean/fillet/sketch/pad/...) + selectors
    sketcher_ops.py       # Constrained-sketch builder (geometry/constraints/solver diagnostics)
    ip_filter.py          # FilteredXMLRPCServer — IP/CIDR allowlist
    settings.py           # JSON settings persistence (auto-start, remote, allowed IPs)
    step_journal.py       # Pure step model: StepRecord, planned/done arithmetic, review helpers
    step_engine.py        # FreeCAD half of the journal — apply_op, per-step transactions, undo
    step_panel.py         # CADPilot Steps dock — review loop UI (status dots, param editor)
    dbglog.py             # Ring-buffer debug log + rotating file (readable while GUI is wedged)
    request_log.py        # Tags log records with the RPC request that caused them

examples/                 # Showcase models (.FCStd) and their PNG renders
tests/                    # pytest suite for the MCP server side (fake XML-RPC connection) and tests/live_complex_verify.py — the ACCUMULATING live regression corpus: complex real-scenario builds (parametric flange, enclosure, hinge assembly, journal truth, session semantics, async) asserting analytic volumes against a RUNNING FreeCAD; stress rounds ADD cases here instead of writing throwaway probes (run: .venv/Scripts/python.exe tests/live_complex_verify.py)
evaluations/              # mcp-builder Phase 4: read-only QA pairs + run notes