vitaminmcp 3.1.1 → 3.2.1

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.1",
+  "version": "3.2.1",
   "jars": {
-    "mcp-server.jar": "423c885926a6c5f82d1c403ce01592afabfcc0646b756c5ce7370a0a88be09b1"
+    "mcp-server.jar": "b9af85303677bfe1e792259c5efab2763bd0fbafa12c1d468f7b034c563ba021"
   },
   "assets": {
-    "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-win-x64.exe": "0932bb6677cf9ff8657905a193e8f36f2943a4bba2b1597817f7ac192b575524",
+    "bot-runner-linux-x64": "a488c2f97c8c63f46bfb40e192af6939d3f49af1c61426974eb36cc3688a4db4",
+    "bot-runner-linux-arm64": "492fb73d79fd8db5d391567eb5b093c8f48bbd39b9bd669061c30c10dafc829f",
+    "bot-runner-darwin-x64": "b5fa212b25d001938384015fb22d5168977974d38105746b2c3a7a2b73aabd09",
+    "bot-runner-darwin-arm64": "e426feeac28baea547f5010ac47a33f50c401419bce258c4492408a87eec83bd",
     "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.1",
+  "version": "3.2.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": [
@@ -37,6 +37,7 @@
   "files": [
     "bin",
     "lib",
+    "service",
     "runner",
     "checksums.json",
     "README.md"

package/runner/runner.mjs

@@ -6,6 +6,11 @@
  *
  *   node runner.mjs <host> <port> [protocol]
  *
+ * Without a protocol it pings the server. VITAMINMCP_SERVER_VERSION, when set, is the Minecraft
+ * version the agent reports, and it wins over a ping that disagrees (see `selectProtocol`). It is
+ * an environment variable rather than an argument so a runner and an MCP server of different
+ * releases still understand each other's command line.
+ *
  * 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.
  */
@@ -14,7 +19,7 @@ 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';
+import { pingProtocol, selectProtocol, 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.
@@ -32,10 +37,24 @@ async function main() {
   const host = argv[0];
   const port = Number(argv[1]);
 
+  const serverVersion = process.env.VITAMINMCP_SERVER_VERSION || undefined;
+
   let bots;
   let negotiated;
+  let pinged;
   try {
-    negotiated = argv.length > 2 ? Number(argv[2]) : await pingProtocol(host, port);
+    if (argv.length > 2) {
+      negotiated = Number(argv[2]);
+    } else {
+      ({ protocol: negotiated, pinged } = selectProtocol(await pingProtocol(host, port), serverVersion));
+    }
+    if (pinged !== undefined) {
+      process.stderr.write(
+        `The server-list ping answered protocol ${pinged}, but the agent reports Minecraft `
+          + `${serverVersion} (protocol ${negotiated}). Something in front of the server answered `
+          + `the ping, a proxy or ViaVersion; using ${negotiated}.\n`,
+      );
+    }
     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
@@ -45,7 +64,10 @@ async function main() {
     process.exit(1);
   }
 
-  write(protocol.encode(protocol.READY, String(negotiated)));
+  // A third field only when the ping disagreed, so the line a caller already parses is unchanged.
+  write(pinged === undefined
+    ? protocol.encode(protocol.READY, String(negotiated))
+    : protocol.encode(protocol.READY, String(negotiated), String(pinged)));
 
   const dispatch = new Dispatch(bots);
   const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });

package/runner/src/version.mjs

@@ -76,3 +76,39 @@ export function versionForProtocol(protocol) {
       .join(', ')}). It supports ${mc.supportedVersions.join(', ')}.`,
   );
 }
+
+/**
+ * The protocol a Minecraft version speaks, from minecraft-data's table of every release it has
+ * heard of. That table is wider than the versions it carries data for, so a release the runner
+ * cannot speak yet still has a number here.
+ */
+export function protocolForVersion(minecraftVersion) {
+  return minecraftData.versionsByMinecraftVersion?.pc?.[minecraftVersion]?.version;
+}
+
+/**
+ * Which protocol to speak: the one the agent says its server runs, over the one the ping answered.
+ *
+ * A ping is answered by whatever holds the port, and two common things answer it with the
+ * protocol the ping was written in rather than the server's own: a proxy that echoes it, and
+ * ViaVersion with ViaBackwards, which rewrites the status reply to the client's protocol whenever
+ * it can translate. The ping is written in PING_VERSION, so either one made the runner join as
+ * 1.21.1 — on a 26.x server, through a chain of translations, without a word. The agent runs inside
+ * the server, and nothing answers for it.
+ *
+ * Without a version from the agent the ping decides, as it always did. `pinged` is returned only
+ * when the two disagree, so the caller can say so.
+ */
+export function selectProtocol(pinged, serverVersion) {
+  if (!serverVersion) {
+    return { protocol: pinged };
+  }
+  const declared = protocolForVersion(serverVersion);
+  if (declared === undefined) {
+    throw new Error(
+      `The agent reports Minecraft ${serverVersion}, which this runner's minecraft-data does not `
+        + 'know: the dependency is older than the server.',
+    );
+  }
+  return declared === pinged ? { protocol: declared } : { protocol: declared, pinged };
+}

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