@adhisang/minecraft-modding-mcp 4.2.0 → 5.0.0

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/tiny-remapper-service.js

@@ -1,10 +1,10 @@
 import { existsSync } from "node:fs";
 import { createError, ERROR_CODES } from "./errors.js";
-import { assertJavaAvailable, runJavaProcess } from "./java-process.js";
+import { javaRunner } from "./java-process.js";
 import { log } from "./logger.js";
 export async function remapJar(tinyRemapperJarPath, options) {
     const { inputJar, outputJar, mappingsFile, fromNamespace, toNamespace, threads = 4, rebuildSourceFilenames = false, timeoutMs = 600_000, maxMemoryMb = 4096 } = options;
-    await assertJavaAvailable();
+    await javaRunner.assertAvailable();
     log("info", "remap.start", {
         inputJar,
         outputJar,
@@ -21,7 +21,7 @@ export async function remapJar(tinyRemapperJarPath, options) {
         args.push("--rebuildSourceFilenames");
     }
     try {
-        const result = await runJavaProcess({
+        const result = await javaRunner.run({
             jarPath: tinyRemapperJarPath,
             args,
             timeoutMs,

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;
 };

package/dist/tool-guidance.js

@@ -1,7 +1,7 @@
 import { ZodError } from "zod";
 import { buildSuggestedCall } from "./build-suggested-call.js";
 import { ERROR_CODES, isAppError } from "./errors.js";
-import { statusForErrorCode } from "./error-mapping.js";
+import { extractAllowlistedContext, issueOriginForErrorCode, retryClassForErrorCode, statusForErrorCode } from "./error-mapping.js";
 export const SUGGESTED_CALL_DEFAULTS = {
     allowDecompile: true,
     preferProjectVersion: false,
@@ -14,7 +14,7 @@ export const SUGGESTED_CALL_DEFAULTS = {
     explain: false,
     preferProjectMapping: false,
     minSeverity: "all",
-    reportMode: "full",
+    reportMode: "summary-first",
     treatInfoAsWarning: true,
     includeIssues: true
 };
@@ -98,14 +98,19 @@ export function extractValidatedSuggestionAndExamples(details) {
                 typeof ex.reason !== "string") {
                 continue;
             }
+            // Re-validate through the example path, not the primary path: example
+            // calls are templates and MAY carry placeholder sentinels (e.g.
+            // "<version>"), which the primary gate intentionally rejects.
             const result = buildSuggestedCall({
                 tool: ex.tool,
-                params: ex.params
+                params: undefined,
+                examples: [{ params: ex.params, reason: ex.reason }]
             });
-            if (result.suggestedCall) {
+            const validatedExample = result.exampleCalls?.[0];
+            if (validatedExample) {
                 validated.push({
                     tool: ex.tool,
-                    params: result.suggestedCall.params,
+                    params: validatedExample.params,
                     reason: ex.reason
                 });
             }
@@ -414,12 +419,10 @@ export function buildSourceLookupSuggestedParams(tool, normalizedInput) {
     const targetValue = asNonEmptyString(record?.target);
     result.target = targetValue
         ? {
-            type: "resolve",
             kind: inferTargetKindFromString(targetValue),
             value: targetValue
         }
         : {
-            type: "resolve",
             kind: "version",
             value: "<minecraft-version>"
         };
@@ -607,7 +610,21 @@ export function buildValidateProjectSuggestedParams(normalizedInput) {
     return result;
 }
 function gatedGuidance(tool, hints, params) {
-    const validated = buildSuggestedCall({ tool, params });
+    // Pass the reconstructed params as both the primary and a fallback example.
+    // When they are fully executable they become `suggestedCall`; when they still
+    // carry `<…>` placeholders (e.g. a missing version) the gate drops the
+    // primary and surfaces the same shape as an `exampleCalls` template instead
+    // of emitting a non-callable suggestedCall.
+    const validated = buildSuggestedCall({
+        tool,
+        params,
+        examples: [
+            {
+                params,
+                reason: `Example ${tool} call shape — replace any <…> placeholder values before sending.`
+            }
+        ]
+    });
     return {
         hints,
         ...validated,
@@ -630,8 +647,8 @@ export function buildInvalidInputGuidance(tool, normalizedInput) {
     }
     if (tool === "get-class-source" || tool === "get-class-members") {
         return gatedGuidance(tool, [
-            `${tool}.target must be an object: {"type":"resolve","kind":"version|jar|coordinate","value":"..."} or {"type":"artifact","artifactId":"..."}.`,
-            "Bare string targets are not accepted; wrap the value under target.type/target.kind/target.value."
+            `${tool}.target must be an object: {"kind":"version|jar|coordinate","value":"..."} or {"kind":"artifact","artifactId":"..."} (same shape as resolve-artifact).`,
+            "Bare string targets are not accepted; wrap the value under target.kind/target.value."
         ], buildSourceLookupSuggestedParams(tool, normalizedInput));
     }
     if (tool === "validate-project") {
@@ -666,6 +683,8 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             status: 400,
             code: ERROR_CODES.INVALID_INPUT,
             instance: requestId,
+            retryClass: retryClassForErrorCode(ERROR_CODES.INVALID_INPUT),
+            issueOrigin: issueOriginForErrorCode(ERROR_CODES.INVALID_INPUT),
             fieldErrors: toFieldErrorsFromZod(caughtError),
             hints: hintsWithFallback,
             ...(guidance?.suggestedCall ? { suggestedCall: guidance.suggestedCall } : {}),
@@ -675,6 +694,7 @@ export function mapErrorToProblem(caughtError, requestId, context) {
     }
     if (isAppError(caughtError)) {
         const { suggestedCall, exampleCalls, primaryDropped } = extractValidatedSuggestionAndExamples(caughtError.details);
+        const sanitizedContext = extractAllowlistedContext(caughtError.details);
         let failedStage = extractFailedStageFromDetails(caughtError.details);
         if (!failedStage
             && context?.tool === "validate-mixin"
@@ -692,11 +712,14 @@ export function mapErrorToProblem(caughtError, requestId, context) {
             status: statusForErrorCode(caughtError.code),
             code: caughtError.code,
             instance: requestId,
+            retryClass: retryClassForErrorCode(caughtError.code),
+            issueOrigin: issueOriginForErrorCode(caughtError.code),
             fieldErrors: extractFieldErrorsFromDetails(caughtError.details),
             hints: hintsWithFallback,
             ...(suggestedCall ? { suggestedCall } : {}),
             ...(exampleCalls ? { exampleCalls } : {}),
-            ...(failedStage ? { failedStage } : {})
+            ...(failedStage ? { failedStage } : {}),
+            ...(sanitizedContext ? { context: sanitizedContext } : {})
         };
     }
     return {
@@ -705,7 +728,9 @@ export function mapErrorToProblem(caughtError, requestId, context) {
         detail: "Unexpected server error.",
         status: 500,
         code: ERROR_CODES.INTERNAL,
-        instance: requestId
+        instance: requestId,
+        retryClass: retryClassForErrorCode(ERROR_CODES.INTERNAL),
+        issueOrigin: issueOriginForErrorCode(ERROR_CODES.INTERNAL)
     };
 }
 /**