stackchan-mcp 0.12.0__tar.gz → 0.13.0__tar.gz

{stackchan_mcp-0.12.0 → stackchan_mcp-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.12.0
+Version: 0.13.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
@@ -25,9 +25,11 @@ Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.10
 Requires-Dist: aiohttp>=3
 Requires-Dist: mcp<2.0,>=1.27
+Requires-Dist: platformdirs<5.0,>=4.0
 Requires-Dist: pydantic>=2
 Requires-Dist: python-dotenv
 Requires-Dist: pyyaml>=6
+Requires-Dist: tomli<3.0,>=2.0; python_version < '3.11'
 Requires-Dist: websockets>=12
 Requires-Dist: zeroconf>=0.149
 Provides-Extra: stt

{stackchan_mcp-0.12.0 → stackchan_mcp-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.12.0"
+version = "0.13.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"
@@ -34,6 +34,8 @@ dependencies = [
     "pydantic>=2",
     "python-dotenv",
     "PyYAML>=6",
+    "platformdirs>=4.0,<5.0",
+    "tomli>=2.0,<3.0; python_version < '3.11'",
     # The stdio server captures the active ServerSession via a subclassed
     # Server.run() loop because the public MCP SDK does not yet expose a
     # stable hook for server-side notifications. That subclass relies on

{stackchan_mcp-0.12.0 → stackchan_mcp-0.13.0}/stackchan_mcp/cli.py

@@ -745,6 +745,10 @@ def _configure_gateway_startup() -> None:
         format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
     )
 
+    from .user_defaults import log_user_defaults_startup
+
+    log_user_defaults_startup()
+
 
 def _acquire_startup_lock(
     *,

{stackchan_mcp-0.12.0 → stackchan_mcp-0.13.0}/stackchan_mcp/stdio_server.py

@@ -21,6 +21,7 @@ from mcp.types import Notification, TextContent, Tool
 from . import __version__
 from .gateway import get_gateway
 from .notify_config import NotifyConfig, load_notify_config
+from .user_defaults import resolve_default
 from .stt import listen_and_transcribe
 from .tts import synthesize_and_send
 
@@ -388,30 +389,64 @@ async def _handle_follow_pose_stream(
     if not (url.startswith("ws://") or url.startswith("wss://")):
         return _follow_pose_error("url must start with ws:// or wss://")
 
-    flip_yaw = arguments.get("flip_yaw", 1)
+    tool_name = "stackchan_follow_pose_stream"
+
+    flip_yaw = (
+        arguments["flip_yaw"]
+        if "flip_yaw" in arguments
+        else resolve_default(tool_name, "flip_yaw", 1)
+    )
     if not _is_int_arg(flip_yaw) or flip_yaw not in (-1, 1):
         return _follow_pose_error("flip_yaw must be -1 or 1")
 
-    flip_pitch = arguments.get("flip_pitch", 1)
+    flip_pitch = (
+        arguments["flip_pitch"]
+        if "flip_pitch" in arguments
+        else resolve_default(tool_name, "flip_pitch", 1)
+    )
     if not _is_int_arg(flip_pitch) or flip_pitch not in (-1, 1):
         return _follow_pose_error("flip_pitch must be -1 or 1")
 
-    pitch_center_deg = arguments.get("pitch_center_deg", 45)
+    pitch_center_deg = (
+        arguments["pitch_center_deg"]
+        if "pitch_center_deg" in arguments
+        else resolve_default(tool_name, "pitch_center_deg", 45)
+    )
     if (
         not _is_int_arg(pitch_center_deg)
         or not 5 <= pitch_center_deg <= 85
     ):
         return _follow_pose_error("pitch_center_deg must be an integer in 5..85")
 
-    downsample_hz = arguments.get("downsample_hz", 20.0)
-    if not _is_number_arg(downsample_hz) or not 0 < downsample_hz <= 60:
-        return _follow_pose_error("downsample_hz must be a number in (0, 60]")
+    smoothing_window = (
+        arguments["smoothing_window"]
+        if "smoothing_window" in arguments
+        else resolve_default(tool_name, "smoothing_window", 5)
+    )
+    if not _is_int_arg(smoothing_window) or not 1 <= smoothing_window <= 20:
+        return _follow_pose_error("smoothing_window must be an integer in 1..20")
+
+    downsample_hz = (
+        arguments["downsample_hz"]
+        if "downsample_hz" in arguments
+        else resolve_default(tool_name, "downsample_hz", 20.0)
+    )
+    if not _is_number_arg(downsample_hz) or not 0 < downsample_hz <= 20:
+        return _follow_pose_error("downsample_hz must be a number in (0, 20]")
 
-    max_step_deg = arguments.get("max_step_deg", 12.0)
+    max_step_deg = (
+        arguments["max_step_deg"]
+        if "max_step_deg" in arguments
+        else resolve_default(tool_name, "max_step_deg", 12.0)
+    )
     if not _is_number_arg(max_step_deg) or not 0 < max_step_deg <= 30:
         return _follow_pose_error("max_step_deg must be a number in (0, 30]")
 
-    speed_dps = arguments.get("speed_dps", 240)
+    speed_dps = (
+        arguments["speed_dps"]
+        if "speed_dps" in arguments
+        else resolve_default(tool_name, "speed_dps", 240)
+    )
     if not _is_int_arg(speed_dps) or not 1 <= speed_dps <= 240:
         return _follow_pose_error("speed_dps must be an integer in 1..240")
 
@@ -429,6 +464,7 @@ async def _handle_follow_pose_stream(
         flip_yaw=flip_yaw,
         flip_pitch=flip_pitch,
         pitch_center_deg=pitch_center_deg,
+        smoothing_window=smoothing_window,
         downsample_hz=float(downsample_hz),
         max_step_deg=float(max_step_deg),
         speed_dps=speed_dps,
@@ -610,6 +646,14 @@ async def _dispatch_mcp_tool(
             "self.gateway_config.set",
             arguments,
         ),
+        "get_touch_sensor_enabled": (
+            "self.robot.get_touch_sensor_enabled",
+            {},
+        ),
+        "set_touch_sensor_enabled": (
+            "self.robot.set_touch_sensor_enabled",
+            arguments,
+        ),
         "set_avatar": (
             "self.display.set_avatar",
             arguments,
@@ -927,15 +971,29 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                                 "anchor. Defaults to the head's neutral pose."
                             ),
                         },
+                        "smoothing_window": {
+                            "type": "integer",
+                            "default": 5,
+                            "minimum": 1,
+                            "maximum": 20,
+                            "description": (
+                                "Moving-average window size for incoming sensor "
+                                "frames. 1 = passthrough (disable gateway-side "
+                                "smoothing). Default 5."
+                            ),
+                        },
                         "downsample_hz": {
                             "type": "number",
                             "default": 20,
                             "exclusiveMinimum": 0,
-                            "maximum": 60,
+                            "maximum": 20,
                             "description": (
                                 "Cap servo command rate. Recent frames are "
                                 "smoothed; commands are issued at most this "
-                                "frequently."
+                                "frequently. Capped at 20 to match the "
+                                "SCS0009 servo's observed sustained WritePos "
+                                "rate; higher continuous rates can trigger "
+                                "UART hang."
                             ),
                         },
                         "max_step_deg": {
@@ -1062,6 +1120,38 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                     },
                 },
             ),
+            Tool(
+                name="get_touch_sensor_enabled",
+                description=(
+                    "Read the device's NVS-backed head-touch sensor enable "
+                    "flag. When disabled, the firmware stops both the local "
+                    "motion response and the MCP stackchan/event emission; "
+                    "the setting persists across reboot."
+                ),
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="set_touch_sensor_enabled",
+                description=(
+                    "Enable or disable the device's head-touch sensor at "
+                    "runtime. The NVS-backed setting persists across reboot. "
+                    "Disabling stops both the firmware local motion response "
+                    "and the MCP stackchan/event emission."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "enabled": {
+                            "type": "boolean",
+                            "description": (
+                                "True to enable tap/stroke detection; false "
+                                "to disable local reactions and event emission."
+                            ),
+                        },
+                    },
+                    "required": ["enabled"],
+                },
+            ),
             Tool(
                 name="set_avatar",
                 description=(
@@ -1516,10 +1606,22 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                         "speaker_id": {
                             "type": "integer",
                             "description": (
-                                "Engine-specific speaker identifier "
+                                "Engine-specific numeric speaker identifier "
                                 "(e.g. a VOICEVOX speaker ID)."
                             ),
                         },
+                        "speaker_name": {
+                            "type": "string",
+                            "description": (
+                                "Engine-specific string speaker/voice "
+                                "identifier (e.g. an Edge TTS voice name "
+                                "such as 'en-US-AriaNeural'). Distinct from "
+                                "'voice', which selects the engine itself "
+                                "(e.g. 'edge-tts'); use speaker_name for "
+                                "engines whose speaker selector is a string "
+                                "name rather than the numeric speaker_id."
+                            ),
+                        },
                         "reference_audio": {
                             "type": "string",
                             "description": (
@@ -1644,7 +1746,12 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                     "address, then read' patterns, use `i2c_write_read` "
                     "instead. Returns "
                     "{\"ok\": true, \"bytes\": [...]} or "
-                    "{\"ok\": false, \"error\": \"ESP_ERR_TIMEOUT\"} on NACK."
+                    "{\"ok\": false, \"error\": \"ESP_ERR_TIMEOUT\"} on NACK. "
+                    "Optional `scl_speed_hz` (default 400000) sets the I2C "
+                    "clock for this transaction; lower it (e.g. 100000 or "
+                    "200000) for slower Units such as the RCWL-9620 "
+                    "ultrasonic ranger that fail at 400 kHz with "
+                    "ESP_ERR_INVALID_STATE."
                 ),
                 inputSchema={
                     "type": "object",
@@ -1665,6 +1772,19 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                             "minimum": 1,
                             "maximum": 256,
                         },
+                        "scl_speed_hz": {
+                            "type": "integer",
+                            "default": 400000,
+                            "description": (
+                                "I2C clock for this transaction. Default "
+                                "400000; lower it (e.g. 100000 or 200000) "
+                                "for slower Units such as the RCWL-9620 "
+                                "ultrasonic ranger that fail at 400 kHz "
+                                "with ESP_ERR_INVALID_STATE."
+                            ),
+                            "minimum": 100000,
+                            "maximum": 1000000,
+                        },
                     },
                     "required": ["addr", "n_bytes"],
                 },
@@ -1676,7 +1796,11 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                     "on Grove Port A. `bytes` is an array of integers "
                     "(0..255). This tool operates on the external Port A "
                     "bus only; on-board ICs (PMIC, AW9523, touch, etc.) "
-                    "on the internal bus are not reachable."
+                    "on the internal bus are not reachable. Optional "
+                    "`scl_speed_hz` (default 400000) sets the I2C clock for "
+                    "this transaction; lower it (e.g. 100000 or 200000) for "
+                    "slower Units such as the RCWL-9620 ultrasonic ranger "
+                    "that fail at 400 kHz with ESP_ERR_INVALID_STATE."
                 ),
                 inputSchema={
                     "type": "object",
@@ -1700,6 +1824,19 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                                 "maximum": 255,
                             },
                         },
+                        "scl_speed_hz": {
+                            "type": "integer",
+                            "default": 400000,
+                            "description": (
+                                "I2C clock for this transaction. Default "
+                                "400000; lower it (e.g. 100000 or 200000) "
+                                "for slower Units such as the RCWL-9620 "
+                                "ultrasonic ranger that fail at 400 kHz "
+                                "with ESP_ERR_INVALID_STATE."
+                            ),
+                            "minimum": 100000,
+                            "maximum": 1000000,
+                        },
                     },
                     "required": ["addr", "bytes"],
                 },
@@ -1712,7 +1849,11 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                     "single Repeated Start transaction. Common 'set "
                     "register pointer, then read' idiom: pass "
                     "write_bytes=[reg_addr] to read from a specific "
-                    "register."
+                    "register. Optional `scl_speed_hz` (default 400000) "
+                    "sets the I2C clock for this transaction; lower it "
+                    "(e.g. 100000 or 200000) for slower Units such as the "
+                    "RCWL-9620 ultrasonic ranger that fail at 400 kHz with "
+                    "ESP_ERR_INVALID_STATE."
                 ),
                 inputSchema={
                     "type": "object",
@@ -1745,6 +1886,19 @@ def create_server(notify_config: NotifyConfig | None = None) -> StackChanServer:
                             "minimum": 1,
                             "maximum": 256,
                         },
+                        "scl_speed_hz": {
+                            "type": "integer",
+                            "default": 400000,
+                            "description": (
+                                "I2C clock for this transaction. Default "
+                                "400000; lower it (e.g. 100000 or 200000) "
+                                "for slower Units such as the RCWL-9620 "
+                                "ultrasonic ranger that fail at 400 kHz "
+                                "with ESP_ERR_INVALID_STATE."
+                            ),
+                            "minimum": 100000,
+                            "maximum": 1000000,
+                        },
                     },
                     "required": ["addr", "write_bytes", "n_bytes"],
                 },

{stackchan_mcp-0.12.0 → stackchan_mcp-0.13.0}/stackchan_mcp/tts/__init__.py

@@ -54,8 +54,15 @@ def _register_irodori() -> None:
     get_registry().register(IrodoriEngine())
 
 
+def _register_edge_tts() -> None:
+    from .edge_tts import EdgeTTSEngine
+
+    get_registry().register(EdgeTTSEngine())
+
+
 _try_register(_register_voicevox, "voicevox")
 _try_register(_register_irodori, "irodori")
+_try_register(_register_edge_tts, "edge-tts")
 
 
 __all__ = [

stackchan_mcp-0.13.0/stackchan_mcp/tts/edge_tts.py

@@ -0,0 +1,158 @@
+"""Edge TTS engine — subprocess client for Microsoft's online TTS service.
+
+Uses the `edge-tts` Python package's CLI (https://github.com/rany2/edge-tts)
+to synthesise speech via Microsoft's online TTS service. No local model or
+Docker container needed — just `pip install edge-tts` and the `edge-tts`
+binary on PATH. Produces natural English (and many other language) voices,
+unlike VOICEVOX which is Japanese-only by default.
+
+edge-tts always emits MP3 regardless of the output filename/extension
+passed to --write-media, so this engine pipes that MP3 through ffmpeg to
+get raw 16 kHz mono PCM.
+
+This is intentionally a subprocess-based engine (not an HTTP client like
+VoicevoxEngine) since edge-tts ships as a CLI tool, not a long-running
+server.
+
+Configuration (environment variables):
+
+    STACKCHAN_EDGE_TTS_DEFAULT_VOICE
+        Voice name used when the say() tool does not specify one via
+        speaker_name. Default "en-GB-SoniaNeural". Read lazily on each
+        access (not cached at import/construction time) so a .env file
+        loaded after engine registration — e.g. under
+        `serve --transport streamable-http`, where the tts package import
+        chain resolves before _configure_gateway_startup() loads .env —
+        still takes effect.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .audio_utils import DEVICE_SAMPLE_RATE
+from .base import TTSEngine
+
+logger = logging.getLogger(__name__)
+
+
+#: Default voice. en-GB-SoniaNeural is a natural British English voice.
+DEFAULT_EDGE_TTS_VOICE = "en-GB-SoniaNeural"
+
+#: Timeout for the edge-tts subprocess and the ffmpeg conversion step.
+DEFAULT_SUBPROCESS_TIMEOUT_SECONDS = 30.0
+
+
+class EdgeTTSEngine(TTSEngine):
+    """Synthesise text via the edge-tts CLI, return 16 kHz mono PCM.
+
+    Setup: `pip install edge-tts` (already on PATH as `edge-tts` once
+    installed) and `ffmpeg` on PATH for MP3 -> PCM conversion.
+    """
+
+    name = "edge-tts"
+
+    def __init__(
+        self,
+        default_voice: str | None = None,
+        timeout_seconds: float = DEFAULT_SUBPROCESS_TIMEOUT_SECONDS,
+        edge_tts_binary: str | None = None,
+        ffmpeg_binary: str | None = None,
+    ) -> None:
+        # Only the explicit constructor override is stored here. The
+        # STACKCHAN_EDGE_TTS_DEFAULT_VOICE environment variable is
+        # intentionally NOT read in __init__ — see default_voice below
+        # and the module docstring for why.
+        self._default_voice_override = default_voice
+        self._timeout_seconds = timeout_seconds
+        self._edge_tts_binary = edge_tts_binary or "edge-tts"
+        self._ffmpeg_binary = ffmpeg_binary or "ffmpeg"
+
+    @property
+    def default_voice(self) -> str:
+        """Voice name used when no voice is specified per-call.
+
+        Resolved lazily on every access: explicit constructor override
+        wins, otherwise STACKCHAN_EDGE_TTS_DEFAULT_VOICE is read fresh
+        from the environment, falling back to DEFAULT_EDGE_TTS_VOICE.
+        """
+        if self._default_voice_override is not None:
+            return self._default_voice_override
+        return os.getenv("STACKCHAN_EDGE_TTS_DEFAULT_VOICE") or DEFAULT_EDGE_TTS_VOICE
+
+    async def synthesize(self, text: str, **opts: Any) -> bytes:
+        """Run edge-tts + ffmpeg, return 16 kHz mono signed-16-bit PCM.
+
+        Recognised opts:
+
+            speaker_name: str
+                Edge TTS voice name (e.g. "en-GB-SoniaNeural",
+                "en-US-AriaNeural"). Falls back to `default_voice`. This
+                is distinct from the say() tool's `voice` argument, which
+                selects the engine itself (e.g. "edge-tts"); speaker_name
+                is the string equivalent of VOICEVOX's numeric
+                speaker_id, for engines whose speaker selector is a name.
+            speaker_id: int | None
+                Ignored. Accepted only so the orchestrator can pass a
+                uniform argument set across engines without raising.
+        """
+        if not text:
+            raise ValueError("text must not be empty")
+
+        speaker_name = opts.get("speaker_name")
+        voice = speaker_name if isinstance(speaker_name, str) and speaker_name else self.default_voice
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            mp3_path = Path(tmpdir) / "out.mp3"
+            pcm_path = Path(tmpdir) / "out.pcm"
+
+            proc = await asyncio.create_subprocess_exec(
+                self._edge_tts_binary,
+                "--voice", voice,
+                "--text", text,
+                "--write-media", str(mp3_path),
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            _, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=self._timeout_seconds
+            )
+            if proc.returncode != 0:
+                raise RuntimeError(
+                    f"edge-tts failed (code {proc.returncode}): "
+                    f"{stderr.decode(errors='replace')}"
+                )
+
+            ffmpeg_proc = await asyncio.create_subprocess_exec(
+                self._ffmpeg_binary, "-nostdin", "-y", "-i", str(mp3_path),
+                "-f", "s16le", "-ar", str(DEVICE_SAMPLE_RATE), "-ac", "1",
+                str(pcm_path),
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            _, ffmpeg_stderr = await asyncio.wait_for(
+                ffmpeg_proc.communicate(), timeout=self._timeout_seconds
+            )
+            if ffmpeg_proc.returncode != 0:
+                raise RuntimeError(
+                    f"ffmpeg conversion failed (code {ffmpeg_proc.returncode}): "
+                    f"{ffmpeg_stderr.decode(errors='replace')}"
+                )
+
+            pcm = pcm_path.read_bytes()
+
+        logger.info(
+            "edge-tts synthesised %d bytes PCM (16 kHz mono) for "
+            "voice=%s, text=%r",
+            len(pcm),
+            voice,
+            text[:60],
+        )
+        return pcm

{stackchan_mcp-0.12.0 → stackchan_mcp-0.13.0}/stackchan_mcp/tts/orchestrator.py

@@ -238,6 +238,7 @@ async def synthesize_and_send(
         )
 
     speaker_id = arguments.get("speaker_id")
+    speaker_name = arguments.get("speaker_name")
     reference_audio = arguments.get("reference_audio")
 
     tts_text = text
@@ -308,6 +309,7 @@ async def synthesize_and_send(
         pcm = await engine.synthesize(
             tts_text,
             speaker_id=speaker_id,
+            speaker_name=speaker_name,
             reference_audio=reference_audio,
         )
     except ValueError: