@adhisang/minecraft-modding-mcp 3.0.0 → 3.1.0

package/dist/observability.d.ts

@@ -3,12 +3,19 @@ export interface MetricTimingSnapshot {
     totalMs: number;
     avgMs: number;
     lastMs: number;
+    p95Ms: number;
+    p99Ms: number;
 }
 export interface CacheArtifactByteAccountingRow {
     artifact_id: string;
     content_bytes: number;
     updated_at: string;
 }
+type CacheArtifactByteAccountingRefRow = {
+    artifactId: string;
+    totalContentBytes: number;
+    updatedAt: string;
+};
 export interface RuntimeMetricSnapshot {
     resolve_duration_ms: MetricTimingSnapshot;
     search_duration_ms: MetricTimingSnapshot;
@@ -18,6 +25,10 @@ export interface RuntimeMetricSnapshot {
     search_intent_symbol_duration_ms: MetricTimingSnapshot;
     search_intent_text_duration_ms: MetricTimingSnapshot;
     search_intent_path_duration_ms: MetricTimingSnapshot;
+    search_query_mode_auto_count: number;
+    search_query_mode_token_count: number;
+    search_query_mode_literal_count: number;
+    search_literal_explicit_count: number;
     search_regex_fallback_count: number;
     search_token_bytes_returned: number;
     onehop_expand_count: number;
@@ -43,6 +54,10 @@ export declare class RuntimeMetrics {
     private cacheHits;
     private cacheMisses;
     private repoFailoverCount;
+    private searchQueryModeAutoCount;
+    private searchQueryModeTokenCount;
+    private searchQueryModeLiteralCount;
+    private searchLiteralExplicitCount;
     private searchRegexFallbackCount;
     private searchTokenBytesReturned;
     private oneHopExpandCount;
@@ -58,12 +73,13 @@ export declare class RuntimeMetrics {
     private cacheEvictions;
     private cacheEntries;
     private cacheTotalContentBytes;
-    private cacheArtifactBytesLru;
+    private cacheArtifactBytesLruRef;
     constructor();
     recordDuration(name: DurationMetricName, durationMs: number): void;
     recordArtifactCacheHit(): void;
     recordArtifactCacheMiss(): void;
     recordRepoFailover(): void;
+    recordSearchQueryMode(mode: "auto" | "token" | "literal"): void;
     recordSearchIntentDuration(intent: "symbol" | "text" | "path", durationMs: number): void;
     recordSearchRegexFallback(): void;
     recordSearchTokenBytesReturned(tokenBytes: number): void;
@@ -80,7 +96,7 @@ export declare class RuntimeMetrics {
     recordCacheEviction(count?: number): void;
     setCacheEntries(entries: number): void;
     setCacheTotalContentBytes(totalBytes: number): void;
-    setCacheArtifactByteAccounting(entries: CacheArtifactByteAccountingRow[]): void;
+    setCacheArtifactByteAccountingRef(entries: ReadonlyArray<CacheArtifactByteAccountingRefRow>): void;
     snapshot(): RuntimeMetricSnapshot;
     private toSnapshot;
     private resolveCacheHitRate;

package/dist/observability.js

@@ -1,8 +1,21 @@
+const MAX_TIMING_SAMPLES = 512;
+function percentile(samples, p) {
+    if (samples.length === 0) {
+        return 0;
+    }
+    const sorted = [...samples].sort((left, right) => left - right);
+    const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[index] ?? 0;
+}
 export class RuntimeMetrics {
     timings = new Map();
     cacheHits = 0;
     cacheMisses = 0;
     repoFailoverCount = 0;
+    searchQueryModeAutoCount = 0;
+    searchQueryModeTokenCount = 0;
+    searchQueryModeLiteralCount = 0;
+    searchLiteralExplicitCount = 0;
     searchRegexFallbackCount = 0;
     searchTokenBytesReturned = 0;
     oneHopExpandCount = 0;
@@ -18,7 +31,7 @@ export class RuntimeMetrics {
     cacheEvictions = 0;
     cacheEntries = 0;
     cacheTotalContentBytes = 0;
-    cacheArtifactBytesLru = [];
+    cacheArtifactBytesLruRef = [];
     constructor() {
         const names = [
             "resolve_duration_ms",
@@ -31,7 +44,7 @@ export class RuntimeMetrics {
             "search_intent_path_duration_ms"
         ];
         for (const name of names) {
-            this.timings.set(name, { count: 0, totalMs: 0, lastMs: 0 });
+            this.timings.set(name, { count: 0, totalMs: 0, lastMs: 0, samples: [] });
         }
     }
     recordDuration(name, durationMs) {
@@ -43,6 +56,10 @@ export class RuntimeMetrics {
         timing.count += 1;
         timing.totalMs += normalizedDuration;
         timing.lastMs = normalizedDuration;
+        timing.samples.push(normalizedDuration);
+        if (timing.samples.length > MAX_TIMING_SAMPLES) {
+            timing.samples.shift();
+        }
     }
     recordArtifactCacheHit() {
         this.cacheHits += 1;
@@ -53,6 +70,20 @@ export class RuntimeMetrics {
     recordRepoFailover() {
         this.repoFailoverCount += 1;
     }
+    recordSearchQueryMode(mode) {
+        switch (mode) {
+            case "auto":
+                this.searchQueryModeAutoCount += 1;
+                break;
+            case "token":
+                this.searchQueryModeTokenCount += 1;
+                break;
+            case "literal":
+                this.searchQueryModeLiteralCount += 1;
+                this.searchLiteralExplicitCount += 1;
+                break;
+        }
+    }
     recordSearchIntentDuration(intent, durationMs) {
         const metricName = intent === "symbol"
             ? "search_intent_symbol_duration_ms"
@@ -106,12 +137,8 @@ export class RuntimeMetrics {
     setCacheTotalContentBytes(totalBytes) {
         this.cacheTotalContentBytes = Math.max(0, Math.trunc(totalBytes));
     }
-    setCacheArtifactByteAccounting(entries) {
-        this.cacheArtifactBytesLru = entries.map((entry) => ({
-            artifact_id: entry.artifact_id,
-            content_bytes: Math.max(0, Math.trunc(entry.content_bytes)),
-            updated_at: entry.updated_at
-        }));
+    setCacheArtifactByteAccountingRef(entries) {
+        this.cacheArtifactBytesLruRef = entries;
     }
     snapshot() {
         return {
@@ -123,6 +150,10 @@ export class RuntimeMetrics {
             search_intent_symbol_duration_ms: this.toSnapshot("search_intent_symbol_duration_ms"),
             search_intent_text_duration_ms: this.toSnapshot("search_intent_text_duration_ms"),
             search_intent_path_duration_ms: this.toSnapshot("search_intent_path_duration_ms"),
+            search_query_mode_auto_count: this.searchQueryModeAutoCount,
+            search_query_mode_token_count: this.searchQueryModeTokenCount,
+            search_query_mode_literal_count: this.searchQueryModeLiteralCount,
+            search_literal_explicit_count: this.searchLiteralExplicitCount,
             search_regex_fallback_count: this.searchRegexFallbackCount,
             search_token_bytes_returned: this.searchTokenBytesReturned,
             onehop_expand_count: this.oneHopExpandCount,
@@ -138,7 +169,11 @@ export class RuntimeMetrics {
             cache_evictions: this.cacheEvictions,
             cache_entries: this.cacheEntries,
             cache_total_content_bytes: this.cacheTotalContentBytes,
-            cache_artifact_bytes_lru: this.cacheArtifactBytesLru,
+            cache_artifact_bytes_lru: this.cacheArtifactBytesLruRef.map((entry) => ({
+                artifact_id: entry.artifactId,
+                content_bytes: Math.max(0, Math.trunc(entry.totalContentBytes)),
+                updated_at: entry.updatedAt
+            })),
             cache_hit_rate: this.resolveCacheHitRate(),
             repo_failover_count: this.repoFailoverCount
         };
@@ -151,7 +186,9 @@ export class RuntimeMetrics {
             count,
             totalMs,
             avgMs: count > 0 ? totalMs / count : 0,
-            lastMs: timing?.lastMs ?? 0
+            lastMs: timing?.lastMs ?? 0,
+            p95Ms: percentile(timing?.samples ?? [], 95),
+            p99Ms: percentile(timing?.samples ?? [], 99)
         };
     }
     resolveCacheHitRate() {

package/dist/source-service.d.ts

@@ -488,7 +488,6 @@ export declare class SourceService {
     private searchTextIntent;
     private searchPathIntent;
     private findSymbolHits;
-    private loadScopedFilePaths;
     private indexedCandidateLimit;
     private indexedCandidateLimitForMatch;
     private extractClassMetadata;

package/dist/source-service.js

@@ -1208,6 +1208,7 @@ export class SourceService {
             const limit = clampLimit(input.limit, 20, searchLimitCap);
             const regexPattern = match === "regex" ? compileRegex(query) : undefined;
             const queryMode = input.queryMode ?? "auto";
+            this.metrics.recordSearchQueryMode(queryMode);
             const cursorContext = buildSearchCursorContext({
                 artifactId: artifact.artifactId,
                 query,
@@ -1227,7 +1228,6 @@ export class SourceService {
             const recordHit = (hit) => {
                 accumulator.add(hit);
             };
-            const hasSeparators = /[._$]/.test(query);
             const tokenOnlyTextIntent = intent === "text" && queryMode === "token";
             if (intent === "symbol") {
                 this.searchSymbolIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
@@ -1256,10 +1256,6 @@ export class SourceService {
                     }
                     else {
                         this.searchTextIntentIndexed(artifact.artifactId, query, match, scope, recordHit);
-                        // F-03: queryMode=auto fallback — when indexed returns 0 hits and query has separators, retry with literal scan
-                        if (queryMode === "auto" && hasSeparators && accumulator.currentCount() === 0) {
-                            this.searchTextIntent(artifact.artifactId, query, match, scope, regexPattern, recordHit);
-                        }
                     }
                     this.metrics.recordSearchIndexedHit();
                 }
@@ -3617,6 +3613,7 @@ export class SourceService {
         const candidateLimit = this.indexedCandidateLimitForMatch(match);
         const indexed = this.filesRepo.searchFileCandidates(artifactId, {
             query,
+            match,
             limit: candidateLimit,
             mode: "text"
         });
@@ -3701,13 +3698,20 @@ export class SourceService {
         }
     }
     searchTextIntent(artifactId, query, match, scope, regexPattern, onHit) {
-        const filePaths = this.loadScopedFilePaths(artifactId, scope);
         const pageSize = Math.max(1, this.config.searchScanPageSize ?? 250);
-        for (const chunk of chunkArray(filePaths, pageSize)) {
-            const rows = this.filesRepo.getFileContentsByPaths(artifactId, chunk);
+        const glob = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
+        let cursor = undefined;
+        while (true) {
+            const page = this.filesRepo.listFileRows(artifactId, { limit: pageSize, cursor });
             this.metrics.recordSearchDbRoundtrip();
-            this.metrics.recordSearchRowsScanned(rows.length);
-            for (const row of rows) {
+            this.metrics.recordSearchRowsScanned(page.items.length);
+            for (const row of page.items) {
+                if (!checkPackagePrefix(row.filePath, scope?.packagePrefix)) {
+                    continue;
+                }
+                if (glob && !glob.test(row.filePath)) {
+                    continue;
+                }
                 const contentIndex = match === "regex"
                     ? matchRegexIndex(row.content, regexPattern)
                     : findContentMatchIndex(row.content, query, match);
@@ -3721,29 +3725,44 @@ export class SourceService {
                     reasonCodes: ["content_match", `text_${match}`]
                 });
             }
+            if (!page.nextCursor) {
+                break;
+            }
+            cursor = page.nextCursor;
         }
     }
     searchPathIntent(artifactId, query, match, scope, regexPattern, onHit) {
-        const filePaths = this.loadScopedFilePaths(artifactId, scope);
-        const matching = filePaths.flatMap((filePath) => {
-            const pathIndex = match === "regex"
-                ? matchRegexIndex(filePath, regexPattern)
-                : findMatchIndex(filePath, query, match);
-            if (pathIndex < 0) {
-                return [];
-            }
-            return [{ filePath, pathIndex }];
-        });
         const pageSize = Math.max(1, this.config.searchScanPageSize ?? 250);
-        for (const chunk of chunkArray(matching, pageSize)) {
-            for (const candidate of chunk) {
+        const glob = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
+        let cursor = undefined;
+        while (true) {
+            const page = this.filesRepo.listFiles(artifactId, { limit: pageSize, cursor });
+            this.metrics.recordSearchDbRoundtrip();
+            this.metrics.recordSearchRowsScanned(page.items.length);
+            for (const filePath of page.items) {
+                if (!checkPackagePrefix(filePath, scope?.packagePrefix)) {
+                    continue;
+                }
+                if (glob && !glob.test(filePath)) {
+                    continue;
+                }
+                const pathIndex = match === "regex"
+                    ? matchRegexIndex(filePath, regexPattern)
+                    : findMatchIndex(filePath, query, match);
+                if (pathIndex < 0) {
+                    continue;
+                }
                 onHit({
-                    filePath: candidate.filePath,
-                    score: scorePathMatch(match, candidate.pathIndex),
+                    filePath,
+                    score: scorePathMatch(match, pathIndex),
                     matchedIn: "path",
                     reasonCodes: ["path_match", `path_${match}`]
                 });
             }
+            if (!page.nextCursor) {
+                break;
+            }
+            cursor = page.nextCursor;
         }
     }
     findSymbolHits(artifactId, query, match, scope, regexPattern) {
@@ -3806,31 +3825,6 @@ export class SourceService {
         }
         return result;
     }
-    loadScopedFilePaths(artifactId, scope) {
-        const glob = scope?.fileGlob ? buildGlobRegex(normalizePathStyle(scope.fileGlob)) : undefined;
-        const result = [];
-        let cursor = undefined;
-        const pageSize = Math.max(1, this.config.searchScanPageSize ?? 250);
-        while (true) {
-            const page = this.filesRepo.listFiles(artifactId, { limit: pageSize, cursor });
-            this.metrics.recordSearchDbRoundtrip();
-            this.metrics.recordSearchRowsScanned(page.items.length);
-            for (const filePath of page.items) {
-                if (!checkPackagePrefix(filePath, scope?.packagePrefix)) {
-                    continue;
-                }
-                if (glob && !glob.test(filePath)) {
-                    continue;
-                }
-                result.push(filePath);
-            }
-            if (!page.nextCursor) {
-                break;
-            }
-            cursor = page.nextCursor;
-        }
-        return result;
-    }
     indexedCandidateLimit() {
         return Math.min(Math.max(this.config.maxSearchHits * 5, 500), 5000);
     }
@@ -4543,11 +4537,7 @@ export class SourceService {
     publishCacheMetrics() {
         this.metrics.setCacheEntries(this.cacheMetricsState.entries);
         this.metrics.setCacheTotalContentBytes(this.cacheMetricsState.totalContentBytes);
-        this.metrics.setCacheArtifactByteAccounting(this.cacheMetricsState.lru.map((row) => ({
-            artifact_id: row.artifactId,
-            content_bytes: row.totalContentBytes,
-            updated_at: row.updatedAt
-        })));
+        this.metrics.setCacheArtifactByteAccountingRef(this.cacheMetricsState.lru);
     }
 }
 //# sourceMappingURL=source-service.js.map

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

@@ -15,6 +15,7 @@ export interface ListFilesOptions {
 export interface SearchFilesOptions {
     limit: number;
     query: string;
+    match?: "exact" | "prefix" | "contains" | "regex";
     cursor?: string;
     mode?: "mixed" | "text" | "path";
     fetchLimitOverride?: number;

package/dist/storage/files-repo.js

@@ -102,6 +102,25 @@ function buildPreview(content, query) {
     const suffix = end < content.length ? "..." : "";
     return `${prefix}${content.slice(start, end)}${suffix}`.replace(/\s+/g, " ").trim();
 }
+function tokenizeIndexedQuery(query) {
+    return query.match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+function buildIndexedMatchQuery(query, match) {
+    const tokens = tokenizeIndexedQuery(query.trim());
+    if (tokens.length === 0) {
+        return query.trim();
+    }
+    // Separator-heavy queries become an order-agnostic FTS5 MATCH expression.
+    // Whitespace is implicit AND, which keeps "dispatcher.register" on the indexed
+    // path while SourceService re-checks hydrated path/content matches before
+    // returning hits. Callers can still use literal mode for exact substring scans.
+    return tokens.map((token, index) => {
+        if (match === "prefix" && index === tokens.length - 1) {
+            return `${token}*`;
+        }
+        return token;
+    }).join(" ");
+}
 export class FilesRepo {
     db;
     deleteStmt;
@@ -257,6 +276,7 @@ export class FilesRepo {
         }
         const cursor = parseSearchCursor(options.cursor);
         const likeQuery = `%${normalized}%`;
+        const ftsQuery = buildIndexedMatchQuery(normalized, options.match);
         const mode = options.mode ?? "mixed";
         // Cursor-adaptive fetch limit: when no cursor, use a generous limit;
         // with cursor + SQL pushdown, we need far fewer rows.
@@ -294,9 +314,9 @@ export class FilesRepo {
         }));
         const mergedByPath = new Map(merged.map((hit) => [hit.filePath, hit]));
         let contentRows = [];
-        if (includeContent) {
+        if (includeContent && ftsQuery) {
             try {
-                contentRows = this.searchFtsStmt.all(artifactId, normalized, fetchLimit);
+                contentRows = this.searchFtsStmt.all(artifactId, ftsQuery, fetchLimit);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -305,7 +325,7 @@ export class FilesRepo {
                 }
                 log("warn", "storage.files.fts_syntax_error", {
                     artifactId,
-                    query: normalized,
+                    query: ftsQuery,
                     message
                 });
             }
@@ -379,14 +399,18 @@ export class FilesRepo {
         if (!normalized) {
             return 0;
         }
+        const ftsQuery = buildIndexedMatchQuery(normalized, "contains");
+        if (!ftsQuery) {
+            return 0;
+        }
         try {
-            const row = this.db.prepare(`SELECT COUNT(*) AS cnt FROM files_fts WHERE artifact_id = ? AND files_fts MATCH ?`).get(artifactId, normalized);
+            const row = this.db.prepare(`SELECT COUNT(*) AS cnt FROM files_fts WHERE artifact_id = ? AND files_fts MATCH ?`).get(artifactId, ftsQuery);
             return row?.cnt ?? 0;
         }
         catch {
             log("warn", "storage.files.count_text_candidates_failed", {
                 artifactId,
-                query: normalized
+                query: ftsQuery
             });
             return 0;
         }

package/dist/tool-contract-manifest.d.ts

@@ -0,0 +1,4 @@
+export declare const TOOL_SURFACE_SECTION_IDS: readonly ["v3-entry-tools", "source-exploration", "version-comparison-symbol-tracking", "mapping-symbols", "nbt-utilities", "mod-analysis", "validation", "registry-diagnostics"];
+export type ToolSurfaceSectionId = (typeof TOOL_SURFACE_SECTION_IDS)[number];
+export type ToolSurfaceLocale = "en" | "ja";
+export declare function renderToolSurfaceSection(locale: ToolSurfaceLocale, sectionId: ToolSurfaceSectionId): string;

package/dist/tool-contract-manifest.js

@@ -0,0 +1,139 @@
+export const TOOL_SURFACE_SECTION_IDS = [
+    "v3-entry-tools",
+    "source-exploration",
+    "version-comparison-symbol-tracking",
+    "mapping-symbols",
+    "nbt-utilities",
+    "mod-analysis",
+    "validation",
+    "registry-diagnostics"
+];
+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?` |"
+        ],
+        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?` |"
+        ]
+    },
+    "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` |"
+        ],
+        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` |"
+        ]
+    },
+    "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[]` |"
+        ],
+        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[]` |"
+        ]
+    },
+    "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[]` |"
+        ],
+        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[]` |"
+        ]
+    },
+    "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` |"
+        ],
+        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` |"
+        ]
+    },
+    "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[]` |"
+        ],
+        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[]` |"
+        ]
+    },
+    "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` |"
+        ],
+        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` |"
+        ]
+    },
+    "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 |"
+        ],
+        ja: [
+            "| `get-registry-data` | 生成済みレジストリスナップショット（ブロック / アイテム / エンティティなど）を取得 | `version`, `registry?`, `includeData?`, `maxEntriesPerRegistry?` | `registries`, `data?`, `entryCount`, `returnedEntryCount?`, `registryEntryCounts?`, `dataTruncated?`, `warnings[]` |",
+            "| `get-runtime-metrics` | ランタイムカウンターとレイテンシスナップショットを確認 | none | `result.*` runtime metrics, `meta` envelope |"
+        ]
+    }
+};
+export function renderToolSurfaceSection(locale, sectionId) {
+    const header = locale === "en"
+        ? "| Tool | Purpose | Key Inputs | Key Outputs |"
+        : "| ツール | 役割 | 主な入力 | 主な出力 |";
+    const divider = "| --- | --- | --- | --- |";
+    const rows = SECTION_ROWS[sectionId][locale];
+    return [header, divider, ...rows].join("\n");
+}
+//# sourceMappingURL=tool-contract-manifest.js.map

package/package.json

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