BlockHand（積木之手）— Minecraft Education MCP

AI가 Minecraft Education Edition에서 손과 발을 갖게 합니다: 동작(Agent 이동, 채굴, 배치, 경작, 운반), 눈(블록 감지, 좌표 조회, 게임 이벤트 구독), 창조(10가지 기하 도형과 격자 단위 청사진).

Minecraft Education 공식 문서화된 /wsserver 연결 명령(/connect는 alias)으로 작동하며, 프로세스 주입, 게임 파일 수정, 화면 인식 없이 동작합니다. 연결 명령은 공식 인터페이스입니다. 이후 WebSocket 메시지 프로토콜은 공개된 안정성 보장이 없으므로, 게임 업데이트 후에는 재검증이 필요합니다.

• 42개 도구, 2개 리소스

• 216개 단위·통합 테스트, 게임 실행 없이 가능한 stdio/프로세스 수명주기 smoke 1개, 실기기 live 검증 1개

• 계정, 토큰, 비밀번호 불필요; MCP 런타임은 loopback에만 바인딩되며 게임 파일이나 artifact를 쓰지 않음

1. 3단계 시작하기

1단계: 각 머신에 설치 및 빌드

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

Node는 프로젝트 .nvmrc가 지정한 22.23.1이어야 하며, pnpm은 Corepack으로 11.17.0에 고정됩니다. Windows와 Mac 모두 로컬에 의존성을 설치해야 합니다. 다른 OS의 node_modules를 복사하지 마세요. Minecraft Education의 Mac 최소 요구 사항은 현재 macOS 14입니다.

2단계: 해당 머신에 MCP 등록 1회

Codex／Claude Code／Gemini CLI／Grok CLI를 지원하며, Windows와 macOS 모두 동일합니다.

먼저 두 개의 절대 경로 확보

등록 시 반드시 절대 경로를 사용해야 하며, node만 적으면 안 됩니다. 데스크톱 AI 도구는 Finder／파일 탐색기에서 실행되므로 셸의 nvm, Homebrew 또는 PATH를 읽지 못합니다. node라고 적으면 터미널에서는 테스트가 통과하지만, 데스크톱 버전으로 바꾸면 시작이 실패하고 오류 메시지는 대개 "server가 응답하지 않음"이라고만 나와서 디버깅이 어렵습니다.

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). 경로에 공백이 있으면 전체를 따옴표로 감쌉니다.

설치 프로그램 사용(4개 모두 지원, 권장)

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

설치 프로그램은 단순히 명령을 설정 파일에 쓰는 것이 아니라 다음을 수행합니다:

• 이 머신의 절대 Node 경로를 자동으로 채움 — 데스크톱 프로그램이 nvm, Homebrew 또는 셸 PATH를 읽을 수 있는지에 의존하지 않습니다.

• 실제 MCP initialize를 먼저 실행(곧 기록될 command／args／env 사용)하여 42개 도구가 모두 있는지 확인한 후에만 영구 설정을 변경합니다. 오래된 dist, 잘못된 launcher, 실행 불가능한 Node는 기록 전에 실패합니다.

• 이미 올바르게 등록되어 있으면 아무것도 하지 않으며, 재실행해도 안전합니다.

• 같은 이름이지만 호환되지 않으면 멈추고 차이점을 나열하며, 자동 remove/add를 하지 않아 다른 사람의 timeout, tool policy 또는 다른 clone의 설정을 덮어쓰지 않습니다.

• 각 사의 공식 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에 기록되어 repo와 함께 공유할 수 있으며, 반 전체가 함께 사용할 때는 이 옵션을 사용합니다.

설정 파일 수동 작성(설치 프로그램이 실패할 때의 대비책)

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이 Microsoft Store의 UWP 버전이면 loopback이 Windows 앱 격리로 차단되므로 추가 CheckNetIsolation LoopbackExempt 면제가 필요합니다(8절 참조).

등록 후

해당 AI 도구를 완전히 종료하고 재시작하세요 — 데스크톱 버전은 창을 닫는 것이 아니라 프로그램을 실제로 종료해야 합니다. 그런 다음 doctor로 확인합니다(Minecraft를 건드리지 않고 설정도 변경하지 않음):

corepack pnpm run doctor

Node 버전, 빌드 산출물, 플랫폼 요구 사항, 등록 상태를 확인하고, 실제 등록된 command／args／env로 MCP initialize를 다시 실행하여 설정이 유효하지 않은 Node를 가리키면서도 그린 라이트를 보여주는 일이 없도록 합니다. --json을 추가하면 구조화된 출력을 얻을 수 있습니다. 각 사의 CLI에 직접 물어볼 수도 있습니다:

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

또는 AI에게 직접 mc_status를 호출하라고 하면, connectCommand를 반환하는지로 server가 뜰 수 있는지 알 수 있습니다.

각 머신마다 각각 한 번씩 등록해야 합니다: Windows 노트북, Mac, 다른 컴퓨터의 Node와 프로젝트 절대 경로가 모두 다르므로 설정을 서로 복사할 수 없습니다. 같은 머신에서 같은 도구의 데스크톱 버전／CLI／IDE는 동일한 설정을 공유합니다.

3단계: 게임에서 수동으로 연결

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 또는 여러 task가 동시에 실행될 때 나중에 시작된 MCP가 다른 빈 포트를 얻을 수 있습니다. 항상 현재 조작 중인 task가 보고한 명령을 사용하세요.

Related MCP server: Minecraft MCP Bot

2. 실기기 검증

먼저 게임을 열지 않는 안전한 진단을 수행합니다:

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

doctor는 영구 설정을 수정하지 않고 Minecraft를 시작하지 않습니다. 격리된 loopback 소켓을 잠시 생성하여 launcher, 42개 tools, 2개 resources, stdio EOF, 리스닝 포트 해제를 검증하고, Codex 실제 등록된 command／args／env로 initialize를 한 번 더 완료하여 설정이 유효하지 않은 Node를 가리키면서 그린 라이트를 보여주는 일이 없도록 합니다.

게임이 켜져 있고, 세계가 로드되었고, 치트가 켜진 후:

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

스크립트는 입력할 /connect를 출력하고, 연결될 때까지 기다린 다음 전체 경로를 실행하며 각 항목에 PASS／FAIL을 보고합니다: 연결 → 플레이어 좌표 읽기 → 게임 내 발화 → 시간 설정 → Agent 소환 → 감지 → L자 경로 이동 → 빌드 미리보기 → 속이 빈 유리 구 건설 → 블록이 실제로 존재하는지 역검증 → 청사진 병합 → 이벤트 구독 및 수신 → 정책 게이트 → 데모 건축물 정리.

게임 업데이트 이후

블록 읽기(mc_read_block)는 testforblock 실패 메시지의 텍스트 형식에 의존하며, 이 형식에는 공식적인 안정성 보장이 없습니다. Minecraft Education이 자동 업데이트로 문구를 바꾸거나, 게임 언어가 번체／간체／영어가 아닌 다른 언어로 바뀌면 이 경로는 무효화됩니다.

실패는 조용합니다: 도구가 고장 나는 것이 아니라 "읽을 수 없다"고 말하기 시작할 뿐입니다. 그래서 이 프로젝트는 의도적으로 이를 매번 live에서 실행하는 정례 검사로 만들지 않았습니다 — 정례 검사는 초록불을 보면 안심하는 습관을 기르게 하며, 실제로 판단이 필요한 시점은 "행동이 수상해지는 그 순간"이지 매주 고정적으로 실행하는 그 한 번이 아닙니다.

필요할 때 능동적으로 판단하도록 변경:

mc_verify_reading  { position: 任一座標 }

최대 두 개의 명령을 보내고 세계에 전혀 쓰지 않으며 parseable을 반환합니다:

• true → 파싱 경로가 정상이며 mc_read_block의 결과를 신뢰할 수 있습니다.

• false → 프로토콜이 드리프트됨. 이 경우 mc_read_block은 null 대신 항상 오류를 반환하므로(3절 참조) "읽을 수 없음"을 "거기가 비어 있음"으로 오인하는 일이 없습니다. 반환된 raw는 게임의 원본 메시지이므로, 이를 src/domain/block-report.ts의 PATTERNS와 대조하면 어떤 패턴을 보완해야 하는지 알 수 있습니다.

이 도구를 실행하고 싶게 만드는 세 가지 신호:

1. mc_read_block이 오류를 반환하기 시작했는데, 게임에서 그 칸에 분명히 뭔가가 있는 것이 보입니다.

2. 게임이 방금 업데이트되었고, 읽기에 의존하는 작업(채점, 대칭 분석)을 앞두고 있습니다.

3. 게임 언어를 변경했습니다.

server instructions에도 같은 단서가 들어 있어, AI가 행동이 수상할 때 스스로 이 도구를 찾아낼 수 있으므로 사용자가 알려줄 필요가 없습니다.

기본적으로 데모 건축물을 air로 되돌려 세계에 쓰레기를 남기지 않습니다. 남겨두고 보려면:

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

게임을 열지 않아도 되는 검증(타입, 테스트, build, stdio 핸드셰이크, STDIN 닫힘 시 포트 해제와 포트 점유 실패를 한 번에 실행):

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

3. 도구 개요

연결 및 대비책(4)

Agent — 손과 발(10)

Agent 방향은 자신이 바라보는 방향 기준이지 세계 방위가 아닙니다.

세계(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은 querytarget이 반환한 JSON 문자열을 파싱해 주며, 플레이어나 Agent 좌표를 얻는 정식 방법입니다 — 건설 전에 먼저 물어보세요.

읽기 영역에는 선천적 한계가 있으며, 없는 척하는 것보다 명확히 말하는 것이 낫습니다. Education에는 "임의 블록 읽기" 명령이 없으므로:

• mc_test_block은 예/아니오 문제입니다: 먼저 블록 ID를 추측해야 합니다.

• mc_read_block은 추측할 필요가 없습니다 — 공기를 센티널로 사용해 물어보고, 추측이 틀리면 게임 메시지가 실제 블록을 알려줍니다. 하지만 반환되는 것은 지역화된 표시 이름("흙")이지 블록 ID(dirt)가 아니므로 mc_set_block에 다시 넣을 수 없습니다. 파싱할 수 없으면 이 도구는 null 성공 응답이 아니라 오류를 반환합니다 — 이유는 아래 참조.

• mc_verify_reading은 위 파싱 경로가 여전히 유효한지 능동적으로 검증합니다. 수업 전에 한 번 실행하면 mc_read_block의 결과를 믿을 수 있는지 알 수 있습니다.

• mc_compare_regions는 하나의 testforblocks로 전체 영역을 비교합니다. 격자 단위 비교는 수백 칸 이상이면 host 타임아웃에 부딪히지만, 이 방식은 그렇지 않습니다. masked 모드는 소스의 공기를 무시하므로 "있어야 할 것이 있는지"를 주변에 추가된 것이 무엇이든 상관없이 확인하기에 적합합니다 — 학생 작품 채점이 바로 이 형태입니다.

파싱 실패 시 null이 아니라 오류를 반환하는 이유

이 도구의 사용자는 AI이고, AI는 시스템 고장을 의심하지 않기 때문입니다.

"성공" 응답에 block: null이 붙으면 "읽었는데 거기가 비어 있다"로 읽히기 쉽습니다. 그러면 AI는 이 잘못된 인식을 바탕으로 매우 자신 있게 계속 작업합니다 — 예를 들어 학생이 한 시간 동안 지은 작품을 빈 땅으로 오인해 덮어버리고, 사후에 확인할 수 있는 오류 기록도 남지 않습니다. 사람은 null을 보면 이상하다고 느끼고 멈춰서 디버깅하지만, AI는 그렇지 않습니다.

오류는 데이터로 계속 사용될 수 없습니다. 이것이 핵심입니다.

mc_verify_reading은 나머지 절반입니다: 그 칸이 무엇인지 미리 알 필요가 없습니다 — 그 칸이 공기면 베드록으로 물어보고(공기가 베드록일 수 없으므로 불일치가 보장됨) 실패 메시지를 강제로 끌어냅니다; 그 칸에 뭔가가 있으면 첫 번째 질문에서 이미 메시지를 얻습니다. 두 경로 모두 메시지를 얻는 것이 보장되며, 최대 두 개의 명령이고 세계에 전혀 쓰지 않습니다.

이 방어선은 돌연변이 테스트로 지켜집니다: 의도적으로 파싱 규칙을 망가뜨리면 탐지와 파서를 합친 7개 테스트가 반드시 빨간불이 되어야 합니다.

전체 영역을 격자 단위로 읽으려면 행동 팩과 Script API를 사용하세요. 이 프로젝트는 의도적으로 그 길을 가지 않습니다. 학교 컴퓨터에 설치 단계가 하나 더 늘어나기 때문입니다.

같은 건축물을 반복 수정

mc_structure의 saveMode는 바로 이를 위해 설계되었습니다:

버전 관리는 이름 짓기입니다: castle_v1, castle_v2. 같은 이름이면 덮어쓰므로 버전을 바꾸기 전에 이름을 먼저 바꾸세요.

게임에는 저장된 구조 목록을 보여주는 명령이 없으므로 무엇을 저장했는지는 이름으로만 기억할 수 있습니다. 브리지는 이번 연결에서 저장한 목록을 기억하며 mc_status로 확인할 수 있습니다 — 하지만 이는 이번 프로세스에만 해당되고 재시작하면 사라집니다(disk 모드의 파일은 남아 있지만 이름은 직접 기억해야 합니다).

대칭 분석 — 작품 채점

mc_analyze_symmetry는 영역이 거울 대칭인지 확인하며, 비대칭일 때 어느 블록이 비대칭인지 지적해 주지 단순히 "아니오"만 던지지 않습니다.

원리: testforblocks는 평행 이동 비교만 하고 거울 반전은 하지 않으므로, 먼저 structure save로 영역을 저장한 다음 structure load의 mirror 매개변수로 거울 반전시켜 임시 영역에 배치하고, 두 영역을 비교합니다. 전체가 통과하면 바로 만점; 통과하지 못하면 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개가 넘는 칸이므로 3만 번 이상의 WebSocket 왕복이 필요합니다 — 실질적으로 멈춤과 같습니다.

BlockHand의 파이프라인은:

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

반지름 8의 속이 찬 구는 2,000개가 넘는 블록을 200개 미만의 명령으로 압축하며, 병합 결과는 결정적입니다 — 같은 입력은 항상 같은 배치를 얻으므로 "병합 후 덮는 블록 집합이 원본 점 집합과 완전히 동일해야 한다"는 테스트로 고정되어 있어 더 많이 덮거나 덜 덮는 일이 없습니다.

속이 빈 형태는 항상 "내부 판정 + 외곽 이웃 테스트"로 구현하며, 각 형태마다 별도의 속이 빈 수학을 작성하지 않습니다. 새 형태는 inside()만 작성하면 속이 빈 동작이 자동으로 일관됩니다.

5. 안전 경계

하지 않는 일

• 외부 네트워크에 연결하지 않음: 127.0.0.1에서만 WebSocket 리스닝.

• MCP 런타임은 호스트 파일을 쓰지 않음: artifact 출력 경로가 없습니다. 사용자가 명시적으로 setup:<client>／uninstall:<client>를 실행할 때만 해당 사의 공식 CLI가 로컬 MCP 설정을 업데이트합니다.

• 예외 하나를 명확히 설명: mc_structure의 saveMode="disk"는 게임을 통해 구조를 파일로 기록하여 Minecraft 세계 폴더에 저장합니다. MCP 런타임이 파일을 쓰는 것은 아니지만, 사용자 하드디스크에 실제로 남는 것은 맞습니다. 그래서 기본값은 memory(임시, 게임을 끄면 사라짐)이며, 사용자가 명시적으로 보존을 요청할 때만 disk를 사용해야 하고, 도구 응답은 항상 어디에 기록했는지 알려줍니다 — 조용히 파일을 남기지 않습니다.

• 비밀번호를 건드리지 않음: 프로젝트 전체에 token, 계정, 자격 증명이 없습니다.

• 능동적으로 연결하지 않음: 게임이 /connect로 들어오지 않으면 모든 도구는 따를 수 있는 오류 메시지를 반환하며 조용히 실패하지 않습니다.

mc_run_command의 게이트

mcp/README.md 아키텍처 원칙 4는 임의 실행 진입점을 거부하도록 요구합니다. 여기서의 판단은: slash 명령의 범위는 전적으로 로컬 게임 세계 내에 있으며, 호스트 파일 시스템, 프로세스, 네트워크에 닿지 않으므로 임의 코드 실행과 동일하지 않습니다. 실제로 막아야 하는 것은 브리지를 무효화하는 작업이므로, 정책은 의도를 추측하는 키워드 블랙리스트가 아니라 구조적입니다:

1. 한 줄만 허용 — 줄바꿈과 NUL은 직접 거부하며, \n으로 하나의 요청을 두 개의 명령으로 쪼갤 수 없습니다.

2. wsserver와 connect를 거부 — 게임을 다른 엔드포인트로 향하게 하여 이후 모든 도구가 무효화됩니다.

3. 나머지 명령은 read-only／world-write／wide-effect 위험 등급으로 표시하고, MCP Host가 annotation에 따라 수동 확인 여부를 결정하도록 위임합니다.

명령줄에 삽입될 모든 블록 ID, 선택자, 상태 문자열은 먼저 화이트리스트 정규식을 통과하여 공백으로 추가 매개변수를 만들어내는 것을 방지합니다.

교실 보호(기본 켜짐)

위 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 도구 파이프라인 전체를 순수 메모리 페이크로 끝까지 테스트할 수 있습니다. tests/integration/mcp-client.test.ts의 16개 테스트는 게임을 실행할 필요가 없습니다.

8. 알려진 제한 사항

• 세계에서 반드시 치트를 켜야 함 — 그렇지 않으면 게임이 모든 명령을 거부합니다. 이는 Minecraft의 규칙이지 버그가 아닙니다.

• macOS에서 실기 live 검증 완료(Claude Code 경로): 2026-08-25에 macOS에서 Claude Code를 통해 /connect, 대량 읽기/쓰기(단일 세션에서 45,000개 이상의 블록, fill/setblock/testforblock/teleport 포함), 연결 끊김 후 재연결 전체 흐름을 완료했습니다. 아직 검증되지 않은 것은 "Finder에서 Codex Desktop 시작" 경로입니다. GUI 시작은 PATH와 환경 변수 상속 방식이 다르므로 각각 실기 테스트가 필요합니다.

• Agent는 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 client의 기본 타임아웃은 대부분 60초이며, 이를 초과하면 Host 쪽에서 연결이 끊깁니다(도구 자체는 계속 실행 중). 먼저 mc_build_preview로 fillBatches를 확인하고, 수량이 많으면 배치로 나누어 건설하세요.

• 각 BlockHand 프로세스는 여전히 각자 수신 포트를 하나씩 보유함 — STDIO client가 닫히면 server는 Minecraft WebSocket을 함께 닫고 포트를 해제합니다. AI 도구의 데스크톱 버전이 여러 작업을 동시에 로드하거나, 데스크톱 버전/CLI/IDE를 병렬로 실행하면 첫 번째가 우선 포트를 얻고 나머지는 자동으로 빈 포트를 얻습니다. 항상 현재 작업의 mc_status.connectCommand를 사용해 게임이 실제로 조작하려는 인스턴스에 연결되게 하세요. 고정 포트가 필요하면 각 client에 서로 다른 MINECRAFT_EDU_WS_PORT를 지정하거나 MINECRAFT_EDU_WS_PORT_FALLBACK을 0으로 설정하면 됩니다.

• 핸드셰이크 후 첫 번째 명령이 반드시 타임아웃되던 문제를 수정함 — 네 번의 독립된 실기 실행 모두에서 재현되었습니다. 게임이 서버에 복호화기가 준비되기 전에 암호화 프레임을 하나 보내고, 스트림이 어긋나면서 다음 요청의 응답을 읽을 수 없게 됩니다. AES-CFB8은 자기 동기화(self-synchronizing) 방식이므로 첫 번째에만 영향을 줍니다. 이제 adapter는 핸드셰이크 완료 후 읽기 전용 time query daytime을 자동으로 한 번 보내 그 손실을 흡수하고 결과를 버리므로, 호출 측의 첫 동작은 정상적으로 실행됩니다. stderr에는 primed post-handshake stream이 기록됩니다.

• 이벤트는 실제로 발생할 때만 트리거됨 — BlockPlaced는 플레이어가 직접 블록을 놓을 때만 발생하며, /setblock과 /fill은 해당되지 않습니다. 이벤트를 받으려면 먼저 구독한 다음 이벤트가 실제로 발생하게 해야 합니다.

• 일부 응답의 requestId는 요청과 일치하지 않음(전부 0인 ID를 반환하는 것이 관찰됨). adapter는 "대기 중인 요청이 하나만 남은" 경우 그 응답을 해당 요청에 귀속시키고, stderr에 추론된 것임을 기록합니다. 그렇지 않으면 해당 요청들은 끝까지 조용히 타임아웃되어, 호출 측은 실제 실패 원인이 아니라 "반응 없음"만 보게 됩니다.

• 게임 연결은 한 번에 하나만 유지되며, 새 연결이 이전 연결을 대체합니다.

• 실기 검증이 완료된 환경: Minecraft Education 1.26.32.0(Win32 데스크톱 버전). Microsoft Store의 UWP 버전으로 바꾸면 loopback이 Windows 앱 격리에 막혀 추가로 CheckNetIsolation LoopbackExempt 면제가 필요합니다. macOS 14+의 검수 매트릭스는 agents/docs/macos-support.md를 참조하세요.

9. 라이선스

이 프로젝트는 MIT License로 배포됩니다. 상업적 용도를 포함하여 자유롭게 사용, 수정, 배포 및 재라이선스할 수 있으며, 유일한 조건은 원본 저작권 고지와 라이선스 조항을 보존하는 것입니다.

소프트웨어는 "있는 그대로" 제공되며, 어떠한 명시적 또는 묵시적 보증도 수반되지 않습니다.

Minecraft, Minecraft Education은 Mojang Studios와 Microsoft의 상표입니다. 본 프로젝트는 두 회사와 제휴 관계가 없으며, 그로부터 보증을 받지 않았습니다.