mcp-umphreys

A FastMCP (Streamable HTTP) MCP server for Umphrey's McGee setlist data. It reads from the umphreys-vault Postgres database (the source of truth) with a live All Things Umphreys (ATU) v2 API fallthrough for in-progress shows on show night.

No audio, no reviews: Umphrey's has no upstream analog for either.

Templated from mcp-phish; the public tool output shapes are byte-for-byte compatible with that contract so the downstream setlist game (open-setlist-stash) parses them unchanged.

Tools

Game-critical (shapes match the mcp-phish contract):

Umphrey's-native (no game dependency):

Every tool returns {"data": <model>} (or the standard {"error", "code"} failure shape) as a JSON string in the FastMCP content[0].text.

Related MCP server: setlist-mcp

The hot window

get_show / recent_shows for a show within VAULT_HOT_WINDOW_HOURS (default 24) of now read live from ATU instead of the vault, with a short cache TTL (HOT_WINDOW_CACHE_TTL_SECONDS, default 90s). This is required so the game's resolver sees an in-progress setlist grow on show night instead of a frozen vault snapshot. The set-label normalization (e → Encore, One Set → Set 1) is applied identically on the live and vault paths so encore detection works in both.

Running

cp .env.example .env   # set PG_PASSWORD; STUB_MODE=true skips the live network
pip install -e ".[dev]"
python -m mcp_umphreys.server   # Streamable HTTP on :3717

Tests run with no network and no Postgres (stub ATU client + a fake vault reader):

ruff check . && mypy && pytest

Deployment

The image is published to GHCR by CI, not built on the host. docker compose up -d pulls the pinned version and joins the external umphreys-vault_default network so the server reaches the vault's postgres container by name. The opaque response cache persists in the mcp-umphreys-cache volume. Port 3717.

To cut a release:

1. Bump the image tag in docker-compose.yml and commit it. The release workflow refuses to publish if this disagrees with the git tag, which stops a release from producing an image the compose does not reference.

2. Tag and push:

   git tag -a v0.1.0 -m "v0.1.0"
   git push origin v0.1.0

3. .github/workflows/release.yml builds linux/amd64 and linux/arm64, pushes to ghcr.io/pete-builds/mcp-umphreys, attaches an SBOM and a signed provenance attestation, and cuts a GitHub release.

4. On the host:

   docker compose pull && docker compose up -d

The first deploy after switching from build: . to a pulled image is the one worth watching, since the host stops compiling the code it runs.