BlockHand（積木之手）— Minecraft Education MCP

Dale manos y pies a la IA en Minecraft Education Edition: acciones (movimiento del Agent, excavar, colocar, cultivar, transportar), ojos (detectar bloques, consultar coordenadas, suscribirse a eventos del juego), creación (diez formas geométricas y planos cuadrícula por cuadrícula).

Opera a través del comando de conexión /wsserver documentado oficialmente por Minecraft Education (/connect es un alias), sin inyectar procesos, sin modificar archivos del juego y sin reconocimiento de pantalla. El comando de conexión es una interfaz oficial; el protocolo de mensajes WebSocket posterior no tiene garantía pública de estabilidad, por lo que tras una actualización del juego habrá que volver a verificar.

• 42 herramientas, 2 recursos

• 216 pruebas unitarias y de integración, 1 smoke de stdio/ciclo de vida de proceso que no requiere abrir el juego, 1 verificación live en dispositivo real

• No requiere ninguna cuenta, token ni secreto; el runtime de MCP solo se vincula a loopback, no escribe archivos del juego ni artefactos

1. Primeros pasos en tres pasos

Paso uno: instalar y compilar en cada máquina

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

Node debe ser el 22.23.1 especificado en el .nvmrc del proyecto, y pnpm está fijado por Corepack en 11.17.0. Tanto en Windows como en Mac hay que instalar las dependencias localmente; no copies el node_modules de otro sistema operativo. El requisito mínimo actual de Minecraft Education en Mac es macOS 14.

Paso dos: registrar MCP una vez en esa máquina

Compatible con Codex／Claude Code／Gemini CLI／Grok CLI, tanto en Windows como en macOS.

Primero obtén las dos rutas absolutas

Al registrar es obligatorio usar rutas absolutas, no basta con escribir node. Las herramientas de IA de escritorio se inician desde Finder/Explorador de archivos y no leen el nvm, Homebrew ni el PATH de tu shell; si escribes node funciona al probarlo en la terminal, pero al cambiar a la versión de escritorio fallará al iniciar, y el mensaje de error normalmente solo dice «el server no responde», lo que es difícil de depurar.

macOS:

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

Windows (PowerShell):

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

A continuación, <NODE> representa la ruta absoluta de Node y <REPO> la ruta absoluta del proyecto. El punto de entrada del servidor es fijo: <REPO>/dist/index.js (en Windows se escribe <REPO>\dist\index.js). Si la ruta contiene espacios, hay que poner todo entre comillas.

Con el instalador (compatible con los cuatro, recomendado)

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

El instalador no solo escribe el comando en el archivo de configuración; además:

• Rellena automáticamente la ruta absoluta de Node de esta máquina, sin depender de que el programa de escritorio pueda leer nvm, Homebrew o el PATH del shell.

• Primero ejecuta un initialize real de MCP (con el command/args/env que se va a escribir), y solo si confirma que los 42 tools están presentes toca cualquier configuración persistente. Un dist antiguo, un launcher incorrecto o un Node no ejecutable fallarán antes de escribir nada.

• Si ya está registrado correctamente, no hace nada; volver a ejecutarlo es seguro.

• Si hay algo con el mismo nombre pero incompatible, se detiene y lista las diferencias, sin hacer remove/add automático, para no sobrescribir el timeout, la tool policy o la configuración de otro clone de otra persona.

• Solo escribe a través de los subcomandos oficiales mcp add／mcp remove de cada cliente, sin editar manualmente los archivos de configuración — eso saltaría la validación de schema y la resolución de scope de cada cliente.

Para desinstalar usa corepack pnpm run uninstall:codex (o uninstall:claude, etc.). También tiene protección contra borrado accidental: si no es un entry reconocible de este árbol de trabajo, lo rechaza.

Ubicación de escritura y requisitos de reinicio de cada cliente:

Hay diferencias en la estrategia de lectura: Codex y Grok tienen mcp list --json, que usa directamente la salida legible por máquina. El list de Claude Code y Gemini solo tiene texto legible por humanos y no incluye env, por lo que no se puede juzgar la compatibilidad; por eso se leen en modo solo lectura los archivos de configuración que su CLI oficial acaba de escribir. La escritura siempre va por CLI.

Comandos manuales (si no quieres usar el instalador)

Los comandos son equivalentes, pero las rutas absolutas hay que rellenarlas tú, y no hay validación previa de initialize ni protección contra sobrescritura.

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

Tres diferencias fáciles de pisar:

• En Gemini, command y args son parámetros posicionales, van después del nombre, sin separador --.

• El scope por defecto de Gemini es project; para que esté disponible globalmente hay que escribir explícitamente --scope user.

• El scope por defecto de Claude es local (solo afecta al directorio actual); --scope project escribe en el .mcp.json de la raíz del proyecto, se puede compartir con el repo, úsalo cuando toda la clase lo comparta.

Editar manualmente el archivo de configuración (respaldo si el instalador falla)

Claude Code y Gemini CLI usan JSON:

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

Codex y Grok CLI usan TOML:

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

Notas adicionales para Windows

• La ruta absoluta de Node suele ser C:\Program Files\nodejs\node.exe; con nvm-windows es algo como C:\Users\<tú>\AppData\Roaming\nvm\v22.23.1\node.exe.

• En los archivos de configuración JSON hay que escapar las barras invertidas: "C:\\Program Files\\nodejs\\node.exe". En TOML se pueden usar literales de cadena con comillas simples: command = 'C:\Program Files\nodejs\node.exe'.

• Si Minecraft Education es la versión UWP de Microsoft Store, el loopback estará bloqueado por el aislamiento de aplicaciones de Windows y se necesitará una exención adicional de CheckNetIsolation LoopbackExempt (ver sección 8).

Después de registrar

Sal por completo y reinicia esa herramienta de IA — en la versión de escritorio hay que terminar el programa de verdad, no cerrar la ventana. Luego confirma con doctor (sin tocar Minecraft ni cambiar configuración):

corepack pnpm run doctor

Comprueba la versión de Node, los artefactos de build, los requisitos de plataforma y el estado del registro, y vuelve a ejecutar un initialize de MCP con el command/args/env realmente registrado, para evitar que la configuración apunte a un Node inválido y dé un falso verde. Añade --json para obtener salida estructurada. También puedes preguntar directamente a la CLI de cada cliente:

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

O simplemente pídele a la IA que llame a mc_status; si devuelve connectCommand, significa que el server puede arrancar.

Cada máquina debe registrarse una vez por separado: la ruta absoluta de Node y del proyecto de un portátil Windows, un Mac y otro ordenador son diferentes, no se pueden copiar configuraciones entre ellas. En la misma máquina, la versión de escritorio／CLI／IDE de la misma herramienta comparten la misma configuración.

Paso tres: conectar manualmente desde el juego

corepack pnpm run connect

Esta entrada compatible solo muestra cómo operar, no abre Minecraft, no cambia la ventana en primer plano ni simula el teclado. Se ha eliminado la entrada automática de PowerShell en Windows; en Mac tampoco se añade automatización con AppleScript.

Es muy fácil invertir la dirección: el juego es el que conecta hacia fuera, el MCP server es el que recibe la conexión.

1. En la conversación actual de IA, llama a mc_status y copia el connectCommand que devuelve.

2. Abre Minecraft Education, entra en un mundo (quedarse en el menú principal no sirve).

3. El mundo debe tener Cheats activados, y el operador necesita permisos de Admin／OP.

4. Escribe manualmente en la barra de chat, por ejemplo:

/connect 127.0.0.1:19131

Cuando veas Connection established, ya está. Después solo tienes que decirle a la IA «construye una esfera de vidrio hueca delante de mí».

Para reconectar no hace falta volver a escribir todo: pulsa T en la barra de chat para abrirla, luego ↑ para recuperar el comando anterior, y Enter.

Las primeras versiones tenían un bug de «desconexión obligatoria tras ~60 segundos de inactividad»: el heartbeat solo reconocía los pong frames de WebSocket, pero el cliente de Bedrock／Education nunca responde pong, por lo que una conexión sana era terminada por su propio heartbeat. Ya está corregido (ahora se determina la actividad por cualquier paquete entrante, complementado con sondas a nivel de aplicación); la inactividad ya no debería causar desconexiones. Si aún se desconecta, primero confirma que estás ejecutando un dist/ recompilado.

No memorices el 19131: cuando se inician simultáneamente la versión de escritorio, la CLI, el IDE o varias tareas, el MCP que se abre después puede obtener un puerto libre distinto. Usa siempre el comando que reporte la tarea que vas a operar en ese momento.

Related MCP server: Minecraft MCP Bot

2. Verificación en dispositivo real

Primero haz el diagnóstico seguro sin abrir el juego:

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

doctor no modifica configuración persistente ni inicia Minecraft; crea brevemente un socket loopback aislado para verificar el launcher, los 42 tools, los 2 resources, el EOF de stdio y la liberación del puerto de escucha, y completa otro initialize con el command/args/env realmente registrado de Codex, para evitar que la configuración apunte a un Node inválido y dé un falso verde.

Con el juego abierto, el mundo cargado y los cheats activados:

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

El script imprime el /connect que hay que introducir, espera a que conectes, y luego recorre una ruta completa reportando PASS／FAIL en cada paso: conexión → leer coordenadas del jugador → hablar en el juego → fijar la hora → invocar al Agent → detectar → recorrer una trayectoria en forma de L → previsualizar construcción → construir esfera de vidrio hueca → volver a verificar que los bloques existen de verdad → fusionar planos → suscribirse y recibir eventos → puerta de políticas → limpiar la construcción de demostración.

Después de una actualización del juego

Leer bloques (mc_read_block) depende del formato de texto del mensaje de fallo de testforblock; ese formato no tiene ninguna garantía oficial de estabilidad. Si Minecraft Education se actualiza silenciosamente y cambia el texto, o el idioma del juego deja de ser chino tradicional／chino simplificado／inglés, esta ruta dejará de funcionar.

El fallo es silencioso: la herramienta no se rompe, solo empieza a decir «no se puede leer». Por eso este proyecto deliberadamente no la convierte en una comprobación rutinaria de cada live — las comprobaciones rutinarias crean el hábito de confiar al ver la luz verde, y el momento en que realmente hay que juzgar es «cuando el comportamiento se vuelve sospechoso», no la que se ejecuta fijamente cada semana.

En su lugar, se juzga activamente cuando sea necesario:

mc_verify_reading  { position: 任一座標 }

Envía como máximo dos comandos, no escribe nada en el mundo, y devuelve parseable:

• true → la ruta de parseo es normal, el resultado de mc_read_block es fiable.

• false → el protocolo ha derivado. En ese caso mc_read_block siempre devuelve un error en lugar de null (ver sección 3), así que nadie confundirá «no se puede leer» con «ahí está vacío». El raw devuelto es el mensaje original del juego; compáralo con los PATTERNS de src/domain/block-report.ts para saber qué patrón hay que añadir.

Tres señales que te harán querer ejecutarlo:

1. mc_read_block empieza a devolver errores, pero tú ves en el juego que esa celda sí tiene algo.

2. El juego acaba de actualizarse y vas a hacer algo que dependa de la lectura (corrección, análisis de simetría).

3. Has cambiado el idioma del juego.

Las instructions del server también contienen esa misma pista, así que la IA encontrará esta herramienta por sí sola cuando el comportamiento sea sospechoso, sin que tengas que recordárselo.

Por defecto rellena la construcción de demostración con air, sin dejar basura en el mundo. Para dejarla visible:

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

Verificación que no requiere abrir el juego (tipos, pruebas, build, handshake de stdio, cierre de STDIN que libera el puerto y fallo de ocupación de puerto, todo de una vez):

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

3. Superficie de herramientas

Conexión y respaldo (4)

Agent — manos y pies (10)

La dirección del Agent es relativa a su propia orientación, no a los puntos cardinales del mundo.

Mundo (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 (hora／clima／reglas del juego／dificultad), mc_structure (guardar y leer estructuras), mc_ticking_area.

mc_query_target parsea la cadena JSON que devuelve querytarget; esta es la forma correcta de obtener las coordenadas del jugador o del Agent — consúltalo antes de construir.

La lectura tiene limitaciones inherentes; es mejor decirlo claro que fingir que no existen. Education no tiene un comando de «leer cualquier bloque», así que:

• mc_test_block es una pregunta de sí/no: tienes que adivinar primero un ID de bloque.

• mc_read_block no requiere adivinar — usa el aire como centinela para preguntar, y cuando falla, el mensaje del juego dice cuál es el bloque real. Pero devuelve el nombre de visualización localizado («tierra») en lugar del ID de bloque (dirt), y no se puede volver a alimentar a mc_set_block. Cuando no se puede parsear, esta herramienta devuelve un error, no una respuesta de éxito con null — la razón está más abajo.

• mc_verify_reading verifica activamente que esa ruta de parseo sigue funcionando. Ejecútalo una vez antes de clase y sabrás si se puede confiar en el resultado de mc_read_block.

• mc_compare_regions compara una región completa con un solo testforblocks. La comparación celda por celda choca con el timeout del host a partir de unos cientos de celdas; esto no. El modo masked ignora el aire de la fuente, ideal para comprobar «si está lo que debería estar» sin importar qué más hay alrededor — corregir trabajos de estudiantes tiene exactamente esta forma.

Por qué un fallo de parseo debe devolver un error en lugar de null

Porque el usuario de esta herramienta es una IA, y la IA no sospecha que el sistema esté roto.

Una respuesta de «éxito» con block: null se lee fácilmente como «leído, ahí está vacío». Entonces la IA continúa con mucha confianza basándose en esa percepción errónea — por ejemplo, sobrescribiendo como terreno vacío el trabajo que un estudiante construyó durante toda una clase, y sin ningún registro de error que consultar después. Una persona ve null, le parece raro y se detiene a depurar; la IA no.

Un error no se puede seguir usando como dato; ese es el punto.

mc_verify_reading es la otra mitad: no necesita saber de antemano qué hay en esa celda — si la celda es aire, pregunta con bedrock (el aire no puede ser bedrock, se garantiza el desajuste) para forzar un mensaje de fallo; si la celda tiene algo, la primera pregunta ya da el mensaje. Ambas rutas garantizan obtener un mensaje, con como máximo dos comandos, sin escribir nada en el mundo.

Esta línea de defensa está protegida por pruebas de mutación: si se rompe deliberadamente la regla de parseo, las 7 pruebas de sonda y parser deben ponerse en rojo.

Para leer celda por celda una región completa, usa behavior packs y Script API; este proyecto deliberadamente no va por ese camino, porque añadiría un paso de instalación más en los ordenadores de la escuela.

Modificar repetidamente el mismo edificio

El saveMode de mc_structure está diseñado precisamente para esto:

El control de versiones es poner nombres: castle_v1, castle_v2. El mismo nombre sobrescribe directamente; antes de cambiar de versión, cambia el nombre.

El juego no tiene un comando de «listar estructuras guardadas», así que lo que se ha guardado solo se puede recordar por el nombre. El puente recuerda la lista guardada en esta conexión; pregúntale a mc_status y la verás — pero solo cubre este proceso, se pierde al reiniciar (los archivos del modo disk siguen ahí; el nombre lo tienes que recordar tú).

Análisis de simetría — corregir trabajos

mc_analyze_symmetry comprueba si una región es simétrica por espejo, y cuando no lo es, señala qué celdas son asimétricas, no solo devuelve un «no».

Principio: testforblocks solo hace comparación por traslación, no por espejo; así que primero se guarda la región con structure save, luego se coloca su imagen especular en una zona temporal con el parámetro mirror de structure load, y se comparan las dos regiones. Si todo pasa, puntuación completa directamente; si no pasa, se desglosa celda por celda en n³ celdas, y la puntuación es la proporción de celdas coincidentes.

Esta herramienta escribe temporalmente en el mundo; el flujo es el siguiente, y si falla cualquier paso no deja un desastre:

1. Guarda la región de análisis — si falla, se aborta (normalmente porque el chunk no está cargado).

2. Primero hace una copia de seguridad de la zona temporal — si la copia falla, se aborta, y nunca se coloca la copia especular; el mundo queda intacto.

3. Coloca la copia especular, compara.

4. Tanto si tiene éxito como si no, restaura la zona temporal y borra la estructura temporal; el resultado de la restauración se reporta fielmente en scratchRestored, sin maquillar los fallos.

La zona temporal no puede solaparse con la región de análisis, o la copia especular sobrescribiría el edificio original — esta comprobación se hace antes de enviar ningún comando.

Jugador y feedback (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 (sonidos／partículas).

Construcción (4)

Eventos — percepción (4)

mc_events_catalog, mc_events_subscribe, mc_events_unsubscribe, mc_events_poll.

Los eventos entran en un buffer circular y se leen de forma continua con un cursor; dropped > 0 significa que el polling es demasiado lento y hay eventos que nunca se podrán leer. Tras reconectar, se vuelve a suscribir automáticamente.

4. Por qué construir no se bloquea

El enfoque ingenuo es enviar un setblock por cada bloque. Una esfera sólida de radio 20 tiene más de 33 000 celdas, es decir, más de treinta mil idas y vueltas de WebSocket — en la práctica equivale a congelarse.

La tubería de BlockHand es:

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

Una esfera sólida de radio 8 se comprime de más de 2 000 bloques a menos de 200 comandos, y el resultado de la fusión es determinista — la misma entrada siempre produce el mismo conjunto de lotes, así que hay pruebas que fijan que «el conjunto de bloques cubiertos tras la fusión debe ser exactamente igual al conjunto de puntos original», sin cubrir de más ni de menos.

Las formas huecas se implementan siempre con «determinación interna + prueba de vecinos de la carcasa», en lugar de escribir una matemática hueca distinta para cada forma. Para añadir una forma nueva solo hay que escribir inside(), y el comportamiento hueco es automáticamente consistente.

5. Límites de seguridad

Lo que no se hace

• No se conecta a redes externas: solo abre un listener WebSocket en 127.0.0.1.

• El runtime de MCP no escribe archivos en el host: no hay ninguna ruta de salida de artefactos. Solo cuando el usuario ejecuta explícitamente setup:<client>／uninstall:<client>, la CLI oficial de ese cliente actualiza la configuración MCP local.

• Hay que explicar una excepción: mc_structure con saveMode="disk" escribe la estructura como archivo a través del juego, en la carpeta del mundo de Minecraft. No es el runtime de MCP escribiendo archivos, pero sí deja algo en el disco del usuario. Por eso el valor por defecto es memory (temporal, desaparece al cerrar el juego), y solo se debe usar disk cuando el usuario lo pide explícitamente; además, la respuesta de la herramienta siempre dice dónde ha escrito — no deja archivos en silencio.

• No toca secretos: todo el proyecto no tiene tokens, cuentas ni credenciales.

• No conecta por iniciativa propia: si el juego no hace /connect, todas las herramientas devuelven mensajes de error accionables, sin fallar en silencio.

La puerta de mc_run_command

El principio de arquitectura 4 de mcp/README.md exige rechazar puntos de entrada de ejecución arbitraria. El criterio aquí es: el alcance de los comandos slash está completamente dentro del mundo del juego local, no toca el sistema de archivos del host, los procesos ni la red, así que no equivale a ejecución arbitraria de código. Lo que realmente hay que bloquear son las operaciones que invalidan el puente, por lo que la política es estructural, no una lista negra de palabras clave que adivina intenciones:

1. Solo se permiten líneas únicas — los saltos de línea y NUL se rechazan directamente; no se puede usar \n para dividir una petición en dos comandos.

2. Se rechazan wsserver y connect — eso apuntaría el juego a otro endpoint y todas las herramientas dejarían de funcionar.

3. El resto de comandos se etiquetan con nivel de riesgo read-only／world-write／wide-effect, y el MCP Host decide según las anotaciones si requiere confirmación humana.

Todos los IDs de bloque, selectores y cadenas de estado que se van a insertar en la línea de comandos pasan primero por una expresión regular de lista blanca, para evitar componer parámetros adicionales con espacios.

Protección para el aula (activada por defecto)

El punto 3 de arriba deja la decisión al Host, lo cual es válido en el contexto de desarrollo individual, pero el escenario de uso de este proyecto es el aula:

• El Host puede estar configurado para aprobación automática — es fácil que un profesor lo haga para que la clase fluya.

• Un estudiante que pueda hablar con esa IA puede dar comandos. No necesita hackear el puente; solo convencer al modelo.

• El mal uso ni siquiera necesita comandos raw: mc_player_action ya acepta @a y kill es una de las opciones. Así que bloquear solo los comandos raw es teatro; hay que bloquear ambas vías.

La regla se formula de una manera que se puede enseñar a un profesor en una frase: las acciones que afectan a «personas» deben nombrarlas explícitamente.

«Matar a toda la clase» pasa así de una frase a tener que nombrar uno por uno, y la gestión legítima del aula (vaciar el inventario de un estudiante concreto) no se ve afectada en absoluto.

Para desactivarlo, pon MINECRAFT_EDU_CLASSROOM_GUARD=0 — el propio mensaje de error te lo dice, para que nadie piense que la herramienta está rota.

Marcas comerciales

Según las Directrices de uso de Minecraft, las herramientas de terceros no deben parecer productos oficiales. El nombre del producto BlockHand no incluye deliberadamente la marca Minecraft; minecraft-edu es solo un nombre de carpeta descriptivo dentro de este espacio de trabajo privado. Si en el futuro se publica externamente, el nombre del paquete y cualquier exposición pública deben revisarse.

6. Configuración

Todo tiene valores predeterminados, .env no es imprescindible.

7. Mapa de módulos

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 入口

La capa de dominio no sabe nada de la existencia de WebSocket, por lo que toda la tubería de herramientas MCP se puede probar de principio a fin con simulacros de memoria pura: las 16 pruebas en tests/integration/mcp-client.test.ts no necesitan abrir el juego.

8. Limitaciones conocidas

• El mundo debe tener los trucos activados, de lo contrario el juego rechazará cada comando. Es una regla de Minecraft, no un error.

• Verificación en vivo en macOS completada (ruta de Claude Code): el 2026-08-25 se completó en macOS a través de Claude Code el flujo completo de /connect, lectura/escritura masiva (más de 45,000 bloques en una sola sesión, incluyendo fill/setblock/testforblock/teleport) y reconexión tras desconexión. Aún no se ha verificado la ruta de inicio "iniciar Codex Desktop desde Finder": la herencia de PATH y variables de entorno en el inicio por GUI es diferente, y aún requiere pruebas individuales.

• Agent es exclusivo de Education Edition, la versión Bedrock normal no tiene esta función.

• Los nombres de eventos y los subcomandos de agent no están documentados oficialmente por Mojang, provienen de observaciones públicas; los cambios de versión del juego pueden alterar el comportamiento. mc_events_subscribe permite nombres fuera de la lista, pero los marca como no verificados.

• El orden de los parámetros de agent setitem no está confirmado, actualmente no se ha convertido en una herramienta dedicada; si lo necesitas, usa mc_run_command.

• @s no siempre se puede resolver bajo comandos WebSocket: los comandos enviados desde el puente no tienen identidad de entidad; en pruebas, querytarget @s no responde en absoluto. Por lo tanto, mc_query_target usa @p (el jugador más cercano) por defecto, y live también prueba @p → @a → @e[type=player] en orden e informa cada resultado.

• Las construcciones grandes pueden chocar con el tiempo de espera de solicitud del host MCP: la herramienta de construcción envía cada fill y espera la respuesta del juego; en pruebas, una esfera hueca de radio 6 (126 comandos) tarda unos 13 segundos, pero puede ser más si el juego está ocupado. El tiempo de espera predeterminado del cliente MCP suele ser de 60 segundos; si se supera, se corta en el host (la herramienta en sí sigue ejecutándose). Usa mc_build_preview para ver fillBatches y construye por lotes si la cantidad es grande.

• Cada proceso de BlockHand sigue teniendo su propio puerto de escucha: cuando el cliente STDIO se cierra, el servidor cierra el WebSocket de Minecraft y libera el puerto. Cuando la versión de escritorio de la herramienta de IA carga múltiples tareas, o cuando la versión de escritorio/CLI/IDE se ejecutan en paralelo, la primera obtiene el puerto preferido y las demás obtienen automáticamente un puerto libre; usa siempre mc_status.connectCommand de la tarea actual para que el juego se conecte a la instancia que realmente quieres operar. Si necesitas un puerto fijo, puedes asignar diferentes MINECRAFT_EDU_WS_PORT a cada cliente, o establecer MINECRAFT_EDU_WS_PORT_FALLBACK en 0.

• El primer comando después del handshake solía fallar siempre por tiempo de espera, ahora corregido: se reprodujo en cuatro ejecuciones independientes en hardware real: el juego envía un marco cifrado antes de que el servidor instale el descifrador, y la desalineación del flujo hace que la respuesta a la siguiente solicitud no se pueda leer. AES-CFB8 se auto-sincroniza, por lo que solo afecta al primero. El adaptador ahora envía automáticamente un time query daytime de solo lectura después del handshake para absorber esa pérdida y descartar el resultado, de modo que la primera acción del llamador funcione normalmente. stderr registrará primed post-handshake stream.

• Los eventos solo se disparan cuando realmente ocurren: BlockPlaced solo se emite cuando el jugador coloca un bloque manualmente; /setblock y /fill no cuentan. Para recibir eventos, primero debes suscribirte y luego hacer que el evento ocurra realmente.

• El requestId de algunas respuestas no coincide con la solicitud (se ha observado que devuelven IDs todos ceros). El adaptador, cuando solo queda una solicitud pendiente, asigna la respuesta a esa solicitud y registra en stderr que fue inferida; de lo contrario, esas solicitudes se agotan silenciosamente y el llamador solo ve "sin respuesta" en lugar de la causa real del fallo.

• Solo se mantiene una conexión de juego a la vez; una nueva conexión reemplaza a la anterior.

• Entornos verificados en hardware real: Minecraft Education 1.26.32.0 (versión de escritorio Win32). Si se usa la versión UWP de Microsoft Store, el loopback será bloqueado por el aislamiento de aplicaciones de Windows, y se necesita una exención adicional de CheckNetIsolation LoopbackExempt. La matriz de aceptación para macOS 14+ se encuentra en agents/docs/macos-support.md.

9. Licencia

Este proyecto se publica bajo la Licencia MIT. Puedes usarlo, modificarlo, distribuirlo y sublicenciarlo libremente, incluso con fines comerciales, con la única condición de conservar el aviso de copyright y los términos de licencia originales.

El software se proporciona "tal cual", sin garantías expresas o implícitas de ningún tipo.

Minecraft y Minecraft Education son marcas comerciales de Mojang Studios y Microsoft; este proyecto no está afiliado a ellos ni cuenta con su respaldo.