setlist-mcp 0.2.0 → 0.4.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.2.0"
+    "version": "0.4.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.2.0",
+      "version": "0.4.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -42,6 +42,15 @@ Optional: `SETLIST_ACCEPT_LANGUAGE` (one of `en, es, fr, de, pt, tr, it, pl`) lo
 
 See [SKILL.md](SKILL.md) for from-source setup, the full tool reference, and example flows.
 
+## Attribution & terms
+
+Use is governed by the [setlist.fm API terms](https://www.setlist.fm/help/api-terms). In short:
+
+- **Attribute setlist.fm.** Every result carries a `url`; surface it as a *followable* source link (no `nofollow`) wherever the data is shown. The tool descriptions instruct the model to do this, and results pass the `url` through verbatim.
+- **Non-commercial only** under a free key — commercial use requires setlist.fm's permission.
+- **No persistent caching** — this server makes a live API call per tool invocation and keeps no datastore. Please don't add one.
+- **Keep your API key private** — it lives in `SETLIST_API_KEY` (`.env` is gitignored) and never appears in tool output.
+
 ## Development
 
 ```bash

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,11 +98,25 @@ 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
+
+setlist.fm's [API terms](https://www.setlist.fm/help/api-terms) bind anyone using this data. When you present setlist.fm results to a user:
+
+- **Always cite the source.** Each setlist/artist/venue result includes a `url` — show it as a real, clickable link to setlist.fm (e.g. "Source: [The Beatles setlist on setlist.fm](https://www.setlist.fm/...)"). The terms require a *followable* link — never a `nofollow`. If a particular result has no `url`, link to https://www.setlist.fm instead.
+- **Non-commercial use only.** A free API key covers non-commercial use; commercial use needs setlist.fm's permission.
+- **Live data, not a datastore.** The terms forbid persistent caching — this server fetches fresh on every call and you should treat results as point-in-time, not build a local copy.
+- **Don't expose or share the API key.** It's read from `SETLIST_API_KEY` and never appears in results.
+
+## Interpreting setlist data
+
+- Songs live in `sets.set[]`; each set may have an `encore` number (1 = first encore) and a `name` (e.g. an acoustic set or a full album).
+- Each `song` may carry: `tape: true` (a pre-recorded intro/outro — not actually performed live), `cover` (the original artist when it's a cover), `with` (a guest performer), and `info` (a note like "acoustic" or "first time live"). Surface these when relevant rather than dropping them.
 
 ## Notes
 
 - 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/attribution.js

@@ -0,0 +1,6 @@
+// setlist.fm API terms require a *followable* attribution link wherever their
+// data appears (no nofollow): https://www.setlist.fm/help/api-terms. Every
+// setlist/artist/venue object carries a `url` (passed through verbatim by
+// textResult), so this note — appended to each data tool's description, but not
+// to setlist_healthcheck — tells the model to surface that `url` as a source link.
+export const ATTRIBUTION_NOTE = ' Results include a setlist.fm `url`; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no `url`, link to https://www.setlist.fm instead.';

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,7 +31258,7 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 
 // src/client.ts
 import { dirname, join } from "path";
@@ -31206,6 +31267,7 @@ 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 +31291,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,22 +31306,26 @@ 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 deepMapStringField(data, "eventDate", dmyToIso);
   }
 };
 var client = new SetlistClient();
 
+// src/attribution.ts
+var ATTRIBUTION_NOTE = " Results include a setlist.fm `url`; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution \u2014 no nofollow). If a result has no `url`, link to https://www.setlist.fm instead.";
+
 // src/tools/artists.ts
 var page = external_exports.number().int().positive().optional().describe("Result page number (defaults to 1)");
 function registerArtistTools(server) {
   server.registerTool(
     "setlist_search_artists",
     {
-      description: "Search setlist.fm for artists by name or MusicBrainz ID. Returns matching artists with their MusicBrainz ID (mbid) \u2014 use that mbid with setlist_get_artist or setlist_get_artist_setlists.",
+      description: "Search setlist.fm for artists by name or MusicBrainz ID. Returns matching artists with their MusicBrainz ID (mbid) \u2014 use that mbid with setlist_get_artist or setlist_get_artist_setlists." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         artistName: external_exports.string().optional().describe("Artist name to search for"),
@@ -31277,7 +31344,7 @@ function registerArtistTools(server) {
   server.registerTool(
     "setlist_get_artist",
     {
-      description: "Get a setlist.fm artist by their MusicBrainz ID (mbid).",
+      description: "Get a setlist.fm artist by their MusicBrainz ID (mbid)." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         mbid: external_exports.string().describe("Artist's MusicBrainz ID (mbid)")
@@ -31291,7 +31358,7 @@ function registerArtistTools(server) {
   server.registerTool(
     "setlist_get_artist_setlists",
     {
-      description: "Get an artist's setlists (most recent first) by their MusicBrainz ID (mbid). Paginated via `p`.",
+      description: "Get an artist's setlists (most recent first) by their MusicBrainz ID (mbid). Paginated via `p`." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         mbid: external_exports.string().describe("Artist's MusicBrainz ID (mbid)"),
@@ -31310,12 +31377,13 @@ function registerArtistTools(server) {
 }
 
 // src/tools/setlists.ts
+var SETLIST_SHAPE_NOTE = ' A setlist\'s songs live in `sets.set[]`; each set may have an `encore` number (1 = first encore) and a `name` (e.g. an acoustic set or a full album). Each `song` may carry: `tape: true` (pre-recorded intro/outro/interlude \u2014 not actually performed), `cover` (the original artist when it is a cover), `with` (a guest performer), and `info` (a note like "acoustic" or "first time live").';
 var page2 = external_exports.number().int().positive().optional().describe("Result page number (defaults to 1)");
 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. Returns setlists with their songs and event details. Provide at least one filter." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         artistName: external_exports.string().optional().describe("Artist name"),
@@ -31328,21 +31396,24 @@ 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);
     }
   );
   server.registerTool(
     "setlist_get_setlist",
     {
-      description: "Get a setlist.fm setlist by its ID, including the full song list and event details.",
+      description: "Get a setlist.fm setlist by its ID, including the full song list and event details." + SETLIST_SHAPE_NOTE + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         setlistId: external_exports.string().describe("Setlist ID (e.g. 63de4613)")
@@ -31356,7 +31427,7 @@ function registerSetlistTools(server) {
   server.registerTool(
     "setlist_get_setlist_version",
     {
-      description: "Get a specific historical version of a setlist by its version ID. Setlists are wiki-edited; each edit has a version ID returned in a setlist's `versionId` field.",
+      description: "Get a specific historical version of a setlist by its version ID. Setlists are wiki-edited; each edit has a version ID returned in a setlist's `versionId` field." + SETLIST_SHAPE_NOTE + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         versionId: external_exports.string().describe("Setlist version ID")
@@ -31378,7 +31449,7 @@ function registerVenueTools(server) {
   server.registerTool(
     "setlist_search_venues",
     {
-      description: "Search setlist.fm for venues by name and/or location. Returns matching venues with their venue ID \u2014 use it with setlist_get_venue or setlist_get_venue_setlists.",
+      description: "Search setlist.fm for venues by name and/or location. Returns matching venues with their venue ID \u2014 use it with setlist_get_venue or setlist_get_venue_setlists." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         name: external_exports.string().optional().describe("Venue name"),
@@ -31398,7 +31469,7 @@ function registerVenueTools(server) {
   server.registerTool(
     "setlist_get_venue",
     {
-      description: "Get a setlist.fm venue by its ID.",
+      description: "Get a setlist.fm venue by its ID." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         venueId: external_exports.string().describe("Venue ID")
@@ -31412,7 +31483,7 @@ function registerVenueTools(server) {
   server.registerTool(
     "setlist_get_venue_setlists",
     {
-      description: "Get setlists performed at a venue, by venue ID (most recent first). Paginated via `p`.",
+      description: "Get setlists performed at a venue, by venue ID (most recent first). Paginated via `p`." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         venueId: external_exports.string().describe("Venue ID"),
@@ -31436,7 +31507,7 @@ function registerGeoTools(server) {
   server.registerTool(
     "setlist_search_cities",
     {
-      description: "Search setlist.fm for cities by name and/or location. Returns cities with their geoId \u2014 use it as cityId in setlist_search_setlists / setlist_search_venues, or with setlist_get_city.",
+      description: "Search setlist.fm for cities by name and/or location. Returns cities with their geoId \u2014 use it as cityId in setlist_search_setlists / setlist_search_venues, or with setlist_get_city." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         name: external_exports.string().optional().describe("City name"),
@@ -31454,7 +31525,7 @@ function registerGeoTools(server) {
   server.registerTool(
     "setlist_get_city",
     {
-      description: "Get a city by its geoId.",
+      description: "Get a city by its geoId." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         geoId: external_exports.string().describe("City's geoId")
@@ -31468,7 +31539,7 @@ function registerGeoTools(server) {
   server.registerTool(
     "setlist_search_countries",
     {
-      description: "List all countries supported by setlist.fm, with their ISO country codes. Use a code as countryCode in setlist_search_setlists.",
+      description: "List all countries supported by setlist.fm, with their ISO country codes. Use a code as countryCode in setlist_search_setlists." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true }
     },
     async () => {
@@ -31484,7 +31555,7 @@ function registerUserTools(server) {
   server.registerTool(
     "setlist_get_user",
     {
-      description: "Get a setlist.fm user's public profile by their userId (their setlist.fm username).",
+      description: "Get a setlist.fm user's public profile by their userId (their setlist.fm username)." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         userId: external_exports.string().describe("setlist.fm userId (username)")
@@ -31498,7 +31569,7 @@ function registerUserTools(server) {
   server.registerTool(
     "setlist_get_user_attended",
     {
-      description: "Get the concerts a setlist.fm user has marked as attended. Paginated via `p`.",
+      description: "Get the concerts a setlist.fm user has marked as attended. Paginated via `p`." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         userId: external_exports.string().describe("setlist.fm userId (username)"),
@@ -31517,7 +31588,7 @@ function registerUserTools(server) {
   server.registerTool(
     "setlist_get_user_edited",
     {
-      description: "Get the setlists a setlist.fm user has created or edited. Paginated via `p`.",
+      description: "Get the setlists a setlist.fm user has created or edited. Paginated via `p`." + ATTRIBUTION_NOTE,
       annotations: { readOnlyHint: true },
       inputSchema: {
         userId: external_exports.string().describe("setlist.fm userId (username)"),

package/dist/client.js

@@ -1,6 +1,6 @@
 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';
 // 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 +8,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 +41,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 +56,13 @@ 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).
+        return deepMapStringField(data, 'eventDate', dmyToIso);
     }
 }
 /**

package/dist/tools/artists.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { textResult } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
+import { ATTRIBUTION_NOTE } from '../attribution.js';
 const page = z
     .number()
     .int()
@@ -9,7 +10,8 @@ const page = z
     .describe('Result page number (defaults to 1)');
 export function registerArtistTools(server) {
     server.registerTool('setlist_search_artists', {
-        description: "Search setlist.fm for artists by name or MusicBrainz ID. Returns matching artists with their MusicBrainz ID (mbid) — use that mbid with setlist_get_artist or setlist_get_artist_setlists.",
+        description: "Search setlist.fm for artists by name or MusicBrainz ID. Returns matching artists with their MusicBrainz ID (mbid) — use that mbid with setlist_get_artist or setlist_get_artist_setlists." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             artistName: z.string().optional().describe('Artist name to search for'),
@@ -27,7 +29,7 @@ export function registerArtistTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_get_artist', {
-        description: "Get a setlist.fm artist by their MusicBrainz ID (mbid).",
+        description: "Get a setlist.fm artist by their MusicBrainz ID (mbid)." + ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             mbid: z.string().describe("Artist's MusicBrainz ID (mbid)"),
@@ -37,7 +39,8 @@ export function registerArtistTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_get_artist_setlists', {
-        description: "Get an artist's setlists (most recent first) by their MusicBrainz ID (mbid). Paginated via `p`.",
+        description: "Get an artist's setlists (most recent first) by their MusicBrainz ID (mbid). Paginated via `p`." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             mbid: z.string().describe("Artist's MusicBrainz ID (mbid)"),

package/dist/tools/geo.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { textResult } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
+import { ATTRIBUTION_NOTE } from '../attribution.js';
 const page = z
     .number()
     .int()
@@ -9,7 +10,8 @@ const page = z
     .describe('Result page number (defaults to 1)');
 export function registerGeoTools(server) {
     server.registerTool('setlist_search_cities', {
-        description: "Search setlist.fm for cities by name and/or location. Returns cities with their geoId — use it as cityId in setlist_search_setlists / setlist_search_venues, or with setlist_get_city.",
+        description: "Search setlist.fm for cities by name and/or location. Returns cities with their geoId — use it as cityId in setlist_search_setlists / setlist_search_venues, or with setlist_get_city." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             name: z.string().optional().describe('City name'),
@@ -23,7 +25,7 @@ export function registerGeoTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_get_city', {
-        description: "Get a city by its geoId.",
+        description: "Get a city by its geoId." + ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             geoId: z.string().describe("City's geoId"),
@@ -33,7 +35,8 @@ export function registerGeoTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_search_countries', {
-        description: "List all countries supported by setlist.fm, with their ISO country codes. Use a code as countryCode in setlist_search_setlists.",
+        description: "List all countries supported by setlist.fm, with their ISO country codes. Use a code as countryCode in setlist_search_setlists." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
     }, async () => {
         const data = await client.request('GET', '/1.0/search/countries');

package/dist/tools/setlists.js

@@ -1,6 +1,10 @@
 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
+// renders shows correctly. Appended to the get_setlist descriptions.
+const SETLIST_SHAPE_NOTE = ' A setlist\'s songs live in `sets.set[]`; each set may have an `encore` number (1 = first encore) and a `name` (e.g. an acoustic set or a full album). Each `song` may carry: `tape: true` (pre-recorded intro/outro/interlude — not actually performed), `cover` (the original artist when it is a cover), `with` (a guest performer), and `info` (a note like "acoustic" or "first time live").';
 const page = z
     .number()
     .int()
@@ -9,7 +13,8 @@ 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. Returns setlists with their songs and event details. Provide at least one filter." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             artistName: z.string().optional().describe('Artist name'),
@@ -22,20 +27,30 @@ 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', {
-        description: "Get a setlist.fm setlist by its ID, including the full song list and event details.",
+        description: "Get a setlist.fm setlist by its ID, including the full song list and event details." +
+            SETLIST_SHAPE_NOTE +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             setlistId: z.string().describe('Setlist ID (e.g. 63de4613)'),
@@ -45,7 +60,9 @@ export function registerSetlistTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_get_setlist_version', {
-        description: "Get a specific historical version of a setlist by its version ID. Setlists are wiki-edited; each edit has a version ID returned in a setlist's `versionId` field.",
+        description: "Get a specific historical version of a setlist by its version ID. Setlists are wiki-edited; each edit has a version ID returned in a setlist's `versionId` field." +
+            SETLIST_SHAPE_NOTE +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             versionId: z.string().describe('Setlist version ID'),

package/dist/tools/users.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { textResult } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
+import { ATTRIBUTION_NOTE } from '../attribution.js';
 const page = z
     .number()
     .int()
@@ -9,7 +10,8 @@ const page = z
     .describe('Result page number (defaults to 1)');
 export function registerUserTools(server) {
     server.registerTool('setlist_get_user', {
-        description: "Get a setlist.fm user's public profile by their userId (their setlist.fm username).",
+        description: "Get a setlist.fm user's public profile by their userId (their setlist.fm username)." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             userId: z.string().describe('setlist.fm userId (username)'),
@@ -19,7 +21,8 @@ export function registerUserTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_get_user_attended', {
-        description: "Get the concerts a setlist.fm user has marked as attended. Paginated via `p`.",
+        description: "Get the concerts a setlist.fm user has marked as attended. Paginated via `p`." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             userId: z.string().describe('setlist.fm userId (username)'),
@@ -30,7 +33,8 @@ export function registerUserTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_get_user_edited', {
-        description: "Get the setlists a setlist.fm user has created or edited. Paginated via `p`.",
+        description: "Get the setlists a setlist.fm user has created or edited. Paginated via `p`." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             userId: z.string().describe('setlist.fm userId (username)'),

package/dist/tools/venues.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { textResult } from '@chrischall/mcp-utils';
 import { client } from '../client.js';
+import { ATTRIBUTION_NOTE } from '../attribution.js';
 const page = z
     .number()
     .int()
@@ -9,7 +10,8 @@ const page = z
     .describe('Result page number (defaults to 1)');
 export function registerVenueTools(server) {
     server.registerTool('setlist_search_venues', {
-        description: "Search setlist.fm for venues by name and/or location. Returns matching venues with their venue ID — use it with setlist_get_venue or setlist_get_venue_setlists.",
+        description: "Search setlist.fm for venues by name and/or location. Returns matching venues with their venue ID — use it with setlist_get_venue or setlist_get_venue_setlists." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             name: z.string().optional().describe('Venue name'),
@@ -25,7 +27,7 @@ export function registerVenueTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_get_venue', {
-        description: "Get a setlist.fm venue by its ID.",
+        description: "Get a setlist.fm venue by its ID." + ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             venueId: z.string().describe('Venue ID'),
@@ -35,7 +37,8 @@ export function registerVenueTools(server) {
         return textResult(data);
     });
     server.registerTool('setlist_get_venue_setlists', {
-        description: "Get setlists performed at a venue, by venue ID (most recent first). Paginated via `p`.",
+        description: "Get setlists performed at a venue, by venue ID (most recent first). Paginated via `p`." +
+            ATTRIBUTION_NOTE,
         annotations: { readOnlyHint: true },
         inputSchema: {
             venueId: z.string().describe('Venue ID'),

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.2.0'; // x-release-please-version
+export const VERSION = '0.4.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "setlist-mcp",
-  "version": "0.2.0",
+  "version": "0.4.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.2.0",
+  "version": "0.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "setlist-mcp",
-      "version": "0.2.0",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       },