kompas3d-mcp/README.md

# kompas3d-mcp

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

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

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

> Подробности: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) · план — [docs/IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md)
> · спорные вопросы — [docs/OPEN_QUESTIONS.md](docs/OPEN_QUESTIONS.md) · обзор — [docs/presentation.html](docs/presentation.html)

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

- **Windows x64**, установленный **КОМПАС-3D** (разрабатывалось на v24 Home).
- **.NET SDK 8+** (собирается и на SDK 10; целевой фреймворк `net8.0-windows`).

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

```powershell
dotnet build -c Release
# сервер (stdio):
dotnet run --project src/Kompas.Mcp.Host -c Release
# или собранный exe:
src/Kompas.Mcp.Host/bin/Release/net8.0-windows/kompas-mcp.exe
```

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

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

## Инструменты (83 инструмента)

| Группа | Инструменты |
|---|---|
| System | `kompas_connect`, `kompas_status`, `kompas_set_visible` |
| Documents | `document_create`, `document_open`, `document_save`, `document_save_as`, `document_close`, `document_active` |
| Sketch | `sketch_create`, `sketch_create_on_face`, `sketch_create_on_face_index`, `sketch_create_on_offset_plane`, `sketch_add_line`, `sketch_add_circle`, `sketch_add_rectangle`, `sketch_add_axis`, `sketch_add_arc`, `sketch_add_arc_3points`, `sketch_add_ellipse`, `sketch_add_polyline`, `sketch_add_polygon`, `sketch_add_spline`, `sketch_add_point`, `sketch_close` |
| Features | `extrude_boss`, `extrude_cut`, `revolve_boss`, `revolve_cut`, `fillet_edge`, `chamfer_edge`, `fillet_edge_index`, `chamfer_edge_index`, `shell`, `rib`, `sweep`, `loft`, `linear_pattern`, `circular_pattern`, `mirror_operation`, `mirror_body`, `hole`, `hole_counterbore`, `hole_countersink`, `hole_conic`, `draft`, `rebuild` |
| Edit | `move_face`, `split_solid_by_plane`, `move_body`, `boolean_union` |
| Inspection | `describe_model`, `list_features`, `list_bodies`, `list_variables`, `describe_face`, `describe_edge`, `measure` |
| Vision | `model_snapshot` (PNG-снимок; fallback — сначала `describe_model`) |
| Query | `get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`, `list_components` |
| Variables | `create_variable`, `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_rough`, `drawing_add_text`, `drawing_set_technical_requirements`, `drawing_set_sheet_format`, `drawing_add_leader` |
| Validation | `validate_part` |

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

`kompas_connect` → `document_create part` → `sketch_create XOY` → `sketch_add_circle` →
`sketch_close` → `extrude_boss` → `describe_model` → (повтор для следующих элементов).

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

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

## Структура

```
src/Kompas.Mcp.Core/   COM-слой: STA-диспетчер, подключение, документы, эскизы/операции, конвертация, снимок, инспекция модели
src/Kompas.Mcp.Host/   MCP-сервер (stdio) + определения инструментов
tests/Kompas.Mcp.Tests/ 331 тест: unit + integration (integration требуют КОМПАС)
libs/kompas-interop/   вендорские interop-сборки КОМПАС (из SDK Samples/Common)
docs/                  архитектура, план, презентация, MD-база знаний SDK (Kompas3D_SDK/)
usecases/              полигон обкатки подходов (в .gitignore); приёмы поднимаются в навык kompas-3d
.claude/skills/        навык kompas-3d (методика)
.claude/agents/        субагенты-делегаты: docs-maintainer (Sonnet), kompas-sdk-research (Haiku)
```

## Тесты

```powershell
dotnet test                                   # все (integration требуют КОМПАС)
dotnet test --filter "Category=Unit"          # только unit (без COM)
dotnet test --filter "Category=Integration"   # только integration
```

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

- **STA-поток** (`KompasDispatcher`) владеет всеми COM-вызовами — КОМПАС однопоточный STA.
- Подключение через API5 `KompasObject` (`KOMPAS.Application.5`) → API7 `IApplication` (`ksGetApplication7`).
- 3D строится через API5 `ksPart`, снимок — через `ksDocument3D`; прямое редактирование импортированной B-rep — через API7. Структурный осмотр, переменные, сборки и чертежи инкапсулированы в сервисах COM-слоя.
- STEP импорт/экспорт — через встроенный конвертер КОМПАС.
- MCP — официальный C# SDK `ModelContextProtocol`, транспорт stdio, логи в stderr.
- Детали реализации, обоснования и проверенные COM-приёмы — в [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) и [CLAUDE.md](CLAUDE.md).

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

`libs/kompas-interop/*.dll` — interop-сборки АСКОН из состава SDK КОМПАС-3D; распространяются
согласно условиям АСКОН. Для работы требуется установленный КОМПАС-3D.