@adhisang/minecraft-modding-mcp 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [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
@@ -16,15 +41,11 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 - 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/path scan fallbacks no longer materialize the full scoped file-path list before scanning, reducing heap growth and keeping full-scan cost more predictable on large artifacts.
-- Runtime metrics now keep cache LRU byte-accounting rows by reference and only materialize `cache_artifact_bytes_lru` during snapshot reads, removing per-publish array copies from the cache hit path.
+- Explicit text and path scan fallbacks in `search-class-source` now use less memory and stay more predictable on large artifacts.
 
 ### Documentation
-- README tool tables are now validated from a shared contract manifest in code, correcting the documented `compare-minecraft` class-only `subject.kind="class".sourcePriority` input and aligning the published `inspect-minecraft` / `validate-project` output summaries with the implementation.
-- Clarified the updated `search-class-source` `queryMode` behavior and the summary-first follow-up contract for the top-level workflow tools in both READMEs.
+- 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.
-- Reorganized the English README around package-user quick start, start-here examples, and linked reference docs so setup guidance is easier to scan without losing detailed contract notes.
-- Synchronized the Japanese README with the current English README structure, examples, quick-start guidance, and tool-surface summary.
 
 ## [3.0.0] - 2026-03-09
 
@@ -33,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.
@@ -56,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.
@@ -70,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.
@@ -80,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
 
@@ -102,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.
@@ -112,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
@@ -165,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
 
@@ -180,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.

package/README.md

@@ -128,6 +128,8 @@ Pass environment variables to override defaults:
 
 These six top-level workflow tools cover the common workflows and return summary-first results, so they are the best default starting points for agents and MCP clients.
 
+All six return `result.summary` first, and can include `summary.nextActions` when there is a clear follow-up step. Use the table for tool selection, then use the examples and reference docs for exact payloads.
+
 | Tool | Start here for |
 | --- | --- |
 | `inspect-minecraft` | versions, artifacts, classes, files, and source search |
@@ -139,10 +141,13 @@ These six top-level workflow tools cover the common workflows and return summary
 
 ### Workflow Notes
 
-- These top-level workflow tools return `result.summary` first and include `summary.nextActions` when there is a clear follow-up step.
+Keep only the high-frequency notes here. For the full pitfall list, exact contract details, migration notes, and environment variables, see [docs/tool-reference.md](docs/tool-reference.md).
+
 - `search-class-source` defaults to `queryMode="auto"` and keeps separator queries such as `foo.bar`, `foo_bar`, and `foo$bar` on the indexed path. Use `queryMode="literal"` for an explicit full substring scan.
-- When a public parameter has a fixed safe default, `tools/list` exposes it through the JSON Schema `default` field.
-- Error recovery `suggestedCall` payloads omit parameters when the supplied value already matches the tool default, keeping retry calls smaller without changing behavior.
+- If you do not already have an artifact, prefer `subject.kind="workspace"` for `inspect-minecraft` instead of guessing artifact details. When artifact context is the only missing input, a retryable `suggestedCall` preserves the requested task.
+- `trace-symbol-lifecycle` expects `Class.method` in `symbol`. Keep exact overload matching in the separate `descriptor` field.
+- Workspace inspection can still confirm vanilla classes when source coverage is partial, and `inspect-minecraft task="list-files"` reports a partial result with follow-up guidance when that happens.
+- `analyze-mod` and `validate-project` still require structured `subject` objects and canonical `include` groups, but stale string-subject or domain-include payloads now return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
 
 ### Inspect Minecraft source from a version
 
@@ -221,9 +226,9 @@ These six top-level workflow tools cover the common workflows and return summary
 
 ## Documentation
 
-- [Detailed example requests](docs/examples.md)
-- [Tool and configuration reference](docs/tool-reference.md)
-- [日本語 README](docs/README-ja.md)
+- [Detailed example requests](docs/examples.md) for copyable payloads and common workflows
+- [Tool and configuration reference](docs/tool-reference.md) for exact inputs, outputs, resource behavior, environment variables, and migration notes
+- [日本語 README](docs/README-ja.md) for a Japanese onboarding overview
 
 ## Tool Surface
 
@@ -232,14 +237,14 @@ Start with these top-level workflow tools unless you already know the exact spec
 ### Top-Level Workflow Tools
 
 <!-- BEGIN GENERATED TOOL TABLE: v3-entry-tools -->
-| 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`, `versions?`, `subject`, `artifact?`, `class?`, `source?`, `members?`, `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?`, `subject.kind="class".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?` |
-| `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?` |
+| Tool | Purpose |
+| --- | --- |
+| `inspect-minecraft` | Inspect versions, artifacts, classes, files, source text, and workspace-aware lookup flows |
+| `analyze-symbol` | Handle symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol resolution, and API overviews |
+| `compare-minecraft` | Compare version pairs, class diffs, registry diffs, and migration-oriented summaries |
+| `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, and preview or apply remaps |
+| `validate-project` | Summarize workspaces and run direct Mixin or Access Widener validation |
+| `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |
 <!-- END GENERATED TOOL TABLE: v3-entry-tools -->
 
 ### Source Exploration
@@ -247,17 +252,17 @@ Start with these top-level workflow tools unless you already know the exact spec
 Tools for browsing Minecraft versions, resolving source artifacts, and reading or searching decompiled source code.
 
 <!-- BEGIN GENERATED TOOL TABLE: source-exploration -->
-| 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[]`, `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?`, `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` |
+| Tool | Purpose |
+| --- | --- |
+| `list-versions` | List available Minecraft versions from Mojang metadata and local cache |
+| `resolve-artifact` | Resolve source artifacts from versions, JAR paths, or Maven coordinates |
+| `find-class` | Find simple or fully-qualified class names inside an artifact |
+| `get-class-source` | Read class source from an artifact or resolve the backing artifact on demand |
+| `get-class-members` | List constructors, fields, and methods from bytecode |
+| `search-class-source` | Search indexed class source by symbol, text, or path |
+| `get-artifact-file` | Read a full source file with a byte limit |
+| `list-artifact-files` | List indexed source file paths with cursor pagination |
+| `index-artifact` | Rebuild indexed metadata for an existing artifact |
 <!-- END GENERATED TOOL TABLE: source-exploration -->
 
 ### Version Comparison & Symbol Tracking
@@ -265,11 +270,11 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading o
 Tools for comparing class and registry changes across Minecraft versions and tracing symbol existence over time.
 
 <!-- BEGIN GENERATED TOOL TABLE: version-comparison-symbol-tracking -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `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[]` |
+| Tool | Purpose |
+| --- | --- |
+| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions |
+| `diff-class-signatures` | Compare one class across two versions and return member deltas |
+| `compare-versions` | Compare class and registry changes between two versions |
 <!-- END GENERATED TOOL TABLE: version-comparison-symbol-tracking -->
 
 ### Mapping & Symbols
@@ -277,13 +282,13 @@ Tools for comparing class and registry changes across Minecraft versions and tra
 Tools for converting symbol names between namespaces and checking symbol existence.
 
 <!-- BEGIN GENERATED TOOL TABLE: mapping-symbols -->
-| 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?`, `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[]` |
+| Tool | Purpose |
+| --- | --- |
+| `find-mapping` | Look up mapping candidates for class, field, or method symbols |
+| `resolve-method-mapping-exact` | Resolve one method mapping with strict owner, name, and descriptor matching |
+| `get-class-api-matrix` | Show one class API across `obfuscated`, `mojang`, `intermediary`, and `yarn` |
+| `resolve-workspace-symbol` | Resolve compile-visible symbol names from a Gradle workspace |
+| `check-symbol-exists` | Check whether a class, field, or method exists in a namespace |
 <!-- END GENERATED TOOL TABLE: mapping-symbols -->
 
 ### NBT Utilities
@@ -291,11 +296,11 @@ Tools for converting symbol names between namespaces and checking symbol existen
 Tools for decoding, patching, and encoding Java Edition NBT binary data using a typed JSON representation.
 
 <!-- BEGIN GENERATED TOOL TABLE: nbt-utilities -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `nbt-to-json` | Decode Java Edition NBT binary (`base64`) to typed JSON | `nbtBase64`, `compression?` (`none`, `gzip`, `auto`) | `typedJson`, `meta.compressionDetected`, `meta.inputBytes` |
-| `nbt-apply-json-patch` | Apply RFC 6902 patch (`add/remove/replace/test`) to typed NBT JSON | `typedJson`, `patch` | `typedJson`, `meta.appliedOps`, `meta.testOps`, `meta.changed` |
-| `json-to-nbt` | Encode typed JSON back to Java Edition NBT binary (`base64`) | `typedJson`, `compression?` (`none`, `gzip`) | `nbtBase64`, `meta.outputBytes`, `meta.compressionApplied` |
+| Tool | Purpose |
+| --- | --- |
+| `nbt-to-json` | Decode Java Edition NBT binary payloads into typed JSON |
+| `nbt-apply-json-patch` | Apply RFC 6902 patches to typed NBT JSON |
+| `json-to-nbt` | Encode typed JSON back to Java Edition NBT binary |
 <!-- END GENERATED TOOL TABLE: nbt-utilities -->
 
 ### Mod Analysis
@@ -303,13 +308,13 @@ Tools for decoding, patching, and encoding Java Edition NBT binary data using a
 Tools for extracting metadata from mod JARs, decompiling mod source, searching mod code, and remapping mod namespaces.
 
 <!-- BEGIN GENERATED TOOL TABLE: mod-analysis -->
-| 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?`, `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/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[]` |
+| Tool | Purpose |
+| --- | --- |
+| `analyze-mod-jar` | Extract mod metadata, dependencies, entrypoints, and mixin config info from a JAR |
+| `decompile-mod-jar` | Decompile a mod JAR and optionally return one class source |
+| `get-mod-class-source` | Read one class source from the decompiled mod cache |
+| `search-mod-source` | Search decompiled mod source by class, method, field, or content |
+| `remap-mod-jar` | Remap a Fabric or Quilt mod JAR to `yarn` or `mojang` names |
 <!-- END GENERATED TOOL TABLE: mod-analysis -->
 
 ### Validation
@@ -317,10 +322,10 @@ Tools for extracting metadata from mod JARs, decompiling mod source, searching m
 Tools for validating Mixin source and Access Widener files against a target Minecraft version.
 
 <!-- BEGIN GENERATED TOOL TABLE: validation -->
-| 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?`, `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` |
+| Tool | Purpose |
+| --- | --- |
+| `validate-mixin` | Validate Mixin source against a target Minecraft version |
+| `validate-access-widener` | Validate Access Widener content against a target Minecraft version |
 <!-- END GENERATED TOOL TABLE: validation -->
 
 ### Registry & Diagnostics
@@ -328,52 +333,14 @@ Tools for validating Mixin source and Access Widener files against a target Mine
 Tools for querying generated registry data and inspecting server runtime state.
 
 <!-- BEGIN GENERATED TOOL TABLE: registry-diagnostics -->
-| Tool | Purpose | Key Inputs | Key Outputs |
-| --- | --- | --- | --- |
-| `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 | Purpose |
+| --- | --- |
+| `get-registry-data` | Read generated registry snapshots and optionally include entry data |
+| `get-runtime-metrics` | Inspect runtime metrics and latency snapshots |
 <!-- END GENERATED TOOL TABLE: registry-diagnostics -->
 
 Detailed parameter constraints, migration notes, resource behavior, and the full environment-variable matrix live in [docs/tool-reference.md](docs/tool-reference.md).
 
-## Resources
-
-Fixed resources:
-
-- `mc://versions/list`
-- `mc://metrics`
-
-Template resources:
-
-- `mc://source/{artifactId}/{className}`
-- `mc://artifact/{artifactId}/files/{filePath}`
-- `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}`
-- `mc://artifact/{artifactId}/members/{className}`
-- `mc://artifact/{artifactId}`
-
-See [docs/tool-reference.md#resources](docs/tool-reference.md#resources) for the full resource table and response behavior.
-
-## Response Model
-
-Tools and JSON resources return the standard `{ result?, error?, meta }` envelope. Text resources (`class-source` and `artifact-file`) return raw text on success and structured JSON on failure.
-
-See [docs/tool-reference.md#response-envelope](docs/tool-reference.md#response-envelope) for the exact envelope fields and error shape.
-
-## Common Environment Variables
-
-These are the most commonly changed settings. For the full supported list, see [docs/tool-reference.md#environment-variables](docs/tool-reference.md#environment-variables).
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `MCP_CACHE_DIR` | `~/.cache/minecraft-modding-mcp` | Cache root for downloads and SQLite |
-| `MCP_SOURCE_REPOS` | Maven Central + Fabric + Forge + NeoForge | Comma-separated Maven repository URLs |
-| `MCP_MAPPING_SOURCE_PRIORITY` | `loom-first` | Mapping source priority (`loom-first` or `maven-first`) |
-| `MCP_ENABLE_INDEXED_SEARCH` | `true` | Enable indexed search for `search-class-source` |
-| `MCP_VINEFLOWER_JAR_PATH` | unset | Override the Vineflower JAR path |
-| `MCP_TINY_REMAPPER_JAR_PATH` | unset | Override the tiny-remapper JAR path |
-| `MCP_MAX_SEARCH_HITS` | `200` | Maximum search result count |
-| `MCP_MAX_CACHE_BYTES` | `2147483648` | Maximum total cache size in bytes |
-
 ## Development
 
 Repository requirements:

package/dist/config.js

@@ -52,6 +52,17 @@ function expandHome(pathValue) {
     const withoutTilde = pathValue.startsWith("~/") ? pathValue.slice(2) : pathValue.slice(1);
     return resolve(homedir(), withoutTilde);
 }
+function normalizeOptionalPathEnvValue(pathValue) {
+    if (!pathValue) {
+        return undefined;
+    }
+    const trimmed = pathValue.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const normalized = trimmed.toLowerCase();
+    return normalized === "undefined" || normalized === "null" ? undefined : trimmed;
+}
 function normalizePath(pathValue, field) {
     const expanded = expandHome(pathValue.trim());
     const normalizedForHost = normalizePathForHost(expanded, undefined, field);
@@ -120,14 +131,11 @@ function parseMappingSourcePriority(envValue) {
     return DEFAULTS.mappingSourcePriority;
 }
 function parseOptionalJarPath(envValue, field) {
-    if (!envValue) {
-        return undefined;
-    }
-    const trimmed = envValue.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    return normalizePath(trimmed, field);
+    const trimmed = normalizeOptionalPathEnvValue(envValue);
+    return trimmed ? normalizePath(trimmed, field) : undefined;
+}
+function parseRequiredPath(envValue, fallback, field) {
+    return normalizePath(normalizeOptionalPathEnvValue(envValue) ?? fallback, field);
 }
 function parseVineflowerPath(envValue) {
     return parseOptionalJarPath(envValue, "MCP_VINEFLOWER_JAR_PATH");
@@ -137,12 +145,12 @@ function buildArtifactsDirectory(cacheDir) {
     return normalizePath(input, "MCP_SQLITE_PATH");
 }
 export function loadConfig() {
-    const cacheDir = normalizePath(process.env.MCP_CACHE_DIR ?? DEFAULTS.cacheDir, "MCP_CACHE_DIR");
-    const localM2Path = normalizePath(process.env.MCP_LOCAL_M2 ?? DEFAULTS.localM2Path, "MCP_LOCAL_M2");
+    const cacheDir = parseRequiredPath(process.env.MCP_CACHE_DIR, DEFAULTS.cacheDir, "MCP_CACHE_DIR");
+    const localM2Path = parseRequiredPath(process.env.MCP_LOCAL_M2, DEFAULTS.localM2Path, "MCP_LOCAL_M2");
     const sourceRepos = parseRepos(process.env.MCP_SOURCE_REPOS);
     return {
         cacheDir,
-        sqlitePath: normalizePath(process.env.MCP_SQLITE_PATH ?? buildArtifactsDirectory(cacheDir), "MCP_SQLITE_PATH"),
+        sqlitePath: parseRequiredPath(process.env.MCP_SQLITE_PATH, buildArtifactsDirectory(cacheDir), "MCP_SQLITE_PATH"),
         sourceRepos,
         localM2Path,
         vineflowerJarPath: parseVineflowerPath(process.env.MCP_VINEFLOWER_JAR_PATH),

package/dist/entry-tools/analyze-symbol-service.d.ts

@@ -180,6 +180,8 @@ type AnalyzeSymbolDeps = {
         symbol: string;
         descriptor?: string;
         mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn";
+        toVersion?: string;
+        maxVersions?: number;
     }) => Promise<TraceSymbolLifecycleOutput>;
     resolveWorkspaceSymbol: (input: {
         projectPath: string;

package/dist/entry-tools/analyze-symbol-service.js

@@ -231,7 +231,9 @@ export class AnalyzeSymbolService {
                         ? `${input.subject.owner}.${input.subject.name}`
                         : input.subject.name,
                     descriptor: input.subject.descriptor,
-                    mapping: input.sourceMapping
+                    mapping: input.sourceMapping,
+                    toVersion: input.version,
+                    maxVersions: 5
                 });
                 return {
                     ...buildEntryToolResult({
@@ -309,10 +311,11 @@ export class AnalyzeSymbolService {
                 };
             }
             case "api-overview": {
+                const classNameMapping = input.classNameMapping ?? input.sourceMapping ?? "obfuscated";
                 const output = await this.deps.getClassApiMatrix({
                     version: input.version,
                     className: input.subject.name,
-                    classNameMapping: input.classNameMapping ?? "obfuscated",
+                    classNameMapping,
                     includeKinds: input.includeKinds,
                     maxRows: input.maxRows
                 });
@@ -329,7 +332,7 @@ export class AnalyzeSymbolService {
                                 kind: input.subject.kind,
                                 name: input.subject.name,
                                 version: input.version,
-                                classNameMapping: input.classNameMapping ?? "obfuscated"
+                                classNameMapping
                             }),
                             counts: {
                                 rows: output.rowCount,

package/dist/entry-tools/inspect-minecraft-service.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { FindClassOutput, GetArtifactFileOutput, GetClassMembersOutput, GetClassSourceOutput, ListArtifactFilesOutput, ResolveArtifactOutput, SearchClassSourceOutput } from "../source-service.js";
+import type { CheckSymbolExistsOutput, FindClassOutput, GetArtifactFileOutput, GetClassMembersOutput, GetClassSourceOutput, ListArtifactFilesOutput, ResolveArtifactOutput, SearchClassSourceOutput } from "../source-service.js";
 import type { ListVersionsOutput } from "../version-service.js";
 export declare const inspectMinecraftShape: {
     task: z.ZodOptional<z.ZodEnum<["auto", "versions", "artifact", "class-overview", "class-source", "class-members", "search", "file", "list-files"]>>;
@@ -1869,6 +1869,18 @@ type InspectMinecraftDeps = {
         artifactId: string;
         limit?: number;
     }) => Promise<FindClassOutput>;
+    checkSymbolExists?: (input: {
+        version: string;
+        kind: "class" | "field" | "method";
+        name: string;
+        owner?: string;
+        descriptor?: string;
+        sourceMapping: "obfuscated" | "mojang" | "intermediary" | "yarn";
+        sourcePriority?: "loom-first" | "maven-first";
+        nameMode?: "fqcn" | "auto";
+        signatureMode?: "exact" | "name-only";
+        maxCandidates?: number;
+    }) => Promise<CheckSymbolExistsOutput>;
     getClassSource: (input: {
         className: string;
         artifactId?: string;
@@ -1940,6 +1952,11 @@ export declare class InspectMinecraftService {
     private resolveWorkspaceArtifactReference;
     private resolveTask;
     private summarizeRequestedSubject;
+    private exampleVersionForSubject;
+    private buildArtifactContextSuggestedCall;
+    private taskForSubject;
+    private invalidTaskSubjectError;
+    private resolveBinaryBackedClass;
     private resolveArtifactReference;
     private resolveArtifactRef;
     private handleVersions;