stackchan-mcp 0.9.1__py3-none-win_amd64.whl

stackchan_mcp/ownership.py

@@ -0,0 +1,270 @@
+"""Gateway ownership lock - refuse-mode MVP (#177 Phase A)."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal, TypedDict
+
+LOCK_DIR = Path.home() / ".stackchan-mcp"
+LOCK_PATH = LOCK_DIR / "owner.lock"
+
+
+LockMode = Literal["stdio", "streamable-http"]
+
+
+class _BaseLockInfo(TypedDict):
+    owner_id: str
+    pid: int
+    start_ts: str
+    host: str
+
+
+class LockInfo(_BaseLockInfo, total=False):
+    mode: LockMode
+    http_endpoint: str | None
+    started_by: str | None
+
+
+class OwnershipError(RuntimeError):
+    """Raised when ownership cannot be acquired."""
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def generate_owner_id() -> str:
+    env = os.environ.get("STACKCHAN_OWNER_ID")
+    if env:
+        return env
+    return f"stackchan-mcp-{uuid.uuid4().hex[:8]}"
+
+
+def is_pid_alive(pid: int) -> bool:
+    """Return whether pid is alive without disturbing the target process.
+
+    On Windows, os.kill(pid, 0) calls TerminateProcess(..., 0), which would
+    kill the target process; use a non-destructive Win32 API check instead.
+    """
+    if pid <= 0:
+        return False
+    if sys.platform == "win32":
+        return _is_pid_alive_windows(pid)
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _is_pid_alive_windows(pid: int) -> bool:
+    import ctypes
+    import ctypes.wintypes
+
+    PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    STILL_ACTIVE = 259
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.OpenProcess.argtypes = [
+        ctypes.wintypes.DWORD,
+        ctypes.wintypes.BOOL,
+        ctypes.wintypes.DWORD,
+    ]
+    kernel32.OpenProcess.restype = ctypes.wintypes.HANDLE
+    kernel32.GetExitCodeProcess.argtypes = [
+        ctypes.wintypes.HANDLE,
+        ctypes.POINTER(ctypes.wintypes.DWORD),
+    ]
+    kernel32.GetExitCodeProcess.restype = ctypes.wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [ctypes.wintypes.HANDLE]
+    kernel32.CloseHandle.restype = ctypes.wintypes.BOOL
+
+    handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+    if not handle:
+        return False
+
+    try:
+        exit_code = ctypes.wintypes.DWORD()
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+            return False
+        return exit_code.value == STILL_ACTIVE
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+def read_lock(path: Path = LOCK_PATH) -> LockInfo | None:
+    if not path.exists():
+        return None
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    if not isinstance(raw, dict):
+        return None
+
+    owner_id = raw.get("owner_id")
+    pid = raw.get("pid")
+    start_ts = raw.get("start_ts")
+    host = raw.get("host")
+    if (
+        not isinstance(owner_id, str)
+        or not isinstance(pid, int)
+        or not isinstance(start_ts, str)
+        or not isinstance(host, str)
+    ):
+        return None
+
+    info: LockInfo = {
+        "owner_id": owner_id,
+        "pid": pid,
+        "start_ts": start_ts,
+        "host": host,
+    }
+
+    # Optional metadata: silently ignore unknown or malformed values so a
+    # schema-drift writer (for example a future-mode lock file or a
+    # partially compatible external writer) cannot cause read_lock to
+    # return None and trick acquire_lock into unlinking a live owner's
+    # lock file. The four required #177 base fields above are
+    # authoritative for the claim/refuse decision; validating optional
+    # metadata is a separate diagnostic concern.
+
+    mode = raw.get("mode")
+    if mode in ("stdio", "streamable-http"):
+        info["mode"] = mode
+
+    if "http_endpoint" in raw:
+        http_endpoint = raw["http_endpoint"]
+        if http_endpoint is None or isinstance(http_endpoint, str):
+            info["http_endpoint"] = http_endpoint
+
+    if "started_by" in raw:
+        started_by = raw["started_by"]
+        if started_by is None or isinstance(started_by, str):
+            info["started_by"] = started_by
+
+    return info
+
+
+def _write_lock_atomic(info: LockInfo, path: Path = LOCK_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp")
+    tmp.write_text(json.dumps(info, indent=2), encoding="utf-8")
+    try:
+        # Link the complete temp file into place only if no owner file exists.
+        # This keeps readers from seeing partial JSON and lets exactly one
+        # simultaneous startup win the initial claim.
+        os.link(tmp, path)
+    finally:
+        tmp.unlink(missing_ok=True)
+
+
+def acquire_lock(
+    owner_id: str,
+    path: Path = LOCK_PATH,
+    *,
+    mode: LockMode = "stdio",
+    http_endpoint: str | None = None,
+    started_by: str | None = None,
+) -> LockInfo:
+    """Acquire the ownership lock. Raise OwnershipError on refuse.
+
+    The default stdio-mode call writes the original #177 lock shape so
+    older lock readers and ``stackchan-mcp --check`` output remain
+    compatible. Daemon transports can attach optional metadata for
+    diagnostics without changing the atomic hardlink claim.
+    """
+    if mode not in ("stdio", "streamable-http"):
+        raise ValueError(f"unsupported lock mode: {mode!r}")
+    if mode == "stdio" and (http_endpoint is not None or started_by is not None):
+        raise ValueError(
+            "stdio-mode ownership locks must not carry http_endpoint or "
+            "started_by; these fields are reserved for non-stdio transports"
+        )
+
+    while True:
+        existing = read_lock(path)
+        if existing is not None:
+            if is_pid_alive(existing["pid"]):
+                raise OwnershipError(
+                    "stackchan-mcp: device already owned by "
+                    f"{existing['owner_id']} "
+                    f"(pid {existing['pid']}, since {existing['start_ts']})"
+                )
+            print(
+                f"stackchan-mcp: removed stale lock from dead pid {existing['pid']}",
+                file=sys.stderr,
+            )
+            path.unlink(missing_ok=True)
+        elif path.exists():
+            path.unlink()
+
+        info: LockInfo = {
+            "owner_id": owner_id,
+            "pid": os.getpid(),
+            "start_ts": _now_iso(),
+            "host": socket.gethostname(),
+        }
+        if mode != "stdio":
+            info["mode"] = mode
+        if http_endpoint is not None:
+            info["http_endpoint"] = http_endpoint
+        if started_by is not None:
+            info["started_by"] = started_by
+
+        try:
+            _write_lock_atomic(info, path)
+        except FileExistsError:
+            continue
+        return info
+
+
+def release_lock(path: Path = LOCK_PATH) -> None:
+    """Remove the lock file. Idempotent.
+
+    This is the legacy, owner-unaware release primitive kept for backward
+    compatibility. New callers should prefer :func:`release_lock_if_owner`
+    so that a stale cleanup callback cannot unlink a successor process's
+    live lock.
+    """
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def release_lock_if_owner(info: LockInfo, path: Path = LOCK_PATH) -> bool:
+    """Remove the lock file only if it still belongs to ``info``.
+
+    Returns ``True`` if the lock was removed, ``False`` if the on-disk
+    lock has a different ``owner_id`` / ``pid`` / ``start_ts`` or no
+    longer exists. This is the owner-scoped counterpart to
+    :func:`release_lock` and is intended for cleanup paths (``finally``
+    blocks, ``atexit.register``) where the caller may have lost ownership
+    between claim and cleanup — for example after the gateway exited and
+    a second process acquired the lock before the first process's
+    interpreter exit callbacks ran.
+    """
+    existing = read_lock(path)
+    if existing is None:
+        return False
+    if (
+        existing.get("owner_id") != info.get("owner_id")
+        or existing.get("pid") != info.get("pid")
+        or existing.get("start_ts") != info.get("start_ts")
+    ):
+        return False
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False

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/queue.py

@@ -0,0 +1,191 @@
+"""Bounded command queue for Issue #178 Phase B chunk 1.
+
+This module follows the command-queue design in
+``docs/178-http-transport-spike.md`` and intentionally stays independent from
+the HTTP MCP server, MCP SDK objects, and ESP32 gateway wiring.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from typing import Any
+
+COMMAND_QUEUE_SIZE_ENV = "STACKCHAN_COMMAND_QUEUE_SIZE"
+DEFAULT_COMMAND_QUEUE_CAPACITY = 32
+QUEUE_FULL_ERROR_CODE = -32000
+QUEUE_FULL_MESSAGE = "stackchan command queue is full"
+QUEUE_FULL_RETRY_AFTER_MS = 250
+
+DispatchFn = Callable[["QueueItem"], Awaitable[Any]]
+
+
+@dataclass(frozen=True)
+class QueueItem:
+    """One ESP32-bound command and the future that receives its response."""
+
+    correlation_id: str
+    client_session_id: str | None
+    client_request_id: int | str
+    tool_name: str
+    arguments: dict[str, Any]
+    response_future: asyncio.Future[Any]
+    enqueued_at: float
+
+
+class QueueFull(Exception):
+    """Raised by CommandQueue.enqueue when capacity is reached."""
+
+    def __init__(self, queue_depth: int, capacity: int) -> None:
+        self.queue_depth = queue_depth
+        self.capacity = capacity
+        super().__init__(
+            f"{QUEUE_FULL_MESSAGE} (queue_depth={queue_depth}, capacity={capacity})"
+        )
+
+
+class CommandQueue:
+    """Asyncio-backed bounded FIFO queue for serialized command dispatch."""
+
+    def __init__(self, capacity: int | None = None) -> None:
+        self._capacity = capacity if capacity is not None else _capacity_from_env()
+        if self._capacity < 1:
+            raise ValueError("command queue capacity must be at least 1")
+        self._queue: asyncio.Queue[QueueItem] = asyncio.Queue(
+            maxsize=self._capacity
+        )
+
+    @property
+    def capacity(self) -> int:
+        """Return the maximum number of queued commands."""
+        return self._capacity
+
+    @property
+    def depth(self) -> int:
+        """Return the current number of queued commands."""
+        return self._queue.qsize()
+
+    def enqueue(self, item: QueueItem) -> None:
+        """Add an item without blocking, raising QueueFull on saturation."""
+        try:
+            self._queue.put_nowait(item)
+        except asyncio.QueueFull as exc:
+            raise QueueFull(self.depth, self.capacity) from exc
+
+    async def get(self) -> QueueItem:
+        """Await the next queued item in FIFO order."""
+        return await self._queue.get()
+
+    async def run_dispatcher(self, dispatch_fn: DispatchFn) -> None:
+        """Dispatch commands one at a time and complete each response future.
+
+        The injected dispatch function is awaited to completion before the next
+        queue item is fetched. Exceptions from dispatch_fn are delivered to the
+        item's response_future so the dispatcher loop can continue.
+        """
+        while True:
+            item = await self.get()
+            try:
+                result = await dispatch_fn(item)
+            except Exception as exc:
+                if not item.response_future.done():
+                    item.response_future.set_exception(exc)
+            else:
+                if not item.response_future.done():
+                    item.response_future.set_result(result)
+            finally:
+                self._queue.task_done()
+
+
+def build_queue_full_error(
+    queue_depth: int,
+    retry_after_ms: int = QUEUE_FULL_RETRY_AFTER_MS,
+) -> dict[str, Any]:
+    """Build the JSON-RPC inner error payload for queue saturation."""
+    return {
+        "code": QUEUE_FULL_ERROR_CODE,
+        "message": QUEUE_FULL_MESSAGE,
+        "data": {
+            "queue_depth": queue_depth,
+            "retry_after_ms": retry_after_ms,
+        },
+    }
+
+
+def _capacity_from_env() -> int:
+    raw_capacity = os.getenv(COMMAND_QUEUE_SIZE_ENV)
+    if raw_capacity is None or raw_capacity == "":
+        return DEFAULT_COMMAND_QUEUE_CAPACITY
+    try:
+        capacity = int(raw_capacity)
+    except ValueError as exc:
+        raise ValueError(
+            f"{COMMAND_QUEUE_SIZE_ENV} must be an integer"
+        ) from exc
+    if capacity < 1:
+        raise ValueError(f"{COMMAND_QUEUE_SIZE_ENV} must be at least 1")
+    return capacity
+
+
+def _make_smoke_item(
+    response_future: asyncio.Future[Any],
+    tool_name: str = "smoke.tool",
+) -> QueueItem:
+    return QueueItem(
+        correlation_id=str(uuid.uuid4()),
+        client_session_id="smoke-session",
+        client_request_id=1,
+        tool_name=tool_name,
+        arguments={"value": "smoke"},
+        response_future=response_future,
+        enqueued_at=time.monotonic(),
+    )
+
+
+async def _run_smoke() -> None:
+    queue = CommandQueue(capacity=1)
+    response_future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
+    queue.enqueue(_make_smoke_item(response_future))
+
+    async def dispatch_fn(item: QueueItem) -> dict[str, Any]:
+        return {
+            "ok": True,
+            "correlation_id": item.correlation_id,
+            "tool_name": item.tool_name,
+        }
+
+    dispatcher = asyncio.create_task(queue.run_dispatcher(dispatch_fn))
+    result = await asyncio.wait_for(response_future, timeout=1.0)
+    assert result["ok"] is True
+    assert result["tool_name"] == "smoke.tool"
+
+    dispatcher.cancel()
+    with suppress(asyncio.CancelledError):
+        await dispatcher
+
+    full_queue = CommandQueue(capacity=1)
+    full_queue.enqueue(
+        _make_smoke_item(asyncio.get_running_loop().create_future(), "full.first")
+    )
+    try:
+        full_queue.enqueue(
+            _make_smoke_item(
+                asyncio.get_running_loop().create_future(),
+                "full.second",
+            )
+        )
+    except QueueFull as exc:
+        assert exc.queue_depth == 1
+        assert build_queue_full_error(exc.queue_depth)["code"] == -32000
+    else:
+        raise AssertionError("QueueFull was not raised")
+
+
+if __name__ == "__main__":
+    asyncio.run(_run_smoke())
+    print("smoke: PASS")

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()