sonovault-mcp 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,12 +3,13 @@
3
3
  [![CI](https://github.com/rekordcloud/sonovault-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/rekordcloud/sonovault-mcp/actions/workflows/ci.yml)
4
4
  [![npm](https://img.shields.io/npm/v/sonovault-mcp)](https://www.npmjs.com/package/sonovault-mcp)
5
5
 
6
- MCP server for the **[SonoVault](https://sonovault.now)** music metadata API. Gives Claude, Cursor, and any MCP client search across 93M+ tracks, artists, labels, and releases, with full metadata per result: genre, label, release dates, artist credits, ISRC and ISWC codes, and cross-platform IDs (Spotify, Apple Music, Tidal, Beatport, Discogs, MusicBrainz, YouTube).
6
+ MCP server for the **[SonoVault](https://sonovault.now)** music metadata API. Gives Claude, Cursor, and any MCP client search across 93M+ tracks, artists, labels, and releases, with full metadata per result: genre, BPM, musical key, label, release dates, artist credits, ISRC and ISWC codes, and cross-platform IDs (Spotify, Apple Music, Tidal, Beatport, Discogs, MusicBrainz, YouTube).
7
7
 
8
8
  Ask your assistant things like:
9
9
 
10
10
  - "What releases did mau5trap put out this year?"
11
11
  - "Find Daft Punk's Veridis Quo and give me its genre, label, and ISRC"
12
+ - "What key and BPM is One More Time, and which tracks on Discovery mix well with it?"
12
13
  - "Show me the tracklist of Discovery with ISRCs"
13
14
  - "What's the Spotify and Beatport ID for ISRC GBDUW0000053?"
14
15
  - "Resolve this play log to ISRCs and labels" (paste up to 100 lines)
@@ -84,16 +85,16 @@ Any client that speaks MCP over stdio works. Command: `npx -y sonovault-mcp` wit
84
85
 
85
86
  | Tool | What it does |
86
87
  |---|---|
87
- | `search_tracks` | Fuzzy search by artist + title. Returns ISRC, genre, label, release date. |
88
- | `lookup_isrc` | Exact recording lookup by ISRC. |
89
- | `get_track` | Fetch a track by SonoVault ID. |
88
+ | `search_tracks` | Fuzzy search by artist + title. Returns ISRC, genre, BPM, musical key, label, release date. |
89
+ | `lookup_isrc` | Exact recording lookup by ISRC, with BPM and musical key. |
90
+ | `get_track` | Fetch a track by SonoVault ID, with BPM and musical key. |
90
91
  | `get_work_codes` | Recording to composition: the ISWC(s) behind a recording. |
91
92
  | `get_recordings_of_work` | Composition to recordings: every recording of an ISWC. |
92
93
  | `get_platform_links` | One track's ID and deep link on all 7 platforms, from any ID or ISRC. |
93
94
  | `resolve_tracks` | Bulk resolve up to 100 track names, ISRCs, or platform IDs. |
94
95
  | `search_artists`, `get_artist_releases` | Artist search and discography, with Wikidata and MusicBrainz identifiers. |
95
96
  | `search_labels`, `get_label_releases` | Label search and catalog, optionally for one release date or a date range. |
96
- | `search_releases`, `get_release` | Release search, and tracklists with ISRCs in playing order with disc and track numbers, plus MusicBrainz release and release-group ids. `get_release` also lists the real editions behind a release, each with its own label and catalog number, and takes an `edition` id to render that edition's numbering. |
97
+ | `search_releases`, `get_release` | Release search, and tracklists with ISRCs, BPM and key in playing order with disc and track numbers, plus MusicBrainz release and release-group ids. `get_release` also lists the real editions behind a release, each with its own label and catalog number, and takes an `edition` id to render that edition's numbering. |
97
98
  | `list_genres` | The canonical genre hierarchy. |
98
99
  | `browse_tracks` | Discover by label, artist, genre, or year (paid tier). |
99
100
 
@@ -107,7 +108,7 @@ Paste a play log with just artist and title, and ask: "Resolve these to ISRC, al
107
108
 
108
109
  ### Clean up a DJ library
109
110
 
110
- "Here are 50 tracks from my rekordbox export. Find the canonical version of each, flag duplicates that share an ISRC, and tag each with its genre." The assistant combines `resolve_tracks` with the genre fields on each result.
111
+ "Here are 50 tracks from my rekordbox export. Find the canonical version of each, flag duplicates that share an ISRC, and tag each with its genre, BPM and key." The assistant combines `resolve_tracks` with the genre, tempo and key fields on each result.
111
112
 
112
113
  ### Bridge recordings to compositions
113
114
 
@@ -129,11 +130,17 @@ Yes. A free SonoVault key includes 1,000 requests/month with no credit card. Eve
129
130
 
130
131
  ### What metadata does each track include?
131
132
 
132
- Title, artist credits (with primary/remixer flags), ISRC, duration, genre and subgenre, and per-release album title, label, and release date. ISWC work codes come from the dedicated work-code tools.
133
+ Title, artist credits (with primary/remixer flags), ISRC, duration, BPM, musical key, genre and subgenre, and per-release album title, label, and release date. ISWC work codes come from the dedicated work-code tools.
133
134
 
134
135
  ### Does it return BPM or musical key?
135
136
 
136
- No. The public SonoVault API deliberately excludes audio features like BPM, key, and energy. No audio previews or artwork either.
137
+ Yes. Every track carries `bpm` (full tempo, up to 2 decimals, so 174 rather than 87) and its musical key in three notations:
138
+
139
+ - `key_alphanumeric`: 1 to 12 plus `A` for minor or `B` for major, e.g. `10B`. Neighbouring numbers and the same number with the other letter mix harmonically.
140
+ - `key_musical`: standard notation, e.g. `D`, `Am`, `F#m`, `Ebm`.
141
+ - `key_open`: Open Key notation, lowercase, e.g. `3d`, `1m`.
142
+
143
+ `keys` lists every key held for the track, one entry per source. Key comes from OpenKeyScan and BPM from the Lexicon DJ beat detector (trusted by 100k+ DJs), both run by SonoVault on the audio. Daft Punk's One More Time comes back as 123 BPM, `10B` / `D` / `3d`. All of these are null (and `keys` empty) for a track that has not been analysed yet. Other audio features such as energy or danceability are not exposed.
137
144
 
138
145
  ### Where does the data come from?
139
146
 
package/dist/index.js CHANGED
@@ -8,7 +8,7 @@ import { SonoVault as SonoVault2 } from "sonovault";
8
8
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
9
9
  import { SonoVaultError } from "sonovault";
10
10
  import { z } from "zod";
11
- var SERVER_VERSION = "1.2.0";
11
+ var SERVER_VERSION = "1.3.0";
12
12
  function json(data) {
13
13
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
14
14
  }
@@ -16,6 +16,7 @@ function toolError(err) {
16
16
  const message = err instanceof SonoVaultError ? `SonoVault API error (HTTP ${err.status}): ${err.message}` + (err.isForbidden ? " (this endpoint needs a paid SonoVault tier)" : "") + (err.isAuthError ? " (check SONOVAULT_API_KEY)" : "") : `Error: ${err.message}`;
17
17
  return { content: [{ type: "text", text: message }], isError: true };
18
18
  }
19
+ var KEY_BPM = "bpm (full tempo, e.g. 123) and musical key in three notations: key_alphanumeric (e.g. '10B'), key_musical (e.g. 'D', 'F#m') and key_open (Open Key, e.g. '3d'), plus keys[] with one entry per source. All null (keys empty) when the track has not been analysed.";
19
20
  var DATE = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Expected YYYY-MM-DD");
20
21
  function wrap(fn) {
21
22
  return async (...args) => {
@@ -32,7 +33,7 @@ function createServer(sv2) {
32
33
  "search_tracks",
33
34
  {
34
35
  title: "Search tracks",
35
- description: "Search the SonoVault catalog (93M+ tracks) by artist and title. Both are required; there is no free-text search. Returns ISRC, genre, duration, artist credits, and release info (album, label, release date) per track.",
36
+ description: "Search the SonoVault catalog (93M+ tracks) by artist and title. Both are required; there is no free-text search. Returns ISRC, genre, duration, BPM, musical key, artist credits, and release info (album, label, release date) per track. Tempo and key: " + KEY_BPM,
36
37
  inputSchema: {
37
38
  artist: z.string().describe("Artist name, e.g. 'Daft Punk'"),
38
39
  title: z.string().describe("Track title, e.g. 'One More Time'"),
@@ -45,7 +46,7 @@ function createServer(sv2) {
45
46
  "get_track",
46
47
  {
47
48
  title: "Get track by ID",
48
- description: "Fetch one track by its SonoVault track ID, with full metadata.",
49
+ description: "Fetch one track by its SonoVault track ID, with full metadata (ISRC, genre, duration, BPM, musical key, artist credits, releases). Tempo and key: " + KEY_BPM,
49
50
  inputSchema: { id: z.number().int().describe("SonoVault track ID") }
50
51
  },
51
52
  wrap(async ({ id }) => sv2.tracks.get(id))
@@ -54,7 +55,7 @@ function createServer(sv2) {
54
55
  "lookup_isrc",
55
56
  {
56
57
  title: "Look up a track by ISRC",
57
- description: "Exact lookup of a recording by its ISRC (International Standard Recording Code, e.g. GBDUW0000053). Returns the track's full metadata.",
58
+ description: "Exact lookup of a recording by its ISRC (International Standard Recording Code, e.g. GBDUW0000053). Returns the track's full metadata, including BPM and musical key. Tempo and key: " + KEY_BPM,
58
59
  inputSchema: { isrc: z.string().describe("ISRC code, e.g. GBDUW0000053") }
59
60
  },
60
61
  wrap(async ({ isrc }) => sv2.tracks.byIsrc(isrc))
@@ -95,7 +96,7 @@ function createServer(sv2) {
95
96
  applemusic_id: z.string().optional(),
96
97
  tidal_id: z.string().optional(),
97
98
  beatport_id: z.string().optional(),
98
- discogs_id: z.string().optional(),
99
+ discogs_id: z.string().optional().describe("Discogs track key: release ID plus track position, e.g. '2844-A'. A bare release ID matches nothing."),
99
100
  musicbrainz_id: z.string().optional(),
100
101
  youtube_id: z.string().optional()
101
102
  }
@@ -106,7 +107,7 @@ function createServer(sv2) {
106
107
  "resolve_tracks",
107
108
  {
108
109
  title: "Bulk resolve",
109
- description: "Resolve up to 100 inputs in one call to canonical tracks plus cross-platform links. input_type picks the key: 'track_name' (items are {artist, title} objects), 'isrc', 'sonovault_id', or a platform id type ('spotify_id', 'applemusic_id', 'tidal_id', 'beatport_id', 'discogs_id', 'musicbrainz_id'). Costs one API credit per line.",
110
+ description: "Resolve up to 100 inputs in one call to canonical tracks plus cross-platform links. input_type picks the key: 'track_name' (items are {artist, title} objects), 'isrc', 'sonovault_id', or a platform id type ('spotify_id', 'applemusic_id', 'tidal_id', 'beatport_id', 'discogs_id', 'musicbrainz_id'). A discogs_id item is a Discogs track key (release ID plus track position, e.g. '2844-A'), not a bare release ID. Each matched track carries the same fields as get_track, including BPM and musical key. Costs one API credit per line.",
110
111
  inputSchema: {
111
112
  input_type: z.enum([
112
113
  "track_name",
@@ -195,7 +196,7 @@ function createServer(sv2) {
195
196
  "get_release",
196
197
  {
197
198
  title: "Get release with tracklist",
198
- description: "Fetch one release by SonoVault release ID, including its full tracklist with ISRCs. Tracks come back in playing order, each with disc_number and track_number; a track whose position is unknown sorts last with both null. A SonoVault release groups every edition of an album onto one record, so the response also carries an editions array naming the real editions behind it, each with its provider, format, release date, barcode, country, track count, label and catalog number (pressings of one album often carry different labels); pass one of their ids as `edition` to render that edition's numbering instead of the default consensus. musicbrainz_release_ids and musicbrainz_release_group_ids are arrays for the same reason.",
199
+ description: "Fetch one release by SonoVault release ID, including its full tracklist with ISRCs, BPM and musical key per track (same bpm/key_* fields as get_track, null when not analysed). Tracks come back in playing order, each with disc_number and track_number; a track whose position is unknown sorts last with both null. A SonoVault release groups every edition of an album onto one record, so the response also carries an editions array naming the real editions behind it, each with its provider, format, release date, barcode, country, track count, label and catalog number (pressings of one album often carry different labels); pass one of their ids as `edition` to render that edition's numbering instead of the default consensus. musicbrainz_release_ids and musicbrainz_release_group_ids are arrays for the same reason.",
199
200
  inputSchema: {
200
201
  id: z.number().int().describe("SonoVault release ID"),
201
202
  edition: z.number().int().optional().describe("Edition id from the response's editions array. Renders that edition's track numbering; tracks it does not carry keep a null position and come last.")
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "sonovault-mcp",
3
- "version": "1.2.0",
4
- "description": "MCP server for the SonoVault music metadata API. Search 93M+ tracks, artists, and releases; get genre, label, release dates, ISRC/ISWC codes, and cross-platform IDs.",
3
+ "version": "1.3.0",
4
+ "description": "MCP server for the SonoVault music metadata API. Search 93M+ tracks, artists, and releases; get genre, BPM, musical key, label, release dates, ISRC/ISWC codes, and cross-platform IDs.",
5
5
  "mcpName": "io.github.rekordcloud/sonovault",
6
6
  "keywords": [
7
7
  "mcp",
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "dependencies": {
45
45
  "@modelcontextprotocol/sdk": "^1.29.0",
46
- "sonovault": "^4.2.0",
46
+ "sonovault": "^4.3.0",
47
47
  "zod": "^3.25.0"
48
48
  },
49
49
  "devDependencies": {