mcp-phish

Ein MCP-Server, der die APIs api.phish.net v5 und phish.in v2 hinter einer einheitlichen, typisierten Tool-Oberfläche zusammenfasst. Zwölf Tools für Setlisten, Songs, Jam-Charts, Rezensionen und Audio. Jede Antwort wird durch fixierte Pydantic-Modelle geformt, sodass das Übertragungsformat auch bei Änderungen der zugrunde liegenden APIs stabil bleibt.

Aufgebaut auf FastMCP mit Streamable HTTP-Transport. Entwickelt für den Betrieb in einem vertrauenswürdigen LAN oder hinter einem Tailscale-ACL — es gibt keine integrierte Authentifizierung auf MCP-Ebene.

Warum

Heutzutage besteht das Phish.net + phish.in-Ökosystem aus einer kleinen Menge ungepflegter Wrapper und Einmalskripte. Niemand kombiniert beides sauber. mcp-phish bietet jedem MCP-fähigen Client (Claude Code, Claude Desktop, benutzerdefinierte Agenten) eine fokussierte, gut typisierte Oberfläche für die Fragen, die Fans tatsächlich stellen: Setliste für ein Datum, Song-Debüt und -Lücke, Audio-URL für einen Track, Jam-Chart-Hits für eine Tour.

Die Quelle kann sich ändern (Live-API → zwischengespeichert → Vault). Die Pydantic-Formen, die an MCP-Clients zurückgegeben werden, tun dies nie.

Schnellstart

docker run --rm \
  -p 3705:3705 \
  -e STUB_MODE=true \
  ghcr.io/pete-builds/mcp-phish:latest

Der Server startet standardmäßig im Stub-Modus. Er liefert realistische Mock-Daten und benötigt keinen Netzwerkzugriff oder API-Schlüssel. Registrieren Sie ihn bei Claude Code:

claude mcp add phish --transport http --scope user --url http://localhost:3705/mcp

Fragen Sie dann Claude: "Was war die Setliste am 30.12.95?" und Sie sollten das Madison Square Garden-Konzert mit dem Mike's > Simple > Weekapaug-Groove erhalten.

Um die echten APIs zu nutzen, registrieren Sie einen kostenlosen Schlüssel unter api.phish.net/keys/ und schalten Sie den Stub-Modus aus:

docker run --rm \
  -p 3705:3705 \
  -e STUB_MODE=false \
  -e PHISHNET_API_KEY=<your-key> \
  ghcr.io/pete-builds/mcp-phish:latest

Tool-Referenz

Jedes Tool gibt einen JSON-String mit dem Standard-Envelope zurück:

{"data": <typed payload>}

oder bei einem Fehler:

{
  "error": "human-readable message",
  "code": "UPSTREAM_DOWN | NOT_FOUND | INVALID_INPUT | RATE_LIMITED | INTERNAL",
  "details": { "...": "..." }
}

Die Pydantic-Modelle in src/mcp_phish/models.py (ShowSummary, Show, SetlistEntry, Song, Performance, NotableJam, Review, Track, ShowAudio, Health) sind der öffentliche Vertrag. Sie sind mit extra="forbid" fixiert, sodass jede Änderung der Upstream-API zu einem Validierungsfehler führt, anstatt zu einer stillschweigenden Änderung der Datenstruktur.

Stub-Modus vs. Real-Modus

Der Wechsel der Modi ist eine Konfigurationsänderung, keine Codeänderung. Dieselben zwölf Tools, dieselben Antwortformen.

Caching

mcp-phish unterhält einen undurchsichtigen Key-Value-Cache auf der Festplatte (/data/phish-cache.db, aiosqlite), der mit (endpoint, params_hash) indiziert ist. Ein einzelner TTL steuert jeden Eintrag (CACHE_TTL_SECONDS, Standard 86400 = 24h). Bei einem Treffer erfolgt kein Upstream-Aufruf.

Dieser Cache ist kein normalisierter Datenspeicher. Er enthält lediglich rohe JSON-Antworten, um die Upstream-Ratenbegrenzungen einzuhalten und wiederholte LLM-gesteuerte Erkundungen schnell zu machen. Betrachten Sie ihn als flüchtig.

Drosselung (Throttling)

Jeder Upstream-Aufruf durchläuft einen Token-Bucket pro Instanz mit einer konfigurierbaren Steady-State-Rate:

Der Bucket ist prozessintern. Mehrere Container koordinieren sich nicht. Der Token-Status wird in health() offengelegt, sodass eine Claude Code-Sitzung sehen kann, was noch übrig ist.

Konfiguration

Die gesamte Konfiguration wird aus Umgebungsvariablen (und einer .env-Datei, falls vorhanden) gelesen. Pydantic validiert beim Start und schlägt bei ungültigen Werten sofort fehl.

Ein vollständiges Beispiel befindet sich in .env.example.

MCP-Client-Einrichtung

Claude Code

claude mcp add phish --transport http --scope user --url http://<host>:3705/mcp

Claude Desktop

{
  "mcpServers": {
    "phish": {
      "transport": "streamable-http",
      "url": "http://<host>:3705/mcp"
    }
  }
}

Generische Konfiguration

Streamable HTTP unter http://<host>:3705/mcp. Jeder MCP-Client, der das Streamable HTTP-Transportprotokoll unterstützt, kann eine Verbindung herstellen.

Architektur

+---------------------+     Streamable HTTP     +---------------------+
|  MCP Client         |  -------------------->  |  mcp-phish          |
|  (Claude Code, etc) |  <--------------------  |  (FastMCP server)   |
+---------------------+                         +----+--------------+-+
                                                     |              |
                                                     |              |
                                                     v              v
                                          +----------+--+   +-------+--------+
                                          | api.phish.net|   | phish.in/api/v2|
                                          |     v5       |   |                |
                                          +--------------+   +----------------+

                                                     ^
                                                     |
                                          +----------+----------+
                                          | aiosqlite KV cache  |
                                          |  /data/phish-cache  |
                                          +---------------------+

mcp-phish ist ein schlanker asynchroner Proxy mit einem kleinen Cache: Er übersetzt MCP-Tool-Aufrufe in Upstream-REST-Aufrufe, speichert rohe Antworten für den konfigurierten TTL zwischen und projiziert sie in die öffentliche Pydantic-Form. Er speichert keinen Zustand über diesen Cache hinaus. Er ruft keine anderen Cloud-Dienste auf als die beiden Phish-APIs.

Sicherheitshinweise

• Betreiben Sie mcp-phish in einem vertrauenswürdigen LAN, über Tailscale oder hinter einem Reverse-Proxy mit Authentifizierung. Der Server selbst authentifiziert MCP-Clients nicht.

• API-Schlüssel befinden sich nur in der Umgebung des Containers. Sie werden niemals protokolliert, niemals in Antworten wiederholt und niemals auf die Festplatte geschrieben.

• Der Container läuft als UID 1000, ohne Shell, ohne Home-Verzeichnis, mit einem schreibgeschützten Root-Dateisystem (/tmp ist tmpfs) und no-new-privileges.

• Das /data-Cache-Volume ist der einzige beschreibbare Pfad.

• Python-Abhängigkeiten werden mit pip --require-hashes aus einer hash-gesperrten requirements.lock installiert. Das Basis-Image wird vor der ersten getaggten Version per Digest fixiert.

• Veröffentlichte Images sind Multi-Arch (amd64/arm64) mit Build-Provenienz und SBOM via docker/build-push-action.

Für Schwachstellenberichte siehe SECURITY.md.

Entwicklung

Erfordert Python 3.13+ und Docker.

# Clone + install dev deps
git clone https://github.com/pete-builds/mcp-phish.git
cd mcp-phish
python -m venv .venv && source .venv/bin/activate
pip install --require-hashes -r requirements-dev.lock
pip install -e . --no-deps

# Run the test suite
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check (mypy strict)
mypy src/mcp_phish

# Run the server locally in stub mode
python -m mcp_phish.server

# Or build the image yourself
cp docker-compose.example.yml docker-compose.yml
docker compose up --build

Aktualisieren von Abhängigkeiten

Die Dateien requirements.lock und requirements-dev.lock sind hash-fixiert. Bearbeiten Sie die entsprechende .in-Datei und generieren Sie sie dann neu:

uv pip compile requirements.in --output-file requirements.lock --generate-hashes --python-version 3.13
uv pip compile requirements-dev.in --output-file requirements-dev.lock --generate-hashes --python-version 3.13

Dependabot öffnet wöchentliche PRs für Updates auf requirements.in-Ebene, das Docker-Basis-Image und GitHub Actions-Versionen.

Roadmap

Dieser Server ist Phase 1 eines größeren Phish-Datenprojekts. Der oben dokumentierte Pydantic-Vertrag bleibt über die zukünftigen Phasen hinweg Byte-identisch.

• Phase 2 — Postgres-Vault + nächtliche ETL-Hydrierung.

• Phase 3 — Vault-gestützter Lesepfad für dieses MCP. Hot-Window-Fallthrough liest aktuelle Shows live; ältere Lesevorgänge kommen aus dem Vault.

• Phase 4 — Setlisten-Vorhersagespiel (separates Repo).

• Phase 5 — Chat + Dashboard-UI über MCP (separates Repo).

Der Phasenstatus befindet sich unter https://github.com/pete-builds/mcp-phish/issues.

Danksagungen

Danke an die Betreiber von phish.net und phish.in, dass sie das Korpus öffentlich und maschinenlesbar halten. Dieser Wrapper ist mit keinem der beiden Projekte verbunden. Bitte respektieren Sie deren Ratenbegrenzungen und Nutzungsbedingungen.

Lizenz

MIT.

Mitwirken

Issues und Pull Requests sind willkommen. Bevor Sie einen PR öffnen:

1. Stellen Sie sicher, dass ruff check, ruff format --check und mypy src/mcp_phish sauber sind.

2. Fügen Sie Tests hinzu oder aktualisieren Sie diese; halten Sie die Abdeckung bei 80% oder höher.

3. Führen Sie pytest lokal aus und bestätigen Sie, dass die Suite besteht.

4. Aktualisieren Sie CHANGELOG.md unter einer [Unreleased]-Überschrift.