Christian Krakau-Louis
74e5e5b531
Add a Quizzical Beats MCP server and automation service for agentic quiz workflows. Includes tools for catalog lookup/add/import, round creation and naming, MP3/PDF generation and inspection, email delivery, TTS snippet updates, docs, and focused tests. Deployment intentionally not performed.
64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# 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
|
|
```
|
|
|
|
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. |
|
|
| `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. |
|
|
|
|
## 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`.
|