Metadata-Version: 2.4
Name: king-crimson-mcp
Version: 0.1.2
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)**
<!-- mcp-name: io.github.ytkoka/king-crimson-mcp -->
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.

## Quick start (for listeners)

You don't need to be a programmer. Three one-time steps, then it runs inside Claude.

### Step 1 — Install `uv` (one time)

`uv` is a small tool that can fetch and run this server for you.

- **macOS / Linux:**
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **Windows (PowerShell):**
  ```powershell
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```

Close and reopen your terminal afterward. To check it worked:
```bash
uv --version
```

### Step 2 — Get your free API keys

This server reads public music databases. Two of them need a free key:

- **setlist.fm** (live performance history) — apply for a key at
  <https://api.setlist.fm/docs/1.0/index.html>
- **Discogs** (physical editions) — create a token at
  Discogs → Settings → Developers → *Generate token*

You also set a **contact email** (`MCP_CONTACT`) — MusicBrainz requires this so
their servers know who's calling. Any email you own is fine.

(MusicBrainz and Cover Art Archive need no key.)

### Step 3 — Add it to Claude Desktop

Open Claude Desktop's config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add this (fill in your email and keys):
```json
{
  "mcpServers": {
    "king-crimson": {
      "command": "uvx",
      "args": ["king-crimson-mcp"],
      "env": {
        "MCP_CONTACT": "you@example.com",
        "SETLISTFM_API_KEY": "your-setlistfm-key",
        "DISCOGS_TOKEN": "your-discogs-token"
      }
    }
  }
}
```
Restart Claude Desktop. King Crimson tools will appear automatically — you don't
run anything in a terminal yourself.

### Step 4 — First use

In Claude, ask something like *"Refresh the King Crimson setlist cache"* once
(it downloads the full concert history, ~40 seconds). After that, try
*"Show me the performance history of Starless"* or
*"Which incarnations played 21st Century Schizoid Man?"*

## Troubleshooting

- **"uvx: command not found" / server won't start in Claude Desktop.**
  `uv` isn't installed or isn't on your PATH. Redo Step 1, then fully quit and
  reopen Claude Desktop. On Windows you may need the full path to `uvx` in the
  `command` field.
- **A warning appears if you run it manually in a terminal.**
  Running `uvx king-crimson-mcp` directly just waits silently for a client —
  that's normal (it speaks over stdin/stdout). You don't need to run it by hand;
  Claude Desktop starts and stops it for you. Press Ctrl+C to stop.
- **`get_editions` / setlist tools return an error about a missing key.**
  That tool's API key isn't set in your config's `env` block. See Step 2.
- **setlist data looks incomplete for older tours.**
  setlist.fm is user-submitted; some historical shows or songs simply aren't
  logged there. This is a data limitation, not a bug.

## Install from PyPI

For developers — the same package as Quick start above, without the Claude Desktop config:

```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).
