ReverseCAD MCP
by grizlizora
README.md
<div align="center">
# ⚙️ ReverseCAD: Industrial-Grade STL ➔ STEP AP242 + CAD Features Engine
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[]()
[]()
[]()
[]()
[]()
[]()
[](https://modelcontextprotocol.io)
[](LICENSE)
[](COMMERCIAL.md)
**High-performance, 100% pure TypeScript reverse-engineering engine and MCP server that deterministically transforms raw `.stl` polygon meshes into clean, production-grade solid B-Rep models (STEP AP242 / ISO 10303-21) and dense engineering CAD Features JSON in seconds.**
[🚀 Quick Start](#-quick-start--cli-usage) • [✨ Key Capabilities](#-key-engineering-capabilities) • [📁 Output Artifacts](#-output-artifacts) • [🏗️ Architecture](docs/ARCHITECTURE.md) • [🤖 MCP Server](#-model-context-protocol-mcp-server) • [🧪 Testing](#-test-suite--quality-verification) • [🏢 Commercial Licensing](COMMERCIAL.md) • [👨💻 Author](#-author--collaboration)
</div>
---
## ✨ Key Engineering Capabilities
| Engineering Feature | Technology & Mathematical Method | Representation in STEP & JSON |
|---|---|---|
| 🧊 **Watertight Solid B-Rep Guarantee** | Euler-Poincaré invariant ($\chi = 2 - 2g$), symmetric half-edge pairing, 64-bit quantized topological vertex pool. | **STEP:** `MANIFOLD_SOLID_BREP` with a single closed `CLOSED_SHELL`. Strictly 0 open edges, 0 non-manifold edges. |
| ⚖️ **Exact Gauss-Mirtich Mass & 3D Inertia** | Analytical divergence theorem integration with exact `/ 120.0` divisor. Volume, surface area, center of mass, and full $3 \times 3$ inertia tensor. | **JSON:** `volumeMm3`, `centerOfMass`, `inertiaTensor` ($I_{xx}, I_{yy}, I_{zz}, I_{xy}, I_{yz}, I_{zx}$ with $I_{xy}=0$ on symmetric bodies). |
| 🧹 **Boundary Unification (No Extra Lines)** | Coplanar half-edge cancellation, Jordan cycle extraction, RDP collinear vertex reduction ($10^{-5}$ mm). | **STEP:** Clean unified `ADVANCED_FACE` with single outer bound and inner loops. Zero internal wireframe lines. |
| 🔄 **2D Gauss Area Angle Sweep Triangulator** | Monotonic cyclic angle sweep (`loop-band-triangulator.ts`) determining CW/CCW orientation via 2D Shoelace area in transverse normal plane. | Guarantees 100% topological band closure between top and bottom loops without butterfly self-intersections. |
| 📐 **Seamless C0 Profile Fitting** | Algebraic least-squares circle fitting (Kåsa/Pratt), seamless tangent line-to-arc transitions without edge duplication, $2\pi$ circle closure. | **STEP:** Precise `CIRCLE` and `LINE` geometry with C0 profile boundary snapping (`profile-loop-snapper.ts`). |
| 🔩 **ISO Metric Threads (M2–M24)** | Catalog matching, coaxial cylinder RANSAC, pitch $P$ and tap drill diameter extraction. Mode selectable (`auto`, `physical`, `semantic`). | **STEP:** Optional cosmetic helical geometry or analytical core.<br />**JSON:** `spec: "M6x1", pitchMm: 1.0, isInternal: true`. |
| 🛡️ **Scale-Invariant & Datum Shielding** | Dynamic scale normalization $D_{\text{bbox}}$, Tier E protection for micro-chamfers, strict datum plane locks (`datumA && datumB`). | Prevents decimation erosion on 45° entrance chamfers and critical reference datums. |
| 🕳️ **Internal Cavities & Channels** | Signed volume divergence theorem integration per closed manifold shell ($V < 0$). | Internal cooling lines and cavities remain 100% hollow during slicing and CAD import. |
| ⚡ **DWRR Concurrency & Zero-GC Profiling** | Deficit Weighted Round-Robin fair-share scheduling, dynamic CPU core/RAM scaling, Structure-of-Arrays (SoA) binary heaps. | Eliminates head-of-line blocking on 16-core systems. Heap delta: 0.00 MB during hot loops. |
| 🔬 **RSVS 5-Gate Reality Simulation** | Strict verification: Hausdorff $H_{99} \le 0.05$ mm, $H_{\max}$ via $O(N)$ QuickSelect, RMSE, mass drift, native B-Rep topological validation. | Pre-manufacturing geometric sign-off before sending code to CNC mills or 3D printers. |
---
## 📁 Output Artifacts
Running ReverseCAD produces up to 5 synchronized manufacturing artifacts plus a streaming audit manifest:
```
output_directory/
├── 🧊 [1] Model.step <- 3D CAD Solid B-Rep (ISO 10303-21 AP242 / AP214)
├── ⚡ [2] Model.cad_features.summary.json <- High-density AI JSON (<1200 tokens)
├── 🔬 [3] Model.cad_features.topology.json <- Deep B-Rep topological geometry dump
├── 📊 [4] Model.verification_report.json <- RSVS 5-Gate quality & accuracy report
├── 🌈 [5] Model.heatmap.glb <- 3D interactive color deviation heatmap
└── 📜 conversion_manifest.ndjson <- Real-time streaming pipeline audit log
```
---
## 🚀 Quick Start & CLI Usage
### 1. Requirements & Installation
* **Node.js** `>= 20.0.0` or **Bun** `>= 1.1.0`
* **macOS** (Apple Silicon ARM64 / Intel x64), **Linux** (x86_64 / aarch64), or **Windows**
```bash
# Clone the repository
git clone https://github.com/grizlizora/reverse-cad.git
cd reverse-cad
# Install dependencies and compile
npm install
npm run build
# Make the driver executable
chmod +x ./convert.sh
```
### 2. Basic Conversions
```bash
# Convert STL to production solid STEP AP242 with default outputs
./convert.sh model.stl
# Or using Bun directly
bun run src/cli/index.ts model.stl
```
### 3. Selective Artifact Emission (`--emit`)
Control exactly which files are generated to minimize I/O and optimize throughput:
```bash
# 1. Solid-Only: Generate ONLY the 3D STEP solid (fastest, zero JSON)
./convert.sh part.stl --emit step # (or: ./convert.sh part.stl --step-only)
# 2. AI Package: STEP solid + compact AI engineering summary JSON
./convert.sh part.stl --emit step,summary
# 3. Full Engineering Audit: All 5 artifacts including GLB 3D deviation heatmap
./convert.sh part.stl --emit all
# 4. JSON-Only: Skip STEP generation entirely, extract CAD features in milliseconds
./convert.sh part.stl --json-only
```
### 4. Advanced CLI Options
| Flag | Values | Description |
|---|---|---|
| `-t, --threads` | `<N>` | Number of parallel worker threads (`0` = auto CPU core count minus 1). |
| `-q, --quality` | `high` \| `fast` | Processing preset: `high` (full RANSAC + QEM) or `fast` (quick decimation). |
| `-o, --out-dir` | `<path>` | Custom destination directory for generated artifacts (default: `./output`). |
| `-i, --interactive` | — | Launch interactive terminal wizard to select outputs and options. |
| `-y, --yes, --default` | — | Non-interactive mode: accept defaults without prompting (ideal for CI/CD). |
| `--emit` | `formats` | Comma-separated outputs: `step`, `summary`, `topology`, `report`, `heatmap`, `all`, `minimal`. |
| `--representation` | `auto` \| `brep` \| `tessellated` | STEP geometry mode: analytical `brep`, faceted `tessellated`, or adaptive `auto`. |
| `--thread-mode` | `auto` \| `physical` \| `semantic` | Metric thread mode: physical modeled threads, semantic annotation, or auto. |
| `-m, --material` | `<preset>` | Assign material density: `steel`, `aluminum`, `pla`, `petg`, `abs`, `glass`. |
| `--heatmap` | `failed-only` \| `always` \| `none` | Control 3D GLB deviation heatmap generation. |
| `--align-viewer` | — | Auto-align 6 canonical views (Top/Bottom/Front/Back) for CAD viewers (default). |
| `--keep-orientation` | — | Preserve original coordinates without CAD axis reorientation. |
| `--verify` / `--no-verify` | — | Enable or disable the RSVS 5-Gate reality simulation verification suite. |
| `--mcp` | — | Start as a Stdio MCP Server for AI coding assistants. |
| `--test` | — | Run embedded RSVS regression test suite and mutation tests. |
| `-v, --verbose` | — | Enable verbose debugging logs. |
---
## 🤖 Model Context Protocol (MCP) Server
ReverseCAD implements the official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) specification (Stdio transport). AI assistants (*Cursor, Claude Desktop, Antigravity*) can analyze, query, and convert 3D CAD geometries directly within the chat workflow.
### Configuration
Add ReverseCAD to your AI assistant's config file (e.g., `claude_desktop_config.json` or `.gemini/antigravity/mcp/`):
```json
{
"mcpServers": {
"reverse-cad": {
"command": "node",
"args": ["/absolute/path/to/reverse-cad/dist/mcp/mcp-server.js"]
}
}
}
```
*Or with Bun:*
```json
{
"mcpServers": {
"reverse-cad": {
"command": "bun",
"args": ["/absolute/path/to/reverse-cad/src/mcp/mcp-server.ts"]
}
}
}
```
### Available MCP Tools
| MCP Tool Name | Input Parameters | Output & Purpose |
|---|---|---|
| `cad_analyze_stl` | `filePath`, `threshold?` | Analyzes mesh quality, triangle count, watertightness, bounding box, volume, and surface area. |
| `cad_detect_threads` | `filePath` | Detects ISO metric threads (M2–M24), nominal diameters, pitches, and tap drill specifications. |
| `cad_verify_rsvs` | `filePath`, `outDir?` | Runs RSVS 5-Gate reality simulation, returning Hausdorff $H_{99}$, RMSE, and Euler characteristic. |
| `cad_convert_to_step` | `filePath`, `outDir?`, `options?` | Converts STL to solid STEP AP242 and emits CAD features JSON artifacts. |
---
## 🏗️ Clean Code & Strict Modularity Architecture
ReverseCAD enforces an uncompromising architectural policy:
* **Strict Line Limit (< 190 lines):** Every single module across all **355+ TypeScript files** in `src/` is strictly under 190 lines of code. There are zero "God-objects".
* **Single Responsibility Principle (SRP):** Complex algorithms (e.g. QEM decimation, RANSAC segmentation, B-Rep synthesis) are decoupled into focused, testable micro-modules.
* **Acyclic Dependency Graph (DAG):** Circular dependencies are strictly eliminated through dependency inversion and dedicated coordinator facades.
* **Zero-Allocation Hot Paths:** FPU-heavy geometric loops operate entirely on flat `TypedArray` buffers (`Float32Array`, `Float64Array`, `Int32Array`, `Uint8Array`) and Structure-of-Arrays (SoA) binary heaps.
Detailed architectural diagrams, mathematical formulations, and concurrency designs are available in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
---
## 🧪 Test Suite & Quality Verification
ReverseCAD features an extensive, multi-tier automated test suite verifying mathematical precision, topological closure, concurrency, and real-world CAD benchmarks.
```bash
# Run the complete test suite in Bun
bun run src/test/run-tests.ts
# Or run the compiled test suite in Node.js
npm test
```
### Embedded Test Suites:
1. **Wave 8–10 Math & Concurrency Verification:**
- Exact Gauss-Mirtich inertia tensor ($120.0$ divisor, $I_{xy} = 0.0$ on unit cube).
- 2D Gauss polygon area loop winding direction (Shoelace formula).
- Seamless line-to-arc profile continuity without edge duplication.
- Strict CLI enum argument validation.
- Decoupled spatial grid and deterministic PRNG sampling.
2. **Boundary Unifier & Feature Protection (`test-boundary-unifier.ts`):**
- 8/8 tests verifying coplanar face unification, collinear vertex reduction, and hole loop extraction.
3. **Crease Preservation (`test-crease-preservation.ts`):**
- In-memory decimation test preserving 90° sharp edges and 45° chamfers with $H_{\max} = 0.0000$ mm.
4. **Watertight Solid B-Rep Hole (`test-watertight-solid-hole.ts`):**
- Verifies 100% closed solid cube with cylindrical hole (Faces = 18, OpenEdges = 0, NonManifold = 0).
5. **RSVS Reality Simulation Benchmarks (Gates G0–G4):**
- `benchmark_prismatic_m6.stl` (M6 metric thread detection).
- `benchmark_internal_labyrinth.stl` (Zero-voxel internal cavity detection).
- `benchmark_pip_hinge.stl` (Print-in-Place clearance detection).
- `benchmark_organic_saddle.stl` (Hyperbolic paraboloid freeform reconstruction).
- Combinatorial Matrix Scanner & Zero-GC Memory Leak Audit.
---
## 📄 Licensing & Commercial Options
ReverseCAD uses a transparent **Dual-Licensing Model**:
* 🟢 **Community Edition ([PolyForm Noncommercial 1.0.0](LICENSE)):**
100% Free for individuals, students, makers, hobbyists, and non-commercial educational/academic research.
* 🏢 **Commercial & Enterprise Edition ($10,000 USD / year):**
Required for all for-profit enterprises, manufacturing bureaus, 3D print farms, CNC machine shops, closed-source SaaS products, and commercial applications. Includes legal indemnification, enterprise support, and SLA. See [COMMERCIAL.md](COMMERCIAL.md).
---
## 👨💻 Author & Collaboration
Designed and engineered with passion by **Roman ([@grizlizora](https://t.me/grizlizora))** — Specialist in High-Performance Computational Geometry, B-Rep CAD Kernels, Multithreaded Systems, and AI Agent Integrations.
* 💬 **Telegram:** [@grizlizora](https://t.me/grizlizora)
* 🐙 **GitHub:** [@grizlizora](https://github.com/grizlizora)
* 📧 **Email:** [roma.vaida66@gmail.com](mailto:roma.vaida66@gmail.com)
* 💼 **LinkedIn:** [Roman Vaida](https://www.linkedin.com/in/roman-vaida-4873a6287)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues