voice-mcp-server 0.1.0

package/src/daemon/audio_server.py

@@ -0,0 +1,363 @@
+import asyncio
+import sys
+import os
+import time
+import threading
+import queue
+import logging
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request, HTTPException
+from fastapi.responses import StreamingResponse
+from hydra import compose, initialize
+from hydra.utils import instantiate
+
+# Enforce strict model download locations BEFORE loading any ML libraries
+app_support_dir = os.path.expanduser("~/Library/Application Support/VoiceMCP/models")
+os.makedirs(app_support_dir, exist_ok=True)
+os.environ["HF_HOME"] = os.path.join(app_support_dir, "huggingface")
+os.environ["TORCH_HOME"] = os.path.join(app_support_dir, "torch")
+
+# Add src to python path for imports
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from simulation.models import Config
+from simulation.engine import CoreEngine, State
+from adapters_real.queue_llm import QueueLLMBridge
+
+# --- Global State ---
+mcp_command_queue = queue.Queue()
+mcp_result_queue = queue.Queue()
+active_session_id = None
+mutex_lock = threading.Lock()
+last_active_timestamp = time.time()
+IDLE_TIMEOUT_SECONDS = 900 # 15 minutes
+
+# Daemon Lifecycle State
+daemon_status = "DOWNLOADING" # Starts in downloading state to prevent Claude timeouts
+daemon_status_message = "Initializing models..."
+daemon_progress = 0
+
+# Engine reference
+engine = None
+mic = None
+speaker = None
+
+def pre_download_models():
+    """Forces huggingface_hub to fetch the massive models into our explicit directory before instantiation."""
+    global daemon_status_message, daemon_progress
+    try:
+        from huggingface_hub import snapshot_download, try_to_load_from_cache
+        from huggingface_hub.utils import LocalEntryNotFoundError
+
+        # 1. Kokoro TTS (82M)
+        try:
+            try_to_load_from_cache(repo_id="hexgrad/Kokoro-82M", filename="kokoro-v1_0.pth")
+            daemon_status_message = "Loading Kokoro TTS (82M)..."
+            daemon_progress = 10
+            # Ensure everything is correct
+            snapshot_download(repo_id="hexgrad/Kokoro-82M", allow_patterns=["*.pth", "*.json", "voices/*"], local_files_only=True)
+        except (LocalEntryNotFoundError, Exception):
+            daemon_status_message = "Downloading Kokoro TTS (82M)..."
+            daemon_progress = 5
+            snapshot_download(repo_id="hexgrad/Kokoro-82M", allow_patterns=["*.pth", "*.json", "voices/*"])
+
+        # 2. MLX Whisper Large v3 (3GB)
+        try:
+            try_to_load_from_cache(repo_id="mlx-community/whisper-large-v3-mlx", filename="weights.npz")
+            daemon_status_message = "Loading MLX Whisper Large v3 (3GB)..."
+            daemon_progress = 50
+            snapshot_download(repo_id="mlx-community/whisper-large-v3-mlx", local_files_only=True)
+        except (LocalEntryNotFoundError, Exception):
+            daemon_status_message = "Downloading MLX Whisper Large v3 (3GB)..."
+            daemon_progress = 30
+            snapshot_download(repo_id="mlx-community/whisper-large-v3-mlx")
+
+        daemon_status_message = "Finalizing AI setup..."
+        daemon_progress = 90
+    except Exception as e:
+        print(f"Model download error: {e}", file=sys.stderr)
+        daemon_status_message = f"Error downloading models: {e}"
+
+def run_audio_daemon():
+    """Runs the CoreEngine in a persistent background thread."""
+    global engine, mic, speaker, last_active_timestamp, daemon_status, daemon_status_message, daemon_progress
+    
+    # Pre-download models so the daemon status reflects exactly what is happening
+    pre_download_models()
+    daemon_status_message = "Instantiating hardware..."
+    daemon_progress = 95
+    
+    # Load configuration using Hydra
+    config_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', 'config'))
+    
+    with initialize(version_base=None, config_path="../../config"):
+        cfg = compose(config_name="config")
+        print("Loaded Hydra configuration successfully.")
+
+    mic = instantiate(cfg.microphone)
+    speaker = instantiate(cfg.speaker)
+    vad = instantiate(cfg.vad)
+    stt = instantiate(cfg.stt)
+    llm = QueueLLMBridge(mcp_command_queue, mcp_result_queue)
+    
+    config = Config(
+        vad_probability_threshold=cfg.vad.get("vad_probability_threshold", 0.80),
+        vad_bargein_threshold_ms=cfg.vad.get("vad_bargein_threshold_ms", 500),
+        endpointing_patience_normal_ms=cfg.vad.get("endpointing_patience_normal_ms", 1500),
+        endpointing_patience_interrupted_ms=cfg.vad.get("endpointing_patience_interrupted_ms", 700),
+        vad_silence_grace_ms=cfg.config.get("vad_silence_grace_ms", 100)
+    )
+    
+    engine = CoreEngine(config, mic, speaker, vad, stt, llm)
+    engine.state = State.EXECUTING  # Start dormant
+    
+    daemon_status = "READY"
+    daemon_status_message = "Audio Engine is online."
+    daemon_progress = 100
+    print("Audio Daemon Started. Waiting for commands.", file=sys.stderr)
+    
+    try:
+        while True:
+            # If dormant, check for commands from FastAPI
+            if engine.state == State.EXECUTING:
+                try:
+                    cmd = mcp_command_queue.get(timeout=0.1) # Blocks briefly
+                    
+                    # We got a command, wake up the hardware!
+                    mic.start_stream()
+                    engine.start_conversation(cmd.get("text", ""))
+                    engine.expect_reply = cmd.get("expect_reply", True)
+                    
+                except queue.Empty:
+                    pass
+            else:
+                engine.tick()
+                # Once we drop back to EXECUTING, we finished the conversation loop
+                if engine.state == State.EXECUTING:
+                    mic.stop_stream()
+                    last_active_timestamp = time.time()
+                    
+    except Exception as e:
+        print(f"Daemon exception: {e}", file=sys.stderr)
+    finally:
+        if mic:
+            mic.close()
+
+async def watchdog():
+    """Monitors idle time and self-destructs if inactive."""
+    global last_active_timestamp
+    while True:
+        await asyncio.sleep(60)
+        idle_time = time.time() - last_active_timestamp
+        if idle_time > IDLE_TIMEOUT_SECONDS:
+            print(f"Idle timeout reached ({idle_time:.0f}s). Self-destructing to free RAM.", file=sys.stderr)
+            if mic:
+                mic.close()
+            os._exit(0)
+
+def parent_pid_polling():
+    """Polls the parent PID. If the parent dies, the daemon instantly self-destructs."""
+    while True:
+        time.sleep(3.0)
+        if os.getppid() == 1:
+            print("Parent process died. Stopping daemon to prevent Zombie microphone lock.", file=sys.stderr)
+            os._exit(0)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Boot the daemon thread on startup
+    daemon_thread = threading.Thread(target=run_audio_daemon, daemon=True)
+    daemon_thread.start()
+    
+    # Start the watchdog
+    asyncio.create_task(watchdog())
+    
+    # Start the Parent PID Poller
+    polling_thread = threading.Thread(target=parent_pid_polling, daemon=True)
+    polling_thread.start()
+    
+    yield
+    # Shutdown logic
+    if mic:
+        mic.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/health")
+async def health_check():
+    # If the app is up, we are technically "healthy" enough for the MCP client to connect,
+    # even if we are downloading. The actual block happens in /converse.
+    return {
+        "status": "ok", 
+        "daemon_status": daemon_status,
+        "message": daemon_status_message,
+        "progress": daemon_progress
+    }
+
+@app.get("/status")
+async def status_sse(request: Request):
+    """Server-Sent Events endpoint to broadcast download/status progress to the UI."""
+    async def event_generator():
+        last_msg = ""
+        while True:
+            if await request.is_disconnected():
+                break
+            
+            # Only yield if the message changed to save bandwidth, unless we just connected
+            if daemon_status_message != last_msg:
+                last_msg = daemon_status_message
+                yield {
+                    "event": "status_update",
+                    "data": f'{{"status": "{daemon_status}", "message": "{daemon_status_message}"}}'
+                }
+            await asyncio.sleep(0.5)
+            
+    from sse_starlette.sse import EventSourceResponse
+    return EventSourceResponse(event_generator())
+
+@app.post("/reload")
+async def reload_config():
+    global engine, mic, speaker, vad, stt, daemon_status, daemon_status_message
+    
+    if daemon_status == "DOWNLOADING":
+        return {"status": "error", "message": "Cannot reload while downloading models."}
+        
+    daemon_status = "RELOADING"
+    daemon_status_message = "Hot-swapping audio models..."
+    
+    with mutex_lock:
+        # 1. Stop the current engine
+        if engine:
+            engine.state = State.EXECUTING
+        if mic: 
+            mic.close()
+            
+        # 1b. CRITICAL: Explicitly obliterate old models from VRAM to prevent Out-Of-Memory (OOM) crashes on hot-swaps
+        import gc
+        try:
+            del speaker
+            del vad
+            del stt
+            del engine
+        except NameError:
+            pass
+            
+        gc.collect()
+        
+        try:
+            import mlx.core as mx
+            mx.metal.clear_cache()
+        except ImportError:
+            pass
+            
+        try:
+            import torch
+            if torch.backends.mps.is_available():
+                torch.mps.empty_cache()
+        except ImportError:
+            pass
+        
+        try:
+            # 2. Re-read the YAML file using Hydra
+            with initialize(version_base=None, config_path="../../config"):
+                cfg = compose(config_name="config")
+                
+            # 3. Instantiate the new models on the fly
+            mic = instantiate(cfg.microphone)
+            speaker = instantiate(cfg.speaker)
+            vad = instantiate(cfg.vad)
+            stt = instantiate(cfg.stt)
+            llm = QueueLLMBridge(mcp_command_queue, mcp_result_queue)
+            
+            config = Config(
+                vad_probability_threshold=cfg.vad.get("vad_probability_threshold", 0.80),
+                vad_bargein_threshold_ms=cfg.vad.get("vad_bargein_threshold_ms", 500),
+                endpointing_patience_normal_ms=cfg.vad.get("endpointing_patience_normal_ms", 1500),
+                endpointing_patience_interrupted_ms=cfg.vad.get("endpointing_patience_interrupted_ms", 700),
+                vad_silence_grace_ms=cfg.config.get("vad_silence_grace_ms", 100)
+            )
+            
+            engine = CoreEngine(config, mic, speaker, vad, stt, llm)
+            engine.state = State.EXECUTING
+            
+            daemon_status = "READY"
+            daemon_status_message = "Audio Engine reloaded successfully."
+            return {"status": "ok", "message": "Audio engine hot-swapped successfully."}
+            
+        except Exception as e:
+            daemon_status = "ERROR"
+            daemon_status_message = f"Failed to reload: {str(e)}"
+            return {"status": "error", "message": daemon_status_message}
+
+@app.post("/converse")
+async def converse(request: Request):
+    global active_session_id, last_active_timestamp
+    
+    # Fast-Fail Graceful State to prevent Claude Timeout during the 3GB initial download
+    if daemon_status == "DOWNLOADING":
+        return {
+            "status": "system_busy", 
+            "message": f"SYSTEM NOTIFICATION: Speak MCP is currently initializing. {daemon_status_message} Please instruct the user to wait a moment and try again."
+        }
+        
+    body = await request.json()
+    session_id = body.get("session_id")
+    text_to_speak = body.get("text_to_speak", "")
+    expect_reply = body.get("expect_reply", True)
+    
+    with mutex_lock:
+        if active_session_id is not None and active_session_id != session_id:
+            return {
+                "status": "system_busy", 
+                "message": "Microphone is in use by another session. Fallback to text."
+            }
+        # Lock the logical session
+        active_session_id = session_id
+        last_active_timestamp = time.time()
+
+    try:
+        # Feed command to daemon
+        mcp_command_queue.put({"text": text_to_speak, "expect_reply": expect_reply})
+        
+        # Wait for human to interact or natural termination, checking for client disconnects
+        while True:
+            if await request.is_disconnected():
+                print(f"[{session_id}] Client disconnected! Aborting audio loop.", file=sys.stderr)
+                # Client hung up (e.g. reload or ctrl+c). We must reset the engine immediately.
+                if speaker:
+                    speaker.flush()
+                if engine:
+                    engine.state = State.EXECUTING # This will trigger mic.stop_stream() in the loop
+                raise HTTPException(status_code=499, detail="Client Disconnected")
+            
+            try:
+                # Use a short timeout so we can loop and check for is_disconnected()
+                result = await asyncio.to_thread(mcp_result_queue.get, timeout=0.1)
+                last_active_timestamp = time.time()
+                return result
+            except queue.Empty:
+                await asyncio.sleep(0.01)
+
+    finally:
+        # Always release the logical lock when the request ends
+        with mutex_lock:
+            active_session_id = None
+
+if __name__ == "__main__":
+    import uvicorn
+    import os
+    
+    # Isolate socket to user directory to prevent /tmp hijacking and permission issues
+    app_support_dir = os.path.expanduser("~/Library/Application Support/SpeakMCP")
+    os.makedirs(app_support_dir, exist_ok=True)
+    socket_path = os.path.join(app_support_dir, "daemon.sock")
+    
+    # Cleanup orphaned socket to prevent "Address already in use" deadlock
+    if os.path.exists(socket_path):
+        try:
+            os.unlink(socket_path)
+        except OSError:
+            pass
+
+    # Important: run with workers=1 to ensure singleton
+    uvicorn.run(app, uds=socket_path, workers=1)

package/src/index.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+// Get the directory of the current module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Root of the project
+const projectRoot = join(__dirname, "..");
+
+// Path to the Python script
+const pythonScriptPath = join(projectRoot, "src", "mcp_server.py");
+
+/**
+ * Locate the best Python executable to use.
+ * Priority:
+ * 1. Local venv inside the project
+ * 2. System python3
+ */
+function getPythonExecutable(): string {
+  const venvPath = join(projectRoot, "venv", "bin", "python3");
+  if (existsSync(venvPath)) {
+    return venvPath;
+  }
+  return "python3";
+}
+
+const pythonExecutable = getPythonExecutable();
+
+/**
+ * Start the Python MCP Server and bridge standard I/O.
+ */
+function startBridge() {
+  const pythonProcess = spawn(pythonExecutable, [pythonScriptPath], {
+    stdio: ["pipe", "pipe", "inherit"],
+    env: {
+      ...process.env,
+      // Ensure Python output isn't buffered
+      PYTHONUNBUFFERED: "1",
+    },
+  });
+
+  // Pipe our stdin into Python's stdin
+  process.stdin.pipe(pythonProcess.stdin!);
+
+  // Pipe Python's stdout back to our stdout
+  pythonProcess.stdout!.pipe(process.stdout);
+
+  // Handle process termination
+  pythonProcess.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+
+  // Forward signals
+  process.on("SIGINT", () => pythonProcess.kill("SIGINT"));
+  process.on("SIGTERM", () => pythonProcess.kill("SIGTERM"));
+}
+
+startBridge();

package/src/mcp_server.py

@@ -0,0 +1,254 @@
+import os
+import sys
+
+# 1. Save the actual OS-level stdout (FD 1) to a cloned file descriptor
+original_stdout_fd = os.dup(1)
+
+# 2. Force OS-level stdout (FD 1) to point to stderr (FD 2). 
+# Now, ALL C-level and Python-level logs safely pipe to stderr.
+os.dup2(2, 1)
+
+# 3. Redirect Python's sys.stdout just to be thorough
+sys.stdout = sys.stderr
+
+import uuid
+import subprocess
+import json
+import socket
+import http.client
+import time
+import logging
+import asyncio
+import random
+
+from mcp.server.fastmcp import FastMCP, Context
+
+logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+
+# Inject the busy-signal instructions into the server instructions
+instructions = """
+<voice_loop_instructions>
+If the voice_converse tool returns "status": "system_busy", it means the physical microphone is currently locked by another AI agent in a different window. 
+DO NOT retry the tool. Output a standard text message explaining the audio channel is busy, and continue the conversation via text.
+CRITICAL RULE: If you use the voice_converse tool and it returns "status": "silence_timeout", you MUST NOT abandon the voice loop by simply typing a text response. You MUST formally close the hardware loop by calling voice_converse ONE LAST TIME with "expect_reply": false and "text_to_speak": "I didn't hear anything, so I am turning off the microphone now."
+</voice_loop_instructions>
+"""
+
+# Initialize FastMCP Server
+mcp = FastMCP("voice-mcp-server-client", instructions=instructions)
+
+SESSION_ID = str(uuid.uuid4())
+
+# We use Unix Domain Sockets to bypass macOS firewall popups
+# Isolate socket to user directory to prevent /tmp hijacking
+app_support_dir = os.path.expanduser("~/Library/Application Support/SpeakMCP")
+os.makedirs(app_support_dir, exist_ok=True)
+SOCKET_PATH = os.path.join(app_support_dir, "daemon.sock")
+
+class UDSHTTPConnection(http.client.HTTPConnection):
+    """Subclass to force http.client over Unix Domain Sockets."""
+    def __init__(self, socket_path, timeout=300.0):
+        super().__init__("localhost", timeout=timeout)
+        self.socket_path = socket_path
+
+    def connect(self):
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.sock.settimeout(self.timeout)
+        self.sock.connect(self.socket_path)
+
+def make_uds_request(method: str, path: str, payload: dict = None, timeout: float = 1.0) -> tuple[int, dict]:
+    """Helper to cleanly make UDS requests and parse JSON."""
+    conn = UDSHTTPConnection(SOCKET_PATH, timeout=timeout)
+    try:
+        body = json.dumps(payload).encode('utf-8') if payload else None
+        headers = {'Content-Type': 'application/json'} if payload else {}
+        conn.request(method, path, body=body, headers=headers)
+        response = conn.getresponse()
+        data = response.read().decode('utf-8')
+        return response.status, json.loads(data) if data else {}
+    finally:
+        conn.close()
+
+def check_daemon_health():
+    try:
+        status, _ = make_uds_request("GET", "/health", timeout=1.0)
+        return status == 200
+    except (socket.error, ConnectionError, FileNotFoundError, ConnectionRefusedError):
+        return False
+
+def ensure_daemon_running():
+    """Checks if daemon is up, auto-boots it if not, and polls until ready."""
+    if check_daemon_health():
+        return
+
+    logging.info("Daemon is down, attempting to boot detached process...")
+    # Boot the daemon detached
+    project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+    python_exec = os.path.join(project_root, "venv", "bin", "python3")
+    daemon_script = os.path.join(project_root, "src", "daemon", "audio_server.py")
+    
+    subprocess.Popen(
+        [python_exec, daemon_script],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True # Detach entirely so it survives CLI restarts
+    )
+
+    # Poll until health check passes (give it time to load ML models)
+    max_retries = 120 # 60 seconds
+    for _ in range(max_retries):
+        if check_daemon_health():
+            return
+        time.sleep(0.5)
+            
+    raise RuntimeError("Failed to auto-boot Voice Audio Daemon. Health check timed out.")
+
+@mcp.tool()
+def configure_audio_engine(speaker_adapter: str = None, vad_adapter: str = None, stt_adapter: str = None) -> dict:
+    """
+    Dynamically hot-swap the Voice Audio Daemon's AI models and hardware without restarting.
+    Args:
+        speaker_adapter: Valid options: 'kokoro_speaker', 'elevenlabs_speaker', 'live_speaker'.
+        vad_adapter: Valid options: 'silero_vad' (Conversational), 'ptt_vad' (Walkie-Talkie).
+        stt_adapter: Valid options: 'mlx_whisper_large_v3', 'whisper_stt'.
+    """
+    try:
+        ensure_daemon_running()
+        import re
+        
+        project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+        config_path = os.path.join(project_root, "config", "config.yaml")
+        
+        with open(config_path, "r") as f:
+            content = f.read()
+            
+        if speaker_adapter:
+            content = re.sub(r"- speaker: .*", f"- speaker: {speaker_adapter}", content)
+        if vad_adapter:
+            content = re.sub(r"- vad: .*", f"- vad: {vad_adapter}", content)
+        if stt_adapter:
+            content = re.sub(r"- stt: .*", f"- stt: {stt_adapter}", content)
+            
+        with open(config_path, "w") as f:
+            f.write(content)
+            
+        # Trigger Daemon hot-reload
+        status, response_data = make_uds_request("POST", "/reload", timeout=15.0)
+        return response_data
+        
+    except (socket.error, ConnectionError, FileNotFoundError, ConnectionRefusedError):
+        return {
+            "status": "error", 
+            "message": "CRITICAL: The Voice Audio Daemon failed to respond to the reload request."
+        }
+    except Exception as e:
+         return {
+            "status": "error", 
+            "message": f"CRITICAL Error dynamically reloading audio daemon: {str(e)}"
+        }
+
+async def render_visualizer(ctx: Context):
+    """Renders a fake audio visualizer using MCP progress notifications."""
+    if not ctx: return
+    bars = [" ", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
+    try:
+        while True:
+            spectrum = "".join(random.choice(bars) for _ in range(12))
+            await ctx.report_progress(100, 100, message=f"🎙️  {spectrum}  🎙️")
+            await asyncio.sleep(0.1)
+    except asyncio.CancelledError:
+        pass
+
+@mcp.tool()
+async def voice_converse(text_to_speak: str, expect_reply: bool = True, ctx: Context = None) -> dict:
+    """
+    Speak a prompt to the user and listen for a response.
+    If expect_reply is False, the tool returns immediately after queuing the speech.
+    """
+    try:
+        ensure_daemon_running()
+
+        async def _do_converse():
+            return await asyncio.to_thread(
+                make_uds_request,
+                "POST", 
+                "/converse", 
+                {"session_id": SESSION_ID, "text_to_speak": text_to_speak, "expect_reply": expect_reply},
+                300.0
+            )
+        
+        # Start the visualizer!
+        vis_task = asyncio.create_task(render_visualizer(ctx)) if ctx else None
+        try:
+            status, response_data = await _do_converse()
+        finally:
+            if vis_task:
+                vis_task.cancel()
+        
+        # Handle the initialization (download) state automatically with native progress
+        if response_data and response_data.get("status") == "system_busy" and "initializing" in response_data.get("message", "").lower():
+            if ctx:
+                await ctx.info("Speak MCP: Initializing Local AI Models. This may take a few minutes...")
+            
+            while True:
+                try:
+                    # Async request for health to not block the event loop
+                    h_status, h_data = await asyncio.to_thread(make_uds_request, "GET", "/health", None, 5.0)
+                    if h_status == 200:
+                        d_status = h_data.get("daemon_status")
+                        d_msg = h_data.get("message", "")
+                        d_progress = h_data.get("progress", 0)
+                        
+                        # Report progress back to Gemini CLI for native rendering
+                        if ctx:
+                            await ctx.report_progress(d_progress, 100, message=d_msg)
+                        
+                        if d_status == "READY":
+                            if ctx:
+                                await ctx.info("Speak MCP: Setup Complete!")
+                                
+                            # After setup, the models are ready! Now perform the ACTUAL converse call with visualizer.
+                            vis_task2 = asyncio.create_task(render_visualizer(ctx)) if ctx else None
+                            try:
+                                status, final_response = await _do_converse()
+                                return final_response
+                            finally:
+                                if vis_task2:
+                                    vis_task2.cancel()
+                            
+                        elif d_status == "ERROR":
+                            return {"status": "error", "message": d_msg}
+                except Exception:
+                    pass
+                await asyncio.sleep(1.0)
+                
+        return response_data
+            
+    except (socket.error, ConnectionError, FileNotFoundError, ConnectionRefusedError):
+
+        return {
+            "status": "error", 
+            "user_transcript": "", 
+            "message": "CRITICAL: The Voice Audio Daemon failed to respond."
+        }
+    except TimeoutError:
+         return {
+            "status": "error", 
+            "user_transcript": "", 
+            "message": "CRITICAL: The Voice Audio Daemon timed out waiting for speech."
+        }
+    except Exception as e:
+         return {
+            "status": "error", 
+            "user_transcript": "", 
+            "message": f"CRITICAL Error starting audio daemon: {str(e)}"
+        }
+
+if __name__ == "__main__":
+    # 4. Restore the OS-level stdout just before handing control to the MCP SDK
+    os.dup2(original_stdout_fd, 1)
+    os.close(original_stdout_fd)
+    sys.stdout = sys.__stdout__
+    
+    # 5. Now the JSON-RPC protocol has an absolutely pristine stdout pipe
+    mcp.run()