kompas3d-mcp

# КОМПАС-3D MCP [English](README.en.md) Локальный 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-автоматизации, как при обычной установке программы. Другие версии и редакции пока не проверены. 1. На странице этого репозитория нажмите **Code → Download ZIP**. Распакуйте архив в постоянную папку, например `C:\Tools\Compass3DMCP`. Откройте именно папку с файлом `install.ps1`. 2. Установите [uv](https://docs.astral.sh/uv/getting-started/installation/) из PowerShell: ```powershell winget install --id astral-sh.uv --exact ``` 3. Закройте и снова откройте PowerShell, перейдите в папку проекта и запустите установку: ```powershell cd C:\Tools\Compass3DMCP powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 ``` 4. Перезапустите Codex. Попросите: **«Подключись к КОМПАС через kompas3d и создай тестовую деталь»**. Установщик создаёт окружение Python, устанавливает зависимости, регистрирует сервер `kompas3d` и копирует три навыка в Codex. `uv` может загрузить подходящий Python автоматически. Интернет нужен для установки зависимостей; сервер работает локально через stdio, без порта и отдельного API-ключа. ИИ-клиент может использовать облачную модель. Настройки находятся в `%USERPROFILE%\.codex`, либо в папке `CODEX_HOME`, если она задана. Перед изменением существующего конфига создаётся резервная копия. Чужие настройки сохраняются; при конфликтующей записи `kompas3d` установщик остановится с пояснением. **Не перемещайте и не удаляйте папку проекта после установки:** Codex запускает Python из её `.venv`. ### Ручная установка В PowerShell из папки проекта: ```powershell uv sync --locked uv run python scripts/install.py ``` ### Обновление Обновите файлы проекта в той же папке через `git pull` либо распакуйте свежий ZIP поверх исходных файлов. Затем выполните: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -UpdateSkills ``` Или вручную: ```powershell uv sync --locked uv run python scripts/install.py --update-skills ``` Изменённые копии навыков сохраняются в резервную папку перед заменой. Перезапустите Codex. ## Другие MCP-клиенты Выполните `uv sync --locked` из папки проекта. Добавьте сервер в конфигурацию своего клиента, заменив путь на абсолютный путь к вашей установке: ```json { "mcpServers": { "kompas3d": { "command": "C:/Tools/Compass3DMCP/.venv/Scripts/python.exe", "args": ["-m", "kompas_mcp.server"] } } } ``` Формат настроек зависит от клиента. Транспорт: **stdio**. Рекомендуемый тайм-аут команды: **180 секунд**, запуска: **30 секунд**. Ручной запуск сервера: `uv run kompas3d-mcp`. Автоустановка навыков рассчитана на Codex. В другом клиенте используйте инструкции из папки [`skills`](skills) в поддерживаемом им формате. Для анализа изображений чертежей нужна модель, умеющая читать изображения. ## Что можно поручить агенту > Используй $kompas-modeling. Создай пластину 80 × 50 × 8 мм с четырьмя сквозными отверстиями Ø6 мм. Центры отверстий расположи в 10 мм от двух ближайших краёв. Сохрани редактируемую модель и копию STEP в C:\Models. > Используй $kompas-blueprints. Построй модель по приложенному PDF. Составь список размеров и их источников. Если размеры не заданы, сначала уточни их. > Используй $kompas-api. Найди четыре наружных вертикальных ребра этой детали и добавь скругление радиусом 2 мм. Проверь результат измерениями. | Навык | Для чего нужен | | --- | --- | | [`kompas-modeling`](skills/kompas-modeling/SKILL.md) | Планирование модели, эскизы и операции, изменение деталей, проверка геометрии | | [`kompas-blueprints`](skills/kompas-blueprints/SKILL.md) | Чтение видов и разрезов, российские обозначения на чертежах, учёт размеров и недостающих данных | | [`kompas-api`](skills/kompas-api/SKILL.md) | Поиск в установленном SDK, сложные операции, API5/API7, выбор граней и рёбер, диагностика | ## Возможности и степень готовности | Область | Возможности | | --- | --- | | Моделирование | Эскизы, выдавливание и вырезание, вращение, скругления, фаски, оболочки, сечения и траектории | | Изменение деталей | Поиск граней и рёбер, изменение и подавление операций, линейные массивы, зеркальные копии | | Параметризация | Переменные и выражения, перестроение, материал и плотность; ограничения эскиза через API | | Сборки и документы | Создание и открытие деталей, сборок, чертежей, фрагментов, спецификаций и текстовых документов; вставка компонентов | | Чертежи | Ассоциативные стандартные виды, линии, окружности, линейные размеры и текст | | Проверка и обмен | Объём, площадь, масса, габариты, число тел, PNG-превью, сохранение и экспорт | | Расширенные команды | Поиск справки SDK, просмотр интерфейсов и вызовы COM, последовательности зависимых операций | Не требуется отдельный MCP-инструмент для каждой кнопки КОМПАС: общие инструменты настраивают нативные операции и вызывают API. На проверенной установке каталог содержит **1 119 интерфейсов SDK**. Доступ к интерфейсу сам по себе не означает, что каждый сценарий проверен. Проверены в живом КОМПАС, в том числе с сохранением и повторным открытием: базовые тела и вырезы, скругления и фаски, оболочки, элемент по сечениям, линейные массивы и зеркальные копии, изменение толщины листовой заготовки, управляющие переменные, отдельные ограничения эскиза, вставка компонента и создание видов чертежа. **Сопряжения сборок, сложные поверхности, гибка и развёртка, расширенные отверстия и резьбы, спецификации с наполнением и дополнительные модули ещё не прошли полную проверку сценариев.** Подробное разделение проверенного, доступного через API и непроверенного есть в [карте покрытия](docs/coverage.md). Список всех инструментов и технические подробности: [English README](README.en.md#included-tools). ## Если что-то не работает - **`uv` не найден:** переоткройте терминал после установки. Если `winget` недоступен, установите uv по [официальной инструкции](https://docs.astral.sh/uv/getting-started/installation/). - **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**, включая изменение и удаление объектов и запись файлов. Используйте сервер только с доверенным локальным клиентом. ## Для разработчиков ```powershell 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](README.en.md#verification). Проект использует установленный SDK АСКОН и [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk). КОМПАС-3D и его SDK в репозиторий не входят. ## Лицензия Проект распространяется по лицензии [MIT](LICENSE). Условия использования КОМПАС-3D и SDK определяются АСКОН.