replica-omnisciente/.hermes/plans/2026-07-14_160000-music-mvp-aurelio-telegram.md

Music MVP — Full Plan (Debug Mode + Daily Overview + Service Integration)

For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.

Goal: A unified music intelligence layer accessible from Telegram. Debug mode for service visibility, daily music digest, and deep integration with the full media stack.

---

Services Map (Gigabyte — 192.168.0.104)

Service	Port	Docker Container	API	Auth	Status
Navidrome	4533	pf-navidrome	Subsonic REST	user fabio, md5 token+salt	🟢
Lidarr	8686	pf-lidarr	/api/v1	X-Api-Key: 24077d03b9a742a786dd799567659cb8	🟢 688 artists
Prowlarr	9696	pf-prowlarr	/api/v1	X-Api-Key: c45adb4eff734ea491d04e1cbe93bca9	🟢
Slskd	5030	pf-slskd	/api/v0	TBD	🟢 v0.25.1
Jellyfin	8096	pf-jellyfin	REST	API key bc8c6c069daf4e4c8fec660a92114ac4	🟢
Maloja	42010	CT 216	/apis/mlj_1/	public (charts)	🟢
Multi-scrobbler	9078	CT 216	—	—	🟢
qBittorrent	—	pf-qbittorrent	REST	TBD	🟢

External Services

Service	API	Auth	Purpose
Last.fm	ws.audioscrobbler.com	API key b7bc626626486b5b60555db6ef836976, session L2nx0sc...	Scrobbling + charts
MusicBrainz	musicbrainz.org/ws/2	User-Agent header	Artist/album metadata, MBIDs
ListenBrainz	api.listenbrainz.org/1	Token TBD	Open-source scrobbling + recommendations

Data Flow

Playing music:
  Navidrome/Jellyfin → Multi-scrobbler → Maloja + Last.fm + [ListenBrainz]

Discovering music:
  Lidarr → Prowlarr (indexers) → qBittorrent → library
  MusicBrainz → artist metadata, MBIDs, release groups
  Last.fm → user charts, similar artists, tags
  ListenBrainz → recommendations, fresh releases

Converting music:
  Navidrome (download) → MuScriptor (transcribe) → MIDI files

---

Feature 1: Debug Mode

What the user sees in Telegram:

/debug music — full status dashboard
/debug music navidrome — Navidrome logs + config
/debug music lidarr — Lidarr queue + recent activity
/debug music scrobbler — Multi-scrobbler status + recent scrobbles
/debug music services — all service health at a glance
/debug music config navidrome — Navidrome config dump

Tools the MCP server exposes:

# Debug & Monitoring
music_debug_services()                    # health check all services
music_debug_logs(service, lines=50)       # tail Docker logs
music_debug_config(service)               # dump service config
music_debug_scrobbler_status()            # multi-scrobbler sources + clients
music_debug_lidarr_activity()             # recent Lidarr activity (imports, grabs)
music_debug_disk_usage()                  # music library disk usage

Implementation:

Each debug tool maps to a Docker API call or service REST endpoint:

• docker logs --tail N <container> for logs
• docker inspect <container> for config/env
• Service REST APIs for status endpoints

---

Feature 2: Daily Music Overview

What the user sees every morning:

🎵 Daily Music Brief — Monday, July 14

📊 Listening Stats (Last.fm/Maloja)
  Top this week: LCD Soundsystem (12 plays), Caribou (8), Daft Punk (5)
  Total scrobbles today: 23
  New discovery: "Komori Uta" by YIN YIN

🆕 New Releases (from your 688 Lidarr artists)
  • Caribou — "Honey" (single, released today)
  • Tame Impala — "Wings of Time" (single, 2 days ago)
  • LCD Soundsystem — "new body rhumba" (single, 3 days ago)

📥 Library Status
  Lidarr: 2 albums downloading, 0 missing
  Disk: 1.2 TB / 2 TB (60%)
  
🔗 Scrobbler Health
  Navidrome → Maloja: ✅ Last: 2 min ago
  Jellyfin → Maloja: ✅ Last: 1h ago
  Navidrome → Last.fm: ✅ Last: 2 min ago

Tools:

# Daily Overview
music_daily_brief()                       # full daily report
music_new_releases(days=7)                # new releases from followed artists
music_listening_stats(period="week")      # Last.fm + Maloja stats
music_library_health()                    # disk, missing, downloading

New Releases Detection:

Two approaches combined:

1. Lidarr calendar — GET /api/v1/calendar?start=...&end=... — releases Lidarr knows about
2. MusicBrainz — GET /ws/2/release-group?artist=<mbid>&type=album|single&first-release-date:[NOW-7DAYS TO NOW] — any new release from followed artists
3. Last.fm — artist.getNewReleases — if available

---

Feature 3: ListenBrainz Integration

Why:

• Open-source alternative to Last.fm
• Better recommendation engine
• Cross-compatible with MusicBrainz MBIDs
• Can run alongside Last.fm (multi-scrobbler supports multiple clients)

How:

1. Register at listenbrainz.org
2. Get API token
3. Add ListenBrainz as a client in multi-scrobbler config
4. Use ListenBrainz API for recommendations + fresh releases

Multi-scrobbler config addition:

{
  "type": "listenbrainz",
  "name": "ListenBrainz",
  "data": {
    "url": "https://api.listenbrainz.org",
    "token": "<LISTENBRAINZ_TOKEN>"
  }
}

---

Feature 4: MusicBrainz Metadata

What MusicBrainz provides:

• Canonical artist/album/track IDs (MBIDs)
• Release groups, release dates, track listings
• Artist relationships (collaborations, aliases)
• Genre/tag taxonomy
• Cover art via Cover Art Archive

Tools:

# MusicBrainz
music_brainz_search(query)                # search for artist/album
music_brainz_artist_info(mbid)            # detailed artist info
music_brainz_releases(mbid, days=30)      # recent releases for artist
music_brainz_similar(mbid)                # similar artists

---

Implementation Tasks

Task 1: music-mcp server skeleton (with debug tools)

Same pattern as muscriptor-mcp. FastMCP SSE on port 8089.

Task 2: Navidrome client (search, browse, download, stream)

Subsonic API: search3, getAlbumList2, getRandomSongs, getNowPlaying, stream, download.

Task 3: Lidarr client (library management + calendar)

Lidarr v3 API: artist CRUD, queue, wanted, calendar, lookup.

Task 4: Prowlarr client (indexer search)

GET /api/v1/search — search across all configured indexers.

Task 5: Last.fm client (stats, charts, new releases)

user.getTopArtists, user.getTopTracks, user.getRecentTracks, artist.getInfo, artist.getSimilar.

Task 6: MusicBrainz client (metadata, release groups)

/ws/2/artist, /ws/2/release-group, /ws/2/release with proper User-Agent.

Task 7: Debug tools (logs, config, health)

Docker API calls for container logs + inspect. Service REST endpoints for status.

Task 8: Daily overview composer

Combines data from all clients into a formatted daily brief.

Task 9: MuScriptor bridge

Calls muscriptor-mcp's transcribe_to_midi tool.

Task 10: Register + deploy

Register in .aurelio/mcp_config.json. Deploy on Gigabyte. Set up daily cron.

Task 11: ListenBrainz setup

Register account, add to multi-scrobbler, verify scrobbling works.

---

Files Summary

Action	Path
Create	scripts/music-mcp/pyproject.toml
Create	scripts/music-mcp/src/music_mcp/__init__.py
Create	scripts/music-mcp/src/music_mcp/server.py
Create	scripts/music-mcp/src/music_mcp/navidrome_client.py
Create	scripts/music-mcp/src/music_mcp/lidarr_client.py
Create	scripts/music-mcp/src/music_mcp/prowlarr_client.py
Create	scripts/music-mcp/src/music_mcp/lastfm_client.py
Create	scripts/music-mcp/src/music_mcp/musicbrainz_client.py
Create	scripts/music-mcp/src/music_mcp/muscriptor_bridge.py
Create	scripts/music-mcp/src/music_mcp/debug_tools.py
Create	scripts/music-mcp/src/music_mcp/daily_overview.py
Create	scripts/music-mcp/systemd/music-mcp.service
Modify	.aurelio/mcp_config.json

Cron Schedule

Time	Job	Output
8:00 AM	music_daily_brief()	Telegram: daily music overview
On-demand	/debug music	Telegram: service status
On-demand	/search Caribou	Telegram: unified search results
On-demand	/midi Sun Caribou	Telegram: MIDI conversion