discogs-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Discogs MCP — a Cloudflare Workers MCP server that lets AI assistants interact with users' Discogs music collections. Implements OAuth 1.0a authentication against the Discogs API, intelligent search with mood mapping, and context-aware recommendations. Deployed at discogs-mcp.com (locked to maintainer; users must self-host).

Commands

npm run dev              # Local dev server on port 8787
npm run build            # Dry-run build (wrangler deploy --dry-run)
npm test                 # Vitest with Cloudflare Workers pool
npm test -- path/to/file # Single test file
npm test -- --watch      # Watch mode
npm run lint             # ESLint (must pass before every commit)
npm run format           # Prettier --write
npm run format:check     # Prettier --check
npm run deploy           # Deploy to dev environment
npm run deploy:prod      # Deploy to production
npm run cf-typegen       # Regenerate Cloudflare Workers types

Architecture

Entry point: src/index-oauth.ts — routes requests through OAuthProvider which handles OAuth endpoints, then delegates MCP traffic to the server created by src/mcp/server.ts.

src/
├── auth/              # OAuth 1.0a flow against Discogs
├── clients/           # DiscogsClient (API calls + retry) → CachedDiscogsClient (KV cache wrapper)
├── mcp/
│   ├── server.ts      # MCP server factory — registers all tools, resources, prompts
│   ├── tools/
│   │   ├── public.ts          # Unauthenticated: ping, server_info, auth_status
│   │   └── authenticated.ts   # Requires auth: search_collection, search_discogs, get_release, etc.
│   ├── resources/     # MCP resource definitions
│   └── prompts/       # MCP prompt templates
├── rate-limiter/      # Durable Object for coordinated rate limiting across Workers
├── types/             # Shared TypeScript types
├── utils/
│   ├── moodMapping.ts         # Maps emotional descriptors ("mellow", "Sunday vibes") → genres/styles
│   ├── searchRanking.ts       # Deduplication, scoring, ranking of search results
│   ├── searchQueryParser.ts   # Classifies queries (mood, specific, genre, etc.)
│   ├── cache.ts               # KV-based caching utilities
│   └── kvLogger.ts            # Structured logging to KV
└── marketing-page.ts  # HTML landing page