@adhisang/minecraft-modding-mcp 5.0.0 → 6.0.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [6.0.0] - 2026-06-25
+
+### Changed
+
+- **Breaking:** tool responses omit `meta.warnings` entirely when there are no warnings (previously always emitted as `[]`), and omit `meta.detailApplied` when it equals the tool's default detail level (entry tools: `summary`; expert/batch tools: their per-tool default). Clients must treat a missing `meta.warnings` as "no warnings" and a missing `meta.detailApplied` as "the default detail was applied". `meta.includeApplied` semantics are unchanged (already omitted when empty).
+- `tools/list` payload slimmed by ~12% (93.2 KB → 82.2 KB, roughly 2,700 fewer tokens held in an agent's context): parameter descriptions that merely echoed enum values (e.g. `"obfuscated | mojang | intermediary | yarn"`) are removed since the JSON Schema `enum` already carries them, the shared `detail`/`include`/`target`/`scope`/`gradleUserHome` descriptions are tightened, the expert-tool steering note is shortened, and the longest tool descriptions (`resolve-method-mapping-exact`, `get-class-source`, `get-class-members`, the `batch-*` family) no longer repeat information already present in their input schemas. Wording-only — no input shapes, defaults, or validation rules changed.
+- Per-member remap-failure warnings are aggregated into a single line per namespace direction (e.g. `Could not remap 12 methods from obfuscated to mojang (foo, bar, baz, +9 more).`) instead of one line per member, and the structured `meta.warningDetails[]` companion is capped to a representative set (5 entries) at `detail: "summary"` (the full text still lives in `meta.warnings[]`, so each kept entry's `index` still dereferences it). On unobfuscated versions a single core class could previously emit hundreds of near-identical remap-warning lines — the dominant token sink for those responses.
+
+### Fixed
+
+- `validate-mixin` / mixin parsing: `@Mixin(My$GeneratedClass.class)` class-literal targets containing `$` (a legal Java identifier character) are now captured as the full class name; previously the target regex started the capture mid-name and produced a wrong target.
+- **Unobfuscated Minecraft versions (26.1+):** `get-class-members` / `get-class-source` no longer mislabel the already-deobfuscated runtime namespace as `obfuscated` for a `mapping: "mojang"` request when reusing a previously-resolved artifact. The mislabel made `requestedMapping ("mojang") !== mappingApplied ("obfuscated")`, which triggered a doomed mojang↔obfuscated remap that dropped every member (forcing a spurious `decompiledFallback`), disabled `memberPattern`, and flooded the response with per-member remap warnings. The namespace is now reconciled to `mojang` (identity), so members come back from bytecode with correct names, `memberPattern` applies, and the warning flood disappears.
+- **`batch-symbol-exists` / `check-symbol-exists` on unobfuscated versions:** method existence checks returned `not_found` for methods that genuinely exist, because the empty mapping graph reported `not_found` and skipped the runtime-bytecode fallback. The fallback now runs for `not_found` method queries; name-only lookups resolve when any overload matches (no longer reported as `ambiguous` for an existence check), and inherited methods are included (`level.getGameTime()` resolves on `Level`).
+- `check-symbol-exists`: a class genuinely absent from the runtime jar now yields a clear `… was not found in the Minecraft <version> runtime jar` message instead of a generic load-failure note.
+- `resolve-artifact`: a decompilation failure (`ERR_DECOMPILER_FAILED`) no longer advertises an `artifactId` for an artifact that was never persisted — the leaked id previously caused a follow-up `find-class` / `get-class-*` to fail with "Artifact not found. Resolve context first."
+- Workspace dependency version detection falls back to the umbrella package's version property (e.g. `fabricApiVersion` / `fabric_api_version`) for submodules that don't declare their own (e.g. `net.fabricmc.fabric-api:fabric-screen-handler-api-v1`), instead of failing with `ERR_DEPENDENCY_VERSION_UNRESOLVED`. The submodule's own property still takes precedence when present.
+- `get-class-source` now honors an explicit `mapping` argument instead of forcing the artifact's stored namespace (matching `get-class-members`), so a `className` supplied in a declared namespace no longer fails with `CLASS_NOT_FOUND`. Several recovery `suggestedCall`s are corrected: the snippet continuation no longer drops the default `maxLines` (which produced an unbounded follow-up read), the `decompiledFallback` truncation flag is reported accurately, and a hardcoded `"latest"` version that `resolve-artifact` rejects is replaced with the concrete resolved version. A method query with an omitted `signatureMode` is treated as a non-exact match in the runtime check (descriptorless methods are no longer guaranteed `not_found`), binary jars are remapped from the source jar (not the absent output) after an index loss, the `globToSqlLike` `**` push-down no longer drops direct children, the vanilla-jar fallback no longer retains the named-signature mapping, and the workspace-context write-back is serialized so it stops racing dependency-target synthesis.
+- `resolve-method-mapping-exact` mirrors `find-mapping`'s obfuscated-namespace acceptance set, so a single-hop `intermediary → yarn` lookup whose candidate carries an obfuscated-namespace descriptor no longer returns a false `not_found`. Loading yarn Tiny pairs from Maven no longer unions three builds (or fetches unusable v1 jars), removing the spurious `ambiguous` results that produced. Tiny caches (`extractTinyFromJar` / `resolveMojangTinyFile`) are now written atomically (temp file + `rename`) so a crash mid-write cannot leave a truncated `.tiny` behind a permanent `existsSync` fast path, and `get-class-api-matrix` keys its cursor context on `gradleUserHome` so a cursor minted against one dependency graph cannot replay against another.
+- `validate-mixin` / mixin parsing no longer matches the word `class` inside comments or javadoc (which yielded a wrong `className`) and no longer parses annotations inside block comments (which produced phantom `@Shadow` / `@Accessor` members and false definite errors); both passes now skip comment regions. The injection-point wildcard quantifier is anchored so an exact-match target no longer triggers a false positive.
+- `search-class-source` / file search no longer re-emits `both`-tier hits as duplicate `content`-tier hits on later pages (they are deduped across the cursor), escapes the `LIKE` needle in path search, push-down, and count queries so the declared `ESCAPE` clause actually applies, and stops returning a `nextCursor` on the final partial page (which previously forced an extra empty-page fetch).
+- `inspect-minecraft`: `task: "versions"` no longer drops the entire `versions` block at the default detail level, and `task: "file"` content is reachable now that `file` is a valid `include` group. `task: "api-overview"` honors `maxRows` and flags truncation instead of silently capping the matrix at 25 rows while reporting `rowsTruncated: false`. The `file` / `search` / `list-files` tasks return the friendly "blocked" summary (carrying the version-inference warning) instead of forwarding an empty `artifactId`, `task: "workspace"` no longer passes the literal `"unknown"` as the Minecraft version, the `get-class-members` truncation `nextAction` raises the member limit so the suggested retry no longer reproduces the same cut, and the `remap-mod-jar` preview `nextAction` preserves an explicit `outputJar`.
+- stdio supervisor: a supervisor-replayed `initialize` no longer emits a stray error response when the worker crashes again after the client is already initialized; a worker spawn error that previously stalled the supervisor permanently now recovers; and a stale worker exit no longer detaches and orphans the replacement worker. The Java subprocess runner drains trailing stdout/stderr before resolving on child exit, so the final output is no longer lost.
+- NBT JSON Patch: an `add` / `replace` op with key `__proto__` is assigned as an own enumerable property instead of silently mutating the prototype and dropping the member. Non-finite floats round-trip correctly — decode emits a sentinel string rather than a raw number, and the typed-JSON layer no longer rejects otherwise-valid NBT containing `NaN` / `Infinity`.
+- Data generation no longer deadlocks once the child's stdout pipe buffer fills (the output is now drained), the download timeout now covers the response body stream instead of being cleared after headers (removing an indefinite hang), and concurrent identical `remap-mod-jar` calls no longer race on a non-atomic cache copy.
+- Access Widener parsing accepts valid `transitive-` kinds — the prefix is stripped, the base kind validated, and transitivity recorded on the entry — instead of rejecting them as unknown. Path conversion recognizes the `wsl.localhost` UNC form (not only `wsl$`) and rejects a UNC WSL path that targets a different distro than the server runs in, instead of silently mapping it.
+- `validate-mixin` recovery suggestions no longer read `input.path` before checking the mode (which turned a project-mode call into an executable path-mode `suggestedCall`), and the access-transformer suggestion no longer hardcodes the access-widener subject kind. The `batch-class-source` `outputFile` dedupe guard canonicalizes paths unconditionally so absolute-path aliases (`/a/../b`, `//a`) collide as intended and cannot race `writeFile` on the same inode.
+
+### Performance
+
+- SQLite repositories cache prepared statements for dynamically built queries (cursor-paginated symbol/file lookups, scoped symbol search, count queries, `IN (...)`-list lookups) in a small per-repo LRU instead of re-preparing the SQL on every call.
+- Symbol search with regex/glob/package filters now streams rows from SQLite instead of materializing every symbol of the artifact in memory first; only matching rows are retained.
+- Cache-registry operations no longer read and JSON-parse every registry file from disk on each call; the parsed registry state is cached and invalidated on write.
+- `get-class-members` / `get-class-source` no longer re-strip the whole decompiled file once per nested type when extracting members (`extractDecompiledMembers` was quadratic in the nested-type count).
+- NBT patch validation revalidates only the touched subtree per patch op instead of the whole document (previously quadratic), and the array encoders reuse a single buffer cursor instead of allocating a `Buffer` per scalar write.
+- `check-symbol-exists` indexes its lookups instead of scanning the full target namespace on every call.
+
 ## [5.0.0] - 2026-06-04
 
 ### Changed

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

@@ -9,6 +9,7 @@
 export type AccessWidenerEntry = {
     line: number;
     kind: "accessible" | "extendable" | "mutable";
+    transitive?: boolean;
     targetKind: "class" | "method" | "field";
     target: string;
     owner?: string;

package/dist/access-widener-parser.js

@@ -40,7 +40,9 @@ export function parseAccessWidener(content) {
         }
         const kind = parts[0];
         const targetKind = parts[1];
-        if (!VALID_KINDS.has(kind)) {
+        const transitive = kind.startsWith("transitive-");
+        const baseKind = transitive ? kind.slice("transitive-".length) : kind;
+        if (!VALID_KINDS.has(baseKind)) {
             parseWarnings.push(`Line ${lineNum}: Unknown access kind "${kind}".`);
             continue;
         }
@@ -48,16 +50,17 @@ export function parseAccessWidener(content) {
             parseWarnings.push(`Line ${lineNum}: Unknown target kind "${targetKind}".`);
             continue;
         }
-        const validKind = kind;
+        const validKind = baseKind;
         const validTargetKind = targetKind;
         if (validTargetKind === "class") {
-            entries.push({ line: lineNum, kind: validKind, targetKind: validTargetKind, target: parts[2] });
+            entries.push({ line: lineNum, kind: validKind, transitive, targetKind: validTargetKind, target: parts[2] });
         }
         else if (parts.length >= 5) {
             // method/field: <kind> <targetKind> <owner> <name> <descriptor>
             entries.push({
                 line: lineNum,
                 kind: validKind,
+                transitive,
                 targetKind: validTargetKind,
                 target: parts[2],
                 owner: parts[2],

package/dist/cache-registry.js

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
-import { readdir, rm, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { readFile, readdir, rm, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { mapWithConcurrencyLimit } from "./concurrency.js";
 import { createError, ERROR_CODES } from "./errors.js";
 import { normalizeOptionalPathForHost } from "./path-converter.js";
 import Database from "./storage/sqlite.js";
@@ -25,6 +26,7 @@ export const CACHE_HEALTH_STATES = [
 ];
 const STALE_ENTRY_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 const CURSOR_VERSION = 1;
+const CACHE_STAT_CONCURRENCY = 8;
 const STATUS_PRIORITY = ["in_use", "corrupt", "orphaned", "stale", "partial", "healthy"];
 function kindRoot(config, cacheKind) {
     switch (cacheKind) {
@@ -165,12 +167,12 @@ function inferProjectPath(pathValue, runtimeInfo) {
     }
     return undefined;
 }
-function isCorruptRegistryJson(filePath) {
+async function isCorruptRegistryJson(filePath) {
     if (!filePath.endsWith(".json")) {
         return false;
     }
     try {
-        JSON.parse(readFileSync(filePath, "utf8"));
+        JSON.parse(await readFile(filePath, "utf8"));
         return false;
     }
     catch {
@@ -242,7 +244,7 @@ function candidatePathsForEntry(entry) {
 function entryUpdatedAt(entry) {
     return typeof entry.meta?.updatedAt === "string" ? entry.meta.updatedAt : undefined;
 }
-function deriveEntryStatus(entry, config, now) {
+function deriveEntryStatus(entry, config, now, entryPathExists = false) {
     const maybeMeta = entry.meta ?? {};
     if (maybeMeta.inUse === true) {
         return "in_use";
@@ -251,7 +253,7 @@ function deriveEntryStatus(entry, config, now) {
         return "corrupt";
     }
     const candidatePaths = candidatePathsForEntry(entry);
-    const existingPaths = candidatePaths.filter((candidate) => existsSync(candidate));
+    const existingPaths = candidatePaths.filter((candidate) => (entryPathExists && candidate === entry.path) || existsSync(candidate));
     if (entry.cacheKind === "artifact-index" && !existsSync(config.sqlitePath)) {
         return "orphaned";
     }
@@ -275,10 +277,9 @@ function deriveEntryStatus(entry, config, now) {
 }
 function sortEntries(entries) {
     return [...entries].sort((left, right) => {
-        if (left.cacheKind !== right.cacheKind) {
-            return left.cacheKind.localeCompare(right.cacheKind);
-        }
-        return left.entryId.localeCompare(right.entryId);
+        const leftKey = entrySortKey(left);
+        const rightKey = entrySortKey(right);
+        return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
     });
 }
 function entrySortKey(entry) {
@@ -367,17 +368,19 @@ function matchesSelector(entry, selector, runtimeInfo) {
             return false;
         }
     }
-    const normalizedPaths = candidatePathsForEntry(entry)
-        .map((candidate) => normalizePathKey(candidate, runtimeInfo))
-        .filter((candidate) => Boolean(candidate));
-    if (selector.normalizedJarPath && !normalizedPaths.includes(selector.normalizedJarPath)) {
-        return false;
-    }
-    if (selector.normalizedProjectPath) {
-        const projectMatch = normalizedPaths.some((candidate) => candidate === selector.normalizedProjectPath || candidate.startsWith(`${selector.normalizedProjectPath}/`));
-        if (!projectMatch) {
+    if (selector.normalizedJarPath || selector.normalizedProjectPath) {
+        const normalizedPaths = candidatePathsForEntry(entry)
+            .map((candidate) => normalizePathKey(candidate, runtimeInfo))
+            .filter((candidate) => Boolean(candidate));
+        if (selector.normalizedJarPath && !normalizedPaths.includes(selector.normalizedJarPath)) {
             return false;
         }
+        if (selector.normalizedProjectPath) {
+            const projectMatch = normalizedPaths.some((candidate) => candidate === selector.normalizedProjectPath || candidate.startsWith(`${selector.normalizedProjectPath}/`));
+            if (!projectMatch) {
+                return false;
+            }
+        }
     }
     return true;
 }
@@ -455,18 +458,17 @@ function workspaceCacheEntries(workspaceCache) {
         }
     }));
 }
-async function fileBackedEntries(config, cacheKind) {
+async function fileBackedEntries(config, cacheKind, detectCorruption) {
     if (cacheKind === "binary-remap") {
         return binaryRemapEntries(config);
     }
     const root = kindRoot(config, cacheKind);
     const files = await listFilesRecursive(root);
-    const entries = [];
-    for (const filePath of files) {
+    return mapWithConcurrencyLimit(files, CACHE_STAT_CONCURRENCY, async (filePath) => {
         const fileStat = await stat(filePath);
         const normalizedEntryId = filePath.slice(root.length + 1);
         const inferredScope = inferScope(filePath, normalizedEntryId) ?? (cacheKind === "decompiled-source" ? "vanilla" : undefined);
-        entries.push({
+        return {
             cacheKind,
             entryId: normalizedEntryId,
             path: filePath,
@@ -479,7 +481,7 @@ async function fileBackedEntries(config, cacheKind) {
                 scope: inferredScope,
                 projectPath: inferProjectPath(filePath, config.pathRuntimeInfo),
                 partial: fileStat.size === 0,
-                corrupt: cacheKind === "registry" ? isCorruptRegistryJson(filePath) : false,
+                corrupt: cacheKind === "registry" && detectCorruption ? await isCorruptRegistryJson(filePath) : false,
                 inUse: filePath.endsWith(".lock") ||
                     filePath.endsWith(".wal") ||
                     filePath.endsWith(".journal"),
@@ -487,9 +489,8 @@ async function fileBackedEntries(config, cacheKind) {
                     ? { jarPath: filePath }
                     : {})
             }
-        });
-    }
-    return entries;
+        };
+    });
 }
 /**
  * Binary-remap cache entries are keyed by the final artifact id even when the
@@ -570,9 +571,10 @@ async function directoryFileSizeBytes(root) {
 }
 export function createCacheRegistry(config) {
     const workspaceCache = config.workspaceContextCache ?? getProcessWorkspaceContextCache();
-    async function collectEntries(cacheKinds, selector) {
+    async function collectEntries(cacheKinds, selector, detectCorruption = false) {
         const selectedKinds = cacheKinds?.length ? cacheKinds : [...PUBLIC_CACHE_KINDS];
         const preparedSelector = prepareSelector(selector, config.pathRuntimeInfo);
+        const detectCorruptionForKinds = detectCorruption || selector?.status === "corrupt";
         const now = Date.now();
         const entries = await Promise.all(selectedKinds.map((cacheKind) => {
             if (cacheKind === "artifact-index") {
@@ -581,13 +583,15 @@ export function createCacheRegistry(config) {
             if (cacheKind === "workspace") {
                 return Promise.resolve(workspaceCacheEntries(workspaceCache));
             }
-            return fileBackedEntries(config, cacheKind);
+            return fileBackedEntries(config, cacheKind, detectCorruptionForKinds);
         }));
         const enriched = entries
             .flat()
             .map((entry) => ({
             ...entry,
-            status: entry.cacheKind === "workspace" ? entry.status : deriveEntryStatus(entry, config, now)
+            status: entry.cacheKind === "workspace"
+                ? entry.status
+                : deriveEntryStatus(entry, config, now, entry.cacheKind !== "artifact-index")
         }));
         return sortEntries(enriched.filter((entry) => matchesSelector(entry, preparedSelector, config.pathRuntimeInfo)));
     }
@@ -628,7 +632,7 @@ export function createCacheRegistry(config) {
             return entries.slice(0, limit);
         },
         async verifyEntries(input) {
-            const entries = await collectEntries(input.cacheKinds, input.selector);
+            const entries = await collectEntries(input.cacheKinds, input.selector, true);
             const unhealthy = entries.filter((entry) => entry.status !== "healthy");
             const warningStatuses = [...new Set(unhealthy.map((entry) => entry.status))];
             return {

package/dist/decompiler/vineflower.js

@@ -1,4 +1,4 @@
-import { access, constants, mkdir, readFile, readdir, stat } from "node:fs/promises";
+import { access, constants, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { mkdirSync, rmSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, join, relative, sep } from "node:path";
@@ -8,6 +8,7 @@ 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 DECOMPILE_COMPLETE_MARKER = ".decompile-complete";
 const VINEFLOWER_FLAG_PROFILES = [
     { label: "default", flags: ["-din=1", "-rbr=1", "-dgs=1"] },
     { label: "relaxed", flags: ["-din=1", "-rbr=0", "-dgs=0"] },
@@ -132,7 +133,10 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
     try {
         await mkdir(outputDir, { recursive: true });
         const outputDirStats = await stat(outputDir).catch(() => undefined);
-        if (outputDirStats) {
+        const markerPresent = outputDirStats
+            ? await access(join(outputDir, DECOMPILE_COMPLETE_MARKER), constants.F_OK).then(() => true, () => false)
+            : false;
+        if (outputDirStats && markerPresent) {
             const existingJavaFiles = await collectJavaFiles(outputDir);
             if (existingJavaFiles.length > 0) {
                 const results = await mapWithConcurrencyLimit(existingJavaFiles, DECOMPILED_JAVA_READ_CONCURRENCY, async (candidate) => {
@@ -153,6 +157,7 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
                 };
             }
         }
+        clearOutputDir(outputDir);
         await assertVineflowerAvailable(options.vineflowerJarPath);
         await assertJavaAvailable();
         const profilesAttempted = [];
@@ -189,6 +194,7 @@ export async function decompileBinaryJar(binaryJarPath, cacheDir, options) {
                         content: await readFileTreeText(abs)
                     };
                 });
+                await writeFile(join(outputDir, DECOMPILE_COMPLETE_MARKER), profile.label, "utf8");
                 emitDecompileLog("decompile.done", {
                     durationMs: Date.now() - startedAt,
                     artifactIdCandidate: options.artifactIdCandidate,

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

@@ -248,7 +248,8 @@ export class AnalyzeModService {
                                             jarPath: input.subject.jarPath
                                         },
                                         executionMode: "apply",
-                                        targetMapping: input.targetMapping
+                                        targetMapping: input.targetMapping,
+                                        ...(input.outputJar !== undefined ? { outputJar } : {})
                                     })
                                 ]
                             },

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

@@ -72,7 +72,7 @@ export const analyzeSymbolShape = {
     }),
     version: nonEmptyString
         .optional()
-        .describe("Point-in-time MC version for task=exists/map/exact-map/api-overview. For task=lifecycle it is accepted as a back-compat alias for toVersion (range end)."),
+        .describe("Point-in-time MC version for task=exists/map/exact-map/workspace/api-overview. For task=lifecycle it is accepted as a back-compat alias for toVersion (range end)."),
     fromVersion: nonEmptyString
         .optional()
         .describe("task=lifecycle only: range start (oldest) version; defaults to the oldest version in the manifest."),
@@ -112,11 +112,11 @@ const LIFECYCLE_ONLY_FIELDS = [
     "includeSnapshots"
 ];
 export const analyzeSymbolSchema = z.object(analyzeSymbolShape).superRefine((value, ctx) => {
-    if (value.task !== "workspace" && value.task !== "lifecycle" && !value.version) {
+    if (value.task !== "lifecycle" && !value.version) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["version"],
-            message: "version is required for non-workspace tasks."
+            message: "version is required for non-lifecycle tasks."
         });
     }
     if (value.task === "lifecycle" && !value.version && !value.toVersion) {
@@ -379,7 +379,7 @@ export class AnalyzeSymbolService {
             case "workspace": {
                 const output = await this.deps.resolveWorkspaceSymbol({
                     projectPath: input.projectPath,
-                    version: input.version ?? "unknown",
+                    version: input.version,
                     kind: subjectKind,
                     name: input.subject.name,
                     owner: input.subject.owner,
@@ -405,7 +405,7 @@ export class AnalyzeSymbolService {
                                 owner: input.subject.owner,
                                 descriptor: input.subject.descriptor,
                                 projectPath: input.projectPath,
-                                version: input.version ?? "unknown",
+                                version: input.version,
                                 sourceMapping: input.sourceMapping ?? "obfuscated"
                             }),
                             counts: {
@@ -433,6 +433,11 @@ export class AnalyzeSymbolService {
                     ...(input.gradleUserHome !== undefined ? { gradleUserHome: input.gradleUserHome } : {}),
                     maxRows: input.maxRows
                 });
+                const includeMatrix = include.includes("matrix") || detail !== "summary";
+                const matrixRowCap = input.maxRows ?? 25;
+                const matrixCapWarning = includeMatrix && output.rows.length > matrixRowCap
+                    ? `Matrix rows were truncated to ${matrixRowCap} of ${output.rowCount}. Raise maxRows to include more rows.`
+                    : undefined;
                 return {
                     ...buildEntryToolResult({
                         task: "api-overview",
@@ -458,16 +463,20 @@ export class AnalyzeSymbolService {
                                 className: output.className,
                                 classIdentity: output.classIdentity
                             },
-                            matrix: include.includes("matrix") || detail !== "summary"
+                            matrix: includeMatrix
                                 ? {
                                     rowCount: output.rowCount,
-                                    rowsTruncated: output.rowsTruncated,
-                                    rows: output.rows.slice(0, 25)
+                                    rowsTruncated: output.rowsTruncated || output.rows.length > matrixRowCap,
+                                    rows: output.rows.slice(0, matrixRowCap)
                                 }
                                 : undefined
                         }
                     }),
-                    warnings: inferenceWarning ? [inferenceWarning, ...output.warnings] : output.warnings
+                    warnings: [
+                        ...(inferenceWarning ? [inferenceWarning] : []),
+                        ...output.warnings,
+                        ...(matrixCapWarning ? [matrixCapWarning] : [])
+                    ]
                 };
             }
         }

package/dist/entry-tools/compare-minecraft-service.js

@@ -64,7 +64,7 @@ export class CompareMinecraftService {
                     : {
                         fromVersion: input.subject.fromVersion,
                         toVersion: input.subject.toVersion,
-                        packageFilter: input.subject.kind === "class" ? undefined : input.subject.registry
+                        packageFilter: undefined
                     };
                 const output = await this.deps.compareVersions({
                     fromVersion: subject.fromVersion,

package/dist/entry-tools/inspect-minecraft/handlers/class-members.js

@@ -63,12 +63,13 @@ export async function handleClassMembers(deps, subject, detail, include, limit)
                     include,
                     warnings: [...artifact.warnings, ...members.warnings],
                     truncated: createTruncationMeta({
-                        omittedGroups: ["members"],
+                        omittedGroups: detail === "summary" ? ["members"] : [],
                         nextActions: [
                             createNextAction("inspect-minecraft", {
                                 task: "class-members",
                                 detail: "full",
                                 include: ["members"],
+                                limit: Math.min(members.counts.total, 5000),
                                 subject
                             })
                         ]

package/dist/entry-tools/inspect-minecraft/handlers/file.js

@@ -8,6 +8,31 @@ export async function handleFile(deps, subject, detail, include) {
     const artifact = subject.kind === "file"
         ? await resolveArtifactReference(deps, subject, "file")
         : await resolveWorkspaceArtifactReference(deps, subject, fileSubject.artifact);
+    if (!artifact.artifactId) {
+        const summary = {
+            status: "blocked",
+            headline: `Could not resolve artifact context for ${fileSubject.filePath}.`,
+            subject: createSummarySubject({
+                task: "file",
+                filePath: fileSubject.filePath
+            })
+        };
+        return {
+            ...buildEntryToolResult({
+                task: "file",
+                summary,
+                detail,
+                include,
+                blocks: {
+                    subject: {
+                        requested: subject
+                    }
+                },
+                alwaysBlocks: ["subject"]
+            }),
+            warnings: artifact.warnings
+        };
+    }
     const file = await deps.getArtifactFile({
         artifactId: artifact.artifactId,
         filePath: fileSubject.filePath
@@ -45,7 +70,7 @@ export async function handleFile(deps, subject, detail, include) {
                     content: include.includes("source") || detail !== "summary" ? file.content : undefined
                 }
             },
-            alwaysBlocks: ["subject"]
+            alwaysBlocks: ["subject", "file"]
         }),
         warnings: [...artifact.warnings]
     };

package/dist/entry-tools/inspect-minecraft/handlers/versions.js

@@ -41,7 +41,8 @@ export async function handleVersions(deps, input, detail, include) {
                     snapshots: input.includeSnapshots ? versions.snapshots : undefined,
                     cached: versions.cached
                 }
-            }
+            },
+            alwaysBlocks: ["versions"]
         }),
         warnings: versions.warnings ?? []
     };

package/dist/entry-tools/inspect-minecraft/internal.js

@@ -210,6 +210,7 @@ export async function resolveWorkspaceArtifactReference(deps, subject, artifactR
     return {
         artifactId: artifact.artifactId,
         artifact,
+        version: artifact.version,
         warnings: [...artifact.warnings]
     };
 }
@@ -468,6 +469,7 @@ async function resolveArtifactRef(deps, ref, subject) {
     return {
         artifactId: artifact.artifactId,
         artifact,
+        version: artifact.version,
         warnings: [...artifact.warnings]
     };
 }

package/dist/entry-tools/response-contract.d.ts

@@ -30,6 +30,8 @@ export declare function createTruncationMeta(input: {
 }): TruncationMeta;
 export declare function buildEntryToolMeta(input: {
     detail: DetailLevel;
+    /** When set and equal to `detail`, detailApplied is omitted (the default needs no echo). */
+    defaultDetail?: DetailLevel;
     include?: readonly string[];
     warnings?: readonly string[];
     truncated?: TruncationMeta;

package/dist/entry-tools/response-contract.js

@@ -71,8 +71,8 @@ export function createTruncationMeta(input) {
 }
 export function buildEntryToolMeta(input) {
     return {
-        warnings: [...(input.warnings ?? [])],
-        detailApplied: input.detail,
+        ...(input.warnings && input.warnings.length > 0 ? { warnings: [...input.warnings] } : {}),
+        ...(input.detail === input.defaultDetail ? {} : { detailApplied: input.detail }),
         ...(input.include && input.include.length > 0
             ? { includeApplied: normalizeIncludeGroups(input.include) }
             : {}),

package/dist/entry-tools/validate-project-service.d.ts

@@ -454,7 +454,7 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     reportMode: "full" | "summary-first" | "compact";
     treatInfoAsWarning: boolean;
     includeIssues: boolean;
-    task: "project-summary" | "mixin" | "access-widener" | "access-transformer";
+    task: "project-summary" | "mixin" | "access-transformer" | "access-widener";
     subject: {
         kind: "workspace";
         projectPath: string;
@@ -510,7 +510,7 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     include?: string[] | undefined;
     atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
 }, {
-    task: "project-summary" | "mixin" | "access-widener" | "access-transformer";
+    task: "project-summary" | "mixin" | "access-transformer" | "access-widener";
     subject: {
         kind: "workspace";
         projectPath: string;
@@ -580,7 +580,7 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     reportMode: "full" | "summary-first" | "compact";
     treatInfoAsWarning: boolean;
     includeIssues: boolean;
-    task: "project-summary" | "mixin" | "access-widener" | "access-transformer";
+    task: "project-summary" | "mixin" | "access-transformer" | "access-widener";
     subject: {
         kind: "workspace";
         projectPath: string;
@@ -636,7 +636,7 @@ export declare const validateProjectSchema: z.ZodEffects<z.ZodObject<{
     include?: string[] | undefined;
     atNamespace?: "obfuscated" | "mojang" | "srg" | undefined;
 }, {
-    task: "project-summary" | "mixin" | "access-widener" | "access-transformer";
+    task: "project-summary" | "mixin" | "access-transformer" | "access-widener";
     subject: {
         kind: "workspace";
         projectPath: string;

package/dist/entry-tools/verify-mixin-target-service.js

@@ -5,7 +5,7 @@ import { suggestSimilar } from "../mixin-validator.js";
 export const VERIFY_MIXIN_TARGET_OFF = process.env.VERIFY_MIXIN_TARGET_OFF === "1";
 const ACCESSOR_NAME_RE = /^(get|set|is)([A-Z]\w*)$/;
 const INVOKER_NAME_RE = /^(invoke|call)([A-Z]\w*)$/;
-function decodeAccessFlags(flags) {
+function decodeAccessFlags(flags, kind) {
     const labels = [];
     if (flags == null) {
         return labels;
@@ -23,9 +23,9 @@ function decodeAccessFlags(flags) {
     if ((flags & 0x0020) !== 0)
         labels.push("synchronized");
     if ((flags & 0x0040) !== 0)
-        labels.push("volatile");
+        labels.push(kind === "method" ? "bridge" : "volatile");
     if ((flags & 0x0080) !== 0)
-        labels.push("transient");
+        labels.push(kind === "method" ? "varargs" : "transient");
     if ((flags & 0x0100) !== 0)
         labels.push("native");
     if ((flags & 0x0400) !== 0)
@@ -137,11 +137,11 @@ function deriveVisibility(accessFlags) {
         return "private";
     return "package-private";
 }
-function buildMatch(member) {
+function buildMatch(member, kind) {
     return {
         name: member.name,
         descriptor: member.jvmDescriptor,
-        accessFlags: decodeAccessFlags(member.accessFlags),
+        accessFlags: decodeAccessFlags(member.accessFlags, kind),
         javaSignature: member.javaSignature,
         ...(member.sourceLine ? { sourceLine: member.sourceLine } : {})
     };
@@ -267,7 +267,7 @@ export class VerifyMixinTargetService {
         if (member.descriptor) {
             const descriptorHits = exactNameHits.filter((m) => m.jvmDescriptor === member.descriptor);
             if (descriptorHits.length > 0) {
-                matches = descriptorHits.map(buildMatch);
+                matches = descriptorHits.map((m) => buildMatch(m, member.kind));
             }
             else {
                 matches = [];
@@ -279,7 +279,7 @@ export class VerifyMixinTargetService {
             }
         }
         else {
-            matches = exactNameHits.map(buildMatch);
+            matches = exactNameHits.map((m) => buildMatch(m, member.kind));
         }
         if (matches.length === 0 && candidates.length === 0) {
             const suggestions = suggestSimilar(memberName, allMemberNames);