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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.6.0
+Version: 0.7.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.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.6.0"
+version = "0.7.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.7.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"],
@@ -422,6 +437,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 +483,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 +567,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": (