@adhisang/minecraft-modding-mcp 4.1.0 → 4.2.0

package/dist/entry-tools/validate-project/internal.d.ts

@@ -1,3 +1,4 @@
+import type { StageEmitter } from "../../stage-emitter.js";
 import type { SourceMapping } from "../../types.js";
 type TaskStatus = "ok" | "skipped" | "missing" | "error";
 type TaskEntryBase = {
@@ -44,8 +45,27 @@ type TaskStatusReport = {
         };
     };
 };
+type MinecraftArtifactProbeInput = {
+    target: {
+        kind: "version";
+        value: string;
+    };
+    mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
+    sourcePriority?: "loom-first" | "maven-first";
+    projectPath?: string;
+    gradleUserHome?: string;
+    scope?: "vanilla" | "merged" | "loader";
+    preferProjectVersion?: boolean;
+};
+type MinecraftArtifactProbeOutput = {
+    artifactId: string;
+    mappingApplied: SourceMapping;
+    warnings?: string[];
+};
 export type ValidateProjectDeps = {
-    validateMixin: (input: Record<string, unknown>) => Promise<Record<string, unknown> & {
+    validateMixin: (input: Record<string, unknown>, options?: {
+        stageEmitter?: StageEmitter;
+    }) => Promise<Record<string, unknown> & {
         warnings?: string[];
     }>;
     validateAccessWidener: (input: {
@@ -54,6 +74,7 @@ export type ValidateProjectDeps = {
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
         sourcePriority?: "loom-first" | "maven-first";
         projectPath?: string;
+        gradleUserHome?: string;
         scope?: "vanilla" | "merged" | "loader";
         preferProjectVersion?: boolean;
     }) => Promise<Record<string, unknown> & {
@@ -65,6 +86,7 @@ export type ValidateProjectDeps = {
         atNamespace?: "srg" | "mojang" | "obfuscated";
         sourcePriority?: "loom-first" | "maven-first";
         projectPath?: string;
+        gradleUserHome?: string;
         scope?: "vanilla" | "merged" | "loader";
         preferProjectVersion?: boolean;
     }) => Promise<Record<string, unknown> & {
@@ -74,23 +96,10 @@ export type ValidateProjectDeps = {
     discoverAccessWideners: (projectPath: string) => Promise<string[]>;
     discoverAccessTransformers?: (projectPath: string) => Promise<string[]>;
     detectProjectMinecraftVersion?: (projectPath: string) => Promise<string | undefined>;
-    resolveArtifact?: (input: {
-        target: {
-            kind: "version";
-            value: string;
-        };
-        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
-        sourcePriority?: "loom-first" | "maven-first";
-        projectPath?: string;
-        scope?: "vanilla" | "merged" | "loader";
-        preferProjectVersion?: boolean;
-    }) => Promise<{
-        artifactId: string;
-        mappingApplied: SourceMapping;
-        warnings?: string[];
-    }>;
+    probeMinecraftArtifact?: (input: MinecraftArtifactProbeInput) => Promise<MinecraftArtifactProbeOutput>;
+    resolveArtifact?: (input: MinecraftArtifactProbeInput) => Promise<MinecraftArtifactProbeOutput>;
 };
-export declare function runUpstreamProbes(projectPath: string): Promise<{
+export declare function runUpstreamProbes(projectPath: string, gradleUserHome?: string): Promise<{
     workspace: TaskStatusReport["workspace.detected"];
     gradle: TaskStatusReport["gradle.readable"];
     loom: TaskStatusReport["loom.cache.found"];
@@ -99,7 +108,7 @@ export declare function buildEarlyTasksForBlocked(projectPath: string, detail: "
     mixinDiscoveryCount: number;
     awDiscoveryCount: number;
     atDiscoveryCount: number;
-}): Promise<TaskStatusReport | undefined>;
+}, gradleUserHome?: string): Promise<TaskStatusReport | undefined>;
 export declare function buildFullTaskStatusReport(deps: ValidateProjectDeps, args: {
     projectPath: string;
     detail: "summary" | "standard" | "full";
@@ -107,6 +116,7 @@ export declare function buildFullTaskStatusReport(deps: ValidateProjectDeps, arg
     resolvedVersion: string;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
     sourcePriority?: "loom-first" | "maven-first";
+    gradleUserHome?: string;
     scope?: "vanilla" | "merged" | "loader";
     preferProjectVersion?: boolean;
     mixinDiscoveryCount: number;
@@ -131,5 +141,6 @@ export declare function buildFullTaskStatusReport(deps: ValidateProjectDeps, arg
         invalid: number;
     };
     atDurationMs: number;
+    stageEmitter?: StageEmitter;
 }): Promise<TaskStatusReport | undefined>;
 export {};

package/dist/entry-tools/validate-project/internal.js

@@ -100,10 +100,10 @@ async function probeGradleReadable(projectPath) {
         };
     }
 }
-async function probeLoomCacheFound(projectPath) {
+async function probeLoomCacheFound(projectPath, gradleUserHome) {
     const startedAt = Date.now();
     try {
-        const roots = buildVersionSourceSearchRoots(projectPath);
+        const roots = buildVersionSourceSearchRoots({ projectPath, gradleUserHome });
         for (const root of roots) {
             if (await pathExists(root)) {
                 return {
@@ -126,14 +126,28 @@ async function probeLoomCacheFound(projectPath) {
         };
     }
 }
-async function probeMinecraftArtifactResolved(resolveArtifact, args) {
+async function probeMinecraftArtifactResolved(artifactProbe, args, stageEmitter) {
     const startedAt = Date.now();
+    // Stage notification kept outside the probe's try block: a telemetry
+    // failure must not be classified as ERR_ARTIFACT_PROBE_FAILED.
     try {
-        const output = await resolveArtifact({
+        await stageEmitter?.("validate-project:artifact-probe", {
+            version: args.version,
+            mapping: args.mapping ?? "obfuscated",
+            projectPath: args.projectPath,
+            scope: args.scope ?? null
+        });
+    }
+    catch {
+        // swallow telemetry failure
+    }
+    try {
+        const output = await artifactProbe({
             target: { kind: "version", value: args.version },
             mapping: args.mapping,
             sourcePriority: args.sourcePriority,
             projectPath: args.projectPath,
+            gradleUserHome: args.gradleUserHome,
             scope: args.scope,
             preferProjectVersion: args.preferProjectVersion
         });
@@ -168,16 +182,18 @@ function downstreamSkipReason(report, upstream) {
     return undefined;
 }
 function buildValidationEntryWithCounts(upstream, discoveredCount, errorCount, counts, durationMs) {
+    // Real validator outcomes win over upstream skip when validators ran.
+    // The artifact probe is informational; its failure must not erase real counts.
+    if (discoveredCount > 0 || errorCount > 0) {
+        if (errorCount > 0) {
+            return { status: "error", durationMs, counts };
+        }
+        return { status: "ok", durationMs, counts };
+    }
     if (upstream) {
         return upstream;
     }
-    if (discoveredCount === 0) {
-        return { status: "missing", durationMs };
-    }
-    if (errorCount > 0) {
-        return { status: "error", durationMs, counts };
-    }
-    return { status: "ok", durationMs, counts };
+    return { status: "missing", durationMs };
 }
 function projectTaskEntry(entry, detail, include) {
     const fullDetail = detail !== "summary" && include.includes("workspace");
@@ -200,9 +216,9 @@ function projectTaskStatusReport(report, detail, include) {
     }
     return projected;
 }
-export async function runUpstreamProbes(projectPath) {
+export async function runUpstreamProbes(projectPath, gradleUserHome) {
     const workspace = await probeWorkspaceDetected(projectPath);
-    const loom = await probeLoomCacheFound(projectPath);
+    const loom = await probeLoomCacheFound(projectPath, gradleUserHome);
     let gradle;
     if (workspace.status !== "ok") {
         gradle = { status: "skipped" };
@@ -212,11 +228,11 @@ export async function runUpstreamProbes(projectPath) {
     }
     return { workspace, gradle, loom };
 }
-export async function buildEarlyTasksForBlocked(projectPath, detail, include, discovery) {
+export async function buildEarlyTasksForBlocked(projectPath, detail, include, discovery, gradleUserHome) {
     if (VALIDATE_PROJECT_TASKS_OFF) {
         return undefined;
     }
-    const { workspace, gradle, loom } = await runUpstreamProbes(projectPath);
+    const { workspace, gradle, loom } = await runUpstreamProbes(projectPath, gradleUserHome);
     const minecraftArtifactResolved = {
         status: "skipped"
     };
@@ -247,20 +263,22 @@ export async function buildFullTaskStatusReport(deps, args) {
     if (VALIDATE_PROJECT_TASKS_OFF) {
         return undefined;
     }
-    const { workspace, gradle, loom } = await runUpstreamProbes(args.projectPath);
+    const { workspace, gradle, loom } = await runUpstreamProbes(args.projectPath, args.gradleUserHome);
     let minecraftArtifactResolved;
     if (workspace.status !== "ok" || gradle.status !== "ok") {
         minecraftArtifactResolved = { status: "skipped" };
     }
-    else if (deps.resolveArtifact) {
-        minecraftArtifactResolved = await probeMinecraftArtifactResolved(deps.resolveArtifact, {
+    else if (deps.probeMinecraftArtifact ?? deps.resolveArtifact) {
+        const artifactProbe = deps.probeMinecraftArtifact ?? deps.resolveArtifact;
+        minecraftArtifactResolved = await probeMinecraftArtifactResolved(artifactProbe, {
             version: args.resolvedVersion,
             mapping: args.mapping,
             sourcePriority: args.sourcePriority,
             projectPath: args.projectPath,
+            gradleUserHome: args.gradleUserHome,
             scope: args.scope,
             preferProjectVersion: args.preferProjectVersion
-        });
+        }, args.stageEmitter);
     }
     else {
         minecraftArtifactResolved = { status: "skipped" };

package/dist/entry-tools/validate-project-service.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { StageEmitter } from "../stage-emitter.js";
 import type { SourceMapping } from "../types.js";
 import { type ValidateProjectDeps } from "./validate-project/internal.js";
 export type TaskStatus = "ok" | "skipped" | "missing" | "error";
@@ -51,14 +52,17 @@ export declare const validateProjectShape: {
     subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"workspace">;
         projectPath: z.ZodString;
+        gradleUserHome: z.ZodOptional<z.ZodString>;
         discover: z.ZodOptional<z.ZodArray<z.ZodEnum<["mixins", "access-wideners", "access-transformers"]>, "many">>;
     }, "strip", z.ZodTypeAny, {
         kind: "workspace";
         projectPath: string;
+        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
     }, {
         kind: "workspace";
         projectPath: string;
+        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"mixin">;
@@ -247,14 +251,17 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"workspace">;
         projectPath: z.ZodString;
+        gradleUserHome: z.ZodOptional<z.ZodString>;
         discover: z.ZodOptional<z.ZodArray<z.ZodEnum<["mixins", "access-wideners", "access-transformers"]>, "many">>;
     }, "strip", z.ZodTypeAny, {
         kind: "workspace";
         projectPath: string;
+        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
     }, {
         kind: "workspace";
         projectPath: string;
+        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"mixin">;
@@ -448,6 +455,7 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     subject: {
         kind: "workspace";
         projectPath: string;
+        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
     } | {
         kind: "mixin";
@@ -503,6 +511,7 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     subject: {
         kind: "workspace";
         projectPath: string;
+        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
     } | {
         kind: "mixin";
@@ -570,6 +579,7 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     subject: {
         kind: "workspace";
         projectPath: string;
+        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
     } | {
         kind: "mixin";
@@ -625,6 +635,7 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     subject: {
         kind: "workspace";
         projectPath: string;
+        gradleUserHome?: string | undefined;
         discover?: ("mixins" | "access-wideners" | "access-transformers")[] | undefined;
     } | {
         kind: "mixin";
@@ -683,13 +694,16 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     include?: string[] | undefined;
 }>;
 export type ValidateProjectInput = z.infer<typeof validateProjectSchema>;
+export type ValidateProjectExecuteOptions = {
+    stageEmitter?: StageEmitter;
+};
 export declare function discoverWorkspaceMixins(projectPath: string, configPaths?: string[]): Promise<string[]>;
 export declare function discoverWorkspaceAccessWideners(projectPath: string): Promise<string[]>;
 export declare function discoverWorkspaceAccessTransformers(projectPath: string): Promise<string[]>;
 export declare class ValidateProjectService {
     private readonly deps;
     constructor(deps: ValidateProjectDeps);
-    execute(input: ValidateProjectInput): Promise<Record<string, unknown> & {
+    execute(input: ValidateProjectInput, options?: ValidateProjectExecuteOptions): Promise<Record<string, unknown> & {
         warnings?: string[];
     }>;
 }

package/dist/entry-tools/validate-project-service.js

@@ -31,6 +31,7 @@ const subjectSchema = z.discriminatedUnion("kind", [
     z.object({
         kind: z.literal("workspace"),
         projectPath: nonEmptyString,
+        gradleUserHome: nonEmptyString.optional(),
         discover: z.array(z.enum(["mixins", "access-wideners", "access-transformers"])).optional()
     }),
     z.object({
@@ -263,7 +264,7 @@ export class ValidateProjectService {
     constructor(deps) {
         this.deps = deps;
     }
-    async execute(input) {
+    async execute(input, options = {}) {
         const detail = resolveDetail(input.detail);
         const include = resolveInclude(input.include);
         switch (input.task) {
@@ -274,7 +275,7 @@ export class ValidateProjectService {
             case "access-transformer":
                 return handleAccessTransformer(this.deps, input, detail, include);
             case "project-summary":
-                return handleProjectSummary(this.deps, input, detail, include);
+                return handleProjectSummary(this.deps, input, detail, include, options);
         }
     }
 }

package/dist/entry-tools/verify-mixin-target-service.d.ts

@@ -16,6 +16,7 @@ export type VerifyMixinTargetInput = {
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     projectPath?: string;
+    gradleUserHome?: string;
     target?: ResolveArtifactTargetInput;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
@@ -82,6 +83,7 @@ export type VerifyMixinTargetDeps = {
         mapping?: SourceMapping;
         sourcePriority?: MappingSourcePriority;
         projectPath?: string;
+        gradleUserHome?: string;
         scope?: ArtifactScope;
         preferProjectVersion?: boolean;
         strictVersion?: boolean;

package/dist/entry-tools/verify-mixin-target-service.js

@@ -185,6 +185,7 @@ export class VerifyMixinTargetService {
             mapping: input.mapping,
             sourcePriority: input.sourcePriority,
             projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome,
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion,
             strictVersion: input.strictVersion

package/dist/gradle-paths.d.ts

@@ -1,4 +1,9 @@
 export declare function normalizeOptionalProjectPath(projectPath: string | undefined): string | undefined;
-export declare function resolveGradleUserHomePath(): string;
-export declare function buildVersionSourceSearchRoots(projectPath: string | undefined): string[];
-export declare function buildLoaderRuntimeSearchRoots(projectPath: string | undefined): string[];
+export declare function normalizeOptionalGradleUserHomePath(gradleUserHome: string | undefined): string | undefined;
+export declare function resolveGradleUserHomePath(gradleUserHome?: string): string;
+export type GradleCacheSearchInput = string | {
+    projectPath?: string;
+    gradleUserHome?: string;
+} | undefined;
+export declare function buildVersionSourceSearchRoots(input: GradleCacheSearchInput): string[];
+export declare function buildLoaderRuntimeSearchRoots(input: GradleCacheSearchInput): string[];

package/dist/gradle-paths.js

@@ -12,7 +12,22 @@ export function normalizeOptionalProjectPath(projectPath) {
     const normalized = normalizePathForHost(trimmed, undefined, "projectPath");
     return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
 }
-export function resolveGradleUserHomePath() {
+export function normalizeOptionalGradleUserHomePath(gradleUserHome) {
+    if (!gradleUserHome) {
+        return undefined;
+    }
+    const trimmed = gradleUserHome.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const normalized = normalizePathForHost(trimmed, undefined, "gradleUserHome");
+    return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
+}
+export function resolveGradleUserHomePath(gradleUserHome) {
+    const explicit = normalizeOptionalGradleUserHomePath(gradleUserHome);
+    if (explicit) {
+        return explicit;
+    }
     const configured = process.env.GRADLE_USER_HOME?.trim();
     if (!configured) {
         return resolvePath(homedir(), ".gradle");
@@ -20,7 +35,20 @@ export function resolveGradleUserHomePath() {
     const normalized = normalizePathForHost(configured, undefined, "GRADLE_USER_HOME");
     return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
 }
-export function buildVersionSourceSearchRoots(projectPath) {
+function normalizeGradleCacheSearchInput(input) {
+    if (typeof input === "string" || input === undefined) {
+        return {
+            projectPath: normalizeOptionalProjectPath(input)
+        };
+    }
+    const gradleUserHome = normalizeOptionalGradleUserHomePath(input.gradleUserHome);
+    return {
+        projectPath: normalizeOptionalProjectPath(input.projectPath),
+        gradleUserHome
+    };
+}
+export function buildVersionSourceSearchRoots(input) {
+    const { projectPath, gradleUserHome } = normalizeGradleCacheSearchInput(input);
     const roots = new Set();
     if (projectPath) {
         roots.add(resolvePath(projectPath, ".gradle", "loom-cache"));
@@ -30,12 +58,13 @@ export function buildVersionSourceSearchRoots(projectPath) {
         roots.add(resolvePath(projectParent, ".gradle-user-home", "loom-cache"));
         roots.add(resolvePath(projectParent, ".gradle-user-home", "caches", "fabric-loom"));
     }
-    const homeGradle = resolveGradleUserHomePath();
+    const homeGradle = resolveGradleUserHomePath(gradleUserHome);
     roots.add(resolvePath(homeGradle, "loom-cache"));
     roots.add(resolvePath(homeGradle, "caches", "fabric-loom"));
     return [...roots];
 }
-export function buildLoaderRuntimeSearchRoots(projectPath) {
+export function buildLoaderRuntimeSearchRoots(input) {
+    const { projectPath, gradleUserHome } = normalizeGradleCacheSearchInput(input);
     const roots = new Set();
     if (projectPath) {
         roots.add(resolvePath(projectPath, "build"));
@@ -47,7 +76,7 @@ export function buildLoaderRuntimeSearchRoots(projectPath) {
         roots.add(resolvePath(projectPath, ".gradle", "caches", "neoformruntime"));
         roots.add(resolvePath(projectPath, ".gradle", "caches", "moddev"));
     }
-    const homeGradle = resolveGradleUserHomePath();
+    const homeGradle = resolveGradleUserHomePath(gradleUserHome);
     roots.add(resolvePath(homeGradle, "caches", "forge_gradle"));
     roots.add(resolvePath(homeGradle, "caches", "neogradle"));
     roots.add(resolvePath(homeGradle, "caches", "neoformruntime"));

package/dist/index.js

@@ -129,7 +129,7 @@ const analyzeModService = new AnalyzeModService({
     remapModJar: (input) => remapModJar(input, config)
 });
 const validateProjectService = new ValidateProjectService({
-    validateMixin: (input) => sourceService.validateMixin(input),
+    validateMixin: (input, options) => sourceService.validateMixin(input, options),
     validateAccessWidener: (input) => sourceService.validateAccessWidener(input),
     validateAccessTransformer: (input) => sourceService.validateAccessTransformer(input),
     discoverMixins: discoverWorkspaceMixins,
@@ -142,6 +142,7 @@ const validateProjectService = new ValidateProjectService({
             mapping: input.mapping,
             sourcePriority: input.sourcePriority,
             projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome,
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion
         });
@@ -150,7 +151,8 @@ const validateProjectService = new ValidateProjectService({
             mappingApplied: output.mappingApplied,
             warnings: output.warnings
         };
-    }
+    },
+    probeMinecraftArtifact: (input) => sourceService.probeMinecraftArtifact(input)
 });
 const manageCacheService = new ManageCacheService({
     registry: createCacheRegistry({
@@ -165,6 +167,7 @@ const verifyMixinTargetService = new VerifyMixinTargetService({
             mapping: input.mapping,
             sourcePriority: input.sourcePriority,
             projectPath: input.projectPath,
+            gradleUserHome: input.gradleUserHome,
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion,
             strictVersion: input.strictVersion
@@ -405,17 +408,19 @@ server.tool("list-versions", "List available Minecraft versions from Mojang mani
     limit: input.limit
 })));
 registerToolSchema("list-versions", listVersionsSchema);
-server.tool("inspect-minecraft", "High-level v3 entry tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings.", inspectMinecraftShape, { readOnlyHint: true }, async (args) => runTool("inspect-minecraft", args, inspectMinecraftSchema, async (input) => inspectMinecraftService.execute(input)));
+server.tool("inspect-minecraft", "Top-level workflow tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings.", inspectMinecraftShape, { readOnlyHint: true }, async (args) => runTool("inspect-minecraft", args, inspectMinecraftSchema, async (input) => inspectMinecraftService.execute(input)));
 registerToolSchema("inspect-minecraft", inspectMinecraftSchema);
-server.tool("analyze-symbol", "High-level v3 entry tool for symbol existence, mapping, lifecycle, workspace analysis, and API overview.", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
+server.tool("analyze-symbol", "Top-level workflow tool for symbol existence, mapping, lifecycle, workspace analysis, and API overview.", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
 registerToolSchema("analyze-symbol", analyzeSymbolSchema);
-server.tool("compare-minecraft", "High-level v3 entry tool for version comparisons, class diffs, registry diffs, and migration overviews.", compareMinecraftShape, { readOnlyHint: true }, async (args) => runTool("compare-minecraft", args, compareMinecraftSchema, async (input) => compareMinecraftService.execute(input)));
+server.tool("compare-minecraft", "Top-level workflow tool for version comparisons, class diffs, registry diffs, and migration overviews.", compareMinecraftShape, { readOnlyHint: true }, async (args) => runTool("compare-minecraft", args, compareMinecraftSchema, async (input) => compareMinecraftService.execute(input)));
 registerToolSchema("compare-minecraft", compareMinecraftSchema);
-server.tool("analyze-mod", "High-level v3 entry tool for mod metadata inspection, decompile/search flows, class source, and safe remap previews/applies.", analyzeModShape, { readOnlyHint: false }, async (args) => runTool("analyze-mod", args, analyzeModSchema, async (input) => analyzeModService.execute(input)));
+server.tool("analyze-mod", "Top-level workflow tool for mod metadata inspection, decompile/search flows, class source, and safe remap previews/applies.", analyzeModShape, { readOnlyHint: false }, async (args) => runTool("analyze-mod", args, analyzeModSchema, async (input) => analyzeModService.execute(input)));
 registerToolSchema("analyze-mod", analyzeModSchema);
-server.tool("validate-project", "High-level v3 entry tool for project summary, direct mixin validation, and access widener/access transformer validation.", validateProjectShape, { readOnlyHint: true }, async (args) => runTool("validate-project", args, validateProjectSchema, async (input) => validateProjectService.execute(input)));
+server.tool("validate-project", "Top-level workflow tool for project summary, direct mixin validation, and access widener/access transformer validation.", validateProjectShape, { readOnlyHint: true }, async (args, extra) => runTool("validate-project", args, validateProjectSchema, async (input) => validateProjectService.execute(input, {
+    stageEmitter: makeStageEmitter(extra)
+})));
 registerToolSchema("validate-project", validateProjectSchema);
-server.tool("manage-cache", "High-level v3 entry tool for cache summaries, listing, verification, previewed mutation, and explicit apply operations.", manageCacheShape, { readOnlyHint: false }, async (args) => runTool("manage-cache", args, manageCacheSchema, async (input) => manageCacheService.execute(input)));
+server.tool("manage-cache", "Top-level workflow tool for cache summaries, listing, verification, previewed mutation, and explicit apply operations.", manageCacheShape, { readOnlyHint: false }, async (args) => runTool("manage-cache", args, manageCacheSchema, async (input) => manageCacheService.execute(input)));
 registerToolSchema("manage-cache", manageCacheSchema);
 if (!VERIFY_MIXIN_TARGET_OFF) {
     server.tool("verify-mixin-target", "Single-call probe: does this target owner / member exist and which @Shadow / @Accessor / @Invoker should the mixin use? Reuses target.kind workspace/version/coordinate/dependency/jar.", verifyMixinTargetShape, { readOnlyHint: true }, async (args) => runTool("verify-mixin-target", args, verifyMixinTargetSchema, async (input) => verifyMixinTargetService.execute({
@@ -425,6 +430,7 @@ if (!VERIFY_MIXIN_TARGET_OFF) {
         mapping: input.mapping,
         sourcePriority: input.sourcePriority,
         projectPath: input.projectPath,
+        gradleUserHome: input.gradleUserHome,
         target: input.target,
         scope: input.scope,
         preferProjectVersion: input.preferProjectVersion,
@@ -448,6 +454,7 @@ server.tool("resolve-artifact", "Resolve source artifact from a target object ({
     sourcePriority: input.sourcePriority,
     allowDecompile: input.allowDecompile,
     projectPath: input.projectPath,
+    gradleUserHome: input.gradleUserHome,
     scope: input.scope,
     preferProjectVersion: input.preferProjectVersion,
     strictVersion: input.strictVersion,
@@ -477,6 +484,7 @@ server.tool("get-class-source", "Get Java source for a class by target ({ type:
         sourcePriority: input.sourcePriority,
         allowDecompile: input.allowDecompile,
         projectPath: input.projectPath,
+        gradleUserHome: input.gradleUserHome,
         scope: input.scope,
         preferProjectVersion: input.preferProjectVersion,
         strictVersion: input.strictVersion,
@@ -503,6 +511,7 @@ server.tool("get-class-members", "Get fields/methods/constructors for one class
         memberPattern: input.memberPattern,
         maxMembers: input.maxMembers,
         projectPath: input.projectPath,
+        gradleUserHome: input.gradleUserHome,
         scope: input.scope,
         preferProjectVersion: input.preferProjectVersion,
         strictVersion: input.strictVersion
@@ -527,7 +536,8 @@ server.tool("search-class-source", "Search indexed class source files for one ar
         limit: input.limit,
         cursor: input.cursor,
         queryNamespace: input.queryNamespace,
-        sourcePriority: input.sourcePriority
+        sourcePriority: input.sourcePriority,
+        gradleUserHome: input.gradleUserHome
     });
 }));
 registerToolSchema("search-class-source", searchClassSourceSchema);
@@ -551,6 +561,7 @@ server.tool("trace-symbol-lifecycle", "Trace which Minecraft versions contain a
     toVersion: input.toVersion,
     mapping: input.mapping,
     sourcePriority: input.sourcePriority,
+    gradleUserHome: input.gradleUserHome,
     includeSnapshots: input.includeSnapshots,
     maxVersions: input.maxVersions,
     includeTimeline: input.includeTimeline
@@ -562,6 +573,7 @@ server.tool("diff-class-signatures", "Compare one class signature between two Mi
     toVersion: input.toVersion,
     mapping: input.mapping,
     sourcePriority: input.sourcePriority,
+    gradleUserHome: input.gradleUserHome,
     includeFullDiff: input.includeFullDiff
 })));
 registerToolSchema("diff-class-signatures", diffClassSignaturesSchema);
@@ -574,6 +586,7 @@ server.tool("find-mapping", "Find symbol mapping candidates between namespaces u
     sourceMapping: input.sourceMapping,
     targetMapping: input.targetMapping,
     sourcePriority: input.sourcePriority,
+    gradleUserHome: input.gradleUserHome,
     signatureMode: input.signatureMode,
     disambiguation: input.disambiguation,
     maxCandidates: input.maxCandidates
@@ -587,6 +600,7 @@ server.tool("resolve-method-mapping-exact", "Resolve one method mapping exactly
     sourceMapping: input.sourceMapping,
     targetMapping: input.targetMapping,
     sourcePriority: input.sourcePriority,
+    gradleUserHome: input.gradleUserHome,
     maxCandidates: input.maxCandidates
 })));
 registerToolSchema("resolve-method-mapping-exact", resolveMethodMappingExactSchema);
@@ -596,6 +610,7 @@ server.tool("get-class-api-matrix", "List class/member API rows across obfuscate
     classNameMapping: input.classNameMapping,
     includeKinds: parseClassApiKinds(input.includeKinds),
     sourcePriority: input.sourcePriority,
+    gradleUserHome: input.gradleUserHome,
     maxRows: input.maxRows
 })));
 registerToolSchema("get-class-api-matrix", getClassApiMatrixSchema);
@@ -608,6 +623,7 @@ server.tool("resolve-workspace-symbol", "Resolve class/field/method names as see
     descriptor: input.descriptor,
     sourceMapping: input.sourceMapping,
     sourcePriority: input.sourcePriority,
+    gradleUserHome: input.gradleUserHome,
     maxCandidates: input.maxCandidates
 })));
 registerToolSchema("resolve-workspace-symbol", resolveWorkspaceSymbolSchema);
@@ -619,6 +635,7 @@ server.tool("check-symbol-exists", "Check whether a class/field/method symbol ex
     descriptor: input.descriptor,
     sourceMapping: input.sourceMapping,
     sourcePriority: input.sourcePriority,
+    gradleUserHome: input.gradleUserHome,
     nameMode: input.nameMode,
     signatureMode: input.signatureMode,
     maxCandidates: input.maxCandidates
@@ -654,6 +671,7 @@ server.tool("validate-mixin", "Validate Mixin source against Minecraft bytecode
     sourcePriority: input.sourcePriority,
     scope: input.scope,
     projectPath: input.projectPath,
+    gradleUserHome: input.gradleUserHome,
     preferProjectVersion: input.preferProjectVersion,
     minSeverity: input.minSeverity,
     hideUncertain: input.hideUncertain,
@@ -674,6 +692,7 @@ server.tool("validate-access-widener", "Validate Access Widener file entries aga
     mapping: input.mapping,
     sourcePriority: input.sourcePriority,
     projectPath: input.projectPath,
+    gradleUserHome: input.gradleUserHome,
     scope: input.scope,
     preferProjectVersion: input.preferProjectVersion
 })));
@@ -684,6 +703,7 @@ server.tool("validate-access-transformer", "Validate Access Transformer file ent
     atNamespace: input.atNamespace,
     sourcePriority: input.sourcePriority,
     projectPath: input.projectPath,
+    gradleUserHome: input.gradleUserHome,
     scope: input.scope,
     preferProjectVersion: input.preferProjectVersion
 })));

package/dist/mapping/loaders/tiny-loom.d.ts

@@ -1,2 +1,2 @@
 import type { MappingLoaderResult } from "./types.js";
-export declare function loadTinyPairsFromLoom(version: string, projectPath?: string): Promise<MappingLoaderResult>;
+export declare function loadTinyPairsFromLoom(version: string, projectPath?: string, gradleUserHome?: string): Promise<MappingLoaderResult>;

package/dist/mapping/loaders/tiny-loom.js

@@ -7,8 +7,11 @@ import { effectiveLoomSearchProjectPath } from "../lookup.js";
 import { mergeDirectionIndexes } from "../parsers/symbol-records.js";
 import { parseTinyMappings } from "../parsers/tiny.js";
 const GLOB_SPECIAL_CHARS = /[\\!*+?()[\]{}@|]/g;
-export async function loadTinyPairsFromLoom(version, projectPath) {
-    const searchRoots = buildVersionSourceSearchRoots(effectiveLoomSearchProjectPath(projectPath));
+export async function loadTinyPairsFromLoom(version, projectPath, gradleUserHome) {
+    const searchRoots = buildVersionSourceSearchRoots({
+        projectPath: effectiveLoomSearchProjectPath(projectPath),
+        gradleUserHome
+    });
     const merged = new Map();
     const discoveredPaths = new Set();
     for (const root of searchRoots) {