pm-minecraft

MCP 클라이언트를 위한 독립형 Minecraft 서바이벌 바디입니다.

Mineflayer, Prismarine Viewer, 로컬 웹 UI, Streamable HTTP MCP 서버를 실행합니다.

에이전트, 모델, 인지 런타임은 포함하지 않습니다. 선택한 에이전트에게 MCP 사용법, 스크린샷 보는 법, MCP를 통해 실행할 수 있는 커스텀 TypeScript 스크립트 작성법을 알려주는 최소한의 지침만 포함합니다.

https://github.com/minedojo/voyager 와 https://github.com/Mega-Gorilla/Discovery 에 큰 감사를 드립니다 :3

이것은 저와 함께 마인크래프트를 플레이할 수 있는 재미있는 인지 아키텍처 AI 컴패니언을 만들기 위한 지속적인 노력의 일부입니다. 독립형으로도 작동합니다 ^_^

설정

요구 사항: Windows PowerShell, Node.js 20+, py를 통한 Python 3.12, 그리고 서바이벌 모드의 캐릭터가 있는 연결 가능한 Minecraft Java 1.19.x 서버.

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

설정은 공유 PM 워크플로우를 따릅니다: uv를 사용하여 이 저장소의 Python 3.12 .venv를 생성하고, 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)

  • wenhao의 item-pickup-range (/setPickupRange 5)

• 서바이벌 월드 생성, 치트 활성화, 평화로움

• 입장 후 포트 12345에서 "Open to LAN"

캐릭터 생성 및 시작

.\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을 생성합니다. 런처는 로컬 웹 UI, Prismarine viewer, MCP URL을 출력합니다. 여러 캐릭터의 경우 고유한 -WebPort, -ViewerPort, -McpPort 값을 사용하세요.

deploy/drafts/*.ts 예제는 모두 작업 공간의 drafts/에 복사되고 해당 AGENTS.md에 나열됩니다. 이들은 minecraft_execute_typescript를 통해 그대로 실행되므로, 에이전트는 하나를 직접 실행하거나 가드-및-검증 형태를 새 초안에 복사할 수 있습니다. 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 및 작은 메타데이터 사이드카). 상태와 동작은 이 파일들을 링크만 합니다.

• actions/ — MCP 도구 호출당 하나의 플랫 yaml, <timestamp>_<tool>.yaml 이름으로 실시간으로 기록됩니다 (호출이 시작되는 순간 도구와 입력이 포함된 시작 파일이 나타나고, 스냅샷이 발생함에 따라 전/후 상태 + 스크린샷 링크가 추가되며, 최종 재작성 시 원시 pretty-printed 도구 출력, 지속 시간 및 예외가 기록됩니다). 필드: tool, tool_input, tool_output (둘 다 pretty JSON 블록 스칼라), 네 개의 링크 before_state_path / before_screenshot_path / after_state_path / after_screenshot_path (상태를 만들지 않은 도구는 비어 있고, minecraft_observe처럼 하나만 만드는 도구는 before-only), 그리고 스킬의 execution_id / skill_path 같은 조회 헤더. 성공 또는 실패는 tool_output의 반환 데이터에서 직접 읽습니다. 예외는 error: 블록에 기록됩니다.

• mcp-server.log — 포착된 모든 바디/네트워크 오류와 모든 처리되지 않은 예외 (traceback 포함)가 여기에 기록됩니다.

도구 결과는 전체 상태를 인라인하는 대신 동일한 링크(beforeStatePath / afterStatePath / beforeScreenshotPath / afterScreenshotPath)를 반환하므로, 모델은 세부 정보가 필요할 때 파일을 따라갑니다.

스크린샷은 include_image와 관계없이 모든 상태에 대해 artifacts/minecraft/screenshots에 캡처되어 기록됩니다 — 모든 동작 전후, 모든 minecraft_observe 호출 시 — 서버가 이미지 캡처를 활성화한 상태로 시작된 경우에 한합니다 (기본값, --no-images로 비활성화). 이는 에이전트가 직접 보지 않은 상태를 포함하여 실행의 완전하고 끊김 없는 디스크상 시각적 기록을 후속 분석을 위해 제공합니다.

include_image는 픽셀 바이트가 해당 특정 도구 호출의 응답에도 첨부되어 에이전트가 지금 바로 볼 수 있는지 여부만 제어합니다. minecraft_observe는 기본적으로 include_image=true입니다 (다른 모든 도구는 일상적인 동작을 컨텍스트에서 저렴하게 유지하기 위해 기본적으로 include_image=false). 상태만 필요할 때 응답에 이미지를 넣지 않으려면 minecraft_observe에 include_image=false를 전달하세요 — 스크린샷은 어느 쪽이든 여전히 캡처되어 디스크에 저장됩니다. 요청되었지만 캡처에 실패한 스크린샷(뷰어/봇이 준비되지 않음, 지원되는 브라우저를 찾지 못함)은 screenshot: {"error": ..., "message": ...}로 보고되며, screenshot: null(서버 전체에서 --no-images로 이미지 캡처가 비활성화됨)과 구별됩니다.

이동 (걷기만)

minecraft_walk_to는 걷기만 합니다. 1블록 계단을 오르고 1블록을 내려갈 수 있지만, 파지 않고, 비계를 놓지 않고, 탑을 쌓지 않고, 파쿠르를 하지 않고, 문을 열지 않습니다. 시작 중심 영역의 chunk_limit 청크(기본 3, 서버의 구성된 최대값으로 제한) 내에서 정적 목표를 사용하여 수평 위치(GoalNearXZ, 따라서 지형 높이는 자동 선택)를 목표로 합니다. 대상이 해당 영역 밖에 있거나, 근처에 서 있을 바닥이 없거나, 도보 경로가 없으면, 가만히 있지 않고 즉시 실패합니다.

tolerance 기본값은 1.5입니다. 탐색 A* 예산(walkSearchTimeoutMs, 기본 1000)은 "더 가까이 이동" 메시지와 함께 실패하기 전에 경로 찾기에 걸릴 수 있는 시간을 제한합니다.

터널링 및 장거리 이동

• minecraft_mine_block은 일반적으로 머리 높이의 시야를 요구하므로, 1칸 폭의 수직 갱도 안의 인접한 발 높이 블록에는 불가능합니다. 이제 --mine-visibility-ignore-distance 블록(기본 3, 시작 스크립트에 -MineVisibilityIgnoreDistance 전달) 내의 대상에 대해서는 해당 게이트를 건너뛰므로 1칸 폭 터널에서 직진 터널링이 가능합니다.

• minecraft_walk_to는 --max-chunk-limit(기본 8)까지의 chunk_limit을 허용합니다. 더 큰 요청은 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). 긴 스킬은 별도 하위 프로세스에서 실행되며 해당 시간 초과 시 서버 측에서 종료됩니다.

• 클라이언트 창에 맞추기: 에이전트의 .mcp.json requestTimeoutMs(캐릭터 기본 200000)는 서버 스킬 시간 초과보다 위에 유지되어야 합니다. 그렇지 않으면 긴 스킬이 완료되기 전에 클라이언트 측에서 잘립니다. 경험 법칙: minecraft_set_skill_timeout을 requestTimeoutMs - 10s로 설정하세요.

• 반복-무이득 회로 차단기는 기본적으로 비활성화되어 있습니다. 이는 동일한 무이득 작업을 루프에서 재시도하던 구형의 약한 모델의 유물이었습니다. 단일 "관련 항목"에 키가 지정되어 관련 없는 스킬 작업을 잘못 차단했습니다. 원할 때 --enable-anti-stall-guard MCP 인수(시작 스크립트의 -EnableAntiStallGuard)로 명시적으로 다시 활성화하세요.

상태 투명성

• 모든 상태(전체 및 델타)는 항상 플레이어 position, health, food, foodSaturation을 포함하고, 모든 결과는 항상 현재 heldItem을 보고하므로 에이전트는 diff에서 자신의 생명력이나 들고 있는 도구를 추론할 필요가 없습니다.

• 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의 시야(안티-X-ray) 결과는 "가서 확인 / 파서 드러내기"로 취급하세요.

• 장거리 지상 이동은 가능합니다: 동적 청크 스트리밍 걷기로 작동합니다. 각 walk_to를 클라이언트 창 안에 유지하면 한 청크씩 이동하는 것보다 훨씬 넓은 범위를 커버합니다.

• 타임아웃: minecraft_set_skill_timeout을 requestTimeoutMs - 10s로 유지하여 긴 스킬이 중단되지 않고 완료되게 하세요. minecraft_info가 현재 값을 보고합니다. 문서가 어긋날 때마다 다시 읽으세요.

• 하나의 거대하고 되돌릴 수 없는 스킬보다 작고 되돌릴 수 있는 여러 스킬을 선호하세요: 각각 결정적 사후 조건이 필요합니다. minecraft_observe + minecraft_stop으로 벗어난 실행을 추적하고 중단할 수 있습니다.

멋진 기능

캐릭터를 수동으로 제어하거나 코딩 에이전트가 MCP를 사용하는 방식을 볼 수 있는 WebUI가 여기 있습니다.

그리고 Codex가 제 캐릭터의 스킨을 설명한 내용입니다. Prismarine은 기본 Steve만 렌더링합니다 :(

개발

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

프로그래밍 방식으로 사용하기 (pip install)

pm-minecraft는 다른 Python 프로젝트에 직접 내장할 수 있습니다 — 예를 들어 데몬 스레드에서 Minecraft 캐릭터를 유지하는 인지 아키텍처 같은 것에 말이죠. ps1 스크립트도, 런처의 subprocess.Popen도, 분리된 자식 프로세스도 없습니다. 모든 Node 프로세스는 stdin 수명주기 파이프를 통해 Python 부모에 연결됩니다. 부모가 죽으면 — 정상적으로든 강제로든 — OS가 파이프를 닫고, Node는 EOF를 보고 깨끗하게 종료됩니다. Windows와 Linux에서 동일한 의미론입니다.

설치

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

대상 머신의 요구 사항:

• Python 3.12, 그리고 PATH에 Node.js 20+ (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 호스트/포트, 사용자 이름, 에이전트 홈, 아티팩트 루트, 웹/뷰어/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, ...) — scripts/init_character.ps1의 Python 포트: 에이전트 작업 공간을 생성합니다 (AGENTS.md, .mcp.json, lib/minecraft.ts, drafts/, skills/, memory/minecraft/). 비어 있지 않은 에이전트 루트는 거부합니다.

• pm_minecraft_mcp.check_prerequisites(config) — 빠른 실패 검사로, 어떤 것이든 생성되기 전에 자동으로 실행됩니다: 에이전트 홈 초기화, Minecraft 서버 TCP 도달 가능, 로컬 서비스 포트 사용 가능, PATH의 node. 각 실패는 즉시 특정 메시지와 함께 예외를 발생시킵니다. 바디가 조인된 후, 협상된 버전이 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를 모두 시작합니다.

여러 캐릭터

캐릭터당 하나의 구성(고유 사용자 이름 + 고유 웹/뷰어/MCP 포트)을 사용하고 각각에 고유한 데몬 스레드 쌍을 제공하세요. Node 런타임은 동일한 Python 환경의 모든 캐릭터 간에 읽기 전용으로 공유됩니다.

에이전트 측 동작은 변경되지 않습니다

MCP 클라이언트의 관점에서 변경된 것은 없습니다: 동일한 도구 이름, 스키마, .mcp.json 레이아웃, minecraft_execute_typescript 계약. 에이전트는 여전히 임의의 TypeScript 초안을 작업 공간에 작성하고 서버에 대해 실행할 수 있습니다. 초안은 캐릭터 홈의 lib/minecraft.ts와 함께 패키지의 tsx 런타임을 통해 실행됩니다.

수명주기 보장

• 바디는 하나의 Node 프로세스입니다 (npm/tsx 래퍼 프로세스 없음). 스킬 실행도 각각 하나의 프로세스입니다. 추적할 프로세스 트리가 없습니다.

• 자식은 CREATE_NEW_PROCESS_GROUP을 받지 않으며 taskkill되지 않습니다. 종료는 먼저 stdin-EOF, 최후 수단으로 일반 kill()입니다.

• 임의의 순간에 임베딩 프로세스를 죽여도 (taskkill /F 또는 kill -9 포함) 바디가 고아가 될 수 없습니다: 수명주기 파이프가 끊기고 Node가 수 초 내에 종료됩니다.