+
Not a mockup. Every line on this sheet was drawn by the tools this server exposes — ISO layers, involute gear geometry, DIN 6885 keyway, section A-A, ISO 129 dimensions, an ISO 286 H7 bore fit, ISO 7200 title block — then rendered headlessly by view_screenshot. drawing_critique returns 0 issues on it. Rebuild it with python scripts/render_readme_showcase.py.
| Area | What it does |
|---|---|
| Drawing lifecycle | create, open, save, export DXF/PDF, audit (now repairs), purge; undo/redo live on COM and opt-in headless via EZDXF_UNDO_DEPTH |
| Geometry | lines, arcs, polylines, splines, hatches, trim/extend/fillet/chamfer, handle-preserving edits |
| Annotation | ISO 129 toleranced dimensions, ISO 286 fits (fit="H7"), TABLE, MLEADER, GD&T frames and datums (ISO 1101) |
| Engineering generators | involute gears (front + section A-A), DIN 6885 keyed bores, ISO A3 title block |
| Discovery ✨ | search_tools ranked over an AutoCAD command and synonym corpus — FILLET, BPOLY, QSELECT, WBLOCK, OVERKILL, CHSPACE each rank #1 of the 154-tool registry |
| Batching ✨ | cad_batch runs a whole step list in one round trip; fields= projects the response on 11 result-heavy tools (a closed, gated list) |
| Paper space ✨ | 8 of the 12 layout tools are new — layout_delete/rename/copy, viewport_list/set_scale/lock/delete, entity_change_space (CHSPACE, headless only); layout listing, creation and activation, viewport_create and drawing_export_pdf(layout=...) shipped in v1.4.0, which wrongly declared headless viewport rendering impossible |
| Selection ✨ | window vs crossing stated back to the caller; the polygon is tested as a shape, not as its bounding box — the entity side is still its bounding box, on both engines |
| Boundaries ✨ | boundary_trace (BOUNDARY/BPOLY) chains loose edges into one closed polyline; ARC edges keep their exact bulges, while a bulged polyline segment or any other curved edge is chained as its chord — headless engine only |
| Measurement ✨ | analysis_measure_entity measures what is in the drawing, by handle |
| Hatch depth ✨ | gradients, in-place edits and island styles on both; typed edge boundaries headless only |
| Annotation objects ✨ | WIPEOUT, REVCLOUD, MTEXT background masks — headless only, ActiveX exposes no member — plus text find/replace on both |
| 3D solids | solid_box/cylinder/extrude/revolve/boolean on live AutoCAD (ENABLE_3D=true) — unverified against a live seat: they shipped in v1.4.0, and the v1.5.0 live run covered only what that release added |
| Quality loop | drawing_preflight → drawing_plan → drawing_critique → drawing_refine → drawing_finalize (0–100 score) |
| Delivery | drawing_deliver: DXF/PDF/PNG + SHA-256 manifest + reopen-parity checks |
entity_creation 18, entity_modification 15, layers 14, analysis 12, layouts 12, premium 12, drawing 11, engineering 10, blocks 8, entity_query 8, system 7, dimensions 5, solids 5, corner_ops 4, view 4, batch 3, transactions 3, templates 2, validation 1.
+154 tools in 19 groups. Plus 6 resources that cost nothing in the tool budget (autocad://drawing/info, layers, blocks, entities/stats, entities/{layer_name}, system/status) and 5 prompt templates.
-Alongside the tools, **6 MCP resources** cost nothing in the tool budget and are browsable at any time — `autocad://drawing/info`, `autocad://layers`, `autocad://blocks`, `autocad://entities/stats`, `autocad://entities/{layer_name}`, `autocad://system/status` — plus **5 prompt templates** (`prompt_mechanical_drawing`, `prompt_floor_plan`, `prompt_electrical_schematic`, `prompt_pid_diagram`, `prompt_quick_drawing`).
-
-### Two rules worth knowing before you draw
-
-**Coordinates come out in WCS, and the exceptions are declared rather than hidden.** DXF stores CIRCLE / ARC / LWPOLYLINE / TEXT / INSERT geometry in a per-entity frame, and before v1.5.0 the word `extrusion` appeared nowhere in this codebase, so a mirrored or rotated entity reported coordinates that were quietly wrong. An entity in a plane tilted out of WCS XY now reports `plane_normal` and omits the fields xy cannot express, rather than answering with a number that looks fine.
-
-Three things stay in the entity frame on purpose, and `system_capabilities`' `ocs_normalized` reason string is the live list: **TEXT `rotation`** (a mirrored TEXT is mirror-imaged, and no single scalar angle expresses that), **z components**, and **HATCH boundary geometry**. On the live backend that same reason string also records `2d_polyline_coordinates_not_verified_against_live_autocad` — read it at runtime rather than trusting this paragraph.
-
-**Never read vertices back and shoelace them.** That loses **28.2%** of the area on a semicircular edge, silently. `analysis_measure_entity(handle)` reads the real geometry and states its own accuracy: `exact`, `flatten_tolerance`, `assumed_closed`, `self_intersecting`.
+**Two rules worth knowing.** Every coordinate in and out of a tool is WCS on both engines — the one exception is TEXT `rotation`, which stays in the entity frame because a mirrored TEXT is mirror-imaged and no scalar angle expresses that. And never read vertices back and shoelace them: that loses **28.2%** of the area on a semicircular edge, silently. `analysis_measure_entity(handle)` reads the real geometry and states its own accuracy.
## The two engines
-One contract, split across 19 modules in `backends/contracts/`. Most are ABCs; `gdt.py` and `settings.py` are concrete shared mixins rather than interfaces. Optional methods are declarative — `@capability(key, reason=...)` supplies a default that *refuses* — and a test holds the two backends' capability key sets equal, so a key cannot exist on one engine and be forgotten on the other.
-
-There are **27 capability keys**. `system_capabilities` returns the live map, and you should read it at runtime rather than trusting the table below, because five of the 27 depend on how the machine is set up:
+One contract across 19 modules in `backends/contracts/`. `@capability(key, reason=…)` supplies a default that *refuses*, and a test holds both backends' capability key sets equal. There are **27 capability keys**; read `system_capabilities` at runtime rather than trusting the table — five of them depend on how the machine is set up.
| Capability | COM (live AutoCAD) | ezdxf (headless) |
|---|:---:|:---:|
| Live document control | ✅ | — |
| Cross-platform, no AutoCAD | — | ✅ |
-| Transactions and rollback | ✅ *undo mark; rollback sends `_UNDO B` and AutoCAD never confirms it landed — best-effort, not atomic* | ✅ *full DXF snapshot, restored synchronously* |
+| Transactions and rollback | ✅ | ✅ |
| Paper-space layouts + viewports | ✅ | ✅ |
-| Viewport model-content rendering | ✅ | ✅ ᵐ *(no viewport borders)* |
+| Viewport model-content rendering | ✅ | ✅ ᵐ *(no borders)* |
| Selection window / crossing / polygon | ✅ | ✅ |
| Entity area by handle | ActiveX `.Area` | Analytic, bulges included |
-| HATCH filled area (islands subtracted) | AutoCAD's own number — *measured: a r20 hatch with an r10 island returns 942.478, so the island is subtracted* | Loops walked, `hatch_style` reported |
-| REGION area | ✅ *`.Area` + `.Perimeter`, verified on a seat* | — *ACIS is opaque to ezdxf* |
-| 3DSOLID **surface** area | — *ActiveX exposes `.Volume` only; use MASSPROP* | — |
-| 3D solids | ✅ *only with `ENABLE_3D=true`* | — *no headless ACIS* |
-| DWG write | ✅ | — *no DWG writer* |
-| WIPEOUT | — *`AddWipeout` verified absent, AutoCAD 2026* | ✅ |
-| MTEXT background colour | — *`BackgroundFillColor` verified absent, AutoCAD 2026* | ✅ |
-| REVCLOUD, BPOLY / boundary tracing | — *no ActiveX member; command-line only* | ✅ |
-| CHSPACE (`entity_change_space`) | — *unverified against a live seat* | ✅ ᶜ |
-| Undo history | ✅ | opt-in — `EZDXF_UNDO_DEPTH` defaults to `0` |
+| HATCH filled area (islands subtracted) | AutoCAD's own number | Loops walked, `hatch_style` reported |
+| REGION / 3DSOLID area | ✅ | — *ACIS is opaque to ezdxf* |
+| 3D solids | ✅ *with `ENABLE_3D=true`* | — |
+| DWG write | ✅ | — |
+| WIPEOUT · MTEXT background colour | — *verified absent, AutoCAD 2026* | ✅ |
+| REVCLOUD · BPOLY · typed hatch edges | — *no ActiveX member* | ✅ |
+| CHSPACE | — *unverified on a live seat* | ✅ ᶜ |
+| Undo history | ✅ | opt-in — `EZDXF_UNDO_DEPTH` |
| TABLE and MLEADER | Native | Portable composite |
-| Raw commands / AutoLISP | ✅ *on by default, denylist-sanitized — `DANGEROUS_COMMANDS_ENABLED=true` removes the denylist* | — *no live command line* |
-| Screenshots and PDF export | AutoCAD window capture | Matplotlib render ᵐ |
+| Screenshots and PDF | Window capture | Matplotlib ᵐ |
-ᵐ Needs matplotlib — the `[pdf]` or `[full]` extra. Without it `png`, `pdf`, `viewport_render` and `handle_overlay` all report unsupported on the headless engine.[pdf]/[full]); without it png, pdf, viewport_render and handle_overlay report unsupported headlessly.
-
-| Server | Matrix | Pinned | Score | Pass |
-|---|---|---|---:|---:|
-| **autocad-mcp-pro** *(this repo)* | v3 · 15 tasks | working tree | **100.0** | 15/15 |
-| [beiming183-cloud/AutoCAD-MCP](https://github.com/beiming183-cloud/AutoCAD-MCP) | v2 · 10 tasks | `11f7c47` | 50.0 | 5/10 |
-| [puran-water/autocad-mcp](https://github.com/puran-water/autocad-mcp) | v2 · 10 tasks | `95476a3` | 45.0 | 4/10 |
-
-> [!WARNING]
-> **Read the matrix column before the score column.** The five v3 tasks are new in v1.5.0; the competitor runs are from 2026-07-23 against pinned competitor commits, and were never put to them. Their scores are over the ten tasks they actually ran, and the five new rows render blank rather than as zeros — an invented zero is indistinguishable from a measured one. These bars do not share a denominator, which is why each one carries its matrix.
-
-Competitors are driven **black-box over MCP stdio** against the tool contracts read from their pinned source, at **50% coverage on both**: five of the ten tasks per competitor are recorded `unsupported` — the operation is absent from that checkout, or refused by it — and those rows score zero against a denominator of ten, so 50.0 and 45.0 are coverage-weighted, not ten measured attempts. Over the tasks actually driven, beiming scores 100.0 and puran-water 90.0. Where a task does run, every geometry claim the competitor makes is re-derived by re-opening the exported DXF with ezdxf inside the harness — their own tool output is never the source of truth. This repo's row is not run that way: it runs in-process against the backend, and 13 of its 15 tasks assert on backend return values rather than on a re-opened DXF (only `dxf_roundtrip` and `auditable_delivery` write a file at all). What is independent there is the expected value — a closed-form area, entities placed on purpose, a token ceiling fixed before the measurement — not the observation. A capability refusal is recorded `unsupported`, not `fail` — "cannot reach this" and "got this wrong" are different findings. That classification is written into the adapter from the competitor's pinned source; a refusal that only appears at runtime becomes `unsupported` where the adapter recognises it (beiming's `E_UNSUPPORTED` on `transaction begin` is the one that did) and lands as `fail` otherwise.
-
-### 2 · Task matrix — where the score comes from
-
-
-
-**v2 scored this repo 10/10, and that number carried no information**: every task in it exercised something the server was built around. v3 adds five tasks chosen because they *can* fail — and two of them did, while being written: `hatch_islands` (a HATCH could not be measured at all) and `measure_from_handle` (the boundary tools and the measurement tool disagreed about the same shape). A third measurement defect fixed in the same release — a circle stored as two bulged vertices measured 0.0 — is carried by `two_vertex_circle_has_area` in the correctness suite, not by a benchmark task.
-
-| v3 task | Verified against |
-|---|---|
-| `tool_discovery` | six AutoCAD command names, each ranking **#1** of the 154-tool registry the harness ranks (pass bar is top-3) |
-| `token_budget` | 40,305 → 356 tokens advertised, against a 2,000 ceiling fixed in advance |
-| `hatch_islands` | **300** filled with the island, 400 ignoring it |
-| `selection_filter` | window 1, crossing 2, bounding box 3, polygon 1 |
-| `measure_from_handle` | **139.2699** against the 100.0 a vertex shoelace gives |
-
-### 3 · Correctness A/B — every release re-proves itself
+### Correctness — every release re-proves itself
26 deterministic headless checks against the previous tag and the current tree, each in its own subprocess so a hard crash counts as a miss rather than killing the run.
-**v1.5.1 release gate**, baseline `v1.5.0` ([report](https://github.com/U-C4N/Autocad-MCP/blob/main/benchmarks/results/published/ab-v1.5.0-vs-v1.5.1.json)):
-
| Version | Checks passing | Pass rate | Fixed | Regressed |
|---|---:|---:|---:|---:|
| v1.5.0 *(baseline)* | 24 / 26 | 92.3 % | — | — |
| **v1.5.1** *(this release)* | **26 / 26** | **100 %** | 2 | **0** |
-**v1.5.0 fails two of these**, and they are the reason it is yanked:
-`diameter_dim_measures_the_diameter` and `radius_dim_ignores_the_leader_length`.
-It has both methods and gets both wrong — `leader_length`, a *text placement*,
-was being measured as geometry, so at default settings every diameter callout
-came out **2 × leader_length too large** (60 on a true ⌀40). v1.4.0 shipped the
-same defect. The live COM backend was never affected.
+Against the older `v1.4.0` baseline the same suite reports **21 / 26 → 26 / 26, five fixed, zero regressed**. Three of the five are new capability (`miss → pass`); two are repaired defects (`fail → pass`) — the diameter and radius callouts, which measured the leader as geometry and dimensioned a 40 mm bore as 60 at default settings.
-Against the older `v1.4.0` baseline the same suite reports **21 / 26** ᵃ with
-five fixed ([report](https://github.com/U-C4N/Autocad-MCP/blob/main/benchmarks/results/published/ab-v1.4.0-vs-v1.5.0.json)) — three of those
-five are new capability rather than repairs: v1.4.0 has no `entity_measure` and
-no boundary tracing, so it misses them by not having the method.
+### The task matrix — five tasks that can fail
-ᵃ Against the 26-check current suite. v1.4.0 passed 21/21 of the checks that existed when it shipped.
+An earlier matrix scored this server 10/10, which carried no information: every task in it exercised something the server was built around. Five were added because they *can* fail, and three did while being written.
-The 21 pre-existing checks are unchanged and all still pass: the discovery layer, `cad_batch`, the 19-module contract split, layouts/viewports and Wave A landed with **zero correctness regressions**.
+| Task | Verified against |
+|---|---|
+| `tool_discovery` | six AutoCAD command names, each ranking #1 |
+| `token_budget` | 40,305 → 356 tokens, against a ceiling fixed in advance |
+| `hatch_islands` | 300 filled with the island, 400 ignoring it |
+| `selection_filter` | window 1, crossing 2, bounding box 3, polygon 1 |
+| `measure_from_handle` | 139.2699 against the 100.0 a vertex shoelace gives |
-### 4 · Headless performance
+### Headless performance
-
+
-| Workload | Wall time | Result |
-|---|---:|---|
-| Create 2,000 lines (individual calls) | 0.35 s | ~5,716 entities/s |
-| 10,000 lines: build + DXF export + reopen | 2.18 s | ~4,591 entities/s end-to-end |
-| Region query over 10,000 entities | 2.47 s | 2,500 matched |
-| Premium pass (layers + part + dims + full critique) | 0.26 s | 0 issues |
-
-One run of each workload — `perf_suite` executes each exactly once per invocation, and these are the figures in the committed [`perf-ezdxf.json`](https://github.com/U-C4N/Autocad-MCP/blob/main/benchmarks/results/published/perf-ezdxf.json). Run-to-run spread on this machine is wide enough to matter: treat them as an order of magnitude, not a stopwatch.
-
-Workloads call the same backend methods the MCP tools call, so the backend's own per-call overhead — worker-thread hand-off, document lock, the `EZDXF_CALL_TIMEOUT` guard — is included. The FastMCP layer above it is **not**: `perf_suite.py` never builds the server, so tool dispatch, argument validation, the five middleware and result serialization all sit outside the timer, and in-process they cost roughly an order of magnitude more than the backend call itself. Read these as backend-engine numbers, not per-tool-call latency. **Self-measurement only** — competitor servers pay an extra stdio serialization cost that in-process runs do not, so no cross-server timing claims are made.
-
-> [!CAUTION]
-> These are **not** an improvement over v1.4.0, and they are not the engine's floor. The per-call timeout guard costs about **21%** of entity-creation throughput — see [what this release is bad at](https://github.com/U-C4N/Autocad-MCP#what-this-release-is-bad-at) for the paired measurement and why the guard is kept.
-
-### 5 · Source-review leaderboard
-
-
-
-Nine public AutoCAD MCP projects against a fixed 100-point rubric — CAD breadth (25), correctness and delivery (20), backends/platforms (15), engineering production (15), tests and maintenance (15), security and operations (10). Stars and raw tool counts score nothing. Data and dates in [`benchmarks/source_review.json`](https://github.com/U-C4N/Autocad-MCP/blob/main/benchmarks/source_review.json).
-
-**This table is not re-scored per release** — no row is, including the other eight. This repository's row is still the one written against **v1.4.0**. Raising our own number for v1.5.0 would mean re-reviewing eight other projects the same day to keep it fair, and that has not been done — so the score stays where the evidence is.
-
-Method, caveats and boundaries for every lane: [`benchmarks/README.md`](https://github.com/U-C4N/Autocad-MCP/blob/main/benchmarks/README.md).
+Workloads call the same backend methods the MCP tools call, so server-side overhead is included. Numbers move with hardware; the report records the machine fingerprint. **Read the next section before quoting them** — this release is slower than v1.4.0 at creating entities, on purpose.
## What this release is bad at
A page that only lists strengths is a page that has not been measured.
-**Entity creation is ~21% slower than it would be without the call timeout.**
-The timeout is what stops one hung ezdxf call wedging a server whose document
-lock is a single `asyncio.Lock`, and it is not free. Measured on one
-interpreter, three runs of each configuration with the median taken by hand
-(`perf_suite` runs each workload once per invocation — it cannot produce a
-median itself):
+**Entity creation is slower than v1.4.0.** Median of three runs on one machine and interpreter: 2,000 lines **1.4× slower**, the 10,000-line roundtrip **2.3× slower**. Attributed — setting `EZDXF_CALL_TIMEOUT=0` returns creation to v1.4.0's numbers. The cost is the per-call `asyncio.wait_for` wrapped around every headless call so one hung call can no longer wedge a server whose document lock is a single `asyncio.Lock`. Deliberate trade, documented knob, on the 1.6 roadmap. The premium quality pass went the other way — **3.7× faster**.
-| Workload | `EZDXF_CALL_TIMEOUT=0` | default (120 s) | Cost |
-|---|---:|---:|---:|
-| 2,000 lines | 243.7 ms | 294.3 ms | +20.8% |
-| 10,000-line roundtrip | 1,709.6 ms | 2,049.2 ms | +19.9% |
+**Wave A shipped 13 tools of a planned 39.** Every cut is backed by a measurement. The REGION and 2D-boolean family went because `add_region()` produces a REGION with **zero ACIS bytes**, and the `greiner_hormann` substitute loses **28.2%** of the area on a square with one semicircular edge.
-v1.5.0 paid **28.6%** on the first workload; v1.5.1 rebuilt the wrapper around a
-single `asyncio.timeout_at` instead of two `asyncio.wait_for`s — `wait_for`
-wraps its awaitable in a Task, so the old shape created two extra Tasks and two
-timer handles on *every* call. That recovered about a third of the overhead and
-fixed a latent double-release, but it did not close the gap: the remaining cost
-is the Task the abandon-on-timeout design genuinely needs. The knob is
-documented rather than hidden, and the item stays open.
+**`system_run_command` / `system_run_lisp` are a guardrail, not a security boundary** — the rejection message says so in those words. A 36-verb denylist refuses the obvious cases, but AutoCAD accepts hundreds of commands and `DANGEROUS_COMMANDS_ENABLED=true` switches it off entirely.
-> These figures are hand-collected across separate single-shot runs and have no
-> published artifact; `benchmarks/results/published/perf-ezdxf.json` records one
-> default-configuration run only.
+**Path validation is per-tool, and unscoped until you scope it.** With `ALLOWED_PATHS` empty — the default — the only positive bound is a ten-entry system-directory denylist that does not include `C:/Users`, `/home`, `/root` or `/var`. **Set `ALLOWED_PATHS`.**
-> The README on `main` through the v1.4 era printed *slower* numbers than the table above — 0.64 s and 13.9 s for the same two workloads. That looks like a 2–6× win and is not one: the old report was recorded on CPython 3.14 and this one on 3.11.15. Almost entirely the interpreter, not code — run on one interpreter, this release is *slower* than v1.4.0 on both workloads, not faster. Comparing the two published files directly is the mistake this paragraph exists to stop.
-
-**Wave A shipped 13 tools of a planned ~39.** Every cut is backed by a measurement. The REGION and 2D-boolean family went because `add_region()` produces a REGION with **zero ACIS bytes**, and the substitute, `greiner_hormann`, takes and returns flat vertex lists, so a bulged edge goes in as its chord: **28.2%** of the area on a square with one semicircular edge — shipping it would have re-created the exact class of silent error this release's honesty pass exists to delete. Of the planned measurement family only `analysis_measure_entity` shipped — measuring a drawn entity by handle, which neither backend could do — and the centroid and moment-of-inertia tools were cut with nothing replacing them. Of the eight `analysis_*` tools that already existed, the two tagged `measure` both measured points the caller typed in.
-
-**`system_run_command` / `system_run_lisp` are a guardrail, not a security boundary** — the rejection message clients receive says so in those words. A 36-verb command denylist and a 24-pattern AutoLISP denylist refuse the obviously destructive cases, but AutoCAD accepts hundreds of commands and any loaded ARX/LISP adds more, so the list cannot be complete, and `DANGEROUS_COMMANDS_ENABLED=true` switches both off entirely.
-
-**Path validation is per-tool, and unscoped until you scope it.** Nine tools call `validate_path`; nothing in the middleware enforces it server-wide. With `ALLOWED_PATHS` empty — the default — the only positive bound is a ten-entry system-directory denylist that does not include `C:/Users`, `/home`, `/root` or `/var`. **Set `ALLOWED_PATHS`.** It is the setting that actually scopes the filesystem.
-
-**Non-AutoCAD ProgIDs are unverified.** `CAD_PROGID` changes which COM application the backend attaches to — the configured ProgID is used at both `GetActiveObject` and `Dispatch`, and an unrecognised one fails loudly rather than falling back to AutoCAD. Nothing has been tested against BricsCAD, ZWCAD or GstarCAD, the connection included: no running seat of any of them was ever attached to. They are listed in `.env.example` commented out and marked UNVERIFIED.
+**Non-AutoCAD ProgIDs are unverified.** `CAD_PROGID` changes which COM application the backend attaches to; nothing beyond the connection has been tested against BricsCAD, ZWCAD or GstarCAD.
## Configuration
-Nothing here loads a `.env` file — there is no dotenv dependency. Export these, or set them in your MCP client's `env` block. `.env.example` is documentation, and it is not the full list.
+Nothing loads a `.env` file — export these, or set them in your MCP client's `env` block.