Christian Krakau-Louis
ce97e71239
Add generic MCP CRUD access for mapped datastore objects and include song usage frequency in song query results.
89 lines
3.9 KiB
Markdown
89 lines
3.9 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
|
|
```
|
|
|
|
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`.
|