@adhisang/minecraft-modding-mcp 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -5,7 +5,47 @@ 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).
 
-## [Unreleased]
+## [3.1.1] - 2026-03-21
+
+### Fixed
+- `analyze-symbol task="api-overview"` now inherits `sourceMapping` as the default `classNameMapping`, avoiding unintended fallback to `obfuscated` when callers omit `classNameMapping`.
+- `get-class-api-matrix` now builds rows from the explicitly requested `classNameMapping` instead of silently pivoting to `obfuscated` when both identities are available.
+- `find-mapping` now accepts short obfuscated class ids such as `dhl` when `sourceMapping="obfuscated"` instead of rejecting them at input validation.
+- `find-mapping` now restores `mojang -> intermediary`, `mojang -> yarn`, and `intermediary -> mojang` conversions on mappings builds where those paths previously failed.
+- `trace-symbol-lifecycle` now strips an accidental inline signature suffix from `symbol` before splitting `Class.method`, preventing misparsed lifecycle lookups while keeping the separate `descriptor` field as the exact-match path.
+- `trace-symbol-lifecycle` now rejects class-like `symbol` inputs such as `net.minecraft.world.item.Item` with `ERR_INVALID_INPUT` instead of scanning versions until lookup work fails elsewhere.
+- `analyze-symbol task="lifecycle"` now applies its required `version` as the lifecycle scan upper bound instead of ignoring that input and always scanning the default full range, and the high-level helper now keeps that scan to a recent 5-version window for predictable runtime.
+- `trace-symbol-lifecycle` now completes broad lifecycle scans more reliably without long stalls.
+- `analyze-mod` and `validate-project` now return retryable `suggestedCall` guidance when older string-subject or domain-include payloads fail with `ERR_INVALID_INPUT`.
+- `validate-mixin` and `validate-project task="project-summary"` now treat empty mixin configs as warning-only discovery results with zero validated classes instead of `ERR_INVALID_INPUT`.
+- `inspect-minecraft` now keeps workspace `class-overview`, class-like `search`, and `list-files` usable when source coverage is partial, with partial-status guidance where needed.
+- `inspect-minecraft` invalid task/subject combinations now return retryable `suggestedCall` guidance instead of dead-end `ERR_INVALID_INPUT` messages, preserving the requested task when artifact context is the only missing input and otherwise pointing to the subject-compatible retry path.
+- Path-based environment overrides now treat blank values and the literal strings `undefined` and `null` as unset, preventing accidental `./undefined` and `./null` cache roots and invalid JAR override paths when clients serialize missing values incorrectly.
+
+### Performance
+- `trace-symbol-lifecycle`, `check-symbol-exists`, and `find-mapping` now respond faster on Mojang/obfuscated-only workflows, especially on cold lookups.
+
+### Documentation
+- Shortened the English and Japanese READMEs so onboarding guidance, workflow notes, and detailed reference material no longer repeat the same content across multiple sections.
+- Simplified the generated tool-surface tables in both READMEs to compact purpose-only summaries and pointed exact input/output details to `docs/tool-reference.md`.
+- Rewrote the Japanese workflow guidance in more natural Japanese and clarified that the detailed examples and full reference remain English-first for now.
+
+## [3.1.0] - 2026-03-15
+
+### Changed
+- `search-class-source` `queryMode="auto" | "token"` now keeps separator queries such as `foo.bar`, `foo_bar`, and `foo$bar` on the indexed path instead of silently retrying a full substring scan; `queryMode="literal"` remains the explicit opt-in scan mode.
+- The top-level workflow tools now include `result.summary.subject` consistently, and high-confidence follow-up flows such as migration overviews, remap previews, cache previews, and search misses from those tools now surface `summary.nextActions`.
+- `tools/list` now exposes JSON Schema `default` values for fixed MCP tool parameters such as `list-versions.includeSnapshots=false`, `search-class-source.queryMode="auto"`, `inspect-minecraft.includeSnapshots=false`, `analyze-mod.searchType="all"` / `includeFiles=true` / `limit=50`, `validate-mixin.reportMode="full"`, and selected controls on the top-level workflow tools like `manage-cache.executionMode="preview"` / `limit=50`, so clients can rely on schema metadata instead of parsing prose descriptions.
+
+### Fixed
+- Error recovery payloads (`suggestedCall`) now omit parameters when the supplied value matches the tool's default behavior, keeping retryable calls smaller without changing their semantics.
+
+### Performance
+- Explicit text and path scan fallbacks in `search-class-source` now use less memory and stay more predictable on large artifacts.
+
+### Documentation
+- Corrected the published `compare-minecraft` class-only `subject.kind="class".sourcePriority` input and aligned the documented `inspect-minecraft` / `validate-project` outputs with current behavior.
+- Documented that safe fixed defaults now appear in `tools/list` schema output and that `suggestedCall` omits default-valued parameters.
 
 ## [3.0.0] - 2026-03-09
 
@@ -14,9 +54,6 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - The new v3 entry tools share `detail` / `include` response shaping and always return `result.summary` inside the standard `{ result?, error?, meta }` envelope, reducing default payload size and making next actions explicit.
 - `analyze-mod` now exposes `executionMode="preview" | "apply"` for safe remap planning and execution, and `manage-cache` now exposes the same preview/apply model for cache deletion, pruning, and rebuild workflows.
 
-### Documentation
-- Added v3 entry-tool usage guidance, shared response-shaping notes, and entry-tool-first migration guidance to both READMEs.
-
 ### Fixed
 - `inspect-minecraft` now routes `subject.kind="workspace"` requests with `focus.kind="class" | "file" | "search"` through the matching task for `task=auto`, while preserving workspace-aware artifact resolution for focused file and search follow-up flows.
 - `inspect-minecraft task=class-overview | class-source | class-members` now accepts `subject.kind="workspace"` with `focus.kind="class"` even when the focus omits an explicit artifact reference, reusing workspace version detection to resolve artifact context first.
@@ -37,8 +74,8 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ### Fixed
 - `compare-versions` now applies `packageFilter` consistently to `classes.addedCount`, `removedCount`, and `unchanged`, so class summary counts reflect the same filtered package scope as the returned class lists.
-- Heavy analysis tools are now serialized behind a bounded in-process queue, and queue overflow fails fast with `ERR_LIMIT_EXCEEDED` instead of amplifying concurrent load across the whole MCP transport.
-- The stdio CLI entrypoint now supervises an internal worker process, automatically restarts it after an unexpected exit, replays MCP initialization for the live session, and turns in-flight crashes into retryable JSON-RPC request failures instead of a full transport disconnect.
+- Heavy analysis tools now fail fast with `ERR_LIMIT_EXCEEDED` when too many expensive requests arrive at once, instead of letting the whole MCP session degrade under load.
+- The stdio CLI now recovers more cleanly from unexpected internal exits, reducing full-session disconnects during live use.
 - `trace-symbol-lifecycle` now uses strict method remapping when a descriptor is provided, falls back to name-only lookup when it is omitted, and surfaces real mapping input failures in warnings instead of collapsing them into generic lookup errors.
 - `get-class-source` / `get-class-members` now infer a missing artifact version from `projectPath` when `preferProjectVersion=true`, making project-aware lookups more consistent for previously resolved artifacts.
 - Error recovery payloads (`suggestedCall`) now use the current `target` object schema instead of deprecated `targetKind` / `targetValue` fields.
@@ -51,7 +88,7 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - `resolve-workspace-symbol` now recognizes NeoForge ModDevGradle workspaces as `mojang` compile mappings instead of returning `mapping_unavailable`.
 - `resolve-artifact`, `get-class-source`, and `get-class-members` now preserve `ERR_JAR_NOT_FOUND` for missing `target.kind=jar` paths instead of leaking raw filesystem `ENOENT` failures through the public contract.
 - `get-registry-data` now invalidates corrupt cached `registries.json` snapshots, regenerates them on demand, and reports `ERR_REGISTRY_GENERATION_FAILED` when the regenerated snapshot is still unreadable.
-- `validate-mixin` now retries with `sourcePriority="maven-first"` after a partial `loom-first` validation caused by mapping/signature resolution limits, reducing false warnings from Loom-only resolution paths.
+- `validate-mixin` now retries with Maven mapping data after Loom-only partial results when that can complete validation, reducing false warnings.
 - `validate-mixin` no longer emits schema-invalid `check-symbol-exists` recovery payloads in `suggestedCall`; unsupported parameters such as `scope` and `projectPath` are omitted from those calls.
 - `validate-mixin` now lowers confidence for skipped member validation and exposes requested-vs-applied scope/source-priority details instead of making partial results look fully verified.
 - `validate-mixin` now follows the resolved artifact namespace during bytecode lookup for non-vanilla scopes, so `scope="merged"` on Mojang-mapped Loom workspaces validates against merged class names instead of falling back to false partial results and retry-driven timeouts.
@@ -61,13 +98,11 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - `check-symbol-exists` no longer repeats raw Loom tiny-cache miss warnings when Maven tiny mappings successfully satisfy the lookup; successful fallback now emits concise fallback context instead.
 
 ### Documentation
-- Corrected the `compare-versions` README contract to document registry results under `result.registry`.
-- Documented the new compact-response options, `summary-first` validate-mixin mode, bare-string `target` recovery guidance, and updated token-efficient examples in both READMEs.
+- Corrected the published `compare-versions` response docs to show registry results under `result.registry`.
 
 ### Performance
-- `resolve-artifact`, `index-artifact`, and `get-runtime-metrics` now keep cache entry/byte accounting incrementally during ingest, reindex, cache hits, and eviction, avoiding repeated full-cache rescans after each artifact load.
-- `find-mapping`, `get-class-api-matrix`, `resolve-workspace-symbol`, `check-symbol-exists`, and `validate-mixin` now reuse hot-path mapping graph paths, class remaps, and normalization work, reducing latency for repeated namespace lookups and large Mixin validation batches.
-- Warm-cache source and mod workflows now avoid extra regex recompilation, statement-cache churn, and FIFO cache evictions across search, signature lookup, source resolution, and decompile paths.
+- Cache-heavy artifact loading and runtime metric reads now stay faster after repeated operations instead of rescanning cache state each time.
+- `find-mapping`, `get-class-api-matrix`, `resolve-workspace-symbol`, `check-symbol-exists`, and `validate-mixin` now respond faster on repeated mapping-heavy workflows.
 
 ## [2.0.0] - 2026-03-07
 
@@ -83,7 +118,7 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ### Fixed
 - `resolve-artifact`: `targetKind=coordinate` now reuses the local Gradle `modules-2` cache in addition to the local Maven repository and configured source repos, so cached third-party libraries such as Architectury can resolve without manual cache spelunking.
-- `resolve-artifact`: `mapping=mojang` + Loom merged source discovery now flags partial source coverage with `qualityFlags=["partial-source-no-net-minecraft"]` and a warning when the selected source jar does not actually contain `net.minecraft` entries.
+- `resolve-artifact`: `mapping=mojang` + Loom merged source discovery now warns when the selected source jar only provides partial Minecraft source coverage.
 - `get-class-source` / `get-class-members`: when an artifact is resolved from a `*-sources.jar`, the server now keeps the sibling binary jar and automatically falls back to it when source coverage is incomplete instead of treating the source jar as bytecode.
 - `get-class-source`: partial-source binary fallback now bypasses the same sibling `*-sources.jar` that triggered the miss, and fallback failures for vanilla classes point to `get-class-api-matrix` instead of misleading `find-class` recovery.
 - `get-class-members`: bytecode lookup now follows the resolved artifact namespace (`mappingApplied`) before remapping members back to the requested namespace, fixing merged Mojang artifacts that were incorrectly forced through obfuscated class names.
@@ -93,18 +128,14 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - Tool input parsing now leaves nested `typedJson` and JSON Patch `value` payload fields untouched, even when their keys happen to match top-level numeric option names such as `limit` or `maxLines`.
 
 ### Performance
-- `search-class-source`: reduce search latency, heap growth, and DB round-trips by returning compact hits only and skipping snippet hydration, relation expansion, and `totalApprox` count queries.
-- Tool input preprocessing now stays shallow, avoiding recursive scans through large nested payloads such as NBT typed JSON and patch bodies.
+- `search-class-source` now returns compact hits more efficiently, reducing latency and memory use on larger artifacts.
 
 ## [1.2.1] - 2026-03-05
 
 ### Fixed
-- MCP startup regression: removed eager `SourceService` pre-initialization during server startup so `tools/list` handshakes are not blocked by SQLite initialization on slower environments.
+- MCP startup regression: `tools/list` handshakes no longer stall on SQLite initialization in slower environments.
 - Decompiler: skip Java/Vineflower availability checks when decompiled source is already cached, avoiding unnecessary startup errors on systems without Java.
 
-### Documentation
-- Clarified startup behavior in README (`SourceService` remains lazy and is not pre-initialized before tool discovery).
-
 ## [1.2.0] - 2026-03-05
 
 ### Added
@@ -146,12 +177,7 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - 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.
-
-### Performance
-- Avoid duplicate UTF-8 decode during truncation.
-- Eager `SourceService` init during handshake idle time.
+- `SourceService` startup work now avoids slowing the MCP handshake while still using idle time to reduce the wait before the first source-heavy request.
 
 ## [1.1.1] - 2026-03-02
 
@@ -161,11 +187,8 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [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.
+- Restore Codex startup handshake compatibility by accepting both newline-delimited and `Content-Length` stdio framing on stdio connections.
 
 ### Documentation
 - Add Quick Start setup for Claude Code, OpenAI Codex CLI, and Gemini CLI.