@adhisang/minecraft-modding-mcp 5.0.0 → 6.0.0

package/dist/tool-schemas.js

@@ -1,12 +1,12 @@
-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 = "Response detail: 'summary' (terse: drops diagnostics/empties, slims candidates), 'standard' (default for source/file tools: keeps fields but drops heavy diagnostics), 'full' (everything). Replaces the old `compact` flag.";
-const RESPONSE_INCLUDE_DESCRIPTION = "Opt specific field groups back in regardless of detail, e.g. [\"provenance\"], [\"candidates\"], [\"samples\"], [\"artifact\"], [\"descriptors\"].";
+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);
 }
@@ -30,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
@@ -89,13 +89,13 @@ export const sourceLookupTargetSchema = z.discriminatedUnion("kind", [
     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 with kind (same shape as resolve-artifact). Examples: {"kind":"version","value":"1.21.10"}, {"kind":"workspace"} (uses projectPath), {"kind":"dependency","group":"...","name":"..."}, or {"kind":"artifact","artifactId":"..."} to reuse an already-resolved artifact. 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): accept a fully-qualified name, or a dotless name where the tool allows it; fqcn: require a fully-qualified name.";
+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")
@@ -103,14 +103,14 @@ 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."),
+    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
 };
@@ -119,14 +119,14 @@ 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,
@@ -134,7 +134,7 @@ export const getClassSourceShape = {
     outputFile: optionalNonEmptyString.describe("Write source to this file path and return metadata-only response"),
     detail: detailParam("standard"),
     include: responseIncludeParam,
-    includeProvenance: z.boolean().default(false).describe("Alias for include:[\"provenance\"]. When true, include diagnostic metadata (provenance, qualityFlags, artifactContents). Default false — omitted to keep the common path lean.")
+    includeProvenance: z.boolean().default(false).describe('Alias for include:["provenance"] (diagnostic metadata). Default false.')
 };
 export const getClassSourceSchema = z
     .object(getClassSourceShape)
@@ -152,24 +152,24 @@ 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 150, max 5000. Page beyond the first 150 with cursor."),
-    cursor: optionalNonEmptyString.describe("Continuation cursor from a previous response's nextCursor; resumes the member list after the last returned page."),
+    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."),
+    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\"]. When true, include diagnostic metadata (provenance, qualityFlags, artifactContents). Default false — omitted to keep the common path lean."),
-    includeDescriptors: z.boolean().default(false).describe("Alias for include:[\"descriptors\"]. When true, also emit jvmDescriptor on FIELD members. Default false: field descriptors are omitted (the type is already in javaSignature). Method/constructor descriptors are always present for overload disambiguation.")
+    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", [
@@ -185,18 +185,18 @@ export const verifyMixinTargetMemberSchema = z.discriminatedUnion("kind", [
     })
 ]);
 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"),
-    autoRemap: z.boolean().optional().describe("When true and mapping differs from the artifact namespace, translate owner+member via find-mapping instead of failing ERR_NAMESPACE_MISMATCH. Requires a version-based target."),
-    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"]);
@@ -211,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,
@@ -233,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];
@@ -243,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({
@@ -285,7 +285,7 @@ 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,
@@ -332,7 +332,7 @@ 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,
@@ -346,16 +346,16 @@ 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,
     detail: detailParam("standard"),
     include: responseIncludeParam
@@ -389,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"),
@@ -401,21 +401,21 @@ 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,
     nameMode: classNameModeSchema.default("auto").describe(NAME_MODE_DESCRIPTION),
     signatureMode: z.enum(["exact", "name-only"]).default("name-only").describe(SIGNATURE_MODE_DESCRIPTION),
@@ -426,7 +426,7 @@ 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."),
+    maxCandidates: optionalPositiveInt.default(5).describe("default 5, max 200"),
     detail: detailParam("summary"),
     include: responseIncludeParam
 };
@@ -496,11 +496,11 @@ export const resolveMethodMappingExactShape = {
     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."),
+    maxCandidates: optionalPositiveInt.default(5).describe("default 5, max 200"),
     detail: detailParam("summary"),
     include: responseIncludeParam
 };
@@ -538,25 +538,25 @@ 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)"),
-    cursor: optionalNonEmptyString.describe("Continuation cursor from a previous response's nextCursor; resumes after the last returned row.")
+    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."),
+    maxCandidates: optionalPositiveInt.default(5).describe("default 5, max 200 (field/method lookups)"),
     detail: detailParam("summary"),
     include: responseIncludeParam
 };
@@ -621,16 +621,16 @@ export const resolveWorkspaceSymbolSchema = z
 });
 export const checkSymbolExistsShape = {
     version: nonEmptyString,
-    kind: workspaceSymbolKindSchema.describe("class | field | method"),
+    kind: workspaceSymbolKindSchema,
     owner: optionalNonEmptyString,
     name: nonEmptyString,
-    descriptor: optionalDescriptorString.describe("JVM descriptor. Optional when signatureMode='name-only' (default). 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("auto").describe(NAME_MODE_DESCRIPTION),
     signatureMode: z.enum(["exact", "name-only"]).default("name-only").describe(SIGNATURE_MODE_DESCRIPTION),
-    maxCandidates: optionalPositiveInt.default(5).describe("Limit returned candidates (default 5, max 200). Raise when you need the full candidate list."),
+    maxCandidates: optionalPositiveInt.default(5).describe("default 5, max 200"),
     detail: detailParam("summary"),
     include: responseIncludeParam
 };
@@ -693,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
@@ -710,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 = {
@@ -740,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: optionalNonEmptyString.describe("Minecraft version. Optional when input.mode='project' (detected from the workspace) or preferProjectVersion=true with projectPath set; required otherwise."),
-    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)
@@ -761,7 +761,7 @@ export const validateMixinShape = {
     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("summary-first")
-        .describe("Default 'summary-first': hoists shared provenance/warnings/incomplete reasons and drops per-result resolvedMembers/toolHealth/structuredWarnings. 'compact' omits heavy per-result detail; 'full'=everything. resolvedMembers/per-result toolHealth/resolutionTrace require reportMode='full' or explain=true."),
+        .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)
@@ -785,8 +785,8 @@ export const validateMixinSchema = z.object(validateMixinShape).superRefine((val
 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),
@@ -797,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),
@@ -814,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 only. To discover which registries exist without pulling every entry body, pass includeData:false (omitting registry with the default includeData:true returns the full data for every registry)."),
+    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);
@@ -823,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)")
 };
@@ -848,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);
@@ -858,7 +858,7 @@ 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()

package/dist/warning-details.d.ts

@@ -16,3 +16,15 @@ export type WarningDetail = {
  * position and dereferences the text via `warnings[index]`.
  */
 export declare function classifyWarnings(warnings: string[]): WarningDetail[];
+/**
+ * Cap of structured warningDetails entries emitted at `detail:"summary"`.
+ */
+export declare const SUMMARY_WARNING_DETAIL_CAP = 5;
+/**
+ * At `detail:"summary"` the structured warningDetails companion is capped to a small
+ * representative set to keep responses lean. The full human-readable text still lives
+ * in `meta.warnings[]`, and each kept entry's `index` continues to dereference it, so
+ * no information is lost — only the redundant structured duplicate is trimmed. Standard
+ * and full detail return the companion unchanged.
+ */
+export declare function capWarningDetailsForSummary(warningDetails: WarningDetail[], isSummary: boolean): WarningDetail[];

package/dist/warning-details.js

@@ -60,4 +60,21 @@ function classifyWarning(message, index) {
 export function classifyWarnings(warnings) {
     return warnings.map((message, index) => classifyWarning(message, index));
 }
+/**
+ * Cap of structured warningDetails entries emitted at `detail:"summary"`.
+ */
+export const SUMMARY_WARNING_DETAIL_CAP = 5;
+/**
+ * At `detail:"summary"` the structured warningDetails companion is capped to a small
+ * representative set to keep responses lean. The full human-readable text still lives
+ * in `meta.warnings[]`, and each kept entry's `index` continues to dereference it, so
+ * no information is lost — only the redundant structured duplicate is trimmed. Standard
+ * and full detail return the companion unchanged.
+ */
+export function capWarningDetailsForSummary(warningDetails, isSummary) {
+    if (!isSummary || warningDetails.length <= SUMMARY_WARNING_DETAIL_CAP) {
+        return warningDetails;
+    }
+    return warningDetails.slice(0, SUMMARY_WARNING_DETAIL_CAP);
+}
 //# sourceMappingURL=warning-details.js.map

package/dist/workspace-mapping-service.js

@@ -65,6 +65,15 @@ function buildDependencyPropertyKeys(group, name) {
         `${groupSegment}_${name}_version`,
         `${camelGroupName}Version`
     ];
+    // Umbrella fallback: submodules of an umbrella package (e.g. Fabric API's
+    // net.fabricmc.fabric-api:fabric-screen-handler-api-v1) rarely declare their own
+    // version — the parent declares a single umbrella property (fabric_api_version /
+    // fabricApiVersion) that all submodules inherit. When the artifact name differs from
+    // the group's last segment, append the umbrella's keys as LOWER-priority candidates so
+    // submodule version detection no longer fails with ERR_DEPENDENCY_VERSION_UNRESOLVED.
+    if (groupSegment !== name) {
+        keys.push(`${groupSegment.replace(/-/g, "_")}_version`, `${camelCaseDependencyName(groupSegment)}Version`);
+    }
     const seen = new Set();
     const deduped = [];
     for (const key of keys) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "MCP server for AI-assisted Minecraft modding: inspect decompiled source, resolve Mojang/Yarn/Intermediary mappings, diff versions, analyze Fabric/Forge/NeoForge mod JARs, and validate Mixin, Access Widener, and Access Transformer files.",
   "type": "module",
   "main": "dist/index.js",