{
  "markdown": "# mcp-divoom-lan\n\n`mcp-divoom-lan` is an open-source MCP server that wraps Divoom watchface LAN APIs as standard tools for AI clients.\n\nIt works together with the **v2** HTML visual editor for modifying watchfaces, switching faces, adjusting brightness, and creating new local watchfaces.\n\n**v2 visual editor (public):**\n\n- GitHub: `https://github.com/DivoomDevelop/divoom-watchface-visual-editor_v2`\n- Live site: `https://divoomdevelop.github.io/divoom-watchface-visual-editor_v2/`\n\nYour local clone path (e.g. `D:\\divoom-watchface-visual-editor`) is machine-specific; **use the v2 GitHub / GitHub Pages URLs above in docs and MCP metadata.**\n\n## Goals\n\n- Expose key capabilities from `Divoom_Watchface_Remote_Customization_Guide_EN.md` as MCP tools\n- Let MCP-enabled clients (Cursor, Claude Desktop, local LLMs, etc.) drive watchface actions via natural language\n- Preserve safety boundaries (read before write, explicit warnings for risky operations, multipart rules)\n\n## Default safety policy (important)\n\n- **Read before write:** call `watchface_get_local`, then `watchface_patch_local`, then read back to verify.\n- If `GetLocalClockInfo` returns an **empty `ItemList`:** stop writes; switch to an editable watchface first.\n- Do **not** call `watchface_create_local_clock` unless the user clearly asks to create a new one (no implicit creation).\n\n## Implemented tools\n\n- `watchface_get_local` → `Device/GetLocalClockInfo`\n- `watchface_patch_local` → `Device/PatchLocalClockInfo` (default `/divoom_api`); optional `dialAssetsPath` switches to multipart `POST /patch_local_clock` (same dial/tar.gz rules as `watchface_create_local_clock`)\n- `watchface_get_fonts_local` → `Device/GetLocalFontList`\n- `watchface_get_store_market_list` → `Device/GetStoreClockMarketList`\n- `watchface_set_clock_select` → `Channel/SetClockSelectId`\n- `watchface_get_brightness` → `Sys/GetBrightness`\n- `watchface_set_brightness` → `Channel/SetBrightness`\n- `watchface_onoff_screen` → `Channel/OnOffScreen` (1=on, 0=off)\n- `watchface_replace_dial_bg_file` → `POST /replace_clock_dial_bg`\n- `watchface_upload_file` → `POST /upload`\n- `watchface_create_local_clock` → `POST /create_local_clock` (multipart: single dial image **or** `tar.gz`; JSON `DialAssets`/`UseDialAssetBundle` selects mode, default auto-detect gzip)\n- `watchface_reset_local_then_cloud` → `Device/ResetLocalClockFromServer`\n- `watchface_get_screen_snapshot` → `Device/GetScreenSnapshot` (wait 2s, then GET `/userdata/snapshot.webp` for visual diff)\n- `watchface_raw_command` → generic `POST /divoom_api`\n- `watchface_protocol_quick_reference` → key protocol constraints for the model\n\n## Resources (context for the model)\n\nThe server exposes two MCP resources:\n\n- `divoom://guide/quick-reference`\n- `divoom://skill/watchface-customization`\n\n## MCP Bundle (.mcpb)\n\nFor [MCPB](https://github.com/anthropics/mcpb)-compatible hosts (e.g. Claude desktop connectors, Smithery stdio releases), build a local bundle:\n\n1. Install the packer: `npm install -g @anthropic-ai/mcpb`\n2. From this package root: `npm run mcpb:pack`\n3. Output: `mcp-divoom-lan.mcpb` (gitignored). The staging directory `mcpb/staging/` is also gitignored.\n\nThe bundle includes `dist/`, `resources/`, production `node_modules`, and a `manifest.json` with user fields for **device IP**, **port**, and **timeout**.\n\n## Quick start\n\n```bash\ncd tools/mcp-divoom-lan  # or your clone root for this package\nnpm install\nnpm run build\nnpm start\n```\n\nDevelopment (watch rebuild):\n\n```bash\nnpm run dev\n```\n\nPre-release check (typecheck, build, pack dry-run):\n\n```bash\nnpm run release:check\n```\n\n## Documentation\n\n- `docs/README.md` — documentation index\n- `docs/quick-start.md` — minimal setup\n- `docs/tool-examples.md` — tool usage examples (includes §5b analog pointer layout)\n- `docs/disp-usage.md` — choosing `disp` ids (pointer layout `131/132/233`; net-gallery uniqueness `13/125–130/173–175`)\n- `docs/html-visual-editor.md` — using the visual editor with MCP\n- `docs/safety-and-troubleshooting.md` — safety and FAQs\n- `docs/reference/` — condensed protocol rules (EN/ZH)\n- `docs/examples/` — sample requests/responses and catalog\n\n## Environment variables\n\n- `DIVOOM_DEVICE_HOST` — device LAN IP (e.g. `192.168.1.120`)\n- `DIVOOM_DEVICE_PORT` — HTTP port, default `9000`\n- `DIVOOM_TIMEOUT_MS` — request timeout ms, default `45000`\n\nIf `DIVOOM_DEVICE_HOST` is unset, each tool call must pass `target.host`.\n\n## Example client config (stdio)\n\n### Cursor / Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"divoom-lan\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/ABSOLUTE/PATH/to/tools/mcp-divoom-lan/dist/index.js\"\n      ],\n      \"env\": {\n        \"DIVOOM_DEVICE_HOST\": \"192.168.1.120\",\n        \"DIVOOM_DEVICE_PORT\": \"9000\",\n        \"DIVOOM_TIMEOUT_MS\": \"45000\"\n      }\n    }\n  }\n}\n```\n\nYou can also copy `client-config.example.json` in this directory as a starting point.\n\n## Publishing checklist (for maintainers)\n\n1. Use a dedicated repo (e.g. `mcp-divoom-lan`) with this package at the repo root.\n2. Verify metadata: `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `RELEASE.md` as applicable.\n3. Run `npm run release:check`.\n4. Tag a GitHub release (e.g. `v0.1.2`) with screenshots and sample requests if helpful.\n5. Submit listings where appropriate (MCP Registry, Smithery, Glama, [MCP.so](https://mcp.so/submit), community indexes). For Glama, follow `GLAMA_SUBMISSION_READY.md` (includes `Dockerfile` and `glama.json`). For MCP.so, follow `MCP_SO_SUBMISSION_READY.md`. For 火山引擎 MCP 清单，见 `VOLCENGINE_SUBMISSION_READY.md`（PR: https://github.com/volcengine/mcp-server/pull/398）。For **阿里云百炼**自定义 MCP（控制台 npx 部署），见 `BAILIAN_MCP_SUBMISSION_READY.md`。For **扣子 Coze** 插件发布/商店（HTTP 插件，与 MCP 不同），见 `COZE_SUBMISSION_READY.md`。\n6. Minimal demo flow: `watchface_get_local` → `watchface_patch_local` (font size/color) → `watchface_replace_dial_bg_file` (background).\n\n## Files often used at release\n\nIncluded in this repo (when present): `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `RELEASE.md`, optional checklist and directory templates, and `.github/workflows/ci.yml`.\n\n## Should the HTML visual editor ship inside this npm package?\n\n**Recommendation:** **no** for the core MCP package — keep MCP lean. Offer the editor as a **separate optional** project.\n\n- **Core:** `https://github.com/DivoomDevelop/mcp-divoom-lan`\n- **Visual editor v2:** `https://github.com/DivoomDevelop/divoom-watchface-visual-editor_v2`\n- **Hosted v2:** `https://divoomdevelop.github.io/divoom-watchface-visual-editor_v2/`\n\nBenefits:\n\n- Small MCP install suitable for all AI clients  \n- Non-developers can use the visual UI to understand `ItemList`, then let the AI apply patches  \n- Clear split between WYSIWYG editing and automated MCP writes\n\n## Alignment with upstream docs\n\nThis repo ships standalone docs under `docs/`, `docs/reference/`, and `docs/examples/`. If you maintain full guides elsewhere, keep this tree synced or treat it as the distribution subset.\n",
  "bytes": 6986,
  "sha": "d87c2d665f8394fb9e954e786c50c7e56bc3d4899d09622b4ef1695f9957060f",
  "repo_slug": "divoomdevelop/mcp-divoom-lan",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_divoomdevelop_mcp_divoom_lan_9dd6db99/readme"
}