# CADCLAW

CADCLAW builds and verifies STEP-based CAD assemblies. It is a Python package
(PyPI: `cadclaw`) with two halves.

Assemble: a declarative assembly spec places authored STEP parts by connector
frames and datum chains rather than hand-typed coordinates, compiles the
assembly with CadQuery, and emits a design inventory, a model-derived BOM,
review-view renders, and step-by-step build sequences.

Verify: a chain of geometric, structural, tolerance, and text-audit gates over
the result, reporting findings with severity, evidence, and a confidence budget
rather than just pass/fail. "Pytest for mechanical design", in spirit.

CADCLAW places parts authored in external CAD (Fusion, Rhino, SolidWorks). It
does not generate geometry: no parametric plates, bolt-circle constants, or
hole-drilling helpers. CADCLAW also ships an MCP server so MCP-compatible
assistants (Claude Desktop, Cursor, etc.) can drive both halves directly, and
can see the rendered review images at each assembly round.

This file is a high-density plain-text summary intended for LLM and
agent-driven retrieval. The canonical site is https://cadclaw.io.

## Identity

- Name: CADCLAW
- Publisher: Sunnyday Technologies (https://sunn3d.com)
- Authored and maintained by: Nick Sonnentag, Sunnyday Technologies
- Contact: info@sunn3d.com
- Repository: https://github.com/sunnyday-technologies/CADCLAW
- License: MIT
- PyPI: https://pypi.org/project/cadclaw/
- DOI: 10.5281/zenodo.19647390
- Current published version: 0.10.0 (PyPI checked 2026-08-11; canonical source: https://pypi.org/project/cadclaw/)
- Site: https://cadclaw.io
- Status: open source, actively maintained

## What CADCLAW does

### Assembly (the `cadclaw assemble` command group)

CADCLAW compiles a declarative assembly spec into a STEP assembly.

- Assembly spec (`cadclaw/assembly_spec.py`) — strict schema
  (`assembly_spec.v0.1`); unknown keys fail validation, outputs cannot
  overwrite `protected_paths`, incomplete work is declared `not_built_yet`.
- Assembly compiler (`cadclaw/assembly_compiler.py`) — resolves authored STEP
  sources and compiles with CadQuery. `resolve_relative_placements()` walks the
  datum chain in topological order and solves each constraint-placed transform,
  reporting cycles, missing refs, and missing frames as findings.
- Connector metadata (`cadclaw/connector_metadata.py`) — local coordinate
  frames per authored component: extrusion ends, mount faces, rail slots,
  wheel contacts, shaft axes, belt planes.
- Component manifest (`cadclaw/component_manifest.py`) — index of an authored
  STEP library with bbox signatures and metadata coverage.

Commands: `assemble validate-spec`, `assemble build`, `assemble check-round`,
`assemble inspect-component`, `assemble render-views`, `assemble
render-sequence`.

Placement is by constraint, not hand-typed coordinates. An instance declares
`place_relative_to` (ref / parent_frame / frame / axis / side / offset_mm /
lock) to seat its connector frame against a parent's frame. `lock: "frame"`
solves all three translation axes; `lock: "axis"` solves only the handoff axis
and keeps the instance transform for orientation and the two free axes.
Absolute transforms still work, so migration is incremental.

CADCLAW does NOT author geometry. It places parts the user drew in external
CAD. There are no parametric plate, bracket, mount, or hole-pattern generators,
and none are planned.

### Validation

CADCLAW validates STEP CAD assemblies and their BOMs through automated gates.
Configure once in `cadclaw.yaml`, run from the `cadclaw` console script.

Validation domains (each maps to a module under `cadclaw/`):

- Inventory (`cadclaw/inventory.py`) — label parts by bbox signature,
  count against expected, per-region (axis-aligned) constraints.
- Interference (`cadclaw/interference.py`) — pairwise solid-solid overlap
  via OCC `BRepAlgoAPI_Common`, reports overlap volume in mm^3.
- Adjacency (`cadclaw/adjacency.py`) — parts of type A must have a part
  of type B within N mm. Catches misplaced/scattered components.
- Dimensional (`cadclaw/dimensional.py`) — checks part dimensions against
  expected ranges; catches wrong thickness, swapped args, scaling errors.
- Orientation (`cadclaw/orientation.py`) — verifies expected face planes for
  labels that opt in through `cadclaw.yaml`.
- Floating (`cadclaw/floating.py`) — flags non-exempt parts isolated from
  configured structural labels beyond a max gap.
- Color/material (`cadclaw/color_check.py`) — compares STEP AP242 color
  metadata against expected label colors.
- Semantic PMI presence (`cadclaw/pmi.py`) — reports presence or absence for
  each declared AP242 semantic class: dimensions, geometric tolerances,
  and datums. Graphical PMI, material assignments, and process/general notes
  are excluded. This gate is unreleased on the development branch and is not
  part of the published 0.10.0 package.
- AP242 STEP round trip (`cadclaw/roundtrip.py`) — an opt-in actual OCCT XCAF
  import, AP242 export, and reimport that compares CADCLAW's deduplicated
  renderable-shape count, bounded geometry measures, declared interface gaps,
  and source-present supported semantic-PMI class counts. It does not inspect
  native CAD, verify translator
  identity, compare PMI values/associations, or establish standards conformance.
  Minimum-cost per-part matching has a hard 256-renderable-shape method limit;
  larger equal-count comparisons error before quadratic matrix allocation.
  This gate is unreleased and not part of the published 0.10.0 package.
- Structural (`cadclaw/kinematics.py`) — beam deflection (Euler-Bernoulli),
  motor torque budget, belt tension. Static load math; not motion-clearance
  or full-travel sweeps.
- Tolerance (`cadclaw/tolerance.py`) — worst-case, RSS, and Monte Carlo
  tolerance stacking with Cpk and per-dimension variance contribution.
- Parity (`cadclaw/parity.py`) — STEP-vs-STEP comparison; flags the
  Fusion visibility-toggle bug.
- BOM audit (`cadclaw/bom_audit.py`) — BOM JSON ↔ CAD assembly: qty,
  mfg_type, unit, required/forbidden text terms, CAD-side count drift.
- Disassembly (`cadclaw/disassembly.py`) — sequenced part removal,
  radial exploded views, animation frame export.
- Render (`cadclaw/render.py`) — STEP → PNG → animated GIF via
  offscreen VTK.

Honesty toolchain (text-side validation, also surfaced via the CLI):

- `cadclaw doctor` — environment diagnostic.
- `cadclaw publish-audit` (`cadclaw/publish_audit.py`) — scans the working
  tree for private data before commit.
- `cadclaw claim-audit` (`cadclaw/claim_audit.py`) — flags overclaims and
  untagged numeric assertions in README and BOM notes.

CADCLAW does NOT prove that a native CAD model has no hidden parts, that a
physical build matches CAD, that a vendor part is in stock, that a printed
part is strong enough for production, or that an AI-generated CAD change is
correct. Each report includes a confidence budget per gate.

## Install

```
pip install cadclaw
cadclaw doctor   # verify environment
```

Requirements: Python 3.10+ (Python 3.11 is the current CADCLAW development
runtime), CadQuery 2.7+ (provides OCC/STEP support), VTK 9.3+ for rendering,
pyyaml 6+, and pydantic 2.5+. No commercial CAD software is required for
CADCLAW's own checks. Cross-platform (Windows, macOS, Linux).

## CLI

```
cadclaw doctor
cadclaw assemble validate-spec  <spec.yaml>
cadclaw assemble build          <spec.yaml> --connector-metadata <meta.yaml>
cadclaw assemble check-round    <spec.yaml>   # build + check + render, one round
cadclaw assemble render-sequence <spec.yaml>  # step-by-step build STEPs + BOM CSV
cadclaw harness       --rules cadclaw.yaml
cadclaw bom-audit     --rules cadclaw.yaml
cadclaw publish-audit --rules cadclaw.yaml
cadclaw claim-audit   --rules cadclaw.yaml --report-format md -o report.md
cadclaw inspect       ...                 # diagnostic queries
```

Exit codes: 0 pass, 1 fail, 2 warn-only (no fails), 3 internal error.

## MCP server

The repository also publishes `cadclaw_mcp/` — a Model Context Protocol
server that exposes CADCLAW assembly, check, analysis, audit, and render tools.
The MCP server runs LOCALLY after `pip install cadclaw`; it is NOT a hosted
endpoint and does not control a native CAD application. It is also not a
security sandbox: path-taking tools can read declared STEP, spec, rules, BOM,
and metadata inputs, and assembly/render tools can write configured outputs,
using the local process account's filesystem permissions. Run it in a
least-privilege working copy, inspect tool arguments, and require human review
for write-producing operations.

MCP coverage is 24 tools spanning both halves.

Assembly (6): assemble_validate_spec, assemble_build, assemble_check_round,
assemble_inspect_component, assemble_render_views, assemble_render_sequence.

Validation and analysis (18): run_harness, check_inventory, check_interference,
check_adjacency, check_dimensions, check_region_inventory,
check_bom_against_cad, check_claims, check_publish_boundary,
compare_step_parity, compute_deflection, compute_motor_budget,
compute_belt_tension, tolerance_stack, disassembly_sequence,
export_exploded_view, load_assembly, doctor.

Visual review: the render-producing assembly tools return their PNGs as inline
MCP image content (toggle with `return_images`), so the calling model can see
the assembly it just built rather than only reading a report. The PNGs are
always written to disk as the human-auditable traceability artifact for each
round. Inline images are capped (MAX_INLINE_IMAGES) so a long sequence cannot
flood the client context; the report says how many were truncated.

Entry point: `python -m cadclaw_mcp` (see `cadclaw_mcp/server.py`).

## Companion projects

- M3-CRETE — experimental open-hardware motion reference and historical
  CADCLAW development target; not a validated production deployment.
  https://m3-crete.com · https://github.com/sunnyday-technologies/M3-CRETE
- CEMFORGE — early-stage materials-evidence and decision support, separate
  from CADCLAW's geometry checks. https://cemforge.ai
- Open3DCP — maintainer-authored draft record schema and documentation, not a
  supplied dataset or ratified standard. https://open3dcp.org

## Machine-readable surface

- Site root (HTML, with embedded SoftwareApplication JSON-LD):
  https://cadclaw.io/
- Sitemap: https://cadclaw.io/sitemap.xml
- This file: https://cadclaw.io/llms.txt
- Static discovery document (experimental and non-standard; read-only site resources,
  not a hosted MCP endpoint):
  https://cadclaw.io/.well-known/mcp-manifest.json
- robots.txt (explicit opt-in for ClaudeBot, GPTBot, Google-Extended,
  PerplexityBot): https://cadclaw.io/robots.txt
- README, source, issues: https://github.com/sunnyday-technologies/CADCLAW
- Package: https://pypi.org/project/cadclaw/

## Citation

```
Sonnentag, N. (2026). CADCLAW: Automated assembly and validation framework
for STEP-based CAD. Sunnyday Technologies.
https://github.com/sunnyday-technologies/CADCLAW
DOI: 10.5281/zenodo.19647390
```