MCP Divoom Lan

🌐 mcp-divoom-lan

Divoom ウォッチフェイス LAN API を AI クライアント向けの標準ツールとしてラップするオープンソース MCP サーバー

mcp-divoom-lan は、Divoom ウォッチフェイス LAN API を AI クライアント向けの標準ツールとしてラップするオープンソース MCP サーバーです。

v2 HTML ビジュアルエディタと連携し、ウォッチフェイスの変更、フェイス切り替え、明るさ調整、新しいローカルウォッチフェイスの作成を行えます。

v2 ビジュアルエディタ（公開）:

• GitHub: https://github.com/DivoomDevelop/divoom-watchface-visual-editor_v2
• ライブサイト: https://divoomdevelop.github.io/divoom-watchface-visual-editor_v2/

ローカルクローンパス（例: D:\divoom-watchface-visual-editor）はマシン固有です。ドキュメントと MCP メタデータでは、上記の v2 GitHub / GitHub Pages URL を使用してください。

🎯 目的

• Divoom_Watchface_Remote_Customization_Guide_EN.md の主要機能を MCP ツールとして公開する
• Cursor、Claude Desktop、ローカル LLM など MCP 対応クライアントから、自然言語でウォッチフェイス操作を実行できるようにする
• 安全境界を維持する（書き込み前の読み取り、危険操作に対する明示的な警告、multipart ルール）

🛡️ デフォルト安全ポリシー（重要）

• 書き込み前に読み取り: watchface_get_local を呼び、次に watchface_patch_local、その後で読み戻して検証します。
• GetLocalClockInfo が 空の ItemList を返した場合: 書き込みを停止し、先に編集可能なウォッチフェイスへ切り替えてください。
• ユーザーが新しいウォッチフェイスの作成を明確に求めていない限り、watchface_create_local_clock を呼び出さないでください（暗黙的な作成は禁止）。

🧰 実装済みツール

• watchface_get_local → Device/GetLocalClockInfo
• watchface_patch_local → Device/PatchLocalClockInfo（デフォルト /divoom_api）。任意の dialAssetsPath は multipart POST /patch_local_clock に切り替えます（watchface_create_local_clock と同じ dial/tar.gz ルール）。
• 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_onoff_screen → Channel/OnOffScreen（1=オン、0=オフ）
• watchface_replace_dial_bg_file → POST /replace_clock_dial_bg
• watchface_upload_file → POST /upload
• watchface_create_local_clock → POST /create_local_clock（multipart: 単一のダイヤル画像 または tar.gz。JSON の DialAssets/UseDialAssetBundle がモードを選択。デフォルトは gzip 自動検出）
• watchface_reset_local_then_cloud → Device/ResetLocalClockFromServer
• watchface_get_screen_snapshot → Device/GetScreenSnapshot（2 秒待機後、/userdata/snapshot.webp を GET して視覚差分を確認）
• watchface_raw_command → 汎用 POST /divoom_api
• watchface_protocol_quick_reference → モデル向けの主要プロトコル制約

📚 リソース（モデル向けコンテキスト）

サーバーは 2 つの MCP リソースを公開します:

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

📦 MCP バンドル (.mcpb)

MCPB 互換ホスト（例: Claude Desktop コネクタ、Smithery stdio リリース）向けに、ローカルバンドルをビルドします:

1. パッカーをインストール: npm install -g @anthropic-ai/mcpb
2. このパッケージルートで: npm run mcpb:pack
3. 出力: mcp-divoom-lan.mcpb（gitignore 対象）。ステージングディレクトリ mcpb/staging/ も gitignore 対象です。

バンドルには dist/、resources/、本番用 node_modules、および デバイス IP、ポート、タイムアウト のユーザー入力フィールドを持つ manifest.json が含まれます。

🚀 クイックスタート

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

開発（watch 再ビルド）:

npm run dev

リリース前チェック（typecheck、build、pack dry-run）:

npm run release:check

📖 ドキュメント

• docs/README.md — ドキュメント索引
• docs/quick-start.md — 最小セットアップ
• docs/tool-examples.md — ツール使用例（§5b アナログポインタレイアウトを含む）
• docs/disp-usage.md — disp ID の選択（ポインタレイアウト 131/132/233、ネットギャラリーの一意性 13/125–130/173–175）
• docs/html-visual-editor.md — MCP でビジュアルエディタを使用する
• docs/safety-and-troubleshooting.md — 安全と FAQ
• docs/reference/ — 凝縮されたプロトコルルール（EN/ZH）
• docs/examples/ — サンプルリクエスト/レスポンスとカタログ

⚙️ 環境変数

• DIVOOM_DEVICE_HOST — デバイスの LAN IP（例: 192.168.1.120）
• DIVOOM_DEVICE_PORT — HTTP ポート、デフォルト 9000
• DIVOOM_TIMEOUT_MS — リクエストタイムアウト（ms）、デフォルト 45000

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 リリース（例: 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 は軽量に保ちます。エディタは別のオプションプロジェクトとして提供します。

• コア: https://github.com/DivoomDevelop/mcp-divoom-lan
• ビジュアルエディタ v2: https://github.com/DivoomDevelop/divoom-watchface-visual-editor_v2
• ホスト版 v2: https://divoomdevelop.github.io/divoom-watchface-visual-editor_v2/

利点:

• すべての AI クライアントに適した小さい MCP インストール
• 非開発者でもビジュアル UI で ItemList を理解し、その後 AI にパッチ適用を任せられる
• WYSIWYG 編集と自動 MCP 書き込みを明確に分離

🔄 上流ドキュメントとの整合性

このリポジトリは docs/、docs/reference/、docs/examples/ 配下にスタンドアロンのドキュメントを同梱しています。完全なガイドを別で管理している場合は、このツリーを同期するか、配布用サブセットとして扱ってください。