kompas3d-mcp/.claude/skills/kompas-3d/SKILL.md

---
name: kompas-3d
description: >
  Методика работы с КОМПАС-3D через MCP-сервер этого проекта: построение и
  модификация деталей, импорт/экспорт STEP, работа со сборками, осмотр геометрии
  снимками и запросами. Используй ВСЕГДА, когда задача — что-то СДЕЛАТЬ в КОМПАС
  через MCP-инструменты (создать/править деталь, импортировать STEP, разобрать
  сборку, померить, отрендерить, экспортировать). Здесь — playbook'и и эвристики,
  выработанные в usecases/. Триггеры: «построй деталь в КОМПАС», «импортируй STEP»,
  «что в этой сборке», «нарасти/измени деталь», «экспортируй STEP», «сделай снимок модели».
  НЕ для поиска по справке SDK — это навык kompas-sdk-research.
---

# kompas-3d — методика управления КОМПАС-3D через MCP

## Два слоя (важно не смешивать)

- **MCP-сервер** (`src/Kompas.Mcp.Host`) — *инструмент*. Он **транслирует возможности COM API/SDK
  КОМПАС** в MCP-инструменты. Инструменты делаются **общими** (по возможностям SDK), а не под
  конкретную задачу. Расширяя MCP, добавляй универсальную операцию (например `import_step`,
  `list_components`, `export_step`, «переместить грань», «рассечь тело»), а не «сделать вот эту деталь».
- **Этот навык** — *методика*. Как из общих инструментов собрать решение: порядок шагов,
  выбор геометрии, проверка результата, обход подводных камней. Подходы вырабатываются в
  **`usecases/`** и поднимаются сюда.

Итог: **MCP = чем делать, навык = как делать.** Новый приём сначала обкатывается кейсом, потом
обобщается: инструмент → в MCP, метод → в этот навык.

## Когда применять

Любая задача «сделать что-то В КОМПАС» через MCP: создать/править деталь, эскизы и операции,
импорт/экспорт обменных форматов, разбор сборки, измерения, снимки. Для поиска сигнатур/констант
в справке — отдельный навык `kompas-sdk-research`. Для правки документации — `docs-delegate`.

## Инструменты MCP

**Реализованы (v2+, 35 инструментов):** `kompas_connect`, `kompas_set_visible`, `kompas_status`;
`document_create|open|save|save_as|close|active`; `sketch_create`, `sketch_create_on_face[_index]`,
`sketch_add_line|circle|rectangle|axis`, `sketch_close`; `extrude_boss|cut`, `revolve_boss|cut`,
`fillet_edge[_index]`, `chamfer_edge[_index]`, `rebuild`; **`move_face`** (прямое редактирование: сдвинуть грань на N мм);
`get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`, `list_components`;
`import_step`, `export_step`; `model_snapshot`.

**Планируются (трансляция SDK, по мере кейсов):** рассечение/перемещение тела как инструменты
(`SplitSolids`/`BodyRepositions` — механика есть, продуктизация не закончена), `list_bodies`,
массивы/паттерны, переменные/свойства.

> Если нужного инструмента ещё нет — не хардкодь обход под кейс. Заведи кейс в `usecases/`,
> докажи механику (тест или минимальный прогон в usecases/), затем продуктизируй как
> **общий** инструмент MCP (с тестами, TDD) и опиши приём здесь.

## Базовый цикл (эскиз → операция → осмотр)

Опорный сценарий построения, проверен end-to-end (см. `usecases/0001`):

1. `kompas_connect` (+ `kompas_set_visible true`, чтобы снимки были осмысленны).
2. `document_create part`.
3. `sketch_create XOY` → `sketch_add_*` → `sketch_close`.
4. `extrude_boss`/`revolve_boss`/…
5. **Осмотр:** `model_snapshot` (увидеть) + `get_part_info`/`get_bounding_box` (сверить числами).
6. Итерация «на грани»: `model_snapshot` → `list_faces` → `sketch_create_on_face_index` → операция.

## Работа с импортом / сборками (выработано в usecases/0002)

Конвейер «импорт → разбор → извлечение детали → осмотр → модификация → экспорт»:

1. **Импорт STEP** в новый документ (под капотом: встроенный конвертер по коду формата
   `ksConverterFromSTEP`, затем `ConvertFromAdditionFormat`). Тип документа выбирается по
   содержимому: сборка → `.a3d`, одиночное тело → деталь.
2. **Разбор сборки**: перечислить компоненты (имя, обозначение, габарит, файл) — обход `TopPart → Parts`.
3. **Извлечение отдельной детали**: при импорте включать «создавать файлы компонентов», тогда
   компоненты пишутся как отдельные `.m3d` рядом; открывать деталь самостоятельным документом
   (`OpenSourceDocument`). Гашение видимости компонента на снимок **не влияет** — изоляция так не делается.
4. **Осмотр детали**: габарит по осям (какая ось — «высота»), `list_faces`/`list_edges`, стандартные
   проекции (`#Спереди/#Сверху/#Слева/#Справа/#Изометрия`) + `model_snapshot` для каждой.
5. **Модификация**: на «тупой» импортированной B-rep работает `move_face` — сдвинуть грань на +N мм
   (наружу, добавить материал) или −N мм (внутрь). Рассечение/раздвижка тела — механика есть,
   отдельных инструментов пока нет (см. ниже).
6. **Экспорт STEP**: `ConvertToAdditionFormat` (есть AP203/AP214/AP242).

Точные COM-приёмы и сигнатуры — в авто-памяти `kompas-step-and-assembly-api` и в `usecases/0002/case.md`.

## Эвристики и подводные камни

- **Решай по снимку.** После каждой формообразующей операции делай `model_snapshot` и проверяй
  визуально; числами — `get_part_info`/`get_bounding_box`.
- **Грань/ребро по индексу надёжнее, чем по точке.** Сначала `list_faces`/`list_edges`, затем
  `*_on_face_index` / `*_edge_index`. По точке (`SelectByPoint`) — только когда индекс не подходит.
- **Направление операции.** `extrude_boss(..., forward)` может уйти «не туда» в зависимости от
  нормали выбранной грани — проверь снимком, при необходимости инвертируй `forward`.
- **МЦХ.** Объём/масса меняющейся геометрии бери через `get_part_info` (под капотом API5
  `CalcMassInertiaProperties`); перед чтением после правок — `rebuild`.
- **id эскизов/операций** недействительны после смены активного документа (create/open/close).
- **Единицы — мм** (геометрия) и кг (масса). Локальные координаты эскиза ≠ мировые координаты модели.

## Открытые вопросы / границы

- **Перемещение грани (`move_face`) — реализовано.** Работает на импортированной B-rep через
  `IPart7.FindObjectsByPoint` + `FaceMover`. Проверено: top_spacer 39.45→41.45 мм.
- **Рассечение/перемещение тела** (`SplitSolids`/`BodyRepositions`) — механика задокументирована,
  отдельными MCP-инструментами не оформлена. Возможная следующая опция.
- Сборки/паттерны/переменные в MCP пока не реализованы.

## Связанное

- Инструменты и их реализация: `src/Kompas.Mcp.Host/Tools/*`, `src/Kompas.Mcp.Core/*`.
- Кейсы (полигон подходов): `usecases/` (см. `usecases/README.md`).
- Поиск по справке SDK: навык **kompas-sdk-research**.
- Правка документации проекта: навык **docs-delegate**.
- Память: `kompas-step-and-assembly-api` (проверенные COM-приёмы импорта/экспорта/обхода).