@lzimul/minecraft-mcp 1.0.3 → 1.0.5

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) [2020-2030] [lZiMUl]
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) [2020-2030] [lZiMUl]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,47 +1,78 @@
 # lZiMUl Minecraft MCP
 
-Minecraft Model Context Protocol (MCP) server. It exposes the complete Minecraft registry (Java Edition data) as MCP resources and provides tools to read and write blocks in persisted, per-dimension worlds. Requires Node.js 22 or newer.
+Minecraft Model Context Protocol (MCP) server. It exposes the complete Minecraft registry (Java Edition data) as MCP resources and provides tools to read, write, query and fill blocks, inspect dimensions, create, move and delete entities and players, set their positions, and manage inventories in persisted, per-dimension worlds. Requires Node.js 22 or newer.
 
 ## Features
 
-- All Minecraft blocks and items exposed as MCP resources with full properties (name, hardness, blast resistance, durability, enchantment categories, light level, collision box, and more)
-- Block lookup and placement tools backed by simulated dimensions (Overworld, The Nether, The End), each with its own isolated world state and height range
+- All Minecraft blocks, items and entity types exposed as MCP resources with full properties (name, hardness, blast resistance, durability, enchantment categories, light level, collision box, entity dimensions, category, and more)
+- Block lookup, placement, area queries and bounded fill tools backed by simulated dimensions (Overworld, The Nether, The End), each with its own isolated world state and height range
 - Block states are supported everywhere: `minecraft:oak_stairs[facing=south,half=bottom]`
-- World state is persisted per dimension as JSON and survives restarts
+- 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
+- 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
 - Tool annotations for safe client automation
 
 ## Protocol
 
-This server implements **MCP 2026-07-28 only**. The legacy 2025-era `initialize` handshake is rejected, so clients must use the modern protocol:
-
-- Start a session with `server/discover`, or send any request carrying the per-request envelope.
-- Every request must include the envelope in `params._meta`:
-  - `io.modelcontextprotocol/protocolVersion`: `"2026-07-28"`
-  - `io.modelcontextprotocol/clientCapabilities`
-  - `io.modelcontextprotocol/clientInfo` (optional)
-- Responses use the modern result shape (`resultType`, server identity under `_meta['io.modelcontextprotocol/serverInfo']`).
-- A legacy `initialize` is answered with `UnsupportedProtocolVersionError` naming the supported modern revision.
-
-When testing with MCP Inspector 2.12 or newer, set **Protocol Era** to `modern` (or `auto`) for this server. The Inspector's default `legacy` mode sends `initialize`, which this server intentionally rejects.
+The server implements the MCP `2026-07-28` revision. Modern clients open a session with `server/discover` and carry the per-request envelope in every request's `params._meta` (`io.modelcontextprotocol/protocolVersion`, `io.modelcontextprotocol/clientCapabilities`, and optionally `io.modelcontextprotocol/clientInfo`). Responses use the modern result shape (`resultType`, server identity under `_meta['io.modelcontextprotocol/serverInfo']`). The legacy `initialize` handshake is rejected with error `-32022`; clients must use `server/discover` or send the per-request envelope.
 
 ## Tools
 
-| Tool       | Description                                                                            |
-| ---------- | -------------------------------------------------------------------------------------- |
-| `getBlock` | Get the block (and its states) at coordinates in a dimension (defaults to `overworld`) |
-| `setBlock` | Place a block with optional states in a dimension and return the replaced block        |
-| `getItem`  | Look up item properties by id (`minecraft:diamond_sword` or `diamond_sword`)           |
+| Tool                   | Description                                                                               |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| `getBlock`             | Get the block (and its states) at coordinates in a dimension (defaults to `overworld`)    |
+| `setBlock`             | Place a block with optional states in a dimension and return the replaced block           |
+| `getDimension`         | Get dimension metadata, block count, entity count and player count                        |
+| `getDimensionBlocks`   | Page through every placed (non-air) block in a dimension, sorted by coordinates           |
+| `getBlocksInArea`      | Page through placed blocks inside a box, with an optional block and states filter         |
+| `fillBlocks`           | Fill a box with one block, optionally replacing existing blocks; air clears the box       |
+| `getDimensionEntities` | List every entity and player in a dimension with type, name and position                  |
+| `getDimensionRawFile`  | Return the raw dimension JSON snapshot, including `blocks` and `entities`                 |
+| `getItem`              | Look up item properties by id (`minecraft:diamond_sword` or `diamond_sword`)              |
+| `createEntity`         | Create a non-player entity with an empty hotbar and backpack                              |
+| `getEntity`            | Get an entity by UUID, including position, dimension and full inventory                   |
+| `deleteEntity`         | Delete an entity or player by UUID or player name and discard its inventory               |
+| `moveEntity`           | Move an entity one block forward, back, left, right, up or down                           |
+| `getEntityPosition`    | Get an entity UUID, type, name and exact `x`/`y`/`z` position                             |
+| `setEntityPosition`    | Set an entity UUID to an exact `x`/`y`/`z` position                                       |
+| `createPlayer`         | Create a uniquely named player with an empty hotbar and backpack                          |
+| `getPlayer`            | Get a player by name (case-insensitive), including position, dimension and full inventory |
+| `getInventory`         | Read the 9 hotbar slots and 27 backpack slots of an entity or player                      |
+| `clearInventory`       | Remove every item from an entity or player inventory                                      |
+| `swapInventorySlots`   | Swap any two hotbar or backpack slots of an entity or player                              |
+| `setInventory`         | Set or clear one hotbar/backpack slot of an entity or player                              |
 
 `setBlock` accepts both the full form (`minecraft:oak_stairs[facing=south,half=bottom]`) and the short form (`oak_stairs[facing=south]`). Setting `minecraft:air` removes the block; air cannot carry states.
 
+`getDimensionBlocks` is paginated because a dimension can hold up to 250,000 placed blocks. `limit` defaults to 1,000 and is capped at 10,000; `offset` skips rows. Rows are sorted by `x`, `y`, `z` and include the block id, display name and states.
+
+`getBlocksInArea` reads an inclusive box in one dimension. Its corners may be supplied in any order, and the optional `blockType` filter matches the block id; when states are included, the stored state map must match exactly. The same `limit`/`offset` pagination applies.
+
+`fillBlocks` writes one block type into an inclusive box. By default it fills only air; set `overwrite` to `true` to replace existing blocks. Use `minecraft:air` with `overwrite` to clear a region. A single request is limited to 16,384 coordinates, and the result reports changed, placed, removed and skipped counts.
+
+`getDimensionEntities` lists entity and player summaries, sorted by UUID; use `getEntity` or `getInventory` when you need the full inventory of one record. The former `getDimensionEntitys` spelling is no longer registered. `getDimensionRawFile` returns the same raw JSON format that is written to disk, so the result can be loaded directly by `app/minecraft_world_viewer.html`.
+
+### Entities, players and inventories
+
+- Entity type ids come from the generated registry (`lzimul://minecraft/entities`), for example `minecraft:zombie` or `zombie`. `createEntity` rejects `minecraft:player`; use `createPlayer` for players.
+- Players are addressed by name, case-insensitively, and names are unique across all dimensions. Entity and player UUIDs come from the creation response.
+- Every entity and player has a 9-slot hotbar plus a 27-slot backpack (36 slots total). Slots are zero-based within their section.
+- `getInventory`, `setInventory`, `clearInventory`, `swapInventorySlots` and `deleteEntity` accept either an entity UUID or a player name. `setInventory` requires `section` (`hotbar` or `inventory`, default `inventory`), `slot`, `item` and `count`; `swapInventorySlots` requires two section/slot pairs.
+- `count` must not exceed the item's stack size. Set the item to `minecraft:air` or the count to `0` to clear a slot. Empty slots are returned as `null`. `clearInventory` removes all 36 slots at once.
+- `deleteEntity` removes the entity or player and its inventory from its dimension. Deleting a player frees the name for reuse.
+- `moveEntity` moves exactly one block and takes only an entity UUID and a direction: `forward` (`+Z`, south), `back` (`-Z`, north), `left` (`-X`, west), `right` (`+X`, east), `up` (`+Y`) or `down` (`-Y`). The destination must remain inside the entity's dimension.
+- `getEntityPosition` returns the entity UUID, type, name and `x`/`y`/`z`; `setEntityPosition` takes an entity UUID plus a nested `{ "x": ..., "y": ..., "z": ... }` position.
+- A dimension holds at most 10,000 entities and players combined. Entity names are limited to 64 characters and player names to 32 characters (`A-Z`, `a-z`, `0-9`, `_`).
+
 ## Persistence
 
 World snapshots are stored as one JSON document per dimension, so the dimensions never share a file:
 
 ```text
-world-data/
+app/dimensions/
   overworld.json
   the_nether.json
   the_end.json
@@ -51,10 +82,11 @@ Each snapshot looks like this:
 
 ```json
 {
-  "format": "lzimul-world/2",
+  "format": "lzimul:minecraft/dimension",
   "dimension": "minecraft:overworld",
   "updatedAt": "2026-01-01T00:00:00.000Z",
   "modifiedBlockCount": 1,
+  "entityCount": 1,
   "blocks": [
     {
       "x": 0,
@@ -63,28 +95,50 @@ Each snapshot looks like this:
       "block": "minecraft:oak_stairs",
       "states": { "facing": "south", "half": "bottom" }
     }
+  ],
+  "entities": [
+    {
+      "id": "0f0f2f4e-7d5a-4d8e-9a3b-2f6c1d8e4a10",
+      "kind": "player",
+      "type": "minecraft:player",
+      "name": "Steve",
+      "x": 1,
+      "y": 64,
+      "z": 0,
+      "createdAt": "2026-01-01T00:00:00.000Z"
+    }
   ]
 }
 ```
 
-- The whole dimension is loaded once at startup and kept in memory; mutations are written back debounced and atomically (temporary file + rename).
-- `setBlock` awaits the write, so a successful response means the block is durably stored. If persisting fails the tool returns an error instead of pretending success.
+- The whole dimension (blocks, entities and players) is loaded once at startup and kept in memory; mutations are written back debounced and atomically (temporary file + rename).
+- `setBlock`, `fillBlocks`, `createEntity`, `deleteEntity`, `createPlayer`, `setInventory`, `clearInventory`, `swapInventorySlots`, `moveEntity` and `setEntityPosition` await the write, so a successful response means the change is durably stored. If persisting fails the tool returns an error instead of pretending success.
 - Parallel tool calls share a single in-flight snapshot write instead of writing one full file per call, so building with many simultaneous `setBlock` calls stays fast.
 - Unmodified coordinates are air; only placed blocks are stored. Placing air removes the coordinate from the snapshot.
 - Empty state maps are omitted from the file to keep snapshots small.
+- Entity and player inventories are omitted when they are completely empty. When present, `inventory.hotbar` has 9 entries and `inventory.inventory` has 27 entries; each entry is `{ "item": "minecraft:diamond_sword", "count": 1 }` or `null`.
+- Player names are not stored in a separate index: the player name index is rebuilt from the snapshots when the world loads. If two dimension files contain the same case-insensitive name, the first dimension wins and the duplicate player is dropped with a warning.
 - Snapshots are written as compact JSON (about half the bytes of pretty-printed JSON) with a trailing newline.
-- Files written by format v1 (`lzimul-world/1`, no states) still load; new files use `lzimul-world/2`.
+- Files written by format v1 (`lzimul-world/1`, no states) and v2 (`lzimul-world/2`, no entities) still load; new files use `lzimul:minecraft/dimension` and include an `entities` array. A missing `entities` array simply means the dimension has no entities.
+- Malformed block or entity entries are skipped without discarding the rest of the dimension. An entity's dimension always comes from the file it was loaded from, so an entry cannot claim to live in another dimension.
 - A dimension file is created on its first write; untouched dimensions stay empty.
 
 ### Configuration
 
-| Variable            | Default        | Description                                            |
-| ------------------- | -------------- | ------------------------------------------------------ |
-| `MCP_WORLD_STORAGE` | `file`         | `file` for JSON snapshots, `memory` for volatile state |
-| `MCP_WORLD_DIR`     | `./world-data` | Directory that holds the per-dimension snapshots       |
+| 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` |
 
 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.
 
+### Logging
+
+Server logs use [log4js](https://log4js-node.github.io/log4js-node/) with a chalk-based layout. `error`/`fatal` are red, `warn` yellow, `info` green, `debug` cyan and `trace` blue. Chalk disables ANSI colours automatically when the output is redirected to a non-colour terminal.
+
+Logs are written to **stderr**, never stdout: stdout is the MCP JSON-RPC transport, so mixing log lines into it would corrupt the protocol stream. `MCP_LOG_LEVEL` controls the verbosity (default `info`). Developer scripts use a small stdout logger (`scripts/logger.mjs`) with the same colours, so test output stays readable.
+
 ### Storage backends
 
 State is accessed through `IWorldStore` (`src/interfaces/world-store.interface.ts`):
@@ -96,34 +150,38 @@ State is accessed through `IWorldStore` (`src/interfaces/world-store.interface.t
 
 ## Resources
 
-| URI                                    | Description                                    |
-| -------------------------------------- | ---------------------------------------------- |
-| `lzimul://minecraft/blocks`            | Block index                                    |
-| `lzimul://minecraft/blocks/{name}`     | Single block properties                        |
-| `lzimul://minecraft/items`             | Item index                                     |
-| `lzimul://minecraft/items/{name}`      | Single item properties                         |
-| `lzimul://minecraft/dimensions`        | Persisted dimension index with world state     |
-| `lzimul://minecraft/dimensions/{type}` | Single dimension state including placed blocks |
+| URI                                    | Description                                          |
+| -------------------------------------- | ---------------------------------------------------- |
+| `lzimul://minecraft/blocks`            | Block index                                          |
+| `lzimul://minecraft/blocks/{name}`     | Single block properties                              |
+| `lzimul://minecraft/items`             | Item index                                           |
+| `lzimul://minecraft/items/{name}`      | Single item properties                               |
+| `lzimul://minecraft/entities`          | Entity type index (157 types, including `player`)    |
+| `lzimul://minecraft/entities/{name}`   | Single entity type properties                        |
+| `lzimul://minecraft/dimensions`        | Dimension index with block, entity and player counts |
+| `lzimul://minecraft/dimensions/{type}` | Single dimension state including blocks and entities |
 
-Placed blocks in the dimension resources include a `states` object. If a resource read fails, the server returns a JSON document with an `error` field instead of dropping the request.
+Placed blocks in the dimension resources include a `states` object. If a resource read fails, the server returns a JSON document with an `error` field instead of dropping the request. The dimensions index stays small on purpose: it reports per-dimension metadata, `modifiedBlockCount`, `entityCount` and `playerCount`, while `lzimul://minecraft/dimensions/{type}` returns the placed blocks plus the full entity/player list. In total the server registers 2,838 resources: every block, item and entity type, the indexes, and the seven dimension-related resources.
 
 ## Security
 
 - Tool input is validated with Zod: coordinates are bounded, dimensions come from an enum, and ids are limited in length.
-- Block ids are resolved against the generated registry; unknown blocks and namespaces are rejected.
+- Block and item ids are resolved against the generated registries; unknown blocks, items and entity types and unknown namespaces are rejected.
 - State names and values are restricted to `[a-z0-9_]` / `[a-z0-9_.-]`, 64 characters each, and reserved keys (`__proto__`, `constructor`, `prototype`) are rejected to rule out prototype pollution.
-- Each dimension holds at most 250,000 modified blocks, and the file store refuses snapshots over 128 MiB.
-- Snapshot writes are atomic, corrupt files are quarantined with a UUID suffix, and malformed blocks are skipped while the rest of the world loads.
+- Inventory input is validated too: the section and slot must be in range, the item must exist, and the count must fit the item's stack size. `minecraft:air` or count `0` clears a slot.
+- Each dimension holds at most 250,000 modified blocks and 10,000 entities/players. Entity names are capped at 64 characters, player names at 32 characters, and player names are case-insensitively unique across all dimensions. The file store refuses to load or write a snapshot over 128 MiB, so an oversized world fails the tool call instead of producing a file that would be quarantined on restart.
+- Snapshot writes are atomic, corrupt files are quarantined with a UUID suffix, and malformed block or entity entries are skipped while the rest of the world loads. Entity dimensions are taken from the snapshot file rather than trusted from the entry.
 - Run `npm audit` after dependency changes. The dependency tree currently reports no vulnerabilities; the `katex` override keeps the markdown lint toolchain patched.
 
 ## Performance
 
 Measured on Node.js 26 (results vary by hardware):
 
-- Startup, including registry import and 2,686 resource registrations: about 0.4 s.
+- Startup, including registry import and 2,838 resource registrations: about 0.4 s.
 - 300 concurrent `setBlock` tool calls: about 70 ms end-to-end, because parallel flushes share in-flight snapshot writes instead of writing the file 300 times.
 - 20,000 persisted blocks: about 1.1 MiB of compact JSON, ~25 ms to save and ~24 ms to load.
-- In-memory reads and writes are O(1) map operations; only the debounced snapshot write is proportional to the number of modified blocks.
+- In-memory block, entity and inventory reads/writes are O(1) map operations; only the debounced snapshot write is proportional to the number of modified blocks and entities.
+- `getDimensionBlocks` pages a cached, coordinate-sorted block array instead of re-sorting the world on every call.
 
 ## Project Structure
 
@@ -132,20 +190,20 @@ src/
   index.ts        Entry point
   app/            Server assembly
   config/         Server metadata, dimensions, storage, world limits
-  data/           Generated registry data (blocks, items, version)
-  enums/          Enumerations (EBoundingBox, EIconTheme, EDimensionType)
-  interfaces/     Interfaces (IBlock, IItem, IDimension, IPlacedBlock, IDataEntry, IWorldStore)
-  resources/      Resource registration and error fallbacks
-  schemas/        Zod schemas and converters
-  tools/          Tool registration and error handling
-  utils/          Shared helpers (error messages)
-  world/          Simulated dimension world state
-    stores/       IWorldStore implementations (file, memory)
+  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)
+  resources/      Block, item, entity and dimension resource registration
+  schemas/        Zod schemas and converters (blocks, entities, inventories)
+  tools/          Block, dimension, entity, player and inventory tools
+  utils/          Shared helpers (error messages, log4js + chalk logger)
+  world/          Simulated dimension state, entity inventory and item specs
+    stores/       IWorldStore implementations (file, memory) and serializers
 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 (including states)
-  protocol-test.mjs        Modern-only protocol era and envelope enforcement
-  persistence-test.mjs     Restart test for the world snapshots
+  smoke-test.mjs           End-to-end smoke test (blocks, dimensions, entities, inventories)
+  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
   clean.mjs                Removes build output
@@ -153,26 +211,27 @@ 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, protocol, 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 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, 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                                     |
 
 ## Data
 
 Registry data is generated from [PrismarineJS/minecraft-data](https://github.com/PrismarineJS/minecraft-data). To regenerate for a specific version:
 
 ```bash
-node scripts/generate-data.mjs <version> [blocks.json] [items.json]
+node scripts/generate-data.mjs <version> [blocks.json] [items.json] [entities.json]
 ```
 
-When local JSON files are provided they are used directly, otherwise the data is fetched from GitHub. The data version is exported as `MINECRAFT_DATA_VERSION` and used in all descriptions.
+When local JSON files are provided they are used directly, otherwise the data is fetched from GitHub. The fourth argument is optional and only needed for a custom entity registry; without it the entity list is fetched from the same minecraft-data release. The data version is exported as `MINECRAFT_DATA_VERSION` and used in all descriptions.
 
 ## License
 

package/SECURITY.md

@@ -1,21 +1,38 @@
-# Security Policy
-
-## Supported Versions
-
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
-
-| Version | Supported          |
-|---------|--------------------|
-| 5.1.x   | :white_check_mark: |
-| 5.0.x   | :x:                |
-| 4.0.x   | :white_check_mark: |
-| < 4.0   | :x:                |
-
-## Reporting a Vulnerability
-
-Use this section to tell people how to report a vulnerability.
-
-Tell them where to go, how often they can expect to get an update on a
-reported vulnerability, what to expect if the vulnerability is accepted or
-declined, etc.
+# Security Policy
+
+## Supported Versions
+
+Only the latest `1.x` release line receives security fixes.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Please do **not** open a public issue for security problems.
+
+- Email: lZiMUl@lzimul.com
+- Or use GitHub's private vulnerability reporting on
+  <https://github.com/lZiMUl/minecraft-mcp/security/advisories/new>
+
+Include the affected version, a minimal reproduction (tool call, resource URI
+or world snapshot), and the impact you observed. You can expect an initial
+response within a few days. Please allow time for a fix and release before
+disclosing the issue publicly.
+
+## Scope
+
+The server is designed to run locally over stdio. Reports that are in scope
+include, but are not limited to:
+
+- Prototype pollution or code execution through block ids, block states or
+  snapshot files
+- Path traversal or arbitrary file writes through `MCP_WORLD_DIR`
+- Denial of service through oversized tool input or snapshots
+- Data loss when persisting world state
+
+The following are generally out of scope: running the server with an
+untrusted `MCP_WORLD_DIR`, modifying files on disk without restarting the
+server, and issues that require an already-compromised host.

package/build/config/server-info.js

@@ -1,13 +1,14 @@
 import { MINECRAFT_BLOCK_COUNT } from '../data/blocks.js';
+import { MINECRAFT_ENTITY_COUNT } from '../data/entities.js';
 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 and ${MINECRAFT_ITEM_COUNT} items with their properties (name, hardness, blast resistance, durability, enchantment categories, etc.) as resources, plus tools to get and place blocks and look up items.`,
-    version: '1.0.3',
-    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.5',
+    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/world-limits.js

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