kompas3d-mcp/README.md

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

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

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

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)

{
  "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, либо точкой в мировых координатах. Эскиз строится списком примитивов за один вызов: sketch_create(plane|faceIndex, entities[]).

Формообразование идёт двумя путями, и их сочетают: 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 (2465 статей, собраны из HTML-справки SDK) и проиндексирована в RAG. Доступ — через MCP-сервер kompas-sdk (bearer в KOMPAS_SDK_RAG_TOKEN); ищет по ней субагент kompas-sdk-research.

Тесты

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.

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

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