stackchan-mcp 0.6.0__tar.gz → 0.8.0__tar.gz

{stackchan_mcp-0.6.0 → stackchan_mcp-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.6.0
+Version: 0.8.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

{stackchan_mcp-0.6.0 → stackchan_mcp-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.6.0"
+version = "0.8.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"

{stackchan_mcp-0.6.0 → stackchan_mcp-0.8.0}/stackchan_mcp/esp32_client.py

@@ -7,6 +7,7 @@ and as an MCP client that sends commands TO the ESP32.
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Sequence
 import json
 import logging
 import os
@@ -25,6 +26,34 @@ logger = logging.getLogger(__name__)
 # Timeout for waiting for ESP32 responses
 RESPONSE_TIMEOUT = 10.0
 
+ToolCall = tuple[str, dict[str, Any]]
+ToolCallResult = tuple[Any, dict[str, Any] | None]
+
+_TOOL_LANES = {
+    "self.robot.": "servo",
+    "self.led.": "led",
+    "self.display.": "avatar",
+    "self.screen.": "display",
+    "self.audio_speaker.": "audio",
+    "self.camera.": "camera",
+    "self.touch.": "touch",
+    "self.get_device_status": "status",
+}
+
+
+def _hardware_lane(tool_name: str) -> str:
+    """Return the hardware lane used for per-peripheral dispatch ordering."""
+    for prefix, lane in _TOOL_LANES.items():
+        if tool_name.startswith(prefix):
+            return lane
+    return "default"
+
+
+def _retrieve_future_exception(future: asyncio.Future[Any]) -> None:
+    """Mark a completed Future exception as observed, if it has one."""
+    if future.done() and not future.cancelled():
+        future.exception()
+
 
 class ESP32Connection:
     """Manages a single ESP32 device connection."""
@@ -75,14 +104,18 @@ class ESP32Connection:
         self._pending[req_id] = future
 
         try:
-            await self._ws.send(json.dumps(message))
+            await self._ws_send(json.dumps(message))
             response = await asyncio.wait_for(future, timeout=RESPONSE_TIMEOUT)
             return parse_jsonrpc_response(response)
+        except asyncio.CancelledError:
+            self._pending.pop(req_id, None)
+            raise
         except asyncio.TimeoutError:
             self._pending.pop(req_id, None)
             return None, {"code": -32000, "message": f"Timeout waiting for ESP32 response (method={method})"}
         except Exception as exc:
             self._pending.pop(req_id, None)
+            _retrieve_future_exception(future)
             return None, {"code": -32000, "message": f"ESP32 communication error: {exc}"}
 
     async def initialize(self, vision_url: str = "", vision_token: str = "") -> bool:
@@ -285,6 +318,17 @@ class ESP32Manager:
         # observable from gateway code; if a full-duplex contract
         # ever lands later the lock can split again.
         self._listen_lock = self._tts_lock
+        self._tool_lane_locks = {
+            "servo": asyncio.Lock(),
+            "led": asyncio.Lock(),
+            "avatar": asyncio.Lock(),
+            "display": asyncio.Lock(),
+            "audio": asyncio.Lock(),
+            "camera": asyncio.Lock(),
+            "touch": asyncio.Lock(),
+            "status": asyncio.Lock(),
+            "default": asyncio.Lock(),
+        }
 
     @property
     def device_connected(self) -> bool:
@@ -481,13 +525,55 @@ class ESP32Manager:
 
     async def call_tool(
         self, name: str, arguments: dict[str, Any]
-    ) -> tuple[Any, dict[str, Any] | None]:
+    ) -> ToolCallResult:
         """Call a tool on the connected ESP32 device."""
+        result = await self.call_tools([(name, arguments)])
+        return result[0]
+
+    async def call_tools(self, calls: Sequence[ToolCall]) -> list[ToolCallResult]:
+        """Call multiple ESP32 tools while preserving per-hardware ordering.
+
+        Existing single-tool callers should continue to use ``call_tool``.
+        This helper is for compound gateway flows that can safely overlap
+        hardware-independent peripherals, such as servo + LEDs + avatar.
+        Calls sharing the same hardware lane are serialized; calls on
+        different lanes are dispatched concurrently.
+        """
+        if not calls:
+            return []
         if not self._connection or not self._connection.connected:
-            return None, {"code": -32000, "message": "No ESP32 device connected"}
+            return [
+                (None, {"code": -32000, "message": "No ESP32 device connected"})
+                for _ in calls
+            ]
         if not self._connection.initialized:
-            return None, {"code": -32000, "message": "ESP32 not initialized"}
-        return await self._connection.call_tool(name, arguments)
+            return [
+                (None, {"code": -32000, "message": "ESP32 not initialized"})
+                for _ in calls
+            ]
+
+        connection = self._connection
+        return list(
+            await asyncio.gather(
+                *(
+                    self._call_tool_on_connection(connection, name, arguments)
+                    for name, arguments in calls
+                )
+            )
+        )
+
+    async def _call_tool_on_connection(
+        self,
+        connection: ESP32Connection,
+        name: str,
+        arguments: dict[str, Any],
+    ) -> ToolCallResult:
+        lane = _hardware_lane(name)
+        lock = self._tool_lane_locks[lane]
+        async with lock:
+            if connection is not self._connection or not connection.connected:
+                return None, {"code": -32000, "message": "ESP32 not connected"}
+            return await connection.call_tool(name, arguments)
 
     async def send_audio_frame(self, opus_frame: bytes) -> None:
         """Push a single Opus frame to the connected device.

{stackchan_mcp-0.6.0 → stackchan_mcp-0.8.0}/stackchan_mcp/stdio_server.py

@@ -103,8 +103,14 @@ def create_server() -> Server:
             Tool(
                 name="move_head",
                 description=(
-                    "Move the robot's head to the specified angles. "
-                    "yaw: horizontal (-90 to 90), pitch: vertical (-30 to 30)."
+                    "Move the robot's head to safe, recommended angles. "
+                    "yaw: horizontal (-90 to 90), pitch: vertical (5 to 85, "
+                    "the M5Stack-recommended operating range). Out-of-range "
+                    "requests are rejected at this MCP layer; for advanced "
+                    "callers that need the firmware hard clamp (pitch 0..88), "
+                    "use the firmware-side `set_head_angles` device tool, "
+                    "which exposes a permissive schema and the authoritative "
+                    "two-tier guard described in the README."
                 ),
                 inputSchema={
                     "type": "object",
@@ -112,10 +118,19 @@ def create_server() -> Server:
                         "yaw": {
                             "type": "integer",
                             "description": "Horizontal angle in degrees (-90 to 90)",
+                            "minimum": -90,
+                            "maximum": 90,
                         },
                         "pitch": {
                             "type": "integer",
-                            "description": "Vertical angle in degrees (-30 to 30)",
+                            "description": (
+                                "Vertical angle in degrees (5 to 85, "
+                                "M5Stack-recommended operating range). For the "
+                                "wider firmware hard clamp (0..88), use the "
+                                "`set_head_angles` device tool instead."
+                            ),
+                            "minimum": 5,
+                            "maximum": 85,
                         },
                     },
                     "required": ["yaw", "pitch"],
@@ -281,6 +296,77 @@ def create_server() -> Server:
                     "required": ["enabled"],
                 },
             ),
+            Tool(
+                name="set_servo_torque",
+                description=(
+                    "Enable or disable SCS0009 servo torque on the yaw / "
+                    "pitch axes independently. Disabling torque stops motor "
+                    "current on that axis; the head holds via static "
+                    "friction (no motion is commanded). On disable, the "
+                    "firmware also cancels any in-flight MotionDriver "
+                    "interpolation and marks the axis position unknown so "
+                    "a subsequent same-target set_head_angles is re-"
+                    "dispatched rather than no-op-optimized. Re-enabling "
+                    "torque does NOT trigger a move; the next "
+                    "set_head_angles or wobble call will. Diagnostic / "
+                    "power-management primitive used to observe physical "
+                    "head behavior under torque-off (Issue #163; auto "
+                    "release on idle is Issue #152 Phase 4)."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "yaw_enabled": {
+                            "type": "boolean",
+                            "description": (
+                                "True to enable yaw axis torque, false to "
+                                "disable."
+                            ),
+                        },
+                        "pitch_enabled": {
+                            "type": "boolean",
+                            "description": (
+                                "True to enable pitch axis torque, false "
+                                "to disable."
+                            ),
+                        },
+                    },
+                    "required": ["yaw_enabled", "pitch_enabled"],
+                },
+            ),
+            Tool(
+                name="set_auto_torque_release",
+                description=(
+                    "Enable or disable firmware-side automatic SCS0009 "
+                    "torque release after motion idle timeout. timeout_ms "
+                    "is clamped by the firmware to 500..600000 ms. "
+                    "Disabling this setting does not re-enable torque if "
+                    "it is already released; the next set_head_angles, "
+                    "wobble, or explicit set_servo_torque(true, true) call "
+                    "re-engages torque."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "enabled": {
+                            "type": "boolean",
+                            "description": (
+                                "True to enable idle auto-release, false "
+                                "to disable it."
+                            ),
+                        },
+                        "timeout_ms": {
+                            "type": "integer",
+                            "description": (
+                                "Idle timeout in milliseconds. Values "
+                                "outside 500..600000 are clamped by the "
+                                "firmware handler."
+                            ),
+                        },
+                    },
+                    "required": ["enabled", "timeout_ms"],
+                },
+            ),
             Tool(
                 name="get_touch_state",
                 description=(
@@ -422,6 +508,9 @@ def create_server() -> Server:
                     "minimal firmware change to handle the inbound 'listen' "
                     "wire type (paired with this gateway release). Engine is "
                     "selectable via 'engine' (default 'faster-whisper', local). "
+                    "Optional 'motion' feedback can switch the avatar to "
+                    "'thinking' during capture ('face-only') or tilt the head "
+                    "up while preserving yaw ('look-up'). "
                     "Install the relevant extra "
                     "('pip install stackchan-mcp[stt-faster-whisper]' or "
                     "'stt-openai'); calling this tool before an engine is "
@@ -465,6 +554,29 @@ def create_server() -> Server:
                                 "fall back to their default when omitted."
                             ),
                         },
+                        "motion": {
+                            "type": "string",
+                            "enum": ["none", "face-only", "look-up"],
+                            "description": (
+                                "Optional visible feedback during capture. "
+                                "'none' preserves the previous behaviour. "
+                                "'face-only' shows the thinking avatar during "
+                                "capture and restores idle at the end. "
+                                "'look-up' preserves yaw, tilts pitch to "
+                                "look_up_pitch, and holds the pose on success."
+                            ),
+                            "default": "none",
+                        },
+                        "look_up_pitch": {
+                            "type": "number",
+                            "description": (
+                                "Pitch angle for motion='look-up'. Must be "
+                                "between 5 and 85 degrees."
+                            ),
+                            "default": 50.0,
+                            "minimum": 5,
+                            "maximum": 85,
+                        },
                     },
                 },
             ),
@@ -526,6 +638,59 @@ def create_server() -> Server:
                 )
             ]
 
+        if name == "move_head":
+            # Belt-and-suspenders validation for the recommended pitch range.
+            # The Tool inputSchema already declares minimum/maximum for both
+            # yaw and pitch, but mcp Python SDK server-side enforcement of
+            # JSON Schema bounds is not guaranteed across versions and
+            # clients. Reject out-of-recommended values here as a clean
+            # MCP error JSON before any motion command reaches the device.
+            # Callers that genuinely need the firmware hard clamp 0..88
+            # should use the firmware-side `set_head_angles` device tool,
+            # which exposes the authoritative two-tier guard described in
+            # the README "Y-axis (pitch) safe range" section.
+            yaw_val = arguments.get("yaw")
+            pitch_val = arguments.get("pitch")
+            if (
+                not isinstance(yaw_val, int)
+                or isinstance(yaw_val, bool)
+                or not (-90 <= yaw_val <= 90)
+            ):
+                return [
+                    TextContent(
+                        type="text",
+                        text=json.dumps(
+                            {
+                                "error": (
+                                    "yaw must be an integer in -90..90 "
+                                    f"(got {yaw_val!r})"
+                                )
+                            }
+                        ),
+                    )
+                ]
+            if (
+                not isinstance(pitch_val, int)
+                or isinstance(pitch_val, bool)
+                or not (5 <= pitch_val <= 85)
+            ):
+                return [
+                    TextContent(
+                        type="text",
+                        text=json.dumps(
+                            {
+                                "error": (
+                                    "pitch must be an integer in 5..85 "
+                                    "(M5Stack-recommended operating range; "
+                                    "for the wider firmware hard clamp "
+                                    "0..88 use `set_head_angles`). got "
+                                    f"{pitch_val!r}"
+                                )
+                            }
+                        ),
+                    )
+                ]
+
         # Map MCP client tool names to ESP32 MCP tool names (self.* prefix)
         tool_map: dict[str, tuple[str, dict[str, Any]]] = {
             "get_device_info": (
@@ -583,6 +748,14 @@ def create_server() -> Server:
                 "self.display.set_blink",
                 arguments,
             ),
+            "set_servo_torque": (
+                "self.robot.set_servo_torque",
+                arguments,
+            ),
+            "set_auto_torque_release": (
+                "self.robot.set_auto_torque_release",
+                arguments,
+            ),
             "get_touch_state": (
                 "self.touch.get_touch_state",
                 {},