@adhisang/minecraft-modding-mcp 3.1.1 → 3.2.0

package/dist/index.js

@@ -4,6 +4,7 @@ import { ZodError, z } from "zod";
 import { CompatStdioServerTransport } from "./compat-stdio-transport.js";
 import { objectResult } from "./mcp-helpers.js";
 import { prepareToolInput } from "./tool-input.js";
+import { isCompactEnabled, COMPACT_MAPPING_TOOL_NAMES, compactResponse, compactArtifactResponse, compactMappingResponse } from "./response-utils.js";
 import { loadConfig } from "./config.js";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { log } from "./logger.js";
@@ -18,7 +19,7 @@ import { InspectMinecraftService, inspectMinecraftSchema, inspectMinecraftShape
 import { AnalyzeSymbolService, analyzeSymbolSchema, analyzeSymbolShape } from "./entry-tools/analyze-symbol-service.js";
 import { CompareMinecraftService, compareMinecraftSchema, compareMinecraftShape } from "./entry-tools/compare-minecraft-service.js";
 import { AnalyzeModService, analyzeModSchema, analyzeModShape } from "./entry-tools/analyze-mod-service.js";
-import { ValidateProjectService, validateProjectSchema, validateProjectShape, discoverWorkspaceAccessWideners, discoverWorkspaceMixins } from "./entry-tools/validate-project-service.js";
+import { ValidateProjectService, validateProjectSchema, validateProjectShape, discoverWorkspaceAccessTransformers, discoverWorkspaceAccessWideners, discoverWorkspaceMixins } from "./entry-tools/validate-project-service.js";
 import { ManageCacheService, manageCacheSchema, manageCacheShape } from "./entry-tools/manage-cache-service.js";
 import { createCacheRegistry } from "./cache-registry.js";
 import { buildEntryToolMeta } from "./entry-tools/response-contract.js";
@@ -89,7 +90,7 @@ const sourceLookupTargetSchema = z.discriminatedUnion("type", [
 ]);
 const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = "Object with kind and value. Example: {\"kind\":\"version\",\"value\":\"1.21.10\"}. Must be an object, not a string.";
 const SOURCE_LOOKUP_TARGET_DESCRIPTION = "Object: {\"type\":\"resolve\",\"kind\":\"version\",\"value\":\"1.21.10\"} or {\"type\":\"artifact\",\"artifactId\":\"...\"}. Must be an object, not a string.";
-const SOURCE_SCOPE_DESCRIPTION = 'vanilla = Mojang client jar only; merged = Loom cache discovery (default); loader = currently behaves the same as "merged".';
+const SOURCE_SCOPE_DESCRIPTION = "vanilla = Mojang client jar only; merged = source-oriented merged runtime discovery; loader = loader/runtime artifact discovery when the workspace exposes transformed runtime jars.";
 const SUGGESTED_CALL_DEFAULTS = {
     allowDecompile: true,
     preferProjectVersion: false,
@@ -129,7 +130,9 @@ const resolveArtifactShape = {
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
-    strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false.")
+    strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
+    compact: z.boolean().default(false).describe("When true, return minimal fields (artifactId, origin, isDecompiled, version, requestedMapping, mappingApplied, qualityFlags). "
+        + "Omit provenance, artifactContents, sampleEntries, adjacentSourceCandidates, binaryJarPath, coordinate, repoUrl, resolvedSourceJarPath.")
 };
 const resolveArtifactSchema = z.object(resolveArtifactShape);
 const getClassSourceShape = {
@@ -250,7 +253,9 @@ const findMappingShape = {
     })
         .partial()
         .optional(),
-    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)"),
+    compact: z.boolean().default(false).describe("When true, omit top-level empty arrays, null/undefined values, and empty objects from the response. "
+        + "Also omit redundant candidates array for single full-confidence exact-match resolutions.")
 };
 const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -317,7 +322,9 @@ const resolveMethodMappingExactShape = {
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)"),
+    compact: z.boolean().default(false).describe("When true, omit top-level empty arrays, null/undefined values, and empty objects from the response. "
+        + "Also omit redundant candidates array for single full-confidence exact-match resolutions.")
 };
 const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
@@ -368,7 +375,9 @@ const resolveWorkspaceSymbolShape = {
     descriptor: optionalNonEmptyString,
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates for field/method lookups (max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates for field/method lookups (max 200)"),
+    compact: z.boolean().default(false).describe("When true, omit top-level empty arrays, null/undefined values, and empty objects from the response. "
+        + "Also omit redundant candidates array for single full-confidence exact-match resolutions.")
 };
 const resolveWorkspaceSymbolSchema = z
     .object(resolveWorkspaceSymbolShape)
@@ -440,7 +449,9 @@ const checkSymbolExistsShape = {
     nameMode: classNameModeSchema.default("fqcn").describe("fqcn | auto"),
     signatureMode: z.enum(["exact", "name-only"]).default("exact")
         .describe("exact: require descriptor for methods; name-only: match by owner+name only"),
-    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)"),
+    compact: z.boolean().default(false).describe("When true, omit top-level empty arrays, null/undefined values, and empty objects from the response. "
+        + "Also omit redundant candidates array for single full-confidence exact-match resolutions.")
 };
 const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -581,9 +592,24 @@ const validateAccessWidenerShape = {
     content: nonEmptyString.describe("Access Widener file content"),
     version: nonEmptyString.describe("Minecraft version"),
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted runtime validation"),
+    scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
+    preferProjectVersion: z.boolean().default(false)
+        .describe("When true, detect MC version from gradle.properties and override version")
 };
 const validateAccessWidenerSchema = z.object(validateAccessWidenerShape);
+const validateAccessTransformerShape = {
+    content: nonEmptyString.describe("Access Transformer file content"),
+    version: nonEmptyString.describe("Minecraft version"),
+    atNamespace: z.enum(["srg", "mojang", "obfuscated"]).optional().describe("srg | mojang | obfuscated"),
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    projectPath: optionalNonEmptyString.describe("Optional workspace root path for Forge/NeoForge runtime validation"),
+    scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
+    preferProjectVersion: z.boolean().default(false)
+        .describe("When true, detect MC version from gradle.properties and override version")
+};
+const validateAccessTransformerSchema = z.object(validateAccessTransformerShape);
 const analyzeModJarShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
     includeClasses: z.boolean().default(false).describe("Include full class listing")
@@ -715,8 +741,11 @@ const analyzeModService = new AnalyzeModService({
 const validateProjectService = new ValidateProjectService({
     validateMixin: (input) => sourceService.validateMixin(input),
     validateAccessWidener: (input) => sourceService.validateAccessWidener(input),
+    validateAccessTransformer: (input) => sourceService.validateAccessTransformer(input),
     discoverMixins: discoverWorkspaceMixins,
-    discoverAccessWideners: discoverWorkspaceAccessWideners
+    discoverAccessWideners: discoverWorkspaceAccessWideners,
+    discoverAccessTransformers: discoverWorkspaceAccessTransformers,
+    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath)
 });
 const manageCacheService = new ManageCacheService({
     registry: createCacheRegistry({
@@ -1379,7 +1408,7 @@ function buildInvalidInputGuidance(tool, normalizedInput) {
     if (tool === "validate-project") {
         return {
             hints: [
-                "validate-project.subject must be an object with subject.kind=workspace|mixin|access-widener.",
+                "validate-project.subject must be an object with subject.kind=workspace|mixin|access-widener|access-transformer.",
                 "task=\"project-summary\" uses {\"subject\":{\"kind\":\"workspace\",\"projectPath\":\"/workspace\"}}.",
                 "Legacy include names like projectSummary/detectedConfig/validationSummary are not accepted; use include:[\"workspace\"] only when you need discovery details."
             ],
@@ -1502,6 +1531,17 @@ async function runTool(tool, rawInput, schema, action) {
             ? heavyToolExecutionGate.run(tool, () => action(parsedInput))
             : action(parsedInput));
         const { result, warnings, meta: resultMeta } = splitWarnings(payload);
+        const isCompact = isCompactEnabled(tool, parsedInput);
+        let projectedResult = result;
+        if (isCompact) {
+            if (tool === "resolve-artifact") {
+                projectedResult = compactArtifactResponse(projectedResult);
+            }
+            if (COMPACT_MAPPING_TOOL_NAMES.has(tool)) {
+                projectedResult = compactMappingResponse(projectedResult);
+            }
+            projectedResult = compactResponse(projectedResult);
+        }
         const entryMeta = ENTRY_TOOL_NAMES.has(tool)
             ? buildEntryToolMeta({
                 detail: normalizedInput &&
@@ -1519,7 +1559,7 @@ async function runTool(tool, rawInput, schema, action) {
             })
             : undefined;
         return objectResult({
-            result,
+            result: projectedResult,
             meta: {
                 ...(entryMeta ?? {}),
                 ...resultMeta,
@@ -1584,7 +1624,7 @@ server.tool("inspect-minecraft", "High-level v3 entry tool for version discovery
 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("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("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("validate-project", "High-level v3 entry tool for project summary, direct mixin validation, and access widener validation.", validateProjectShape, { readOnlyHint: true }, async (args) => runTool("validate-project", args, validateProjectSchema, async (input) => validateProjectService.execute(input)));
+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("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("resolve-artifact", "Resolve source artifact from a target object ({ kind, value }) and return artifact metadata. For target.kind=jar, only <basename>-sources.jar is auto-adopted; other adjacent *-sources.jar files are informational.", resolveArtifactShape, { readOnlyHint: true }, async (args) => runTool("resolve-artifact", args, resolveArtifactSchema, async (input) => sourceService.resolveArtifact({
     target: input.target,
@@ -1785,7 +1825,19 @@ server.tool("validate-access-widener", "Validate Access Widener file entries aga
     content: input.content,
     version: input.version,
     mapping: input.mapping,
-    sourcePriority: input.sourcePriority
+    sourcePriority: input.sourcePriority,
+    projectPath: input.projectPath,
+    scope: input.scope,
+    preferProjectVersion: input.preferProjectVersion
+})));
+server.tool("validate-access-transformer", "Validate Access Transformer file entries against Minecraft bytecode signatures for a given version.", validateAccessTransformerShape, { readOnlyHint: true }, async (args) => runTool("validate-access-transformer", args, validateAccessTransformerSchema, async (input) => sourceService.validateAccessTransformer({
+    content: input.content,
+    version: input.version,
+    atNamespace: input.atNamespace,
+    sourcePriority: input.sourcePriority,
+    projectPath: input.projectPath,
+    scope: input.scope,
+    preferProjectVersion: input.preferProjectVersion
 })));
 server.tool("analyze-mod-jar", "Analyze a Minecraft mod JAR to extract loader type, metadata, entrypoints, mixins, and dependencies.", analyzeModJarShape, { readOnlyHint: true }, async (args) => runTool("analyze-mod-jar", args, analyzeModJarSchema, async (input) => {
     const result = await analyzeModJar(input.jarPath, {

package/dist/mapping-pipeline-service.d.ts

@@ -3,6 +3,7 @@ export interface MappingPipelineInput {
     requestedMapping: SourceMapping;
     target: SourceTargetInput;
     resolved: ResolvedSourceArtifact;
+    runtimeNamesUnobfuscated?: boolean;
 }
 export interface MappingPipelineResult {
     mappingApplied: SourceMapping;
@@ -13,6 +14,7 @@ export interface MappingPipelineResult {
  * Mapping pipeline for v0.3.
  * Current implementation enforces explicit guarantees:
  * - obfuscated: always pass-through
- * - mojang: requires source-backed artifact; decompile-only artifacts are rejected
+ * - mojang: requires source-backed artifacts on legacy obfuscated versions,
+ *   but unobfuscated runtime jars can pass through directly
  */
 export declare function applyMappingPipeline(input: MappingPipelineInput): MappingPipelineResult;

package/dist/mapping-pipeline-service.js

@@ -3,7 +3,8 @@ import { createError, ERROR_CODES } from "./errors.js";
  * Mapping pipeline for v0.3.
  * Current implementation enforces explicit guarantees:
  * - obfuscated: always pass-through
- * - mojang: requires source-backed artifact; decompile-only artifacts are rejected
+ * - mojang: requires source-backed artifacts on legacy obfuscated versions,
+ *   but unobfuscated runtime jars can pass through directly
  */
 export function applyMappingPipeline(input) {
     const transformChain = [];
@@ -22,6 +23,20 @@ export function applyMappingPipeline(input) {
             transformChain
         };
     }
+    if (input.requestedMapping === "mojang" && input.runtimeNamesUnobfuscated) {
+        transformChain.push("mapping:mojang-runtime-unobfuscated");
+        if (input.resolved.isDecompiled) {
+            qualityFlags.push("decompiled");
+        }
+        else {
+            qualityFlags.push("source-backed");
+        }
+        return {
+            mappingApplied: "mojang",
+            qualityFlags,
+            transformChain
+        };
+    }
     if (input.requestedMapping !== "mojang" &&
         input.requestedMapping !== "intermediary" &&
         input.requestedMapping !== "yarn") {

package/dist/mapping-service.d.ts

@@ -62,6 +62,7 @@ export type FindMappingInput = {
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    projectPath?: string;
     disambiguation?: {
         ownerHint?: string;
         descriptorHint?: string;
@@ -74,6 +75,7 @@ export type EnsureMappingAvailableInput = {
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    projectPath?: string;
 };
 export type EnsureMappingAvailableOutput = {
     transformChain: string[];
@@ -88,6 +90,7 @@ export type ResolveMethodMappingExactInput = {
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    projectPath?: string;
     maxCandidates?: number;
 };
 export type ResolveMethodMappingExactOutput = SymbolResolutionOutput;
@@ -153,6 +156,7 @@ export declare class MappingService {
     checkSymbolExists(input: SymbolExistenceInput): Promise<SymbolExistenceOutput>;
     private mapRecordBetweenMappings;
     private mapCandidatesAlongPath;
+    private projectMethodDescriptorToTarget;
     private provenanceForPath;
     /**
      * Probe the mapping graph health for a given version.

package/dist/mapping-service.js

@@ -3,8 +3,9 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import fastGlob from "fast-glob";
 import { createError, ERROR_CODES } from "./errors.js";
+import { buildVersionSourceSearchRoots, normalizeOptionalProjectPath } from "./gradle-paths.js";
 import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
-import { listJarEntries, readJarEntryAsUtf8 } from "./source-jar-reader.js";
+import { collectMatchedJarEntriesAsUtf8 } from "./source-jar-reader.js";
 import { VersionService, isUnobfuscatedVersion } from "./version-service.js";
 const SUPPORTED_MAPPINGS = new Set([
     "obfuscated",
@@ -19,6 +20,7 @@ const MATCH_RANK = {
 };
 const DESCRIPTOR_FALLBACK_CONFIDENCE = 0.85;
 const MAX_CANDIDATES = 200;
+const GLOB_SPECIAL_CHARS = /[\\!*+?()[\]{}@|]/g;
 function createDirectionIndex() {
     return {
         exact: new Map(),
@@ -811,13 +813,32 @@ function applyDisambiguationHints(candidates, disambiguation) {
     }
     const descriptorHint = normalizeDescriptorHint(disambiguation.descriptorHint);
     if (descriptorHint) {
-        const descriptorMatched = filtered.filter((candidate) => candidate.descriptor === descriptorHint);
+        const descriptorMatched = filtered.filter((candidate) => candidate.descriptor != null && candidate.descriptor === descriptorHint);
         if (descriptorMatched.length > 0) {
             filtered = descriptorMatched;
         }
     }
     return filtered;
 }
+function projectLookupCandidateDescriptor(candidate, sourceDescriptor, targetDescriptor) {
+    // Tiny mappings preserve method descriptors verbatim, so single-hop tiny paths often
+    // return the source descriptor even though the final symbol is already in the target
+    // namespace. Multi-hop paths that already produced a target-side descriptor are left
+    // unchanged by design.
+    if (candidate.kind !== "method" ||
+        !candidate.descriptor ||
+        !targetDescriptor ||
+        candidate.descriptor !== sourceDescriptor) {
+        return candidate;
+    }
+    return {
+        ...candidate,
+        descriptor: targetDescriptor
+    };
+}
+function effectiveLoomSearchProjectPath(projectPath) {
+    return normalizeOptionalProjectPath(projectPath) ?? normalizeOptionalProjectPath(process.cwd());
+}
 function collectTargetRecords(graph, targetMapping) {
     return [...(graph.recordsByTarget.get(targetMapping) ?? [])];
 }
@@ -953,7 +974,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -968,7 +989,15 @@ export class MappingService {
                 ]
             };
         }
-        const rawCandidates = this.mapCandidatesAlongPath(graph, path, queryRecord);
+        const descriptorProjection = queryRecord.kind === "method" && queryRecord.descriptor
+            ? this.projectMethodDescriptorToTarget(graph, path, queryRecord.descriptor)
+            : undefined;
+        const projectedDescriptor = descriptorProjection?.complete ? descriptorProjection.descriptor : undefined;
+        const rawCandidates = this
+            .mapCandidatesAlongPath(graph, path, queryRecord)
+            .map((candidate) => queryRecord.kind === "method" && queryRecord.descriptor
+            ? projectLookupCandidateDescriptor(candidate, queryRecord.descriptor, projectedDescriptor)
+            : candidate);
         const warnings = [];
         const disambiguatedCandidates = applyDisambiguationHints(rawCandidates, input.disambiguation);
         if (rawCandidates.length > disambiguatedCandidates.length) {
@@ -1037,7 +1066,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             throw createError({
@@ -1121,7 +1150,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath);
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -1137,12 +1166,16 @@ export class MappingService {
             };
         }
         const warnings = [];
+        const descriptorProjection = this.projectMethodDescriptorToTarget(graph, path, descriptor);
+        const projectedDescriptor = descriptorProjection.complete ? descriptorProjection.descriptor : undefined;
         const rawCandidates = this
             .mapCandidatesAlongPath(graph, path, queryRecord)
-            .filter((candidate) => candidate.kind === "method");
+            .filter((candidate) => candidate.kind === "method")
+            .map((candidate) => projectLookupCandidateDescriptor(candidate, descriptor, projectedDescriptor));
         const candidates = rawCandidates.map(toResolutionCandidate);
         const limitedCandidates = limitResolutionCandidates(candidates, input.maxCandidates);
-        const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor === descriptor);
+        const strictDescriptor = projectedDescriptor ?? descriptor;
+        const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor === strictDescriptor);
         if (strictCandidates.length === 1) {
             const resolved = toResolutionCandidate(strictCandidates[0]);
             return {
@@ -1172,8 +1205,10 @@ export class MappingService {
                 provenance: this.provenanceForPath(graph, path)
             };
         }
-        if (pathUsesSource(graph.pairs, path, "mojang-client-mappings")) {
-            warnings.push("Method descriptor could not be preserved through mojang-client-mappings and exact resolution is unavailable.");
+        if (descriptorProjection.hadClassReferences && !descriptorProjection.complete) {
+            warnings.push(pathUsesSource(graph.pairs, path, "mojang-client-mappings")
+                ? "Method descriptor could not be preserved through mojang-client-mappings and exact resolution is unavailable."
+                : "Method descriptor could not be fully remapped across the mapping path and exact resolution is unavailable.");
             return {
                 querySymbol,
                 mappingContext,
@@ -1624,6 +1659,33 @@ export class MappingService {
             descriptor: item.record.descriptor
         }));
     }
+    projectMethodDescriptorToTarget(graph, path, descriptor) {
+        let hadClassReferences = false;
+        let complete = true;
+        const classProjectionCache = new Map();
+        const projectedDescriptor = descriptor.replace(/L([^;]+);/g, (fullMatch, internalName) => {
+            hadClassReferences = true;
+            const cached = classProjectionCache.get(internalName);
+            if (cached) {
+                return `L${cached};`;
+            }
+            const projectedClassCandidates = this
+                .mapCandidatesAlongPath(graph, path, createClassSymbolRecord(internalName.replace(/\//g, ".")))
+                .filter((candidate) => candidate.kind === "class");
+            if (projectedClassCandidates.length !== 1) {
+                complete = false;
+                return fullMatch;
+            }
+            const projectedInternalName = projectedClassCandidates[0].symbol.replace(/\./g, "/");
+            classProjectionCache.set(internalName, projectedInternalName);
+            return `L${projectedInternalName};`;
+        });
+        return {
+            descriptor: projectedDescriptor,
+            hadClassReferences,
+            complete
+        };
+    }
     provenanceForPath(graph, path) {
         if (path.length <= 1) {
             return undefined;
@@ -1646,6 +1708,18 @@ export class MappingService {
     async checkMappingHealth(input) {
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
         const degradations = [];
+        if (isUnobfuscatedVersion(input.version)) {
+            const requestFulfillable = input.requestedMapping === "obfuscated" || input.requestedMapping === "mojang";
+            if (!requestFulfillable) {
+                degradations.push(`Version ${input.version} is unobfuscated; ${input.requestedMapping} mappings are not applicable.`);
+            }
+            return {
+                mojangMappingsAvailable: true,
+                tinyMappingsAvailable: false,
+                memberRemapAvailable: requestFulfillable,
+                degradations
+            };
+        }
         let graph;
         try {
             graph = await this.loadGraph(input.version, priority, "full");
@@ -1692,8 +1766,9 @@ export class MappingService {
             degradations
         };
     }
-    async loadGraph(version, priority, mode) {
-        const cacheKey = `${version}|${priority}|${mode}`;
+    async loadGraph(version, priority, mode, projectPath) {
+        const effectiveProjectPath = effectiveLoomSearchProjectPath(projectPath);
+        const cacheKey = `${version}|${priority}|${mode}|${effectiveProjectPath ?? ""}`;
         const cached = this.graphCache.get(cacheKey);
         if (cached) {
             this.graphCache.delete(cacheKey);
@@ -1704,7 +1779,7 @@ export class MappingService {
         if (existingLock) {
             return existingLock;
         }
-        const buildPromise = this.buildGraph(version, priority, mode);
+        const buildPromise = this.buildGraph(version, priority, mode, effectiveProjectPath);
         this.buildLocks.set(cacheKey, buildPromise);
         try {
             const built = await buildPromise;
@@ -1716,7 +1791,7 @@ export class MappingService {
             this.buildLocks.delete(cacheKey);
         }
     }
-    async buildGraph(version, priority, mode) {
+    async buildGraph(version, priority, mode, projectPath) {
         if (isUnobfuscatedVersion(version)) {
             return {
                 version,
@@ -1749,7 +1824,7 @@ export class MappingService {
             const deferredTinyWarnings = [];
             for (const source of mappingSourceOrder(priority)) {
                 const tinyLoad = source === "loom-cache"
-                    ? await this.loadTinyPairsFromLoom(version)
+                    ? await this.loadTinyPairsFromLoom(version, projectPath)
                     : await this.loadTinyPairsFromMaven(version);
                 if (tinyLoad.pairs.size === 0) {
                     deferredTinyWarnings.push(...tinyLoad.warnings);
@@ -1847,46 +1922,67 @@ export class MappingService {
             };
         }
     }
-    async loadTinyPairsFromLoom(version) {
-        const patterns = [".gradle/loom-cache/**/*.tiny", ".gradle/loom-cache/**/*.tinyv2"];
-        const candidates = fastGlob.sync(patterns, {
-            cwd: process.cwd(),
-            absolute: true,
-            onlyFiles: true
-        });
-        const byVersion = candidates
-            .filter((p) => p.replaceAll("\\", "/").includes(`/${version}/`))
-            .sort((left, right) => left.localeCompare(right));
-        if (byVersion.length === 0) {
-            return {
-                pairs: new Map(),
-                warnings: [`No Loom tiny mapping files matched version "${version}".`],
-                mappingArtifact: "loom-cache:none"
-            };
-        }
+    async loadTinyPairsFromLoom(version, projectPath) {
+        const searchRoots = buildVersionSourceSearchRoots(effectiveLoomSearchProjectPath(projectPath));
         const merged = new Map();
-        for (const path of byVersion) {
+        const discoveredPaths = new Set();
+        for (const root of searchRoots) {
+            let discovered = [];
+            const versionRoot = join(root, version);
             try {
-                const content = await readFile(path, "utf8");
-                const parsed = parseTinyMappings(content);
-                for (const [key, index] of parsed.entries()) {
-                    const existing = merged.get(key);
-                    if (!existing) {
-                        merged.set(key, index);
-                    }
-                    else {
-                        mergeDirectionIndexes(existing, index);
-                    }
-                }
+                discovered = existsSync(versionRoot)
+                    ? await fastGlob.glob(["**/*.tiny", "**/*.tinyv2"], {
+                        cwd: versionRoot,
+                        absolute: true,
+                        onlyFiles: true
+                    })
+                    : await fastGlob.glob([`${version.replace(GLOB_SPECIAL_CHARS, "\\$&")}/**/*.tiny`, `${version.replace(GLOB_SPECIAL_CHARS, "\\$&")}/**/*.tinyv2`], {
+                        cwd: root,
+                        absolute: true,
+                        onlyFiles: true
+                    });
             }
             catch {
-                // best effort: skip unreadable or invalid files
+                continue;
             }
+            const byVersion = discovered
+                .filter((path) => path.replaceAll("\\", "/").includes(`/${version}/`))
+                .sort((left, right) => left.localeCompare(right));
+            if (byVersion.length === 0) {
+                continue;
+            }
+            for (const path of byVersion) {
+                discoveredPaths.add(path);
+                try {
+                    const content = await readFile(path, "utf8");
+                    const parsed = parseTinyMappings(content);
+                    for (const [key, index] of parsed.entries()) {
+                        const existing = merged.get(key);
+                        if (!existing) {
+                            merged.set(key, index);
+                        }
+                        else {
+                            mergeDirectionIndexes(existing, index);
+                        }
+                    }
+                }
+                catch {
+                    // best effort: skip unreadable or invalid files
+                }
+            }
+        }
+        const orderedPaths = [...discoveredPaths].sort((left, right) => left.localeCompare(right));
+        if (orderedPaths.length > 0) {
+            return {
+                pairs: merged,
+                warnings: [],
+                mappingArtifact: orderedPaths[0]
+            };
         }
         return {
-            pairs: merged,
-            warnings: [],
-            mappingArtifact: byVersion[0]
+            pairs: new Map(),
+            warnings: [`No Loom tiny mapping files matched version "${version}".`],
+            mappingArtifact: "loom-cache:none"
         };
     }
     async loadTinyPairsFromMaven(version) {
@@ -1942,15 +2038,11 @@ export class MappingService {
         };
     }
     async parseTinyFromJar(jarPath) {
-        const entries = await listJarEntries(jarPath);
-        const tinyEntries = entries
-            .filter((entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"))
-            .sort((left, right) => left.localeCompare(right));
+        const tinyEntries = (await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry.toLowerCase().endsWith(".tiny") || entry.toLowerCase().endsWith(".tinyv2"), { continueOnError: true })).sort((left, right) => left.filePath.localeCompare(right.filePath));
         const merged = new Map();
         for (const entry of tinyEntries) {
             try {
-                const text = await readJarEntryAsUtf8(jarPath, entry);
-                const parsed = parseTinyMappings(text);
+                const parsed = parseTinyMappings(entry.content);
                 for (const [key, index] of parsed.entries()) {
                     const existing = merged.get(key);
                     if (!existing) {
@@ -2008,8 +2100,12 @@ export class MappingService {
             return;
         }
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, sourcePriority);
-        this.graphCache.delete(`${normalizedVersion}|${priority}|full`);
-        this.graphCache.delete(`${normalizedVersion}|${priority}|obfuscated-mojang-only`);
+        const prefix = `${normalizedVersion}|${priority}|`;
+        for (const key of this.graphCache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.graphCache.delete(key);
+            }
+        }
     }
 }
 // ---------------------------------------------------------------------------
@@ -2039,14 +2135,13 @@ async function fetchYarnCoordinatesStandalone(version, fetchFn = globalThis.fetc
     }
 }
 async function extractTinyFromJar(jarPath, outputPath) {
-    const entries = await listJarEntries(jarPath);
-    const tinyEntry = entries.find((entry) => entry === "mappings/mappings.tiny" || entry.toLowerCase().endsWith(".tiny"));
+    const matchedEntries = await collectMatchedJarEntriesAsUtf8(jarPath, (entry) => entry === "mappings/mappings.tiny" || entry.toLowerCase().endsWith(".tiny"), { maxEntries: 1 });
+    const tinyEntry = matchedEntries[0];
     if (!tinyEntry) {
         return false;
     }
-    const content = await readJarEntryAsUtf8(jarPath, tinyEntry);
     await mkdir(dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, content, "utf8");
+    await writeFile(outputPath, tinyEntry.content, "utf8");
     return true;
 }
 /**