stackchan-mcp 0.9.1__py3-none-win_amd64.whl

stackchan_mcp/mdns_advertiser.py

@@ -0,0 +1,347 @@
+"""mDNS/DNS-SD advertisement for the StackChan WebSocket gateway."""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+import socket
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+SERVICE_TYPE = "_stackchan-mcp._tcp.local."
+DEFAULT_INSTANCE = "stackchan-mcp"
+SERVICE_NAME = f"{DEFAULT_INSTANCE}.{SERVICE_TYPE}"
+FALLBACK_SERVICE_HOSTNAME = f"{DEFAULT_INSTANCE}.local."
+TXT_VERSION = "1"
+
+# Private (RFC1918) IPv4 ranges. Addresses inside these ranges are the most
+# likely to be reachable from a same-LAN device, so they are advertised first.
+# Anything outside is still advertised, just ordered after these.
+_PRIVATE_NETWORKS = (
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+)
+
+# Only prefixes shorter than /31 have a distinct network and broadcast address.
+# A /31 (point-to-point) or /32 (host) address must never be treated as a
+# network or broadcast address, since that would drop a legitimate host IP.
+_MAX_NETWORK_BROADCAST_PREFIX = 30
+
+
+@dataclass(frozen=True)
+class MdnsAdvertisement:
+    """Resolved service advertisement parameters."""
+
+    service_type: str
+    service_name: str
+    server: str
+    port: int
+    path: str
+    properties: dict[str, str]
+    parsed_addresses: list[str]
+
+
+def _load_zeroconf_classes() -> tuple[type[Any], type[Any]]:
+    from zeroconf import ServiceInfo
+    from zeroconf.asyncio import AsyncZeroconf
+
+    return AsyncZeroconf, ServiceInfo
+
+
+def _is_usable_ipv4(address: str) -> bool:
+    try:
+        ip = ipaddress.ip_address(address)
+    except ValueError:
+        return False
+    return (
+        ip.version == 4
+        and not ip.is_unspecified
+        and not ip.is_loopback
+        and not ip.is_multicast
+    )
+
+
+def _is_network_or_broadcast_address(address: str, prefix: int | None) -> bool:
+    """Return ``True`` when ``address`` is the subnet network or broadcast address.
+
+    Requires the subnet prefix: without it (e.g. the socket-based source) the
+    network/broadcast endpoints cannot be derived, so callers pass ``None`` and
+    the address is kept. Host prefixes (/31, /32) have no distinct network or
+    broadcast address and are never excluded here.
+    """
+    if prefix is None or prefix > _MAX_NETWORK_BROADCAST_PREFIX:
+        return False
+    try:
+        interface = ipaddress.ip_interface(f"{address}/{prefix}")
+    except ValueError:
+        return False
+    network = interface.network
+    return interface.ip in (network.network_address, network.broadcast_address)
+
+
+def _is_private_lan_address(address: str) -> bool:
+    try:
+        ip = ipaddress.ip_address(address)
+    except ValueError:
+        return False
+    return any(ip in network for network in _PRIVATE_NETWORKS)
+
+
+def _lan_reachability_tier(address: str) -> int:
+    """Sort key: private (RFC1918) LAN addresses first, everything else after.
+
+    Returns a 2-value tier so a stable sort preserves the original enumeration
+    order within each tier.
+    """
+    return 0 if _is_private_lan_address(address) else 1
+
+
+def _select_advertised_addresses(
+    candidates: list[tuple[str, int | None]],
+) -> list[str]:
+    """Filter, de-duplicate and order candidate addresses for advertisement.
+
+    Excludes only clearly-unusable addresses (loopback/multicast/unspecified via
+    :func:`_is_usable_ipv4`, plus network/broadcast addresses when a prefix is
+    known). All remaining addresses are kept and ordered by LAN-reachability
+    likelihood (RFC1918 private ranges first) using a stable sort, so addresses
+    a same-LAN device can reach are tried before overlay/global/edge-case ones.
+    """
+    seen: set[str] = set()
+    usable: list[str] = []
+    for address, prefix in candidates:
+        if address in seen or not _is_usable_ipv4(address):
+            continue
+        if _is_network_or_broadcast_address(address, prefix):
+            continue
+        seen.add(address)
+        usable.append(address)
+    usable.sort(key=_lan_reachability_tier)
+    return usable
+
+
+def _is_wildcard_host(host: str) -> bool:
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return host in {"", "*"}
+    return ip.is_unspecified
+
+
+def _build_service_hostname() -> str:
+    """Return a service-specific mDNS hostname for the SRV record.
+
+    Uses a fixed name to avoid advertising A records that overlap with
+    the system's own Bonjour hostname registration, which can trigger
+    macOS to change the user's LocalHostName.
+    """
+    return FALLBACK_SERVICE_HOSTNAME
+
+
+def _iter_ifaddr_ipv4_addresses() -> list[tuple[str, int | None]]:
+    """Enumerate host IPv4 addresses with their subnet prefix length.
+
+    The prefix (``ip.network_prefix``) lets the caller drop network/broadcast
+    addresses; it is ``None`` only if ifaddr reports a non-integer prefix.
+    """
+    try:
+        import ifaddr
+    except ImportError:
+        return []
+
+    addresses: list[tuple[str, int | None]] = []
+    for adapter in ifaddr.get_adapters():
+        for ip in adapter.ips:
+            if not isinstance(ip.ip, str):
+                continue
+            prefix = ip.network_prefix if isinstance(ip.network_prefix, int) else None
+            addresses.append((ip.ip, prefix))
+    return addresses
+
+
+def _iter_socket_ipv4_addresses() -> list[tuple[str, int | None]]:
+    """Enumerate host IPv4 addresses via socket resolution.
+
+    This source carries no subnet prefix, so each entry pairs the address with
+    ``None``; network/broadcast addresses therefore cannot be (and are not)
+    excluded from this source.
+    """
+    addresses: set[str] = set()
+    hostnames = {socket.gethostname(), socket.getfqdn()}
+
+    for hostname in hostnames:
+        try:
+            infos = socket.getaddrinfo(hostname, None, socket.AF_INET)
+        except socket.gaierror:
+            continue
+        for _family, _socktype, _proto, _canonname, sockaddr in infos:
+            addresses.add(sockaddr[0])
+
+    # Add the primary outbound IPv4 as a best-effort fallback. UDP connect()
+    # selects a local address without sending packets.
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.connect(("8.8.8.8", 80))
+        addresses.add(sock.getsockname()[0])
+    except OSError:
+        pass
+    finally:
+        sock.close()
+
+    return [(address, None) for address in sorted(addresses)]
+
+
+def _enumerate_usable_ipv4_addresses() -> list[str]:
+    ifaddr_entries = _iter_ifaddr_ipv4_addresses()
+    socket_entries = _iter_socket_ipv4_addresses()
+
+    # The socket-based source carries no subnet prefix, so on its own it cannot
+    # exclude network/broadcast addresses. When the same address also appears
+    # in the ifaddr source (which does carry a prefix), adopt that prefix so
+    # ``_is_network_or_broadcast_address`` can recognise and drop the entry.
+    # Without this, a host whose ``getaddrinfo``-resolved set includes an
+    # interface's subnet network base (which can happen when an interface ends
+    # up with its own subnet's network address as its host IP) would be
+    # advertised and then crash the zeroconf socket with ``EADDRNOTAVAIL``.
+    prefix_by_address = {
+        address: prefix
+        for address, prefix in ifaddr_entries
+        if prefix is not None
+    }
+    enriched_socket_entries = [
+        (address, prefix_by_address.get(address, prefix))
+        for address, prefix in socket_entries
+    ]
+
+    return _select_advertised_addresses(
+        [*ifaddr_entries, *enriched_socket_entries]
+    )
+
+
+def _resolve_concrete_host_ipv4_addresses(host: str) -> list[str]:
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        try:
+            infos = socket.getaddrinfo(host, None, socket.AF_INET)
+        except socket.gaierror:
+            return []
+        addresses = [sockaddr[0] for *_unused, sockaddr in infos]
+    else:
+        addresses = [str(ip)]
+
+    # A concrete HOST carries no subnet prefix, so network/broadcast addresses
+    # cannot be derived; pair each address with ``None`` to keep them.
+    return _select_advertised_addresses([(address, None) for address in addresses])
+
+
+def build_advertisement(
+    *,
+    host: str,
+    port: int,
+    path: str = "/",
+) -> MdnsAdvertisement | None:
+    """Resolve advertisement parameters, or ``None`` if they would be unusable."""
+    if port <= 0 or port > 65535:
+        logger.warning(
+            "mDNS advertisement skipped: WebSocket port %s is not publishable",
+            port,
+        )
+        return None
+
+    normalized_path = path if path.startswith("/") else f"/{path}"
+    addresses = (
+        _enumerate_usable_ipv4_addresses()
+        if _is_wildcard_host(host)
+        else _resolve_concrete_host_ipv4_addresses(host)
+    )
+    if not addresses:
+        logger.warning(
+            "mDNS advertisement skipped: no usable non-loopback IPv4 address "
+            "found for HOST=%s",
+            host,
+        )
+        return None
+
+    return MdnsAdvertisement(
+        service_type=SERVICE_TYPE,
+        service_name=SERVICE_NAME,
+        server=_build_service_hostname(),
+        port=port,
+        path=normalized_path,
+        properties={"path": normalized_path, "version": TXT_VERSION},
+        parsed_addresses=addresses,
+    )
+
+
+class MdnsAdvertiser:
+    """Registers the gateway's WebSocket endpoint via mDNS/DNS-SD."""
+
+    def __init__(self) -> None:
+        self._zeroconf: Any | None = None
+        self._service_info: Any | None = None
+
+    async def start(self, *, host: str, port: int, path: str = "/") -> None:
+        advertisement = build_advertisement(host=host, port=port, path=path)
+        if advertisement is None:
+            return
+
+        AsyncZeroconf, ServiceInfo = _load_zeroconf_classes()
+        # Constrain zeroconf to the IPv4 interfaces we actually advertise on.
+        # The default ``InterfaceChoice.All`` makes zeroconf bind a socket on
+        # every host IPv4 address it can find, which on a host with several
+        # interfaces can include addresses the kernel refuses ``sendto`` on
+        # (the engine then never finishes starting, and the gateway hangs in
+        # ``async_wait_for_start``). Passing the same set of addresses we put
+        # into the SRV record keeps zeroconf in sync with our advertisement
+        # and skips the unusable interfaces entirely.
+        zeroconf = AsyncZeroconf(interfaces=advertisement.parsed_addresses)
+        info = ServiceInfo(
+            advertisement.service_type,
+            advertisement.service_name,
+            port=advertisement.port,
+            properties=advertisement.properties,
+            server=advertisement.server,
+            parsed_addresses=advertisement.parsed_addresses,
+        )
+        try:
+            await zeroconf.async_register_service(info, allow_name_change=True)
+        except Exception:
+            await zeroconf.async_close()
+            raise
+        self._zeroconf = zeroconf
+        self._service_info = info
+        registered_name = getattr(info, "name", advertisement.service_name)
+        if registered_name != advertisement.service_name:
+            logger.warning(
+                "mDNS service registered under a modified name %s (requested %s). "
+                "A previous gateway instance may not have shut down cleanly and its "
+                "registration is still visible on the network. The ESP32 still "
+                "discovers this gateway by service type, so auto-discovery keeps "
+                "working; the stale entry clears when its mDNS TTL expires.",
+                registered_name,
+                advertisement.service_name,
+            )
+        logger.info(
+            "mDNS advertising %s on port %d with addresses %s",
+            registered_name,
+            advertisement.port,
+            ", ".join(advertisement.parsed_addresses),
+        )
+
+    async def stop(self) -> None:
+        zeroconf = self._zeroconf
+        info = self._service_info
+        self._zeroconf = None
+        self._service_info = None
+
+        if zeroconf is None:
+            return
+        try:
+            if info is not None:
+                await zeroconf.async_unregister_service(info)
+        finally:
+            await zeroconf.async_close()

stackchan_mcp/notify.example.yml

@@ -0,0 +1,21 @@
+# ~/.config/stackchan-mcp/notify.yml
+legacy_event:
+  enabled: false          # self-defined method "stackchan/event" (existing, backward-compat)
+channels:
+  enabled: false          # standard "notifications/claude/channel"
+jsonl:
+  enabled: false          # JSONL append for out-of-process host integration
+  path: ~/.claude/stackchan-events.jsonl
+# messages: override the wording delivered for each physical event.
+# Omit this block entirely to keep the built-in experiential defaults
+# ("head was tapped" / "head was stroked for {duration_ms}ms").
+# The examples below customize the phrasing per event type; {duration_ms}
+# is substituted from the event payload.
+messages:
+  touch:
+    tap:
+      action: head_pat
+      template: "got a head pat"
+    stroke:
+      action: head_stroke
+      template: "head being stroked for {duration_ms}ms"

stackchan_mcp/notify_config.py

@@ -0,0 +1,235 @@
+"""Notification configuration for Stack-chan physical events."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+import os
+from pathlib import Path
+from typing import Any, Final
+
+import yaml
+
+from .event_log import DEFAULT_LOG_PATH, PATH_ENV_VAR
+
+logger = logging.getLogger(__name__)
+
+CONFIG_ENV_VAR: Final[str] = "STACKCHAN_NOTIFY_CONFIG"
+CONFIG_FILENAME: Final[str] = "stackchan-mcp/notify.yml"
+
+
+@dataclass(frozen=True)
+class MessageTemplate:
+    action: str
+    template: str
+
+
+@dataclass(frozen=True)
+class NotifyConfig:
+    legacy_event_enabled: bool
+    channels_enabled: bool
+    jsonl_enabled: bool
+    jsonl_path: Path
+    messages: dict[tuple[str, str], MessageTemplate]
+
+
+DEFAULT_MESSAGE_TEMPLATES: Final[dict[tuple[str, str], MessageTemplate]] = {
+    ("touch", "tap"): MessageTemplate(
+        action="head_pat",
+        template="head was tapped",
+    ),
+    ("touch", "stroke"): MessageTemplate(
+        action="head_stroke",
+        template="head was stroked for {duration_ms}ms",
+    ),
+}
+
+
+def resolve_notify_config_path() -> Path | None:
+    """Return the first existing notify.yml path, or None."""
+    override = os.environ.get(CONFIG_ENV_VAR)
+    if override:
+        path = Path(override).expanduser()
+        if path.exists():
+            return path
+        logger.warning(
+            "%s points to a non-existent file: %s",
+            CONFIG_ENV_VAR,
+            path,
+        )
+        return None
+
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    candidates = []
+    if xdg_config_home:
+        candidates.append(Path(xdg_config_home).expanduser() / CONFIG_FILENAME)
+    candidates.append(Path.home() / ".config" / CONFIG_FILENAME)
+
+    for path in candidates:
+        if path.exists():
+            return path
+    return None
+
+
+def load_notify_config() -> NotifyConfig:
+    """Load the notification config, falling back to all-OFF on errors."""
+    path = resolve_notify_config_path()
+    if path is None:
+        return _default_config()
+
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            raw = yaml.safe_load(f)
+        return _parse_config(raw)
+    except (OSError, yaml.YAMLError, ValueError, TypeError) as exc:
+        logger.warning(
+            "Failed to load Stack-chan notify config from %s: %s",
+            path,
+            exc,
+        )
+        return _default_config()
+
+
+def render_template(template: str, payload: dict[str, Any]) -> str:
+    """Render a user template while preserving unknown placeholders.
+
+    A malformed-but-yaml-valid template (e.g. ``{duration_ms.foo}`` or
+    ``{unknown[0]}``) can raise ``AttributeError`` or ``TypeError`` from
+    ``str.format_map``. These are caught here so a single bad user template
+    cannot crash the channels dispatch path on every physical event; the
+    original template string is returned as a defensive fallback.
+    """
+    try:
+        return template.format_map(_SafeFormatDict(payload))
+    except (IndexError, KeyError, ValueError, AttributeError, TypeError):
+        return template
+
+
+def _default_config() -> NotifyConfig:
+    return NotifyConfig(
+        legacy_event_enabled=False,
+        channels_enabled=False,
+        jsonl_enabled=False,
+        jsonl_path=_resolve_jsonl_path(None),
+        messages=_default_messages(),
+    )
+
+
+def _default_messages() -> dict[tuple[str, str], MessageTemplate]:
+    return dict(DEFAULT_MESSAGE_TEMPLATES)
+
+
+def _parse_config(raw: Any) -> NotifyConfig:
+    if raw is None:
+        raw = {}
+    if not isinstance(raw, dict):
+        raise ValueError("notify config root must be a mapping")
+
+    legacy_event_enabled = _parse_enabled(raw, "legacy_event")
+    channels_enabled = _parse_enabled(raw, "channels")
+    jsonl_section = _parse_section(raw, "jsonl")
+    jsonl_enabled = _parse_enabled(raw, "jsonl")
+    jsonl_path = _resolve_jsonl_path(_optional_string(jsonl_section, "path"))
+    messages = _parse_messages(raw.get("messages"))
+
+    return NotifyConfig(
+        legacy_event_enabled=legacy_event_enabled,
+        channels_enabled=channels_enabled,
+        jsonl_enabled=jsonl_enabled,
+        jsonl_path=jsonl_path,
+        messages=messages,
+    )
+
+
+def _parse_enabled(root: dict[Any, Any], section_name: str) -> bool:
+    section = _parse_section(root, section_name)
+    enabled = section.get("enabled", False)
+    if not isinstance(enabled, bool):
+        raise ValueError(f"{section_name}.enabled must be a boolean")
+    return enabled
+
+
+def _parse_section(root: dict[Any, Any], section_name: str) -> dict[Any, Any]:
+    section = root.get(section_name, {})
+    if section is None:
+        return {}
+    if not isinstance(section, dict):
+        raise ValueError(f"{section_name} must be a mapping")
+    return section
+
+
+def _optional_string(section: dict[Any, Any], key: str) -> str | None:
+    value = section.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{key} must be a non-empty string")
+    return value
+
+
+def _parse_messages(raw_messages: Any) -> dict[tuple[str, str], MessageTemplate]:
+    messages = _default_messages()
+    if raw_messages is None:
+        return messages
+    if not isinstance(raw_messages, dict):
+        raise ValueError("messages must be a mapping")
+
+    for event_type, subtypes in raw_messages.items():
+        if not isinstance(event_type, str) or not event_type:
+            raise ValueError("messages event_type keys must be non-empty strings")
+        if not isinstance(subtypes, dict):
+            raise ValueError(f"messages.{event_type} must be a mapping")
+        for subtype, message in subtypes.items():
+            if not isinstance(subtype, str) or not subtype:
+                raise ValueError("messages subtype keys must be non-empty strings")
+            if not isinstance(message, dict):
+                raise ValueError(f"messages.{event_type}.{subtype} must be a mapping")
+            action = message.get("action")
+            template = message.get("template")
+            if not isinstance(action, str) or not action:
+                raise ValueError(
+                    f"messages.{event_type}.{subtype}.action must be a non-empty string"
+                )
+            if not isinstance(template, str) or not template:
+                raise ValueError(
+                    f"messages.{event_type}.{subtype}.template must be a non-empty string"
+                )
+            messages[(event_type, subtype)] = MessageTemplate(
+                action=action,
+                template=template,
+            )
+    return messages
+
+
+def _resolve_jsonl_path(configured_path: str | None) -> Path:
+    override = os.environ.get(PATH_ENV_VAR)
+    if override:
+        return _absolute_path(override)
+    if configured_path:
+        return _absolute_path(configured_path)
+    return DEFAULT_LOG_PATH
+
+
+def _absolute_path(raw_path: str) -> Path:
+    path = Path(raw_path).expanduser()
+    if path.is_absolute():
+        return path
+    return path.resolve()
+
+
+class _SafeFormatDict(dict[str, Any]):
+    def __missing__(self, key: str) -> "_MissingPlaceholder":
+        return _MissingPlaceholder(key)
+
+
+class _MissingPlaceholder:
+    def __init__(self, key: str) -> None:
+        self._key = key
+
+    def __format__(self, spec: str) -> str:
+        if spec:
+            return "{" + self._key + ":" + spec + "}"
+        return "{" + self._key + "}"
+
+    def __str__(self) -> str:
+        return "{" + self._key + "}"