@lzimul/minecraft-mcp 1.0.4 → 1.0.6

package/build/app/server.js

@@ -2,8 +2,13 @@ import { McpServer } from '@modelcontextprotocol/server';
 import { SERVER_INFO } from '../config/server-info.js';
 import { registerResources } from '../resources/index.js';
 import { registerTools } from '../tools/index.js';
-export function createServer(world) {
+import { instrumentToolCalls } from './tool-events.js';
+export function createServer(world, options) {
     const server = new McpServer(SERVER_INFO);
+    const onToolCall = options?.onToolCall;
+    if (onToolCall) {
+        instrumentToolCalls(server, onToolCall);
+    }
     registerTools(server, world);
     registerResources(server, world);
     return server;

package/build/app/tool-events.js

@@ -0,0 +1,72 @@
+import { toErrorMessage } from '../utils/error-message.js';
+import { logger } from '../utils/logger.js';
+function readIsError(result) {
+    if (typeof result !== 'object' || result === null) {
+        return false;
+    }
+    return result.isError === true;
+}
+function extractErrorMessage(result) {
+    if (typeof result !== 'object' || result === null) {
+        return 'Tool call failed';
+    }
+    const content = result.content;
+    if (Array.isArray(content)) {
+        const first = content.find((entry) => typeof entry === 'object' &&
+            entry !== null &&
+            entry.type === 'text' &&
+            typeof entry.text === 'string');
+        if (first) {
+            return first.text;
+        }
+    }
+    return 'Tool call failed';
+}
+function safeNotify(listener, event) {
+    try {
+        listener(event);
+    }
+    catch (error) {
+        logger.warn(`Tool-call listener failed: ${toErrorMessage(error)}`);
+    }
+}
+export function instrumentToolCalls(server, listener) {
+    const host = server;
+    const original = host.registerTool.bind(server);
+    host.registerTool = (name, config, cb) => {
+        const wrapped = async (args, extra) => {
+            const startedAt = Date.now();
+            try {
+                const result = await cb(args, extra);
+                const durationMs = Date.now() - startedAt;
+                const isError = readIsError(result);
+                safeNotify(listener, {
+                    type: 'tool-call',
+                    tool: name,
+                    arguments: args,
+                    result,
+                    isError,
+                    error: isError ? extractErrorMessage(result) : null,
+                    startedAt,
+                    durationMs
+                });
+                return result;
+            }
+            catch (error) {
+                const durationMs = Date.now() - startedAt;
+                safeNotify(listener, {
+                    type: 'tool-call',
+                    tool: name,
+                    arguments: args,
+                    result: null,
+                    isError: true,
+                    error: toErrorMessage(error),
+                    startedAt,
+                    durationMs
+                });
+                throw error;
+            }
+        };
+        return original(name, config, wrapped);
+    };
+}

package/build/app/websocket.js

@@ -0,0 +1,116 @@
+import { WebSocket, WebSocketServer } from 'ws';
+import { toErrorMessage } from '../utils/error-message.js';
+import { logger } from '../utils/logger.js';
+import { dimensionState } from '../resources/dimension-resources.js';
+import { World } from '../world/world.js';
+function buildWorldSnapshot(world) {
+    return {
+        type: 'world-snapshot',
+        timestamp: Date.now(),
+        dimensions: World.listDimensions().map(dimension => dimensionState(world, dimension))
+    };
+}
+function sendText(socket, text) {
+    if (socket.readyState !== WebSocket.OPEN) {
+        return;
+    }
+    try {
+        socket.send(text);
+    }
+    catch (error) {
+        logger.warn(`WebSocket send failed: ${toErrorMessage(error)}`);
+    }
+}
+function sendObject(socket, payload) {
+    try {
+        sendText(socket, JSON.stringify(payload));
+    }
+    catch (error) {
+        logger.warn(`WebSocket serialize failed: ${toErrorMessage(error)}`);
+    }
+}
+function isClientMessage(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const type = value.type;
+    return type === 'world-request' || type === 'world';
+}
+function handleClientMessage(world, socket, data) {
+    const text = data.toString().trim();
+    if (text.length === 0) {
+        return;
+    }
+    let request;
+    try {
+        request = JSON.parse(text);
+    }
+    catch {
+        return;
+    }
+    if (isClientMessage(request)) {
+        sendObject(socket, buildWorldSnapshot(world));
+    }
+}
+export function startWebSocketService(world, config) {
+    const clients = new Set();
+    const wss = new WebSocketServer({
+        host: config.host,
+        port: config.port,
+        path: config.path
+    });
+    wss.on('error', error => {
+        logger.error(`WebSocket service error: ${toErrorMessage(error)}`);
+    });
+    wss.on('connection', socket => {
+        clients.add(socket);
+        logger.info(`WebSocket client connected (${clients.size} client(s))`);
+        sendObject(socket, buildWorldSnapshot(world));
+        socket.on('message', data => {
+            handleClientMessage(world, socket, data);
+        });
+        socket.on('close', () => {
+            clients.delete(socket);
+            logger.info(`WebSocket client disconnected (${clients.size} client(s))`);
+        });
+        socket.on('error', error => {
+            logger.warn(`WebSocket client error: ${toErrorMessage(error)}`);
+            clients.delete(socket);
+        });
+    });
+    function broadcast(event) {
+        if (clients.size === 0) {
+            return;
+        }
+        let text;
+        try {
+            text = JSON.stringify(event);
+        }
+        catch (error) {
+            logger.warn(`WebSocket tool-call serialize failed: ${toErrorMessage(error)}`);
+            return;
+        }
+        for (const socket of clients) {
+            sendText(socket, text);
+        }
+    }
+    function clientCount() {
+        return clients.size;
+    }
+    async function close() {
+        for (const socket of clients) {
+            try {
+                socket.close(1001, 'Server shutting down');
+            }
+            catch {
+            }
+        }
+        clients.clear();
+        await new Promise(resolve => {
+            wss.close(() => {
+                resolve();
+            });
+        });
+    }
+    return { broadcast, clientCount, close };
+}

package/build/config/server-info.js

@@ -4,11 +4,11 @@ import { MINECRAFT_ITEM_COUNT } from '../data/items.js';
 import { MINECRAFT_DATA_VERSION } from '../data/version.js';
 import { EIconTheme } from '../enums/icon-theme.enum.js';
 export const SERVER_INFO = {
-    name: 'lzimul',
+    name: '@lzimul/minecraft-mcp',
     title: 'lZiMUl Minecraft MCP',
-    description: `Minecraft Model Context Protocol server (Java Edition ${MINECRAFT_DATA_VERSION}): exposes all ${MINECRAFT_BLOCK_COUNT} blocks, ${MINECRAFT_ITEM_COUNT} items and ${MINECRAFT_ENTITY_COUNT} entity types with their properties as resources, plus tools to read and place blocks, inspect dimensions, create entities and players, and manage their hotbar and backpack inventories.`,
-    version: '1.0.4',
-    websiteUrl: 'https://mcp.lzimul.com/lZiMUl',
+    description: `Minecraft Model Context Protocol server (Java Edition ${MINECRAFT_DATA_VERSION}): exposes all ${MINECRAFT_BLOCK_COUNT} blocks, ${MINECRAFT_ITEM_COUNT} items and ${MINECRAFT_ENTITY_COUNT} entity types with their properties as resources, plus tools to read, place, query and fill blocks, inspect dimensions, create, move and delete entities and players, set entity positions, and manage their hotbar and backpack inventories.`,
+    version: '1.0.6',
+    websiteUrl: 'https://projects.lzimul.com/minecraft-mcp',
     icons: [
         {
             src: 'https://i1.hdslb.com/bfs/face/79fbb5635ff6e50fe2699c518af82162523e5f08.jpg',

package/build/config/storage.js

@@ -4,9 +4,10 @@ function storageKind() {
         ? 'memory'
         : 'file';
 }
+const DEFAULT_WORLD_DIRECTORY = './app/dimensions';
 function storageDirectory() {
     const configured = process.env.MCP_WORLD_DIR?.trim();
-    return path.resolve(configured && configured.length > 0 ? configured : './world-data');
+    return path.resolve(configured && configured.length > 0 ? configured : DEFAULT_WORLD_DIRECTORY);
 }
 export const WORLD_STORAGE = {
     kind: storageKind(),

package/build/config/websocket.js

@@ -0,0 +1,48 @@
+function envString(name) {
+    const raw = process.env[name];
+    if (typeof raw !== 'string') {
+        return null;
+    }
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function envFlag(name, fallback) {
+    const raw = envString(name);
+    if (raw === null) {
+        return fallback;
+    }
+    const normalized = raw.toLowerCase();
+    if (['false', '0', 'no', 'off'].includes(normalized)) {
+        return false;
+    }
+    if (['true', '1', 'yes', 'on'].includes(normalized)) {
+        return true;
+    }
+    return fallback;
+}
+function envPort(name, fallback) {
+    const raw = envString(name);
+    if (raw === null) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535
+        ? parsed
+        : fallback;
+}
+function envHost(name, fallback) {
+    return envString(name) ?? fallback;
+}
+function envPath(name, fallback) {
+    const raw = envString(name);
+    if (raw === null) {
+        return fallback;
+    }
+    return raw.startsWith('/') ? raw : `/${raw}`;
+}
+export const WEBSOCKET_CONFIG = {
+    enabled: envFlag('MCP_WS_ENABLED', true),
+    host: envHost('MCP_WS_HOST', '127.0.0.1'),
+    port: envPort('MCP_WS_PORT', 8765),
+    path: envPath('MCP_WS_PATH', '/')
+};

package/build/config/world-limits.js

@@ -4,7 +4,9 @@ export const WORLD_LIMITS = {
     minVertical: -64,
     maxVertical: 320,
     maxModifiedBlocks: 250_000,
+    maxFillVolume: 16_384,
     maxEntitiesPerDimension: 10_000,
+    maxEntityIdLength: 128,
     maxEntityNameLength: 64,
     maxPlayerNameLength: 32
 };

package/build/enums/move-direction.enum.js

@@ -0,0 +1,9 @@
+export var EMoveDirection;
+(function (EMoveDirection) {
+    EMoveDirection["Forward"] = "forward";
+    EMoveDirection["Back"] = "back";
+    EMoveDirection["Left"] = "left";
+    EMoveDirection["Right"] = "right";
+    EMoveDirection["Up"] = "up";
+    EMoveDirection["Down"] = "down";
+})(EMoveDirection || (EMoveDirection = {}));

package/build/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { createServer } from './app/server.js';
+import { startWebSocketService } from './app/websocket.js';
+import { WEBSOCKET_CONFIG } from './config/websocket.js';
 import { WORLD_STORAGE } from './config/storage.js';
 import { toErrorMessage } from './utils/error-message.js';
 import { logger } from './utils/logger.js';
@@ -8,7 +10,14 @@ 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 wsService = null;
+    if (WEBSOCKET_CONFIG.enabled) {
+        wsService = startWebSocketService(world, WEBSOCKET_CONFIG);
+        logger.info(`WebSocket service listening on ws://${WEBSOCKET_CONFIG.host}:${WEBSOCKET_CONFIG.port}${WEBSOCKET_CONFIG.path}`);
+    }
+    const handle = serveStdio(() => createServer(world, wsService ? { onToolCall: wsService.broadcast } : {}), {
+        legacy: 'reject'
+    });
     let shuttingDown = false;
     const shutdown = async (exitCode) => {
         if (shuttingDown) {
@@ -30,6 +39,15 @@ async function main() {
             logger.error(`Failed to close the MCP transport: ${toErrorMessage(error)}`);
             code = 1;
         }
+        if (wsService) {
+            try {
+                await wsService.close();
+            }
+            catch (error) {
+                logger.error(`Failed to close the WebSocket service: ${toErrorMessage(error)}`);
+                code = 1;
+            }
+        }
         process.exit(code);
     };
     process.once('SIGINT', () => {

package/build/interfaces/websocket.interface.js

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

package/build/resources/dimension-resources.js

@@ -1,7 +1,7 @@
 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';
+import { errorResource } from './error-content.js';
 function dimensionSummary(world, dimension) {
     const simulated = world.getDimension(dimension.type);
     return {
@@ -17,7 +17,7 @@ function dimensionSummary(world, dimension) {
         uri: `lzimul://minecraft/dimensions/${dimension.type}`
     };
 }
-function dimensionState(world, dimension) {
+export function dimensionState(world, dimension) {
     const simulated = world.getDimension(dimension.type);
     return {
         key: dimension.key,