VitaminMCP

插件

· 作者 Backas03

一个 MCP 服务器,使 AI 代理能够使用机器人和服务器自省功能对 Minecraft 服务器执行真实的端到端测试。

0 本站下载 0 关注 更新于 4 周前

最新 3.2.2 · 26.1.2 · Paper / Purpur

一键开服(送7天)

VitaminMCP

用 AI 代理测试你的插件 —— 在真实运行的服务器上,配合真实玩家。 VitaminMCP demo

源代码 · 文档 · 问题反馈

VitaminMCP 是一个 Paper/Purpur 插件,它从正在运行的服务器内部开放一个 MCP(模型上下文协议) 端点。连接一个 AI 代理——Claude Code、Cursor、Codex、Gemini CLI 或任何 MCP 客户端——它就能驱动服务器并读取发生的情况,同时真实的机器人客户端通过实际的 Minecraft 协议加入。

你正在测试的插件本身没有任何改变。 无需采用测试框架,无需对源码进行插桩,也无需模拟服务器:被测试的插件在其真实生命周期中于真实服务器上运行。这也意味着它可以作用于你未编写的插件——任何已安装的插件都可进行测试。

代理可以执行的操作

  • 生成并控制测试玩家 —— 真实的协议客户端,而非模拟的 Player 对象
  • 以控制台或玩家身份执行命令
  • 打开、读取、点击并断言物品栏和插件 GUI
  • 右键点击 NPC 和村民,就像触发商店或任务发布者那样
  • 移动玩家,破坏和使用方块,聊天
  • 等待事件和条件,而不是休眠
  • 读取玩家的整个屏幕:菜单、聊天、动作栏、标题、Boss 血条、计分板
  • 读取实时服务器状态:事件、日志、异常、权限
  • 同时驱动多个服务器 —— BungeeCord 网络的每个后端拥有一个会话

MCP 工具

工具 功能
session_start 连接到正在运行的服务器;对于代理网络可同时建立多个会话
session_reset 断开所有机器人的连接,或关闭一个会话
server_info 实现信息、版本、TPS、在线玩家数、已安装插件
logs_query 按严重性和正则表达式搜索服务器日志
events_summary 统计时间窗口内按类型捕获的 Bukkit 事件数量
events_query 读取单独捕获的事件,按类型和玩家过滤
exceptions_recent 不同的异常及其计数;按需获取完整堆栈跟踪
state_query 实时服务器状态 —— player(包括权限检查)、block、inventory(插件 GUI 内容存在的地方)、plugin(命令、权限、实时配置)
command_exec 以控制台或任何玩家的身份运行命令,包含权限检查
wait_for 阻塞直到条件成立 —— ticks、block_is、block_is_not、event、player_online、player_offline、player_near、player_state、inventory_open、inventory_contains、log_matches
bot_spawn 连接一个真实的 Minecraft 协议客户端作为测试玩家
bot_inspect 查看发送给该机器人客户端的所有内容:聊天、动作栏、标题、Boss 血条、计分板、生命值、效果、打开的菜单
bot_run_scenario 在一次调用中运行完整的脚本化测试;失败时会报告失败的步骤以及当时服务器的行为
bot_view 单个机器人的实时本地查看器 —— 世界或它打开的菜单

场景步骤

bot_run_scenario 使用以下步骤编写整个测试脚本 —— 失败时会报告失败的步骤以及当时服务器的行为:

类别 步骤 功能
世界与移动 spawn 连接机器人并等待其站立在世界中
despawn 断开机器人的连接
move_to 通过真实物理引擎行走 —— 压力板和移动监听器会触发;支持用于设置的 teleport 模式
look_at 面向某个方块或位置
jump 跳跃
sneak 开始或停止潜行
sprint 开始或停止疾跑
方块与物品 break_block 破坏方块,通过真实的挖掘过程
place_block 从手中放置方块
use_block 右键点击方块 —— 按钮、门、箱子等
hold_item 将物品放入主手
drop_item 丢弃手中的物品
交互 use_entity 右键点击实体 —— 就像实际触发商店或任务 NPC 那样
attack_entity 攻击实体
click_slot 点击打开的菜单或 GUI 中的槽位
close_menu 关闭打开的菜单
chat 以机器人身份发送聊天消息
command 以机器人身份发送命令,包含权限检查
console 在场景中间运行控制台命令
等待 wait_for 阻塞直到条件成立 —— 每个 wait_for 条件均可作为步骤使用
断言 assert_block 断言某个方块的状态
assert_player 断言玩家的实时状态 —— 位置、游戏模式、OP 状态、生命值
assert_event 断言服务器上触发了某个事件
assert_inventory 断言打开的 GUI 或物品栏的槽位内容
assert_message 断言发送给机器人客户端的内容 —— 聊天、动作栏、标题
assert_reachable 断言某个位置实际上是可以步行到达的

版本支持

Minecraft 版本 Windows Linux macOS 状态
1.18 – 1.20.6 ? ? ? 计划中;低于当前代理基线版本 (1.21)
1.21 – 1.21.11 ? ? ? 支持并进行实时测试
26.1 – 26.1.2 ? ? ? 支持并进行实时测试;服务器需要 Java 25
26.2 及更高版本 ? ? ? 已发布;每个版本都需要在添加前进行兼容性运行

按操作系统的运行器支持

操作系统 Node 源运行器 原生运行器资产 含义
Windows x64 ? ? 已发布,且是矩阵测试运行的平台
Linux x64 / arm64 ? ? 自 3.0.0 起发布
macOS Intel / Apple Silicon ? ? 自 3.0.0 起发布,临时签名

图例: ? 支持 · ? 计划中或需要指定的运行时环境 · ? 不支持。

设置

1. 安装插件 — 从最新版本(或此处的版本标签页)下载 VitaminMCP.jar,将其放入 plugins/ 目录并启动服务器。

2. 将 MCP 服务器添加到你的 AI 客户端中 — 它运行在你的本地机器上,而非服务器上:

Claude Code

claude mcp add vitaminmcp -- npx -y vitaminmcp

Claude Desktop、Cursor 或任何使用 JSON MCP 配置的客户端:

{
  "mcpServers": {
    "vitaminmcp": {
      "command": "npx",
      "args": ["-y", "vitaminmcp"]
    }
  }
}

它也托管在 官方 MCP 注册中心,ID 为 io.github.Backas03/vitaminmcp,因此支持注册中心目录的客户端可以直接从中添加。

3. 让智能体自动完成配置 — 让它运行 setup 提示命令(在 Claude Code 中:/mcp__vitaminmcp__setup)。它将查找正在运行的服务器,检查插件状态并完成连接。

完整的安装与使用文档请访问:backas03.github.io/VitaminMCP —— 涵盖了所有工具、运行场景、多服务器会话以及远程服务器设置等详细信息,详见 usage.md。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源