vitaminmcp 1.5.0

package/README.md

@@ -0,0 +1,75 @@
+# vitaminmcp
+
+**MCP server for testing Minecraft plugins.** Drives a real Paper/Purpur server and real protocol
+bots from an AI agent, so a plugin can be tested end to end without opening the game.
+
+This package is the launcher. It fetches the jars it needs on first run and speaks stdio to your
+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:
+
+```json
+{
+  "mcpServers": {
+    "vitaminmcp": {
+      "command": "npx",
+      "args": ["-y", "vitaminmcp"]
+    }
+  }
+}
+```
+
+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:
+
+> **Prompt:** Set up VitaminMCP on my Minecraft server at ~/servers/test and connect to it.
+
+Once the plugin is running, `session_start` needs no arguments for a server on this machine: the
+agent leaves its host, ports and token where this server reads them.
+
+## What you get
+
+- 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
+- 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
+
+## Requires
+
+- **Java 21 or later** on this machine — the jars run on the JVM. Point `JAVA_HOME` at it, or have
+  `java` on `PATH`
+- **Paper 1.21 or later** on the Minecraft server, with `VitaminMCP.jar` in its `plugins/`
+
+## Environment
+
+| | |
+|---|---|
+| `JAVA_HOME` | the JDK to run the jars with |
+| `VITAMINMCP_HOME` | where jars and agent handshakes are kept. Default `~/.vitaminmcp` |
+| `VITAMINMCP_TOKEN` | an agent token, for a server that leaves no local handshake |
+| `VITAMINMCP_SERVER_JAR` | run this `mcp-server.jar` instead of a downloaded one |
+| `VITAMINMCP_RUNNER_JAR` | use this bot runner instead of a downloaded one |
+
+## What it downloads
+
+On first run, from [the GitHub release](https://github.com/Backas03/VitaminMCP-minecraft/releases)
+matching this package's version, into `~/.vitaminmcp/jars/<version>/`:
+
+- `mcp-server.jar` (~2 MB) — waited for, since nothing works without it
+- `bot-runner.jar` (~93 MB) — fetched in the background, because only bots need it. A client that
+  never spawns one never waits for it
+
+Both are checked against a SHA-256 pinned into this package at publish time. A file that does not
+match is deleted rather than run.
+
+Full documentation, design notes and the plugin itself:
+**[github.com/Backas03/VitaminMCP-minecraft](https://github.com/Backas03/VitaminMCP-minecraft)**
+
+MIT.

package/bin/vitaminmcp.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { BOT_RUNNER_JAR, MCP_SERVER_JAR, ensureJar, jarPath } from '../lib/jars.mjs';
+import { checkJava, findJava } from '../lib/java.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * stdout is the MCP channel and carries nothing but JSON-RPC. Everything this launcher has to say
+ * goes to stderr, where a client shows it as server output rather than trying to parse it.
+ */
+function say(message) {
+  process.stderr.write(`[vitaminmcp] ${message}\n`);
+}
+
+function die(message) {
+  process.stderr.write(`[vitaminmcp] ${message}\n`);
+  process.exit(1);
+}
+
+async function version() {
+  const manifest = await fs.readFile(path.join(HERE, '..', 'package.json'), 'utf8');
+  return JSON.parse(manifest).version;
+}
+
+const HELP = `vitaminmcp — MCP server for testing Minecraft plugins
+
+  Launched by an MCP client, not usually by hand. To connect it to Claude Code:
+
+    claude mcp add vitaminmcp -- npx -y vitaminmcp
+
+  The agent plugin still has to be installed on the Minecraft server itself. Once this server is
+  connected, the /mcp__vitaminmcp__setup command walks through it.
+
+Options
+  --help        this text
+  --version     the version this launcher will run
+  --jars        download the jars and print where they are, without starting anything
+
+Environment
+  JAVA_HOME               the JDK to run the jars with; Java 21 or later
+  VITAMINMCP_HOME         where jars and agent handshakes are kept (default ~/.vitaminmcp)
+  VITAMINMCP_TOKEN        an agent token, for a server that leaves no local handshake
+  VITAMINMCP_SERVER_JAR   run this mcp-server jar instead of a downloaded one
+  VITAMINMCP_RUNNER_JAR   use this bot runner instead of a downloaded one
+`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const release = await version();
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stderr.write(HELP);
+    return 0;
+  }
+  if (argv.includes('--version') || argv.includes('-v')) {
+    process.stderr.write(`${release}\n`);
+    return 0;
+  }
+
+  const java = findJava();
+  const usable = checkJava(java);
+  if (!usable.ok) {
+    die(usable.message);
+  }
+
+  // The server jar is small and nothing works without it, so it is waited for. The runner is
+  // ninety megabytes and only bots need it, so it is fetched alongside: a client that never
+  // spawns a bot never waits for it, and one that does waits inside a tool call rather than
+  // inside a startup timeout.
+  let server = process.env.VITAMINMCP_SERVER_JAR;
+  if (!server) {
+    try {
+      server = await ensureJar(release, MCP_SERVER_JAR, { log: say });
+    } catch (error) {
+      die(String(error.message ?? error));
+    }
+  }
+
+  const runner = process.env.VITAMINMCP_RUNNER_JAR ?? jarPath(release, BOT_RUNNER_JAR);
+  const runnerReady = process.env.VITAMINMCP_RUNNER_JAR
+    ? Promise.resolve(runner)
+    : ensureJar(release, BOT_RUNNER_JAR, { log: say }).catch((error) => {
+        say(`the bot runner could not be downloaded: ${error.message ?? error}`);
+        say('Everything except bots still works. Retry by restarting this server.');
+      });
+
+  if (argv.includes('--jars')) {
+    await runnerReady;
+    process.stderr.write(`${server}\n${runner}\n`);
+    return 0;
+  }
+
+  return await run(java, server, runner);
+}
+
+/**
+ * Runs the server jar, and lives exactly as long as it does.
+ *
+ * A download still in flight is abandoned when the server exits rather than held on to: the
+ * `.part` file it leaves is claimed again by the next start, and a client waiting on a process
+ * that no longer serves anything is worse than a jar fetched twice.
+ */
+function run(java, server, runner) {
+  const child = spawn(java, ['-jar', server], {
+    stdio: 'inherit',
+    env: { ...process.env, VITAMINMCP_RUNNER_JAR: runner },
+  });
+
+  return new Promise((resolve) => {
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      process.on(signal, () => child.kill(signal));
+    }
+
+    child.on('error', (error) => {
+      say(`could not start java: ${error.message}`);
+      resolve(1);
+    });
+
+    child.on('exit', (code, signal) => {
+      resolve(signal ? 1 : (code ?? 0));
+    });
+  });
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error) => die(String(error?.stack ?? error)),
+);

package/checksums.json

@@ -0,0 +1,7 @@
+{
+  "version": "1.5.0",
+  "jars": {
+    "mcp-server.jar": "edf2c4e468751e38c7b31f30148a28c417f16762e5519643fdf287f789a9a5f5",
+    "bot-runner.jar": "f681c8049f2ee6b194b1ae5bb07a5eedbce89f816aa89eac0b713e5adbb207b9"
+  }
+}

package/lib/jars.mjs

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+const RELEASES = 'https://github.com/Backas03/VitaminMCP-minecraft/releases/download';
+
+/** The jar this package launches, and the one it launches in turn. */
+export const MCP_SERVER_JAR = 'mcp-server.jar';
+export const BOT_RUNNER_JAR = 'bot-runner.jar';
+
+let checksumsPromise;
+
+const REPORT = 'https://github.com/Backas03/VitaminMCP-minecraft/issues';
+
+/**
+ * The exact bytes this version of the package expects, stamped in at release.
+ *
+ * Pinning them here rather than trusting whatever the release currently serves is the point: a
+ * release asset can be replaced after the fact, and a published npm version cannot.
+ *
+ * The file names the version it was stamped for, and that is checked. Otherwise the one mistake
+ * this design invites — publishing a version bump without re-stamping — would ship a package that
+ * downloads one release and checks it against another, and every install would fail on a hash
+ * mismatch that reads exactly like a compromised download.
+ */
+async function checksums(version) {
+  checksumsPromise ??= fs
+    .readFile(path.join(HERE, '..', 'checksums.json'), 'utf8')
+    .then(JSON.parse)
+    .catch((cause) => {
+      throw new Error(
+        'This package was published without checksums.json, so it cannot verify what it ' +
+          `downloads and will not download anything. Please report it at ${REPORT}.`,
+        { cause },
+      );
+    });
+
+  const stamped = await checksumsPromise;
+  if (stamped.version !== version) {
+    throw new Error(
+      `This package is version ${version} but its checksums were stamped for ` +
+        `${stamped.version}, so it cannot tell a bad download from a mismatched one. Nothing ` +
+        `was installed. Please report it at ${REPORT}.`,
+    );
+  }
+  return stamped.jars ?? {};
+}
+
+/**
+ * Where downloaded jars live: one directory per version, so switching versions never mixes them.
+ *
+ * The same root the agent writes its handshake into, so one variable moves everything VitaminMCP
+ * keeps outside the project.
+ */
+export function cacheDirectory(version) {
+  const root = process.env.VITAMINMCP_HOME || path.join(os.homedir(), '.vitaminmcp');
+  return path.join(root, 'jars', version);
+}
+
+/** A jar already on this machine, or null. Never downloads. */
+export async function cachedJar(version, name) {
+  const file = path.join(cacheDirectory(version), name);
+  try {
+    await fs.access(file);
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Makes sure one jar is on this machine, downloading it if not, and returns its path.
+ *
+ * Downloads land on a `.part` file and are renamed once the hash matches, so an interrupted
+ * download is never mistaken for a finished one — and the server, which waits for exactly that
+ * rename, never opens a half-written jar.
+ */
+export async function ensureJar(version, name, { log = () => {} } = {}) {
+  const directory = cacheDirectory(version);
+  const file = path.join(directory, name);
+
+  const existing = await cachedJar(version, name);
+  if (existing) {
+    return existing;
+  }
+
+  const expected = (await checksums(version))[name];
+  if (!expected) {
+    throw new Error(`checksums.json does not cover ${name}, so it will not be downloaded.`);
+  }
+
+  await fs.mkdir(directory, { recursive: true });
+  const partial = `${file}.part`;
+  const url = `${RELEASES}/${version}/${name}`;
+
+  // Claimed before the request goes out, not after it answers. The server waits on this file to
+  // decide whether a jar is coming or simply absent, and between spawning it and the first byte
+  // arriving there is easily enough time for it to ask.
+  await fs.writeFile(partial, '');
+
+  log(`downloading ${name} (${version})`);
+
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok || !response.body) {
+    throw new Error(
+      `Could not download ${name}: ${response.status} ${response.statusText}\n  ${url}`,
+    );
+  }
+
+  const hash = createHash('sha256');
+  const source = Readable.fromWeb(response.body);
+  source.on('data', (chunk) => hash.update(chunk));
+
+  try {
+    await pipeline(source, createWriteStream(partial));
+
+    const actual = hash.digest('hex');
+    if (actual !== expected) {
+      throw new Error(
+        `${name} does not match the checksum this package was published with.\n` +
+          `  expected ${expected}\n` +
+          `  received ${actual}\n` +
+          `  from     ${url}\n` +
+          'Nothing was installed. Please report this.',
+      );
+    }
+
+    await fs.rename(partial, file);
+  } catch (error) {
+    await fs.rm(partial, { force: true });
+    throw error;
+  }
+
+  log(`${name} ready`);
+  return file;
+}
+
+/** Where a jar will be once it has downloaded, whether or not it has. */
+export function jarPath(version, name) {
+  return path.join(cacheDirectory(version), name);
+}

package/lib/java.mjs

@@ -0,0 +1,67 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/** The floor the jars are compiled against. Below it they will not load at all. */
+export const REQUIRED_JAVA = 21;
+
+/**
+ * The java to run the jars with: JAVA_HOME if it points at one, otherwise whatever is on PATH.
+ *
+ * JAVA_HOME wins because a machine with several JDKs usually means one of them was chosen
+ * deliberately, and PATH is the one nobody remembers setting.
+ */
+export function findJava() {
+  const home = process.env.JAVA_HOME;
+  if (home) {
+    const candidate = path.join(home, 'bin', process.platform === 'win32' ? 'java.exe' : 'java');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return process.platform === 'win32' ? 'java.exe' : 'java';
+}
+
+/**
+ * Checks the java that will actually be used, and says what is wrong in terms of a fix.
+ *
+ * Worth doing before spawning: java's own failure for a too-old runtime is
+ * `UnsupportedClassVersionError` naming class file version 65, which is a puzzle rather than a
+ * message, and an MCP client shows it — if it shows anything — as a server that died at startup.
+ */
+export function checkJava(java) {
+  const probe = spawnSync(java, ['-version'], { encoding: 'utf8' });
+
+  if (probe.error) {
+    return {
+      ok: false,
+      message:
+        `No Java found. VitaminMCP runs on the JVM, so it needs Java ${REQUIRED_JAVA} or later ` +
+        `on this machine.\n` +
+        `  Tried: ${java}\n` +
+        `  Install a JDK (https://adoptium.net/), or point JAVA_HOME at one you already have.`,
+    };
+  }
+
+  // Every JVM prints its version to stderr, and has since before anyone thought to standardise it.
+  const output = `${probe.stderr || ''}${probe.stdout || ''}`;
+  const match = output.match(/version "(\d+)(?:\.(\d+))?/);
+  if (!match) {
+    // An unrecognised banner is not a reason to refuse; the jars themselves will say so if it
+    // really is too old.
+    return { ok: true, version: null };
+  }
+
+  const major = match[1] === '1' ? Number(match[2]) : Number(match[1]);
+  if (major < REQUIRED_JAVA) {
+    return {
+      ok: false,
+      version: major,
+      message:
+        `Java ${major} is too old — VitaminMCP needs ${REQUIRED_JAVA} or later.\n` +
+        `  Using: ${java}\n` +
+        `  Install a newer JDK (https://adoptium.net/), or point JAVA_HOME at one you already have.`,
+    };
+  }
+  return { ok: true, version: major };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "vitaminmcp",
+  "version": "1.5.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": [
+    "mcp",
+    "modelcontextprotocol",
+    "minecraft",
+    "paper",
+    "purpur",
+    "bukkit",
+    "plugin-testing",
+    "end-to-end-testing"
+  ],
+  "homepage": "https://github.com/Backas03/VitaminMCP-minecraft#readme",
+  "bugs": "https://github.com/Backas03/VitaminMCP-minecraft/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Backas03/VitaminMCP-minecraft.git",
+    "directory": "npm"
+  },
+  "license": "MIT",
+  "author": "Backas03",
+  "type": "module",
+  "bin": {
+    "vitaminmcp": "bin/vitaminmcp.mjs"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "checksums.json",
+    "README.md"
+  ],
+  "scripts": {
+    "stamp": "node scripts/stamp-checksums.mjs",
+    "prepublishOnly": "node scripts/stamp-checksums.mjs --verify"
+  }
+}