TianshangCAD

A modern CAD CLI + MCP Server system. 2D/3D drawing, editing, measurement, validation and JSON-driven workflows are available both from the command line and as standardized tools callable by any MCP client (AI agent).

Status: v0.13.0 — plugin SDK + gltf/cam example plugins; 20 core aggregate tools (+ 2 plugin tools). 1065 tests passing, ~85% coverage (measured with optional extras installed), ruff and mypy clean.

中文文档: readme/README.zh-CN.md

Changelog · Migration guide v0.6.0 → v0.9.0

Features

• CAD CLI — file, draw, edit, view, measure, layer, batch command groups with short aliases (l = draw line, c = draw circle, ...)

• MCP Server — 20 core JSON-RPC aggregate tools (each with an action discriminator) over stdio, streamable HTTP or WebSocket (collaboration), callable from Claude, Cursor and other MCP clients

• Plugin ecosystem — plugin SDK (manifest + permissions + lifecycle + entry-point discovery) with two official plugins: plugin-gltf (glTF 2.0 import/export) and plugin-cam (2.5-axis toolpaths → G-code), exposing cad_gltf / cad_cam

• 3D views — JSON-defined View3DDefinition with spherical camera pose, named views (iso / top / front / side / back / bottom), perspective / orthographic projection, plane sections (XY / YZ / XZ), exploded views and orbit GIF animation; incremental WebGL delta sync for browser clients

• Batch automation — schedule one-off / cron / dependency-chained jobs, sandboxed Python / SCR / batch script execution, webhook notifications, SQLite persistence and reusable Jinja2 command templates

• Geometry validation — self-intersection, degenerate-face and non-manifold-edge checks with structured type / location / fix_suggestion diagnostics; box-box interference volumes; topology metrics

• Rendering — 2D orthographic PNG (top / front / side, DPI 72–300), shaded 3D preview and Three.js WebGL export with a bundled browser viewer

• Versioning — full document snapshots with deepdiff-based save / list / diff / restore

• Natural language — cad_nlp maps English / Chinese requests to tool calls with ambiguity handling

• JSON-driven — scenes and geometry defined and validated with Pydantic schemas; full import/export round-trip

• Pluggable kernel — analytic (default, no native deps) / OCC (cadquery) / FreeCAD

• File IO — JSON, DXF, STL (STEP via the OCC backend)

• Production hardening — Docker image with healthcheck, Prometheus metrics (/metrics), API-key authentication (401/403), sliding-window rate limiting (429) and a /health endpoint

• Quality gates — mypy strict typing, ruff linting, pytest with a 80% coverage floor; GitHub Actions CI runs lint + tests on every push. The reported ~87% coverage assumes the optional extras (boolean, solver, occ, collab, sim) are installed; the base pip install -e . suite measures lower.

Related MCP server: build123d-mcp

Install

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -e ".[dev]"

The [sim] extra (pip install -e '.[sim]') provides FEA and kinematics. CalculiX FEA requires the ccx solver binary installed separately; install it from calculix.de and ensure ccx is in PATH.

Self-contained Debian package (Linux amd64, bundles all runtime wheels — no network access needed at install time):

wget <release>/tianshangcad_<version>_amd64.deb
sudo dpkg -i tianshangcad_<version>_amd64.deb

Optional OCC kernel:

pip install -e ".[occ]"

CLI Usage

tianshangcad --version
tianshangcad file new design.json --unit mm
tianshangcad draw line 0,0 100,0
tianshangcad draw circle 50,50 --radius 25
tianshangcad draw box 0,0,0 --dimensions 100,50,30
tianshangcad edit move line_1 --dx 50
tianshangcad view zoom --extents
tianshangcad measure distance 0,0 100,100

Short aliases are expanded automatically: tianshangcad l 0,0 100,0 equals tianshangcad draw line 0,0 100,0. tianshangcad --version prints the current version (e.g. tianshangcad 0.12.0).

Command groups

MCP Server

Run the server and connect any MCP client to it.

stdio (local agents)

python -m tianshangcad --transport stdio

Streamable HTTP

python -m tianshangcad --transport http --host 127.0.0.1 --port 8081

The server then serves MCP at http://127.0.0.1:8081/mcp, exposes a health check at /health and Prometheus metrics at /metrics.

When an API key is configured (via the TIANSHANGCAD_API_KEYS env var, comma-separated), HTTP requests must send it as x-api-key or Authorization: Bearer <key>: missing keys get 401, invalid keys get 403. Requests are also subject to a sliding-window rate limit (default 100 requests / 60 s, configurable via TIANSHANGCAD_RATE_LIMIT_MAX and TIANSHANGCAD_RATE_LIMIT_WINDOW); exceeding it returns 429. /health and /metrics are always public. stdio mode is unaffected.

Tool Search (progressive discovery)

tools/list accepts an optional query string and returns only the tools whose name or description matches, so clients can progressively discover the right tool before calling it:

tools/list  {"query": "measure"}   -> [cad_measure, cad_object, cad_status, cad_validate]  (cad_measure first)
tools/list  {"query": "layer"}     -> [cad_layer, cad_status]  (cad_layer first)
tools/list  {}                     -> all 22 tools (20 core + cad_gltf + cad_cam)

Name matches rank highest, then description matches; multi-word queries require every token to match; stopword-only queries match nothing.

Tools (20 core aggregate + 2 plugin)

Validation, rendering, 3D views & NLP

Validate geometry with structured diagnostics, render orthographic views, snapshot and restore document versions, drive tools from natural language, and create named 3D views with camera, section, explode and animation:

# Render a 300 DPI top view PNG
tianshangcad render view --view top --dpi 300 --output preview.png
tianshangcad render 3d --output preview3d.png
tianshangcad render webgl --output viewer_data.json --viewer examples/threejs_viewer.html

# 3D views
tianshangcad render view3d iso --output iso.png
tianshangcad render section XY --offset 0 --output section.png
tianshangcad render explode --scale 1.5 --output explode.png
tianshangcad render gif --frames 48 --output orbit.gif
tianshangcad render views

# NLP examples (via the MCP tool cad_nlp)
"new file design.dwg"        -> cad_file  {file: {action: create, filename: design.dwg}}
"draw a line from 0,0 to 10,10" -> cad_object  {object: {action: create, type: line, params: {...}}}
"render the side view"       -> cad_render  {render: {mode: ortho, view: side}}
"save a version"             -> cad_version  {version: {action: save}}

cad_nlp (action=chat) adds multi-turn dialogue with anaphora resolution: each session_id remembers the last created object so later turns can refer to it with pronouns or descriptions. Create intents are executed against the current document, so "it" / "它" resolves to the real object id.

# Turn 1: draw a circle (creates the object, records it in the session)
"draw a circle at 5,5 radius 3"   -> cad_object, object_id tracked
# Turn 2: move the referenced circle (same session_id)
"move it to 10,10"                -> cad_object {object: {action: update, object_id, params}}
"move the circle I just drew to 3,3" -> same, explicit anaphora
"把它移到 4,4"                     -> same, Chinese pronoun

Version diffing uses deepdiff and reports changed fields, added/removed items and the raw result. The WebGL export writes Three.js BufferGeometry JSON consumable by examples/threejs_viewer.html. View definitions (camera pose, projection, section/explode parameters) are persisted with the document and are also exposed as MCP tools (cad_view for view definitions, cad_render for section / explode / animation / webgl modes).

Real-time collaboration

Phase 9 collaboration builds on the LWW-Map CRDT: a session holds the shared document state as keyed registers (geometry / layers / variables / constraints / assembly), with 4-role × 4-scope RBAC (viewer / editor / admin / owner over document / scene / assembly / settings). Sessions support presence, annotations, document branches (fork / edit / merge with explicit conflict resolution) and a transport-agnostic sync primitive:

# Optional dependency for the WebSocket hub
pip install -e ".[collab]"

tianshangcad collab create --name review        # seed a session over the current doc
tianshangcad collab list
tianshangcad collab annotate <session_id> "check the hole"
tianshangcad collab perm <session_id> bob --role editor

# WebSocket transport (default port 8082)
python -m tianshangcad --transport ws --port 8082

MCP clients use cad_collab_session, cad_collab_branch, cad_collab_annotation, cad_collab_presence, cad_collab_history, cad_collab_resolve, cad_collab_permission and cad_collab_sync. WebSocket clients speak a small JSON envelope (subscribe / op / sync / ping) that maps onto the sync tool. A multi-client hub fans an applied op out as a deltas broadcast to every subscriber of the same session (excluding the origin sender, which already received its live response).

Batch & automation

Schedule jobs with a standard 5-field cron expression, dependency chains and webhook notifications; run scripts through a sandboxed engine; persist job state to SQLite:

# One-off job
tianshangcad batch schedule commands.json --name report

# Cron job (daily at 02:00) using a built-in template
tianshangcad batch schedule commands.json --cron "0 2 * * *"

# Run a sandboxed Python script
tianshangcad batch run-script script.py --type python --timeout 30

# Inspect results
tianshangcad batch list
tianshangcad batch status <job_id>
tianshangcad batch logs --source batch --job-id <job_id>

Scripts run in an isolated subprocess (python -I) with an import whitelist (os, subprocess, socket, ... are blocked), a runtime sys.modules guard and a hard timeout.

Plugins

Plugins extend the server with new MCP tools and CLI commands. The SDK (core/plugins/) provides a manifest + permission declaration, a load → initialize → run → shutdown lifecycle and four extension points (tools / commands / kernel / solver). Plugins are discovered from the tianshangcad.plugins entry-point group of installed distributions.

tianshangcad plugin list                    # discover + list
tianshangcad plugin enable <name>           # enable / disable
tianshangcad plugin manifest <name>         # inspect the manifest

Two official plugins ship with the package:

• plugin-gltf — glTF 2.0 import/export (PBR materials); cad_gltf, gltf CLI.

• plugin-cam — 2.5-axis contour + drilling toolpaths to G-code; cad_cam, cam CLI.

Security: plugins run in-process, in the same trust domain as the server, and are not sandboxed. The MCP cad_plugin install action only loads plugins from installed distributions' entry-points (it never imports an arbitrary module:attr path); only install plugins from trusted sources. Process-level sandboxing is a future hardening step.

Docker

A multi-stage image (< 500 MB, python:3.12-slim) is provided in docker/ for headless deployment:

docker compose -f docker/docker-compose.yml up -d

The container runs the MCP server over streamable HTTP on port 8081 with a /health healthcheck, and mounts data/ + config/ volumes. Environment overrides: TIANSHANGCAD_RUNTIME, TIANSHANGCAD_HEADLESS, TIANSHANGCAD_TEMP_DIR, TIANSHANGCAD_API_KEYS, TIANSHANGCAD_LOG_LEVEL, TIANSHANGCAD_RATE_LIMIT_MAX, TIANSHANGCAD_RATE_LIMIT_WINDOW.

Example MCP client configuration (Claude Desktop ~/.config/claude/mcp.json):

{
  "mcpServers": {
    "cad-server": {
      "command": "python",
      "args": ["-m", "tianshangcad", "--transport", "stdio"],
      "autoApprove": [
        "cad_json",
        "cad_measure",
        "cad_render",
        "cad_validate"
      ]
    }
  }
}

Development

bash scripts/setup_dev.sh   # venv + editable install + stubs
bash scripts/run_tests.sh   # ruff + mypy + pytest (coverage gate >= 80%)
bash scripts/build_docs.sh

Or run each gate directly:

ruff check .   # lint
mypy src       # type check
pytest         # tests (coverage gate >= 80%)

Benchmark harness (CADGenBench)

scripts/cadgenbench_harness.py is an offline demo harness that drives the real MCP server over stdio to build a small set of 3D parts, export them as STEP, and run a local validity check (watertight manifold) mirroring CADGenBench's scoring gate -- no external API or HuggingFace token needed:

python scripts/cadgenbench_harness.py            # analytic AP203 exporter
python scripts/cadgenbench_harness.py --occ      # OCCT kernel path
# Results: dist/cadgenbench/run_summary.json

To turn this into a real CADGenBench submission, read a sample's description.yaml, let an LLM choose the tool calls with this server as the backend, and upload the resulting output.step candidates to the leaderboard Space.

Project Layout

src/tianshangcad/
|-- cli/            # typer CLI: commands + alias expansion
|-- mcp/            # MCP server, transports, security and tool registry
|   |-- server.py       # MCPServer wiring (20 core tools + plugin discovery)
|   |-- transport.py    # stdio / streamable HTTP (+ auth, rate limiting)
|   |-- security.py     # tool permission whitelist
|   |-- auth.py         # API-key authentication
|   |-- rate_limit.py   # sliding-window rate limiter
|   `-- tools/          # crud, json_ops, status, validate, batch, boolean,
|                       # file_io, variables, render, versioning, nlp, view3d,
|                       # features, simulation
|-- core/           # document, entity, layer, kernel, session, history,
|                   # variables, scheduler, script_runner, batch_templates,
|                   # validation, versioning, view_manager, features, simulation,
|                   # assembly, drawing, constraint, plugins (SDK + manager)
|-- plugins/        # official example plugins: gltf (glTF 2.0), cam (2.5-axis)
|-- io/             # JSON / DXF / STL importers and exporters
|-- schemas/        # Pydantic geometry, scene and view3d schemas
|-- render/         # 2D / 3D PNG rendering, WebGL export, section, explode,
|                   # animation
`-- utils/          # logger, config, errors, validators, units, metrics
examples/
`-- threejs_viewer.html  # browser viewer for WebGL exports
docker/
|-- Dockerfile          # multi-stage image (python:3.12-slim)
|-- docker-compose.yml  # service definition with healthcheck
`-- entrypoint.sh
tests/
|-- unit/           # CLI, core, IO, MCP tool unit tests
`-- integration/    # MCP e2e, batch, JSON workflow and performance tests

Documentation

• readme/README.zh-CN.md — Chinese README

Continuous Integration

.github/workflows/ci.yml runs ruff + mypy on every push / PR, pytest with the 80% coverage gate on Python 3.12, and a separate stress job for the concurrency / soak suite. Pushing a v* tag triggers .github/workflows/release.yml, which builds the Windows executables (tianshangcad.exe, tianshangcad-server.exe via PyInstaller) and the self-contained Debian package (scripts/build_deb.py, bundles runtime wheels for Linux amd64) and publishes them to a GitHub Release.

License

Apache License 2.0 — see LICENSE.

Community guidelines: Code of Conduct · Security: SECURITY.md · Contributing via pull requests is welcome.

Third-party runtime dependencies are all permissive-licensed (MIT / BSD / Apache-2.0 / ISC / PSF, plus MPL-2.0 for certifi); the full inventory is in THIRD_PARTY_LICENSES.md.

Optional backends: cadquery (Apache-2.0) is compatible. The optional FreeCAD / OpenCASCADE backends are LGPL-2.1 and are not bundled; if you enable them you must comply with the LGPL (retain notices, keep the library re-linkable). The default AnalyticKernel is self-authored and fully Apache-2.0.