feat(mcp): MCP server v1 — mount on /mcp, per-agent voice binding, stdio shim (Wave 2.2) (#368)

* feat(mcp): MCP server v1 — mount on /mcp, per-agent voice binding, stdio shim (Wave 2.2)

The FastMCP server (previously dead code, never mounted) is now mounted on
the main FastAPI app at /mcp via Streamable HTTP, with its session manager
composed into the app lifespan through an AsyncExitStack (best-effort: a
missing mcp package or OMNIVOICE_MCP_DISABLE=1 never breaks startup).
streamable_http_path set to '/' so the sub-mount lands at /mcp, not
/mcp/mcp. Adds the 'mcp' dependency (1.27.x).

Per-agent voice binding (Spec 2 headline): each MCP client sends an
X-OmniVoice-Client-Id header; generate_speech resolves the voice as
explicit arg > the client's binding > global default > app default. New
mcp_client_bindings table (alembic 0004 + _BASE_SCHEMA, additive/idempotent),
services/mcp_bindings.py (CRUD + resolve_voice + best-effort last_seen),
and a loopback-gated REST router (/api/mcp/bindings) the Settings panel
drives.

New transcribe tool (base64 audio in, 200 MB cap). Stdio shim
(backend/mcp_shim, httpx-only, ported from voicebox MIT) proxies stdio
clients to the mounted endpoint and forwards OMNIVOICE_CLIENT_ID as the
binding header. Settings → Sharing gains an MCP bindings panel. Docs:
docs/mcp.md (both connection modes + binding REST) and docs/mcp.json
updated to the shim form.

Tests: bindings service + resolution precedence + migration up/down (pure,
run locally); REST CRUD + mount-not-404 + disable-flag (main-importing,
validated in CI). MCP build + mount + initialize handshake verified
out-of-band (no torch).

Spec: docs/competitive-analysis.md Spec 2 / parity program Wave 2.2.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(mcp): assert /mcp mount via app.routes, not a lifespan client

The two main-importing mount tests ran the app lifespan, which now starts
the FastMCP session manager and binds asyncio queues to the test loop —
contaminating later lifespan-running tests ('bound to a different event
loop'). The mount happens at import time, so inspecting app.routes for the
/mcp Mount is the correct loop-free assertion. Same fix shape as the
Wave 0.2 consent tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(mcp): stop reload-main poisoning across the MCP test files

Root cause of the CI failure: the bindings REST fixture set
OMNIVOICE_MCP_DISABLE=1 and reloaded main but never restored it, so a
later 'from main import app' in test_mcp_mount saw /mcp un-mounted
({'/audio','/voice_audio'}). Reloading main mutates the shared module for
every subsequent test.

- REST fixture: drop the disable flag (the mount is harmless without a
  lifespan), yield the client, and restore main (+ core.config/db) to the
  default data dir in teardown so the global module is clean again.
- test_main_mounts_mcp_route: reload main with the disable flag cleared so
  the assertion is independent of any earlier reload.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: debpalash

backend/api/routers/mcp_bindings.py

@@ -0,0 +1,53 @@
+"""REST CRUD for per-agent MCP voice bindings (Wave 2.2 / Spec 2).
+
+Loopback-gated — the Settings UI manages bindings here. The MCP tools
+themselves resolve voices via ``services.mcp_bindings.resolve_voice``.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from api.dependencies import require_loopback
+from services import mcp_bindings
+
+router = APIRouter(
+    prefix="/api/mcp",
+    tags=["mcp"],
+    dependencies=[Depends(require_loopback)],
+)
+
+
+class _BindingBody(BaseModel):
+    client_id: str = Field(..., min_length=1, max_length=128)
+    label: str | None = None
+    profile_id: str | None = None
+    default_engine: str | None = None
+
+
+@router.get("/bindings")
+def list_bindings():
+    """All per-agent voice bindings, most-recently-seen first."""
+    return mcp_bindings.list_bindings()
+
+
+@router.put("/bindings")
+def upsert_binding(body: _BindingBody):
+    """Create or update the binding for an MCP client id."""
+    try:
+        return mcp_bindings.upsert_binding(
+            body.client_id,
+            label=body.label,
+            profile_id=body.profile_id,
+            default_engine=body.default_engine,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/bindings/{client_id}")
+def delete_binding(client_id: str):
+    if not mcp_bindings.delete_binding(client_id):
+        raise HTTPException(status_code=404, detail="No binding for that client id")
+    return {"deleted": client_id}

backend/core/db.py

@@ -142,6 +142,19 @@ def db_conn():
         value TEXT NOT NULL,
         updated_at REAL NOT NULL
     );
+
+    -- Wave 2.2: per-agent MCP voice bindings. An MCP client (Claude Code,
+    -- Cursor, …) identified by the X-OmniVoice-Client-Id header it sends is
+    -- bound to a default voice profile / engine. Fresh installs create it
+    -- here; v0.3.x upgrades get it via alembic 0004.
+    CREATE TABLE IF NOT EXISTS mcp_client_bindings (
+        client_id TEXT PRIMARY KEY,
+        label TEXT NOT NULL DEFAULT '',
+        profile_id TEXT,
+        default_engine TEXT,
+        last_seen_at REAL,
+        created_at REAL
+    );
 """
 
 # Only tables/columns this module is allowed to ALTER. Prevents SQL injection via

backend/main.py

@@ -428,7 +428,23 @@ def _warm():
         capture_preload_task = asyncio.create_task(_preload_capture_asr())
     else:
         logger.info("Capture ASR preload disabled; dictation ASR will load on first use.")
-    yield
+
+    # ── MCP session manager (Wave 2.2) ────────────────────────────────────
+    # FastMCP's Streamable-HTTP transport needs its session manager running
+    # for the lifetime of the app. It's created lazily by streamable_http_app()
+    # (called in mount_mcp below), so we stack its `run()` context into ours
+    # via AsyncExitStack rather than replacing this lifespan. Best-effort: a
+    # missing/broken MCP layer must never stop the rest of the backend.
+    from contextlib import AsyncExitStack
+    async with AsyncExitStack() as _mcp_stack:
+        _sm = getattr(app.state, "mcp_session_manager", None)
+        if _sm is not None:
+            try:
+                await _mcp_stack.enter_async_context(_sm.run())
+                logger.info("MCP server mounted at /mcp")
+            except Exception as e:
+                logger.warning("MCP session manager failed to start: %s", e)
+        yield
     # ── Graceful shutdown (SIGTERM from Tauri, Ctrl+C, etc.) ────────────
     logger.info("Shutdown: cleaning up…")
     idle_task.cancel()
@@ -749,6 +765,27 @@ def health():
 app.include_router(marketplace.router)
 app.include_router(sonitranslate.router)
 app.include_router(settings_router.router)  # Phase 1 AUTH-03 endpoints
+from api.routers import mcp_bindings as _mcp_bindings_router  # noqa: E402
+app.include_router(_mcp_bindings_router.router)  # Wave 2.2 per-agent voice bindings
+
+# ── Mount the MCP server (Wave 2.2) ───────────────────────────────────────
+# FastMCP's Streamable-HTTP app is sub-mounted at /mcp; its session manager is
+# stashed on app.state for the lifespan above to run. Opt-out via
+# OMNIVOICE_MCP_DISABLE=1; best-effort so a missing mcp package or a build
+# without it never breaks startup.
+if os.environ.get("OMNIVOICE_MCP_DISABLE", "").strip().lower() not in ("1", "true", "yes", "on"):
+    try:
+        from mcp_server import create_mcp_server
+
+        _mcp = create_mcp_server()
+        _mcp_app = _mcp.streamable_http_app()
+        app.state.mcp_session_manager = _mcp.session_manager
+        app.mount("/mcp", _mcp_app)
+        logging.getLogger("omnivoice.api").info("MCP app mounted at /mcp")
+    except Exception as _mcp_err:  # noqa: BLE001
+        logging.getLogger("omnivoice.api").info(
+            "MCP server not mounted (%s); /mcp disabled.", _mcp_err
+        )
 
 frontend_path = os.path.join(os.path.dirname(__file__), "..", "frontend", "dist")
 if os.path.exists(frontend_path):

backend/mcp_server.py

@@ -53,6 +53,14 @@ def create_mcp_server():
             "voice design, and video dubbing in 646 languages."
         ),
     )
+    # Serve the Streamable-HTTP transport at the app root so mounting the whole
+    # app at "/mcp" on the main FastAPI yields the endpoint at "/mcp". FastMCP's
+    # default path is "/mcp", which would double-prefix to "/mcp/mcp" when
+    # sub-mounted. Harmless for the standalone CLI run() path.
+    try:
+        mcp.settings.streamable_http_path = "/"
+    except Exception:
+        pass
 
     # ── Helpers ─────────────────────────────────────────────────────────
 
@@ -75,6 +83,21 @@ async def _api_post_form(path: str, data: dict, files: dict | None = None):
 
     # ── Tools ───────────────────────────────────────────────────────────
 
+    def _current_client_id() -> str | None:
+        """The X-OmniVoice-Client-Id of the calling MCP client, if any.
+
+        FastMCP exposes the HTTP request via its request context on the
+        Streamable-HTTP transport; stdio clients (and any version where the
+        accessor differs) simply resolve to None and fall back to the
+        global default voice."""
+        try:
+            req = mcp.get_context().request_context.request
+            if req is not None:
+                return req.headers.get("x-omnivoice-client-id")
+        except Exception:
+            pass
+        return None
+
     @mcp.tool()
     async def generate_speech(
         text: str,
@@ -89,7 +112,8 @@ async def generate_speech(
         Args:
             text: The text to synthesize into speech.
             language: Target language (ISO code or 'Auto'). 646 languages supported.
-            profile_id: ID of a saved voice profile to clone. Omit for voice design mode.
+            profile_id: ID of a saved voice profile to clone. Omit to use this
+                agent's bound voice (Settings → MCP), else the global default.
             instruct: Style instruction (e.g. 'whisper', 'excited', 'narrator').
             speed: Speech speed multiplier (0.5–2.0, default 1.0).
             steps: Diffusion steps (8=fast/draft, 16=balanced, 32=quality).
@@ -98,6 +122,17 @@ async def generate_speech(
             JSON with audio_id, generation_time, audio_duration, and
             base64-encoded WAV data.
         """
+        # Per-agent voice binding (Wave 2.2): explicit arg wins; otherwise
+        # resolve this client's bound profile, then the global default.
+        client_id = _current_client_id()
+        try:
+            from services import mcp_bindings
+            resolved = mcp_bindings.resolve_voice(client_id, profile_id)
+            profile_id = resolved.get("profile_id")
+            mcp_bindings.touch_last_seen(client_id) if client_id else None
+        except Exception:
+            pass  # binding layer unavailable — use whatever was passed
+
         form = {
             "text": text,
             "language": language,
@@ -159,6 +194,34 @@ async def list_languages() -> str:
             '],"note":"Pass any ISO 639 code or set language=Auto for detection."}'
         )
 
+    @mcp.tool()
+    async def transcribe(audio_base64: str, language: str | None = None) -> str:
+        """Transcribe spoken audio to text.
+
+        Args:
+            audio_base64: Base64-encoded audio bytes (wav/mp3/webm/m4a).
+            language: Optional language hint; omit for auto-detect.
+
+        Returns:
+            JSON with the recognized text, language, and duration.
+        """
+        try:
+            raw = base64.b64decode(audio_base64, validate=True)
+        except Exception:
+            return '{"error":"audio_base64 is not valid base64"}'
+        # 200 MB cap — same spirit as voicebox's transcribe gate. Keeps a
+        # buggy/hostile agent from posting an unbounded blob.
+        if len(raw) > 200 * 1024 * 1024:
+            return '{"error":"audio exceeds 200 MB limit"}'
+        data = {}
+        if language:
+            data["language"] = language
+        r = await _api_post_form(
+            "/transcribe", data=data,
+            files={"audio": ("audio.wav", raw, "application/octet-stream")},
+        )
+        return str(r.json())
+
     @mcp.tool()
     async def check_health() -> str:
         """Check if the OmniVoice backend is running and what GPU device is active."""

backend/mcp_shim/__init__.py

@@ -0,0 +1 @@
+"""omnivoice-mcp — stdio MCP shim for clients that only speak stdio."""