Metadata-Version: 2.5
Name: myrohome-helper-mcp
Version: 0.3.2
Summary: MCP server that lets an AI assistant read and control an HAI/Leviton Omni controller through Myro:Home Helper
Project-URL: Homepage, https://www.myrocontrol.com
Project-URL: Repository, https://gitlab.com/MyroControl/myrohome-helper-mcp
Author: Myro Control, LLC
License: MIT
License-File: LICENSE
Keywords: hai,home-automation,leviton,mcp,myrohome,omni
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.0
Requires-Dist: mcp<2,>=1.2
Description-Content-Type: text/markdown

# Myro:Home Helper MCP server

Lets an AI assistant (Claude Desktop, Claude Code, ChatGPT desktop, anything
that speaks [MCP](https://modelcontextprotocol.io)) read and control an
HAI/Leviton Omni controller through **Myro:Home Helper**, using the Helper's
HTTP API. The assistant sees typed tools with descriptions instead of guessing
URL shapes.

## What you need

- Myro:Home Helper 4.06 or later on a Mac on your network (4.07 or later for
  the read tools: `list_objects`, `get_object`, `helper_log`).
- An API key for your controller: Helper → **API** tab → Generate.
- [`uv`](https://docs.astral.sh/uv/) on the machine running the assistant
  (`brew install uv` or the one-line installer). `uvx` fetches and runs this
  server on demand and keeps it updated.

## Configure

Claude Desktop (`claude_desktop_config.json`) or any client that takes the
standard MCP config:

```json
{
  "mcpServers": {
    "myrohome-helper": {
      "command": "uvx",
      "args": ["myrohome-helper-mcp"],
      "env": {
        "MHH_URL": "http://192.168.1.76:9393",
        "MHH_API_KEY": "your-api-key"
      }
    }
  }
}
```

Claude Code:

```
claude mcp add myrohome-helper -e MHH_URL=http://192.168.1.76:9393 -e MHH_API_KEY=your-api-key -- uvx myrohome-helper-mcp
```

The controller ID is fetched from the Helper automatically. Set
`MHH_CONTROLLER_ID` only if you want to pin it.

## Tools

Read:

| Tool | What it returns |
|---|---|
| `helper_info` | Helper version and identity, and which controller the key is for |
| `controller_status` | Name, model, firmware, connection, power, battery, phone line, energy cost, troubles |
| `controller_property(name)` | One controller property |
| `list_objects(type?)` | Every object with decoded state; filter by Zone, Unit, Flag, Output, Thermostat, Auxiliary Sensor, … |
| `get_object(type, number)` | One object |
| `helper_log(lines)` | The Helper's recent log lines |
| `ethernet_quality` | The controller connection's health record |
| `list_logged_sensors` | Which sensors record history, with the type and number |
| `sensor_history(type, number, points)` | Logged readings for one sensor or thermostat |

Write (each changes the physical home; tool descriptions tell the assistant to confirm first):

| Tool | Effect |
|---|---|
| `set_unit(number, value)` | 0 off, 1 or 100 on, 2–99 dimmer level |
| `set_flag(number, value)` | Flag to 0–255 |
| `set_output(number, on)` | Output relay on or off |
| `set_energy_cost(level)` | low / medium / high / critical |
| `send_notification(message)` | Push to the Myro:Home apps |
| `speak(message)` | Speak on the Mac |
| `log_message(message)` | Write to the Helper log |
| `sync_now` | Re-sync from the controller |

Scripts (save, enable and reload need a key with **remote script management** enabled;
listing, reading and validating do not):

| Tool | What it does |
|---|---|
| `list_scripts` | Every script: name, id, enabled, schedule |
| `get_script(identifier)` | One script's full source |
| `scripting_reference(compact)` | The live scripting API, with your real device names |
| `validate_script(code)` | Syntax and warnings, without running it |
| `save_script(name, code, script_id, enabled)` | Create or replace; disabled by default |
| `set_script_enabled(identifier, enabled)` | Enabling runs the script immediately |
| `reload_scripts` | Re-runs every enabled script |

Audio, Lutron and displays:

| Tool | What it does |
|---|---|
| `list_audio_sources` | Sources and their cached metadata |
| `audio_source_metadata(source, refresh)` | What one source is playing |
| `set_audio_zone(zone, power, volume, mute, source)` | Control a zone |
| `list_lutron` | Bridges, devices and Picos |
| `set_lutron_level(bridge_id, level, ...)` | Set a Lutron device 0-100 |
| `activate_lutron_scene(bridge_id, scene_href)` | Activate a scene |
| `press_lutron_button(bridge_id, integration_id, component)` | Press a keypad or Pico button |
| `list_displays` | Vestaboards and LaMetric clocks |
| `send_to_vestaboard(text | lines | characters, ...)` | Show text on a Vestaboard: auto-fit, per-row, or a raw code grid |
| `send_to_lametric(text, ...)` | Show a notification on a LaMetric |
| `sync_clock` | Set the controller's clock from this Mac |

Security (all four need an API key with arm/disarm enabled **and** a panel code stored locally):

| Tool | Effect |
|---|---|
| `arm(mode, area)` | day, night, away, vacation, day_instant, night_delayed |
| `disarm(area)` | Disarms the system |
| `bypass_zone(zone, bypassed, area)` | Bypass or restore one zone |
| `restore_all_zones(area)` | Restore every bypassed zone |

Security tools stay disabled until the owner stores a panel code on the machine
running this server:

```
uvx myrohome-helper-mcp security-code set      # prompts; nothing is echoed
uvx myrohome-helper-mcp security-code delete
```

The code goes into the operating system credential store (macOS Keychain,
Windows Credential Locker, Linux Secret Service) under the controller's
identity. It is never placed in the MCP config, an environment variable, or a
conversation, and it is read only when a security tool is actually called.
Helper validates it against the panel itself.

## Security

This server runs on your LAN like every other Myro:Home client and holds one
controller's API key. Anyone who can run the assistant with this config can do
what the key allows. Keep it on trusted machines. The Helper's HTTP API is
plain HTTP on the local network; do not expose port 9393 to the internet.

## Developing

```
uv sync
MHH_URL=http://192.168.1.76:9393 MHH_API_KEY=... uv run myrohome-helper-mcp   # stdio server
uv run mcp dev src/myrohome_helper_mcp/server.py                             # MCP inspector
```

## Releasing

Bump `version` in `pyproject.toml` and `__init__.py`, commit, then tag and
push: `git tag v0.1.0 && git push origin v0.1.0`. The GitLab CI job builds
and publishes to PyPI through trusted publishing (one-time setup: PyPI
project -> Publishing -> add GitLab publisher `MyroControl/myrohome-helper-mcp`,
environment `pypi`).

MIT licensed. Myro Control, LLC.
