vitaminmcp 3.1.0 → 3.2.0

package/README.md

@@ -36,6 +36,28 @@ as — `/mcp` lists it); in any client, just ask:
 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.
 
+## One process for many projects
+
+If a Windows client keeps one stdio server per loaded project, install one shared service:
+
+```powershell
+npx -y vitaminmcp service install
+```
+
+Configure those projects with the URL `http://127.0.0.1:25584/mcp`. Each client gets isolated MCP
+state, and bot runners are still created only after `session_start`. Windows asks for administrator
+approval once; no client startup hook or Windows account password is needed. `service status` and
+`service uninstall` inspect or remove it, and installing again updates it. Account data is kept on
+uninstall.
+
+Elsewhere, a platform service manager can own `npx -y vitaminmcp --http 25584` as a foreground
+process. The portable default remains stdio.
+
+The shared endpoint is loopback-only but has no token: every program and every account on the
+machine can use the agent handshakes and Microsoft accounts under `~/.vitaminmcp` through it. Use
+it on a computer only you use, and keep to stdio on a shared one. A session left idle for six
+hours is closed and its bots disconnect.
+
 ## What you get
 
 - Spawn and control test players — real protocol clients, not mock `Player` objects

package/bin/vitaminmcp.mjs

@@ -9,8 +9,9 @@ import { fileURLToPath } from 'node:url';
 import {
   MCP_SERVER_JAR, assetPath, ensureAsset, ensureJar,
 } from '../lib/jars.mjs';
-import { checkJava, findJava } from '../lib/java.mjs';
+import { checkJava, findJava, mcpServerArgs } from '../lib/java.mjs';
 import { checkNode, findNode, runnerAssetName, viewerAssetName } from '../lib/node.mjs';
+import { runServiceAction, serviceAction } from '../lib/service.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
@@ -45,6 +46,9 @@ Options
   --help        this text
   --version     the version this launcher will run
   --jars        download the jars and print where they are, without starting anything
+  --http [port] serve MCP over loopback HTTP (default port 25584)
+  service install|uninstall|status
+                manage one shared Windows service (install also updates it)
 
 Environment
   JAVA_HOME               the JDK to run the jars with; Java 21 or later
@@ -69,6 +73,17 @@ async function main() {
     return 0;
   }
 
+  const service = serviceAction(argv);
+  if (service) {
+    if (service === 'install') {
+      const java = findJava();
+      const usable = checkJava(java);
+      if (!usable.ok) die(usable.message);
+      return await runServiceAction(service, release, { java });
+    }
+    return await runServiceAction(service, release);
+  }
+
   const java = findJava();
   const usable = checkJava(java);
   if (!usable.ok) {
@@ -121,17 +136,11 @@ async function main() {
   }
 
   await runnerReady;
-  return await run(java, server, runner, release, viewerAsset);
+  const env = serverEnvironment(runner, release, viewerAsset);
+  return await run(java, server, env, argv);
 }
 
-/**
- * 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, release, viewerAsset) {
+function serverEnvironment(runner, release, viewerAsset) {
   const env = {
     ...process.env,
     VITAMINMCP_RUNNER_JAR: runner,
@@ -142,7 +151,12 @@ function run(java, server, runner, release, viewerAsset) {
   if (!env.VITAMINMCP_VIEWER_PATH) {
     env.VITAMINMCP_VIEWER_PATH = path.join(HERE, '..', 'lib', 'viewer-loader.mjs');
   }
-  const child = spawn(java, ['-jar', server], {
+  return env;
+}
+
+/** Runs the server jar, and lives exactly as long as it does. */
+function run(java, server, env, args) {
+  const child = spawn(java, mcpServerArgs(server, args), {
     stdio: 'inherit',
     env,
   });

package/checksums.json

@@ -1,14 +1,14 @@
 {
-  "version": "3.1.0",
+  "version": "3.2.0",
   "jars": {
-    "mcp-server.jar": "f64ee16d5aaa115a9d4e019adccf830b74ebe8683d2ade5e05b7db0cf9692d66"
+    "mcp-server.jar": "19e54259d2afb5171b6af61fb9b5e8dc41178807eef9886b0105568cab26cab6"
   },
   "assets": {
-    "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-win-x64.exe": "e79b3e4a3e5ce571d5f18f199265ef2bf2de4b94102fc537c48055687d93c501",
+    "bot-runner-linux-x64": "75ec38cbd3facd07734ab147ef3ac7feae4bcfa909b39e5d2baf422b5e52c044",
+    "bot-runner-linux-arm64": "f9f35216e07ff75f3f27729068af3afd40da1fb1b5126a92cfab512ae7fb8631",
+    "bot-runner-darwin-x64": "15116f74ac073944683de21c0ee4e91f87ad079edfeed12121c54547f84ac859",
+    "bot-runner-darwin-arm64": "bd71e5b21f5a33f81411f99a7137abb0663f355f6ef54e17504bb6087b965fc6",
     "bot-runner-viewer-win-x64.tgz": "e39a36cdf92b9223aa7c9610f8231afc7a577e8ed007bc3571895bd945baf3e1"
   }
 }

package/lib/java.mjs

@@ -5,6 +5,24 @@ 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;
 
+const SHARED_SERVER_JVM_FLAGS = ['-Xms16m', '-Xmx128m', '-XX:+UseSerialGC'];
+
+export function mcpServerArgs(server, args = []) {
+  const flags = args.includes('--http') ? SHARED_SERVER_JVM_FLAGS : [];
+  return [...flags, '-jar', server, ...args];
+}
+
+export function javaHome(java, run = spawnSync) {
+  const probe = run(
+    java,
+    ['-Dstdout.encoding=UTF-8', '-Dstderr.encoding=UTF-8', '-XshowSettings:properties', '-version'],
+    { encoding: 'utf8' },
+  );
+  const output = `${probe.stderr || ''}${probe.stdout || ''}`;
+  const match = output.match(/^\s*java\.home = (.+?)\s*$/m);
+  return match ? match[1] : null;
+}
+
 /**
  * The java to run the jars with: JAVA_HOME if it points at one, otherwise whatever is on PATH.
  *

package/lib/service.mjs

@@ -0,0 +1,82 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { javaHome as findJavaHome } from './java.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ACTIONS = new Set(['install', 'uninstall', 'status']);
+
+export function serviceAction(args) {
+  if (args[0] !== 'service') return null;
+  if (args.length !== 2 || !ACTIONS.has(args[1])) {
+    throw new Error('service requires one action: install, uninstall, or status');
+  }
+  return args[1];
+}
+
+/** Runs the Windows-only installer kept outside the cross-platform launcher logic. */
+export function runServiceAction(
+  action,
+  release,
+  {
+    platform = process.platform,
+    node = process.execPath,
+    java = null,
+    javaHome = java ? findJavaHome(java) : null,
+    npmCli = npmCliPath(node),
+    packageRoot = path.join(HERE, '..'),
+    home = process.env.VITAMINMCP_HOME ?? path.join(os.homedir(), '.vitaminmcp'),
+    spawnProcess = spawn,
+  } = {},
+) {
+  if (platform !== 'win32') {
+    throw new Error('VitaminMCP service management is available only on Windows');
+  }
+  if (action === 'install' && !npmCli) {
+    throw new Error('service install needs npm; run it through npx or install Node with npm');
+  }
+  if (action === 'install' && !javaHome) {
+    throw new Error(`service install could not find the Java home of ${java ?? 'java'}`);
+  }
+
+  const script = path.join(HERE, '..', 'service', 'windows-service.ps1');
+  const args = [
+    '-NoProfile',
+    '-ExecutionPolicy', 'Bypass',
+    '-File', script,
+    '-Action', action,
+    '-PackageRoot', packageRoot,
+    '-NodePath', node,
+    '-DataHome', home,
+    '-Version', release,
+  ];
+  if (npmCli) args.push('-NpmCliPath', npmCli);
+  if (javaHome) args.push('-JavaHome', javaHome);
+
+  const localJar = path.join(packageRoot, '..', 'build', 'dist', 'mcp-server.jar');
+  if (!existsSync(path.join(packageRoot, 'checksums.json')) && existsSync(localJar)) {
+    args.push('-ServerJar', localJar);
+  }
+
+  const child = spawnProcess('powershell.exe', args, { stdio: 'inherit' });
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => resolve(signal ? 1 : (code ?? 1)));
+  });
+}
+
+function npmCliPath(node) {
+  if (process.env.npm_execpath && existsSync(process.env.npm_execpath)) {
+    return process.env.npm_execpath;
+  }
+  const besideNode = path.join(path.dirname(node), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+  if (existsSync(besideNode)) return besideNode;
+
+  const found = spawnSync('where.exe', ['npm.cmd'], { encoding: 'utf8' });
+  if (found.status !== 0) return null;
+  const npm = found.stdout.split(/\r?\n/, 1)[0]?.trim();
+  return npm || null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitaminmcp",
-  "version": "3.1.0",
+  "version": "3.2.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": [
@@ -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"
@@ -36,6 +37,7 @@
   "files": [
     "bin",
     "lib",
+    "service",
     "runner",
     "checksums.json",
     "README.md"

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,24 +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

@@ -39,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: {
@@ -302,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),
+  );
+}

package/service/windows-service.ps1

@@ -0,0 +1,383 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [ValidateSet('install', 'uninstall', 'status')]
+    [string]$Action,
+
+    [string]$PackageRoot = '',
+    [string]$NodePath = '',
+    [string]$NpmCliPath = '',
+    [string]$JavaHome = '',
+    [string]$DataHome = '',
+    [string]$Version = '',
+    [string]$ServerJar = '',
+    [string]$OutputPath = ''
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$ServiceId = 'VitaminMCP'
+$InstallRoot = [System.IO.Path]::GetFullPath((Join-Path $env:ProgramData $ServiceId))
+$ExpectedRoot = [System.IO.Path]::GetFullPath((Join-Path $env:ProgramData 'VitaminMCP'))
+$Wrapper = Join-Path $InstallRoot 'VitaminMCP.exe'
+$Config = Join-Path $InstallRoot 'VitaminMCP.xml'
+$AppRoot = Join-Path $InstallRoot 'app'
+$Logs = Join-Path $InstallRoot 'logs'
+$WinSwUrl = 'https://github.com/winsw/winsw/releases/download/v2.12.0/WinSW.NET461.exe'
+$WinSwSha256 = 'b5066b7bbdfba1293e5d15cda3caaea88fbeab35bd5b38c41c913d492aadfc4f'
+$SystemSid = 'S-1-5-18'
+$AdministratorsSid = 'S-1-5-32-544'
+$WorldSids = @('S-1-1-0', 'S-1-5-11', 'S-1-5-32-545')
+
+function Test-Administrator {
+    $identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+    $principal = [Security.Principal.WindowsPrincipal]::new($identity)
+    return $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+
+function Quote-PowerShell([string]$Value) {
+    return "'" + $Value.Replace("'", "''") + "'"
+}
+
+function Invoke-Elevated {
+    $output = [System.IO.Path]::GetTempFileName()
+    try {
+        $values = @{
+            Action = $Action
+            PackageRoot = $PackageRoot
+            NodePath = $NodePath
+            NpmCliPath = $NpmCliPath
+            JavaHome = $JavaHome
+            DataHome = $DataHome
+            Version = $Version
+            ServerJar = $ServerJar
+            OutputPath = $output
+        }
+        $command = '& ' + (Quote-PowerShell $PSCommandPath)
+        foreach ($entry in $values.GetEnumerator()) {
+            $command += ' -' + $entry.Key + ' ' + (Quote-PowerShell ([string]$entry.Value))
+        }
+        $encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($command))
+        Write-Host 'Waiting for administrator approval, then for the service change to finish...'
+        try {
+            $process = Start-Process -FilePath 'powershell.exe' -Verb RunAs -Wait -PassThru `
+                -WindowStyle Hidden `
+                -ArgumentList @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', $encoded)
+        } catch {
+            throw 'Administrator approval is required to change the VitaminMCP service.'
+        }
+        Get-Content -LiteralPath $output | Write-Host
+        $code = $process.ExitCode
+    } finally {
+        Remove-Item -LiteralPath $output -Force -ErrorAction SilentlyContinue
+    }
+    exit $code
+}
+
+function Invoke-Native([string]$File, [string[]]$Arguments) {
+    $ErrorActionPreference = 'Continue'
+    & $File @Arguments 2>&1 | ForEach-Object { "$_" }
+    if ($LASTEXITCODE -ne 0) {
+        throw "$File exited with code $LASTEXITCODE"
+    }
+}
+
+function Initialize-InstallRoot {
+    $inherit = [Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+    $security = [Security.AccessControl.DirectorySecurity]::new()
+    $security.SetOwner([Security.Principal.SecurityIdentifier]::new($AdministratorsSid))
+    $security.SetAccessRuleProtection($true, $false)
+    foreach ($sid in @($SystemSid, $AdministratorsSid)) {
+        $security.AddAccessRule([Security.AccessControl.FileSystemAccessRule]::new(
+            [Security.Principal.SecurityIdentifier]::new($sid), 'FullControl', $inherit, 'None', 'Allow'))
+    }
+    [System.IO.Directory]::CreateDirectory($InstallRoot, $security) | Out-Null
+
+    $directory = Get-Item -LiteralPath $InstallRoot -Force
+    $existing = Get-Acl -LiteralPath $InstallRoot
+    $owner = $existing.GetOwner([Security.Principal.SecurityIdentifier]).Value
+    $reparse = [bool]($directory.Attributes -band [System.IO.FileAttributes]::ReparsePoint)
+    if ($reparse -or $owner -ne $AdministratorsSid -or -not $existing.AreAccessRulesProtected) {
+        throw "$InstallRoot already exists and was not created by this installer. " +
+            'Remove it as an administrator and run the install again.'
+    }
+}
+
+function Test-WorldReadable([string]$Path) {
+    $read = [Security.AccessControl.FileSystemRights]::ReadAndExecute
+    $rules = (Get-Acl -LiteralPath $Path).GetAccessRules(
+        $true, $true, [Security.Principal.SecurityIdentifier])
+    foreach ($rule in $rules) {
+        if ($rule.AccessControlType -eq 'Allow' -and `
+                $WorldSids -contains $rule.IdentityReference.Value -and `
+                ($rule.FileSystemRights -band $read) -eq $read) {
+            return $true
+        }
+    }
+    return $false
+}
+
+function Grant-ServiceRead([string]$Path, [string]$Rights) {
+    if (Test-WorldReadable $Path) {
+        return
+    }
+    Invoke-Native 'icacls.exe' @($Path, '/grant', "NT SERVICE\${ServiceId}:$Rights", '/T', '/C', '/Q')
+}
+
+function Get-LogTail {
+    $files = Get-ChildItem -LiteralPath $Logs -Filter '*.log' -File -ErrorAction SilentlyContinue
+    foreach ($file in $files) {
+        Write-Output "--- $($file.Name)"
+        Get-Content -LiteralPath $file.FullName -Tail 20
+    }
+}
+
+function Escape-Xml([string]$Value) {
+    return [Security.SecurityElement]::Escape($Value)
+}
+
+function Get-InstalledService {
+    return Get-CimInstance Win32_Service -Filter "Name='$ServiceId'" -ErrorAction SilentlyContinue
+}
+
+function Assert-OwnedService {
+    $service = Get-InstalledService
+    if ($null -eq $service) {
+        return
+    }
+    $registered = [System.IO.Path]::GetFullPath($service.PathName.Trim('"'))
+    if (-not $registered.Equals($Wrapper, [StringComparison]::OrdinalIgnoreCase)) {
+        throw "A different service named $ServiceId already exists at $registered"
+    }
+}
+
+function Test-Mcp {
+    $session = $null
+    try {
+        $body = @{
+            jsonrpc = '2.0'
+            id = 1
+            method = 'initialize'
+            params = @{
+                protocolVersion = '2025-06-18'
+                capabilities = @{}
+                clientInfo = @{ name = 'vitaminmcp-service'; version = '1' }
+            }
+        } | ConvertTo-Json -Depth 5 -Compress
+        $response = Invoke-WebRequest -UseBasicParsing -TimeoutSec 2 `
+            -Uri 'http://127.0.0.1:25584/mcp' -Method Post `
+            -ContentType 'application/json' -Headers @{ Accept = 'application/json, text/event-stream' } `
+            -Body $body
+        $session = $response.Headers['Mcp-Session-Id']
+        $json = $response.Content | ConvertFrom-Json
+        return $response.StatusCode -eq 200 -and $session -and `
+            $json.result.serverInfo.name -eq 'VitaminMCP'
+    } catch {
+        return $false
+    } finally {
+        if ($session) {
+            try {
+                Invoke-WebRequest -UseBasicParsing -TimeoutSec 2 `
+                    -Uri 'http://127.0.0.1:25584/mcp' -Method Delete `
+                    -Headers @{ 'Mcp-Protocol-Version' = '2025-06-18'; 'Mcp-Session-Id' = $session } `
+                    | Out-Null
+            } catch {}
+        }
+    }
+}
+
+function Show-Status {
+    $service = Get-Service -Name $ServiceId -ErrorAction SilentlyContinue
+    if ($null -eq $service) {
+        Write-Output 'VitaminMCP service is not installed.'
+        exit 1
+    }
+    $ready = Test-Mcp
+    Write-Output "VitaminMCP service: $($service.Status); MCP ready: $ready"
+    if (-not $ready) {
+        exit 1
+    }
+}
+
+function Install-Service {
+    if (-not $PackageRoot -or -not $NodePath -or -not $NpmCliPath -or `
+            -not $JavaHome -or -not $DataHome -or -not $Version) {
+        throw 'The service installer did not receive complete runtime paths.'
+    }
+    $javaPath = Join-Path $JavaHome 'bin\java.exe'
+    foreach ($required in @($PackageRoot, $NodePath, $NpmCliPath, $javaPath)) {
+        if (-not (Test-Path -LiteralPath $required)) {
+            throw "Required path does not exist: $required"
+        }
+    }
+    if ($ServerJar -and -not (Test-Path -LiteralPath $ServerJar -PathType Leaf)) {
+        throw "Local MCP server jar does not exist: $ServerJar"
+    }
+
+    Initialize-InstallRoot
+    New-Item -ItemType Directory -Force -Path $DataHome, $Logs | Out-Null
+
+    $download = "$Wrapper.part"
+    $validWrapper = (Test-Path -LiteralPath $Wrapper -PathType Leaf) -and `
+        ((Get-FileHash -Algorithm SHA256 -LiteralPath $Wrapper).Hash.ToLowerInvariant() -eq $WinSwSha256)
+    if (-not $validWrapper) {
+        Remove-Item -LiteralPath $download -Force -ErrorAction SilentlyContinue
+        Invoke-WebRequest -UseBasicParsing -Uri $WinSwUrl -OutFile $download
+        $received = (Get-FileHash -Algorithm SHA256 -LiteralPath $download).Hash.ToLowerInvariant()
+        if ($received -ne $WinSwSha256) {
+            Remove-Item -LiteralPath $download -Force
+            throw "WinSW checksum mismatch: expected $WinSwSha256, received $received"
+        }
+        Move-Item -LiteralPath $download -Destination $Wrapper -Force
+    }
+
+    $staging = Join-Path $InstallRoot 'app.new'
+    if (Test-Path -LiteralPath $staging) {
+        Remove-Item -LiteralPath $staging -Recurse -Force
+    }
+    New-Item -ItemType Directory -Path $staging | Out-Null
+    $npmArguments = @(
+        'install', '--omit=dev', '--ignore-scripts', '--install-links', '--no-save',
+        '--prefix', $staging, $PackageRoot
+    )
+    if ($NpmCliPath.EndsWith('.cmd', [StringComparison]::OrdinalIgnoreCase)) {
+        Invoke-Native $NpmCliPath $npmArguments
+    } else {
+        Invoke-Native $NodePath (@($NpmCliPath) + $npmArguments)
+    }
+
+    $launcher = Join-Path $staging 'node_modules\vitaminmcp\bin\vitaminmcp.mjs'
+    if (-not (Test-Path -LiteralPath $launcher -PathType Leaf)) {
+        throw "npm did not install the VitaminMCP launcher at $launcher"
+    }
+
+    Assert-OwnedService
+    $service = Get-Service -Name $ServiceId -ErrorAction SilentlyContinue
+    if ($service -and $service.Status -ne 'Stopped') {
+        Stop-Service -Name $ServiceId -Force
+        $service.WaitForStatus('Stopped', [TimeSpan]::FromSeconds(30))
+    }
+
+    if (Test-Path -LiteralPath $AppRoot) {
+        Remove-Item -LiteralPath $AppRoot -Recurse -Force
+    }
+    Move-Item -LiteralPath $staging -Destination $AppRoot
+    $launcher = Join-Path $AppRoot 'node_modules\vitaminmcp\bin\vitaminmcp.mjs'
+
+    $localJar = ''
+    if ($ServerJar) {
+        $localJar = Join-Path $InstallRoot 'mcp-server.jar'
+        Copy-Item -LiteralPath $ServerJar -Destination $localJar -Force
+    }
+
+    $javaDirectory = Split-Path -Parent $javaPath
+    $accounts = Join-Path $DataHome 'accounts'
+    $serverEnvironment = if ($localJar) {
+        "  <env name=`"VITAMINMCP_SERVER_JAR`" value=`"$(Escape-Xml $localJar)`" />`r`n"
+    } else { '' }
+    $xml = @"
+<service>
+  <id>$ServiceId</id>
+  <name>VitaminMCP</name>
+  <description>Shared local VitaminMCP server for MCP clients.</description>
+  <executable>$(Escape-Xml $NodePath)</executable>
+  <arguments>&quot;$(Escape-Xml $launcher)&quot; --http 25584</arguments>
+  <workingdirectory>$(Escape-Xml $AppRoot)</workingdirectory>
+  <env name="VITAMINMCP_HOME" value="$(Escape-Xml $DataHome)" />
+  <env name="VITAMINMCP_ACCOUNTS_DIR" value="$(Escape-Xml $accounts)" />
+  <env name="VITAMINMCP_NODE" value="$(Escape-Xml $NodePath)" />
+  <env name="JAVA_HOME" value="$(Escape-Xml $JavaHome)" />
+  <env name="PATH" value="$(Escape-Xml $javaDirectory);%PATH%" />
+$serverEnvironment  <startmode>Automatic</startmode>
+  <delayedAutoStart>true</delayedAutoStart>
+  <onfailure action="restart" delay="10 sec" />
+  <resetfailure>1 hour</resetfailure>
+  <stoptimeout>15 sec</stoptimeout>
+  <logpath>$(Escape-Xml $Logs)</logpath>
+  <log mode="roll" />
+</service>
+"@
+    [System.IO.File]::WriteAllText($Config, $xml, [Text.UTF8Encoding]::new($false))
+
+    if (-not (Get-Service -Name $ServiceId -ErrorAction SilentlyContinue)) {
+        Invoke-Native $Wrapper @('install')
+    }
+    Invoke-Native 'sc.exe' @('config', $ServiceId, 'obj=', "NT SERVICE\$ServiceId", 'start=', 'delayed-auto')
+    Invoke-Native 'sc.exe' @('sidtype', $ServiceId, 'unrestricted')
+
+    $principal = "NT SERVICE\$ServiceId"
+    Invoke-Native 'icacls.exe' @($InstallRoot, '/grant', "${principal}:(OI)(CI)RX", '/T', '/C', '/Q')
+    Invoke-Native 'icacls.exe' @($Logs, '/grant', "${principal}:(OI)(CI)M", '/T', '/C', '/Q')
+    Invoke-Native 'icacls.exe' @($DataHome, '/grant', "${principal}:(OI)(CI)M", '/T', '/C', '/Q')
+    Grant-ServiceRead $NodePath 'RX'
+    Grant-ServiceRead $JavaHome '(OI)(CI)RX'
+
+    Start-Service -Name $ServiceId
+    $deadline = [DateTime]::UtcNow.AddSeconds(60)
+    do {
+        if (Test-Mcp) {
+            Write-Output "VitaminMCP $Version is ready at http://127.0.0.1:25584/mcp"
+            Write-Output ''
+            Write-Output 'Codex config:'
+            Write-Output '[mcp_servers.vitaminmcp]'
+            Write-Output 'url = "http://127.0.0.1:25584/mcp"'
+            Write-Output 'startup_timeout_sec = 60'
+            return
+        }
+        Start-Sleep -Milliseconds 250
+    } while ([DateTime]::UtcNow -lt $deadline)
+    Get-LogTail
+    throw "The service started but MCP did not become ready. The log tails above are from $Logs"
+}
+
+function Uninstall-Service {
+    Assert-OwnedService
+    $service = Get-Service -Name $ServiceId -ErrorAction SilentlyContinue
+    if ($service) {
+        if ($service.Status -ne 'Stopped') {
+            Stop-Service -Name $ServiceId -Force
+            $service.WaitForStatus('Stopped', [TimeSpan]::FromSeconds(30))
+        }
+        Invoke-Native 'sc.exe' @('delete', $ServiceId)
+        $deadline = [DateTime]::UtcNow.AddSeconds(15)
+        while ((Get-Service -Name $ServiceId -ErrorAction SilentlyContinue) -and `
+                [DateTime]::UtcNow -lt $deadline) {
+            Start-Sleep -Milliseconds 250
+        }
+    }
+    if (-not $InstallRoot.Equals($ExpectedRoot, [StringComparison]::OrdinalIgnoreCase)) {
+        throw "Refusing to remove unexpected install path: $InstallRoot"
+    }
+    if (Test-Path -LiteralPath $InstallRoot) {
+        Remove-Item -LiteralPath $InstallRoot -Recurse -Force
+    }
+    Write-Output "VitaminMCP service removed. Account data was kept at $DataHome"
+}
+
+if ($Action -eq 'status') {
+    Show-Status
+    exit 0
+}
+if (-not (Test-Administrator)) {
+    Invoke-Elevated
+}
+
+function Invoke-Action {
+    if ($Action -eq 'install') {
+        Install-Service
+    } else {
+        Uninstall-Service
+    }
+}
+
+if (-not $OutputPath) {
+    Invoke-Action
+    exit 0
+}
+try {
+    Invoke-Action *> $OutputPath
+} catch {
+    "ERROR: $($_.Exception.Message)" | Out-File -LiteralPath $OutputPath -Append
+    exit 1
+}
+exit 0