vitaminmcp 3.0.3 → 3.1.1

package/README.md

@@ -43,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.11, 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.3",
+  "version": "3.1.1",
   "jars": {
-    "mcp-server.jar": "e077b0ab2ea776f4d57560c260818f0b9bb7ed7e76418e513fcdcc8a110a3801"
+    "mcp-server.jar": "423c885926a6c5f82d1c403ce01592afabfcc0646b756c5ce7370a0a88be09b1"
   },
   "assets": {
-    "bot-runner-win-x64.exe": "19cec3a83b03611c29808aad3bc3f395d8ace7202ead621a6bd0eb9dd5dc03bf",
-    "bot-runner-linux-x64": "63443c1b796d1ef8132bdb7212860462db88b020948d53ca940e468f7fa26c9a",
-    "bot-runner-linux-arm64": "871b9ce95e5f0411451935bcb2cf11b1151ca82d17448dda314eae8f4c6d3e41",
-    "bot-runner-darwin-x64": "f69a7b78c936fd183eeb1bfb2734a7d54c6d34d36d61532ea0738c818bc195d9",
-    "bot-runner-darwin-arm64": "81e30798ad2d06aced01b2fea076ed5c6a334debe96ae0dd12213aa961c696b9",
+    "bot-runner-win-x64.exe": "0f97651dd8bdc9861b587780ced4b94711ccaf52e5383ca1d61796b89c6c9947",
+    "bot-runner-linux-x64": "c178ef44dfb36f9e0fab3b2e78ba954e670bc0e227c49a2ef00de345ef96c6d6",
+    "bot-runner-linux-arm64": "65cd7adb1c35fbfe20671b59f9bb95b15ba9b0678646b3c4ce53d24e93024617",
+    "bot-runner-darwin-x64": "8c67b91564c8db96e27c817e0adaa778426ba5cc300ea6e2cd71c6aeb00e9737",
+    "bot-runner-darwin-arm64": "a0a6467a8fe08254fa4d1e830d16fad3368d6f8e8fb2ba18e078a7073243cbb9",
     "bot-runner-viewer-win-x64.tgz": "e39a36cdf92b9223aa7c9610f8231afc7a577e8ed007bc3571895bd945baf3e1"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitaminmcp",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "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": [
@@ -25,7 +25,8 @@
   "type": "module",
   "dependencies": {
     "mineflayer": "^4.37.1",
-    "mineflayer-pathfinder": "2.4.5"
+    "mineflayer-pathfinder": "2.4.5",
+    "prismarine-auth": "^3.1.1"
   },
   "bin": {
     "vitaminmcp": "bin/vitaminmcp.mjs"

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

@@ -1,4 +1,8 @@
 import mineflayer from 'mineflayer';
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import prismarineAuth from 'prismarine-auth';
 import { configurePathfinder, loadPathfinder, moveTo } from './movement.mjs';
 import { reachable } from './movement.mjs';
 import { stopAllViews, stopView as stopBotView, view as startView } from './viewer.mjs';
@@ -7,6 +11,12 @@ import { collect, forget } from './clientview.mjs';
 import { addressField, identity } from './identity.mjs';
 import { answerResourcePacks, describeProgress, traceProgress } from './join.mjs';
 
+const { Authflow } = prismarineAuth;
+
+const DEFAULT_ACCOUNTS_DIRECTORY = resolve(
+  process.env.VITAMINMCP_ACCOUNTS_DIR ?? join(homedir(), '.vitaminmcp', 'accounts'),
+);
+
 /** How long a bot has to get from a socket to standing in the world. */
 const LOGIN_TIMEOUT_MILLIS = 30_000;
 
@@ -28,16 +38,19 @@ export class BotRegistry {
 
   #version;
 
+  #accounts;
+
   #bots = new Map();
 
-  constructor(host, port, version) {
+  constructor(host, port, version, accounts = new MicrosoftAccounts()) {
     this.#host = host;
     this.#port = port;
     this.#version = version;
+    this.#accounts = accounts;
   }
 
   /** Connects a bot and waits until it is standing in the world. */
-  async spawn(name, clientIp) {
+  async spawn(name, clientIp, auth = 'offline', account = '') {
     // The Java runner overwrites the map entry, so a repeated spawn is not an error there and must
     // not become one here. Closing the old socket first is the only difference: leaving it open
     // would hold a player slot under a name this runner no longer tracks.
@@ -47,12 +60,40 @@ export class BotRegistry {
       quietly(() => existing.quit());
     }
 
-    const id = identity(name);
-    // Normal logins use the server's ordinary offline UUID for this name, which stays stable when
-    // a test reuses the same bot. A clientIp is an explicit request for the opt-in BungeeCord
-    // forwarding handshake used by tests that need a spoofed address or UUID.
+    const mode = authenticationMode(auth);
+    if (mode === 'microsoft' && clientIp?.trim()) {
+      throw new Error('clientIp forwarding is only available for offline bots');
+    }
+
+    const accountKey = account?.trim() || name;
+    const authenticated = mode === 'microsoft'
+      ? await this.#accounts.require(accountKey)
+      : null;
+    if (authenticated && authenticated.profile.name.toLowerCase() !== name.toLowerCase()) {
+      throw new Error(
+        `Microsoft account '${accountKey}' owns profile '${authenticated.profile.name}', `
+          + `not '${name}'. Call bot_spawn with name='${authenticated.profile.name}'.`,
+      );
+    }
+
+    const id = authenticated
+      ? identity(authenticated.profile.name, { uuid: canonicalUuid(authenticated.profile.id) })
+      : identity(name);
     const bot = mineflayer.createBot(
-      connectionOptions(this.#host, this.#port, this.#version, id, clientIp),
+      connectionOptions(
+        this.#host,
+        this.#port,
+        this.#version,
+        id,
+        clientIp,
+        mode,
+        accountKey,
+        authenticated?.profilesFolder,
+        (code) => {
+          this.#accounts.invalidate(accountKey);
+          throw new Error(loginRequired(accountKey, code));
+        },
+      ),
     );
     loadPathfinder(bot);
 
@@ -84,7 +125,11 @@ export class BotRegistry {
     configurePathfinder(bot);
     await settle(bot, name);
     await worldKnown(bot, name);
-    return position(bot);
+    return {
+      ...position(bot),
+      playerName: id.name,
+      uuid: id.uuid,
+    };
   }
 
   async move(name, x, y, z, mode, timeoutMillis) {
@@ -144,22 +189,151 @@ export class BotRegistry {
   }
 }
 
-/** Builds a normal login, adding BungeeCord forwarding only for an explicit clientIp test. */
-export function connectionOptions(host, port, version, id, clientIp) {
+/** Builds a login, adding BungeeCord forwarding only for an explicit offline-mode IP test. */
+export function connectionOptions(
+  host,
+  port,
+  version,
+  id,
+  clientIp,
+  auth = 'offline',
+  account = id.name,
+  profilesFolder = DEFAULT_ACCOUNTS_DIRECTORY,
+  onMsaCode = undefined,
+) {
+  const mode = authenticationMode(auth);
   const options = {
     host,
     port,
-    username: id.name,
-    auth: 'offline',
+    username: mode === 'microsoft' ? account : id.name,
+    auth: mode,
     version,
     checkTimeoutInterval: LOGIN_TIMEOUT_MILLIS,
+    // mineflayer's default console.logs bot errors, and stdout is the protocol channel.
+    logErrors: false,
   };
-  if (clientIp && clientIp.trim()) {
+  if (mode === 'microsoft') {
+    options.profilesFolder = profilesFolder;
+    options.onMsaCode = onMsaCode;
+  } else if (clientIp && clientIp.trim()) {
     options.fakeHost = addressField(host, clientIp.trim(), id);
   }
   return options;
 }
 
+/** Microsoft device-code authentication that survives a failed first spawn through its cache. */
+export class MicrosoftAccounts {
+  #directory;
+
+  #createFlow;
+
+  #states = new Map();
+
+  constructor(
+    directory = DEFAULT_ACCOUNTS_DIRECTORY,
+    createFlow = (account, profilesFolder, onCode) => new Authflow(
+      account,
+      profilesFolder,
+      undefined,
+      onCode,
+    ),
+  ) {
+    this.#directory = resolve(directory);
+    this.#createFlow = createFlow;
+  }
+
+  async require(account) {
+    let state = this.#states.get(account);
+    if (!state) {
+      state = this.#start(account);
+      this.#states.set(account, state);
+    }
+    if (state.status === 'starting') {
+      await state.firstUpdate;
+    }
+    if (state.status === 'ready') {
+      return { profile: state.profile, profilesFolder: this.#directory };
+    }
+    if (state.status === 'failed') {
+      this.#states.delete(account);
+      throw state.error;
+    }
+    throw new Error(loginRequired(account, state.code));
+  }
+
+  invalidate(account) {
+    this.#states.delete(account);
+  }
+
+  #start(account) {
+    let announce;
+    const state = {
+      status: 'starting',
+      code: null,
+      profile: null,
+      error: null,
+      firstUpdate: new Promise((resolveFirstUpdate) => {
+        announce = resolveFirstUpdate;
+      }),
+    };
+
+    const authenticate = async () => {
+      await mkdir(this.#directory, { recursive: true, mode: 0o700 });
+      const flow = this.#createFlow(account, this.#directory, (code) => {
+        state.status = 'pending';
+        state.code = code;
+        announce();
+      });
+      const result = await flow.getMinecraftJavaToken({
+        fetchProfile: true,
+        fetchCertificates: false,
+      });
+      if (!result.profile?.name || !result.profile?.id) {
+        throw new Error(`Microsoft account '${account}' has no Minecraft Java profile`);
+      }
+      state.status = 'ready';
+      state.profile = result.profile;
+      announce();
+    };
+
+    authenticate().catch((error) => {
+      state.status = 'failed';
+      state.error = error instanceof Error ? error : new Error(String(error));
+      announce();
+    });
+    return state;
+  }
+}
+
+function authenticationMode(auth) {
+  const mode = String(auth || 'offline').toLowerCase();
+  if (mode !== 'offline' && mode !== 'microsoft') {
+    throw new Error(`unknown bot auth '${auth}'; use offline or microsoft`);
+  }
+  return mode;
+}
+
+function loginRequired(account, code) {
+  const uri = code?.verification_uri || 'https://www.microsoft.com/link';
+  const userCode = code?.user_code || '(request a new code)';
+  return `Microsoft login required for account '${account}'. Open ${uri} and enter code `
+    + `${userCode}, complete sign-in, then call bot_spawn again with the same name and account.`;
+}
+
+function canonicalUuid(value) {
+  const compact = String(value).replaceAll('-', '');
+  if (!/^[0-9a-fA-F]{32}$/.test(compact)) {
+    throw new Error(`Microsoft returned an invalid Minecraft profile UUID: ${value}`);
+  }
+  return [
+    compact.slice(0, 8),
+    compact.slice(8, 12),
+    compact.slice(12, 16),
+    compact.slice(16, 20),
+    compact.slice(20),
+  ].join('-').toLowerCase();
+}
+
 function position(bot) {
   const at = bot.entity?.position;
   return at ? { x: at.x, y: at.y, z: at.z } : { x: 0, y: 0, z: 0 };

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));
     }
   }
 
@@ -38,7 +39,9 @@ export class Dispatch {
     switch (verb) {
       case protocol.SPAWN: {
         const clientIp = command.length > 2 ? command[2] : '';
-        return positionLine(verb, await this.#bots.spawn(command[1], clientIp));
+        const auth = command.length > 3 ? command[3] : 'offline';
+        const account = command.length > 4 ? command[4] : '';
+        return spawnLine(verb, await this.#bots.spawn(command[1], clientIp, auth, account));
       }
 
       case protocol.DESPAWN: {
@@ -301,3 +304,15 @@ function positionLine(verb, at) {
     protocol.javaDouble(at.z),
   );
 }
+
+function spawnLine(verb, at) {
+  return protocol.encode(
+    protocol.OK,
+    verb,
+    protocol.javaDouble(at.x),
+    protocol.javaDouble(at.y),
+    protocol.javaDouble(at.z),
+    protocol.sanitize(at.playerName),
+    protocol.sanitize(at.uuid),
+  );
+}