@adhisang/minecraft-modding-mcp 1.1.0 → 1.2.0

package/dist/decompiler/vineflower.js

@@ -1,11 +1,16 @@
 import { access, constants } from "node:fs/promises";
-import { mkdirSync, readdirSync, statSync } from "node:fs";
+import { mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, join, relative, sep } from "node:path";
 import { createError, ERROR_CODES, isAppError } from "../errors.js";
 import { assertJavaAvailable, runJavaProcess } from "../java-process.js";
 import { log } from "../logger.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
+const VINEFLOWER_FLAG_PROFILES = [
+    { label: "default", flags: ["-din=1", "-rbr=1", "-dgs=1"] },
+    { label: "relaxed", flags: ["-din=1", "-rbr=0", "-dgs=0"] },
+    { label: "safe", flags: ["-din=0", "-rbr=0", "-dgs=0"] },
+];
 function emitDecompileLog(event, details) {
     log(event === "decompile.error" ? "error" : "info", event, details);
 }
@@ -83,10 +88,14 @@ function decompileOutputDir(cacheDir, binaryJarPath, signature) {
     const digest = createHash("sha256").update(binaryJarPath).update(signature).digest("hex");
     return join(cacheDir, "decompiled", digest);
 }
-async function runVineflower(vineflowerJarPath, binaryJarPath, outputDir, timeoutMs) {
+function clearOutputDir(dir) {
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+}
+async function runVineflower(vineflowerJarPath, binaryJarPath, outputDir, timeoutMs, flags = VINEFLOWER_FLAG_PROFILES[0].flags) {
     const result = await runJavaProcess({
         jarPath: vineflowerJarPath,
-        args: [binaryJarPath, outputDir, "-din=1", "-rbr=1", "-dgs=1"],
+        args: [...flags, binaryJarPath, outputDir],
         timeoutMs,
         normalizePathArgs: true
     });
@@ -97,8 +106,8 @@ async function runVineflower(vineflowerJarPath, binaryJarPath, outputDir, timeou
             details: {
                 binaryJarPath,
                 outputDir,
-                code: result.exitCode,
-                stdout: result.stdoutTail,
+                exitCode: result.exitCode,
+                stdoutTail: result.stdoutTail,
                 stderrTail: result.stderrTail
             }
         });
@@ -145,31 +154,71 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
                 };
             }
         }
-        await runVineflower(options.vineflowerJarPath, normalizedBinaryJarPath, outputDir, timeoutMs);
-        const javaFileNames = await collectJavaFiles(outputDir);
-        if (javaFileNames.length === 0) {
-            throw createError({
-                code: ERROR_CODES.DECOMPILER_FAILED,
-                message: "No Java files were produced by decompilation.",
-                details: { binaryJarPath: normalizedBinaryJarPath, outputDir }
-            });
+        const profilesAttempted = [];
+        let lastDecompileError;
+        for (const profile of VINEFLOWER_FLAG_PROFILES) {
+            profilesAttempted.push(profile.label);
+            try {
+                if (profilesAttempted.length > 1) {
+                    clearOutputDir(outputDir);
+                    emitDecompileLog("decompile.retry", {
+                        binaryJarPath: normalizedBinaryJarPath,
+                        profile: profile.label,
+                        attempt: profilesAttempted.length
+                    });
+                }
+                await runVineflower(options.vineflowerJarPath, normalizedBinaryJarPath, outputDir, timeoutMs, profile.flags);
+                const javaFileNames = await collectJavaFiles(outputDir);
+                if (javaFileNames.length === 0) {
+                    throw createError({
+                        code: ERROR_CODES.DECOMPILER_FAILED,
+                        message: "No Java files were produced by decompilation.",
+                        details: {
+                            binaryJarPath: normalizedBinaryJarPath,
+                            outputDir,
+                            producedJavaCount: 0,
+                            profile: profile.label
+                        }
+                    });
+                }
+                const javaFiles = await Promise.all(javaFileNames.map(async (candidate) => {
+                    const abs = join(outputDir, candidate);
+                    return {
+                        filePath: normalizeOutputPath(outputDir, abs),
+                        content: await readFileTreeText(abs)
+                    };
+                }));
+                emitDecompileLog("decompile.done", {
+                    durationMs: Date.now() - startedAt,
+                    artifactIdCandidate: options.artifactIdCandidate,
+                    javaFileCount: javaFiles.length,
+                    profile: profile.label
+                });
+                return {
+                    outputDir,
+                    javaFiles,
+                    decompileProfile: profile.label
+                };
+            }
+            catch (retryError) {
+                if (isAppError(retryError) && retryError.code !== ERROR_CODES.DECOMPILER_FAILED) {
+                    throw retryError;
+                }
+                lastDecompileError = retryError;
+            }
         }
-        const javaFiles = await Promise.all(javaFileNames.map(async (candidate) => {
-            const abs = join(outputDir, candidate);
-            return {
-                filePath: normalizeOutputPath(outputDir, abs),
-                content: await readFileTreeText(abs)
-            };
-        }));
-        emitDecompileLog("decompile.done", {
-            durationMs: Date.now() - startedAt,
-            artifactIdCandidate: options.artifactIdCandidate,
-            javaFileCount: javaFiles.length
-        });
-        return {
-            outputDir,
-            javaFiles
-        };
+        throw isAppError(lastDecompileError)
+            ? createError({
+                code: ERROR_CODES.DECOMPILER_FAILED,
+                message: `Decompilation failed after trying all flag profiles.`,
+                details: {
+                    binaryJarPath: normalizedBinaryJarPath,
+                    outputDir,
+                    profilesAttempted,
+                    stderrTail: extractStderrTail(lastDecompileError)
+                }
+            })
+            : lastDecompileError;
     }
     catch (error) {
         emitDecompileLog("decompile.error", {

package/dist/index.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ZodError, z } from "zod";
+import { CompatStdioServerTransport } from "./compat-stdio-transport.js";
 import { objectResult } from "./mcp-helpers.js";
 import { loadConfig } from "./config.js";
 import { ERROR_CODES, isAppError } from "./errors.js";
@@ -22,6 +22,9 @@ const SEARCH_MATCHES = ["exact", "prefix", "contains", "regex"];
 const SEARCH_SYMBOL_KINDS = ["class", "interface", "enum", "record", "method", "field"];
 const MEMBER_ACCESS = ["public", "all"];
 const WORKSPACE_SYMBOL_KINDS = ["class", "field", "method"];
+const CLASS_NAME_MODES = ["fqcn", "auto"];
+const SOURCE_MODES = ["metadata", "snippet", "full"];
+const ARTIFACT_SCOPES = ["vanilla", "merged", "loader"];
 const DECODE_COMPRESSIONS = ["none", "gzip", "auto"];
 const ENCODE_COMPRESSIONS = ["none", "gzip"];
 const nonEmptyString = z.string().trim().min(1);
@@ -35,6 +38,9 @@ const searchMatchSchema = z.enum(SEARCH_MATCHES);
 const searchSymbolKindSchema = z.enum(SEARCH_SYMBOL_KINDS);
 const memberAccessSchema = z.enum(MEMBER_ACCESS);
 const workspaceSymbolKindSchema = z.enum(WORKSPACE_SYMBOL_KINDS);
+const classNameModeSchema = z.enum(CLASS_NAME_MODES);
+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) {
@@ -75,20 +81,31 @@ const resolveArtifactShape = {
     targetValue: nonEmptyString,
     mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    allowDecompile: z.boolean().optional().describe("default true")
+    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"),
+    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"),
     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"),
+    strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
     startLine: optionalPositiveInt,
     endLine: optionalPositiveInt,
-    maxLines: optionalPositiveInt
+    maxLines: optionalPositiveInt,
+    maxChars: optionalPositiveInt.describe("Hard character limit on sourceText; truncates if exceeded"),
+    outputFile: optionalNonEmptyString.describe("Write source to this file path and return metadata-only response")
 };
 const getClassSourceSchema = z
     .object(getClassSourceShape)
@@ -120,7 +137,11 @@ const getClassMembersShape = {
     includeSynthetic: z.boolean().optional().describe("default false"),
     includeInherited: z.boolean().optional().describe("default false"),
     memberPattern: optionalNonEmptyString,
-    maxMembers: optionalPositiveInt.describe("default 500, max 5000")
+    maxMembers: optionalPositiveInt.describe("default 500, max 5000"),
+    projectPath: optionalNonEmptyString,
+    scope: artifactScopeSchema.optional().describe("vanilla | merged | loader"),
+    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)
@@ -142,6 +163,7 @@ const searchClassSourceShape = {
     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
 };
@@ -187,7 +209,14 @@ const findMappingShape = {
     descriptor: optionalNonEmptyString,
     sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
     targetMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    disambiguation: z
+        .object({
+        ownerHint: optionalNonEmptyString,
+        descriptorHint: optionalNonEmptyString
+    })
+        .partial()
+        .optional()
 };
 const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -390,9 +419,12 @@ const checkSymbolExistsShape = {
     kind: workspaceSymbolKindSchema.describe("class | field | method"),
     owner: optionalNonEmptyString,
     name: nonEmptyString,
-    descriptor: optionalNonEmptyString.describe("required for kind=method"),
+    descriptor: optionalNonEmptyString.describe("required for kind=method unless signatureMode=name-only"),
     sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    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")
 };
 const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -410,7 +442,7 @@ const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((va
                 path: ["descriptor"]
             });
         }
-        if (!value.name.includes(".")) {
+        if (value.nameMode !== "auto" && !value.name.includes(".")) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 message: "name must be fully-qualified class name when kind=class.",
@@ -443,10 +475,10 @@ const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((va
         }
         return;
     }
-    if (!value.descriptor) {
+    if (!value.descriptor && value.signatureMode !== "name-only") {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "descriptor is required when kind=method.",
+            message: "descriptor is required when kind=method (use signatureMode='name-only' to match by name only).",
             path: ["descriptor"]
         });
     }
@@ -479,12 +511,44 @@ const indexArtifactShape = {
 };
 const indexArtifactSchema = z.object(indexArtifactShape);
 const validateMixinShape = {
-    source: nonEmptyString.describe("Mixin Java source text"),
+    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')"),
+    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"),
-    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
+    sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    scope: artifactScopeSchema.optional().describe("vanilla | merged | loader"),
+    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()
+        .describe("'error'=errors only, 'warning'=errors+warnings, 'all'=everything (default 'all')"),
+    hideUncertain: z.boolean().optional()
+        .describe("Omit issues with confidence='uncertain' (default false)"),
+    explain: z.boolean().optional()
+        .describe("When true, enrich each issue with explanation and suggestedCall for agent recovery (default false)"),
+    warningMode: z.enum(["full", "aggregated"]).optional()
+        .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)"),
+    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)")
 };
-const validateMixinSchema = z.object(validateMixinShape);
+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 validateAccessWidenerShape = {
     content: nonEmptyString.describe("Access Widener file content"),
     version: nonEmptyString.describe("Minecraft version"),
@@ -519,7 +583,10 @@ const decompileModJarShape = {
 const decompileModJarSchema = z.object(decompileModJarShape);
 const getModClassSourceShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
-    className: nonEmptyString.describe("Fully-qualified class name (e.g. com.example.MyMixin)")
+    className: nonEmptyString.describe("Fully-qualified class name (e.g. com.example.MyMixin)"),
+    maxLines: optionalPositiveInt.describe("Max lines to return"),
+    maxChars: optionalPositiveInt.describe("Hard character limit; truncates if exceeded"),
+    outputFile: optionalNonEmptyString.describe("Write full source to file, return placeholder in content")
 };
 const getModClassSourceSchema = z.object(getModClassSourceShape);
 const MOD_SEARCH_TYPES = ["class", "method", "field", "content", "all"];
@@ -565,7 +632,18 @@ const nbtLimits = {
     maxInflatedBytes: config.maxNbtInflatedBytes,
     maxResponseBytes: config.maxNbtResponseBytes
 };
-const sourceService = new SourceService(config);
+let sourceServiceInstance;
+function getSourceService() {
+    sourceServiceInstance ??= new SourceService(config);
+    return sourceServiceInstance;
+}
+const sourceService = new Proxy({}, {
+    get(_target, property, _receiver) {
+        const service = getSourceService();
+        const value = Reflect.get(service, property, service);
+        return typeof value === "function" ? value.bind(service) : value;
+    }
+});
 registerResources(server, sourceService);
 let processHandlersAttached = false;
 let serverStarted = false;
@@ -634,6 +712,20 @@ function toHints(details) {
     }
     return hints;
 }
+function toSuggestedCall(details) {
+    if (typeof details !== "object" || details == null) {
+        return undefined;
+    }
+    const maybe = details.suggestedCall;
+    if (typeof maybe !== "object" || maybe == null) {
+        return undefined;
+    }
+    const call = maybe;
+    if (typeof call.tool !== "string" || typeof call.params !== "object" || call.params == null) {
+        return undefined;
+    }
+    return { tool: call.tool, params: call.params };
+}
 function statusForErrorCode(code) {
     if (code === ERROR_CODES.INVALID_INPUT ||
         code === ERROR_CODES.COORDINATE_PARSE_FAILED ||
@@ -723,6 +815,7 @@ function mapErrorToProblem(caughtError, requestId) {
         };
     }
     if (isAppError(caughtError)) {
+        const suggestedCall = toSuggestedCall(caughtError.details);
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -731,7 +824,8 @@ function mapErrorToProblem(caughtError, requestId) {
             code: caughtError.code,
             instance: requestId,
             fieldErrors: extractFieldErrorsFromDetails(caughtError.details),
-            hints: toHints(caughtError.details)
+            hints: toHints(caughtError.details),
+            ...(suggestedCall ? { suggestedCall } : {})
         };
     }
     return {
@@ -830,18 +924,40 @@ server.tool("resolve-artifact", "Resolve source artifact from version, jar path,
     },
     mapping: input.mapping,
     sourcePriority: input.sourcePriority,
-    allowDecompile: input.allowDecompile
+    allowDecompile: input.allowDecompile,
+    projectPath: input.projectPath,
+    scope: input.scope,
+    preferProjectVersion: input.preferProjectVersion,
+    strictVersion: input.strictVersion
 })));
-server.tool("get-class-source", "Get Java source for a class by artifactId or by resolving target (version/jar/coordinate), with optional line-range filtering.", getClassSourceShape, { readOnlyHint: true }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => sourceService.getClassSource({
+const findClassShape = {
+    className: nonEmptyString.describe("Simple name (e.g. Blocks) or fully-qualified name (e.g. net.minecraft.world.level.block.Blocks)"),
+    artifactId: nonEmptyString,
+    limit: optionalPositiveInt.describe("default 20, max 200")
+};
+const findClassSchema = z.object(findClassShape);
+server.tool("find-class", "Resolve a simple or qualified class name to fully-qualified class names within an artifact. Use this before get-class-source when you only have a simple name.", findClassShape, { readOnlyHint: true }, async (args) => runTool("find-class", args, findClassSchema, async (input) => sourceService.findClass({
     className: input.className,
     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
+    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,
@@ -854,7 +970,11 @@ server.tool("get-class-members", "Get fields/methods/constructors for one class
     includeSynthetic: input.includeSynthetic,
     includeInherited: input.includeInherited,
     memberPattern: input.memberPattern,
-    maxMembers: input.maxMembers
+    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) => {
     const scope = input.packagePrefix || input.fileGlob || input.symbolKind
@@ -880,6 +1000,7 @@ server.tool("search-class-source", "Search indexed class source files for one ar
         match: input.match,
         scope: scope,
         include,
+        queryMode: input.queryMode,
         limit: input.limit,
         cursor: input.cursor
     });
@@ -916,7 +1037,8 @@ server.tool("find-mapping", "Find symbol mapping candidates between namespaces u
     descriptor: input.descriptor,
     sourceMapping: input.sourceMapping,
     targetMapping: input.targetMapping,
-    sourcePriority: input.sourcePriority
+    sourcePriority: input.sourcePriority,
+    disambiguation: input.disambiguation
 })));
 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,
@@ -952,7 +1074,9 @@ server.tool("check-symbol-exists", "Check whether a class/field/method symbol ex
     name: input.name,
     descriptor: input.descriptor,
     sourceMapping: input.sourceMapping,
-    sourcePriority: input.sourcePriority
+    sourcePriority: input.sourcePriority,
+    nameMode: input.nameMode,
+    signatureMode: input.signatureMode
 })));
 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,
@@ -973,9 +1097,25 @@ 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,
+    sourceRoots: input.sourceRoots,
     version: input.version,
     mapping: input.mapping,
-    sourcePriority: input.sourcePriority
+    sourcePriority: input.sourcePriority,
+    scope: input.scope,
+    projectPath: input.projectPath,
+    preferProjectVersion: input.preferProjectVersion,
+    minSeverity: input.minSeverity,
+    hideUncertain: input.hideUncertain,
+    explain: input.explain,
+    warningMode: input.warningMode,
+    preferProjectMapping: input.preferProjectMapping,
+    reportMode: input.reportMode,
+    warningCategoryFilter: input.warningCategoryFilter,
+    treatInfoAsWarning: input.treatInfoAsWarning
 })));
 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,
@@ -1006,7 +1146,10 @@ server.tool("decompile-mod-jar", "Decompile a Minecraft mod JAR using Vineflower
 })));
 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,
-    className: input.className
+    className: input.className,
+    maxLines: input.maxLines,
+    maxChars: input.maxChars,
+    outputFile: input.outputFile
 })));
 server.tool("search-mod-source", "Search through decompiled mod JAR source code by class name, method, field, or content pattern. The mod JAR will be decompiled automatically if not already cached.", searchModSourceShape, { readOnlyHint: true }, async (args) => runTool("search-mod-source", args, searchModSourceSchema, async (input) => sourceService.searchModSource({
     jarPath: input.jarPath,
@@ -1034,11 +1177,12 @@ export async function startServer() {
         sqlitePath: config.sqlitePath,
         sourceRepos: config.sourceRepos.length
     });
-    const transport = new StdioServerTransport();
+    const transport = new CompatStdioServerTransport();
     await server.connect(transport);
     // In stdio mode, explicitly resume stdin so JSON-RPC lines are consumed.
     process.stdin.resume();
     serverStarted = true;
+    setImmediate(getSourceService); // Eagerly init SourceService during MCP handshake
 }
 export { server, sourceService, config, SERVER_VERSION };
 //# sourceMappingURL=index.js.map

package/dist/mapping-service.d.ts

@@ -48,6 +48,7 @@ export type SymbolResolutionOutput = {
     candidates: Array<SymbolReference & Pick<MappingLookupCandidate, "matchKind" | "confidence">>;
     warnings: string[];
     provenance?: MappingLookupProvenance;
+    ambiguityReasons?: string[];
 };
 export type FindMappingInput = {
     version: string;
@@ -58,6 +59,10 @@ export type FindMappingInput = {
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    disambiguation?: {
+        ownerHint?: string;
+        descriptorHint?: string;
+    };
 };
 export type FindMappingOutput = SymbolResolutionOutput;
 export type EnsureMappingAvailableInput = {
@@ -112,6 +117,7 @@ export type ClassApiMatrixOutput = {
     classIdentity: Partial<Record<SourceMapping, string>>;
     rows: ClassApiMatrixRow[];
     warnings: string[];
+    ambiguousRowCount?: number;
 };
 export type SymbolExistenceInput = {
     version: string;
@@ -121,6 +127,8 @@ export type SymbolExistenceInput = {
     descriptor?: string;
     sourceMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
+    nameMode?: "fqcn" | "auto";
+    signatureMode?: "exact" | "name-only";
 };
 export type SymbolExistenceOutput = SymbolResolutionOutput;
 export declare class MappingService {
@@ -138,6 +146,20 @@ export declare class MappingService {
     private mapRecordBetweenMappings;
     private mapCandidatesAlongPath;
     private provenanceForPath;
+    /**
+     * Probe the mapping graph health for a given version.
+     * Returns availability of mojang mappings, tiny mappings, and member remap paths.
+     */
+    checkMappingHealth(input: {
+        version: string;
+        requestedMapping: SourceMapping;
+        sourcePriority?: MappingSourcePriority;
+    }): Promise<{
+        mojangMappingsAvailable: boolean;
+        tinyMappingsAvailable: boolean;
+        memberRemapAvailable: boolean;
+        degradations: string[];
+    }>;
     private loadGraph;
     private buildGraph;
     private mergePairs;