Kompas3D MCP

MCP-сервер для КОМПАС-3D v24: ИИ-агент строит и проверяет настоящие детали и сборки, а сервер
отвечает тем, что измерил на модели, а не тем, что вызов «прошёл».

English summary. A Model Context Protocol server that lets an AI agent drive a real, licensed
KOMPAS-3D v24 (x64) over COM: parts, sketches (including bulk geometry: native polyline and
spline), features, patterns, booleans, assemblies and mates, assembly interference and clearance
checks, drawings (views, dimensions, title block, DXF/DWG export), external variables and material,
STEP and image export. Every mutating call reports a
measured verification level (volume, bodies, faces, re-read parameters, save/reopen), journals
operations for idempotent retries, rejects stale revisions, and is confined to configured disk
roots. No arbitrary code execution. 90 tools, MIT licensed. Documentation is in Russian.

Быстрая установка через ChatGPT Codex

  ChatGPT Codex: установка одной фразой

Если у вас Windows, установлен КОМПАС-3D v24 и есть ChatGPT Codex
(приложение, CLI или расширение IDE), ничего скачивать и собирать вручную не нужно. Скопируйте в
Codex этот текст:

https://github.com/SergeySklyarov/Kompas3D-MCP
Установи и подключи последнюю принятую версию KompasMCP из этого репозитория на этой Windows-машине по инструкции docs/operator-guide/codex-setup.md; проверь зависимости, checksum и доступность инструментов; мои модели не изменяй.

Codex проверит зависимости, скачает готовый пакет из Releases, сверит контрольную сумму, создаст
конфигурацию и подключит сервер. Разрешите ему скачивание и запуск установщика, когда он спросит.
В конце перезапустите Codex (в приложении Restart) и в новом чате напишите
«вызови kompas_health и kompas_capabilities»: должно прийти 94 инструмента. Подробности и ручной
путь: подключение к Codex.

_{ChatGPT, Codex и логотип OpenAI являются товарными знаками OpenAI. Проект не связан с OpenAI и
не одобрен ею.}

Быстрая установка через Claude

  Claude Code: установка одной фразой

Если у вас Windows, установлен КОМПАС-3D v24 и есть Claude Code (вкладка
Code в приложении Claude, CLI или расширение IDE), скопируйте в него этот текст:

https://github.com/SergeySklyarov/Kompas3D-MCP
Установи и подключи последнюю принятую версию KompasMCP из этого репозитория на этой Windows-машине по инструкции docs/operator-guide/claude-setup.md; проверь зависимости, checksum и доступность инструментов; мои модели не изменяй.

Claude проверит зависимости, скачает готовый пакет, сверит контрольную сумму, создаст конфигурацию
и зарегистрирует сервер командой claude mcp add. Разрешите ему скачивание и запуск команд, когда
он спросит. Затем начните новую сессию и попросите вызвать kompas_health и kompas_capabilities:
должно прийти 90 инструментов. Подробности и вариант для обычного чата Claude Desktop:
подключение к Claude.

_{Claude и логотип Claude являются товарными знаками Anthropic. Проект не связан с Anthropic и не
одобрен ею.}

Пример: деталь по чертежу, собранная агентом

Агенту дают чертёж и задачу, и он строит деталь сам, вызовами инструментов этого сервера. Каждый
шаг сервер подтверждает измерением.

Задание конкурса Model Mania 2021 (SOLIDWORKS). Права на чертёж принадлежат SOLIDWORKS.

Деталь, построенная агентом (ChatGPT 6.0 Astra, режим размышлений Low) по этому чертежу:
два вида одного тела. Слева дерево построения, которое агент собрал сам.

Что умеет

• Детали. Эскизы на базовых и смещённых плоскостях с правкой отдельных сущностей и проверкой
  определённости; выдавливание, вращение, по траектории, по сечениям, оболочка; скругления, фаски,
  родные отверстия; булевы операции, разделение и отсечение плоскостью, перенос и поворот тела;
  массивы по сетке, круговые и зеркальные.
• Правка, а не пересоздание. Параметры существующего признака читаются и меняются на месте;
  признак можно подавить, восстановить или удалить; опорную плоскость эскиза можно сменить.
• Вспомогательная геометрия. Плоскости, оси и точки создаются как объекты модели и правятся.
• Сборки и сопряжения. Вставка и замена компонентов, размещение, проверка ссылок на файлы;
  создание, параметры, фиксация и удаление сопряжений.
• Чертежи. Группа стандартных ассоциативных видов из модели, список видов, размеры (линейный,
  диаметральный, радиальный), основная надпись: запись и перечитывание ячеек штампа, технические
  требования, экспорт в DXF/DWG с проверкой выгруженного файла.
• Переменные и материал. Внешние параметрические переменные верхнего компонента: чтение,
  присвоение числового значения и выражения. Материал и плотность детали: чтение (плотность в
  кг/м³ документированным маршрутом расчёта МЦХ) и назначение с подтверждением перечитыванием;
  масса по плотности из модели.
• Измерение и топология. Габарит, объём, площадь, центр масс; грани и рёбра конечного тела и
  однозначный выбор по структурному признаку.
• Обмен. Экспорт и импорт STEP; растровый снимок модели (PNG, JPG, BMP, TIF) в заданной
  проекции (view: спереди, сверху, изометрия и др.), который возвращается клиенту картинкой.
• Сеанс. Подключение к КОМПАС или запуск своего экземпляра, явный захват и передача сеанса
  между чатами без перезапуска клиента.

Почему ему можно доверять модель

• Измеренный уровень проверки. В ответе каждой операции есть verification.level: от
  call_returned («КОМПАС сказал, что получилось») до geometry_checked (модель перечитана, тела,
  габарит и объём совпали) и geometry_roundtrip_checked. Сервер не сообщает уровень, которого не
  достиг; непроверенное перечислено в unverified_aspects.
• Журнал операций и идемпотентность. Каждая мутация несёт operation_id и пишется в журнал до
  и после выполнения. Повтор с тем же operation_id не применяет операцию второй раз, а тот же
  operation_id с другими аргументами отвергается (OPERATION_ID_CONFLICT). Ошибка говорит,
  можно ли повторять и как (retry_policy), и были ли частичные эффекты.
• Защита от устаревшего состояния. expected_revision отвергает мутацию, если модель
  изменилась с момента чтения (REVISION_CONFLICT); ссылки на грани, рёбра и признаки привязаны к
  ревизии и устаревают явно (STALE_REFERENCE), а не указывают на чужой объект.
• Политика путей. Сервер читает и пишет только в корнях из конфигурации (только чтение, запись,
  экспорт). Путь вне них отклоняется (PATH_NOT_ALLOWED) до обращения к КОМПАС.
• Изоляция COM. Host говорит MCP и не трогает COM вообще; весь КОМПАС живёт в отдельном
  процессе Worker с одним STA-потоком. Host следит за Worker, перезапускает его при сбое и прямо
  сообщает, что прежние document_id после перезапуска недействительны.
• Никакого произвольного кода. Нет инструмента «выполни скрипт» или «вызови COM-метод по
  имени»: только типизированные инструменты со строгими JSON-схемами аргументов.
• Только документированный API. Каждая операция идёт маршрутом из официальной справки
  КОМПАС v24; сверка вызовов со справкой лежит в docs/API_COMPLIANCE.md.
• Пользовательский КОМПАС не закрывается. Сервер завершает только тот экземпляр, который
  запустил сам.

Как устроено

MCP-клиент (stdio)
   │
KompasMcp.Host        контракты, валидация по схемам, журнал, реестр ссылок и ревизий; без COM
   │ именованный канал
KompasMcp.Worker      отдельный процесс, один STA-поток с циклом сообщений; здесь живёт КОМПАС
   │
KompasMcp.Api5Adapter единственный проект, который знает типы КОМПАС (API5 и точечно API7)

Решения по архитектуре: docs/adr/.

Требования

• Windows x64.
• Установленный и лицензированный КОМПАС-3D v24 x64. Сервер работает с настоящим приложением
  и CAD не эмулирует.
• Для готового пакета: .NET 10 Runtime x64 (подходит и .NET 10 Desktop Runtime x64). .NET SDK
  не нужен.
• Для сборки из исходников: .NET SDK 10 (global.json закрепляет 10.0.401).

Interop-сборки берутся из каталога установки КОМПАС и ни в репозиторий, ни в пакет не входят. По
той же причине сборка в облачном CI невозможна: проверка изменений идёт на машине с установленным
КОМПАС.

Установка

Готовый пакет. В Releases
лежат KompasMCP-<тег>-win-x64.zip, SHA256SUMS.txt, release-manifest.json и установщик
Install-KompasMcp.ps1. Собирать ничего не нужно. Архив «Source code» на странице выпуска - это
исходники, готового сервера в нём нет.

Через Codex. Дайте агенту ссылку на этот репозиторий и поручение:

Установи и подключи последнюю принятую версию KompasMCP из этого репозитория на этой
Windows-машине; проверь зависимости, checksum и доступность инструментов; мои модели не изменяй.

Что он сделает и как проверить результат: подключение к Codex.

Другой MCP-клиент. Распакуйте пакет, создайте конфигурацию из config\kompas-mcp.example.json
и подключите KompasMcp.Host.exe --config <конфиг> как stdio-сервер. Пример для клиентов с
JSON-конфигурацией:

{
  "mcpServers": {
    "kompas": {
      "command": "<каталог-пакета>\KompasMcp.Host.exe",
      "args": ["--config", "<путь>\kompas-mcp.json"],
      "timeout": 600000
    }
  }
}

Проверка из клиента: kompas_health, kompas_capabilities, затем kompas_connect {"mode": "launch"}.

Из исходников. .\scripts\publish.ps1 -Configuration Release собирает тот же пакет в
artifacts\publish. Подробно: установка,
конфигурация, сборка,
диагностика. Модульные тесты идут без КОМПАС:
dotnet test tests\Unit\KompasMcp.Unit\KompasMcp.Unit.csproj -c Debug -p:Platform=x64.

Инструменты

94 инструмента с названием и назначением каждого: docs/TOOLS.md.
Схемы аргументов лежат в schemas/.

Состояние и планы

Целевая версия: КОМПАС-3D v24.0.0.2799 x64. Текущий выпуск -
v0.9.0, заметки:
docs/distribution/v0.9.0.md. Теги выпусков - версия продукта
vMAJOR.MINOR.PATCH (правило). Обязательный объём закрывается, только когда каждое применимое
действие режима (создание, чтение, правка, перестроение, сохранение и повторное открытие,
подавление, удаление зависимостей, отрицательные проверки, проверка геометрии) подтверждено живым
прогоном.

Закрыты все одиннадцать профилей: режимов 102/102, зависимостей 60/60, открыто 0,
problems: [] (scripts/acceptance-levels.py).

Приёмка выпуска 0.9.0 (на бинарях пакета): полный живой прогон 1685 PASS / 6 NAMED / 0 FAIL
(1691 строка); дополнительный прогон «подавить -> снять» (20 повторов) - 39 PASS / 1 NAMED / 0
FAIL; клиентская приёмка рабочим MCP-клиентом - 14 строк из 14 исполнено и выполнено ожиданию,
несделанных нет. Паспорт поставки - итог PASS по всем уровням: доставка, функциональная приёмка,
обязательный объём и клиентская приёмка, fully_ready = true. Текущее состояние и измеренные числа:
docs/STATUS.md; каталог операций, матрица покрытия и
профили: coverage/solid-v24/.

Снимок дашборда от 23.09.2026 по профилю mechanical-core-v1: иллюстрация, а не источник чисел.
Действующие числа - в таблице выше и в docs/STATUS.md.

Чего пока нет:

• Спецификации и прочие 2D-документы. Чертежи профиля drawings-minimal-v1 закрыты (виды,
  размеры, штамп, технические требования, DXF/DWG), а спецификации, сборочные чертежи и остальные
  2D-документы КОМПАС в выпуск не входят.
• В сборках массивы компонентов, полная спецификация (BOM) и виды сопряжений сверх профиля
  mates-minimal-v1 в этот выпуск не входят. Компоненты внутри подсборок читаются, но адреса для
  правки у них нет: размещение и замена вложенного компонента отвергаются.
• Эскиз прямо на грани. Документированный маршрут принимает опорой плоскость, поэтому грань
  отвергается по виду ссылки. Эскиз у грани строится на плоскости, созданной от неё
  (kompas_create_aux_geometry, plane/offset, base_face_ref), формой plane: { reference }.
• Переменные детали. Создание переменных (kompas_create_variable) и привязка параметров
  операций (kompas_bind_parameter) входят в выпуск; kompas_set_variable меняет значение или
  выражение существующей переменной. Удаление и переименование переменных, функциональные и
  интервальные переменные, таблица переменных, переменные компонентов сборки и привязка размеров
  эскиза - вне выпуска.
• Родные приклеивание и вырезание по траектории (SM-04.boss) отложены; сохранение копии базового
  объекта при объединении (SM-15.union.mode_save_base_copy) запланировано следующим этапом.
• Девять профилей из таблицы выше - это не весь каталог операций P6: в каталоге
  41 семейство, из них 24 в обязательном объёме (94 обязательных режима). План:
  implementation-plan.md.
• Сервер не правит произвольную операцию КОМПАС: то, что не подтверждено, возвращается как
  CAPABILITY_UNAVAILABLE с объяснением, а не как успех.

Документация

Что не входит в репозиторий

Доказательства прогонов и приёмки, собранные поставки, рабочие данные, модели заказчика и
локальные конфигурации в публикацию не входят. Документы называют их по имени: это указание на
доказательство, которое читатель воспроизводит опубликованными приборами из scripts/ на своей
установке КОМПАС. Полный перечень и пояснения: обзор, раздел «Что намеренно не
входит в публичный репозиторий». Набор публикации проверяет страж
scripts/verify-publish-set.py.

Лицензия

MIT. КОМПАС-3D является продуктом АСКОН и в репозиторий не входит; для работы нужна
собственная лицензия.