КОМПАС-3D MCP

English

Локальный MCP-сервер, с которым ИИ-агент создаёт и редактирует модели в КОМПАС-3D по текстовому описанию, чертежу или PDF. Результат: редактируемая модель с нативными операциями КОМПАС, а также экспорт в STEP, STL и IGES.

41 инструмент, 3 навыка для агента и доступ к API5/API7. Помимо моделирования: параметры и выражения, сборки, чертежи, размеры, материалы и работа с документами. Проверено на Windows, КОМПАС-3D v25 Home и Python 3.12.

Чертёж и описание понимает ИИ-клиент. Сервер выполняет команды в КОМПАС, возвращает измерения и изображения модели. Отдельного OCR или нейросети text-to-3D в сервере нет.

Быстрая установка в Codex

Понадобятся Windows, установленный КОМПАС-3D с действующей лицензией и SDK, а также Codex с поддержкой MCP. КОМПАС должен быть зарегистрирован для COM-автоматизации, как при обычной установке программы. Другие версии и редакции пока не проверены.

На странице этого репозитория нажмите Code → Download ZIP. Распакуйте архив в постоянную папку, например C:\Tools\Compass3DMCP. Откройте именно папку с файлом install.ps1.

Установите uv из PowerShell:

winget install --id astral-sh.uv --exact

Закройте и снова откройте PowerShell, перейдите в папку проекта и запустите установку:
```
cd C:\Tools\Compass3DMCP
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```
Перезапустите Codex. Попросите: «Подключись к КОМПАС через kompas3d и создай тестовую деталь».

Установщик создаёт окружение Python, устанавливает зависимости, регистрирует сервер kompas3d и копирует три навыка в Codex. uv может загрузить подходящий Python автоматически. Интернет нужен для установки зависимостей; сервер работает локально через stdio, без порта и отдельного API-ключа. ИИ-клиент может использовать облачную модель.

Настройки находятся в %USERPROFILE%\.codex, либо в папке CODEX_HOME, если она задана. Перед изменением существующего конфига создаётся резервная копия. Чужие настройки сохраняются; при конфликтующей записи kompas3d установщик остановится с пояснением.

Не перемещайте и не удаляйте папку проекта после установки: Codex запускает Python из её .venv.

Ручная установка

В PowerShell из папки проекта:

uv sync --locked
uv run python scripts/install.py

Обновление

Обновите файлы проекта в той же папке через git pull либо распакуйте свежий ZIP поверх исходных файлов. Затем выполните:

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -UpdateSkills

Или вручную:

uv sync --locked
uv run python scripts/install.py --update-skills

Изменённые копии навыков сохраняются в резервную папку перед заменой. Перезапустите Codex.

Другие MCP-клиенты

Выполните uv sync --locked из папки проекта. Добавьте сервер в конфигурацию своего клиента, заменив путь на абсолютный путь к вашей установке:

{
  "mcpServers": {
    "kompas3d": {
      "command": "C:/Tools/Compass3DMCP/.venv/Scripts/python.exe",
      "args": ["-m", "kompas_mcp.server"]
    }
  }
}

Формат настроек зависит от клиента. Транспорт: stdio. Рекомендуемый тайм-аут команды: 180 секунд, запуска: 30 секунд. Ручной запуск сервера: uv run kompas3d-mcp.

Автоустановка навыков рассчитана на Codex. В другом клиенте используйте инструкции из папки skills в поддерживаемом им формате. Для анализа изображений чертежей нужна модель, умеющая читать изображения.

Что можно поручить агенту

Используй $kompas-modeling. Создай пластину 80 × 50 × 8 мм с четырьмя сквозными отверстиями Ø6 мм. Центры отверстий расположи в 10 мм от двух ближайших краёв. Сохрани редактируемую модель и копию STEP в C:\Models.

Используй $kompas-blueprints. Построй модель по приложенному PDF. Составь список размеров и их источников. Если размеры не заданы, сначала уточни их.

Используй $kompas-api. Найди четыре наружных вертикальных ребра этой детали и добавь скругление радиусом 2 мм. Проверь результат измерениями.

Навык	Для чего нужен
`kompas-modeling`	Планирование модели, эскизы и операции, изменение деталей, проверка геометрии
`kompas-blueprints`	Чтение видов и разрезов, российские обозначения на чертежах, учёт размеров и недостающих данных
`kompas-api`	Поиск в установленном SDK, сложные операции, API5/API7, выбор граней и рёбер, диагностика

Возможности и степень готовности

Область	Возможности
Моделирование	Эскизы, выдавливание и вырезание, вращение, скругления, фаски, оболочки, сечения и траектории
Изменение деталей	Поиск граней и рёбер, изменение и подавление операций, линейные массивы, зеркальные копии
Параметризация	Переменные и выражения, перестроение, материал и плотность; ограничения эскиза через API
Сборки и документы	Создание и открытие деталей, сборок, чертежей, фрагментов, спецификаций и текстовых документов; вставка компонентов
Чертежи	Ассоциативные стандартные виды, линии, окружности, линейные размеры и текст
Проверка и обмен	Объём, площадь, масса, габариты, число тел, PNG-превью, сохранение и экспорт
Расширенные команды	Поиск справки SDK, просмотр интерфейсов и вызовы COM, последовательности зависимых операций

Не требуется отдельный MCP-инструмент для каждой кнопки КОМПАС: общие инструменты настраивают нативные операции и вызывают API. На проверенной установке каталог содержит 1 119 интерфейсов SDK. Доступ к интерфейсу сам по себе не означает, что каждый сценарий проверен.

Проверены в живом КОМПАС, в том числе с сохранением и повторным открытием: базовые тела и вырезы, скругления и фаски, оболочки, элемент по сечениям, линейные массивы и зеркальные копии, изменение толщины листовой заготовки, управляющие переменные, отдельные ограничения эскиза, вставка компонента и создание видов чертежа.

Сопряжения сборок, сложные поверхности, гибка и развёртка, расширенные отверстия и резьбы, спецификации с наполнением и дополнительные модули ещё не прошли полную проверку сценариев. Подробное разделение проверенного, доступного через API и непроверенного есть в карте покрытия. Список всех инструментов и технические подробности: English README.

Если что-то не работает

uv не найден: переоткройте терминал после установки. Если winget недоступен, установите uv по официальной инструкции.
SDK не найден: проверьте наличие SDK/lib и архива справки в установленном КОМПАС. Автопоиск использует C:/Program Files/ASCON/KOMPAS*/SDK. Для другого пути задайте переменную среды KOMPAS_SDK_PATH, указывающую на папку SDK, и перезапустите клиент.
Ошибка подключения COM: проверьте, что КОМПАС установлен и запускается. При нескольких версиях регистрация COM определяет запускаемую версию и должна соответствовать выбранному SDK.
Файл уже открыт: попросите агента использовать attach_active_model и проверить путь активного документа.
После перезапуска пропали ссылки на объекты: идентификаторы действуют в рамках сеанса. Нужно заново открыть или подключить документ и найти геометрию.
Команда зависла или истёк тайм-аут: отмена запроса не прерывает уже выполняющуюся операцию КОМПАС. Проверьте состояние документа перед повтором.

Важные ограничения

Все размеры геометрии задаются в миллиметрах, углы в градусах. Эскизы редактируемые, но не получают полный набор ограничений автоматически.
Агент должен проверять размеры и геометрию: правдоподобное изображение не доказывает соответствие чертежу. Неуказанные размеры требуют уточнения или явно обозначенных допущений.
Импорт STEP проверен как твёрдое тело. STL может дать полигональную геометрию без истории операций. Импорт IGES в локальной проверке не сработал.
Операции выполняются последовательно, без автоматического отката. При ошибке часть изменений может сохраниться.
Общие api_invoke и api_batch предоставляют широкий доступ к локальному COM, включая изменение и удаление объектов и запись файлов. Используйте сервер только с доверенным локальным клиентом.

Для разработчиков

uv sync --locked
uv run pytest -q
uv run ruff check src tests scripts

Модульные и протокольные тесты не запускают КОМПАС. Для проверки реальной CAD-автоматизации есть scripts/validate_live.py и тематические scripts/validate_*.py: они запускают приложение и создают тестовые документы. Результаты сохраняются в artifacts, подробности и команды перечислены в English README.

Проект использует установленный SDK АСКОН и MCP Python SDK. КОМПАС-3D и его SDK в репозиторий не входят.

Лицензия

Проект распространяется по лицензии MIT. Условия использования КОМПАС-3D и SDK определяются АСКОН.

kompas3d