voicemeeter-mcp 0.1.0__tar.gz

voicemeeter_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev]'
+      - name: Lint
+        run: ruff check src tests
+      - name: Tests
+        run: pytest
+      - name: Forbidden terms check
+        env:
+          FORBIDDEN_TERMS: ${{ secrets.FORBIDDEN_TERMS }}
+        run: |
+          if [ -n "$FORBIDDEN_TERMS" ] && git grep -qiE "$FORBIDDEN_TERMS" -- . ; then
+            echo "::error::forbidden terms found in repository"
+            exit 1
+          fi
+      - name: Secret shape check
+        run: |
+          if git grep -nE '(password|refresh_token|client_secret)"?\s*[:=]\s*"[A-Za-z0-9_/-]{20,}' -- ':!tests' ; then
+            echo "::error::possible hardcoded credential"
+            exit 1
+          fi

voicemeeter_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

voicemeeter_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+docs/superpowers/
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/

voicemeeter_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aaronckj
+
+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.

voicemeeter_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: voicemeeter-mcp
+Version: 0.1.0
+Summary: MCP server for controlling Voicemeeter (Basic/Banana/Potato) on Windows: strip and bus gains, mutes, routing, levels, macro buttons, and presets.
+Project-URL: Homepage, https://github.com/aaronckj/voicemeeter-mcp
+Project-URL: Issues, https://github.com/aaronckj/voicemeeter-mcp/issues
+Author: aaronckj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,mcp,mixer,model-context-protocol,streaming,voicemeeter
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.2
+Requires-Dist: voicemeeter-api>=2.5; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# voicemeeter-mcp
+
+An MCP (Model Context Protocol) server for controlling
+[Voicemeeter](https://vb-audio.com/Voicemeeter/) (Basic, Banana, or Potato)
+on Windows: strip and bus gains, mutes, output routing, live levels, macro
+buttons, presets, and audio-engine restarts.
+
+- Uses the official Voicemeeter Remote API (via
+  [voicemeeter-api](https://pypi.org/project/voicemeeter-api/)).
+- **Windows-only, local-only** — the Remote API is an in-process DLL, so this
+  server must run on the PC where Voicemeeter runs. From another machine,
+  connect over SSH stdio (example below).
+- Every mutating tool accepts `dry_run=true` and returns a preview instead of
+  acting.
+
+## Quick start (on the Voicemeeter PC)
+
+```bash
+# select your edition: basic | banana | potato   (default: banana)
+set VM_MCP_KIND=banana
+
+claude mcp add voicemeeter -s user -- uvx voicemeeter-mcp
+```
+
+From a different machine (SSH stdio):
+
+```bash
+claude mcp add voicemeeter -s user -- ssh streampc "uvx voicemeeter-mcp"
+```
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `mixer_state` | full snapshot: every strip/bus with label, gain, mute, routing |
+| `set_strip_gain` / `mute_strip` | input fader control |
+| `set_strip_routing` | send a strip to A1/A2/A3/B1/B2 outputs |
+| `set_bus_gain` / `mute_bus` | output control |
+| `get_levels` | live post-fader levels — find silent or clipping paths |
+| `trigger_macro_button` | press a Voicemeeter macro button |
+| `load_preset` | load a settings XML |
+| `restart_audio_engine` | the classic crackle fix |
+| `health_check` | connection + version |
+
+A typical agent ask: *"the game audio is too loud on stream"* →
+`mixer_state` to find the strip by label → `set_strip_gain(strip, -12)`.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+ruff check src tests && pytest
+```
+
+Tests run anywhere (fake Remote API); only live use requires Windows.
+
+## License
+
+MIT

voicemeeter_mcp-0.1.0/README.md

@@ -0,0 +1,59 @@
+# voicemeeter-mcp
+
+An MCP (Model Context Protocol) server for controlling
+[Voicemeeter](https://vb-audio.com/Voicemeeter/) (Basic, Banana, or Potato)
+on Windows: strip and bus gains, mutes, output routing, live levels, macro
+buttons, presets, and audio-engine restarts.
+
+- Uses the official Voicemeeter Remote API (via
+  [voicemeeter-api](https://pypi.org/project/voicemeeter-api/)).
+- **Windows-only, local-only** — the Remote API is an in-process DLL, so this
+  server must run on the PC where Voicemeeter runs. From another machine,
+  connect over SSH stdio (example below).
+- Every mutating tool accepts `dry_run=true` and returns a preview instead of
+  acting.
+
+## Quick start (on the Voicemeeter PC)
+
+```bash
+# select your edition: basic | banana | potato   (default: banana)
+set VM_MCP_KIND=banana
+
+claude mcp add voicemeeter -s user -- uvx voicemeeter-mcp
+```
+
+From a different machine (SSH stdio):
+
+```bash
+claude mcp add voicemeeter -s user -- ssh streampc "uvx voicemeeter-mcp"
+```
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `mixer_state` | full snapshot: every strip/bus with label, gain, mute, routing |
+| `set_strip_gain` / `mute_strip` | input fader control |
+| `set_strip_routing` | send a strip to A1/A2/A3/B1/B2 outputs |
+| `set_bus_gain` / `mute_bus` | output control |
+| `get_levels` | live post-fader levels — find silent or clipping paths |
+| `trigger_macro_button` | press a Voicemeeter macro button |
+| `load_preset` | load a settings XML |
+| `restart_audio_engine` | the classic crackle fix |
+| `health_check` | connection + version |
+
+A typical agent ask: *"the game audio is too loud on stream"* →
+`mixer_state` to find the strip by label → `set_strip_gain(strip, -12)`.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+ruff check src tests && pytest
+```
+
+Tests run anywhere (fake Remote API); only live use requires Windows.
+
+## License
+
+MIT

voicemeeter_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "voicemeeter-mcp"
+version = "0.1.0"
+description = "MCP server for controlling Voicemeeter (Basic/Banana/Potato) on Windows: strip and bus gains, mutes, routing, levels, macro buttons, and presets."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "aaronckj" }]
+keywords = ["mcp", "voicemeeter", "audio", "mixer", "streaming", "model-context-protocol"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "mcp>=1.2",
+  "voicemeeter-api>=2.5; sys_platform == 'win32'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+voicemeeter-mcp = "voicemeeter_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/aaronckj/voicemeeter-mcp"
+Issues = "https://github.com/aaronckj/voicemeeter-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voicemeeter_mcp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

voicemeeter_mcp-0.1.0/src/voicemeeter_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

voicemeeter_mcp-0.1.0/src/voicemeeter_mcp/__main__.py

@@ -0,0 +1,13 @@
+"""CLI entry: run the MCP server."""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    from .server import build_app
+
+    build_app().run()
+
+
+if __name__ == "__main__":
+    main()

voicemeeter_mcp-0.1.0/src/voicemeeter_mcp/client.py

@@ -0,0 +1,83 @@
+"""Voicemeeter Remote API connection wrapper (via voicemeeter-api / voicemeeterlib)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger("voicemeeter_mcp")
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+# Strip/bus counts per Voicemeeter kind: (hardware strips, virtual strips, buses)
+KINDS = {
+    "basic": (2, 1, 2),
+    "banana": (3, 2, 5),
+    "potato": (5, 3, 8),
+}
+
+
+class VmError(RuntimeError):
+    pass
+
+
+class VM:
+    """Lazy holder for a voicemeeterlib remote (injectable for tests)."""
+
+    def __init__(self, remote: Any = None, kind: str | None = None):
+        self._remote = remote
+        self.kind = kind or os.environ.get("VM_MCP_KIND", "banana")
+        if self.kind not in KINDS:
+            raise VmError(f"unknown Voicemeeter kind: {self.kind!r} (basic|banana|potato)")
+
+    @property
+    def remote(self) -> Any:
+        if self._remote is None:
+            try:
+                import voicemeeterlib
+            except ImportError as exc:
+                raise VmError(
+                    "voicemeeter-api is Windows-only; run this server on the PC "
+                    "where Voicemeeter is installed"
+                ) from exc
+            try:
+                self._remote = voicemeeterlib.api(self.kind)
+                self._remote.login()
+            except Exception as exc:
+                raise VmError(
+                    f"cannot connect to Voicemeeter {self.kind} — is it running? ({exc})"
+                ) from exc
+        return self._remote
+
+    def counts(self) -> tuple[int, int, int]:
+        return KINDS[self.kind]
+
+    def strip(self, i: int) -> Any:
+        hw, virt, _ = self.counts()
+        if not 0 <= i < hw + virt:
+            raise VmError(f"strip index {i} out of range for {self.kind} (0..{hw + virt - 1})")
+        return self.remote.strip[i]
+
+    def bus(self, i: int) -> Any:
+        _, _, buses = self.counts()
+        if not 0 <= i < buses:
+            raise VmError(f"bus index {i} out of range for {self.kind} (0..{buses - 1})")
+        return self.remote.bus[i]
+
+
+def preview(action: str, would: dict) -> dict:
+    return {"preview": True, "action": action, "would": would}
+
+
+_vm: VM | None = None
+
+
+def get_vm() -> VM:
+    global _vm
+    if _vm is None:
+        _vm = VM()
+    return _vm

voicemeeter_mcp-0.1.0/src/voicemeeter_mcp/server.py

@@ -0,0 +1,277 @@
+"""FastMCP app: Voicemeeter strips, buses, macro buttons, presets."""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import get_vm, preview
+
+ROUTES = ("A1", "A2", "A3", "B1", "B2", "B3")
+
+
+def build_app() -> FastMCP:
+    mcp = FastMCP(
+        "voicemeeter",
+        instructions=(
+            "Control Voicemeeter (Basic/Banana/Potato) on this Windows machine: "
+            "strip/bus gains and mutes, output routing, levels, macro buttons, "
+            "and presets. Strips are inputs (hardware first, then virtual); "
+            "buses are outputs (A = hardware, B = virtual). Every mutating tool "
+            "accepts dry_run=True."
+        ),
+    )
+
+    @mcp.tool()
+    def mixer_state() -> dict:
+        """Full mixer snapshot: every strip and bus with label, gain, mute, routing."""
+        vm = get_vm()
+        hw, virt, buses = vm.counts()
+        strips = []
+        for i in range(hw + virt):
+            s = vm.strip(i)
+            routing = {r: bool(getattr(s, r, False)) for r in ROUTES if hasattr(s, r)}
+            strips.append(
+                {
+                    "index": i,
+                    "label": s.label,
+                    "kind": "hardware" if i < hw else "virtual",
+                    "gain_db": round(s.gain, 1),
+                    "muted": bool(s.mute),
+                    "routing": routing,
+                }
+            )
+        bus_list = []
+        for i in range(buses):
+            b = vm.bus(i)
+            bus_list.append(
+                {
+                    "index": i,
+                    "label": b.label,
+                    "gain_db": round(b.gain, 1),
+                    "muted": bool(b.mute),
+                }
+            )
+        return {"kind": vm.kind, "strips": strips, "buses": bus_list}
+
+    @mcp.tool()
+    def set_strip_gain(strip: int, gain_db: float, dry_run: bool = False) -> dict:
+        """Set a strip's fader gain in dB (0 = unity; range -60..+12)."""
+        if dry_run:
+            return preview("set_strip_gain", {"strip": strip, "gain_db": gain_db})
+        vm = get_vm()
+        vm.strip(strip).gain = max(-60.0, min(12.0, gain_db))
+        return {"strip": strip, "gain_db": gain_db}
+
+    @mcp.tool()
+    def mute_strip(strip: int, muted: bool, dry_run: bool = False) -> dict:
+        """Mute or unmute an input strip."""
+        if dry_run:
+            return preview("mute_strip", {"strip": strip, "muted": muted})
+        vm = get_vm()
+        vm.strip(strip).mute = muted
+        return {"strip": strip, "muted": muted}
+
+    @mcp.tool()
+    def set_strip_routing(strip: int, route: str, enabled: bool, dry_run: bool = False) -> dict:
+        """Send or stop sending a strip to an output. route: A1|A2|A3|B1|B2 (kind-dependent)."""
+        route = route.upper()
+        if route not in ROUTES:
+            return {"error": f"route must be one of {ROUTES}"}
+        if dry_run:
+            return preview(
+                "set_strip_routing", {"strip": strip, "route": route, "enabled": enabled}
+            )
+        vm = get_vm()
+        s = vm.strip(strip)
+        if not hasattr(s, route):
+            return {"error": f"{vm.kind} has no {route} routing on strip {strip}"}
+        setattr(s, route, enabled)
+        return {"strip": strip, "route": route, "enabled": enabled}
+
+    @mcp.tool()
+    def set_bus_gain(bus: int, gain_db: float, dry_run: bool = False) -> dict:
+        """Set a bus (output) gain in dB."""
+        if dry_run:
+            return preview("set_bus_gain", {"bus": bus, "gain_db": gain_db})
+        vm = get_vm()
+        vm.bus(bus).gain = max(-60.0, min(12.0, gain_db))
+        return {"bus": bus, "gain_db": gain_db}
+
+    @mcp.tool()
+    def mute_bus(bus: int, muted: bool, dry_run: bool = False) -> dict:
+        """Mute or unmute an output bus."""
+        if dry_run:
+            return preview("mute_bus", {"bus": bus, "muted": muted})
+        vm = get_vm()
+        vm.bus(bus).mute = muted
+        return {"bus": bus, "muted": muted}
+
+    @mcp.tool()
+    def get_levels() -> dict:
+        """Current audio levels (post-fader) per strip and bus — spot silent or clipping paths."""
+        vm = get_vm()
+        hw, virt, buses = vm.counts()
+        return {
+            "strips": [
+                {
+                    "index": i,
+                    "label": vm.strip(i).label,
+                    "levels": list(vm.strip(i).levels.postfader),
+                }
+                for i in range(hw + virt)
+            ],
+            "buses": [
+                {"index": i, "label": vm.bus(i).label, "levels": list(vm.bus(i).levels.all)}
+                for i in range(buses)
+            ],
+        }
+
+    @mcp.tool()
+    def trigger_macro_button(button: int, dry_run: bool = False) -> dict:
+        """Press-and-release a Voicemeeter macro button by index."""
+        if dry_run:
+            return preview("trigger_macro_button", {"button": button})
+        vm = get_vm()
+        vm.remote.button[button].trigger = True
+        vm.remote.button[button].trigger = False
+        return {"triggered": button}
+
+    @mcp.tool()
+    def load_preset(xml_path: str, dry_run: bool = False) -> dict:
+        """Load a Voicemeeter settings XML preset from the local filesystem."""
+        if dry_run:
+            return preview("load_preset", {"xml_path": xml_path})
+        vm = get_vm()
+        vm.remote.set("command.load", xml_path)
+        return {"loaded": xml_path}
+
+    @mcp.tool()
+    def restart_audio_engine(dry_run: bool = False) -> dict:
+        """Restart the Voicemeeter audio engine (fixes crackle/desync; brief dropout)."""
+        if dry_run:
+            return preview("restart_audio_engine", {"note": "brief audio dropout"})
+        vm = get_vm()
+        vm.remote.command.restart()
+        return {"restarted": True}
+
+    @mcp.tool()
+    def snapshot_state(name: str = "baseline") -> dict:
+        """Save the full mixer state (gains, mutes, routing, comp/gate, EQ) to a
+        named snapshot file (letters/digits/_/- only). Take one when the stream
+        sounds RIGHT."""
+        from .snapshots import capture_state, save_snapshot
+
+        vm = get_vm()
+        state = capture_state(vm)
+        try:
+            path = save_snapshot(state, name)
+        except ValueError as exc:
+            return {"error": str(exc)}
+        return {"snapshot_path": str(path), "kind": state["kind"]}
+
+    @mcp.tool()
+    def diff_vs_snapshot(snapshot_path: str) -> dict:
+        """Compare the LIVE mixer state against a saved snapshot — answers
+        'what changed since the known-good config'. Snapshot must live in the
+        snapshot directory (as written by snapshot_state)."""
+        import json as _json
+
+        from .snapshots import capture_state, diff_states, resolve_snapshot_path
+
+        vm = get_vm()
+        try:
+            path = resolve_snapshot_path(snapshot_path)
+        except ValueError as exc:
+            return {"error": str(exc)}
+        baseline = _json.loads(path.read_text())
+        changes = diff_states(baseline, capture_state(vm))
+        return {"changes": changes, "in_sync": not changes}
+
+    @mcp.tool()
+    def set_strip_comp(strip: int, amount: float, dry_run: bool = False) -> dict:
+        """Set a strip's compressor knob (0.0 = off … 10.0 = max)."""
+        if dry_run:
+            return preview("set_strip_comp", {"strip": strip, "amount": amount})
+        vm = get_vm()
+        s = vm.strip(strip)
+        target = getattr(s, "comp", None)
+        if target is None:
+            return {"error": f"strip {strip} has no compressor on {vm.kind}"}
+        amount = max(0.0, min(10.0, amount))
+        if hasattr(target, "knob"):
+            target.knob = amount
+        else:
+            s.comp = amount
+        return {"strip": strip, "comp": amount}
+
+    @mcp.tool()
+    def set_strip_gate(strip: int, amount: float, dry_run: bool = False) -> dict:
+        """Set a strip's noise-gate knob (0.0 = off … 10.0 = max)."""
+        if dry_run:
+            return preview("set_strip_gate", {"strip": strip, "amount": amount})
+        vm = get_vm()
+        s = vm.strip(strip)
+        target = getattr(s, "gate", None)
+        if target is None:
+            return {"error": f"strip {strip} has no gate on {vm.kind}"}
+        amount = max(0.0, min(10.0, amount))
+        if hasattr(target, "knob"):
+            target.knob = amount
+        else:
+            s.gate = amount
+        return {"strip": strip, "gate": amount}
+
+    @mcp.tool()
+    def set_bus_eq(bus: int, enabled: bool, dry_run: bool = False) -> dict:
+        """Enable or disable the parametric EQ on a bus."""
+        if dry_run:
+            return preview("set_bus_eq", {"bus": bus, "enabled": enabled})
+        vm = get_vm()
+        b = vm.bus(bus)
+        target = getattr(b, "eq", None)
+        if target is None:
+            return {"error": f"bus {bus} has no EQ on {vm.kind}"}
+        if hasattr(target, "on"):
+            target.on = enabled
+        else:
+            b.eq = enabled
+        return {"bus": bus, "eq": enabled}
+
+    @mcp.tool()
+    def set_strip_device(
+        strip: int, device_name: str, driver: str = "wdm", dry_run: bool = False
+    ) -> dict:
+        """Bind a hardware strip to a physical input device.
+        driver: wdm|mme|ks|asio. Hardware strips only (virtual strips have no device)."""
+        if driver not in ("wdm", "mme", "ks", "asio"):
+            return {"error": "driver must be wdm|mme|ks|asio"}
+        if dry_run:
+            return preview(
+                "set_strip_device", {"strip": strip, "device": device_name, "driver": driver}
+            )
+        vm = get_vm()
+        hw, _, _ = vm.counts()
+        if strip >= hw:
+            return {"error": f"strip {strip} is virtual; only strips 0..{hw - 1} take devices"}
+        s = vm.strip(strip)
+        setattr(s.device, driver, device_name)
+        return {"strip": strip, "device": device_name, "driver": driver}
+
+    @mcp.tool()
+    def health_check() -> dict:
+        """Verify connection to Voicemeeter and report kind/version."""
+        try:
+            vm = get_vm()
+            hw, virt, buses = vm.counts()
+            _ = vm.strip(0).label
+            return {
+                "status": "ok",
+                "kind": vm.kind,
+                "strips": hw + virt,
+                "buses": buses,
+                "version": getattr(vm.remote, "version", "unknown"),
+            }
+        except Exception as exc:  # noqa: BLE001 - health check reports, never raises
+            return {"status": f"error: {exc}"}
+
+    return mcp

voicemeeter_mcp-0.1.0/src/voicemeeter_mcp/snapshots.py

@@ -0,0 +1,80 @@
+"""Mixer state snapshots and diffs — "what changed since the known-good config"."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+SNAPSHOT_DIR = Path.home() / ".config" / "voicemeeter-mcp" / "snapshots"
+_NAME_RE = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+
+def resolve_snapshot_path(path: str) -> Path:
+    """Resolve a snapshot path, refusing anything outside SNAPSHOT_DIR."""
+    rp = Path(path).expanduser().resolve()
+    base = SNAPSHOT_DIR.resolve()
+    if not rp.is_relative_to(base):
+        raise ValueError(f"snapshot path must be inside {base}")
+    return rp
+
+STRIP_PARAMS = ("gain", "mute", "A1", "A2", "A3", "B1", "B2", "B3", "comp", "gate")
+BUS_PARAMS = ("gain", "mute", "eq")
+
+
+def capture_state(vm) -> dict:
+    hw, virt, buses = vm.counts()
+    state: dict = {"kind": vm.kind, "strips": {}, "buses": {}}
+    for i in range(hw + virt):
+        s = vm.strip(i)
+        entry = {"label": s.label}
+        for p in STRIP_PARAMS:
+            if hasattr(s, p):
+                v = getattr(s, p)
+                # comp/gate are sub-objects (knob) in some lib versions
+                v = getattr(v, "knob", v)
+                entry[p] = round(v, 2) if isinstance(v, float) else v
+        state["strips"][str(i)] = entry
+    for i in range(buses):
+        b = vm.bus(i)
+        entry = {"label": b.label}
+        for p in BUS_PARAMS:
+            if hasattr(b, p):
+                v = getattr(b, p)
+                v = getattr(v, "on", v)
+                entry[p] = round(v, 2) if isinstance(v, float) else v
+        state["buses"][str(i)] = entry
+    return state
+
+
+def diff_states(baseline: dict, current: dict) -> list[dict]:
+    """List every parameter that differs between two snapshots."""
+    changes: list[dict] = []
+    for section, singular in (("strips", "strip"), ("buses", "bus")):
+        base_sec = baseline.get(section, {})
+        cur_sec = current.get(section, {})
+        for idx in sorted(set(base_sec) | set(cur_sec), key=lambda x: int(x)):
+            b = base_sec.get(idx, {})
+            c = cur_sec.get(idx, {})
+            for key in sorted(set(b) | set(c)):
+                if b.get(key) != c.get(key):
+                    changes.append(
+                        {
+                            "where": f"{singular} {idx} ({c.get('label') or b.get('label')})",
+                            "param": key,
+                            "baseline": b.get(key),
+                            "current": c.get(key),
+                        }
+                    )
+    return changes
+
+
+def save_snapshot(state: dict, name: str) -> Path:
+    if not _NAME_RE.match(name):
+        raise ValueError("snapshot name must be 1-64 chars of letters, digits, _ or -")
+    SNAPSHOT_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+    path = SNAPSHOT_DIR / f"{name}-{stamp}.json"
+    path.write_text(json.dumps(state, indent=2))
+    return path

voicemeeter_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,102 @@
+import asyncio
+import json
+from types import SimpleNamespace
+
+import voicemeeter_mcp.client as client_mod
+from voicemeeter_mcp.client import VM, VmError
+from voicemeeter_mcp.server import build_app
+
+EXPECTED = {
+    "mixer_state", "set_strip_gain", "mute_strip", "set_strip_routing",
+    "set_bus_gain", "mute_bus", "get_levels", "trigger_macro_button",
+    "load_preset", "restart_audio_engine", "health_check",
+    "snapshot_state", "diff_vs_snapshot", "set_strip_comp", "set_strip_gate",
+    "set_bus_eq", "set_strip_device",
+}
+
+
+class FakeStrip:
+    def __init__(self, label):
+        self.label = label
+        self.gain = 0.0
+        self.mute = False
+        self.A1 = True
+        self.A2 = False
+        self.B1 = False
+        self.levels = SimpleNamespace(postfader=[-20.0, -20.0])
+
+
+class FakeBus:
+    def __init__(self, label):
+        self.label = label
+        self.gain = 0.0
+        self.mute = False
+        self.levels = SimpleNamespace(all=[-18.0, -18.0])
+
+
+class FakeRemote:
+    def __init__(self):
+        self.strip = [FakeStrip(f"strip{i}") for i in range(5)]
+        self.bus = [FakeBus(f"bus{i}") for i in range(5)]
+        self.version = "banana 2.1.1.4"
+
+
+def make_app():
+    client_mod._vm = VM(remote=FakeRemote(), kind="banana")
+    return build_app()
+
+
+def teardown_function():
+    client_mod._vm = None
+
+
+def call_tool(app, name, args=None):
+    result = asyncio.run(app.call_tool(name, args or {}))
+    blocks = result[0] if isinstance(result, tuple) else result
+    return json.loads(blocks[0].text)
+
+
+def test_all_tools_registered():
+    app = make_app()
+    tools = asyncio.run(app.list_tools())
+    assert {t.name for t in tools} == EXPECTED
+
+
+def test_mixer_state_counts_banana():
+    app = make_app()
+    out = call_tool(app, "mixer_state")
+    assert out["kind"] == "banana"
+    assert len(out["strips"]) == 5  # 3 hardware + 2 virtual
+    assert len(out["buses"]) == 5
+    assert out["strips"][0]["routing"]["A1"] is True
+
+
+def test_set_strip_gain_clamps():
+    app = make_app()
+    call_tool(app, "set_strip_gain", {"strip": 0, "gain_db": -100})
+    assert client_mod._vm.strip(0).gain == -60.0
+
+
+def test_mute_strip_dry_run_no_change():
+    app = make_app()
+    out = call_tool(app, "mute_strip", {"strip": 1, "muted": True, "dry_run": True})
+    assert out["preview"] is True
+    assert client_mod._vm.strip(1).mute is False
+
+
+def test_routing_validation():
+    app = make_app()
+    out = call_tool(app, "set_strip_routing", {"strip": 0, "route": "Z9", "enabled": True})
+    assert "error" in out
+    out = call_tool(app, "set_strip_routing", {"strip": 0, "route": "b1", "enabled": True})
+    assert out["enabled"] is True
+    assert client_mod._vm.strip(0).B1 is True
+
+
+def test_strip_index_out_of_range():
+    client_mod._vm = VM(remote=FakeRemote(), kind="banana")
+    try:
+        client_mod._vm.strip(9)
+        raise AssertionError("expected VmError")
+    except VmError as exc:
+        assert "out of range" in str(exc)

voicemeeter_mcp-0.1.0/tests/test_snapshots.py

@@ -0,0 +1,81 @@
+from types import SimpleNamespace
+
+from voicemeeter_mcp.client import VM
+from voicemeeter_mcp.snapshots import capture_state, diff_states
+
+
+class Knob:
+    def __init__(self, v):
+        self.knob = v
+
+
+class FakeStrip:
+    def __init__(self, label, gain=0.0):
+        self.label = label
+        self.gain = gain
+        self.mute = False
+        self.A1 = True
+        self.B1 = False
+        self.comp = Knob(0.0)
+        self.gate = Knob(2.5)
+        self.levels = SimpleNamespace(postfader=[-20.0])
+
+
+class FakeBus:
+    def __init__(self, label):
+        self.label = label
+        self.gain = 0.0
+        self.mute = False
+        self.eq = SimpleNamespace(on=False)
+        self.levels = SimpleNamespace(all=[-18.0])
+
+
+class FakeRemote:
+    def __init__(self):
+        self.strip = [FakeStrip(f"s{i}") for i in range(5)]
+        self.bus = [FakeBus(f"b{i}") for i in range(5)]
+
+
+def test_capture_and_diff_roundtrip():
+    vm = VM(remote=FakeRemote(), kind="banana")
+    baseline = capture_state(vm)
+    assert baseline["strips"]["0"]["gate"] == 2.5
+    assert diff_states(baseline, capture_state(vm)) == []
+
+
+def test_diff_detects_changes():
+    vm = VM(remote=FakeRemote(), kind="banana")
+    baseline = capture_state(vm)
+    vm.remote.strip[1].gain = -12.0
+    vm.remote.strip[1].mute = True
+    vm.remote.bus[0].eq = SimpleNamespace(on=True)
+    changes = diff_states(baseline, capture_state(vm))
+    params = {(c["where"], c["param"]) for c in changes}
+    assert ("strip 1 (s1)", "gain") in params
+    assert ("strip 1 (s1)", "mute") in params
+    assert ("bus 0 (b0)", "eq") in params
+    assert len(changes) == 3
+
+
+def test_snapshot_name_rejects_traversal():
+    import pytest
+
+    from voicemeeter_mcp.snapshots import save_snapshot
+
+    with pytest.raises(ValueError):
+        save_snapshot({}, "../../evil")
+    with pytest.raises(ValueError):
+        save_snapshot({}, "a/b")
+
+
+def test_resolve_snapshot_path_confined(tmp_path):
+    import pytest
+
+    from voicemeeter_mcp import snapshots
+
+    with pytest.raises(ValueError):
+        snapshots.resolve_snapshot_path("/etc/passwd")
+    with pytest.raises(ValueError):
+        snapshots.resolve_snapshot_path(str(snapshots.SNAPSHOT_DIR / ".." / "x.json"))
+    ok = snapshots.SNAPSHOT_DIR / "good.json"
+    assert snapshots.resolve_snapshot_path(str(ok)) == ok.resolve()