@adhisang/minecraft-modding-mcp 3.2.0 → 4.0.0

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

@@ -606,6 +606,7 @@ export class InspectMinecraftService {
                     artifact: resolved.artifact
                         ? {
                             artifactId: resolved.artifact.artifactId,
+                            artifactAlias: resolved.artifact.artifactAlias,
                             origin: resolved.artifact.origin,
                             mappingApplied: resolved.artifact.mappingApplied,
                             version: resolved.artifact.version,
@@ -961,9 +962,14 @@ export class InspectMinecraftService {
                         }
                     },
                     members: include.includes("members") || detail !== "summary"
-                        ? members.members
+                        ? {
+                            ...members.members,
+                            ...(members.decompiledFallback ? { decompiledFallback: members.decompiledFallback } : {}),
+                            ...(members.decompiledMemberCounts ? { decompiledMemberCounts: members.decompiledMemberCounts } : {})
+                        }
                         : {
-                            counts: members.counts
+                            counts: members.counts,
+                            ...(members.decompiledMemberCounts ? { decompiledMemberCounts: members.decompiledMemberCounts } : {})
                         }
                 },
                 alwaysBlocks: ["subject"]

package/dist/entry-tools/manage-cache-service.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { type CacheRegistry } from "../cache-registry.js";
 export declare const manageCacheShape: {
     action: z.ZodEnum<["summary", "list", "inspect", "delete", "prune", "rebuild", "verify"]>;
-    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap"]>, "many">>;
+    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap"]>, "many">>;
     selector: z.ZodOptional<z.ZodObject<{
         artifactId: z.ZodOptional<z.ZodString>;
         version: z.ZodOptional<z.ZodString>;
@@ -42,7 +42,7 @@ export declare const manageCacheShape: {
 };
 export declare const manageCacheSchema: z.ZodObject<{
     action: z.ZodEnum<["summary", "list", "inspect", "delete", "prune", "rebuild", "verify"]>;
-    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap"]>, "many">>;
+    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap"]>, "many">>;
     selector: z.ZodOptional<z.ZodObject<{
         artifactId: z.ZodOptional<z.ZodString>;
         version: z.ZodOptional<z.ZodString>;
@@ -86,7 +86,7 @@ export declare const manageCacheSchema: z.ZodObject<{
     cursor?: string | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
-    cacheKinds?: ("artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap")[] | undefined;
+    cacheKinds?: ("artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap" | "binary-remap")[] | undefined;
     selector?: {
         mapping?: string | undefined;
         jarPath?: string | undefined;
@@ -105,7 +105,7 @@ export declare const manageCacheSchema: z.ZodObject<{
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
     executionMode?: "preview" | "apply" | undefined;
-    cacheKinds?: ("artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap")[] | undefined;
+    cacheKinds?: ("artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap" | "binary-remap")[] | undefined;
     selector?: {
         mapping?: string | undefined;
         jarPath?: string | undefined;

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

@@ -269,7 +269,32 @@ export class ValidateProjectService {
                 if (input.subject.kind !== "mixin") {
                     throw createError({
                         code: ERROR_CODES.INVALID_INPUT,
-                        message: "task=mixin requires subject.kind=mixin."
+                        message: "task=mixin requires subject.kind=mixin.",
+                        details: {
+                            task: input.task,
+                            subjectKind: input.subject.kind,
+                            failedStage: "input-validation",
+                            nextAction: "Set subject.kind to \"mixin\" for task=\"mixin\"."
+                        }
+                    });
+                }
+                if (!input.version) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "task=mixin requires version.",
+                        details: {
+                            task: "mixin",
+                            failedStage: "input-validation",
+                            nextAction: "Pass version explicitly (e.g. \"1.21.10\"). task=\"project-summary\" supports preferProjectVersion for auto-detection from gradle.properties, but direct task=\"mixin\" requires an explicit version.",
+                            suggestedCall: {
+                                tool: "validate-project",
+                                params: {
+                                    task: "mixin",
+                                    subject: input.subject,
+                                    version: "1.21.10"
+                                }
+                            }
+                        }
                     });
                 }
                 const output = await this.deps.validateMixin({
@@ -330,7 +355,32 @@ export class ValidateProjectService {
                 if (input.subject.kind !== "access-widener") {
                     throw createError({
                         code: ERROR_CODES.INVALID_INPUT,
-                        message: "task=access-widener requires subject.kind=access-widener."
+                        message: "task=access-widener requires subject.kind=access-widener.",
+                        details: {
+                            task: input.task,
+                            subjectKind: input.subject.kind,
+                            failedStage: "input-validation",
+                            nextAction: "Set subject.kind to \"access-widener\" for task=\"access-widener\"."
+                        }
+                    });
+                }
+                if (!input.version) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "task=access-widener requires version.",
+                        details: {
+                            task: "access-widener",
+                            failedStage: "input-validation",
+                            nextAction: "Pass version explicitly (e.g. \"1.21.10\"). Access Widener validation resolves class names against a specific Minecraft version.",
+                            suggestedCall: {
+                                tool: "validate-project",
+                                params: {
+                                    task: "access-widener",
+                                    subject: input.subject,
+                                    version: "1.21.10"
+                                }
+                            }
+                        }
                     });
                 }
                 const content = input.subject.input.mode === "inline"
@@ -386,7 +436,32 @@ export class ValidateProjectService {
                 if (input.subject.kind !== "access-transformer") {
                     throw createError({
                         code: ERROR_CODES.INVALID_INPUT,
-                        message: "task=access-transformer requires subject.kind=access-transformer."
+                        message: "task=access-transformer requires subject.kind=access-transformer.",
+                        details: {
+                            task: input.task,
+                            subjectKind: input.subject.kind,
+                            failedStage: "input-validation",
+                            nextAction: "Set subject.kind to \"access-transformer\" for task=\"access-transformer\"."
+                        }
+                    });
+                }
+                if (!input.version) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "task=access-transformer requires version.",
+                        details: {
+                            task: "access-transformer",
+                            failedStage: "input-validation",
+                            nextAction: "Pass version explicitly (e.g. \"1.21.10\"). Access Transformer validation resolves class names against a specific Minecraft version.",
+                            suggestedCall: {
+                                tool: "validate-project",
+                                params: {
+                                    task: "access-transformer",
+                                    subject: input.subject,
+                                    version: "1.21.10"
+                                }
+                            }
+                        }
                     });
                 }
                 const content = input.subject.input.mode === "inline"
@@ -395,7 +470,12 @@ export class ValidateProjectService {
                 if (!this.deps.validateAccessTransformer) {
                     throw createError({
                         code: ERROR_CODES.CONTEXT_UNRESOLVED,
-                        message: "Access Transformer validation is not configured."
+                        message: "Access Transformer validation is not configured.",
+                        details: {
+                            task: "access-transformer",
+                            failedStage: "dependency-resolution",
+                            nextAction: "The current runtime was built without an Access Transformer validator. Rebuild the MCP server with validateAccessTransformer configured, or use task=\"access-widener\" if the workspace uses Fabric AccessWideners."
+                        }
                     });
                 }
                 const output = await this.deps.validateAccessTransformer({

package/dist/index.js

@@ -4,7 +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 { 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";
@@ -60,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);
@@ -131,8 +144,9 @@ const resolveArtifactShape = {
     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."),
-    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.")
+    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 = {
@@ -150,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)
@@ -179,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 = {
@@ -192,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") {
@@ -213,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)"),
@@ -242,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,
@@ -253,9 +275,10 @@ const findMappingShape = {
     })
         .partial()
         .optional(),
-    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.")
+    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") {
@@ -306,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"]
         });
     }
@@ -322,9 +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)"),
-    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.")
+    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)
@@ -372,12 +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)"),
-    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.")
+    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)
@@ -443,15 +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)"),
-    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.")
+    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") {
@@ -886,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;
@@ -1447,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",
@@ -1461,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 {
@@ -1540,7 +1584,16 @@ async function runTool(tool, rawInput, schema, action) {
             if (COMPACT_MAPPING_TOOL_NAMES.has(tool)) {
                 projectedResult = compactMappingResponse(projectedResult);
             }
-            projectedResult = compactResponse(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({
@@ -1558,6 +1611,8 @@ async function runTool(tool, rawInput, schema, action) {
                     : undefined
             })
             : undefined;
+        const durationMs = Date.now() - startedAt;
+        sourceService.recordToolCall(tool, durationMs);
         return objectResult({
             result: projectedResult,
             meta: {
@@ -1565,7 +1620,7 @@ async function runTool(tool, rawInput, schema, action) {
                 ...resultMeta,
                 requestId,
                 tool,
-                durationMs: Date.now() - startedAt,
+                durationMs,
                 warnings
             }
         });
@@ -1605,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 });
@@ -1634,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)"),
@@ -1704,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({
@@ -1712,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,
@@ -1741,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
 })));

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

@@ -4,6 +4,14 @@ export interface MappingPipelineInput {
     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;
@@ -15,6 +23,7 @@ export interface MappingPipelineResult {
  * Current implementation enforces explicit guarantees:
  * - obfuscated: always pass-through
  * - mojang: requires source-backed artifacts on legacy obfuscated versions,
- *   but unobfuscated runtime jars can pass through directly
+ *   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;