@adhisang/minecraft-modding-mcp 4.1.1 → 4.2.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.2.1] - 2026-05-23
+
+### Fixed
+- Mojang binary-remap cache writes recover from corrupt `<cacheDir>/remapped/<artifactId>.jar` directories instead of surfacing raw `ENOTEMPTY`, and `manage-cache` can list and delete those corrupt `binary-remap` entries by `selector.artifactId`.
+- `isAppError(value)` now narrows to `AppError` via `instanceof AppError` instead of `Error & { code: string }`. Plain `Error` objects that happen to carry a `code` field no longer pass the guard, so unrelated errors can no longer leak through `AppError`-specific error handling.
+- Java NBT `TAG_String` now encodes/decodes via MUTF-8 to match Mojang's `DataInputStream.readUTF` / `DataOutputStream.writeUTF` contract. Supplementary characters (emoji, supplementary CJK) and the NUL character (`U+0000`) now round-trip correctly. ASCII and common BMP byte sequences are byte-identical to the previous UTF-8 output, so existing NBT payloads are unaffected.
+
+## [4.2.0] - 2026-05-17
+
+### Added
+- Cache-backed source, mapping, validation, batch, and workflow tools now accept `gradleUserHome` so callers can use Loom caches from a non-default Gradle User Home instead of the MCP process default.
+
 ## [4.1.1] - 2026-05-10
 
 ### Documentation
@@ -160,8 +172,8 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 ## [3.0.0] - 2026-03-09
 
 ### Added
-- v3 entry tools: `inspect-minecraft`, `analyze-symbol`, `compare-minecraft`, `analyze-mod`, `validate-project`, and `manage-cache` now provide summary-first starting points for the main Minecraft, symbol, mod, validation, and cache workflows while keeping expert tools available for follow-up work.
-- The new v3 entry tools share `detail` / `include` response shaping and always return `result.summary` inside the standard `{ result?, error?, meta }` envelope, reducing default payload size and making next actions explicit.
+- Top-level workflow tools: `inspect-minecraft`, `analyze-symbol`, `compare-minecraft`, `analyze-mod`, `validate-project`, and `manage-cache` now provide summary-first starting points for the main Minecraft, symbol, mod, validation, and cache workflows while keeping expert tools available for follow-up work.
+- The new top-level workflow tools share `detail` / `include` response shaping and always return `result.summary` inside the standard `{ result?, error?, meta }` envelope, reducing default payload size and making next actions explicit.
 - `analyze-mod` now exposes `executionMode="preview" | "apply"` for safe remap planning and execution, and `manage-cache` now exposes the same preview/apply model for cache deletion, pruning, and rebuild workflows.
 
 ### Fixed

package/README.md

@@ -134,6 +134,8 @@ Pass environment variables to override defaults:
 }
 ```
 
+When a build used a non-default Gradle User Home, pass `gradleUserHome` on cache-backed source, mapping, validation, and workflow calls. The server treats it as a per-call Gradle User Home and searches `<gradleUserHome>/loom-cache` and `<gradleUserHome>/caches/fabric-loom` before the MCP process default. It does not accept arbitrary Loom cache directories.
+
 ## Start Here
 
 These six top-level workflow tools cover the common paths and return summary-first results. They are the best default starting points for agents and MCP clients.
@@ -161,6 +163,8 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - `validate-project task="project-summary"` propagates `preferProjectVersion=true` across discovered Mixin, Access Widener, and Access Transformer checks. If no version can be resolved from the request or `gradle.properties`, the summary returns recovery guidance instead of guessing.
 - `validate-mixin` and `validate-project` keep `mapping-health` lightweight for `obfuscated` and `mojang` validation, avoiding full Tiny mapping graph loads unless `intermediary` or `yarn` namespaces are requested.
 - `validate-project task="project-summary"` uses a lightweight artifact probe for `tasks["minecraft.artifact.resolved"]`; it does not decompile Minecraft or rebuild the source index just to report per-probe status. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
+- If a workspace was built with `GRADLE_USER_HOME=/tmp/...` or another isolated Gradle home, pass that path as `gradleUserHome` so source, mapping, runtime, and project validation lookups use the same Loom cache instead of stale caches under the MCP process home.
+- `manage-cache` reports corrupt Mojang binary-remap cache directories under `cacheKinds: ["binary-remap"]` with `status: "corrupt"`, and can delete them by `selector.artifactId` in preview/apply workflows.
 
 ### Inspect Minecraft source from a version
 
@@ -251,7 +255,7 @@ Start with these top-level workflow tools unless you already know the exact spec
 
 ### Top-Level Workflow Tools
 
-<!-- BEGIN GENERATED TOOL TABLE: v3-entry-tools -->
+<!-- BEGIN GENERATED TOOL TABLE: top-level-workflow-tools -->
 | Tool | Purpose |
 | --- | --- |
 | `inspect-minecraft` | Inspect versions, artifacts, classes, files, source text, and workspace-aware lookup flows |
@@ -260,7 +264,7 @@ Start with these top-level workflow tools unless you already know the exact spec
 | `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, and preview or apply remaps |
 | `validate-project` | Summarize workspaces and run direct Mixin, Access Widener, or Access Transformer validation |
 | `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |
-<!-- END GENERATED TOOL TABLE: v3-entry-tools -->
+<!-- END GENERATED TOOL TABLE: top-level-workflow-tools -->
 
 ### Source Exploration
 

package/dist/cache-registry.js

@@ -442,6 +442,9 @@ function workspaceCacheEntries(workspaceCache) {
     }));
 }
 async function fileBackedEntries(config, cacheKind) {
+    if (cacheKind === "binary-remap") {
+        return binaryRemapEntries(config);
+    }
     const root = kindRoot(config, cacheKind);
     const files = await listFilesRecursive(root);
     const entries = [];
@@ -466,17 +469,91 @@ async function fileBackedEntries(config, cacheKind) {
                 inUse: filePath.endsWith(".lock") ||
                     filePath.endsWith(".wal") ||
                     filePath.endsWith(".journal"),
-                ...(cacheKind === "downloads" || cacheKind === "mod-remap" || cacheKind === "binary-remap"
+                ...(cacheKind === "downloads" || cacheKind === "mod-remap"
                     ? { jarPath: filePath }
-                    : {}),
-                ...(cacheKind === "binary-remap"
-                    ? { artifactId: normalizedEntryId.replace(/\.jar$/i, "") }
                     : {})
             }
         });
     }
     return entries;
 }
+/**
+ * Binary-remap cache entries are keyed by the final artifact id even when the
+ * on-disk entry is a corrupt final directory or a leftover temp path.
+ */
+function parseBinaryRemapEntryName(name) {
+    const legacyTempMatch = /^(.+)\.jar\.tmp\..+$/.exec(name);
+    if (legacyTempMatch?.[1]) {
+        return { artifactId: legacyTempMatch[1], corrupt: true };
+    }
+    const tempMatch = /^(.+)\.tmp\.\d+\.\d+\.[A-Za-z0-9_-]+\.jar$/.exec(name);
+    if (tempMatch?.[1]) {
+        return { artifactId: tempMatch[1], corrupt: true };
+    }
+    const finalJarMatch = /^(.+)\.jar$/.exec(name);
+    if (finalJarMatch?.[1]) {
+        return { artifactId: finalJarMatch[1], corrupt: false };
+    }
+    return undefined;
+}
+async function binaryRemapEntries(config) {
+    const root = kindRoot(config, "binary-remap");
+    if (!existsSync(root)) {
+        return [];
+    }
+    const entries = [];
+    // Do not recurse here: a corrupt `<artifactId>.jar` directory must remain one
+    // selectable cache entry so `selector.artifactId` can remove it recursively.
+    const dirents = await readdir(root, { withFileTypes: true });
+    for (const entry of dirents.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isFile() && !entry.isDirectory()) {
+            continue;
+        }
+        const parsed = parseBinaryRemapEntryName(entry.name);
+        if (!parsed) {
+            continue;
+        }
+        const filePath = join(root, entry.name);
+        const fileStat = await stat(filePath);
+        const corrupt = parsed.corrupt || entry.isDirectory();
+        const sizeBytes = entry.isDirectory()
+            ? await directoryFileSizeBytes(filePath)
+            : fileStat.size;
+        entries.push({
+            cacheKind: "binary-remap",
+            entryId: entry.name,
+            path: filePath,
+            sizeBytes,
+            status: corrupt ? "corrupt" : "healthy",
+            meta: {
+                updatedAt: fileStat.mtime.toISOString(),
+                version: inferVersion(filePath, entry.name),
+                mapping: inferMapping(filePath, entry.name),
+                scope: inferScope(filePath, entry.name),
+                projectPath: inferProjectPath(filePath, config.pathRuntimeInfo),
+                partial: entry.isFile() && fileStat.size === 0,
+                corrupt,
+                inUse: false,
+                jarPath: filePath,
+                artifactId: parsed.artifactId
+            }
+        });
+    }
+    return entries;
+}
+async function directoryFileSizeBytes(root) {
+    const files = await listFilesRecursive(root);
+    let totalBytes = 0;
+    for (const filePath of files) {
+        try {
+            totalBytes += (await stat(filePath)).size;
+        }
+        catch {
+            // The entry may disappear during cleanup or a concurrent cache write.
+        }
+    }
+    return totalBytes;
+}
 export function createCacheRegistry(config) {
     const workspaceCache = config.workspaceContextCache ?? getProcessWorkspaceContextCache();
     async function collectEntries(cacheKinds, selector) {
@@ -564,7 +641,9 @@ export function createCacheRegistry(config) {
                             continue;
                         }
                         if (existsSync(entry.path)) {
-                            await rm(entry.path, { force: true });
+                            // Only binary-remap inventory can return directories as entries;
+                            // other file-backed kinds keep their existing file-only contract.
+                            await rm(entry.path, { recursive: entry.cacheKind === "binary-remap", force: true });
                         }
                     }
                 }

package/dist/entry-tools/analyze-symbol-service.d.ts

@@ -23,6 +23,7 @@ export declare const analyzeSymbolShape: {
     targetMapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
     classNameMapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
     projectPath: z.ZodOptional<z.ZodString>;
+    gradleUserHome: z.ZodOptional<z.ZodString>;
     signatureMode: z.ZodDefault<z.ZodEnum<["exact", "name-only"]>>;
     nameMode: z.ZodDefault<z.ZodEnum<["fqcn", "auto"]>>;
     includeKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["class", "field", "method"]>, "many">>;
@@ -54,6 +55,7 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     targetMapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
     classNameMapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
     projectPath: z.ZodOptional<z.ZodString>;
+    gradleUserHome: z.ZodOptional<z.ZodString>;
     signatureMode: z.ZodDefault<z.ZodEnum<["exact", "name-only"]>>;
     nameMode: z.ZodDefault<z.ZodEnum<["fqcn", "auto"]>>;
     includeKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["class", "field", "method"]>, "many">>;
@@ -77,6 +79,7 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    gradleUserHome?: string | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
     includeKinds?: ("class" | "field" | "method")[] | undefined;
@@ -94,6 +97,7 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    gradleUserHome?: string | undefined;
     nameMode?: "auto" | "fqcn" | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
@@ -117,6 +121,7 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    gradleUserHome?: string | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
     includeKinds?: ("class" | "field" | "method")[] | undefined;
@@ -134,6 +139,7 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    gradleUserHome?: string | undefined;
     nameMode?: "auto" | "fqcn" | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
@@ -152,6 +158,7 @@ type AnalyzeSymbolDeps = {
         descriptor?: string;
         sourceMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
         sourcePriority?: "loom-first" | "maven-first";
+        gradleUserHome?: string;
         nameMode?: "fqcn" | "auto";
         signatureMode?: "exact" | "name-only";
         maxCandidates?: number;
@@ -164,6 +171,7 @@ type AnalyzeSymbolDeps = {
         descriptor?: string;
         sourceMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
         targetMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
+        gradleUserHome?: string;
         signatureMode?: "exact" | "name-only";
         maxCandidates?: number;
     }) => Promise<FindMappingOutput>;
@@ -174,12 +182,14 @@ type AnalyzeSymbolDeps = {
         descriptor: string;
         sourceMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
         targetMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
+        gradleUserHome?: string;
         maxCandidates?: number;
     }) => Promise<ResolveMethodMappingExactOutput>;
     traceSymbolLifecycle: (input: {
         symbol: string;
         descriptor?: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
+        gradleUserHome?: string;
         toVersion?: string;
         maxVersions?: number;
     }) => Promise<TraceSymbolLifecycleOutput>;
@@ -191,6 +201,7 @@ type AnalyzeSymbolDeps = {
         owner?: string;
         descriptor?: string;
         sourceMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
+        gradleUserHome?: string;
         maxCandidates?: number;
     }) => Promise<ResolveWorkspaceSymbolOutput>;
     getClassApiMatrix: (input: {
@@ -198,6 +209,7 @@ type AnalyzeSymbolDeps = {
         className: string;
         classNameMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
         includeKinds?: ("class" | "field" | "method")[];
+        gradleUserHome?: string;
         maxRows?: number;
     }) => Promise<GetClassApiMatrixOutput>;
 };

package/dist/entry-tools/analyze-symbol-service.js

@@ -30,6 +30,7 @@ export const analyzeSymbolShape = {
     targetMapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
     classNameMapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
     projectPath: nonEmptyString.optional(),
+    gradleUserHome: nonEmptyString.optional(),
     signatureMode: z.enum(["exact", "name-only"]).default("exact"),
     nameMode: z.enum(["fqcn", "auto"]).default("fqcn"),
     includeKinds: z.array(z.enum(["class", "field", "method"])).optional(),
@@ -107,6 +108,7 @@ export class AnalyzeSymbolService {
                     owner: input.subject.owner,
                     descriptor: input.subject.descriptor,
                     sourceMapping: input.sourceMapping ?? "obfuscated",
+                    ...(input.gradleUserHome !== undefined ? { gradleUserHome: input.gradleUserHome } : {}),
                     nameMode: input.nameMode,
                     signatureMode: input.signatureMode,
                     maxCandidates: input.maxCandidates
@@ -152,6 +154,7 @@ export class AnalyzeSymbolService {
                     descriptor: input.subject.descriptor,
                     sourceMapping: input.sourceMapping ?? "obfuscated",
                     targetMapping: input.targetMapping ?? "mojang",
+                    ...(input.gradleUserHome !== undefined ? { gradleUserHome: input.gradleUserHome } : {}),
                     signatureMode: input.signatureMode,
                     maxCandidates: input.maxCandidates
                 });
@@ -202,6 +205,7 @@ export class AnalyzeSymbolService {
                     descriptor: input.subject.descriptor,
                     sourceMapping: input.sourceMapping ?? "obfuscated",
                     targetMapping: input.targetMapping ?? "mojang",
+                    ...(input.gradleUserHome !== undefined ? { gradleUserHome: input.gradleUserHome } : {}),
                     maxCandidates: input.maxCandidates
                 });
                 return {
@@ -243,6 +247,7 @@ export class AnalyzeSymbolService {
                         : input.subject.name,
                     descriptor: input.subject.descriptor,
                     mapping: input.sourceMapping,
+                    ...(input.gradleUserHome !== undefined ? { gradleUserHome: input.gradleUserHome } : {}),
                     toVersion: input.version,
                     maxVersions: 5
                 });
@@ -286,6 +291,7 @@ export class AnalyzeSymbolService {
                     owner: input.subject.owner,
                     descriptor: input.subject.descriptor,
                     sourceMapping: input.sourceMapping ?? "obfuscated",
+                    ...(input.gradleUserHome !== undefined ? { gradleUserHome: input.gradleUserHome } : {}),
                     maxCandidates: input.maxCandidates
                 });
                 return {
@@ -328,6 +334,7 @@ export class AnalyzeSymbolService {
                     className: input.subject.name,
                     classNameMapping,
                     includeKinds: input.includeKinds,
+                    ...(input.gradleUserHome !== undefined ? { gradleUserHome: input.gradleUserHome } : {}),
                     maxRows: input.maxRows
                 });
                 return {

package/dist/entry-tools/batch-class-members-service.d.ts

@@ -19,6 +19,7 @@ export type BatchClassMembersInput = {
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;

package/dist/entry-tools/batch-class-members-service.js

@@ -21,6 +21,7 @@ export class BatchClassMembersService {
                     sourcePriority: input.sourcePriority,
                     allowDecompile: input.allowDecompile,
                     projectPath: input.projectPath,
+                    gradleUserHome: input.gradleUserHome,
                     scope: input.scope,
                     preferProjectVersion: input.preferProjectVersion,
                     strictVersion: input.strictVersion
@@ -56,6 +57,7 @@ export class BatchClassMembersService {
                     sourcePriority: input.sourcePriority,
                     allowDecompile: input.allowDecompile,
                     projectPath: input.projectPath,
+                    gradleUserHome: input.gradleUserHome,
                     scope: input.scope,
                     preferProjectVersion: input.preferProjectVersion,
                     strictVersion: input.strictVersion

package/dist/entry-tools/batch-class-source-service.d.ts

@@ -17,6 +17,7 @@ export type BatchClassSourceInput = {
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;

package/dist/entry-tools/batch-class-source-service.js

@@ -21,6 +21,7 @@ export class BatchClassSourceService {
                     sourcePriority: input.sourcePriority,
                     allowDecompile: input.allowDecompile,
                     projectPath: input.projectPath,
+                    gradleUserHome: input.gradleUserHome,
                     scope: input.scope,
                     preferProjectVersion: input.preferProjectVersion,
                     strictVersion: input.strictVersion
@@ -57,6 +58,7 @@ export class BatchClassSourceService {
                     sourcePriority: input.sourcePriority,
                     allowDecompile: input.allowDecompile,
                     projectPath: input.projectPath,
+                    gradleUserHome: input.gradleUserHome,
                     scope: input.scope,
                     preferProjectVersion: input.preferProjectVersion,
                     strictVersion: input.strictVersion

package/dist/entry-tools/batch-mappings-service.d.ts

@@ -23,6 +23,7 @@ export type BatchMappingsInput = {
     version: string;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
+    gradleUserHome?: string;
     concurrency?: number;
     failFast?: boolean;
     compact?: boolean;

package/dist/entry-tools/batch-mappings-service.js

@@ -26,6 +26,7 @@ export class BatchMappingsService {
                     targetMapping: entry.targetMapping,
                     sourcePriority: input.sourcePriority,
                     projectPath: input.projectPath,
+                    gradleUserHome: input.gradleUserHome,
                     signatureMode: entry.signatureMode,
                     disambiguation: entry.disambiguation,
                     maxCandidates: entry.maxCandidates

package/dist/entry-tools/batch-symbol-exists-service.d.ts

@@ -30,6 +30,7 @@ export type BatchSymbolExistsInput = {
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;
     projectPath?: string;
+    gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;

package/dist/entry-tools/batch-symbol-exists-service.js

@@ -35,6 +35,7 @@ export class BatchSymbolExistsService {
                     sourcePriority: input.sourcePriority,
                     allowDecompile: input.allowDecompile,
                     projectPath: input.projectPath,
+                    gradleUserHome: input.gradleUserHome,
                     scope: input.scope,
                     preferProjectVersion: input.preferProjectVersion,
                     strictVersion: input.strictVersion
@@ -71,6 +72,7 @@ export class BatchSymbolExistsService {
                     descriptor: entry.descriptor,
                     sourceMapping: sharedArtifact.sourceMapping,
                     sourcePriority: input.sourcePriority,
+                    gradleUserHome: input.gradleUserHome,
                     nameMode: entry.nameMode,
                     signatureMode: entry.signatureMode,
                     maxCandidates: entry.maxCandidates,

package/dist/entry-tools/compare-minecraft-service.d.ts

@@ -26,12 +26,14 @@ export declare const compareMinecraftShape: {
         toVersion: z.ZodString;
         mapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
         sourcePriority: z.ZodOptional<z.ZodEnum<["loom-first", "maven-first"]>>;
+        gradleUserHome: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         kind: "class";
         className: string;
         fromVersion: string;
         toVersion: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+        gradleUserHome?: string | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     }, {
         kind: "class";
@@ -39,6 +41,7 @@ export declare const compareMinecraftShape: {
         fromVersion: string;
         toVersion: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+        gradleUserHome?: string | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"registry">;
@@ -87,12 +90,14 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         toVersion: z.ZodString;
         mapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
         sourcePriority: z.ZodOptional<z.ZodEnum<["loom-first", "maven-first"]>>;
+        gradleUserHome: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         kind: "class";
         className: string;
         fromVersion: string;
         toVersion: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+        gradleUserHome?: string | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     }, {
         kind: "class";
@@ -100,6 +105,7 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         fromVersion: string;
         toVersion: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+        gradleUserHome?: string | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"registry">;
@@ -136,6 +142,7 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         fromVersion: string;
         toVersion: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+        gradleUserHome?: string | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     } | {
         kind: "registry";
@@ -161,6 +168,7 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         fromVersion: string;
         toVersion: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+        gradleUserHome?: string | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     } | {
         kind: "registry";
@@ -191,6 +199,7 @@ type CompareMinecraftDeps = {
         toVersion: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
         sourcePriority?: "loom-first" | "maven-first";
+        gradleUserHome?: string;
         includeFullDiff?: boolean;
     }) => Promise<DiffClassSignaturesOutput>;
     getRegistryData: (input: {

package/dist/entry-tools/compare-minecraft-service.js

@@ -18,7 +18,8 @@ const subjectSchema = z.discriminatedUnion("kind", [
         fromVersion: nonEmptyString,
         toVersion: nonEmptyString,
         mapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
-        sourcePriority: z.enum(["loom-first", "maven-first"]).optional()
+        sourcePriority: z.enum(["loom-first", "maven-first"]).optional(),
+        gradleUserHome: nonEmptyString.optional()
     }),
     z.object({
         kind: z.literal("registry"),
@@ -175,6 +176,7 @@ export class CompareMinecraftService {
                     toVersion: input.subject.toVersion,
                     mapping: input.subject.mapping,
                     sourcePriority: input.subject.sourcePriority,
+                    ...(input.subject.gradleUserHome !== undefined ? { gradleUserHome: input.subject.gradleUserHome } : {}),
                     includeFullDiff: input.includeFullDiff
                 });
                 const changedCount = output.summary.total.added +

package/dist/entry-tools/inspect-minecraft/handlers/class-members.js

@@ -12,6 +12,7 @@ export async function handleClassMembers(deps, subject, detail, include, limit)
         mapping: classSubject.mapping,
         scope: classSubject.scope,
         projectPath: classSubject.projectPath,
+        gradleUserHome: classSubject.gradleUserHome,
         preferProjectVersion: classSubject.preferProjectVersion,
         strictVersion: classSubject.strictVersion,
         maxMembers: limit

package/dist/entry-tools/inspect-minecraft/handlers/class-overview.js

@@ -43,7 +43,8 @@ export async function handleClassOverview(deps, subject, detail, include) {
         const partialSourceFallback = subject.kind === "workspace" && hasPartialVanillaCoverage(artifact.artifact)
             ? await resolveBinaryBackedClass(deps, className, {
                 version: artifact.version,
-                mapping: classSubject.mapping
+                mapping: classSubject.mapping,
+                gradleUserHome: classSubject.gradleUserHome
             })
             : undefined;
         if (partialSourceFallback) {
@@ -53,6 +54,7 @@ export async function handleClassOverview(deps, subject, detail, include) {
                 mapping: classSubject.mapping,
                 scope: classSubject.scope,
                 projectPath: classSubject.projectPath,
+                gradleUserHome: classSubject.gradleUserHome,
                 preferProjectVersion: classSubject.preferProjectVersion,
                 strictVersion: classSubject.strictVersion,
                 mode: "metadata"

package/dist/entry-tools/inspect-minecraft/handlers/class-source.js

@@ -13,6 +13,7 @@ export async function handleClassSource(deps, subject, detail, include) {
         mapping: classSubject.mapping,
         scope: classSubject.scope,
         projectPath: classSubject.projectPath,
+        gradleUserHome: classSubject.gradleUserHome,
         preferProjectVersion: classSubject.preferProjectVersion,
         strictVersion: classSubject.strictVersion,
         mode: include.includes("source") || detail === "full" ? "snippet" : "metadata"

package/dist/entry-tools/inspect-minecraft/handlers/list-files.js

@@ -35,6 +35,7 @@ export async function handleListFiles(deps, subject, detail, include, limit, cur
                         projectPath: subject.projectPath,
                         mapping: subject.mapping,
                         scope: subject.scope,
+                        gradleUserHome: subject.gradleUserHome,
                         preferProjectVersion: subject.preferProjectVersion,
                         strictVersion: subject.strictVersion,
                         focus: {

package/dist/entry-tools/inspect-minecraft/handlers/search.js

@@ -34,7 +34,8 @@ export async function handleSearch(deps, subject, detail, include, limit, cursor
     const binaryBackedClassHit = needsBinaryBackedClassHit
         ? await resolveBinaryBackedClass(deps, searchSubject.query, {
             version: artifact.version,
-            mapping: subject.mapping
+            mapping: subject.mapping,
+            gradleUserHome: subject.gradleUserHome
         })
         : undefined;
     const binaryBackedHitRecord = binaryBackedClassHit == null