@adhisang/minecraft-modding-mcp 4.2.1 → 5.0.0

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 { statusForErrorCode } from "./error-mapping.js";
+import { extractAllowlistedContext, issueOriginForErrorCode, retryClassForErrorCode, statusForErrorCode } from "./error-mapping.js";
 export const SUGGESTED_CALL_DEFAULTS = {
     allowDecompile: true,
     preferProjectVersion: false,
@@ -14,7 +14,7 @@ export const SUGGESTED_CALL_DEFAULTS = {
     explain: false,
     preferProjectMapping: false,
     minSeverity: "all",
-    reportMode: "full",
+    reportMode: "summary-first",
     treatInfoAsWarning: true,
     includeIssues: true
 };
@@ -98,14 +98,19 @@ export function extractValidatedSuggestionAndExamples(details) {
                 typeof ex.reason !== "string") {
                 continue;
             }
+            // Re-validate through the example path, not the primary path: example
+            // calls are templates and MAY carry placeholder sentinels (e.g.
+            // "<version>"), which the primary gate intentionally rejects.
             const result = buildSuggestedCall({
                 tool: ex.tool,
-                params: ex.params
+                params: undefined,
+                examples: [{ params: ex.params, reason: ex.reason }]
             });
-            if (result.suggestedCall) {
+            const validatedExample = result.exampleCalls?.[0];
+            if (validatedExample) {
                 validated.push({
                     tool: ex.tool,
-                    params: result.suggestedCall.params,
+                    params: validatedExample.params,
                     reason: ex.reason
                 });
             }
@@ -414,12 +419,10 @@ export function buildSourceLookupSuggestedParams(tool, normalizedInput) {
     const targetValue = asNonEmptyString(record?.target);
     result.target = targetValue
         ? {
-            type: "resolve",
             kind: inferTargetKindFromString(targetValue),
             value: targetValue
         }
         : {
-            type: "resolve",
             kind: "version",
             value: "<minecraft-version>"
         };
@@ -607,7 +610,21 @@ export function buildValidateProjectSuggestedParams(normalizedInput) {
     return result;
 }
 function gatedGuidance(tool, hints, params) {
-    const validated = buildSuggestedCall({ tool, params });
+    // Pass the reconstructed params as both the primary and a fallback example.
+    // When they are fully executable they become `suggestedCall`; when they still
+    // carry `<…>` placeholders (e.g. a missing version) the gate drops the
+    // primary and surfaces the same shape as an `exampleCalls` template instead
+    // of emitting a non-callable suggestedCall.
+    const validated = buildSuggestedCall({
+        tool,
+        params,
+        examples: [
+            {
+                params,
+                reason: `Example ${tool} call shape — replace any <…> placeholder values before sending.`
+            }
+        ]
+    });
     return {
         hints,
         ...validated,
@@ -630,8 +647,8 @@ export function buildInvalidInputGuidance(tool, normalizedInput) {
     }
     if (tool === "get-class-source" || tool === "get-class-members") {
         return gatedGuidance(tool, [
-            `${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."
+            `${tool}.target must be an object: {"kind":"version|jar|coordinate","value":"..."} or {"kind":"artifact","artifactId":"..."} (same shape as resolve-artifact).`,
+            "Bare string targets are not accepted; wrap the value under target.kind/target.value."
         ], buildSourceLookupSuggestedParams(tool, normalizedInput));
     }
     if (tool === "validate-project") {
@@ -666,6 +683,8 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             status: 400,
             code: ERROR_CODES.INVALID_INPUT,
             instance: requestId,
+            retryClass: retryClassForErrorCode(ERROR_CODES.INVALID_INPUT),
+            issueOrigin: issueOriginForErrorCode(ERROR_CODES.INVALID_INPUT),
             fieldErrors: toFieldErrorsFromZod(caughtError),
             hints: hintsWithFallback,
             ...(guidance?.suggestedCall ? { suggestedCall: guidance.suggestedCall } : {}),
@@ -675,6 +694,7 @@ export function mapErrorToProblem(caughtError, requestId, context) {
     }
     if (isAppError(caughtError)) {
         const { suggestedCall, exampleCalls, primaryDropped } = extractValidatedSuggestionAndExamples(caughtError.details);
+        const sanitizedContext = extractAllowlistedContext(caughtError.details);
         let failedStage = extractFailedStageFromDetails(caughtError.details);
         if (!failedStage
             && context?.tool === "validate-mixin"
@@ -692,11 +712,14 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             status: statusForErrorCode(caughtError.code),
             code: caughtError.code,
             instance: requestId,
+            retryClass: retryClassForErrorCode(caughtError.code),
+            issueOrigin: issueOriginForErrorCode(caughtError.code),
             fieldErrors: extractFieldErrorsFromDetails(caughtError.details),
             hints: hintsWithFallback,
             ...(suggestedCall ? { suggestedCall } : {}),
             ...(exampleCalls ? { exampleCalls } : {}),
-            ...(failedStage ? { failedStage } : {})
+            ...(failedStage ? { failedStage } : {}),
+            ...(sanitizedContext ? { context: sanitizedContext } : {})
         };
     }
     return {
@@ -705,7 +728,9 @@ export function mapErrorToProblem(caughtError, requestId, context) {
         detail: "Unexpected server error.",
         status: 500,
         code: ERROR_CODES.INTERNAL,
-        instance: requestId
+        instance: requestId,
+        retryClass: retryClassForErrorCode(ERROR_CODES.INTERNAL),
+        issueOrigin: issueOriginForErrorCode(ERROR_CODES.INTERNAL)
     };
 }
 /**