cadpilot 0.4.0__tar.gz

cadpilot-0.4.0/.gitattributes

@@ -0,0 +1,7 @@
+# Normalize line endings: LF in the repository, platform-native on checkout
+* text=auto
+
+# Never convert binary assets
+*.png binary
+*.gif binary
+*.FCStd binary

cadpilot-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run --no-sync ruff check .
+
+      - name: Format check
+        run: uv run --no-sync ruff format --check .
+
+      - name: Test
+        run: uv run --no-sync pytest -q

cadpilot-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Run tests
+        run: |
+          uv sync
+          uv run --no-sync pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cadpilot-0.4.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+build/
+*.egg-info/
+
+# FreeCAD working files (demos / backups)
+*.FCStd
+*.FCBak
+*.FCStd1
+
+# Local plans / skills
+docs/superpowers/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+
+# IDE
+.idea/
+.vscode/
+.zcode/
+
+# Local secrets
+.env
+
+# Allow the demo model in examples/
+!examples/ModernBicycle.FCStd

cadpilot-0.4.0/.python-version

@@ -0,0 +1 @@
+3.12

cadpilot-0.4.0/AGENTS.md

@@ -0,0 +1,190 @@
+# 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/screenshot helpers
+  server_state.py         # ServerState dataclass (connection, host, screenshot 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)
+  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)
+
+examples/                 # Usage examples (adk/agent.py, langchain/react.py)
+tests/                    # pytest suite for the MCP server side (fake XML-RPC connection)
+assets/                   # Demo GIFs and images for README
+```
+
+## Build & Run
+
+```bash
+# Install dependencies (requires Python ≥3.12, uv)
+uv sync
+
+# Run MCP server locally (developer mode)
+uv run cadpilot                          # connects to FreeCAD on localhost:9875
+uv run cadpilot --with-screenshots       # attach screenshots by default (multimodal models)
+uv run cadpilot --only-text-feedback     # never return screenshots (hard guarantee)
+uv run cadpilot --host 192.168.1.100     # connect to remote FreeCAD
+
+# Publish to PyPI (via hatchling)
+uv build
+
+# Run tests (MCP server side only; the addon needs a live FreeCAD)
+uv run pytest
+```
+
+The FreeCAD addon must be installed separately — copy `addon/CADPilot/` into FreeCAD's `Mod/` directory and restart FreeCAD.
+
+## Addon Hot-Reload (No Restart)
+
+During development you can reload the addon **without restarting FreeCAD**:
+
+1. Copy the updated addon files to the live `Mod/` directory:
+   ```bash
+   cp -rf "H:/My_Software/FreeCAD-MCP/addon/CADPilot/." \
+          "C:/Users/intel/AppData/Roaming/FreeCAD/v1-1/Mod/CADPilot/"
+   ```
+
+2. In FreeCAD's Python console (or via `execute_code`) run:
+   ```python
+   import sys, importlib
+   import rpc_server.rpc_server as rs_old
+
+   print("stop:", rs_old.stop_rpc_server())
+
+   from PySide import QtCore  # or PySide6 / PySide2
+
+
+   def _start(rs):
+       result = rs.start_rpc_server(9875)
+       print("start:", result)
+       if "still stopping" in str(result):
+           # Previous stop is still draining; retry instead of giving up
+           # (giving up here leaves a half-restarted server: socket dead,
+           # no heartbeat, every GUI-dispatched call hangs).
+           QtCore.QTimer.singleShot(4000, lambda: _start(rs))
+
+
+   def restart():
+       for sub in [
+           "ip_filter",
+           "settings",
+           "gui_dispatch",
+           "object_factory",
+           "property_mapper",
+           "serialize",
+           "view_manager",
+           "commands",
+           "geometry_query",
+           "assembly_ops",
+           "trim_ops",
+           "joint_ops",
+           "sketcher_ops",
+           "feature_ops",
+       ]:
+           name = f"rpc_server.{sub}"
+           if name in sys.modules:
+               importlib.reload(sys.modules[name])
+       rs = importlib.reload(rs_old)
+       _start(rs)
+
+
+   # Deferred restart: the in-flight XML-RPC request blocks shutdown drain,
+   # so we wait 4s for server_close() to finish before re-binding the port.
+   QtCore.QTimer.singleShot(4000, restart)
+   ```
+
+3. Wait ~8 seconds before issuing the next MCP call so the new server is ready.
+
+4. If GUI-dispatched calls (e.g. `execute_code`) hang after the reload but
+   `ping` still answers, the heartbeat/waker chain died during the race.
+   Repair via `execute_code_async` (its worker runs without GUI dispatch):
+   ```python
+   import rpc_server.gui_dispatch as gd
+   from PySide import QtCore
+   import FreeCADGui
+
+   def repair():
+       while not gd._rpc_request_queue.empty():
+           t = gd._rpc_request_queue.get()
+           if t is not gd._SHUTDOWN:
+               t()
+       QtCore.QTimer.singleShot(500, gd.process_gui_tasks)
+
+   QtCore.QTimer.singleShot(0, FreeCADGui.getMainWindow(), repair)
+   ```
+
+> **Why deferred?** `stop_rpc_server()` calls `shutdown()` which blocks until the current request drains, and `server_close()` must release the socket before `start_rpc_server()` can bind again. Running the restart synchronously inside the same `execute_code` call deadlocks because the request itself is blocking shutdown. The `QTimer` deferral runs on FreeCAD's main GUI thread after the RPC call returns.
+
+## Architecture & Key Constraints
+
+- **GUI thread rule**: All FreeCAD document/GUI operations MUST run on FreeCAD's main (GUI) thread. The addon uses `dispatch_to_gui()` to queue lambdas and a `QTimer` waker to process them. Never call FreeCAD APIs directly from the RPC server thread.
+- **Two-process model**: The MCP server and FreeCAD run in separate processes. They communicate exclusively via XML-RPC on port 9875. The MCP server never imports FreeCAD.
+- **MCP version compatibility**: `server.py` imports `FastMCP` from `mcp.server.fastmcp` (1.x) with a fallback to `MCPServer` from `mcp.server.mcpserver` (2.x). Keep both paths working.
+- **Timeouts**: Default XML-RPC transport timeout is 150s. `execute_code` has a 90s GUI-thread timeout; use `execute_code_async` for longer operations.
+- **Reconnect**: `FreeCADConnection._invoke` rebuilds the XML-RPC proxy and retries once on dead-connection errors (FreeCAD/addon restart). Socket timeouts are NOT retried — the op may still be executing server-side.
+- **Screenshot handling**: Screenshots are OPTIONAL and off by default. Per-call `with_screenshot` params opt in; `--with-screenshots` makes them default-on; `--only-text-feedback` is a hard off that overrides everything (see `ServerState.resolve_screenshot`). Screenshots are base64 PNG via temp files. Mutation tools (create/edit/delete/execute_operations) capture the screenshot inline in the same RPC dispatch; the client falls back to a second `get_active_screenshot` call against old addons. When no explicit size is given, the long edge is capped at 768px (`DEFAULT_MAX_DIM` in `view_manager.py`). Some view types (TechDraw, Spreadsheet) don't support screenshots — `get_active_screenshot` returns `None` in those cases.
+- **Async tasks**: `execute_code_async` returns a `task_id`; status, `task_print()` output, and tracebacks are kept in a bounded in-memory registry (`_async_tasks`, FIFO max 50) and polled via `get_task_result`. `sys.stdout` is never redirected for background tasks (process-wide race).
+- **Unified cad() tool**: All mutations go through `cad(operation=...)` (nsforge math()-style dispatcher) to keep the tool list small. Steps: the operation functions in `operations/core.py` remain the implementation; `cad_operation` dispatches and records session steps. Scope is modeling-only — FEM analysis, the parts library, and `reload_document` were removed in v0.2. Feature ops (boolean/fillet/chamfer/loft/sweep/mirror/pattern, plus Sketcher/PartDesign: variables/sketch/pad/pocket/revolution/groove/thickness/draft since v0.3, plus datum_plane/hull since v0.4) share the single RPC `create_feature` and pass params as a spec dict (obj_name = base, obj_properties = params). For `sketch`/`variables`/`datum_plane`/`hull`, obj_name names the NEW object and `spec["base"]` carries it (see `CAD_NO_BASE_OPERATIONS`). Sketches are built atomically in `sketcher_ops.py` (geometry + constraints in one transaction, solver runs immediately); results carry `dof`/`fully_constrained`/`warnings` via `describe_feature`, failures roll back with solver diagnostics. Thickness/draft support both the FreeCAD ≥1.1 LinkSub `Base` layout and the ≤1.0 `Faces` property (probe `PropertiesList`).
+- **Sketch mode details** (live-verified on FreeCAD 1.1.3): sketch `external: [[obj, "EdgeN"|"VertexN"], ...]` adds external geometry (GeoIds from -3 in list order, start/end points ONLY — `mid`/`center` on external ids fails at solve with MalformedConstraints, so `_check_external_point_refs` rejects it up front); out-of-body targets are auto-bridged via `PartDesign::SubShapeBinder` (`_external_binder`, idempotent `Ext_<obj>_<elem>`) because PartDesign rejects external geometry outside the sketch's body, and `addExternal` takes `(str, str)`. `datum_plane` attaches a PartDesign::Plane to an origin plane (`body.Origin.OriginFeatures` Role lookup) or an existing face (FlatFace + optional offset); sketches attach via `plane={"datum": name}`. `hull` = visual hull: intersect 2-3 view-profile sketches extruded along their sketch normals (extent = union bbox projected per-normal ±`margin`, default max(1mm, 5% of diagonal)); result is a STATIC `Part::Feature` (no proxy — survives document reload), same-name re-run replaces the Shape in place (iterate), multiple solids → largest wins, empty intersection → RuntimeError. v1 limits: view sketches at the global origin, one closed outer profile per view. **Attachment fusion**: pad/pocket on a sketch attached to a solid's face (directly or through a datum plane) operate on THAT solid via attachment — pocket cuts it, pad fuses into it; do NOT pad-then-boolean-cut (the pad already contains the base solid). **execute_code + openTransaction**: always pair with try/except → `doc.abortTransaction()` — a leaked transaction leaves broken objects that poison later recomputes (null shapes).
+- **Geometry sensing**: `measure_geometry`/`get_topology`/`check_interference` are read-only Shape queries (addon `geometry_query.py`), dispatched to the GUI thread without a transaction. Values are rounded to 4 significant digits; topology lists are size-sorted and paginated (`limit`/`offset`).
+- **Assembly toolchain**: `get_anchors`/`set_anchors`/`assemble`/`verify_assembly` (addon `assembly_ops.py`) give the model data-driven spatial awareness — no screenshots required. Anchors are named points+directions: auto-derived per object (`bbox_center/min/max`, `com`, `axis_mid/start/end` from the dominant cylindrical face, `face0-2_center` from the largest planar faces) plus explicit named ones stored as JSON in an `App::PropertyString` named `MCP_Anchors` in LOCAL coords (they follow Placement). `set_anchors(coord_frame="global")` converts via `obj.Placement.inverse()` at write time — use it whenever the source coordinates are global, because many objects carry non-identity Placements. `assemble` takes a mate list `{obj, anchor, target, target_anchor, mode: center|touch|axis, offset}`, applies each mate in one FreeCAD transaction, then RE-RESOLVES the anchor post-move to report per-mate residuals (mm + deg) and aborts on `tolerance` violation; partial commit via `commit_if` when at least one mate passed. `verify_assembly` audits the whole document: floating objects (nearest-neighbour distance via bbox prefilter + `distToShape`), interferences (common volume for bbox-overlapping pairs), and explicit anchor-pair checks with per-check tolerance. PRECISION RULE: `_r()`/`_vec()` rounding (4 sig digits) applies ONLY at the report boundary — `_resolve_anchor`/`_auto_anchor_map` must return RAW `FreeCAD.Vector`s for math (rounding at ~1000mm coords = 0.1mm granularity → false residuals). `verify_assembly` also builds a union-find **contact graph** from pairs already scanned (exact `distToShape` ≤ `_CONTACT_TOLERANCE` = 0.5mm, or common volume > threshold) and reports connected components: the largest is the main assembly, the rest are `islands` (with `gap_mm`/`nearest_main`).
+- **Connectivity auto-audit**: after every committed `cad()` mutation, `cad_operation` re-runs the read-only `verify_assembly` audit and appends a "⚠ Connectivity" warning (formatted by `_format_connectivity_warning`) to both the tool response and the recorded step's `result_summary`; `detect_risks` surfaces it as a `disconnected_islands` risk in `session_status`. Guards: skipped when `object_count > _AUTO_AUDIT_MAX_OBJECTS` (300), when the addon is old (no `islands` key), or globally via `--no-auto-audit` (`ServerState.auto_audit`). Audit failures never block the mutation.
+- **Assembly mode (`assembly_session` tool)**: independent state machine for mate-based assembly with PERSISTENT joints (FreeCAD 1.1 native Assembly workbench — `Assembly::AssemblyObject` with `Type="Assembly"`, `App::Link` components that own Placements, `JointObject.Joint` joints in the JointGroup). Ops: start(ground) / add_component / mate / solve / unmate / rollback(to_step) / verify / status / complete. Mate refs: `{"part", face|anchor|point}` — resolved to `(link, ["FaceN", "VertexM"])` where the vertex sets the mate landing point (GUI click semantics). `preSolve` (matchJCS) runs before the final single `solve(True)` — skipping it lands mates with faces perpendicular; repeated solve passes corrupt storePrev state. Frames: `link.Shape` is GLOBAL, joint references/`findPlacement` are part-LOCAL; residuals are geometric truth (`fa.distToShape(fb)` + normal angle), never JCS math. `trim={"winner":...}` bakes a non-destructive cut in the loser-link local frame and re-points the link; rollback deletes joints/cuts, re-points links, restores pre-mate placements (precomputed per-step undo, merged by `assembly_state.plan_rollback`). Gap profiles sample the a-face UV grid and measure perpendicular lift from the mate plane (overhang ≠ gap).
+- **Modeling sessions**: `session_state.py` binds a session to one document. Every committed mutation runs inside a FreeCAD transaction (addon `_run_op_with_screenshot` wraps `doc.openTransaction`), so `session_rollback` = `doc.undo()` × N + log truncation; removed steps sit in a redo buffer until a new step (mirrors FreeCAD redo semantics). `execute_code` steps are non-atomic and block rollback unless forced. Sessions/patterns persist under `$CADPILOT_HOME` (default `~/.cadpilot/`). Mutation results carry an `objects` fingerprint (sorted object names) used to detect state drift after rollback.
+- **Knowledge hierarchy**: prompts instruct ① model's own knowledge → ② `recall_patterns` → ③ `inspect_freecad`; successful approaches are stored via `save_pattern`/`session_complete`.
+- **Name sanitization**: FreeCAD sanitizes document/object names (spaces → underscores, deduplication). RPC handlers return the *actual* name from FreeCAD, not the requested name.
+
+## Coding Conventions
+
+- Python 3.12+ (uses `X | None` union syntax, `type` alias).
+- Logging: use `logging.getLogger("CADPilotserver")` in both MCP server and addon code.
+- Tool operations: each tool has a dedicated `_operation` function in `operations/core.py` that takes a `FreeCADConnection` as its first arg and returns a `ToolResponse` (`list[TextContent | ImageContent]`).
+- Addon code uses `FreeCAD.Console.PrintMessage/PrintError/PrintWarning` for FreeCAD's Report View.
+- Settings persisted as JSON via `cadpilot_settings.json` (in FreeCAD's user data dir).
+- **Docstring budget (prompt economy)**: every `@mcp.tool()` docstring is injected into the AI client's context on `tools/list`. Keep docstrings to a 1-3 line summary + brief Args — long parameter/semantics references go in `src/cadpilot/tool_docs.py` (`CAD_OP_DOCS`) and are served on demand via the `operation_help` tool. `tests/test_operation_help.py::test_tool_docstring_budget` enforces a total budget (< 14,000 chars across all tools); it fails if docstrings creep back up.
+
+## Adding a New MCP Tool
+
+1. Add the operation function in `src/cadpilot/operations/core.py`.
+2. Export it from `src/cadpilot/operations/__init__.py`.
+3. Add the `@mcp.tool()` handler in `src/cadpilot/server.py` that calls the operation.
+4. Add the corresponding RPC method in `addon/CADPilot/rpc_server/rpc_server.py` (on the `FreeCADRPC` class).
+5. Add the client proxy method in `src/cadpilot/freecad_client.py`.
+6. If the tool touches the document/GUI, dispatch via `dispatch_to_gui()` in the addon.

cadpilot-0.4.0/CHANGELOG.md

@@ -0,0 +1,204 @@
+# Changelog
+
+## v0.4.0 (2026-07-30)
+
+### Renamed to CADPilot
+
+The project has been renamed from `freecad-mcp` to **CADPilot** (AI pilots FreeCAD). All identifiers updated:
+
+- PyPI package: `freecad-mcp` → `cadpilot`
+- Python module: `freecad_mcp` → `cadpilot`
+- CLI command: `uvx freecad-mcp` → `uvx cadpilot`
+- FreeCAD addon directory: `FreeCADMCP` → `CADPilot`
+- Workbench name: "FreeCAD MCP" → "CADPilot"
+- Environment variable: `FREECAD_MCP_HOME` → `CADPILOT_HOME`
+- Data directory: `~/.freecad-mcp` → `~/.cadpilot`
+- Settings file: `freecad_mcp_settings.json` → `cadpilot_settings.json`
+- Logger name: `FreeCADMCPserver` → `CADPilot`
+
+### New features (since v0.3.0)
+
+- `datum_plane` and `hull` feature operations in `cad()`
+- Assembly session with persistent joints (FreeCAD 1.1 Assembly workbench)
+- Connectivity auto-audit after every `cad()` mutation
+- Declarative priority trimming (`trim={"winner": ...}`)
+
+### Fixed
+
+- **`execute_code` namespace pollution**: user code now runs in a copy of the
+  addon module's globals (same as `execute_code_async`) — assignments can no
+  longer corrupt the RPC server's own namespace across calls.
+- **Assembly state robustness** (`assembly_state.py`): `load()` returns `None`
+  on missing/corrupt/structurally-invalid session files instead of raising
+  (consistent with `session_state.load_session`); `save()` is now atomic
+  (tmp + replace) so a failed write can't truncate a saved session; the
+  `_current` registry is guarded by a lock.
+- **`assembly_session` RPC error handling** (`operations/assembly.py`):
+  `start` / `add_component` / `mate` / `unmate` / `rollback` now check the
+  addon result for `{"success": false}` before consuming fields — a failed
+  RPC returns the addon's error message and records nothing (previously
+  crashed with `KeyError` after a half-mutated state). `mate` no longer
+  crashes when the result carries trim data but the call passed no `trim`.
+- **Dev tooling**: the ruff config parsed invalidly (`[tool.ruff.format]
+  line-length`), silently disabling all lint/format runs; fixed and the whole
+  tree re-linted/reformatted (136 findings resolved).
+
+## v0.3.0
+
+### New features
+
+- **Constrained sketches + PartDesign** — eight new `cad()` feature ops enabling
+  the full "variables → sketch → solid → dress-up" parametric chain:
+  - `variables` — create/update a Spreadsheet parameter table (`cells: {"A1": [alias, value]}`,
+    idempotent); everything downstream binds to it via `=Spreadsheet.alias`.
+  - `sketch` — atomic constrained sketch (`Sketcher::SketchObject` inside a
+    PartDesign Body, auto-created when absent). `geometry` (line/arc/circle/bspline/point;
+    list order = GeoId) + `constraints` (coincident, horizontal, vertical, tangent,
+    perpendicular, parallel, equal, symmetric, distance, distance_x, distance_y,
+    radius, angle) are applied in one transaction and solved immediately.
+    Point references are `[geo_id, "start"|"end"|"center"|"mid"]`; `[-1, *]` is the
+    origin. `plane`: "XY"/"XZ"/"YZ" (+`offset`) or `{"face": [obj, "FaceN"]}`.
+    Dimensional values accept `=expressions`. Results report `dof` /
+    `fully_constrained`; under-constrained sketches succeed with a warning,
+    conflicting/failed ones roll back with solver diagnostics
+    (`ConflictingConstraints`, `RedundantConstraints`).
+  - `pad` / `pocket` — PartDesign extrusion from a sketch (closed profile
+    enforced), `length`/`reversed`/`midplane`.
+  - `revolution` / `groove` — PartDesign revolve, `axis` ("X"/"Y"/"Z" sketch axes
+    or `{"edge": [obj, "EdgeN"]}`) and `angle`.
+  - `thickness` / `draft` — dress-up ops; FreeCAD ≥1.1 LinkSub `Base` and
+    ≤1.0 `Faces` property layouts both supported. `pull_direction` takes
+    `{"edge": [obj, "EdgeN"]}`.
+- Live verification script: `scripts/live_sketch_verify.py` (runs against a live
+  FreeCAD; builds a parametric bracket and checks volumes, expression
+  propagation, failure diagnostics, and undo).
+
+## v0.2.0 (2026-07-30)
+
+### Breaking changes
+
+- Four standalone tools are merged into a single unified **`cad()`** tool
+  (nsforge `math()`-style dispatcher, reduces resident tool context):
+  - `create_object` → `cad(operation="create_object", doc_name, obj_type, obj_name, ...)`
+  - `edit_object` → `cad(operation="edit_object", ...)`
+  - `delete_object` → `cad(operation="delete_object", ...)`
+  - `execute_operations` → `cad(operation="batch", ops=[...])`
+- **Removed** (modeling-only scope):
+  - `run_fem_analysis` and all `Fem::` object creation support
+    (addon `fem_executor.py` gone; no CalculiX/Gmsh dependency)
+  - `get_parts_list` and `insert_part_from_library` (addon `parts_library.py` gone)
+  - `reload_document`
+- **RPC response format**: `get_objects`, `get_object`, and `list_documents` now
+  return `{"success": true, "objects"/"object"/"documents": ...}` instead of bare
+  lists/dicts. The MCP client (`freecad_client.py`) handles the conversion
+  transparently, so MCP tool callers see the same data — but direct XML-RPC
+  consumers must adapt.
+- Clients calling the removed/merged tools must switch to `cad()`.
+
+### New features
+
+- **Modeling sessions**: `session_start` / `session_status` / `session_get_steps` /
+  `session_rollback` / `session_redo` / `session_add_note` / `session_pause` /
+  `session_resume` / `session_list` / `session_complete`.
+  - Every committed mutation runs inside a FreeCAD transaction; `session_rollback`
+    maps to native `doc.undo()` with log truncation, `session_redo` mirrors FreeCAD
+    redo semantics (a new step clears the redo buffer).
+  - `execute_code` steps are non-atomic and block rollback unless `force=True`.
+  - Sessions persist as JSON under `$CADPILOT_HOME/sessions/` (default
+    `~/.cadpilot/sessions/`).
+- **Pattern memory**: `save_pattern` / `recall_patterns` — successful workflows can be
+  stored and retrieved by keyword search (CJK-safe substring matching).
+  `session_complete` can archive a session as a pattern.
+- **Runtime introspection**: `inspect_freecad` — inspect an object's properties/methods
+  or a dotted-name API docstring without leaving the session.
+
+### Fixed
+
+- **Double coordinate transform in geometry queries**: FreeCAD Shapes carry the
+  object's Placement as their internal location, so `BoundBox`, `CenterOfMass`,
+  `Vertex.Point`, `Face.Surface` (Axis/Center) and `Face.normalAt` already return
+  GLOBAL coordinates. `measure_geometry` / `get_topology` / `get_positioning_info`
+  applied `obj.Placement` a second time, returning wrong positions/normals/axes for
+  any moved or rotated object (e.g. a rotated fuselage reported its bbox along -Z).
+  All manual placement transforms removed; `placement.rotation.angle_deg` now
+  actually reports degrees (was radians).
+- **`align_shapes` radian/degree bug**: `Face.getAngle()` returns radians but
+  `FreeCAD.Rotation(axis, angle)` expects degrees — touch/axis modes rotated by a
+  far-too-small angle. Fixed with `math.degrees()`.
+- **Expression binding**: in `cad()` create/edit `obj_properties`, string values starting with `=` are bound via the ExpressionEngine (`obj.setExpression`) instead of assigned literally — Spreadsheet-driven parametric design without new tools.
+- **Feature operations**: `cad()` gains `boolean`/`fillet`/`chamfer`/`loft`/`sweep`/`mirror`/`pattern` — parametric FreeCAD objects (transactional, rollback-able), with edge/face selectors ("all" / indices / names) fed by `get_topology`.
+- **Geometry sensing**: `measure_geometry` (volume/area/bbox/center of mass/validity), `get_topology` (paginated faces/edges/vertices with semantic info for selection), `check_interference` (distance + common volume) — quantitative feedback after each modeling step.
+- **Spatial positioning** (the hardest problem in AI-driven CAD assembly):
+  - `cad(operation="move")` — relative translate/rotate on top of current Placement
+    (solves ~80% of positioning needs without manual coordinate math).
+  - `get_positioning_info` — global-coordinate spatial data for a specific face/edge/vertex
+    (center, normal, axis, radius, start/end points — all transformed by the object's Placement).
+  - `align_shapes` — move an object so one of its elements aligns with a target element on
+    another object. Modes: `"touch"` (face-to-face contact, normals opposed), `"center"`
+    (center-to-center), `"axis"` (cylindrical axis alignment). Optional `offset` for gap/overlap.
+- **Global coordinates everywhere**: `measure_geometry` now returns bounding box and center of
+  mass in global coordinates (applies Placement transform). `get_topology` face/edge/vertex
+  entries now include global-coordinate data: face `radius`/`axis` (cylindrical/conical/spherical),
+  edge `start`/`end` vertices and `radius`/`axis` (circular), vertex global position.
+- **Guidance**: mutation responses include lightweight `display_text` suggestions and
+  risk warnings (state drift after rollback, non-atomic steps, document closed).
+
+### Bug fixes
+
+- **Consistent edge schema**: closed (full-circle) edges in `get_topology` /
+  `get_positioning_info` now always carry an `end` point (equal to `start`) —
+  previously the key was absent for single-vertex edges, breaking callers that
+  iterate `start`/`end` uniformly.
+- **`align_shapes` silent offset**: `offset` is only meaningful in `touch` mode;
+  passing a non-zero offset in `center`/`axis` mode now returns a `warning`
+  field instead of silently ignoring it.
+- **Dead code**: removed an always-overwritten placement computation in
+  `_build_move` (`feature_ops.py`).
+- **Null shape serialization**: `serialize_shape` now checks `shape.isNull()` in
+  addition to `shape is None`, preventing `AttributeError` on objects whose Shape
+  property exists but is a null OCCT handle.
+- **Mirror feature type**: `_build_mirror` now tries `Part::Mirroring` first and
+  falls back to `Part::Mirror` only on type-not-found errors, with a clear
+  `ValueError` if neither exists — no more silent `TypeError` on FreeCAD builds
+  that only ship one of the two.
+- **Thread safety**: `_now()` in `session_state.py` wrapped with a `threading.Lock`
+  to prevent rare timestamp collisions in concurrent session operations.
+- **Object name normalization**: `_normalize_object_names()` handles both string
+  and dict elements from different RPC code paths, fixing `objects_after`
+  fingerprint mismatches in session steps.
+- **Interference threshold**: `check_interference` common-volume threshold raised
+  from `1e-7` to `1e-4` mm³ to avoid false positives from floating-point noise.
+- **Face normals**: `get_topology` now computes normals for ALL face types (not
+  just `Plane`), using `face.normalAt()` at the face center.
+
+### Improvements
+
+- **Screenshot policy**: screenshots are opt-in per call (`with_screenshot`).
+  Precedence: `--only-text-feedback` (hard off) > per-call `with_screenshot` >
+  `--with-screenshots` (default-on). Screenshots are capped at 768px on the long edge
+  by default to save tokens.
+- **Inline screenshots**: `execute_code` and `create_document` now capture
+  screenshots in the same GUI dispatch (single RPC round trip) instead of a
+  separate `get_active_screenshot` call, halving latency for screenshot-enabled
+  workflows.
+- **Stability**: read-only RPCs (`get_objects`, `get_object`, `list_documents`) now
+  dispatch onto the FreeCAD GUI thread; the XML-RPC client retries once on
+  recoverable connection errors.
+- **Merged RPC**: mutations and their optional screenshot are fetched in a single
+  XML-RPC round trip; mutation results include an `objects` fingerprint (sorted
+  object names) used for drift detection.
+- **Batch single-recompute**: `cad(operation="batch", ...)` now skips per-object
+  `doc.recompute()` and performs a single recompute after all ops, significantly
+  faster for large batches.
+- **Boolean multi-tool**: `cad(operation="boolean", tool=["Obj1","Obj2",...])`
+  now accepts a list of tool objects — they are fused into a temporary compound
+  before the boolean operation, enabling multi-body cuts/fuses in one step.
+- **ViewObject serialization**: extended with `DisplayMode`, `LineColor`,
+  `PointSize`, `LineWidth`, and `DrawStyle` properties for richer visual feedback.
+- **Compatibility**: the new MCP server falls back gracefully against older addons
+  (single-shot screenshot RPC, optional params); older clients keep working against
+  the new addon.
+  - Tests: pytest suite (119 tests) covering responses, operations, reconnect, session
+  state, pattern store, guidance, cad() dispatch, name normalization, spatial
+  positioning (move, get_positioning_info, align_shapes), and global-coordinate
+  topology queries.

cadpilot-0.4.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Shirokuma (k tanaka)
+Copyright (c) 2026 LBurny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.