ssyubix-pixelart-mcp

# ssyubix-pixelart-mcp

<!-- mcp-name: io.github.syuaibsyuaib/ssyubix-pixelart-mcp -->

MCP server (Python) for drawing pixel art and assembling 2D game tilesets.
Built with [MCP Python SDK v1.x](https://github.com/modelcontextprotocol/python-sdk)
(stable), **stdio** transport, designed to be used alongside
`unity-mcp-server` in a single agent session.

## Installation

From PyPI:
```bash
pip install ssyubix-pixelart-mcp
```

Or from source:
```bash
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 .
```

## Running

```bash
python -m pixelart_mcp.server
# or, if installed from PyPI:
ssyubix-pixelart-mcp
```

## Connecting to Claude Desktop / Claude Code

Add to `claude_desktop_config.json` (Claude Desktop) or via
`claude mcp add` (Claude Code):

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

## Tools List (24)

**Drawing**
- `pixelart_create_canvas`, `pixelart_import_canvas`, `pixelart_set_pixel`, `pixelart_draw_line`, `pixelart_draw_rect`, `pixelart_draw_circle`, `pixelart_draw_polygon`, `pixelart_flood_fill`

**Canvas Management**
- `pixelart_clear_canvas`, `pixelart_flip_canvas`, `pixelart_duplicate_canvas`, `pixelart_get_canvas_info`, `pixelart_get_canvas_preview`, `pixelart_delete_canvas`, `pixelart_list_canvases`

**Color Palette**
- `pixelart_generate_palette`, `pixelart_extract_palette`

**Size Suggestion**
- `pixelart_suggest_tile_size`, `pixelart_suggest_tilemap_layout`

**Tileset**
- `pixelart_create_tileset`, `pixelart_set_tile`, `pixelart_export_tileset`, `pixelart_delete_tileset`, `pixelart_list_tilesets`

## Terminology: Tile vs Tileset vs Tilemap

These are easy to conflate and doing so produces broken/tiny output — a
real bug that happened in production: an agent asked for a "tilemap" got
back a single 32x32 canvas (that's a *tile* size) and shipped it as the
whole map, which looked broken when used at real scale.

- **Tile**: one small square (e.g. 16x16px) — `pixelart_create_canvas`.
- **Tileset**: a sheet of many distinct tiles arranged in a grid (e.g. grass,
  path, water tile types) — `pixelart_create_tileset` + `pixelart_set_tile` + `pixelart_export_tileset`.
- **Tilemap**: a full level/map, composed of many tiles placed across a grid
  (built the same way as a tileset, but every slot is filled to represent
  the actual level layout) — never a single tile-sized canvas.

## Typical Workflow

**For a single asset/tile:**
1. `pixelart_suggest_tile_size` (optional) — ask for ideal tile size based on object category or screen resolution.
2. `pixelart_generate_palette` — create color palette according to style/mood.
3. `pixelart_create_canvas` → `pixelart_set_pixel` / `draw_line` / `draw_rect` / `draw_circle` / `flood_fill` — draw a single tile.
4. `pixelart_get_canvas_preview` — view the result (upscaled PNG) before proceeding.

**For a tileset or a full tilemap/level:**
5. `pixelart_suggest_tilemap_layout` — get the grid (columns/rows) and total pixel
   size needed, from either an explicit tile count or a target screen/level size.
6. `pixelart_create_tileset` with that grid → `pixelart_set_tile` for **every** slot → `pixelart_export_tileset`.
7. The result of `export_tileset` is PNG + JSON metadata (tile size, grid, PPU) —
   the agent can then call `unity-mcp-server` tools to slice/import into a Unity project.

## Running Tests

```bash
sh claude_tools/run_tests.sh
```

## Structure

```
pixelart_mcp/
  server.py      # entry point, registers 23 tools
  canvas.py       # pixel drawing primitives
  palette.py      # palette generator
  sizing.py       # tile size heuristics
  tileset.py      # tileset assembly & export
  models.py       # Pydantic input models
  tests/          # 58 unit tests
claude_tools/     # helper script (dump schema, run tests)
task.md           # status & work notes
PUBLISHING.md      # guide to publish to PyPI & official MCP Registry
```

## If `unity-mcp-server` is Not Available

`pixelart_mcp` is **not technically dependent** on `unity-mcp-server` —
all tools above work fully without it. The difference is only in the final step:
without `unity-mcp-server`, the result of `pixelart_export_tileset` (PNG +
JSON metadata) must be imported manually into Unity Editor. Here are the steps
(based on official Unity Manual), to guide an AI when helping a non-technical user:

1. **Copy the exported PNG file** to the `Assets` folder (or a subfolder like
   `Assets/Sprites`) within your Unity project.
2. In the **Project** window, click on the PNG file. In the **Inspector** panel:
   - **Texture Type** → `Sprite (2D and UI)`
   - **Sprite Mode** → `Multiple` (because it contains many tiles in one sheet)
   - **Pixels Per Unit** → enter the `ppu` value from the JSON metadata file
   - **Filter Mode** → `Point (no filter)` — to keep pixel art sharp, not blurred
   - **Compression** → `None` — to prevent color corruption
   - Click **Apply**.
3. Click the **Sprite Editor** button in the Inspector to open the Sprite Editor.
4. In the Sprite Editor, click the **Slice** dropdown, select **Grid By Cell Size**,
   then enter the **Pixel Size** with `tile_width` x `tile_height` from the JSON metadata.
5. Click **Slice**, then click **Apply** in the Sprite Editor toolbar.
6. Done — each tile is now a separate sprite that can be dragged directly into the
   Scene or used in a Tilemap.

All required values (`tile_width`, `tile_height`, `ppu`) are automatically
available in the `.json` file generated by `pixelart_export_tileset`
— the AI does not need to calculate them, just read them and guide the user
through the steps above.

## For AI Agents Maintaining/Developing This Project

Read `AGENTS.md` first — it contains the architecture map, mandatory conventions,
checklist for adding new tools, and the workflow for handling user feedback/feature requests.

## License

Apache License 2.0 — see `LICENSE` and `NOTICE` files.

## Publishing to PyPI & MCP Registry

See `PUBLISHING.md` for complete guide (exact commands, requires personal
credentials — PyPI token & GitHub OAuth login).

## SDK Version Notes

This server is built on top of **v1.x** MCP Python SDK (stable, recommended
for production). SDK v2 is still pre-release as of July 2026 — not used here
per policy of "only stable/current official references".