Skip to main content
Glama

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).

TianshangCAD MCP server

MCP Score CI Python Version License Tests Coverage

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: root-ext-cad

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

Group

Commands

file

new, open, save, close, list, info, export, import

draw

line, circle, arc, rectangle, polygon, polyline, box, cylinder, sphere

edit

move, copy, rotate, scale, erase, list, undo, redo

view

zoom, pan, list

measure

distance, area, list

layer

create, list, set, on, off, delete

render

view, 3d, webgl, view3d, section, explode, gif, views, status

batch

schedule, run-script, list, status, cancel, templates, logs

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)

Group

Tools

Files

cad_file (action: create/open/save/close/delete/list/import/export)

Objects

cad_object (action: create/read/update/delete/copy/transform/list/boolean)

Layers

cad_layer (action: create/read/update/delete/list)

JSON

cad_json (action: load/parse/validate/save/import_geometry/export_geometry/import_scene/export_scene)

Measure

cad_measure (action: distance/area)

Validate

cad_validate (action: geometry/interference/topology/metrics)

Status

cad_status (target: check/file/object/layer/health/logs_get/logs_clear)

Render

cad_render (mode: ortho/view_3d/section/explode/animation/webgl)

3D Views

cad_view (action: create/read/list/update/delete)

NLP

cad_nlp (action: command/chat)

Version

cad_version (action: save/list/diff/restore)

Variables

cad_variable (action: set/list)

Batch

cad_batch (action: execute/schedule/status/cancel/list/templates/run_script)

Constraints

cad_constraint (action: add/remove/list/solve)

Assembly

cad_assembly (action: create/add_part/add_subasm/add_mate/remove_part/solve/bom/explode)

Drawing

cad_drawing (action: create/add_view/add_section/add_dimension/add_tolerance/delete/export)

Features

cad_feature (action: sweep/loft/fillet/chamfer/pattern_linear/pattern_circular/pattern_mirror)

Simulation

cad_sim (action: mesh/setup/run/result/list/delete)

Collaboration

cad_collab (tool: session/branch/annotation/presence/history/resolve/permission/sync)

Plugins

cad_plugin (action: install/uninstall/list/enable/disable/manifest)

glTF (plugin)

cad_gltf (action: export/import/preview)

CAM (plugin)

cad_cam (action: toolpath/simulate/export_gcode)

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.

Available Tools

22 tools
cad_assemblyA
Destructive

Create, edit, solve or analyze an assembly.

聚合装配操作。按 ``action`` 派发:create / add_part / add_subasm /
add_mate / remove_part / solve / bom / explode。
- ``create``: initialize the document's assembly container.
- ``add_part`` / ``add_subasm``: build the tree; parts may reference a
  document ``entity_id`` and nest under a ``parent_id``.
- ``add_mate``: constrain two nodes (coincident / concentric / parallel /
  perpendicular / distance / angle).
- ``solve``: apply mates in order and return every node's world transform.
- ``bom``: flattened bill of materials (``format`` json or csv).
- ``explode``: radial offsets by tree depth (``direction`` x/y/z).

When not to use: ``cad_assembly`` composes *parts*, not geometry. Create
part geometry first with ``cad_object`` (create), then add it to the
assembly. For drawings of an assembly use ``cad_drawing``.

Inputs: assembly (required). Returns: Output of the aggregate assembly tool.

cad_batchA
Destructive

Execute, schedule, inspect or manage batch jobs.

按 ``action`` 执行批处理操作:execute / schedule / status / cancel / list /
templates / run_script。
- ``execute``: run a list of tool calls synchronously (each ``command``
  has ``tool`` + ``arguments``); ``stop_on_error`` halts on the first
  failure.
- ``schedule`` / ``status`` / ``cancel`` / ``list``: create and manage
  one-off / cron / dependency-chained jobs (durable across restarts).
- ``templates``: list reusable Jinja2 command templates.
- ``run_script``: execute a sandboxed script (python / scr / batch).

When not to use: ``cad_batch`` sequences *other* tools. For a single
operation call the concrete aggregate directly (``cad_object``,
``cad_file``, ...). ``execute`` is synchronous — use ``schedule`` for
long-running work.

Inputs: batch. Returns: Output of the aggregate batch tool.

cad_camA
Idempotent

Generate, simulate or export 2.5-axis toolpaths (contour + drilling).

聚合 CAM 工具。按 ``action`` 派发:
- ``toolpath``: 从当前文档的矩形/多边形(轮廓)与圆(钻孔)生成 2.5 轴刀轨,
  返回轮廓数、钻孔数、刀轨长度与包围盒。
- ``simulate``: 返回仿真报告(刀轨长度 + 估算加工时间)。
- ``export_gcode``: 生成并写出 G-code(G0/G1 + 钻孔循环,M2 结束)。

When not to use: 需要完整 3D 刀具路径或刀轴控制时超出本工具范围;本工具
聚焦 2.5 轴轮廓铣削 + 钻孔。

Inputs: cam (required). Returns: Output of the aggregate cam tool.

cad_collabA

Session, branch, annotation, presence, history, resolve, permission or sync.

聚合协作操作。按 ``tool`` 派发到协作子域:session / branch / annotation /
presence / history / resolve / permission / sync。
- ``session``: create / list / join / leave / info a collaboration session
  over a document.
- ``branch``: fork / edit / merge / list document branches (CRDT).
- ``annotation``: add / list / close review annotations.
- ``presence``: set / get / list user presence.
- ``history``: applied operation history.
- ``resolve``: settle a branch-merge conflict (ours / theirs / latest).
- ``permission``: RBAC list / grant / check (viewer/editor/admin/owner).
- ``sync``: push operations + pull deltas/state — the WebSocket entry point.

When not to use: ``cad_collab`` coordinates *multi-user* work on a
document. For single-user edits use ``cad_object`` / ``cad_layer`` /
``cad_file`` directly; RBAC defaults to the session owner for unknown
users until an identity transport is configured.

Inputs: collab (required). Returns: Output of the aggregate collab tool.

cad_constraintA

Add, remove, list or solve geometric constraints.

按 ``action`` 执行约束操作:add / remove / list / solve。
Adds 2D sketch constraints between entities (e.g. coincidence, distance,
angle). ``solve`` runs the constraint solver and reports residual error;
the optional ``planegcs`` backend is used when installed.

When not to use: ``cad_constraint`` constrains *geometry*; for assembly
mating (parts) use ``cad_assembly`` (action=add_mate/solve). For direct
transforms use ``cad_object`` (action=transform).

Inputs: constraint. Returns: Output of the aggregate constraint tool.

cad_drawingA
Destructive

Create, edit or export an engineering drawing.

聚合工程图操作。按 ``action`` 派发:create / add_view / add_section /
add_dimension / add_tolerance / delete / export。
- ``create``: a sheet (paper A0-A4, title block).
- ``add_view`` / ``add_section``: main / projection / section / detail /
  isometric views over referenced entities.
- ``add_dimension``: ISO 129-1 dimensions (linear / angular / radial /
  diameter / ordinate).
- ``add_tolerance``: GD&T feature-control frames (position / flatness /
  parallelism / perpendicularity / concentricity).
- ``export``: write the sheet as svg / dxf / pdf at ``path``.

When not to use: ``cad_drawing`` produces engineering drawing sheets.
For plain 2D/3D preview images use ``cad_render``; for interop geometry
files use ``cad_file`` (export step/dxf/stl); for object geometry edits
use ``cad_object``.

Inputs: drawing (required). Returns: Output of the aggregate drawing tool.

cad_featureA

Sweep, loft, fillet, chamfer or pattern geometry.

聚合特征操作。按 ``action`` 派发:sweep / loft / fillet / chamfer /
pattern_linear / pattern_circular / pattern_mirror。
- ``sweep`` / ``loft``: create new solids from a profile (sweep along a
  ``path``) or between ``profile_ids`` (loft). OCCT-backed when the
  ``occ`` extra is installed, with analytic fallbacks otherwise.
- ``fillet`` / ``chamfer``: round or bevel edges — exact on the OCCT
  kernel, otherwise report ``requires_occ``.
- ``pattern_linear`` / ``pattern_circular`` / ``pattern_mirror``: copy an
  entity into an array (rigid transforms, available on every kernel).

When not to use: ``cad_feature`` derives new geometry from existing
entities. For editing a single object's parameters use ``cad_object``
(update/transform); for boolean combination use ``cad_object``
(action=boolean).

Inputs: feature (required). Returns: Output of the aggregate feature tool.

cad_fileA
Destructive

Create, open, save, close, delete, list, import or export files.

聚合文件操作。按 ``action`` 派发:create / open / save / close / delete /
list / import / export。
- ``create`` / ``open`` / ``save`` / ``close`` / ``delete`` / ``list``:
  manage in-memory documents. ``open`` and ``save`` read/write the JSON
  scene format; ``create`` starts a new document (optional ``template`` /
  ``unit``).
- ``export``: write the current document to an interop format — step
  (recommended), dxf, stl, dwg or json — at ``path``.
- ``import``: load an interop file (.json / .dxf / .step / .dwg) as a new
  document.

When not to use: ``cad_file`` handles whole files/documents. For
per-object geometry edits use ``cad_object``; to import/export raw JSON
scene data (not files) use ``cad_json`` (import_scene/export_scene).

Inputs: file (required). Returns: Output of the aggregate file tool.

cad_gltfA
Idempotent

Export, import or preview glTF 2.0 geometry.

聚合 glTF 工具。按 ``action`` 派发:
- ``export``: 将当前文档的实体(实体几何)导出为自包含 glTF 2.0 文件,
  颜色属性映射为 PBR ``baseColorFactor``。
- ``import``: 读取 glTF 文件并把每个 mesh 作为 ``mesh`` 实体导入当前文档。
- ``preview``: 返回当前文档 glTF 表示的概要(mesh 数 / 包围盒)。

When not to use: 需要 STEP/DXF/STL 等工程格式互操作时用 ``cad_file``
(import/export);本工具专注 glTF 网格资产。

Inputs: gltf (required). Returns: Output of the aggregate gltf tool.

cad_jsonA
Read-onlyIdempotent

Read / parse / validate / import / export JSON.

按 ``action`` 执行 JSON 读写、解析、校验、导入与导出:
- load:读取文件原文
- parse:解析并报告结构
- validate:按 scene/geometry 模式校验
- import_geometry:将 JSON 几何导入当前文档
- export_geometry:将对象导出为 JSON
- import_scene:以 JSON 场景创建新文档
- export_scene:导出当前文档为 JSON 场景
- save:将 JSON 字符串写入文件

When not to use: ``cad_json`` operates on JSON text and scene data in
memory. To read/write the JSON scene as a whole file use ``cad_file``
(open/save); for interop formats (STEP/DXF/STL/DWG) use ``cad_file``
(import/export); for creating/editing individual geometry objects use
``cad_object``.

Inputs: params (required). Returns: Output of the aggregate JSON tool.

cad_layerA
Destructive

Create, read, update, delete or list layers.

聚合图层操作。按 ``action`` 派发:create / read / update / delete / list。
Layers group objects for display and selection. ``create`` accepts
color / linetype / linewidth; ``update`` can also toggle ``visible`` /
``locked``; ``delete`` removes the layer *and* the objects on it.

When not to use: for per-object layer membership use ``cad_object``
(create/update with a ``layer``); for per-layer object counts use
``cad_status`` (target=layer). To hide objects without deleting them
prefer ``cad_layer`` (update visible=false).

Inputs: layer (required). Returns: Output of the aggregate layer tool.

cad_measureA
Read-onlyIdempotent

Measure a distance or an object's area/volume.

聚合测量操作。按 ``action`` 派发:distance / area。
- ``distance``: Euclidean distance between ``point_a`` and ``point_b``
  (2D ``[x, y]`` or 3D ``[x, y, z]``), returns ``distance``.
- ``area``: measure an existing object by ``object_id`` — 2D kinds
  (circle / rectangle / polygon) return area (``mm^2``), 3D kinds
  (box / cylinder / sphere / cone) return volume (``mm^3``); ``kind``
  in the output reports which.

When not to use: ``cad_measure`` reads existing geometry. To query
object position / bounding box use ``cad_object`` (action=read) or
``cad_status`` (target=object); to validate mesh validity use
``cad_validate`` (action=geometry).

Inputs: measure (required). Returns: Output of the aggregate measurement tool.

cad_nlpA

Parse a natural language request into a tool call or continue a chat.

聚合 NLP 操作。按 ``action`` 派发:command / chat。
- ``command``: map free-form English/Chinese text to a CAD tool call
  (returns ``tool`` + ``arguments``; does NOT execute it). Ambiguous
  requests return candidate ``suggestions``.
- ``chat``: multi-turn dialogue with anaphora resolution — a create
  intent executes immediately and its object is remembered so "move it"
  / "把它" resolve to that object.

When not to use: ``cad_nlp`` is a convenience dispatcher. For
deterministic, schema-driven control prefer calling the concrete
aggregate tools directly (``cad_object``, ``cad_file``, ...). ``command``
only parses — you must dispatch the returned call yourself.

Inputs: nlp (required). Returns: Output of the aggregate natural language tool.

cad_objectA
Destructive

Create, read, update, delete, copy, transform, list or boolean objects.

聚合对象操作。按 ``action`` 派发:create / read / update / delete / copy /
transform / list / boolean。
- ``create``: add an entity by ``type`` (line, circle, arc, rectangle,
  polygon, polyline, box, cylinder, sphere, cone) with ``params``;
  returns the new ``object_id`` and bounding box.
- ``read`` / ``update`` / ``delete`` / ``copy``: inspect, edit (geometry /
  layer / properties), remove, or duplicate an object by ``object_id``.
- ``transform``: apply a 4x4 matrix (column-major, translation in the
  fourth column) for translate / rotate / scale.
- ``list``: enumerate objects, optionally filtered by ``layer``.
- ``boolean``: combine objects (union / subtract / intersect) into a new
  mesh; requires the optional ``boolean`` extra.

When not to use: ``cad_object`` edits the current document's geometry.
For interop file formats use ``cad_file`` (import/export); for JSON
scene round-trips use ``cad_json``; for measurements on existing objects
use ``cad_measure``; for geometric validation use ``cad_validate``.

Inputs: object (required). Returns: Output of the aggregate object tool.

cad_pluginA

Install, uninstall, list, enable, disable or inspect plugins.

聚合插件工具。按 ``action`` 派发:install / uninstall / list / enable /
disable / manifest。
- ``install``: 触发 entry-point 发现,只从已安装发行版加载插件(不接收
  任意模块路径)。
- ``uninstall`` / ``enable`` / ``disable``: 按名字管理插件生命周期。
- ``list``: 触发 entry-point 发现并列出已安装插件。
- ``manifest``: 返回指定插件的静态声明(名称/版本/权限/依赖)。

Security: 插件与服务器运行在同一进程 / 信任域,未做进程级沙箱。
``install`` 只加载已安装发行版的 entry-point 插件(等价于 ``pip
install`` 的信任边界),不接受 ``module:attr`` 导入。仅从可信来源安装
插件;进程级沙箱是后续硬化项。

When not to use: 插件提供的实际建模能力应通过其注册的 MCP 工具直接调用;
``cad_plugin`` 只管理插件生命周期。

Inputs: plugin (required). Returns: Output of the aggregate plugin tool.

cad_renderA
Read-onlyIdempotent

Render the document in a selected mode.

按 ``mode`` 渲染当前文档:
- ortho:2D 正交投影 PNG(top/front/side)
- view_3d:按存储的三维视图定义渲染 PNG
- section:平面剖切 PNG(plane=XY/YZ/XZ)
- explode:爆炸视图 PNG
- animation:orbit/turntable GIF 动画
- webgl:WebGL 增量同步 delta

When not to use: ``cad_render`` produces images / sync deltas only. To
store or edit a named view *definition* before rendering use
``cad_view``; for drawing-sheet exports (SVG/DXF/PDF) use
``cad_drawing`` (action=export); for interop geometry files use
``cad_file`` (export).

Inputs: render (required). Returns: Output of the aggregate render tool.

cad_simA
Destructive

Mesh, setup, run, inspect or delete a simulation.

聚合仿真操作。按 ``action`` 派发:mesh / setup / run / result / list / delete。
- ``mesh``: generate a hexa8 hex mesh of an entity's bounding box (pure
  Python, always available).
- ``setup``: register a simulation (``kind`` = fea or kinematics).
- ``run``: execute synchronously, or schedule an async batch job with
  ``async_run``. FEA (CalculiX) and kinematics (PyBullet) backends are
  optional — absent engines report ``requires_sim``.
- ``result`` / ``list`` / ``delete``: inspect or remove simulations.

When not to use: ``cad_sim`` analyzes physical behavior. For geometric
*validity* checks use ``cad_validate`` (geometry/interference); for
meshing previews that are pure geometry use ``cad_object`` (read).

Inputs: sim (required). Returns: Output of the aggregate simulation tool.

cad_statusA
DestructiveIdempotent

Query session, file, object, layer, health or logs status.

按 ``target`` 查询当前会话的各类状态(check/file/object/layer/health/
logs_get/logs_clear)。
- ``check``: overall session summary (open files, current document).
- ``file`` / ``object`` / ``layer``: live detail for one entity.
- ``health``: server version, uptime and registered tool count.
- ``logs_get`` / ``logs_clear``: read (with limit/level/source/job_id
  filters) or clear the in-memory log buffer.

When not to use: ``cad_status`` reports live session/server state. For
geometric *validation* (manifold checks, interference) or aggregate
document statistics use ``cad_validate`` (geometry/metrics); for
measuring distances/areas use ``cad_measure``.

Inputs: status. Returns: Output of the aggregate status tool.

cad_validateA
Read-onlyIdempotent

Validate geometry, detect interference, inspect topology or fetch metrics.

聚合校验操作。按 ``action`` 派发:geometry / interference / topology / metrics。
- ``geometry``: check objects for self-intersections, degenerate faces and
  non-manifold edges (optional ``object_ids`` filter); returns issues with
  ``type`` / ``location`` / ``fix_suggestion``.
- ``interference``: detect box-box overlaps between objects, with overlap
  volume per pair.
- ``topology``: per-object vertex/edge/face counts and manifold status.
- ``metrics``: aggregate document stats (files, objects, layers, bbox,
  kinds) for the current session.

When not to use: ``cad_validate`` analyzes correctness and aggregates.
For simple geometric measurements (distance / area) use ``cad_measure``;
for live server/file/object status use ``cad_status``; for JSON scene
validation against the schema use ``cad_json`` (action=validate).

Inputs: query (required). Returns: Output of the aggregate validation tool.

cad_variableA

Set or list parametric variables in the current document.

按 ``action`` 设置(set)或列出(list)当前文档的参数变量。Set with
``value`` and/or ``expr`` (expressions may reference other variables,
e.g. ``width * 2``); ``{name}`` tokens in CLI draw arguments interpolate
the resolved value.

When not to use: variables are document-scoped bookkeeping — do NOT use
them to store free-form strings (only numeric values), and use
``cad_object_update`` for geometry changes rather than variables.

Inputs: variable. Returns: Output of the aggregate variable tool.

cad_versionA

Save, list, diff or restore document version snapshots.

按 ``action`` 执行版本快照操作:save / list / diff / restore。
In-memory snapshots of the current document state. ``save`` captures a
labeled snapshot; ``diff`` compares two snapshots with ``deepdiff`` and
reports changed/added/removed fields; ``restore`` rolls the document back
to a snapshot.

When not to use: ``cad_version`` is for in-memory undo-like versioning.
For durable file persistence use ``cad_file`` (save/export); for
collaboration branches use ``cad_collab`` (tool=branch).

Inputs: version. Returns: Output of the aggregate version tool.

cad_viewA
Destructive

Create, read, list, update or delete a 3D view definition.

聚合 3D 视图操作。按 ``action`` 派发:create / read / list / update / delete。
Manages named ``View3DDefinition`` records (camera pose, projection,
section plane, explode offsets). Each view has a unique ``name`` per
document and an optional explicit ``view_id``.

When not to use: ``cad_view`` manages view *definitions* only — it does
not produce images. To render a stored view (or ortho / section / explode /
animation / webgl output) use ``cad_render`` (mode=view_3d etc.).

Inputs: view (required). Returns: Output of the aggregate 3D view tool.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 22 tools

    Disambiguation4/5

    Each cad_* tool targets a distinct domain and the 'When not to use' sections actively separate overlapping areas like cad_file vs cad_json vs cad_gltf and cad_status vs cad_validate. A few boundaries remain blurry (cad_status metrics vs cad_validate metrics, cad_version snapshots vs cad_collab branches), but the descriptions mostly prevent misselection.

    Naming Consistency5/5

    All tools follow a consistent cad_<domain> pattern, making the surface highly predictable. This uniform prefix convention is clearer than many servers using mixed verb styles.

    Tool Count4/5

    22 tools is on the heavy side, but each maps to a distinct CAD subdomain such as file, object, layer, assembly, drawing, simulation, CAM, and collaboration. The count is justified for a full CAD server rather than padding, though it is slightly above the typical 3-15 well-scoped range.

    Completeness5/5

    The surface covers the CAD lifecycle unusually well: document/file management, geometry CRUD, layers, views, constraints, assemblies, drawings, features, simulation, CAM, glTF, plugins, validation, status, and collaboration. There are no obvious dead ends—each domain includes the key create/read/update/delete or equivalent operations needed.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      CAD-engineering MCP tool server for parametric modeling, DFM validation, mechanical calculations, and more. Enables code-CAD builds (build123d/CadQuery), model inspection, meshing, and mechanical calculators via MCP stdio.
      11
      -
    • A
      license
      B
      quality
      D
      maintenance
      MCP server that lets AI draw in AutoLISP-capable CAD (reference BricsCAD on Linux) via a file bridge, enabling 2D drafting, 3D solid modeling, and verification with 100 tools.
      128
      3
      Apache 2.0