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

package/dist/mapping-service.js

@@ -22,6 +22,12 @@ const SUPPORTED_MAPPINGS = new Set([
     "intermediary",
     "yarn"
 ]);
+/**
+ * Cap on the declaring classes named in the owner-strict not_found warning. A real
+ * mapping can hold dozens of same-signature methods, and the warning is guidance, not
+ * an inventory — find-mapping is the tool that returns the full list.
+ */
+const MAX_REPORTED_DECLARING_OWNERS = 5;
 /* parsers extracted to src/mapping/parsers/{symbol-records,normalize,proguard,tiny}.ts */
 export class MappingService {
     config;
@@ -388,39 +394,89 @@ export class MappingService {
             const obfuscatedProjection = this.projectMethodDescriptorToTarget(graph, toObfuscatedPath, descriptor);
             acceptedDescriptors.add(obfuscatedProjection.descriptor);
         }
-        const strictCandidates = rawCandidates.filter((candidate) => candidate.descriptor !== undefined && acceptedDescriptors.has(candidate.descriptor));
+        // "Strict" is the query's full advertised triple: owner + name + descriptor. The
+        // descriptor alone is not enough, because `lookupCandidates` also indexes methods
+        // under the OWNERLESS `<name><descriptor>` simple-name key — so a same-signature
+        // method on an unrelated class used to survive the filter and force an `ambiguous`
+        // verdict next to the one exact, confidence-1 candidate that answered the question.
+        const descriptorMatched = rawCandidates.filter((candidate) => candidate.descriptor !== undefined && acceptedDescriptors.has(candidate.descriptor));
+        const acceptedOwners = this.acceptedOwnersAlongPath(graph, path, owner);
+        const strictCandidates = descriptorMatched.filter((candidate) => candidate.owner !== undefined && acceptedOwners.has(candidate.owner));
+        // A candidate is attributed to the FIRST gate it failed, so the two counts partition
+        // the rejected set and never double-count a candidate that fails both.
+        const rejectedByDescriptor = rawCandidates.length - descriptorMatched.length;
+        const rejectedByOwner = descriptorMatched.length - strictCandidates.length;
         if (strictCandidates.length === 1) {
             const resolved = toResolutionCandidate(strictCandidates[0]);
+            // The verdict is computed from `strictCandidates`, so that is the set reported —
+            // the same rule the ambiguous branch follows. Returning the raw name-matched list
+            // here would publish candidates the strict filter had already rejected alongside
+            // `status: "resolved"`, with nothing to tell them apart from the answer.
+            const limitedStrictCandidates = limitResolutionCandidates([resolved], input.maxCandidates);
             return {
                 querySymbol,
                 mappingContext,
                 resolved: true,
                 status: "resolved",
                 resolvedSymbol: resolved,
-                candidates: limitedCandidates.candidates,
-                candidateCount: limitedCandidates.candidateCount,
-                candidatesTruncated: limitedCandidates.candidatesTruncated,
+                candidates: limitedStrictCandidates.candidates,
+                candidateCount: limitedStrictCandidates.candidateCount,
+                candidatesTruncated: limitedStrictCandidates.candidatesTruncated,
                 warnings,
                 provenance: this.provenanceForPath(graph, path)
             };
         }
         if (strictCandidates.length > 1) {
+            // The verdict is computed from `strictCandidates`, so that is the set reported.
+            // Returning the raw name-matched list here put candidates the strict filter had
+            // already rejected — including full-confidence exact matches on other owners —
+            // next to `status: "ambiguous"`, with nothing to tell them apart from the two the
+            // tool actually could not choose between.
+            const strictResolutionCandidates = strictCandidates.map(toResolutionCandidate);
+            const limitedStrictCandidates = limitResolutionCandidates(strictResolutionCandidates, input.maxCandidates);
             warnings.push("Exact method mapping is ambiguous for owner+method+descriptor.");
-            if (limitedCandidates.candidatesTruncated) {
+            if (limitedStrictCandidates.candidatesTruncated) {
                 warnings.push("Raise maxCandidates up to 200 to inspect the full candidate list, or narrow the lookup via find-mapping disambiguation hints.");
             }
+            // Report the counts BY REASON. Most rejections here are by owner, not by
+            // descriptor, so a warning that names descriptor as the cause would be wrong.
+            const rejectedTotal = rejectedByOwner + rejectedByDescriptor;
+            if (rejectedTotal > 0) {
+                warnings.push(`${rejectedTotal} further name-matched candidate(s) were rejected before the verdict ` +
+                    `(${rejectedByOwner} by owner, ${rejectedByDescriptor} by descriptor) and are not reported; ` +
+                    `use find-mapping for the unfiltered list.`);
+            }
             return {
                 querySymbol,
                 mappingContext,
                 resolved: false,
                 status: "ambiguous",
-                candidates: limitedCandidates.candidates,
-                candidateCount: limitedCandidates.candidateCount,
-                candidatesTruncated: limitedCandidates.candidatesTruncated,
+                candidates: limitedStrictCandidates.candidates,
+                candidateCount: limitedStrictCandidates.candidateCount,
+                candidatesTruncated: limitedStrictCandidates.candidatesTruncated,
                 warnings,
-                provenance: this.provenanceForPath(graph, path)
+                provenance: this.provenanceForPath(graph, path),
+                ambiguityReasons: inferAmbiguityReasons(strictResolutionCandidates, pathUsesSource(graph.pairs, path, "mojang-client-mappings"))
             };
         }
+        // Owner-strictness has an accepted cost: a method the owner INHERITS rather than
+        // declares no longer resolves, because the mapping formats record declarations and
+        // carry no class hierarchy. Make that legible instead of returning a bare not_found.
+        if (rejectedByOwner > 0 && strictCandidates.length === 0) {
+            const declaringOwners = [
+                ...new Set(descriptorMatched.map((candidate) => candidate.owner).filter(Boolean))
+            ];
+            const shownOwners = declaringOwners.slice(0, MAX_REPORTED_DECLARING_OWNERS);
+            const ownerList = shownOwners.join(", ") +
+                (declaringOwners.length > shownOwners.length
+                    ? `, and ${declaringOwners.length - shownOwners.length} more`
+                    : "");
+            warnings.push(`Exact method resolution is owner-strict: "${owner}" does not itself declare ` +
+                `${method}${descriptor}. ${rejectedByOwner} candidate(s) with that name and descriptor ` +
+                `are declared by other classes (${targetMapping}: ${ownerList}). An inherited or relocated ` +
+                `member cannot resolve here — use find-mapping for an owner-agnostic lookup, or query the ` +
+                `declaring class directly.`);
+        }
         if (descriptorProjection.hadClassReferences && !descriptorProjection.complete) {
             warnings.push(pathUsesSource(graph.pairs, path, "mojang-client-mappings")
                 ? "Method descriptor could not be preserved through mojang-client-mappings and exact resolution is unavailable."
@@ -964,6 +1020,34 @@ export class MappingService {
             descriptor: item.record.descriptor
         }));
     }
+    /**
+     * The owner names that a query owner is allowed to appear under once candidates have
+     * been projected along `path`.
+     *
+     * The query owner arrives in the SOURCE namespace while `mapCandidatesAlongPath`
+     * hands back records whose `owner` is the declaring class in the TARGET namespace
+     * (both parsers build member records with `createMethodSymbolRecord(<owner in that
+     * namespace>, ...)`), so the two are only comparable after the owner itself has been
+     * carried along the same path. Projecting the owner as a class record through
+     * `mapCandidatesAlongPath` is that carriage, and it is the same mechanism
+     * `projectMethodDescriptorToTarget` already uses for class references inside a
+     * descriptor.
+     *
+     * `simple-name` class matches are excluded on purpose: they mean "some other class
+     * that happens to share this simple name", which is exactly the foreign-owner noise
+     * the strict filter exists to remove. The source-namespace name is kept as an
+     * accepted alias so an owner that the mapping does not rename still matches itself.
+     */
+    acceptedOwnersAlongPath(graph, path, owner) {
+        const accepted = new Set([normalizeMappedSymbolOutput(owner)]);
+        for (const candidate of this.mapCandidatesAlongPath(graph, path, createClassSymbolRecord(owner))) {
+            if (candidate.kind !== "class" || candidate.matchKind === "simple-name") {
+                continue;
+            }
+            accepted.add(normalizeMappedSymbolOutput(candidate.symbol));
+        }
+        return accepted;
+    }
     projectMethodDescriptorToTarget(graph, path, descriptor) {
         let hadClassReferences = false;
         let complete = true;

package/dist/mcp-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult, ReadResourceResult, ServerContext } from "@modelcontextprotocol/server";
 import { type ErrorCode } from "./errors.js";
 type ObjectResultOptions = {
     isError?: boolean;
@@ -6,9 +6,26 @@ type ObjectResultOptions = {
 export declare function objectResult<T extends Record<string, unknown>>(data: T, options?: ObjectResultOptions): CallToolResult;
 export declare function textResource(uri: string, value: string): ReadResourceResult;
 export declare function objectResource(uri: string, data: Record<string, unknown>): ReadResourceResult;
+/**
+ * Whether the request being handled carries the FULL shallow modern
+ * (2026-07-28) era signal in its lifted `_meta` envelope: a string
+ * protocol-version AND a plain-object clientCapabilities — the same shallow
+ * modern-signal check era-classifier's `classifyEraSignal` applies at
+ * supervisor admission (kept in lockstep; that module is the canonical
+ * definition). The version key ALONE is not enough: a claim-shaped-INVALID
+ * request (version present, capabilities missing/invalid) is
+ * legacy-permissively forwarded on a legacy-locked connection, the SDK's
+ * era-blind lift still surfaces the key at `ctx.mcpReq.envelope`, and the
+ * reply is encoded by the LEGACY codec — which serializes handler-returned
+ * fields verbatim. Shallow-VALID envelopes, by contrast, are answered by the
+ * 2026 codec (the SDK rejects envelope-less modern requests -32602
+ * pre-handler, and era-conflict admission keeps modern claims off legacy
+ * connections). Reads only public context surface (`ctx.mcpReq.envelope`).
+ */
+export declare function isModernEraRequest(ctx: Pick<ServerContext, "mcpReq"> | undefined): boolean;
 export declare function errorResource(uri: string, error: string | {
     message: string;
     code?: ErrorCode;
     details?: unknown;
-}): ReadResourceResult;
+}, ctx?: Pick<ServerContext, "mcpReq">): ReadResourceResult;
 export {};

package/dist/mcp-helpers.js

@@ -1,3 +1,6 @@
+import { ResourceNotFoundError } from "@modelcontextprotocol/server";
+import { PROBLEM_DETAILS_READ_CACHE_FIELDS } from "./cache-policy.js";
+import { CLIENT_CAPABILITIES_META_KEY, PROTOCOL_VERSION_META_KEY } from "./era-classifier.js";
 import { ERROR_CODES } from "./errors.js";
 import { retryClassForErrorCode, issueOriginForErrorCode, extractAllowlistedContext } from "./error-mapping.js";
 import { toHints, extractValidatedSuggestionAndExamples, extractFieldErrorsFromDetails } from "./tool-guidance.js";
@@ -25,15 +28,18 @@ export function objectResource(uri, data) {
         ]
     };
 }
+function isResourceNotFoundErrorCode(code) {
+    return (code === ERROR_CODES.FILE_NOT_FOUND ||
+        code === ERROR_CODES.SOURCE_NOT_FOUND ||
+        code === ERROR_CODES.CLASS_NOT_FOUND ||
+        code === ERROR_CODES.VERSION_NOT_FOUND ||
+        code === ERROR_CODES.JAR_NOT_FOUND);
+}
 function statusForResourceErrorCode(code) {
     if (code === ERROR_CODES.INVALID_INPUT) {
         return 400;
     }
-    if (code === ERROR_CODES.FILE_NOT_FOUND ||
-        code === ERROR_CODES.SOURCE_NOT_FOUND ||
-        code === ERROR_CODES.CLASS_NOT_FOUND ||
-        code === ERROR_CODES.VERSION_NOT_FOUND ||
-        code === ERROR_CODES.JAR_NOT_FOUND) {
+    if (isResourceNotFoundErrorCode(code)) {
         return 404;
     }
     if (code === ERROR_CODES.MAPPING_UNAVAILABLE ||
@@ -43,10 +49,38 @@ function statusForResourceErrorCode(code) {
     }
     return 500;
 }
-export function errorResource(uri, error) {
+/** Shallow plain-object check, mirroring era-classifier's canonical helper. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether the request being handled carries the FULL shallow modern
+ * (2026-07-28) era signal in its lifted `_meta` envelope: a string
+ * protocol-version AND a plain-object clientCapabilities — the same shallow
+ * modern-signal check era-classifier's `classifyEraSignal` applies at
+ * supervisor admission (kept in lockstep; that module is the canonical
+ * definition). The version key ALONE is not enough: a claim-shaped-INVALID
+ * request (version present, capabilities missing/invalid) is
+ * legacy-permissively forwarded on a legacy-locked connection, the SDK's
+ * era-blind lift still surfaces the key at `ctx.mcpReq.envelope`, and the
+ * reply is encoded by the LEGACY codec — which serializes handler-returned
+ * fields verbatim. Shallow-VALID envelopes, by contrast, are answered by the
+ * 2026 codec (the SDK rejects envelope-less modern requests -32602
+ * pre-handler, and era-conflict admission keeps modern claims off legacy
+ * connections). Reads only public context surface (`ctx.mcpReq.envelope`).
+ */
+export function isModernEraRequest(ctx) {
+    const envelope = ctx?.mcpReq?.envelope;
+    return (typeof envelope?.[PROTOCOL_VERSION_META_KEY] === "string" &&
+        isPlainObject(envelope[CLIENT_CAPABILITIES_META_KEY]));
+}
+export function errorResource(uri, error, ctx) {
     const isStr = typeof error === "string";
     const detail = isStr ? error : error.message;
     const code = isStr ? ERROR_CODES.INVALID_INPUT : error.code ?? ERROR_CODES.INTERNAL;
+    if (!isStr && isModernEraRequest(ctx) && isResourceNotFoundErrorCode(code)) {
+        throw new ResourceNotFoundError(uri, detail);
+    }
     // Resource reads carry the same AppError as the equivalent tool call, so they
     // get the same recovery metadata. Classifiers are always present; the rest is
     // extracted from the AppError details (reusing the tool-error helpers as-is so
@@ -57,6 +91,14 @@ export function errorResource(uri, error) {
     const fieldErrors = extractFieldErrorsFromDetails(details);
     const context = extractAllowlistedContext(details);
     return {
+        // ProblemDetails-read cache override (adopted policy): STRUCTURAL
+        // identification — this constructor IS the error-resource path, so the
+        // override never re-infers from serialized text. Emitted as
+        // handler-returned result fields (SDK precedence rank 1, beating the
+        // resource's configured class-row hint) and gated to modern-era requests
+        // because the 2025 codec serializes handler-returned fields verbatim —
+        // legacy replies must stay byte-identical to the frozen golden surfaces.
+        ...(isModernEraRequest(ctx) ? PROBLEM_DETAILS_READ_CACHE_FIELDS : {}),
         contents: [
             {
                 uri,

package/dist/minecraft-explorer-service.d.ts

@@ -1,5 +1,5 @@
 import type { Config } from "./types.js";
-export type MappingNamespace = "obfuscated" | "mojang" | "yarn";
+export type MappingNamespace = "obfuscated" | "mojang" | "intermediary" | "yarn";
 type SignatureAccess = "public" | "all";
 export interface ResponseContext {
     minecraftVersion: string;

package/dist/mixin/types.d.ts

@@ -185,6 +185,10 @@ export type AccessWidenerValidationResult = {
         invalid: number;
     };
     provenance?: RuntimeValidationProvenance<SourceMapping>;
+    /** True when the runtime jar used for evidence was not an exact match for the request. */
+    approximate?: boolean;
+    /** Why the verdict is approximate; present only alongside `approximate`. */
+    approximationReasons?: string[];
     warnings: string[];
 };
 export type AccessTransformerValidationResult = {
@@ -204,5 +208,9 @@ export type AccessTransformerValidationResult = {
         invalid: number;
     };
     provenance?: RuntimeValidationProvenance<AccessTransformerNamespace>;
+    /** True when the runtime jar used for evidence was not an exact match for the request. */
+    approximate?: boolean;
+    /** Why the verdict is approximate; present only alongside `approximate`. */
+    approximationReasons?: string[];
     warnings: string[];
 };

package/dist/mod-analyzer.js

@@ -26,13 +26,13 @@ const fabricModJsonSchema = z
     name: z.string().optional(),
     version: z.string().optional(),
     description: z.string().optional(),
-    entrypoints: z.record(z.array(stringOrEntrypoint)).optional(),
+    entrypoints: z.record(z.string(), z.array(stringOrEntrypoint)).optional(),
     mixins: z.array(stringOrMixinRef).optional(),
     accessWidener: z.string().optional(),
-    depends: z.record(z.union([z.string(), z.array(z.string())])).optional(),
-    recommends: z.record(z.union([z.string(), z.array(z.string())])).optional(),
-    conflicts: z.record(z.union([z.string(), z.array(z.string())])).optional(),
-    suggests: z.record(z.union([z.string(), z.array(z.string())])).optional(),
+    depends: z.record(z.string(), z.union([z.string(), z.array(z.string())])).optional(),
+    recommends: z.record(z.string(), z.union([z.string(), z.array(z.string())])).optional(),
+    conflicts: z.record(z.string(), z.union([z.string(), z.array(z.string())])).optional(),
+    suggests: z.record(z.string(), z.union([z.string(), z.array(z.string())])).optional(),
     jars: z.array(z.object({ file: z.string() }).passthrough()).optional()
 })
     .passthrough();
@@ -50,7 +50,7 @@ const quiltModJsonSchema = z
         })
             .passthrough()
             .optional(),
-        entrypoints: z.record(z.array(stringOrEntrypoint)).optional(),
+        entrypoints: z.record(z.string(), z.array(stringOrEntrypoint)).optional(),
         depends: z.array(z.unknown()).optional()
     })
         .passthrough()
@@ -72,7 +72,7 @@ const forgeModsTomlSchema = z
     })
         .passthrough())
         .optional(),
-    dependencies: z.record(z.array(z.unknown())).optional(),
+    dependencies: z.record(z.string(), z.array(z.unknown())).optional(),
     mixins: z.array(z.object({ config: z.string() }).passthrough()).optional(),
     accessTransformers: z.array(z.object({ file: z.string().optional() }).passthrough()).optional()
 })

package/dist/mod-decompile-service.js

@@ -193,6 +193,7 @@ export class ModDecompileService {
         const decompileResult = await decompileBinaryJar(jarPath, this.config.cacheDir, {
             vineflowerJarPath: vineflowerPath,
             timeoutMs: DECOMPILE_TIMEOUT_MS,
+            maxMemoryMb: this.config.decompileMaxMemoryMb,
             signature: cacheKey
         });
         const files = decompileResult.javaFiles.map((entry) => entry.filePath);

package/dist/nbt/java-nbt-codec.js

@@ -16,18 +16,28 @@ const TAG_ID_BY_NAME = {
     longArray: 12
 };
 const TAG_NAME_BY_ID = Object.fromEntries(Object.entries(TAG_ID_BY_NAME).map(([name, id]) => [id, name]));
+// Default repair guidance, mirroring the per-stage `nextAction` the size-limit path
+// already sets. `toHints()` reads only `details.nextAction`, so without one these
+// rejections reach the client with nothing actionable at all. A caller-supplied
+// `nextAction` still wins: the spread comes last.
+const PARSE_NEXT_ACTION = "The payload is not a well-formed Java NBT stream at the reported offset. Check that " +
+    "nbtBase64 holds the whole file and that compression matches how it was written " +
+    '(use compression "auto" to detect gzip).';
+const ENCODE_NEXT_ACTION = "The typed document could not be written as Java NBT. Correct the node named by " +
+    "jsonPointer, then retry; round-tripping a real payload through nbt-to-json yields a " +
+    "document this encoder accepts.";
 function parseError(message, details) {
     return createError({
         code: ERROR_CODES.NBT_PARSE_FAILED,
         message,
-        details
+        details: { nextAction: PARSE_NEXT_ACTION, ...details }
     });
 }
 function encodeError(message, details) {
     return createError({
         code: ERROR_CODES.NBT_ENCODE_FAILED,
         message,
-        details
+        details: { nextAction: ENCODE_NEXT_ACTION, ...details }
     });
 }
 function resolveTagName(tagId, pointer) {

package/dist/nbt/json-patch.js

@@ -7,25 +7,36 @@ function isRecord(value) {
         !Array.isArray(value) &&
         !ArrayBuffer.isView(value));
 }
+// Default repair guidance, mirroring the per-stage `nextAction` the NBT size-limit path
+// already sets. `toHints()` reads only `details.nextAction`, so without one these
+// rejections reach the client with nothing actionable. A caller-supplied `nextAction`
+// still wins: the spread comes last.
+const INVALID_PATCH_NEXT_ACTION = 'The patch must be an RFC6902 array of {"op": "add"|"remove"|"replace"|"test", "path": ' +
+    '"/json/pointer", "value": <typed-nbt-node>} objects. Paths address the typed document ' +
+    '(for example "/root/value/<key>"), and an added or replaced value is a typed node, not a bare scalar.';
+const UNSUPPORTED_FEATURE_NEXT_ACTION = "This operation is not expressible in Java NBT. Rewrite it in terms the format supports " +
+    "(homogeneous lists, typed compound entries, decimal-string longs) and retry.";
+const PATCH_CONFLICT_NEXT_ACTION = "The document did not hold what the patch expected at that path. Re-read the current " +
+    "document with nbt-to-json and rebuild the patch against it.";
 function invalidPatch(message, details) {
     throw createError({
         code: ERROR_CODES.JSON_PATCH_INVALID,
         message,
-        details
+        details: { nextAction: INVALID_PATCH_NEXT_ACTION, ...details }
     });
 }
 function unsupportedFeature(message, details) {
     throw createError({
         code: ERROR_CODES.NBT_UNSUPPORTED_FEATURE,
         message,
-        details
+        details: { nextAction: UNSUPPORTED_FEATURE_NEXT_ACTION, ...details }
     });
 }
 function patchConflict(message, details) {
     throw createError({
         code: ERROR_CODES.JSON_PATCH_CONFLICT,
         message,
-        details
+        details: { nextAction: PATCH_CONFLICT_NEXT_ACTION, ...details }
     });
 }
 function parsePatchOperations(patch) {

package/dist/nbt/pipeline.js

@@ -1,5 +1,6 @@
 import { gunzipSync, gzipSync } from "node:zlib";
-import { createError, ERROR_CODES } from "../errors.js";
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { AppError, createError, ERROR_CODES } from "../errors.js";
 import { decodeJavaNbt, encodeJavaNbt } from "./java-nbt-codec.js";
 import { applyJsonPatch } from "./json-patch.js";
 import { assertValidTypedNbtDocument } from "./typed-json.js";
@@ -46,6 +47,42 @@ function limitExceeded(stage, field, actual, limit) {
         }
     });
 }
+/**
+ * `assertValidTypedNbtDocument` has six call sites and knows nothing about tools, so the
+ * recovery suggestion is attached here — the only layer that knows which tool the caller
+ * invoked. The suggestion is a TEMPLATE (it needs the caller's own base64 payload), so it
+ * travels as `exampleCalls`; `params: undefined` means the primary-drop marker is never
+ * set and no "payload failed schema validation" hint is appended.
+ */
+function assertValidTypedNbtDocumentForTool(value, tool) {
+    try {
+        assertValidTypedNbtDocument(value);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== ERROR_CODES.NBT_INVALID_TYPED_JSON) {
+            throw error;
+        }
+        throw createError({
+            code: error.code,
+            // Frozen: an approved-deviation ProblemDetails golden asserts this text verbatim.
+            message: error.message,
+            details: {
+                ...error.details,
+                ...buildSuggestedCall({
+                    tool: "nbt-to-json",
+                    params: undefined,
+                    examples: [
+                        {
+                            params: { nbtBase64: "<base64-encoded-nbt-payload>" },
+                            reason: `Decode a real NBT payload with nbt-to-json to obtain a well-formed typedJson ` +
+                                `document, edit that, then retry ${tool} with it.`
+                        }
+                    ]
+                })
+            }
+        });
+    }
+}
 function assertByteLimit(stage, field, actual, limit) {
     if (actual > limit) {
         limitExceeded(stage, field, actual, limit);
@@ -149,7 +186,7 @@ export function nbtBase64ToTypedJson(input, limits = DEFAULT_NBT_LIMITS) {
 }
 export function typedJsonToNbtBase64(input, limits = DEFAULT_NBT_LIMITS) {
     const compression = parseEncodeCompression(input.compression);
-    assertValidTypedNbtDocument(input.typedJson);
+    assertValidTypedNbtDocumentForTool(input.typedJson, "json-to-nbt");
     let output = encodeJavaNbt(input.typedJson);
     if (compression === "gzip") {
         output = gzipSync(output);
@@ -165,7 +202,7 @@ export function typedJsonToNbtBase64(input, limits = DEFAULT_NBT_LIMITS) {
     };
 }
 export function applyNbtJsonPatch(input, limits = DEFAULT_NBT_LIMITS) {
-    assertValidTypedNbtDocument(input.typedJson);
+    assertValidTypedNbtDocumentForTool(input.typedJson, "nbt-apply-json-patch");
     const patched = applyJsonPatch(input.typedJson, input.patch);
     assertByteLimit("patch-output", "typedJson", jsonUtf8Bytes(patched.typedJson), limits.maxResponseBytes);
     return patched;

package/dist/nbt/typed-json.js

@@ -205,13 +205,38 @@ export function validateTypedNbtDocument(value) {
     }
     return validateNode(value.root, "/root");
 }
+/**
+ * Prose form of the document contract. The `typedJson` argument is advertised on the
+ * wire as an empty JSON Schema (`{}`) and those bytes are frozen for legacy parity, so
+ * the rejection is the only place a caller can be told what the document must look
+ * like. Kept in sync with `docs/tool-reference.md` -> "Typed NBT document shape".
+ */
+const TYPED_NBT_DOCUMENT_SHAPE = 'A typed NBT document is {"rootName": <string>, "root": <node>}, where every node is ' +
+    '{"type": "byte|short|int|long|float|double|byteArray|string|list|compound|intArray|longArray", "value": ...}; ' +
+    'a "list" node also carries "elementType", and "long"/"longArray" values are decimal strings.';
 export function assertValidTypedNbtDocument(value) {
     const validation = validateTypedNbtDocument(value);
     if (!validation.ok) {
+        const { jsonPointer, expectedType, actualType } = validation.issue;
+        // A root-level failure has an empty JSON pointer, which is useless as a field path;
+        // fall back to the argument name so the caller has something to act on.
+        const fieldPath = jsonPointer || "typedJson";
         throw createError({
             code: ERROR_CODES.NBT_INVALID_TYPED_JSON,
             message: "Invalid typed NBT JSON document.",
-            details: { ...validation.issue }
+            details: {
+                // The raw issue triple stays in place: existing readers index it directly.
+                ...validation.issue,
+                fieldErrors: [
+                    {
+                        path: fieldPath,
+                        message: `expected ${expectedType}, received ${actualType}`,
+                        code: "nbt_invalid_node"
+                    }
+                ],
+                nextAction: `Correct ${fieldPath}: expected ${expectedType}, received ${actualType}. ` +
+                    TYPED_NBT_DOCUMENT_SHAPE
+            }
         });
     }
 }

package/dist/registration-adapter.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { CallToolResult, McpServer, ServerContext, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
+/**
+ * Validation-bypassing Standard Schema adapter for MCP SDK v2 tool
+ * registration.
+ *
+ * The v2 SDK validates tool arguments through `schema["~standard"].validate`
+ * before invoking the handler and returns generic InvalidParams text on
+ * failure. This adapter's identity `validate` passes ALL object args through
+ * raw so runTool() remains the single source of truth for validation and
+ * error envelopes (matching pre-migration behavior, where the equivalent v1
+ * layer was bypassed).
+ *
+ * `jsonSchema` is a Converter object whose `input()` serves the pinned
+ * pre-migration wire schema for the tool (V1_PARITY_SCHEMAS), advertised
+ * VERBATIM in tools/list. The zod fallback only applies to tools without a
+ * frozen fixture (none today).
+ */
+export declare function appValidated<S extends z.ZodObject>(name: string, schema: S): StandardSchemaWithJSON<unknown, z.output<S>>;
+/**
+ * Tool handler shape used by all app registrations: raw (unvalidated) args
+ * plus the v2 ServerContext. Handlers delegate validation to runTool().
+ */
+export type AppToolHandler = (args: unknown, ctx: ServerContext) => Promise<CallToolResult>;
+/**
+ * Registers a tool through the v2 `registerTool` API with the
+ * validation-bypassing adapter, preserving the v1 registration surface
+ * (name, description, zod raw shape, annotations, handler).
+ */
+export declare function registerAppTool(server: McpServer, name: string, description: string, shape: z.ZodRawShape, annotations: ToolAnnotations, handler: AppToolHandler): void;
+export declare const EXPERT_TOOL_NOTE = " Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.";
+export declare function registerExpertTool(server: McpServer, name: string, description: string, shape: z.ZodRawShape, annotations: ToolAnnotations, handler: AppToolHandler): void;

package/dist/registration-adapter.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { V1_PARITY_SCHEMAS } from "./v1-parity-schemas.js";
+/**
+ * Validation-bypassing Standard Schema adapter for MCP SDK v2 tool
+ * registration.
+ *
+ * The v2 SDK validates tool arguments through `schema["~standard"].validate`
+ * before invoking the handler and returns generic InvalidParams text on
+ * failure. This adapter's identity `validate` passes ALL object args through
+ * raw so runTool() remains the single source of truth for validation and
+ * error envelopes (matching pre-migration behavior, where the equivalent v1
+ * layer was bypassed).
+ *
+ * `jsonSchema` is a Converter object whose `input()` serves the pinned
+ * pre-migration wire schema for the tool (V1_PARITY_SCHEMAS), advertised
+ * VERBATIM in tools/list. The zod fallback only applies to tools without a
+ * frozen fixture (none today).
+ */
+export function appValidated(name, schema) {
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "app",
+            validate: (value) => ({ value: value }),
+            jsonSchema: {
+                input: () => V1_PARITY_SCHEMAS[name] ?? z.toJSONSchema(schema, { io: "input" })
+            }
+        }
+    };
+}
+/**
+ * Registers a tool through the v2 `registerTool` API with the
+ * validation-bypassing adapter, preserving the v1 registration surface
+ * (name, description, zod raw shape, annotations, handler).
+ */
+export function registerAppTool(server, name, description, shape, annotations, handler) {
+    server.registerTool(name, {
+        description,
+        inputSchema: appValidated(name, z.object(shape)),
+        annotations
+    }, handler);
+}
+// Low-level/expert tools duplicate capability that the six entry tools expose
+// in a single resolve+fetch call. registerExpertTool() registers them exactly
+// like registerAppTool() but appends a note steering agents to the entry tools
+// first. Entry tools, batch tools, and the NBT/runtime utilities (which have no
+// entry equivalent) keep their plain descriptions via registerAppTool().
+export const EXPERT_TOOL_NOTE = " Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.";
+export function registerExpertTool(server, name, description, shape, annotations, handler) {
+    registerAppTool(server, name, description + EXPERT_TOOL_NOTE, shape, annotations, handler);
+}
+//# sourceMappingURL=registration-adapter.js.map

package/dist/request-context.d.ts

@@ -0,0 +1,7 @@
+export type RequestContext = {
+    requestId: string;
+    deadlineAt?: number;
+    signal?: AbortSignal;
+};
+export declare function runWithRequestContext<T>(context: RequestContext, fn: () => T): T;
+export declare function getRequestContext(): RequestContext | undefined;

package/dist/request-context.js

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const requestContextStorage = new AsyncLocalStorage();
+export function runWithRequestContext(context, fn) {
+    return requestContextStorage.run(context, fn);
+}
+export function getRequestContext() {
+    return requestContextStorage.getStore();
+}
+//# sourceMappingURL=request-context.js.map

package/dist/resources.d.ts

@@ -1,3 +1,3 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 import type { SourceService } from "./source-service.js";
 export declare function registerResources(server: McpServer, sourceService: SourceService): void;