Mcp Divoom TimeFrame Lan

mcp-divoom-lan

mcp-divoom-lan は、TimesFrame/AstroToo のウォッチフェイスと PIXOO64/TimeGate の LAN ディスプレイ制御に対応するオープンソースの MCP サーバーです。TimesFrame/AstroToo は Device/GetHardwareVersion を照会します。PIXOO64/TimeGate は、検出された Hardware または明示的なハードウェアプロファイルを使用します。不明なハードウェアは拒否されます。利用可能な検出データを確認したうえで、TimesFrame で応答がない場合のフォールバックを維持しています。

PIXOO64 Hardware 90/92 は 80/post、96 は 9000/divoom_api を使用します。10 個の専用ツールで、ディスプレイ要素、テキスト、RGB アニメーション、制御コマンドを送信します。Hardware 96 のコマンドリストは、参照ファームウェアに合わせるため、MCP 内で順番に実行されます。PIXOO64 のガイドと例を参照してください。デバイスのファームウェアは変更されません。

ウォッチフェイスの編集、切り替え、明るさの調整、新しいローカルウォッチフェイスの作成には、v2 HTML ビジュアルエディターを併用できます。

TimeGate Hardware 400 は 80/post、402 は 9000/divoom_api を使用します。10 個の専用ツールで、独立した 5 つの 128×128 画面を制御します。デバイス設定から取得した LocalToken が必要です。Hardware 402 のバッチは、MCP 内で順番に実行されます。バージョンごとのフィールド、配置、背景の違いについては、TimeGate ガイドを参照してください。デバイスのファームウェアは変更されません。

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 ツールとして公開する
• MCP 対応クライアント（Cursor、Claude Desktop、ローカル LLM など）が自然言語でウォッチフェイスの操作を実行できるようにする
• 安全性の境界を維持する（書き込み前の読み取り、リスクのある操作に対する明示的な警告、マルチパートのルール）

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

• 製品プロファイルを選択します： Hardware 510/511/512 は TimesFrame、530 は AstroToo、90/92/96 は PIXOO64、400/402 は TimeGate を選択します。明示的な target.hardware は呼び出し元によるプロファイルの上書きです。これらの製品には pixoo64_* または timegate_* を使用してください。以下の管理対象ウォッチフェイスのルールは TimesFrame/AstroToo に適用されます。
• 内部管理スロット： ユーザーと MCP クライアントは、作成およびパッチ適用の呼び出しで ClockId を省略します。サーバーが管理スロットを挿入し、最初に読み取ってから、存在しない場合は作成し、存在する場合は更新します。
• 書き込み前に読み取ります： MCP サーバーは管理スロットを事前確認してから書き込みます。その後、クライアントは読み戻して確認してください。
• GetLocalClockInfo が空の ItemList を返す場合： 書き込みを中止し、まず編集可能なウォッチフェイスに切り替えてください。
• 編集には watchface_patch_local を優先してください。ユーザーがウォッチフェイスの作成を求めた場合、または管理対象の設定と背景全体を意図的に置き換える場合は、watchface_create_local_clock を使用してください。

実装済みツール（42）

検出ツール（1）：

• watchface_list_devices → 選択可能な TimesFrame／AstroToo／PIXOO64／TimeGate のターゲットと、製品固有のデフォルトポートを返します

デバイスツール（15）：

• watchface_get_device_info → ハードウェアの識別情報と LAN 機能のレポート
• watchface_get_local → Device/GetLocalClockInfo
• watchface_patch_local → 呼び出し元から ClockId を指定せずに、管理対象スロットを追加または更新します。既存の設定には Device/PatchLocalClockInfo を使用します。背景と完全なアイテムテーブルが指定されている場合、設定がなければ新規作成します。
• watchface_get_fonts_local → Device/GetLocalFontList
• watchface_get_store_market_list → Device/GetStoreClockMarketList
• watchface_set_clock_select → Channel/SetClockSelectId（TimesFrame では、手動選択によって現在の期間の従来のスケジュールが抑制されるよう、1 回のシリアル化された MCP 操作内でペアのリクエストをキューに登録します。AstroToo では 1 回だけ送信します）
• 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 → AstroToo 専用の POST /upload_local_asset。成功した作成／更新で使用する、一時的な local:// ステージング参照を返します。AstroToo では製品写真／ピクセル用の POST /upload は別扱いです。TimesFrame ではローカルのみの MCP モードで汎用 /upload はブロックされます。
• watchface_create_local_clock → 呼び出し元から ClockId を指定せずに、管理対象スロットをマルチパート形式で追加または更新します。設定がない場合は /create_local_clock、すでにある場合は /patch_local_clock を使用します。
• watchface_reset_local_then_cloud → Device/ResetLocalClockFromServer
• watchface_get_screen_snapshot → Device/GetScreenSnapshot（返された AstroToo のスナップショットパスをダウンロードします。TimesFrame では WebP フォールバックを維持します）
• watchface_raw_command → 汎用の POST /divoom_api

オフライン／モデル認識型の作成ツール（6）：

• watchface_protocol_quick_reference → モデル向けの主要なプロトコル制約
• watchface_clock_catalog → 製品固有の ClockId、中国語／英語の名称、フォント、disp、アイテム ID の仕様。ネイティブ設定は任意です。
• watchface_disp_catalog → モデル固有の disp カタログとフィルター
• watchface_font_catalog → モデル固有のフォントカタログ。稼働中の AstroToo ターゲットがある場合、ローカルで利用可能なフォントを AstroToo の名前に統合します。
• watchface_template_search → 厳選された TimesFrame または AstroToo の文字盤テンプレート
• watchface_layout_suggest → モデル固有のレイアウトのヒント。AstroToo に TimesFrame の座標統計が渡されることはありません。

PIXOO64 ツール（10）：pixoo64_get_device_info、pixoo64_send_animation、pixoo64_send_items、pixoo64_send_text、pixoo64_clear_text、pixoo64_set_brightness、pixoo64_onoff_screen、pixoo64_set_channel、pixoo64_play_gif、pixoo64_command_list。divoom://pixoo64/guide と divoom://pixoo64/example を参照してください。LAN のターゲットを直接指定する場合は、{ "host":"192.168.1.100", "model":"pixoo64", "hardware":90 } のように指定できます。バージョンのデフォルト値を使用するには、port と DIVOOM_DEVICE_PORT を省略してください。

TimeGate ツール（10）：timegate_get_device_info、timegate_send_items、timegate_send_text、timegate_clear_text、timegate_set_brightness、timegate_get_brightness、timegate_onoff_screen、timegate_select_clock、timegate_play_gif、timegate_command_list。divoom://timegate/guide と divoom://timegate/example を参照してください。認証が必要な呼び出しでは、実際のデバイス設定から取得した localToken を指定します。

リソース（モデルのコンテキスト）

製品データはディレクトリごとに格納されています：resources/timesframe、resources/astrotoo、resources/pixoo64、resources/timegate、resources/common。resources/products.json には、ハードウェアの対応関係、画面ごとのキャンバスサイズ、ディレクトリ、ルートが記録されています。実行時のローダーが別の製品のデータにフォールバックすることはありません。

元のリソース URI は TimesFrame のセマンティクスを維持しています。AstroToo には、480×480 の専用リソースがあります：

• divoom://products/catalog
• divoom://guide/quick-reference
• divoom://skill/watchface-customization
• divoom://font/catalog
• divoom://font/guide
• divoom://disp/catalog
• divoom://watchface/schema
• divoom://watchface/example-minimal
• divoom://guide/ai-watchface
• divoom://templates/curated
• divoom://astrotoo/guide
• divoom://astrotoo/disp/summary
• divoom://astrotoo/disp/catalog
• divoom://astrotoo/disp/guide/en
• divoom://astrotoo/disp/guide/zh-cn
• divoom://astrotoo/font/catalog
• divoom://astrotoo/clocks/catalog
• divoom://astrotoo/clocks/configs
• divoom://astrotoo/templates/curated
• divoom://astrotoo/watchface/example-minimal
• divoom://astrotoo/watchface/schema

MCP バンドル（.mcpb）

MCPB 互換ホスト（Claude デスクトップコネクタ、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 が格納されます。

クイックスタート

公開済み npm パッケージ：

{
  "mcpServers": {
    "divoom-lan": {
      "command": "npx",
      "args": ["-y", "mcp-divoom-lan@latest"],
      "env": {
        "DIVOOM_DEVICE_HOST": "192.168.1.120",
        "DIVOOM_DEVICE_PORT": "9000",
        "DIVOOM_DEVICE_MODEL": "auto",
        "DIVOOM_TIMEOUT_MS": "45000"
      }
    }
  }
}

DIVOOM_DEVICE_HOST は省略可能です。設定せず、1 つの MCP サーバーで複数のデバイスを制御する場合は、各ツール呼び出しに target.host を含めてください。

ソースからビルド：

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

開発（変更を監視して再ビルド）：

npm run dev

シミュレーターと Divoom コマンドサーバーから AstroToo リソースを再生成：

$env:DIVOOM_ASTROTOO_SIMULATOR_ROOT='D:\work\divoom_product\timebox\trunck\device\tool_src\lv_sim_visual_studio\LvglAstroTooSimulator'
$env:DIVOOM_ASTROTOO_DEVICE_ID='300400436'
npm run build:astrotoo

ジェネレーターは、JSON ボディを使って https://appchina.divoom-gz.com/ + コマンド文字列を呼び出します。デフォルト ID は Device/GetClockDefaultList（IsDefault=1）から、フォント名は Device/GetFontForAI から、不足している設定は Device/GetClockInfoV3 から取得します。

リリース前チェック（型チェック、ビルド、パックのドライラン）：

npm run release:check

ドキュメント

• docs/README.md — ドキュメントのインデックス
• docs/quick-start.md — 最小限のセットアップ
• docs/mcp-tools.md — 全 42 ツールの API カタログとモデル固有のファイルポリシー
• docs/astrotoo-and-multiple-devices.md — ハードウェア検出、複数のターゲット、AstroToo のローカルストレージ
• docs/astrotoo-watchface-workflow.md — AstroToo のウォッチフェイスを作成、更新、切り替え、スクリーンショット撮影するリリース対応ワークフロー
• docs/adding-products.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 — オプションの上書き値です。PIXOO64 90/92 または TimeGate 400 の場合は 80、それ以外は 9000 を使用します。省略可能です。
• DIVOOM_DEVICE_MODEL — auto（デフォルト）、timesframe、astrotoo、pixoo64、または timegate
• DIVOOM_DEVICE_HARDWARE — オプションのデフォルトデバイスプロファイル：PIXOO64 90/92/96 または TimeGate 400/402。省略するとデバイスを検出します。
• DIVOOM_TIMEGATE_LOCAL_TOKEN — オプションのデフォルトのTimeGate設定にあるLocalTokenです。ホストを基準に照合されます。それ以外の場合は、呼び出しごとに localToken を指定してください。
• DIVOOM_TIMEOUT_MS — リクエストのタイムアウト（ミリ秒）。デフォルトは 45000 です。

DIVOOM_DEVICE_HOST が設定されていない場合は、各ツール呼び出しで target.host を指定する必要があります。複数のデバイスを操作するには、呼び出しごとに異なる target を指定してください。サーバーはホストごとに一連の操作をまとめて直列化しつつ、各デバイスの独立した処理は並行して実行します。

クライアント設定例（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_DEVICE_MODEL": "auto",
        "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.3.0）。
5. 適切な掲載先（MCP Registry、Smithery、Glama、MCP.so、およびコミュニティのインデックス）に登録を申請します。Glama については、Dockerfile と glama.json を含む GLAMA_SUBMISSION_READY.md に従ってください。MCP.so については、MCP_SO_SUBMISSION_READY.md に従ってください。Volcengine MCP カタログについては、VOLCENGINE_SUBMISSION_READY.md を参照してください（PR：https://github.com/volcengine/mcp-server/pull/398）。npx でデプロイする Alibaba Cloud Bailian カスタム MCP については、BAILIAN_MCP_SUBMISSION_READY.md を参照してください。Coze HTTP プラグインの公開については、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/ に単独で利用できるドキュメントが含まれています。別の場所で包括的なガイドを管理している場合は、このディレクトリ構成との同期を保つか、配布用のサブセットとして扱ってください。