@cyanheads/musicbrainz-mcp-server 0.2.0 → 0.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.
Files changed (79) hide show
  1. package/AGENTS.md +44 -13
  2. package/CLAUDE.md +44 -13
  3. package/Dockerfile +6 -3
  4. package/README.md +79 -125
  5. package/changelog/0.2.x/0.2.1.md +32 -0
  6. package/changelog/0.3.x/0.3.0.md +33 -0
  7. package/dist/config/server-config.d.ts +1 -0
  8. package/dist/config/server-config.d.ts.map +1 -1
  9. package/dist/config/server-config.js +5 -0
  10. package/dist/config/server-config.js.map +1 -1
  11. package/dist/index.js +2 -1
  12. package/dist/index.js.map +1 -1
  13. package/dist/mcp-server/resources/definitions/entity.resource.d.ts.map +1 -1
  14. package/dist/mcp-server/resources/definitions/entity.resource.js +18 -6
  15. package/dist/mcp-server/resources/definitions/entity.resource.js.map +1 -1
  16. package/dist/mcp-server/tools/definitions/_pagination.d.ts +12 -0
  17. package/dist/mcp-server/tools/definitions/_pagination.d.ts.map +1 -0
  18. package/dist/mcp-server/tools/definitions/_pagination.js +52 -0
  19. package/dist/mcp-server/tools/definitions/_pagination.js.map +1 -0
  20. package/dist/mcp-server/tools/definitions/_shared.d.ts +2 -0
  21. package/dist/mcp-server/tools/definitions/_shared.d.ts.map +1 -1
  22. package/dist/mcp-server/tools/definitions/_shared.js +22 -6
  23. package/dist/mcp-server/tools/definitions/_shared.js.map +1 -1
  24. package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts +15 -3
  25. package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts.map +1 -1
  26. package/dist/mcp-server/tools/definitions/browse-entities.tool.js +128 -31
  27. package/dist/mcp-server/tools/definitions/browse-entities.tool.js.map +1 -1
  28. package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts +13 -0
  29. package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts.map +1 -1
  30. package/dist/mcp-server/tools/definitions/get-artist.tool.js +53 -1
  31. package/dist/mcp-server/tools/definitions/get-artist.tool.js.map +1 -1
  32. package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts +7 -0
  33. package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts.map +1 -1
  34. package/dist/mcp-server/tools/definitions/get-cover-art.tool.js +45 -8
  35. package/dist/mcp-server/tools/definitions/get-cover-art.tool.js.map +1 -1
  36. package/dist/mcp-server/tools/definitions/get-label.tool.d.ts +15 -0
  37. package/dist/mcp-server/tools/definitions/get-label.tool.d.ts.map +1 -1
  38. package/dist/mcp-server/tools/definitions/get-label.tool.js +28 -4
  39. package/dist/mcp-server/tools/definitions/get-label.tool.js.map +1 -1
  40. package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts +13 -0
  41. package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts.map +1 -1
  42. package/dist/mcp-server/tools/definitions/get-recording.tool.js +27 -6
  43. package/dist/mcp-server/tools/definitions/get-recording.tool.js.map +1 -1
  44. package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts +4 -0
  45. package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts.map +1 -1
  46. package/dist/mcp-server/tools/definitions/get-release-group.tool.js +9 -3
  47. package/dist/mcp-server/tools/definitions/get-release-group.tool.js.map +1 -1
  48. package/dist/mcp-server/tools/definitions/get-release.tool.d.ts +24 -3
  49. package/dist/mcp-server/tools/definitions/get-release.tool.d.ts.map +1 -1
  50. package/dist/mcp-server/tools/definitions/get-release.tool.js +69 -8
  51. package/dist/mcp-server/tools/definitions/get-release.tool.js.map +1 -1
  52. package/dist/mcp-server/tools/definitions/get-work.tool.d.ts +8 -2
  53. package/dist/mcp-server/tools/definitions/get-work.tool.d.ts.map +1 -1
  54. package/dist/mcp-server/tools/definitions/get-work.tool.js +33 -5
  55. package/dist/mcp-server/tools/definitions/get-work.tool.js.map +1 -1
  56. package/dist/mcp-server/tools/definitions/index.d.ts +152 -53
  57. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  58. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts +2 -2
  59. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts.map +1 -1
  60. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js +26 -7
  61. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js.map +1 -1
  62. package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts +9 -1
  63. package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map +1 -1
  64. package/dist/mcp-server/tools/definitions/search-entities.tool.js +44 -14
  65. package/dist/mcp-server/tools/definitions/search-entities.tool.js.map +1 -1
  66. package/dist/services/musicbrainz/musicbrainz-service.d.ts +12 -3
  67. package/dist/services/musicbrainz/musicbrainz-service.d.ts.map +1 -1
  68. package/dist/services/musicbrainz/musicbrainz-service.js +22 -4
  69. package/dist/services/musicbrainz/musicbrainz-service.js.map +1 -1
  70. package/dist/services/musicbrainz/release-appearances.d.ts +16 -0
  71. package/dist/services/musicbrainz/release-appearances.d.ts.map +1 -0
  72. package/dist/services/musicbrainz/release-appearances.js +15 -0
  73. package/dist/services/musicbrainz/release-appearances.js.map +1 -0
  74. package/dist/services/musicbrainz/types.d.ts +13 -4
  75. package/dist/services/musicbrainz/types.d.ts.map +1 -1
  76. package/package.json +10 -9
  77. package/server.json +17 -3
  78. package/skills/musicbrainz-guide/SKILL.md +69 -0
  79. package/skills/musicbrainz-guide/references/query-syntax.md +23 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyanheads/musicbrainz-mcp-server",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "mcpName": "io.github.cyanheads/musicbrainz-mcp-server",
5
5
  "description": "Search artists, releases, recordings, works, and labels; traverse relationships; resolve ISRC/ISWC/barcode; fetch cover art via MCP. STDIO or Streamable HTTP.",
6
6
  "type": "module",
@@ -11,6 +11,7 @@
11
11
  },
12
12
  "files": [
13
13
  "changelog/",
14
+ "skills/",
14
15
  "dist/",
15
16
  "!dist/*.mcpb",
16
17
  "README.md",
@@ -81,7 +82,7 @@
81
82
  }
82
83
  ],
83
84
  "license": "Apache-2.0",
84
- "packageManager": "bun@1.4.3",
85
+ "packageManager": "bun@1.4.4",
85
86
  "engines": {
86
87
  "bun": ">=1.4.0",
87
88
  "node": ">=24.0.0"
@@ -90,18 +91,18 @@
90
91
  "access": "public"
91
92
  },
92
93
  "dependencies": {
93
- "@cyanheads/mcp-ts-core": "^0.13.15",
94
+ "@cyanheads/mcp-ts-core": "^0.13.18",
94
95
  "pino-pretty": "^13.2.0",
95
- "zod": "^4.6.5"
96
+ "zod": "^4.6.7"
96
97
  },
97
98
  "devDependencies": {
98
- "@biomejs/biome": "2.5.15",
99
+ "@biomejs/biome": "2.6.4",
99
100
  "@socketsecurity/bun-security-scanner": "^1.1.3",
100
- "@types/node": "26.6.5",
101
+ "@types/node": "26.6.6",
101
102
  "depcheck": "^1.4.7",
102
- "ignore": "^7.0.12",
103
- "tsc-alias": "^1.9.7",
103
+ "ignore": "^7.0.14",
104
+ "tsc-alias": "^1.9.10",
104
105
  "typescript": "^7.0.2",
105
- "vitest": "^5.0.3"
106
+ "vitest": "^5.0.5"
106
107
  }
107
108
  }
package/server.json CHANGED
@@ -6,7 +6,7 @@
6
6
  "url": "https://github.com/cyanheads/musicbrainz-mcp-server",
7
7
  "source": "github"
8
8
  },
9
- "version": "0.2.0",
9
+ "version": "0.3.0",
10
10
  "remotes": [
11
11
  {
12
12
  "type": "streamable-http",
@@ -19,8 +19,15 @@
19
19
  "registryBaseUrl": "https://registry.npmjs.org",
20
20
  "identifier": "@cyanheads/musicbrainz-mcp-server",
21
21
  "runtimeHint": "npx",
22
- "version": "0.2.0",
22
+ "version": "0.3.0",
23
23
  "environmentVariables": [
24
+ {
25
+ "name": "MUSICBRAINZ_CLAMP_OVERSIZED_LIMITS",
26
+ "description": "Clamp search/browse page limits above 100 with a notice; off restores maximum-100 validation.",
27
+ "format": "boolean",
28
+ "isRequired": false,
29
+ "default": "true"
30
+ },
24
31
  {
25
32
  "name": "MUSICBRAINZ_CONTACT",
26
33
  "description": "Contact (email or URL) embedded in the mandatory descriptive MusicBrainz User-Agent. Not start-blocking — the server ships a default contact — but operators running a shared or hosted instance should set their own so MusicBrainz can reach them about traffic.",
@@ -44,8 +51,15 @@
44
51
  "registryBaseUrl": "https://registry.npmjs.org",
45
52
  "identifier": "@cyanheads/musicbrainz-mcp-server",
46
53
  "runtimeHint": "npx",
47
- "version": "0.2.0",
54
+ "version": "0.3.0",
48
55
  "environmentVariables": [
56
+ {
57
+ "name": "MUSICBRAINZ_CLAMP_OVERSIZED_LIMITS",
58
+ "description": "Clamp search/browse page limits above 100 with a notice; off restores maximum-100 validation.",
59
+ "format": "boolean",
60
+ "isRequired": false,
61
+ "default": "true"
62
+ },
49
63
  {
50
64
  "name": "MCP_TRANSPORT_TYPE",
51
65
  "description": "Selects the HTTP transport.",
@@ -0,0 +1,69 @@
1
+ ---
2
+ name: musicbrainz-guide
3
+ description: Resolve music identities and follow musicbrainz_* tools across discographies, editions, tracklists, recordings, compositions, credits, and artwork. Use for multi-step music metadata research, ISRC/ISWC/barcode resolution, or MusicBrainz Lucene queries.
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: "cyanheads"
7
+ version: "1.0"
8
+ ---
9
+
10
+ ## Scope
11
+
12
+ Use MusicBrainz for music identities, discographies, edition metadata, credits, relationships, and Cover Art Archive image links. Access is keyless and read-only. Audio playback, audio fingerprint recognition, catalog editing, and licensing clearance are outside this server's surface.
13
+
14
+ ## Identifiers
15
+
16
+ Choose the entity before resolving its name:
17
+
18
+ | Entity | Represents | Where its MBID comes from |
19
+ |:---|:---|:---|
20
+ | Artist | A person, group, or other credited artist | Artist search, artist credits, relationship targets |
21
+ | Release-group | An album/single across its editions | Release-group search, artist discography, release's parent group |
22
+ | Release | A specific edition | Release search, group's editions, recording's appearances, barcode lookup |
23
+ | Recording | Recorded audio that can appear on multiple releases | Recording search, release track's recording link, ISRC lookup, work relationships |
24
+ | Work | A composition, including movements or arrangements | Work search, recording's work relationships, ISWC lookup |
25
+ | Label | A music label | Label search, release label information, relationship targets |
26
+
27
+ `musicbrainz_lookup_identifier` resolves ISRCs to recordings, ISWCs to works, and barcodes to releases. Keep each returned MBID's entity type attached to it; identical UUID syntax does not make types interchangeable. Preserve identifiers as strings, including leading zeros.
28
+
29
+ Area MBIDs come from an artist or label's returned `areaId`; names and country codes are not area MBIDs. IPI/ISNI identify people or organizations, while a work's society attributes identify that composition in a society's catalog.
30
+
31
+ ## Gates
32
+
33
+ 1. Confirm the intended identity before traversing: compare credited artist, disambiguation, dates, and edition evidence. A high search score or standard identifier can still yield several candidates; do not silently choose the first.
34
+ 2. Before saying “all” or “none,” establish coverage with the appropriate browse and continuation notices. Embedded discographies, editions, release appearances, and work recording relationships can be partial. A failed call or an unrequested relationship is not evidence of absence.
35
+ 3. Select a release edition before attributing its date, label, barcode, track order, or artwork to the user's copy. A release-group's first-release date and representative artwork describe the group, not every edition.
36
+ 4. Preserve relationship direction and attributes when reporting credits, movements, and arrangements. Browse supplies entity identities; obtain recording relationship details before making performance-specific claims.
37
+ 5. Report missing catalog facts as missing. Community metadata and external links do not establish current copyright ownership or permission to reuse an image or recording.
38
+
39
+ ## Core chain
40
+
41
+ Resolve a name with `musicbrainz_search_entities`, or a supplied standard identifier with `musicbrainz_lookup_identifier`. Check the candidates, then call the matching `musicbrainz_get_*` tool. Follow returned MBIDs and typed relationships for the next hop; use `musicbrainz_browse_entities` when the task needs the linked set rather than a detail preview.
42
+
43
+ ## Workflows
44
+
45
+ ### Discography and editions
46
+
47
+ For an artist's albums, resolve the artist, browse release-groups, and inspect primary and secondary types. “Album” alone does not establish a studio album: live albums and compilations can share that primary type. Missing secondary types mean unclassified metadata, so qualify uncertain classifications. Keep the applied filters when continuing; pipe-separated type filters do not universally mean “either,” so follow the tool's category semantics.
48
+
49
+ For a particular pressing, browse the group's releases, narrow candidates by country and date, then use `musicbrainz_get_release` to compare format, barcode, and catalog number with the user's evidence. Retrieve remaining media before reporting a complete tracklist. Recording enumeration cannot reconstruct ordered track occurrences, including repeated appearances of the same recording.
50
+
51
+ ### Track credits and compositions
52
+
53
+ For a named track on an edition, start from `musicbrainz_get_release` and use the track's own artist credit. A release credit such as “Various Artists” does not identify the performer of each track. Follow its recording MBID to `musicbrainz_get_recording` for performance relationships, then the work relationship to `musicbrainz_get_work` for writers/composers, ISWCs, movements, or arrangements. A recording credit does not replace a missing edition-specific track credit, and the work's writer is not automatically its performer.
54
+
55
+ For performances of a composition, resolve the work, browse its recordings, and retrieve recording details where the question needs performance dates or relationship attributes. For classical parts, follow work targets and retain ordering keys and direction; do not sort movements by title or treat an arrangement as the same work without checking the relationship.
56
+
57
+ For society registrations, inspect work attributes, then follow the writer/composer's artist MBID for IPI/ISNI. Preserve repeated society entries and their string values. These are catalog identifiers, not a determination of current ownership or licensing authority.
58
+
59
+ For labels or artists in an area, obtain `areaId` from a known artist or label and browse by that returned MBID. Check whether the associated area matches the user's requested geography; a birth area or country name is not a substitute for the requested area.
60
+
61
+ ### Artwork and external identities
62
+
63
+ Use `musicbrainz_get_cover_art` for the selected release's image URLs. Use group artwork only when representative artwork satisfies the task. Inspect full-archive availability and notices before treating an empty image page as no artwork.
64
+
65
+ Follow returned external links for cross-database identities. Keep the originating entity attached: an album group and one edition can link to different external records. Do not manufacture a Discogs identifier or Wikidata QID from a title match.
66
+
67
+ ## References
68
+
69
+ - [Lucene query syntax and entity-specific examples](references/query-syntax.md)
@@ -0,0 +1,23 @@
1
+ # MusicBrainz query syntax
2
+
3
+ Use these expressions with `musicbrainz_search_entities`. Choose the entity index first; fields differ by index.
4
+
5
+ - Quote phrases: `recording:"Bohemian Rhapsody"`.
6
+ - Write Boolean operators in uppercase and group alternatives: `artist:(Radiohead OR "Thom Yorke") AND recording:"Creep"`.
7
+ - Escape literal query punctuation with a backslash. Inside JSON, encode that backslash as `\\`; for example, a literal `+` becomes `\\+` in the JSON string.
8
+ - Start with a quoted title and credited artist; refine with a resolved artist MBID when names collide.
9
+
10
+ | Index | Example expression |
11
+ |:---|:---|
12
+ | Artist | `artist:"Björk" AND country:IS` |
13
+ | Release-group | `releasegroup:"OK Computer" AND primarytype:album` |
14
+ | Release | `release:"OK Computer" AND country:JP AND format:CD` |
15
+ | Recording | `recording:"Creep" AND arid:a74b1b7f-71a5-4011-9441-d0b5e4122711` |
16
+ | Work | `work:"Bohemian Rhapsody"` |
17
+ | Label | `label:"Warp" AND country:GB` |
18
+
19
+ `arid` is an artist MBID; `rgid` is a release-group MBID. Replace example IDs with the identity resolved for the task. Search `primarytype` and `secondarytype` are distinct fields; browse filters have their own schema and do not accept Lucene expressions. Recording `firstreleasedate` concerns earliest release, not recording-session time.
20
+
21
+ Search exposes at most the first 500 matches. Narrow broad queries; use browse for complete linked sets. `totalCount` can exceed the accessible search window.
22
+
23
+ Sources: [MusicBrainz indexed search and fields](https://musicbrainz.org/doc/Indexed_Search_Syntax), [search window](https://musicbrainz.org/doc/Search), and [Lucene Boolean grouping and escaping](https://lucene.apache.org/core/3_6_2/queryparsersyntax.html).