skript-mcp

Skript MCP

Este proyecto expone un pequeño servidor MCP respaldado por un servidor Paper que se ejecuta permanentemente. Paper, Skript y los complementos instalados son el analizador sintáctico: el código Python no intenta entender la sintaxis de Skript en sí.

La imagen predeterminada contiene este perfil de compatibilidad:

Cada jar descargado se verifica durante la construcción de la imagen. Sobrescribe todas las URL y sumas de verificación relacionadas juntas en .env para usar otro perfil autoritativo. Nunca actualices solo un complemento sin verificar el conjunto completo.

Skript 2.14.3 es intencional para el perfil 1.21.4. SkBee 3.16.1 es la última versión de SkBee para Minecraft 1.21.4, y las versiones más recientes de Skript 2.15/2.16 chocan con su registro de tipo audience de Adventure. Skript más reciente requiere mover todo el perfil a una versión más reciente de Minecraft y SkBee.

Iniciar Paper

Ejecuta el script de configuración. Verifica Docker y uv, crea .env con una contraseña RCON aleatoria, instala dependencias, construye Paper y verifica RCON:

./setup.sh

Para la configuración manual, crea un archivo de entorno local y reemplaza la contraseña con un valor aleatorio largo que contenga solo letras, números, puntos, guiones bajos o guiones:

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

Establece PUID y PGID en .env con la salida de id -u y id -g. Por defecto son 1000 y permiten que Paper lea los archivos temporales creados por el host con modo 0600.

Los registros de Paper se montan en runtime/logs. Los scripts del host se montan directamente en /server/plugins/Skript/scripts desde scripts. Los datos del mundo y los generados por complementos permanecen como estado desechable del contenedor. Solo se publica RCON, y está vinculado a 127.0.0.1:25575; el puerto de juego no se publica.

Verifica el inicio y las versiones de los complementos con:

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

Ejecutar el servidor MCP

Instálalo y ejecútalo con uv:

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

El proceso MCP lee estas variables de entorno:

Para OpenCode, agrega una entrada MCP local y pasa la misma contraseña RCON a través del entorno:

{
  "$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": {}
    }
  }
}

Reinicia OpenCode después de cambiar su configuración.

Herramientas

• skript_check_file(path) valida un archivo .sk existente por ruta. Las rutas relativas se resuelven bajo SKRIPT_SCRIPTS_DIR; las rutas absolutas se aceptan cuando apuntan dentro de ese directorio. Recarga el conjunto completo de scripts para que las funciones y otras definiciones compartidas de scripts hermanos estén disponibles.

• skript_reload_file(path) recarga una ruta existente dentro de SKRIPT_SCRIPTS_DIR sin recargar sus scripts hermanos.

• minecraft_command(command) ejecuta un comando privilegiado a través de RCON local.

• minecraft_logs(lines=200) devuelve una cola limitada del archivo latest.log.

• skript_reset() elimina solo los archivos obsoletos __mcp_check_<uuid>.sk.

Las operaciones de recarga se serializan. Los diagnósticos se analizan principalmente desde la respuesta de RCON porque Skript redirige deliberadamente los diagnósticos de comandos fuera del registro normal del servidor; los bytes añadidos a latest.log después del desplazamiento de la operación se capturan y se fusionan como fuente secundaria.

Seguridad

skript_check_file realiza una recarga real de cada script habilitado, no un análisis en entorno aislado. El código fuente que contiene manejadores on load o comportamiento de complementos puede modificar el mundo, archivos o sistemas externos. Solo verifica scripts de confianza y trata minecraft_command y la contraseña RCON como acceso de administrador completo.

Ejecuta las pruebas unitarias con:

uv run pytest