vitaminmcp 3.0.1 → 3.0.3

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,7 +43,7 @@ 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 1.21.11, from one install
 
 ## Requires
 

package/checksums.json

@@ -1,14 +1,14 @@
 {
-  "version": "3.0.1",
+  "version": "3.0.3",
   "jars": {
-    "mcp-server.jar": "d2873f9e4d64a8aad41e2529dc337697343b377d4a5d892d7b618d3476309426"
+    "mcp-server.jar": "e077b0ab2ea776f4d57560c260818f0b9bb7ed7e76418e513fcdcc8a110a3801"
   },
   "assets": {
-    "bot-runner-win-x64.exe": "e4ed541a46bdb338d566e1b036acc786864d6b3cefcdc6b4272952ab1e265a66",
-    "bot-runner-linux-x64": "9b2a202455a88870d6a4d1afe0b23b8e287e620ca213b36c2fbe6d2f4699d10e",
-    "bot-runner-linux-arm64": "077c8b45b14ba2419700ddf0607e92d35ffe1f134e89db42ccc6d927f002355e",
-    "bot-runner-darwin-x64": "7e30f2c345ddcd7fc16c7d94849ef3dbd0543c184d84606562744d0c3d98e990",
-    "bot-runner-darwin-arm64": "9f581bcbcba6f995500c3d93d45d0d05bc9aad582f0824d57f4f9beca208a9b1",
+    "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-viewer-win-x64.tgz": "e39a36cdf92b9223aa7c9610f8231afc7a577e8ed007bc3571895bd945baf3e1"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitaminmcp",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "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/src/bots.mjs

@@ -5,6 +5,7 @@ import { stopAllViews, stopView as stopBotView, view as startView } from './view
 
 import { collect, forget } from './clientview.mjs';
 import { addressField, identity } from './identity.mjs';
+import { answerResourcePacks, describeProgress, traceProgress } from './join.mjs';
 
 /** How long a bot has to get from a socket to standing in the world. */
 const LOGIN_TIMEOUT_MILLIS = 30_000;
@@ -55,13 +56,19 @@ export class BotRegistry {
     );
     loadPathfinder(bot);
 
+    // Both before anything is awaited. A server can push a resource pack the moment login
+    // succeeds, and a request that arrives before its listener does is a connection that
+    // hangs in configuration until the timeout below gives up on it.
+    answerResourcePacks(bot);
+    const progress = traceProgress(bot);
+
     // Before waiting to join, not after: messages are events, and a plugin that greets or refuses
     // on join says so within a tick of the bot arriving. Attaching afterwards loses exactly the
     // messages most worth having.
     collect(bot, name);
 
     try {
-      await joined(bot, name);
+      await joined(bot, name, progress);
     } catch (failure) {
       quietly(() => bot.end());
       throw failure;
@@ -223,7 +230,7 @@ async function worldKnown(bot, name) {
 }
 
 /** Resolves when the bot is in the world; rejects on a kick, an error, or the timeout. */
-function joined(bot, name) {
+function joined(bot, name, progress) {
   return new Promise((resolve, reject) => {
     const finish = (settleFn, value) => {
       clearTimeout(timer);
@@ -238,7 +245,10 @@ function joined(bot, name) {
     const onError = (error) => finish(reject, error);
 
     const timer = setTimeout(
-      () => finish(reject, new Error(`Bot ${name} did not join within ${LOGIN_TIMEOUT_MILLIS}ms`)),
+      () => finish(reject, new Error(
+        `Bot ${name} did not join within ${LOGIN_TIMEOUT_MILLIS}ms `
+          + `(${describeProgress(bot, progress)})`,
+      )),
       LOGIN_TIMEOUT_MILLIS,
     );
 

package/runner/src/join.mjs

@@ -0,0 +1,93 @@
+/**
+ * Getting a bot from an open socket to standing in the world.
+ *
+ * Since 1.20.2 that path runs through the configuration phase, where the server may hold the
+ * connection open waiting for answers a headless client has no reason to send on its own.
+ * minecraft-protocol answers the vanilla ones (client settings, known packs, finish), and what is
+ * left over is here.
+ */
+
+/**
+ * The client's answers to a resource pack request — vanilla's `ResourcePack.Action` ordinals.
+ *
+ * Only the two used below are named. `DECLINED` is deliberately not among them: a plugin that
+ * forces a pack kicks on a decline, and a bot that cannot join is no better than one that hangs.
+ */
+const ACCEPTED = 3;
+const SUCCESSFULLY_LOADED = 0;
+
+/**
+ * Answers every resource pack the server sends, without downloading it.
+ *
+ * A plugin that pushes a pack from `AsyncPlayerConnectionConfigureEvent` blocks that connection
+ * until the client reports what became of the pack, and until then no `PlayerJoinEvent` happens
+ * and no play state is entered. mineflayer only *emits* `resourcePack` and leaves the answer to
+ * the bot author, so a bot that never answers waits out the whole login timeout on a server that
+ * would have let it in. That is what happens on any server hosting its own pack — CraftEngine,
+ * Oraxen, ItemsAdder — which is most of them.
+ *
+ * Nothing is fetched: the URL is usually only reachable from inside the network the server is on,
+ * and a test bot has no use for textures. `SUCCESSFULLY_LOADED` is what a client that applied the
+ * pack reports, and it is the only answer that satisfies both a required pack and an optional one.
+ *
+ * `bot.acceptResourcePack()` is not used for this. It answers with mineflayer's own tracked
+ * `latestUUID`, which is a `uuid-1345` object where the protocol writer expects the string form —
+ * it serialises to the nil UUID, naming a pack the server has never heard of, and the connection
+ * goes on waiting. The uuid is echoed straight back off the request here instead.
+ */
+export function answerResourcePacks(bot) {
+  const client = bot._client;
+
+  const answer = (request) => {
+    // ACCEPTED first, then the terminal result, in the order a real client reports them: a server
+    // that tracks the intermediate state sees the same sequence it would see from a player.
+    send(client, request, ACCEPTED);
+    send(client, request, SUCCESSFULLY_LOADED);
+  };
+
+  // 1.20.3 renamed the request and started identifying packs by uuid; both names are registered
+  // because only one of them exists in any given version's protocol.
+  client.on('add_resource_pack', answer);
+  client.on('resource_pack_send', answer);
+}
+
+/** One response, built from whatever identified the request, since that differs by version. */
+function send(client, request, result) {
+  const response = { result };
+  if (request?.uuid !== undefined) {
+    response.uuid = request.uuid;
+  }
+  if (request?.hash !== undefined) {
+    response.hash = request.hash;
+  }
+
+  try {
+    client.write('resource_pack_receive', response);
+  } catch (error) {
+    // A bot that cannot answer is about to time out with a message that says where it stopped.
+    // Throwing from a packet handler would instead take the whole runner, and every other bot in
+    // it, down with an unhandled error.
+    process.stderr.write(`could not answer a resource pack request: ${error?.message ?? error}\n`);
+  }
+}
+
+/**
+ * Records how far a connection got, so a failure can say so.
+ *
+ * `did not join within 30000ms` is the same sentence whether the server refused the handshake,
+ * dropped the login, or is sitting in configuration waiting for something. The protocol state and
+ * the last packet that arrived separate those three at a glance, and cost one listener.
+ */
+export function traceProgress(bot) {
+  const trace = { packet: null };
+  bot._client.on('packet', (_data, meta) => {
+    trace.packet = meta?.name ?? null;
+  });
+  return trace;
+}
+
+/** Where the connection had got to, in the words the protocol uses for it. */
+export function describeProgress(bot, trace) {
+  return `last state: ${bot._client?.state ?? 'unknown'}, `
+    + `last packet received: ${trace?.packet ?? 'none'}`;
+}