@lzimul/minecraft-mcp 1.0.4 → 1.0.6

package/build/tools/entity-tools.js

@@ -2,9 +2,10 @@ 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 { EMoveDirection } from '../enums/move-direction.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 { entityInfoSchema, entitySummarySchema, inventoryChangeSchema, inventoryViewSchema, itemStackSchema, toEntityInfo, toEntitySummary, 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';
@@ -13,13 +14,13 @@ const entityIdSchema = z
     .string()
     .trim()
     .min(1)
-    .max(128)
+    .max(WORLD_LIMITS.maxEntityIdLength)
     .describe('Entity UUID returned by createEntity or createPlayer');
 const targetSchema = z
     .string()
     .trim()
     .min(1)
-    .max(128)
+    .max(WORLD_LIMITS.maxEntityIdLength)
     .describe('Entity UUID or player name (player names are case-insensitive)');
 const playerNameSchema = z
     .string()
@@ -41,6 +42,45 @@ const itemIdSchema = z
     .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.');
+const entityPositionShape = {
+    x: z.number().int(),
+    y: z.number().int(),
+    z: z.number().int()
+};
+const entityPositionSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    name: z.string(),
+    ...entityPositionShape
+});
+const entityMovementSchema = entityPositionSchema.extend({
+    direction: z.enum(EMoveDirection),
+    previous: z.object(entityPositionShape)
+});
+const entityPositionChangeSchema = entityPositionSchema.extend({
+    previous: z.object(entityPositionShape)
+});
+const inventoryClearSchema = inventoryViewSchema.extend({
+    clearedSlots: z.number().int()
+});
+const inventorySwapSchema = inventoryViewSchema.extend({
+    fromSection: z.enum(EInventorySection),
+    fromSlot: z.number().int(),
+    toSection: z.enum(EInventorySection),
+    toSlot: z.number().int(),
+    previousFrom: itemStackSchema.nullable(),
+    previousTo: itemStackSchema.nullable()
+});
+function toEntityPosition(entity) {
+    return {
+        id: entity.id,
+        type: entity.type.key,
+        name: entity.name,
+        x: entity.x,
+        y: entity.y,
+        z: entity.z
+    };
+}
 function resolveEntityType(input) {
     const normalized = input.trim().toLowerCase();
     return (getEntityTypeByName(normalized) ??
@@ -50,6 +90,9 @@ function resolveTarget(world, target) {
     const normalized = target.trim();
     return world.findEntity(normalized) ?? world.findPlayer(normalized);
 }
+function unknownTargetError(target) {
+    return toolError(`Unknown entity or player "${target}". Use an entity UUID from createEntity/createPlayer or a player name.`);
+}
 function text(message) {
     return { type: 'text', text: message };
 }
@@ -214,6 +257,161 @@ export function registerEntityTools(server, world) {
             return toolError(`getPlayer failed: ${toErrorMessage(error)}`);
         }
     });
+    server.registerTool('deleteEntity', {
+        title: 'Delete Entity',
+        description: 'Delete one entity or player by UUID or player name. The entity is removed from its dimension and its inventory is discarded. Player names become available again after deletion.',
+        inputSchema: z.object({
+            target: targetSchema
+        }),
+        outputSchema: entitySummarySchema,
+        annotations: {
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false
+        }
+    }, async ({ target }) => {
+        try {
+            const entity = resolveTarget(world, target);
+            if (!entity) {
+                return unknownTargetError(target);
+            }
+            const dimension = world.getDimension(entity.dimension);
+            const deleted = dimension.deleteEntity(entity.id) ?? entity;
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`Entity "${deleted.name}" was deleted but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            return {
+                content: [
+                    text(`Deleted ${deleted.kind} "${deleted.name}" (${deleted.id}, ${deleted.type.key}) from ${dimension.info.displayName}`)
+                ],
+                structuredContent: toEntitySummary(deleted)
+            };
+        }
+        catch (error) {
+            return toolError(`deleteEntity failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('moveEntity', {
+        title: 'Move Entity',
+        description: 'Move one entity or player exactly one block in a fixed direction: forward (+Z, south), back (-Z, north), left (-X, west), right (+X, east), up (+Y) or down (-Y). The destination must stay inside the entity dimension.',
+        inputSchema: z.object({
+            id: entityIdSchema,
+            direction: z
+                .enum(EMoveDirection)
+                .describe('One-block direction: forward (+Z), back (-Z), left (-X), right (+X), up (+Y), down (-Y)')
+        }),
+        outputSchema: entityMovementSchema,
+        annotations: {
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false
+        }
+    }, async ({ id, direction }) => {
+        try {
+            const entity = world.findEntity(id);
+            if (!entity) {
+                return toolError(`Unknown entity "${id}". Use an entity UUID returned by createEntity or createPlayer.`);
+            }
+            const dimension = world.getDimension(entity.dimension);
+            const { previous, entity: moved } = dimension.moveEntity(id, direction);
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`Entity "${moved.name}" was moved but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            return {
+                content: [
+                    text(`Moved ${moved.name} (${moved.id}) ${direction} from (${previous.x}, ${previous.y}, ${previous.z}) to (${moved.x}, ${moved.y}, ${moved.z}) in ${dimension.info.displayName}`)
+                ],
+                structuredContent: {
+                    ...toEntityPosition(moved),
+                    direction,
+                    previous
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`moveEntity failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('getEntityPosition', {
+        title: 'Get Entity Position',
+        description: 'Get the UUID, entity type, name and exact x/y/z position of one entity or player.',
+        inputSchema: z.object({
+            id: entityIdSchema
+        }),
+        outputSchema: entityPositionSchema,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ id }) => {
+        try {
+            const entity = world.findEntity(id);
+            if (!entity) {
+                return toolError(`Unknown entity "${id}". Use an entity UUID returned by createEntity or createPlayer.`);
+            }
+            const position = toEntityPosition(entity);
+            return {
+                content: [
+                    text(`${position.name} (${position.type}, ${position.id}) is at (${position.x}, ${position.y}, ${position.z})`)
+                ],
+                structuredContent: position
+            };
+        }
+        catch (error) {
+            return toolError(`getEntityPosition failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('setEntityPosition', {
+        title: 'Set Entity Position',
+        description: 'Set the exact x/y/z position of one entity or player. The position must stay inside the entity dimension.',
+        inputSchema: z.object({
+            id: entityIdSchema,
+            position: z.object(blockPositionShape)
+        }),
+        outputSchema: entityPositionChangeSchema,
+        annotations: {
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ id, position }) => {
+        try {
+            const entity = world.findEntity(id);
+            if (!entity) {
+                return toolError(`Unknown entity "${id}". Use an entity UUID returned by createEntity or createPlayer.`);
+            }
+            const dimension = world.getDimension(entity.dimension);
+            if (!dimension.contains(position.x, position.y, position.z)) {
+                return coordinateRangeError(dimension.info, position.x, position.y, position.z);
+            }
+            const { previous, entity: updated } = dimension.setEntityPosition(id, position.x, position.y, position.z);
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`Entity "${updated.name}" was moved but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            return {
+                content: [
+                    text(`Set ${updated.name} (${updated.id}) position from (${previous.x}, ${previous.y}, ${previous.z}) to (${updated.x}, ${updated.y}, ${updated.z}) in ${dimension.info.displayName}`)
+                ],
+                structuredContent: {
+                    ...toEntityPosition(updated),
+                    previous
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`setEntityPosition 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.',
@@ -230,7 +428,7 @@ export function registerEntityTools(server, world) {
         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.`);
+                return unknownTargetError(target);
             }
             const view = toInventoryView(entity);
             return {
@@ -244,6 +442,121 @@ export function registerEntityTools(server, world) {
             return toolError(`getInventory failed: ${toErrorMessage(error)}`);
         }
     });
+    server.registerTool('clearInventory', {
+        title: 'Clear Inventory',
+        description: 'Remove every item from the 9 hotbar slots and 27 backpack slots of one entity or player. The target is an entity UUID or a player name. The cleared slot count is returned.',
+        inputSchema: z.object({
+            target: targetSchema
+        }),
+        outputSchema: inventoryClearSchema,
+        annotations: {
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false
+        }
+    }, async ({ target }) => {
+        try {
+            const entity = resolveTarget(world, target);
+            if (!entity) {
+                return unknownTargetError(target);
+            }
+            const dimension = world.getDimension(entity.dimension);
+            const { clearedSlots, entity: updated } = dimension.clearInventory(entity.id);
+            if (clearedSlots > 0) {
+                try {
+                    await dimension.flush();
+                }
+                catch (error) {
+                    return toolError(`The inventory of "${updated.name}" was cleared but could not be persisted to the world store: ${toErrorMessage(error)}`);
+                }
+            }
+            return {
+                content: [
+                    text(clearedSlots > 0
+                        ? `Cleared ${clearedSlots} inventory slot(s) of "${updated.name}"`
+                        : `The inventory of "${updated.name}" was already empty`)
+                ],
+                structuredContent: {
+                    ...toInventoryView(updated),
+                    clearedSlots
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`clearInventory failed: ${toErrorMessage(error)}`);
+        }
+    });
+    server.registerTool('swapInventorySlots', {
+        title: 'Swap Inventory Slots',
+        description: 'Swap two inventory slots of one entity or player. section is "hotbar" (slots 0-8) or "inventory" (backpack, slots 0-26). Both slots may be in the same or different sections. The target is an entity UUID or a player name.',
+        inputSchema: z.object({
+            target: targetSchema,
+            fromSection: z
+                .enum(EInventorySection)
+                .describe('"hotbar" or "inventory" for the first slot'),
+            fromSlot: z
+                .number()
+                .int()
+                .min(0)
+                .max(INVENTORY_SLOT_COUNT - 1)
+                .describe('First slot index (hotbar 0-8, backpack 0-26)'),
+            toSection: z
+                .enum(EInventorySection)
+                .describe('"hotbar" or "inventory" for the second slot'),
+            toSlot: z
+                .number()
+                .int()
+                .min(0)
+                .max(INVENTORY_SLOT_COUNT - 1)
+                .describe('Second slot index (hotbar 0-8, backpack 0-26)')
+        }),
+        outputSchema: inventorySwapSchema,
+        annotations: {
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false
+        }
+    }, async ({ target, fromSection, fromSlot, toSection, toSlot }) => {
+        try {
+            const entity = resolveTarget(world, target);
+            if (!entity) {
+                return unknownTargetError(target);
+            }
+            const fromMax = slotCount(fromSection) - 1;
+            if (fromSlot > fromMax) {
+                return toolError(`Slot ${fromSlot} is out of range for the ${fromSection} section (0-${fromMax}).`);
+            }
+            const toMax = slotCount(toSection) - 1;
+            if (toSlot > toMax) {
+                return toolError(`Slot ${toSlot} is out of range for the ${toSection} section (0-${toMax}).`);
+            }
+            const dimension = world.getDimension(entity.dimension);
+            const { previousFrom, previousTo, entity: updated } = dimension.swapInventorySlots(entity.id, fromSection, fromSlot, toSection, toSlot);
+            try {
+                await dimension.flush();
+            }
+            catch (error) {
+                return toolError(`The inventory slots of "${updated.name}" were swapped but could not be persisted to the world store: ${toErrorMessage(error)}`);
+            }
+            return {
+                content: [
+                    text(`Swapped ${fromSection} slot ${fromSlot} with ${toSection} slot ${toSlot} of "${updated.name}"`)
+                ],
+                structuredContent: {
+                    ...toInventoryView(updated),
+                    fromSection,
+                    fromSlot,
+                    toSection,
+                    toSlot,
+                    previousFrom: previousFrom ? toItemStackInfo(previousFrom) : null,
+                    previousTo: previousTo ? toItemStackInfo(previousTo) : null
+                }
+            };
+        }
+        catch (error) {
+            return toolError(`swapInventorySlots 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.',
@@ -278,7 +591,7 @@ export function registerEntityTools(server, world) {
         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.`);
+                return unknownTargetError(target);
             }
             const maxSlot = slotCount(section) - 1;
             if (slot > maxSlot) {