Metadata-Version: 2.4
Name: divoom-agent-mcp
Version: 0.1.0
Summary: MCP server exposing the divoom-agent semantic API as tools for LLMs (Claude, etc.)
Author: Orion Parrott
License: MIT
Keywords: divoom,mcp,claude,ai-tools,ambient-display
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: divoom-agent>=0.1
Requires-Dist: mcp>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# divoom-agent-mcp

MCP server that exposes the [`divoom-agent`](https://github.com/orionparrott/divoom-agent) semantic API as tools for LLMs. Lets Claude (or any MCP-aware tool-using model) drive a Divoom 16x16 LED panel as an ambient AI peripheral.

Top of the three-library stack:

```
divoom-protocol     ← bytes/BLE/encoder
divoom-agent        ← semantic ambient API
divoom-agent-mcp    ← THIS PACKAGE. MCP tools for LLM use.
```

## Install

```bash
pip install -e .[dev]
```

This installs the `divoom-agent-mcp` console script.

## Usage with Claude Code

Add to your Claude Code MCP config (`~/.claude/mcp.json` or via `claude mcp add`):

```json
{
  "mcpServers": {
    "divoom-agent": {
      "command": "divoom-agent-mcp",
      "env": {
        "DIVOOM_ADDRESS": ""
      }
    }
  }
}
```

Leave `DIVOOM_ADDRESS` empty to auto-scan for the nearest Divoom on startup, or set it to a specific device address (BLE MAC on Linux/Pi, or a CoreBluetooth UUID on macOS) to pin to a specific panel.

The server connects lazily on first tool invocation, so adding the MCP config doesn't immediately wake the panel.

## Tools exposed

| Tool | What it does |
|---|---|
| `set_status(state)` | Ambient state: `thinking` / `working` / `idle` / `success` / `error`. Loops until replaced. |
| `notify(kind)` | Discrete event: `shipped` / `celebrate` / `message`. |
| `set_alert(level)` | Severity ladder 1-3: yellow / orange / red flash. |
| `paint_pixels(grid)` | Custom 16x16 pixel art. Grid is a list of 16 rows × 16 cells × `[R,G,B]`. |
| `set_color(r, g, b, brightness)` | Solid Lighting color. |
| `set_brightness(value)` | 0-100. |
| `clear_panel()` | Black. |
| `show_clock()` | Built-in clock channel. |
| `start_mondrian(fps)` | Generative Mondrian cycle. |
| `stop_animation()` | Cancel any running animation. |

## Example LLM-driven sessions

Once configured, Claude can compose moves like:

> "Show that you're thinking about my question."
→ `set_status("thinking")` → blue breath on the panel

> "I just shipped a deploy — celebrate for a few seconds, then go back to idle."
→ `notify("celebrate")` → wait → `set_status("idle")`

> "Paint me a sunset on the panel."
→ `paint_pixels([... orange/red gradient ...])`

## Development

```bash
.venv/bin/pip install -e .[dev]
.venv/bin/pytest                    # currently no live-BLE tests
.venv/bin/divoom-agent-mcp          # run server interactively (uses stdio)
```

Test from another terminal with an MCP client (e.g. the official `mcp` CLI inspector) or just point Claude Code at it.

## License

MIT.
