@adhisang/minecraft-modding-mcp 3.1.1 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2026-04-18
+
+### Changed
+- BREAKING: `resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` now default `compact` to `true` (was `false`). Pass `compact: false` to restore the full diagnostic shape.
+- BREAKING: `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, `check-symbol-exists`, and `analyze-symbol` now default `maxCandidates` to `5` (was `200`; `200` is still the upper bound).
+- BREAKING: `find-mapping` now defaults `signatureMode` to `"name-only"` (was effectively `"exact"`). `kind="method"` lookups without a `descriptor` no longer fail; pass `signatureMode: "exact"` explicitly for strict descriptor matching.
+- BREAKING: `resolve-artifact` with `mapping="mojang"` and `target.kind="version"` against a still-obfuscated Minecraft version now succeeds by tiny-remapping the binary jar and decompiling the result, tagged `qualityFlags: ["binary-remapped", "decompiled"]` and `provenance.transformChain: ["binary-remap:obf->mojang", "decompile:vineflower"]`. The remapped jar is cached at `<cacheDir>/remapped/<artifactId>.jar`. Coordinate and jar targets are not eligible. `ERR_MAPPING_NOT_APPLIED` is still raised when tiny-remapper, the Mojang tiny mapping file, or the version's Mojang mappings are missing.
+- `find-mapping` and `check-symbol-exists` accept an empty `descriptor` as equivalent to omitting it.
+- Compact mode on mapping tools keeps the top three unresolved candidates with full metadata and slims the tail to `{kind, symbol, owner, name, descriptor, confidence, matchKind}`. A new `candidateDetailsTruncated` flag signals this slim, distinct from the existing `candidatesTruncated` (upstream truncation).
+
+### Added
+- `find-mapping` exposes `signatureMode` as a first-class input. `"exact"` matches `owner + name + descriptor`; `"name-only"` matches by `owner + name` and ranks overloads by confidence. `resolve-method-mapping-exact` retains strict exact-triple semantics.
+- `get-class-source`, `get-class-members`, `search-class-source`, and `list-artifact-files` accept an opt-in `compact` parameter (default `false`). It strips diagnostic envelopes (`provenance`, `artifactContents`, `qualityFlags`, plus `context` for `get-class-members`) while preserving primary payloads (`sourceText`, `members`/`counts`, `hits`, `items`).
+- `manage-cache` exposes the Mojang remapped jar under a new `binary-remap` cache kind with `selector.artifactId` filtering. LRU eviction unlinks the matching remapped jar so cache accounting stays consistent.
+- `validate-mixin` top-level errors now carry `failedStage` on the `ProblemDetails` envelope (one of `input-validation | resolve | mapping-health | parse | target-lookup`), so callers can branch without parsing `message`.
+- `validate-mixin` `quickSummary` appends notes when `provenance.scopeFallback` fires or `toolHealth.overallHealthy` is false.
+- Ambiguous mapping responses in `find-mapping`, `resolve-method-mapping-exact`, and `check-symbol-exists` include recovery guidance in `warnings` (descriptor hints, `signatureMode="exact"` retries, `disambiguation.ownerHint`, raising `maxCandidates`).
+- `docs/tool-reference.md` includes a "Which Tool for Which Question" decision table; `README.md` links to it from the Documentation section.
+
+### Fixed
+- `check-symbol-exists` projects the caller's JVM descriptor to the obfuscated namespace before filtering method overloads, so `signatureMode="exact"` retries work with descriptors that reference remapped Minecraft classes. Mixed descriptors such as `(Lnet/minecraft/world/item/ItemStack;Ljava/lang/String;)V` resolve via partial projection instead of falling back to the unprojected source descriptor.
+- `find-mapping` with `signatureMode="exact"` and `kind="method"` filters resolved candidates by the (projected) requested descriptor. A caller who supplied `foo(Z)V` is no longer told that `foo(I)V` is the exact mapping.
+- Compact mode slim candidate projection retains `kind` and `symbol` alongside `owner`, `name`, `descriptor`, `confidence`, and `matchKind`, so clients keying off `kind` or `symbol` are no longer silently broken.
+- `normalizeMethodDescriptor` rejects descriptors with more than 255 leading `[` (JVM §4.3.2) and rejects malformed shapes such as `()`, `(I)`, and `(L;)V` with `ERR_INVALID_INPUT`.
+
+## [3.2.0] - 2026-04-12
+
+### Added
+- `resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` now accept an optional `compact` parameter (default `false`). When `true`, empty arrays, null values, and empty objects are stripped from the top-level response. For `resolve-artifact`, compact mode additionally omits `provenance`, `artifactContents`, `sampleEntries`, `adjacentSourceCandidates`, `binaryJarPath`, `coordinate`, `repoUrl`, and `resolvedSourceJarPath`. For mapping tools, compact mode omits the redundant `candidates` array when the result is a single full-confidence exact-match resolution.
+- `validate-access-widener` now accepts `projectPath`, `scope`, and `preferProjectVersion` for runtime-aware validation against Loom runtime jars, and reports additive `provenance`, `resolvedInRuntime`, and `resolvedRuntimeAccess` evidence for matched class, method, and field entries.
+- Added `validate-access-transformer` for Forge / NeoForge Access Transformer validation, including `atNamespace` support, workspace-driven namespace inference, runtime artifact provenance, and per-entry runtime access evidence.
+- `analyze-mod-jar` now surfaces packaged Access Transformer paths alongside mod metadata.
+
+### Fixed
+- `validate-access-widener` and `validate-access-transformer` runtime-aware method validation now preserves remapped JVM descriptors through exact and fallback member remaps, eliminating false-negative `method not found` results for entries whose descriptors reference remapped Minecraft classes such as `Level#setBlock(BlockPos, BlockState, int)`.
+- `validate-access-widener` runtime-aware `scope: "merged"` now prefers explicit `*merged-intermediary*` / `*merged-mojang*` runtime jars over ambiguous `minecraft-merged.jar` candidates, and Loom tiny lookup now scans workspace and Gradle user-home caches so runtime validation can resolve descriptor remaps in normal Loom setups.
+- `validate-project` now forwards workspace runtime context to discovered Access Widener validation so project-summary runs can use the same runtime-aware behavior as direct `validate-access-widener` calls.
+- `validate-project` now discovers Access Transformer files, supports `task="access-transformer"`, and can include those validations in workspace summaries when `discover` requests them.
+- `resolve-artifact`, `get-class-source`, `get-class-members`, and `inspect-minecraft` source/class-member flows now treat unobfuscated releases such as `26.1+` as native `mojang` runtime namespaces for both version and versioned-coordinate targets, avoiding false `ERR_MAPPING_NOT_APPLIED` failures and wrong-version Loom source-jar approximations when no exact source jar is present.
+- `validate-mixin` tool-health diagnostics now treat unobfuscated `mojang` runtime names as available, while still flagging `intermediary`/`yarn` as unavailable on `26.1+`.
+- `validate-project task="project-summary"` now pre-resolves `preferProjectVersion=true` consistently across discovered Access Widener and workspace Mixin checks, and returns a blocked summary with version-agnostic recovery guidance when discovered validators need a version but neither the request nor `gradle.properties` can supply one.
+- `check-symbol-exists` and `analyze-symbol task="exists"` now fall back to unobfuscated runtime bytecode for `mojang`/runtime-name existence checks on `26.1+`, preserve the original `mapping_unavailable` result when the runtime JAR cannot be resolved, and return a targeted warning when callers provide only a short class name.
+- Loom tiny mapping discovery no longer performs unbounded directory traversal when the version-specific cache directory is absent, preventing excessive memory consumption on systems with large Gradle caches.
+- Mapping graph cache eviction after lifecycle scans now correctly releases all cached entries for a version instead of silently skipping them.
+
+### Performance
+- `resolve-artifact` source-jar detection and mapping tiny-jar loading now reuse a single ZIP walk per jar probe instead of reopening and fully enumerating matching archives on each helper call.
+- `search-mod-source`, `decompile-mod-jar`, `get-mod-class-source`, `validate-project` workspace discovery, and workspace mapping detection now avoid synchronous hot-path file/glob reads and use bounded concurrent text reads where safe, reducing event-loop stalls on larger decompiled outputs and multi-module workspaces.
+
 ## [3.1.1] - 2026-03-21
 
 ### Fixed

package/README.md

@@ -5,23 +5,23 @@
 [![Node.js >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
 [![CI](https://github.com/adhi-jp/minecraft-modding-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/adhi-jp/minecraft-modding-mcp/actions/workflows/ci.yml)
 
-**[日本語](docs/README-ja.md)** | English
+**English** | [日本語](docs/README-ja.md)
 
----
+> **Note**: This project is entirely vibe-coded — built with AI-assisted development without formal specs.
 
-`@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.
+---
 
-[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.
+`@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 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**
+**36 tools** (6 entry + 30 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`
 - **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
+- **Mod JAR Analysis**: extract metadata, dependencies, entrypoints, Mixin configs, and packaged Access Transformer paths from Fabric, Forge, and NeoForge mod JARs
+- **Mixin, Access Widener, and Access Transformer Validation**: validate source, `.accesswidener`, and Forge/NeoForge access transformer 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
@@ -47,8 +47,17 @@ If automatic JAR downloads are blocked in your environment, set `MCP_VINEFLOWER_
 
 CLI clients:
 
-- `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`
+Claude Code:
+
+```bash
+claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
+```
+
+OpenAI Codex CLI:
+
+```bash
+codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
+```
 
 Run `claude mcp list` or `codex mcp list` after registration to verify the server is available.
 
@@ -136,7 +145,7 @@ All six return `result.summary` first, and can include `summary.nextActions` whe
 | `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 |
+| `validate-project` | workspace summaries plus direct Mixin, Access Widener, and Access Transformer validation |
 | `manage-cache` | cache inventory, verification, and preview/apply cleanup workflows |
 
 ### Workflow Notes
@@ -146,8 +155,9 @@ Keep only the high-frequency notes here. For the full pitfall list, exact contra
 - `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`.
+- For unobfuscated releases such as `26.1+`, `check-symbol-exists` and `analyze-symbol task="exists"` validate `mojang` lookups against runtime bytecode when no mapping graph exists, and return `mapping_unavailable` when the runtime JAR itself is unreachable.
+- `analyze-mod` and `validate-project` require structured `subject` objects and canonical `include` groups; stale string-subject or domain-include payloads return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
+- `validate-project task="project-summary"` propagates `preferProjectVersion=true` across discovered Mixin, Access Widener, and Access Transformer checks. When no version can be resolved from the request or `gradle.properties`, the summary blocks with version-agnostic recovery guidance.
 
 ### Inspect Minecraft source from a version
 
@@ -216,7 +226,7 @@ Keep only the high-frequency notes here. For the full pitfall list, exact contra
     "subject": {
       "kind": "workspace",
       "projectPath": "/workspace/modid",
-      "discover": ["mixins", "access-wideners"]
+      "discover": ["mixins", "access-wideners", "access-transformers"]
     },
     "preferProjectVersion": true,
     "preferProjectMapping": true
@@ -224,10 +234,12 @@ Keep only the high-frequency notes here. For the full pitfall list, exact contra
 }
 ```
 
+Workspace summaries still default to discovering mixins and access wideners. Add `"access-transformers"` to `subject.discover` when you want Access Transformer files included in the summary run.
+
 ## Documentation
 
 - [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
+- [Tool and configuration reference](docs/tool-reference.md) for exact inputs, outputs, resource behavior, environment variables, and migration notes — start with the [Which Tool for Which Question](docs/tool-reference.md#which-tool-for-which-question) decision table when you are not sure which tool to call
 - [日本語 README](docs/README-ja.md) for a Japanese onboarding overview
 
 ## Tool Surface
@@ -243,7 +255,7 @@ Start with these top-level workflow tools unless you already know the exact spec
 | `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 |
+| `validate-project` | Summarize workspaces and run direct Mixin, Access Widener, or Access Transformer validation |
 | `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |
 <!-- END GENERATED TOOL TABLE: v3-entry-tools -->
 
@@ -265,6 +277,8 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading o
 | `index-artifact` | Rebuild indexed metadata for an existing artifact |
 <!-- END GENERATED TOOL TABLE: source-exploration -->
 
+For unobfuscated releases such as `26.1+`, `mapping="mojang"` uses the runtime/decompile path directly and skips Loom source-jar discovery, while `intermediary` and `yarn` fall back to `obfuscated` with a warning.
+
 ### Version Comparison & Symbol Tracking
 
 Tools for comparing class and registry changes across Minecraft versions and tracing symbol existence over time.
@@ -291,6 +305,10 @@ Tools for converting symbol names between namespaces and checking symbol existen
 | `check-symbol-exists` | Check whether a class, field, or method exists in a namespace |
 <!-- END GENERATED TOOL TABLE: mapping-symbols -->
 
+`resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` default `compact` to `true`: empty fields are stripped, `resolve-artifact` omits diagnostic fields (`provenance`, `artifactContents`, etc.), and mapping tools omit the redundant `candidates` array on full-confidence exact matches and slim the tail to `{kind, symbol, owner, name, descriptor, confidence, matchKind}` (signalled by `candidateDetailsTruncated`) for unresolved results with more than three candidates. Pass `compact: false` for the full diagnostic shape.
+
+`get-class-source`, `get-class-members`, `search-class-source`, and `list-artifact-files` accept the same `compact` parameter as opt-in (default `false`). When enabled it strips `provenance`, `artifactContents`, `qualityFlags`, and (for `get-class-members`) `context`, while preserving primary payloads (`sourceText`, `members`/`counts`, `hits`, `items`). See [docs/tool-reference.md](docs/tool-reference.md) for the full per-tool field list.
+
 ### NBT Utilities
 
 Tools for decoding, patching, and encoding Java Edition NBT binary data using a typed JSON representation.
@@ -310,7 +328,7 @@ Tools for extracting metadata from mod JARs, decompiling mod source, searching m
 <!-- BEGIN GENERATED TOOL TABLE: mod-analysis -->
 | Tool | Purpose |
 | --- | --- |
-| `analyze-mod-jar` | Extract mod metadata, dependencies, entrypoints, and mixin config info from a JAR |
+| `analyze-mod-jar` | Extract mod metadata, dependencies, entrypoints, mixin config info, and packaged access transformer paths 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 |
@@ -319,13 +337,14 @@ Tools for extracting metadata from mod JARs, decompiling mod source, searching m
 
 ### Validation
 
-Tools for validating Mixin source and Access Widener files against a target Minecraft version.
+Tools for validating Mixin source, Access Widener files, and Forge/NeoForge Access Transformer files against a target Minecraft version. `validate-access-widener` defaults to vanilla bytecode validation; pass `projectPath`, `scope`, and `preferProjectVersion` for runtime-aware mode, which returns runtime `provenance` plus per-entry `resolvedRuntimeAccess` evidence. `validate-access-transformer` infers `atNamespace` from Forge/NeoForge workspace context when `projectPath` is provided and uses loader runtime artifacts for `scope="loader"`.
 
 <!-- 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 |
+| `validate-access-widener` | Validate Access Widener content against a target Minecraft version, optionally using runtime-aware Loom artifacts |
+| `validate-access-transformer` | Validate Access Transformer content against a target Minecraft version, optionally using Forge/NeoForge runtime artifacts |
 <!-- END GENERATED TOOL TABLE: validation -->
 
 ### Registry & Diagnostics

package/dist/access-transformer-parser.d.ts

@@ -0,0 +1,17 @@
+export type AccessTransformerAccessAction = "public" | "protected" | "package-private" | "private";
+export type AccessTransformerFinalAction = "add" | "remove";
+export type AccessTransformerEntry = {
+    line: number;
+    targetKind: "class" | "field" | "method";
+    owner: string;
+    target: string;
+    name?: string;
+    descriptor?: string;
+    accessAction: AccessTransformerAccessAction;
+    finalAction?: AccessTransformerFinalAction;
+};
+export type ParsedAccessTransformer = {
+    entries: AccessTransformerEntry[];
+    parseWarnings: string[];
+};
+export declare function parseAccessTransformer(content: string): ParsedAccessTransformer;

package/dist/access-transformer-parser.js

@@ -0,0 +1,97 @@
+function parseAccessDeclaration(raw) {
+    const match = raw.match(/^(public|protected|default|private)([+-]f)?$/i);
+    if (!match) {
+        return undefined;
+    }
+    const finalModifier = match[2]?.toLowerCase();
+    return {
+        accessAction: match[1]?.toLowerCase() === "default"
+            ? "package-private"
+            : match[1]?.toLowerCase(),
+        ...(finalModifier === "+f" ? { finalAction: "add" } : {}),
+        ...(finalModifier === "-f" ? { finalAction: "remove" } : {})
+    };
+}
+function splitMemberToken(tokens) {
+    if (tokens.length === 0) {
+        return { targetKind: "class" };
+    }
+    if (tokens.length === 1) {
+        const token = tokens[0] ?? "";
+        const descriptorStart = token.indexOf("(");
+        if (descriptorStart >= 0) {
+            return {
+                targetKind: "method",
+                name: token.slice(0, descriptorStart),
+                descriptor: token.slice(descriptorStart)
+            };
+        }
+        return {
+            targetKind: "field",
+            name: token
+        };
+    }
+    return {
+        targetKind: "method",
+        name: tokens[0],
+        descriptor: tokens.slice(1).join("")
+    };
+}
+export function parseAccessTransformer(content) {
+    const entries = [];
+    const parseWarnings = [];
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
+        const lineNumber = index + 1;
+        const rawLine = (lines[index] ?? "").trim();
+        if (!rawLine || rawLine.startsWith("#")) {
+            continue;
+        }
+        const withoutComment = rawLine.replace(/\s+#.*$/, "").trim();
+        if (!withoutComment) {
+            continue;
+        }
+        const parts = withoutComment.split(/\s+/);
+        if (parts.length < 2) {
+            parseWarnings.push(`Line ${lineNumber}: Incomplete access transformer entry "${withoutComment}".`);
+            continue;
+        }
+        const declaration = parseAccessDeclaration(parts[0] ?? "");
+        if (!declaration) {
+            parseWarnings.push(`Line ${lineNumber}: Unsupported access declaration "${parts[0]}".`);
+            continue;
+        }
+        const owner = parts[1] ?? "";
+        if (!owner) {
+            parseWarnings.push(`Line ${lineNumber}: Incomplete access transformer entry "${withoutComment}".`);
+            continue;
+        }
+        const member = splitMemberToken(parts.slice(2));
+        if (member.targetKind === "method" && (!member.name || !member.descriptor)) {
+            parseWarnings.push(`Line ${lineNumber}: Method entry requires a method name and JVM descriptor.`);
+            continue;
+        }
+        if ((member.targetKind === "field" || member.targetKind === "method") && !member.name) {
+            parseWarnings.push(`Line ${lineNumber}: Member entry requires a target name.`);
+            continue;
+        }
+        const target = member.targetKind === "class"
+            ? owner
+            : `${owner}#${member.name}${member.descriptor ?? ""}`;
+        entries.push({
+            line: lineNumber,
+            owner,
+            target,
+            targetKind: member.targetKind,
+            ...(member.name ? { name: member.name } : {}),
+            ...(member.descriptor ? { descriptor: member.descriptor } : {}),
+            accessAction: declaration.accessAction,
+            ...(declaration.finalAction ? { finalAction: declaration.finalAction } : {})
+        });
+    }
+    return {
+        entries,
+        parseWarnings
+    };
+}
+//# sourceMappingURL=access-transformer-parser.js.map

package/dist/cache-registry.d.ts

@@ -1,5 +1,5 @@
 import { type PathRuntimeInfo } from "./path-converter.js";
-export declare const PUBLIC_CACHE_KINDS: readonly ["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap"];
+export declare const PUBLIC_CACHE_KINDS: readonly ["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap"];
 export type PublicCacheKind = (typeof PUBLIC_CACHE_KINDS)[number];
 export declare const CACHE_HEALTH_STATES: readonly ["healthy", "partial", "stale", "orphaned", "corrupt", "in_use"];
 export type CacheHealthState = (typeof CACHE_HEALTH_STATES)[number];

package/dist/cache-registry.js

@@ -10,7 +10,8 @@ export const PUBLIC_CACHE_KINDS = [
     "mapping",
     "registry",
     "decompiled-source",
-    "mod-remap"
+    "mod-remap",
+    "binary-remap"
 ];
 export const CACHE_HEALTH_STATES = [
     "healthy",
@@ -37,6 +38,8 @@ function kindRoot(config, cacheKind) {
             return join(config.cacheDir, "decompiled");
         case "mod-remap":
             return join(config.cacheDir, "remapped-mods");
+        case "binary-remap":
+            return join(config.cacheDir, "remapped");
     }
 }
 async function listFilesRecursive(root) {
@@ -439,7 +442,12 @@ async function fileBackedEntries(config, cacheKind) {
                 inUse: filePath.endsWith(".lock") ||
                     filePath.endsWith(".wal") ||
                     filePath.endsWith(".journal"),
-                ...(cacheKind === "downloads" || cacheKind === "mod-remap" ? { jarPath: filePath } : {})
+                ...(cacheKind === "downloads" || cacheKind === "mod-remap" || cacheKind === "binary-remap"
+                    ? { jarPath: filePath }
+                    : {}),
+                ...(cacheKind === "binary-remap"
+                    ? { artifactId: normalizedEntryId.replace(/\.jar$/i, "") }
+                    : {})
             }
         });
     }

package/dist/concurrency.d.ts

@@ -0,0 +1 @@
+export declare function mapWithConcurrencyLimit<T, R>(items: readonly T[], limit: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/concurrency.js

@@ -0,0 +1,24 @@
+export async function mapWithConcurrencyLimit(items, limit, mapper) {
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new Error("limit must be a positive integer");
+    }
+    if (items.length === 0) {
+        return [];
+    }
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workerCount = Math.min(limit, items.length);
+    const worker = async () => {
+        while (true) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            if (currentIndex >= items.length) {
+                return;
+            }
+            results[currentIndex] = await mapper(items[currentIndex], currentIndex);
+        }
+    };
+    await Promise.all(Array.from({ length: workerCount }, async () => worker()));
+    return results;
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { Config } from "./types.js";
+import type { ArtifactTargetKind, Config, MappingVariant } from "./types.js";
 declare const DEFAULTS: {
     readonly cacheDir: "~/.cache/minecraft-modding-mcp";
     readonly sourceRepos: readonly ["https://repo1.maven.org/maven2", "https://maven.fabricmc.net", "https://maven.minecraftforge.net", "https://maven.neoforged.net/releases"];
@@ -24,4 +24,13 @@ declare const DEFAULTS: {
 };
 export declare function loadConfig(): Config;
 export declare function stableArtifactId(parts: string[]): string;
+export interface ArtifactAliasInput {
+    artifactId: string;
+    kind: ArtifactTargetKind;
+    value: string;
+    mappingVariant?: MappingVariant;
+    resolvedVersion?: string;
+    coordinate?: string;
+}
+export declare function buildArtifactAlias(input: ArtifactAliasInput): string;
 export { DEFAULTS };

package/dist/config.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { basename, isAbsolute, resolve } from "node:path";
 import { normalizePathForHost } from "./path-converter.js";
 const DEFAULTS = {
     cacheDir: "~/.cache/minecraft-modding-mcp",
@@ -182,5 +182,56 @@ export function stableArtifactId(parts) {
         .join("|");
     return createHash("sha256").update(normalizer).digest("hex");
 }
+// 12 hex chars (48 bits) of artifactId entropy keeps alias collisions astronomically
+// unlikely while staying short enough to copy/paste. A shorter prefix would let two
+// distinct artifacts whose readable tokens (kind, version, mapping, scope, variant)
+// happen to match share an alias and trip the schema-v4 UNIQUE constraint.
+const ARTIFACT_ALIAS_HASH_LEN = 12;
+function slugifyAliasPart(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function aliasJarBase(jarPath) {
+    const base = basename(jarPath);
+    return base.toLowerCase().endsWith(".jar") ? base.slice(0, -4) : base;
+}
+// Generates a deterministic, human-readable alias canonical to the artifact row.
+// The alias is 1:1 with `artifactId`: only dimensions baked into `artifactId`
+// itself (kind, value/version/coordinate, mappingVariant) appear in the alias,
+// plus a 12-hex-char (48-bit) suffix taken from `artifactId`. Request-level
+// dimensions like `mapping` and `scope` are intentionally excluded — including
+// them would make resolveArtifact rotate the alias for the same row whenever
+// a caller passed a different mapping/scope, breaking aliases already returned
+// to earlier callers. Two distinct artifactIds whose readable tokens collide and
+// whose first 48 hash bits also collide would trip the schema-v4 alias UNIQUE
+// constraint at upsert time — a hard error, not silent drift.
+// Phase 3.1a: display-only. Phase 3.1b stores it for lookup.
+export function buildArtifactAlias(input) {
+    const tokens = [];
+    if (input.kind === "version") {
+        tokens.push("mc", input.resolvedVersion ?? input.value);
+    }
+    else if (input.kind === "coordinate") {
+        tokens.push("coord", input.coordinate ?? input.value);
+    }
+    else {
+        tokens.push("jar", aliasJarBase(input.value));
+    }
+    // mappingVariant is canonical — `artifactIdForJar` / `artifactIdForCoordinate`
+    // bake "mojang-remapped" into the artifactId, so the same artifactId always
+    // produces the same alias regardless of how many times resolveArtifact is
+    // called. The token here is purely a human-readable hint; the 12-char hash
+    // suffix would already separate remapped artifacts from pass-through ones.
+    if (input.mappingVariant === "mojang-remapped") {
+        tokens.push("remapped");
+    }
+    tokens.push(input.artifactId.slice(0, ARTIFACT_ALIAS_HASH_LEN));
+    return tokens
+        .map(slugifyAliasPart)
+        .filter(Boolean)
+        .join("-");
+}
 export { DEFAULTS };
 //# sourceMappingURL=config.js.map

package/dist/decompiler/vineflower.js

@@ -1,11 +1,13 @@
-import { access, constants } from "node:fs/promises";
-import { mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { access, constants, mkdir, readFile, readdir, stat } from "node:fs/promises";
+import { mkdirSync, rmSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, join, relative, sep } from "node:path";
+import { mapWithConcurrencyLimit } from "../concurrency.js";
 import { createError, ERROR_CODES, isAppError } from "../errors.js";
 import { assertJavaAvailable, runJavaProcess } from "../java-process.js";
 import { log } from "../logger.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
+const DECOMPILED_JAVA_READ_CONCURRENCY = 8;
 const VINEFLOWER_FLAG_PROFILES = [
     { label: "default", flags: ["-din=1", "-rbr=1", "-dgs=1"] },
     { label: "relaxed", flags: ["-din=1", "-rbr=0", "-dgs=0"] },
@@ -47,14 +49,14 @@ async function assertVineflowerAvailable(vineflowerJarPath) {
         });
     }
 }
-function collectJavaFilesSync(baseDir, currentDir = "") {
+async function collectJavaFilesRecursive(baseDir, currentDir = "") {
     const absoluteBase = currentDir ? join(baseDir, currentDir) : baseDir;
-    const entries = readdirSync(absoluteBase, { withFileTypes: true });
+    const entries = await readdir(absoluteBase, { withFileTypes: true });
     const result = [];
     for (const entry of entries) {
         const next = currentDir ? join(currentDir, entry.name) : entry.name;
         if (entry.isDirectory()) {
-            result.push(...collectJavaFilesSync(baseDir, next));
+            result.push(...await collectJavaFilesRecursive(baseDir, next));
             continue;
         }
         if (entry.isFile() && entry.name.endsWith(".java")) {
@@ -66,23 +68,21 @@ function collectJavaFilesSync(baseDir, currentDir = "") {
 async function collectJavaFiles(baseDir) {
     try {
         const fastGlobModule = (await import("fast-glob"));
-        const sync = fastGlobModule.default?.sync;
-        if (typeof sync === "function") {
-            return sync("**/*.java", { cwd: baseDir, onlyFiles: true });
+        const glob = fastGlobModule.default?.glob;
+        if (typeof glob === "function") {
+            return (await glob("**/*.java", { cwd: baseDir, onlyFiles: true }))
+                .sort((left, right) => left.localeCompare(right));
         }
     }
     catch {
         // optional dependency: fallback to recursive traversal
     }
-    return collectJavaFilesSync(baseDir).map((candidate) => candidate.split(sep).join("/"));
+    return (await collectJavaFilesRecursive(baseDir))
+        .map((candidate) => candidate.split(sep).join("/"))
+        .sort((left, right) => left.localeCompare(right));
 }
 function readFileTreeText(filePath) {
-    return new Promise((resolve, reject) => {
-        import("node:fs/promises")
-            .then((fs) => fs.readFile(filePath, "utf8"))
-            .then(resolve)
-            .catch(reject);
-    });
+    return readFile(filePath, "utf8");
 }
 function decompileOutputDir(cacheDir, binaryJarPath, signature) {
     const digest = createHash("sha256").update(binaryJarPath).update(signature).digest("hex");
@@ -130,17 +130,18 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
     const signature = options.signature ?? basename(normalizedBinaryJarPath);
     const outputDir = decompileOutputDir(cacheDir, normalizedBinaryJarPath, signature).replace(/[/\\]$/, "");
     try {
-        mkdirSync(outputDir, { recursive: true });
-        if (statSync(outputDir, { throwIfNoEntry: false })) {
+        await mkdir(outputDir, { recursive: true });
+        const outputDirStats = await stat(outputDir).catch(() => undefined);
+        if (outputDirStats) {
             const existingJavaFiles = await collectJavaFiles(outputDir);
             if (existingJavaFiles.length > 0) {
-                const results = await Promise.all(existingJavaFiles.map(async (candidate) => {
+                const results = await mapWithConcurrencyLimit(existingJavaFiles, DECOMPILED_JAVA_READ_CONCURRENCY, async (candidate) => {
                     const abs = join(outputDir, candidate);
                     return {
                         filePath: normalizeOutputPath(outputDir, abs),
                         content: await readFileTreeText(abs)
                     };
-                }));
+                });
                 emitDecompileLog("decompile.done", {
                     durationMs: Date.now() - startedAt,
                     artifactIdCandidate: options.artifactIdCandidate,
@@ -181,13 +182,13 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
                         }
                     });
                 }
-                const javaFiles = await Promise.all(javaFileNames.map(async (candidate) => {
+                const javaFiles = await mapWithConcurrencyLimit(javaFileNames, DECOMPILED_JAVA_READ_CONCURRENCY, async (candidate) => {
                     const abs = join(outputDir, candidate);
                     return {
                         filePath: normalizeOutputPath(outputDir, abs),
                         content: await readFileTreeText(abs)
                     };
-                }));
+                });
                 emitDecompileLog("decompile.done", {
                     durationMs: Date.now() - startedAt,
                     artifactIdCandidate: options.artifactIdCandidate,

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

@@ -75,7 +75,7 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     limit: number;
-    searchType: "class" | "method" | "field" | "all" | "content";
+    searchType: "class" | "field" | "method" | "all" | "content";
     task: "search" | "remap" | "summary" | "class-source" | "decompile";
     subject: {
         kind: "jar";
@@ -111,7 +111,7 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     targetMapping?: "mojang" | "yarn" | undefined;
     outputJar?: string | undefined;
     query?: string | undefined;
-    searchType?: "class" | "method" | "field" | "all" | "content" | undefined;
+    searchType?: "class" | "field" | "method" | "all" | "content" | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
     includeFiles?: boolean | undefined;
@@ -119,7 +119,7 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     executionMode?: "preview" | "apply" | undefined;
 }>, {
     limit: number;
-    searchType: "class" | "method" | "field" | "all" | "content";
+    searchType: "class" | "field" | "method" | "all" | "content";
     task: "search" | "remap" | "summary" | "class-source" | "decompile";
     subject: {
         kind: "jar";
@@ -155,7 +155,7 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     targetMapping?: "mojang" | "yarn" | undefined;
     outputJar?: string | undefined;
     query?: string | undefined;
-    searchType?: "class" | "method" | "field" | "all" | "content" | undefined;
+    searchType?: "class" | "field" | "method" | "all" | "content" | undefined;
     detail?: "full" | "summary" | "standard" | undefined;
     include?: string[] | undefined;
     includeFiles?: boolean | undefined;