@adhisang/minecraft-modding-mcp 4.1.0 → 4.1.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [4.1.1] - 2026-05-10
+
+### Documentation
+- `package.json` `description` and `keywords` now mirror the GitHub repository's `description` and topics. `description` summarizes the actual feature surface (source inspection, Mojang/Yarn/Intermediary mappings, version diffs, Fabric/Forge/NeoForge mod JAR analysis, Mixin/Access Widener/Access Transformer validation); `keywords` expands from three entries to the published 15-topic set.
+
+### Fixed
+- Concurrent class source/member lookups in the same MCP server process now share one in-flight source indexing/decompile rebuild for the same binary fallback artifact.
+- `validate-project task="project-summary"` no longer performs heavyweight source indexing for its `minecraft.artifact.resolved` task probe. The probe now uses lightweight artifact metadata while preserving the public `tasks` response shape.
+- `validate-mixin` mapping-health checks no longer load the full Tiny mapping graph for `obfuscated` or `mojang` requests, preventing `validate-project task="project-summary"` worker restarts on large Mojang-mapped workspaces.
+- `validate-project task="project-summary"` task report no longer marks executed validators as `skipped` when the lightweight `minecraft.artifact.resolved` probe fails. Mixin / access-widener / access-transformer entries now reflect their real outcome (`ok` with `counts`, or `error`).
+- `validate-mixin` `toolHealth.tinyMappingsAvailable` now means "Tiny is sufficient for the request": `true` when Tiny is not required (`obfuscated` / `mojang`) or is loaded, `false` only when `intermediary` / `yarn` was requested and Tiny is unavailable. `confidenceScore` is no longer penalized when Tiny is intentionally skipped, including on graph-load failure.
+- `validate-project task="project-summary"` lightweight artifact probe defaults omitted `scope` to `"vanilla"` to match `validate-mixin`'s resolve stage, skipping workspace-wide source-jar discovery unless the caller explicitly requests `scope="merged"` or `scope="loader"`.
+- `validate-project task="project-summary"` stage notifications are now best-effort. Telemetry/transport failures no longer abort the summary, count as validation errors, hide nested `validate-mixin` work behind zero-count summaries, or surface as `ERR_ARTIFACT_PROBE_FAILED` in `tasks["minecraft.artifact.resolved"]`.
+
 ## [4.1.0] - 2026-05-09
 
 ### Documentation

package/README.md

@@ -159,6 +159,8 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - For unobfuscated releases such as `26.1+`, `check-symbol-exists` and `analyze-symbol task="exists"` validate `mojang` lookups against runtime bytecode when no mapping graph exists, and return `mapping_unavailable` when the runtime JAR itself is unreachable.
 - `analyze-mod` and `validate-project` require structured `subject` objects and canonical `include` groups; stale string-subject or domain-include payloads return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
 - `validate-project task="project-summary"` propagates `preferProjectVersion=true` across discovered Mixin, Access Widener, and Access Transformer checks. If no version can be resolved from the request or `gradle.properties`, the summary returns recovery guidance instead of guessing.
+- `validate-mixin` and `validate-project` keep `mapping-health` lightweight for `obfuscated` and `mojang` validation, avoiding full Tiny mapping graph loads unless `intermediary` or `yarn` namespaces are requested.
+- `validate-project task="project-summary"` uses a lightweight artifact probe for `tasks["minecraft.artifact.resolved"]`; it does not decompile Minecraft or rebuild the source index just to report per-probe status. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
 
 ### Inspect Minecraft source from a version
 
@@ -362,6 +364,8 @@ Tools for querying generated registry data and inspecting server runtime state.
 
 Tools that share one resolved artifact or Minecraft version across a fixed shortlist. Results include one status per item plus an aggregate `summary`. See [Batch lookup contract](docs/tool-reference.md#batch-lookup-contract) for failure handling and retry mapping.
 
+Within one MCP server process, batch class lookups that need the same binary fallback share one in-flight source indexing/decompile rebuild for that artifact.
+
 <!-- BEGIN GENERATED TOOL TABLE: batch-lookup -->
 | Tool | Purpose |
 | --- | --- |

package/dist/entry-tools/validate-project/cases/project-summary.d.ts

@@ -1,7 +1,11 @@
 import { type DetailLevel } from "../../response-contract.js";
+import type { StageEmitter } from "../../../stage-emitter.js";
 import type { ValidateProjectInput } from "../../validate-project-service.js";
 import { type ValidateProjectDeps } from "../internal.js";
-export declare function handleProjectSummary(deps: ValidateProjectDeps, input: ValidateProjectInput, detail: DetailLevel, include: string[]): Promise<{
+type ProjectSummaryOptions = {
+    stageEmitter?: StageEmitter;
+};
+export declare function handleProjectSummary(deps: ValidateProjectDeps, input: ValidateProjectInput, detail: DetailLevel, include: string[], options?: ProjectSummaryOptions): Promise<{
     warnings: string[];
     tasks?: {
         "workspace.detected": {
@@ -95,3 +99,4 @@ export declare function handleProjectSummary(deps: ValidateProjectDeps, input: V
         };
     } | undefined;
 }>;
+export {};

package/dist/entry-tools/validate-project/cases/project-summary.js

@@ -2,7 +2,24 @@ import { readFile } from "node:fs/promises";
 import { buildEntryToolResult, createSummarySubject } from "../../response-contract.js";
 import { ERROR_CODES, createError } from "../../../errors.js";
 import { buildEarlyTasksForBlocked, buildFullTaskStatusReport } from "../internal.js";
-export async function handleProjectSummary(deps, input, detail, include) {
+// Telemetry failures must not change validation outcomes; swallow rejections
+// so a broken emitter does not abort the summary or count as a validation error.
+async function safeEmit(emitter, stage, payload) {
+    if (!emitter)
+        return;
+    try {
+        await emitter(stage, payload);
+    }
+    catch {
+        // swallow telemetry failure
+    }
+}
+export async function handleProjectSummary(deps, input, detail, include, options = {}) {
+    // Forwarded emitter for nested validators and probes; same swallow contract
+    // as safeEmit so a rejecting raw emitter cannot leak into their outcomes.
+    const wrappedEmitter = options.stageEmitter
+        ? (stage, meta) => safeEmit(options.stageEmitter, stage, meta)
+        : undefined;
     if (input.subject.kind !== "workspace") {
         throw createError({
             code: ERROR_CODES.INVALID_INPUT,
@@ -42,6 +59,10 @@ export async function handleProjectSummary(deps, input, detail, include) {
                 }
             }
         });
+        await safeEmit(options.stageEmitter, "validate-project:task-report", {
+            projectPath: input.subject.projectPath,
+            reason: "missing-version"
+        });
         const tasks = await buildEarlyTasksForBlocked(input.subject.projectPath, detail, include);
         return {
             ...baseResult,
@@ -50,11 +71,15 @@ export async function handleProjectSummary(deps, input, detail, include) {
         };
     }
     const projectPath = input.subject.projectPath;
+    const discover = input.subject.discover ?? ["mixins", "access-wideners"];
+    await safeEmit(options.stageEmitter, "validate-project:workspace-discovery", {
+        projectPath,
+        discover
+    });
     const detectedProjectVersion = input.preferProjectVersion
         ? await deps.detectProjectMinecraftVersion?.(projectPath)
         : undefined;
     const resolvedVersion = detectedProjectVersion ?? input.version;
-    const discover = input.subject.discover ?? ["mixins", "access-wideners"];
     const [mixinConfigs, accessWideners, accessTransformers] = await Promise.all([
         discover.includes("mixins")
             ? deps.discoverMixins(projectPath, input.configPaths)
@@ -102,6 +127,13 @@ export async function handleProjectSummary(deps, input, detail, include) {
                 }
             }
         });
+        await safeEmit(options.stageEmitter, "validate-project:task-report", {
+            projectPath,
+            reason: "version-unresolved",
+            mixinDiscoveryCount: mixinConfigs.length,
+            awDiscoveryCount: accessWideners.length,
+            atDiscoveryCount: accessTransformers.length
+        });
         const tasks = await buildEarlyTasksForBlocked(projectPath, detail, include, {
             mixinDiscoveryCount: mixinConfigs.length,
             awDiscoveryCount: accessWideners.length,
@@ -144,6 +176,10 @@ export async function handleProjectSummary(deps, input, detail, include) {
                 }
             }
         });
+        await safeEmit(options.stageEmitter, "validate-project:task-report", {
+            projectPath,
+            reason: "version-not-required"
+        });
         const tasks = await buildEarlyTasksForBlocked(projectPath, detail, include);
         return {
             ...baseResult,
@@ -158,8 +194,16 @@ export async function handleProjectSummary(deps, input, detail, include) {
     let partialMixins = 0;
     let invalidMixins = 0;
     let mixinCaughtErrors = 0;
-    for (const configPath of mixinConfigs) {
+    await safeEmit(options.stageEmitter, "validate-project:mixin-validation", {
+        targetTotal: mixinConfigs.length
+    });
+    for (const [mixinIndex, configPath] of mixinConfigs.entries()) {
         try {
+            await safeEmit(options.stageEmitter, "validate-project:mixin-validation", {
+                targetIndex: mixinIndex + 1,
+                targetTotal: mixinConfigs.length,
+                configPath
+            });
             const mixinResult = await deps.validateMixin({
                 input: {
                     mode: "config",
@@ -180,6 +224,8 @@ export async function handleProjectSummary(deps, input, detail, include) {
                 warningCategoryFilter: input.warningCategoryFilter,
                 treatInfoAsWarning: input.treatInfoAsWarning,
                 includeIssues: input.includeIssues
+            }, {
+                stageEmitter: wrappedEmitter
             });
             const summary = mixinResult.summary;
             validMixins += summary?.valid ?? 0;
@@ -202,8 +248,16 @@ export async function handleProjectSummary(deps, input, detail, include) {
     let validAw = 0;
     let invalidAw = 0;
     let awCaughtErrors = 0;
-    for (const awPath of accessWideners) {
+    await safeEmit(options.stageEmitter, "validate-project:access-widener-validation", {
+        targetTotal: accessWideners.length
+    });
+    for (const [awIndex, awPath] of accessWideners.entries()) {
         try {
+            await safeEmit(options.stageEmitter, "validate-project:access-widener-validation", {
+                targetIndex: awIndex + 1,
+                targetTotal: accessWideners.length,
+                filePath: awPath
+            });
             const output = await deps.validateAccessWidener({
                 content: await readFile(awPath, "utf8"),
                 version: validationVersion,
@@ -236,8 +290,16 @@ export async function handleProjectSummary(deps, input, detail, include) {
     let validAt = 0;
     let invalidAt = 0;
     let atCaughtErrors = 0;
-    for (const atPath of accessTransformers) {
+    await safeEmit(options.stageEmitter, "validate-project:access-transformer-validation", {
+        targetTotal: accessTransformers.length
+    });
+    for (const [atIndex, atPath] of accessTransformers.entries()) {
         try {
+            await safeEmit(options.stageEmitter, "validate-project:access-transformer-validation", {
+                targetIndex: atIndex + 1,
+                targetTotal: accessTransformers.length,
+                filePath: atPath
+            });
             if (!deps.validateAccessTransformer) {
                 throw createError({
                     code: ERROR_CODES.CONTEXT_UNRESOLVED,
@@ -315,6 +377,12 @@ export async function handleProjectSummary(deps, input, detail, include) {
         },
         alwaysBlocks: ["project"]
     });
+    await safeEmit(options.stageEmitter, "validate-project:task-report", {
+        projectPath,
+        mixinDiscoveryCount: mixinConfigs.length,
+        awDiscoveryCount: accessWideners.length,
+        atDiscoveryCount: accessTransformers.length
+    });
     const tasks = await buildFullTaskStatusReport(deps, {
         projectPath,
         detail,
@@ -335,7 +403,8 @@ export async function handleProjectSummary(deps, input, detail, include) {
         atDiscoveryCount: accessTransformers.length,
         atCaughtErrors,
         atCounts: { ok: validAt, invalid: invalidAt },
-        atDurationMs
+        atDurationMs,
+        stageEmitter: wrappedEmitter
     });
     return {
         ...baseResult,

package/dist/entry-tools/validate-project/internal.d.ts

@@ -1,3 +1,4 @@
+import type { StageEmitter } from "../../stage-emitter.js";
 import type { SourceMapping } from "../../types.js";
 type TaskStatus = "ok" | "skipped" | "missing" | "error";
 type TaskEntryBase = {
@@ -44,8 +45,26 @@ type TaskStatusReport = {
         };
     };
 };
+type MinecraftArtifactProbeInput = {
+    target: {
+        kind: "version";
+        value: string;
+    };
+    mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
+    sourcePriority?: "loom-first" | "maven-first";
+    projectPath?: string;
+    scope?: "vanilla" | "merged" | "loader";
+    preferProjectVersion?: boolean;
+};
+type MinecraftArtifactProbeOutput = {
+    artifactId: string;
+    mappingApplied: SourceMapping;
+    warnings?: string[];
+};
 export type ValidateProjectDeps = {
-    validateMixin: (input: Record<string, unknown>) => Promise<Record<string, unknown> & {
+    validateMixin: (input: Record<string, unknown>, options?: {
+        stageEmitter?: StageEmitter;
+    }) => Promise<Record<string, unknown> & {
         warnings?: string[];
     }>;
     validateAccessWidener: (input: {
@@ -74,21 +93,8 @@ export type ValidateProjectDeps = {
     discoverAccessWideners: (projectPath: string) => Promise<string[]>;
     discoverAccessTransformers?: (projectPath: string) => Promise<string[]>;
     detectProjectMinecraftVersion?: (projectPath: string) => Promise<string | undefined>;
-    resolveArtifact?: (input: {
-        target: {
-            kind: "version";
-            value: string;
-        };
-        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
-        sourcePriority?: "loom-first" | "maven-first";
-        projectPath?: string;
-        scope?: "vanilla" | "merged" | "loader";
-        preferProjectVersion?: boolean;
-    }) => Promise<{
-        artifactId: string;
-        mappingApplied: SourceMapping;
-        warnings?: string[];
-    }>;
+    probeMinecraftArtifact?: (input: MinecraftArtifactProbeInput) => Promise<MinecraftArtifactProbeOutput>;
+    resolveArtifact?: (input: MinecraftArtifactProbeInput) => Promise<MinecraftArtifactProbeOutput>;
 };
 export declare function runUpstreamProbes(projectPath: string): Promise<{
     workspace: TaskStatusReport["workspace.detected"];
@@ -131,5 +137,6 @@ export declare function buildFullTaskStatusReport(deps: ValidateProjectDeps, arg
         invalid: number;
     };
     atDurationMs: number;
+    stageEmitter?: StageEmitter;
 }): Promise<TaskStatusReport | undefined>;
 export {};

package/dist/entry-tools/validate-project/internal.js

@@ -126,10 +126,23 @@ async function probeLoomCacheFound(projectPath) {
         };
     }
 }
-async function probeMinecraftArtifactResolved(resolveArtifact, args) {
+async function probeMinecraftArtifactResolved(artifactProbe, args, stageEmitter) {
     const startedAt = Date.now();
+    // Stage notification kept outside the probe's try block: a telemetry
+    // failure must not be classified as ERR_ARTIFACT_PROBE_FAILED.
     try {
-        const output = await resolveArtifact({
+        await stageEmitter?.("validate-project:artifact-probe", {
+            version: args.version,
+            mapping: args.mapping ?? "obfuscated",
+            projectPath: args.projectPath,
+            scope: args.scope ?? null
+        });
+    }
+    catch {
+        // swallow telemetry failure
+    }
+    try {
+        const output = await artifactProbe({
             target: { kind: "version", value: args.version },
             mapping: args.mapping,
             sourcePriority: args.sourcePriority,
@@ -168,16 +181,18 @@ function downstreamSkipReason(report, upstream) {
     return undefined;
 }
 function buildValidationEntryWithCounts(upstream, discoveredCount, errorCount, counts, durationMs) {
+    // Real validator outcomes win over upstream skip when validators ran.
+    // The artifact probe is informational; its failure must not erase real counts.
+    if (discoveredCount > 0 || errorCount > 0) {
+        if (errorCount > 0) {
+            return { status: "error", durationMs, counts };
+        }
+        return { status: "ok", durationMs, counts };
+    }
     if (upstream) {
         return upstream;
     }
-    if (discoveredCount === 0) {
-        return { status: "missing", durationMs };
-    }
-    if (errorCount > 0) {
-        return { status: "error", durationMs, counts };
-    }
-    return { status: "ok", durationMs, counts };
+    return { status: "missing", durationMs };
 }
 function projectTaskEntry(entry, detail, include) {
     const fullDetail = detail !== "summary" && include.includes("workspace");
@@ -252,15 +267,16 @@ export async function buildFullTaskStatusReport(deps, args) {
     if (workspace.status !== "ok" || gradle.status !== "ok") {
         minecraftArtifactResolved = { status: "skipped" };
     }
-    else if (deps.resolveArtifact) {
-        minecraftArtifactResolved = await probeMinecraftArtifactResolved(deps.resolveArtifact, {
+    else if (deps.probeMinecraftArtifact ?? deps.resolveArtifact) {
+        const artifactProbe = deps.probeMinecraftArtifact ?? deps.resolveArtifact;
+        minecraftArtifactResolved = await probeMinecraftArtifactResolved(artifactProbe, {
             version: args.resolvedVersion,
             mapping: args.mapping,
             sourcePriority: args.sourcePriority,
             projectPath: args.projectPath,
             scope: args.scope,
             preferProjectVersion: args.preferProjectVersion
-        });
+        }, args.stageEmitter);
     }
     else {
         minecraftArtifactResolved = { status: "skipped" };

package/dist/entry-tools/validate-project-service.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { StageEmitter } from "../stage-emitter.js";
 import type { SourceMapping } from "../types.js";
 import { type ValidateProjectDeps } from "./validate-project/internal.js";
 export type TaskStatus = "ok" | "skipped" | "missing" | "error";
@@ -683,13 +684,16 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     include?: string[] | undefined;
 }>;
 export type ValidateProjectInput = z.infer<typeof validateProjectSchema>;
+export type ValidateProjectExecuteOptions = {
+    stageEmitter?: StageEmitter;
+};
 export declare function discoverWorkspaceMixins(projectPath: string, configPaths?: string[]): Promise<string[]>;
 export declare function discoverWorkspaceAccessWideners(projectPath: string): Promise<string[]>;
 export declare function discoverWorkspaceAccessTransformers(projectPath: string): Promise<string[]>;
 export declare class ValidateProjectService {
     private readonly deps;
     constructor(deps: ValidateProjectDeps);
-    execute(input: ValidateProjectInput): Promise<Record<string, unknown> & {
+    execute(input: ValidateProjectInput, options?: ValidateProjectExecuteOptions): Promise<Record<string, unknown> & {
         warnings?: string[];
     }>;
 }

package/dist/entry-tools/validate-project-service.js

@@ -263,7 +263,7 @@ export class ValidateProjectService {
     constructor(deps) {
         this.deps = deps;
     }
-    async execute(input) {
+    async execute(input, options = {}) {
         const detail = resolveDetail(input.detail);
         const include = resolveInclude(input.include);
         switch (input.task) {
@@ -274,7 +274,7 @@ export class ValidateProjectService {
             case "access-transformer":
                 return handleAccessTransformer(this.deps, input, detail, include);
             case "project-summary":
-                return handleProjectSummary(this.deps, input, detail, include);
+                return handleProjectSummary(this.deps, input, detail, include, options);
         }
     }
 }

package/dist/index.js

@@ -129,7 +129,7 @@ const analyzeModService = new AnalyzeModService({
     remapModJar: (input) => remapModJar(input, config)
 });
 const validateProjectService = new ValidateProjectService({
-    validateMixin: (input) => sourceService.validateMixin(input),
+    validateMixin: (input, options) => sourceService.validateMixin(input, options),
     validateAccessWidener: (input) => sourceService.validateAccessWidener(input),
     validateAccessTransformer: (input) => sourceService.validateAccessTransformer(input),
     discoverMixins: discoverWorkspaceMixins,
@@ -150,7 +150,8 @@ const validateProjectService = new ValidateProjectService({
             mappingApplied: output.mappingApplied,
             warnings: output.warnings
         };
-    }
+    },
+    probeMinecraftArtifact: (input) => sourceService.probeMinecraftArtifact(input)
 });
 const manageCacheService = new ManageCacheService({
     registry: createCacheRegistry({
@@ -413,7 +414,9 @@ server.tool("compare-minecraft", "High-level v3 entry tool for version compariso
 registerToolSchema("compare-minecraft", compareMinecraftSchema);
 server.tool("analyze-mod", "High-level v3 entry 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)));
 registerToolSchema("analyze-mod", analyzeModSchema);
-server.tool("validate-project", "High-level v3 entry tool for project summary, direct mixin validation, and access widener/access transformer validation.", validateProjectShape, { readOnlyHint: true }, async (args) => runTool("validate-project", args, validateProjectSchema, async (input) => validateProjectService.execute(input)));
+server.tool("validate-project", "High-level v3 entry 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)
+})));
 registerToolSchema("validate-project", validateProjectSchema);
 server.tool("manage-cache", "High-level v3 entry tool for cache summaries, listing, verification, previewed mutation, and explicit apply operations.", manageCacheShape, { readOnlyHint: false }, async (args) => runTool("manage-cache", args, manageCacheSchema, async (input) => manageCacheService.execute(input)));
 registerToolSchema("manage-cache", manageCacheSchema);

package/dist/mapping-service.d.ts

@@ -31,7 +31,11 @@ export declare class MappingService {
     private provenanceForPath;
     /**
      * Probe the mapping graph health for a given version.
-     * Returns availability of mojang mappings, tiny mappings, and member remap paths.
+     *
+     * `tinyMappingsAvailable` reports whether Tiny is sufficient for the
+     * request: `true` when Tiny is not required (obfuscated/mojang) or is
+     * loaded, `false` only when intermediary/yarn was requested and Tiny is
+     * unavailable.
      */
     checkMappingHealth(input: {
         version: string;

package/dist/mapping-service.js

@@ -926,11 +926,16 @@ export class MappingService {
     }
     /**
      * Probe the mapping graph health for a given version.
-     * Returns availability of mojang mappings, tiny mappings, and member remap paths.
+     *
+     * `tinyMappingsAvailable` reports whether Tiny is sufficient for the
+     * request: `true` when Tiny is not required (obfuscated/mojang) or is
+     * loaded, `false` only when intermediary/yarn was requested and Tiny is
+     * unavailable.
      */
     async checkMappingHealth(input) {
         const priority = mappingPriorityFromInput(this.config.mappingSourcePriority, input.sourcePriority);
         const degradations = [];
+        const needsTinyMappings = input.requestedMapping === "intermediary" || input.requestedMapping === "yarn";
         if (isUnobfuscatedVersion(input.version)) {
             const requestFulfillable = input.requestedMapping === "obfuscated" || input.requestedMapping === "mojang";
             if (!requestFulfillable) {
@@ -938,19 +943,19 @@ export class MappingService {
             }
             return {
                 mojangMappingsAvailable: true,
-                tinyMappingsAvailable: false,
+                tinyMappingsAvailable: !needsTinyMappings,
                 memberRemapAvailable: requestFulfillable,
                 degradations
             };
         }
         let graph;
         try {
-            graph = await this.loadGraph(input.version, priority, "full");
+            graph = await this.loadGraph(input.version, priority, needsTinyMappings ? "full" : "obfuscated-mojang-only");
         }
         catch {
             return {
                 mojangMappingsAvailable: false,
-                tinyMappingsAvailable: false,
+                tinyMappingsAvailable: !needsTinyMappings,
                 memberRemapAvailable: false,
                 degradations: ["Mapping graph could not be loaded."]
             };
@@ -967,7 +972,7 @@ export class MappingService {
         if (!mojangAvailable) {
             degradations.push("Mojang client mappings are not available for this version.");
         }
-        if (!tinyAvailable) {
+        if (needsTinyMappings && !tinyAvailable) {
             degradations.push("No intermediary/yarn tiny mappings were found for this version.");
         }
         // Check if member remap path exists (requestedMapping → obfuscated)
@@ -984,7 +989,7 @@ export class MappingService {
         }
         return {
             mojangMappingsAvailable: mojangAvailable,
-            tinyMappingsAvailable: tinyAvailable,
+            tinyMappingsAvailable: needsTinyMappings ? tinyAvailable : true,
             memberRemapAvailable,
             degradations
         };

package/dist/source/artifact-resolver.d.ts

@@ -1,5 +1,5 @@
 import type { SourceService } from "../source-service.js";
-import type { ArtifactContentsSummary, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
+import type { ArtifactContentsSummary, ProbeMinecraftArtifactInput, ProbeMinecraftArtifactOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
 import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactScope, ArtifactTargetKind, ResolvedSourceArtifact, RuntimeValidationProvenance, SourceMapping } from "../types.js";
 import type { WorkspaceProjectLoader } from "../workspace-mapping-service.js";
 export type VersionSourceDiscovery = {
@@ -33,6 +33,7 @@ export declare function discoverVersionSourceJar(_svc: SourceService, input: {
     version: string;
     projectPath?: string;
 }): Promise<VersionSourceDiscovery>;
+export declare function probeMinecraftArtifact(svc: SourceService, input: ProbeMinecraftArtifactInput): Promise<ProbeMinecraftArtifactOutput>;
 export declare function discoverAccessWidenerRuntimeCandidates(_svc: SourceService, input: {
     version: string;
     projectPath?: string;

package/dist/source/artifact-resolver.js

@@ -7,8 +7,9 @@ import { log } from "../logger.js";
 import { applyMappingPipeline } from "../mapping-pipeline-service.js";
 import { parseCoordinate } from "../maven-resolver.js";
 import { resolveMojangTinyFile } from "../mojang-tiny-mapping-service.js";
+import { artifactSignatureFromFile } from "../path-resolver.js";
 import { detectFabricLikeInputNamespace, listJavaEntries } from "../source-jar-reader.js";
-import { resolveSourceTarget as resolveSourceTargetInternal } from "../source-resolver.js";
+import { artifactIdForJar, resolveSourceTarget as resolveSourceTargetInternal } from "../source-resolver.js";
 import { resolveTinyRemapperJar } from "../tiny-remapper-resolver.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
@@ -209,6 +210,102 @@ export async function discoverVersionSourceJar(_svc, input) {
         selectedHasMinecraftNamespace: selected?.hasMinecraftNamespace
     };
 }
+export async function probeMinecraftArtifact(svc, input) {
+    let value = input.target.value.trim();
+    const warnings = [];
+    const requestedMapping = normalizeMapping(input.mapping);
+    if (input.preferProjectVersion && input.projectPath) {
+        const detected = await svc.workspaceMappingService.detectProjectMinecraftVersion(input.projectPath);
+        if (detected && detected !== value) {
+            warnings.push(`Overriding version "${value}" with project version "${detected}" from gradle.properties.`);
+        }
+        value = detected ?? value;
+    }
+    if (!value) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "target.value must be non-empty.",
+            details: { target: input.target }
+        });
+    }
+    const versionJar = await svc.versionService.resolveVersionJar(value);
+    const resolvedVersion = versionJar.version;
+    const runtimeNamesUnobfuscated = isUnobfuscatedVersion(resolvedVersion);
+    warnings.push(`Resolved Minecraft ${versionJar.version} from ${versionJar.clientJarUrl}.`);
+    let effectiveMapping = requestedMapping;
+    if ((requestedMapping === "intermediary" || requestedMapping === "yarn") &&
+        runtimeNamesUnobfuscated) {
+        warnings.push(`Version ${resolvedVersion} is unobfuscated; ${requestedMapping} mappings are not applicable. Using the obfuscated namespace label for the deobfuscated runtime names.`);
+        effectiveMapping = "obfuscated";
+    }
+    if ((effectiveMapping === "intermediary" || effectiveMapping === "yarn") &&
+        !runtimeNamesUnobfuscated) {
+        throw createError({
+            code: ERROR_CODES.MAPPING_NOT_APPLIED,
+            message: `Lightweight artifact probe cannot verify ${effectiveMapping} mapping availability without running the full resolver.`,
+            details: {
+                requestedMapping: effectiveMapping,
+                version: resolvedVersion,
+                nextAction: "Use a direct validation task for mapping-sensitive checks, or use mapping=obfuscated for the project-summary artifact probe."
+            }
+        });
+    }
+    if (effectiveMapping === "mojang" && !runtimeNamesUnobfuscated) {
+        // Match validate-mixin's resolve stage: omitted scope defaults to vanilla,
+        // avoiding a workspace-wide source-jar scan that validate-mixin would skip.
+        const effectiveScope = input.scope ?? "vanilla";
+        if (effectiveScope === "vanilla") {
+            throw createError({
+                code: ERROR_CODES.MAPPING_NOT_APPLIED,
+                message: "Lightweight artifact probe cannot verify mojang mapping with scope=vanilla on obfuscated runtime versions.",
+                details: {
+                    requestedMapping: effectiveMapping,
+                    version: resolvedVersion,
+                    nextAction: "Retry with scope=merged and projectPath so the probe can use a Loom source jar, or use mapping=obfuscated."
+                }
+            });
+        }
+        const versionSourceDiscovery = await svc.discoverVersionSourceJar({
+            version: resolvedVersion,
+            projectPath: input.projectPath
+        });
+        if (!versionSourceDiscovery.selectedSourceJarPath) {
+            throw createError({
+                code: ERROR_CODES.MAPPING_NOT_APPLIED,
+                message: "Lightweight artifact probe cannot verify mojang mapping without a source-backed Loom artifact.",
+                details: {
+                    requestedMapping: effectiveMapping,
+                    version: resolvedVersion,
+                    searchedPaths: versionSourceDiscovery.searchedPaths,
+                    candidateArtifacts: versionSourceDiscovery.candidateArtifacts,
+                    nextAction: "Use mapping=obfuscated for project-summary, or run a direct validation task when full source resolution is required."
+                }
+            });
+        }
+        const selectedSourceJarPath = versionSourceDiscovery.selectedSourceJarPath;
+        const sourceSignature = artifactSignatureFromFile(selectedSourceJarPath).signature;
+        const artifactId = artifactIdForJar("jar", selectedSourceJarPath, sourceSignature);
+        warnings.push(`Resolved source-backed artifact from Loom cache candidate: ${selectedSourceJarPath}.`);
+        if (versionSourceDiscovery.selectedHasMinecraftNamespace === false) {
+            warnings.push(`Source coverage does not include net.minecraft for ${selectedSourceJarPath}; class lookups may fall back to the binary artifact.`);
+        }
+        if (!hasExactVersionToken(selectedSourceJarPath, value)) {
+            warnings.push(`Requested version "${value}" but resolved source jar does not contain exact version string: ${selectedSourceJarPath}`);
+        }
+        return {
+            artifactId,
+            mappingApplied: "mojang",
+            ...(warnings.length > 0 ? { warnings } : {})
+        };
+    }
+    const binarySignature = artifactSignatureFromFile(versionJar.jarPath).signature;
+    const artifactId = artifactIdForJar("jar", versionJar.jarPath, `${binarySignature}:decompile`);
+    return {
+        artifactId,
+        mappingApplied: effectiveMapping,
+        ...(warnings.length > 0 ? { warnings } : {})
+    };
+}
 export async function discoverAccessWidenerRuntimeCandidates(_svc, input) {
     const normalizedProjectPath = normalizeOptionalProjectPath(input.projectPath);
     const normalizedProjectPathLower = normalizedProjectPath

package/dist/source/indexer.js

@@ -323,6 +323,23 @@ export async function ingestIfNeeded(svc, resolved) {
         touchCacheMetrics(svc, resolved.artifactId, touchedAt);
         return;
     }
+    const inflight = svc.state.inflightArtifactIngests.get(resolved.artifactId);
+    if (inflight) {
+        await inflight;
+        return;
+    }
+    const ingestPromise = rebuildMissingArtifactIndex(svc, resolved, reason);
+    svc.state.inflightArtifactIngests.set(resolved.artifactId, ingestPromise);
+    try {
+        await ingestPromise;
+    }
+    finally {
+        if (svc.state.inflightArtifactIngests.get(resolved.artifactId) === ingestPromise) {
+            svc.state.inflightArtifactIngests.delete(resolved.artifactId);
+        }
+    }
+}
+async function rebuildMissingArtifactIndex(svc, resolved, reason) {
     svc.metrics.recordArtifactCacheMiss();
     svc.metrics.recordReindex();
     log("info", "index.rebuild.start", {

package/dist/source/state.d.ts

@@ -14,6 +14,11 @@ export declare class SourceServiceState {
      * tiny-remapper run.
      */
     readonly inflightRemaps: Map<string, Promise<string>>;
+    /**
+     * Process-local artifact ingest jobs keyed by artifactId. This collapses
+     * concurrent class source/member lookups inside one MCP server process.
+     */
+    readonly inflightArtifactIngests: Map<string, Promise<void>>;
     readonly lru: LruList<{
         totalContentBytes: number;
         updatedAt: string;

package/dist/source/state.js

@@ -14,6 +14,11 @@ export class SourceServiceState {
      * tiny-remapper run.
      */
     inflightRemaps = new Map();
+    /**
+     * Process-local artifact ingest jobs keyed by artifactId. This collapses
+     * concurrent class source/member lookups inside one MCP server process.
+     */
+    inflightArtifactIngests = new Map();
     lru = new LruList();
 }
 //# sourceMappingURL=state.js.map

package/dist/source-resolver.d.ts

@@ -1,5 +1,6 @@
 import type { Config, MappingVariant, ResolvedSourceArtifact, SourceTargetInput } from "./types.js";
 export type { MappingVariant } from "./types.js";
+export declare function artifactIdForJar(inputKind: string, artifactPath: string, signature: string, suffix?: string, mappingVariant?: MappingVariant): string;
 export interface ResolveSourceTargetOptions {
     allowDecompile: boolean;
     preferBinaryOnly?: boolean;

package/dist/source-resolver.js

@@ -133,7 +133,7 @@ async function resolveGradleCacheCoordinateCandidate(coordinate) {
 function resolveRemoteBinaryCandidate(coordinate, repos) {
     return buildRemoteBinaryUrls(repos, coordinate);
 }
-function artifactIdForJar(inputKind, artifactPath, signature, suffix, mappingVariant = "pass") {
+export function artifactIdForJar(inputKind, artifactPath, signature, suffix, mappingVariant = "pass") {
     const parts = [inputKind, artifactPath, signature, suffix ?? "source"];
     if (mappingVariant === "mojang-remapped") {
         parts.push("mojang-remapped");

package/dist/source-service.d.ts

@@ -50,6 +50,22 @@ export type ResolveArtifactOutput = {
     warnings: string[];
     sampleEntries?: string[];
 };
+export type ProbeMinecraftArtifactInput = {
+    target: {
+        kind: "version";
+        value: string;
+    };
+    mapping?: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+    projectPath?: string;
+    scope?: ArtifactScope;
+    preferProjectVersion?: boolean;
+};
+export type ProbeMinecraftArtifactOutput = {
+    artifactId: string;
+    mappingApplied: SourceMapping;
+    warnings?: string[];
+};
 export type ArtifactContentsSummary = {
     sourceKind: "source-jar" | "decompiled-binary";
     indexedContentKinds: string[];
@@ -508,6 +524,7 @@ export declare class SourceService {
         workspaceContextCache?: WorkspaceContextCache;
     });
     resolveArtifact(input: ResolveArtifactInput): Promise<ResolveArtifactOutput>;
+    probeMinecraftArtifact(input: ProbeMinecraftArtifactInput): Promise<ProbeMinecraftArtifactOutput>;
     synthesizeWorkspaceTarget(input: ResolveArtifactInput, workspace: import("./types.js").WorkspaceTargetInput): ReturnType<typeof workspaceTarget.synthesizeWorkspaceTarget>;
     synthesizeDependencyTarget(input: ResolveArtifactInput, dep: import("./types.js").DependencyTargetInput): ReturnType<typeof workspaceTarget.synthesizeDependencyTarget>;
     loadOrDetectWorkspaceContext(projectPath: string): ReturnType<typeof workspaceTarget.loadOrDetectWorkspaceContext>;

package/dist/source-service.js

@@ -67,6 +67,9 @@ export class SourceService {
     async resolveArtifact(input) {
         return artifactResolver.resolveArtifact(this, input);
     }
+    async probeMinecraftArtifact(input) {
+        return artifactResolver.probeMinecraftArtifact(this, input);
+    }
     async synthesizeWorkspaceTarget(input, workspace) {
         return workspaceTarget.synthesizeWorkspaceTarget(this, input, workspace);
     }

package/docs/README-ja.md

@@ -158,6 +158,8 @@ stdio トランスポートは、改行区切り形式と `Content-Length` フ
 - `trace-symbol-lifecycle` の `symbol` には `Class.method` を指定します。厳密なオーバーロード指定は別フィールドの `descriptor` を使ってください。
 - ワークスペースのソースカバレッジが部分的な場合でも、バニラクラスを確認できます。`inspect-minecraft task="list-files"` は、その場合に部分的な結果とフォローアップガイダンスを返します。
 - `analyze-mod` と `validate-project` は、オブジェクト形式の `subject` と正規の `include` グループを要求します。古い文字列形式の `subject` やドメイン名形式の `include` には `ERR_INVALID_INPUT` と、再試行しやすい `suggestedCall` を返します。
+- `validate-mixin` と `validate-project` は、`obfuscated` / `mojang` 検証では `mapping-health` を軽量に保ちます。`intermediary` / `yarn` 名前空間を要求しない限り、完全な Tiny マッピンググラフは読み込みません。
+- `validate-project task="project-summary"` の `tasks["minecraft.artifact.resolved"]` は軽量なアーティファクト probe です。probe 状態を返すためだけに Minecraft のデコンパイルやソースインデックス再構築は行いません。追加の `tasks` フィールドを省きたい場合は `VALIDATE_PROJECT_TASKS_OFF=1` を使います。
 
 ### あるバージョンの Minecraft ソースを確認する
 

package/docs/tool-reference.md

@@ -91,6 +91,7 @@ Workspace detection is memoised in a process-resident `WorkspaceContextCache` (1
 - `validate-mixin` summary-first workflows should combine `includeIssues=false`, `reportMode="compact"`, and `warningMode="aggregated"`.
 - `validate-mixin` top-level failures expose `failedStage` as a first-class field on the serialized `error` envelope (alongside `code`, `hints`, `suggestedCall`) — one of `"input-validation" | "resolve" | "mapping-health" | "parse" | "target-lookup"`. Branch on that before inspecting `message` to recover automatically (e.g. retry `resolve` failures with `scope="vanilla"`, retry `target-lookup` failures with a different `mapping`). Nested errors that already carry a `failedStage` are preserved so upstream tags (e.g. from `resolve-artifact`) surface unchanged.
 - `validate-mixin` per-result `quickSummary` appends `Scope fell back from "<requested>" to "<applied>" (<reason>).` when `provenance.scopeFallback` is set and `Mapping health degraded: <degradations>.` when `toolHealth.overallHealthy === false`. Clean validations keep the original one-line summary; the extra notes only attach when the pipeline actually fell back or detected a degraded mapping.
+- `mapping-health` stays lightweight for `obfuscated` and `mojang` requests. It avoids full Tiny mapping graph loads unless the caller requests `intermediary` or `yarn`, where Tiny namespace availability is part of the health check.
 - `validate-mixin` runs each stage (`resolve` / `mapping-health` / `parse` / `target-lookup`) against an independent soft-deadline. When the `target-lookup` stage exhausts its budget mid-loop, completed targets stay in `targetOutcomes` with `status: "ok"` (and `slowTarget: true` plus `elapsedMs` when the per-target soft cap was exceeded) while remaining targets land as `status: "deferred-budget"`. The summary then carries `targetsDeferredBudget` and `degradedReason: "stage-budget"`, and `validationStatus` is promoted to `"partial"`. If the budget is exhausted before the first iteration, `targetOutcomes` stays empty, `targetsDeferredBudget` is omitted, and `degradedReason: "stage-budget-pre-target"`.
 - Empty Mixin configs are treated as warning-only discovery results with `summary.total=0` instead of invalid input; malformed JSON still returns `ERR_INVALID_INPUT`.
 
@@ -148,6 +149,8 @@ Common input fields:
 - `compact: boolean` (default `true`) — applies the same per-tool projection that the corresponding single tool's `compact: true` mode applies. When `false`, per-entry `result` is byte-identical to the single tool's `compact: false` output.
 - Per-tool shared inputs (`target`, `mapping`, `projectPath`, `version`, etc.) follow the same shape as the matching single tool.
 
+Resource behavior: `concurrency` limits per-entry dispatch for one batch call. Within one MCP server process, entries or calls that need the same artifact index or decompiled fallback share the in-flight rebuild by `artifactId`. Separate MCP server processes sharing the same cache are not coordinated by this process-local guard.
+
 Common output:
 
 ```json
@@ -272,14 +275,14 @@ These environment variables are read once at worker startup and provide rollback
   | `workspace.detected` | A `gradle.properties`, `settings.gradle{,.kts}`, or `build.gradle{,.kts}` file exists at `subject.projectPath`. | `evidence: ["gradle.properties", ...]` lists the gradle files that were found. | `missing` when no gradle files exist; `error` when the filesystem read itself failed. |
   | `gradle.readable` | `gradle.properties` can be read and the workspace's gradle build scripts are enumerable. | `propertiesPath` and `buildScripts[]` (relative paths). | `skipped` when `workspace.detected` is not `ok`; `missing` when no gradle files at all; `error` on parse / read failure. |
   | `loom.cache.found` | A Loom (Fabric / Quilt) cache directory under the workspace or `GRADLE_USER_HOME` exists. Independent of `workspace.detected` so callers can detect a global Loom cache even on non-gradle workspaces. | `cachePath` of the first matching directory. | `missing` when none of the candidate roots exist; `error` on filesystem failure. |
-  | `minecraft.artifact.resolved` | `resolve-artifact` with `target: { kind: "version", value: <resolvedVersion> }` succeeds against the workspace context. | `artifactId` and `mappingApplied`. | `skipped` when `workspace.detected` or `gradle.readable` is not `ok`; `error` when `resolve-artifact` throws (carries `error.code` and `error.detail`). |
-  | `mixins.validated` | At least one `*.mixins.json` file was discovered AND every per-config validation completed without throwing. | `counts: { ok, partial, invalid }` (validation outcomes from `validate-mixin`). | `skipped` when any upstream probe is non-`ok`; `missing` when discovery returned 0 paths; `error` when one or more per-config validations threw. |
-  | `accessWideners.validated` | At least one Access Widener file was discovered AND every validation completed without throwing. | `counts: { ok, invalid }`. | `skipped` / `missing` / `error` follow the same rules as `mixins.validated`. |
-  | `accessTransformers.validated` | At least one Access Transformer file was discovered AND every validation completed without throwing. | `counts: { ok, invalid }`. | Same as `mixins.validated`. |
+  | `minecraft.artifact.resolved` | A lightweight artifact metadata probe can locate `target: { kind: "version", value: <resolvedVersion> }` against the workspace context. The probe does not decompile Minecraft or rebuild the source index. | `artifactId` and `mappingApplied`. | `skipped` when `workspace.detected` or `gradle.readable` is not `ok`; `error` when the lightweight probe cannot verify the artifact or requested mapping without full resolution (carries `error.code` and `error.detail`). |
+  | `mixins.validated` | At least one `*.mixins.json` file was discovered AND every per-config validation completed without throwing. | `counts: { ok, partial, invalid }` (validation outcomes from `validate-mixin`). | `error` when any per-config validation threw (still emits `counts`); `skipped` when discovery was empty AND `workspace.detected` / `gradle.readable` blocked; `missing` when discovery returned 0 paths and upstream probes were `ok`. A failed `minecraft.artifact.resolved` does not flip executed validators to `skipped`. |
+  | `accessWideners.validated` | At least one Access Widener file was discovered AND every validation completed without throwing. | `counts: { ok, invalid }`. | Same rules as `mixins.validated`. |
+  | `accessTransformers.validated` | At least one Access Transformer file was discovered AND every validation completed without throwing. | `counts: { ok, invalid }`. | Same rules as `mixins.validated`. |
 
-  Status precedence (top wins): `skipped` (upstream blocked) > `missing` (no items) > `error` (item-level caught) > `ok`.
+  Status precedence (top wins): `error` (item-level caught) > `ok` (validators ran) > `skipped` (upstream env blocked AND no items ran) > `missing` (no items, upstream `ok`).
 
-  Output projection: with `detail: "summary"` (or when `include` does not contain `"workspace"`), each `tasks[*]` entry is slimmed to `status`, `error?`, and `warnings?` only — `evidence` / `buildScripts` / `counts` / `propertiesPath` / `cachePath` / `artifactId` / `mapping` / `durationMs` are stripped. With `detail: "full"` (or `"standard"`) AND `include` containing `"workspace"`, every sub-field is preserved. Set `VALIDATE_PROJECT_TASKS_OFF=1` at process start to omit the field entirely (legacy shape).
+  Output projection: with `detail: "summary"` (or when `include` does not contain `"workspace"`), each `tasks[*]` entry is slimmed to `status`, `error?`, and `warnings?` only — `evidence` / `buildScripts` / `counts` / `propertiesPath` / `cachePath` / `artifactId` / `mapping` / `durationMs` are stripped. With `detail: "full"` (or `"standard"`) AND `include` containing `"workspace"`, every sub-field is preserved. Set `VALIDATE_PROJECT_TASKS_OFF=1` at process start to omit the field entirely (legacy shape). Use `resolve-artifact` directly when a follow-up source lookup needs a fully indexed artifact.
 - `validate-access-widener` keeps vanilla validation when `projectPath`, `scope`, and `preferProjectVersion` are omitted. Supplying Loom workspace context switches it into runtime-aware mode, which returns `provenance` and per-entry runtime access evidence without changing the existing summary shape.
 - `validate-access-transformer` accepts `atNamespace="srg" | "mojang" | "obfuscated"`. When `projectPath` points at a Forge or NeoForge workspace, the tool can infer that namespace automatically and validate against loader/runtime artifacts for `scope="loader"`.
 - Start with `manage-cache` for cache inventory and safe cleanup. Use `executionMode="preview"` before `executionMode="apply"`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "4.1.0",
-  "description": "MCP server with utilities for Minecraft modding workflows",
+  "version": "4.1.1",
+  "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",
   "types": "dist/index.d.ts",
@@ -36,9 +36,21 @@
     "validate": "npm run check && npm test && npm run test:coverage && npm run test:perf"
   },
   "keywords": [
+    "claude",
+    "fabric",
+    "forge",
     "mcp",
+    "mcp-server",
     "minecraft",
-    "modding"
+    "minecraft-modding",
+    "mixin",
+    "modding",
+    "model-context-protocol",
+    "mojang-mappings",
+    "neoforge",
+    "nodejs",
+    "typescript",
+    "yarn-mappings"
   ],
   "author": "adhi-jp",
   "license": "MIT",