@adhisang/minecraft-modding-mcp 6.1.1 → 6.3.0

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;

package/dist/source/artifact-resolver.js

@@ -206,13 +206,32 @@ export async function discoverVersionSourceJar(_svc, input) {
     const candidateArtifacts = candidates
         .slice(0, 20)
         .map((candidate) => `${candidate.jarPath}#java=${candidate.javaEntryCount}#net_minecraft=${candidate.hasMinecraftNamespace ? 1 : 0}`);
+    // Loom split-source workspaces publish the version as a common/clientOnly
+    // PAIR with no merged jar; selecting one loses the other half's classes
+    // (e.g. net.minecraft.client.* when common wins). Surface the best-scored
+    // jar of the other half so ingestion can index both.
+    const selectedHalf = selected ? splitSourceHalf(selected.jarPath) : undefined;
+    const companion = selectedHalf
+        ? candidates.find((candidate) => candidate !== selected &&
+            candidate.looksLikeMinecraftArtifact &&
+            splitSourceHalf(candidate.jarPath) !== undefined &&
+            splitSourceHalf(candidate.jarPath) !== selectedHalf &&
+            // Version affinity: a leftover other-half jar from a different
+            // version must never be spliced into this version's index.
+            hasExactVersionToken(candidate.jarPath, input.version))
+        : undefined;
     return {
         searchedPaths,
         candidateArtifacts,
         selectedSourceJarPath: selected?.jarPath,
-        selectedHasMinecraftNamespace: selected?.hasMinecraftNamespace
+        selectedHasMinecraftNamespace: selected?.hasMinecraftNamespace,
+        ...(companion ? { companionSourceJarPaths: [companion.jarPath] } : {})
     };
 }
+function splitSourceHalf(jarPath) {
+    const match = /minecraft-(common|clientonly)/i.exec(jarPath);
+    return match ? match[1].toLowerCase() : undefined;
+}
 export async function probeMinecraftArtifact(svc, input) {
     let value = input.target.value.trim();
     const warnings = [];
@@ -1171,6 +1190,10 @@ export async function resolveArtifact(svc, input) {
         if (dependencyProvenance) {
             provenance.dependencyResolution = dependencyProvenance;
         }
+        if (versionSourceDiscovery?.companionSourceJarPaths?.length &&
+            resolved.sourceJarPath === versionSourceDiscovery.selectedSourceJarPath) {
+            provenance.companionSourceJars = versionSourceDiscovery.companionSourceJarPaths;
+        }
         if (dependencyOrigin && dependencyRequestedMapping && dependencyRequestedMapping !== "obfuscated") {
             const coord = resolved.coordinate ?? value;
             warnings.push(`Dependency artifact ${coord} mapping "${dependencyRequestedMapping}" is not enforced (binary remap is disabled for non-vanilla artifacts); the JAR is returned in its native namespace and mappingApplied is reported as "obfuscated" with qualityFlag "dependency-mapping-unverified". Caller must validate symbol availability.`);

package/dist/source/class-source/members-builder.d.ts

@@ -50,6 +50,10 @@ export type WireMember = {
     ownerFqn?: string;
     /** Present only when true. */
     isSynthetic?: boolean;
+    /** Rendered default value of an annotation-type member. */
+    annotationDefault?: string;
+    /** Runtime-visible annotations; present only under the opt-in projection. */
+    annotations?: string[];
 };
 export type WireMembersBlock = {
     /** Hoisted owner when every member shares one owner (the common, non-inherited case). */

package/dist/source/class-source/members-builder.js

@@ -82,7 +82,9 @@ export function projectMembersForWire(slice, includeInherited, keepFieldDescript
         javaSignature: m.javaSignature,
         ...(keepDescriptor ? { jvmDescriptor: m.jvmDescriptor } : {}),
         ...(hoistOwner ? {} : { ownerFqn: m.ownerFqn }),
-        ...(m.isSynthetic ? { isSynthetic: true } : {})
+        ...(m.isSynthetic ? { isSynthetic: true } : {}),
+        ...(m.annotationDefault !== undefined ? { annotationDefault: m.annotationDefault } : {}),
+        ...(m.annotations?.length ? { annotations: m.annotations } : {})
     });
     return {
         ...(hoistOwner ? { ownerFqn: [...owners][0] } : {}),

package/dist/source/class-source.d.ts

@@ -37,7 +37,7 @@ export declare function buildFallbackProvenance(svc: SourceService, input: {
     requestedMapping: SourceMapping;
     mappingApplied: SourceMapping;
 }): ArtifactProvenance;
-export declare function buildClassSourceNotFoundError(_svc: SourceService, input: {
+export declare function buildClassSourceNotFoundError(svc: SourceService, input: {
     className: string;
     lookupClassName: string;
     artifactId: string;
@@ -51,6 +51,7 @@ export declare function buildClassSourceNotFoundError(_svc: SourceService, input
     scope?: ArtifactScope;
     projectPath?: string;
     version?: string;
+    nestedJars?: string[];
 }): AppError;
 export declare function buildDecompiledFallback(svc: SourceService, artifactId: string, lookupClassName: string, memberPattern: string | undefined, maxMembers: number): {
     fallback: DecompiledFallback;
@@ -58,5 +59,6 @@ export declare function buildDecompiledFallback(svc: SourceService, artifactId:
     truncated: boolean;
 } | undefined;
 export declare function findClass(svc: SourceService, input: FindClassInput): FindClassOutput;
+export declare function findClassIncludingNested(svc: SourceService, input: FindClassInput): Promise<FindClassOutput>;
 export declare function getClassSource(svc: SourceService, input: GetClassSourceInput): Promise<GetClassSourceOutput>;
 export declare function getClassMembers(svc: SourceService, input: GetClassMembersInput): Promise<GetClassMembersOutput>;