@cyanheads/musicbrainz-mcp-server 0.1.5 → 0.1.6

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 (55) hide show
  1. package/AGENTS.md +20 -20
  2. package/CLAUDE.md +20 -20
  3. package/Dockerfile +13 -7
  4. package/LICENSE +1 -1
  5. package/README.md +2 -2
  6. package/changelog/0.1.x/0.1.6.md +21 -0
  7. package/changelog/template.md +60 -19
  8. package/dist/mcp-server/resources/definitions/entity.resource.d.ts +4 -4
  9. package/dist/mcp-server/resources/definitions/entity.resource.js +2 -2
  10. package/dist/mcp-server/resources/definitions/entity.resource.js.map +1 -1
  11. package/dist/mcp-server/resources/definitions/index.d.ts +4 -4
  12. package/dist/mcp-server/tools/definitions/_shared.d.ts +1 -1
  13. package/dist/mcp-server/tools/definitions/_shared.js +2 -2
  14. package/dist/mcp-server/tools/definitions/_shared.js.map +1 -1
  15. package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts +4 -4
  16. package/dist/mcp-server/tools/definitions/browse-entities.tool.js +1 -1
  17. package/dist/mcp-server/tools/definitions/browse-entities.tool.js.map +1 -1
  18. package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts +1 -1
  19. package/dist/mcp-server/tools/definitions/get-artist.tool.js +1 -1
  20. package/dist/mcp-server/tools/definitions/get-artist.tool.js.map +1 -1
  21. package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts +2 -2
  22. package/dist/mcp-server/tools/definitions/get-cover-art.tool.js +3 -3
  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 +1 -1
  25. package/dist/mcp-server/tools/definitions/get-label.tool.js +1 -1
  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 +1 -1
  28. package/dist/mcp-server/tools/definitions/get-recording.tool.js +1 -1
  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 +1 -1
  31. package/dist/mcp-server/tools/definitions/get-release-group.tool.js +1 -1
  32. package/dist/mcp-server/tools/definitions/get-release-group.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/get-release.tool.d.ts +1 -1
  34. package/dist/mcp-server/tools/definitions/get-release.tool.js +1 -1
  35. package/dist/mcp-server/tools/definitions/get-release.tool.js.map +1 -1
  36. package/dist/mcp-server/tools/definitions/get-work.tool.d.ts +1 -1
  37. package/dist/mcp-server/tools/definitions/get-work.tool.js +1 -1
  38. package/dist/mcp-server/tools/definitions/get-work.tool.js.map +1 -1
  39. package/dist/mcp-server/tools/definitions/index.d.ts +189 -189
  40. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts +1 -1
  41. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts.map +1 -1
  42. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js +7 -4
  43. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js.map +1 -1
  44. package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts +3 -3
  45. package/dist/services/cover-art/cover-art-service.d.ts +1 -1
  46. package/dist/services/cover-art/cover-art-service.d.ts.map +1 -1
  47. package/dist/services/cover-art/cover-art-service.js +8 -5
  48. package/dist/services/cover-art/cover-art-service.js.map +1 -1
  49. package/dist/services/musicbrainz/musicbrainz-service.d.ts +5 -4
  50. package/dist/services/musicbrainz/musicbrainz-service.d.ts.map +1 -1
  51. package/dist/services/musicbrainz/musicbrainz-service.js +33 -22
  52. package/dist/services/musicbrainz/musicbrainz-service.js.map +1 -1
  53. package/dist/services/musicbrainz/rate-limiter.d.ts.map +1 -1
  54. package/package.json +11 -10
  55. package/server.json +3 -3
package/AGENTS.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** musicbrainz-mcp-server
4
- **Version:** 0.1.5
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.9`
4
+ **Version:** 0.1.6
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
8
8
  **Zod:** ^4.4.3
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.
@@ -35,7 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
35
35
  - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
36
36
  - **Use `ctx.log`** for request-scoped logging. No `console` calls.
37
37
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
38
- - **Check `ctx.elicit`** for presence before calling.
38
+ - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
39
39
  - **Secrets in env vars only** — never hardcoded.
40
40
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
41
41
 
@@ -45,7 +45,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
45
45
 
46
46
  ### Tool
47
47
 
48
- Tools are `musicbrainz_{verb}_{noun}`, all read-only, with typed error contracts encoding the live 400-vs-404 split (`invalid_mbid` / `entity_not_found`). `search_entities` is the entry point — it resolves a name to an MBID that chains into the `get_*` tools.
48
+ Tools are `musicbrainz_{verb}_{noun}`, all read-only, with typed error contracts encoding the live validation-vs-not-found split (`invalid_mbid` / `entity_not_found`). `search_entities` is the entry point — it resolves a name to an MBID that chains into the `get_*` tools.
49
49
 
50
50
  ```ts
51
51
  import { tool, z } from '@cyanheads/mcp-ts-core';
@@ -102,7 +102,7 @@ export const searchEntitiesTool = tool('musicbrainz_search_entities', {
102
102
 
103
103
  ### Resource
104
104
 
105
- One resource template mirrors the `get_*` lookups — the entity type is a path parameter. No `list()`: the corpus is millions of entities, so discovery is via `musicbrainz_search_entities`. The handler maps the service's `InvalidParams`/`NotFound` onto the typed `invalid_mbid` / `entity_not_found` contract via `ctx.fail` + `ctx.recoveryFor`.
105
+ One resource template mirrors the `get_*` lookups — the entity type is a path parameter. No `list()`: the corpus is millions of entities, so discovery is via `musicbrainz_search_entities`. The handler maps the service's `ValidationError`/`NotFound` onto the typed `invalid_mbid` / `entity_not_found` contract via `ctx.fail` + `ctx.recoveryFor`.
106
106
 
107
107
  ```ts
108
108
  import { resource, z } from '@cyanheads/mcp-ts-core';
@@ -115,7 +115,7 @@ export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
115
115
  description: 'A single MusicBrainz entity by type and MBID, with default linked sub-resources folded in.',
116
116
  mimeType: 'application/json',
117
117
  errors: [
118
- { reason: 'invalid_mbid', code: JsonRpcErrorCode.InvalidParams,
118
+ { reason: 'invalid_mbid', code: JsonRpcErrorCode.ValidationError,
119
119
  when: 'The MBID is malformed / all-zeros, or entity_type is not one of the six valid types.',
120
120
  recovery: 'Use a 36-character UUID MBID and a valid entity_type.' },
121
121
  { reason: 'entity_not_found', code: JsonRpcErrorCode.NotFound,
@@ -130,7 +130,7 @@ export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
130
130
  try {
131
131
  return await getMusicBrainzService().lookup(params.entity_type, params.mbid, { inc: DEFAULT_INC[params.entity_type] }, ctx, { signal: ctx.signal });
132
132
  } catch (error: unknown) {
133
- if (error instanceof McpError && error.code === JsonRpcErrorCode.InvalidParams)
133
+ if (error instanceof McpError && error.code === JsonRpcErrorCode.ValidationError)
134
134
  throw ctx.fail('invalid_mbid', `Malformed MBID "${params.mbid}".`, { ...ctx.recoveryFor('invalid_mbid') });
135
135
  if (error instanceof McpError && error.code === JsonRpcErrorCode.NotFound)
136
136
  throw ctx.fail('entity_not_found', `No ${params.entity_type} exists with MBID ${params.mbid}.`, { ...ctx.recoveryFor('entity_not_found') });
@@ -195,8 +195,7 @@ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("
195
195
  ```ts
196
196
  await createApp({
197
197
  name: 'musicbrainz-mcp-server',
198
- title: 'musicbrainz-mcp-server', // must match the unscoped package name — enforced by lint:packaging
199
- websiteUrl: 'https://github.com/cyanheads/musicbrainz-mcp-server',
198
+ title: 'musicbrainz-mcp-server',
200
199
  tools: allToolDefinitions,
201
200
  resources: allResourceDefinitions,
202
201
  prompts: [],
@@ -209,7 +208,7 @@ await createApp({
209
208
  });
210
209
  ```
211
210
 
212
- `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. Client adoption is uneven, but there's no downside when set.
211
+ 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.
213
212
 
214
213
  ---
215
214
 
@@ -219,13 +218,15 @@ Handlers receive a unified `ctx` object. Key properties:
219
218
 
220
219
  | Property | Description |
221
220
  |:---------|:------------|
222
- | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
223
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`. Backs the MusicBrainz response cache (shared across tenants — the data is public CC0). |
221
+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Dual-sink: Pino and client-visible `notifications/message`. |
222
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, options)`. Backs the MusicBrainz response cache. |
223
+ | `ctx.requestInput` | Suspend and ask the caller for missing input. Never returns; the handler is re-entered with responses. |
224
+ | `ctx.inputs` | Reader over a retried request's responses. Empty on the first round. |
224
225
  | `ctx.enrich` | Provenance helpers on search/browse — `.echo(query)`, `.total(n)`, `.notice(msg)`. Surface the effective query, upstream total, and a zero-hits hint without polluting the typed output. |
225
226
  | `ctx.fail` / `ctx.recoveryFor` | Throw a typed contract error by reason (`ctx.fail('invalid_mbid', …)`); `ctx.recoveryFor(reason)` pulls the declared recovery metadata for the throw site. |
226
227
  | `ctx.signal` | `AbortSignal` for cancellation — forwarded into every upstream fetch. |
227
228
  | `ctx.requestId` | Unique request ID. |
228
- | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
229
+ | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
229
230
 
230
231
  ---
231
232
 
@@ -339,7 +340,6 @@ Available skills:
339
340
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
340
341
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
341
342
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
342
- | `devcheck` | Lint, format, typecheck, audit |
343
343
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
344
344
  | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
345
345
  | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
@@ -351,7 +351,7 @@ Available skills:
351
351
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
352
352
  | `api-mirror` | MirrorService: stand up a self-refreshing local mirror of a bulk upstream dataset (SQLite + FTS5) — Tier 3 opt-in |
353
353
  | `api-config` | AppConfig, parseConfig, env vars |
354
- | `api-context` | Context interface, logger, state, progress |
354
+ | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
355
355
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
356
356
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
357
357
  | `api-services` | LLM, Speech, Graph services |
@@ -384,7 +384,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
384
384
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
385
385
  | `bun run lint:mcp` | Validate MCP tool/resource definitions against the linter rules |
386
386
  | `bun run lint:packaging` | Validate `manifest.json` ↔ `server.json` env var alignment + bundle/identity guards |
387
- | `bun test` | Run the Vitest suite |
387
+ | `bun run test` | Run the Vitest suite |
388
388
  | `bun run start:stdio` | Production mode (stdio) |
389
389
  | `bun run start:http` | Production mode (HTTP) |
390
390
  | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
@@ -396,7 +396,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
396
396
 
397
397
  ## Bundling
398
398
 
399
- `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
399
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs plus platform-specific native bindings that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
400
400
 
401
401
  **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
402
 
@@ -414,14 +414,14 @@ Each per-version file opens with YAML frontmatter:
414
414
  ---
415
415
  summary: "One-line headline, ≤350 chars" # required — powers the rollup index
416
416
  breaking: false # optional — true flags breaking changes
417
- security: false # optional — true flags security fixes
417
+ security: false # optional — true only for this project's source-code security fixes
418
418
  ---
419
419
 
420
420
  # 0.1.0 — YYYY-MM-DD
421
421
  ...
422
422
  ```
423
423
 
424
- `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
424
+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section; use it only for a fix in this server's own source, never for a dependency CVE bump. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
425
425
 
426
426
  `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
427
 
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** musicbrainz-mcp-server
4
- **Version:** 0.1.5
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.9`
4
+ **Version:** 0.1.6
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
8
8
  **Zod:** ^4.4.3
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.
@@ -35,7 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
35
35
  - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
36
36
  - **Use `ctx.log`** for request-scoped logging. No `console` calls.
37
37
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
38
- - **Check `ctx.elicit`** for presence before calling.
38
+ - **Need input the caller didn't supply?** `return ctx.requestInput(...)` and read `ctx.inputs` when the handler is re-entered. Never `await` for user input mid-handler.
39
39
  - **Secrets in env vars only** — never hardcoded.
40
40
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
41
41
 
@@ -45,7 +45,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
45
45
 
46
46
  ### Tool
47
47
 
48
- Tools are `musicbrainz_{verb}_{noun}`, all read-only, with typed error contracts encoding the live 400-vs-404 split (`invalid_mbid` / `entity_not_found`). `search_entities` is the entry point — it resolves a name to an MBID that chains into the `get_*` tools.
48
+ Tools are `musicbrainz_{verb}_{noun}`, all read-only, with typed error contracts encoding the live validation-vs-not-found split (`invalid_mbid` / `entity_not_found`). `search_entities` is the entry point — it resolves a name to an MBID that chains into the `get_*` tools.
49
49
 
50
50
  ```ts
51
51
  import { tool, z } from '@cyanheads/mcp-ts-core';
@@ -102,7 +102,7 @@ export const searchEntitiesTool = tool('musicbrainz_search_entities', {
102
102
 
103
103
  ### Resource
104
104
 
105
- One resource template mirrors the `get_*` lookups — the entity type is a path parameter. No `list()`: the corpus is millions of entities, so discovery is via `musicbrainz_search_entities`. The handler maps the service's `InvalidParams`/`NotFound` onto the typed `invalid_mbid` / `entity_not_found` contract via `ctx.fail` + `ctx.recoveryFor`.
105
+ One resource template mirrors the `get_*` lookups — the entity type is a path parameter. No `list()`: the corpus is millions of entities, so discovery is via `musicbrainz_search_entities`. The handler maps the service's `ValidationError`/`NotFound` onto the typed `invalid_mbid` / `entity_not_found` contract via `ctx.fail` + `ctx.recoveryFor`.
106
106
 
107
107
  ```ts
108
108
  import { resource, z } from '@cyanheads/mcp-ts-core';
@@ -115,7 +115,7 @@ export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
115
115
  description: 'A single MusicBrainz entity by type and MBID, with default linked sub-resources folded in.',
116
116
  mimeType: 'application/json',
117
117
  errors: [
118
- { reason: 'invalid_mbid', code: JsonRpcErrorCode.InvalidParams,
118
+ { reason: 'invalid_mbid', code: JsonRpcErrorCode.ValidationError,
119
119
  when: 'The MBID is malformed / all-zeros, or entity_type is not one of the six valid types.',
120
120
  recovery: 'Use a 36-character UUID MBID and a valid entity_type.' },
121
121
  { reason: 'entity_not_found', code: JsonRpcErrorCode.NotFound,
@@ -130,7 +130,7 @@ export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
130
130
  try {
131
131
  return await getMusicBrainzService().lookup(params.entity_type, params.mbid, { inc: DEFAULT_INC[params.entity_type] }, ctx, { signal: ctx.signal });
132
132
  } catch (error: unknown) {
133
- if (error instanceof McpError && error.code === JsonRpcErrorCode.InvalidParams)
133
+ if (error instanceof McpError && error.code === JsonRpcErrorCode.ValidationError)
134
134
  throw ctx.fail('invalid_mbid', `Malformed MBID "${params.mbid}".`, { ...ctx.recoveryFor('invalid_mbid') });
135
135
  if (error instanceof McpError && error.code === JsonRpcErrorCode.NotFound)
136
136
  throw ctx.fail('entity_not_found', `No ${params.entity_type} exists with MBID ${params.mbid}.`, { ...ctx.recoveryFor('entity_not_found') });
@@ -195,8 +195,7 @@ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("
195
195
  ```ts
196
196
  await createApp({
197
197
  name: 'musicbrainz-mcp-server',
198
- title: 'musicbrainz-mcp-server', // must match the unscoped package name — enforced by lint:packaging
199
- websiteUrl: 'https://github.com/cyanheads/musicbrainz-mcp-server',
198
+ title: 'musicbrainz-mcp-server',
200
199
  tools: allToolDefinitions,
201
200
  resources: allResourceDefinitions,
202
201
  prompts: [],
@@ -209,7 +208,7 @@ await createApp({
209
208
  });
210
209
  ```
211
210
 
212
- `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. Client adoption is uneven, but there's no downside when set.
211
+ 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.
213
212
 
214
213
  ---
215
214
 
@@ -219,13 +218,15 @@ Handlers receive a unified `ctx` object. Key properties:
219
218
 
220
219
  | Property | Description |
221
220
  |:---------|:------------|
222
- | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
223
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`. Backs the MusicBrainz response cache (shared across tenants — the data is public CC0). |
221
+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Dual-sink: Pino and client-visible `notifications/message`. |
222
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, options)`. Backs the MusicBrainz response cache. |
223
+ | `ctx.requestInput` | Suspend and ask the caller for missing input. Never returns; the handler is re-entered with responses. |
224
+ | `ctx.inputs` | Reader over a retried request's responses. Empty on the first round. |
224
225
  | `ctx.enrich` | Provenance helpers on search/browse — `.echo(query)`, `.total(n)`, `.notice(msg)`. Surface the effective query, upstream total, and a zero-hits hint without polluting the typed output. |
225
226
  | `ctx.fail` / `ctx.recoveryFor` | Throw a typed contract error by reason (`ctx.fail('invalid_mbid', …)`); `ctx.recoveryFor(reason)` pulls the declared recovery metadata for the throw site. |
226
227
  | `ctx.signal` | `AbortSignal` for cancellation — forwarded into every upstream fetch. |
227
228
  | `ctx.requestId` | Unique request ID. |
228
- | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
229
+ | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
229
230
 
230
231
  ---
231
232
 
@@ -339,7 +340,6 @@ Available skills:
339
340
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
340
341
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
341
342
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
342
- | `devcheck` | Lint, format, typecheck, audit |
343
343
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
344
344
  | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
345
345
  | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
@@ -351,7 +351,7 @@ Available skills:
351
351
  | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
352
352
  | `api-mirror` | MirrorService: stand up a self-refreshing local mirror of a bulk upstream dataset (SQLite + FTS5) — Tier 3 opt-in |
353
353
  | `api-config` | AppConfig, parseConfig, env vars |
354
- | `api-context` | Context interface, logger, state, progress |
354
+ | `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
355
355
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
356
356
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
357
357
  | `api-services` | LLM, Speech, Graph services |
@@ -384,7 +384,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
384
384
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
385
385
  | `bun run lint:mcp` | Validate MCP tool/resource definitions against the linter rules |
386
386
  | `bun run lint:packaging` | Validate `manifest.json` ↔ `server.json` env var alignment + bundle/identity guards |
387
- | `bun test` | Run the Vitest suite |
387
+ | `bun run test` | Run the Vitest suite |
388
388
  | `bun run start:stdio` | Production mode (stdio) |
389
389
  | `bun run start:http` | Production mode (HTTP) |
390
390
  | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
@@ -396,7 +396,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
396
396
 
397
397
  ## Bundling
398
398
 
399
- `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
399
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs plus platform-specific native bindings that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
400
400
 
401
401
  **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
402
 
@@ -414,14 +414,14 @@ Each per-version file opens with YAML frontmatter:
414
414
  ---
415
415
  summary: "One-line headline, ≤350 chars" # required — powers the rollup index
416
416
  breaking: false # optional — true flags breaking changes
417
- security: false # optional — true flags security fixes
417
+ security: false # optional — true only for this project's source-code security fixes
418
418
  ---
419
419
 
420
420
  # 0.1.0 — YYYY-MM-DD
421
421
  ...
422
422
  ```
423
423
 
424
- `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
424
+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section; use it only for a fix in this server's own source, never for a dependency CVE bump. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
425
425
 
426
426
  `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
427
 
package/Dockerfile CHANGED
@@ -4,15 +4,17 @@
4
4
  # This stage installs all dependencies (including dev), builds the TypeScript
5
5
  # source code into JavaScript, and prepares the production assets.
6
6
  # ==============================================================================
7
- FROM oven/bun:1.3 AS build
7
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
8
8
 
9
9
  WORKDIR /usr/src/app
10
10
 
11
11
  # Copy dependency manifests for optimized layer caching
12
12
  COPY package.json bun.lock ./
13
13
 
14
- # Install all dependencies (including dev dependencies for building)
15
- RUN bun install --frozen-lockfile
14
+ # Install all dependencies (including dev dependencies for building).
15
+ # The BuildKit cache mount persists Bun's global package cache across builds.
16
+ RUN --mount=type=cache,target=/root/.bun/install/cache \
17
+ bun install --frozen-lockfile --ignore-scripts
16
18
 
17
19
  # Copy the rest of the source code
18
20
  COPY . .
@@ -28,7 +30,7 @@ RUN bun run build
28
30
  # application. It uses a slim base image and only includes production
29
31
  # dependencies and build artifacts.
30
32
  # ==============================================================================
31
- FROM oven/bun:1.3-slim AS production
33
+ FROM oven/bun:1.4.0-slim AS production
32
34
 
33
35
  WORKDIR /usr/src/app
34
36
 
@@ -49,14 +51,18 @@ COPY package.json bun.lock ./
49
51
 
50
52
  # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
51
53
  # that are not needed in the final production image.
52
- RUN bun install --production --frozen-lockfile --ignore-scripts
54
+ # `--omit=peer` drops the framework's optional peer tiers. Anything this server
55
+ # imports directly remains in its own dependencies.
56
+ RUN --mount=type=cache,target=/root/.bun/install/cache \
57
+ bun install --production --omit=peer --frozen-lockfile --ignore-scripts
53
58
 
54
59
  # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
55
60
  # These are not bundled by default to keep the base image lean. Enable at build time
56
61
  # with: docker build --build-arg OTEL_ENABLED=true
57
62
  ARG OTEL_ENABLED=true
58
- RUN if [ "$OTEL_ENABLED" = "true" ]; then \
59
- bun add @hono/otel \
63
+ RUN --mount=type=cache,target=/root/.bun/install/cache \
64
+ if [ "$OTEL_ENABLED" = "true" ]; then \
65
+ bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
60
66
  @opentelemetry/instrumentation-http \
61
67
  @opentelemetry/exporter-metrics-otlp-http \
62
68
  @opentelemetry/exporter-trace-otlp-http \
package/LICENSE CHANGED
@@ -186,7 +186,7 @@ Apache License
186
186
  same "printed page" as the copyright notice for easier
187
187
  identification within third-party archives.
188
188
 
189
- Copyright 2025 Casey Hand @cyanheads
189
+ Copyright 2026 Casey Hand @cyanheads
190
190
 
191
191
  Licensed under the Apache License, Version 2.0 (the "License");
192
192
  you may not use this file except in compliance with the License.
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.5-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-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
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/)
11
11
 
12
12
  </div>
13
13
 
@@ -232,7 +232,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 MUSICBRAINZ_CONTACT=you@example.com b
232
232
 
233
233
  ### Prerequisites
234
234
 
235
- - [Bun v1.3.2](https://bun.sh/) or higher (or Node.js v24+).
235
+ - [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
236
236
  - No API key. Optionally set `MUSICBRAINZ_CONTACT` to your email or URL — recommended for any shared or hosted deployment.
237
237
 
238
238
  ### Installation
@@ -0,0 +1,21 @@
1
+ ---
2
+ summary: "Adopt mcp-ts-core ^0.12.3 and MCP SDK v2, align MusicBrainz validation contracts and request context with the framework, and refresh build, bundle, and project tooling."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.6 — 2026-08-21
8
+
9
+ ## Changed
10
+
11
+ - **`@cyanheads/mcp-ts-core` `^0.10.9` → `^0.12.3`** — adopts MCP SDK v2, the 2026 protocol revision, strict tool inputs, and the current server-side context and telemetry behavior.
12
+ - **MusicBrainz validation contracts** — upstream malformed MBIDs, links, and identifiers now surface as `ValidationError` while retaining their existing reason and recovery metadata; well-formed missing entities remain `NotFound`.
13
+ - **MusicBrainz and Cover Art services** — request context now derives from the handler context, storage receives that canonical context, and Cover Art treats an upstream 404 as an expected no-art response before retry classification.
14
+ - **Build, verification, and bundle tooling** — TypeScript typechecks both source and tests without emitting, build emission is isolated, dependency guards inspect overrides, and MCPB cleanup removes platform-native bindings alongside dependency-shipped agent docs.
15
+ - **Project metadata and contributor guidance** — package, manifest, and plugin author identity is Casey Hand; add repository attributes plus contributing, conduct, funding, and security guidance.
16
+
17
+ ## Dependencies
18
+
19
+ - `@cyanheads/mcp-ts-core` `^0.10.9` → `^0.12.3`
20
+ - `@biomejs/biome` `2.5.0` → `2.5.9`, `@types/node` `26.0.0` → `26.2.0`, `ignore` `^7.0.5` → `^7.0.6`, `tsc-alias` `^1.8.17` → `^1.9.2`, `typescript` `^6.0.3` → `^7.0.2`, and `vitest` `^4.1.9` → `^4.1.11`
21
+ - `@socketsecurity/bun-security-scanner` `^1.1.2` added for dependency scanning.
@@ -4,10 +4,11 @@
4
4
  # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
5
5
  # with a concrete date.
6
6
 
7
- # Required. One-line GitHub Release-style headline. 350 character cap.
8
- # Default short and scannable. Don't pad, don't stitch unrelated changes with
9
- # semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
10
- # inside the value as a key separator and fails GitHub's strict parser.
7
+ # Required. One-line GitHub Release-style headline. 350 character cap — a
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
11
+ # `: ` inside the value as a key separator and fails GitHub's strict parser.
11
12
  summary: ""
12
13
 
13
14
  # Set `true` when consumers must change code to upgrade: API removals,
@@ -15,16 +16,19 @@ summary: ""
15
16
  # usage. Flagged as `Breaking` in the rollup.
16
17
  breaking: false
17
18
 
18
- # Set `true` if this release contains any security fix. Pairs with the
19
- # `## Security` section below. Flagged as `Security` in the rollup so
20
- # users can triage upgrade urgency at a glance.
19
+ # Set `true` ONLY for a security fix in THIS project's own source code — a
20
+ # vulnerability or hardening in code you ship. A dependency or transitive CVE
21
+ # bump is routine maintenance, NOT a security release: record it under
22
+ # `## Dependencies` (with the advisory ID) and leave this `false`. When true,
23
+ # pairs with the `## Security` section below and flags `Security` in the rollup.
21
24
  security: false
22
25
 
23
26
  # Optional free-form notes for maintenance agents processing this release.
24
27
  # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
25
- # downstream servers. Use for adoption instructions that don't fit the
26
- # human-facing sections: new files to create, fields to populate, one-time
27
- # migration steps. Omit the field entirely when there's nothing to say.
28
+ # downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
29
+ # populate, one-time migration steps. Never a second rendering of the body:
30
+ # if a body bullet already says it, name the bullet's symbol instead of
31
+ # re-explaining. Omit the field entirely when there's nothing to say.
28
32
  # agent-notes: |
29
33
  # <instructions for downstream maintenance agents>
30
34
  ---
@@ -39,17 +43,54 @@ security: false
39
43
  each bullet with the symbol or concept name in **bold** so they can skip
40
44
  what's irrelevant and zoom in on what's not.
41
45
 
42
- Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
43
- name the symbol, state what changed, stop. Use a second sentence only when
44
- it carries weight. If a bullet feels long, it is.
45
-
46
- Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
47
- relevant skill), ceremonial framings ("This release introduces…",
48
- backwards-compat paragraphs), file-by-file test enumerations, internal
49
- implementation notes. Prefer code/symbol names over English re-explanations.
46
+ Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
47
+ changed + at most one consumer-facing caveat. One sentence by default, two
48
+ when the second carries weight — a bullet past ~40 words or three sentences
49
+ is wrong. The depth lives one hop away: the linked issue carries the why,
50
+ the commit diff carries the how. The changelog names what changed and what
51
+ a consumer does about it; a reader who wants mechanism opens the link.
52
+
53
+ Model length on THIS guide, never on the previous entry — entries modeled
54
+ on entries compound.
55
+
56
+ Cut (each has shipped as a wall of text; these are the cruft):
57
+ - History/justification narration — how the bug worked, why the old
58
+ behavior was wrong. One short clause at most; the issue carries the story.
59
+ - Design-rationale defense — "chosen over Y because…", "guarding the
60
+ getter is not enough…". That is the author arguing with a reviewer;
61
+ reviewers read the PR, not the changelog.
62
+ - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
63
+ <prev>". Keep one only where its absence would cause a real misread,
64
+ as a short parenthetical.
65
+ - Edge-case inventories — marker lists, not-flagged lists, escape tables.
66
+ Tests and the issue carry those.
67
+ - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
68
+ skill own those), ceremonial framings ("This release introduces…"),
69
+ backwards-compat paragraphs, file-by-file test enumerations. Prefer
70
+ code/symbol names over English re-explanations.
71
+
72
+ Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
73
+ the TRUTH of what you write, never the AMOUNT.
74
+
75
+ Example — same fact, right size:
76
+
77
+ TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
78
+ (#341). `fetch` resolves once headers arrive and the deadline was
79
+ cleared as the helper returned, so a peer that answered promptly and
80
+ then stalled the stream held the request open indefinitely. A 2xx
81
+ carrying a body now comes back as a passthrough wrapper that disarms
82
+ the deadline when the body closes, errors, or is cancelled; …
83
+ [+90 more words of mechanism and edge cases]
84
+
85
+ RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
86
+ exchange, not just the headers** (#341). A stalled body aborts with
87
+ the same `Timeout` error; the returned `Response` is a wrapper, so
88
+ identity assertions (`toBe(response)`) no longer hold.
50
89
 
51
90
  Narrative intro: skip by default. Add one short sentence only when the
52
- release theme genuinely needs framing the bullets can't carry.
91
+ release theme genuinely needs framing the bullets can't carry. When many
92
+ bullets share one upgrade consequence, state it ONCE — intro line or
93
+ agent-notes — never per bullet.
53
94
 
54
95
  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
55
96
  Fixed, Security. Include only sections with entries; delete the rest
@@ -12,16 +12,16 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
12
12
  export declare const entityResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
13
13
  entity_type: z.ZodEnum<{
14
14
  artist: "artist";
15
- "release-group": "release-group";
16
- release: "release";
15
+ label: "label";
17
16
  recording: "recording";
17
+ release: "release";
18
+ "release-group": "release-group";
18
19
  work: "work";
19
- label: "label";
20
20
  }>;
21
21
  mbid: z.ZodString;
22
22
  }, z.core.$strip>, undefined, readonly [{
23
23
  readonly reason: "invalid_mbid";
24
- readonly code: JsonRpcErrorCode.InvalidParams;
24
+ readonly code: JsonRpcErrorCode.ValidationError;
25
25
  readonly when: "The MBID is malformed / all-zeros, or entity_type is not one of the six valid types.";
26
26
  readonly recovery: "Use a 36-character UUID MBID and a valid entity_type (artist, release-group, release, recording, work, label).";
27
27
  }, {
@@ -28,7 +28,7 @@ export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
28
28
  errors: [
29
29
  {
30
30
  reason: 'invalid_mbid',
31
- code: JsonRpcErrorCode.InvalidParams,
31
+ code: JsonRpcErrorCode.ValidationError,
32
32
  when: 'The MBID is malformed / all-zeros, or entity_type is not one of the six valid types.',
33
33
  recovery: 'Use a 36-character UUID MBID and a valid entity_type (artist, release-group, release, recording, work, label).',
34
34
  },
@@ -55,7 +55,7 @@ export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
55
55
  return await service.lookup(params.entity_type, params.mbid, { inc: DEFAULT_INC[params.entity_type] }, ctx, { signal: ctx.signal });
56
56
  }
57
57
  catch (error) {
58
- if (error instanceof McpError && error.code === JsonRpcErrorCode.InvalidParams) {
58
+ if (error instanceof McpError && error.code === JsonRpcErrorCode.ValidationError) {
59
59
  throw ctx.fail('invalid_mbid', `Malformed MBID "${params.mbid}".`, {
60
60
  ...ctx.recoveryFor('invalid_mbid'),
61
61
  });
@@ -1 +1 @@
1
- {"version":3,"file":"entity.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity.resource.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"entity.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity.resource.ts"],"names":[],"mappings":"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"}
@@ -6,16 +6,16 @@
6
6
  export declare const allResourceDefinitions: import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
7
7
  entity_type: import("zod").ZodEnum<{
8
8
  artist: "artist";
9
- "release-group": "release-group";
10
- release: "release";
9
+ label: "label";
11
10
  recording: "recording";
11
+ release: "release";
12
+ "release-group": "release-group";
12
13
  work: "work";
13
- label: "label";
14
14
  }>;
15
15
  mbid: import("zod").ZodString;
16
16
  }, import("zod/v4/core").$strip>, undefined, readonly [{
17
17
  readonly reason: "invalid_mbid";
18
- readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
18
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
19
19
  readonly when: "The MBID is malformed / all-zeros, or entity_type is not one of the six valid types.";
20
20
  readonly recovery: "Use a 36-character UUID MBID and a valid entity_type (artist, release-group, release, recording, work, label).";
21
21
  }, {
@@ -17,7 +17,7 @@ import { z } from '@cyanheads/mcp-ts-core';
17
17
  import type { RawAlias, RawArtistCredit, RawCoverArtStub, RawLifeSpan, RawRelation, RawTag } from '../../../services/musicbrainz/types.js';
18
18
  /**
19
19
  * Classify an upstream error from an MBID lookup against the MusicBrainz 400-vs-404
20
- * split: a malformed / all-zeros MBID returns HTTP 400 (`InvalidParams`); a
20
+ * split: a malformed / all-zeros MBID returns HTTP 400 (`ValidationError`); a
21
21
  * well-formed MBID with no matching entity returns HTTP 404 (`NotFound`). Returns
22
22
  * the contract reason for those two cases, or `null` for anything else (transient
23
23
  * upstream failures bubble unchanged). Handlers call `ctx.fail(reason, …)` on a