内容
# idotmatrix-mcp
一款让AI助手在[iDotMatrix](https://www.idotmatrix.com/) LED显示屏上通过蓝牙绘制像素艺术的MCP（模型上下文协议）服务器。
将您的iDotMatrix显示屏连接到Claude、ChatGPT或任何兼容MCP的客户端，并要求它绘制图片、图标、动画、仪表盘——任何适合16x16、32x32或64x64像素网格的内容。
## 工作原理
服务器维护一个与显示屏分辨率匹配的内存像素画布。AI助手通过MCP工具与画布交互——绘制形状、填充颜色、渲染文本——然后将完成的帧通过BLE推送到物理显示屏。
```
AI助手 ──MCP工具──> idotmatrix-mcp ──BLE──> iDotMatrix显示屏
(画布缓冲区)
```
**工作流程：**
1. 助手调用`discover_devices`查找附近的iDotMatrix显示屏
2. 它通过`connect_device`连接，指定屏幕尺寸
3. 它使用绘图工具（或`draw_batch`进行多次操作）绘制画布
4. 它调用`get_preview`在聊天中查看ANSI块艺术预览
5. 它调用`send_to_display`将帧推送到物理设备
## 前置条件
- **Node.js** 18+
- **macOS** （通过`idotmatrix` npm包支持BLE——在底层使用Noble）
- 一个**iDotMatrix LED显示屏**，已通电并在蓝牙范围内
## 安装
```bash
git clone https://github.com/nailan/idotmatrix-mcp.git
cd idotmatrix-mcp
npm install
npm run build
```
## 配置
### Claude Desktop
添加到您的Claude Desktop配置（`~/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
添加到您的Claude Code设置（`.claude/settings.json`或全局）：
```json
{
"mcpServers": {
"idotmatrix": {
"command": "node",
"args": ["/absolute/path/to/idotmatrix-mcp/dist/index.js", "--stdio"]
}
}
}
```
### HTTP模式（其他客户端）
服务器还支持Streamable HTTP传输，用于不支持stdio的客户端：
```bash
node dist/index.js # 默认http://127.0.0.1:8321/mcp
node dist/index.js --port=9000 # 自定义端口
```
## 工具
### 画布管理
| 工具 | 描述 |
|------|-------------|
| `clear_canvas(颜色)` | 用一种颜色填充整个画布并重置 |
| `get_preview()` | 返回画布的ANSI块艺术预览 |
| `list_colors()` | 列出所有48种命名颜色及其十六进制值 |
### 绘图基元
| 工具 | 描述 |
|------|-------------|
| `draw_rect(x, y, width, height, color, fill?)` | 矩形（默认为填充） |
| `draw_circle(cx, cy, radius, color, fill?)` | 圆形（默认为填充） |
| `draw_ellipse(cx, cy, rx, ry, color, fill?)` | 具有独立半径的椭圆 |
| `draw_line(x1, y1, x2, y2, color)` | 两点之间的线 |
| `draw_triangle(x1, y1, x2, y2, x3, y3, color, fill?)` | 三角形（默认为填充） |
| `draw_rounded_rect(x, y, width, height, radius, color, fill?)` | 具有圆角的矩形 |
| `draw_polygon(cx, cy, radius, sides, color, fill?, rotation?)` | 正多边形（3-12边） |
| `draw_gradient(x, y, width, height, color_from, color_to, direction?)` | 线性渐变填充（垂直、水平或对角） |
| `set_pixel(x, y, color)` | 设置单个像素 |
| `flood_fill(x, y, color)` | 从一个点开始的油漆桶填充 |
| `draw_text(text, x, y, color, font_size?)` | 位图文本（3x5“小”或5x7“中”） |
### 批量绘图
| 工具 | 描述 |
|------|-------------|
| `draw_batch(commands)` | 在一次调用中执行多个绘图命令 |
`draw_batch`接受一个命令对象数组。每个对象都有一个`command`字段和与相应单个工具相同的参数。这是组成场景最有效的方法——一次工具调用而不是多次往返。
```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" }
]
```
支持的命令：`clear`, `rect`, `circle`, `ellipse`, `line`, `triangle`, `rounded_rect`, `polygon`, `gradient`, `pixel`, `fill`, `text`.
执行在第一个错误时停止，并报告哪个命令失败。
### 设备管理
| 工具 | 描述 |
|------|-------------|
| `discover_devices(timeout_seconds?)` | 扫描附近的iDotMatrix BLE设备 |
| `connect_device(device_id, screen_size)` | 连接到设备（屏幕尺寸：16、32或64） |
| `disconnect_device()` | 与当前设备断开连接 |
| `send_to_display()` | 将画布缓冲区推送到连接的显示屏 |
## 颜色调色板
服务器包含一个为LED显示屏优化的48色调色板。使用`list_colors`查看所有选项。一些亮点：
- **中性色：** `black`, `white`, `gray`, `dark_gray`, `light_gray`
- **暖色：** `red`, `orange`, `yellow`, `coral`, `salmon`, `pink`, `hot_pink`
- **冷色：** `blue`, `cyan`, `green`, `teal`, `sky_blue`, `purple`, `violet`
- **土色：** `brown`, `tan`, `sand`, `skin`, `peach`, `dark_brown`
- **自然色：** `forest`, `dark_green`, `lime`, `spring`, `mint`, `olive`
渐变色在任何两种调色板颜色之间插值，产生平滑的中间色调，不局限于48色调色板。
## 提示
服务器提供了一个`drawing-guide`提示，为AI助手提供了关于坐标系、可用工具、颜色调色板和像素艺术技巧的上下文。支持提示的MCP客户端将自动提供此功能。
## 坐标系
- 原点`(0, 0)`在**左上角**
- X向右增加，Y向下增加
- 在边界外绘制会被静默裁剪
## 开发
```bash
npm run dev # 使用tsx运行（无构建步骤）
npm run build # 将TypeScript编译到dist/
npm run clean # 删除dist/
```
## 许可证
MIT
