mc-asset

English | 繁體中文 | 简体中文

A pixel-native 2D asset creation engine and deterministic CLI/MCP toolchain for Minecraft Java Edition resource packs, designed for human creators and AI coding agents.

mc-asset bridges the gap where language models struggle with visual pixel art. It provides deterministic pixel manipulation, procedural pattern generation, seamless tiling analysis, animated sprite sheet packaging, palette quantization, and resource pack validation.

Highlights

• Pixel-Native Engine: All raster formats and editable text specifications map directly to an in-memory PixelCanvas with integer coordinates and strict layer/region bounds.

• Strict Determinism: Zero unseeded randomness and zero floating-point drift. Re-running a command with the same inputs and seed produces byte-identical PNG and .mcpx files across both Bun and Node runtimes.

• Agent-First Architecture: Clean separation between standard output and diagnostic logs. All core operations support --json structured envelopes with standardized error codes.

• Dual Interface (CLI & MCP): A unified Core engine powers both a command-line interface and a native Model Context Protocol (MCP) server for integration with AI assistants (Claude Desktop, Cursor, and OpenCode).

• Filesystem Safety: Refuses implicit output filenames. Implements per-file atomic staging (O_EXCL temp files + rename), collision detection with Unicode NFC and case-folding, and guards against accidental overwrites.

Related MCP server: material-workbench

Showcase

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

Material variants — one source fanned out into four ramps (iron, gold, wood, crystal); the shape stays the same and only the palette changes:

Seamless tiling — a single 32px seamless tile (left, ×4) and a 2×2 repeat of it (right, ×4); the edges meet with no visible seam:

Animation sheet packed from individual frames:

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

Via Homebrew (macOS / Linux)

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

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

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-one MCP tools, batch operations, the error model, and the limits.

• 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 — the rules for changing this repository.

Quickstart

1. From ASCII Grid to Validated Texture

Create a 16×16 sprite using human-readable text syntax:

mkdir -p /tmp/mc-asset-demo
cat << 'EOF' > /tmp/mc-asset-demo/gem.grid
[palette]
. = transparent
R = #E74C3CFF
D = #C0392BFF
L = #F1948AFF
W = #FFFFFFFF

[grid]
................
......LLLL......
.....LRRRRD.....
....LRRRRRRD....
...LRRRWWRRRD...
...LRRWWWRRRD...
..LRRRWWWRRRRD..
..LRRRRRRRRRRD..
..LRRRRRRRRRRD..
..LRRRRRRRRRRD..
...DRRRRRRRRD...
...DRRRRRRRRD...
....DRRRRRRD....
.....DRRRRD.....
......DDDD......
................
EOF

Render the grid into a PNG texture and save the editable .mcpx source:

mc-asset render /tmp/mc-asset-demo/gem.grid \
  --output /tmp/mc-asset-demo/gem.png \
  --source /tmp/mc-asset-demo/gem.mcpx
# ok render profile=generic applied=0 output=/tmp/mc-asset-demo/gem.png source=/tmp/mc-asset-demo/gem.mcpx

Analyze color metrics and alpha distribution:

mc-asset analyze /tmp/mc-asset-demo/gem.png
# dimensions: 16x16
# colors: 5
# alpha: predicted cutout (opaque=124 transparent=132 partial=0)
# dominant: #00000000 x132 (0.5156), #E74C3CFF x84 (0.3281), #C0392BFF x20 (0.0781), #F1948AFF x12 (0.0469), #FFFFFFFF x8 (0.0313)
# profile: predicted profile generic has no Minecraft-specific restrictions.
# palette: colorCount=5 alphaLevels=2 transparent=132 partial=0
# pixel-art: 16x16 aspect=1:1 isolated=0 semiTransparent=0 tileFriendly=true
# recommended: quantize.colors=8 cleanup=none resize=nearest

Validate the asset for Minecraft resource pack compliance:

mc-asset validate /tmp/mc-asset-demo/gem.png --profile minecraft:item
# verdict: pass
# dimensions: 16x16
# colors: 5
# alpha: predicted cutout (opaque=124 transparent=132 partial=0)
# profile: predicted profile minecraft:item prefers the items atlas without mipmaps.

Practical Recipes

Recipe 1: Downsampling Reference Art (pixelize)

Convert high-resolution reference art into pixel art with deterministic color reduction and edge alignment:

mc-asset pixelize reference.png \
  --size 16 \
  --preset item \
  --profile minecraft:item \
  --output item_texture.png

• --preset item: Applies 16-color target palette, item-specific boundary preservation, and noise elimination.

• Supported presets: item, block, gui, particle, generic.

Recipe 2: Procedural Textures & Seam Tiling (generate & tile)

Generate a procedural stone texture and check its tiling seamlessness:

# Generate 16x16 procedural noise texture using built-in stone palette
mc-asset generate noise \
  --size 16 \
  --palette stone \
  --seed 42 \
  --output stone.png

# Evaluate horizontal, vertical, and corner seam discontinuity
mc-asset tile stone.png
# ok tile profile=generic seam=h:0.065196 v:0.096051 c:0.003604 repeat=0.908038

# Automatically repair seams and preview 4x4 repeat
mc-asset tile stone.png \
  --edge-match both \
  --preview 4x4 \
  --output stone_preview.png

Recipe 3: Palette Quantization & Artifact Cleanup (quantize & cleanup)

Clean up stray semi-transparent pixels from third-party tools:

# Quantize to 8 colors
mc-asset quantize sprite.png --colors 8 --output quantized.png

# Remove isolated noise and stray pixels
mc-asset cleanup quantized.png \
  --fix isolated,noise \
  --allow-render-pass-change \
  --output clean.png

Recipe 4: Material Variants (variant & recolor)

Fan out a single source asset into multiple material tiers:

mc-asset variant sword.mcpx \
  --materials iron,copper,gold \
  --output-dir ./dist_variants \
  --mkdir
# Writes sword_iron.png, sword_iron.mcpx, sword_copper.png, etc.

Recipe 5: Animated Sprite Sheets (animate)

Pack individual frames into an animated vertical sprite sheet:

mc-asset animate pack \
  --frames-dir ./textures/fire_frames \
  --layout vertical \
  --output ./textures/fire.png

# Validate animation sheet against companion .mcmeta
mc-asset validate ./textures/fire.png --mcmeta ./textures/fire.png.mcmeta

Recipe 6: Full Resource Pack Validation (validate-pack)

Scan an entire resource pack directory for missing texture dependencies, invalid namespaces, unreferenced files, and broken model JSON references:

mc-asset validate-pack ./MyResourcePack \
  --minecraft-version 26.3 \
  --json

MCP Server Integration (For AI Agents)

mc-asset includes a native stdio Model Context Protocol server. Agents interact with the pixel engine directly through structured function calls without subprocess overhead.

The running server exposes 21 tools. scale_gui_asset and all authoring additions (inspect_asset, apply_asset_operations.feedback, ellipse/polygonFill/strokeMask) shipped with v0.3.2; the latest published release is v0.3.2 (2026-09-23).

Exposed MCP Tools

inspect_asset has two modes. structure reports layers (bounds, area, visibility, raw RGBA color usage), regions (identity, bounds, area only), and overlaps. view returns the composited PNG as a standard image block plus six-key metadata, with optional crop and scale (integer 1–16, default 1). Outputs wider than 1024px are refused with RESOURCE_LIMIT_EXCEEDED and a crop hint; the small-image auto-scale applies to apply feedback only, never to inspect view. Image bytes travel as type: "image" and are not duplicated in the text block.

apply_asset_operations accepts an optional feedback object (image: none / full / changed; scale 1–16; crop selection expression; diff none / summary). Omitting it keeps the legacy output byte-for-byte.

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mc-asset": {
      "command": "npx",
      "args": ["-y", "mc-asset", "mcp"]
    }
  }
}

OpenCode

Add to opencode.json or opencode.jsonc:

{
  "mcp": {
    "mc-asset": {
      "type": "local",
      "command": ["npx", "-y", "mc-asset", "mcp"],
      "enabled": true
    }
  }
}

Cursor

Add to your MCP configuration:

{
  "mcpServers": {
    "mc-asset": {
      "command": "npx",
      "args": ["-y", "mc-asset", "mcp"]
    }
  }
}

Command Reference

Batch Operations (--operations)

The import, render, and build commands support batch pixel edits via --operations <path> or --operations - (stdin).

[
  { "type": "setPixel", "x": 0, "y": 0, "color": "#FF0000FF" },
  { "type": "drawLine", "from": [0, 0], "to": [15, 15], "color": "#00FF00FF" },
  { "type": "fillRect", "rect": { "x": 2, "y": 2, "width": 4, "height": 4 }, "color": "#FFFF00FF" },
  { "type": "floodFill", "x": 5, "y": 5, "color": "#0000FFFF" },
  { "type": "clearPixel", "x": 0, "y": 0 }
]

• Atomicity: Execution is all-or-nothing. If an operation fails (e.g. out of bounds), all preceding operations in the batch roll back.

• Color Values: Accepts transparent, #RRGGBB, or #RRGGBBAA.

• Vocabulary: 25 typed variants, including 9 pixel operations (setPixel, clearPixel, drawLine, drawRect, fillRect, floodFill, ellipse, polygonFill, strokeMask) plus layer, region, stampRect, and regionFromSelection operations. The full per-type table lives in docs/cli-surface.md.

• Compact shapes: ellipse takes rect plus color plus mode (fill / outline); polygonFill takes integer [x, y] points plus color, at most 4096 points with no self-intersection and no holes; strokeMask takes layerId plus a source selection plus color, with an optional selection clip. A 4097-point polygon fails with RESOURCE_LIMIT_EXCEEDED before point mapping; a self-intersecting ring fails with SELF_INTERSECTING_POLYGON.

• Selection: Pixel operations accept an optional selection expression; an empty match refuses the write with EMPTY_SELECTION and rolls the batch back.

Architecture & Reliability Guarantees

                  ┌─────────────────────────────────┐
                  │          mc-asset Core          │
                  │  PixelCanvas • IO • Algorithms  │
                  └───────────────┬─────────────────┘
                                  │
                 ┌────────────────┴────────────────┐
                 │                                 │
     ┌───────────▼───────────┐         ┌───────────▼───────────┐
     │     CLI Interface     │         │   Native MCP Server   │
     │  (Terminal & Scripts) │         │  (Stdio Agent Bridge) │
     └───────────────────────┘         └───────────────────────┘

Determinism Model

1. Byte-Identical PNG Encoding: Uses fixed deflate levels and filter strategies (src/io/png.ts) with pure integer color blending. Output files do not embed timestamps or host metadata.

2. Seed-Driven PRNG: Procedural generation relies exclusively on an integer xorshift32 PRNG initialized via --seed.

3. Cross-Runtime Consistency: Output bytes produced under Bun match bytes produced under Node.js byte for byte for the commands covered by the scripts/compare-runtime.mjs matrix.

File & Channel Safety

• Atomic Writes: Every output file is written to a unique temporary file (.tmp-<pid>-<counter>-<randomhex>-<original name>) in the target directory and committed via atomic rename.

• Collision Protection: Paths are resolved to absolute normalized paths folded with Unicode NFC and case-folding. Aliasing the input without --in-place or defining duplicate output targets fails before any bytes land on disk.

• Channel Isolation:

  • Without --stdout: Human logs route to stdout. With --json, a structured { success, result, error } envelope routes to stdout and logs route to stderr.

  • With --stdout: Raw artifact bytes exclusively own stdout. Envelope and logs route to stderr.

Standardized Exit Codes

Development

# Run test suite
bun test

# Run TypeScript type check
bun run test:typecheck

# Run linter
bun run lint

# Build standalone distribution bundles
bun run build

# Verify cross-runtime byte parity (Bun vs Node)
node scripts/compare-runtime.mjs

License

MIT © 2026 Smile Minecraft Project