VitaminMCP

VitaminMCP

使用 AI Agent 测试你的插件——在真实运行的服务器上，与真实玩家一起。

文档 · Modrinth · npm · 问题反馈

VitaminMCP 是一个 Paper/Purpur 插件，可从正在运行的服务器内部开放 MCP（Model Context Protocol）端点。连接 AI Agent——Claude Code、Cursor、Codex、Gemini CLI，或任何 MCP 客户端——即可驱动服务器并读取运行结果，同时真实机器人客户端通过实际的 Minecraft 协议加入服务器。

你正在测试的插件不需要做任何改动。 无需采用测试框架，无需插桩源码，也无需模拟服务器：被测插件会在真实服务器上经历真实生命周期。这也意味着它适用于你没有编写的插件——任何已安装的插件都可以测试。

Agent 可以做什么

• 生成并控制测试玩家——使用真实协议客户端，而不是模拟的 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	将离线或通过 Microsoft 身份验证的 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	断言玩家的实时状态——位置、游戏模式、管理员权限、生命值
	assert_event	断言服务端触发了某个事件
	assert_inventory	断言已打开 GUI 或背包中的槽位
	assert_message	断言机器人的客户端收到的内容——聊天、动作栏、标题
	assert_reachable	断言可以实际步行到达某个位置

三部分如何配合、每个工具和步骤接受的参数，以及场景示例，请参阅 docs/reference.md。

版本支持

Minecraft 版本	Windows	Linux	macOS	状态
1.18 – 1.20.6	🟡	🟡	🟡	计划支持；低于当前 Agent 的最低版本（1.21）
1.21 – 1.21.11	🟢	🟢	🟢	已支持并通过实时测试
26.1 – 26.1.2	🟢	🟢	🟢	已支持并通过实时测试
26.2 – 26.3，Agent	🟢	🟢	🟢	Agent 已支持：日志、事件、状态和命令，已在 Paper 26.2-134 和 26.3-200 上手动验证
26.2 – 26.3，机器人	🔴	🔴	🔴	暂不支持：mineflayer 最高支持到 26.1（#4）。session_start 会为 Agent 开启会话，并说明机器人无法加入的原因
后续版本	🟡	🟡	🟡	每个版本在加入前都需要进行兼容性测试

各操作系统的运行器支持情况

操作系统	Node 源码运行器	原生运行器资源	说明
Windows x64	🟢	🟢	已发布，且该平台用于运行兼容性矩阵测试
Linux x64 / arm64	🟢	🟢	自 3.0.0 起发布
macOS Intel / Apple Silicon	🟢	🟢	自 3.0.0 起发布，采用临时签名

图例： 🟢 已支持 · 🟡 计划支持或需要指定的运行时 · 🔴 不支持。

有关要求、各项声明的依据，以及版本矩阵的运行方式，请参阅 docs/reference.md。

安装

1. 安装插件 — 从最新版本（或 Modrinth）下载 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 官方注册表，名称为 io.github.Backas03/vitaminmcp，因此支持注册表目录的客户端可以从那里添加它。

对于每个已加载项目都使用一个 stdio 进程的客户端，也可以让所有项目连接到 一个共享的回环服务。在 Windows 上， 运行 npx -y vitaminmcp service install 即可通过一条命令安装并验证该共享服务。

3. 让 Agent 自动完成配置 — 让它运行 setup 提示词（在 Claude Code 中： /mcp__vitaminmcp__setup）。它会查找正在运行的服务、检查插件并建立连接。

对于运行在本机上的服务，这样就足够了。Claude Code 插件（还附带测试技能）、其他客户端、从 jars 安装、 config.yml 默认值、bot 配置，以及通过 SSH 或 TLS 连接到服务端的说明，都在 INSTALL.md 中。

完整的安装和使用文档：backas03.github.io/VitaminMCP — 涵盖每个工具、场景运行、多服务会话和远程服务配置，详见 docs/usage.md。

贡献与构建

贡献规则见 CONTRIBUTING.md，从源代码构建的说明见 docs/reference.md，发布步骤见 docs/publishing.md。

许可证

MIT — 请参阅 LICENSE。jars 中捆绑的第三方代码及其许可证，列于 docs/reference.md。