MCP acceptance case: populate the empty music collections via the MCP write path (not by hand) #487
Closed
opened 2026-07-20 00:19:30 +02:00 by timothy
·
4 comments
No Branch/Tag Specified
main
renovate/dotnet-monorepo
renovate/meziantou.analyzer-3.x
renovate/lucene.net
renovate/sqlitepclraw.bundle_e_sqlite3-3.x
renovate/cliwrap-3.x
913-scripted-playout-401
release/v26.15.0-notes
issue-806-guard-populations
scratch/767b-poisoned
scratch/767b-control
release/v26.14.0-notes
release/v26.14.0
docs/510-skill-logo-bug-policy
fix/510-watermark-resolution-policy
fix/629-verdict-classifier-falseopens
fix/609-decisions-edit-token-scope
issue-135-clear-to-none
release/v26.12.0-notes
fix/409b-lastscan-api-parity
fix/401-updatechannel-mirror-422
fix/327-playlist-rename-validation
fix/410-scancancel-log-level
fix/409-447-librariesscreen-neverscanned
fix/338-zap-exit-code
fix/367-plex-budget-message
fix/310-debom-legacy-cs
ci/604-lane-rebalance
feat/388-design-mirror
feat/247-test-ownership
feat/247-primary-action
feat/357-player-owned-playback
feat/357-jellyfin-plugin-poc
fix/289-mcp-hardening
issue58-mcp
feat/244-channels-extract
ci/auto-bump-prod-compose
feat/multi-rerun-collections-api
feat/collections-api
feat/quick-wins
feat/185-docs-part2
feat/140-collections-screen
feat/146-channel-edit
feat/147-classic-ui-link
issue22-renovate-dashboard
feat/91-cutover
feat/63-composite-create
feat/65-library-browse
feat/85-epg
feat/86-schedule-editor
feat/109-dashboard-data
feat/99-session-tracking
fix/dockerfile-node-tag
feat/59-spa-foundation
docs/59-ui-redesign-brief
feat/102-json-guide
feat/111-schedule-durations
feat/104-artwork-upload
feat/103-media-sources-api
feat/playouts-read-api
feat/108-health-api
feat/105-picker-list-endpoints
issue-97-channel-state-api
issue42-jellyfin-musicvideos
issue46-rest-api-error-contract
dependabot/nuget/ErsatzTV.FFmpeg.Tests/multi-d307a2e06f
qsv-improvements
hdr-vulkan-cuda-test
v26.16.0
v26.15.0
v26.14.0
v26.13.0
v26.12.0
v26.11.0
v26.10.0
v26.9.0
v26.8.0
v26.7.0
blazor-final
v26.6.0
v26.5.0
v26.4.0
v26.3.1
v26.3.0
v26.2.0
v26.1.1
v26.1.0
v25.9.0
v25.8.0
v25.7.1
v25.7.0
v25.6.0
v25.5.0
v25.4.0
v25.3.1
v25.3.0
v25.2.0
v25.1.0
v0.8.8-beta
v0.8.7-beta
v0.8.6-beta
v0.8.5-beta
v0.8.4-beta
v0.8.3-beta
v0.8.2-beta
v0.8.1-beta
v0.8.0-beta
v0.7.9-beta
v0.7.8-beta
v0.7.7-beta
v0.7.6-beta
v0.7.5-beta
v0.7.4-beta
v0.7.3-beta
v0.7.2-beta
v0.7.1-beta
v0.7.0-beta
v0.6.9-beta
v0.6.8-beta
v0.6.7-beta
v0.6.6-beta
v0.6.5-beta
v0.6.4-beta
v0.6.3-beta
v0.6.2-beta
v0.6.1-beta
v0.6.0-beta
v0.5.8-beta
v0.5.7-beta
v0.5.6-beta
v0.5.5-beta
v0.5.4-beta
v0.5.3-beta
v0.5.2-beta
v0.5.1-beta
v0.5.0-beta
v0.4.5-alpha
v0.4.4-alpha
v0.4.3-alpha
v0.4.2-alpha
v0.4.1-alpha
v0.4.0-alpha
v0.3.8-alpha
v0.3.7-alpha
develop
v0.3.6-alpha
v0.3.5-alpha
v0.3.4-alpha
v0.3.3-alpha
v0.3.2-alpha
v0.3.1-alpha
v0.3.0-alpha
v0.2.5-alpha
v0.2.4-alpha
v0.2.3-alpha
v0.2.2-alpha
v0.2.1-alpha
v0.2.0-alpha
v0.1.5-alpha
v0.1.4-alpha
v0.1.3-alpha
v0.1.2-alpha
v0.1.1-alpha
v0.1.0-alpha
v0.0.62-alpha
v0.0.61-alpha
v0.0.60-alpha
v0.0.59-alpha
v0.0.58-alpha
v0.0.57-alpha
v0.0.56-alpha
v0.0.55-alpha
v0.0.54-alpha
v0.0.53-alpha
v0.0.52-alpha
v0.0.51-alpha
v0.0.50-alpha
v0.0.49-prealpha
v0.0.48-prealpha
v0.0.47-prealpha
v0.0.46-prealpha
v0.0.45-prealpha
v0.0.44-prealpha
v0.0.43-prealpha
v0.0.42-prealpha
v0.0.41-prealpha
v0.0.40-prealpha
v0.0.39-prealpha
v0.0.38-prealpha
v0.0.37-prealpha
v0.0.36-prealpha
v0.0.35-prealpha
v0.0.34-prealpha
v0.0.33-prealpha
v0.0.32-prealpha
v0.0.31-prealpha
v0.0.30-prealpha
v0.0.29-prealpha
v0.0.28-prealpha
v0.0.27-prealpha
v0.0.26-prealpha
v0.0.25-prealpha
v0.0.24-prealpha
v0.0.23-prealpha
v0.0.22-prealpha
v0.0.21-prealpha
v0.0.20-prealpha
v0.0.19-prealpha
v0.0.18-prealpha
v0.0.17-prealpha
v0.0.16-prealpha
v0.0.15-prealpha
v0.0.14-prealpha
v0.0.13-prealpha
v0.0.12-prealpha
v0.0.11-prealpha
v0.0.10-prealpha
v0.0.9-prealpha
v0.0.8-prealpha
v0.0.7-prealpha
v0.0.6-prealpha
v0.0.5-prealpha
v0.0.4-prealpha
v0.0.3-prealpha
v0.0.2-prealpha
v0.0.1-prealpha
Labels
Clear labels
ad-hoc
api
bug
ci-cd
content
dependencies
enhancement
frontend
in-progress
jellyfin
parked
priority: high
priority: low
priority: medium
review
security
One-off / ad-hoc work not tracked by a dedicated issue
REST API / HTTP endpoints
Something isn't working
Build, test, deploy pipeline
Channel content / schedules / playlists
Dependency updates (Renovate)
New feature or improvement
ChicoryTV React SPA frontend
Claimed by an active session — do not pick up
Jellyfin tuner / IPTV integration
Excluded from automatic queue pickup; work only when explicitly selected
Adversarial review finding
Security / vulnerability fix
Milestone
No items
No Milestone
Projects
Clear projects
No projects
No Assignees
Notifications
Due Date
No due date set.
Depends on
Reference: timothy/ersatztv#487
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Split out of #474 by operator decision: do not hand-populate these collections. They are being deliberately reserved as the first realistic write-path acceptance case for the MCP server (#58).
Why this is a good test case
It is a real task with real stakes, not a synthetic fixture, and it exercises exactly the shape #58 says it wants to support — "expose useful read actions first … add write actions only where the API contract is stable and operations are safe/idempotent enough for tool use":
CollectionItemrows. Re-running the whole operation should be a no-op.CollectionItemcounts go non-zero, the playouts build, and theCollection "X" has no valid items!ERRflood stops.Precondition (blocking)
Depends on #474: Jellyfin's
Music Videoslibrary must be re-added with content typeMusic videosand synced, soArtist/MusicVideorows actually exist. Until then there is nothing to add to a collection. Do not start this before #474 reports a successful scan.The data
10 collections currently hold 0
CollectionItemrows (Concert Filmsholds 1), so their playouts fail every rebuild cycle:/data/music?VaporwaveJungleElectronicBehind the MusicMTV UnpluggedConcert Films(already has 1 item)Glastonbury+Glastonbury ConcertsHipHopHistoryGuy,Cookin Soul,Soul Train,Yo MTV RapsTop of the Pops,BBC Old Grey Whistle Test 70s Gold,The Midnight SpecialThe exact-match rows are the mechanical half; the ambiguous rows are the half that needs an operator decision. Both halves are wanted — an MCP that can only do the unambiguous ones has not been shown to be useful.
Full folder list (30) is in the #474 evidence.
Done-when
Artist/MusicVideorows presentCollectionItemrows)has no valid items!ERRflood is gone from the prod logNotes
If this turns out to be blocked by a gap in the MCP write surface, that gap is the finding — file it against #58 rather than working around it by hand. Falling back to manual population defeats the purpose of reserving the task.
Field data changes this task's shape — read before picking it up
Live investigation during #489's E2E (2026-07-20) answered the "ambiguous four" question and, more importantly, showed the premise of this issue is wrong in a useful way.
There is no artist grouping to hang collections on
/data/musichas no usable per-item artist metadata:ffprobe format_tags).info.json(uploader/channel)<artist><title>,<plot>, artwork, but no artistMeasured directly: typing the library
musicvideosand scanning produced 1437 music videos across 138 "artists", of which 1194 (83%) wereUnknown Artist— the rest junk fragments parsed from filenames (BBC Music×47,BBC×26,4 goes to×6). Not one of the 30 folders became an artist. Typing itmixedinstead produced 1438 ungrouped Movies, which is worse.So "add the artist to the collection" — the mechanism this issue assumes — does not exist. Any plan built on artist grouping will fail.
What does work: folder →
<tag>, proven end to endPiloted on
/data/music/Vaporwave(206 NFOs):<tag>Vaporwave</tag>into each<musicvideo>-root NFO (204; the 2<movie>-root files skipped), preserving BOM and encoding — all 206 still parse as well-formed XML.<artist>from the.info.jsonuploader/channelwhere available — 154 real artists (DoogerWooger,Aim To Head Official,Music Farm). Deliberately not the folder name: a folder is not an artist, and inventing 30 fake artists to make collections convenient would corrupt the data model.Tagrows, all correctly linked toMusicVideoMetadata.tagandgenreare both first-class searchable fields (ErsatzTV.Application/Search/SearchFieldCatalog.cs:21-22), so these become smart collections that auto-populate and stay current — strictly better than the manualCollectionItemmembership this issue originally proposed. The MCP write path then creates/edits a smart-collection rule per folder, rather than resolving and adding N items by hand.Blocked by #497
Bulk-tagging the remaining 29 folders will appear to do nothing.
JellyfinMusicVideoLibraryScanner.UpdateMetadatacopies only scalars, soTags/Genres/Studiosare dropped for items that already exist. Proven with identical Jellyfin data: 0 tags on rescan of existing items (evendeep=true) vs 204 on a clean first scan. Until #497 lands, the only way to pick up new tags is to wipe and rescan the library.Suggested revision to this issue
Music Video Mix,Glastonbury Live,Hip Hop & Soul,Retro TV Music) stay an operator decision, but become a rule decision (which tags to OR together) rather than an item-picking exercise — e.g.Hip Hop & Soul=HipHopHistoryGuyORCookin SoulORSoul TrainORYo MTV Raps.The tagging script used for the pilot is reusable for the bulk run; it is idempotent (skips files that already carry the tag) and additive.
Claiming as the live acceptance case for the MCP write path (#58 / PR #517, MERGEABLE). Scoped this session to the one already-tagged folder — Vaporwave — per the reshape in the comment above (the 29-folder NFO-tagging sweep is deferred as a separate content task, and #497 is now closed/deployed on prod v26.11.0 so tags will propagate).
Read probe against prod (v26.11.0) via the MCP, read-only, confirmed the setup:
get_collection_items→totalCount:0, ETag"0").ersatztv_search_all_itemstag:"Vaporwave"→ 204 musicVideoIds (matches the pilot's 204 tagged items).Proceeding to populate collection 20 through
ersatztv_add_collection_items(musicVideoIds), verify the count, prove idempotence by re-running, then rebuild the Vaporwave channel's playout and confirm thehas no valid items!ERR flood stops for it.Acceptance case PASSED (Vaporwave) — the MCP write path is proven live on prod ✅
Ran entirely through the
ErsatzTV.Mcpwrite path (#58 / PR #517) against prod (v26.11.0),ERSATZTV_ALLOW_WRITES=true, machine key from/config/api.key:ersatztv_search_all_itemstag:"Vaporwave"musicVideoIdsersatztv_add_collection_items(collection 20, 204 ids)ersatztv_get_collection_items(20)totalCount0 → 204add_collection_itemsCollectionItemrows)ersatztv_reset_channel_playout(29)ersatztv_get_playout/_items(playout 28)buildStatus.success = true, 47 upcoming items scheduledCollection "Vaporwave" has no valid items!So the channel is revived and the write path is idempotent, existence-checked, and observable — exactly what this issue reserved the task to prove.
Done-when (Vaporwave scope)
success=true, 47 items)has no valid items!flood gone for VaporwaveDeferred (tracked, not done here)
<tag>yet). That is content-file work on/data/music(media-management-flavored); #497 is now closed/deployed so tags will propagate on rescan. Splitting that out as the remaining work on this issue.Leaving this issue open for the 29-folder sweep; removing my
in-progressclaim. The MCP-write-path half is done and proven.Closing record
Outcome: The deferred 29-folder half is done. All 30
/data/musicfolders are now<tag>-stamped, and all 11 music collections are populated through the MCP write path — no SQL, no SPA. 1,184 items added across 10 previously-empty collections (Vaporwave's 204 were already done in the pilot).Root cause (why the collections were empty): two stacked causes, both now cleared. The folders carried no
<tag>at all (only the Vaporwave pilot did), and until #497 landed,JellyfinMusicVideoLibraryScanner.UpdateMetadatadroppedTagson already-existing items so a rescan could never pick them up. With #497 deployed (verified: running image digestfc8cb8ed…== registry:prod), tagging + rescan propagated cleanly.Decisions/conventions changed: none. The operator rule-decision for the ambiguous collections is recorded in the table above (approved 2026-07-25).
Reusable knowledge:
tag:is an analyzed Lucene field, so a one-word tag phrase-matches any tag containing that token.tag:"Glastonbury"returns 246 (its own 59 plus all 187Glastonbury Concerts);tag:"Electronic"returns 27 because it also matchesX-mix 5 - Mr. C - The Electronic Storm. There is no exact-tag operator. Both effects were benign/intended here, but tag-driven automation must not assume exact matching.<Base> - <variant>.mp4files into one multi-version item —Behind the Music(61 files) andTop of the Pops(24 files) each collapse to a single item. Filed as #615.pageNumis 0-based but documented 1-based (silently returns a short set), over-largepageSizecaps the page but not the offset, and playout rows carry nochannelIdwhilereset_channel_playoutwants one.Verification:
<artist>written; re-run reports0 added / 1476 already tagged. 1513/1515 NFOs parse (the 2 failures are pre-existing malformed files with an unescaped&; the tagger refused to write them and they are untouched). Backup of all 1,515 NFOs at/home/timothy/etv487-nfo-backup-2026-07-25.tgzon jazz.15→15, 246→246, 394→394, 274→274, 27→27, 204→204, 124→124, 29→29, 49→49, 1→1, 17→17). No duplicateCollectionItemrows.buildStatus.success = true; the 11 music playouts carry 15–244 scheduled items. Lasthas no valid items!entry is 17:00:40, before population; forced rebuilds of every music channel at 17:09:44–17:10:11 produced zero new entries in stdout or the structured log store.Deferred:
Behind the Musicat 1 item andTop of the Popsat 1 of 24. Needs a content-modelling decision (rename ~85 files vs. re-home as a TV library).Classic Albums(45 items) is tagged but unassigned — no existing collection claims it and it didn't fit any of the 11. Left deliberately unassigned rather than guessed; say the word and it's a one-line add.Electroniccarries 27, not 26 —X-mix 5 - Mr. C - The Electronic Stormmatches on theelectronictoken. Left in place: it is thematically correct, collections may overlap, and removing it would be undone by any re-run of the rule. Flagged rather than silently corrected.Docs updated: none required — no repo code changed. This was prod data operations plus two throwaway ops scripts; the MCP server was built from a clean
origin/mainworktree and not modified.Review posture: no code diff to review. The scripts were self-reviewed adversarially (dry-run before write, format-preserving splice, XML well-formedness gate, DTD/entity refusal, full backup, idempotence positive-control on the already-tagged folder, and a deliberately non-circular provenance check). Per
process.independent-review-rubricthis is a stated exemption: no C# change, no API surface change, no migration — but it does mutate prod state, so the verification above is deliberately heavier than a code review would be.The tagging script (preserved — the pilot's version was lost by living only in a session)
Run as
python3 tag_music_nfos.py --root /mnt/media/music_videos [--dry-run] [--folder NAME].(driver/reporting boilerplate omitted; the load-bearing logic is above)