# План реализации MCP-сервера КОМПАС-3D

> Документ описывает, **как** строить сервер. Что строим и почему — в
> [`ARCHITECTURE.md`](ARCHITECTURE.md). Прогресс отражается в
> [`presentation.html`](presentation.html) (TODO).

## Принцип

**«Ходячий скелет» + спайки на риски.** Сначала сквозной тонкий срез
(подключение → снимок), который проходит через все слои и доказывает, что связка
COM ↔ STA ↔ MCP работает. Затем наращиваем инструменты, и **каждый шаг построения сразу
проверяем визуально** (`model_snapshot`) — это и есть целевой UX «строю под контролем».

## Окружение (проверено 2026-05-25)

| | Факт | Следствие для плана |
|---|---|---|
| .NET SDK | **10.0.108** (отдельного .NET 8 SDK нет; рантайм 8 есть) | таргет **`net8.0-windows`** (LTS), собирается SDK 10 |
| ProgID КОМПАС | **`KOMPAS.Application.7`** и **`KOMPAS.Application.5`** зарегистрированы; `KOMPASLT.*` **отсутствует** | подключаться напрямую к API7 через `KOMPAS.Application.7`; LT — только запасной |
| Процесс | КОМПАС не запущен | спайк подключения должен уметь **launch**, не только attach |
| SDK | `C:\Program Files\ASCON\KOMPAS-3D v24 Home\SDK` (`lib\*.tlb`) | источник interop |

**Прерэквизит разработчика:** установленный КОМПАС v24 + возможность его запускать.

---

## Спайки (делать первыми — снимают главные неизвестные)

| # | Риск / вопрос | Критерий успеха |
|---|---|---|
| **S1** | Генерация COM-interop из `.tlb` в SDK-проекте | `net8.0-windows` проект с `<COMReference>` на `kAPI7.tlb`, `kAPI5.tlb`, `ksConstants.tlb`, `ksConstants3D.tlb` собирается; типы `IApplication`, `KompasObject` доступны. Запасной путь — `tlbimp`/ручные interop-сборки |
| **S2** | Подключение по ProgID | консольная проба: attach (`Marshal.GetActiveObject`) → при отказе launch (`Activator.CreateInstance(Type.GetTypeFromProgID("KOMPAS.Application.7"))`); получить `IApplication`, `Visible=true`, прочитать версию |
| **S3** | STA-поток + насос сообщений + async MCP | выделенный STA-поток выполняет COM-вызовы из пула задач без `RPC_E_WRONGTHREAD`; насос сообщений не вешает процесс |
| **S4** | Рендер модели в растр на v24 Home | `ksDocument3D.RasterFormatParam()` → `resultArrayBytes` отдаёт корректные PNG-байты открытого 3D-документа |

Спайки — выбрасываемый код в `spikes/`; выводы переносятся в `Core`.

---

## Фазы

### Фаза 0 — Каркас репозитория
- `git init`, `.gitignore` (.NET + `bin/`, `obj/`; **не** игнорировать `docs/`).
- `KompasMcp.sln`; проекты `Kompas.Mcp.Host`, `Kompas.Mcp.Core`, `Kompas.Mcp.Interop`, `Kompas.Mcp.Tools`
  (в v1 допустимо начать одним проектом, разнося по папкам).
- `Directory.Build.props`: `TargetFramework=net8.0-windows`, `Platforms=x64`, `Nullable=enable`, `LangVersion=latest`.
- Пакеты: `ModelContextProtocol`, `Microsoft.Extensions.Hosting`.
- **Готово:** `dotnet build -c Release` проходит; пустой stdio-хост стартует.

### Фаза 1 — Interop + маппинг констант
- `<COMReference>` на типобиблиотеки (итог S1). Зафиксировать стратегию (embed vs сборки).
- `Kompas.Mcp.Interop`: хелперы «строка ↔ enum» — `DocumentTypeEnum` (part=4, assembly=5, drawing=1, fragment=2),
  `Obj3dType`, `ksEndTypeEnum`, `ksDirectionTypeEnum`, базовые плоскости (`o3d_planeXOY/XOZ/YOZ`).
- **Готово:** unit-тесты маппинга (без COM) зелёные.

### Фаза 2 — STA-диспетчер
- `KompasThread`: выделенный STA-поток, очередь задач (`Channel`/`BlockingCollection`),
  `Task<T> InvokeAsync(Func<T>)`, насос сообщений + периодический `PumpWaitingMessages` (итог S3).
- **Готово:** интеграционный тест — параллельные `InvokeAsync` исполняются строго на одном STA-потоке.

### Фаза 3 — Connection + вертикальный срез (MCP)
- `KompasSession`: resolve ProgID (`KOMPAS.Application.7` → `.5`+`ksGetApplication7()` → `KOMPASLT.*`),
  attach/launch, `Visible`, версия/редакция, освобождение COM, `Quit` только если запускали мы.
- Хост: stdio-сервер, **логи в stderr**, регистрация инструментов через DI.
- Инструменты `System`: `kompas_connect`, `kompas_status`, `kompas_set_visible`.
- **Готово (веха «скелет»):** из MCP Inspector вызвать `kompas_connect` → КОМПАС стартует и виден; `kompas_status` отвечает.

### Фаза 4 — Documents
- `document_create` (part/assembly/drawing/fragment), `document_open`, `document_save`, `document_close`, `document_active`.
- **Готово:** создать деталь, сохранить `.m3d`, закрыть, открыть заново.

### Фаза 5 — Vision (раннее — делает всё дальнейшее проверяемым)
- `set_view` (ориентация iso/front/top/right, zoom-to-fit, `ShadedWireframe`), `model_snapshot`
  (`RasterFormatParam.resultArrayBytes` → image-контент MCP) — итог S4.
- **Готово:** `model_snapshot` возвращает PNG открытой детали; агент видит изображение в ответе инструмента.

### Фаза 6 — Sketch
- `sketch_create` (плоскость или грань), `sketch_add_line|circle|arc|rectangle`, `sketch_close`
  (`NewEntity(o3d_sketch)`→`SetPlane`→`BeginEdit`/примитивы/`EndEdit`, гарантированный `EndEdit` в `finally`).
- **Готово:** построить эскиз-окружность на XOY и увидеть его на снимке.

### Фаза 7 — Features
- `extrude_boss`/`extrude_cut` (depth, direction, endType), `revolve_boss`/`revolve_cut`, `rebuild`.
- **Готово (целевой демо-сценарий):** окружность → `extrude_boss` (цилиндр) → `model_snapshot` →
  выбрать грань → эскиз → `extrude_cut` (отверстие) → `model_snapshot`. Полный цикл со зрением.

### Фаза 8 — Query / Selection
- `select_face_by_point`, `list_bodies`, `list_faces_planes`, `get_part_info` (МЦХ/габариты).
- **Готово:** агент может выбрать грань для следующего эскиза по координатам.

### Фаза 9 — Качество и поставка
- Unit-тесты (маппинг, валидация, форматирование); интеграционные (`[Trait("Category","Integration")]`, гейтятся).
- Трансляция ошибок COM (`ksGetLastError`/`IApplication.KompasError`) в структурированные MCP-ошибки.
- Сборка `kompas-mcp.exe` (`dotnet publish -c Release -r win-x64`), регистрация stdio-сервера в конфиге клиента.
- Escape-hatch `run_kompas_command` (опц.).

---

## Порядок и зависимости

```
S1,S2 ─► Фаза 0 ─► Фаза 1 ─► Фаза 2 ─► Фаза 3 (скелет) ─► Фаза 4 ─► Фаза 5 (зрение)
                                                                       │
                                              Фаза 6 ─► Фаза 7 ─► Фаза 8 ─► Фаза 9
S3 ─► Фаза 2     S4 ─► Фаза 5
```

Критический риск — **S1/S3** (interop + STA). Если `<COMReference>` не заработает на v24 `.tlb` —
переход на сгенерированные `tlbimp` interop-сборки. Все спайки до Фазы 3.

## Definition of Done для v1

Агент через MCP: подключается к КОМПАС → создаёт деталь → строит эскиз → выдавливает →
делает снимок → видит результат → выбирает грань → повторяет → сохраняет `.m3d`.
Сервер собирается в один `.exe` и регистрируется в клиенте по stdio.