# MCP Interface

Quizzical Beats includes an MCP server for agentic round production workflows.
It exposes the same catalog, round, export, email, and custom-audio capabilities
used by the Flask application.

## Run Locally

Install dependencies and start the MCP server from the repository root:

```bash
pip install -r requirements.txt
python -m musicround.mcp_server
```

For a production streamable HTTP endpoint, run the authenticated ASGI entrypoint:

```bash
MCP_BEARER_TOKEN=... uvicorn musicround.mcp_http:app --host 0.0.0.0 --port 8000
```

If `MCP_BEARER_TOKEN` is not set, the HTTP entrypoint falls back to
`AUTOMATION_TOKEN`. Set `MCP_ALLOWED_HOSTS` and `MCP_ALLOWED_ORIGINS` when the
server is exposed behind a reverse proxy or ingress.

The server uses the normal Quizzical Beats Flask configuration. Set the same
environment variables you use for the web app, including `SECRET_KEY`,
`AUTOMATION_TOKEN`, database configuration, mail settings, and any Spotify,
Deezer, OpenAI, AWS Polly, or ElevenLabs credentials needed by the tools you
plan to call.

## Tools

The MCP server exposes these tools:

| Tool | Purpose |
| --- | --- |
| `find_songs` | Search the existing Quizzical Beats catalog before adding duplicates. |
| `add_song` | Add or update a catalog song, including platform IDs and tags. |
| `datastore_schema` | Describe all mapped datastore object types, columns, and primary keys. |
| `list_datastore_objects` | List persisted objects with optional exact-match filters, ordering, limit, and offset. |
| `get_datastore_object` | Fetch one persisted object by primary key. |
| `create_datastore_object` | Create one persisted object from scalar column fields. |
| `update_datastore_object` | Update scalar column fields on one persisted object. |
| `delete_datastore_object` | Delete one persisted object by primary key. |
| `import_catalog_item` | Import a Spotify or Deezer track, album, or playlist. |
| `compile_round` | Create a named round from explicit song IDs or selection criteria. |
| `rename_round` | Set or clear a round name. |
| `create_round_from_playlist` | Import a playlist and turn the imported songs into a round. |
| `generate_round_assets` | Generate the round PDF and/or MP3. |
| `inspect_round_mp3` | Check round MP3 duration, loudness, silence, and clipping indicators. |
| `inspect_round_pdf` | Check round PDF existence and basic structural validity. |
| `send_round_email` | Generate assets and email the finished round bundle. |
| `generate_tts_snippet` | Generate and assign custom intro, replay, or outro TTS MP3s. |

`find_songs` includes `used_count`, `usage_frequency`, and `last_used` for each
result so agents can see how often songs have already appeared in rounds.

The generic datastore CRUD tools operate on mapped SQLAlchemy models, including
`song`, `round`, `tag`, `song_tag`, `user`, `role`, `user_preferences`,
`round_export`, `system_setting`, and `import_job_record`. Read results redact
fields whose names contain `password`, `token`, or `secret` unless
`include_sensitive` is explicitly set.

## Intended Workflow

1. Search with `find_songs` to avoid duplicates.
2. Add missing tracks with `add_song` or import platform content with
   `import_catalog_item`.
3. Create the round with `compile_round` or `create_round_from_playlist`.
4. Generate PDF and MP3 files with `generate_round_assets`.
5. Inspect the generated files with `inspect_round_pdf` and `inspect_round_mp3`.
6. Send the completed bundle with `send_round_email`.

For Spotify imports, pass a `user_id` for a user with connected Spotify tokens.
For email, either pass an explicit recipient or use a selected user that has an
email address.

## Custom Audio

Use `generate_tts_snippet` to update the reusable audio segments:

- `intro`: lead-in before the first song.
- `replay`: announcement before the repeat section.
- `outro`: lead-out after the round.

Supported TTS services follow the existing application helper: `openai`, `polly`,
and `elevenlabs`.