setlist-mcp 0.4.0 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for setlist.fm — concert setlists, artists, venues, and tours via the setlist.fm API",
-    "version": "0.4.0"
+    "version": "0.5.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "setlist.fm",
       "source": "./",
       "description": "MCP server for setlist.fm — search concert setlists, artists, venues, and tours via natural language",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "setlist-mcp",
   "displayName": "setlist.fm",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server for setlist.fm — search concert setlists, artists, venues, and tours via the setlist.fm API",
   "author": {
     "name": "Chris Hall",

package/SKILL.md

@@ -116,6 +116,9 @@ setlist.fm's [API terms](https://www.setlist.fm/help/api-terms) bind anyone usin
 
 ## Notes
 
+- **Stub setlists:** every setlist result carries `songCount` / `setCount` / `hasSongs`. A page can exist with no songs logged (`hasSongs: false`) — skip those without a second `get_setlist` call.
+- **Disambiguate by location:** `artistName` + `date` can return shows in multiple cities. Add `cityName`/`cityId` or `venueName`/`venueId` to pin the right one (e.g. TSO on a date plays both Charlotte and Orlando).
+- **All performers at a venue/festival on a day:** call `setlist_search_setlists` with `venueName` (or `venueId`) + `date` and **no** artist.
 - IDs chain: `search_*` tools return the `mbid` / `setlistId` / `venueId` / `geoId` you feed into the `get_*` tools.
 - **All dates are ISO `yyyy-MM-dd`** — both the `date`/`lastUpdated` inputs and every `eventDate` in the output. (The server translates to/from setlist.fm's native `dd-MM-yyyy` internally.)
 - Results are paginated; pass `p` (1-based) to page through large result sets.

package/dist/augment.js

@@ -0,0 +1,21 @@
+export function augmentSetlists(value) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            augmentSetlists(item);
+    }
+    else if (value !== null && typeof value === 'object') {
+        const obj = value;
+        const sets = obj.sets;
+        if (sets !== null && typeof sets === 'object') {
+            const raw = sets.set;
+            const list = Array.isArray(raw) ? raw : [];
+            const songCount = list.reduce((n, s) => n + (Array.isArray(s?.song) ? s.song.length : 0), 0);
+            obj.songCount = songCount;
+            obj.setCount = list.length;
+            obj.hasSongs = songCount > 0;
+        }
+        for (const key of Object.keys(obj))
+            augmentSetlists(obj[key]);
+    }
+    return value;
+}

package/dist/bundle.js

@@ -31258,11 +31258,33 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.5.0";
 
 // src/client.ts
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
+
+// src/augment.ts
+function augmentSetlists(value) {
+  if (Array.isArray(value)) {
+    for (const item of value) augmentSetlists(item);
+  } else if (value !== null && typeof value === "object") {
+    const obj = value;
+    const sets = obj.sets;
+    if (sets !== null && typeof sets === "object") {
+      const raw = sets.set;
+      const list = Array.isArray(raw) ? raw : [];
+      const songCount = list.reduce((n, s) => n + (Array.isArray(s?.song) ? s.song.length : 0), 0);
+      obj.songCount = songCount;
+      obj.setCount = list.length;
+      obj.hasSongs = songCount > 0;
+    }
+    for (const key of Object.keys(obj)) augmentSetlists(obj[key]);
+  }
+  return value;
+}
+
+// src/client.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, "..", ".env"), override: false });
 var BASE_URL = "https://api.setlist.fm/rest";
@@ -31311,7 +31333,7 @@ var SetlistClient = class {
       ...opts.query !== void 0 ? { query: opts.query } : {},
       ...opts.body !== void 0 ? { body: opts.body } : {}
     });
-    return deepMapStringField(data, "eventDate", dmyToIso);
+    return augmentSetlists(deepMapStringField(data, "eventDate", dmyToIso));
   }
 };
 var client = new SetlistClient();
@@ -31383,7 +31405,7 @@ function registerSetlistTools(server) {
   server.registerTool(
     "setlist_search_setlists",
     {
-      description: "Search setlist.fm for concert setlists. Filter by any combination of artist, venue, city, country, tour, date, or year. Returns setlists with their songs and event details. Provide at least one filter." + ATTRIBUTION_NOTE,
+      description: "Search setlist.fm for concert setlists. Filter by any combination of artist, venue, city, country, tour, date, or year (provide at least one). Combine filters to disambiguate \u2014 artistName + date can span multiple cities, so add cityName/cityId or venueName/venueId to pin the exact show. Omit the artist and pass venueName/venueId + date to list EVERY performer at a venue or festival that day. Every result includes songCount, setCount, and hasSongs, so you can skip empty 'stub' setlists (hasSongs: false) without a second fetch." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         artistName: external_exports.string().optional().describe("Artist name"),
@@ -31606,6 +31628,121 @@ function registerUserTools(server) {
   );
 }
 
+// src/tools/resolve.ts
+var MAX_BATCH = 24;
+function songCountOf(s) {
+  const sets = Array.isArray(s.sets?.set) ? s.sets.set : [];
+  return sets.reduce((n, set2) => n + (Array.isArray(set2?.song) ? set2.song.length : 0), 0);
+}
+function normalizeArtist(name) {
+  return name.replace(/["'’‘”“]/g, "").replace(/\s*[+&]\s*/g, " and ").replace(/\./g, "").replace(/\s+/g, " ").trim();
+}
+async function emptyOn404(run, fallback) {
+  try {
+    return await run();
+  } catch (err) {
+    if (/\b404\b/.test(messageOf(err))) return fallback;
+    throw err;
+  }
+}
+async function searchSetlists(query) {
+  return emptyOn404(async () => {
+    const data = await client.request("GET", "/1.0/search/setlists", {
+      query
+    });
+    return data?.setlist ?? [];
+  }, []);
+}
+async function topArtistMbid(artistName) {
+  return emptyOn404(async () => {
+    const data = await client.request("GET", "/1.0/search/artists", {
+      query: { artistName, sort: "relevance" }
+    });
+    return data?.artist?.[0]?.mbid;
+  }, void 0);
+}
+function score(s, city, venue) {
+  let sc = 0;
+  const vn = s.venue?.name?.toLowerCase() ?? "";
+  const cn = s.venue?.city?.name?.toLowerCase() ?? "";
+  if (venue && vn.includes(venue.toLowerCase())) sc += 4;
+  if (city && cn.includes(city.toLowerCase())) sc += 2;
+  if (songCountOf(s) > 0) sc += 1;
+  return sc;
+}
+function pickBest(list, city, venue) {
+  if (list.length === 0) return void 0;
+  return [...list].sort((a, b) => score(b, city, venue) - score(a, city, venue) || songCountOf(b) - songCountOf(a))[0];
+}
+async function resolveOne(c) {
+  const filters = {
+    date: isoToDmy(c.date),
+    ...c.city ? { cityName: c.city } : {},
+    ...c.venue ? { venueName: c.venue } : {}
+  };
+  let list = await searchSetlists({ artistName: c.artist, ...filters });
+  if (list.length === 0) {
+    const mbid = await topArtistMbid(c.artist);
+    if (mbid) list = await searchSetlists({ artistMbid: mbid, ...filters });
+  }
+  if (list.length === 0) {
+    const norm = normalizeArtist(c.artist);
+    if (norm && norm.toLowerCase() !== c.artist.toLowerCase()) {
+      list = await searchSetlists({ artistName: norm, ...filters });
+    }
+  }
+  const best = pickBest(list, c.city, c.venue);
+  if (!best) return { input: c, match: null, alternatives: 0 };
+  const songCount = songCountOf(best);
+  return {
+    input: c,
+    match: {
+      setlistId: best.id,
+      url: best.url,
+      eventDate: best.eventDate,
+      // already ISO (normalized by client.request)
+      artist: best.artist?.name,
+      venue: best.venue?.name,
+      city: best.venue?.city?.name,
+      tour: best.tour?.name,
+      songCount,
+      hasSongs: songCount > 0
+    },
+    alternatives: list.length - 1
+  };
+}
+function registerResolveTools(server) {
+  server.registerTool(
+    "setlist_resolve_concerts",
+    {
+      description: "Resolve many concerts to their setlists in ONE call (instead of 2+ per show). Given up to 24 `{artist, date, city?, venue?}`, returns the best-match setlist for each \u2014 `{setlistId, url, eventDate, artist, venue, city, tour, songCount, hasSongs}` \u2014 plus a `{matched, stubs, unmatched}` summary. For each: searches artist + date (narrowed by your city/venue), and on a miss falls back to a relevance artist lookup (by mbid) and a punctuation-normalized name so format variants still resolve. `hasSongs: false` flags an empty stub page. Processed sequentially to respect setlist.fm's rate limit; chunk lists longer than 24 across calls." + ATTRIBUTION_NOTE,
+      annotations: { readOnlyHint: true },
+      inputSchema: {
+        concerts: external_exports.array(
+          external_exports.object({
+            artist: external_exports.string().describe("Artist name"),
+            date: external_exports.string().describe("Event date, ISO yyyy-MM-dd (e.g. 2025-08-28)"),
+            city: external_exports.string().optional().describe("City to disambiguate multi-city dates (optional)"),
+            venue: external_exports.string().optional().describe("Venue to disambiguate (optional)")
+          })
+        ).min(1).max(MAX_BATCH).describe(`Concerts to resolve (1\u2013${MAX_BATCH} per call)`)
+      }
+    },
+    async ({ concerts }) => {
+      const results = [];
+      for (const c of concerts) {
+        results.push(await resolveOne(c));
+      }
+      const matched = results.filter((r) => r.match).length;
+      const stubs = results.filter((r) => r.match && !r.match.hasSongs).length;
+      return textResult({
+        results,
+        summary: { total: results.length, matched, stubs, unmatched: results.length - matched }
+      });
+    }
+  );
+}
+
 // src/tools/utilities.ts
 function registerUtilityTools(server) {
   server.registerTool(
@@ -31657,6 +31794,7 @@ await runMcp({
     registerVenueTools,
     registerGeoTools,
     registerUserTools,
+    registerResolveTools,
     registerUtilityTools
   ]
 });

package/dist/client.js

@@ -1,6 +1,7 @@
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { loadDotenvSafely, readEnvVar, createApiClient, deepMapStringField, dmyToIso, } from '@chrischall/mcp-utils';
+import { augmentSetlists } from './augment.js';
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. the
 // mcpb bundle). `loadDotenvSafely` swallows a missing dotenv module and never
 // lets .env override a host-provided value.
@@ -61,8 +62,9 @@ export class SetlistClient {
             ...(opts.query !== undefined ? { query: opts.query } : {}),
             ...(opts.body !== undefined ? { body: opts.body } : {}),
         });
-        // Surface every date as ISO yyyy-MM-dd (the API returns eventDate as dd-MM-yyyy).
-        return deepMapStringField(data, 'eventDate', dmyToIso);
+        // Surface every date as ISO yyyy-MM-dd (the API returns eventDate as dd-MM-yyyy),
+        // and annotate setlists with songCount/setCount/hasSongs so stubs are visible.
+        return augmentSetlists(deepMapStringField(data, 'eventDate', dmyToIso));
     }
 }
 /**

package/dist/index.js

@@ -6,6 +6,7 @@ import { registerSetlistTools } from './tools/setlists.js';
 import { registerVenueTools } from './tools/venues.js';
 import { registerGeoTools } from './tools/geo.js';
 import { registerUserTools } from './tools/users.js';
+import { registerResolveTools } from './tools/resolve.js';
 import { registerUtilityTools } from './tools/utilities.js';
 // The setlist.fm client is a module-level singleton (imported by each tool
 // module) that defers its config error to the first request. That preserves the
@@ -22,6 +23,7 @@ await runMcp({
         registerVenueTools,
         registerGeoTools,
         registerUserTools,
+        registerResolveTools,
         registerUtilityTools,
     ],
 });

package/dist/tools/resolve.js

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+import { textResult, isoToDmy, messageOf } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+import { ATTRIBUTION_NOTE } from '../attribution.js';
+const MAX_BATCH = 24;
+function songCountOf(s) {
+    const sets = Array.isArray(s.sets?.set) ? s.sets.set : [];
+    return sets.reduce((n, set) => n + (Array.isArray(set?.song) ? set.song.length : 0), 0);
+}
+// Loosen punctuation/format variants for a fuzzy retry: drop quotes, turn + / &
+// into "and", drop stray periods, collapse whitespace. (Dan + Shay, "Weird Al"
+// Yankovic, DJ Pee .Wee.)
+function normalizeArtist(name) {
+    return name
+        .replace(/["'’‘”“]/g, '')
+        .replace(/\s*[+&]\s*/g, ' and ')
+        .replace(/\./g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// A no-match search returns HTTP 404 from setlist.fm — treat that as "empty",
+// not an error; let anything else propagate.
+async function emptyOn404(run, fallback) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        if (/\b404\b/.test(messageOf(err)))
+            return fallback;
+        throw err;
+    }
+}
+async function searchSetlists(query) {
+    return emptyOn404(async () => {
+        const data = await client.request('GET', '/1.0/search/setlists', {
+            query,
+        });
+        return data?.setlist ?? [];
+    }, []);
+}
+async function topArtistMbid(artistName) {
+    return emptyOn404(async () => {
+        const data = await client.request('GET', '/1.0/search/artists', {
+            query: { artistName, sort: 'relevance' },
+        });
+        return data?.artist?.[0]?.mbid;
+    }, undefined);
+}
+function score(s, city, venue) {
+    let sc = 0;
+    const vn = s.venue?.name?.toLowerCase() ?? '';
+    const cn = s.venue?.city?.name?.toLowerCase() ?? '';
+    if (venue && vn.includes(venue.toLowerCase()))
+        sc += 4;
+    if (city && cn.includes(city.toLowerCase()))
+        sc += 2;
+    if (songCountOf(s) > 0)
+        sc += 1;
+    return sc;
+}
+function pickBest(list, city, venue) {
+    if (list.length === 0)
+        return undefined;
+    // Best location/song score wins; prefer a populated setlist on ties via songCount.
+    return [...list].sort((a, b) => score(b, city, venue) - score(a, city, venue) || songCountOf(b) - songCountOf(a))[0];
+}
+async function resolveOne(c) {
+    const filters = {
+        date: isoToDmy(c.date),
+        ...(c.city ? { cityName: c.city } : {}),
+        ...(c.venue ? { venueName: c.venue } : {}),
+    };
+    let list = await searchSetlists({ artistName: c.artist, ...filters });
+    // Fuzzy fallback 1: resolve the artist via the (more forgiving) relevance
+    // search, then query by its mbid.
+    if (list.length === 0) {
+        const mbid = await topArtistMbid(c.artist);
+        if (mbid)
+            list = await searchSetlists({ artistMbid: mbid, ...filters });
+    }
+    // Fuzzy fallback 2: a punctuation-normalized name.
+    if (list.length === 0) {
+        const norm = normalizeArtist(c.artist);
+        if (norm && norm.toLowerCase() !== c.artist.toLowerCase()) {
+            list = await searchSetlists({ artistName: norm, ...filters });
+        }
+    }
+    const best = pickBest(list, c.city, c.venue);
+    if (!best)
+        return { input: c, match: null, alternatives: 0 };
+    const songCount = songCountOf(best);
+    return {
+        input: c,
+        match: {
+            setlistId: best.id,
+            url: best.url,
+            eventDate: best.eventDate, // already ISO (normalized by client.request)
+            artist: best.artist?.name,
+            venue: best.venue?.name,
+            city: best.venue?.city?.name,
+            tour: best.tour?.name,
+            songCount,
+            hasSongs: songCount > 0,
+        },
+        alternatives: list.length - 1,
+    };
+}
+export function registerResolveTools(server) {
+    server.registerTool('setlist_resolve_concerts', {
+        description: "Resolve many concerts to their setlists in ONE call (instead of 2+ per show). Given up to 24 `{artist, date, city?, venue?}`, returns the best-match setlist for each — `{setlistId, url, eventDate, artist, venue, city, tour, songCount, hasSongs}` — plus a `{matched, stubs, unmatched}` summary. For each: searches artist + date (narrowed by your city/venue), and on a miss falls back to a relevance artist lookup (by mbid) and a punctuation-normalized name so format variants still resolve. `hasSongs: false` flags an empty stub page. Processed sequentially to respect setlist.fm's rate limit; chunk lists longer than 24 across calls." +
+            ATTRIBUTION_NOTE,
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            concerts: z
+                .array(z.object({
+                artist: z.string().describe('Artist name'),
+                date: z.string().describe('Event date, ISO yyyy-MM-dd (e.g. 2025-08-28)'),
+                city: z.string().optional().describe('City to disambiguate multi-city dates (optional)'),
+                venue: z.string().optional().describe('Venue to disambiguate (optional)'),
+            }))
+                .min(1)
+                .max(MAX_BATCH)
+                .describe(`Concerts to resolve (1–${MAX_BATCH} per call)`),
+        },
+    }, async ({ concerts }) => {
+        const results = [];
+        // Sequential on purpose: one request at a time keeps us within setlist.fm's
+        // ~2 req/sec limit (the client also retries once on a 429).
+        for (const c of concerts) {
+            results.push((await resolveOne(c)));
+        }
+        const matched = results.filter((r) => r.match).length;
+        const stubs = results.filter((r) => r.match && !r.match.hasSongs).length;
+        return textResult({
+            results,
+            summary: { total: results.length, matched, stubs, unmatched: results.length - matched },
+        });
+    });
+}

package/dist/tools/setlists.js

@@ -13,7 +13,7 @@ const page = z
     .describe('Result page number (defaults to 1)');
 export function registerSetlistTools(server) {
     server.registerTool('setlist_search_setlists', {
-        description: "Search setlist.fm for concert setlists. Filter by any combination of artist, venue, city, country, tour, date, or year. Returns setlists with their songs and event details. Provide at least one filter." +
+        description: "Search setlist.fm for concert setlists. Filter by any combination of artist, venue, city, country, tour, date, or year (provide at least one). Combine filters to disambiguate — artistName + date can span multiple cities, so add cityName/cityId or venueName/venueId to pin the exact show. Omit the artist and pass venueName/venueId + date to list EVERY performer at a venue or festival that day. Every result includes songCount, setCount, and hasSongs, so you can skip empty 'stub' setlists (hasSongs: false) without a second fetch." +
             ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {

package/dist/version.js

@@ -3,4 +3,4 @@
 // release-please-config.json's `extra-files`), and `versionSyncTest` guards
 // that it stays equal to package.json. Import VERSION wherever the version is
 // needed rather than re-declaring it.
-export const VERSION = '0.4.0'; // x-release-please-version
+export const VERSION = '0.5.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "setlist-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "mcpName": "io.github.chrischall/setlist-mcp",
   "description": "setlist.fm MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/setlist-mcp",
     "source": "github"
   },
-  "version": "0.4.0",
+  "version": "0.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "setlist-mcp",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "transport": {
         "type": "stdio"
       },