# Airirang Builder

> AI-driven precise Minecraft building via 3D mesh voxelization + /fill greedy meshing + datapack. MCP server. NOT AN OFFICIAL MINECRAFT PRODUCT.

- **Type:** MCP server
- **Install:** `agentstack add mcp-airirang-airirang-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [airirang](https://agentstack.voostack.com/s/airirang)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [airirang](https://github.com/airirang)
- **Source:** https://github.com/airirang/airirang-builder
- **Website:** https://www.npmjs.com/package/airirang-builder

## Install

```sh
agentstack add mcp-airirang-airirang-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AIrirang Builder

**English** | [한국어](README.ko.md)

> **Build precise Minecraft structures from a single natural-language prompt — via MCP.**

> **NOT AN OFFICIAL MINECRAFT PRODUCT.**
> **NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.**

[](LICENSE)
[](package.json)
[](https://modelcontextprotocol.io)

AIrirang Builder collapses the full **3D mesh (.obj) → voxel → greedy-meshed `/fill` → datapack** pipeline into a single MCP tool call (`quick-build`). Where existing Minecraft AI agents fire hundreds of `place-block` calls, AIrirang Builder ships a datapack in one shot and the world renders in seconds with `/function airirang:`.

---

## Quick Start (5 minutes)

### 1. Install

```bash
# Run instantly with npx (recommended)
npx airirang-builder list-presets

# Or install globally
npm install -g airirang-builder
```

Requirements: **Node 20+**, Minecraft **Java Edition 1.20.5 ~ 1.21.x**.

### 2. Register with Claude Desktop

Add this to your Claude Desktop config (`claude_desktop_config.json` — macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "airirang-builder": {
      "command": "npx",
      "args": ["-y", "airirang-builder", "serve"]
    }
  }
}
```

Restart Claude Desktop and the seven tools are exposed automatically.

### 3. First build

In the chat, ask in one line:

> "Build the House_3 preset into `~/minecraft/saves/world/datapacks`."

The client calls the `quick-build` tool **once**. AIrirang Builder then:

1. Loads the preset `.obj` + `.mtl`
2. Voxelizes across multiple materials
3. Compresses to `/fill` commands via greedy meshing
4. Generates `pack.mcmeta` + `data//function/.mcfunction`

→ The datapack is installed straight into your world's `datapacks/` folder.

### 4. Run in Minecraft

```mcfunction
# Once, after entering the world:
/reload
/function airirang:house_3
```

A pitched roof with windows materializes in seconds.

---

## MCP Tools (7)

The `serve` command starts a stdio MCP server, auto-exposed to any MCP-compatible client (Claude Desktop, VSCode Claude, etc.).

| # | Tool | Purpose |
|---|---|---|
| 1 | `list-presets` | Returns the bundled CC0 preset catalog (5 Quaternius models). |
| 2 | `voxelize-preset` | Voxelize + greedy-mesh a preset → array of `/fill` command lines (no disk writes). |
| 3 | `voxelize-custom` | Same pipeline on a user-supplied `.obj` path. |
| 4 | `generate-mcfunction` | Persist a command array to a `.mcfunction` file. |
| 5 | `execute-build` | Wrap an existing `.mcfunction` into a Java Edition datapack. |
| 6 | **`quick-build`** | **The flagship one-shot tool:** load → voxelize → greedy → mcfunction → datapack. |
| 7 | `list-builds` | Lists previously built datapacks under `outRoot`. |

### `quick-build` example call

```jsonc
// MCP tool call (the client generates this automatically; you can also call it directly)
{
  "name": "quick-build",
  "arguments": {
    "presetId": "house_3",
    "name": "airirang-house3",
    "namespace": "airirang",
    "functionId": "house_3",
    "outRoot": "/Users/me/minecraft/saves/world/datapacks",
    "mcVersion": "1.21",
    "pitch": 0.1,
    "fillInterior": true,
    "blockOverrides": {
      "Wood": "minecraft:spruce_planks"
    }
  }
}
```

Response (summary):

```jsonc
{
  "ok": true,
  "datapackRoot": ".../datapacks/airirang-house3",
  "lineCount": 187,
  "cuboidCount": 184,
  "voxelCount": 9421,
  "packFormat": 57,
  "installMessage": "/reload && /function airirang:house_3"
}
```

Pass `objPath` instead of `presetId` to build from your own `.obj`.

### CLI usage

A standalone CLI is available without the MCP server.

```bash
# Preset catalog
npx airirang-builder list-presets

# .obj → voxelize → .mcfunction
npx airirang-builder voxelize path/to/mesh.obj --pitch 0.1 --out mesh.mcfunction

# All the way to a datapack
npx airirang-builder build path/to/mesh.obj \
  --name airirang-mesh --out-root ~/minecraft/saves/world/datapacks

# MCP server mode (what Claude Desktop invokes)
npx airirang-builder serve
```

---

## Why AIrirang Builder

### vs. yuniko-software/minecraft-mcp-server

| Dimension | yuniko-software | **AIrirang Builder** |
|---|---|---|
| Build mechanism | Bot issues a `place-block` MCP call per block | Single `quick-build` call emits a datapack |
| Precision | Bound by bot pathing (blocks occasionally missed) | Deterministic voxel grid, 100% |
| Speed (large build) | Minutes to hours | Seconds (greedy `/fill` compression) |
| Token efficiency | Hundreds–thousands per build (repeated calls) | Tens per build (single call) |
| Input | Natural language + coordinates | Natural language + 3D mesh (`.obj`) or preset |
| License | MIT | Apache-2.0 |

### Compression metrics

- **Quaternius House_3** (`asset/.../House_3.obj`, pitch=0.1): ~9.4K voxels → **≤ 250** `/fill` lines, bbox `[21, 22, 23]`.
- **POC benchmarks** (regression-locked with Vitest):
  - `realistic-building`: ≥ **95%** `/fill` compression
  - `eiffel-lattice`: ≥ **80%** `/fill` compression (even on lattice structures)
- **Minecraft 1.21 measured**: 200 `/fill` lines → pitched roof + windows render fully.

See [poc/](poc/) for the underlying numbers (the POC scripts that produced these metrics).

---

## Bundled Presets — Quaternius CC0

This package bundles five models from [Quaternius](https://quaternius.com)' *Medieval Village Pack — Dec 2020*, released under **CC0 1.0 Universal**.

| `id` | Display Name | Source |
|---|---|---|
| `house_1` | Medieval House (Plaster + Tile Roof) | Quaternius — Medieval Village Pack (Dec 2020) |
| `house_3` | Medieval House 3 (Stone + Timber) | Quaternius — Medieval Village Pack (Dec 2020) |
| `inn` | Medieval Inn | Quaternius — Medieval Village Pack (Dec 2020) |
| `mill` | Medieval Mill | Quaternius — Medieval Village Pack (Dec 2020) |
| `sawmill` | Medieval Sawmill | Quaternius — Medieval Village Pack (Dec 2020) |

- **Author**: Quaternius
- **Source**: 
- **License**: CC0 1.0 Universal — No Rights Reserved
- **Attribution**: Not required by CC0, but AIrirang Builder records the source and author in this README and in `src/presets/manifest.json` by convention.

No Mojang assets (textures, sounds, logos) are bundled. Block identifiers (e.g. `minecraft:spruce_planks`) are resolved at runtime by the game itself — this package contains zero game resources.

---

## License

AIrirang Builder is licensed under the **Apache License 2.0** ([LICENSE](LICENSE)).

Free for any use — personal, education, open source, **and commercial / closed-source** — as long as you retain the copyright and [NOTICE](NOTICE). No copyleft, no separate commercial license required.

---

## Disclaimer

> **NOT AN OFFICIAL MINECRAFT PRODUCT.**
> **NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.**

"Minecraft" is a registered trademark of Mojang Studios. This project bundles **zero** Mojang assets in compliance with the Mojang Commercial Usage Guidelines. We recommend using AIrirang Builder only in single-player worlds or self-hosted servers you control.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and [CHANGELOG.md](CHANGELOG.md) for release notes.

---

*AIrirang Studio*

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [airirang](https://github.com/airirang)
- **Source:** [airirang/airirang-builder](https://github.com/airirang/airirang-builder)
- **License:** Apache-2.0
- **Homepage:** https://www.npmjs.com/package/airirang-builder

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-airirang-airirang-builder
- Seller: https://agentstack.voostack.com/s/airirang
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.