@adhisang/minecraft-modding-mcp 6.1.0 → 6.2.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [6.2.0] - 2026-07-11
+
+### Added
+
+- Workspace ergonomics for artifact addressing, all additive: (1) `find-class`, `get-artifact-file`, `list-artifact-files`, `search-class-source`, and `index-artifact` accept the shared `target` shape as an alternative to a flat `artifactId` (mutually exclusive — exactly one must be supplied; existing `artifactId` calls are unchanged). (2) `analyze-symbol` infers an omitted `version` from a supplied `projectPath` instead of rejecting at schema time; inferred runs always carry a `versionInference { version, source }` block plus a warning, an explicit `version` is never overridden, and an undetectable version fails with `ERR_WORKSPACE_VERSION_UNRESOLVED`. (3) `inspect-minecraft` direct subjects (`class`/`file`/`search`) without `subject.artifact` auto-resolve through the workspace only when exactly one workspace is known, always with a provenance warning; several known workspaces refuse with `workspaceCandidates`, and an explicit `subject.artifact` is never overridden.
+
+- Bytecode member reads now surface annotation metadata: annotation-type classes (`@interface`) expose each member's default value as `annotationDefault` (rendered from the `AnnotationDefault` attribute, including string/enum/class/array/nested-annotation and numeric constants), and `get-class-members` gains an optional `includeAnnotations` flag that adds runtime-visible member annotations (e.g. `@java.lang.Deprecated`) to each member. Defaults are always present when the classfile carries them; member annotations appear only under the opt-in flag. `analyze-mod` `task="members"` includes both without a flag. No new dependencies — the existing classfile reader parses the attribute bodies.
+
+- `analyze-mod` gains a `members` task (`subject: { kind: "class", jarPath, className }`) that reads a mod class's constructors, fields, and methods (all access levels, including private and protected) directly from bytecode — no decompiler invocation on this path, unlike `task: "class-source"`. Responses carry `extractionMethod: "bytecode-only"`. Additive: existing tasks and inputs are unchanged, and the tool count stays at 41.
+
+- `get-artifact-file` serves `assets/**` and `data/**` text files (including vanilla `data/minecraft/dimension_type/*.json`, and resources in any jar-backed artifact such as mod jars) directly from the backing jar when the source index has no row for them — responses carry `deliveryMode: "jar-read-through"`. Delivery is text-only with a 512 KiB per-file cap and explicit `truncated` flag; binary entries answer with size metadata and a `contentOmittedReason` instead of content; traversal-shaped paths are rejected with `ERR_INVALID_INPUT`; misses return `ERR_FILE_NOT_FOUND` with `nearbyPaths` hints that surface directory relocations such as the `assets/minecraft/models/item/*` → `assets/minecraft/items/*` move. The `list-artifact-files` assets/data warning now points at this read-through path.
+
+- Class-not-found errors (`ERR_CLASS_NOT_FOUND`) from `get-class-source`, `get-class-members`, and their batch variants now include a top-level `didYouMean` array with ranked near-miss candidates from the artifact's symbol index — `{ className, matchReason }` with reasons `exact-simple-name` (moved class, ranked first), `case-insensitive`, and `edit-distance:N`. A stale fully-qualified name like a pre-move `ItemTransform` package now names the current location instead of dead-ending. The array is empty when the index has no usable candidates, and candidates are phrased as hints, not assertions.
+
+- Jar-in-Jar shell jars (near-zero own classes, content bundled under `META-INF/jars`, like the Fabric API umbrella jar) resolve instead of failing with `ERR_DECOMPILER_FAILED`. The resolved artifact carries `qualityFlags: ["shell-jar"]` and the nested-jar inventory in `provenance.nestedJars` (also surfaced by `analyze-mod-jar` as `nestedJars`); `get-class-source` and `get-class-members` redirect automatically to the single nested jar containing the requested class, marking the response with `provenance.nestedJar`. A class present in several nested jars returns the new `ERR_NESTED_JAR_AMBIGUOUS` error with `nestedJarCandidates` instead of a silent pick, and class-not-found errors on shells list the inventory. Extracted nested jars live in a content-addressed `nested-jars` cache directory, manageable via `manage-cache` `cacheKinds: ["nested-jar"]`.
+
+- `validate-project` calls now have a supervisor-owned 120-second end-to-end deadline, configurable with `MCP_VALIDATE_PROJECT_TIMEOUT_MS` from 10,000 through 600,000 ms. Expiry returns the standard synthetic `{ error, meta }` tool-result envelope with `ERR_TOOL_TIMEOUT`, queue/running phase diagnostics, redacted progress context, and restart-initiation state. Queue expiry leaves the active worker untouched; running expiry replaces the isolated worker and preserves admitted later requests when initialization replay succeeds. Replacement startup/replay failure terminalizes queued work with existing restart errors. The supervisor FIFO holds at most two worker-bound requests and returns `ERR_LIMIT_EXCEEDED` (tool calls) or JSON-RPC `-32000` (non-tool requests) on overflow; cap-blocked requests fail immediately and undeliverable notifications are warning-dropped. POSIX process-group cleanup treats an already-gone process group as clean so stale cleanup tokens do not block later validation.
+
+### Changed
+
+- The two constant per-response warning sentences on unobfuscated versions are replaced by structured flags on `mappingContext` — agents that pattern-matched the old strings should read the flags instead. `"Version X is unobfuscated; mapping graph is empty because the runtime already uses deobfuscated names."` is now `mappingContext.unobfuscatedRuntime: true`, and `"Version X is unobfuscated; validated symbol existence against runtime bytecode."` is now `mappingContext.runtimeValidated: true` (`get-class-api-matrix`, which has no `mappingContext`, reports a top-level `unobfuscatedRuntime: true`). No information is removed: the flags carry the same facts, the full former wording stays documented in `docs/tool-reference.md`, and all other warnings are untouched.
+
+### Fixed
+
+- Loom split-source workspaces (a `minecraft-common` / `minecraft-clientOnly` sources-jar pair with no merged jar) no longer lose one half's classes to single-jar selection: version-target resolution with project Loom sources indexes the best-scored jar of the other half too (`provenance.companionSourceJars` names it), so client-only classes like `net.minecraft.client.renderer.block.model.ItemTransform` are indexed and findable via symbol search. Class-not-found errors for version targets additionally carry an `exampleCalls` retry using `scope: "vanilla"` (existing enum values only), whose client-jar decompilation also contains client-only classes.
+- Inherited-member expansion no longer emits `Could not resolve super class ...` warnings for platform packages that are never inside a Minecraft jar (`java.*`, `javax.*`, `jdk.*`, `sun.*`, and the separately-shipped `com.mojang.serialization.*` — each verified against real 26.x and 1.21.10 jars). Suppression is allowlist-only: resolution failures for real Minecraft classes, including `com.mojang.blaze3d.*` client-jar content, stay visible.
+- `check-symbol-exists` no longer reports false negatives for fields and classes on unobfuscated versions: the runtime-bytecode fallback introduced in 6.0.0 only re-checked `not_found` verdicts for methods, so a mapping graph lacking a record for a real field like `EntityType.ITEM` returned `not_found` without consulting the jar. Every `not_found` verdict is now runtime-checked (genuinely-missing symbols stay `not_found`), and bytecode-derived response contexts report `mappingNamespace: "mojang"` on unobfuscated versions instead of a hardcoded `"obfuscated"`.
+- Dependency version detection probes the snake_case transforms of hyphenated artifact names (`fabric_api_version` and the compound `fabric_api_fabric_api_version` for `net.fabricmc.fabric-api:fabric-api`). Previously only submodules received a snake_case umbrella fallback key, so resolving the umbrella artifact itself against a standard Fabric template that declares `fabric_api_version` failed with `ERR_DEPENDENCY_VERSION_UNRESOLVED`.
+- Umbrella submodule dependency targets (e.g. `net.fabricmc.fabric-api:fabric-gametest-api-v1`) no longer copy the umbrella's version into the submodule coordinate, which synthesized nonexistent coordinates like `fabric-gametest-api-v1:0.153.0+26.2` and failed downstream. Resolution now adopts the single cached modules-2 version, or — when several are cached — the version named by the cached umbrella POM's `<dependency>` entry (recorded as `provenance.submoduleVersionSource: "umbrella-pom"`). Anything still ambiguous fails closed with `ERR_DEPENDENCY_VERSION_UNRESOLVED` and `candidatesSeen` instead of guessing.
+
+## [6.1.1] - 2026-07-04
+
+### Fixed
+
+- `check-symbol-exists` no longer misreports an overridden method as unresolved in exact-signature mode. Requesting inherited methods surfaces the same name + descriptor from both the overriding and overridden owner, and the exact-signature branch treated that as an ambiguous match; it now treats any match as resolved and only zero matches as `not_found`.
+- NBT JSON-patch validation rejects raw non-finite `float`/`double` numbers (`Infinity`, `-Infinity`, `NaN`) again. A prior fix for the `"NaN"`/`"Infinity"`/`"-Infinity"` sentinel-string round-trip had also stopped rejecting raw non-finite JS numbers, which cannot survive JSON serialization and would silently corrupt the document.
+
 ## [6.1.0] - 2026-06-28
 
 ### Added

package/README.md

@@ -147,7 +147,7 @@ All six return `result.summary` first and can include `summary.nextActions` when
 | `inspect-minecraft` | versions, artifacts, classes, files, and source search |
 | `analyze-symbol` | symbol existence checks, mapping conversion, lifecycle tracing, and workspace symbol resolution |
 | `compare-minecraft` | version-pair diffs, class diffs, registry diffs, and migration-oriented overviews |
-| `analyze-mod` | mod metadata, decompile/search flows, class source, and safe remap preview/apply |
+| `analyze-mod` | mod metadata, decompile/search flows, class source, bytecode member queries, and safe remap preview/apply |
 | `validate-project` | workspace summaries plus direct Mixin, Access Widener, and Access Transformer validation |
 | `manage-cache` | cache inventory, verification, and preview/apply cleanup workflows |
 
@@ -163,6 +163,8 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - `validate-project task="project-summary"` propagates `preferProjectVersion=true` across discovered Mixin, Access Widener, and Access Transformer checks. If no version can be resolved from the request or `gradle.properties`, the summary returns recovery guidance instead of guessing.
 - `validate-mixin` and `validate-project` keep `mapping-health` lightweight for `obfuscated` and `mojang` validation, avoiding full Tiny mapping graph loads unless `intermediary` or `yarn` namespaces are requested.
 - `validate-project task="project-summary"` uses a lightweight artifact probe for `tasks["minecraft.artifact.resolved"]`; it does not decompile Minecraft or rebuild the source index just to report per-probe status. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
+- `validate-project` has a supervisor-owned end-to-end deadline of 120 seconds, including queue time. Set `MCP_VALIDATE_PROJECT_TIMEOUT_MS` to an ASCII-decimal value from `10000` through `600000` to override it. A timeout returns `ERR_TOOL_TIMEOUT`; a running timeout restarts the isolated worker before queued calls resume, while a queue timeout leaves the current worker untouched.
+- Queued calls resume only after the replacement worker completes initialization replay. If replacement startup or replay fails, queued tool calls terminate with `ERR_WORKER_RESTART` instead of waiting indefinitely. If unresolved process-tree cleanup fills the supervisor's two live-generation slots, new requests fail with the existing restart envelope and unavailable notifications are warning-dropped until cleanup or reconnect. On POSIX, an already-gone process group counts as cleaned up rather than leaving a stale cleanup token.
 - If a workspace was built with `GRADLE_USER_HOME=/tmp/...` or another isolated Gradle home, pass that path as `gradleUserHome` so source, mapping, runtime, and project validation lookups use the same Loom cache instead of stale caches under the MCP process home.
 - `manage-cache` reports corrupt Mojang binary-remap cache directories under `cacheKinds: ["binary-remap"]` with `status: "corrupt"`, and can delete them by `selector.artifactId` in preview/apply workflows.
 
@@ -262,7 +264,7 @@ Start with these top-level workflow tools unless you already know the exact spec
 | `inspect-minecraft` | Inspect versions, artifacts, classes, files, source text, and workspace-aware lookup flows |
 | `analyze-symbol` | Handle symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol resolution, and API overviews |
 | `compare-minecraft` | Compare version pairs, class diffs, registry diffs, and migration-oriented summaries |
-| `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, and preview or apply remaps |
+| `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, read class members from bytecode, and preview or apply remaps |
 | `validate-project` | Summarize workspaces and run direct Mixin, Access Widener, or Access Transformer validation |
 | `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |
 <!-- END GENERATED TOOL TABLE: top-level-workflow-tools -->

package/dist/cache-registry.d.ts

@@ -1,6 +1,6 @@
 import { type PathRuntimeInfo } from "./path-converter.js";
 import { type WorkspaceContextCache } from "./workspace-context-cache.js";
-export declare const PUBLIC_CACHE_KINDS: readonly ["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap", "workspace"];
+export declare const PUBLIC_CACHE_KINDS: readonly ["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap", "nested-jar", "workspace"];
 export type PublicCacheKind = (typeof PUBLIC_CACHE_KINDS)[number];
 export declare const CACHE_HEALTH_STATES: readonly ["healthy", "partial", "stale", "orphaned", "corrupt", "in_use"];
 export type CacheHealthState = (typeof CACHE_HEALTH_STATES)[number];

package/dist/cache-registry.js

@@ -14,6 +14,7 @@ export const PUBLIC_CACHE_KINDS = [
     "decompiled-source",
     "mod-remap",
     "binary-remap",
+    "nested-jar",
     "workspace"
 ];
 export const CACHE_HEALTH_STATES = [
@@ -44,6 +45,8 @@ function kindRoot(config, cacheKind) {
             return join(config.cacheDir, "remapped-mods");
         case "binary-remap":
             return join(config.cacheDir, "remapped");
+        case "nested-jar":
+            return join(config.cacheDir, "nested-jars");
         case "workspace":
             return "<in-memory:workspace-context-cache>";
     }

package/dist/entry-tools/analyze-mod-service.d.ts

@@ -1,7 +1,7 @@
 import type { AnalyzeModOptions, ModAnalysisResult } from "../mod-analyzer.js";
 import { z } from "zod";
 export declare const analyzeModShape: {
-    task: z.ZodEnum<["summary", "decompile", "search", "class-source", "remap"]>;
+    task: z.ZodEnum<["summary", "decompile", "search", "class-source", "members", "remap"]>;
     subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"jar">;
         jarPath: z.ZodString;
@@ -38,7 +38,7 @@ export declare const analyzeModShape: {
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
 };
 export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
-    task: z.ZodEnum<["summary", "decompile", "search", "class-source", "remap"]>;
+    task: z.ZodEnum<["summary", "decompile", "search", "class-source", "members", "remap"]>;
     subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"jar">;
         jarPath: z.ZodString;
@@ -75,7 +75,7 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     limit: number;
-    task: "search" | "summary" | "class-source" | "remap" | "decompile";
+    task: "search" | "summary" | "class-source" | "members" | "remap" | "decompile";
     subject: {
         kind: "jar";
         jarPath: string;
@@ -96,7 +96,7 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     outputJar?: string | undefined;
     maxFiles?: number | undefined;
 }, {
-    task: "search" | "summary" | "class-source" | "remap" | "decompile";
+    task: "search" | "summary" | "class-source" | "members" | "remap" | "decompile";
     subject: {
         kind: "jar";
         jarPath: string;
@@ -119,7 +119,7 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     maxFiles?: number | undefined;
 }>, {
     limit: number;
-    task: "search" | "summary" | "class-source" | "remap" | "decompile";
+    task: "search" | "summary" | "class-source" | "members" | "remap" | "decompile";
     subject: {
         kind: "jar";
         jarPath: string;
@@ -140,7 +140,7 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     outputJar?: string | undefined;
     maxFiles?: number | undefined;
 }, {
-    task: "search" | "summary" | "class-source" | "remap" | "decompile";
+    task: "search" | "summary" | "class-source" | "members" | "remap" | "decompile";
     subject: {
         kind: "jar";
         jarPath: string;
@@ -196,6 +196,12 @@ type AnalyzeModDeps = {
     }) => Promise<Record<string, unknown> & {
         warnings?: string[];
     }>;
+    getModClassMembers: (input: {
+        jarPath: string;
+        className: string;
+    }) => Promise<Record<string, unknown> & {
+        warnings?: string[];
+    }>;
 };
 export declare class AnalyzeModService {
     private readonly deps;

package/dist/entry-tools/analyze-mod-service.js

@@ -20,7 +20,7 @@ const subjectSchema = z.discriminatedUnion("kind", [
     })
 ]);
 export const analyzeModShape = {
-    task: z.enum(["summary", "decompile", "search", "class-source", "remap"]),
+    task: z.enum(["summary", "decompile", "search", "class-source", "members", "remap"]),
     subject: subjectSchema,
     query: nonEmptyString.optional(),
     searchType: z.enum(["class", "method", "field", "content", "all"]).default("all"),
@@ -43,11 +43,11 @@ export const analyzeModSchema = z.object(analyzeModShape).superRefine((value, ct
             message: `${value.task} requires subject.kind=jar.`
         });
     }
-    if (value.task === "class-source" && value.subject.kind !== "class") {
+    if ((value.task === "class-source" || value.task === "members") && value.subject.kind !== "class") {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["subject", "kind"],
-            message: "class-source requires subject.kind=class."
+            message: `${value.task} requires subject.kind=class.`
         });
     }
     if (value.task === "search" && !value.query) {
@@ -206,6 +206,40 @@ export class AnalyzeModService {
                     warnings: Array.isArray(output.warnings) ? output.warnings : []
                 };
             }
+            case "members": {
+                if (input.subject.kind !== "class") {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "members requires subject.kind=class."
+                    });
+                }
+                const output = await this.deps.getModClassMembers({
+                    jarPath: input.subject.jarPath,
+                    className: input.subject.className
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "members",
+                        detail,
+                        include,
+                        summary: {
+                            status: "ok",
+                            headline: `Read bytecode members of ${input.subject.className}.`,
+                            subject: createSummarySubject({
+                                task: "members",
+                                kind: input.subject.kind,
+                                jarPath: input.subject.jarPath,
+                                className: input.subject.className
+                            })
+                        },
+                        blocks: {
+                            members: output
+                        },
+                        alwaysBlocks: ["members"]
+                    }),
+                    warnings: Array.isArray(output.warnings) ? output.warnings : []
+                };
+            }
             case "remap": {
                 const normalizedInputJar = normalizePathForHost(input.subject.jarPath, undefined, "jarPath");
                 const analysis = await this.deps.analyzeModJar(normalizedInputJar);

package/dist/entry-tools/analyze-symbol-service.d.ts

@@ -180,6 +180,7 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
 }>;
 export type AnalyzeSymbolInput = z.infer<typeof analyzeSymbolSchema>;
 type AnalyzeSymbolDeps = {
+    detectProjectMinecraftVersion: (projectPath: string) => Promise<string | undefined>;
     checkSymbolExists: (input: {
         version: string;
         kind: "class" | "field" | "method";
@@ -254,5 +255,6 @@ export declare class AnalyzeSymbolService {
     execute(input: AnalyzeSymbolInput): Promise<Record<string, unknown> & {
         warnings?: string[];
     }>;
+    private dispatch;
 }
 export {};

package/dist/entry-tools/analyze-symbol-service.js

@@ -112,11 +112,11 @@ const LIFECYCLE_ONLY_FIELDS = [
     "includeSnapshots"
 ];
 export const analyzeSymbolSchema = z.object(analyzeSymbolShape).superRefine((value, ctx) => {
-    if (value.task !== "lifecycle" && !value.version) {
+    if (value.task !== "lifecycle" && !value.version && !value.projectPath) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["version"],
-            message: "version is required for non-lifecycle tasks."
+            message: "version is required for non-lifecycle tasks (or pass projectPath so the version can be inferred from the workspace)."
         });
     }
     if (value.task === "lifecycle" && !value.version && !value.toVersion) {
@@ -189,6 +189,41 @@ export class AnalyzeSymbolService {
         const detail = resolveDetail(input.detail);
         const include = resolveInclude(input.include);
         const { kind: subjectKind, warning: inferenceWarning } = inferSubjectKind(input.subject);
+        // Omitted version with a supplied projectPath: infer from the workspace.
+        // Inference always carries provenance (versionInference block + warning);
+        // an explicit version is never overridden.
+        let versionInference;
+        if (input.task !== "lifecycle" && !input.version && input.projectPath) {
+            const detected = await this.deps.detectProjectMinecraftVersion(input.projectPath);
+            if (!detected) {
+                throw createError({
+                    code: ERROR_CODES.WORKSPACE_VERSION_UNRESOLVED,
+                    message: `Could not infer a Minecraft version from ${input.projectPath}.`,
+                    details: {
+                        projectPath: input.projectPath,
+                        nextAction: "Declare minecraft_version (or mc_version) in gradle.properties, or pass version explicitly."
+                    }
+                });
+            }
+            versionInference = {
+                version: detected,
+                source: `projectPath:gradle.properties (${input.projectPath})`
+            };
+            input = { ...input, version: detected };
+        }
+        const inferenceWarnings = versionInference
+            ? [
+                `version was inferred from the workspace: ${versionInference.version} (source: ${versionInference.source}).`
+            ]
+            : [];
+        const result = await this.dispatch(input, detail, include, subjectKind, inferenceWarning);
+        if (versionInference) {
+            result.versionInference = versionInference;
+            result.warnings = [...(result.warnings ?? []), ...inferenceWarnings];
+        }
+        return result;
+    }
+    async dispatch(input, detail, include, subjectKind, inferenceWarning) {
         switch (input.task) {
             case "exists": {
                 const output = await this.deps.checkSymbolExists({

package/dist/entry-tools/inspect-minecraft/internal.d.ts

@@ -1015,6 +1015,10 @@ export type InspectMinecraftDeps = {
         cursor?: string;
     }) => Promise<ListArtifactFilesOutput>;
     detectProjectMinecraftVersion: (projectPath: string) => Promise<string | undefined>;
+    listWorkspaceContexts: () => Array<{
+        projectPath: string;
+        minecraftVersion?: string;
+    }>;
 };
 export declare function requireWorkspaceClassFocus(subject: Subject): WorkspaceClassFocus;
 export declare function requireWorkspaceSearchFocus(subject: Subject): WorkspaceSearchFocus;

package/dist/entry-tools/inspect-minecraft/internal.js

@@ -392,6 +392,31 @@ export async function resolveArtifactReference(deps, subject, task) {
     }
     if (subject.kind === "class" || subject.kind === "file" || subject.kind === "search") {
         if (!subject.artifact) {
+            // Guardrailed auto-resolution: an omitted subject.artifact resolves
+            // through the workspace ONLY when exactly one workspace is known, and
+            // the response always carries a provenance warning. An explicit
+            // subject.artifact is never overridden (this branch requires absence).
+            const workspaces = deps.listWorkspaceContexts();
+            const unique = workspaces.length === 1 ? workspaces[0] : undefined;
+            if (unique) {
+                const version = unique.minecraftVersion ??
+                    (await deps.detectProjectMinecraftVersion(unique.projectPath));
+                if (version) {
+                    const artifact = await deps.resolveArtifact({
+                        target: { kind: "version", value: version },
+                        projectPath: unique.projectPath
+                    });
+                    return {
+                        artifactId: artifact.artifactId,
+                        artifact,
+                        version,
+                        warnings: [
+                            `subject.artifact was omitted; auto-resolved through the unique known workspace ${unique.projectPath} (Minecraft ${version}). Pass subject.artifact to target a different artifact.`,
+                            ...artifact.warnings
+                        ]
+                    };
+                }
+            }
             const suggestedTask = task
                 ?? (subject.kind === "class"
                     ? "class-overview"
@@ -403,6 +428,9 @@ export async function resolveArtifactReference(deps, subject, task) {
                 message: `${subject.kind} subject requires artifact context.`,
                 details: {
                     nextAction: "Add subject.artifact or use subject.kind=workspace so inspect-minecraft can resolve the artifact first.",
+                    ...(workspaces.length > 1
+                        ? { workspaceCandidates: workspaces.map((workspace) => workspace.projectPath) }
+                        : {}),
                     ...(await buildArtifactContextSuggestedCall(deps, suggestedTask, subject))
                 }
             });

package/dist/entry-tools/manage-cache-service.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { type CacheRegistry } from "../cache-registry.js";
 export declare const manageCacheShape: {
     action: z.ZodEnum<["summary", "list", "inspect", "delete", "prune", "rebuild", "verify"]>;
-    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap", "workspace"]>, "many">>;
+    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap", "nested-jar", "workspace"]>, "many">>;
     selector: z.ZodOptional<z.ZodObject<{
         artifactId: z.ZodOptional<z.ZodString>;
         version: z.ZodOptional<z.ZodString>;
@@ -42,7 +42,7 @@ export declare const manageCacheShape: {
 };
 export declare const manageCacheSchema: z.ZodObject<{
     action: z.ZodEnum<["summary", "list", "inspect", "delete", "prune", "rebuild", "verify"]>;
-    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap", "workspace"]>, "many">>;
+    cacheKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap", "nested-jar", "workspace"]>, "many">>;
     selector: z.ZodOptional<z.ZodObject<{
         artifactId: z.ZodOptional<z.ZodString>;
         version: z.ZodOptional<z.ZodString>;
@@ -86,7 +86,7 @@ export declare const manageCacheSchema: z.ZodObject<{
     cursor?: string | undefined;
     detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
-    cacheKinds?: ("workspace" | "artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap" | "binary-remap")[] | undefined;
+    cacheKinds?: ("workspace" | "artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap" | "binary-remap" | "nested-jar")[] | undefined;
     selector?: {
         version?: string | undefined;
         projectPath?: string | undefined;
@@ -105,7 +105,7 @@ export declare const manageCacheSchema: z.ZodObject<{
     detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
     executionMode?: "preview" | "apply" | undefined;
-    cacheKinds?: ("workspace" | "artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap" | "binary-remap")[] | undefined;
+    cacheKinds?: ("workspace" | "artifact-index" | "downloads" | "mapping" | "registry" | "decompiled-source" | "mod-remap" | "binary-remap" | "nested-jar")[] | undefined;
     selector?: {
         version?: string | undefined;
         projectPath?: string | undefined;

package/dist/error-mapping.d.ts

@@ -38,6 +38,10 @@ export type RetryClass = "transient" | "permanent" | "server" | "environment" |
  * - `environment`: a server capability is missing (Java, decompiler, remapper).
  */
 export type IssueOrigin = "code_issue" | "tool_issue" | "environment";
+export type DidYouMeanCandidate = {
+    className: string;
+    matchReason: string;
+};
 export type ProblemDetails = {
     type: string;
     title: string;
@@ -51,9 +55,18 @@ export type ProblemDetails = {
     hints?: string[];
     suggestedCall?: SuggestedCall;
     exampleCalls?: ExampleCall[];
+    /** Ranked near-miss candidates for a class/symbol that was not found. */
+    didYouMean?: DidYouMeanCandidate[];
     failedStage?: string;
     context?: Record<string, string | number | boolean>;
 };
+/**
+ * Validates and extracts a `didYouMean` array from error details. Like
+ * `suggestedCall`, it travels as a dedicated typed field — the primitive-only
+ * context allowlist is not loosened for it. Malformed payloads are dropped
+ * whole rather than partially published.
+ */
+export declare function extractDidYouMean(details: unknown): DidYouMeanCandidate[] | undefined;
 export declare function statusForErrorCode(code: string): number;
 /**
  * Single source of truth mapping an error code to its {@link RetryClass}. Used

package/dist/error-mapping.js

@@ -1,5 +1,30 @@
 import { ERROR_CODES, isAppError } from "./errors.js";
 import { log } from "./logger.js";
+const MAX_DID_YOU_MEAN_ENTRIES = 16;
+/**
+ * Validates and extracts a `didYouMean` array from error details. Like
+ * `suggestedCall`, it travels as a dedicated typed field — the primitive-only
+ * context allowlist is not loosened for it. Malformed payloads are dropped
+ * whole rather than partially published.
+ */
+export function extractDidYouMean(details) {
+    const raw = details?.didYouMean;
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const cleaned = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object") {
+            return undefined;
+        }
+        const { className, matchReason } = entry;
+        if (typeof className !== "string" || typeof matchReason !== "string") {
+            return undefined;
+        }
+        cleaned.push({ className, matchReason });
+    }
+    return cleaned.slice(0, MAX_DID_YOU_MEAN_ENTRIES);
+}
 export function statusForErrorCode(code) {
     if (code === ERROR_CODES.BATCH_ABORTED) {
         return 412;
@@ -9,6 +34,9 @@ export function statusForErrorCode(code) {
         // not an internal server failure.
         return 408;
     }
+    if (code === ERROR_CODES.TOOL_TIMEOUT) {
+        return 408;
+    }
     if (code === ERROR_CODES.INVALID_INPUT ||
         code === ERROR_CODES.COORDINATE_PARSE_FAILED ||
         code === ERROR_CODES.INVALID_LINE_RANGE ||
@@ -35,7 +63,8 @@ export function statusForErrorCode(code) {
         code === ERROR_CODES.DECOMPILE_DISABLED ||
         code === ERROR_CODES.REMAP_FAILED ||
         code === ERROR_CODES.WORKSPACE_VERSION_UNRESOLVED ||
-        code === ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED) {
+        code === ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED ||
+        code === ERROR_CODES.NESTED_JAR_AMBIGUOUS) {
         return 422;
     }
     if (code === ERROR_CODES.REMAPPER_UNAVAILABLE ||
@@ -82,6 +111,7 @@ const RETRY_CLASS_PERMANENT = new Set([
     ERROR_CODES.REMAP_FAILED,
     ERROR_CODES.WORKSPACE_VERSION_UNRESOLVED,
     ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED,
+    ERROR_CODES.NESTED_JAR_AMBIGUOUS,
     ERROR_CODES.PROVENANCE_INCOMPLETE,
     ERROR_CODES.BATCH_ABORTED
 ]);
@@ -145,7 +175,8 @@ const ISSUE_ORIGIN_CODE = new Set([
     ERROR_CODES.JAR_NOT_FOUND,
     ERROR_CODES.VERSION_NOT_FOUND,
     ERROR_CODES.WORKSPACE_VERSION_UNRESOLVED,
-    ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED
+    ERROR_CODES.DEPENDENCY_VERSION_UNRESOLVED,
+    ERROR_CODES.NESTED_JAR_AMBIGUOUS
 ]);
 /**
  * Single source of truth mapping an error code to its {@link IssueOrigin}.
@@ -243,6 +274,7 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
         const baseHints = extractHints(caughtError.details);
         const fieldErrors = extractFieldErrors(caughtError.details);
         const context = extractAllowlistedContext(caughtError.details);
+        const didYouMean = extractDidYouMean(caughtError.details);
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -255,6 +287,7 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
             ...(fieldErrors ? { fieldErrors } : {}),
             ...(baseHints ? { hints: baseHints } : {}),
             ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {}),
+            ...(didYouMean ? { didYouMean } : {}),
             ...(context ? { context } : {})
         };
     }

package/dist/errors.d.ts

@@ -31,10 +31,12 @@ export declare const ERROR_CODES: {
     readonly REMAP_FAILED: "ERR_REMAP_FAILED";
     readonly REMAPPER_UNAVAILABLE: "ERR_REMAPPER_UNAVAILABLE";
     readonly WORKER_RESTART: "ERR_WORKER_RESTART";
+    readonly TOOL_TIMEOUT: "ERR_TOOL_TIMEOUT";
     readonly MIXIN_PARSE_FAILED: "ERR_MIXIN_PARSE_FAILED";
     readonly STAGE_BUDGET_PRE_PARSE: "ERR_STAGE_BUDGET_PRE_PARSE";
     readonly WORKSPACE_VERSION_UNRESOLVED: "ERR_WORKSPACE_VERSION_UNRESOLVED";
     readonly DEPENDENCY_VERSION_UNRESOLVED: "ERR_DEPENDENCY_VERSION_UNRESOLVED";
+    readonly NESTED_JAR_AMBIGUOUS: "ERR_NESTED_JAR_AMBIGUOUS";
     readonly BATCH_ABORTED: "ERR_BATCH_ABORTED";
     readonly INTERNAL: "ERR_INTERNAL";
 };

package/dist/errors.js

@@ -31,10 +31,12 @@ export const ERROR_CODES = {
     REMAP_FAILED: "ERR_REMAP_FAILED",
     REMAPPER_UNAVAILABLE: "ERR_REMAPPER_UNAVAILABLE",
     WORKER_RESTART: "ERR_WORKER_RESTART",
+    TOOL_TIMEOUT: "ERR_TOOL_TIMEOUT",
     MIXIN_PARSE_FAILED: "ERR_MIXIN_PARSE_FAILED",
     STAGE_BUDGET_PRE_PARSE: "ERR_STAGE_BUDGET_PRE_PARSE",
     WORKSPACE_VERSION_UNRESOLVED: "ERR_WORKSPACE_VERSION_UNRESOLVED",
     DEPENDENCY_VERSION_UNRESOLVED: "ERR_DEPENDENCY_VERSION_UNRESOLVED",
+    NESTED_JAR_AMBIGUOUS: "ERR_NESTED_JAR_AMBIGUOUS",
     BATCH_ABORTED: "ERR_BATCH_ABORTED",
     INTERNAL: "ERR_INTERNAL"
 };