@adhisang/minecraft-modding-mcp 3.1.1 → 4.0.0

package/dist/gradle-paths.js

@@ -0,0 +1,57 @@
+import { homedir } from "node:os";
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { normalizePathForHost } from "./path-converter.js";
+export function normalizeOptionalProjectPath(projectPath) {
+    if (!projectPath) {
+        return undefined;
+    }
+    const trimmed = projectPath.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const normalized = normalizePathForHost(trimmed, undefined, "projectPath");
+    return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
+}
+export function resolveGradleUserHomePath() {
+    const configured = process.env.GRADLE_USER_HOME?.trim();
+    if (!configured) {
+        return resolvePath(homedir(), ".gradle");
+    }
+    const normalized = normalizePathForHost(configured, undefined, "GRADLE_USER_HOME");
+    return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
+}
+export function buildVersionSourceSearchRoots(projectPath) {
+    const roots = new Set();
+    if (projectPath) {
+        roots.add(resolvePath(projectPath, ".gradle", "loom-cache"));
+        roots.add(resolvePath(projectPath, ".gradle-user", "caches", "fabric-loom"));
+        roots.add(resolvePath(projectPath, ".gradle", "caches", "fabric-loom"));
+        const projectParent = dirname(projectPath);
+        roots.add(resolvePath(projectParent, ".gradle-user-home", "loom-cache"));
+        roots.add(resolvePath(projectParent, ".gradle-user-home", "caches", "fabric-loom"));
+    }
+    const homeGradle = resolveGradleUserHomePath();
+    roots.add(resolvePath(homeGradle, "loom-cache"));
+    roots.add(resolvePath(homeGradle, "caches", "fabric-loom"));
+    return [...roots];
+}
+export function buildLoaderRuntimeSearchRoots(projectPath) {
+    const roots = new Set();
+    if (projectPath) {
+        roots.add(resolvePath(projectPath, "build"));
+        roots.add(resolvePath(projectPath, ".gradle"));
+        roots.add(resolvePath(projectPath, ".gradle", "forge-userdev"));
+        roots.add(resolvePath(projectPath, ".gradle", "neogradle"));
+        roots.add(resolvePath(projectPath, ".gradle", "caches", "forge_gradle"));
+        roots.add(resolvePath(projectPath, ".gradle", "caches", "neogradle"));
+        roots.add(resolvePath(projectPath, ".gradle", "caches", "neoformruntime"));
+        roots.add(resolvePath(projectPath, ".gradle", "caches", "moddev"));
+    }
+    const homeGradle = resolveGradleUserHomePath();
+    roots.add(resolvePath(homeGradle, "caches", "forge_gradle"));
+    roots.add(resolvePath(homeGradle, "caches", "neogradle"));
+    roots.add(resolvePath(homeGradle, "caches", "neoformruntime"));
+    roots.add(resolvePath(homeGradle, "caches", "moddev"));
+    return [...roots];
+}
+//# sourceMappingURL=gradle-paths.js.map

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, COMPACT_SOURCE_TOOL_NAMES, COMPACT_MEMBERS_TOOL_NAMES, COMPACT_LIGHT_TOOL_NAMES, TOOL_PRESERVE_PAYLOAD_KEYS, compactResponse, compactArtifactResponse, compactMappingResponse, compactSourceResponse, compactMembersResponse, compactLightResponse } 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";
@@ -59,6 +60,19 @@ const heavyToolExecutionGate = new ToolExecutionGate({ maxConcurrent: 1, maxQueu
 const nonEmptyString = z.string().trim().min(1);
 const optionalNonEmptyString = z.string().trim().min(1).optional();
 const optionalPositiveInt = z.number().int().positive().optional();
+// Optional descriptor: "" and whitespace-only strings are normalized to undefined so that
+// tools with signatureMode="name-only" can accept "caller omitted descriptor" inputs whether
+// the caller passed an empty string or omitted the field entirely. Malformed descriptors are
+// still rejected downstream by normalizeMethodDescriptor in mapping-service.
+const optionalDescriptorString = z
+    .string()
+    .optional()
+    .transform((value) => {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+});
 const sourceMappingSchema = z.enum(SOURCE_MAPPINGS);
 const mappingSourcePrioritySchema = z.enum(SOURCE_PRIORITIES);
 const targetKindSchema = z.enum(TARGET_KINDS);
@@ -89,7 +103,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 +143,10 @@ 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(true).describe("Return minimal fields (artifactId, origin, isDecompiled, version, requestedMapping, mappingApplied, qualityFlags). "
+        + "Omit provenance, artifactContents, sampleEntries, adjacentSourceCandidates, binaryJarPath, coordinate, repoUrl, resolvedSourceJarPath. "
+        + "Enabled by default; set to false for full output.")
 };
 const resolveArtifactSchema = z.object(resolveArtifactShape);
 const getClassSourceShape = {
@@ -147,7 +164,8 @@ const getClassSourceShape = {
     endLine: optionalPositiveInt,
     maxLines: optionalPositiveInt,
     maxChars: optionalPositiveInt.describe("Hard character limit on sourceText; truncates if exceeded"),
-    outputFile: optionalNonEmptyString.describe("Write source to this file path and return metadata-only response")
+    outputFile: optionalNonEmptyString.describe("Write source to this file path and return metadata-only response"),
+    compact: z.boolean().default(false).describe("When true, strip debug metadata (provenance, artifactContents, qualityFlags) and empty fields from the response. Default false.")
 };
 const getClassSourceSchema = z
     .object(getClassSourceShape)
@@ -176,7 +194,8 @@ const getClassMembersShape = {
     projectPath: optionalNonEmptyString,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
-    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, strip debug metadata (provenance, artifactContents, qualityFlags, context) and empty fields from the response. Default false.")
 };
 const getClassMembersSchema = z.object(getClassMembersShape);
 const searchClassSourceShape = {
@@ -189,7 +208,10 @@ const searchClassSourceShape = {
     symbolKind: searchSymbolKindSchema.optional().describe("class | interface | enum | record | method | field"),
     queryMode: z.enum(["auto", "token", "literal"]).default("auto").describe("auto: indexed search, including separator queries like foo.bar; token: indexed-only; literal: explicit substring scan only"),
     limit: optionalPositiveInt.default(20),
-    cursor: optionalNonEmptyString
+    cursor: optionalNonEmptyString,
+    queryNamespace: sourceMappingSchema.optional().describe("Namespace of the query. When set and intent='symbol' with a fully-qualified class name, the query is translated through find-mapping before searching the artifact namespace. Ignored for text/path intents (warning surfaced)."),
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first. Used only when queryNamespace triggers translation."),
+    compact: z.boolean().default(false).describe("When true, strip the artifactContents summary and empty fields from the response. Default false.")
 };
 const searchClassSourceSchema = z.object(searchClassSourceShape).superRefine((value, ctx) => {
     if (value.symbolKind && value.intent && value.intent !== "symbol") {
@@ -210,12 +232,13 @@ const listArtifactFilesShape = {
     artifactId: nonEmptyString,
     prefix: optionalNonEmptyString,
     limit: optionalPositiveInt,
-    cursor: optionalNonEmptyString
+    cursor: optionalNonEmptyString,
+    compact: z.boolean().default(false).describe("When true, strip the artifactContents summary and empty fields from the response. Default false.")
 };
 const listArtifactFilesSchema = z.object(listArtifactFilesShape);
 const traceSymbolLifecycleShape = {
     symbol: nonEmptyString.describe("fully.qualified.Class.method"),
-    descriptor: optionalNonEmptyString.describe('optional JVM descriptor, e.g. "(I)V"'),
+    descriptor: optionalDescriptorString.describe('optional JVM descriptor, e.g. "(I)V". Empty strings are treated as omitted.'),
     fromVersion: optionalNonEmptyString,
     toVersion: optionalNonEmptyString,
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
@@ -239,10 +262,12 @@ const findMappingShape = {
     kind: workspaceSymbolKindSchema.describe("class | field | method"),
     name: nonEmptyString,
     owner: optionalNonEmptyString,
-    descriptor: optionalNonEmptyString,
+    descriptor: optionalDescriptorString.describe("JVM descriptor. Optional when signatureMode='name-only' (default). Empty strings are treated as omitted."),
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    signatureMode: z.enum(["exact", "name-only"]).default("name-only")
+        .describe("exact: descriptor required for kind=method; name-only (default): match by owner+name only"),
     disambiguation: z
         .object({
         ownerHint: optionalNonEmptyString,
@@ -250,7 +275,10 @@ const findMappingShape = {
     })
         .partial()
         .optional(),
-    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
+    maxCandidates: optionalPositiveInt.default(5).describe("Limit returned candidates (default 5, max 200). Raise when you need the full candidate list."),
+    compact: z.boolean().default(true).describe("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. "
+        + "Enabled by default; set to false for full output.")
 };
 const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -301,10 +329,10 @@ const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) =>
         }
         return;
     }
-    if (!value.descriptor) {
+    if (!value.descriptor && value.signatureMode !== "name-only") {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "descriptor is required when kind=method.",
+            message: "descriptor is required when kind=method (use signatureMode='name-only' to match by name only).",
             path: ["descriptor"]
         });
     }
@@ -317,7 +345,10 @@ 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(5).describe("Limit returned candidates (default 5, max 200). Raise when you need the full candidate list."),
+    compact: z.boolean().default(true).describe("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. "
+        + "Enabled by default; set to false for full output.")
 };
 const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
@@ -365,10 +396,13 @@ const resolveWorkspaceSymbolShape = {
     kind: workspaceSymbolKindSchema.describe("class | field | method"),
     name: nonEmptyString,
     owner: optionalNonEmptyString,
-    descriptor: optionalNonEmptyString,
+    descriptor: optionalDescriptorString.describe("JVM descriptor. Empty strings are treated as omitted."),
     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(5).describe("Limit returned candidates for field/method lookups (default 5, max 200). Raise when you need the full candidate list."),
+    compact: z.boolean().default(true).describe("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. "
+        + "Enabled by default; set to false for full output.")
 };
 const resolveWorkspaceSymbolSchema = z
     .object(resolveWorkspaceSymbolShape)
@@ -434,13 +468,16 @@ const checkSymbolExistsShape = {
     kind: workspaceSymbolKindSchema.describe("class | field | method"),
     owner: optionalNonEmptyString,
     name: nonEmptyString,
-    descriptor: optionalNonEmptyString.describe("required for kind=method unless signatureMode=name-only"),
+    descriptor: optionalDescriptorString.describe("required for kind=method unless signatureMode=name-only. Empty strings are treated as omitted."),
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     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(5).describe("Limit returned candidates (default 5, max 200). Raise when you need the full candidate list."),
+    compact: z.boolean().default(true).describe("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. "
+        + "Enabled by default; set to false for full output.")
 };
 const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -581,9 +618,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 +767,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({
@@ -857,6 +912,16 @@ function statusForErrorCode(code) {
     }
     return 500;
 }
+function extractFailedStageFromDetails(details) {
+    if (typeof details !== "object" || details == null) {
+        return undefined;
+    }
+    const maybeStage = details.failedStage;
+    if (typeof maybeStage === "string" && maybeStage.trim().length > 0) {
+        return maybeStage;
+    }
+    return undefined;
+}
 function extractFieldErrorsFromDetails(details) {
     if (typeof details !== "object" || details == null) {
         return undefined;
@@ -1379,7 +1444,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."
             ],
@@ -1418,11 +1483,18 @@ function mapErrorToProblem(caughtError, requestId, context) {
             instance: requestId,
             fieldErrors: toFieldErrorsFromZod(caughtError),
             hints: guidance?.hints ?? ["Check fieldErrors and submit a valid tool argument payload."],
-            ...(guidance?.suggestedCall ? { suggestedCall: guidance.suggestedCall } : {})
+            ...(guidance?.suggestedCall ? { suggestedCall: guidance.suggestedCall } : {}),
+            ...(context?.tool === "validate-mixin" ? { failedStage: "input-validation" } : {})
         };
     }
     if (isAppError(caughtError)) {
         const suggestedCall = toSuggestedCall(caughtError.details);
+        let failedStage = extractFailedStageFromDetails(caughtError.details);
+        if (!failedStage
+            && context?.tool === "validate-mixin"
+            && caughtError.code === ERROR_CODES.INVALID_INPUT) {
+            failedStage = "input-validation";
+        }
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -1432,7 +1504,8 @@ function mapErrorToProblem(caughtError, requestId, context) {
             instance: requestId,
             fieldErrors: extractFieldErrorsFromDetails(caughtError.details),
             hints: toHints(caughtError.details),
-            ...(suggestedCall ? { suggestedCall } : {})
+            ...(suggestedCall ? { suggestedCall } : {}),
+            ...(failedStage ? { failedStage } : {})
         };
     }
     return {
@@ -1502,6 +1575,26 @@ 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);
+            }
+            if (COMPACT_SOURCE_TOOL_NAMES.has(tool)) {
+                projectedResult = compactSourceResponse(projectedResult);
+            }
+            if (COMPACT_MEMBERS_TOOL_NAMES.has(tool)) {
+                projectedResult = compactMembersResponse(projectedResult);
+            }
+            if (COMPACT_LIGHT_TOOL_NAMES.has(tool)) {
+                projectedResult = compactLightResponse(projectedResult);
+            }
+            projectedResult = compactResponse(projectedResult, TOOL_PRESERVE_PAYLOAD_KEYS[tool]);
+        }
         const entryMeta = ENTRY_TOOL_NAMES.has(tool)
             ? buildEntryToolMeta({
                 detail: normalizedInput &&
@@ -1518,14 +1611,16 @@ async function runTool(tool, rawInput, schema, action) {
                     : undefined
             })
             : undefined;
+        const durationMs = Date.now() - startedAt;
+        sourceService.recordToolCall(tool, durationMs);
         return objectResult({
-            result,
+            result: projectedResult,
             meta: {
                 ...(entryMeta ?? {}),
                 ...resultMeta,
                 requestId,
                 tool,
-                durationMs: Date.now() - startedAt,
+                durationMs,
                 warnings
             }
         });
@@ -1565,12 +1660,14 @@ async function runTool(tool, rawInput, schema, action) {
                 reason: caughtError instanceof Error ? caughtError.message : String(caughtError)
             });
         }
+        const errorDurationMs = Date.now() - startedAt;
+        sourceService.recordToolCall(tool, errorDurationMs);
         return objectResult({
             error: problem,
             meta: {
                 requestId,
                 tool,
-                durationMs: Date.now() - startedAt,
+                durationMs: errorDurationMs,
                 warnings: []
             }
         }, { isError: true });
@@ -1584,7 +1681,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,
@@ -1594,7 +1691,8 @@ server.tool("resolve-artifact", "Resolve source artifact from a target object ({
     projectPath: input.projectPath,
     scope: input.scope,
     preferProjectVersion: input.preferProjectVersion,
-    strictVersion: input.strictVersion
+    strictVersion: input.strictVersion,
+    compact: input.compact
 })));
 const findClassShape = {
     className: nonEmptyString.describe("Simple name (e.g. Blocks) or fully-qualified name (e.g. net.minecraft.world.level.block.Blocks)"),
@@ -1664,7 +1762,9 @@ server.tool("search-class-source", "Search indexed class source files for one ar
         scope: scope,
         queryMode: input.queryMode,
         limit: input.limit,
-        cursor: input.cursor
+        cursor: input.cursor,
+        queryNamespace: input.queryNamespace,
+        sourcePriority: input.sourcePriority
     });
 }));
 server.tool("get-artifact-file", "Get full source file content by artifactId and file path.", getArtifactFileShape, { readOnlyHint: true }, async (args) => runTool("get-artifact-file", args, getArtifactFileSchema, async (input) => sourceService.getArtifactFile({
@@ -1672,7 +1772,12 @@ server.tool("get-artifact-file", "Get full source file content by artifactId and
     filePath: input.filePath,
     maxBytes: input.maxBytes
 })));
-server.tool("list-artifact-files", "List source file paths in an artifact with optional prefix filter and cursor-based pagination.", listArtifactFilesShape, { readOnlyHint: true }, async (args) => runTool("list-artifact-files", args, listArtifactFilesSchema, async (input) => sourceService.listArtifactFiles(input)));
+server.tool("list-artifact-files", "List source file paths in an artifact with optional prefix filter and cursor-based pagination.", listArtifactFilesShape, { readOnlyHint: true }, async (args) => runTool("list-artifact-files", args, listArtifactFilesSchema, async (input) => sourceService.listArtifactFiles({
+    artifactId: input.artifactId,
+    prefix: input.prefix,
+    limit: input.limit,
+    cursor: input.cursor
+})));
 server.tool("trace-symbol-lifecycle", "Trace which Minecraft versions contain a specific class method and report first/last seen versions.", traceSymbolLifecycleShape, { readOnlyHint: true }, async (args) => runTool("trace-symbol-lifecycle", args, traceSymbolLifecycleSchema, async (input) => sourceService.traceSymbolLifecycle({
     symbol: input.symbol,
     descriptor: input.descriptor,
@@ -1701,6 +1806,7 @@ server.tool("find-mapping", "Find symbol mapping candidates between namespaces u
     sourceMapping: input.sourceMapping,
     targetMapping: input.targetMapping,
     sourcePriority: input.sourcePriority,
+    signatureMode: input.signatureMode,
     disambiguation: input.disambiguation,
     maxCandidates: input.maxCandidates
 })));
@@ -1785,7 +1891,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/lru-list.d.ts

@@ -0,0 +1,31 @@
+/**
+ * O(1) doubly-linked list + Map LRU.
+ * head = oldest, tail = newest.
+ */
+export declare class LruList<T> {
+    private map;
+    private head;
+    private tail;
+    get size(): number;
+    /** O(1) — move to tail (most recent), return value reference. */
+    touch(key: string): T | undefined;
+    /** O(1) — insert or update + move to tail. Returns previous value if existed. */
+    upsert(key: string, value: T): T | undefined;
+    /** O(1) — remove by key, return removed value. */
+    remove(key: string): T | undefined;
+    /** O(1) — peek at oldest (head) without removing. */
+    peekOldest(): {
+        key: string;
+        value: T;
+    } | undefined;
+    /** O(1) — clear all entries. */
+    clear(): void;
+    /** O(n) — iterate oldest → newest. */
+    toArray(): Array<{
+        key: string;
+        value: T;
+    }>;
+    private unlink;
+    private appendToTail;
+    private moveToTail;
+}

package/dist/lru-list.js

@@ -0,0 +1,102 @@
+/**
+ * O(1) doubly-linked list + Map LRU.
+ * head = oldest, tail = newest.
+ */
+export class LruList {
+    map = new Map();
+    head = null;
+    tail = null;
+    get size() {
+        return this.map.size;
+    }
+    /** O(1) — move to tail (most recent), return value reference. */
+    touch(key) {
+        const node = this.map.get(key);
+        if (!node) {
+            return undefined;
+        }
+        this.moveToTail(node);
+        return node.value;
+    }
+    /** O(1) — insert or update + move to tail. Returns previous value if existed. */
+    upsert(key, value) {
+        const existing = this.map.get(key);
+        if (existing) {
+            const prev = existing.value;
+            existing.value = value;
+            this.moveToTail(existing);
+            return prev;
+        }
+        const node = { key, value, prev: null, next: null };
+        this.map.set(key, node);
+        this.appendToTail(node);
+        return undefined;
+    }
+    /** O(1) — remove by key, return removed value. */
+    remove(key) {
+        const node = this.map.get(key);
+        if (!node) {
+            return undefined;
+        }
+        this.unlink(node);
+        this.map.delete(key);
+        return node.value;
+    }
+    /** O(1) — peek at oldest (head) without removing. */
+    peekOldest() {
+        if (!this.head) {
+            return undefined;
+        }
+        return { key: this.head.key, value: this.head.value };
+    }
+    /** O(1) — clear all entries. */
+    clear() {
+        this.map.clear();
+        this.head = null;
+        this.tail = null;
+    }
+    /** O(n) — iterate oldest → newest. */
+    toArray() {
+        const result = [];
+        let current = this.head;
+        while (current) {
+            result.push({ key: current.key, value: current.value });
+            current = current.next;
+        }
+        return result;
+    }
+    unlink(node) {
+        if (node.prev) {
+            node.prev.next = node.next;
+        }
+        else {
+            this.head = node.next;
+        }
+        if (node.next) {
+            node.next.prev = node.prev;
+        }
+        else {
+            this.tail = node.prev;
+        }
+        node.prev = null;
+        node.next = null;
+    }
+    appendToTail(node) {
+        if (!this.tail) {
+            this.head = node;
+            this.tail = node;
+            return;
+        }
+        node.prev = this.tail;
+        this.tail.next = node;
+        this.tail = node;
+    }
+    moveToTail(node) {
+        if (node === this.tail) {
+            return;
+        }
+        this.unlink(node);
+        this.appendToTail(node);
+    }
+}
+//# sourceMappingURL=lru-list.js.map

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

@@ -3,6 +3,15 @@ export interface MappingPipelineInput {
     requestedMapping: SourceMapping;
     target: SourceTargetInput;
     resolved: ResolvedSourceArtifact;
+    runtimeNamesUnobfuscated?: boolean;
+    /**
+     * When true and the mojang request lands on a binary-only artifact, the pipeline
+     * authorizes a downstream tiny-remap (obfuscated -> mojang) followed by decompile
+     * instead of throwing MAPPING_NOT_APPLIED. The caller is responsible for
+     * pre-resolving tiny-remapper jar, mojang tiny mappings, and verifying mapping
+     * health before setting this flag.
+     */
+    allowBinaryRemap?: boolean;
 }
 export interface MappingPipelineResult {
     mappingApplied: SourceMapping;
@@ -13,6 +22,8 @@ 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,
+ *   or binary-only artifacts may be remapped + decompiled when allowBinaryRemap=true
  */
 export declare function applyMappingPipeline(input: MappingPipelineInput): MappingPipelineResult;