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

package/dist/mapping/loaders/tiny-loom-selection.js

@@ -26,9 +26,16 @@ const MAX_INDEX_ENTRY_BUDGET = 64_000_000;
  * overrides it outright.
  */
 export function resolveTinyIndexEntryBudget(value = process.env.MCP_LOOM_TINY_MAX_INDEX_ENTRIES, heapStats = v8.getHeapStatistics()) {
-    const override = Number.parseInt(value ?? "", 10);
-    if (Number.isFinite(override) && override > 0) {
-        return override;
+    // Strict ASCII digits and safe integers only, mirroring `loadMaxFrameBytes` and
+    // `loadMaxDownloadBytes`. Number.parseInt stops at the first non-digit, so "1e9",
+    // "2_000_000", "10M" and "1.9" used to be accepted as 1, 2, 10 and 1 — a budget
+    // that truncates every real Loom load. No floor is applied: an explicit override
+    // is allowed to be small on purpose.
+    if (/^[0-9]+$/.test(value ?? "")) {
+        const override = Number(value);
+        if (Number.isSafeInteger(override) && override > 0) {
+            return override;
+        }
     }
     const free = Math.max(0, heapStats.heap_size_limit - heapStats.used_heap_size);
     const derived = Math.floor((free * HEAP_BUDGET_FRACTION) / HEAP_BYTES_PER_INDEX_ENTRY);

package/dist/mapping/parsers/tiny.js

@@ -128,6 +128,10 @@ export function parseTinyMappingsInto(target, text, options) {
             for (const namespace of header.columns) {
                 const value = columns[namespace.columnIndex]?.trim() ?? "";
                 if (!value) {
+                    // A class row that omits this namespace ends the previous class's name
+                    // for it. Leaving the stale entry made the following field/method rows
+                    // register under the PREVIOUS class as owner, at confidence 1.
+                    currentClassNames.delete(namespace.mapping);
                     continue;
                 }
                 currentClassNames.set(namespace.mapping, value);

package/dist/mapping-service.js

@@ -145,6 +145,10 @@ export class MappingService {
                 candidates: [],
                 candidateCount: 0,
                 warnings: [
+                    // A truncated Loom index (or a source that yielded nothing) is often WHY the
+                    // path is missing, so the loader's own warnings lead the no-path sentence
+                    // instead of being replaced by it.
+                    ...graph.warnings,
                     `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`
                 ]
             };
@@ -164,7 +168,10 @@ export class MappingService {
             .map((candidate) => queryRecord.kind === "method" && queryRecord.descriptor
             ? projectLookupCandidateDescriptor(candidate, queryRecord.descriptor, projectedDescriptor)
             : candidate);
-        const warnings = [];
+        // Seeded from the graph so loader-level warnings (a truncated Loom index, a tiny
+        // source that yielded nothing) reach the caller. ensureMappingAvailable,
+        // getClassApiMatrix and checkSymbolExists already do this.
+        const warnings = [...graph.warnings];
         // signatureMode="exact" on kind=method must not return descriptorless fallback candidates
         // (lookupCandidates adds owner+name fallbacks by design for the loose path). Without this
         // filter a caller who supplied `foo(I)V` could be told `foo(Z)V` is the exact mapping,
@@ -374,11 +381,18 @@ export class MappingService {
                 candidates: [],
                 candidateCount: 0,
                 warnings: [
+                    // A truncated Loom index (or a source that yielded nothing) is often WHY the
+                    // path is missing, so the loader's own warnings lead the no-path sentence
+                    // instead of being replaced by it.
+                    ...graph.warnings,
                     `No mapping path is available for ${sourceMapping} -> ${targetMapping} on version "${version}".`
                 ]
             };
         }
-        const warnings = [];
+        // Seeded from the graph so loader-level warnings (a truncated Loom index, a tiny
+        // source that yielded nothing) reach the caller. ensureMappingAvailable,
+        // getClassApiMatrix and checkSymbolExists already do this.
+        const warnings = [...graph.warnings];
         const descriptorProjection = this.projectMethodDescriptorToTarget(graph, path, descriptor);
         const projectedDescriptor = descriptorProjection.complete ? descriptorProjection.descriptor : undefined;
         const rawCandidates = this
@@ -475,7 +489,14 @@ export class MappingService {
                 `${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.`);
+                `declaring class directly.` +
+                // An owner with no package never projects along the mapping path (simple-name
+                // class matches are deliberately excluded), so it is rejected for its shape
+                // rather than for inheritance. Saying so stops the message misdirecting.
+                (owner.includes(".")
+                    ? ""
+                    : ` "${owner}" is also not fully qualified: an unqualified owner cannot be projected ` +
+                        `into ${targetMapping} and can never match, so supply the fully-qualified owner.`));
         }
         if (descriptorProjection.hadClassReferences && !descriptorProjection.complete) {
             warnings.push(pathUsesSource(graph.pairs, path, "mojang-client-mappings")

package/dist/maven-resolver.d.ts

@@ -11,7 +11,68 @@ export interface MavenCandidate {
     sourceUrl?: string;
     binaryUrl?: string;
 }
+/**
+ * Parses `group:artifact:version[:classifier]` - and is the single place a
+ * caller-supplied coordinate is checked before any of it becomes a path.
+ *
+ * Every segment ends up as a directory or file-name component downstream (the
+ * local `~/.m2` layout, the Gradle cache layout, and a remote repository URL),
+ * so a segment carrying `/` or `..` would walk out of the repository root it
+ * was resolved against. Validating here rather than at each sink means the nine
+ * consumers of this function inherit the rule and cannot drift apart - which is
+ * exactly how two different group-to-path builders came to exist.
+ *
+ * The rule is `isSafeMavenSegment`, the same one the `dependency` route now
+ * applies to its `group`, `name` and `version` before it probes anything. That
+ * route synthesises a coordinate and lands on these same sinks, so the two
+ * cannot be allowed to answer differently. Its `..` clause rejects a groupId
+ * like `a..b`; that input is contained under both builders and so is not a
+ * safety matter, but a doubled dot yields an empty Maven path segment and is
+ * not publishable, and rejecting it keeps the two routes answering identically.
+ *
+ * `version` and `classifier` additionally admit U+0020, because
+ * `net.fabricmc:yarn:1.14 Pre-Release 1+build.10:v2` is a published coordinate
+ * (see `SAFE_MAVEN_VALUE_RE`); `groupId` and `artifactId` do not.
+ *
+ * Each segment is trimmed before it is checked, so `"g : a : 1.0"` names the
+ * artifact it obviously means instead of failing on the padding, and a leading
+ * or trailing space cannot survive into a `version` either. `coordinate` in the
+ * error details echoes the argument this function was handed - which is the
+ * caller's own text only when the caller reached it directly; the public
+ * artifact route trims `target.value` before calling, so outer padding on a
+ * `target.kind="coordinate"` request is gone by the time it gets here.
+ */
 export declare function parseCoordinate(coordinate: string): MavenCoordinate;
+/**
+ * Whether the artifacts behind a coordinate may change under a stable name.
+ *
+ * Maven defines exactly one mutable form: a version ending in `-SNAPSHOT`,
+ * which a repository is free to republish for the same coordinate. A
+ * timestamped unique snapshot (`1.0.0-20240101.120000-3`) is the resolved,
+ * concrete build and never changes, so it is immutable - as is every release
+ * version. Callers use this to pick a cache freshness policy: mutable
+ * coordinates must be revalidated, immutable ones can be served from cache
+ * forever.
+ *
+ * The suffix is matched case-insensitively, unlike Maven's own case-sensitive
+ * `ArtifactUtils.isSnapshot`. The two error directions are not symmetric: being
+ * stricter than a repository that publishes `-snapshot` would serve a mutable
+ * artifact from cache forever, while being looser costs one conditional request
+ * per resolve on a version that almost certainly meant `-SNAPSHOT` anyway.
+ */
+export declare function isMutableMavenCoordinate(coordinate: string): boolean;
+/**
+ * The one group-to-path conversion. Exported so no caller writes its own.
+ *
+ * `split(".").filter(Boolean).join("/")` is not the same as
+ * `replace(/\./g, "/")`: dropping the empty segments means a groupId of `.`,
+ * `..` or `.a` yields `""`, `""` and `"a"` rather than `"/"`, `"//"` and
+ * `"/a"`. A leading slash is an absolute path, so under `path.resolve` the
+ * naive form escapes the repository root entirely - no `/` and no `..` needed
+ * in the input. This form cannot produce one, which makes the group leg safe by
+ * construction rather than by whatever filter runs upstream of it.
+ */
+export declare function groupToPath(groupId: string): string;
 export declare function normalizedCoordinateValue(coordinate: string): string;
 export declare function resolveLocalM2Candidate(localM2Path: string, coordinateValue: string): MavenCandidate;
 export declare function localArtifactPathsFromCoordinate(localM2Path: string, coordinate: string): MavenCandidate;

package/dist/maven-resolver.js

@@ -1,6 +1,38 @@
 import { accessSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { ERROR_CODES, createError } from "./errors.js";
+import { describeSafeMavenSegmentRule, isSafeMavenSegment } from "./maven-token.js";
+/**
+ * Parses `group:artifact:version[:classifier]` - and is the single place a
+ * caller-supplied coordinate is checked before any of it becomes a path.
+ *
+ * Every segment ends up as a directory or file-name component downstream (the
+ * local `~/.m2` layout, the Gradle cache layout, and a remote repository URL),
+ * so a segment carrying `/` or `..` would walk out of the repository root it
+ * was resolved against. Validating here rather than at each sink means the nine
+ * consumers of this function inherit the rule and cannot drift apart - which is
+ * exactly how two different group-to-path builders came to exist.
+ *
+ * The rule is `isSafeMavenSegment`, the same one the `dependency` route now
+ * applies to its `group`, `name` and `version` before it probes anything. That
+ * route synthesises a coordinate and lands on these same sinks, so the two
+ * cannot be allowed to answer differently. Its `..` clause rejects a groupId
+ * like `a..b`; that input is contained under both builders and so is not a
+ * safety matter, but a doubled dot yields an empty Maven path segment and is
+ * not publishable, and rejecting it keeps the two routes answering identically.
+ *
+ * `version` and `classifier` additionally admit U+0020, because
+ * `net.fabricmc:yarn:1.14 Pre-Release 1+build.10:v2` is a published coordinate
+ * (see `SAFE_MAVEN_VALUE_RE`); `groupId` and `artifactId` do not.
+ *
+ * Each segment is trimmed before it is checked, so `"g : a : 1.0"` names the
+ * artifact it obviously means instead of failing on the padding, and a leading
+ * or trailing space cannot survive into a `version` either. `coordinate` in the
+ * error details echoes the argument this function was handed - which is the
+ * caller's own text only when the caller reached it directly; the public
+ * artifact route trims `target.value` before calling, so outer padding on a
+ * `target.kind="coordinate"` request is gone by the time it gets here.
+ */
 export function parseCoordinate(coordinate) {
     const values = coordinate.trim().split(":");
     if (values.length !== 3 && values.length !== 4) {
@@ -10,22 +42,81 @@ export function parseCoordinate(coordinate) {
             details: { coordinate }
         });
     }
-    const [groupId, artifactId, version, classifier] = values;
+    const groupId = values[0]?.trim() ?? "";
+    const artifactId = values[1]?.trim() ?? "";
+    const version = values[2]?.trim() ?? "";
+    const classifier = values[3]?.trim() || undefined;
     if (!groupId || !artifactId || !version) {
+        // Names the empty segment too. Every other rejection below carries
+        // `details.component`, and a caller branching on it should not have to
+        // special-case the one branch that dropped it.
+        const emptyComponent = !groupId
+            ? "groupId"
+            : !artifactId
+                ? "artifactId"
+                : "version";
         throw createError({
             code: ERROR_CODES.COORDINATE_PARSE_FAILED,
             message: `Invalid maven coordinate "${coordinate}". All fields must be non-empty.`,
-            details: { coordinate }
+            details: { coordinate, component: emptyComponent }
         });
     }
+    const segments = [
+        ["groupId", groupId],
+        ["artifactId", artifactId],
+        ["version", version],
+        // An absent classifier is not a segment; an empty or whitespace-only one
+        // has already normalised to absent above.
+        ...(classifier ? [["classifier", classifier]] : [])
+    ];
+    for (const [component, value] of segments) {
+        if (!isSafeMavenSegment(value, component)) {
+            throw createError({
+                code: ERROR_CODES.COORDINATE_PARSE_FAILED,
+                message: `Invalid maven coordinate "${coordinate}". ${describeSafeMavenSegmentRule(component)}`,
+                details: { coordinate, component }
+            });
+        }
+    }
     return {
         groupId,
         artifactId,
         version,
-        classifier: classifier?.trim() || undefined
+        classifier
     };
 }
-function groupToPath(groupId) {
+/**
+ * Whether the artifacts behind a coordinate may change under a stable name.
+ *
+ * Maven defines exactly one mutable form: a version ending in `-SNAPSHOT`,
+ * which a repository is free to republish for the same coordinate. A
+ * timestamped unique snapshot (`1.0.0-20240101.120000-3`) is the resolved,
+ * concrete build and never changes, so it is immutable - as is every release
+ * version. Callers use this to pick a cache freshness policy: mutable
+ * coordinates must be revalidated, immutable ones can be served from cache
+ * forever.
+ *
+ * The suffix is matched case-insensitively, unlike Maven's own case-sensitive
+ * `ArtifactUtils.isSnapshot`. The two error directions are not symmetric: being
+ * stricter than a repository that publishes `-snapshot` would serve a mutable
+ * artifact from cache forever, while being looser costs one conditional request
+ * per resolve on a version that almost certainly meant `-SNAPSHOT` anyway.
+ */
+export function isMutableMavenCoordinate(coordinate) {
+    return /-SNAPSHOT$/i.test(parseCoordinate(coordinate).version);
+}
+/**
+ * The one group-to-path conversion. Exported so no caller writes its own.
+ *
+ * `split(".").filter(Boolean).join("/")` is not the same as
+ * `replace(/\./g, "/")`: dropping the empty segments means a groupId of `.`,
+ * `..` or `.a` yields `""`, `""` and `"a"` rather than `"/"`, `"//"` and
+ * `"/a"`. A leading slash is an absolute path, so under `path.resolve` the
+ * naive form escapes the repository root entirely - no `/` and no `..` needed
+ * in the input. This form cannot produce one, which makes the group leg safe by
+ * construction rather than by whatever filter runs upstream of it.
+ */
+export function groupToPath(groupId) {
     return groupId.split(".").filter(Boolean).join("/");
 }
 export function normalizedCoordinateValue(coordinate) {

package/dist/maven-token.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The one definition of "safe Maven coordinate segment".
+ *
+ * Every route that turns caller-supplied text into a filesystem path component
+ * - the `coordinate` target parsed by `parseCoordinate`, and the `dependency`
+ * target that synthesises a coordinate from `group`/`name`/`version` - has to
+ * agree on what a segment may contain, because they share the same downstream
+ * sinks. Two copies of this rule would be two chances to disagree.
+ *
+ * Deliberately a leaf module: it imports nothing. `maven-resolver.ts` is the
+ * chokepoint that enforces the rule and pulls in only `node:fs`, `node:path`
+ * and `./errors.js`; importing it from `workspace-mapping-service.ts`, where
+ * the rule used to live, would drag fast-glob and the whole workspace-detection
+ * surface into the resolver's import graph.
+ *
+ * The name records where the rule was first enforced (a dependency target's
+ * `version`). The grammar is now shared by all four segments of a coordinate,
+ * with one deliberate split between them - see `SAFE_MAVEN_VALUE_RE` - and one
+ * deliberately narrower variant for tokens read off disk rather than supplied
+ * by a caller - see `isSafeMavenVersionToken`.
+ */
+/** The four components of `group:artifact:version[:classifier]`. */
+export type MavenSegmentComponent = "groupId" | "artifactId" | "version" | "classifier";
+/**
+ * Characters an IDENTIFIER segment (`groupId`, `artifactId`) may contain.
+ *
+ * Everything else is out, path separators and NUL and control characters
+ * included - a segment becomes a directory or file name verbatim.
+ */
+export declare const SAFE_MAVEN_TOKEN_RE: RegExp;
+/**
+ * The shared rule for a segment of a CALLER-SUPPLIED coordinate, per component.
+ *
+ * Both routes go through this and only this: `parseCoordinate` for a
+ * `coordinate` target, and `synthesizeDependencyTarget` for the `group`, `name`
+ * and explicit `version` of a `dependency` target. They cannot drift apart,
+ * because there is no second definition for them to drift towards.
+ */
+export declare function isSafeMavenSegment(value: string, component: MavenSegmentComponent): boolean;
+/**
+ * The identifier grammar on its own, for a version token DISCOVERED in the
+ * workspace rather than stated by a caller: a `gradle.properties` value, a
+ * `modules-2` directory entry, an umbrella POM's `<version>`.
+ *
+ * It deliberately does NOT take the space branch, so this is narrower than
+ * `isSafeMavenSegment(value, "version")`. The two inputs are not the same kind
+ * of thing. A caller naming `1.14 Pre-Release 1+build.10` has stated which
+ * artifact they want, and refusing it loses them a real one. A scan of
+ * `~/.gradle/caches/modules-2/.../<name>/` is guessing which of somebody else's
+ * directories is a version, and every name it admits becomes a candidate that
+ * can make the resolution ambiguous or supply a version the project never
+ * declared - so the narrower rule is the right default where nothing is lost by
+ * it. Widening it is a separate decision with its own evidence, not a
+ * consequence of this one.
+ */
+export declare function isSafeMavenVersionToken(token: string): boolean;
+/**
+ * The rule in words, for an error message that must not drift from the code.
+ *
+ * `label` names the field that failed as the CALLER spells it, so a caller
+ * reading the message can tell which of the four segments to fix; it defaults
+ * to the component name, and the `dependency` route passes its own field names
+ * (`group`, `name`) instead.
+ */
+export declare function describeSafeMavenSegmentRule(component: MavenSegmentComponent, label?: string): string;

package/dist/maven-token.js

@@ -0,0 +1,120 @@
+/**
+ * The one definition of "safe Maven coordinate segment".
+ *
+ * Every route that turns caller-supplied text into a filesystem path component
+ * - the `coordinate` target parsed by `parseCoordinate`, and the `dependency`
+ * target that synthesises a coordinate from `group`/`name`/`version` - has to
+ * agree on what a segment may contain, because they share the same downstream
+ * sinks. Two copies of this rule would be two chances to disagree.
+ *
+ * Deliberately a leaf module: it imports nothing. `maven-resolver.ts` is the
+ * chokepoint that enforces the rule and pulls in only `node:fs`, `node:path`
+ * and `./errors.js`; importing it from `workspace-mapping-service.ts`, where
+ * the rule used to live, would drag fast-glob and the whole workspace-detection
+ * surface into the resolver's import graph.
+ *
+ * The name records where the rule was first enforced (a dependency target's
+ * `version`). The grammar is now shared by all four segments of a coordinate,
+ * with one deliberate split between them - see `SAFE_MAVEN_VALUE_RE` - and one
+ * deliberately narrower variant for tokens read off disk rather than supplied
+ * by a caller - see `isSafeMavenVersionToken`.
+ */
+/**
+ * Characters an IDENTIFIER segment (`groupId`, `artifactId`) may contain.
+ *
+ * Everything else is out, path separators and NUL and control characters
+ * included - a segment becomes a directory or file name verbatim.
+ */
+export const SAFE_MAVEN_TOKEN_RE = /^[A-Za-z0-9._+-]+$/;
+/**
+ * The same set plus U+0020, for a VALUE segment (`version`, `classifier`).
+ *
+ * Fabric publishes Yarn against Minecraft's own pre-release ids, and those ids
+ * contain spaces: `net.fabricmc:yarn:1.14 Pre-Release 1+build.10:v2` is a real,
+ * published coordinate. A rule without this branch refuses to resolve it - a
+ * false rejection of a genuine artifact, which is the worse of the two failure
+ * directions here, because a space is not a path separator and cannot traverse
+ * a directory. Permitting it costs nothing in containment: the segment still
+ * becomes exactly one path component, and every other escape character stays
+ * out.
+ *
+ * `groupId` and `artifactId` stay on the identifier rule. Maven identifiers
+ * never contain spaces and no real ecosystem coordinate uses one there, so
+ * widening them would buy no artifact and only enlarge the accepted surface.
+ */
+const SAFE_MAVEN_VALUE_RE = /^[A-Za-z0-9._+ -]+$/;
+/**
+ * Upper bound on a segment. A sanity limit ONLY - it is not, and cannot be, a
+ * control on the length of the file name a coordinate produces: `artifactId`,
+ * `version` and `classifier` are concatenated into one name
+ * (`<artifact>-<version>-<classifier>-sources.jar`), so three segments at this
+ * bound still build a name past 600 characters. What the bound does buy is that
+ * a pathological megabyte-long input cannot be spent building paths; the
+ * filesystem's own NAME_MAX is what refuses an overlong file name, and it does
+ * so on open, harmlessly.
+ */
+const MAX_MAVEN_TOKEN_LENGTH = 200;
+/** Length, leading dot and `..` - the clauses every token shares. */
+function passesCommonTokenRules(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_MAVEN_TOKEN_LENGTH) {
+        return false;
+    }
+    if (value.startsWith(".") || value.includes("..")) {
+        return false;
+    }
+    // An already-trimmed value is the contract: a segment with leading or
+    // trailing whitespace is rejected rather than repaired here, so the one place
+    // that trims (each route, before it validates) stays the one place that
+    // decides what "the caller's segment" is. That also keeps the space branch
+    // from admitting a version of nothing but spaces.
+    return value.trim() === value;
+}
+/**
+ * The shared rule for a segment of a CALLER-SUPPLIED coordinate, per component.
+ *
+ * Both routes go through this and only this: `parseCoordinate` for a
+ * `coordinate` target, and `synthesizeDependencyTarget` for the `group`, `name`
+ * and explicit `version` of a `dependency` target. They cannot drift apart,
+ * because there is no second definition for them to drift towards.
+ */
+export function isSafeMavenSegment(value, component) {
+    if (!passesCommonTokenRules(value)) {
+        return false;
+    }
+    const pattern = component === "version" || component === "classifier" ? SAFE_MAVEN_VALUE_RE : SAFE_MAVEN_TOKEN_RE;
+    return pattern.test(value);
+}
+/**
+ * The identifier grammar on its own, for a version token DISCOVERED in the
+ * workspace rather than stated by a caller: a `gradle.properties` value, a
+ * `modules-2` directory entry, an umbrella POM's `<version>`.
+ *
+ * It deliberately does NOT take the space branch, so this is narrower than
+ * `isSafeMavenSegment(value, "version")`. The two inputs are not the same kind
+ * of thing. A caller naming `1.14 Pre-Release 1+build.10` has stated which
+ * artifact they want, and refusing it loses them a real one. A scan of
+ * `~/.gradle/caches/modules-2/.../<name>/` is guessing which of somebody else's
+ * directories is a version, and every name it admits becomes a candidate that
+ * can make the resolution ambiguous or supply a version the project never
+ * declared - so the narrower rule is the right default where nothing is lost by
+ * it. Widening it is a separate decision with its own evidence, not a
+ * consequence of this one.
+ */
+export function isSafeMavenVersionToken(token) {
+    return passesCommonTokenRules(token) && SAFE_MAVEN_TOKEN_RE.test(token);
+}
+/**
+ * The rule in words, for an error message that must not drift from the code.
+ *
+ * `label` names the field that failed as the CALLER spells it, so a caller
+ * reading the message can tell which of the four segments to fix; it defaults
+ * to the component name, and the `dependency` route passes its own field names
+ * (`group`, `name`) instead.
+ */
+export function describeSafeMavenSegmentRule(component, label = component) {
+    const allowed = component === "version" || component === "classifier"
+        ? "[A-Za-z0-9._+-] characters or the space character"
+        : "[A-Za-z0-9._+-] characters";
+    return `${label} must contain only ${allowed}, must not start with '.', and must not include '..'.`;
+}
+//# sourceMappingURL=maven-token.js.map

package/dist/mcp-helpers.js

@@ -2,7 +2,7 @@ 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 { problemClassification, extractAllowlistedContext, extractDidYouMean, extractNestedJarsField } from "./error-mapping.js";
 import { toHints, extractValidatedSuggestionAndExamples, extractFieldErrorsFromDetails } from "./tool-guidance.js";
 export function objectResult(data, options = {}) {
     return {
@@ -90,6 +90,12 @@ export function errorResource(uri, error, ctx) {
     const { suggestedCall, exampleCalls } = extractValidatedSuggestionAndExamples(details);
     const fieldErrors = extractFieldErrorsFromDetails(details);
     const context = extractAllowlistedContext(details);
+    const didYouMean = extractDidYouMean(details);
+    // The field-returning form, so a SHORTENED inventory says so here too. The
+    // inventory-only view would publish a trimmed list indistinguishable from a
+    // complete one, and a caller reading it would conclude the class is bundled
+    // in none of the inner jars.
+    const nestedJarsField = extractNestedJarsField(details);
     return {
         // ProblemDetails-read cache override (adopted policy): STRUCTURAL
         // identification — this constructor IS the error-resource path, so the
@@ -114,12 +120,17 @@ export function errorResource(uri, error, ctx) {
                         status: statusForResourceErrorCode(code),
                         code,
                         instance: uri,
-                        retryClass: retryClassForErrorCode(code),
-                        issueOrigin: issueOriginForErrorCode(code),
+                        // Shared with the tool path via the one classification builder, so
+                        // a throw site that classified itself (e.g. a tool-resolved
+                        // artifact with no binary jar) is not silently re-labelled
+                        // caller-fixable just because the caller used a resource URI.
+                        ...problemClassification(code, details),
                         ...(fieldErrors ? { fieldErrors } : {}),
                         ...(hints ? { hints } : {}),
                         ...(suggestedCall ? { suggestedCall } : {}),
                         ...(exampleCalls ? { exampleCalls } : {}),
+                        ...(didYouMean ? { didYouMean } : {}),
+                        ...nestedJarsField,
                         ...(context ? { context } : {})
                     },
                     meta: { uri }

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

@@ -5,7 +5,12 @@ export interface ResponseContext {
     minecraftVersion: string;
     mappingType: string;
     mappingNamespace: MappingNamespace;
-    jarHash: string;
+    /**
+     * Cheap per-response staleness stamp derived from the jar's path, mtime and
+     * size — NOT a hash of the jar's byte content. Named accordingly so callers
+     * do not mistake it for a content identity key.
+     */
+    jarSignature: string;
     generatedAt: string;
 }
 export interface SignatureMember {
@@ -27,6 +32,13 @@ export interface GetSignatureInput {
     access?: SignatureAccess;
     includeSynthetic?: boolean;
     includeInherited?: boolean;
+    /**
+     * True when the jar being read is a resolved dependency (Maven/Gradle)
+     * artifact rather than a vanilla Minecraft version jar. Dependency jars live
+     * under cache paths whose embedded numbers are not Minecraft versions, so the
+     * path-derived version heuristic must be skipped for them.
+     */
+    dependencyOrigin?: boolean;
 }
 export interface GetSignatureOutput {
     classAccessFlags?: number;