mcp-phish

api.phish.net v5 및 phish.in v2 API를 단일 유형화된 도구 인터페이스로 래핑하는 MCP 서버입니다. 세트리스트, 노래, 잼 차트, 리뷰 및 오디오 전반에 걸쳐 12개의 도구를 제공합니다. 모든 응답은 고정된 Pydantic 모델을 통해 구성되므로 업스트림 API 변경에도 와이어 형식이 안정적으로 유지됩니다.

FastMCP와 Streamable HTTP 전송을 기반으로 구축되었습니다. 신뢰할 수 있는 LAN 또는 Tailscale ACL 뒤에서 실행되도록 설계되었으며, MCP 수준의 인증은 내장되어 있지 않습니다.

목적

현재 Phish.net + phish.in 생태계는 유지 관리되지 않는 래퍼와 일회성 스크립트의 작은 집합으로 구성되어 있습니다. 이 둘을 깔끔하게 결합한 곳은 없습니다. mcp-phish는 모든 MCP 인식 클라이언트(Claude Code, Claude Desktop, 커스텀 에이전트)에 팬들이 실제로 궁금해하는 질문(특정 날짜의 세트리스트, 노래 데뷔 및 간격, 트랙의 오디오 URL, 투어의 잼 차트 히트곡 등)에 대해 집중적이고 잘 정의된 인터페이스를 제공합니다.

소스는 변경될 수 있지만(라이브 API → 캐시 → 볼트), MCP 클라이언트로 반환되는 Pydantic 형태는 절대 변하지 않습니다.

빠른 시작

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에게 *"12/30/95의 세트리스트가 뭐야?"*라고 물어보면 Mike's > Simple > Weekapaug 그루브가 포함된 Madison Square Garden 공연 정보를 받을 수 있습니다.

실제 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

도구 참조

모든 도구는 표준 봉투(envelope)가 포함된 JSON 문자열을 반환합니다:

{"data": <typed payload>}

실패 시:

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

src/mcp_phish/models.py에 있는 Pydantic 모델(ShowSummary, Show, SetlistEntry, Song, Performance, NotableJam, Review, Track, ShowAudio, Health)이 공개 계약입니다. 이 모델들은 extra="forbid"로 고정되어 있어 업스트림 변경 사항이 발생하면 조용한 형태 변경이 아닌 유효성 검사 오류가 발생합니다.

스텁 모드 vs 실제 모드

모드 전환은 코드 변경이 아닌 설정 변경입니다. 동일한 12개의 도구와 동일한 응답 형태를 사용합니다.

캐싱

mcp-phish는 디스크(/data/phish-cache.db, aiosqlite)에 (endpoint, params_hash)를 키로 하는 불투명한 키-값 캐시를 유지합니다. 모든 항목은 단일 TTL(CACHE_TTL_SECONDS, 기본값 86400 = 24시간)을 따릅니다. 캐시 적중 시 업스트림 호출은 발생하지 않습니다.

이 캐시는 정규화된 데이터 저장소가 아닙니다. 업스트림 속도 제한을 준수하고 LLM 기반 탐색을 빠르게 하기 위해 원시 JSON 응답만 저장합니다. 일시적인 데이터로 취급하십시오.

스로틀링

모든 업스트림 호출은 구성 가능한 정상 상태 속도를 가진 인스턴스별 토큰 버킷을 통과합니다:

버킷은 프로세스 내부에 있습니다. 여러 컨테이너가 조정되지 않습니다. 토큰 상태는 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"
    }
  }
}

일반 구성

http://<host>:3705/mcp에서 Streamable HTTP를 사용합니다. Streamable HTTP 전송을 지원하는 모든 MCP 클라이언트가 연결할 수 있습니다.

아키텍처

+---------------------+     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 호출로 변환하고, 원시 응답을 구성된 TTL 동안 캐시하며, 이를 공개 Pydantic 형태로 투영합니다. 캐시 외에는 어떠한 상태도 저장하지 않습니다. 두 개의 Phish API 외에는 어떠한 클라우드 서비스도 호출하지 않습니다.

보안 참고 사항

• mcp-phish를 신뢰할 수 있는 LAN, Tailscale 또는 인증이 있는 리버스 프록시 뒤에서 실행하십시오. 서버 자체는 MCP 클라이언트를 인증하지 않습니다.

• API 키는 컨테이너의 환경 변수에만 존재합니다. 로그에 기록되거나, 응답에 에코되거나, 디스크에 기록되지 않습니다.

• 컨테이너는 UID 1000으로 실행되며, 셸, 홈 디렉토리, 읽기 전용 루트 파일 시스템(/tmp는 tmpfs) 및 no-new-privileges가 적용됩니다.

• /data 캐시 볼륨만이 유일한 쓰기 가능 경로입니다.

• Python 의존성은 해시가 잠긴 requirements.lock에서 pip --require-hashes를 사용하여 설치됩니다. 기본 이미지는 첫 번째 태그된 릴리스 전에 다이제스트로 고정됩니다.

• 게시된 이미지는 docker/build-push-action을 통해 빌드 출처 및 SBOM이 포함된 멀티 아키텍처(amd64/arm64) 이미지입니다.

취약점 보고는 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은 requirements.in 수준의 업데이트, Docker 기본 이미지 및 GitHub Actions 버전에 대해 매주 PR을 엽니다.

로드맵

이 서버는 더 큰 Phish 데이터 프로젝트의 1단계입니다. 위에 문서화된 Pydantic 계약은 향후 단계에서도 바이트 단위로 동일하게 유지됩니다.

• 2단계 — Postgres 볼트 + 야간 ETL 하이드레이션.

• 3단계 — 이 MCP를 위한 볼트 기반 읽기 경로. 핫 윈도우 폴스루(Hot-window fallthrough)는 최근 공연을 실시간으로 읽고, 이전 공연은 볼트에서 읽습니다.

• 4단계 — 세트리스트 예측 게임(별도 저장소).

• 5단계 — MCP 기반 채팅 + 대시보드 UI(별도 저장소).

단계별 상태는 https://github.com/pete-builds/mcp-phish/issues에서 확인할 수 있습니다.

감사의 말

코퍼스를 공개하고 기계가 액세스할 수 있도록 유지해 준 phish.net 및 phish.in 운영자에게 감사드립니다. 이 래퍼는 두 프로젝트와 제휴하지 않았습니다. 그들의 속도 제한과 서비스 약관을 존중해 주십시오.

라이선스

MIT.

기여

이슈 및 풀 리퀘스트를 환영합니다. PR을 열기 전에:

1. ruff check, ruff format --check, mypy src/mcp_phish가 깨끗한지 확인하십시오.

2. 테스트를 추가하거나 업데이트하고, 커버리지를 80% 이상으로 유지하십시오.

3. 로컬에서 pytest를 실행하여 제품군이 통과하는지 확인하십시오.

4. CHANGELOG.md의 [Unreleased] 헤딩 아래에 업데이트하십시오.