# AutoCAD MCP Server

Máy chủ MCP cho **tự động hóa AutoCAD LT** và **tạo DXF headless**.

Hai backend, một API:

| Backend | Runtime | Cần AutoCAD? | Screenshot |
|---------|---------|-------------|------------|
| **File IPC** | Windows Python | Có — AutoCAD LT 2024+ (Windows) | Win32 PrintWindow |
| **ezdxf** | Mọi nền tảng | Không (headless) | matplotlib render |

Server cung cấp **8 công cụ chính** (`drawing`, `entity`, `layer`, `block`, `annotation`, `pid`, `view`, `system`) thông qua **MCP stdio transport**.  

Một **MCP client** (Claude Desktop, Claude Code, v.v.) có thể kết nối và điều khiển AutoCAD bằng **yêu cầu ngôn ngữ tự nhiên**.

---

# Prerequisites (Backend File IPC)

Yêu cầu:

- **Windows 10/11**  
  (Backend File IPC dùng Win32 API để gửi message tới cửa sổ mà không cần focus)

- **AutoCAD LT 2024 trở lên**  
  AutoLISP được hỗ trợ từ LT 2024 trên Windows.  

  ⚠ AutoCAD LT cho Mac **không hỗ trợ AutoLISP**.

- **Python 3.10+**  
  (Python chạy native trên Windows — **không dùng WSL Python**)

- **uv package manager**

Cài đặt:

https://docs.astral.sh/uv/getting-started/installation/

---

💡 Backend **ezdxf headless** chạy được trên:

- Linux
- macOS
- WSL

và **không cần AutoCAD**, chỉ dùng để tạo file DXF offline.

---

# Quick Start

## 1. Clone và cài đặt

```powershell
git clone https://github.com/ks40-academy/autocad-mcp.git
cd autocad-mcp
uv sync
```

---

# 2. Load LISP dispatcher trong AutoCAD LT

Mở AutoCAD LT và load file:

`mcp_dispatch.lsp`

bằng lệnh **APPLOAD**

Các bước:

1. Gõ `APPLOAD` trong command line
2. Chọn file

```
<repo>/lisp-code/mcp_dispatch.lsp
```

3. Nhấn **Load**

Nếu thành công sẽ thấy:

```
=== MCP Dispatch v3.1 loaded ===
Ready for commands via (c:mcp-dispatch)
```

---

💡 Mẹo

Thêm file này vào **Startup Suite** trong APPLOAD để AutoCAD tự load khi mở bản vẽ.

---

# 3. Cấu hình MCP client

Ví dụ cấu hình trong:

`claude_desktop_config.json`

```json
{
  "mcpServers": {
    "autocad-mcp": {
      "command": "C:\\path\\to\\autocad-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "autocad_mcp"],
      "env": { "AUTOCAD_MCP_BACKEND": "auto" }
    }
  }
}
```

### Lưu ý quan trọng

- `command` phải trỏ tới **Windows Python trong venv**
- Không dùng **WSL Python**

---

# Chạy từ WSL

Nếu MCP client chạy trong WSL (ví dụ Claude Code):

khởi động server thông qua `cmd.exe`

```json
{
  "mcpServers": {
    "autocad-mcp": {
      "type": "stdio",
      "command": "cmd.exe",
      "args": [
        "/d",
        "/s",
        "/c",
        "cd /d C:\\path\\to\\autocad-mcp && .venv\\Scripts\\python.exe -m autocad_mcp"
      ],
      "env": { "AUTOCAD_MCP_BACKEND": "auto" }
    }
  }
}
```

---

# 4. Kiểm tra hoạt động

Từ MCP client gọi:

```
system(operation="status")
```

Kết quả:

```
backend: "file_ipc"
```

nếu AutoCAD đang chạy

hoặc

```
backend: "ezdxf"
```

nếu chạy chế độ headless.

---

# Tools

## drawing — Quản lý file bản vẽ

| Operation | Mô tả | File IPC | ezdxf |
|-----------|------|----------|-------|
| create | Reset bản vẽ sạch | Yes | Yes |
| open | Mở bản vẽ | Yes | Yes (DXF) |
| info | Thông tin entity và layer | Yes | Yes |
| save | Lưu bản vẽ | Yes | Yes |
| save_as_dxf | Xuất DXF | Yes | Yes |
| plot_pdf | Xuất PDF | Yes | No |
| purge | Xóa đối tượng không dùng | Yes | Yes |
| get_variables | Lấy biến hệ thống | Yes | Yes |
| undo | Hoàn tác | Yes | No |
| redo | Làm lại | Yes | No |

---

# entity — Quản lý đối tượng

### Tạo

- create_line
- create_circle
- create_polyline
- create_rectangle
- create_arc
- create_ellipse
- create_mtext
- create_hatch

### Đọc

- list
- count
- get

### Chỉnh sửa

- copy
- move
- rotate
- scale
- mirror
- offset*
- array
- fillet*
- chamfer*
- erase

⚠ `offset`, `fillet`, `chamfer` chỉ dùng với File IPC.

---

# layer — Quản lý layer

- list
- create
- set_current
- set_properties
- freeze
- thaw
- lock
- unlock

---

# block — Thao tác block

| Operation | File IPC | ezdxf |
|----------|----------|-------|
| list | Yes | Yes |
| insert | Yes | Yes |
| insert_with_attributes | Yes | Yes |
| get_attributes | Yes | Yes |
| update_attribute | Yes | Yes |
| define | No | Yes |

---

# annotation — Chú thích

- create_text
- create_dimension_linear
- create_dimension_aligned
- create_dimension_angular
- create_dimension_radius
- create_leader

---

# pid — P&ID

Thư viện ký hiệu CTO.

Các lệnh:

- setup_layers
- insert_symbol
- list_symbols
- draw_process_line
- connect_equipment
- add_flow_arrow
- add_equipment_tag
- add_line_number
- insert_valve
- insert_instrument
- insert_pump
- insert_tank

---

⚠ Cần cài thư viện:

https://www.cadtoolsonline.com/

vào thư mục

```
C:\PIDv4-CTO\
```

---

# view — Viewport & Screenshot

| Operation | Mô tả |
|-----------|------|
| zoom_extents | Zoom toàn bộ |
| zoom_window | Zoom theo cửa sổ |
| get_screenshot | Chụp ảnh AutoCAD |

File IPC dùng:

```
PrintWindow (Win32)
```

Có thể chụp ngay cả khi AutoCAD bị minimize.

ezdxf dùng:

```
matplotlib render
```

---

# system — Quản lý server

- status
- health
- get_backend
- runtime
- init
- execute_lisp

---

## execute_lisp

Chạy AutoLISP bất kỳ:

Ví dụ

```
(+ 1 2)
```

Gửi:

```
data: {code: "(+ 1 2)"}
```

Biến server thành **nền tảng automation mở rộng**.

---

# Architecture

```
MCP Client (Claude)
        │
        │ stdio (JSON-RPC)
        ▼
Python MCP Server (autocad_mcp)
        │
        ├── File IPC Backend
        │       │
        │       └── C:/temp/*.json
        │               │
        │               ▼
        │        mcp_dispatch.lsp (AutoCAD)
        │
        └── ezdxf Backend
                │
                ▼
           in-memory DXF
```

File IPC gửi **keystrokes** tới AutoCAD bằng:

```
PostMessageW(WM_CHAR)
```

Ưu điểm:

- Không cướp focus cửa sổ
- Có thể làm việc ứng dụng khác song song.

---

# Environment Variables

| Variable | Default | Mô tả |
|---------|--------|------|
| AUTOCAD_MCP_BACKEND | auto | chọn backend |
| AUTOCAD_MCP_IPC_DIR | C:/temp | thư mục IPC |
| AUTOCAD_MCP_IPC_TIMEOUT | 10 | timeout |
| AUTOCAD_MCP_ONLY_TEXT | false | tắt screenshot |

---

⚠ Nếu đổi:

```
AUTOCAD_MCP_IPC_DIR
```

phải sửa luôn biến:

```
*mcp-ipc-dir*
```

trong file

```
mcp_dispatch.lsp
```

---

# Development

```powershell
uv sync
uv run pytest tests/ -v
```

---

# AutoCAD LT AutoLISP Compatibility

AutoLISP được thêm vào **AutoCAD LT 2024 (Windows)**.

| Hỗ trợ | Không hỗ trợ |
|------|-------------|
| .lsp | VLIDE |
| vl-* functions | vlax-* |
| File I/O | Express Tools |
| entget | 3D operations |
| selection sets | AutoLISP trên Mac |

---

# What's New v3.1

Các cập nhật chính:

- execute_lisp
- undo / redo
- open drawing
- create drawing reset
- save path
- get_variables fix
- polyline fix
- ESC prefix
- UTF8 fallback
- IPC timeout config
- thread-safe init

---

# License

MIT