内容
# Skydimo LED MCP 服务器
将物理 RGB LED 灯带转变为 AI 编程助手实时状态指示器。
当您的 AI 在思考时，灯光会流动彩虹色。当它在编写代码时，绿色光束会横跨灯带移动。当测试失败时，红色脉冲会闪烁。您只需 glance 一眼桌面 — 无需查看屏幕，即可了解正在发生的事情。
## 工作原理
```
AI 工具（WorkBuddy、Claude Code、opencode 等）
│ MCP 协议（stdio）
▼
server.py ──→ skydimo_bridge.py ──→ daemon/skydimo.py
│ │
│ 写入 .ai_state 文件
│ │
▼ ▼
MCP 工具/资源 daemon/skydimo_daemon.py
│ 读取 .ai_state（约 100ms 轮询）
│ 渲染动画（约 40fps）
▼
COM4（Adalight 协议）
│
▼
Skydimo SK0124 LED 灯带 ✨
```
MCP 服务器暴露了 AI 助手可以调用的工具。每次工具调用都会将状态名称写入文件。后台守护进程会轮询该文件并立即切换 LED 动画（总延迟约 162ms）。
## 17 种 LED 模式
| 模式 | 效果 | 使用场景 |
|------|--------|-------------|
| `reasoning` | 彩虹流动 | AI 正在思考/处理 |
| `output` | 绿色追逐光束 | 流式输出/写入文件 |
| `decision` | 红色快速呼吸 | 需要用户决策/代码审查 |
| `idle` | 青绿色呼吸（慢） | 空闲/等待/完成 |
| `waiting_user` | 青绿色 + 白色闪光 | 等待用户回复 |
| `testing` | 蓝白色扫描器 | 运行测试/验证 |
| `success` | 绿色波浪 + 闪光 | 测试通过/任务完成 |
| `error` | 红色双脉冲 | 错误/命令失败 |
| `planning` | 紫色慢呼吸 | 架构规划/设计 |
| `git_push` | 黄色闪烁 | 推送代码到远程 |
| `git_merge` | 橙色脉冲 | 合并分支/解决冲突 |
| `wows_battle` | 深蓝色慢追逐 + 黄色火焰闪烁 | World of Warships：战斗中 |
| `wows_firing` | 橙黄色闪烁，2 秒后消退 | World of Warships：主炮开火 |
| `wows_hit` | 红橙色 - 红色 3 次闪烁，缓慢 | World of Warships：舰船被击中 |
| `wows_victory` | 金色波浪从中心扩散 + 白色闪光 | World of Warships：胜利 |
| `wows_sailing` | 深蓝色非常缓慢流动 | World of Warships：航行/等待 |
| `off` | 全关 | 关闭灯光 |
## 硬件要求
- **LED 灯带：** Skydimo SK0124（54 个 RGB LEDs）
- **连接：** CH340 USB-串口适配器
- **协议：** Adalight（`Ada` 头 + LED 数量 + RGB 数据）
- **默认端口：** COM4，115200 波特率
> 所有硬件参数都可以通过环境变量配置（参见下文）。
## 鸣谢与前沿技术
该项目建立在开源 RGB 照明社区的工作基础上：
- **[OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB)** — 大型开源 RGB 照明控制项目。我们的 Adalight 协议实现遵循 OpenRGB 用于可寻址 LED 灯带的相同标准。
- **[Skydimo OpenRGB](https://gitlab.com/skydimo-team/skydimo-open-rgb)** — Skydimo（SK0124 LED 灯带制造商）维护的 OpenRGB 分支，具有设备特定的优化。他们的作品为本项目的串口参数和帧格式提供了参考。
- **[Skydimo](https://skydimo.com)** — 本项目使用的 SK0124 RGB LED 灯带硬件制造商。
本项目**不**依赖或嵌入 OpenRGB 或 Skydimo 的软件。守护进程（`daemon/skydimo_daemon.py`）是一个独立的 Python 实现，它使用 Adalight 协议直接与串口通信。但是，协议知识和硬件参数源自上述项目。
## 快速入门
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
> **注意：** `mcp` 和 `pyserial` 可以在同一个 Python 环境中。如果它们必须分开（例如，MCP 服务器在托管的虚拟环境中运行，但 pyserial 仅在系统 Python 中），请设置 `SKYDIMO_DAEMON_PY` 环境变量，以指向具有 pyserial 的解释器。
### 2. 启动守护进程
```bash
python daemon/skydimo.py start idle
```
LED 灯带应会亮起，呈现青绿色呼吸灯效。
### 3. 配置您的 MCP 客户端
在您的 MCP 客户端配置文件中添加以下内容（例如，WorkBuddy 的 `~/.workbuddy/mcp.json`）：
```json
{
"mcpServers": {
"skydimo-led": {
"type": "stdio",
"command": "python",
"args": ["/path/to/skydimo-led-mcp/server.py"],
"description": "AI 活动物理 LED 灯带状态指示器"
}
}
}
```
对于 Claude Code，请添加到 `~/.claude.json`。对于 opencode，请添加到 `opencode.jsonc`。
### 4. 测试
告诉您的 AI 助手：*"将 LED 设置为 reasoning 模式。"*
灯带应切换到彩虹流动模式。
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SKYDIMO_PORT` | `COM4` | 串口（例如，`COM4`，`/dev/ttyUSB0`） |
| `SKYDIMO_BAUDRATE` | `115200` | 串口波特率 |
| `SKYDIMO_NUM_LEDS` | `54` | 灯带上的 LED 数量 |
| `SKYDIMO_DIR` | `./daemon` | 守护进程目录路径 |
| `SKYDIMO_DAEMON_PY` | `sys.executable` | 守护进程的 Python 解释器（必须具有 pyserial） |
## 项目结构
```
skydimo-led-mcp/
├── server.py # MCP 服务器（stdio 传输）— 4 个工具 + 3 个资源
├── skydimo_bridge.py # 桥接：MCP 服务器 → 守护进程 CLI（具有自动恢复功能）
├── index.html # 双语文档页面（= skydimo://help 资源）
├── requirements.txt # Python 依赖项（mcp + pyserial）
├── daemon/
│ ├── skydimo_daemon.py # 后台守护进程：COM4 + LED 动画渲染
│ ├── skydimo.py # CLI 入口点（启动/停止/状态/设置状态）
│ └── skydimo_config.py # 共享配置（路径、端口、模式 — 环境变量可配置）
├── scripts/
│ └── start_daemon.bat # Windows 自动启动脚本（用于启动文件夹）
├── LICENSE # MIT
└── .gitignore
```
## MCP 工具
| 工具 | 描述 | 参数 |
|------|-------------|------------|
| `set_led_state` | 切换 LED 至视觉模式 | `mode`（必填）：17 种模式之一 |
| `start_daemon` | 启动后台守护进程 | `mode`（可选，默认为 `idle`） |
| `stop_daemon` | 优雅地停止守护进程（发送关闭帧） | 无 |
| `get_status` | 查询守护进程状态和当前 LED 状态 | 无 |
## MCP 资源
| URI | 内容 |
|-----|---------|
| `skydimo://status` | 纯文本状态（守护进程是否运行？当前状态） |
| `skydimo://modes` | 有效模式名称的 JSON 列表 |
| `skydimo://help` | HTML 文档页面 |
## 守护进程自动启动（Windows）
将 `scripts/start_daemon.bat` 复制到 Windows 启动文件夹（`Win+R` → `shell:startup`），以便在登录时启动守护进程。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
## 鸣谢
- [OpenRGB](https://gitlab.com/CalcProgrammer1/OpenRGB) — 开源 RGB 照明控制
- [Skydimo OpenRGB](https://gitlab.com/skydimo-team/skydimo-open-rgb) — Skydimo 的设备优化分支
- [Skydimo](https://skydimo.com) — 硬件制造商
- [Model Context Protocol](https://modelcontextprotocol.io) — MCP 规范
