@adhisang/minecraft-modding-mcp 2.1.0 → 3.1.0

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.
 
-**29 tools** | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
+**35 tools** (6 entry + 29 expert) | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
 
 ## Features
 
-- **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,38 +124,159 @@ Pass environment variables to override defaults:
 }
 ```
 
+## Start Here
+
+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.
+
+| 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 |
+
+### Workflow Notes
+
+- These top-level workflow tools return `result.summary` first and include `summary.nextActions` when there is a clear follow-up step.
+- `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.
+
+### Inspect Minecraft source from a version
+
+```json
+{
+  "tool": "inspect-minecraft",
+  "arguments": {
+    "task": "class-source",
+    "subject": {
+      "kind": "class",
+      "className": "net.minecraft.server.Main",
+      "artifact": {
+        "type": "resolve-target",
+        "target": {
+          "kind": "version",
+          "value": "1.21.10"
+        }
+      }
+    }
+  }
+}
+```
+
+### Map or check a symbol
+
+```json
+{
+  "tool": "analyze-symbol",
+  "arguments": {
+    "task": "map",
+    "subject": {
+      "kind": "method",
+      "owner": "net.minecraft.server.Main",
+      "name": "tickServer"
+    },
+    "version": "1.21.10",
+    "sourceMapping": "mojang",
+    "targetMapping": "intermediary",
+    "signatureMode": "name-only"
+  }
+}
+```
+
+### Summarize a mod JAR
+
+```json
+{
+  "tool": "analyze-mod",
+  "arguments": {
+    "task": "summary",
+    "subject": {
+      "kind": "jar",
+      "jarPath": "/path/to/mymod-1.0.0.jar"
+    }
+  }
+}
+```
+
+### Validate a workspace
+
+```json
+{
+  "tool": "validate-project",
+  "arguments": {
+    "task": "project-summary",
+    "subject": {
+      "kind": "workspace",
+      "projectPath": "/workspace/modid",
+      "discover": ["mixins", "access-wideners"]
+    },
+    "preferProjectVersion": true,
+    "preferProjectMapping": true
+  }
+}
+```
+
+## Documentation
+
+- [Detailed example requests](docs/examples.md)
+- [Tool and configuration reference](docs/tool-reference.md)
+- [日本語 README](docs/README-ja.md)
+
 ## Tool Surface
 
+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.
+
+### 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?` |
+<!-- END GENERATED TOOL TABLE: v3-entry-tools -->
+
 ### Source Exploration
 
-Tools for browsing Minecraft versions, resolving source artifacts, and reading/searching decompiled source code.
+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?`, `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?`, `access?`, `includeInherited?`, `maxMembers?`, `strictVersion?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `returnedNamespace`, `artifactContents`, `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` |
+<!-- END GENERATED TOOL TABLE: source-exploration -->
 
 ### Version Comparison & Symbol Tracking
 
-Tools for comparing class/registry changes across Minecraft versions and tracing symbol existence over time.
+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?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |
+| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions (`descriptor` omitted = name-only lookup) | `symbol`, `descriptor?`, `fromVersion?`, `toVersion?`, `mapping?`, `sourcePriority?`, `includeSnapshots?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |
 | `diff-class-signatures` | Compare one class between two versions and return member deltas | `className`, `fromVersion`, `toVersion`, `mapping?`, `sourcePriority?`, `includeFullDiff?` | `classChange`, `constructors/methods/fields.{added,removed,modified}`, `modified`, `modified[].{key,changed,from?,to?}`, `summary`, `warnings[]` |
 | `compare-versions` | Compare class/registry changes between two versions | `fromVersion`, `toVersion`, `category?`, `packageFilter?`, `maxClassResults?` | `classes`, `registry`, `summary`, `warnings[]` |
+<!-- END GENERATED TOOL TABLE: version-comparison-symbol-tracking -->
 
 ### Mapping & Symbols
 
 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[]` |
@@ -209,21 +284,25 @@ Tools for converting symbol names between namespaces and checking symbol existen
 | `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[]` |
+<!-- END GENERATED TOOL TABLE: mapping-symbols -->
 
 ### NBT Utilities
 
 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` |
+<!-- END GENERATED TOOL TABLE: nbt-utilities -->
 
 ### Mod Analysis
 
 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 |
@@ -231,763 +310,106 @@ Tools for extracting metadata from mod JARs, decompiling mod source, searching m
 | `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[]` |
+<!-- END GENERATED TOOL TABLE: mod-analysis -->
 
 ### Validation
 
 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` |
+<!-- END GENERATED TOOL TABLE: validation -->
 
 ### Registry & Diagnostics
 
 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 |
+<!-- END GENERATED TOOL TABLE: registry-diagnostics -->
 
-### 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:
-- 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.
+Detailed parameter constraints, migration notes, resource behavior, and the full environment-variable matrix live in [docs/tool-reference.md](docs/tool-reference.md).
 
 ## 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`.
+Fixed resources:
 
-## Examples
+- `mc://versions/list`
+- `mc://metrics`
 
-### 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
-  }
-}
-```
+Template resources:
 
-#### Search by method symbol
-```json
-{
-  "tool": "search-class-source",
-  "arguments": {
-    "artifactId": "<artifact-id>",
-    "query": "tickServer",
-    "intent": "symbol",
-    "match": "exact"
-  }
-}
-```
+- `mc://source/{artifactId}/{className}`
+- `mc://artifact/{artifactId}/files/{filePath}`
+- `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}`
+- `mc://artifact/{artifactId}/members/{className}`
+- `mc://artifact/{artifactId}`
 
-#### 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
-  }
-}
-```
+See [docs/tool-reference.md#resources](docs/tool-reference.md#resources) for the full resource table and response behavior.
 
-#### List artifact files with prefix filter
+## Response Model
 
-List source files under a specific package to understand project structure:
+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.
 
-```json
-{
-  "tool": "list-artifact-files",
-  "arguments": {
-    "artifactId": "<artifact-id>",
-    "prefix": "net/minecraft/world/level/",
-    "limit": 50
-  }
-}
-```
+See [docs/tool-reference.md#response-envelope](docs/tool-reference.md#response-envelope) for the exact envelope fields and error shape.
 
-### Version Comparison & Symbol Tracking
+## Common Environment Variables
 
-#### 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
-  }
-}
-```
+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).
 
-#### 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
-
-Get a high-level summary of what changed between two releases, including class additions/removals and registry diffs:
-
-```json
-{
-  "tool": "compare-versions",
-  "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"
-    }
-  }
-}
-```
-
-#### 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"
-  }
-}
-```
-
-#### Check class existence by short name (`nameMode=auto`)
-```json
-{
-  "tool": "check-symbol-exists",
-  "arguments": {
-    "version": "1.21.10",
-    "kind": "class",
-    "name": "Blocks",
-    "nameMode": "auto",
-    "sourceMapping": "mojang"
-  }
-}
-```
-
-### NBT Utilities
-
-#### Decode Java NBT base64 to typed JSON
-```json
-{
-  "tool": "nbt-to-json",
-  "arguments": {
-    "nbtBase64": "<base64-nbt>",
-    "compression": "auto"
-  }
-}
-```
-
-#### 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" } }
-    ]
-  }
-}
-```
-
-#### Encode typed JSON back to NBT base64
-```json
-{
-  "tool": "json-to-nbt",
-  "arguments": {
-    "typedJson": {
-      "rootName": "Level",
-      "root": { "type": "compound", "value": {} }
-    },
-    "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
-  }
-}
-```
-
-#### 2. Decompile the mod JAR
-
-Decompile all classes and optionally retrieve a specific class inline:
-
-```json
-{
-  "tool": "decompile-mod-jar",
-  "arguments": {
-    "jarPath": "/path/to/mymod-1.0.0.jar",
-    "includeFiles": false,
-    "className": "com.example.mymod.MyMod"
-  }
-}
-```
-
-#### 3. Read a specific class from decompiled source
-
-After decompilation, read any class without re-decompiling:
-
-```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:
-
-```json
-{
-  "tool": "search-mod-source",
-  "arguments": {
-    "jarPath": "/path/to/mymod-1.0.0.jar",
-    "query": "onPlayerTick",
-    "searchType": "method",
-    "limit": 50
-  }
-}
-```
-
-#### 5. Remap mod JAR to readable names
-
-Remap a Fabric mod from `intermediary` to `yarn` names for easier reading:
-
-```json
-{
-  "tool": "remap-mod-jar",
-  "arguments": {
-    "inputJar": "/path/to/mymod-1.0.0.jar",
-    "targetMapping": "yarn",
-    "mcVersion": "1.21.10"
-  }
-}
-```
-
-If the input jar was already built with Mojang mappings, use `targetMapping: "mojang"` to get a copied output jar and a `fromMapping: "mojang"` result.
-
-### Validation
-
-#### Validate Mixin source
-
-Check a Mixin class source for correctness against a target Minecraft version:
-
-```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
-  }
-}
-```
-
-#### Validate all Mixins in a project
-
-Discover `*.mixins.json` files from a workspace root and validate every referenced Mixin in one call:
-
-```json
-{
-  "tool": "validate-mixin",
-  "arguments": {
-    "input": {
-      "mode": "project",
-      "path": "/workspace/modid"
-    },
-    "version": "1.21.10",
-    "projectPath": "/workspace/modid",
-    "preferProjectVersion": true,
-    "preferProjectMapping": true,
-    "reportMode": "compact",
-    "warningMode": "aggregated",
-    "includeIssues": false
-  }
-}
-```
-
-#### Validate multiple Mixin files (batch)
-
-Run the same validation settings against multiple Mixin source files:
-
-```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
-  }
-}
-```
-
-#### Validate Access Widener
-
-Check an Access Widener file for valid entries against the target 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"
-  }
-}
-```
-
-### Registry & Diagnostics
+| 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 |
 
-#### Get all registries for a version
+## Development
 
-Retrieve the full set of generated registries (blocks, items, entities, etc.) for a Minecraft version:
+Repository requirements:
 
-```json
-{
-  "tool": "get-registry-data",
-  "arguments": {
-    "version": "1.21.10",
-    "includeData": false
-  }
-}
-```
-
-#### Get a single registry
+- Node.js 22+
+- `pnpm`
+- Java when running remap or decompile flows locally
 
-Fetch only a specific registry type:
+Setup and run the repository:
 
-```json
-{
-  "tool": "get-registry-data",
-  "arguments": {
-    "version": "1.21.10",
-    "registry": "minecraft:block",
-    "maxEntriesPerRegistry": 50
-  }
-}
+```bash
+pnpm install
+pnpm dev
 ```
 
-#### Force reindex an artifact
-
-Rebuild the search index for an artifact after cache or tooling changes:
+Build the packaged shape:
 
-```json
-{
-  "tool": "index-artifact",
-  "arguments": {
-    "artifactId": "<artifact-id>",
-    "force": true
-  }
-}
+```bash
+pnpm build
+pnpm start
 ```
 
-#### Inspect runtime metrics
-
-Check server performance counters, cache sizes, and latency snapshots:
+Always run:
 
-```json
-{
-  "tool": "get-runtime-metrics",
-  "arguments": {}
-}
+```bash
+pnpm check
+pnpm test
 ```
 
-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`.
-
-### 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.
+Run these when relevant:
 
-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 |
-
-## Architecture
-
-| 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