setlist-mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,67 @@
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { loadDotenvSafely, readEnvVar, createApiClient, } 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.
+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';
+export class SetlistClient {
+    apiKey;
+    configError;
+    api;
+    /**
+     * Defer the config error so the server can still start (and answer the host's
+     * install-time tools/list smoke test) when SETLIST_API_KEY isn't set yet.
+     * Tool calls re-raise the error at request time via {@link requireKey}.
+     */
+    constructor() {
+        const key = readEnvVar('SETLIST_API_KEY');
+        if (!key) {
+            this.apiKey = null;
+            this.configError = new Error('SETLIST_API_KEY environment variable is required');
+        }
+        else {
+            this.apiKey = key;
+            this.configError = null;
+        }
+        // setlist.fm authenticates with an `x-api-key` header (not a Bearer token),
+        // attached per-request in `request()`. We localize city/country names via an
+        // optional `Accept-Language`. `Accept: application/json` is already the
+        // fetchJson default (the API serves XML otherwise).
+        const lang = readEnvVar('SETLIST_ACCEPT_LANGUAGE');
+        this.api = createApiClient({
+            baseUrl: BASE_URL,
+            serviceName: SERVICE_NAME,
+            retry: { count: 1, delayMs: 2000 },
+            baseHeaders: lang ? { 'Accept-Language': lang } : undefined,
+        });
+    }
+    requireKey() {
+        if (this.configError)
+            throw this.configError;
+        return this.apiKey;
+    }
+    /**
+     * Issue a request with the `x-api-key` header attached. `requireKey()` runs
+     * here (not in the constructor) so a missing key surfaces at request time,
+     * keeping the deferred-config-error pattern intact.
+     */
+    async request(method, path, opts = {}) {
+        const apiKey = this.requireKey();
+        return this.api.fetchJson(method, path, {
+            headers: { 'x-api-key': apiKey },
+            ...(opts.query !== undefined ? { query: opts.query } : {}),
+            ...(opts.body !== undefined ? { body: opts.body } : {}),
+        });
+    }
+}
+/**
+ * Module-level singleton shared by every tool module. Constructing it here (not
+ * in `index.ts`) keeps the deferred-config-error pattern: the server boots and
+ * answers the host's install-time tools/list smoke test even when the API key
+ * is absent — the error only surfaces on the first request.
+ */
+export const client = new SetlistClient();

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { runMcp } from '@chrischall/mcp-utils';
+import { VERSION } from './version.js';
+import { registerArtistTools } from './tools/artists.js';
+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 { 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
+// deferred-config-error pattern: the server boots and answers the host's
+// install-time tools/list smoke test even when SETLIST_API_KEY is absent — the
+// configuration error only surfaces on the first tool call.
+await runMcp({
+    name: 'setlist-mcp',
+    version: VERSION,
+    banner: '[setlist-mcp] This project was developed and is maintained by AI (Claude Opus 4.8). Use at your own discretion.',
+    tools: [
+        registerArtistTools,
+        registerSetlistTools,
+        registerVenueTools,
+        registerGeoTools,
+        registerUserTools,
+        registerUtilityTools,
+    ],
+});

package/dist/tools/artists.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+const page = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .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.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            artistName: z.string().optional().describe('Artist name to search for'),
+            artistMbid: z.string().optional().describe("Artist's MusicBrainz ID (mbid)"),
+            sort: z
+                .enum(['sortName', 'relevance'])
+                .optional()
+                .describe('Sort order (sortName = default, or relevance)'),
+            p: page,
+        },
+    }, async ({ artistName, artistMbid, sort, p }) => {
+        const data = await client.request('GET', '/1.0/search/artists', {
+            query: { artistName, artistMbid, sort, p },
+        });
+        return textResult(data);
+    });
+    server.registerTool('setlist_get_artist', {
+        description: "Get a setlist.fm artist by their MusicBrainz ID (mbid).",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            mbid: z.string().describe("Artist's MusicBrainz ID (mbid)"),
+        },
+    }, async ({ mbid }) => {
+        const data = await client.request('GET', `/1.0/artist/${encodeURIComponent(mbid)}`);
+        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`.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            mbid: z.string().describe("Artist's MusicBrainz ID (mbid)"),
+            p: page,
+        },
+    }, async ({ mbid, p }) => {
+        const data = await client.request('GET', `/1.0/artist/${encodeURIComponent(mbid)}/setlists`, { query: { p } });
+        return textResult(data);
+    });
+}

package/dist/tools/geo.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+const page = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .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.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            name: z.string().optional().describe('City name'),
+            country: z.string().optional().describe("City's country"),
+            state: z.string().optional().describe('State the city lies in'),
+            stateCode: z.string().optional().describe('State code the city lies in'),
+            p: page,
+        },
+    }, async (args) => {
+        const data = await client.request('GET', '/1.0/search/cities', { query: args });
+        return textResult(data);
+    });
+    server.registerTool('setlist_get_city', {
+        description: "Get a city by its geoId.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            geoId: z.string().describe("City's geoId"),
+        },
+    }, async ({ geoId }) => {
+        const data = await client.request('GET', `/1.0/city/${encodeURIComponent(geoId)}`);
+        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.",
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const data = await client.request('GET', '/1.0/search/countries');
+        return textResult(data);
+    });
+}

package/dist/tools/setlists.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+const page = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .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.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            artistName: z.string().optional().describe('Artist name'),
+            artistMbid: z.string().optional().describe("Artist's MusicBrainz ID (mbid)"),
+            venueName: z.string().optional().describe('Venue name'),
+            venueId: z.string().optional().describe('Venue ID'),
+            cityName: z.string().optional().describe('City name'),
+            cityId: z.string().optional().describe("City's geoId"),
+            state: z.string().optional().describe('State name'),
+            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)'),
+            year: z.number().int().optional().describe('Event year'),
+            lastUpdated: z
+                .string()
+                .optional()
+                .describe('Only setlists updated after this UTC time (format yyyyMMddHHmmss)'),
+            p: page,
+        },
+    }, async (args) => {
+        const data = await client.request('GET', '/1.0/search/setlists', { query: args });
+        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.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            setlistId: z.string().describe('Setlist ID (e.g. 63de4613)'),
+        },
+    }, async ({ setlistId }) => {
+        const data = await client.request('GET', `/1.0/setlist/${encodeURIComponent(setlistId)}`);
+        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.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            versionId: z.string().describe('Setlist version ID'),
+        },
+    }, async ({ versionId }) => {
+        const data = await client.request('GET', `/1.0/setlist/version/${encodeURIComponent(versionId)}`);
+        return textResult(data);
+    });
+}

package/dist/tools/users.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+const page = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .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).",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            userId: z.string().describe('setlist.fm userId (username)'),
+        },
+    }, async ({ userId }) => {
+        const data = await client.request('GET', `/1.0/user/${encodeURIComponent(userId)}`);
+        return textResult(data);
+    });
+    server.registerTool('setlist_get_user_attended', {
+        description: "Get the concerts a setlist.fm user has marked as attended. Paginated via `p`.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            userId: z.string().describe('setlist.fm userId (username)'),
+            p: page,
+        },
+    }, async ({ userId, p }) => {
+        const data = await client.request('GET', `/1.0/user/${encodeURIComponent(userId)}/attended`, { query: { p } });
+        return textResult(data);
+    });
+    server.registerTool('setlist_get_user_edited', {
+        description: "Get the setlists a setlist.fm user has created or edited. Paginated via `p`.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            userId: z.string().describe('setlist.fm userId (username)'),
+            p: page,
+        },
+    }, async ({ userId, p }) => {
+        const data = await client.request('GET', `/1.0/user/${encodeURIComponent(userId)}/edited`, { query: { p } });
+        return textResult(data);
+    });
+}

package/dist/tools/utilities.js

@@ -0,0 +1,41 @@
+import { textResult, toolAnnotations, messageOf } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerUtilityTools(server) {
+    server.registerTool('setlist_healthcheck', {
+        title: 'Verify setlist.fm API key + connectivity',
+        description: 'Confirm the API key is configured and works by calling the setlist.fm countries endpoint. Reports {ok, authenticated, country_count} with a plain-English hint distinguishing "no key" vs "bad key" vs "API error". Read-only.',
+        annotations: toolAnnotations({
+            title: 'Verify setlist.fm API key + connectivity',
+            readOnly: true,
+            idempotent: true,
+            openWorld: true,
+        }),
+        inputSchema: {},
+    }, async () => {
+        try {
+            const data = await client.request('GET', '/1.0/search/countries');
+            const count = data.total ?? data.country?.length ?? 0;
+            return textResult({
+                ok: true,
+                authenticated: true,
+                country_count: count,
+                hint: 'API key is valid and the setlist.fm API is reachable.',
+            });
+        }
+        catch (e) {
+            const msg = messageOf(e);
+            const noKey = /environment variable is required/.test(msg);
+            const badKey = /\b(401|403)\b/.test(msg);
+            return textResult({
+                ok: false,
+                authenticated: false,
+                error: msg,
+                hint: noKey
+                    ? 'Set SETLIST_API_KEY (in .env or the MCP host env), then retry. Apply for a key at https://www.setlist.fm/settings/api.'
+                    : badKey
+                        ? 'The API key was rejected (401/403). Verify SETLIST_API_KEY is correct and active.'
+                        : 'The setlist.fm API call failed — it may be rate-limited or temporarily unavailable. Retry shortly.',
+            });
+        }
+    });
+}

package/dist/tools/venues.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+const page = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .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.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            name: z.string().optional().describe('Venue name'),
+            cityName: z.string().optional().describe('City the venue is in'),
+            cityId: z.string().optional().describe("City's geoId"),
+            state: z.string().optional().describe('State name'),
+            stateCode: z.string().optional().describe('State code'),
+            country: z.string().optional().describe("Venue's country"),
+            p: page,
+        },
+    }, async (args) => {
+        const data = await client.request('GET', '/1.0/search/venues', { query: args });
+        return textResult(data);
+    });
+    server.registerTool('setlist_get_venue', {
+        description: "Get a setlist.fm venue by its ID.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            venueId: z.string().describe('Venue ID'),
+        },
+    }, async ({ venueId }) => {
+        const data = await client.request('GET', `/1.0/venue/${encodeURIComponent(venueId)}`);
+        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`.",
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            venueId: z.string().describe('Venue ID'),
+            p: page,
+        },
+    }, async ({ venueId, p }) => {
+        const data = await client.request('GET', `/1.0/venue/${encodeURIComponent(venueId)}/setlists`, { query: { p } });
+        return textResult(data);
+    });
+}

package/dist/version.js

@@ -0,0 +1,6 @@
+// Single source of truth for the server version. release-please bumps the
+// string below via the `x-release-please-version` marker (registered in
+// 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.1.0'; // x-release-please-version

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "setlist-mcp",
+  "version": "0.1.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>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischall/setlist-mcp.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "setlist.fm",
+    "setlists",
+    "concerts",
+    "live-music",
+    "gigs",
+    "tours",
+    "musicbrainz"
+  ],
+  "type": "module",
+  "bin": {
+    "setlist-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    ".claude-plugin",
+    "SKILL.md",
+    ".mcp.json",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc && npm run bundle",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
+    "dev": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@chrischall/mcp-utils": "^0.5.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.0",
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "esbuild": "^0.28.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/server.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.chrischall/setlist-mcp",
+  "description": "setlist.fm concert data for Claude — setlists, artists, venues, tours, and cities",
+  "repository": {
+    "url": "https://github.com/chrischall/setlist-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "setlist-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "SETLIST_API_KEY",
+          "description": "Your setlist.fm API key (apply at setlist.fm/settings/api)",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true
+        },
+        {
+          "name": "SETLIST_ACCEPT_LANGUAGE",
+          "description": "Optional language for city/country names (en, es, fr, de, pt, tr, it, pl)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}