@adhisang/minecraft-modding-mcp 4.1.0 → 4.2.0

package/dist/tool-schemas.js

@@ -16,6 +16,7 @@ export const ENCODE_COMPRESSIONS = ["none", "gzip"];
 export const nonEmptyString = z.string().trim().min(1);
 export const optionalNonEmptyString = z.string().trim().min(1).optional();
 export const optionalPositiveInt = z.number().int().positive().optional();
+export const gradleUserHomeSchema = optionalNonEmptyString.describe("Gradle User Home to use for Loom/Gradle cache lookups instead of the MCP process GRADLE_USER_HOME.");
 // Optional descriptor: "" and whitespace-only strings are normalized to undefined so that
 // tools with signatureMode="name-only" can accept "caller omitted descriptor" inputs whether
 // the caller passed an empty string or omitted the field entirely. Malformed descriptors are
@@ -98,6 +99,7 @@ export const resolveArtifactShape = {
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     allowDecompile: z.boolean().default(true),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
+    gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
     strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
@@ -114,6 +116,7 @@ export const getClassSourceShape = {
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     allowDecompile: z.boolean().default(true),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
+    gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
     strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
@@ -149,6 +152,7 @@ export const getClassMembersShape = {
     memberPattern: optionalNonEmptyString,
     maxMembers: optionalPositiveInt.describe("default 500, max 5000"),
     projectPath: optionalNonEmptyString,
+    gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
     strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
@@ -174,6 +178,7 @@ export const verifyMixinTargetShape = {
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     projectPath: optionalNonEmptyString.describe("Workspace root path for target.kind=workspace and Loom cache assistance."),
+    gradleUserHome: gradleUserHomeSchema,
     target: resolveArtifactTargetSchema.describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
@@ -196,6 +201,7 @@ export const batchClassSourceShape = {
     sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().optional(),
     projectPath: optionalNonEmptyString,
+    gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional(),
     preferProjectVersion: z.boolean().optional(),
     strictVersion: z.boolean().optional(),
@@ -250,6 +256,7 @@ export const batchClassMembersShape = {
     sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().optional(),
     projectPath: optionalNonEmptyString,
+    gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional(),
     preferProjectVersion: z.boolean().optional(),
     strictVersion: z.boolean().optional(),
@@ -278,6 +285,7 @@ export const batchSymbolExistsShape = {
     sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().optional(),
     projectPath: optionalNonEmptyString,
+    gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional(),
     preferProjectVersion: z.boolean().optional(),
     strictVersion: z.boolean().optional(),
@@ -310,6 +318,7 @@ export const batchMappingsShape = {
     version: nonEmptyString.describe("Minecraft version shared by every entry. Per-entry version is rejected; this batch shape is intentionally single-version."),
     sourcePriority: mappingSourcePrioritySchema.optional(),
     projectPath: optionalNonEmptyString,
+    gradleUserHome: gradleUserHomeSchema,
     concurrency: z.number().int().min(1).max(8).optional(),
     failFast: z.boolean().optional(),
     compact: z.boolean().optional(),
@@ -329,6 +338,7 @@ export const searchClassSourceShape = {
     cursor: optionalNonEmptyString,
     queryNamespace: sourceMappingSchema.optional().describe("Namespace of the query. When set and intent='symbol' with a fully-qualified class name, the query is translated through find-mapping before searching the artifact namespace. Ignored for text/path intents (warning surfaced)."),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first. Used only when queryNamespace triggers translation."),
+    gradleUserHome: gradleUserHomeSchema,
     compact: z.boolean().default(false).describe("When true, strip the artifactContents summary and empty fields from the response. Default false.")
 };
 export const searchClassSourceSchema = z.object(searchClassSourceShape).superRefine((value, ctx) => {
@@ -361,6 +371,7 @@ export const traceSymbolLifecycleShape = {
     toVersion: optionalNonEmptyString,
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    gradleUserHome: gradleUserHomeSchema,
     includeSnapshots: z.boolean().default(false),
     maxVersions: optionalPositiveInt.default(120).describe("max 400"),
     includeTimeline: z.boolean().default(false)
@@ -372,6 +383,7 @@ export const diffClassSignaturesShape = {
     toVersion: nonEmptyString,
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    gradleUserHome: gradleUserHomeSchema,
     includeFullDiff: z.boolean().default(true).describe("When false, omit from/to snapshots from modified entries and keep only key+changed")
 };
 export const diffClassSignaturesSchema = z.object(diffClassSignaturesShape);
@@ -384,6 +396,7 @@ export const findMappingShape = {
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    gradleUserHome: gradleUserHomeSchema,
     signatureMode: z.enum(["exact", "name-only"]).default("name-only")
         .describe("exact: descriptor required for kind=method; name-only (default): match by owner+name only"),
     disambiguation: z
@@ -463,6 +476,7 @@ export const resolveMethodMappingExactShape = {
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    gradleUserHome: gradleUserHomeSchema,
     maxCandidates: optionalPositiveInt.default(5).describe("Limit returned candidates (default 5, max 200). Raise when you need the full candidate list."),
     compact: z.boolean().default(true).describe("Omit top-level empty arrays, null/undefined values, and empty objects from the response. "
         + "Also omit redundant candidates array for single full-confidence exact-match resolutions. "
@@ -505,6 +519,7 @@ export const getClassApiMatrixShape = {
     classNameMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     includeKinds: classApiKindsSchema.optional().describe("comma-separated: class,field,method"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    gradleUserHome: gradleUserHomeSchema,
     maxRows: optionalPositiveInt.describe("Limit returned rows (max 5000)")
 };
 export const getClassApiMatrixSchema = z.object(getClassApiMatrixShape);
@@ -517,6 +532,7 @@ export const resolveWorkspaceSymbolShape = {
     descriptor: optionalDescriptorString.describe("JVM descriptor. Empty strings are treated as omitted."),
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    gradleUserHome: gradleUserHomeSchema,
     maxCandidates: optionalPositiveInt.default(5).describe("Limit returned candidates for field/method lookups (default 5, max 200). Raise when you need the full candidate list."),
     compact: z.boolean().default(true).describe("Omit top-level empty arrays, null/undefined values, and empty objects from the response. "
         + "Also omit redundant candidates array for single full-confidence exact-match resolutions. "
@@ -589,6 +605,7 @@ export const checkSymbolExistsShape = {
     descriptor: optionalDescriptorString.describe("required for kind=method unless signatureMode=name-only. Empty strings are treated as omitted."),
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
+    gradleUserHome: gradleUserHomeSchema,
     nameMode: classNameModeSchema.default("fqcn").describe("fqcn | auto"),
     signatureMode: z.enum(["exact", "name-only"]).default("exact")
         .describe("exact: require descriptor for methods; name-only: match by owner+name only"),
@@ -711,6 +728,7 @@ export const validateMixinShape = {
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
+    gradleUserHome: gradleUserHomeSchema,
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
     minSeverity: z.enum(["error", "warning", "all"]).default("all")
         .describe("'error'=errors only, 'warning'=errors+warnings, 'all'=everything"),
@@ -738,6 +756,7 @@ export const validateAccessWidenerShape = {
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted runtime validation"),
+    gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().default(false)
         .describe("When true, detect MC version from gradle.properties and override version")
@@ -749,6 +768,7 @@ export const validateAccessTransformerShape = {
     atNamespace: z.enum(["srg", "mojang", "obfuscated"]).optional().describe("srg | mojang | obfuscated"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Forge/NeoForge runtime validation"),
+    gradleUserHome: gradleUserHomeSchema,
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().default(false)
         .describe("When true, detect MC version from gradle.properties and override version")

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 ソースを確認する
 
@@ -250,7 +252,7 @@ stdio トランスポートは、改行区切り形式と `Content-Length` フ
 
 ### トップレベルワークフローツール
 
-<!-- BEGIN GENERATED TOOL TABLE: v3-entry-tools -->
+<!-- BEGIN GENERATED TOOL TABLE: top-level-workflow-tools -->
 | ツール | 役割 |
 | --- | --- |
 | `inspect-minecraft` | バージョン、アーティファクト、クラス、ファイル、ソース本文、ワークスペース文脈の調査フローをまとめて扱う |
@@ -259,7 +261,7 @@ stdio トランスポートは、改行区切り形式と `Content-Length` フ
 | `analyze-mod` | Mod メタデータの要約、Mod コードのデコンパイル / 検索、クラスソース確認、リマップのプレビュー / 実行を扱う |
 | `validate-project` | ワークスペース要約と、Mixin / Access Widener / Access Transformer の直接検証を行う |
 | `manage-cache` | キャッシュの一覧、検証、クリーンアップ / 再構築のプレビュー / 実行を行う |
-<!-- END GENERATED TOOL TABLE: v3-entry-tools -->
+<!-- END GENERATED TOOL TABLE: top-level-workflow-tools -->
 
 ### ソース探索
 

package/docs/tool-reference.md

@@ -38,6 +38,7 @@ Start here when you are not sure which tool to reach for. In every row, the left
 - 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.
 - 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.
 - `get-class-members` also returns an additive `status: "ok" | "members_unavailable" | "partial"` field so callers can distinguish "really 0 members" from "extraction unavailable":
 
@@ -91,6 +92,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 +150,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
@@ -271,15 +275,15 @@ 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`. |
+  | `loom.cache.found` | A Loom (Fabric / Quilt) cache directory exists under the workspace, `gradleUserHome`, or the process `GRADLE_USER_HOME`. It is 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` | 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"`.
@@ -385,6 +389,8 @@ Use `resolve-workspace-symbol` when you need compile-visible names from actual G
 
 Path-based overrides treat blank values and the literal strings `undefined` and `null` as unset, so accidental client serialization does not create `./undefined` or `./null` cache roots or broken JAR override paths.
 
+`gradleUserHome` is a per-call path option, not an environment variable. It takes precedence over the MCP process `GRADLE_USER_HOME` for Loom source jars, Loom Tiny mappings, loader/runtime jars, and `validate-project` Loom cache probes. `projectPath` search roots still apply for workspace-local caches.
+
 ### Core and Repository Discovery
 
 | Variable | Default | Description |

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.2.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",
   "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",