vitaminmcp 1.5.0 → 2.0.0

package/README.md

@@ -45,6 +45,8 @@ agent leaves its host, ports and token where this server reads them.
 
 - **Java 21 or later** on this machine — the jars run on the JVM. Point `JAVA_HOME` at it, or have
   `java` on `PATH`
+- **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/`
 
 ## Environment
@@ -55,7 +57,9 @@ agent leaves its host, ports and token where this server reads them.
 | `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 |
+| `VITAMINMCP_RUNNER_JAR` | use this runner path instead of automatic selection |
+| `VITAMINMCP_NODE` | Node executable for the source runner fallback |
+| `VITAMINMCP_NODE_RUNNER` | bundled `runner.mjs` path when Node is available |
 
 ## What it downloads
 
@@ -63,8 +67,9 @@ On first run, from [the GitHub release](https://github.com/Backas03/VitaminMCP-m
 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
+- a source Node runner when Node and the bundled runner are available — no runner asset download
+- otherwise one platform runner asset (`win-x64`, `linux-x64`, `linux-arm64`, `darwin-x64` or
+  `darwin-arm64`), checked against a SHA-256 pinned into this package
 
 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.

package/bin/vitaminmcp.mjs

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 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 {
+  MCP_SERVER_JAR, assetPath, ensureAsset, ensureJar,
+} from '../lib/jars.mjs';
 import { checkJava, findJava } from '../lib/java.mjs';
+import { checkNode, findNode, runnerAssetName } from '../lib/node.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
@@ -47,7 +51,9 @@ Environment
   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
+  VITAMINMCP_RUNNER_JAR   use this runner path instead of selecting one automatically
+  VITAMINMCP_NODE         Node executable for the source runner fallback
+  VITAMINMCP_NODE_RUNNER  path to a bundled runner.mjs when Node is available
 `;
 
 async function main() {
@@ -82,13 +88,24 @@ async function main() {
     }
   }
 
-  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.');
-      });
+  const configuredRunner = process.env.VITAMINMCP_RUNNER_JAR;
+  const node = findNode();
+  const nodeCheck = checkNode(node);
+  const sourceRunner = process.env.VITAMINMCP_NODE_RUNNER
+    ?? path.join(HERE, '..', 'runner', 'runner.mjs');
+  let runner;
+  let runnerReady;
+  if (configuredRunner) {
+    runner = configuredRunner;
+    runnerReady = Promise.resolve(runner);
+  } else if (nodeCheck.ok && existsSync(sourceRunner)) {
+    runner = sourceRunner;
+    runnerReady = Promise.resolve(runner);
+  } else {
+    const asset = runnerAssetName();
+    runner = assetPath(release, asset);
+    runnerReady = ensureAsset(release, asset, { log: say });
+  }
 
   if (argv.includes('--jars')) {
     await runnerReady;
@@ -96,6 +113,7 @@ async function main() {
     return 0;
   }
 
+  await runnerReady;
   return await run(java, server, runner);
 }
 

package/checksums.json

@@ -1,7 +1,9 @@
 {
-  "version": "1.5.0",
+  "version": "2.0.0",
   "jars": {
-    "mcp-server.jar": "edf2c4e468751e38c7b31f30148a28c417f16762e5519643fdf287f789a9a5f5",
-    "bot-runner.jar": "f681c8049f2ee6b194b1ae5bb07a5eedbce89f816aa89eac0b713e5adbb207b9"
+    "mcp-server.jar": "557ad3ad919244e31fcbc8f7ecb05c8c7744c2922a0220e0fec9eb531af77759"
+  },
+  "assets": {
+    "bot-runner-win-x64.exe": "230ea83146c9f3ade0999764e8b9dd5ca790f13fec055484237ba8e6b7d8b3bd"
   }
 }

package/lib/jars.mjs

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { createWriteStream } from 'node:fs';
+import { createReadStream, createWriteStream } from 'node:fs';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -13,9 +13,9 @@ const RELEASES = 'https://github.com/Backas03/VitaminMCP-minecraft/releases/down
 
 /** 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;
+let manifestPromise;
 
 const REPORT = 'https://github.com/Backas03/VitaminMCP-minecraft/issues';
 
@@ -53,6 +53,17 @@ async function checksums(version) {
   return stamped.jars ?? {};
 }
 
+async function assetChecksums(version) {
+  manifestPromise ??= fs
+    .readFile(path.join(HERE, '..', 'checksums.json'), 'utf8')
+    .then(JSON.parse);
+  const stamped = await manifestPromise;
+  if (stamped.version !== version) {
+    throw new Error(`This package is version ${version} but its checksums were stamped for ${stamped.version}.`);
+  }
+  return stamped.assets ?? {};
+}
+
 /**
  * Where downloaded jars live: one directory per version, so switching versions never mixes them.
  *
@@ -69,10 +80,14 @@ export async function cachedJar(version, name) {
   const file = path.join(cacheDirectory(version), name);
   try {
     await fs.access(file);
-    return file;
   } catch {
     return null;
   }
+  const expected = (await checksums(version))[name];
+  if (!expected) return null;
+  if (await verifyFileHash(file, expected)) return file;
+  await fs.rm(file, { force: true });
+  return null;
 }
 
 /**
@@ -146,3 +161,76 @@ export async function ensureJar(version, name, { log = () => {} } = {}) {
 export function jarPath(version, name) {
   return path.join(cacheDirectory(version), name);
 }
+
+export function assetCacheDirectory(version) {
+  const root = process.env.VITAMINMCP_HOME || path.join(os.homedir(), '.vitaminmcp');
+  return path.join(root, 'assets', version);
+}
+
+export async function cachedAsset(version, name) {
+  const file = path.join(assetCacheDirectory(version), name);
+  try {
+    await fs.access(file);
+  } catch {
+    return null;
+  }
+  const expected = (await assetChecksums(version))[name];
+  if (!expected) return null;
+  if (await verifyFileHash(file, expected)) return file;
+  await fs.rm(file, { force: true });
+  return null;
+}
+
+/** Fetches a pinned platform asset only after Node fallback selection has failed. */
+export async function ensureAsset(version, name, { log = () => {} } = {}) {
+  const directory = assetCacheDirectory(version);
+  const file = path.join(directory, name);
+  const existing = await cachedAsset(version, name);
+  if (existing) return existing;
+  const expected = (await assetChecksums(version))[name];
+  if (!expected) throw new Error(`checksums.json does not cover asset ${name}, so it will not be downloaded.`);
+  await fs.mkdir(directory, { recursive: true });
+  const partial = `${file}.part`;
+  await fs.writeFile(partial, '');
+  const url = `${RELEASES}/${version}/${name}`;
+  log(`downloading ${name} (${version})`);
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok || !response.body) {
+    await fs.rm(partial, { force: true });
+    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 its pinned checksum.\n  expected ${expected}\n  received ${actual}`);
+    }
+    await fs.rename(partial, file);
+    if (process.platform !== 'win32') await fs.chmod(file, 0o755);
+  } catch (error) {
+    await fs.rm(partial, { force: true });
+    throw error;
+  }
+  log(`${name} ready`);
+  return file;
+}
+
+export function assetPath(version, name) {
+  return path.join(assetCacheDirectory(version), name);
+}
+
+async function sha256File(file) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(file)) {
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+
+/** Verifies a cached release byte-for-byte without loading the whole file into memory. */
+export async function verifyFileHash(file, expected) {
+  return (await sha256File(file)) === expected;
+}

package/lib/node.mjs

@@ -0,0 +1,43 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+export const REQUIRED_NODE = '18.17';
+
+/** Finds an explicitly configured Node first, then the executable on PATH. */
+export function findNode() {
+  const configured = process.env.VITAMINMCP_NODE;
+  if (configured && (existsSync(configured) || path.basename(configured) === configured)) {
+    return configured;
+  }
+  return process.platform === 'win32' ? 'node.exe' : 'node';
+}
+
+/** Checks Node before choosing the source runner path. */
+export function checkNode(node) {
+  const probe = spawnSync(node, ['--version'], { encoding: 'utf8' });
+  if (probe.error) {
+    return { ok: false, message: `No Node found. The hybrid runner needs Node ${REQUIRED_NODE} or later.` };
+  }
+  const match = `${probe.stdout || ''}${probe.stderr || ''}`.match(/v(\d+)(?:\.(\d+))?/);
+  if (!match) return { ok: true, version: null };
+  const major = Number(match[1]);
+  const minor = Number(match[2] ?? 0);
+  if (major < 18 || (major === 18 && minor < 17)) {
+    return { ok: false, version: `${major}.${minor}`, message:
+      `Node ${major}.${minor} is too old — the hybrid runner needs Node ${REQUIRED_NODE} or later.` };
+  }
+  return { ok: true, version: `${major}.${minor}` };
+}
+
+/** The release asset name for the current SEA target. */
+export function runnerAssetName(platform = process.platform, arch = process.arch) {
+  if (platform === 'win32' && arch === 'x64') return 'bot-runner-win-x64.exe';
+  if (platform === 'linux' || platform === 'darwin') {
+    throw new Error(
+      `Native runner assets for ${platform}-${arch} are planned but not released yet. `
+        + 'Install Node 18.17 or later to use the source runner.',
+    );
+  }
+  throw new Error(`No VitaminMCP runner asset exists for ${platform}-${arch}.`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vitaminmcp",
-  "version": "1.5.0",
-  "mcpName": "io.github.backas03/vitaminmcp",
+  "version": "2.0.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",
@@ -23,6 +23,10 @@
   "license": "MIT",
   "author": "Backas03",
   "type": "module",
+  "dependencies": {
+    "mineflayer": "^4.37.1",
+    "mineflayer-pathfinder": "2.4.5"
+  },
   "bin": {
     "vitaminmcp": "bin/vitaminmcp.mjs"
   },
@@ -32,11 +36,14 @@
   "files": [
     "bin",
     "lib",
+    "runner",
     "checksums.json",
     "README.md"
   ],
   "scripts": {
+    "test": "node --test test/*.test.mjs",
     "stamp": "node scripts/stamp-checksums.mjs",
-    "prepublishOnly": "node scripts/stamp-checksums.mjs --verify"
+    "stage-runner": "node scripts/stage-node-runner.mjs",
+    "prepublishOnly": "node scripts/stage-node-runner.mjs && node scripts/stamp-checksums.mjs --verify"
   }
 }

package/runner/runner.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * The bot runner, on mineflayer.
+ *
+ * Speaks the VitaminMCP stdio line protocol and is launched as the runner child process:
+ *
+ *   node runner.mjs <host> <port> [protocol]
+ *
+ * Everything it prints on stdout is protocol. Diagnostics go to stderr, which the MCP server
+ * inherits — a stray `console.log` here is a desynchronised session, not a stray log line.
+ */
+import { createInterface } from 'node:readline';
+
+import { BotRegistry } from './src/bots.mjs';
+import { Dispatch } from './src/dispatch.mjs';
+import * as protocol from './src/protocol.mjs';
+import { pingProtocol, versionForProtocol } from './src/version.mjs';
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length < 2) {
+    process.stderr.write('usage: runner.mjs <host> <port> [protocol]\n');
+    process.exit(2);
+  }
+
+  const host = argv[0];
+  const port = Number(argv[1]);
+
+  let bots;
+  let negotiated;
+  try {
+    negotiated = argv.length > 2 ? Number(argv[2]) : await pingProtocol(host, port);
+    bots = new BotRegistry(host, port, versionForProtocol(negotiated));
+  } catch (error) {
+    // The Java side reads this line and reports it as the reason the runner did not start, so it
+    // has to arrive on stdout in protocol form rather than as a stack trace on stderr.
+    write(protocol.encode(protocol.ERROR, 'startup', `${error?.name ?? 'Error'}: ${error?.message ?? error}`));
+    process.stderr.write(`${error?.stack ?? error}\n`);
+    process.exit(1);
+  }
+
+  write(protocol.encode(protocol.READY, String(negotiated)));
+
+  const dispatch = new Dispatch(bots);
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+  for await (const line of lines) {
+    const reply = await dispatch.handle(line);
+    if (reply === null) {
+      break;
+    }
+    if (reply !== '') {
+      write(reply);
+    }
+  }
+
+  bots.shutdown();
+  process.exit(0);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error?.stack ?? error}\n`);
+  process.exit(1);
+});
+
+function write(line) {
+  process.stdout.write(`${line}\n`);
+}