内容
# Halo PixelBar MCP
一个用于控制EDIFIER Halo PixelBar的本地MCP服务器，可通过AI在Windows上进行控制。它开放了一个允许列表，用于环境光、像素屏幕和扬声器的独立硬件音量。
> 这是一个独立的社区项目。它与EDIFIER无关，也不受EDIFIER的认可或支持。
参见[PROTOCOL_NOTES.md](PROTOCOL_NOTES.md)，了解观察到的包格式、字段映射和实时硬件测试。
## 前置条件
- Windows 10 或 Windows 11。
- 一个 **EDIFIER Halo PixelBar（花再）**，暴露USB VID `0x2D99`，PID `0xA106`，HID接口 `4`，使用页面 `0xFF14`，使用 `1`。
- 一个可以传输数据的USB连接，而不是仅限于供电的电缆。当Windows可以枚举HID接口时，数据传输适配器或扩展坞是可以的。
- Python 3.11 或更新版本。
- 一个可以启动stdio服务器的本地MCP主机，例如Codex或Claude Desktop。
EDIFIER TempoHub在协议验证过程中已安装，但此MCP不调用TempoHub，不读取EDIFIER帐户，也不要求帐户凭证。设备过滤器故意严格；其他EDIFIER扬声器和PixelBar修订版不被假定为兼容。
## 安装
```powershell
git clone https://github.com/Seraph310/halo-pixelbar-mcp.git
cd halo-pixelbar-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
```
### Codex 配置
将以下内容添加到 `%USERPROFILE%\.codex\config.toml` 中，替换两个路径：
```toml
[mcp_servers.halo_pixelbar]
command = 'C:\path\to\halo-pixelbar-mcp\.venv\Scripts\python.exe'
args = ['C:\path\to\halo-pixelbar-mcp\server.py']
startup_timeout_sec = 30
```
在更改MCP主机的配置后，请重新启动。
## 工具
| 工具 | 用途 |
| --- | --- |
| `get_halo_status` | 检测验证的HID控制接口 |
| `get_halo_volume` | 读取独立的0-16扬声器音量 |
| `set_halo_volume` | 设置硬件音量并通过查询再次验证 |
| `show_halo_text` | 显示带有安全布局的短UTF-8消息 |
| `set_halo_scene` | 选择内置时钟、游戏、工作、阅读、宠物、迷因、赛博或波形场景 |
| `set_halo_screen_color` | 设置像素屏幕主题颜色 |
| `set_halo_ambient` | 设置灯光效果、RGB颜色、亮度和速度 |
| `set_halo_ambient_power` | 仅打开或关闭环境光 |
## 测试环境
- Windows 11 64位，版本 `26200`。
- EDIFIER Halo PixelBar（花再），USB VID `0x2D99`，PID `0xA106`。
- EDIFIER TempoHub安装程序版本 `1.2.6`。
- Python `3.11.5`。
- 数据传输USB适配器；当Windows仍可以枚举HID接口时，不需要直接连接到主板的USB接口。
## 安全边界
- 仅针对确切验证的VID、PID、接口、使用页面、使用和匹配的Halo/PixelBar产品名称。
- 不暴露任意HID包、固件、工厂重置、帐户、文件或shell命令工具。
- 在写入之前验证颜色、场景、效果、速度、亮度、布局、文本长度和硬件音量。
- 不需要或读取EDIFIER TempoHub凭证。
- 从公共MCP状态结果中省略物理设备序列号。
## 可选音乐伴侣
将此服务器与[CloudMusic Desktop MCP](https://github.com/Seraph310/cloudmusic-desktop-mcp)配对，以允许MCP主机协调AI选择的音乐与灯光、屏幕和硬件音量变化。两个服务器是独立的，可以单独安装。
## 协议归属
包格式通过本地设备观察、安装的官方控制器和实时读取测试建立。同时还与MIT许可的[XFEstudio/HaloPixelToolBox](https://github.com/XFEstudio/HaloPixelToolBox)实现和官方Halo PixelBar用户手册进行了比较。没有提取的TempoHub二进制文件、反编译文件、凭证、固件或研究快照包含在此仓库中。
## 测试
```powershell
.\.venv\Scripts\python.exe -m pytest -q
```
## 致谢
由Celia和OpenAI Codex共同构建。
Celia领导产品方向和实时硬件验证。Codex协助逆向工程、实现和测试。
## 许可证
[MIT](LICENSE)
