Datapack MCP Server

[!WARNING] This project was created using GitHub Copilot Chat's Agent mode. Please use with caution and verify the functionality thoroughly.

MCP (Model Context Protocol) Server for validating Minecraft datapack JSON files using Spyglass.

This server allows AI agents to validate Minecraft datapack JSON files (recipes, advancements, loot tables, predicates, etc.) against the official Minecraft data formats.

Features

• ✅ Validates datapack JSON files using Spyglass' mcdoc type system
• 🎯 Supports all datapack JSON types (recipes, advancements, loot tables, predicates, etc.)
• 🔄 Supports any Minecraft version or pack format
• 🚀 Easy to use with MCP-compatible AI agents

Installation

Using npx (Recommended)

You can run this server directly from GitHub without installing:

npx github:sharo-jef/datapack-mcp-server

Local Installation

git clone https://github.com/sharo-jef/datapack-mcp-server.git
cd datapack-mcp-server
npm install
npm run build

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "datapack-validator": {
      "command": "npx",
      "args": ["-y", "github:sharo-jef/datapack-mcp-server"]
    }
  }
}

Or if you have it installed locally:

{
  "mcpServers": {
    "datapack-validator": {
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "/path/to/datapack-mcp-server/src/index.ts"
      ]
    }
  }
}

With Other MCP Clients

Any MCP-compatible client can connect to this server using stdio transport.

Tool: validate_datapack_json

Validates Minecraft datapack JSON files.

Parameters

• type (required): The type of datapack file
  • Supported types: advancement, loot_table, predicate, item_modifier, recipe, text_component, chat_type, damage_type, dialog, dimension, dimension_type, worldgen/biome, worldgen/carver, worldgen/configured_feature, worldgen/placed_feature, worldgen/density_function, worldgen/noise, worldgen/noise_settings, worldgen/structure, worldgen/structure_set, worldgen/template_pool, tags/block, tags/item, tags/entity_type, tags/function
• content (required): The JSON content to validate (as a string, must be valid JSON parseable by JSON.parse)
• version (optional): Minecraft version (e.g., 1.21.11)
• packFormat (optional): Data pack format number (e.g., 48 for 1.21.4-1.21.11)
  • Prefer packFormat over version when available - it is more precise as multiple Minecraft versions can share the same pack format

Note: Either version or packFormat must be specified.

Example Usage

// Example request from an AI agent
{
  "type": "recipe",
  "content": "{\"type\":\"minecraft:crafting_shaped\",\"pattern\":[\"###\",\"# #\",\"###\"],\"key\":{\"#\":{\"item\":\"minecraft:stick\"}},\"result\":{\"item\":\"minecraft:chest\"}}",
  "version": "1.21.11"
}

Response

Valid JSON:

✓ Valid recipe JSON for Minecraft 1.21.11

Invalid JSON:

✗ Invalid recipe JSON:

error 1:1 Unknown property 'invalid_field'
error 5:10 Expected string, got number

Development

Build

npm run build

Watch Mode

npm run dev

Run Locally

npm start

Test

npm test

Technical Details

This server uses:

• Spyglass: For JSON validation against Minecraft's mcdoc type system
  • @spyglassmc/core
  • @spyglassmc/java-edition
  • @spyglassmc/json
  • @spyglassmc/mcdoc
  • @spyglassmc/nbt
  • @spyglassmc/locales
• MCP SDK: For Model Context Protocol support (@modelcontextprotocol/sdk)
• TypeScript: Native execution in Node.js v20.10.0+

The validation logic is based on misode/misode.github.io's Spyglass integration.

License

This project is licensed under the MIT License - see the LICENSE file for details.

This project includes code based on misode/misode.github.io, which is also licensed under the MIT License.

Credits

• Spyglass - The validation engine
• misode - For mcmeta data and Spyglass integration code
• Model Context Protocol - MCP specification