mc-asset — Minecraft Pixel Asset Engine

mc-asset

English | 繁體中文 | 简体中文

mc-asset is a texture and model tool for Minecraft Java Edition resource packs, built for both creators and AI agents over the command line (CLI) or MCP.

Language models can't place pixels by eye, so mc-asset turns texture work into text and commands: draw a sprite as a character grid, pixelize reference art, generate tiling textures, pack animation sheets, preview cuboid models, and validate a whole resource pack, from a shell or over MCP. The same input and seed always produce identical files.

*Six 16×16 items, each written as a text grid and drawn by mc-asset render (shown ×6), following the vanilla style rules in the minecraft-pixel-art skill. The grids are in docs/assets/showcase/items/.*

---

Contents

• What It Does
• Highlights
• Showcase
• Installation
• For AI agents
• Quickstart
• Practical Recipes
• MCP Server
• Command Reference
• Batch Operations (--operations)
• Architecture & Reliability Guarantees
• Development
• License

---

What It Does

• Draw textures from text character grids (render)
• Downsample reference art into pixel art (pixelize) and reduce colors (quantize)
• Fan one sprite out into material variants (variant)
• Generate and seam-check tiling textures (generate, tile)
• Pack animation sprite sheets and write .mcmeta files (animate, mcmeta)
• Scale GUI sprites with nine-slice borders (gui-scale)
• Compare two PNGs pixel by pixel (compare)
• Validate a single texture or a whole resource pack (validate, validate-pack)
• Losslessly compress PNGs (optimize)
• Create, validate, and preview Java block models (model)
• Author complete resource packs from declarative recipes, audit styles, catalog vanilla assets, and export reproducible zips (pack, style)
• Expose all capabilities to AI agents over an MCP server (mcp)

---

Highlights

• Text in, texture out. Sprites are character grids (.grid) or editable multi-layer sources (.mcpx) that build to PNG. See docs/mcpx-format.md.
• Identical output. No unseeded randomness and integer-only color blending, so PNG and .mcpx output is identical run to run and between Bun and Node.
• One engine, two front ends. The CLI and the stdio MCP server call the same core, so an agent gets the exact same result as a shell script.
• Uniform JSON output. --json always returns { success, result, error } with a stable error code, and logs never mix into stdout data.
• No surprise writes. Every output path is explicit, existing files need --force, and each file is written to a temp file before being renamed into place.

---

Showcase

Every image below is produced by mc-asset itself, with fixed seeds for the generated textures, so the whole set is reproducible. The commands live in docs/assets/showcase/README.md.

Material variants — the sword from the top of this page fanned out into all nine built-in materials (copper, crystal, diamond, gold, iron, netherite, oxidized_copper, stone, wood, shown ×5). Its palette gives each color a role, so the blade and guard take the new ramp while the darkest outline, the white glint, the wooden grip, and the guard's gem keep their colors:

Generated patterns — every generate pattern as a 16px swatch from a fixed seed (shown ×4):

| noise | clustered-noise | stripes | checker | gradient | |:-:|:-:|:-:|:-:|:-:| | | | | | | | brick | spots | veins | cracks | grain | | | | | | |

Seamless tiling — a 16px brick block face (left, ×8) and a 4×4 wall of it (right, ×4); the mortar lines continue across every edge:

Block textures — stone, dirt, and oak planks as 16×16 textures (left, ×8) that tile cleanly across all four edges. On the right is a 4×4 wall of the planks texture (×4):

Animation sheet — four frames of a glowing ore block packed into one vertical strip (×4), the layout Minecraft reads with an .mcmeta animation:

Potion variants and compare — the potion recolored into crystal, gold, and iron (×5) while the glass bottle, wooden cork, and white glint keep their colors; compare of the iron and gold variants finds 72 changed liquid pixels, marked in magenta on the diagnostic (×8):

Button nine-slice — a 16px button frame (left, ×4) scaled to 48×16 with nine-slice (middle, ×4) and with plain stretch (right, ×4); the nine-slice keeps the corners and bevels crisp while the stretch smears them:

Java model three-view preview — a five-cuboid stepped shrine model (model-shrine.json) using the brick, planks, stone, and glowing ore textures shown above. model preview --size 128 looks at it three times: from the front (north, front), from the side (east, right), and from above (top):

---

Installation

Via npm (recommended)

Run the server straight from the registry — no local install needed:

npx -y mc-asset mcp

Install the CLI globally to get the mc-asset command on your PATH:

npm install -g mc-asset

mc-asset --version

Via Homebrew (macOS / Linux)

brew tap smile-minecraft/tap

brew install smile-minecraft/tap/mc-asset mc-asset --version

Via Bun or Node.js (From Source)

git clone https://github.com/smile-minecraft/mc-asset.git

cd mc-asset bun install --frozen-lockfile bun run build ./bin/mc-asset.js --version

*Prerequisites*: tested with Node.js 22 and Bun 1.3. bun run build needs Bun and ./bin/mc-asset.js needs Node.js; with Bun alone, run bun ./bin/mc-asset.js.

---

For AI agents

• llms.txt — a compact index of the repository for agents.
• llms-full.txt — the same material as a single file: install, the twenty-five MCP tools, batch operations, the error model, and the limits.
• docs/cli-surface.md — the frozen CLI commands, the batch operations specification, and the exit-code registry.
• docs/mcpx-format.md — the editable multi-layer .mcpx and .grid grammar and specification.
• docs/mcp-guide.md — registration, one verbatim capture per MCP tool, and the error model.
• docs/mcp-surface.md — the frozen MCP surface: tool names, inputs, and the read/write contract.
• [AGENTS.md](https:/