@adhisang/minecraft-modding-mcp 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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).
 
+## [1.2.0] - 2026-03-05
+
+### Added
+- New `find-class` tool to resolve simple or fully-qualified class names to concrete source paths inside an indexed artifact.
+- `resolve-artifact` / `get-class-source`: `scope` (`vanilla`/`merged`/`loader`), `preferProjectVersion`, `strictVersion`, `projectPath` parameters for workspace-driven resolution.
+- `get-class-source`: `mode` (`metadata`/`snippet`/`full`), `maxChars`, `outputFile` parameters for token-efficient source retrieval.
+- `search-class-source`: `queryMode` (`auto`/`token`/`literal`) controls FTS5 vs substring scan behavior.
+- `get-mod-class-source`: `maxLines`, `maxChars`, `outputFile` truncation parameters matching `get-class-source` behavior.
+- `find-mapping`: `disambiguation` hints (`ownerHint`, `descriptorHint`) to narrow ambiguous candidates; `ambiguityReasons` in `status=ambiguous` responses.
+- `get-class-api-matrix`: `ambiguousRowCount` when ambiguity fallback is applied.
+- `check-symbol-exists`: `nameMode` (`fqcn`/`auto`) and `signatureMode` (`exact`/`name-only`) parameters.
+- `analyze-mod-jar`: `jarKind` (`binary`/`source`/`mixed`) in response.
+- `resolve-artifact`: `sampleEntries` when a source JAR is resolved.
+- `validate-mixin`: major enhancements — `sourcePath`, `sourcePaths`, `mixinConfigPath` (with `sourceRoot`/`sourceRoots[]` for batch auto-discovery), `explain` mode with `explanation`/`suggestedCall` on issues, `resolvedMembers` tracking, `category`/`issueOrigin` classification, `structuredWarnings` with severity, `warningCategoryFilter`, `treatInfoAsWarning`, `reportMode`, `preferProjectMapping`, `provenance` with `resolutionNotes`, `toolHealth`, `confidenceScore`, batch `processingErrors`/`totalValidationErrors`/`totalValidationWarnings`.
+- Error details: structured `suggestedCall` (`{ tool, params }`) for agent-driven recovery on `get-class-source` and `resolve-artifact` errors.
+
+### Fixed
+- `validate-mixin`: JVM descriptor false positives — method references with descriptors (e.g. `playerTouch(L...;)V`) are now stripped before comparison.
+- `validate-mixin`: array-form `method = {"m1", "m2"}` parsing, `@Accessor(value = "name")` syntax, `@Accessor`/`@Invoker` parse failure escalation to `issues[]`.
+- `validate-mixin`: `@Invoker` validation now checks methods only (not fields), preventing false negatives.
+- `validate-mixin`: mapping fallback failures reported as `target-mapping-failed` warning (not `target-not-found` error).
+- `validate-mixin`: multi-line annotation handling between `@Shadow`/`@Accessor` and declarations; inline annotations stripped from declaration lines.
+- `validate-mixin`: `@Mixin(targets = "...")`/`targets = {"a", "b"}` string forms supported; simple `@Mixin` class names resolved via imports.
+- `validate-mixin`: Fabric Loom split source sets and multi-module `sourceRoots` auto-discovery across common/fabric/neoforge/forge/quilt main+client paths.
+- `validate-mixin`: parser supports `$` in names, FQN/generic/array/wildcard member signatures, `default`/`synchronized` modifiers, `interface` declarations.
+- `validate-mixin`: `sourcePath` normalized with host/WSL path conversion; bytecode signature members remapped to requested mapping before validation.
+- `validate-mixin`: `hideUncertain`/`minSeverity` filtering now recomputes `summary.parseWarnings` from filtered issues.
+- Vineflower flags now passed before positional `<input-jar> <output-dir>` arguments, fixing false `ERR_DECOMPILER_FAILED` errors.
+- Vineflower decompilation retries with fallback flag profiles on failure.
+- `get-artifact-file`: UTF-8 boundary-safe byte truncation prevents malformed replacement characters.
+- Version approximation detection avoids prefix false positives (e.g. `1.21.1` vs `1.21.10`).
+- Classifier source-jar resolution correctly picks `<artifact>-<version>-<classifier>-sources.jar`.
+- Default cache dir to `~/.cache/minecraft-modding-mcp` when `MCP_CACHE_DIR` unset.
+- Cursor validation: invalid non-empty cursors now throw `ERR_INVALID_INPUT` instead of silently returning first page.
+- `check-symbol-exists`: `ERR_INVALID_INPUT` for invalid symbol combinations before evaluating mapping availability.
+- `resolve-artifact` mapping failures for version targets include actionable diagnostics (`searchedPaths`, `candidateArtifacts`, `recommendedCommand`).
+- `search-mod-source` detects source-only jars and searches `.java` entries directly without decompilation.
+- `CLASS_NOT_FOUND` / `MAPPING_NOT_APPLIED` errors include improved scope/context fields and recovery guidance.
+- Mojang proguard mapping: JVM descriptor parsing fixes.
+
+### Changed
+- Lazy `SourceService` initialization — deferred until first tool/resource access, reducing cold-start latency during MCP handshake.
+- Eagerly init `SourceService` during MCP handshake idle time for faster first-request response.
+- Codecov workflow temporarily disabled.
+
+### Performance
+- Avoid duplicate UTF-8 decode during truncation.
+- Eager `SourceService` init during handshake idle time.
+
 ## [1.1.1] - 2026-03-02
 
 ### Fixed

package/README.md

@@ -13,7 +13,7 @@
 
 It lets you explore decompiled Minecraft source, convert symbol names across four naming namespaces (`official`, `mojang`, `intermediary`, `yarn`), analyze and decompile Fabric/Forge/NeoForge mod JARs, validate Mixin and Access Widener files, read and patch NBT data, and query generated registry snapshots — all through a structured tool and resource interface designed for Claude Desktop, VS Code, and other MCP-capable clients.
 
-**28 tools** | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
+**29 tools** | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
 
 ## Features
 
@@ -57,6 +57,8 @@ codex mcp list
 
 The stdio transport auto-detects both newline-delimited and `Content-Length` framing, so Codex and newline-based MCP clients can use the same server command.
 
+The server now lazily initializes heavyweight source/index services on first MCP request, reducing initial process startup latency for clients that only perform handshake/tool discovery.
+
 #### Gemini CLI
 
 Add the following to `~/.gemini/settings.json`:
@@ -114,7 +116,7 @@ Generate LCOV output for Codecov upload:
 pnpm test:coverage:lcov
 ```
 
-GitHub Actions upload workflow: `.github/workflows/codecov.yml` (triggered on `v*` tags and manual dispatch).
+GitHub Actions upload workflow: `.github/workflows/codecov.yml` (temporarily disabled; when enabled, it runs on `v*` tags and manual dispatch).
 
 ### MCP Client Configuration
 
@@ -176,10 +178,11 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading/s
 | Tool | Purpose | Key Inputs | Key Outputs |
 | --- | --- | --- | --- |
 | `list-versions` | List available Minecraft versions from Mojang manifest + local cache | `includeSnapshots?`, `limit?` | `result.latest`, `result.releases[]`, `meta.warnings[]` |
-| `resolve-artifact` | Resolve source artifact from `version` / `jar` / `coordinate` | `targetKind`, `targetValue`, `mapping?`, `sourcePriority?`, `allowDecompile?` | `artifactId`, `origin`, `mappingApplied`, `qualityFlags[]`, `adjacentSourceCandidates?`, `warnings[]` |
-| `get-class-source` | Get class source by `artifactId` or resolve target on demand, with line filtering | `className`, `artifactId?`, `targetKind?`, `targetValue?`, `startLine?`, `endLine?`, `maxLines?` | `sourceText`, `returnedRange`, `truncated`, `artifactId`, mapping/provenance metadata |
-| `get-class-members` | Get class fields/methods/constructors from bytecode | `className`, `artifactId?`, `targetKind?`, `targetValue?`, `mapping?`, `access?`, `includeInherited?`, `maxMembers?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `warnings[]` |
-| `search-class-source` | Search indexed class source for symbols/text/path | `artifactId`, `query`, `intent?`, `match?`, `packagePrefix?`, `fileGlob?`, `symbolKind?`, `snippetLines?`, `includeDefinition?`, `includeOneHop?`, `limit?`, `cursor?` | `hits[]`, `relations?`, `nextCursor?`, `totalApprox`, `mappingApplied` |
+| `resolve-artifact` | Resolve source artifact from `version` / `jar` / `coordinate` | `targetKind`, `targetValue`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `artifactId`, `origin`, `mappingApplied`, `qualityFlags[]`, `adjacentSourceCandidates?`, `sampleEntries?`, `warnings[]` |
+| `find-class` | Resolve simple or fully-qualified class names inside an artifact | `className`, `artifactId`, `limit?` | `matches[]`, `total`, `warnings[]` |
+| `get-class-source` | Get class source by `artifactId` or resolve target on demand (`mode=metadata` by default) | `className`, `mode?`, `artifactId?`, `targetKind?`, `targetValue?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?`, `startLine?`, `endLine?`, `maxLines?`, `maxChars?`, `outputFile?` | `mode`, `sourceText`, `returnedRange`, `truncated`, `charsTruncated?`, `outputFile?`, `artifactId`, mapping/provenance metadata |
+| `get-class-members` | Get class fields/methods/constructors from bytecode | `className`, `artifactId?`, `targetKind?`, `targetValue?`, `mapping?`, `access?`, `includeInherited?`, `maxMembers?`, `strictVersion?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `warnings[]` |
+| `search-class-source` | Search indexed class source for symbols/text/path | `artifactId`, `query`, `intent?`, `match?`, `packagePrefix?`, `fileGlob?`, `symbolKind?`, `snippetLines?`, `includeDefinition?`, `includeOneHop?`, `queryMode?`, `limit?`, `cursor?` | `hits[]`, `relations?`, `nextCursor?`, `totalApprox`, `mappingApplied` |
 | `get-artifact-file` | Read full source file with byte guard | `artifactId`, `filePath`, `maxBytes?` | `content`, `contentBytes`, `truncated`, `mappingApplied` |
 | `list-artifact-files` | List indexed source file paths with cursor pagination | `artifactId`, `prefix?`, `limit?`, `cursor?` | `items[]`, `nextCursor?`, `mappingApplied` |
 | `index-artifact` | Rebuild index metadata for an existing artifact | `artifactId`, `force?` | `reindexed`, `reason`, `counts`, `indexedAt`, `durationMs` |
@@ -200,11 +203,11 @@ Tools for converting symbol names between namespaces and checking symbol existen
 
 | Tool | Purpose | Key Inputs | Key Outputs |
 | --- | --- | --- | --- |
-| `find-mapping` | Find mapping candidates for class/field/method symbols between namespaces | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `targetMapping`, `sourcePriority?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `provenance?`, `meta.warnings[]` |
+| `find-mapping` | Find mapping candidates for class/field/method symbols between namespaces | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `disambiguation?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `ambiguityReasons?`, `provenance?`, `meta.warnings[]` |
 | `resolve-method-mapping-exact` | Resolve one method mapping with strict owner+name+descriptor matching | `version`, `kind` (`method`), `name`, `owner`, `descriptor`, `sourceMapping`, `targetMapping`, `sourcePriority?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `provenance?`, `meta.warnings[]` |
-| `get-class-api-matrix` | Show one class API as a mapping matrix (`official/mojang/intermediary/yarn`) | `version`, `className`, `classNameMapping`, `includeKinds?`, `sourcePriority?` | `classIdentity`, `rows[]`, `meta.warnings[]` |
+| `get-class-api-matrix` | Show one class API as a mapping matrix (`official/mojang/intermediary/yarn`) | `version`, `className`, `classNameMapping`, `includeKinds?`, `sourcePriority?` | `classIdentity`, `rows[]`, `ambiguousRowCount?`, `meta.warnings[]` |
 | `resolve-workspace-symbol` | Resolve compile-visible symbol names for a Gradle workspace (`build.gradle/.kts`) | `projectPath`, `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `workspaceDetection`, `meta.warnings[]` |
-| `check-symbol-exists` | Strict symbol presence check for class/field/method | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `meta.warnings[]` |
+| `check-symbol-exists` | Strict symbol presence check for class/field/method | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?`, `nameMode?`, `signatureMode?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `meta.warnings[]` |
 
 ### NBT Utilities
 
@@ -222,9 +225,9 @@ Tools for extracting metadata from mod JARs, decompiling mod source, searching m
 
 | Tool | Purpose | Key Inputs | Key Outputs |
 | --- | --- | --- | --- |
-| `analyze-mod-jar` | Extract mod metadata/dependencies/entrypoints from mod JAR | `jarPath`, `includeClasses?` | `modId`, `loader`, `dependencies`, `entrypoints`, `mixinConfigs`, class stats |
+| `analyze-mod-jar` | Extract mod metadata/dependencies/entrypoints from mod JAR | `jarPath`, `includeClasses?` | `modId`, `loader`, `jarKind`, `dependencies`, `entrypoints`, `mixinConfigs`, class stats |
 | `decompile-mod-jar` | Decompile mod JAR and optionally return one class source | `jarPath`, `className?` | `outputDir`, `fileCount`, `files?`, `source?`, `warnings[]` |
-| `get-mod-class-source` | Read one class source from decompiled mod cache | `jarPath`, `className` | `className`, `content`, `totalLines`, `warnings[]` |
+| `get-mod-class-source` | Read one class source from decompiled mod cache | `jarPath`, `className`, `maxLines?`, `maxChars?`, `outputFile?` | `className`, `content`, `totalLines`, `truncated?`, `charsTruncated?`, `outputFilePath?`, `warnings[]` |
 | `search-mod-source` | Search decompiled mod source by class/method/field/content | `jarPath`, `query`, `searchType?`, `limit?` | `hits[]`, `totalHits`, `truncated`, `warnings[]` |
 | `remap-mod-jar` | Remap a Fabric mod JAR from intermediary to yarn/mojang names | `inputJar`, `targetMapping`, `mcVersion?`, `outputJar?` | `outputJar`, `mcVersion`, `fromMapping`, `targetMapping`, `resolvedTargetNamespace`, `warnings[]` |
 
@@ -234,7 +237,7 @@ Tools for validating Mixin source and Access Widener files against a target Mine
 
 | Tool | Purpose | Key Inputs | Key Outputs |
 | --- | --- | --- | --- |
-| `validate-mixin` | Parse/validate Mixin source against target Minecraft version | `source`, `version`, `mapping?`, `sourcePriority?` | `valid`, `issues[]`, `warnings[]`, `summary` |
+| `validate-mixin` | Parse/validate Mixin source against target Minecraft version | `source?`, `sourcePath?`, `sourcePaths?`, `mixinConfigPath?`, `sourceRoot?`, `sourceRoots?`, `version`, `mapping?`, `sourcePriority?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `minSeverity?`, `hideUncertain?`, `warningMode?`, `preferProjectMapping?`, `reportMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `explain?` | single: `valid`, `issues[]`, `warnings[]`, `structuredWarnings?`, `aggregatedWarnings?`, `summary` (incl. `parseWarnings`), `unfilteredSummary?`, `provenance?`, `resolvedMembers?`, `toolHealth?`, `confidenceScore?`; batch: `results[]`, `summary`, `toolHealth?` |
 | `validate-access-widener` | Parse/validate Access Widener content against target version | `content`, `version`, `mapping?`, `sourcePriority?` | `valid`, `issues[]`, `warnings[]`, `summary` |
 
 ### Registry & Diagnostics
@@ -250,13 +253,40 @@ Tools for querying generated registry data and inspecting server runtime state.
 
 `get-class-source` requires either `artifactId` or `targetKind`+`targetValue`. Supplying both is rejected.
 `get-class-members` requires either `artifactId` or `targetKind`+`targetValue`, and needs a binary jar (`binaryJarPath`) to read `.class` entries.
+`validate-mixin` requires exactly one of `source`, `sourcePath`, `sourcePaths`, or `mixinConfigPath`. `sourcePath`/`sourcePaths[]` are normalized for host/WSL path formats before file reads. `mixinConfigPath` reads a mixin config JSON and auto-discovers source files for batch validation (`sourceRoots[]` or `sourceRoot` override lookup roots; otherwise common roots like `src/main/java`, `src/client/java`, `common/src/{main,client}/java`, `fabric/src/{main,client}/java`, `neoforge/src/{main,client}/java`, `forge/src/{main,client}/java`, and `quilt/src/{main,client}/java` are auto-detected from configured mixin classes).
+`validate-mixin` single-file responses include `provenance.resolutionNotes?` when mapping fallback occurs.
+`validate-mixin` validates `@Invoker` targets against methods only and `@Accessor` targets against fields only.
+`validate-mixin` parser supports both `.class` literal targets and `targets = "..."` / `targets = {"a", "b"}` string forms.
+`validate-mixin` parser handles multi-line annotations between `@Shadow`/`@Accessor` and declarations, and strips inline annotations from declaration lines.
+`validate-mixin` distinguishes `target-mapping-failed` (warning, uncertain) from `target-not-found` (error) when class mapping fails.
+`validate-mixin` issues and `structuredWarnings` include `category` (`mapping`, `configuration`, `validation`, `resolution`, or `parse`) to distinguish setup/tooling/parser limits from real validation errors.
+`validate-mixin` supports post-filtering with `minSeverity`, `hideUncertain`, and `warningCategoryFilter`; `treatInfoAsWarning=false` suppresses info-level entries in `structuredWarnings`.
+`validate-mixin` single-file responses include `resolvedMembers?` tracking each member's resolution status (`resolved` or `not-found`).
+`validate-mixin` with `explain=true` enriches each issue with `explanation` and `suggestedCall` (tool + params) for agent-driven recovery.
+`validate-mixin` batch `summary` uses `processingErrors` (exception count), `totalValidationErrors`, and `totalValidationWarnings` instead of the ambiguous `errors` field.
+`resolve-artifact` with `targetKind=version` uses Loom cache discovery from `projectPath` only when `mapping=mojang`; mapping failures include `searchedPaths`, `candidateArtifacts`, and `recommendedCommand` in error details.
+`resolve-artifact` supports `scope` (`vanilla`/`merged`/`loader`) and optional `preferProjectVersion=true` to override `targetValue` from `gradle.properties` (`minecraft_version`, `mc_version`, `minecraftVersion`) when `targetKind=version`.
+`resolve-artifact` includes `sampleEntries` only when a source JAR is resolved; decompile-only paths leave it unset.
+`find-class` returns type symbols (`class`/`interface`/`enum`/`record`) only; fully-qualified lookups are filtered by exact FQCN/file path to avoid false negatives when many classes share the same simple name.
 `search-class-source` uses `limit: 20` by default; `snippetLines` defaults to `8` and is clamped to `1..80`; `includeDefinition` and `includeOneHop` default to `false`.
+`search-class-source` `queryMode` controls text search strategy: `auto` (default) uses indexed token search with literal fallback for separator queries, `token` keeps indexed token behavior only, and `literal` uses substring scan only.
 `search-class-source` with `match=regex` enforces `query.length <= 200` and a strict result cap of `100`.
+`get-artifact-file` byte truncation now preserves UTF-8 character boundaries, preventing replacement-character (`�`) corruption when `maxBytes` cuts through multibyte text.
 `search-class-source` `fileGlob` supports `*`, `**`, and `?`; recursive patterns such as `net/minecraft/**/*.java` are supported.
 `get-class-source` fallback matching enforces package compatibility and returns `ERR_CLASS_NOT_FOUND` when only name-colliding classes from other packages exist.
+`get-class-source` mode defaults to `metadata` (symbol outline only); `mode=snippet` auto-sets `maxLines=200` when no line range/max is provided; `mode=full` returns the entire source. `outputFile` writes the selected text and returns the file path in `outputFile`.
+Decompile fallback for `resolve-artifact`/`get-class-source` now invokes Vineflower with flags before positional `<input-jar> <output-dir>` arguments to avoid false `ERR_DECOMPILER_FAILED` outcomes on valid jars.
 `resolve-artifact` with `targetKind=jar` only auto-adopts the exact sibling `"<jar-basename>-sources.jar"`. Other adjacent `*-sources.jar` files are returned as `adjacentSourceCandidates` info only and are never auto-selected.
+For `targetKind=coordinate` with a classifier (`group:artifact:version:classifier`), local Maven source lookup checks `<artifact>-<version>-<classifier>-sources.jar` first and then `<artifact>-<version>-sources.jar`.
 Mod tool `jarPath` inputs are normalized to a canonical local `.jar` file path before existence checks, cache keying, and processing.
 `search-mod-source` enforces `query.length <= 200` and `limit <= 200`.
+`search-mod-source` detects source-only jars and searches `.java` entries directly without decompilation.
+`get-mod-class-source` supports `maxLines`, `maxChars`, and `outputFile` with truncation behavior aligned to `get-class-source`; when `outputFile` is set, the written file reflects applied truncation.
+`find-mapping` returns `ambiguityReasons` when `status=ambiguous` to explain why candidates could not be uniquely resolved.
+`get-class-api-matrix` returns `ambiguousRowCount` when one or more rows required ambiguity fallback.
+`check-symbol-exists` defaults to strict FQCN class inputs; set `nameMode=auto` to allow short class names (ambiguous matches return `status=ambiguous`).
+`check-symbol-exists` supports `signatureMode=name-only` to match methods by owner+name without requiring a descriptor. Single match returns `resolved`; multiple overloads return `ambiguous` with all candidates.
+`check-symbol-exists` always validates input shape first and returns `ERR_INVALID_INPUT` for invalid symbol combinations, even when mapping data is unavailable.
 `remap-mod-jar` requires Java to be installed and only supports Fabric/Quilt mods.
 
 ## Resources
@@ -299,7 +329,8 @@ All tools return exactly one of:
     "targetKind": "version",
     "targetValue": "1.21.10",
     "mapping": "official",
-    "allowDecompile": true
+    "allowDecompile": true,
+    "projectPath": "/path/to/mod/workspace"
   }
 }
 ```
@@ -420,7 +451,10 @@ Get a high-level summary of what changed between two releases, including class a
     "name": "a.b.C",
     "sourceMapping": "official",
     "targetMapping": "mojang",
-    "sourcePriority": "loom-first"
+    "sourcePriority": "loom-first",
+    "disambiguation": {
+      "ownerHint": "net.minecraft"
+    }
   }
 }
 ```
@@ -501,6 +535,20 @@ Get a high-level summary of what changed between two releases, including class a
 }
 ```
 
+#### Check class existence by short name (`nameMode=auto`)
+```json
+{
+  "tool": "check-symbol-exists",
+  "arguments": {
+    "version": "1.21.10",
+    "kind": "class",
+    "name": "Blocks",
+    "nameMode": "auto",
+    "sourceMapping": "mojang"
+  }
+}
+```
+
 ### NBT Utilities
 
 #### Decode Java NBT base64 to typed JSON
@@ -638,6 +686,24 @@ Check a Mixin class source for correctness against a target Minecraft version:
 }
 ```
 
+#### Validate multiple Mixin files (batch)
+
+Run the same validation settings against multiple Mixin source files:
+
+```json
+{
+  "tool": "validate-mixin",
+  "arguments": {
+    "sourcePaths": [
+      "/path/to/PlayerMixin.java",
+      "/path/to/WorldMixin.java"
+    ],
+    "version": "1.21.10",
+    "mapping": "yarn"
+  }
+}
+```
+
 #### Validate Access Widener
 
 Check an Access Widener file for valid entries against the target version:
@@ -723,7 +789,7 @@ Check server performance counters, cache sizes, and latency snapshots:
 `find-mapping` supports lookup across `official`, `mojang`, `intermediary`, and `yarn`.
 
 Symbol query inputs use `kind` + `name` + optional `owner`/`descriptor`:
-- class: `kind=class`, `name=a.b.C` (FQCN only)
+- class: `kind=class`, `name=a.b.C` (default FQCN). For existence checks only, `nameMode=auto` allows short names like `C`.
 - field: `kind=field`, `owner=a.b.C`, `name=fieldName`
 - method: `kind=method`, `owner=a.b.C`, `name=methodName`, `descriptor=(I)V`
 
@@ -737,6 +803,7 @@ Symbol query inputs use `kind` + `name` + optional `owner`/`descriptor`:
 Method descriptor precision is best on Tiny-backed paths (`intermediary`/`yarn`). For `official <-> mojang`, Mojang `client_mappings` do not carry JVM descriptors, so descriptor queries may fallback to name matching and emit a warning.
 
 Use `resolve-method-mapping-exact` when candidate ranking is not enough and the workflow needs strict `owner+name+descriptor` certainty.
+Use `find-mapping` `disambiguation.ownerHint` / `disambiguation.descriptorHint` to narrow ambiguous candidate sets.
 Use `resolve-workspace-symbol` when you need compile-visible names from actual Gradle Loom mappings in a workspace.
 
 ## Environment Variables
@@ -745,7 +812,7 @@ Use `resolve-workspace-symbol` when you need compile-visible names from actual G
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `MCP_CACHE_DIR` | `.cache/minecraft-modding-mcp` | Cache root for downloads and SQLite |
+| `MCP_CACHE_DIR` | `~/.cache/minecraft-modding-mcp` | Cache root for downloads and SQLite |
 | `MCP_SQLITE_PATH` | `<cacheDir>/source-cache.db` | SQLite database path |
 | `MCP_SOURCE_REPOS` | Maven Central + Fabric + Forge + NeoForge | Comma-separated Maven repository URLs |
 | `MCP_LOCAL_M2` | `~/.m2/repository` | Local Maven repository path |

package/dist/config.d.ts

@@ -1,6 +1,6 @@
 import type { Config } from "./types.js";
 declare const DEFAULTS: {
-    readonly cacheDir: ".cache/minecraft-modding-mcp";
+    readonly cacheDir: "~/.cache/minecraft-modding-mcp";
     readonly sourceRepos: readonly ["https://repo1.maven.org/maven2", "https://maven.fabricmc.net", "https://maven.minecraftforge.net", "https://maven.neoforged.net/releases"];
     readonly localM2Path: "~/.m2/repository";
     readonly indexedSearchEnabled: true;

package/dist/config.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 import { normalizePathForHost } from "./path-converter.js";
 const DEFAULTS = {
-    cacheDir: ".cache/minecraft-modding-mcp",
+    cacheDir: "~/.cache/minecraft-modding-mcp",
     sourceRepos: [
         "https://repo1.maven.org/maven2",
         "https://maven.fabricmc.net",

package/dist/decompiler/vineflower.d.ts

@@ -4,6 +4,7 @@ export interface DecompileResult {
         filePath: string;
         content: string;
     }>;
+    decompileProfile?: string;
 }
 interface DecompileBinaryOptions {
     vineflowerJarPath?: string;

package/dist/decompiler/vineflower.js

@@ -1,11 +1,16 @@
 import { access, constants } from "node:fs/promises";
-import { mkdirSync, readdirSync, statSync } from "node:fs";
+import { mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, join, relative, sep } from "node:path";
 import { createError, ERROR_CODES, isAppError } from "../errors.js";
 import { assertJavaAvailable, runJavaProcess } from "../java-process.js";
 import { log } from "../logger.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
+const VINEFLOWER_FLAG_PROFILES = [
+    { label: "default", flags: ["-din=1", "-rbr=1", "-dgs=1"] },
+    { label: "relaxed", flags: ["-din=1", "-rbr=0", "-dgs=0"] },
+    { label: "safe", flags: ["-din=0", "-rbr=0", "-dgs=0"] },
+];
 function emitDecompileLog(event, details) {
     log(event === "decompile.error" ? "error" : "info", event, details);
 }
@@ -83,10 +88,14 @@ function decompileOutputDir(cacheDir, binaryJarPath, signature) {
     const digest = createHash("sha256").update(binaryJarPath).update(signature).digest("hex");
     return join(cacheDir, "decompiled", digest);
 }
-async function runVineflower(vineflowerJarPath, binaryJarPath, outputDir, timeoutMs) {
+function clearOutputDir(dir) {
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+}
+async function runVineflower(vineflowerJarPath, binaryJarPath, outputDir, timeoutMs, flags = VINEFLOWER_FLAG_PROFILES[0].flags) {
     const result = await runJavaProcess({
         jarPath: vineflowerJarPath,
-        args: [binaryJarPath, outputDir, "-din=1", "-rbr=1", "-dgs=1"],
+        args: [...flags, binaryJarPath, outputDir],
         timeoutMs,
         normalizePathArgs: true
     });
@@ -97,8 +106,8 @@ async function runVineflower(vineflowerJarPath, binaryJarPath, outputDir, timeou
             details: {
                 binaryJarPath,
                 outputDir,
-                code: result.exitCode,
-                stdout: result.stdoutTail,
+                exitCode: result.exitCode,
+                stdoutTail: result.stdoutTail,
                 stderrTail: result.stderrTail
             }
         });
@@ -145,31 +154,71 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
                 };
             }
         }
-        await runVineflower(options.vineflowerJarPath, normalizedBinaryJarPath, outputDir, timeoutMs);
-        const javaFileNames = await collectJavaFiles(outputDir);
-        if (javaFileNames.length === 0) {
-            throw createError({
-                code: ERROR_CODES.DECOMPILER_FAILED,
-                message: "No Java files were produced by decompilation.",
-                details: { binaryJarPath: normalizedBinaryJarPath, outputDir }
-            });
+        const profilesAttempted = [];
+        let lastDecompileError;
+        for (const profile of VINEFLOWER_FLAG_PROFILES) {
+            profilesAttempted.push(profile.label);
+            try {
+                if (profilesAttempted.length > 1) {
+                    clearOutputDir(outputDir);
+                    emitDecompileLog("decompile.retry", {
+                        binaryJarPath: normalizedBinaryJarPath,
+                        profile: profile.label,
+                        attempt: profilesAttempted.length
+                    });
+                }
+                await runVineflower(options.vineflowerJarPath, normalizedBinaryJarPath, outputDir, timeoutMs, profile.flags);
+                const javaFileNames = await collectJavaFiles(outputDir);
+                if (javaFileNames.length === 0) {
+                    throw createError({
+                        code: ERROR_CODES.DECOMPILER_FAILED,
+                        message: "No Java files were produced by decompilation.",
+                        details: {
+                            binaryJarPath: normalizedBinaryJarPath,
+                            outputDir,
+                            producedJavaCount: 0,
+                            profile: profile.label
+                        }
+                    });
+                }
+                const javaFiles = await Promise.all(javaFileNames.map(async (candidate) => {
+                    const abs = join(outputDir, candidate);
+                    return {
+                        filePath: normalizeOutputPath(outputDir, abs),
+                        content: await readFileTreeText(abs)
+                    };
+                }));
+                emitDecompileLog("decompile.done", {
+                    durationMs: Date.now() - startedAt,
+                    artifactIdCandidate: options.artifactIdCandidate,
+                    javaFileCount: javaFiles.length,
+                    profile: profile.label
+                });
+                return {
+                    outputDir,
+                    javaFiles,
+                    decompileProfile: profile.label
+                };
+            }
+            catch (retryError) {
+                if (isAppError(retryError) && retryError.code !== ERROR_CODES.DECOMPILER_FAILED) {
+                    throw retryError;
+                }
+                lastDecompileError = retryError;
+            }
         }
-        const javaFiles = await Promise.all(javaFileNames.map(async (candidate) => {
-            const abs = join(outputDir, candidate);
-            return {
-                filePath: normalizeOutputPath(outputDir, abs),
-                content: await readFileTreeText(abs)
-            };
-        }));
-        emitDecompileLog("decompile.done", {
-            durationMs: Date.now() - startedAt,
-            artifactIdCandidate: options.artifactIdCandidate,
-            javaFileCount: javaFiles.length
-        });
-        return {
-            outputDir,
-            javaFiles
-        };
+        throw isAppError(lastDecompileError)
+            ? createError({
+                code: ERROR_CODES.DECOMPILER_FAILED,
+                message: `Decompilation failed after trying all flag profiles.`,
+                details: {
+                    binaryJarPath: normalizedBinaryJarPath,
+                    outputDir,
+                    profilesAttempted,
+                    stderrTail: extractStderrTail(lastDecompileError)
+                }
+            })
+            : lastDecompileError;
     }
     catch (error) {
         emitDecompileLog("decompile.error", {