@adhisang/minecraft-modding-mcp 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-03-09
+
+### Added
+- v3 entry tools: `inspect-minecraft`, `analyze-symbol`, `compare-minecraft`, `analyze-mod`, `validate-project`, and `manage-cache` now provide summary-first starting points for the main Minecraft, symbol, mod, validation, and cache workflows while keeping expert tools available for follow-up work.
+- 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.
+- `validate-project task=project-summary` now keeps per-config Mixin validation failures inside the summary result as warnings and invalid counts instead of aborting the whole workspace run on the first bad config.
+- `compare-minecraft` now accepts `sourcePriority` for class-diff requests, and `registry-diff` degrades to `summary.status="partial"` with recovery actions when only one side of detailed registry data can be loaded.
+- `compare-minecraft task=versions` now sets `meta.truncated` with recovery actions when summary-mode class or registry samples are clipped, including mixed `include=["classes"]` / `["registry"]` requests where the other summary-side group was truncated.
+- `manage-cache` now applies `selector.olderThan`, `mapping`, `scope`, `projectPath`, and normalized `jarPath` matching, exposes real cache health states (`stale`, `orphaned`, `corrupt`, `in_use`), and advances `list` pagination through `meta.pagination.nextCursor`.
+
+## [2.1.0] - 2026-03-08
+
+### Added
+- Source inspection tools now expose `artifactContents` so clients can tell whether a result came from a `source-jar` or `decompiled-binary`, whether non-Java resources are indexed, and whether source coverage is `full` or `partial`.
+- `get-class-source`, `get-class-members`, `search-class-source`, and `get-artifact-file` now expose `returnedNamespace` to distinguish the namespace of returned content from the underlying artifact namespace (`mappingApplied`).
+- Token-efficient response shaping options: `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` now accept `maxCandidates`; `get-class-api-matrix` accepts `maxRows`; `diff-class-signatures` accepts `includeFullDiff`; `decompile-mod-jar` accepts `includeFiles` / `maxFiles`; `get-registry-data` accepts `includeData` / `maxEntriesPerRegistry`; `validate-mixin` accepts `includeIssues`.
+- `validate-mixin` now reports per-result `validationStatus` (`full` / `partial` / `invalid`), member coverage counters (`summary.membersValidated` / `membersSkipped` / `membersMissing`), batch `summary.partial`, and scope/source-priority provenance fields (`requestedScope` / `appliedScope`, `requestedSourcePriority` / `appliedSourcePriority`) so partial validation is explicit.
+- `validate-mixin` now supports `input.mode="project"` to recursively discover `*.mixins.json` under a workspace root and validate every referenced Mixin in one call.
+- `validate-mixin` now adds `confidenceBreakdown` and `reportMode="summary-first"` so callers can see why confidence dropped and consume batch-oriented output without repeated per-result provenance/warning payloads.
+
+### 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.
+- `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.
+- `list-artifact-files` now warns when callers probe `assets/` or `data/` prefixes against the Java-source index, instead of silently returning an unexplained empty result.
+- `artifactContents.sourceCoverage` now strictly reports `full` or `partial`, matching the documented contract instead of carrying an unreachable `unknown` branch in the exported type.
+- `get-class-members` now rejects malformed field and method descriptors from corrupted bytecode with `ERR_INVALID_INPUT` instead of returning malformed Java signatures, and invalid `void` method arguments now report as method descriptor errors instead of misleading field descriptor errors.
+- `resolve-artifact` now searches project-local and Gradle user-home Loom caches without auto-selecting unrelated mod/library source jars just because their filenames contain the requested Minecraft version.
+- `resolve-artifact` and related version-target mapping failures now preserve `ERR_MAPPING_NOT_APPLIED` while adding `artifactOrigin` plus actionable recovery details for decompile-only artifacts.
+- `remap-mod-jar` now detects Mojang-mapped Fabric/Quilt inputs, returns a copied output for `targetMapping="mojang"`, and fails fast with contextual diagnostics for unsupported Mojang-input `targetMapping="yarn"` requests.
+- `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` 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.
+- Invalid `validate-mixin` requests now return the standard `ERR_INVALID_INPUT` envelope with `fieldErrors`, `hints`, and a mode-correct `suggestedCall` instead of the SDK's generic pre-validation text error.
+- Bare string `target` inputs for `resolve-artifact`, `get-class-source`, and `get-class-members` now return `ERR_INVALID_INPUT` with schema-correct wrapper suggestions instead of generic object-schema failures.
+- `validate-mixin` now classifies signature-loading/tool-limited target failures as `validation-incomplete` warnings instead of reporting them as missing classes.
+- `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.
+
+### 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.
+
 ## [2.0.0] - 2026-03-07
 
 ### Changed

package/README.md

@@ -13,7 +13,7 @@
 
 It lets you explore decompiled Minecraft source, convert symbol names across four naming namespaces (`obfuscated`, `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.
 
-**29 tools** | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
+**35 tools** (6 entry + 29 expert) | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
 
 ## Features
 
@@ -172,6 +172,29 @@ Pass environment variables to override defaults:
 
 ## Tool Surface
 
+### v3 Entry Tools
+
+These are the default starting points for v3 workflows. They keep the public `{ result?, error?, meta }` envelope, always return `result.summary`, and share `detail: "summary" | "standard" | "full"` plus opt-in `include[]` groups. Mutating entry tools use `executionMode: "preview" | "apply"` so preview is explicit in the public contract.
+
+| Tool | Purpose | Key Inputs | Key Outputs |
+| --- | --- | --- | --- |
+| `inspect-minecraft` | Start from a version, artifact, class, file, search query, or workspace and route to the most relevant Minecraft inspection flow | `task?`, `subject?`, `detail?`, `include?`, `limit?`, `cursor?`, `includeSnapshots?` | `result.summary`, `subject`, `artifact?`, `class?`, `search?`, `file?`, `files?` |
+| `analyze-symbol` | One entry point for symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol analysis, and API overview | `task`, `subject`, `version?`, `sourceMapping?`, `targetMapping?`, `projectPath?`, `classNameMapping?`, `signatureMode?`, `nameMode?`, `includeKinds?`, `maxRows?`, `maxCandidates?`, `detail?`, `include?` | `result.summary`, `match?`, `candidates?`, `ambiguity?`, `matrix?`, `workspace?` |
+| `compare-minecraft` | Compare version pairs, class signatures, registries, or produce a migration-oriented overview | `task?`, `subject`, `detail?`, `include?`, `sourcePriority?`, `maxClassResults?`, `maxEntriesPerRegistry?`, `includeFullDiff?`, `limit?` | `result.summary`, `comparison`, `classes?`, `classDiff?`, `registry?`, `migration?` |
+| `analyze-mod` | Metadata-first entry point for mod summary, decompile/search flows, class source, and safe remap previews/applies | `task`, `subject`, `query?`, `searchType?`, `targetMapping?`, `outputJar?`, `executionMode?`, `includeFiles?`, `maxFiles?`, `maxLines?`, `maxChars?`, `limit?`, `detail?`, `include?` | `result.summary`, `metadata?`, `decompile?`, `hits?`, `source?`, `operation?` |
+| `validate-project` | Project-level validation entry for workspace summaries plus direct Mixin and Access Widener validation | `task`, `subject`, `version?`, `mapping?`, `sourcePriority?`, `scope?`, `preferProjectVersion?`, `preferProjectMapping?`, `sourceRoots?`, `configPaths?`, `minSeverity?`, `hideUncertain?`, `explain?`, `warningMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `includeIssues?`, `detail?`, `include?` | `result.summary`, `project`, `workspace?`, `issues?`, `recovery?` |
+| `manage-cache` | User-facing cache summary, listing, verification, previewed deletion/pruning/rebuild, and explicit apply operations | `action`, `cacheKinds?`, `selector?`, `executionMode?`, `detail?`, `include?`, `limit?`, `cursor?` | `result.summary`, `stats?`, `cacheEntries?`, `operation?`, `meta.pagination.nextCursor?` |
+
+`compare-minecraft` forwards `sourcePriority` for class-diff flows, matching `diff-class-signatures`.
+`inspect-minecraft` also accepts `subject.kind="workspace"` with `focus.kind="class"` for `task="class-overview" | "class-source" | "class-members"` without requiring an explicit `artifact`; it resolves the artifact from the workspace version first.
+`compare-minecraft` summary-mode version comparisons now expose clipped class and registry samples through `meta.truncated`, including mixed `include=["classes"]` / `["registry"]` requests where the other summary-side group was clipped.
+When `registry-diff` can only load one side of detailed registry data, it returns `summary.status="partial"` plus recovery-oriented `nextActions` instead of failing the whole call.
+
+`manage-cache` list pagination returns `meta.pagination.nextCursor`.
+`selector.olderThan` accepts ISO-8601 durations such as `P30D`, `selector.status` uses the shared `healthy | partial | stale | orphaned | corrupt | in_use` vocabulary, and `jarPath` / `projectPath` matching normalizes WSL and Windows path forms before filtering.
+
+If you already know the exact low-level operation you want, the retained expert tools below are still available and remain the fastest way to do narrow follow-up work.
+
 ### Source Exploration
 
 Tools for browsing Minecraft versions, resolving source artifacts, and reading/searching decompiled source code.
@@ -179,13 +202,13 @@ 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` | `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `artifactId`, `origin`, `mappingApplied`, `qualityFlags[]`, `adjacentSourceCandidates?`, `sampleEntries?`, `warnings[]` |
+| `resolve-artifact` | Resolve source artifact from `version` / `jar` / `coordinate` | `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `artifactId`, `origin`, `mappingApplied`, `qualityFlags[]`, `artifactContents`, `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 artifact target or resolve target on demand (`mode=metadata` by default) | `className`, `target`, `mode?`, `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`, `target`, `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?`, `queryMode?`, `limit?`, `cursor?` | `hits[]`, `nextCursor?`, `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` |
+| `get-class-source` | Get class source by artifact target or resolve target on demand (`mode=metadata` by default) | `className`, `target`, `mode?`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?`, `startLine?`, `endLine?`, `maxLines?`, `maxChars?`, `outputFile?` | `mode`, `sourceText`, `returnedRange`, `truncated`, `charsTruncated?`, `outputFile?`, `artifactId`, `returnedNamespace`, `artifactContents`, mapping/provenance metadata |
+| `get-class-members` | Get class fields/methods/constructors from bytecode | `className`, `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `access?`, `includeSynthetic?`, `includeInherited?`, `memberPattern?`, `maxMembers?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `returnedNamespace`, `artifactContents`, `warnings[]` |
+| `search-class-source` | Search indexed class source for symbols/text/path | `artifactId`, `query`, `intent?`, `match?`, `packagePrefix?`, `fileGlob?`, `symbolKind?`, `queryMode?`, `limit?`, `cursor?` | `hits[]`, `nextCursor?`, `mappingApplied`, `returnedNamespace`, `artifactContents` |
+| `get-artifact-file` | Read full source file with byte guard | `artifactId`, `filePath`, `maxBytes?` | `content`, `contentBytes`, `truncated`, `mappingApplied`, `returnedNamespace`, `artifactContents` |
+| `list-artifact-files` | List indexed source file paths with cursor pagination | `artifactId`, `prefix?`, `limit?`, `cursor?` | `items[]`, `nextCursor?`, `mappingApplied`, `artifactContents`, `warnings[]` |
 | `index-artifact` | Rebuild index metadata for an existing artifact | `artifactId`, `force?` | `reindexed`, `reason`, `counts`, `indexedAt`, `durationMs` |
 
 ### Version Comparison & Symbol Tracking
@@ -194,9 +217,9 @@ Tools for comparing class/registry changes across Minecraft versions and tracing
 
 | Tool | Purpose | Key Inputs | Key Outputs |
 | --- | --- | --- | --- |
-| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions | `symbol`, `descriptor?`, `fromVersion?`, `toVersion?`, `mapping?`, `sourcePriority?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |
-| `diff-class-signatures` | Compare one class between two versions and return member deltas | `className`, `fromVersion`, `toVersion`, `mapping?`, `sourcePriority?` | `classChange`, `constructors/methods/fields.{added,removed,modified}`, `summary`, `warnings[]` |
-| `compare-versions` | Compare class/registry changes between two versions | `fromVersion`, `toVersion`, `category?`, `packageFilter?`, `maxClassResults?` | `classesDiff`, `registryDiff`, `summary`, `warnings[]` |
+| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions (`descriptor` omitted = name-only lookup) | `symbol`, `descriptor?`, `fromVersion?`, `toVersion?`, `mapping?`, `sourcePriority?`, `includeSnapshots?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |
+| `diff-class-signatures` | Compare one class between two versions and return member deltas | `className`, `fromVersion`, `toVersion`, `mapping?`, `sourcePriority?`, `includeFullDiff?` | `classChange`, `constructors/methods/fields.{added,removed,modified}`, `modified`, `modified[].{key,changed,from?,to?}`, `summary`, `warnings[]` |
+| `compare-versions` | Compare class/registry changes between two versions | `fromVersion`, `toVersion`, `category?`, `packageFilter?`, `maxClassResults?` | `classes`, `registry`, `summary`, `warnings[]` |
 
 ### Mapping & Symbols
 
@@ -204,11 +227,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?`, `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`, `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 (`obfuscated/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?`, `nameMode?`, `signatureMode?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `meta.warnings[]` |
+| `find-mapping` | Find mapping candidates for class/field/method symbols between namespaces | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `disambiguation?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `ambiguityReasons?`, `provenance?`, `meta.warnings[]` |
+| `resolve-method-mapping-exact` | Resolve one method mapping with strict owner+name+descriptor matching | `version`, `name`, `owner`, `descriptor`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `provenance?`, `meta.warnings[]` |
+| `get-class-api-matrix` | Show one class API as a mapping matrix (`obfuscated/mojang/intermediary/yarn`) | `version`, `className`, `classNameMapping`, `includeKinds?`, `sourcePriority?`, `maxRows?` | `classIdentity`, `rows[]`, `rowCount`, `rowsTruncated?`, `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?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `workspaceDetection`, `meta.warnings[]` |
+| `check-symbol-exists` | Strict symbol presence check for class/field/method | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?`, `nameMode?`, `signatureMode?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `meta.warnings[]` |
 
 ### NBT Utilities
 
@@ -227,10 +250,10 @@ 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`, `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[]` |
+| `decompile-mod-jar` | Decompile mod JAR and optionally return one class source | `jarPath`, `className?`, `includeFiles?`, `maxFiles?` | `outputDir`, `fileCount`, `files?`, `returnedFileCount?`, `filesTruncated?`, `filesOmitted?`, `source?`, `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[]` |
+| `remap-mod-jar` | Remap a Fabric/Quilt mod JAR to yarn/mojang names; Mojang-mapped inputs are copied for `targetMapping="mojang"` | `inputJar`, `targetMapping`, `mcVersion?`, `outputJar?` | `outputJar`, `mcVersion`, `fromMapping`, `targetMapping`, `resolvedTargetNamespace`, `warnings[]` |
 
 ### Validation
 
@@ -238,7 +261,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 | `input`, `sourceRoots?`, `version`, `mapping?`, `sourcePriority?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `minSeverity?`, `hideUncertain?`, `warningMode?`, `preferProjectMapping?`, `reportMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `explain?` | `mode`, `results[]`, `summary`, `issueSummary?`, `toolHealth?`, `confidenceScore?` |
+| `validate-mixin` | Parse/validate Mixin source against target Minecraft version | `input`, `sourceRoots?`, `version`, `mapping?`, `sourcePriority?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `minSeverity?`, `hideUncertain?`, `warningMode?`, `preferProjectMapping?`, `reportMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `explain?`, `includeIssues?` | `mode`, `results[].validationStatus`, `summary.partial`, `issueSummary?`, `provenance?`, `incompleteReasons?`, `toolHealth?`, `confidenceScore?`, `confidenceBreakdown?` |
 | `validate-access-widener` | Parse/validate Access Widener content against target version | `content`, `version`, `mapping?`, `sourcePriority?` | `valid`, `issues[]`, `warnings[]`, `summary` |
 
 ### Registry & Diagnostics
@@ -247,7 +270,7 @@ Tools for querying generated registry data and inspecting server runtime state.
 
 | Tool | Purpose | Key Inputs | Key Outputs |
 | --- | --- | --- | --- |
-| `get-registry-data` | Get generated registry snapshots (blocks/items/entities etc.) | `version`, `registry?` | `registries` (all or selected), `warnings[]` |
+| `get-registry-data` | Get generated registry snapshots (blocks/items/entities etc.) | `version`, `registry?`, `includeData?`, `maxEntriesPerRegistry?` | `registries`, `data?`, `entryCount`, `returnedEntryCount?`, `registryEntryCounts?`, `dataTruncated?`, `warnings[]` |
 | `get-runtime-metrics` | Inspect runtime counters and latency snapshots | none | `result.*` runtime metrics, `meta` envelope |
 
 ### Tool Constraints
@@ -255,11 +278,33 @@ Tools for querying generated registry data and inspecting server runtime state.
 `resolve-artifact` now takes `target: { kind, value }`.
 `get-class-source` requires `target`, where `target.type="artifact"` selects a previously resolved `artifactId` and `target.type="resolve"` supplies `{ kind, value }` directly.
 `get-class-members` requires the same `target` object shape and still needs a binary jar (`binaryJarPath`) to read `.class` entries.
+`get-class-members` returns `ERR_INVALID_INPUT` when a classfile contains malformed field or method descriptors instead of emitting malformed Java signature text from corrupted bytecode.
+Malformed `void` usage outside method return positions is rejected with descriptor-specific errors, so invalid method arguments now report as method descriptor failures instead of field descriptor failures.
+Error `suggestedCall` payloads now use the same `target` object schema instead of legacy `targetKind` / `targetValue` fields.
 Positive integer tool parameters accept numeric strings such as `"10"` in addition to JSON numbers.
 This numeric-string coercion only applies to documented top-level tool arguments; nested `typedJson` payloads and JSON Patch `value` objects are preserved verbatim.
-`validate-mixin` requires `input.mode` to be exactly one of `inline`, `path`, `paths`, or `config`. `input.path`/`input.paths[]` are normalized for host/WSL path formats before file reads. `input.configPaths[]` reads mixin config JSON files and auto-discovers source files for batch validation (`sourceRoots[]` 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).
+`resolve-artifact`, `get-class-source`, `get-class-members`, `search-class-source`, `get-artifact-file`, and `list-artifact-files` include `artifactContents` so clients can see whether the backing artifact is `source-jar` or `decompiled-binary`, whether resources are indexed (`resourcesIncluded=false` today), and whether source coverage is always `full` or `partial`.
+`get-class-source`, `get-class-members`, `search-class-source`, and `get-artifact-file` include `returnedNamespace`; compare it with `mappingApplied` when a tool returns remapped symbols instead of raw indexed source text.
+`list-artifact-files` warns when you probe `assets/` or `data/` prefixes because the current index stores Java source only, not non-Java resources.
+`get-class-source` and `get-class-members` can infer a missing artifact version from `projectPath` when `preferProjectVersion=true` and artifact metadata does not already contain a version.
+Heavy analysis tools (`trace-symbol-lifecycle`, `diff-class-signatures`, `compare-versions`, `find-mapping`, `resolve-method-mapping-exact`, `get-class-api-matrix`, `get-registry-data`) are serialized inside the server to protect stdio transport stability; when the queue is full they fail fast with `ERR_LIMIT_EXCEEDED`.
+The CLI stdio entrypoint now runs a supervised worker process. If the worker exits unexpectedly, the wrapper restarts it, replays MCP initialization for the current session, and keeps the same stdio connection usable; any request that was already in flight fails with a retryable JSON-RPC internal error instead of tearing down the whole transport.
+`find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` accept `maxCandidates` to cap `candidates[]`; `candidateCount` always reports the full pre-truncation candidate total and `candidatesTruncated=true` signals clipping.
+`get-class-api-matrix` accepts `maxRows`; `rowCount` reports the full pre-truncation row total and `rowsTruncated=true` signals clipping.
+`diff-class-signatures` supports `includeFullDiff=false` to omit `from`/`to` snapshots from `modified[]` entries and keep only `key` plus `changed`.
+`validate-mixin` requires `input.mode` to be exactly one of `inline`, `path`, `paths`, `config`, or `project`. `input.path`/`input.paths[]` are normalized for host/WSL path formats before file reads. `input.configPaths[]` reads mixin config JSON files and auto-discovers source files for batch validation (`sourceRoots[]` 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). `input.mode="project"` recursively discovers `**/*.mixins.json` under `input.path`, then runs the same config-driven batch validation with `projectPath` defaulting to that workspace root.
 `validate-mixin` always returns `mode`, `results[]`, and `summary`; single-input modes still use a one-element `results[]` array.
+`validate-mixin` supports `includeIssues=false` for summary-first workflows that do not need per-result `issues[]`; combine it with `reportMode=compact` and `warningMode=aggregated` to keep responses small.
+`reportMode=summary-first` hoists shared provenance, warnings, and incomplete-reason summaries to the top level while trimming duplicate per-result metadata.
+`validate-mixin` per-result responses now include `validationStatus` (`full`, `partial`, `invalid`) plus `summary.membersValidated`, `summary.membersSkipped`, and `summary.membersMissing`; `quickSummary` now includes member coverage counts instead of only issue counts.
+`validate-mixin` batch `summary` now includes `partial` so callers can distinguish fully clean results from tool-limited-but-non-failing results.
+`validate-mixin` now reports `validation-incomplete` when target metadata cannot be loaded reliably, instead of misclassifying those tool-limited cases as confirmed missing classes.
+`validate-mixin` responses now include `confidenceBreakdown` alongside `confidenceScore`, exposing the base score plus the penalties that lowered confidence.
 `validate-mixin` per-result responses include `provenance.resolutionNotes?` when mapping fallback occurs.
+`validate-mixin` provenance now exposes `requestedScope` / `appliedScope` and `requestedSourcePriority` / `appliedSourcePriority` so fallback and retry behavior is explicit.
+`scope="loader"` currently resolves the same artifact class as `scope="merged"`; keep using `scope` to declare intent, but expect the same underlying lookup path today.
+For non-vanilla scopes such as `scope="merged"`, `validate-mixin` now performs bytecode lookup in the resolved artifact namespace before remapping members back to the requested namespace, so Mojang-mapped Loom workspaces validate against merged class names instead of reporting false partial results.
+`validate-mixin` automatically retries with `sourcePriority="maven-first"` after a partial `loom-first` validation caused by mapping/signature resolution limits, and records that retry in warnings plus provenance notes.
 `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.
@@ -267,13 +312,17 @@ This numeric-string coercion only applies to documented top-level tool arguments
 `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` per-result 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` with `explain=true` enriches each issue with `explanation` and `suggestedCall` (tool + params) for agent-driven recovery; generated `check-symbol-exists` recovery payloads now stay within that tool's public schema.
+Schema validation failures now also return the standard `ERR_INVALID_INPUT` envelope with `fieldErrors`, `hints`, and a mode-correct `suggestedCall` for common `validate-mixin` mistakes such as passing raw source text directly as `input`.
+Bare string `target` values now return `ERR_INVALID_INPUT` with a schema-correct `suggestedCall` wrapper for `resolve-artifact`, `get-class-source`, and `get-class-members`.
 `validate-mixin` summary uses `processingErrors`, `totalValidationErrors`, and `totalValidationWarnings`; the deprecated `summary.errors` field was removed.
+`check-symbol-exists` suppresses raw `No Loom tiny mapping files matched version ...` noise when Maven tiny mappings successfully satisfy the lookup; successful fallback now reports a single concise warning instead of repeating the Loom miss on every result.
 `resolve-artifact` with `target.kind=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 `target.value` from `gradle.properties` (`minecraft_version`, `mc_version`, `minecraftVersion`) when `target.kind=version`.
 `resolve-artifact` with `target.kind=coordinate` searches the local Maven repository, the local Gradle `modules-2` cache, and configured `MCP_SOURCE_REPOS` before reporting `ERR_SOURCE_NOT_FOUND`.
+`resolve-artifact`, `get-class-source`, and `get-class-members` now preserve `ERR_JAR_NOT_FOUND` for missing or inaccessible `target.kind=jar` paths instead of surfacing raw filesystem exceptions.
 `resolve-artifact` includes `sampleEntries` only when a source JAR is resolved; decompile-only paths leave it unset.
-`resolve-artifact` adds `qualityFlags=["partial-source-no-net-minecraft"]` and a warning when a merged Loom source candidate does not contain `net.minecraft` sources; `get-class-source` now bypasses that sibling `*-sources.jar` during binary fallback so the fallback can actually reach the binary artifact.
+`resolve-artifact` adds `qualityFlags=["partial-source-no-net-minecraft"]` and a warning when a merged Loom source candidate does not contain `net.minecraft` sources; only candidates that still look like Minecraft source artifacts are auto-selected, while version-matching mod/library source jars remain diagnostics only. `get-class-source` now bypasses that sibling `*-sources.jar` during binary fallback so the fallback can actually reach the binary artifact.
 `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.
 `find-class` returns an explanatory warning when an `obfuscated` artifact is queried with names that look like deobfuscated Mojang classes.
 `find-class` suppresses non-vanilla matches for vanilla-looking queries on artifacts flagged with `partial-source-no-net-minecraft`; in that situation it returns a warning instead of unrelated modded classes.
@@ -297,18 +346,28 @@ Mod tool `jarPath` inputs are normalized to a canonical local `.jar` file path b
 `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.
+`decompile-mod-jar` supports `includeFiles=false` to skip the full class list and `maxFiles` to cap it when you only need counts or a sample. `returnedFileCount`, `filesTruncated`, and `filesOmitted` make the shaping explicit.
 `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.
+`get-registry-data` now discards corrupt cached `registries.json` files, regenerates them when possible, and returns `ERR_REGISTRY_GENERATION_FAILED` if the regenerated snapshot is still unreadable.
+`get-registry-data` supports `includeData=false` to return registry names and counts without full entry bodies. `maxEntriesPerRegistry` caps returned entries per registry while preserving full `entryCount` and `registryEntryCounts`.
 Migration notes:
+- Start with `inspect-minecraft` for version/artifact/class/file/search workflows before dropping to `list-versions`, `resolve-artifact`, `get-class-source`, `get-class-members`, `search-class-source`, `get-artifact-file`, or `list-artifact-files`.
+- Start with `analyze-symbol` for symbol mapping/existence/lifecycle/workspace questions before using `find-mapping`, `resolve-method-mapping-exact`, `check-symbol-exists`, `trace-symbol-lifecycle`, `resolve-workspace-symbol`, or `get-class-api-matrix` directly.
+- Start with `compare-minecraft` for version-pair, class diff, registry diff, and migration-summary flows before using `compare-versions`, `diff-class-signatures`, or `get-registry-data` directly.
+- Start with `analyze-mod` for metadata-first mod inspection and safe remap previews/applies before using `analyze-mod-jar`, `decompile-mod-jar`, `get-mod-class-source`, `search-mod-source`, or `remap-mod-jar` directly.
+- Start with `validate-project` for workspace summaries and direct Mixin / Access Widener validation before using `validate-mixin` or `validate-access-widener` directly.
+- Start with `manage-cache` for cache inventory and safe cleanup; use `executionMode="preview"` to inspect deletion/prune/rebuild impact before `executionMode="apply"`.
 - Replace `resolve-artifact` `targetKind` + `targetValue` with `target: { kind, value }`.
 - Replace `get-class-source` / `get-class-members` top-level `artifactId` / `targetKind` / `targetValue` with `target: { type: "artifact", artifactId }` or `target: { type: "resolve", kind, value }`.
 - `resolve-method-mapping-exact` is method-only and no longer accepts `kind`.
-- Replace `validate-mixin` `source` / `sourcePath` / `sourcePaths` / `mixinConfigPath` / `sourceRoot` with `input.mode` plus `input.source` / `input.path` / `input.paths[]` / `input.configPaths[]` and `sourceRoots[]`. Use `summary.processingErrors` instead of `summary.errors`.
+- Replace `validate-mixin` `source` / `sourcePath` / `sourcePaths` / `mixinConfigPath` / `sourceRoot` with `input.mode` plus `input.source` / `input.path` / `input.paths[]` / `input.configPaths[]` and `sourceRoots[]`. Use `input.mode="project"` when you want to discover `*.mixins.json` automatically from a workspace root. Use `summary.processingErrors` instead of `summary.errors`.
 - `search-class-source` removed `snippetLines`, `includeDefinition`, and `includeOneHop`; responses now contain compact `hits[]` plus `nextCursor?` only, and `symbolKind` may only be used with `intent=symbol`.
 `remap-mod-jar` requires Java to be installed and only supports Fabric/Quilt mods.
+Mojang-mapped inputs can be returned as-is for `targetMapping="mojang"`. `targetMapping="yarn"` still expects an intermediary-built input jar.
 
 ## Resources
 
@@ -448,7 +507,8 @@ List source files under a specific package to understand project structure:
     "className": "net.minecraft.server.Main",
     "fromVersion": "1.20.1",
     "toVersion": "1.21.10",
-    "mapping": "obfuscated"
+    "mapping": "obfuscated",
+    "includeFullDiff": false
   }
 }
 ```
@@ -470,6 +530,10 @@ Get a high-level summary of what changed between two releases, including class a
 }
 ```
 
+Registry deltas are returned under `result.registry` (not `registryDiff`).
+When `packageFilter` is provided, `result.classes.addedCount`, `removedCount`, and `unchanged`
+are all scoped to that filtered package set.
+
 ### Mapping & Symbols
 
 #### Lookup mapping candidates
@@ -483,6 +547,7 @@ Get a high-level summary of what changed between two releases, including class a
     "sourceMapping": "obfuscated",
     "targetMapping": "mojang",
     "sourcePriority": "loom-first",
+    "maxCandidates": 10,
     "disambiguation": {
       "ownerHint": "net.minecraft"
     }
@@ -529,11 +594,14 @@ Get a high-level summary of what changed between two releases, including class a
     "version": "1.21.10",
     "className": "a.b.C",
     "classNameMapping": "obfuscated",
-    "includeKinds": "class,field,method"
+    "includeKinds": "class,field,method",
+    "maxRows": 100
   }
 }
 ```
 
+Add `maxCandidates` or `maxRows` when you only need the top matches or a bounded API slice.
+
 #### Resolve workspace compile-visible symbol
 ```json
 {
@@ -649,6 +717,7 @@ Decompile all classes and optionally retrieve a specific class inline:
   "tool": "decompile-mod-jar",
   "arguments": {
     "jarPath": "/path/to/mymod-1.0.0.jar",
+    "includeFiles": false,
     "className": "com.example.mymod.MyMod"
   }
 }
@@ -663,7 +732,8 @@ After decompilation, read any class without re-decompiling:
   "tool": "get-mod-class-source",
   "arguments": {
     "jarPath": "/path/to/mymod-1.0.0.jar",
-    "className": "com.example.mymod.mixin.PlayerMixin"
+    "className": "com.example.mymod.mixin.PlayerMixin",
+    "maxLines": 120
   }
 }
 ```
@@ -699,6 +769,8 @@ Remap a Fabric mod from `intermediary` to `yarn` names for easier reading:
 }
 ```
 
+If the input jar was already built with Mojang mappings, use `targetMapping: "mojang"` to get a copied output jar and a `fromMapping: "mojang"` result.
+
 ### Validation
 
 #### Validate Mixin source
@@ -714,7 +786,33 @@ Check a Mixin class source for correctness against a target Minecraft version:
       "source": "@Mixin(PlayerEntity.class)\npublic abstract class PlayerMixin {\n  @Inject(method = \"tick\", at = @At(\"HEAD\"))\n  private void onTick(CallbackInfo ci) {}\n}"
     },
     "version": "1.21.10",
-    "mapping": "yarn"
+    "mapping": "yarn",
+    "reportMode": "compact",
+    "warningMode": "aggregated",
+    "includeIssues": false
+  }
+}
+```
+
+#### Validate all Mixins in a project
+
+Discover `*.mixins.json` files from a workspace root and validate every referenced Mixin in one call:
+
+```json
+{
+  "tool": "validate-mixin",
+  "arguments": {
+    "input": {
+      "mode": "project",
+      "path": "/workspace/modid"
+    },
+    "version": "1.21.10",
+    "projectPath": "/workspace/modid",
+    "preferProjectVersion": true,
+    "preferProjectMapping": true,
+    "reportMode": "compact",
+    "warningMode": "aggregated",
+    "includeIssues": false
   }
 }
 ```
@@ -735,7 +833,10 @@ Run the same validation settings against multiple Mixin source files:
       ]
     },
     "version": "1.21.10",
-    "mapping": "yarn"
+    "mapping": "yarn",
+    "reportMode": "compact",
+    "warningMode": "aggregated",
+    "includeIssues": false
   }
 }
 ```
@@ -765,7 +866,8 @@ Retrieve the full set of generated registries (blocks, items, entities, etc.) fo
 {
   "tool": "get-registry-data",
   "arguments": {
-    "version": "1.21.10"
+    "version": "1.21.10",
+    "includeData": false
   }
 }
 ```
@@ -779,7 +881,8 @@ Fetch only a specific registry type:
   "tool": "get-registry-data",
   "arguments": {
     "version": "1.21.10",
-    "registry": "minecraft:block"
+    "registry": "minecraft:block",
+    "maxEntriesPerRegistry": 50
   }
 }
 ```
@@ -809,6 +912,9 @@ Check server performance counters, cache sizes, and latency snapshots:
 }
 ```
 
+Cache entry counts and byte accounting are maintained incrementally during `resolve-artifact`, `index-artifact`, cache hits, and eviction, so `get-runtime-metrics` remains cheap even after repeated artifact loads.
+Repeated mapping-heavy workflows such as `find-mapping`, `get-class-api-matrix`, `resolve-workspace-symbol`, `check-symbol-exists`, and `validate-mixin` also reuse hot-path resolution work to keep large batches responsive.
+
 ## Mapping Policy
 
 ### Namespace Definitions
@@ -838,6 +944,9 @@ Symbol query inputs use `kind` + `name` + optional `owner`/`descriptor`:
 - for unobfuscated versions (for example 26.1+), requesting `intermediary` / `yarn` falls back to `obfuscated` with a warning.
 - `mojang` requires source-backed artifacts; decompile-only paths are rejected with `ERR_MAPPING_NOT_APPLIED`.
 
+When `trace-symbol-lifecycle` omits `descriptor`, the server resolves methods by owner+name and warns if overload ambiguity prevents a unique answer.
+For decompile-only `ERR_MAPPING_NOT_APPLIED` failures, error details include `artifactOrigin`, `nextAction`, and `suggestedCall` so clients can recover without guessing.
+
 If `find-class` or `get-class-source` returns no hit on an `obfuscated` artifact for names like `net.minecraft.world.item.Item`, the tool now warns that `obfuscated` means Mojang's obfuscated runtime names and recommends retrying with `mapping="mojang"` or translating via `find-mapping`.
 
 Method descriptor precision is best on Tiny-backed paths (`intermediary`/`yarn`). For `obfuscated <-> mojang`, Mojang `client_mappings` do not carry JVM descriptors, so descriptor queries may fallback to name matching and emit a warning.

package/dist/cache-registry.d.ts

@@ -0,0 +1,95 @@
+import { type PathRuntimeInfo } from "./path-converter.js";
+export declare const PUBLIC_CACHE_KINDS: readonly ["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap"];
+export type PublicCacheKind = (typeof PUBLIC_CACHE_KINDS)[number];
+export declare const CACHE_HEALTH_STATES: readonly ["healthy", "partial", "stale", "orphaned", "corrupt", "in_use"];
+export type CacheHealthState = (typeof CACHE_HEALTH_STATES)[number];
+export type CacheSelector = {
+    artifactId?: string;
+    version?: string;
+    jarPath?: string;
+    entryId?: string;
+    status?: CacheHealthState;
+    olderThan?: string;
+    mapping?: string;
+    scope?: string;
+    projectPath?: string;
+};
+export type CacheKindSummary = {
+    cacheKind: PublicCacheKind;
+    entryCount: number;
+    totalBytes: number;
+    status: CacheHealthState;
+};
+export type CacheEntry = {
+    cacheKind: PublicCacheKind;
+    entryId: string;
+    path: string;
+    sizeBytes: number;
+    status: CacheHealthState;
+    owner?: string;
+    meta?: Record<string, unknown>;
+};
+type CacheEntryPage = {
+    entries: CacheEntry[];
+    nextCursor?: string;
+};
+export type CacheRegistryConfig = {
+    cacheDir: string;
+    sqlitePath: string;
+    pathRuntimeInfo?: PathRuntimeInfo;
+};
+export interface CacheRegistry {
+    summarize(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+    }): Promise<{
+        kinds: Partial<Record<PublicCacheKind, CacheKindSummary>>;
+    }>;
+    listEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        limit?: number;
+        cursor?: string;
+    }): Promise<CacheEntryPage>;
+    inspectEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        limit?: number;
+    }): Promise<CacheEntry[]>;
+    verifyEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+    }): Promise<{
+        checkedEntries: number;
+        unhealthyEntries: number;
+        warnings: string[];
+    }>;
+    deleteEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        executionMode: "preview" | "apply";
+    }): Promise<{
+        deletedEntries: number;
+        deletedBytes: number;
+        warnings: string[];
+    }>;
+    pruneEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        executionMode: "preview" | "apply";
+    }): Promise<{
+        deletedEntries: number;
+        deletedBytes: number;
+        warnings: string[];
+    }>;
+    rebuildEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        executionMode: "preview" | "apply";
+    }): Promise<{
+        rebuiltEntries: number;
+        warnings: string[];
+    }>;
+}
+export declare function createCacheRegistry(config: CacheRegistryConfig): CacheRegistry;
+export {};