@adhisang/minecraft-modding-mcp 3.1.0 → 3.1.1

package/dist/index.js

@@ -109,6 +109,10 @@ const SUGGESTED_CALL_DEFAULTS = {
 function isSuggestedCallDefault(field, value) {
     return value === SUGGESTED_CALL_DEFAULTS[field];
 }
+const ANALYZE_MOD_INCLUDE_GROUPS = ["warnings", "files", "source", "samples", "timings"];
+const ANALYZE_MOD_LEGACY_METADATA_INCLUDES = ["metadata", "entrypoints", "mixins", "dependencies"];
+const VALIDATE_PROJECT_INCLUDE_GROUPS = ["warnings", "issues", "workspace", "recovery"];
+const VALIDATE_PROJECT_LEGACY_WORKSPACE_INCLUDES = ["detectedConfig", "mixins", "accessWideners"];
 const listVersionsShape = {
     includeSnapshots: z.boolean().default(false),
     limit: optionalPositiveInt.default(20).describe("max 200")
@@ -264,7 +268,7 @@ const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) =>
                 path: ["descriptor"]
             });
         }
-        if (!value.name.includes(".")) {
+        if (value.sourceMapping !== "obfuscated" && !value.name.includes(".")) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 message: "name must be fully-qualified class name when kind=class.",
@@ -680,6 +684,7 @@ const inspectMinecraftService = new InspectMinecraftService({
     listVersions: (input) => sourceService.listVersions(input),
     resolveArtifact: (input) => sourceService.resolveArtifact(input),
     findClass: (input) => Promise.resolve(sourceService.findClass(input)),
+    checkSymbolExists: (input) => sourceService.checkSymbolExists(input),
     getClassSource: (input) => sourceService.getClassSource(input),
     getClassMembers: (input) => sourceService.getClassMembers(input),
     searchClassSource: (input) => sourceService.searchClassSource(input),
@@ -1154,6 +1159,184 @@ function buildSourceLookupSuggestedParams(tool, normalizedInput) {
     }
     return result;
 }
+function filterAllowedIncludeValues(values, allowed) {
+    if (!values?.length) {
+        return [];
+    }
+    const allowedSet = new Set(allowed);
+    const filtered = values.filter((value) => allowedSet.has(value));
+    return [...new Set(filtered)];
+}
+function buildAnalyzeModSuggestedParams(normalizedInput) {
+    const record = asObjectRecord(normalizedInput);
+    if (!record) {
+        return {
+            task: "summary",
+            detail: "standard",
+            subject: {
+                kind: "jar",
+                jarPath: "<mod-jar-path>"
+            }
+        };
+    }
+    const task = asNonEmptyString(record.task) ?? "summary";
+    const result = { task };
+    const subjectRecord = asObjectRecord(record.subject);
+    const include = asStringArray(record.include);
+    const canonicalInclude = filterAllowedIncludeValues(include, ANALYZE_MOD_INCLUDE_GROUPS);
+    const wantsLegacyMetadata = include?.some((value) => ANALYZE_MOD_LEGACY_METADATA_INCLUDES.includes(value)) ?? false;
+    const detail = asNonEmptyString(record.detail);
+    if (task === "summary" && wantsLegacyMetadata) {
+        result.detail = detail && detail !== "summary" ? detail : "standard";
+    }
+    else if (detail && detail !== "summary") {
+        result.detail = detail;
+    }
+    if (canonicalInclude.length > 0) {
+        result.include = canonicalInclude;
+    }
+    if (task === "class-source") {
+        result.subject = {
+            kind: "class",
+            jarPath: asNonEmptyString(subjectRecord?.jarPath) ?? asNonEmptyString(record.subject) ?? "<mod-jar-path>",
+            className: asNonEmptyString(subjectRecord?.className) ?? asNonEmptyString(record.className) ?? "<fully-qualified-class-name>"
+        };
+    }
+    else {
+        result.subject = {
+            kind: "jar",
+            jarPath: asNonEmptyString(subjectRecord?.jarPath) ?? asNonEmptyString(record.subject) ?? asNonEmptyString(record.jarPath) ?? "<mod-jar-path>"
+        };
+    }
+    const stringFields = ["query", "searchType", "targetMapping", "outputJar", "executionMode"];
+    for (const field of stringFields) {
+        const value = record[field];
+        if (typeof value === "string" && value.trim()) {
+            result[field] = value;
+        }
+    }
+    const booleanFields = ["includeFiles"];
+    for (const field of booleanFields) {
+        const value = record[field];
+        if (typeof value === "boolean") {
+            result[field] = value;
+        }
+    }
+    const numericFields = ["limit", "maxFiles", "maxLines", "maxChars"];
+    for (const field of numericFields) {
+        const value = record[field];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            result[field] = value;
+        }
+    }
+    return result;
+}
+function buildValidateProjectSuggestedParams(normalizedInput) {
+    const record = asObjectRecord(normalizedInput);
+    if (!record) {
+        return {
+            task: "project-summary",
+            subject: {
+                kind: "workspace",
+                projectPath: "<workspace-path>"
+            },
+            preferProjectVersion: true
+        };
+    }
+    const task = asNonEmptyString(record.task) ?? "project-summary";
+    const result = { task };
+    const subjectRecord = asObjectRecord(record.subject);
+    const include = asStringArray(record.include);
+    const canonicalInclude = filterAllowedIncludeValues(include, VALIDATE_PROJECT_INCLUDE_GROUPS);
+    const wantsWorkspaceInclude = include?.some((value) => VALIDATE_PROJECT_LEGACY_WORKSPACE_INCLUDES.includes(value)) ?? false;
+    const detail = asNonEmptyString(record.detail);
+    if (detail && detail !== "summary") {
+        result.detail = detail;
+    }
+    const includeSuggestion = wantsWorkspaceInclude
+        ? [...new Set([...canonicalInclude, "workspace"])]
+        : canonicalInclude;
+    if (includeSuggestion.length > 0) {
+        result.include = includeSuggestion;
+    }
+    const stringFields = [
+        "version",
+        "mapping",
+        "sourcePriority",
+        "scope",
+        "minSeverity",
+        "warningMode"
+    ];
+    for (const field of stringFields) {
+        const value = record[field];
+        if (typeof value === "string" && value.trim()) {
+            result[field] = value;
+        }
+    }
+    const booleanFields = [
+        "preferProjectVersion",
+        "preferProjectMapping",
+        "hideUncertain",
+        "explain",
+        "treatInfoAsWarning",
+        "includeIssues"
+    ];
+    for (const field of booleanFields) {
+        const value = record[field];
+        if (typeof value === "boolean" &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
+            result[field] = value;
+        }
+    }
+    const sourceRoots = asStringArray(record.sourceRoots);
+    if (sourceRoots?.length) {
+        result.sourceRoots = sourceRoots;
+    }
+    const configPaths = asStringArray(record.configPaths);
+    if (configPaths?.length) {
+        result.configPaths = configPaths;
+    }
+    const warningCategoryFilter = asStringArray(record.warningCategoryFilter);
+    if (warningCategoryFilter?.length) {
+        result.warningCategoryFilter = warningCategoryFilter;
+    }
+    if (task === "project-summary") {
+        const subject = {
+            kind: "workspace",
+            projectPath: asNonEmptyString(subjectRecord?.projectPath) ??
+                asNonEmptyString(record.subject) ??
+                asNonEmptyString(record.projectPath) ??
+                "<workspace-path>"
+        };
+        const discover = asStringArray(subjectRecord?.discover);
+        if (discover?.length) {
+            subject.discover = discover;
+        }
+        result.subject = subject;
+        return result;
+    }
+    if (task === "mixin") {
+        const inputRecord = asObjectRecord(subjectRecord?.input) ?? asObjectRecord(record.input);
+        result.subject = {
+            kind: "mixin",
+            input: inputRecord ?? {
+                mode: "inline",
+                source: "<Mixin Java source>"
+            }
+        };
+        return result;
+    }
+    const inputRecord = asObjectRecord(subjectRecord?.input) ?? asObjectRecord(record.input);
+    result.subject = {
+        kind: "access-widener",
+        input: inputRecord ?? {
+            mode: "inline",
+            content: "<access widener contents>"
+        }
+    };
+    return result;
+}
 function buildInvalidInputGuidance(tool, normalizedInput) {
     if (tool === "validate-mixin") {
         const hints = [
@@ -1193,6 +1376,32 @@ function buildInvalidInputGuidance(tool, normalizedInput) {
             }
         };
     }
+    if (tool === "validate-project") {
+        return {
+            hints: [
+                "validate-project.subject must be an object with subject.kind=workspace|mixin|access-widener.",
+                "task=\"project-summary\" uses {\"subject\":{\"kind\":\"workspace\",\"projectPath\":\"/workspace\"}}.",
+                "Legacy include names like projectSummary/detectedConfig/validationSummary are not accepted; use include:[\"workspace\"] only when you need discovery details."
+            ],
+            suggestedCall: {
+                tool,
+                params: buildValidateProjectSuggestedParams(normalizedInput)
+            }
+        };
+    }
+    if (tool === "analyze-mod") {
+        return {
+            hints: [
+                "analyze-mod.subject must be an object with subject.kind=jar|class.",
+                "task=\"summary\" uses {\"subject\":{\"kind\":\"jar\",\"jarPath\":\"/path/to/mod.jar\"}}.",
+                "Legacy include names like metadata/entrypoints/mixins/dependencies are not accepted; use detail=\"standard\" to surface the metadata block, and canonical include groups only for warnings/files/source/samples/timings."
+            ],
+            suggestedCall: {
+                tool,
+                params: buildAnalyzeModSuggestedParams(normalizedInput)
+            }
+        };
+    }
     return undefined;
 }
 function mapErrorToProblem(caughtError, requestId, context) {

package/dist/mapping-service.d.ts

@@ -177,6 +177,7 @@ export declare class MappingService {
     private parseTinyFromJar;
     private fetchYarnCoordinates;
     private trimGraphCache;
+    releaseGraphCacheEntry(version: string, sourcePriority?: MappingSourcePriority): void;
 }
 /**
  * Resolve and cache a Tiny v2 mapping file for the given Minecraft version.

package/dist/mapping-service.js

@@ -420,7 +420,7 @@ function parseClientMappings(text) {
 }
 function normalizeTinyNamespace(namespace) {
     const normalized = namespace.trim().toLowerCase();
-    if (normalized === "obfuscated") {
+    if (normalized === "obfuscated" || normalized === "official") {
         return "obfuscated";
     }
     if (normalized === "mojang") {
@@ -590,6 +590,12 @@ function mappingSourceOrder(priority) {
     }
     return ["loom-cache", "maven"];
 }
+function requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) {
+    return sourceMapping !== "intermediary" &&
+        sourceMapping !== "yarn" &&
+        targetMapping !== "intermediary" &&
+        targetMapping !== "yarn";
+}
 function namespacePath(graph, sourceMapping, targetMapping) {
     if (sourceMapping === targetMapping) {
         return [sourceMapping];
@@ -709,7 +715,7 @@ function normalizeMethodDescriptor(descriptor) {
     }
     return normalized;
 }
-function normalizeQuerySymbol(input, signatureMode) {
+function normalizeQuerySymbol(input, signatureMode, options) {
     if (input.kind !== "class" && input.kind !== "field" && input.kind !== "method") {
         throw invalidInputError('kind must be one of "class", "field", or "method".', {
             kind: input.kind
@@ -735,7 +741,7 @@ function normalizeQuerySymbol(input, signatureMode) {
             });
         }
         const className = normalizeMappedSymbolOutput(normalizedName);
-        if (!className.includes(".")) {
+        if (!className.includes(".") && !options?.allowShortClassName) {
             throw invalidInputError("name must be a fully qualified class name when kind=class.", {
                 name: input.name
             });
@@ -905,7 +911,9 @@ export class MappingService {
                 }
             });
         }
-        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode);
+        const { record: queryRecord, querySymbol } = normalizeQuerySymbol(input, input.signatureMode, {
+            allowShortClassName: input.kind === "class" && input.sourceMapping === "obfuscated"
+        });
         const sourceMapping = input.sourceMapping;
         const targetMapping = input.targetMapping;
         if (!SUPPORTED_MAPPINGS.has(sourceMapping) || !SUPPORTED_MAPPINGS.has(targetMapping)) {
@@ -945,7 +953,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -1029,7 +1037,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             throw createError({
@@ -1113,7 +1121,7 @@ export class MappingService {
                 warnings: []
             };
         }
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full");
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -1214,7 +1222,7 @@ export class MappingService {
             });
         }
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, "full");
         const warnings = [...graph.warnings];
         const includeKinds = normalizeIncludedKinds(input.includeKinds);
         const pathCache = new Map();
@@ -1246,7 +1254,7 @@ export class MappingService {
                 classByMapping[mapping] = mapped[0];
             }
         }
-        const baseMapping = classByMapping.obfuscated ? "obfuscated" : classNameMapping;
+        const baseMapping = classNameMapping;
         const baseClass = classByMapping[baseMapping];
         if (!baseClass) {
             return {
@@ -1435,7 +1443,7 @@ export class MappingService {
                     querySymbol
                 };
             })();
-        const graph = await this.loadGraph(version, priority);
+        const graph = await this.loadGraph(version, priority, sourceMapping === "mojang" ? "obfuscated-mojang-only" : "full");
         const warnings = [...graph.warnings];
         const records = collectTargetRecords(graph, sourceMapping);
         if (records.length === 0) {
@@ -1640,7 +1648,7 @@ export class MappingService {
         const degradations = [];
         let graph;
         try {
-            graph = await this.loadGraph(input.version, priority);
+            graph = await this.loadGraph(input.version, priority, "full");
         }
         catch {
             return {
@@ -1684,8 +1692,8 @@ export class MappingService {
             degradations
         };
     }
-    async loadGraph(version, priority) {
-        const cacheKey = `${version}|${priority}`;
+    async loadGraph(version, priority, mode) {
+        const cacheKey = `${version}|${priority}|${mode}`;
         const cached = this.graphCache.get(cacheKey);
         if (cached) {
             this.graphCache.delete(cacheKey);
@@ -1696,7 +1704,7 @@ export class MappingService {
         if (existingLock) {
             return existingLock;
         }
-        const buildPromise = this.buildGraph(version, priority);
+        const buildPromise = this.buildGraph(version, priority, mode);
         this.buildLocks.set(cacheKey, buildPromise);
         try {
             const built = await buildPromise;
@@ -1708,11 +1716,12 @@ export class MappingService {
             this.buildLocks.delete(cacheKey);
         }
     }
-    async buildGraph(version, priority) {
+    async buildGraph(version, priority, mode) {
         if (isUnobfuscatedVersion(version)) {
             return {
                 version,
                 priority,
+                mode,
                 pairs: new Map(),
                 adjacency: new Map(),
                 pathCache: new Map(),
@@ -1725,6 +1734,7 @@ export class MappingService {
         const graph = {
             version,
             priority,
+            mode,
             pairs: new Map(),
             adjacency: new Map(),
             pathCache: new Map(),
@@ -1734,27 +1744,29 @@ export class MappingService {
         const mojangLoad = await this.loadMojangPairs(version);
         graph.warnings.push(...mojangLoad.warnings);
         this.mergePairs(graph.pairs, mojangLoad.pairs, "mojang-client-mappings", mojangLoad.mappingArtifact);
-        let tinyLoaded = false;
-        const deferredTinyWarnings = [];
-        for (const source of mappingSourceOrder(priority)) {
-            const tinyLoad = source === "loom-cache"
-                ? await this.loadTinyPairsFromLoom(version)
-                : await this.loadTinyPairsFromMaven(version);
-            if (tinyLoad.pairs.size === 0) {
-                deferredTinyWarnings.push(...tinyLoad.warnings);
-                continue;
+        if (mode === "full") {
+            let tinyLoaded = false;
+            const deferredTinyWarnings = [];
+            for (const source of mappingSourceOrder(priority)) {
+                const tinyLoad = source === "loom-cache"
+                    ? await this.loadTinyPairsFromLoom(version)
+                    : await this.loadTinyPairsFromMaven(version);
+                if (tinyLoad.pairs.size === 0) {
+                    deferredTinyWarnings.push(...tinyLoad.warnings);
+                    continue;
+                }
+                tinyLoaded = true;
+                this.mergePairs(graph.pairs, tinyLoad.pairs, source, tinyLoad.mappingArtifact);
+                graph.warnings.push(...tinyLoad.warnings);
+                if (deferredTinyWarnings.length > 0) {
+                    graph.warnings.push(`Used ${source === "maven" ? "Maven" : "Loom cache"} tiny mappings for "${version}" after an earlier source lookup returned no data.`);
+                }
+                break;
             }
-            tinyLoaded = true;
-            this.mergePairs(graph.pairs, tinyLoad.pairs, source, tinyLoad.mappingArtifact);
-            graph.warnings.push(...tinyLoad.warnings);
-            if (deferredTinyWarnings.length > 0) {
-                graph.warnings.push(`Used ${source === "maven" ? "Maven" : "Loom cache"} tiny mappings for "${version}" after an earlier source lookup returned no data.`);
+            if (!tinyLoaded) {
+                graph.warnings.push(...deferredTinyWarnings);
+                graph.warnings.push("No intermediary/yarn tiny mappings were found for this version.");
             }
-            break;
-        }
-        if (!tinyLoaded) {
-            graph.warnings.push(...deferredTinyWarnings);
-            graph.warnings.push("No intermediary/yarn tiny mappings were found for this version.");
         }
         graph.adjacency = buildAdjacency(graph.pairs);
         graph.recordsByTarget = buildTargetRecordIndex(graph.pairs);
@@ -1990,6 +2002,15 @@ export class MappingService {
             this.graphCache.delete(oldestKey);
         }
     }
+    releaseGraphCacheEntry(version, sourcePriority) {
+        const normalizedVersion = version.trim();
+        if (!normalizedVersion) {
+            return;
+        }
+        const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, sourcePriority);
+        this.graphCache.delete(`${normalizedVersion}|${priority}|full`);
+        this.graphCache.delete(`${normalizedVersion}|${priority}|obfuscated-mojang-only`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Standalone: Tiny v2 mapping file resolution for remapping

package/dist/source-service.d.ts

@@ -497,6 +497,8 @@ export declare class SourceService {
     private buildFallbackProvenance;
     private resolveClassNameForLookup;
     private buildClassSourceNotFoundError;
+    private rejectLifecycleClassLikeInput;
+    private releaseLifecycleMappingGraph;
     private resolveToObfuscatedClassName;
     private resolveToObfuscatedMemberName;
     private remapSignatureMembers;