gh-christianlouis-quizzicalbeats/docs/developer-guide/mcp.md

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:

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.