@lzimul/minecraft-mcp 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# lZiMUl Minecraft MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## 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
+- Block states are supported everywhere: `minecraft:oak_stairs[facing=south,half=bottom]`
+- World state is persisted per dimension as JSON and survives restarts
+- 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
+
+## 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`)           |
+
+`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.
+
+## Persistence
+
+World snapshots are stored as one JSON document per dimension, so the dimensions never share a file:
+
+```text
+world-data/
+  overworld.json
+  the_nether.json
+  the_end.json
+```
+
+Each snapshot looks like this:
+
+```json
+{
+  "format": "lzimul-world/2",
+  "dimension": "minecraft:overworld",
+  "updatedAt": "2026-01-01T00:00:00.000Z",
+  "modifiedBlockCount": 1,
+  "blocks": [
+    {
+      "x": 0,
+      "y": 64,
+      "z": 0,
+      "block": "minecraft:oak_stairs",
+      "states": { "facing": "south", "half": "bottom" }
+    }
+  ]
+}
+```
+
+- 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.
+- 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.
+- 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`.
+- 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       |
+
+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.
+
+### Storage backends
+
+State is accessed through `IWorldStore` (`src/interfaces/world-store.interface.ts`):
+
+| Backend            | Used by             | Notes                                                 |
+| ------------------ | ------------------- | ----------------------------------------------------- |
+| `FileWorldStore`   | stdio (`npm start`) | Atomic per-dimension JSON files under `MCP_WORLD_DIR` |
+| `MemoryWorldStore` | tests, `memory`     | Volatile; useful for throwaway sessions               |
+
+## 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 |
+
+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.
+
+## 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.
+- 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.
+- 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.
+- 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.
+
+## Project Structure
+
+```text
+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)
+scripts/
+  generate-data.mjs        Regenerates src/data from minecraft-data
+  smoke-test.mjs           End-to-end smoke test (including states)
+  persistence-test.mjs     Restart test for the world snapshots
+  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
+```
+
+## 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 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]
+```
+
+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.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,21 @@
+# 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.

package/build/app/server.js

@@ -0,0 +1,10 @@
+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) {
+    const server = new McpServer(SERVER_INFO);
+    registerTools(server, world);
+    registerResources(server, world);
+    return server;
+}

package/build/config/dimensions.js

@@ -0,0 +1,27 @@
+import { EDimensionType } from '../enums/dimension-type.enum.js';
+export const DIMENSIONS = [
+    {
+        key: 'minecraft:overworld',
+        type: EDimensionType.Overworld,
+        displayName: 'Overworld',
+        minY: -64,
+        maxY: 320,
+        hasSkylight: true
+    },
+    {
+        key: 'minecraft:the_nether',
+        type: EDimensionType.TheNether,
+        displayName: 'The Nether',
+        minY: 0,
+        maxY: 256,
+        hasSkylight: false
+    },
+    {
+        key: 'minecraft:the_end',
+        type: EDimensionType.TheEnd,
+        displayName: 'The End',
+        minY: 0,
+        maxY: 256,
+        hasSkylight: false
+    }
+];

package/build/config/server-info.js

@@ -0,0 +1,25 @@
+import { MINECRAFT_BLOCK_COUNT } from '../data/blocks.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',
+    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.1',
+    websiteUrl: 'https://mcp.lzimul.com/lZiMUl',
+    icons: [
+        {
+            src: 'https://i1.hdslb.com/bfs/face/79fbb5635ff6e50fe2699c518af82162523e5f08.jpg',
+            mimeType: 'image/jpeg',
+            sizes: ['48x48', '96x96', '192x192'],
+            theme: EIconTheme.Light
+        },
+        {
+            src: 'https://i1.hdslb.com/bfs/face/79fbb5635ff6e50fe2699c518af82162523e5f08.jpg',
+            mimeType: 'image/jpeg',
+            sizes: ['48x48', '96x96', '192x192'],
+            theme: EIconTheme.Dark
+        }
+    ]
+};

package/build/config/storage.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+function storageKind() {
+    return process.env.MCP_WORLD_STORAGE?.trim().toLowerCase() === 'memory'
+        ? 'memory'
+        : 'file';
+}
+function storageDirectory() {
+    const configured = process.env.MCP_WORLD_DIR?.trim();
+    return path.resolve(configured && configured.length > 0 ? configured : './world-data');
+}
+export const WORLD_STORAGE = {
+    kind: storageKind(),
+    directory: storageDirectory(),
+    writeDelayMs: 25
+};

package/build/config/world-limits.js

@@ -0,0 +1,7 @@
+export const WORLD_LIMITS = {
+    minHorizontal: -30000000,
+    maxHorizontal: 30000000,
+    minVertical: -64,
+    maxVertical: 320,
+    maxModifiedBlocks: 250_000
+};