MinecraftBot

Un jugador autónomo de Minecraft Java Edition basado en Mineflayer, MCP y una máquina de estados de Skills verificable. Se une al servidor como un personaje de juego independiente, percibe el mundo principalmente mediante datos estructurados a nivel de protocolo y puede navegar, recolectar, fabricar, combatir, construir y ejecutar tareas largas de forma continua.

Se recomienda utilizarlo junto con el agente de escritorio independiente Demiurge: Demiurge ofrece la configuración del personaje, el LLM actual, la memoria a largo plazo, las conversaciones con imágenes del escritorio y la toma de decisiones de alto nivel; MinecraftBot se encarga de conectar con el servidor, la percepción estructurada y la ejecución fiable. Ambos proyectos son independientes y no requieren instalar mods en el cliente de Minecraft.

Dos modos de funcionamiento

El proyecto no sube .env, claves de API, registros de ejecución, la base de datos de memoria SQLite ni datos locales de Minecraft.

Related MCP server: Minecraft Dedalus MCP

Capacidades implementadas

• Conexión fuera de internet con identidad offline o de Microsoft, reconexión automática y nombre de personaje fijo.

• Percepción de jugadores, inventarios, equipamiento, entidades, bloques, tiempo, clima y eventos.

• Resúmenes de escena, memoria de localizaciones, persistencia de tareas y recuperación tras caídas de conexión.

• Planificación mediante API LLM externa, recuperación de fallos y validación estricta de JSON.

• Base de datos precisa de objetos, bloques, criaturas y recetas, incluyendo cálculo recursivo de materiales.

• RAG local de guías invisible, que puede importar guías en Markdown/TXT.

• Bloqueo de recursos de Skills, prioridad de desalojo, tiempo de espera, cancelación, progreso, reintentos y verificación de resultados.

• Navegación, seguimiento, excavación, recolección, colocación, elaboración, fundición, combate, escape, alimentación, entrega, uso de cofres, construcción y exploración.

• Monitorización de alarma por poca vida, atascos, inventario lleno y herramientas con poca durabilidad.

• Memoria SQLite, interfaz de salud JSON y registros estructurados.

• Reproyección geométrica de la profundidad, clustering de regiones residuales, máscara de cambios conocidos e interfaz opcional de análisis VLM.

• Mock LLM y Mock Executor, para probar el sistema principal sin servidor de Minecraft ni clave de API.

• Herramientas/recursos MCP stdio, notificaciones de eventos del juego y el bucle cerrado de personaje, sesión y memoria a largo plazo con el mismo Demiurge.

Estructura de ejecución

PCL（FuQiang） ───────公网──────> 腾讯云 Minecraft Server
                                      ↑
本机 Demiurge ──MCP stdio──> Mineflayer AI_Player
      │ 当前角色/长期记忆           │ 结构化感知/RAG/Skill Runtime
      └────唯一 LLM 规划与对话──────┘

Requisitos del entorno

• Servidor Java de Minecraft.

• Node.js 22.13 o superior.

• pnpm 10 o superior, que se puede activar mediante Corepack.

• El modo MCP requiere un Demiurge con LLM configurado; para ejecución independiente solo se necesita API compatible OpenAI.

Instalación local

corepack enable
pnpm install
cp .env.example .env

Para ejecución independiente, al menos hay que ajustar:

MC_HOST=127.0.0.1
MC_PORT=25565
MC_USERNAME=AI_Player
MC_AUTH=offline
MC_OWNER=FuQiang

LLM_MODE=api
LLM_BASE_URL=https://你的API地址/v1
LLM_API_KEY=你的密钥
LLM_MODEL=你的模型名

Haz primero una autocomprobación sin conexión:

pnpm typecheck
pnpm test
pnpm smoke

Inicia el modo de desarrollo:

pnpm dev

Modo de producción:

pnpm build
NODE_ENV=production pnpm start

Uso de Demiurge (recomendado)

Compila los dos proyectos por separado:

# 本项目
pnpm install --frozen-lockfile
pnpm build

# Demiurge（单独克隆）
git clone https://github.com/Dancncn/Demiurge.git
cd Demiurge
npm install
npm run tauri dev

En Windows, compilar Demiurge además necesita Rust stable (MSVC), la Workloads de Visual Studio 2022 Build Tools “Desarrollo de escritorio con C++” y el Windows SDK. Si aparece el error de que no se encuentra link.exe, instala estos componentes.

En “Configuración → Minecraft” de Demiurge, selecciona el directorio de este proyecto y el ejecutable de Node.js, escribe la IP pública del servidor, el nombre del usuario de IA AI_Player y el nombre del personaje del usuario principal FuQiang, y por último activa la opción. Al guardar la configuración, Demiurge iniciará automáticamente el subproceso MCP. Al salir, desactivar o cambiar la configuración, lo detendrá o reiniciará.

El modo MCP obliga a usar MCP_STDIO=true y LLM_MODE=mock. Aquí mock solo significa que Mineflayer usará el modelo de planificación; todas las planificaciones, el personaje y el diálogo los Models del LLM real configurado en ese momento en Demiurge.

El chat público y el privado pueden llevar el nombre de usuario real, el canal, la identificación del usuario principal y el escenario. Si el jugador escribe AI_Player，跟着我, se le puede mencionar de forma natural. Los mensajes públicos no dirigidos son juzgados por el modelo junto con el contexto del diálogo para decidir si van al AI. Las conversaciones y las experiencias clave se guardan en el mismo namespace de memoria que el personaje actual; la memoria automática dura se escribe de forma manual en el escenario, canal, usuario y autor principal, sin depender de que se remitan en el modelo de memoria.

El área de entrada de escritorio admite imágenes nativas multimodales JPEG, PNG, GIF, WebP (10 MB por imagen, 20 MB en total). Las imágenes solo se envían al modelo actual de Demiurge y no se tramitan por el chat del juego.

Consulta la configuración completa y la validación del multiplayer en la Guía de integración de Demiurge.

Configuración del servidor Minecraft

server.properties:

online-mode=false
server-port=25565
server-ip=
white-list=true

Después de reiniciar el servidor, ejecuta en la consola:

whitelist on
whitelist add FuQiang
whitelist add AI_Player

El modo offline no tiene una autenticación de cuenta fiable. El grupo de seguridad debe permitir el acceso a TCP:25565 solo a tu IP pública, o deberías conectar mediante Tailscale/WireGuard. No hay que basarse en las listas blancas para evitar la suplantaciónización de nombre.

Comandos del juego

MC_OWNER define al usuario principal; la comparación de nombres no distingue mayúsculas, pero los eventos y la memoria guardan el nombre exacto que el jugador muestra en display. El modelo separa las relaciones, permisos y recuerdos del usuario principal y los de otros jugadores. Otros jugadores aún pueden chat público, privado y pedir ayuda normal. En modo MCP, el mensaje natural se pasa de forma unificada al personaje actual de Demiurge para su análisis y procesamiento. En modo independiente solo ejecuta las tareas en las que el usuario principal menciona explícitamente el nombre del IA.

AI_Player，帮助
AI_Player，状态
AI_Player，停止
AI_Player，跟着我
AI_Player，去 120 64 -30
AI_Player，收集16个橡木
AI_Player，制作一把石镐并交给我
AI_Player，探索周围区域

El prefijo fijo @AI ha sido eliminado. Usa el nombre de usuario de la IA definido en la configuración y se le indica directamente; los mensajes privado se consideran de forma natural como para la IA, y el modelo decide si necesita encargarse de las llamadas no dirigidas.

Base de habilidades

La receta y el registro preciso uses minecraft-data del servidor actual, sin hacer búsqueda por vector. Las guías de lenguaje natural se pueden importar de forma masiva:

pnpm knowledge:index ./my-guides

Admite recuperación recursiva de .md y .txt. Por defecto se usan vectores de hash de recuperación local, sin coste añadido de embedding. En el futuro se puede sustituir la implementación vectorial de GuideRag.

Comprobación de funcionamiento

Por defecto solo observa la máquina en la nube:

GET http://127.0.0.1:3008/health
GET http://127.0.0.1:3008/metrics

Puedes desactivar HEALTH_PORT=0. No expongas este puerto de salud a la red pública.

Módulo de visión

El sistema principal no depende de capturas de pantalla. src/vision incluye:

• Reprojección geométrica de la profundidad del frame anterior y la matriz de cámara.

• Residual RGB entre el frame real y el frame predicho.

• Máscara de regiones con acciones conocidas.

• Agrupación de regiones conectadas y filtrado de umbral.

• Eventos anómalos y llamadas opcionales de VLM.

Mineflayer no porporciona de forma nativa RGB y buffered. por profundidad, por lo que el modo visual necesita un rendererizador fuera de pantalla o un mod del cliente que entregue los fotogramas. Este proyecto ya proporciona HttpFrameSource; solo hay que añadir VISION_ENABLED=true y VISION_FRAME_URL=http://127.0.0.1:端口/frame. Si no hay fuente de frames, mantén VISION_ENABLED=false y la demás funcionalidad del juego sigue usando perception estrutural.

Límites de seguridad

• PVP desactivado por defecto: ALLOW_PVP=false.

• Puedes desactivar el lanzamiento de objetos: ALLOW_DROP_ITEMS=false.

• El plan simple como máximo MAX_PLAN_STEPS pasos.

• El objetivo sencillo está limitado por MAX_ACTION_DISTANCE.

• El modo independiente solo hace tareas en las que el usuario principal menciona el nombre del AI; el modo MCP decide si el AI debe invocad en público.

• El LLM solo puede elegir Skill registrado; los parámetros pasan por Zod.

• Las claves de API solo se leen de las variables de entorno, y los logs se tratan con compensación de campos.

• El escape urgent siempre tiene prioridad sobre tareas normales, puede romver el control de movimiento y cámara.

Para los pasos concretos de despliegue en Tencent Cloud véase [docs/DEPLOY_TENCENT.md](docs/DEPLOY_TENCENT. md), para la interface Skills docs/SKILLS.md, y para el convenio de visión docs/VISION.md.

Límites del proyecto

• Orientado a Minecraft Java Edition, la conexión de protocolo la da Minecraft.

• La perception estructura es la ruta principal por defecto; una parte vision and VLM need additional frame source.

• El movimiento y el combate de niveles de microsecond / milisecon do son gestionados por el Ejecutor y el Skill; el LLM no está en cada fotograma.

• Los servidores offline no pueden verificar de forma fiable la propiedad de los nombres de usuario, por lo que debe limitar la fuente de acceso al servidor o usar una red privada.

• En modo MCP, todos los chats públicos pueden generar el juicio de contexto del Demiurge, y deberías evaluar el costo de API basado en el número de jugadores del servidor.

Desarrollo y validación

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

Las pruebas no requieren un servidor de Minecraft real ni Key de LLM real; también Mock Executor y Mock LLM cubren la main flow de planificación, Skills, memoria, notificaciones MCP y residual de visión.