@adhisang/minecraft-modding-mcp 1.0.0

package/dist/resources.js

@@ -0,0 +1,154 @@
+import { text, object, error } from "mcp-use/server";
+import { createError, ERROR_CODES, isAppError } from "./errors.js";
+function decodeTemplateParam(params, key) {
+    const value = params[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Missing template parameter: ${key}.`,
+            details: { key }
+        });
+    }
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `${key} contains invalid URL encoding.`,
+            details: { key, value }
+        });
+    }
+}
+export function registerResources(server, sourceService) {
+    // ── Fixed resources ──────────────────────────────────────────────
+    server.resource({
+        name: "versions-list",
+        uri: "mc://versions/list",
+        description: "List all available Minecraft versions with their metadata.",
+        mimeType: "application/json"
+    }, async () => {
+        try {
+            const result = await sourceService.listVersions();
+            return object(result);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return error(e.message);
+            throw e;
+        }
+    });
+    server.resource({
+        name: "runtime-metrics",
+        uri: "mc://metrics",
+        description: "Runtime metrics and performance counters for the MCP server.",
+        mimeType: "application/json"
+    }, async () => {
+        try {
+            const result = sourceService.getRuntimeMetrics();
+            return object(result);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return error(e.message);
+            throw e;
+        }
+    });
+    // ── Template resources ───────────────────────────────────────────
+    server.resourceTemplate({
+        name: "class-source",
+        uriTemplate: "mc://source/{artifactId}/{className}",
+        description: "Java source code for a class within a resolved artifact. className may use dot or slash separators.",
+        mimeType: "text/x-java"
+    }, async (_uri, params) => {
+        try {
+            const result = await sourceService.getClassSource({
+                artifactId: params.artifactId,
+                className: decodeTemplateParam(params, "className")
+            });
+            return text(result.sourceText);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return error(e.message);
+            throw e;
+        }
+    });
+    server.resourceTemplate({
+        name: "artifact-file",
+        uriTemplate: "mc://artifact/{artifactId}/files/{filePath}",
+        description: "Raw content of a file within a resolved artifact. filePath is the archive-relative path.",
+        mimeType: "text/plain"
+    }, async (_uri, params) => {
+        try {
+            const result = await sourceService.getArtifactFile({
+                artifactId: params.artifactId,
+                filePath: decodeTemplateParam(params, "filePath")
+            });
+            return text(result.content);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return error(e.message);
+            throw e;
+        }
+    });
+    server.resourceTemplate({
+        name: "find-mapping",
+        uriTemplate: "mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}",
+        description: "Look up a mapping for a class, field, or method between two naming namespaces.",
+        mimeType: "application/json"
+    }, async (_uri, params) => {
+        try {
+            const result = await sourceService.findMapping({
+                version: params.version,
+                kind: params.kind,
+                name: decodeTemplateParam(params, "name"),
+                sourceMapping: params.sourceMapping,
+                targetMapping: params.targetMapping
+            });
+            return object(result);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return error(e.message);
+            throw e;
+        }
+    });
+    server.resourceTemplate({
+        name: "class-members",
+        uriTemplate: "mc://artifact/{artifactId}/members/{className}",
+        description: "List constructors, methods, and fields for a class within a resolved artifact.",
+        mimeType: "application/json"
+    }, async (_uri, params) => {
+        try {
+            const result = await sourceService.getClassMembers({
+                artifactId: params.artifactId,
+                className: decodeTemplateParam(params, "className")
+            });
+            return object(result);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return error(e.message);
+            throw e;
+        }
+    });
+    server.resourceTemplate({
+        name: "artifact-metadata",
+        uriTemplate: "mc://artifact/{artifactId}",
+        description: "Metadata for a previously resolved artifact (origin, coordinate, mapping, provenance).",
+        mimeType: "application/json"
+    }, async (_uri, params) => {
+        try {
+            const artifact = sourceService.getArtifact(params.artifactId);
+            return object(artifact);
+        }
+        catch (e) {
+            if (isAppError(e))
+                return error(e.message);
+            throw e;
+        }
+    });
+}
+//# sourceMappingURL=resources.js.map

package/dist/search-hit-accumulator.d.ts

@@ -0,0 +1,38 @@
+export type SymbolKind = "class" | "interface" | "enum" | "record" | "method" | "field";
+export type SearchResultSymbol = {
+    symbolKind: SymbolKind;
+    symbolName: string;
+    qualifiedName?: string;
+    line: number;
+};
+export type SearchSourceHit = {
+    filePath: string;
+    score: number;
+    matchedIn: "symbol" | "path" | "content";
+    startLine: number;
+    endLine: number;
+    snippet: string;
+    reasonCodes: string[];
+    symbol?: SearchResultSymbol;
+};
+export interface SearchCursorPayload {
+    score: number;
+    filePath: string;
+    symbolName: string;
+    line: number;
+    contextKey?: string;
+}
+export interface SearchHitAccumulator {
+    add(hit: SearchSourceHit): void;
+    setTotalApproxOverride(count: number): void;
+    finalize(): {
+        page: SearchSourceHit[];
+        nextCursorHit?: SearchSourceHit;
+        totalApprox: number;
+    };
+}
+export declare function scoreHitOrder(left: SearchSourceHit, right: SearchSourceHit): number;
+export declare function encodeSearchCursor(hit: SearchSourceHit, contextKey?: string): string;
+export declare function decodeSearchCursor(cursor: string | undefined): SearchCursorPayload | undefined;
+export declare function isAfterSearchCursor(hit: SearchSourceHit, cursor: SearchCursorPayload): boolean;
+export declare function createSearchHitAccumulator(limit: number, cursor: SearchCursorPayload | undefined): SearchHitAccumulator;

package/dist/search-hit-accumulator.js

@@ -0,0 +1,153 @@
+export function scoreHitOrder(left, right) {
+    if (right.score !== left.score) {
+        return right.score - left.score;
+    }
+    const pathCompare = left.filePath.localeCompare(right.filePath);
+    if (pathCompare !== 0) {
+        return pathCompare;
+    }
+    const leftSymbol = left.symbol?.symbolName ?? "";
+    const rightSymbol = right.symbol?.symbolName ?? "";
+    const symbolCompare = leftSymbol.localeCompare(rightSymbol);
+    if (symbolCompare !== 0) {
+        return symbolCompare;
+    }
+    const leftLine = left.symbol?.line ?? left.startLine;
+    const rightLine = right.symbol?.line ?? right.startLine;
+    return leftLine - rightLine;
+}
+export function encodeSearchCursor(hit, contextKey) {
+    return Buffer.from(JSON.stringify({
+        score: hit.score,
+        filePath: hit.filePath,
+        symbolName: hit.symbol?.symbolName ?? "",
+        line: hit.symbol?.line ?? hit.startLine,
+        contextKey
+    }), "utf8").toString("base64");
+}
+export function decodeSearchCursor(cursor) {
+    if (!cursor) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64").toString("utf8"));
+        if (typeof parsed.score !== "number" ||
+            typeof parsed.filePath !== "string" ||
+            typeof parsed.symbolName !== "string" ||
+            typeof parsed.line !== "number" ||
+            (parsed.contextKey != null && typeof parsed.contextKey !== "string")) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isAfterSearchCursor(hit, cursor) {
+    if (hit.score < cursor.score) {
+        return true;
+    }
+    if (hit.score > cursor.score) {
+        return false;
+    }
+    const fileCompare = hit.filePath.localeCompare(cursor.filePath);
+    if (fileCompare > 0) {
+        return true;
+    }
+    if (fileCompare < 0) {
+        return false;
+    }
+    const hitSymbolName = hit.symbol?.symbolName ?? "";
+    const symbolCompare = hitSymbolName.localeCompare(cursor.symbolName);
+    if (symbolCompare > 0) {
+        return true;
+    }
+    if (symbolCompare < 0) {
+        return false;
+    }
+    const hitLine = hit.symbol?.line ?? hit.startLine;
+    return hitLine > cursor.line;
+}
+/**
+ * Binary min-heap that keeps the top-K highest-quality hits.
+ * The root is the worst (lowest-quality) item in the heap.
+ * Compare function: positive means `a` is worse than `b` (lower quality).
+ */
+function heapSiftDown(heap, index, size) {
+    while (true) {
+        let smallest = index;
+        const left = 2 * index + 1;
+        const right = 2 * index + 2;
+        if (left < size && scoreHitOrder(heap[left], heap[smallest]) > 0) {
+            smallest = left;
+        }
+        if (right < size && scoreHitOrder(heap[right], heap[smallest]) > 0) {
+            smallest = right;
+        }
+        if (smallest === index) {
+            break;
+        }
+        const temp = heap[index];
+        heap[index] = heap[smallest];
+        heap[smallest] = temp;
+        index = smallest;
+    }
+}
+function heapSiftUp(heap, index) {
+    while (index > 0) {
+        const parent = (index - 1) >> 1;
+        // Keep the worst item at the root: bubble up only when child is worse than parent.
+        if (scoreHitOrder(heap[index], heap[parent]) <= 0) {
+            break;
+        }
+        const temp = heap[index];
+        heap[index] = heap[parent];
+        heap[parent] = temp;
+        index = parent;
+    }
+}
+export function createSearchHitAccumulator(limit, cursor) {
+    const pageLimit = Math.max(1, limit);
+    const keepLimit = pageLimit + 1;
+    const heap = [];
+    let totalApprox = 0;
+    let totalApproxOverride = undefined;
+    let totalAfterCursor = 0;
+    return {
+        add(hit) {
+            totalApprox += 1;
+            if (cursor && !isAfterSearchCursor(hit, cursor)) {
+                return;
+            }
+            totalAfterCursor += 1;
+            if (heap.length < keepLimit) {
+                heap.push(hit);
+                heapSiftUp(heap, heap.length - 1);
+                return;
+            }
+            // heap[0] is the worst item in our top-K. If hit is worse or equal, discard.
+            if (scoreHitOrder(hit, heap[0]) >= 0) {
+                return;
+            }
+            // Replace root with new hit and restore heap property
+            heap[0] = hit;
+            heapSiftDown(heap, 0, heap.length);
+        },
+        setTotalApproxOverride(count) {
+            totalApproxOverride = Math.max(0, Math.trunc(count));
+        },
+        finalize() {
+            // Sort heap contents by scoreHitOrder (best first)
+            const sorted = heap.slice().sort(scoreHitOrder);
+            const page = sorted.slice(0, pageLimit);
+            const hasMore = totalAfterCursor > page.length;
+            return {
+                page,
+                nextCursorHit: hasMore && page.length > 0 ? page[page.length - 1] : undefined,
+                totalApprox: totalApproxOverride ?? totalApprox
+            };
+        }
+    };
+}
+//# sourceMappingURL=search-hit-accumulator.js.map

package/dist/source-jar-reader.d.ts

@@ -0,0 +1,13 @@
+export interface JavaEntryText {
+    filePath: string;
+    content: string;
+}
+export declare class EntryTooLargeError extends Error {
+    constructor(entryPath: string, jarPath: string, maxBytes: number);
+}
+export declare function listJarEntries(jarPath: string): Promise<string[]>;
+export declare function listJavaEntries(jarPath: string): Promise<string[]>;
+export declare function readJarEntryAsUtf8(jarPath: string, entryPath: string): Promise<string>;
+export declare function readJarEntryAsBuffer(jarPath: string, entryPath: string): Promise<Buffer>;
+export declare function iterateJavaEntriesAsUtf8(jarPath: string, maxBytes?: number): AsyncGenerator<JavaEntryText>;
+export declare function readAllJavaEntriesAsUtf8(jarPath: string, maxBytes?: number): Promise<JavaEntryText[]>;

package/dist/source-jar-reader.js

@@ -0,0 +1,216 @@
+import * as yauzl from "yauzl";
+import { createError, ERROR_CODES } from "./errors.js";
+import { log } from "./logger.js";
+import { isSecureJarEntryPath } from "./path-resolver.js";
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+function toErrorMessage(value) {
+    if (value instanceof Error) {
+        return value.message;
+    }
+    return String(value);
+}
+function openZipFile(jarPath) {
+    return new Promise((resolve, reject) => {
+        yauzl.open(jarPath, {
+            lazyEntries: true,
+            autoClose: false
+        }, (error, zipFile) => {
+            if (error || !zipFile) {
+                reject(new Error(`Failed to read jar "${jarPath}": ${toErrorMessage(error)}`));
+                return;
+            }
+            resolve(zipFile);
+        });
+    });
+}
+async function withZipFile(jarPath, action) {
+    const zipFile = await openZipFile(jarPath);
+    try {
+        return await action(zipFile);
+    }
+    finally {
+        zipFile.close();
+    }
+}
+function readNextEntry(zipFile) {
+    return new Promise((resolve, reject) => {
+        const onEntry = (entry) => {
+            cleanup();
+            resolve(entry);
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(undefined);
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const cleanup = () => {
+            zipFile.removeListener("entry", onEntry);
+            zipFile.removeListener("end", onEnd);
+            zipFile.removeListener("error", onError);
+        };
+        zipFile.once("entry", onEntry);
+        zipFile.once("end", onEnd);
+        zipFile.once("error", onError);
+        zipFile.readEntry();
+    });
+}
+export class EntryTooLargeError extends Error {
+    constructor(entryPath, jarPath, maxBytes) {
+        super(`Entry "${entryPath}" in "${jarPath}" exceeds size limit of ${maxBytes} bytes`);
+        this.name = "EntryTooLargeError";
+    }
+}
+function readEntryStream(zipFile, entry, jarPath, maxBytes) {
+    return new Promise((resolve, reject) => {
+        zipFile.openReadStream(entry, (error, stream) => {
+            if (error || !stream) {
+                reject(new Error(`Failed to read entry "${entry.fileName}" from "${jarPath}": ${toErrorMessage(error)}`));
+                return;
+            }
+            let settled = false;
+            let totalBytes = 0;
+            const chunks = [];
+            stream.on("data", (chunk) => {
+                if (settled)
+                    return;
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                totalBytes += buf.length;
+                if (maxBytes !== undefined && totalBytes > maxBytes) {
+                    settled = true;
+                    stream.destroy();
+                    reject(new EntryTooLargeError(entry.fileName, jarPath, maxBytes));
+                    return;
+                }
+                chunks.push(buf);
+            });
+            stream.once("error", (streamError) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new Error(`Failed to read entry "${entry.fileName}" from "${jarPath}": ${toErrorMessage(streamError)}`));
+            });
+            stream.once("end", () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(Buffer.concat(chunks));
+            });
+        });
+    });
+}
+function decodeUtf8OrThrow(contentBuffer, jarPath, entryPath) {
+    try {
+        return UTF8_DECODER.decode(contentBuffer);
+    }
+    catch {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Entry "${entryPath.replaceAll("\\", "/")}" in "${jarPath}" is not valid UTF-8. Only UTF-8 source files are supported.`,
+            details: { jarPath, entryPath: entryPath.replaceAll("\\", "/") }
+        });
+    }
+}
+export async function listJarEntries(jarPath) {
+    return withZipFile(jarPath, async (zipFile) => {
+        const entries = [];
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                break;
+            }
+            entries.push(entry.fileName);
+        }
+        return entries;
+    });
+}
+export async function listJavaEntries(jarPath) {
+    const entries = await listJarEntries(jarPath);
+    return entries.filter((entry) => entry.toLowerCase().endsWith(".java") && isSecureJarEntryPath(entry));
+}
+export async function readJarEntryAsUtf8(jarPath, entryPath) {
+    const contentBuffer = await readJarEntryAsBuffer(jarPath, entryPath);
+    return decodeUtf8OrThrow(contentBuffer, jarPath, entryPath);
+}
+export async function readJarEntryAsBuffer(jarPath, entryPath) {
+    const normalizedTargetPath = entryPath.replaceAll("\\", "/");
+    if (!isSecureJarEntryPath(normalizedTargetPath)) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Entry path "${normalizedTargetPath}" is not allowed.`,
+            details: { jarPath, entryPath: normalizedTargetPath }
+        });
+    }
+    return withZipFile(jarPath, async (zipFile) => {
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                throw createError({
+                    code: ERROR_CODES.SOURCE_NOT_FOUND,
+                    message: `Entry "${normalizedTargetPath}" was not found in "${jarPath}".`,
+                    details: { jarPath, entryPath: normalizedTargetPath }
+                });
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            if (entry.fileName !== normalizedTargetPath) {
+                continue;
+            }
+            return readEntryStream(zipFile, entry, jarPath);
+        }
+    });
+}
+export async function* iterateJavaEntriesAsUtf8(jarPath, maxBytes) {
+    const zipFile = await openZipFile(jarPath);
+    try {
+        while (true) {
+            const entry = await readNextEntry(zipFile);
+            if (!entry) {
+                break;
+            }
+            if (!entry.fileName.toLowerCase().endsWith(".java")) {
+                continue;
+            }
+            if (!isSecureJarEntryPath(entry.fileName)) {
+                continue;
+            }
+            let buf;
+            try {
+                buf = await readEntryStream(zipFile, entry, jarPath, maxBytes);
+            }
+            catch (err) {
+                if (err instanceof EntryTooLargeError) {
+                    log("warn", "source_jar.entry_too_large", {
+                        jarPath,
+                        entryPath: entry.fileName,
+                        maxBytes
+                    });
+                    continue;
+                }
+                throw err;
+            }
+            const content = decodeUtf8OrThrow(buf, jarPath, entry.fileName);
+            yield {
+                filePath: entry.fileName,
+                content
+            };
+        }
+    }
+    finally {
+        zipFile.close();
+    }
+}
+export async function readAllJavaEntriesAsUtf8(jarPath, maxBytes) {
+    const entries = [];
+    for await (const entry of iterateJavaEntriesAsUtf8(jarPath, maxBytes)) {
+        entries.push({
+            filePath: entry.filePath,
+            content: entry.content
+        });
+    }
+    return entries;
+}
+//# sourceMappingURL=source-jar-reader.js.map

package/dist/source-resolver.d.ts

@@ -0,0 +1,14 @@
+import type { Config, ResolvedSourceArtifact, SourceTargetInput } from "./types.js";
+export interface ResolveSourceTargetOptions {
+    allowDecompile: boolean;
+    preferredRepos?: string[];
+    onRepoFailover?: (event: {
+        stage: "source" | "binary";
+        repoUrl: string;
+        statusCode?: number;
+        reason: string;
+        attempt: number;
+        totalAttempts: number;
+    }) => void;
+}
+export declare function resolveSourceTarget(input: SourceTargetInput, options: ResolveSourceTargetOptions, explicitConfig: Config): Promise<ResolvedSourceArtifact>;