@adhisang/minecraft-modding-mcp 6.1.1 → 6.3.0

package/dist/tool-contract-manifest.js

@@ -15,7 +15,7 @@ const SECTION_ROWS = {
             "| `inspect-minecraft` | Inspect versions, artifacts, classes, files, source text, and workspace-aware lookup flows |",
             "| `analyze-symbol` | Handle symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol resolution, and API overviews |",
             "| `compare-minecraft` | Compare version pairs, class diffs, registry diffs, and migration-oriented summaries |",
-            "| `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, and preview or apply remaps |",
+            "| `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, read class members from bytecode, and preview or apply remaps |",
             "| `validate-project` | Summarize workspaces and run direct Mixin, Access Widener, or Access Transformer validation |",
             "| `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |"
         ],
@@ -32,7 +32,7 @@ const SECTION_ROWS = {
         en: [
             "| `list-versions` | List available Minecraft versions from Mojang metadata and local cache |",
             "| `resolve-artifact` | Resolve source artifacts from versions, JAR paths, or Maven coordinates |",
-            "| `find-class` | Find simple or fully-qualified class names inside an artifact |",
+            "| `find-class` | Find simple or fully-qualified class names, including classes bundled in nested JARs |",
             "| `get-class-source` | Read class source from an artifact or resolve the backing artifact on demand |",
             "| `get-class-members` | List constructors, fields, and methods from bytecode |",
             "| `search-class-source` | Search indexed class source by symbol, text, or path |",

package/dist/tool-guidance.js

@@ -1,7 +1,7 @@
 import { ZodError } from "zod";
 import { buildSuggestedCall } from "./build-suggested-call.js";
 import { ERROR_CODES, isAppError } from "./errors.js";
-import { extractAllowlistedContext, issueOriginForErrorCode, retryClassForErrorCode, statusForErrorCode } from "./error-mapping.js";
+import { extractAllowlistedContext, extractDidYouMean, issueOriginForErrorCode, retryClassForErrorCode, statusForErrorCode } from "./error-mapping.js";
 export const SUGGESTED_CALL_DEFAULTS = {
     allowDecompile: true,
     preferProjectVersion: false,
@@ -656,7 +656,103 @@ function gatedGuidance(tool, hints, params) {
         primaryDropped: !validated.suggestedCall
     };
 }
+function buildInspectWorkspaceSubject(source) {
+    const subject = {
+        kind: "workspace",
+        projectPath: asNonEmptyString(source.projectPath) ?? "<workspace-path>"
+    };
+    if (typeof source.mapping === "string" &&
+        ["obfuscated", "mojang", "intermediary", "yarn"].includes(source.mapping)) {
+        subject.mapping = source.mapping;
+    }
+    if (typeof source.scope === "string" &&
+        ["vanilla", "merged", "loader"].includes(source.scope)) {
+        subject.scope = source.scope;
+    }
+    const gradleUserHome = asNonEmptyString(source.gradleUserHome);
+    if (gradleUserHome) {
+        subject.gradleUserHome = gradleUserHome;
+    }
+    if (typeof source.preferProjectVersion === "boolean") {
+        subject.preferProjectVersion = source.preferProjectVersion;
+    }
+    if (typeof source.strictVersion === "boolean") {
+        subject.strictVersion = source.strictVersion;
+    }
+    return subject;
+}
+function inspectTaskForFocus(task, focusKind) {
+    if (focusKind === "class" &&
+        (task === "auto" || task === "class-overview" || task === "class-source" || task === "class-members")) {
+        return task;
+    }
+    if (focusKind === "search" && (task === "auto" || task === "search")) {
+        return task;
+    }
+    if (focusKind === "file" && (task === "auto" || task === "file")) {
+        return task;
+    }
+    return "auto";
+}
+function buildInspectMinecraftInvalidFocusGuidance(normalizedInput) {
+    const input = asObjectRecord(normalizedInput);
+    const originalSubject = asObjectRecord(input?.subject);
+    if (originalSubject?.kind !== "workspace" ||
+        originalSubject.focus === undefined ||
+        asObjectRecord(originalSubject.focus)) {
+        return undefined;
+    }
+    const requestedTask = asNonEmptyString(input?.task);
+    const workspaceSubject = buildInspectWorkspaceSubject(originalSubject);
+    const examples = [
+        {
+            params: {
+                task: inspectTaskForFocus(requestedTask, "class"),
+                subject: {
+                    ...workspaceSubject,
+                    focus: { kind: "class", className: "<fully-qualified-class-name>" }
+                }
+            },
+            reason: "Use class focus for class overview, source, or member inspection."
+        },
+        {
+            params: {
+                task: inspectTaskForFocus(requestedTask, "search"),
+                subject: {
+                    ...workspaceSubject,
+                    focus: { kind: "search", query: "<search-query>" }
+                }
+            },
+            reason: "Use search focus for symbol, text, or path search."
+        },
+        {
+            params: {
+                task: inspectTaskForFocus(requestedTask, "file"),
+                subject: {
+                    ...workspaceSubject,
+                    focus: { kind: "file", filePath: "<artifact-relative-file-path>" }
+                }
+            },
+            reason: "Use file focus for an artifact-relative file read."
+        }
+    ];
+    const validated = buildSuggestedCall({
+        tool: "inspect-minecraft",
+        params: undefined,
+        examples
+    });
+    return {
+        hints: [
+            "inspect-minecraft subject.focus must be a structured object, not a string.",
+            "Choose focus.kind=class with className, search with query, or file with filePath; task=auto dispatches from that kind and does not interpret prose."
+        ],
+        ...(validated.exampleCalls ? { exampleCalls: validated.exampleCalls } : {})
+    };
+}
 export function buildInvalidInputGuidance(tool, normalizedInput) {
+    if (tool === "inspect-minecraft") {
+        return buildInspectMinecraftInvalidFocusGuidance(normalizedInput);
+    }
     if (tool === "validate-mixin") {
         return gatedGuidance(tool, [
             "validate-mixin.input must be an object with input.mode = \"inline\" | \"path\" | \"paths\" | \"config\" | \"project\".",
@@ -719,17 +815,28 @@ export function mapErrorToProblem(caughtError, requestId, context) {
     }
     if (isAppError(caughtError)) {
         const { suggestedCall, exampleCalls, primaryDropped } = extractValidatedSuggestionAndExamples(caughtError.details);
+        const invalidInputGuidance = context?.tool === "inspect-minecraft" && caughtError.code === ERROR_CODES.INVALID_INPUT
+            ? buildInvalidInputGuidance(context.tool, context.normalizedInput)
+            : undefined;
+        const effectiveSuggestedCall = invalidInputGuidance
+            ? invalidInputGuidance.suggestedCall
+            : suggestedCall;
+        const effectiveExampleCalls = invalidInputGuidance?.exampleCalls ?? exampleCalls;
         const sanitizedContext = extractAllowlistedContext(caughtError.details);
+        const extractedDidYouMean = extractDidYouMean(caughtError.details);
         let failedStage = extractFailedStageFromDetails(caughtError.details);
         if (!failedStage
             && context?.tool === "validate-mixin"
             && caughtError.code === ERROR_CODES.INVALID_INPUT) {
             failedStage = "input-validation";
         }
-        const baseHints = toHints(caughtError.details);
-        const hintsWithFallback = primaryDropped && !suggestedCall
-            ? [...(baseHints ?? []), VALIDATION_FALLBACK_HINT]
-            : baseHints;
+        const baseHints = [
+            ...(toHints(caughtError.details) ?? []),
+            ...(invalidInputGuidance?.hints ?? [])
+        ];
+        const hintsWithFallback = primaryDropped && !effectiveSuggestedCall
+            ? [...baseHints, VALIDATION_FALLBACK_HINT]
+            : baseHints.length > 0 ? baseHints : undefined;
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -741,8 +848,9 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             issueOrigin: issueOriginForErrorCode(caughtError.code),
             fieldErrors: extractFieldErrorsFromDetails(caughtError.details),
             hints: hintsWithFallback,
-            ...(suggestedCall ? { suggestedCall } : {}),
-            ...(exampleCalls ? { exampleCalls } : {}),
+            ...(effectiveSuggestedCall ? { suggestedCall: effectiveSuggestedCall } : {}),
+            ...(effectiveExampleCalls ? { exampleCalls: effectiveExampleCalls } : {}),
+            ...(extractedDidYouMean ? { didYouMean: extractedDidYouMean } : {}),
             ...(failedStage ? { failedStage } : {}),
             ...(sanitizedContext ? { context: sanitizedContext } : {})
         };