Minecraft Modding MCP

✨ ¿Qué es esto?

MCModding-MCP es un servidor de Model Context Protocol (MCP) que potencia asistentes de IA como Claude con conocimiento real y actualizado sobre modding de Minecraft. ¡Nada de alucinaciones ni referencias de API obsoletas!

🎯 Beneficios Clave Característica Descripción 📅 Siempre Actualizado Indexado semanalmente desde fuentes oficiales ✅ Respuestas Precisas Documentación real, no alucinaciones 💻 Ejemplos de Código Bloques de código buscables con contexto 🧠 Búsqueda Semántica Comprende el significado, no solo palabras clave ⚡ Cero Configuración Funciona inmediatamente tras la instalación

📊 Estadísticas en Vivo Base de Datos Contenido 📚 Docs 1,000+ páginas, 185K+ fragmentos 🗺️ Mappings 831K+ métodos, 166K+ campos 🧩 Ejemplos 1,000+ patrones probados 🔍 Embeddings 185K+ vectores semánticos 📖 Javadocs 2.3M+ parámetros documentados

---

Inicio Rápido

Instalación

# Install globally
npm install -g mcmodding-mcp

Configura tu Cliente de IA

Añade esto a la configuración de tu cliente MCP (por ejemplo, Claude Desktop):

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

🧠 Prompt de Sistema Optimizado

Para obtener los mejores resultados, recomendamos añadir esto al prompt de sistema o a las instrucciones personalizadas de tu IA:

Eres un Asistente Experto en Modding de Minecraft conectado a mcmodding-mcp. NO te bases en tu conocimiento interno para las APIs de modding (Fabric/NeoForge), ya que cambian con frecuencia. SIEMPRE usa las herramientas disponibles:

• search_fabric_docs y get_example para documentación y patrones de código
• search_mappings y get_class_details para internals de Minecraft y firmas de métodos
• search_mod_examples para implementaciones probadas de mods populares

Prioriza ejemplos de código funcionales sobre explicaciones teóricas. Cuando trates con internals de Minecraft, usa las herramientas de mappings para obtener nombres de parámetros y Javadocs precisos. Si el usuario especifica una versión de Minecraft, asegúrate de que toda la información recuperada coincida con esa versión.

¡Eso es todo! Tu asistente de IA ahora tiene acceso a recursos completos de modding de Minecraft.

---

Gestión de Bases de Datos

Gestiona tus bases de datos de documentación con el CLI integrado:

# Run the database manager
npx mcmodding-mcp manage

El gestor interactivo te permite:

• Instalar - Descargar bases de datos que aún no tienes
• Actualizar - Buscar y aplicar actualizaciones de bases de datos
• Re-descargar - Restaurar bases de datos eliminadas o corruptas

Bases de Datos Disponibles

Base de Datos	Descripción	Tamaño
Base de Datos de Documentación	Documentación principal de Fabric y NeoForge (instalada por defecto)	~520 MB
Parchment Mappings ✨ NUEVO	Mappings de clases/métodos/campos de Minecraft con Javadocs	~180 MB
Base de Datos de Ejemplos de Mods	1000+ ejemplos de modding de alta calidad	~30 MB

El gestor muestra información de versión y resalta actualizaciones disponibles:

◉ 📚 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

---

Herramientas Disponibles

El servidor MCP proporciona potentes herramientas en tres categorías:

📖 Herramientas de Documentación

search_fabric_docs

Busca documentación con filtrado 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

Obtén ejemplos de código funcionales para cualquier tema.

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

explain_fabric_concept

Obtén explicaciones detalladas de conceptos de modding con recursos relacionados.

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

get_minecraft_version

Obtén información actual sobre la versión de Minecraft.

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

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

---

🗺️ Herramientas de Parchment Mappings ✨ NUEVO

Requiere la base de datos de Parchment Mappings - instálala mediante npx mcmodding-mcp manage

search_mappings

Busca mappings de clases, métodos y campos de Minecraft con nombres de parámetros y 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

Obtén información completa sobre una clase de Minecraft, incluyendo todos sus métodos y campos.

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

lookup_obfuscated

Consulta nombres desofuscados a partir de identificadores ofuscados (útil para registros de errores).

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

get_method_signature

Obtén la firma completa de un método, incluyendo todos los nombres y tipos de parámetros.

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

browse_package

Descubre clases en un paquete de Minecraft.

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

---

🧩 Herramientas de Ejemplos de Mods

Requiere la base de datos de Ejemplos de Mods - instálala mediante npx mcmodding-mcp manage

search_mod_examples

Busca código probado de mods populares como Create, Botania y 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

Obtén información detallada sobre un ejemplo específico con código completo y explicaciones.

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

list_canonical_mods

Descubre todos los mods indexados y sus ejemplos disponibles.

list_mod_categories

Explora las categorías de ejemplos disponibles (bloques, entidades, renderizado, etc.).

---

Características

Motor de Búsqueda Híbrido

Combina múltiples estrategias de búsqueda para obtener los mejores resultados:

Estrategia	Propósito
FTS5 Texto Completo	Coincidencia rápida de palabras clave con ranking
Embeddings Semánticos	Comprensión de significado y contexto
Búsqueda por Sección	Encontrar secciones de documentación relevantes
Búsqueda de Código	Localizar patrones de código específicos

Actualizaciones Automáticas

La base de datos comprueba automáticamente si hay actualizaciones al iniciar:

• Compara la versión local con los lanzamientos de GitHub
• Descarga nuevas versiones con verificación de hash
• Crea copias de seguridad antes de actualizar
• No bloquea - el servidor se inicia inmediatamente

Fuentes de Documentación

Actualmente indexa:

• wiki.fabricmc.net - Wiki de Fabric (226+ páginas)
• docs.fabricmc.net - Documentación oficial de Fabric (266+ páginas)
• docs.neoforged.net - Documentación de NeoForge (512+ páginas)

---

Para Desarrolladores

Configuración de Desarrollo

# 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 Compilación

# 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

Estructura del Proyecto

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 de la Base de Datos

-- 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(...);

---

Flujo de Trabajo de Lanzamiento

Este proyecto utiliza release-please para lanzamientos automatizados.

Estrategia de Ramas

Rama	Propósito
dev	Desarrollo activo
prod	Lanzamientos de producción

Cómo Funciona

1. Haz push de commits a dev usando conventional commits
2. Release-please mantiene un PR de lanzamiento (dev → prod)
3. Al fusionarse, lanzamiento automático: publicación npm + lanzamiento en GitHub + subida de base de datos
4. Los cambios se sincronizan de vuelta a dev

Consulta RELEASE_WORKFLOW.md para más detalles.

---

Configuración

Variables de Entorno

Variable	Descripción	Valor por Defecto
DB_PATH	Ruta personalizada de base de datos	./data/mcmodding-docs.db
GITHUB_REPO_URL	Repositorio personalizado para actualizaciones	Auto-detectado
MCP_DEBUG	Habilitar registro de depuración	false

Desactivar Actualizaciones Automáticas

Establece DB_PATH en una ubicación personalizada para gestionar las actualizaciones manualmente:

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

---

💡 ¡Comparte tus Ideas!

Estamos desarrollando activamente mcmodding-mcp y ¡queremos saber tu opinión!

¿Tienes una Idea?

• Solicitudes de funciones - ¿Qué herramientas harían tu modding más fácil?
• Nuevas fuentes de documentación - ¿Conoces un gran recurso de modding que deberíamos indexar?
• Mejoras de flujo de trabajo - ¿Cómo podrían funcionar mejor las herramientas para tu caso de uso?

👉 Abre una Solicitud de Función

¿Encontraste un Error?

• ¿Resultados de búsqueda incorrectos?
• ¿Documentación faltante o desactualizada?
• ¿Una herramienta que no funciona como se esperaba?

👉 Reporta un Error

Comparte tu Experiencia

¿Usas mcmodding-mcp para un proyecto interesante? Nos encantaría saberlo. Comparte tu historia en Discussions.

---

Contribuciones

¡Agradecemos las contribuciones! Consulta CONTRIBUTING.md para las pautas.

Guía Rápida de Contribución

1. Haz un fork del repositorio
2. Crea una rama de características desde dev
3. Haz cambios con conventional commits
4. Envía un PR a dev

---

Licencia

Licencia MIT - consulta LICENSE para más detalles.

Registro de Cambios

Consulta CHANGELOG.md para un historial detallado de cambios y lanzamientos.

---

Agradecimientos

• Documentación de Fabric - Documentación oficial de Fabric
• Wiki de Fabric - Wiki comunitaria
• Documentación de NeoForge - Documentación oficial de NeoForge
• ParchmentMC - Nombres de parámetros y mappings de Javadocs
• Model Context Protocol - Especificación de MCP
• Transformers.js - Embeddings ML locales
• better-sqlite3 - Bindings SQLite rápidos

---