Skip to main content
Glama
deenesjakoruzh
MCNeteaseDevs

NetEase ModSDK MCP Server

by MCNeteaseDevs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

🎮 NetEase ModSDK MCP Server

Model Context Protocol Server для разработки ModSDK в Minecraft China Edition (NetEase)

Предоставляет AI-ассистентам для программирования версионированные рекомендации по разработке, поиск официальной документации, генерацию артефактов и унифицированную проверку для ModSDK 3.9 / BE 1.21.120. Полностью офлайн во время выполнения — читает только снимки из репозитория.

✨ Ключевые возможности

Возможность

Описание

🔍 Умный поиск по документации

Нечёткий поиск, сегментация по CamelCase, поиск на китайском — покрывает API-интерфейсы и документацию по событиям

📝 Генерация кода

Автоматическая генерация Mod-проектов, Server/Client System, пользовательских предметов/блоков/сущностей в соответствии со стандартами NetEase

🔧 Генерация инструментов и оружия

Генерация JSON одним кликом: меч, кирка, топор, лопата, мотыга, лук, броня, еда, метательные предметы

📋 Рецепты и таблицы добычи

Генерация упорядоченных/неупорядоченных рецептов крафта, печных рецептов, таблиц добычи, правил спавна

🔬 Ревью кода

Проверка совместимости с Python 2.7, смешивания клиент/сервер, анти-паттернов производительности

🧭 Версионированные рекомендации

Выбор правил по цели, области и стороне, с указанием уровня источника и границ доказательств для 3.9

📚 Энциклопедия компонентов

Запрос использования и конфигурации предметов/блоков/сущностей/уникальных компонентов NetEase

⚡ Лучшие практики

Проекция официальных правил, MCP-стратегий и инженерных рекомендаций с границами из версионированного реестра

Related MCP server: MCP SpecNavigator

🚀 Быстрый старт

Предварительные требования

  • Python ≥ 3.10

  • pip (менеджер пакетов Python)

1. Установка зависимостей

cd "<PROJECT_ROOT>"
pip install -r requirements.txt

2. Выберите свой AI-клиент для настройки

Общее примечание: все клиенты запускаются с абсолютным путём к start_mcp.py, параметр cwd не требуется — максимальная совместимость. Замените <PROJECT_ROOT> в примерах ниже на корневой каталог вашего проекта.

Отредактируйте файл конфигурации:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "modsdk-mcp-server": {
      "command": "python",
      "args": ["<PROJECT_ROOT>/start_mcp.py"]
    }
  }
}

После сохранения перезапустите Claude Desktop.

Claude Code не поддерживает параметр cwd, используйте абсолютный путь к start_mcp.py:

claude mcp add "modsdk-mcp-server" -- python "<PROJECT_ROOT>/start_mcp.py"

Или вручную отредактируйте ~/.claude/settings.json:

{
  "mcpServers": {
    "modsdk-mcp-server": {
      "command": "python",
      "args": ["<PROJECT_ROOT>/start_mcp.py"]
    }
  }
}

Создайте .cursor/mcp.json (Cursor) или .vscode/mcp.json (VS Code) в корне проекта:

{
  "servers": {
    "modsdk-mcp-server": {
      "command": "python",
      "args": ["<PROJECT_ROOT>/start_mcp.py"]
    }
  }
}

⚠️ Частая проблема (VS Code / Cursor)

Если при запуске MCP в VS Code или Cursor возникает следующая ошибка:

Error: tool parameters array type must have items

Причина:

В схеме параметров инструментов MCP некоторые поля объявлены как "type": "array", но не содержат поле "items".

Согласно спецификации JSON Schema, для всех типов массивов обязательно определение "items", иначе в средах со строгой валидацией (например, VS Code / Cursor) возникнет ошибка.

Решение:

Измените определение параметров соответствующего инструмента, например:

❌ Неправильно:

{
  "type": "array"
}

✅ Правильно:

{
  "type": "array",
  "items": {
    "type": "object"
  }
}

Запустите SSE-сервис:

python "<PROJECT_ROOT>/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

Поиск по документации

Инструмент

Описание

search_docs

Поиск по документации (нечёткое совпадение, сегментация CamelCase, китайский)

search_api

Поиск по структурированному индексу API/событий

get_api_detail

Чтение сигнатур, примечаний, примеров и метаданных источника для одноимённых API/событий на разных сторонах

get_document

Получение полного содержимого указанного документа

get_document_section

Получение указанного раздела документа

get_document_structure

Получение структуры оглавления документа

list_documents

Список всех доступных документов

reload_documents

Перезагрузка индекса документов

get_development_guidance

Возврат наиболее релевантных правил и рекомендаций по проверке по цели, области, стороне и версии

Генерация кода

Инструмент

Описание

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

get_best_practices

Обратно совместимая проекция правил реестра

search_components

Поиск компонентов Bedrock Edition

get_component_details

Получение подробной информации о компоненте

list_components

Список всех доступных компонентов

get_architecture_pattern

Получение и проверка примеров ключевой архитектуры

📂 Структура проекта

ModSDK MCP Server/
├── modsdk_mcp/                     # MCP Server 核心模块
│   ├── __init__.py                 # 包标识
│   ├── __main__.py                 # python -m 入口
│   ├── server.py                   # MCP Server 主程序（工具注册、请求处理）
│   ├── docs_reader.py              # 文档读取与搜索引擎
│   ├── standards.py                # 严格加载版本化规范注册表
│   ├── guidance.py                 # 规则筛选与稳定 guidance JSON
│   ├── validation.py               # Python/JSON 统一产物校验
│   ├── knowledge_base.py           # 组件知识库 & 最佳实践兼容投影
│   └── templates.py                # 代码模板 & JSON 生成器
├── docs/                           # ModSDK 官方文档（Markdown）
│   ├── 接口/                       #   API 接口文档
│   ├── 事件/                       #   事件文档
│   ├── 枚举值/                     #   枚举值文档
│   └── 更新信息/                   #   版本更新日志
├── standard/registry/              # 唯一规范源、版本配置与白名单快照
├── skills/                         # 兼容说明；不作为运行时规范源
├── start_mcp.py                    # Agent专用启动入口
├── .mcp.json                       # MCP 配置
├── requirements.txt                # Python 依赖
├── Dockerfile                      # Docker 镜像配置
├── docker-compose.yml              # Docker Compose 配置
├── DEPLOYMENT.md                   # 详细部署指南
└── README.md                       # 本文件

⚙️ Переменные окружения

Имя переменной

Описание

Значение по умолчанию

MODSDK_DOCS_PATH

Путь к каталогу документации ModSDK

./docs

MCP_HOST

Адрес прослушивания в режиме SSE

0.0.0.0

MCP_PORT

Порт прослушивания в режиме SSE

8000

🎯 Встроенные стандарты кода

Генераторы MCP Server проходят унифицированную проверку с учётом структуры. Блокируются только серьёзные нарушения, которые можно достоверно доказать, и строковые префиксы, явно запрещённые проектом; рекомендации по производительности, JSON UI и жизненному циклу по умолчанию выводятся как предупреждения или требуют ручного подтверждения.

Стандарт

Описание

Разделение клиент/сервер

ServerSystem запрещено импортировать clientApi, и наоборот

Совместимость с Python 2.7

Запрещены реальные префиксы строк u/U/ur/ru и синтаксис, специфичный для Python 3; файлы содержат объявление UTF-8

Точный белый список импортов

Используются 456 официальных снимков из репозитория; модули проекта должны быть явно объявлены

Предупреждения о производительности в контексте

Предупреждения о спаме, повторном создании или снижении частоты — только при достаточном контексте циклов, Tick или высокочастотных событий

Связь точка-точка

Приоритет NotifyToClient, осторожное использование BroadcastToAllClient

Форматы JSON

Базовые предметы 1.10; блоки поддерживают legacy_1_10, scalar_1_16, modern_1_19_20

standard/registry/ — единственный источник стандартов. Приоритетно используйте get_development_guidance; 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 组件的详细用法

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers