TianshangCAD
This server provides a comprehensive CAD system via MCP, supporting 2D/3D design, editing, validation, rendering, automation, and real-time collaboration.
File Management: Create, open, save, close, list, export (JSON, DXF, STL, STEP, SVG, PDF), and import CAD files.
Object Creation & Editing: Create points, lines, circles, arcs, rectangles, polygons, polylines, boxes, cylinders, spheres, cones; read, update, delete, move, rotate, scale, copy, and erase objects.
Layers: Manage layers with color, linetype, linewidth, visibility, and lock states.
Boolean Operations: Union, subtract, intersect on 3D objects.
Parametric Design: Set and list named variables with units and expressions.
Geometric Constraints: Add, remove, list, and solve constraints (fixed, coincident, parallel, perpendicular, tangent, distance, angle).
Assembly Modeling: Create assemblies, add parts/sub-assemblies, define mates (coincident, concentric, distance, etc.), solve, generate BOM (JSON/CSV), and compute exploded views.
Engineering Drawings: Create sheets (A0–A4), add views (main, projection, section, detail, isometric), dimensions (ISO 129-1), GD&T, and export to SVG/DXF/PDF.
Advanced Features: Sweep along path, loft between profiles, fillet, chamfer, linear/circular/mirror patterns.
Validation & Metrics: Check self-intersections, degenerate faces, non-manifold edges, interferences; compute topology and document metrics.
Rendering: Orthographic (top/front/side) and 3D PNGs at 72–300 DPI, section/exploded views, orbit/turntable GIFs, WebGL delta sync.
Versioning: Save, list, diff (deepdiff), and restore document snapshots.
Natural Language Processing: Parse English/Chinese commands, multi-turn dialogue with anaphora resolution.
Batch Automation: Execute command sequences, schedule cron jobs, run sandboxed Python/SCR scripts, manage job status and templates.
Simulation: Mesh entities, set up and run FEA/kinematics simulations, retrieve results.
Collaboration: Real-time editing via CRDT, sessions, branches, annotations, presence, operation history, and role-based access.
System Status: Check overall health, file/object/layer status, and retrieve logs.
Employs FreeCAD as an optional geometric kernel for CAD modeling operations.
Provides a /metrics endpoint with Prometheus-compatible metrics for monitoring the server.
Exports 3D scene data as Three.js BufferGeometry JSON, enabling visualization in a browser via a bundled Three.js viewer.
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),
ruffandmypyclean.
中文文档: readme/README.zh-CN.md
Changelog · Migration guide v0.6.0 → v0.9.0
Features
CAD CLI —
file,draw,edit,view,measure,layer,batchcommand groups with short aliases (l=draw line,c=draw circle, ...)MCP Server — 20 core JSON-RPC aggregate tools (each with an
actiondiscriminator) over stdio, streamable HTTP or WebSocket (collaboration), callable from Claude, Cursor and other MCP clientsPlugin ecosystem — plugin SDK (manifest + permissions + lifecycle + entry-point discovery) with two official plugins:
plugin-gltf(glTF 2.0 import/export) andplugin-cam(2.5-axis toolpaths → G-code), exposingcad_gltf/cad_cam3D views — JSON-defined
View3DDefinitionwith 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 clientsBatch 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_suggestiondiagnostics; box-box interference volumes; topology metricsRendering — 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 / restoreNatural language —
cad_nlpmaps English / Chinese requests to tool calls with ambiguity handlingJSON-driven — scenes and geometry defined and validated with Pydantic schemas; full import/export round-trip
Pluggable kernel — analytic (default, no native deps) / OCC (
cadquery) / FreeCADFile 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/healthendpointQuality gates —
mypystrict typing,rufflinting,pytestwith 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 basepip 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 theccxsolver binary installed separately; install it from calculix.de and ensureccxis inPATH.
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.debOptional 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,100Short 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 |
| new, open, save, close, list, info, export, import |
| line, circle, arc, rectangle, polygon, polyline, box, cylinder, sphere |
| move, copy, rotate, scale, erase, list, undo, redo |
| zoom, pan, list |
| distance, area, list |
| create, list, set, on, off, delete |
| view, 3d, webgl, view3d, section, explode, gif, views, status |
| 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 stdioStreamable HTTP
python -m tianshangcad --transport http --host 127.0.0.1 --port 8081The 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 |
|
Objects |
|
Layers |
|
JSON |
|
Measure |
|
Validate |
|
Status |
|
Render |
|
3D Views |
|
NLP |
|
Version |
|
Variables |
|
Batch |
|
Constraints |
|
Assembly |
|
Drawing |
|
Features |
|
Simulation |
|
Collaboration |
|
Plugins |
|
glTF (plugin) |
|
CAM (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 pronounVersion 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 8082MCP 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 manifestTwo official plugins ship with the package:
plugin-gltf— glTF 2.0 import/export (PBR materials);cad_gltf,gltfCLI.plugin-cam— 2.5-axis contour + drilling toolpaths to G-code;cad_cam,camCLI.
Security: plugins run in-process, in the same trust domain as the server, and are not sandboxed. The MCP
cad_plugininstallaction only loads plugins from installed distributions' entry-points (it never imports an arbitrarymodule:attrpath); 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 -dThe 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.shOr 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.jsonTo 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 testsDocumentation
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 toolscad_assemblyADestructive
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_batchADestructive
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_camAIdempotent
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_drawingADestructive
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_fileADestructive
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_gltfAIdempotent
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_jsonARead-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_layerADestructive
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_measureARead-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_objectADestructive
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_renderARead-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_simADestructive
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_statusADestructiveIdempotent
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_validateARead-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_viewADestructive
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
Scored across 22 tools
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.
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.
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.
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
Related MCP Connectors
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Text-to-CAD: build exact STEP or 3MF/STL on the server, each stated requirement measured.
Parametric CAD as code: model 3D-printable parts on an exact B-rep kernel, measured.
Collaborative whiteboard MCP server — create objects, connectors, C4 diagrams, and manage boards
Related MCP Servers
- AlicenseAqualityAmaintenanceMCP server for Python build123d to help AIs develop and reason about 3D models and CAD482,099 PyPI154Apache 2.0
- FlicenseAqualityBmaintenanceCAD-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-
- AlicenseBqualityDmaintenanceMCP 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.1283Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for AI-driven CAD operations, enabling parametric modeling, build, inspection, measurement, rendering, and diff comparison with STEP, DXF, and GLB export.MIT