@cyanheads/musicbrainz-mcp-server 0.1.6 → 0.1.8

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 (61) hide show
  1. package/AGENTS.md +26 -15
  2. package/CLAUDE.md +26 -15
  3. package/README.md +83 -54
  4. package/changelog/0.1.x/0.1.7.md +24 -0
  5. package/changelog/0.1.x/0.1.8.md +20 -0
  6. package/changelog/template.md +9 -26
  7. package/dist/config/server-config.d.ts +6 -1
  8. package/dist/config/server-config.d.ts.map +1 -1
  9. package/dist/config/server-config.js +6 -17
  10. package/dist/config/server-config.js.map +1 -1
  11. package/dist/index.js +9 -0
  12. package/dist/index.js.map +1 -1
  13. package/dist/mcp-server/tools/definitions/_shared.d.ts +3 -2
  14. package/dist/mcp-server/tools/definitions/_shared.d.ts.map +1 -1
  15. package/dist/mcp-server/tools/definitions/_shared.js +4 -3
  16. package/dist/mcp-server/tools/definitions/_shared.js.map +1 -1
  17. package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts.map +1 -1
  18. package/dist/mcp-server/tools/definitions/get-artist.tool.js +10 -2
  19. package/dist/mcp-server/tools/definitions/get-artist.tool.js.map +1 -1
  20. package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts +11 -3
  21. package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts.map +1 -1
  22. package/dist/mcp-server/tools/definitions/get-cover-art.tool.js +65 -11
  23. package/dist/mcp-server/tools/definitions/get-cover-art.tool.js.map +1 -1
  24. package/dist/mcp-server/tools/definitions/get-label.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/get-label.tool.js +10 -2
  26. package/dist/mcp-server/tools/definitions/get-label.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts.map +1 -1
  28. package/dist/mcp-server/tools/definitions/get-recording.tool.js +10 -2
  29. package/dist/mcp-server/tools/definitions/get-recording.tool.js.map +1 -1
  30. package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts +10 -4
  31. package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts.map +1 -1
  32. package/dist/mcp-server/tools/definitions/get-release-group.tool.js +70 -13
  33. package/dist/mcp-server/tools/definitions/get-release-group.tool.js.map +1 -1
  34. package/dist/mcp-server/tools/definitions/get-release.tool.d.ts.map +1 -1
  35. package/dist/mcp-server/tools/definitions/get-release.tool.js +10 -2
  36. package/dist/mcp-server/tools/definitions/get-release.tool.js.map +1 -1
  37. package/dist/mcp-server/tools/definitions/get-work.tool.d.ts.map +1 -1
  38. package/dist/mcp-server/tools/definitions/get-work.tool.js +10 -2
  39. package/dist/mcp-server/tools/definitions/get-work.tool.js.map +1 -1
  40. package/dist/mcp-server/tools/definitions/index.d.ts +16 -6
  41. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  42. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts +2 -2
  43. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js +30 -16
  45. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts +7 -1
  47. package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map +1 -1
  48. package/dist/mcp-server/tools/definitions/search-entities.tool.js +17 -1
  49. package/dist/mcp-server/tools/definitions/search-entities.tool.js.map +1 -1
  50. package/dist/services/cover-art/cover-art-service.d.ts +24 -10
  51. package/dist/services/cover-art/cover-art-service.d.ts.map +1 -1
  52. package/dist/services/cover-art/cover-art-service.js +23 -14
  53. package/dist/services/cover-art/cover-art-service.js.map +1 -1
  54. package/dist/services/musicbrainz/musicbrainz-service.d.ts +3 -1
  55. package/dist/services/musicbrainz/musicbrainz-service.d.ts.map +1 -1
  56. package/dist/services/musicbrainz/musicbrainz-service.js +7 -3
  57. package/dist/services/musicbrainz/musicbrainz-service.js.map +1 -1
  58. package/dist/services/musicbrainz/types.d.ts +16 -3
  59. package/dist/services/musicbrainz/types.d.ts.map +1 -1
  60. package/package.json +10 -9
  61. package/server.json +3 -3
package/AGENTS.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** musicbrainz-mcp-server
4
- **Version:** 0.1.6
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
- **Engines:** Bun ≥1.3.0, Node ≥24.0.0
4
+ **Version:** 0.1.8
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.6`
6
+ **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
8
- **Zod:** ^4.4.3
8
+ **Zod:** ^4.6.5
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
11
11
 
@@ -199,6 +199,7 @@ await createApp({
199
199
  tools: allToolDefinitions,
200
200
  resources: allResourceDefinitions,
201
201
  prompts: [],
202
+ sessionMode: 'stateless',
202
203
  instructions:
203
204
  'Entities are addressed by MBID (a UUID); from a name, call musicbrainz_search_entities first and chain the MBID into the matching musicbrainz_get_* tool. The get_* tools embed at most one page (25) of any linked list — use musicbrainz_browse_entities for the complete set. Rate-limited to ~1 request/second against MusicBrainz.',
204
205
  setup(core) {
@@ -208,6 +209,8 @@ await createApp({
208
209
  });
209
210
  ```
210
211
 
212
+ `sessionMode: 'stateless'` declares the HTTP session posture in code, so it holds however the process is launched instead of depending on a deployment env var (`MCP_SESSION_MODE` still overrides when set). Nothing here is per-session: no tool gates on `ctx.requestInput`, and the response cache uses `ctx.state` — tenant-scoped storage, not the session store — so it is unaffected. `require: 'stateful'` would be the declaration for a server whose tools do gate on `ctx.requestInput`; this one has none. No `teardown` hook: neither service allocates a watcher, socket, or ref'd timer in `setup()`, and neither exposes a `shutdown()`.
213
+
211
214
  The in-code identity block is `name` + `title` only, both exactly `musicbrainz-mcp-server`. `description` is **not** passed to `createApp()` — the framework derives the served description from `package.json` (the canonical source). `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, scope hints, the rate-limit note) instead of repeating the same context across tool descriptions.
212
215
 
213
216
  ---
@@ -234,7 +237,7 @@ Handlers receive a unified `ctx` object. Key properties:
234
237
 
235
238
  Handlers throw — the framework catches, classifies, and formats.
236
239
 
237
- **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
240
+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated). Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`): spread `...ctx.recoveryFor('reason')` into the throw's data argument to put it on the wire as `data.recovery.hint` (mirrored into `content[]` text unless the message already contains it verbatim), or pass an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it; prefer it over moving a handler's literal `ctx.fail` out of scan range, which silences the rule for the whole definition. `severity` (`debug` | `info` | `notice` | `warning`) lowers that one reason's log level without touching the wire envelope or the `mcp.tool.*` counters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
238
241
 
239
242
  ```ts
240
243
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -287,7 +290,7 @@ src/
287
290
  rate-limiter.ts # Process-wide ~1 req/sec token bucket
288
291
  types.ts # Raw/domain entity types
289
292
  cover-art/
290
- cover-art-service.ts # Cover Art Archive client — 404 → empty set, follows 307
293
+ cover-art-service.ts # Cover Art Archive client — 404 → empty set (found:false), follows 307
291
294
  mcp-server/
292
295
  tools/definitions/
293
296
  search-entities.tool.ts # musicbrainz_search_entities (the entry point)
@@ -320,9 +323,9 @@ No `prompts/` directory — this server registers no prompts.
320
323
 
321
324
  ## Skills
322
325
 
323
- Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
326
+ Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
324
327
 
325
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
328
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
326
329
 
327
330
  Available skills:
328
331
 
@@ -341,8 +344,9 @@ Available skills:
341
344
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
342
345
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
343
346
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
344
- | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
345
- | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
347
+ | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
348
+ | `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
349
+ | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
346
350
  | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
347
351
  | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
348
352
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
@@ -361,7 +365,7 @@ Available skills:
361
365
  | `api-workers` | Cloudflare Workers runtime |
362
366
  | `techniques` | Cross-cutting implementation techniques and recipes for the framework |
363
367
 
364
- **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
368
+ **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
365
369
 
366
370
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
367
371
 
@@ -377,9 +381,10 @@ When you complete a skill's checklist, check the boxes and add a completion time
377
381
  | `bun run rebuild` | Clean + build |
378
382
  | `bun run clean` | Remove build artifacts |
379
383
  | `bun run devcheck` | Lint + format + typecheck + security + packaging + changelog sync |
380
- | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
384
+ | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
385
+ | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
381
386
  | `bun run tree` | Generate `docs/tree.md` directory structure doc |
382
- | `bun run list-skills` | List the skills available in `.claude/skills/` |
387
+ | `bun run list-skills` | List the skills available in `.claude/skills/` (falling back to `framework-skills/`) |
383
388
  | `bun run format` | Auto-fix formatting (safe fixes only) |
384
389
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
385
390
  | `bun run lint:mcp` | Validate MCP tool/resource definitions against the linter rules |
@@ -400,7 +405,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
400
405
 
401
406
  **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
402
407
 
403
- **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
408
+ **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
404
409
 
405
410
  ---
406
411
 
@@ -425,12 +430,18 @@ security: false # optional — true only for this pro
425
430
 
426
431
  `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
427
432
 
428
- **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
433
+ **Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
429
434
 
430
435
  **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
431
436
 
432
437
  ---
433
438
 
439
+ ## Publishing
440
+
441
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
442
+
443
+ ---
444
+
434
445
  ## Imports
435
446
 
436
447
  ```ts
package/CLAUDE.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** musicbrainz-mcp-server
4
- **Version:** 0.1.6
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
- **Engines:** Bun ≥1.3.0, Node ≥24.0.0
4
+ **Version:** 0.1.8
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.6`
6
+ **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
8
- **Zod:** ^4.4.3
8
+ **Zod:** ^4.6.5
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
11
11
 
@@ -199,6 +199,7 @@ await createApp({
199
199
  tools: allToolDefinitions,
200
200
  resources: allResourceDefinitions,
201
201
  prompts: [],
202
+ sessionMode: 'stateless',
202
203
  instructions:
203
204
  'Entities are addressed by MBID (a UUID); from a name, call musicbrainz_search_entities first and chain the MBID into the matching musicbrainz_get_* tool. The get_* tools embed at most one page (25) of any linked list — use musicbrainz_browse_entities for the complete set. Rate-limited to ~1 request/second against MusicBrainz.',
204
205
  setup(core) {
@@ -208,6 +209,8 @@ await createApp({
208
209
  });
209
210
  ```
210
211
 
212
+ `sessionMode: 'stateless'` declares the HTTP session posture in code, so it holds however the process is launched instead of depending on a deployment env var (`MCP_SESSION_MODE` still overrides when set). Nothing here is per-session: no tool gates on `ctx.requestInput`, and the response cache uses `ctx.state` — tenant-scoped storage, not the session store — so it is unaffected. `require: 'stateful'` would be the declaration for a server whose tools do gate on `ctx.requestInput`; this one has none. No `teardown` hook: neither service allocates a watcher, socket, or ref'd timer in `setup()`, and neither exposes a `shutdown()`.
213
+
211
214
  The in-code identity block is `name` + `title` only, both exactly `musicbrainz-mcp-server`. `description` is **not** passed to `createApp()` — the framework derives the served description from `package.json` (the canonical source). `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, scope hints, the rate-limit note) instead of repeating the same context across tool descriptions.
212
215
 
213
216
  ---
@@ -234,7 +237,7 @@ Handlers receive a unified `ctx` object. Key properties:
234
237
 
235
238
  Handlers throw — the framework catches, classifies, and formats.
236
239
 
237
- **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
240
+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated). Forwarding it is lint-enforced per throw site (`error-contract-recovery-unforwarded`): spread `...ctx.recoveryFor('reason')` into the throw's data argument to put it on the wire as `data.recovery.hint` (mirrored into `content[]` text unless the message already contains it verbatim), or pass an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it; prefer it over moving a handler's literal `ctx.fail` out of scan range, which silences the rule for the whole definition. `severity` (`debug` | `info` | `notice` | `warning`) lowers that one reason's log level without touching the wire envelope or the `mcp.tool.*` counters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
238
241
 
239
242
  ```ts
240
243
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -287,7 +290,7 @@ src/
287
290
  rate-limiter.ts # Process-wide ~1 req/sec token bucket
288
291
  types.ts # Raw/domain entity types
289
292
  cover-art/
290
- cover-art-service.ts # Cover Art Archive client — 404 → empty set, follows 307
293
+ cover-art-service.ts # Cover Art Archive client — 404 → empty set (found:false), follows 307
291
294
  mcp-server/
292
295
  tools/definitions/
293
296
  search-entities.tool.ts # musicbrainz_search_entities (the entry point)
@@ -320,9 +323,9 @@ No `prompts/` directory — this server registers no prompts.
320
323
 
321
324
  ## Skills
322
325
 
323
- Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
326
+ Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
324
327
 
325
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
328
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
326
329
 
327
330
  Available skills:
328
331
 
@@ -341,8 +344,9 @@ Available skills:
341
344
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
342
345
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
343
346
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
344
- | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
345
- | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
347
+ | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
348
+ | `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
349
+ | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
346
350
  | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
347
351
  | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
348
352
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
@@ -361,7 +365,7 @@ Available skills:
361
365
  | `api-workers` | Cloudflare Workers runtime |
362
366
  | `techniques` | Cross-cutting implementation techniques and recipes for the framework |
363
367
 
364
- **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
368
+ **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
365
369
 
366
370
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
367
371
 
@@ -377,9 +381,10 @@ When you complete a skill's checklist, check the boxes and add a completion time
377
381
  | `bun run rebuild` | Clean + build |
378
382
  | `bun run clean` | Remove build artifacts |
379
383
  | `bun run devcheck` | Lint + format + typecheck + security + packaging + changelog sync |
380
- | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
384
+ | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
385
+ | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
381
386
  | `bun run tree` | Generate `docs/tree.md` directory structure doc |
382
- | `bun run list-skills` | List the skills available in `.claude/skills/` |
387
+ | `bun run list-skills` | List the skills available in `.claude/skills/` (falling back to `framework-skills/`) |
383
388
  | `bun run format` | Auto-fix formatting (safe fixes only) |
384
389
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
385
390
  | `bun run lint:mcp` | Validate MCP tool/resource definitions against the linter rules |
@@ -400,7 +405,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
400
405
 
401
406
  **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
402
407
 
403
- **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
408
+ **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
404
409
 
405
410
  ---
406
411
 
@@ -425,12 +430,18 @@ security: false # optional — true only for this pro
425
430
 
426
431
  `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
427
432
 
428
- **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
433
+ **Section order:** the Keep a Changelog sequence — Added, Changed, Deprecated, Removed, Fixed, Security — then `Dependencies` last. Include only sections with entries — don't ship empty headers.
429
434
 
430
435
  **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
431
436
 
432
437
  ---
433
438
 
439
+ ## Publishing
440
+
441
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
442
+
443
+ ---
444
+
434
445
  ## Imports
435
446
 
436
447
  ```ts
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-0.1.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.1.8-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -31,49 +31,65 @@
31
31
 
32
32
  ---
33
33
 
34
- ## Tools
34
+ ## Overview
35
35
 
36
- Ten read-only tools mapping the three MusicBrainz access modes — **search** when you have text, **lookup** (`get_*` and `lookup_identifier`) when you hold an MBID or standard identifier, and **browse** when you need the complete linked set beyond the single page that lookup folds in:
36
+ Open music metadata over the live MusicBrainz Web Service v2 and the Cover Art Archive. Search by name, look up entities by MBID or a standard identifier (ISRC/ISWC/barcode), browse the complete linked set beyond what the lookup tools embed, and fetch cover art from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
37
+
38
+ ### Tools
37
39
 
38
40
  | Tool | Description |
39
41
  |:---|:---|
40
- | `musicbrainz_search_entities` | Full-text Lucene search across an entity type (artist, release-group, release, recording, work, label). Returns ranked matches with MBID and a 0–100 relevance score. The first step when starting from a name. |
41
- | `musicbrainz_get_artist` | Artist profile by MBID — type, country, life span, aliases, tags/genres, discography (release-groups), band-membership relationships, and external links. |
42
- | `musicbrainz_get_release_group` | Release-group ("the album" above specific pressings) by MBID — primary/secondary type, first-release date, artist credit, editions, and a cover-art availability flag. |
43
- | `musicbrainz_get_release` | One edition's full detail by MBID — tracklist (media → tracks → recordings), label + catalog number, barcode, packaging, and a cover-art stub. |
44
- | `musicbrainz_get_recording` | Recording (a specific performance/track) by MBID — length, artist credits, ISRCs, the releases it appears on, the work(s) it performs, and performance/production relationships. |
45
- | `musicbrainz_get_work` | Work (a composition, distinct from any recording) by MBID — type, languages, ISWCs, writer/composer relationships, and the recordings that perform it. |
46
- | `musicbrainz_get_label` | Label by MBID — type, country, life span, label code, area, aliases, tags, and external links. |
47
- | `musicbrainz_lookup_identifier` | Resolve a standard identifier without a name search — ISRC → recordings, ISWC → works, barcode → releases. Output is discriminated on the resolved entity type. |
48
- | `musicbrainz_browse_entities` | Paginate the complete set of entities linked to a parent MBID — every release on a label, every release-group by an artist, every recording of a work. The only complete-enumeration path. |
49
- | `musicbrainz_get_cover_art` | Cover Art Archive images for a release or release-group MBID — front/back flags, image types, full-resolution URLs, and 250/500/1200px thumbnails. No art returns an empty set, not an error. |
42
+ | `musicbrainz_search_entities` | Full-text Lucene search across a MusicBrainz entity type. Returns ranked matches with MBID and a relevance score. |
43
+ | `musicbrainz_get_artist` | Artist profile by MBID — type, life span, discography, relationships, external links. |
44
+ | `musicbrainz_get_release_group` | Release-group ("the album" above specific pressings) by MBID — type, first-release date, editions, cover-art availability. |
45
+ | `musicbrainz_get_release` | One edition's full detail by MBID — tracklist, label, catalog number, barcode, packaging. |
46
+ | `musicbrainz_get_recording` | Recording (a specific performance) by MBID — length, ISRCs, releases it appears on, performance relationships. |
47
+ | `musicbrainz_get_work` | Work (a composition) by MBID — type, ISWCs, writer relationships, performing recordings. |
48
+ | `musicbrainz_get_label` | Label by MBID — type, life span, label code, external links. |
49
+ | `musicbrainz_lookup_identifier` | Resolve an ISRC, ISWC, or barcode directly to recordings, works, or releases. |
50
+ | `musicbrainz_browse_entities` | Paginate the complete set of entities linked to a parent MBID — the only complete-enumeration path. |
51
+ | `musicbrainz_get_cover_art` | Cover Art Archive images for a release or release-group MBID. |
52
+
53
+ ### Resources
54
+
55
+ | Resource | Description |
56
+ |:---|:---|
57
+ | `musicbrainz://{entity_type}/{mbid}` | A single MusicBrainz entity by type and MBID, with default linked sub-resources folded in. |
50
58
 
51
- ### `musicbrainz_search_entities`
59
+ All entity data is also reachable via the `get_*` tools, so tool-only clients lose nothing. There is no resource `list()` — the corpus is millions of entities; discovery is via `musicbrainz_search_entities`.
52
60
 
53
- Resolve a name to an MBID with full-text Lucene search.
61
+ ## Capability reference
62
+
63
+ ### `musicbrainz_search_entities` <sub>tool</sub>
54
64
 
55
65
  - Searches one entity type per call: artist, release-group, release, recording, work, or label
56
66
  - Field-scoped Lucene syntax (e.g. `artist:radiohead AND country:GB`)
57
67
  - Surfaces the raw 0–100 relevance `score` per hit (100 = exact); results stay in MusicBrainz score-descending order, not re-ranked
58
68
  - Type-specific fields appear only for the relevant entity (ISRCs on recordings, ISWCs on works, artist credit on release-groups/releases/recordings)
59
- - Pagination via `limit` (1–100) and `offset`; echoes the effective query and the true upstream total
69
+ - Pagination via `limit` (1–100, default 25) and `offset`; echoes the effective query and the true upstream total
70
+ - A whitespace-only query fails locally as `blank_query` with a recovery hint; everything else goes upstream exactly as sent, incidental whitespace included
60
71
 
61
72
  ---
62
73
 
63
- ### `musicbrainz_get_artist`
64
-
65
- The 80% artist-detail call.
74
+ ### `musicbrainz_get_artist` <sub>tool</sub>
66
75
 
67
76
  - Folds discography (release-groups), band-membership / collaboration relationships, aliases, and tags/genres into one request via `inc`
68
77
  - External links (Wikidata QID, Discogs, official site) surface as `url-rels` — chainable to `wikidata-mcp-server` and friends; this server does not chase them itself
69
- - `inc_release_groups` and `inc_relationships` toggle the expensive sub-resources
78
+ - `inc_release_groups` and `inc_relationships` (both default `true`) toggle the expensive sub-resources
70
79
  - Discography and relationships are capped at one page (25); for a prolific artist's complete release-group list, use `musicbrainz_browse_entities` (`target_type=release-group`, artist link)
71
80
 
72
81
  ---
73
82
 
74
- ### `musicbrainz_get_release`
83
+ ### `musicbrainz_get_release_group` <sub>tool</sub>
75
84
 
76
- One edition's full detail, the level with an actual tracklist.
85
+ - Primary type (Album, Single, EP, Broadcast, Other) and secondary types (Live, Compilation, Soundtrack, …), first-release date, and the artist credit (array plus a display string)
86
+ - Embedded releases (editions) capped at one page (25); `musicbrainz_browse_entities` (`target_type=release`, `link.release-group`) gives the complete set
87
+ - Cover-art availability (image count, front/back) comes from the Cover Art Archive — the art `musicbrainz_get_cover_art` returns for the same MBID — looked up alongside the MusicBrainz record; when that lookup fails the field is omitted with a notice rather than reported as "no art"
88
+ - Chain a listed release MBID into `musicbrainz_get_release` for its tracklist
89
+
90
+ ---
91
+
92
+ ### `musicbrainz_get_release` <sub>tool</sub>
77
93
 
78
94
  - Tracklist as media → tracks → recordings, each with length and recording MBID (lengths rendered `m:ss`, stored as milliseconds upstream)
79
95
  - Label + catalog number, barcode, country, release date, format, packaging, and text representation (language/script)
@@ -81,56 +97,67 @@ One edition's full detail, the level with an actual tracklist.
81
97
 
82
98
  ---
83
99
 
84
- ### `musicbrainz_lookup_identifier`
100
+ ### `musicbrainz_get_recording` <sub>tool</sub>
101
+
102
+ - Length (rendered `m:ss`), ISRCs, artist credits, and the releases it appears on
103
+ - `inc_relationships` (default `true`) toggles performance/production relationships (performer, producer, engineer — each with role and credited-artist MBID) and work-rels linking to the underlying composition
104
+ - External links (url-rels) surface alongside relationships when included
105
+
106
+ ---
107
+
108
+ ### `musicbrainz_get_work` <sub>tool</sub>
109
+
110
+ - Type, ISWCs, lyrics languages, aliases, and tags/genres
111
+ - `inc_relationships` (default `true`) toggles writer/composer/lyricist relationships, recording-rels (the recordings that perform it), and external links
112
+ - Recording relationships are returned in full — the work lookup is the one `get_*` tool with no per-page cap
113
+
114
+ ---
115
+
116
+ ### `musicbrainz_get_label` <sub>tool</sub>
85
117
 
86
- The deterministic path when you already hold a standard identifier — no name search.
118
+ - Type, country, life span, label code (the LC number), area, aliases, tags, and external links
119
+ - Releases are NOT embedded — a major label can have tens of thousands; enumerate them with `musicbrainz_browse_entities` (`target_type=release`, `link.label`)
120
+
121
+ ---
122
+
123
+ ### `musicbrainz_lookup_identifier` <sub>tool</sub>
87
124
 
88
125
  - `id_type=isrc` → recordings (a recording-level code, often shared by several recordings)
89
126
  - `id_type=iswc` → works (a composition-level code)
90
- - `id_type=barcode` → releases (UPC/EAN)
127
+ - `id_type=barcode` → releases (UPC/EAN digits; spaces and hyphens are ignored, anything else is rejected as `invalid_identifier`)
91
128
  - ISRC and ISWC hit dedicated exact endpoints; barcode is a Lucene search filter, so its results are ranked (exact match scores 100)
92
- - The output `kind` field tells you which entity type came back
129
+ - The output `kind` field discriminates which entity type came back (recordings | works | releases)
93
130
 
94
131
  ---
95
132
 
96
- ### `musicbrainz_browse_entities`
97
-
98
- The complete-enumeration path — a correctness tool, not just convenience.
133
+ ### `musicbrainz_browse_entities` <sub>tool</sub>
99
134
 
100
135
  - Paginates the full linked set: every release-group by an artist, every release on a label, every recording of a work, every release in a release-group
101
- - Pages arbitrarily deep via `offset`; `totalCount` is the true upstream total
136
+ - Page size `limit` (1–100, default 25); pages arbitrarily deep via `offset`, and `totalCount` is the true upstream total
102
137
  - Use it whenever a linked set may exceed a page — the `get_*` tools embed at most one page (25), and a partial list read as complete is a silent correctness gap
103
138
  - Provide exactly one `link` MBID matching a valid parent→child relationship for the `target_type`
104
139
 
105
140
  ---
106
141
 
107
- ### `musicbrainz_get_cover_art`
108
-
109
- Cover Art Archive images, kept separate from the release record.
142
+ ### `musicbrainz_get_cover_art` <sub>tool</sub>
110
143
 
111
144
  - Front/back flags, image types, full-resolution URLs, and 250/500/1200px thumbnail URLs
112
145
  - Returns an empty image set (not an error) when the entity has no art — absence of art is information
113
- - Art is served at the release level; a release-group MBID resolves to a representative release's art automatically
146
+ - The archive answers the same 404 for "no art" and for an MBID it has no record of, so that case is checked against MusicBrainz first: a malformed or all-zeros MBID fails as `invalid_mbid`, one matching no release/release-group as `entity_not_found`, and an unreachable check returns the empty set with its existence flagged unconfirmed
147
+ - Art is served at the release level; `entity_type` defaults to `release`, and a release-group MBID resolves to a representative release's art automatically
114
148
  - Image URLs are linked, never rehosted — image copyright stays with the rights holders (only the MusicBrainz core metadata is CC0)
115
149
 
116
- ## Resources
150
+ ---
117
151
 
118
- | Type | Name | Description |
119
- |:---|:---|:---|
120
- | Resource | `musicbrainz://{entity_type}/{mbid}` | A single MusicBrainz entity by type and MBID, with default linked sub-resources folded in. Mirrors the matching `musicbrainz_get_*` tool. `entity_type` ∈ artist, release-group, release, recording, work, label. |
152
+ ### `musicbrainz://{entity_type}/{mbid}` <sub>resource</sub>
121
153
 
122
- All entity data is also reachable via the `get_*` tools, so tool-only clients (the majority) lose nothing. There is no resource `list()` — the corpus is millions of entities; discovery is via `musicbrainz_search_entities`, not resource enumeration.
154
+ - Mirrors the matching `musicbrainz_get_*` tool with the same default `inc` sets, returned as the raw MusicBrainz JSON record
155
+ - `entity_type` ∈ artist, release-group, release, recording, work, label
156
+ - Embedded linked lists are capped at one page, same as the lookup tools — use `musicbrainz_browse_entities` for the complete set
123
157
 
124
158
  ## Features
125
159
 
126
- Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
127
-
128
- - Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
129
- - Unified error handling — handlers throw, framework catches, classifies, and formats
130
- - Pluggable auth: `none`, `jwt`, `oauth`
131
- - Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
132
- - Structured logging with optional OpenTelemetry tracing
133
- - STDIO and Streamable HTTP transports
160
+ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
134
161
 
135
162
  MusicBrainz-specific:
136
163
 
@@ -166,6 +193,8 @@ A public instance is available at `https://musicbrainz.caseyjhand.com/mcp` — n
166
193
  }
167
194
  ```
168
195
 
196
+ ### Self-Hosted / Local
197
+
169
198
  Add the following to your MCP client configuration file.
170
199
 
171
200
  ```json
@@ -285,11 +314,7 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
285
314
 
286
315
  ### Rate limit and User-Agent
287
316
 
288
- MusicBrainz enforces a **~1 request/second** average rate limit per IP across the whole hosted instance and **blocks requests without a descriptive `User-Agent`** that identifies the application and a contact. This server satisfies both: it sends `musicbrainz-mcp-server/<version> (<contact>)` as the `User-Agent` and serializes all upstream calls through a process-wide token-bucket limiter, with response caching to keep repeat lookups off the wire. On a shared or hosted instance every client shares the one limiter, so bulk enumeration via `musicbrainz_browse_entities` paces accordingly. Set `MUSICBRAINZ_CONTACT` to your own email or URL when you deploy.
289
-
290
- ### Attribution and licensing
291
-
292
- MusicBrainz core entity data is released under **CC0** (public-domain dedication) — see the [MusicBrainz license](https://musicbrainz.org/doc/About/Data_License). This server stays on that core metadata and does not fetch annotation text (which carries a different, non-CC0 license). Cover art is served by the [Cover Art Archive](https://coverartarchive.org/), a joint project of MusicBrainz and the Internet Archive; image URLs are linked, never rehosted, and each image's copyright stays with its rights holders. Cite MusicBrainz and the Cover Art Archive in downstream use.
317
+ MusicBrainz blocks requests without a descriptive `User-Agent` identifying the application and a contact. This server sends `musicbrainz-mcp-server/<version> (<contact>)`, where `<contact>` is `MUSICBRAINZ_CONTACT` — set it to your own email or URL when you deploy. Upstream calls serialize through one process-wide limiter, so on a shared or hosted instance every client draws on the same ~1 req/sec budget and bulk enumeration via `musicbrainz_browse_entities` paces accordingly.
293
318
 
294
319
  ## Running the server
295
320
 
@@ -331,7 +356,7 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
331
356
  | `src/index.ts` | `createApp()` entry point — registers tools and the resource, inits both services. |
332
357
  | `src/config` | Server-specific environment variable parsing and validation with Zod. |
333
358
  | `src/services/musicbrainz` | MusicBrainz WS/2 client — User-Agent, rate limiter, response cache, retry, and domain types. |
334
- | `src/services/cover-art` | Cover Art Archive client — maps 404 to an empty image set, follows the release-group redirect. |
359
+ | `src/services/cover-art` | Cover Art Archive client — maps 404 to an empty image set flagged as not found, follows the release-group redirect. |
335
360
  | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Ten read-only tools across search, lookup, browse, and cover art. |
336
361
  | `src/mcp-server/resources` | Resource definitions. The `musicbrainz://{entity_type}/{mbid}` entity mirror. |
337
362
  | `tests/` | Unit and integration tests mirroring `src/`. |
@@ -346,9 +371,13 @@ See [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md) for development guidelines and archit
346
371
  - All upstream calls route through the services — never `fetch()` MusicBrainz directly, or you bypass the User-Agent, rate limiter, and cache
347
372
  - Wrap external API data: validate raw → normalize to domain type → return output schema; never fabricate missing fields
348
373
 
374
+ ## Attribution and licensing
375
+
376
+ MusicBrainz core entity data is released under **CC0** (public-domain dedication) — see the [MusicBrainz license](https://musicbrainz.org/doc/About/Data_License). This server stays on that core metadata and does not fetch annotation text (which carries a different, non-CC0 license). Cover art is served by the [Cover Art Archive](https://coverartarchive.org/), a joint project of MusicBrainz and the Internet Archive; image URLs are linked, never rehosted, and each image's copyright stays with its rights holders. Cite MusicBrainz and the Cover Art Archive in downstream use.
377
+
349
378
  ## Contributing
350
379
 
351
- Issues and pull requests are welcome. Run checks and tests before submitting:
380
+ Issues are welcome. Run checks and tests before submitting:
352
381
 
353
382
  ```sh
354
383
  bun run devcheck
@@ -0,0 +1,24 @@
1
+ ---
2
+ summary: "Adopt mcp-ts-core ^0.13.6 (InvalidParams argument rejections, recovery hints, error.data URL redaction), declare stateless session mode (#13), and refresh README, plugin metadata, and skill tooling."
3
+ breaking: true
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.7 — 2026-09-20
8
+
9
+ ## Added
10
+
11
+ - **`sessionMode: 'stateless'`** declared in `createApp()` ([#13](https://github.com/cyanheads/musicbrainz-mcp-server/issues/13)) — the HTTP session posture now holds however the process is launched, rather than depending on a deployment env var; `.env.example` restates it.
12
+
13
+ ## Changed
14
+
15
+ - **`@cyanheads/mcp-ts-core` `^0.12.3` → `^0.13.6`** — tool argument rejections now classify as `InvalidParams` (`-32602`) with a `reason` and a schema-derived recovery hint instead of `ValidationError`; tool error text closes with a `(reason … · not retryable)` clause; the upstream request URL no longer lands on client-facing `error.data` by default.
16
+ - **README reorganized** around a capability-reference structure; `.claude-plugin/plugin.json` gains `$schema` and `keywords`, and `manifest.json` author identity syncs to `cyanheads`.
17
+ - Framework skill tree moved from `skills/` to `framework-skills/` — Claude Code and Codex auto-load a plugin's root `skills/`, which was surfacing development-only skills to every installing agent. CodeQL static analysis workflow added.
18
+
19
+ ## Dependencies
20
+
21
+ - `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.13.6`
22
+ - `zod` `^4.4.3` → `^4.6.5`
23
+ - `@biomejs/biome` `2.5.9` → `2.5.14`, `@types/node` `26.2.0` → `26.6.1`, `ignore` `^7.0.6` → `^7.0.9`, `tsc-alias` `^1.9.2` → `^1.9.5`
24
+ - Bun engine floor `>=1.3.0` → `>=1.4.0`
@@ -0,0 +1,20 @@
1
+ ---
2
+ summary: "Cover-art availability now resolves through the Cover Art Archive, with typed rejections for blank search queries and malformed barcodes."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.8 — 2026-09-22
8
+
9
+ ## Fixed
10
+
11
+ - **`musicbrainz_get_cover_art`** verifies an unknown MBID against MusicBrainz on a Cover Art Archive 404 ([#6](https://github.com/cyanheads/musicbrainz-mcp-server/issues/6)) — the archive answers the same 404 for a real entity with no art and for one it has no record of; the tool now returns `invalid_mbid`, `entity_not_found`, or the genuine no-art success. An unreachable check keeps the no-art success with existence flagged unconfirmed.
12
+ - **`musicbrainz_search_entities`** rejects a whitespace-only `query` locally as `blank_query` ([#7](https://github.com/cyanheads/musicbrainz-mcp-server/issues/7)) instead of forwarding it upstream for a generic 400.
13
+ - **`musicbrainz_get_release_group`**'s `coverArt` now comes from the Cover Art Archive ([#8](https://github.com/cyanheads/musicbrainz-mcp-server/issues/8)) — WS/2 carries no `cover-art-archive` stub at the release-group level. The lookup runs concurrently with the WS/2 lookup, bounded; a failed lookup omits `coverArt` with a notice instead of reporting `exists: false`.
14
+ - **`musicbrainz_lookup_identifier`** accepts only digits for a barcode ([#9](https://github.com/cyanheads/musicbrainz-mcp-server/issues/9)) — spaces and hyphens are stripped first, anything else (including a Lucene wildcard) is rejected as `invalid_identifier` before the search call.
15
+ - Typed error contracts on the six MBID `get_*` tools now branch on literal reasons ([#14](https://github.com/cyanheads/musicbrainz-mcp-server/issues/14)) so the error-contract lint rules can verify them; behavior is unchanged.
16
+
17
+ ## Dependencies
18
+
19
+ - `vitest` `^4.1.11` → `^5.0.1`
20
+ - `@types/node` `26.6.1` → `26.6.2`
@@ -6,8 +6,8 @@
6
6
 
7
7
  # Required. One-line GitHub Release-style headline. 350 character cap — a
8
8
  # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
9
- # unrelated changes with commas/semicolons into an inventory — pick the
10
- # headline, like a tag's theme line. Quotes required: unquoted YAML treats
9
+ # unrelated changes with commas/semicolons into an inventory — pick the one
10
+ # headline the release is about. Quotes required: unquoted YAML treats
11
11
  # `: ` inside the value as a key separator and fails GitHub's strict parser.
12
12
  summary: ""
13
13
 
@@ -117,30 +117,13 @@ security: false
117
117
  in that unrelated item's metadata.
118
118
 
119
119
  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
120
- via `gh release create --notes-from-tag`. The tag is a derivative of this
121
- changelog entry — a condensed, scannable version, not a copy. Format:
122
-
123
- <theme — omit version number, GitHub prepends it>
124
- ← blank line
125
- <1-2 sentence context: what this release does>
126
- ← blank line
127
- Dependency bumps: ← section header
128
- ← blank line
129
- - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6 ← bullet
130
- ← blank line
131
- Changed: ← only sections with entries
132
- ← blank line
133
- - `format()` output includes `query` in text mode
134
- ← blank line
135
- Added:
136
- ← blank line
137
- - `manifest.json` scaffolded for MCPB bundle support
138
- - Install badges (Claude Desktop, Cursor, VS Code)
139
- ← blank line
140
- <N> tests pass; `bun run devcheck` clean. ← footer
141
-
142
- Never a flat comma-separated string. Always structured markdown with
143
- sections. The tag must scan well as a rendered GitHub Release page.
120
+ via `gh release create --notes-from-tag`. It is a condensed digest of this
121
+ entry, never a copy, and its format is owned by the `release-and-publish`
122
+ skill (step 4, "Create the annotated tag"): a short subject line without the
123
+ version, flat headline bullets — no Keep-a-Changelog section headers, no
124
+ gates line — at most one deps line, issue backlinks, and the changelog link
125
+ last. In release-PR mode the `git-wrapup` skill authors those bullets as the
126
+ PR body's `## Changes` and the tag copies them.
144
127
  -->
145
128
 
146
129
  ## Added