NetEase ModSDK MCP Server

🎮 NetEase ModSDK MCP Server

Model Context Protocol Server for 我的世界中国版（网易）ModSDK 开发

为 AI 编程助手（Claude Desktop、Cursor 等）提供 文档检索、代码生成、代码审查 能力，显著提升 NetEase ModSDK 开发效率。

✨ 核心能力

🚀 快速开始

前置要求

• Python ≥ 3.10
• pip（Python 包管理器）

1. 安装依赖

cd "D:/ModSDK MCP Server"
pip install -r requirements.txt

2. 选择你的 AI 客户端进行配置

通用说明：所有客户端统一使用 start_mcp.py 绝对路径启动，无需 cwd 参数，兼容性最好。 请将下方示例中的 D:/ModSDK MCP Server 替换为你的实际安装路径。

🟢 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": ["D:/ModSDK MCP Server/start_mcp.py"]
    }
  }
}

保存后重启 Claude Desktop。

🟣 Claude Code（CLI）

Claude Code 不支持 cwd 参数，使用 start_mcp.py 绝对路径即可：

claude mcp add "modsdk-mcp-server" -- python "D:/ModSDK MCP Server/start_mcp.py"

或手动编辑 ~/.claude/settings.json：

{
  "mcpServers": {
    "modsdk-mcp-server": {
      "command": "python",
      "args": ["D:/ModSDK MCP Server/start_mcp.py"]
    }
  }
}

🔵 Cursor / VS Code

在项目根目录创建 .cursor/mcp.json（Cursor）或 .vscode/mcp.json（VS Code）：

{
  "servers": {
    "modsdk-mcp-server": {
      "command": "python",
      "args": ["D:/ModSDK MCP Server/start_mcp.py"]
    }
  }
}

⚠️ 常见问题（VS Code / Cursor） 如果在 VS Code 或 Cursor 中启动 MCP 时出现以下错误： `` Error: tool parameters array type must have items ` **原因：** MCP 工具的参数 schema 中，某些字段声明为 "type": "array"，但没有提供 "items" 字段。 根据 JSON Schema 规范，所有数组类型必须定义 "items"，否则在严格校验环境（如 VS Code / Cursor）中会报错。 **解决方法：** 修改对应工具的参数定义，例如： ❌ 错误写法： `json { "type": "array" } ` ✅ 正确写法： `json { "type": "array", "items": { "type": "object" } } ``

🔴 SSE 模式（远程 / Docker）

启动 SSE 服务：

python "D:/ModSDK MCP Server/start_mcp.py" --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 工具一览

文档查询

代码生成

JSON 生成

一键生成工具 & 武器

代码审查 & 最佳实践

📂 项目结构

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                    # Agent专用启动入口
├── .mcp.json                       # MCP 配置
├── requirements.txt                # Python 依赖
├── Dockerfile                      # Docker 镜像配置
├── docker-compose.yml              # Docker Compose 配置
├── DEPLOYMENT.md                   # 详细部署指南
└── README.md                       # 本文件

⚙️ 环境变量

🎯 内置代码规范

MCP Server 生成的所有代码 自动遵循 以下网易 ModSDK 强制规范：

📚 完整规范见 standard/ 目录或通过 get_best_practices 工具查询。

📝 使用示例

生成 Mod 项目

帮我创建一个名为"传送系统"的 Mod，ID 为 teleport_sys，功能是让玩家通过命令传送到指定位置

生成自定义钻石剑

帮我生成一把自定义钻石剑，命名空间 mymod，ID 为 diamond_blade，攻击力 10，耐久 500

代码审查

帮我审查这段代码：

def OnTick(self):
    import mod.server.extraServerApi as serverApi
    comp = serverApi.GetEngineCompFactory().CreatePos(self.playerId)
    pos = comp.GetPos()

查询组件用法

搜索 minecraft:food 组件的详细用法