157 lines
7.8 KiB
Markdown
157 lines
7.8 KiB
Markdown
---
|
||
name: autocad-mcp
|
||
description: |
|
||
Automate AutoCAD drawing operations through AutoCAD MCP Pro server (FastMCP 3.0).
|
||
86 tools for drawings, entities, layers, blocks, dimensions, analysis, batch ops,
|
||
templates, and validation. Dual backends: COM (live AutoCAD) and ezdxf (headless DXF).
|
||
|
||
Trigger when: (1) User mentions AutoCAD, DXF, DWG, or CAD drawings,
|
||
(2) User wants to create/modify engineering drawings programmatically,
|
||
(3) Working with tools prefixed drawing_, entity_, layer_, block_, dimension_,
|
||
analysis_, view_, system_, template_, or validation_,
|
||
(4) User asks about CAD automation, drafting workflows, or MCP server setup.
|
||
---
|
||
|
||
# AutoCAD MCP Pro
|
||
|
||
## Contents
|
||
|
||
- [Quick Start](#quick-start)
|
||
- [Backend Selection](#backend-selection)
|
||
- [Key Concepts](#key-concepts)
|
||
- [Tool Groups](#tool-groups)
|
||
- [Common Workflows](#common-workflows)
|
||
- [Security Rules](#security-rules)
|
||
- [Architecture](#architecture)
|
||
- [Troubleshooting](#troubleshooting)
|
||
- [Examples](#examples)
|
||
|
||
## Quick Start
|
||
|
||
Standard workflow for any drawing task:
|
||
|
||
```
|
||
1. drawing_new() # or drawing_open(path)
|
||
2. layer_create(name, color, linetype) # set up layers
|
||
3. entity_create_*(...) # draw geometry
|
||
4. dimension_*(...) # add dimensions
|
||
5. analysis_entity_stats() # verify drawing
|
||
6. drawing_save() # persist changes
|
||
```
|
||
|
||
Use `transaction_begin()` before complex operations. If something goes wrong, `transaction_rollback()` reverts all changes since begin.
|
||
|
||
For batch operations, use `entity_batch_create(entities)` with a list of entity definitions — handles are returned for each created entity.
|
||
|
||
## Backend Selection
|
||
|
||
| Environment Variable | Behavior |
|
||
|---------------------|----------|
|
||
| `AUTOCAD_MCP_BACKEND=auto` | Try COM first, fall back to ezdxf (default) |
|
||
| `AUTOCAD_MCP_BACKEND=com` | Force COM — requires running AutoCAD on Windows |
|
||
| `AUTOCAD_MCP_BACKEND=ezdxf` | Force ezdxf — headless DXF ops, no AutoCAD needed |
|
||
|
||
COM-only features: `system_run_command`, `system_run_lisp`, `view_zoom_extents/window` (view ops are no-ops in ezdxf). Screenshots: COM uses Win32 capture, ezdxf uses matplotlib render.
|
||
|
||
## Key Concepts
|
||
|
||
**Entity handles**: Hex strings (e.g. `"1A2B"`) returned by all create/copy operations. Required for modify/query operations (`entity_get`, `entity_move`, `entity_delete`, etc.).
|
||
|
||
**Coordinates**: Drawing units (mm default). Angles in degrees, counter-clockwise from X axis.
|
||
|
||
**ACI colors**: 1–255 = specific colors, 256 = ByLayer, 0 = ByBlock. Common: 1=red, 2=yellow, 3=green, 4=cyan, 5=blue, 6=magenta, 7=white.
|
||
|
||
**Transactions**: `transaction_begin` → operations → `transaction_commit` or `transaction_rollback`. ezdxf uses full DXF snapshots; COM uses native undo marks.
|
||
|
||
## Tool Groups
|
||
|
||
| Group | Count | Key Tools | Details |
|
||
|-------|-------|-----------|---------|
|
||
| Drawing Management | 11 | `drawing_new`, `drawing_open`, `drawing_save`, `drawing_export_*` | [tools-drawing.md](references/tools-drawing.md) |
|
||
| Entity Creation | 13 | `entity_create_line/circle/arc/polyline/text/hatch/...` | [tools-entity-creation.md](references/tools-entity-creation.md) |
|
||
| Entity Modification | 13 | `entity_move/copy/rotate/scale/mirror/offset/delete/...` | [tools-entity-modification.md](references/tools-entity-modification.md) |
|
||
| Dimensions | 5 | `dimension_linear/aligned/angular/radius/diameter` | [tools-dimensions.md](references/tools-dimensions.md) |
|
||
| Layer Management | 12 | `layer_create/delete/freeze/thaw/lock/unlock/isolate/...` | [tools-layers.md](references/tools-layers.md) |
|
||
| Block Operations | 7 | `block_insert/explode/create_from_entities/attributes/...` | [tools-blocks.md](references/tools-blocks.md) |
|
||
| Analysis | 9 | `analysis_entity_stats/find_in_region/measure_*/bounding_box` | [tools-analysis.md](references/tools-analysis.md) |
|
||
| Batch & Templates | 4 | `entity_batch_create/modify`, `template_apply_layers/list` | [tools-batch-template.md](references/tools-batch-template.md) |
|
||
| Validation | 1 | `validation_check` | [tools-batch-template.md](references/tools-batch-template.md) |
|
||
| View & Screenshot | 5 | `view_zoom_extents/window/screenshot/zoom_and_screenshot` | [tools-view-system.md](references/tools-view-system.md) |
|
||
| Transactions | 3 | `transaction_begin/commit/rollback` | [tools-view-system.md](references/tools-view-system.md) |
|
||
| System | 6 | `system_status/get_variable/run_command/run_lisp/about` | [tools-view-system.md](references/tools-view-system.md) |
|
||
|
||
**Resources** (6): `autocad://drawing`, `autocad://layers`, `autocad://blocks`, `autocad://stats`, `autocad://status`, `autocad://entities/{layer_name}`
|
||
|
||
**Prompt templates** (5): `prompt_floor_plan`, `prompt_pid_diagram`, `prompt_electrical_schematic`, `prompt_mechanical_drawing`, `prompt_quick_drawing`
|
||
|
||
## Common Workflows
|
||
|
||
**New drawing from scratch**: Set up layers first, then draw entities, add dimensions, save.
|
||
See [workflows.md](references/workflows.md) for step-by-step checklists.
|
||
|
||
**Edit existing DXF**: `drawing_open` → `entity_list` to find entities → modify/delete → save.
|
||
|
||
**Batch operations**: `entity_batch_create([{type:"line", ...}, {type:"circle", ...}])` — single call, multiple entities.
|
||
|
||
**Template-based**: `template_apply_layers("architectural")` creates standard layer sets, then add content.
|
||
|
||
**Quality check**: `validation_check(["empty_layers", "zero_length", "duplicate_entities"])` reports issues.
|
||
|
||
## Security Rules
|
||
|
||
All file paths pass through `validate_path()`:
|
||
- Path traversal blocked (`../` patterns rejected)
|
||
- `ALLOWED_PATHS` env restricts accessible directories
|
||
- Write operations require `allow_write=True`
|
||
|
||
Commands pass through `sanitize_command()`:
|
||
- Dangerous patterns blocked: ERASE ALL, DELETE, PURGE, QUIT
|
||
- LISP sanitized: `startapp`, `vl-file-delete`, `dos_*` rejected
|
||
- Override: `DANGEROUS_COMMANDS_ENABLED=true`
|
||
|
||
Details: [security.md](references/security.md)
|
||
|
||
## Architecture
|
||
|
||
```
|
||
server.py FastMCP 3.0 server (86 tools, 6 resources, 5 prompts)
|
||
├── config.py Centralized pydantic-settings configuration
|
||
├── security.py Path validation + command sanitization
|
||
└── backends/
|
||
├── base.py AutoCADBackend ABC + data models
|
||
├── ezdxf_backend.py Headless DXF via ezdxf (async via _async wrapper)
|
||
└── com_backend.py Live AutoCAD via pywin32 COM (STA single-thread)
|
||
```
|
||
|
||
Middleware stack: ErrorHandling → AuditLog → Timing → Logging
|
||
|
||
Adding a new tool: (1) abstract method in `base.py` → (2) implement in `ezdxf_backend.py` → (3) implement in `com_backend.py` → (4) register in `server.py` with `@mcp.tool` → (5) test
|
||
|
||
Details: [architecture.md](references/architecture.md)
|
||
|
||
## Troubleshooting
|
||
|
||
| Error | Solution |
|
||
|-------|----------|
|
||
| "Backend unavailable" | Call `drawing_new()` or `drawing_open(path)` first |
|
||
| "Entity handle not found" | Use `entity_list()` to get valid handles |
|
||
| "Layer not found" | `layer_list()` to see existing, `layer_create()` to add |
|
||
| "Path validation failed" | Use absolute paths within `ALLOWED_PATHS` |
|
||
| "Command rejected" | Check `DANGEROUS_COMMANDS_ENABLED` setting |
|
||
| "COM backend failed" | Verify AutoCAD is running, or switch to ezdxf |
|
||
| "View ops are no-ops" | View/zoom only work with COM backend |
|
||
|
||
Full list: [troubleshooting.md](references/troubleshooting.md)
|
||
|
||
## Examples
|
||
|
||
- [Basic drawing workflow](examples/basic-workflow.md) — Room with walls, door, dimensions
|
||
- [Floor plan](examples/floor-plan.md) — Multi-room apartment layout
|
||
- [Mechanical part](examples/mechanical-part.md) — Flange with bolt pattern
|
||
|
||
## Utility Scripts
|
||
|
||
**Setup check**: `python scripts/check_setup.py` — Verify dependencies and configuration
|
||
|
||
**Drawing validation**: `python scripts/validate_drawing.py` — Check for common drawing issues
|