sonovault-mcp 1.0.1 → 1.0.3

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,7 +3,7 @@
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 90M+ 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, 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
 
@@ -40,7 +40,43 @@ Add to `claude_desktop_config.json`:
40
40
  claude mcp add sonovault -e SONOVAULT_API_KEY=svk_live_... -- npx -y sonovault-mcp
41
41
  ```
42
42
 
43
- ### Cursor / VS Code / other MCP clients
43
+ ### Cursor
44
+
45
+ Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project):
46
+
47
+ ```json
48
+ {
49
+ "mcpServers": {
50
+ "sonovault": {
51
+ "command": "npx",
52
+ "args": ["-y", "sonovault-mcp"],
53
+ "env": { "SONOVAULT_API_KEY": "svk_live_..." }
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+ ### VS Code (GitHub Copilot)
60
+
61
+ Add to `.vscode/mcp.json`:
62
+
63
+ ```json
64
+ {
65
+ "servers": {
66
+ "sonovault": {
67
+ "command": "npx",
68
+ "args": ["-y", "sonovault-mcp"],
69
+ "env": { "SONOVAULT_API_KEY": "svk_live_..." }
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ ### Windsurf
76
+
77
+ Add the same `mcpServers` block as Claude Desktop to `~/.codeium/windsurf/mcp_config.json`.
78
+
79
+ ### Other MCP clients
44
80
 
45
81
  Any client that speaks MCP over stdio works. Command: `npx -y sonovault-mcp` with the `SONOVAULT_API_KEY` environment variable set.
46
82
 
@@ -63,12 +99,57 @@ Any client that speaks MCP over stdio works. Command: `npx -y sonovault-mcp` wit
63
99
 
64
100
  All tools are read-only. Most work on the free tier; `browse_tracks` needs a paid plan.
65
101
 
66
- ## Use cases
102
+ ## Example workflows
103
+
104
+ ### Enrich a radio play log for royalty reporting
105
+
106
+ Paste a play log with just artist and title, and ask: "Resolve these to ISRC, album, and label, and give me a table I can map onto a SoundExchange Report of Use." The assistant calls `resolve_tracks` once per 100 lines and returns the identifiers collecting societies match on. Works the same for PPL, Sena, GVL, and Re:Sound reporting.
107
+
108
+ ### Clean up a DJ library
109
+
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
+
112
+ ### Bridge recordings to compositions
113
+
114
+ "I have ISRCs from my distributor. Which musical works do they belong to, and what other recordings exist of each work?" The assistant chains `get_work_codes` and `get_recordings_of_work`. Useful for publishing administration and cover/version research.
115
+
116
+ ### Check cross-platform availability
117
+
118
+ "Is this Beatport exclusive on Spotify yet? Beatport ID 6014288." One `get_platform_links` call answers it, with deep links per platform.
119
+
120
+ ### Research a label
121
+
122
+ "Summarize what Anjunabeats released in the last six months, grouped by subgenre." The assistant pages through `get_label_releases` and pulls genre from the tracklists.
123
+
124
+ ## FAQ
125
+
126
+ ### Is there a free tier?
127
+
128
+ Yes. A free SonoVault key includes 1,000 requests/month with no credit card. Every tool except `browse_tracks` works on it.
129
+
130
+ ### What metadata does each track include?
131
+
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
+
134
+ ### Does it return BPM or musical key?
135
+
136
+ No. The public SonoVault API deliberately excludes audio features like BPM, key, and energy. No audio previews or artwork either.
137
+
138
+ ### Where does the data come from?
139
+
140
+ Aggregated and deduplicated from MusicBrainz, Discogs, Spotify, Apple Music, Tidal, and Beatport, with ISWC links from The MLC. Details: [sonovault.now/data-sources](https://sonovault.now/data-sources).
141
+
142
+ ### How is this different from a Spotify API integration?
143
+
144
+ Single-platform APIs return their own IDs only. SonoVault resolves one recording to its IDs on all seven supported platforms, keyed by ISRC, and adds identifiers (ISRC, ISWC) that platform APIs don't expose. Comparison: [sonovault.now/compare/spotify-api](https://sonovault.now/compare/spotify-api).
145
+
146
+ ### Is my API key sent anywhere besides SonoVault?
147
+
148
+ No. The server runs locally over stdio and sends your key only to `api.sonovault.now` as a request header. The code is small and auditable: [src/server.ts](src/server.ts).
149
+
150
+ ## Agent Skill
67
151
 
68
- - **Royalty reporting**: resolve radio play logs to the ISRC + label fields SoundExchange, PPL, and other societies match on.
69
- - **Publishing workflows**: bridge recordings to compositions with ISRC to ISWC mapping.
70
- - **Library tools**: dedupe and enrich music libraries by canonical identifiers.
71
- - **Cross-platform apps**: turn any platform's track ID into all the others.
152
+ Not using MCP? [`skill/SKILL.md`](skill/SKILL.md) is an [Agent Skill](https://agentskills.io/) that teaches any agent to call the SonoVault API directly over HTTP: search rules, ISRC/ISWC recipes, bulk resolution, and error handling.
72
153
 
73
154
  ## Related
74
155
 
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.0.1";
11
+ var SERVER_VERSION = "1.0.3";
12
12
  function json(data) {
13
13
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
14
14
  }
@@ -31,7 +31,7 @@ function createServer(sv2) {
31
31
  "search_tracks",
32
32
  {
33
33
  title: "Search tracks",
34
- description: "Search the SonoVault catalog (90M+ 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.",
34
+ 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.",
35
35
  inputSchema: {
36
36
  artist: z.string().describe("Artist name, e.g. 'Daft Punk'"),
37
37
  title: z.string().describe("Track title, e.g. 'One More Time'"),
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "sonovault-mcp",
3
- "version": "1.0.1",
4
- "description": "MCP server for the SonoVault music metadata API. Search 90M+ tracks, artists, and releases; get genre, label, release dates, ISRC/ISWC codes, and cross-platform IDs.",
3
+ "version": "1.0.3",
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.",
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": "^1.2.0",
46
+ "sonovault": "^3.0.0",
47
47
  "zod": "^3.25.0"
48
48
  },
49
49
  "devDependencies": {