@adhisang/minecraft-modding-mcp 6.2.0 → 7.0.0-rc.0

package/dist/version-diff-service.d.ts

@@ -2,6 +2,17 @@ import { VersionService } from "./version-service.js";
 import { RegistryService } from "./registry-service.js";
 import type { Config } from "./types.js";
 export type CompareVersionsCategory = "classes" | "registry" | "all";
+/**
+ * Namespace the compared class names live in.
+ *
+ * A vanilla client jar for an obfuscated release lists `dlp.class`, not
+ * `net/minecraft/world/item/Item.class`, so a diff taken straight off the jar
+ * entries answers in obfuscated names. Every caller-facing name — the `added`
+ * and `removed` lists AND `packageFilter` — is expressed in mojang names when
+ * the official mappings for both versions can be loaded, and the namespace is
+ * always reported so a zero result is never ambiguous.
+ */
+export type ClassDiffNamespace = "mojang" | "obfuscated";
 export type CompareVersionsInput = {
     fromVersion: string;
     toVersion: string;
@@ -18,6 +29,15 @@ export type CompareVersionsOutput = {
         addedCount: number;
         removedCount: number;
         unchanged: number;
+        /** Namespace the class names above (and any packageFilter) are expressed in. */
+        namespace: ClassDiffNamespace;
+        /** Present only when the caller passed packageFilter; reports what it matched. */
+        packageFilter?: {
+            value: string;
+            namespace: ClassDiffNamespace;
+            matchedFrom: number;
+            matchedTo: number;
+        };
     };
     registry?: {
         added: Record<string, string[]>;
@@ -36,6 +56,19 @@ export declare class VersionDiffService {
     private readonly config;
     private readonly versionService;
     private readonly registryService;
+    private readonly mojangClassMaps;
     constructor(config: Config, versionService: VersionService, registryService: RegistryService);
+    /**
+     * obfuscated -> mojang class map for one version, or undefined when the
+     * official mappings cannot be obtained (offline, or a release that publishes
+     * none). Never throws: a missing map degrades the diff to obfuscated names
+     * with a warning rather than failing the comparison.
+     */
+    private loadMojangClassMap;
+    /**
+     * Lifts one version's jar class list into mojang names when possible.
+     * Returns the namespace the returned set is actually expressed in.
+     */
+    private toMojangNames;
     compareVersions(input: CompareVersionsInput): Promise<CompareVersionsOutput>;
 }

package/dist/version-diff-service.js

@@ -1,5 +1,7 @@
+import { readFile } from "node:fs/promises";
 import { createError, ERROR_CODES } from "./errors.js";
 import { log } from "./logger.js";
+import { resolveMojangTinyFile } from "./mojang-tiny-mapping-service.js";
 import { listJarEntries } from "./source-jar-reader.js";
 const DEFAULT_MAX_CLASS_RESULTS = 500;
 const MAX_CLASS_RESULTS_LIMIT = 5000;
@@ -25,6 +27,49 @@ function filterByPackage(classes, prefix) {
 function filterSetByPackage(classes, prefix) {
     return new Set(filterByPackage([...classes], prefix));
 }
+/**
+ * True when the jar's class names are obfuscated.
+ *
+ * Obfuscation collapses every Minecraft class into the DEFAULT package with a
+ * short generated name (`dlp`, `ije`), so a jar where a large share of the
+ * classes carry no package at all is obfuscated. Unobfuscated releases, jars
+ * remapped before listing, and ordinary library/mod jars all keep real package
+ * structure and need no mapping load.
+ */
+function looksObfuscated(classes) {
+    if (classes.size === 0) {
+        return false;
+    }
+    let defaultPackage = 0;
+    for (const fqn of classes) {
+        if (!fqn.includes(".")) {
+            defaultPackage += 1;
+        }
+    }
+    return defaultPackage > 0 && defaultPackage * 4 >= classes.size;
+}
+/** Parses the `c<TAB>obf<TAB>mojang` rows of a merged mojang tiny v2 file. */
+function parseTinyClassRows(content) {
+    const classMap = new Map();
+    for (const line of content.split("\n")) {
+        if (line.charCodeAt(0) !== 99 /* 'c' */ || line.charCodeAt(1) !== 9 /* TAB */) {
+            continue;
+        }
+        const parts = line.split("\t");
+        if (parts.length < 3) {
+            continue;
+        }
+        const obfuscated = parts[1];
+        const mojang = parts[2];
+        if (!obfuscated || !mojang) {
+            continue;
+        }
+        classMap.set(obfuscated.replaceAll("/", "."), mojang.replaceAll("/", "."));
+    }
+    return classMap;
+}
+/** Bounded per-process memo so a repeated comparison re-reads nothing. */
+const MOJANG_CLASS_MAP_CACHE_LIMIT = 4;
 function diffSets(from, to) {
     const added = [];
     const removed = [];
@@ -128,11 +173,76 @@ export class VersionDiffService {
     config;
     versionService;
     registryService;
+    mojangClassMaps = new Map();
     constructor(config, versionService, registryService) {
         this.config = config;
         this.versionService = versionService;
         this.registryService = registryService;
     }
+    /**
+     * obfuscated -> mojang class map for one version, or undefined when the
+     * official mappings cannot be obtained (offline, or a release that publishes
+     * none). Never throws: a missing map degrades the diff to obfuscated names
+     * with a warning rather than failing the comparison.
+     */
+    async loadMojangClassMap(version) {
+        const cached = this.mojangClassMaps.get(version);
+        if (cached) {
+            return cached;
+        }
+        try {
+            const { path } = await resolveMojangTinyFile(version, this.config, {
+                versionService: this.versionService
+            });
+            const classMap = parseTinyClassRows(await readFile(path, "utf8"));
+            if (classMap.size === 0) {
+                return undefined;
+            }
+            if (this.mojangClassMaps.size >= MOJANG_CLASS_MAP_CACHE_LIMIT) {
+                const oldest = this.mojangClassMaps.keys().next().value;
+                if (oldest !== undefined) {
+                    this.mojangClassMaps.delete(oldest);
+                }
+            }
+            this.mojangClassMaps.set(version, classMap);
+            return classMap;
+        }
+        catch (error) {
+            log("warn", "version-diff.mojang_class_map_unavailable", {
+                version,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return undefined;
+        }
+    }
+    /**
+     * Lifts one version's jar class list into mojang names when possible.
+     * Returns the namespace the returned set is actually expressed in.
+     */
+    async toMojangNames(version, classes) {
+        if (!looksObfuscated(classes)) {
+            return { classes, namespace: "mojang", unmapped: 0 };
+        }
+        const classMap = await this.loadMojangClassMap(version);
+        if (!classMap) {
+            return { classes, namespace: "obfuscated", unmapped: classes.size };
+        }
+        const mapped = new Set();
+        let unmapped = 0;
+        for (const fqn of classes) {
+            const mojang = classMap.get(fqn);
+            if (mojang) {
+                mapped.add(mojang);
+            }
+            else {
+                // Library classes shipped inside the jar (and anything the mappings do
+                // not cover) keep the name the jar carries; they are already readable.
+                mapped.add(fqn);
+                unmapped += 1;
+            }
+        }
+        return { classes: mapped, namespace: "mojang", unmapped };
+    }
     async compareVersions(input) {
         const fromVersion = input.fromVersion.trim();
         const toVersion = input.toVersion.trim();
@@ -168,14 +278,38 @@ export class VersionDiffService {
                     listJarEntries(fromJar.jarPath),
                     listJarEntries(toJar.jarPath)
                 ]);
-                const fromClasses = extractClassEntries(fromEntries);
-                const toClasses = extractClassEntries(toEntries);
+                // The class names must be lifted OUT of the jar's own namespace
+                // before anything is compared or filtered: a mojang packageFilter
+                // against obfuscated jar entries matched nothing and reported a
+                // silent all-zero diff that read as "no changes".
+                const [fromNames, toNames] = await Promise.all([
+                    this.toMojangNames(fromVersion, extractClassEntries(fromEntries)),
+                    this.toMojangNames(toVersion, extractClassEntries(toEntries))
+                ]);
+                const namespace = fromNames.namespace === "mojang" && toNames.namespace === "mojang"
+                    ? "mojang"
+                    : "obfuscated";
+                if (namespace === "obfuscated") {
+                    warnings.push(`Official Mojang mappings could not be loaded for ${fromNames.namespace === "obfuscated" ? fromVersion : toVersion}, so class names (and packageFilter) are compared in the OBFUSCATED namespace. Deobfuscated prefixes such as "net.minecraft.world.item" cannot match here.`);
+                }
+                const fromClasses = fromNames.classes;
+                const toClasses = toNames.classes;
                 const filteredFromClasses = input.packageFilter
                     ? filterSetByPackage(fromClasses, input.packageFilter)
                     : fromClasses;
                 const filteredToClasses = input.packageFilter
                     ? filterSetByPackage(toClasses, input.packageFilter)
                     : toClasses;
+                if (input.packageFilter && filteredFromClasses.size === 0 && filteredToClasses.size === 0) {
+                    // An empty diff and a non-matching filter look identical on the
+                    // wire, so the filter has to say which one happened.
+                    warnings.push(`packageFilter "${input.packageFilter}" matched no class in either ${fromVersion} or ${toVersion}; ` +
+                        `the reported zeros mean "filter matched nothing", not "nothing changed". ` +
+                        `Class names are compared in the ${namespace} namespace — ` +
+                        (namespace === "obfuscated"
+                            ? "an obfuscated jar has no package structure to filter on, so omit packageFilter."
+                            : "check the package prefix spelling, e.g. \"net.minecraft.world.item\"."));
+                }
                 const { added, removed, unchanged } = diffSets(filteredFromClasses, filteredToClasses);
                 const truncatedAdded = added.slice(0, maxClassResults);
                 const truncatedRemoved = removed.slice(0, maxClassResults);
@@ -190,7 +324,18 @@ export class VersionDiffService {
                     removed: truncatedRemoved,
                     addedCount: added.length,
                     removedCount: removed.length,
-                    unchanged
+                    unchanged,
+                    namespace,
+                    ...(input.packageFilter
+                        ? {
+                            packageFilter: {
+                                value: input.packageFilter,
+                                namespace,
+                                matchedFrom: filteredFromClasses.size,
+                                matchedTo: filteredToClasses.size
+                            }
+                        }
+                        : {})
                 };
             })());
         }

package/dist/version-service.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { buildSuggestedCall } from "./build-suggested-call.js";
-import { createError, ERROR_CODES } from "./errors.js";
+import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { computeFileSha1 } from "./hash.js";
 import { defaultDownloadPath, downloadToCache } from "./repo-downloader.js";
 const DEFAULT_VERSION_MANIFEST_URL = "https://piston-meta.mojang.com/mc/game/version_manifest_v2.json";
@@ -352,26 +352,48 @@ export class VersionService {
         return details;
     }
     async fetchJson(url) {
-        const response = await this.fetchFn(url);
-        if (!response.ok) {
+        const timeout = new AbortController();
+        const timer = setTimeout(() => timeout.abort(), this.config.fetchTimeoutMs);
+        try {
+            const response = await this.fetchFn(url, { signal: timeout.signal });
+            if (!response.ok) {
+                throw createError({
+                    code: ERROR_CODES.REPO_FETCH_FAILED,
+                    message: `Request failed for "${url}" with status ${response.status}.`,
+                    details: {
+                        url,
+                        statusCode: response.status
+                    }
+                });
+            }
+            try {
+                return await response.json();
+            }
+            catch {
+                throw createError({
+                    code: ERROR_CODES.REPO_FETCH_FAILED,
+                    message: `Response from "${url}" is not valid JSON.`,
+                    details: { url }
+                });
+            }
+        }
+        catch (error) {
+            // A typed status/JSON error is more precise than the timeout mapping even
+            // when the abort timer fired concurrently — never rewrite it.
+            if (isAppError(error) || !timeout.signal.aborted) {
+                throw error;
+            }
             throw createError({
                 code: ERROR_CODES.REPO_FETCH_FAILED,
-                message: `Request failed for "${url}" with status ${response.status}.`,
+                message: `Request timed out for "${url}" after ${this.config.fetchTimeoutMs}ms.`,
                 details: {
                     url,
-                    statusCode: response.status
+                    timeoutMs: this.config.fetchTimeoutMs
                 }
             });
         }
-        try {
-            return await response.json();
-        }
-        catch {
-            throw createError({
-                code: ERROR_CODES.REPO_FETCH_FAILED,
-                message: `Response from "${url}" is not valid JSON.`,
-                details: { url }
-            });
+        finally {
+            clearTimeout(timer);
         }
     }
     cacheIndexPath() {

package/dist/warning-details.js

@@ -31,7 +31,24 @@ const WARNING_RULES = [
         affectedFields: ["mapping", "version"]
     },
     {
-        test: /falling back to vanilla|resolution failed; falling back|sources jar\.?\s*Falling back|does not include net\.minecraft/i,
+        // compare-versions: the filter is fine but matched nothing, which used to
+        // be indistinguishable from "nothing changed".
+        test: /packageFilter ".*" matched no class/i,
+        code: "filter_matched_nothing",
+        category: "validation",
+        severity: "warning",
+        affectedFields: ["packageFilter"]
+    },
+    {
+        // compare-versions could not lift the jars out of the obfuscated namespace.
+        test: /compared in the OBFUSCATED namespace/i,
+        code: "namespace_fallback",
+        category: "mapping",
+        severity: "warning",
+        affectedFields: ["packageFilter"]
+    },
+    {
+        test: /falling back to vanilla|resolution failed; falling back|sources jar\.?\s*Falling back|(?:does not include|excludes) net\.minecraft/i,
         code: "partial_coverage",
         category: "coverage",
         severity: "warning",

package/docs/README-ja.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@adhisang/minecraft-modding-mcp)](https://www.npmjs.com/package/@adhisang/minecraft-modding-mcp)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
-[![Node.js >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
+[![Node.js >=22.13.0](https://img.shields.io/badge/node-%3E%3D22.13.0-brightgreen.svg)](https://nodejs.org/)
 [![CI](https://github.com/adhi-jp/minecraft-modding-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/adhi-jp/minecraft-modding-mcp/actions/workflows/ci.yml)
 
 **[English](../README.md)** | 日本語
@@ -33,7 +33,7 @@ stdio で動作し、Claude Desktop、Claude Code、VS Code、Codex CLI、Gemini
 
 要件:
 
-- Node.js 22+
+- Node.js 22.13.0+
 - Java は `remap-mod-jar` と、Vineflower または tiny-remapper を必要とするデコンパイル / リマップ処理でのみ必要です
 
 ローカルでサーバーを起動:
@@ -64,6 +64,8 @@ codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
 
 stdio トランスポートは、改行区切り形式と `Content-Length` フレーミングの両方を自動判別します。そのため、Codex と標準的な MCP クライアントで同じサーバー起動コマンドを利用できます。
 
+サーバーは MCP プロトコルリビジョン `2026-07-28`(`server/discover` とリクエスト単位 `_meta` によるステートレス動作)と、従来の `initialize` ベースのレガシープロトコル(`2025-11-25`〜`2024-10-07`)の両方を同一バイナリでサポートします。1 プロセスはクライアントの最初のシグナルで選択された era を提供します。ワイヤレベルの詳細は [docs/tool-reference.md → MCP Protocol Support](tool-reference.md#mcp-protocol-support) を参照してください。
+
 #### Claude Desktop
 
 `claude_desktop_config.json` に次を追加します:
@@ -378,7 +380,7 @@ Mixin ソース、Access Widener ファイル、Forge / NeoForge の Access Tran
 
 リポジトリ要件:
 
-- Node.js 22+
+- Node.js 22.13.0+
 - `pnpm`
 - ローカルでリマップやデコンパイルを実行する場合は Java
 
@@ -405,12 +407,16 @@ pnpm test
 
 必要に応じて実行:
 
+- `pnpm test:file <path...>`: 通常テストをファイル指定で絞り込む場合
+- `pnpm test:grep <name-pattern>`: 通常テストを再帰的に集め、テスト名で絞り込む場合
 - `pnpm test:manual:stdio-smoke`: MCP トランスポート、登録、手動ワークフローの変更時
 - `pnpm test:manual:package-smoke`: パッケージインストールや配布形態の検証時
 - `pnpm test:perf`: 検索、インデックス、性能に影響する変更時
 - `pnpm test:coverage` または `pnpm test:coverage:lcov`: カバレッジ確認時（`lines=80`, `branches=70`, `functions=80`）
 - `pnpm validate`: ローカルの完全検証スイートを実行する場合
 
+通常の `.test.ts` ファイルは `tests/` 配下のドメイン別ディレクトリ（例: `source-service/`, `entry-tools/`, `mapping/`, `mixin/`, `integration/mcp-tools/`, `contracts/`, `utils/`）に置きます。ヘルパー専用モジュールは `tests/helpers` に残し、手動 smoke、性能、リソース、smoke 専用ファイルは既存の専用ディレクトリに残します。
+
 ## ライセンス
 
 [MIT](../LICENSE)