内容
# tronbyt-mcp
让您的 AI 助手在 LED 显示屏上显示信息。
如果您拥有由自行托管的 [tronbyt/server](https://github.com/tronbyt/server) 管理的 [Tidbyt](https://tidbyt.com) 或类似 Tidbyt 风格的 LED 矩阵显示屏，那么它就可以与 Claude（或其他支持 [MCP](https://modelcontextprotocol.io) 的 AI 工具，即开放标准协议，用于让助手访问工具）连接。一旦安装完成，您的显示屏就变成了您可以与助手对话的对象：
> "在琥珀色中，在标志上显示 **BREAD'S DONE**。"
> "将显示屏调暗至 20%，并在晚上 10 点至早上 7 点开启夜间模式。"
> "当前标志上有哪些应用程序？禁用股票行情显示。"
> "显示时钟应用程序一会儿。"
助手处理其余部分 - 将文本渲染成显示屏的像素格式，与您的服务器通信，管理应用程序轮换。所有操作都在您自己的机器上运行，针对您自己的服务器；没有任何内容通过云服务。
## 工作原理
`tronbyt-mcp` 是一个小型 MCP 服务器，它封装了 tronbyt/server 记录的 [REST API](https://github.com/tronbyt/server/blob/main/API.md)。您的 MCP 客户端（Claude Code、Claude Desktop 等）本地启动它，并通过 stdio 与其通信；它通过 HTTP 与您的 Tronbyt 服务器通信，并使用设备 API 密钥。
## 要求
- 由自行托管的 **tronbyt/server** （v2.x）管理的显示屏。服务器管理的任何设备都可以使用 - 它不必是 Tidbyt：Tidbyt Gen1/Gen2、Tronbyt S3 和 S3 Wide 套件、MatrixPortal S3（包括 Waveshare 变体）、Waveshare S3、Pixoticker、树莓派显示屏和“其他”类型的自制面板。支持标准 64×32 和宽 128×64（2x）面板。
- **Node.js ≥ 20.9**
- **MCP 客户端**：Claude Code、Claude Desktop 或其他支持 MCP stdio 服务器的客户端。
## 安装
### 1. 获取设备 API 密钥
在 Tronbyt 网页界面中，打开设备的设置并复制（或生成）其 **API 密钥**。密钥范围限定为单个设备 - 一个密钥，一个显示屏。
### 2. 将服务器添加到您的 MCP 客户端
**Claude Code** （一条命令）：
```sh
claude mcp add tronbyt \
-e TRONBYT_BASE_URL=http://tronbyt.local:8000 \
-e TRONBYT_API_KEY=<您的设备密钥> \
-- npx -y tronbyt-mcp
```
**Claude Desktop**：编辑配置文件 —
macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`，
Windows：`%APPDATA%\Claude\claude_desktop_config.json` — 并添加：
```json
{
"mcpServers": {
"tronbyt": {
"command": "npx",
"args": ["-y", "tronbyt-mcp"],
"env": {
"TRONBYT_BASE_URL": "http://tronbyt.local:8000",
"TRONBYT_API_KEY": "<您的设备密钥>"
}
}
}
}
```
然后重启 Claude Desktop。
**其他 MCP 客户端**：使用命令 `npx` 配置 stdio 服务器，参数为 `["-y", "tronbyt-mcp"]`，以及上述两个环境变量。
**从源代码**（而不是 npx）：
```sh
git clone https://github.com/jonfishr/tronbyt-mcp.git
cd tronbyt-mcp
npm install && npm run build
```
然后在您的 MCP 客户端配置中使用 `node /path/to/tronbyt-mcp/dist/index.js` 作为服务器命令（相同的环境变量）。
**多个显示屏？** API 密钥是每个设备的，因此为每个显示屏添加一个条目（`tronbyt-kitchen`、`tronbyt-office` 等），每个密钥都有自己的密钥。
### 3. 检查是否有效
询问您的助手类似 *"列出我的 Tronbyt 设备。"* 的问题。您应该会收到包含亮度、夜间模式和应用程序列表的显示屏信息。（在 Claude Code 中，`/mcp` 还会显示服务器及其工具。）
## 配置
| 环境变量 | 必需 | 默认值 | 备注 |
|---------|----------|---------|-------|
| `TRONBYT_BASE_URL` | 是 | — | 您的 tronbyt/server，例如 `http://tronbyt.local:8000` |
| `TRONBYT_API_KEY` | 是 | — | 来自 Tronbyt 网页界面的每个设备的 API 密钥 |
| `TRONBYT_TIMEOUT_MS` | 否 | `10000` | 每个请求的超时时间 |
## 用法
您不需要直接调用这些 - 您的助手会根据您的请求选择合适的工具 - 但这是它可以使用的工具：
| 工具 | 功能 |
|------|--------------|
| `list_devices` | 可见的设备：亮度、夜间模式、固定应用、最后一次查看 |
| `update_device` | 设置亮度、旋转间隔、夜间/调暗模式、固定应用 |
| `reboot_device` | 重启显示屏 |
| `list_installations` | 设备上安装的应用，包含状态和配置 |
| `update_installation` | 启用/禁用、固定/取消固定或重新安排安装 |
| `delete_installation` | 删除安装及其渲染的图像 |
| `push_app` | 渲染服务器端应用（带有可选配置）并显示 |
| `push_image` | 将 base64 WebP（64×32 或 128×64 适用于宽屏显示）直接推送到显示屏 |
| `push_text` | 在本地将文本渲染为显示大小的 WebP 并推送 |
推送工具采用 `background`: `false`（默认）会中断显示屏并立即显示推送；`true` 会将其保存到轮换中而不会中断。当密钥恰好看到一个设备（正常情况）时，`device_id` 永远不需要指定。
### `push_text`
文本使用 [Tom Thumb](https://robey.lag.net/2010/01/23/tiny-monospace-font.html) 3×5 像素字体渲染，自动换行并居中。仅限可打印的 ASCII；`\n` 强制换行。颜色为十六进制（`#ffcc00`），默认为黑色背景下的白色。
画布大小根据设备类型检测（`size: "auto"`）：标准显示屏为 64×32，宽屏/2x 显示屏（`tronbyt_s3_wide`、`raspberrypi_wide`）为 128×64。在宽屏显示屏上，字体默认放大 - 相同 16 个字符 × 5 行，两倍像素。传递 `text_size: "small"` 以获取原生大小的字符（32 个字符 × 10 行），或完全重写检测结果为 `size: "64x32"` / `"128x64"`。
## 删除
- **Claude Code:** `claude mcp remove tronbyt`
- **Claude Desktop / 其他客户端：** 从配置文件中删除 `"tronbyt"` 条目并重启客户端。
- **如果您从源代码安装：** 删除克隆的目录。如果您使用了 `npx`，则缓存的副本可能会在 `~/.npm/_npx` 下保留；它很小且无害，或者使用 `npm cache clean --force` 清除。
- **在服务器上：** 您推送的任何内容都会在设备上显示为安装 - 要求您的助手删除它，或在 Tronbyt 网页界面中删除。如果您完成了操作，请在网页界面中撤销 API 密钥。没有任何其他内容存储在任何地方。
## 开发
```sh
npm install
npm test # vitest: 单元测试 + 进程内 MCP + stdio 端到端测试（先构建）
npm run build # tsc -> dist/
npm run gen:font # 从 scripts/tom-thumb.bdf 重新生成 src/font.ts
```
在真实服务器上进行烟雾测试（非破坏性 - 以后台模式推送到轮换，然后删除安装）。在构建后，从存储库根目录运行：
```sh
TRONBYT_BASE_URL=http://tronbyt.local:8000 TRONBYT_API_KEY=<密钥> scripts/smoke.sh
```
## 超出范围（v1）
- `update_firmware_settings` - 故意排除；错误的值可能会导致显示屏无法访问
- 动画（多帧 WebP）、按 URL 加载图像
- HTTP 传输（仅 stdio）
## 许可证
MIT。捆绑的像素字体是 Tom Thumb / "Fixed4x6"，由 Brian J. Swetland 和 Robey Pointer (MIT) 创建，作为 `scripts/tom-thumb.bdf` 销售。本项目与 Tidbyt（公司）或 Tronbyt 项目无关。
