# text2d — 2D Retro Pixel Art Texture MCP Server

A high-performance Model Context Protocol (MCP) server that empowers AI assistants to procedurally generate, manipulate, and export 2D retro pixel art textures and tilesets for game development.

---

## Features

- **Image to Retro Pixel Art Conversion:** Ingest external PNG files and automatically downscale, quantize to retro palettes, and apply Bayer dithering via `pixelize_image`.
- **Procedural Texture Synthesis:** Deterministic generation of `wood`, `stone` (cobblestone/rock), `brick`, `grass`, `metal` (brushed plates with rivets), and `water` caustics.
- **Pixel-Level Primitives:** Full control via `set_pixel`, `set_pixel_batch`, `draw_shape` (lines, rects, circles), and `flood_fill`.
- **Retro Palettes & Quantization:** Built-in authentic color palettes including `PICO-8`, `DawnBringer 32 (DB32)`, `Endesga 32`, `GameBoy`, `NES Classic`, and `Cyberpunk Neon`.
- **Pixel-Art Post-Processing:** Bayer ordered dithering (2x2, 4x4, 8x8) and 1px inner/outer pixel-perfect outlines.
- **Export Options:** PNG files with nearest-neighbor integer scaling, Base64 Data URIs, ASCII Unicode block previews, and 2D JSON color grids.

## Visual Examples & Gallery

### 1. Image Pixelization (`pixelize_image`)
Convert high-resolution realistic photos or assets into authentic retro pixel art with automatic palette quantization and Bayer dithering.

| Original Input | Endesga 32 (32x32) | PICO-8 (32x32) | GameBoy (32x32) |
|:---:|:---:|:---:|:---:|
| <img src="examples/input/realistic_car.jpg" width="160" alt="Original Photo" /> | <img src="examples/output/car_pixel_32_endesga.png" width="160" alt="Endesga 32" /> | <img src="examples/output/car_pixel_32_pico8.png" width="160" alt="PICO-8" /> | <img src="examples/output/car_pixel_32_gameboy.png" width="160" alt="GameBoy" /> |

| DawnBringer 32 (48x48) | Cyberpunk Neon (64x64) |
|:---:|:---:|
| <img src="examples/output/car_pixel_48_db32.png" width="200" alt="DB32 48x48" /> | <img src="examples/output/car_pixel_64_cyberpunk.png" width="200" alt="Cyberpunk 64x64" /> |

### 2. Procedural Texture Synthesis (`generate_texture`)
Generate seamless, deterministic retro textures in seconds without external assets.

| Wood (`wood`) | Stone (`stone`) | Brick (`brick`) |
|:---:|:---:|:---:|
| <img src="examples/output/wood.png" width="150" alt="Wood Texture" /> | <img src="examples/output/stone.png" width="150" alt="Stone Texture" /> | <img src="examples/output/brick.png" width="150" alt="Brick Texture" /> |

| Grass (`grass`) | Metal (`metal`) | Water (`water`) |
|:---:|:---:|:---:|
| <img src="examples/output/grass.png" width="150" alt="Grass Texture" /> | <img src="examples/output/metal.png" width="150" alt="Metal Texture" /> | <img src="examples/output/water.png" width="150" alt="Water Texture" /> |

---

## MCP Tools Matrix

| Tool Name | Description | Key Parameters |
|---|---|---|
| `pixelize_image` | Ingests external PNG and converts to 2D retro pixel art | `file_path`, `target_width`, `target_height`, `palette`, `sampling`, `dither`, `export_output_path` |
| `create_canvas` | Initializes a new in-memory pixel canvas | `width`, `height`, `palette`, `mode`, `backgroundColor` |
| `generate_texture` | Synthesizes a procedural retro texture | `canvas_id`, `texture_type`, `seed`, `palette`, `options` |
| `set_pixel` | Sets a single pixel at (x, y) | `canvas_id`, `x`, `y`, `color` |
| `set_pixel_batch` | Batch updates multiple coordinates | `canvas_id`, `pixels: [{x, y, color}]` |
| `draw_shape` | Draws rasterized line, rect, or circle | `canvas_id`, `shape`, `x1`, `y1`, `x2`, `y2`, `color`, `filled` |
| `flood_fill` | Contiguous area flood fill | `canvas_id`, `x`, `y`, `color` |
| `apply_dither` | Applies Bayer ordered dithering | `canvas_id`, `matrix_size`, `spread` |
| `apply_outline` | Draws 1px pixel-perfect outline | `canvas_id`, `color`, `mode` |
| `export_texture` | Exports canvas to PNG, Data URI, ASCII or JSON | `canvas_id`, `format`, `file_path`, `scale` |
| `list_palettes` | Lists all built-in retro palettes | *None* |
| `list_canvases` | Lists active canvases in memory | *None* |
| `get_canvas_info` | Inspects canvas metadata and dimensions | `canvas_id` |
| `delete_canvas` | Frees canvas from memory | `canvas_id` |

---

## Installation & Usage

You can install and run `text2d` directly from GitHub without publishing to npm:

### 1. Global Installation (Recommended)

Install globally directly from the GitHub repository:

```bash
npm install -g github:al3duc/text2d-mcp
```

Once installed, the `text2d` command is available system-wide.

---

## MCP Client Configuration

Add `text2d` to your MCP client configuration (e.g. `claude_desktop_config.json`, `mcp_config.json`, or Cursor):

### Option A: Using Global Installation (Simplest)

```json
{
  "mcpServers": {
    "text2d": {
      "command": "text2d"
    }
  }
}
```

### Option B: Direct Execution via `npx` (No permanent install)

```json
{
  "mcpServers": {
    "text2d": {
      "command": "npx",
      "args": [
        "-y",
        "github:al3duc/text2d-mcp"
      ]
    }
  }
}
```

### Option C: Claude Code CLI Command

If using Claude Code, register it with a single terminal command:

```bash
claude mcp add text2d -- npx -y github:al3duc/text2d-mcp
```

### Option D: Local Clone (Development)

```bash
git clone https://github.com/al3duc/text2d-mcp.git
cd text2d-mcp
npm install
npm run build
```

```json
{
  "mcpServers": {
    "text2d": {
      "command": "node",
      "args": [
        "<PATH_TO_TEXT2D_REPOSITORY>/dist/index.js"
      ]
    }
  }
}
```
*Note: Replace `<PATH_TO_TEXT2D_REPOSITORY>` with the absolute path to your cloned repository.*

---

## Build & Test

```bash
# Install dependencies
npm install

# Run unit & integration tests
npm test

# Build TypeScript to dist/
npm run build

# Generate procedural texture samples (wood, stone, brick, grass, metal, water)
npx tsx examples/generate_samples.ts

# Test converting realistic images from examples/input/ to pixel art
npx tsx examples/test_car_pixelize.ts
```

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.