DnB Crate MCP

Local-first catalog for a private drum & bass library. An MCP host (Cursor, Codex, MCP Inspector) talks to a stdio server; the same domain services are also available from a CLI. The app indexes a local crate, analyzes tracks (BPM, grid, key, sections, descriptors), plans a deterministic one-hour set, and renders a gapless 24-bit FLAC with equal-power crossfades plus beat-aligned phrase mixes and bass swaps.

The language model interprets requests. This application owns scanning, storage, search, and validation.

Prerequisites

• Node.js 24+ (the version used at repo init was 24.16.0)

• pnpm 11+

• A folder of audio you own or may access (.wav, .flac, .mp3, .m4a, .aiff)

• FFmpeg and ffprobe on PATH for rendering (see docs/rendering.md and docs/analysis.md). Status tools report whether they are present.

Related MCP server: rekordbox-mcp

Setup

pnpm install
copy dnb-crate.config.example.json dnb-crate.config.json

Edit dnb-crate.config.json so libraryRoots points at your music folder and outputRoot points at a directory that is not inside that library. Both dnb-crate.config.json and data/ are gitignored.

Alternatively, use environment variables (see .env.example).

CLI

pnpm cli db:migrate
pnpm cli library:scan
pnpm cli library:scan --dry-run
pnpm cli library:stats
pnpm cli track:search --query "Technimatic" --limit 10
pnpm cli analysis:start --track-id UUID --wait
pnpm cli analysis:get --track-id UUID
pnpm cli analysis:compare --track-id UUID
pnpm cli analysis:report
pnpm cli analysis:cue-preview --track-id UUID --cue drop
pnpm cli transition:plan --from UUID --to UUID --bars 32
pnpm cli plan:create --name "Liquid hour" --duration-ms 3600000 --seed 1 --end-query "Nightfall"
pnpm cli plan:list
pnpm cli plan:get --id UUID
pnpm cli plan:validate --id UUID
pnpm cli render:start --plan-id UUID --wait
pnpm cli render:status --id UUID
pnpm cli render:manifest --id UUID

JSON is written to stdout. Diagnostics go to stderr.

MCP server (stdio)

Stdout is reserved for JSON-RPC. Do not console.log in this process.

pnpm mcp

Cursor

In your user MCP config (path varies by Cursor version), add a server without hardcoding someone else’s disk layout:

{
  "mcpServers": {
    "dnb-crate": {
      "command": "npx",
      "args": ["tsx", "apps/mcp-server/src/main.ts"],
      "cwd": "PATH_TO_THIS_REPO",
      "env": {
        "DNB_CRATE_CONFIG": "PATH_TO_THIS_REPO/dnb-crate.config.json"
      }
    }
  }
}

Use pnpm exec tsx instead of npx tsx if you prefer the workspace binary.

MCP Inspector

npx @modelcontextprotocol/inspector pnpm mcp

Set the same DNB_CRATE_* environment variables in the Inspector session. Confirm tools/list, call scan_library, then search_tracks.

Tools (33)

Resources: dnbcrate://tracks/{trackId}, dnbcrate://tracks/{trackId}/analysis, dnbcrate://set-plans/{setPlanId}, dnbcrate://renders/{renderJobId}/manifest.

Prompt: build-dnb-set (optional; the tool workflow works without it).

Scoring details: docs/scoring.md. Analysis / templates: docs/analysis.md. Rendering / loudness / jobs: docs/rendering.md. Ear-check lessons for later mixes: docs/mixing-lessons.md. Example plan JSON: docs/examples/one-hour-plan.example.json.

Tests

pnpm test
pnpm typecheck
pnpm lint
pnpm format:check

Tests generate tiny sine-wave fixtures. They never read a private library.

Layout

• packages/domain — types, config, errors, key normalization

• packages/catalog — SQLite, scanner, search, set plans, analysis jobs, render jobs

• packages/audio-analysis — envelope BPM/grid analyzer, click-track fixtures

• packages/audio-renderer — FFmpeg adapter, equal-power / phrase-mix / bass-swap, loudness

• apps/cli — deterministic administration

• apps/mcp-server — thin MCP adapters

• docs/ — decisions, progress, tool contracts, spec

Source-file safety

Source music is read-only. Generated files go under outputRoot. Tools never accept arbitrary paths, SQL, or shell commands.