@adhisang/minecraft-modding-mcp 1.0.0

package/dist/mod-analyzer.js

@@ -0,0 +1,346 @@
+import { parse as parseToml } from "smol-toml";
+import { z } from "zod";
+import { AppError, ERROR_CODES } from "./errors.js";
+import { normalizeJarPath } from "./path-resolver.js";
+import { listJarEntries, readJarEntryAsUtf8 } from "./source-jar-reader.js";
+function toErrorMessage(value) {
+    if (value instanceof Error) {
+        return value.message;
+    }
+    return String(value);
+}
+// ---------------------------------------------------------------------------
+// Zod schemas — .passthrough() for lenient parsing
+// ---------------------------------------------------------------------------
+const stringOrEntrypoint = z.union([
+    z.string(),
+    z.object({ value: z.string() }).passthrough()
+]);
+const stringOrMixinRef = z.union([
+    z.string(),
+    z.object({ config: z.string() }).passthrough()
+]);
+const fabricModJsonSchema = z
+    .object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    version: z.string().optional(),
+    description: z.string().optional(),
+    entrypoints: z.record(z.array(stringOrEntrypoint)).optional(),
+    mixins: z.array(stringOrMixinRef).optional(),
+    accessWidener: z.string().optional(),
+    depends: z.record(z.union([z.string(), z.array(z.string())])).optional(),
+    recommends: z.record(z.union([z.string(), z.array(z.string())])).optional(),
+    conflicts: z.record(z.union([z.string(), z.array(z.string())])).optional(),
+    suggests: z.record(z.union([z.string(), z.array(z.string())])).optional()
+})
+    .passthrough();
+const quiltModJsonSchema = z
+    .object({
+    schema_version: z.number().optional(),
+    quilt_loader: z
+        .object({
+        id: z.string().optional(),
+        version: z.string().optional(),
+        metadata: z
+            .object({
+            name: z.string().optional(),
+            description: z.string().optional()
+        })
+            .passthrough()
+            .optional(),
+        entrypoints: z.record(z.array(stringOrEntrypoint)).optional(),
+        depends: z.array(z.unknown()).optional()
+    })
+        .passthrough()
+        .optional(),
+    mixin: z.union([z.string(), z.array(z.string())]).optional(),
+    access_widener: z.string().optional()
+})
+    .passthrough();
+const forgeModsTomlSchema = z
+    .object({
+    modLoader: z.string().optional(),
+    mods: z
+        .array(z
+        .object({
+        modId: z.string().optional(),
+        displayName: z.string().optional(),
+        version: z.string().optional(),
+        description: z.string().optional()
+    })
+        .passthrough())
+        .optional(),
+    dependencies: z.record(z.array(z.unknown())).optional(),
+    mixins: z.array(z.object({ config: z.string() }).passthrough()).optional()
+})
+    .passthrough();
+const legacyForgeSchema = z.array(z
+    .object({
+    modid: z.string().optional(),
+    name: z.string().optional(),
+    version: z.string().optional(),
+    description: z.string().optional()
+})
+    .passthrough());
+// ---------------------------------------------------------------------------
+// Parser: Fabric
+// ---------------------------------------------------------------------------
+function normalizeFabricEntrypoint(v) {
+    return typeof v === "string" ? v : v.value;
+}
+function normalizeMixinRef(v) {
+    return typeof v === "string" ? v : v.config;
+}
+function collectFabricDeps(record, kind) {
+    if (!record)
+        return [];
+    return Object.entries(record).map(([modId, versionRange]) => ({
+        modId,
+        versionRange: Array.isArray(versionRange) ? versionRange.join(" || ") : versionRange,
+        kind
+    }));
+}
+function parseFabricMod(content) {
+    const parsed = fabricModJsonSchema.safeParse(JSON.parse(content));
+    if (!parsed.success)
+        return {};
+    const mod = parsed.data;
+    const entrypoints = mod.entrypoints
+        ? Object.fromEntries(Object.entries(mod.entrypoints).map(([key, values]) => [
+            key,
+            values.map(normalizeFabricEntrypoint)
+        ]))
+        : undefined;
+    const mixinConfigs = mod.mixins?.map(normalizeMixinRef);
+    const dependencies = [
+        ...collectFabricDeps(mod.depends, "required"),
+        ...collectFabricDeps(mod.recommends, "recommends"),
+        ...collectFabricDeps(mod.conflicts, "conflicts"),
+        ...collectFabricDeps(mod.suggests, "optional")
+    ];
+    return {
+        modId: mod.id,
+        modName: mod.name,
+        modVersion: mod.version,
+        description: mod.description,
+        entrypoints,
+        mixinConfigs,
+        accessWidener: mod.accessWidener,
+        dependencies: dependencies.length > 0 ? dependencies : undefined
+    };
+}
+// ---------------------------------------------------------------------------
+// Parser: Quilt
+// ---------------------------------------------------------------------------
+function parseQuiltMod(content) {
+    const parsed = quiltModJsonSchema.safeParse(JSON.parse(content));
+    if (!parsed.success)
+        return {};
+    const mod = parsed.data;
+    const loader = mod.quilt_loader;
+    const entrypoints = loader?.entrypoints
+        ? Object.fromEntries(Object.entries(loader.entrypoints).map(([key, values]) => [
+            key,
+            values.map(normalizeFabricEntrypoint)
+        ]))
+        : undefined;
+    const rawMixin = mod.mixin;
+    const mixinConfigs = rawMixin
+        ? Array.isArray(rawMixin)
+            ? rawMixin
+            : [rawMixin]
+        : undefined;
+    const dependencies = [];
+    if (loader?.depends && Array.isArray(loader.depends)) {
+        for (const dep of loader.depends) {
+            if (typeof dep === "string") {
+                dependencies.push({ modId: dep, kind: "required" });
+            }
+            else if (dep && typeof dep === "object" && "id" in dep) {
+                const d = dep;
+                dependencies.push({
+                    modId: d.id,
+                    versionRange: d.versions,
+                    kind: d.optional ? "optional" : "required"
+                });
+            }
+        }
+    }
+    return {
+        modId: loader?.id,
+        modName: loader?.metadata?.name,
+        modVersion: loader?.version,
+        description: loader?.metadata?.description,
+        entrypoints,
+        mixinConfigs,
+        accessWidener: mod.access_widener,
+        dependencies: dependencies.length > 0 ? dependencies : undefined
+    };
+}
+// ---------------------------------------------------------------------------
+// Parser: Forge / NeoForge (TOML)
+// ---------------------------------------------------------------------------
+function parseForgeMod(content, entries) {
+    const raw = parseToml(content);
+    const parsed = forgeModsTomlSchema.safeParse(raw);
+    if (!parsed.success)
+        return {};
+    const toml = parsed.data;
+    const firstMod = toml.mods?.[0];
+    // Determine Forge vs NeoForge from modLoader field
+    const modLoaderValue = toml.modLoader?.toLowerCase() ?? "";
+    const isNeoForge = modLoaderValue.includes("neoforge") || modLoaderValue.includes("lowcodefml");
+    // Also check for neoforge.mods.toml presence
+    const hasNeoforgeToml = entries.includes("META-INF/neoforge.mods.toml");
+    const detectedLoader = isNeoForge || hasNeoforgeToml ? "neoforge" : "forge";
+    // Dependencies
+    const dependencies = [];
+    if (toml.dependencies) {
+        for (const depArray of Object.values(toml.dependencies)) {
+            for (const dep of depArray) {
+                if (dep && typeof dep === "object") {
+                    const d = dep;
+                    if (d.modId) {
+                        dependencies.push({
+                            modId: d.modId,
+                            versionRange: d.versionRange,
+                            kind: d.mandatory === false ? "optional" : "required"
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Mixin configs
+    const mixinConfigs = toml.mixins?.map((m) => m.config);
+    return {
+        detectedLoader,
+        modId: firstMod?.modId,
+        modName: firstMod?.displayName,
+        modVersion: firstMod?.version,
+        description: firstMod?.description,
+        mixinConfigs: mixinConfigs && mixinConfigs.length > 0 ? mixinConfigs : undefined,
+        dependencies: dependencies.length > 0 ? dependencies : undefined
+    };
+}
+// ---------------------------------------------------------------------------
+// Parser: Legacy Forge (mcmod.info)
+// ---------------------------------------------------------------------------
+function parseLegacyForgeMod(content) {
+    // mcmod.info may be wrapped in an extra array or be a direct array
+    let rawArray = JSON.parse(content);
+    if (Array.isArray(rawArray) && rawArray.length === 1 && Array.isArray(rawArray[0])) {
+        rawArray = rawArray[0];
+    }
+    const parsed = legacyForgeSchema.safeParse(rawArray);
+    if (!parsed.success)
+        return {};
+    const first = parsed.data[0];
+    if (!first)
+        return {};
+    return {
+        modId: first.modid,
+        modName: first.name,
+        modVersion: first.version,
+        description: first.description
+    };
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+export async function analyzeModJar(jarPath, options) {
+    let resolvedPath;
+    try {
+        resolvedPath = normalizeJarPath(jarPath);
+    }
+    catch (cause) {
+        throw new AppError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: cause instanceof Error ? cause.message : `Invalid jar path: ${jarPath}`,
+            details: { jarPath }
+        });
+    }
+    let entries;
+    try {
+        entries = await listJarEntries(resolvedPath);
+    }
+    catch (cause) {
+        throw new AppError({
+            code: ERROR_CODES.SOURCE_NOT_FOUND,
+            message: `Failed to read jar "${resolvedPath}".`,
+            details: {
+                jarPath: resolvedPath,
+                reason: toErrorMessage(cause)
+            }
+        });
+    }
+    // Class counting
+    const classEntries = entries.filter((e) => e.endsWith(".class"));
+    const classCount = classEntries.length;
+    const classes = options?.includeClasses ? classEntries : undefined;
+    // Detect loader and parse metadata
+    let loader = "unknown";
+    let metadata = {};
+    if (entries.includes("fabric.mod.json")) {
+        loader = "fabric";
+        try {
+            const content = await readJarEntryAsUtf8(resolvedPath, "fabric.mod.json");
+            metadata = parseFabricMod(content);
+        }
+        catch {
+            // graceful fallback
+        }
+    }
+    else if (entries.includes("quilt.mod.json")) {
+        loader = "quilt";
+        try {
+            const content = await readJarEntryAsUtf8(resolvedPath, "quilt.mod.json");
+            metadata = parseQuiltMod(content);
+        }
+        catch {
+            // graceful fallback
+        }
+    }
+    else if (entries.includes("META-INF/neoforge.mods.toml")) {
+        loader = "neoforge";
+        try {
+            const content = await readJarEntryAsUtf8(resolvedPath, "META-INF/neoforge.mods.toml");
+            const result = parseForgeMod(content, entries);
+            const { detectedLoader: _, ...rest } = result;
+            metadata = rest;
+        }
+        catch {
+            // graceful fallback
+        }
+    }
+    else if (entries.includes("META-INF/mods.toml")) {
+        try {
+            const content = await readJarEntryAsUtf8(resolvedPath, "META-INF/mods.toml");
+            const result = parseForgeMod(content, entries);
+            loader = result.detectedLoader ?? "forge";
+            const { detectedLoader: _, ...rest } = result;
+            metadata = rest;
+        }
+        catch {
+            loader = "forge";
+        }
+    }
+    else if (entries.includes("mcmod.info")) {
+        loader = "forge";
+        try {
+            const content = await readJarEntryAsUtf8(resolvedPath, "mcmod.info");
+            metadata = parseLegacyForgeMod(content);
+        }
+        catch {
+            // graceful fallback
+        }
+    }
+    return {
+        loader,
+        ...metadata,
+        classCount,
+        ...(classes !== undefined ? { classes } : {})
+    };
+}
+//# sourceMappingURL=mod-analyzer.js.map

package/dist/mod-decompile-service.d.ts

@@ -0,0 +1,39 @@
+import type { Config } from "./types.js";
+export type DecompileModJarInput = {
+    jarPath: string;
+    className?: string;
+};
+export type DecompileModJarOutput = {
+    modId: string;
+    modName?: string;
+    modVersion?: string;
+    loader: string;
+    outputDir: string;
+    fileCount: number;
+    files?: string[];
+    source?: {
+        className: string;
+        content: string;
+        totalLines: number;
+    };
+    warnings: string[];
+};
+export type GetModClassSourceInput = {
+    jarPath: string;
+    className: string;
+};
+export type GetModClassSourceOutput = {
+    className: string;
+    content: string;
+    totalLines: number;
+    modId?: string;
+    warnings: string[];
+};
+export declare class ModDecompileService {
+    private readonly config;
+    private readonly decompileCache;
+    constructor(config: Config);
+    decompileModJar(input: DecompileModJarInput): Promise<DecompileModJarOutput>;
+    getModClassSource(input: GetModClassSourceInput): Promise<GetModClassSourceOutput>;
+    private ensureDecompiled;
+}

package/dist/mod-decompile-service.js

@@ -0,0 +1,136 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createError, ERROR_CODES } from "./errors.js";
+import { log } from "./logger.js";
+import { decompileBinaryJar } from "./decompiler/vineflower.js";
+import { resolveVineflowerJar } from "./vineflower-resolver.js";
+import { analyzeModJar } from "./mod-analyzer.js";
+import { validateAndNormalizeJarPath } from "./path-resolver.js";
+const DECOMPILE_TIMEOUT_MS = 300_000;
+function modDecompileCacheKey(jarPath) {
+    return createHash("sha256").update(jarPath).digest("hex");
+}
+function classNameToFilePath(className) {
+    return className.replaceAll(".", "/") + ".java";
+}
+function filePathToClassName(filePath) {
+    return filePath.replace(/\.java$/, "").replaceAll("/", ".");
+}
+export class ModDecompileService {
+    config;
+    // Cache: jarPath hash → decompiled output dir + file list
+    decompileCache = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    async decompileModJar(input) {
+        const jarPath = validateAndNormalizeJarPath(input.jarPath);
+        const warnings = [];
+        const { outputDir, files, analysis } = await this.ensureDecompiled(jarPath, warnings);
+        let sourceResult;
+        if (input.className) {
+            const targetFile = classNameToFilePath(input.className);
+            const matched = files.find((f) => f === targetFile || f.endsWith(`/${targetFile}`) || f === input.className);
+            if (matched) {
+                const content = readFileSync(join(outputDir, matched), "utf8");
+                sourceResult = {
+                    className: filePathToClassName(matched),
+                    content,
+                    totalLines: content.split("\n").length
+                };
+            }
+            else {
+                warnings.push(`Class "${input.className}" not found in decompiled output. Use the files list to find available classes.`);
+            }
+        }
+        return {
+            modId: analysis.modId ?? "unknown",
+            modName: analysis.modName,
+            modVersion: analysis.modVersion,
+            loader: analysis.loader,
+            outputDir,
+            fileCount: files.length,
+            files: input.className ? undefined : files.map(filePathToClassName),
+            source: sourceResult,
+            warnings
+        };
+    }
+    async getModClassSource(input) {
+        const jarPath = validateAndNormalizeJarPath(input.jarPath);
+        const className = input.className.trim();
+        if (!className) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "className must be non-empty."
+            });
+        }
+        const warnings = [];
+        const { outputDir, files, analysis } = await this.ensureDecompiled(jarPath, warnings);
+        const targetFile = classNameToFilePath(className);
+        const matched = files.find((f) => f === targetFile || f.endsWith(`/${targetFile}`));
+        if (!matched) {
+            throw createError({
+                code: ERROR_CODES.CLASS_NOT_FOUND,
+                message: `Class "${className}" not found in decompiled mod JAR.`,
+                details: { className, jarPath, availableCount: files.length }
+            });
+        }
+        const content = readFileSync(join(outputDir, matched), "utf8");
+        return {
+            className: filePathToClassName(matched),
+            content,
+            totalLines: content.split("\n").length,
+            modId: analysis.modId,
+            warnings
+        };
+    }
+    async ensureDecompiled(jarPath, warnings) {
+        const cacheKey = modDecompileCacheKey(jarPath);
+        const cached = this.decompileCache.get(cacheKey);
+        if (cached)
+            return cached;
+        log("info", "mod-decompile.start", { jarPath });
+        const startedAt = Date.now();
+        // Analyze mod metadata
+        let analysis;
+        try {
+            analysis = await analyzeModJar(jarPath, { includeClasses: false });
+        }
+        catch {
+            analysis = {
+                loader: "unknown",
+                classCount: 0
+            };
+            warnings.push("Could not extract mod metadata from JAR.");
+        }
+        // Resolve Vineflower
+        const vineflowerPath = await resolveVineflowerJar(this.config.cacheDir, this.config.vineflowerJarPath);
+        // Decompile
+        const decompileResult = await decompileBinaryJar(jarPath, this.config.cacheDir, {
+            vineflowerJarPath: vineflowerPath,
+            timeoutMs: DECOMPILE_TIMEOUT_MS,
+            signature: cacheKey
+        });
+        const files = decompileResult.javaFiles.map((entry) => entry.filePath);
+        const result = {
+            outputDir: decompileResult.outputDir,
+            files,
+            analysis
+        };
+        this.decompileCache.set(cacheKey, result);
+        // Trim cache
+        if (this.decompileCache.size > 8) {
+            const oldest = this.decompileCache.keys().next().value;
+            if (oldest !== undefined)
+                this.decompileCache.delete(oldest);
+        }
+        log("info", "mod-decompile.done", {
+            jarPath,
+            fileCount: files.length,
+            durationMs: Date.now() - startedAt
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=mod-decompile-service.js.map

package/dist/mod-remap-service.d.ts

@@ -0,0 +1,17 @@
+import type { Config } from "./types.js";
+export interface ModRemapInput {
+    inputJar: string;
+    outputJar?: string;
+    mcVersion?: string;
+    targetMapping: "yarn" | "mojang";
+}
+export interface ModRemapResult {
+    outputJar: string;
+    mcVersion: string;
+    fromMapping: string;
+    targetMapping: string;
+    resolvedTargetNamespace: "yarn" | "mojang";
+    durationMs: number;
+    warnings: string[];
+}
+export declare function remapModJar(input: ModRemapInput, config: Config): Promise<ModRemapResult>;