stackchan-mcp 0.3.0__tar.gz → 0.4.0__tar.gz

{stackchan_mcp-0.3.0 → stackchan_mcp-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.3.0
+Version: 0.4.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
@@ -114,6 +114,29 @@ will notice the dropped WebSocket and retry while idle. The retry delay starts
 at 5 seconds and backs off up to 60 seconds. After the gateway is listening
 again, check `get_status` from the stdio MCP side to confirm the device is back.
 
+## Configuration changes
+
+The gateway reads `.env` once at process start. Because the gateway runs as a
+**stdio MCP server** (it has no standalone CLI mode beyond `--help` /
+`--version` / `--check`), editing `.env` while it is connected to an MCP
+client does not take effect on the running process — and killing the gateway
+process directly will not auto-restart it; the MCP client owns the lifecycle.
+
+After editing `.env` (for example to update `STACKCHAN_TOKEN`, `VISION_URL`,
+or `VISION_TOKEN`):
+
+1. Reconnect the MCP client. In Claude Code this is `/mcp` to reconnect, or a
+   full Claude Code restart.
+2. Confirm `mcp__stackchan-mcp__get_status` returns `connected: true` with the
+   expected `tools_count`.
+3. If the ESP32 was already connected with a stale auth credential, hard-reset
+   the device (`esptool.py --before default_reset --after hard_reset chip_id`,
+   or DTR/RTS toggle via pyserial) so it reconnects with the fresh
+   configuration.
+
+`STACKCHAN_TOKEN` takes precedence over the legacy `BEARER_TOKEN`; setting
+either is enough, but if you have both, keep them aligned.
+
 ## Tests
 
 ```bash
@@ -165,7 +188,8 @@ Same shape, under `mcpServers`.
 | `get_touch_state` | Touch sensor state (press/release/stroke) |
 | `set_avatar(face)` | Switch avatar expression (`idle` / `happy` / `thinking` / `sad` / `surprised` / `embarrassed`), or `off` to hide the avatar and disable blink so the underlying xiaozhi-esp32 screens (WiFi config UI, OTA, settings) are visible. A subsequent `set_avatar(<other face>)` brings it back and restores blink. |
 | `set_blink(state)` | Blink animation on/off |
-| `set_mouth(state)` | Mouth shape (`closed` / `half` / `open` / `e` / `u`) |
+| `set_mouth(state)` | Mouth shape (`closed` / `half` / `open` / `e` / `u`), one-shot, held until next call |
+| `set_mouth_sequence(steps)` | Queue and play a list of `{shape, duration_ms}` steps locally for TTS lip-sync. The firmware walks the queue without per-step network RTT. Calling `set_mouth`, `set_avatar`, or this tool again interrupts the in-flight sequence; autonomous blink is paused while a sequence is playing. |
 | `check_vm_en` | Read PY32 VM EN GPIO state (servo power supply diagnostic) |
 
 The mapping from these names to ESP32-side `self.*` MCP tools is in

{stackchan_mcp-0.3.0 → stackchan_mcp-0.4.0}/README.md

@@ -83,6 +83,29 @@ will notice the dropped WebSocket and retry while idle. The retry delay starts
 at 5 seconds and backs off up to 60 seconds. After the gateway is listening
 again, check `get_status` from the stdio MCP side to confirm the device is back.
 
+## Configuration changes
+
+The gateway reads `.env` once at process start. Because the gateway runs as a
+**stdio MCP server** (it has no standalone CLI mode beyond `--help` /
+`--version` / `--check`), editing `.env` while it is connected to an MCP
+client does not take effect on the running process — and killing the gateway
+process directly will not auto-restart it; the MCP client owns the lifecycle.
+
+After editing `.env` (for example to update `STACKCHAN_TOKEN`, `VISION_URL`,
+or `VISION_TOKEN`):
+
+1. Reconnect the MCP client. In Claude Code this is `/mcp` to reconnect, or a
+   full Claude Code restart.
+2. Confirm `mcp__stackchan-mcp__get_status` returns `connected: true` with the
+   expected `tools_count`.
+3. If the ESP32 was already connected with a stale auth credential, hard-reset
+   the device (`esptool.py --before default_reset --after hard_reset chip_id`,
+   or DTR/RTS toggle via pyserial) so it reconnects with the fresh
+   configuration.
+
+`STACKCHAN_TOKEN` takes precedence over the legacy `BEARER_TOKEN`; setting
+either is enough, but if you have both, keep them aligned.
+
 ## Tests
 
 ```bash
@@ -134,7 +157,8 @@ Same shape, under `mcpServers`.
 | `get_touch_state` | Touch sensor state (press/release/stroke) |
 | `set_avatar(face)` | Switch avatar expression (`idle` / `happy` / `thinking` / `sad` / `surprised` / `embarrassed`), or `off` to hide the avatar and disable blink so the underlying xiaozhi-esp32 screens (WiFi config UI, OTA, settings) are visible. A subsequent `set_avatar(<other face>)` brings it back and restores blink. |
 | `set_blink(state)` | Blink animation on/off |
-| `set_mouth(state)` | Mouth shape (`closed` / `half` / `open` / `e` / `u`) |
+| `set_mouth(state)` | Mouth shape (`closed` / `half` / `open` / `e` / `u`), one-shot, held until next call |
+| `set_mouth_sequence(steps)` | Queue and play a list of `{shape, duration_ms}` steps locally for TTS lip-sync. The firmware walks the queue without per-step network RTT. Calling `set_mouth`, `set_avatar`, or this tool again interrupts the in-flight sequence; autonomous blink is paused while a sequence is playing. |
 | `check_vm_en` | Read PY32 VM EN GPIO state (servo power supply diagnostic) |
 
 The mapping from these names to ESP32-side `self.*` MCP tools is in

{stackchan_mcp-0.3.0 → stackchan_mcp-0.4.0}/pyproject.toml

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

@@ -184,7 +184,9 @@ def create_server() -> Server:
                 description=(
                     "Set the avatar mouth shape for lip-sync. "
                     "The shape is held until the next set_avatar / set_mouth call, "
-                    "or until an autonomous blink restores the resting face."
+                    "or until an autonomous blink restores the resting face. "
+                    "Calling this while a set_mouth_sequence is in flight "
+                    "interrupts the sequence."
                 ),
                 inputSchema={
                     "type": "object",
@@ -198,6 +200,68 @@ def create_server() -> Server:
                     "required": ["mouth"],
                 },
             ),
+            Tool(
+                name="set_mouth_sequence",
+                description=(
+                    "Queue a lip-sync sequence and play it on the device. "
+                    "Each step holds 'shape' for 'duration_ms' before "
+                    "advancing. The firmware walks the queue locally so "
+                    "there is no per-step network RTT (use this instead of "
+                    "issuing many set_mouth calls back-to-back from a TTS "
+                    "loop). Returns immediately with the queued step count "
+                    "and estimated total duration. Calling set_mouth, "
+                    "set_avatar, or this tool again interrupts the in-flight "
+                    "sequence and replaces it. Autonomous blink is paused "
+                    "while a sequence is playing and resumed when it ends. "
+                    "The final shape is held until the next "
+                    "set_mouth / set_avatar call, or until an autonomous "
+                    "blink restores the resting face — this is the same "
+                    "Phase 2 trade-off that applies to set_mouth, since the "
+                    "blink animation ends by repainting the full face. If "
+                    "the final shape must persist visually, disable blink "
+                    "with set_blink(false) before the sequence (or append a "
+                    "closed step if you just want the mouth to close at "
+                    "the end)."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "steps": {
+                            "type": "array",
+                            "minItems": 1,
+                            "maxItems": 256,
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "shape": {
+                                        "type": "string",
+                                        "enum": ["closed", "half", "open", "e", "u"],
+                                        "description": (
+                                            "Mouth shape for this step. "
+                                            "One of: closed, half, open, e, u."
+                                        ),
+                                    },
+                                    "duration_ms": {
+                                        "type": "integer",
+                                        "minimum": 10,
+                                        "maximum": 10000,
+                                        "description": (
+                                            "How long to hold this shape "
+                                            "before advancing, in ms (10..10000)."
+                                        ),
+                                    },
+                                },
+                                "required": ["shape", "duration_ms"],
+                            },
+                            "description": (
+                                "Ordered list of mouth shapes with hold "
+                                "durations (1..256 steps)."
+                            ),
+                        },
+                    },
+                    "required": ["steps"],
+                },
+            ),
             Tool(
                 name="set_blink",
                 description=(
@@ -294,6 +358,13 @@ def create_server() -> Server:
                 "self.display.set_mouth",
                 arguments,
             ),
+            # The MCP Property type system on ESP32 only supports
+            # string/integer/boolean, so we serialise the steps array to
+            # a JSON string here. The firmware decodes it via cJSON.
+            "set_mouth_sequence": (
+                "self.display.set_mouth_sequence",
+                {"steps_json": json.dumps(arguments.get("steps", []))},
+            ),
             "set_blink": (
                 "self.display.set_blink",
                 arguments,

stackchan_mcp-0.4.0/tests/test_stdio_server.py

@@ -0,0 +1,148 @@
+"""Tests for stdio MCP server tool definitions."""
+
+import json
+
+import pytest
+from mcp.types import CallToolRequest, ListToolsRequest
+
+from stackchan_mcp.stdio_server import create_server
+
+
+def test_create_server():
+    """Server creation succeeds with correct name."""
+    server = create_server()
+    assert server is not None
+    assert server.name == "stackchan-mcp"
+
+
+@pytest.mark.asyncio
+async def test_list_tools_includes_get_head_angles():
+    """get_head_angles is exposed to MCP clients."""
+    server = create_server()
+
+    result = await server.request_handlers[ListToolsRequest](
+        ListToolsRequest(method="tools/list")
+    )
+
+    tool_names = [tool.name for tool in result.root.tools]
+    assert "get_head_angles" in tool_names
+
+
+@pytest.mark.asyncio
+async def test_get_head_angles_relays_to_esp32(monkeypatch):
+    """get_head_angles maps to the ESP32 self.robot.get_head_angles tool."""
+    calls = []
+
+    class FakeESP32:
+        device_connected = True
+
+        async def call_tool(self, name, arguments):
+            calls.append((name, arguments))
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": json.dumps({"yaw": 12, "pitch": -3}),
+                    }
+                ],
+            }, None
+
+    class FakeGateway:
+        esp32 = FakeESP32()
+
+    import stackchan_mcp.stdio_server as stdio_server
+
+    monkeypatch.setattr(stdio_server, "get_gateway", lambda: FakeGateway())
+    server = create_server()
+
+    result = await server.request_handlers[CallToolRequest](
+        CallToolRequest(
+            method="tools/call",
+            params={"name": "get_head_angles", "arguments": {}},
+        )
+    )
+
+    assert calls == [("self.robot.get_head_angles", {})]
+    assert json.loads(result.root.content[0].text) == {"yaw": 12, "pitch": -3}
+
+
+@pytest.mark.asyncio
+async def test_list_tools_includes_set_mouth_sequence():
+    """set_mouth_sequence is exposed to MCP clients with an array schema."""
+    server = create_server()
+
+    result = await server.request_handlers[ListToolsRequest](
+        ListToolsRequest(method="tools/list")
+    )
+
+    tool = next((t for t in result.root.tools if t.name == "set_mouth_sequence"), None)
+    assert tool is not None, "set_mouth_sequence tool should be registered"
+
+    schema = tool.inputSchema
+    assert schema["properties"]["steps"]["type"] == "array"
+    assert schema["properties"]["steps"]["minItems"] == 1
+    assert schema["properties"]["steps"]["maxItems"] == 256
+
+    item_schema = schema["properties"]["steps"]["items"]
+    assert item_schema["properties"]["shape"]["enum"] == [
+        "closed",
+        "half",
+        "open",
+        "e",
+        "u",
+    ]
+    assert item_schema["properties"]["duration_ms"]["minimum"] == 10
+    assert item_schema["properties"]["duration_ms"]["maximum"] == 10000
+    assert set(item_schema["required"]) == {"shape", "duration_ms"}
+
+
+@pytest.mark.asyncio
+async def test_set_mouth_sequence_relays_steps_as_json_string(monkeypatch):
+    """set_mouth_sequence serialises steps to JSON for the firmware.
+
+    The ESP32 MCP Property type system only supports string/integer/boolean,
+    so the gateway flattens the steps array to a JSON string under
+    `steps_json` before forwarding to self.display.set_mouth_sequence.
+    """
+    calls = []
+
+    class FakeESP32:
+        device_connected = True
+
+        async def call_tool(self, name, arguments):
+            calls.append((name, arguments))
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": json.dumps(
+                            {"ok": True, "queued_steps": 2, "estimated_duration_ms": 160}
+                        ),
+                    }
+                ],
+            }, None
+
+    class FakeGateway:
+        esp32 = FakeESP32()
+
+    import stackchan_mcp.stdio_server as stdio_server
+
+    monkeypatch.setattr(stdio_server, "get_gateway", lambda: FakeGateway())
+    server = create_server()
+
+    steps = [
+        {"shape": "open", "duration_ms": 80},
+        {"shape": "closed", "duration_ms": 80},
+    ]
+    await server.request_handlers[CallToolRequest](
+        CallToolRequest(
+            method="tools/call",
+            params={"name": "set_mouth_sequence", "arguments": {"steps": steps}},
+        )
+    )
+
+    assert len(calls) == 1
+    name, arguments = calls[0]
+    assert name == "self.display.set_mouth_sequence"
+    assert set(arguments.keys()) == {"steps_json"}
+    assert json.loads(arguments["steps_json"]) == steps

{stackchan_mcp-0.3.0 → stackchan_mcp-0.4.0}/uv.lock

@@ -1313,7 +1313,7 @@ wheels = [
 
 [[package]]
 name = "stackchan-mcp"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

stackchan_mcp-0.3.0/tests/test_stdio_server.py

@@ -1,66 +0,0 @@
-"""Tests for stdio MCP server tool definitions."""
-
-import json
-
-import pytest
-from mcp.types import CallToolRequest, ListToolsRequest
-
-from stackchan_mcp.stdio_server import create_server
-
-
-def test_create_server():
-    """Server creation succeeds with correct name."""
-    server = create_server()
-    assert server is not None
-    assert server.name == "stackchan-mcp"
-
-
-@pytest.mark.asyncio
-async def test_list_tools_includes_get_head_angles():
-    """get_head_angles is exposed to MCP clients."""
-    server = create_server()
-
-    result = await server.request_handlers[ListToolsRequest](
-        ListToolsRequest(method="tools/list")
-    )
-
-    tool_names = [tool.name for tool in result.root.tools]
-    assert "get_head_angles" in tool_names
-
-
-@pytest.mark.asyncio
-async def test_get_head_angles_relays_to_esp32(monkeypatch):
-    """get_head_angles maps to the ESP32 self.robot.get_head_angles tool."""
-    calls = []
-
-    class FakeESP32:
-        device_connected = True
-
-        async def call_tool(self, name, arguments):
-            calls.append((name, arguments))
-            return {
-                "content": [
-                    {
-                        "type": "text",
-                        "text": json.dumps({"yaw": 12, "pitch": -3}),
-                    }
-                ],
-            }, None
-
-    class FakeGateway:
-        esp32 = FakeESP32()
-
-    import stackchan_mcp.stdio_server as stdio_server
-
-    monkeypatch.setattr(stdio_server, "get_gateway", lambda: FakeGateway())
-    server = create_server()
-
-    result = await server.request_handlers[CallToolRequest](
-        CallToolRequest(
-            method="tools/call",
-            params={"name": "get_head_angles", "arguments": {}},
-        )
-    )
-
-    assert calls == [("self.robot.get_head_angles", {})]
-    assert json.loads(result.root.content[0].text) == {"yaw": 12, "pitch": -3}