verifying-a-minecraft-plugin

Verifying a Minecraft plugin with VitaminMCP

Real bots connect over the Minecraft protocol while an agent inside the server reports what happened. This is the only thing that answers "does it actually work" — a build passing says nothing about whether the server boots, and a plugin that boots can still refuse silently.

Order of work

1. session_start — every other tool depends on it
2. Observe before acting: logs_query, exceptions_recent, events_summary, state_query
3. Spawn bots and drive them only once you know the server's current state
4. Once the steps are known, hand the whole sequence to bot_run_scenario
5. Wait with wait_for, never by sleeping

1. Connecting

On the same machine, session_start takes no arguments. The agent writes its host, both ports and its token to ~/.vitaminmcp/agents/<port>.properties while it runs, and this reads them. The response reports resolvedFrom, so a session that connected to something unexpected says so.

Pass only what differs:

• mcpPort — which agent, when several run on this machine. A proxied network is several servers, one agent each, and with more than one running an omitted mcpPort is an error that lists them rather than a guess
• session — a name for this connection. Several sessions can be open at once, which is what a proxied network needs: one per backend, each with its own agent. Opening one never disturbs the others, so bots stay connected. Name them (lobby, survival) and pass session to every later call — it is optional only while exactly one is open
• port — the Minecraft port bots connect to, which on a proxied network is the proxy's
• host and token — required together for a server on another machine. A token minted locally says nothing about a remote server and is deliberately not sent there. The token is the auth-token in that server's plugins/VitaminMCP/config.yml; it is a credential, so ask the user for it rather than hunting for it
• tls: "true" when the remote agent serves HTTPS, plus tlsFingerprint if its certificate is self-signed. The agent prints both at startup