@adhisang/minecraft-modding-mcp 1.0.0

package/dist/nbt/json-patch.js

@@ -0,0 +1,352 @@
+import { isDeepStrictEqual } from "node:util";
+import { createError, ERROR_CODES } from "../errors.js";
+import { assertValidTypedNbtDocument, validateTypedNbtDocument } from "./typed-json.js";
+function isRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !ArrayBuffer.isView(value));
+}
+function invalidPatch(message, details) {
+    throw createError({
+        code: ERROR_CODES.JSON_PATCH_INVALID,
+        message,
+        details
+    });
+}
+function unsupportedFeature(message, details) {
+    throw createError({
+        code: ERROR_CODES.NBT_UNSUPPORTED_FEATURE,
+        message,
+        details
+    });
+}
+function patchConflict(message, details) {
+    throw createError({
+        code: ERROR_CODES.JSON_PATCH_CONFLICT,
+        message,
+        details
+    });
+}
+function parsePatchOperations(patch) {
+    if (!Array.isArray(patch)) {
+        invalidPatch("JSON Patch must be an array.");
+    }
+    const normalized = [];
+    for (let i = 0; i < patch.length; i += 1) {
+        const rawOperation = patch[i];
+        if (!isRecord(rawOperation)) {
+            invalidPatch("JSON Patch operation must be an object.", { opIndex: i });
+        }
+        if (typeof rawOperation.op !== "string") {
+            invalidPatch('JSON Patch operation requires string field "op".', { opIndex: i });
+        }
+        if (typeof rawOperation.path !== "string") {
+            invalidPatch('JSON Patch operation requires string field "path".', { opIndex: i });
+        }
+        if (rawOperation.op === "move" || rawOperation.op === "copy") {
+            unsupportedFeature(`JSON Patch operation "${rawOperation.op}" is not supported in v1.`, {
+                opIndex: i,
+                op: rawOperation.op
+            });
+        }
+        if (rawOperation.op !== "add" &&
+            rawOperation.op !== "remove" &&
+            rawOperation.op !== "replace" &&
+            rawOperation.op !== "test") {
+            invalidPatch(`Unsupported JSON Patch operation "${rawOperation.op}".`, {
+                opIndex: i,
+                op: rawOperation.op
+            });
+        }
+        if ((rawOperation.op === "add" ||
+            rawOperation.op === "replace" ||
+            rawOperation.op === "test") &&
+            !("value" in rawOperation)) {
+            invalidPatch(`JSON Patch operation "${rawOperation.op}" requires "value".`, {
+                opIndex: i
+            });
+        }
+        normalized.push({
+            op: rawOperation.op,
+            path: rawOperation.path,
+            from: typeof rawOperation.from === "string" ? rawOperation.from : undefined,
+            value: rawOperation.value
+        });
+    }
+    return normalized;
+}
+function decodePointerToken(path, token, opIndex) {
+    if (/~(?:[^01]|$)/.test(token)) {
+        invalidPatch("Invalid JSON Pointer escape sequence.", {
+            opIndex,
+            path
+        });
+    }
+    return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function parsePointer(path, opIndex) {
+    if (path === "") {
+        return [];
+    }
+    if (!path.startsWith("/")) {
+        invalidPatch('JSON Pointer path must be empty or start with "/".', {
+            opIndex,
+            path
+        });
+    }
+    return path
+        .split("/")
+        .slice(1)
+        .map((token) => decodePointerToken(path, token, opIndex));
+}
+function hasOwn(target, key) {
+    return Object.prototype.hasOwnProperty.call(target, key);
+}
+function parseArrayIndex(token, length, options) {
+    if (token === "-") {
+        if (options.allowAppend) {
+            return length;
+        }
+        patchConflict('"-" is only allowed for add on arrays.', {
+            opIndex: options.opIndex,
+            jsonPointer: options.path
+        });
+    }
+    if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+        patchConflict("Invalid array index in JSON Pointer.", {
+            opIndex: options.opIndex,
+            jsonPointer: options.path
+        });
+    }
+    const index = Number.parseInt(token, 10);
+    if (options.allowAppend) {
+        if (index > length) {
+            patchConflict("Array add index is out of bounds.", {
+                opIndex: options.opIndex,
+                jsonPointer: options.path
+            });
+        }
+    }
+    else if (index >= length) {
+        patchConflict("Array index is out of bounds.", {
+            opIndex: options.opIndex,
+            jsonPointer: options.path
+        });
+    }
+    return index;
+}
+function resolveParent(root, tokens, opIndex, path) {
+    if (tokens.length === 0) {
+        patchConflict("Operation path does not reference a child location.", {
+            opIndex,
+            jsonPointer: path
+        });
+    }
+    let cursor = root;
+    for (let i = 0; i < tokens.length - 1; i += 1) {
+        const token = tokens[i];
+        const pointer = `/${tokens.slice(0, i + 1).join("/")}`;
+        if (Array.isArray(cursor)) {
+            const index = parseArrayIndex(token, cursor.length, {
+                allowAppend: false,
+                opIndex,
+                path: pointer
+            });
+            cursor = cursor[index];
+            continue;
+        }
+        if (!isRecord(cursor)) {
+            patchConflict("JSON Pointer traversed into a non-container value.", {
+                opIndex,
+                jsonPointer: pointer
+            });
+        }
+        if (!hasOwn(cursor, token)) {
+            patchConflict("JSON Pointer path does not exist.", {
+                opIndex,
+                jsonPointer: pointer
+            });
+        }
+        cursor = cursor[token];
+    }
+    return { parent: cursor, key: tokens[tokens.length - 1] };
+}
+function readValueAtPath(root, tokens, opIndex, path) {
+    if (tokens.length === 0) {
+        return root;
+    }
+    let cursor = root;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const pointer = `/${tokens.slice(0, i + 1).join("/")}`;
+        if (Array.isArray(cursor)) {
+            const index = parseArrayIndex(token, cursor.length, {
+                allowAppend: false,
+                opIndex,
+                path: pointer
+            });
+            cursor = cursor[index];
+            continue;
+        }
+        if (!isRecord(cursor)) {
+            patchConflict("JSON Pointer traversed into a non-container value.", {
+                opIndex,
+                jsonPointer: pointer
+            });
+        }
+        if (!hasOwn(cursor, token)) {
+            patchConflict("JSON Pointer path does not exist.", {
+                opIndex,
+                jsonPointer: pointer
+            });
+        }
+        cursor = cursor[token];
+    }
+    return cursor;
+}
+function assertTypedNbtInvariant(root, opIndex, path) {
+    const validation = validateTypedNbtDocument(root);
+    if (!validation.ok) {
+        patchConflict("JSON Patch operation produced invalid typed NBT JSON.", {
+            opIndex,
+            jsonPointer: validation.issue.jsonPointer,
+            expectedType: validation.issue.expectedType,
+            actualType: validation.issue.actualType,
+            path
+        });
+    }
+}
+export function applyJsonPatch(document, patch) {
+    assertValidTypedNbtDocument(document);
+    const operations = parsePatchOperations(patch);
+    let working = structuredClone(document);
+    let testOps = 0;
+    let changed = false;
+    for (let i = 0; i < operations.length; i += 1) {
+        const operation = operations[i];
+        const tokens = parsePointer(operation.path, i);
+        if (operation.op === "test") {
+            const actual = readValueAtPath(working, tokens, i, operation.path);
+            testOps += 1;
+            if (!isDeepStrictEqual(actual, operation.value)) {
+                patchConflict("JSON Patch test operation failed.", {
+                    opIndex: i,
+                    jsonPointer: operation.path,
+                    expectedType: typeof operation.value,
+                    actualType: typeof actual
+                });
+            }
+            continue;
+        }
+        if (operation.op === "add") {
+            const nextValue = structuredClone(operation.value);
+            if (tokens.length === 0) {
+                working = nextValue;
+            }
+            else {
+                const { parent, key } = resolveParent(working, tokens, i, operation.path);
+                if (Array.isArray(parent)) {
+                    const index = parseArrayIndex(key, parent.length, {
+                        allowAppend: true,
+                        opIndex: i,
+                        path: operation.path
+                    });
+                    parent.splice(index, 0, nextValue);
+                }
+                else if (isRecord(parent)) {
+                    parent[key] = nextValue;
+                }
+                else {
+                    patchConflict("Add target parent is not a container.", {
+                        opIndex: i,
+                        jsonPointer: operation.path
+                    });
+                }
+            }
+            changed = true;
+            assertTypedNbtInvariant(working, i, operation.path);
+            continue;
+        }
+        if (operation.op === "remove") {
+            if (tokens.length === 0) {
+                patchConflict("Cannot remove the typed NBT document root.", {
+                    opIndex: i,
+                    jsonPointer: operation.path
+                });
+            }
+            const { parent, key } = resolveParent(working, tokens, i, operation.path);
+            if (Array.isArray(parent)) {
+                const index = parseArrayIndex(key, parent.length, {
+                    allowAppend: false,
+                    opIndex: i,
+                    path: operation.path
+                });
+                parent.splice(index, 1);
+            }
+            else if (isRecord(parent)) {
+                if (!hasOwn(parent, key)) {
+                    patchConflict("Remove target path does not exist.", {
+                        opIndex: i,
+                        jsonPointer: operation.path
+                    });
+                }
+                delete parent[key];
+            }
+            else {
+                patchConflict("Remove target parent is not a container.", {
+                    opIndex: i,
+                    jsonPointer: operation.path
+                });
+            }
+            changed = true;
+            assertTypedNbtInvariant(working, i, operation.path);
+            continue;
+        }
+        if (operation.op === "replace") {
+            const nextValue = structuredClone(operation.value);
+            if (tokens.length === 0) {
+                working = nextValue;
+            }
+            else {
+                const { parent, key } = resolveParent(working, tokens, i, operation.path);
+                if (Array.isArray(parent)) {
+                    const index = parseArrayIndex(key, parent.length, {
+                        allowAppend: false,
+                        opIndex: i,
+                        path: operation.path
+                    });
+                    parent[index] = nextValue;
+                }
+                else if (isRecord(parent)) {
+                    if (!hasOwn(parent, key)) {
+                        patchConflict("Replace target path does not exist.", {
+                            opIndex: i,
+                            jsonPointer: operation.path
+                        });
+                    }
+                    parent[key] = nextValue;
+                }
+                else {
+                    patchConflict("Replace target parent is not a container.", {
+                        opIndex: i,
+                        jsonPointer: operation.path
+                    });
+                }
+            }
+            changed = true;
+            assertTypedNbtInvariant(working, i, operation.path);
+            continue;
+        }
+    }
+    assertValidTypedNbtDocument(working);
+    return {
+        typedJson: working,
+        meta: {
+            appliedOps: operations.length,
+            testOps,
+            changed
+        }
+    };
+}
+//# sourceMappingURL=json-patch.js.map

package/dist/nbt/pipeline.d.ts

@@ -0,0 +1,39 @@
+import { type TypedNbtDocument } from "./typed-json.js";
+import type { ApplyJsonPatchResult } from "./types.js";
+export type DecodeCompression = "none" | "gzip" | "auto";
+export type EncodeCompression = "none" | "gzip";
+export interface NbtLimits {
+    maxInputBytes: number;
+    maxInflatedBytes: number;
+    maxResponseBytes: number;
+}
+export declare const DEFAULT_NBT_LIMITS: NbtLimits;
+export interface NbtToJsonInput {
+    nbtBase64: string;
+    compression?: DecodeCompression;
+}
+export interface JsonToNbtInput {
+    typedJson: unknown;
+    compression?: EncodeCompression;
+}
+export interface ApplyPatchInput {
+    typedJson: unknown;
+    patch: unknown;
+}
+export interface NbtToJsonOutput {
+    typedJson: TypedNbtDocument;
+    meta: {
+        compressionDetected: "none" | "gzip";
+        inputBytes: number;
+    };
+}
+export interface JsonToNbtOutput {
+    nbtBase64: string;
+    meta: {
+        outputBytes: number;
+        compressionApplied: EncodeCompression;
+    };
+}
+export declare function nbtBase64ToTypedJson(input: NbtToJsonInput, limits?: NbtLimits): NbtToJsonOutput;
+export declare function typedJsonToNbtBase64(input: JsonToNbtInput, limits?: NbtLimits): JsonToNbtOutput;
+export declare function applyNbtJsonPatch(input: ApplyPatchInput, limits?: NbtLimits): ApplyJsonPatchResult;

package/dist/nbt/pipeline.js

@@ -0,0 +1,173 @@
+import { gunzipSync, gzipSync } from "node:zlib";
+import { createError, ERROR_CODES } from "../errors.js";
+import { decodeJavaNbt, encodeJavaNbt } from "./java-nbt-codec.js";
+import { applyJsonPatch } from "./json-patch.js";
+import { assertValidTypedNbtDocument } from "./typed-json.js";
+export const DEFAULT_NBT_LIMITS = {
+    maxInputBytes: 4 * 1024 * 1024,
+    maxInflatedBytes: 16 * 1024 * 1024,
+    maxResponseBytes: 8 * 1024 * 1024
+};
+function invalidInput(message, details) {
+    throw createError({
+        code: ERROR_CODES.INVALID_INPUT,
+        message,
+        details
+    });
+}
+function limitExceeded(stage, field, actual, limit) {
+    let message = "NBT payload exceeds configured size limit.";
+    let nextAction = "Reduce payload size or increase NBT limits.";
+    if (stage === "decode-input") {
+        message = "Decoded NBT payload exceeds max input bytes.";
+        nextAction = "Use smaller nbtBase64 input or increase MCP_MAX_NBT_INPUT_BYTES.";
+    }
+    else if (stage === "inflate") {
+        message = "Inflated gzip NBT payload exceeds max inflated bytes.";
+        nextAction = "Use smaller compressed payload or increase MCP_MAX_NBT_INFLATED_BYTES.";
+    }
+    else if (stage === "decode-output" || stage === "patch-output") {
+        message = "Typed NBT JSON response exceeds max response bytes.";
+        nextAction = "Reduce typedJson size or increase MCP_MAX_NBT_RESPONSE_BYTES.";
+    }
+    else if (stage === "encode-output") {
+        message = "NBT base64 response exceeds max response bytes.";
+        nextAction = "Reduce typedJson size or increase MCP_MAX_NBT_RESPONSE_BYTES.";
+    }
+    throw createError({
+        code: ERROR_CODES.LIMIT_EXCEEDED,
+        message,
+        details: {
+            stage,
+            field,
+            actual,
+            limit,
+            nextAction
+        }
+    });
+}
+function assertByteLimit(stage, field, actual, limit) {
+    if (actual > limit) {
+        limitExceeded(stage, field, actual, limit);
+    }
+}
+function jsonUtf8Bytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+function estimatedDecodedBase64Bytes(normalizedBase64) {
+    const paddingBytes = normalizedBase64.endsWith("==") ? 2 : normalizedBase64.endsWith("=") ? 1 : 0;
+    return (normalizedBase64.length / 4) * 3 - paddingBytes;
+}
+function isInflateLimitError(error) {
+    if (typeof error !== "object" || error == null) {
+        return false;
+    }
+    const maybeError = error;
+    if (maybeError.code === "ERR_BUFFER_TOO_LARGE") {
+        return true;
+    }
+    if (typeof maybeError.message !== "string") {
+        return false;
+    }
+    const normalizedMessage = maybeError.message.toLowerCase();
+    return normalizedMessage.includes("maxoutputlength") || normalizedMessage.includes("cannot create a buffer larger");
+}
+function inflateParseFailed(error) {
+    throw createError({
+        code: ERROR_CODES.NBT_PARSE_FAILED,
+        message: "Failed to inflate gzip NBT payload.",
+        details: {
+            reason: error instanceof Error ? error.message : String(error),
+            nextAction: "Provide valid gzip-compressed NBT data or set compression to none for uncompressed payloads."
+        }
+    });
+}
+function parseDecodeCompression(value) {
+    if (value === undefined) {
+        return "auto";
+    }
+    if (value === "none" || value === "gzip" || value === "auto") {
+        return value;
+    }
+    invalidInput('Field "compression" must be one of none|gzip|auto.');
+}
+function parseEncodeCompression(value) {
+    if (value === undefined) {
+        return "none";
+    }
+    if (value === "none" || value === "gzip") {
+        return value;
+    }
+    invalidInput('Field "compression" must be one of none|gzip.');
+}
+function decodeBase64Nbt(value, limits) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        invalidInput('Field "nbtBase64" must be a non-empty base64 string.');
+    }
+    const normalized = value.replace(/\s+/g, "");
+    if (normalized.length === 0 || normalized.length % 4 !== 0) {
+        invalidInput('Field "nbtBase64" is not valid base64.');
+    }
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {
+        invalidInput('Field "nbtBase64" is not valid base64.');
+    }
+    const estimatedDecodedBytes = estimatedDecodedBase64Bytes(normalized);
+    assertByteLimit("decode-input", "nbtBase64", estimatedDecodedBytes, limits.maxInputBytes);
+    const decoded = Buffer.from(normalized, "base64");
+    assertByteLimit("decode-input", "nbtBase64", decoded.length, limits.maxInputBytes);
+    return decoded;
+}
+function isGzipBuffer(buffer) {
+    return buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b;
+}
+export function nbtBase64ToTypedJson(input, limits = DEFAULT_NBT_LIMITS) {
+    const compression = parseDecodeCompression(input.compression);
+    const encoded = decodeBase64Nbt(input.nbtBase64, limits);
+    let payload = encoded;
+    let compressionDetected = "none";
+    if (compression === "gzip" || (compression === "auto" && isGzipBuffer(encoded))) {
+        try {
+            payload = gunzipSync(encoded, { maxOutputLength: limits.maxInflatedBytes });
+        }
+        catch (error) {
+            if (isInflateLimitError(error)) {
+                limitExceeded("inflate", "nbtBase64", limits.maxInflatedBytes + 1, limits.maxInflatedBytes);
+            }
+            inflateParseFailed(error);
+        }
+        compressionDetected = "gzip";
+    }
+    const typedJson = decodeJavaNbt(payload);
+    assertByteLimit("decode-output", "typedJson", jsonUtf8Bytes(typedJson), limits.maxResponseBytes);
+    return {
+        typedJson,
+        meta: {
+            compressionDetected,
+            inputBytes: encoded.length
+        }
+    };
+}
+export function typedJsonToNbtBase64(input, limits = DEFAULT_NBT_LIMITS) {
+    const compression = parseEncodeCompression(input.compression);
+    assertValidTypedNbtDocument(input.typedJson);
+    let output = encodeJavaNbt(input.typedJson);
+    if (compression === "gzip") {
+        output = gzipSync(output);
+    }
+    const nbtBase64 = output.toString("base64");
+    assertByteLimit("encode-output", "result", Buffer.byteLength(nbtBase64, "utf8"), limits.maxResponseBytes);
+    return {
+        nbtBase64,
+        meta: {
+            outputBytes: output.length,
+            compressionApplied: compression
+        }
+    };
+}
+export function applyNbtJsonPatch(input, limits = DEFAULT_NBT_LIMITS) {
+    assertValidTypedNbtDocument(input.typedJson);
+    const patched = applyJsonPatch(input.typedJson, input.patch);
+    assertByteLimit("patch-output", "typedJson", jsonUtf8Bytes(patched.typedJson), limits.maxResponseBytes);
+    return patched;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/nbt/typed-json.d.ts

@@ -0,0 +1,10 @@
+import type { TypedNbtDocument, TypedNbtValidationIssue } from "./types.js";
+type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    issue: TypedNbtValidationIssue;
+};
+export declare function validateTypedNbtDocument(value: unknown): ValidationResult;
+export declare function assertValidTypedNbtDocument(value: unknown): asserts value is TypedNbtDocument;
+export type { TypedNbtDocument, TypedNbtValidationIssue } from "./types.js";