# Piper TTS MCP Server
[![Russian](https://img.shields.io/badge/lang-Russian-blue)](README.ru.md)

A Model Context Protocol (MCP) server that provides Text-to-Speech (TTS) capabilities using the [Piper](https://github.com/rhasspy/piper) engine. This server allows AI models to "speak" by generating high-quality voice messages from text.

## Features

- **High-Quality TTS**: Uses Piper for fast, local speech synthesis.
- **MCP Integration**: Compatible with any MCP client supporting HTTP transport.
- **Audio Streaming**: Returns a URL to the generated audio in Ogg Opus format (optimized for web/mobile).
- **Automatic Model Management**: Automatically downloads requested models if they are not present locally.
- **LRU Caching**: Stores the last 3 generated audio files in memory for retrieval.

## Installation & Setup

### Prerequisites

- [Docker](https://www.docker.com/) and Docker Compose
- Or [Python 3.12](https://www.python.org/) with `uv`

### Using Docker (Recommended)

1. **Build the image**:
   ```bash
   docker compose build
   ```

2. **Start the server**:
   ```bash
   docker compose up piper-mcp
   ```
   The server will be running at `http://localhost:8000`.

### Local Development

1. **Install dependencies**:
   ```bash
   uv sync
   ```

2. **Run the server**:
   ```bash
   # Use HTTP transport by default
   export MCP_TRANSPORT=http
   uv run server.py
   ```

## MCP Server Connection

To connect, use the following configuration (HTTP transport):

```json
{
  "mcpServers": {
    "piper-tts": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

## Testing

To run the automated tests using Docker (uses the `test` profile):
```bash
docker compose --profile test up tests
```

Or locally:
```bash
pytest tests/
```

## MCP Tool

After connecting, the following tool will be available:

- **`speak`**: Generates a voice message from text.
  - **Arguments**: `text` (string) — the text to speak.
  - **Result**: A JSON object containing `status`, `audio_url`, and metadata (size, format).

## Model Selection

The voice model is selected using the `MODEL` environment variable. 

- **Default Model**: `ru_RU-denis-medium`.
- **Logic**:
  1. At startup, the server checks for `.onnx` and `.onnx.json` files in the working directory.
  2. If not found, it automatically downloads them from the official Piper repository.
  3. Change the `MODEL` value in `docker-compose.yml` to switch voices.

## Project Repositories

- **Piper Engine**: [https://github.com/OHF-Voice/piper1-gpl](https://github.com/OHF-Voice/piper1-gpl)
- **Piper Voices (Model List)**: [https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md](https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md) — check this repository to see all available voices and their names.