pm-minecraft

Автономное выживальческое тело Minecraft для MCP-клиентов.

Оно запускает Mineflayer, Prismarine Viewer, локальный веб-интерфейс и Streamable HTTP MCP-сервер.

Оно не содержит агента, модели или когнитивной среды выполнения. Только минимальные инструкции, подсказывающие вашему агенту, как использовать MCP, смотреть на скриншоты и создавать собственные TypeScript-скрипты, которые можно выполнять через MCP.

Огромное спасибо https://github.com/minedojo/voyager и https://github.com/Mega-Gorilla/Discovery :3

Это часть моих постоянных усилий по созданию забавного когнитивного ИИ-компаньона, который сможет играть с вами в Minecraft. Также работает и как самостоятельная штука ^_^

Установка

Требования: Windows PowerShell, Node.js 20+, Python 3.12 через py и достижимый сервер Minecraft Java 1.19.x с персонажем в режиме выживания.

Set-Location C:\workspace\pm-minecraft-mcp
.\setup.ps1

Установка следует общему рабочему процессу PM: она использует uv для создания .venv Python 3.12 этого репозитория, синхронизирует его lockfile и устанавливает заблокированные Node-пакеты. scripts/setup.ps1 остаётся как обёртка для совместимости.

Если что-то не работает, скажите вашему кодинг-агенту это исправить.

Related MCP server: Godot MCP Runtime

Minecraft

Я украл настройку у https://github.com/Mega-Gorilla/Discovery.

Я никогда вручную не модил Minecraft, вот что работает у меня:

• Скачайте Prism

• Установите 1.19.4

• Установите Fabric Loader 0.19.3

• Установите эти моды через Prism:

  • Fabric API

  • CompleteConfig

  • Mod Menu

  • Multiplayer Server Pause (Forge)

  • item-pickup-range от wenhao (/setPickupRange 5)

• Создайте мир выживания, с читами, в мирном режиме

• Зайдите и "Открыть для LAN" на порту 12345

Создание и запуск персонажа

.\scripts\init_character.ps1 `
  -Name Floppa `
  -AgentRoot C:/Temp/Floppa `
  -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

.\scripts\start_minecraft_mcp.ps1 `
  -Name Floppa `
  -MinecraftHost 127.0.0.1 `
  -MinecraftPort 12345 `
  -AgentRoot C:/Temp/Floppa `
  -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

Инициализатор создаёт рабочее пространство агента: memory/minecraft/, drafts/, skills/, lib/minecraft.ts и .mcp.json. Запускающий скрипт выводит URL локального веб-интерфейса, Prismarine viewer и MCP. Для нескольких персонажей используйте уникальные значения -WebPort, -ViewerPort и -McpPort.

Каждый пример из deploy/drafts/*.ts копируется в drafts/ рабочего пространства и перечисляется в его AGENTS.md. Они работают как есть через minecraft_execute_typescript, так что агент может выполнить один из них напрямую или скопировать его форму guard-and-verify в новый черновик. Добавьте пример в deploy/drafts/, чтобы он поставлялся с каждым новым персонажем.

Агент может вызвать minecraft_list_capabilities перед тем, как написать новое поведение. Если ни одна возможность не подходит, агент пишет TypeScript-черновик из общих действий тела. Агент запускает черновик с детерминированным постусловием. После успешного запуска minecraft_promote_skill копирует черновик в skills/. Запись о продвижении включает хэш исходника, ID выполнения и постусловие.

Наблюдения за сущностями включают стабильные ID времени выполнения, пока сущность загружена. Общее действие attack_entity выполняет одну обычную атаку в режиме выживания по наблюдаемому ID. Для цели убийства агент должен проверить результат выживания, например, увеличение инвентаря. Навык может сочетать наблюдение, перемещение, экипировку, атаки и проверку в такие поведения, как охота.

Остановите экземпляр с помощью:

.\scripts\stop_minecraft_mcp.ps1 -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

Затем используйте его из рабочего пространства:

Set-Location C:/Temp/Floppa
codex

Codex читает .mcp.json. Подскажите ему использовать сервер minecraft; логи состояний и скриншоты находятся в ./artifacts/minecraft.

Режимы восприятия и просмотра

minecraft_find_block по умолчанию использует require_visible: true. Это обычная настройка выживания: она возвращает только блоки с беспрепятственным лучом от головы персонажа. Агент должен исследовать, переместиться в лучшую точку обзора или использовать другое наблюдение, когда не видит цель. Для дальнего планирования установите require_visible: false; результат — это только местоположение в загруженном мире, до которого всё равно нужно добраться и визуально проверить перед добычей.

Логирование на диск

Всё записывается в корень артефактов персонажа (artifacts/minecraft/):

• states/ — один необработанный полный файл состояния на снимок (<timestamp>-mcstate-<id>.yaml). Каждое состояние хранит только те сообщения чата, которые впервые появились в этом состоянии, поэтому каждое сообщение чата существует ровно один раз во всём дереве; восстановите транскрипт, пройдя по файлам по порядку. Каждое состояние ссылается на свой скриншот; оно никогда не содержит байтов изображения или дублированных метаданных скриншота. current_state.yaml — это файл-указатель, который содержит только относительный путь последнего состояния.

• screenshots/ — единственное место, где живут картинки (.png плюс небольшой метаданный sidecar на кадр). Состояния и действия только ссылаются на них.

• actions/ — один плоский yaml на каждый вызов MCP-инструмента, названный <timestamp>_<tool>.yaml, записываемый на лету (стартовый файл с инструментом и входными данными появляется в момент начала вызова, ссылки на состояние до/после + скриншот добавляются по мере создания снимков, а необработанный красиво отформатированный вывод инструмента, длительность и любые исключения попадают в финальную перезапись). Поля: tool, tool_input, tool_output (оба — красивые JSON-блочные скаляры), четыре ссылки before_state_path / before_screenshot_path / after_state_path / after_screenshot_path (пустые, когда инструмент не создал состояния, только before для таких инструментов, как minecraft_observe, которые создают одно), плюс заголовки для поиска, такие как execution_id / skill_path для навыков. Успех или неудача читаются прямо из возвращаемых данных в tool_output; исключения попадают в блок error:.

• mcp-server.log — все перехваченные ошибки тела/сети и все необработанные исключения (с traceback) попадают сюда.

Результаты инструментов возвращают те же ссылки (beforeStatePath / afterStatePath / beforeScreenshotPath / afterScreenshotPath) вместо встраивания всего состояния, поэтому модель обращается к файлам, когда ей нужны детали.

Скриншоты захватываются и записываются в artifacts/minecraft/screenshots для каждого состояния — до и после каждого действия, при каждом вызове minecraft_observe — независимо от include_image, если сервер запущен с включённым захватом изображений (по умолчанию; отключите с помощью --no-images). Это даёт полную, бесшовную визуальную историю запуска на диске для последующего анализа, даже для состояний, на которые агент сам никогда не смотрел.

include_image управляет только тем, прикрепляются ли байты пикселей также к ответу этого конкретного вызова инструмента, чтобы агент мог видеть их прямо сейчас; minecraft_observe по умолчанию использует include_image=true (все остальные инструменты по умолчанию используют include_image=false, чтобы рутинные действия были дешёвыми в контексте). Передайте include_image=false в minecraft_observe, чтобы не помещать изображение в ответ, когда нужны только состояния — скриншот всё равно захватывается и сохраняется на диск в любом случае. Скриншот, который был запрошен, но не удался (viewer/бот не готов, не найден поддерживаемый браузер), сообщается как screenshot: {"error": ..., "message": ...}, в отличие от screenshot: null (захват изображений отключён на уровне сервера через --no-images).

Навигация (только ходьба)

minecraft_walk_to только ходит. Он может подняться на 1-блочные ступени и спуститься на 1 блок, но он не копает, не ставит строительные леса, не строит башни, не занимается паркуром и не открывает двери. Он целится в горизонтальную позицию (GoalNearXZ, поэтому высота местности выбирается автоматически), используя статическую цель внутри области из chunk_limit чанков с центром в точке старта (по умолчанию 3, ограничено максимальным значением, настроенным на сервере). Если цель находится за пределами этой области, рядом нет пригодного для стояния пола или нет пешего маршрута, вызов быстро завершается ошибкой, а не ждёт.

tolerance по умолчанию равен 1.5. Бюджет поиска A* (walkSearchTimeoutMs, по умолчанию 1000) ограничивает время поиска пути, прежде чем он завершится ошибкой с сообщением "move closer".

Туннелирование и навигация на дальние расстояния

• minecraft_mine_block обычно требует прямой видимости от головы, что невозможно для соседнего блока на уровне ног внутри 1-блочного тоннеля. Теперь он пропускает это ограничение для целей в пределах --mine-visibility-ignore-distance блоков (по умолчанию 3, передайте -MineVisibilityIgnoreDistance в стартовый скрипт), чтобы вы могли копать туннель прямо вперёд из 1-блочного тоннеля.

• minecraft_walk_to принимает chunk_limit до --max-chunk-limit (по умолчанию 8). Более крупные запросы отклоняются с error: requested chunk limit (N) greater than allowed (M).

• minecraft_pillar_up сообщает о чёткой ошибке pillar_up_needs_placeable_block, когда предмет в руке не является размещаемым блоком, и объясняет, что пространство для головы при приземлении должно быть расчищено сначала; dig_up расчищает пространство для головы на каждом шаге.

• Черновики, поставляемые с каждым персонажем (автоматически развёртываются в drafts/):

  • dig_staircase(height, distance, stop) — проходимый 2-блочный нисходящий пандус.

  • clear_room(width, depth, height) — расширяет 1-блочный тоннель в комнату.

  • dig_up(targetY) / descend_to_depth(targetY, stopOnOre) — безопасный одношаговый подъём / спуск, проверяющий лаву/воду перед копанием.

  • tunnel_forward / tunnel_iron / branch_mine_safe_iron — туннелирование и добыча руды, всё с защитой от опасностей (они останавливаются перед копанием в воду/лаву).

  • place_crafting_table / place_block / climb_pillar / find_village (дальнее патрулирование, сообщающее, когда видит жителя).

Остановленные запуски, таймауты и защита от зависаний

• minecraft_stop останавливает активную команду Mineflayer и завершает любой запущенный процесс TypeScript-навыка (убивает оба). minecraft_kill_command останавливает только текущую физическую команду; minecraft_kill_skill завершает только запущенный процесс навыка.

• Кооперативная отмена: навыки проверяют маркер сигнала завершения в каждом вызове API / сне и чисто выходят (SkillCancelledError) при остановке, поэтому minecraft_stop/kill_skill (и отключение клиента) быстро останавливают навык и позволяют ему записать свой результат — раннер жёстко убивается только если он игнорирует маркер.

• Настраиваемый таймаут навыка: minecraft_set_skill_timeout(seconds) (1..3600) задаёт максимальную длительность для minecraft_execute_typescript и minecraft_collect_blocks (по умолчанию 90; значение по умолчанию при запуске через -SkillTimeoutSeconds / --skill-timeout-seconds). Длинные навыки выполняются в отдельном подпроцессе и завершаются на стороне сервера по истечении этого таймаута.

• Согласуйте с окном вашего клиента: requestTimeoutMs в .mcp.json агента (по умолчанию для персонажа 200000) должен оставаться ВЫШЕ таймаута навыка на сервере, иначе длинные навыки обрезаются на стороне клиента до завершения. Правило большого пальца: установите minecraft_set_skill_timeout в requestTimeoutMs - 10s.

• Повторный предохранитель безрезультатности отключён по умолчанию. Это был пережиток старых, более слабых моделей, которые повторяли идентичную безрезультатную операцию в цикле; привязанный к одному "релевантному предмету", он ошибочно блокировал несвязанные операции навыков. Включите его явно, когда он нужен, с помощью аргумента MCP --enable-anti-stall-guard (-EnableAntiStallGuard в стартовом скрипте).

Прозрачность состояния

• Каждое состояние (полное и дельта) всегда несёт позицию игрока position, health, food и foodSaturation, и каждый результат всегда сообщает текущий heldItem, так что агенту никогда не приходится выводить свои собственные жизненные показатели или удерживаемый инструмент из диффа.

• minecraft_collect_blocks заранее экипирует самый дешёвый инструмент, который добывает целевой блок (вместо того чтобы умереть на полпути с отказом unharvestable), и тело больше не меняет удерживаемый предмет, кроме случаев, когда collect_blocks нужен другой инструмент.

Советы из живого тестирования (эргономика агента)

Они взяты из реальных игровых сессий с кодинг-агентом, и их стоит закодировать в AGENTS.md вашего агента или в подсказки навыков:

• Координаты плоские в обёрточных инструментах: minecraft_walk_to(x,y,z,…) / minecraft_mine_block(x,y,z,…) принимают отдельные числа, а НЕ объект position/block. Для вложенных схем действий используйте minecraft_call с формами из minecraft_info (например, {"action":"place_block","parameters":{"referenceBlock":{…}}}).

• Проверяй перед копанием: читай hazards (вода/лава) и inspect следующую ячейку перед прокладкой туннеля. Черновики доставки останавливаются на опасности; сырой mine_block в воду/лаву застревает бот.

• Дрейф удерживаемого инструмента: подъёмный mine_block или pillar_up может оставить размещаемый блок (земля/булыжник) в руке вместо инструмента. Переэкипируйся и проверь после любого подъёмного копания; инструменты также ломаются по прочности, так что держи запасную кирку.

• Копай широко, а не 1-шириной: туннели шириной 1 открывают только переднюю грань и проходят мимо руды в боковых стенах. Используй clear_room/branch_mine_safe_iron (шириной 3), чтобы открыть руду, и рассматривай результат find_block с прямой видимостью (анти-рентген) как «пойди посмотри / копай, чтобы открыть его».

• Дальние путешествия по земле работают с динамической ходьбой с потоковой загрузкой чанков; держи каждый walk_to в пределах окна клиента, и он покрывает гораздо больше земли, чем прыжки на один чанк.

• Тайм-ауты: держи minecraft_set_skill_timeout на requestTimeoutMs - 10s, чтобы длинные навыки завершались, а не обрезались. minecraft_info сообщает текущее значение; перечитывай его, когда документация расходится.

• Предпочитай много маленьких обратимых навыков одному большому необратимому; каждый требует детерминированного постусловия. minecraft_observe + minecraft_stop позволяют отслеживать и останавливать любой случайный запуск.

Крутые штуки

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

А вот Codex, описывающий скин моего персонажа. Prismarine рендерит только стандартного Стива :(

Разработка

npm test
npm run build
.\.venv\Scripts\python.exe -m compileall mcp

Использование программно (pip install)

pm-minecraft можно встроить непосредственно в другой Python-проект — например, в когнитивную архитектуру, которая поддерживает персонажа Minecraft в фоновых потоках. Никаких ps1-скриптов, никакого subprocess.Popen для запуска и никаких отсоединённых дочерних процессов: каждый Node-процесс привязан к своему Python-родителю через канал жизненного цикла stdin. Когда родитель умирает — корректно или при принудительном завершении — ОС закрывает канал, Node видит EOF и корректно завершается. Та же семантика на Windows и Linux.

Установка

pip install git+https://github.com/flamingrickpat/pm-minecraft.git

Требования к целевой машине:

• Python 3.12 и Node.js 20+ в PATH (node и npm).

• При первом запуске персонажа в Python-среде пакет один раз устанавливает своё дерево зависимостей Node в <venv>/pm-minecraft-runtime/<version>/ (выполняет npm ci под файловой блокировкой; однократно, пару минут). Каждый последующий запуск мгновенный. Предварительно прогрейте с помощью pm_minecraft_mcp.ensure_node_runtime().

• Доступный сервер Minecraft Java 1.19.x с персонажем в режиме выживания (так же, как в автономной настройке).

Точки входа

Всё это один типизированный объект конфигурации плюс блокирующие функции, предназначенные для работы в фоновых потоках:

• pm_minecraft_mcp.ServerConfig(...) — все настройки: хост/порт Minecraft, имя пользователя, домашний каталог агента, корень артефактов, хосты+порты web/viewer/MCP, тайм-аут запуска, захват изображений, лимиты навыков, дистанция просмотра.

• pm_minecraft_mcp.execute_node_main_loop(config) — запускает тело Minecraft (один Node-процесс) и блокируется до его завершения.

• pm_minecraft_mcp.execute_python_main_loop(config, manage_body=True) — запускает MCP-сервер и блокируется, пока он обслуживает запросы. При значении по умолчанию manage_body=True он также запускает и владеет телом сам (одного потока достаточно); при manage_body=False ожидает, что телом управляет сопутствующий поток execute_node_main_loop, и ждёт, пока он станет готов.

• pm_minecraft_mcp.init_character(name, agent_root, artifact_root, ...) — Python-порт scripts/init_character.ps1: создаёт рабочее пространство агента (AGENTS.md, .mcp.json, lib/minecraft.ts, drafts/, skills/, memory/minecraft/). Отказывается от непустых корневых каталогов агента.

• pm_minecraft_mcp.check_prerequisites(config) — быстрые проверки, также выполняемые автоматически перед любым запуском: инициализирован ли домашний каталог агента, доступен ли сервер Minecraft по TCP, свободны ли локальные служебные порты, есть ли node в PATH. Каждый сбой немедленно вызывает исключение с конкретным сообщением. После подключения тела согласованная версия должна быть 1.19.x, а режим игры — выживание, иначе точка входа вызывает исключение.

Пример

examples/main.py запускает персонажа в двух фоновых потоках и завершает работу по Ctrl-D:

import threading
from pathlib import Path

from pm_minecraft_mcp import (
    ServerConfig,
    execute_node_main_loop,
    execute_python_main_loop,
    init_character,
)

AGENT_ROOT = Path.home() / "characters" / "Floppa"

if not (AGENT_ROOT / "AGENTS.md").exists():
    init_character(
        name="Floppa",
        agent_root=AGENT_ROOT,
        artifact_root=AGENT_ROOT / "artifacts" / "minecraft",
        minecraft_host="127.0.0.1",
        minecraft_port=12345,
        web_port=3000,
        viewer_port=3007,
        mcp_port=8765,
    )

config = ServerConfig(
    minecraft_host="127.0.0.1",
    minecraft_port=12345,
    username="Floppa",
    agent_home=AGENT_ROOT,
    artifact_root=AGENT_ROOT / "artifacts" / "minecraft",
    web_host="127.0.0.1",
    web_port=3000,
    viewer_port=3007,
    mcp_host="127.0.0.1",
    mcp_port=8765,
    startup_timeout_seconds=90,
    capture_images=True,
    max_skill_characters=50000,
    viewer_scale=1,
    viewer_fov=80,
    view_distance=24,
)

threading.Thread(target=execute_node_main_loop, args=(config,), daemon=True).start()
threading.Thread(
    target=execute_python_main_loop, args=(config,), kwargs={"manage_body": False}, daemon=True
).start()

try:
    while True:
        input()  # Ctrl-D (EOF) ends the process; children follow via stdin EOF
except (EOFError, KeyboardInterrupt):
    pass

Однопоточный вариант тоже работает: один фоновый поток на execute_python_main_loop(config) запускает и тело, и MCP.

Несколько персонажей

Используйте один конфиг (уникальное имя пользователя + уникальные порты web/viewer/MCP) для каждого персонажа и дайте каждому свою пару фоновых потоков. Среда выполнения Node используется совместно только для чтения между всеми персонажами в одном Python-окружении.

Поведение на стороне агента не изменилось

С точки зрения MCP-клиента ничего не меняется: те же имена инструментов, схемы, структура .mcp.json и контракт minecraft_execute_typescript. Агент по-прежнему может записать произвольный черновик TypeScript в своё рабочее пространство и выполнить его на сервере; черновики выполняются через tsx-рантайм пакета с lib/minecraft.ts из домашнего каталога персонажа.

Гарантии жизненного цикла

• Тело — это один Node-процесс (без процессов-обёрток npm/tsx); запуски навыков также по одному процессу. Нет деревьев процессов, за которыми нужно следить.

• Дочерние процессы никогда не получают CREATE_NEW_PROCESS_GROUP и никогда не завершаются через taskkill. Сначала завершение через stdin-EOF, а обычный kill() — как крайняя мера.

• Убийство встраивающего процесса в любой момент (включая taskkill /F или kill -9) не может осиротить тело: канал жизненного цикла разрывается, и Node завершается в течение нескольких секунд.