CloudNet MCP 서버

이 서버는 CloudNet Service REST API v3에 대한 인터페이스를 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이를 통해 AI 어시스턴트가 사용자의 CloudNet 노드와 서비스를 안전하고 정확하게 관찰할 수 있습니다.

주요 기능

• 노드 및 정보 가져오기: 모든 클러스터 노드를 나열하고 상세 통계를 가져옵니다.

• 서비스 관리: 활성 스마트 서비스 목록을 확인하고 서버 콘솔에서 명령을 원활하게 실행합니다.

• 플레이어 관리: 온라인 플레이어 조회, 플레이어 프로필 검사, 플레이어 추방, 메시지 전송 및 플레이어를 대신하여 명령 실행을 수행합니다.

• QQ 봇 모드: 안전한 명령 실행 기능을 갖춘 QQ 그룹 서버 관리 봇에 최적화되어 있습니다.

Related MCP server: Coolify MCP Server

사전 요구 사항

• Python 3.12+

• uv 패키지 관리자

설치

git clone https://github.com/yourusername/cloudnet-mcp.git
cd cloudnet-mcp
uv sync

구성

환경 변수

• CLOUDNET_URL: REST API URL (기본값: http://127.0.0.1:2812/api/v3)

• CLOUDNET_USER: 기본 인증 사용자 이름

• CLOUDNET_PASSWORD: 기본 인증 비밀번호

QQ 봇 모드 (선택 사항)

예제 설정을 복사하여 사용자 정의합니다:

cp config.example.yaml config.yaml

config.yaml에서 QQ 모드를 활성화합니다:

qq_mode:
  enabled: true
  safe_commands_only: true
  chinese_responses: true

실행

# Basic usage
uv run cloudnet-mcp

# With config file
uv run cloudnet-mcp -c config.yaml

명령줄 옵션

QQ 봇 모드

QQ 모드가 활성화되면 추가 도구를 사용할 수 있습니다:

안전한 명령 실행

명령은 권한 수준별로 구성됩니다:

• Guest (게스트): 쿼리 명령 (list, tps, seed 등)

• Admin (관리자): 관리 명령 (kick, ban, whitelist, gamemode 등)

• Super User (슈퍼 유저): 서버 명령 (stop, restart, reload 등)

권한 상속: 관리자는 게스트 권한을 상속받으며, 슈퍼 유저는 모든 권한을 상속받습니다.

사용자 정의 명령

config.yaml에 사용자 정의 명령을 추가합니다:

safe_commands:
  guest:
    - command: stats
      args: "<player>"
      description: "View player statistics"
  admin:
    - command: money
      args: "set <player> <amount>"
      description: "Set player balance"

사용자 정의 명령은 내장 명령과 병합됩니다. 동일한 명령 이름을 사용하여 내장 명령 설명을 재정의할 수 있습니다.

차단된 명령

다음 패턴은 항상 차단됩니다:

• op - 운영자 상태 부여

• deop - 운영자 상태 취소

• execute - 다른 엔티티로 실행

Claude Desktop과 함께 사용하기

claude_desktop_config.json에 다음을 추가합니다:

{
  "mcpServers": {
    "cloudnet": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH/TO/YOUR/cloudnet-mcp",
        "run",
        "cloudnet-mcp",
        "-c",
        "PATH/TO/YOUR/cloudnet-mcp/config.yaml"
      ],
      "env": {
        "CLOUDNET_URL": "http://127.0.0.1:2812/api/v3",
        "CLOUDNET_USER": "your_user",
        "CLOUDNET_PASSWORD": "your_password"
      }
    }
  }
}

CloudNet MCP 서버

이것은 CloudNet Service REST API v3에 대한 인터페이스 액세스 지원을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. AI 어시스턴트가 사용자의 CloudNet 노드와 서비스를 안전하고 정확하게 관찰할 수 있게 합니다.

기능 특성

• 노드 목록 및 정보 가져오기: 전체 CloudNet 클러스터 내 모든 노드의 상세 통계 데이터와 정보를 확인합니다.

• 서비스 관리: 실행 중인 스마트 서비스 목록을 가져오고, 서버 콘솔에서 원격으로 명령을 실행할 수 있습니다.

• 플레이어 관리: 온라인 플레이어 조회, 플레이어 상세 정보 확인, 플레이어 추방, 메시지 전송, 플레이어 대신 명령 실행을 수행합니다.

• QQ Bot 모드: QQ 그룹 서버 관리 봇을 위한 최적화 모드로, 안전한 명령 실행을 지원합니다.

사전 요구 사항

• Python 3.12 이상 버전

• uv 패키지 관리자

설치 가이드

git clone https://github.com/yourusername/cloudnet-mcp.git
cd cloudnet-mcp
uv sync

구성

환경 변수

• CLOUDNET_URL: CloudNet REST API 주소 (기본값: http://127.0.0.1:2812/api/v3)

• CLOUDNET_USER: 기본 인증 사용자 이름

• CLOUDNET_PASSWORD: 기본 인증 비밀번호

QQ Bot 모드 (선택 사항)

예제 설정 파일을 복사하여 수정합니다:

cp config.example.yaml config.yaml

config.yaml에서 QQ 모드를 활성화합니다:

qq_mode:
  enabled: true
  safe_commands_only: true
  chinese_responses: true

실행

# 基本用法
uv run cloudnet-mcp

# 使用配置文件
uv run cloudnet-mcp -c config.yaml

명령줄 매개변수

QQ Bot 모드

QQ 모드를 활성화하면 다음과 같은 추가 도구가 제공됩니다:

안전한 명령 실행

명령은 권한 수준별로 구성됩니다:

• Guest (게스트): 쿼리류 명령 (list, tps, seed 등)

• Admin (관리자): 관리류 명령 (kick, ban, whitelist, gamemode 등)

• Super User (슈퍼 유저): 서버 관리 명령 (stop, restart, reload 등)

권한 상속: 관리자는 게스트 권한을 상속받으며, 슈퍼 유저는 모든 권한을 상속받습니다.

내장 명령 목록

Guest 레벨 (11개):

• list - 온라인 플레이어 목록 확인

• tps - 서버 TPS 확인

• seed - 월드 시드 확인

• difficulty - 게임 난이도 확인

• whitelist list - 화이트리스트 목록 확인

• time query - 게임 시간 조회

• gamerule query - 게임 규칙 조회

• scoreboard objectives list - 스코어보드 목표 나열

• scoreboard players list - 스코어보드 플레이어 나열

• bossbar list - 보스바 나열

• trigger - 스코어보드 목표 트리거

Admin 레벨 (41개):

• kick <플레이어> [사유] - 플레이어 추방

• ban <플레이어> [사유] - 플레이어 차단

• pardon <플레이어> - 플레이어 차단 해제

• ban-ip <주소|플레이어> [사유] - IP 차단

• pardon-ip <주소> - IP 차단 해제

• whitelist add/remove <플레이어> - 화이트리스트 관리

• whitelist on/off/reload - 화이트리스트 켜기/끄기/재로드

• gamemode <모드> [플레이어] - 게임 모드 설정

• tp <엔티티|좌표> - 엔티티 텔레포트

• give <플레이어> <아이템> [수량] - 아이템 지급

• clear [플레이어] [아이템] [수량] - 아이템 제거

• effect <플레이어> give|clear - 효과 부여/제거

• enchant <플레이어> <마법부여> [레벨] - 아이템 마법부여

• summon <엔티티> [좌표] - 엔티티 소환

• kill [엔티티] - 엔티티 처치

• fill/setblock/clone - 블록 조작

• weather clear|rain|thunder - 날씨 설정

• time set <시간> - 게임 시간 설정

• 더 보기...

Super User 레벨 (16개):

• stop - 서버 정지

• restart - 서버 재시작

• reload - 데이터팩 재로드

• save-all/save-off/save-on - 저장 제어

• debug start|stop - 성능 분석 디버깅

• gamerule set <규칙> <값> - 게임 규칙 설정

• defaultgamemode <모드> - 기본 게임 모드 설정

• 더 보기...

사용자 정의 명령

config.yaml에 사용자 정의 명령을 추가합니다:

safe_commands:
  guest:
    - command: stats
      args: "<玩家>"
      description: "查看玩家统计"
    - command: ping
      description: "查看延迟"
  admin:
    - command: money
      args: "set <玩家> <金额>"
      description: "设置玩家余额"
    - command: heal
      args: "[玩家]"
      description: "治疗玩家"
  super_user:
    - command: plugins
      description: "查看插件列表"

사용자 정의 명령은 내장 명령과 병합됩니다. 동일한 명령 이름을 사용하면 내장 명령의 설명을 덮어쓸 수 있습니다.

차단된 명령

다음 명령 템플릿은 항상 차단됩니다:

• op - 관리자 권한 부여

• deop - 관리자 권한 취소

• execute - 다른 엔티티 권한으로 실행

Claude Desktop에서 사용하기

다음 설정을 claude_desktop_config.json에 추가하십시오:

{
  "mcpServers": {
    "cloudnet": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH/TO/YOUR/cloudnet-mcp",
        "run",
        "cloudnet-mcp",
        "-c",
        "PATH/TO/YOUR/cloudnet-mcp/config.yaml"
      ],
      "env": {
        "CLOUDNET_URL": "http://127.0.0.1:2812/api/v3",
        "CLOUDNET_USER": "您的用户名",
        "CLOUDNET_PASSWORD": "您的密码"
      }
    }
  }
}