@adhisang/minecraft-modding-mcp 1.0.0

package/dist/path-converter.js

@@ -0,0 +1,161 @@
+import { release } from "node:os";
+import { createError, ERROR_CODES } from "./errors.js";
+const WINDOWS_DRIVE_PATH = /^[A-Za-z]:[\\/]/;
+const MALFORMED_WINDOWS_DRIVE_PATH = /^[A-Za-z]:(?![\\/])/;
+const WSL_MOUNT_PATH = /^\/mnt\/[a-z](?:\/|$)/i;
+const UNC_WSL_PATH = /^(?:\\\\wsl\$\\|\/\/wsl\$\/)/i;
+function normalizeToUnixSlashes(value) {
+    return value.replace(/\\/g, "/");
+}
+function normalizeToWindowsSlashes(value) {
+    return value.replace(/\//g, "\\");
+}
+function parseUncWslPath(pathValue) {
+    const normalized = normalizeToUnixSlashes(pathValue);
+    if (!normalized.toLowerCase().startsWith("//wsl$/")) {
+        return undefined;
+    }
+    const remainder = normalized.slice("//wsl$/".length).replace(/^\/+/, "");
+    const slashIndex = remainder.indexOf("/");
+    if (slashIndex < 0) {
+        return {
+            distro: remainder,
+            innerPath: ""
+        };
+    }
+    return {
+        distro: remainder.slice(0, slashIndex),
+        innerPath: remainder.slice(slashIndex + 1)
+    };
+}
+export function detectPathRuntime() {
+    const platform = process.platform;
+    const osRelease = release().toLowerCase();
+    const isWsl = platform === "linux" &&
+        (Boolean(process.env.WSL_DISTRO_NAME) ||
+            Boolean(process.env.WSL_INTEROP) ||
+            osRelease.includes("microsoft"));
+    return {
+        platform,
+        isWsl,
+        wslDistro: process.env.WSL_DISTRO_NAME
+    };
+}
+export function isWindowsDrivePath(pathValue) {
+    return WINDOWS_DRIVE_PATH.test(pathValue);
+}
+export function isWslMountPath(pathValue) {
+    return WSL_MOUNT_PATH.test(pathValue);
+}
+export function isUncWslPath(pathValue) {
+    return UNC_WSL_PATH.test(pathValue);
+}
+export function validatePathFormat(pathValue, runtimeInfo) {
+    const runtime = runtimeInfo ?? detectPathRuntime();
+    const trimmed = pathValue.trim();
+    if (!trimmed) {
+        return "Path is required.";
+    }
+    if (trimmed.includes("\0")) {
+        return "Path contains an invalid null character.";
+    }
+    if (MALFORMED_WINDOWS_DRIVE_PATH.test(trimmed)) {
+        return 'Windows drive paths must include a separator after the drive (example: "C:\\\\path").';
+    }
+    if (isUncWslPath(trimmed)) {
+        const parsed = parseUncWslPath(trimmed);
+        if (!parsed?.distro) {
+            return 'UNC WSL paths must include a distro segment (example: "\\\\\\\\wsl$\\\\Ubuntu\\\\path").';
+        }
+    }
+    const usesWindowsStyle = isWindowsDrivePath(trimmed) || isUncWslPath(trimmed);
+    if (usesWindowsStyle && runtime.platform !== "win32" && !runtime.isWsl) {
+        return "Windows-style paths are not supported on this host.";
+    }
+    return undefined;
+}
+function throwInvalidPath(pathValue, reason, runtime, field) {
+    throw createError({
+        code: ERROR_CODES.INVALID_INPUT,
+        message: reason,
+        details: {
+            field: field ?? "path",
+            path: pathValue,
+            platform: runtime.platform,
+            isWsl: runtime.isWsl
+        }
+    });
+}
+function toWslPath(pathValue, runtime, field) {
+    if (isWindowsDrivePath(pathValue)) {
+        const normalized = normalizeToUnixSlashes(pathValue);
+        const match = normalized.match(/^([A-Za-z]):(?:\/(.*))?$/);
+        if (!match?.[1]) {
+            throwInvalidPath(pathValue, "Failed to parse Windows drive path.", runtime, field);
+        }
+        const drive = match[1].toLowerCase();
+        const rest = (match[2] ?? "").replace(/^\/+/, "");
+        return rest ? `/mnt/${drive}/${rest}` : `/mnt/${drive}`;
+    }
+    const parsed = parseUncWslPath(pathValue);
+    if (parsed) {
+        const rest = parsed.innerPath.replace(/^\/+/, "");
+        return rest ? `/${rest}` : "/";
+    }
+    return pathValue;
+}
+function toWindowsPath(pathValue, runtime, field) {
+    if (isWslMountPath(pathValue)) {
+        const normalized = normalizeToUnixSlashes(pathValue);
+        const match = normalized.match(/^\/mnt\/([A-Za-z])(?:\/(.*))?$/);
+        if (!match?.[1]) {
+            throwInvalidPath(pathValue, "Failed to parse WSL mount path.", runtime, field);
+        }
+        const drive = match[1].toUpperCase();
+        const rest = (match[2] ?? "").replace(/^\/+/, "").replace(/\//g, "\\");
+        return rest ? `${drive}:\\${rest}` : `${drive}:\\`;
+    }
+    if (pathValue.startsWith("/")) {
+        const distro = runtime.wslDistro?.trim();
+        if (!distro) {
+            throwInvalidPath(pathValue, "Cannot convert Unix path to Windows path without WSL distro name.", runtime, field);
+        }
+        return `\\\\wsl$\\${distro}${pathValue.replace(/\//g, "\\")}`;
+    }
+    return normalizeToWindowsSlashes(pathValue);
+}
+export function normalizePathForHost(pathValue, runtimeInfo, field) {
+    const runtime = runtimeInfo ?? detectPathRuntime();
+    const validationError = validatePathFormat(pathValue, runtime);
+    if (validationError) {
+        throwInvalidPath(pathValue, validationError, runtime, field);
+    }
+    const trimmed = pathValue.trim();
+    if (runtime.isWsl) {
+        if (isWindowsDrivePath(trimmed) || isUncWslPath(trimmed)) {
+            return toWslPath(trimmed, runtime, field);
+        }
+        return trimmed;
+    }
+    if (runtime.platform === "win32") {
+        if (isWindowsDrivePath(trimmed) || isUncWslPath(trimmed)) {
+            return normalizeToWindowsSlashes(trimmed);
+        }
+        if (isWslMountPath(trimmed) || trimmed.startsWith("/")) {
+            return toWindowsPath(trimmed, runtime, field);
+        }
+        return trimmed;
+    }
+    return trimmed;
+}
+export function normalizeOptionalPathForHost(pathValue, runtimeInfo, field) {
+    if (!pathValue) {
+        return undefined;
+    }
+    const trimmed = pathValue.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return normalizePathForHost(trimmed, runtimeInfo, field);
+}
+//# sourceMappingURL=path-converter.js.map

package/dist/path-resolver.d.ts

@@ -0,0 +1,19 @@
+import type { ArtifactSignature } from "./types.js";
+export interface ResolvedJarInfo {
+    originalPath: string;
+    resolvedPath: string;
+}
+export declare function normalizeJarPath(jarPath: string): string;
+export declare function resolveJarPathWithSymlinkCheck(jarPath: string): ResolvedJarInfo;
+export declare function buildJarSignature(stats: {
+    mtimeMs: number;
+    size: number;
+}): string;
+export declare function artifactSignatureFromFile(jarPath: string): ArtifactSignature;
+export declare function isSecureJarEntryPath(entryPath: string): boolean;
+/**
+ * Validate and normalize a user-supplied jar path input.
+ * Trims whitespace, validates non-empty, resolves symlinks, and wraps
+ * any filesystem error as ERR_INVALID_INPUT.
+ */
+export declare function validateAndNormalizeJarPath(jarPathInput: string): string;

package/dist/path-resolver.js

@@ -0,0 +1,78 @@
+import { realpathSync, statSync } from "node:fs";
+import { extname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { normalizePathForHost } from "./path-converter.js";
+import { createError, ERROR_CODES } from "./errors.js";
+const INVALID_ENTRY = /(^|\/|\\)\.\.(\/|\\|$)/;
+export function normalizeJarPath(jarPath) {
+    const normalizedInput = normalizePathForHost(jarPath, undefined, "jarPath");
+    const absolute = resolve(normalizedInput);
+    const stats = statSync(absolute);
+    if (!stats.isFile()) {
+        throw createError({
+            code: ERROR_CODES.JAR_NOT_FOUND,
+            message: `Expected a file path for jar, got "${normalizedInput}".`,
+            details: { jarPath: normalizedInput }
+        });
+    }
+    if (extname(absolute).toLowerCase() !== ".jar") {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Expected a .jar file, got "${normalizedInput}".`,
+            details: { jarPath: normalizedInput }
+        });
+    }
+    const resolved = realpathSync(absolute);
+    return resolved;
+}
+export function resolveJarPathWithSymlinkCheck(jarPath) {
+    const resolvedPath = normalizeJarPath(jarPath);
+    return {
+        originalPath: jarPath,
+        resolvedPath
+    };
+}
+export function buildJarSignature(stats) {
+    return `${Math.trunc(stats.mtimeMs)}:${stats.size}`;
+}
+export function artifactSignatureFromFile(jarPath) {
+    const resolvedPath = resolveJarPathWithSymlinkCheck(jarPath).resolvedPath;
+    const stats = statSync(resolvedPath);
+    return {
+        sourcePath: resolvedPath,
+        sourceArtifactId: createHash("sha256").update(`jar|${resolvedPath}|${buildJarSignature(stats)}`).digest("hex"),
+        signature: buildJarSignature(stats),
+        signatureParts: {
+            mtimeMs: stats.mtimeMs,
+            size: stats.size
+        }
+    };
+}
+export function isSecureJarEntryPath(entryPath) {
+    return !INVALID_ENTRY.test(entryPath.replaceAll("\\", "/"));
+}
+/**
+ * Validate and normalize a user-supplied jar path input.
+ * Trims whitespace, validates non-empty, resolves symlinks, and wraps
+ * any filesystem error as ERR_INVALID_INPUT.
+ */
+export function validateAndNormalizeJarPath(jarPathInput) {
+    const jarPath = jarPathInput.trim();
+    if (!jarPath) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: "jarPath must be non-empty."
+        });
+    }
+    try {
+        return normalizeJarPath(jarPath);
+    }
+    catch (cause) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: cause instanceof Error ? cause.message : `Invalid jar path: "${jarPath}".`,
+            details: { jarPath }
+        });
+    }
+}
+//# sourceMappingURL=path-resolver.js.map

package/dist/registry-service.d.ts

@@ -0,0 +1,29 @@
+import { VersionService } from "./version-service.js";
+import type { Config } from "./types.js";
+export type GetRegistryDataInput = {
+    version: string;
+    registry?: string;
+};
+export type RegistryEntry = {
+    protocol_id: number;
+};
+export type RegistryData = {
+    default?: string;
+    entries: Record<string, RegistryEntry>;
+};
+export type GetRegistryDataOutput = {
+    version: string;
+    registry?: string;
+    registries?: string[];
+    data: Record<string, RegistryData> | RegistryData;
+    entryCount: number;
+    warnings: string[];
+};
+export declare class RegistryService {
+    private readonly config;
+    private readonly versionService;
+    private readonly registryCache;
+    constructor(config: Config, versionService: VersionService);
+    getRegistryData(input: GetRegistryDataInput): Promise<GetRegistryDataOutput>;
+    private loadRegistries;
+}

package/dist/registry-service.js

@@ -0,0 +1,214 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { createError, ERROR_CODES } from "./errors.js";
+import { log } from "./logger.js";
+const DATAGEN_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_STDIO_SNAPSHOT = 6_240;
+function limitOutput(text) {
+    if (text.length <= MAX_STDIO_SNAPSHOT)
+        return text;
+    return text.slice(-MAX_STDIO_SNAPSHOT);
+}
+function resolveRegistryPaths(registryDir) {
+    return [
+        join(registryDir, "reports", "registries.json"),
+        join(registryDir, "generated", "reports", "registries.json"),
+        join(registryDir, "registries.json")
+    ];
+}
+function findRegistryFile(registryDir) {
+    for (const candidate of resolveRegistryPaths(registryDir)) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function runDataGen(serverJarPath, outputDir, version) {
+    return new Promise((resolve, reject) => {
+        // MC 1.18+ uses bundler format, older versions use -cp with main class directly.
+        // The bundler approach works for 1.18+ and the -cp approach for older versions.
+        // We try bundler first since most modern versions use it.
+        const isLegacy = isLegacyVersion(version);
+        const args = isLegacy
+            ? [
+                "-cp", serverJarPath,
+                "-Xmx2G", "-Xms512M",
+                "net.minecraft.data.Main",
+                "--reports", "--all", "--server",
+                "--output", outputDir
+            ]
+            : [
+                "-DbundlerMainClass=net.minecraft.data.Main",
+                "-Xmx2G", "-Xms512M",
+                "-jar", serverJarPath,
+                "--reports", "--all", "--server",
+                "--output", outputDir
+            ];
+        log("info", "registry.datagen.start", { version, isLegacy, serverJarPath, outputDir });
+        const proc = spawn("java", args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            cwd: outputDir
+        });
+        let stderr = "";
+        const timer = setTimeout(() => {
+            proc.kill();
+            reject(createError({
+                code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
+                message: `Registry data generation timed out for version "${version}".`,
+                details: { version, timeoutMs: DATAGEN_TIMEOUT_MS, stderrTail: limitOutput(stderr) }
+            }));
+        }, DATAGEN_TIMEOUT_MS);
+        proc.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+            stderr = limitOutput(stderr);
+        });
+        proc.once("error", (error) => {
+            clearTimeout(timer);
+            reject(createError({
+                code: ERROR_CODES.JAVA_UNAVAILABLE,
+                message: "java command is not available for data generation.",
+                details: { error: error instanceof Error ? error.message : String(error) }
+            }));
+        });
+        proc.once("exit", (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(createError({
+                    code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
+                    message: `Data generation exited with code ${code} for version "${version}".`,
+                    details: { version, code, stderrTail: limitOutput(stderr) }
+                }));
+                return;
+            }
+            log("info", "registry.datagen.done", { version });
+            resolve();
+        });
+    });
+}
+/**
+ * MC versions before 1.18 use -cp instead of -jar bundler format for data gen.
+ * 1.18 snapshots start with "21w" (2021 weekly), release is "1.18".
+ */
+function isLegacyVersion(version) {
+    // Snapshot format: YYwNNa
+    const snapshotMatch = version.match(/^(\d{2})w(\d{2})[a-z]$/);
+    if (snapshotMatch) {
+        const year = Number(snapshotMatch[1]);
+        const week = Number(snapshotMatch[2]);
+        // 1.18 started in 21w37a
+        if (year < 21)
+            return true;
+        if (year === 21 && week < 37)
+            return true;
+        return false;
+    }
+    // Release format: 1.X or 1.X.Y
+    const releaseMatch = version.match(/^1\.(\d+)(?:\.\d+)?(?:-.*)?$/);
+    if (releaseMatch) {
+        return Number(releaseMatch[1]) < 18;
+    }
+    // New format (26.1+) is never legacy
+    return false;
+}
+export class RegistryService {
+    config;
+    versionService;
+    registryCache = new Map();
+    constructor(config, versionService) {
+        this.config = config;
+        this.versionService = versionService;
+    }
+    async getRegistryData(input) {
+        const version = input.version.trim();
+        if (!version) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "version must be non-empty."
+            });
+        }
+        const warnings = [];
+        const allRegistries = await this.loadRegistries(version, warnings);
+        const registryNames = Object.keys(allRegistries).sort();
+        if (input.registry) {
+            const registryName = normalizeRegistryName(input.registry);
+            const data = allRegistries[registryName];
+            if (!data) {
+                throw createError({
+                    code: ERROR_CODES.SOURCE_NOT_FOUND,
+                    message: `Registry "${registryName}" not found for version "${version}".`,
+                    details: {
+                        version,
+                        registry: registryName,
+                        available: registryNames.slice(0, 20)
+                    }
+                });
+            }
+            return {
+                version,
+                registry: registryName,
+                data,
+                entryCount: Object.keys(data.entries).length,
+                warnings
+            };
+        }
+        let totalEntries = 0;
+        for (const registry of Object.values(allRegistries)) {
+            totalEntries += Object.keys(registry.entries).length;
+        }
+        return {
+            version,
+            registries: registryNames,
+            data: allRegistries,
+            entryCount: totalEntries,
+            warnings
+        };
+    }
+    async loadRegistries(version, warnings) {
+        const cached = this.registryCache.get(version);
+        if (cached)
+            return cached;
+        const registryDir = join(this.config.cacheDir, "registries", version);
+        // Check if we already have generated data
+        let registryFile = findRegistryFile(registryDir);
+        if (!registryFile) {
+            await mkdir(registryDir, { recursive: true });
+            const serverJar = await this.versionService.resolveServerJar(version);
+            await runDataGen(serverJar.jarPath, registryDir, version);
+            registryFile = findRegistryFile(registryDir);
+            if (!registryFile) {
+                throw createError({
+                    code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
+                    message: `Registry data generation did not produce registries.json for version "${version}".`,
+                    details: { version, registryDir }
+                });
+            }
+        }
+        const raw = readFileSync(registryFile, "utf8");
+        const parsed = JSON.parse(raw);
+        // Validate structure
+        if (typeof parsed !== "object" || parsed === null) {
+            throw createError({
+                code: ERROR_CODES.REGISTRY_GENERATION_FAILED,
+                message: `registries.json for version "${version}" has invalid structure.`,
+                details: { version }
+            });
+        }
+        this.registryCache.set(version, parsed);
+        // Trim cache to avoid unbounded growth
+        if (this.registryCache.size > 8) {
+            const oldest = this.registryCache.keys().next().value;
+            if (oldest !== undefined)
+                this.registryCache.delete(oldest);
+        }
+        return parsed;
+    }
+}
+function normalizeRegistryName(name) {
+    const trimmed = name.trim();
+    if (trimmed.includes(":"))
+        return trimmed;
+    return `minecraft:${trimmed}`;
+}
+//# sourceMappingURL=registry-service.js.map

package/dist/repo-downloader.d.ts

@@ -0,0 +1,15 @@
+export interface DownloadResult {
+    ok: boolean;
+    statusCode?: number;
+    etag?: string;
+    lastModified?: string;
+    contentLength?: number;
+    path?: string;
+}
+export interface DownloadOptions {
+    timeoutMs?: number;
+    retries?: number;
+    fetchFn?: typeof fetch;
+}
+export declare function downloadToCache(url: string, destinationPath: string, opts?: DownloadOptions): Promise<DownloadResult>;
+export declare function defaultDownloadPath(cacheDir: string, url: string): string;

package/dist/repo-downloader.js

@@ -0,0 +1,111 @@
+import { createWriteStream, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createError, ERROR_CODES } from "./errors.js";
+function isHttpUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "http:" || parsed.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function retryDelay(baseMs, attempt) {
+    return Math.floor(baseMs * 2 ** attempt + Math.random() * 128);
+}
+export async function downloadToCache(url, destinationPath, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 15000;
+    const maxRetries = opts.retries ?? 2;
+    const fetchFn = opts.fetchFn ?? globalThis.fetch;
+    if (!isHttpUrl(url)) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Unsupported scheme for download URL: ${url}`,
+            details: { url }
+        });
+    }
+    mkdirSync(dirname(destinationPath), { recursive: true });
+    let attempt = 0;
+    while (true) {
+        const timeout = new AbortController();
+        const timer = setTimeout(() => timeout.abort(), timeoutMs);
+        try {
+            const response = await fetchFn(url, { signal: timeout.signal });
+            clearTimeout(timer);
+            const status = response.status;
+            if (status === 404) {
+                return { ok: false, statusCode: status };
+            }
+            if (status === 429 || (status >= 500 && status < 600)) {
+                if (attempt >= maxRetries) {
+                    return { ok: false, statusCode: status };
+                }
+                const retryAfter = Number.parseInt(response.headers.get("retry-after") ?? "", 10);
+                const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : retryDelay(200, attempt);
+                await sleep(waitMs);
+                attempt += 1;
+                continue;
+            }
+            if (!response.ok) {
+                return {
+                    ok: false,
+                    statusCode: status,
+                    etag: response.headers.get("etag") ?? undefined,
+                    lastModified: response.headers.get("last-modified") ?? undefined,
+                    contentLength: Number.parseInt(response.headers.get("content-length") ?? "0", 10)
+                };
+            }
+            const tempPath = `${destinationPath}.${randomBytes(4).toString("hex")}.tmp`;
+            try {
+                if (!response.body) {
+                    writeFileSync(tempPath, Buffer.alloc(0));
+                }
+                else {
+                    const readable = Readable.fromWeb(response.body);
+                    await pipeline(readable, createWriteStream(tempPath));
+                }
+                const contentLength = statSync(tempPath).size;
+                renameSync(tempPath, destinationPath);
+                return {
+                    ok: true,
+                    statusCode: status,
+                    etag: response.headers.get("etag") ?? undefined,
+                    lastModified: response.headers.get("last-modified") ?? undefined,
+                    contentLength,
+                    path: destinationPath
+                };
+            }
+            catch (streamError) {
+                try {
+                    unlinkSync(tempPath);
+                }
+                catch {
+                    // best-effort cleanup
+                }
+                throw streamError instanceof Error ? streamError : new Error(String(streamError));
+            }
+        }
+        catch (caughtError) {
+            clearTimeout(timer);
+            if (attempt >= maxRetries) {
+                throw caughtError instanceof Error ? caughtError : new Error(String(caughtError));
+            }
+            await sleep(retryDelay(200, attempt));
+            attempt += 1;
+        }
+    }
+}
+export function defaultDownloadPath(cacheDir, url) {
+    const filename = `${sha256(url)}.jar`;
+    return `${cacheDir}/downloads/${filename}`;
+}
+//# sourceMappingURL=repo-downloader.js.map

package/dist/resources.d.ts

@@ -0,0 +1,3 @@
+import type { MCPServer } from "mcp-use/server";
+import type { SourceService } from "./source-service.js";
+export declare function registerResources(server: InstanceType<typeof MCPServer>, sourceService: SourceService): void;