stackchan-mcp 0.1.0__tar.gz

stackchan_mcp-0.1.0/.env.example

@@ -0,0 +1,33 @@
+# stackchan-mcp gateway environment variables
+# Copy this file to `.env` and fill in your values.
+
+# --- ESP32 authentication ---
+# Token sent by the ESP32 as `Authorization: Bearer <token>`.
+# Set the same value in the firmware's WiFi config UI (token field).
+STACKCHAN_TOKEN=your-secret-token-here
+
+# Legacy alias (still supported, prefer STACKCHAN_TOKEN above).
+BEARER_TOKEN=
+
+# --- WebSocket server (ESP32 -> gateway) ---
+HOST=0.0.0.0
+WS_PORT=8765
+
+# --- HTTP capture server (ESP32 -> gateway, photo upload) ---
+CAPTURE_PORT=8766
+
+# Full public capture URL sent to the ESP32.
+# Use this for remote tunnel setups such as Tailscale Funnel.
+# Example: https://stackchan.example.ts.net:8443/capture
+VISION_URL=
+
+# Optional separate bearer token for HTTP photo uploads to VISION_URL.
+# If empty, STACKCHAN_TOKEN is reused.
+VISION_TOKEN=
+
+# LAN IP of THIS machine, as seen from the ESP32.
+# The gateway tells the ESP32 to POST captured photos to this address.
+# Required if you want take_photo to work and VISION_URL is not set.
+# Example: something like 192.168.x.y on a typical home network
+# (run `ifconfig` / `ip addr` to find your host's LAN IP).
+VISION_HOST=

stackchan_mcp-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+
+# Environment / secrets
+.env
+.env.local
+*.local
+
+# Captures (user photos)
+captures/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+*.zip
+build/
+dist/

stackchan_mcp-0.1.0/LICENSE

@@ -0,0 +1,39 @@
+MIT License
+
+Copyright (c) 2025 Shenzhen Xinzhi Future Technology Co., Ltd.
+Copyright (c) 2025 Project Contributors
+Copyright (c) 2026 kisaragi-mochi
+
+NOTE: This MIT License covers the repository as a whole **except** for the
+SCServo_lib files (Feetech serial bus servo SDK), which live in
+`firmware/main/boards/stackchan/` (files: SCS.{cc,h}, SCSCL.{cc,h},
+SCSerial.{cc,h}, INST.h, SCServo.h) and are licensed separately under the
+GNU General Public License v3.0. Their full license text is in
+`firmware/main/boards/stackchan/SCServo_lib_LICENSE.txt`.
+
+Because the firmware binary statically links the SCServo_lib code, the
+combined firmware build is effectively distributed under GPL-3.0. The
+gateway/ Python package, which runs in a separate process and communicates
+with the device only over a network socket, remains under the MIT License
+above.
+
+---
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stackchan_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: stackchan-mcp
+Version: 0.1.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
+Project-URL: Issues, https://github.com/kisaragi-mochi/stackchan-mcp/issues
+Author: kisaragi-mochi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: esp32,llm,mcp,robotics,stackchan,xiaozhi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv
+Requires-Dist: websockets>=12
+Description-Content-Type: text/markdown
+
+# gateway
+
+Python "two-faced" MCP gateway for the **M5Stack official [StackChan](https://docs.m5stack.com/ja/StackChan)** kit (custom [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) firmware in [`../firmware/main/boards/stackchan/`](../firmware/main/boards/stackchan/)).
+
+```
+┌─────────────┐  stdio MCP  ┌──────────────┐  WebSocket MCP  ┌──────────┐
+│ MCP client  │ ──────────▶ │   gateway    │ ──────────────▶ │  ESP32   │
+│ (Claude...) │ ◀────────── │  (this dir)  │ ◀────────────── │ StackChan│
+└─────────────┘             │              │                 └──────────┘
+                            │  /capture    │ ◀─ HTTP POST ──┘  (JPEG)
+                            └──────────────┘
+```
+
+The gateway exposes a clean stdio MCP server to the LLM client (left) while
+speaking the xiaozhi-esp32 WebSocket MCP dialect to the device (right). It
+also runs a small HTTP server (`/capture`) so the ESP32 can upload photos.
+
+The package name on PyPI, the installed CLI command, and the MCP server id
+in your client config are all `stackchan-mcp`.
+
+## Install (end users)
+
+The gateway is published to PyPI as `stackchan-mcp`. For end users, install
+it as an isolated CLI tool:
+
+```bash
+uv tool install stackchan-mcp
+# or
+pipx install stackchan-mcp
+```
+
+Then run:
+
+```bash
+stackchan-mcp
+```
+
+`stackchan-mcp` reads its configuration (`STACKCHAN_TOKEN`, `VISION_HOST`,
+etc.) from environment variables or a `.env` file in the working directory.
+See the [Setup](#setup) section below for the supported variables. For the
+firmware side (WebSocket gateway URL, auth token, NVS configuration), see
+[`../README.md`](../README.md#configuring-the-websocket-gateway-url-and-auth-token).
+
+If you prefer a project-managed virtualenv, `pip install stackchan-mcp`
+inside an active venv works as well, and `python -m stackchan_mcp` inside
+that venv is equivalent to `stackchan-mcp`. Just avoid `pip install`
+against the system Python (PEP 668).
+
+## Setup
+
+```bash
+cd gateway
+cp .env.example .env       # then edit .env (see below)
+uv sync
+```
+
+Edit `.env`:
+- `STACKCHAN_TOKEN`: Bearer token for ESP32 auth (must match firmware setting)
+- `VISION_URL`: full public capture URL for remote access tunnels, such as
+  `https://stackchan.example.ts.net:8443/capture`
+- `VISION_TOKEN`: optional separate Bearer token for capture uploads; if empty,
+  `STACKCHAN_TOKEN` is reused
+- `VISION_HOST`: LAN IP of this machine, as seen from the ESP32
+  (something like `192.168.x.y` on a typical home network — run `ifconfig`
+  or `ip addr` to find it). Required for `take_photo` when `VISION_URL` is not
+  set.
+
+## Run
+
+```bash
+uv run python -m stackchan_mcp
+```
+
+Default ports:
+- WebSocket (ESP32 -> gateway): `0.0.0.0:8765`
+- HTTP capture (ESP32 -> gateway): `0.0.0.0:8766`
+
+For non-LAN setups, see [`../docs/remote-access.md`](../docs/remote-access.md)
+for the Tailscale Funnel flow.
+
+When you restart the gateway during development, an already-connected ESP32
+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.
+
+## Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+## Register as MCP server
+
+### Claude Code (`~/.claude.json`)
+
+```json
+{
+  "mcpServers": {
+    "stackchan-mcp": {
+      "type": "stdio",
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/absolute/path/to/stackchan-mcp/gateway",
+        "python",
+        "-m",
+        "stackchan_mcp"
+      ],
+      "env": {
+        "STACKCHAN_TOKEN": "your-secret-token-here",
+        "VISION_HOST": "your.host.lan.ip"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+Same shape, under `mcpServers`.
+
+## Tools exposed to MCP client
+
+| Tool | Description |
+|---|---|
+| `get_status` | Gateway connection state (ESP32 connected? device info?) |
+| `get_device_info` | ESP32 device status (battery, volume, WiFi, etc.) |
+| `take_photo(question?)` | Trigger camera capture; returns saved JPEG path |
+| `set_volume(volume)` | Speaker volume 0-100 |
+| `set_brightness(brightness)` | Screen brightness 0-100 |
+| `move_head(yaw, pitch, speed?)` | Drive yaw + pitch servos |
+| `get_head_angles` | Read current yaw + pitch servo angles |
+| `get_touch_state` | Touch sensor state (press/release/stroke) |
+| `set_avatar(face)` | Switch avatar expression (`idle` / `happy` / `thinking` / `sad` / `surprised` / `embarrassed`) |
+| `set_blink(state)` | Blink animation on/off |
+| `set_mouth(state)` | Mouth shape (`closed` / `half` / `open` / `e` / `u`) |
+| `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/stdio_server.py`.
+
+## Architecture
+
+```
+stackchan_mcp/
+├── __main__.py         # entry: starts gateway + stdio server
+├── gateway.py          # singleton orchestrator
+├── stdio_server.py     # MCP client side (stdio MCP server)
+├── esp32_client.py     # ESP32 side (WebSocket MCP client + auth)
+├── capture_server.py   # HTTP /capture endpoint for photo uploads
+├── server.py           # legacy local WS test server (unused in prod)
+├── mcp_router.py       # legacy local stub router (unused in prod)
+├── protocol.py         # JSON-RPC 2.0 message helpers
+├── tools.py            # ESP32-side tool definitions (stub/test)
+├── audio_stream.py     # placeholder for future Opus pipeline
+└── handlers/
+    ├── robot.py        # legacy stubs
+    ├── camera.py       # legacy stubs
+    └── audio.py        # legacy stubs
+```
+
+Captures land in `~/.stackchan/captures/` by default.
+
+## Manual smoke test (Python)
+
+```python
+import asyncio, json, websockets
+
+async def smoke():
+    async with websockets.connect(
+        "ws://localhost:8765",
+        additional_headers={"Authorization": "Bearer your-secret-token-here"},
+    ) as ws:
+        await ws.send(json.dumps({
+            "type": "hello", "version": 1, "audio_params": {},
+        }))
+        print(await ws.recv())
+
+        await ws.send(json.dumps({"type": "mcp", "payload": {
+            "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {},
+        }}))
+        print(await ws.recv())
+
+        await ws.send(json.dumps({"type": "mcp", "payload": {
+            "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {},
+        }}))
+        print(await ws.recv())
+
+asyncio.run(smoke())
+```
+
+## Phase roadmap
+
+- **Phase 1** (done): stdio MCP shell, ESP32 WebSocket bridge, tool routing
+- **Phase 2** (done): real servo / volume / brightness via ESP32
+- **Phase 3** (done): camera capture (JPEG over HTTP)
+- **Phase 4** (planned): Opus audio stream (STT/TTS pipeline)
+
+## License
+
+The gateway is distributed under the MIT License (see `LICENSE`). The
+parent monorepo's `firmware/` directory contains SCServo_lib code under
+GPL-3.0, but those files live only inside
+`firmware/main/boards/stackchan/` and never enter this package. The
+gateway and firmware communicate only over WebSocket, so the GPL/MIT
+boundary is preserved at the process level.

stackchan_mcp-0.1.0/README.md

@@ -0,0 +1,207 @@
+# gateway
+
+Python "two-faced" MCP gateway for the **M5Stack official [StackChan](https://docs.m5stack.com/ja/StackChan)** kit (custom [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) firmware in [`../firmware/main/boards/stackchan/`](../firmware/main/boards/stackchan/)).
+
+```
+┌─────────────┐  stdio MCP  ┌──────────────┐  WebSocket MCP  ┌──────────┐
+│ MCP client  │ ──────────▶ │   gateway    │ ──────────────▶ │  ESP32   │
+│ (Claude...) │ ◀────────── │  (this dir)  │ ◀────────────── │ StackChan│
+└─────────────┘             │              │                 └──────────┘
+                            │  /capture    │ ◀─ HTTP POST ──┘  (JPEG)
+                            └──────────────┘
+```
+
+The gateway exposes a clean stdio MCP server to the LLM client (left) while
+speaking the xiaozhi-esp32 WebSocket MCP dialect to the device (right). It
+also runs a small HTTP server (`/capture`) so the ESP32 can upload photos.
+
+The package name on PyPI, the installed CLI command, and the MCP server id
+in your client config are all `stackchan-mcp`.
+
+## Install (end users)
+
+The gateway is published to PyPI as `stackchan-mcp`. For end users, install
+it as an isolated CLI tool:
+
+```bash
+uv tool install stackchan-mcp
+# or
+pipx install stackchan-mcp
+```
+
+Then run:
+
+```bash
+stackchan-mcp
+```
+
+`stackchan-mcp` reads its configuration (`STACKCHAN_TOKEN`, `VISION_HOST`,
+etc.) from environment variables or a `.env` file in the working directory.
+See the [Setup](#setup) section below for the supported variables. For the
+firmware side (WebSocket gateway URL, auth token, NVS configuration), see
+[`../README.md`](../README.md#configuring-the-websocket-gateway-url-and-auth-token).
+
+If you prefer a project-managed virtualenv, `pip install stackchan-mcp`
+inside an active venv works as well, and `python -m stackchan_mcp` inside
+that venv is equivalent to `stackchan-mcp`. Just avoid `pip install`
+against the system Python (PEP 668).
+
+## Setup
+
+```bash
+cd gateway
+cp .env.example .env       # then edit .env (see below)
+uv sync
+```
+
+Edit `.env`:
+- `STACKCHAN_TOKEN`: Bearer token for ESP32 auth (must match firmware setting)
+- `VISION_URL`: full public capture URL for remote access tunnels, such as
+  `https://stackchan.example.ts.net:8443/capture`
+- `VISION_TOKEN`: optional separate Bearer token for capture uploads; if empty,
+  `STACKCHAN_TOKEN` is reused
+- `VISION_HOST`: LAN IP of this machine, as seen from the ESP32
+  (something like `192.168.x.y` on a typical home network — run `ifconfig`
+  or `ip addr` to find it). Required for `take_photo` when `VISION_URL` is not
+  set.
+
+## Run
+
+```bash
+uv run python -m stackchan_mcp
+```
+
+Default ports:
+- WebSocket (ESP32 -> gateway): `0.0.0.0:8765`
+- HTTP capture (ESP32 -> gateway): `0.0.0.0:8766`
+
+For non-LAN setups, see [`../docs/remote-access.md`](../docs/remote-access.md)
+for the Tailscale Funnel flow.
+
+When you restart the gateway during development, an already-connected ESP32
+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.
+
+## Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+## Register as MCP server
+
+### Claude Code (`~/.claude.json`)
+
+```json
+{
+  "mcpServers": {
+    "stackchan-mcp": {
+      "type": "stdio",
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/absolute/path/to/stackchan-mcp/gateway",
+        "python",
+        "-m",
+        "stackchan_mcp"
+      ],
+      "env": {
+        "STACKCHAN_TOKEN": "your-secret-token-here",
+        "VISION_HOST": "your.host.lan.ip"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+Same shape, under `mcpServers`.
+
+## Tools exposed to MCP client
+
+| Tool | Description |
+|---|---|
+| `get_status` | Gateway connection state (ESP32 connected? device info?) |
+| `get_device_info` | ESP32 device status (battery, volume, WiFi, etc.) |
+| `take_photo(question?)` | Trigger camera capture; returns saved JPEG path |
+| `set_volume(volume)` | Speaker volume 0-100 |
+| `set_brightness(brightness)` | Screen brightness 0-100 |
+| `move_head(yaw, pitch, speed?)` | Drive yaw + pitch servos |
+| `get_head_angles` | Read current yaw + pitch servo angles |
+| `get_touch_state` | Touch sensor state (press/release/stroke) |
+| `set_avatar(face)` | Switch avatar expression (`idle` / `happy` / `thinking` / `sad` / `surprised` / `embarrassed`) |
+| `set_blink(state)` | Blink animation on/off |
+| `set_mouth(state)` | Mouth shape (`closed` / `half` / `open` / `e` / `u`) |
+| `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/stdio_server.py`.
+
+## Architecture
+
+```
+stackchan_mcp/
+├── __main__.py         # entry: starts gateway + stdio server
+├── gateway.py          # singleton orchestrator
+├── stdio_server.py     # MCP client side (stdio MCP server)
+├── esp32_client.py     # ESP32 side (WebSocket MCP client + auth)
+├── capture_server.py   # HTTP /capture endpoint for photo uploads
+├── server.py           # legacy local WS test server (unused in prod)
+├── mcp_router.py       # legacy local stub router (unused in prod)
+├── protocol.py         # JSON-RPC 2.0 message helpers
+├── tools.py            # ESP32-side tool definitions (stub/test)
+├── audio_stream.py     # placeholder for future Opus pipeline
+└── handlers/
+    ├── robot.py        # legacy stubs
+    ├── camera.py       # legacy stubs
+    └── audio.py        # legacy stubs
+```
+
+Captures land in `~/.stackchan/captures/` by default.
+
+## Manual smoke test (Python)
+
+```python
+import asyncio, json, websockets
+
+async def smoke():
+    async with websockets.connect(
+        "ws://localhost:8765",
+        additional_headers={"Authorization": "Bearer your-secret-token-here"},
+    ) as ws:
+        await ws.send(json.dumps({
+            "type": "hello", "version": 1, "audio_params": {},
+        }))
+        print(await ws.recv())
+
+        await ws.send(json.dumps({"type": "mcp", "payload": {
+            "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {},
+        }}))
+        print(await ws.recv())
+
+        await ws.send(json.dumps({"type": "mcp", "payload": {
+            "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {},
+        }}))
+        print(await ws.recv())
+
+asyncio.run(smoke())
+```
+
+## Phase roadmap
+
+- **Phase 1** (done): stdio MCP shell, ESP32 WebSocket bridge, tool routing
+- **Phase 2** (done): real servo / volume / brightness via ESP32
+- **Phase 3** (done): camera capture (JPEG over HTTP)
+- **Phase 4** (planned): Opus audio stream (STT/TTS pipeline)
+
+## License
+
+The gateway is distributed under the MIT License (see `LICENSE`). The
+parent monorepo's `firmware/` directory contains SCServo_lib code under
+GPL-3.0, but those files live only inside
+`firmware/main/boards/stackchan/` and never enter this package. The
+gateway and firmware communicate only over WebSocket, so the GPL/MIT
+boundary is preserved at the process level.

stackchan_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "stackchan-mcp"
+version = "0.1.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"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "kisaragi-mochi" },
+]
+keywords = ["mcp", "stackchan", "esp32", "xiaozhi", "robotics", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Communications",
+    "Topic :: System :: Hardware",
+]
+dependencies = [
+    "websockets>=12",
+    "pydantic>=2",
+    "python-dotenv",
+    "mcp>=1.0",
+    "aiohttp>=3",
+]
+
+[project.urls]
+Homepage = "https://github.com/kisaragi-mochi/stackchan-mcp"
+Repository = "https://github.com/kisaragi-mochi/stackchan-mcp"
+Issues = "https://github.com/kisaragi-mochi/stackchan-mcp/issues"
+
+[project.scripts]
+stackchan-mcp = "stackchan_mcp.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "ruff>=0.15.12",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

stackchan_mcp-0.1.0/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-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-0.1.0/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