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

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。
VitaminMCP
Test your plugins with an AI agent — on a real running server, with real players.

Source code · Documentation · Issues
VitaminMCP is a Paper/Purpur plugin that opens an MCP (Model Context Protocol) endpoint from inside your running server. Connect an AI agent — Claude Code, Cursor, Codex, Gemini CLI, any MCP client — and it can drive the server and read back what happened, while real bot clients join over the actual Minecraft protocol.
Nothing about the plugin you are testing changes. No test framework to adopt, no source to instrument, no mock server: the plugin under test runs on a real server through its real lifecycle. That also means it works on plugins you did not write — anything installed is testable.
What the agent can do
- Spawn and control test players — real protocol clients, not mock
Playerobjects - Execute commands as the console or as a player
- Open, read, click and assert on inventories and plugin GUIs
- Right-click NPCs and villagers, the way a shop or quest giver is actually triggered
- Move players, break and use blocks, chat
- Wait for events and conditions instead of sleeping
- Read the player's whole screen: menus, chat, action bar, titles, boss bars, scoreboard
- Read live server state: events, logs, exceptions, permissions
- Drive several servers at once — one session per backend of a BungeeCord network
MCP tools
| Tool | What it does |
|---|---|
session_start |
Connect to a running server; several sessions at once for proxied networks |
session_reset |
Disconnect every bot, or close a session |
server_info |
Implementation, version, TPS, online players, installed plugins |
logs_query |
Search server logs by severity and regular expression |
events_summary |
Count captured Bukkit events by type over a time window |
events_query |
Read individual captured events, filtered by type and player |
exceptions_recent |
Distinct exceptions with counts; full stack trace on demand |
state_query |
Live server state — player (including permission checks), block, inventory (the only place a plugin GUI's contents exist), plugin (commands, permissions, live config) |
command_exec |
Run a command as the console or as any player, permissions and all |
wait_for |
Block until a condition holds — ticks, block_is, block_is_not, event, player_online, player_offline, player_near, player_state, inventory_open, inventory_contains, log_matches |
bot_spawn |
Connect a real Minecraft protocol client as a test player |
bot_inspect |
Everything the bot's client was sent: chat, action bar, titles, boss bars, scoreboard, health, effects, open menu |
bot_run_scenario |
Run a whole scripted test in one call; a failure reports the failing step and what the server was doing at that moment |
bot_view |
Live localhost viewer for one bot — the world, or the menu it has open |
Scenario steps
bot_run_scenario scripts a whole test from these steps — a failure reports the failing step and
what the server was doing at that moment:
| Category | Step | What it does |
|---|---|---|
| World & movement | spawn |
Connect the bot and wait until it is standing in the world |
despawn |
Disconnect the bot | |
move_to |
Walk there through real physics — pressure plates and move listeners fire; teleport mode for setup |
|
look_at |
Face a block or position | |
jump |
Jump | |
sneak |
Start or stop sneaking | |
sprint |
Start or stop sprinting | |
| Blocks & items | break_block |
Break a block, through real digging |
place_block |
Place a block from the hand | |
use_block |
Right-click a block — buttons, doors, chests | |
hold_item |
Put an item into the main hand | |
drop_item |
Drop the held item | |
| Interaction | use_entity |
Right-click an entity — the way a shop or quest NPC is actually triggered |
attack_entity |
Attack an entity | |
click_slot |
Click a slot in the open menu or GUI | |
close_menu |
Close the open menu | |
chat |
Send a chat message as the bot | |
command |
Send a command as the bot, permissions and all | |
console |
Run a console command mid-scenario | |
| Waiting | wait_for |
Block until a condition holds — every wait_for condition is available as a step |
| Assertions | assert_block |
Assert what a block is |
assert_player |
Assert a player's live state — position, game mode, op, health | |
assert_event |
Assert that an event fired on the server | |
assert_inventory |
Assert the slots of the open GUI or an inventory | |
assert_message |
Assert what the bot's client was told — chat, action bar, title | |
assert_reachable |
Assert a position can actually be walked to |
Version support
| Minecraft version | Windows | Linux | macOS | Status |
|---|---|---|---|---|
| 1.18 – 1.20.6 | ? | ? | ? | Planned; below the current agent floor (1.21) |
| 1.21 – 1.21.11 | ? | ? | ? | Supported and live-tested |
| 26.1 – 26.1.2 | ? | ? | ? | Supported and live-tested; the server needs Java 25 |
| 26.2 and later | ? | ? | ? | Released; each needs a compatibility run before it is added |
Runner support by operating system
| Operating system | Node source runner | Native runner asset | Meaning |
|---|---|---|---|
| Windows x64 | ? | ? | Published, and the platform the matrix is run on |
| Linux x64 / arm64 | ? | ? | Published since 3.0.0 |
| macOS Intel / Apple Silicon | ? | ? | Published since 3.0.0, ad-hoc signed |
Legend: ? supported · ? planned or requires the stated runtime · ? unsupported.
Setup
1. Install the plugin — download VitaminMCP.jar from the
latest release (or the Versions tab
here), drop it into plugins/, and start the server.
2. Add the MCP server to your AI client — it runs on your machine, not on the server:
Claude Code
claude mcp add vitaminmcp -- npx -y vitaminmcp
Claude Desktop, Cursor, or any client with a JSON MCP config:
{
"mcpServers": {
"vitaminmcp": {
"command": "npx",
"args": ["-y", "vitaminmcp"]
}
}
}
It is also on the official MCP registry as
io.github.Backas03/vitaminmcp, so clients with a registry catalogue can add it from there.
3. Let the agent wire itself up — ask it to run the setup prompt (in Claude Code:
/mcp__vitaminmcp__setup). It finds the running server, checks the plugin, and connects.
Full installation and usage docs: backas03.github.io/VitaminMCP — every tool, scenario runs, multi-server sessions, and remote-server setup are covered in usage.md.
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 VitaminMCP
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
机器人像玩家一样聊天:chat 场景步骤发送玩家聊天而非执行 /say,因此读取聊天输入的插件可以接收到它。
现有场景使用相同的参数运行并获得相同形状的响应,服务器插件与 3.2.0 版本相同,仅版本号不同。服务器从 chat 步骤看到的内容发生了变化:现在是玩家聊天,而以前看到的是 /say 命令。那些断言 /say 广播或其聊天命令事件的场景需要更新。以 / 开头的 chat 消息现在会导致步骤失败而不是被说出;请使用 command 发送此类消息。
修复
chat 发送玩家聊天。 它过去会运行 /say <message>。这从未到达等待聊天输入的插件(例如询问数量的商店或询问名称的提示),并且对于没有权限使用 /say 的机器人来说也会失败。现在消息以玩家输入的形式发出,并且该步骤会等待直到服务器收到它,最多等待 timeoutMillis 毫秒。如果插件消耗并取消了消息,仍然算作已接收,因此请检查插件对消息的处理情况,使用 assert_message 或状态断言进行验证。
当服务器拒绝该消息时,步骤将失败并显示告诉机器人的内容。离线机器人没有聊天签名密钥,因此要求安全聊天的服务器可能会拒绝它们;在这种情况下请使用微软账户的机器人。
当机器人能够签名时,命令会被签名。 运行带有消息的命令(如 /msg 或 /say)的微软账户机器人现在会以与玩家客户端相同的方式对其进行签名。
升级
按之前方式安装即可;服务器插件可以保持在 3.2.0 或 3.2.1 版本。
此修复由 @qsef1256 提供,见 #5。
完整更新日志:
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
插件
ExyliaPlugins 的库。
插件
通过对话框或铁砧界面帮助你的 Anthme
插件
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
插件
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
插件
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧