@adhisang/minecraft-modding-mcp 4.1.1 → 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

@@ -252,7 +252,7 @@ stdio トランスポートは、改行区切り形式と `Content-Length` フ
 
 ### トップレベルワークフローツール
 
-<!-- BEGIN GENERATED TOOL TABLE: v3-entry-tools -->
+<!-- BEGIN GENERATED TOOL TABLE: top-level-workflow-tools -->
 | ツール | 役割 |
 | --- | --- |
 | `inspect-minecraft` | バージョン、アーティファクト、クラス、ファイル、ソース本文、ワークスペース文脈の調査フローをまとめて扱う |
@@ -261,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":
 
@@ -274,7 +275,7 @@ 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. |
+  | `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`. |
@@ -388,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,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "4.1.1",
+  "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",