@lzimul/minecraft-mcp 1.0.2 → 1.0.4

package/build/enums/entity-kind.enum.js

@@ -0,0 +1,5 @@
+export var EEntityKind;
+(function (EEntityKind) {
+    EEntityKind["Entity"] = "entity";
+    EEntityKind["Player"] = "player";
+})(EEntityKind || (EEntityKind = {}));

package/build/enums/inventory-section.enum.js

@@ -0,0 +1,5 @@
+export var EInventorySection;
+(function (EInventorySection) {
+    EInventorySection["Hotbar"] = "hotbar";
+    EInventorySection["Inventory"] = "inventory";
+})(EInventorySection || (EInventorySection = {}));

package/build/index.js

@@ -3,6 +3,7 @@ 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 { logger } from './utils/logger.js';
 import { createWorldStore } from './world/stores/index.js';
 import { World } from './world/world.js';
 async function main() {
@@ -19,14 +20,14 @@ async function main() {
             await world.flush();
         }
         catch (error) {
-            console.error(`[lzimul-minecraft-mcp] Failed to flush world state on shutdown: ${toErrorMessage(error)}`);
+            logger.error(`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)}`);
+            logger.error(`Failed to close the MCP transport: ${toErrorMessage(error)}`);
             code = 1;
         }
         process.exit(code);
@@ -42,6 +43,6 @@ try {
     await main();
 }
 catch (error) {
-    console.error(`[lzimul-minecraft-mcp] Fatal: ${toErrorMessage(error)}`);
+    logger.error(`Fatal: ${toErrorMessage(error)}`);
     process.exitCode = 1;
 }

package/build/interfaces/entity-inventory.interface.js

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

package/build/interfaces/entity-type.interface.js

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

package/build/interfaces/entity.interface.js

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

package/build/resources/dimension-resources.js

@@ -1,6 +1,22 @@
 import { toBlockInfo } from '../schemas/block-schema.js';
+import { toEntityInfo } from '../schemas/entity-schema.js';
 import { errorResource } from './error-content.js';
 import { World } from '../world/world.js';
+function dimensionSummary(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,
+        entityCount: simulated.entityCount,
+        playerCount: simulated.playerCount,
+        uri: `lzimul://minecraft/dimensions/${dimension.type}`
+    };
+}
 function dimensionState(world, dimension) {
     const simulated = world.getDimension(dimension.type);
     return {
@@ -11,21 +27,22 @@ function dimensionState(world, dimension) {
         maxY: dimension.maxY,
         hasSkylight: dimension.hasSkylight,
         modifiedBlockCount: simulated.modifiedBlockCount,
-        placedBlocks: simulated.placedBlocks
-            .map(placed => ({
+        entityCount: simulated.entityCount,
+        playerCount: simulated.playerCount,
+        placedBlocks: simulated.sortedPlacedBlocks.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)
+        })),
+        entities: simulated.sortedPlacedEntities.map(toEntityInfo)
     };
 }
 export function registerDimensionIndexResource(server, world) {
     server.registerResource('minecraft/dimensions', 'lzimul://minecraft/dimensions', {
         title: 'Minecraft Dimension List',
-        description: 'Index of the persisted Minecraft dimensions',
+        description: 'Index of the persisted Minecraft dimensions with their block counts (read the per-dimension resource for placed blocks)',
         mimeType: 'application/json'
     }, async (uri) => {
         try {
@@ -34,7 +51,7 @@ export function registerDimensionIndexResource(server, world) {
                     {
                         uri: uri.href,
                         mimeType: 'application/json',
-                        text: JSON.stringify(World.listDimensions().map(dimension => dimensionState(world, dimension)), null, 2)
+                        text: JSON.stringify(World.listDimensions().map(dimension => dimensionSummary(world, dimension)), null, 2)
                     }
                 ]
             };

package/build/resources/entity-resources.js

@@ -0,0 +1,17 @@
+import { MINECRAFT_ENTITY_COUNT, MINECRAFT_ENTITY_TYPES } from '../data/entities.js';
+import { MINECRAFT_DATA_VERSION } from '../data/version.js';
+import { registerDataEntryResources, registerDataIndexResource } from './data-resources.js';
+export function registerEntityResources(server) {
+    registerDataIndexResource(server, {
+        name: 'minecraft/entities',
+        uri: 'lzimul://minecraft/entities',
+        title: 'Minecraft Entity Type List',
+        description: `Index of all ${MINECRAFT_ENTITY_COUNT} Minecraft entity types (Java Edition ${MINECRAFT_DATA_VERSION})`,
+        entries: MINECRAFT_ENTITY_TYPES
+    });
+    registerDataEntryResources(server, {
+        pathPrefix: 'entities',
+        category: 'entity type',
+        entries: MINECRAFT_ENTITY_TYPES
+    });
+}

package/build/resources/index.js

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

package/build/schemas/coordinate-schema.js

@@ -10,3 +10,8 @@ export const verticalCoordinate = z
     .int()
     .min(WORLD_LIMITS.minVertical)
     .max(WORLD_LIMITS.maxVertical);
+export const blockPositionShape = {
+    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)')
+};

package/build/schemas/dimension-schema.js

@@ -4,3 +4,4 @@ export const dimensionSchema = z
     .enum(EDimensionType)
     .default(EDimensionType.Overworld);
 export const dimensionTypeSchema = z.enum(EDimensionType);
+export const dimensionField = dimensionSchema.describe('Dimension: "overworld" (default), "the_nether" or "the_end"');

package/build/schemas/entity-schema.js

@@ -0,0 +1,95 @@
+import * as z from 'zod/v4';
+import { EEntityKind } from '../enums/entity-kind.enum.js';
+import { EInventorySection } from '../enums/inventory-section.enum.js';
+import { HOTBAR_SLOT_COUNT, INVENTORY_SLOT_COUNT, inventoryUsedSlots, sectionUsedSlots, TOTAL_SLOT_COUNT } from '../world/entity-inventory.js';
+export const itemStackSchema = z.object({
+    item: z.string(),
+    count: z.number().int().min(1)
+});
+export const entityInventorySchema = z.object({
+    hotbar: z.array(itemStackSchema.nullable()),
+    inventory: z.array(itemStackSchema.nullable())
+});
+export const entitySummarySchema = z.object({
+    id: z.string(),
+    kind: z.enum(EEntityKind),
+    type: z.string(),
+    typeDisplayName: z.string(),
+    category: z.string(),
+    name: z.string(),
+    x: z.number(),
+    y: z.number(),
+    z: z.number(),
+    dimension: z.string()
+});
+export const entityInfoSchema = entitySummarySchema.extend({
+    createdAt: z.string(),
+    usedSlots: z.number().int(),
+    totalSlots: z.number().int(),
+    inventory: entityInventorySchema
+});
+export const inventoryViewSchema = z.object({
+    entity: entitySummarySchema,
+    hotbar: z.array(itemStackSchema.nullable()),
+    inventory: z.array(itemStackSchema.nullable()),
+    hotbarUsed: z.number().int(),
+    inventoryUsed: z.number().int(),
+    usedSlots: z.number().int(),
+    totalSlots: z.number().int()
+});
+export const inventoryChangeSchema = inventoryViewSchema.extend({
+    section: z.enum(EInventorySection),
+    slot: z.number().int(),
+    previous: itemStackSchema.nullable(),
+    item: itemStackSchema.nullable()
+});
+export function toItemStackInfo(stack) {
+    return { item: stack.item, count: stack.count };
+}
+function toNullableItemStackInfo(stack) {
+    return stack ? toItemStackInfo(stack) : null;
+}
+export function toEntityInventoryInfo(entity) {
+    return {
+        hotbar: entity.inventory.hotbar.map(toNullableItemStackInfo),
+        inventory: entity.inventory.inventory.map(toNullableItemStackInfo)
+    };
+}
+export function toEntitySummary(entity) {
+    return {
+        id: entity.id,
+        kind: entity.kind,
+        type: entity.type.key,
+        typeDisplayName: entity.type.displayName,
+        category: entity.type.category,
+        name: entity.name,
+        x: entity.x,
+        y: entity.y,
+        z: entity.z,
+        dimension: entity.dimension
+    };
+}
+export function toEntityInfo(entity) {
+    return {
+        ...toEntitySummary(entity),
+        createdAt: entity.createdAt,
+        usedSlots: inventoryUsedSlots(entity.inventory),
+        totalSlots: TOTAL_SLOT_COUNT,
+        inventory: toEntityInventoryInfo(entity)
+    };
+}
+export function toInventoryView(entity) {
+    return {
+        entity: toEntitySummary(entity),
+        hotbar: entity.inventory.hotbar.map(toNullableItemStackInfo),
+        inventory: entity.inventory.inventory.map(toNullableItemStackInfo),
+        hotbarUsed: sectionUsedSlots(entity.inventory, EInventorySection.Hotbar),
+        inventoryUsed: sectionUsedSlots(entity.inventory, EInventorySection.Inventory),
+        usedSlots: inventoryUsedSlots(entity.inventory),
+        totalSlots: TOTAL_SLOT_COUNT
+    };
+}
+export const INVENTORY_LIMITS = {
+    hotbar: HOTBAR_SLOT_COUNT,
+    inventory: INVENTORY_SLOT_COUNT
+};

package/build/tools/block-tools.js

@@ -1,25 +1,20 @@
 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 { blockPositionShape } from '../schemas/coordinate-schema.js';
+import { dimensionField } 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';
+import { coordinateRangeError, 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"')
+            ...blockPositionShape,
+            dimension: dimensionField
         }),
         outputSchema: z.object({
             x: z.number(),
@@ -38,10 +33,9 @@ export function registerBlockTools(server, world) {
         try {
             const dimension = world.getDimension(dimensionType);
             if (!dimension.contains(x, y, z)) {
-                return rangeError(dimension.info, x, y, z);
+                return coordinateRangeError(dimension.info, x, y, z);
             }
-            const block = dimension.getBlock(x, y, z);
-            const states = dimension.getStates(x, y, z);
+            const { block, states } = dimension.getBlockState(x, y, z);
             return {
                 content: [
                     {
@@ -67,15 +61,13 @@ export function registerBlockTools(server, world) {
         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)'),
+            ...blockPositionShape,
             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"')
+            dimension: dimensionField
         }),
         outputSchema: z.object({
             x: z.number(),
@@ -96,7 +88,7 @@ export function registerBlockTools(server, world) {
         try {
             const dimension = world.getDimension(dimensionType);
             if (!dimension.contains(x, y, z)) {
-                return rangeError(dimension.info, x, y, z);
+                return coordinateRangeError(dimension.info, x, y, z);
             }
             const spec = parseBlockSpec(blockType);
             if (!spec.ok) {
@@ -110,8 +102,7 @@ export function registerBlockTools(server, world) {
             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);
+            const previous = dimension.getBlockState(x, y, z);
             dimension.setBlock(x, y, z, spec.block, spec.states);
             try {
                 await dimension.flush();
@@ -123,7 +114,7 @@ export function registerBlockTools(server, world) {
                 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)}`
+                        text: `Block set at (${x}, ${y}, ${z}) in ${dimension.info.displayName}: ${previous.block.displayName} (${previous.block.key})${formatStates(previous.states)} -> ${spec.block.displayName} (${spec.block.key})${formatStates(spec.states)}`
                     }
                 ],
                 structuredContent: {
@@ -133,8 +124,8 @@ export function registerBlockTools(server, world) {
                     dimension: dimension.info.key,
                     block: toBlockInfo(spec.block),
                     states: spec.states,
-                    previous: toBlockInfo(previousBlock),
-                    previousStates
+                    previous: toBlockInfo(previous.block),
+                    previousStates: previous.states
                 }
             };
         }