skript-mcp

Skript MCP

该项目暴露了一个小型 MCP 服务器，后端由一个永久运行的 Paper 服务器支持。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 读取主机创建的权限为 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