@adhisang/minecraft-modding-mcp 1.2.1 → 2.1.0

package/dist/index.js

@@ -3,18 +3,20 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ZodError, z } from "zod";
 import { CompatStdioServerTransport } from "./compat-stdio-transport.js";
 import { objectResult } from "./mcp-helpers.js";
+import { prepareToolInput } from "./tool-input.js";
 import { loadConfig } from "./config.js";
-import { ERROR_CODES, isAppError } from "./errors.js";
+import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { log } from "./logger.js";
 import { applyNbtJsonPatch, nbtBase64ToTypedJson, typedJsonToNbtBase64 } from "./nbt/pipeline.js";
 import { analyzeModJar } from "./mod-analyzer.js";
 import { remapModJar } from "./mod-remap-service.js";
 import { registerResources } from "./resources.js";
 import { SourceService } from "./source-service.js";
+import { ToolExecutionGate } from "./tool-execution-gate.js";
 if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "production";
 }
-const SOURCE_MAPPINGS = ["official", "mojang", "intermediary", "yarn"];
+const SOURCE_MAPPINGS = ["obfuscated", "mojang", "intermediary", "yarn"];
 const SOURCE_PRIORITIES = ["loom-first", "maven-first"];
 const TARGET_KINDS = ["version", "jar", "coordinate"];
 const SEARCH_INTENTS = ["symbol", "text", "path"];
@@ -27,6 +29,16 @@ const SOURCE_MODES = ["metadata", "snippet", "full"];
 const ARTIFACT_SCOPES = ["vanilla", "merged", "loader"];
 const DECODE_COMPRESSIONS = ["none", "gzip", "auto"];
 const ENCODE_COMPRESSIONS = ["none", "gzip"];
+const HEAVY_TOOL_NAMES = new Set([
+    "trace-symbol-lifecycle",
+    "diff-class-signatures",
+    "compare-versions",
+    "find-mapping",
+    "resolve-method-mapping-exact",
+    "get-class-api-matrix",
+    "get-registry-data"
+]);
+const heavyToolExecutionGate = new ToolExecutionGate({ maxConcurrent: 1, maxQueue: 2 });
 const nonEmptyString = z.string().trim().min(1);
 const optionalNonEmptyString = z.string().trim().min(1).optional();
 const optionalPositiveInt = z.number().int().positive().optional();
@@ -43,63 +55,53 @@ const sourceModeSchema = z.enum(SOURCE_MODES);
 const artifactScopeSchema = z.enum(ARTIFACT_SCOPES);
 const decodeCompressionSchema = z.enum(DECODE_COMPRESSIONS);
 const encodeCompressionSchema = z.enum(ENCODE_COMPRESSIONS);
-function validateTargetPair(value, ctx) {
-    const hasArtifactId = Boolean(value.artifactId);
-    const hasTargetKind = value.targetKind !== undefined;
-    const hasTargetValue = value.targetValue !== undefined;
-    if (hasArtifactId && (hasTargetKind || hasTargetValue)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "artifactId and targetKind/targetValue are mutually exclusive.",
-            path: ["artifactId"]
-        });
-        return;
-    }
-    if (hasTargetKind !== hasTargetValue) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "targetKind and targetValue must be provided together.",
-            path: [hasTargetKind ? "targetValue" : "targetKind"]
-        });
-        return;
-    }
-    if (!hasArtifactId && !hasTargetKind) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "Either artifactId or targetKind+targetValue must be provided.",
-            path: ["artifactId"]
-        });
-    }
-}
+const resolveArtifactTargetSchema = z.object({
+    kind: targetKindSchema,
+    value: nonEmptyString
+});
+const sourceLookupTargetSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("artifact"),
+        artifactId: nonEmptyString
+    }),
+    z.object({
+        type: z.literal("resolve"),
+        kind: targetKindSchema,
+        value: nonEmptyString
+    })
+]);
+const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = "Object with kind and value. Example: {\"kind\":\"version\",\"value\":\"1.21.10\"}. Must be an object, not a string.";
+const SOURCE_LOOKUP_TARGET_DESCRIPTION = "Object: {\"type\":\"resolve\",\"kind\":\"version\",\"value\":\"1.21.10\"} or {\"type\":\"artifact\",\"artifactId\":\"...\"}. Must be an object, not a string.";
+const SOURCE_SCOPE_DESCRIPTION = 'vanilla = Mojang client jar only; merged = Loom cache discovery (default); loader = currently behaves the same as "merged".';
 const listVersionsShape = {
     includeSnapshots: z.boolean().optional().describe("default false"),
     limit: optionalPositiveInt.describe("default 20, max 200")
 };
 const listVersionsSchema = z.object(listVersionsShape);
 const resolveArtifactShape = {
-    targetKind: targetKindSchema.describe("version | jar | coordinate"),
-    targetValue: nonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
+    target: z.object({
+        kind: targetKindSchema,
+        value: nonEmptyString
+    }).describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     allowDecompile: z.boolean().optional().describe("default true"),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
-    scope: artifactScopeSchema.optional().describe("vanilla = Mojang client jar only; merged = Loom cache discovery (default); loader = loader-specific"),
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override targetValue"),
+    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.")
 };
 const resolveArtifactSchema = z.object(resolveArtifactShape);
 const getClassSourceShape = {
     className: nonEmptyString,
     mode: sourceModeSchema.optional().describe("metadata (default) = symbol outline only; snippet = source with default maxLines=200; full = entire source"),
-    artifactId: optionalNonEmptyString,
-    targetKind: targetKindSchema.optional().describe("version | jar | coordinate"),
-    targetValue: optionalNonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
+    target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     allowDecompile: z.boolean().optional().describe("default true"),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
-    scope: artifactScopeSchema.optional().describe("vanilla = Mojang client jar only; merged = Loom cache discovery (default); loader = loader-specific"),
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override targetValue"),
+    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."),
     startLine: optionalPositiveInt,
     endLine: optionalPositiveInt,
@@ -110,11 +112,6 @@ const getClassSourceShape = {
 const getClassSourceSchema = z
     .object(getClassSourceShape)
     .superRefine((value, ctx) => {
-    validateTargetPair({
-        artifactId: value.artifactId,
-        targetKind: value.targetKind,
-        targetValue: value.targetValue
-    }, ctx);
     if (value.startLine !== undefined &&
         value.endLine !== undefined &&
         value.startLine > value.endLine) {
@@ -127,10 +124,8 @@ const getClassSourceSchema = z
 });
 const getClassMembersShape = {
     className: nonEmptyString,
-    artifactId: optionalNonEmptyString,
-    targetKind: targetKindSchema.optional().describe("version | jar | coordinate"),
-    targetValue: optionalNonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn (default official)"),
+    target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     allowDecompile: z.boolean().optional().describe("default true"),
     access: memberAccessSchema.optional().describe("public | all (default public)"),
@@ -139,19 +134,11 @@ const getClassMembersShape = {
     memberPattern: optionalNonEmptyString,
     maxMembers: optionalPositiveInt.describe("default 500, max 5000"),
     projectPath: optionalNonEmptyString,
-    scope: artifactScopeSchema.optional().describe("vanilla | merged | loader"),
+    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.")
 };
-const getClassMembersSchema = z
-    .object(getClassMembersShape)
-    .superRefine((value, ctx) => {
-    validateTargetPair({
-        artifactId: value.artifactId,
-        targetKind: value.targetKind,
-        targetValue: value.targetValue
-    }, ctx);
-});
+const getClassMembersSchema = z.object(getClassMembersShape);
 const searchClassSourceShape = {
     artifactId: nonEmptyString,
     query: nonEmptyString,
@@ -160,14 +147,19 @@ const searchClassSourceShape = {
     packagePrefix: optionalNonEmptyString,
     fileGlob: optionalNonEmptyString,
     symbolKind: searchSymbolKindSchema.optional().describe("class | interface | enum | record | method | field"),
-    snippetLines: optionalPositiveInt.describe("default 8, clamp 1..80"),
-    includeDefinition: z.boolean().optional().describe("default false"),
-    includeOneHop: z.boolean().optional().describe("default false"),
     queryMode: z.enum(["auto", "token", "literal"]).optional().describe("auto (default): FTS5 with literal fallback for separator queries; token: FTS5 only; literal: substring scan only"),
     limit: optionalPositiveInt.describe("default 20"),
     cursor: optionalNonEmptyString
 };
-const searchClassSourceSchema = z.object(searchClassSourceShape);
+const searchClassSourceSchema = z.object(searchClassSourceShape).superRefine((value, ctx) => {
+    if (value.symbolKind && value.intent && value.intent !== "symbol") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["symbolKind"],
+            message: 'symbolKind filter is only supported when intent="symbol".'
+        });
+    }
+});
 const getArtifactFileShape = {
     artifactId: nonEmptyString,
     filePath: nonEmptyString,
@@ -186,7 +178,7 @@ const traceSymbolLifecycleShape = {
     descriptor: optionalNonEmptyString.describe('optional JVM descriptor, e.g. "(I)V"'),
     fromVersion: optionalNonEmptyString,
     toVersion: optionalNonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn (default official)"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     includeSnapshots: z.boolean().optional().describe("default false"),
     maxVersions: optionalPositiveInt.describe("default 120, max 400"),
@@ -197,8 +189,9 @@ const diffClassSignaturesShape = {
     className: nonEmptyString,
     fromVersion: nonEmptyString,
     toVersion: nonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn (default official)"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    includeFullDiff: z.boolean().optional().describe("When false, omit from/to snapshots from modified entries and keep only key+changed")
 };
 const diffClassSignaturesSchema = z.object(diffClassSignaturesShape);
 const findMappingShape = {
@@ -207,8 +200,8 @@ const findMappingShape = {
     name: nonEmptyString,
     owner: optionalNonEmptyString,
     descriptor: optionalNonEmptyString,
-    sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
-    targetMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
+    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
+    targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     disambiguation: z
         .object({
@@ -216,7 +209,8 @@ const findMappingShape = {
         descriptorHint: optionalNonEmptyString
     })
         .partial()
-        .optional()
+        .optional(),
+    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
 };
 const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -277,42 +271,21 @@ const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) =>
 });
 const resolveMethodMappingExactShape = {
     version: nonEmptyString,
-    kind: workspaceSymbolKindSchema.describe("class | field | method"),
     name: nonEmptyString,
-    owner: optionalNonEmptyString,
-    descriptor: optionalNonEmptyString.describe("required for kind=method"),
-    sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
-    targetMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    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"),
+    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
 };
 const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
     .superRefine((value, ctx) => {
-    if (value.kind !== "method") {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "resolve-method-mapping-exact requires kind=method.",
-            path: ["kind"]
-        });
-    }
-    if (!value.owner) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "owner is required when kind=method.",
-            path: ["owner"]
-        });
-    }
-    if (!value.descriptor) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "descriptor is required when kind=method.",
-            path: ["descriptor"]
-        });
-    }
     if (/[\s./()]/.test(value.name)) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "name must be a simple method name when kind=method.",
+            message: "name must be a simple method name.",
             path: ["name"]
         });
     }
@@ -340,9 +313,10 @@ const classApiKindsSchema = z.string().superRefine((value, ctx) => {
 const getClassApiMatrixShape = {
     version: nonEmptyString,
     className: nonEmptyString,
-    classNameMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
+    classNameMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     includeKinds: classApiKindsSchema.optional().describe("comma-separated: class,field,method"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    maxRows: optionalPositiveInt.describe("Limit returned rows (max 5000)")
 };
 const getClassApiMatrixSchema = z.object(getClassApiMatrixShape);
 const resolveWorkspaceSymbolShape = {
@@ -352,8 +326,9 @@ const resolveWorkspaceSymbolShape = {
     name: nonEmptyString,
     owner: optionalNonEmptyString,
     descriptor: optionalNonEmptyString,
-    sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    maxCandidates: optionalPositiveInt.describe("Limit returned candidates for field/method lookups (default 200, max 200)")
 };
 const resolveWorkspaceSymbolSchema = z
     .object(resolveWorkspaceSymbolShape)
@@ -420,11 +395,12 @@ const checkSymbolExistsShape = {
     owner: optionalNonEmptyString,
     name: nonEmptyString,
     descriptor: optionalNonEmptyString.describe("required for kind=method unless signatureMode=name-only"),
-    sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
+    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     nameMode: classNameModeSchema.optional().describe("fqcn | auto (default fqcn)"),
     signatureMode: z.enum(["exact", "name-only"]).optional()
-        .describe("exact (default): require descriptor for methods; name-only: match by owner+name only")
+        .describe("exact (default): require descriptor for methods; name-only: match by owner+name only"),
+    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
 };
 const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -511,17 +487,34 @@ const indexArtifactShape = {
 };
 const indexArtifactSchema = z.object(indexArtifactShape);
 const validateMixinShape = {
-    source: optionalNonEmptyString.describe("Mixin Java source text (mutually exclusive with sourcePath/sourcePaths/mixinConfigPath)"),
-    sourcePath: optionalNonEmptyString.describe("Path to Mixin .java file (alternative to source/sourcePaths/mixinConfigPath)"),
-    sourcePaths: z.array(z.string().min(1)).optional().describe("Array of Mixin .java file paths for batch validation"),
-    mixinConfigPath: z.union([nonEmptyString, z.array(nonEmptyString).min(1)]).optional().describe("Path (or array of paths) to mixin config JSON (e.g. modid.mixins.json); auto-discovers and batch-validates all listed classes"),
-    sourceRoot: optionalNonEmptyString.describe("Source root relative to projectPath (default 'src/main/java')"),
+    input: z.discriminatedUnion("mode", [
+        z.object({
+            mode: z.literal("inline"),
+            source: nonEmptyString.describe("Mixin Java source text")
+        }),
+        z.object({
+            mode: z.literal("path"),
+            path: nonEmptyString.describe("Path to a Mixin .java file")
+        }),
+        z.object({
+            mode: z.literal("paths"),
+            paths: z.array(nonEmptyString).min(1).describe("Array of Mixin .java file paths for batch validation")
+        }),
+        z.object({
+            mode: z.literal("config"),
+            configPaths: z.array(nonEmptyString).min(1).describe("Path array to mixin config JSON files (e.g. modid.mixins.json)")
+        }),
+        z.object({
+            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 }."),
     sourceRoots: z.array(z.string().min(1)).optional()
         .describe("Array of source roots for multi-module projects (e.g. ['common/src/main/java', 'neoforge/src/main/java'])"),
     version: nonEmptyString.describe("Minecraft version"),
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    scope: artifactScopeSchema.optional().describe("vanilla | merged | loader"),
+    scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
     minSeverity: z.enum(["error", "warning", "all"]).optional()
@@ -534,25 +527,20 @@ const validateMixinShape = {
         .describe("'full'=all warnings (default), 'aggregated'=group warnings by category with counts and samples"),
     preferProjectMapping: z.boolean().optional()
         .describe("When true, auto-detect mapping from project config even if mapping is explicitly provided"),
-    reportMode: z.enum(["compact", "full"]).optional()
-        .describe("'compact' omits resolvedMembers/structuredWarnings/toolHealth details, 'full'=everything (default)"),
+    reportMode: z.enum(["compact", "full", "summary-first"]).optional()
+        .describe("'compact' omits heavy per-result detail, 'summary-first' hoists shared provenance/warnings/incomplete reasons, 'full'=everything (default)"),
     warningCategoryFilter: z.array(z.enum(["mapping", "configuration", "validation", "resolution", "parse"])).optional()
         .describe("Only include warnings/issues matching these categories (default: all)"),
     treatInfoAsWarning: z.boolean().optional()
-        .describe("When false, suppress info-severity structured warnings from output (default true)")
+        .describe("When false, suppress info-severity structured warnings from output (default true)"),
+    includeIssues: z.boolean().optional()
+        .describe("When false, keep summary fields but omit per-result issues[] payloads")
 };
-const validateMixinSchema = z.object(validateMixinShape).refine((d) => {
-    const hasSource = d.source != null;
-    const hasSourcePath = d.sourcePath != null;
-    const hasSourcePaths = d.sourcePaths != null && d.sourcePaths.length > 0;
-    const hasMixinConfig = d.mixinConfigPath != null && (typeof d.mixinConfigPath === "string" || (Array.isArray(d.mixinConfigPath) && d.mixinConfigPath.length > 0));
-    // Exactly one of the four must be provided
-    return [hasSource, hasSourcePath, hasSourcePaths, hasMixinConfig].filter(Boolean).length === 1;
-}, { message: "Exactly one of 'source', 'sourcePath', 'sourcePaths', or 'mixinConfigPath' must be provided." });
+const validateMixinSchema = z.object(validateMixinShape);
 const validateAccessWidenerShape = {
     content: nonEmptyString.describe("Access Widener file content"),
     version: nonEmptyString.describe("Minecraft version"),
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
 };
 const validateAccessWidenerSchema = z.object(validateAccessWidenerShape);
@@ -563,7 +551,9 @@ const analyzeModJarShape = {
 const analyzeModJarSchema = z.object(analyzeModJarShape);
 const getRegistryDataShape = {
     version: nonEmptyString.describe("Minecraft version (e.g. 1.21)"),
-    registry: optionalNonEmptyString.describe('Optional registry name (e.g. "block", "item", "minecraft:biome"). Omit to list all registries.')
+    registry: optionalNonEmptyString.describe('Optional registry name (e.g. "block", "item", "minecraft:biome"). Omit to list all registries.'),
+    includeData: z.boolean().optional().describe("When false, return registry names/counts without full entry bodies"),
+    maxEntriesPerRegistry: optionalPositiveInt.describe("Limit returned entries per registry body")
 };
 const getRegistryDataSchema = z.object(getRegistryDataShape);
 const COMPARE_VERSIONS_CATEGORIES = ["classes", "registry", "all"];
@@ -578,7 +568,9 @@ const compareVersionsShape = {
 const compareVersionsSchema = z.object(compareVersionsShape);
 const decompileModJarShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
-    className: optionalNonEmptyString.describe("Optional fully-qualified class name to view source. Omit to list all classes.")
+    className: optionalNonEmptyString.describe("Optional fully-qualified class name to view source. Omit to list all classes."),
+    includeFiles: z.boolean().optional().describe("When false, omit the full class list and return counts only"),
+    maxFiles: optionalPositiveInt.describe("Limit returned class names when files are included")
 };
 const decompileModJarSchema = z.object(decompileModJarShape);
 const getModClassSourceShape = {
@@ -626,6 +618,9 @@ const server = new McpServer({
     name: "@adhisang/minecraft-modding-mcp",
     version: SERVER_VERSION
 });
+// The SDK validates tool args before invoking handlers and returns generic InvalidParams text.
+// Bypass that layer so runTool() remains the single source of truth for validation and error envelopes.
+server.validateToolInput = async (_tool, args) => args;
 const config = loadConfig();
 const nbtLimits = {
     maxInputBytes: config.maxNbtInputBytes,
@@ -672,11 +667,16 @@ function attachProcessErrorHandlers() {
 function buildRequestId() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
-function buildTarget(kind, value) {
-    if (!kind || !value) {
-        return undefined;
+function normalizeSourceLookupTarget(target) {
+    if (target.type === "artifact") {
+        return { artifactId: target.artifactId };
     }
-    return { kind, value };
+    return {
+        target: {
+            kind: target.kind,
+            value: target.value
+        }
+    };
 }
 function parseClassApiKinds(value) {
     if (value == null) {
@@ -801,8 +801,314 @@ function extractFieldErrorsFromDetails(details) {
         .filter((entry) => entry != null);
     return normalized.length > 0 ? normalized : undefined;
 }
-function mapErrorToProblem(caughtError, requestId) {
+function asObjectRecord(value) {
+    return typeof value === "object" && value != null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function asStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.trim())
+        ? value
+        : undefined;
+}
+function truncateSuggestionText(value, maxLength = 500) {
+    return value.length > maxLength
+        ? `${value.slice(0, maxLength)}...`
+        : value;
+}
+function parseJsonObjectString(value) {
+    if (!value.trim().startsWith("{")) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return asObjectRecord(parsed);
+    }
+    catch {
+        return undefined;
+    }
+}
+function inferTargetKindFromString(value) {
+    if (/[\\/]/.test(value) || /\.jar$/i.test(value)) {
+        return "jar";
+    }
+    if (value.split(":").length >= 3) {
+        return "coordinate";
+    }
+    return "version";
+}
+function copySourceLookupSuggestionFields(tool, source) {
+    const result = {};
+    const stringFields = tool === "get-class-source"
+        ? ["className", "mode", "mapping", "sourcePriority", "projectPath", "scope", "outputFile"]
+        : ["className", "mapping", "sourcePriority", "projectPath", "scope", "access", "memberPattern"];
+    for (const field of stringFields) {
+        const value = source[field];
+        if (typeof value === "string" && value.trim()) {
+            result[field] = value;
+        }
+    }
+    const numericFields = tool === "get-class-source"
+        ? ["startLine", "endLine", "maxLines", "maxChars"]
+        : ["maxMembers"];
+    for (const field of numericFields) {
+        const value = source[field];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            result[field] = value;
+        }
+    }
+    const booleanFields = tool === "get-class-source"
+        ? ["allowDecompile", "preferProjectVersion", "strictVersion"]
+        : ["allowDecompile", "preferProjectVersion", "strictVersion", "includeSynthetic", "includeInherited"];
+    for (const field of booleanFields) {
+        const value = source[field];
+        if (typeof value === "boolean") {
+            result[field] = value;
+        }
+    }
+    return result;
+}
+function copyValidateMixinSharedParams(source) {
+    const result = {};
+    const stringFields = [
+        "version",
+        "mapping",
+        "sourcePriority",
+        "scope",
+        "projectPath",
+        "minSeverity",
+        "warningMode",
+        "reportMode"
+    ];
+    for (const field of stringFields) {
+        const value = source[field];
+        if (typeof value === "string" && value.trim()) {
+            result[field] = value;
+        }
+    }
+    const booleanFields = [
+        "preferProjectVersion",
+        "hideUncertain",
+        "explain",
+        "preferProjectMapping",
+        "treatInfoAsWarning",
+        "includeIssues"
+    ];
+    for (const field of booleanFields) {
+        const value = source[field];
+        if (typeof value === "boolean") {
+            result[field] = value;
+        }
+    }
+    const sourceRoots = asStringArray(source.sourceRoots);
+    if (sourceRoots) {
+        result.sourceRoots = sourceRoots;
+    }
+    const warningCategoryFilter = asStringArray(source.warningCategoryFilter);
+    if (warningCategoryFilter) {
+        result.warningCategoryFilter = warningCategoryFilter;
+    }
+    return result;
+}
+function buildValidateMixinSuggestedParams(normalizedInput) {
+    const record = asObjectRecord(normalizedInput);
+    if (!record) {
+        return {
+            input: {
+                mode: "inline",
+                source: "<Mixin Java source>"
+            },
+            version: "<minecraft-version>"
+        };
+    }
+    const inputRecord = asObjectRecord(record.input);
+    const shared = copyValidateMixinSharedParams(record);
+    const version = asNonEmptyString(record.version) ?? "<minecraft-version>";
+    const inlineSource = asNonEmptyString(record.input) ??
+        asNonEmptyString(inputRecord?.source) ??
+        asNonEmptyString(record.source);
+    if (inlineSource) {
+        const parsedInlineObject = parseJsonObjectString(inlineSource);
+        if (parsedInlineObject && typeof parsedInlineObject.mode === "string") {
+            return {
+                ...shared,
+                input: parsedInlineObject,
+                version
+            };
+        }
+        return {
+            ...shared,
+            input: {
+                mode: "inline",
+                source: truncateSuggestionText(inlineSource)
+            },
+            version
+        };
+    }
+    const path = asNonEmptyString(inputRecord?.path) ??
+        asNonEmptyString(record.sourcePath);
+    if (path) {
+        return {
+            ...shared,
+            input: {
+                mode: "path",
+                path
+            },
+            version
+        };
+    }
+    const paths = asStringArray(inputRecord?.paths) ??
+        asStringArray(record.sourcePaths);
+    if (paths) {
+        return {
+            ...shared,
+            input: {
+                mode: "paths",
+                paths
+            },
+            version
+        };
+    }
+    const configPaths = asStringArray(inputRecord?.configPaths) ??
+        (asNonEmptyString(record.mixinConfigPath) ? [record.mixinConfigPath] : undefined);
+    if (configPaths) {
+        return {
+            ...shared,
+            input: {
+                mode: "config",
+                configPaths
+            },
+            version
+        };
+    }
+    const projectPath = asNonEmptyString(record.projectPath) ??
+        (inputRecord?.mode === "project" ? asNonEmptyString(inputRecord.path) : undefined);
+    if (projectPath) {
+        return {
+            ...shared,
+            input: {
+                mode: "project",
+                path: projectPath
+            },
+            version
+        };
+    }
+    return {
+        ...shared,
+        input: {
+            mode: "inline",
+            source: "<Mixin Java source>"
+        },
+        version
+    };
+}
+function buildResolveArtifactSuggestedParams(normalizedInput) {
+    const record = asObjectRecord(normalizedInput);
+    if (!record) {
+        return {
+            target: {
+                kind: "version",
+                value: "<minecraft-version>"
+            }
+        };
+    }
+    const targetValue = asNonEmptyString(record.target);
+    const result = {
+        target: targetValue
+            ? {
+                kind: inferTargetKindFromString(targetValue),
+                value: targetValue
+            }
+            : {
+                kind: "version",
+                value: "<minecraft-version>"
+            }
+    };
+    const stringFields = ["mapping", "sourcePriority", "projectPath", "scope"];
+    for (const field of stringFields) {
+        const value = record[field];
+        if (typeof value === "string" && value.trim()) {
+            result[field] = value;
+        }
+    }
+    const booleanFields = ["allowDecompile", "preferProjectVersion", "strictVersion"];
+    for (const field of booleanFields) {
+        const value = record[field];
+        if (typeof value === "boolean") {
+            result[field] = value;
+        }
+    }
+    return result;
+}
+function buildSourceLookupSuggestedParams(tool, normalizedInput) {
+    const record = asObjectRecord(normalizedInput);
+    const result = record ? copySourceLookupSuggestionFields(tool, record) : {};
+    const targetValue = asNonEmptyString(record?.target);
+    result.target = targetValue
+        ? {
+            type: "resolve",
+            kind: inferTargetKindFromString(targetValue),
+            value: targetValue
+        }
+        : {
+            type: "resolve",
+            kind: "version",
+            value: "<minecraft-version>"
+        };
+    if (!asNonEmptyString(result.className)) {
+        result.className = "<fully-qualified-class-name>";
+    }
+    return result;
+}
+function buildInvalidInputGuidance(tool, normalizedInput) {
+    if (tool === "validate-mixin") {
+        const hints = [
+            "validate-mixin.input must be an object with input.mode = \"inline\" | \"path\" | \"paths\" | \"config\" | \"project\".",
+            "Whole-project example: {\"input\":{\"mode\":\"project\",\"path\":\"/workspace\"},\"version\":\"1.21.10\",\"preferProjectVersion\":true,\"preferProjectMapping\":true}.",
+            "Legacy top-level source/sourcePath/sourcePaths/mixinConfigPath fields are no longer accepted; wrap them under input.mode instead."
+        ];
+        return {
+            hints,
+            suggestedCall: {
+                tool,
+                params: buildValidateMixinSuggestedParams(normalizedInput)
+            }
+        };
+    }
+    if (tool === "resolve-artifact") {
+        return {
+            hints: [
+                "resolve-artifact.target must be an object: {\"kind\":\"version|jar|coordinate\",\"value\":\"...\"}.",
+                "Bare string targets are not accepted; wrap the value under target.kind and target.value."
+            ],
+            suggestedCall: {
+                tool,
+                params: buildResolveArtifactSuggestedParams(normalizedInput)
+            }
+        };
+    }
+    if (tool === "get-class-source" || tool === "get-class-members") {
+        return {
+            hints: [
+                `${tool}.target must be an object: {"type":"resolve","kind":"version|jar|coordinate","value":"..."} or {"type":"artifact","artifactId":"..."}.`,
+                "Bare string targets are not accepted; wrap the value under target.type/target.kind/target.value."
+            ],
+            suggestedCall: {
+                tool,
+                params: buildSourceLookupSuggestedParams(tool, normalizedInput)
+            }
+        };
+    }
+    return undefined;
+}
+function mapErrorToProblem(caughtError, requestId, context) {
     if (caughtError instanceof ZodError) {
+        const guidance = context?.tool
+            ? buildInvalidInputGuidance(context.tool, context.normalizedInput)
+            : undefined;
         return {
             type: "https://minecraft-modding-mcp.dev/problems/invalid-input",
             title: "Invalid input",
@@ -811,7 +1117,8 @@ function mapErrorToProblem(caughtError, requestId) {
             code: ERROR_CODES.INVALID_INPUT,
             instance: requestId,
             fieldErrors: toFieldErrorsFromZod(caughtError),
-            hints: ["Check fieldErrors and submit a valid tool argument payload."]
+            hints: guidance?.hints ?? ["Check fieldErrors and submit a valid tool argument payload."],
+            ...(guidance?.suggestedCall ? { suggestedCall: guidance.suggestedCall } : {})
         };
     }
     if (isAppError(caughtError)) {
@@ -856,9 +1163,35 @@ function splitWarnings(data) {
 async function runTool(tool, rawInput, schema, action) {
     const requestId = buildRequestId();
     const startedAt = Date.now();
+    let normalizedInput = rawInput;
     try {
-        const parsedInput = schema.parse(rawInput);
-        const payload = await action(parsedInput);
+        const preparedInput = prepareToolInput(rawInput);
+        normalizedInput = preparedInput.normalizedInput;
+        const { removedOfficialPaths, suggestedReplacementInput } = preparedInput;
+        if (removedOfficialPaths.length > 0) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `The "official" mapping namespace was removed. Use "obfuscated" instead.`,
+                details: {
+                    fieldErrors: removedOfficialPaths.map((path) => ({
+                        path,
+                        message: `"official" is no longer supported for this field. Use "obfuscated".`,
+                        code: "invalid_enum_value"
+                    })),
+                    nextAction: `Replace "official" with "obfuscated" in mapping-related fields and retry.`,
+                    suggestedCall: suggestedReplacementInput
+                        ? {
+                            tool,
+                            params: suggestedReplacementInput
+                        }
+                        : undefined
+                }
+            });
+        }
+        const parsedInput = schema.parse(normalizedInput);
+        const payload = await (HEAVY_TOOL_NAMES.has(tool)
+            ? heavyToolExecutionGate.run(tool, () => action(parsedInput))
+            : action(parsedInput));
         const { result, warnings } = splitWarnings(payload);
         return objectResult({
             result,
@@ -871,7 +1204,10 @@ async function runTool(tool, rawInput, schema, action) {
         });
     }
     catch (caughtError) {
-        const problem = mapErrorToProblem(caughtError, requestId);
+        const problem = mapErrorToProblem(caughtError, requestId, {
+            tool,
+            normalizedInput
+        });
         if (isAppError(caughtError)) {
             const isSevere = caughtError.code === ERROR_CODES.DB_FAILURE ||
                 caughtError.code === ERROR_CODES.REPO_FETCH_FAILED ||
@@ -910,18 +1246,15 @@ async function runTool(tool, rawInput, schema, action) {
                 durationMs: Date.now() - startedAt,
                 warnings: []
             }
-        });
+        }, { isError: true });
     }
 }
 server.tool("list-versions", "List available Minecraft versions from Mojang manifest and locally cached version jars.", listVersionsShape, { readOnlyHint: true }, async (args) => runTool("list-versions", args, listVersionsSchema, async (input) => sourceService.listVersions({
     includeSnapshots: input.includeSnapshots,
     limit: input.limit
 })));
-server.tool("resolve-artifact", "Resolve source artifact from version, jar path, or Maven coordinate and return artifact metadata. For targetKind=jar, only <basename>-sources.jar is auto-adopted; other adjacent *-sources.jar files are informational.", resolveArtifactShape, { readOnlyHint: true }, async (args) => runTool("resolve-artifact", args, resolveArtifactSchema, async (input) => sourceService.resolveArtifact({
-    target: {
-        kind: input.targetKind,
-        value: input.targetValue
-    },
+server.tool("resolve-artifact", "Resolve source artifact from a target object ({ kind, value }) and return artifact metadata. For target.kind=jar, only <basename>-sources.jar is auto-adopted; other adjacent *-sources.jar files are informational.", resolveArtifactShape, { readOnlyHint: true }, async (args) => runTool("resolve-artifact", args, resolveArtifactSchema, async (input) => sourceService.resolveArtifact({
+    target: input.target,
     mapping: input.mapping,
     sourcePriority: input.sourcePriority,
     allowDecompile: input.allowDecompile,
@@ -941,42 +1274,48 @@ server.tool("find-class", "Resolve a simple or qualified class name to fully-qua
     artifactId: input.artifactId,
     limit: input.limit
 })));
-server.tool("get-class-source", "Get Java source for a class by artifactId or by resolving target (version/jar/coordinate). Default mode=metadata returns symbol outline only; use mode=snippet for bounded excerpts or mode=full for entire source.", getClassSourceShape, { readOnlyHint: true }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => sourceService.getClassSource({
-    className: input.className,
-    mode: input.mode,
-    artifactId: input.artifactId,
-    target: buildTarget(input.targetKind, input.targetValue),
-    mapping: input.mapping,
-    sourcePriority: input.sourcePriority,
-    allowDecompile: input.allowDecompile,
-    projectPath: input.projectPath,
-    scope: input.scope,
-    preferProjectVersion: input.preferProjectVersion,
-    strictVersion: input.strictVersion,
-    startLine: input.startLine,
-    endLine: input.endLine,
-    maxLines: input.maxLines,
-    maxChars: input.maxChars,
-    outputFile: input.outputFile
-})));
-server.tool("get-class-members", "Get fields/methods/constructors for one class from binary bytecode by artifactId or by resolving target (version/jar/coordinate).", getClassMembersShape, { readOnlyHint: true }, async (args) => runTool("get-class-members", args, getClassMembersSchema, async (input) => sourceService.getClassMembers({
-    className: input.className,
-    artifactId: input.artifactId,
-    target: buildTarget(input.targetKind, input.targetValue),
-    mapping: input.mapping,
-    sourcePriority: input.sourcePriority,
-    allowDecompile: input.allowDecompile,
-    access: input.access,
-    includeSynthetic: input.includeSynthetic,
-    includeInherited: input.includeInherited,
-    memberPattern: input.memberPattern,
-    maxMembers: input.maxMembers,
-    projectPath: input.projectPath,
-    scope: input.scope,
-    preferProjectVersion: input.preferProjectVersion,
-    strictVersion: input.strictVersion
-})));
-server.tool("search-class-source", "Search indexed class source files for one artifact with symbol/text/path intent and optional one-hop relation expansion.", searchClassSourceShape, { readOnlyHint: true }, async (args) => runTool("search-class-source", args, searchClassSourceSchema, async (input) => {
+server.tool("get-class-source", "Get Java source for a class by target ({ type: 'artifact', artifactId } or { type: 'resolve', kind, value }). Default mode=metadata returns symbol outline only; use mode=snippet for bounded excerpts or mode=full for entire source.", getClassSourceShape, { readOnlyHint: true }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => {
+    const normalizedTarget = normalizeSourceLookupTarget(input.target);
+    return sourceService.getClassSource({
+        className: input.className,
+        mode: input.mode,
+        artifactId: normalizedTarget.artifactId,
+        target: normalizedTarget.target,
+        mapping: input.mapping,
+        sourcePriority: input.sourcePriority,
+        allowDecompile: input.allowDecompile,
+        projectPath: input.projectPath,
+        scope: input.scope,
+        preferProjectVersion: input.preferProjectVersion,
+        strictVersion: input.strictVersion,
+        startLine: input.startLine,
+        endLine: input.endLine,
+        maxLines: input.maxLines,
+        maxChars: input.maxChars,
+        outputFile: input.outputFile
+    });
+}));
+server.tool("get-class-members", "Get fields/methods/constructors for one class from binary bytecode by target ({ type: 'artifact', artifactId } or { type: 'resolve', kind, value }).", getClassMembersShape, { readOnlyHint: true }, async (args) => runTool("get-class-members", args, getClassMembersSchema, async (input) => {
+    const normalizedTarget = normalizeSourceLookupTarget(input.target);
+    return sourceService.getClassMembers({
+        className: input.className,
+        artifactId: normalizedTarget.artifactId,
+        target: normalizedTarget.target,
+        mapping: input.mapping,
+        sourcePriority: input.sourcePriority,
+        allowDecompile: input.allowDecompile,
+        access: input.access,
+        includeSynthetic: input.includeSynthetic,
+        includeInherited: input.includeInherited,
+        memberPattern: input.memberPattern,
+        maxMembers: input.maxMembers,
+        projectPath: input.projectPath,
+        scope: input.scope,
+        preferProjectVersion: input.preferProjectVersion,
+        strictVersion: input.strictVersion
+    });
+}));
+server.tool("search-class-source", "Search indexed class source files for one artifact with symbol/text/path intent and compact hit output.", searchClassSourceShape, { readOnlyHint: true }, async (args) => runTool("search-class-source", args, searchClassSourceSchema, async (input) => {
     const scope = input.packagePrefix || input.fileGlob || input.symbolKind
         ? {
             packagePrefix: input.packagePrefix,
@@ -984,22 +1323,12 @@ server.tool("search-class-source", "Search indexed class source files for one ar
             symbolKind: input.symbolKind
         }
         : undefined;
-    const include = input.snippetLines !== undefined ||
-        input.includeDefinition !== undefined ||
-        input.includeOneHop !== undefined
-        ? {
-            snippetLines: input.snippetLines,
-            includeDefinition: input.includeDefinition,
-            includeOneHop: input.includeOneHop
-        }
-        : undefined;
     return sourceService.searchClassSource({
         artifactId: input.artifactId,
         query: input.query,
         intent: input.intent,
         match: input.match,
         scope: scope,
-        include,
         queryMode: input.queryMode,
         limit: input.limit,
         cursor: input.cursor
@@ -1027,7 +1356,8 @@ server.tool("diff-class-signatures", "Compare one class signature between two Mi
     fromVersion: input.fromVersion,
     toVersion: input.toVersion,
     mapping: input.mapping,
-    sourcePriority: input.sourcePriority
+    sourcePriority: input.sourcePriority,
+    includeFullDiff: input.includeFullDiff
 })));
 server.tool("find-mapping", "Find symbol mapping candidates between namespaces using structured symbol inputs for a specific Minecraft version.", findMappingShape, { readOnlyHint: true }, async (args) => runTool("find-mapping", args, findMappingSchema, async (input) => sourceService.findMapping({
     version: input.version,
@@ -1038,24 +1368,26 @@ server.tool("find-mapping", "Find symbol mapping candidates between namespaces u
     sourceMapping: input.sourceMapping,
     targetMapping: input.targetMapping,
     sourcePriority: input.sourcePriority,
-    disambiguation: input.disambiguation
+    disambiguation: input.disambiguation,
+    maxCandidates: input.maxCandidates
 })));
 server.tool("resolve-method-mapping-exact", "Resolve one method mapping exactly by owner+name+descriptor between namespaces and report resolved/not_found/ambiguous.", resolveMethodMappingExactShape, { readOnlyHint: true }, async (args) => runTool("resolve-method-mapping-exact", args, resolveMethodMappingExactSchema, async (input) => sourceService.resolveMethodMappingExact({
     version: input.version,
-    kind: input.kind,
     name: input.name,
     owner: input.owner,
     descriptor: input.descriptor,
     sourceMapping: input.sourceMapping,
     targetMapping: input.targetMapping,
-    sourcePriority: input.sourcePriority
+    sourcePriority: input.sourcePriority,
+    maxCandidates: input.maxCandidates
 })));
-server.tool("get-class-api-matrix", "List class/member API rows across official/mojang/intermediary/yarn mappings for one class and Minecraft version.", getClassApiMatrixShape, { readOnlyHint: true }, async (args) => runTool("get-class-api-matrix", args, getClassApiMatrixSchema, async (input) => sourceService.getClassApiMatrix({
+server.tool("get-class-api-matrix", "List class/member API rows across obfuscated/mojang/intermediary/yarn mappings for one class and Minecraft version.", getClassApiMatrixShape, { readOnlyHint: true }, async (args) => runTool("get-class-api-matrix", args, getClassApiMatrixSchema, async (input) => sourceService.getClassApiMatrix({
     version: input.version,
     className: input.className,
     classNameMapping: input.classNameMapping,
     includeKinds: parseClassApiKinds(input.includeKinds),
-    sourcePriority: input.sourcePriority
+    sourcePriority: input.sourcePriority,
+    maxRows: input.maxRows
 })));
 server.tool("resolve-workspace-symbol", "Resolve class/field/method names as seen at compile time for a workspace by reading Gradle Loom mapping settings.", resolveWorkspaceSymbolShape, { readOnlyHint: true }, async (args) => runTool("resolve-workspace-symbol", args, resolveWorkspaceSymbolSchema, async (input) => sourceService.resolveWorkspaceSymbol({
     projectPath: input.projectPath,
@@ -1065,7 +1397,8 @@ server.tool("resolve-workspace-symbol", "Resolve class/field/method names as see
     owner: input.owner,
     descriptor: input.descriptor,
     sourceMapping: input.sourceMapping,
-    sourcePriority: input.sourcePriority
+    sourcePriority: input.sourcePriority,
+    maxCandidates: input.maxCandidates
 })));
 server.tool("check-symbol-exists", "Check whether a class/field/method symbol exists in a specific mapping namespace for one Minecraft version.", checkSymbolExistsShape, { readOnlyHint: true }, async (args) => runTool("check-symbol-exists", args, checkSymbolExistsSchema, async (input) => sourceService.checkSymbolExists({
     version: input.version,
@@ -1076,7 +1409,8 @@ server.tool("check-symbol-exists", "Check whether a class/field/method symbol ex
     sourceMapping: input.sourceMapping,
     sourcePriority: input.sourcePriority,
     nameMode: input.nameMode,
-    signatureMode: input.signatureMode
+    signatureMode: input.signatureMode,
+    maxCandidates: input.maxCandidates
 })));
 server.tool("nbt-to-json", "Decode Java Edition NBT binary payload (base64) into typed JSON.", nbtToJsonShape, { readOnlyHint: true }, async (args) => runTool("nbt-to-json", args, nbtToJsonSchema, async (input) => Promise.resolve(nbtBase64ToTypedJson({
     nbtBase64: input.nbtBase64,
@@ -1096,11 +1430,7 @@ server.tool("index-artifact", "Rebuild indexed files/symbols metadata for an exi
 })));
 server.tool("get-runtime-metrics", "Get runtime service counters and latency snapshots for cache/search/index diagnostics.", { readOnlyHint: true }, async (args) => runTool("get-runtime-metrics", args, emptySchema, async () => Promise.resolve(sourceService.getRuntimeMetrics())));
 server.tool("validate-mixin", "Validate Mixin source against Minecraft bytecode signatures for a given version.", validateMixinShape, { readOnlyHint: true }, async (args) => runTool("validate-mixin", args, validateMixinSchema, async (input) => sourceService.validateMixin({
-    source: input.source,
-    sourcePath: input.sourcePath,
-    sourcePaths: input.sourcePaths,
-    mixinConfigPath: input.mixinConfigPath,
-    sourceRoot: input.sourceRoot,
+    input: input.input,
     sourceRoots: input.sourceRoots,
     version: input.version,
     mapping: input.mapping,
@@ -1115,7 +1445,8 @@ server.tool("validate-mixin", "Validate Mixin source against Minecraft bytecode
     preferProjectMapping: input.preferProjectMapping,
     reportMode: input.reportMode,
     warningCategoryFilter: input.warningCategoryFilter,
-    treatInfoAsWarning: input.treatInfoAsWarning
+    treatInfoAsWarning: input.treatInfoAsWarning,
+    includeIssues: input.includeIssues
 })));
 server.tool("validate-access-widener", "Validate Access Widener file entries against Minecraft bytecode signatures for a given version.", validateAccessWidenerShape, { readOnlyHint: true }, async (args) => runTool("validate-access-widener", args, validateAccessWidenerSchema, async (input) => sourceService.validateAccessWidener({
     content: input.content,
@@ -1131,7 +1462,9 @@ server.tool("analyze-mod-jar", "Analyze a Minecraft mod JAR to extract loader ty
 }));
 server.tool("get-registry-data", "Get Minecraft registry data (blocks, items, biomes, etc.) for a specific version by running the server data generator.", getRegistryDataShape, { readOnlyHint: true }, async (args) => runTool("get-registry-data", args, getRegistryDataSchema, async (input) => sourceService.getRegistryData({
     version: input.version,
-    registry: input.registry
+    registry: input.registry,
+    includeData: input.includeData,
+    maxEntriesPerRegistry: input.maxEntriesPerRegistry
 })));
 server.tool("compare-versions", "Compare two Minecraft versions to find added/removed classes and registry entry changes. Useful for understanding what changed between versions during mod migration.", compareVersionsShape, { readOnlyHint: true }, async (args) => runTool("compare-versions", args, compareVersionsSchema, async (input) => sourceService.compareVersions({
     fromVersion: input.fromVersion,
@@ -1142,7 +1475,9 @@ server.tool("compare-versions", "Compare two Minecraft versions to find added/re
 })));
 server.tool("decompile-mod-jar", "Decompile a Minecraft mod JAR using Vineflower and list available classes, or view a specific class source. Builds on analyze-mod-jar by exposing the actual source code.", decompileModJarShape, { readOnlyHint: true }, async (args) => runTool("decompile-mod-jar", args, decompileModJarSchema, async (input) => sourceService.decompileModJar({
     jarPath: input.jarPath,
-    className: input.className
+    className: input.className,
+    includeFiles: input.includeFiles,
+    maxFiles: input.maxFiles
 })));
 server.tool("get-mod-class-source", "Get decompiled source code for a specific class in a mod JAR. The mod JAR will be decompiled if not already cached.", getModClassSourceShape, { readOnlyHint: true }, async (args) => runTool("get-mod-class-source", args, getModClassSourceSchema, async (input) => sourceService.getModClassSource({
     jarPath: input.jarPath,