pm-minecraft

Un cuerpo de supervivencia de Minecraft autónomo para clientes MCP.

Ejecuta Mineflayer, Prismarine Viewer, una interfaz web local y un servidor MCP HTTP Streamable.

No contiene un agente, modelo ni runtime cognitivo. Solo algunas instrucciones mínimas que le dicen a tu agente elegido cómo usar el MCP, mirar capturas de pantalla y crear scripts TypeScript personalizados, que se pueden ejecutar a través de MCP.

Muchas gracias a https://github.com/minedojo/voyager y https://github.com/Mega-Gorilla/Discovery :3

Esto es parte de un esfuerzo continuo de mi parte para hacer un compañero de IA con arquitectura cognitiva divertido que pueda jugar Minecraft contigo. También funciona como independiente ^_^

Configuración

Requisitos: Windows PowerShell, Node.js 20+, Python 3.12 a través de py, y un servidor de Minecraft Java 1.19.x accesible con el personaje en modo supervivencia.

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

La configuración sigue el flujo de trabajo PM compartido: usa uv para crear el .venv de Python 3.12 de este repositorio, sincroniza su lockfile e instala los paquetes Node bloqueados. scripts/setup.ps1 permanece como un envoltorio de compatibilidad.

Si no funciona, dile a tu agente de codificación que lo arregle.

Related MCP server: Godot MCP Runtime

Minecraft

Robé la configuración de https://github.com/Mega-Gorilla/Discovery.

Nunca he moddeado Minecraft manualmente, lo que me funciona:

• Descargar Prism

• Instalar 1.19.4

• Instalar Fabric Loader 0.19.3

• Instalar estos mods a través de Prism:

  • Fabric API

  • CompleteConfig

  • Mod Menu

  • Multiplayer Server Pause (Forge)

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

• Crear mundo de supervivencia, con trucos habilitados, pacífico

• Entrar y "Abrir a LAN" en el puerto 12345

Crear y iniciar un personaje

.\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

El inicializador crea el espacio de trabajo del agente, memory/minecraft/, drafts/, skills/, lib/minecraft.ts y .mcp.json. El lanzador imprime la interfaz web local, el visor de Prismarine y las URLs del MCP. Para varios personajes, usa valores únicos -WebPort, -ViewerPort y -McpPort.

Cada ejemplo de deploy/drafts/*.ts se copia en el drafts/ del espacio de trabajo y se lista en su AGENTS.md. Se ejecutan tal cual a través de minecraft_execute_typescript, por lo que el agente puede ejecutar uno directamente o copiar su forma de guarda-y-verifica en un nuevo borrador. Agrega un ejemplo a deploy/drafts/ para enviarlo con cada nuevo personaje.

El agente puede llamar a minecraft_list_capabilities antes de escribir un nuevo comportamiento. Si ninguna capacidad encaja, el agente escribe un borrador TypeScript a partir de acciones genéricas del cuerpo. El agente ejecuta el borrador con una postcondición determinista. Después de una ejecución exitosa, minecraft_promote_skill copia el borrador en skills/. El registro de promoción incluye el hash de origen, el ID de ejecución y la postcondición.

Las observaciones de entidades incluyen IDs de runtime estables mientras cada entidad permanezca cargada. La acción genérica attack_entity realiza un ataque de supervivencia ordinario contra un ID observado. Para un objetivo de matar, el agente debe verificar un resultado de supervivencia, como un aumento en el inventario. Una habilidad puede combinar observación, movimiento, equipo, ataques y verificación en comportamientos como cazar.

Detén una instancia con:

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

Luego úsala desde el espacio de trabajo:

Set-Location C:/Temp/Floppa
codex

Codex lee .mcp.json. Indícale que use el servidor minecraft; los registros de estado y las capturas de pantalla están en ./artifacts/minecraft.

Modos de percepción y visor

minecraft_find_block por defecto usa require_visible: true. Esta es la configuración normal de supervivencia: devuelve solo bloques con un rayo sin obstrucciones desde la cabeza del personaje. Un agente debe explorar, moverse a un mejor punto de vista o usar una observación diferente cuando no puede ver el objetivo. Para planificación de largo alcance, establece require_visible: false; el resultado es solo una ubicación en el mundo cargado y aún debe alcanzarse y verificarse visualmente antes de minar.

Registro en disco

Todo se escribe bajo la raíz de artefactos del personaje (artifacts/minecraft/):

• states/ — un archivo de estado completo sin procesar por instantánea (<timestamp>-mcstate-<id>.yaml). Cada estado almacena solo los mensajes de chat vistos por primera vez en ese estado, por lo que cada mensaje de chat existe exactamente una vez en todo el árbol; reconstruye la transcripción recorriendo los archivos en orden. Cada estado enlaza a su captura de pantalla; nunca contiene bytes de imagen ni metadatos de captura duplicados. current_state.yaml es un archivo puntero que solo contiene la ruta relativa del estado más reciente.

• screenshots/ — el único lugar donde viven las imágenes (.png más un pequeño archivo lateral de metadatos por fotograma). Los estados y acciones solo enlazan a estos.

• actions/ — un yaml plano por llamada de herramienta MCP, nombrado <timestamp>_<tool>.yaml, escrito sobre la marcha (un archivo inicial con la herramienta y la entrada aparece en el momento en que comienza la llamada, antes/después de que se agreguen los enlaces de estado + captura a medida que ocurren las instantáneas, y la salida de herramienta sin procesar y bien formateada, la duración y cualquier excepción aterrizan en la reescritura final). Campos: tool, tool_input, tool_output (ambos escalares de bloque JSON bonitos), los cuatro enlaces before_state_path / before_screenshot_path / after_state_path / after_screenshot_path (vacíos cuando la herramienta no hizo ningún estado, solo antes para herramientas como minecraft_observe que hacen uno), más encabezados de búsqueda como execution_id / skill_path para habilidades. El éxito o el fracaso se lee directamente de los datos de retorno en tool_output; las excepciones aterrizan en un bloque error:.

• mcp-server.log — cada error de cuerpo/red capturado y cada excepción no manejada (con traceback) aterriza aquí.

Los resultados de las herramientas devuelven los mismos enlaces (beforeStatePath / afterStatePath / beforeScreenshotPath / afterScreenshotPath) en lugar de incluir todo el estado, para que el modelo siga los archivos cuando necesite detalles.

Las capturas de pantalla se capturan y escriben en artifacts/minecraft/screenshots para cada estado - antes y después de cada acción, en cada llamada minecraft_observe - independientemente de include_image, siempre que el servidor se inicie con la captura de imágenes habilitada (por defecto; deshabilita con --no-images). Esto da un historial visual completo y sin interrupciones en disco de la ejecución para análisis posterior, incluso para estados que el agente nunca miró.

include_image solo controla si los bytes de píxeles también se adjuntan a la respuesta de esa llamada de herramienta específica para que el agente pueda verlos ahora mismo; minecraft_observe por defecto usa include_image=true (todas las demás herramientas usan include_image=false para mantener las acciones rutinarias baratas en contexto). Pasa include_image=false a minecraft_observe para omitir poner la imagen en la respuesta cuando solo se necesita el estado - la captura de pantalla aún se captura y se guarda en disco de cualquier manera. Una captura de pantalla que se solicitó pero falló al capturarse (visor/bot no listo, no se encontró un navegador compatible) se reporta como screenshot: {"error": ..., "message": ...}, distinto de screenshot: null (la captura de imágenes está deshabilitada en todo el servidor a través de --no-images).

Navegación (solo caminar)

minecraft_walk_to solo camina. Puede subir escalones de 1 bloque y bajar 1 bloque, pero no cava, coloca andamios, construye torres, hace parkour ni abre puertas. Apunta a la posición horizontal (GoalNearXZ, por lo que la altura del terreno se elige automáticamente) usando un objetivo estático dentro de una región centrada en el inicio de chunk_limit chunks (por defecto 3, limitado por el máximo configurado del servidor). Si el objetivo está fuera de esa región, no tiene un piso estable cerca, o no tiene una ruta a pie, la llamada falla rápidamente en lugar de quedarse esperando.

tolerance por defecto es 1.5. El presupuesto de búsqueda A* (walkSearchTimeoutMs, por defecto 1000) limita cuánto tiempo puede tomar la búsqueda de ruta antes de fallar con un mensaje de "muévete más cerca".

Túneles y navegación de larga distancia

• minecraft_mine_block normalmente requiere línea de visión desde la cabeza, lo cual es imposible para el bloque adyacente a nivel de los pies dentro de un túnel de 1 de ancho. Ahora omite esa restricción para objetivos dentro de --mine-visibility-ignore-distance bloques (por defecto 3, pasa -MineVisibilityIgnoreDistance al script de inicio) para que puedas hacer túneles en línea recta desde un túnel de 1 de ancho.

• minecraft_walk_to acepta un chunk_limit de hasta --max-chunk-limit (por defecto 8). Las solicitudes más grandes se rechazan con error: requested chunk limit (N) greater than allowed (M).

• minecraft_pillar_up reporta un error claro pillar_up_needs_placeable_block cuando el objeto sostenido no es un bloque colocable, y explica que el espacio libre de aterrizaje debe despejarse primero; dig_up despeja el espacio libre por salto.

• Borradores que se envían con cada personaje (desplegados automáticamente en drafts/):

  • dig_staircase(height, distance, stop) — rampa descendente transitable de 2 de alto.

  • clear_room(width, depth, height) — expande un túnel de 1 de ancho en una habitación.

  • dig_up(targetY) / descend_to_depth(targetY, stopOnOre) — ascenso/descenso de un solo salto seguro contra peligros que inspecciona lava/agua antes de cavar.

  • tunnel_forward / tunnel_iron / branch_mine_safe_iron — túneles y minería de mineral, todos protegidos contra peligros (se detienen antes de cavar en agua/lava).

  • place_crafting_table / place_block / climb_pillar / find_village (patrulla de larga distancia que informa cuando ve a un aldeano).

Ejecuciones detenidas, tiempos de espera y el guardián anti-estancamiento

• minecraft_stop detiene el comando Mineflayer activo y termina cualquier proceso de habilidad TypeScript en ejecución (mata ambos). minecraft_kill_command detiene solo el comando físico actual; minecraft_kill_skill termina solo el proceso de habilidad en ejecución.

• Cancelación cooperativa: las habilidades verifican un marcador de señal de muerte en cada llamada de API / sueño y salen limpiamente (SkillCancelledError) cuando se detienen, por lo que minecraft_stop/kill_skill (y una desconexión del cliente) detienen una habilidad rápidamente y le permiten escribir su resultado — el runner solo se mata a la fuerza si ignora el marcador.

• Tiempo de espera de habilidad configurable: minecraft_set_skill_timeout(seconds) (1..3600) establece la duración máxima para minecraft_execute_typescript y minecraft_collect_blocks (por defecto 90; el valor predeterminado en el lanzamiento a través de -SkillTimeoutSeconds / --skill-timeout-seconds). Las habilidades largas se ejecutan en un subproceso separado y se terminan en el lado del servidor en ese tiempo de espera.

• Coincide con tu ventana de cliente: el requestTimeoutMs del .mcp.json del agente (por defecto del personaje 200000) debe permanecer POR ENCIMA del tiempo de espera de habilidad del servidor, de lo contrario las habilidades largas se cortan en el lado del cliente antes de terminar. Regla general: establece minecraft_set_skill_timeout a requestTimeoutMs - 10s.

• El disyuntor de repetición-sin-ganancia está deshabilitado por defecto. Era un vestigio de modelos más antiguos y débiles que reintentaban una operación idéntica sin ganancia en un bucle; vinculado a un solo "elemento relevante", bloqueaba incorrectamente operaciones de habilidad no relacionadas. Vuelve a habilitarlo explícitamente cuando lo quieras con el argumento MCP --enable-anti-stall-guard (-EnableAntiStallGuard en el script de inicio).

Transparencia de estado

• Cada estado (completo y delta) siempre lleva la position del jugador, health, food y foodSaturation, y cada resultado siempre informa el heldItem actual, por lo que un agente nunca tiene que inferir sus propias estadísticas vitales o la herramienta sostenida a partir de un diff.

• minecraft_collect_blocks equipa la herramienta más barata que cosecha el bloque objetivo de antemano (en lugar de morir a mitad de ejecución con un rechazo unharvestable), y el cuerpo ya no cambia el objeto sostenido excepto cuando collect_blocks necesita una herramienta diferente.

Consejos de pruebas en vivo (ergonomía del agente)

Estos provienen de sesiones reales en el juego con un agente de codificación y valen la pena codificarlos en el AGENTS.md de tu agente o en los prompts de habilidades:

• Las coordenadas son planas en las herramientas envoltorio: minecraft_walk_to(x,y,z,…) / minecraft_mine_block(x,y,z,…) toman números separados, NO un objeto position/block. Para esquemas de acción anidados usa minecraft_call con las formas en minecraft_info (p. ej. {"action":"place_block","parameters":{"referenceBlock":{…}}}).

• Sondea antes de cavar: lee hazards (agua/lava) e inspect la siguiente celda antes de tunelar. Los borradores de envío se detienen ante un peligro; un mine_block directo hacia agua/lava deja al bot varado.

• Deriva de la herramienta en mano: un mine_block o pillar_up con tendencia a escalar puede dejar un bloque colocable (tierra/adoquín) en la mano en lugar de una herramienta. Vuelve a equipar y verifica después de cualquier minado con tendencia a escalar; las herramientas también se rompen por durabilidad, así que ten un pico de repuesto.

• Mina en ancho, no en 1 de ancho: los túneles de 1 de ancho solo exponen la cara frontal y pasan de largo el mineral en las paredes laterales. Usa clear_room/branch_mine_safe_iron (de 3 de ancho) para exponer el mineral, y trata el resultado de línea de vista (anti-x-ray) de find_block como "ve a mirar / mina para revelarlo".

• Los viajes largos por tierra funcionan con el caminar dinámico de transmisión de fragmentos; mantén cada walk_to dentro de tu ventana de cliente y cubre mucho más terreno que saltos de un fragmento.

• Tiempos de espera: mantén minecraft_set_skill_timeout en requestTimeoutMs - 10s para que las habilidades largas terminen en lugar de cortarse. minecraft_info informa el valor actual; vuelve a leerlo siempre que la documentación se desvíe.

• Prefiere muchas habilidades pequeñas y reversibles sobre una sola enorme e irreversible; cada una necesita una postcondición determinista. minecraft_observe + minecraft_stop te permiten rastrear y detener cualquier ejecución desviada.

Cosas interesantes

Aquí está la interfaz web donde puedes controlar manualmente al personaje o ver cómo el agente de codificación usa el MCP.

Y aquí está Codex describiendo la piel de mi personaje. Prismarine solo renderiza el Steve predeterminado :(

Desarrollo

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

Uso programático (pip install)

pm-minecraft se puede incrustar directamente en otro proyecto de Python — por ejemplo, una arquitectura cognitiva que mantiene vivo a un personaje de Minecraft en hilos daemon. Sin scripts ps1, sin subprocess.Popen de lanzadores, y sin procesos hijos separados en ningún lugar: cada proceso de Node está adjunto a su padre de Python a través de una tubería de ciclo de vida de stdin. Cuando el padre muere — de forma elegante o con un kill forzado — el sistema operativo cierra la tubería, Node ve EOF y se apaga limpiamente. Misma semántica en Windows y Linux.

Instalación

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

Requisitos para la máquina de destino:

• Python 3.12 y Node.js 20+ en PATH (node y npm).

• La primera vez que un personaje se inicia en un entorno de Python, el paquete instala su árbol de dependencias de Node una vez en <venv>/pm-minecraft-runtime/<version>/ (ejecuta npm ci bajo un bloqueo de archivo; una sola vez, un par de minutos). Cada inicio posterior es instantáneo. Precalienta con pm_minecraft_mcp.ensure_node_runtime().

• Un servidor de Minecraft Java 1.19.x accesible con el personaje en modo supervivencia (igual que la configuración independiente).

Puntos de entrada

Todo es un objeto de configuración tipado más funciones bloqueantes diseñadas para ejecutarse en hilos daemon:

• pm_minecraft_mcp.ServerConfig(...) — todos los ajustes: host/puerto de Minecraft, nombre de usuario, hogar del agente, raíz de artefactos, hosts+puertos web/visor/MCP, tiempo de espera de inicio, captura de imágenes, límites de habilidades, distancia de visión.

• pm_minecraft_mcp.execute_node_main_loop(config) — ejecuta el cuerpo de Minecraft (un proceso de Node) y bloquea hasta que sale.

• pm_minecraft_mcp.execute_python_main_loop(config, manage_body=True) — ejecuta el servidor MCP y bloquea mientras sirve. Con el valor predeterminado manage_body=True también inicia y posee el cuerpo en sí (un hilo es suficiente); con manage_body=False espera que el cuerpo sea gestionado por un hilo compañero execute_node_main_loop y espera a que esté listo.

• pm_minecraft_mcp.init_character(name, agent_root, artifact_root, ...) — puerto de Python de scripts/init_character.ps1: crea el espacio de trabajo del agente (AGENTS.md, .mcp.json, lib/minecraft.ts, drafts/, skills/, memory/minecraft/). Rechaza raíces de agente no vacías.

• pm_minecraft_mcp.check_prerequisites(config) — las comprobaciones de fallo rápido, también se ejecutan automáticamente antes de que se lance cualquier cosa: hogar del agente inicializado, servidor de Minecraft accesible por TCP, puertos de servicios locales libres, node en PATH. Cada fallo se eleva inmediatamente con un mensaje específico. Después de que el cuerpo se une, la versión negociada debe ser 1.19.x y el modo de juego supervivencia, de lo contrario el punto de entrada se eleva.

Ejemplo

examples/main.py inicia un personaje en dos hilos daemon y se apaga con 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

La variante de un solo hilo también funciona: un hilo daemon en execute_python_main_loop(config) inicia tanto el cuerpo como el MCP.

Múltiples personajes

Usa una configuración (nombre de usuario único + puertos web/visor/MCP únicos) por personaje y dale a cada uno su propio par de hilos daemon. El runtime de Node se comparte de solo lectura entre todos los personajes en el mismo entorno de Python.

El comportamiento del lado del agente no cambia

Desde la perspectiva del cliente MCP nada cambia: los mismos nombres de herramientas, esquemas, diseño de .mcp.json y contrato de minecraft_execute_typescript. Un agente aún puede escribir un borrador de TypeScript arbitrario en su espacio de trabajo y ejecutarlo contra el servidor; los borradores se ejecutan a través del runtime tsx del paquete con lib/minecraft.ts del hogar del personaje.

Garantías de ciclo de vida

• El cuerpo es un proceso de Node (sin procesos envoltorio npm/tsx); las ejecuciones de habilidades también son un proceso cada una. No hay árboles de procesos que perseguir.

• Los hijos nunca reciben CREATE_NEW_PROCESS_GROUP y nunca se les hace taskkill. El apagado es primero EOF de stdin, y un kill() simple como último recurso.

• Matar el proceso incrustante en cualquier momento (incluyendo taskkill /F o kill -9) no puede dejar huérfano al cuerpo: la tubería de ciclo de vida se rompe y Node sale en cuestión de segundos.