# Blender for Codex — 1.3.1

Открытый проект: приветствуются [участие в разработке](CONTRIBUTING.md), сообщения об ошибках и pull requests. Ближайшие задачи — в [плане развития](ROADMAP.md).

Локальная интеграция Codex ↔ Blender: MCP-сервер, дополнение Blender, навык агента, установщик и диагностика. Это адаптация открытого сервера [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp), как в [плагине Kimi](https://github.com/artmediastudio/kimi-blender-mcp-plugin). Лицензия MIT; версии исходников зафиксированы в UPSTREAM.json. Это сторонний проект.

## Возможности

- Чтение сцены, объектов, материалов и параметров.
- Моделирование, материалы, свет, камеры и анимация через Python/bpy.
- Просмотр сцены, рендеринг, открытие/сохранение .blend и импорт/экспорт через bpy.
- Дополнительные интеграции ресурсов upstream. Их аккаунты, тарифы и ключи настраиваются отдельно; в этом комплекте они не проверялись.

Основная работа происходит локально: Codex → stdio MCP → 127.0.0.1:9876 → Blender.
Телеметрия upstream принудительно отключена в launcher. Сам Codex продолжает работать по своим настройкам; это не автономная локальная модель.
Выполнение bpy имеет права процесса Blender на файлы компьютера. Дополнение слушает локальное соединение без отдельного пароля; не публикуйте этот порт в сеть.

## Установка на Windows

### Установка в список «Плагины»

```powershell
codex plugin marketplace add blend3dweb/codex-blender-mcp-plugin
codex plugin add codex-blender-mcp@blend3dweb
```

Каталог появится под именем **Blend3DWeb**, плагин — **Blender for Codex**. GitHub-репозиторий публичный; это пользовательский marketplace, не публикация в общем каталоге OpenAI.

После установки подготовьте Python-окружение именно установленной копии. Если раньше сервер был добавлен отдельно через `codex mcp add`, сначала удалите дублирующую ручную запись командой `codex mcp remove codex-blender` — установленный плагин предоставляет свой сервер с этим именем. Затем:

```powershell
$server = (codex mcp get codex-blender --json | ConvertFrom-Json).transport
$env:PLUGIN_DATA = $server.env.PLUGIN_DATA
python (Join-Path $server.env.PLUGIN_ROOT 'scripts/setup.py')
Remove-Item Env:PLUGIN_DATA
```

Окружение хранится в постоянном `PLUGIN_DATA`, отдельно от версионного кэша. Установите дополнение Blender по шагам ниже и перезапустите Codex. Не запускайте `--register-codex` при установке через marketplace: это альтернативный способ подключения.

### Альтернатива: только MCP через CLI

Нужны Python 3.10+ и Blender. Проверенная версия Blender указана в VALIDATION.md.

1. Распакуйте папку в постоянное место. Откройте там PowerShell.
2. Подготовьте окружение и добавьте сервер в Codex:

   ```powershell
   python scripts/setup.py --register-codex
   ```

   Установщик создаёт .venv внутри комплекта. Добавляет только MCP-запись `codex-blender`; существующую запись с таким именем не перезаписывает. Перед изменением config.toml создаёт резервную копию. При конфликте используйте `--name blender-local`.
   Для подготовки без изменения настроек Codex: `python scripts/setup.py`.

3. В Blender откройте Edit → Preferences → Add-ons → меню → Install from Disk. Выберите `assets/blender_mcp.py`, включите **MCP for Blender**.
4. В 3D Viewport нажмите **N**, вкладка **MCP for Blender**, проверьте **Start MCP Server**. В текущем дополнении также предусмотрен автозапуск.
5. Полностью перезапустите Codex. Попросите: «Проверь подключение к Blender и перечисли объекты сцены».

Для диагностики, когда другой MCP-клиент не подключён:

```powershell
.\.venv\Scripts\python.exe scripts/check_connection.py
```

Диагностика читает сцену, не изменяет её. Отсутствующий Blender приводит к ошибке, а не к сообщению об успехе.

## Комплект плагина

`plugin.json`, `mcp.json` и `skills/` подготовлены в формате Agent Plugins для настольного клиента. Перед запуском сервера требуется выполнить setup в той папке, где установлен комплект. Загрузка ZIP через интерфейс плагинов отдельно не проверялась; проверенный путь подключения — локальный MCP через Codex CLI. Не подключайте одновременно MCP из манифеста и дублирующую запись из config.toml.

Установка через CLI регистрирует MCP-сервер, но не устанавливает отдельно упакованный навык в каталог навыков Codex. Инструкции навыка доступны при установке комплекта как плагина; сам сервер также содержит инструкции для работы со сценой.

## Удаление и восстановление

`codex mcp remove codex-blender` удаляет созданную MCP-запись (если выбрали другое имя, укажите его). В Blender отключите и удалите установленное дополнение. После этого папку комплекта можно удалить. Не восстанавливайте старый config.toml целиком, если после установки появились другие настройки: сохраните их и удалите только эту запись.

## Состав и воспроизводимость

- `assets/blender_mcp.py` — дополнение upstream без изменений.
- `vendor/blender_mcp/` — зафиксированные исходники сервера upstream без изменений; лицензия в `vendor/LICENSE`.
- `scripts/` — launcher, установщик и проверка MCP.
- `requirements.lock.txt` — проверенные версии зависимостей Python; первая установка требует доступа к PyPI.
- `skills/blender-mcp/SKILL.md` — инструкции Codex.
- `VALIDATION.md` — фактически выполненные проверки и ограничения.

Формат подключения: [официальная документация MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). Формат комплекта: [официальная документация плагинов](https://developers.openai.com/plugins/build/plugins).

## Версия 1.1: студийные операции

Добавлены 11 специализированных навыков и два MCP-инструмента: `studio_capabilities` описывает параметры, `studio_action` выполняет операцию над явно заданными объектами. Поддержаны inspect, bevel, subdivide, decimate, remesh, sculpt_deform, uv_smart, material, keyframe, turntable, rigid_body, cloth, render_settings, save_copy. Новые инструменты находятся в scripts/studio_tools.py и scripts/studio_ops.py; исходники upstream не изменены.

Для ручного подключения через CLI навыки нужно дополнительно скопировать из skills в каталог навыков Codex без перезаписи существующих папок. Установка всего пакета через интерфейс плагинов отдельно не проверялась.

## Версия 1.2: пространственный осмотр

Добавлены `spatial_capabilities`, `spatial_inspect` и навык `blender-spatial-inspection`. Доступны связность сетки, координаты и связи элементов, плоские сечения, выборочные расстояния между поверхностями и сопоставление ориентиров через камеру. Для изображений используется уже существующий `look` с несколькими ракурсами, Wireframe и X-Ray.

[Инструкция по новым возможностям](docs/SPATIAL-INSPECTION-RU.md). Проверено 21 геометрической проверкой, 11 проверками через MCP и 19 регрессионными проверками студийных операций в Blender 5.2.2 LTS. Пакет содержит 13 инструментов и 13 навыков. Автоматическое восстановление по фото и проверка самопересечений не реализованы.

## Версия 1.3: обратимые локальные правки

Добавлены `edit_capabilities` и `edit_session`: снимок координат, локальное смещение с плавным спадом, численное сравнение и откат с защитой посторонних изменений. Всего **15 MCP-инструментов и 13 навыков**. [Инструкция](docs/LOCAL-EDIT-RU.md), [план развития](ROADMAP.md), [результаты проверки](VALIDATION.md).

Это инструменты управления и проверки, а не обучение модели скульптингу или автоматическое восстановление по одной фотографии. Снимки находятся в памяти текущего Blender и восстанавливают только базовые координаты вершин.

## Разработка и тесты

Запускайте тесты из корня репозитория. Скрипты `tests/test_*_ops.py` используют `bpy` и выполняются внутри Blender, а не обычным pytest.

```powershell
python scripts/test_blender.py --blender "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe"
.\.venv\Scripts\python.exe tests/test_mcp.py --blender "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe"
```

Первый запуск проверяет геометрию в отдельных фоновых процессах с factory startup. Второй запускает отдельный интерактивный Blender для проверки MCP и снимков viewport, порт по умолчанию 19877; нужно графическое окружение. Основная сцена пользователя и его настройки не используются. Логи и изображения сохраняются в игнорируемый `test-output/`.