@adhisang/minecraft-modding-mcp 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,11 +5,69 @@ 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
+- `search-class-source` now safely supports recursive `fileGlob` patterns such as `**` without regex construction failures.
+- `get-class-source` now rejects package-incompatible fallback matches and preserves canonical inner-class (`Outer.Inner`) lookup support.
+
 ## [1.1.0] - 2026-03-01
 
 ### Changed
 - Migrate stdio transport from mcp-use to @modelcontextprotocol/sdk.
 
+### Fixed
+- Restore Codex startup handshake compatibility by accepting both newline-delimited and `Content-Length` stdio framing.
+
 ### Documentation
 - Add Quick Start setup for Claude Code, OpenAI Codex CLI, and Gemini CLI.
 

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
 
@@ -55,6 +55,10 @@ codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
 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`:
@@ -112,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
 
@@ -174,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` |
@@ -198,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
 
@@ -220,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[]` |
 
@@ -232,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
@@ -248,11 +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
@@ -295,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"
   }
 }
 ```
@@ -416,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"
+    }
   }
 }
 ```
@@ -497,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
@@ -634,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:
@@ -719,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`
 
@@ -733,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
@@ -741,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 |
@@ -782,7 +853,7 @@ Use `resolve-workspace-symbol` when you need compile-visible names from actual G
 | Component | Technology |
 | --- | --- |
 | Runtime | Node.js 22+ (native `node:sqlite`) |
-| Transport | stdio (MCP standard) |
+| Transport | stdio (MCP standard, auto-detects newline + `Content-Length` framing) |
 | Storage | SQLite — artifact metadata, source index, mapping cache |
 | Decompilation | [Vineflower](https://github.com/Vineflower/vineflower) (auto-downloaded) |
 | Remapping | [tiny-remapper](https://github.com/FabricMC/tiny-remapper) (requires Java) |

package/dist/cli.js

@@ -1,22 +1,7 @@
 #!/usr/bin/env node
 import { startServer } from "./index.js";
-function keepProcessAliveUntilStdinCloses() {
-    return new Promise((resolve) => {
-        const keepAlive = setInterval(() => { }, 1 << 30);
-        const release = () => {
-            clearInterval(keepAlive);
-            resolve();
-        };
-        if (process.stdin.destroyed) {
-            release();
-            return;
-        }
-        process.stdin.once("end", release);
-        process.stdin.once("close", release);
-    });
-}
 startServer()
-    .then(() => keepProcessAliveUntilStdinCloses())
+    .then(() => undefined)
     .catch((err) => {
     console.error("Fatal: server failed to start", err);
     process.exit(1);

package/dist/compat-stdio-transport.d.ts

@@ -0,0 +1,27 @@
+import { type JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+type StdioReadable = NodeJS.ReadStream;
+type StdioWritable = NodeJS.WriteStream;
+export declare class CompatStdioServerTransport {
+    private readonly stdin;
+    private readonly stdout;
+    private started;
+    private closed;
+    private mode;
+    private buffer;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(stdin?: StdioReadable, stdout?: StdioWritable);
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+    private readonly handleData;
+    private readonly handleStreamError;
+    private readonly handleStreamClosed;
+    private emitCloseOnce;
+    private processReadBuffer;
+    private detectMode;
+    private readLineDelimitedMessage;
+    private readContentLengthMessage;
+}
+export {};

package/dist/compat-stdio-transport.js

@@ -0,0 +1,217 @@
+import process from "node:process";
+import { JSONRPCMessageSchema } from "@modelcontextprotocol/sdk/types.js";
+function findHeaderBoundary(buffer) {
+    const crlfBoundary = buffer.indexOf("\r\n\r\n");
+    if (crlfBoundary !== -1) {
+        return { index: crlfBoundary, delimiterBytes: 4 };
+    }
+    const lfBoundary = buffer.indexOf("\n\n");
+    if (lfBoundary !== -1) {
+        return { index: lfBoundary, delimiterBytes: 2 };
+    }
+    return undefined;
+}
+function parseJsonRpcMessage(json) {
+    return JSONRPCMessageSchema.parse(JSON.parse(json));
+}
+function asError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+export class CompatStdioServerTransport {
+    stdin;
+    stdout;
+    started = false;
+    closed = false;
+    mode = "unknown";
+    buffer = Buffer.alloc(0);
+    onclose;
+    onerror;
+    onmessage;
+    constructor(stdin = process.stdin, stdout = process.stdout) {
+        this.stdin = stdin;
+        this.stdout = stdout;
+    }
+    async start() {
+        if (this.started) {
+            throw new Error("CompatStdioServerTransport already started. connect() should be called only once.");
+        }
+        this.started = true;
+        this.stdin.on("data", this.handleData);
+        this.stdin.on("error", this.handleStreamError);
+        this.stdin.on("end", this.handleStreamClosed);
+        this.stdin.on("close", this.handleStreamClosed);
+        this.stdin.resume();
+    }
+    async send(message) {
+        const json = JSON.stringify(message);
+        const frame = this.mode === "content-length"
+            ? `Content-Length: ${Buffer.byteLength(json, "utf8")}\r\n\r\n${json}`
+            : `${json}\n`;
+        await new Promise((resolve) => {
+            if (this.stdout.write(frame)) {
+                resolve();
+                return;
+            }
+            this.stdout.once("drain", resolve);
+        });
+    }
+    async close() {
+        this.stdin.off("data", this.handleData);
+        this.stdin.off("error", this.handleStreamError);
+        this.stdin.off("end", this.handleStreamClosed);
+        this.stdin.off("close", this.handleStreamClosed);
+        if (this.stdin.listenerCount("data") === 0) {
+            this.stdin.pause();
+        }
+        this.buffer = Buffer.alloc(0);
+        this.emitCloseOnce();
+    }
+    handleData = (chunk) => {
+        if (chunk.length === 0) {
+            return;
+        }
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        this.processReadBuffer();
+    };
+    handleStreamError = (error) => {
+        this.onerror?.(error);
+    };
+    handleStreamClosed = () => {
+        this.emitCloseOnce();
+    };
+    emitCloseOnce() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.onclose?.();
+    }
+    processReadBuffer() {
+        while (true) {
+            try {
+                if (this.mode === "unknown") {
+                    const detected = this.detectMode();
+                    if (!detected) {
+                        return;
+                    }
+                    this.mode = detected;
+                    continue;
+                }
+                const modeBefore = this.mode;
+                const message = this.mode === "content-length"
+                    ? this.readContentLengthMessage()
+                    : this.readLineDelimitedMessage();
+                if (!message) {
+                    // readLineDelimitedMessage may switch mode to "content-length"
+                    // mid-stream; retry with the new parser instead of stopping.
+                    if (this.mode !== modeBefore) {
+                        continue;
+                    }
+                    return;
+                }
+                this.onmessage?.(message);
+            }
+            catch (caughtError) {
+                this.onerror?.(asError(caughtError));
+                this.mode = "unknown";
+            }
+        }
+    }
+    detectMode() {
+        // Skip blank leading lines that some clients may emit.
+        while (this.buffer.length > 0) {
+            if (this.buffer[0] === 0x0a) {
+                this.buffer = this.buffer.subarray(1);
+                continue;
+            }
+            if (this.buffer.length >= 2 && this.buffer[0] === 0x0d && this.buffer[1] === 0x0a) {
+                this.buffer = this.buffer.subarray(2);
+                continue;
+            }
+            break;
+        }
+        if (this.buffer.length === 0) {
+            return undefined;
+        }
+        const prefix = this.buffer
+            .subarray(0, Math.min(this.buffer.length, 32))
+            .toString("utf8")
+            .toLowerCase();
+        if (prefix.startsWith("content-length")) {
+            return "content-length";
+        }
+        const firstNewline = this.buffer.indexOf(0x0a);
+        if (firstNewline === -1) {
+            return undefined;
+        }
+        const firstLine = this.buffer.subarray(0, firstNewline).toString("utf8").replace(/\r$/, "");
+        if (/^\s*content-length\s*:/i.test(firstLine)) {
+            return "content-length";
+        }
+        return "line";
+    }
+    readLineDelimitedMessage() {
+        while (true) {
+            const newlineIndex = this.buffer.indexOf(0x0a);
+            if (newlineIndex === -1) {
+                return undefined;
+            }
+            const line = this.buffer.subarray(0, newlineIndex).toString("utf8").replace(/\r$/, "");
+            this.buffer = this.buffer.subarray(newlineIndex + 1);
+            if (line.trim().length === 0) {
+                continue;
+            }
+            if (/^\s*content-length\s*:/i.test(line)) {
+                // Reconstruct the header with the correct line ending so that
+                // findHeaderBoundary can locate \r\n\r\n or \n\n reliably.
+                const sep = this.buffer.length > 0 && this.buffer[0] === 0x0d ? "\r\n" : "\n";
+                this.buffer = Buffer.concat([Buffer.from(`${line}${sep}`, "utf8"), this.buffer]);
+                this.mode = "content-length";
+                return undefined;
+            }
+            return parseJsonRpcMessage(line);
+        }
+    }
+    readContentLengthMessage() {
+        const headerBoundary = findHeaderBoundary(this.buffer);
+        if (!headerBoundary) {
+            return undefined;
+        }
+        const headersRaw = this.buffer.subarray(0, headerBoundary.index).toString("utf8");
+        const headerLines = headersRaw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        let contentLength;
+        for (const headerLine of headerLines) {
+            const separatorIndex = headerLine.indexOf(":");
+            if (separatorIndex === -1) {
+                this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
+                throw new Error(`Malformed header line: ${headerLine}`);
+            }
+            const headerName = headerLine.slice(0, separatorIndex).trim().toLowerCase();
+            const headerValue = headerLine.slice(separatorIndex + 1).trim();
+            if (headerName === "content-length") {
+                const parsed = Number.parseInt(headerValue, 10);
+                if (!Number.isFinite(parsed) || parsed < 0) {
+                    this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
+                    throw new Error(`Invalid Content-Length header value: ${headerValue}`);
+                }
+                contentLength = parsed;
+            }
+        }
+        if (contentLength === undefined) {
+            this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
+            throw new Error("Missing Content-Length header.");
+        }
+        const messageStart = headerBoundary.index + headerBoundary.delimiterBytes;
+        const frameEnd = messageStart + contentLength;
+        if (this.buffer.length < frameEnd) {
+            return undefined;
+        }
+        const body = this.buffer.subarray(messageStart, frameEnd).toString("utf8");
+        this.buffer = this.buffer.subarray(frameEnd);
+        return parseJsonRpcMessage(body);
+    }
+}
+//# sourceMappingURL=compat-stdio-transport.js.map

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;