skript-mcp

Skript MCP

This project exposes a small MCP server backed by a permanently running Paper server. Paper, Skript, and the installed addons are the parser: the Python code does not attempt to understand Skript syntax itself.

The default image contains this compatibility profile:

Every downloaded jar is checked during the image build. Override all related URLs and checksums together in .env to use another authoritative profile. Never update only one addon without verifying the complete set.

Skript 2.14.3 is intentional for the 1.21.4 profile. SkBee 3.16.1 is the last SkBee release for Minecraft 1.21.4, and newer Skript 2.15/2.16 releases collide with its Adventure audience type registration. Newer Skript requires moving the whole profile to a newer Minecraft and SkBee release.

Paper starten

Führen Sie das Setup-Skript aus. Es prüft Docker und uv, erstellt .env mit einem zufälligen RCON-Passwort, installiert Abhängigkeiten, baut Paper und überprüft RCON:

./setup.sh

Für die manuelle Einrichtung erstellen Sie eine lokale Umgebungsdatei und ersetzen das Passwort durch einen langen, zufälligen Wert, der nur Buchstaben, Zahlen, Punkte, Unterstriche oder Bindestriche enthält:

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

Setzen Sie PUID und PGID in .env auf die Ausgabe von id -u und id -g. Sie sind standardmäßig auf 1000 gesetzt und ermöglichen Paper das Lesen der vom Host erstellten temporären Dateien mit der Berechtigung 0600.

Paper-Logs werden unter runtime/logs eingehängt. Host-Skripte werden direkt unter /server/plugins/Skript/scripts von scripts aus eingehängt. Welt- und plugin-generierte Daten bleiben als wegwerfbarer Containerzustand erhalten. Nur RCON wird veröffentlicht und ist an 127.0.0.1:25575 gebunden; der Spielport wird nicht veröffentlicht.

Überprüfen Sie den Start und die Plugin-Versionen mit:

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

Den MCP-Server ausführen

Installieren und führen Sie ihn mit uv aus:

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

Der MCP-Prozess liest diese Umgebungsvariablen:

Fügen Sie für OpenCode einen lokalen MCP-Eintrag hinzu und übergeben Sie dasselbe RCON-Passwort über die Umgebung:

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

Starten Sie OpenCode nach einer Änderung seiner Konfiguration neu.

Werkzeuge

• skript_check_file(path) validiert eine vorhandene .sk-Datei anhand des Pfades. Relative Pfade werden unter SKRIPT_SCRIPTS_DIR aufgelöst; absolute Pfade werden akzeptiert, wenn sie innerhalb dieses Verzeichnisses liegen. Es lädt den gesamten Skriptsatz neu, sodass Funktionen und andere gemeinsame Definitionen aus Schwester-Skripten verfügbar sind.

• skript_reload_file(path) lädt einen vorhandenen Pfad innerhalb von SKRIPT_SCRIPTS_DIR neu, ohne seine Schwester-Skripte neu zu laden.

• minecraft_command(command) führt einen privilegierten Befehl über das lokale RCON aus.

• minecraft_logs(lines=200) gibt einen begrenzten Auszug vom Ende der latest.log zurück.

• skript_reset() entfernt nur veraltete __mcp_check_<uuid>.sk-Dateien.

Neuadevorgänge werden serialisiert. Diagnosen werden hauptsächlich aus der RCON-Antwort geparst, da Skript Befehlsdiagnosen bewusst vom normalen Server-Logging umleitet; Bytes, die nach dem Operationsoffset an latest.log angehängt werden, werden erfasst und als sekundäre Quelle zusammengeführt.

Sicherheit

skript_check_file führt ein echtes Neuladen aller aktivierten Skripte durch, keine sandboxierte Analyse. Quellen, die on load-Handler oder Addon-Verhalten enthalten, können die Welt, Dateien oder externe Systeme verändern. Überprüfen Sie nur vertrauenswürdige Skripte und behandeln Sie minecraft_command und das RCON-Passwort als vollständigen Administratorzugriff.

Führen Sie Komponententests aus mit:

uv run pytest