vitaminmcp 3.0.2 → 3.1.0

package/README.md

@@ -7,11 +7,9 @@ This package is the launcher. It fetches the jars it needs on first run and spea
 MCP client — it is not the whole product on its own: the agent is a Paper plugin, and it goes on
 the Minecraft server.
 
-```bash
-claude mcp add vitaminmcp -- npx -y vitaminmcp
-```
-
-Or in `.mcp.json`, `claude_desktop_config.json`, or whatever your client calls it:
+It speaks plain stdio, so it works in any MCP client — Claude Code, Cursor, Codex, Gemini CLI,
+Windsurf, Claude Desktop, VS Code. Register it wherever your client keeps MCP servers
+(`.mcp.json`, `.cursor/mcp.json`, `~/.gemini/settings.json`, `claude_desktop_config.json`, …):
 
 ```json
 {
@@ -24,8 +22,14 @@ Or in `.mcp.json`, `claude_desktop_config.json`, or whatever your client calls i
 }
 ```
 
-Then, in Claude Code, `/mcp__vitaminmcp__setup` walks through the other half — putting
-`VitaminMCP.jar` in the server's `plugins/`, restarting it, and connecting. Or just ask:
+Clients with a CLI take the same thing as a command, e.g.
+`claude mcp add vitaminmcp -- npx -y vitaminmcp` or
+`codex mcp add vitaminmcp -- npx -y vitaminmcp`.
+
+The server publishes a `setup` MCP prompt that walks through the other half — putting
+`VitaminMCP.jar` in the Minecraft server's `plugins/`, restarting it, and connecting. In Claude
+Code that surfaces as `/mcp__vitaminmcp__setup` (named after whatever the server was registered
+as — `/mcp` lists it); in any client, just ask:
 
 > **Prompt:** Set up VitaminMCP on my Minecraft server at ~/servers/test and connect to it.
 
@@ -39,12 +43,13 @@ agent leaves its host, ports and token where this server reads them.
 - Open, read, click and assert on inventories and plugin GUIs
 - Wait for events and conditions instead of sleeping
 - Read live server state: events, logs, exceptions, permissions
-- Paper / Purpur 1.21 through 1.21.8, from one install
+- Paper / Purpur 1.21 through 26.1, from one install
 
 ## Requires
 
 - **Java 21 or later** on this machine — the jars run on the JVM. Point `JAVA_HOME` at it, or have
-  `java` on `PATH`
+  `java` on `PATH`. (The Paper server itself needs Java 25 from 26.1 on; that is Paper's
+  requirement, and the agent loads there unchanged)
 - **Node 18.17 or later** when using the source runner fallback. If Node is absent, the launcher
   selects a pinned platform runner asset instead.
 - **Paper 1.21 or later** on the Minecraft server, with `VitaminMCP.jar` in its `plugins/`

package/checksums.json

@@ -1,14 +1,14 @@
 {
-  "version": "3.0.2",
+  "version": "3.1.0",
   "jars": {
-    "mcp-server.jar": "452ed2928e9e0a6ddcb25dab4586999012b334f9994a0aff8c305148fde0c7ae"
+    "mcp-server.jar": "f64ee16d5aaa115a9d4e019adccf830b74ebe8683d2ade5e05b7db0cf9692d66"
   },
   "assets": {
-    "bot-runner-win-x64.exe": "d263637058d5e4a894d1765cfa79de528774a36d9d4c5132c0bb5e9c5b1ae0d0",
-    "bot-runner-linux-x64": "dcac4f6a1e7c9ad9228a95cee4a59925973616eab9214b4bc81ad338ae398de5",
-    "bot-runner-linux-arm64": "08642a57deec10a1d967bc95e5e4fc35cfb4de5cdcd31c391f90829fdc569ac7",
-    "bot-runner-darwin-x64": "0f2e229cbb94ef65ff79336b517489a9c2fa715c42a86e5d4da5a2df510f48ba",
-    "bot-runner-darwin-arm64": "3e570c14a11d0df7eb84bcdce15acb5fbcabbda0f64ceb1c1f389d9ee2a43fef",
+    "bot-runner-win-x64.exe": "8af36a3e4a3678db5246777c1c8080bea230b50a742dff173758d0513df74e98",
+    "bot-runner-linux-x64": "2f344983a5558d36cf03e4bcf55e0752324d159aebefc18f711c28704cf48264",
+    "bot-runner-linux-arm64": "fa6c49b5db5b6cc84b62d295bbef2ace49305400a7480e86baa009e9629d120c",
+    "bot-runner-darwin-x64": "1769db980857d36204bf93e14bbe5ba329435032b116c8003a12043ba817168a",
+    "bot-runner-darwin-arm64": "b137677b9117af944d006ff0da0e94b524875c86ebfa2596c2b856b9ef63fd2e",
     "bot-runner-viewer-win-x64.tgz": "e39a36cdf92b9223aa7c9610f8231afc7a577e8ed007bc3571895bd945baf3e1"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitaminmcp",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "mcpName": "io.github.Backas03/vitaminmcp",
   "description": "MCP server for testing Minecraft plugins: drives a real Paper server and real protocol bots from an AI agent.",
   "keywords": [

package/runner/runner.mjs

@@ -16,6 +16,12 @@ import { Dispatch } from './src/dispatch.mjs';
 import * as protocol from './src/protocol.mjs';
 import { pingProtocol, versionForProtocol } from './src/version.mjs';
 
+// stdout is the protocol channel; a dependency's console.log (mineflayer did this on 26.1, with a
+// stack trace) desynchronises every later reply. `write` below is the only path to stdout.
+for (const level of ['log', 'info', 'debug']) {
+  console[level] = (...messages) => process.stderr.write(`${messages.map(String).join(' ')}\n`);
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   if (argv.length < 2) {

package/runner/src/actions.mjs

@@ -234,26 +234,45 @@ export function useEntity(bot, name, x, y, z, radius, type) {
     );
   }
 
-  // Both packets, in this order, because that is what a real client sends and what the Java
-  // runner reproduces: a plugin listening only for the second sees nothing without the first.
-  bot._client.write('use_entity', {
-    target: entityId,
-    mouse: INTERACT_AT,
-    x: 0.0,
-    y: 1.0,
-    z: 0.0,
-    hand: MAIN_HAND,
-    sneaking: false,
-  });
-  bot._client.write('use_entity', {
-    target: entityId,
-    mouse: INTERACT,
-    hand: MAIN_HAND,
-    sneaking: false,
-  });
+  if (interactCarriesMouseButton(bot)) {
+    // Both packets, in this order, because that is what a real client sends and what the Java
+    // runner reproduces: a plugin listening only for the second sees nothing without the first.
+    bot._client.write('use_entity', {
+      target: entityId,
+      mouse: INTERACT_AT,
+      x: 0.0,
+      y: 1.0,
+      z: 0.0,
+      hand: MAIN_HAND,
+      sneaking: false,
+    });
+    bot._client.write('use_entity', {
+      target: entityId,
+      mouse: INTERACT,
+      hand: MAIN_HAND,
+      sneaking: false,
+    });
+  } else {
+    // 26.1: one packet with a hand and a hit position; attacks have their own packet.
+    bot._client.write('use_entity', {
+      target: entityId,
+      hand: MAIN_HAND,
+      location: { x: 0.0, y: 1.0, z: 0.0 },
+      sneaking: false,
+    });
+  }
   return entityId;
 }
 
+/** Through 1.21.11 `use_entity` has a `mouse` field; from 26.1 it has a `location` instead. */
+function interactCarriesMouseButton(bot) {
+  const fields = bot.registry?.protocol?.play?.toServer?.types?.packet_use_entity?.[1];
+  if (!Array.isArray(fields)) {
+    throw new Error('The protocol definition for use_entity is missing, so the bot cannot interact with entities.');
+  }
+  return fields.some((field) => field?.name === 'mouse');
+}
+
 /** Left-clicks the nearest tracked entity. */
 export function attackEntity(bot, name, x, y, z, radius, type) {
   requireInWorld(bot, name);

package/runner/src/bots.mjs

@@ -153,6 +153,8 @@ export function connectionOptions(host, port, version, id, clientIp) {
     auth: 'offline',
     version,
     checkTimeoutInterval: LOGIN_TIMEOUT_MILLIS,
+    // mineflayer's default console.logs bot errors, and stdout is the protocol channel.
+    logErrors: false,
   };
   if (clientIp && clientIp.trim()) {
     options.fakeHost = addressField(host, clientIp.trim(), id);

package/runner/src/dispatch.mjs

@@ -30,7 +30,8 @@ export class Dispatch {
     try {
       return await this.#run(verb, command);
     } catch (error) {
-      return protocol.encode(protocol.ERROR, verb, String(error?.message ?? error));
+      // A newline in the message would become a second stdout line, read as the next reply.
+      return protocol.encode(protocol.ERROR, verb, protocol.sanitize(error?.message ?? error));
     }
   }