mcp-phish

MCP-сервер, который оборачивает API api.phish.net v5 и phish.in v2 в единый типизированный интерфейс инструментов. Двенадцать инструментов для работы с сет-листами, песнями, джем-чартами, рецензиями и аудио. Каждый ответ формируется через замороженные модели Pydantic, поэтому формат данных остается стабильным даже при изменениях в исходных API.

Построен на базе FastMCP с использованием транспорта Streamable HTTP. Предназначен для запуска в доверенной локальной сети или за Tailscale ACL — встроенная аутентификация на уровне MCP отсутствует.

Зачем это нужно

Сегодня экосистема Phish.net + phish.in представляет собой набор неподдерживаемых оберток и одноразовых скриптов. Никто не объединяет их чисто. mcp-phish предоставляет любому MCP-совместимому клиенту (Claude Code, Claude Desktop, пользовательские агенты) сфокусированную, хорошо типизированную область для вопросов, которые действительно задают фанаты: сет-лист на конкретную дату, дебют песни и перерыв между исполнениями, URL аудио для трека, хиты джем-чартов для тура.

Источник может меняться (живой API → кэш → хранилище). Структуры Pydantic, возвращаемые MCP-клиентам, — никогда.

Быстрый старт

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

Сервер по умолчанию запускается в режиме заглушки (stub mode). Он возвращает реалистичные фиктивные данные и не требует доступа к сети или API-ключа. Зарегистрируйте его в Claude Code:

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

Затем спросите Claude: "Какой был сет-лист 30.12.95?", и вы должны получить ответ с концертом в Madison Square Garden с грувом Mike's > Simple > Weekapaug.

Чтобы работать с реальными API, зарегистрируйте бесплатный ключ на api.phish.net/keys/ и отключите режим заглушки:

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

Справочник инструментов

Каждый инструмент возвращает JSON-строку со стандартным конвертом:

{"data": <typed payload>}

или, в случае ошибки:

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

Модели Pydantic в src/mcp_phish/models.py (ShowSummary, Show, SetlistEntry, Song, Performance, NotableJam, Review, Track, ShowAudio, Health) являются публичным контрактом. Они заморожены с помощью extra="forbid", поэтому любое изменение в исходном API приведет к ошибке валидации, а не к скрытому изменению структуры данных.

Режим заглушки против реального режима

Переключение режимов — это изменение конфигурации, а не кода. Те же двенадцать инструментов, те же структуры ответов.

Кэширование

mcp-phish хранит непрозрачный кэш "ключ-значение" на диске (/data/phish-cache.db, aiosqlite), индексируемый по (endpoint, params_hash). Единый TTL управляет каждой записью (CACHE_TTL_SECONDS, по умолчанию 86400 = 24 часа). При попадании в кэш вызов внешнего API не выполняется.

Этот кэш не является нормализованным хранилищем данных. Он просто хранит необработанные JSON-ответы, чтобы оставаться в рамках лимитов внешних API и ускорить повторные исследования с помощью LLM. Относитесь к нему как к эфемерному.

Троттлинг

Каждый внешний вызов проходит через токен-бакет (token bucket) для каждого экземпляра с настраиваемой скоростью:

Бакет находится внутри процесса. Несколько контейнеров не координируются между собой. Состояние токенов отображается в health(), чтобы сессия Claude Code могла видеть остаток лимита.

Конфигурация

Вся конфигурация считывается из переменных окружения (и файла .env, если он присутствует). Pydantic проверяет их при запуске и немедленно завершает работу при обнаружении неверных значений.

Полный пример находится в .env.example.

Настройка 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"
    }
  }
}

Общая конфигурация

Streamable HTTP по адресу http://<host>:3705/mcp. Может подключиться любой MCP-клиент, поддерживающий транспорт Streamable HTTP.

Архитектура

+---------------------+     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 — это тонкий асинхронный прокси с небольшим кэшем: он преобразует вызовы инструментов MCP в REST-вызовы к внешним API, кэширует необработанные ответы на настроенный TTL и проецирует их в публичную структуру Pydantic. Он не хранит никакого состояния, кроме этого кэша. Он не вызывает никаких облачных сервисов, кроме двух API Phish.

Заметки по безопасности

• Запускайте mcp-phish в доверенной локальной сети, через Tailscale или за обратным прокси с аутентификацией. Сам сервер не аутентифицирует MCP-клиентов.

• API-ключи живут только в окружении контейнера. Они никогда не логируются, не отображаются в ответах и не записываются на диск.

• Контейнер работает под UID 1000, без оболочки (shell), без домашней директории, с файловой системой root только для чтения (/tmp — это tmpfs) и no-new-privileges.

• Том кэша /data — единственный путь с правами записи.

• Python-зависимости устанавливаются с помощью pip --require-hashes из файла requirements.lock с хеш-проверкой. Базовый образ будет закреплен по дайджесту перед первым тегированным релизом.

• Опубликованные образы являются мультиархитектурными (amd64/arm64) с подтверждением сборки и SBOM через docker/build-push-action.

Отчеты об уязвимостях см. в SECURITY.md.

Разработка

Требуются Python 3.13+ и 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

Обновление зависимостей

Файлы requirements.lock и requirements-dev.lock закреплены по хешу. Отредактируйте соответствующий файл .in, затем перегенерируйте:

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 еженедельно открывает PR для обновлений уровня requirements.in, базового образа Docker и версий GitHub Actions.

Дорожная карта

Этот сервер — Фаза 1 более крупного проекта данных Phish. Контракт Pydantic, описанный выше, останется байт-идентичным в будущих фазах.

• Фаза 2 — хранилище Postgres + ночная гидратация ETL.

• Фаза 3 — путь чтения из хранилища для этого MCP. "Горячее окно" считывает недавние концерты в реальном времени; старые данные поступают из хранилища.

• Фаза 4 — игра по предсказанию сет-листов (отдельный репозиторий).

• Фаза 5 — чат + UI дашборда поверх MCP (отдельный репозиторий).

Статус фаз находится по адресу https://github.com/pete-builds/mcp-phish/issues.

Благодарности

Спасибо операторам phish.net и phish.in за то, что они сохраняют корпус данных публичным и доступным для машин. Эта обертка не связана ни с одним из проектов. Пожалуйста, уважайте их лимиты запросов и условия обслуживания.

Лицензия

MIT.

Участие в разработке

Приветствуются issues и pull requests. Перед открытием PR:

1. Убедитесь, что ruff check, ruff format --check и mypy src/mcp_phish проходят без ошибок.

2. Добавьте или обновите тесты; поддерживайте покрытие на уровне 80% или выше.

3. Запустите pytest локально и подтвердите, что набор тестов проходит.

4. Обновите CHANGELOG.md под заголовком [Unreleased].