@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.
- package/AGENTS.md +20 -20
- package/CLAUDE.md +20 -20
- package/Dockerfile +13 -7
- package/LICENSE +1 -1
- package/README.md +2 -2
- package/changelog/0.1.x/0.1.6.md +21 -0
- package/changelog/template.md +60 -19
- package/dist/mcp-server/resources/definitions/entity.resource.d.ts +4 -4
- package/dist/mcp-server/resources/definitions/entity.resource.js +2 -2
- package/dist/mcp-server/resources/definitions/entity.resource.js.map +1 -1
- package/dist/mcp-server/resources/definitions/index.d.ts +4 -4
- package/dist/mcp-server/tools/definitions/_shared.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/_shared.js +2 -2
- package/dist/mcp-server/tools/definitions/_shared.js.map +1 -1
- package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts +4 -4
- package/dist/mcp-server/tools/definitions/browse-entities.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/browse-entities.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/get-artist.tool.js +1 -1
- 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 +2 -2
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.js +3 -3
- 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 +1 -1
- package/dist/mcp-server/tools/definitions/get-label.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/get-label.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/get-recording.tool.js +1 -1
- 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 +1 -1
- package/dist/mcp-server/tools/definitions/get-release-group.tool.js +1 -1
- 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 +1 -1
- package/dist/mcp-server/tools/definitions/get-release.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/get-release.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-work.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/get-work.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/get-work.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +189 -189
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js +7 -4
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts +3 -3
- package/dist/services/cover-art/cover-art-service.d.ts +1 -1
- package/dist/services/cover-art/cover-art-service.d.ts.map +1 -1
- package/dist/services/cover-art/cover-art-service.js +8 -5
- package/dist/services/cover-art/cover-art-service.js.map +1 -1
- package/dist/services/musicbrainz/musicbrainz-service.d.ts +5 -4
- package/dist/services/musicbrainz/musicbrainz-service.d.ts.map +1 -1
- package/dist/services/musicbrainz/musicbrainz-service.js +33 -22
- package/dist/services/musicbrainz/musicbrainz-service.js.map +1 -1
- package/dist/services/musicbrainz/rate-limiter.d.ts.map +1 -1
- package/package.json +11 -10
- 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
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
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/
|
|
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
|
-
- **
|
|
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
|
|
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 `
|
|
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.
|
|
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.
|
|
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',
|
|
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.
|
|
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()`.
|
|
223
|
-
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`. Backs the MusicBrainz response cache
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
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/
|
|
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
|
-
- **
|
|
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
|
|
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 `
|
|
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.
|
|
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.
|
|
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',
|
|
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.
|
|
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()`.
|
|
223
|
-
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`. Backs the MusicBrainz response cache
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
59
|
-
|
|
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
|
|
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
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://modelcontextprotocol.io/) [](https://www.typescriptlang.org/) [](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.
|
|
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.
|
package/changelog/template.md
CHANGED
|
@@ -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
|
|
9
|
-
#
|
|
10
|
-
#
|
|
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`
|
|
19
|
-
#
|
|
20
|
-
#
|
|
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.
|
|
26
|
-
#
|
|
27
|
-
#
|
|
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.
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+CAA+C,CAAC;AAGtF,mFAAmF;AACnF,MAAM,WAAW,GAAiC;IAChD,MAAM,EAAE,CAAC,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC;IAClF,eAAe,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,CAAC;IACjE,OAAO,EAAE,CAAC,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,gBAAgB,CAAC;IACrE,SAAS,EAAE,CAAC,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,CAAC;IAC1F,IAAI,EAAE,CAAC,aAAa,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC;IAChF,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC;CACjD,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAEnG,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC,oCAAoC,EAAE;IAC3E,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,gCAAgC;IACvC,WAAW,EACT,sZAAsZ;IACxZ,QAAQ,EAAE,kBAAkB;IAE5B,MAAM,EAAE;QACN;YACE,MAAM,EAAE,cAAc;YACtB,IAAI,EAAE,gBAAgB,CAAC,
|
|
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
|
-
|
|
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.
|
|
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 (`
|
|
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
|