Report the current environment: java (path + version), workdir, hmcl dir contents (HMCL.jar / hmcl-agent.jar / javafx jars), whether the headless HMCL agent JVM is running (loopback probe with short timeout), and counts of installed versions and modpacks. Run this first to diagnose setup problems. java is null when no JDK is found.

Prepare the HMCL directory: if /HMCL.jar is missing, download the latest HMCL release jar from GitHub (asset ending in .jar); then run node agent/build.mjs (requires javac on PATH) to fetch the javafx jars and compile hmcl-agent.jar; copy hmcl-agent.jar and the javafx jars into . Returns the resulting paths. Safe to re-run.

Start the headless HMCL JVM with the injected javaagent (no-op if already running, per ensureAgent) and return the agent status ({hmclVersion, workdir, java, versions, running, gamePid}). The launcher GUI never opens; only the game window appears when a game is launched.

Stop the headless HMCL JVM by POSTing /shutdown to the agent on 127.0.0.1, then confirm the agent is down with a status probe. Fails when no agent is reachable (run start_hmcl first).

List installed game versions by scanning /versions/ — a directory counts as a version when it contains /.json. Returns [{id, path, hasJar}], sorted by id.

Install a vanilla Minecraft version (e.g. "1.20.4") through the HMCL agent. Downloads the version json, client jar and libraries (via BMCLAPI/mojang mirrors) into /versions// and /libraries/ — this can take a few minutes on first run. Assets are downloaded by HMCL at first launch.

List installed modpacks by scanning /versions/*/modpack.json (HMCL ModpackConfiguration). Returns [{name, path, format, gameVersion?, modLoader?}] where format maps Modrinth→mrpack, CurseForge→curseforge, HMCL→hmcl; gameVersion/modLoader are best-effort reads from the pack manifest. name is the instance id — pass it as version to launch_game.

Launch a game instance through the agent as an offline account. version is an instance id (see list_versions / list_modpacks). username defaults to Steve; maxMemory is the max heap in MB; javaPath overrides the Java used for the game; extraArgs are appended after the default JVM args. The game runs as a separate child process — the game window opens normally.

Stop the currently running game process via the agent (POST /launch/stop).

Search modpacks with HMCL's own repositories: Modrinth (default) or CurseForge (HMCL's embedded API key — no HMCL_MCP_CURSEFORGE_API_KEY needed). Returns ModpackSummary[]: id (slug), title, description, authors, url.

Get details of a modpack project (id = Modrinth slug or CurseForge slug) through HMCL: summary + available versions (id = version name, version, gameVersions, loaders) and the latest version.

Download a modpack file through HMCL into /mcpacks/ (SHA-1 verified via HMCL's downloader). Pass versionId (a version name from get_modpack) to pick a specific version; defaults to the latest. Returns {id, version, gameVersions, filename, path, size, sha1}.

Install a modpack as a game instance under /versions/. Either pass path to a local .mrpack/.zip file, or id (plus optional versionId) to download it first via HMCL; name is the instance name (defaults to the pack name). Requires the HMCL agent — it is started automatically if possible.