mcdev-mcp

Un servidor MCP que ayuda a agentes de codificación a trabajar con el desarrollo de mods de Minecraft

Documentación

mcdev-mcp

Un servidor MCP (Model Context Protocol) que permite a los agentes de codificación de IA trabajar eficazmente con el desarrollo de mods de Minecraft. Proporciona tanto análisis estático del código fuente descompilado como interacción en tiempo de ejecución con una instancia de Minecraft en ejecución.

Características

Análisis estático (funciona sin conexión)

Acceso a código fuente descompilado — Descarga y descompila automáticamente el cliente de Minecraft usando Vineflower
Soporte para instantáneas de desarrollo — Funciona con instantáneas de desarrollo (p. ej., 26.1-snapshot-10) que carecen de mapeos ProGuard
Búsqueda de símbolos — Busca clases, métodos y campos por nombre (mc_search)
Recuperación de código fuente — Obtén el código fuente completo de una clase o métodos individuales con contexto
Exploración de paquetes — Lista todas las clases bajo una ruta de paquete o descubre paquetes disponibles
Jerarquía de clases — Encuentra subclases e implementadores de interfaces
Análisis de grafo de llamadas — Encuentra llamadores y llamados de métodos en todo el código base

Interacción en tiempo de ejecución (requiere el mod DebugBridge)

Ejecución de Groovy en vivo — Ejecuta scripts de Groovy dentro de la JVM de Minecraft en ejecución (mc_execute); migrado desde Lua a mediados de 2026
Instantáneas del estado del juego — Posición del jugador, salud, dimensión, hora, clima (mc_snapshot)
Capturas de pantalla, grabaciones e inspección de pantalla — JPEG de la ventana del juego, hoja de contactos de múltiples fotogramas para depuración temporal y estructura de la GUI actual (mc_screenshot, mc_record_video, mc_screen_inspect)
Introspección del mundo — Entidades y entidades de bloque cercanas, más detalles por id (mc_nearby_entities, mc_entity_details, mc_nearby_blocks, mc_block_details, mc_looked_at_entity)
Marcadores visuales — Delimita entidades o bloques para que el usuario los localice (mc_set_entity_glow, mc_set_block_glow, mc_clear_block_glow)
Renderizado de texturas de objetos — Renderiza una ranura de inventario, un id de objeto o una ranura en otra entidad como PNG (mc_get_item_texture, mc_get_item_texture_by_id, mc_get_entity_item_texture)
Historial de chat — Mensajes de chat recientes del lado del cliente (mc_chat_history)
Control de sesión y bucle de desarrollo — Unirse/salir de servidores, cerrar el cliente y reconectarse tras un reinicio (mc_join_server, mc_leave_server, mc_quit_client, mc_wait_for_bridge, mc_wait_until_in_world; controlado por session_control_enabled en la configuración de DebugBridge). La orquestación de compilación/inicio es tarea del agente de codificación, guiada por el recurso mcdev://guides/dev-loop y la habilidad minecraft-dev-loop.
Comandos de barra — Ejecuta comandos dentro del juego (mc_run_command, herramienta de desarrollo opcional)
Registros de ejecución de scripts — Revisa ejecuciones anteriores de mc_execute y patrones de error (mc_script_logs, opcional mediante configuración de usuario de Claude Desktop)

Recursos MCP

mcdev://guides/python-scripting — Referencia del protocolo de cable para agentes de IA que quieran controlar DebugBridge directamente desde Python (omitiendo las herramientas MCP): encapsulado WebSocket, un cliente asyncio mínimo y la superficie Groovy que se envía a través de él. Se expone mediante el estándar MCP resources/list + resources/read, con una referencia en el instructions del servidor para que los agentes sepan dónde mirar.

Inicio rápido

Nota de seguridad: init es intencionalmente solo de terminal. El servidor MCP solo expone herramientas de lectura/consulta. La descarga y descompilación de las fuentes de Minecraft debe activarla usted en la terminal; un agente de IA conectado al servidor no tiene superficie de herramientas para activar init, rebuild, clean ni callgraph.

1. Inicialice en su terminal

# Download, decompile, and index Minecraft sources (~2-5 minutes)
npx mcdev-mcp init -v 1.21.11

Este comando:

Descarga el JAR del cliente de Minecraft
Descompila con Vineflower (Java puro, 8 hilos)
Construye el índice de símbolos (clases, métodos, campos, herencia)
Genera el grafo de llamadas para mc_find_refs

Los datos se almacenan en el directorio de caché de su sistema operativo (consulte Ubicación de almacenamiento más abajo), por lo que persisten entre invocaciones de npx. Espere aproximadamente ~2 GB por versión de Minecraft, principalmente fuentes .java descompiladas y una base de datos SQLite de grafos de llamadas. Todo es regenerable, por lo que su sistema operativo puede eliminarlo libremente bajo presión de almacenamiento y init reconstruirá lo que necesite.

2. Añada a su cliente MCP

Codex Desktop / Codex CLI

Codex puede lanzar servidores MCP stdio locales directamente. Instale el paquete publicado con:

codex mcp add mcdev-mcp -- npx -y mcdev-mcp serve

Si está desarrollando desde una copia local, compile primero y apunte Codex al servidor local:

git clone https://github.com/use-ai-for-mc/mcdev-mcp.git
cd mcdev-mcp
npm install
npm run build
codex mcp add mcdev-mcp -- node "$(pwd)/dist/index.js"

Verifique que Codex puede verlo:

codex mcp list
codex mcp get mcdev-mcp

Reinicie Codex Desktop o inicie una nueva sesión de Codex después de añadir el servidor. Codex lanzará el servidor MCP automáticamente cuando una sesión lo necesite; no ejecute serve manualmente.

Otros clientes MCP

{
  "mcpServers": {
    "mcdev": {
      "command": "npx",
      "args": ["-y", "mcdev-mcp", "serve"]
    }
  }
}

El subcomando serve inicia el servidor MCP sobre stdio. Su cliente MCP (Claude Desktop, Cursor, etc.) lo lanza automáticamente; nunca ejecuta serve directamente.

3. (Opcional) Instale DebugBridge para herramientas de juego en vivo

Las herramientas de análisis estático (mc_search, mc_get_class, mc_find_refs, …) funcionan en cuanto init termina. Las herramientas de tiempo de ejecución (mc_execute, mc_snapshot, capturas de pantalla, introspección del mundo, texturas de objetos, marcadores luminosos, etc.) requieren además el mod DebugBridge instalado en la instancia de Minecraft que desea controlar. Sin DebugBridge, esas herramientas solo informarán de un error de conexión; la parte estática sigue funcionando sin verse afectada.

Versiones compatibles

Tipo de versión	Ejemplo	Notas
Esquema nuevo (`26.x` y posterior)	`26.1`, `26.1-snapshot-10`	Recomendado. Se distribuye pre-desofuscado; sin paso de mapeo ProGuard.
Versiones `1.14` – `1.21.x`	`1.21.11`, `1.20.4`, `1.19.4`	Compatible. Se requieren los mapeos ProGuard oficiales de Mojang (se descargan automáticamente).
Versiones antiguas (`< 1.14`)	`1.13`, `1.12.2`	No compatible: no se publican mapeos oficiales.

El validador se encuentra en src/cli.ts (isValidVersion). Para versiones 1.x.x requiere 1.14 o posterior; el nuevo esquema 26.x+ se acepta incondicionalmente.

(Opcional) Omitir grafo de llamadas

# Skip callgraph generation if you don't need mc_find_refs
npx mcdev-mcp init -v 1.21.11 --skip-callgraph

# Generate callgraph later
npx mcdev-mcp callgraph -v 1.21.11

Verificar la instalación

npx mcdev-mcp status

Nota: mc_version (con action: "set") debe llamarse antes de usar cualquier otra herramienta MCP estática. Si la versión no está inicializada, se indicará a la IA que le pida ejecutar init.

Instalar desde el código fuente (desarrollo)

git clone https://github.com/use-ai-for-mc/mcdev-mcp.git
cd mcdev-mcp
npm install
npm run build

# Use the local build instead of npx
node dist/cli.js init -v 1.21.11
node dist/cli.js serve         # stdio MCP server; MCP clients launch this

¿Actualizando desde una versión anterior? Si tiene una instalación anterior que usa DecompilerMC, ejecute npx mcdev-mcp clean --all primero para eliminar los datos antiguos en caché.

Herramientas MCP

Gestión de versiones (herramientas estáticas)

Antes de usar herramientas estáticas, establezca la versión activa de Minecraft:

`mc_version`

Gestiona la versión activa de Minecraft. Llámelo con action: "set" antes de otras herramientas estáticas, o con action: "list" para ver qué está inicializado.

{
  "action": "set",
  "version": "1.21.11"
}

{
  "action": "list"
}

Requisitos de las herramientas estáticas

Herramienta	Requiere `init`	Requiere `callgraph`
`mc_version`	-	-
`mc_search`	✓	-
`mc_get_class`	✓	-
`mc_get_method`	✓	-
`mc_list_classes`	✓	-
`mc_list_packages`	✓	-
`mc_find_hierarchy`	✓	-
`mc_find_refs`	✓	✓

`mc_search`

Busca en el código fuente descompilado clases, métodos o campos por patrón de nombre.

{
  "query": "Minecraft",
  "type": "class"
}

`mc_get_class`

Obtiene el código fuente descompilado completo de una clase.

{
  "className": "net.minecraft.client.Minecraft"
}

`mc_get_method`

Obtiene el código fuente de un método específico con contexto.

{
  "className": "net.minecraft.client.Minecraft",
  "methodName": "tick"
}

`mc_find_refs`

Encuentra quién llama a un método (llamadores) o a qué llama (llamados).

{
  "className": "net.minecraft.client.MouseHandler",
  "methodName": "setup",
  "direction": "callers"
}

Dirección	Descripción
`callers`	Encuentra métodos que llaman a este método
`callees`	Encuentra métodos a los que llama este método

Nota: requiere que se genere el grafo de llamadas (incluido en init de forma predeterminada).

`mc_list_classes`

Lista todas las clases bajo una ruta de paquete específica (incluye subpaquetes).

{
  "packagePath": "net.minecraft.client.gui.screens"
}

`mc_list_packages`

Lista todos los paquetes disponibles. Opcionalmente, filtre por espacio de nombres.

{
  "namespace": "minecraft"
}

Espacio de nombres	Descripción
`minecraft`	Clases del cliente de Minecraft
`fabric`	Clases de Fabric API (si están indexadas)

`mc_find_hierarchy`

Encuentra clases que extienden o implementan una clase o interfaz determinada.

{
  "className": "net.minecraft.world.entity.Entity",
  "direction": "subclasses"
}

Dirección	Descripción
`subclasses`	Clases que extienden esta clase
`implementors`	Clases que implementan esta interfaz

Herramientas de tiempo de ejecución

Estas herramientas requieren que Minecraft se esté ejecutando con el mod DebugBridge instalado.

`mc_connect`

Conéctese a una instancia de Minecraft en ejecución. Otras herramientas de tiempo de ejecución se conectan automáticamente si es necesario. Pase reset: true para desconectarse y borrar el estado antes de reconectarse (útil al cambiar de instancia). Si se omite port, escanea los puertos 9876-9886.

{
  "port": 9876,
  "reset": false
}

`mc_execute`

Ejecuta código Groovy en el juego en ejecución. El enlace persiste entre llamadas, y mc / player / level están preenlazados. (El tiempo de ejecución migró de Lua a Apache Groovy 5 a mediados de 2026: la descripción de la herramienta incluye una chuleta de Lua→Groovy).

return player.blockPosition().toShortString()

`mc_snapshot`

Obtiene una instantánea estructurada del estado actual del juego (jugador, mundo, hora, clima).

{}

`mc_screenshot`

Captura la ventana del juego como archivo JPEG y devuelve su ruta.

{
  "downscale": 2,
  "quality": 0.75
}

`mc_record_video`

Captura una ráfaga corta de fotogramas para depurar problemas de renderizado temporal (fallos de animación, errores de shaders, partículas, artefactos de subtick que una sola captura no puede resolver). Devuelve un JPEG de cuadrícula compuesta (predeterminado) o N JPEG de fotogramas separados.

{
  "frames": 60,
  "interval": 50,
  "output": "grid",
  "downscale": 2,
  "quality": 0.75
}

interval es "frame" (cada tick de renderizado, ~60 Hz) o milisegundos (número, >= 1). Se recomiendan intervalos numéricos (50–100 ms) a menos que necesite específicamente detalle de subtick; con cadencia "frame" el codificador puede quedarse atrás y el recuento de dropped de la respuesta le indica cuántos fotogramas se omitieron. Límite de 300 fotogramas por llamada. Los archivos se guardan en <gameDir>/debugbridge-recordings/<requestId>/.

`mc_screen_inspect`

Captura la pantalla que el jugador tiene abierta actualmente (UI de cofre, inventario, pantalla de avances, etc.) y devuelve su estructura.

{
  "includeIcons": false
}

Establezca includeIcons: true para renderizar cada objeto único en la pantalla como un PNG pequeño y adjuntar un mapa de iconos con clave por id de registro.

`mc_chat_history`

Obtiene los mensajes de chat más recientes del lado del cliente: lo que el usuario ha visto en el chat.

{
  "limit": 50,
  "includeJson": false
}

Establezca includeJson: true para incluir el JSON completo de Minecraft Component de cada mensaje (útil cuando el estilo de los mensajes de chat es importante).

`mc_nearby_entities`

Lista entidades (mobs, objetos, proyectiles, jugadores) dentro de un radio del jugador.

{
  "range": 64,
  "limit": 100,
  "includeIcons": false
}

Devuelve el id, tipo, posición y resumen de equipo principal de cada entidad. Pase el id a mc_entity_details, mc_set_entity_glow o mc_get_entity_item_texture para profundizar.

`mc_entity_details`

Obtiene los detalles completos de una entidad por id (el campo id devuelto por mc_nearby_entities o mc_looked_at_entity).

{
  "entityId": 12345
}

`mc_looked_at_entity`

Devuelve el id de la entidad a la que el jugador apunta actualmente (raycast), o null si no hay nada en la línea de visión.

{
  "range": 64
}

`mc_nearby_blocks`

Lista entidades de bloque cercanas (carteles, cofres, estandartes, beacons, tolvas, …). Los bloques normales del mundo no se incluyen; use mc_block_details para cualquier posición específica.

{
  "range": 16,
  "limit": 100
}

`mc_block_details`

Obtiene los detalles de la entidad de bloque en (x, y, z): líneas de cartel, contenido de cofre, patrones de estandarte, etc.

{
  "x": 100,
  "y": 64,
  "z": 200
}

`mc_set_entity_glow`

Delinea una entidad con el resplandor del color del equipo para que el usuario pueda localizarla. Pasa glow: false para eliminarlo.

{
  "entityId": 12345,
  "glow": true
}

`mc_set_block_glow`

Resalta un bloque en el mundo (contorno amarillo en 1.19, resplandor estándar en versiones más recientes). Pasa glow: false para eliminar solo esta posición.

{
  "x": 100,
  "y": 64,
  "z": 200,
  "glow": true
}

`mc_clear_block_glow`

Elimina todos los resaltados de bloques configurados mediante mc_set_block_glow en una sola llamada.

{}

`mc_get_item_texture`

Renderiza el objeto en el slot N del inventario del jugador como un PNG adjunto como contenido de imagen MCP.

{
  "slot": 0
}

Rango de slots	Significado
0–35	Inventario principal (0–8 son la barra de acceso rápido)
36–39	Armadura (botas, grebas, peto, casco)
40	Mano secundaria

`mc_get_item_texture_by_id`

Renderiza la textura predeterminada para un ID de registro (p. ej., minecraft:diamond) sin necesidad de que el objeto esté en ningún inventario.

{
  "itemId": "minecraft:diamond"
}

`mc_get_entity_item_texture`

Renderiza un objeto llevado por otra entidad. slot es "mainhand", "offhand" o uno de los nombres de slots de armadura.

{
  "entityId": 12345,
  "slot": "mainhand"
}

Control de sesión y bucle de desarrollo

Estas cinco herramientas son los primitivos del lado del puente del bucle reconstruir → relanzar → reincorporar. Los endpoints subyacentes (disconnect, joinServer, quit) están deshabilitados por defecto: establece "session_control_enabled": true en <minecraft>/config/debugbridge.json y reinicia el cliente (la bandera se lee al inicio). mc_connect informa si la instancia conectada lo tiene habilitado, y las herramientas devuelven instrucciones exactas cuando está desactivado.

Las mitades específicas de la máquina del bucle — compilar el mod, copiar el jar en <gameDir>/mods/ y lanzar el cliente — son deliberadamente no herramientas del servidor: un agente de codificación con acceso a shell las descubre y ejecuta por sí mismo, guiado por el recurso mcdev://guides/dev-loop (también disponible como una habilidad copiable de Claude Code en skills/minecraft-dev-loop/). La versión corta: el agente deriva el destino de implementación, el nombre de la instancia y el lanzador del gameDir que mc_connect informa, persiste el comando de lanzamiento que compone en el CLAUDE.md del proyecto y deja la autenticación completamente al lanzador.

Precaución: mc_quit_client apaga todo el cliente de Minecraft, y mc_join_server / mc_leave_server cambian el mundo en el que está el usuario — derriban la sesión de juego actual. Para ejecuciones de prueba automatizadas repetidas, prefiere un servidor local desechable sobre un servidor comunitario en vivo (mundo no determinista, otros jugadores, reglas del servidor).

`mc_join_server`

Únete a un servidor multijugador (desconectándote del mundo actual primero si es necesario). El paquete de recursos del servidor se pre-acepta por defecto para que la unión no se detenga en el mensaje de confirmación. El acuse del puente significa que el intento de conexión ha comenzado: los puentes ≥ 2.0.0 lo difieren hasta que el cliente se ha asentado (sin superposición de inicio/recarga), por lo que una unión disparada justo después de un relanzamiento puede tardar unos segundos extra en acusar; los puentes más antiguos acusan tan pronto como la solicitud está en cola. Por defecto, la herramienta luego sondea cada segundo hasta que una instantánea del juego muestra un jugador (unido) o aparece un DisconnectedScreen (fallido — su título se devuelve como la razón).

{
  "address": "localhost:25565",
  "acceptResourcePacks": true,
  "wait": true,
  "timeoutSeconds": 60
}

`mc_leave_server`

Sal del mundo/servidor actual a la pantalla de título (cuando no estás en un mundo, aún así restablece la pantalla de menú abierta a la pantalla de título). Disparar y acusar — el acuse significa que la desconexión se puso en cola en el hilo del juego.

{}

`mc_wait_until_in_world`

Sondea hasta que el jugador esté en un mundo, aparezca un DisconnectedScreen o expire el tiempo de espera. Solo lectura (no requiere control de sesión); útil después de mc_join_server con wait: false o después de un relanzamiento.

{
  "timeoutSeconds": 60
}

`mc_quit_client`

Apaga correctamente el cliente de Minecraft (la caída del WebSocket justo después del acuse es el modo de éxito normal). Por defecto resuelve el PID del cliente desde el puerto del puente antes de salir, luego sondea hasta que el puerto deje de escuchar y ese proceso salga — en caso de éxito es seguro relanzar inmediatamente, incluso a través de lanzadores que rastrean la instancia (Prism ignora silenciosamente --launch mientras aún ve el proceso antiguo). Cuando el PID no se puede resolver (sin lsof, permisos), cae a solo-cierre-de-puerto y el resultado lo dice — la JVM puede sobrevivir al puerto por unos segundos, así que en ese caso confirma tú mismo que el proceso antiguo salió antes de relanzar.

{
  "waitForExit": true,
  "timeoutSeconds": 30
}

`mc_wait_for_bridge`

Bloquea hasta que el puente de un cliente recién (re)lanzado responda, luego conéctate a él. Escanea los puertos 9876-9886 una vez por segundo, aceptando solo la instancia que coincida con el directorio del juego / versión de la conexión anterior — así una segunda instancia en ejecución no se confunde con el relanzamiento. Pasa expectedVersion solo cuando cambies deliberadamente de instancia. Solo lectura.

{
  "expectedVersion": "1.21.11",
  "timeoutSeconds": 120
}

`mc_run_command` (herramienta de desarrollo opcional)

Ejecuta un comando de barra de Minecraft.

{
  "command": "/give @s minecraft:diamond 64"
}

Deshabilitado por defecto. Tanto este servidor (MCDEV_RUN_COMMAND=1) como el mod DebugBridge (runCommandEnabled en BridgeConfig) deben optar por participar. Consulta Opt-in / herramientas de desarrollo a continuación.

`mc_script_logs` (herramienta de desarrollo opcional)

Revisa el registro respaldado en archivos de ejecuciones pasadas de mc_execute (marca de tiempo, código, resultado, error, duración), resume patrones de error comunes o imprime las rutas de los registros.

{
  "mode": "errors",
  "limit": 20
}

Modo	Devuelve
`"errors"`	Las llamadas `mc_execute` fallidas más recientes
`"stats"`	Patrones de error agregados (qué mensajes se repiten)
`"paths"`	Dónde viven los archivos de registro en el disco

Deshabilitado por defecto. Habilitado por MCDEV_SCRIPT_LOGS=1. El MCPB de Claude Desktop expone esto como un interruptor visible para el usuario ("Registrar ejecuciones de scripts") — consulta Opt-in / herramientas de desarrollo.

Opt-in / herramientas de desarrollo

Dos herramientas de tiempo de ejecución están restringidas detrás de variables de entorno para que el servidor predeterminado solo exponga los envoltorios de solo lectura y "seguros". El mod del puente tiene sus propias banderas coincidentes, por lo que activar solo la variable de entorno del lado del servidor no hace nada si el mod tampoco ha optado por participar.

Herramienta	Variable de entorno	Bandera del lado del puente	Superficie en Claude Desktop
`mc_run_command`	`MCDEV_RUN_COMMAND=1` (o `true`)	`runCommandEnabled`	No expuesto a través de user_config del MCPB — establece la variable de entorno explícitamente al lanzar el servidor.
`mc_script_logs`	`MCDEV_SCRIPT_LOGS=1` (o `true`)	(solo lado del servidor)	Interruptor "Registrar ejecuciones de scripts" en la configuración de la extensión MCPB (también habilita el registro en archivos de cada `mc_execute`).

Cuando la variable de entorno no está establecida (o está establecida en 0/false), la herramienta simplemente no se registra y no aparecerá en la lista de herramientas del cliente MCP.

Indexador Java basado en AST (vista previa)

Establece MCDEV_AST_PARSER=1 antes de init o rebuild para usar el nuevo indexador respaldado por java-parser. En comparación con el analizador regex predeterminado:

Maneja correctamente anotaciones multilínea, genéricos anidados, registros, tipos sellados, coincidencia de patrones y campos inicializados con lambda (el analizador regex cuenta mal silenciosamente en cada uno de estos).
Captura constantes de interfaz y métodos de interfaz default/static que el analizador regex pasa por alto.
No pliega miembros de clases anidadas en las listas del tipo externo.

En una comparación directa en el código fuente de Minecraft 1.21.11 (muestra de 500 archivos), el analizador AST encontró ~2× más campos y ~33% menos métodos (correctamente atribuidos) que el analizador regex. Es ~4.5× más lento por archivo, por lo que un re-indexado completo se ejecuta en aproximadamente 75 segundos en lugar de 17 — aceptable dentro de un init que ya toma 2–5 minutos para descarga + descompilación. Las clases de comandos generadas muy grandes se aíslan en procesos de trabajo limitados; si java-parser aún agota un trabajador en un archivo, el indexador cae al analizador regex para ese archivo en lugar de fallar todo el re-build.

MCDEV_AST_PARSER=1 npx mcdev-mcp init -v 1.21.11
# or, to re-index an already-decompiled version:
MCDEV_AST_PARSER=1 npx mcdev-mcp rebuild -v 1.21.11 --with-callgraph

El servidor MCP sella manifest.indexerVersion para poder saber qué analizador produjo el índice existente. Cuando cambias la bandera pero aún no has reconstruido, el servidor imprime una pista única por versión en la siguiente llamada de herramienta:

[source-store/manifest:1.21.11] Index was built with the 'regex' parser, but the server is now running the 'ast' parser.
  This is fine — existing indices still work — but the new parser would produce a better index.
  Run `mcdev-mcp rebuild -v 1.21.11` (or `init -v 1.21.11` for a full re-fetch) to refresh.
  Set MCDEV_SUPPRESS_INDEXER_HINT=1 to silence this message.

Requisitos

Dependencia	Versión	Propósito
Node.js	18+	Tiempo de ejecución
Java	8+	Descompilación (Vineflower) y grafo de llamadas
~2GB	disco	Fuentes descompiladas + caché

Nota: Se recomienda Java 17+ para el comando callgraph debido a la compatibilidad con Gradle.

Comandos CLI

Invoca mediante npx mcdev-mcp <command> (o node dist/cli.js <command> desde un checkout de fuente).

Comando	Descripción
`serve`	Inicia el servidor MCP sobre stdio (lanzado por clientes MCP — no ejecutado por humanos)
`init -v <version>`	Descarga, descompila, indexa fuentes de Minecraft y genera el grafo de llamadas
`init -v <version> --skip-callgraph`	Igual que el anterior pero omite la generación del grafo de llamadas
`callgraph -v <version>`	Genera el grafo de llamadas para `mc_find_refs`
`status`	Muestra todas las versiones inicializadas y en qué etapa está cada una
`rebuild -v <version>`	Reconstruye el índice de símbolos desde fuentes ya en caché
`rebuild -v <version> --with-callgraph`	También regenera el grafo de llamadas en la misma ejecución
`clean -v <version> --all`	Elimina datos en caché para una versión
`clean --all`	Elimina todos los datos en caché entre versiones

Re-indexado

Para re-indexar una versión:

# Clean existing data for a version
npx mcdev-mcp clean -v 1.21.11 --all

# Re-initialize
npx mcdev-mcp init -v 1.21.11

Arquitectura

mcdev-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── cli.ts                # CLI commands
│   ├── tools/
│   │   ├── static/           # Decompiled source tools
│   │   └── runtime/          # DebugBridge runtime tools
│   ├── decompiler/           # Vineflower integration
│   ├── indexer/              # Symbol index builder
│   ├── callgraph/            # Call graph generation & queries
│   └── storage/              # Source & index storage
└── dist/                     # Compiled output

Cómo funciona

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client (AI Agent)                    │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┴────────────────────┐
         ▼                                          ▼
┌─────────────────────────────┐    ┌──────────────────────────────────┐
│   Static Tools (8)          │    │   Runtime Tools (18 + 2 opt-in)  │
│  ┌────────────────────────┐ │    │  ┌────────────────────────────┐  │
│  │ mc_version             │ │    │  │ mc_connect / mc_execute    │  │
│  │ mc_search              │ │    │  │ mc_snapshot / mc_screenshot│  │
│  │ mc_get_class / method  │ │    │  │ mc_screen_inspect          │  │
│  │ mc_list_classes / pkgs │ │    │  │ mc_chat_history            │  │
│  │ mc_find_hierarchy      │ │    │  │ mc_nearby_entities + det.  │  │
│  │ mc_find_refs           │ │    │  │ mc_nearby_blocks   + det.  │  │
│  └───────────┬────────────┘ │    │  │ mc_looked_at_entity        │  │
│              │              │    │  │ mc_set_*_glow / mc_clear_* │  │
│       ┌──────┴──────┐       │    │  │ mc_get_item_texture (×3)   │  │
│       ▼             ▼       │    │  │ ─── opt-in (env-gated) ─── │  │
│  ┌─────────┐  ┌──────────┐  │    │  │ mc_run_command             │  │
│  │  Index  │  │Callgraph │  │    │  │ mc_script_logs             │  │
│  │ (JSON)  │  │ (SQLite) │  │    │  └─────────────┬──────────────┘  │
│  └────┬────┘  └────┬─────┘  │    │                │                 │
└───────┼────────────┼────────┘    │         ┌──────┴──────┐          │
        ▼            ▼              │         ▼             │          │
┌────────────────────────────┐      │   ┌──────────────┐    │          │
│ Decompiled Src (local)     │      │   │  WebSocket   │    │          │
│ (Vineflower)               │      │   │ to Minecraft │    │          │
└────────────────────────────┘      │   └──────┬───────┘    │          │
                                    └──────────┼────────────┘
                                               ▼
                                    ┌────────────────────────────┐
                                    │ DebugBridge Mod (in game)  │
                                    │ github.com/use-ai-for-mc/  │
                                    │ debugbridge                │
                                    └────────────────────────────┘

Consulta docs/ARCHITECTURE.md para documentación de diseño detallada.

Ubicación de almacenamiento

mcdev-mcp almacena todos los datos en caché en el directorio de caché estándar del sistema operativo, cortesía de env-paths. Todo bajo este directorio es regenerable — seguro de eliminar en cualquier momento — y init reconstruirá lo que necesite en la próxima ejecución.

Plataforma	Ruta
macOS	`~/Library/Caches/mcdev-mcp`
Linux	`~/.cache/mcdev-mcp` (compatible con XDG, respeta `$XDG_CACHE_HOME`)
Windows	`%LOCALAPPDATA%\mcdev-mcp\Cache`

Uso de disco: aproximadamente 2 GB por versión de Minecraft (JAR ~60 MB, fuentes descompiladas ~1.8 GB, base de datos del grafo de llamadas ~200 MB, índice de símbolos ~50 MB). Ejecuta npx mcdev-mcp status para ver qué versiones están en caché, y npx mcdev-mcp clean --all (o clean -v <version> --all) para recuperar espacio.

Diseño

<cache-dir>/
├── tools/
│   └── vineflower.jar         # Decompiler, downloaded once
├── java-callgraph2/           # Call graph tool, cloned once
├── cache/
│   └── {version}/
│       ├── jars/               # Downloaded Minecraft client JARs
│       └── client/             # Decompiled Minecraft sources
├── index/
│   └── {version}/
│       ├── manifest.json       # Index metadata
│       └── minecraft/          # Per-package symbol indices
└── tmp/                        # Temporary files (cleaned by --all)

¿Actualizando desde una instalación anterior a 1.0? Las versiones anteriores almacenaban todo bajo ~/.mcdev-mcp/. Si tienes datos allí y quieres conservarlos, muévelos manualmente a la nueva ubicación (p. ej., en macOS: mv ~/.mcdev-mcp ~/Library/Caches/mcdev-mcp). De lo contrario, solo ejecuta init de nuevo — el paso de descarga es idempotente.

Desarrollo

npm run build    # Compile TypeScript
npm test         # Run tests
npm run lint     # Lint code
npm run mcpb     # Build a Claude Desktop MCPB bundle for the current platform

Publicación de versiones

Las versiones se impulsan por etiquetas. Empujar una etiqueta v* activa GitHub Actions para:

Ejecutar la matriz de pruebas completa y las verificaciones de TypeScript
Construir un único paquete MCPB universal en ubuntu-latest
Publicar el paquete en npm
Crear una versión de GitHub con el .mcpb adjunto

Para cortar una versión:

# 1. Bump the version. npm version only touches package.json; mirror the same
#    value into manifest.json by hand — the verify-version CI job hard-fails
#    if the two disagree with the tag.
npm version patch          # or: minor, major, 1.2.3, etc.
$EDITOR manifest.json      # set "version" to match package.json

# 2. Commit the manifest bump (npm version already committed package.json)
git commit -am "Sync manifest.json version"
git tag -f "v$(node -p 'require(\"./package.json\").version')"

# 3. Push the commit and the tag
git push --follow-tags

Eso es todo — el flujo de trabajo en .github/workflows/ci.yml maneja el resto. No se necesita secreto NPM_TOKEN; el flujo de trabajo publica en npm a través de Trusted Publishing (OIDC). Se debe configurar un editor de confianza en el lado de npm, bajo la configuración de acceso de publicación del paquete: propietario use-ai-for-mc, repositorio mcdev-mcp, flujo de trabajo ci.yml. Las versiones también envían atestaciones de procedencia de npm a través de npm publish --provenance.

La compilación MCPB también se puede ejecutar localmente:

npm run mcpb
# → dist-mcpb/mcdev-mcp-<version>.mcpb

El paquete es universal — JavaScript puro más sql.js (SQLite compilado a WebAssembly), sin binarios nativos. El mismo .mcpb funciona en macOS (arm64 y x86_64), Linux (x64/arm64) y Windows. Se requiere Node ≥ 20 en tiempo de ejecución (desde package.json engines).

Instalación del MCPB en Claude Desktop

Descarga el paquete desde la página de Releases y haz doble clic en el archivo .mcpb. Claude Desktop validará el manifiesto y ofrecerá instalarlo. Después de la instalación, ejecuta mcdev-mcp init -v <version> en una terminal una vez para poblar la caché (la extensión no puede activar init por sí misma — es deliberadamente solo-terminal, consulta Inicio rápido).

Limitaciones

Análisis estático: mc_find_refs no puede rastrear llamadas a través de reflexión, callbacks de JNI, o referencias a lambda/métodos creadas dinámicamente
Solo cliente: Las clases del lado del servidor no se incluyen en el análisis estático
Herramientas de ejecución: Requieren Minecraft ejecutándose con el mod DebugBridge instalado

Aviso legal

Esta herramienta descompila el código fuente de Minecraft con fines de referencia para desarrollo. Por favor, respeta la propiedad intelectual de Mojang:

PUEDES:

Descompilar y estudiar el código para comprenderlo y aprender
Usar el conocimiento para desarrollar mods que no contengan código sustancial de Mojang
Referenciar nombres de clases/métodos para el desarrollo de mods

NO PUEDES:

Distribuir código fuente descompilado
Distribuir versiones modificadas de Minecraft
Usar código descompilado comercialmente sin permiso

Según el EULA de Minecraft: "No puedes distribuir ninguna Versión Modificada de nuestro juego o software" y "Los mods están bien para distribuir; las versiones hackeadas o las Versiones Modificadas del cliente o servidor del juego no están bien para distribuir."

Esta herramienta es solo para referencia — no copies código descompilado directamente en tus proyectos.

Componentes de terceros

Este proyecto incluye o utiliza software de terceros bajo las siguientes licencias:

DecompilerMC (MIT) — Lógica del descompilador adaptada y traducida de Python a TypeScript en src/decompiler/
Vineflower (Apache-2.0) — Descompilador de Java utilizado para la generación de código fuente
java-callgraph2 — Clonado en tiempo de ejecución para la generación de grafos de llamadas estáticos

Dependencias adicionales en tiempo de ejecución (descargadas/utilizadas):

Mojang — Mapeos oficiales de ProGuard y JAR del cliente de Minecraft

Consulta LICENCIA para el texto completo de la licencia y las atribuciones de terceros.

mcdev-mcp

Documentación

mcdev-mcp

Características

Análisis estático (funciona sin conexión)

Interacción en tiempo de ejecución (requiere el mod DebugBridge)

Recursos MCP

Inicio rápido

1. Inicialice en su terminal

2. Añada a su cliente MCP

Codex Desktop / Codex CLI

Otros clientes MCP

3. (Opcional) Instale DebugBridge para herramientas de juego en vivo

Versiones compatibles

(Opcional) Omitir grafo de llamadas

Verificar la instalación

Instalar desde el código fuente (desarrollo)

Herramientas MCP

Gestión de versiones (herramientas estáticas)

mc_version

Requisitos de las herramientas estáticas

mc_search

mc_get_class

mc_get_method

mc_find_refs

mc_list_classes

mc_list_packages

mc_find_hierarchy

Herramientas de tiempo de ejecución

mc_connect

mc_execute

mc_snapshot

mc_screenshot

mc_record_video

mc_screen_inspect

mc_chat_history

mc_nearby_entities

mc_entity_details

mc_looked_at_entity

mc_nearby_blocks

mc_block_details

mc_set_entity_glow

mc_set_block_glow

mc_clear_block_glow

mc_get_item_texture

mc_get_item_texture_by_id

mc_get_entity_item_texture

Control de sesión y bucle de desarrollo

mc_join_server

mc_leave_server

mc_wait_until_in_world

mc_quit_client

mc_wait_for_bridge

mc_run_command (herramienta de desarrollo opcional)

mc_script_logs (herramienta de desarrollo opcional)

Opt-in / herramientas de desarrollo

Indexador Java basado en AST (vista previa)

Requisitos

Comandos CLI

Re-indexado

Arquitectura

Cómo funciona

Ubicación de almacenamiento

Diseño

Desarrollo

Publicación de versiones

Instalación del MCPB en Claude Desktop

Limitaciones

Aviso legal

Componentes de terceros

Licencia

`mc_version`

`mc_search`

`mc_get_class`

`mc_get_method`

`mc_find_refs`

`mc_list_classes`

`mc_list_packages`

`mc_find_hierarchy`

`mc_connect`

`mc_execute`

`mc_snapshot`

`mc_screenshot`

`mc_record_video`

`mc_screen_inspect`

`mc_chat_history`

`mc_nearby_entities`

`mc_entity_details`

`mc_looked_at_entity`

`mc_nearby_blocks`

`mc_block_details`

`mc_set_entity_glow`

`mc_set_block_glow`

`mc_clear_block_glow`

`mc_get_item_texture`

`mc_get_item_texture_by_id`

`mc_get_entity_item_texture`

`mc_join_server`

`mc_leave_server`

`mc_wait_until_in_world`

`mc_quit_client`

`mc_wait_for_bridge`

`mc_run_command` (herramienta de desarrollo opcional)

`mc_script_logs` (herramienta de desarrollo opcional)