pzMCP (Wink)

Zomboid MCP服务器项目

为Project Zomboid mod开发提供智能脚本验证、生成和上下文辅助

*使用AI增强工具改变您的建模工作流程*

🚀 概述

Zomboid MCP服务器项目是一个全面的 模型上下文协议 这款服务器彻底改变了Zomboid项目的模组开发。它通过人工智能增强的工具提供智能脚本验证、生成和上下文辅助，使所有技能水平的开发人员都可以访问建模。

✨ 主要特点

• 🔍 2700多种香草类商品 -具有全文搜索功能的完整可搜索数据库
• 🎯 智能自动检测 -自动查找您的Project Zomboid安装
• ⚡ 闪电快速设置 -使用uv包管理器安装一个命令
• 🤖 Claude桌面集成 -无缝AI辅助开发
• ✅ 实时验证 -语法检查和引用验证
• 🛠️ 脚本生成 -基于模板的创建，具有平衡的统计数据
• 🔧 WSL兼容 -非常适合Windows开发人员

🎮 它做什么

改变您的改装体验：

"Use the Project Zomboid MCP to find me a crowbar"
→ Returns: Crowbar item with damage: 1.0, durability: 10, categories: Blunt;Improvised

"Create a steel katana with 2.5 damage and high durability"  
→ Generates: Complete Project Zomboid script with balanced stats

"Validate this script for syntax errors"
→ Analyzes: Line-by-line validation with specific error locations

🚀 快速开始

Windows用户（WSL推荐）

# Install WSL (PowerShell as admin)
wsl --install

# Clone and setup (in WSL Ubuntu terminal)
git clone https://github.com/your-username/pzmcp.git
cd pzmcp
curl -LsSf https://astral.sh/uv/install.sh | sh && source ~/.bashrc
uv sync && uv run python -c "from mcp_server.core.enhanced_data_extractor import extract_with_path_manager; extract_with_path_manager(comprehensive=True)"

📖 完整的设置指南： WINDOWS_SETUP.md | 🤖 克劳德整合： CLAUDE_DESKTOP_INTEGRATION.md

Linux/macOS用户

git clone https://github.com/your-username/pzmcp.git && cd pzmcp
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync && uv run python -c "from mcp_server.core.enhanced_data_extractor import extract_with_path_manager; extract_with_path_manager(comprehensive=True)"

🔧 使用示例

使用克劳德桌面（推荐）

配置后，只需与Claude聊天：

"Use the Project Zomboid MCP to find me a crowbar"
"Create a steel katana with 2.5 damage and high durability"  
"Validate this Project Zomboid script for syntax errors"

命令行接口

# Search items directly
uv run python -c "import sqlite3; conn = sqlite3.connect('mcp_data.db'); cursor = conn.cursor(); cursor.execute('SELECT item_name, display_name FROM items_fts WHERE display_name MATCH \"baseball bat\"'); [print(f'{item[0]}: {item[1]}') for item in cursor.fetchall()]"

# Run MCP server for testing
uv run python run_server.py

🏗️ 建筑

┌─────────────────────────────────────────────────────┐
│                MCP Server Core                      │
├─────────────────────────────────────────────────────┤
│  Path Manager  │  Enhanced Parser  │  Script Gen    │
├─────────────────────────────────────────────────────┤
│          SQLite FTS5 Database Layer                 │
├─────────────────────────────────────────────────────┤
│  Game Data     │  Templates       │  Validation     │
│  (2,700+ items)│  (JSON-based)   │  (Real-time)    │
└─────────────────────────────────────────────────────┘

数据管道

Project Zomboid Installation
        ↓
Path Manager (Auto-detection)
        ↓  
Enhanced Data Extractor
        ↓
SQLite FTS5 Database
        ↓
MCP Tools & Claude Integration

🛠️ MCP工具可用

与Claude Desktop集成后，您可以访问：

🎯 真实世界的例子

项目研究

User: "Find me all the different types of axes in Project Zomboid"
Claude: Using the Project Zomboid MCP to search for axes...
→ Returns: HandAxe, WoodAxe, AxeStone, FireAxe with full stats

平衡脚本创建

User: "Create a reinforced crowbar that's better than normal but not overpowered"
Claude: Analyzing vanilla crowbar stats and generating balanced alternative...
→ Creates: Complete item script with appropriate damage/durability increases

配方开发

User: "Make a recipe to craft the reinforced crowbar using a normal crowbar and steel"
Claude: Generating craftRecipe with proper skill requirements...
→ Produces: Balanced recipe requiring Metalworking skill and appropriate materials

📁 项目结构

pzmcp/
├── mcp_server/           # Core MCP server implementation
│   ├── core/            # Database, extraction, path management
│   ├── parsers/         # Script parsers for items/recipes/vehicles
│   └── templates/       # JSON templates for script generation
├── media/scripts/       # Project Zomboid script files (copied)
├── docs/               # Documentation and guides
│   ├── WINDOWS_SETUP.md
│   ├── CLAUDE_DESKTOP_INTEGRATION.md
│   └── CHANGELOG.md
├── pz_path_manager.py  # Smart PZ installation detection
├── pyproject.toml      # Modern Python packaging
└── README.md          # This file

⚡ 演出

• 🚀 快10-100倍 使用uv进行依赖性管理
• ⚡ 亚秒级搜索 2700多种商品
• 💾 高效存储 使用SQLite FTS5
• 🔄 自动检测 Zomboid项目安装
• 📱 轻量级 -在普通硬件上工作

🔧 高级配置

自定义项目Zomboid路径

# Add custom installation path
uv run python pz_path_manager.py --add "my_pz" "C:\Custom\ProjectZomboid\media\scripts" 1

多个环境

为开发版和生产版模组配置不同的Claude Desktop环境。

调试模式

# Run with debug logging
uv run python run_server.py --debug

🤝 贡献

我们欢迎捐款！以下是如何开始：

1. 分叉存储库
2. 创建要素分支: git checkout -b feature/amazing-feature
3. 进行更改 并添加测试
4. 运行门楣: uv run ruff check .
5. 提交拉取请求

开发设置

git clone https://github.com/your-username/pzmcp.git
cd pzmcp
uv sync --dev  # Install with development dependencies
uv run pytest  # Run tests

📚 文档

• Windows安装指南 -完成WSL安装和配置
• Claude桌面集成 -AI助手设置
• 更新日志 -版本历史和功能
• 珠江三角洲 -产品要求和架构

🐛 故障排除

常见问题

MCP服务器无法启动？

• 检查WSL是否已安装并正在运行
• 验证Claude Desktop配置中的路径
• 确保数据库已填充

数据库为空？

• 运行数据提取： uv run python -c "from mcp_server.core.enhanced_data_extractor import extract_with_path_manager; extract_with_path_manager()"
• 检查Project Zomboid安装路径

克劳德桌面无法连接？

• 配置更改后完全重新启动Claude Desktop
• 检查MCP配置中的JSON语法
• 验证WSL路径是否正确

获得帮助

• GitHub问题：Bug报告和功能请求
• 文档：设置和使用的综合指南
• 社区：用于Project Zomboid改装的Discord服务器

📜 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 独立石 -创建Zomboid项目并使其可修改
• Anthropic -对于Claude和MCP协议
• Zomboid Modding社区项目 -寻求灵感和反馈
• 贡献者 -所有帮助改进此工具的人

🚀 路线图

v0.3.0-高级功能

• 完整的车辆脚本支持
• 先进的模板系统
• Lua脚本集成
• 性能优化工具

v1.0.0-生产就绪

• 面向非技术用户的GUI界面
• 蒸汽车间集成
• 自动化测试管道
• 为mod团队提供企业支持

______________________________________________________________________

立即转换您的Project Zomboid改装工作流程！

📖 安装指南 • 🤖 克劳德集成 • 📋 更新日志

*由以下材料制成❤️ Zomboid项目改装社区*