# kompas3d-mcp

**MCP-сервер для управления CAD-системой КОМПАС-3D (АСКОН) языковой моделью.**

Сервер — COM-клиент КОМПАС-3D: подключается к установленному КОМПАС и даёт LLM 56 инструментов для
создания документов, построения 3D-деталей (эскиз → формообразующая операция), работы со сборками и
чертежами, импорта/экспорта STEP, прямого редактирования импортированной B-rep, а также структурного
осмотра модели (`describe_model` — дерево операций, тела, топология, переменные, МЦХ одним вызовом)
и снимка модели, по которому агент «видит» результат.

Принцип: **MCP транслирует возможности SDK КОМПАС в общие инструменты**, а не под конкретную задачу.
Поверх MCP — навык **`kompas-3d`** с методикой работы (playbook'и, эвристики). Отдельный навык
**`kompas-fdm-design`** — методика проектирования под FDM/FFF 3D-печать (правила DFM + лёгкий
гео-аудит инструментами осмотра): работает поверх `kompas-3d`, экспортирует через `export_step`,
слайсер не вызывает.

Проектной документации в отдельном каталоге нет: этот README — обзор и каталог инструментов,
[CLAUDE.md](CLAUDE.md) — архитектура, проверенные COM-приёмы и подводные камни.

## Требования

- **Windows x64**, установленный **КОМПАС-3D** (разрабатывалось на v24 Home) **вместе с компонентом
  SDK**: interop-сборки принадлежат АСКОН, в поставку сервера не входят и берутся из установки —
  `SDK\Samples\CSharp.zip` (каталог `Common`), при первом запуске распаковываются в
  `%LOCALAPPDATA%\kompas-mcp\interop\<ключ>`. Если SDK не установлен, положите сборки рядом с
  `kompas-mcp.exe` или укажите каталог с ними в `KOMPAS_INTEROP_DIR`.
- **.NET SDK 8+** для сборки из исходников (целевой фреймворк `net8.0-windows`; формат решения
  `.slnx` понимает только SDK 9+ — на SDK 8 собирайте проекты по путям). Для готового релиза рантайм
  не нужен: сервер публикуется self-contained.

## Установка как плагин Claude Code

Сервер и оба публикуемых навыка упакованы в плагин `kompas` (каталог [`plugin/`](plugin/)) — самый
простой способ подключить проект к Claude Code без ручной сборки: `/plugin marketplace add` +
`/plugin install`, дальше лаунчер сам скачивает self-contained сборку сервера по
`plugin/server.lock.json` и сверяет её SHA256. Проверка установки — команда `/kompas:doctor`.
Подробности, режим разработки (`KOMPAS_MCP_EXE`) и сниппеты для Codex/opencode — в
[`plugin/README.md`](plugin/README.md).

> Публичного релиза пока нет (`server.lock.json` в состоянии `0.0.0`, запись в каталоге плагинов не
> заведена) — используйте режим разработки или сборку ниже.

## Сборка и запуск

```powershell
dotnet build -c Release
# сервер (stdio):
dotnet run --project src/Kompas.Mcp.Host -c Release
# или собранный exe (платформа x64 — из Directory.Build.props):
src/Kompas.Mcp.Host/bin/x64/Release/net8.0-windows/kompas-mcp.exe
kompas-mcp.exe --version   # версия бинаря, КОМПАС для этого не нужен
```

### Подключение к MCP-клиенту (stdio)

```json
{
  "mcpServers": {
    "kompas": { "command": "C:\\путь\\к\\kompas-mcp.exe", "args": [] }
  }
}
```

## Инструменты (58)

| Группа | Инструменты |
|---|---|
| System | `kompas_connect`, `kompas_status`, `kompas_set_visible`, `set_auto_validate` |
| Documents | `document_create`, `document_open`, `document_save`, `document_close`, `document_active`, `set_part_info` |
| Sketch | `sketch_create`, `sketch_add`, `sketch_close` |
| Features | `extrude`, `revolve`, `primitive`, `fillet_edge`, `chamfer_edge`, `shell`, `rib`, `sweep`, `loft`, `pattern`, `mirror`, `hole`, `draft`, `rebuild` |
| Edit | `move_face`, `split_solid_by_plane`, `move_body`, `boolean_union` |
| Inspection | `describe_model`, `list_features`, `list_bodies`, `list_variables`, `measure` |
| Vision | `model_snapshot` (PNG-снимок; сначала — `describe_model`) |
| Query | `list_faces`, `list_edges`, `list_components` |
| Variables | `set_variable`, `delete_variable` |
| Conversion | `import_step`, `export_step` |
| Assembly | `assembly_add_component`, `assembly_add_mate` |
| Drawing | `drawing_create_standard_views`, `drawing_fill_title_block`, `drawing_add_linear_dimension`, `drawing_add_diametral_dimension`, `drawing_add_radial_dimension`, `drawing_add_angular_dimension`, `drawing_add_leader`, `drawing_add_rough`, `drawing_add_text`, `drawing_set_technical_requirements`, `drawing_set_sheet_format` |
| Validation | `validate_part` |

Инструменты сгруппированы по смыслу операции, а не по способу вызова: тип задаётся параметром
(`extrude(mode=boss|cut)`, `hole(type=simple|counterbore|countersink|conic)`,
`pattern(kind=linear|circular)`), а объект — либо индексом из `list_faces`/`list_edges`,
либо точкой в мировых координатах (рёбра под скругление/фаску — и списком точек `points[]`,
чтобы N углов давали одну операцию). Эскиз строится списком примитивов за один вызов:
`sketch_create(plane|faceIndex, entities[])`. У каждой операции есть `name` — имя узла в дереве
построения; без него дерево состоит из безликих «Эскиз:1», «Элемент выдавливания:2».

Формообразование идёт двумя путями, и их сочетают: `primitive(kind=block|cylinder|sphere|cone,
result=new|union|subtract|intersect)` строит тело по размерам без эскиза (в том числе вычитает
карман или паз), а `sketch_create` + `extrude` нужен там, где контур сложный — текст, кривые,
произвольный профиль.

Примитивы эскиза: `line`, `circle`, `rectangle`, `arc`, `arc3points`, `ellipse`, `polyline`,
`polygon`, `spline`, `point`, `axis`, `text`. Надпись (`type=text` с `text`, `height`, `fontName`)
сразу переводится в кривые, поэтому её можно выдавливать — так делаются логотипы и гравировка;
в ответе возвращается габарит глифов (и отдельно ширина ячейки строки), по нему надпись выравнивают. Параметры
`extrude(thinThickness, thinSide)` превращают контур в стенку заданной толщины: `outward`
наращивает её наружу и даёт ободок-эквидистанту вокруг контура (например, подложку под надпись).

### Типовой сценарий

`kompas_connect` → `document_create part` →
`sketch_create(plane="XOY", entities=[{type:"rectangle", points:[…]}, {type:"circle", …}])` →
`extrude(mode="boss", depth=20)` → `describe_model` → (повтор для следующих элементов).

> `describe_model` предпочтителен перед `model_snapshot`: отдаёт структурный «паспорт» детали
> (дерево операций, тела, переменные, топологию, МЦХ) без расхода токенов на изображение.
> Параметр `sections` (`box,mass,…`) сужает и ответ, и объём чтения модели.

> Каждая мутирующая операция сама дописывает к ответу итог проверки построения — отдельный
> `validate_part` после каждого шага не нужен. Отключается на сессию через `set_auto_validate(false)`
> или при старте сервера переменной окружения `KOMPAS_MCP_AUTOVALIDATE=0`.

> ⚠️ Вызовы зависимых инструментов выполняйте **последовательно**, дождавшись ответа: сессия
> построения хранит эскизы по `id`, а сервер обрабатывает запросы конкурентно.

## Структура

```
src/Kompas.Mcp.Core/    COM-слой: STA-диспетчер, подключение, документы, эскизы/операции,
                        сборки, чертежи, конвертация, снимок, инспекция модели
src/Kompas.Mcp.Host/    MCP-сервер (stdio) + определения инструментов (Tools/ — по группе на файл)
tests/Kompas.Mcp.Tests/ 427 тестов: unit (корень) + Integration/ (нужен запущенный КОМПАС)
libs/kompas-interop/    interop-сборки КОМПАС (из SDK Samples/Common) — только для компиляции
plugin/                 плагин Claude Code `kompas`: манифест, лаунчер, лок версии сервера,
                        навыки kompas-3d и kompas-fdm-design (источник истины)
tools/                  раскладка навыков junction'ами + Pester-тесты PowerShell плагина
.gitea/workflows/       CI (сборка + unit-тесты) и релиз (публикация в ветку dist)
.claude/skills/         junction'ы на plugin/skills + kompas-mcp-dev (внутренний навык разработки)
.claude/agents/         субагент kompas-sdk-research (Haiku) — поиск по справке SDK
```

Справка по COM API КОМПАС живёт **вне репозитория** — в приватном
[`kompas-sdk-docs`](https://git.shahovalov.ru/mikhail/kompas-sdk-docs) (2465 статей, собраны из
HTML-справки SDK) и проиндексирована в RAG. Доступ — через MCP-сервер `kompas-sdk` (bearer в
`KOMPAS_SDK_RAG_TOKEN`); ищет по ней субагент `kompas-sdk-research`.

## Тесты

```powershell
dotnet test                                   # все (integration требуют КОМПАС)
dotnet test --filter "Category=Unit"          # только unit (без COM)
dotnet test --filter "Category=Integration"   # только integration
pwsh -NoProfile -File tools/tests/run-ps-tests.ps1   # Pester-тесты скриптов плагина
```

427 тестов: 291 unit + 136 integration. CI (Gitea Actions, `.gitea/workflows/ci.yml`) собирает проект и
гоняет `Category=Unit&Requires!=Windows` на Linux-раннере (245 тестов) — 5 тестов STA-диспетчера
помечены `Requires=Windows` (`Thread.SetApartmentState` не работает на Linux). Integration-тесты в CI
не запускаются никогда: нужен запущенный КОМПАС с GUI и лицензией. Плюс 41 Pester-тест
PowerShell-скриптов плагина и раскладки навыков — в счёт .NET-тестов не входят.

## Архитектура (кратко)

- **STA-поток** (`KompasDispatcher`) владеет всеми COM-вызовами — КОМПАС однопоточный STA.
- Подключение через API5 `KompasObject` (`KOMPAS.Application.5`) → API7 `IApplication`
  (`ksGetApplication7`). 3D строится через API5 `ksPart`, снимок — через `ksDocument3D`; отверстия,
  сборки, чертежи и прямое редактирование B-rep — через API7.
- **Interop-сборки подставляются в рантайме** (`KompasInteropLoader`) из установленного КОМПАС, а не
  из поставки сервера: установка находится по `HKCR\CLSID\{...}\LocalServer32`, сборки распаковываются
  из `SDK\Samples\CSharp.zip` в `%LOCALAPPDATA%\kompas-mcp\interop\<ключ>`.
- STEP импорт/экспорт — через встроенный конвертер КОМПАС (AP203/AP214/AP242).
- MCP — официальный C# SDK `ModelContextProtocol`, транспорт stdio, логи в stderr (stdout занят
  протоколом).
- Детали реализации, обоснования и проверенные COM-приёмы — в [CLAUDE.md](CLAUDE.md).

## Лицензирование

`libs/kompas-interop/*.dll` — interop-сборки АСКОН из состава SDK КОМПАС-3D. Они нужны **только для
компиляции** и в релизный архив сервера не попадают (`Private=false`): сервер подставляет их в
рантайме из установленного у пользователя КОМПАС-3D. Для работы требуется установленный КОМПАС-3D
с компонентом SDK.
