scitex 2.13.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/audio/mcp_server.py

@@ -1,348 +1,237 @@
 #!/usr/bin/env python3
-# Timestamp: "2025-12-27 (ywatanabe)"
+# Timestamp: 2026-01-15
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/audio/mcp_server.py
 # ----------------------------------------
 
 """
-MCP Server for SciTeX Audio - Text-to-Speech with Multiple Backends
+FastMCP Server for SciTeX Audio - HTTP/SSE Transport Support
 
-Uses cross-process FIFO locking to ensure only one instance
-plays audio at a time across all Claude Code sessions.
+Enables remote agents to connect and play audio on local speakers.
+
+Usage:
+    scitex audio serve                           # stdio (default)
+    scitex audio serve -t http --port 31293      # HTTP transport
+    scitex audio serve -t sse --port 31293       # SSE transport
+
+For remote audio:
+    1. Run locally:  scitex audio serve -t http --port 31293
+    2. SSH tunnel:   ssh -R 31293:localhost:31293 remote-host
+    3. Remote agent connects to http://localhost:31293
 """
 
 from __future__ import annotations
 
-import asyncio
-import base64
-import os
-import uuid
-from dataclasses import dataclass, field
+import json
 from datetime import datetime
 from pathlib import Path
+from typing import Optional
 
-# Graceful MCP dependency handling
+# Graceful FastMCP dependency handling
 try:
-    import mcp.types as types
-    from mcp.server import NotificationOptions, Server
-    from mcp.server.models import InitializationOptions
-    from mcp.server.stdio import stdio_server
+    from fastmcp import FastMCP
 
-    MCP_AVAILABLE = True
+    FASTMCP_AVAILABLE = True
 except ImportError:
-    MCP_AVAILABLE = False
-    types = None  # type: ignore
-    Server = None  # type: ignore
-    NotificationOptions = None  # type: ignore
-    InitializationOptions = None  # type: ignore
-    stdio_server = None  # type: ignore
-
-__all__ = ["AudioServer", "main", "MCP_AVAILABLE"]
-
+    FASTMCP_AVAILABLE = False
+    FastMCP = None  # type: ignore
 
-@dataclass
-class SpeechRequest:
-    """A queued speech request."""
+__all__ = ["mcp", "run_server", "run_relay_server", "main", "FASTMCP_AVAILABLE"]
 
-    request_id: str
-    text: str
-    backend: str | None = None
-    voice: str | None = None
-    rate: int | None = None
-    speed: float | None = None
-    play: bool = True
-    save: bool = False
-    fallback: bool = True
-    future: asyncio.Future = field(default_factory=lambda: None)
-    created_at: datetime = field(default_factory=datetime.now)
-    agent_id: str | None = None
+# Import branding
+from ._branding import (
+    get_mcp_instructions,
+    get_mcp_server_name,
+)
 
+# Initialize MCP server
+if FASTMCP_AVAILABLE:
+    mcp = FastMCP(
+        name=get_mcp_server_name(),
+        instructions=get_mcp_instructions(),
+    )
+else:
+    mcp = None
 
-# Directory configuration
-SCITEX_BASE_DIR = Path(os.getenv("SCITEX_DIR", Path.home() / ".scitex"))
-SCITEX_AUDIO_DIR = SCITEX_BASE_DIR / "audio"
 
-
-def get_audio_dir() -> Path:
+def _get_audio_dir() -> Path:
     """Get the audio output directory."""
-    SCITEX_AUDIO_DIR.mkdir(parents=True, exist_ok=True)
-    return SCITEX_AUDIO_DIR
-
-
-class AudioServer:
-    """MCP Server for Text-to-Speech with cross-process FIFO queuing."""
-
-    def __init__(self):
-        self.server = Server("scitex-audio")
-        self._speech_queue: asyncio.Queue[SpeechRequest] = asyncio.Queue()
-        self._queue_processor_task: asyncio.Task | None = None
-        self._current_request: SpeechRequest | None = None
-        self._processed_count: int = 0
-        self._is_processing: bool = False
-        self.setup_handlers()
-
-    async def start_queue_processor(self):
-        """Start the background queue processor if not already running."""
-        if self._queue_processor_task is None or self._queue_processor_task.done():
-            self._queue_processor_task = asyncio.create_task(
-                self._process_speech_queue()
-            )
-
-    async def _process_speech_queue(self):
-        """Process speech requests sequentially from the queue."""
-        while True:
-            try:
-                request = await self._speech_queue.get()
-                self._current_request = request
-                self._is_processing = True
+    import os
 
-                try:
-                    result = await self._execute_speak(request)
-                    if request.future and not request.future.done():
-                        request.future.set_result(result)
-                except Exception as e:
-                    if request.future and not request.future.done():
-                        request.future.set_exception(e)
-                finally:
-                    self._processed_count += 1
-                    self._current_request = None
-                    self._is_processing = False
-                    self._speech_queue.task_done()
-
-            except asyncio.CancelledError:
-                break
-            except Exception:
-                continue
+    base_dir = Path(os.getenv("SCITEX_DIR", Path.home() / ".scitex"))
+    audio_dir = base_dir / "audio"
+    audio_dir.mkdir(parents=True, exist_ok=True)
+    return audio_dir
 
-    async def _execute_speak(self, request: SpeechRequest) -> dict:
-        """Execute a single speech request with cross-process locking."""
-        from . import available_backends
-        from . import speak as tts_speak
-        from ._cross_process_lock import AudioPlaybackLock
 
-        loop = asyncio.get_event_loop()
+if FASTMCP_AVAILABLE:
+    import asyncio
 
-        output_path = None
-        if request.save:
-            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-            output_path = str(get_audio_dir() / f"tts_{timestamp}.mp3")
+    def _run_async(coro):
+        """Run async handler synchronously for FastMCP tools."""
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        return loop.run_until_complete(coro)
 
-        def do_speak_with_lock():
-            # Acquire cross-process lock to ensure FIFO across all instances
-            lock = AudioPlaybackLock()
-            lock.acquire(timeout=120.0)
-            try:
-                return tts_speak(
-                    text=request.text,
-                    backend=request.backend,
-                    voice=request.voice,
-                    play=request.play,
-                    output_path=output_path,
-                    fallback=request.fallback,
-                    rate=request.rate,
-                    speed=request.speed,
-                )
-            finally:
-                lock.release()
-
-        await loop.run_in_executor(None, do_speak_with_lock)
-
-        backends = available_backends()
-        used_backend = request.backend or (backends[0] if backends else None)
-
-        response = {
-            "success": True,
-            "request_id": request.request_id,
-            "text": request.text,
-            "backend": used_backend,
-            "available_backends": backends,
-            "voice": request.voice,
-            "played": request.play,
-            "fallback_enabled": request.fallback,
-            "timestamp": datetime.now().isoformat(),
-            "agent_id": request.agent_id,
-        }
-
-        if output_path:
-            response["saved_to"] = output_path
-
-        return response
-
-    def setup_handlers(self):
-        """Set up MCP server handlers."""
-        from ._mcp_handlers import (
-            check_audio_status_handler,
-            clear_audio_cache_handler,
-            generate_audio_handler,
-            list_audio_files_handler,
-            list_backends_handler,
-            list_voices_handler,
-            play_audio_handler,
+    @mcp.tool()
+    def speak(
+        text: str,
+        backend: Optional[str] = None,
+        voice: Optional[str] = None,
+        rate: int = 150,
+        speed: float = 1.5,
+        play: bool = True,
+        save: bool = False,
+        fallback: bool = True,
+        agent_id: Optional[str] = None,
+    ) -> str:
+        """[audio] Convert text to speech with fallback (pyttsx3 -> gtts -> elevenlabs).
+
+        NOTE: Plays on SERVER. For remote use, see speak_relay.
+        """
+        return audio_speak_local(
+            text=text, backend=backend, voice=voice, rate=rate,
+            speed=speed, play=play, save=save, fallback=fallback,
+            agent_id=agent_id,
         )
-        from ._mcp_tool_schemas import get_tool_schemas
-
-        @self.server.list_tools()
-        async def handle_list_tools():
-            return get_tool_schemas()
-
-        @self.server.call_tool()
-        async def handle_call_tool(name: str, arguments: dict):
-            if name == "speak":
-                await self.start_queue_processor()
-                return await self.speak(**arguments)
-            elif name == "generate_audio":
-                return await generate_audio_handler(**arguments)
-            elif name == "list_backends":
-                return await list_backends_handler()
-            elif name == "list_voices":
-                return await list_voices_handler(**arguments)
-            elif name == "play_audio":
-                return await play_audio_handler(**arguments)
-            elif name == "list_audio_files":
-                return await list_audio_files_handler(**arguments)
-            elif name == "clear_audio_cache":
-                return await clear_audio_cache_handler(**arguments)
-            elif name == "speech_queue_status":
-                return await self.speech_queue_status()
-            elif name == "check_audio_status":
-                return await check_audio_status_handler()
-            elif name == "announce_context":
-                return await self.announce_context(**arguments)
-            else:
-                raise ValueError(f"Unknown tool: {name}")
-
-        @self.server.list_resources()
-        async def handle_list_resources():
-            audio_dir = get_audio_dir()
-            if not audio_dir.exists():
-                return []
-
-            resources = []
-            audio_files = sorted(
-                list(audio_dir.glob("*.mp3")) + list(audio_dir.glob("*.wav")),
-                key=lambda p: p.stat().st_mtime,
-                reverse=True,
-            )[:20]
-
-            for audio_file in audio_files:
-                mtime = datetime.fromtimestamp(audio_file.stat().st_mtime)
-                mime_type = "audio/mpeg" if audio_file.suffix == ".mp3" else "audio/wav"
-                resources.append(
-                    types.Resource(
-                        uri=f"audio://{audio_file.name}",
-                        name=audio_file.name,
-                        description=f"Audio from {mtime.strftime('%Y-%m-%d %H:%M:%S')}",
-                        mimeType=mime_type,
-                    )
-                )
-            return resources
-
-        @self.server.read_resource()
-        async def handle_read_resource(uri: str):
-            if uri.startswith("audio://"):
-                filename = uri.replace("audio://", "")
-                filepath = get_audio_dir() / filename
-
-                if filepath.exists():
-                    with open(filepath, "rb") as f:
-                        content = base64.b64encode(f.read()).decode()
-
-                    mime_type = (
-                        "audio/mpeg" if filepath.suffix == ".mp3" else "audio/wav"
-                    )
-                    return types.ResourceContent(
-                        uri=uri, mimeType=mime_type, content=content
-                    )
-                else:
-                    raise ValueError(f"Audio file not found: {filename}")
-
-    async def speak(
-        self,
+
+    @mcp.tool()
+    def audio_speak_local(
         text: str,
-        backend: str | None = None,
-        voice: str | None = None,
-        rate: int | None = None,
-        speed: float | None = None,
+        backend: Optional[str] = None,
+        voice: Optional[str] = None,
+        rate: int = 150,
+        speed: float = 1.5,
         play: bool = True,
         save: bool = False,
         fallback: bool = True,
-        agent_id: str | None = None,
-        wait: bool = True,
-    ):
-        """Queue speech request with cross-process FIFO ordering."""
+        agent_id: Optional[str] = None,
+    ) -> str:
+        """[audio] Convert text to speech on the LOCAL/SERVER machine.
+
+        Use when running Claude Code directly on your local machine.
+        Audio plays where MCP server runs.
+
+        Args:
+            text: Text to convert to speech
+            backend: TTS backend (pyttsx3, gtts, elevenlabs)
+            voice: Voice/language
+            rate: Speech rate (pyttsx3 only)
+            speed: Speed multiplier (gtts)
+            play: Play audio (default True)
+            save: Save to file (default False)
+            fallback: Try next backend on failure
+            agent_id: Agent identifier
+        """
+        from ._mcp.speak_handlers import speak_local_handler
+
+        result = _run_async(speak_local_handler(
+            text=text, backend=backend, voice=voice, rate=rate,
+            speed=speed, play=play, save=save, fallback=fallback,
+            agent_id=agent_id,
+        ))
+        return json.dumps(result, indent=2)
+
+    @mcp.tool()
+    def audio_speak_relay(
+        text: str,
+        backend: Optional[str] = None,
+        voice: Optional[str] = None,
+        rate: int = 150,
+        speed: float = 1.5,
+        play: bool = True,
+        save: bool = False,
+        fallback: bool = True,
+        agent_id: Optional[str] = None,
+    ) -> str:
+        """[audio] Convert text to speech via RELAY server (remote playback).
+
+        Use when running on remote server (e.g., NAS) and want audio
+        on your local machine. REQUIRES relay server running locally.
+
+        Args:
+            text: Text to convert to speech
+            backend: TTS backend (pyttsx3, gtts, elevenlabs)
+            voice: Voice/language
+            rate: Speech rate (pyttsx3 only)
+            speed: Speed multiplier (gtts)
+            play: Play audio (default True)
+            save: Save to file (default False)
+            fallback: Try next backend on failure
+            agent_id: Agent identifier
+
+        Returns:
+            Success with playback info, or error with setup instructions
+        """
+        from ._mcp.speak_handlers import speak_relay_handler
+
+        result = _run_async(speak_relay_handler(
+            text=text, backend=backend, voice=voice, rate=rate,
+            speed=speed, play=play, save=save, fallback=fallback,
+            agent_id=agent_id,
+        ))
+        return json.dumps(result, indent=2)
+
+    @mcp.tool()
+    def list_backends() -> str:
+        """List available TTS backends and their status.
+
+        Returns
+        -------
+            JSON string with available backends and fallback order
+        """
         try:
-            request_id = str(uuid.uuid4())[:8]
-            loop = asyncio.get_event_loop()
-            future = loop.create_future()
-
-            request = SpeechRequest(
-                request_id=request_id,
-                text=text,
-                backend=backend,
-                voice=voice,
-                rate=rate,
-                speed=speed,
-                play=play,
-                save=save,
-                fallback=fallback,
-                future=future,
-                agent_id=agent_id,
-            )
+            from . import FALLBACK_ORDER, available_backends
 
-            await self._speech_queue.put(request)
-            queue_position = self._speech_queue.qsize()
-
-            if wait:
-                result = await future
-                result["queue_position"] = 0
-                return result
-            else:
-                return {
+            backends = available_backends()
+            return json.dumps(
+                {
                     "success": True,
-                    "queued": True,
-                    "request_id": request_id,
-                    "queue_position": queue_position,
-                    "text": text,
-                    "agent_id": agent_id,
-                    "message": f"Request queued at position {queue_position}",
+                    "available": backends,
+                    "fallback_order": FALLBACK_ORDER,
                     "timestamp": datetime.now().isoformat(),
-                }
-
+                },
+                indent=2,
+            )
         except Exception as e:
-            return {"success": False, "error": str(e)}
+            return json.dumps({"success": False, "error": str(e)}, indent=2)
 
-    async def speech_queue_status(self):
-        """Get the current speech queue status."""
+    @mcp.tool()
+    def check_audio_status() -> str:
+        """Check WSL audio connectivity and available playback methods.
+
+        Returns
+        -------
+            JSON string with audio status information
+        """
         try:
-            current = None
-            if self._current_request:
-                current = {
-                    "request_id": self._current_request.request_id,
-                    "text": self._current_request.text[:50] + "..."
-                    if len(self._current_request.text) > 50
-                    else self._current_request.text,
-                    "agent_id": self._current_request.agent_id,
-                    "created_at": self._current_request.created_at.isoformat(),
-                }
-
-            return {
-                "success": True,
-                "queue_size": self._speech_queue.qsize(),
-                "is_processing": self._is_processing,
-                "current_request": current,
-                "total_processed": self._processed_count,
-                "processor_running": self._queue_processor_task is not None
-                and not self._queue_processor_task.done(),
-                "timestamp": datetime.now().isoformat(),
-            }
+            from . import check_wsl_audio
+
+            status = check_wsl_audio()
+            status["success"] = True
+            status["timestamp"] = datetime.now().isoformat()
+            return json.dumps(status, indent=2)
         except Exception as e:
-            return {"success": False, "error": str(e)}
+            return json.dumps({"success": False, "error": str(e)}, indent=2)
+
+    @mcp.tool()
+    def announce_context(include_full_path: bool = False) -> str:
+        """Announce the current working directory and git branch.
 
-    async def announce_context(self, include_full_path: bool = False):
-        """Announce the current working directory and git branch."""
+        Useful for orientation when starting work in a new session.
+
+        Args:
+            include_full_path: Include full path or just directory name
+
+        Returns
+        -------
+            JSON string with context information and speak result
+        """
         import subprocess
 
         try:
-            # Get current working directory
             cwd = Path.cwd()
             dir_name = str(cwd) if include_full_path else cwd.name
 
@@ -367,58 +256,187 @@ class AudioServer:
             else:
                 text = f"Working in {dir_name}"
 
-            # Speak the announcement
-            await self.start_queue_processor()
-            result = await self.speak(text=text)
+            # Speak the announcement using the speak tool
+            speak_result = speak(text=text)
 
-            return {
-                "success": True,
-                "directory": str(cwd),
-                "directory_name": cwd.name,
-                "git_branch": git_branch,
-                "announced_text": text,
-                "speak_result": result,
-            }
+            return json.dumps(
+                {
+                    "success": True,
+                    "directory": str(cwd),
+                    "directory_name": cwd.name,
+                    "git_branch": git_branch,
+                    "announced_text": text,
+                    "speak_result": json.loads(speak_result),
+                },
+                indent=2,
+            )
 
         except Exception as e:
-            return {"success": False, "error": str(e)}
-
-
-async def _run_server():
-    """Run the MCP server (internal)."""
-    server = AudioServer()
-    async with stdio_server() as (read_stream, write_stream):
-        await server.server.run(
-            read_stream,
-            write_stream,
-            InitializationOptions(
-                server_name="scitex-audio",
-                server_version="0.3.0",  # Bumped for cross-process FIFO
-                capabilities=server.server.get_capabilities(
-                    notification_options=NotificationOptions(),
-                    experimental_capabilities={},
-                ),
-            ),
-        )
+            return json.dumps({"success": False, "error": str(e)}, indent=2)
 
 
-def main():
-    """Main entry point for the MCP server."""
-    if not MCP_AVAILABLE:
+def run_server(
+    transport: str = "stdio",
+    host: Optional[str] = None,
+    port: Optional[int] = None,
+) -> None:
+    """Run the MCP server.
+
+    Args:
+        transport: Transport protocol ("stdio", "sse", or "http")
+        host: Host for HTTP/SSE transport (default from branding)
+        port: Port for HTTP/SSE transport (default from branding)
+    """
+    from ._branding import DEFAULT_HOST, DEFAULT_PORT
+
+    host = host or DEFAULT_HOST
+    port = port or DEFAULT_PORT
+
+    if not FASTMCP_AVAILABLE:
         import sys
 
+        from ._branding import BRAND_NAME
+
         print("=" * 60)
-        print("MCP Server 'scitex-audio' requires the 'mcp' package.")
+        print(f"MCP Server '{BRAND_NAME}' requires the 'fastmcp' package.")
         print()
         print("Install with:")
-        print("  pip install mcp")
+        print("  pip install fastmcp")
         print()
         print("Or install scitex with MCP support:")
         print("  pip install scitex[mcp]")
         print("=" * 60)
         sys.exit(1)
 
-    asyncio.run(_run_server())
+    from ._branding import BRAND_NAME
+
+    if transport == "stdio":
+        mcp.run(transport="stdio")
+    elif transport == "sse":
+        print(f"Starting {BRAND_NAME} MCP server (SSE) on {host}:{port}")
+        mcp.run(transport="sse", host=host, port=port)
+    elif transport == "http":
+        print(f"Starting {BRAND_NAME} MCP server (HTTP) on {host}:{port}")
+        print(f"Connect via: http://{host}:{port}/mcp")
+        mcp.run(transport="streamable-http", host=host, port=port)
+    else:
+        raise ValueError(f"Unknown transport: {transport}")
+
+
+def run_relay_server(host: Optional[str] = None, port: Optional[int] = None) -> None:
+    """Run HTTP relay server for remote audio playback.
+
+    This exposes simple REST endpoints that remote agents can connect to.
+    Unlike the MCP server, this uses standard HTTP POST/GET.
+
+    Endpoints:
+        POST /speak - Speak text
+        GET /health - Health check
+        GET /list_backends - List available backends
+    """
+    from ._branding import BRAND_NAME, DEFAULT_HOST, DEFAULT_PORT
+
+    host = host or DEFAULT_HOST
+    port = port or DEFAULT_PORT
+
+    try:
+        from http.server import BaseHTTPRequestHandler, HTTPServer
+    except ImportError as e:
+        raise RuntimeError(f"HTTP server not available: {e}") from e
+
+    class RelayHandler(BaseHTTPRequestHandler):
+        """HTTP handler for audio relay requests."""
+
+        def _send_json(self, data: dict, status: int = 200) -> None:
+            """Send JSON response."""
+            import json
+
+            body = json.dumps(data, indent=2).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_OPTIONS(self) -> None:
+            """Handle CORS preflight."""
+            self.send_response(200)
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type")
+            self.end_headers()
+
+        def do_GET(self) -> None:
+            """Handle GET requests."""
+            import json
+
+            if self.path == "/health":
+                self._send_json({"status": "healthy", "server": BRAND_NAME})
+            elif self.path == "/list_backends":
+                result = list_backends()
+                self._send_json(json.loads(result))
+            else:
+                self._send_json({"error": "Not found"}, 404)
+
+        def do_POST(self) -> None:
+            """Handle POST requests."""
+            import json
+
+            if self.path == "/speak":
+                content_length = int(self.headers.get("Content-Length", 0))
+                body = self.rfile.read(content_length)
+                try:
+                    data = json.loads(body.decode("utf-8"))
+                    # Import speak directly from audio module (not MCP tool)
+                    from . import speak as tts_speak
+                    from ._cross_process_lock import AudioPlaybackLock
+
+                    # Acquire lock for FIFO
+                    lock = AudioPlaybackLock()
+                    lock.acquire(timeout=120.0)
+                    try:
+                        tts_speak(
+                            text=data.get("text", ""),
+                            backend=data.get("backend"),
+                            voice=data.get("voice"),
+                            rate=data.get("rate", 150),
+                            speed=data.get("speed", 1.5),
+                            play=data.get("play", True),
+                            fallback=data.get("fallback", True),
+                            mode="local",
+                        )
+                    finally:
+                        lock.release()
+
+                    self._send_json({
+                        "success": True,
+                        "text": data.get("text", ""),
+                        "played": True,
+                        "timestamp": datetime.now().isoformat(),
+                    })
+                except Exception as e:
+                    self._send_json({"success": False, "error": str(e)}, 500)
+            else:
+                self._send_json({"error": "Not found"}, 404)
+
+        def log_message(self, format: str, *args) -> None:
+            """Suppress default logging."""
+            pass
+
+    print(f"Starting {BRAND_NAME} relay server on {host}:{port}")
+    print("Endpoints: POST /speak, GET /health, GET /list_backends")
+    server = HTTPServer((host, port), RelayHandler)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nShutting down relay server")
+        server.shutdown()
+
+
+def main():
+    """Entry point for scitex-audio-mcp command."""
+    run_server(transport="stdio")
 
 
 if __name__ == "__main__":