acad-mcp 0.2.0__tar.gz

acad_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: acad-mcp
+Version: 0.2.0
+Summary: MCP server that lets Claude (and other MCP clients) drive a running AutoCAD on Windows via COM
+Keywords: mcp,autocad,cad,claude,model-context-protocol,dwg,dxf
+Author: thurdevv
+Author-email: thurdevv <demonrspy@gmail.com>
+License-Expression: MIT
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: ezdxf>=1.4.5
+Requires-Dist: mcp[cli]>=2.3.0
+Requires-Dist: opencv-python-headless>=5.0.0.93
+Requires-Dist: pillow>=13.0.0
+Requires-Dist: pywin32>=312
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/thurdevv/acad-mcp
+Project-URL: Issues, https://github.com/thurdevv/acad-mcp/issues
+Project-URL: Changelog, https://github.com/thurdevv/acad-mcp/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# acad-mcp — let Claude drive AutoCAD
+
+<!-- mcp-name: io.github.thurdevv/acad-mcp -->
+
+**[Português](README.pt-BR.md)**
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude (and other MCP clients) **draw, edit, read and
+check drawings in the AutoCAD running on your Windows PC** — and process whole folders of DWGs without opening them.
+
+![demo](docs/demo.gif)
+
+- **61 tools + a guided prompt**, every write is **one undo step** (Ctrl+Z).
+- **Fast on large drawings**: reads run as LISP inside AutoCAD — 50,000 entities in ~15 s (vs ~22 min over COM).
+- **Batch**: run a routine or a layer standard over a folder with AutoCAD's console engine (no window, in
+  parallel). **Originals are never modified** — copies go to an output folder.
+- **Routines without AI**: built-in LISP routines (find/replace, fill title blocks, export attributes, count
+  blocks, layer standard from CSV, purge/audit, plot PDF) that a person can also type as `MCP_...` commands.
+- **Recreate drawings**: import vector PDFs with real measurements, DXF/DWG, or trace scans/photos into lines;
+  a coordinate grid on screenshots lets the model compare and fix.
+- **English and Portuguese** (`ACAD_MCP_LANG=pt`).
+
+> AutoCAD is a registered trademark of Autodesk, Inc. This project is not affiliated with or endorsed by Autodesk.
+
+## Requirements
+
+- **Windows** and the **full AutoCAD** (uses COM/ActiveX). **AutoCAD LT is not supported** (no COM, no console).
+  Tested on **AutoCAD 2027**; earlier versions (2021+) are likely to work but are not verified.
+- [uv](https://docs.astral.sh/uv/) (it installs Python 3.13 for you).
+- Linux/macOS: not possible — AutoCAD's automation only exists on Windows.
+
+## Install
+
+### Claude Desktop — extension (easiest)
+Download `acad-mcp-<version>.mcpb` from the Releases page and open it with Claude Desktop
+(Settings → Extensions). Options: language, read-only, LISP on/off, auto-restore window.
+
+### Claude Desktop — config file
+```json
+{
+  "mcpServers": {
+    "acad": { "command": "uvx", "args": ["acad-mcp"], "env": { "ACAD_MCP_LANG": "en" } }
+  }
+}
+```
+Edit the config **with Claude fully closed** (tray icon → Quit): Claude rewrites the file from memory when it
+quits, which would drop your change.
+
+### One-click install from this folder (Windows)
+Double-click **`INSTALAR.bat`**: it checks AutoCAD, asks the language, closes Claude (after asking), installs uv
+if missing, installs Python and the dependencies, configures Claude (with a backup), runs a self-test and reopens
+Claude. A `.venv` copied from another PC is detected and rebuilt.
+
+### Claude Code
+```bash
+claude mcp add --scope user acad -- uvx acad-mcp
+```
+
+### Other MCP clients
+Any client that runs local stdio servers: command `uvx`, args `["acad-mcp"]`. For HTTP: `acad-mcp --http`
+(listens on 127.0.0.1:8765/mcp only).
+
+## Use
+
+Open AutoCAD and keep its window **not minimized** (it may stay behind other windows). Then ask, e.g.:
+
+- *"Create layers WALL (red, 0.35) and AXIS (green, CENTER) and draw a 4 × 3 m room with axes and dimensions."*
+- *"Count the blocks and export their attributes to a CSV on my Desktop."*
+- *"Check this drawing against the `example` standard and fix what you can."*
+- *"In C:\Projects\Sheets, replace 'REV A' with 'REV B' in every drawing."* (batch, originals untouched)
+- *"Recreate the attached part directly in AutoCAD with dimensions, then show me."*
+
+## Tools
+
+| Group | Tools |
+|---|---|
+| Document | `status`, `list_documents`, `new_drawing`, `open_drawing`, `activate_drawing`, `save_drawing`, `close_drawing` |
+| Read | `drawing_info`, `list_layers`, `list_styles`, `list_blocks`, `query_entities`, `get_entity`, `get_selection` |
+| View | `get_view_image` (screenshot, optional coordinate grid), `zoom_view` |
+| Draw | `draw_line`, `draw_polyline`, `draw_rectangle`, `draw_circle`, `draw_arc`, `draw_text`, `draw_dimension`, `draw_hatch`, `draw_leader`, `draw_table`, `insert_block`, `create_block`, `draw_batch` |
+| Edit | `transform_entities`, `array_entities`, `offset_entity`, `erase_entities`, `set_entity_properties`, `edit_text`, `set_block_attributes`, `modify_geometry`, `explode_entities` |
+| Layers & styles | `manage_layer`, `manage_text_style`, `set_current`, `load_linetype` |
+| Data | `quantities`, `block_report` (CSV) |
+| Standards | `list_standards`, `check_standards`, `apply_standards`, `purge_and_audit` |
+| Files & recreate | `import_file` (DXF, DWG, vector PDF, image), `list_received_files`, `trace_image` |
+| Routines & batch | `list_routines`, `run_routine`, `save_routine`, `export_routines_for_autocad`, `batch_process`, `batch_status` |
+| Escape hatches | `run_command`, `run_lisp`, `undo`, `cancel_command` |
+
+Prompt: `recreate_drawing` — measurements first, ask for what is missing, draw, compare, fix.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ACAD_MCP_LANG` | `en` | `pt` for Portuguese descriptions and messages |
+| `ACAD_MCP_READ_ONLY` | `0` | `1` = only reading tools are registered |
+| `ACAD_MCP_ALLOW_LISP` | `1` | `0` disables `run_lisp`, routines and batch routines |
+| `ACAD_MCP_ALLOW_COMMANDS` | `1` | `0` disables `run_command` |
+| `ACAD_MCP_AUTO_RESTORE` | `0` | `1` restores a minimized AutoCAD when needed (AutoCAD may grab focus) |
+| `ACAD_MCP_COMMAND_TIMEOUT` | `30` | seconds before a command waiting for input is cancelled |
+| `ACAD_MCP_FAST_THRESHOLD` | `300` | entity count above which reads use in-process LISP |
+| `ACAD_MCP_STANDARDS_DIR` | `Documents\AutoCAD MCP\standards` | your JSON standards |
+| `ACAD_MCP_ROUTINES_DIR` | `Documents\AutoCAD MCP\routines` | your saved routines |
+
+## How it works (and what was measured)
+
+- One COM thread talks to AutoCAD; a **COM message filter** retries calls while AutoCAD is busy, so a tool is
+  never re-run (re-running duplicated saves during development).
+- Commands/LISP go through `SendCommand` with a **watchdog**: if a command waits for input, ESC is sent to the
+  drawing area (ESC to the main window does not cancel). The command line rejects expressions over ~1–2 k
+  characters, so long LISP is written to a temp file and read+evaluated (reading text does not trigger
+  SECURELOAD, unlike `(load)`).
+- With the window **minimized**, `SendCommand` gets queued and AutoCAD freezes when restored, so commands, LISP and
+  screenshots refuse to run minimized (unless auto-restore is on). Direct drawing/editing works minimized.
+- COM selection sets leave internal "OLEAPPLICATION" undo records; `undo` skips them.
+- **Batch console engine** (`accoreconsole.exe`): pure AutoLISP and `vlax-curve-*` work, **`vla-*` does not**;
+  plotting to PDF and saving work. Measured: 3 files in ~1.5 s with 3 workers. Use `engine="gui"` for
+  `vla-*` routines and JSON standards.
+- **PDF import**: `-PDFIMPORT` runs without a dialog. PDFs plotted by AutoCAD came back at real size; PDFs
+  without CAD scale come in inches (1 pt = 1/72") — rescale and check one known measurement.
+- **trace_image** is a draft: straight strokes within ~1 % on clean drawings in tests; curves and text are not
+  traced.
+
+## Safety
+
+- Never writes over an existing file without `overwrite=true`; closing with unsaved changes needs
+  `discard_changes=true`; batch only touches copies.
+- `run_command` blocks SHELL, START, NETLOAD, APPLOAD, SCRIPT, QUIT and similar; file dialogs are off.
+- `run_lisp` blocks `startapp`, file deletion/renaming, registry writes, etc. **It is not a sandbox** — LISP can
+  do a lot. Disable it with `ACAD_MCP_ALLOW_LISP=0` or use read-only mode.
+- HTTP mode listens on localhost only. **Never expose it publicly without authentication**: whoever reaches it
+  controls your AutoCAD. See [SECURITY.md](SECURITY.md).
+
+## ChatGPT
+
+ChatGPT only talks to remote MCP servers. See [docs/chatgpt.md](docs/chatgpt.md) (OpenAI Secure MCP Tunnel; not
+fully verified yet).
+
+## Development
+
+```bash
+uv sync
+uv run pytest -m "not live"     # no AutoCAD needed
+uv run pytest                   # also the live tests: AutoCAD open, window not minimized
+uv build                        # wheel + sdist
+uv run python scripts/build_mcpb.py   # Claude Desktop extension (needs Node.js)
+```
+The live tests create their own drawings and close them without saving; they never touch yours.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

acad_mcp-0.2.0/README.md

@@ -0,0 +1,151 @@
+# acad-mcp — let Claude drive AutoCAD
+
+<!-- mcp-name: io.github.thurdevv/acad-mcp -->
+
+**[Português](README.pt-BR.md)**
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude (and other MCP clients) **draw, edit, read and
+check drawings in the AutoCAD running on your Windows PC** — and process whole folders of DWGs without opening them.
+
+![demo](docs/demo.gif)
+
+- **61 tools + a guided prompt**, every write is **one undo step** (Ctrl+Z).
+- **Fast on large drawings**: reads run as LISP inside AutoCAD — 50,000 entities in ~15 s (vs ~22 min over COM).
+- **Batch**: run a routine or a layer standard over a folder with AutoCAD's console engine (no window, in
+  parallel). **Originals are never modified** — copies go to an output folder.
+- **Routines without AI**: built-in LISP routines (find/replace, fill title blocks, export attributes, count
+  blocks, layer standard from CSV, purge/audit, plot PDF) that a person can also type as `MCP_...` commands.
+- **Recreate drawings**: import vector PDFs with real measurements, DXF/DWG, or trace scans/photos into lines;
+  a coordinate grid on screenshots lets the model compare and fix.
+- **English and Portuguese** (`ACAD_MCP_LANG=pt`).
+
+> AutoCAD is a registered trademark of Autodesk, Inc. This project is not affiliated with or endorsed by Autodesk.
+
+## Requirements
+
+- **Windows** and the **full AutoCAD** (uses COM/ActiveX). **AutoCAD LT is not supported** (no COM, no console).
+  Tested on **AutoCAD 2027**; earlier versions (2021+) are likely to work but are not verified.
+- [uv](https://docs.astral.sh/uv/) (it installs Python 3.13 for you).
+- Linux/macOS: not possible — AutoCAD's automation only exists on Windows.
+
+## Install
+
+### Claude Desktop — extension (easiest)
+Download `acad-mcp-<version>.mcpb` from the Releases page and open it with Claude Desktop
+(Settings → Extensions). Options: language, read-only, LISP on/off, auto-restore window.
+
+### Claude Desktop — config file
+```json
+{
+  "mcpServers": {
+    "acad": { "command": "uvx", "args": ["acad-mcp"], "env": { "ACAD_MCP_LANG": "en" } }
+  }
+}
+```
+Edit the config **with Claude fully closed** (tray icon → Quit): Claude rewrites the file from memory when it
+quits, which would drop your change.
+
+### One-click install from this folder (Windows)
+Double-click **`INSTALAR.bat`**: it checks AutoCAD, asks the language, closes Claude (after asking), installs uv
+if missing, installs Python and the dependencies, configures Claude (with a backup), runs a self-test and reopens
+Claude. A `.venv` copied from another PC is detected and rebuilt.
+
+### Claude Code
+```bash
+claude mcp add --scope user acad -- uvx acad-mcp
+```
+
+### Other MCP clients
+Any client that runs local stdio servers: command `uvx`, args `["acad-mcp"]`. For HTTP: `acad-mcp --http`
+(listens on 127.0.0.1:8765/mcp only).
+
+## Use
+
+Open AutoCAD and keep its window **not minimized** (it may stay behind other windows). Then ask, e.g.:
+
+- *"Create layers WALL (red, 0.35) and AXIS (green, CENTER) and draw a 4 × 3 m room with axes and dimensions."*
+- *"Count the blocks and export their attributes to a CSV on my Desktop."*
+- *"Check this drawing against the `example` standard and fix what you can."*
+- *"In C:\Projects\Sheets, replace 'REV A' with 'REV B' in every drawing."* (batch, originals untouched)
+- *"Recreate the attached part directly in AutoCAD with dimensions, then show me."*
+
+## Tools
+
+| Group | Tools |
+|---|---|
+| Document | `status`, `list_documents`, `new_drawing`, `open_drawing`, `activate_drawing`, `save_drawing`, `close_drawing` |
+| Read | `drawing_info`, `list_layers`, `list_styles`, `list_blocks`, `query_entities`, `get_entity`, `get_selection` |
+| View | `get_view_image` (screenshot, optional coordinate grid), `zoom_view` |
+| Draw | `draw_line`, `draw_polyline`, `draw_rectangle`, `draw_circle`, `draw_arc`, `draw_text`, `draw_dimension`, `draw_hatch`, `draw_leader`, `draw_table`, `insert_block`, `create_block`, `draw_batch` |
+| Edit | `transform_entities`, `array_entities`, `offset_entity`, `erase_entities`, `set_entity_properties`, `edit_text`, `set_block_attributes`, `modify_geometry`, `explode_entities` |
+| Layers & styles | `manage_layer`, `manage_text_style`, `set_current`, `load_linetype` |
+| Data | `quantities`, `block_report` (CSV) |
+| Standards | `list_standards`, `check_standards`, `apply_standards`, `purge_and_audit` |
+| Files & recreate | `import_file` (DXF, DWG, vector PDF, image), `list_received_files`, `trace_image` |
+| Routines & batch | `list_routines`, `run_routine`, `save_routine`, `export_routines_for_autocad`, `batch_process`, `batch_status` |
+| Escape hatches | `run_command`, `run_lisp`, `undo`, `cancel_command` |
+
+Prompt: `recreate_drawing` — measurements first, ask for what is missing, draw, compare, fix.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ACAD_MCP_LANG` | `en` | `pt` for Portuguese descriptions and messages |
+| `ACAD_MCP_READ_ONLY` | `0` | `1` = only reading tools are registered |
+| `ACAD_MCP_ALLOW_LISP` | `1` | `0` disables `run_lisp`, routines and batch routines |
+| `ACAD_MCP_ALLOW_COMMANDS` | `1` | `0` disables `run_command` |
+| `ACAD_MCP_AUTO_RESTORE` | `0` | `1` restores a minimized AutoCAD when needed (AutoCAD may grab focus) |
+| `ACAD_MCP_COMMAND_TIMEOUT` | `30` | seconds before a command waiting for input is cancelled |
+| `ACAD_MCP_FAST_THRESHOLD` | `300` | entity count above which reads use in-process LISP |
+| `ACAD_MCP_STANDARDS_DIR` | `Documents\AutoCAD MCP\standards` | your JSON standards |
+| `ACAD_MCP_ROUTINES_DIR` | `Documents\AutoCAD MCP\routines` | your saved routines |
+
+## How it works (and what was measured)
+
+- One COM thread talks to AutoCAD; a **COM message filter** retries calls while AutoCAD is busy, so a tool is
+  never re-run (re-running duplicated saves during development).
+- Commands/LISP go through `SendCommand` with a **watchdog**: if a command waits for input, ESC is sent to the
+  drawing area (ESC to the main window does not cancel). The command line rejects expressions over ~1–2 k
+  characters, so long LISP is written to a temp file and read+evaluated (reading text does not trigger
+  SECURELOAD, unlike `(load)`).
+- With the window **minimized**, `SendCommand` gets queued and AutoCAD freezes when restored, so commands, LISP and
+  screenshots refuse to run minimized (unless auto-restore is on). Direct drawing/editing works minimized.
+- COM selection sets leave internal "OLEAPPLICATION" undo records; `undo` skips them.
+- **Batch console engine** (`accoreconsole.exe`): pure AutoLISP and `vlax-curve-*` work, **`vla-*` does not**;
+  plotting to PDF and saving work. Measured: 3 files in ~1.5 s with 3 workers. Use `engine="gui"` for
+  `vla-*` routines and JSON standards.
+- **PDF import**: `-PDFIMPORT` runs without a dialog. PDFs plotted by AutoCAD came back at real size; PDFs
+  without CAD scale come in inches (1 pt = 1/72") — rescale and check one known measurement.
+- **trace_image** is a draft: straight strokes within ~1 % on clean drawings in tests; curves and text are not
+  traced.
+
+## Safety
+
+- Never writes over an existing file without `overwrite=true`; closing with unsaved changes needs
+  `discard_changes=true`; batch only touches copies.
+- `run_command` blocks SHELL, START, NETLOAD, APPLOAD, SCRIPT, QUIT and similar; file dialogs are off.
+- `run_lisp` blocks `startapp`, file deletion/renaming, registry writes, etc. **It is not a sandbox** — LISP can
+  do a lot. Disable it with `ACAD_MCP_ALLOW_LISP=0` or use read-only mode.
+- HTTP mode listens on localhost only. **Never expose it publicly without authentication**: whoever reaches it
+  controls your AutoCAD. See [SECURITY.md](SECURITY.md).
+
+## ChatGPT
+
+ChatGPT only talks to remote MCP servers. See [docs/chatgpt.md](docs/chatgpt.md) (OpenAI Secure MCP Tunnel; not
+fully verified yet).
+
+## Development
+
+```bash
+uv sync
+uv run pytest -m "not live"     # no AutoCAD needed
+uv run pytest                   # also the live tests: AutoCAD open, window not minimized
+uv build                        # wheel + sdist
+uv run python scripts/build_mcpb.py   # Claude Desktop extension (needs Node.js)
+```
+The live tests create their own drawings and close them without saving; they never touch yours.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

acad_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "acad-mcp"
+version = "0.2.0"
+description = "MCP server that lets Claude (and other MCP clients) drive a running AutoCAD on Windows via COM"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+keywords = [
+    "mcp",
+    "autocad",
+    "cad",
+    "claude",
+    "model-context-protocol",
+    "dwg",
+    "dxf",
+]
+classifiers = [
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "ezdxf>=1.4.5",
+    "mcp[cli]>=2.3.0",
+    "opencv-python-headless>=5.0.0.93",
+    "pillow>=13.0.0",
+    "pywin32>=312",
+]
+
+[[project.authors]]
+name = "thurdevv"
+email = "demonrspy@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/thurdevv/acad-mcp"
+Issues = "https://github.com/thurdevv/acad-mcp/issues"
+Changelog = "https://github.com/thurdevv/acad-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+acad-mcp = "acad_mcp:main"
+
+[build-system]
+requires = ["uv_build>=0.13.8,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.2.0"]
+
+[tool.pytest.ini_options]
+markers = ["live: needs a running AutoCAD (window not minimized)"]
+testpaths = ["tests"]
+pythonpath = ["src"]

acad_mcp-0.2.0/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[project]
+name = "acad-mcp"
+version = "0.2.0"
+description = "MCP server that lets Claude (and other MCP clients) drive a running AutoCAD on Windows via COM"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [{ name = "thurdevv", email = "demonrspy@gmail.com" }]
+keywords = ["mcp", "autocad", "cad", "claude", "model-context-protocol", "dwg", "dxf"]
+classifiers = [
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "ezdxf>=1.4.5",
+    "mcp[cli]>=2.3.0",
+    "opencv-python-headless>=5.0.0.93",
+    "pillow>=13.0.0",
+    "pywin32>=312",
+]
+
+[project.urls]
+Homepage = "https://github.com/thurdevv/acad-mcp"
+Issues = "https://github.com/thurdevv/acad-mcp/issues"
+Changelog = "https://github.com/thurdevv/acad-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+acad-mcp = "acad_mcp:main"
+
+[build-system]
+requires = ["uv_build>=0.13.8,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+]
+
+[tool.pytest.ini_options]
+markers = ["live: needs a running AutoCAD (window not minimized)"]
+testpaths = ["tests"]
+pythonpath = ["src"]

acad_mcp-0.2.0/src/acad_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""MCP para controlar o AutoCAD pelo Claude ou ChatGPT."""
+
+
+def main() -> None:
+    from .server import main as _main
+
+    _main()

acad_mcp-0.2.0/src/acad_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""python -m acad_mcp  (also the entry point of the Claude Desktop extension)."""
+
+from acad_mcp import main
+
+if __name__ == "__main__":
+    main()

acad_mcp-0.2.0/src/acad_mcp/acad/__init__.py

@@ -0,0 +1 @@
+"""AutoCAD access through COM (single thread), commands, fast LISP reads and screen capture."""

acad_mcp-0.2.0/src/acad_mcp/acad/capture.py

@@ -0,0 +1,128 @@
+"""Image of the AutoCAD drawing area (PrintWindow; works even when the window is covered)."""
+
+from __future__ import annotations
+
+import ctypes
+import io
+import math
+from typing import Any
+
+import win32gui
+import win32ui
+from PIL import Image, ImageDraw, ImageFont
+
+from ..i18n import t as tr
+from . import commands
+from .errors import AcadError
+from .winutil import active_view_hwnd, is_minimized
+
+PW_RENDERFULLCONTENT = 2
+
+
+def capture_view_png(app: Any, max_width: int = 1600, crop_to_view: bool = True,
+                     grid: dict[str, Any] | None = None) -> tuple[bytes, dict]:
+    """grid = {"center": VIEWCTR, "view_height": VIEWSIZE} to overlay coordinates."""
+    main = int(app.HWND)
+    if is_minimized(main):
+        if not commands.AUTO_RESTORE:
+            raise AcadError(tr(
+                "The AutoCAD window is minimized, so no image can be captured. "
+                "Ask the user to restore it (it may stay behind other windows).",
+                "A janela do AutoCAD está minimizada; não dá para capturar a imagem. "
+                "Peça ao usuário para restaurar a janela (pode ficar atrás de outras).",
+            ))
+        commands.restore_behind(main)
+    l, t, r, b = win32gui.GetWindowRect(main)
+    w, h = r - l, b - t
+    hdc = win32gui.GetWindowDC(main)
+    mfc = win32ui.CreateDCFromHandle(hdc)
+    mem = mfc.CreateCompatibleDC()
+    bmp = win32ui.CreateBitmap()
+    try:
+        bmp.CreateCompatibleBitmap(mfc, w, h)
+        mem.SelectObject(bmp)
+        if not ctypes.windll.user32.PrintWindow(main, mem.GetSafeHdc(), PW_RENDERFULLCONTENT):
+            raise AcadError(tr("Could not capture the AutoCAD window (PrintWindow).",
+                               "Falha ao capturar a janela do AutoCAD (PrintWindow)."))
+        info = bmp.GetInfo()
+        img = Image.frombuffer(
+            "RGB", (info["bmWidth"], info["bmHeight"]), bmp.GetBitmapBits(True), "raw", "BGRX", 0, 1
+        )
+    finally:
+        win32gui.DeleteObject(bmp.GetHandle())
+        mem.DeleteDC()
+        mfc.DeleteDC()
+        win32gui.ReleaseDC(main, hdc)
+
+    meta: dict[str, Any] = {"window_size": [w, h]}
+    cropped = False
+    if crop_to_view:
+        view = active_view_hwnd(main)
+        if view:
+            vl, vt, vr, vb = win32gui.GetWindowRect(view)
+            box = (max(vl - l, 0), max(vt - t, 0), min(vr - l, w), min(vb - t, h))
+            if box[2] - box[0] > 50 and box[3] - box[1] > 50:
+                img = img.crop(box)
+                cropped = True
+                meta["cropped_to_drawing_area"] = True
+    if grid is not None and cropped:
+        meta["coordinates"] = draw_grid(img, grid["center"], grid["view_height"])
+    scale = 1.0
+    if img.width > max_width:
+        scale = max_width / img.width
+        img = img.resize((max_width, int(img.height * scale)), Image.LANCZOS)
+    if "coordinates" in meta:
+        c = meta["coordinates"]
+        c["units_per_pixel"] = c["units_per_pixel"] / scale
+    meta["image_size"] = [img.width, img.height]
+    buf = io.BytesIO()
+    img.save(buf, format="PNG", optimize=True)
+    return buf.getvalue(), meta
+
+
+def _nice_step(span: float, target_lines: int = 8) -> float:
+    raw = span / max(target_lines, 1)
+    mag = 10 ** math.floor(math.log10(raw)) if raw > 0 else 1
+    for m in (1, 2, 5, 10):
+        if raw <= m * mag:
+            return m * mag
+    return 10 * mag
+
+
+def draw_grid(img: Image.Image, center: list[float], view_height: float) -> dict[str, Any]:
+    """Draw a labelled coordinate grid on the image (plan view in WCS assumed).
+
+    Returns the pixel <-> drawing mapping so the model can read coordinates off the picture.
+    """
+    W, H = img.size
+    upp = view_height / H  # drawing units per pixel
+    x0 = center[0] - W / 2 * upp
+    y_top = center[1] + H / 2 * upp
+    step = _nice_step(max(W, H) * upp)
+    d = ImageDraw.Draw(img, "RGBA")
+    font = ImageFont.load_default()
+    color, label = (0, 200, 255, 90), (0, 220, 255, 255)
+
+    def fmt(v: float) -> str:
+        return f"{v:.0f}" if step >= 1 else f"{v:.3g}"
+
+    gx = math.ceil(x0 / step) * step
+    while gx <= x0 + W * upp:
+        px = (gx - x0) / upp
+        d.line([(px, 0), (px, H)], fill=color, width=1)
+        d.text((px + 2, H - 12), fmt(gx), fill=label, font=font)
+        gx += step
+    y_bottom = y_top - H * upp
+    gy = math.ceil(y_bottom / step) * step
+    while gy <= y_top:
+        py = (y_top - gy) / upp
+        d.line([(0, py), (W, py)], fill=color, width=1)
+        d.text((2, py + 2), fmt(gy), fill=label, font=font)
+        gy += step
+    return {
+        "grid_step": step,
+        "units_per_pixel": upp,
+        "top_left": [x0, y_top],
+        "how_to_read": tr("x = top_left.x + px * units_per_pixel; y = top_left.y - py * units_per_pixel",
+                          "x = top_left.x + px * units_per_pixel; y = top_left.y - py * units_per_pixel"),
+    }