MCP Handlers

MCP (Model Context Protocol) handlers for AI agent integration.

Handlers

Utility handlers for the scitex-audio MCP server.

async scitex_audio._mcp.handlers.announce_context_handler(include_full_path: bool = False, branch_resolver=None, speak_fn=None) → dict[source]

Announce current working directory and git branch.

Parameters:

  • branch_resolver – Injectable callable returning the git branch name (or None) for cwd (testing). Defaults to a real git rev-parse subprocess.

  • speak_fn – Injectable speak handler (testing). Defaults to speak_handler().

async scitex_audio._mcp.handlers.check_audio_status_handler(status_fn=None) → dict[source]

Check WSL audio connectivity and available playback methods.

Parameters:

status_fn – Injectable status probe (testing). Defaults to scitex_audio.check_wsl_audio.

async scitex_audio._mcp.handlers.clear_audio_cache_handler(max_age_hours: float = 24, audio_dir=None) → dict[source]

Clear audio cache.

Parameters:

audio_dir – Injectable directory to clear (testing). Defaults to _get_audio_dir().

async scitex_audio._mcp.handlers.generate_audio_handler(text: str, backend: str | None = None, voice: str | None = None, output_path: str | None = None, return_base64: bool = False, speak_fn=None, audio_dir=None) → dict[source]

Generate audio file without playing.

Parameters:

  • speak_fn – Injectable TTS function (testing). Defaults to scitex_audio.speak.

  • audio_dir – Injectable output directory (testing). Defaults to _get_audio_dir().

async scitex_audio._mcp.handlers.list_audio_files_handler(limit: int = 20, audio_dir=None) → dict[source]

List generated audio files.

Parameters:

audio_dir – Injectable directory to scan (testing). Defaults to _get_audio_dir().

async scitex_audio._mcp.handlers.list_backends_handler(available_fn=None, fallback_order=None) → dict[source]

List available TTS backends.

Parameters:

  • available_fn – Injectable available-backends function (testing). Defaults to scitex_audio.available_backends.

  • fallback_order – Injectable fallback order (testing). Defaults to scitex_audio.FALLBACK_ORDER.

async scitex_audio._mcp.handlers.list_voices_handler(backend: str = 'gtts', get_tts_fn=None) → dict[source]

List available voices for a backend.

Parameters:

get_tts_fn – Injectable engine factory (testing). Defaults to scitex_audio.get_tts.

async scitex_audio._mcp.handlers.play_audio_handler(path: str, player=None) → dict[source]

Play an audio file.

Parameters:

player – Injectable playback callable taking a Path (testing). Defaults to BaseTTS._play_audio.

async scitex_audio._mcp.handlers.speak_handler(text: str, backend: str | None = None, voice: str | None = None, rate: int = 150, speed: float = 1.5, play: bool = True, save: bool = False, output_path: str | None = None, fallback: bool = True, agent_id: str | None = None, wait: bool = True, signature: bool = False, num_threads: int | None = None, speak_fn=None, audio_dir=None, signature_fn=None) → dict[source]

Convert text to speech with fallback.

Parameters:

  • save – If True and output_path is None, auto-generate a timestamped path.

  • output_path – Explicit path to save the audio file (overrides save flag).

  • signature – If True, prepend hostname/project/branch to text.

  • num_threads – CPU thread count for LuxTTS backend (None=default).

  • speak_fn – Injectable TTS function (testing). Defaults to scitex_audio.speak.

  • audio_dir – Injectable output directory (testing). Defaults to _get_audio_dir().

  • signature_fn – Injectable signature builder (testing). Defaults to _get_signature().

async scitex_audio._mcp.handlers.speech_queue_status_handler() → dict[source]

Get current speech queue status.

Speak Handlers

Speak handlers for scitex.audio MCP server.

Provides speak_local_handler and speak_relay_handler for explicit control over audio playback location (server vs relay).

async scitex_audio._mcp.speak_handlers.speak_local_handler(text: str, backend: str | None = None, voice: str | None = None, rate: int = 150, speed: float = 1.5, play: bool = True, save: bool = False, fallback: bool = True, agent_id: str | None = None, signature: bool = False, speak_fn=None, sink_check=None) → dict[source]

Play audio on the LOCAL/SERVER machine.

Use when running Claude Code directly on your local machine. Audio plays on the machine where the MCP server is running.

Returns success=False if: - SCITEX_AUDIO_MODE=remote (should use relay instead) - Audio sink is SUSPENDED (no output device) - Playback was requested but failed

Parameters:

  • speak_fn – Injectable TTS function (testing). Defaults to scitex_audio.speak.

  • sink_check – Injectable audio-sink probe (testing). Defaults to check_audio_sink_state.

async scitex_audio._mcp.speak_handlers.speak_relay_handler(text: str, backend: str | None = None, voice: str | None = None, rate: int = 150, speed: float = 1.5, play: bool = True, save: bool = False, fallback: bool = True, agent_id: str | None = None, url_resolver=None, ssh_ip_resolver=None) → dict[source]

Forward speech to RELAY server for remote playback.

Use when running on a remote server and want audio on your local machine. Returns detailed error with setup instructions if relay unavailable.

Parameters:

  • url_resolver – Injectable relay-URL resolver (testing). Defaults to get_relay_url.

  • ssh_ip_resolver – Injectable SSH-client-IP resolver (testing). Defaults to get_ssh_client_ip.