内容
# craft-runner
本地 Minecraft 服务器插件测试平台，作为 MCP 服务器暴露。
本项目旨在通过 MCP 使用。CLI 仅是一个调试助手。
## 安装
全局安装已发布的 npm 包：
```sh
npm install -g @score2/craft-runner
```
这会安装三个命令：
- `craft-runner-mcp`：stdio MCP 服务器
- `craft-runner`：用户友好型 CLI
- `craftr`：较短的 CLI 别名
要求：
- Node.js 20+
- 与测试的 Minecraft 版本匹配的 Java
- 从源代码重建捆绑的调试代理时，仅需要 Gradle
要从源代码检出开始工作：
```sh
npm install
npm run build
npm install -g .
```
## MCP 命令
安装后，MCP 客户端可以使用以下命令启动 stdio 服务器：
```sh
craft-runner-mcp
```
macOS/Linux 示例 MCP 配置：
```json
{
"mcpServers": {
"craft-runner": {
"command": "craft-runner-mcp"
}
}
}
```
在 Windows 上，MCP 客户端在没有 shell 的情况下生成命令时，应通过 `cmd.exe` 使用 npm `.cmd` 代理：
```json
{
"mcpServers": {
"craft-runner": {
"command": "cmd.exe",
"args": ["/d", "/s", "/c", "craft-runner-mcp.cmd"]
}
}
}
```
对于 Codex 或 Claude Code，请在 MCP 服务器配置中使用相同的命令形状。不需要额外的守护进程或端口；MCP 服务器通过 stdio 进行通信。
## CLI
CLI 输出默认情况下是人类可读的。当脚本需要原始结构化响应时，请添加 `--json`：
```sh
craftr --json server list
```
```sh
craft-runner java list
craft-runner java validate 1.21.4 --java sdk:21.0.10-oracle
craft-runner server create --id test-paper --loader paper --minecraft-version 1.21.4 --start
craft-runner server create --id local-custom --path ./server.jar --minecraft-version 1.20.4
craft-runner server create --id direct-custom --direct-path /opt/minecraft/server.jar --minecraft-version 1.20.4
craft-runner server list
craft-runner server info test-server
craft-runner server logs test-server --tail 120
craft-runner server files test-server
craft-runner stats
craft-runner core list
craft-runner core info paper-1.21.4-123
craft-runner core verify paper-1.21.4-123
craft-runner core remove paper-1.21.4-123
```
`--path` 将自定义 jar 导入 craft-runner 的共享核心缓存。使用 `--direct-path` 时，jar 已经存在于执行主机上，应直接启动而无需复制到核心缓存中。对于远程 MCP 调用，`core_ref.direct_path` 在远程主机上被解释。
较短的别名 `craftr` 也已安装：
```sh
craftr server list
craftr stats
craftr core list
```
## Shell 补全
生成 zsh 补全：
```sh
craft-runner completion zsh
```
在当前 shell 中临时使用：
```sh
source <(craft-runner completion zsh)
```
持久的 zsh 安装通常意味着将生成的脚本写入已经存在于 `fpath` 中的目录，例如 Homebrew 的 site-functions 目录：
```sh
craft-runner completion install zsh
autoload -Uz compinit && compinit
```
选择特定的补全目录：
```sh
craft-runner completion install zsh --dir ~/.zsh/completions
```
如果服务器卡住，无法正常关闭，可以使用强制关闭备用方案：
```sh
craftr server kill test-paper
```
这绕过了正常的 Minecraft 和插件关闭。优先使用 `craftr server stop` 进行例行关闭。
## 发布自动化
GitHub Actions 在推送和拉取请求上运行回归测试。npm 发布有意被限制：发布工作流仅在手动调度或推送提交消息包含 `[npm publish]` 时运行。相同的工作流还会创建或更新匹配的 GitHub 发布 (`v<package version>`)，并为手动服务器安装附加特定于平台的 `craft-runner-agent-*.jar` 文件。MCP 管理的服务器会根据服务器加载器和 Minecraft 版本自动选择匹配的代理 jar。
对于 npm 受信任发布，请配置 npm 信任：
- 仓库：`Score2/craft-runner`
- 工作流：`.github/workflows/publish.yml`
- 分支：`master`
## 主要 MCP 工具
- `create_server`
- `list_servers`
- `get_server`
- `get_stats`
- `start_server`
- `stop_server`
- `kill_server`
- `restart_server`
- `destroy_server`
- `put_server_file`
- `put_server_files`
- `add_plugin`
- `remove_server_file`
- `list_server_files`
- `tail_server_log`
- `read_server_log`
- `wait_server_ready`
- `send_server_command`
- `get_server_events`
- `list_core_providers`
- `search_cores`
- `download_core`
- `import_core`
- `list_cores`
- `remove_core`
- `verify_core`
- `list_java_installations`
- `get_java_info`
- `validate_java_for_core`
- `debug_install_agent`
- `debug_agent_status`
- `debug_agent_api`
- `debug_eval_js`
- `debug_eval_js_file`
- `hot_plugin_capabilities`
- `hot_list_plugins`
- `hot_load_plugin`
- `hot_unload_plugin`
- `hot_reload_plugin`
`send_server_command` 是 Minecraft/代理控制台命令的支持路径。它在类 Unix 系统上使用调试代理套接字，在 Windows 上使用文件邮箱备用方案，仅在旧版/无代理服务器上回退到旧版 RCON 或托管 stdin。对于 MCP 客户端，不应直接与 tmux 交互，不应仅使用 `debug_eval_js` 来调度命令。
## JS 调试代理
对于支持插件/模组的服务器，craft-runner 可以安装本地调试代理。代理使用 GraalJS，并通过 `~/.craft-runner/agents/<server-port>/` 下的本地端点进行通信，而无需打开另一个 TCP 端口。在 Linux/macOS 上，它优先使用 Unix 域套接字，并回退到文件邮箱请求；在 Windows 上，它使用文件邮箱传输。相同的代理 jar 包含 Bukkit 家族服务器、BungeeCord/Waterfall、Velocity、Fabric、Forge 和 NeoForge 的入口点。Vanilla 服务器没有插件/模组加载机制，因此它们无法直接加载此代理。
```sh
craftr debug install-agent test-paper
craftr server restart test-paper
craftr debug status test-paper
craftr debug discover-agents
craftr debug register-agent 25565 --id manual-test-paper
craftr debug js test-paper --code "cr.platform.onlinePlayerNames()"
craftr debug hot-capabilities test-paper
craftr debug hot-load test-paper ./build/libs/MyPlugin.jar
craftr debug hot-reload test-paper MyPlugin ./build/libs/MyPlugin.jar
craftr debug hot-unload test-paper MyPlugin
```
安装程序将 jar 放在 Bukkit 家族和代理加载器的 `plugins/` 下，放在 Fabric、Forge 和 NeoForge 的 `mods/` 下。对于 `custom` 加载器，它会写入两个位置，因为仅凭元数据无法推断出平台。代理 jar 捆绑在 npm 包中，因此正常使用不需要 Gradle。`debug_install_agent` 带有 `rebuild: true` 需要 `PATH` 上的 Gradle。
邮箱路径：
```text
~/.craft-runner/agents/
<server-port>/
config.json
endpoint.json
agent.sock
requests/
responses/
tmp/
current.json
```
端点目录以 Minecraft 服务器端口命名，以便 MCP、本地工具和未来的远程运行程序可以在没有 craft-runner 元数据的情况下识别手动安装的代理。每个端点在 `config.json` 中都有一个唯一的令牌；代理会忽略具有不匹配令牌的请求。
用户也可以手动安装 `craft-runner-agent.jar`。在 Bukkit 家族、BungeeCord/Waterfall 和 Velocity 服务器上，`/craftragent status` 显示端点，`/craftragent token` 打印本地令牌。该命令通过 Incendo Cloud 注册，因此命令行为在这些平台上共享。`/cra` 可用作服务器内的简写别名。`list`、`hot-load`、`hot-unload` 和 `hot-reload` 可从同一命令中使用，但热插件操作目前仅对 Bukkit 家族、BungeeCord/Waterfall 和 Velocity 服务器执行实际加载/卸载工作。
要让 MCP 使用手动安装的代理，请扫描本地端点并注册匹配的端口。发现的/手动代理被视为临时的外部服务器：craft-runner 可以使用它们的调试端点，但不能销毁或拥有它们的生命周期。
```sh
craftr debug discover-agents
craftr debug register-agent 25565 --id manual-test-paper
```
调试脚本应优先使用 `cr` DSL 而非原始 Java 全局变量：
- `cr.common` 是跨平台的，包含 Java 反射、构造、集合、检查和原始服务器/插件/记录器访问助手。
- `cr.platform` 是特定于平台的。Bukkit 家族服务器公开玩家、世界、插件、命令、材料、物品堆栈和 Folia 检测的助手。BungeeCord/Waterfall 和 Velocity 公开代理玩家/服务器助手。Fabric、Forge 和 NeoForge 目前公开通用平台元数据和原始服务器/插件对象，因此在那里使用 `cr.common` 反射。
有用示例：
```js
cr.common.platformName()
cr.common.inspect(cr.common.server())
cr.common.callStatic("org.bukkit.Bukkit", "getOnlinePlayers").size()
cr.platform.capabilities()
cr.platform.onlinePlayerNames()
cr.platform.dispatchCommand("say hello from craft-runner")
```
MCP 客户端可以调用 `debug_agent_api` 以检索当前 DSL 引用，然后生成 `debug_eval_js` 代码。
## Bukkit 热插件调试
Bukkit 家族服务器可以使用调试代理来加载、卸载和重载插件 jar，而无需重启服务器：
```sh
craftr debug hot-capabilities test-paper
craftr debug hot-list test-paper
craftr debug hot-load test-paper ./plugins/MyPlugin.jar
craftr debug hot-reload test-paper MyPlugin ./plugins/MyPlugin.jar
craftr debug hot-unload test-paper MyPlugin
```
等效的 MCP 工具是 `hot_plugin_capabilities`、`hot_list_plugins`、`hot_load_plugin`、`hot_unload_plugin` 和 `hot_reload_plugin`。
重要注意事项：
- 热加载/卸载/重载旨在用于快速调试循环、快速迭代和小规模的视觉或文本调整。对于普通的插件更改，除非用户明确要求避免，否则优先使用正常的服务器重启。
- 如果热重载/卸载导致奇怪的行为、过时的状态、丢失的命令、类加载器问题、调度器问题或依赖关系不一致，请首先尝试完全重启服务器，除非用户明确要求不要重启。
- Bukkit 样式的 `plugin.yml` jar 在 Bukkit、Spigot、Paper 和 Folia 上受支持。
- 纯 Paper `paper-plugin.yml` jar 在 Paper/Folia 上通过反射 Paper 内部实现受支持。Paper 的公共运行时路径故意拒绝 Paper 插件提供程序，因此此路径是尽力而为，可能需要随着 Paper 内部更改而更新。
- 在 Paper 1.20.5+ 上，插件重映射委托给正在运行的服务器。
- 在 Folia 上，插件 jar 必须满足 Folia 自己的兼容性规则，例如在需要时声明 `folia-supported: true`。
- 卸载/重载是尽力而为的。插件拥有的静态状态、自定义线程、原生资源和第三方注册表可能仍需要重启服务器。
- BungeeCord/Waterfall 和 Velocity 目前报告热插件操作为不支持。Velocity 没有公共卸载 API，运行时加载无法安全地为仅新加载的插件重放初始化，而不影响现有插件。
## 核心安装缓存
下载的核心存储在用户缓存目录下一次。运行时资产绑定到特定核心，例如 `libraries/`、Paper/Purpur 缓存输出和 Forge/NeoForge 安装程序输出，在该核心的安装目录下集中准备。
每个测试服务器都保留自己的 `plugins/`、配置、世界和日志，而可共享的核心绑定目录则从核心安装目录链接。
## 运行时目录
默认情况下，临时测试服务器放置在系统临时目录下，可以由操作系统清理。缓存的服务器核心和共享的核心安装数据存储在用户缓存目录下，以避免重复下载。
有用环境变量：
- `CRAFT_RUNNER_CACHE_DIR`：覆盖核心/缓存目录
- `CRAFT_RUNNER_SERVER_BASE_DIR`：覆盖测试服务器的创建位置
- `CRAFT_RUNNER_STATE_DIR`：覆盖元数据和锁定存储
- `CRAFT_RUNNER_JAVA_REF`：默认 Java 引用，例如 `system`、`home:/path` 或 `path:/path/to/java`
远程和 Docker 运行程序尚未实现。
