# 🎨 Pixel Art MCP

> An [MCP](https://modelcontextprotocol.io) server that turns text prompts into
> cozy **pixel-art PNGs** — using a **free, no-API-key** image backend — and
> saves them straight into your project.

Point Claude (or any MCP client) at this server and ask for *"a cozy library
interior, side view, warm afternoon light"*; it generates the image, crushes it
down into authentic, palette-limited pixel art, and writes the PNG to disk. Built
originally to make scene art for a pixel study-game, but useful for any game/app
that needs quick, consistent pixel assets.

<!-- Replace with a real screenshot once you have one -->
<!-- ![sample](docs/sample.png) -->

---

## ✨ Features

- **Text → pixel art** in one call, saved as a ready-to-use PNG.
- **Free by default** — uses [Pollinations](https://pollinations.ai) (no API key, no signup).
- **Real pixel-art post-processing** — the model output is downscaled to a true
  pixel grid (nearest-neighbor) and **palette-quantized**, so it looks like
  pixel art, not just a blurry "pixel-ish" render.
- **Pluggable backends** — swap to Hugging Face (free token) or a local Stable
  Diffusion endpoint by changing one function / env var.
- **Project-agnostic output** — relative paths resolve against `PIXEL_OUT_DIR`,
  so the same server serves any project.
- **Two tools**: generate from a prompt, or pixelate an image you already have.
- **Tiny & hackable** — one `server.py`, ~200 lines, easy to extend.

## 🧠 How it works

MCP servers expose *tools* to an LLM. This one talks to the client (e.g. Claude
Code) over stdio using JSON-RPC; the client launches it, lists its tools, and
calls them when the model decides to.

```
prompt ──▶ style preamble ──▶ free image backend (HTTPS)
                                     │  raw image bytes
                                     ▼
                            Pillow: resize to WxH (NEAREST)
                                     │
                            quantize to N colors (median cut)
                                     ▼
                            save PNG ──▶ PIXEL_OUT_DIR/<out_path>
```

The "make it look like real pixel art" step is the downscale + palette quantize,
not the model — that's the part worth keeping no matter which backend you use.

## 📦 Requirements

- **Python 3.10+**
- Outbound HTTPS at generation time (to the chosen backend)
- An MCP client (e.g. [Claude Code](https://claude.com/claude-code))

## 🚀 Install

```bash
git clone https://github.com/uncagedspirit/pixel-art-mcp.git
cd pixel-art-mcp

python -m venv .venv
# Windows:
.venv/Scripts/python.exe -m pip install -r requirements.txt
# macOS / Linux:
# .venv/bin/python -m pip install -r requirements.txt
```

Optionally install it as a package (gives you a `pixel-art-mcp` command):

```bash
.venv/Scripts/python.exe -m pip install .
```

## 🔌 Register with Claude Code

Add an entry to your project's `.mcp.json` (or your global Claude config).

**Windows**

```json
{
  "mcpServers": {
    "pixel-art": {
      "command": "C:/path/to/pixel-art-mcp/.venv/Scripts/python.exe",
      "args": ["C:/path/to/pixel-art-mcp/server.py"],
      "env": { "PIXEL_OUT_DIR": "C:/path/to/your/project" }
    }
  }
}
```

**macOS / Linux**

```json
{
  "mcpServers": {
    "pixel-art": {
      "command": "/path/to/pixel-art-mcp/.venv/bin/python",
      "args": ["/path/to/pixel-art-mcp/server.py"],
      "env": { "PIXEL_OUT_DIR": "/path/to/your/project" }
    }
  }
}
```

Then **restart Claude Code** and approve the `pixel-art` server. The CLI
alternative: `claude mcp add pixel-art -- <python> <server.py>`.

> `PIXEL_OUT_DIR` sets where generated files land (defaults to the working
> directory). Set it to the project you want assets written into.

## 🛠️ Tools

### `generate_pixel_art(prompt, out_path, width=160, height=90, colors=32, seed=None)`
Generate a pixel-art PNG from a prompt.

| Arg | Meaning |
|-----|---------|
| `prompt` | What to draw |
| `out_path` | Where to save (relative → under `PIXEL_OUT_DIR`) |
| `width`,`height` | Pixel-grid size. `160x90` for 16:9 scenes; `32`–`64` for sprites |
| `colors` | Palette size; `16`–`32` reads as retro |
| `seed` | Optional, for reproducible results |

### `pixelate_image(in_path, out_path, width=160, height=90, colors=32)`
Pixelate an image you already have into a matching style.

## 🎚️ Backends

Set `PIXEL_BACKEND`:

| Value | Free? | Setup |
|-------|-------|-------|
| `pollinations` (default) | ✅ | nothing — no key |
| `huggingface` | free tier | set `HF_TOKEN` (and optionally `HF_MODEL`) |

To use a **local Stable Diffusion** (best quality/control, needs a GPU), add a
backend function that POSTs to your local endpoint (e.g. AUTOMATIC1111 /
ComfyUI / SD.Next) and wire it into `_generate_raw`. The post-processing stays
the same.

## 🧪 Quick test (without an MCP client)

```bash
.venv/Scripts/python.exe -c "import server; print(server.make_pixel_art('cozy cafe interior, side view, warm lamps', 'out/cafe.png', 160, 90, 32, 1))"
```

## 🗺️ Roadmap / ideas

- [ ] `chroma_key` tool — generate sprites on a solid background and key it out
      for **transparent characters/props**.
- [ ] **Sprite-sheet / animation frames** (e.g. N-frame idle loops, packed into a strip).
- [ ] **Palette locking** — pass a fixed palette so a whole asset set shares colors.
- [ ] **Tileset / tilemap** export (Tiled-friendly) for maps.
- [ ] **Batch generation** from a manifest (one call → a whole scene set).
- [ ] **Upscaled preview** output alongside the true-resolution PNG.
- [ ] More backends (Replicate, local ComfyUI workflow, Retro Diffusion).
- [ ] Optional **background removal** / auto-trim for props.
- [ ] Deterministic, seed-pinned regeneration + a small results gallery.

Contributions welcome — open an issue or PR.

## 🤝 Contributing

1. Fork & branch.
2. Keep `server.py` small; put new capabilities behind new `@mcp.tool()` functions.
3. Prefer pure helper functions (like `make_pixel_art`) so logic is testable
   without the MCP transport.
4. Update this README's tool list + roadmap.

## ⚠️ Notes

- Pollinations is a free community service: it can be slow/rate-limited and you
  should review its terms for your intended (especially commercial) use.
- This is a **generation/dev tool**. It makes network calls when generating; the
  output is plain local PNGs you commit into your project.

## 📄 License

[MIT](LICENSE) — do whatever, just keep the notice.