Project Zomboid MCP Server

Um servidor MCP com inteligência artificial para desenvolvimento de mods do Project Zomboid, oferecendo validação de scripts, geração e assistência contextual.

GitHub
6
Experimente este MCPPatrocinado

Documentação

Project Zomboid MCP Server

Um servidor abrangente do Model Context Protocol (MCP) para desenvolvimento de mods de Project Zomboid, oferecendo validação inteligente de scripts, geração e assistência contextual por meio de ferramentas aprimoradas por IA.

🚀 Recursos

Integração Inteligente com Project Zomboid

  • Detecção automática de instalações via Steam, Epic Games e GOG
  • Suporte multiplataforma (Windows, Linux, macOS, WSL)
  • Compatibilidade com Build 42 e suporte à estrutura moderna de mods
  • Sistema de fallback com análise local de scripts

Conhecimento Abrangente de Dados do Jogo

  • Indexação completa do jogo vanilla com recursos de busca em texto completo
  • Extração de metadados ricos, incluindo dano, durabilidade, categorias e tags
  • Mapeamento de relacionamentos entre itens, receitas e dependências
  • Validação de referências em tempo real contra o banco de dados do jogo

Geração Inteligente de Scripts

  • Geração baseada em templates usando padrões reais do jogo
  • Análise de balanceamento comparando itens personalizados aos equivalentes vanilla
  • Validação de referências garantindo que todas as dependências existam
  • Múltiplos formatos de saída (itens, receitas, scripts de reparo, sons, veículos)

Motor de Validação Avançado

  • Validação de sintaxe em tempo real com relatórios de erro detalhados
  • Verificação de referências para itens, sons e sprites
  • Análise de balanceamento com avaliação de impacto na jogabilidade
  • Sugestões de melhores práticas para o desenvolvimento de mods

Pronto para Implantação

  • Suporte a Cloudflare Workers para implantação serverless
  • Integração com D1 Database para armazenamento persistente
  • API HTTP para integração com qualquer cliente MCP
  • Compatível com Claude Desktop com exemplos de configuração

🔧 Instalação

Pré-requisitos

  • Node.js 18.0.0 ou superior
  • Gerenciador de pacotes npm ou yarn

Desenvolvimento 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

Implantação em 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

Com Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Com Cursor/VSCode

O servidor pode ser integrado a qualquer IDE que suporte o protocolo MCP:

  1. Instale a extensão MCP para o seu IDE
  2. Configure o endpoint do servidor
  3. Comece a usar as ferramentas de desenvolvimento de Project Zomboid

🛠️ Ferramentas MCP

search_vanilla

Pesquise conteúdo vanilla de Project Zomboid com correspondência inteligente.

Parâmetros:

  • query (string): Consulta de busca para conteúdo do jogo
  • type (string, opcional): Filtrar por tipo de conteúdo (item, receita, som, veículo)
  • category (string, opcional): Filtrar por categoria de item
  • limit (número, opcional): Máximo de resultados (padrão: 20)

Exemplo:

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

generate_script

Gere scripts equilibrados de Project Zomboid usando templates e dados do jogo.

Parâmetros:

  • type (string): Tipo de script (item, receita, receita_evoluida, reparo, som, veículo)
  • name (string): Nome do item/receita a ser gerado
  • properties (objeto): Propriedades e especificações
  • module (string, opcional): Nome do módulo (padrão: "Base")

Exemplo:

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

Valide a sintaxe e referências de scripts de Project Zomboid com relatórios de erro detalhados.

Parâmetros:

  • content (string): Conteúdo do script a validar
  • type (string, opcional): Tipo de script esperado
  • strict (booleano, opcional): Ativar modo de validação estrita

Exemplo:

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

check_references

Valide referências de itens, sons e sprites no banco de dados do jogo.

Parâmetros:

  • references (string[]): Lista de referências a validar
  • type (string, opcional): Tipo de referências (item, som, sprite, todas)

Exemplo:

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

analyze_mod

Análise abrangente do diretório de mods, incluindo validação de balanceamento, compatibilidade e estrutura.

Parâmetros:

  • modPath (string): Caminho para o diretório do mod
  • checkBalance (booleano, opcional): Realizar análise de balanceamento
  • checkCompatibility (booleano, opcional): Verificar compatibilidade com o vanilla
  • generateReport (booleano, opcional): Gerar relatório detalhado de análise

Exemplo:

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

parse_game_files

Analise e indexe os arquivos do jogo Project Zomboid para preencher o banco de dados.

Parâmetros:

  • gamePath (string, opcional): Caminho para a instalação de Project Zomboid (detectado automaticamente se não for informado)
  • forceReparse (booleano, opcional): Forçar nova análise mesmo que os dados já existam

Exemplo:

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

🏗️ Arquitetura

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

Componentes Principais

  • DatabaseManager: Banco de dados SQLite/D1 com recursos de busca em texto completo
  • ProjectZomboidParser: Análise de arquivos vanilla do jogo e diretórios de mods
  • ScriptGenerator: Geração de scripts equilibrados usando templates e dados do jogo
  • ValidationEngine: Validação de sintaxe e referências em tempo real
  • ModAnalyzer: Análise abrangente de mods e métricas de qualidade
  • PathManager: Detecção automática de instalações de Project Zomboid

🌐 Implantação em Cloudflare Workers

O servidor inclui suporte completo a Cloudflare Workers para implantação serverless:

Recursos

  • D1 Database para armazenamento persistente
  • Armazenamento KV para cache de dados acessados com frequência
  • Endpoints de API HTTP para todas as ferramentas MCP
  • Escalonamento automático sem cold starts
  • Implantação global de borda para baixa latência

Endpoints da API

  • GET /health - Verificação de integridade
  • GET /mcp/info - Capacidades do servidor
  • POST /tools/{toolName} - Executar ferramentas MCP
  • POST /admin/load-game-data - Carregar dados vanilla do jogo

Configuração

Atualize o wrangler.toml com os IDs do seu banco de dados:

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

📋 Fluxo de Trabalho de Desenvolvimento

Configurando o Desenvolvimento de Mods

  1. Inicializar o Banco de Dados:

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

  2. Analisar Arquivos do Jogo:

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

  3. Iniciar o Desenvolvimento:

    // 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 Arquivo Suportados

  • mod.info: Metadados e configuração do mod
  • Arquivos de Script (.txt): Itens, receitas, veículos, sons, scripts de reparo
  • Arquivos Lua (.lua): Lógica do jogo e manipuladores de eventos
  • Ativos: Texturas, sons, modelos e mapas

🔍 Exemplos

Criando uma 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'
});

Analisando a Qualidade de um 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(', ')}`);

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🆘 Suporte

  • GitHub Issues: Relatórios de bugs e solicitações de recursos
  • Documentação: Guias abrangentes e referências de API
  • Comunidade: Servidor Discord para desenvolvedores de mods

🔮 Roteiro

v1.1.0 - Recursos Aprimorados

  • Suporte a scripts de veículos com análise e geração completas
  • Templates avançados para cenários complexos de criação de mods
  • Integração de scripts Lua para assistência na lógica do jogo
  • Ferramentas de otimização de desempenho para mods grandes

v1.2.0 - Recursos de Colaboração

  • Suporte a múltiplos usuários para desenvolvimento de mods em equipe
  • Integração com controle de versão em fluxos de trabalho Git
  • Pipelines de testes automatizados para validação de mods
  • Geração de documentação a partir da análise de mods

v2.0.0 - Plataforma Completa

  • Interface web para usuários não técnicos
  • Integração com Steam Workshop para publicação direta
  • Recursos de marketplace para descoberta de mods
  • Suporte empresarial para grandes equipes de mods

Feito com ❤️ para a comunidade de mods de Project Zomboid