skript-mcp

Skript MCP

このプロジェクトは、常時稼働しているPaperサーバーをバックエンドとする小さなMCPサーバーを公開します。Paper、Skript、およびインストールされたアドオンがパーサーです。PythonコードはSkriptの構文自体を理解しようとはしません。

デフォルトのイメージには、以下の互換性プロファイルが含まれています。

ダウンロードされたすべてのjarは、イメージビルド中にチェックされます。別の信頼できるプロファイルを使用するには、関連するすべてのURLとチェックサムを.envでまとめて上書きしてください。完全なセットを確認せずに、1つのアドオンだけを更新しないでください。

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がホスト作成のモード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内の既存の1つのパスをリロードし、兄弟スクリプトはリロードしません。

• 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