@adhisang/minecraft-modding-mcp 4.2.1 → 5.0.0

package/dist/source-jar-reader.js

@@ -3,6 +3,15 @@ import { createError, ERROR_CODES } from "./errors.js";
 import { log } from "./logger.js";
 import { isSecureJarEntryPath } from "./path-resolver.js";
 const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+// Test-only instrumentation: counts real jar opens at the single openZipFile
+// chokepoint so perf tests can assert N-opens-per-call collapses to 1.
+let zipOpenCount = 0;
+export function __getZipOpenCount() {
+    return zipOpenCount;
+}
+export function __resetZipOpenCount() {
+    zipOpenCount = 0;
+}
 function toErrorMessage(value) {
     if (value instanceof Error) {
         return value.message;
@@ -23,7 +32,7 @@ export function hasJavaSourceExtension(entryPath) {
     }
     return true;
 }
-function openZipFile(jarPath) {
+export function openZipFile(jarPath) {
     return new Promise((resolve, reject) => {
         yauzl.open(jarPath, {
             lazyEntries: true,
@@ -33,6 +42,7 @@ function openZipFile(jarPath) {
                 reject(new Error(`Failed to read jar "${jarPath}": ${toErrorMessage(error)}`));
                 return;
             }
+            zipOpenCount += 1;
             resolve(zipFile);
         });
     });
@@ -193,6 +203,66 @@ export async function readJarEntryAsBuffer(jarPath, entryPath) {
         }
     });
 }
+/**
+ * Opens a jar ONCE, drains its central directory into a name->entry index, and
+ * serves repeated entry reads via O(1) lookup + openReadStream. Use this when a
+ * single logical operation reads many entries from the same jar (e.g. walking a
+ * class hierarchy) instead of calling {@link readJarEntryAsBuffer} per entry,
+ * which re-opens and re-scans the jar each time. Callers MUST close() the reader
+ * (in a finally) to release the file descriptor. getEntryBuffer throws the same
+ * INVALID_INPUT (unsafe path) / SOURCE_NOT_FOUND (missing entry) errors as
+ * readJarEntryAsBuffer; duplicate entry names resolve to the first occurrence.
+ */
+export async function createJarEntryReader(jarPath) {
+    const zipFile = await openZipFile(jarPath);
+    let closed = false;
+    const index = new Map();
+    try {
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                break;
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (!index.has(entry.fileName)) {
+                index.set(entry.fileName, entry);
+            }
+        }
+    }
+    catch (error) {
+        zipFile.close();
+        throw error;
+    }
+    return {
+        async getEntryBuffer(entryPath) {
+            const normalizedTargetPath = entryPath.replaceAll("\\", "/");
+            if (!isSecureJarEntryPath(normalizedTargetPath)) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: `Entry path "${normalizedTargetPath}" is not allowed.`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            const entry = index.get(normalizedTargetPath);
+            if (!entry) {
+                throw createError({
+                    code: ERROR_CODES.SOURCE_NOT_FOUND,
+                    message: `Entry "${normalizedTargetPath}" was not found in "${jarPath}".`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            return readEntryStream(zipFile, entry, jarPath);
+        },
+        close() {
+            if (!closed) {
+                closed = true;
+                zipFile.close();
+            }
+        }
+    };
+}
 export async function collectMatchedJarEntriesAsUtf8(jarPath, predicate, options = {}) {
     return withZipFile(jarPath, async (zipFile) => {
         const entries = [];
@@ -226,6 +296,48 @@ export async function collectMatchedJarEntriesAsUtf8(jarPath, predicate, options
         }
     });
 }
+/**
+ * Raw-buffer counterpart of {@link collectMatchedJarEntriesAsUtf8}: opens the jar
+ * ONCE and returns the matched entries as raw Buffers (no UTF-8 decode), so binary
+ * inputs like `.class` bytes survive intact. Used to avoid re-opening the jar per
+ * sampled entry. Mirrors the sibling's maxBytes/maxEntries/continueOnError semantics
+ * and its finally-close, but takes an injectable open seam for open-count assertions.
+ */
+export async function collectMatchedJarEntriesAsBuffers(jarPath, predicate, options = {}, deps = {}) {
+    const open = deps.openZipFile ?? openZipFile;
+    const zipFile = await open(jarPath);
+    try {
+        const entries = [];
+        const maxEntries = options.maxEntries == null ? undefined : Math.max(1, Math.trunc(options.maxEntries));
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                return entries;
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (!predicate(entry.fileName)) {
+                continue;
+            }
+            try {
+                const contentBuffer = await readEntryStream(zipFile, entry, jarPath, options.maxBytes);
+                entries.push({ filePath: entry.fileName, content: contentBuffer });
+                if (maxEntries != null && entries.length >= maxEntries) {
+                    return entries;
+                }
+            }
+            catch (error) {
+                if (!options.continueOnError) {
+                    throw error;
+                }
+            }
+        }
+    }
+    finally {
+        zipFile.close();
+    }
+}
 export async function* iterateJavaEntriesAsUtf8(jarPath, maxBytes) {
     const zipFile = await openZipFile(jarPath);
     try {
@@ -285,7 +397,7 @@ function countMatches(input, pattern) {
     }
     return count;
 }
-export async function detectFabricLikeInputNamespace(inputJar) {
+export async function detectFabricLikeInputNamespace(inputJar, deps = {}) {
     const warnings = [];
     const classEntries = (await listJarEntries(inputJar))
         .filter((entry) => entry.endsWith(".class"))
@@ -297,16 +409,15 @@ export async function detectFabricLikeInputNamespace(inputJar) {
             warnings
         };
     }
+    // Read all sampled class entries in a SINGLE jar open instead of re-opening the
+    // jar once per entry. The sample set and latin1 decode are unchanged, so scores —
+    // and therefore the detected namespace — are identical.
+    const sampleSet = new Set(classEntries);
+    const matched = await collectMatchedJarEntriesAsBuffers(inputJar, (name) => sampleSet.has(name), { continueOnError: true }, deps);
     let mojangScore = 0;
     let intermediaryScore = 0;
-    for (const entry of classEntries) {
-        let text = "";
-        try {
-            text = (await readJarEntryAsBuffer(inputJar, entry)).toString("latin1");
-        }
-        catch {
-            continue;
-        }
+    for (const { content } of matched) {
+        const text = content.toString("latin1");
         mojangScore += countMatches(text, /net\/minecraft\/(?:advancements|client|commands|core|data|gametest|nbt|network|recipe|resources|server|sounds|stats|tags|util|world)\//g) * 3;
         intermediaryScore += countMatches(text, /net\/minecraft\/class_\d+/g) * 3;
         intermediaryScore += countMatches(text, /\b(?:method|field)_\d+\b/g);

package/dist/source-service.d.ts

@@ -11,6 +11,7 @@ import * as indexer from "./source/indexer.js";
 import * as workspaceTarget from "./source/workspace-target.js";
 import * as validateMixinModule from "./source/validate-mixin.js";
 import * as artifactResolver from "./source/artifact-resolver.js";
+import type { WireMembersBlock } from "./source/class-source/members-builder.js";
 import { type StageEmitter } from "./stage-emitter.js";
 import { WorkspaceMappingService, type WorkspaceCompileMappingOutput } from "./workspace-mapping-service.js";
 import { type WorkspaceContextCache } from "./workspace-context-cache.js";
@@ -30,7 +31,8 @@ export type ResolveArtifactInput = {
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
-    compact?: boolean;
+    /** When true, compute the optional `sampleEntries` listing (detail=full / include=samples). */
+    includeSampleEntries?: boolean;
 };
 export type ResolveArtifactOutput = {
     artifactId: string;
@@ -112,6 +114,8 @@ export type SearchClassSourceInput = {
 export type SearchClassSourceOutput = {
     hits: SearchSourceHit[];
     nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored (results restart from page one). */
+    cursorIgnored?: boolean;
     mappingApplied: SourceMapping;
     returnedNamespace: SourceMapping;
     artifactContents: ArtifactContentsSummary;
@@ -205,6 +209,10 @@ export type GetClassSourceOutput = {
     };
     truncated: boolean;
     charsTruncated?: boolean;
+    /** True when startLine begins past EOF; the returned range is empty (not clamped). */
+    outOfRange?: boolean;
+    /** First not-yet-returned line when truncated; pass back as startLine to continue. */
+    nextStartLine?: number;
     origin: ResolvedSourceArtifact["origin"];
     artifactId: string;
     requestedMapping: SourceMapping;
@@ -213,6 +221,11 @@ export type GetClassSourceOutput = {
     provenance: ArtifactProvenance;
     qualityFlags: string[];
     artifactContents: ArtifactContentsSummary;
+    /** Replayable get-class-source call that reads from nextStartLine (truncated, non-file output only). */
+    suggestedCall?: {
+        tool: string;
+        params: Record<string, unknown>;
+    };
     outputFile?: string;
     warnings: string[];
 };
@@ -245,11 +258,14 @@ export type GetClassMembersInput = {
     includeInherited?: boolean;
     memberPattern?: string;
     maxMembers?: number;
+    cursor?: string;
     projectPath?: string;
     gradleUserHome?: string;
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
+    /** When true, keep jvmDescriptor on FIELD members (always kept on methods/constructors). */
+    includeDescriptors?: boolean;
 };
 export type DecompiledMember = {
     name: string;
@@ -265,11 +281,7 @@ export type DecompiledFallback = {
 export type GetClassMembersStatus = "ok" | "members_unavailable" | "partial";
 export type GetClassMembersOutput = {
     className: string;
-    members: {
-        constructors: SignatureMember[];
-        fields: SignatureMember[];
-        methods: SignatureMember[];
-    };
+    members: WireMembersBlock;
     counts: {
         constructors: number;
         fields: number;
@@ -277,6 +289,10 @@ export type GetClassMembersOutput = {
         total: number;
     };
     truncated: boolean;
+    /** Continuation cursor when more members remain; pass back as cursor to fetch the next page. */
+    nextCursor?: string;
+    /** True when a provided cursor was malformed or belonged to a different query and was ignored. */
+    cursorIgnored?: boolean;
     context: ExplorerResponseContext;
     origin: ResolvedSourceArtifact["origin"];
     artifactId: string;
@@ -420,7 +436,12 @@ export type ValidateMixinInput = {
         path: string;
     };
     sourceRoots?: string[];
-    version: string;
+    /**
+     * Optional when input.mode='project', or preferProjectVersion=true with a
+     * projectPath set: the dispatcher detects the Minecraft version from
+     * gradle.properties before any version-dependent stage runs.
+     */
+    version?: string;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     scope?: ArtifactScope;

package/dist/storage/files-repo.d.ts

@@ -47,6 +47,7 @@ export declare class FilesRepo {
     private readonly listStmt;
     private readonly listRowsStmt;
     private readonly searchPathStmt;
+    private readonly searchContentLikePathsStmt;
     private readonly searchFtsStmt;
     private readonly getByPathsStmtCache;
     private readonly classLookupStmtCache;
@@ -58,6 +59,17 @@ export declare class FilesRepo {
     getFileContent(artifactId: string, filePath: string): FileRow | undefined;
     listFiles(artifactId: string, options: ListFilesOptions): PagedResult<string>;
     listFileRows(artifactId: string, options: ListFileRowsOptions): PagedResult<FileRow>;
+    /**
+     * Narrow the literal/contains text-scan candidate set without hydrating content:
+     * returns the file_paths whose content matches `content LIKE %needle%` (ASCII
+     * case-insensitive). The result is a SUPERSET of the JS contains/exact match set
+     * for an ASCII needle, so callers MUST still run the exact JS post-verify. Only
+     * file_path is selected — content stays in the DB until getFileContentsByPaths.
+     */
+    searchContentLikeCandidatePaths(artifactId: string, needle: string, limit: number): {
+        filePaths: string[];
+        scannedRows: number;
+    };
     getFileContentsByPaths(artifactId: string, filePaths: string[]): FileRow[];
     searchFileCandidates(artifactId: string, options: SearchFilesOptions): PagedResult<SearchFileCandidateResult> & {
         scannedRows: number;

package/dist/storage/files-repo.js

@@ -121,6 +121,10 @@ function buildIndexedMatchQuery(query, match) {
         return token;
     }).join(" ");
 }
+/** Escape LIKE wildcards so the needle is matched literally under ESCAPE '\'. */
+function escapeLikeNeedle(value) {
+    return value.replace(/[\\%_]/g, "\\$&");
+}
 export class FilesRepo {
     db;
     deleteStmt;
@@ -129,6 +133,7 @@ export class FilesRepo {
     listStmt;
     listRowsStmt;
     searchPathStmt;
+    searchContentLikePathsStmt;
     searchFtsStmt;
     getByPathsStmtCache = new Map();
     classLookupStmtCache = new Map();
@@ -167,6 +172,13 @@ export class FilesRepo {
       WHERE artifact_id = ? AND file_path LIKE ? ESCAPE '\\'
       ORDER BY file_path ASC
       LIMIT ?
+    `);
+        this.searchContentLikePathsStmt = this.db.prepare(`
+      SELECT file_path
+      FROM files
+      WHERE artifact_id = ? AND content LIKE ? ESCAPE '\\'
+      ORDER BY file_path ASC
+      LIMIT ?
     `);
         this.searchFtsStmt = this.db.prepare(`
       SELECT file_path, rank
@@ -239,6 +251,18 @@ export class FilesRepo {
             nextCursor: nextCursorFromRows(rows)
         };
     }
+    /**
+     * Narrow the literal/contains text-scan candidate set without hydrating content:
+     * returns the file_paths whose content matches `content LIKE %needle%` (ASCII
+     * case-insensitive). The result is a SUPERSET of the JS contains/exact match set
+     * for an ASCII needle, so callers MUST still run the exact JS post-verify. Only
+     * file_path is selected — content stays in the DB until getFileContentsByPaths.
+     */
+    searchContentLikeCandidatePaths(artifactId, needle, limit) {
+        const pattern = `%${escapeLikeNeedle(needle)}%`;
+        const rows = this.searchContentLikePathsStmt.all(artifactId, pattern, Math.max(1, limit));
+        return { filePaths: rows.map((row) => row.file_path), scannedRows: rows.length };
+    }
     getFileContentsByPaths(artifactId, filePaths) {
         if (filePaths.length === 0) {
             return [];

package/dist/storage/symbols-repo.d.ts

@@ -22,6 +22,12 @@ export interface FindScopedSymbolsOptions {
     query: string;
     match: ScopedSymbolMatch;
     symbolKind?: string;
+    /**
+     * Restrict results to these symbol kinds via a bound `symbol_kind IN (...)` clause.
+     * Combined with the singular `symbolKind` it ANDs (both apply). An empty array is
+     * ignored (degrades to no kind filter) to avoid emitting an invalid `IN ()`.
+     */
+    symbolKinds?: string[];
     packagePrefix?: string;
     filePathLike?: string;
     limit?: number;

package/dist/storage/symbols-repo.js

@@ -260,6 +260,12 @@ export class SymbolsRepo {
             where.push("symbol_kind = ?");
             params.push(options.symbolKind);
         }
+        const symbolKinds = options.symbolKinds;
+        if (symbolKinds && symbolKinds.length > 0) {
+            const placeholders = symbolKinds.map(() => "?").join(", ");
+            where.push(`symbol_kind IN (${placeholders})`);
+            params.push(...symbolKinds);
+        }
         if (options.packagePrefix?.trim()) {
             const normalizedPrefix = options.packagePrefix.replace(/\.+/g, "/").replace(/\/+$/, "");
             where.push("file_path LIKE ? ESCAPE '\\'");

package/dist/symbols/symbol-extractor.js

@@ -1,6 +1,26 @@
-const CLASS_DECLARATION = /^(?:\s*@[\w.]+\s+)*(?:\s*(?:public|private|protected|abstract|final|sealed|non-sealed|static)\s+)*\s*(class|interface|enum|record)\s+([A-Za-z_$][\w$]*)/;
-const METHOD_DECLARATION = /^(?:\s*@[\w.]+\s+)*[^{;]*?\b([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?:\{|;)/;
-const FIELD_DECLARATION = /^(?:\s*@[\w.]+\s+)*[^\s][\w<>\[\],.?]+\s+([A-Za-z_$][\w$]*)\s*(?:=|;|,)/;
+// A type token may carry spaced generics (Map<String, Integer>), arrays (int[][]),
+// wildcards (List<? extends Foo>), and FQNs (java.util.Map). It must not contain "=".
+const TYPE_TOKEN = "[\\w.$][\\w.$<>\\[\\],?\\s]*";
+const MODIFIER = "(?:public|private|protected|abstract|final|static|native|synchronized|default|strictfp|transient|volatile)";
+const MODIFIER_OR_ANNOTATION_RUN = `(?:(?:@[\\w.]+|${MODIFIER})\\s+)*`;
+const TYPE_PARAMS = "(?:<[^>]+>\\s*)?";
+const THROWS_CLAUSE = "(?:\\s+throws\\s+[\\w.$,\\s]+)?";
+const CLASS_DECLARATION = new RegExp(`^${MODIFIER_OR_ANNOTATION_RUN}(class|interface|enum|record)\\s+([A-Za-z_$][\\w$]*)`);
+// Method/constructor with a body: return type is optional (constructors have none); ends with "{".
+const METHOD_BLOCK_DECLARATION = new RegExp(`^${MODIFIER_OR_ANNOTATION_RUN}${TYPE_PARAMS}(?:${TYPE_TOKEN}\\s+)?([A-Za-z_$][\\w$]*)\\s*\\([^)]*\\)${THROWS_CLAUSE}\\s*\\{`);
+// Abstract/interface method declaration: a return type is REQUIRED; ends with ";".
+// Requiring the return type is what separates "void onTick();" from a bare call "doThing();".
+const METHOD_ABSTRACT_DECLARATION = new RegExp(`^${MODIFIER_OR_ANNOTATION_RUN}${TYPE_PARAMS}${TYPE_TOKEN}\\s+([A-Za-z_$][\\w$]*)\\s*\\([^)]*\\)${THROWS_CLAUSE}\\s*;`);
+const FIELD_DECLARATION = new RegExp(`^${MODIFIER_OR_ANNOTATION_RUN}${TYPE_TOKEN}\\s+([A-Za-z_$][\\w$]*)\\s*(?:=|;|,)`);
+// Lines that begin with one of these keywords are statements, not declarations. They are
+// skipped wholesale so that "return helper();" / "for (...)" / "new Foo() {" never produce
+// phantom members. "default"/"synchronized" are intentionally excluded (they double as
+// member modifiers); the method regexes reject their statement forms structurally.
+const STATEMENT_LINE_KEYWORDS = new Set([
+    "if", "for", "while", "switch", "catch", "return", "throw", "else", "do",
+    "case", "break", "continue", "assert", "super", "this", "try", "new", "yield"
+]);
+// Defence-in-depth: even if a keyword is captured as a member name, drop it.
 const NOISE_TOKENS = new Set(["if", "for", "while", "switch", "catch", "return", "new", "throw"]);
 function normalizeLine(line) {
     return line.replace(/\s+/g, " ").trim();
@@ -8,6 +28,10 @@ function normalizeLine(line) {
 function isNoiseToken(token) {
     return NOISE_TOKENS.has(token);
 }
+function isStatementLine(line) {
+    const firstWord = /^([A-Za-z_$][\w$]*)/.exec(line)?.[1];
+    return firstWord != null && STATEMENT_LINE_KEYWORDS.has(firstWord);
+}
 function lineIndexToLine(lineNo) {
     return lineNo + 1;
 }
@@ -17,8 +41,13 @@ export function extractSymbolsFromSource(filePath, content) {
     const qualifiedName = filePath.replace(/\.java$/, "").replaceAll("/", ".");
     for (let index = 0; index < lines.length; index += 1) {
         const rawLine = lines[index] ?? "";
-        const line = normalizeLine(rawLine);
-        if (!line) {
+        const normalized = normalizeLine(rawLine);
+        if (!normalized) {
+            continue;
+        }
+        // Drop a single leading "}"/"{" so "} public void foo() {" still parses.
+        const line = normalized.replace(/^[}{]\s*/, "");
+        if (!line || isStatementLine(line)) {
             continue;
         }
         const classMatch = line.match(CLASS_DECLARATION);
@@ -35,7 +64,7 @@ export function extractSymbolsFromSource(filePath, content) {
             }
             continue;
         }
-        const methodMatch = line.match(METHOD_DECLARATION);
+        const methodMatch = line.match(METHOD_BLOCK_DECLARATION) ?? line.match(METHOD_ABSTRACT_DECLARATION);
         if (methodMatch) {
             const symbolName = methodMatch[1];
             if (symbolName && !isNoiseToken(symbolName)) {

package/dist/text-truncate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Slice `text` to at most `maxChars` UTF-16 code units without splitting a
+ * surrogate pair. A naive `text.slice(0, maxChars)` can leave a lone high
+ * surrogate at the boundary (e.g. when an emoji straddles the cut), producing
+ * an invalid string; this drops that dangling half so callers never emit one.
+ */
+export declare function sliceToMaxCharsSafe(text: string, maxChars: number): string;

package/dist/text-truncate.js

@@ -0,0 +1,21 @@
+/**
+ * Slice `text` to at most `maxChars` UTF-16 code units without splitting a
+ * surrogate pair. A naive `text.slice(0, maxChars)` can leave a lone high
+ * surrogate at the boundary (e.g. when an emoji straddles the cut), producing
+ * an invalid string; this drops that dangling half so callers never emit one.
+ */
+export function sliceToMaxCharsSafe(text, maxChars) {
+    if (maxChars <= 0) {
+        return "";
+    }
+    if (text.length <= maxChars) {
+        return text;
+    }
+    let cut = text.slice(0, maxChars);
+    const lastUnit = cut.charCodeAt(cut.length - 1);
+    if (lastUnit >= 0xd800 && lastUnit <= 0xdbff) {
+        cut = cut.slice(0, -1);
+    }
+    return cut;
+}
+//# sourceMappingURL=text-truncate.js.map

package/dist/tiny-remapper-resolver.js

@@ -15,6 +15,16 @@ function tinyRemapperDownloadUrl(version) {
 export async function resolveTinyRemapperJar(cacheDir, overridePath, fetchFn) {
     // 1. Environment / config override
     if (overridePath) {
+        if (!existsSync(overridePath)) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `Configured tiny-remapper jar does not exist: ${overridePath}`,
+                details: {
+                    path: overridePath,
+                    nextAction: "Point tinyRemapperJarPath / MCP_TINY_REMAPPER_JAR at an existing fat jar, or unset it to download automatically."
+                }
+            });
+        }
         return overridePath;
     }
     const version = process.env.MCP_TINY_REMAPPER_VERSION ?? DEFAULT_VERSION;

package/dist/tool-contract-manifest.js

@@ -67,14 +67,14 @@ const SECTION_ROWS = {
     "mapping-symbols": {
         en: [
             "| `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 |"
         ],
         ja: [
             "| `find-mapping` | クラス、フィールド、メソッドのシンボルに対するマッピング候補を調べる |",
-            "| `resolve-method-mapping-exact` | owner、name、descriptor の厳密一致で 1 つのメソッドマッピングを解決する |",
+            "| `resolve-method-mapping-exact` | `find-mapping`（kind=method, signatureMode=exact）の厳密版ショートカット。owner+name+descriptor の三つ組が必須 |",
             "| `get-class-api-matrix` | 1 つのクラス API を `obfuscated`、`mojang`、`intermediary`、`yarn` で見比べる |",
             "| `resolve-workspace-symbol` | Gradle ワークスペースからコンパイル時に見えるシンボル名を解決する |",
             "| `check-symbol-exists` | 名前空間内でクラス、フィールド、メソッドが存在するかを確認する |"

package/dist/tool-execution-gate.js

@@ -3,6 +3,13 @@ const DEFAULT_OPTIONS = {
     maxConcurrent: 1,
     maxQueue: 2
 };
+// Heavy tools that have a batch equivalent able to collapse many same-kind
+// queries into a single gated call. Used to point overflow guidance at the
+// right batch-* tool instead of just telling the caller to retry serially.
+const BATCH_EQUIVALENTS = {
+    "find-mapping": "batch-mappings",
+    "resolve-method-mapping-exact": "batch-mappings"
+};
 export class ToolExecutionGate {
     maxConcurrent;
     maxQueue;
@@ -17,6 +24,10 @@ export class ToolExecutionGate {
             return this.execute({ tool, task: task });
         }
         if (this.queue.length >= this.maxQueue) {
+            const batchTool = BATCH_EQUIVALENTS[tool];
+            const nextAction = batchTool
+                ? `Retry after the current heavy analysis request completes. To run many ${tool} queries efficiently, collapse them into a single ${batchTool} call instead of issuing them in parallel.`
+                : "Retry after the current heavy analysis request completes. Avoid sending multiple heavy mapping/version analysis tools in parallel.";
             return Promise.reject(createError({
                 code: ERROR_CODES.LIMIT_EXCEEDED,
                 message: `Heavy tool queue is full; "${tool}" was not started.`,
@@ -26,7 +37,7 @@ export class ToolExecutionGate {
                     queuedCount: this.queue.length,
                     maxConcurrent: this.maxConcurrent,
                     maxQueue: this.maxQueue,
-                    nextAction: "Retry after the current heavy analysis request completes. Avoid sending multiple heavy mapping/version analysis tools in parallel."
+                    nextAction
                 }
             }));
         }

package/dist/tool-guidance.d.ts

@@ -1,4 +1,5 @@
 import { ZodError } from "zod";
+import type { WarningDetail } from "./warning-details.js";
 import { type ExampleCall, type ProblemDetails, type ProblemFieldError, type SuggestedCall } from "./error-mapping.js";
 import type { SourceTargetInput } from "./types.js";
 export type ToolMeta = {
@@ -6,6 +7,8 @@ export type ToolMeta = {
     tool: string;
     durationMs: number;
     warnings: string[];
+    /** Structured companion to `warnings`: one classified entry per warning string, referencing its text via `warnings[detail.index]`. */
+    warningDetails?: WarningDetail[];
     detailApplied?: "summary" | "standard" | "full";
     includeApplied?: string[];
     truncated?: Record<string, unknown>;
@@ -29,7 +32,7 @@ export declare const SUGGESTED_CALL_DEFAULTS: {
     readonly explain: false;
     readonly preferProjectMapping: false;
     readonly minSeverity: "all";
-    readonly reportMode: "full";
+    readonly reportMode: "summary-first";
     readonly treatInfoAsWarning: true;
     readonly includeIssues: true;
 };