# good_wook 🐟

A free, non-commercial **conversational Phish MCP** — a natural-language front end to
the band **Phish**'s show history, usable from Claude / claude.ai.

It is a **live proxy over the [Phish.net](https://phish.net) API v5**. It does **not**
scrape, store, or redistribute setlist data — every answer is fetched live and credited
to Phish.net. Short-lived caching is used only to reduce load. **Data: Phish.net.**

good_wook is an independent fan tool, not affiliated with Phish.net or Phish.

## Use it

The server is live at **`https://good-wook.mino-yakking.com/mcp`** (Streamable HTTP).

Add it as a custom connector in claude.ai (**Settings → Connectors → Add custom
connector**), paste the URL above, then just ask:

- "What's the latest Phish show?"
- "What did Phish play on this day in history?"
- "How many times have they played Tweezer, and what's the current gap?"
- "Give me a random Phish show."

> Custom connectors require a paid Claude plan.

good_wook uses the Phish.net API under its published API terms: every answer is fetched
live per user request, nothing is stored or redistributed, and every response carries
Phish.net attribution.

## How it works

Phish.net runs on the **Songfish** platform. The live client + formatter are a small
core, with Phish.net specifics isolated to config — base URL, API key, and
`constants.FIELD_MAP` for Phish.net's field names.

A Cloudflare Worker (`McpAgent` + Durable Object) serves the MCP over Streamable HTTP,
edge-caches upstream responses, and rate-limits per client. A Python stdio server
(`src/good_wook/`) mirrors the same tools for local use.

**API key** — Phish.net v5 requires one (request at [phish.net/api](https://phish.net/api)).
It is read from `PHISHNET_API_KEY` locally and from a Cloudflare secret in the Worker;
it is never committed. Offline tests pass without a key.

## Tools (11)
`ping`, `get_setlist`, `latest_show`, `this_day_in_history`, `search_shows`,
`random_show`, `song_stats` (incl. current gap), `song_history`,
`jam_chart`, `venue_info`, `upcoming_shows`.

A corpus-wide **biggest-gaps leaderboard is intentionally omitted** — it needs stored
aggregates, which the no-storage design (and Phish.net's terms) disallow. Per-song
current gap lives in `song_stats`. A **top-rated-shows** tool is likewise omitted:
Phish.net v5 exposes no sortable show rating.

## Develop
```bash
uv sync
uv run pytest            # offline tests (format + client + normalization)
PHISHNET_API_KEY=... uv run python scripts/spike.py   # once you have a key
PHISHNET_API_KEY=... uv run good_wook                 # stdio MCP for Claude Code
```

## Attribution & license

Independent fan project, run non-commercially. Not affiliated with Phish.net or Phish.
Setlist data © Phish.net — the data is theirs, served live under attribution and not
covered by this repo's license.

The good_wook source is MIT licensed ([LICENSE](LICENSE)).