@adhisang/minecraft-modding-mcp 3.0.0 → 3.1.0

package/dist/entry-tools/manage-cache-service.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { PUBLIC_CACHE_KINDS } from "../cache-registry.js";
 import { createError, ERROR_CODES } from "../errors.js";
 import { buildIncludeSchema, detailSchema, executionModeSchema, positiveIntSchema } from "./entry-tool-schema.js";
-import { buildEntryToolResult } from "./response-contract.js";
+import { buildEntryToolResult, createNextAction, createSummarySubject } from "./response-contract.js";
 import { normalizeReadOnlyExecutionMode, requireNonEmptyObject, resolveDetail, resolveInclude } from "./request-normalizers.js";
 const nonEmptyString = z.string().trim().min(1);
 const INCLUDE_GROUPS = ["warnings", "cacheEntries", "paths", "owners", "health", "preview", "timings"];
@@ -22,9 +22,9 @@ export const manageCacheShape = {
     }).optional(),
     detail: detailSchema.optional(),
     include: buildIncludeSchema(INCLUDE_GROUPS),
-    limit: positiveIntSchema.optional(),
+    limit: positiveIntSchema.default(50),
     cursor: nonEmptyString.optional(),
-    executionMode: executionModeSchema.optional()
+    executionMode: executionModeSchema.default("preview")
 };
 export const manageCacheSchema = z.object(manageCacheShape);
 export class ManageCacheService {
@@ -37,6 +37,12 @@ export class ManageCacheService {
         const include = resolveInclude(input.include);
         const executionMode = normalizeReadOnlyExecutionMode(input.action, input.executionMode);
         const cacheKinds = input.cacheKinds?.length ? input.cacheKinds : [...PUBLIC_CACHE_KINDS];
+        const summarySubject = createSummarySubject({
+            action: input.action,
+            cacheKinds,
+            executionMode,
+            selector: input.selector
+        });
         if (executionMode === "apply" &&
             (input.action === "delete" || input.action === "prune" || input.action === "rebuild")) {
             requireNonEmptyObject(input.selector, `${input.action} apply requires a non-empty selector.`);
@@ -58,6 +64,7 @@ export class ManageCacheService {
                         summary: {
                             status: hasUnhealthyKinds ? "partial" : "ok",
                             headline: `Summarized ${cacheKinds.length} cache kind(s).`,
+                            subject: summarySubject,
                             counts: {
                                 entries: entryCount,
                                 bytes: totalBytes
@@ -100,6 +107,7 @@ export class ManageCacheService {
                         summary: {
                             status: hasUnhealthyEntries ? "partial" : "ok",
                             headline: `${input.action === "list" ? "Listed" : "Inspected"} ${page.entries.length} cache entr${page.entries.length === 1 ? "y" : "ies"}.`,
+                            subject: summarySubject,
                             counts: {
                                 entries: page.entries.length
                             }
@@ -137,6 +145,7 @@ export class ManageCacheService {
                         summary: {
                             status: output.unhealthyEntries > 0 ? "partial" : "ok",
                             headline: `Verified ${output.checkedEntries} cache entr${output.checkedEntries === 1 ? "y" : "ies"}.`,
+                            subject: summarySubject,
                             counts: {
                                 checkedEntries: output.checkedEntries,
                                 unhealthyEntries: output.unhealthyEntries
@@ -173,10 +182,23 @@ export class ManageCacheService {
                         summary: {
                             status: output.deletedEntries > 0 && executionMode === "apply" ? "changed" : "unchanged",
                             headline: `${executionMode === "apply" ? "Applied" : "Previewed"} ${input.action} across ${cacheKinds.length} cache kind(s).`,
+                            subject: summarySubject,
                             counts: {
                                 deletedEntries: output.deletedEntries,
                                 deletedBytes: output.deletedBytes
-                            }
+                            },
+                            ...(executionMode === "preview"
+                                ? {
+                                    nextActions: [
+                                        createNextAction("manage-cache", {
+                                            action: input.action,
+                                            cacheKinds,
+                                            executionMode: "apply",
+                                            selector: input.selector
+                                        })
+                                    ]
+                                }
+                                : {})
                         },
                         blocks: {
                             operation: {
@@ -204,9 +226,22 @@ export class ManageCacheService {
                         summary: {
                             status: output.rebuiltEntries > 0 && executionMode === "apply" ? "changed" : "unchanged",
                             headline: `${executionMode === "apply" ? "Applied" : "Previewed"} rebuild for ${cacheKinds.length} cache kind(s).`,
+                            subject: summarySubject,
                             counts: {
                                 rebuiltEntries: output.rebuiltEntries
-                            }
+                            },
+                            ...(executionMode === "preview"
+                                ? {
+                                    nextActions: [
+                                        createNextAction("manage-cache", {
+                                            action: "rebuild",
+                                            cacheKinds,
+                                            executionMode: "apply",
+                                            selector: input.selector
+                                        })
+                                    ]
+                                }
+                                : {})
                         },
                         blocks: {
                             operation: {

package/dist/entry-tools/response-contract.d.ts

@@ -23,6 +23,7 @@ export type TruncationMeta = {
 };
 export declare function normalizeIncludeGroups(include: readonly string[] | undefined): string[];
 export declare function createNextAction(tool: string, params: Record<string, unknown>): NextAction;
+export declare function createSummarySubject(fields: Record<string, unknown>): Record<string, unknown>;
 export declare function createTruncationMeta(input: {
     omittedGroups?: string[];
     nextActions?: NextAction[];

package/dist/entry-tools/response-contract.js

@@ -57,6 +57,9 @@ export function normalizeIncludeGroups(include) {
 export function createNextAction(tool, params) {
     return { tool, params };
 }
+export function createSummarySubject(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
 export function createTruncationMeta(input) {
     return {
         didTruncate: true,

package/dist/entry-tools/validate-project-service.d.ts

@@ -142,18 +142,18 @@ export declare const validateProjectShape: {
     sourcePriority: z.ZodOptional<z.ZodEnum<["loom-first", "maven-first"]>>;
     scope: z.ZodOptional<z.ZodEnum<["vanilla", "merged", "loader"]>>;
     preferProjectVersion: z.ZodOptional<z.ZodBoolean>;
-    preferProjectMapping: z.ZodOptional<z.ZodBoolean>;
+    preferProjectMapping: z.ZodDefault<z.ZodBoolean>;
     detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
     sourceRoots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     configPaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    minSeverity: z.ZodOptional<z.ZodEnum<["error", "warning", "all"]>>;
-    hideUncertain: z.ZodOptional<z.ZodBoolean>;
-    explain: z.ZodOptional<z.ZodBoolean>;
+    minSeverity: z.ZodDefault<z.ZodEnum<["error", "warning", "all"]>>;
+    hideUncertain: z.ZodDefault<z.ZodBoolean>;
+    explain: z.ZodDefault<z.ZodBoolean>;
     warningMode: z.ZodOptional<z.ZodEnum<["full", "aggregated"]>>;
     warningCategoryFilter: z.ZodOptional<z.ZodArray<z.ZodEnum<["mapping", "configuration", "validation", "resolution", "parse"]>, "many">>;
-    treatInfoAsWarning: z.ZodOptional<z.ZodBoolean>;
-    includeIssues: z.ZodOptional<z.ZodBoolean>;
+    treatInfoAsWarning: z.ZodDefault<z.ZodBoolean>;
+    includeIssues: z.ZodDefault<z.ZodBoolean>;
 };
 export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     task: z.ZodEnum<["project-summary", "mixin", "access-widener"]>;
@@ -298,19 +298,25 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     sourcePriority: z.ZodOptional<z.ZodEnum<["loom-first", "maven-first"]>>;
     scope: z.ZodOptional<z.ZodEnum<["vanilla", "merged", "loader"]>>;
     preferProjectVersion: z.ZodOptional<z.ZodBoolean>;
-    preferProjectMapping: z.ZodOptional<z.ZodBoolean>;
+    preferProjectMapping: z.ZodDefault<z.ZodBoolean>;
     detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
     sourceRoots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     configPaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    minSeverity: z.ZodOptional<z.ZodEnum<["error", "warning", "all"]>>;
-    hideUncertain: z.ZodOptional<z.ZodBoolean>;
-    explain: z.ZodOptional<z.ZodBoolean>;
+    minSeverity: z.ZodDefault<z.ZodEnum<["error", "warning", "all"]>>;
+    hideUncertain: z.ZodDefault<z.ZodBoolean>;
+    explain: z.ZodDefault<z.ZodBoolean>;
     warningMode: z.ZodOptional<z.ZodEnum<["full", "aggregated"]>>;
     warningCategoryFilter: z.ZodOptional<z.ZodArray<z.ZodEnum<["mapping", "configuration", "validation", "resolution", "parse"]>, "many">>;
-    treatInfoAsWarning: z.ZodOptional<z.ZodBoolean>;
-    includeIssues: z.ZodOptional<z.ZodBoolean>;
+    treatInfoAsWarning: z.ZodDefault<z.ZodBoolean>;
+    includeIssues: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
+    minSeverity: "all" | "error" | "warning";
+    hideUncertain: boolean;
+    explain: boolean;
+    preferProjectMapping: boolean;
+    treatInfoAsWarning: boolean;
+    includeIssues: boolean;
     task: "mixin" | "access-widener" | "project-summary";
     subject: {
         kind: "workspace";
@@ -350,14 +356,8 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     sourcePriority?: "loom-first" | "maven-first" | undefined;
     sourceRoots?: string[] | undefined;
     preferProjectVersion?: boolean | undefined;
-    minSeverity?: "all" | "error" | "warning" | undefined;
-    hideUncertain?: boolean | undefined;
-    explain?: boolean | undefined;
     warningMode?: "full" | "aggregated" | undefined;
-    preferProjectMapping?: boolean | undefined;
     warningCategoryFilter?: ("mapping" | "parse" | "validation" | "configuration" | "resolution")[] | undefined;
-    treatInfoAsWarning?: boolean | undefined;
-    includeIssues?: boolean | undefined;
     configPaths?: string[] | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
@@ -413,6 +413,12 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
 }>, {
+    minSeverity: "all" | "error" | "warning";
+    hideUncertain: boolean;
+    explain: boolean;
+    preferProjectMapping: boolean;
+    treatInfoAsWarning: boolean;
+    includeIssues: boolean;
     task: "mixin" | "access-widener" | "project-summary";
     subject: {
         kind: "workspace";
@@ -452,14 +458,8 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     sourcePriority?: "loom-first" | "maven-first" | undefined;
     sourceRoots?: string[] | undefined;
     preferProjectVersion?: boolean | undefined;
-    minSeverity?: "all" | "error" | "warning" | undefined;
-    hideUncertain?: boolean | undefined;
-    explain?: boolean | undefined;
     warningMode?: "full" | "aggregated" | undefined;
-    preferProjectMapping?: boolean | undefined;
     warningCategoryFilter?: ("mapping" | "parse" | "validation" | "configuration" | "resolution")[] | undefined;
-    treatInfoAsWarning?: boolean | undefined;
-    includeIssues?: boolean | undefined;
     configPaths?: string[] | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;

package/dist/entry-tools/validate-project-service.js

@@ -4,7 +4,7 @@ import fastGlob from "fast-glob";
 import { z } from "zod";
 import { createError, ERROR_CODES } from "../errors.js";
 import { buildIncludeSchema, detailSchema } from "./entry-tool-schema.js";
-import { buildEntryToolResult } from "./response-contract.js";
+import { buildEntryToolResult, createSummarySubject } from "./response-contract.js";
 import { resolveDetail, resolveInclude } from "./request-normalizers.js";
 const nonEmptyString = z.string().trim().min(1);
 const INCLUDE_GROUPS = ["warnings", "issues", "workspace", "recovery"];
@@ -42,18 +42,18 @@ export const validateProjectShape = {
     sourcePriority: z.enum(["loom-first", "maven-first"]).optional(),
     scope: z.enum(["vanilla", "merged", "loader"]).optional(),
     preferProjectVersion: z.boolean().optional(),
-    preferProjectMapping: z.boolean().optional(),
+    preferProjectMapping: z.boolean().default(false),
     detail: detailSchema.optional(),
     include: buildIncludeSchema(INCLUDE_GROUPS),
     sourceRoots: z.array(nonEmptyString).optional(),
     configPaths: z.array(nonEmptyString).optional(),
-    minSeverity: z.enum(["error", "warning", "all"]).optional(),
-    hideUncertain: z.boolean().optional(),
-    explain: z.boolean().optional(),
+    minSeverity: z.enum(["error", "warning", "all"]).default("all"),
+    hideUncertain: z.boolean().default(false),
+    explain: z.boolean().default(false),
     warningMode: z.enum(["full", "aggregated"]).optional(),
     warningCategoryFilter: z.array(z.enum(["mapping", "configuration", "validation", "resolution", "parse"])).optional(),
-    treatInfoAsWarning: z.boolean().optional(),
-    includeIssues: z.boolean().optional()
+    treatInfoAsWarning: z.boolean().default(true),
+    includeIssues: z.boolean().default(true)
 };
 export const validateProjectSchema = z.object(validateProjectShape).superRefine((value, ctx) => {
     if (value.task === "project-summary" && value.subject.kind !== "workspace") {
@@ -162,6 +162,15 @@ export class ValidateProjectService {
                         summary: {
                             status: invalidCount > 0 ? "invalid" : partialCount > 0 ? "partial" : "ok",
                             headline: `Validated ${summary?.total ?? 0} mixin input(s).`,
+                            subject: createSummarySubject({
+                                task: "mixin",
+                                kind: input.subject.kind,
+                                input: input.subject.input,
+                                version: input.version,
+                                mapping: input.mapping,
+                                sourcePriority: input.sourcePriority,
+                                scope: input.scope
+                            }),
                             counts: {
                                 valid: summary?.valid ?? 0,
                                 partial: partialCount,
@@ -205,6 +214,14 @@ export class ValidateProjectService {
                             headline: output.valid
                                 ? "Access Widener is valid."
                                 : "Access Widener contains validation issues.",
+                            subject: createSummarySubject({
+                                task: "access-widener",
+                                kind: input.subject.kind,
+                                input: input.subject.input,
+                                version: input.version,
+                                mapping: input.mapping,
+                                sourcePriority: input.sourcePriority
+                            }),
                             counts: {
                                 valid: output.valid ? 1 : 0,
                                 invalid: output.valid ? 0 : 1
@@ -241,6 +258,12 @@ export class ValidateProjectService {
                             summary: {
                                 status: "blocked",
                                 headline: "project-summary requires version or preferProjectVersion=true.",
+                                subject: createSummarySubject({
+                                    task: "project-summary",
+                                    kind: input.subject.kind,
+                                    projectPath: input.subject.projectPath,
+                                    discover: input.subject.discover
+                                }),
                                 nextActions: [
                                     {
                                         tool: "validate-project",
@@ -350,6 +373,16 @@ export class ValidateProjectService {
                         summary: {
                             status,
                             headline: `Validated ${mixinConfigs.length} mixin config(s) and ${accessWideners.length} access widener(s).`,
+                            subject: createSummarySubject({
+                                task: "project-summary",
+                                kind: input.subject.kind,
+                                projectPath,
+                                discover: input.subject.discover,
+                                version: input.version,
+                                mapping: input.mapping,
+                                sourcePriority: input.sourcePriority,
+                                scope: input.scope
+                            }),
                             counts: {
                                 valid: validMixins + validAw,
                                 partial: partialCount,

package/dist/index.js

@@ -90,9 +90,28 @@ 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 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 +121,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 +130,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 +163,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 +183,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 +216,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 +227,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 +246,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") {
@@ -294,7 +313,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 +364,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 +433,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 +497,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 +514,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 +553,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 +582,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 +597,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 +622,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"];
@@ -908,7 +927,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 +948,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 +970,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 +987,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 +1127,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;
         }
     }