@adhisang/minecraft-modding-mcp 6.1.1 → 6.3.0

package/dist/tool-schemas.js

@@ -161,6 +161,7 @@ export const getClassMembersShape = {
     access: memberAccessSchema.default("public"),
     includeSynthetic: z.boolean().default(false),
     includeInherited: z.boolean().default(false),
+    includeAnnotations: z.boolean().default(false).describe("Opt-in: include runtime-visible member annotations (e.g. @Deprecated) on each member."),
     memberPattern: optionalNonEmptyString.describe(MEMBER_PATTERN_DESCRIPTION),
     projection: memberProjectionSchema.optional().describe(MEMBER_PROJECTION_DESCRIPTION),
     maxMembers: optionalPositiveInt.describe("default 150, max 5000. Page beyond the first 150 with cursor."),
@@ -348,8 +349,35 @@ export const batchMappingsShape = {
     entries: z.array(batchMappingsEntrySchema).min(1).max(50)
 };
 export const batchMappingsSchema = z.object(batchMappingsShape);
+// Exactly one of artifactId/target addresses the artifact on flat tools.
+// `target` is additive: existing flat-artifactId calls stay valid.
+function requireExactlyOneArtifactRef(value, ctx) {
+    if (value.artifactId && value.target) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["target"],
+            message: "artifactId and target are mutually exclusive."
+        });
+    }
+    if (!value.artifactId && !value.target) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["artifactId"],
+            message: "Either artifactId or target must be provided."
+        });
+    }
+}
+export const findClassShape = {
+    className: nonEmptyString.describe("Simple name (e.g. Blocks) or fully-qualified name (e.g. net.minecraft.world.level.block.Blocks)"),
+    artifactId: optionalNonEmptyString,
+    target: sourceLookupTargetSchema.optional().describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
+    projectPath: optionalNonEmptyString.describe("Workspace root for dependency or workspace target resolution."),
+    limit: optionalPositiveInt.describe("default 20, max 200")
+};
+export const findClassSchema = z.object(findClassShape).superRefine(requireExactlyOneArtifactRef);
 export const searchClassSourceShape = {
-    artifactId: nonEmptyString,
+    artifactId: optionalNonEmptyString,
+    target: sourceLookupTargetSchema.optional().describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     query: nonEmptyString,
     intent: searchIntentSchema.optional(),
     match: searchMatchSchema.optional(),
@@ -366,6 +394,7 @@ export const searchClassSourceShape = {
     include: responseIncludeParam
 };
 export const searchClassSourceSchema = z.object(searchClassSourceShape).superRefine((value, ctx) => {
+    requireExactlyOneArtifactRef(value, ctx);
     if (value.symbolKind && value.intent && value.intent !== "symbol") {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -375,20 +404,22 @@ export const searchClassSourceSchema = z.object(searchClassSourceShape).superRef
     }
 });
 export const getArtifactFileShape = {
-    artifactId: nonEmptyString,
+    artifactId: optionalNonEmptyString,
+    target: sourceLookupTargetSchema.optional().describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     filePath: nonEmptyString,
     maxBytes: optionalPositiveInt
 };
-export const getArtifactFileSchema = z.object(getArtifactFileShape);
+export const getArtifactFileSchema = z.object(getArtifactFileShape).superRefine(requireExactlyOneArtifactRef);
 export const listArtifactFilesShape = {
-    artifactId: nonEmptyString,
+    artifactId: optionalNonEmptyString,
+    target: sourceLookupTargetSchema.optional().describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     prefix: optionalNonEmptyString,
     limit: optionalPositiveInt,
     cursor: optionalNonEmptyString,
     detail: detailParam("standard"),
     include: responseIncludeParam
 };
-export const listArtifactFilesSchema = z.object(listArtifactFilesShape);
+export const listArtifactFilesSchema = z.object(listArtifactFilesShape).superRefine(requireExactlyOneArtifactRef);
 export const traceSymbolLifecycleShape = {
     symbol: nonEmptyString.describe("fully.qualified.Class.method"),
     descriptor: optionalDescriptorString.describe('optional JVM descriptor, e.g. "(I)V". Empty strings are treated as omitted.'),
@@ -719,10 +750,11 @@ export const jsonToNbtShape = {
 };
 export const jsonToNbtSchema = z.object(jsonToNbtShape);
 export const indexArtifactShape = {
-    artifactId: nonEmptyString,
+    artifactId: optionalNonEmptyString,
+    target: sourceLookupTargetSchema.optional().describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     force: z.boolean().default(false)
 };
-export const indexArtifactSchema = z.object(indexArtifactShape);
+export const indexArtifactSchema = z.object(indexArtifactShape).superRefine(requireExactlyOneArtifactRef);
 export const validateMixinShape = {
     input: z.discriminatedUnion("mode", [
         z.object({

package/dist/types.d.ts

@@ -60,6 +60,8 @@ export interface DependencyResolutionProvenance {
     candidatesSeen?: string[];
     attempts?: string[];
     cacheHit: boolean;
+    /** Set when a submodule version was adopted from the cached umbrella POM. */
+    submoduleVersionSource?: "umbrella-pom";
 }
 export interface ArtifactProvenance {
     target: SourceTargetInput;
@@ -76,6 +78,27 @@ export interface ArtifactProvenance {
     workspaceResolution?: WorkspaceResolutionProvenance;
     dependencyResolution?: DependencyResolutionProvenance;
     warnings?: string[];
+    /**
+     * In-archive paths of bundled Jar-in-Jar nested jars, recorded once at
+     * ingest for shell jars (near-zero own classes). Class-family lookups
+     * redirect into these instead of dead-ending in decompilation.
+     */
+    nestedJars?: string[];
+    /**
+     * Set on responses that were served by redirecting a class lookup into a
+     * nested jar of a shell artifact.
+     */
+    nestedJar?: {
+        entryName: string;
+        shellArtifactId: string;
+    };
+    /**
+     * Additional sources jars indexed into this artifact alongside
+     * resolvedFrom.sourceJarPath — the other half of a Loom split-source pair
+     * (minecraft-common / minecraft-clientOnly), so client-only classes are not
+     * lost to single-jar selection.
+     */
+    companionSourceJars?: string[];
 }
 export interface RuntimeValidationProvenance<TMapping extends RuntimeValidationNamespace = RuntimeValidationNamespace> {
     version: string;

package/dist/workspace-mapping-service.d.ts

@@ -31,6 +31,7 @@ export type DependencyVersionResolution = {
     source: string;
     candidatesSeen: string[];
     attempts: string[];
+    submoduleVersionSource?: "umbrella-pom";
 } | {
     resolved: false;
     candidatesSeen: string[];

package/dist/workspace-mapping-service.js

@@ -59,21 +59,39 @@ function buildDependencyPropertyKeys(group, name) {
     const camelName = camelCaseDependencyName(name);
     const groupSegment = lastGroupSegment(group);
     const camelGroupName = camelCaseDependencyName(`${groupSegment}_${name}`);
+    const snakeName = name.replace(/-/g, "_");
+    const snakeGroupSegment = groupSegment.replace(/-/g, "_");
+    // Hyphenated artifact names (e.g. fabric-api) are declared in
+    // gradle.properties as snake_case keys (fabric_api_version), so the base
+    // enumeration must probe the snake_case transforms too — including for the
+    // umbrella artifact itself, which never reaches the umbrella fallback below.
     const keys = [
         `${name}_version`,
+        `${snakeName}_version`,
         `${camelName}Version`,
         `${groupSegment}_${name}_version`,
+        `${snakeGroupSegment}_${snakeName}_version`,
         `${camelGroupName}Version`
     ];
-    // Umbrella fallback: submodules of an umbrella package (e.g. Fabric API's
-    // net.fabricmc.fabric-api:fabric-screen-handler-api-v1) rarely declare their own
-    // version — the parent declares a single umbrella property (fabric_api_version /
-    // fabricApiVersion) that all submodules inherit. When the artifact name differs from
-    // the group's last segment, append the umbrella's keys as LOWER-priority candidates so
-    // submodule version detection no longer fails with ERR_DEPENDENCY_VERSION_UNRESOLVED.
-    if (groupSegment !== name) {
-        keys.push(`${groupSegment.replace(/-/g, "_")}_version`, `${camelCaseDependencyName(groupSegment)}Version`);
+    return dedupeKeys(keys);
+}
+// Umbrella properties (fabric_api_version / fabricApiVersion) declare the
+// UMBRELLA package's version, not a submodule's. They are never adopted as a
+// submodule version directly — the umbrella version differs from every
+// submodule version (e.g. fabric-api 0.153.0+26.2 vs
+// fabric-screen-handler-api-v1 2.0.5+...). They only locate the cached
+// umbrella POM, which names the real per-submodule versions.
+function buildUmbrellaPropertyKeys(group, name) {
+    const groupSegment = lastGroupSegment(group);
+    if (groupSegment === name) {
+        return [];
     }
+    return dedupeKeys([
+        `${groupSegment.replace(/-/g, "_")}_version`,
+        `${camelCaseDependencyName(groupSegment)}Version`
+    ]);
+}
+function dedupeKeys(keys) {
     const seen = new Set();
     const deduped = [];
     for (const key of keys) {
@@ -84,6 +102,89 @@ function buildDependencyPropertyKeys(group, name) {
     }
     return deduped;
 }
+function readPomDependencyVersion(pomContent, group, name) {
+    const blocks = pomContent.match(/<dependency>[\s\S]*?<\/dependency>/g) ?? [];
+    for (const block of blocks) {
+        const groupId = block.match(/<groupId>\s*([^<]+?)\s*<\/groupId>/)?.[1];
+        const artifactId = block.match(/<artifactId>\s*([^<]+?)\s*<\/artifactId>/)?.[1];
+        if (groupId !== group || artifactId !== name) {
+            continue;
+        }
+        // A matching block without a literal <version> (e.g. a managed entry
+        // relying on inheritance) must not end the scan — a later block for the
+        // same artifact may carry the concrete version.
+        const version = block.match(/<version>\s*([^<]+?)\s*<\/version>/)?.[1];
+        if (version) {
+            return version;
+        }
+    }
+    return undefined;
+}
+// When modules-2 caches several versions of a submodule, the cached umbrella
+// POM (modules-2/files-2.1/<group>/<umbrella>/<version>/<hash>/<umbrella>-<version>.pom)
+// is the only local evidence of which one the declared umbrella version maps
+// to. Adoption is fail-closed: no umbrella property, no readable POM, no
+// matching <dependency> entry, or a POM version absent from the cached
+// candidates all leave the resolution unresolved instead of guessing.
+async function adoptSubmoduleVersionFromUmbrellaPom(args) {
+    const { group, name, propsContent, candidates, candidatesSeen, attempts } = args;
+    const groupSegment = lastGroupSegment(group);
+    const umbrellaKeys = buildUmbrellaPropertyKeys(group, name);
+    if (umbrellaKeys.length === 0) {
+        return undefined;
+    }
+    let umbrellaVersion;
+    if (propsContent !== undefined) {
+        for (const key of umbrellaKeys) {
+            attempts.push(`umbrella-property:${key}`);
+            const value = readPropertyValue(propsContent, key);
+            if (value && isSafeMavenVersionToken(value)) {
+                umbrellaVersion = value;
+                break;
+            }
+        }
+    }
+    if (!umbrellaVersion) {
+        return undefined;
+    }
+    const umbrellaDir = resolve(resolveGradleUserHome(), "caches", "modules-2", "files-2.1", group, groupSegment, umbrellaVersion);
+    attempts.push(`umbrella-pom:${umbrellaDir}`);
+    let hashDirs = [];
+    try {
+        hashDirs = await readdir(umbrellaDir);
+    }
+    catch {
+        return undefined;
+    }
+    const pomFileName = `${groupSegment}-${umbrellaVersion}.pom`;
+    for (const hashDir of hashDirs) {
+        const pomPath = resolve(umbrellaDir, hashDir, pomFileName);
+        let pomContent;
+        try {
+            pomContent = await readFile(pomPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const version = readPomDependencyVersion(pomContent, group, name);
+        if (!version || !isSafeMavenVersionToken(version)) {
+            continue;
+        }
+        if (!candidates.includes(version)) {
+            attempts.push(`umbrella-pom:${pomPath}:names-uncached-version:${version}`);
+            return undefined;
+        }
+        return {
+            resolved: true,
+            version,
+            source: `umbrella-pom:${pomPath}`,
+            candidatesSeen,
+            attempts,
+            submoduleVersionSource: "umbrella-pom"
+        };
+    }
+    return undefined;
+}
 function readPropertyValue(content, key) {
     const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const pattern = new RegExp(`^\\s*${escaped}\\s*=\\s*(.+?)\\s*$`, "m");
@@ -326,6 +427,17 @@ export class WorkspaceMappingService {
             return { resolved: false, candidatesSeen, attempts };
         }
         if (sorted.length > 1) {
+            const pomAdoption = await adoptSubmoduleVersionFromUmbrellaPom({
+                group,
+                name,
+                propsContent,
+                candidates: sorted,
+                candidatesSeen,
+                attempts
+            });
+            if (pomAdoption) {
+                return pomAdoption;
+            }
             return { resolved: false, candidatesSeen, attempts };
         }
         const chosen = sorted[0];

package/docs/README-ja.md

@@ -405,12 +405,16 @@ pnpm test
 
 必要に応じて実行:
 
+- `pnpm test:file <path...>`: 通常テストをファイル指定で絞り込む場合
+- `pnpm test:grep <name-pattern>`: 通常テストを再帰的に集め、テスト名で絞り込む場合
 - `pnpm test:manual:stdio-smoke`: MCP トランスポート、登録、手動ワークフローの変更時
 - `pnpm test:manual:package-smoke`: パッケージインストールや配布形態の検証時
 - `pnpm test:perf`: 検索、インデックス、性能に影響する変更時
 - `pnpm test:coverage` または `pnpm test:coverage:lcov`: カバレッジ確認時（`lines=80`, `branches=70`, `functions=80`）
 - `pnpm validate`: ローカルの完全検証スイートを実行する場合
 
+通常の `.test.ts` ファイルは `tests/` 配下のドメイン別ディレクトリ（例: `source-service/`, `entry-tools/`, `mapping/`, `mixin/`, `integration/mcp-tools/`, `contracts/`, `utils/`）に置きます。ヘルパー専用モジュールは `tests/helpers` に残し、手動 smoke、性能、リソース、smoke 専用ファイルは既存の専用ディレクトリに残します。
+
 ## ライセンス
 
 [MIT](../LICENSE)

package/docs/tool-reference.md

@@ -32,11 +32,13 @@ Start here when you are not sure which tool to reach for. In every row, the left
 - Start with the top-level workflow tools when possible. `inspect-minecraft`, `analyze-symbol`, `compare-minecraft`, `analyze-mod`, `validate-project`, and `manage-cache` cover the common workflows and return summary-first results with follow-up hints.
 - `resolve-artifact` uses `target: { kind, value }`. `kind` is one of `"version"`, `"jar"`, `"coordinate"`, `"workspace"`, or `"dependency"` (see "Workspace and dependency target shapes" below).
 - `get-class-source` and `get-class-members` use `target: { kind, value }` — the same `kind`-based shape as `resolve-artifact` (`"version"`, `"jar"`, `"coordinate"`, `"workspace"`, `"dependency"`), plus `target: { kind: "artifact", artifactId }` to reuse an already-resolved artifact.
-- `find-class`, `search-class-source`, `list-artifact-files`, and `find-mapping` keep their existing input shapes (an `artifactId` or a `version`); they do not currently accept `target.kind="workspace"` or `target.kind="dependency"`.
+- `find-class`, `search-class-source`, `get-artifact-file`, `list-artifact-files`, and `index-artifact` accept either an `artifactId` or the shared object `target` shape. `find-class` also accepts top-level `projectPath`, which supplies the workspace context required by `target.kind="workspace"` and dependency targets using `versionFromProject`. For another flat tool whose target needs workspace context, resolve the artifact first and pass its `artifactId`.
 - `validate-mixin` and `validate-project task="mixin"` use `input.mode="inline" | "path" | "paths" | "config" | "project"`.
 - Positive integer tool arguments accept numeric strings such as `"10"` for documented top-level parameters.
 - When a parameter has a fixed safe default, `tools/list` exposes it through the JSON Schema `default` field so clients can rely on schema metadata instead of prose notes.
 - Retryable `suggestedCall` payloads omit parameters when the supplied value already matches the tool default, keeping recovery calls smaller without changing behavior.
+- `ERR_CLASS_NOT_FOUND` errors from the class tools carry a top-level `didYouMean` array (parallel to `suggestedCall`) with ranked near-miss candidates from the artifact's symbol index: each entry is `{ className, matchReason }` where `matchReason` is `"exact-simple-name"` (same simple name in another package — the moved-class case, ranked first), `"case-insensitive"`, or `"edit-distance:N"`. Candidates are hints, never assertions that the class exists at the suggested location; the array is empty when the index has nothing usable. All same-simple-name FQNs are enumerated rather than collapsed.
+- `find-class` searches the nested `.class` inventories of Jar-in-Jar shell artifacts such as the Fabric API umbrella JAR. It accepts simple or qualified names, returns dotted names for inner classes, deduplicates a class bundled more than once, and honors `limit`. The returned source path is inferred from the outer class. For top-level matches, `get-class-source` and `get-class-members` resolve the actual containing nested JAR before reading content; dotted inner-class matches are also readable through `get-class-source`.
 - Source-oriented tools expose `artifactContents` so callers can tell whether the backing artifact is a `source-jar` or a `decompiled-binary`. `get-class-source`, `get-class-members`, `search-class-source`, and `get-artifact-file` also expose `returnedNamespace`.
 - Cache-backed source, mapping, validation, batch, and workflow tools accept `gradleUserHome?: string` when they need Loom cache data. Use it for builds that used an isolated `GRADLE_USER_HOME`; the server searches `<gradleUserHome>/loom-cache` and `<gradleUserHome>/caches/fabric-loom` before the MCP process default. The value selects a Gradle User Home, not arbitrary Loom cache roots.
 - `get-class-members` returns `decompiledFallback` (with `constructors`, `fields`, `methods`, each entry is `{ name, line, kind }`) and `decompiledMemberCounts` whenever bytecode enumeration yields zero but the decompiled source for the class is already indexed. The bytecode-derived `members` / `counts` are preserved as-is; the fallback is additive and carries no descriptor or access modifier. `qualityFlags` gains `"members-from-decompiled-source"` in that case. Use `get-class-source` for descriptors and full context.
@@ -58,6 +60,75 @@ Start here when you are not sure which tool to reach for. In every row, the left
 - Heavy analysis tools are serialized in-process to protect stdio stability. Queue overflow returns `ERR_LIMIT_EXCEEDED`.
 - All tools and JSON resources use the standard `{ result?, error?, meta }` envelope. `class-source` and `artifact-file` resources return raw text on success and structured JSON on failure.
 
+## inspect-minecraft workspace focus
+
+Use `subject.kind="workspace"` when `inspect-minecraft` should resolve Minecraft artifact context from a project. Its `focus` is a structured object, not a string:
+
+| Focus shape | `task="auto"` dispatch | Explicit tasks |
+| --- | --- | --- |
+| `focus: { kind: "class", className: "..." }` | `class-overview` | `class-overview`, `class-source`, `class-members` |
+| `focus: { kind: "search", query: "..." }` | `search` | `search` |
+| `focus: { kind: "file", filePath: "..." }` | `file` | `file` |
+
+`task="auto"` is structured dispatch based on `subject.kind` and `focus.kind`; it is not a natural-language planner and does not interpret prose. A string `focus` remains invalid and returns `ERR_INVALID_INPUT` with three schema-validated class/search/file `exampleCalls`; the server never guesses which object shape the text meant.
+
+Class source from a workspace:
+
+```json
+{
+  "tool": "inspect-minecraft",
+  "arguments": {
+    "task": "class-source",
+    "subject": {
+      "kind": "workspace",
+      "projectPath": "/path/to/workspace",
+      "focus": {
+        "kind": "class",
+        "className": "net.minecraft.world.item.Item"
+      }
+    }
+  }
+}
+```
+
+Source search from a workspace:
+
+```json
+{
+  "tool": "inspect-minecraft",
+  "arguments": {
+    "task": "auto",
+    "subject": {
+      "kind": "workspace",
+      "projectPath": "/path/to/workspace",
+      "focus": {
+        "kind": "search",
+        "query": "CreativeModeTab"
+      }
+    }
+  }
+}
+```
+
+Artifact-relative file read from a workspace:
+
+```json
+{
+  "tool": "inspect-minecraft",
+  "arguments": {
+    "task": "auto",
+    "subject": {
+      "kind": "workspace",
+      "projectPath": "/path/to/workspace",
+      "focus": {
+        "kind": "file",
+        "filePath": "net/minecraft/world/item/Item.java"
+      }
+    }
+  }
+}
+```
+
 ## Workspace and dependency target shapes
 
 `resolve-artifact`, `get-class-source`, and `get-class-members` accept two synthesizing `target.kind` values in addition to the canonical `"version"` / `"jar"` / `"coordinate"` shapes. The synthesizer rewrites the call into one of those canonical shapes before downstream resolution, so behaviour from the resolver onward is unchanged.
@@ -92,18 +163,27 @@ same dependency, call `resolve-artifact` once and reuse the returned
 
 Workspace detection is memoised in a process-resident `WorkspaceContextCache` (16-entry LRU, 5-minute TTL). The cache is observable through `manage-cache` with `cacheKinds: ["workspace"]`, and individual entries can be invalidated via `selector.projectPath`.
 
-`target.kind="dependency"` resolution probes four de-duplicated `gradle.properties` keys in order — `name_version`, `camelCaseVersion`, `lastSegment(group)_name_version`, and `camelCase(lastSegment(group)_name)Version` — before falling back to the modules-2 cache layout `~/.gradle/caches/modules-2/files-2.1/<group>/<name>/`. Version tokens that contain path separators, `..`, NUL, control characters, or any character outside `[A-Za-z0-9._+-]` are rejected; in `gradle.properties` the rejection is recorded under `attempts[]` as `gradle.properties:<key>:rejected-unsafe-version` and the next key is tried. Snapshot and dev directories are excluded by default. The modules-2 fallback only resolves when exactly one valid entry remains; multiple entries raise `ERR_DEPENDENCY_VERSION_UNRESOLVED` so a global cache cannot supply a version the workspace did not declare.
+`target.kind="dependency"` resolution probes up to six de-duplicated `gradle.properties` keys in order — `name_version`, `snake_case(name)_version`, `camelCaseVersion`, `lastSegment(group)_name_version`, `snake_case(lastSegment(group)_name)_version`, and `camelCase(lastSegment(group)_name)Version`. Hyphens become underscores in the snake_case forms (`fabric-api` probes `fabric_api_version`); for hyphen-less names the snake_case forms deduplicate into the raw keys, leaving four. The probe falls back to the modules-2 cache layout `~/.gradle/caches/modules-2/files-2.1/<group>/<name>/`. Version tokens that contain path separators, `..`, NUL, control characters, or any character outside `[A-Za-z0-9._+-]` are rejected; in `gradle.properties` the rejection is recorded under `attempts[]` as `gradle.properties:<key>:rejected-unsafe-version` and the next key is tried. Snapshot and dev directories are excluded by default. The modules-2 fallback resolves directly when exactly one valid entry remains. When several entries remain and the dependency is a submodule of an umbrella package (artifact name differs from the group's last segment, e.g. `net.fabricmc.fabric-api:fabric-screen-handler-api-v1`), the declared umbrella version property (`fabric_api_version` / `fabricApiVersion`) locates the cached umbrella POM and the submodule adopts the version that POM names — the resolving response records `provenance.submoduleVersionSource: "umbrella-pom"` with the POM path in `provenance.source` (workspace-context-cache hits within the TTL return the cached version with `provenance.source: "workspace-context-cache"` instead). Umbrella properties are never adopted verbatim as a submodule's version. Every remaining ambiguity raises `ERR_DEPENDENCY_VERSION_UNRESOLVED` with `candidatesSeen` so a global cache cannot supply a version the workspace did not declare.
 
 ## Common Pitfalls
 
+- Flat-`artifactId` tools (`find-class`, `get-artifact-file`, `list-artifact-files`, `search-class-source`, `index-artifact`) also accept the shared `target` shape (`{ kind: "version" | "jar" | "coordinate" | "artifact" | "dependency", ... }`) instead of `artifactId` — exactly one of the two must be supplied. The target is resolved (and ingested if needed) before the lookup, so a fresh `resolve-artifact` round-trip is unnecessary. `{ kind: "artifact", artifactId }` passes through directly. Targets that need workspace context beyond their own fields — `kind: "workspace"`, or `kind: "dependency"` without an explicit `version` — cannot supply a `projectPath` through these tools; resolve them with `resolve-artifact` first and pass the `artifactId`.
+- `analyze-symbol` infers an omitted `version` from `projectPath` (gradle.properties `minecraft_version`/`mc_version`); the response then carries `versionInference { version, source }` and a warning. An explicit `version` always wins. `inspect-minecraft` direct subjects without `subject.artifact` auto-resolve only when exactly one workspace is known to the process (provenance warning attached); several candidates are refused with `workspaceCandidates`.
+
+- Loom split-source workspaces publish a version as a `minecraft-common` / `minecraft-clientOnly` sources-jar pair with no merged jar. Version-target resolution indexes both halves (the companion jar appears in `provenance.companionSourceJars`), so client-only classes are queryable under the merged scope. If a class still cannot be found, the error's `exampleCalls` carries a `scope: "vanilla"` retry — the decompiled client jar also contains client-only classes.
 - `mapping="mojang"` requires source-backed artifacts on legacy obfuscated versions. For unobfuscated releases such as `26.1+`, the runtime/decompile path is accepted directly for version and versioned-coordinate targets. When source jars are not available but the version's Mojang tiny mappings, the tiny-remapper jar, and `MappingService.checkMappingHealth` are all healthy, `resolve-artifact` with `target.kind="version"` will transparently tiny-remap the binary jar (`obfuscated -> mojang`) and decompile the result, and the response carries `qualityFlags` `"binary-remapped"` and `"decompiled"` plus `provenance.transformChain` `"binary-remap:obf->mojang"` and `"decompile:vineflower"`. Coordinate and jar targets are not eligible for this fallback and still surface `ERR_MAPPING_NOT_APPLIED`. Source-backed and obfuscated artifacts keep their existing `artifactId` hashes — only the new mojang-remapped variant lives in a separate cache slot.
 - Mojang binary-remap cache entries live under `<cacheDir>/remapped`. `manage-cache` lists valid files plus corrupt directories and leftover temp entries under `cacheKinds: ["binary-remap"]`; corrupt entries carry `status: "corrupt"` and `meta.artifactId`, so callers can preview or apply cleanup with `selector.artifactId`.
-- `list-artifact-files` indexes Java source paths only. Probing `assets/` or `data/` prefixes will not return non-Java resources.
+- Jar-in-Jar shell jars (near-zero own classes with bundled `META-INF/jars/*.jar`, e.g. the Fabric API umbrella jar) no longer dead-end in `ERR_DECOMPILER_FAILED`. `resolve-artifact` detects the shell, skips decompilation, and returns the artifact with `qualityFlags: ["shell-jar"]` and the bundled inventory in `provenance.nestedJars`; `analyze-mod-jar` reports the same inventory as `nestedJars`. `get-class-source` / `get-class-members` lookups against a shell automatically redirect to the single nested jar containing the class and mark the response with `provenance.nestedJar` (`entryName` + `shellArtifactId`); a class found in several nested jars raises `ERR_NESTED_JAR_AMBIGUOUS` with `nestedJarCandidates` and per-candidate `suggestedCall` examples instead of picking one. Class-not-found errors on a shell carry the `nestedJars` inventory. The redirect is deliberately single-level: a nested jar that is itself a shell surfaces its own inventory when resolved directly as its own artifact. Extracted nested jars are content-addressed under `<cacheDir>/nested-jars`, observable through `manage-cache` with `cacheKinds: ["nested-jar"]`.
+- `list-artifact-files` indexes Java source paths only — `assets/` and `data/` prefixes list nothing. Text files under those prefixes ARE retrievable by exact path with `get-artifact-file`: when the index has no row, the tool reads the entry directly from the backing jar (`deliveryMode: "jar-read-through"` marks such responses). This works for any artifact with a backing jar — vanilla client jars and mod jars alike; for Jar-in-Jar shells it reads the shell's own entries only (resolve a nested jar as its own artifact to reach its resources). Read-through delivery is text-only with a 512 KiB per-file cap (`truncated: true` beyond it); binary entries (e.g. `.png`, `.ogg`) answer with size metadata plus `contentOmittedReason` instead of content. Traversal-shaped paths (`..`, absolute) are rejected with `ERR_INVALID_INPUT`, and a miss returns `ERR_FILE_NOT_FOUND` with `nearbyPaths` naming same-named entries elsewhere in the jar (directory layouts move between versions, e.g. `assets/minecraft/models/item/*` → `assets/minecraft/items/*`).
 - `search-class-source` defaults to `queryMode="auto"`. Use `queryMode="literal"` for explicit substring scans. `match="regex"` enforces `query.length <= 200` and caps results at `100`.
 - `search-class-source` returns compact hits only. Use `get-artifact-file` or `get-class-source` to inspect returned files.
 - `find-class` and `get-class-source` on `mapping="obfuscated"` expect Mojang obfuscated names. Deobfuscated queries warn and usually need `mapping="mojang"` or a `find-mapping` step first.
+- `get-class-members` exposes `annotationDefault` on annotation-type members (the `default` value of an `@interface` member) whenever the classfile carries it, and accepts `includeAnnotations: true` to additionally list runtime-visible member annotations such as `@java.lang.Deprecated` per member. The leaner `names`/`signatures` projections drop annotation fields. `analyze-mod` `task="members"` includes both without a flag.
+- On unobfuscated versions, `find-mapping`, `resolve-method-mapping-exact`, and `check-symbol-exists` report two structured `mappingContext` flags instead of per-response warning sentences (`get-class-api-matrix` reports a top-level `unobfuscatedRuntime: true` — its non-mojang columns are empty by design there): `unobfuscatedRuntime: true` replaces "Version X is unobfuscated; mapping graph is empty because the runtime already uses deobfuscated names.", and `runtimeValidated: true` replaces "Version X is unobfuscated; validated symbol existence against runtime bytecode." Do not pattern-match the old sentences.
 - `check-symbol-exists` defaults to strict FQCN class lookup. Use `nameMode="auto"` for short class names.
+- On unobfuscated versions, every `not_found` and `mapping_unavailable` verdict from the mapping graph — classes and fields included, not just methods — is re-validated against runtime bytecode before being returned, so a graph that lacks a record for a real symbol (e.g. `EntityType.ITEM`) no longer produces false negatives. Genuinely-missing symbols still return `not_found` after the runtime check. Bytecode-derived response contexts report `mappingNamespace: "mojang"` on unobfuscated versions instead of a hardcoded `"obfuscated"`.
 - `check-symbol-exists` can use `signatureMode="name-only"` for overload discovery, but exact `descriptor` matching is still the most reliable path.
+- Inherited-member expansion (`get-class-members` with `includeInherited: true`, and the `check-symbol-exists` runtime-bytecode fallback that reuses it) suppresses super-class and interface resolution warnings for platform packages that are never inside a Minecraft jar (`java.*`, `javax.*`, `jdk.*`, `sun.*`, `com.mojang.serialization.*`). A warning about any other unresolved super type — including `com.mojang.blaze3d.*` — is a real signal.
 - `analyze-symbol task="api-overview"` inherits `sourceMapping` as the default `classNameMapping`; it falls back to `obfuscated` only when neither value is provided.
 - `find-mapping` accepts short class ids such as `dhl` only when `sourceMapping="obfuscated"`. Other class lookup paths still validate class names as fully-qualified.
 - `find-mapping` still rejects the public namespace name `official`, but upstream Tiny files that use `official` internally are now bridged to the supported `obfuscated` graph automatically.
@@ -247,7 +327,8 @@ Translate symbols across mapping namespaces with one shared Minecraft version. P
 
 `ProblemDetails.code` may carry the codes below in addition to the existing tool-specific values.
 
-- `ERR_WORKER_RESTART` — Synthetic envelope produced by the supervisor when the worker process exits while handling `tools/call`. The response is a `CallToolResult` with `isError: true` and `structuredContent.error.code === "ERR_WORKER_RESTART"`. `structuredContent.meta.synthetic === true` and `meta.restart` records `tool` / `durationMs` / `lastStage` / `lastStageElapsedMs` / `lastStageMeta` / `exit` / `retryRecommendation` so the caller can decide whether to retry, narrow the input, clear caches, or report a bug. Non-`tools/call` requests (`initialize`, `tools/list`, etc.) still receive the legacy raw JSON-RPC `-32603` envelope.
+- `ERR_WORKER_RESTART` — Synthetic envelope produced when the worker exits during `tools/call`, replacement startup or initialization replay fails, or live process-tree cleanup leaves the supervisor unable to start a worker. The response is a `CallToolResult` with `isError: true` and `structuredContent.error.code === "ERR_WORKER_RESTART"`. `structuredContent.meta.synthetic === true` and `meta.restart` records `tool` / `durationMs` / `lastStage` / `lastStageElapsedMs` / `lastStageMeta` / `exit` / `retryRecommendation` so the caller can decide whether to retry, narrow the input, clear caches, or report a bug. Non-`tools/call` requests receive the legacy raw JSON-RPC `-32603` envelope.
+- `ERR_TOOL_TIMEOUT` — Synthetic `CallToolResult` produced only for `validate-project` when its supervisor-owned end-to-end deadline expires. The default is 120,000 ms and includes supervisor queue time. `meta.timeout.phase` is `"queue"` when the call expired before dispatch and `"running"` after dispatch. A queue timeout does not restart the worker; a running timeout isolates the worker process tree, initiates replacement, and sets `meta.timeout.workerRestartInitiated: true`. Cancellation suppresses the timeout result while retaining the deadline for worker cleanup.
 - `ERR_MIXIN_PARSE_FAILED` — Reserved code for `validate-mixin` parse-stage failures in single / inline mode. Today the runtime parser is permissive (no hard parse failure path), but emitting this code keeps the contract stable for future strict-parse modes.
 - `ERR_STAGE_BUDGET_PRE_PARSE` — Raised when a pre-parse stage (`resolve`, `mapping-health`, or `parse` itself) exhausts its independent soft-deadline before validation can proceed. The error carries `failedStage: <stage name>`, `meta.stageBudgetExhausted: true`, and the `budgetMs` / `elapsedMs` for the offending stage. Recovery: shrink `mixinConfigPath` (e.g. validate one config file at a time) or set `MIXIN_STAGE_BUDGETS_OFF=1` to disable budgets for diagnostic reruns.
 - `ERR_WORKSPACE_VERSION_UNRESOLVED` — Raised by `resolve-artifact`, `get-class-source`, and `get-class-members` when `target.kind="workspace"` cannot detect a Minecraft version from `gradle.properties`. Both `strict: true` and `strict: false` raise; `details.strict` records which value was supplied. The error carries `details.projectPath` and a `suggestedCall` with `target: { kind: "version", value: "<your-mc-version>" }` so the caller can fall back to an explicit version target.
@@ -264,6 +345,9 @@ The optional `error.exampleCalls?: Array<{ tool: string; params: Record<string,
 ## Meta fields
 
 - `meta.restart` (synthetic worker-restart responses only) — emitted exclusively when the supervisor returns an `ERR_WORKER_RESTART` envelope. Shape: `{ tool, durationMs, lastStage, lastStageElapsedMs, lastStageMeta, exit: { code, signal }, retryRecommendation }`. `retryRecommendation` is one of `"narrow-query" | "clear-cache" | "report-bug" | "same-request"`, decided by the supervisor from `lastStage`, `exit.signal`, and the recent restart cadence (3 restarts within 60 s of the same tool → `"report-bug"`).
+- `meta.timeout` (`ERR_TOOL_TIMEOUT` only) — exact shape: `{ tool: "validate-project", phase: "queue" | "running", durationMs, deadlineMs, lastStage, lastStageElapsedMs, lastStageMeta, redactedToolArgs, redactedToolArgsModified, retryRecommendation, workerRestartInitiated }`. Stage and argument diagnostics use the supervisor's bounded redaction rules. `workerRestartInitiated` reports initiation only; it does not claim that replacement startup or initialization replay completed.
+- `meta.queue` (supervisor queue overflow only) — `{ reason: "supervisor-request-queue", maxQueued: 2, queuedCount: 2 }`. The FIFO retains at most two total worker-bound requests; a queued `validate-project` barrier consumes one slot, while a running barrier is outside the FIFO. Overflowing `tools/call` receives a synthetic `ERR_LIMIT_EXCEEDED` result. An overflowing non-tool request receives raw JSON-RPC `-32000` with message `"MCP supervisor request queue is full."`; notifications do not consume slots.
+- Replacement startup/replay uses a 10–30 second internal watchdog and bounded retry backoff. Successful replay releases queued work. Spawn, pre-ready, replay, or watchdog failure terminalizes queued requests with the existing worker-restart response shapes. At the two-slot live-generation cap, new worker-bound requests, including `initialize`, fail immediately instead of entering the FIFO; notifications that cannot be delivered are emitted as structured supervisor warnings and dropped. Tree-cleanup helper attempts are bounded to five seconds so recovery and shutdown cannot wait forever on `taskkill` or an equivalent platform operation. On POSIX, `ESRCH` while signaling the saved process group means the group is already gone and is treated as completed cleanup.
 - `meta.stageBudgetExhausted` (`ERR_STAGE_BUDGET_PRE_PARSE` errors only) — set to `true` to flag that the failure is budget-driven rather than a genuine resolve / mapping-health / parse error. Pair with `failedStage` and `error.detail` (`"Stage <name> exhausted budget before parse completed."`) for diagnostics. The companion fields `meta.budgetMs` (the stage budget that was exceeded) and `meta.elapsedMs` (the actual stage elapsed time) are emitted alongside it on the same envelope so callers can decide between retry, input-shrink (`mixinConfigPath`), or `MIXIN_STAGE_BUDGETS_OFF=1` rollback without parsing message text.
 - `validate-mixin` batch-mode entries (`results[i]`, when invoked with `input.mode = "paths" | "config" | "project"`) preserve typed error metadata when an entry fails: optional `errorCode` (e.g. `"ERR_STAGE_BUDGET_PRE_PARSE"`) and `errorDetails` (the `failedStage` / `stageBudgetExhausted` / `budgetMs` / `elapsedMs` shape from the underlying AppError) sit alongside the legacy `error` string. The shape is additive — callers that only read `error` continue to see the same human-readable message.
 
@@ -274,7 +358,7 @@ These environment variables are read once at worker startup and provide rollback
 | Env | Effect | Acceptance test |
 |---|---|---|
 | `MIXIN_STAGE_BUDGETS_OFF=1` | Sets every `validate-mixin` stage budget (including the per-target soft cap) to `Number.POSITIVE_INFINITY`. Restores the pre-budget run-to-completion behaviour. | `tests/source-service-validate-mixin-budget.test.ts` (`MIXIN_STAGE_BUDGETS_OFF=1 disables all budgets`) |
-| `SUPERVISOR_STRUCTURED_RESTART_OFF=1` | Suppresses synthetic `CallToolResult` envelopes; `tools/call` requests killed by a worker exit fall back to the legacy raw JSON-RPC `-32603` error. | `tests/stdio-supervisor.test.ts` (`buildWorkerRestartReply returns raw -32603 when structuredRestartDisabled`) |
+| `SUPERVISOR_STRUCTURED_RESTART_OFF=1` | Suppresses synthetic `CallToolResult` envelopes; `tools/call` requests killed by a worker exit fall back to the legacy raw JSON-RPC `-32603` error. | `tests/stdio/stdio-supervisor.test.ts` (`buildWorkerRestartReply returns raw -32603 when structuredRestartDisabled`) |
 | `MIXIN_STAGE_PROGRESS_OFF=1` | Replaces the worker stage emitter with a no-op so `$/stageUpdate` notifications are never sent. Use as a fallback when the active SDK build does not surface `extra.requestId`. | `tests/stage-emitter.test.ts` (`makeStageEmitter is a no-op when disabled option is true`) |
 | `WORKSPACE_TARGET_OFF=1` | Rejects `target.kind="workspace"` on `resolve-artifact`, `get-class-source`, and `get-class-members` with `ERR_INVALID_INPUT`. Restores the pre-workspace-target behaviour where callers must always supply `target.kind="version"`/`"jar"`/`"coordinate"`. | `tests/source-service-workspace-target.test.ts` (`synthesizeWorkspaceTarget rejects target.kind=workspace when WORKSPACE_TARGET_OFF is set`) |
 | `DEPENDENCY_TARGET_OFF=1` | Rejects `target.kind="dependency"` on the same three tools with `ERR_INVALID_INPUT`. | `tests/source-service-dependency-target.test.ts` (`synthesizeDependencyTarget rejects target.kind=dependency when DEPENDENCY_TARGET_OFF is set`) |
@@ -294,6 +378,7 @@ These environment variables are read once at worker startup and provide rollback
 - `analyze-symbol` `subject.kind` accepts `"symbol"` to auto-detect the concrete kind from the selector (owner+descriptor ⇒ method, owner only ⇒ field, otherwise ⇒ class); the inferred kind is surfaced as a warning. For `task="api-overview"` the inferred kind is always class.
 - Start with `compare-minecraft` for version-pair, class diff, registry diff, and migration-summary flows before using `compare-versions`, `diff-class-signatures`, or `get-registry-data` directly.
 - Start with `analyze-mod` for metadata-first mod inspection and safe remap preview/apply flows before using `analyze-mod-jar`, `decompile-mod-jar`, `get-mod-class-source`, `search-mod-source`, or `remap-mod-jar` directly.
+- `analyze-mod` `task="members"` (subject `{ kind: "class", jarPath, className }`) reads a mod class's constructors/fields/methods (all access levels, including private and protected) straight from bytecode — no decompiler runs on this path, unlike `task="class-source"` which costs a full decompile. Responses mark `extractionMethod: "bytecode-only"`; a class missing from the jar returns `ERR_CLASS_NOT_FOUND`.
 - Start with `validate-project` for workspace summaries and direct Mixin, Access Widener, or Access Transformer validation before using `validate-mixin`, `validate-access-widener`, or `validate-access-transformer` directly.
 - `validate-project task="project-summary"` discovers mixins and access wideners by default. Add `discover: ["access-transformers"]` when you also want Access Transformer files included in the workspace summary.
 - `validate-project task="project-summary"` returns an additive `tasks` field alongside the existing aggregate `result.summary` / `result.project` blocks. The headline `result.summary.status` is unchanged; the new field reports per-probe status so a `status: "blocked"` headline still preserves which probes succeeded.
@@ -404,7 +489,7 @@ If callers accidentally append an inline signature suffix to `trace-symbol-lifec
 
 For decompile-only `ERR_MAPPING_NOT_APPLIED` failures, error details include `artifactOrigin`, `nextAction`, and `suggestedCall` so clients can recover without guessing.
 
-If `find-class` or `get-class-source` returns no hit on an `obfuscated` artifact for names like `net.minecraft.world.item.Item`, the tool warns that `obfuscated` means Mojang's runtime names and recommends retrying with `mapping="mojang"` or translating via `find-mapping`.
+If `find-class` or `get-class-source` returns no hit on an obfuscated Minecraft runtime artifact for names like `net.minecraft.world.item.Item`, the tool warns that `obfuscated` means Mojang's runtime names and recommends retrying with `mapping="mojang"` or translating via `find-mapping`. `find-class` does not issue that advice for dependency-resolved or Jar-in-Jar shell artifacts, whose native names are not evidence of Minecraft obfuscation.
 
 Method descriptor precision is best on Tiny-backed paths (`intermediary` and `yarn`). For `obfuscated <-> mojang`, Mojang `client_mappings` do not carry JVM descriptors, so descriptor queries may fall back to name matching and emit a warning.
 
@@ -477,6 +562,7 @@ Path-based overrides treat blank values and the literal strings `undefined` and
 | Variable | Default | Description |
 | --- | --- | --- |
 | `MCP_SUPERVISOR_DEBUG` | unset | Set to `1` to emit verbose stdio supervisor diagnostics |
+| `MCP_VALIDATE_PROJECT_TIMEOUT_MS` | `120000` | End-to-end `validate-project` deadline, including queue time. Accepts ASCII decimal digits only and must be from `10000` through `600000`; invalid values use the default. |
 
 Internal worker-mode environment variables are reserved for the transport implementation and are intentionally omitted from the public reference.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "6.1.1",
+  "version": "6.3.0",
   "description": "MCP server for AI-assisted Minecraft modding: inspect decompiled source, resolve Mojang/Yarn/Intermediary mappings, diff versions, analyze Fabric/Forge/NeoForge mod JARs, and validate Mixin, Access Widener, and Access Transformer files.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,11 +23,11 @@
     "prepack": "npm run build",
     "start": "node dist/cli.js",
     "check": "tsc --noEmit -p tsconfig.json",
-    "test": "node --test --import tsx tests/*.test.ts",
+    "test": "node scripts/run-tests.mjs",
     "test:file": "node --test --import tsx",
-    "test:grep": "node --test --import tsx --test-name-pattern",
-    "test:coverage": "node --test --import tsx --experimental-test-coverage --test-coverage-lines=80 --test-coverage-branches=70 --test-coverage-functions=80 tests/*.test.ts",
-    "test:coverage:lcov": "node --input-type=module -e \"import { mkdirSync } from 'node:fs'; mkdirSync('coverage', { recursive: true });\" && node --test --import tsx --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-coverage-lines=80 --test-coverage-branches=70 --test-coverage-functions=80 tests/*.test.ts",
+    "test:grep": "node scripts/run-tests.mjs --test-name-pattern",
+    "test:coverage": "node scripts/run-tests.mjs --coverage",
+    "test:coverage:lcov": "node scripts/run-tests.mjs --coverage --lcov coverage/lcov.info",
     "test:perf": "node --test --test-concurrency=1 --import tsx tests/perf/*.perf.ts",
     "test:perf:update-baseline": "UPDATE_PERF_BASELINE=1 node --test --test-concurrency=1 --import tsx tests/perf/*.perf.ts",
     "test:perf:strict": "STRICT_PERF=1 node --test --test-concurrency=1 --import tsx tests/perf/*.perf.ts",