VitaminMCP-minecraft

# VitaminMCP

**Minecraft automation testing MCP server plugin for AI agents.**

VitaminMCP is a **Paper/Purpur server plugin.** Drop `VitaminMCP.jar` into `plugins/`, start the
server, and it opens an MCP endpoint from inside the running server — so an AI agent can drive that
server and read back what happened, while real bot clients connect to it over the Minecraft
protocol.

**Nothing about the plugin you are testing changes.** No test framework to adopt, no source to
instrument, no harness to compile against, no mock server standing in for a real one: the plugin
under test runs on a real server through its real lifecycle, and VitaminMCP watches it from the next
plugin slot over. Which also means it works on plugins you did not write — anything already
installed is testable.

Drive a real Minecraft server and real players through MCP tools, and run end-to-end plugin tests
without opening the game.

- Spawn and control test players — real protocol clients, not mock `Player` objects
- 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
- Assert on blocks, players, events, inventories and the messages a player received
- 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, bots staying
  connected across all of them
- Paper / Purpur **1.21 through 1.21.8**, from one install — the runner works out which protocol the
  server speaks and adapts

Full usage is in [docs/usage.md](docs/usage.md), design rationale in
[docs/design.md](docs/design.md), contribution rules in [CONTRIBUTING.md](CONTRIBUTING.md),
release steps in [docs/publishing.md](docs/publishing.md).

---

## How it fits together

Three jars, in three different places. Only the first is a Minecraft plugin.

```text
  your MCP client (Claude Code, ...)
        |
        |  stdio
        v
  mcp-server.jar ---- HTTP(S) + token ---->  VitaminMCP.jar  <- the plugin, inside your server
        |                                    sees events, logs, exceptions, live state
        |  spawns
        v
  bot-runner.jar ---- Minecraft protocol ->  the same server, on :25565
                                             sees what a player's client was actually sent
```

| | Runs | Role |
|---|---|---|
| `VitaminMCP.jar` | **in the server, as a plugin** | Listens to every event, taps the log, and serves an authenticated MCP endpoint. The only piece with a view of server internals |
| `mcp-server.jar` | on your machine, as a child of your MCP client | Speaks stdio to the client and HTTP to the plugin, and owns the bots |
| `bot-runner.jar` | on your machine, as a child of `mcp-server` | Connects real clients over the real protocol — login, packets, GUIs and all |

**Why the agent has to be a plugin.** Half of what a test needs to assert on has no protocol
representation. Whether a `PlayerJoinEvent` fired, a stack trace on the console, whether `/op`
actually resolved, what a permission node evaluates to — none of that reaches a connected client.
Only code running inside the server can see it. Hence the split: the plugin reports what the
*server* did, bots observe what a *player* was shown, and a single assertion can draw on both.

**The plugin is worth installing on its own.** With nothing else set up, it turns "find out why the
server died last night" into a question you can ask — events, logs, exceptions, plugin list, live
state, all over MCP ([design.md §1](docs/design.md)). Bots are opt-in, and so is the server
configuration they need ([Server setup](#2-server-setup-if-you-want-bots)); read-only is the
default, so a plugin-only install cannot alter the server at all.

---

## Why

**Without VitaminMCP**, verifying a plugin change means:

- Launch Minecraft, join the server
- Click through the GUI by hand
- Read the chat and eyeball whether it did the right thing
- Repeat for every permission level, every edge case, every version

**With VitaminMCP**, you type this to your agent:

> **Prompt:** Spawn a bot, op it, open the `/shop` GUI, check slot 11 is a diamond sword listed at
> 100 coins, buy it, confirm the sword is in the bot's inventory, then deop.

and it drives the server, verifies each step, and tells you which one failed and what the server was
doing at that moment.

The difference that matters for an AI agent is not the automation — it is that **failures are
attributable.** A scenario stops at the first failing step and returns the events and log lines from
that instant, so there is no second round-trip to find out why.

---

## What a test looks like

Every action below is a real step. Type the prompt and let the agent build it, or hand
`bot_run_scenario` the array yourself.

### Buying from a shop GUI

> **Prompt:** Spawn a bot called `Tester1` and op it. Open the `/shop` GUI and check slot 11 holds a
> diamond sword named "Diamond Sword" with "100 coins" in its lore. Buy it, then confirm the sword
> ended up in the bot's own inventory. Deop when you are done.

```json
[
  {"action": "spawn",         "bot": "Tester1"},
  {"action": "console",       "command": "op Tester1"},
  {"action": "assert_player", "bot": "Tester1", "op": true},

  {"action": "command",       "bot": "Tester1", "command": "shop"},
  {"action": "wait_for",      "condition": "inventory_open", "name": "Tester1", "title": "Shop"},
  {"action": "assert_inventory", "bot": "Tester1", "size": 27, "slots": [
      {"slot": 11, "material": "DIAMOND_SWORD", "name": "Diamond Sword", "lore": "100 coins"}
  ]},

  {"action": "click_slot",    "bot": "Tester1", "slot": 11},
  {"action": "assert_event",  "eventType": "InventoryClickEvent", "player": "Tester1"},
  {"action": "wait_for",      "condition": "inventory_contains",
                              "name": "Tester1", "material": "DIAMOND_SWORD", "which": "player"},

  {"action": "close_menu",    "bot": "Tester1"},
  {"action": "console",       "command": "deop Tester1"}
]
```

### A login reward, and its cooldown

> **Prompt:** Test the daily reward plugin. Join as `Newcomer`, wait for the reward menu, check slot
> 13 is the claim button, click it and confirm the bot was told it claimed something. Then rejoin as
> the same player, click again, and confirm it is refused this time because the cooldown is still
> running.

The second half tests the refusal, which is the part that usually goes unverified: a cooldown
rejection is often one chat message with nothing behind it — no exception, no log line, no event.

```json
[
  {"action": "spawn",    "bot": "Newcomer"},
  {"action": "wait_for", "condition": "inventory_open", "name": "Newcomer", "title": "Daily Reward"},
  {"action": "assert_inventory", "bot": "Newcomer", "slots": [
      {"slot": 13, "material": "CHEST", "name": "Claim"}
  ]},
  {"action": "click_slot",     "bot": "Newcomer", "slot": 13},
  {"action": "assert_message", "bot": "Newcomer", "contains": "claimed"},

  {"action": "despawn", "bot": "Newcomer"},
  {"action": "spawn",   "bot": "Newcomer"},
  {"action": "wait_for","condition": "inventory_open", "name": "Newcomer"},
  {"action": "click_slot",     "bot": "Newcomer", "slot": 13},
  {"action": "assert_message", "bot": "Newcomer", "contains": "already"}
]
```

That second run works because **a bot's UUID is derived from its name.** `Newcomer` is the same
player across runs, so anything keyed on identity — permissions, cooldowns, stored data —
reproduces instead of drifting.

A failure comes back naming the step, the reason, and the evidence:

```jsonc
{"step": 5, "action": "assert_inventory", "passed": false,
 "detail": "slot 11 expected DIAMOND_SWORD but held AIR",
 "evidence": "events=[...] logs=[...]"}
```

---

## Tools

Two groups. **Session tools** live in `mcp-server` and are always present. **Agent tools** are
proxied from the plugin, so which ones exist is decided by the server you connected to —
`session_start` returns their real definitions in `agentTools`.

### Connection

| | |
|---|---|
| `session_start` | Connect to a server and its agent. Every other tool needs it. Several sessions can be open at once — one per backend of a proxied network |
| `session_reset` | Disconnect every bot, keeping the connection. Use between independent tests. World state is **not** rolled back. `close: true` ends the session instead |

### Players

| | |
|---|---|
| `bot_spawn` | Connect a bot and wait until it is standing in the world. UUID derives from the name |
| `bot_inspect` | What the bot's client was actually sent: menu contents, messages (chat, action bar, title, subtitle), boss bars and the sidebar scoreboard |
| `bot_run_scenario` | Run a whole scenario. Stops at the first failure with evidence attached |

### Server

| | |
|---|---|
| `server_info` | Version, TPS, players online, installed plugins, capture statistics |
| `command_exec` | Run a command as the console or as a player. **Changes the server** — absent entirely unless `read-only: false` |

### World and state

| | |
|---|---|
| `state_query` `kind="player"` | Position, gamemode, op, IP, and any permission nodes you name |
| `state_query` `kind="block"` | The block at a coordinate |
| `state_query` `kind="inventory"` | The menu a player has open — the only place a plugin GUI's contents exist |

### Events and logs

| | |
|---|---|
| `events_summary` | Counts by event type. Call this before `events_query` — it stays small however busy the server is |
| `events_query` | Individual events, filtered by type and player, paged by cursor |
| `logs_query` | Logs by minimum severity and regular expression |
| `exceptions_recent` | Distinct exceptions with occurrence counts and first-seen times. Pass `hash`