@adhisang/minecraft-modding-mcp 4.2.0 → 5.0.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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).
 
+## [Unreleased]
+
+## [5.0.0] - 2026-06-04
+
+### Changed
+
+- **Breaking:** `get-class-members` now returns at most **150** members per page by default (was 500). The existing `nextCursor` continuation already covers paging; callers that need more in one response can pass an explicit `maxMembers` (still capped at 5000). `maxClassResults` and `maxVersions` defaults are unchanged.
+- **Breaking:** `inspect-minecraft` responses no longer echo the requested subject inside `summary.subject`. The raw requested subject still surfaces exactly once, in the always-on top-level `subject` block as `subject.requested` (paired with `subject.resolved`). Clients reading `summary.subject.requested` must switch to `subject.requested` (or correlate via `requestId`).
+- **Breaking:** `meta.warningDetails[]` entries no longer duplicate the warning text. Each entry now carries `index: number` referencing its string in `meta.warnings[]` (1:1, order-preserving) instead of a `message` field. Clients reading `warningDetails[].message` must switch to `meta.warnings[detail.index]`.
+- **Breaking:** `get-class-source` and `get-class-members` now omit the diagnostic fields `provenance`, `qualityFlags`, and `artifactContents` by default. Pass the new `includeProvenance: true` to include them. (`compact` keeps its existing meaning — strip empty fields, and for `get-class-members` also `context`.) Callers that previously read those fields without setting `compact` must now pass `includeProvenance: true`.
+- **Breaking:** `get-class-members` member objects are slimmed on the wire. `accessFlags` is dropped (the modifiers are already encoded in `javaSignature`), `isSynthetic` is emitted only when `true`, and `ownerFqn` is hoisted to a single block-level `members.ownerFqn` when every member shares one owner (the common, non-`includeInherited` case); it stays per-member when `includeInherited` surfaces multiple owners. `name` and `javaSignature` are unchanged. Read the owner from `members.ownerFqn` (falling back to `member.ownerFqn`), and derive access modifiers from `javaSignature` instead of `accessFlags`. `diff-class-signatures` / `verify-mixin-target` member shapes are unchanged.
+- **Breaking:** `get-class-members` omits `jvmDescriptor` on **field** members by default (the type is already in `javaSignature`). Method/constructor `jvmDescriptor` is always present for overload disambiguation. Pass `includeDescriptors: true` (legacy `get-class-members`) or `include: ["descriptors"]` (`inspect-minecraft` task=`class-members`) to also emit field descriptors.
+- **Breaking:** `analyze-symbol` (and the `inspect-minecraft`-adjacent mapping flows `exists`/`map`/`exact-map`/`workspace`) now reuse the expert-tool candidate projection: when a lookup resolves to a single exact candidate that just duplicates `match`, the `candidates` block is omitted; for unresolved results with more than three candidates the tail is slimmed and `candidateDetailsTruncated: true` is surfaced. Read the resolved symbol from `match` rather than `candidates[0]`.
+- **Breaking:** `validate-mixin` (and `validate-project` task=`mixin`/`project-summary`) now default `reportMode` to `summary-first` (was `full`) — for every caller, not just the MCP wire boundary. The default response hoists shared provenance/warnings/incomplete reasons and omits per-result `resolvedMembers`, `toolHealth`, `structuredWarnings`, `aggregatedWarnings`, and `confidenceBreakdown`; `summary`, `issues`, `issueSummary`, and top-level provenance/toolHealth are retained. Pass `reportMode="full"` or `explain=true` to restore per-result `resolvedMembers`/`toolHealth`/`resolutionTrace`. `explain=true` now also preserves `resolutionTrace` under `reportMode="compact"`.
+- `verify-mixin-target`: `member.descriptor` now accepts empty / whitespace-only strings as "omitted" (normalized to `undefined`), matching every other optional descriptor field on the surface. Previously rejected with `ERR_INVALID_INPUT`. Non-breaking — no change for callers passing a real descriptor.
+- **Breaking:** `get-class-source` and `get-class-members` now take the same `kind`-based `target` shape as `resolve-artifact`: `target: { kind: "version"|"jar"|"coordinate"|"workspace"|"dependency", ... }`, plus `target: { kind: "artifact", artifactId }` to reuse an already-resolved artifact. The old `target: { type: "artifact", artifactId }` form is removed — migrate to `{ kind: "artifact", artifactId }`. The redundant `{ type: "resolve", kind, value }` wrapper is still accepted (the `type` key is now ignored), but `{ kind, value }` is the canonical shape. Published `suggestedCall` targets for these tools now use the `kind`-based shape.
+- **Breaking:** `analyze-symbol` `task="lifecycle"` gains explicit range controls `fromVersion`, `toVersion`, `maxVersions`, `includeTimeline`, and `includeSnapshots` (accepted only for `task="lifecycle"`; supplying them on another task is now rejected instead of silently ignored). The existing `version` field is kept as a back-compat alias for `toVersion` (range end; `toVersion` takes precedence). **Behavior change:** the lifecycle scan default grew from the previous hard-coded **5 versions** to the service default of **120** (clamped at 400) — pass `maxVersions: 5` to restore the old window. A lifecycle request still requires an end anchor (`version` or `toVersion`).
+- `analyze-symbol` `subject.kind="symbol"` is now real selector-based auto-detect (owner+descriptor ⇒ method, owner only ⇒ field, otherwise ⇒ class) with the inferred kind surfaced as a warning and documented via the schema `describe()`. Previously `"symbol"` was silently coerced to `class` (exists/map/workspace), rejected (api-overview), or ignored (exact-map/lifecycle). `summary.subject.kind` now reports the resolved concrete kind instead of echoing `"symbol"`. Non-breaking — the enum keeps all four values and explicit kinds are unaffected.
+- **Breaking:** `check-symbol-exists` now defaults `signatureMode` to `name-only` (was `exact`), matching `find-mapping` so the two sibling lookup tools behave identically. A `kind="method"` query with no descriptor now matches by owner+name (resolving uniquely or reporting ambiguous overloads) instead of failing with `ERR_INVALID_INPUT`; pass `signatureMode="exact"` to require a descriptor. `find-mapping` gains a `nameMode` parameter (default `auto`, mirroring `check-symbol-exists`): `auto` accepts a dotless class name for any `sourceMapping` (previously only `obfuscated`), `fqcn` requires a fully-qualified name. `analyze-symbol`'s own `signatureMode` default is intentionally left at `exact`.
+- **Breaking:** the per-tool `compact` boolean is removed from all expert tools (`resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, `check-symbol-exists`, `get-class-source`, `get-class-members`, `search-class-source`, `list-artifact-files`) and the four `batch-*` tools, replaced by the entry-tool **`detail`** (`summary` | `standard` | `full`) + **`include[]`** response contract — one response-shaping vocabulary across the whole server. Per-tool defaults keep every default response byte-identical: resolution/mapping tools + batch default `detail: "summary"` (= old `compact: true`); `get-class-source`/`get-class-members`/`search-class-source`/`list-artifact-files` default `detail: "standard"` (= old `compact: false`, post-Phase-4 diagnostic strip). **Migration:** `compact: true` → `detail: "summary"`, `compact: false` → `detail: "full"`. `include[]` opts specific field groups back in (`["provenance"]`, `["candidates"]`, `["samples"]`, `["artifact"]`, `["paths"]`, `["descriptors"]`). The Phase-4 `includeProvenance` / `includeDescriptors` flags are retained as aliases for `include: ["provenance"]` / `include: ["descriptors"]`. Expert and batch responses now also report `meta.detailApplied` / `meta.includeApplied`.
+- `resolve-method-mapping-exact` is now documented as a strict shortcut for `find-mapping` (kind=method, signatureMode=exact): its description, schema, and the README/tool-reference entries explain that it additionally requires a **complete** descriptor projection (returns `mapping_unavailable` when class references cannot all be projected, where `find-mapping`'s exact mode resolves leniently). Documentation-only — no wire, behavior, or input-schema change; the tool is retained.
+- The display caps that were previously clamped silently now emit a clamp warning so the documented contract is truthful: `list-versions` `limit` (capped at 200), `get-class-api-matrix` `maxRows` (capped at 5000), and `compare-versions` `maxClassResults` (capped at 5000) push `"<field> was clamped to <cap> from <value>."` when an over-range value is supplied (and `inspect-minecraft task="versions"` surfaces the `list-versions` warning). Non-breaking — out-of-range values still clamp and succeed; the caps are unchanged.
+- Resource read errors (`mc://…` URIs) now carry the same recovery metadata as the equivalent tool call: `retryClass` and `issueOrigin` are always present, and `hints`, `suggestedCall`, `exampleCalls`, `fieldErrors`, and `context` are surfaced whenever the underlying `AppError` supplies them (previously the resource envelope returned only `code` + `detail`). The envelope keeps its existing nested `{ error, meta }` shape and the generic `problems/resource` type/title. Additive and non-breaking for clients reading by key.
+- **Breaking:** error envelopes add a new `retryClass` value `"server"` for non-recoverable internal server faults. `ERR_INTERNAL` (sanitized programming bugs / unexpected throws, including every non-`AppError` thrown by a handler) and `ERR_DB_FAILURE` (SQLite integrity/migration failures) now report `retryClass: "server"` instead of `"transient"`, so agents stop retrying deterministic server bugs. Genuinely-transient codes are unchanged — `ERR_REPO_FETCH_FAILED`, `ERR_ARTIFACT_RESOLUTION_FAILED`, `ERR_STAGE_BUDGET_PRE_PARSE`, `ERR_LIMIT_EXCEEDED`, and `ERR_JAVA_PROCESS_FAILED` stay `"transient"`. Clients that exhaustively `switch` on `retryClass` must add a `"server"` case (treat it like `"permanent"` for retry posture: do not retry the identical call). `issueOrigin` is unchanged (`ERR_INTERNAL` stays `tool_issue`).
+
+### Fixed
+
+- `remap-mod-jar` no longer serves a stale remapped JAR after a newer Fabric **yarn** build is published for the same Minecraft version. Yarn Tiny mappings are now cached per build coordinate (`mappings/yarn/${coordinate}.tiny`) and the resolved yarn coordinate is part of the remap cache key, so a new build produces a fresh remap instead of reusing the old jar. The newest build is re-checked at most once per 24h per MC version (a small on-disk metadata marker keeps the check off the cache-hit fast path; on a Fabric Maven outage the last-known-good build is reused rather than failing). Mojang mappings are immutable per release and unaffected. `remap-mod-jar` gains an optional `forceRemap: true` to bypass the cache and re-resolve on demand. The remap pipeline version bumps (`v2`→`v3`), a one-time invalidation of previously cached remapped jars; obsolete `mappings/${version}-yarn.tiny` files can be reclaimed via `manage-cache` on the `mapping` kind.
+
+### Performance
+
+- `get-class-api-matrix` now computes per-row cross-namespace mappings only for the requested page (`maxRows`/`cursor` window) instead of the whole class on every request, so paginated/deep-page calls scale with the window rather than the full member set. `rows`, row order, `rowCount`, `nextCursor`, and `cursorIgnored` are byte-identical. **Behavior change:** on paginated calls, `warnings` (per-row ambiguity notes) and `ambiguousRowCount` now reflect only the returned page; an unpaginated call (no `maxRows`) still reports them for the whole class.
+
+## [4.2.1] - 2026-05-23
+
+### Fixed
+- Mojang binary-remap cache writes recover from corrupt `<cacheDir>/remapped/<artifactId>.jar` directories instead of surfacing raw `ENOTEMPTY`, and `manage-cache` can list and delete those corrupt `binary-remap` entries by `selector.artifactId`.
+- `isAppError(value)` now narrows to `AppError` via `instanceof AppError` instead of `Error & { code: string }`. Plain `Error` objects that happen to carry a `code` field no longer pass the guard, so unrelated errors can no longer leak through `AppError`-specific error handling.
+- Java NBT `TAG_String` now encodes/decodes via MUTF-8 to match Mojang's `DataInputStream.readUTF` / `DataOutputStream.writeUTF` contract. Supplementary characters (emoji, supplementary CJK) and the NUL character (`U+0000`) now round-trip correctly. ASCII and common BMP byte sequences are byte-identical to the previous UTF-8 output, so existing NBT payloads are unaffected.
+
 ## [4.2.0] - 2026-05-17
 
 ### Added

package/README.md

@@ -15,7 +15,7 @@
 
 It runs over stdio and works with Claude Desktop, Claude Code, VS Code, Codex CLI, Gemini CLI, and other MCP-capable clients.
 
-**37 tools** (6 entry + 31 expert) | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
+**41 tools** (6 entry + 35 expert) | **9 resources** | **4 namespace mappings** | **SQLite-backed cache**
 
 ## Features
 
@@ -164,6 +164,7 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - `validate-mixin` and `validate-project` keep `mapping-health` lightweight for `obfuscated` and `mojang` validation, avoiding full Tiny mapping graph loads unless `intermediary` or `yarn` namespaces are requested.
 - `validate-project task="project-summary"` uses a lightweight artifact probe for `tasks["minecraft.artifact.resolved"]`; it does not decompile Minecraft or rebuild the source index just to report per-probe status. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
 - If a workspace was built with `GRADLE_USER_HOME=/tmp/...` or another isolated Gradle home, pass that path as `gradleUserHome` so source, mapping, runtime, and project validation lookups use the same Loom cache instead of stale caches under the MCP process home.
+- `manage-cache` reports corrupt Mojang binary-remap cache directories under `cacheKinds: ["binary-remap"]` with `status: "corrupt"`, and can delete them by `selector.artifactId` in preview/apply workflows.
 
 ### Inspect Minecraft source from a version
 
@@ -202,7 +203,8 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
     "version": "1.21.10",
     "sourceMapping": "mojang",
     "targetMapping": "intermediary",
-    "signatureMode": "name-only"
+    "signatureMode": "name-only",
+    "detail": "standard"
   }
 }
 ```
@@ -305,13 +307,13 @@ Tools for converting symbol names between namespaces and checking symbol existen
 | Tool | Purpose |
 | --- | --- |
 | `find-mapping` | Look up mapping candidates for class, field, or method symbols |
-| `resolve-method-mapping-exact` | Resolve one method mapping with strict owner, name, and descriptor matching |
+| `resolve-method-mapping-exact` | Strict shortcut for `find-mapping` (kind=method, signatureMode=exact); requires the full owner+name+descriptor triple |
 | `get-class-api-matrix` | Show one class API across `obfuscated`, `mojang`, `intermediary`, and `yarn` |
 | `resolve-workspace-symbol` | Resolve compile-visible symbol names from a Gradle workspace |
 | `check-symbol-exists` | Check whether a class, field, or method exists in a namespace |
 <!-- END GENERATED TOOL TABLE: mapping-symbols -->
 
-Several lookup tools support `compact` result shaping for shorter responses. See [docs/tool-reference.md](docs/tool-reference.md) for defaults and the full per-tool field list.
+Expert and batch tools share the `detail` (`summary` | `standard` | `full`) + `include[]` response contract for shorter responses (replacing the old per-tool `compact` flag). See [docs/tool-reference.md](docs/tool-reference.md) for per-tool defaults and the full field list.
 
 ### NBT Utilities
 

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

@@ -1,8 +1,9 @@
 export type AccessTransformerAccessAction = "public" | "protected" | "package-private" | "private";
 export type AccessTransformerFinalAction = "add" | "remove";
+export type AccessTransformerTargetKind = "class" | "field" | "method" | "wildcard-all" | "wildcard-method";
 export type AccessTransformerEntry = {
     line: number;
-    targetKind: "class" | "field" | "method";
+    targetKind: AccessTransformerTargetKind;
     owner: string;
     target: string;
     name?: string;

package/dist/access-transformer-parser.js

@@ -19,10 +19,19 @@ function splitMemberToken(tokens) {
     if (tokens.length === 1) {
         const token = tokens[0] ?? "";
         const descriptorStart = token.indexOf("(");
+        // Wildcards: "*" targets all fields and methods; "*()" targets all methods.
+        // (Standard Forge/NeoForge AT syntax — previously parsed as a literal name.)
+        if (token === "*") {
+            return { targetKind: "wildcard-all", name: "*" };
+        }
         if (descriptorStart >= 0) {
+            const namePart = token.slice(0, descriptorStart);
+            if (namePart === "*") {
+                return { targetKind: "wildcard-method", name: "*", descriptor: token.slice(descriptorStart) };
+            }
             return {
                 targetKind: "method",
-                name: token.slice(0, descriptorStart),
+                name: namePart,
                 descriptor: token.slice(descriptorStart)
             };
         }

package/dist/build-suggested-call.js

@@ -6,16 +6,33 @@ function asParamsRecord(params) {
     }
     return params;
 }
-export function buildSuggestedCall(spec) {
-    if (SUGGESTED_CALL_VALIDATE_OFF) {
-        const rawParams = asParamsRecord(spec.params);
-        if (rawParams) {
-            return { suggestedCall: { tool: spec.tool, params: rawParams } };
-        }
-        return {};
+// Placeholder sentinels are `<...>` tokens that a caller must substitute before
+// the call is executable (e.g. "<version>", "<fully-qualified-class-name>").
+// The two JVM pseudo-method-names `<init>` / `<clinit>` are real, valid values
+// and are explicitly excluded so constructor lookups are not misclassified.
+const PLACEHOLDER_SENTINEL_RE = /<(?!init>)(?!clinit>)[^<>]+>/;
+function containsPlaceholderSentinel(value) {
+    if (typeof value === "string") {
+        return PLACEHOLDER_SENTINEL_RE.test(value);
+    }
+    if (Array.isArray(value)) {
+        return value.some(containsPlaceholderSentinel);
+    }
+    if (value && typeof value === "object") {
+        return Object.values(value).some(containsPlaceholderSentinel);
     }
+    return false;
+}
+export function buildSuggestedCall(spec) {
     const primaryParams = asParamsRecord(spec.params);
-    if (primaryParams) {
+    // A `suggestedCall` must be directly executable. Reject any primary payload
+    // that still carries a placeholder sentinel (e.g. "<version>") even when it
+    // is schema-valid: those belong in `exampleCalls` as templates, not as a
+    // call the caller can replay verbatim.
+    if (primaryParams && !containsPlaceholderSentinel(primaryParams)) {
+        if (SUGGESTED_CALL_VALIDATE_OFF) {
+            return { suggestedCall: { tool: spec.tool, params: primaryParams } };
+        }
         // Unknown-tool fail-open: the registry is populated at index.ts startup;
         // service-level tests that do not boot index.ts run with an empty
         // registry and rely on this pass-through. Callers that synthesize a tool
@@ -31,14 +48,18 @@ export function buildSuggestedCall(spec) {
     }
     const droppedMarker = spec.params !== undefined ? { _suggestedCallPrimaryDropped: true } : {};
     if (spec.examples && spec.examples.length > 0) {
+        // Example calls are templates (placeholders allowed) and only their
+        // schema-shape is checked. Mirror the primary path's unknown-tool
+        // fail-open so service-level tests with an unpopulated registry still
+        // surface templates instead of silently dropping them.
+        const exampleSchemaUnavailable = SUGGESTED_CALL_VALIDATE_OFF || !getToolSchema(spec.tool);
         const validated = spec.examples
             .map((example) => {
             const exampleParams = asParamsRecord(example.params);
             if (!exampleParams) {
                 return null;
             }
-            const result = validateToolParams(spec.tool, exampleParams);
-            if (!result.valid) {
+            if (!exampleSchemaUnavailable && !validateToolParams(spec.tool, exampleParams).valid) {
                 return null;
             }
             return {

package/dist/cache-registry.d.ts

@@ -34,6 +34,14 @@ type CacheEntryPage = {
     entries: CacheEntry[];
     nextCursor?: string;
 };
+/**
+ * Whether a cache entry path contains the selector version as a whole version
+ * token. Used as a fallback when an entry has no structured meta.version. The
+ * match is anchored so that a coarse selector like "1.2" does NOT match a "1.21"
+ * path (which would cause destructive prune/delete to hit the wrong caches),
+ * while still allowing major.minor sweeps where "1.21" matches "1.21.4".
+ */
+export declare function pathContainsVersion(path: string, version: string): boolean;
 export type CacheRegistryConfig = {
     cacheDir: string;
     sqlitePath: string;

package/dist/cache-registry.js

@@ -99,6 +99,20 @@ function inferVersion(...candidates) {
     }
     return undefined;
 }
+/**
+ * Whether a cache entry path contains the selector version as a whole version
+ * token. Used as a fallback when an entry has no structured meta.version. The
+ * match is anchored so that a coarse selector like "1.2" does NOT match a "1.21"
+ * path (which would cause destructive prune/delete to hit the wrong caches),
+ * while still allowing major.minor sweeps where "1.21" matches "1.21.4".
+ */
+export function pathContainsVersion(path, version) {
+    const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Preceding char must not be a digit or dot (avoid matching inside a longer
+    // version like 1.21 -> 21); following char must not be a digit (block
+    // 1.2 -> 1.21) but a dot is allowed so 1.21 sweeps 1.21.4.
+    return new RegExp(`(?<![\\d.])${escaped}(?!\\d)`).test(path);
+}
 function inferMapping(...candidates) {
     for (const candidate of candidates) {
         const normalized = candidate?.toLowerCase();
@@ -329,7 +343,7 @@ function matchesSelector(entry, selector, runtimeInfo) {
     }
     if (selector.version) {
         const version = typeof maybeMeta.version === "string" ? maybeMeta.version : undefined;
-        if (version !== selector.version && !entry.path.includes(selector.version)) {
+        if (version !== selector.version && !pathContainsVersion(entry.path, selector.version)) {
             return false;
         }
     }
@@ -442,6 +456,9 @@ function workspaceCacheEntries(workspaceCache) {
     }));
 }
 async function fileBackedEntries(config, cacheKind) {
+    if (cacheKind === "binary-remap") {
+        return binaryRemapEntries(config);
+    }
     const root = kindRoot(config, cacheKind);
     const files = await listFilesRecursive(root);
     const entries = [];
@@ -466,17 +483,91 @@ async function fileBackedEntries(config, cacheKind) {
                 inUse: filePath.endsWith(".lock") ||
                     filePath.endsWith(".wal") ||
                     filePath.endsWith(".journal"),
-                ...(cacheKind === "downloads" || cacheKind === "mod-remap" || cacheKind === "binary-remap"
+                ...(cacheKind === "downloads" || cacheKind === "mod-remap"
                     ? { jarPath: filePath }
-                    : {}),
-                ...(cacheKind === "binary-remap"
-                    ? { artifactId: normalizedEntryId.replace(/\.jar$/i, "") }
                     : {})
             }
         });
     }
     return entries;
 }
+/**
+ * Binary-remap cache entries are keyed by the final artifact id even when the
+ * on-disk entry is a corrupt final directory or a leftover temp path.
+ */
+function parseBinaryRemapEntryName(name) {
+    const legacyTempMatch = /^(.+)\.jar\.tmp\..+$/.exec(name);
+    if (legacyTempMatch?.[1]) {
+        return { artifactId: legacyTempMatch[1], corrupt: true };
+    }
+    const tempMatch = /^(.+)\.tmp\.\d+\.\d+\.[A-Za-z0-9_-]+\.jar$/.exec(name);
+    if (tempMatch?.[1]) {
+        return { artifactId: tempMatch[1], corrupt: true };
+    }
+    const finalJarMatch = /^(.+)\.jar$/.exec(name);
+    if (finalJarMatch?.[1]) {
+        return { artifactId: finalJarMatch[1], corrupt: false };
+    }
+    return undefined;
+}
+async function binaryRemapEntries(config) {
+    const root = kindRoot(config, "binary-remap");
+    if (!existsSync(root)) {
+        return [];
+    }
+    const entries = [];
+    // Do not recurse here: a corrupt `<artifactId>.jar` directory must remain one
+    // selectable cache entry so `selector.artifactId` can remove it recursively.
+    const dirents = await readdir(root, { withFileTypes: true });
+    for (const entry of dirents.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isFile() && !entry.isDirectory()) {
+            continue;
+        }
+        const parsed = parseBinaryRemapEntryName(entry.name);
+        if (!parsed) {
+            continue;
+        }
+        const filePath = join(root, entry.name);
+        const fileStat = await stat(filePath);
+        const corrupt = parsed.corrupt || entry.isDirectory();
+        const sizeBytes = entry.isDirectory()
+            ? await directoryFileSizeBytes(filePath)
+            : fileStat.size;
+        entries.push({
+            cacheKind: "binary-remap",
+            entryId: entry.name,
+            path: filePath,
+            sizeBytes,
+            status: corrupt ? "corrupt" : "healthy",
+            meta: {
+                updatedAt: fileStat.mtime.toISOString(),
+                version: inferVersion(filePath, entry.name),
+                mapping: inferMapping(filePath, entry.name),
+                scope: inferScope(filePath, entry.name),
+                projectPath: inferProjectPath(filePath, config.pathRuntimeInfo),
+                partial: entry.isFile() && fileStat.size === 0,
+                corrupt,
+                inUse: false,
+                jarPath: filePath,
+                artifactId: parsed.artifactId
+            }
+        });
+    }
+    return entries;
+}
+async function directoryFileSizeBytes(root) {
+    const files = await listFilesRecursive(root);
+    let totalBytes = 0;
+    for (const filePath of files) {
+        try {
+            totalBytes += (await stat(filePath)).size;
+        }
+        catch {
+            // The entry may disappear during cleanup or a concurrent cache write.
+        }
+    }
+    return totalBytes;
+}
 export function createCacheRegistry(config) {
     const workspaceCache = config.workspaceContextCache ?? getProcessWorkspaceContextCache();
     async function collectEntries(cacheKinds, selector) {
@@ -564,7 +655,9 @@ export function createCacheRegistry(config) {
                             continue;
                         }
                         if (existsSync(entry.path)) {
-                            await rm(entry.path, { force: true });
+                            // Only binary-remap inventory can return directories as entries;
+                            // other file-backed kinds keep their existing file-only contract.
+                            await rm(entry.path, { recursive: entry.cacheKind === "binary-remap", force: true });
                         }
                     }
                 }

package/dist/config.d.ts

@@ -12,6 +12,7 @@ declare const DEFAULTS: {
     readonly fetchTimeoutMs: 15000;
     readonly fetchRetries: 2;
     readonly searchScanPageSize: 250;
+    readonly searchScanMaxBytes: 67108864;
     readonly indexInsertChunkSize: 200;
     readonly maxMappingGraphCache: 16;
     readonly maxSignatureCache: 2000;

package/dist/config.js

@@ -20,6 +20,7 @@ const DEFAULTS = {
     fetchTimeoutMs: 15000,
     fetchRetries: 2,
     searchScanPageSize: 250,
+    searchScanMaxBytes: 67_108_864,
     indexInsertChunkSize: 200,
     maxMappingGraphCache: 16,
     maxSignatureCache: 2_000,
@@ -41,6 +42,8 @@ const MAX_CACHE_BYTES_LOWER_BOUND = 1_024;
 const TIMEOUT_LOWER_BOUND_MS = 500;
 const SEARCH_SCAN_PAGE_SIZE_LOWER_BOUND = 1;
 const SEARCH_SCAN_PAGE_SIZE_UPPER_BOUND = 10_000;
+const SEARCH_SCAN_MAX_BYTES_LOWER_BOUND = 1_024;
+const SEARCH_SCAN_MAX_BYTES_UPPER_BOUND = 4_294_967_296;
 const INDEX_INSERT_CHUNK_SIZE_LOWER_BOUND = 1;
 const INDEX_INSERT_CHUNK_SIZE_UPPER_BOUND = 20_000;
 const CACHE_ENTRIES_LOWER_BOUND = 1;
@@ -163,6 +166,7 @@ export function loadConfig() {
         fetchTimeoutMs: parseNumber(process.env.MCP_FETCH_TIMEOUT_MS, DEFAULTS.fetchTimeoutMs, TIMEOUT_LOWER_BOUND_MS, Number.MAX_SAFE_INTEGER),
         fetchRetries: parseNumber(process.env.MCP_FETCH_RETRIES, DEFAULTS.fetchRetries, MAX_RETRIES_LOWER_BOUND, MAX_RETRIES_UPPER_BOUND),
         searchScanPageSize: parseNumber(process.env.MCP_SEARCH_SCAN_PAGE_SIZE, DEFAULTS.searchScanPageSize, SEARCH_SCAN_PAGE_SIZE_LOWER_BOUND, SEARCH_SCAN_PAGE_SIZE_UPPER_BOUND),
+        searchScanMaxBytes: parseNumber(process.env.MCP_SEARCH_SCAN_MAX_BYTES, DEFAULTS.searchScanMaxBytes, SEARCH_SCAN_MAX_BYTES_LOWER_BOUND, SEARCH_SCAN_MAX_BYTES_UPPER_BOUND),
         indexInsertChunkSize: parseNumber(process.env.MCP_INDEX_INSERT_CHUNK_SIZE, DEFAULTS.indexInsertChunkSize, INDEX_INSERT_CHUNK_SIZE_LOWER_BOUND, INDEX_INSERT_CHUNK_SIZE_UPPER_BOUND),
         maxMappingGraphCache: parseNumber(process.env.MCP_CACHE_GRAPH_MAX, DEFAULTS.maxMappingGraphCache, CACHE_ENTRIES_LOWER_BOUND, CACHE_ENTRIES_UPPER_BOUND),
         maxSignatureCache: parseNumber(process.env.MCP_CACHE_SIGNATURE_MAX, DEFAULTS.maxSignatureCache, CACHE_ENTRIES_LOWER_BOUND, CACHE_ENTRIES_UPPER_BOUND),

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

@@ -75,8 +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" | "field" | "method" | "all" | "content";
-    task: "search" | "remap" | "summary" | "class-source" | "decompile";
+    task: "search" | "summary" | "class-source" | "remap" | "decompile";
     subject: {
         kind: "jar";
         jarPath: string;
@@ -85,18 +84,19 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
         jarPath: string;
         className: string;
     };
-    includeFiles: boolean;
+    searchType: "class" | "field" | "method" | "all" | "content";
     executionMode: "preview" | "apply";
+    includeFiles: boolean;
     maxLines?: number | undefined;
     maxChars?: number | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
+    include?: string[] | undefined;
+    query?: string | undefined;
     targetMapping?: "mojang" | "yarn" | undefined;
     outputJar?: string | undefined;
-    query?: string | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
-    include?: string[] | undefined;
     maxFiles?: number | undefined;
 }, {
-    task: "search" | "remap" | "summary" | "class-source" | "decompile";
+    task: "search" | "summary" | "class-source" | "remap" | "decompile";
     subject: {
         kind: "jar";
         jarPath: string;
@@ -108,19 +108,18 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     limit?: number | undefined;
     maxLines?: number | undefined;
     maxChars?: number | undefined;
-    targetMapping?: "mojang" | "yarn" | undefined;
-    outputJar?: string | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
+    include?: string[] | undefined;
     query?: string | undefined;
     searchType?: "class" | "field" | "method" | "all" | "content" | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
-    include?: string[] | undefined;
+    targetMapping?: "mojang" | "yarn" | undefined;
+    outputJar?: string | undefined;
+    executionMode?: "preview" | "apply" | undefined;
     includeFiles?: boolean | undefined;
     maxFiles?: number | undefined;
-    executionMode?: "preview" | "apply" | undefined;
 }>, {
     limit: number;
-    searchType: "class" | "field" | "method" | "all" | "content";
-    task: "search" | "remap" | "summary" | "class-source" | "decompile";
+    task: "search" | "summary" | "class-source" | "remap" | "decompile";
     subject: {
         kind: "jar";
         jarPath: string;
@@ -129,18 +128,19 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
         jarPath: string;
         className: string;
     };
-    includeFiles: boolean;
+    searchType: "class" | "field" | "method" | "all" | "content";
     executionMode: "preview" | "apply";
+    includeFiles: boolean;
     maxLines?: number | undefined;
     maxChars?: number | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
+    include?: string[] | undefined;
+    query?: string | undefined;
     targetMapping?: "mojang" | "yarn" | undefined;
     outputJar?: string | undefined;
-    query?: string | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
-    include?: string[] | undefined;
     maxFiles?: number | undefined;
 }, {
-    task: "search" | "remap" | "summary" | "class-source" | "decompile";
+    task: "search" | "summary" | "class-source" | "remap" | "decompile";
     subject: {
         kind: "jar";
         jarPath: string;
@@ -152,15 +152,15 @@ export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
     limit?: number | undefined;
     maxLines?: number | undefined;
     maxChars?: number | undefined;
-    targetMapping?: "mojang" | "yarn" | undefined;
-    outputJar?: string | undefined;
+    detail?: "summary" | "standard" | "full" | undefined;
+    include?: string[] | undefined;
     query?: string | undefined;
     searchType?: "class" | "field" | "method" | "all" | "content" | undefined;
-    detail?: "full" | "summary" | "standard" | undefined;
-    include?: string[] | undefined;
+    targetMapping?: "mojang" | "yarn" | undefined;
+    outputJar?: string | undefined;
+    executionMode?: "preview" | "apply" | undefined;
     includeFiles?: boolean | undefined;
     maxFiles?: number | undefined;
-    executionMode?: "preview" | "apply" | undefined;
 }>;
 export type AnalyzeModInput = z.infer<typeof analyzeModSchema>;
 type AnalyzeModDeps = {