@adhisang/minecraft-modding-mcp 6.1.1 → 6.3.0

package/CHANGELOG.md

@@ -5,7 +5,46 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [6.3.0] - 2026-07-18
+
+### Added
+
+- `find-class` accepts top-level `projectPath` for workspace-relative `target.kind="workspace"` and dependency targets using `versionFromProject`, and searches simple or qualified class names across nested `.class` inventories when the resolved artifact is a Jar-in-Jar shell such as the Fabric API umbrella JAR. Nested matches retain the existing response shape, deduplicate repeated qualified names, and honor `limit`; top-level matches remain directly usable by the source/member tools.
+
+### Fixed
+
+- `inspect-minecraft` now describes `task`, structured workspace `subject.focus`, and each class/search/file focus branch in `tools/list`. A string focus remains invalid instead of being guessed or coerced, but its `ERR_INVALID_INPUT` response now includes three schema-validated `exampleCalls` that preserve valid workspace context and show the exact object shapes for retrying.
+- `find-class` no longer interprets a native dependency or Jar-in-Jar shell miss as evidence of obfuscated Minecraft runtime names, so it does not recommend `mapping="mojang"` for those artifacts. Dotted inner-class names discovered in a shell also continue through `get-class-source` instead of missing the binary `$` entry.
+
+## [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
 

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 |
 
@@ -156,13 +156,15 @@ All six return `result.summary` first and can include `summary.nextActions` when
 These notes cover high-frequency decisions during onboarding. For the full pitfall list, exact contracts, migration notes, and environment variables, see [docs/tool-reference.md](docs/tool-reference.md).
 
 - `search-class-source` defaults to `queryMode="auto"` and keeps separator queries such as `foo.bar`, `foo_bar`, and `foo$bar` on the indexed path. Use `queryMode="literal"` for an explicit full substring scan.
-- If you do not already have an artifact, prefer `subject.kind="workspace"` for `inspect-minecraft` instead of guessing artifact details. When artifact context is the only missing input, a retryable `suggestedCall` preserves the requested task.
+- If you do not already have an artifact, prefer `subject.kind="workspace"` for `inspect-minecraft` instead of guessing artifact details. `subject.focus` is an object, not a string: use `{ "kind": "class", "className": "..." }`, `{ "kind": "search", "query": "..." }`, or `{ "kind": "file", "filePath": "..." }`. `task="auto"` dispatches only from `subject.kind` and `focus.kind`; it is not a natural-language planner. Invalid string focus returns class/search/file `exampleCalls`, while missing artifact context keeps the requested task in a retryable `suggestedCall`.
 - `trace-symbol-lifecycle` expects `Class.method` in `symbol`. Keep exact overload matching in the separate `descriptor` field.
 - For unobfuscated releases such as `26.1+`, `check-symbol-exists` and `analyze-symbol task="exists"` validate `mojang` lookups against runtime bytecode when no mapping graph exists, and return `mapping_unavailable` when the runtime JAR itself is unreachable.
 - `analyze-mod` and `validate-project` require structured `subject` objects and canonical `include` groups; stale string-subject or domain-include payloads return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
 - `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 -->
@@ -276,7 +278,7 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading o
 | --- | --- |
 | `list-versions` | List available Minecraft versions from Mojang metadata and local cache |
 | `resolve-artifact` | Resolve source artifacts from versions, JAR paths, or Maven coordinates |
-| `find-class` | Find simple or fully-qualified class names inside an artifact |
+| `find-class` | Find simple or fully-qualified class names, including classes bundled in nested JARs |
 | `get-class-source` | Read class source from an artifact or resolve the backing artifact on demand |
 | `get-class-members` | List constructors, fields, and methods from bytecode |
 | `search-class-source` | Search indexed class source by symbol, text, or path |
@@ -285,6 +287,8 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading o
 | `index-artifact` | Rebuild indexed metadata for an existing artifact |
 <!-- END GENERATED TOOL TABLE: source-exploration -->
 
+`find-class` accepts either an `artifactId` or the shared object `target` shape. For a workspace-relative dependency, pass `target: { kind: "dependency", group, name, versionFromProject: true }` with top-level `projectPath`. Fabric-style umbrella JARs are searched through their nested `.class` inventories; a top-level class match can then be passed to `get-class-source` or `get-class-members`, which resolve the containing nested JAR. Dotted inner-class matches are also readable through `get-class-source`. An empty result still means that the requested class name is absent from the resolved dependency version.
+
 For unobfuscated releases such as `26.1+`, `mapping="mojang"` uses the runtime/decompile path directly and skips Loom source-jar discovery, while `intermediary` and `yarn` fall back to `obfuscated` with a warning.
 
 ### Version Comparison & Symbol Tracking
@@ -413,12 +417,16 @@ pnpm test
 
 Run these when relevant:
 
+- `pnpm test:file <path...>` for focused ordinary suites
+- `pnpm test:grep <name-pattern>` for recursive ordinary suites filtered by test name
 - `pnpm test:manual:stdio-smoke` for MCP transport, registration, or manual workflow changes
 - `pnpm test:manual:package-smoke` when checking packaged install and distribution behavior
 - `pnpm test:perf` for search, index, or performance-sensitive changes
 - `pnpm test:coverage` or `pnpm test:coverage:lcov` for coverage checks (`lines=80`, `branches=70`, `functions=80`)
 - `pnpm validate` for the full local validation suite
 
+Ordinary `.test.ts` files live in domain directories under `tests/` (for example `source-service/`, `entry-tools/`, `mapping/`, `mixin/`, `integration/mcp-tools/`, `contracts/`, and `utils/`). Keep helper-only modules in `tests/helpers`; manual smoke, performance, resource, and smoke-only files remain in their existing special directories.
+
 ## License
 
 [MIT](LICENSE)

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

@@ -90,10 +90,10 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
     targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    gradleUserHome?: string | undefined;
     maxVersions?: number | undefined;
     sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
-    gradleUserHome?: string | undefined;
     includeSnapshots?: boolean | undefined;
     fromVersion?: string | undefined;
     toVersion?: string | undefined;
@@ -114,10 +114,10 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
     targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    gradleUserHome?: string | undefined;
     maxVersions?: number | undefined;
     sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
-    gradleUserHome?: string | undefined;
     nameMode?: "auto" | "fqcn" | undefined;
     includeSnapshots?: boolean | undefined;
     fromVersion?: string | undefined;
@@ -142,10 +142,10 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
     targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    gradleUserHome?: string | undefined;
     maxVersions?: number | undefined;
     sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
-    gradleUserHome?: string | undefined;
     includeSnapshots?: boolean | undefined;
     fromVersion?: string | undefined;
     toVersion?: string | undefined;
@@ -166,10 +166,10 @@ export declare const analyzeSymbolSchema: z.ZodEffects<z.ZodObject<{
     detail?: "summary" | "standard" | "full" | undefined;
     include?: string[] | undefined;
     targetMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
+    gradleUserHome?: string | undefined;
     maxVersions?: number | undefined;
     sourceMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     classNameMapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
-    gradleUserHome?: string | undefined;
     nameMode?: "auto" | "fqcn" | undefined;
     includeSnapshots?: boolean | undefined;
     fromVersion?: string | undefined;
@@ -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

@@ -401,6 +401,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     scope?: "vanilla" | "merged" | "loader" | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
+    gradleUserHome?: string | undefined;
     artifact?: {
         artifactId: string;
         type: "resolved-id";
@@ -411,7 +412,6 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
         };
         type: "resolve-target";
     } | undefined;
-    gradleUserHome?: string | undefined;
 }, {
     kind: "class";
     className: string;
@@ -420,6 +420,7 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
     scope?: "vanilla" | "merged" | "loader" | undefined;
     preferProjectVersion?: boolean | undefined;
     strictVersion?: boolean | undefined;
+    gradleUserHome?: string | undefined;
     artifact?: {
         artifactId: string;
         type: "resolved-id";
@@ -430,7 +431,6 @@ export declare const subjectSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject
         };
         type: "resolve-target";
     } | undefined;
-    gradleUserHome?: string | undefined;
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"file">;
     filePath: z.ZodString;
@@ -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;
@@ -1040,7 +1044,7 @@ export declare function resolveWorkspaceArtifactReference(deps: InspectMinecraft
     version?: string;
     warnings: string[];
 }>;
-export declare function resolveTask(task: InspectMinecraftTask | undefined, subject: Subject | undefined): "search" | "class-source" | "artifact" | "file" | "versions" | "class-members" | "class-overview" | "list-files";
+export declare function resolveTask(task: InspectMinecraftTask | undefined, subject: Subject | undefined): "search" | "class-source" | "file" | "class-overview" | "class-members" | "artifact" | "versions" | "list-files";
 export declare function summarizeRequestedSubject(subject: Subject): Record<string, unknown>;
 export declare function taskForSubject(subject: Subject): ConcreteInspectMinecraftTask;
 export declare function invalidTaskSubjectError(task: ConcreteInspectMinecraftTask, subject: Subject): never;

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

@@ -30,27 +30,27 @@ export const artifactRefSchema = z.discriminatedUnion("type", [
 ]);
 export const workspaceFocusSchema = z.discriminatedUnion("kind", [
     z.object({
-        kind: z.literal("class"),
-        className: nonEmptyString,
-        artifact: artifactRefSchema.optional()
-    }),
+        kind: z.literal("class").describe("Select class inspection."),
+        className: nonEmptyString.describe("Fully-qualified class name to inspect."),
+        artifact: artifactRefSchema.optional().describe("Optional explicit artifact override; otherwise resolve it from the workspace.")
+    }).describe('Class focus object: {"kind":"class","className":"net.minecraft.world.item.Item"}. task=auto dispatches it to class-overview; select class-source or class-members explicitly when needed.'),
     z.object({
-        kind: z.literal("file"),
-        filePath: nonEmptyString,
-        artifact: artifactRefSchema.optional()
-    }),
+        kind: z.literal("file").describe("Select an artifact-relative file read."),
+        filePath: nonEmptyString.describe("Artifact-relative file path to read."),
+        artifact: artifactRefSchema.optional().describe("Optional explicit artifact override; otherwise resolve it from the workspace.")
+    }).describe('File focus object: {"kind":"file","filePath":"net/minecraft/world/item/Item.java"}. task=auto dispatches it to file.'),
     z.object({
-        kind: z.literal("search"),
-        query: nonEmptyString,
-        artifact: artifactRefSchema.optional(),
+        kind: z.literal("search").describe("Select source search."),
+        query: nonEmptyString.describe("Source, symbol, or path query to search for."),
+        artifact: artifactRefSchema.optional().describe("Optional explicit artifact override; otherwise resolve it from the workspace."),
         intent: z.enum(["symbol", "text", "path"]).optional(),
         match: z.enum(["exact", "prefix", "contains", "regex"]).optional(),
         symbolKind: z.enum(["class", "interface", "enum", "record", "method", "field"]).optional(),
         packagePrefix: nonEmptyString.optional(),
         fileGlob: nonEmptyString.optional(),
         queryMode: z.enum(["auto", "token", "literal"]).default("auto")
-    })
-]);
+    }).describe('Search focus object: {"kind":"search","query":"CreativeModeTab"}. task=auto dispatches it to search.')
+]).describe('Structured workspace focus. Object, not string. Choose {kind:"class",className}, {kind:"file",filePath}, or {kind:"search",query}.');
 export const subjectSchema = z.discriminatedUnion("kind", [
     z.object({
         kind: z.literal("version"),
@@ -108,8 +108,8 @@ export const subjectSchema = z.discriminatedUnion("kind", [
         preferProjectVersion: z.boolean().optional(),
         strictVersion: z.boolean().optional(),
         focus: workspaceFocusSchema.optional()
-    })
-]);
+    }).describe("Workspace subject. Resolves Minecraft artifact context from projectPath; add a structured focus object for class, file, or search work.")
+]).describe("Structured inspection subject. Use kind=workspace with a structured focus object when the workspace should resolve artifact context.");
 export function hasPartialVanillaCoverage(artifact) {
     return artifact?.qualityFlags.includes("partial-source-no-net-minecraft") === true
         || artifact?.artifactContents.sourceCoverage === "partial";
@@ -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))
                 }
             });