SetlistMCP CLAUDE.md

setlist-mcp

An MCP server exposing setlist.fm search to Claude, for looking up setlists from gigs Adrian has been to.

This file is the standing context for Claude Code sessions in this repo — keep it current as the project evolves instead of letting it drift out of sync.

The rule that breaks everything if forgotten

stdout is the JSON-RPC channel. This server speaks MCP over stdio, and the host parses every line of stdout as a protocol message. One stray line — from your code or from a dependency — breaks the connection, and the symptom is an unhelpful SyntaxError from the host quoting the offending character.

So:

• Never console.log in src/. Use the injected logger, or console.error.
• The winston console transport is configured with stderrLevels covering every level (see src/logger.js), driven by consoleToStderr in src/config/*.json. Don't remove that.
• dotenv.config() must keep quiet: true — dotenv prints an "injected env" banner to stdout otherwise. This is verified: it writes 76 bytes to stdout, 0 to stderr.
• Paths resolve against import.meta.dirname, never the cwd. An MCP client spawns the server from its own working directory.

Stack

• Node.js 22+ (ESM, "type": "module"), no bundler or TS build step
• @modelcontextprotocol/server v2 (pinned to 2.0.0) + zod v4 for schemas
• Mocha + Chai + Sinon for tests, c8 for coverage
• ESLint (neostandard) — no semicolons
• npm (not yarn/pnpm)

Architecture

src/index.js          entry point: dotenv, serveStdio, signals
src/server.js         createDependencies() + createServer()
src/tools/            one module per tool, plus shared result helpers
src/services/         API clients and the primitives they sit on

createDependencies() is called once, outside the serveStdio factory. serveStdio invokes its factory per connection, so building rate limiters inside it would reset them on every client reconnect and double the outbound request rate.