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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.2.0
+Version: 0.3.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

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

@@ -1,6 +1,6 @@
 [project]
 name = "stackchan-mcp"
-version = "0.2.0"
+version = "0.3.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/__init__.py

@@ -0,0 +1,12 @@
+"""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)
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("stackchan-mcp")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0+unknown"

stackchan_mcp-0.3.0/stackchan_mcp/cli.py

@@ -0,0 +1,540 @@
+"""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 argparse
+import asyncio
+import errno
+import logging
+import os
+import shutil
+import socket
+import subprocess
+import sys
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+
+from . import __version__
+
+logger = logging.getLogger(__name__)
+
+
+_DESCRIPTION = (
+    "stdio MCP gateway for the StackChan / xiaozhi-esp32 firmware. "
+    "Bridges stdio MCP clients (for example Claude Code) to a StackChan "
+    "ESP32 device over WebSocket, and exposes an HTTP capture endpoint "
+    "for photo uploads from the device."
+)
+
+_EPILOG = """\
+Environment variables:
+  STACKCHAN_TOKEN   Bearer token shared with the ESP32 firmware.
+  VISION_URL        Full public capture URL (e.g. Tailscale Funnel).
+  VISION_HOST       LAN IP of this machine, as seen from the ESP32.
+  VISION_TOKEN      Optional separate token for VISION_URL uploads.
+  HOST              Bind address for the ESP32 WebSocket server (default 0.0.0.0).
+  WS_PORT           Port for the ESP32 WebSocket server (default 8765).
+  CAPTURE_PORT      Port for the HTTP capture server (default 8766).
+
+See gateway/README.md and the top-level README.md for full setup,
+including pairing the ESP32 firmware and configuring the WiFi gateway URL.
+"""
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="stackchan-mcp",
+        description=_DESCRIPTION,
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help=(
+            "Run a non-destructive preflight (configuration, port "
+            "availability, derived URLs) and exit. Exit 0 if ready to run, "
+            "non-zero if at least one blocking issue is found."
+        ),
+    )
+    return parser
+
+
+# --- Preflight diagnostics (--check) ----------------------------------------
+#
+# The preflight is intentionally side-effect-free: it loads ``.env``, reads
+# environment variables, attempts non-blocking ``bind()`` calls to the two
+# server ports, and prints a concise human-readable report. It does NOT
+# reach out to any ESP32, does not start either server, and does not modify
+# any files. Live device connectivity belongs in a future ``status``
+# subcommand (Issue #54 "Out of scope" note).
+
+
+_BIND_ERROR_PREFIX = "bind error: "
+
+
+def _check_port(host: str, port: int) -> tuple[bool, str | None]:
+    """Probe ``(host, port)`` by trying to ``bind()`` it across every family.
+
+    Resolves ``host`` via ``getaddrinfo`` with ``AF_UNSPEC`` and walks
+    each (family, sockaddr) candidate so the preflight matches the
+    same dual-stack behaviour as ``websockets.serve`` / ``aiohttp``.
+    A literal ``::1`` or an IPv6-resolving ``localhost`` is therefore
+    probed against the right address family rather than being
+    misreported by an ``AF_INET``-only socket.
+
+    Returns ``(available, info)``:
+
+    - ``(True, None)``: at least one address family bound successfully.
+      (Some IPv6 stacks fail with ``EADDRNOTAVAIL`` on hosts without a
+      configured v6 interface; the gateway also tolerates that, so we
+      report "ready" if any candidate succeeded.)
+    - ``(False, "pid <N>, <cmd>")``: at least one candidate reported
+      ``EADDRINUSE``. We short-circuit on the first one because the
+      gateway will collide with the holder regardless of any other
+      family that may have been free.
+    - ``(False, None)``: same as above, but ``lsof`` could not identify
+      the holder (or is unavailable on this platform).
+    - ``(False, "bind error: <reason>")``: every candidate failed for
+      a non-``EADDRINUSE`` reason (typically ``EADDRNOTAVAIL`` for an
+      IP that is not assigned to any local interface, or ``EACCES`` on
+      a privileged port without permission). Distinguishing this from
+      "in use" prevents users from chasing a phantom process when the
+      real issue is the bind address.
+    """
+    try:
+        infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    except socket.gaierror as exc:
+        return (False, f"{_BIND_ERROR_PREFIX}getaddrinfo failed: {exc}")
+
+    last_error: str | None = None
+    bound_at_least_once = False
+    for family, socktype, proto, _canonname, sockaddr in infos:
+        sock = socket.socket(family, socktype, proto)
+        # Mirror ``asyncio.create_server``'s default behaviour on POSIX:
+        # the gateway sets SO_REUSEADDR=1, so a port in TIME_WAIT after
+        # a recent gateway restart would NOT actually block a fresh
+        # bind. Without this option the preflight would misreport such
+        # a port as IN USE and exit non-zero, even though the gateway
+        # itself would start cleanly. SO_REUSEADDR does not let the
+        # bind succeed when another process is currently LISTENing on
+        # the port (POSIX semantics), so the EADDRINUSE branch below
+        # still fires for genuine collisions.
+        if hasattr(socket, "SO_REUSEADDR"):
+            try:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            except OSError:
+                # Some platforms reject SO_REUSEADDR for certain socket
+                # types; fall through and try the bind anyway.
+                pass
+        try:
+            try:
+                sock.bind(sockaddr)
+            except OSError as exc:
+                if exc.errno == errno.EADDRINUSE:
+                    # Mirror gateway behaviour: an EADDRINUSE on any
+                    # candidate family means the gateway will collide.
+                    return (False, _try_get_port_holder(port))
+                reason = exc.strerror or (
+                    os.strerror(exc.errno)
+                    if exc.errno is not None
+                    else str(exc)
+                )
+                last_error = f"{_BIND_ERROR_PREFIX}{reason}"
+            else:
+                bound_at_least_once = True
+        finally:
+            sock.close()
+
+    if bound_at_least_once:
+        return (True, None)
+    return (False, last_error)
+
+
+def _try_get_port_holder(port: int) -> str | None:
+    """Best-effort lookup of the process holding ``port`` via ``lsof``.
+
+    Returns ``"pid <N>, <cmd>"`` on success, or ``None`` if ``lsof`` is
+    not installed, the call fails, or the port is not in fact held (for
+    example, the bind failure was due to a permission error rather than
+    EADDRINUSE).
+    """
+    if shutil.which("lsof") is None:
+        return None
+    try:
+        result = subprocess.run(
+            ["lsof", f"-iTCP:{port}", "-sTCP:LISTEN", "-Fpcn"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0 or not result.stdout:
+        return None
+    pid: str | None = None
+    cmd: str | None = None
+    for line in result.stdout.splitlines():
+        if line.startswith("p"):
+            pid = line[1:]
+        elif line.startswith("c"):
+            cmd = line[1:]
+    if pid and cmd:
+        return f"pid {pid}, {cmd}"
+    if pid:
+        return f"pid {pid}"
+    return None
+
+
+def _format_port_status(available: bool, holder: str | None) -> str:
+    if available:
+        return "AVAILABLE"
+    if holder is None:
+        return "IN USE"
+    if holder.startswith(_BIND_ERROR_PREFIX):
+        # Don't say "IN USE" for non-EADDRINUSE bind failures
+        # (EADDRNOTAVAIL, EACCES, etc.). Surface the actual reason
+        # instead so the user does not chase a phantom process.
+        reason = holder.removeprefix(_BIND_ERROR_PREFIX)
+        return f"BIND ERROR ({reason})"
+    return f"IN USE ({holder})"
+
+
+_TCP_PORT_RANGE = range(0, 65536)
+
+
+def _validate_port_value(raw: str, var: str) -> tuple[int | None, str]:
+    """Parse ``raw`` as a TCP port, returning ``(port, source_or_error)``.
+
+    Returns ``(int_value, var)`` for a valid in-range integer (0..65535
+    inclusive — ``0`` lets the OS pick, which the gateway may not
+    actually want but is at least bind-able). Returns ``(None, "<var>=
+    <raw> (...)")`` otherwise; the caller treats that as a blocking
+    issue rather than silently falling through to a default.
+
+    Both branches matter for the preflight: ``socket.bind()`` raises
+    ``OverflowError`` for values outside the TCP port range, so without
+    this validation ``--check`` would crash with a stack trace instead
+    of producing the diagnostic report it exists to produce.
+    """
+    try:
+        value = int(raw)
+    except ValueError:
+        return (None, f"{var}={raw!r} (not an integer)")
+    if value not in _TCP_PORT_RANGE:
+        return (None, f"{var}={raw!r} (out of TCP port range 0-65535)")
+    return (value, var)
+
+
+def _resolve_ws_port() -> tuple[int | None, str]:
+    """Resolve the WebSocket port using the same precedence as ``gateway.py``.
+
+    Mirrors ``int(os.getenv("WS_PORT", os.getenv("PORT", "8765")))`` from
+    ``gateway.py`` so the preflight checks the port the gateway will
+    actually bind, not a hard-coded default. See ``_validate_port_value``
+    for the validation rules; on success returns ``(port, "WS_PORT")``
+    or ``(port, "PORT")``, otherwise ``(None, "<var>=<raw> (...)")``.
+    """
+    for var in ("WS_PORT", "PORT"):
+        raw = os.getenv(var)
+        if raw is None:
+            continue
+        return _validate_port_value(raw, var)
+    return (8765, "default")
+
+
+def _resolve_capture_port() -> tuple[int | None, str]:
+    """Resolve the HTTP capture port using ``gateway.py``'s precedence.
+
+    Mirrors ``int(os.getenv("CAPTURE_PORT", "8766"))``. See
+    ``_validate_port_value`` for the validation rules.
+    """
+    raw = os.getenv("CAPTURE_PORT")
+    if raw is None:
+        return (8766, "default")
+    return _validate_port_value(raw, "CAPTURE_PORT")
+
+
+# Exact query parameter names that are always redacted in preflight
+# output. Compared lowercased.
+_SECRET_QUERY_KEYS = frozenset(
+    {
+        "access_token",
+        "api_key",
+        "apikey",
+        "auth",
+        "auth_token",
+        "key",
+        "password",
+        "secret",
+        "sig",
+        "signature",
+        "token",
+    }
+)
+
+# Suffix-based heuristic for redacting provider-specific signed-URL
+# parameters without enumerating every variant. Matches things like
+# ``X-Amz-Signature``, ``X-Amz-Security-Token``, ``X-Goog-Signature``,
+# Azure SAS ``sig`` (already covered by the exact set), generic
+# ``*_token`` / ``*-secret`` patterns, etc. Compared lowercased.
+_SECRET_QUERY_KEY_SUFFIXES = (
+    "signature",
+    "token",
+    "secret",
+    "password",
+    "credential",
+    "credentials",
+)
+
+
+def _is_secret_query_key(key: str) -> bool:
+    lower = key.lower()
+    if lower in _SECRET_QUERY_KEYS:
+        return True
+    return any(lower.endswith(suffix) for suffix in _SECRET_QUERY_KEY_SUFFIXES)
+
+
+def _redact_url_secrets(url: str) -> str:
+    """Mask userinfo and secret-looking query params in ``url``.
+
+    The preflight output is meant to be safe to paste into a public
+    issue or log, so any in-URL credential is replaced before
+    printing:
+
+    - ``https://user:pass@host/path`` → ``https://***:***@host/path``
+    - ``?token=abc&page=1`` → ``?token=%2A%2A%2Aredacted%2A%2A%2A&page=1``
+      (only keys in ``_SECRET_QUERY_KEYS`` are touched; non-secret
+      params keep their value)
+
+    Non-credential structure (scheme, host, port, path, fragment,
+    non-secret query keys) is preserved so users can still see what
+    the gateway is actually configured to call. Inputs that fail to
+    parse are returned unchanged so the preflight never crashes on a
+    malformed value.
+    """
+    try:
+        parsed = urlparse(url)
+    except (ValueError, TypeError):
+        return url
+
+    netloc = parsed.netloc
+    if "@" in netloc:
+        # Strip userinfo and replace with a fixed placeholder. Don't
+        # try to preserve the username — the username alone can leak
+        # information and the structural info we care about (host,
+        # port) lives after the @.
+        _userinfo, _, host_part = netloc.rpartition("@")
+        netloc = f"***:***@{host_part}"
+
+    query = parsed.query
+    if query:
+        try:
+            params = parse_qsl(query, keep_blank_values=True)
+        except ValueError:
+            params = None
+        if params is not None:
+            redacted = [
+                (k, "***redacted***") if _is_secret_query_key(k) else (k, v)
+                for k, v in params
+            ]
+            query = urlencode(redacted)
+
+    return urlunparse(
+        (parsed.scheme, netloc, parsed.path, parsed.params, query, parsed.fragment)
+    )
+
+
+def _load_dotenv() -> None:
+    """Lazy ``.env`` loader exposed as a single attachable seam.
+
+    Wrapping ``python-dotenv`` here keeps two properties:
+
+    1. ``import stackchan_mcp.cli`` stays side-effect free (the
+       ``dotenv`` import only happens when the gateway / preflight is
+       actually invoked).
+    2. Tests can ``monkeypatch.setattr(cli, "_load_dotenv", ...)`` to
+       prevent the real ``find_dotenv()`` walking up to the developer's
+       ``gateway/.env`` and contaminating environment-isolation tests.
+    """
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+
+def _run_preflight() -> int:
+    """Run preflight diagnostics. Returns the desired process exit code.
+
+    Output is intentionally fixed-width and grep-friendly. Exit 0 means
+    "ready to run"; non-zero means at least one blocking issue (currently
+    only port unavailability). Missing optional configuration is reported
+    but does not fail the check, mirroring how the gateway itself only
+    warns about a missing ``STACKCHAN_TOKEN``.
+    """
+    _load_dotenv()
+
+    issues = 0
+    print(f"stackchan-mcp {__version__} preflight")
+    print()
+
+    # --- Configuration ------------------------------------------------------
+    print("Configuration:")
+    token = os.getenv("STACKCHAN_TOKEN") or os.getenv("BEARER_TOKEN")
+    if token:
+        print("  STACKCHAN_TOKEN     set (***redacted***)")
+    else:
+        print("  STACKCHAN_TOKEN     not set (gateway will accept any client)")
+
+    vision_host = os.getenv("VISION_HOST", "")
+    capture_port_raw = os.getenv("CAPTURE_PORT", "8766")
+    if vision_host:
+        print(f"  VISION_HOST         {vision_host}")
+    else:
+        print("  VISION_HOST         not set")
+
+    vision_url_explicit = os.getenv("VISION_URL", "")
+    if vision_url_explicit:
+        print(f"  VISION_URL          {_redact_url_secrets(vision_url_explicit)}")
+    elif vision_host:
+        # Derived URL has no userinfo or query params, so no redaction
+        # needed; the host part is shown as-is by design (it is the IP
+        # the user has configured for capture).
+        derived = f"http://{vision_host}:{capture_port_raw}/capture"
+        print(f"  VISION_URL          (derived) {derived}")
+    else:
+        print(
+            "  VISION_URL          not set "
+            "(set VISION_HOST or VISION_URL for take_photo)"
+        )
+
+    if os.getenv("VISION_TOKEN"):
+        print("  VISION_TOKEN        set (***redacted***)")
+    else:
+        print("  VISION_TOKEN        not set (will reuse STACKCHAN_TOKEN)")
+
+    # --- Ports --------------------------------------------------------------
+    print()
+    print("Ports:")
+    host = os.getenv("HOST", "0.0.0.0")
+    ws_port, ws_source = _resolve_ws_port()
+    cap_port, cap_source = _resolve_capture_port()
+
+    if ws_port is None:
+        print(f"  ws://{host}:???     INVALID ({ws_source})")
+        issues += 1
+    if cap_port is None:
+        print(f"  http://{host}:???   INVALID ({cap_source})")
+        issues += 1
+
+    if (
+        ws_port is not None
+        and cap_port is not None
+        and ws_port == cap_port
+        and ws_port != 0
+    ):
+        # The gateway runs WebSocket and HTTP capture as separate
+        # listeners; binding the WebSocket server first will then make
+        # the HTTP bind fail. Independent _check_port probes can't see
+        # this on their own (each one binds-and-releases), so we surface
+        # the conflict explicitly.
+        #
+        # Port 0 is excluded: each ``bind((host, 0))`` asks the OS for a
+        # fresh ephemeral port, so two listeners both configured with 0
+        # do NOT collide (this is exactly the configuration the existing
+        # gateway tests use).
+        print(
+            f"  WS_PORT ({ws_source}) and CAPTURE_PORT ({cap_source}) "
+            f"both resolve to {ws_port}; the gateway needs distinct ports."
+        )
+        issues += 1
+
+    if ws_port is not None:
+        ws_available, ws_holder = _check_port(host, ws_port)
+        print(
+            f"  ws://{host}:{ws_port}   "
+            f"{_format_port_status(ws_available, ws_holder)}"
+        )
+        if not ws_available:
+            issues += 1
+
+    if cap_port is not None:
+        cap_available, cap_holder = _check_port(host, cap_port)
+        print(
+            f"  http://{host}:{cap_port} "
+            f"{_format_port_status(cap_available, cap_holder)}"
+        )
+        if not cap_available:
+            issues += 1
+
+    # --- Result -------------------------------------------------------------
+    print()
+    if issues == 0:
+        print("Result: ready. Exit 0.")
+        return 0
+    plural = "s" if issues > 1 else ""
+    print(f"Result: {issues} issue{plural}. Exit 1.")
+    return 1
+
+
+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(argv: list[str] | None = None) -> None:
+    """Console-script entry point.
+
+    Parses ``--help`` / ``--version`` / ``--check`` early (without
+    starting the server), then loads ``.env``, configures logging, and
+    starts the gateway. Side effects are intentionally scoped to this
+    function so that ``import stackchan_mcp`` stays clean.
+    """
+    parser = _build_arg_parser()
+    # argparse exits with status 0 on --help / --version before reaching
+    # any of the gateway start-up below, which is the intended behaviour.
+    args = parser.parse_args(argv)
+
+    if args.check:
+        # ``_run_preflight`` loads ``.env`` itself; do not double-load
+        # via the path below.
+        sys.exit(_run_preflight())
+
+    _load_dotenv()
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()