autocad-mcp-pro/INSTALL.ru.md

# AutoCAD MCP Pro — как у нас развёрнут и как обновлять

Этот репозиторий — **зеркало** открытого проекта `U-C4N/Autocad-MCP` (PyPI-пакет
`autocad-mcp-pro`), которым мы пользуемся для черчения из агентов Hermes.

## 1. Источники версий и обновлений (единственные авторитетные)

| Что | Где смотреть |
|---|---|
| Исходный репозиторий | https://github.com/U-C4N/Autocad-MCP |
| Релизы и теги (что нового) | https://github.com/U-C4N/Autocad-MCP/releases — теги `v1.3.0 … v1.6.0` |
| Список изменений | `CHANGELOG.md` в корне репозитория (самый подробный источник) |
| PyPI-пакет и доступные версии | https://pypi.org/pypi/autocad-mcp-pro/json (поле `info.version`, `releases`) |
| Внутренняя версия сервера | MCP-вызов `system_about` / ответ `initialize` (`serverInfo.version`) |

**Текущий пин зеркала:** ветка `main`, коммит `cdb1063` (после релиза **1.6.0 от 24.09.2026**).
Релизы: `v1.5.1` → `v1.6.0` (247 зарегистрированных инструментов, 242 отдаётся по умолчанию).

Обновления проверять так (без установки):

```bash
# последняя версия на PyPI
curl -s https://pypi.org/pypi/autocad-mcp-pro/json | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['info']['version'], list(d['releases'])[-4:])"
# свежие релизы на GitHub
curl -s https://api.github.com/repos/U-C4N/Autocad-MCP/releases | python3 -c "import json,sys;[print(r['tag_name'], r['published_at']) for r in json.load(sys.stdin)[:5]]"
```

## 2. Как это работает у нас (архитектура)

```
Hermes (Docker, VM108)  --HTTP MCP (Bearer)-->  контейнер autocad-mcp :30015  --ezdxf-->  DXF/PDF
                                              контейнер autocad-mcp-160 :30016 (тестовый 1.6.0)
                                              папка обмена: /var/lib/docker/volumes/hermes_hermes-data/_data/dxf  →  /opt/data/dxf
```

| Параметр | Значение |
|---|---|
| Рабочий контейнер | `autocad-mcp`, образ `autocad-mcp:latest` = **1.5.1 + наш патч**, порт **30015 → 8000** |
| Тестовый контейнер | `autocad-mcp-160`, образ `autocad-mcp:1.6.0` (апстрим без патча), порт **30016** |
| Бэкенд | `AUTOCAD_MCP_BACKEND=ezdxf` (headless, без AutoCAD; COM — только на Windows рядом с AutoCAD) |
| Токен доступа | файл `/opt/data/.autocad_mcp_token` (chmod 600, **в git не попадает**), передаётся как `Authorization: Bearer …` |
| Папка файлов | `ALLOWED_PATHS=/opt/data/dxf` — сервер принимает файлы **только** оттуда (иначе «Path rejected») |
| Профиль инструментов | `TOOL_PROFILE=full`; для слабых моделей есть `TOOL_PACKS=core,mech...` и `DISCOVERY_MODE=search` (2 инструмента / 356 токенов вместо 83 921) |
| Деплой-скрипты | `/opt/data/deploy_autocad_mcp.py` (рабочий, с тегом отката `autocad-mcp:prev`), `/opt/data/work/cad_mcp/deploy_160_test.py` (тестовый 1.6.0) |
| Логи сборки | `/opt/data/autocad_mcp_build.log`, `/opt/data/autocad_mcp_160_build.log` |
| Проверка живости | `python3 /opt/data/work/cad_mcp/tools_inventory.py 30015` (делает `initialize` → `tools/list`) |

## 3. Что в нашей рабочей сборке сверх апстрима (патч 01.10.2026)

Оверлей лежит в `/opt/data/autocad-mcp-build/patch/` и копируется поверх `site-packages`
(см. `Dockerfile` в `/opt/data/autocad-mcp-build/`). Этих инструментов в апстриме нет:

| Инструмент | Зачем |
|---|---|
| `titleblock_apply_gost_form3` | основная надпись по **ГОСТ Р 21.1101-2013 форма 3** (апстрим знает только ISO 7200) |
| `file_put` / `file_get` | передача файлов внутрь `ALLOWED_PATHS` и обратно (без Docker-томов и HTTP-моста) |
| `drawing_open_base64` / `drawing_save_base64` | обмен чертежами в base64 |
| `entity_create_attdef`, `block_get_attdefs` | символы-блоки с атрибутами (тип/высота/группа) |
| параметр `layout=` у инструментов **геометрии** (29 инструментов) | рисовать линии/полилинии прямо на ЛИСТЕ, а не только в модели |
| параметр `inline_font=True` (5 инструментов) | инлайн-кодировка ISOCPEUR в каждом тексте |
| `drawing_export_pdf(page_size="layout")` | страница PDF ровно по формату листа (в 1.5.1 апстрим подгонял по содержимому) |
| `layout_set_paper` | явный размер бумаги листа (A4 книжный и др.) |
| `template_apply_layers(spds)` | ГОСТ-набор слоёв (RAMKA, STAMPS, 00 БЛОКИ АННОТАЦИЙ, Стены) |
| `dimstyle_ensure`, `text_apply_style` | размерный стиль СПДС, текстовые стили |

⚠️ **Следствие:** апстрим 1.6.0 нельзя просто «поставить вместо» — часть наших возможностей
пропадёт (ГОСТ-штамп, file_put/file_get, `layout` у геометрии, `inline_font`). Поэтому 1.6.0
поднимается **рядом** (порт 30016), а перенос патча делается отдельным шагом.

## 4. Установка с нуля

```bash
# 1) образ (Docker-контекст: Dockerfile + patch/)
mkdir -p /opt/data/autocad-mcp-build && cd /opt/data/autocad-mcp-build
# Dockerfile:
#   FROM python:3.11-slim
#   RUN pip install --no-cache-dir autocad-mcp-pro==1.5.1 matplotlib
#   COPY patch/ /usr/local/lib/python3.11/site-packages/
#   EXPOSE 8000
#   CMD ["autocad-mcp","--transport","http","--host","0.0.0.0","--port","8000"]

# 2) сборка и переустановка контейнера (Portainer API, безопасно: сначала образ, потом замена)
python3 /opt/data/deploy_autocad_mcp.py            # рабочий (с тегом отката autocad-mcp:prev)
python3 /opt/data/work/cad_mcp/deploy_160_test.py  # тестовый 1.6.0 на :30016

# 3) подключение в Hermes (конфиг защищён, менять через config set)
export PATH="/opt/hermes/.venv/bin:$PATH" HERMES_HOME=/opt/data HOME=/opt/data
hermes config set mcp_servers.autocad.type http
hermes config set mcp_servers.autocad.url http://10.26.5.108:30015/mcp
hermes config set mcp_servers.autocad.headers.Authorization "Bearer <токен из /opt/data/.autocad_mcp_token>"
hermes mcp test autocad          # ожидаем "Connected" + число инструментов

# 4) проверка
python3 /opt/data/work/cad_mcp/tools_inventory.py 30015
python3 /opt/skills/devops/cad-automation/scripts/mcp_acceptance_test.py   # приёмочный прогон
```

## 5. Обновление версии

1. Проверить новую версию (п. 1) и прочитать `CHANGELOG.md`.
2. Собрать **тестовый** образ на новую версию: скопировать
   `/opt/data/autocad-mcp-build/Dockerfile` в новый каталог, заменить пин версии,
   запустить `deploy_160_test.py` (порт 30016).
3. Прогнать инвентаризацию и приёмку по обоим портам, сравнить:
   `tools_inventory.py 30015` против `tools_inventory.py 30016` — что появилось, что пропало.
4. Перенести наш патч (см. п. 3) либо решить, что из апстрима заменяет нашу доработку.
5. Переключить рабочий контейнер (`deploy_autocad_mcp.py`) — он сам ставит тег отката
   `autocad-mcp:prev`; при проблеме вернуться на него.

**Откат:** остановить контейнер, создать заново из образа `autocad-mcp:prev` с теми же
параметрами (порт 30015 → 8000, `ALLOWED_PATHS=/opt/data/dxf`, тот же токен, User 10000:10000).

## 6. Грабли, которые уже собирали (не повторять)

- `tools/list` «сырым» POST даёт **HTTP 400** — нужен `initialize` → заголовок `Mcp-Session-Id` → `tools/list`.
- Файлы внутрь контейнера: только путь из `ALLOWED_PATHS` (`/opt/data/dxf`), иначе «Path rejected».
- У контейнера **свой том** — это не тот `/opt/data/dxf`, который видит агент; для передачи
  файлов используем `file_put`/`file_get` или мост `dxf-bridge` (`http://10.26.5.108:30055/`).
- PDF: проверять медиабокс (`pymupdf` → `page.rect.width/72*25.4` ≈ формат листа) и шрифт (`ISOCPEUR`).
- Чертёж отдавать пользователю только после проверки движком AutoCAD (`accoreconsole /i … /s …`).
- COM-режим (живой AutoCAD) **невозможен из Docker** — сервер обязан работать на Windows рядом с AutoCAD.