mcp-server-harmony 0.1.0__py3-none-any.whl

harmony_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for the Logitech Harmony Hub."""
+
+__version__ = "0.1.0"

harmony_mcp/assumptions.py

@@ -0,0 +1,157 @@
+"""Every protocol detail this server relies on that hasn't been checked on a real hub.
+
+Why a registry instead of comments: a comment saying "unverified" is easy to
+miss and never goes away. Here each assumption has an id that:
+  - code cites next to where it depends on it (``# ASSUMPTION H-PROVISION``),
+  - a test cites to document it (tests/test_assumptions.py, test_contract.py),
+  - HARDWARE_VALIDATION.md cites in the step that confirms it,
+  - `mcp-server-harmony doctor` prints, with its status.
+
+tests/test_assumptions.py fails if an id is missing from the README or
+HARDWARE_VALIDATION.md, so the three can't drift apart.
+
+To record a hardware result, change ``status`` to "hardware-verified" (or
+"hardware-contradicted", with what you saw in ``note``) and commit it.
+
+Confidence is about the *claim*, judged from its source:
+  high   - the library we run (aioharmony, used by Home Assistant) depends on it
+  medium - inferred from another project's code or docs, not from aioharmony itself
+  low    - our own guess; the simulator implements it but nothing confirms it
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Confidence = Literal["high", "medium", "low"]
+Status = Literal["simulator-only", "hardware-verified", "hardware-contradicted"]
+
+
+@dataclass(frozen=True)
+class Assumption:
+    id: str
+    claim: str
+    source: str
+    confidence: Confidence
+    status: Status = "simulator-only"
+    note: str = ""
+
+
+# Hardware runs, cited by the notes below.
+_HW_2026_10_14 = "2026-10-14, two real hubs (Harmony Hub, Office Hub, firmware 4.15.600) via the service on LXC210"
+
+ASSUMPTIONS: tuple[Assumption, ...] = (
+    Assumption(
+        "H-PORT",
+        "The hub's local API is HTTP and websocket on TCP 8088.",
+        "aioharmony const.DEFAULT_WS_HUB_PORT, used for every request",
+        "high",
+        status="hardware-verified",
+        note=_HW_2026_10_14 + ": both hubs connected on 8088.",
+    ),
+    Assumption(
+        "H-PROVISION",
+        "POST http://<hub>:8088/ with cmd 'setup.account?getProvisionInfo' returns data.activeRemoteId, "
+        "which the websocket URL needs as hubId.",
+        "aioharmony hubconnector_websocket._retrieve_hub_info; Home Assistant validates hubs the same way",
+        "high",
+        status="hardware-verified",
+        note=_HW_2026_10_14 + ": both websockets opened, which needs the provisioned hubId.",
+    ),
+    Assumption(
+        "H-FRAMES",
+        "Requests are {hubId, timeout, hbus:{cmd, id, params}}; replies are {cmd, code, id, msg, data} and are "
+        "matched to requests by id.",
+        "aioharmony hub_send and responsehandler",
+        "high",
+        status="hardware-verified",
+        note=_HW_2026_10_14 + ": get_status and power_off got their replies.",
+    ),
+    Assumption(
+        "H-CONFIG-SHAPE",
+        "The config has activity[] and device[] with string ids, controlGroup[].function[], and each "
+        "function's action is a JSON *string* holding command and deviceId.",
+        "aioharmony json_config and _get_config",
+        "high",
+        note="Partial, " + _HW_2026_10_14 + ": the running activity's id (32845636) resolved to its name "
+        "through the parsed config. Devices and commands not exercised yet.",
+    ),
+    Assumption(
+        "H-POWEROFF",
+        "Activity -1 is the built-in PowerOff; starting it turns everything off.",
+        "aioharmony power_off() is start_activity(-1)",
+        "high",
+        status="hardware-verified",
+        note=_HW_2026_10_14 + ": power_off on Office Hub sent runactivity -1; the hub went off, and the LG "
+        "Office TV dropped to standby (confirmed independently by mcp-server-webos).",
+    ),
+    Assumption(
+        "H-NAME",
+        "'connect.discoveryinfo?get' returns the hub's friendlyName (the name set in the Harmony app).",
+        "aioharmony HarmonyClient.name",
+        "high",
+        status="hardware-verified",
+        note=_HW_2026_10_14 + ": the hubs reported 'Harmony Hub' and 'Office Hub'.",
+    ),
+    Assumption(
+        "H-START-SEQUENCE",
+        "Starting an activity: the hub acks runactivity, sends stateDigest notify (activityStatus 1, or 0 for "
+        "power off), startActivity code 100 progress frames, startActivity code 200 when done, then "
+        "startActivityFinished.",
+        "aioharmony's start_activity handlers; the fake hub's exact order and timing are hand-built",
+        "medium",
+    ),
+    Assumption(
+        "H-PRESS-SILENT",
+        "holdAction press/release gets no reply on success, only on failure.",
+        "aioharmony send_commands comment ('the HUB sends a message back if there is an issue')",
+        "medium",
+    ),
+    Assumption(
+        "H-PRESS-ERROR",
+        "A rejected press is answered with a non-200 code and a msg. The fake hub uses code 417 with "
+        "'Unknown command'; the real code and text are unknown.",
+        "none: the fake hub's choice",
+        "low",
+    ),
+    Assumption(
+        "H-HOLD",
+        "hold_ms keeps the button 'pressed' between the press and release frames; whether the hub repeats the "
+        "IR code while held (like a held physical button) is unknown.",
+        "aioharmony SendCommandDevice.delay (press, sleep, release)",
+        "low",
+    ),
+    Assumption(
+        "H-CONFIG-PUSH",
+        "Editing the hub in the Harmony app makes it push stateDigest notify with a new configVersion "
+        "(syncStatus not 1); aioharmony then refetches the config.",
+        "aioharmony _notification_callback",
+        "medium",
+    ),
+    Assumption(
+        "H-RECONNECT",
+        "After the websocket drops, aioharmony reconnects by itself (first retry after 1 s, backing off to 30 s) "
+        "and calls the disconnect and connect callbacks.",
+        "aioharmony hubconnector_websocket._reconnect",
+        "high",
+    ),
+    Assumption(
+        "H-SSDP",
+        "Hubs answer an SSDP M-SEARCH for ST urn:myharmony-com:device:harmony:1, with LOCATION on the hub's address.",
+        "Home Assistant's harmony manifest matches that deviceType; HA may learn it from NOTIFY, not M-SEARCH",
+        "medium",
+    ),
+    Assumption(
+        "H-TIMING",
+        "An activity start or power-off finishes within 60 s.",
+        "none: our timeout, picked to cover slow TVs",
+        "low",
+    ),
+)
+
+BY_ID = {a.id: a for a in ASSUMPTIONS}
+
+
+def unverified() -> list[Assumption]:
+    return [a for a in ASSUMPTIONS if a.status != "hardware-verified"]

harmony_mcp/catalog.py

@@ -0,0 +1,181 @@
+"""The hub's own configuration, turned into the names the model may use.
+
+A Harmony hub already holds a closed world: the activities you set up, the
+devices in them, and every command each device knows (the IR codes live on the
+hub; we only ever send a command *name*). That makes the hub's config the
+allow-list. The model can only start an activity, or send a command, that
+appears here; there is no way to send a raw IR code or an unknown device id.
+
+This module is pure data shaping (no I/O), so it is tested directly against a
+config captured in the same shape the hub returns.
+
+The raw config (``HarmonyAPI.config``) looks like this, trimmed::
+
+    {
+      "activity": [
+        {"id": "-1", "label": "PowerOff", "controlGroup": []},
+        {"id": "38123456", "label": "Watch Shield",
+         "controlGroup": [
+           {"name": "Volume", "function": [
+             {"name": "VolumeUp", "label": "Volume Up",
+              "action": "{\\"command\\":\\"VolumeUp\\",\\"type\\":\\"IRCommand\\",\\"deviceId\\":\\"71234567\\"}"}
+           ]}
+         ]}
+      ],
+      "device": [
+        {"id": "71234567", "label": "Onkyo AV Receiver", "manufacturer": "Onkyo",
+         "model": "TX-NR7100", "controlGroup": [...same shape as above...]}
+      ]
+    }
+
+Two quirks worth knowing: ids are *strings* in the config but *ints* everywhere
+in aioharmony's API, and each function's ``action`` is itself a JSON string.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+# Harmony's built-in "everything off" pseudo-activity. It is in the config's
+# activity list, but it is not something the user set up, so it is reported as
+# power "off" rather than listed as an activity.
+POWER_OFF_ID = -1
+
+
+@dataclass(frozen=True)
+class Command:
+    """One button the hub knows how to send.
+
+    name      - the hub's canonical name, e.g. "VolumeUp". This is what is sent.
+    label     - the human label, e.g. "Volume Up". Accepted as input too.
+    device_id - the device that receives it. For an activity's commands this is
+                whichever device the activity routes that button to (volume to
+                the receiver, play/pause to the Shield, ...).
+    group     - the hub's control group, e.g. "Volume", "TransportBasic".
+    """
+
+    name: str
+    label: str
+    device_id: int
+    group: str
+
+
+@dataclass(frozen=True)
+class Device:
+    device_id: int
+    name: str
+    manufacturer: str
+    model: str
+    commands: tuple[Command, ...] = field(default=(), repr=False)
+
+
+@dataclass(frozen=True)
+class Activity:
+    activity_id: int
+    name: str
+    commands: tuple[Command, ...] = field(default=(), repr=False)
+
+
+def norm(name: str) -> str:
+    """Matching key: case-, space-, dash- and underscore-insensitive.
+
+    The model may say "volume up", "Volume Up", "VolumeUp" or "volume_up";
+    all of them should find the hub's "VolumeUp".
+    """
+    return "".join(ch for ch in name.lower() if ch.isalnum())
+
+
+def _parse_commands(control_groups: Any) -> tuple[Command, ...]:
+    out: list[Command] = []
+    for group in control_groups or []:
+        if not isinstance(group, dict):
+            continue
+        group_name = str(group.get("name", ""))
+        for fn in group.get("function", []) or []:
+            if not isinstance(fn, dict):
+                continue
+            try:
+                action = json.loads(fn.get("action") or "")
+                cmd = Command(
+                    name=str(action["command"]),
+                    label=str(fn.get("label") or fn.get("name") or action["command"]),
+                    device_id=int(action["deviceId"]),
+                    group=group_name,
+                )
+            except (ValueError, KeyError, TypeError):
+                # A function we can't parse is simply not offered to the model.
+                log.debug("Skipping unparseable function %r", fn)
+                continue
+            out.append(cmd)
+    return tuple(out)
+
+
+def _find(commands: tuple[Command, ...], wanted: str) -> Command | None:
+    key = norm(wanted)
+    for c in commands:
+        if norm(c.name) == key or norm(c.label) == key:
+            return c
+    return None
+
+
+@dataclass(frozen=True)
+class Catalog:
+    """Everything the hub's config says the model is allowed to touch."""
+
+    activities: tuple[Activity, ...] = ()
+    devices: tuple[Device, ...] = ()
+
+    @classmethod
+    def from_config(cls, config: dict[str, Any] | None) -> Catalog:
+        if not config:
+            return cls()
+        activities = []
+        for a in config.get("activity", []) or []:
+            try:
+                aid = int(a["id"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            if aid == POWER_OFF_ID:
+                continue
+            activities.append(Activity(aid, str(a.get("label", aid)), _parse_commands(a.get("controlGroup"))))
+        devices = []
+        for d in config.get("device", []) or []:
+            try:
+                did = int(d["id"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            devices.append(
+                Device(
+                    did,
+                    str(d.get("label", did)),
+                    str(d.get("manufacturer", "")),
+                    str(d.get("model", "")),
+                    _parse_commands(d.get("controlGroup")),
+                )
+            )
+        return cls(tuple(activities), tuple(devices))
+
+    # --- lookups by what the model typed ----------------------------------
+    def activity(self, name: str) -> Activity | None:
+        key = norm(name)
+        return next((a for a in self.activities if norm(a.name) == key), None)
+
+    def activity_by_id(self, activity_id: int | None) -> Activity | None:
+        return next((a for a in self.activities if a.activity_id == activity_id), None)
+
+    def device(self, name: str) -> Device | None:
+        key = norm(name)
+        return next((d for d in self.devices if norm(d.name) == key), None)
+
+    def device_name(self, device_id: int) -> str:
+        d = next((d for d in self.devices if d.device_id == device_id), None)
+        return d.name if d else str(device_id)
+
+    @staticmethod
+    def find_command(commands: tuple[Command, ...], name: str) -> Command | None:
+        return _find(commands, name)

harmony_mcp/cli.py

@@ -0,0 +1,302 @@
+"""Entry point: `mcp-server-harmony [serve|check|call|discover|doctor|simulate]`.
+
+serve      speak MCP: stdio by default (the client launches it), or --http for
+           a long-lived service behind Cloudflare Access (remote.py). --dry-run
+           reads the hubs but sends nothing that changes anything.
+check      first contact with one hub (--host) or every configured one: list
+           what it has and save it, with its own name, to config.json.
+call       call one tool exactly as the model would (through an in-process MCP
+           client, so arguments are validated the same way) and print the
+           result: `call start_activity activity="Den/Watch TV"`; `call tools`.
+discover   look for hubs with SSDP (discovery.py); `check --discover` adds them.
+doctor     check each hub layer by layer and say what failed (doctor.py);
+           --dump writes redacted fixtures from your real hubs.
+simulate   run wire-level fake hubs (sim/fake_hub.py) on 127.0.0.1 and
+           127.0.0.2, so everything above works without hardware.
+
+There is no pairing step: a Harmony hub answers anyone on the LAN.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+from aioharmony.exceptions import HarmonyException
+from aioharmony.harmonyapi import HarmonyAPI
+
+from . import __version__, remote
+from .catalog import Catalog
+from .config import Protocol, config_dir, load_settings, save_hub
+from .logsafe import setup_logging
+
+
+def _setup_logging(args: argparse.Namespace, default: int = logging.INFO) -> None:
+    verbose = getattr(args, "verbose", 0)
+    level = logging.DEBUG if verbose else default
+    unredacted = getattr(args, "no_redact", False) or os.environ.get("HARMONY_LOG_UNREDACTED") in ("1", "true")
+    setup_logging(level, redacted=not unredacted)
+
+
+# --- check ------------------------------------------------------------------------------
+async def _check_one(host: str, protocol: Protocol | None) -> bool:
+    api = HarmonyAPI(ip_address=host, protocol=protocol)
+    try:
+        if not await api.connect():
+            print(f"Couldn't connect to a Harmony hub at {host} (TCP 8088). Try `doctor`.", file=sys.stderr)
+            return False
+    except (HarmonyException, OSError) as exc:
+        print(f"Couldn't connect to {host}: {exc}. Try `doctor`.", file=sys.stderr)
+        return False
+    try:
+        # aioharmony reports the IP as the name when the hub didn't send one.
+        name = api.name if api.name and api.name != host else None
+        catalog = Catalog.from_config(api.config)
+        current = catalog.activity_by_id(api.current_activity[0])
+        print(f"{name or host} (firmware {api.fw_version}, {api.protocol}) at {host}")
+        print(f"  Running: {current.name if current else 'nothing (off)'}")
+        print("  Activities:")
+        for a in catalog.activities:
+            print(f"    {a.name}  ({len(a.commands)} commands)")
+        print("  Devices:")
+        for d in catalog.devices:
+            print(f"    {d.name}  [{d.manufacturer} {d.model}]  ({len(d.commands)} commands)")
+    finally:
+        await api.close()
+    path = save_hub(host, name)
+    print(f"  Saved to {path}")
+    return True
+
+
+async def _cmd_check(host: str | None, discover_first: bool = False) -> int:
+    settings = load_settings()
+    for p in settings.problems:
+        print(f"Config: {p}", file=sys.stderr)
+    if discover_first:
+        from .discovery import discover
+
+        hosts = [h.host for h in await discover()]
+        if not hosts:
+            print("SSDP found no hubs; use --host <ip> (see `discover --help`).", file=sys.stderr)
+            return 1
+    else:
+        hosts = [host] if host else [h.host for h in settings.hubs]
+    if not hosts:
+        print("No hubs configured. Run: mcp-server-harmony check --host <ip>  (once per hub)", file=sys.stderr)
+        return 2
+    if settings.port is not None:
+        import aioharmony.hubconnector_websocket as ws_connector
+
+        ws_connector.DEFAULT_HUB_PORT = settings.port
+    results = [await _check_one(h, settings.protocol) for h in hosts]
+    return 0 if all(results) else 1
+
+
+# --- discover -----------------------------------------------------------------------------
+async def _cmd_discover(timeout: float, st: str, raw: bool) -> int:
+    from .discovery import discover
+
+    print(f"Searching for {st} ({timeout:.0f}s)...")
+    hits = await discover(timeout=timeout, st=st)
+    for hit in hits:
+        print(f"  {hit.host:<16} {hit.server or ''}  {hit.location or ''}")
+        if raw:
+            print("    " + hit.raw.strip().replace("\n", "\n    "))
+    if not hits:
+        print(
+            "Nothing answered. SSDP is multicast: it doesn't cross VLANs or guest networks, and on WSL2 needs "
+            "mirrored networking. `check --host <ip>` always works. (Unverified on a real hub: ASSUMPTION H-SSDP.)"
+        )
+        return 1
+    print("Add them with: mcp-server-harmony check --discover")
+    return 0
+
+
+# --- doctor -------------------------------------------------------------------------------
+async def _cmd_doctor(args: argparse.Namespace) -> int:
+    from dataclasses import replace
+
+    from .config import HubSettings
+    from .doctor import render, run_doctor, to_json
+
+    settings = load_settings()
+    if args.host:
+        settings = replace(settings, hubs=(HubSettings(args.host),))
+    report = await run_doctor(settings, timeout=args.timeout, dump_dir=Path(args.dump) if args.dump else None)
+    print(to_json(report) if args.json else render(report))
+    return 0 if report.ok else 1
+
+
+# --- simulate -----------------------------------------------------------------------------
+SIM_HUBS = (("living_room", "Living Room", "127.0.0.1", 12345678), ("den", "Den", "127.0.0.2", 87654321))
+
+
+async def _cmd_simulate(args: argparse.Namespace, ready: asyncio.Event | None = None) -> int:
+    from .sim.fake_hub import FakeHub, load_fixture
+
+    fakes = [
+        FakeHub(load_fixture(fixture), name=name, host=host, port=args.port, remote_id=rid, step_delay=args.step_delay)
+        for fixture, name, host, rid in SIM_HUBS[: args.hubs]
+    ]
+    try:
+        for f in fakes:
+            await f.start()
+    except OSError as exc:
+        print(
+            f"Couldn't start a fake hub: {exc}. Is port {args.port} free? (On macOS add the second loopback "
+            "address first: sudo ifconfig lo0 alias 127.0.0.2.)",
+            file=sys.stderr,
+        )
+        for f in fakes:
+            await f.stop()
+        return 1
+    cfg_dir = Path(args.write_config) if args.write_config else None
+    if cfg_dir is not None:
+        cfg_dir.mkdir(parents=True, exist_ok=True)
+        doc: dict[str, object] = {"protocol": "WEBSOCKETS", "hubs": [{"host": f.host} for f in fakes]}
+        if args.port != 8088:
+            doc["port"] = args.port
+        (cfg_dir / "config.json").write_text(json.dumps(doc, indent=2) + "\n")
+    print("Fake Harmony hubs (verified-against-nothing: they implement the protocol as aioharmony expects it):")
+    for f in fakes:
+        print(
+            f"  {f.name:<12} {f.host}:{f.port}  activities: {', '.join(a['label'] for a in f.config['activity'][1:])}"
+        )
+    target = cfg_dir or config_dir()
+    print(f"\nIn another terminal:\n  HARMONY_CONFIG_DIR={target} mcp-server-harmony doctor")
+    print(f"  HARMONY_CONFIG_DIR={target} mcp-server-harmony serve      # or add it to Claude Code/Desktop")
+    if cfg_dir is None:
+        print("(Pass --write-config DIR to have a config.json for these written for you.)")
+    print("Ctrl+C to stop.")
+    sys.stdout.flush()
+    if ready is not None:
+        ready.set()
+    try:
+        while True:
+            await asyncio.sleep(args.flaky or 3600)
+            if args.flaky:
+                print("Dropping all connections (--flaky)")
+                for f in fakes:
+                    await f.drop_connections()
+    finally:
+        for f in fakes:
+            await f.stop()
+
+
+async def _cmd_call(args: argparse.Namespace) -> int:
+    from mcp import Client
+
+    from .server import mcp
+
+    tool_args: dict[str, object] = {}
+    for pair in args.args:
+        key, sep, raw = pair.partition("=")
+        if not sep:
+            print(f"arguments are key=value, got {pair!r}", file=sys.stderr)
+            return 2
+        try:
+            tool_args[key] = json.loads(raw)  # repeat=3 -> 3, hub=null -> None
+        except json.JSONDecodeError:
+            tool_args[key] = raw  # activity=Watch TV -> a string
+    async with Client(mcp) as c:
+        if args.tool == "tools":
+            for t in (await c.list_tools()).tools:
+                print(f"{t.name:<16} {(t.description or '').splitlines()[0]}")
+            return 0
+        result = await c.call_tool(args.tool, tool_args)
+    if result.is_error:
+        print(" ".join(getattr(part, "text", "") for part in result.content) or "error", file=sys.stderr)
+        return 1
+    body = result.structured_content
+    if isinstance(body, dict) and set(body) == {"result"}:
+        body = body["result"]
+    print(json.dumps(body, indent=2))
+    return 0
+
+
+# --- main ---------------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="mcp-server-harmony", description="MCP server for Logitech Harmony Hubs")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("-v", "--verbose", action="count", default=0, help="debug logging (aioharmony frames too)")
+    common.add_argument(
+        "--no-redact",
+        action="store_true",
+        help="don't mask IPs and MACs in logs; secrets stay masked (HARMONY_LOG_UNREDACTED=1)",
+    )
+    sub = parser.add_subparsers(dest="cmd")
+    serve = sub.add_parser("serve", parents=[common], help="Run the MCP server (stdio by default, or --http)")
+    serve.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="read the hubs but send nothing that changes anything (HARMONY_DRY_RUN=1)",
+    )
+    remote.add_http_arguments(serve, default_port=8713, default_path="/harmony/mcp")
+    check = sub.add_parser(
+        "check", parents=[common], help="Connect to a hub (or every configured hub), list it, and save it"
+    )
+    where = check.add_mutually_exclusive_group()
+    where.add_argument("--host", help="A hub's IP address or hostname, to add it")
+    where.add_argument("--discover", action="store_true", help="find hubs with SSDP first, then check and save each")
+    call = sub.add_parser("call", parents=[common], help="Call one tool as the model would and print the result")
+    call.add_argument("tool", help="tool name, or 'tools' to list them")
+    call.add_argument("args", nargs="*", metavar="key=value", help="tool arguments (values are JSON if they parse)")
+    call.add_argument("--dry-run", action="store_true", help="send nothing that changes anything")
+    disc = sub.add_parser("discover", parents=[common], help="Look for hubs on the LAN with SSDP")
+    disc.add_argument("--timeout", type=float, default=3.0)
+    disc.add_argument("--st", default="urn:myharmony-com:device:harmony:1", help="search target (try ssdp:all)")
+    disc.add_argument("--raw", action="store_true", help="print each reply in full")
+    doc = sub.add_parser("doctor", parents=[common], help="Check config and every hub, layer by layer")
+    doc.add_argument("--json", action="store_true", help="machine-readable output")
+    doc.add_argument("--dump", metavar="DIR", help="also write each hub's redacted raw data to DIR")
+    doc.add_argument("--timeout", type=float, default=10.0, help="seconds per step (default 10)")
+    doc.add_argument("--host", help="check this address instead of the configured hubs")
+    sim = sub.add_parser("simulate", parents=[common], help="Run fake hubs locally, for testing without hardware")
+    sim.add_argument("--hubs", type=int, choices=[1, 2], default=2)
+    sim.add_argument("--port", type=int, default=8088, help="port for every fake hub (aioharmony uses 8088)")
+    sim.add_argument("--step-delay", type=float, default=0.4, help="seconds per device while an activity starts")
+    sim.add_argument("--write-config", metavar="DIR", help="write a config.json pointing at the fake hubs to DIR")
+    sim.add_argument("--flaky", type=float, metavar="SECONDS", help="drop every connection every SECONDS")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.cmd in ("check", "call", "discover", "doctor", "simulate"):
+        _setup_logging(args, default=logging.WARNING)
+        if getattr(args, "dry_run", False):
+            os.environ["HARMONY_DRY_RUN"] = "1"
+        with contextlib.suppress(KeyboardInterrupt):
+            if args.cmd == "check":
+                sys.exit(asyncio.run(_cmd_check(args.host, args.discover)))
+            if args.cmd == "call":
+                sys.exit(asyncio.run(_cmd_call(args)))
+            if args.cmd == "discover":
+                sys.exit(asyncio.run(_cmd_discover(args.timeout, args.st, args.raw)))
+            if args.cmd == "doctor":
+                sys.exit(asyncio.run(_cmd_doctor(args)))
+            sys.exit(asyncio.run(_cmd_simulate(args)))
+        sys.exit(130)
+
+    _setup_logging(args)
+    if getattr(args, "dry_run", False):
+        os.environ["HARMONY_DRY_RUN"] = "1"  # read by load_settings in the server's lifespan
+    # Imported here so the other commands don't pay for the MCP server's imports.
+    from .server import mcp
+
+    if getattr(args, "http", False):
+        try:
+            remote.serve_http(mcp, remote.http_config(args))
+        except remote.ConfigError as exc:
+            parser.exit(2, f"mcp-server-harmony: {exc}\n")
+    else:
+        mcp.run()  # stdio: JSON-RPC over stdin/stdout