@adhisang/minecraft-modding-mcp 3.0.0 → 3.1.1

package/dist/index.js

@@ -90,9 +90,32 @@ const sourceLookupTargetSchema = z.discriminatedUnion("type", [
 const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = "Object with kind and value. Example: {\"kind\":\"version\",\"value\":\"1.21.10\"}. Must be an object, not a string.";
 const SOURCE_LOOKUP_TARGET_DESCRIPTION = "Object: {\"type\":\"resolve\",\"kind\":\"version\",\"value\":\"1.21.10\"} or {\"type\":\"artifact\",\"artifactId\":\"...\"}. Must be an object, not a string.";
 const SOURCE_SCOPE_DESCRIPTION = 'vanilla = Mojang client jar only; merged = Loom cache discovery (default); loader = currently behaves the same as "merged".';
+const SUGGESTED_CALL_DEFAULTS = {
+    allowDecompile: true,
+    preferProjectVersion: false,
+    strictVersion: false,
+    mode: "metadata",
+    access: "public",
+    includeSynthetic: false,
+    includeInherited: false,
+    hideUncertain: false,
+    explain: false,
+    preferProjectMapping: false,
+    minSeverity: "all",
+    reportMode: "full",
+    treatInfoAsWarning: true,
+    includeIssues: true
+};
+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().optional().describe("default false"),
-    limit: optionalPositiveInt.describe("default 20, max 200")
+    includeSnapshots: z.boolean().default(false),
+    limit: optionalPositiveInt.default(20).describe("max 200")
 };
 const listVersionsSchema = z.object(listVersionsShape);
 const resolveArtifactShape = {
@@ -102,7 +125,7 @@ const resolveArtifactShape = {
     }).describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    allowDecompile: z.boolean().optional().describe("default true"),
+    allowDecompile: z.boolean().default(true),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
@@ -111,11 +134,11 @@ const resolveArtifactShape = {
 const resolveArtifactSchema = z.object(resolveArtifactShape);
 const getClassSourceShape = {
     className: nonEmptyString,
-    mode: sourceModeSchema.optional().describe("metadata (default) = symbol outline only; snippet = source with default maxLines=200; full = entire source"),
+    mode: sourceModeSchema.default("metadata").describe("metadata = symbol outline only; snippet = source with default maxLines=200; full = entire source"),
     target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    allowDecompile: z.boolean().optional().describe("default true"),
+    allowDecompile: z.boolean().default(true),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
@@ -144,10 +167,10 @@ const getClassMembersShape = {
     target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    allowDecompile: z.boolean().optional().describe("default true"),
-    access: memberAccessSchema.optional().describe("public | all (default public)"),
-    includeSynthetic: z.boolean().optional().describe("default false"),
-    includeInherited: z.boolean().optional().describe("default false"),
+    allowDecompile: z.boolean().default(true),
+    access: memberAccessSchema.default("public").describe("public | all"),
+    includeSynthetic: z.boolean().default(false),
+    includeInherited: z.boolean().default(false),
     memberPattern: optionalNonEmptyString,
     maxMembers: optionalPositiveInt.describe("default 500, max 5000"),
     projectPath: optionalNonEmptyString,
@@ -164,8 +187,8 @@ const searchClassSourceShape = {
     packagePrefix: optionalNonEmptyString,
     fileGlob: optionalNonEmptyString,
     symbolKind: searchSymbolKindSchema.optional().describe("class | interface | enum | record | method | field"),
-    queryMode: z.enum(["auto", "token", "literal"]).optional().describe("auto (default): FTS5 with literal fallback for separator queries; token: FTS5 only; literal: substring scan only"),
-    limit: optionalPositiveInt.describe("default 20"),
+    queryMode: z.enum(["auto", "token", "literal"]).default("auto").describe("auto: indexed search, including separator queries like foo.bar; token: indexed-only; literal: explicit substring scan only"),
+    limit: optionalPositiveInt.default(20),
     cursor: optionalNonEmptyString
 };
 const searchClassSourceSchema = z.object(searchClassSourceShape).superRefine((value, ctx) => {
@@ -197,9 +220,9 @@ const traceSymbolLifecycleShape = {
     toVersion: optionalNonEmptyString,
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    includeSnapshots: z.boolean().optional().describe("default false"),
-    maxVersions: optionalPositiveInt.describe("default 120, max 400"),
-    includeTimeline: z.boolean().optional().describe("default false")
+    includeSnapshots: z.boolean().default(false),
+    maxVersions: optionalPositiveInt.default(120).describe("max 400"),
+    includeTimeline: z.boolean().default(false)
 };
 const traceSymbolLifecycleSchema = z.object(traceSymbolLifecycleShape);
 const diffClassSignaturesShape = {
@@ -208,7 +231,7 @@ const diffClassSignaturesShape = {
     toVersion: nonEmptyString,
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    includeFullDiff: z.boolean().optional().describe("When false, omit from/to snapshots from modified entries and keep only key+changed")
+    includeFullDiff: z.boolean().default(true).describe("When false, omit from/to snapshots from modified entries and keep only key+changed")
 };
 const diffClassSignaturesSchema = z.object(diffClassSignaturesShape);
 const findMappingShape = {
@@ -227,7 +250,7 @@ const findMappingShape = {
     })
         .partial()
         .optional(),
-    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
 };
 const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -245,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.",
@@ -294,7 +317,7 @@ const resolveMethodMappingExactShape = {
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
 };
 const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
@@ -345,7 +368,7 @@ const resolveWorkspaceSymbolShape = {
     descriptor: optionalNonEmptyString,
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    maxCandidates: optionalPositiveInt.describe("Limit returned candidates for field/method lookups (default 200, max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates for field/method lookups (max 200)")
 };
 const resolveWorkspaceSymbolSchema = z
     .object(resolveWorkspaceSymbolShape)
@@ -414,10 +437,10 @@ const checkSymbolExistsShape = {
     descriptor: optionalNonEmptyString.describe("required for kind=method unless signatureMode=name-only"),
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    nameMode: classNameModeSchema.optional().describe("fqcn | auto (default fqcn)"),
-    signatureMode: z.enum(["exact", "name-only"]).optional()
-        .describe("exact (default): require descriptor for methods; name-only: match by owner+name only"),
-    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
+    nameMode: classNameModeSchema.default("fqcn").describe("fqcn | auto"),
+    signatureMode: z.enum(["exact", "name-only"]).default("exact")
+        .describe("exact: require descriptor for methods; name-only: match by owner+name only"),
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
 };
 const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -478,7 +501,7 @@ const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((va
 });
 const nbtToJsonShape = {
     nbtBase64: nonEmptyString,
-    compression: decodeCompressionSchema.optional().describe("none | gzip | auto (default auto)")
+    compression: decodeCompressionSchema.default("auto").describe("none | gzip | auto")
 };
 const nbtToJsonSchema = z.object(nbtToJsonShape);
 const nbtPatchOperationSchema = z
@@ -495,12 +518,12 @@ const nbtApplyJsonPatchShape = {
 const nbtApplyJsonPatchSchema = z.object(nbtApplyJsonPatchShape);
 const jsonToNbtShape = {
     typedJson: z.unknown(),
-    compression: encodeCompressionSchema.optional().describe("none | gzip (default none)")
+    compression: encodeCompressionSchema.default("none").describe("none | gzip")
 };
 const jsonToNbtSchema = z.object(jsonToNbtShape);
 const indexArtifactShape = {
     artifactId: nonEmptyString,
-    force: z.boolean().optional().describe("default false")
+    force: z.boolean().default(false)
 };
 const indexArtifactSchema = z.object(indexArtifactShape);
 const validateMixinShape = {
@@ -534,23 +557,23 @@ const validateMixinShape = {
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
-    minSeverity: z.enum(["error", "warning", "all"]).optional()
-        .describe("'error'=errors only, 'warning'=errors+warnings, 'all'=everything (default 'all')"),
-    hideUncertain: z.boolean().optional()
-        .describe("Omit issues with confidence='uncertain' (default false)"),
-    explain: z.boolean().optional()
-        .describe("When true, enrich each issue with explanation and suggestedCall for agent recovery (default false)"),
+    minSeverity: z.enum(["error", "warning", "all"]).default("all")
+        .describe("'error'=errors only, 'warning'=errors+warnings, 'all'=everything"),
+    hideUncertain: z.boolean().default(false)
+        .describe("Omit issues with confidence='uncertain'"),
+    explain: z.boolean().default(false)
+        .describe("When true, enrich each issue with explanation and suggestedCall for agent recovery"),
     warningMode: z.enum(["full", "aggregated"]).optional()
-        .describe("'full'=all warnings (default), 'aggregated'=group warnings by category with counts and samples"),
-    preferProjectMapping: z.boolean().optional()
+        .describe("'full'=all warnings; 'aggregated'=group warnings by category with counts and samples. Single validation uses the provided value as-is; batch validation defaults to 'aggregated'"),
+    preferProjectMapping: z.boolean().default(false)
         .describe("When true, auto-detect mapping from project config even if mapping is explicitly provided"),
-    reportMode: z.enum(["compact", "full", "summary-first"]).optional()
-        .describe("'compact' omits heavy per-result detail, 'summary-first' hoists shared provenance/warnings/incomplete reasons, 'full'=everything (default)"),
+    reportMode: z.enum(["compact", "full", "summary-first"]).default("full")
+        .describe("'compact' omits heavy per-result detail, 'summary-first' hoists shared provenance/warnings/incomplete reasons, 'full'=everything"),
     warningCategoryFilter: z.array(z.enum(["mapping", "configuration", "validation", "resolution", "parse"])).optional()
         .describe("Only include warnings/issues matching these categories (default: all)"),
-    treatInfoAsWarning: z.boolean().optional()
-        .describe("When false, suppress info-severity structured warnings from output (default true)"),
-    includeIssues: z.boolean().optional()
+    treatInfoAsWarning: z.boolean().default(true)
+        .describe("When false, suppress info-severity structured warnings from output"),
+    includeIssues: z.boolean().default(true)
         .describe("When false, keep summary fields but omit per-result issues[] payloads")
 };
 const validateMixinSchema = z.object(validateMixinShape);
@@ -563,13 +586,13 @@ const validateAccessWidenerShape = {
 const validateAccessWidenerSchema = z.object(validateAccessWidenerShape);
 const analyzeModJarShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
-    includeClasses: z.boolean().optional().describe("Include full class listing (default false)")
+    includeClasses: z.boolean().default(false).describe("Include full class listing")
 };
 const analyzeModJarSchema = z.object(analyzeModJarShape);
 const getRegistryDataShape = {
     version: nonEmptyString.describe("Minecraft version (e.g. 1.21)"),
     registry: optionalNonEmptyString.describe('Optional registry name (e.g. "block", "item", "minecraft:biome"). Omit to list all registries.'),
-    includeData: z.boolean().optional().describe("When false, return registry names/counts without full entry bodies"),
+    includeData: z.boolean().default(true).describe("When false, return registry names/counts without full entry bodies"),
     maxEntriesPerRegistry: optionalPositiveInt.describe("Limit returned entries per registry body")
 };
 const getRegistryDataSchema = z.object(getRegistryDataShape);
@@ -578,15 +601,15 @@ const compareVersionsCategorySchema = z.enum(COMPARE_VERSIONS_CATEGORIES);
 const compareVersionsShape = {
     fromVersion: nonEmptyString.describe("Older Minecraft version (e.g. 1.20.4)"),
     toVersion: nonEmptyString.describe("Newer Minecraft version (e.g. 1.21)"),
-    category: compareVersionsCategorySchema.optional().describe("classes | registry | all (default all)"),
+    category: compareVersionsCategorySchema.default("all").describe("classes | registry | all"),
     packageFilter: optionalNonEmptyString.describe("Filter classes to a package prefix (e.g. net.minecraft.world.item)"),
-    maxClassResults: optionalPositiveInt.describe("Max class results per direction (default 500, max 5000)")
+    maxClassResults: optionalPositiveInt.default(500).describe("Max class results per direction (max 5000)")
 };
 const compareVersionsSchema = z.object(compareVersionsShape);
 const decompileModJarShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
     className: optionalNonEmptyString.describe("Optional fully-qualified class name to view source. Omit to list all classes."),
-    includeFiles: z.boolean().optional().describe("When false, omit the full class list and return counts only"),
+    includeFiles: z.boolean().default(true).describe("When false, omit the full class list and return counts only"),
     maxFiles: optionalPositiveInt.describe("Limit returned class names when files are included")
 };
 const decompileModJarSchema = z.object(decompileModJarShape);
@@ -603,8 +626,8 @@ const modSearchTypeSchema = z.enum(MOD_SEARCH_TYPES);
 const searchModSourceShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
     query: nonEmptyString.describe("Search pattern (regex or literal string)"),
-    searchType: modSearchTypeSchema.optional().describe("class | method | field | content | all (default all)"),
-    limit: optionalPositiveInt.describe("Max results (default 50, max 200)")
+    searchType: modSearchTypeSchema.default("all").describe("class | method | field | content | all"),
+    limit: optionalPositiveInt.default(50).describe("Max results (max 200)")
 };
 const searchModSourceSchema = z.object(searchModSourceShape);
 const REMAP_TARGETS = ["yarn", "mojang"];
@@ -661,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),
@@ -908,7 +932,10 @@ function copySourceLookupSuggestionFields(tool, source) {
         : ["className", "mapping", "sourcePriority", "projectPath", "scope", "access", "memberPattern"];
     for (const field of stringFields) {
         const value = source[field];
-        if (typeof value === "string" && value.trim()) {
+        if (typeof value === "string" &&
+            value.trim() &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }
     }
@@ -926,7 +953,9 @@ function copySourceLookupSuggestionFields(tool, source) {
         : ["allowDecompile", "preferProjectVersion", "strictVersion", "includeSynthetic", "includeInherited"];
     for (const field of booleanFields) {
         const value = source[field];
-        if (typeof value === "boolean") {
+        if (typeof value === "boolean" &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }
     }
@@ -946,7 +975,10 @@ function copyValidateMixinSharedParams(source) {
     ];
     for (const field of stringFields) {
         const value = source[field];
-        if (typeof value === "string" && value.trim()) {
+        if (typeof value === "string" &&
+            value.trim() &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }
     }
@@ -960,7 +992,9 @@ function copyValidateMixinSharedParams(source) {
     ];
     for (const field of booleanFields) {
         const value = source[field];
-        if (typeof value === "boolean") {
+        if (typeof value === "boolean" &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }
     }
@@ -1098,7 +1132,8 @@ function buildResolveArtifactSuggestedParams(normalizedInput) {
     const booleanFields = ["allowDecompile", "preferProjectVersion", "strictVersion"];
     for (const field of booleanFields) {
         const value = record[field];
-        if (typeof value === "boolean") {
+        if (typeof value === "boolean" &&
+            !isSuggestedCallDefault(field, value)) {
             result[field] = value;
         }
     }
@@ -1124,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 = [
@@ -1163,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.