Repository navigation
Releases
Releases · SDNick484/mcp-server-harmony
v0.4.0
Added
initializereports the package version asserverInfo.version(it was empty), so a bug report says which build answered.harmony_get_statuswith no hub configured adds ahintsaying how to add one, instead of an empty list alone.scripts/smoke_stdio.py: launches an installed server over stdio as an MCP client does and checks the first exchange. CI's newwheel-smokejob runs it against the built wheel on Linux, macOS and Windows; the release workflow runs it before publishing.- Issue templates: a bug report and a hardware report.
harmony_describe_activity(read-only): the devices an activity involves, with expected power (on/off/unknown) and input, and which device gets each button group. The expected state comes from each activity'sfixitin the hub's config (new assumptionH-FIXIT, medium); without one it saysunknown.mcp-server-harmony export: per hub, the raw config (account identifiers removed;--redactmasks addresses) and a Markdown worksheet for rebuilding the setup on another remote, both readable by the owner only. A record to rebuild from, not a backup.migrate_to_another_remote(target)prompt: describes every activity and writes a rebuild checklist for the named remote.harmony_set_sleep_timer(minutes, hub=None): turns a hub's TV system off after 1-720 minutes (0 cancels), replacing a timer already set. It runs the normal power off, so the busy guard, rate limit and dry run apply, and retries for five minutes if the hub is busy or unreachable. The hub going off first drops it; switching activities keeps it. Held in the server's memory only (it outlives the chat underserve --http, not over stdio).harmony_get_statusgives each hubsleep_timer(when it fires, minutes left, or null) andlast_sleep_timer(how the last one ended: fired, cancelled or failed, and why). Both are always present, null when empty.harmony_tune_channel: tune by pressing a channel's digits (702,5.1,5-1) through the running activity or a nameddevice, or by a favorite's name from the hub's newchannelsmap inconfig.json(shown inharmony://hubs/{hub}, kept bycheck). The digits go out as one sequence (HubClient.send_sequence): one busy check, one rate-limit charge refused whole, one dry-run report.enteradds the select button. New assumptionH-DIGITS.harmony_get_history(hub, limit, after_seq): a record of each hub's activity changes (when, from, to, how long the previous state lasted, and whether this server or something else such as the remote or app caused it), newest first or oldest first afterafter_seq, likesofabaton_get_recent_presses. The first state read after startup is arecording_startedmarker, not a change; a change found after a reconnect is markednoticed_late. Kept in memory and in a capped, owner-onlyhistory.jsonlin the config directory, names only, never addresses. Turn it off withHARMONY_HISTORY=offor"history": falseinconfig.json. New assumptionsH-ACTIVITY-PUSH(hardware-verified for starts from the remote) andH-OFF-PUSH. HARDWARE_VALIDATION step 10.
Fixed
doctor --dumpcould keep the Logitech account's e-mail address: a real config'sglobal.timeStampHashembeds it mid-string, where neither the key list nor log redaction caught it. The scrub now drops that key and any value with an address inside it.harmony_send_commandcould not tell the-and.buttons apart (both normalised to nothing, so the first one won). Exact names are now matched before the normalised match.doctor --dumpandexportkept four more identifiers that a real firmware 4.15.600 config carries:uuid,setupSession,hubIdandremoteId. They are now masked (test:test_scrub_masks_hub_and_setup_identifiers), and the first real captures from both hubs are intests/fixtures/recorded/.mcp-server-harmony callno longer addsrecording_startedmarkers to the activity history (every run appended one per hub).callnow only readshistory.jsonl, socall get_historystill shows what a server recorded;serverecords as before. A history file read while a server is mid-append, even cut inside a multi-byte character, no longer fails to load.harmony://hubsandharmony://hubs/{hub}wait out the same startup connection grace as tool calls when read right after the server starts.
Documentation
- Hardware run of HARDWARE_VALIDATION steps 10 to 13 on 2026-11-12 (two hubs, firmware 4.15.600):
H-FIXIT,H-DIGITS,H-OFF-PUSHandH-CONFIG-SHAPEare nowhardware-verified(scope and open items in each note);H-ACTIVITY-PUSHandH-RECONNECTgained notes. Untried: favorites, Bedroom channel entry, the remote's own button for history, the unplug test, the sleep timer's busy retry. - README: the status reflects the 2026-11-04 hardware run; a Claude Desktop config using
uvx; absolute links, so they work on PyPI.
v0.3.0
The v0.2.0 tag never reached PyPI (it pointed at a commit still versioned 0.1.0), so this release carries 0.2.0's changes too.
Breaking Changes
- Tool Namespacing: All MCP tools are now prefixed with
harmony_(harmony_get_status,harmony_list_activities,harmony_list_devices,harmony_list_commands,harmony_start_activity,harmony_power_off,harmony_send_command) to avoid naming collisions in MCP clients when run alongside sibling smart home servers. - CLI Shorthand: The
callCLI subcommand accepts both prefixed (harmony_get_status) and legacy/shorthand names (get_status,status).
Security
- Network Topology Masking: Internal hub LAN IPv4 addresses in
harmony_get_statuspayloads are sanitized withmask_ip(e.g.192.0.2.20->x.x.x.20) to prevent leaking local network topology to LLMs over stdout.
Documentation
HARDWARE_VALIDATION.mdstep 7: the Office Hub results forhold_ms(held presses acted as one tap on the LG TV and Onkyo).H-HOLDis unchanged inassumptions.pyuntil a configured hold action is checked.HARDWARE_VALIDATION.mdsteps 6, 8 and 9: results of the 2026-11-04 run on the Office and Bedroom hubs (presses, start/switch, multi-hub power off, the busy guard, config push, reconnect), with what each did not show.
Assumptions (hardware, 2026-11-04)
H-FORCE-OFFis nowhardware-contradicted: a forced power off sent during a start from the physical remote was refused by the hub ("Activity in progress").power_off(force=true)is unchanged; it still skips this server's own busy guard, but the hub can refuse it. README and CLAUDE.md say so. Whetherforcehelps a hub that is really stuck is untested.H-CONFIG-PUSHis nowhardware-verified: an activity renamed in the Harmony app showed up inharmony_list_activitieswith no restart.H-RECONNECTstayssimulator-only, with a note: a hub unplugged and replugged came backreachable: trueon its own, but the re-read of state after a reconnect wasn't exercised.
v0.1.0
First release of mcp-server-harmony: an MCP server that controls one or more Logitech Harmony Hubs over their local websocket API (no Logitech cloud, no Home Assistant), built on aioharmony.
What's in it
- Tools:
get_status,list_activities,list_devices,list_commands,start_activity,power_off,send_command - Resources:
harmony://hubsand a per-hub catalog; prompt:fix_stuck_remote - Activity-first:
send_commandwithout a device goes through the running activity - Multiple hubs, never guessed: ambiguous calls are refused with the hub names; hub-qualified refs like
Den/Watch TV - Safety: the hub's config is the allow-list; commands refused mid-sequence; per-hub rate limits; dry-run mode
- CLI:
serve(stdio or--http),check,call,discover,doctor,simulate(wire-level fake hubs) - Deploy: Alpine/OpenRC service for an LXC
Verification status
Hardware-verified on real hubs (2026-10-14): H-FRAMES, H-NAME, H-PORT, H-POWEROFF, H-PROVISION (connect, status, names, power off).
Simulator-only so far: H-CONFIG-PUSH, H-CONFIG-SHAPE, H-HOLD, H-PRESS-ERROR, H-PRESS-SILENT, H-RECONNECT, H-SSDP, H-START-SEQUENCE, H-TIMING (activity starts, button presses, reconnects, config pushes). See HARDWARE_VALIDATION.md.
Tested on Python 3.11–3.14.