@adhisang/minecraft-modding-mcp 3.1.0 → 3.1.1

package/dist/source-service.js

@@ -159,6 +159,7 @@ function clampLimit(limit, fallback, max) {
 }
 const MAX_REGEX_QUERY_LENGTH = 200;
 const MAX_REGEX_RESULT_LIMIT = 100;
+const TRACE_LIFECYCLE_MAX_CONCURRENCY = 3;
 function normalizePathStyle(path) {
     return path.replaceAll("\\", "/");
 }
@@ -214,6 +215,18 @@ function normalizeOptionalProjectPath(projectPath) {
     const normalized = normalizePathForHost(trimmed, undefined, "projectPath");
     return isAbsolute(normalized) ? normalized : resolvePath(process.cwd(), normalized);
 }
+function looksLikeClassSegment(name) {
+    const trimmed = name.trim();
+    return /^[A-Z_$]/.test(trimmed);
+}
+function looksLikeJvmMethodDescriptor(descriptor) {
+    const trimmed = descriptor?.trim();
+    if (!trimmed || !trimmed.startsWith("(")) {
+        return false;
+    }
+    const closing = trimmed.indexOf(")");
+    return closing > 0 && closing < trimmed.length - 1;
+}
 function resolveGradleUserHomePath() {
     const configured = process.env.GRADLE_USER_HOME?.trim();
     if (!configured) {
@@ -278,16 +291,19 @@ function scopeToJarType(scope) {
 }
 function parseQualifiedMethodSymbol(symbol) {
     const trimmed = symbol.trim();
-    const separator = trimmed.lastIndexOf(".");
-    if (separator <= 0 || separator >= trimmed.length - 1) {
+    const descriptorStart = trimmed.indexOf("(");
+    const qualifiedSymbol = descriptorStart >= 0 ? trimmed.slice(0, descriptorStart) : trimmed;
+    const inlineDescriptor = descriptorStart >= 0 ? trimmed.slice(descriptorStart).trim() : undefined;
+    const separator = qualifiedSymbol.lastIndexOf(".");
+    if (separator <= 0 || separator >= qualifiedSymbol.length - 1) {
         throw createError({
             code: ERROR_CODES.INVALID_INPUT,
             message: `symbol must be in the form "fully.qualified.Class.method".`,
             details: { symbol }
         });
     }
-    const className = trimmed.slice(0, separator);
-    const methodName = trimmed.slice(separator + 1);
+    const className = qualifiedSymbol.slice(0, separator);
+    const methodName = qualifiedSymbol.slice(separator + 1);
     if (!className ||
         !methodName ||
         className.includes("/") ||
@@ -299,7 +315,11 @@ function parseQualifiedMethodSymbol(symbol) {
             details: { symbol }
         });
     }
-    return { className, methodName };
+    return {
+        className,
+        methodName,
+        ...(inlineDescriptor ? { inlineDescriptor } : {})
+    };
 }
 function normalizeOptionalString(value) {
     if (value == null) {
@@ -308,6 +328,27 @@ function normalizeOptionalString(value) {
     const trimmed = value.trim();
     return trimmed ? trimmed : undefined;
 }
+async function mapWithConcurrencyLimit(items, limit, mapper) {
+    if (items.length === 0) {
+        return [];
+    }
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workerCount = Math.max(1, Math.min(Math.trunc(limit), items.length));
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        while (true) {
+            // Safe in Node's single-threaded event loop because no await occurs between
+            // reading and incrementing nextIndex inside this synchronous dispatch section.
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            if (currentIndex >= items.length) {
+                return;
+            }
+            results[currentIndex] = await mapper(items[currentIndex], currentIndex);
+        }
+    }));
+    return results;
+}
 function normalizeStrictPositiveInt(value, field) {
     if (value == null) {
         return undefined;
@@ -1644,8 +1685,9 @@ export class SourceService {
     }
     async traceSymbolLifecycle(input) {
         const mapping = normalizeMapping(input.mapping);
-        const { className: userClassName, methodName: userMethodName } = parseQualifiedMethodSymbol(input.symbol);
-        const descriptor = normalizeOptionalString(input.descriptor);
+        const { className: userClassName, methodName: userMethodName, inlineDescriptor } = parseQualifiedMethodSymbol(input.symbol);
+        const descriptor = normalizeOptionalString(input.descriptor)
+            ?? (looksLikeJvmMethodDescriptor(inlineDescriptor) ? normalizeOptionalString(inlineDescriptor) : undefined);
         const includeTimeline = input.includeTimeline ?? false;
         const includeSnapshots = input.includeSnapshots ?? false;
         const maxVersions = clampLimit(input.maxVersions, 120, 400);
@@ -1701,60 +1743,75 @@ export class SourceService {
             selectedVersions = selectedVersions.slice(selectedVersions.length - maxVersions);
             warnings.push(`Version scan truncated to ${maxVersions} entries. Effective fromVersion is now "${selectedVersions[0]}".`);
         }
-        const resolvedSymbolsByVersion = new Map();
-        const scanned = [];
-        for (const version of selectedVersions) {
+        const referenceVersion = selectedVersions[selectedVersions.length - 1];
+        await this.rejectLifecycleClassLikeInput({
+            symbol: input.symbol,
+            className: userClassName,
+            methodName: userMethodName,
+            mapping,
+            version: referenceVersion,
+            sourcePriority: input.sourcePriority
+        });
+        const scannedResults = await mapWithConcurrencyLimit(selectedVersions, TRACE_LIFECYCLE_MAX_CONCURRENCY, async (version) => {
+            const versionWarnings = [];
             try {
-                let resolvedSymbols = resolvedSymbolsByVersion.get(version);
-                if (!resolvedSymbols) {
-                    const [obfuscatedClassName, obfuscatedMethod] = await Promise.all([
-                        this.resolveToObfuscatedClassName(userClassName, version, mapping, input.sourcePriority, warnings),
-                        this.resolveToObfuscatedMemberName(userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, warnings)
-                    ]);
-                    resolvedSymbols = {
-                        className: obfuscatedClassName,
-                        methodName: obfuscatedMethod.name,
-                        methodDescriptor: obfuscatedMethod.descriptor
-                    };
-                    resolvedSymbolsByVersion.set(version, resolvedSymbols);
-                }
-                const resolvedJar = await this.versionService.resolveVersionJar(version);
+                const [obfuscatedClassName, obfuscatedMethod, resolvedJar] = await Promise.all([
+                    this.resolveToObfuscatedClassName(userClassName, version, mapping, input.sourcePriority, versionWarnings),
+                    this.resolveToObfuscatedMemberName(userMethodName, userClassName, descriptor, "method", version, mapping, input.sourcePriority, versionWarnings),
+                    this.versionService.resolveVersionJar(version)
+                ]);
                 const signature = await this.explorerService.getSignature({
-                    fqn: resolvedSymbols.className,
+                    fqn: obfuscatedClassName,
                     jarPath: resolvedJar.jarPath,
                     access: "all",
                     includeSynthetic: true
                 });
-                const sameNameMethods = signature.methods.filter((method) => method.name === resolvedSymbols.methodName);
-                const matchesDescriptor = (resolvedSymbols.methodDescriptor ?? descriptor)
-                    ? sameNameMethods.some((method) => method.jvmDescriptor === (resolvedSymbols.methodDescriptor ?? descriptor))
+                const sameNameMethods = signature.methods.filter((method) => method.name === obfuscatedMethod.name);
+                const effectiveDescriptor = obfuscatedMethod.descriptor ?? descriptor;
+                const matchesDescriptor = effectiveDescriptor
+                    ? sameNameMethods.some((method) => method.jvmDescriptor === effectiveDescriptor)
                     : sameNameMethods.length > 0;
                 const reason = !matchesDescriptor && descriptor && sameNameMethods.length > 0 ? "descriptor-mismatch" : undefined;
-                scanned.push({
-                    version,
-                    exists: matchesDescriptor,
-                    reason,
-                    determinate: true
-                });
+                return {
+                    entry: {
+                        version,
+                        exists: matchesDescriptor,
+                        reason,
+                        determinate: true
+                    },
+                    warnings: versionWarnings
+                };
             }
             catch (caughtError) {
                 if (isAppError(caughtError) && caughtError.code === ERROR_CODES.CLASS_NOT_FOUND) {
-                    scanned.push({
+                    return {
+                        entry: {
+                            version,
+                            exists: false,
+                            reason: "class-not-found",
+                            determinate: true
+                        },
+                        warnings: versionWarnings
+                    };
+                }
+                versionWarnings.push(`Failed to evaluate ${version}: ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
+                return {
+                    entry: {
                         version,
                         exists: false,
-                        reason: "class-not-found",
-                        determinate: true
-                    });
-                    continue;
-                }
-                scanned.push({
-                    version,
-                    exists: false,
-                    reason: "unresolved",
-                    determinate: false
-                });
-                warnings.push(`Failed to evaluate ${version}: ${caughtError instanceof Error ? caughtError.message : String(caughtError)}`);
+                        reason: "unresolved",
+                        determinate: false
+                    },
+                    warnings: versionWarnings
+                };
+            }
+            finally {
+                this.releaseLifecycleMappingGraph(version, input.sourcePriority);
             }
+        });
+        const scanned = scannedResults.map((result) => result.entry);
+        for (const result of scannedResults) {
+            warnings.push(...result.warnings);
         }
         const determinate = scanned.filter((entry) => entry.determinate);
         const present = determinate.filter((entry) => entry.exists);
@@ -2695,17 +2752,18 @@ export class SourceService {
                     path: this.resolveMixinInputPath(path, "path")
                 },
                 sourcePath: path
-            })), input);
+            })), input, []);
         }
         const resolvedInput = mode === "project"
             ? this.createProjectValidateMixinConfigInput(input)
             : input;
-        const configSources = await this.resolveMixinConfigSources(resolvedInput);
+        const { sources: configSources, warnings: configWarnings } = await this.resolveMixinConfigSources(resolvedInput);
         if (configSources.length === 0) {
-            throw createError({
-                code: ERROR_CODES.INVALID_INPUT,
-                message: "Mixin config(s) contain no mixin class entries."
-            });
+            const emptyOutput = this.buildValidateMixinOutput(mode, []);
+            return this.applyValidateMixinOutputCompaction({
+                ...emptyOutput,
+                warnings: [...new Set([...emptyOutput.warnings, ...configWarnings])]
+            }, input);
         }
         return this.validateMixinMany(mode, configSources.map((entry) => ({
             source: {
@@ -2715,7 +2773,7 @@ export class SourceService {
                 configPath: entry.configPath
             },
             sourcePath: entry.sourcePath
-        })), resolvedInput);
+        })), resolvedInput, configWarnings);
     }
     createProjectValidateMixinConfigInput(input) {
         if (input.input.mode !== "project") {
@@ -3245,9 +3303,13 @@ export class SourceService {
     }
     async resolveMixinConfigSources(input) {
         if (input.input.mode !== "config") {
-            return [];
+            return {
+                sources: [],
+                warnings: []
+            };
         }
         const results = [];
+        const warnings = [];
         for (const rawConfigPath of input.input.configPaths) {
             const resolvedConfigPath = this.resolveMixinInputPath(rawConfigPath, "configPath");
             let configJson;
@@ -3268,6 +3330,7 @@ export class SourceService {
                 ...(configJson.server ?? [])
             ];
             if (classNames.length === 0) {
+                warnings.push(`Mixin config "${resolvedConfigPath}" contains no mixin class entries.`);
                 continue;
             }
             const projectBase = input.projectPath
@@ -3302,9 +3365,12 @@ export class SourceService {
                 });
             }
         }
-        return results;
+        return {
+            sources: results,
+            warnings
+        };
     }
-    async validateMixinMany(mode, entries, input) {
+    async validateMixinMany(mode, entries, input, additionalWarnings) {
         const results = [];
         const batchWarningMode = input.warningMode ?? "aggregated";
         const { input: _discardedInput, ...sharedInput } = input;
@@ -3331,7 +3397,13 @@ export class SourceService {
                 });
             }
         }
-        return this.applyValidateMixinOutputCompaction(this.buildValidateMixinOutput(mode, results), input);
+        const output = this.buildValidateMixinOutput(mode, results);
+        return this.applyValidateMixinOutputCompaction({
+            ...output,
+            warnings: additionalWarnings.length === 0
+                ? output.warnings
+                : [...new Set([...output.warnings, ...additionalWarnings])]
+        }, input);
     }
     applyValidateMixinOutputCompaction(output, input) {
         let nextOutput = output;
@@ -4045,6 +4117,38 @@ export class SourceService {
             details
         });
     }
+    rejectLifecycleClassLikeInput(input) {
+        if (!looksLikeClassSegment(input.methodName)) {
+            return;
+        }
+        const classLikeSymbol = `${input.className}.${input.methodName}`;
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `symbol must be in the form "fully.qualified.Class.method".`,
+            details: {
+                symbol: input.symbol,
+                classLikeSymbol,
+                nextAction: "Pass lifecycle input as Class.method and use the separate descriptor field for exact overload matching.",
+                suggestedCall: input.version
+                    ? {
+                        tool: "check-symbol-exists",
+                        params: {
+                            version: input.version,
+                            kind: "class",
+                            name: classLikeSymbol,
+                            sourceMapping: input.mapping
+                        }
+                    }
+                    : undefined
+            }
+        });
+    }
+    releaseLifecycleMappingGraph(version, sourcePriority) {
+        if ("releaseGraphCacheEntry" in this.mappingService &&
+            typeof this.mappingService.releaseGraphCacheEntry === "function") {
+            this.mappingService.releaseGraphCacheEntry(version, sourcePriority);
+        }
+    }
     async resolveToObfuscatedClassName(className, version, mapping, sourcePriority, warnings) {
         return this.resolveClassNameForLookup({
             className,

package/dist/tool-contract-manifest.js

@@ -11,128 +11,126 @@ export const TOOL_SURFACE_SECTION_IDS = [
 const SECTION_ROWS = {
     "v3-entry-tools": {
         en: [
-            "| `inspect-minecraft` | Start from a version, artifact, class, file, search query, or workspace and route to the most relevant Minecraft inspection flow | `task?`, `subject?`, `detail?`, `include?`, `limit?`, `cursor?`, `includeSnapshots?` | `result.summary`, `versions?`, `subject`, `artifact?`, `class?`, `source?`, `members?`, `search?`, `file?`, `files?` |",
-            "| `analyze-symbol` | One entry point for symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol analysis, and API overview | `task`, `subject`, `version?`, `sourceMapping?`, `targetMapping?`, `projectPath?`, `classNameMapping?`, `signatureMode?`, `nameMode?`, `includeKinds?`, `maxRows?`, `maxCandidates?`, `detail?`, `include?` | `result.summary`, `match?`, `candidates?`, `ambiguity?`, `matrix?`, `workspace?` |",
-            "| `compare-minecraft` | Compare version pairs, class signatures, registries, or produce a migration-oriented overview | `task?`, `subject`, `detail?`, `include?`, `subject.kind=\"class\".sourcePriority?`, `maxClassResults?`, `maxEntriesPerRegistry?`, `includeFullDiff?`, `limit?` | `result.summary`, `comparison`, `classes?`, `classDiff?`, `registry?`, `migration?` |",
-            "| `analyze-mod` | Metadata-first entry point for mod summary, decompile/search flows, class source, and safe remap previews/applies | `task`, `subject`, `query?`, `searchType?`, `targetMapping?`, `outputJar?`, `executionMode?`, `includeFiles?`, `maxFiles?`, `maxLines?`, `maxChars?`, `limit?`, `detail?`, `include?` | `result.summary`, `metadata?`, `decompile?`, `hits?`, `source?`, `operation?` |",
-            "| `validate-project` | Project-level validation entry for workspace summaries plus direct Mixin and Access Widener validation | `task`, `subject`, `version?`, `mapping?`, `sourcePriority?`, `scope?`, `preferProjectVersion?`, `preferProjectMapping?`, `sourceRoots?`, `configPaths?`, `minSeverity?`, `hideUncertain?`, `explain?`, `warningMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `includeIssues?`, `detail?`, `include?` | `result.summary`, `project`, `workspace?`, `issues?` |",
-            "| `manage-cache` | User-facing cache summary, listing, verification, previewed deletion/pruning/rebuild, and explicit apply operations | `action`, `cacheKinds?`, `selector?`, `executionMode?`, `detail?`, `include?`, `limit?`, `cursor?` | `result.summary`, `stats?`, `cacheEntries?`, `operation?`, `meta.pagination.nextCursor?` |"
+            "| `inspect-minecraft` | Inspect versions, artifacts, classes, files, source text, and workspace-aware lookup flows |",
+            "| `analyze-symbol` | Handle symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol resolution, and API overviews |",
+            "| `compare-minecraft` | Compare version pairs, class diffs, registry diffs, and migration-oriented summaries |",
+            "| `analyze-mod` | Summarize mod metadata, decompile and search mod code, inspect class source, and preview or apply remaps |",
+            "| `validate-project` | Summarize workspaces and run direct Mixin or Access Widener validation |",
+            "| `manage-cache` | List, verify, and preview or apply cache cleanup and rebuild operations |"
         ],
         ja: [
-            "| `inspect-minecraft` | バージョン、アーティファクト、クラス、ファイル、検索クエリ、ワークスペースから開始し、最適な Minecraft 調査フローへ振り分ける | `task?`, `subject?`, `detail?`, `include?`, `limit?`, `cursor?`, `includeSnapshots?` | `result.summary`, `versions?`, `subject`, `artifact?`, `class?`, `source?`, `members?`, `search?`, `file?`, `files?` |",
-            "| `analyze-symbol` | シンボル存在確認、名前空間マッピング、ライフサイクル追跡、ワークスペースシンボル解析、API 概要の単一エントリーポイント | `task`, `subject`, `version?`, `sourceMapping?`, `targetMapping?`, `projectPath?`, `classNameMapping?`, `signatureMode?`, `nameMode?`, `includeKinds?`, `maxRows?`, `maxCandidates?`, `detail?`, `include?` | `result.summary`, `match?`, `candidates?`, `ambiguity?`, `matrix?`, `workspace?` |",
-            "| `compare-minecraft` | バージョンペア比較、クラスシグネチャ比較、レジストリ比較、移行向け概要を提供 | `task?`, `subject`, `detail?`, `include?`, `subject.kind=\"class\".sourcePriority?`, `maxClassResults?`, `maxEntriesPerRegistry?`, `includeFullDiff?`, `limit?` | `result.summary`, `comparison`, `classes?`, `classDiff?`, `registry?`, `migration?` |",
-            "| `analyze-mod` | Mod 要約、デコンパイル / 検索フロー、クラスソース、安全なリマップ preview/apply のためのメタデータ優先エントリーポイント | `task`, `subject`, `query?`, `searchType?`, `targetMapping?`, `outputJar?`, `executionMode?`, `includeFiles?`, `maxFiles?`, `maxLines?`, `maxChars?`, `limit?`, `detail?`, `include?` | `result.summary`, `metadata?`, `decompile?`, `hits?`, `source?`, `operation?` |",
-            "| `validate-project` | ワークスペース要約と、Mixin / Access Widener の直接検証をまとめたプロジェクト単位の検証エントリー | `task`, `subject`, `version?`, `mapping?`, `sourcePriority?`, `scope?`, `preferProjectVersion?`, `preferProjectMapping?`, `sourceRoots?`, `configPaths?`, `minSeverity?`, `hideUncertain?`, `explain?`, `warningMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `includeIssues?`, `detail?`, `include?` | `result.summary`, `project`, `workspace?`, `issues?` |",
-            "| `manage-cache` | ユーザー向けのキャッシュ要約、一覧、検証、preview 付き削除 / prune / rebuild、明示的な apply 操作 | `action`, `cacheKinds?`, `selector?`, `executionMode?`, `detail?`, `include?`, `limit?`, `cursor?` | `result.summary`, `stats?`, `cacheEntries?`, `operation?`, `meta.pagination.nextCursor?` |"
+            "| `inspect-minecraft` | バージョン、アーティファクト、クラス、ファイル、ソース本文、ワークスペース文脈の調査フローをまとめて扱う |",
+            "| `analyze-symbol` | シンボル存在確認、名前空間変換、ライフサイクル追跡、ワークスペースシンボル解決、API 概要をまとめて扱う |",
+            "| `compare-minecraft` | バージョン差分、クラス差分、レジストリ差分、移行向け概要を比較する |",
+            "| `analyze-mod` | Mod メタデータの要約、Mod コードのデコンパイル / 検索、クラスソース確認、リマップのプレビュー / 実行を扱う |",
+            "| `validate-project` | ワークスペース要約と、Mixin / Access Widener の直接検証を行う |",
+            "| `manage-cache` | キャッシュの一覧、検証、クリーンアップ / 再構築のプレビュー / 実行を行う |"
         ]
     },
     "source-exploration": {
         en: [
-            "| `list-versions` | List available Minecraft versions from Mojang manifest + local cache | `includeSnapshots?`, `limit?` | `result.latest`, `result.releases[]`, `meta.warnings[]` |",
-            "| `resolve-artifact` | Resolve source artifact from `version` / `jar` / `coordinate` | `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `artifactId`, `origin`, `mappingApplied`, `qualityFlags[]`, `artifactContents`, `adjacentSourceCandidates?`, `sampleEntries?`, `warnings[]` |",
-            "| `find-class` | Resolve simple or fully-qualified class names inside an artifact | `className`, `artifactId`, `limit?` | `matches[]`, `total`, `warnings[]` |",
-            "| `get-class-source` | Get class source by artifact target or resolve target on demand (`mode=metadata` by default) | `className`, `target`, `mode?`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?`, `startLine?`, `endLine?`, `maxLines?`, `maxChars?`, `outputFile?` | `mode`, `sourceText`, `returnedRange`, `truncated`, `charsTruncated?`, `outputFile?`, `artifactId`, `returnedNamespace`, `artifactContents`, mapping/provenance metadata |",
-            "| `get-class-members` | Get class fields/methods/constructors from bytecode | `className`, `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `access?`, `includeSynthetic?`, `includeInherited?`, `memberPattern?`, `maxMembers?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `returnedNamespace`, `artifactContents`, `warnings[]` |",
-            "| `search-class-source` | Search indexed class source for symbols/text/path | `artifactId`, `query`, `intent?`, `match?`, `packagePrefix?`, `fileGlob?`, `symbolKind?`, `queryMode?`, `limit?`, `cursor?` | `hits[]`, `nextCursor?`, `mappingApplied`, `returnedNamespace`, `artifactContents` |",
-            "| `get-artifact-file` | Read full source file with byte guard | `artifactId`, `filePath`, `maxBytes?` | `content`, `contentBytes`, `truncated`, `mappingApplied`, `returnedNamespace`, `artifactContents` |",
-            "| `list-artifact-files` | List indexed source file paths with cursor pagination | `artifactId`, `prefix?`, `limit?`, `cursor?` | `items[]`, `nextCursor?`, `mappingApplied`, `artifactContents`, `warnings[]` |",
-            "| `index-artifact` | Rebuild index metadata for an existing artifact | `artifactId`, `force?` | `reindexed`, `reason`, `counts`, `indexedAt`, `durationMs` |"
+            "| `list-versions` | List available Minecraft versions from Mojang metadata and local cache |",
+            "| `resolve-artifact` | Resolve source artifacts from versions, JAR paths, or Maven coordinates |",
+            "| `find-class` | Find simple or fully-qualified class names inside an artifact |",
+            "| `get-class-source` | Read class source from an artifact or resolve the backing artifact on demand |",
+            "| `get-class-members` | List constructors, fields, and methods from bytecode |",
+            "| `search-class-source` | Search indexed class source by symbol, text, or path |",
+            "| `get-artifact-file` | Read a full source file with a byte limit |",
+            "| `list-artifact-files` | List indexed source file paths with cursor pagination |",
+            "| `index-artifact` | Rebuild indexed metadata for an existing artifact |"
         ],
         ja: [
-            "| `list-versions` | Mojang マニフェストとローカルキャッシュから利用可能な Minecraft バージョンを一覧表示 | `includeSnapshots?`, `limit?` | `result.latest`, `result.releases[]`, `meta.warnings[]` |",
-            "| `resolve-artifact` | `version` / `jar` / `coordinate` からソースアーティファクトを解決 | `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `artifactId`, `origin`, `mappingApplied`, `qualityFlags[]`, `artifactContents`, `adjacentSourceCandidates?`, `sampleEntries?`, `warnings[]` |",
-            "| `find-class` | アーティファクト内で簡易名または完全修飾クラス名を解決 | `className`, `artifactId`, `limit?` | `matches[]`, `total`, `warnings[]` |",
-            "| `get-class-source` | アーティファクトターゲットからクラスソースを取得し、必要に応じてその場で解決する（デフォルトは `mode=metadata`） | `className`, `target`, `mode?`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?`, `startLine?`, `endLine?`, `maxLines?`, `maxChars?`, `outputFile?` | `mode`, `sourceText`, `returnedRange`, `truncated`, `charsTruncated?`, `outputFile?`, `artifactId`, `returnedNamespace`, `artifactContents`, マッピング / 来歴メタデータ |",
-            "| `get-class-members` | バイトコードからクラスのフィールド / メソッド / コンストラクタを取得 | `className`, `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `access?`, `includeSynthetic?`, `includeInherited?`, `memberPattern?`, `maxMembers?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `returnedNamespace`, `artifactContents`, `warnings[]` |",
-            "| `search-class-source` | インデックス化されたクラスソースをシンボル / テキスト / パスで検索 | `artifactId`, `query`, `intent?`, `match?`, `packagePrefix?`, `fileGlob?`, `symbolKind?`, `queryMode?`, `limit?`, `cursor?` | `hits[]`, `nextCursor?`, `mappingApplied`, `returnedNamespace`, `artifactContents` |",
-            "| `get-artifact-file` | バイト上限付きでソースファイル全体を読み取る | `artifactId`, `filePath`, `maxBytes?` | `content`, `contentBytes`, `truncated`, `mappingApplied`, `returnedNamespace`, `artifactContents` |",
-            "| `list-artifact-files` | インデックス化されたソースファイルパスをカーソルページネーション付きで一覧表示 | `artifactId`, `prefix?`, `limit?`, `cursor?` | `items[]`, `nextCursor?`, `mappingApplied`, `artifactContents`, `warnings[]` |",
-            "| `index-artifact` | 既存アーティファクトのインデックスメタデータを再構築 | `artifactId`, `force?` | `reindexed`, `reason`, `counts`, `indexedAt`, `durationMs` |"
+            "| `list-versions` | Mojang メタデータとローカルキャッシュから利用可能な Minecraft バージョンを一覧表示する |",
+            "| `resolve-artifact` | バージョン、JAR パス、Maven 座標からソースアーティファクトを解決する |",
+            "| `find-class` | アーティファクト内で簡易名または完全修飾クラス名を探す |",
+            "| `get-class-source` | アーティファクトからクラスソースを読み取り、必要に応じて背後のアーティファクトを解決する |",
+            "| `get-class-members` | バイトコードからコンストラクタ、フィールド、メソッドを一覧化する |",
+            "| `search-class-source` | インデックス化されたクラスソースをシンボル、テキスト、パスで検索する |",
+            "| `get-artifact-file` | バイト上限付きでソースファイル全体を読み取る |",
+            "| `list-artifact-files` | インデックス化されたソースファイルパスをカーソルページネーション付きで一覧表示する |",
+            "| `index-artifact` | 既存アーティファクトのインデックスメタデータを再構築する |"
         ]
     },
     "version-comparison-symbol-tracking": {
         en: [
-            "| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions (`descriptor` omitted = name-only lookup) | `symbol`, `descriptor?`, `fromVersion?`, `toVersion?`, `mapping?`, `sourcePriority?`, `includeSnapshots?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |",
-            "| `diff-class-signatures` | Compare one class between two versions and return member deltas | `className`, `fromVersion`, `toVersion`, `mapping?`, `sourcePriority?`, `includeFullDiff?` | `classChange`, `constructors/methods/fields.{added,removed,modified}`, `modified`, `modified[].{key,changed,from?,to?}`, `summary`, `warnings[]` |",
-            "| `compare-versions` | Compare class/registry changes between two versions | `fromVersion`, `toVersion`, `category?`, `packageFilter?`, `maxClassResults?` | `classes`, `registry`, `summary`, `warnings[]` |"
+            "| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions |",
+            "| `diff-class-signatures` | Compare one class across two versions and return member deltas |",
+            "| `compare-versions` | Compare class and registry changes between two versions |"
         ],
         ja: [
-            "| `trace-symbol-lifecycle` | `Class.method` が Minecraft のどのバージョンで存在するかを追跡（`descriptor` 省略時は name-only lookup） | `symbol`, `descriptor?`, `fromVersion?`, `toVersion?`, `mapping?`, `sourcePriority?`, `includeSnapshots?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |",
-            "| `diff-class-signatures` | 2 つのバージョン間で 1 つのクラスを比較し、メンバー差分を返す | `className`, `fromVersion`, `toVersion`, `mapping?`, `sourcePriority?`, `includeFullDiff?` | `classChange`, `constructors/methods/fields.{added,removed,modified}`, `modified`, `modified[].{key,changed,from?,to?}`, `summary`, `warnings[]` |",
-            "| `compare-versions` | 2 つのバージョン間でクラス / レジストリ変更を比較 | `fromVersion`, `toVersion`, `category?`, `packageFilter?`, `maxClassResults?` | `classes`, `registry`, `summary`, `warnings[]` |"
+            "| `trace-symbol-lifecycle` | `Class.method` が Minecraft のどのバージョンで存在するかを追跡する |",
+            "| `diff-class-signatures` | 2 つのバージョン間で 1 つのクラスを比較し、メンバー差分を返す |",
+            "| `compare-versions` | 2 つのバージョン間でクラスとレジストリの変更を比較する |"
         ]
     },
     "mapping-symbols": {
         en: [
-            "| `find-mapping` | Find mapping candidates for class/field/method symbols between namespaces | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `disambiguation?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `ambiguityReasons?`, `provenance?`, `meta.warnings[]` |",
-            "| `resolve-method-mapping-exact` | Resolve one method mapping with strict owner+name+descriptor matching | `version`, `name`, `owner`, `descriptor`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `provenance?`, `meta.warnings[]` |",
-            "| `get-class-api-matrix` | Show one class API as a mapping matrix (`obfuscated/mojang/intermediary/yarn`) | `version`, `className`, `classNameMapping`, `includeKinds?`, `sourcePriority?`, `maxRows?` | `classIdentity`, `rows[]`, `rowCount`, `rowsTruncated?`, `ambiguousRowCount?`, `meta.warnings[]` |",
-            "| `resolve-workspace-symbol` | Resolve compile-visible symbol names for a Gradle workspace (`build.gradle/.kts`) | `projectPath`, `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `workspaceDetection`, `meta.warnings[]` |",
-            "| `check-symbol-exists` | Strict symbol presence check for class/field/method | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?`, `nameMode?`, `signatureMode?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `meta.warnings[]` |"
+            "| `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 |",
+            "| `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` | クラス / フィールド / メソッドのシンボルについて、名前空間間のマッピング候補を検索 | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `disambiguation?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `ambiguityReasons?`, `provenance?`, `meta.warnings[]` |",
-            "| `resolve-method-mapping-exact` | owner + name + descriptor の厳密一致で 1 つのメソッドマッピングを解決 | `version`, `name`, `owner`, `descriptor`, `sourceMapping`, `targetMapping`, `sourcePriority?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `provenance?`, `meta.warnings[]` |",
-            "| `get-class-api-matrix` | 1 つのクラス API をマッピングマトリクス（`obfuscated/mojang/intermediary/yarn`）として表示 | `version`, `className`, `classNameMapping`, `includeKinds?`, `sourcePriority?`, `maxRows?` | `classIdentity`, `rows[]`, `rowCount`, `rowsTruncated?`, `ambiguousRowCount?`, `meta.warnings[]` |",
-            "| `resolve-workspace-symbol` | Gradle ワークスペース（`build.gradle/.kts`）でコンパイル時に見えるシンボル名を解決 | `projectPath`, `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `workspaceDetection`, `meta.warnings[]` |",
-            "| `check-symbol-exists` | クラス / フィールド / メソッドの厳密な存在確認 | `version`, `kind`, `name`, `owner?`, `descriptor?`, `sourceMapping`, `sourcePriority?`, `nameMode?`, `signatureMode?`, `maxCandidates?` | `querySymbol`, `mappingContext`, `resolved`, `status`, `resolvedSymbol?`, `candidates[]`, `candidateCount`, `candidatesTruncated?`, `meta.warnings[]` |"
+            "| `find-mapping` | クラス、フィールド、メソッドのシンボルに対するマッピング候補を調べる |",
+            "| `resolve-method-mapping-exact` | owner、name、descriptor の厳密一致で 1 つのメソッドマッピングを解決する |",
+            "| `get-class-api-matrix` | 1 つのクラス API を `obfuscated`、`mojang`、`intermediary`、`yarn` で見比べる |",
+            "| `resolve-workspace-symbol` | Gradle ワークスペースからコンパイル時に見えるシンボル名を解決する |",
+            "| `check-symbol-exists` | 名前空間内でクラス、フィールド、メソッドが存在するかを確認する |"
         ]
     },
     "nbt-utilities": {
         en: [
-            "| `nbt-to-json` | Decode Java Edition NBT binary (`base64`) to typed JSON | `nbtBase64`, `compression?` (`none`, `gzip`, `auto`) | `typedJson`, `meta.compressionDetected`, `meta.inputBytes` |",
-            "| `nbt-apply-json-patch` | Apply RFC 6902 patch (`add/remove/replace/test`) to typed NBT JSON | `typedJson`, `patch` | `typedJson`, `meta.appliedOps`, `meta.testOps`, `meta.changed` |",
-            "| `json-to-nbt` | Encode typed JSON back to Java Edition NBT binary (`base64`) | `typedJson`, `compression?` (`none`, `gzip`) | `nbtBase64`, `meta.outputBytes`, `meta.compressionApplied` |"
+            "| `nbt-to-json` | Decode Java Edition NBT binary payloads into typed JSON |",
+            "| `nbt-apply-json-patch` | Apply RFC 6902 patches to typed NBT JSON |",
+            "| `json-to-nbt` | Encode typed JSON back to Java Edition NBT binary |"
         ],
         ja: [
-            "| `nbt-to-json` | Java Edition の NBT バイナリ（`base64`）を型付き JSON にデコード | `nbtBase64`, `compression?` (`none`, `gzip`, `auto`) | `typedJson`, `meta.compressionDetected`, `meta.inputBytes` |",
-            "| `nbt-apply-json-patch` | RFC 6902 パッチ（`add/remove/replace/test`）を型付き NBT JSON に適用 | `typedJson`, `patch` | `typedJson`, `meta.appliedOps`, `meta.testOps`, `meta.changed` |",
-            "| `json-to-nbt` | 型付き JSON を Java Edition の NBT バイナリ（`base64`）へ再エンコード | `typedJson`, `compression?` (`none`, `gzip`) | `nbtBase64`, `meta.outputBytes`, `meta.compressionApplied` |"
+            "| `nbt-to-json` | Java Edition の NBT バイナリを型付き JSON にデコードする |",
+            "| `nbt-apply-json-patch` | 型付き NBT JSON に RFC 6902 パッチを適用する |",
+            "| `json-to-nbt` | 型付き JSON を Java Edition の NBT バイナリへ再エンコードする |"
         ]
     },
     "mod-analysis": {
         en: [
-            "| `analyze-mod-jar` | Extract mod metadata/dependencies/entrypoints from mod JAR | `jarPath`, `includeClasses?` | `modId`, `loader`, `jarKind`, `dependencies`, `entrypoints`, `mixinConfigs`, class stats |",
-            "| `decompile-mod-jar` | Decompile mod JAR and optionally return one class source | `jarPath`, `className?`, `includeFiles?`, `maxFiles?` | `outputDir`, `fileCount`, `files?`, `returnedFileCount?`, `filesTruncated?`, `filesOmitted?`, `source?`, `warnings[]` |",
-            "| `get-mod-class-source` | Read one class source from decompiled mod cache | `jarPath`, `className`, `maxLines?`, `maxChars?`, `outputFile?` | `className`, `content`, `totalLines`, `truncated?`, `charsTruncated?`, `outputFilePath?`, `warnings[]` |",
-            "| `search-mod-source` | Search decompiled mod source by class/method/field/content | `jarPath`, `query`, `searchType?`, `limit?` | `hits[]`, `totalHits`, `truncated`, `warnings[]` |",
-            "| `remap-mod-jar` | Remap a Fabric/Quilt mod JAR to yarn/mojang names; Mojang-mapped inputs are copied for `targetMapping=\"mojang\"` | `inputJar`, `targetMapping`, `mcVersion?`, `outputJar?` | `outputJar`, `mcVersion`, `fromMapping`, `targetMapping`, `resolvedTargetNamespace`, `warnings[]` |"
+            "| `analyze-mod-jar` | Extract mod metadata, dependencies, entrypoints, and mixin config info from a JAR |",
+            "| `decompile-mod-jar` | Decompile a mod JAR and optionally return one class source |",
+            "| `get-mod-class-source` | Read one class source from the decompiled mod cache |",
+            "| `search-mod-source` | Search decompiled mod source by class, method, field, or content |",
+            "| `remap-mod-jar` | Remap a Fabric or Quilt mod JAR to `yarn` or `mojang` names |"
         ],
         ja: [
-            "| `analyze-mod-jar` | Mod JAR から Mod メタデータ / 依存関係 / エントリポイントを抽出 | `jarPath`, `includeClasses?` | `modId`, `loader`, `jarKind`, `dependencies`, `entrypoints`, `mixinConfigs`, class stats |",
-            "| `decompile-mod-jar` | Mod JAR をデコンパイルし、必要に応じて 1 つのクラスソースを返す | `jarPath`, `className?`, `includeFiles?`, `maxFiles?` | `outputDir`, `fileCount`, `files?`, `returnedFileCount?`, `filesTruncated?`, `filesOmitted?`, `source?`, `warnings[]` |",
-            "| `get-mod-class-source` | デコンパイル済み Mod キャッシュから 1 つのクラスソースを読み取る | `jarPath`, `className`, `maxLines?`, `maxChars?`, `outputFile?` | `className`, `content`, `totalLines`, `truncated?`, `charsTruncated?`, `outputFilePath?`, `warnings[]` |",
-            "| `search-mod-source` | デコンパイル済み Mod ソースを class / method / field / content で検索 | `jarPath`, `query`, `searchType?`, `limit?` | `hits[]`, `totalHits`, `truncated`, `warnings[]` |",
-            "| `remap-mod-jar` | Fabric / Quilt Mod JAR を yarn / mojang 名へリマップする。`targetMapping=\"mojang\"` で Mojang マップ済み入力はコピー扱い | `inputJar`, `targetMapping`, `mcVersion?`, `outputJar?` | `outputJar`, `mcVersion`, `fromMapping`, `targetMapping`, `resolvedTargetNamespace`, `warnings[]` |"
+            "| `analyze-mod-jar` | JAR から Mod メタデータ、依存関係、エントリポイント、Mixin 設定情報を抽出する |",
+            "| `decompile-mod-jar` | Mod JAR をデコンパイルし、必要に応じて 1 つのクラスソースを返す |",
+            "| `get-mod-class-source` | デコンパイル済み Mod キャッシュから 1 つのクラスソースを読み取る |",
+            "| `search-mod-source` | デコンパイル済み Mod ソースを class、method、field、content で検索する |",
+            "| `remap-mod-jar` | Fabric または Quilt の Mod JAR を `yarn` または `mojang` 名へリマップする |"
         ]
     },
     "validation": {
         en: [
-            "| `validate-mixin` | Parse/validate Mixin source against target Minecraft version | `input`, `sourceRoots?`, `version`, `mapping?`, `sourcePriority?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `minSeverity?`, `hideUncertain?`, `warningMode?`, `preferProjectMapping?`, `reportMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `explain?`, `includeIssues?` | `mode`, `results[].validationStatus`, `summary.partial`, `issueSummary?`, `provenance?`, `incompleteReasons?`, `toolHealth?`, `confidenceScore?`, `confidenceBreakdown?` |",
-            "| `validate-access-widener` | Parse/validate Access Widener content against target version | `content`, `version`, `mapping?`, `sourcePriority?` | `valid`, `issues[]`, `warnings[]`, `summary` |"
+            "| `validate-mixin` | Validate Mixin source against a target Minecraft version |",
+            "| `validate-access-widener` | Validate Access Widener content against a target Minecraft version |"
         ],
         ja: [
-            "| `validate-mixin` | 対象 Minecraft バージョンに対して Mixin ソースを解析 / 検証 | `input`, `sourceRoots?`, `version`, `mapping?`, `sourcePriority?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `minSeverity?`, `hideUncertain?`, `warningMode?`, `preferProjectMapping?`, `reportMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `explain?`, `includeIssues?` | `mode`, `results[].validationStatus`, `summary.partial`, `issueSummary?`, `provenance?`, `incompleteReasons?`, `toolHealth?`, `confidenceScore?`, `confidenceBreakdown?` |",
-            "| `validate-access-widener` | 対象バージョンに対して Access Widener の内容を解析 / 検証 | `content`, `version`, `mapping?`, `sourcePriority?` | `valid`, `issues[]`, `warnings[]`, `summary` |"
+            "| `validate-mixin` | 対象 Minecraft バージョンに対して Mixin ソースを検証する |",
+            "| `validate-access-widener` | 対象 Minecraft バージョンに対して Access Widener の内容を検証する |"
         ]
     },
     "registry-diagnostics": {
         en: [
-            "| `get-registry-data` | Get generated registry snapshots (blocks/items/entities etc.) | `version`, `registry?`, `includeData?`, `maxEntriesPerRegistry?` | `registries`, `data?`, `entryCount`, `returnedEntryCount?`, `registryEntryCounts?`, `dataTruncated?`, `warnings[]` |",
-            "| `get-runtime-metrics` | Inspect runtime counters and latency snapshots | none | `result.*` runtime metrics, `meta` envelope |"
+            "| `get-registry-data` | Read generated registry snapshots and optionally include entry data |",
+            "| `get-runtime-metrics` | Inspect runtime metrics and latency snapshots |"
         ],
         ja: [
-            "| `get-registry-data` | 生成済みレジストリスナップショット（ブロック / アイテム / エンティティなど）を取得 | `version`, `registry?`, `includeData?`, `maxEntriesPerRegistry?` | `registries`, `data?`, `entryCount`, `returnedEntryCount?`, `registryEntryCounts?`, `dataTruncated?`, `warnings[]` |",
-            "| `get-runtime-metrics` | ランタイムカウンターとレイテンシスナップショットを確認 | none | `result.*` runtime metrics, `meta` envelope |"
+            "| `get-registry-data` | 生成済みレジストリスナップショットを読み取り、必要に応じてエントリデータも含める |",
+            "| `get-runtime-metrics` | ランタイムメトリクスとレイテンシスナップショットを確認する |"
         ]
     }
 };
 export function renderToolSurfaceSection(locale, sectionId) {
-    const header = locale === "en"
-        ? "| Tool | Purpose | Key Inputs | Key Outputs |"
-        : "| ツール | 役割 | 主な入力 | 主な出力 |";
-    const divider = "| --- | --- | --- | --- |";
+    const header = locale === "en" ? "| Tool | Purpose |" : "| ツール | 役割 |";
+    const divider = "| --- | --- |";
     const rows = SECTION_ROWS[sectionId][locale];
     return [header, divider, ...rows].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "MCP server with utilities for Minecraft modding workflows",
   "type": "module",
   "main": "dist/index.js",