skript-mcp

Skript MCP

Этот проект предоставляет небольшой MCP-сервер, работающий поверх постоянно запущенного сервера Paper. Paper, Skript и установленные аддоны выступают в роли парсера: код на Python не пытается самостоятельно разбирать синтаксис Skript.

Образ по умолчанию содержит следующий профиль совместимости:

Каждый загруженный jar-файл проверяется во время сборки образа. Чтобы использовать другой авторитетный профиль, переопределите все соответствующие URL и контрольные суммы вместе в файле .env. Никогда не обновляйте только один аддон без проверки всего набора.

Skript 2.14.3 выбран намеренно для профиля 1.21.4. SkBee 3.16.1 — последний релиз SkBee для Minecraft 1.21.4, а более новые версии Skript 2.15/2.16 конфликтуют с его регистрацией типа audience из Adventure. Для перехода на более новый Skript потребуется обновить весь профиль до более новой версии Minecraft и SkBee.

Запуск Paper

Запустите скрипт настройки. Он проверяет Docker и uv, создаёт .env со случайным паролем RCON, устанавливает зависимости, собирает Paper и проверяет RCON:

./setup.sh

Для ручной настройки создайте локальный файл окружения и замените пароль на длинное случайное значение, содержащее только буквы, цифры, точки, подчёркивания или дефисы:

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

Установите PUID и PGID в .env равными выводу команд id -u и id -g. По умолчанию они равны 1000 и позволяют Paper читать созданные хостом временные файлы с правами 0600.

Логи Paper монтируются в runtime/logs. Скрипты хоста монтируются напрямую в /server/plugins/Skript/scripts из папки 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