# idotmatrix-mcp

An MCP (Model Context Protocol) server that lets AI assistants draw pixel art on [iDotMatrix](https://www.idotmatrix.com/) LED displays over Bluetooth.

Connect your iDotMatrix display to Claude, ChatGPT, or any MCP-compatible client and ask it to draw pictures, icons, animations, dashboards — anything that fits on a 16x16, 32x32, or 64x64 pixel grid.

## How It Works

The server maintains an in-memory pixel canvas that matches your display's resolution. AI assistants interact with the canvas through MCP tools — drawing shapes, filling colors, rendering text — then push the finished frame to the physical display over BLE.

```
AI Assistant  ──MCP tools──>  idotmatrix-mcp  ──BLE──>  iDotMatrix Display
                              (canvas buffer)
```

**Workflow:**

1. The assistant calls `discover_devices` to find nearby iDotMatrix displays
2. It connects with `connect_device`, specifying the screen size
3. It draws on the canvas using drawing tools (or `draw_batch` for multiple operations at once)
4. It calls `get_preview` to see an ANSI block-art preview in the chat
5. It calls `send_to_display` to push the frame to the physical device

## Prerequisites

- **Node.js** 18+
- **macOS** (BLE support via the `idotmatrix` npm package — uses Noble under the hood)
- An **iDotMatrix LED display** powered on and within Bluetooth range

## Installation

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

## Configuration

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "idotmatrix": {
      "command": "node",
      "args": ["/absolute/path/to/idotmatrix-mcp/dist/index.js", "--stdio"]
    }
  }
}
```

### Claude Code

Add to your Claude Code settings (`.claude/settings.json` or global):

```json
{
  "mcpServers": {
    "idotmatrix": {
      "command": "node",
      "args": ["/absolute/path/to/idotmatrix-mcp/dist/index.js", "--stdio"]
    }
  }
}
```

### HTTP mode (other clients)

The server also supports Streamable HTTP transport for clients that don't use stdio:

```bash
node dist/index.js                  # defaults to http://127.0.0.1:8321/mcp
node dist/index.js --port=9000      # custom port
```

## Tools

### Canvas Management

| Tool | Description |
|------|-------------|
| `clear_canvas(color)` | Fill entire canvas with one color and reset |
| `get_preview()` | Return an ANSI block-art preview of the canvas |
| `list_colors()` | List all 48 named colors with hex values |

### Drawing Primitives

| Tool | Description |
|------|-------------|
| `draw_rect(x, y, width, height, color, fill?)` | Rectangle (filled by default) |
| `draw_circle(cx, cy, radius, color, fill?)` | Circle (filled by default) |
| `draw_ellipse(cx, cy, rx, ry, color, fill?)` | Ellipse with independent radii |
| `draw_line(x1, y1, x2, y2, color)` | Line between two points |
| `draw_triangle(x1, y1, x2, y2, x3, y3, color, fill?)` | Triangle (filled by default) |
| `draw_rounded_rect(x, y, width, height, radius, color, fill?)` | Rectangle with rounded corners |
| `draw_polygon(cx, cy, radius, sides, color, fill?, rotation?)` | Regular polygon (3-12 sides) |
| `draw_gradient(x, y, width, height, color_from, color_to, direction?)` | Linear gradient fill (vertical, horizontal, or diagonal) |
| `set_pixel(x, y, color)` | Set a single pixel |
| `flood_fill(x, y, color)` | Paint-bucket fill from a point |
| `draw_text(text, x, y, color, font_size?)` | Bitmap text (3x5 "small" or 5x7 "medium") |

### Batch Drawing

| Tool | Description |
|------|-------------|
| `draw_batch(commands)` | Execute multiple draw commands in one call |

`draw_batch` accepts an array of command objects. Each object has a `command` field plus the same parameters as the corresponding individual tool. This is the most efficient way to compose scenes — one tool call instead of many round-trips.

```json
[
  { "command": "clear", "color": "dark_blue" },
  { "command": "gradient", "x": 0, "y": 0, "width": 64, "height": 32, "color_from": "navy", "color_to": "sky_blue" },
  { "command": "circle", "cx": 48, "cy": 8, "radius": 5, "color": "yellow" },
  { "command": "ellipse", "cx": 20, "cy": 16, "rx": 10, "ry": 5, "color": "white" },
  { "command": "rounded_rect", "x": 10, "y": 40, "width": 44, "height": 16, "radius": 4, "color": "green" },
  { "command": "polygon", "cx": 50, "cy": 10, "radius": 6, "sides": 5, "color": "gold" },
  { "command": "text", "text": "HI", "x": 28, "y": 44, "color": "white" }
]
```

Supported commands: `clear`, `rect`, `circle`, `ellipse`, `line`, `triangle`, `rounded_rect`, `polygon`, `gradient`, `pixel`, `fill`, `text`.

Execution stops on the first error and reports which command failed.

### Device Management

| Tool | Description |
|------|-------------|
| `discover_devices(timeout_seconds?)` | Scan for nearby iDotMatrix BLE devices |
| `connect_device(device_id, screen_size)` | Connect to a device (screen size: 16, 32, or 64) |
| `disconnect_device()` | Disconnect from the current device |
| `send_to_display()` | Push the canvas buffer to the connected display |

## Color Palette

The server includes a curated 48-color palette optimized for LED displays. Use `list_colors` to see all options. Some highlights:

- **Neutrals:** `black`, `white`, `gray`, `dark_gray`, `light_gray`
- **Warm:** `red`, `orange`, `yellow`, `coral`, `salmon`, `pink`, `hot_pink`
- **Cool:** `blue`, `cyan`, `green`, `teal`, `sky_blue`, `purple`, `violet`
- **Earth:** `brown`, `tan`, `sand`, `skin`, `peach`, `dark_brown`
- **Nature:** `forest`, `dark_green`, `lime`, `spring`, `mint`, `olive`

Gradients interpolate between any two palette colors, producing smooth intermediate shades not limited to the 48-color palette.

## Prompts

The server ships a `drawing-guide` prompt that gives the AI assistant context about the coordinate system, available tools, color palette, and pixel art tips. MCP clients that support prompts will make this available automatically.

## Coordinate System

- Origin `(0, 0)` is the **top-left** corner
- X increases rightward, Y increases downward
- Drawing outside bounds is silently clipped

## Development

```bash
npm run dev          # run with tsx (no build step)
npm run build        # compile TypeScript to dist/
npm run clean        # remove dist/
```

## License

MIT