@adhisang/minecraft-modding-mcp 4.2.1 → 5.0.0

package/dist/index.js

@@ -5,7 +5,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 { DETAIL_ENABLED_TOOL_NAMES, DEFAULT_DETAIL_BY_TOOL, projectByDetail } from "./response-utils.js";
 import { loadConfig } from "./config.js";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { log } from "./logger.js";
@@ -15,6 +15,7 @@ import { remapModJar } from "./mod-remap-service.js";
 import { registerResources } from "./resources.js";
 import { SourceService } from "./source-service.js";
 import { ToolExecutionGate } from "./tool-execution-gate.js";
+import { classifyWarnings } from "./warning-details.js";
 import { WorkspaceMappingService } from "./workspace-mapping-service.js";
 import { InspectMinecraftService, inspectMinecraftSchema, inspectMinecraftShape } from "./entry-tools/inspect-minecraft-service.js";
 import { AnalyzeSymbolService, analyzeSymbolSchema, analyzeSymbolShape } from "./entry-tools/analyze-symbol-service.js";
@@ -55,6 +56,13 @@ const ENTRY_TOOL_NAMES = new Set([
     "validate-project",
     "manage-cache"
 ]);
+// Batch tools self-project per entry but report the applied detail at the top level.
+const BATCH_DETAIL_TOOL_NAMES = new Set([
+    "batch-class-source",
+    "batch-class-members",
+    "batch-symbol-exists",
+    "batch-mappings"
+]);
 const heavyToolExecutionGate = new ToolExecutionGate({ maxConcurrent: 1, maxQueue: 2 });
 function getServerVersionFromPackageJson() {
     try {
@@ -77,6 +85,13 @@ const server = new McpServer({
 // The SDK validates tool args before invoking handlers and returns generic InvalidParams text.
 // Bypass that layer so runTool() remains the single source of truth for validation and error envelopes.
 server.validateToolInput = async (_tool, args) => args;
+// Low-level/expert tools duplicate capability that the six entry tools expose
+// in a single resolve+fetch call. expertTool() registers them exactly like
+// server.tool() but appends a note steering agents to the entry tools first.
+// Entry tools, batch tools, and the NBT/runtime utilities (which have no entry
+// equivalent) keep their plain descriptions via server.tool().
+const EXPERT_TOOL_NOTE = " Expert/follow-up tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first; reach for this only for the narrow operation it names.";
+const expertTool = ((name, description, ...rest) => server.tool(name, description + EXPERT_TOOL_NOTE, ...rest));
 const config = loadConfig();
 const nbtLimits = {
     maxInputBytes: config.maxNbtInputBytes,
@@ -176,10 +191,32 @@ const verifyMixinTargetService = new VerifyMixinTargetService({
             artifactId: output.artifactId,
             mappingApplied: output.mappingApplied,
             binaryJarPath: output.binaryJarPath,
+            version: output.version,
             provenance: output.provenance,
             warnings: output.warnings
         };
     },
+    findMapping: async (input) => {
+        const output = await sourceService.findMapping({
+            version: input.version,
+            kind: input.kind,
+            name: input.name,
+            owner: input.owner,
+            descriptor: input.descriptor,
+            sourceMapping: input.sourceMapping,
+            targetMapping: input.targetMapping
+        });
+        return {
+            resolved: output.resolved,
+            resolvedSymbol: output.resolvedSymbol
+                ? {
+                    name: output.resolvedSymbol.name,
+                    owner: output.resolvedSymbol.owner,
+                    descriptor: output.resolvedSymbol.descriptor
+                }
+                : undefined
+        };
+    },
     getSignature: (input) => sourceService.explorerService.getSignature(input)
 });
 const batchClassSourceService = new BatchClassSourceService({
@@ -226,11 +263,10 @@ function buildRequestId() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
 function normalizeSourceLookupTarget(target) {
-    if (target.type === "artifact") {
+    if (target.kind === "artifact") {
         return { artifactId: target.artifactId };
     }
-    const { type: _type, ...rest } = target;
-    return { target: rest };
+    return { target: target };
 }
 function parseClassApiKinds(value) {
     if (value == null) {
@@ -270,6 +306,33 @@ function splitWarnings(data) {
         meta
     };
 }
+/**
+ * Read the detail/include response-shape controls from a parsed tool input.
+ * Folds the legacy includeProvenance/includeDescriptors flags into the include
+ * set as aliases so the migration off `compact` preserves Phase-4 behavior.
+ */
+function readResponseShapeInput(parsedInput) {
+    const include = new Set();
+    if (parsedInput === null || typeof parsedInput !== "object" || Array.isArray(parsedInput)) {
+        return { include };
+    }
+    const record = parsedInput;
+    if (Array.isArray(record.include)) {
+        for (const group of record.include) {
+            if (typeof group === "string")
+                include.add(group);
+        }
+    }
+    if (record.includeProvenance === true)
+        include.add("provenance");
+    if (record.includeDescriptors === true)
+        include.add("descriptors");
+    const detail = typeof record.detail === "string" &&
+        (record.detail === "summary" || record.detail === "standard" || record.detail === "full")
+        ? record.detail
+        : undefined;
+    return { detail, include };
+}
 async function runTool(tool, rawInput, schema, action) {
     const requestId = buildRequestId();
     const startedAt = Date.now();
@@ -289,6 +352,11 @@ async function runTool(tool, rawInput, schema, action) {
                         code: "invalid_enum_value"
                     })),
                     nextAction: `Replace "official" with "obfuscated" in mapping-related fields and retry.`,
+                    // Route construction through buildSuggestedCall to satisfy the D12
+                    // invariant (tests/suggested-call-invariant.test.ts): every emitted
+                    // suggestedCall must be built by the helper. The downstream
+                    // mapErrorToProblem gate re-validates on emission; that second pass is
+                    // the intentional, cheap cost of the two complementary safety gates.
                     ...(suggestedReplacementInput
                         ? buildSuggestedCall({
                             tool,
@@ -303,44 +371,32 @@ 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);
+        // Expert tools share the entry-tool detail/include response contract (the old
+        // per-tool `compact` boolean is gone). projectByDetail reproduces the previous
+        // compact defaults byte-identically: resolution tools default detail=summary
+        // (old compact:true), source/file tools default detail=standard (old compact:false).
+        // The legacy includeProvenance/includeDescriptors flags are folded into the
+        // include set as aliases so Phase-4 behavior is preserved.
+        const shapeInput = readResponseShapeInput(parsedInput);
+        const effectiveDetail = ENTRY_TOOL_NAMES.has(tool)
+            ? (shapeInput.detail ?? "summary")
+            : (shapeInput.detail ?? DEFAULT_DETAIL_BY_TOOL[tool] ?? "summary");
         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]);
+        if (DETAIL_ENABLED_TOOL_NAMES.has(tool)) {
+            projectedResult = projectByDetail(tool, projectedResult, effectiveDetail, shapeInput.include);
         }
-        const entryMeta = ENTRY_TOOL_NAMES.has(tool)
+        // Entry, expert, and batch tools all report the applied detail/include shape in meta.
+        const entryMeta = ENTRY_TOOL_NAMES.has(tool) ||
+            DETAIL_ENABLED_TOOL_NAMES.has(tool) ||
+            BATCH_DETAIL_TOOL_NAMES.has(tool)
             ? buildEntryToolMeta({
-                detail: normalizedInput &&
-                    typeof normalizedInput === "object" &&
-                    !Array.isArray(normalizedInput) &&
-                    typeof normalizedInput.detail === "string"
-                    ? normalizedInput.detail ?? "summary"
-                    : "summary",
-                include: normalizedInput &&
-                    typeof normalizedInput === "object" &&
-                    !Array.isArray(normalizedInput) &&
-                    Array.isArray(normalizedInput.include)
-                    ? normalizedInput.include
-                    : undefined
+                detail: effectiveDetail,
+                include: shapeInput.include.size > 0 ? [...shapeInput.include] : undefined
             })
             : undefined;
         const durationMs = Date.now() - startedAt;
         sourceService.recordToolCall(tool, durationMs);
+        const warningDetails = classifyWarnings(warnings);
         return objectResult({
             result: projectedResult,
             meta: {
@@ -349,7 +405,8 @@ async function runTool(tool, rawInput, schema, action) {
                 requestId,
                 tool,
                 durationMs,
-                warnings
+                warnings,
+                ...(warningDetails.length > 0 ? { warningDetails } : {})
             }
         });
     }
@@ -403,14 +460,14 @@ async function runTool(tool, rawInput, schema, action) {
         }, { isError: true });
     }
 }
-server.tool("list-versions", "List available Minecraft versions from Mojang manifest and locally cached version jars.", listVersionsShape, { readOnlyHint: true }, async (args) => runTool("list-versions", args, listVersionsSchema, async (input) => sourceService.listVersions({
+expertTool("list-versions", "List available Minecraft versions from Mojang manifest and locally cached version jars.", listVersionsShape, { readOnlyHint: true }, async (args) => runTool("list-versions", args, listVersionsSchema, async (input) => sourceService.listVersions({
     includeSnapshots: input.includeSnapshots,
     limit: input.limit
 })));
 registerToolSchema("list-versions", listVersionsSchema);
 server.tool("inspect-minecraft", "Top-level workflow tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings.", inspectMinecraftShape, { readOnlyHint: true }, async (args) => runTool("inspect-minecraft", args, inspectMinecraftSchema, async (input) => inspectMinecraftService.execute(input)));
 registerToolSchema("inspect-minecraft", inspectMinecraftSchema);
-server.tool("analyze-symbol", "Top-level workflow tool for symbol existence, mapping, lifecycle, workspace analysis, and API overview.", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
+server.tool("analyze-symbol", "Top-level workflow tool for symbol existence, mapping, lifecycle (with fromVersion/toVersion/maxVersions/includeTimeline range controls), workspace analysis, and API overview. subject.kind accepts 'symbol' to auto-detect class/field/method from the selector (inferred kind is returned as a warning).", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
 registerToolSchema("analyze-symbol", analyzeSymbolSchema);
 server.tool("compare-minecraft", "Top-level workflow tool for version comparisons, class diffs, registry diffs, and migration overviews.", compareMinecraftShape, { readOnlyHint: true }, async (args) => runTool("compare-minecraft", args, compareMinecraftSchema, async (input) => compareMinecraftService.execute(input)));
 registerToolSchema("compare-minecraft", compareMinecraftSchema);
@@ -428,6 +485,7 @@ if (!VERIFY_MIXIN_TARGET_OFF) {
         member: input.member,
         mixinMemberName: input.mixinMemberName,
         mapping: input.mapping,
+        autoRemap: input.autoRemap,
         sourcePriority: input.sourcePriority,
         projectPath: input.projectPath,
         gradleUserHome: input.gradleUserHome,
@@ -439,7 +497,7 @@ if (!VERIFY_MIXIN_TARGET_OFF) {
     registerToolSchema("verify-mixin-target", verifyMixinTargetSchema);
 }
 if (!BATCH_TOOLS_OFF) {
-    server.tool("batch-class-source", "Batch lookup: read source for many classes in one call, sharing a single resolved artifact. Returns per-entry { status, result?, error? } plus aggregate summary. Per-entry retry suggestions point at get-class-source.", batchClassSourceShape, { readOnlyHint: true }, async (args) => runTool("batch-class-source", args, batchClassSourceSchema, async (input) => batchClassSourceService.execute(input)));
+    server.tool("batch-class-source", "Batch lookup: read source for many classes in one call, sharing a single resolved artifact. Returns per-entry { status, result?, error? } plus aggregate summary. Per-entry retry suggestions point at get-class-source. Not read-only: per-entry outputFile writes source files to disk.", batchClassSourceShape, { readOnlyHint: false }, async (args) => runTool("batch-class-source", args, batchClassSourceSchema, async (input) => batchClassSourceService.execute(input)));
     registerToolSchema("batch-class-source", batchClassSourceSchema);
     server.tool("batch-class-members", "Batch lookup: list members for many classes in one call, sharing a single resolved artifact. Returns per-entry { status, result?, error? } plus aggregate summary. Per-entry retry suggestions point at get-class-members.", batchClassMembersShape, { readOnlyHint: true }, async (args) => runTool("batch-class-members", args, batchClassMembersSchema, async (input) => batchClassMembersService.execute(input)));
     registerToolSchema("batch-class-members", batchClassMembersSchema);
@@ -448,7 +506,7 @@ if (!BATCH_TOOLS_OFF) {
     server.tool("batch-mappings", "Batch mapping translation: resolve many symbols across mapping namespaces with one shared Minecraft version. Per-entry retry suggestions point at find-mapping.", batchMappingsShape, { readOnlyHint: true }, async (args) => runTool("batch-mappings", args, batchMappingsSchema, async (input) => batchMappingsService.execute(input)));
     registerToolSchema("batch-mappings", batchMappingsSchema);
 }
-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({
+expertTool("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,
     mapping: input.mapping,
     sourcePriority: input.sourcePriority,
@@ -458,7 +516,8 @@ server.tool("resolve-artifact", "Resolve source artifact from a target object ({
     scope: input.scope,
     preferProjectVersion: input.preferProjectVersion,
     strictVersion: input.strictVersion,
-    compact: input.compact
+    includeSampleEntries: input.detail === "full" ||
+        (Array.isArray(input.include) && input.include.includes("samples"))
 })));
 registerToolSchema("resolve-artifact", resolveArtifactSchema);
 const findClassShape = {
@@ -467,13 +526,13 @@ const findClassShape = {
     limit: optionalPositiveInt.describe("default 20, max 200")
 };
 const findClassSchema = z.object(findClassShape);
-server.tool("find-class", "Resolve a simple or qualified class name to fully-qualified class names within an artifact. Use this before get-class-source when you only have a simple name.", findClassShape, { readOnlyHint: true }, async (args) => runTool("find-class", args, findClassSchema, async (input) => sourceService.findClass({
+expertTool("find-class", "Resolve a simple or qualified class name to fully-qualified class names within an artifact. Use this before get-class-source when you only have a simple name.", findClassShape, { readOnlyHint: true }, async (args) => runTool("find-class", args, findClassSchema, async (input) => sourceService.findClass({
     className: input.className,
     artifactId: input.artifactId,
     limit: input.limit
 })));
 registerToolSchema("find-class", findClassSchema);
-server.tool("get-class-source", "Get Java source for a class by target ({ type: 'artifact', artifactId } or { type: 'resolve', kind, value }). Default mode=metadata returns symbol outline only; use mode=snippet for bounded excerpts or mode=full for entire source.", getClassSourceShape, { readOnlyHint: true }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => {
+expertTool("get-class-source", "Get Java source for a class by target ({ kind: 'artifact', artifactId } or { kind: 'version'|'jar'|'coordinate'|'workspace'|'dependency', ... } — same shape as resolve-artifact). To read source text, pass mode=snippet (bounded excerpt) or mode=full (entire source); the default mode=metadata returns a symbol outline only, not the body. Not read-only: outputFile writes the source to disk.", getClassSourceShape, { readOnlyHint: false }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => {
     const normalizedTarget = normalizeSourceLookupTarget(input.target);
     return sourceService.getClassSource({
         className: input.className,
@@ -496,7 +555,7 @@ server.tool("get-class-source", "Get Java source for a class by target ({ type:
     });
 }));
 registerToolSchema("get-class-source", getClassSourceSchema);
-server.tool("get-class-members", "Get fields/methods/constructors for one class from binary bytecode by target ({ type: 'artifact', artifactId } or { type: 'resolve', kind, value }).", getClassMembersShape, { readOnlyHint: true }, async (args) => runTool("get-class-members", args, getClassMembersSchema, async (input) => {
+expertTool("get-class-members", "Get fields/methods/constructors for one class from binary bytecode by target ({ kind: 'artifact', artifactId } or { kind: 'version'|'jar'|'coordinate'|'workspace'|'dependency', ... } — same shape as resolve-artifact).", getClassMembersShape, { readOnlyHint: true }, async (args) => runTool("get-class-members", args, getClassMembersSchema, async (input) => {
     const normalizedTarget = normalizeSourceLookupTarget(input.target);
     return sourceService.getClassMembers({
         className: input.className,
@@ -510,15 +569,20 @@ server.tool("get-class-members", "Get fields/methods/constructors for one class
         includeInherited: input.includeInherited,
         memberPattern: input.memberPattern,
         maxMembers: input.maxMembers,
+        cursor: input.cursor,
         projectPath: input.projectPath,
         gradleUserHome: input.gradleUserHome,
         scope: input.scope,
         preferProjectVersion: input.preferProjectVersion,
-        strictVersion: input.strictVersion
+        strictVersion: input.strictVersion,
+        // includeDescriptors is the documented alias for include:["descriptors"]; honor both
+        // (mirror batch-class-members-service / inspect-minecraft class-members handler).
+        includeDescriptors: input.includeDescriptors === true ||
+            (Array.isArray(input.include) && input.include.includes("descriptors"))
     });
 }));
 registerToolSchema("get-class-members", getClassMembersSchema);
-server.tool("search-class-source", "Search indexed class source files for one artifact with symbol/text/path intent and compact hit output.", searchClassSourceShape, { readOnlyHint: true }, async (args) => runTool("search-class-source", args, searchClassSourceSchema, async (input) => {
+expertTool("search-class-source", "Search indexed class source files for one artifact with symbol/text/path intent and compact hit output.", searchClassSourceShape, { readOnlyHint: true }, async (args) => runTool("search-class-source", args, searchClassSourceSchema, async (input) => {
     const scope = input.packagePrefix || input.fileGlob || input.symbolKind
         ? {
             packagePrefix: input.packagePrefix,
@@ -541,20 +605,20 @@ server.tool("search-class-source", "Search indexed class source files for one ar
     });
 }));
 registerToolSchema("search-class-source", searchClassSourceSchema);
-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({
+expertTool("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({
     artifactId: input.artifactId,
     filePath: input.filePath,
     maxBytes: input.maxBytes
 })));
 registerToolSchema("get-artifact-file", getArtifactFileSchema);
-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({
+expertTool("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
 })));
 registerToolSchema("list-artifact-files", listArtifactFilesSchema);
-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({
+expertTool("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,
     fromVersion: input.fromVersion,
@@ -567,7 +631,7 @@ server.tool("trace-symbol-lifecycle", "Trace which Minecraft versions contain a
     includeTimeline: input.includeTimeline
 })));
 registerToolSchema("trace-symbol-lifecycle", traceSymbolLifecycleSchema);
-server.tool("diff-class-signatures", "Compare one class signature between two Minecraft versions and report added/removed/modified constructors, methods, and fields.", diffClassSignaturesShape, { readOnlyHint: true }, async (args) => runTool("diff-class-signatures", args, diffClassSignaturesSchema, async (input) => sourceService.diffClassSignatures({
+expertTool("diff-class-signatures", "Compare one class signature between two Minecraft versions and report added/removed/modified constructors, methods, and fields.", diffClassSignaturesShape, { readOnlyHint: true }, async (args) => runTool("diff-class-signatures", args, diffClassSignaturesSchema, async (input) => sourceService.diffClassSignatures({
     className: input.className,
     fromVersion: input.fromVersion,
     toVersion: input.toVersion,
@@ -577,7 +641,7 @@ server.tool("diff-class-signatures", "Compare one class signature between two Mi
     includeFullDiff: input.includeFullDiff
 })));
 registerToolSchema("diff-class-signatures", diffClassSignaturesSchema);
-server.tool("find-mapping", "Find symbol mapping candidates between namespaces using structured symbol inputs for a specific Minecraft version.", findMappingShape, { readOnlyHint: true }, async (args) => runTool("find-mapping", args, findMappingSchema, async (input) => sourceService.findMapping({
+expertTool("find-mapping", "Find symbol mapping candidates between namespaces using structured symbol inputs for a specific Minecraft version.", findMappingShape, { readOnlyHint: true }, async (args) => runTool("find-mapping", args, findMappingSchema, async (input) => sourceService.findMapping({
     version: input.version,
     kind: input.kind,
     name: input.name,
@@ -587,12 +651,13 @@ server.tool("find-mapping", "Find symbol mapping candidates between namespaces u
     targetMapping: input.targetMapping,
     sourcePriority: input.sourcePriority,
     gradleUserHome: input.gradleUserHome,
+    nameMode: input.nameMode,
     signatureMode: input.signatureMode,
     disambiguation: input.disambiguation,
     maxCandidates: input.maxCandidates
 })));
 registerToolSchema("find-mapping", findMappingSchema);
-server.tool("resolve-method-mapping-exact", "Resolve one method mapping exactly by owner+name+descriptor between namespaces and report resolved/not_found/ambiguous.", resolveMethodMappingExactShape, { readOnlyHint: true }, async (args) => runTool("resolve-method-mapping-exact", args, resolveMethodMappingExactSchema, async (input) => sourceService.resolveMethodMappingExact({
+expertTool("resolve-method-mapping-exact", "Strict shortcut for find-mapping(kind=method, signatureMode=exact): resolve one method mapping by owner+name+descriptor between namespaces and report resolved/not_found/ambiguous. Stricter than find-mapping's exact mode — it requires a COMPLETE descriptor projection and returns mapping_unavailable when the descriptor's class references cannot all be projected to the target namespace (find-mapping is more lenient there). Use find-mapping kind=method signatureMode=exact unless you specifically need that strict-completeness guarantee.", resolveMethodMappingExactShape, { readOnlyHint: true }, async (args) => runTool("resolve-method-mapping-exact", args, resolveMethodMappingExactSchema, async (input) => sourceService.resolveMethodMappingExact({
     version: input.version,
     name: input.name,
     owner: input.owner,
@@ -604,17 +669,18 @@ server.tool("resolve-method-mapping-exact", "Resolve one method mapping exactly
     maxCandidates: input.maxCandidates
 })));
 registerToolSchema("resolve-method-mapping-exact", resolveMethodMappingExactSchema);
-server.tool("get-class-api-matrix", "List class/member API rows across obfuscated/mojang/intermediary/yarn mappings for one class and Minecraft version.", getClassApiMatrixShape, { readOnlyHint: true }, async (args) => runTool("get-class-api-matrix", args, getClassApiMatrixSchema, async (input) => sourceService.getClassApiMatrix({
+expertTool("get-class-api-matrix", "List class/member API rows across obfuscated/mojang/intermediary/yarn mappings for one class and Minecraft version.", getClassApiMatrixShape, { readOnlyHint: true }, async (args) => runTool("get-class-api-matrix", args, getClassApiMatrixSchema, async (input) => sourceService.getClassApiMatrix({
     version: input.version,
     className: input.className,
     classNameMapping: input.classNameMapping,
     includeKinds: parseClassApiKinds(input.includeKinds),
     sourcePriority: input.sourcePriority,
     gradleUserHome: input.gradleUserHome,
-    maxRows: input.maxRows
+    maxRows: input.maxRows,
+    cursor: input.cursor
 })));
 registerToolSchema("get-class-api-matrix", getClassApiMatrixSchema);
-server.tool("resolve-workspace-symbol", "Resolve class/field/method names as seen at compile time for a workspace by reading Gradle Loom mapping settings.", resolveWorkspaceSymbolShape, { readOnlyHint: true }, async (args) => runTool("resolve-workspace-symbol", args, resolveWorkspaceSymbolSchema, async (input) => sourceService.resolveWorkspaceSymbol({
+expertTool("resolve-workspace-symbol", "Resolve class/field/method names as seen at compile time for a workspace by reading Gradle Loom mapping settings.", resolveWorkspaceSymbolShape, { readOnlyHint: true }, async (args) => runTool("resolve-workspace-symbol", args, resolveWorkspaceSymbolSchema, async (input) => sourceService.resolveWorkspaceSymbol({
     projectPath: input.projectPath,
     version: input.version,
     kind: input.kind,
@@ -627,7 +693,7 @@ server.tool("resolve-workspace-symbol", "Resolve class/field/method names as see
     maxCandidates: input.maxCandidates
 })));
 registerToolSchema("resolve-workspace-symbol", resolveWorkspaceSymbolSchema);
-server.tool("check-symbol-exists", "Check whether a class/field/method symbol exists in a specific mapping namespace for one Minecraft version.", checkSymbolExistsShape, { readOnlyHint: true }, async (args) => runTool("check-symbol-exists", args, checkSymbolExistsSchema, async (input) => sourceService.checkSymbolExists({
+expertTool("check-symbol-exists", "Check whether a class/field/method symbol exists in a specific mapping namespace for one Minecraft version.", checkSymbolExistsShape, { readOnlyHint: true }, async (args) => runTool("check-symbol-exists", args, checkSymbolExistsSchema, async (input) => sourceService.checkSymbolExists({
     version: input.version,
     kind: input.kind,
     owner: input.owner,
@@ -641,29 +707,29 @@ server.tool("check-symbol-exists", "Check whether a class/field/method symbol ex
     maxCandidates: input.maxCandidates
 })));
 registerToolSchema("check-symbol-exists", checkSymbolExistsSchema);
-server.tool("nbt-to-json", "Decode Java Edition NBT binary payload (base64) into typed JSON.", nbtToJsonShape, { readOnlyHint: true }, async (args) => runTool("nbt-to-json", args, nbtToJsonSchema, async (input) => Promise.resolve(nbtBase64ToTypedJson({
+server.tool("nbt-to-json", "Decode Java Edition NBT binary payload (base64) into typed JSON.", nbtToJsonShape, { readOnlyHint: true, openWorldHint: false }, async (args) => runTool("nbt-to-json", args, nbtToJsonSchema, async (input) => Promise.resolve(nbtBase64ToTypedJson({
     nbtBase64: input.nbtBase64,
     compression: input.compression
 }, nbtLimits))));
 registerToolSchema("nbt-to-json", nbtToJsonSchema);
-server.tool("nbt-apply-json-patch", "Apply RFC6902 add/remove/replace/test operations to typed NBT JSON.", nbtApplyJsonPatchShape, { readOnlyHint: true }, async (args) => runTool("nbt-apply-json-patch", args, nbtApplyJsonPatchSchema, async (input) => Promise.resolve(applyNbtJsonPatch({
+server.tool("nbt-apply-json-patch", "Apply RFC6902 add/remove/replace/test operations to typed NBT JSON.", nbtApplyJsonPatchShape, { readOnlyHint: true, openWorldHint: false }, async (args) => runTool("nbt-apply-json-patch", args, nbtApplyJsonPatchSchema, async (input) => Promise.resolve(applyNbtJsonPatch({
     typedJson: input.typedJson,
     patch: input.patch
 }, nbtLimits))));
 registerToolSchema("nbt-apply-json-patch", nbtApplyJsonPatchSchema);
-server.tool("json-to-nbt", "Encode typed NBT JSON to Java Edition NBT binary payload (base64).", jsonToNbtShape, { readOnlyHint: true }, async (args) => runTool("json-to-nbt", args, jsonToNbtSchema, async (input) => Promise.resolve(typedJsonToNbtBase64({
+server.tool("json-to-nbt", "Encode typed NBT JSON to Java Edition NBT binary payload (base64).", jsonToNbtShape, { readOnlyHint: true, openWorldHint: false }, async (args) => runTool("json-to-nbt", args, jsonToNbtSchema, async (input) => Promise.resolve(typedJsonToNbtBase64({
     typedJson: input.typedJson,
     compression: input.compression
 }, nbtLimits))));
 registerToolSchema("json-to-nbt", jsonToNbtSchema);
-server.tool("index-artifact", "Rebuild indexed files/symbols metadata for an existing artifactId. Does not resolve new artifacts.", indexArtifactShape, async (args) => runTool("index-artifact", args, indexArtifactSchema, async (input) => sourceService.indexArtifact({
+expertTool("index-artifact", "Rebuild indexed files/symbols metadata for an existing artifactId. Does not resolve new artifacts.", indexArtifactShape, { readOnlyHint: false, idempotentHint: true }, async (args) => runTool("index-artifact", args, indexArtifactSchema, async (input) => sourceService.indexArtifact({
     artifactId: input.artifactId,
     force: input.force
 })));
 registerToolSchema("index-artifact", indexArtifactSchema);
-server.tool("get-runtime-metrics", "Get runtime service counters and latency snapshots for cache/search/index diagnostics.", { readOnlyHint: true }, async (args) => runTool("get-runtime-metrics", args, emptySchema, async () => Promise.resolve(sourceService.getRuntimeMetrics())));
+server.tool("get-runtime-metrics", "Get runtime service counters and latency snapshots for cache/search/index diagnostics.", { readOnlyHint: true, openWorldHint: false }, async (args) => runTool("get-runtime-metrics", args, emptySchema, async () => Promise.resolve(sourceService.getRuntimeMetrics())));
 registerToolSchema("get-runtime-metrics", emptySchema);
-server.tool("validate-mixin", "Validate Mixin source against Minecraft bytecode signatures for a given version.", validateMixinShape, { readOnlyHint: true }, async (args, extra) => runTool("validate-mixin", args, validateMixinSchema, async (input) => sourceService.validateMixin({
+expertTool("validate-mixin", "Validate Mixin source against Minecraft bytecode signatures for a given version.", validateMixinShape, { readOnlyHint: true }, async (args, extra) => runTool("validate-mixin", args, validateMixinSchema, async (input) => sourceService.validateMixin({
     input: input.input,
     sourceRoots: input.sourceRoots,
     version: input.version,
@@ -686,7 +752,7 @@ server.tool("validate-mixin", "Validate Mixin source against Minecraft bytecode
     stageEmitter: makeStageEmitter(extra)
 })));
 registerToolSchema("validate-mixin", validateMixinSchema);
-server.tool("validate-access-widener", "Validate Access Widener file entries against Minecraft bytecode signatures for a given version.", validateAccessWidenerShape, { readOnlyHint: true }, async (args) => runTool("validate-access-widener", args, validateAccessWidenerSchema, async (input) => sourceService.validateAccessWidener({
+expertTool("validate-access-widener", "Validate Access Widener file entries against Minecraft bytecode signatures for a given version.", validateAccessWidenerShape, { readOnlyHint: true }, async (args) => runTool("validate-access-widener", args, validateAccessWidenerSchema, async (input) => sourceService.validateAccessWidener({
     content: input.content,
     version: input.version,
     mapping: input.mapping,
@@ -697,7 +763,7 @@ server.tool("validate-access-widener", "Validate Access Widener file entries aga
     preferProjectVersion: input.preferProjectVersion
 })));
 registerToolSchema("validate-access-widener", validateAccessWidenerSchema);
-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({
+expertTool("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,
@@ -708,7 +774,7 @@ server.tool("validate-access-transformer", "Validate Access Transformer file ent
     preferProjectVersion: input.preferProjectVersion
 })));
 registerToolSchema("validate-access-transformer", validateAccessTransformerSchema);
-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) => {
+expertTool("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, {
         includeClasses: input.includeClasses ?? false
     });
@@ -722,7 +788,7 @@ server.tool("get-registry-data", "Get Minecraft registry data (blocks, items, bi
     maxEntriesPerRegistry: input.maxEntriesPerRegistry
 })));
 registerToolSchema("get-registry-data", getRegistryDataSchema);
-server.tool("compare-versions", "Compare two Minecraft versions to find added/removed classes and registry entry changes. Useful for understanding what changed between versions during mod migration.", compareVersionsShape, { readOnlyHint: true }, async (args) => runTool("compare-versions", args, compareVersionsSchema, async (input) => sourceService.compareVersions({
+expertTool("compare-versions", "Compare two Minecraft versions to find added/removed classes and registry entry changes.", compareVersionsShape, { readOnlyHint: true }, async (args) => runTool("compare-versions", args, compareVersionsSchema, async (input) => sourceService.compareVersions({
     fromVersion: input.fromVersion,
     toVersion: input.toVersion,
     category: input.category,
@@ -730,14 +796,14 @@ server.tool("compare-versions", "Compare two Minecraft versions to find added/re
     maxClassResults: input.maxClassResults
 })));
 registerToolSchema("compare-versions", compareVersionsSchema);
-server.tool("decompile-mod-jar", "Decompile a Minecraft mod JAR using Vineflower and list available classes, or view a specific class source. Builds on analyze-mod-jar by exposing the actual source code.", decompileModJarShape, { readOnlyHint: true }, async (args) => runTool("decompile-mod-jar", args, decompileModJarSchema, async (input) => sourceService.decompileModJar({
+expertTool("decompile-mod-jar", "Decompile a Minecraft mod JAR using Vineflower and list available classes, or view a specific class source. Builds on analyze-mod-jar.", decompileModJarShape, { readOnlyHint: true }, async (args) => runTool("decompile-mod-jar", args, decompileModJarSchema, async (input) => sourceService.decompileModJar({
     jarPath: input.jarPath,
     className: input.className,
     includeFiles: input.includeFiles,
     maxFiles: input.maxFiles
 })));
 registerToolSchema("decompile-mod-jar", decompileModJarSchema);
-server.tool("get-mod-class-source", "Get decompiled source code for a specific class in a mod JAR. The mod JAR will be decompiled if not already cached.", getModClassSourceShape, { readOnlyHint: true }, async (args) => runTool("get-mod-class-source", args, getModClassSourceSchema, async (input) => sourceService.getModClassSource({
+expertTool("get-mod-class-source", "Get decompiled source code for a specific class in a mod JAR. The mod JAR will be decompiled if not already cached. Not read-only: outputFile writes the source to disk.", getModClassSourceShape, { readOnlyHint: false }, async (args) => runTool("get-mod-class-source", args, getModClassSourceSchema, async (input) => sourceService.getModClassSource({
     jarPath: input.jarPath,
     className: input.className,
     maxLines: input.maxLines,
@@ -745,19 +811,20 @@ server.tool("get-mod-class-source", "Get decompiled source code for a specific c
     outputFile: input.outputFile
 })));
 registerToolSchema("get-mod-class-source", getModClassSourceSchema);
-server.tool("search-mod-source", "Search through decompiled mod JAR source code by class name, method, field, or content pattern. The mod JAR will be decompiled automatically if not already cached.", searchModSourceShape, { readOnlyHint: true }, async (args) => runTool("search-mod-source", args, searchModSourceSchema, async (input) => sourceService.searchModSource({
+expertTool("search-mod-source", "Search through decompiled mod JAR source code by class name, method, field, or content pattern. The mod JAR will be decompiled automatically if not already cached.", searchModSourceShape, { readOnlyHint: true }, async (args) => runTool("search-mod-source", args, searchModSourceSchema, async (input) => sourceService.searchModSource({
     jarPath: input.jarPath,
     query: input.query,
     searchType: input.searchType,
     limit: input.limit
 })));
 registerToolSchema("search-mod-source", searchModSourceSchema);
-server.tool("remap-mod-jar", "Remap a Fabric mod JAR from intermediary to yarn/mojang names. Requires Java to be installed.", remapModJarShape, { readOnlyHint: false }, async (args) => runTool("remap-mod-jar", args, remapModJarSchema, async (input) => {
+expertTool("remap-mod-jar", "Remap a Fabric mod JAR from intermediary to yarn/mojang names. Requires Java to be installed.", remapModJarShape, { readOnlyHint: false }, async (args) => runTool("remap-mod-jar", args, remapModJarSchema, async (input) => {
     const result = await remapModJar({
         inputJar: input.inputJar,
         outputJar: input.outputJar,
         mcVersion: input.mcVersion,
-        targetMapping: input.targetMapping
+        targetMapping: input.targetMapping,
+        forceRemap: input.forceRemap
     }, config);
     return result;
 }));

package/dist/mapping/internal-types.d.ts

@@ -50,5 +50,12 @@ export type LoadedGraph = {
     adjacency: Map<import("../types.js").SourceMapping, import("../types.js").SourceMapping[]>;
     pathCache: Map<PairKey, import("../types.js").SourceMapping[] | undefined>;
     recordsByTarget: Map<import("../types.js").SourceMapping, MappingSymbolRecord[]>;
+    /**
+     * Graph-scoped cache of class-to-class descriptor projections, keyed by
+     * `path.join(">") + NUL + internalName`. Value is the projected internal name,
+     * or `null` to memoize an unmapped/ambiguous class. Shared across all member
+     * lookups on this graph; dies with graph eviction.
+     */
+    classProjectionCache: Map<string, string | null>;
     warnings: string[];
 };

package/dist/mapping/lookup.d.ts

@@ -37,7 +37,7 @@ export declare function normalizeDescriptorHint(descriptorHint: string | undefin
 export declare function applyDisambiguationHints(candidates: MappingLookupCandidate[], disambiguation: {
     ownerHint?: string;
     descriptorHint?: string;
-} | undefined): MappingLookupCandidate[];
+} | undefined, warnings?: string[]): MappingLookupCandidate[];
 export declare function projectLookupCandidateDescriptor(candidate: MappingLookupCandidate, sourceDescriptor: string, targetDescriptor: string | undefined): MappingLookupCandidate;
 export declare function effectiveLoomSearchProjectPath(projectPath: string | undefined): string | undefined;
 export declare function collectTargetRecords(graph: LoadedGraph, targetMapping: SourceMapping): MappingSymbolRecord[];

package/dist/mapping/lookup.js

@@ -376,7 +376,7 @@ export function normalizeDescriptorHint(descriptorHint) {
     const normalized = descriptorHint?.trim();
     return normalized || undefined;
 }
-export function applyDisambiguationHints(candidates, disambiguation) {
+export function applyDisambiguationHints(candidates, disambiguation, warnings) {
     if (!disambiguation || candidates.length <= 1) {
         return candidates;
     }
@@ -400,6 +400,12 @@ export function applyDisambiguationHints(candidates, disambiguation) {
         if (descriptorMatched.length > 0) {
             filtered = descriptorMatched;
         }
+        else {
+            // Candidate descriptors are projected toward the target namespace, so a hint
+            // written in another namespace silently matches nothing. Surface that instead
+            // of leaving the ambiguity unexplained.
+            warnings?.push(`descriptorHint "${descriptorHint}" matched none of the ${filtered.length} candidate descriptor(s); it may be in a different mapping namespace. Hint ignored.`);
+        }
     }
     return filtered;
 }

package/dist/mapping/types.d.ts

@@ -55,6 +55,7 @@ export type FindMappingInput = {
     name: string;
     owner?: string;
     descriptor?: string;
+    nameMode?: "fqcn" | "auto";
     signatureMode?: "exact" | "name-only";
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
@@ -103,6 +104,7 @@ export type ClassApiMatrixInput = {
     gradleUserHome?: string;
     includeKinds?: ClassApiMatrixKind[];
     maxRows?: number;
+    cursor?: string;
 };
 export type ClassApiMatrixEntry = {
     symbol: string;
@@ -127,6 +129,10 @@ export type ClassApiMatrixOutput = {
     rows: ClassApiMatrixRow[];
     rowCount: number;
     rowsTruncated?: boolean;
+    /** Continuation cursor when more rows remain; pass back as cursor for the next page. */
+    nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored. */
+    cursorIgnored?: boolean;
     warnings: string[];
     ambiguousRowCount?: number;
 };