Minecraft Modding MCP

✨ O que é isso?

O MCModding-MCP é um servidor do Model Context Protocol (MCP) que potencializa assistentes de IA como o Claude com conhecimento real e atualizado sobre modding de Minecraft. Chega de alucinações ou referências de API desatualizadas!

🎯 Principais Benefícios Recurso Descrição 📅 Sempre Atualizado Indexado semanalmente a partir de fontes oficiais ✅ Respostas Precisas Documentação real, não alucinações 💻 Exemplos de Código Blocos de código pesquisáveis com contexto 🧠 Busca Semântica Entende o significado, não apenas palavras-chave ⚡ Zero Configuração Funciona imediatamente após a instalação

📊 Estatísticas ao Vivo Banco de Dados Conteúdo 📚 Documentos 1.000+ páginas, 185K+ trechos 🗺️ Mapeamentos 831K+ métodos, 166K+ campos 🧩 Exemplos 1.000+ padrões testados em batalha 🔍 Embeddings 185K+ vetores semânticos 📖 Javadocs 2,3M+ parâmetros documentados

---

Início Rápido

Instalação

# Install globally
npm install -g mcmodding-mcp

Configure Seu Cliente de IA

Adicione à configuração do seu cliente MCP (ex.: Claude Desktop):

{
  "mcpServers": {
    "mcmodding": {
      "command": "mcmodding-mcp"
    }
  }
}

🧠 Prompt de Sistema Otimizado

Para obter os melhores resultados, recomendamos adicionar isto ao prompt de sistema do seu assistente de IA ou às instruções personalizadas:

Você é um Assistente Especialista em Modding de Minecraft conectado ao mcmodding-mcp. NÃO confie no seu conhecimento interno para APIs de modding (Fabric/NeoForge), pois elas mudam com frequência. SEMPRE use as ferramentas disponíveis:

• search_fabric_docs e get_example para documentação e padrões de código
• search_mappings e get_class_details para internals do Minecraft e assinaturas de métodos
• search_mod_examples para implementações testadas em batalha de mods populares

Priorize exemplos de código funcionais em vez de explicações teóricas. Ao lidar com internals do Minecraft, use as ferramentas de mapeamento para obter nomes de parâmetros e Javadocs precisos. Se o usuário especificar uma versão do Minecraft, garanta que todas as informações recuperadas correspondam a essa versão.

Pronto! Seu assistente de IA agora tem acesso a recursos abrangentes de modding de Minecraft.

---

Gerenciamento de Banco de Dados

Gerencie seus bancos de dados de documentação com a CLI integrada:

# Run the database manager
npx mcmodding-mcp manage

O gerenciador interativo permite que você:

• Instalar - Baixe bancos de dados que você ainda não tem
• Atualizar - Verifique e aplique atualizações de banco de dados
• Baixar novamente - Restaure bancos de dados excluídos ou corrompidos

Bancos de Dados Disponíveis

Banco de Dados	Descrição	Tamanho
Banco de Dados de Documentação	Documentação principal do Fabric e NeoForge (instalado por padrão)	~520 MB
Parchment Mappings ✨ NOVO	Mapeamentos de classes/métodos/campos do Minecraft com Javadocs	~180 MB
Banco de Dados de Exemplos de Mods	1.000+ exemplos de modding de alta qualidade	~30 MB

O gerenciador mostra informações de versão e destaca atualizações disponíveis:

◉ 📚 Documentation Database [core]
     ✔ Installed: v0.2.1 → ↻ Update: v0.2.2 [520.3 MB]
     Core Fabric & NeoForge documentation - installed by default

○ 🗺️ Parchment Mappings Database ✨ NEW
     ⚠ Not installed → Available: v0.1.0 [178.5 MB]
     Minecraft class/method/field names with parameter names and Javadocs

○ 🧩 Mod Examples Database
     ⚠ Not installed → Available: v0.1.0 [28.1 MB]
     1000+ high-quality modding examples for Fabric & NeoForge

---

Ferramentas Disponíveis

O servidor MCP fornece ferramentas poderosas em três categorias:

📖 Ferramentas de Documentação

search_fabric_docs

Pesquise documentação com filtragem inteligente.

// Example: Find information about item registration
{
  query: "how to register custom items",
  category: "items",           // Optional filter
  loader: "fabric",            // fabric | neoforge
  minecraft_version: "1.21.10"  // Optional version filter
}

get_example

Obtenha exemplos de código funcionais para qualquer tópico.

// Example: Get block registration code
{
  topic: "custom block with block entity",
  language: "java",
  loader: "fabric"
}

explain_fabric_concept

Obtenha explicações detalhadas de conceitos de modding com recursos relacionados.

// Example: Understand mixins
{
  concept: 'mixins';
}

get_minecraft_version

Obtenha informações atuais da versão do Minecraft.

// Get latest version
{
  type: 'latest';
}

// Get all indexed versions
{
  type: 'all';
}

---

🗺️ Ferramentas de Parchment Mappings ✨ NOVO

Requer o banco de dados Parchment Mappings - instale via npx mcmodding-mcp manage

search_mappings

Pesquise mapeamentos de classes, métodos e campos do Minecraft com nomes de parâmetros e Javadocs.

// Example: Find block-related classes and methods
{
  query: "BlockEntity",
  type: "class",              // class | method | field | all
  minecraft_version: "1.21.10",
  include_javadoc: true
}

get_class_details

Obtenha informações abrangentes sobre uma classe do Minecraft, incluindo todos os métodos e campos.

// Example: Explore the Block class
{
  class_name: "net.minecraft.world.level.block.Block",
  include_methods: true,
  include_fields: true
}

lookup_obfuscated

Consulte nomes desofuscados a partir de identificadores ofuscados (útil para logs de crash).

// Example: Decode an obfuscated method name
{
  obfuscated_name: 'm_46859_';
}

get_method_signature

Obtenha a assinatura completa de um método, incluindo todos os nomes e tipos de parâmetros.

// Example: Get method details
{
  class_name: "Block",
  method_name: "onPlace"
}

browse_package

Descubra classes em um pacote do Minecraft.

// Example: Browse block package
{
  package_name: 'net.minecraft.world.level.block';
}

---

🧩 Ferramentas de Exemplos de Mods

Requer o banco de dados de Exemplos de Mods - instale via npx mcmodding-mcp manage

search_mod_examples

Pesquise código testado em batalha de mods populares como Create, Botania e Applied Energistics 2.

// Example: Find block entity implementations
{
  query: "block entity tick",
  mod: "Create",              // Optional: filter by mod
  category: "tile-entities",
  complexity: "intermediate"
}

get_mod_example

Obtenha informações detalhadas sobre um exemplo específico com código completo e explicações.

// Example: Get full details for an example
{
  id: 42,
  include_related: true
}

list_canonical_mods

Descubra todos os mods indexados e seus exemplos disponíveis.

list_mod_categories

Navegue pelas categorias de exemplos disponíveis (blocos, entidades, renderização, etc.).

---

Recursos

Mecanismo de Busca Híbrido

Combina múltiplas estratégias de busca para obter os melhores resultados:

Estratégia	Finalidade
Texto Completo FTS5	Correspondência rápida de palavras-chave com classificação
Embeddings Semânticos	Compreensão de significado e contexto
Busca por Seção	Encontrar seções relevantes da documentação
Busca de Código	Localizar padrões de código específicos

Atualizações Automáticas

O banco de dados verifica automaticamente atualizações na inicialização:

• Compara a versão local com os lançamentos do GitHub
• Baixa novas versões com verificação de hash
• Cria backups antes de atualizar
• Não bloqueante - o servidor inicia imediatamente

Fontes de Documentação

Atualmente indexa:

• wiki.fabricmc.net - Wiki do Fabric (226+ páginas)
• docs.fabricmc.net - Documentação Oficial do Fabric (266+ páginas)
• docs.neoforged.net - Documentação do NeoForge (512+ páginas)

---

Para Desenvolvedores

Configuração de Desenvolvimento

# Clone repository
git clone https://github.com/OGMatrix/mcmodding-mcp.git
cd mcmodding-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

Comandos de Build

# Development
npm run dev              # Watch mode with hot reload
npm run typecheck        # TypeScript type checking
npm run lint             # ESLint
npm run test             # Run tests
npm run format           # Prettier formatting

# Production
npm run build            # Build TypeScript
npm run build:prod       # Build with fresh documentation index
npm run index-docs       # Index documentation with embeddings

# Database Management
npx mcmodding-mcp manage # Interactive database installer/updater

Estrutura do Projeto

mcmodding-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── db-versioning.ts      # Auto-update system
│   ├── indexer/
│   │   ├── crawler.ts        # Documentation crawler
│   │   ├── chunker.ts        # Text chunking
│   │   ├── embeddings.ts     # Semantic embeddings
│   │   ├── store.ts          # SQLite database
│   │   └── sitemap.ts        # Sitemap parsing
│   ├── services/
│   │   ├── search-service.ts # Search logic
│   │   └── concept-service.ts # Concept explanations
│   └── tools/
│       ├── searchDocs.ts     # search_fabric_docs handler
│       ├── getExample.ts     # get_example handler
│       └── explainConcept.ts # explain_fabric_concept handler
├── scripts/
│   └── index-docs.ts         # Documentation indexing script
├── data/
│   ├── mcmodding-docs.db     # SQLite database
│   └── db-manifest.json      # Version manifest
└── dist/                     # Compiled JavaScript

Esquema do Banco de Dados

-- Documents: Full documentation pages
CREATE TABLE documents (
  id INTEGER PRIMARY KEY,
  url TEXT UNIQUE NOT NULL,
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  category TEXT NOT NULL,
  loader TEXT NOT NULL,          -- fabric | neoforge | shared
  minecraft_version TEXT,
  hash TEXT NOT NULL             -- For change detection
);

-- Chunks: Searchable content units
CREATE TABLE chunks (
  id TEXT PRIMARY KEY,
  document_id INTEGER NOT NULL,
  chunk_type TEXT NOT NULL,      -- title | section | code | full
  content TEXT NOT NULL,
  section_heading TEXT,
  code_language TEXT,
  word_count INTEGER,
  has_code BOOLEAN
);

-- Embeddings: Semantic search vectors
CREATE TABLE embeddings (
  chunk_id TEXT PRIMARY KEY,
  embedding BLOB NOT NULL,       -- 384-dim Float32Array
  dimension INTEGER NOT NULL,
  model TEXT NOT NULL            -- Xenova/all-MiniLM-L6-v2
);

-- FTS5 indexes for fast text search
CREATE VIRTUAL TABLE documents_fts USING fts5(...);
CREATE VIRTUAL TABLE chunks_fts USING fts5(...);

---

Fluxo de Trabalho de Lançamento

Este projeto usa release-please para lançamentos automatizados.

Estratégia de Branch

Branch	Finalidade
dev	Desenvolvimento ativo
prod	Lançamentos de produção

Como Funciona

1. Envie commits para dev usando conventional commits
2. O release-please mantém um PR de lançamento (dev → prod)
3. Quando mesclado, lançamento automático: npm publish + GitHub release + upload do banco de dados
4. As alterações são sincronizadas de volta para dev

Consulte RELEASE_WORKFLOW.md para obter detalhes completos.

---

Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
DB_PATH	Caminho personalizado do banco de dados	./data/mcmodding-docs.db
GITHUB_REPO_URL	Repositório personalizado para atualizações	Detectado automaticamente
MCP_DEBUG	Ativar registro de depuração	false

Desativando Atualizações Automáticas

Defina DB_PATH para um local personalizado para gerenciar atualizações manualmente:

DB_PATH=/path/to/my/database.db mcmodding-mcp

---

💡 Compartilhe Suas Ideias!

Estamos desenvolvendo ativamente o mcmodding-mcp e queremos ouvir você!

Tem uma ideia?

• Solicitações de recursos - Quais ferramentas facilitariam seu modding?
• Novas fontes de documentação - Conhece um ótimo recurso de modding que devemos indexar?
• Melhorias no fluxo de trabalho - Como as ferramentas poderiam funcionar melhor para o seu caso de uso?

👉 Abra uma Solicitação de Recurso

Encontrou um bug?

• Resultados de busca incorretos?
• Documentação ausente ou desatualizada?
• Ferramenta não funcionando como esperado?

👉 Reporte um Bug

Compartilhe Sua Experiência

Usando o mcmodding-mcp em um projeto legal? Adoraríamos saber! Compartilhe sua história em Discussions.

---

Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para obter diretrizes.

Guia Rápido de Contribuição

1. Faça um fork do repositório
2. Crie uma branch de recurso a partir de dev
3. Faça alterações com conventional commits
4. Envie um PR para dev

---

Licença

Licença MIT - consulte LICENSE para obter detalhes.

Changelog

Consulte CHANGELOG.md para obter um histórico detalhado de alterações e lançamentos.

---

Agradecimentos

• Fabric Documentation - Documentação oficial do Fabric
• Fabric Wiki - Wiki da comunidade
• NeoForge Documentation - Documentação oficial do NeoForge
• ParchmentMC - Nomes de parâmetros e mapeamentos de Javadoc
• Model Context Protocol - Especificação do MCP
• Transformers.js - Embeddings de ML locais
• better-sqlite3 - Bindings SQLite rápidos

---