MCP Divoom Lan

🎨 mcp-divoom-lan

mcp-divoom-lan 是一个开源 MCP 服务器，将 Divoom 表盘局域网 API 封装为标准化工具，供各类 AI 客户端调用。

它可与 v2 HTML 可视化编辑器协同工作，用于修改表盘、切换表面、调节亮度以及创建本地新表盘。

🖼️ v2 可视化编辑器（公开）

💡 使用建议

本地克隆路径（如 D:\divoom-watchface-visual-editor）因机器而异，请在文档和 MCP 元数据中统一使用上述 v2 GitHub / GitHub Pages 地址。

🎯 项目目标

• 将 Divoom_Watchface_Remote_Customization_Guide_EN.md 中的核心能力封装为 MCP 工具
• 让支持 MCP 的客户端（Cursor、Claude Desktop、本地 LLM 等）通过自然语言驱动表盘操作
• 保持安全边界（先读后写、危险操作显式警告、multipart 规则）

🛡️ 默认安全策略（重要）

⚠️ 核心原则

• 先读后写：先调用 watchface_get_local，再调用 watchface_patch_local，最后回读验证结果。
• 若 GetLocalClockInfo 返回 空 ItemList：立即停止写入操作，先切换到一个可编辑的表盘。
• 除非用户明确要求创建新表盘，否则不要调用 watchface_create_local_clock（禁止隐式创建）。

🧰 已实现的工具

📚 MCP 资源（模型上下文）

服务器暴露两个 MCP 资源：

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

📦 MCP Bundle (.mcpb)

针对兼容 MCPB 的宿主（例如 Claude Desktop 连接器、Smithery stdio 发布包），可按以下步骤构建本地 bundle：

1. 安装打包工具：npm install -g @anthropic-ai/mcpb
2. 在包根目录执行：npm run mcpb:pack
3. 产物：mcp-divoom-lan.mcpb（已被 gitignore 忽略）。暂存目录 mcpb/staging/ 同样被 gitignore 忽略。

该 bundle 包含 dist/、resources/、生产环境 node_modules，以及一个 manifest.json，其中包含面向用户的 设备 IP、端口 和 超时时间 字段。

🚀 快速开始

cd tools/mcp-divoom-lan  # or your clone root for this package
npm install
npm run build
npm start

开发模式（监听并自动重建）：

npm run dev

发版前检查（类型检查、构建、打包 dry-run）：

npm run release:check

📖 文档

⚙️ 环境变量

💡 使用提示

若未设置 DIVOOM_DEVICE_HOST，则每次工具调用都必须传入 target.host。

💻 客户端配置示例（stdio）

Cursor / Claude Desktop

{
  "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 作为起始配置。

📤 发布清单（面向维护者）

1. 使用专用仓库（例如 mcp-divoom-lan），并将本包放置在仓库根目录。
2. 核对元数据文件：LICENSE、SECURITY.md、CONTRIBUTING.md、CHANGELOG.md、RELEASE.md（按需）。
3. 运行 npm run release:check。
4. 打 GitHub Release 标签（例如 v0.1.2），可附上截图和示例请求。
5. 在合适的渠道提交收录（MCP Registry、Smithery、Glama、MCP.so、社区索引）。其中：
   • Glama：遵循 GLAMA_SUBMISSION_READY.md（含 Dockerfile 与 glama.json）。
   • MCP.so：遵循 MCP_SO_SUBMISSION_READY.md。
   • 火山引擎 MCP 清单：见 VOLCENGINE_SUBMISSION_READY.md（PR：https://github.com/volcengine/mcp-server/pull/398）。
   • 阿里云百炼自定义 MCP（控制台 npx 部署）：见 BAILIAN_MCP_SUBMISSION_READY.md。
   • 扣子 Coze 插件发布/商店（HTTP 插件，与 MCP 不同）：见 COZE_SUBMISSION_READY.md。
6. 最小演示流程：watchface_get_local → watchface_patch_local（字号/颜色）→ watchface_replace_dial_bg_file（背景）。

📁 发布时常用文件

本仓库包含（存在时）：LICENSE、CHANGELOG.md、CONTRIBUTING.md、SECURITY.md、RELEASE.md、可选的清单与目录模板，以及 .github/workflows/ci.yml。

🤔 HTML 可视化编辑器是否应随 npm 包一起发布？

建议：核心 MCP 包不打包编辑器——保持 MCP 精简。将编辑器作为独立可选项目提供。

优势：

• MCP 安装包体积小，适用于所有 AI 客户端
• 非开发者可通过可视化界面理解 ItemList，再交由 AI 应用补丁
• 所见即所得编辑与自动化 MCP 写入职责清晰分离

🔗 与上游文档的对齐

本仓库在 docs/、docs/reference/、docs/examples/ 下维护独立文档。如果你在其他地方维护完整指南，请保持此目录树同步，或将其视为分发子集。