minecraft-builder-mcp

Строительный редактор Minecraft для совместной работы человека и ИИ-агента.

Рабочий прототип: Paper-плагин, ядро редактирования, MCP/ACP Bridge и Fabric-мод камеры. Строительство, конфликты, undo, аварийное восстановление и .schem проверены на локальном Paper через HTTP и настоящий MCP stdio. Камера проверена в Prism с одним клиентом: настоящий PNG 1280×720 передан через MCP. Вход в отдельный профиль Codex и первый ход модели через ACP ещё предстоит проверить.

Что умеет

• Читает ограниченные участки и строит коробки, линии, цилиндры и повторяющиеся элементы.
• Сначала сохраняет план, затем применяет его порциями с проверкой текущих блоков. Ручное изменение останавливает конфликтующую запись; отмена тоже проверяет состояние мира.
• Хранит журнал на диске, различает повтор запроса и новую операцию, останавливает неоднозначные операции после сбоя.
• Сохраняет именованные части и их защиту, экспортирует и импортирует ограниченный Sponge v2 .schem через тот же механизм планов.
• Даёт 14 MCP-инструментов и /ai для игрового чата через закреплённый codex-acp.
• Снимает настоящие изображения через локальный Worker на spectator-клиенте. Проверен также один клиент с временным переключением владельца в spectator.

Сейчас это один владелец, один проект и один мир, до 4096 блоков на план, только загруженные чанки и ограниченный набор ванильных материалов. Полный журнал дельт, автоматическое объединение ручных правок и все возможности дизайн-документа ещё не реализованы. Подробный статус и ограничения.

Сборка

Проверенная среда — Linux x64, Minecraft/Paper 26.2, Java 25, Node.js 22.22.3+. Из корня репозитория:

./scripts/build.sh

Скрипт загружает закреплённые JDK 25.0.2 и Maven 3.9.11 в пользовательский кэш с проверкой хешей, устанавливает зависимости Bridge по lockfile и собирает все три компонента с тестами. Системная Java не меняется. Нужны уже установленные Python 3, Node.js и npm. Закреплённые версии.

Результаты:

• paper-plugin/target/paper-plugin-0.1.0-SNAPSHOT.jar — серверный плагин, ядро включено.
• camera-mod/build/libs/minecraft-builder-camera-0.1.0-SNAPSHOT.jar — клиентский мод.
• bridge/dist/ — исполняемые MCP/ACP-компоненты.

Локальный запуск

1. Подготовить отдельный тестовый Paper. На первой установке прочитать Minecraft EULA, затем принять её явно:

   python3 scripts/dev-server.py --accept-eula --run
   

   Для последующих запусков достаточно python3 scripts/dev-server.py --run. Сервер хранится в .runtime/server, слушает 127.0.0.1:25575, вход в Minecraft остаётся включён. Для уже подготовленного в этой рабочей папке сервера EULA принята пользователем.

2. Подключиться клиентом Minecraft Java 26.2 к 127.0.0.1:25575. В консоли этого сервера выдать своему игровому имени op <имя>. В игре выполнить:

   /ai setup
   /ai area here
   

   Вторая команда выбирает участок вокруг игрока. Чанки должны быть загружены, а рядом с местами записи — поддерживаемые блоки. Точные границы можно задать через /ai area minX minY minZ maxX maxY maxZ.

3. В другом терминале из корня проекта проверить настройки и войти в отдельный профиль Codex:

   python3 scripts/bridge.py doctor
   python3 scripts/bridge.py login
   python3 scripts/bridge.py login --status
   

   Вход выполняется самим пользователем по device code. Помощник читает локальные токены Paper без вывода в терминал. Обычный профиль ~/.codex не копируется; состояние проекта хранится в .runtime/bridge-state. Первый настоящий ход ещё должен подтвердить авторизацию и разрешения MCP у закреплённого адаптера.

4. Запустить чат:

   python3 scripts/bridge.py chat
   

   Теперь можно отправить /ai Построй небольшую башню рядом со мной. Для выбора модели доступна переменная MCB_MODEL; без неё выбор остаётся за адаптером. /ai status показывает состояние, /ai stop останавливает дальнейшую запись и запрос к агенту. Уже сделанные изменения отменяются отдельным проверяемым undo.

MCP можно подключить к внешнему клиенту командой python3 scripts/bridge.py mcp. Область владельца берётся из конфигурации Paper. Команда предназначена для запуска клиентом MCP по stdio, а не для интерактивного терминала.

Камера

Обычному игроку мод не нужен. Для наблюдателя установить Fabric Loader и API указанных версий, добавить JAR камеры в отдельный профиль 26.2. Перед запуском передать этому процессу MCB_CAMERA_TOKEN из поля camera-token приватной конфигурации плагина; в Paper заполнить camera-player-uuid и перезапустить сервер. Наблюдатель должен быть подключён к нему в spectator.

Если строитель и наблюдатель играют одновременно, нужны допустимые отдельные игровые сессии. Для одного клиента можно указать UUID владельца и временно включать spectator. Такой сценарий уже проверен в профиле Prism 26.2 MCP Building; секрет передаётся Java через scripts/camera-wrapper.py, без добавления в логируемые переменные Prism. Точный порядок и ограничения снимка — в инструкции камеры. После подключения /ai camera save name сохраняет ракурс владельца. Результат локального теста с одним клиентом.

Проверки и документы

./mvnw test
npm --prefix bridge test
JAVA_HOME="$HOME/.cache/minecraft-builder-mcp/jdk-25.0.2" camera-mod/gradlew --project-dir camera-mod test

python3 scripts/live-server-test.py запускает и останавливает собственный процесс в .runtime/server, проверяет конфликты и undo, намеренно завершает этот процесс для проверки восстановления, затем прогоняет MCP и .schem. Для него сначала собрать проект, один раз запустить плагин и принять EULA; текущий сервер должен быть остановлен. Проверка предназначена для подготовленного тестового мира и изменяет только ограниченные тестовые области. Результаты сохраняются в .runtime/live-server-results.json и .runtime/live-mcp-results.log.

• Дизайн проекта и дальнейшие этапы.
• Что реализовано и чем проверено.
• Готический зал по референсу: 29 354 блока в живом мире.
• Протокол, ядро и журнал.
• Bridge, вход и ограничения ACP.

Git инициализирован, ветка main. Сгенерированные миры, секреты, зависимости и сборки исключены через .gitignore.