mcp-divoom-lan

mcp-divoom-lan 是一个可开源发布的 MCP Server，将 Divoom 表盘局域网 API 封装为标准工具，便于 AI 客户端直接调用。

支持与 HTML 可视化编辑器协同，覆盖表盘修改、表盘选择、亮度调节与新表盘创建。

可视化编辑器公开地址：

GitHub: https://github.com/DivoomDevelop/divoom-watchface-visual-editor
在线页面: https://divoomdevelop.github.io/divoom-watchface-visual-editor/

目标

将 Divoom_Watchface_Remote_Customization_Guide_EN.md 中的关键能力转成 MCP Tools
让支持 MCP 的客户端（Cursor、Claude Desktop、本地模型等）通过自然语言执行表盘操作
保留安全边界（读前写、危险命令显式提示、multipart 规则）

默认安全策略（重要）

先读后写：先 watchface_get_local，再 watchface_patch_local，最后回读确认。
若 GetLocalClockInfo 返回 ItemList 为空：立即停止写入，先切换到可编辑表盘再继续。
非用户明确要求时，禁止调用 watchface_create_local_clock（不要隐式新建表盘）。

已实现工具

watchface_get_local -> Device/GetLocalClockInfo
watchface_patch_local -> Device/PatchLocalClockInfo
watchface_get_fonts_local -> Device/GetLocalFontList
watchface_get_store_market_list -> Device/GetStoreClockMarketList
watchface_set_clock_select -> Channel/SetClockSelectId
watchface_get_brightness -> Sys/GetBrightness
watchface_set_brightness -> Channel/SetBrightness
watchface_replace_dial_bg_file -> POST /replace_clock_dial_bg
watchface_upload_file -> POST /upload
watchface_create_local_clock -> POST /create_local_clock
watchface_reset_local_then_cloud -> Device/ResetLocalClockFromServer
watchface_raw_command -> 通用 POST /divoom_api
watchface_protocol_quick_reference -> 返回协议关键约束

Resource（知识上下文）

Server 暴露了两份 MCP Resource，可用于给模型补充上下文：

divoom://guide/quick-reference
divoom://skill/watchface-customization

快速开始

cd tools/mcp-divoom-lan
npm install
npm run build
npm start

开发调试：

npm run dev

发布前一键检查：

npm run release:check

使用文档（新增）

docs/README.md：文档索引
docs/quick-start.md：快速上手
docs/tool-examples.md：工具调用示例
docs/html-visual-editor.md：配合 HTML 可视化编辑器
docs/safety-and-troubleshooting.md：安全边界与常见问题
docs/reference/：协议关键约束提炼（中英）
docs/examples/：请求/响应样例（含目录清单）

环境变量

DIVOOM_DEVICE_HOST：设备 LAN IP（例如 192.168.1.120）
DIVOOM_DEVICE_PORT：HTTP 端口，默认 9000
DIVOOM_TIMEOUT_MS：请求超时，默认 45000

如果不设置 DIVOOM_DEVICE_HOST，则每次调用工具时必须传 target.host。

客户端配置示例

Cursor / Claude Desktop（stdio）

{
  "mcpServers": {
    "divoom-lan": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/to/tools/mcp-divoom-lan/dist/index.js"
      ],
      "env": {
        "DIVOOM_DEVICE_HOST": "192.168.1.120",
        "DIVOOM_DEVICE_PORT": "9000",
        "DIVOOM_TIMEOUT_MS": "45000"
      }
    }
  }
}

也可直接使用本目录的 client-config.example.json 作为模板。

发布方案（可直接执行）

新建独立仓库（建议名 mcp-divoom-lan），复制本目录内容作为仓库根目录。
检查并更新元数据（已内置）：
- LICENSE
- SECURITY.md
- CONTRIBUTING.md
- CHANGELOG.md
- RELEASE.md
运行 npm run release:check，确认构建、类型检查、打包检查全部通过。
GitHub Release 发布 v0.1.0，附上使用截图与请求示例。
向 MCP 目录提交：
- 官方 MCP Registry
- Smithery
- Glama
- 其他社区目录（如 mcp.so）
同步发布“最小可复现演示”：
- watchface_get_local 读配置
- watchface_patch_local 改字体大小和颜色
- watchface_replace_dial_bg_file 替换底图

发布收尾文件（已包含）

LICENSE：开源许可证（MIT）
CHANGELOG.md：版本变更记录
CONTRIBUTING.md：贡献规范
SECURITY.md：安全漏洞提交流程
RELEASE.md：发版操作手册
PUBLISH_CHECKLIST.md：发版检查清单
GITHUB_RELEASE_NOTES_v0.1.0.md：可直接使用的 Release 正文模板
MCP_DIRECTORY_LISTING_TEMPLATE.md：MCP 目录提交通用模板
GITHUB_RELEASE_NOTES_v0.1.0_READY.md：可直接替换占位符的 Release 正文
MCP_REGISTRY_SUBMISSION_READY.md：官方 MCP Registry 提交文案
SMITHERY_SUBMISSION_READY.md：Smithery 提交文案
GLAMA_SUBMISSION_READY.md：Glama 提交文案
.github/workflows/ci.yml：CI（check/build/pack）

是否要打包 HTML 可视化编辑器？

建议：要，但作为可选增强包，不要和 MCP 核心耦合。

核心包（必须）：https://github.com/DivoomDevelop/mcp-divoom-lan
可视化包（建议）：https://github.com/DivoomDevelop/divoom-watchface-visual-editor
在线编辑器（GitHub Pages）：https://divoomdevelop.github.io/divoom-watchface-visual-editor/

这样做的好处：

MCP 工具保持轻量，适合所有 AI 客户端
非技术用户可以先在可视化页面理解 ItemList，再让 AI 下发 patch
便于后续演进为“所见即所得 + AI 指令”的组合体验

与现有文档对齐

当前仓库已内置可独立发布的最小文档：docs/ + docs/reference/ + docs/examples/
若你在源码大仓中维护协议细节，可继续保留完整 Guide / EXAMPLE / SKILL 作为上游源

注意：CHANGELOG.md 底部的 GitHub Release 链接目前是占位地址，创建正式仓库后请替换为真实 URL。

mcp-divoom-lan

mcp-divoom-lan

目标

默认安全策略（重要）

已实现工具

Resource（知识上下文）

快速开始

使用文档（新增）

环境变量

客户端配置示例

Cursor / Claude Desktop（stdio）

发布方案（可直接执行）

发布收尾文件（已包含）

是否要打包 HTML 可视化编辑器？

与现有文档对齐

Reviews