@lzimul/minecraft-mcp 0.0.0-stage → 1.0.1

package/build/data/version.js

@@ -0,0 +1 @@
+export const MINECRAFT_DATA_VERSION = '26.1';

package/build/enums/bounding-box.enum.js

@@ -0,0 +1,5 @@
+export var EBoundingBox;
+(function (EBoundingBox) {
+    EBoundingBox["Empty"] = "empty";
+    EBoundingBox["Block"] = "block";
+})(EBoundingBox || (EBoundingBox = {}));

package/build/enums/dimension-type.enum.js

@@ -0,0 +1,6 @@
+export var EDimensionType;
+(function (EDimensionType) {
+    EDimensionType["Overworld"] = "overworld";
+    EDimensionType["TheNether"] = "the_nether";
+    EDimensionType["TheEnd"] = "the_end";
+})(EDimensionType || (EDimensionType = {}));

package/build/enums/icon-theme.enum.js

@@ -0,0 +1,5 @@
+export var EIconTheme;
+(function (EIconTheme) {
+    EIconTheme["Light"] = "light";
+    EIconTheme["Dark"] = "dark";
+})(EIconTheme || (EIconTheme = {}));

package/build/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { createServer } from './app/server.js';
+import { WORLD_STORAGE } from './config/storage.js';
+import { toErrorMessage } from './utils/error-message.js';
+import { createWorldStore } from './world/stores/index.js';
+import { World } from './world/world.js';
+async function main() {
+    const world = await World.load(createWorldStore(), WORLD_STORAGE.writeDelayMs);
+    const handle = serveStdio(() => createServer(world));
+    let shuttingDown = false;
+    const shutdown = async (exitCode) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        let code = exitCode;
+        try {
+            await world.flush();
+        }
+        catch (error) {
+            console.error(`[lzimul-minecraft-mcp] Failed to flush world state on shutdown: ${toErrorMessage(error)}`);
+            code = 1;
+        }
+        try {
+            await handle.close();
+        }
+        catch (error) {
+            console.error(`[lzimul-minecraft-mcp] Failed to close the MCP transport: ${toErrorMessage(error)}`);
+            code = 1;
+        }
+        process.exit(code);
+    };
+    process.once('SIGINT', () => {
+        void shutdown(0);
+    });
+    process.once('SIGTERM', () => {
+        void shutdown(0);
+    });
+}
+try {
+    await main();
+}
+catch (error) {
+    console.error(`[lzimul-minecraft-mcp] Fatal: ${toErrorMessage(error)}`);
+    process.exitCode = 1;
+}

package/build/interfaces/block-states.interface.js

@@ -0,0 +1 @@
+export {};

package/build/interfaces/block.interface.js

@@ -0,0 +1 @@
+import { EBoundingBox } from '../enums/bounding-box.enum.js';

package/build/interfaces/data-entry.interface.js

@@ -0,0 +1 @@
+export {};

package/build/interfaces/dimension.interface.js

@@ -0,0 +1 @@
+import { EDimensionType } from '../enums/dimension-type.enum.js';

package/build/interfaces/item.interface.js

@@ -0,0 +1 @@
+export {};

package/build/interfaces/placed-block.interface.js

@@ -0,0 +1 @@
+export {};

package/build/interfaces/world-store.interface.js

@@ -0,0 +1 @@
+export {};

package/build/resources/block-resources.js

@@ -0,0 +1,17 @@
+import { MINECRAFT_BLOCKS, MINECRAFT_BLOCK_COUNT } from '../data/blocks.js';
+import { MINECRAFT_DATA_VERSION } from '../data/version.js';
+import { registerDataEntryResources, registerDataIndexResource } from './data-resources.js';
+export function registerBlockResources(server) {
+    registerDataIndexResource(server, {
+        name: 'minecraft/blocks',
+        uri: 'lzimul://minecraft/blocks',
+        title: 'Minecraft Block List',
+        description: `Index of all ${MINECRAFT_BLOCK_COUNT} Minecraft blocks (Java Edition ${MINECRAFT_DATA_VERSION})`,
+        entries: MINECRAFT_BLOCKS
+    });
+    registerDataEntryResources(server, {
+        pathPrefix: 'blocks',
+        category: 'block',
+        entries: MINECRAFT_BLOCKS
+    });
+}

package/build/resources/data-resources.js

@@ -0,0 +1,55 @@
+import { errorResource } from './error-content.js';
+function lazyJsonText(build) {
+    let cached = '';
+    return () => {
+        if (!cached) {
+            cached = JSON.stringify(build(), null, 2);
+        }
+        return cached;
+    };
+}
+export function registerDataIndexResource(server, config) {
+    const getText = lazyJsonText(() => config.entries.map(entry => ({
+        id: entry.id,
+        key: entry.key,
+        name: entry.name,
+        displayName: entry.displayName
+    })));
+    server.registerResource(config.name, config.uri, {
+        title: config.title,
+        description: config.description,
+        mimeType: 'application/json'
+    }, async (uri) => {
+        try {
+            return {
+                contents: [
+                    { uri: uri.href, mimeType: 'application/json', text: getText() }
+                ]
+            };
+        }
+        catch (error) {
+            return errorResource(uri.href, error);
+        }
+    });
+}
+export function registerDataEntryResources(server, config) {
+    for (const entry of config.entries) {
+        const getText = lazyJsonText(() => entry);
+        server.registerResource(`minecraft/${config.pathPrefix}/${entry.name}`, `lzimul://minecraft/${config.pathPrefix}/${entry.name}`, {
+            title: `${entry.displayName} (${entry.key})`,
+            description: `Properties of the Minecraft ${config.category} ${entry.key}`,
+            mimeType: 'application/json'
+        }, async (uri) => {
+            try {
+                return {
+                    contents: [
+                        { uri: uri.href, mimeType: 'application/json', text: getText() }
+                    ]
+                };
+            }
+            catch (error) {
+                return errorResource(uri.href, error);
+            }
+        });
+    }
+}

package/build/resources/dimension-resources.js

@@ -0,0 +1,70 @@
+import { toBlockInfo } from '../schemas/block-schema.js';
+import { errorResource } from './error-content.js';
+import { World } from '../world/world.js';
+function dimensionState(world, dimension) {
+    const simulated = world.getDimension(dimension.type);
+    return {
+        key: dimension.key,
+        type: dimension.type,
+        displayName: dimension.displayName,
+        minY: dimension.minY,
+        maxY: dimension.maxY,
+        hasSkylight: dimension.hasSkylight,
+        modifiedBlockCount: simulated.modifiedBlockCount,
+        placedBlocks: simulated.placedBlocks
+            .map(placed => ({
+            x: placed.x,
+            y: placed.y,
+            z: placed.z,
+            block: toBlockInfo(placed.block),
+            states: placed.states
+        }))
+            .toSorted((a, b) => a.x - b.x || a.y - b.y || a.z - b.z)
+    };
+}
+export function registerDimensionIndexResource(server, world) {
+    server.registerResource('minecraft/dimensions', 'lzimul://minecraft/dimensions', {
+        title: 'Minecraft Dimension List',
+        description: 'Index of the persisted Minecraft dimensions',
+        mimeType: 'application/json'
+    }, async (uri) => {
+        try {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(World.listDimensions().map(dimension => dimensionState(world, dimension)), null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            return errorResource(uri.href, error);
+        }
+    });
+}
+export function registerDimensionResources(server, world) {
+    for (const dimension of World.listDimensions()) {
+        server.registerResource(`minecraft/dimensions/${dimension.type}`, `lzimul://minecraft/dimensions/${dimension.type}`, {
+            title: `${dimension.displayName} (${dimension.key})`,
+            description: `Persisted state of the ${dimension.displayName} dimension`,
+            mimeType: 'application/json'
+        }, async (uri) => {
+            try {
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            mimeType: 'application/json',
+                            text: JSON.stringify(dimensionState(world, dimension), null, 2)
+                        }
+                    ]
+                };
+            }
+            catch (error) {
+                return errorResource(uri.href, error);
+            }
+        });
+    }
+}

package/build/resources/error-content.js

@@ -0,0 +1,12 @@
+import { toErrorMessage } from '../utils/error-message.js';
+export function errorResource(uri, error) {
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: 'application/json',
+                text: JSON.stringify({ uri, error: toErrorMessage(error) }, null, 2)
+            }
+        ]
+    };
+}

package/build/resources/index.js

@@ -0,0 +1,9 @@
+import { registerBlockResources } from './block-resources.js';
+import { registerDimensionIndexResource, registerDimensionResources } from './dimension-resources.js';
+import { registerItemResources } from './item-resources.js';
+export function registerResources(server, world) {
+    registerBlockResources(server);
+    registerItemResources(server);
+    registerDimensionIndexResource(server, world);
+    registerDimensionResources(server, world);
+}

package/build/resources/item-resources.js

@@ -0,0 +1,17 @@
+import { MINECRAFT_ITEMS, MINECRAFT_ITEM_COUNT } from '../data/items.js';
+import { MINECRAFT_DATA_VERSION } from '../data/version.js';
+import { registerDataEntryResources, registerDataIndexResource } from './data-resources.js';
+export function registerItemResources(server) {
+    registerDataIndexResource(server, {
+        name: 'minecraft/items',
+        uri: 'lzimul://minecraft/items',
+        title: 'Minecraft Item List',
+        description: `Index of all ${MINECRAFT_ITEM_COUNT} Minecraft items (Java Edition ${MINECRAFT_DATA_VERSION})`,
+        entries: MINECRAFT_ITEMS
+    });
+    registerDataEntryResources(server, {
+        pathPrefix: 'items',
+        category: 'item',
+        entries: MINECRAFT_ITEMS
+    });
+}

package/build/schemas/block-schema.js

@@ -0,0 +1,27 @@
+import * as z from 'zod/v4';
+export const blockInfoSchema = z.object({
+    key: z.string(),
+    name: z.string(),
+    displayName: z.string(),
+    hardness: z.number(),
+    resistance: z.number(),
+    diggable: z.boolean(),
+    transparent: z.boolean(),
+    emitLight: z.number(),
+    filterLight: z.number(),
+    boundingBox: z.string()
+});
+export function toBlockInfo(block) {
+    return {
+        key: block.key,
+        name: block.name,
+        displayName: block.displayName,
+        hardness: block.hardness,
+        resistance: block.resistance,
+        diggable: block.diggable,
+        transparent: block.transparent,
+        emitLight: block.emitLight,
+        filterLight: block.filterLight,
+        boundingBox: block.boundingBox
+    };
+}

package/build/schemas/coordinate-schema.js

@@ -0,0 +1,12 @@
+import * as z from 'zod/v4';
+import { WORLD_LIMITS } from '../config/world-limits.js';
+export const horizontalCoordinate = z
+    .number()
+    .int()
+    .min(WORLD_LIMITS.minHorizontal)
+    .max(WORLD_LIMITS.maxHorizontal);
+export const verticalCoordinate = z
+    .number()
+    .int()
+    .min(WORLD_LIMITS.minVertical)
+    .max(WORLD_LIMITS.maxVertical);

package/build/schemas/dimension-schema.js

@@ -0,0 +1,6 @@
+import * as z from 'zod/v4';
+import { EDimensionType } from '../enums/dimension-type.enum.js';
+export const dimensionSchema = z
+    .enum(EDimensionType)
+    .default(EDimensionType.Overworld);
+export const dimensionTypeSchema = z.enum(EDimensionType);

package/build/schemas/item-schema.js

@@ -0,0 +1,28 @@
+import * as z from 'zod/v4';
+export const itemInfoSchema = z.object({
+    key: z.string(),
+    name: z.string(),
+    displayName: z.string(),
+    stackSize: z.number(),
+    maxDurability: z.number().optional(),
+    enchantCategories: z.array(z.string()).optional(),
+    repairWith: z.array(z.string()).optional()
+});
+export function toItemInfo(item) {
+    const info = {
+        key: item.key,
+        name: item.name,
+        displayName: item.displayName,
+        stackSize: item.stackSize
+    };
+    if (item.maxDurability) {
+        info.maxDurability = item.maxDurability;
+    }
+    if (item.enchantCategories) {
+        info.enchantCategories = [...item.enchantCategories];
+    }
+    if (item.repairWith) {
+        info.repairWith = [...item.repairWith];
+    }
+    return info;
+}

package/build/tools/block-tools.js

@@ -0,0 +1,145 @@
+import * as z from 'zod/v4';
+import { WORLD_LIMITS } from '../config/world-limits.js';
+import { blockInfoSchema, toBlockInfo } from '../schemas/block-schema.js';
+import { horizontalCoordinate, verticalCoordinate } from '../schemas/coordinate-schema.js';
+import { dimensionSchema } from '../schemas/dimension-schema.js';
+import { toErrorMessage } from '../utils/error-message.js';
+import { formatStates } from '../world/block-states.js';
+import { parseBlockSpec } from '../world/block-spec.js';
+import { toolError } from './result.js';
+const blockStatesSchema = z.record(z.string(), z.string());
+function rangeError(dimension, x, y, z) {
+    return toolError(`Coordinates (${x}, ${y}, ${z}) are out of range in ${dimension.displayName} (Y: ${dimension.minY} to ${dimension.maxY - 1}).`);
+}
+export function registerBlockTools(server, world) {
+    server.registerTool('getBlock', {
+        title: 'Get Block',
+        description: 'Get the block at the given coordinates in the given dimension, including its properties (name, hardness, light level, etc.) and its block states (for example facing=south). Each dimension has its own persisted world state; unmodified coordinates return air (minecraft:air).',
+        inputSchema: z.object({
+            x: horizontalCoordinate.describe('X coordinate (-30000000 to 30000000)'),
+            y: verticalCoordinate.describe('Y coordinate, within the dimension height range'),
+            z: horizontalCoordinate.describe('Z coordinate (-30000000 to 30000000)'),
+            dimension: dimensionSchema.describe('Dimension: "overworld" (default), "the_nether" or "the_end"')
+        }),
+        outputSchema: z.object({
+            x: z.number(),
+            y: z.number(),
+            z: z.number(),
+            dimension: z.string(),
+            block: blockInfoSchema,
+            states: blockStatesSchema
+        }),
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ x, y, z, dimension: dimensionType }) => {
+        try {
+            const dimension = world.getDimension(dimensionType);
+            if (!dimension.contains(x, y, z)) {
+                return rangeError(dimension.info, x, y, z);
+            }
+            const block = dimension.getBlock(x, y, z);
+            const states = dimension.getStates(x, y, z);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Block at (${x}, ${y}, ${z}) in ${dimension.info.displayName} is ${block.displayName} (${block.key})${formatStates(states)}`
+                    }
+                ],
+                structuredContent: {
+                    x,
+                    y,
+                    z,
+                    dimension: dimension.info.key,
+                    block: toBlockInfo(block),
+                    states
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`getBlock failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('setBlock', {
+        title: 'Set Block',
+        description: 'Place a block at the given coordinates in the given dimension and return the replaced block. Block states are supported: "minecraft:oak_stairs[facing=south,half=bottom]" or "oak_stairs[facing=south]". Each dimension has its own persisted world state; setting air removes the block. blockType is a block id such as "minecraft:stone" or "stone"; see the resource lzimul://minecraft/blocks for the full list.',
+        inputSchema: z.object({
+            x: horizontalCoordinate.describe('X coordinate (-30000000 to 30000000)'),
+            y: verticalCoordinate.describe('Y coordinate, within the dimension height range'),
+            z: horizontalCoordinate.describe('Z coordinate (-30000000 to 30000000)'),
+            blockType: z
+                .string()
+                .min(1)
+                .max(256)
+                .describe('Block id with optional states, such as "minecraft:stone" or "minecraft:oak_stairs[facing=south]"'),
+            dimension: dimensionSchema.describe('Dimension: "overworld" (default), "the_nether" or "the_end"')
+        }),
+        outputSchema: z.object({
+            x: z.number(),
+            y: z.number(),
+            z: z.number(),
+            dimension: z.string(),
+            block: blockInfoSchema,
+            states: blockStatesSchema,
+            previous: blockInfoSchema,
+            previousStates: blockStatesSchema
+        }),
+        annotations: {
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ x, y, z, blockType, dimension: dimensionType }) => {
+        try {
+            const dimension = world.getDimension(dimensionType);
+            if (!dimension.contains(x, y, z)) {
+                return rangeError(dimension.info, x, y, z);
+            }
+            const spec = parseBlockSpec(blockType);
+            if (!spec.ok) {
+                return toolError(spec.error);
+            }
+            const isAir = spec.block.key === 'minecraft:air';
+            const hasStates = Object.keys(spec.states).length > 0;
+            if (isAir && hasStates) {
+                return toolError('Air cannot carry block states. Use "minecraft:air" to remove a block.');
+            }
+            if (!isAir && !dimension.canSetBlock(x, y, z)) {
+                return toolError(`The ${dimension.info.displayName} world already holds the maximum of ${WORLD_LIMITS.maxModifiedBlocks} modified blocks. Remove blocks with "minecraft:air" before adding more.`);
+            }
+            const previousBlock = dimension.getBlock(x, y, z);
+            const previousStates = dimension.getStates(x, y, z);
+            dimension.setBlock(x, y, z, spec.block, spec.states);
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`Block ${spec.block.key} was applied at (${x}, ${y}, ${z}) in ${dimension.info.displayName} but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Block set at (${x}, ${y}, ${z}) in ${dimension.info.displayName}: ${previousBlock.displayName} (${previousBlock.key})${formatStates(previousStates)} -> ${spec.block.displayName} (${spec.block.key})${formatStates(spec.states)}`
+                    }
+                ],
+                structuredContent: {
+                    x,
+                    y,
+                    z,
+                    dimension: dimension.info.key,
+                    block: toBlockInfo(spec.block),
+                    states: spec.states,
+                    previous: toBlockInfo(previousBlock),
+                    previousStates
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`setBlock failed: ${toErrorMessage(error)}`);
+        }
+    });
+}

package/build/tools/index.js

@@ -0,0 +1,6 @@
+import { registerBlockTools } from './block-tools.js';
+import { registerItemTools } from './item-tools.js';
+export function registerTools(server, world) {
+    registerBlockTools(server, world);
+    registerItemTools(server);
+}

package/build/tools/item-tools.js

@@ -0,0 +1,50 @@
+import * as z from 'zod/v4';
+import { getItemByName } from '../data/items.js';
+import { itemInfoSchema, toItemInfo } from '../schemas/item-schema.js';
+import { toErrorMessage } from '../utils/error-message.js';
+import { toolError } from './result.js';
+export function registerItemTools(server) {
+    server.registerTool('getItem', {
+        title: 'Get Item',
+        description: 'Get the properties of a Minecraft item by id (stack size, durability, enchantment categories, etc.). See the resource lzimul://minecraft/items for the full list.',
+        inputSchema: z.object({
+            item: z
+                .string()
+                .min(1)
+                .max(256)
+                .describe('Item id, such as "minecraft:diamond_sword" or "diamond_sword"')
+        }),
+        outputSchema: z.object({
+            item: itemInfoSchema
+        }),
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ item: itemId }) => {
+        try {
+            const item = getItemByName(itemId.trim().toLowerCase());
+            if (!item) {
+                return toolError(`Unknown item "${itemId}". Use an item id such as "minecraft:diamond_sword"; see the resource lzimul://minecraft/items for the full list.`);
+            }
+            const durability = item.maxDurability
+                ? `, durability ${item.maxDurability}`
+                : '';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `${item.displayName} (${item.key}): stack size ${item.stackSize}${durability}`
+                    }
+                ],
+                structuredContent: {
+                    item: toItemInfo(item)
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`getItem failed: ${toErrorMessage(error)}`);
+        }
+    });
+}

package/build/tools/result.js

@@ -0,0 +1,11 @@
+export function toolText(text) {
+    return {
+        content: [{ type: 'text', text }]
+    };
+}
+export function toolError(message) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: message }]
+    };
+}

package/build/utils/error-message.js

@@ -0,0 +1,25 @@
+const FALLBACK_MESSAGE = 'Unknown error';
+export function toErrorMessage(error) {
+    if (error === null || error === void 0) {
+        return FALLBACK_MESSAGE;
+    }
+    if (error instanceof Error) {
+        const message = error.message.trim();
+        return message.length > 0 ? message : error.name || FALLBACK_MESSAGE;
+    }
+    if (typeof error === 'string') {
+        return error.trim() || FALLBACK_MESSAGE;
+    }
+    if (typeof error === 'object') {
+        try {
+            const serialized = JSON.stringify(error);
+            return typeof serialized === 'string' && serialized !== '{}'
+                ? serialized
+                : FALLBACK_MESSAGE;
+        }
+        catch {
+            return FALLBACK_MESSAGE;
+        }
+    }
+    return String(error) || FALLBACK_MESSAGE;
+}