stackchan-mcp 0.1.0__py3-none-any.whl

stackchan_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""stackchan-mcp: Two-faced gateway for StackChan (xiaozhi-esp32).
+
+MCP client side: stdio MCP server (mcp Python SDK)
+ESP32 side: WebSocket server (MCP client over JSON-RPC 2.0)
+"""
+
+__version__ = "0.1.0"

stackchan_mcp/__main__.py

@@ -0,0 +1,12 @@
+"""Entry point: ``python -m stackchan_mcp``.
+
+The actual implementation lives in :mod:`stackchan_mcp.cli` so that the
+console script and ``python -m`` paths share a single side-effect-free
+import surface.
+"""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

stackchan_mcp/audio_stream.py

@@ -0,0 +1,34 @@
+"""Opus audio frame handling — skeleton for Phase 4 (planned).
+
+This module will handle:
+- Incoming Opus frames from the device (STT pipeline)
+- Outgoing Opus frames to the device (TTS pipeline)
+
+For now, binary frames are logged and discarded.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+async def handle_audio_frame(data: bytes, session_id: str) -> None:
+    """Process an incoming binary Opus frame (stub).
+
+    Phase 4 will pipe this into an STT engine.
+    """
+    logger.debug(
+        "audio_frame session=%s bytes=%d (discarded — Phase 4)",
+        session_id,
+        len(data),
+    )
+
+
+async def send_audio_frame(data: bytes) -> bytes:
+    """Prepare an outgoing Opus frame (stub).
+
+    Phase 4 will generate this from a TTS engine.
+    """
+    return data

stackchan_mcp/capture_server.py

@@ -0,0 +1,91 @@
+"""HTTP capture server for receiving photos from ESP32.
+
+ESP32's camera.Explain() POSTs multipart/form-data with:
+- field 'question' (text)
+- field 'file' (camera.jpg, JPEG image)
+
+This server saves the JPEG and returns the file path so MCP client
+can view the image via the Read tool.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+
+from aiohttp import web
+
+logger = logging.getLogger(__name__)
+
+CAPTURE_DIR = os.path.expanduser("~/.stackchan/captures")
+CAPTURE_TOKEN_KEY = web.AppKey("capture_token", str)
+
+
+def _is_authorized(auth_header: str, expected_token: str) -> bool:
+    """Return whether the bearer auth header matches the expected token."""
+    return auth_header == f"Bearer {expected_token}"
+
+
+async def handle_capture(request: web.Request) -> web.Response:
+    """Handle photo upload from ESP32."""
+    expected_token = request.app[CAPTURE_TOKEN_KEY]
+    if expected_token and not _is_authorized(
+        request.headers.get("Authorization", ""), expected_token
+    ):
+        logger.warning("Capture upload auth rejected")
+        return web.Response(
+            text='{"error": "Unauthorized"}',
+            status=401,
+            content_type="application/json",
+        )
+
+    os.makedirs(CAPTURE_DIR, exist_ok=True)
+
+    reader = await request.multipart()
+    question = ""
+    image_path = ""
+
+    async for part in reader:
+        if part.name == "question":
+            question = (await part.read()).decode("utf-8")
+        elif part.name == "file":
+            timestamp = int(time.time() * 1000)
+            filename = f"capture_{timestamp}.jpg"
+            image_path = os.path.join(CAPTURE_DIR, filename)
+            with open(image_path, "wb") as f:
+                while True:
+                    chunk = await part.read_chunk(8192)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+
+    if image_path and os.path.exists(image_path):
+        file_size = os.path.getsize(image_path)
+        logger.info(
+            "Captured photo: %s (%d bytes), question: %s",
+            image_path,
+            file_size,
+            question,
+        )
+        result = json.dumps({
+            "image_path": image_path,
+            "size_bytes": file_size,
+            "question": question,
+        })
+        return web.Response(text=result, content_type="application/json")
+
+    return web.Response(
+        text='{"error": "No image received"}',
+        status=400,
+        content_type="application/json",
+    )
+
+
+def create_capture_app(capture_token: str = "") -> web.Application:
+    """Create the HTTP capture application."""
+    app = web.Application()
+    app[CAPTURE_TOKEN_KEY] = capture_token
+    app.router.add_post("/capture", handle_capture)
+    return app

stackchan_mcp/cli.py

@@ -0,0 +1,57 @@
+"""Console entry point for stackchan-mcp.
+
+This module exists so that `import stackchan_mcp` (or any of its
+submodules) does not trigger import-time side effects like
+`load_dotenv()` or logging configuration. All such side effects live
+inside :func:`main`, which is registered as the `stackchan-mcp`
+console script in ``pyproject.toml`` and is also re-exported through
+``stackchan_mcp.__main__`` so that ``python -m stackchan_mcp`` keeps
+working.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+async def _run() -> None:
+    """Start both the ESP32 WebSocket server and the stdio MCP server."""
+    from .gateway import get_gateway
+    from .stdio_server import run_stdio_server
+
+    gateway = get_gateway()
+
+    await gateway.start()
+    logger.info("Gateway started, waiting for ESP32 connections...")
+
+    try:
+        # Run stdio MCP server (blocks until MCP client disconnects)
+        await run_stdio_server()
+    finally:
+        await gateway.stop()
+
+
+def main() -> None:
+    """Console-script entry point.
+
+    Loads ``.env``, configures logging, and starts the gateway. Side
+    effects are intentionally scoped to this function so that
+    ``import stackchan_mcp`` stays clean.
+    """
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()

stackchan_mcp/esp32_client.py

@@ -0,0 +1,340 @@
+"""ESP32 connection manager.
+
+Acts as a WebSocket server that ESP32 connects TO,
+and as an MCP client that sends commands TO the ESP32.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import uuid
+from typing import Any
+
+import websockets
+from websockets.asyncio.server import ServerConnection
+
+from .protocol import HelloResponse, make_mcp_message, parse_jsonrpc_response
+
+logger = logging.getLogger(__name__)
+
+# Timeout for waiting for ESP32 responses
+RESPONSE_TIMEOUT = 10.0
+
+
+class ESP32Connection:
+    """Manages a single ESP32 device connection."""
+
+    def __init__(self, ws: ServerConnection, session_id: str):
+        self._ws = ws
+        self.session_id = session_id
+        self.device_id: str = "unknown"
+        self.tools: list[dict[str, Any]] = []
+        self._request_id = 0
+        self._pending: dict[int, asyncio.Future[dict[str, Any]]] = {}
+        self._connected = True
+        self._initialized = False
+
+    @property
+    def connected(self) -> bool:
+        return self._connected
+
+    @property
+    def initialized(self) -> bool:
+        return self._initialized
+
+    def _next_id(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+    async def send_mcp_request(
+        self, method: str, params: dict[str, Any]
+    ) -> tuple[Any, dict[str, Any] | None]:
+        """Send an MCP request to ESP32 and wait for response.
+
+        Returns (result, error).
+        """
+        if not self._connected:
+            return None, {"code": -32000, "message": "ESP32 not connected"}
+
+        req_id = self._next_id()
+        message = make_mcp_message(self.session_id, method, params, req_id)
+
+        future: asyncio.Future[dict[str, Any]] = asyncio.get_event_loop().create_future()
+        self._pending[req_id] = future
+
+        try:
+            await self._ws.send(json.dumps(message))
+            response = await asyncio.wait_for(future, timeout=RESPONSE_TIMEOUT)
+            return parse_jsonrpc_response(response)
+        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)
+            return None, {"code": -32000, "message": f"ESP32 communication error: {exc}"}
+
+    async def initialize(self, vision_url: str = "", vision_token: str = "") -> bool:
+        """Send MCP initialize to ESP32."""
+        capabilities: dict[str, Any] = {}
+        if vision_url:
+            vision: dict[str, Any] = {"url": vision_url}
+            if vision_token:
+                vision["token"] = vision_token
+            capabilities["vision"] = vision
+        result, error = await self.send_mcp_request("initialize", {"capabilities": capabilities})
+        if error:
+            logger.error("ESP32 initialize failed: %s", error)
+            return False
+
+        logger.info(
+            "ESP32 initialized: protocol=%s server=%s",
+            result.get("protocolVersion", "?"),
+            result.get("serverInfo", {}),
+        )
+        self._initialized = True
+        return True
+
+    async def discover_tools(self) -> list[dict[str, Any]]:
+        """Discover tools available on ESP32."""
+        all_tools: list[dict[str, Any]] = []
+        cursor = ""
+
+        while True:
+            params: dict[str, Any] = {"cursor": cursor}
+            result, error = await self.send_mcp_request("tools/list", params)
+
+            if error:
+                logger.error("tools/list failed: %s", error)
+                break
+
+            tools = result.get("tools", [])
+            all_tools.extend(tools)
+
+            next_cursor = result.get("nextCursor", "")
+            if not next_cursor:
+                break
+            cursor = next_cursor
+
+        self.tools = all_tools
+        logger.info("Discovered %d tools on ESP32", len(all_tools))
+        return all_tools
+
+    async def call_tool(
+        self, name: str, arguments: dict[str, Any]
+    ) -> tuple[Any, dict[str, Any] | None]:
+        """Call a tool on ESP32."""
+        return await self.send_mcp_request(
+            "tools/call", {"name": name, "arguments": arguments}
+        )
+
+    def handle_response(self, payload: dict[str, Any]) -> None:
+        """Handle an incoming MCP response from ESP32."""
+        req_id = payload.get("id")
+        if req_id is not None and req_id in self._pending:
+            future = self._pending.pop(req_id)
+            if not future.done():
+                future.set_result(payload)
+        else:
+            # Notification (no id) — log and discard for now
+            method = payload.get("method", "")
+            logger.info("ESP32 notification: %s", method)
+
+    def disconnect(self) -> None:
+        """Mark connection as disconnected."""
+        self._connected = False
+        self._initialized = False
+        # Cancel all pending futures
+        for future in self._pending.values():
+            if not future.done():
+                future.set_exception(ConnectionError("ESP32 disconnected"))
+        self._pending.clear()
+
+
+class ESP32Manager:
+    """Manages ESP32 device connections.
+
+    Runs a WebSocket server that ESP32 devices connect to.
+    Currently supports a single device connection.
+    """
+
+    def __init__(self):
+        self._connection: ESP32Connection | None = None
+        self._server: Any = None
+        self._lock = asyncio.Lock()
+        self._init_tasks: list[asyncio.Task] = []
+        self._vision_url: str = ""
+        self._vision_token: str = ""
+
+    @property
+    def device_connected(self) -> bool:
+        return self._connection is not None and self._connection.connected
+
+    @property
+    def connection(self) -> ESP32Connection | None:
+        return self._connection
+
+    async def start(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8765,
+        vision_url: str = "",
+        vision_token: str = "",
+    ) -> None:
+        """Start the WebSocket server for ESP32 connections."""
+        self._vision_url = vision_url
+        self._vision_token = vision_token
+        logger.info("ESP32 WebSocket server starting on ws://%s:%d", host, port)
+        self._server = await websockets.serve(
+            self._handler,
+            host,
+            port,
+            process_request=self._check_auth,
+        )
+
+    async def stop(self) -> None:
+        """Stop the WebSocket server."""
+        # Cancel any pending initialization tasks
+        for task in self._init_tasks:
+            task.cancel()
+        self._init_tasks.clear()
+
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+    def _check_auth(
+        self, connection: ServerConnection, request: websockets.http11.Request
+    ) -> None | websockets.http11.Response:
+        """Validate Bearer token.
+
+        websockets 16+ passes (connection, request) to process_request.
+        """
+        expected = os.getenv("STACKCHAN_TOKEN") or os.getenv("BEARER_TOKEN")
+        if not expected:
+            logger.warning("STACKCHAN_TOKEN not set — accepting all connections")
+            return None
+
+        auth = request.headers.get("Authorization", "")
+        if auth == f"Bearer {expected}":
+            return None
+
+        logger.warning("ESP32 auth rejected")
+        return websockets.http11.Response(
+            401, "Unauthorized", websockets.datastructures.Headers()
+        )
+
+    async def _handler(self, ws: ServerConnection) -> None:
+        """Handle an incoming ESP32 WebSocket connection.
+
+        Architecture: the message read loop runs continuously, dispatching
+        MCP responses to pending futures. Initialization (initialize + tools/list)
+        runs as a separate task so it doesn't block the read loop.
+        """
+        session_id = str(uuid.uuid4())
+        device_id = (
+            ws.request.headers.get("Device-Id", "unknown") if ws.request else "unknown"
+        )
+        logger.info("ESP32 connecting: device=%s", device_id)
+
+        connection = ESP32Connection(ws, session_id)
+        connection.device_id = device_id
+
+        try:
+            async for message in ws:
+                if isinstance(message, bytes):
+                    # Binary = audio frame, ignore for now
+                    continue
+
+                try:
+                    data = json.loads(message)
+                except json.JSONDecodeError:
+                    logger.warning("Invalid JSON from ESP32: %s", str(message)[:100])
+                    continue
+
+                msg_type = data.get("type", "")
+
+                if msg_type == "hello":
+                    # ESP32 hello handshake
+                    features = data.get("features", {})
+                    if not features.get("mcp"):
+                        logger.warning("ESP32 does not support MCP, rejecting")
+                        await ws.close()
+                        return
+
+                    # Send hello response
+                    resp = HelloResponse(session_id=session_id)
+                    await ws.send(resp.model_dump_json())
+
+                    # Register connection
+                    async with self._lock:
+                        if self._connection and self._connection.connected:
+                            logger.warning("Replacing existing ESP32 connection")
+                            self._connection.disconnect()
+                        self._connection = connection
+
+                    # Start initialization as a separate task so the read loop
+                    # continues to pump messages (responses to initialize/tools_list)
+                    task = asyncio.create_task(self._init_device(connection, device_id))
+                    self._init_tasks.append(task)
+                    task.add_done_callback(lambda t: self._init_tasks.remove(t) if t in self._init_tasks else None)
+
+                elif msg_type == "mcp":
+                    # MCP response from ESP32
+                    payload = data.get("payload", {})
+                    connection.handle_response(payload)
+
+                else:
+                    logger.debug("ESP32 message type=%s (ignored)", msg_type)
+
+        except websockets.exceptions.ConnectionClosed:
+            logger.info("ESP32 disconnected: device=%s", device_id)
+        finally:
+            connection.disconnect()
+            async with self._lock:
+                if self._connection is connection:
+                    self._connection = None
+
+    async def _init_device(self, connection: ESP32Connection, device_id: str) -> None:
+        """Initialize MCP session with a newly connected device."""
+        if await connection.initialize(
+            vision_url=self._vision_url,
+            vision_token=self._vision_token,
+        ):
+            await connection.discover_tools()
+            logger.info(
+                "ESP32 ready: device=%s tools=%d",
+                device_id,
+                len(connection.tools),
+            )
+        else:
+            logger.error("ESP32 MCP initialization failed")
+
+    async def call_tool(
+        self, name: str, arguments: dict[str, Any]
+    ) -> tuple[Any, dict[str, Any] | None]:
+        """Call a tool on the connected ESP32 device."""
+        if not self._connection or not self._connection.connected:
+            return None, {"code": -32000, "message": "No ESP32 device connected"}
+        if not self._connection.initialized:
+            return None, {"code": -32000, "message": "ESP32 not initialized"}
+        return await self._connection.call_tool(name, arguments)
+
+    def get_status(self) -> dict[str, Any]:
+        """Get current connection status."""
+        if not self._connection or not self._connection.connected:
+            return {
+                "connected": False,
+                "device_id": None,
+                "tools_count": 0,
+            }
+        return {
+            "connected": True,
+            "device_id": self._connection.device_id,
+            "initialized": self._connection.initialized,
+            "tools_count": len(self._connection.tools),
+            "tools": [t.get("name", "") for t in self._connection.tools],
+        }

stackchan_mcp/gateway.py

@@ -0,0 +1,123 @@
+"""Two-faced gateway: bridges MCP client (stdio MCP) and ESP32 (WebSocket MCP).
+
+MCP client sees a standard MCP server via stdio.
+ESP32 sees a WebSocket server that sends MCP client requests.
+This module orchestrates both sides.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from aiohttp import web
+
+from .capture_server import create_capture_app
+from .esp32_client import ESP32Manager
+
+logger = logging.getLogger(__name__)
+
+
+class Gateway:
+    """Main gateway orchestrator.
+
+    Holds the ESP32 manager and provides the bridge between
+    the stdio MCP server (MCP client side) and the ESP32 device.
+
+    Also runs an HTTP capture server for receiving photos from ESP32.
+    """
+
+    def __init__(self):
+        self.esp32 = ESP32Manager()
+        self._running = False
+        self._http_runner: web.AppRunner | None = None
+
+    @property
+    def vision_url(self) -> str:
+        """URL for ESP32 to POST captured photos to.
+
+        VISION_URL can be set to a complete public capture URL for remote
+        access setups such as Tailscale Funnel. Otherwise VISION_HOST should
+        be the LAN IP of the host running this gateway, as seen from the ESP32
+        (e.g. something like 192.168.x.y on a typical home network). Falls
+        back to "127.0.0.1" with a warning if unset; in that case the ESP32
+        will not be able to reach the capture endpoint over the network.
+        """
+        explicit_url = os.getenv("VISION_URL")
+        if explicit_url:
+            return explicit_url
+
+        host = os.getenv("VISION_HOST")
+        if not host:
+            logger.warning(
+                "VISION_URL/VISION_HOST not set; defaulting to 127.0.0.1. "
+                "ESP32 will not reach the capture endpoint unless "
+                "VISION_HOST is set to this host's LAN IP or VISION_URL is "
+                "set to a full capture URL."
+            )
+            host = "127.0.0.1"
+        port = int(os.getenv("CAPTURE_PORT", "8766"))
+        return f"http://{host}:{port}/capture"
+
+    @property
+    def vision_token(self) -> str:
+        """Bearer token expected by the capture endpoint.
+
+        VISION_TOKEN can be set separately. By default, reuse the ESP32
+        WebSocket token so remote capture uploads are protected whenever the
+        gateway itself is protected.
+        """
+        return (
+            os.getenv("VISION_TOKEN")
+            or os.getenv("STACKCHAN_TOKEN")
+            or os.getenv("BEARER_TOKEN")
+            or ""
+        )
+
+    async def start(self) -> None:
+        """Start the ESP32 WebSocket server and HTTP capture server."""
+        host = os.getenv("HOST", "0.0.0.0")
+        ws_port = int(os.getenv("WS_PORT", os.getenv("PORT", "8765")))
+        capture_port = int(os.getenv("CAPTURE_PORT", "8766"))
+
+        # Start WebSocket server for ESP32
+        await self.esp32.start(
+            host,
+            ws_port,
+            vision_url=self.vision_url,
+            vision_token=self.vision_token,
+        )
+
+        # Start HTTP capture server
+        app = create_capture_app(capture_token=self.vision_token)
+        self._http_runner = web.AppRunner(app)
+        await self._http_runner.setup()
+        site = web.TCPSite(self._http_runner, host, capture_port)
+        await site.start()
+
+        self._running = True
+        logger.info(
+            "Gateway started: WS on %s:%d, capture on %s:%d, vision_url=%s",
+            host, ws_port, host, capture_port, self.vision_url,
+        )
+
+    async def stop(self) -> None:
+        """Stop the gateway."""
+        self._running = False
+        if self._http_runner:
+            await self._http_runner.cleanup()
+            self._http_runner = None
+        await self.esp32.stop()
+        logger.info("Gateway stopped")
+
+
+# Singleton gateway instance, shared between stdio server and ESP32 manager
+_gateway: Gateway | None = None
+
+
+def get_gateway() -> Gateway:
+    """Get or create the singleton gateway."""
+    global _gateway
+    if _gateway is None:
+        _gateway = Gateway()
+    return _gateway

stackchan_mcp/handlers/__init__.py

@@ -0,0 +1,7 @@
+"""Tool handler implementations.
+
+Submodules:
+- robot: head servo + LED control
+- audio: volume control (stub)
+- camera: photo capture via ESP32
+"""

stackchan_mcp/handlers/audio.py

@@ -0,0 +1,21 @@
+"""Audio handlers: volume control (stub)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..tools import SetVolumeParams
+
+logger = logging.getLogger(__name__)
+
+_volume: int = 50
+
+
+def set_volume(args: dict[str, Any]) -> bool:
+    """Set speaker volume (in-memory stub)."""
+    global _volume
+    params = SetVolumeParams(**args)
+    _volume = params.volume
+    logger.info("set_volume -> %d", _volume)
+    return True