@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/tool-schemas.js

@@ -1,5 +1,19 @@
-import { isAbsolute as pathIsAbsolute, resolve as pathResolve } from "node:path";
+import { resolve as pathResolve } from "node:path";
 import { z } from "zod";
+import { DETAIL_LEVELS, CANONICAL_INCLUDE_GROUPS } from "./entry-tools/response-contract.js";
+// Shared response-shape controls for the expert + batch tools (replacing the old
+// per-tool `compact` boolean). detail: summary|standard|full + include[] mirrors the
+// entry-tool contract. Defaults are per-tool (see DEFAULT_DETAIL_BY_TOOL in response-utils):
+// resolution/mapping tools + batch default "summary"; source/file tools default "standard".
+const DETAIL_DESCRIPTION = "summary = terse (drops diagnostics/empties, slims candidates); standard = keeps fields, drops heavy diagnostics; full = everything.";
+const RESPONSE_INCLUDE_DESCRIPTION = 'Field groups to include regardless of detail, e.g. ["provenance"].';
+function detailParam(defaultLevel) {
+    return z.enum(DETAIL_LEVELS).default(defaultLevel).describe(DETAIL_DESCRIPTION);
+}
+const responseIncludeParam = z
+    .array(z.enum(CANONICAL_INCLUDE_GROUPS))
+    .optional()
+    .describe(RESPONSE_INCLUDE_DESCRIPTION);
 export const SOURCE_MAPPINGS = ["obfuscated", "mojang", "intermediary", "yarn"];
 export const SOURCE_PRIORITIES = ["loom-first", "maven-first"];
 export const TARGET_KINDS = ["version", "jar", "coordinate"];
@@ -16,7 +30,7 @@ export const ENCODE_COMPRESSIONS = ["none", "gzip"];
 export const nonEmptyString = z.string().trim().min(1);
 export const optionalNonEmptyString = z.string().trim().min(1).optional();
 export const optionalPositiveInt = z.number().int().positive().optional();
-export const gradleUserHomeSchema = optionalNonEmptyString.describe("Gradle User Home to use for Loom/Gradle cache lookups instead of the MCP process GRADLE_USER_HOME.");
+export const gradleUserHomeSchema = optionalNonEmptyString.describe("Gradle user home for Loom cache lookups (overrides GRADLE_USER_HOME).");
 // Optional descriptor: "" and whitespace-only strings are normalized to undefined so that
 // tools with signatureMode="name-only" can accept "caller omitted descriptor" inputs whether
 // the caller passed an empty string or omitted the field entirely. Malformed descriptors are
@@ -62,32 +76,26 @@ export const resolveArtifactTargetSchema = z.discriminatedUnion("kind", [
     workspaceTargetSchema,
     dependencyTargetSchema
 ]);
-export const sourceLookupTargetSchema = z.union([
-    z.object({
-        type: z.literal("artifact"),
-        artifactId: nonEmptyString
-    }),
-    z.object({ type: z.literal("resolve"), kind: z.literal("version"), value: nonEmptyString }),
-    z.object({ type: z.literal("resolve"), kind: z.literal("jar"), value: nonEmptyString }),
-    z.object({ type: z.literal("resolve"), kind: z.literal("coordinate"), value: nonEmptyString }),
-    z.object({
-        type: z.literal("resolve"),
-        kind: z.literal("workspace"),
-        scope: artifactScopeSchema.optional(),
-        strict: z.boolean().optional()
-    }),
-    z.object({
-        type: z.literal("resolve"),
-        kind: z.literal("dependency"),
-        group: nonEmptyString,
-        name: nonEmptyString,
-        version: z.string().trim().min(1).optional(),
-        versionFromProject: z.boolean().optional()
-    })
+// Extended target schema for the source-lookup tools (get-class-source / get-class-members):
+// the same kind-based shape as resolveArtifactTargetSchema, PLUS a `kind:"artifact"` variant
+// that short-circuits resolution by reusing an already-resolved artifactId. The shared
+// resolveArtifactTargetSchema is intentionally NOT widened — the artifact kind has no
+// resolution meaning for resolve-artifact / verify-mixin-target / the batch tools.
+export const sourceLookupTargetSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("version"), value: nonEmptyString }),
+    z.object({ kind: z.literal("jar"), value: nonEmptyString }),
+    z.object({ kind: z.literal("coordinate"), value: nonEmptyString }),
+    workspaceTargetSchema,
+    dependencyTargetSchema,
+    z.object({ kind: z.literal("artifact"), artifactId: nonEmptyString })
 ]);
-export const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = 'Object with kind. Examples: {"kind":"version","value":"1.21.10"}, {"kind":"workspace"} (uses projectPath), or {"kind":"dependency","group":"dev.architectury","name":"architectury"}. Must be an object, not a string.';
-export const SOURCE_LOOKUP_TARGET_DESCRIPTION = 'Object: {"type":"resolve","kind":"version","value":"1.21.10"} or {"type":"resolve","kind":"workspace"} or {"type":"resolve","kind":"dependency","group":"...","name":"..."} or {"type":"artifact","artifactId":"..."}. Must be an object, not a string.';
-export const SOURCE_SCOPE_DESCRIPTION = "vanilla = Mojang client jar only; merged = source-oriented merged runtime discovery; loader = loader/runtime artifact discovery when the workspace exposes transformed runtime jars.";
+export const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = 'Object, not string. e.g. {"kind":"version","value":"1.21.10"}, {"kind":"workspace"}, {"kind":"dependency","group":"g","name":"n"}.';
+export const SOURCE_LOOKUP_TARGET_DESCRIPTION = 'Same shape as resolve-artifact target, plus {"kind":"artifact","artifactId":"..."} to reuse a resolved artifact. Object, not string.';
+export const SOURCE_SCOPE_DESCRIPTION = "vanilla = Mojang client jar only; merged = merged runtime discovery; loader = loader-transformed runtime jars.";
+// Shared describe() text reused by every symbol-lookup tool so the contract reads
+// identically on find-mapping and check-symbol-exists (and any future sibling).
+export const SIGNATURE_MODE_DESCRIPTION = "exact: descriptor required for kind=method; name-only (default): match by owner+name only.";
+export const NAME_MODE_DESCRIPTION = "auto (default): FQCN, or dotless name where allowed; fqcn: require FQCN.";
 export const listVersionsShape = {
     includeSnapshots: z.boolean().default(false),
     limit: optionalPositiveInt.default(20).describe("max 200")
@@ -95,37 +103,38 @@ export const listVersionsShape = {
 export const listVersionsSchema = z.object(listVersionsShape);
 export const resolveArtifactShape = {
     target: resolveArtifactTargetSchema.describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
-    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    mapping: sourceMappingSchema.optional(),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().default(true),
-    projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
+    projectPath: optionalNonEmptyString.describe("Workspace root for Loom cache-assisted resolution"),
     gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
-    strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
-    compact: z.boolean().default(true).describe("Return minimal fields (artifactId, origin, isDecompiled, version, requestedMapping, mappingApplied, qualityFlags). "
-        + "Omit provenance, artifactContents, sampleEntries, adjacentSourceCandidates, binaryJarPath, coordinate, repoUrl, resolvedSourceJarPath. "
-        + "Enabled by default; set to false for full output.")
+    preferProjectVersion: z.boolean().optional().describe("Detect MC version from gradle.properties and override target.value"),
+    strictVersion: z.boolean().optional().describe("Reject version-approximated results (default false)"),
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const resolveArtifactSchema = z.object(resolveArtifactShape);
 export const getClassSourceShape = {
     className: nonEmptyString,
     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"),
+    mapping: sourceMappingSchema.optional(),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().default(true),
-    projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
+    projectPath: optionalNonEmptyString.describe("Workspace root for Loom cache-assisted resolution"),
     gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
-    strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
+    preferProjectVersion: z.boolean().optional().describe("Detect MC version from gradle.properties and override target.value"),
+    strictVersion: z.boolean().optional().describe("Reject version-approximated results (default false)"),
     startLine: optionalPositiveInt,
     endLine: optionalPositiveInt,
     maxLines: optionalPositiveInt,
     maxChars: optionalPositiveInt.describe("Hard character limit on sourceText; truncates if exceeded"),
     outputFile: optionalNonEmptyString.describe("Write source to this file path and return metadata-only response"),
-    compact: z.boolean().default(false).describe("When true, strip debug metadata (provenance, artifactContents, qualityFlags) and empty fields from the response. Default false.")
+    detail: detailParam("standard"),
+    include: responseIncludeParam,
+    includeProvenance: z.boolean().default(false).describe('Alias for include:["provenance"] (diagnostic metadata). Default false.')
 };
 export const getClassSourceSchema = z
     .object(getClassSourceShape)
@@ -143,46 +152,51 @@ export const getClassSourceSchema = z
 export const getClassMembersShape = {
     className: nonEmptyString,
     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"),
+    mapping: sourceMappingSchema.optional().describe("default obfuscated"),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().default(true),
-    access: memberAccessSchema.default("public").describe("public | all"),
+    access: memberAccessSchema.default("public"),
     includeSynthetic: z.boolean().default(false),
     includeInherited: z.boolean().default(false),
     memberPattern: optionalNonEmptyString,
-    maxMembers: optionalPositiveInt.describe("default 500, max 5000"),
+    maxMembers: optionalPositiveInt.describe("default 150, max 5000. Page beyond the first 150 with cursor."),
+    cursor: optionalNonEmptyString.describe("nextCursor from the previous response."),
     projectPath: optionalNonEmptyString,
     gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
-    strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
-    compact: z.boolean().default(false).describe("When true, strip debug metadata (provenance, artifactContents, qualityFlags, context) and empty fields from the response. Default false.")
+    preferProjectVersion: z.boolean().optional().describe("Detect MC version from gradle.properties and override version"),
+    strictVersion: z.boolean().optional().describe("Reject version-approximated results (default false)"),
+    detail: detailParam("standard"),
+    include: responseIncludeParam,
+    includeProvenance: z.boolean().default(false).describe('Alias for include:["provenance"] (diagnostic metadata). Default false.'),
+    includeDescriptors: z.boolean().default(false).describe('Alias for include:["descriptors"]: also emit jvmDescriptor on FIELD members (method/constructor descriptors are always present). Default false.')
 };
 export const getClassMembersSchema = z.object(getClassMembersShape);
 export const verifyMixinTargetMemberSchema = z.discriminatedUnion("kind", [
     z.object({
         kind: z.literal("method"),
         name: nonEmptyString,
-        descriptor: z.string().trim().min(1).optional()
+        descriptor: optionalDescriptorString.describe('Optional JVM method descriptor, e.g. "()V". Empty/whitespace strings are treated as omitted.')
     }),
     z.object({
         kind: z.literal("field"),
         name: nonEmptyString,
-        descriptor: z.string().trim().min(1).optional()
+        descriptor: optionalDescriptorString.describe('Optional JVM field descriptor, e.g. "I". Empty/whitespace strings are treated as omitted.')
     })
 ]);
 export const verifyMixinTargetShape = {
-    owner: nonEmptyString.describe("Fully-qualified class name of the target owner (e.g. net.minecraft.world.entity.LivingEntity)."),
-    member: verifyMixinTargetMemberSchema.describe('Member to verify. Object with kind. Examples: {"kind":"method","name":"tick","descriptor":"()V"} or {"kind":"field","name":"airSupply"}.'),
-    mixinMemberName: optionalNonEmptyString.describe("Optional caller-authored mixin field/method name. Drives @Accessor (getXxx/setXxx) and @Invoker (invokeXxx/callXxx) advice when the target is private."),
-    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    owner: nonEmptyString.describe("Fully-qualified target owner class name."),
+    member: verifyMixinTargetMemberSchema.describe('e.g. {"kind":"method","name":"tick","descriptor":"()V"} or {"kind":"field","name":"airSupply"}.'),
+    mixinMemberName: optionalNonEmptyString.describe("Caller-authored mixin member name; drives @Accessor/@Invoker advice when the target is private."),
+    mapping: sourceMappingSchema.optional(),
+    autoRemap: z.boolean().optional().describe("Translate owner+member via find-mapping when mapping differs from the artifact namespace (requires a version-based target)."),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     projectPath: optionalNonEmptyString.describe("Workspace root path for target.kind=workspace and Loom cache assistance."),
     gradleUserHome: gradleUserHomeSchema,
     target: resolveArtifactTargetSchema.describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
-    strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false.")
+    preferProjectVersion: z.boolean().optional().describe("Detect MC version from gradle.properties and override target.value"),
+    strictVersion: z.boolean().optional().describe("Reject version-approximated results (default false)")
 };
 export const verifyMixinTargetSchema = z.object(verifyMixinTargetShape);
 export const batchSymbolKindSchema = z.enum(["class", "field", "method"]);
@@ -197,7 +211,7 @@ export const batchClassSourceEntrySchema = z.object({
 });
 export const batchClassSourceShape = {
     target: resolveArtifactTargetSchema.describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
-    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
+    mapping: sourceMappingSchema.optional(),
     sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().optional(),
     projectPath: optionalNonEmptyString,
@@ -207,7 +221,8 @@ export const batchClassSourceShape = {
     strictVersion: z.boolean().optional(),
     concurrency: z.number().int().min(1).max(8).optional().describe("1..8, default 4"),
     failFast: z.boolean().optional().describe("default false"),
-    compact: z.boolean().optional().describe("default true"),
+    detail: detailParam("summary"),
+    include: responseIncludeParam,
     entries: z
         .array(batchClassSourceEntrySchema)
         .min(1)
@@ -218,8 +233,8 @@ export const batchClassSourceSchema = z.object(batchClassSourceShape).superRefin
     // Per-entry `outputFile` is forwarded into the concurrently-dispatched
     // `getClassSource` calls; two entries resolving to the same physical file
     // would race on `writeFile`. Normalize via `path.resolve` so aliases like
-    // `out.java` / `./out.java` / `dir/../out.java` collide as expected,
-    // matching the writer's `isAbsolute(p) ? p : resolvePath(p)` rule.
+    // `out.java` / `./out.java` / `dir/../out.java` / `/tmp/dir/../out.java`
+    // collide as expected, covering relative and absolute spellings alike.
     const seen = new Map();
     for (let i = 0; i < value.entries.length; i += 1) {
         const entry = value.entries[i];
@@ -228,7 +243,7 @@ export const batchClassSourceSchema = z.object(batchClassSourceShape).superRefin
         const trimmed = entry.outputFile.trim();
         if (trimmed.length === 0)
             continue;
-        const canonical = pathIsAbsolute(trimmed) ? trimmed : pathResolve(trimmed);
+        const canonical = pathResolve(trimmed);
         const previous = seen.get(canonical);
         if (previous !== undefined) {
             ctx.addIssue({
@@ -262,14 +277,15 @@ export const batchClassMembersShape = {
     strictVersion: z.boolean().optional(),
     concurrency: z.number().int().min(1).max(8).optional(),
     failFast: z.boolean().optional(),
-    compact: z.boolean().optional(),
+    detail: detailParam("summary"),
+    include: responseIncludeParam,
     entries: z.array(batchClassMembersEntrySchema).min(1).max(50)
 };
 export const batchClassMembersSchema = z.object(batchClassMembersShape);
 export const batchSymbolExistsTargetSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("version"), value: nonEmptyString }),
     workspaceTargetSchema
-]).describe('Object with kind. Only kind="version" or kind="workspace" is accepted; dependency/jar/coordinate targets carry library versions, not Minecraft versions, and would corrupt the mapping query.');
+]).describe('Only kind="version" or kind="workspace"; other kinds carry library versions, not MC versions.');
 export const batchSymbolExistsEntrySchema = z.object({
     kind: batchSymbolKindSchema,
     name: nonEmptyString,
@@ -291,7 +307,8 @@ export const batchSymbolExistsShape = {
     strictVersion: z.boolean().optional(),
     concurrency: z.number().int().min(1).max(8).optional(),
     failFast: z.boolean().optional(),
-    compact: z.boolean().optional(),
+    detail: detailParam("summary"),
+    include: responseIncludeParam,
     entries: z.array(batchSymbolExistsEntrySchema).min(1).max(50)
 };
 export const batchSymbolExistsSchema = z.object(batchSymbolExistsShape);
@@ -315,31 +332,33 @@ export const batchMappingsEntrySchema = z
 })
     .strict();
 export const batchMappingsShape = {
-    version: nonEmptyString.describe("Minecraft version shared by every entry. Per-entry version is rejected; this batch shape is intentionally single-version."),
+    version: nonEmptyString.describe("Minecraft version shared by every entry (single-version batch)."),
     sourcePriority: mappingSourcePrioritySchema.optional(),
     projectPath: optionalNonEmptyString,
     gradleUserHome: gradleUserHomeSchema,
     concurrency: z.number().int().min(1).max(8).optional(),
     failFast: z.boolean().optional(),
-    compact: z.boolean().optional(),
+    detail: detailParam("summary"),
+    include: responseIncludeParam,
     entries: z.array(batchMappingsEntrySchema).min(1).max(50)
 };
 export const batchMappingsSchema = z.object(batchMappingsShape);
 export const searchClassSourceShape = {
     artifactId: nonEmptyString,
     query: nonEmptyString,
-    intent: searchIntentSchema.optional().describe("symbol | text | path"),
-    match: searchMatchSchema.optional().describe("exact | prefix | contains | regex"),
+    intent: searchIntentSchema.optional(),
+    match: searchMatchSchema.optional(),
     packagePrefix: optionalNonEmptyString,
     fileGlob: optionalNonEmptyString,
-    symbolKind: searchSymbolKindSchema.optional().describe("class | interface | enum | record | method | field"),
-    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"),
+    symbolKind: searchSymbolKindSchema.optional(),
+    queryMode: z.enum(["auto", "token", "literal"]).default("auto").describe("auto: indexed search incl. separator queries like foo.bar; token: indexed-only; literal: substring scan only"),
     limit: optionalPositiveInt.default(20),
     cursor: optionalNonEmptyString,
-    queryNamespace: sourceMappingSchema.optional().describe("Namespace of the query. When set and intent='symbol' with a fully-qualified class name, the query is translated through find-mapping before searching the artifact namespace. Ignored for text/path intents (warning surfaced)."),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first. Used only when queryNamespace triggers translation."),
+    queryNamespace: sourceMappingSchema.optional().describe("Query namespace; symbol-intent FQCN queries are translated via find-mapping first. Ignored for text/path intents."),
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("Used only when queryNamespace triggers translation."),
     gradleUserHome: gradleUserHomeSchema,
-    compact: z.boolean().default(false).describe("When true, strip the artifactContents summary and empty fields from the response. Default false.")
+    detail: detailParam("standard"),
+    include: responseIncludeParam
 };
 export const searchClassSourceSchema = z.object(searchClassSourceShape).superRefine((value, ctx) => {
     if (value.symbolKind && value.intent && value.intent !== "symbol") {
@@ -361,7 +380,8 @@ export const listArtifactFilesShape = {
     prefix: optionalNonEmptyString,
     limit: optionalPositiveInt,
     cursor: optionalNonEmptyString,
-    compact: z.boolean().default(false).describe("When true, strip the artifactContents summary and empty fields from the response. Default false.")
+    detail: detailParam("standard"),
+    include: responseIncludeParam
 };
 export const listArtifactFilesSchema = z.object(listArtifactFilesShape);
 export const traceSymbolLifecycleShape = {
@@ -369,8 +389,8 @@ export const traceSymbolLifecycleShape = {
     descriptor: optionalDescriptorString.describe('optional JVM descriptor, e.g. "(I)V". Empty strings are treated as omitted.'),
     fromVersion: optionalNonEmptyString,
     toVersion: optionalNonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    mapping: sourceMappingSchema.optional().describe("default obfuscated"),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     gradleUserHome: gradleUserHomeSchema,
     includeSnapshots: z.boolean().default(false),
     maxVersions: optionalPositiveInt.default(120).describe("max 400"),
@@ -381,24 +401,24 @@ export const diffClassSignaturesShape = {
     className: nonEmptyString,
     fromVersion: nonEmptyString,
     toVersion: nonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    mapping: sourceMappingSchema.optional().describe("default obfuscated"),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     gradleUserHome: gradleUserHomeSchema,
     includeFullDiff: z.boolean().default(true).describe("When false, omit from/to snapshots from modified entries and keep only key+changed")
 };
 export const diffClassSignaturesSchema = z.object(diffClassSignaturesShape);
 export const findMappingShape = {
     version: nonEmptyString,
-    kind: workspaceSymbolKindSchema.describe("class | field | method"),
+    kind: workspaceSymbolKindSchema,
     name: nonEmptyString,
     owner: optionalNonEmptyString,
-    descriptor: optionalDescriptorString.describe("JVM descriptor. Optional when signatureMode='name-only' (default). Empty strings are treated as omitted."),
-    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
-    targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    descriptor: optionalDescriptorString.describe("JVM descriptor; optional when signatureMode='name-only'. Empty = omitted."),
+    sourceMapping: sourceMappingSchema,
+    targetMapping: sourceMappingSchema,
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     gradleUserHome: gradleUserHomeSchema,
-    signatureMode: z.enum(["exact", "name-only"]).default("name-only")
-        .describe("exact: descriptor required for kind=method; name-only (default): match by owner+name only"),
+    nameMode: classNameModeSchema.default("auto").describe(NAME_MODE_DESCRIPTION),
+    signatureMode: z.enum(["exact", "name-only"]).default("name-only").describe(SIGNATURE_MODE_DESCRIPTION),
     disambiguation: z
         .object({
         ownerHint: optionalNonEmptyString,
@@ -406,10 +426,9 @@ export const findMappingShape = {
     })
         .partial()
         .optional(),
-    maxCandidates: optionalPositiveInt.default(5).describe("Limit returned candidates (default 5, max 200). Raise when you need the full candidate list."),
-    compact: z.boolean().default(true).describe("Omit top-level empty arrays, null/undefined values, and empty objects from the response. "
-        + "Also omit redundant candidates array for single full-confidence exact-match resolutions. "
-        + "Enabled by default; set to false for full output.")
+    maxCandidates: optionalPositiveInt.default(5).describe("default 5, max 200"),
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -427,7 +446,7 @@ export const findMappingSchema = z.object(findMappingShape).superRefine((value,
                 path: ["descriptor"]
             });
         }
-        if (value.sourceMapping !== "obfuscated" && !value.name.includes(".")) {
+        if (value.nameMode !== "auto" && !value.name.includes(".")) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 message: "name must be fully-qualified class name when kind=class.",
@@ -468,19 +487,22 @@ export const findMappingSchema = z.object(findMappingShape).superRefine((value,
         });
     }
 });
+// Strict shortcut for find-mapping(kind=method, signatureMode=exact): identical inputs,
+// but requires a COMPLETE descriptor projection and returns mapping_unavailable when the
+// descriptor's class references cannot all be projected (find-mapping's exact mode is more
+// lenient there). Prefer find-mapping unless you need that strict-completeness guarantee.
 export const resolveMethodMappingExactShape = {
     version: nonEmptyString,
     name: nonEmptyString,
     owner: nonEmptyString,
     descriptor: nonEmptyString.describe("required JVM descriptor"),
-    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
-    targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    sourceMapping: sourceMappingSchema,
+    targetMapping: sourceMappingSchema,
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     gradleUserHome: gradleUserHomeSchema,
-    maxCandidates: optionalPositiveInt.default(5).describe("Limit returned candidates (default 5, max 200). Raise when you need the full candidate list."),
-    compact: z.boolean().default(true).describe("Omit top-level empty arrays, null/undefined values, and empty objects from the response. "
-        + "Also omit redundant candidates array for single full-confidence exact-match resolutions. "
-        + "Enabled by default; set to false for full output.")
+    maxCandidates: optionalPositiveInt.default(5).describe("default 5, max 200"),
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
@@ -516,27 +538,27 @@ export const classApiKindsSchema = z.string().superRefine((value, ctx) => {
 export const getClassApiMatrixShape = {
     version: nonEmptyString,
     className: nonEmptyString,
-    classNameMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
+    classNameMapping: sourceMappingSchema,
     includeKinds: classApiKindsSchema.optional().describe("comma-separated: class,field,method"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     gradleUserHome: gradleUserHomeSchema,
-    maxRows: optionalPositiveInt.describe("Limit returned rows (max 5000)")
+    maxRows: optionalPositiveInt.describe("Limit returned rows (max 5000)"),
+    cursor: optionalNonEmptyString.describe("nextCursor from the previous response.")
 };
 export const getClassApiMatrixSchema = z.object(getClassApiMatrixShape);
 export const resolveWorkspaceSymbolShape = {
     projectPath: nonEmptyString,
     version: nonEmptyString,
-    kind: workspaceSymbolKindSchema.describe("class | field | method"),
+    kind: workspaceSymbolKindSchema,
     name: nonEmptyString,
     owner: optionalNonEmptyString,
     descriptor: optionalDescriptorString.describe("JVM descriptor. Empty strings are treated as omitted."),
-    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    sourceMapping: sourceMappingSchema,
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     gradleUserHome: gradleUserHomeSchema,
-    maxCandidates: optionalPositiveInt.default(5).describe("Limit returned candidates for field/method lookups (default 5, max 200). Raise when you need the full candidate list."),
-    compact: z.boolean().default(true).describe("Omit top-level empty arrays, null/undefined values, and empty objects from the response. "
-        + "Also omit redundant candidates array for single full-confidence exact-match resolutions. "
-        + "Enabled by default; set to false for full output.")
+    maxCandidates: optionalPositiveInt.default(5).describe("default 5, max 200 (field/method lookups)"),
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const resolveWorkspaceSymbolSchema = z
     .object(resolveWorkspaceSymbolShape)
@@ -599,20 +621,18 @@ export const resolveWorkspaceSymbolSchema = z
 });
 export const checkSymbolExistsShape = {
     version: nonEmptyString,
-    kind: workspaceSymbolKindSchema.describe("class | field | method"),
+    kind: workspaceSymbolKindSchema,
     owner: optionalNonEmptyString,
     name: nonEmptyString,
-    descriptor: optionalDescriptorString.describe("required for kind=method unless signatureMode=name-only. Empty strings are treated as omitted."),
-    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    descriptor: optionalDescriptorString.describe("JVM descriptor; optional when signatureMode='name-only'. Empty = omitted."),
+    sourceMapping: sourceMappingSchema,
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     gradleUserHome: gradleUserHomeSchema,
-    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(5).describe("Limit returned candidates (default 5, max 200). Raise when you need the full candidate list."),
-    compact: z.boolean().default(true).describe("Omit top-level empty arrays, null/undefined values, and empty objects from the response. "
-        + "Also omit redundant candidates array for single full-confidence exact-match resolutions. "
-        + "Enabled by default; set to false for full output.")
+    nameMode: classNameModeSchema.default("auto").describe(NAME_MODE_DESCRIPTION),
+    signatureMode: z.enum(["exact", "name-only"]).default("name-only").describe(SIGNATURE_MODE_DESCRIPTION),
+    maxCandidates: optionalPositiveInt.default(5).describe("default 5, max 200"),
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -673,7 +693,7 @@ export const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRef
 });
 export const nbtToJsonShape = {
     nbtBase64: nonEmptyString,
-    compression: decodeCompressionSchema.default("auto").describe("none | gzip | auto")
+    compression: decodeCompressionSchema.default("auto")
 };
 export const nbtToJsonSchema = z.object(nbtToJsonShape);
 const nbtPatchOperationSchema = z
@@ -690,7 +710,7 @@ export const nbtApplyJsonPatchShape = {
 export const nbtApplyJsonPatchSchema = z.object(nbtApplyJsonPatchShape);
 export const jsonToNbtShape = {
     typedJson: z.unknown(),
-    compression: encodeCompressionSchema.default("none").describe("none | gzip")
+    compression: encodeCompressionSchema.default("none")
 };
 export const jsonToNbtSchema = z.object(jsonToNbtShape);
 export const indexArtifactShape = {
@@ -720,16 +740,16 @@ export const validateMixinShape = {
             mode: z.literal("project"),
             path: nonEmptyString.describe("Workspace root path used to discover *.mixins.json files automatically")
         })
-    ]).describe("One of { mode: 'inline', source }, { mode: 'path', path }, { mode: 'paths', paths[] }, { mode: 'config', configPaths[] }, or { mode: 'project', path }."),
+    ]).describe("mode = inline | path | paths | config | project"),
     sourceRoots: z.array(z.string().min(1)).optional()
-        .describe("Array of source roots for multi-module projects (e.g. ['common/src/main/java', 'neoforge/src/main/java'])"),
-    version: nonEmptyString.describe("Minecraft version"),
-    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+        .describe("Source roots for multi-module projects (e.g. ['common/src/main/java'])"),
+    version: optionalNonEmptyString.describe("Minecraft version. Optional when input.mode='project' or preferProjectVersion=true with projectPath; required otherwise."),
+    mapping: sourceMappingSchema.optional(),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
-    projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
+    projectPath: optionalNonEmptyString.describe("Workspace root for Loom cache-assisted resolution"),
     gradleUserHome: gradleUserHomeSchema,
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
+    preferProjectVersion: z.boolean().optional().describe("Detect MC version from gradle.properties and override version"),
     minSeverity: z.enum(["error", "warning", "all"]).default("all")
         .describe("'error'=errors only, 'warning'=errors+warnings, 'all'=everything"),
     hideUncertain: z.boolean().default(false)
@@ -740,8 +760,8 @@ export const validateMixinShape = {
         .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"]).default("full")
-        .describe("'compact' omits heavy per-result detail, 'summary-first' hoists shared provenance/warnings/incomplete reasons, 'full'=everything"),
+    reportMode: z.enum(["compact", "full", "summary-first"]).default("summary-first")
+        .describe("summary-first (default) hoists shared provenance/warnings, drops per-result heavy detail; compact omits heavy per-result detail; full = everything (required for resolvedMembers/toolHealth/resolutionTrace unless explain=true)."),
     warningCategoryFilter: z.array(z.enum(["mapping", "configuration", "validation", "resolution", "parse"])).optional()
         .describe("Only include warnings/issues matching these categories (default: all)"),
     treatInfoAsWarning: z.boolean().default(true)
@@ -749,12 +769,24 @@ export const validateMixinShape = {
     includeIssues: z.boolean().default(true)
         .describe("When false, keep summary fields but omit per-result issues[] payloads")
 };
-export const validateMixinSchema = z.object(validateMixinShape);
+export const validateMixinSchema = z.object(validateMixinShape).superRefine((value, ctx) => {
+    if (value.version) {
+        return;
+    }
+    const canDetectVersion = value.input?.mode === "project" || (value.preferProjectVersion === true && Boolean(value.projectPath));
+    if (!canDetectVersion) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["version"],
+            message: "version is required unless input.mode='project' or preferProjectVersion=true with projectPath set (so the Minecraft version can be detected from gradle.properties)."
+        });
+    }
+});
 export const validateAccessWidenerShape = {
     content: nonEmptyString.describe("Access Widener file content"),
     version: nonEmptyString.describe("Minecraft version"),
-    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    mapping: sourceMappingSchema.optional(),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted runtime validation"),
     gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
@@ -765,8 +797,8 @@ export const validateAccessWidenerSchema = z.object(validateAccessWidenerShape);
 export const validateAccessTransformerShape = {
     content: nonEmptyString.describe("Access Transformer file content"),
     version: nonEmptyString.describe("Minecraft version"),
-    atNamespace: z.enum(["srg", "mojang", "obfuscated"]).optional().describe("srg | mojang | obfuscated"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    atNamespace: z.enum(["srg", "mojang", "obfuscated"]).optional(),
+    sourcePriority: mappingSourcePrioritySchema.optional(),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Forge/NeoForge runtime validation"),
     gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
@@ -782,7 +814,7 @@ export const analyzeModJarSchema = z.object(analyzeModJarShape);
 export 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().default(true).describe("When false, return registry names/counts without full entry bodies"),
+    includeData: z.boolean().default(true).describe("false = registry names/counts only (cheap discovery); true (default) = full entry bodies."),
     maxEntriesPerRegistry: optionalPositiveInt.describe("Limit returned entries per registry body")
 };
 export const getRegistryDataSchema = z.object(getRegistryDataShape);
@@ -791,7 +823,7 @@ export const compareVersionsCategorySchema = z.enum(COMPARE_VERSIONS_CATEGORIES)
 export 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.default("all").describe("classes | registry | all"),
+    category: compareVersionsCategorySchema.default("all"),
     packageFilter: optionalNonEmptyString.describe("Filter classes to a package prefix (e.g. net.minecraft.world.item)"),
     maxClassResults: optionalPositiveInt.default(500).describe("Max class results per direction (max 5000)")
 };
@@ -816,7 +848,7 @@ export const modSearchTypeSchema = z.enum(MOD_SEARCH_TYPES);
 export const searchModSourceShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
     query: nonEmptyString.describe("Search pattern (regex or literal string)"),
-    searchType: modSearchTypeSchema.default("all").describe("class | method | field | content | all"),
+    searchType: modSearchTypeSchema.default("all"),
     limit: optionalPositiveInt.default(50).describe("Max results (max 200)")
 };
 export const searchModSourceSchema = z.object(searchModSourceShape);
@@ -826,7 +858,11 @@ export const remapModJarShape = {
     inputJar: nonEmptyString.describe("Path to the mod JAR file"),
     outputJar: optionalNonEmptyString.describe("Output path for remapped JAR (auto-generated if omitted)"),
     mcVersion: optionalNonEmptyString.describe("Minecraft version (auto-detected from mod metadata if omitted)"),
-    targetMapping: remapTargetSchema.describe("yarn | mojang")
+    targetMapping: remapTargetSchema,
+    forceRemap: z
+        .boolean()
+        .optional()
+        .describe("Skip the cache and re-resolve the newest yarn build (busts a stale remap)")
 };
 export const remapModJarSchema = z.object(remapModJarShape);
 export const emptySchema = z.object({}).passthrough();