@adhisang/minecraft-modding-mcp 6.1.1 → 6.2.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { makeStageEmitter } from "./stage-emitter.js";
-import { ZodError, z } from "zod";
+import { ZodError } from "zod";
 import { CompatStdioServerTransport } from "./compat-stdio-transport.js";
 import { objectResult } from "./mcp-helpers.js";
 import { prepareToolInput } from "./tool-input.js";
@@ -34,7 +34,7 @@ import { buildEntryToolMeta } from "./entry-tools/response-contract.js";
 import { registerToolSchema } from "./tool-schema-registry.js";
 import { buildSuggestedCall } from "./build-suggested-call.js";
 import { applyErrorMetaExtensions, mapErrorToProblem } from "./tool-guidance.js";
-import { nonEmptyString, optionalPositiveInt, analyzeModJarSchema, analyzeModJarShape, batchClassMembersSchema, batchClassMembersShape, batchClassSourceSchema, batchClassSourceShape, batchMappingsSchema, batchMappingsShape, batchSymbolExistsSchema, batchSymbolExistsShape, checkSymbolExistsSchema, checkSymbolExistsShape, compareVersionsSchema, compareVersionsShape, decompileModJarSchema, decompileModJarShape, diffClassSignaturesSchema, diffClassSignaturesShape, emptySchema, findMappingSchema, findMappingShape, getArtifactFileSchema, getArtifactFileShape, getClassApiMatrixSchema, getClassApiMatrixShape, getClassMembersSchema, getClassMembersShape, getClassSourceSchema, getClassSourceShape, getModClassSourceSchema, getModClassSourceShape, getRegistryDataSchema, getRegistryDataShape, indexArtifactSchema, indexArtifactShape, jsonToNbtSchema, jsonToNbtShape, listArtifactFilesSchema, listArtifactFilesShape, listVersionsSchema, listVersionsShape, nbtApplyJsonPatchSchema, nbtApplyJsonPatchShape, nbtToJsonSchema, nbtToJsonShape, remapModJarSchema, remapModJarShape, resolveArtifactSchema, resolveArtifactShape, resolveMethodMappingExactSchema, resolveMethodMappingExactShape, resolveWorkspaceSymbolSchema, resolveWorkspaceSymbolShape, searchClassSourceSchema, searchClassSourceShape, searchModSourceSchema, searchModSourceShape, traceSymbolLifecycleSchema, traceSymbolLifecycleShape, validateAccessTransformerSchema, validateAccessTransformerShape, validateAccessWidenerSchema, validateAccessWidenerShape, validateMixinSchema, validateMixinShape, verifyMixinTargetSchema, verifyMixinTargetShape } from "./tool-schemas.js";
+import { analyzeModJarSchema, analyzeModJarShape, batchClassMembersSchema, batchClassMembersShape, batchClassSourceSchema, batchClassSourceShape, batchMappingsSchema, batchMappingsShape, batchSymbolExistsSchema, batchSymbolExistsShape, checkSymbolExistsSchema, checkSymbolExistsShape, compareVersionsSchema, compareVersionsShape, decompileModJarSchema, decompileModJarShape, diffClassSignaturesSchema, diffClassSignaturesShape, emptySchema, findMappingSchema, findMappingShape, getArtifactFileSchema, getArtifactFileShape, getClassApiMatrixSchema, getClassApiMatrixShape, getClassMembersSchema, getClassMembersShape, getClassSourceSchema, getClassSourceShape, getModClassSourceSchema, getModClassSourceShape, getRegistryDataSchema, getRegistryDataShape, indexArtifactSchema, indexArtifactShape, jsonToNbtSchema, jsonToNbtShape, listArtifactFilesSchema, listArtifactFilesShape, listVersionsSchema, listVersionsShape, nbtApplyJsonPatchSchema, nbtApplyJsonPatchShape, nbtToJsonSchema, nbtToJsonShape, remapModJarSchema, remapModJarShape, resolveArtifactSchema, resolveArtifactShape, resolveMethodMappingExactSchema, resolveMethodMappingExactShape, resolveWorkspaceSymbolSchema, resolveWorkspaceSymbolShape, searchClassSourceSchema, searchClassSourceShape, searchModSourceSchema, searchModSourceShape, traceSymbolLifecycleSchema, traceSymbolLifecycleShape, validateAccessTransformerSchema, validateAccessTransformerShape, validateAccessWidenerSchema, validateAccessWidenerShape, validateMixinSchema, validateMixinShape, verifyMixinTargetSchema, verifyMixinTargetShape, findClassShape, findClassSchema } from "./tool-schemas.js";
 export { mapErrorToProblem, applyErrorMetaExtensions };
 if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "production";
@@ -121,9 +121,11 @@ const inspectMinecraftService = new InspectMinecraftService({
     searchClassSource: (input) => sourceService.searchClassSource(input),
     getArtifactFile: (input) => sourceService.getArtifactFile(input),
     listArtifactFiles: (input) => sourceService.listArtifactFiles(input),
-    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath)
+    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath),
+    listWorkspaceContexts: () => sourceService.workspaceContextCache.list()
 });
 const analyzeSymbolService = new AnalyzeSymbolService({
+    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath),
     checkSymbolExists: (input) => sourceService.checkSymbolExists(input),
     findMapping: (input) => sourceService.findMapping(input),
     resolveMethodMappingExact: (input) => sourceService.resolveMethodMappingExact(input),
@@ -141,7 +143,8 @@ const analyzeModService = new AnalyzeModService({
     decompileModJar: (input) => sourceService.decompileModJar(input),
     getModClassSource: (input) => sourceService.getModClassSource(input),
     searchModSource: (input) => sourceService.searchModSource(input),
-    remapModJar: (input) => remapModJar(input, config)
+    remapModJar: (input) => remapModJar(input, config),
+    getModClassMembers: (input) => sourceService.getModClassMembers(input)
 });
 const validateProjectService = new ValidateProjectService({
     validateMixin: (input, options) => sourceService.validateMixin(input, options),
@@ -475,7 +478,7 @@ server.tool("analyze-symbol", "Top-level workflow tool for symbol existence, map
 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);
-server.tool("analyze-mod", "Top-level workflow tool for mod metadata inspection, decompile/search flows, class source, and safe remap previews/applies.", analyzeModShape, { readOnlyHint: false }, async (args) => runTool("analyze-mod", args, analyzeModSchema, async (input) => analyzeModService.execute(input)));
+server.tool("analyze-mod", "Top-level workflow tool for mod metadata inspection, decompile/search flows, class source, bytecode-only class member reads, and safe remap previews/applies.", analyzeModShape, { readOnlyHint: false }, async (args) => runTool("analyze-mod", args, analyzeModSchema, async (input) => analyzeModService.execute(input)));
 registerToolSchema("analyze-mod", analyzeModSchema);
 server.tool("validate-project", "Top-level workflow tool for project summary, direct mixin validation, and access widener/access transformer validation.", validateProjectShape, { readOnlyHint: true }, async (args, extra) => runTool("validate-project", args, validateProjectSchema, async (input) => validateProjectService.execute(input, {
     stageEmitter: makeStageEmitter(extra)
@@ -524,15 +527,32 @@ expertTool("resolve-artifact", "Resolve a source artifact and return artifact me
         (Array.isArray(input.include) && input.include.includes("samples"))
 })));
 registerToolSchema("resolve-artifact", resolveArtifactSchema);
-const findClassShape = {
-    className: nonEmptyString.describe("Simple name (e.g. Blocks) or fully-qualified name (e.g. net.minecraft.world.level.block.Blocks)"),
-    artifactId: nonEmptyString,
-    limit: optionalPositiveInt.describe("default 20, max 200")
-};
-const findClassSchema = z.object(findClassShape);
+// Flat tools accept `target` as an additive alternative to `artifactId`
+// (mutually exclusive, enforced by each schema). A target is resolved to its
+// artifactId here before the underlying artifactId-based service call.
+async function resolveFlatArtifactId(input) {
+    if (input.artifactId) {
+        return input.artifactId;
+    }
+    const target = input.target;
+    // {kind:"artifact"} reuses an already-resolved artifact without a resolve
+    // round-trip. Workspace-context kinds carry their own projectPath when the
+    // target shape provides one; kinds that require workspace context beyond
+    // that fail with the resolver's own projectPath guidance.
+    if (target?.kind === "artifact" && target.artifactId) {
+        return target.artifactId;
+    }
+    const resolved = await sourceService.resolveArtifact({
+        target: target,
+        ...(target && "projectPath" in target && target.projectPath
+            ? { projectPath: target.projectPath }
+            : {})
+    });
+    return resolved.artifactId;
+}
 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,
+    artifactId: await resolveFlatArtifactId(input),
     limit: input.limit
 })));
 registerToolSchema("find-class", findClassSchema);
@@ -596,7 +616,7 @@ expertTool("search-class-source", "Search indexed class source files for one art
         }
         : undefined;
     return sourceService.searchClassSource({
-        artifactId: input.artifactId,
+        artifactId: await resolveFlatArtifactId(input),
         query: input.query,
         intent: input.intent,
         match: input.match,
@@ -611,13 +631,13 @@ expertTool("search-class-source", "Search indexed class source files for one art
 }));
 registerToolSchema("search-class-source", searchClassSourceSchema);
 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,
+    artifactId: await resolveFlatArtifactId(input),
     filePath: input.filePath,
     maxBytes: input.maxBytes
 })));
 registerToolSchema("get-artifact-file", getArtifactFileSchema);
 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,
+    artifactId: await resolveFlatArtifactId(input),
     prefix: input.prefix,
     limit: input.limit,
     cursor: input.cursor
@@ -727,8 +747,8 @@ server.tool("json-to-nbt", "Encode typed NBT JSON to Java Edition NBT binary pay
     compression: input.compression
 }, nbtLimits))));
 registerToolSchema("json-to-nbt", jsonToNbtSchema);
-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,
+expertTool("index-artifact", "Rebuild indexed files/symbols metadata for an artifact addressed by artifactId or target. A new target is resolved and ingested first; force rebuilds an existing index.", indexArtifactShape, { readOnlyHint: false, idempotentHint: true }, async (args) => runTool("index-artifact", args, indexArtifactSchema, async (input) => sourceService.indexArtifact({
+    artifactId: await resolveFlatArtifactId(input),
     force: input.force
 })));
 registerToolSchema("index-artifact", indexArtifactSchema);

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

@@ -56,6 +56,13 @@ export type CandidateAccumulator = {
 };
 export type LoadedGraph = {
     version: string;
+    /**
+     * True when the runtime already uses deobfuscated names, so the graph is
+     * deliberately empty. Surfaces on outputs as
+     * mappingContext.unobfuscatedRuntime instead of a per-response warning
+     * sentence.
+     */
+    unobfuscatedRuntime?: boolean;
     priority: import("../types.js").MappingSourcePriority;
     mode: GraphLoadMode;
     pairs: Map<PairKey, PairRecord>;

package/dist/mapping/types.d.ts

@@ -38,6 +38,19 @@ export type SymbolResolutionOutput = {
         sourceMapping: SourceMapping;
         targetMapping?: SourceMapping;
         sourcePriorityApplied: MappingSourcePriority;
+        /**
+         * The runtime already uses deobfuscated names, so the mapping graph is
+         * deliberately empty. Replaces the former per-response warning
+         * "Version X is unobfuscated; mapping graph is empty because the runtime
+         * already uses deobfuscated names."
+         */
+        unobfuscatedRuntime?: boolean;
+        /**
+         * Symbol existence was validated against runtime bytecode. Replaces the
+         * former per-response warning "Version X is unobfuscated; validated
+         * symbol existence against runtime bytecode."
+         */
+        runtimeValidated?: boolean;
     };
     resolved: boolean;
     status: SymbolResolutionStatus;
@@ -122,6 +135,11 @@ export type ClassApiMatrixRow = {
     completeness: boolean;
 };
 export type ClassApiMatrixOutput = {
+    /**
+     * The runtime already uses deobfuscated names, so non-mojang matrix
+     * columns are empty by design (the mapping graph is deliberately empty).
+     */
+    unobfuscatedRuntime?: boolean;
     version: string;
     className: string;
     classNameMapping: SourceMapping;

package/dist/mapping-service.js

@@ -126,6 +126,9 @@ export class MappingService {
             };
         }
         const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath, input.gradleUserHome);
+        if (graph.unobfuscatedRuntime) {
+            mappingContext.unobfuscatedRuntime = true;
+        }
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -352,6 +355,9 @@ export class MappingService {
             };
         }
         const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath, input.gradleUserHome);
+        if (graph.unobfuscatedRuntime) {
+            mappingContext.unobfuscatedRuntime = true;
+        }
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -469,6 +475,7 @@ export class MappingService {
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
         const graph = await this.loadGraph(version, priority, "full", undefined, input.gradleUserHome);
         const warnings = [...graph.warnings];
+        const unobfuscatedRuntime = graph.unobfuscatedRuntime === true;
         const includeKinds = normalizeIncludedKinds(input.includeKinds);
         const pathCache = new Map();
         const resolvePath = (sourceMapping, targetMapping) => {
@@ -514,6 +521,7 @@ export class MappingService {
                 },
                 rows: [],
                 rowCount: 0,
+                ...(unobfuscatedRuntime ? { unobfuscatedRuntime: true } : {}),
                 warnings
             };
         }
@@ -638,6 +646,7 @@ export class MappingService {
             version,
             className,
             classNameMapping,
+            ...(unobfuscatedRuntime ? { unobfuscatedRuntime: true } : {}),
             classIdentity: {
                 obfuscated: classByMapping.obfuscated?.symbol,
                 mojang: classByMapping.mojang?.symbol,
@@ -727,6 +736,9 @@ export class MappingService {
                 };
             })();
         const graph = await this.loadGraph(version, priority, sourceMapping === "mojang" ? "obfuscated-mojang-only" : "full", undefined, input.gradleUserHome);
+        if (graph.unobfuscatedRuntime) {
+            mappingContext.unobfuscatedRuntime = true;
+        }
         const warnings = [...graph.warnings];
         const records = collectTargetRecords(graph, sourceMapping);
         if (records.length === 0) {
@@ -1115,9 +1127,10 @@ export class MappingService {
                 recordsByTarget: new Map(),
                 exactRecordIndex: new Map(),
                 classProjectionCache: new Map(),
-                warnings: [
-                    `Version ${version} is unobfuscated; mapping graph is empty because the runtime already uses deobfuscated names.`
-                ]
+                // No warning sentence: consumers surface this as the structured
+                // mappingContext.unobfuscatedRuntime flag instead.
+                unobfuscatedRuntime: true,
+                warnings: []
             };
         }
         const graph = {

package/dist/minecraft-explorer-service.d.ts

@@ -15,6 +15,10 @@ export interface SignatureMember {
     jvmDescriptor: string;
     accessFlags: number;
     isSynthetic: boolean;
+    /** Rendered default value of an annotation-type member (AnnotationDefault). */
+    annotationDefault?: string;
+    /** Rendered runtime-visible annotations on the member, e.g. "@java.lang.Deprecated". */
+    annotations?: string[];
 }
 export interface GetSignatureInput {
     fqn: string;

package/dist/minecraft-explorer-service.js

@@ -3,6 +3,7 @@ import { loadConfig } from "./config.js";
 import { artifactSignatureFromFile, normalizeJarPath } from "./path-resolver.js";
 import { createJarEntryReader } from "./source-jar-reader.js";
 import { matchesMemberPattern } from "./source/member-pattern.js";
+import { isUnobfuscatedVersion } from "./version-service.js";
 const CLASSFILE_MAGIC = 0xcafebabe;
 const MAX_INHERITANCE_DEPTH = 64;
 const ACC_PUBLIC = 0x0001;
@@ -173,6 +174,21 @@ function toInternalName(fqn) {
 function extractVersionFromPath(inputPath) {
     return inputPath.match(/(\d+\.\d+(?:\.\d+)?)/)?.[1];
 }
+// Super classes/interfaces from these packages are never inside a Minecraft
+// jar, so failing to resolve them during inherited-member expansion is
+// expected, not a signal. Suppression is allowlist-only and per-prefix
+// verified: JDK packages by definition, com.mojang.serialization because the
+// DataFixerUpper serialization library ships as its own dependency jar
+// (checked against 26.x client-only/common and 1.21.10 client jars). A broad
+// com.mojang.* entry would be wrong — com.mojang.blaze3d.* IS client-jar
+// content and its resolution failures must stay visible.
+const KNOWN_ABSENT_PLATFORM_PREFIXES = [
+    "java/",
+    "javax/",
+    "jdk/",
+    "sun/",
+    "com/mojang/serialization/"
+];
 class SignatureCacheStore {
     maxEntries;
     nodes = new Map();
@@ -305,16 +321,111 @@ function readOptionalClassName(cp, index) {
     }
     return readClassName(cp, index);
 }
+function descriptorToClassName(descriptor) {
+    if (descriptor.startsWith("L") && descriptor.endsWith(";")) {
+        return descriptor.slice(1, -1).replace(/\//g, ".");
+    }
+    return descriptor;
+}
+function readNumericConstant(cp, index) {
+    const entry = cp[index];
+    if (entry && (entry.tag === 3 || entry.tag === 4 || entry.tag === 5 || entry.tag === 6)) {
+        return String(entry.numericValue);
+    }
+    return "<unknown-constant>";
+}
+// JVMS 4.7.16.1 element_value, rendered as compact Java-ish text. Every
+// branch reads exactly its encoded bytes so nested/array values stay aligned.
+function readElementValue(reader, cp) {
+    const tag = String.fromCharCode(reader.readU1());
+    switch (tag) {
+        case "B":
+        case "I":
+        case "S":
+        case "D":
+        case "F":
+        case "J":
+            return readNumericConstant(cp, reader.readU2());
+        case "C": {
+            const raw = readNumericConstant(cp, reader.readU2());
+            const code = Number(raw);
+            return Number.isFinite(code) ? `'${String.fromCharCode(code)}'` : raw;
+        }
+        case "Z": {
+            const raw = readNumericConstant(cp, reader.readU2());
+            return raw === "1" ? "true" : raw === "0" ? "false" : raw;
+        }
+        case "s":
+            return JSON.stringify(readUtf8(cp, reader.readU2()));
+        case "e": {
+            const typeDescriptor = readUtf8(cp, reader.readU2());
+            const constantName = readUtf8(cp, reader.readU2());
+            return `${descriptorToClassName(typeDescriptor)}.${constantName}`;
+        }
+        case "c":
+            return `${descriptorToClassName(readUtf8(cp, reader.readU2()))}.class`;
+        case "@":
+            return readAnnotationText(reader, cp);
+        case "[": {
+            const count = reader.readU2();
+            const parts = [];
+            for (let index = 0; index < count; index += 1) {
+                parts.push(readElementValue(reader, cp));
+            }
+            return `{${parts.join(", ")}}`;
+        }
+        default:
+            return "<unsupported-element-value>";
+    }
+}
+function readAnnotationText(reader, cp) {
+    const typeDescriptor = readUtf8(cp, reader.readU2());
+    const pairCount = reader.readU2();
+    const pairs = [];
+    for (let index = 0; index < pairCount; index += 1) {
+        const name = readUtf8(cp, reader.readU2());
+        pairs.push(`${name} = ${readElementValue(reader, cp)}`);
+    }
+    return `@${descriptorToClassName(typeDescriptor)}${pairs.length > 0 ? `(${pairs.join(", ")})` : ""}`;
+}
 function readAttributes(reader, cp, count) {
     const names = [];
+    let annotationDefault;
+    let annotations;
     for (let index = 0; index < count; index += 1) {
         const nameIndex = reader.readU2();
         const length = reader.readU4();
         const attributeName = readUtf8(cp, nameIndex);
         names.push(attributeName);
-        reader.skip(length);
+        const body = reader.readBytes(length);
+        // Malformed attribute bodies must never fail the whole class parse; the
+        // rendered value is best-effort metadata, not a structural field.
+        if (attributeName === "AnnotationDefault") {
+            try {
+                annotationDefault = readElementValue(new ByteReader(body), cp);
+            }
+            catch {
+                annotationDefault = undefined;
+            }
+        }
+        else if (attributeName === "RuntimeVisibleAnnotations") {
+            try {
+                const bodyReader = new ByteReader(body);
+                const annotationCount = bodyReader.readU2();
+                const rendered = [];
+                for (let a = 0; a < annotationCount; a += 1) {
+                    rendered.push(readAnnotationText(bodyReader, cp));
+                }
+                if (rendered.length > 0) {
+                    annotations = rendered;
+                }
+            }
+            catch {
+                annotations = undefined;
+            }
+        }
     }
-    return names;
+    return { names, annotationDefault, annotations };
 }
 function parseClassFile(buffer) {
     const reader = new ByteReader(buffer);
@@ -336,17 +447,28 @@ function parseClassFile(buffer) {
                 cp[index] = { tag: 1, value: reader.readBytes(length).toString("utf8") };
                 break;
             }
-            case 3:
-            case 4:
-                reader.skip(4);
-                cp[index] = { tag };
+            case 3: {
+                const bytes = reader.readBytes(4);
+                cp[index] = { tag, numericValue: bytes.readInt32BE(0) };
+                break;
+            }
+            case 4: {
+                const bytes = reader.readBytes(4);
+                cp[index] = { tag, numericValue: bytes.readFloatBE(0) };
                 break;
-            case 5:
-            case 6:
-                reader.skip(8);
-                cp[index] = { tag };
+            }
+            case 5: {
+                const bytes = reader.readBytes(8);
+                cp[index] = { tag, numericValue: bytes.readBigInt64BE(0).toString() };
                 index += 1;
                 break;
+            }
+            case 6: {
+                const bytes = reader.readBytes(8);
+                cp[index] = { tag, numericValue: bytes.readDoubleBE(0) };
+                index += 1;
+                break;
+            }
             case 7:
             case 8:
             case 16:
@@ -389,13 +511,17 @@ function parseClassFile(buffer) {
             const nameIndex = reader.readU2();
             const descriptorIndex = reader.readU2();
             const attributesCount = reader.readU2();
-            const attributeNames = readAttributes(reader, cp, attributesCount);
+            const attributeResult = readAttributes(reader, cp, attributesCount);
             members.push({
                 name: readUtf8(cp, nameIndex),
                 descriptor: readUtf8(cp, descriptorIndex),
                 accessFlags,
                 isSynthetic: (accessFlags & ACC_SYNTHETIC) !== 0 ||
-                    attributeNames.some((attributeName) => attributeName === "Synthetic")
+                    attributeResult.names.some((attributeName) => attributeName === "Synthetic"),
+                ...(attributeResult.annotationDefault !== undefined
+                    ? { annotationDefault: attributeResult.annotationDefault }
+                    : {}),
+                ...(attributeResult.annotations ? { annotations: attributeResult.annotations } : {})
             });
         }
         return members;
@@ -478,6 +604,9 @@ export class MinecraftExplorerService {
         const parsedClassCache = new Map([[parsed.internalName, parsed]]);
         const warnings = [];
         const warnMissingInheritedClass = (internalName, relation) => {
+            if (KNOWN_ABSENT_PLATFORM_PREFIXES.some((prefix) => internalName.startsWith(prefix))) {
+                return;
+            }
             warnings.push(`Could not resolve ${relation} class "${internalName.replace(/\//g, ".")}" while expanding inherited members.`);
         };
         const readParsedClassByInternalName = async (internalName, relation) => {
@@ -572,7 +701,9 @@ export class MinecraftExplorerService {
                     javaSignature: `${modifiers ? `${modifiers} ` : ""}${fieldType} ${member.name}`.trim(),
                     jvmDescriptor: member.descriptor,
                     accessFlags: member.accessFlags,
-                    isSynthetic: member.isSynthetic
+                    isSynthetic: member.isSynthetic,
+                    ...(member.annotationDefault !== undefined ? { annotationDefault: member.annotationDefault } : {}),
+                    ...(member.annotations ? { annotations: member.annotations } : {})
                 };
             }
             const parsedMethod = parseMethodDescriptor(member.descriptor);
@@ -585,7 +716,9 @@ export class MinecraftExplorerService {
                     javaSignature: `${modifiers ? `${modifiers} ` : ""}${ownerSimpleClassName}(${args})`.trim(),
                     jvmDescriptor: member.descriptor,
                     accessFlags: member.accessFlags,
-                    isSynthetic: member.isSynthetic
+                    isSynthetic: member.isSynthetic,
+                    ...(member.annotationDefault !== undefined ? { annotationDefault: member.annotationDefault } : {}),
+                    ...(member.annotations ? { annotations: member.annotations } : {})
                 };
             }
             return {
@@ -594,7 +727,9 @@ export class MinecraftExplorerService {
                 javaSignature: `${modifiers ? `${modifiers} ` : ""}${parsedMethod.returnType} ${member.name}(${args})`.trim(),
                 jvmDescriptor: member.descriptor,
                 accessFlags: member.accessFlags,
-                isSynthetic: member.isSynthetic
+                isSynthetic: member.isSynthetic,
+                ...(member.annotationDefault !== undefined ? { annotationDefault: member.annotationDefault } : {}),
+                ...(member.annotations ? { annotations: member.annotations } : {})
             };
         };
         const shouldIncludeMember = (member) => {
@@ -652,10 +787,14 @@ export class MinecraftExplorerService {
         };
     }
     contextForJar(jarPath) {
+        const minecraftVersion = extractVersionFromPath(jarPath);
         return {
-            minecraftVersion: extractVersionFromPath(jarPath) ?? "unknown",
+            minecraftVersion: minecraftVersion ?? "unknown",
             mappingType: "unknown",
-            mappingNamespace: "obfuscated",
+            // Unobfuscated releases ship mojang names in their bytecode; claiming
+            // "obfuscated" for them misled namespace reconciliation downstream.
+            // With no derivable version the conservative "obfuscated" stands.
+            mappingNamespace: minecraftVersion && isUnobfuscatedVersion(minecraftVersion) ? "mojang" : "obfuscated",
             jarHash: artifactSignatureFromFile(jarPath).sourceArtifactId,
             generatedAt: new Date().toISOString()
         };

package/dist/mod-analyzer.d.ts

@@ -19,8 +19,15 @@ export interface ModAnalysisResult {
     dependencies?: ModDependency[];
     classCount: number;
     classes?: string[];
+    /**
+     * In-archive paths of bundled Jar-in-Jar nested jars (META-INF/jars scan
+     * plus present-and-safe fabric.mod.json "jars" declarations). Absent when
+     * the mod bundles none.
+     */
+    nestedJars?: string[];
 }
 export interface AnalyzeModOptions {
     includeClasses?: boolean;
 }
+export declare function collectNestedJars(entries: string[], declared: string[] | undefined): string[];
 export declare function analyzeModJar(jarPath: string, options?: AnalyzeModOptions): Promise<ModAnalysisResult>;

package/dist/mod-analyzer.js

@@ -1,7 +1,7 @@
 import { parse as parseToml } from "smol-toml";
 import { z } from "zod";
 import { AppError, ERROR_CODES } from "./errors.js";
-import { normalizeJarPath } from "./path-resolver.js";
+import { isSecureJarEntryPath, normalizeJarPath } from "./path-resolver.js";
 import { listJarEntries, readJarEntryAsUtf8 } from "./source-jar-reader.js";
 function toErrorMessage(value) {
     if (value instanceof Error) {
@@ -32,7 +32,8 @@ const fabricModJsonSchema = z
     depends: z.record(z.union([z.string(), z.array(z.string())])).optional(),
     recommends: z.record(z.union([z.string(), z.array(z.string())])).optional(),
     conflicts: z.record(z.union([z.string(), z.array(z.string())])).optional(),
-    suggests: z.record(z.union([z.string(), z.array(z.string())])).optional()
+    suggests: z.record(z.union([z.string(), z.array(z.string())])).optional(),
+    jars: z.array(z.object({ file: z.string() }).passthrough()).optional()
 })
     .passthrough();
 const quiltModJsonSchema = z
@@ -120,6 +121,7 @@ function parseFabricMod(content) {
         ...collectFabricDeps(mod.conflicts, "conflicts"),
         ...collectFabricDeps(mod.suggests, "optional")
     ];
+    const declaredNestedJars = mod.jars?.map((entry) => entry.file);
     return {
         modId: mod.id,
         modName: mod.name,
@@ -128,9 +130,25 @@ function parseFabricMod(content) {
         entrypoints,
         mixinConfigs,
         accessWidener: mod.accessWidener,
-        dependencies: dependencies.length > 0 ? dependencies : undefined
+        dependencies: dependencies.length > 0 ? dependencies : undefined,
+        ...(declaredNestedJars && declaredNestedJars.length > 0 ? { declaredNestedJars } : {})
     };
 }
+// Nested-jar inventory: every real `.jar` entry directly under META-INF/jars/
+// plus declared fabric.mod.json "jars" files that actually exist in the
+// archive under a safe (non-escaping) path. Declared-but-absent or escaping
+// paths are dropped — the inventory never names content the archive cannot
+// safely serve.
+export function collectNestedJars(entries, declared) {
+    const present = new Set(entries);
+    const collected = new Set(entries.filter((entry) => /^META-INF\/jars\/[^/]+\.jar$/.test(entry)));
+    for (const file of declared ?? []) {
+        if (isSecureJarEntryPath(file) && present.has(file) && file.endsWith(".jar")) {
+            collected.add(file);
+        }
+    }
+    return [...collected].sort((left, right) => left.localeCompare(right));
+}
 // ---------------------------------------------------------------------------
 // Parser: Quilt
 // ---------------------------------------------------------------------------
@@ -350,20 +368,23 @@ export async function analyzeModJar(jarPath, options) {
             // graceful fallback
         }
     }
+    const { declaredNestedJars, ...metadataRest } = metadata;
+    const nestedJars = collectNestedJars(entries, declaredNestedJars);
     return {
         loader,
         jarKind,
-        ...metadata,
-        ...(packagedAccessTransformers.length > 0 || metadata.accessTransformers
+        ...metadataRest,
+        ...(packagedAccessTransformers.length > 0 || metadataRest.accessTransformers
             ? {
                 accessTransformers: [...new Set([
-                        ...(metadata.accessTransformers ?? []),
+                        ...(metadataRest.accessTransformers ?? []),
                         ...packagedAccessTransformers
                     ])]
             }
             : {}),
         classCount,
-        ...(classes !== undefined ? { classes } : {})
+        ...(classes !== undefined ? { classes } : {}),
+        ...(nestedJars.length > 0 ? { nestedJars } : {})
     };
 }
 //# sourceMappingURL=mod-analyzer.js.map

package/dist/source/artifact-resolver.d.ts

@@ -7,6 +7,8 @@ export type VersionSourceDiscovery = {
     candidateArtifacts: string[];
     selectedSourceJarPath?: string;
     selectedHasMinecraftNamespace?: boolean;
+    /** The other half of a Loom split-source pair (common/clientOnly), when present. */
+    companionSourceJarPaths?: string[];
 };
 type RuntimeJarCandidate = {
     jarPath: string;