@adhisang/minecraft-modding-mcp 4.2.0 → 5.0.0

package/dist/tool-schemas.js

@@ -1,5 +1,19 @@
 import { isAbsolute as pathIsAbsolute, 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\"].";
+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"];
@@ -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_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.";
+// 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 listVersionsShape = {
     includeSnapshots: z.boolean().default(false),
     limit: optionalPositiveInt.default(20).describe("max 200")
@@ -103,9 +111,8 @@ export const resolveArtifactShape = {
     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.")
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const resolveArtifactSchema = z.object(resolveArtifactShape);
 export const getClassSourceShape = {
@@ -125,7 +132,9 @@ export const getClassSourceShape = {
     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\"]. When true, include diagnostic metadata (provenance, qualityFlags, artifactContents). Default false — omitted to keep the common path lean.")
 };
 export const getClassSourceSchema = z
     .object(getClassSourceShape)
@@ -150,25 +159,29 @@ export const getClassMembersShape = {
     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("Continuation cursor from a previous response's nextCursor; resumes the member list after the last returned page."),
     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.")
+    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.")
 };
 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 = {
@@ -176,6 +189,7 @@ export const verifyMixinTargetShape = {
     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"),
     projectPath: optionalNonEmptyString.describe("Workspace root path for target.kind=workspace and Loom cache assistance."),
     gradleUserHome: gradleUserHomeSchema,
@@ -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)
@@ -262,7 +277,8 @@ 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);
@@ -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);
@@ -321,7 +338,8 @@ export const batchMappingsShape = {
     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);
@@ -339,7 +357,8 @@ export const searchClassSourceShape = {
     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."),
     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 = {
@@ -397,8 +417,8 @@ export const findMappingShape = {
     targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     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,
@@ -407,9 +427,8 @@ 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.")
+    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,6 +487,10 @@ 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,
@@ -478,9 +501,8 @@ export const resolveMethodMappingExactShape = {
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     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.")
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
@@ -520,7 +542,8 @@ export const getClassApiMatrixShape = {
     includeKinds: classApiKindsSchema.optional().describe("comma-separated: class,field,method"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     gradleUserHome: gradleUserHomeSchema,
-    maxRows: optionalPositiveInt.describe("Limit returned rows (max 5000)")
+    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.")
 };
 export const getClassApiMatrixSchema = z.object(getClassApiMatrixShape);
 export const resolveWorkspaceSymbolShape = {
@@ -534,9 +557,8 @@ export const resolveWorkspaceSymbolShape = {
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     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.")
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const resolveWorkspaceSymbolSchema = z
     .object(resolveWorkspaceSymbolShape)
@@ -602,17 +624,15 @@ export const checkSymbolExistsShape = {
     kind: workspaceSymbolKindSchema.describe("class | field | method"),
     owner: optionalNonEmptyString,
     name: nonEmptyString,
-    descriptor: optionalDescriptorString.describe("required for kind=method unless signatureMode=name-only. Empty strings are treated as omitted."),
+    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"),
     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"),
+    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."),
-    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.")
+    detail: detailParam("summary"),
+    include: responseIncludeParam
 };
 export const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -723,7 +743,7 @@ export const validateMixinShape = {
     ]).describe("One of { mode: 'inline', source }, { mode: 'path', path }, { mode: 'paths', paths[] }, { mode: 'config', configPaths[] }, or { mode: 'project', path }."),
     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"),
+    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"),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
@@ -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("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."),
     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,7 +769,19 @@ 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"),
@@ -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("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)."),
     maxEntriesPerRegistry: optionalPositiveInt.describe("Limit returned entries per registry body")
 };
 export const getRegistryDataSchema = z.object(getRegistryDataShape);
@@ -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.describe("yarn | mojang"),
+    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();

package/dist/types.d.ts

@@ -112,6 +112,7 @@ export interface Config {
     fetchTimeoutMs: number;
     fetchRetries: number;
     searchScanPageSize: number;
+    searchScanMaxBytes: number;
     indexInsertChunkSize: number;
     maxMappingGraphCache: number;
     maxSignatureCache: number;

package/dist/version-diff-service.js

@@ -145,6 +145,11 @@ export class VersionDiffService {
             });
         }
         const warnings = [];
+        if (input.maxClassResults != null &&
+            Number.isFinite(input.maxClassResults) &&
+            input.maxClassResults > MAX_CLASS_RESULTS_LIMIT) {
+            warnings.push(`maxClassResults was clamped to ${MAX_CLASS_RESULTS_LIMIT} from ${input.maxClassResults}.`);
+        }
         const startedAt = Date.now();
         log("info", "version-diff.start", { fromVersion, toVersion, category });
         const includeClasses = category === "classes" || category === "all";

package/dist/version-service.d.ts

@@ -16,6 +16,7 @@ export type ListVersionsOutput = {
     snapshots?: VersionEntry[];
     cached: string[];
     totalAvailable: number;
+    warnings?: string[];
 };
 export type ResolvedVersionJar = {
     version: string;
@@ -47,6 +48,7 @@ export declare class VersionService {
     private manifestCache;
     private readonly versionDetailCache;
     private readonly resolveLocks;
+    private indexWriteChain;
     constructor(config: Config, fetchFn?: typeof fetch);
     listVersions(input?: ListVersionsInput): Promise<ListVersionsOutput>;
     listVersionIds(input?: ListVersionIdsInput): Promise<string[]>;
@@ -60,6 +62,7 @@ export declare class VersionService {
     private cacheIndexPath;
     private loadCacheIndex;
     private recordCacheEntry;
+    private recordCacheEntryInternal;
     private trimVersionDetailCache;
 }
 /**

package/dist/version-service.js

@@ -38,6 +38,9 @@ export class VersionService {
     manifestCache;
     versionDetailCache = new Map();
     resolveLocks = new Map();
+    // Serializes index.json read-modify-write so parallel resolutions of different
+    // versions can't clobber each other (resolveLocks only guards the same version).
+    indexWriteChain = Promise.resolve();
     constructor(config, fetchFn = globalThis.fetch) {
         this.config = config;
         this.fetchFn = fetchFn;
@@ -47,6 +50,10 @@ export class VersionService {
         const manifest = await this.fetchManifest();
         const includeSnapshots = input.includeSnapshots ?? false;
         const limit = clampLimit(input.limit, 20, 200);
+        const warnings = [];
+        if (input.limit != null && Number.isFinite(input.limit) && input.limit > 200) {
+            warnings.push(`limit was clamped to 200 from ${input.limit}.`);
+        }
         const versions = manifest.versions ?? [];
         const releases = versions
             .filter((entry) => entry.type === "release")
@@ -65,7 +72,8 @@ export class VersionService {
             releases,
             snapshots: includeSnapshots ? snapshots : undefined,
             cached: Array.from(new Set(cached)).sort((a, b) => a.localeCompare(b)),
-            totalAvailable: versions.length
+            totalAvailable: versions.length,
+            ...(warnings.length ? { warnings } : {})
         };
     }
     async listVersionIds(input = {}) {
@@ -389,7 +397,15 @@ export class VersionService {
             return { entries: [] };
         }
     }
-    async recordCacheEntry(entry) {
+    recordCacheEntry(entry) {
+        // Chain onto the previous write so reads and writes never interleave. The
+        // caller still awaits its own write's result, but the shared chain swallows
+        // failures so one rejected write cannot poison subsequent writes.
+        const next = this.indexWriteChain.then(() => this.recordCacheEntryInternal(entry));
+        this.indexWriteChain = next.catch(() => undefined);
+        return next;
+    }
+    async recordCacheEntryInternal(entry) {
         const indexPath = this.cacheIndexPath();
         const existing = await this.loadCacheIndex();
         const deduped = existing.entries.filter((candidate) => candidate.version !== entry.version);

package/dist/warning-details.d.ts

@@ -0,0 +1,18 @@
+export type WarningCategory = "pagination" | "mapping" | "coverage" | "validation" | "general";
+export type WarningSeverity = "warning" | "info";
+export type WarningDetail = {
+    /** Stable machine code for the warning family. */
+    code: string;
+    category: WarningCategory;
+    severity: WarningSeverity;
+    /** Index into `meta.warnings[]` that holds the original human-readable text. */
+    index: number;
+    /** Input fields a caller can adjust to address the warning, when applicable. */
+    affectedFields?: string[];
+};
+/**
+ * Build the structured `warningDetails[]` companion for a list of warning strings.
+ * The mapping is 1:1 and order-preserving, so each entry's `index` equals its
+ * position and dereferences the text via `warnings[index]`.
+ */
+export declare function classifyWarnings(warnings: string[]): WarningDetail[];

package/dist/warning-details.js

@@ -0,0 +1,63 @@
+// Structured companion to the string `meta.warnings`. Each warning string is
+// classified into a high-value family so agents can branch on category/severity
+// without parsing prose. The original text is NOT duplicated here; each entry
+// references its warning by position via `index` (read `meta.warnings[index]`).
+// First matching rule wins; more specific patterns precede broader ones.
+const WARNING_RULES = [
+    {
+        test: /Member list was truncated|truncated to \d+ (entries|rows)|Raise maxCandidates|Raise maxRows/i,
+        code: "result_truncated",
+        category: "pagination",
+        severity: "info",
+        affectedFields: ["maxMembers", "maxRows", "maxCandidates", "cursor"]
+    },
+    {
+        test: /\bwas clamped to\b/i,
+        code: "input_clamped",
+        category: "validation",
+        severity: "info"
+    },
+    {
+        test: /are not indexed|non-Java resources are not indexed/i,
+        code: "resource_not_indexed",
+        category: "coverage",
+        severity: "info"
+    },
+    {
+        test: /namespace translation requires a version|could not be applied because the artifact has no version|Could not (re)?map .* (from .* to|to .* namespace)|Remap failed for|Mapping lookup failed|No exact class symbol matched|Unsupported .* namespace/i,
+        code: "namespace_fallback",
+        category: "mapping",
+        severity: "warning",
+        affectedFields: ["mapping", "version"]
+    },
+    {
+        test: /falling back to vanilla|resolution failed; falling back|sources jar\.?\s*Falling back|does not include net\.minecraft/i,
+        code: "partial_coverage",
+        category: "coverage",
+        severity: "warning",
+        affectedFields: ["scope"]
+    }
+];
+function classifyWarning(message, index) {
+    for (const rule of WARNING_RULES) {
+        if (rule.test.test(message)) {
+            return {
+                code: rule.code,
+                category: rule.category,
+                severity: rule.severity,
+                index,
+                ...(rule.affectedFields ? { affectedFields: rule.affectedFields } : {})
+            };
+        }
+    }
+    return { code: "general", category: "general", severity: "info", index };
+}
+/**
+ * Build the structured `warningDetails[]` companion for a list of warning strings.
+ * The mapping is 1:1 and order-preserving, so each entry's `index` equals its
+ * position and dereferences the text via `warnings[index]`.
+ */
+export function classifyWarnings(warnings) {
+    return warnings.map((message, index) => classifyWarning(message, index));
+}
+//# sourceMappingURL=warning-details.js.map

package/docs/README-ja.md

@@ -15,7 +15,7 @@
 
 stdio で動作し、Claude Desktop、Claude Code、VS Code、Codex CLI、Gemini CLI などの MCP 対応クライアントから利用できます。
 
-**37 ツール**（6 エントリー + 31 エキスパート） | **7 リソース** | **4 マッピング名前空間** | **SQLite ベースのキャッシュ**
+**41 ツール**（6 エントリー + 35 エキスパート） | **9 リソース** | **4 マッピング名前空間** | **SQLite ベースのキャッシュ**
 
 ## 特長
 
@@ -301,7 +301,7 @@ Minecraft バージョン間でのクラス / レジストリ変更比較と、
 | ツール | 役割 |
 | --- | --- |
 | `find-mapping` | クラス、フィールド、メソッドのシンボルに対するマッピング候補を調べる |
-| `resolve-method-mapping-exact` | owner、name、descriptor の厳密一致で 1 つのメソッドマッピングを解決する |
+| `resolve-method-mapping-exact` | `find-mapping`（kind=method, signatureMode=exact）の厳密版ショートカット。owner+name+descriptor の三つ組が必須 |
 | `get-class-api-matrix` | 1 つのクラス API を `obfuscated`、`mojang`、`intermediary`、`yarn` で見比べる |
 | `resolve-workspace-symbol` | Gradle ワークスペースからコンパイル時に見えるシンボル名を解決する |
 | `check-symbol-exists` | 名前空間内でクラス、フィールド、メソッドが存在するかを確認する |

package/docs/examples.md

@@ -105,7 +105,7 @@ Start with these top-level workflow tools when possible. They cover the common w
   "tool": "get-class-source",
   "arguments": {
     "target": {
-      "type": "artifact",
+      "kind": "artifact",
       "artifactId": "<artifact-id>"
     },
     "className": "net.minecraft.server.Main",
@@ -137,7 +137,7 @@ Start with these top-level workflow tools when possible. They cover the common w
   "tool": "get-class-members",
   "arguments": {
     "target": {
-      "type": "artifact",
+      "kind": "artifact",
       "artifactId": "<artifact-id>"
     },
     "className": "net.minecraft.server.Main",
@@ -395,6 +395,30 @@ Start with these top-level workflow tools when possible. They cover the common w
 
 If the input JAR was already built with Mojang mappings, use `targetMapping: "mojang"` to get a copied output JAR and a `fromMapping: "mojang"` result.
 
+### Bridge a mod hit to a Minecraft-side check
+
+When `search-mod-source` or `get-mod-class-source` surfaces a class or member that
+looks like a Minecraft target (for example a Mixin `@Shadow`/`@Inject` target, or a
+symbol from a crash stack), verify it against the target Minecraft version before
+trusting it. Feed the owner/member into `verify-mixin-target`. When your owner/member
+are in a readable namespace (e.g. `mojang`/`yarn`) but the resolved artifact is
+obfuscated, set `autoRemap: true` to translate them automatically in one call:
+
+```json
+{
+  "tool": "verify-mixin-target",
+  "arguments": {
+    "target": { "kind": "version", "value": "1.21.10" },
+    "owner": "net.minecraft.world.entity.LivingEntity",
+    "member": { "kind": "method", "name": "tickServer", "descriptor": "()V" },
+    "mapping": "mojang",
+    "autoRemap": true
+  }
+}
+```
+
+For a plain "does this symbol exist in this version?" question, use `analyze-symbol task="exists"` instead.
+
 ## Validation
 
 ### Validate Mixin source