ssyubix-pixelart-mcp 0.1.0

MCP server for drawing pixel-art tiles and tilesets for 2D games

ssyubix-pixelart-mcp

MCP server (Python) untuk menggambar pixel art dan menyusun tileset game 2D. Dibangun dengan MCP Python SDK v1.x (stable), transport stdio, dirancang untuk dipakai berdampingan dengan unity-mcp-server dalam satu sesi agent.

Instalasi

Dari PyPI:

pip install ssyubix-pixelart-mcp

Atau dari source:

git clone https://github.com/syuaibsyuaib/ssyubix-pixelart-mcp
cd ssyubix-pixelart-mcp
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .

Menjalankan

python -m pixelart_mcp.server
# atau, jika diinstall dari PyPI:
ssyubix-pixelart-mcp

Menyambungkan ke Claude Desktop / Claude Code

Tambahkan ke claude_desktop_config.json (Claude Desktop) atau lewat claude mcp add (Claude Code):

{
  "mcpServers": {
    "pixelart": {
      "command": "/path/ke/ssyubix-pixelart-mcp/venv/bin/python",
      "args": ["-m", "pixelart_mcp.server"]
    }
  }
}

Daftar tools (23)

Menggambar

• pixelart_create_canvas, pixelart_import_canvas, pixelart_set_pixel, pixelart_draw_line, pixelart_draw_rect, pixelart_draw_circle, pixelart_draw_polygon, pixelart_flood_fill

Manajemen kanvas

• pixelart_clear_canvas, pixelart_flip_canvas, pixelart_duplicate_canvas, pixelart_get_canvas_info, pixelart_get_canvas_preview, pixelart_delete_canvas, pixelart_list_canvases

Palet warna

• pixelart_generate_palette, pixelart_extract_palette

Saran ukuran

• pixelart_suggest_tile_size

Tileset

• pixelart_create_tileset, pixelart_set_tile, pixelart_export_tileset, pixelart_delete_tileset, pixelart_list_tilesets

Alur kerja tipikal

1. pixelart_suggest_tile_size (opsional) — tanya ukuran tile ideal berdasarkan kategori objek atau resolusi layar.
2. pixelart_generate_palette — buat palet warna sesuai gaya/mood.
3. pixelart_create_canvas → pixelart_set_pixel / draw_line / draw_rect / draw_circle / flood_fill — gambar satu tile.
4. pixelart_get_canvas_preview — lihat hasilnya (upscaled PNG) sebelum lanjut.
5. pixelart_create_tileset → pixelart_set_tile (ulangi untuk tiap tile) → pixelart_export_tileset.
6. Hasil export_tileset berupa PNG + JSON metadata (ukuran tile, grid, PPU) — agent bisa lanjut memanggil tool unity-mcp-server untuk slice/import ke proyek Unity.

Menjalankan test

sh claude_tools/run_tests.sh

Struktur

pixelart_mcp/
  server.py      # entry point, registrasi 23 tools
  canvas.py       # primitif gambar piksel
  palette.py      # generator palet
  sizing.py       # heuristik ukuran tile
  tileset.py      # assembly & export tileset
  models.py       # Pydantic input models
  tests/          # 58 unit test
claude_tools/     # helper script (dump schema, run tests)
task.md           # status & catatan pengerjaan
PUBLISHING.md      # panduan publish ke PyPI & MCP Registry resmi

Jika unity-mcp-server tidak tersedia

pixelart_mcp tidak bergantung secara teknis pada unity-mcp-server — semua tool di atas tetap berfungsi penuh tanpanya. Bedanya hanya di langkah terakhir: tanpa unity-mcp-server, hasil pixelart_export_tileset (PNG + JSON metadata) harus diimport manual ke Unity Editor. Berikut langkahnya (berdasarkan Unity Manual resmi), untuk dituntun AI ke user non-teknis:

1. Salin file PNG hasil ekspor ke folder Assets (atau subfolder seperti Assets/Sprites) di dalam project Unity.
2. Di jendela Project, klik file PNG tersebut. Di panel Inspector:
   • Texture Type → Sprite (2D and UI)
   • Sprite Mode → Multiple (karena berisi banyak tile dalam satu sheet)
   • Pixels Per Unit → isi dengan nilai ppu dari file JSON metadata
   • Filter Mode → Point (no filter) — supaya pixel art tetap tajam, tidak blur
   • Compression → None — supaya warna tidak rusak
   • Klik Apply.
3. Klik tombol Sprite Editor di Inspector untuk membuka Sprite Editor.
4. Di Sprite Editor, klik dropdown Slice, pilih tipe Grid By Cell Size, lalu isi Pixel Size dengan tile_width x tile_height dari JSON metadata.
5. Klik Slice, lalu klik Apply di toolbar Sprite Editor.
6. Selesai — setiap tile sekarang jadi sprite terpisah yang bisa di-drag langsung ke Scene atau dipakai di Tilemap.

Semua angka yang dibutuhkan (tile_width, tile_height, ppu) sudah tersedia otomatis di file .json yang dihasilkan pixelart_export_tileset — AI tidak perlu menghitung ulang, tinggal baca dari sana dan sampaikan ke user langkah di atas.

Untuk AI agent yang merawat/mengembangkan proyek ini

Baca AGENTS.md dulu — berisi peta arsitektur, konvensi wajib, checklist menambah tool baru, dan alur menangani kritik/permintaan fitur dari pengguna.

Lisensi

Apache License 2.0 — lihat file LICENSE dan NOTICE.

Publish ke PyPI & MCP Registry

Lihat PUBLISHING.md untuk panduan lengkap (perintah persis, butuh kredensial pribadi — PyPI token & login GitHub OAuth).

Catatan versi SDK

Server ini dibangun di atas v1.x MCP Python SDK (stable, direkomendasikan untuk produksi). SDK v2 masih pre-release per Juli 2026 — belum dipakai di sini sesuai kebijakan "hanya referensi resmi/terbaru yang sudah stabil".