Project Zomboid MCP Server

Un servidor MCP impulsado por IA para el desarrollo de mods de Project Zomboid, que ofrece validación de scripts, generación y asistencia contextual.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Project Zomboid MCP Server

Un servidor completo del Protocolo de Contexto de Modelos (MCP) para el desarrollo de mods de Project Zomboid, que proporciona validación inteligente de scripts, generación y asistencia contextual mediante herramientas mejoradas con IA.

🚀 Características

Integración inteligente con Project Zomboid

  • Detección automática de instalaciones de Steam, Epic Games y GOG
  • Soporte multiplataforma (Windows, Linux, macOS, WSL)
  • Compatibilidad con Build 42 con soporte para estructura moderna de mods
  • Sistema de respaldo con análisis local de scripts

Conocimiento integral de datos del juego

  • Indexación completa del juego vanilla con capacidades de búsqueda de texto completo
  • Extracción de metadatos enriquecidos incluyendo daño, durabilidad, categorías y etiquetas
  • Mapeo de relaciones entre objetos, recetas y dependencias
  • Validación de referencias en tiempo real contra la base de datos del juego

Generación inteligente de scripts

  • Generación basada en plantillas utilizando patrones reales del juego
  • Análisis de equilibrio comparando objetos personalizados con equivalentes vanilla
  • Validación de referencias asegurando que todas las dependencias existan
  • Múltiples formatos de salida (objetos, recetas, scripts de reparación, sonidos, vehículos)

Motor de validación avanzado

  • Validación de sintaxis en tiempo real con informes de errores detallados
  • Verificación de referencias para objetos, sonidos y sprites
  • Análisis de equilibrio con evaluación de impacto en el juego
  • Sugerencias de mejores prácticas para el desarrollo de mods

Listo para implementación

  • Soporte para Cloudflare Workers para implementación sin servidor
  • Integración con D1 Database para almacenamiento persistente
  • API HTTP para integración con cualquier cliente MCP
  • Listo para Claude Desktop con configuraciones de ejemplo

🔧 Instalación

Requisitos previos

  • Node.js 18.0.0 o superior
  • Administrador de paquetes npm o yarn

Desarrollo local

# Clone the repository
git clone https://github.com/minimax/pz-mcp-server.git
cd pz-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Implementación en Cloudflare Workers

# Install Wrangler CLI
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Create D1 database
wrangler d1 create pz-mcp-prod

# Deploy to Cloudflare Workers
wrangler deploy

📖 Uso

Con Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "pz-mcp-server": {
      "command": "node",
      "args": ["/path/to/pz-mcp-server/dist/index.js"]
    }
  }
}

Con Cursor/VSCode

El servidor se puede integrar con cualquier IDE que soporte el protocolo MCP:

  1. Instala la extensión MCP para tu IDE
  2. Configura el endpoint del servidor
  3. Comienza a usar las herramientas de desarrollo de Project Zomboid

🛠️ Herramientas MCP

search_vanilla

Busca contenido vanilla de Project Zomboid con coincidencia inteligente.

Parámetros:

  • query (cadena): Consulta de búsqueda para contenido del juego
  • type (cadena, opcional): Filtrar por tipo de contenido (item, recipe, sound, vehicle)
  • category (cadena, opcional): Filtrar por categoría de objeto
  • limit (número, opcional): Resultados máximos (predeterminado: 20)

Ejemplo:

// Search for weapons
await mcp.callTool('search_vanilla', {
  query: 'katana',
  type: 'item',
  category: 'Weapon'
});

generate_script

Genera scripts equilibrados de Project Zomboid usando plantillas y datos del juego.

Parámetros:

  • type (cadena): Tipo de script (item, recipe, evolvedrecipe, fixing, sound, vehicle)
  • name (cadena): Nombre del objeto/receta a generar
  • properties (objeto): Propiedades y especificaciones
  • module (cadena, opcional): Nombre del módulo (predeterminado: "Base")

Ejemplo:

// Generate a custom weapon
await mcp.callTool('generate_script', {
  type: 'item',
  name: 'SuperKatana',
  properties: {
    DisplayName: 'Super Katana',
    Type: 'Weapon',
    MaxDamage: 5.0,
    Weight: 2.0,
    Categories: 'LongBlade'
  }
});

validate_script

Valida la sintaxis y las referencias de scripts de Project Zomboid con informes de errores detallados.

Parámetros:

  • content (cadena): Contenido del script a validar
  • type (cadena, opcional): Tipo de script esperado
  • strict (booleano, opcional): Habilitar modo de validación estricta

Ejemplo:

// Validate mod script
await mcp.callTool('validate_script', {
  content: scriptContent,
  type: 'item',
  strict: true
});

check_references

Valida referencias de objetos, sonidos y sprites contra la base de datos del juego.

Parámetros:

  • references (cadena[]): Lista de referencias a validar
  • type (cadena, opcional): Tipo de referencias (item, sound, sprite, all)

Ejemplo:

// Check if items exist
await mcp.callTool('check_references', {
  references: ['Base.Katana', 'Base.Apple'],
  type: 'item'
});

analyze_mod

Análisis integral del directorio de mods incluyendo validación de equilibrio, compatibilidad y estructura.

Parámetros:

  • modPath (cadena): Ruta al directorio del mod
  • checkBalance (booleano, opcional): Realizar análisis de equilibrio
  • checkCompatibility (booleano, opcional): Verificar compatibilidad con vanilla
  • generateReport (booleano, opcional): Generar informe de análisis detallado

Ejemplo:

// Analyze mod quality
await mcp.callTool('analyze_mod', {
  modPath: '/path/to/my-mod',
  checkBalance: true,
  checkCompatibility: true
});

parse_game_files

Analiza e indexa los archivos del juego Project Zomboid para poblar la base de datos.

Parámetros:

  • gamePath (cadena, opcional): Ruta a la instalación de Project Zomboid (se detecta automáticamente si no se proporciona)
  • forceReparse (booleano, opcional): Forzar re-análisis incluso si los datos existen

Ejemplo:

// Parse vanilla game files
await mcp.callTool('parse_game_files', {
  forceReparse: false
});

🏗️ Arquitectura

┌─────────────────────────────────────────────────────┐
│                MCP Server Core                      │
├─────────────────────────────────────────────────────┤
│  Path Manager  │  Enhanced Parser  │  Script Gen    │
├─────────────────────────────────────────────────────┤
│          SQLite/D1 Database Layer                   │
├─────────────────────────────────────────────────────┤
│  Game Data     │  Templates       │  Validation     │
│  (Vanilla PZ)  │  (JSON-based)   │  (Real-time)    │
└─────────────────────────────────────────────────────┘

Componentes principales

  • DatabaseManager: Base de datos SQLite/D1 con capacidades de búsqueda de texto completo
  • ProjectZomboidParser: Analiza archivos vanilla del juego y directorios de mods
  • ScriptGenerator: Genera scripts equilibrados usando plantillas y datos del juego
  • ValidationEngine: Validación de sintaxis y referencias en tiempo real
  • ModAnalyzer: Análisis integral de mods y métricas de calidad
  • PathManager: Detección automática de instalaciones de Project Zomboid

🌐 Implementación en Cloudflare Workers

El servidor incluye soporte completo para Cloudflare Workers para implementación sin servidor:

Características

  • D1 Database para almacenamiento persistente
  • KV Storage para almacenamiento en caché de datos de acceso frecuente
  • Endpoints de API HTTP para todas las herramientas MCP
  • Escalado automático con cero arranques en frío
  • Implementación global en el borde para baja latencia

Endpoints de API

  • GET /health - Verificación de estado
  • GET /mcp/info - Capacidades del servidor
  • POST /tools/{toolName} - Ejecutar herramientas MCP
  • POST /admin/load-game-data - Cargar datos vanilla del juego

Configuración

Actualiza wrangler.toml con tus IDs de base de datos:

[[env.production.d1_databases]]
binding = "DB"
database_name = "pz-mcp-prod"
database_id = "your-database-id"

📋 Flujo de trabajo de desarrollo

Configuración para desarrollo de mods

  1. Inicializar base de datos:

    npm run dev
# Server will auto-detect Project Zomboid installation

  2. Analizar archivos del juego:

    await mcp.callTool('parse_game_files', {});

  3. Comenzar el desarrollo:

    // Search for existing items
const results = await mcp.callTool('search_vanilla', {
  query: 'weapon damage > 3'
});

// Generate new item
const script = await mcp.callTool('generate_script', {
  type: 'item',
  name: 'MyWeapon',
  properties: { /* ... */ }
});

// Validate before use
const validation = await mcp.callTool('validate_script', {
  content: script
});

Formatos de archivo compatibles

  • mod.info: Metadatos y configuración del mod
  • Archivos de script (.txt): Objetos, recetas, vehículos, sonidos, scripts de reparación
  • Archivos Lua (.lua): Lógica del juego y manejadores de eventos
  • Recursos: Texturas, sonidos, modelos y mapas

🔍 Ejemplos

Crear un arma personalizada

// 1. Search for similar weapons
const similarWeapons = await mcp.callTool('search_vanilla', {
  query: 'katana sword blade',
  type: 'item'
});

// 2. Generate balanced weapon
const weaponScript = await mcp.callTool('generate_script', {
  type: 'item',
  name: 'EliteKatana',
  properties: {
    DisplayName: 'Elite Katana',
    Type: 'Weapon',
    Weight: 2.5,
    MaxDamage: 4.5,
    MinDamage: 3.5,
    Categories: 'LongBlade',
    Icon: 'Katana',
    SwingSound: 'KatanaSwing'
  }
});

// 3. Validate the script
const validation = await mcp.callTool('validate_script', {
  content: weaponScript,
  strict: true
});

// 4. Check references exist
await mcp.callTool('check_references', {
  references: ['Katana', 'KatanaSwing'],
  type: 'all'
});

Analizar la calidad de un mod

const analysis = await mcp.callTool('analyze_mod', {
  modPath: '/path/to/my-zombie-mod',
  checkBalance: true,
  checkCompatibility: true,
  generateReport: true
});

console.log(`Mod Quality Score: ${analysis.quality.overall}/100`);
console.log(`Issues Found: ${analysis.issues.length}`);
console.log(`Recommendations: ${analysis.recommendations.join(', ')}`);

🤝 Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Añade pruebas para la nueva funcionalidad
  5. Envía una solicitud de extracción (pull request)

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

🆘 Soporte

  • GitHub Issues: Informes de errores y solicitudes de características
  • Documentación: Guías completas y referencias de API
  • Comunidad: Servidor de Discord para desarrolladores de mods

🔮 Hoja de ruta

v1.1.0 - Características mejoradas

  • Soporte para scripts de vehículos con análisis y generación completos
  • Plantillas avanzadas para escenarios complejos de modding
  • Integración de scripts Lua para asistencia en la lógica del juego
  • Herramientas de optimización de rendimiento para mods grandes

v1.2.0 - Características de colaboración

  • Soporte multiusuario para desarrollo de mods en equipo
  • Integración con control de versiones con flujos de trabajo de Git
  • Pipelines de pruebas automatizadas para validación de mods
  • Generación de documentación a partir del análisis de mods

v2.0.0 - Plataforma completa

  • Interfaz web para usuarios no técnicos
  • Integración con Steam Workshop para publicación directa
  • Funciones de mercado para descubrimiento de mods
  • Soporte empresarial para equipos grandes de mods

Hecho con ❤️ para la comunidad de modding de Project Zomboid