setlist-mcp: Instructions file for Claude Code

setlist-mcp

MCP server for setlist.fm. Wraps the setlist.fm REST API (https://api.setlist.fm/rest) and exposes 20 tools to Claude over stdio: 18 read-only (the REST API has no write endpoints — those are all GETs) plus 2 authenticated "I was there" attendance actions (setlist_mark_attended / setlist_unmark_attended) performed against the logged-in website (Apache Wicket), not the REST API.

Commands

npm run build          # tsc + esbuild bundle → dist/index.js + dist/bundle.js
npm test               # tsc typecheck + vitest run
npm run test:watch     # vitest watch
npm run test:coverage  # tsc typecheck + vitest run --coverage (v8 reporter, no thresholds)

Run locally (requires built dist/):

SETLIST_API_KEY=xxx node dist/index.js

Tool naming

All tools are prefixed setlist_ (e.g. setlist_search_setlists, setlist_get_artist).

Architecture

src/
  version.ts      # single source of truth for VERSION (x-release-please-version)
  index.ts        # MCP server entry — runMcp({ name, version, banner, tools })
  client.ts       # SetlistClient — reads SETLIST_API_KEY, attaches x-api-key
                  #   header per request, 15s request timeout + 2s 429 retry (both
                  #   via createApiClient), normalizes response eventDate → ISO
                  #   (deepMapStringField + dmyToIso from @chrischall/mcp-utils),
                  #   then augmentSetlists(...) annotates each setlist
  errors.ts       # SetlistConfigError — the deferred missing-key error, side-effect
                  #   free so tools/* can classify it without importing client.ts
  augment.ts      # augmentSetlists — walks a response, tags every setlist object
                  #   with songCount / setCount / hasSongs so callers skip empty stubs
  web-client.ts   # SetlistWebClient — authenticated www.setlist.fm (website) client
                  #   for the attendance writes; session-cookie auth, 5xx retry,
                  #   serialized write pacer (see attendance gotcha)
  fetchproxy-cookie.ts # resolveSessionCookie — shared createAuthResolver
                  #   (mcp-utils) three-path resolver: SETLIST_SESSION_COOKIE →
                  #   one-shot fetchproxy browser-bridge grab (15s withDeadline)
                  #   → actionable error (lazy; @fetchproxy/bootstrap)
  attribution.ts  # ATTRIBUTION_NOTE appended to data tool descriptions
  view.ts         # SETLIST_VIEWS / viewArg / viewResponse — the fleet `view`
                  #   vocabulary. compact = stripMediaUrls only (no field
                  #   projection; see the docblock), full = untouched. Every
                  #   read tool answers through viewResponse; writes do not
  tools/
    artists.ts    # setlist_search_artists, setlist_get_artist, setlist_get_artist_setlists
    setlists.ts   # setlist_search_setlists, setlist_get_setlist, setlist_get_setlist_version
    venues.ts     # setlist_search_venues, setlist_get_venue, setlist_get_venue_setlists
    geo.ts        # setlist_search_cities, setlist_get_city, setlist_search_countries
    users.ts      # setlist_get_user, setlist_get_user_attended, setlist_get_user_edited
    resolve.ts    # setlist_resolve_concerts (batch {artist,date,city?,venue?} → setlist resolver)
    attendance.ts # setlist_mark_attended, setlist_unmark_attended (authenticated website writes via web-client.ts)
    urls.ts       # setlist_id_from_url (pure local parser — extracts the setlist ID from a /setlist/ URL)
    utilities.ts  # setlist_healthcheck
    hints.ts      # _meta.mint context-group hints (domain family; lookup/change/other,
                  #   no canonical read, no subject) — every tool but the healthcheck