# КОМПАС-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 определяются АСКОН.