@adhisang/minecraft-modding-mcp 2.0.0 → 3.0.0

package/dist/index.js

@@ -12,6 +12,16 @@ 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";
+import { WorkspaceMappingService } from "./workspace-mapping-service.js";
+import { InspectMinecraftService, inspectMinecraftSchema, inspectMinecraftShape } from "./entry-tools/inspect-minecraft-service.js";
+import { AnalyzeSymbolService, analyzeSymbolSchema, analyzeSymbolShape } from "./entry-tools/analyze-symbol-service.js";
+import { CompareMinecraftService, compareMinecraftSchema, compareMinecraftShape } from "./entry-tools/compare-minecraft-service.js";
+import { AnalyzeModService, analyzeModSchema, analyzeModShape } from "./entry-tools/analyze-mod-service.js";
+import { ValidateProjectService, validateProjectSchema, validateProjectShape, discoverWorkspaceAccessWideners, discoverWorkspaceMixins } from "./entry-tools/validate-project-service.js";
+import { ManageCacheService, manageCacheSchema, manageCacheShape } from "./entry-tools/manage-cache-service.js";
+import { createCacheRegistry } from "./cache-registry.js";
+import { buildEntryToolMeta } from "./entry-tools/response-contract.js";
 if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "production";
 }
@@ -28,6 +38,24 @@ 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 ENTRY_TOOL_NAMES = new Set([
+    "inspect-minecraft",
+    "analyze-symbol",
+    "compare-minecraft",
+    "analyze-mod",
+    "validate-project",
+    "manage-cache"
+]);
+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();
@@ -59,6 +87,9 @@ const sourceLookupTargetSchema = z.discriminatedUnion("type", [
         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")
@@ -68,12 +99,12 @@ const resolveArtifactShape = {
     target: z.object({
         kind: targetKindSchema,
         value: nonEmptyString
-    }).describe("Resolve target: { kind: version|jar|coordinate, value }"),
+    }).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"),
+    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.")
 };
@@ -81,12 +112,12 @@ 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"),
-    target: sourceLookupTargetSchema.describe("Either { type: 'artifact', artifactId } or { type: 'resolve', kind, value }"),
+    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"),
+    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,
@@ -110,7 +141,7 @@ const getClassSourceSchema = z
 });
 const getClassMembersShape = {
     className: nonEmptyString,
-    target: sourceLookupTargetSchema.describe("Either { type: 'artifact', artifactId } or { type: 'resolve', kind, value }"),
+    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"),
@@ -120,7 +151,7 @@ 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.")
 };
@@ -176,7 +207,8 @@ const diffClassSignaturesShape = {
     fromVersion: nonEmptyString,
     toVersion: nonEmptyString,
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    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 = {
@@ -194,7 +226,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") {
@@ -260,7 +293,8 @@ const resolveMethodMappingExactShape = {
     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")
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
 };
 const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
@@ -298,7 +332,8 @@ const getClassApiMatrixShape = {
     className: nonEmptyString,
     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 = {
@@ -309,7 +344,8 @@ const resolveWorkspaceSymbolShape = {
     owner: optionalNonEmptyString,
     descriptor: optionalNonEmptyString,
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    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)
@@ -380,7 +416,8 @@ const checkSymbolExistsShape = {
     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") {
@@ -483,14 +520,18 @@ const validateMixinShape = {
         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("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()
@@ -503,12 +544,14 @@ 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);
 const validateAccessWidenerShape = {
@@ -525,7 +568,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"];
@@ -540,7 +585,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 = {
@@ -588,6 +635,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,
@@ -606,6 +656,50 @@ const sourceService = new Proxy({}, {
         return typeof value === "function" ? value.bind(service) : value;
     }
 });
+const workspaceMappingService = new WorkspaceMappingService();
+const inspectMinecraftService = new InspectMinecraftService({
+    listVersions: (input) => sourceService.listVersions(input),
+    resolveArtifact: (input) => sourceService.resolveArtifact(input),
+    findClass: (input) => Promise.resolve(sourceService.findClass(input)),
+    getClassSource: (input) => sourceService.getClassSource(input),
+    getClassMembers: (input) => sourceService.getClassMembers(input),
+    searchClassSource: (input) => sourceService.searchClassSource(input),
+    getArtifactFile: (input) => sourceService.getArtifactFile(input),
+    listArtifactFiles: (input) => sourceService.listArtifactFiles(input),
+    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath)
+});
+const analyzeSymbolService = new AnalyzeSymbolService({
+    checkSymbolExists: (input) => sourceService.checkSymbolExists(input),
+    findMapping: (input) => sourceService.findMapping(input),
+    resolveMethodMappingExact: (input) => sourceService.resolveMethodMappingExact(input),
+    traceSymbolLifecycle: (input) => sourceService.traceSymbolLifecycle(input),
+    resolveWorkspaceSymbol: (input) => sourceService.resolveWorkspaceSymbol(input),
+    getClassApiMatrix: (input) => sourceService.getClassApiMatrix(input)
+});
+const compareMinecraftService = new CompareMinecraftService({
+    compareVersions: (input) => sourceService.compareVersions(input),
+    diffClassSignatures: (input) => sourceService.diffClassSignatures(input),
+    getRegistryData: (input) => sourceService.getRegistryData(input)
+});
+const analyzeModService = new AnalyzeModService({
+    analyzeModJar: (jarPath, options) => analyzeModJar(jarPath, options),
+    decompileModJar: (input) => sourceService.decompileModJar(input),
+    getModClassSource: (input) => sourceService.getModClassSource(input),
+    searchModSource: (input) => sourceService.searchModSource(input),
+    remapModJar: (input) => remapModJar(input, config)
+});
+const validateProjectService = new ValidateProjectService({
+    validateMixin: (input) => sourceService.validateMixin(input),
+    validateAccessWidener: (input) => sourceService.validateAccessWidener(input),
+    discoverMixins: discoverWorkspaceMixins,
+    discoverAccessWideners: discoverWorkspaceAccessWideners
+});
+const manageCacheService = new ManageCacheService({
+    registry: createCacheRegistry({
+        cacheDir: config.cacheDir,
+        sqlitePath: config.sqlitePath
+    })
+});
 registerResources(server, sourceService);
 let processHandlersAttached = false;
 let serverStarted = false;
@@ -768,8 +862,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",
@@ -778,7 +1178,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)) {
@@ -806,25 +1207,37 @@ function mapErrorToProblem(caughtError, requestId) {
 }
 function splitWarnings(data) {
     const result = { ...data };
+    const warnings = [];
     const maybeWarnings = result.warnings;
-    if (!Array.isArray(maybeWarnings)) {
-        return {
-            result,
-            warnings: []
-        };
+    if (Array.isArray(maybeWarnings)) {
+        warnings.push(...maybeWarnings.filter((entry) => typeof entry === "string"));
+        delete result.warnings;
+    }
+    let meta = {};
+    const maybeMeta = result.meta;
+    if (maybeMeta && typeof maybeMeta === "object" && !Array.isArray(maybeMeta)) {
+        meta = { ...maybeMeta };
+        delete result.meta;
+        const metaWarnings = meta.warnings;
+        if (Array.isArray(metaWarnings)) {
+            warnings.push(...metaWarnings.filter((entry) => typeof entry === "string"));
+            delete meta.warnings;
+        }
     }
-    const warnings = maybeWarnings.filter((entry) => typeof entry === "string");
-    delete result.warnings;
     return {
         result,
-        warnings
+        warnings: [...new Set(warnings)],
+        meta
     };
 }
 async function runTool(tool, rawInput, schema, action) {
     const requestId = buildRequestId();
     const startedAt = Date.now();
+    let normalizedInput = rawInput;
     try {
-        const { normalizedInput, removedOfficialPaths, suggestedReplacementInput } = prepareToolInput(rawInput);
+        const preparedInput = prepareToolInput(rawInput);
+        normalizedInput = preparedInput.normalizedInput;
+        const { removedOfficialPaths, suggestedReplacementInput } = preparedInput;
         if (removedOfficialPaths.length > 0) {
             throw createError({
                 code: ERROR_CODES.INVALID_INPUT,
@@ -846,11 +1259,31 @@ async function runTool(tool, rawInput, schema, action) {
             });
         }
         const parsedInput = schema.parse(normalizedInput);
-        const payload = await action(parsedInput);
-        const { result, warnings } = splitWarnings(payload);
+        const payload = await (HEAVY_TOOL_NAMES.has(tool)
+            ? heavyToolExecutionGate.run(tool, () => action(parsedInput))
+            : action(parsedInput));
+        const { result, warnings, meta: resultMeta } = splitWarnings(payload);
+        const entryMeta = ENTRY_TOOL_NAMES.has(tool)
+            ? buildEntryToolMeta({
+                detail: normalizedInput &&
+                    typeof normalizedInput === "object" &&
+                    !Array.isArray(normalizedInput) &&
+                    typeof normalizedInput.detail === "string"
+                    ? normalizedInput.detail ?? "summary"
+                    : "summary",
+                include: normalizedInput &&
+                    typeof normalizedInput === "object" &&
+                    !Array.isArray(normalizedInput) &&
+                    Array.isArray(normalizedInput.include)
+                    ? normalizedInput.include
+                    : undefined
+            })
+            : undefined;
         return objectResult({
             result,
             meta: {
+                ...(entryMeta ?? {}),
+                ...resultMeta,
                 requestId,
                 tool,
                 durationMs: Date.now() - startedAt,
@@ -859,7 +1292,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 ||
@@ -905,6 +1341,12 @@ server.tool("list-versions", "List available Minecraft versions from Mojang mani
     includeSnapshots: input.includeSnapshots,
     limit: input.limit
 })));
+server.tool("inspect-minecraft", "High-level v3 entry tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings.", inspectMinecraftShape, { readOnlyHint: true }, async (args) => runTool("inspect-minecraft", args, inspectMinecraftSchema, async (input) => inspectMinecraftService.execute(input)));
+server.tool("analyze-symbol", "High-level v3 entry tool for symbol existence, mapping, lifecycle, workspace analysis, and API overview.", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
+server.tool("compare-minecraft", "High-level v3 entry tool for version comparisons, class diffs, registry diffs, and migration overviews.", compareMinecraftShape, { readOnlyHint: true }, async (args) => runTool("compare-minecraft", args, compareMinecraftSchema, async (input) => compareMinecraftService.execute(input)));
+server.tool("analyze-mod", "High-level v3 entry tool for mod metadata inspection, decompile/search flows, class source, and safe remap previews/applies.", analyzeModShape, { readOnlyHint: false }, async (args) => runTool("analyze-mod", args, analyzeModSchema, async (input) => analyzeModService.execute(input)));
+server.tool("validate-project", "High-level v3 entry tool for project summary, direct mixin validation, and access widener validation.", validateProjectShape, { readOnlyHint: true }, async (args) => runTool("validate-project", args, validateProjectSchema, async (input) => validateProjectService.execute(input)));
+server.tool("manage-cache", "High-level v3 entry tool for cache summaries, listing, verification, previewed mutation, and explicit apply operations.", manageCacheShape, { readOnlyHint: false }, async (args) => runTool("manage-cache", args, manageCacheSchema, async (input) => manageCacheService.execute(input)));
 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,
@@ -1008,7 +1450,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,
@@ -1019,7 +1462,8 @@ 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,
@@ -1028,14 +1472,16 @@ server.tool("resolve-method-mapping-exact", "Resolve one method mapping exactly
     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 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,
@@ -1045,7 +1491,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,
@@ -1056,7 +1503,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,
@@ -1091,7 +1539,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,
@@ -1107,7 +1556,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,
@@ -1118,7 +1569,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,