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/ 下維護獨立文檔。如果你在其他地方維護完整指南，請保持此目錄樹同步，或將其視為分發子集。