@adhisang/minecraft-modding-mcp 4.2.1 → 6.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 { capWarningDetailsForSummary, 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 tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.";
+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,37 @@ 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 report the applied detail/include shape in meta.
+        // detailApplied is omitted when it matches the tool's default to keep responses lean.
+        const defaultDetail = ENTRY_TOOL_NAMES.has(tool)
+            ? "summary"
+            : DEFAULT_DETAIL_BY_TOOL[tool] ?? "summary";
+        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,
+                defaultDetail,
+                include: shapeInput.include.size > 0 ? [...shapeInput.include] : undefined
             })
             : undefined;
         const durationMs = Date.now() - startedAt;
         sourceService.recordToolCall(tool, durationMs);
+        const warningDetails = capWarningDetailsForSummary(classifyWarnings(warnings), effectiveDetail === "summary");
         return objectResult({
             result: projectedResult,
             meta: {
@@ -349,7 +410,8 @@ async function runTool(tool, rawInput, schema, action) {
                 requestId,
                 tool,
                 durationMs,
-                warnings
+                ...(warnings.length > 0 ? { warnings } : {}),
+                ...(warningDetails.length > 0 ? { warningDetails } : {})
             }
         });
     }
@@ -393,8 +455,7 @@ async function runTool(tool, rawInput, schema, action) {
         const errorMeta = {
             requestId,
             tool,
-            durationMs: errorDurationMs,
-            warnings: []
+            durationMs: errorDurationMs
         };
         applyErrorMetaExtensions(errorMeta, caughtError);
         return objectResult({
@@ -403,14 +464,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, workspace analysis, and API overview. subject.kind='symbol' auto-detects class/field/method from the selector.", 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 +489,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,16 +501,16 @@ 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 get-class-source for many classes sharing one resolved artifact; returns per-entry status plus aggregate summary. Not read-only: per-entry outputFile writes 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)));
+    server.tool("batch-class-members", "Batch get-class-members for many classes sharing one resolved artifact; returns per-entry status plus aggregate summary.", batchClassMembersShape, { readOnlyHint: true }, async (args) => runTool("batch-class-members", args, batchClassMembersSchema, async (input) => batchClassMembersService.execute(input)));
     registerToolSchema("batch-class-members", batchClassMembersSchema);
-    server.tool("batch-symbol-exists", "Batch existence/mapping query: probe many symbols in one call against a shared Minecraft-version artifact. Accepts target.kind=workspace or version only (other kinds carry library versions, not Minecraft versions). Per-entry retry suggestions point at check-symbol-exists.", batchSymbolExistsShape, { readOnlyHint: true }, async (args) => runTool("batch-symbol-exists", args, batchSymbolExistsSchema, async (input) => batchSymbolExistsService.execute(input)));
+    server.tool("batch-symbol-exists", "Batch check-symbol-exists for many symbols against one shared Minecraft version (target.kind=version or workspace only).", batchSymbolExistsShape, { readOnlyHint: true }, async (args) => runTool("batch-symbol-exists", args, batchSymbolExistsSchema, async (input) => batchSymbolExistsService.execute(input)));
     registerToolSchema("batch-symbol-exists", batchSymbolExistsSchema);
-    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)));
+    server.tool("batch-mappings", "Batch find-mapping: resolve many symbols across mapping namespaces with one shared Minecraft version.", 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 a source artifact and return artifact metadata. For target.kind=jar, only <basename>-sources.jar is auto-adopted.", 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 +520,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 +530,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. Default mode=metadata returns a symbol outline only; pass mode=snippet or mode=full to read source text. Not read-only: outputFile writes 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 +559,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.", 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 +573,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 +609,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 +635,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 +645,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 +655,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 variant of find-mapping(kind=method, signatureMode=exact): requires a COMPLETE descriptor projection and returns mapping_unavailable when any descriptor class reference cannot be projected. Prefer find-mapping unless you need that 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 +673,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 +697,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 +711,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 +756,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 +767,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 +778,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 +792,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 +800,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 +815,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/java-process.js

@@ -107,7 +107,7 @@ export function runJavaProcess(options) {
                 }
             }));
         });
-        proc.once("exit", (code) => {
+        proc.once("close", (code) => {
             clearTimeout(timer);
             resolve({
                 exitCode: code ?? -1,

package/dist/json-rpc-framing.d.ts

@@ -9,6 +9,9 @@ export declare function encodeJsonRpcMessage(message: JSONRPCMessage, mode: Conc
 export declare class JsonRpcFrameReader {
     private mode;
     private buffer;
+    private pendingChunks;
+    private pendingBytes;
+    private awaitedFrameEnd;
     get currentMode(): FramingMode;
     reset(): void;
     clear(): void;
@@ -16,6 +19,7 @@ export declare class JsonRpcFrameReader {
         onFrame: (frame: ParsedJsonRpcFrame) => void;
         onError: (error: Error) => void;
     }): void;
+    private canCompleteFrame;
     private detectMode;
     private readLineDelimitedMessage;
     private readContentLengthMessage;

package/dist/json-rpc-framing.js

@@ -25,21 +25,35 @@ export function encodeJsonRpcMessage(message, mode) {
 export class JsonRpcFrameReader {
     mode = "unknown";
     buffer = Buffer.alloc(0);
+    pendingChunks = [];
+    pendingBytes = 0;
+    awaitedFrameEnd = -1;
     get currentMode() {
         return this.mode;
     }
     reset() {
         this.mode = "unknown";
+        this.awaitedFrameEnd = -1;
     }
     clear() {
         this.mode = "unknown";
         this.buffer = Buffer.alloc(0);
+        this.pendingChunks = [];
+        this.pendingBytes = 0;
+        this.awaitedFrameEnd = -1;
     }
     processChunk(chunk, handlers) {
         if (chunk.length === 0) {
             return;
         }
-        this.buffer = Buffer.concat([this.buffer, chunk]);
+        this.pendingChunks.push(chunk);
+        this.pendingBytes += chunk.length;
+        if (!this.canCompleteFrame(chunk)) {
+            return;
+        }
+        this.buffer = Buffer.concat([this.buffer, ...this.pendingChunks]);
+        this.pendingChunks = [];
+        this.pendingBytes = 0;
         while (true) {
             try {
                 if (this.mode === "unknown") {
@@ -71,6 +85,12 @@ export class JsonRpcFrameReader {
             }
         }
     }
+    canCompleteFrame(chunk) {
+        if (this.mode === "content-length" && this.awaitedFrameEnd >= 0) {
+            return this.buffer.length + this.pendingBytes >= this.awaitedFrameEnd;
+        }
+        return chunk.includes(0x0a);
+    }
     detectMode() {
         while (this.buffer.length > 0) {
             if (this.buffer[0] === 0x0a) {
@@ -124,6 +144,7 @@ export class JsonRpcFrameReader {
         }
     }
     readContentLengthMessage() {
+        this.awaitedFrameEnd = -1;
         const headerBoundary = findHeaderBoundary(this.buffer);
         if (!headerBoundary) {
             return undefined;
@@ -158,6 +179,7 @@ export class JsonRpcFrameReader {
         const messageStart = headerBoundary.index + headerBoundary.delimiterBytes;
         const frameEnd = messageStart + contentLength;
         if (this.buffer.length < frameEnd) {
+            this.awaitedFrameEnd = frameEnd;
             return undefined;
         }
         const body = this.buffer.subarray(messageStart, frameEnd).toString("utf8");