# 🖌️ Pixelorama MCP Bridge

> Local MCP server for deterministic Pixelorama control from any MCP-compatible AI agent. Create, edit, import/export spritesheets, and save .pxo projects programmatically via Godot extension + file-queue transport.

## What is it

An MCP (Model Context Protocol) server that connects any compatible AI agent to [Pixelorama](https://orama-interactive.itch.io/pixelorama) via a Godot extension + file-queue transport. It allows creating projects, editing individual pixels, importing/exporting spritesheets, and saving `.pxo` projects programmatically.

## Compatible Agents

Works with any MCP-compatible agent:

- **Hermes Agent** — `mcp_servers` in `config.yaml`
- **Claude Code / Claude Desktop** — `mcpServers` in `claude_desktop_config.json` or `.mcp.json`
- **ChatGPT / Codex** — MCP connector settings
- **Cursor, Windsurf, Cline, Continue, Aider, etc.** — any MCP-compatible client
- **Custom agents** — any tool that speaks MCP over stdio

## Requirements

- **Python 3.11+** (tested on 3.11.15)
- **Pixelorama** (Windows/Linux/macOS) — [download](https://orama-interactive.itch.io/pixelorama)
- **Any MCP-compatible AI agent** (Hermes, Claude, GPT, Cursor, etc.)

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/ramonsamagaio/Hermes-Pixelorama-MCP.git
cd Hermes-Pixelorama-MCP
```

### 2. Install dependencies

```bash
pip install mcp>=1.12,<2 pillow>=11,<13
# or via uv:
uv pip install -e .
```

### 3. Install the extension into Pixelorama

```bash
python -m pixelorama_bridge.installer \
  --project-root . \
  --pixelorama-user-dir "$APPDATA/pixelorama"
```

This will:
- Copy `extension/src/Extensions/HermesBridge.zip` to Pixelorama's extensions folder
- Generate an auth token at `pixelorama_user_dir/hermes_bridge/token`
- Enable the extension in Pixelorama's `config.ini`

### 4. Configure your agent

#### Hermes Agent

Add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  pixelorama:
    command: python
    args:
      - -m
      - pixelorama_bridge.mcp_server
    env:
      PIXELORAMA_BRIDGE_ROOT: /c/Users/ramon/AppData/Roaming/pixelorama/hermes_bridge
      PIXELORAMA_EXE: /c/Users/ramon/Downloads/pixelorama.exe
```

#### Claude Code / Claude Desktop

Add to `~/.claude.json` (global) or `.mcp.json` (project-level):

```json
{
  "mcpServers": {
    "pixelorama": {
      "command": "python",
      "args": ["-m", "pixelorama_bridge.mcp_server"],
      "env": {
        "PIXELORAMA_BRIDGE_ROOT": "/home/user/.local/share/pixelorama/hermes_bridge",
        "PIXELORAMA_EXE": "/home/user/Downloads/pixelorama.AppImage"
      }
    }
  }
}
```

Then restart Claude:

```bash
claude mcp list          # verify it appears
claude                   # tools are now available
```

#### ChatGPT / Codex (OpenAI)

Use an MCP connector or configure via your agent's settings. Example for a custom script:

```bash
python -m pixelorama_bridge.mcp_server
```

#### Cursor / Windsurf / Cline / Continue

Add to your MCP settings (usually in `.cursorrules`, `.windsurf/mcp.json`, `.cline/mcp.json`, or `.continue/config.json`):

```json
{
  "mcpServers": {
    "pixelorama": {
      "command": "python",
      "args": ["-m", "pixelorama_bridge.mcp_server"],
      "env": {
        "PIXELORAMA_BRIDGE_ROOT": "/home/user/.local/share/pixelorama/hermes_bridge",
        "PIXELORAMA_EXE": "/path/to/pixelorama"
      }
    }
  }
}
```

#### Aider

```bash
aider --mcp-server "python:-m:pixelorama_bridge.mcp_server"
```

Adjust paths according to your system.

### 5. Restart your agent

After configuring, restart your agent. The tools will be available once Pixelorama is running with the HermesBridge extension loaded.

## Available Tools

Once connected, the agent has access to:

| Tool | Description |
|------|-------------|
| `pixelorama_status` | Check if Pixelorama and HermesBridge extension are active |
| `pixelorama_launch` | Launch Pixelorama (optionally with project) |
| `pixelorama_create_project` | Create transparent RGBA project with dimensions and frames |
| `pixelorama_open_project` | Open existing `.pxo` project |
| `pixelorama_project_info` | Return dimensions, frame/layer counts |
| `pixelorama_set_frame_png` | Replace cel with PNG (same size) |
| `pixelorama_get_frame_png` | Export cel to PNG |
| `pixelorama_set_pixels` | Apply exact `[x,y,r,g,b,a]` edits |
| `pixelorama_set_frame_duration` | Set frame duration multiplier |
| `pixelorama_save_project` | Save as `.pxo` |
| `pixelorama_export_spritesheet` | Export frames to transparent PNG spritesheet |
| `pixelorama_import_spritesheet` | Split spritesheet and import as real animation frames |

## Example Usage

```
Create a 32x32 project with 6 frames, import the spritesheet:
path=spritesheet.png, frame_width=32, frame_height=32, frame_count=6, columns=6

Now edit frame 2:
set frame=2, path=edited_frame.png

Save the project:
save_project path=animation.pxo

Export the final spritesheet:
export_spritesheet path=output.png, frame_count=6, columns=6
```

## Architecture

```
Hermes-Pixelorama-MCP/
├── pyproject.toml                    # Dependencies (mcp, pillow)
├── extension/
│   └── src/Extensions/HermesBridge/
│       ├── Main.gd                   # Godot extension (file-queue listener)
│       ├── Main.tscn                 # Godot scene
│       └── extension.json            # Metadata
├── src/pixelorama_bridge/
│   ├── __init__.py
│   ├── mcp_server.py                 # FastMCP server (tools)
│   ├── transport.py                  # FileQueueTransport (request/response)
│   ├── image_ops.py                  # split/build spritesheet, apply pixels
│   ├── installer.py                  # Install extension + generate token
│   └── packaging.py                  # Build .zip of extension
└── tests/                            # pytest suite
```

## License

MIT