@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.
- package/AGENTS.md +26 -15
- package/CLAUDE.md +26 -15
- package/README.md +83 -54
- package/changelog/0.1.x/0.1.7.md +24 -0
- package/changelog/0.1.x/0.1.8.md +20 -0
- package/changelog/template.md +9 -26
- package/dist/config/server-config.d.ts +6 -1
- package/dist/config/server-config.d.ts.map +1 -1
- package/dist/config/server-config.js +6 -17
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +9 -0
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/_shared.d.ts +3 -2
- package/dist/mcp-server/tools/definitions/_shared.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/_shared.js +4 -3
- package/dist/mcp-server/tools/definitions/_shared.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-artist.tool.js +10 -2
- package/dist/mcp-server/tools/definitions/get-artist.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts +11 -3
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.js +65 -11
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-label.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-label.tool.js +10 -2
- package/dist/mcp-server/tools/definitions/get-label.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-recording.tool.js +10 -2
- package/dist/mcp-server/tools/definitions/get-recording.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts +10 -4
- package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-release-group.tool.js +70 -13
- package/dist/mcp-server/tools/definitions/get-release-group.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-release.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-release.tool.js +10 -2
- package/dist/mcp-server/tools/definitions/get-release.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-work.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-work.tool.js +10 -2
- package/dist/mcp-server/tools/definitions/get-work.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +16 -6
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js +30 -16
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts +7 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.js +17 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.js.map +1 -1
- package/dist/services/cover-art/cover-art-service.d.ts +24 -10
- package/dist/services/cover-art/cover-art-service.d.ts.map +1 -1
- package/dist/services/cover-art/cover-art-service.js +23 -14
- package/dist/services/cover-art/cover-art-service.js.map +1 -1
- package/dist/services/musicbrainz/musicbrainz-service.d.ts +3 -1
- package/dist/services/musicbrainz/musicbrainz-service.d.ts.map +1 -1
- package/dist/services/musicbrainz/musicbrainz-service.js +7 -3
- package/dist/services/musicbrainz/musicbrainz-service.js.map +1 -1
- package/dist/services/musicbrainz/types.d.ts +16 -3
- package/dist/services/musicbrainz/types.d.ts.map +1 -1
- package/package.json +10 -9
- 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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
|
|
6
|
-
**Engines:** Bun ≥1.
|
|
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.
|
|
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)
|
|
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
|
|
345
|
-
| `release-
|
|
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:
|
|
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
|
|
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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
|
|
6
|
-
**Engines:** Bun ≥1.
|
|
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.
|
|
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)
|
|
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
|
|
345
|
-
| `release-
|
|
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:
|
|
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
|
|
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
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://modelcontextprotocol.io/) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
12
12
|
</div>
|
|
13
13
|
|
|
@@ -31,49 +31,65 @@
|
|
|
31
31
|
|
|
32
32
|
---
|
|
33
33
|
|
|
34
|
-
##
|
|
34
|
+
## Overview
|
|
35
35
|
|
|
36
|
-
|
|
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
|
|
41
|
-
| `musicbrainz_get_artist` | Artist profile by MBID — type,
|
|
42
|
-
| `musicbrainz_get_release_group` | Release-group ("the album" above specific pressings) by MBID —
|
|
43
|
-
| `musicbrainz_get_release` | One edition's full detail by MBID — tracklist
|
|
44
|
-
| `musicbrainz_get_recording` | Recording (a specific performance
|
|
45
|
-
| `musicbrainz_get_work` | Work (a composition
|
|
46
|
-
| `musicbrainz_get_label` | Label by MBID — type,
|
|
47
|
-
| `musicbrainz_lookup_identifier` | Resolve
|
|
48
|
-
| `musicbrainz_browse_entities` | Paginate the complete set of entities linked to a parent MBID —
|
|
49
|
-
| `musicbrainz_get_cover_art` | Cover Art Archive images for a release or release-group MBID
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
### `
|
|
83
|
+
### `musicbrainz_get_release_group` <sub>tool</sub>
|
|
75
84
|
|
|
76
|
-
|
|
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
|
-
### `
|
|
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
|
-
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
|
|
150
|
+
---
|
|
117
151
|
|
|
118
|
-
|
|
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
|
-
|
|
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://
|
|
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
|
|
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
|
|
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`
|
package/changelog/template.md
CHANGED
|
@@ -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
|
|
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`.
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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
|