mcdev-mcp

Um servidor MCP que ajuda agentes de codificação a trabalhar com desenvolvimento de mods para Minecraft

Documentação

mcdev-mcp

Um servidor MCP (Model Context Protocol) que capacita agentes de IA de codificação a trabalhar efetivamente com o desenvolvimento de mods para Minecraft. Fornece tanto análise estática do código-fonte descompilado quanto interação em tempo de execução com uma instância do Minecraft em execução.

Recursos

Análise Estática (funciona offline)

Acesso ao Código-Fonte Descompilado — Baixa e descompila automaticamente o cliente Minecraft usando Vineflower
Suporte a Snapshots de Desenvolvimento — Funciona com snapshots de desenvolvimento (ex.: 26.1-snapshot-10) que não possuem mapeamentos ProGuard
Busca de Símbolos — Busca por classes, métodos e campos por nome (mc_search)
Recuperação de Código-Fonte — Obtém o código-fonte completo da classe ou métodos individuais com contexto
Exploração de Pacotes — Lista todas as classes sob um caminho de pacote ou descobre pacotes disponíveis
Hierarquia de Classes — Encontra subclasses e implementadores de interfaces
Análise de Grafo de Chamadas — Encontra chamadores e chamados de métodos em toda a base de código

Interação em Tempo de Execução (requer o mod DebugBridge)

Execução Groovy ao Vivo — Executa scripts Groovy dentro da JVM do Minecraft em execução (mc_execute); migrado de Lua em meados de 2026
Snapshots do Estado do Jogo — Posição do jogador, saúde, dimensão, hora, clima (mc_snapshot)
Capturas de Tela, Gravações e Inspeção de Tela — JPEG da janela do jogo, folha de contato com múltiplos quadros para depuração temporal e estrutura da GUI atual (mc_screenshot, mc_record_video, mc_screen_inspect)
Introspecção do Mundo — Entidades próximas e block-entities, além de detalhes por id (mc_nearby_entities, mc_entity_details, mc_nearby_blocks, mc_block_details, mc_looked_at_entity)
Marcadores Visuais — Contorna entidades ou blocos para o usuário identificar (mc_set_entity_glow, mc_set_block_glow, mc_clear_block_glow)
Renderização de Texturas de Itens — Renderiza um slot de inventário, um id de item ou um slot em outra entidade como PNG (mc_get_item_texture, mc_get_item_texture_by_id, mc_get_entity_item_texture)
Histórico de Chat — Mensagens de chat recentes do lado do cliente (mc_chat_history)
Controle de Sessão e Loop de Desenvolvimento — Entrar/sair de servidores, sair do cliente e reconectar após um relançamento (mc_join_server, mc_leave_server, mc_quit_client, mc_wait_for_bridge, mc_wait_until_in_world; controlado por session_control_enabled na configuração do DebugBridge). A orquestração de build/execução é responsabilidade do agente de codificação, guiada pelo recurso mcdev://guides/dev-loop e pela habilidade minecraft-dev-loop.
Comandos com Barra — Executa comandos no jogo (mc_run_command, ferramenta de desenvolvimento opcional)
Logs de Execução de Scripts — Revisa execuções anteriores de mc_execute e padrões de erro (mc_script_logs, opcional via configuração de usuário do Claude Desktop)

Recursos MCP

mcdev://guides/python-scripting — Referência do protocolo de comunicação para agentes de IA que desejam acionar o DebugBridge diretamente via Python (ignorando as ferramentas MCP): enquadramento WebSocket, um cliente asyncio mínimo e a superfície Groovy que você envia através dele. Exposto via resources/list + resources/read padrão do MCP, com um ponteiro no instructions do servidor para que os agentes saibam onde procurar.

Início Rápido

Nota de segurança — init é intencionalmente apenas via terminal. O servidor MCP expõe apenas ferramentas de leitura/consulta. O download e a descompilação dos fontes do Minecraft devem ser acionados por você no terminal; um agente de IA conectado ao servidor não tem superfície de ferramentas para acionar init, rebuild, clean ou callgraph.

1. Inicialize no seu terminal

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

Este comando:

Baixa o JAR do cliente Minecraft
Descompila usando Vineflower (Java puro, 8 threads)
Constrói o índice de símbolos (classes, métodos, campos, herança)
Gera o grafo de chamadas para mc_find_refs

Os dados são armazenados no diretório de cache do seu sistema operacional (veja Local de armazenamento abaixo), portanto persistem entre invocações de npx. Espere aproximadamente ~2 GB por versão do Minecraft — principalmente fontes descompiladas de .java e um banco de dados SQLite de grafo de chamadas. Tudo isso é regenerável, então seu sistema operacional pode liberar sob pressão de armazenamento e init reconstruirá o que precisar.

2. Adicione ao seu cliente MCP

Codex Desktop / Codex CLI

O Codex pode iniciar servidores MCP stdio locais diretamente. Instale o pacote publicado com:

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

Se você estiver desenvolvendo a partir de um checkout local, compile primeiro e aponte o Codex para o 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 se o Codex consegue vê-lo:

codex mcp list
codex mcp get mcdev-mcp

Reinicie o Codex Desktop, ou inicie uma nova sessão do Codex, após adicionar o servidor. O Codex iniciará o servidor MCP automaticamente quando uma sessão precisar dele; você não executa serve manualmente.

Outros clientes MCP

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

O subcomando serve inicia o servidor MCP via stdio. Seu cliente MCP (Claude Desktop, Cursor, etc.) o inicia automaticamente — você nunca executa serve diretamente.

3. (Opcional) Instale o DebugBridge para ferramentas de jogo ao vivo

As ferramentas de análise estática (mc_search, mc_get_class, mc_find_refs, …) funcionam assim que init termina. As ferramentas de tempo de execução (mc_execute, mc_snapshot, capturas de tela, introspecção do mundo, texturas de itens, marcadores brilhantes, etc.) adicionalmente requerem o mod DebugBridge instalado na instância do Minecraft que você deseja controlar. Sem o DebugBridge, essas ferramentas apenas reportarão um erro de conexão — a metade estática continua funcionando normalmente.

Versões Suportadas

Tipo de Versão	Exemplo	Notas
Novo esquema (`26.x` e posteriores)	`26.1`, `26.1-snapshot-10`	Recomendado. Já vem pré-desofuscado; sem etapa de mapeamento ProGuard.
Versões `1.14` – `1.21.x`	`1.21.11`, `1.20.4`, `1.19.4`	Suportado. Os mapeamentos ProGuard oficiais da Mojang são necessários (baixados automaticamente).
Versões mais antigas (`< 1.14`)	`1.13`, `1.12.2`	Não suportado — nenhum mapeamento oficial publicado.

O validador está em src/cli.ts (isValidVersion). Para versões 1.x.x, requer 1.14 ou posterior; o novo esquema 26.x+ é aceito incondicionalmente.

(Opcional) Pular Grafo de Chamadas

# 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 Instalação

npx mcdev-mcp status

Nota: mc_version (com action: "set") deve ser chamado antes de usar qualquer outra ferramenta MCP estática. Se a versão não estiver inicializada, a IA será instruída a pedir que você execute init.

Instalar a partir do código-fonte (desenvolvimento)

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

Atualizando de uma versão mais antiga? Se você tiver uma instalação anterior usando DecompilerMC, execute npx mcdev-mcp clean --all primeiro para remover dados antigos em cache.

Ferramentas MCP

Gerenciamento de Versão (Ferramentas Estáticas)

Antes de usar ferramentas estáticas, defina a versão ativa do Minecraft:

`mc_version`

Gerencia a versão ativa do Minecraft. Chame com action: "set" antes de outras ferramentas estáticas, ou action: "list" para ver o que está inicializado.

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

{
  "action": "list"
}

Requisitos das Ferramentas Estáticas

Ferramenta	Requer `init`	Requer `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 no código-fonte descompilado por classes, métodos ou campos por padrão de nome.

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

`mc_get_class`

Obtém o código-fonte descompilado completo de uma classe.

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

`mc_get_method`

Obtém o código-fonte de um método específico com contexto.

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

`mc_find_refs`

Encontra quem chama um método (chamadores) ou o que ele chama (chamados).

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

Direção	Descrição
`callers`	Encontra métodos que chamam este método
`callees`	Encontra métodos que este método chama

Nota: Requer que o grafo de chamadas seja gerado (incluído em init por padrão).

`mc_list_classes`

Lista todas as classes sob um caminho de pacote específico (inclui subpacotes).

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

`mc_list_packages`

Lista todos os pacotes disponíveis. Opcionalmente, filtre por namespace.

{
  "namespace": "minecraft"
}

Namespace	Descrição
`minecraft`	Classes do cliente Minecraft
`fabric`	Classes da API Fabric (se indexadas)

`mc_find_hierarchy`

Encontra classes que estendem ou implementam uma determinada classe ou interface.

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

Direção	Descrição
`subclasses`	Classes que estendem esta classe
`implementors`	Classes que implementam esta interface

Ferramentas de Tempo de Execução

Estas ferramentas exigem que o Minecraft esteja em execução com o mod DebugBridge instalado.

`mc_connect`

Conecta a uma instância do Minecraft em execução. Outras ferramentas de tempo de execução se conectam automaticamente se necessário. Passe reset: true para desconectar e limpar o estado antes de reconectar (útil ao alternar entre instâncias). Se port for omitido, verifica as portas 9876-9886.

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

`mc_execute`

Executa código Groovy no jogo em execução. O binding persiste entre chamadas, e mc / player / level são pré-vinculados. (O tempo de execução migrou de Lua para Apache Groovy 5 em meados de 2026 — a descrição da ferramenta traz uma folha de referência Lua→Groovy.)

return player.blockPosition().toShortString()

`mc_snapshot`

Obtém um snapshot estruturado do estado atual do jogo (jogador, mundo, hora, clima).

{}

`mc_screenshot`

Captura a janela do jogo como um arquivo JPEG e retorna seu caminho.

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

`mc_record_video`

Captura uma sequência curta de quadros para depurar problemas de renderização temporal (falhas de animação, bugs de shader, partículas, artefatos de sub-tick que uma única captura não resolve). Retorna ou uma imagem JPEG composta em grade (padrão) ou N arquivos JPEG separados.

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

interval é ou "frame" (a cada render tick, ~60 Hz) ou milissegundos (número, >= 1). Intervalos numéricos (50–100 ms) são recomendados a menos que você precise especificamente de detalhes de sub-tick; na cadência de "frame" o codificador pode ficar para trás e a contagem de dropped na resposta informa quantos quadros foram pulados. Limitado a 300 quadros por chamada. Os arquivos ficam em <gameDir>/debugbridge-recordings/<requestId>/.

`mc_screen_inspect`

Captura a tela que o jogador tem aberta no momento (UI de baú, inventário, tela de avanços, etc.) e retorna sua estrutura.

{
  "includeIcons": false
}

Defina includeIcons: true para renderizar cada item único na tela como um pequeno PNG e anexar um mapa de ícones indexado por id de registro.

`mc_chat_history`

Obtém as mensagens de chat mais recentes do lado do cliente — o que o usuário viu no chat.

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

Defina includeJson: true para incluir o JSON completo de Component do Minecraft de cada mensagem (útil quando o estilo da mensagem de chat importa).

`mc_nearby_entities`

Lista entidades (mobs, itens, projéteis, jogadores) dentro de um raio do jogador.

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

Retorna o id, tipo, posição e resumo do equipamento principal de cada entidade. Passe o id para mc_entity_details, mc_set_entity_glow ou mc_get_entity_item_texture para detalhar.

`mc_entity_details`

Obtém detalhes completos de uma entidade por id (o campo id retornado por mc_nearby_entities ou mc_looked_at_entity).

{
  "entityId": 12345
}

`mc_looked_at_entity`

Retorna o id da entidade que o jogador está mirando no momento (raycast), ou null se nada estiver na linha de visão.

{
  "range": 64
}

`mc_nearby_blocks`

Lista block-entities próximos (placas, baús, estandartes, beacons, funis, …). Blocos comuns do mundo não são incluídos — use mc_block_details para qualquer posição específica.

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

`mc_block_details`

Obtém detalhes do block-entity em (x, y, z): linhas de placas, conteúdo de baús, padrões de estandartes, etc.

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

`mc_set_entity_glow`

Delineie uma entidade com o brilho da cor do time para que o usuário possa identificá-la. Passe glow: false para remover.

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

`mc_set_block_glow`

Destaque um bloco no mundo (contorno amarelo na 1.19, brilho vanilla em versões mais novas). Passe glow: false para remover apenas esta posição.

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

`mc_clear_block_glow`

Limpe todos os destaques de bloco definidos via mc_set_block_glow em uma única chamada.

{}

`mc_get_item_texture`

Renderize o item no slot N do inventário do jogador como um PNG anexado como conteúdo de imagem MCP.

{
  "slot": 0
}

Faixa de slots	Significado
0–35	Inventário principal (0–8 são a barra de atalho)
36–39	Armadura (botas, calças, peitoral, capacete)
40	Mão secundária

`mc_get_item_texture_by_id`

Renderize a textura padrão para um ID de registro (ex.: minecraft:diamond) sem precisar que o item esteja em qualquer inventário.

{
  "itemId": "minecraft:diamond"
}

`mc_get_entity_item_texture`

Renderize um item carregado por outra entidade. slot é "mainhand", "offhand" ou um dos nomes de slot de armadura.

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

Controle de sessão e ciclo de desenvolvimento

Estas cinco ferramentas são os primitivos do lado da ponte para o ciclo reconstruir → relançar → reentrar. Os endpoints subjacentes (disconnect, joinServer, quit) estão desabilitados por padrão: defina "session_control_enabled": true em <minecraft>/config/debugbridge.json e reinicie o cliente (a flag é lida na inicialização). mc_connect informa se a instância conectada o tem habilitado, e as ferramentas retornam instruções exatas quando está desligado.

As metades específicas da máquina do ciclo — compilar o mod, copiar o jar para <gameDir>/mods/ e iniciar o cliente — são deliberadamente não ferramentas do servidor: um agente de codificação com acesso ao shell as descobre e executa por conta própria, guiado pelo recurso mcdev://guides/dev-loop (também disponível como uma habilidade copiável do Claude Code em skills/minecraft-dev-loop/). A versão resumida: o agente deriva o alvo de implantação, o nome da instância e o launcher do gameDir que mc_connect reporta, persiste o comando de inicialização que compõe no CLAUDE.md do projeto e deixa a autenticação inteiramente para o launcher.

Cuidado: mc_quit_client desliga todo o cliente Minecraft, e mc_join_server / mc_leave_server mudam em qual mundo o usuário está — eles encerram a sessão de jogo atual. Para execuções de teste automatizadas repetidas, prefira um servidor local descartável em vez de um servidor comunitário ao vivo (mundo não determinístico, outros jogadores, regras do servidor).

`mc_join_server`

Entre em um servidor multiplayer (desconectando do mundo atual primeiro, se necessário). O pacote de recursos do servidor é pré-aceito por padrão para que a entrada não trave no prompt de confirmação. O ack da ponte significa que a tentativa de conexão começou: pontes ≥ 2.0.0 adiam até o cliente se estabilizar (sem sobreposição de inicialização/recarga), então uma entrada disparada logo após um relançamento pode levar alguns segundos extras para o ack; pontes mais antigas confirmam assim que a solicitação é enfileirada. Por padrão, a ferramenta então consulta a cada segundo até que um snapshot do jogo mostre um jogador (entrou) ou um DisconnectedScreen apareça (falhou — seu título é retornado como o motivo).

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

`mc_leave_server`

Saia do mundo/servidor atual para a tela de título (quando não está em um mundo, ainda redefine a tela de menu aberta para a tela de título). Dispare e confirme — o ack significa que a desconexão foi enfileirada na thread do jogo.

{}

`mc_wait_until_in_world`

Consulte até que o jogador esteja em um mundo, um DisconnectedScreen apareça ou o tempo limite expire. Somente leitura (não requer controle de sessão); útil após mc_join_server com wait: false ou após um relançamento.

{
  "timeoutSeconds": 60
}

`mc_quit_client`

Desligue graciosamente o cliente Minecraft (o WebSocket caindo logo após o ack é o modo de sucesso normal). Por padrão, resolve o PID do cliente a partir da porta da ponte antes de sair, então consulta até que a porta pare de escutar e esse processo saia — em caso de sucesso, é seguro relançar imediatamente, mesmo através de launchers que rastreiam a instância (Prism ignora silenciosamente --launch enquanto ainda vê o processo antigo). Quando o PID não pode ser resolvido (sem lsof, permissões), ele cai para apenas fechamento de porta e o resultado diz isso — a JVM pode sobreviver à porta por alguns segundos, então nesse caso confirme você mesmo que o processo antigo saiu antes de relançar.

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

`mc_wait_for_bridge`

Bloqueie até que a ponte de um cliente recém-(re)iniciado responda, então conecte-se a ele. Varre as portas 9876-9886 uma vez por segundo, aceitando apenas a instância que corresponde ao diretório do jogo / versão da conexão anterior — então uma segunda instância em execução não é confundida com o relançamento. Passe expectedVersion apenas ao trocar deliberadamente de instância. Somente leitura.

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

`mc_run_command` (ferramenta de desenvolvimento opt-in)

Execute um comando de barra do Minecraft.

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

Desabilitado por padrão. Tanto este servidor (MCDEV_RUN_COMMAND=1) quanto o mod DebugBridge (runCommandEnabled em BridgeConfig) devem optar por participar. Veja Opt-in / ferramentas de desenvolvimento abaixo.

`mc_script_logs` (ferramenta de desenvolvimento opt-in)

Revise o log baseado em arquivo de execuções passadas de mc_execute (timestamp, código, resultado, erro, duração), resuma padrões de erro comuns ou imprima os caminhos dos logs.

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

Modo	Retorna
`"errors"`	As chamadas `mc_execute` mais recentes que falharam
`"stats"`	Padrões de erro agregados (quais mensagens recorrem)
`"paths"`	Onde os arquivos de log vivem no disco

Desabilitado por padrão. Habilitado por MCDEV_SCRIPT_LOGS=1. O MCPB do Claude Desktop expõe isso como um alternador voltado ao usuário ("Registrar execuções de script") — veja Opt-in / ferramentas de desenvolvimento.

Opt-in / ferramentas de desenvolvimento

Duas ferramentas de runtime são controladas por variáveis de ambiente para que o servidor padrão exponha apenas os wrappers somente leitura e "seguros". O mod da ponte tem suas próprias flags correspondentes, então virar apenas o env do lado do servidor não faz nada se o mod também não optou por participar.

Ferramenta	Variável de ambiente	Flag do lado da ponte	Superfície no Claude Desktop
`mc_run_command`	`MCDEV_RUN_COMMAND=1` (ou `true`)	`runCommandEnabled`	Não exposto via user_config do MCPB — defina o env explicitamente ao iniciar o servidor.
`mc_script_logs`	`MCDEV_SCRIPT_LOGS=1` (ou `true`)	(somente lado do servidor)	Alternador "Registrar execuções de script" nas configurações da extensão MCPB (também habilita o registro em arquivo de cada `mc_execute`).

Quando a variável de ambiente não está definida (ou definida como 0/false), a ferramenta simplesmente não é registrada e não aparecerá na lista de ferramentas do cliente MCP.

Indexador Java baseado em AST (pré-visualização)

Defina MCDEV_AST_PARSER=1 antes de init ou rebuild para usar o novo indexador baseado em java-parser. Comparado ao parser regex padrão, ele:

Lida corretamente com anotações multilinha, genéricos aninhados, records, tipos selados, pattern matching e campos inicializados por lambda (o parser regex conta errado silenciosamente em cada um desses).
Captura constantes de interface e métodos de interface default/static que o parser regex perde.
Não dobra membros de classes aninhadas nas listas do tipo externo.

Em um confronto direto no código-fonte do Minecraft 1.21.11 (amostra de 500 arquivos), o parser AST encontrou ~2× mais campos e ~33% menos métodos (corretamente atribuídos) do que o parser regex. É ~4,5× mais lento por arquivo, então uma reindexação completa roda em aproximadamente 75 segundos em vez de 17 — aceitável dentro de um init que já leva 2–5 minutos para download + descompilação. Classes de comando geradas muito grandes são isoladas em processos de trabalho limitados; se java-parser ainda esgotar um trabalhador em um arquivo, o indexador cai para o parser regex para esse arquivo em vez de falhar a reconstrução inteira.

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

O servidor MCP carimba manifest.indexerVersion para que possa dizer qual parser produziu o índice existente. Quando você vira a flag mas ainda não reconstruiu, o servidor imprime uma dica única por versão na próxima chamada de ferramenta:

[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

Dependência	Versão	Propósito
Node.js	18+	Runtime
Java	8+	Descompilação (Vineflower) e callgraph
~2GB	disco	Fontes descompiladas + cache

Nota: Java 17+ é recomendado para o comando callgraph devido à compatibilidade com Gradle.

Comandos CLI

Invoque via npx mcdev-mcp <command> (ou node dist/cli.js <command> a partir de um checkout do código-fonte).

Comando	Descrição
`serve`	Inicia o servidor MCP via stdio (iniciado por clientes MCP — não executado por humanos)
`init -v <version>`	Baixa, descompila, indexa fontes do Minecraft e gera callgraph
`init -v <version> --skip-callgraph`	Igual ao acima, mas pula a geração do callgraph
`callgraph -v <version>`	Gera o grafo de chamadas para `mc_find_refs`
`status`	Mostra todas as versões inicializadas e em qual estágio cada uma está
`rebuild -v <version>`	Reconstrói o índice de símbolos a partir de fontes já em cache
`rebuild -v <version> --with-callgraph`	Também regenera o callgraph na mesma execução
`clean -v <version> --all`	Remove dados em cache para uma versão
`clean --all`	Remove todos os dados em cache entre versões

Reindexação

Para reindexar uma versão:

# 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

Arquitetura

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

Como 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                │
                                    └────────────────────────────┘

Veja docs/ARCHITECTURE.md para documentação detalhada de design.

Local de armazenamento

mcdev-mcp armazena todos os dados em cache no diretório de cache padrão do SO, cortesia de env-paths. Tudo sob este diretório é regenerável — seguro excluir a qualquer momento — e init reconstruirá o que precisar na próxima execução.

Plataforma	Caminho
macOS	`~/Library/Caches/mcdev-mcp`
Linux	`~/.cache/mcdev-mcp` (compatível com XDG, honra `$XDG_CACHE_HOME`)
Windows	`%LOCALAPPDATA%\mcdev-mcp\Cache`

Uso de disco: aproximadamente 2 GB por versão do Minecraft (JAR ~60 MB, fontes descompiladas ~1,8 GB, banco do callgraph ~200 MB, índice de símbolos ~50 MB). Execute npx mcdev-mcp status para ver quais versões estão em cache, e npx mcdev-mcp clean --all (ou clean -v <version> --all) para recuperar espaço.

Layout

<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)

Atualizando de uma instalação pré-1.0? Versões anteriores armazenavam tudo sob ~/.mcdev-mcp/. Se você tem dados lá e quer mantê-los, mova-os manualmente para o novo local (ex.: no macOS: mv ~/.mcdev-mcp ~/Library/Caches/mcdev-mcp). Caso contrário, basta executar init novamente — a etapa de download é idempotente.

Desenvolvimento

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

Lançamentos

Os lançamentos são orientados por tags. Enviar uma tag v* aciona o GitHub Actions para:

Executar a matriz de testes completa e verificações TypeScript
Construir um único bundle MCPB universal em ubuntu-latest
Publicar o pacote no npm
Criar um GitHub Release com o .mcpb anexado

Para cortar um lançamento:

# 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

É isso — o workflow em .github/workflows/ci.yml cuida do resto. Nenhum segredo NPM_TOKEN é necessário; o workflow publica no npm via Trusted Publishing (OIDC). Um editor confiável deve ser configurado no lado do npm, nas configurações de acesso de publicação do pacote: proprietário use-ai-for-mc, repositório mcdev-mcp, workflow ci.yml. Os lançamentos também enviam atestados de proveniência do npm via npm publish --provenance.

A construção do MCPB também é executável localmente:

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

O bundle é universal — JavaScript puro mais sql.js (SQLite compilado para WebAssembly), sem binários nativos. O mesmo .mcpb funciona no macOS (arm64 e x86_64), Linux (x64/arm64) e Windows. Node ≥ 20 é necessário no runtime (de package.json engines).

Instalando o MCPB no Claude Desktop

Baixe o pacote na página de Releases e clique duas vezes no arquivo .mcpb. O Claude Desktop validará o manifesto e oferecerá a instalação. Após a instalação, execute mcdev-mcp init -v <version> em um terminal uma vez para popular o cache (a extensão não pode acionar init por conta própria — é deliberadamente restrito ao terminal, veja Quick Start).

Limitações

Análise Estática: mc_find_refs não consegue rastrear chamadas por reflexão, callbacks JNI ou referências a métodos/lambdas criadas dinamicamente
Somente Cliente: Classes do lado do servidor não são incluídas na análise estática
Ferramentas de Runtime: Requer Minecraft em execução com o mod DebugBridge instalado

Aviso Legal

Esta ferramenta descompila o código-fonte do Minecraft para fins de referência de desenvolvimento. Por favor, respeite a propriedade intelectual da Mojang:

Você PODE:

Descompilar e estudar o código para compreensão e aprendizado
Usar o conhecimento para desenvolver mods que não contenham código substancial da Mojang
Referenciar nomes de classes/métodos para desenvolvimento de mods

Você NÃO PODE:

Distribuir código-fonte descompilado
Distribuir versões modificadas do Minecraft
Usar código descompilado comercialmente sem permissão

Conforme o EULA do Minecraft: "Você não pode distribuir quaisquer Versões Modificadas do nosso jogo ou software" e "Mods podem ser distribuídos; versões hackeadas ou Versões Modificadas do cliente ou servidor do jogo não podem ser distribuídas."

Esta ferramenta é somente para referência — não copie código descompilado diretamente em seus projetos.

Componentes de Terceiros

Este projeto inclui ou usa software de terceiros sob as seguintes licenças:

DecompilerMC (MIT) — Lógica de descompilação adaptada e traduzida de Python para TypeScript em src/decompiler/
Vineflower (Apache-2.0) — Descompilador Java usado para geração de código-fonte
java-callgraph2 — Clonado em tempo de execução para geração de grafo de chamadas estático

Dependências adicionais em tempo de execução (baixadas/usadas):

Mojang — Mapeamentos oficiais do ProGuard e JAR do cliente do Minecraft

Veja LICENSE para o texto completo da licença e atribuições de terceiros.

mcdev-mcp

Documentação

mcdev-mcp

Recursos

Análise Estática (funciona offline)

Interação em Tempo de Execução (requer o mod DebugBridge)

Recursos MCP

Início Rápido

1. Inicialize no seu terminal

2. Adicione ao seu cliente MCP

Codex Desktop / Codex CLI

Outros clientes MCP

3. (Opcional) Instale o DebugBridge para ferramentas de jogo ao vivo

Versões Suportadas

(Opcional) Pular Grafo de Chamadas

Verificar Instalação

Instalar a partir do código-fonte (desenvolvimento)

Ferramentas MCP

Gerenciamento de Versão (Ferramentas Estáticas)

mc_version

Requisitos das Ferramentas Estáticas

mc_search

mc_get_class

mc_get_method

mc_find_refs

mc_list_classes

mc_list_packages

mc_find_hierarchy

Ferramentas de Tempo de Execução

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

Controle de sessão e ciclo de desenvolvimento

mc_join_server

mc_leave_server

mc_wait_until_in_world

mc_quit_client

mc_wait_for_bridge

mc_run_command (ferramenta de desenvolvimento opt-in)

mc_script_logs (ferramenta de desenvolvimento opt-in)

Opt-in / ferramentas de desenvolvimento

Indexador Java baseado em AST (pré-visualização)

Requisitos

Comandos CLI

Reindexação

Arquitetura

Como Funciona

Local de armazenamento

Layout

Desenvolvimento

Lançamentos

Instalando o MCPB no Claude Desktop

Limitações

Aviso Legal

Componentes de Terceiros

Licença

`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` (ferramenta de desenvolvimento opt-in)

`mc_script_logs` (ferramenta de desenvolvimento opt-in)