stackchan-mcp 0.9.1__tar.gz → 0.11.0__tar.gz

{stackchan_mcp-0.9.1 → stackchan_mcp-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.9.1
+Version: 0.11.0
 Summary: Two-faced MCP gateway for StackChan (xiaozhi-esp32): bridges stdio MCP clients to the ESP32 over WebSocket + HTTP.
 Project-URL: Homepage, https://github.com/kisaragi-mochi/stackchan-mcp
 Project-URL: Repository, https://github.com/kisaragi-mochi/stackchan-mcp
@@ -41,6 +41,10 @@ Requires-Dist: opuslib>=3; extra == 'stt-openai'
 Provides-Extra: tts
 Requires-Dist: httpx>=0.27; extra == 'tts'
 Requires-Dist: opuslib>=3; extra == 'tts'
+Provides-Extra: tts-irodori
+Requires-Dist: httpx>=0.27; extra == 'tts-irodori'
+Requires-Dist: miniaudio>=1.59; extra == 'tts-irodori'
+Requires-Dist: opuslib>=3; extra == 'tts-irodori'
 Provides-Extra: tts-voicevox
 Requires-Dist: httpx>=0.27; extra == 'tts-voicevox'
 Requires-Dist: opuslib>=3; extra == 'tts-voicevox'

{stackchan_mcp-0.9.1 → stackchan_mcp-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.9.1"
+version = "0.11.0"
 description = "Two-faced MCP gateway for StackChan (xiaozhi-esp32): bridges stdio MCP clients to the ESP32 over WebSocket + HTTP."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -51,7 +51,7 @@ dependencies = [
 [project.optional-dependencies]
 # Phase 4 TTS — see Issue #70.
 # Concrete engines (VOICEVOX, Irodori) consume these libraries:
-#   * httpx     — VOICEVOX HTTP engine client
+#   * httpx     — VOICEVOX / Irodori HTTP engine client
 #   * opuslib   — Opus encoding for the device's audio decoder
 # `tts-voicevox` is a no-op alias provided so users can declare intent
 # explicitly; the VOICEVOX engine itself is an external HTTP process and
@@ -63,6 +63,17 @@ tts = [
 tts-voicevox = [
     "stackchan-mcp[tts]",
 ]
+# Irodori is an external HTTP synthesis service that returns MP3 (see
+# Issue #286). On top of the base `[tts]` extra (httpx + opuslib) it adds
+# `miniaudio` to decode the MP3 response to PCM. miniaudio is a small,
+# self-contained C extension (MIT) with prebuilt wheels for Windows,
+# macOS (x86_64 + arm64), and Linux, so it installs without a system
+# audio library — unlike a ffmpeg/libav binding — which keeps the
+# Windows wheel path (and the CI windows-smoke job) simple.
+tts-irodori = [
+    "stackchan-mcp[tts]",
+    "miniaudio>=1.59",
+]
 
 # Phase 4 STT — see Issue #91.
 # The base `stt` extra carries `opuslib` for decoding the device's

{stackchan_mcp-0.9.1 → stackchan_mcp-0.11.0}/stackchan_mcp/mdns_advertiser.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import ipaddress
 import logging
 import socket
@@ -238,6 +239,26 @@ def _resolve_concrete_host_ipv4_addresses(host: str) -> list[str]:
     return _select_advertised_addresses([(address, None) for address in addresses])
 
 
+def _resolve_addresses_for_host(host: str) -> list[str]:
+    """Resolve advertised addresses for ``host`` using the same logic as
+    :func:`build_advertisement`.
+
+    Wildcard hosts (``0.0.0.0`` / ``*`` / ``""``) enumerate every usable
+    non-loopback IPv4 address on the machine; concrete hosts only resolve
+    addresses for that specific host. The refresh loop calls this helper so
+    its comparison set matches what a fresh ``build_advertisement(...)``
+    would actually register — without this, a host started with a concrete
+    HOST in a multi-NIC / Tailscale environment would see every poll as an
+    "address change" against an unrelated extra interface and churn the
+    registration on every refresh interval.
+    """
+    return (
+        _enumerate_usable_ipv4_addresses()
+        if _is_wildcard_host(host)
+        else _resolve_concrete_host_ipv4_addresses(host)
+    )
+
+
 def build_advertisement(
     *,
     host: str,
@@ -253,11 +274,7 @@ def build_advertisement(
         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)
-    )
+    addresses = _resolve_addresses_for_host(host)
     if not addresses:
         logger.warning(
             "mDNS advertisement skipped: no usable non-loopback IPv4 address "
@@ -280,15 +297,57 @@ def build_advertisement(
 class MdnsAdvertiser:
     """Registers the gateway's WebSocket endpoint via mDNS/DNS-SD."""
 
-    def __init__(self) -> None:
+    def __init__(self, *, refresh_interval: float = 30.0) -> None:
+        if refresh_interval < 10.0 or refresh_interval > 300.0:
+            raise ValueError("refresh_interval must be between 10.0 and 300.0 seconds")
+        self._lock: asyncio.Lock = asyncio.Lock()
         self._zeroconf: Any | None = None
         self._service_info: Any | None = None
+        self._refresh_task: asyncio.Task | None = None
+        self._last_advertised_addresses: tuple[str, ...] | None = None
+        self._refresh_interval: float = refresh_interval
+        self._start_args: dict[str, Any] | None = None
 
     async def start(self, *, host: str, port: int, path: str = "/") -> None:
+        task = self._refresh_task
+        if task is not None and task is not asyncio.current_task():
+            task.cancel()
+            try:
+                await asyncio.wait_for(task, timeout=1.0)
+            except (asyncio.CancelledError, TimeoutError):
+                pass
+
+        async with self._lock:
+            self._refresh_task = None
+            if self._zeroconf is not None:
+                await self._close_zeroconf_locked()
+            self._start_args = {"host": host, "port": port, "path": path}
+            try:
+                advertisement = await self._start_locked(host=host, port=port, path=path)
+            except Exception:
+                self._start_args = None
+                self._last_advertised_addresses = None
+                raise
+            if advertisement is None:
+                self._start_args = None
+                self._last_advertised_addresses = None
+                return
+            self._last_advertised_addresses = tuple(advertisement.parsed_addresses)
+            self._refresh_task = asyncio.create_task(self._refresh_loop())
+
+    async def _start_locked(
+        self, *, host: str, port: int, path: str = "/"
+    ) -> MdnsAdvertisement | None:
         advertisement = build_advertisement(host=host, port=port, path=path)
         if advertisement is None:
-            return
+            return None
 
+        await self._register_advertisement_locked(advertisement)
+        return advertisement
+
+    async def _register_advertisement_locked(
+        self, advertisement: MdnsAdvertisement
+    ) -> None:
         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
@@ -309,7 +368,15 @@ class MdnsAdvertiser:
         )
         try:
             await zeroconf.async_register_service(info, allow_name_change=True)
-        except Exception:
+        except BaseException:
+            # Catch BaseException (not just Exception) so that an
+            # ``asyncio.CancelledError`` arriving mid-registration —
+            # e.g. an external ``stop()`` or a double-``start()`` racing
+            # this registration — still closes the partially-constructed
+            # ``AsyncZeroconf``. Otherwise the bound multicast sockets
+            # and any partial registration would leak past the cancelled
+            # task. ``raise`` preserves the cancellation semantics for
+            # the surrounding ``async with self._lock`` caller.
             await zeroconf.async_close()
             raise
         self._zeroconf = zeroconf
@@ -326,13 +393,28 @@ class MdnsAdvertiser:
                 advertisement.service_name,
             )
         logger.info(
-            "mDNS advertising %s on port %d with addresses %s",
+            "mDNS advertising %s on port %d with addresses %s reason=register",
             registered_name,
             advertisement.port,
             ", ".join(advertisement.parsed_addresses),
         )
 
     async def stop(self) -> None:
+        task = self._refresh_task
+        if task is not None and task is not asyncio.current_task():
+            task.cancel()
+            try:
+                await asyncio.wait_for(task, timeout=1.0)
+            except (asyncio.CancelledError, TimeoutError):
+                pass
+
+        async with self._lock:
+            await self._close_zeroconf_locked()
+            self._refresh_task = None
+            self._last_advertised_addresses = None
+            self._start_args = None
+
+    async def _close_zeroconf_locked(self) -> None:
         zeroconf = self._zeroconf
         info = self._service_info
         self._zeroconf = None
@@ -345,3 +427,91 @@ class MdnsAdvertiser:
                 await zeroconf.async_unregister_service(info)
         finally:
             await zeroconf.async_close()
+
+    async def _reconfigure(self) -> None:
+        async with self._lock:
+            if self._start_args is None:
+                return
+            old_addresses = self._last_advertised_addresses
+            advertisement = build_advertisement(**self._start_args)
+            if advertisement is None:
+                logger.info(
+                    "mDNS reconfigure skipped: build_advertisement returned None "
+                    "(transient empty address state); refresh loop continues "
+                    "reason=transient_empty_address_state old=%s",
+                    old_addresses,
+                )
+                return
+
+            # Clear the cached advertised set BEFORE closing so that even a
+            # failure inside ``_close_zeroconf_locked()`` itself (e.g. the
+            # old interface has vanished mid-cycle and ``async_unregister``
+            # / ``async_close`` raise) still leaves the refresh loop in a
+            # "must retry" state. If the subsequent close raises, or the
+            # re-registration raises, or the host IP later reverts to
+            # ``old_addresses``, the refresh loop's
+            # ``current != _last_advertised_addresses`` check would
+            # otherwise compare against the stale value and stay quiet —
+            # the advertisement would remain dead until a manual restart.
+            # Setting this to ``None`` here guarantees the next refresh
+            # tick observes a divergence and retries registration
+            # regardless of which address state the host happens to be in.
+            self._last_advertised_addresses = None
+            await self._close_zeroconf_locked()
+            await self._register_advertisement_locked(advertisement)
+            new_addresses = tuple(advertisement.parsed_addresses)
+            self._last_advertised_addresses = new_addresses
+            registered_name = getattr(
+                self._service_info,
+                "name",
+                advertisement.service_name,
+            )
+            logger.info(
+                "mDNS reconfigured: reason=address_changed old=%s new=%s "
+                "registered_name=%s",
+                old_addresses,
+                new_addresses,
+                registered_name,
+            )
+
+    async def _refresh_loop(self) -> None:
+        while True:
+            try:
+                await asyncio.sleep(self._refresh_interval)
+                start_args = self._start_args
+                if start_args is None:
+                    continue
+                host = start_args["host"]
+                current_addresses = tuple(_resolve_addresses_for_host(host))
+                old_addresses = self._last_advertised_addresses
+                if current_addresses == old_addresses:
+                    continue
+
+                logger.info(
+                    "mDNS refresh observed address change: reason=address_changed "
+                    "old=%s new=%s debounce=started",
+                    old_addresses,
+                    current_addresses,
+                )
+                await asyncio.sleep(self._refresh_interval)
+                start_args = self._start_args
+                if start_args is None:
+                    continue
+                host = start_args["host"]
+                confirmed_addresses = tuple(_resolve_addresses_for_host(host))
+                if confirmed_addresses != current_addresses:
+                    logger.info(
+                        "mDNS refresh dropped transient address change: "
+                        "reason=debounce_mismatch old=%s first=%s second=%s",
+                        old_addresses,
+                        current_addresses,
+                        confirmed_addresses,
+                    )
+                    continue
+
+                await self._reconfigure()
+            except asyncio.CancelledError:
+                return
+            except Exception:
+                logger.exception("mDNS refresh loop error; continuing")
+                continue

{stackchan_mcp-0.9.1 → stackchan_mcp-0.11.0}/stackchan_mcp/ownership.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import json
+import math
 import os
 import socket
+import subprocess
 import sys
 import uuid
 from datetime import datetime, timezone
@@ -13,6 +15,8 @@ from typing import Literal, TypedDict
 
 LOCK_DIR = Path.home() / ".stackchan-mcp"
 LOCK_PATH = LOCK_DIR / "owner.lock"
+PROC_START_TOLERANCE_SECONDS = 2.0
+_PROC_ROOT = Path("/proc")
 
 
 LockMode = Literal["stdio", "streamable-http"]
@@ -29,6 +33,7 @@ class LockInfo(_BaseLockInfo, total=False):
     mode: LockMode
     http_endpoint: str | None
     started_by: str | None
+    proc_start_epoch: float
 
 
 class OwnershipError(RuntimeError):
@@ -65,6 +70,101 @@ def is_pid_alive(pid: int) -> bool:
     return True
 
 
+def get_process_start_time(pid: int) -> float | None:
+    """Return the kernel-reported process start time as epoch seconds.
+
+    Supported on Linux (``/proc``) and macOS (``ps lstart``). On other
+    platforms — notably Windows — this returns ``None``, so the identity
+    check is skipped and stale-lock detection falls back to the PID-only
+    liveness check (the pre-#253 behavior). Windows process-identity
+    verification is deferred per Issue #253's acceptance criteria.
+    """
+    if pid <= 0:
+        return None
+    if sys.platform.startswith("linux"):
+        return _get_process_start_time_linux(pid)
+    if sys.platform == "darwin":
+        return _get_process_start_time_macos(pid)
+    return None
+
+
+def _get_process_start_time_linux(pid: int) -> float | None:
+    try:
+        stat_text = (_PROC_ROOT / str(pid) / "stat").read_text(encoding="utf-8")
+        proc_stat_text = (_PROC_ROOT / "stat").read_text(encoding="utf-8")
+        ticks_per_second = os.sysconf("SC_CLK_TCK")
+    except (OSError, ValueError):
+        return None
+
+    if not isinstance(ticks_per_second, int) or ticks_per_second <= 0:
+        return None
+
+    try:
+        after_comm = stat_text.rsplit(")", 1)[1].strip()
+        fields = after_comm.split()
+        start_ticks = int(fields[19])
+    except (IndexError, ValueError):
+        return None
+
+    boot_time: int | None = None
+    for line in proc_stat_text.splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[0] == "btime":
+            try:
+                boot_time = int(parts[1])
+            except ValueError:
+                return None
+            break
+    if boot_time is None:
+        return None
+
+    return float(boot_time) + (float(start_ticks) / float(ticks_per_second))
+
+
+def _get_process_start_time_macos(pid: int) -> float | None:
+    env = os.environ.copy()
+    env["LC_ALL"] = "C"
+    try:
+        result = subprocess.run(
+            ["ps", "-o", "lstart=", "-p", str(pid)],
+            capture_output=True,
+            check=False,
+            env=env,
+            text=True,
+        )
+    except OSError:
+        return None
+
+    output = result.stdout.strip()
+    if not output:
+        return None
+
+    line = output.splitlines()[0].strip()
+    try:
+        started = datetime.strptime(line, "%a %b %d %H:%M:%S %Y")
+    except ValueError:
+        return None
+    return started.timestamp()
+
+
+def _coerce_proc_start_epoch(value: object) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    proc_start_epoch = float(value)
+    if not math.isfinite(proc_start_epoch):
+        return None
+    return proc_start_epoch
+
+
+def _process_identity_matches(pid: int, expected_start: float | None) -> bool:
+    if expected_start is None:
+        return True
+    actual_start = get_process_start_time(pid)
+    if actual_start is None:
+        return True
+    return abs(actual_start - expected_start) <= PROC_START_TOLERANCE_SECONDS
+
+
 def _is_pid_alive_windows(pid: int) -> bool:
     import ctypes
     import ctypes.wintypes
@@ -152,6 +252,11 @@ def read_lock(path: Path = LOCK_PATH) -> LockInfo | None:
         if started_by is None or isinstance(started_by, str):
             info["started_by"] = started_by
 
+    if "proc_start_epoch" in raw:
+        proc_start_epoch = _coerce_proc_start_epoch(raw["proc_start_epoch"])
+        if proc_start_epoch is not None:
+            info["proc_start_epoch"] = proc_start_epoch
+
     return info
 
 
@@ -178,10 +283,11 @@ def acquire_lock(
 ) -> LockInfo:
     """Acquire the ownership lock. Raise OwnershipError on refuse.
 
-    The default stdio-mode call writes the original #177 lock shape so
-    older lock readers and ``stackchan-mcp --check`` output remain
-    compatible. Daemon transports can attach optional metadata for
-    diagnostics without changing the atomic hardlink claim.
+    The default stdio-mode call writes the original #177 lock base fields
+    plus additive process identity metadata. Older lock readers remain
+    compatible because the new field is optional JSON. Daemon transports
+    can attach optional metadata for diagnostics without changing the
+    atomic hardlink claim.
     """
     if mode not in ("stdio", "streamable-http"):
         raise ValueError(f"unsupported lock mode: {mode!r}")
@@ -195,25 +301,39 @@ def acquire_lock(
         existing = read_lock(path)
         if existing is not None:
             if is_pid_alive(existing["pid"]):
-                raise OwnershipError(
-                    "stackchan-mcp: device already owned by "
-                    f"{existing['owner_id']} "
-                    f"(pid {existing['pid']}, since {existing['start_ts']})"
+                if _process_identity_matches(
+                    existing["pid"], existing.get("proc_start_epoch")
+                ):
+                    raise OwnershipError(
+                        "stackchan-mcp: device already owned by "
+                        f"{existing['owner_id']} "
+                        f"(pid {existing['pid']}, since {existing['start_ts']})"
+                    )
+                print(
+                    "stackchan-mcp: removed stale lock from recycled pid "
+                    f"{existing['pid']}",
+                    file=sys.stderr,
+                )
+            else:
+                print(
+                    "stackchan-mcp: removed stale lock from dead pid "
+                    f"{existing['pid']}",
+                    file=sys.stderr,
                 )
-            print(
-                f"stackchan-mcp: removed stale lock from dead pid {existing['pid']}",
-                file=sys.stderr,
-            )
             path.unlink(missing_ok=True)
         elif path.exists():
             path.unlink()
 
+        pid = os.getpid()
+        proc_start_epoch = get_process_start_time(pid)
         info: LockInfo = {
             "owner_id": owner_id,
-            "pid": os.getpid(),
+            "pid": pid,
             "start_ts": _now_iso(),
             "host": socket.gethostname(),
         }
+        if proc_start_epoch is not None:
+            info["proc_start_epoch"] = proc_start_epoch
         if mode != "stdio":
             info["mode"] = mode
         if http_endpoint is not None:
@@ -246,8 +366,9 @@ def release_lock_if_owner(info: LockInfo, path: Path = LOCK_PATH) -> bool:
     """Remove the lock file only if it still belongs to ``info``.
 
     Returns ``True`` if the lock was removed, ``False`` if the on-disk
-    lock has a different ``owner_id`` / ``pid`` / ``start_ts`` or no
-    longer exists. This is the owner-scoped counterpart to
+    lock has a different ``owner_id`` / ``pid`` / ``start_ts`` /
+    ``proc_start_epoch`` or no longer exists. This is the owner-scoped
+    counterpart to
     :func:`release_lock` and is intended for cleanup paths (``finally``
     blocks, ``atexit.register``) where the caller may have lost ownership
     between claim and cleanup — for example after the gateway exited and
@@ -263,6 +384,12 @@ def release_lock_if_owner(info: LockInfo, path: Path = LOCK_PATH) -> bool:
         or existing.get("start_ts") != info.get("start_ts")
     ):
         return False
+    if (
+        "proc_start_epoch" in existing
+        and "proc_start_epoch" in info
+        and existing["proc_start_epoch"] != info["proc_start_epoch"]
+    ):
+        return False
     try:
         path.unlink()
         return True