mc-asset — Minecraft Pixel Asset Engine

mc-asset

English | 繁體中文 | 简体中文

mc-asset は、Minecraft Java Edition のリソースパック向けテクスチャおよびモデルツールです。クリエイターと AI エージェントの両方が、コマンドライン（CLI）または MCP を通じて利用できます。

言語モデルは目で見てピクセルを配置できないため、mc-asset はテクスチャ制作をテキストとコマンドで行えるようにします。文字グリッドでスプライトを描画したり、参照アートをピクセル化したり、タイル状に繰り返せるテクスチャを生成したり、アニメーションシートをまとめたり、直方体モデルをプレビューしたり、リソースパック全体を検証したりできます。シェルからでも、MCP 経由でも利用できます。同じ入力とシードを使えば、常に同一のファイルが生成されます。

バニラスタイルのルールに従って、テキストグリッドで記述し、mc-asset render で描画した 6 種類の 16×16 アイテムです（×6 で表示）。グリッドは docs/assets/showcase/items/ にあります。ルールは minecraft-pixel-art スキルで確認できます。

---

目次

• できること
• 主な特長
• ショーケース
• インストール
• AI エージェント向け
• クイックスタート
• 実用レシピ
• MCP サーバー
• コマンドリファレンス
• バッチ操作（--operations）
• アーキテクチャと信頼性の保証
• 開発
• ライセンス

---

できること

• テキストの文字グリッドからテクスチャを描画します（render）
• 参照アートをピクセルアートに縮小し（pixelize）、色数を減らします（quantize）
• 1 つのスプライトから素材のバリエーションを作成します（variant）
• タイル状に繰り返せるテクスチャを生成し、継ぎ目をチェックします（generate、tile）
• アニメーション用スプライトシートをまとめ、.mcmeta ファイルを書き込みます（animate、mcmeta）
• 九分割スライスの境界を使って GUI スプライトを拡大縮小します（gui-scale）
• 2 つの PNG をピクセル単位で比較します（compare）
• 単一のテクスチャまたはリソースパック全体を検証します（validate、validate-pack）
• PNG を可逆圧縮します（optimize）
• Java ブロックモデルを作成、検証、プレビューします（model）
• 宣言型レシピから完全なリソースパックを作成し、スタイルを監査し、バニラアセットをカタログ化して、再現可能な zip ファイルとしてエクスポートします（pack、style）
• MCP サーバー経由で、すべての機能を AI エージェントに提供します（mcp）

---

主な特長

• テキストを入力して、テクスチャを出力。 スプライトは文字グリッド（.grid）または編集可能なマルチレイヤーソース（.mcpx）で、PNG にビルドできます。詳しくは docs/mcpx-format.md をご覧ください。
• 出力は常に同一。 シードなしのランダム処理はなく、色のブレンドには整数のみを使用するため、PNG と .mcpx の出力は実行ごと、および Bun と Node の間で同一です。
• 1 つのエンジン、2 つのフロントエンド。 CLI と stdio MCP サーバーは同じコアを呼び出すため、エージェントはシェルスクリプトとまったく同じ結果を得られます。
• 統一された JSON 出力。 --json は常に、安定したエラーコードを含む { success, result, error } を返し、ログが stdout のデータに混ざることはありません。
• 予期しない書き込みはありません。 すべての出力パスを明示する必要があり、既存ファイルへの書き込みには --force が必要です。また、各ファイルは一時ファイルに書き込んでから所定の場所に名前を変更します。

---

ショーケース

以下の画像はすべて mc-asset 自体で生成したもので、生成テクスチャには固定シードを使用しているため、セット全体を再現できます。コマンドは docs/assets/showcase/README.md にあります。

ピクセル化	色数削減
→	→
詳細な参照画像（128px、×2 で表示）を 16px（×16 で表示）に縮小します。粒子は粗くなり、形状は整ったピクセルグリッドに沿います。	64 色のグラデーションを 8 色に縮小します（どちらも×4）。色数が減り、結果は明瞭な段階状になります。

素材のバリエーション — このページ上部の剣を、組み込みの 9 種類の素材すべてに展開したものです（copper、crystal、diamond、gold、iron、netherite、oxidized_copper、stone、wood、×5 で表示）。パレットでは各色に役割が与えられているため、刃と鍔は新しい色の階調に変わり、最も暗い輪郭、白い輝き、木製の柄、鍔の宝石は元の色を保ちます。

生成パターン — 固定シードから生成した、すべての generate パターンの 16px スウォッチです（×4 で表示）。

noise	clustered-noise	stripes	checker	gradient
brick	spots	veins	cracks	grain
シームレスなタイル — 16px のレンガブロックの面（左、×8）と、それを4×4に並べた壁（右、×4）です。目地はすべての端で途切れずにつながります：

ブロックテクスチャ — 石、土、オークの板材を16×16のテクスチャ（左、×8）で表現したもので、4辺すべてで綺麗につながります。右側は板材テクスチャを4×4に並べた壁（×4）です：

アニメーションシート — 光る鉱石ブロックの4フレームを1つの縦長ストリップにまとめたもの（×4）です。Minecraft が .mcmeta アニメーションで読み込むレイアウトです：

ポーションのバリエーションと比較 — ポーションを crystal、gold、iron に色替えしています（×5）。ガラス瓶、木製の栓、白い輝きは元の色を保っています。compare で鉄と金のバリエーションを比較すると、液体の色が変わった72ピクセルを検出し、診断画像上にマゼンタで表示します（×8）：

ボタンのナインスライス — 16pxのボタンフレーム（左、×4）を、ナインスライス（中央、×4）と単純な伸縮（右、×4）で48×16に拡大しています。ナインスライスでは角や縁取りが鮮明に保たれますが、伸縮ではにじみます：

Javaモデルの3方向プレビュー — レンガ、板材、石、光る鉱石の各テクスチャ（上図）を使った、5つの直方体で構成される階段状の祠モデル（model-shrine.json）です。model preview --size 128 では、正面（北、front）、側面（東、right）、上方（top）の3方向から確認できます：

---

インストール

npm 経由（推奨）

レジストリからサーバーを直接実行できます。ローカルへのインストールは不要です：

npx -y mc-asset mcp

CLI をグローバルにインストールすると、PATH 上で mc-asset コマンドを使えるようになります：

npm install -g mc-asset
mc-asset --version

Homebrew 経由（macOS / Linux）

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

Bun または Node.js 経由（ソースから）

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

前提条件：Node.js 22 および Bun 1.3 でテスト済みです。bun run build の実行には Bun が必要で、./bin/mc-asset.js の実行には Node.js が必要です。Bun のみを使う場合は、bun ./bin/mc-asset.js を実行してください。

---

AI エージェント向け

• llms.txt — エージェント向けのリポジトリの簡潔なインデックスです。
• llms-full.txt — 同じ内容を単一ファイルにまとめたものです。インストール、25 個の MCP ツール、バッチ操作、エラーモデル、制限を掲載しています。
• docs/cli-surface.md — 固定された CLI コマンド、バッチ操作の仕様、終了コードの一覧です。
• docs/mcpx-format.md — 編集可能な多層 .mcpx および .grid の文法と仕様です。
• docs/mcp-guide.md — 登録、MCP ツールごとの逐語的なキャプチャ、エラーモデルについて説明しています。
• docs/mcp-surface.md — 固定された MCP の仕様範囲です。ツール名、入力、読み取り／書き込みの契約を掲載しています。
• AGENTS.md — このリポジトリを変更する際のルールです。

エージェントスキル

リポジトリには skills/ に Agent Skills が 2 つ含まれており、skills CLI でインストールできます。

npx skills add smile-minecraft/mc-asset

• mc-asset — このツールを使った描画 → レンダリング → プレビュー → 測定 → 検証のループ、CLI／MCP コマンドマップ、パレットの役割が再配色に与える影響について説明しています。
• minecraft-pixel-art — アイテム、ブロック、GUI スプライト、アニメーションのバニラスタイルのルールです。パレットと色相シフトした色の段階、素材の輪郭、左上からの光、タイル化、アンチパターンのレビューチェックリストを扱います。

1 つだけインストールするには、--skill mc-asset または --skill minecraft-pixel-art を追加します。

---

クイックスタート

テキストグリッドから検証済みテクスチャを作成する

16×16 の宝石を、1 ピクセルにつき 1 文字の文字グリッドとして描画します。

mkdir -p /tmp/mc-asset-demo
cat << 'EOF' > /tmp/mc-asset-demo/gem.grid
[palette]
. = transparent
o = #0E1846FF
s = #1E3A8CFF
D = #2448A8FF
m = #3569D0FF
l = #5A92EEFF
t = #7FB2F6FF
T = #A9D2FFFF
W = #FFFFFFFF

[grid]
................
................
......sssss.....
.....sTTTTTo....
....sTTWWTTto...
...sTTWWTTttto..
..slllTTTtttmmo.
..slllllmmmmmDo.
..slllllmmmmmDo.
..slllllmmmmDDo.
...olllmmmmDDo..
....ollmmmDDo...
.....olmmmDo....
......ommDo.....
.......ooo......
................
EOF

グリッドを PNG テクスチャにレンダリングし、編集可能な .mcpx ソースを保存します。

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

レンダリングされた gem.png（×8 で表示）：

色とアルファを確認します。

mc-asset analyze /tmp/mc-asset-demo/gem.png
# dimensions: 16x16
# colors: 9
# alpha: predicted cutout (opaque=119 transparent=137 partial=0)
# dominant: #00000000 x137 (0.5352), #3569D0FF x28 (0.1094), #5A92EEFF x24 (0.0938), #0E1846FF x18 (0.0703), #A9D2FFFF x16 (0.0625), #1E3A8CFF x12 (0.0469), #2448A8FF x10 (0.0391), #7FB2F6FF x7 (0.0273)
# profile: predicted profile generic has no Minecraft-specific restrictions.
# palette: colorCount=9 alphaLevels=2 transparent=137 partial=0
# pixel-art: 16x16 aspect=1:1 isolated=0 semiTransparent=0 tileFriendly=true
# recommended: quantize.colors=16 cleanup=none resize=nearest

Minecraft のアイテムテクスチャとして検証します。

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

---

実践レシピ

レシピ 1：参照画像のダウンサンプリング（pixelize）

高解像度の参照画像を 16×16 のアイテムテクスチャに変換します。同じ画像とプリセットを使うと、常に同じピクセルになります。

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

• --preset item は色数を 16 色に設定し、切り抜き、背景、被写体、エッジ、クラスタリングの各処理を有効にします。
• その他のプリセットは block、gui、particle、generic です。

レシピ 2：プロシージャルテクスチャとシームレスなタイル化（generate と tile）

固定シードで石のテクスチャを生成し、タイル化できるか確認します。

mc-asset generate noise \
  --size 16 \
  --palette stone \
  --seed 42 \
  --output stone.png

# Seam scores: horizontal, vertical, corner (lower is smoother)
mc-asset tile stone.png
# ok tile profile=generic seam=h:0.065196 v:0.096051 c:0.003604 repeat=0.908038

# Match the opposite edges and preview a 4x4 repeat
mc-asset tile stone.png \
  --edge-match both \
  --preview 4x4 \
  --output stone_preview.png

レシピ 3：パレットの量子化とアーティファクトの除去（quantize と cleanup）

スプライトを 8 色に減らし、残った不要なピクセルを取り除きます。

mc-asset quantize sprite.png --colors 8 --output quantized.png

mc-asset cleanup quantized.png \
  --fix isolated,noise \
  --allow-render-pass-change \
  --output clean.png

これらの修正クラスはアルファを変更する可能性があり、それに伴ってテクスチャに必要なレンダーパスも変わるため、cleanup は --allow-render-pass-change なしでは実行を拒否します。

レシピ 4：素材のバリエーション（variant と recolor）

1 つのソースから複数の素材ティアを作成するか、単一の素材に再配色します。ソースには編集可能な .mcpx またはフラットな PNG を指定できます（PNG にはパレットの役割が含まれないため、ピクセルは整数の輝度帯に基づいて対応付けられ、存在しないレイヤーの役割が作られることはありません）。

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.

mc-asset recolor sword.mcpx --material gold --output sword_gold.png

レシピ 5：アニメーションスプライトシート（animate）

フレームのフォルダーを縦方向のシートにまとめ、.mcmeta と照合します。

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

mc-asset validate ./textures/fire.png --mcmeta ./textures/fire.png.mcmeta

レシピ 6：リソースパック全体の検証（validate-pack）

リソースパック全体をスキャンし、テクスチャの欠落、不正な名前空間、孤立したテクスチャ、モデル参照の破損、参照の循環を検出します。--minecraft-version で照合するパック形式を指定します。

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

レシピ 7：視覚的なフィードバックを使った一括編集（build と apply_asset_operations）

Quickstart のジェムを一括編集します。金色の 4×4 の正方形を、黒色の 6×6 の枠で囲みます。CLI は一括処理を適用し、PNG を書き出します。

cat << 'EOF' > /tmp/mc-asset-demo/ops.json
[
  { "type": "fillRect", "rect": { "x": 6, "y": 6, "width": 4, "height": 4 }, "color": "#FFD700FF" },
  { "type": "drawRect", "rect": { "x": 5, "y": 5, "width": 6, "height": 6 }, "color": "#000000FF" }
]
EOF

mc-asset build /tmp/mc-asset-demo/gem.mcpx \
  --operations /tmp/mc-asset-demo/ops.json \
  --output /tmp/mc-asset-demo/gem_modified.png
# ok build profile=generic applied=2 output=/tmp/mc-asset-demo/gem_modified.png

一括処理の前後（どちらも ×8）：

→

MCP では、apply_asset_operations が同じ一括処理を実行し、変更内容を画像で返すこともできます。

{
  "sourcePath": "/tmp/mc-asset-demo/gem.mcpx",
  "operations": [
    { "type": "fillRect", "rect": { "x": 6, "y": 6, "width": 4, "height": 4 }, "color": "#FFD700FF" },
    { "type": "drawRect", "rect": { "x": 5, "y": 5, "width": 6, "height": 6 }, "color": "#000000FF" }
  ],
  "outputPngPath": "/tmp/mc-asset-demo/gem_feedback.png",
  "feedback": { "image": "changed", "scale": 8, "diff": "summary" }
}

feedback を指定すると、通常のフィールドはそのまま保持され、変更された範囲を切り抜いて scale（1～16）倍に拡大した PNG 画像ブロックと、diff の概要（raw、composited、structural、outsideSelectionUnchanged）が追加されます。目に見える変更がない編集では、画像の代わりに noVisibleChange が返されます。エージェントはキャンバス全体を取得せずに編集結果を確認できます。MCP ツールは既存のファイルを上書きしないため、出力先のパスは CLI 実行時とは異なります。

レシピ 8：ナインスライスによる GUI の拡大縮小（gui-scale）

枠線をにじませずに GUI フレームのサイズを変更します。nine_slice を指定すると、角は 1:1 でコピーされ、辺と中央はタイル状に並べられます（stretch_inner: true の場合は引き伸ばされます）。16×16 の dialog.png では、dialog.png.mcmeta で枠線を 4px と指定しています。

{ "gui": { "scaling": { "type": "nine_slice", "width": 16, "height": 16, "border": 4 } } }

mc-asset gui-scale ./textures/gui/dialog.png \
  --mcmeta ./textures/gui/dialog.png.mcmeta \
  --size 48x32 \
  --output ./textures/gui/dialog_large.png
# ok gui-scale profile=generic size=48x32 scaling=nine_slice output=./textures/gui/dialog_large.png

gui-scale は同じディレクトリにある .mcmeta を自動では読み込みません。--mcmeta を指定しない場合、スプライト全体が引き伸ばされます。

元画像、16×16	nine_slice、48×32	--mcmeta なし（引き伸ばし）、48×32

3 枚とも ×4 で表示しています。mcmeta を使うと、切り欠かれた角と 2px の面取り部分が 1:1 でコピーされ、幅も保たれます。通常の引き伸ばしでは、面取り部分の厚さが不均一になり、角がにじみます。

レシピ 9：PNG のロスレス最適化と Java モデル（optimize と model）

optimize は、ピクセルを完全に保持したまま最小サイズになるよう PNG を再エンコードします。サイズが小さくならない場合は、元のファイルをそのまま保持します。明示的に指定した PNG パス（最大 256 ファイル）またはディレクトリ全体（--input-dir、最大 4096 個の PNG、任意で --recursive、相対パスを保持）を受け取ります。入力ファイルを書き換えることはありません。--output、--output-dir、--stdout、または --dry-run を選択してください。

mc-asset optimize ./gem.png --dry-run
# ok optimize input=./gem.png output=- status=optimized source=184 result=102 mode=rgba
mc-asset optimize ./gem.png ./sword.png --output-dir ./optimized --mkdir
mc-asset optimize --input-dir ./textures --recursive --output-dir ./optimized --mkdir

model は Java のブロック／アイテムモデル JSON（直方体の elements のみ）を扱います。モデルを作成し、型指定された操作で編集して、パックに対して検証します。

mc-asset model create --spec ./docs/assets/showcase/model-shrine.json \
  --output ./pack/assets/mypack/models/block/shrine.json --mkdir --resource-pack-version 75
mc-asset model validate ./pack/assets/mypack/models/block/shrine.json \
  --pack ./pack --resource-pack-version 75
mc-asset validate-pack ./pack --resource-pack-version 75

model apply は --operations を受け取り、すべての操作を適用するか、どれも適用しないかのどちらかです。model export はモデルを配置し、--binding を指定すると、アイテム定義とブロックステートをその隣に書き込みます。検査では構造と参照の有効性を確認します。Minecraft クライアントで結果をレンダリングすることはないため、外観やゲーム内での動作は検証されません。

model preview は、直方体の elements から固定の診断画像をレンダリングします。3 つの正方形パネルが横に並びます（front = 北面、right = 東面、top = 上面で北が上）。各パネルのサイズは --size ピクセルです（64、128、または 256。デフォルトは 64）。

mc-asset model preview ./pack/assets/mypack/models/block/shrine.json \
  --pack ./pack --size 128 --output ./shrine-preview.png --resource-pack-version 75

--output または --stdout のいずれか一方を必ず指定してください。レポートには、パネル名と座標、入力範囲、coverage、および warnings が含まれます。テクスチャが見つからない場合は、固定のチェッカーボードでレンダリングされ、警告が表示されます。要素の回転、1/256 単位ではない座標、半透明の面、解決できないテクスチャは、partial の対象として列挙されます。display の変換とゲームのライティングは適用されません。これは診断用のビューであり、ゲームのレンダラーではありません。

---

MCP サーバー

mc-asset mcp は CLI と同じコアを使用する stdio MCP サーバーを起動するため、ツール呼び出しと対応するコマンドは同じ結果を返します。27 個のツールを公開します。

公開される MCP ツール

ツール	機能
analyze_asset	読み取り専用の検査：寸法、パレットの分布、アルファ分類、ピクセルアートのヒューリスティックを確認します。
pixelize_asset	ラスター画像（PNG、JPEG、WebP）をピクセルアートに変換し、PNG バイト列または .mcpx ソースを返します。
render_pixel_asset	インラインの ASCII グリッド文字列または .grid ファイルをコンパイルします。オプションでバッチ操作にも対応します。
apply_asset_operations	.mcpx テキストに対して、ピクセル、レイヤー、領域へのアトミックなバッチ変更を適用します。
recolor_asset	テクスチャのパレットを組み込みのマテリアルランプ（iron、gold、stone など）に合わせて置き換えます。
create_variants	ソースアセットから、マテリアルごとのバリエーションを出力ディレクトリに生成します。
validate_asset	単一のテクスチャと .mcmeta が Minecraft の要件に準拠しているか確認します。
import_asset	ラスター画像（PNG、JPEG、WebP）をピクセルキャンバスにデコードします。オプションでバッチにも対応します。
build_asset	.mcpx ソースを PNG バイト列、または再シリアライズしたソースにビルドします。オプションでバッチにも対応します。
transform_asset	ラスター画像または .mcpx 入力に、1 つのジオメトリ操作（反転、回転、切り抜き、余白追加、サイズ変更、移動）を適用します。
scale_gui_asset	mcmeta の伸縮／タイル／nine_slice マッピングを使って GUI スプライトを拡大縮小します。PNG のみ対応します。
quantize_asset	選択した RGBA 色を維持しながら、固有色数を指定数または明示的なパレットに減らします。
cleanup_asset	ピクセルの欠陥（isolated、noise、cluster、fringe、outlier、hole、aa）を検出または修正します。
palette_asset	読み取り専用のパレット extract／inspect レポート（固有色、分布、役割、コントラスト）を提供します。
material_asset	組み込みマテリアルセットの読み取り専用 list／show レポートを提供します。
tile_asset	継ぎ目、エッジの繰り返し、明るさを分析します。オプションでタイル表示のプレビュー PNG を出力します。
generate_asset	決定論的なプロシージャルテクスチャ生成（パターン、サイズ、パレット、シード）を行います。
preview_asset	ascii／palette-map レポート、および scale と nine-slice のガイド PNG を提供します。
mcmeta_asset	PNG からアニメーションまたは GUI の拡大縮小メタデータを生成します。
animate_asset	フレームセットに対してアニメーションの pack／unpack／reorder／resize／validate／preview を実行します。
validate_pack_asset	読み取り専用のパック全体スキャン：名前空間、モデル、テクスチャ、アトラス、対象バージョンを確認します。
inspect_asset	読み取り専用の structure（レイヤー、領域、色の使用状況、重なり）または view（合成済み PNG 画像ブロックとメタデータ）を提供します。inputPath を指定します。
optimize_asset	PNG を元の内容を正確に保ったまま、最小のエンコーディングに再エンコードします（またはソースをそのまま保持します）。ファイルごとのレポート、dryRun、明示的な outputPath／outputDir、またはディレクトリ全体のスキャン（inputDir、recursive、PNG は最大 4096 個）に対応します。
model_asset	Java のブロック／アイテムモデル JSON：inspect、validate、create、apply、export（アイテム定義とブロックステートのバインディングを含む）、および preview（size／outputPngPath による固定診断用三面 PNG）を提供します。外観のレンダリングではなく、構造と参照をレポートします。
compare_assets	同じサイズの PNG を比較し、RGBA の生の差分と可視差分、範囲、オプションの診断用差分画像をレポートします。
style_asset	スタイルプリセット、カスタムスタイルの作成、パレットのエクスポート、リント、テクスチャファミリーの監査を提供します。
pack_asset	リソースパックのプロジェクト：ひな形の作成（init）、レシピの一括ビルド（build）、テクスチャのカタログ化（catalog）、アセットの抽出（extract）、優先順位付き修正案を含むパック全体のチェック（check）、再現可能な ZIP パッケージ化（package）を行います。
inspect_assetにはstructureとviewの2つのモードがあります。structureはレイヤー、領域、色の使用状況、重なりを報告します。viewは合成後のキャンバスをPNG画像ブロックとして返し、任意でcropとscale（1～16）を指定できます。幅が1024pxを超えるビューは縮小されず、代わりにクロップを促すヒントが表示されます。apply_asset_operationsでは任意のfeedbackオブジェクトを指定できます（レシピ7）。指定しない場合、結果は変更されません。docs/mcp-guide.mdには、各ツールの呼び出し例が1つずつ掲載されています。

設定

どのクライアントでも、同じstdioコマンドnpx -y mc-asset mcpを実行します。設定ファイルの場所はクライアントのバージョンによって異なるため、以下の場所が変更されている場合は、クライアントのドキュメントを確認してください。

Claude Code

claude mcp add mc-asset -- npx -y mc-asset mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.jsonに追加します。

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

Cursor

.cursor/mcp.jsonに追加します。

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

OpenCode

opencode.jsonまたはopencode.jsoncに追加します。

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

---

コマンドリファレンス

カテゴリ	コマンド	説明
取り込みとビルド	import <image>	PNG、JPEG、または WebP をデコードして、PNG および／または .mcpx に変換します。
	render <grid>	ASCII グリッド（.grid）をコンパイルして、PNG および／または .mcpx に変換します。
	build [source]	.mcpx ソースファイルまたは標準入力（--stdin）から PNG をビルドします。
変換とジオメトリ	transform <input>	空間操作：--flip、--rotate、--crop、--pad、--resize、--translate。
カラーとクリーンアップ	quantize <input>	色数（--colors <N>）または明示的なパレット（--palette）を指定して色数を削減します。--keep-color も指定できます。
	cleanup <input>	アーティファクトを除去します（--fix isolated,noise,outlier）。
	palette extract	画像からパレットを抽出します。
	palette inspect	パレットを詳細に分析し、役割を割り当てます。
	material list	組み込みの Minecraft 素材を一覧表示します。
	material show	素材のカラ―ランプを表示します。
	recolor <source>	素材のカラ―ランプを使って .mcpx の色を置き換えます。
	variant <source>	複数の素材バリアントを生成し、--output-dir に出力します。
生成とタイル	generate <pattern>	決定論的なプロシージャルテクスチャを生成します（--seed <int>）。
	tile <input>	継ぎ目を測定し、タイルを自動補正します。
	preview <input>	視覚的なプレビュー：--ascii、--palette-map、--scale <N>、--nine-slice。
	gui-scale <input>	mcmeta の stretch/tile/nine_slice マッピングを使って、GUI スプライトを --size <N|WxH> に拡大縮小します。
アニメーション	animate pack	フレームディレクトリをスプライトシートにまとめます。
	animate unpack	スプライトシートをフレームディレクトリに展開します。
	animate reorder	アニメーションフレームの順序を並べ替えます。
	animate resize	アニメーションフレームのサイズを変更します。
	animate validate	.mcmeta に照らしてフレーム数とレイアウトを検証します。
	animate preview	アニメーションシーケンスを ASCII または診断用プレビューで表示します。
	mcmeta animation|gui	PNG の寸法から .mcmeta アニメーションまたは GUI スケーリングドキュメントを生成します（--output、--stdout）。
検証	analyze <image>	読み取り専用のメトリクス分析を行います（色、アルファ、寸法）。
	inspect <input>	読み取り専用の構造レポートまたは合成ビューを出力します（--mode structure|view、--crop、--scale）。
	validate <asset>	単一アセットのテクスチャと、オプションの .mcmeta を検証します。
	validate-pack <path>	リソースパックのルートディレクトリ全体を検証します。
	compare <before> <after>	同じサイズの 2 つの PNG を比較し、RGBA の生の差異と表示上の差異を報告します。診断用 PNG も任意で出力できます（--output、--stdout、--scale）。
最適化とモデル	optimize <input...> or --input-dir <dir>	PNG を可逆で再エンコードし、完全一致する最小サイズのエンコードを使用するか、ソースのバイト列を保持します（--output、--output-dir、--stdout、--dry-run、--mode、--ancillary、--recursive）。
	model inspect|validate <file>	Java のブロック／アイテムモデル JSON を読み取り専用でレポートします（構造、UV、回転、表示、参照）。
	model create|apply|export	Java モデル（直方体の elements）と、そのアイテム定義および blockstate を作成、編集、または配置します。
	model preview <file>	固定の診断用 3 視点 PNG（front、right、top パネル、--size 64|128|256、--output または --stdout）を出力します。未対応のコンテンツは一部のみカバーされ、ゲーム内のレンダリングではありません。
エージェントインターフェース	mcp	stdio MCP サーバーを起動します。

アニメーションと GUI メタデータ（mcmeta）を生成する

mc-asset mcmeta animation sheet.png --frame-size 16 --frametime 2 --frames '[0,{"index":1,"time":4},0]' --minecraft-version 1.21.2 --output sheet.png.mcmeta
mc-asset mcmeta gui panel.png --type nine_slice --border 4 --stretch-inner --resource-pack-version 42 --stdout

• animation
  • 必須：--frame-size <N|WxH>（PNG を分割する、同じサイズのフレームが並ぶ単一の行または列。グリッドは使用できません）。
  • 任意：--frametime <int>（デフォルトは 1）、--frames <json>（フレームインデックス、または正の整数の時間を指定した {index,time} オブジェクト）、--interpolate。
• gui
  • 必須：--type <stretch|tile|nine_slice>。nine_slice では、非負の left、top、right、bottom と正の中央領域を指定する --border <N|json> も必要です。
  • 任意：--stretch-inner（nine_slice のみ）。GUI スケーリングにはパック形式 16.0 が必要です（stretch_inner には 42.0 が必要です）。バージョンの適用条件と出力オプションについては、docs/cli-surface.md を参照してください。

PNG の変更を比較する（compare）

mc-asset compare before.png after.png --json
mc-asset compare before.png after.png --output diff.png --scale 4
mc-asset compare before.png after.png --stdout --json > diff.png

同じサイズの 2 つの PNG を比較し、rawChangedPixels、visibleChangedPixels、rawBounds、visibleBounds を報告します。--output または --stdout（--scale 1..16、長辺は最大 1024px）を指定すると、可視の変更をマゼンタ（255,0,255,255）、アルファ値ゼロのピクセルで RGB のみが変わった箇所をシアン（0,255,255,255）、変更のないピクセルを透明で示す診断マーカー PNG を書き出します。

---

バッチ操作（--operations）

import、render、build コマンドは、--operations <path> または --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 }
]

• アトミック性：実行はすべて成功するか、すべて失敗します。操作に失敗した場合（範囲外など）、それ以前のバッチ内の操作はすべてロールバックされます。
• 色の値：transparent、#RRGGBB、または #RRGGBBAA を受け付けます。
• 操作の種類：25 種類の型付きバリアントに対応しています。これには 9 種類のピクセル操作（setPixel、clearPixel、drawLine、drawRect、fillRect、floodFill、ellipse、polygonFill、strokeMask）のほか、レイヤー、領域、stampRect、regionFromSelection の各操作が含まれます。種類ごとの完全な表は docs/cli-surface.md を参照してください。
• 図形：ellipse は rect 内の楕円を塗りつぶすか、輪郭を描画します。polygonFill は最大 4096 個の整数 [x, y] 点を受け付けます（それを超える場合は RESOURCE_LIMIT_EXCEEDED、自己交差する輪は SELF_INTERSECTING_POLYGON になり、穴は指定できません）。strokeMask は 1 つのレイヤー上にある source 選択範囲の輪郭を描画します。
• 選択範囲：ピクセル操作では任意の selection 式を指定できます。一致するものがない場合は EMPTY_SELECTION が返されて書き込みが拒否され、バッチはロールバックされます。

---

アーキテクチャと信頼性の保証

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

決定性モデル

1. バイト単位で同一の PNG エンコード：固定の deflate レベルとフィルター戦略（src/io/png.ts）を使用し、色のブレンドは整数演算のみで行います。出力ファイルにタイムスタンプやホストのメタデータは埋め込まれません。
2. シード駆動の PRNG：プロシージャル生成では、--seed で初期化した整数 xorshift32 PRNG のみを使用します。
3. ランタイム間の一貫性：scripts/compare-runtime.mjs のマトリックスで対象となるコマンドでは、Bun で生成された出力バイト列は Node.js で生成されたものとバイト単位で一致します。

ファイルとチャネルの安全性

• アトミックな書き込み：すべての出力ファイルは、出力先ディレクトリ内の一意な一時ファイル（.tmp-<pid>-<counter>-<randomhex>-<original name>）に書き込まれ、アトミックな名前変更によって確定されます。
• 衝突の防止：パスは絶対パスに解決され、Unicode NFC 正規化と大文字・小文字の折りたたみを適用して正規化されます。--in-place を指定せずに入力を別名で指定した場合、または重複する出力先を定義した場合は、ディスクにバイト列を書き込む前に失敗します。
• チャネルの分離：
  • --stdout を指定しない場合：人間向けのログは stdout に出力されます。--json を指定すると、構造化された { success, result, error } エンベロープが stdout に、ログが stderr に出力されます。
  • --stdout を指定した場合：生のアーティファクトバイト列は stdout のみを使用します。エンベロープとログは stderr に出力されます。

標準化された終了コード

終了コード	カテゴリ	意味
0	成功	操作が正常に完了しました。
1	内部エラー	エンジンで未処理のエラーが発生しました（INTERNAL_ERROR）。
2	無効な呼び出し	構文エラー、競合するオプション、パラメーターの不足（INVALID_ARGUMENT）。
3	検証失敗	エンジンの処理は成功しましたが、アセットまたはパックの検証に失敗しました（VALIDATION_FAILED）。
4	ファイルシステムエラー	--force を指定せずに出力先が存在する場合、--mkdir を指定せずにディレクトリが存在しない場合、または入力を読み取れない場合。
5	未対応／上限超過	未対応のファイル形式、またはサイズやリソースの上限を超過した場合。

---

開発

# 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

# Check doc links, anchors, and stray release versions
bun run check:docs

---

ライセンス

MIT © 2026 Smile Minecraft Project