@adhisang/minecraft-modding-mcp 6.2.0 → 7.0.0-rc.0

package/dist/storage/db.d.ts

@@ -10,5 +10,6 @@ export interface InitializedDatabase {
     db: SqliteDatabase;
     schemaVersion: number;
 }
-export declare function openDatabase(config: Config, logger?: Logger): InitializedDatabase;
+type DatabaseConfig = Pick<Config, "sqlitePath"> & Partial<Pick<Config, "sqliteCacheKb" | "sqliteMmapSize">>;
+export declare function openDatabase(config: DatabaseConfig, logger?: Logger): InitializedDatabase;
 export {};

package/dist/storage/db.js

@@ -5,6 +5,8 @@ import Database from "./sqlite.js";
 import { runMigrations } from "./migrations.js";
 import { createError, ERROR_CODES, isAppError } from "../errors.js";
 import { log } from "../logger.js";
+const DEFAULT_SQLITE_CACHE_KB = 8_000;
+const DEFAULT_SQLITE_MMAP_SIZE = 268_435_456;
 function ensureParentDirectory(path) {
     mkdirSync(dirname(path), { recursive: true });
 }
@@ -18,6 +20,17 @@ function runIntegrityCheck(db) {
         });
     }
 }
+function applyPragmas(db, config) {
+    const sqliteCacheKb = config.sqliteCacheKb ?? DEFAULT_SQLITE_CACHE_KB;
+    const sqliteMmapSize = config.sqliteMmapSize ?? DEFAULT_SQLITE_MMAP_SIZE;
+    db.pragma("foreign_keys = ON");
+    db.pragma("journal_mode = WAL");
+    db.pragma("synchronous = NORMAL");
+    db.pragma("busy_timeout = 5000");
+    db.pragma(`cache_size = -${sqliteCacheKb}`);
+    db.pragma(`mmap_size = ${sqliteMmapSize}`);
+    db.pragma("temp_store = MEMORY");
+}
 function backupCorruptedDb(sqlitePath) {
     const backupPath = `${sqlitePath}.corrupted.${Date.now()}`;
     renameSync(sqlitePath, backupPath);
@@ -90,10 +103,7 @@ export function openDatabase(config, logger = buildDefaultLogger()) {
     try {
         ensureParentDirectory(config.sqlitePath);
         db = new Database(config.sqlitePath);
-        db.pragma("foreign_keys = ON");
-        db.pragma("journal_mode = WAL");
-        db.pragma("synchronous = NORMAL");
-        db.pragma("busy_timeout = 5000");
+        applyPragmas(db, config);
         const schemaVersion = runMigrations(db);
         runIntegrityCheck(db);
         return { db, schemaVersion };
@@ -133,10 +143,7 @@ export function openDatabase(config, logger = buildDefaultLogger()) {
                 backupPath
             });
             const rebuilt = new Database(config.sqlitePath);
-            rebuilt.pragma("foreign_keys = ON");
-            rebuilt.pragma("journal_mode = WAL");
-            rebuilt.pragma("synchronous = NORMAL");
-            rebuilt.pragma("busy_timeout = 5000");
+            applyPragmas(rebuilt, config);
             const schemaVersion = runMigrations(rebuilt);
             runIntegrityCheck(rebuilt);
             return { db: rebuilt, schemaVersion };

package/dist/synthetic-decorator.d.ts

@@ -0,0 +1,24 @@
+import type { JSONRPCResponse } from "@modelcontextprotocol/server";
+import type { Era } from "./era-classifier.js";
+/**
+ * Centralized modern-era decoration for supervisor-synthesized replies.
+ *
+ * Contract:
+ *  - Decorates ONLY when the originating request's snapshot era is "modern"
+ *    (the era captured at admission; it is the ONLY captured-context field
+ *    synthetic decoration may read — protocolVersion/clientCapabilities/
+ *    clientInfo stay unread, and the identity comes from the canonical
+ *    src/server-identity.ts module, never from request context).
+ *  - Modern-era RESULT envelopes gain the modern public fields the SDK stamps
+ *    on every result it encodes: top-level `resultType: "complete"` (every
+ *    result this server emits is complete — synthetic results are all
+ *    tools/call-shaped, where "complete" is always correct) and
+ *    `_meta[SERVER_INFO_META_KEY]` carrying the canonical identity.
+ *  - Raw JSON-RPC ERROR envelopes and non-modern eras pass through UNCHANGED
+ *    (same reference), keeping the legacy synthetic shapes byte-identical to
+ *    the premigration fixtures (pinned by the synthetic-inventory suite).
+ *  - Cache fields (ttlMs/cacheScope) are NEVER added: they belong only to the
+ *    six cacheable list/read/discover methods, none of which has a structured
+ *    synthetic path.
+ */
+export declare function decorateSyntheticReply(reply: JSONRPCResponse, era: Era | undefined): JSONRPCResponse;

package/dist/synthetic-decorator.js

@@ -0,0 +1,48 @@
+import { SERVER_INFO_META_KEY } from "@modelcontextprotocol/server";
+import { serverIdentitySnapshot } from "./server-identity.js";
+/**
+ * Centralized modern-era decoration for supervisor-synthesized replies.
+ *
+ * Contract:
+ *  - Decorates ONLY when the originating request's snapshot era is "modern"
+ *    (the era captured at admission; it is the ONLY captured-context field
+ *    synthetic decoration may read — protocolVersion/clientCapabilities/
+ *    clientInfo stay unread, and the identity comes from the canonical
+ *    src/server-identity.ts module, never from request context).
+ *  - Modern-era RESULT envelopes gain the modern public fields the SDK stamps
+ *    on every result it encodes: top-level `resultType: "complete"` (every
+ *    result this server emits is complete — synthetic results are all
+ *    tools/call-shaped, where "complete" is always correct) and
+ *    `_meta[SERVER_INFO_META_KEY]` carrying the canonical identity.
+ *  - Raw JSON-RPC ERROR envelopes and non-modern eras pass through UNCHANGED
+ *    (same reference), keeping the legacy synthetic shapes byte-identical to
+ *    the premigration fixtures (pinned by the synthetic-inventory suite).
+ *  - Cache fields (ttlMs/cacheScope) are NEVER added: they belong only to the
+ *    six cacheable list/read/discover methods, none of which has a structured
+ *    synthetic path.
+ */
+export function decorateSyntheticReply(reply, era) {
+    if (era !== "modern") {
+        return reply;
+    }
+    const asRecord = reply;
+    if ("error" in asRecord || !("result" in asRecord)) {
+        return reply;
+    }
+    const result = asRecord.result;
+    const existingMeta = result._meta !== null && typeof result._meta === "object" && !Array.isArray(result._meta)
+        ? result._meta
+        : {};
+    return {
+        ...asRecord,
+        result: {
+            ...result,
+            resultType: "complete",
+            _meta: {
+                ...existingMeta,
+                [SERVER_INFO_META_KEY]: serverIdentitySnapshot()
+            }
+        }
+    };
+}
+//# sourceMappingURL=synthetic-decorator.js.map

package/dist/tool-contract-manifest.js

@@ -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.d.ts

@@ -43,7 +43,7 @@ export declare const ANALYZE_MOD_LEGACY_METADATA_INCLUDES: readonly ["metadata",
 export declare const VALIDATE_PROJECT_INCLUDE_GROUPS: readonly ["warnings", "issues", "workspace", "recovery"];
 export declare const VALIDATE_PROJECT_LEGACY_WORKSPACE_INCLUDES: readonly ["detectedConfig", "mixins", "accessWideners"];
 export declare const VALIDATION_FALLBACK_HINT = "suggested call payload failed schema validation; using fallback examples";
-export declare function toFieldErrorsFromZod(error: ZodError): ProblemFieldError[];
+export declare function toFieldErrorsFromZod(error: ZodError, ...rawInput: [unknown?]): ProblemFieldError[];
 export declare function toHints(details: unknown): string[] | undefined;
 export declare function extractValidatedSuggestionAndExamples(details: unknown): {
     suggestedCall?: SuggestedCall;
@@ -73,6 +73,22 @@ type InvalidInputGuidance = {
     primaryDropped?: boolean;
 };
 export declare function buildInvalidInputGuidance(tool: string, normalizedInput: unknown): InvalidInputGuidance | undefined;
+/**
+ * Removes an ask for a parameter the caller already sent.
+ *
+ * `validate-access-transformer` failed on the canonical NeoForge workspace with
+ * "Provide projectPath for a Forge/NeoForge workspace ..." — while projectPath
+ * WAS supplied. A hint that asks for what it already has is worse than no hint:
+ * it sends the agent into a retry loop with an identical payload. The producing
+ * sites word their guidance conditionally; this is the backstop that keeps any
+ * remaining site from contradicting the request.
+ *
+ * The ask is a leading clause, so an "..., or <alternative>" tail survives as
+ * its own sentence; a hint that is nothing BUT a satisfied ask is dropped.
+ * Applies only to execution errors — an input-validation failure may legitimately
+ * ask again for a parameter that was present but malformed.
+ */
+export declare function dropSatisfiedParameterAsks(hints: string[], normalizedInput: unknown): string[];
 export declare function mapErrorToProblem(caughtError: unknown, requestId: string, context?: {
     tool?: string;
     normalizedInput?: unknown;

package/dist/tool-guidance.js

@@ -26,12 +26,241 @@ export const ANALYZE_MOD_LEGACY_METADATA_INCLUDES = ["metadata", "entrypoints",
 export const VALIDATE_PROJECT_INCLUDE_GROUPS = ["warnings", "issues", "workspace", "recovery"];
 export const VALIDATE_PROJECT_LEGACY_WORKSPACE_INCLUDES = ["detectedConfig", "mixins", "accessWideners"];
 export const VALIDATION_FALLBACK_HINT = "suggested call payload failed schema validation; using fallback examples";
-export function toFieldErrorsFromZod(error) {
-    return error.issues.map((issue) => ({
-        path: issue.path.join(".") || "$",
-        message: issue.message,
-        code: issue.code
-    }));
+/** zod3's getParsedType vocabulary for `received` words. */
+function zod3ParsedType(data) {
+    switch (typeof data) {
+        case "undefined":
+            return "undefined";
+        case "string":
+            return "string";
+        case "number":
+            return Number.isNaN(data) ? "nan" : "number";
+        case "boolean":
+            return "boolean";
+        case "function":
+            return "function";
+        case "bigint":
+            return "bigint";
+        case "symbol":
+            return "symbol";
+        case "object":
+            if (data === null)
+                return "null";
+            if (Array.isArray(data))
+                return "array";
+            if (typeof data.then === "function")
+                return "promise";
+            if (data instanceof Map)
+                return "map";
+            if (data instanceof Set)
+                return "set";
+            if (data instanceof Date)
+                return "date";
+            return "object";
+        default:
+            return "unknown";
+    }
+}
+/** zod3's util.joinValues: single-quote strings, stringify the rest. */
+function zod3JoinValues(values, separator = " | ") {
+    return values
+        .map((value) => (typeof value === "string" ? `'${value}'` : String(value)))
+        .join(separator);
+}
+function valueAtPath(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function zod3SizeMessage(issue, kind) {
+    const origin = issue.origin === "int" ? "number" : issue.origin;
+    const limit = kind === "small" ? issue.minimum : issue.maximum;
+    if (limit === undefined)
+        return undefined;
+    const inclusive = issue.inclusive !== false;
+    const exact = issue.exact === true;
+    switch (origin) {
+        case "array":
+        case "set":
+            return kind === "small"
+                ? `Array must contain ${exact ? "exactly" : inclusive ? "at least" : "more than"} ${limit} element(s)`
+                : `Array must contain ${exact ? "exactly" : inclusive ? "at most" : "less than"} ${limit} element(s)`;
+        case "string":
+            return kind === "small"
+                ? `String must contain ${exact ? "exactly" : inclusive ? "at least" : "over"} ${limit} character(s)`
+                : `String must contain ${exact ? "exactly" : inclusive ? "at most" : "under"} ${limit} character(s)`;
+        case "number":
+            return kind === "small"
+                ? `Number must be ${exact ? "exactly equal to" : inclusive ? "greater than or equal to" : "greater than"} ${limit}`
+                : `Number must be ${exact ? "exactly" : inclusive ? "less than or equal to" : "less than"} ${limit}`;
+        case "bigint":
+            return kind === "small"
+                ? `BigInt must be ${exact ? "exactly equal to" : inclusive ? "greater than or equal to" : "greater than"} ${limit}`
+                : `BigInt must be ${exact ? "exactly" : inclusive ? "less than or equal to" : "less than"} ${limit}`;
+        case "date":
+            return kind === "small"
+                ? `Date must be ${exact ? "exactly equal to" : inclusive ? "greater than or equal to" : "greater than"} ${new Date(Number(limit))}`
+                : `Date must be ${exact ? "exactly" : inclusive ? "smaller than or equal to" : "smaller than"} ${new Date(Number(limit))}`;
+        default:
+            return undefined;
+    }
+}
+const ZOD4_INVALID_TYPE_RE = /^Invalid input: expected (\S+), received (.+)$/;
+const ZOD4_ENUM_RE = /^Invalid option: expected one of /;
+const ZOD4_LITERAL_RE = /^Invalid input: expected \S+$/;
+const ZOD4_TOO_SMALL_RE = /^Too small: /;
+const ZOD4_TOO_BIG_RE = /^Too big: /;
+const ZOD4_UNRECOGNIZED_RE = /^Unrecognized keys?: /;
+/**
+ * Maps one zod4 issue to its zod3-era {code, message}. Issues whose message
+ * does not match the zod4 default pattern carry app-supplied custom text and
+ * pass through unchanged (zod3 surfaced custom messages verbatim too).
+ * `hasInput`/`rawInput` supply the original parse input for the `received`
+ * clauses zod4 no longer records on the issue.
+ */
+function toZod3ParityIssue(issue, rawInput, hasInput) {
+    const code = issue.code ?? "custom";
+    const receivedValue = () => {
+        if ("input" in issue)
+            return { known: true, value: issue.input };
+        if (hasInput)
+            return { known: true, value: valueAtPath(rawInput, issue.path) };
+        return { known: false, value: undefined };
+    };
+    switch (code) {
+        case "invalid_type": {
+            const match = ZOD4_INVALID_TYPE_RE.exec(issue.message);
+            if (!match)
+                return { code, message: issue.message };
+            const received = receivedValue();
+            const receivedWord = received.known
+                ? zod3ParsedType(received.value)
+                : match[2] === "NaN"
+                    ? "nan"
+                    : match[2];
+            if (receivedWord === "undefined") {
+                return { code, message: "Required" };
+            }
+            // zod3's .int() check emitted the hardcoded pair "integer"/"float"
+            // (ZodNumber._parse), not the parsed-type vocabulary. zod4 reports
+            // expected "int" and a plain "number" received.
+            if ((issue.expected ?? match[1]) === "int") {
+                const isNonIntegerNumber = received.known && typeof received.value === "number" && !Number.isInteger(received.value);
+                if (isNonIntegerNumber || (!received.known && match[2] === "number")) {
+                    return { code, message: "Expected integer, received float" };
+                }
+                return { code, message: `Expected integer, received ${receivedWord}` };
+            }
+            return { code, message: `Expected ${issue.expected ?? match[1]}, received ${receivedWord}` };
+        }
+        case "invalid_value": {
+            const values = issue.values ?? [];
+            // zod3 reported a MISSING enum/literal field as invalid_type/"Required"
+            // (the type check on `undefined` fired before value matching); zod4
+            // folds it into invalid_value. Restore the zod3 classification.
+            const missing = receivedValue();
+            if (missing.known && missing.value === undefined) {
+                return { code: "invalid_type", message: "Required" };
+            }
+            // zod3's ZodEnum type-checked BEFORE value matching: a non-string
+            // received value produced invalid_type with the joined options as the
+            // "expected" word and the parsed type as "received".
+            if (values.length > 1 && missing.known && typeof missing.value !== "string") {
+                return {
+                    code: "invalid_type",
+                    message: `Expected ${zod3JoinValues(values)}, received ${zod3ParsedType(missing.value)}`
+                };
+            }
+            if (values.length > 1 && ZOD4_ENUM_RE.test(issue.message)) {
+                const received = receivedValue();
+                return {
+                    code: "invalid_enum_value",
+                    message: `Invalid enum value. Expected ${zod3JoinValues(values)}, received '${String(received.value)}'`
+                };
+            }
+            if (values.length === 1 && ZOD4_LITERAL_RE.test(issue.message)) {
+                return {
+                    code: "invalid_literal",
+                    message: `Invalid literal value, expected ${JSON.stringify(values[0])}`
+                };
+            }
+            return { code: values.length > 1 ? "invalid_enum_value" : "invalid_literal", message: issue.message };
+        }
+        case "invalid_union": {
+            if (issue.note === "No matching discriminator") {
+                return {
+                    code: "invalid_union_discriminator",
+                    message: Array.isArray(issue.options)
+                        ? `Invalid discriminator value. Expected ${zod3JoinValues(issue.options)}`
+                        : issue.message
+                };
+            }
+            return { code, message: issue.message === "Invalid input" ? "Invalid input" : issue.message };
+        }
+        case "too_small": {
+            if (!ZOD4_TOO_SMALL_RE.test(issue.message))
+                return { code, message: issue.message };
+            return { code, message: zod3SizeMessage(issue, "small") ?? issue.message };
+        }
+        case "too_big": {
+            if (!ZOD4_TOO_BIG_RE.test(issue.message))
+                return { code, message: issue.message };
+            return { code, message: zod3SizeMessage(issue, "big") ?? issue.message };
+        }
+        case "unrecognized_keys": {
+            if (!ZOD4_UNRECOGNIZED_RE.test(issue.message))
+                return { code, message: issue.message };
+            const keys = issue.keys ?? [];
+            return {
+                code,
+                message: `Unrecognized key(s) in object: ${zod3JoinValues(keys, ", ")}`
+            };
+        }
+        case "not_multiple_of": {
+            return {
+                code,
+                message: issue.divisor === undefined
+                    ? issue.message
+                    : `Number must be a multiple of ${issue.divisor}`
+            };
+        }
+        case "invalid_format": {
+            if (!issue.message.startsWith("Invalid "))
+                return { code: "invalid_string", message: issue.message };
+            switch (issue.format) {
+                case "regex":
+                    return { code: "invalid_string", message: "Invalid" };
+                case "starts_with":
+                    return { code: "invalid_string", message: `Invalid input: must start with "${issue.prefix ?? ""}"` };
+                case "ends_with":
+                    return { code: "invalid_string", message: `Invalid input: must end with "${issue.suffix ?? ""}"` };
+                case "includes":
+                    return { code: "invalid_string", message: `Invalid input: must include "${issue.includes ?? ""}"` };
+                default:
+                    return { code: "invalid_string", message: `Invalid ${issue.format ?? "string"}` };
+            }
+        }
+        case "custom":
+            return { code, message: issue.message };
+        default:
+            return { code, message: issue.message };
+    }
+}
+export function toFieldErrorsFromZod(error, ...rawInput) {
+    const hasInput = rawInput.length > 0;
+    const input = rawInput[0];
+    return error.issues.map((issue) => {
+        const parity = toZod3ParityIssue(issue, input, hasInput);
+        return {
+            path: issue.path.join(".") || "$",
+            message: parity.message,
+            code: parity.code
+        };
+    });
 }
 export function toHints(details) {
     if (typeof details !== "object" || details == null) {
@@ -656,7 +885,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\".",
@@ -692,6 +1017,78 @@ export function buildInvalidInputGuidance(tool, normalizedInput) {
     }
     return undefined;
 }
+/**
+ * Parameters a hint may ask for, and which are meaningful to check against the
+ * caller's own payload. Restricted to top-level scalar/object inputs so the
+ * check never mistakes a nested field for a supplied argument.
+ */
+const HINT_ASKABLE_PARAMETERS = [
+    "projectPath",
+    "gradleUserHome",
+    "version",
+    "artifactId",
+    "mapping",
+    "atNamespace",
+    "awNamespace",
+    "scope",
+    "className",
+    "content",
+    "jarPath",
+    "mixinConfigPath",
+    "sourcePriority"
+];
+const HINT_ASK_PATTERN = new RegExp(`\\b(?:Provide|Pass|Specify|Supply) (?:a |an |the )?(${HINT_ASKABLE_PARAMETERS.join("|")})\\b`);
+function isSuppliedInputValue(value) {
+    if (value == null)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+/**
+ * Removes an ask for a parameter the caller already sent.
+ *
+ * `validate-access-transformer` failed on the canonical NeoForge workspace with
+ * "Provide projectPath for a Forge/NeoForge workspace ..." — while projectPath
+ * WAS supplied. A hint that asks for what it already has is worse than no hint:
+ * it sends the agent into a retry loop with an identical payload. The producing
+ * sites word their guidance conditionally; this is the backstop that keeps any
+ * remaining site from contradicting the request.
+ *
+ * The ask is a leading clause, so an "..., or <alternative>" tail survives as
+ * its own sentence; a hint that is nothing BUT a satisfied ask is dropped.
+ * Applies only to execution errors — an input-validation failure may legitimately
+ * ask again for a parameter that was present but malformed.
+ */
+export function dropSatisfiedParameterAsks(hints, normalizedInput) {
+    if (hints.length === 0 ||
+        typeof normalizedInput !== "object" ||
+        normalizedInput == null ||
+        Array.isArray(normalizedInput)) {
+        return hints;
+    }
+    const supplied = normalizedInput;
+    const rewritten = [];
+    for (const hint of hints) {
+        const match = HINT_ASK_PATTERN.exec(hint);
+        if (!match || !isSuppliedInputValue(supplied[match[1]])) {
+            rewritten.push(hint);
+            continue;
+        }
+        const alternative = hint.indexOf(", or ");
+        if (alternative < 0) {
+            continue;
+        }
+        const tail = hint.slice(alternative + ", or ".length).trim();
+        if (!tail) {
+            continue;
+        }
+        rewritten.push(tail.charAt(0).toUpperCase() + tail.slice(1));
+    }
+    return rewritten;
+}
 export function mapErrorToProblem(caughtError, requestId, context) {
     if (caughtError instanceof ZodError) {
         const guidance = context?.tool
@@ -710,7 +1107,7 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             instance: requestId,
             retryClass: retryClassForErrorCode(ERROR_CODES.INVALID_INPUT),
             issueOrigin: issueOriginForErrorCode(ERROR_CODES.INVALID_INPUT),
-            fieldErrors: toFieldErrorsFromZod(caughtError),
+            fieldErrors: toFieldErrorsFromZod(caughtError, context?.normalizedInput),
             hints: hintsWithFallback,
             ...(guidance?.suggestedCall ? { suggestedCall: guidance.suggestedCall } : {}),
             ...(guidance?.exampleCalls ? { exampleCalls: guidance.exampleCalls } : {}),
@@ -719,6 +1116,13 @@ 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);
@@ -727,10 +1131,10 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             && 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 = dropSatisfiedParameterAsks([...(toHints(caughtError.details) ?? []), ...(invalidInputGuidance?.hints ?? [])], context?.normalizedInput);
+        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",
@@ -742,8 +1146,8 @@ 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 } : {})

package/dist/tool-schema-registry.d.ts

@@ -13,4 +13,6 @@ export type ValidateToolParamsResult = {
 };
 export declare function validateToolParams(name: string, params: unknown): ValidateToolParamsResult;
 export declare function listRegisteredTools(): string[];
+/** O(1) registry size — the populated-registry probe for per-request paths. */
+export declare function registeredToolCount(): number;
 export declare function clearRegisteredToolsForTest(): void;