@adhisang/minecraft-modding-mcp 6.2.0 → 6.3.0

package/CHANGELOG.md

@@ -5,7 +5,16 @@ 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
 

package/README.md

@@ -156,7 +156,7 @@ 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`.
@@ -278,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 |
@@ -287,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
@@ -415,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/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;

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;
@@ -1044,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";

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

@@ -158,6 +158,7 @@ export declare const inspectMinecraftShape: {
         scope?: "vanilla" | "merged" | "loader" | undefined;
         preferProjectVersion?: boolean | undefined;
         strictVersion?: boolean | undefined;
+        gradleUserHome?: string | undefined;
         artifact?: {
             artifactId: string;
             type: "resolved-id";
@@ -168,7 +169,6 @@ export declare const inspectMinecraftShape: {
             };
             type: "resolve-target";
         } | undefined;
-        gradleUserHome?: string | undefined;
     }, {
         kind: "class";
         className: string;
@@ -177,6 +177,7 @@ export declare const inspectMinecraftShape: {
         scope?: "vanilla" | "merged" | "loader" | undefined;
         preferProjectVersion?: boolean | undefined;
         strictVersion?: boolean | undefined;
+        gradleUserHome?: string | undefined;
         artifact?: {
             artifactId: string;
             type: "resolved-id";
@@ -187,7 +188,6 @@ export declare const inspectMinecraftShape: {
             };
             type: "resolve-target";
         } | undefined;
-        gradleUserHome?: string | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"file">;
         filePath: z.ZodString;
@@ -821,6 +821,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
         scope?: "vanilla" | "merged" | "loader" | undefined;
         preferProjectVersion?: boolean | undefined;
         strictVersion?: boolean | undefined;
+        gradleUserHome?: string | undefined;
         artifact?: {
             artifactId: string;
             type: "resolved-id";
@@ -831,7 +832,6 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
             };
             type: "resolve-target";
         } | undefined;
-        gradleUserHome?: string | undefined;
     }, {
         kind: "class";
         className: string;
@@ -840,6 +840,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
         scope?: "vanilla" | "merged" | "loader" | undefined;
         preferProjectVersion?: boolean | undefined;
         strictVersion?: boolean | undefined;
+        gradleUserHome?: string | undefined;
         artifact?: {
             artifactId: string;
             type: "resolved-id";
@@ -850,7 +851,6 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
             };
             type: "resolve-target";
         } | undefined;
-        gradleUserHome?: string | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"file">;
         filePath: z.ZodString;
@@ -1329,7 +1329,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
     includeSnapshots: boolean;
     limit?: number | undefined;
     cursor?: string | undefined;
-    task?: "search" | "class-source" | "artifact" | "auto" | "file" | "versions" | "class-members" | "class-overview" | "list-files" | undefined;
+    task?: "search" | "class-source" | "file" | "auto" | "class-overview" | "class-members" | "artifact" | "versions" | "list-files" | undefined;
     detail?: "summary" | "standard" | "full" | undefined;
     subject?: {
         kind: "version";
@@ -1366,6 +1366,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
         scope?: "vanilla" | "merged" | "loader" | undefined;
         preferProjectVersion?: boolean | undefined;
         strictVersion?: boolean | undefined;
+        gradleUserHome?: string | undefined;
         artifact?: {
             artifactId: string;
             type: "resolved-id";
@@ -1376,7 +1377,6 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
             };
             type: "resolve-target";
         } | undefined;
-        gradleUserHome?: string | undefined;
     } | {
         kind: "file";
         filePath: string;
@@ -1468,7 +1468,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
 }, {
     limit?: number | undefined;
     cursor?: string | undefined;
-    task?: "search" | "class-source" | "artifact" | "auto" | "file" | "versions" | "class-members" | "class-overview" | "list-files" | undefined;
+    task?: "search" | "class-source" | "file" | "auto" | "class-overview" | "class-members" | "artifact" | "versions" | "list-files" | undefined;
     detail?: "summary" | "standard" | "full" | undefined;
     subject?: {
         kind: "version";
@@ -1505,6 +1505,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
         scope?: "vanilla" | "merged" | "loader" | undefined;
         preferProjectVersion?: boolean | undefined;
         strictVersion?: boolean | undefined;
+        gradleUserHome?: string | undefined;
         artifact?: {
             artifactId: string;
             type: "resolved-id";
@@ -1515,7 +1516,6 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
             };
             type: "resolve-target";
         } | undefined;
-        gradleUserHome?: string | undefined;
     } | {
         kind: "file";
         filePath: string;
@@ -1609,7 +1609,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
     includeSnapshots: boolean;
     limit?: number | undefined;
     cursor?: string | undefined;
-    task?: "search" | "class-source" | "artifact" | "auto" | "file" | "versions" | "class-members" | "class-overview" | "list-files" | undefined;
+    task?: "search" | "class-source" | "file" | "auto" | "class-overview" | "class-members" | "artifact" | "versions" | "list-files" | undefined;
     detail?: "summary" | "standard" | "full" | undefined;
     subject?: {
         kind: "version";
@@ -1646,6 +1646,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
         scope?: "vanilla" | "merged" | "loader" | undefined;
         preferProjectVersion?: boolean | undefined;
         strictVersion?: boolean | undefined;
+        gradleUserHome?: string | undefined;
         artifact?: {
             artifactId: string;
             type: "resolved-id";
@@ -1656,7 +1657,6 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
             };
             type: "resolve-target";
         } | undefined;
-        gradleUserHome?: string | undefined;
     } | {
         kind: "file";
         filePath: string;
@@ -1748,7 +1748,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
 }, {
     limit?: number | undefined;
     cursor?: string | undefined;
-    task?: "search" | "class-source" | "artifact" | "auto" | "file" | "versions" | "class-members" | "class-overview" | "list-files" | undefined;
+    task?: "search" | "class-source" | "file" | "auto" | "class-overview" | "class-members" | "artifact" | "versions" | "list-files" | undefined;
     detail?: "summary" | "standard" | "full" | undefined;
     subject?: {
         kind: "version";
@@ -1785,6 +1785,7 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
         scope?: "vanilla" | "merged" | "loader" | undefined;
         preferProjectVersion?: boolean | undefined;
         strictVersion?: boolean | undefined;
+        gradleUserHome?: string | undefined;
         artifact?: {
             artifactId: string;
             type: "resolved-id";
@@ -1795,7 +1796,6 @@ export declare const inspectMinecraftSchema: z.ZodEffects<z.ZodObject<{
             };
             type: "resolve-target";
         } | undefined;
-        gradleUserHome?: string | undefined;
     } | {
         kind: "file";
         filePath: string;

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

@@ -14,7 +14,7 @@ import { handleListFiles } from "./inspect-minecraft/handlers/list-files.js";
 const INCLUDE_GROUPS = ["warnings", "provenance", "candidates", "members", "descriptors", "source", "files", "samples", "artifact", "timings"];
 const nonEmptyString = z.string().trim().min(1);
 export const inspectMinecraftShape = {
-    task: z.enum(TASKS).optional(),
+    task: z.enum(TASKS).optional().describe("Workflow task. auto dispatches only from subject.kind and workspace focus.kind; it is not a natural-language planner."),
     subject: subjectSchema.optional(),
     includeSnapshots: z.boolean().default(false),
     detail: detailSchema.optional(),

package/dist/index.js

@@ -114,7 +114,7 @@ const workspaceMappingService = new WorkspaceMappingService();
 const inspectMinecraftService = new InspectMinecraftService({
     listVersions: (input) => sourceService.listVersions(input),
     resolveArtifact: (input) => sourceService.resolveArtifact(input),
-    findClass: (input) => Promise.resolve(sourceService.findClass(input)),
+    findClass: (input) => sourceService.findClassIncludingNested(input),
     checkSymbolExists: (input) => sourceService.checkSymbolExists(input),
     getClassSource: (input) => sourceService.getClassSource(input),
     getClassMembers: (input) => sourceService.getClassMembers(input),
@@ -472,7 +472,7 @@ expertTool("list-versions", "List available Minecraft versions from Mojang manif
     limit: input.limit
 })));
 registerToolSchema("list-versions", listVersionsSchema);
-server.tool("inspect-minecraft", "Top-level workflow tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings.", inspectMinecraftShape, { readOnlyHint: true }, async (args) => runTool("inspect-minecraft", args, inspectMinecraftSchema, async (input) => inspectMinecraftService.execute(input)));
+server.tool("inspect-minecraft", "Top-level workflow tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings. Workspace subject.focus is a structured class/file/search object, never a string; task=auto dispatches from subject.kind and focus.kind.", inspectMinecraftShape, { readOnlyHint: true }, async (args) => runTool("inspect-minecraft", args, inspectMinecraftSchema, async (input) => inspectMinecraftService.execute(input)));
 registerToolSchema("inspect-minecraft", inspectMinecraftSchema);
 server.tool("analyze-symbol", "Top-level workflow tool for symbol existence, mapping, lifecycle, workspace analysis, and API overview. subject.kind='symbol' auto-detects class/field/method from the selector.", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
 registerToolSchema("analyze-symbol", analyzeSymbolSchema);
@@ -542,15 +542,14 @@ async function resolveFlatArtifactId(input) {
     if (target?.kind === "artifact" && target.artifactId) {
         return target.artifactId;
     }
+    const projectPath = input.projectPath ?? target?.projectPath;
     const resolved = await sourceService.resolveArtifact({
         target: target,
-        ...(target && "projectPath" in target && target.projectPath
-            ? { projectPath: target.projectPath }
-            : {})
+        ...(projectPath ? { projectPath } : {})
     });
     return resolved.artifactId;
 }
-expertTool("find-class", "Resolve a simple or qualified class name to fully-qualified class names within an artifact. Use this before get-class-source when you only have a simple name.", findClassShape, { readOnlyHint: true }, async (args) => runTool("find-class", args, findClassSchema, async (input) => sourceService.findClass({
+expertTool("find-class", "Resolve a simple or qualified class name to fully-qualified class names within an artifact. Use this before get-class-source when you only have a simple name.", findClassShape, { readOnlyHint: true }, async (args) => runTool("find-class", args, findClassSchema, async (input) => sourceService.findClassIncludingNested({
     className: input.className,
     artifactId: await resolveFlatArtifactId(input),
     limit: input.limit

package/dist/source/class-source.d.ts

@@ -59,5 +59,6 @@ export declare function buildDecompiledFallback(svc: SourceService, artifactId:
     truncated: boolean;
 } | undefined;
 export declare function findClass(svc: SourceService, input: FindClassInput): FindClassOutput;
+export declare function findClassIncludingNested(svc: SourceService, input: FindClassInput): Promise<FindClassOutput>;
 export declare function getClassSource(svc: SourceService, input: GetClassSourceInput): Promise<GetClassSourceOutput>;
 export declare function getClassMembers(svc: SourceService, input: GetClassMembersInput): Promise<GetClassMembersOutput>;

package/dist/source/class-source.js

@@ -8,7 +8,7 @@ import { buildClassSourceSnippet } from "./class-source/snippet-builder.js";
 import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire, projectMembersByLevel } from "./class-source/members-builder.js";
 import { collectDidYouMeanCandidates } from "./did-you-mean.js";
 import { matchesMemberPattern } from "./member-pattern.js";
-import { resolveUniqueNestedJarForClass } from "./nested-jars.js";
+import { findNestedJarClasses, resolveUniqueNestedJarForClass } from "./nested-jars.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
@@ -82,6 +82,14 @@ function obfuscatedNamespaceHint(className) {
 function hasPartialNetMinecraftCoverage(qualityFlags) {
     return qualityFlags.includes("partial-source-no-net-minecraft");
 }
+function shouldSuggestObfuscatedMapping(artifact, className) {
+    const nativeDependency = artifact.provenance?.dependencyResolution != null;
+    const shellArtifact = artifact.qualityFlags.includes("shell-jar");
+    return (artifact.mappingApplied === "obfuscated" &&
+        !nativeDependency &&
+        !shellArtifact &&
+        looksLikeDeobfuscatedClassName(className));
+}
 function classNameToClassPath(className) {
     const normalized = normalizePathStyle(className.trim()).replace(/\//g, ".");
     const segments = normalized.split(".").filter((segment) => segment.length > 0);
@@ -398,7 +406,7 @@ export function findClass(svc, input) {
         if (filteredMatches.length === 0 && partialVanillaLookup) {
             warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
         }
-        if (filteredMatches.length === 0 && artifact.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(className)) {
+        if (filteredMatches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
             warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
         }
         return { matches: filteredMatches, total: filteredMatches.length, warnings };
@@ -432,11 +440,39 @@ export function findClass(svc, input) {
     if (filteredMatches.length === 0 && partialVanillaLookup) {
         warnings.push(`Artifact source coverage is partial and excludes net.minecraft; returning non-vanilla matches for "${className}" would be misleading. Use get-class-source/get-class-members for binary fallback or get-class-api-matrix for mapped API inspection.`);
     }
-    if (filteredMatches.length === 0 && artifact.mappingApplied === "obfuscated" && looksLikeDeobfuscatedClassName(className)) {
+    if (filteredMatches.length === 0 && shouldSuggestObfuscatedMapping(artifact, className)) {
         warnings.push(`No exact class symbol matched "${className}". ${obfuscatedNamespaceHint(className)}`);
     }
     return { matches: filteredMatches, total: filteredMatches.length, warnings };
 }
+export async function findClassIncludingNested(svc, input) {
+    const indexed = findClass(svc, input);
+    if (indexed.total > 0) {
+        return indexed;
+    }
+    const artifact = svc.getArtifact(input.artifactId.trim());
+    const inventory = artifact.provenance?.nestedJars;
+    if (!artifact.qualityFlags.includes("shell-jar") ||
+        !artifact.binaryJarPath ||
+        !inventory ||
+        inventory.length === 0) {
+        return indexed;
+    }
+    const limit = Math.max(1, Math.min(input.limit ?? 20, 200));
+    const matches = await findNestedJarClasses({
+        cacheDir: svc.config.cacheDir,
+        outerJarPath: artifact.binaryJarPath,
+        outerSignature: artifact.artifactId,
+        inventory,
+        className: input.className,
+        limit
+    });
+    return {
+        matches,
+        total: matches.length,
+        warnings: indexed.warnings
+    };
+}
 export async function getClassSource(svc, input) {
     const className = input.className.trim();
     if (!className) {

package/dist/source/nested-jars.d.ts

@@ -9,6 +9,25 @@ export interface NestedJarMatch {
     entryName: string;
     extractedPath: string;
 }
+export interface NestedClassMatch {
+    qualifiedName: string;
+    filePath: string;
+    line: number;
+    symbolKind: "class";
+}
+/**
+ * Finds exact class-name matches across a shell's nested bytecode inventory.
+ * Results use the same binary-backed class representation as entry-tool search:
+ * an inferred outer Java path, line 1, and the broad class symbol kind.
+ */
+export declare function findNestedJarClasses(args: {
+    cacheDir: string;
+    outerJarPath: string;
+    outerSignature: string;
+    inventory: string[];
+    className: string;
+    limit: number;
+}): Promise<NestedClassMatch[]>;
 /**
  * Shell detection with both required signals: near-zero own classes AND
  * bundled nested jars (META-INF/jars scan or fabric.mod.json "jars"

package/dist/source/nested-jars.js

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { buildSuggestedCall } from "../build-suggested-call.js";
 import { ERROR_CODES, createError } from "../errors.js";
 import { collectNestedJars } from "../mod-analyzer.js";
+import { isSecureJarEntryPath } from "../path-resolver.js";
 import { listJarEntries, readJarEntryAsBuffer, readJarEntryAsUtf8 } from "../source-jar-reader.js";
 /**
  * A jar with at most this many own `.class` entries can qualify as a
@@ -29,6 +30,84 @@ function rememberClassSet(key, value) {
         classSetCache.delete(oldest);
     }
 }
+async function loadNestedJarClassSet(args) {
+    let extractedPath;
+    try {
+        extractedPath = await extractNestedJar(args.cacheDir, args.outerJarPath, args.outerSignature, args.entryName);
+    }
+    catch {
+        return undefined;
+    }
+    let classSet = classSetCache.get(extractedPath);
+    if (!classSet) {
+        try {
+            const entries = await listJarEntries(extractedPath);
+            classSet = new Set(entries.filter((entry) => entry.endsWith(".class") && isSecureJarEntryPath(entry)));
+        }
+        catch {
+            return undefined;
+        }
+        rememberClassSet(extractedPath, classSet);
+    }
+    return { extractedPath, classSet };
+}
+function nestedClassMatch(entry) {
+    const internalName = entry.slice(0, -".class".length);
+    if (internalName.startsWith("META-INF/versions/")) {
+        return undefined;
+    }
+    const binarySimpleName = internalName.split("/").at(-1) ?? internalName;
+    if (binarySimpleName === "module-info" || binarySimpleName === "package-info") {
+        return undefined;
+    }
+    const innerSegments = binarySimpleName.split("$").slice(1);
+    if (innerSegments.some((segment) => segment.length === 0 || /^\d/.test(segment))) {
+        return undefined;
+    }
+    return {
+        qualifiedName: internalName.replaceAll("/", ".").replaceAll("$", "."),
+        filePath: `${internalName.split("$")[0]}.java`,
+        line: 1,
+        symbolKind: "class"
+    };
+}
+/**
+ * Finds exact class-name matches across a shell's nested bytecode inventory.
+ * Results use the same binary-backed class representation as entry-tool search:
+ * an inferred outer Java path, line 1, and the broad class symbol kind.
+ */
+export async function findNestedJarClasses(args) {
+    const normalizedQuery = args.className.trim().replaceAll("/", ".").replaceAll("$", ".");
+    const isQualified = normalizedQuery.includes(".");
+    const matches = new Map();
+    inventory: for (const entryName of args.inventory) {
+        const loaded = await loadNestedJarClassSet({
+            cacheDir: args.cacheDir,
+            outerJarPath: args.outerJarPath,
+            outerSignature: args.outerSignature,
+            entryName
+        });
+        if (!loaded) {
+            continue;
+        }
+        for (const classEntry of [...loaded.classSet].sort((left, right) => left.localeCompare(right))) {
+            const match = nestedClassMatch(classEntry);
+            if (!match) {
+                continue;
+            }
+            const simpleName = match.qualifiedName.split(".").at(-1) ?? match.qualifiedName;
+            if ((isQualified && match.qualifiedName !== normalizedQuery) ||
+                (!isQualified && simpleName !== normalizedQuery)) {
+                continue;
+            }
+            matches.set(match.qualifiedName, match);
+            if (isQualified || matches.size >= args.limit) {
+                break inventory;
+            }
+        }
+    }
+    return [...matches.values()];
+}
 /**
  * Shell detection with both required signals: near-zero own classes AND
  * bundled nested jars (META-INF/jars scan or fabric.mod.json "jars"
@@ -128,29 +207,19 @@ export async function extractNestedJar(cacheDir, outerJarPath, outerSignature, e
  */
 export async function findNestedJarsContainingClass(args) {
     const classEntry = `${args.internalName}.class`;
+    const qualifiedName = args.internalName.replaceAll("/", ".").replaceAll("$", ".");
     const matches = [];
     for (const entryName of args.inventory) {
-        let extractedPath;
-        try {
-            extractedPath = await extractNestedJar(args.cacheDir, args.outerJarPath, args.outerSignature, entryName);
-        }
-        catch {
-            // Unsafe or unreadable nested entries never become candidates.
-            continue;
-        }
-        let classSet = classSetCache.get(extractedPath);
-        if (!classSet) {
-            try {
-                const entries = await listJarEntries(extractedPath);
-                classSet = new Set(entries.filter((entry) => entry.endsWith(".class")));
-            }
-            catch {
-                continue;
-            }
-            rememberClassSet(extractedPath, classSet);
-        }
-        if (classSet.has(classEntry)) {
-            matches.push({ entryName, extractedPath });
+        const loaded = await loadNestedJarClassSet({
+            cacheDir: args.cacheDir,
+            outerJarPath: args.outerJarPath,
+            outerSignature: args.outerSignature,
+            entryName
+        });
+        const containsClass = loaded?.classSet.has(classEntry) || [...(loaded?.classSet ?? [])].some((entry) => entry.endsWith(".class") &&
+            entry.slice(0, -".class".length).replaceAll("/", ".").replaceAll("$", ".") === qualifiedName);
+        if (loaded && containsClass) {
+            matches.push({ entryName, extractedPath: loaded.extractedPath });
         }
     }
     return matches;

package/dist/source-service.d.ts

@@ -670,6 +670,7 @@ export declare class SourceService {
     traceSymbolLifecycle(input: TraceSymbolLifecycleInput): Promise<TraceSymbolLifecycleOutput>;
     diffClassSignatures(input: DiffClassSignaturesInput): Promise<DiffClassSignaturesOutput>;
     findClass(input: FindClassInput): FindClassOutput;
+    findClassIncludingNested(input: FindClassInput): Promise<FindClassOutput>;
     getClassSource(input: GetClassSourceInput): Promise<GetClassSourceOutput>;
     getClassMembers(input: GetClassMembersInput): Promise<GetClassMembersOutput>;
     validateMixin(input: ValidateMixinInput, options?: ValidateMixinOptions): Promise<ValidateMixinOutput>;

package/dist/source-service.js

@@ -215,6 +215,9 @@ export class SourceService {
     findClass(input) {
         return classSource.findClass(this, input);
     }
+    async findClassIncludingNested(input) {
+        return classSource.findClassIncludingNested(this, input);
+    }
     async getClassSource(input) {
         return classSource.getClassSource(this, input);
     }

package/dist/tool-contract-manifest.js

@@ -32,7 +32,7 @@ const SECTION_ROWS = {
         en: [
             "| `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 |",

package/dist/tool-guidance.js

@@ -656,7 +656,103 @@ function gatedGuidance(tool, hints, params) {
         primaryDropped: !validated.suggestedCall
     };
 }
+function buildInspectWorkspaceSubject(source) {
+    const subject = {
+        kind: "workspace",
+        projectPath: asNonEmptyString(source.projectPath) ?? "<workspace-path>"
+    };
+    if (typeof source.mapping === "string" &&
+        ["obfuscated", "mojang", "intermediary", "yarn"].includes(source.mapping)) {
+        subject.mapping = source.mapping;
+    }
+    if (typeof source.scope === "string" &&
+        ["vanilla", "merged", "loader"].includes(source.scope)) {
+        subject.scope = source.scope;
+    }
+    const gradleUserHome = asNonEmptyString(source.gradleUserHome);
+    if (gradleUserHome) {
+        subject.gradleUserHome = gradleUserHome;
+    }
+    if (typeof source.preferProjectVersion === "boolean") {
+        subject.preferProjectVersion = source.preferProjectVersion;
+    }
+    if (typeof source.strictVersion === "boolean") {
+        subject.strictVersion = source.strictVersion;
+    }
+    return subject;
+}
+function inspectTaskForFocus(task, focusKind) {
+    if (focusKind === "class" &&
+        (task === "auto" || task === "class-overview" || task === "class-source" || task === "class-members")) {
+        return task;
+    }
+    if (focusKind === "search" && (task === "auto" || task === "search")) {
+        return task;
+    }
+    if (focusKind === "file" && (task === "auto" || task === "file")) {
+        return task;
+    }
+    return "auto";
+}
+function buildInspectMinecraftInvalidFocusGuidance(normalizedInput) {
+    const input = asObjectRecord(normalizedInput);
+    const originalSubject = asObjectRecord(input?.subject);
+    if (originalSubject?.kind !== "workspace" ||
+        originalSubject.focus === undefined ||
+        asObjectRecord(originalSubject.focus)) {
+        return undefined;
+    }
+    const requestedTask = asNonEmptyString(input?.task);
+    const workspaceSubject = buildInspectWorkspaceSubject(originalSubject);
+    const examples = [
+        {
+            params: {
+                task: inspectTaskForFocus(requestedTask, "class"),
+                subject: {
+                    ...workspaceSubject,
+                    focus: { kind: "class", className: "<fully-qualified-class-name>" }
+                }
+            },
+            reason: "Use class focus for class overview, source, or member inspection."
+        },
+        {
+            params: {
+                task: inspectTaskForFocus(requestedTask, "search"),
+                subject: {
+                    ...workspaceSubject,
+                    focus: { kind: "search", query: "<search-query>" }
+                }
+            },
+            reason: "Use search focus for symbol, text, or path search."
+        },
+        {
+            params: {
+                task: inspectTaskForFocus(requestedTask, "file"),
+                subject: {
+                    ...workspaceSubject,
+                    focus: { kind: "file", filePath: "<artifact-relative-file-path>" }
+                }
+            },
+            reason: "Use file focus for an artifact-relative file read."
+        }
+    ];
+    const validated = buildSuggestedCall({
+        tool: "inspect-minecraft",
+        params: undefined,
+        examples
+    });
+    return {
+        hints: [
+            "inspect-minecraft subject.focus must be a structured object, not a string.",
+            "Choose focus.kind=class with className, search with query, or file with filePath; task=auto dispatches from that kind and does not interpret prose."
+        ],
+        ...(validated.exampleCalls ? { exampleCalls: validated.exampleCalls } : {})
+    };
+}
 export function buildInvalidInputGuidance(tool, normalizedInput) {
+    if (tool === "inspect-minecraft") {
+        return buildInspectMinecraftInvalidFocusGuidance(normalizedInput);
+    }
     if (tool === "validate-mixin") {
         return gatedGuidance(tool, [
             "validate-mixin.input must be an object with input.mode = \"inline\" | \"path\" | \"paths\" | \"config\" | \"project\".",
@@ -719,6 +815,13 @@ export function mapErrorToProblem(caughtError, requestId, context) {
     }
     if (isAppError(caughtError)) {
         const { suggestedCall, exampleCalls, primaryDropped } = extractValidatedSuggestionAndExamples(caughtError.details);
+        const invalidInputGuidance = context?.tool === "inspect-minecraft" && caughtError.code === ERROR_CODES.INVALID_INPUT
+            ? buildInvalidInputGuidance(context.tool, context.normalizedInput)
+            : undefined;
+        const effectiveSuggestedCall = invalidInputGuidance
+            ? invalidInputGuidance.suggestedCall
+            : suggestedCall;
+        const effectiveExampleCalls = invalidInputGuidance?.exampleCalls ?? exampleCalls;
         const sanitizedContext = extractAllowlistedContext(caughtError.details);
         const extractedDidYouMean = extractDidYouMean(caughtError.details);
         let failedStage = extractFailedStageFromDetails(caughtError.details);
@@ -727,10 +830,13 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             && caughtError.code === ERROR_CODES.INVALID_INPUT) {
             failedStage = "input-validation";
         }
-        const baseHints = toHints(caughtError.details);
-        const hintsWithFallback = primaryDropped && !suggestedCall
-            ? [...(baseHints ?? []), VALIDATION_FALLBACK_HINT]
-            : baseHints;
+        const baseHints = [
+            ...(toHints(caughtError.details) ?? []),
+            ...(invalidInputGuidance?.hints ?? [])
+        ];
+        const hintsWithFallback = primaryDropped && !effectiveSuggestedCall
+            ? [...baseHints, VALIDATION_FALLBACK_HINT]
+            : baseHints.length > 0 ? baseHints : undefined;
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -742,8 +848,8 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             issueOrigin: issueOriginForErrorCode(caughtError.code),
             fieldErrors: extractFieldErrorsFromDetails(caughtError.details),
             hints: hintsWithFallback,
-            ...(suggestedCall ? { suggestedCall } : {}),
-            ...(exampleCalls ? { exampleCalls } : {}),
+            ...(effectiveSuggestedCall ? { suggestedCall: effectiveSuggestedCall } : {}),
+            ...(effectiveExampleCalls ? { exampleCalls: effectiveExampleCalls } : {}),
             ...(extractedDidYouMean ? { didYouMean: extractedDidYouMean } : {}),
             ...(failedStage ? { failedStage } : {}),
             ...(sanitizedContext ? { context: sanitizedContext } : {})

package/dist/tool-schemas.d.ts

@@ -2529,6 +2529,7 @@ export declare const findClassShape: {
         kind: "artifact";
         artifactId: string;
     }>]>>;
+    projectPath: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
 };
 export declare const findClassSchema: z.ZodEffects<z.ZodObject<{
@@ -2601,9 +2602,11 @@ export declare const findClassSchema: z.ZodEffects<z.ZodObject<{
         kind: "artifact";
         artifactId: string;
     }>]>>;
+    projectPath: z.ZodOptional<z.ZodString>;
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     className: string;
+    projectPath?: string | undefined;
     artifactId?: string | undefined;
     limit?: number | undefined;
     target?: {
@@ -2631,6 +2634,7 @@ export declare const findClassSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
 }, {
     className: string;
+    projectPath?: string | undefined;
     artifactId?: string | undefined;
     limit?: number | undefined;
     target?: {
@@ -2658,6 +2662,7 @@ export declare const findClassSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
 }>, {
     className: string;
+    projectPath?: string | undefined;
     artifactId?: string | undefined;
     limit?: number | undefined;
     target?: {
@@ -2685,6 +2690,7 @@ export declare const findClassSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
 }, {
     className: string;
+    projectPath?: string | undefined;
     artifactId?: string | undefined;
     limit?: number | undefined;
     target?: {
@@ -3596,8 +3602,8 @@ export declare const traceSymbolLifecycleSchema: z.ZodObject<{
     descriptor?: string | undefined;
     mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
     sourcePriority?: "loom-first" | "maven-first" | undefined;
-    maxVersions?: number | undefined;
     gradleUserHome?: string | undefined;
+    maxVersions?: number | undefined;
     includeSnapshots?: boolean | undefined;
     fromVersion?: string | undefined;
     toVersion?: string | undefined;
@@ -4053,10 +4059,10 @@ export declare const nbtToJsonSchema: z.ZodObject<{
     compression: z.ZodDefault<z.ZodEnum<["none", "gzip", "auto"]>>;
 }, "strip", z.ZodTypeAny, {
     nbtBase64: string;
-    compression: "none" | "gzip" | "auto";
+    compression: "auto" | "none" | "gzip";
 }, {
     nbtBase64: string;
-    compression?: "none" | "gzip" | "auto" | undefined;
+    compression?: "auto" | "none" | "gzip" | undefined;
 }>;
 export declare const nbtApplyJsonPatchShape: {
     typedJson: z.ZodUnknown;

package/dist/tool-schemas.js

@@ -371,6 +371,7 @@ 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);

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,12 +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.
@@ -59,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.
@@ -288,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`) |
@@ -419,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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "6.2.0",
+  "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",