@adhisang/minecraft-modding-mcp 3.0.0 → 3.1.1

package/README.md

@@ -9,60 +9,54 @@
 
 ---
 
-`@adhisang/minecraft-modding-mcp` is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives AI assistants deep access to Minecraft's source code, mappings, and mod tooling.
+`@adhisang/minecraft-modding-mcp` is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives AI assistants structured access to Minecraft source code, mappings, mod JARs, registry data, and validation workflows.
 
-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.
+[MCP](https://modelcontextprotocol.io/) is an open protocol that lets AI assistants call external tools through a structured interface. This server works with Claude Desktop, Claude Code, VS Code, Codex CLI, Gemini CLI, and other MCP-capable clients.
 
 **35 tools** (6 entry + 29 expert) | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
 
 ## Features
 
-- **Source Exploration** — Browse and search decompiled Minecraft source code with line-level precision and cursor-paginated file listing
-- **Multi-Mapping Conversion** — Translate class, field, and method names between `obfuscated`, `mojang`, `intermediary`, and `yarn` namespaces
-- **Symbol Lifecycle Tracking** — Trace when a method or field first appeared, disappeared, or changed across Minecraft versions
-- **Mod JAR Analysis** — Extract metadata, dependencies, entrypoints, and Mixin configs from Fabric/Forge/NeoForge mod JARs
-- **Mixin & Access Widener Validation** — Parse and validate Mixin source and `.accesswidener` files against a target Minecraft version
-- **NBT Round-Trip** — Decode NBT binary to typed JSON, apply RFC 6902 patches, and re-encode back to NBT
-- **Registry Data** — Query generated registry snapshots (blocks, items, entities, etc.) for any Minecraft version
-- **Version Comparison** — Diff class signatures and registry entries between two Minecraft versions
-- **JAR Remapping** — Remap Fabric mod JARs from `intermediary` to `yarn` or `mojang` namespaces
-- **MCP Resources** — Access version lists, class source, artifact metadata, and mappings through URI-based resources
+- **Source Exploration**: browse and search decompiled Minecraft source code with line-level precision and cursor-paginated file listing
+- **Multi-Mapping Conversion**: translate class, field, and method names between `obfuscated`, `mojang`, `intermediary`, and `yarn`
+- **Version Comparison**: diff class signatures and registry entries between Minecraft versions
+- **Mod JAR Analysis**: extract metadata, dependencies, entrypoints, and Mixin configs from Fabric, Forge, and NeoForge mod JARs
+- **Mixin and Access Widener Validation**: validate source and `.accesswidener` files against a target Minecraft version
+- **NBT Round-Trip**: decode NBT binary to typed JSON, apply RFC 6902 patches, and encode it back to NBT
+- **Registry Data and Runtime Metrics**: query generated registry snapshots and inspect cache and latency counters
+- **MCP Resources**: expose versions, class source, artifact metadata, and mappings through URI-based resources
 
 ## Quick Start
 
-### Prerequisites
-- Node.js 22+
-- pnpm
+### Package Users
 
-### For Users (Installed Package)
-```bash
-npx @adhisang/minecraft-modding-mcp
-```
+Requirements:
 
-### CLI Agent Tools
+- Node.js 22+
+- Java is only required for `remap-mod-jar` and decompile or remap flows that need Vineflower or tiny-remapper
 
-#### Claude Code
+Start the server locally:
 
 ```bash
-claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
-claude mcp list
+npx -y @adhisang/minecraft-modding-mcp
 ```
 
-#### OpenAI Codex CLI
+If automatic JAR downloads are blocked in your environment, set `MCP_VINEFLOWER_JAR_PATH` and `MCP_TINY_REMAPPER_JAR_PATH` in the client configuration.
 
-```bash
-codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
-codex mcp list
-```
+### Client Setup
 
-The stdio transport auto-detects both newline-delimited and `Content-Length` framing, so Codex and newline-based MCP clients can use the same server command.
+CLI clients:
 
-The server now lazily initializes heavyweight source/index services on first MCP request, reducing initial process startup latency for clients that only perform handshake/tool discovery.
-To preserve handshake reliability across clients, startup does not eagerly pre-initialize `SourceService` before tool discovery.
+- `Claude Code`: `claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp`
+- `OpenAI Codex CLI`: `codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp`
 
-#### Gemini CLI
+Run `claude mcp list` or `codex mcp list` after registration to verify the server is available.
 
-Add the following to `~/.gemini/settings.json`:
+The stdio transport auto-detects both newline-delimited and `Content-Length` framing, so the same server command works across Codex and standard MCP clients.
+
+#### Claude Desktop
+
+Add the following to your `claude_desktop_config.json`:
 
 ```json
 {
@@ -75,59 +69,13 @@ Add the following to `~/.gemini/settings.json`:
 }
 ```
 
-Then run this command in Gemini CLI:
-
-```text
-/mcp list
-```
-
-### For Developers (Repository)
-```bash
-pnpm install
-```
-
-### Run (development)
-```bash
-pnpm dev
-```
-
-### Build + Run (distribution shape)
-```bash
-pnpm build
-pnpm start
-```
-
-### Validate
-```bash
-pnpm check
-pnpm test
-pnpm test:coverage
-```
-
-### Coverage
-```bash
-pnpm test:coverage
-```
-
-Coverage thresholds: `lines=80`, `branches=70`, `functions=80`.
-
-Generate LCOV output for Codecov upload:
-
-```bash
-pnpm test:coverage:lcov
-```
-
-GitHub Actions upload workflow: `.github/workflows/codecov.yml` (temporarily disabled; when enabled, it runs on `v*` tags and manual dispatch).
-
-### MCP Client Configuration
-
-#### Claude Desktop
+#### VS Code
 
-Add the following to your `claude_desktop_config.json`:
+Add the following to `.vscode/mcp.json` in your workspace:
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "minecraft-modding": {
       "command": "npx",
       "args": ["-y", "@adhisang/minecraft-modding-mcp"]
@@ -136,13 +84,13 @@ Add the following to your `claude_desktop_config.json`:
 }
 ```
 
-#### VS Code
+#### Gemini CLI
 
-Add the following to `.vscode/mcp.json` in your workspace:
+Add the following to `~/.gemini/settings.json`:
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "minecraft-modding": {
       "command": "npx",
       "args": ["-y", "@adhisang/minecraft-modding-mcp"]
@@ -151,6 +99,12 @@ Add the following to `.vscode/mcp.json` in your workspace:
 }
 ```
 
+Then run:
+
+```text
+/mcp list
+```
+
 #### Custom Environment
 
 Pass environment variables to override defaults:
@@ -170,853 +124,259 @@ 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.
+## Start Here
 
-### Source Exploration
-
-Tools for browsing Minecraft versions, resolving source artifacts, and reading/searching decompiled source code.
-
-| 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` |
-
-### Version Comparison & Symbol Tracking
-
-Tools for comparing class/registry changes across Minecraft versions and tracing symbol existence over time.
-
-| 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[]` |
-
-### Mapping & Symbols
-
-Tools for converting symbol names between namespaces and checking symbol existence.
-
-| 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[]` |
+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.
 
-### NBT Utilities
-
-Tools for decoding, patching, and encoding Java Edition NBT binary data using a typed JSON representation.
-
-| 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` |
-
-### Mod Analysis
-
-Tools for extracting metadata from mod JARs, decompiling mod source, searching mod code, and remapping mod namespaces.
-
-| 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[]` |
-
-### Validation
+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.
 
-Tools for validating Mixin source and Access Widener files against a target Minecraft version.
-
-| 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` |
-
-### Registry & Diagnostics
-
-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?`, `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
-
-`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.
-`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.
-`validate-mixin` distinguishes `target-mapping-failed` (warning, uncertain) from `target-not-found` (error) when class mapping fails.
-`validate-mixin` issues and `structuredWarnings` include `category` (`mapping`, `configuration`, `validation`, `resolution`, or `parse`) to distinguish setup/tooling/parser limits from real validation errors.
-`validate-mixin` supports post-filtering with `minSeverity`, `hideUncertain`, and `warningCategoryFilter`; `treatInfoAsWarning=false` suppresses info-level entries in `structuredWarnings`.
-`validate-mixin` 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; 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; 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.
-`search-class-source` uses `limit: 20` by default.
-`search-class-source` `queryMode` controls text search strategy: `auto` (default) uses indexed token search with literal fallback for separator queries, `token` keeps indexed token behavior only, and `literal` uses substring scan only.
-`search-class-source` with `match=regex` enforces `query.length <= 200` and a strict result cap of `100`.
-`search-class-source` now returns compact file hits without snippets, line windows, relation expansion, or `totalApprox`.
-Use `get-artifact-file` or `get-class-source` to inspect returned files after search.
-`search-class-source` `symbolKind` is only supported when `intent=symbol`.
-`get-artifact-file` byte truncation now preserves UTF-8 character boundaries, preventing replacement-character (`�`) corruption when `maxBytes` cuts through multibyte text.
-`search-class-source` `fileGlob` supports `*`, `**`, and `?`; recursive patterns such as `net/minecraft/**/*.java` are supported.
-`get-class-source` fallback matching enforces package compatibility and returns `ERR_CLASS_NOT_FOUND` when only name-colliding classes from other packages exist.
-`get-class-source` now falls back to the sibling binary artifact when a source-backed artifact is only partial (for example, merged Loom sources without `net.minecraft` entries); if that fallback still cannot produce source, the error now carries the partial-source context and suggests `get-class-api-matrix` instead of `find-class`.
-`get-class-source` warns when fallback source text is returned in a different namespace than the requested mapping; the source text itself is not remapped.
-`get-class-source` mode defaults to `metadata` (symbol outline only); `mode=snippet` auto-sets `maxLines=200` when no line range/max is provided; `mode=full` returns the entire source. `outputFile` writes the selected text and returns the file path in `outputFile`.
-Decompile fallback for `resolve-artifact`/`get-class-source` now invokes Vineflower with flags before positional `<input-jar> <output-dir>` arguments to avoid false `ERR_DECOMPILER_FAILED` outcomes on valid jars.
-`resolve-artifact` with `target.kind=jar` only auto-adopts the exact sibling `"<jar-basename>-sources.jar"`. Other adjacent `*-sources.jar` files are returned as `adjacentSourceCandidates` info only and are never auto-selected.
-When a resolved artifact comes from a `*-sources.jar`, `get-class-members` now keeps the sibling binary jar (for example `minecraft-merged-<version>.jar`) instead of treating the source jar as bytecode, and it now looks up the class in the resolved artifact namespace before remapping member names back to the requested mapping.
-For `target.kind=coordinate` with a classifier (`group:artifact:version:classifier`), local Maven source lookup checks `<artifact>-<version>-<classifier>-sources.jar` first and then `<artifact>-<version>-sources.jar`.
-Mod tool `jarPath` inputs are normalized to a canonical local `.jar` file path before existence checks, cache keying, and processing.
-`search-mod-source` enforces `query.length <= 200` and `limit <= 200`.
-`search-mod-source` detects source-only jars and searches `.java` entries directly without decompilation.
-`get-mod-class-source` supports `maxLines`, `maxChars`, and `outputFile` with truncation behavior aligned to `get-class-source`; when `outputFile` is set, the written file reflects applied truncation.
-`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 `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
-
-MCP resources provide URI-based access to Minecraft data, usable by any MCP client that supports the resource protocol.
-
-### Fixed Resources
-
-| Resource | URI | Description |
-| --- | --- | --- |
-| `versions-list` | `mc://versions/list` | List all available Minecraft versions with their metadata |
-| `runtime-metrics` | `mc://metrics` | Runtime metrics and performance counters for the MCP server |
-
-### Template Resources
-
-| Resource | URI Template | Description |
-| --- | --- | --- |
-| `class-source` | `mc://source/{artifactId}/{className}` | Java source code for a class within a resolved artifact |
-| `artifact-file` | `mc://artifact/{artifactId}/files/{filePath}` | Raw content of a file within a resolved artifact |
-| `find-mapping` | `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}` | Look up a mapping between two naming namespaces |
-| `class-members` | `mc://artifact/{artifactId}/members/{className}` | List constructors, methods, and fields for a class |
-| `artifact-metadata` | `mc://artifact/{artifactId}` | Metadata for a previously resolved artifact |
-
-`versions-list`, `runtime-metrics`, `find-mapping`, `class-members`, and `artifact-metadata` return structured JSON envelopes on success (`{ result, meta }`) and failure (`{ error, meta }`).
-`class-source` and `artifact-file` keep raw text responses on success, but still return structured JSON errors on failure.
-
-## Response Envelope
-
-All tools return exactly one of:
-
-- Success: `{ result: { ... }, meta: { requestId, tool, durationMs, warnings[] } }`
-- Failure: `{ error: { type, title, detail, status, code, instance, fieldErrors?, hints? }, meta: { requestId, tool, durationMs, warnings[] } }`
-
-JSON resources follow the same `result/error/meta` pattern. Text resources return plain text on success.
-The same JSON envelope is mirrored in MCP `structuredContent` for SDK-aware clients, and failures also set `isError=true`.
-
-## Examples
-
-### Source Exploration
-
-#### Resolve from Minecraft version
-```json
-{
-  "tool": "resolve-artifact",
-  "arguments": {
-    "target": {
-      "kind": "version",
-      "value": "1.21.10"
-    },
-    "mapping": "obfuscated",
-    "allowDecompile": true,
-    "projectPath": "/path/to/mod/workspace"
-  }
-}
-```
-
-#### Get class source with line window
-```json
-{
-  "tool": "get-class-source",
-  "arguments": {
-    "target": {
-      "type": "artifact",
-      "artifactId": "<artifact-id>"
-    },
-    "className": "net.minecraft.server.Main",
-    "startLine": 50,
-    "endLine": 180,
-    "maxLines": 80
-  }
-}
-```
-
-#### Search by method symbol
-```json
-{
-  "tool": "search-class-source",
-  "arguments": {
-    "artifactId": "<artifact-id>",
-    "query": "tickServer",
-    "intent": "symbol",
-    "match": "exact"
-  }
-}
-```
-
-#### Get class member list
-```json
-{
-  "tool": "get-class-members",
-  "arguments": {
-    "artifactId": "<artifact-id>",
-    "className": "net.minecraft.server.Main",
-    "mapping": "obfuscated",
-    "access": "all",
-    "includeInherited": true,
-    "maxMembers": 300
-  }
-}
-```
-
-#### List artifact files with prefix filter
-
-List source files under a specific package to understand project structure:
-
-```json
-{
-  "tool": "list-artifact-files",
-  "arguments": {
-    "artifactId": "<artifact-id>",
-    "prefix": "net/minecraft/world/level/",
-    "limit": 50
-  }
-}
-```
+| Tool | Start here for |
+| --- | --- |
+| `inspect-minecraft` | versions, artifacts, classes, files, and source search |
+| `analyze-symbol` | symbol existence checks, mapping conversion, lifecycle tracing, and workspace symbol resolution |
+| `compare-minecraft` | version-pair diffs, class diffs, registry diffs, and migration-oriented overviews |
+| `analyze-mod` | mod metadata, decompile/search flows, class source, and safe remap preview/apply |
+| `validate-project` | workspace summaries plus direct Mixin and Access Widener validation |
+| `manage-cache` | cache inventory, verification, and preview/apply cleanup workflows |
 
-### Version Comparison & Symbol Tracking
+### Workflow Notes
 
-#### Trace `Class.method` lifecycle
-```json
-{
-  "tool": "trace-symbol-lifecycle",
-  "arguments": {
-    "symbol": "net.minecraft.server.Main.tickServer",
-    "descriptor": "()V",
-    "fromVersion": "1.20.1",
-    "toVersion": "1.21.10",
-    "includeTimeline": true
-  }
-}
-```
+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).
 
-#### Diff one class across two versions
-```json
-{
-  "tool": "diff-class-signatures",
-  "arguments": {
-    "className": "net.minecraft.server.Main",
-    "fromVersion": "1.20.1",
-    "toVersion": "1.21.10",
-    "mapping": "obfuscated",
-    "includeFullDiff": false
-  }
-}
-```
-
-#### Compare two Minecraft versions
+- `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.
+- 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`.
 
-Get a high-level summary of what changed between two releases, including class additions/removals and registry diffs:
+### Inspect Minecraft source from a version
 
 ```json
 {
-  "tool": "compare-versions",
+  "tool": "inspect-minecraft",
   "arguments": {
-    "fromVersion": "1.20.4",
-    "toVersion": "1.21.10",
-    "category": "all",
-    "packageFilter": "net.minecraft.world",
-    "maxClassResults": 100
-  }
-}
-```
-
-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
-```json
-{
-  "tool": "find-mapping",
-  "arguments": {
-    "version": "1.21.10",
-    "kind": "class",
-    "name": "a.b.C",
-    "sourceMapping": "obfuscated",
-    "targetMapping": "mojang",
-    "sourcePriority": "loom-first",
-    "maxCandidates": 10,
-    "disambiguation": {
-      "ownerHint": "net.minecraft"
+    "task": "class-source",
+    "subject": {
+      "kind": "class",
+      "className": "net.minecraft.server.Main",
+      "artifact": {
+        "type": "resolve-target",
+        "target": {
+          "kind": "version",
+          "value": "1.21.10"
+        }
+      }
     }
   }
 }
 ```
 
-#### Lookup method mapping with descriptor
-```json
-{
-  "tool": "find-mapping",
-  "arguments": {
-    "version": "1.21.10",
-    "kind": "method",
-    "name": "tick",
-    "owner": "a.b.C",
-    "descriptor": "(I)V",
-    "sourceMapping": "obfuscated",
-    "targetMapping": "intermediary"
-  }
-}
-```
-
-#### Resolve exact method mapping
-```json
-{
-  "tool": "resolve-method-mapping-exact",
-  "arguments": {
-    "version": "1.21.10",
-    "name": "f",
-    "owner": "a.b.C",
-    "descriptor": "(Ljava/lang/String;)V",
-    "sourceMapping": "obfuscated",
-    "targetMapping": "mojang"
-  }
-}
-```
-
-#### Show class API mapping matrix
-```json
-{
-  "tool": "get-class-api-matrix",
-  "arguments": {
-    "version": "1.21.10",
-    "className": "a.b.C",
-    "classNameMapping": "obfuscated",
-    "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
-{
-  "tool": "resolve-workspace-symbol",
-  "arguments": {
-    "projectPath": "/path/to/mod/workspace",
-    "version": "1.21.10",
-    "kind": "method",
-    "name": "f",
-    "owner": "a.b.C",
-    "descriptor": "(Ljava/lang/String;)V",
-    "sourceMapping": "obfuscated"
-  }
-}
-```
-
-#### Check symbol existence
-```json
-{
-  "tool": "check-symbol-exists",
-  "arguments": {
-    "version": "1.21.10",
-    "kind": "method",
-    "name": "f",
-    "owner": "a.b.C",
-    "descriptor": "(I)V",
-    "sourceMapping": "obfuscated"
-  }
-}
-```
+### Map or check a symbol
 
-#### Check class existence by short name (`nameMode=auto`)
 ```json
 {
-  "tool": "check-symbol-exists",
+  "tool": "analyze-symbol",
   "arguments": {
+    "task": "map",
+    "subject": {
+      "kind": "method",
+      "owner": "net.minecraft.server.Main",
+      "name": "tickServer"
+    },
     "version": "1.21.10",
-    "kind": "class",
-    "name": "Blocks",
-    "nameMode": "auto",
-    "sourceMapping": "mojang"
+    "sourceMapping": "mojang",
+    "targetMapping": "intermediary",
+    "signatureMode": "name-only"
   }
 }
 ```
 
-### NBT Utilities
+### Summarize a mod JAR
 
-#### Decode Java NBT base64 to typed JSON
 ```json
 {
-  "tool": "nbt-to-json",
+  "tool": "analyze-mod",
   "arguments": {
-    "nbtBase64": "<base64-nbt>",
-    "compression": "auto"
+    "task": "summary",
+    "subject": {
+      "kind": "jar",
+      "jarPath": "/path/to/mymod-1.0.0.jar"
+    }
   }
 }
 ```
 
-#### Patch typed NBT JSON
-```json
-{
-  "tool": "nbt-apply-json-patch",
-  "arguments": {
-    "typedJson": {
-      "rootName": "Level",
-      "root": { "type": "compound", "value": {} }
-    },
-    "patch": [
-      { "op": "add", "path": "/root/value/name", "value": { "type": "string", "value": "Alex" } }
-    ]
-  }
-}
-```
+### Validate a workspace
 
-#### Encode typed JSON back to NBT base64
 ```json
 {
-  "tool": "json-to-nbt",
+  "tool": "validate-project",
   "arguments": {
-    "typedJson": {
-      "rootName": "Level",
-      "root": { "type": "compound", "value": {} }
+    "task": "project-summary",
+    "subject": {
+      "kind": "workspace",
+      "projectPath": "/workspace/modid",
+      "discover": ["mixins", "access-wideners"]
     },
-    "compression": "gzip"
-  }
-}
-```
-
-### Mod Analysis Workflow
-
-A typical mod analysis workflow progresses through metadata extraction, decompilation, source reading, and search:
-
-#### 1. Analyze mod metadata
-
-Extract loader type, mod ID, dependencies, and Mixin configurations from a mod JAR:
-
-```json
-{
-  "tool": "analyze-mod-jar",
-  "arguments": {
-    "jarPath": "/path/to/mymod-1.0.0.jar",
-    "includeClasses": true
+    "preferProjectVersion": true,
+    "preferProjectMapping": true
   }
 }
 ```
 
-#### 2. Decompile the mod JAR
+## Documentation
 
-Decompile all classes and optionally retrieve a specific class inline:
+- [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
 
-```json
-{
-  "tool": "decompile-mod-jar",
-  "arguments": {
-    "jarPath": "/path/to/mymod-1.0.0.jar",
-    "includeFiles": false,
-    "className": "com.example.mymod.MyMod"
-  }
-}
-```
+## Tool Surface
 
-#### 3. Read a specific class from decompiled source
+Start with these top-level workflow tools unless you already know the exact specialized operation you want. The lower-level tools remain available for narrow follow-up work and automation.
 
-After decompilation, read any class without re-decompiling:
+### Top-Level Workflow Tools
 
-```json
-{
-  "tool": "get-mod-class-source",
-  "arguments": {
-    "jarPath": "/path/to/mymod-1.0.0.jar",
-    "className": "com.example.mymod.mixin.PlayerMixin",
-    "maxLines": 120
-  }
-}
-```
-
-#### 4. Search across decompiled mod source
-
-Find method references, field usages, or text patterns across the entire decompiled mod:
+<!-- BEGIN GENERATED TOOL TABLE: v3-entry-tools -->
+| 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 -->
 
-```json
-{
-  "tool": "search-mod-source",
-  "arguments": {
-    "jarPath": "/path/to/mymod-1.0.0.jar",
-    "query": "onPlayerTick",
-    "searchType": "method",
-    "limit": 50
-  }
-}
-```
+### Source Exploration
 
-#### 5. Remap mod JAR to readable names
+Tools for browsing Minecraft versions, resolving source artifacts, and reading or searching decompiled source code.
 
-Remap a Fabric mod from `intermediary` to `yarn` names for easier reading:
+<!-- BEGIN GENERATED TOOL TABLE: source-exploration -->
+| 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 -->
 
-```json
-{
-  "tool": "remap-mod-jar",
-  "arguments": {
-    "inputJar": "/path/to/mymod-1.0.0.jar",
-    "targetMapping": "yarn",
-    "mcVersion": "1.21.10"
-  }
-}
-```
+### Version Comparison & Symbol Tracking
 
-If the input jar was already built with Mojang mappings, use `targetMapping: "mojang"` to get a copied output jar and a `fromMapping: "mojang"` result.
+Tools for comparing class and registry changes across Minecraft versions and tracing symbol existence over time.
 
-### Validation
+<!-- BEGIN GENERATED TOOL TABLE: version-comparison-symbol-tracking -->
+| 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 -->
 
-#### Validate Mixin source
+### Mapping & Symbols
 
-Check a Mixin class source for correctness against a target Minecraft version:
+Tools for converting symbol names between namespaces and checking symbol existence.
 
-```json
-{
-  "tool": "validate-mixin",
-  "arguments": {
-    "input": {
-      "mode": "inline",
-      "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",
-    "reportMode": "compact",
-    "warningMode": "aggregated",
-    "includeIssues": false
-  }
-}
-```
+<!-- BEGIN GENERATED TOOL TABLE: mapping-symbols -->
+| 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 -->
 
-#### Validate all Mixins in a project
+### NBT Utilities
 
-Discover `*.mixins.json` files from a workspace root and validate every referenced Mixin in one call:
+Tools for decoding, patching, and encoding Java Edition NBT binary data using a typed JSON representation.
 
-```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
-  }
-}
-```
+<!-- BEGIN GENERATED TOOL TABLE: nbt-utilities -->
+| 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 -->
 
-#### Validate multiple Mixin files (batch)
+### Mod Analysis
 
-Run the same validation settings against multiple Mixin source files:
+Tools for extracting metadata from mod JARs, decompiling mod source, searching mod code, and remapping mod namespaces.
 
-```json
-{
-  "tool": "validate-mixin",
-  "arguments": {
-    "input": {
-      "mode": "paths",
-      "paths": [
-        "/path/to/PlayerMixin.java",
-        "/path/to/WorldMixin.java"
-      ]
-    },
-    "version": "1.21.10",
-    "mapping": "yarn",
-    "reportMode": "compact",
-    "warningMode": "aggregated",
-    "includeIssues": false
-  }
-}
-```
+<!-- BEGIN GENERATED TOOL TABLE: mod-analysis -->
+| 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 -->
 
-#### Validate Access Widener
+### Validation
 
-Check an Access Widener file for valid entries against the target version:
+Tools for validating Mixin source and Access Widener files against a target Minecraft version.
 
-```json
-{
-  "tool": "validate-access-widener",
-  "arguments": {
-    "content": "accessWidener v2 named\naccessible class net/minecraft/server/Main\naccessible method net/minecraft/server/Main tick ()V",
-    "version": "1.21.10",
-    "mapping": "yarn"
-  }
-}
-```
+<!-- BEGIN GENERATED TOOL TABLE: validation -->
+| 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
 
-#### Get all registries for a version
+Tools for querying generated registry data and inspecting server runtime state.
 
-Retrieve the full set of generated registries (blocks, items, entities, etc.) for a Minecraft version:
+<!-- BEGIN GENERATED TOOL TABLE: registry-diagnostics -->
+| 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 -->
 
-```json
-{
-  "tool": "get-registry-data",
-  "arguments": {
-    "version": "1.21.10",
-    "includeData": false
-  }
-}
-```
+Detailed parameter constraints, migration notes, resource behavior, and the full environment-variable matrix live in [docs/tool-reference.md](docs/tool-reference.md).
 
-#### Get a single registry
+## Development
 
-Fetch only a specific registry type:
+Repository requirements:
 
-```json
-{
-  "tool": "get-registry-data",
-  "arguments": {
-    "version": "1.21.10",
-    "registry": "minecraft:block",
-    "maxEntriesPerRegistry": 50
-  }
-}
-```
-
-#### Force reindex an artifact
+- Node.js 22+
+- `pnpm`
+- Java when running remap or decompile flows locally
 
-Rebuild the search index for an artifact after cache or tooling changes:
+Setup and run the repository:
 
-```json
-{
-  "tool": "index-artifact",
-  "arguments": {
-    "artifactId": "<artifact-id>",
-    "force": true
-  }
-}
+```bash
+pnpm install
+pnpm dev
 ```
 
-#### Inspect runtime metrics
-
-Check server performance counters, cache sizes, and latency snapshots:
+Build the packaged shape:
 
-```json
-{
-  "tool": "get-runtime-metrics",
-  "arguments": {}
-}
+```bash
+pnpm build
+pnpm start
 ```
 
-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
-
-| Namespace | Description |
-| --- | --- |
-| `obfuscated` | Mojang obfuscated names (e.g. `a`, `b`, `c`) |
-| `mojang` | Mojang deobfuscated names from `client_mappings.txt` (e.g. `net.minecraft.server.Main`) |
-| `intermediary` | Fabric stable intermediary names (e.g. `net.minecraft.class_1234`, `method_5678`) |
-| `yarn` | Fabric community human-readable names (e.g. `net.minecraft.server.MinecraftServer`, `tick`) |
-
-The legacy public namespace name `official` was removed. Requests that still send `official` now fail validation and should be updated to `obfuscated`.
+Always run:
 
-### Lookup Rules
-
-`find-mapping` supports lookup across `obfuscated`, `mojang`, `intermediary`, and `yarn`.
-
-Symbol query inputs use `kind` + `name` + optional `owner`/`descriptor`:
-- class: `kind=class`, `name=a.b.C` (default FQCN). For existence checks only, `nameMode=auto` allows short names like `C`.
-- field: `kind=field`, `owner=a.b.C`, `name=fieldName`
-- method: `kind=method`, `owner=a.b.C`, `name=methodName`, `descriptor=(I)V`
-
-`mapping: "mojang"` requires a source-backed artifact. If only decompile path is available, the server returns `ERR_MAPPING_NOT_APPLIED`.
-
-`resolve-artifact`, `get-class-members`, `trace-symbol-lifecycle`, and `diff-class-signatures` accept `obfuscated | mojang | intermediary | yarn` with constraints:
-- `intermediary` / `yarn` require a resolvable Minecraft version context (for example `target.kind=version` or a versioned coordinate).
-- 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.
-
-Use `resolve-method-mapping-exact` when candidate ranking is not enough and the workflow needs strict `owner+name+descriptor` certainty.
-Use `find-mapping` `disambiguation.ownerHint` / `disambiguation.descriptorHint` to narrow ambiguous candidate sets.
-Use `resolve-workspace-symbol` when you need compile-visible names from actual Gradle Loom mappings in a workspace.
-
-## Environment Variables
-
-### Core
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `MCP_CACHE_DIR` | `~/.cache/minecraft-modding-mcp` | Cache root for downloads and SQLite |
-| `MCP_SQLITE_PATH` | `<cacheDir>/source-cache.db` | SQLite database path |
-| `MCP_SOURCE_REPOS` | Maven Central + Fabric + Forge + NeoForge | Comma-separated Maven repository URLs |
-| `MCP_LOCAL_M2` | `~/.m2/repository` | Local Maven repository path |
-| `MCP_ENABLE_INDEXED_SEARCH` | `true` | Enable indexed query path for `search-class-source` |
-| `MCP_MAPPING_SOURCE_PRIORITY` | `loom-first` | Mapping source priority (`loom-first` or `maven-first`) |
-| `MCP_VERSION_MANIFEST_URL` | Mojang manifest URL | Override manifest endpoint for testing/private mirrors |
-
-### Limits & Tuning
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `MCP_MAX_CONTENT_BYTES` | `1000000` | Maximum bytes for file read operations |
-| `MCP_MAX_SEARCH_HITS` | `200` | Maximum search result count |
-| `MCP_MAX_ARTIFACTS` | `200` | Maximum cached artifacts |
-| `MCP_MAX_CACHE_BYTES` | `2147483648` | Maximum total cache size in bytes |
-| `MCP_FETCH_TIMEOUT_MS` | `15000` | HTTP request timeout in milliseconds |
-| `MCP_FETCH_RETRIES` | `2` | HTTP request retry count |
-
-### Decompilation & Remapping
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `MCP_VINEFLOWER_JAR_PATH` | unset | External Vineflower JAR path (auto-downloaded if unset) |
-| `MCP_TINY_REMAPPER_JAR_PATH` | unset | External tiny-remapper JAR path (auto-downloaded if unset) |
-| `MCP_REMAP_TIMEOUT_MS` | `600000` | Remap operation timeout in milliseconds |
-| `MCP_REMAP_MAX_MEMORY_MB` | `4096` | Maximum JVM heap for remap operations |
-
-### NBT
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `MCP_MAX_NBT_INPUT_BYTES` | `4194304` | Maximum decoded NBT input bytes accepted by `nbt-to-json` |
-| `MCP_MAX_NBT_INFLATED_BYTES` | `16777216` | Maximum gzip-inflated bytes accepted by `nbt-to-json` |
-| `MCP_MAX_NBT_RESPONSE_BYTES` | `8388608` | Maximum response payload bytes for NBT tools |
+```bash
+pnpm check
+pnpm test
+```
 
-## Architecture
+Run these when relevant:
 
-| Component | Technology |
-| --- | --- |
-| Runtime | Node.js 22+ (native `node:sqlite`) |
-| Transport | stdio (MCP standard, auto-detects newline + `Content-Length` framing) |
-| Storage | SQLite — artifact metadata, source index, mapping cache |
-| Decompilation | [Vineflower](https://github.com/Vineflower/vineflower) (auto-downloaded) |
-| Remapping | [tiny-remapper](https://github.com/FabricMC/tiny-remapper) (requires Java) |
-| Mapping Sources | Mojang `client_mappings.txt`, Fabric Loom workspace, Maven Tiny v2 |
-
-The server runs as a single long-lived process communicating over stdio. Artifacts (source JARs, binary JARs, mapping files) are downloaded on demand and cached in SQLite. The search index is built lazily on first query and persisted for subsequent calls.
-
-## Development Notes
-
-- `SourceService` is the canonical implementation for artifact resolution, ingestion, and source querying.
-- `version` resolution downloads Mojang client JARs into cache and routes them through the same ingestion flow as `jar` and `coordinate` targets.
-- Tool responses are always wrapped as `{ result?, error?, meta }`.
-- Tool responses also mirror that envelope into MCP `structuredContent`, and failures set `isError=true`.
-- `meta` includes `requestId`, `tool`, `durationMs`, and `warnings[]`.
+- `pnpm test:manual:stdio-smoke` for MCP transport, registration, or manual workflow changes
+- `pnpm test:manual:package-smoke` when checking packaged install and distribution behavior
+- `pnpm test:perf` for search, index, or performance-sensitive changes
+- `pnpm test:coverage` or `pnpm test:coverage:lcov` for coverage checks (`lines=80`, `branches=70`, `functions=80`)
+- `pnpm validate` for the full local validation suite
 
 ## License