stackchan-mcp 0.1.0__py3-none-any.whl

stackchan_mcp/handlers/camera.py

@@ -0,0 +1,25 @@
+"""Camera handler: take_photo via ESP32 relay."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+async def take_photo(esp32_call) -> dict[str, Any]:
+    """Take a photo via ESP32 camera.
+
+    Args:
+        esp32_call: async callable (name, arguments) -> (result, error)
+
+    Returns:
+        MCP result content.
+    """
+    result, error = await esp32_call(
+        "self.camera.take_photo", {}
+    )
+    if error:
+        raise RuntimeError(f"take_photo failed: {error.get('message', str(error))}")
+    return result

stackchan_mcp/handlers/robot.py

@@ -0,0 +1,52 @@
+"""Robot handlers: servo and LED (stub implementation with in-memory state)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..tools import SetHeadAnglesParams, SetLedColorParams
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# In-memory device state
+# ---------------------------------------------------------------------------
+
+_head_angles: dict[str, int] = {"yaw": 0, "pitch": 0}
+_led_color: dict[str, int] = {"r": 0, "g": 0, "b": 0}
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+def get_head_angles(_args: dict[str, Any] | None = None) -> dict[str, int]:
+    """Return current head angles."""
+    logger.info("get_head_angles -> %s", _head_angles)
+    return dict(_head_angles)
+
+
+def set_head_angles(args: dict[str, Any]) -> bool:
+    """Set head angles (in-memory stub)."""
+    params = SetHeadAnglesParams(**args)
+    _head_angles["yaw"] = params.yaw
+    _head_angles["pitch"] = params.pitch
+    logger.info(
+        "set_head_angles yaw=%d pitch=%d speed=%d",
+        params.yaw,
+        params.pitch,
+        params.speed,
+    )
+    return True
+
+
+def set_led_color(args: dict[str, Any]) -> bool:
+    """Set LED color (in-memory stub)."""
+    params = SetLedColorParams(**args)
+    _led_color["r"] = params.r
+    _led_color["g"] = params.g
+    _led_color["b"] = params.b
+    logger.info("set_led_color r=%d g=%d b=%d", params.r, params.g, params.b)
+    return True

stackchan_mcp/mcp_router.py

@@ -0,0 +1,126 @@
+"""JSON-RPC 2.0 router for MCP protocol.
+
+Handles: initialize, tools/list, tools/call
+
+In gateway mode, tools/call is relayed to the ESP32 device.
+For testing without ESP32, use route() with local stub handlers.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from .tools import TOOL_DEFINITIONS
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# MCP server capabilities
+# ---------------------------------------------------------------------------
+
+SERVER_INFO = {
+    "name": "stackchan-mcp",
+    "version": "0.1.0",
+}
+
+SERVER_CAPABILITIES = {
+    "tools": {},
+}
+
+
+# ---------------------------------------------------------------------------
+# JSON-RPC helpers
+# ---------------------------------------------------------------------------
+
+
+def _ok(req_id: Any, result: Any) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": req_id, "result": result}
+
+
+def _error(req_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": req_id,
+        "error": {"code": code, "message": message},
+    }
+
+
+# ---------------------------------------------------------------------------
+# Router (local stub mode for testing)
+# ---------------------------------------------------------------------------
+
+# Lazy import to avoid circular dependency
+_TOOL_HANDLERS: dict[str, Any] | None = None
+
+
+def _get_tool_handlers() -> dict[str, Any]:
+    global _TOOL_HANDLERS
+    if _TOOL_HANDLERS is None:
+        from .handlers.audio import set_volume
+        from .handlers.robot import get_head_angles, set_head_angles, set_led_color
+
+        _TOOL_HANDLERS = {
+            "self.robot.get_head_angles": get_head_angles,
+            "self.robot.set_head_angles": set_head_angles,
+            "self.robot.set_led_color": set_led_color,
+            "self.audio_speaker.set_volume": set_volume,
+        }
+    return _TOOL_HANDLERS
+
+
+def route(payload: dict[str, Any]) -> dict[str, Any]:
+    """Route a single JSON-RPC 2.0 request and return a response dict.
+
+    This is the local stub mode — tool calls are handled in-process.
+    """
+    req_id = payload.get("id")
+    method = payload.get("method", "")
+    params = payload.get("params", {})
+
+    logger.info("mcp method=%s id=%s", method, req_id)
+
+    if method == "initialize":
+        return _ok(
+            req_id,
+            {
+                "protocolVersion": "2024-11-05",
+                "serverInfo": SERVER_INFO,
+                "capabilities": SERVER_CAPABILITIES,
+            },
+        )
+
+    if method == "tools/list":
+        return _ok(req_id, {"tools": TOOL_DEFINITIONS})
+
+    if method == "tools/call":
+        tool_name = params.get("name", "")
+        arguments = params.get("arguments", {})
+        handlers = _get_tool_handlers()
+        handler = handlers.get(tool_name)
+
+        if handler is None:
+            return _error(req_id, -32601, f"Unknown tool: {tool_name}")
+
+        try:
+            result = handler(arguments) if arguments else handler()
+            return _ok(
+                req_id,
+                {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": json.dumps(result)
+                            if not isinstance(result, str)
+                            else result,
+                        }
+                    ],
+                },
+            )
+        except Exception as exc:
+            logger.exception("tools/call %s failed", tool_name)
+            return _error(req_id, -32000, str(exc))
+
+    return _error(req_id, -32601, f"Method not found: {method}")

stackchan_mcp/protocol.py

@@ -0,0 +1,95 @@
+"""xiaozhi-esp32 protocol definitions.
+
+Defines message formats for communication between the gateway and ESP32 device.
+Based on: xiaozhi-esp32/docs/mcp-protocol.md
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Transport-level messages (hello handshake)
+# ---------------------------------------------------------------------------
+
+
+class AudioParams(BaseModel):
+    format: str = "opus"
+    sample_rate: int = 16000
+    channels: int = 1
+    frame_duration: int = 60
+
+
+class HelloMessage(BaseModel):
+    """ESP32 -> Gateway: hello (connection announcement)."""
+
+    type: str = "hello"
+    version: int = 1
+    features: dict[str, Any] = Field(default_factory=lambda: {"mcp": True})
+    transport: str = "websocket"
+    audio_params: AudioParams = Field(default_factory=AudioParams)
+    session_id: str | None = None
+
+
+class HelloResponse(BaseModel):
+    """Gateway -> ESP32: hello response."""
+
+    type: str = "hello"
+    version: int = 1
+    transport: str = "websocket"
+    session_id: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# MCP message wrapper (over transport)
+# ---------------------------------------------------------------------------
+
+
+class McpMessage(BaseModel):
+    """MCP message wrapper for transport.
+
+    All MCP communication is wrapped in this envelope.
+    """
+
+    session_id: str = ""
+    type: str = "mcp"
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# JSON-RPC 2.0 helpers
+# ---------------------------------------------------------------------------
+
+
+def make_jsonrpc_request(method: str, params: dict[str, Any], req_id: int) -> dict[str, Any]:
+    """Create a JSON-RPC 2.0 request payload."""
+    return {
+        "jsonrpc": "2.0",
+        "method": method,
+        "params": params,
+        "id": req_id,
+    }
+
+
+def make_mcp_message(
+    session_id: str, method: str, params: dict[str, Any], req_id: int
+) -> dict[str, Any]:
+    """Create a full MCP transport message with JSON-RPC payload."""
+    return {
+        "session_id": session_id,
+        "type": "mcp",
+        "payload": make_jsonrpc_request(method, params, req_id),
+    }
+
+
+def parse_jsonrpc_response(payload: dict[str, Any]) -> tuple[Any, dict[str, Any] | None]:
+    """Parse a JSON-RPC 2.0 response.
+
+    Returns (result, error) — one of them will be None.
+    """
+    if "error" in payload:
+        return None, payload["error"]
+    return payload.get("result"), None

stackchan_mcp/server.py

@@ -0,0 +1,28 @@
+"""WebSocket server for ESP32 connections.
+
+This module is retained for backward compatibility and testing.
+In production, use the Gateway (gateway.py) which orchestrates
+both the ESP32 WebSocket server and the stdio MCP server.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .esp32_client import ESP32Manager
+
+logger = logging.getLogger(__name__)
+
+
+async def run_server(host: str = "0.0.0.0", port: int = 8765) -> None:
+    """Start the ESP32 WebSocket server standalone (for testing)."""
+    manager = ESP32Manager()
+    await manager.start(host, port)
+    logger.info("ESP32 WebSocket server running on ws://%s:%d", host, port)
+
+    # Keep running until interrupted
+    try:
+        import asyncio
+        await asyncio.Future()  # Run forever
+    finally:
+        await manager.stop()

stackchan_mcp/stdio_server.py

@@ -0,0 +1,344 @@
+"""stdio MCP server for MCP client.
+
+Exposes stackchan tools via the MCP Python SDK's stdio transport.
+Each tool call is relayed to the connected ESP32 device.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from .gateway import get_gateway
+
+logger = logging.getLogger(__name__)
+
+
+def create_server() -> Server:
+    """Create and configure the MCP server with tool handlers."""
+    server = Server("stackchan-mcp")
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        """List available stackchan tools.
+
+        Tools prefixed with ESP32 names (self.*) are relayed to the device.
+        get_status is handled locally by the gateway.
+        """
+        return [
+            Tool(
+                name="get_status",
+                description=(
+                    "Get the gateway's connection status: whether ESP32 is connected, "
+                    "device info, and list of available device tools."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                },
+            ),
+            Tool(
+                name="get_device_info",
+                description=(
+                    "Get real-time device information from ESP32: "
+                    "battery level, speaker volume, screen brightness, network status, etc."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                },
+            ),
+            Tool(
+                name="take_photo",
+                description=(
+                    "Take a photo with the robot's camera and ask a question about it. "
+                    "The device captures an image and returns an AI-generated description."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "question": {
+                            "type": "string",
+                            "description": "Question to ask about the photo (e.g. 'What do you see?')",
+                        },
+                    },
+                    "required": ["question"],
+                },
+            ),
+            Tool(
+                name="set_volume",
+                description="Set the speaker volume (0-100).",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "volume": {
+                            "type": "integer",
+                            "description": "Volume level (0-100)",
+                        },
+                    },
+                    "required": ["volume"],
+                },
+            ),
+            Tool(
+                name="set_brightness",
+                description="Set the screen brightness (0-100).",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "brightness": {
+                            "type": "integer",
+                            "description": "Brightness level (0-100)",
+                        },
+                    },
+                    "required": ["brightness"],
+                },
+            ),
+            Tool(
+                name="move_head",
+                description=(
+                    "Move the robot's head to the specified angles. "
+                    "yaw: horizontal (-90 to 90), pitch: vertical (-30 to 30)."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "yaw": {
+                            "type": "integer",
+                            "description": "Horizontal angle in degrees (-90 to 90)",
+                        },
+                        "pitch": {
+                            "type": "integer",
+                            "description": "Vertical angle in degrees (-30 to 30)",
+                        },
+                    },
+                    "required": ["yaw", "pitch"],
+                },
+            ),
+            Tool(
+                name="get_head_angles",
+                description="Get the robot's current head angles: yaw and pitch in degrees.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                },
+            ),
+            Tool(
+                name="gpio_test",
+                description="Test GPIO6 pin by toggling HIGH/LOW 5 times. Check if servo reacts.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="uart_diag",
+                description="Send raw servo bytes via UART and report write result.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="check_vm_en",
+                description=(
+                    "Diagnostic: read PY32 REG_GPIO_O_L and report whether VM EN "
+                    "(pin 0 = servo power) is currently HIGH. Returns "
+                    "{io_expander_present, i2c_read_ok, raw, vm_en_high}."
+                ),
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            Tool(
+                name="set_avatar",
+                description=(
+                    "Switch the avatar face shown on the LCD. "
+                    "Pick the face that fits the current emotional beat — this is "
+                    "the robot's actual visible expression, not just a label."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "face": {
+                            "type": "string",
+                            "enum": [
+                                "idle",
+                                "happy",
+                                "thinking",
+                                "sad",
+                                "surprised",
+                                "embarrassed",
+                            ],
+                            "description": "One of: idle, happy, thinking, sad, surprised, embarrassed.",
+                        },
+                    },
+                    "required": ["face"],
+                },
+            ),
+            Tool(
+                name="set_mouth",
+                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."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "mouth": {
+                            "type": "string",
+                            "enum": ["closed", "half", "open", "e", "u"],
+                            "description": "One of: closed, half, open, e, u.",
+                        },
+                    },
+                    "required": ["mouth"],
+                },
+            ),
+            Tool(
+                name="set_blink",
+                description=(
+                    "Enable or disable autonomous eye blinking. "
+                    "When enabled, the avatar blinks every 3-6 seconds at random."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "enabled": {
+                            "type": "boolean",
+                            "description": "True to start blinking, false to stop.",
+                        },
+                    },
+                    "required": ["enabled"],
+                },
+            ),
+            Tool(
+                name="get_touch_state",
+                description=(
+                    "Read the head-touch (Si12T) sensor state and the most recent "
+                    "gesture event (tap/stroke/idle). Returns per-zone booleans, "
+                    "the raw output byte, and how long ago the last event fired."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any] | None) -> list[TextContent]:
+        """Handle a tool call by relaying to ESP32."""
+        arguments = arguments or {}
+        gw = get_gateway()
+
+        if name == "get_status":
+            # get_status is handled locally — no ESP32 needed
+            status = gw.esp32.get_status()
+            return [TextContent(type="text", text=json.dumps(status, indent=2))]
+
+        if not gw.esp32.device_connected:
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps({"error": "No ESP32 device connected. Please check the device."}),
+                )
+            ]
+
+        # Map MCP client tool names to ESP32 MCP tool names (self.* prefix)
+        tool_map: dict[str, tuple[str, dict[str, Any]]] = {
+            "get_device_info": (
+                "self.get_device_status",
+                {},
+            ),
+            "take_photo": (
+                "self.camera.take_photo",
+                arguments,
+            ),
+            "set_volume": (
+                "self.audio_speaker.set_volume",
+                arguments,
+            ),
+            "set_brightness": (
+                "self.screen.set_brightness",
+                arguments,
+            ),
+            "move_head": (
+                "self.robot.set_head_angles",
+                arguments,
+            ),
+            "get_head_angles": (
+                "self.robot.get_head_angles",
+                {},
+            ),
+            "gpio_test": (
+                "self.robot.gpio_test",
+                {},
+            ),
+            "uart_diag": (
+                "self.robot.uart_diag",
+                {},
+            ),
+            "check_vm_en": (
+                "self.robot.check_vm_en",
+                {},
+            ),
+            "set_avatar": (
+                "self.display.set_avatar",
+                arguments,
+            ),
+            "set_mouth": (
+                "self.display.set_mouth",
+                arguments,
+            ),
+            "set_blink": (
+                "self.display.set_blink",
+                arguments,
+            ),
+            "get_touch_state": (
+                "self.touch.get_touch_state",
+                {},
+            ),
+        }
+
+        if name not in tool_map:
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps({"error": f"Unknown tool: {name}"}),
+                )
+            ]
+
+        esp32_name, esp32_args = tool_map[name]
+        result, error = await gw.esp32.call_tool(esp32_name, esp32_args)
+
+        if error:
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps({"error": error.get("message", str(error))}),
+                )
+            ]
+
+        # result from ESP32 is MCP format: {"content": [...], "isError": bool}
+        if isinstance(result, dict):
+            content = result.get("content", [])
+            if content and isinstance(content, list):
+                # Pass through content items as text
+                texts = []
+                for item in content:
+                    if isinstance(item, dict) and item.get("type") == "text":
+                        texts.append(item.get("text", ""))
+                if texts:
+                    return [TextContent(type="text", text="\n".join(texts))]
+
+            # Fallback: dump entire result
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+
+        return [TextContent(type="text", text=str(result))]
+
+    return server
+
+
+async def run_stdio_server() -> None:
+    """Run the MCP server on stdio."""
+    server = create_server()
+    async with stdio_server() as (read_stream, write_stream):
+        logger.info("stdio MCP server starting")
+        await server.run(read_stream, write_stream, server.create_initialization_options())