96 lines
9.9 KiB
Markdown
96 lines
9.9 KiB
Markdown
# 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 блоков на план, только загруженные чанки и ограниченный набор ванильных материалов. Полный журнал дельт, автоматическое объединение ручных правок и все возможности дизайн-документа ещё не реализованы. [Подробный статус и ограничения](docs/IMPLEMENTATION.md).
|
|
|
|
## Сборка
|
|
|
|
Проверенная среда — Linux x64, Minecraft/Paper 26.2, Java 25, Node.js 22.22.3+. Из корня репозитория:
|
|
|
|
```bash
|
|
./scripts/build.sh
|
|
```
|
|
|
|
Скрипт загружает закреплённые JDK 25.0.2 и Maven 3.9.11 в пользовательский кэш с проверкой хешей, устанавливает зависимости Bridge по lockfile и собирает все три компонента с тестами. Системная Java не меняется. Нужны уже установленные Python 3, Node.js и npm. [Закреплённые версии](docs/compatibility.json).
|
|
|
|
Результаты:
|
|
|
|
- `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](https://www.minecraft.net/eula), затем принять её явно:
|
|
|
|
```bash
|
|
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 <имя>`. В игре выполнить:
|
|
|
|
```text
|
|
/ai setup
|
|
/ai area here
|
|
```
|
|
|
|
Вторая команда выбирает участок вокруг игрока. Чанки должны быть загружены, а рядом с местами записи — поддерживаемые блоки. Точные границы можно задать через `/ai area minX minY minZ maxX maxY maxZ`.
|
|
|
|
3. В другом терминале из корня проекта проверить настройки и войти в отдельный профиль Codex:
|
|
|
|
```bash
|
|
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. Запустить чат:
|
|
|
|
```bash
|
|
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. Точный порядок и ограничения снимка — в [инструкции камеры](camera-mod/README.md). После подключения `/ai camera save name` сохраняет ракурс владельца. [Результат локального теста с одним клиентом](docs/ONE_CLIENT_TEST.md).
|
|
|
|
## Проверки и документы
|
|
|
|
```bash
|
|
./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`.
|
|
|
|
- [Дизайн проекта и дальнейшие этапы](docs/DESIGN.md).
|
|
- [Что реализовано и чем проверено](docs/IMPLEMENTATION.md).
|
|
- [Готический зал по референсу: 29 354 блока в живом мире](docs/builds/GOTHIC_HALL.md).
|
|
- [Протокол](docs/PROTOCOL.md), [ядро и журнал](world-core/README.md).
|
|
- [Bridge, вход и ограничения ACP](bridge/README.md).
|
|
|
|
Git инициализирован, ветка `main`. Сгенерированные миры, секреты, зависимости и сборки исключены через `.gitignore`.
|