stackchan-mcp 0.8.0__tar.gz → 0.9.0__tar.gz

stackchan_mcp-0.9.0/.gitignore

@@ -0,0 +1,41 @@
+# 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/
+
+# Bundled native binaries. The publish workflow builds `opus.dll` on
+# a Windows runner via vcpkg (verified against a pinned SHA256) and
+# drops it under `stackchan_mcp/_libs/` before running `uv build`.
+# Local Windows development can mirror that by either building opus
+# via vcpkg locally, downloading the same DLL from a release
+# artifact, or installing system libopus and copying into `_libs/`.
+# On Linux / macOS the system package manager already provides
+# libopus and this path stays empty. `SOURCES.md` is tracked so the
+# bundling documentation lives alongside the code that consumes it.
+stackchan_mcp/_libs/opus.dll

stackchan_mcp-0.9.0/AGENTS.md

@@ -0,0 +1,79 @@
+# gateway/ AGENTS.md (stackchan-mcp)
+
+Python MCP gateway (`stackchan_mcp` package) developer guide.
+
+For ESP32 firmware build/flash/device operations, see `firmware/AGENTS.md`. For board-specific behavior (servo, touch, avatar), see `firmware/main/boards/stackchan/AGENTS.md`.
+
+## 1. stdio MCP constraint
+
+The gateway runs as a **stdio MCP server** — it lives as long as the host process keeps stdin/stdout open.
+
+- Editing `.env` does NOT reload the running process. **MCP process restart is required** (restart the host application or reconnect).
+- Killing the gateway process directly does NOT auto-restart it. The host must reconnect.
+
+### Verifying token configuration
+
+```bash
+grep "^STACKCHAN_TOKEN=" gateway/.env
+grep "^BEARER_TOKEN=" gateway/.env    # legacy alias
+```
+
+## 2. `STACKCHAN_TOKEN` vs `BEARER_TOKEN` priority
+
+```python
+expected = os.getenv("STACKCHAN_TOKEN") or os.getenv("BEARER_TOKEN")
+```
+
+**`STACKCHAN_TOKEN` takes priority**; `BEARER_TOKEN` is a legacy alias checked only when the primary is empty. Keep both set to the same value as insurance.
+
+The ESP32 firmware token (`CONFIG_DEFAULT_WEBSOCKET_TOKEN` in sdkconfig) must match — see `firmware/AGENTS.md` for details.
+
+## 3. Gateway status check
+
+```bash
+# Process check
+lsof -i :8765 | grep LISTEN          # python LISTEN = OK
+pgrep -fl stackchan_mcp              # process list
+
+# Port conflict check
+lsof -i :8765                        # ESTABLISHED sockets are MCP client connections, not conflicts
+```
+
+If `address already in use ('0.0.0.0', 8765)` occurs, identify the existing process with `lsof` before killing.
+
+## 4. LAN IP changes (gateway side)
+
+The gateway listens on `0.0.0.0:8765`, so LAN IP changes do not directly affect it. The issue is on the ESP32 side — see `firmware/AGENTS.md` for details.
+
+## 5. Validation commands (pre-PR)
+
+```bash
+cd gateway
+uv sync                 # resolve dependencies
+uv run pytest           # tests must pass
+uv run ruff check .     # lint must pass
+```
+
+CI runs the same three commands. A local failure means CI will also fail.
+
+## 6. PyPI publishing
+
+- Bump `version` in `gateway/pyproject.toml`
+- Promote `CHANGELOG.md` `[Unreleased]` Gateway subsection to `[X.Y.Z] - YYYY-MM-DD`
+- Tag push (`git tag vX.Y.Z && git push origin vX.Y.Z`) triggers Trusted Publishing
+- Verify with `pipx install --force stackchan-mcp` after publishing
+
+## 7. `.env` edit checklist
+
+```bash
+# 1. Verify values
+grep "^STACKCHAN_TOKEN=" gateway/.env
+
+# 2. Restart MCP process (host restart or /mcp reconnect)
+
+# 3. Verify reconnection
+# In host: get_status → connected: true / tools_count: 14+
+
+# 4. If token mismatch, also update ESP32 sdkconfig
+#    See firmware/AGENTS.md for token alignment procedure
+```

stackchan_mcp-0.9.0/LICENSE-THIRD-PARTY

@@ -0,0 +1,65 @@
+Third-party software included with stackchan-mcp
+==================================================
+
+The `stackchan-mcp` gateway is distributed under the MIT license (see
+`LICENSE`). The `win_amd64` wheel additionally bundles native binary
+components that are distributed under their own permissive licenses,
+listed below. Non-Windows wheels and the sdist do not contain these
+binaries.
+
+The notices in this file are reproduced verbatim from the upstream
+projects for license-compliance purposes. They apply only to the
+specific binaries listed; the rest of the gateway remains MIT.
+
+--------------------------------------------------------------------------------
+
+Opus codec (libopus)
+--------------------------------------------------------------------------------
+
+Component: `stackchan_mcp/_libs/opus.dll`
+Architecture: `win_amd64` (x86_64)
+Upstream: https://opus-codec.org/
+License: BSD 3-clause + Xiph extension
+
+Copyright 2001-2023 Xiph.Org, Skype Limited, Octasic,
+                    Jean-Marc Valin, Timothy B. Terriberry,
+                    CSIRO, Gregory Maxwell, Mark Borgerding,
+                    Erik de Castro Lopo
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+- Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+- Neither the name of Internet Society, IETF or IETF Trust, nor the
+  names of specific contributors, may be used to endorse or promote
+  products derived from this software without specific prior written
+  permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Opus is also subject to the Internet Society "Note Well" IPR
+disclosure as referenced from RFC 6716. The IPR statement is
+available at:
+
+  https://datatracker.ietf.org/ipr/search/?submit=ipr&rfc=6716
+
+Provenance and SHA256 for the specific binary shipped in each
+release are recorded in `stackchan_mcp/_libs/SOURCES.md` inside the
+wheel.

{stackchan_mcp-0.8.0 → stackchan_mcp-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackchan-mcp
-Version: 0.8.0
+Version: 0.9.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
@@ -8,6 +8,7 @@ Project-URL: Issues, https://github.com/kisaragi-mochi/stackchan-mcp/issues
 Author: kisaragi-mochi
 License-Expression: MIT
 License-File: LICENSE
+License-File: LICENSE-THIRD-PARTY
 Keywords: esp32,llm,mcp,robotics,stackchan,xiaozhi
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -23,10 +24,12 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.10
 Requires-Dist: aiohttp>=3
-Requires-Dist: mcp>=1.0
+Requires-Dist: mcp<2.0,>=1.27
 Requires-Dist: pydantic>=2
 Requires-Dist: python-dotenv
+Requires-Dist: pyyaml>=6
 Requires-Dist: websockets>=12
+Requires-Dist: zeroconf>=0.149
 Provides-Extra: stt
 Requires-Dist: opuslib>=3; extra == 'stt'
 Provides-Extra: stt-faster-whisper
@@ -120,6 +123,29 @@ Default ports:
 - WebSocket (ESP32 -> gateway): `0.0.0.0:8765`
 - HTTP capture (ESP32 -> gateway): `0.0.0.0:8766`
 
+## Daemon mode (Phase B)
+
+For multi-client setups, run one shared Streamable HTTP daemon instead of
+letting each MCP client spawn its own stdio gateway:
+
+```bash
+uv run stackchan-mcp serve --transport streamable-http
+```
+
+The daemon exposes MCP at `http://127.0.0.1:8767/mcp` by default, keeps the
+existing ESP32 WebSocket and capture listeners, and serializes ESP32-bound
+tool calls through a bounded command queue. See
+[`../docs/178-daemon-setup.md`](../docs/178-daemon-setup.md) for environment
+variables, bearer-token rules, `MCP_HTTP_ALLOWED_HOSTS`, bind safety, and
+migration notes.
+
+The zero-subcommand stdio mode remains supported and unchanged for existing
+client configs.
+
+By default, the gateway advertises the WebSocket endpoint as
+`_stackchan-mcp._tcp.local.` via mDNS/DNS-SD so fresh firmware can discover it
+on the local LAN. Run `stackchan-mcp --no-mdns` to disable this advertisement.
+
 For non-LAN setups, see [`../docs/remote-access.md`](../docs/remote-access.md)
 for the Tailscale Funnel flow.
 
@@ -131,10 +157,10 @@ again, check `get_status` from the stdio MCP side to confirm the device is back.
 ## Configuration changes
 
 The gateway reads `.env` once at process start. Because the gateway runs as a
-**stdio MCP server** (it has no standalone CLI mode beyond `--help` /
-`--version` / `--check`), editing `.env` while it is connected to an MCP
-client does not take effect on the running process — and killing the gateway
-process directly will not auto-restart it; the MCP client owns the lifecycle.
+**stdio MCP server** by default, editing `.env` while it is connected to an MCP
+client does not take effect on the running process — and killing that stdio
+gateway process directly will not auto-restart it; the MCP client owns the
+lifecycle. In daemon mode, restart the daemon process after changing `.env`.
 
 After editing `.env` (for example to update `STACKCHAN_TOKEN`, `VISION_URL`,
 or `VISION_TOKEN`):
@@ -278,9 +304,21 @@ asyncio.run(smoke())
 
 ## 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
+The gateway Python code is distributed under the **MIT License** (see
+`LICENSE`). The Windows wheel (`*-win_amd64.whl`) additionally bundles
+a native `opus.dll` built from upstream Opus source via vcpkg by the
+publish workflow. That binary is distributed under the **BSD 3-clause
+license + Xiph extension**; the full notice ships in every
+distribution form (sdist, `py3-none-any` wheel, `win_amd64` wheel) as
+`LICENSE-THIRD-PARTY`. Non-Windows wheels and the sdist do not contain
+any binary subject to that license — they rely on a system `libopus`
+provided by the OS package manager (e.g. `apt install libopus0`,
+`brew install opus`). See `stackchan_mcp/_libs/SOURCES.md` (also
+shipped in the wheel) for build provenance and the per-release
+SHA256 logged by CI.
+
+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.8.0 → stackchan_mcp-0.9.0}/README.md

@@ -75,6 +75,29 @@ Default ports:
 - WebSocket (ESP32 -> gateway): `0.0.0.0:8765`
 - HTTP capture (ESP32 -> gateway): `0.0.0.0:8766`
 
+## Daemon mode (Phase B)
+
+For multi-client setups, run one shared Streamable HTTP daemon instead of
+letting each MCP client spawn its own stdio gateway:
+
+```bash
+uv run stackchan-mcp serve --transport streamable-http
+```
+
+The daemon exposes MCP at `http://127.0.0.1:8767/mcp` by default, keeps the
+existing ESP32 WebSocket and capture listeners, and serializes ESP32-bound
+tool calls through a bounded command queue. See
+[`../docs/178-daemon-setup.md`](../docs/178-daemon-setup.md) for environment
+variables, bearer-token rules, `MCP_HTTP_ALLOWED_HOSTS`, bind safety, and
+migration notes.
+
+The zero-subcommand stdio mode remains supported and unchanged for existing
+client configs.
+
+By default, the gateway advertises the WebSocket endpoint as
+`_stackchan-mcp._tcp.local.` via mDNS/DNS-SD so fresh firmware can discover it
+on the local LAN. Run `stackchan-mcp --no-mdns` to disable this advertisement.
+
 For non-LAN setups, see [`../docs/remote-access.md`](../docs/remote-access.md)
 for the Tailscale Funnel flow.
 
@@ -86,10 +109,10 @@ again, check `get_status` from the stdio MCP side to confirm the device is back.
 ## Configuration changes
 
 The gateway reads `.env` once at process start. Because the gateway runs as a
-**stdio MCP server** (it has no standalone CLI mode beyond `--help` /
-`--version` / `--check`), editing `.env` while it is connected to an MCP
-client does not take effect on the running process — and killing the gateway
-process directly will not auto-restart it; the MCP client owns the lifecycle.
+**stdio MCP server** by default, editing `.env` while it is connected to an MCP
+client does not take effect on the running process — and killing that stdio
+gateway process directly will not auto-restart it; the MCP client owns the
+lifecycle. In daemon mode, restart the daemon process after changing `.env`.
 
 After editing `.env` (for example to update `STACKCHAN_TOKEN`, `VISION_URL`,
 or `VISION_TOKEN`):
@@ -233,9 +256,21 @@ asyncio.run(smoke())
 
 ## 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
+The gateway Python code is distributed under the **MIT License** (see
+`LICENSE`). The Windows wheel (`*-win_amd64.whl`) additionally bundles
+a native `opus.dll` built from upstream Opus source via vcpkg by the
+publish workflow. That binary is distributed under the **BSD 3-clause
+license + Xiph extension**; the full notice ships in every
+distribution form (sdist, `py3-none-any` wheel, `win_amd64` wheel) as
+`LICENSE-THIRD-PARTY`. Non-Windows wheels and the sdist do not contain
+any binary subject to that license — they rely on a system `libopus`
+provided by the OS package manager (e.g. `apt install libopus0`,
+`brew install opus`). See `stackchan_mcp/_libs/SOURCES.md` (also
+shipped in the wheel) for build provenance and the per-release
+SHA256 logged by CI.
+
+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.8.0 → stackchan_mcp-0.9.0}/pyproject.toml

@@ -1,11 +1,16 @@
 [project]
 name = "stackchan-mcp"
-version = "0.8.0"
+version = "0.9.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"]
+# `LICENSE-THIRD-PARTY` carries the BSD-3-Clause + Xiph notice for the
+# native libopus binary bundled into the `win_amd64` wheel. The file is
+# always shipped (sdist and every wheel variant) so license scanners
+# pointed at any distribution form can see it, even though the binary
+# itself is only present in the `win_amd64` wheel.
+license-files = ["LICENSE", "LICENSE-THIRD-PARTY"]
 authors = [
     { name = "kisaragi-mochi" },
 ]
@@ -28,8 +33,19 @@ dependencies = [
     "websockets>=12",
     "pydantic>=2",
     "python-dotenv",
-    "mcp>=1.0",
+    "PyYAML>=6",
+    # The stdio server captures the active ServerSession via a subclassed
+    # Server.run() loop because the public MCP SDK does not yet expose a
+    # stable hook for server-side notifications. That subclass relies on
+    # `Server._experimental_handlers` and `Server._handle_message`, which
+    # are private members. We pin to the verified 1.x line and gate access
+    # behind a startup compatibility guard (see stdio_server.py) so a
+    # future SDK release cannot silently break the gateway via PyPI
+    # auto-resolution. Bump the upper bound after verifying the next
+    # major line.
+    "mcp>=1.27,<2.0",
     "aiohttp>=3",
+    "zeroconf>=0.149",
 ]
 
 [project.optional-dependencies]
@@ -84,3 +100,27 @@ dev = [
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
+
+# Bundle the native libopus binary into the Windows wheel so that
+# `pip install stackchan-mcp[tts]` (or `[stt]`) works out-of-the-box
+# on Windows. The DLL is loaded at import time via
+# `os.add_dll_directory()` in `stackchan_mcp/__init__.py`. See
+# `stackchan_mcp/_libs/SOURCES.md` for provenance and license.
+#
+# Build-time contract: `opus.dll` is NOT tracked in git. The publish
+# workflow builds it from upstream Opus source via vcpkg on a Windows
+# runner (verified against a pinned SHA256), drops it under
+# `stackchan_mcp/_libs/`, then runs `uv build` which produces the
+# `win_amd64` wheel. Builds on non-Windows runners do not place a
+# DLL under `_libs/`, so the sdist and the `py3-none-any` wheel
+# produced on those runners ship without the binary. Glob patterns
+# below match `opus.dll` if and only if it exists at build time, so
+# the same pyproject config covers both wheel variants without an
+# unmatched-pattern error on the non-Windows runner.
+[tool.hatch.build.targets.wheel]
+packages = ["stackchan_mcp"]
+artifacts = [
+    "stackchan_mcp/_libs/opus.dll",
+    "stackchan_mcp/_libs/SOURCES.md",
+    "stackchan_mcp/notify.example.yml",
+]

stackchan_mcp-0.9.0/stackchan_mcp/__init__.py

@@ -0,0 +1,81 @@
+"""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)
+"""
+
+import os as _os
+import platform as _platform
+import sys as _sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path as _Path
+
+try:
+    __version__ = version("stackchan-mcp")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0+unknown"
+
+# Windows: register the bundled native libs directory with the DLL
+# search path before any submodule pulls in `opuslib` (or any other
+# wrapper that calls `ctypes.util.find_library`). On Linux/macOS the
+# system package manager typically already provides libopus, so we do
+# nothing on those platforms.
+#
+# Why this is here and not in tts/__init__.py or stt/__init__.py:
+# opuslib's libopus lookup happens at import time (the wrapper's
+# top-level module unconditionally calls `find_library('opus')` and
+# raises if it returns None). That means we need the DLL search path
+# update to have run before *any* code imports opuslib, no matter
+# which subpackage of stackchan_mcp loads first. The package
+# `__init__.py` is the only place guaranteed to run before all
+# sibling submodules.
+#
+# Why we update BOTH `os.add_dll_directory()` AND `os.environ["PATH"]`:
+# - `os.add_dll_directory()` is the modern, isolated mechanism used by
+#   `LoadLibraryEx(..., LOAD_LIBRARY_SEARCH_USER_DIRS)`. Importantly,
+#   `ctypes.util.find_library()` on Windows uses the legacy
+#   `LoadLibraryW()` path which does **not** consult the
+#   `add_dll_directory()` list (see CPython issue #43603). Since
+#   `opuslib/api/__init__.py` calls exactly that — `find_library('opus')`
+#   — we also have to prepend the directory to PATH so the legacy
+#   resolver picks it up.
+# - We add to `add_dll_directory()` too because direct `ctypes.CDLL(...)`
+#   / extension-module imports use the modern resolver, and we want
+#   bundle discovery to work for both API styles future-proof.
+#
+# See `stackchan_mcp/_libs/SOURCES.md` for the bundled DLL provenance.
+# Architecture gate: the bundled `opus.dll` is built for `win_amd64`
+# (x86_64). On Windows ARM64 / Windows x86 (32-bit), loading the x64
+# DLL would fail with a native-image mismatch — *exactly* the
+# "looks installed but fails at runtime" footgun this bundling is
+# meant to remove. Skip the DLL search-path setup on those
+# architectures so the user falls back to the same
+# "find_library returns None" failure mode they had before this
+# fix, which at least produces a clean ImportError on
+# `import opuslib` rather than a confusing crash inside the DLL
+# loader. A platform-specific wheel build would have rejected those
+# architectures at install time (no compatible wheel), so this
+# guard mostly matters for users who bypass wheel selection (e.g.
+# by installing from sdist on a non-x64 Windows host).
+_machine = _platform.machine().upper() if _sys.platform == "win32" else ""
+_dll_dir_handle = None  # kept alive at module scope; see comment below
+
+if _sys.platform == "win32" and _machine in ("AMD64", "X86_64"):
+    _libs_dir = _Path(__file__).resolve().parent / "_libs"
+    if _libs_dir.is_dir():
+        # Retain the directory handle at module scope. Per CPython docs
+        # (`os.add_dll_directory`), the returned object is "an opaque
+        # value that has a `close()` method ... the returned object
+        # remains valid until close() is called". On garbage
+        # collection, the directory de-registers itself, so direct
+        # `ctypes.CDLL(...)` callers that rely on the modern resolver
+        # path would lose access to the bundle. Holding the handle on
+        # the module keeps the registration live for the process
+        # lifetime — matching the intent documented above for both
+        # `find_library` (legacy) and `LoadLibraryEx` (modern) lookup
+        # paths.
+        _dll_dir_handle = _os.add_dll_directory(str(_libs_dir))
+        _libs_str = str(_libs_dir)
+        _existing_path = _os.environ.get("PATH", "")
+        if _libs_str not in _existing_path.split(_os.pathsep):
+            _os.environ["PATH"] = _libs_str + _os.pathsep + _existing_path

stackchan_mcp-0.9.0/stackchan_mcp/_libs/SOURCES.md

@@ -0,0 +1,130 @@
+# Bundled Native Libraries
+
+This directory contains pre-built native shared libraries that the
+gateway needs on platforms where the system package manager does not
+typically ship them. They are loaded at import time by
+`stackchan_mcp/__init__.py` via `os.add_dll_directory()` (Windows) so
+that `ctypes.util.find_library()` calls inside Python wrapper packages
+(e.g. `opuslib`) resolve to the bundled copy without any user setup.
+
+## Why bundle?
+
+The Python wrapper packages that depend on these libraries (currently
+`opuslib`, pulled in via the `[tts]` and `[stt]` extras) only ship
+Python bindings — they do **not** ship the underlying native library.
+On Linux and macOS most users already have `libopus` available through
+their distro's package manager (`apt install libopus0`,
+`brew install opus`, etc.), but on Windows there is no equivalent
+default install path, which means a plain `pip install stackchan-mcp[tts]`
+fails at runtime with `Could not find Opus library. Make sure it is
+installed.` even though the Python wrappers installed cleanly.
+
+Bundling the Windows binary in the wheel removes that footgun: every
+Windows user who installs `stackchan-mcp[tts]` (or `[stt]`) gets a
+working installation on the first try, with no extra `vcpkg` /
+`conda install -c conda-forge libopus` / manual DLL placement step.
+
+The decision to bundle (vs. download at install time vs. require source
+build) was made on these criteria:
+
+| Criterion | Verdict for libopus |
+|---|---|
+| Maturity of the dependency | Mature (Opus is a frozen IETF codec, RFC 6716, 2012) |
+| Frequency of security advisories | Very low (the codec parser is small and well-audited) |
+| File size | ~480 KB — fits comfortably in the wheel |
+| Re-distribution license | BSD 3-clause (Xiph) — redistribution allowed with attribution |
+| Long-term availability of upstream | Excellent (Xiph.Org maintains the source indefinitely) |
+
+If any of those change (e.g. a future ML-based bundle that ships
+hundreds of MB), revisit and consider the "CI downloads a pinned
+version at build time" approach instead.
+
+## opus.dll
+
+| Field | Value |
+|---|---|
+| Architecture | x86_64 (`win_amd64`) |
+| License | BSD 3-clause + Xiph extension — see <https://opus-codec.org/license/> |
+| Provenance | Built from upstream Opus source by the publish workflow via vcpkg |
+| Build command | `vcpkg install opus:x64-windows` (CI runner: `windows-latest`) |
+
+### Provenance note
+
+`opus.dll` is **not** tracked in git. The publish workflow
+(`.github/workflows/publish.yml`, job `build-windows-wheel`)
+bootstraps a fresh vcpkg checkout on a `windows-latest` runner,
+runs `vcpkg install opus:x64-windows`, copies the produced
+`opus.dll` into `stackchan_mcp/_libs/`, and logs its SHA256 to the
+job log so reviewers can spot vcpkg-side binary drift before a tag
+publishes. The wheel build that follows picks the DLL up via
+`tool.hatch.build.targets.wheel.artifacts` in
+`gateway/pyproject.toml`, and the resulting wheel is renamed from
+`*-py3-none-any.whl` to `*-py3-none-win_amd64.whl` so pip resolves
+it only on Windows x64 installs.
+
+Builds on the Ubuntu runner (sdist + the `py3-none-any` wheel they
+produce) do not place a DLL under `_libs/`, so those distributions
+ship clean — non-Windows installs and non-x64 Windows installs
+either fall back to a system `libopus` (Linux/macOS) or get a
+clean "no compatible wheel" install-time message (Windows ARM64 /
+x86 32-bit).
+
+### Local development
+
+If you need a local Windows checkout to test the bundling path
+(running `uv build` outside CI), mirror the CI step by:
+
+1. Installing libopus via vcpkg (`vcpkg install opus:x64-windows`)
+   and copying the produced DLL into `stackchan_mcp/_libs/opus.dll`.
+2. Or downloading the same `opus.dll` from a release artifact
+   uploaded by the publish workflow.
+3. Or installing system libopus and copying it into the directory.
+
+The DLL is gitignored (see `gateway/.gitignore`) so a local copy
+never sneaks into a commit.
+
+## License compliance
+
+The Opus codec is distributed under the 3-clause BSD license (with the
+optional Xiph patent grant), which permits redistribution in source or
+binary form provided the copyright notice and license text are
+preserved. The canonical notice ships at the top of every gateway
+distribution as `LICENSE-THIRD-PARTY` (declared in
+`gateway/pyproject.toml`'s `license-files`); the same text is
+reproduced below as the bundling-rationale narrative for readers of
+this document.
+
+```
+Copyright 2001-2023 Xiph.Org, Skype Limited, Octasic,
+                    Jean-Marc Valin, Timothy B. Terriberry,
+                    CSIRO, Gregory Maxwell, Mark Borgerding,
+                    Erik de Castro Lopo
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+- Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+- Neither the name of Internet Society, IETF or IETF Trust, nor the
+  names of specific contributors, may be used to endorse or promote
+  products derived from this software without specific prior written
+  permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```