Skip to main content
Glama
deenesjakoruzh
MCNeteaseDevs

NetEase ModSDK MCP Server

by MCNeteaseDevs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

🎮 NetEase ModSDK MCP Server

마인크래프트 중국판(NetEase) ModSDK 개발을 위한 Model Context Protocol Server

AI 프로그래밍 어시스턴트에게 ModSDK 3.9 / BE 1.21.120의 버전별 개발 가이드, 공식 문서 검색, 산출물 생성 및 통합 검증을 제공합니다. 런타임은 완전히 오프라인이며, 저장소 내 스냅샷만 읽습니다.

✨ 핵심 기능

기능

설명

🔍 스마트 문서 검색

퍼지 검색, 카멜케이스 분할, 중국어 검색 지원, API 인터페이스 & 이벤트 문서 포함

📝 코드 생성

NetEase 규범에 맞는 Mod 프로젝트, Server/Client System, 커스텀 아이템/블록/엔티티 자동 생성

🔧 도구 & 무기 생성

검, 곡괭이, 도끼, 삽, 괭이, 활, 갑옷, 음식, 투척 가능 아이템 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)

VS Code 또는 Cursor에서 MCP를 시작할 때 다음 오류가 발생하는 경우:

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

문서 검색(퍼지 매칭, 카멜케이스 분할, 중국어 지원)

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

베드락 에디션 컴포넌트 검색

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 import 금지, 그 반대도 동일

Python 2.7 호환

실제 u/U/ur/ru 문자열 접두사 및 Python 3 전용 문법 금지, 파일에 UTF-8 선언 포함

정확한 import 화이트리스트

저장소 내 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