@adhisang/minecraft-modding-mcp 2.0.0 → 3.0.0

package/dist/compat-stdio-transport.js

@@ -1,29 +1,14 @@
 import process from "node:process";
-import { JSONRPCMessageSchema } from "@modelcontextprotocol/sdk/types.js";
-function findHeaderBoundary(buffer) {
-    const crlfBoundary = buffer.indexOf("\r\n\r\n");
-    if (crlfBoundary !== -1) {
-        return { index: crlfBoundary, delimiterBytes: 4 };
-    }
-    const lfBoundary = buffer.indexOf("\n\n");
-    if (lfBoundary !== -1) {
-        return { index: lfBoundary, delimiterBytes: 2 };
-    }
-    return undefined;
-}
-function parseJsonRpcMessage(json) {
-    return JSONRPCMessageSchema.parse(JSON.parse(json));
-}
+import { JsonRpcFrameReader, encodeJsonRpcMessage } from "./json-rpc-framing.js";
 function asError(value) {
     return value instanceof Error ? value : new Error(String(value));
 }
 export class CompatStdioServerTransport {
     stdin;
     stdout;
+    frameReader = new JsonRpcFrameReader();
     started = false;
     closed = false;
-    mode = "unknown";
-    buffer = Buffer.alloc(0);
     onclose;
     onerror;
     onmessage;
@@ -43,10 +28,7 @@ export class CompatStdioServerTransport {
         this.stdin.resume();
     }
     async send(message) {
-        const json = JSON.stringify(message);
-        const frame = this.mode === "content-length"
-            ? `Content-Length: ${Buffer.byteLength(json, "utf8")}\r\n\r\n${json}`
-            : `${json}\n`;
+        const frame = encodeJsonRpcMessage(message, this.frameReader.currentMode === "content-length" ? "content-length" : "line");
         await new Promise((resolve) => {
             if (this.stdout.write(frame)) {
                 resolve();
@@ -63,15 +45,18 @@ export class CompatStdioServerTransport {
         if (this.stdin.listenerCount("data") === 0) {
             this.stdin.pause();
         }
-        this.buffer = Buffer.alloc(0);
+        this.frameReader.clear();
         this.emitCloseOnce();
     }
     handleData = (chunk) => {
-        if (chunk.length === 0) {
-            return;
-        }
-        this.buffer = Buffer.concat([this.buffer, chunk]);
-        this.processReadBuffer();
+        this.frameReader.processChunk(chunk, {
+            onFrame: ({ message }) => {
+                this.onmessage?.(message);
+            },
+            onError: (error) => {
+                this.onerror?.(error);
+            }
+        });
     };
     handleStreamError = (error) => {
         this.onerror?.(error);
@@ -86,132 +71,5 @@ export class CompatStdioServerTransport {
         this.closed = true;
         this.onclose?.();
     }
-    processReadBuffer() {
-        while (true) {
-            try {
-                if (this.mode === "unknown") {
-                    const detected = this.detectMode();
-                    if (!detected) {
-                        return;
-                    }
-                    this.mode = detected;
-                    continue;
-                }
-                const modeBefore = this.mode;
-                const message = this.mode === "content-length"
-                    ? this.readContentLengthMessage()
-                    : this.readLineDelimitedMessage();
-                if (!message) {
-                    // readLineDelimitedMessage may switch mode to "content-length"
-                    // mid-stream; retry with the new parser instead of stopping.
-                    if (this.mode !== modeBefore) {
-                        continue;
-                    }
-                    return;
-                }
-                this.onmessage?.(message);
-            }
-            catch (caughtError) {
-                this.onerror?.(asError(caughtError));
-                this.mode = "unknown";
-            }
-        }
-    }
-    detectMode() {
-        // Skip blank leading lines that some clients may emit.
-        while (this.buffer.length > 0) {
-            if (this.buffer[0] === 0x0a) {
-                this.buffer = this.buffer.subarray(1);
-                continue;
-            }
-            if (this.buffer.length >= 2 && this.buffer[0] === 0x0d && this.buffer[1] === 0x0a) {
-                this.buffer = this.buffer.subarray(2);
-                continue;
-            }
-            break;
-        }
-        if (this.buffer.length === 0) {
-            return undefined;
-        }
-        const prefix = this.buffer
-            .subarray(0, Math.min(this.buffer.length, 32))
-            .toString("utf8")
-            .toLowerCase();
-        if (prefix.startsWith("content-length")) {
-            return "content-length";
-        }
-        const firstNewline = this.buffer.indexOf(0x0a);
-        if (firstNewline === -1) {
-            return undefined;
-        }
-        const firstLine = this.buffer.subarray(0, firstNewline).toString("utf8").replace(/\r$/, "");
-        if (/^\s*content-length\s*:/i.test(firstLine)) {
-            return "content-length";
-        }
-        return "line";
-    }
-    readLineDelimitedMessage() {
-        while (true) {
-            const newlineIndex = this.buffer.indexOf(0x0a);
-            if (newlineIndex === -1) {
-                return undefined;
-            }
-            const line = this.buffer.subarray(0, newlineIndex).toString("utf8").replace(/\r$/, "");
-            this.buffer = this.buffer.subarray(newlineIndex + 1);
-            if (line.trim().length === 0) {
-                continue;
-            }
-            if (/^\s*content-length\s*:/i.test(line)) {
-                // Reconstruct the header with the correct line ending so that
-                // findHeaderBoundary can locate \r\n\r\n or \n\n reliably.
-                const sep = this.buffer.length > 0 && this.buffer[0] === 0x0d ? "\r\n" : "\n";
-                this.buffer = Buffer.concat([Buffer.from(`${line}${sep}`, "utf8"), this.buffer]);
-                this.mode = "content-length";
-                return undefined;
-            }
-            return parseJsonRpcMessage(line);
-        }
-    }
-    readContentLengthMessage() {
-        const headerBoundary = findHeaderBoundary(this.buffer);
-        if (!headerBoundary) {
-            return undefined;
-        }
-        const headersRaw = this.buffer.subarray(0, headerBoundary.index).toString("utf8");
-        const headerLines = headersRaw
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0);
-        let contentLength;
-        for (const headerLine of headerLines) {
-            const separatorIndex = headerLine.indexOf(":");
-            if (separatorIndex === -1) {
-                this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
-                throw new Error(`Malformed header line: ${headerLine}`);
-            }
-            const headerName = headerLine.slice(0, separatorIndex).trim().toLowerCase();
-            const headerValue = headerLine.slice(separatorIndex + 1).trim();
-            if (headerName === "content-length") {
-                const parsed = Number.parseInt(headerValue, 10);
-                if (!Number.isFinite(parsed) || parsed < 0) {
-                    this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
-                    throw new Error(`Invalid Content-Length header value: ${headerValue}`);
-                }
-                contentLength = parsed;
-            }
-        }
-        if (contentLength === undefined) {
-            this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
-            throw new Error("Missing Content-Length header.");
-        }
-        const messageStart = headerBoundary.index + headerBoundary.delimiterBytes;
-        const frameEnd = messageStart + contentLength;
-        if (this.buffer.length < frameEnd) {
-            return undefined;
-        }
-        const body = this.buffer.subarray(messageStart, frameEnd).toString("utf8");
-        this.buffer = this.buffer.subarray(frameEnd);
-        return parseJsonRpcMessage(body);
-    }
 }
 //# sourceMappingURL=compat-stdio-transport.js.map

package/dist/entry-tools/analyze-mod-service.d.ts

@@ -0,0 +1,207 @@
+import type { AnalyzeModOptions, ModAnalysisResult } from "../mod-analyzer.js";
+import { z } from "zod";
+export declare const analyzeModShape: {
+    task: z.ZodEnum<["summary", "decompile", "search", "class-source", "remap"]>;
+    subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"jar">;
+        jarPath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "jar";
+        jarPath: string;
+    }, {
+        kind: "jar";
+        jarPath: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"class">;
+        jarPath: z.ZodString;
+        className: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "class";
+        jarPath: string;
+        className: string;
+    }, {
+        kind: "class";
+        jarPath: string;
+        className: string;
+    }>]>;
+    query: z.ZodOptional<z.ZodString>;
+    searchType: z.ZodOptional<z.ZodEnum<["class", "method", "field", "content", "all"]>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    includeFiles: z.ZodOptional<z.ZodBoolean>;
+    maxFiles: z.ZodOptional<z.ZodNumber>;
+    maxLines: z.ZodOptional<z.ZodNumber>;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    targetMapping: z.ZodOptional<z.ZodEnum<["yarn", "mojang"]>>;
+    outputJar: z.ZodOptional<z.ZodString>;
+    executionMode: z.ZodOptional<z.ZodEnum<["preview", "apply"]>>;
+    detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
+};
+export declare const analyzeModSchema: z.ZodEffects<z.ZodObject<{
+    task: z.ZodEnum<["summary", "decompile", "search", "class-source", "remap"]>;
+    subject: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"jar">;
+        jarPath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "jar";
+        jarPath: string;
+    }, {
+        kind: "jar";
+        jarPath: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"class">;
+        jarPath: z.ZodString;
+        className: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "class";
+        jarPath: string;
+        className: string;
+    }, {
+        kind: "class";
+        jarPath: string;
+        className: string;
+    }>]>;
+    query: z.ZodOptional<z.ZodString>;
+    searchType: z.ZodOptional<z.ZodEnum<["class", "method", "field", "content", "all"]>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    includeFiles: z.ZodOptional<z.ZodBoolean>;
+    maxFiles: z.ZodOptional<z.ZodNumber>;
+    maxLines: z.ZodOptional<z.ZodNumber>;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    targetMapping: z.ZodOptional<z.ZodEnum<["yarn", "mojang"]>>;
+    outputJar: z.ZodOptional<z.ZodString>;
+    executionMode: z.ZodOptional<z.ZodEnum<["preview", "apply"]>>;
+    detail: z.ZodOptional<z.ZodEnum<["summary", "standard", "full"]>>;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<[string, ...string[]]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    task: "search" | "remap" | "summary" | "class-source" | "decompile";
+    subject: {
+        kind: "jar";
+        jarPath: string;
+    } | {
+        kind: "class";
+        jarPath: string;
+        className: string;
+    };
+    limit?: number | undefined;
+    maxLines?: number | undefined;
+    maxChars?: number | undefined;
+    targetMapping?: "mojang" | "yarn" | undefined;
+    outputJar?: string | undefined;
+    query?: string | undefined;
+    searchType?: "class" | "method" | "field" | "all" | "content" | undefined;
+    detail?: "full" | "summary" | "standard" | undefined;
+    include?: string[] | undefined;
+    includeFiles?: boolean | undefined;
+    maxFiles?: number | undefined;
+    executionMode?: "preview" | "apply" | undefined;
+}, {
+    task: "search" | "remap" | "summary" | "class-source" | "decompile";
+    subject: {
+        kind: "jar";
+        jarPath: string;
+    } | {
+        kind: "class";
+        jarPath: string;
+        className: string;
+    };
+    limit?: number | undefined;
+    maxLines?: number | undefined;
+    maxChars?: number | undefined;
+    targetMapping?: "mojang" | "yarn" | undefined;
+    outputJar?: string | undefined;
+    query?: string | undefined;
+    searchType?: "class" | "method" | "field" | "all" | "content" | undefined;
+    detail?: "full" | "summary" | "standard" | undefined;
+    include?: string[] | undefined;
+    includeFiles?: boolean | undefined;
+    maxFiles?: number | undefined;
+    executionMode?: "preview" | "apply" | undefined;
+}>, {
+    task: "search" | "remap" | "summary" | "class-source" | "decompile";
+    subject: {
+        kind: "jar";
+        jarPath: string;
+    } | {
+        kind: "class";
+        jarPath: string;
+        className: string;
+    };
+    limit?: number | undefined;
+    maxLines?: number | undefined;
+    maxChars?: number | undefined;
+    targetMapping?: "mojang" | "yarn" | undefined;
+    outputJar?: string | undefined;
+    query?: string | undefined;
+    searchType?: "class" | "method" | "field" | "all" | "content" | undefined;
+    detail?: "full" | "summary" | "standard" | undefined;
+    include?: string[] | undefined;
+    includeFiles?: boolean | undefined;
+    maxFiles?: number | undefined;
+    executionMode?: "preview" | "apply" | undefined;
+}, {
+    task: "search" | "remap" | "summary" | "class-source" | "decompile";
+    subject: {
+        kind: "jar";
+        jarPath: string;
+    } | {
+        kind: "class";
+        jarPath: string;
+        className: string;
+    };
+    limit?: number | undefined;
+    maxLines?: number | undefined;
+    maxChars?: number | undefined;
+    targetMapping?: "mojang" | "yarn" | undefined;
+    outputJar?: string | undefined;
+    query?: string | undefined;
+    searchType?: "class" | "method" | "field" | "all" | "content" | undefined;
+    detail?: "full" | "summary" | "standard" | undefined;
+    include?: string[] | undefined;
+    includeFiles?: boolean | undefined;
+    maxFiles?: number | undefined;
+    executionMode?: "preview" | "apply" | undefined;
+}>;
+export type AnalyzeModInput = z.infer<typeof analyzeModSchema>;
+type AnalyzeModDeps = {
+    analyzeModJar: (jarPath: string, options?: AnalyzeModOptions) => Promise<ModAnalysisResult>;
+    decompileModJar: (input: {
+        jarPath: string;
+        includeFiles?: boolean;
+        maxFiles?: number;
+    }) => Promise<Record<string, unknown> & {
+        warnings?: string[];
+    }>;
+    getModClassSource: (input: {
+        jarPath: string;
+        className: string;
+        maxLines?: number;
+        maxChars?: number;
+    }) => Promise<Record<string, unknown> & {
+        warnings?: string[];
+    }>;
+    searchModSource: (input: {
+        jarPath: string;
+        query: string;
+        searchType?: "class" | "method" | "field" | "content" | "all";
+        limit?: number;
+    }) => Promise<Record<string, unknown> & {
+        warnings?: string[];
+    }>;
+    remapModJar: (input: {
+        inputJar: string;
+        outputJar?: string;
+        mcVersion?: string;
+        targetMapping: "yarn" | "mojang";
+    }) => Promise<Record<string, unknown> & {
+        warnings?: string[];
+    }>;
+};
+export declare class AnalyzeModService {
+    private readonly deps;
+    constructor(deps: AnalyzeModDeps);
+    execute(input: AnalyzeModInput): Promise<Record<string, unknown> & {
+        warnings?: string[];
+    }>;
+}
+export {};

package/dist/entry-tools/analyze-mod-service.js

@@ -0,0 +1,253 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { normalizePathForHost } from "../path-converter.js";
+import { createError, ERROR_CODES } from "../errors.js";
+import { z } from "zod";
+import { buildIncludeSchema, detailSchema, executionModeSchema, positiveIntSchema } from "./entry-tool-schema.js";
+import { buildEntryToolResult } from "./response-contract.js";
+import { resolveDetail, resolveInclude } from "./request-normalizers.js";
+const nonEmptyString = z.string().trim().min(1);
+const INCLUDE_GROUPS = ["warnings", "files", "source", "samples", "timings"];
+const subjectSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("jar"),
+        jarPath: nonEmptyString
+    }),
+    z.object({
+        kind: z.literal("class"),
+        jarPath: nonEmptyString,
+        className: nonEmptyString
+    })
+]);
+export const analyzeModShape = {
+    task: z.enum(["summary", "decompile", "search", "class-source", "remap"]),
+    subject: subjectSchema,
+    query: nonEmptyString.optional(),
+    searchType: z.enum(["class", "method", "field", "content", "all"]).optional(),
+    limit: positiveIntSchema.optional(),
+    includeFiles: z.boolean().optional(),
+    maxFiles: positiveIntSchema.optional(),
+    maxLines: positiveIntSchema.optional(),
+    maxChars: positiveIntSchema.optional(),
+    targetMapping: z.enum(["yarn", "mojang"]).optional(),
+    outputJar: nonEmptyString.optional(),
+    executionMode: executionModeSchema.optional(),
+    detail: detailSchema.optional(),
+    include: buildIncludeSchema(INCLUDE_GROUPS)
+};
+export const analyzeModSchema = z.object(analyzeModShape).superRefine((value, ctx) => {
+    if ((value.task === "summary" || value.task === "decompile" || value.task === "search" || value.task === "remap") && value.subject.kind !== "jar") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["subject", "kind"],
+            message: `${value.task} requires subject.kind=jar.`
+        });
+    }
+    if (value.task === "class-source" && value.subject.kind !== "class") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["subject", "kind"],
+            message: "class-source requires subject.kind=class."
+        });
+    }
+    if (value.task === "search" && !value.query) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["query"],
+            message: "search requires query."
+        });
+    }
+    if (value.task === "remap" && !value.targetMapping) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["targetMapping"],
+            message: "remap requires targetMapping."
+        });
+    }
+});
+function deriveOutputJar(inputJar, analysis, targetMapping) {
+    return join(dirname(inputJar), `${analysis.modId ?? "mod"}-${analysis.modVersion ?? "0"}-${targetMapping}.jar`);
+}
+export class AnalyzeModService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const detail = resolveDetail(input.detail);
+        const include = resolveInclude(input.include);
+        switch (input.task) {
+            case "summary": {
+                const analysis = await this.deps.analyzeModJar(input.subject.jarPath, {
+                    includeClasses: detail !== "summary" || include.includes("files")
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "summary",
+                        detail,
+                        include,
+                        summary: {
+                            status: "ok",
+                            headline: `Summarized ${analysis.loader} mod metadata.`,
+                            counts: {
+                                classes: analysis.classCount,
+                                dependencies: analysis.dependencies?.length ?? 0
+                            }
+                        },
+                        blocks: {
+                            metadata: analysis
+                        }
+                    }),
+                    warnings: []
+                };
+            }
+            case "decompile": {
+                const output = await this.deps.decompileModJar({
+                    jarPath: input.subject.jarPath,
+                    includeFiles: input.includeFiles,
+                    maxFiles: input.maxFiles
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "decompile",
+                        detail,
+                        include,
+                        summary: {
+                            status: "ok",
+                            headline: `Decompiled ${input.subject.jarPath}.`
+                        },
+                        blocks: {
+                            decompile: output
+                        }
+                    }),
+                    warnings: Array.isArray(output.warnings) ? output.warnings : []
+                };
+            }
+            case "search": {
+                const output = await this.deps.searchModSource({
+                    jarPath: input.subject.jarPath,
+                    query: input.query,
+                    searchType: input.searchType,
+                    limit: input.limit
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "search",
+                        detail,
+                        include,
+                        summary: {
+                            status: "ok",
+                            headline: `Searched ${input.subject.jarPath} for ${input.query}.`
+                        },
+                        blocks: {
+                            hits: output
+                        }
+                    }),
+                    warnings: Array.isArray(output.warnings) ? output.warnings : []
+                };
+            }
+            case "class-source": {
+                if (input.subject.kind !== "class") {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "class-source requires subject.kind=class."
+                    });
+                }
+                const output = await this.deps.getModClassSource({
+                    jarPath: input.subject.jarPath,
+                    className: input.subject.className,
+                    maxLines: input.maxLines,
+                    maxChars: input.maxChars
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "class-source",
+                        detail,
+                        include,
+                        summary: {
+                            status: "ok",
+                            headline: `Loaded class source for ${input.subject.className}.`
+                        },
+                        blocks: {
+                            source: output
+                        }
+                    }),
+                    warnings: Array.isArray(output.warnings) ? output.warnings : []
+                };
+            }
+            case "remap": {
+                const normalizedInputJar = normalizePathForHost(input.subject.jarPath, undefined, "jarPath");
+                const analysis = await this.deps.analyzeModJar(normalizedInputJar);
+                const outputJar = input.outputJar
+                    ? normalizePathForHost(input.outputJar, undefined, "outputJar")
+                    : deriveOutputJar(normalizedInputJar, analysis, input.targetMapping);
+                if (outputJar === normalizedInputJar) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "outputJar must differ from the input jar."
+                    });
+                }
+                if ((input.executionMode ?? "preview") === "apply" && existsSync(outputJar)) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "outputJar already exists. Choose a new destination."
+                    });
+                }
+                if ((input.executionMode ?? "preview") === "preview") {
+                    return {
+                        ...buildEntryToolResult({
+                            task: "remap",
+                            detail,
+                            include,
+                            summary: {
+                                status: "unchanged",
+                                headline: `Previewed remap output for ${normalizedInputJar}.`
+                            },
+                            blocks: {
+                                metadata: {
+                                    loader: analysis.loader,
+                                    modId: analysis.modId,
+                                    modVersion: analysis.modVersion
+                                },
+                                operation: {
+                                    executionMode: "preview",
+                                    outputJar,
+                                    targetMapping: input.targetMapping
+                                }
+                            },
+                            alwaysBlocks: ["operation"]
+                        }),
+                        warnings: []
+                    };
+                }
+                const output = await this.deps.remapModJar({
+                    inputJar: normalizedInputJar,
+                    outputJar,
+                    targetMapping: input.targetMapping
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "remap",
+                        detail,
+                        include,
+                        summary: {
+                            status: "changed",
+                            headline: `Remapped ${normalizedInputJar} to ${input.targetMapping}.`
+                        },
+                        blocks: {
+                            operation: {
+                                executionMode: "apply",
+                                outputJar,
+                                targetMapping: input.targetMapping
+                            },
+                            metadata: output
+                        },
+                        alwaysBlocks: ["operation"]
+                    }),
+                    warnings: Array.isArray(output.warnings) ? output.warnings : []
+                };
+            }
+        }
+    }
+}
+//# sourceMappingURL=analyze-mod-service.js.map