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 para el desarrollo de ModSDK de Minecraft China (NetEase)

Proporciona a los asistentes de programación con IA guía de desarrollo versionada, búsqueda de documentación oficial, generación de artefactos y validación unificada para ModSDK 3.9 / BE 1.21.120. Funciona completamente sin conexión; solo lee las instantáneas del repositorio.

✨ Capacidades principales

Capacidad

Descripción

🔍 Búsqueda inteligente de documentación

Búsqueda difusa, segmentación camelCase, búsqueda en chino; cubre API e documentación de eventos

📝 Generación de código

Genera automáticamente proyectos Mod, Server/Client System, ítems/bloques/entidades personalizados conforme a las normas de NetEase

🔧 Generación de herramientas y armas

Genera con un clic JSON de espadas, picos, hachas, palas, azadas, arcos, armaduras, alimentos y objetos arrojables

📋 Recetas y tablas de botín

Genera recetas de fabricación ordenadas/desordenadas, recetas de horno, tablas de botín y reglas de aparición

🔬 Revisión de código

Detecta compatibilidad con Python 2.7, uso mixto cliente/servidor y antipatrones de rendimiento

🧭 Guía versionada

Selecciona reglas según objetivo, dominio y lado, y devuelve el nivel de fuente y los límites de evidencia de 3.9

📚 Enciclopedia de componentes

Consulta el uso y la configuración de componentes de ítems/bloques/entidades y componentes exclusivos de NetEase

⚡ Mejores prácticas

Proyecta reglas oficiales, estrategias MCP y recomendaciones de ingeniería con límites desde el registro versionado

Related MCP server: MCP SpecNavigator

🚀 Inicio rápido

Requisitos previos

  • Python ≥ 3.10

  • pip (gestor de paquetes de Python)

1. Instalar dependencias

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

2. Elige tu cliente de IA y configúralo

Nota general: todos los clientes usan la ruta absoluta de start_mcp.py para iniciar, sin necesidad del parámetro cwd; es la opción más compatible. Reemplaza <PROJECT_ROOT> en los ejemplos siguientes con la raíz de tu proyecto en tu máquina.

Edita el archivo de configuración:

  • 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"]
    }
  }
}

Guarda y reinicia Claude Desktop.

Claude Code no admite el parámetro cwd; usa la ruta absoluta de start_mcp.py:

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

O edita manualmente ~/.claude/settings.json:

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

Crea .cursor/mcp.json (Cursor) o .vscode/mcp.json (VS Code) en la raíz del proyecto:

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

⚠️ Problema común (VS Code / Cursor)

Si al iniciar MCP en VS Code o Cursor aparece el siguiente error:

Error: tool parameters array type must have items

Causa:

En el esquema de parámetros de la herramienta MCP, algunos campos se declaran como "type": "array" pero no incluyen el campo "items".

Según la especificación JSON Schema, todos los tipos de matriz deben definir "items"; de lo contrario, en entornos de validación estricta (como VS Code / Cursor) se producirá un error.

Solución:

Modifica la definición de parámetros de la herramienta correspondiente, por ejemplo:

❌ Escritura incorrecta:

{
  "type": "array"
}

✅ Escritura correcta:

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

Inicia el servicio SSE:

python "<PROJECT_ROOT>/start_mcp.py" --sse
# 默认监听 http://0.0.0.0:8000

Configúralo en el cliente:

{
  "mcpServers": {
    "modsdk-mcp-server": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

3. Verificar la conexión

Introduce la siguiente instrucción de prueba en el asistente de IA:

搜索 GetEngineCompFactory 的用法

Si devuelve contenido de la documentación de la API, el MCP Server se ha conectado correctamente.

📖 Resumen de herramientas MCP

Consulta de documentación

Herramienta

Descripción

search_docs

Busca documentación (admite coincidencia difusa, segmentación camelCase y chino)

search_api

Busca el índice estructurado de API/eventos

get_api_detail

Lee la firma, notas, ejemplos y metadatos de origen de API/eventos con el mismo nombre en múltiples lados

get_document

Obtiene el contenido completo de un documento especificado

get_document_section

Obtiene una sección específica de un documento

get_document_structure

Obtiene la estructura del índice de un documento

list_documents

Lista todos los documentos disponibles

reload_documents

Recarga el índice de documentos

get_development_guidance

Devuelve las reglas y sugerencias de validación más relevantes según objetivo, dominio, lado y versión

Generación de código

Herramienta

Descripción

generate_mod_project

Genera una plantilla completa de proyecto Mod (incluye entrada, servidor y cliente)

generate_server_system

Genera código de sistema de servidor

generate_client_system

Genera código de sistema de cliente

generate_event_listener

Genera código de listener de eventos

generate_custom_command

Genera código de comandos personalizados

generate_custom_item

Genera código y JSON de ítems personalizados

generate_custom_block

Genera código y JSON de bloques personalizados

Generación de JSON

Herramienta

Descripción

generate_item_json

Genera JSON de ítems (paquete de comportamiento + paquete de recursos)

generate_block_json

Genera JSON de bloques

generate_recipe_json

Genera JSON de recetas de fabricación (ordenadas/desordenadas/horno)

generate_entity_json

Genera JSON de entidades (paquete de comportamiento + paquete de recursos)

generate_loot_table_json

Genera JSON de tablas de botín

generate_spawn_rules_json

Genera JSON de reglas de aparición

Generación con un clic de herramientas y armas

Herramienta

Descripción

generate_sword_json

Espada personalizada (daño, durabilidad, encantamientos, reparación)

generate_pickaxe_json

Pico personalizado (velocidad de excavación, durabilidad)

generate_axe_json

Hacha personalizada (daño, velocidad de excavación)

generate_shovel_json

Pala personalizada

generate_hoe_json

Azada personalizada

generate_bow_json

Arco personalizado (tiempo de carga, durabilidad)

generate_food_json

Alimento personalizado (valor de hambre, saturación, efectos de poción)

generate_armor_json

Armadura personalizada (valor de armadura, ranuras)

generate_throwable_json

Objeto arrojable personalizado

Revisión de código y mejores prácticas

Herramienta

Descripción

review_code

Revisa de forma unificada artefactos Python/JSON pasados explícitamente

get_best_practices

Proyección de compatibilidad heredada de las reglas del registro

search_components

Busca componentes de Bedrock

get_component_details

Obtiene información detallada de un componente

list_components

Lista todos los componentes disponibles

get_architecture_pattern

Obtiene y valida ejemplos de arquitectura central

📂 Estructura del proyecto

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                       # 本文件

⚙️ Variables de entorno

Nombre de variable

Descripción

Valor predeterminado

MODSDK_DOCS_PATH

Ruta del directorio de documentación ModSDK

./docs

MCP_HOST

Dirección de escucha en modo SSE

0.0.0.0

MCP_PORT

Puerto de escucha en modo SSE

8000

🎯 Normas de código integradas

Los generadores del MCP Server pasan por una validación unificada consciente de la estructura. Solo las violaciones graves demostrables y los prefijos de cadena explícitamente prohibidos por el proyecto bloquean; las sugerencias de rendimiento, JSON UI y ciclo de vida de ingeniería generan advertencias o requieren confirmación manual por defecto.

Norma

Descripción

Separación cliente/servidor

ServerSystem tiene prohibido importar clientApi, y viceversa

Compatibilidad con Python 2.7

Prohibidos los prefijos reales de cadena u/U/ur/ru y la sintaxis exclusiva de Python 3; los archivos deben incluir declaración UTF-8

Lista blanca de imports precisa

Usa las 456 instantáneas oficiales del repositorio; los módulos del proyecto deben declararse explícitamente

Advertencia de rendimiento contextual

Solo sugiere spam, creación repetida o reducción de frecuencia cuando el contexto de bucle, Tick o eventos de alta frecuencia lo justifica

Comunicación punto a punto

Prioriza NotifyToClient; usa BroadcastToAllClient con precaución

Formatos JSON

Ítems básicos 1.10; bloques admiten legacy_1_10, scalar_1_16, modern_1_19_20

standard/registry/ es la única fuente de normas. Prioriza get_development_guidance; get_best_practices solo conserva la proyección de compatibilidad.

📝 Ejemplos de uso

Generar un proyecto Mod

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

Generar una espada de diamante personalizada

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

Revisión de código

帮我审查这段代码：

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

Consultar el uso de un componente

搜索 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