skript-mcp

Skript MCP

이 프로젝트는 영구적으로 실행되는 Paper 서버를 기반으로 하는 작은 MCP 서버를 제공합니다. Paper, Skript 및 설치된 애드온이 파서 역할을 합니다. Python 코드는 Skript 구문 자체를 이해하려고 시도하지 않습니다.

기본 이미지에는 다음 호환성 프로필이 포함되어 있습니다:

이미지 빌드 중에 다운로드된 모든 jar 파일이 확인됩니다. 다른 공식 프로필을 사용하려면 .env에서 관련된 모든 URL과 체크섬을 함께 재정의하십시오. 전체 세트를 확인하지 않고 애드온 하나만 업데이트하지 마십시오.

Skript 2.14.3은 1.21.4 프로필을 위해 의도적으로 사용되었습니다. SkBee 3.16.1은 Minecraft 1.21.4용 마지막 SkBee 릴리스이며, 최신 Skript 2.15/2.16 릴리스는 Adventure audience 타입 등록과 충돌합니다. 최신 Skript를 사용하려면 전체 프로필을 최신 Minecraft 및 SkBee 릴리스로 이동해야 합니다.

Paper 시작

설정 스크립트를 실행합니다. Docker 및 uv를 확인하고, 무작위 RCON 비밀번호로 .env를 생성하며, 종속성을 설치하고, Paper를 빌드하고, RCON을 확인합니다:

./setup.sh

수동 설정의 경우 로컬 환경 파일을 생성하고 비밀번호를 문자, 숫자, 점, 밑줄 또는 하이픈만 포함하는 긴 무작위 값으로 바꾸십시오:

cp .env.example .env
docker compose build
docker compose up -d --wait

.env에서 PUID와 PGID를 id -u 및 id -g의 출력 값으로 설정하십시오. 기본값은 1000이며, Paper가 호스트가 생성한 mode-0600 임시 파일을 읽을 수 있도록 합니다.

Paper 로그는 runtime/logs에 마운트됩니다. 호스트 스크립트는 scripts에서 /server/plugins/Skript/scripts에 직접 마운트됩니다. 월드 및 플러그인 생성 데이터는 폐기 가능한 컨테이너 상태로 유지됩니다. RCON만 게시되며, 127.0.0.1:25575에 바인딩됩니다. 게임플레이 포트는 게시되지 않습니다.

시작 및 플러그인 버전을 확인하려면:

docker compose logs paper
docker compose exec paper sh -c 'nc -z 127.0.0.1 25575'

MCP 서버 실행

uv로 설치하고 실행합니다:

uv sync
uv run --env-file .env skript-mcp

MCP 프로세스는 다음 환경 변수를 읽습니다:

OpenCode의 경우 로컬 MCP 항목을 추가하고 환경을 통해 동일한 RCON 비밀번호를 전달합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "skript": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/absolute/path/to/skript-mcp", "--env-file", "/absolute/path/to/skript-mcp/.env", "skript-mcp"],
      "enabled": true,
      "environment": {}
    }
  }
}

구성을 변경한 후 OpenCode를 다시 시작하십시오.

도구

• skript_check_file(path)는 경로로 기존 .sk 파일의 유효성을 검사합니다. 상대 경로는 SKRIPT_SCRIPTS_DIR 아래에서 확인됩니다. 절대 경로는 해당 디렉터리 내부를 가리키는 경우 허용됩니다. 함수 및 다른 형제 스크립트의 공유 정의를 사용할 수 있도록 전체 스크립트 세트를 다시 로드합니다.

• skript_reload_file(path)는 SKRIPT_SCRIPTS_DIR 내부의 기존 경로 하나를 해당 형제 스크립트를 다시 로드하지 않고 다시 로드합니다.

• minecraft_command(command)는 로컬 RCON을 통해 권한 있는 명령을 실행합니다.

• minecraft_logs(lines=200)는 latest.log의 제한된 꼬리 부분을 반환합니다.

• skript_reset()은 오래된 __mcp_check_<uuid>.sk 파일만 제거합니다.

다시 로드 작업은 직렬화됩니다. 진단은 주로 RCON 응답에서 구문 분석됩니다. Skript는 명령 진단을 의도적으로 일반 서버 로깅에서 리디렉션하기 때문입니다. 작업 오프셋 이후에 latest.log에 추가된 바이트는 캡처되어 보조 소스로 병합됩니다.

안전

skript_check_file은 샌드박스 처리된 구문 분석이 아닌, 활성화된 모든 스크립트의 실제 다시 로드를 수행합니다. on load 핸들러 또는 애드온 동작을 포함하는 소스는 월드, 파일 또는 외부 시스템을 수정할 수 있습니다. 신뢰할 수 있는 스크립트만 확인하고, minecraft_command 및 RCON 비밀번호를 완전한 관리자 액세스 권한으로 취급하십시오.

단위 테스트는 다음으로 실행합니다:

uv run pytest