minecode-mcp 0.1.0

MCP Server for Minecraft datapack development with wiki, Spyglass, Misode, and Mojira integrations

🎮 MineCode

MCP Server for Minecraft Datapack Development

MineCode is a Model Context Protocol (MCP) server that supercharges AI assistants like GitHub Copilot, Claude, and ChatGPT with Minecraft-specific knowledge and tools. It provides real-time access to Minecraft data, wiki information, bug tracking, and datapack generators.

---

✨ Features

• 19 MCP Tools for comprehensive Minecraft development
• Real-time Data from multiple authoritative sources
• Version-specific information (blocks, items, commands, registries)
• Datapack Generators access to loot tables, recipes, biomes, dimensions
• Bug Tracking integration with Mojira
• Works with VS Code, Claude Desktop, and any MCP-compatible client

---

🚀 Quick Start

Installation

# From PyPI (recommended)
pip install minecode-mcp

# Or from GitHub
pip install git+https://github.com/yourusername/minecode-mcp.git

# Or for development
git clone https://github.com/yourusername/minecode-mcp.git
cd minecode-mcp
pip install -e .

Configuration

VS Code with GitHub Copilot

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "minecode": {
      "type": "stdio",
      "command": "minecode"
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "minecode": {
      "command": "minecode"
    }
  }
}

Config file locations:

OS	Path
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Alternative (using Python directly)

{
  "mcpServers": {
    "minecode": {
      "command": "python",
      "args": ["-m", "minecode.server"]
    }
  }
}

---

🛠️ Available Tools

Basic Tools

Tool	Description
hello_world	Test connectivity with a hello message
get_minecraft_version	Get info about a specific Minecraft version
validate_datapack	Validate datapack syntax and structure
list_commands	List all Minecraft commands for a version

📚 Minecraft Wiki Tools

Tool	Description
search_wiki	Search Minecraft Wiki for pages
get_wiki_page	Get content and summary of a wiki page
get_wiki_commands	Get list of all Minecraft commands from wiki
get_wiki_category	Get all pages in a wiki category (Blocks, Items, Mobs, etc.)

🐛 Mojira Bug Tracker Tools

Tool	Description
search_mojira	Search for Minecraft bug reports with filters

🔍 Spyglass API Tools

Tool	Description
spyglass_get_versions	Get all Minecraft Java Edition versions with pack formats
spyglass_get_registries	Get registry entries (items, blocks, entities, biomes, enchantments)
spyglass_get_block_states	Get block state properties and default values
spyglass_get_commands	Get command syntax tree for any command

🎨 Misode Generator Tools

Tool	Description
misode_get_generators	List all available datapack generators
misode_get_presets	Get vanilla presets for any generator type
misode_get_preset_data	Get full JSON data for a specific preset
misode_get_loot_tables	Get loot tables by category (blocks, chests, entities)
misode_get_recipes	Get recipes with type filtering (crafting, smelting, etc.)

---

💡 Usage Examples

Ask your AI assistant:

Creating datapacks:

"Create a custom dimension with floating islands and rare ores"

Looking up game data:

"What are all the block states for a redstone repeater in 1.21?"

Finding recipes:

"Show me the crafting recipe for a beacon"

Checking bugs:

"Search Mojira for bugs related to elytra"

Getting command syntax:

"What's the syntax for the /execute command?"

---

📁 Project Structure

MineCode/
├── minecode/                # Main package
│   ├── __init__.py
│   ├── server.py            # MCP server (19 tools)
│   └── scrappers/           # Data fetching modules
│       ├── __init__.py
│       ├── minecraftwiki.py # Minecraft Wiki API client
│       ├── mojira.py        # Mojira bug tracker scraper
│       ├── spyglass.py      # Spyglass MC API client
│       └── misode.py        # Misode mcmeta client
├── example/                 # Example datapacks
│   └── crystal_dimension/   # Custom dimension example
├── server.py                # Standalone server (development)
├── client.py                # Test client
├── pyproject.toml           # Package configuration
├── requirements.txt         # Dependencies
├── LICENSE                  # MIT License
└── .vscode/
    └── mcp.json             # VS Code MCP configuration

---

🌐 Data Sources

Source	URL	Data Provided
Minecraft Wiki	minecraft.wiki	Game mechanics, items, mobs, tutorials
Mojira	bugs.mojang.com	Bug reports, known issues
Spyglass MC	api.spyglassmc.com	Registries, commands, block states
Misode mcmeta	github.com/misode/mcmeta	Vanilla presets, generators

---

🔧 Development

Setup

# Clone the repository
git clone https://github.com/yourusername/minecode-mcp.git
cd minecode-mcp

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Install in editable mode
pip install -e .

Testing

# Test the MCP server with the test client
python client.py

# Test individual scrapers
python -c "from minecode.scrappers import spyglass; print(spyglass.get_versions())"

Building & Publishing

# Install build tools
pip install build twine

# Build the package
python -m build

# Upload to TestPyPI (for testing)
twine upload --repository testpypi dist/*

# Upload to PyPI (production)
twine upload dist/*

---

📦 Example Datapack

The example/crystal_dimension/ folder contains a complete datapack demonstrating MineCode's capabilities:

• Custom Dimension: "The Crystal Void" with unique terrain
• Custom Biome: Purple/cyan themed with special effects
• Custom Features: Crystal ores, amethyst spikes, decorations
• 8 Functions: Teleport, boss spawning, item kits, building tools

Functions included:

Function	Description
/function crystal:teleport	Teleport to The Crystal Void
/function crystal:return	Return to the Overworld
/function crystal:give_kit	Get Crystal Explorer kit
/function crystal:spawn_boss	Summon the Crystal Guardian (500 HP)
/function crystal:build_tower	Build a decorative Crystal Tower
/function crystal:help	Show all available commands

To use it, copy crystal_dimension/ to your Minecraft world's datapacks/ folder.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

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

---

🙏 Acknowledgments

• Model Context Protocol - The protocol that makes this possible
• Spyglass MC - For the comprehensive Minecraft data API
• Misode - For the datapack generators and vanilla presets
• Minecraft Wiki - For the game documentation

---

Made with 💜 for the Minecraft community