# Cobble MCP 🧱🤖

<p align="center">
  <strong>Autonomous AI Minecraft Companion & Model Context Protocol (MCP) Server</strong>
</p>

<p align="center">
  <a href="https://github.com/brian-mwirigi/cobble-mcp"><img src="https://img.shields.io/badge/GitHub-brian--mwirigi%2Fcobble--mcp-181717?logo=github" alt="GitHub Repo"></a>
  <img src="https://img.shields.io/badge/Minecraft-1.21.x-5b8c32?logo=minecraft" alt="Minecraft 1.21">
  <img src="https://img.shields.io/badge/Node.js-%3E%3D20.10-339933?logo=node.js" alt="Node Version">
  <img src="https://img.shields.io/badge/Protocol-MCP-4C1" alt="Model Context Protocol">
  <img src="https://img.shields.io/badge/AI-Gemini%202.5%20Flash-4285F4?logo=google" alt="Gemini Powered">
  <img src="https://img.shields.io/badge/Tests-141%20Passed-brightgreen" alt="Tests">
  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
</p>

---

Created and maintained by **[Brian Mwirigi](https://github.com/brian-mwirigi)**, **Cobble MCP** transforms a standard Minecraft bot into a sentient, survival-ready AI companion. 

Cobble MCP operates on a **dual-engine architecture**:
1. **Full Model Context Protocol (MCP) Server**: Directly controls Minecraft through [Claude Desktop](https://claude.ai/download), Antigravity IDE, Cursor, or any MCP-compatible AI client.
2. **Autonomous Gemini 2.5 Companion Brain**: A built-in real-time perception engine with 360-degree spatial awareness, survival reflex watchdogs, combat bodyguard instincts, and voice/chat interaction.

---

## 🌟 Key Features

### 🛡️ Autonomous Bodyguard & Threat Radar
- **22-Meter Dual Radar**: Continuously scans the environment around both the bot and the player.
- **Auto-Engage Combat**: The moment a threat enters the perimeter, the bot draws its weapon, pathfinds dynamically toward the mob, and strikes until defeated.
- **Boss & Flying Combat**: Extended hit reach and aerial pursuit for **Ender Dragons**, **Withers**, **Wardens**, **Endermen**, and all standard hostile mobs.
- **Auto-Equip Arsenal**: Instantly equips best armor (Netherite/Diamond) and highest-damage weapon prior to swinging.
- **Seamless Follow Resumption**: Automatically gathers dropped loot and runs back to your side the moment combat ends.

### 🚶 House-Safe Player Escort & Navigation
- **Anti-Grief Pathfinder**: Configured with `canDig = false` and `allow1by1towers = false` so the bot **never breaks walls, roofs, or doors** when navigating inside player houses.
- **Dynamic Tracking**: Follows moving players smoothly with door-opening and parkour abilities.

### 🏗️ Architectural Survey & Multi-Phase Construction
- **Site Survey Engine (`survey-site`)**: Scans topography, elevation profiles, ground slope, clearance volume, and obstacle densities before building.
- **Voxel Construction Engine (`build`, `mc_build`)**: Multi-phase bottom-to-top automated construction with material calculations, error recovery, and pause/resume tracking.
- **Automated Blueprints**: Build emergency bunkers, domes, shelters, houses, walls, and towers on demand.

### ⛏️ Smart Gathering & Inventory Sharing
- **Heuristic Mining (`gather-resource`)**: Automatically selects the optimal harvest tool (axes for logs/wood, pickaxes for stone/ores, shovels for dirt/sand).
- **Item Gifting (`drop-item`)**: Tossa weapons, armor, or mined materials directly to the player at any time.

### 🍲 Survival & Reflex Watchdogs
- **Auto-Eat Watchdog**: Monitors hunger and health, proactively consuming high-saturation food (Golden Carrots, Cooked Beef, Enchanted Apples).
- **Hazard Avoidance**: Automatically douses fire by jumping into nearby water, sleeps through the night in nearby beds, or digs emergency survival shelters when trapped.

---

## 📋 Available MCP Tools (30+)

| Category | Tools | Description |
| :--- | :--- | :--- |
| **Combat & Defense** | `attack-entity`, `health-status`, `flee-threats` | Autonomous mob hunting, health checks, tactical retreat |
| **Survey & Building** | `survey-site`, `build`, `build-status`, `cancel-build` | Terrain analysis, blueprint construction, status tracking |
| **Gathering & Inventory**| `gather-resource`, `collect-drops`, `list-inventory`, `find-item`, `equip-item`, `drop-item` | Smart resource mining, drop pickup, inventory management |
| **Movement & Flight** | `get-position`, `move-to-position`, `look-at`, `jump`, `move-in-direction`, `fly-to` | Precise navigation, aerial creative flight, camera control |
| **World Interaction** | `place-block`, `dig-block`, `get-block-info`, `find-blocks`, `smelt-item` | Block manipulation, inspection, furnace management |
| **Survival & Social** | `eat-food`, `sleep-or-shelter`, `send-chat`, `read-chat`, `detect-gamemode` | Nutrition, resting, chat communication, gamemode checks |

---

## 🚀 Getting Started

### Prerequisites
- **Node.js**: `>= 20.10.0`
- **Git**
- **Minecraft Java Edition**: Tested with version `1.21.x`

### Installation

```bash
# Clone the repository
git clone https://github.com/brian-mwirigi/cobble-mcp.git
cd cobble-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

### Setup Environment

Create a `.env` file in the project root:

```env
# Optional: Required if using autonomous Gemini in-game companion chat
GEMINI_API_KEY=your_gemini_api_key_here
```

---

## 🤖 Using with Claude Desktop

Open your Claude Desktop configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the `cobble-mcp` server:

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "C:/path/to/cobble-mcp/dist/main.js",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "ClaudeBot"
      ]
    }
  }
}
```

> [!TIP]
> For remote multiplayer or hosted servers (e.g. Aternos):
> Set `--host` to your server address (e.g. `yourserver.aternos.me`) and `--port` to your server's assigned port.

---

## 🎮 Running Minecraft

1. Launch Minecraft Java Edition `1.21.x`.
2. Start a singleplayer world and open it to LAN (`ESC` $\rightarrow$ **Open to LAN**), or join your server.
3. Start Claude Desktop or run the standalone companion:

```bash
npm start -- --host localhost --port 25565 --username AntigravityBot
```

---

## 🧪 Testing

Cobble MCP comes with a comprehensive suite of 140+ unit and integration tests:

```bash
npm test
```

---

## 👤 Author

**Brian Mwirigi**
- GitHub: [@brian-mwirigi](https://github.com/brian-mwirigi)
- Repository: [brian-mwirigi/cobble-mcp](https://github.com/brian-mwirigi/cobble-mcp)

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).