@adhisang/minecraft-modding-mcp 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.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
+- `package.json` `description` and `keywords` now mirror the GitHub repository's `description` and topics. `description` summarizes the actual feature surface (source inspection, Mojang/Yarn/Intermediary mappings, version diffs, Fabric/Forge/NeoForge mod JAR analysis, Mixin/Access Widener/Access Transformer validation); `keywords` expands from three entries to the published 15-topic set.
+
+### Fixed
+- Concurrent class source/member lookups in the same MCP server process now share one in-flight source indexing/decompile rebuild for the same binary fallback artifact.
+- `validate-project task="project-summary"` no longer performs heavyweight source indexing for its `minecraft.artifact.resolved` task probe. The probe now uses lightweight artifact metadata while preserving the public `tasks` response shape.
+- `validate-mixin` mapping-health checks no longer load the full Tiny mapping graph for `obfuscated` or `mojang` requests, preventing `validate-project task="project-summary"` worker restarts on large Mojang-mapped workspaces.
+- `validate-project task="project-summary"` task report no longer marks executed validators as `skipped` when the lightweight `minecraft.artifact.resolved` probe fails. Mixin / access-widener / access-transformer entries now reflect their real outcome (`ok` with `counts`, or `error`).
+- `validate-mixin` `toolHealth.tinyMappingsAvailable` now means "Tiny is sufficient for the request": `true` when Tiny is not required (`obfuscated` / `mojang`) or is loaded, `false` only when `intermediary` / `yarn` was requested and Tiny is unavailable. `confidenceScore` is no longer penalized when Tiny is intentionally skipped, including on graph-load failure.
+- `validate-project task="project-summary"` lightweight artifact probe defaults omitted `scope` to `"vanilla"` to match `validate-mixin`'s resolve stage, skipping workspace-wide source-jar discovery unless the caller explicitly requests `scope="merged"` or `scope="loader"`.
+- `validate-project task="project-summary"` stage notifications are now best-effort. Telemetry/transport failures no longer abort the summary, count as validation errors, hide nested `validate-mixin` work behind zero-count summaries, or surface as `ERR_ARTIFACT_PROBE_FAILED` in `tasks["minecraft.artifact.resolved"]`.
+
 ## [4.1.0] - 2026-05-09
 
 ### Documentation
@@ -146,8 +165,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.
@@ -159,6 +161,9 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - For unobfuscated releases such as `26.1+`, `check-symbol-exists` and `analyze-symbol task="exists"` validate `mojang` lookups against runtime bytecode when no mapping graph exists, and return `mapping_unavailable` when the runtime JAR itself is unreachable.
 - `analyze-mod` and `validate-project` require structured `subject` objects and canonical `include` groups; stale string-subject or domain-include payloads return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
 - `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.
 
 ### Inspect Minecraft source from a version
 
@@ -249,7 +254,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 |
@@ -258,7 +263,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
 
@@ -362,6 +367,8 @@ Tools for querying generated registry data and inspecting server runtime state.
 
 Tools that share one resolved artifact or Minecraft version across a fixed shortlist. Results include one status per item plus an aggregate `summary`. See [Batch lookup contract](docs/tool-reference.md#batch-lookup-contract) for failure handling and retry mapping.
 
+Within one MCP server process, batch class lookups that need the same binary fallback share one in-flight source indexing/decompile rebuild for that artifact.
+
 <!-- BEGIN GENERATED TOOL TABLE: batch-lookup -->
 | Tool | Purpose |
 | --- | --- |

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

package/dist/entry-tools/inspect-minecraft/internal.d.ts

@@ -251,6 +251,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     mapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
     scope: z.ZodOptional<z.ZodEnum<["vanilla", "merged", "loader"]>>;
     projectPath: z.ZodOptional<z.ZodString>;
+    gradleUserHome: z.ZodOptional<z.ZodString>;
     preferProjectVersion: z.ZodOptional<z.ZodBoolean>;
     strictVersion: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
@@ -259,6 +260,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
+    gradleUserHome?: string | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
 }, {
@@ -267,6 +269,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
+    gradleUserHome?: string | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
 }>, z.ZodObject<{
@@ -308,6 +311,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     mapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
     scope: z.ZodOptional<z.ZodEnum<["vanilla", "merged", "loader"]>>;
     projectPath: z.ZodOptional<z.ZodString>;
+    gradleUserHome: z.ZodOptional<z.ZodString>;
     preferProjectVersion: z.ZodOptional<z.ZodBoolean>;
     strictVersion: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
@@ -325,6 +329,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
+    gradleUserHome?: string | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
 }, {
@@ -342,6 +347,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
+    gradleUserHome?: string | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
 }>, z.ZodObject<{
@@ -384,6 +390,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     mapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
     scope: z.ZodOptional<z.ZodEnum<["vanilla", "merged", "loader"]>>;
     projectPath: z.ZodOptional<z.ZodString>;
+    gradleUserHome: z.ZodOptional<z.ZodString>;
     preferProjectVersion: z.ZodOptional<z.ZodBoolean>;
     strictVersion: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
@@ -392,6 +399,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
+    gradleUserHome?: string | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
     artifact?: {
@@ -410,6 +418,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
+    gradleUserHome?: string | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
     artifact?: {
@@ -571,6 +580,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath: z.ZodString;
     mapping: z.ZodOptional<z.ZodEnum<["obfuscated", "mojang", "intermediary", "yarn"]>>;
     scope: z.ZodOptional<z.ZodEnum<["vanilla", "merged", "loader"]>>;
+    gradleUserHome: z.ZodOptional<z.ZodString>;
     preferProjectVersion: z.ZodOptional<z.ZodBoolean>;
     strictVersion: z.ZodOptional<z.ZodBoolean>;
     focus: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
@@ -786,6 +796,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath: string;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
+    gradleUserHome?: string | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
     focus?: {
@@ -839,6 +850,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     projectPath: string;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     scope?: "vanilla" | "merged" | "loader" | undefined;
+    gradleUserHome?: string | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
     focus?: {
@@ -922,6 +934,7 @@ export type InspectMinecraftDeps = {
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
         scope?: "vanilla" | "merged" | "loader";
         projectPath?: string;
+        gradleUserHome?: string;
         preferProjectVersion?: boolean;
         strictVersion?: boolean;
     }) => Promise<ResolveArtifactOutput>;
@@ -938,6 +951,7 @@ export type InspectMinecraftDeps = {
         descriptor?: string;
         sourceMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
         sourcePriority?: "loom-first" | "maven-first";
+        gradleUserHome?: string;
         nameMode?: "fqcn" | "auto";
         signatureMode?: "exact" | "name-only";
         maxCandidates?: number;
@@ -952,6 +966,7 @@ export type InspectMinecraftDeps = {
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
         scope?: "vanilla" | "merged" | "loader";
         projectPath?: string;
+        gradleUserHome?: string;
         preferProjectVersion?: boolean;
         strictVersion?: boolean;
         mode?: "metadata" | "snippet" | "full";
@@ -968,6 +983,7 @@ export type InspectMinecraftDeps = {
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
         scope?: "vanilla" | "merged" | "loader";
         projectPath?: string;
+        gradleUserHome?: string;
         preferProjectVersion?: boolean;
         strictVersion?: boolean;
         maxMembers?: number;
@@ -1030,6 +1046,7 @@ export declare function invalidTaskSubjectError(task: ConcreteInspectMinecraftTa
 export declare function resolveBinaryBackedClass(deps: InspectMinecraftDeps, className: string, input: {
     version?: string;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
+    gradleUserHome?: string;
 }): Promise<{
     className: string;
     warnings: string[];