Metadata-Version: 2.4
Name: king-crimson-mcp
Version: 0.1.0
Summary: An MCP server for King Crimson discography and live-performance history, with a curated line-up-era (incarnation) model.
Project-URL: Homepage, https://github.com/ytkoka/king-crimson-mcp
Project-URL: Repository, https://github.com/ytkoka/king-crimson-mcp
Project-URL: Issues, https://github.com/ytkoka/king-crimson-mcp/issues
Author: ytkoka
License: MIT
License-File: LICENSE
Keywords: discogs,king-crimson,mcp,music,musicbrainz,setlist
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]<2.0.0,>=1.10.1
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# King Crimson Discography MCP Server

**日本語版: [README.ja.md](README.ja.md)**

An MCP server that surfaces King Crimson record and live-performance data — including a curated **incarnation (line-up era) model** that shows how each song belongs to specific eras of the band.

## What makes this different

Generic MusicBrainz/Discogs MCP servers can already fetch releases, credits, and pressings. This server does that too, but adds two things a band-agnostic discography tool structurally can't have:

- **A cross-source integration layer keyed on MBID.** MusicBrainz, Discogs, Cover Art Archive, and setlist.fm are stitched together so one release-group MBID gets you credits, physical editions, artwork, and live history without re-resolving identities per source.
- **A King Crimson incarnation model.** King Crimson's line-up turned over almost completely, many times, over five decades — the same song can mean a totally different band depending on the year. This server hand-curates eight line-up eras and cross-references every tracked song's live-performance history against them:

  | Song | Incarnations it appears in |
  |---|---|
  | "21st Century Schizoid Man" | Spread across *every* era — the band's signature |
  | "Starless" | Only the Larks' Tongues era and the Three-drummer era |
  | "Elephant Talk" | Born in the Discipline era, gone by the Three-drummer era |

- **A local, offline-first concert cache.** Full concert history (1,200+ shows) is fetched once via `refresh_setlist_cache` and cached as JSON. Every subsequent song/tour/era query reads the cache — instant, and immune to setlist.fm's intermittent rate-limit failures during analysis.

## Tools

| Tool | Description |
|---|---|
| `search_release(query, artist="King Crimson", limit=10)` | MusicBrainz album search → MBIDs |
| `get_credits(mbid, release_mbid=None)` | Per-track performer/production credits, resolved at the recording level, plus a deduplicated album roster |
| `get_editions(mbid, max_versions=25)` | Physical pressings/reissues via Discogs, preferring the exact MusicBrainz→Discogs relation over fuzzy search |
| `get_artwork(mbid)` | Cover art via the Cover Art Archive |
| `get_live_history(query="", artist="King Crimson", year=None, limit=20)` | One-page setlist.fm search by venue/city/year (no cache needed) |
| `refresh_setlist_cache(artist_mbid=<King Crimson>, max_pages=100, max_retries=3, force=False)` | Fetch and cache an artist's complete concert history from setlist.fm |
| `song_performance_history(song, artist_mbid=<King Crimson>, match="exact")` | A song's live history from the cache: `by_year`, `by_tour`, `by_incarnation` |
| `get_incarnations()` | The curated line-up eras — members, instruments, key releases |

## The incarnation model

Eight line-up eras, split on membership changes:

| id | Era | Years |
|---|---|---|
| `kc_1969` | In the Court era | 1969 |
| `kc_1970_1972` | Transitional era | 1970 – Sep 1972 |
| `kc_1972_1974` | Larks' Tongues era | Oct 1972 – 1974 |
| `kc_1981_1984` | Discipline era | 1981 – 1984 |
| `kc_1994_1997` | Double Trio / THRAK era | 1994 – 1996 |
| `kc_1997_2003` | ProjeKcts / Nuovo Metal era | 1997 – 2003 |
| `kc_2008` | 40th Anniversary era | 2008 |
| `kc_2014_2021` | Three-drummer era | 2014 – 2021 |

Boundaries are dates, not just years — 1972 in particular splits into the Islands-era "Earthbound" spring tour (Transitional) and the Wetton-era autumn tour (Larks' Tongues), since the band's membership genuinely changed mid-year.

Line-up eras are a matter of fan interpretation, and this is one reasonable cut, not the only one. The full definition lives in `KING_CRIMSON_INCARNATIONS` in `src/king_crimson_mcp/server.py` — edit it (members, key releases, date boundaries) to match your own view; the aggregation logic doesn't need to change.

## Install from PyPI

The easiest way to run the server — no clone, no venv:

```bash
# run directly without installing (recommended)
uvx king-crimson-mcp

# or install as a persistent tool
pipx install king-crimson-mcp
king-crimson-mcp
```

Secrets (`MCP_CONTACT`, `DISCOGS_TOKEN`, `SETLISTFM_API_KEY`) go either in a `.env` file in the directory you run the command from, or directly in the Claude Desktop config's `env` block (see below) — either is read. `.env` is loaded from the current working directory, since an installed package has no project directory of its own to keep one in.

## Setup from source (development)

```bash
# Python 3.10+ required (3.12 recommended)
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

# configure secrets
cp .env.example .env
# then edit .env
```

`.env` variables:

- `MCP_CONTACT` — required by MusicBrainz policy; identifies your app to their API via the User-Agent header.
- `DISCOGS_TOKEN` — needed for `get_editions` (Discogs personal access token).
- `SETLISTFM_API_KEY` — needed for `get_live_history`, `refresh_setlist_cache`, and `song_performance_history`.
- `KC_CACHE_DIR` — optional; overrides where the setlist cache is written (see below).

## Running

```bash
# quick tool check via MCP Inspector
mcp dev src/king_crimson_mcp/server.py
```

Run `refresh_setlist_cache` once first — it fetches King Crimson's full concert history (~1,200 shows, ~40 seconds) and caches it locally under `$XDG_CACHE_HOME/king-crimson-mcp` (or `~/.cache/king-crimson-mcp`; override with `KC_CACHE_DIR`). After that, `song_performance_history` reads from the cache and returns instantly.

## Register with Claude Desktop

Using the published package:

```json
{
  "mcpServers": {
    "king-crimson": {
      "command": "uvx",
      "args": ["king-crimson-mcp"],
      "env": {
        "MCP_CONTACT": "you@example.com",
        "DISCOGS_TOKEN": "...",
        "SETLISTFM_API_KEY": "..."
      }
    }
  }
}
```

Or, running from a local clone instead (after `uv pip install -e .`, which installs the same `king-crimson-mcp` console script into the venv):

```json
{
  "mcpServers": {
    "king-crimson": {
      "command": "/absolute/path/to/.venv/bin/king-crimson-mcp",
      "env": { "MCP_CONTACT": "you@example.com" }
    }
  }
}
```

Secrets can live in `.env` (in the directory the command is run from) instead of the `env` block — either is read.

## Data sources & attribution

This project is an **unofficial client** with no affiliation with or endorsement from MusicBrainz, the MetaBrainz Foundation, the Internet Archive, Discogs, or setlist.fm.

- **[MusicBrainz](https://musicbrainz.org/)** — free, no API key. Requires an identifying User-Agent with contact info (rate limit: 1 req/sec). Data is largely CC0; crediting MusicBrainz in your app is good practice.
- **[Cover Art Archive](https://coverartarchive.org/)** — a joint MusicBrainz / Internet Archive project. Images are contributed by individual uploaders; follow the same attribution etiquette as MusicBrainz.
- **[Discogs](https://www.discogs.com/developers)** — requires a personal access token and a unique User-Agent (60 req/min authenticated). Use is subject to the Discogs API terms of service.
- **[setlist.fm](https://api.setlist.fm/docs/1.0/index.html)** — requires an API key (apply at api.setlist.fm). **Any display of setlist.fm data must include an attribution link to the source setlist** — every performance returned by this server includes its `url` for exactly that purpose; surface it wherever you show the data. setlist.fm data is user-submitted, so completeness and accuracy are not guaranteed.

## Limitations

- setlist.fm data is user-submitted — some shows or songs may be missing or incorrect, especially from older tours.
- The incarnation boundaries are one interpretation of King Crimson's line-up history, not an official taxonomy.
- Performer credits depend on what MusicBrainz has cataloged for a given release; sparser releases yield sparser credits.

## License

MIT — see [LICENSE](LICENSE).
