RomanNum3ral
/
anthropic-skills
mirror of https://github.com/anthropics/skills.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge f6791a39eb into f6656c1256

This commit is contained in:
DivoomDevelop 2026-08-16 02:12:08 +08:00 committed by GitHub
parent f6656c1256 f6791a39eb
commit 11bc6396c0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 134 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.claude-plugin/marketplace.json
View File

@ -31,6 +31,7 @@
"./skills/brand-guidelines",
"./skills/canvas-design",
"./skills/doc-coauthoring",
"./skills/divoom-watchface-mcp",
"./skills/frontend-design",
"./skills/internal-comms",
"./skills/mcp-builder",

133
skills/divoom-watchface-mcp/SKILL.md Normal file
View File

@ -0,0 +1,133 @@
---
name: divoom-watchface-mcp
description: Operate Divoom LAN watchface devices via the mcp-divoom-lan MCP server—read/patch dial JSON, switch dials, brightness and screen on/off, multipart background upload, raw /divoom_api only when needed; always read before write and never create a dial unless the user asks.
---
# Divoom watchface MCP (LAN)
## Suggested listing title and blurb (for PRs, docs, or changelogs)
- **Title (reference):** `Add skill: Divoom LAN watchface via mcp-divoom-lan (read-before-write, npm published)`
- **Short description (reference):** Example skill that teaches Claude to drive **Divoom pixel devices on the local network** using the **`mcp-divoom-lan`** MCP server (stdio). Covers safe **read → patch → verify** flows, brightness/screen, dial selection, background multipart uploads, and **explicit-only** local dial creation—aligned with the published npm package and open-source server.
## When to use this skill
Use when the user wants to:
- Change the **current** watchface layout or item fields (text, font, color, positions, `ItemList` data).
- **Switch** which watchface/dial is active.
- **Read or set brightness**, or **turn the screen on/off**.
- **Replace** the dial background image (multipart upload to `/replace_clock_dial_bg`).
- **Upload** files via `/upload` when the product command requires it, or **create a new local dial**—**only if they clearly ask** to create one.
- Use **`watchface_protocol_quick_reference`** or fetch MCP **resources** for constraint reminders before complex edits.
**Do not** use this skill for devices that are not Divoom LAN API targets, or when no MCP server exposing these tool names is connected.
## Preconditions
1. **MCP server:** The client must run **`mcp-divoom-lan`** (stdio) so tools like `watchface_get_local` are available. The server nickname in config (e.g. `divoom-lan`) does not matter; use the tools as defined by that server.
2. **Network:** The host running the MCP client can reach the device (usually same LAN).
3. **Target device:** Either set env `DIVOOM_DEVICE_HOST` (optional `DIVOOM_DEVICE_PORT`, `DIVOOM_TIMEOUT_MS`) or pass `target.host` on each call.
4. **Unknown IP:** Ask the user for the device IP before issuing writes.
### Installing / running the server (end users)
| Source | How |
|--------|-----|
| **npm** | [npmjs.com/package/mcp-divoom-lan](https://www.npmjs.com/package/mcp-divoom-lan) — Node **≥ 20**. Example: `npx -y mcp-divoom-lan` with env `DIVOOM_DEVICE_HOST`, optional `DIVOOM_DEVICE_PORT` (default `9000`). |
| **Source** | [github.com/DivoomDevelop/mcp-divoom-lan](https://github.com/DivoomDevelop/mcp-divoom-lan) — `npm install`, `npm run build`, run `dist/index.js` via your client’s MCP config. |
### Optional visual editor (v2)
Humans can edit layouts in a browser UI; the model still uses MCP for device I/O.
- Repo: [github.com/DivoomDevelop/divoom-watchface-visual-editor_v2](https://github.com/DivoomDevelop/divoom-watchface-visual-editor_v2)
- Hosted: [divoomdevelop.github.io/divoom-watchface-visual-editor_v2/](https://divoomdevelop.github.io/divoom-watchface-visual-editor_v2/)
## Tools you can rely on (current server surface)
| Tool | Role |
|------|------|
| `watchface_get_local` | `Device/GetLocalClockInfo` — snapshot of current (or selected) dial; inspect `ItemList`. |
| `watchface_patch_local` | `Device/PatchLocalClockInfo` — apply patches; **server rejects if pre-read `ItemList` is empty**. Prefer `itemPatchList` / `itemPatchByRoleList` over replacing whole `itemList` when possible. |
| `watchface_get_fonts_local` | `Device/GetLocalFontList` |
| `watchface_get_store_market_list` | `Device/GetStoreClockMarketList` (after device has market data) |
| `watchface_set_clock_select` | `Channel/SetClockSelectId` — switch active dial by `clockId`. |
| `watchface_get_brightness` | `Sys/GetBrightness` |
| `watchface_set_brightness` | `Channel/SetBrightness` |
| `watchface_onoff_screen` | `Channel/OnOffScreen` — `onOff` 1 = on, 0 = off. |
| `watchface_replace_dial_bg_file` | Multipart `POST /replace_clock_dial_bg` — local `imagePath` (JPEG/WebP; **800×1280 recommended**). |
| `watchface_upload_file` | Multipart `POST /upload` — requires `filePath` + `metadata` JSON for the command. |
| `watchface_create_local_clock` | Multipart `POST /create_local_clock` — **explicit user intent only**; never as a “fallback” from failed patch. |
| `watchface_reset_local_then_cloud` | `Device/ResetLocalClockFromServer` — **destructive**; confirm with user first. |
| `watchface_raw_command` | Raw `POST /divoom_api` — last resort; must include `command`; **prefer named tools** when available. |
| `watchface_protocol_quick_reference` | Short operational constraints text for the session. |
### MCP resources (optional context)
If the client supports resources, you may read:
- `divoom://guide/quick-reference`
- `divoom://skill/watchface-customization`
## Multipart uploads (firmware packaging)
传输文件打包要求：固件在 `divoom_http_server_upload_get_file_info` 中要求每个文件段必须有 `Content-Length`，而浏览器 `FormData` 通常只使用 boundary 分隔、不包含每段 `Content-Length`。正在实现固件在无 `Content-Length` 时用 boundary 终止解析，并修复 JSON 段之后定位文件数据的指针计算；编辑器侧改为手动构造带 `Content-Length` 的 multipart 以提高兼容性。
For agents and human-maintained clients:
- **`mcp-divoom-lan` tools** that send multipart (`watchface_upload_file`, `watchface_replace_dial_bg_file`, `watchface_create_local_clock`, `watchface_patch_local` with dial assets) already assemble bodies with **per-part `Content-Length`**—prefer these over hand-rolled HTTP.
- **Browser / editor clients:** default `FormData` often omits per-part `Content-Length`; for strict compatibility with current firmware, **manually build** `multipart/form-data` with **`Content-Length` on each part** (JSON first, file second; CRLF and boundary rules as in the server docs). After firmware adds boundary-terminated parsing, tolerant clients may still prefer explicit lengths for reliability.
## Mandatory operating rules
1. **Use MCP tools only** for device actions—don’t simulate HTTP or fabricate JSON responses.
2. **Read before write (default loop):** `watchface_get_local` → inspect structure and indices → **`watchface_patch_local` (minimal change)** → `watchface_get_local` again to verify.
3. **Empty `ItemList`:** If the latest `GetLocalClockInfo` has **`ItemList` length 0**, **stop patching**. Tell the user to switch to an editable dial (`watchface_set_clock_select`), then re-read. The server also blocks `watchface_patch_local` in this state.
4. **No implicit dial creation:** Call `watchface_create_local_clock` **only** when the user explicitly wants a **new** local dial.
5. **Destructive ops:** `watchface_reset_local_then_cloud` (and similar) need **clear user confirmation** before running.
6. **Background / assets:** For replacing the dial background image, prefer **`watchface_replace_dial_bg_file`**. Use `watchface_upload_file` when the protocol requires a specific upload command + metadata.
7. **Relative brightness:** If the user says “increase/decrease by X%”, combine `watchface_get_brightness` with the device’s scale (often 0–100) and clamp sensibly.
8. **`watchface_raw_command`:** Use sparingly; validate `command` and minimal `payload`; prefer specialized tools to avoid mistakes.
## Task playbooks
### A. “Change color / font / position on what’s showing”
1. `watchface_get_local` (current dial).
2. Locate items in `ItemList` (indices / roles).
3. Build **`itemPatchList`** or **`itemPatchByRoleList`** for the smallest change.
4. `watchface_patch_local` → `watchface_get_local` to confirm.
### B. “Switch watchface / dial”
1. If you need an id, list or discover clocks (device/market tools as appropriate).
2. `watchface_set_clock_select` with `clockId`.
3. `watchface_get_local` to confirm context.
### C. Brightness or screen
1. `watchface_get_brightness` (if adjusting relatively).
2. `watchface_set_brightness` **or** `watchface_onoff_screen` as requested.
### D. Replace background image
1. Ensure image meets spec (JPEG/WebP, **800×1280** recommended).
2. `watchface_replace_dial_bg_file` with `imagePath` (and clock selector fields if not using current display).
### E. New local dial (explicit only)
1. Confirm user wants a **new** dial.
2. `watchface_create_local_clock` with `imagePath` + `metadata` (`ClockName`, `ItemList`, etc., per product docs).
## Response style
- Summarize the intended action, then call tools in order.
- After writes, echo **key results** (`ReturnCode`, `ClockId`, brightness, or what was patched).
- If blocked (network, empty `ItemList`, missing file, user declined reset), **state the blocker and the next user-visible step**.
## References
- MCP repository: [github.com/DivoomDevelop/mcp-divoom-lan](https://github.com/DivoomDevelop/mcp-divoom-lan)
- npm package: [npmjs.com/package/mcp-divoom-lan](https://www.npmjs.com/package/mcp-divoom-lan) — multipart packaging detail lives in package `resources/skill-quick-reference.md` from **v0.1.5** onward.
- Registry name (verification): `io.github.DivoomDevelop/mcp-divoom-lan` (see `package.json` → `mcpName`)