@lzimul/minecraft-mcp 1.0.5 → 1.0.7

package/README.md

@@ -10,6 +10,7 @@ Minecraft Model Context Protocol (MCP) server. It exposes the complete Minecraft
 - Dimension tools for metadata, paginated block access, entity listings and raw JSON snapshots
 - Entity and player tools with deletion, movement, exact position control, and a 9-slot hotbar plus 27-slot backpack per entity, managed through `getInventory`, `setInventory`, `clearInventory` and `swapInventorySlots`
 - World state (blocks, entities, players and inventories) is persisted per dimension as JSON and survives restarts
+- Parallel WebSocket service that broadcasts every tool call (name, arguments, result, error and timing) to all connected clients, with a full world snapshot sent on connect and on demand (`{"type":"world-request"}`)
 - log4js logging to stderr with chalk colours (error red, warn yellow, info green); stdout stays clean for the MCP transport
 - Structured tool output (`outputSchema` / `structuredContent`) plus human readable text
 - Every failure path returns a readable message instead of an unhandled exception
@@ -125,11 +126,15 @@ Each snapshot looks like this:
 
 ### Configuration
 
-| Variable            | Default        | Description                                             |
-| ------------------- | -------------- | ------------------------------------------------------- |
-| `MCP_WORLD_STORAGE` | `file`         | `file` for JSON snapshots, `memory` for volatile state  |
-| `MCP_WORLD_DIR`     | `./app/dimensions` | Directory that holds the per-dimension snapshots    |
-| `MCP_LOG_LEVEL`     | `info`         | log4js level: `trace`, `debug`, `info`, `warn`, `error` |
+| Variable            | Default            | Description                                              |
+| ------------------- | ------------------ | -------------------------------------------------------- |
+| `MCP_WORLD_STORAGE` | `file`             | `file` for JSON snapshots, `memory` for volatile state   |
+| `MCP_WORLD_DIR`     | `./app/dimensions` | Directory that holds the per-dimension snapshots         |
+| `MCP_LOG_LEVEL`     | `info`             | log4js level: `trace`, `debug`, `info`, `warn`, `error`  |
+| `MCP_WS_ENABLED`    | `false`            | Start the WebSocket fan-out service (`false` to disable) |
+| `MCP_WS_HOST`       | `127.0.0.1`        | Host/interface the WebSocket service binds to            |
+| `MCP_WS_PORT`       | `8765`             | TCP port for the WebSocket service                       |
+| `MCP_WS_PATH`       | `/`                | URL path the WebSocket service listens on                |
 
 A corrupt or oversized snapshot is moved aside as `<dimension>.json.corrupt-<uuid>` and the dimension starts empty, so a bad file never blocks startup.
 
@@ -148,6 +153,58 @@ State is accessed through `IWorldStore` (`src/interfaces/world-store.interface.t
 | `FileWorldStore`   | stdio (`npm start`) | Atomic per-dimension JSON files under `MCP_WORLD_DIR` |
 | `MemoryWorldStore` | tests, `memory`     | Volatile; useful for throwaway sessions               |
 
+### WebSocket service
+
+The server can run a WebSocket fan-out service alongside the stdio MCP transport, but it should be treated as a privileged telemetry channel. Keep it **disabled by default** unless you explicitly need it, and enable it only with access controls (for example: an origin allow-list and/or a shared token presented during the upgrade request). Bind/listen settings can still be configured with the `MCP_WS_*` variables above. The MCP transport is unaffected: stdout stays reserved for JSON-RPC, and a WebSocket listen failure is logged but never crashes the process.
+
+When enabled, authenticated/authorized clients receive a **world snapshot** right after the handshake (pushed on a short delay so clients that attach their message listener after `open` still catch it), then a **tool-call event** for every MCP tool invocation:
+
+```jsonc
+// On connect (and on {"type":"world-request"}):
+{ "type": "world-snapshot", "timestamp": 1730000000000, "dimensions": [ /* full per-dimension state: counts, placedBlocks, entities */ ] }
+
+// Broadcast to every client after each tool call:
+{
+  "type": "tool-call",
+  "tool": "getBlock",
+  "arguments": { "dimension": "overworld", "x": 0, "y": 320, "z": 0 },
+  "result": { "isError": true, "content": [ /* ... */ ] },
+  "isError": true,
+  "error": "Coordinates (0, 320, 0) are out of range in Overworld (Y: -64 to 319).",
+  "startedAt": 1730000000000,
+  "durationMs": 1
+}
+```
+
+A client may send `{"type":"world-request"}` (or `{"type":"world"}`) to request a fresh snapshot. The service observes tool calls by wrapping `McpServer.registerTool`, so tools added in the future are broadcast automatically.
+
+#### WebSocket TypeScript types
+
+Package consumers can import the protocol types (published via `lib/index.d.ts`) instead of hand-writing them:
+
+```ts
+import type {
+  IWorldSnapshotMessage, // server -> client: full world state on connect / world-request
+  IDimensionSnapshot, // one dimension: counts, placedBlocks, entities
+  ISnapshotPlacedBlock, // { x, y, z, block: BlockInfo, states: BlockStates }
+  IToolCallEvent, // server -> client: one tool invocation
+  IWebSocketServerMessage, // union of IWorldSnapshotMessage | IToolCallEvent
+  IWebSocketClientMessage, // client -> server: { type: 'world-request' | 'world' }
+  ToolCallListener,
+} from "@lzimul/minecraft-mcp";
+
+// Discriminate incoming messages by `msg.type`:
+function handle(msg: IWebSocketServerMessage): void {
+  if (msg.type === "world-snapshot") {
+    for (const dimension of msg.dimensions) {
+      renderDimension(dimension);
+    }
+  } else if (msg.type === "tool-call") {
+    applyToolCall(msg); // msg.tool, msg.arguments, msg.result, msg.isError, msg.error, msg.startedAt, msg.durationMs
+  }
+}
+```
+
 ## Resources
 
 | URI                                    | Description                                          |
@@ -189,7 +246,7 @@ Measured on Node.js 26 (results vary by hardware):
 src/
   index.ts        Entry point
   app/            Server assembly
-  config/         Server metadata, dimensions, storage, world limits
+  config/         Server metadata, dimensions, storage, world limits, WebSocket
   data/           Generated registry data (blocks, items, entities, version)
   enums/          Enumerations (EBoundingBox, EIconTheme, EDimensionType, EEntityKind, EInventorySection, EMoveDirection)
   interfaces/     Interfaces (IBlock, IItem, IEntityType, IEntity, IEntityInventory, IDimension, IPlacedBlock, IWorldSnapshot, IWorldStore)
@@ -203,6 +260,7 @@ scripts/
   logger.mjs               Coloured stdout logger for developer scripts
   generate-data.mjs        Regenerates src/data from minecraft-data
   smoke-test.mjs           End-to-end smoke test (blocks, dimensions, entities, inventories)
+  websocket-test.mjs       WebSocket fan-out test (snapshots, tool-call broadcast)
   persistence-test.mjs     Restart test for blocks, entities and inventories
   error-test.mjs           Error fallbacks, sanitizing and storage limit tests
   stress-test.mjs          Parallel write, coalescing and restart stress test
@@ -211,17 +269,18 @@ scripts/
 
 ## Scripts
 
-| Command                 | Description                                           |
-| ----------------------- | ----------------------------------------------------- |
-| `npm run build`         | Lint, compile and generate docs                       |
-| `npm run dev`           | Build then start the server                           |
-| `npm start`             | Start the server (stdio)                              |
-| `npm test`              | Run the smoke, persistence, security and stress tests |
-| `npm run test:stress`   | Run only the parallel write stress test               |
-| `npm run generate-data` | Regenerate registry data (see below)                  |
-| `npm run clean`         | Remove build output                                   |
-| `npm run lint`          | Lint without modifying files                          |
-| `npm run lint:fix`      | Lint and auto-fix                                     |
+| Command                  | Description                                                      |
+| ------------------------ | ---------------------------------------------------------------- |
+| `npm run build`          | Lint, compile and generate docs                                  |
+| `npm run dev`            | Build then start the server                                      |
+| `npm start`              | Start the server (stdio)                                         |
+| `npm test`               | Run the smoke, WebSocket, persistence, security and stress tests |
+| `npm run test:websocket` | Run only the WebSocket fan-out test                              |
+| `npm run test:stress`    | Run only the parallel write stress test                          |
+| `npm run generate-data`  | Regenerate registry data (see below)                             |
+| `npm run clean`          | Remove build output                                              |
+| `npm run lint`           | Lint without modifying files                                     |
+| `npm run lint:fix`       | Lint and auto-fix                                                |
 
 ## Data
 

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,131 @@
+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';
+const INITIAL_SNAPSHOT_DELAY_MS = 25;
+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 pendingSnapshots = 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))`);
+        const snapshotTimer = setTimeout(() => {
+            pendingSnapshots.delete(snapshotTimer);
+            try {
+                sendObject(socket, buildWorldSnapshot(world));
+            }
+            catch (error) {
+                logger.warn(`WebSocket initial snapshot failed: ${toErrorMessage(error)}`);
+            }
+        }, INITIAL_SNAPSHOT_DELAY_MS);
+        pendingSnapshots.add(snapshotTimer);
+        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 snapshotTimer of pendingSnapshots) {
+            clearTimeout(snapshotTimer);
+        }
+        pendingSnapshots.clear();
+        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

@@ -7,7 +7,7 @@ export const SERVER_INFO = {
     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, 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.5',
+    version: '1.0.7',
     websiteUrl: 'https://projects.lzimul.com/minecraft-mcp',
     icons: [
         {

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/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,12 @@ 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;
@@ -32,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

@@ -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,

package/lib/app/server.d.ts

@@ -1,4 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/server';
+import type { ToolCallListener } from './tool-events.js';
 import type { World } from '../world/world.js';
-export declare function createServer(world: World): McpServer;
+export interface ICreateServerOptions {
+    readonly onToolCall?: ToolCallListener;
+}
+export declare function createServer(world: World, options?: ICreateServerOptions): McpServer;
 //# sourceMappingURL=server.d.ts.map

package/lib/app/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/app/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAMzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAKpD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/app/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAOzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,MAAM,WAAW,oBAAoB;IAEnC,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAGD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,oBAAoB,GAC7B,SAAS,CAaX"}

package/lib/app/tool-events.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { IToolCallEvent, ToolCallListener } from '../interfaces/websocket.interface.js';
+export type { IToolCallEvent, ToolCallListener };
+export declare function instrumentToolCalls(server: McpServer, listener: ToolCallListener): void;
+//# sourceMappingURL=tool-events.d.ts.map

package/lib/app/tool-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-events.d.ts","sourceRoot":"","sources":["../../src/app/tool-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAK9D,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,sCAAsC,CAAC;AAE9C,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC;AA4DjD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CAwCN"}

package/lib/app/websocket.d.ts

@@ -0,0 +1,10 @@
+import { World } from '../world/world.js';
+import type { IWebSocketConfig } from '../config/websocket.js';
+import type { IToolCallEvent } from '../interfaces/websocket.interface.js';
+export interface IWebSocketService {
+    broadcast(event: IToolCallEvent): void;
+    clientCount(): number;
+    close(): Promise<void>;
+}
+export declare function startWebSocketService(world: World, config: IWebSocketConfig): IWebSocketService;
+//# sourceMappingURL=websocket.d.ts.map

package/lib/app/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/app/websocket.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EACV,cAAc,EAIf,MAAM,sCAAsC,CAAC;AAc9C,MAAM,WAAW,iBAAiB;IAEhC,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAEvC,WAAW,IAAI,MAAM,CAAC;IAEtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA0ED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,gBAAgB,GACvB,iBAAiB,CAyFnB"}

package/lib/config/websocket.d.ts

@@ -0,0 +1,8 @@
+export interface IWebSocketConfig {
+    readonly enabled: boolean;
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+}
+export declare const WEBSOCKET_CONFIG: IWebSocketConfig;
+//# sourceMappingURL=websocket.d.ts.map

package/lib/config/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/config/websocket.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AA2DD,eAAO,MAAM,gBAAgB,EAAE,gBAK9B,CAAC"}

package/lib/index.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export {};
+export type { IDimensionSnapshot, ISnapshotPlacedBlock, IToolCallEvent, IWebSocketClientMessage, IWebSocketServerMessage, IWorldSnapshotMessage, ToolCallListener } from './interfaces/websocket.interface.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAoGA,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,qCAAqC,CAAC"}

package/lib/interfaces/websocket.interface.d.ts

@@ -0,0 +1,47 @@
+import type { EDimensionType } from '../enums/dimension-type.enum.js';
+import type { BlockInfo } from '../schemas/block-schema.js';
+import type { EntityInfo } from '../schemas/entity-schema.js';
+import type { BlockStates } from './block-states.interface.js';
+export interface ISnapshotPlacedBlock {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly block: BlockInfo;
+    readonly states: BlockStates;
+}
+export interface IDimensionSnapshot {
+    readonly key: string;
+    readonly type: EDimensionType;
+    readonly displayName: string;
+    readonly minY: number;
+    readonly maxY: number;
+    readonly hasSkylight: boolean;
+    readonly modifiedBlockCount: number;
+    readonly entityCount: number;
+    readonly playerCount: number;
+    readonly placedBlocks: readonly ISnapshotPlacedBlock[];
+    readonly entities: readonly EntityInfo[];
+}
+export interface IWorldSnapshotMessage {
+    readonly type: 'world-snapshot';
+    readonly timestamp: number;
+    readonly dimensions: readonly IDimensionSnapshot[];
+}
+export interface IToolCallEvent {
+    readonly type: 'tool-call';
+    readonly tool: string;
+    readonly arguments: unknown;
+    readonly result: unknown;
+    readonly isError: boolean;
+    readonly error: string | null;
+    readonly startedAt: number;
+    readonly durationMs: number;
+}
+export type ToolCallListener = (event: IToolCallEvent) => void;
+export type IWebSocketClientMessage = {
+    readonly type: 'world-request';
+} | {
+    readonly type: 'world';
+};
+export type IWebSocketServerMessage = IWorldSnapshotMessage | IToolCallEvent;
+//# sourceMappingURL=websocket.interface.d.ts.map

package/lib/interfaces/websocket.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/websocket.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAG/D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAGD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvD,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;CAC1C;AAGD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAEhC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAGD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAGD,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAG/D,MAAM,MAAM,uBAAuB,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAGlE,MAAM,MAAM,uBAAuB,GAAG,qBAAqB,GAAG,cAAc,CAAC"}

package/lib/resources/dimension-resources.d.ts

@@ -1,5 +1,8 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { World } from '../world/world.js';
+import type { IDimension } from '../interfaces/dimension.interface.js';
+import type { IDimensionSnapshot } from '../interfaces/websocket.interface.js';
+export declare function dimensionState(world: World, dimension: IDimension): IDimensionSnapshot;
 export declare function registerDimensionIndexResource(server: McpServer, world: World): void;
 export declare function registerDimensionResources(server: McpServer, world: World): void;
 //# sourceMappingURL=dimension-resources.d.ts.map

package/lib/resources/dimension-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dimension-resources.d.ts","sourceRoot":"","sources":["../../src/resources/dimension-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAI9D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAqD1C,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,KAAK,GACX,IAAI,CAgCN;AAGD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,KAAK,GACX,IAAI,CA2BN"}
+{"version":3,"file":"dimension-resources.d.ts","sourceRoot":"","sources":["../../src/resources/dimension-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAI9D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAuB/E,wBAAgB,cAAc,CAC5B,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,UAAU,GACpB,kBAAkB,CAqBpB;AAGD,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,KAAK,GACX,IAAI,CAgCN;AAGD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,KAAK,GACX,IAAI,CA2BN"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lzimul/minecraft-mcp",
   "description": "Minecraft Model Context Protocol (MCP) Server",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "author": {
     "name": "lZiMUl",
     "email": "lZiMUl@lzimul.com",
@@ -44,7 +44,8 @@
     "dev": "npm run build && npm run start",
     "generate-data": "node ./scripts/generate-data.mjs",
     "clean": "node ./scripts/clean.mjs",
-    "test": "node ./scripts/smoke-test.mjs && node ./scripts/persistence-test.mjs && node ./scripts/error-test.mjs && node ./scripts/stress-test.mjs",
+    "test": "node ./scripts/smoke-test.mjs && node ./scripts/websocket-test.mjs && node ./scripts/persistence-test.mjs && node ./scripts/error-test.mjs && node ./scripts/stress-test.mjs",
+    "test:websocket": "node ./scripts/websocket-test.mjs",
     "test:stress": "node ./scripts/stress-test.mjs",
     "prepublishOnly": "npm run build && npm test"
   },
@@ -72,6 +73,7 @@
     "@modelcontextprotocol/server": "^2.4.0",
     "chalk": "^6.0.1",
     "log4js": "^6.9.1",
+    "ws": "^8.22.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
@@ -81,6 +83,7 @@
     "@eslint/json": "^2.1.1",
     "@eslint/markdown": "^8.0.3",
     "@types/node": "^26.6.5",
+    "@types/ws": "^8.18.2",
     "@typescript-eslint/eslint-plugin": "^8.72.1",
     "@typescript-eslint/parser": "^8.72.1",
     "eslint": "^10.13.0",