README.md
Model Context Protocol Server for NetEase Minecraft ModSDK development
🎮 NetEase ModSDK MCP Server
Model Context Protocol Server for 我的世界中国版（网易）ModSDK 开发
为 AI 编程助手（Claude Desktop、Cursor、CodeMaker 等）提供 文档检索、代码生成、代码审查 能力，显著提升 NetEase ModSDK 开发效率。
✨ 核心能力
| 能力 | 说明 |
|---|---|
| 🔍 智能文档检索 | 模糊搜索、驼峰分词、中文搜索，覆盖 API 接口 & 事件文档 |
| 📝 代码生成 | 自动生成符合网易规范的 Mod 项目、Server/Client System、自定义物品/方块/实体 |
| 🔧 工具 & 武器生成 | 一键生成剑、镐、斧、锹、锄、弓、盔甲、食物、可投掷物品 JSON |
| 📋 配方 & 战利品表 | 生成有序/无序合成配方、熔炉配方、战利品表、生成规则 |
| 🔬 代码审查 | 检测 Python 2.7 兼容性、客户端/服务端混用、性能反模式 |
| 📚 组件百科 | 查询物品/方块/实体/网易特有组件的用法和配置 |
| ⚡ 最佳实践 | 内置官方性能优化规范，生成代码自动遵循 |
🚀 快速开始
前置要求
- Python ≥ 3.10
- pip（Python 包管理器）
1. 安装依赖
cd "D:/ModSDK MCP Server"
pip install -r requirements.txt
2. 选择你的 AI 客户端进行配置
🟢 Claude Desktop（推荐）
编辑配置文件：
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"ModSDK MCP Server": {
"command": "python",
"args": ["-m", "modsdk_mcp"],
"cwd": "D:/ModSDK MCP Server"
}
}
}
保存后重启 Claude Desktop。
🔵 Cursor / VS Code
在项目根目录创建 .cursor/mcp.json（Cursor）或 .vscode/mcp.json（VS Code）：
{
"servers": {
"ModSDK MCP Server": {
"command": "python",
"args": ["-m", "modsdk_mcp"],
"cwd": "D:/ModSDK MCP Server"
}
}
}
🟡 CodeMaker
在项目根目录创建 .mcp.json：
{
"servers": {
"ModSDK MCP Server": {
"command": "python",
"args": ["start_mcp.py"],
"cwd": "D:/ModSDK MCP Server"
}
}
}
说明: CodeMaker 不支持
python -m的cwd传参方式，因此使用start_mcp.py包装入口。
🔴 SSE 模式（远程 / Docker）
启动 SSE 服务：
python -m modsdk_mcp --sse
# 默认监听 http://0.0.0.0:8000
在客户端中配置：
{
"mcpServers": {
"ModSDK MCP Server": {
"transport": "sse",
"url": "http://localhost:8000/sse"
}
}
}
3. 验证连接
在 AI 助手中输入以下测试指令：
搜索 GetEngineCompFactory 的用法
如果返回了 API 文档内容，说明 MCP Server 已成功连接。
📖 MCP 工具一览
文档查询
| 工具 | 描述 |
|---|---|
search_docs |
搜索文档（支持模糊匹配、驼峰分词、中文） |
get_document |
获取指定文档完整内容 |
get_document_section |
获取文档指定章节 |
get_document_structure |
获取文档目录结构 |
list_documents |
列出所有可用文档 |
reload_documents |
重新加载文档索引 |
代码生成
| 工具 | 描述 |
|---|---|
generate_mod_project |
生成完整 Mod 项目模板（含入口、服务端、客户端） |
generate_server_system |
生成服务端系统代码 |
generate_client_system |
生成客户端系统代码 |
generate_event_listener |
生成事件监听器代码 |
generate_custom_command |
生成自定义命令代码 |
generate_custom_item |
生成自定义物品代码和 JSON |
generate_custom_block |
生成自定义方块代码和 JSON |
JSON 生成
| 工具 | 描述 |
|---|---|
generate_item_json |
生成物品 JSON（行为包 + 资源包） |
generate_block_json |
生成方块 JSON |
generate_recipe_json |
生成合成配方 JSON（有序/无序/熔炉） |
generate_entity_json |
生成实体 JSON（行为包 + 资源包） |
generate_loot_table_json |
生成战利品表 JSON |
generate_spawn_rules_json |
生成生成规则 JSON |
一键生成工具 & 武器
| 工具 | 描述 |
|---|---|
generate_sword_json |
自定义剑（伤害、耐久、附魔、修复） |
generate_pickaxe_json |
自定义镐（挖掘速度、耐久） |
generate_axe_json |
自定义斧（伤害、挖掘速度） |
generate_shovel_json |
自定义锹 |
generate_hoe_json |
自定义锄 |
generate_bow_json |
自定义弓（蓄力时间、耐久） |
generate_food_json |
自定义食物（饥饿值、饱和度、药水效果） |
generate_armor_json |
自定义盔甲（护甲值、槽位） |
generate_throwable_json |
自定义可投掷物品 |
代码审查 & 最佳实践
| 工具 | 描述 |
|---|---|
review_code |
审查代码（Python 2.7 兼容性、架构、性能） |
get_best_practices |
获取最佳实践规则 |
search_components |
搜索基岩版组件 |
get_component_details |
获取组件详细信息 |
list_components |
列出所有可用组件 |
list_modsdk_events |
列出常用事件 |
📂 项目结构
ModSDK MCP Server/
├── modsdk_mcp/ # MCP Server 核心模块
│ ├── __init__.py # 包标识
│ ├── __main__.py # python -m 入口
│ ├── server.py # MCP Server 主程序（工具注册、请求处理）
│ ├── docs_reader.py # 文档读取与搜索引擎
│ ├── knowledge_base.py # 组件知识库 & 最佳实践规则
│ └── templates.py # 代码模板 & JSON 生成器
├── docs/ # ModSDK 官方文档（Markdown）
│ ├── 接口/ # API 接口文档
│ ├── 事件/ # 事件文档
│ ├── 枚举值/ # 枚举值文档
│ └── 更新信息/ # 版本更新日志
├── standard/ # 官方开发规范文档
├── skills/ # Claude Skills 文件
├── start_mcp.py # CodeMaker 专用启动入口
├── .mcp.json # CodeMaker MCP 配置
├── requirements.txt # Python 依赖
├── Dockerfile # Docker 镜像配置
├── docker-compose.yml # Docker Compose 配置
├── DEPLOYMENT.md # 详细部署指南
└── README.md # 本文件
⚙️ 环境变量
| 变量名 | 说明 | 默认值 | |--------|------|
Tools (5)
search_docsSearch documentation using fuzzy matching, camelCase tokenization, and Chinese support.generate_mod_projectGenerate a complete Mod project template including entry, server, and client files.generate_custom_itemGenerate custom item code and JSON configuration.review_codeReview code for Python 2.7 compatibility, architecture, and performance issues.generate_recipe_jsonGenerate synthesis recipe JSON for ordered, unordered, or furnace recipes.Configuration
claude_desktop_config.json
{"mcpServers": {"ModSDK MCP Server": {"command": "python", "args": ["-m", "modsdk_mcp"], "cwd": "D:/ModSDK MCP Server"}}}Try it
→Search for the usage of GetEngineCompFactory in the ModSDK documentation.
→Generate a new custom sword item with specific damage and durability values.
→Review my current Python script for any performance anti-patterns or Python 2.7 compatibility issues.
→Create a new furnace recipe JSON for smelting iron ore into iron ingots.
→Generate a basic server system template for my new Minecraft Mod project.