@lzimul/minecraft-mcp 1.0.6 → 1.0.7

package/README.md

@@ -131,7 +131,7 @@ Each snapshot looks like this:
 | `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`    | `true`             | Start the WebSocket fan-out service (`false` to disable) |
+| `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                |
@@ -155,9 +155,9 @@ State is accessed through `IWorldStore` (`src/interfaces/world-store.interface.t
 
 ### WebSocket service
 
-The server runs a WebSocket fan-out service alongside the stdio MCP transport. It is enabled by default on `127.0.0.1:8765` and can be reconfigured or disabled 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.
+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.
 
-Each connected client immediately receives a **world snapshot**, then a **tool-call event** for every MCP tool invocation:
+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"}):

package/build/app/websocket.js

@@ -3,6 +3,7 @@ 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',
@@ -54,6 +55,7 @@ function handleClientMessage(world, socket, data) {
 }
 export function startWebSocketService(world, config) {
     const clients = new Set();
+    const pendingSnapshots = new Set();
     const wss = new WebSocketServer({
         host: config.host,
         port: config.port,
@@ -65,7 +67,16 @@ export function startWebSocketService(world, config) {
     wss.on('connection', socket => {
         clients.add(socket);
         logger.info(`WebSocket client connected (${clients.size} client(s))`);
-        sendObject(socket, buildWorldSnapshot(world));
+        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);
         });
@@ -98,6 +109,10 @@ export function startWebSocketService(world, config) {
         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');

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.6',
+    version: '1.0.7',
     websiteUrl: 'https://projects.lzimul.com/minecraft-mcp',
     icons: [
         {

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

@@ -1 +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;AAG9C,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,CAuEnB"}
+{"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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lzimul/minecraft-mcp",
   "description": "Minecraft Model Context Protocol (MCP) Server",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "author": {
     "name": "lZiMUl",
     "email": "lZiMUl@lzimul.com",