mcp-phish

Un servidor MCP que envuelve las APIs de api.phish.net v5 y phish.in v2 detrás de una interfaz de herramientas tipadas. Doce herramientas que abarcan setlists, canciones, jam-charts, reseñas y audio. Cada respuesta se estructura a través de modelos Pydantic inmutables para que el formato de transmisión se mantenga estable frente a cambios en la API original.

Construido sobre FastMCP con transporte HTTP Streamable. Diseñado para ejecutarse en una red local de confianza o detrás de una ACL de Tailscale; no incluye autenticación a nivel de MCP.

Por qué

Hoy en día, el ecosistema de Phish.net + phish.in es un pequeño conjunto de envoltorios sin mantenimiento y scripts aislados. Nadie combina ambos de forma limpia. mcp-phish ofrece a cualquier cliente compatible con MCP (Claude Code, Claude Desktop, agentes personalizados) una superficie de consulta enfocada y bien tipada para las preguntas que los fans realmente hacen: setlist de una fecha, debut y brecha de una canción, URL de audio para una pista, éxitos de jam-chart para una gira.

La fuente puede cambiar (API en vivo → caché → almacén). Las estructuras de Pydantic devueltas a los clientes MCP nunca lo hacen.

Inicio rápido

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

El servidor se inicia en modo stub por defecto. Devuelve datos simulados realistas y no requiere acceso a la red ni clave de API. Regístralo en Claude Code:

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

Luego pregúntale a Claude: "¿Cuál fue el setlist del 30/12/95?" y deberías obtener el Madison Square Garden con el groove de Mike's > Simple > Weekapaug.

Para comunicarte con las APIs reales, registra una clave gratuita en api.phish.net/keys/ y desactiva el modo stub:

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

Referencia de herramientas

Cada herramienta devuelve una cadena JSON con el sobre estándar:

{"data": <typed payload>}

o, en caso de error:

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

Los modelos Pydantic en src/mcp_phish/models.py (ShowSummary, Show, SetlistEntry, Song, Performance, NotableJam, Review, Track, ShowAudio, Health) son el contrato público. Están congelados con extra="forbid" para que cualquier cambio en la API original se convierta en un error de validación en lugar de un cambio silencioso en la estructura.

Modo Stub vs modo real

Cambiar de modo es un cambio de configuración, no de código. Las mismas doce herramientas, las mismas estructuras de respuesta.

Caché

mcp-phish mantiene una caché opaca de clave-valor en disco (/data/phish-cache.db, aiosqlite) indexada por (endpoint, params_hash). Un único TTL rige cada entrada (CACHE_TTL_SECONDS, por defecto 86400 = 24h). En caso de acierto, no se realiza ninguna llamada externa.

Esta caché no es un almacén de datos normalizado. Solo contiene respuestas JSON sin procesar para mantenernos bajo los límites de tasa de la API y hacer que la exploración repetida impulsada por LLM sea rápida. Trátala como efímera.

Limitación de tasa (Throttling)

Cada llamada externa pasa a través de un cubo de tokens por instancia con una tasa de estado estable configurable:

El cubo está en proceso. Múltiples contenedores no se coordinan. El estado del token se expone en health() para que una sesión de Claude Code pueda ver lo que queda.

Configuración

Toda la configuración se lee de variables de entorno (y un archivo .env cuando está presente). Pydantic valida al inicio y falla rápidamente ante valores no válidos.

Un ejemplo completo se encuentra en .env.example.

Configuración del cliente MCP

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"
    }
  }
}

Configuración genérica

HTTP Streamable en http://<host>:3705/mcp. Cualquier cliente MCP que admita el transporte HTTP Streamable puede conectarse.

Arquitectura

+---------------------+     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 es un proxy asíncrono ligero con una pequeña caché: traduce llamadas de herramientas MCP en llamadas REST externas, almacena en caché las respuestas crudas durante el TTL configurado y las proyecta en la estructura Pydantic pública. No almacena ningún estado más allá de esa caché. No llama a ningún servicio en la nube que no sean las dos APIs de Phish.

Notas de seguridad

• Ejecuta mcp-phish en una red local de confianza, en Tailscale o detrás de un proxy inverso con autenticación. El servidor en sí no autentica a los clientes MCP.

• Las claves de API viven solo en el entorno del contenedor. Nunca se registran, nunca se repiten en las respuestas y nunca se escriben en el disco.

• El contenedor se ejecuta como UID 1000, sin shell, sin directorio de usuario, con un sistema de archivos raíz de solo lectura (/tmp es tmpfs) y no-new-privileges.

• El volumen de caché /data es la única ruta grabable.

• Las dependencias de Python se instalan con pip --require-hashes desde un requirements.lock bloqueado por hash. La imagen base se fijará por resumen antes del primer lanzamiento etiquetado.

• Las imágenes publicadas son multi-arquitectura (amd64/arm64) con procedencia de compilación y SBOM a través de docker/build-push-action.

Para informes de vulnerabilidades, consulta SECURITY.md.

Desarrollo

Requiere Python 3.13+ y 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

Actualización de dependencias

Los archivos requirements.lock y requirements-dev.lock están fijados por hash. Edita el archivo .in correspondiente y luego regenera:

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 abre PRs semanales para actualizaciones de nivel requirements.in, la imagen base de Docker y las versiones de GitHub Actions.

Hoja de ruta

Este servidor es la Fase 1 de un proyecto de datos de Phish más grande. El contrato de Pydantic documentado anteriormente se mantendrá idéntico a nivel de byte en las fases futuras.

• Fase 2 — Almacén Postgres + hidratación ETL nocturna.

• Fase 3 — Ruta de lectura respaldada por almacén para este MCP. Las lecturas de ventana activa leen conciertos recientes en vivo; las lecturas más antiguas provienen del almacén.

• Fase 4 — Juego de predicción de setlist (repositorio separado).

• Fase 5 — Chat + interfaz de panel sobre MCP (repositorio separado).

El estado de la fase se encuentra en https://github.com/pete-builds/mcp-phish/issues.

Agradecimientos

Gracias a los operadores de phish.net y phish.in por mantener el corpus público y accesible por máquina. Este envoltorio no está afiliado a ninguno de los proyectos. Por favor, respeta sus límites de tasa y términos de servicio.

Licencia

MIT.

Contribución

Las propuestas y solicitudes de extracción (pull requests) son bienvenidas. Antes de abrir una PR:

1. Asegúrate de que ruff check, ruff format --check y mypy src/mcp_phish estén limpios.

2. Agrega o actualiza pruebas; mantén la cobertura en un 80% o más.

3. Ejecuta pytest localmente y confirma que la suite pasa.

4. Actualiza CHANGELOG.md bajo un encabezado [Unreleased].