@adhisang/minecraft-modding-mcp 6.1.1 → 6.3.0

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/entry-tools/manage-cache-service.d.ts

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

package/dist/error-mapping.d.ts

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

package/dist/error-mapping.js

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

package/dist/errors.d.ts

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

package/dist/errors.js

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

package/dist/index.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { makeStageEmitter } from "./stage-emitter.js";
-import { ZodError, z } from "zod";
+import { ZodError } from "zod";
 import { CompatStdioServerTransport } from "./compat-stdio-transport.js";
 import { objectResult } from "./mcp-helpers.js";
 import { prepareToolInput } from "./tool-input.js";
@@ -34,7 +34,7 @@ import { buildEntryToolMeta } from "./entry-tools/response-contract.js";
 import { registerToolSchema } from "./tool-schema-registry.js";
 import { buildSuggestedCall } from "./build-suggested-call.js";
 import { applyErrorMetaExtensions, mapErrorToProblem } from "./tool-guidance.js";
-import { nonEmptyString, optionalPositiveInt, analyzeModJarSchema, analyzeModJarShape, batchClassMembersSchema, batchClassMembersShape, batchClassSourceSchema, batchClassSourceShape, batchMappingsSchema, batchMappingsShape, batchSymbolExistsSchema, batchSymbolExistsShape, checkSymbolExistsSchema, checkSymbolExistsShape, compareVersionsSchema, compareVersionsShape, decompileModJarSchema, decompileModJarShape, diffClassSignaturesSchema, diffClassSignaturesShape, emptySchema, findMappingSchema, findMappingShape, getArtifactFileSchema, getArtifactFileShape, getClassApiMatrixSchema, getClassApiMatrixShape, getClassMembersSchema, getClassMembersShape, getClassSourceSchema, getClassSourceShape, getModClassSourceSchema, getModClassSourceShape, getRegistryDataSchema, getRegistryDataShape, indexArtifactSchema, indexArtifactShape, jsonToNbtSchema, jsonToNbtShape, listArtifactFilesSchema, listArtifactFilesShape, listVersionsSchema, listVersionsShape, nbtApplyJsonPatchSchema, nbtApplyJsonPatchShape, nbtToJsonSchema, nbtToJsonShape, remapModJarSchema, remapModJarShape, resolveArtifactSchema, resolveArtifactShape, resolveMethodMappingExactSchema, resolveMethodMappingExactShape, resolveWorkspaceSymbolSchema, resolveWorkspaceSymbolShape, searchClassSourceSchema, searchClassSourceShape, searchModSourceSchema, searchModSourceShape, traceSymbolLifecycleSchema, traceSymbolLifecycleShape, validateAccessTransformerSchema, validateAccessTransformerShape, validateAccessWidenerSchema, validateAccessWidenerShape, validateMixinSchema, validateMixinShape, verifyMixinTargetSchema, verifyMixinTargetShape } from "./tool-schemas.js";
+import { analyzeModJarSchema, analyzeModJarShape, batchClassMembersSchema, batchClassMembersShape, batchClassSourceSchema, batchClassSourceShape, batchMappingsSchema, batchMappingsShape, batchSymbolExistsSchema, batchSymbolExistsShape, checkSymbolExistsSchema, checkSymbolExistsShape, compareVersionsSchema, compareVersionsShape, decompileModJarSchema, decompileModJarShape, diffClassSignaturesSchema, diffClassSignaturesShape, emptySchema, findMappingSchema, findMappingShape, getArtifactFileSchema, getArtifactFileShape, getClassApiMatrixSchema, getClassApiMatrixShape, getClassMembersSchema, getClassMembersShape, getClassSourceSchema, getClassSourceShape, getModClassSourceSchema, getModClassSourceShape, getRegistryDataSchema, getRegistryDataShape, indexArtifactSchema, indexArtifactShape, jsonToNbtSchema, jsonToNbtShape, listArtifactFilesSchema, listArtifactFilesShape, listVersionsSchema, listVersionsShape, nbtApplyJsonPatchSchema, nbtApplyJsonPatchShape, nbtToJsonSchema, nbtToJsonShape, remapModJarSchema, remapModJarShape, resolveArtifactSchema, resolveArtifactShape, resolveMethodMappingExactSchema, resolveMethodMappingExactShape, resolveWorkspaceSymbolSchema, resolveWorkspaceSymbolShape, searchClassSourceSchema, searchClassSourceShape, searchModSourceSchema, searchModSourceShape, traceSymbolLifecycleSchema, traceSymbolLifecycleShape, validateAccessTransformerSchema, validateAccessTransformerShape, validateAccessWidenerSchema, validateAccessWidenerShape, validateMixinSchema, validateMixinShape, verifyMixinTargetSchema, verifyMixinTargetShape, findClassShape, findClassSchema } from "./tool-schemas.js";
 export { mapErrorToProblem, applyErrorMetaExtensions };
 if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "production";
@@ -114,16 +114,18 @@ 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),
     searchClassSource: (input) => sourceService.searchClassSource(input),
     getArtifactFile: (input) => sourceService.getArtifactFile(input),
     listArtifactFiles: (input) => sourceService.listArtifactFiles(input),
-    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath)
+    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath),
+    listWorkspaceContexts: () => sourceService.workspaceContextCache.list()
 });
 const analyzeSymbolService = new AnalyzeSymbolService({
+    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath),
     checkSymbolExists: (input) => sourceService.checkSymbolExists(input),
     findMapping: (input) => sourceService.findMapping(input),
     resolveMethodMappingExact: (input) => sourceService.resolveMethodMappingExact(input),
@@ -141,7 +143,8 @@ const analyzeModService = new AnalyzeModService({
     decompileModJar: (input) => sourceService.decompileModJar(input),
     getModClassSource: (input) => sourceService.getModClassSource(input),
     searchModSource: (input) => sourceService.searchModSource(input),
-    remapModJar: (input) => remapModJar(input, config)
+    remapModJar: (input) => remapModJar(input, config),
+    getModClassMembers: (input) => sourceService.getModClassMembers(input)
 });
 const validateProjectService = new ValidateProjectService({
     validateMixin: (input, options) => sourceService.validateMixin(input, options),
@@ -469,13 +472,13 @@ 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);
 server.tool("compare-minecraft", "Top-level workflow tool for version comparisons, class diffs, registry diffs, and migration overviews.", compareMinecraftShape, { readOnlyHint: true }, async (args) => runTool("compare-minecraft", args, compareMinecraftSchema, async (input) => compareMinecraftService.execute(input)));
 registerToolSchema("compare-minecraft", compareMinecraftSchema);
-server.tool("analyze-mod", "Top-level workflow tool for mod metadata inspection, decompile/search flows, class source, and safe remap previews/applies.", analyzeModShape, { readOnlyHint: false }, async (args) => runTool("analyze-mod", args, analyzeModSchema, async (input) => analyzeModService.execute(input)));
+server.tool("analyze-mod", "Top-level workflow tool for mod metadata inspection, decompile/search flows, class source, bytecode-only class member reads, and safe remap previews/applies.", analyzeModShape, { readOnlyHint: false }, async (args) => runTool("analyze-mod", args, analyzeModSchema, async (input) => analyzeModService.execute(input)));
 registerToolSchema("analyze-mod", analyzeModSchema);
 server.tool("validate-project", "Top-level workflow tool for project summary, direct mixin validation, and access widener/access transformer validation.", validateProjectShape, { readOnlyHint: true }, async (args, extra) => runTool("validate-project", args, validateProjectSchema, async (input) => validateProjectService.execute(input, {
     stageEmitter: makeStageEmitter(extra)
@@ -524,15 +527,31 @@ expertTool("resolve-artifact", "Resolve a source artifact and return artifact me
         (Array.isArray(input.include) && input.include.includes("samples"))
 })));
 registerToolSchema("resolve-artifact", resolveArtifactSchema);
-const findClassShape = {
-    className: nonEmptyString.describe("Simple name (e.g. Blocks) or fully-qualified name (e.g. net.minecraft.world.level.block.Blocks)"),
-    artifactId: nonEmptyString,
-    limit: optionalPositiveInt.describe("default 20, max 200")
-};
-const findClassSchema = z.object(findClassShape);
-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({
+// Flat tools accept `target` as an additive alternative to `artifactId`
+// (mutually exclusive, enforced by each schema). A target is resolved to its
+// artifactId here before the underlying artifactId-based service call.
+async function resolveFlatArtifactId(input) {
+    if (input.artifactId) {
+        return input.artifactId;
+    }
+    const target = input.target;
+    // {kind:"artifact"} reuses an already-resolved artifact without a resolve
+    // round-trip. Workspace-context kinds carry their own projectPath when the
+    // target shape provides one; kinds that require workspace context beyond
+    // that fail with the resolver's own projectPath guidance.
+    if (target?.kind === "artifact" && target.artifactId) {
+        return target.artifactId;
+    }
+    const projectPath = input.projectPath ?? target?.projectPath;
+    const resolved = await sourceService.resolveArtifact({
+        target: target,
+        ...(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.findClassIncludingNested({
     className: input.className,
-    artifactId: input.artifactId,
+    artifactId: await resolveFlatArtifactId(input),
     limit: input.limit
 })));
 registerToolSchema("find-class", findClassSchema);
@@ -596,7 +615,7 @@ expertTool("search-class-source", "Search indexed class source files for one art
         }
         : undefined;
     return sourceService.searchClassSource({
-        artifactId: input.artifactId,
+        artifactId: await resolveFlatArtifactId(input),
         query: input.query,
         intent: input.intent,
         match: input.match,
@@ -611,13 +630,13 @@ expertTool("search-class-source", "Search indexed class source files for one art
 }));
 registerToolSchema("search-class-source", searchClassSourceSchema);
 expertTool("get-artifact-file", "Get full source file content by artifactId and file path.", getArtifactFileShape, { readOnlyHint: true }, async (args) => runTool("get-artifact-file", args, getArtifactFileSchema, async (input) => sourceService.getArtifactFile({
-    artifactId: input.artifactId,
+    artifactId: await resolveFlatArtifactId(input),
     filePath: input.filePath,
     maxBytes: input.maxBytes
 })));
 registerToolSchema("get-artifact-file", getArtifactFileSchema);
 expertTool("list-artifact-files", "List source file paths in an artifact with optional prefix filter and cursor-based pagination.", listArtifactFilesShape, { readOnlyHint: true }, async (args) => runTool("list-artifact-files", args, listArtifactFilesSchema, async (input) => sourceService.listArtifactFiles({
-    artifactId: input.artifactId,
+    artifactId: await resolveFlatArtifactId(input),
     prefix: input.prefix,
     limit: input.limit,
     cursor: input.cursor
@@ -727,8 +746,8 @@ server.tool("json-to-nbt", "Encode typed NBT JSON to Java Edition NBT binary pay
     compression: input.compression
 }, nbtLimits))));
 registerToolSchema("json-to-nbt", jsonToNbtSchema);
-expertTool("index-artifact", "Rebuild indexed files/symbols metadata for an existing artifactId. Does not resolve new artifacts.", indexArtifactShape, { readOnlyHint: false, idempotentHint: true }, async (args) => runTool("index-artifact", args, indexArtifactSchema, async (input) => sourceService.indexArtifact({
-    artifactId: input.artifactId,
+expertTool("index-artifact", "Rebuild indexed files/symbols metadata for an artifact addressed by artifactId or target. A new target is resolved and ingested first; force rebuilds an existing index.", indexArtifactShape, { readOnlyHint: false, idempotentHint: true }, async (args) => runTool("index-artifact", args, indexArtifactSchema, async (input) => sourceService.indexArtifact({
+    artifactId: await resolveFlatArtifactId(input),
     force: input.force
 })));
 registerToolSchema("index-artifact", indexArtifactSchema);

package/dist/mapping/internal-types.d.ts

@@ -56,6 +56,13 @@ export type CandidateAccumulator = {
 };
 export type LoadedGraph = {
     version: string;
+    /**
+     * True when the runtime already uses deobfuscated names, so the graph is
+     * deliberately empty. Surfaces on outputs as
+     * mappingContext.unobfuscatedRuntime instead of a per-response warning
+     * sentence.
+     */
+    unobfuscatedRuntime?: boolean;
     priority: import("../types.js").MappingSourcePriority;
     mode: GraphLoadMode;
     pairs: Map<PairKey, PairRecord>;

package/dist/mapping/types.d.ts

@@ -38,6 +38,19 @@ export type SymbolResolutionOutput = {
         sourceMapping: SourceMapping;
         targetMapping?: SourceMapping;
         sourcePriorityApplied: MappingSourcePriority;
+        /**
+         * The runtime already uses deobfuscated names, so the mapping graph is
+         * deliberately empty. Replaces the former per-response warning
+         * "Version X is unobfuscated; mapping graph is empty because the runtime
+         * already uses deobfuscated names."
+         */
+        unobfuscatedRuntime?: boolean;
+        /**
+         * Symbol existence was validated against runtime bytecode. Replaces the
+         * former per-response warning "Version X is unobfuscated; validated
+         * symbol existence against runtime bytecode."
+         */
+        runtimeValidated?: boolean;
     };
     resolved: boolean;
     status: SymbolResolutionStatus;
@@ -122,6 +135,11 @@ export type ClassApiMatrixRow = {
     completeness: boolean;
 };
 export type ClassApiMatrixOutput = {
+    /**
+     * The runtime already uses deobfuscated names, so non-mojang matrix
+     * columns are empty by design (the mapping graph is deliberately empty).
+     */
+    unobfuscatedRuntime?: boolean;
     version: string;
     className: string;
     classNameMapping: SourceMapping;

package/dist/mapping-service.js

@@ -126,6 +126,9 @@ export class MappingService {
             };
         }
         const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath, input.gradleUserHome);
+        if (graph.unobfuscatedRuntime) {
+            mappingContext.unobfuscatedRuntime = true;
+        }
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -352,6 +355,9 @@ export class MappingService {
             };
         }
         const graph = await this.loadGraph(version, priority, requiresOnlyObfuscatedMojangGraph(sourceMapping, targetMapping) ? "obfuscated-mojang-only" : "full", input.projectPath, input.gradleUserHome);
+        if (graph.unobfuscatedRuntime) {
+            mappingContext.unobfuscatedRuntime = true;
+        }
         const path = namespacePath(graph, sourceMapping, targetMapping);
         if (!path) {
             return {
@@ -469,6 +475,7 @@ export class MappingService {
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
         const graph = await this.loadGraph(version, priority, "full", undefined, input.gradleUserHome);
         const warnings = [...graph.warnings];
+        const unobfuscatedRuntime = graph.unobfuscatedRuntime === true;
         const includeKinds = normalizeIncludedKinds(input.includeKinds);
         const pathCache = new Map();
         const resolvePath = (sourceMapping, targetMapping) => {
@@ -514,6 +521,7 @@ export class MappingService {
                 },
                 rows: [],
                 rowCount: 0,
+                ...(unobfuscatedRuntime ? { unobfuscatedRuntime: true } : {}),
                 warnings
             };
         }
@@ -638,6 +646,7 @@ export class MappingService {
             version,
             className,
             classNameMapping,
+            ...(unobfuscatedRuntime ? { unobfuscatedRuntime: true } : {}),
             classIdentity: {
                 obfuscated: classByMapping.obfuscated?.symbol,
                 mojang: classByMapping.mojang?.symbol,
@@ -727,6 +736,9 @@ export class MappingService {
                 };
             })();
         const graph = await this.loadGraph(version, priority, sourceMapping === "mojang" ? "obfuscated-mojang-only" : "full", undefined, input.gradleUserHome);
+        if (graph.unobfuscatedRuntime) {
+            mappingContext.unobfuscatedRuntime = true;
+        }
         const warnings = [...graph.warnings];
         const records = collectTargetRecords(graph, sourceMapping);
         if (records.length === 0) {
@@ -1115,9 +1127,10 @@ export class MappingService {
                 recordsByTarget: new Map(),
                 exactRecordIndex: new Map(),
                 classProjectionCache: new Map(),
-                warnings: [
-                    `Version ${version} is unobfuscated; mapping graph is empty because the runtime already uses deobfuscated names.`
-                ]
+                // No warning sentence: consumers surface this as the structured
+                // mappingContext.unobfuscatedRuntime flag instead.
+                unobfuscatedRuntime: true,
+                warnings: []
             };
         }
         const graph = {

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

@@ -15,6 +15,10 @@ export interface SignatureMember {
     jvmDescriptor: string;
     accessFlags: number;
     isSynthetic: boolean;
+    /** Rendered default value of an annotation-type member (AnnotationDefault). */
+    annotationDefault?: string;
+    /** Rendered runtime-visible annotations on the member, e.g. "@java.lang.Deprecated". */
+    annotations?: string[];
 }
 export interface GetSignatureInput {
     fqn: string;