@lzimul/minecraft-mcp 0.0.0-stage → 1.0.0

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,75 @@
-# 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 simulated dimensions.
+
+## 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
+- Structured tool output (`outputSchema` / `structuredContent`) plus human readable text
+- Tool annotations for safe client automation
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `getBlock` | Get the block at coordinates in a dimension (defaults to `overworld`) |
+| `setBlock` | Place a block at coordinates in a dimension and return the replaced block |
+| `getItem` | Look up item properties by id (`minecraft:diamond_sword` or `diamond_sword`) |
+
+## 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` | Simulated dimension index with world state |
+| `lzimul://minecraft/dimensions/{type}` | Single dimension state including placed blocks |
+
+## Project Structure
+
+```text
+src/
+  index.ts        Entry point
+  app/            Server assembly
+  config/         Server metadata, dimensions, world limits
+  data/           Generated registry data (blocks, items, version)
+  enums/          Enumerations (EBoundingBox, EIconTheme, EDimensionType)
+  interfaces/     Interfaces (IBlock, IItem, IDimension, IPlacedBlock, IDataEntry)
+  resources/      Resource registration
+  schemas/        Zod schemas and converters
+  tools/          Tool registration
+  world/          Simulated dimension world state
+scripts/
+  generate-data.mjs   Regenerates src/data from minecraft-data
+  smoke-test.mjs      End-to-end smoke test
+  clean.mjs           Removes build output
+```
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run build` | Lint, compile and generate API docs |
+| `npm run dev` | Build then start the server |
+| `npm start` | Start the server (stdio) |
+| `npm test` | Run the end-to-end smoke 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() {
+    const server = new McpServer(SERVER_INFO);
+    registerTools(server);
+    registerResources(server);
+    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.0',
+    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/world-limits.js

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