Mcp Divoom TimeFrame Lan

mcp-divoom-lan

mcp-divoom-lan 是一个开源 MCP 服务，用于控制 TimesFrame/AstroToo 表盘以及 PIXOO64/TimeGate 局域网显示屏。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 个专用工具可控制五个独立的 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、本地大模型等）通过自然语言执行表盘操作
• 保持安全边界（先读取再写入、对高风险操作发出明确警告、遵守分段规则）

默认安全策略（重要）

• 选择产品配置文件： 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 → 硬件识别和局域网功能报告
• watchface_get_local → Device/GetLocalClockInfo
• watchface_patch_local → 管理槽位的 upsert，不需要调用方提供 ClockId。现有配置使用 Device/PatchLocalClockInfo；提供背景图和完整项目表时，会创建缺失的配置。
• watchface_get_fonts_local → Device/GetLocalFontList
• watchface_get_store_market_list → Device/GetStoreClockMarketList
• watchface_set_clock_select → Channel/SetClockSelectId（TimesFrame 会在一个串行化的 MCP 操作中排队发送一对请求，因此手动选择会在当前时段内停用生效中的传统日程；AstroToo 只发送一次）
• 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 分开处理。仅限本地的 MCP 模式会阻止 TimesFrame 通用的 /upload。
• watchface_create_local_clock → 管理槽位的 multipart upsert，不需要调用方提供 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 Bundle（.mcpb）

对于兼容 MCPB 的宿主（例如 Claude 桌面连接器、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，以及一个包含 设备 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 是可选项。如果不设置，当一个 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

生成器会向 https://appchina.divoom-gz.com/ + 命令字符串发送 JSON 正文。它会从 Device/GetClockDefaultList（IsDefault=1）获取默认 ID，从 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 — 安全与常见问题解答
• docs/reference/ — 精简版协议规则（EN/ZH）
• docs/examples/ — 请求与响应示例及目录

环境变量

• DIVOOM_DEVICE_HOST — 设备的局域网 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，请遵循 GLAMA_SUBMISSION_READY.md（包括 Dockerfile 和 glama.json）。对于 MCP.so，请遵循 MCP_SO_SUBMISSION_READY.md。对于 Volcengine MCP 目录，请参阅 VOLCENGINE_SUBMISSION_READY.md（PR: https://github.com/volcengine/mcp-server/pull/398）。对于通过 npx 部署的阿里云百炼自定义 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/

优势：

• MCP 安装包小，适用于所有 AI 客户端
• 非开发者可以通过可视化界面了解 ItemList，再让 AI 应用补丁
• 清晰区分所见即所得编辑与自动化 MCP 写入

与上游文档保持一致

此仓库在 docs/、docs/reference/ 和 docs/examples/ 下提供独立文档。如果你在其他位置维护完整指南，请保持此目录树同步，或将其视为发行版子集。