@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.0

package/dist/tool-schemas.js

@@ -99,11 +99,13 @@ export const resolveArtifactTargetSchema = z.discriminatedUnion("kind", [
     workspaceTargetSchema,
     dependencyTargetSchema
 ]);
-// Extended target schema for the source-lookup tools (get-class-source / get-class-members):
-// the same kind-based shape as resolveArtifactTargetSchema, PLUS a `kind:"artifact"` variant
-// that short-circuits resolution by reusing an already-resolved artifactId. The shared
-// resolveArtifactTargetSchema is intentionally NOT widened — the artifact kind has no
-// resolution meaning for resolve-artifact / verify-mixin-target / the batch tools.
+// Extended target schema for the source-lookup tools (get-class-source / get-class-members)
+// and the batch tools that fan out over one shared artifact (batch-class-source /
+// batch-class-members): the same kind-based shape as resolveArtifactTargetSchema, PLUS a
+// `kind:"artifact"` variant that short-circuits resolution by reusing an already-resolved
+// artifactId. The shared resolveArtifactTargetSchema is intentionally NOT widened —
+// the artifact kind has no resolution meaning for resolve-artifact / verify-mixin-target,
+// which resolve a target rather than reuse one.
 export const sourceLookupTargetSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("version"), value: nonEmptyString }),
     z.object({ kind: z.literal("jar"), value: nonEmptyString }),
@@ -238,7 +240,7 @@ export const batchClassSourceEntrySchema = z.object({
     outputFile: optionalNonEmptyString
 });
 export const batchClassSourceShape = {
-    target: resolveArtifactTargetSchema.describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
+    target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional(),
     sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().optional(),
@@ -294,7 +296,7 @@ export const batchClassMembersEntrySchema = z.object({
     maxMembers: optionalPositiveInt
 });
 export const batchClassMembersShape = {
-    target: resolveArtifactTargetSchema.describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
+    target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional(),
     sourcePriority: mappingSourcePrioritySchema.optional(),
     allowDecompile: z.boolean().optional(),

package/dist/types.d.ts

@@ -75,6 +75,15 @@ export interface ArtifactProvenance {
         repoUrl?: string;
     };
     transformChain: string[];
+    /**
+     * The artifact's runtime names ship unobfuscated (Minecraft 26.1+): set for a
+     * 26.1+ version target, a 26.1+ Minecraft runtime coordinate, and a jar target
+     * proven to be a 26.1+ runtime jar; absent otherwise. `mappingApplied` keeps the
+     * label the caller asked for, so on such an artifact "obfuscated" names the
+     * as-shipped names, which are already Mojang names. Same flag name as
+     * `mappingContext.unobfuscatedRuntime`.
+     */
+    unobfuscatedRuntime?: boolean;
     workspaceResolution?: WorkspaceResolutionProvenance;
     dependencyResolution?: DependencyResolutionProvenance;
     warnings?: string[];

package/dist/v1-parity-schemas.js

@@ -446,9 +446,26 @@ export const V1_PARITY_SCHEMAS = {
                             "name"
                         ],
                         "additionalProperties": false
+                    },
+                    {
+                        "type": "object",
+                        "properties": {
+                            "kind": {
+                                "type": "string",
+                                "const": "artifact"
+                            },
+                            "artifactId": {
+                                "$ref": "#/properties/target/anyOf/0/properties/value"
+                            }
+                        },
+                        "required": [
+                            "kind",
+                            "artifactId"
+                        ],
+                        "additionalProperties": false
                     }
                 ],
-                "description": "Object, not string. e.g. {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"}, or to inspect a loader/Fabric dependency like vanilla: {\"kind\":\"dependency\",\"group\":\"net.fabricmc.fabric-api\",\"name\":\"fabric-api\",\"versionFromProject\":true} (needs projectPath) or with an explicit \"version\"."
+                "description": "Same shape as resolve-artifact target (incl. {\"kind\":\"dependency\",...} to read a Fabric/loader dependency class like vanilla), plus {\"kind\":\"artifact\",\"artifactId\":\"...\"} to reuse a resolved artifact. Object, not string."
             },
             "mapping": {
                 "type": "string",
@@ -706,9 +723,26 @@ export const V1_PARITY_SCHEMAS = {
                             "name"
                         ],
                         "additionalProperties": false
+                    },
+                    {
+                        "type": "object",
+                        "properties": {
+                            "kind": {
+                                "type": "string",
+                                "const": "artifact"
+                            },
+                            "artifactId": {
+                                "$ref": "#/properties/target/anyOf/0/properties/value"
+                            }
+                        },
+                        "required": [
+                            "kind",
+                            "artifactId"
+                        ],
+                        "additionalProperties": false
                     }
                 ],
-                "description": "Object, not string. e.g. {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"}, or to inspect a loader/Fabric dependency like vanilla: {\"kind\":\"dependency\",\"group\":\"net.fabricmc.fabric-api\",\"name\":\"fabric-api\",\"versionFromProject\":true} (needs projectPath) or with an explicit \"version\"."
+                "description": "Same shape as resolve-artifact target (incl. {\"kind\":\"dependency\",...} to read a Fabric/loader dependency class like vanilla), plus {\"kind\":\"artifact\",\"artifactId\":\"...\"} to reuse a resolved artifact. Object, not string."
             },
             "mapping": {
                 "type": "string",

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

@@ -52,6 +52,29 @@ export type CompareVersionsOutput = {
     };
     warnings: string[];
 };
+/**
+ * `added`/`removed` entries are `group:artifact:<versions>`, where
+ * `<versions>` is the sorted, comma-joined set of distinct versions seen for
+ * that key on the side it was diffed from or to (a single version renders
+ * as before, e.g. "g:a:1"; multiple platform-specific versions render as
+ * "g:a:1,2").
+ */
+export type LibraryDiffResult = {
+    added: string[];
+    removed: string[];
+    addedCount: number;
+    removedCount: number;
+    /** Count only (per design contract) — no list of which libraries bumped. */
+    versionChangedCount: number;
+};
+/**
+ * Pure diff of two versions' `libraries` name lists, keyed by
+ * `group:artifact` so a per-release version bump or a per-platform natives
+ * classifier never reads as churn. Used by migration-overview to surface
+ * library swaps (e.g. LWJGL GLFW replaced by SDL) that a class/registry diff
+ * cannot see.
+ */
+export declare function diffLibraries(fromNames: string[], toNames: string[]): LibraryDiffResult;
 export declare class VersionDiffService {
     private readonly config;
     private readonly versionService;

package/dist/version-diff-service.js

@@ -88,6 +88,107 @@ function diffSets(from, to) {
     removed.sort();
     return { added, removed, unchanged };
 }
+// Matches a Maven-style library coordinate "group:artifact:version" with an
+// optional trailing classifier ("...:natives-linux"). Group/artifact/version
+// segments must be non-empty and colon-free; anything else is not a library
+// name this diff can key on, so it is silently ignored rather than crashing
+// or reading as a spurious added/removed entry. A trailing "@extension"
+// (e.g. "...@jar") is stripped by the caller before this regex runs, so it
+// never leaks into the captured version.
+const LIBRARY_NAME_RE = /^([^:\s]+):([^:\s]+):([^:\s]+)(?::[^:\s]*)?$/;
+function parseLibraryName(name) {
+    // Strip a trailing "@extension" (e.g. "g:a:1@jar", "g:a:1:natives-linux@jar")
+    // before parsing, so it never gets captured as part of the version.
+    const withoutExtension = name.trim().replace(/@[^@]*$/, "");
+    const match = LIBRARY_NAME_RE.exec(withoutExtension);
+    if (!match) {
+        return undefined;
+    }
+    const [, group, artifact, version] = match;
+    return { key: `${group}:${artifact}`, version };
+}
+/**
+ * Collapses a version's raw library name list to the set of distinct
+ * versions seen per `group:artifact` key, dropping the per-platform natives
+ * classifier and any entry whose name does not parse as a library
+ * coordinate. Real Mojang manifests can list the same `group:artifact` with
+ * different versions under different platform rules, so every version seen
+ * is kept (not just the first) — collapsing to one would make the diff
+ * depend on input order.
+ */
+function collapseLibraryNames(names) {
+    const map = new Map();
+    for (const name of names) {
+        if (typeof name !== "string") {
+            continue;
+        }
+        const parsed = parseLibraryName(name);
+        if (!parsed) {
+            continue;
+        }
+        let versions = map.get(parsed.key);
+        if (!versions) {
+            versions = new Set();
+            map.set(parsed.key, versions);
+        }
+        versions.add(parsed.version);
+    }
+    return map;
+}
+/** Renders a key's version set as the sorted, comma-joined suffix used in `added`/`removed`. */
+function renderVersions(versions) {
+    return Array.from(versions).sort().join(",");
+}
+function versionSetsEqual(a, b) {
+    if (a.size !== b.size) {
+        return false;
+    }
+    for (const version of a) {
+        if (!b.has(version)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Pure diff of two versions' `libraries` name lists, keyed by
+ * `group:artifact` so a per-release version bump or a per-platform natives
+ * classifier never reads as churn. Used by migration-overview to surface
+ * library swaps (e.g. LWJGL GLFW replaced by SDL) that a class/registry diff
+ * cannot see.
+ */
+export function diffLibraries(fromNames, toNames) {
+    const fromMap = collapseLibraryNames(fromNames ?? []);
+    const toMap = collapseLibraryNames(toNames ?? []);
+    const added = [];
+    const removed = [];
+    let versionChangedCount = 0;
+    for (const [key, versions] of toMap) {
+        if (!fromMap.has(key)) {
+            added.push(`${key}:${renderVersions(versions)}`);
+        }
+    }
+    for (const [key, versions] of fromMap) {
+        if (!toMap.has(key)) {
+            removed.push(`${key}:${renderVersions(versions)}`);
+        }
+    }
+    for (const [key, fromVersions] of fromMap) {
+        const toVersions = toMap.get(key);
+        if (toVersions !== undefined && !versionSetsEqual(fromVersions, toVersions)) {
+            versionChangedCount += 1;
+        }
+    }
+    added.sort();
+    removed.sort();
+    return {
+        added,
+        removed,
+        addedCount: added.length,
+        removedCount: removed.length,
+        versionChangedCount
+    };
+}
 function diffRegistries(fromRegistries, toRegistries) {
     const fromKeys = new Set(Object.keys(fromRegistries));
     const toKeys = new Set(Object.keys(toRegistries));

package/dist/version-service.d.ts

@@ -54,6 +54,14 @@ export declare class VersionService {
     listVersionIds(input?: ListVersionIdsInput): Promise<string[]>;
     resolveVersionJar(version: string): Promise<ResolvedVersionJar>;
     resolveVersionMappings(version: string): Promise<ResolvedVersionMappings>;
+    /**
+     * Raw `libraries[].name` coordinates (e.g. "org.lwjgl:lwjgl-glfw:3.4.1")
+     * for one version's per-version JSON, in manifest order. Entries missing a
+     * non-empty string `name` are dropped here at the JSON boundary; further
+     * validation (does the name actually parse as a library coordinate) is the
+     * caller's job — see diffLibraries in version-diff-service.ts.
+     */
+    getVersionLibraries(version: string): Promise<string[]>;
     resolveServerJar(version: string): Promise<ResolvedServerJar>;
     private fetchManifest;
     private resolveVersionJarInternal;
@@ -69,5 +77,11 @@ export declare class VersionService {
  * MC 26.1+ uses new YY.N version format and ships unobfuscated source.
  * Legacy 1.x.y versions remain obfuscated.
  * Snapshots: "26w01a" (year >= 26) → unobfuscated, "24w01a" → obfuscated.
+ *
+ * Pre-release / rc / snapshot suffixes: Mojang's real version-manifest ids
+ * use a hyphenated "-pre-N" / "-rc-N" / "-snapshot-N" form (e.g.
+ * "26.2-pre-6", "26.2-rc-2", "26.3-snapshot-6"). The older no-hyphen
+ * "-preN"/"-rcN" form is also accepted for backwards compatibility, but an
+ * arbitrary or numberless suffix (e.g. "26.1-foo", "26.1-snapshot") is not.
  */
 export declare function isUnobfuscatedVersion(version: string): boolean;

package/dist/version-service.js

@@ -136,6 +136,39 @@ export class VersionService {
             mappingsUrl: clientMappingsUrl
         };
     }
+    /**
+     * Raw `libraries[].name` coordinates (e.g. "org.lwjgl:lwjgl-glfw:3.4.1")
+     * for one version's per-version JSON, in manifest order. Entries missing a
+     * non-empty string `name` are dropped here at the JSON boundary; further
+     * validation (does the name actually parse as a library coordinate) is the
+     * caller's job — see diffLibraries in version-diff-service.ts.
+     */
+    async getVersionLibraries(version) {
+        const normalizedVersion = version.trim();
+        if (!normalizedVersion) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "version must be non-empty."
+            });
+        }
+        const manifest = await this.fetchManifest();
+        const versionEntry = (manifest.versions ?? []).find((entry) => entry.id === normalizedVersion);
+        if (!versionEntry) {
+            throw createError({
+                code: ERROR_CODES.VERSION_NOT_FOUND,
+                message: `Minecraft version "${normalizedVersion}" was not found in version manifest.`,
+                details: {
+                    version: normalizedVersion,
+                    nextAction: "Use list-versions to see available Minecraft versions.",
+                    ...buildSuggestedCall({ tool: "list-versions", params: {} })
+                }
+            });
+        }
+        const details = await this.fetchVersionDetails(versionEntry.url, normalizedVersion);
+        return (details.libraries ?? [])
+            .map((lib) => lib?.name)
+            .filter((name) => typeof name === "string" && name.length > 0);
+    }
     async resolveServerJar(version) {
         const normalizedVersion = version.trim();
         if (!normalizedVersion) {
@@ -473,6 +506,12 @@ export class VersionService {
  * MC 26.1+ uses new YY.N version format and ships unobfuscated source.
  * Legacy 1.x.y versions remain obfuscated.
  * Snapshots: "26w01a" (year >= 26) → unobfuscated, "24w01a" → obfuscated.
+ *
+ * Pre-release / rc / snapshot suffixes: Mojang's real version-manifest ids
+ * use a hyphenated "-pre-N" / "-rc-N" / "-snapshot-N" form (e.g.
+ * "26.2-pre-6", "26.2-rc-2", "26.3-snapshot-6"). The older no-hyphen
+ * "-preN"/"-rcN" form is also accepted for backwards compatibility, but an
+ * arbitrary or numberless suffix (e.g. "26.1-foo", "26.1-snapshot") is not.
  */
 export function isUnobfuscatedVersion(version) {
     if (!version)
@@ -482,9 +521,12 @@ export function isUnobfuscatedVersion(version) {
     if (snapshotMatch) {
         return Number(snapshotMatch[1]) >= 26;
     }
-    // New format: YY.N or YY.N.P, optionally with -preN/-rcN suffix.
-    // Examples: "26.1", "27.3.1", "26.1-pre1", "26.1-rc1"
-    const newFormatMatch = version.match(/^(\d{2,})\.\d+(?:\.\d+)?(?:-(?:pre|rc)\d+)?$/);
+    // New format: YY.N or YY.N.P, optionally with a pre-release/rc/snapshot
+    // suffix in either the legacy no-hyphen form (-preN, -rcN) or Mojang's
+    // real hyphenated form (-pre-N, -rc-N, -snapshot-N).
+    // Examples: "26.1", "27.3.1", "26.1-pre1", "26.1-rc1", "26.2-pre-6",
+    // "26.2-rc-2", "26.3-snapshot-6"
+    const newFormatMatch = version.match(/^(\d{2,})\.\d+(?:\.\d+)?(?:-(?:pre|rc)\d+|-(?:pre|rc|snapshot)-\d+)?$/);
     if (newFormatMatch) {
         return Number(newFormatMatch[1]) >= 26;
     }

package/dist/workspace-mapping-service.d.ts

@@ -50,6 +50,14 @@ export type DependencyVersionOptions = {
 export { isSafeMavenVersionToken };
 export declare class WorkspaceMappingService {
     detectCompileMapping(input: WorkspaceCompileMappingInput): Promise<WorkspaceCompileMappingOutput>;
+    /**
+     * Whether `projectPath` holds at least one build.gradle(.kts) that
+     * `detectCompileMapping` reads: the same files, found the same way, and readable.
+     * `detectCompileMapping` answers "no evidence" both when a build declares no
+     * mappings and when there was no build to read (a missing, mistyped or empty
+     * directory); this tells the two apart without changing that output.
+     */
+    hasReadableBuildScript(projectPath: string): Promise<boolean>;
     detectProjectMinecraftVersion(projectPath: string): Promise<string | undefined>;
     detectDependencyVersion(projectPath: string, group: string, name: string, opts?: DependencyVersionOptions): Promise<DependencyVersionResolution>;
     detectProjectLoader(projectPath: string): Promise<WorkspaceProjectLoaderOutput>;

package/dist/workspace-mapping-service.js

@@ -1,4 +1,5 @@
-import { readdir, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { access, readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import fastGlob from "fast-glob";
@@ -271,6 +272,15 @@ function detectLoadersFromContent(content) {
     }
     return detections;
 }
+/** The build.gradle(.kts) files `detectCompileMapping` scans under `root`, sorted. */
+async function listCompileMappingBuildScripts(root) {
+    return (await fastGlob.glob(["build.gradle", "build.gradle.kts", "**/build.gradle", "**/build.gradle.kts"], {
+        cwd: root,
+        absolute: true,
+        onlyFiles: true,
+        ignore: ["**/.git/**", "**/.gradle/**", "**/build/**", "**/out/**", "**/node_modules/**"]
+    })).sort((left, right) => left.localeCompare(right));
+}
 export class WorkspaceMappingService {
     async detectCompileMapping(input) {
         const projectPath = input.projectPath?.trim();
@@ -284,12 +294,7 @@ export class WorkspaceMappingService {
             });
         }
         const root = resolve(projectPath);
-        const files = (await fastGlob.glob(["build.gradle", "build.gradle.kts", "**/build.gradle", "**/build.gradle.kts"], {
-            cwd: root,
-            absolute: true,
-            onlyFiles: true,
-            ignore: ["**/.git/**", "**/.gradle/**", "**/build/**", "**/out/**", "**/node_modules/**"]
-        })).sort((left, right) => left.localeCompare(right));
+        const files = await listCompileMappingBuildScripts(root);
         const evidence = (await mapWithConcurrencyLimit(files, WORKSPACE_FILE_READ_CONCURRENCY, async (filePath) => {
             let content;
             try {
@@ -328,6 +333,29 @@ export class WorkspaceMappingService {
             warnings: []
         };
     }
+    /**
+     * Whether `projectPath` holds at least one build.gradle(.kts) that
+     * `detectCompileMapping` reads: the same files, found the same way, and readable.
+     * `detectCompileMapping` answers "no evidence" both when a build declares no
+     * mappings and when there was no build to read (a missing, mistyped or empty
+     * directory); this tells the two apart without changing that output.
+     */
+    async hasReadableBuildScript(projectPath) {
+        const trimmed = projectPath.trim();
+        if (!trimmed) {
+            return false;
+        }
+        for (const filePath of await listCompileMappingBuildScripts(resolve(trimmed))) {
+            try {
+                await access(filePath, constants.R_OK);
+                return true;
+            }
+            catch {
+                // detectCompileMapping skips an unreadable script too.
+            }
+        }
+        return false;
+    }
     async detectProjectMinecraftVersion(projectPath) {
         const root = resolve(projectPath);
         const propsPath = resolve(root, "gradle.properties");

package/docs/README-ja.md

@@ -161,6 +161,8 @@ stdio トランスポートは、改行区切り形式と `Content-Length` フ
 - ワークスペースのソースカバレッジが部分的な場合でも、バニラクラスを確認できます。`inspect-minecraft task="list-files"` は、その場合に部分的な結果とフォローアップガイダンスを返します。
 - `analyze-mod` と `validate-project` は、オブジェクト形式の `subject` と正規の `include` グループを要求します。古い文字列形式の `subject` やドメイン名形式の `include` には `ERR_INVALID_INPUT` と、再試行しやすい `suggestedCall` を返します。
 - `validate-mixin` と `validate-project` は、`obfuscated` / `mojang` 検証では `mapping-health` を軽量に保ちます。`intermediary` / `yarn` 名前空間を要求しない限り、完全な Tiny マッピンググラフは読み込みません。
+- `validate-project task="project-summary"` は `version` を省略すると `gradle.properties` から Minecraft バージョンを推定し、推定したバージョンを `warnings` に示します。推定を止めるには `preferProjectVersion: false` を指定します。その場合、`version` のない呼び出しは `status: "blocked"` を返します。解決したバージョン（明示指定または推定）は、検出したすべての Mixin / Access Widener / Access Transformer の検証に渡されます。ファイルを検出したのにバージョンを推定できない場合は、推測せずに、明示的な `version` を求める再試行案付きで `status: "blocked"` を返します。
+- `validate-project task="project-summary"` が検証対象のファイルを 1 つも検出しなかった場合、`status` は `"ok"` のままですが、headline が `Nothing to validate: ...` となり、`warnings` にも何も検証していないことが示されます。`"ok"` だけでは、いずれかのファイルが検証に通ったことを意味しません。
 - `validate-project task="project-summary"` の `tasks["minecraft.artifact.resolved"]` は軽量なアーティファクト probe です。probe 状態を返すためだけに Minecraft のデコンパイルやソースインデックス再構築は行いません。追加の `tasks` フィールドを省きたい場合は `VALIDATE_PROJECT_TASKS_OFF=1` を使います。
 
 ### あるバージョンの Minecraft ソースを確認する