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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.7.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.7.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.7.0 → stackchan_mcp-0.8.0}/stackchan_mcp/stdio_server.py

@@ -296,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=(
@@ -677,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",
                 {},

{stackchan_mcp-0.7.0 → stackchan_mcp-0.8.0}/tests/test_audio_utils.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import array
+import importlib
 
 import pytest
 
@@ -206,8 +207,8 @@ def test_chunk_pcm_into_frames_rejects_non_positive_size():
 
 def test_encode_opus_frames_produces_frames_when_libopus_available():
     """When libopus is reachable, encode_opus_frames yields one frame per chunk."""
-    opuslib = pytest.importorskip("opuslib")
     try:
+        opuslib = importlib.import_module("opuslib")
         opuslib.Encoder(16000, 1, opuslib.APPLICATION_VOIP)
     except Exception as exc:  # libopus not loadable
         pytest.skip(f"libopus not available: {exc}")

{stackchan_mcp-0.7.0 → stackchan_mcp-0.8.0}/tests/test_esp32_client.py

@@ -1,13 +1,14 @@
 """Tests for ESP32 client connection management."""
 
 import asyncio
+import gc
 import json
 
 import pytest
 import pytest_asyncio
 import websockets
 
-from stackchan_mcp.esp32_client import ESP32Connection, ESP32Manager
+from stackchan_mcp.esp32_client import ESP32Connection, ESP32Manager, _hardware_lane
 
 
 @pytest_asyncio.fixture
@@ -223,6 +224,242 @@ async def test_auth_rejection(manager):
         del os.environ["STACKCHAN_TOKEN"]
 
 
+# ---------------------------------------------------------------------------
+# Parallel hardware-lane dispatch (Issue #73)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("tool_name", "lane"),
+    [
+        ("self.robot.set_head_angles", "servo"),
+        ("self.led.set_many", "led"),
+        ("self.display.set_avatar", "avatar"),
+        ("self.screen.set_brightness", "display"),
+        ("self.audio_speaker.set_volume", "audio"),
+        ("self.camera.take_photo", "camera"),
+        ("self.touch.get_touch_state", "touch"),
+        ("self.get_device_status", "status"),
+        ("self.unknown.experimental", "default"),
+    ],
+)
+def test_hardware_lane_covers_gateway_tool_routes(tool_name, lane):
+    """Gateway-routed ESP32 tools map to explicit hardware lanes."""
+    assert _hardware_lane(tool_name) == lane
+
+
+@pytest.mark.asyncio
+async def test_connection_pipelines_concurrent_tool_calls_before_first_response():
+    """Concurrent tools/call requests are sent before either response arrives."""
+    ws = _FakeWebSocket()
+    conn = ESP32Connection(ws, session_id="session-parallel")  # type: ignore[arg-type]
+
+    servo_task = asyncio.create_task(
+        conn.call_tool("self.robot.set_head_angles", {"yaw": 10, "pitch": 30})
+    )
+    led_task = asyncio.create_task(
+        conn.call_tool("self.led.set_many", {"colors": "[[255, 0, 0]]"})
+    )
+
+    await asyncio.sleep(0)
+
+    assert len(ws.sent) == 2
+    sent_messages = [json.loads(message) for message in ws.sent]
+    request_ids = [message["payload"]["id"] for message in sent_messages]
+    assert [message["payload"]["method"] for message in sent_messages] == [
+        "tools/call",
+        "tools/call",
+    ]
+    assert [message["payload"]["params"]["name"] for message in sent_messages] == [
+        "self.robot.set_head_angles",
+        "self.led.set_many",
+    ]
+
+    conn.handle_response(
+        {
+            "jsonrpc": "2.0",
+            "id": request_ids[1],
+            "result": {"content": [{"type": "text", "text": "led"}]},
+        }
+    )
+    conn.handle_response(
+        {
+            "jsonrpc": "2.0",
+            "id": request_ids[0],
+            "result": {"content": [{"type": "text", "text": "servo"}]},
+        }
+    )
+
+    servo_result, led_result = await asyncio.gather(servo_task, led_task)
+    assert servo_result[0]["content"][0]["text"] == "servo"
+    assert servo_result[1] is None
+    assert led_result[0]["content"][0]["text"] == "led"
+    assert led_result[1] is None
+
+
+@pytest.mark.asyncio
+async def test_connection_removes_pending_request_when_call_is_cancelled():
+    """Cancelling a tool call does not leave a stale pending response slot."""
+    ws = _FakeWebSocket()
+    conn = ESP32Connection(ws, session_id="session-cancel")  # type: ignore[arg-type]
+
+    task = asyncio.create_task(
+        conn.call_tool("self.robot.set_head_angles", {"yaw": 10, "pitch": 30})
+    )
+
+    await asyncio.sleep(0)
+    assert len(ws.sent) == 1
+    assert len(conn._pending) == 1
+
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+
+    assert conn._pending == {}
+
+
+class _GateableConnection:
+    """Fake initialized connection with per-tool release gates."""
+
+    connected = True
+    initialized = True
+
+    def __init__(self, releases: dict[str, asyncio.Event]) -> None:
+        self.releases = releases
+        self.started: list[str] = []
+        self.finished: list[str] = []
+        self.all_started = asyncio.Event()
+
+    async def call_tool(self, name, arguments):  # noqa: ARG002 - test fake
+        self.started.append(name)
+        if len(self.started) >= len(self.releases):
+            self.all_started.set()
+        await self.releases[name].wait()
+        self.finished.append(name)
+        return {"content": [{"type": "text", "text": name}]}, None
+
+
+@pytest.mark.asyncio
+async def test_manager_call_tools_dispatches_independent_lanes_in_parallel():
+    """Servo, LED, and avatar calls start together instead of waiting in line."""
+    releases = {
+        "self.robot.set_head_angles": asyncio.Event(),
+        "self.led.set_many": asyncio.Event(),
+        "self.display.set_avatar": asyncio.Event(),
+    }
+    connection = _GateableConnection(releases)
+    mgr = ESP32Manager()
+    mgr._connection = connection  # type: ignore[assignment]
+
+    task = asyncio.create_task(
+        mgr.call_tools(
+            [
+                ("self.robot.set_head_angles", {"yaw": 0, "pitch": 45}),
+                ("self.led.set_many", {"colors": "[]"}),
+                ("self.display.set_avatar", {"face": "happy"}),
+            ]
+        )
+    )
+
+    await asyncio.wait_for(connection.all_started.wait(), timeout=1.0)
+    assert connection.started == [
+        "self.robot.set_head_angles",
+        "self.led.set_many",
+        "self.display.set_avatar",
+    ]
+    assert connection.finished == []
+
+    for release in releases.values():
+        release.set()
+    results = await asyncio.wait_for(task, timeout=1.0)
+
+    assert [result[0]["content"][0]["text"] for result in results] == [
+        "self.robot.set_head_angles",
+        "self.led.set_many",
+        "self.display.set_avatar",
+    ]
+    assert [error for _, error in results] == [None, None, None]
+
+
+@pytest.mark.asyncio
+async def test_manager_call_tool_uses_lane_dispatch_for_existing_api():
+    """Existing single-tool API can still overlap independent hardware lanes."""
+    releases = {
+        "self.robot.set_head_angles": asyncio.Event(),
+        "self.led.set_many": asyncio.Event(),
+    }
+    connection = _GateableConnection(releases)
+    mgr = ESP32Manager()
+    mgr._connection = connection  # type: ignore[assignment]
+
+    servo_task = asyncio.create_task(
+        mgr.call_tool("self.robot.set_head_angles", {"yaw": 0, "pitch": 45})
+    )
+    led_task = asyncio.create_task(
+        mgr.call_tool("self.led.set_many", {"colors": "[]"})
+    )
+
+    await asyncio.wait_for(connection.all_started.wait(), timeout=1.0)
+    assert connection.started == [
+        "self.robot.set_head_angles",
+        "self.led.set_many",
+    ]
+    assert connection.finished == []
+
+    for release in releases.values():
+        release.set()
+    results = await asyncio.wait_for(
+        asyncio.gather(servo_task, led_task),
+        timeout=1.0,
+    )
+
+    assert [result[0]["content"][0]["text"] for result in results] == [
+        "self.robot.set_head_angles",
+        "self.led.set_many",
+    ]
+    assert [error for _, error in results] == [None, None]
+
+
+@pytest.mark.asyncio
+async def test_manager_call_tools_serializes_calls_on_same_hardware_lane():
+    """Two servo calls keep their relative order on the servo lane."""
+    releases = {
+        "self.robot.set_head_angles": asyncio.Event(),
+        "self.robot.get_head_angles": asyncio.Event(),
+    }
+    connection = _GateableConnection(releases)
+    mgr = ESP32Manager()
+    mgr._connection = connection  # type: ignore[assignment]
+
+    task = asyncio.create_task(
+        mgr.call_tools(
+            [
+                ("self.robot.set_head_angles", {"yaw": 0, "pitch": 45}),
+                ("self.robot.get_head_angles", {}),
+            ]
+        )
+    )
+
+    await asyncio.sleep(0)
+    await asyncio.sleep(0)
+    assert connection.started == ["self.robot.set_head_angles"]
+
+    releases["self.robot.set_head_angles"].set()
+    await asyncio.sleep(0)
+    await asyncio.sleep(0)
+    assert connection.started == [
+        "self.robot.set_head_angles",
+        "self.robot.get_head_angles",
+    ]
+
+    releases["self.robot.get_head_angles"].set()
+    await asyncio.wait_for(task, timeout=1.0)
+    assert connection.finished == [
+        "self.robot.set_head_angles",
+        "self.robot.get_head_angles",
+    ]
+
+
 # ---------------------------------------------------------------------------
 # send_audio_frame (TTS pipeline egress, Issue #70 PR2)
 # ---------------------------------------------------------------------------
@@ -443,6 +680,32 @@ async def test_send_tts_state_translates_oserror_to_connection_error():
     assert not conn.connected
 
 
+@pytest.mark.asyncio
+async def test_send_mcp_request_translates_send_failure_and_marks_disconnected():
+    """tools/call send failures use the same connection-state handling as TTS."""
+    ws = _FailingWebSocket(OSError("broken pipe"))
+    conn = ESP32Connection(ws, session_id="session-1")  # type: ignore[arg-type]
+    loop = asyncio.get_running_loop()
+    loop_errors = []
+    previous_handler = loop.get_exception_handler()
+
+    loop.set_exception_handler(lambda _loop, context: loop_errors.append(context))
+    try:
+        result, error = await conn.call_tool("self.robot.set_head_angles", {})
+        gc.collect()
+        await asyncio.sleep(0)
+    finally:
+        loop.set_exception_handler(previous_handler)
+
+    assert result is None
+    assert error is not None
+    assert "WebSocket send failed" in error["message"]
+    assert not conn.connected
+    assert conn._pending == {}
+    assert ws.send_calls == 1
+    assert loop_errors == []
+
+
 def test_connection_default_protocol_version_is_one():
     """Fresh ESP32Connection defaults to WebSocket protocol v1.
 

{stackchan_mcp-0.7.0 → stackchan_mcp-0.8.0}/uv.lock

@@ -2009,7 +2009,7 @@ wheels = [
 
 [[package]]
 name = "stackchan-mcp"
-version = "0.7.0"
+version = "0.8.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },