Metadata-Version: 2.4
Name: minecode-mcp
Version: 0.1.1
Summary: MCP Server for Minecraft datapack development with wiki, Spyglass, Misode, and Mojira integrations
Project-URL: Homepage, https://github.com/yourusername/minecode-mcp
Project-URL: Repository, https://github.com/yourusername/minecode-mcp
Project-URL: Issues, https://github.com/yourusername/minecode-mcp/issues
Author-email: Your Name <your.email@example.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,copilot,datapack,mcp,minecraft
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: mcp>=1.25.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# 🎮 MineCode

**MCP Server for Minecraft Datapack Development**

MineCode is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.

![Python](https://img.shields.io/badge/Python-3.10+-blue)
![MCP](https://img.shields.io/badge/MCP-1.25.0-green)
![License](https://img.shields.io/badge/License-MIT-yellow)

---

## ✨ 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

```bash
# 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:

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

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```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)

```json
{
  "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](https://minecraft.wiki) | Game mechanics, items, mobs, tutorials |
| **Mojira** | [bugs.mojang.com](https://bugs.mojang.com) | Bug reports, known issues |
| **Spyglass MC** | [api.spyglassmc.com](https://api.spyglassmc.com) | Registries, commands, block states |
| **Misode mcmeta** | [github.com/misode/mcmeta](https://github.com/misode/mcmeta) | Vanilla presets, generators |

---

## 🔧 Development

### Setup

```bash
# 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

```bash
# 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

```bash
# 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](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol that makes this possible
- [Spyglass MC](https://spyglassmc.com/) - For the comprehensive Minecraft data API
- [Misode](https://misode.github.io/) - For the datapack generators and vanilla presets
- [Minecraft Wiki](https://minecraft.wiki/) - For the game documentation

---

<p align="center">
  Made with 💜 for the Minecraft community
</p>
