mcp-divoom-lan

Official

Overview Schema Source Related Servers Discussions Admin

watchface_patch_local

Upserts the MCP-managed local watchface on a Divoom device, applying field-only or asset updates and creating the slot when missing.

Instructions

Upsert the MCP-managed local watchface. The server injects its managed ClockId, reads that slot first, updates it when present, and creates it when missing if dialAssetsPath plus complete ItemList and ItemIdList are supplied. Callers do not provide a ClockId. Field-only updates use POST /divoom_api; asset updates use multipart. Prefer ItemPatchList for existing rows and do not include item_id inside patch.* unless explicitly renaming a slot. TimesFrame accepts a JPEG/WebP backdrop or clock_bg.tar.gz bundle. AstroToo accepts one JPEG/WebP backdrop only after element files are uploaded separately and bound through local:// FileId values. AstroToo rejects TAR/TGZ/ZIP and bundle_image. For AstroToo, first query hardware/capabilities; use the 480x480 AstroToo resources. Legacy 800x1280 examples and typography apply only to TimesFrame.

Input Schema

Name	Required	Description
`target`	No	Optional per-call target override. If omitted, environment variables are used.
`fileName`	No	Multipart filename header for dialAssetsPath. Defaults to basename(dialAssetsPath).
`itemList`	No
`itemIdList`	No
`filePartName`	No	Multipart field name for dialAssetsPath part. Default is current UTC ms timestamp.
`setColorList`	No
`itemPatchList`	No
`deviceImageUrl`	No
`dialAssetsPath`	No	Optional second multipart part. AstroToo: one JPEG/WebP backdrop only; element files must already have been uploaded individually and referenced by local:// FileId. TimesFrame: either a single backdrop or clock_bg.tar.gz bundle. When set, the tool POSTs /patch_local_clock.
`itemPatchByRoleList`	No
`devicePreviewImageUrl`	No
`devicePreviewImageUrl2`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.3.0Oct 30, 2026

removedInput schema / properties / clockId

Removed value: -{
-  "type": "integer"
-}

changedInput schema / properties / dialAssetsPath / description

Previous value: -"Optional second multipart part. Either a single JPEG/WebP dial backdrop (`clock_bg.jpg|webp`, validated by divoom_watchface_replace_clock_dial_bg_validate_saved_file) or a `clock_bg.tar.gz` bundle. The tarball may contain `clock_bg.jpg|webp` plus the leaves listed by `ItemPatchList[].patch.bundle_image`. Element leaves inside the tar may be JPEG/WebP/PNG (PNG is element-only; backdrop must be JPEG/WebP). When set, the tool POSTs `/patch_local_clock` with the firmware-strict multipart layout."New value: +"Optional second multipart part. AstroToo: one JPEG/WebP backdrop only; element files must already have been uploaded individually and referenced by local:// FileId. TimesFrame: either a single backdrop or clock_bg.tar.gz bundle. When set, the tool POSTs /patch_local_clock."

changedInput schema / properties / itemIdList / items / type
```
Previous value: -"integer"New value: +"string"
```

addedInput schema / properties / target / properties / hardware

Added value: +{
+  "description": "Explicit PIXOO64 90/92/96 or TimeGate 400/402 profile for direct LAN control. Must match the actual device; this is not a firmware version.",
+  "enum": [
+    90,
+    92,
+    96,
+    400,
+    402
+  ],
+  "type": "integer"
+}

addedInput schema / properties / target / properties / model

Added value: +{
+  "default": "auto",
+  "description": "PIXOO64/TimeGate use discovery Hardware or target.hardware; TimesFrame/AstroToo query Hardware on the device.",
+  "enum": [
+    "auto",
+    "timesframe",
+    "astrotoo",
+    "pixoo64",
+    "timegate"
+  ],
+  "type": "string"
+}

removedInput schema / properties / target / properties / port / default
```
Removed value: -9000
```

changedInput schema / properties / target / properties / port / description

Previous value: -"Device HTTP port, commonly 9000."New value: +"Optional HTTP port override. Defaults to 80 for PIXOO64 90/92 and TimeGate 400, otherwise 9000."

removedInput schema / properties / useCurrentDisplayClock
```
Removed value: -{
-  "type": "boolean"
-}
```

First observedv0.1.6Jun 10, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries substantial behavioral burden and discloses server-injected ClockId handling, read-then-update/create logic, endpoint selection, and device-specific asset restrictions. Remaining gaps include explicit overwrite semantics, error behavior, and what the tool returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded, beginning with the core upsert behavior before moving into device-specific constraints. Most sentences earn their place, though the single-paragraph format could be structured more clearly for a complex 12-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main workflow and important TimesFrame/AstroToo constraints, but it is not fully complete for a 12-parameter tool with no output schema and only 33% schema description coverage. Several optional parameters and return behavior remain undocumented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low at 33%, so the description must compensate for many parameters. It adds useful meaning for dialAssetsPath, ItemList, ItemIdList, itemPatchList, and ClockId, but leaves setColorList, itemPatchByRoleList, deviceImageUrl, and preview image parameters unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Upsert the MCP-managed local watchface.' It clarifies the server-managed ClockId and update-vs-create behavior, making the operation distinct from a plain create/read tool, though it does not explicitly name sibling tools such as watchface_create_local_clock.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear operational guidance: field-only updates use POST /divoom_api, asset updates use multipart, ItemPatchList is preferred for existing rows, and AstroToo requires querying hardware/capabilities first. It does not explicitly compare itself to alternative siblings like watchface_create_local_clock or watchface_replace_dial_bg_file.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

watchface_patch_local

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools