Search MusicBrainz for release groups (albums) matching a query.

A "release group" is the canonical album, independent of its many physical editions -- the right granularity for browsing a discography. Use the returned mbid with the other tools.

Args: query: Free-text album title or keywords (e.g. "Red", "Larks' Tongues"). artist: Restrict to this artist. Defaults to "King Crimson". limit: Max results (1-25).

Returns: A dict with a results list of {mbid, title, primary_type, first_release_date, disambiguation}.

Get performer and production credits for an album (release group).

Returns the headline artist credit and release-group relationships, plus per-track performer credits resolved from the recording level in MusicBrainz (individual musicians and their instruments), and a deduplicated album roster.

Args: mbid: MusicBrainz release-group ID (from search_release). release_mbid: Optional specific release (edition) to read track credits from. If omitted, a representative official release is chosen.

Returns: A dict with title, artist_credit, release_used, performers (roster), tracks (per-track credits), relations, and external_links.

List physical editions/pressings of an album via Discogs.

Resolves the Discogs master for the album -- preferring the discogs relation stored on the MusicBrainz release group (exact match), and falling back to a Discogs title/artist search when no such relation exists. Then lists the master's versions (pressings, reissues, box sets) with format, country, year and community stats. Requires DISCOGS_TOKEN.

Args: mbid: MusicBrainz release-group ID (from search_release). max_versions: Max editions to return (1-50).

Returns: A dict with master info and a versions list. match_method reports how the master was resolved ("musicbrainz-relation" or "discogs-search").

Get cover art for a release group from the Cover Art Archive.

Args: mbid: MusicBrainz release-group ID (from search_release).

Returns: A dict with an images list of {front, back, thumbnails, url}.

Search live performance history / setlists via setlist.fm.

Useful for King Crimson given their extensive touring: cross-reference official live albums against what was actually played on a given tour. Requires SETLISTFM_API_KEY.

Args: query: Optional venue or city keyword to narrow the search. artist: Artist name. Defaults to "King Crimson". year: Optional year filter. limit: Max setlists to return (1-20; one API page).

Returns: A dict with a setlists list of {date, venue, city, country, songs}.

Fetch an artist's complete concert history from setlist.fm and cache it locally as JSON, so song/tour analysis runs instantly and offline.

Robust against setlist.fm's intermittent failures: each page is retried with backoff, and any page that still fails is recorded rather than aborting the whole run. King Crimson's history is fixed (band ended 2021), so this rarely needs re-running. Requires SETLISTFM_API_KEY.

Args: artist_mbid: MusicBrainz artist MBID. Defaults to King Crimson. max_pages: Safety cap on pages to fetch (20 shows/page). max_retries: Retries per page on transient error before recording it failed. force: Re-fetch even if a cache file already exists.

Returns: A summary dict (not the setlists themselves): counts, coverage, any failed pages, date range, and the cache file path.

List King Crimson's line-up eras (incarnations): id, name, date range, members with instruments, key releases, and a one-line note.

Use this to look up who played in a given era. Song analysis (song_performance_history) reports per-era counts under by_incarnation keyed by the same ids/names, so this is the reference for those.

Returns: A dict with an incarnations list.

Trace how often and when a song was played live, from the local setlist cache. Run refresh_setlist_cache first. Aggregates by year and by tour so a song's life across decades and line-ups is visible at a glance.

Args: song: Song title to trace (e.g. "Starless", "21st Century Schizoid Man"). artist_mbid: MusicBrainz artist MBID. Defaults to King Crimson. match: "exact" (case-insensitive full title) or "contains" (substring).

Returns: A dict with cache_info, performance_count, first/last performance, by_year and by_tour breakdowns, and the list of performances.

Fetch King Crimson's official live releases from MusicBrainz and cache them locally, parsing a recording date out of each title where possible.

Used by song_live_releases to map songs to the live albums that captured them. King Crimson's live catalog is fixed, so this rarely needs re-running. Requires MCP_CONTACT (MusicBrainz User-Agent policy).

Args: artist_mbid: MusicBrainz artist MBID. Defaults to King Crimson. max_pages: Safety cap on pages to fetch (100 release groups/page). max_retries: Retries per page on transient error (e.g. MusicBrainz's intermittent 503s) before giving up. force: Re-fetch even if a cache file already exists.

Returns: A summary: totals, how many titles yielded a full recording date, and the cache path.

Find official live releases that captured a given song, grouped by incarnation (line-up era).

How it works: the song's performance dates come from the setlist cache; live releases carry a recording date parsed from their title. Where a release's recording date matches a date the song was played, that release is taken to contain the song. This is authoritative for single-show live albums; excerpt compilations are an edge case.

Requires both caches: run refresh_setlist_cache and refresh_live_releases_cache first.

Args: song: Song title (e.g. "Red"). artist_mbid: MusicBrainz artist MBID. Defaults to King Crimson. match: "exact" (case-insensitive full title) or "contains" (substring).

Returns: by_incarnation groupings of matched live releases, plus a coverage note stating how many live releases could not be matched by date (box sets, compilations, undated titles) so the caller can decide to search further.

Fetch King Crimson's compilations and box sets from Discogs and cache their tracklists, so song_box_sets can list which box sets contain a song.

Filters the artist's Discogs releases to Main-role compilations/box sets (format contains "Comp" or "Box"), which excludes single-show live downloads (those are covered by song_live_releases). Requires DISCOGS_TOKEN.

Returns: A summary: releases scanned, box sets cached, and the cache path.

List King Crimson box sets / compilations that contain a given song (from Discogs). Complements song_live_releases: that tool maps single-show live albums to eras; this one covers the multi-show box sets and comps that date-matching can't resolve.

Run refresh_box_sets_cache first.

Args: song: Song title (e.g. "Red"). artist_mbid: MusicBrainz artist MBID (cache key). Defaults to King Crimson. match: "exact" (case-insensitive full track title) or "contains".

Returns: The box sets/compilations whose tracklist includes the song, with title, year, format, Discogs URL, and how many times the song appears on each.