autocad-mcp

# AutoCAD MCP Operations Skill Use this skill for shipped drawing operations performed by the `autocad-mcp` tool suite. Use `autolisp` for AutoLISP authoring. Do not use this skill to write AutoLISP routines or DCL dialogs. Arbitrary AutoLISP is a contributor/expert technique for designing future operations, not the normal drafter-facing path for supported read, write, or plot workflows. ## Invocation Modes The product has one canonical 51-tool contract through MCP and direct CLI, with an explicit Preview exposure boundary. - MCP: connect a supported local client to `autocad-mcp serve`, then call the tools directly. - CLI: run `autocad-mcp call <tool-name> <json-params>` for scripting, headless workflows, and repeatable automation. - Discovery: run `autocad-mcp list-tools` to print the current tool schemas. A Release binary is compiled without the `preview` feature. Its plain `serve` exposes all 51 certified tools and `serve --experimental` is an unknown option. A Preview-capable binary exposes exactly the 36 `readOnlyHint=true` tools through plain `serve`; `serve --experimental` explicitly opts into all 51, including the 15 state-changing tools. A visibly marked Preview MCPB supplies that flag in its manifest. Preview plain `list-tools` and `call` follow the same 36-tool boundary; use their `--experimental` option for full-surface discovery or direct dispatch. Release rejects every such experimental option. The flag changes MCP and direct-CLI tool exposure only. It never bypasses a tool's platform, AutoCAD, ARG/profile, capability, transaction, immutable-source snapshot, race, preservation, verification, or retry checks. Preview has no separate mutation-root restriction: every `drawing_path`, source path, and output path continues to follow the ordinary per-tool contract below. Preview build, package smoke, and clean-host results are development evidence, not Windows AutoCAD certification or Release evidence. Every `drawing_path` is an absolute local path. `plot_to_pdf.output` is an absolute local PDF path. Every top-level request object is closed: omit inapplicable optional inputs and do not send unknown keys or JSON `null` values. The `properties` maps for attachment and instance update are the only open nested objects; their keys are handled by exhaustive runtime property classifiers. ## Default Workflow Read before mutating or plotting. - Run `read_title_blocks` before `write_title_block`. - Run `list_layers` before layer mutations. - Run `list_xrefs` before targeted attachment operations when identity is unknown, then use the returned attachment handle. - Run `list_xref_instances` before targeted instance operations when identity is unknown, then use the returned instance handle. - Run `list_layouts` before `plot_to_pdf`. - Stop if current drawing state, identity, or destructive scope does not match the requested operation. - Do not guess title-block profiles, raw tags, layout names, layer identity, attachment identity, instance identity, unit assumptions, or output paths. ## Tool Contract | Tool | Required parameters | Optional parameters | Output summary | Platform / notes | |---|---|---|---|---| | `list_layers` | `drawing_path` | none | JSON array of expanded LayerRecord objects | DWG and DXF read on all supported hosts | | `get_layer` | `drawing_path` | `handle`, `name` | One expanded LayerRecord selected by handle or name | DWG and DXF read on all supported hosts; handle is preferred | | `create_layer` | `drawing_path`, `name` | `properties` | Layer create evidence with the persisted layer record | Native-DXF write on all supported hosts; Windows-only DWG write through accoreconsole | | `update_layer` | `drawing_path`, `properties` | `handle`, `name`, `expected_handle`, `expected_name` | Layer update evidence with the persisted layer record | Property mutation with stale-state guards | | `rename_layer` | `drawing_path`, `new_name` | `handle`, `name`, `expected_handle`, `expected_name` | Layer rename evidence with the persisted layer record | Rejects protected and xref-dependent layers | | `delete_layer` | `drawing_path` | `handle`, `name`, `expected_handle`, `expected_name` | Layer delete evidence | Rejects protected, current, dependent, content-bearing, and unverified-reference layers | | `list_xrefs` | `drawing_path` | none | JSON array of complete XrefAttachmentRecord objects | DWG and DXF read on all supported hosts; direct attachments only | | `get_xref` | `drawing_path` | `handle`, `name` | One complete XrefAttachmentRecord | DWG and DXF read on all supported hosts; handle is preferred | | `attach_xref` | `drawing_path`, `xref_path`, `reference_type` | `name`, `search_paths`, `placement`, `unit_assumptions` | Attached evidence with persisted attachment and initial instance | Windows with AutoCAD for DWG and DXF hosts; source files unchanged | | `update_xref` | `drawing_path`, `properties` | `handle`, `name`, `expected_handle`, `expected_name`, `layer_reconciliation`, `unit_assumptions`, `search_paths` | Updated evidence with persisted attachment and conditional reconciliation | Windows with AutoCAD for DWG and DXF hosts; source files unchanged | | `detach_xref` | `drawing_path` | `handle`, `name`, `expected_handle`, `expected_name`, `expected_instance_count`, `expected_instance_handles` | Detached evidence with pre-detach attachment and deleted instance handles | Destructive Windows AutoCAD mutation; source files unchanged | | `list_xref_instances` | `drawing_path` | `attachment_handle`, `attachment_name`, `owner_handle`, `owner_type`, `owner_name`, `layer_handle`, `layer_name`, `visibility` | JSON array of complete XrefInstanceRecord objects | DWG and DXF read on all supported hosts; exact filters only | | `get_xref_instance` | `drawing_path`, `handle` | none | One complete XrefInstanceRecord | DWG and DXF read on all supported hosts; persisted handle required | | `insert_xref_instance` | `drawing_path` | `attachment_handle`, `attachment_name`, `expected_attachment_handle`, `placement`, `unit_assumptions` | Inserted evidence with persisted instance | Windows with AutoCAD for DWG and DXF hosts; source files unchanged | | `update_xref_instance` | `drawing_path`, `handle`, `properties` | `expected_attachment_handle`, `expected_owner_handle` | Updated evidence with persisted instance | Windows with AutoCAD for DWG and DXF hosts; owner and attachment cannot change | | `delete_xref_instance` | `drawing_path`, `handle` | `expected_attachment_handle`, `expected_owner_handle` | Deleted evidence with the pre-delete instance | Destructive Windows AutoCAD mutation; attachment is retained | | `reload_xref` | `drawing_path` | `handle`, `name`, `expected_handle`, `expected_name`, `search_paths`, `layer_reconciliation`, `unit_assumptions` | Loaded evidence with persisted attachment and reconciliation | Windows with AutoCAD for DWG and DXF hosts; source files unchanged | | `unload_xref` | `drawing_path` | `handle`, `name`, `expected_handle`, `expected_name` | Unloaded evidence with persisted attachment | Windows with AutoCAD for DWG and DXF hosts; idempotent | | `bind_xref` | `drawing_path`, `symbol_strategy`, `dependency_strategy` | `handle`, `name`, `expected_handle`, `expected_name`, `expected_instance_count`, `expected_instance_handles`, `search_paths` | Bound block, instance, symbol, dependency, and overlay-exclusion mappings | Destructive Windows AutoCAD mutation; source files unchanged | | `resolve_xref_path` | `drawing_path` | `handle`, `name`, `search_paths` | One XREF path-resolution record | DWG and DXF read on all supported hosts; unresolved state is successful data | | `list_xref_dependencies` | `drawing_path` | `handle`, `name`, `search_paths`, `max_depth`, `max_nodes` | Dependency traversal envelope with limit evidence | DWG and DXF read on all supported hosts; nested identity uses attachment chains | | `get_drawing` | `drawing_path` | none | One closed drawing summary with availability-tagged saved-header model/paper geometry and current UCS, spaces, resource counts, and current settings | DWG only on all supported hosts; DXF is unavailable for the expanded read surface | | `list_entities` | `drawing_path` | `entity_types`, `layer`, `owner_handle`, `include_invisible`, `offset`, `limit` | Bounded entity envelope with post-filter total, tagged direct-owner context, reason-bearing bounds/detail, and proven INSERT dynamic linkage | DWG only on all supported hosts; exact filters; limit defaults to 200 and must be 1–1000 | | `get_entity` | `drawing_path`, `handle` | none | One common entity record with tagged direct-owner context, reason-bearing bounds/detail, and proven INSERT dynamic linkage | DWG only on all supported hosts; persisted handle required | | `list_block_definitions` | `drawing_path` | none | Deterministic array of expanded block-definition records | DWG only on all supported hosts; includes layout and XREF context | | `get_block_definition` | `drawing_path` | `handle`, `name` | One expanded block-definition record selected by handle or name | DWG only on all supported hosts; selectors are cross-checked when both are supplied | | `list_block_inserts` | `drawing_path` | none | Deterministic ordinary INSERT/MINSERT array with tagged direct-owner context and proven dynamic linkage | DWG only on all supported hosts; XREF instances are excluded | | `get_block_insert` | `drawing_path`, `handle` | none | One ordinary INSERT/MINSERT record with tagged direct-owner context, proven dynamic linkage, placement, and attributes | DWG only on all supported hosts; XREF instances are rejected | | `list_text` | `drawing_path` | `text_types`, `layer`, `owner_handle`, `owner_type`, `owner_name` | Deterministic array of handle-bearing TEXT and MTEXT records with tagged direct-owner context | DWG only on all supported hosts; exact filters and cross-checked owner selector union | | `get_text` | `drawing_path`, `handle` | none | One TEXT or MTEXT record with tagged direct-owner context | DWG only on all supported hosts; non-text handles are rejected | | `get_layout` | `drawing_path` | `handle`, `name` | One expanded layout record selected by handle or name | DWG only on all supported hosts; selectors are cross-checked when both are supplied | | `list_layout_viewports` | `drawing_path` | `layout_handle`, `layout_name` | Deterministic array of paper-space viewport records | DWG only on all supported hosts; optional exact layout scope | | `get_layout_viewport` | `drawing_path`, `handle` | none | One paper-space viewport record with resolved layout ownership | DWG only on all supported hosts; persisted viewport handle required | | `list_plot_settings` | `drawing_path` | none | Deterministic array of standalone named plot-setting records | DWG only on all supported hosts; embedded layout settings remain on layouts | | `get_plot_setting` | `drawing_path` | `handle`, `name` | One standalone named plot-setting record | DWG only on all supported hosts; selectors are cross-checked when both are supplied | | `list_linetypes` | `drawing_path` | none | Deterministic array of expanded linetype records | DWG only on all supported hosts | | `get_linetype` | `drawing_path` | `handle`, `name` | One expanded linetype record | DWG only on all supported hosts; selectors are cross-checked when both are supplied | | `list_text_styles` | `drawing_path` | none | Deterministic array of expanded text-style records | DWG only on all supported hosts | | `get_text_style` | `drawing_path` | `handle`, `name` | One expanded text-style record | DWG only on all supported hosts; selectors are cross-checked when both are supplied | | `list_dimension_styles` | `drawing_path` | none | Deterministic array of expanded dimension-style records | DWG only on all supported hosts | | `get_dimension_style` | `drawing_path` | `handle`, `name` | One expanded dimension-style record | DWG only on all supported hosts; selectors are cross-checked when both are supplied | | `list_named_views` | `drawing_path` | none | Deterministic array of named-view records | DWG only on all supported hosts | | `get_named_view` | `drawing_path` | `handle`, `name` | One named-view record | DWG only on all supported hosts; selectors are cross-checked when both are supplied | | `list_named_ucs` | `drawing_path` | none | Deterministic array of named UCS records | DWG only on all supported hosts | | `get_named_ucs` | `drawing_path` | `handle`, `name` | One named UCS record | DWG only on all supported hosts; selectors are cross-checked when both are supplied | | `list_blocks` | `drawing_path` | none | JSON array of user-defined block definitions | DWG and DXF read on all supported hosts | | `read_title_blocks` | `drawing_path` | `attribute_value_mode` | JSON array of attributed title-block candidates and values; duplicate tags are returned as arrays and reported as partial structured warnings | DWG and DXF read on all supported hosts; value mode is `split` by default or `arrays` | | `dump_text` | `drawing_path` | none | JSON array of TEXT and MTEXT content | DWG and DXF read on all supported hosts | | `write_title_block` | `drawing_path`, `fields` | none | Title-block write evidence with target and attribute counts | Release Windows-only DWG write through accoreconsole; Preview Windows-only AC1032 DWG write through the bounded acadrust preservation oracle; native-DXF write on all supported hosts | | `list_layouts` | `drawing_path` | none | JSON array of layouts and paper sizes | DWG and DXF read on all supported hosts; run before plotting | | `plot_to_pdf` | `drawing_path`, `layout`, `output` | none | Plot evidence with the output PDF path | Windows only; DWG only; existing file-plotter page setup required | ## CLI Examples Each CLI call is one shell-safe line with a single-quoted JSON object and uses the same parameter names as MCP. Examples that supply `unit_assumptions` assume the corresponding source and host roles are unitless or otherwise assumable. The block shows Release syntax. For a state-changing Preview call, insert `--experimental` after `call`; plain Preview calls expose only read-only tools, and Release rejects that flag. ```bash autocad-mcp call list_layers '{"drawing_path":"/abs/project/A101.dwg"}' autocad-mcp call get_layer '{"drawing_path":"/abs/project/A101.dwg","handle":"10"}' autocad-mcp call create_layer '{"drawing_path":"/abs/project/A101.dxf","name":"ANNO","properties":{"color_index":3,"locked":true}}' autocad-mcp call update_layer '{"drawing_path":"/abs/project/A101.dxf","handle":"10","expected_name":"ANNO","properties":{"off":true}}' autocad-mcp call rename_layer '{"drawing_path":"/abs/project/A101.dxf","handle":"10","expected_name":"ANNO","new_name":"NOTES"}' autocad-mcp call delete_layer '{"drawing_path":"/abs/project/A101.dxf","handle":"10","expected_name":"NOTES"}' autocad-mcp call list_xrefs '{"drawing_path":"/abs/project/A101.dwg"}' autocad-mcp call get_xref '{"drawing_path":"/abs/project/A101.dwg","handle":"2A"}' autocad-mcp call attach_xref '{"drawing_path":"C:/project/A101.dwg","xref_path":"../refs/site.dwg","name":"SITE","reference_type":"attachment","search_paths":["C:/project/shared"],"unit_assumptions":{"source_units":"millimeters","host_units":"millimeters"}}' autocad-mcp call update_xref '{"drawing_path":"C:/project/A101.dwg","handle":"2A","expected_handle":"2A","properties":{"xref_path":"../refs/site-r2.dwg"},"search_paths":["C:/project/shared"],"layer_reconciliation":{"mode":"drawing_policy","properties":[]},"unit_assumptions":{"source_units":"millimeters","host_units":"millimeters"}}' autocad-mcp call detach_xref '{"drawing_path":"C:/project/A101.dwg","handle":"2A","expected_handle":"2A","expected_instance_count":2,"expected_instance_handles":["40","41"]}'