# cast-mcp

Standalone HTTP MCP server for playing audiobooks and local TTS on home speakers.

The service exposes both MCP tools for agents and plain HTTP endpoints for physical devices. Audiobooks are read from `./media` by default and streamed to speakers through signed session URLs backed by `ffmpeg`.

Supported speaker providers:

- Google Cast
- Sonos

Speaker IDs are provider-prefixed, for example `cast:boys-room-speaker` or `sonos:kitchen`. Existing unprefixed Cast IDs still work as a compatibility fallback.

It also includes fully local TTS for short spoken messages. Docker defaults to Piper with the `en_GB-jenny_dioco-medium` voice and falls back to `espeak-ng` if Piper fails.

## Local Setup

```bash
bun install
cp .env.example .env
mkdir -p media data
bun run start
```

## Docker

```bash
cp .env.example .env
mkdir -p media data
docker compose up -d --build
```

Docker mounts `./media` as `/media:ro` and `./data` as `/data`.

## Library Layout

See [`MEDIA.md`](./MEDIA.md) for detailed instructions on where to put audiobook files and what formats are supported.

Each folder under `./media` is treated as one book:

```text
media/
  the-hobbit/
    metadata.json
    001.mp3
    002.mp3
```

Optional `metadata.json`:

```json
{
  "id": "the-hobbit",
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien"
}
```

Supported input extensions are currently `.mp3`, `.m4a`, `.m4b`, `.aac`, `.wav`, `.flac`, and `.ogg`. Streams are transcoded to MP3.

## Endpoints

- `GET /health`
- `POST /mcp`
- `GET /books`
- `POST /scan`
- `GET /speakers`
- `POST /play`
- `POST /say`
- `POST /stop`
- `GET /status/:speakerId`
- `GET /media/stream.mp3?sessionId=...&sig=...`
- `GET /tts/:id/audio.mp3?sig=...`

Control endpoints require `Authorization: Bearer <CONTROL_AUTH_TOKEN>` when configured. MCP uses `MCP_AUTH_TOKEN`.

## OpenCode MCP Config

```json
{
  "mcp": {
    "cast-audio": {
      "type": "remote",
      "url": "http://127.0.0.1:4130/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:CAST_MCP_TOKEN}"
      }
    }
  }
}
```