@adhisang/minecraft-modding-mcp 5.0.0 → 6.1.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
@@ -64,10 +64,10 @@ export const workspaceTargetSchema = z.object({
 });
 export const dependencyTargetSchema = z.object({
     kind: z.literal("dependency"),
-    group: nonEmptyString,
-    name: nonEmptyString,
-    version: z.string().trim().min(1).optional(),
-    versionFromProject: z.boolean().optional()
+    group: nonEmptyString.describe('Maven group, e.g. "net.fabricmc.fabric-api" or "dev.architectury".'),
+    name: nonEmptyString.describe('Maven artifact name, e.g. "fabric-api" or "architectury".'),
+    version: z.string().trim().min(1).optional().describe("Explicit version; omit and set versionFromProject to resolve it from the workspace."),
+    versionFromProject: z.boolean().optional().describe("Resolve the version from the project's gradle.properties / gradle cache (requires projectPath).")
 });
 export const resolveArtifactTargetSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("version"), value: nonEmptyString }),
@@ -89,13 +89,16 @@ 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"}, or to inspect a loader/Fabric dependency like vanilla: {"kind":"dependency","group":"net.fabricmc.fabric-api","name":"fabric-api","versionFromProject":true} (needs projectPath) or with an explicit "version".';
+export const SOURCE_LOOKUP_TARGET_DESCRIPTION = 'Same shape as resolve-artifact target (incl. {"kind":"dependency",...} to read a Fabric/loader dependency class like vanilla), 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 MEMBER_PATTERN_DESCRIPTION = 'Case-insensitive substring filter on member names. Use "|" for OR alternatives, e.g. "getStateForPlacement|canSurvive|setPlacedBy" (each token is matched as a substring, not a regex).';
+export const memberProjectionSchema = z.enum(["names", "signatures", "full"]);
+export const MEMBER_PROJECTION_DESCRIPTION = 'Per-member field projection: "names" (member name only), "signatures" (name + javaSignature, no jvmDescriptor), or "full" (default; complete member shape). Use "names"/"signatures" to cut response tokens for existence/signature checks.';
 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 +106,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 +122,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 +137,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 +155,25 @@ 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,
+    memberPattern: optionalNonEmptyString.describe(MEMBER_PATTERN_DESCRIPTION),
+    projection: memberProjectionSchema.optional().describe(MEMBER_PROJECTION_DESCRIPTION),
     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 +189,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 +215,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 +237,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 +247,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,7 +266,7 @@ export const batchClassMembersEntrySchema = z.object({
     access: memberAccessSchema.optional(),
     includeSynthetic: z.boolean().optional(),
     includeInherited: z.boolean().optional(),
-    memberPattern: optionalNonEmptyString,
+    memberPattern: optionalNonEmptyString.describe(MEMBER_PATTERN_DESCRIPTION),
     maxMembers: optionalPositiveInt
 });
 export const batchClassMembersShape = {
@@ -278,6 +282,7 @@ export const batchClassMembersShape = {
     concurrency: z.number().int().min(1).max(8).optional(),
     failFast: z.boolean().optional(),
     detail: detailParam("summary"),
+    projection: memberProjectionSchema.optional().describe(MEMBER_PROJECTION_DESCRIPTION),
     include: responseIncludeParam,
     entries: z.array(batchClassMembersEntrySchema).min(1).max(50)
 };
@@ -285,7 +290,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 +337,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 +351,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 +394,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 +406,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 +431,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 +501,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 +543,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 +626,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 +698,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 +715,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 +745,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 +766,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 +790,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 +802,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 +819,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 +828,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 +853,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 +863,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/docs/tool-reference.md

@@ -67,6 +67,29 @@ Start here when you are not sure which tool to reach for. In every row, the left
 | `{ kind: "workspace", scope?, strict? }` | When the caller already passes a `projectPath` and wants the tool to detect Minecraft version, compile mapping, and loader from `gradle.properties` and `build.gradle(.kts)`. | `projectPath` | Synthesised to `{ kind: "version", value: <detected> }`. Scope precedence is `target.scope` → top-level `scope` → loader-derived default (`"merged"` when a loader is detected, `"vanilla"` otherwise). When the version is not detected, raises `ERR_WORKSPACE_VERSION_UNRESOLVED` regardless of `strict`. Detected facts surface on `provenance.workspaceResolution`. |
 | `{ kind: "dependency", group, name, version?, versionFromProject? }` | When the caller wants to resolve a Maven-coordinate dependency (e.g. `dev.architectury:architectury`) without computing the exact version themselves. | `projectPath` (unless `version` is given) | Synthesised to `{ kind: "coordinate", value: "<group>:<name>:<version>" }`. The dependency JAR is treated as non-vanilla: binary remap is suppressed. When the caller asks for a non-obfuscated mapping the resolver returns the JAR with `mappingApplied: "obfuscated"` and `qualityFlags: ["dependency-mapping-unverified"]`, plus a warning that the caller must validate symbol availability. Resolution metadata appears on `provenance.dependencyResolution`. |
 
+### Inspecting a Fabric / loader dependency like vanilla
+
+To read members or source of a Fabric API (or any loader/Maven dependency) class
+the same way you read vanilla, pass a `dependency` target straight to
+`get-class-members` / `get-class-source` — no separate lookup tool is needed:
+
+```jsonc
+// members of a Fabric API class, version taken from the workspace
+{
+  "tool": "get-class-members",
+  "className": "net.fabricmc.fabric.api.event.player.UseEntityCallback",
+  "target": { "kind": "dependency", "group": "net.fabricmc.fabric-api", "name": "fabric-api", "versionFromProject": true },
+  "projectPath": "/path/to/workspace"
+}
+```
+
+Use an explicit `"version"` instead of `versionFromProject` when you already
+know it. Because dependency JARs are not remapped, members come back in the
+dependency's own namespace with `qualityFlags: ["dependency-mapping-unverified"]`;
+treat the names as the JAR's compiled names. For repeated lookups against the
+same dependency, call `resolve-artifact` once and reuse the returned
+`artifactId` via `target: { kind: "artifact", artifactId }`.
+
 Workspace detection is memoised in a process-resident `WorkspaceContextCache` (16-entry LRU, 5-minute TTL). The cache is observable through `manage-cache` with `cacheKinds: ["workspace"]`, and individual entries can be invalidated via `selector.projectPath`.
 
 `target.kind="dependency"` resolution probes four de-duplicated `gradle.properties` keys in order — `name_version`, `camelCaseVersion`, `lastSegment(group)_name_version`, and `camelCase(lastSegment(group)_name)Version` — before falling back to the modules-2 cache layout `~/.gradle/caches/modules-2/files-2.1/<group>/<name>/`. Version tokens that contain path separators, `..`, NUL, control characters, or any character outside `[A-Za-z0-9._+-]` are rejected; in `gradle.properties` the rejection is recorded under `attempts[]` as `gradle.properties:<key>:rejected-unsafe-version` and the next key is tried. Snapshot and dev directories are excluded by default. The modules-2 fallback only resolves when exactly one valid entry remains; multiple entries raise `ERR_DEPENDENCY_VERSION_UNRESOLVED` so a global cache cannot supply a version the workspace did not declare.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "5.0.0",
+  "version": "6.1.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",