@lzimul/minecraft-mcp 1.0.2 → 1.0.4

package/build/tools/entity-tools.js

@@ -0,0 +1,325 @@
+import * as z from 'zod/v4';
+import { WORLD_LIMITS } from '../config/world-limits.js';
+import { getEntityTypeByName } from '../data/entities.js';
+import { EInventorySection } from '../enums/inventory-section.enum.js';
+import { blockPositionShape } from '../schemas/coordinate-schema.js';
+import { dimensionField } from '../schemas/dimension-schema.js';
+import { entityInfoSchema, inventoryChangeSchema, inventoryViewSchema, toEntityInfo, toInventoryView, toItemStackInfo } from '../schemas/entity-schema.js';
+import { toErrorMessage } from '../utils/error-message.js';
+import { HOTBAR_SLOT_COUNT, INVENTORY_SLOT_COUNT, slotCount } from '../world/entity-inventory.js';
+import { parseItemSpec } from '../world/item-spec.js';
+import { coordinateRangeError, toolError } from './result.js';
+const entityIdSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .describe('Entity UUID returned by createEntity or createPlayer');
+const targetSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .describe('Entity UUID or player name (player names are case-insensitive)');
+const playerNameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(WORLD_LIMITS.maxPlayerNameLength)
+    .regex(/^[A-Za-z0-9_]+$/u, 'Player names may only contain letters, digits and underscores')
+    .describe('Unique player name (letters, digits and underscores)');
+const entityNameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(WORLD_LIMITS.maxEntityNameLength)
+    .optional()
+    .describe('Optional display name; defaults to the entity type display name');
+const itemIdSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .describe('Item id, such as "minecraft:diamond_sword" or "diamond_sword". Use "minecraft:air" or count 0 to clear the slot.');
+function resolveEntityType(input) {
+    const normalized = input.trim().toLowerCase();
+    return (getEntityTypeByName(normalized) ??
+        getEntityTypeByName(`minecraft:${normalized}`));
+}
+function resolveTarget(world, target) {
+    const normalized = target.trim();
+    return world.findEntity(normalized) ?? world.findPlayer(normalized);
+}
+function text(message) {
+    return { type: 'text', text: message };
+}
+export function registerEntityTools(server, world) {
+    server.registerTool('createEntity', {
+        title: 'Create Entity',
+        description: 'Create a non-player entity (mob, projectile, vehicle, etc.) in a dimension with an empty 9-slot hotbar and 27-slot backpack. Entity ids come from the generated registry; see the resource lzimul://minecraft/entities for the full list. Use createPlayer for players.',
+        inputSchema: z.object({
+            type: z
+                .string()
+                .trim()
+                .min(1)
+                .max(128)
+                .describe('Entity id, such as "minecraft:zombie" or "zombie"; see lzimul://minecraft/entities'),
+            ...blockPositionShape,
+            dimension: dimensionField,
+            name: entityNameSchema
+        }),
+        outputSchema: entityInfoSchema,
+        annotations: {
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false
+        }
+    }, async ({ type: typeId, x, y, z, dimension: dimensionType, name }) => {
+        try {
+            const type = resolveEntityType(typeId);
+            if (!type) {
+                return toolError(`Unknown entity type "${typeId}". Use an id such as "minecraft:zombie"; see the resource lzimul://minecraft/entities for the full list.`);
+            }
+            if (type.name === 'player') {
+                return toolError('The minecraft:player type cannot be created with createEntity. Use createPlayer instead.');
+            }
+            const dimension = world.getDimension(dimensionType);
+            if (!dimension.contains(x, y, z)) {
+                return coordinateRangeError(dimension.info, x, y, z);
+            }
+            if (!dimension.canAddEntity()) {
+                return toolError(`The ${dimension.info.displayName} world already holds the maximum of ${WORLD_LIMITS.maxEntitiesPerDimension} entities.`);
+            }
+            const entity = dimension.createEntity(type, name ?? type.displayName, x, y, z);
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`Entity ${type.key} "${entity.name}" was created at (${x}, ${y}, ${z}) in ${dimension.info.displayName} but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            return {
+                content: [
+                    text(`Created ${entity.type.displayName} "${entity.name}" (${entity.type.key}) with id ${entity.id} at (${x}, ${y}, ${z}) in ${dimension.info.displayName}`)
+                ],
+                structuredContent: toEntityInfo(entity)
+            };
+        }
+        catch (error) {
+            return toolError(`createEntity failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('getEntity', {
+        title: 'Get Entity',
+        description: 'Get an entity or player by UUID, including its type, position, dimension, creation time and full hotbar/backpack contents. Use getInventory or setInventory to change items.',
+        inputSchema: z.object({
+            id: entityIdSchema
+        }),
+        outputSchema: entityInfoSchema,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ id }) => {
+        try {
+            const entity = world.findEntity(id);
+            if (!entity) {
+                return toolError(`Unknown entity "${id}". Use the id returned by createEntity or createPlayer; use getPlayer for a player name.`);
+            }
+            const info = toEntityInfo(entity);
+            return {
+                content: [
+                    text(`${info.typeDisplayName} "${info.name}" (${info.type}, ${info.kind}) at (${info.x}, ${info.y}, ${info.z}) in ${info.dimension}; ${info.usedSlots}/${info.totalSlots} inventory slots used`)
+                ],
+                structuredContent: info
+            };
+        }
+        catch (error) {
+            return toolError(`getEntity failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('createPlayer', {
+        title: 'Create Player',
+        description: 'Create a uniquely named player in a dimension with an empty 9-slot hotbar and 27-slot backpack. Player names are case-insensitively unique across the whole world (all dimensions).',
+        inputSchema: z.object({
+            name: playerNameSchema,
+            ...blockPositionShape,
+            dimension: dimensionField
+        }),
+        outputSchema: entityInfoSchema,
+        annotations: {
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false
+        }
+    }, async ({ name, x, y, z, dimension: dimensionType }) => {
+        try {
+            const existing = world.findPlayer(name);
+            if (existing) {
+                const where = world.getDimension(existing.dimension).info.displayName;
+                return toolError(`A player named "${name}" already exists in ${where}. Player names are case-insensitive and unique across all dimensions.`);
+            }
+            const dimension = world.getDimension(dimensionType);
+            if (!dimension.contains(x, y, z)) {
+                return coordinateRangeError(dimension.info, x, y, z);
+            }
+            if (!dimension.canAddEntity()) {
+                return toolError(`The ${dimension.info.displayName} world already holds the maximum of ${WORLD_LIMITS.maxEntitiesPerDimension} entities.`);
+            }
+            const player = dimension.createPlayer(name, x, y, z);
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`Player "${name}" was created at (${x}, ${y}, ${z}) in ${dimension.info.displayName} but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            return {
+                content: [
+                    text(`Created player "${player.name}" with id ${player.id} at (${x}, ${y}, ${z}) in ${dimension.info.displayName}`)
+                ],
+                structuredContent: toEntityInfo(player)
+            };
+        }
+        catch (error) {
+            return toolError(`createPlayer failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('getPlayer', {
+        title: 'Get Player',
+        description: 'Get a player by name (case-insensitive), including position, dimension, creation time and full hotbar/backpack contents.',
+        inputSchema: z.object({
+            name: playerNameSchema
+        }),
+        outputSchema: entityInfoSchema,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ name }) => {
+        try {
+            const player = world.findPlayer(name);
+            if (!player) {
+                return toolError(`Unknown player "${name}". Player names are case-insensitive; use createPlayer to create one.`);
+            }
+            const info = toEntityInfo(player);
+            return {
+                content: [
+                    text(`Player "${info.name}" (${info.id}) at (${info.x}, ${info.y}, ${info.z}) in ${info.dimension}; ${info.usedSlots}/${info.totalSlots} inventory slots used`)
+                ],
+                structuredContent: info
+            };
+        }
+        catch (error) {
+            return toolError(`getPlayer failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('getInventory', {
+        title: 'Get Inventory',
+        description: 'Get the full inventory of an entity or player: the 9 hotbar slots and the 27 backpack slots, plus used-slot counts. Empty slots are null. The target is an entity UUID or a player name.',
+        inputSchema: z.object({
+            target: targetSchema
+        }),
+        outputSchema: inventoryViewSchema,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ target }) => {
+        try {
+            const entity = resolveTarget(world, target);
+            if (!entity) {
+                return toolError(`Unknown entity or player "${target}". Use an entity UUID from createEntity/createPlayer or a player name.`);
+            }
+            const view = toInventoryView(entity);
+            return {
+                content: [
+                    text(`${entity.name} (${entity.kind}, ${entity.type.key}): ${view.usedSlots}/${view.totalSlots} inventory slots used (hotbar ${view.hotbarUsed}/${HOTBAR_SLOT_COUNT}, backpack ${view.inventoryUsed}/${INVENTORY_SLOT_COUNT})`)
+                ],
+                structuredContent: view
+            };
+        }
+        catch (error) {
+            return toolError(`getInventory failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('setInventory', {
+        title: 'Set Inventory',
+        description: 'Set one inventory slot of an entity or player. section is "hotbar" (slots 0-8) or "inventory" (backpack, slots 0-26). The item is validated against the item registry and the count must fit the item stack size. Use "minecraft:air" or count 0 to clear a slot. The target is an entity UUID or a player name.',
+        inputSchema: z.object({
+            target: targetSchema,
+            section: z
+                .enum(EInventorySection)
+                .default(EInventorySection.Inventory)
+                .describe('"hotbar" for the 9 hotbar slots or "inventory" for the 27 backpack slots'),
+            slot: z
+                .number()
+                .int()
+                .min(0)
+                .max(INVENTORY_SLOT_COUNT - 1)
+                .describe('Slot index within the section (hotbar 0-8, backpack 0-26)'),
+            item: itemIdSchema,
+            count: z
+                .number()
+                .int()
+                .min(0)
+                .max(64)
+                .default(1)
+                .describe('Stack count (1 to the item stack size); 0 clears the slot')
+        }),
+        outputSchema: inventoryChangeSchema,
+        annotations: {
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ target, section, slot, item, count }) => {
+        try {
+            const entity = resolveTarget(world, target);
+            if (!entity) {
+                return toolError(`Unknown entity or player "${target}". Use an entity UUID from createEntity/createPlayer or a player name.`);
+            }
+            const maxSlot = slotCount(section) - 1;
+            if (slot > maxSlot) {
+                return toolError(`Slot ${slot} is out of range for the ${section} section (0-${maxSlot}).`);
+            }
+            const spec = parseItemSpec(item);
+            if (!spec.ok) {
+                return toolError(spec.error);
+            }
+            const isAir = spec.item.key === 'minecraft:air';
+            let stack = null;
+            if (!isAir && count > 0) {
+                if (count > spec.item.stackSize) {
+                    return toolError(`${spec.item.displayName} stacks up to ${spec.item.stackSize} per slot; received ${count}.`);
+                }
+                stack = { item: spec.item.key, count };
+            }
+            const dimension = world.getDimension(entity.dimension);
+            const { previous, entity: updated } = dimension.setInventorySlot(entity.id, section, slot, stack);
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`The ${section} slot ${slot} of "${updated.name}" was changed but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            const message = stack
+                ? `Set ${section} slot ${slot} of "${updated.name}" to ${spec.item.displayName} x${stack.count}`
+                : `Cleared ${section} slot ${slot} of "${updated.name}"`;
+            return {
+                content: [text(message)],
+                structuredContent: {
+                    ...toInventoryView(updated),
+                    section,
+                    slot,
+                    previous: previous ? toItemStackInfo(previous) : null,
+                    item: stack ? toItemStackInfo(stack) : null
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`setInventory failed: ${toErrorMessage(error)}`);
+        }
+    });
+}

package/build/tools/index.js

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

package/build/tools/result.js

@@ -1,11 +1,9 @@
-export function toolText(text) {
-    return {
-        content: [{ type: 'text', text }]
-    };
-}
 export function toolError(message) {
     return {
         isError: true,
         content: [{ type: 'text', text: message }]
     };
 }
+export function coordinateRangeError(dimension, x, y, z) {
+    return toolError(`Coordinates (${x}, ${y}, ${z}) are out of range in ${dimension.displayName} (Y: ${dimension.minY} to ${dimension.maxY - 1}).`);
+}

package/build/tools/world-tools.js

@@ -0,0 +1,139 @@
+import * as z from 'zod/v4';
+import { dimensionField } from '../schemas/dimension-schema.js';
+import { toErrorMessage } from '../utils/error-message.js';
+import { toolError } from './result.js';
+const blockStatesSchema = z.record(z.string(), z.string());
+export function registerWorldTools(server, world) {
+    server.registerTool('getDimension', {
+        title: 'Get Dimension',
+        description: 'Get metadata and live state for one simulated dimension: id, display name, height range, modified block count, entity count and player count. Dimensions are "overworld", "the_nether" and "the_end"; each has its own persisted world state.',
+        inputSchema: z.object({
+            dimension: dimensionField
+        }),
+        outputSchema: z.object({
+            key: z.string(),
+            type: z.string(),
+            displayName: z.string(),
+            minY: z.number().int(),
+            maxY: z.number().int(),
+            hasSkylight: z.boolean(),
+            modifiedBlockCount: z.number().int(),
+            entityCount: z.number().int(),
+            playerCount: z.number().int(),
+            blocksUri: z.string(),
+            dimensionsUri: z.string()
+        }),
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ dimension: dimensionType }) => {
+        try {
+            const dimension = world.getDimension(dimensionType);
+            const info = dimension.info;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `${info.displayName} (${info.key}): ${dimension.modifiedBlockCount} modified blocks, ${dimension.entityCount} entities, ${dimension.playerCount} players; Y ${info.minY} to ${info.maxY - 1}`
+                    }
+                ],
+                structuredContent: {
+                    key: info.key,
+                    type: info.type,
+                    displayName: info.displayName,
+                    minY: info.minY,
+                    maxY: info.maxY,
+                    hasSkylight: info.hasSkylight,
+                    modifiedBlockCount: dimension.modifiedBlockCount,
+                    entityCount: dimension.entityCount,
+                    playerCount: dimension.playerCount,
+                    blocksUri: `lzimul://minecraft/dimensions/${info.type}`,
+                    dimensionsUri: 'lzimul://minecraft/dimensions'
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`getDimension failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('getDimensionBlocks', {
+        title: 'Get Dimension Blocks',
+        description: 'List the placed (non-air) blocks of a dimension, sorted by coordinates. Results are paginated because a dimension can hold up to 250,000 modified blocks: use limit and offset to page through, and hasMore to continue. Unmodified coordinates are air and are not listed; use getBlock for a single coordinate. Each row contains x, y, z, block id, display name and block states.',
+        inputSchema: z.object({
+            dimension: dimensionField,
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(10_000)
+                .default(1_000)
+                .describe('Maximum number of blocks to return (1-10000, default 1000)'),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .default(0)
+                .describe('Number of blocks to skip, for pagination (default 0)')
+        }),
+        outputSchema: z.object({
+            dimension: z.string(),
+            displayName: z.string(),
+            total: z.number().int(),
+            offset: z.number().int(),
+            limit: z.number().int(),
+            returned: z.number().int(),
+            hasMore: z.boolean(),
+            blocks: z.array(z.object({
+                x: z.number().int(),
+                y: z.number().int(),
+                z: z.number().int(),
+                block: z.string(),
+                displayName: z.string(),
+                states: blockStatesSchema
+            }))
+        }),
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ dimension: dimensionType, limit, offset }) => {
+        try {
+            const dimension = world.getDimension(dimensionType);
+            const total = dimension.modifiedBlockCount;
+            const page = dimension.sortedPlacedBlocks.slice(offset, offset + limit);
+            const returned = page.length;
+            const hasMore = offset + returned < total;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Returned ${returned} of ${total} placed block(s) in ${dimension.info.displayName} (offset ${offset}, limit ${limit}${hasMore ? ', more available' : ''})`
+                    }
+                ],
+                structuredContent: {
+                    dimension: dimension.info.key,
+                    displayName: dimension.info.displayName,
+                    total,
+                    offset,
+                    limit,
+                    returned,
+                    hasMore,
+                    blocks: page.map(placed => ({
+                        x: placed.x,
+                        y: placed.y,
+                        z: placed.z,
+                        block: placed.block.key,
+                        displayName: placed.block.displayName,
+                        states: placed.states
+                    }))
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`getDimensionBlocks failed: ${toErrorMessage(error)}`);
+        }
+    });
+}

package/build/utils/logger.js

@@ -0,0 +1,53 @@
+import { format } from 'node:util';
+import { chalkStderr as chalk } from 'chalk';
+import log4js from 'log4js';
+const VALID_LOG_LEVELS = new Set([
+    'ALL',
+    'TRACE',
+    'DEBUG',
+    'INFO',
+    'WARN',
+    'ERROR',
+    'FATAL',
+    'OFF',
+    'MARK'
+]);
+const REQUESTED_LOG_LEVEL = process.env.MCP_LOG_LEVEL?.trim().toUpperCase();
+const LOG_LEVEL = REQUESTED_LOG_LEVEL && VALID_LOG_LEVELS.has(REQUESTED_LOG_LEVEL)
+    ? REQUESTED_LOG_LEVEL
+    : 'INFO';
+const LOGGER_CATEGORY = 'lzimul-minecraft-mcp';
+function chalkLayout(event) {
+    const line = `${event.startTime.toISOString()} [${event.level.levelStr}] ${event.categoryName} - ${format(...event.data)}`;
+    switch (event.level.levelStr) {
+        case 'FATAL':
+        case 'ERROR':
+            return chalk.red(line);
+        case 'WARN':
+            return chalk.yellow(line);
+        case 'INFO':
+            return chalk.green(line);
+        case 'DEBUG':
+            return chalk.cyan(line);
+        case 'TRACE':
+            return chalk.blue(line);
+        default:
+            return line;
+    }
+}
+log4js.addLayout('chalk', () => chalkLayout);
+log4js.configure({
+    appenders: {
+        stderr: {
+            type: 'stderr',
+            layout: { type: 'chalk' }
+        }
+    },
+    categories: {
+        default: {
+            appenders: ['stderr'],
+            level: LOG_LEVEL
+        }
+    }
+});
+export const logger = log4js.getLogger(LOGGER_CATEGORY);

package/build/world/block-spec.js

@@ -62,12 +62,12 @@ export function parseBlockSpec(input) {
                 };
             }
             states[propertyName] = propertyValue;
-        }
-        if (Object.keys(states).length > MAX_STATES) {
-            return {
-                ok: false,
-                error: `Too many block states in "${input}" (max ${MAX_STATES}).`
-            };
+            if (Object.keys(states).length > MAX_STATES) {
+                return {
+                    ok: false,
+                    error: `Too many block states in "${input}" (max ${MAX_STATES}).`
+                };
+            }
         }
     }
     return { ok: true, block, states: normalizeStates(states) };

package/build/world/block-states.js

@@ -17,8 +17,25 @@ export function isSafeStateValue(value) {
         normalized.length <= MAX_STATE_VALUE_LENGTH &&
         SAFE_STATE_VALUE.test(normalized));
 }
-export function normalizeStates(states) {
+export function compareStateNames(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+export function isEmptyStates(states) {
     if (!states) {
+        return true;
+    }
+    for (const key in states) {
+        if (Object.hasOwn(states, key)) {
+            return false;
+        }
+    }
+    return true;
+}
+export function normalizeStates(states) {
+    if (!states || isEmptyStates(states)) {
         return EMPTY_BLOCK_STATES;
     }
     const entries = Object.entries(states)
@@ -26,8 +43,10 @@ export function normalizeStates(states) {
         isSafeStateName(key) &&
         isSafeStateValue(value))
         .map(([key, value]) => [key.toLowerCase(), value.toLowerCase()])
-        .sort(([a], [b]) => a.localeCompare(b));
-    return Object.fromEntries(entries);
+        .sort(([a], [b]) => compareStateNames(a, b));
+    return entries.length === 0
+        ? EMPTY_BLOCK_STATES
+        : Object.fromEntries(entries);
 }
 export function sameStates(a, b) {
     const entries = Object.entries(a);
@@ -35,7 +54,7 @@ export function sameStates(a, b) {
         entries.every(([key, value]) => b[key] === value));
 }
 export function formatStates(states) {
-    const entries = Object.entries(states).sort(([a], [b]) => a.localeCompare(b));
+    const entries = Object.entries(states).sort(([a], [b]) => compareStateNames(a, b));
     if (entries.length === 0) {
         return '';
     }