gitea-admin/gh-christianlouis-quizzicalbeats

Files

T

Christian Krakau-Louis 74e5e5b531 Add MCP automation interface for quiz round creation (#9 )

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.

2026-05-21 18:18:57 +02:00

2.5 KiB

Raw Blame History

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

Search with find_songs to avoid duplicates.
Add missing tracks with add_song or import platform content with import_catalog_item.
Create the round with compile_round or create_round_from_playlist.
Generate PDF and MP3 files with generate_round_assets.
Inspect the generated files with inspect_round_pdf and inspect_round_mp3.
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.

2.5 KiB Raw Blame History