BlockHand（積木之手）— Minecraft Education MCP

Дайте AI «руки и ноги» в Minecraft Education Edition: действия (передвижение агента, копание, размещение, обработка почвы, перенос), глаза (определение блоков, запрос координат, подписка на игровые события), созидание (десять геометрических фигур и попиксельные чертежи).

Работает через официально документированную команду подключения Minecraft Education /wsserver (alias — /connect), без внедрения в процесс, без изменения игровых файлов и без распознавания изображения. Команда подключения — официальный интерфейс; последующий протокол сообщений WebSocket не имеет публичных гарантий стабильности, поэтому после обновления игры требуется повторная проверка.

• 42 инструмента, 2 ресурса

• 216 модульных и интеграционных тестов, 1 smoke-тест stdio/жизненного цикла процесса без запуска игры, 1 live-проверка на реальном устройстве

• Не требует никаких аккаунтов, токенов или секретов; MCP runtime привязан только к loopback, не записывает игровые файлы или артефакты

1. Три шага для начала работы

Шаг первый: установка и сборка на каждой машине

cd /你的路徑/minecraft-edu
corepack pnpm install --frozen-lockfile
corepack pnpm run build

Node должен быть 22.23.1, как указано в .nvmrc проекта, pnpm зафиксирован через Corepack на версии 11.17.0. Зависимости нужно устанавливать локально и на Windows, и на Mac; не копируйте node_modules с другой операционной системы. Минимальные требования Minecraft Education на Mac — macOS 14.

Шаг второй: однократная регистрация MCP на этой машине

Поддерживаются Codex／Claude Code／Gemini CLI／Grok CLI, одинаково на Windows и macOS.

Сначала получите два абсолютных пути

При регистрации обязательно используйте абсолютные пути, нельзя писать просто node. Десктопные AI-инструменты запускаются из Finder/Проводника и не видят nvm, Homebrew или PATH из вашего shell; если написать node, в терминале это может работать, но в десктопной версии запуск провалится, а сообщение об ошибке обычно просто говорит «сервер не отвечает», и разобраться сложно.

macOS:

node -p "process.execPath"   # Node 絕對路徑
pwd                          # 專案絕對路徑（在 minecraft-edu 目錄下執行）

Windows (PowerShell):

node -p "process.execPath"
(Get-Location).Path

Ниже <NODE> обозначает абсолютный путь к Node, <REPO> — абсолютный путь к проекту. Точка входа сервера фиксирована: <REPO>/dist/index.js (на Windows — <REPO>\dist\index.js). Если путь содержит пробелы, всю строку нужно заключать в кавычки.

С помощью установщика (поддерживается всеми четырьмя, рекомендуется)

corepack pnpm run setup:codex     # 或 setup:claude / setup:gemini / setup:grok
corepack pnpm run doctor          # 加 --client=claude 等可診斷其他家

Установщик не просто записывает команду в файл конфигурации, он:

• Автоматически заполняет абсолютный путь к Node на этой машине, не полагаясь на то, сможет ли десктопная программа прочитать nvm, Homebrew или shell PATH.

• Сначала выполняет настоящую MCP initialize (с теми command／args／env, которые будут записаны), убеждается, что все 42 инструмента на месте, и только потом трогает какие-либо постоянные настройки. Старый dist, неправильный launcher, неисполняемый Node — всё это приведёт к ошибке до записи.

• При корректной регистрации ничего не делает, повторный запуск безопасен.

• При совпадении имени, но несовместимости останавливается и показывает различия, не делает автоматически remove/add, чтобы не перезаписать чужой timeout, tool policy или настройки другого клона.

• Записывает только через официальные подкоманды mcp add／mcp remove каждого клиента, не редактирует файлы конфигурации вручную — это обошло бы собственную проверку схемы и разрешение scope у каждого клиента.

Удаление — через corepack pnpm run uninstall:codex (или uninstall:claude и т.д.). Там тоже защита от случайного удаления: если entry не распознаётся как принадлежащий этому рабочему дереву, отказ.

Куда пишет каждый клиент и что нужно после:

Стратегии чтения различаются: у Codex и Grok есть mcp list --json, используется машиночитаемый вывод. У Claude Code и Gemini list — только человекочитаемый текст и не содержит env, по нему нельзя судить о совместимости, поэтому для них используется только чтение файлов конфигурации, только что записанных их официальными CLI. Запись всегда идёт через CLI.

Ручные команды (если не хотите использовать установщик)

Команды эквивалентны, но абсолютные пути нужно заполнять самому, и нет предварительной initialize-проверки и защиты от перезаписи.

codex  mcp add minecraft-edu --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js
claude mcp add minecraft-edu --scope user --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js
gemini mcp add minecraft-edu <NODE> <REPO>/dist/index.js --scope user --env MINECRAFT_EDU_WS_PORT=19131
grok   mcp add minecraft-edu --scope user --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js

Три частых различия, на которых легко споткнуться:

• В Gemini command и args — позиционные параметры, идут после имени, без разделителя --.

• В Gemini scope по умолчанию — project; для глобальной доступности нужно явно указать --scope user.

• В Claude scope по умолчанию — local (действует только в текущей директории); --scope project записывает в .mcp.json в корне проекта, можно расшарить вместе с репозиторием — используйте это для общего доступа в классе.

Ручное редактирование файла конфигурации (запасной вариант, если установщик не работает)

Claude Code и Gemini CLI используют JSON:

{
  "mcpServers": {
    "minecraft-edu": {
      "command": "<NODE>",
      "args": ["<REPO>/dist/index.js"],
      "env": { "MINECRAFT_EDU_WS_PORT": "19131" }
    }
  }
}

Codex и Grok CLI используют TOML:

[mcp_servers.minecraft-edu]
command = "<NODE>"
args = ["<REPO>/dist/index.js"]
env = { MINECRAFT_EDU_WS_PORT = "19131" }

Дополнения для Windows

• Абсолютный путь к Node обычно C:\Program Files\nodejs\node.exe, при использовании nvm-windows — примерно C:\Users\<вы>\AppData\Roaming\nvm\v22.23.1\node.exe.

• В JSON-файлах конфигурации обратные слэши нужно экранировать: "C:\\Program Files\\nodejs\\node.exe". В TOML можно использовать строковые литералы в одинарных кавычках: command = 'C:\Program Files\nodejs\node.exe'.

• Если Minecraft Education — UWP-версия из Microsoft Store, loopback будет заблокирован изоляцией приложений Windows, потребуется дополнительное исключение CheckNetIsolation LoopbackExempt (см. раздел 8).

После регистрации

Полностью выйдите и перезапустите AI-инструмент — в десктопной версии нужно действительно завершить программу, а не закрыть окно. Затем подтвердите с помощью doctor (не трогая Minecraft и не меняя настройки):

corepack pnpm run doctor

Он проверяет версию Node, артефакты сборки, требования платформы, статус регистрации и выполняет ещё одну MCP initialize с фактически зарегистрированными command／args／env, чтобы настройки, указывающие на нерабочий Node, не давали ложную зелёную галочку. Добавьте --json для структурированного вывода. Можно также напрямую спросить CLI каждого клиента:

codex mcp list
claude mcp list
gemini mcp list
grok mcp list

Или просто попросить AI вызвать mc_status — если он возвращает connectCommand, значит сервер поднимается.

Каждая машина должна регистрироваться отдельно: у Windows-ноутбука, Mac и другого компьютера разные пути к Node и к проекту, настройки нельзя копировать друг у друга. На одной машине десктоп／CLI／IDE одного и того же инструмента используют один общий файл настроек.

Шаг третий: вручную подключиться из игры

corepack pnpm run connect

Этот совместимый вход только показывает способ действий, не запускает Minecraft, не переключает окно на передний план и не имитирует клавиатуру. Функция автоматического ввода в Windows PowerShell удалена; на Mac тоже нет автоматизации через AppleScript.

Направление легко перепутать: игра — та сторона, которая подключается наружу, MCP server — та, к которой подключаются.

1. В текущем диалоге с AI вызовите mc_status, скопируйте возвращаемый им connectCommand.

2. Откройте Minecraft Education, войдите в мир (остановка в главном меню не поможет).

3. В мире должны быть включены Cheats, у оператора должны быть права Admin／OP.

4. Вручную введите в строке чата, например:

/connect 127.0.0.1:19131

Когда увидите Connection established — готово. После этого можно сказать AI «построй передо мной полый стеклянный шар».

Для повторного подключения не нужно вводить всё заново: в строке чата нажмите T, затем ↑, чтобы вызвать предыдущую команду, и Enter.

В ранних версиях был баг «обязательный разрыв соединения через ~60 секунд простоя»: heartbeat распознавал только WebSocket pong frame, но клиент Bedrock／Education никогда не отвечает pong, из-за чего здоровое соединение убивалось собственным heartbeat. Сейчас исправлено (активность определяется по любому входящему пакету плюс зондирование на уровне приложения), простой больше не должен вызывать разрыв. Если всё ещё рвётся — сначала убедитесь, что вы запускаете пересобранный dist/.

Не заучивайте наизусть 19131: при одновременном запуске десктопа, CLI, IDE или нескольких задач позже запущенный MCP может получить другой свободный порт. Всегда используйте команду, которую сообщает та задача, с которой вы сейчас работаете.

Related MCP server: Minecraft MCP Bot

2. Проверка на реальном устройстве

Сначала безопасная диагностика без запуска игры:

corepack pnpm run doctor
# 機器可讀版本
corepack pnpm blockhand doctor --json

doctor не изменяет постоянные настройки и не запускает Minecraft; он ненадолго создаёт изолированный loopback socket, проверяет launcher, 42 tools, 2 resources, stdio EOF, освобождение порта прослушивания и выполняет ещё одну initialize с фактически зарегистрированными command／args／env Codex, чтобы настройки, указывающие на нерабочий Node, не давали ложную зелёную галочку.

После того как игра открыта, мир загружен и читы включены:

cd gjlmotea/vibe/mcp/minecraft-edu && corepack pnpm run live

Скрипт печатает /connect, который нужно ввести, ждёт подключения, затем проходит полный путь и сообщает PASS／FAIL по каждому пункту: подключение → чтение координат игрока → сообщение в игре → установка времени → призыв агента → сенсорика → движение по L-образному пути → предпросмотр постройки → полый стеклянный шар → обратная проверка, что блоки действительно существуют → объединение чертежей → подписка и получение событий → политический шлюз → очистка демонстрационных построек.

После обновления игры

Чтение блоков (mc_read_block) опирается на текстовый формат сообщения об ошибке testforblock — у этого формата нет никаких официальных гарантий стабильности. Если Minecraft Education тихо автообновилась и изменила текст, или язык игры переключён не на традиционный/упрощённый китайский или английский — этот путь перестанет работать.

Сбой выглядит тихо: инструмент не сломается, он просто начнёт говорить «не могу прочитать». Поэтому проект намеренно не делает это рутинной проверкой при каждом live-запуске — рутинные проверки приучают успокаиваться при зелёной лампочке, а момент, когда действительно нужно судить, — это «когда поведение стало подозрительным», а не еженедельный фиксированный прогон.

Вместо этого — активная проверка по необходимости:

mc_verify_reading  { position: 任一座標 }

Он отправляет максимум две команды, полностью не записывает в мир, возвращает parseable:

• true → путь разбора в норме, результат mc_read_block можно доверять.

• false → протокол ушёл вперёд. В этом случае mc_read_block всегда возвращает ошибку, а не null (см. раздел 3), так что никто не примет «не могу прочитать» за «там пусто». Возвращаемый raw — исходное сообщение игры; сверьте его с PATTERNS в src/domain/block-report.ts, чтобы понять, какую строку нужно добавить.

Три сигнала, при которых захочется запустить его:

1. mc_read_block начал возвращать ошибки, но вы видите в игре, что в этой клетке точно что-то есть.

2. Игра только что обновилась, а вам дальше нужно делать что-то, зависящее от чтения (проверка работ, анализ симметрии).

3. Сменился язык игры.

В server instructions заложена та же подсказка, так что AI сам найдёт этот инструмент при подозрительном поведении — вам не нужно помнить о нём и напоминать.

По умолчанию демонстрационные постройки заполняются обратно air, в мире не остаётся мусора. Чтобы оставить их для просмотра:

cd gjlmotea/vibe/mcp/minecraft-edu && node scripts/live-check.mjs --keep

Проверка без запуска игры (типы, тесты, сборка, stdio-рукопожатие, освобождение порта при закрытии STDIN и провал при занятом порту — всё за один прогон):

cd gjlmotea/vibe/mcp/minecraft-edu && corepack pnpm run verify

3. Инструменты

Подключение и запасные варианты (4)

Агент — руки и ноги (10)

Направление агента — относительно его собственного разворота, а не сторон света.

Мир (13)

mc_set_block, mc_fill, mc_clone, mc_test_block, mc_read_block, mc_verify_reading, mc_compare_regions, mc_analyze_symmetry, mc_query_target, mc_summon, mc_world_settings (время／погода／игровые правила／сложность), mc_structure (сохранение и загрузка структур), mc_ticking_area.

mc_query_target разбирает JSON-строку, возвращаемую querytarget, — это правильный способ получить координаты игрока или агента: сначала спросите его перед постройкой.

У чтения есть врождённые ограничения, лучше сказать о них честно, чем делать вид, что их нет. В Education нет команды «прочитать произвольный блок», поэтому:

• mc_test_block — вопрос «да/нет»: вам нужно сначала угадать ID блока.

• mc_read_block не требует угадывания — он использует воздух как сторожевой блок, и при неверной догадке игровое сообщение называет фактический блок. Но возвращается локализованное отображаемое имя («земля»), а не ID блока (dirt), и его нельзя скормить обратно в mc_set_block. При невозможности разобрать инструмент возвращает ошибку, а не успешный ответ с null — причина ниже.

• mc_verify_reading активно проверяет, что путь разбора выше всё ещё работает. Один запуск перед занятием — и вы знаете, можно ли доверять результату mc_read_block.

• mc_compare_regions сравнивает целую область одной командой testforblocks. Поштучное сравнение клеток на нескольких сотнях клеток упрётся в таймаут хоста, а это — нет. Режим masked игнорирует воздух источника, подходит для проверки «есть ли нужное» независимо от того, что лишнего вокруг — проверка работ учеников имеет именно такую форму.

Почему при сбое разбора возвращается ошибка, а не null

Потому что пользователь этого инструмента — AI, а AI не подозревает, что система сломана.

«Успешный» ответ с block: null легко прочитать как «прочитано, там пусто». Затем AI с большой уверенностью продолжит действовать на основе этого ошибочного представления — например, закроет работу, которую ученик строил весь урок, как пустое место, и после этого не останется никакой записи об ошибке, которую можно было бы проверить. Человек, увидев null, заподозрит неладное и остановится для отладки; AI — нет.

Ошибку нельзя продолжать использовать как данные — в этом суть.

mc_verify_reading — вторая половина: ему не нужно заранее знать, что в клетке — если там воздух, он спрашивает про bedrock (воздух не может быть bedrock, несовпадение гарантировано), вынуждая сообщение об ошибке; если там что-то есть, первый же вопрос уже дал сообщение. Оба пути гарантированно дают сообщение, максимум две команды, полное отсутствие записи в мир.

Эту линию обороны охраняют мутационные тесты: если намеренно сломать правила разбора, 7 тестов зондирования и парсера должны покраснеть.

Для поштучного чтения целой области используйте behavior pack и Script API; этот проект намеренно не идёт этим путём, потому что это добавило бы лишний шаг установки на школьные компьютеры.

Многократное изменение одного и того же здания

saveMode у mc_structure создан именно для этого:

Управление версиями — это имена: castle_v1, castle_v2. Одноимённые перезаписываются напрямую; перед сменой версии сначала смените имя.

В игре нет команды «список сохранённых структур», поэтому о том, что сохранено, можно помнить только по именам. Мост запоминает список сохранённого за текущее подключение — спросите mc_status и увидите; но это покрывает только текущий процесс, после перезапуска его нет (файлы режима disk остаются, имена нужно помнить самому).

Анализ симметрии — проверка работ

mc_analyze_symmetry проверяет, зеркально ли симметрична область, и при асимметрии указывает, какие именно блоки несимметричны, а не просто выдаёт «нет».

Принцип: testforblocks делает только параллельный перенос без зеркалирования, поэтому сначала область сохраняется через structure save, затем с параметром mirror structure load зеркально размещается во временной зоне, и две области сравниваются. Полное совпадение — сразу полный балл; при несовпадении — детальный разбор по n³ клеткам, оценка — доля совпавших клеток.

Этот инструмент временно записывает в мир, процесс следующий, при сбое на любом шаге не остаётся мусора:

1. Сохранить анализируемую область — при сбое остановиться (обычно область чанков не загружена).

2. Сначала сделать резервную копию временной зоны — при сбое резервирования остановиться, и зеркальная копия ни в коем случае не размещается, мир невредим.

3. Разместить зеркальную копию, сравнить.

4. Независимо от результата восстановить временную зону и удалить временную структуру; результат восстановления честно сообщается в scratchRestored, при сбое не приукрашивается.

Временная зона не должна пересекаться с анализируемой, иначе зеркальная копия перекроет исходное здание — эта проверка выполняется до отправки любых команд.

Игрок и обратная связь (7)

mc_teleport, mc_give, mc_gamemode, mc_effect, mc_player_action (kill／clear／xp／ability), mc_message (say／tell／title／subtitle／actionbar), mc_feedback (звук／частицы).

Строительство (4)

События — восприятие (4)

mc_events_catalog, mc_events_subscribe, mc_events_unsubscribe, mc_events_poll.

События попадают в кольцевой буфер, читаются непрерывно через курсор; dropped > 0 означает, что опрос слишком медленный и часть событий потеряна навсегда. После переподключения подписки восстанавливаются автоматически.

4. Почему строительство не зависает

Наивный подход — отправлять setblock на каждый блок. У сплошного шара радиусом 20 более 33 000 клеток — это более тридцати тысяч WebSocket-обходов — на практике это эквивалент зависания.

Конвейер BlockHand:

形狀參數 → inside() 判定掃描 → 方塊座標集合
        → X 連段合併 → Z 矩形合併 → Y 立方合併（三階段 greedy）
        → 依 Bedrock 單次 /fill 上限 32768 拆批
        → 送出

Сплошной шар радиусом 8 сжимается с более чем 2 000 блоков до менее чем 200 команд, и результат объединения детерминирован — один и тот же вход всегда даёт один и тот же набор batch-команд, поэтому есть тест, фиксирующий «множество блоков, покрытых после объединения, должно в точности совпадать с исходным множеством точек» — ни больше, ни меньше.

Полые формы всегда реализуются через «внутренний тест + тест соседей оболочки», а не отдельной полой математикой для каждой формы. Для новой формы достаточно написать inside(), и полое поведение автоматически согласовано.

5. Границы безопасности

Чего мы не делаем

• Не подключаемся к внешней сети: WebSocket-прослушивание только на 127.0.0.1.

• MCP runtime не пишет файлы на хост: нет ни одного пути вывода артефактов. Только когда пользователь явно выполняет setup:<client>／uninstall:<client>, официальный CLI соответствующего клиента обновляет локальные настройки MCP.

• Одно исключение нужно проговорить: saveMode="disk" у mc_structure через игру сохраняет структуру в файл в папке мира Minecraft. Это не MCP runtime пишет файл, но на диске пользователя действительно что-то остаётся. Поэтому по умолчанию — memory (временное, исчезает при закрытии игры), disk следует использовать только когда пользователь явно попросил сохранить, и ответ инструмента обязательно сообщает, куда именно записано — никакого тихого оставления файлов.

• Не трогаем секреты: во всём проекте нет токенов, аккаунтов или сертификатов.

• Не подключаемся по своей инициативе: если игра не выполнила /connect, все инструменты возвращают понятные сообщения об ошибке с инструкциями, без тихого сбоя.

Шлюз для mc_run_command

Архитектурный принцип 4 в mcp/README.md требует отказа от произвольной точки входа выполнения. Здесь суждение такое: область действия slash-команд полностью ограничена локальным игровым миром, не касается файловой системы хоста, процессов или сети, поэтому это не эквивалент произвольного выполнения кода. Действительно нужно блокировать операции, которые выводят мост из строя, поэтому политика структурная, а не чёрный список ключевых слов по догадке о намерении:

1. Разрешена только одна строка — перевод строки и NUL отклоняются напрямую, нельзя через \n разбить один запрос на две команды.

2. Отклоняются wsserver и connect — это перенаправит игру на другой endpoint, после чего все инструменты перестанут работать.

3. Остальные команды помечаются уровнем риска read-only／world-write／wide-effect, решение о ручном подтверждении принимает MCP Host на основе annotation.

Все ID блоков, селекторы и строки состояния, которые вставляются в командную строку, сначала проходят через whitelist-регулярные выражения, чтобы пробелами нельзя было собрать дополнительные параметры.

Защита для класса (включена по умолчанию)

Пункт 3 выше отдаёт решение Host — это работает в сценарии индивидуальной разработки, но место использования этого проекта — классная комната:

• Host может быть настроен на автоматическое подтверждение — учителю легко так сделать ради плавности урока.

• Ученик, который может говорить с этим AI, фактически может отдавать команды. Ему не нужно взламывать мост, достаточно убедить модель.

• Для злоупотребления даже не нужны raw-команды: mc_player_action и так принимает @a, и kill — один из вариантов. Поэтому блокировать только raw-команды — это игра в театр, блокировать нужно оба пути.

Правило формулируется так, чтобы его можно было объяснить учителю одной фразой: действия, направленные на «людей», должны называть их по имени.

«Убить весь класс» превращается из одной фразы в необходимость называть каждого по имени, а легальное управление классом (очистить инвентарь конкретного ученика) полностью не затрагивается.

Чтобы отключить, задайте MINECRAFT_EDU_CLASSROOM_GUARD=0 — само сообщение об ошибке скажет вам об этом, никто не подумает, что инструмент сломан.

Товарные знаки

Согласно Minecraft Usage Guidelines, сторонние инструменты не должны выглядеть как официальные продукты. Название продукта BlockHand намеренно не содержит товарный знак Minecraft; minecraft-edu — это лишь описательное имя папки в этом приватном рабочем пространстве. Если в будущем планируется публичный выпуск, имя пакета и любые публичные упоминания должны быть пересмотрены.

6. Настройка

Все параметры имеют значения по умолчанию, .env не обязателен.

7. Карта модулей

src/
  domain/                     純資料與純邏輯，不依賴 MCP、ws 或 Node
    contracts.ts              型別、已知事件名、Bedrock fill 上限
    coordinates.ts            絕對／相對／局部座標格式化與邊界檢查
    commands.ts               所有 slash 指令建構器 + 注入白名單
    command-policy.ts         raw 指令的結構性閘門
    build/shapes.ts           十種形狀；inside() + 外殼鄰居測試
    build/fill-planner.ts     三階段 greedy 合併 + 依上限拆批
  ports/minecraft-connection.ts   連線抽象；測試靠它塞假件
  adapters/ws-minecraft-connection.ts  WebSocket 監聽、requestId 對應、事件緩衝、重連重訂閱
  application/
    blockhand-service.ts      Agent 程式展開、querytarget 解析、事件
    build-service.ts          規劃與執行分離（先讀後寫）
  server/
    create-server.ts          server 實例與給 Host 的操作指引
    schemas.ts                共用 zod 片段
    tool-kit.ts               回應塑形與錯誤包裝
    tools/                    session／agent／world／player／build／event
  composition.ts              組裝；可注入假連線
  index.ts                    stdio 入口

Доменный слой полностью не знает о существовании WebSocket, поэтому весь конвейер инструментов MCP можно протестировать с помощью чисто мнимых компонентов в памяти — все 16 тестов в tests/integration/mcp-client.test.ts не требуют запуска игры.

8. Известные ограничения

• В мире должны быть включены читы, иначе игра отклонит каждую команду. Это правило Minecraft, а не ошибка.

• На macOS проведена полная проверка на реальном устройстве (путь Claude Code): 2026-08-25 на macOS через Claude Code выполнены /connect, массовые чтения и записи (более 45 000 блоков за одну сессию, включая fill/setblock/testforblock/teleport) и полный цикл переподключения. Не проверен путь запуска «запуск Codex Desktop из Finder» — при запуске через GUI наследование PATH и переменных окружения отличается, требуется отдельное тестирование.

• Агент — эксклюзив Education Edition, в обычной версии Bedrock этой функции нет.

• Имена событий и подкоманды agent официально не документированы Mojang, они основаны на публичных наблюдениях; обновления игры могут изменить поведение. mc_events_subscribe допускает имена вне списка, но помечает их как непроверенные.

• Порядок параметров agent setitem не подтверждён, в настоящее время для этого нет специального инструмента; при необходимости используйте mc_run_command.

• @s может не разрешаться в командах WebSocket: команды, передаваемые через мост, не имеют идентичности сущности; на практике querytarget @s не даёт никакого ответа. Поэтому mc_query_target по умолчанию использует @p (ближайшего игрока), а live последовательно пробует @p → @a → @e[type=player] и сообщает результат каждого шага.

• Крупные постройки могут столкнуться с тайм-аутом запроса MCP Host: инструменты строительства отправляют fill по одному и ждут ответа игры; на практике полая сфера радиусом 6 (126 команд) занимает около 13 секунд, но при загруженной игре может быть дольше. Тайм-аут по умолчанию у MCP-клиентов обычно 60 секунд; при превышении запрос обрывается на стороне Host (сам инструмент продолжает работать). Сначала используйте mc_build_preview для просмотра fillBatches; при большом количестве стройте партиями.

• Каждый процесс BlockHand по-прежнему удерживает один порт прослушивания: после закрытия STDIO-клиента сервер синхронно закрывает WebSocket Minecraft и освобождает порт. Когда настольная версия AI-инструмента загружает несколько задач одновременно, или при параллельной работе настольной версии/CLI/IDE, первый экземпляр получает предпочтительный порт, остальные автоматически получают свободные порты; всегда используйте mc_status.connectCommand текущей задачи, чтобы игра подключалась к нужному экземпляру. Если нужен фиксированный порт, задайте разные MINECRAFT_EDU_WS_PORT для каждого клиента или установите MINECRAFT_EDU_WS_PORT_FALLBACK в 0.

• Первая команда после рукопожатия раньше всегда истекала по тайм-ауту, теперь исправлено: это воспроизводилось в четырёх независимых запусках на реальном устройстве — игра отправляет зашифрованный кадр до того, как сервер установит дешифратор, что приводит к смещению потока и невозможности прочитать ответ на следующий запрос. AES-CFB8 самосинхронизируется, поэтому затрагивается только первая команда. Теперь адаптер после завершения рукопожатия автоматически отправляет read-only time query daytime, чтобы поглотить эту потерю и отбросить результат; первое действие вызывающей стороны работает нормально. В stderr записывается primed post-handshake stream.

• События срабатывают только при реальном возникновении: BlockPlaced отправляется только когда игрок ставит блок вручную; /setblock и /fill не считаются. Чтобы получать события, нужно сначала подписаться, а затем дождаться реального события.

• requestId частичных ответов не совпадает с запросом (наблюдаются ответы с полностью нулевым ID). Адаптер, когда остаётся только один ожидающий запрос, приписывает ответ ему и записывает в stderr, что это вывод; в противном случае такие запросы молча истекают по тайм-ауту, и вызывающая сторона видит только «нет реакции», а не реальную причину сбоя.

• Одновременно поддерживается только одно игровое соединение; новое соединение заменяет старое.

• Проверенная среда на реальном устройстве: Minecraft Education 1.26.32.0 (Win32 desktop). При использовании UWP-версии из Microsoft Store loopback блокируется изоляцией приложений Windows, требуется дополнительное исключение CheckNetIsolation LoopbackExempt. Матрица приёмки для macOS 14+ приведена в agents/docs/macos-support.md.

9. Лицензия

Проект выпущен под лицензией MIT. Вы можете свободно использовать, изменять, распространять и сублицензировать его, включая коммерческое использование, при единственном условии сохранения исходного уведомления об авторских правах и условий лицензии.

Программное обеспечение предоставляется «как есть», без каких-либо явных или подразумеваемых гарантий.

Minecraft, Minecraft Education являются товарными знаками Mojang Studios и Microsoft; этот проект не аффилирован с ними и не одобрен ими.