setlist-mcp 0.3.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.3.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.3.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.3.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

@@ -72,7 +72,7 @@ All tools are read-only and prefixed `setlist_`.
 - **`setlist_get_artist_setlists`** — an artist's setlists (most recent first), by `mbid`, paginated via `p`.
 
 ### Setlists
-- **`setlist_search_setlists`** — search by any mix of artist, venue, city, country, tour, `date` (dd-MM-yyyy), or `year`.
+- **`setlist_search_setlists`** — search by any mix of artist, venue, city, country, tour, `date` (ISO yyyy-MM-dd), or `year`.
 - **`setlist_get_setlist`** — a setlist (with full song list) by `setlistId`.
 - **`setlist_get_setlist_version`** — a specific historical version by `versionId`.
 
@@ -98,7 +98,7 @@ All tools are read-only and prefixed `setlist_`.
 
 - **"What did Radiohead play at their last show?"** → `setlist_search_artists` (Radiohead → mbid) → `setlist_get_artist_setlists` (latest) → `setlist_get_setlist` for the song list.
 - **"Setlists at Red Rocks in 2023"** → `setlist_search_venues` (Red Rocks → venueId) → `setlist_search_setlists` with `venueId` + `year: 2023`.
-- **"Phish on 2023-08-07"** → `setlist_search_setlists` with `artistName: "Phish"`, `date: "07-08-2023"` (note the dd-MM-yyyy format).
+- **"Phish on 2023-08-07"** → `setlist_search_setlists` with `artistName: "Phish"`, `date: "2023-08-07"`.
 
 ## Attribution & API terms
 
@@ -116,7 +116,10 @@ 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.
-- `date` filters use **dd-MM-yyyy** (e.g. `07-08-2023` = 7 August 2023).
+- **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.
 - setlist.fm rate-limits the standard tier (~2 req/sec); a 429 is retried once.

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

@@ -31001,6 +31001,22 @@ function textResult(data) {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
   };
 }
+function deepMapStringField(value, field, map2) {
+  if (Array.isArray(value)) {
+    for (const item of value)
+      deepMapStringField(item, field, map2);
+  } else if (value !== null && typeof value === "object") {
+    const obj = value;
+    for (const key of Object.keys(obj)) {
+      const v = obj[key];
+      if (key === field && typeof v === "string")
+        obj[key] = map2(v);
+      else
+        deepMapStringField(v, field, map2);
+    }
+  }
+  return value;
+}
 
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
 var DEFAULT_ERROR_MESSAGE_MAX = 500;
@@ -31071,6 +31087,15 @@ var RateLimitedError = class extends Error {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+var RequestTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(service, timeoutMs) {
+    super(`Request to ${service} timed out after ${timeoutMs}ms.`);
+    this.name = "RequestTimeoutError";
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
 function hostOf(baseUrl) {
   try {
     return new URL(baseUrl).host;
@@ -31086,6 +31111,18 @@ function createApiClient(opts) {
   const sleep = opts.sleep ?? defaultSleep;
   const unauthorized = () => opts.onUnauthorized ? opts.onUnauthorized() : new UnauthorizedError(service);
   const rateLimited = () => opts.onRateLimited ? opts.onRateLimited() : new RateLimitedError(service);
+  const timeoutMs = opts.timeout;
+  function withTimeout(run) {
+    if (timeoutMs == null || timeoutMs <= 0)
+      return run(void 0);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return run(controller.signal).catch((err) => {
+      if (err instanceof Error && err.name === "AbortError")
+        throw new RequestTimeoutError(service, timeoutMs);
+      throw err;
+    }).finally(() => clearTimeout(timer));
+  }
   async function send(method, path, opt) {
     const isMultipart = opt.formData !== void 0;
     const hasJsonBody = !isMultipart && opt.body !== void 0;
@@ -31093,7 +31130,7 @@ function createApiClient(opts) {
     const query = opt.query ? buildQueryString(opt.query) : "";
     const url2 = `${base}${path}${query}`;
     const bodyInit = reqBody !== void 0 ? { body: reqBody } : {};
-    const fetchWith = (token) => doFetch(url2, {
+    const fetchWith = (token, signal) => doFetch(url2, {
       method,
       headers: {
         Accept: "application/json",
@@ -31102,9 +31139,10 @@ function createApiClient(opts) {
         ...token ? { Authorization: `Bearer ${token}` } : {},
         ...opt.headers
       },
+      ...signal ? { signal } : {},
       ...bodyInit
     });
-    const once = opts.tokenManager ? () => opts.tokenManager.withAuth(fetchWith) : async () => fetchWith(await opts.getToken?.() || void 0);
+    const once = () => withTimeout((signal) => opts.tokenManager ? opts.tokenManager.withAuth((token) => fetchWith(token, signal)) : (async () => fetchWith(await opts.getToken?.() || void 0, signal))());
     let attempt = 0;
     for (; ; ) {
       const res = await once();
@@ -31171,6 +31209,29 @@ function formatApiError(status, method, path, errorText, opts = {}) {
   return safe.length > 0 ? `${head}: ${safe}` : head;
 }
 
+// node_modules/@chrischall/mcp-utils/dist/dates/index.js
+var ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+var DMY_DATE = /^(\d{2})-(\d{2})-(\d{4})$/;
+var ISO_DATETIME = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?$/;
+function isoToDmy(date5) {
+  const m = ISO_DATE.exec(date5.trim());
+  return m ? `${m[3]}-${m[2]}-${m[1]}` : date5.trim();
+}
+function dmyToIso(date5) {
+  const m = DMY_DATE.exec(date5.trim());
+  return m ? `${m[3]}-${m[2]}-${m[1]}` : date5.trim();
+}
+function isoToCompactTimestamp(value) {
+  const v = value.trim();
+  const d = ISO_DATE.exec(v);
+  if (d)
+    return `${d[1]}${d[2]}${d[3]}000000`;
+  const dt = ISO_DATETIME.exec(v);
+  if (dt)
+    return `${dt[1]}${dt[2]}${dt[3]}${dt[4]}${dt[5]}${dt[6] ?? "00"}`;
+  return v;
+}
+
 // node_modules/@chrischall/mcp-utils/dist/zod/index.js
 var PositiveInt = external_exports.number().int().positive();
 var NonNegInt = external_exports.number().int().nonnegative();
@@ -31197,15 +31258,38 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.3.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";
 var SERVICE_NAME = "setlist.fm";
+var REQUEST_TIMEOUT_MS = 15e3;
 var SetlistClient = class {
   apiKey;
   configError;
@@ -31229,7 +31313,8 @@ var SetlistClient = class {
       baseUrl: BASE_URL,
       serviceName: SERVICE_NAME,
       retry: { count: 1, delayMs: 2e3 },
-      baseHeaders: lang ? { "Accept-Language": lang } : void 0
+      baseHeaders: lang ? { "Accept-Language": lang } : void 0,
+      timeout: REQUEST_TIMEOUT_MS
     });
   }
   requireKey() {
@@ -31243,11 +31328,12 @@ var SetlistClient = class {
    */
   async request(method, path, opts = {}) {
     const apiKey = this.requireKey();
-    return this.api.fetchJson(method, path, {
+    const data = await this.api.fetchJson(method, path, {
       headers: { "x-api-key": apiKey },
       ...opts.query !== void 0 ? { query: opts.query } : {},
       ...opts.body !== void 0 ? { body: opts.body } : {}
     });
+    return augmentSetlists(deepMapStringField(data, "eventDate", dmyToIso));
   }
 };
 var client = new SetlistClient();
@@ -31319,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"),
@@ -31332,14 +31418,17 @@ function registerSetlistTools(server) {
         stateCode: external_exports.string().optional().describe("State code"),
         countryCode: external_exports.string().optional().describe("Country code (ISO 3166-1 alpha-2)"),
         tourName: external_exports.string().optional().describe("Tour name"),
-        date: external_exports.string().optional().describe("Event date in dd-MM-yyyy format (e.g. 07-08-2023)"),
+        date: external_exports.string().optional().describe("Event date, ISO yyyy-MM-dd (e.g. 2025-08-28)"),
         year: external_exports.number().int().optional().describe("Event year"),
-        lastUpdated: external_exports.string().optional().describe("Only setlists updated after this UTC time (format yyyyMMddHHmmss)"),
+        lastUpdated: external_exports.string().optional().describe("Only setlists updated on/after this UTC time, ISO yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss"),
         p: page2
       }
     },
     async (args) => {
-      const data = await client.request("GET", "/1.0/search/setlists", { query: args });
+      const query = { ...args };
+      if (args.date) query.date = isoToDmy(args.date);
+      if (args.lastUpdated) query.lastUpdated = isoToCompactTimestamp(args.lastUpdated);
+      const data = await client.request("GET", "/1.0/search/setlists", { query });
       return textResult(data);
     }
   );
@@ -31539,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(
@@ -31590,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, } from '@chrischall/mcp-utils';
+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.
@@ -8,6 +9,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
 const BASE_URL = 'https://api.setlist.fm/rest';
 const SERVICE_NAME = 'setlist.fm';
+// Bound every request so a slow/hung upstream fails fast (createApiClient throws
+// RequestTimeoutError) instead of hanging the tool call. setlist.fm normally
+// answers in well under a second.
+const REQUEST_TIMEOUT_MS = 15_000;
 export class SetlistClient {
     apiKey;
     configError;
@@ -37,6 +42,7 @@ export class SetlistClient {
             serviceName: SERVICE_NAME,
             retry: { count: 1, delayMs: 2000 },
             baseHeaders: lang ? { 'Accept-Language': lang } : undefined,
+            timeout: REQUEST_TIMEOUT_MS,
         });
     }
     requireKey() {
@@ -51,11 +57,14 @@ export class SetlistClient {
      */
     async request(method, path, opts = {}) {
         const apiKey = this.requireKey();
-        return this.api.fetchJson(method, path, {
+        const data = await this.api.fetchJson(method, path, {
             headers: { 'x-api-key': apiKey },
             ...(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),
+        // 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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { textResult } from '@chrischall/mcp-utils';
+import { textResult, isoToDmy, isoToCompactTimestamp } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
 import { ATTRIBUTION_NOTE } from '../attribution.js';
 // How to read a setlist's song data (per setlist.fm's guidelines), so the model
@@ -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: {
@@ -27,16 +27,24 @@ export function registerSetlistTools(server) {
             stateCode: z.string().optional().describe('State code'),
             countryCode: z.string().optional().describe('Country code (ISO 3166-1 alpha-2)'),
             tourName: z.string().optional().describe('Tour name'),
-            date: z.string().optional().describe('Event date in dd-MM-yyyy format (e.g. 07-08-2023)'),
+            date: z
+                .string()
+                .optional()
+                .describe('Event date, ISO yyyy-MM-dd (e.g. 2025-08-28)'),
             year: z.number().int().optional().describe('Event year'),
             lastUpdated: z
                 .string()
                 .optional()
-                .describe('Only setlists updated after this UTC time (format yyyyMMddHHmmss)'),
+                .describe('Only setlists updated on/after this UTC time, ISO yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss'),
             p: page,
         },
     }, async (args) => {
-        const data = await client.request('GET', '/1.0/search/setlists', { query: args });
+        const query = { ...args };
+        if (args.date)
+            query.date = isoToDmy(args.date);
+        if (args.lastUpdated)
+            query.lastUpdated = isoToCompactTimestamp(args.lastUpdated);
+        const data = await client.request('GET', '/1.0/search/setlists', { query });
         return textResult(data);
     });
     server.registerTool('setlist_get_setlist', {

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.3.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.3.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>",
@@ -42,7 +42,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.5.2",
+    "@chrischall/mcp-utils": "^0.6.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"

package/server.json

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