@cyanheads/musicbrainz-mcp-server 0.1.8 → 0.1.9
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 +36 -31
- package/CLAUDE.md +36 -31
- package/Dockerfile +92 -33
- package/README.md +63 -97
- package/changelog/0.1.x/0.1.9.md +35 -0
- package/dist/mcp-server/resources/definitions/entity.resource.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/entity.resource.js +2 -6
- package/dist/mcp-server/resources/definitions/entity.resource.js.map +1 -1
- package/dist/mcp-server/tools/definitions/_shared.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/_shared.js +1 -1
- package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/browse-entities.tool.js +3 -7
- package/dist/mcp-server/tools/definitions/browse-entities.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-artist.tool.js +2 -8
- 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.map +1 -1
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.js +3 -9
- 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.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-label.tool.js +3 -9
- 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.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-recording.tool.js +3 -9
- 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.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-release-group.tool.js +3 -9
- 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.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-release.tool.js +3 -9
- 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.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-work.tool.js +3 -9
- package/dist/mcp-server/tools/definitions/get-work.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +5 -5
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js +8 -18
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-entities.tool.js +1 -3
- package/dist/mcp-server/tools/definitions/search-entities.tool.js.map +1 -1
- package/package.json +11 -10
- package/server.json +10 -24
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.13.
|
|
4
|
+
**Version:** 0.1.9
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.14`
|
|
6
6
|
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` ^2.
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
|
|
8
8
|
**Zod:** ^4.6.5
|
|
9
9
|
|
|
10
10
|
> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
|
|
@@ -37,6 +37,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
|
|
|
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
|
+
- **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
|
|
40
41
|
- **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
42
|
|
|
42
43
|
---
|
|
@@ -102,7 +103,7 @@ export const searchEntitiesTool = tool('musicbrainz_search_entities', {
|
|
|
102
103
|
|
|
103
104
|
### Resource
|
|
104
105
|
|
|
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`
|
|
106
|
+
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`; the framework fills each declared `recovery` hint on the wire.
|
|
106
107
|
|
|
107
108
|
```ts
|
|
108
109
|
import { resource, z } from '@cyanheads/mcp-ts-core';
|
|
@@ -131,9 +132,9 @@ export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
|
|
|
131
132
|
return await getMusicBrainzService().lookup(params.entity_type, params.mbid, { inc: DEFAULT_INC[params.entity_type] }, ctx, { signal: ctx.signal });
|
|
132
133
|
} catch (error: unknown) {
|
|
133
134
|
if (error instanceof McpError && error.code === JsonRpcErrorCode.ValidationError)
|
|
134
|
-
throw ctx.fail('invalid_mbid', `Malformed MBID "${params.mbid}"
|
|
135
|
+
throw ctx.fail('invalid_mbid', `Malformed MBID "${params.mbid}".`);
|
|
135
136
|
if (error instanceof McpError && error.code === JsonRpcErrorCode.NotFound)
|
|
136
|
-
throw ctx.fail('entity_not_found', `No ${params.entity_type} exists with MBID ${params.mbid}
|
|
137
|
+
throw ctx.fail('entity_not_found', `No ${params.entity_type} exists with MBID ${params.mbid}.`);
|
|
137
138
|
throw error;
|
|
138
139
|
}
|
|
139
140
|
},
|
|
@@ -221,14 +222,16 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
221
222
|
|
|
222
223
|
| Property | Description |
|
|
223
224
|
|:---------|:------------|
|
|
224
|
-
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Dual-sink: Pino and
|
|
225
|
-
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix,
|
|
226
|
-
| `ctx.requestInput` | Suspend and ask the caller for
|
|
227
|
-
| `ctx.inputs` |
|
|
228
|
-
| `ctx.
|
|
229
|
-
| `ctx.
|
|
225
|
+
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
|
|
226
|
+
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). Backs the MusicBrainz response cache. |
|
|
227
|
+
| `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
|
|
228
|
+
| `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
|
|
229
|
+
| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
|
|
230
|
+
| `ctx.enrich` | Success-path agent context — `.echo(query)`, `.total(n)`, `.notice(msg)`, `.truncated()`. Surfaces the effective query, upstream total, and a zero-hits hint without polluting the typed output; lands only when the definition declares an `enrichment` block. |
|
|
231
|
+
| `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
|
|
232
|
+
| `ctx.fail` | Throw a typed contract error by reason (`ctx.fail('invalid_mbid', …)`); the framework fills the declared `recovery` hint. |
|
|
230
233
|
| `ctx.signal` | `AbortSignal` for cancellation — forwarded into every upstream fetch. |
|
|
231
|
-
| `ctx.requestId` |
|
|
234
|
+
| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
|
|
232
235
|
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
|
|
233
236
|
|
|
234
237
|
---
|
|
@@ -237,7 +240,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
237
240
|
|
|
238
241
|
Handlers throw — the framework catches, classifies, and formats.
|
|
239
242
|
|
|
240
|
-
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required
|
|
243
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
|
|
241
244
|
|
|
242
245
|
```ts
|
|
243
246
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -270,7 +273,7 @@ throw new Error('Invalid query format'); // → ValidationError
|
|
|
270
273
|
|
|
271
274
|
// McpError — when no factory exists for the code
|
|
272
275
|
import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
273
|
-
throw new McpError(JsonRpcErrorCode.
|
|
276
|
+
throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
|
|
274
277
|
```
|
|
275
278
|
|
|
276
279
|
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
|
|
@@ -351,19 +354,19 @@ Available skills:
|
|
|
351
354
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
352
355
|
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
353
356
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
357
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
354
358
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
355
359
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
356
|
-
| `api-mirror` | MirrorService: stand up a self-refreshing local mirror of a bulk upstream dataset (SQLite + FTS5) — Tier 3 opt-in |
|
|
357
360
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
358
361
|
| `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
|
|
359
362
|
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
360
363
|
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
364
|
+
| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
|
|
361
365
|
| `api-services` | LLM, Speech, Graph services |
|
|
362
366
|
| `api-testing` | createMockContext, test patterns |
|
|
363
367
|
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
364
368
|
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
365
369
|
| `api-workers` | Cloudflare Workers runtime |
|
|
366
|
-
| `techniques` | Cross-cutting implementation techniques and recipes for the framework |
|
|
367
370
|
|
|
368
371
|
**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
|
|
369
372
|
|
|
@@ -380,16 +383,16 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
380
383
|
| `bun run build` | Compile TypeScript |
|
|
381
384
|
| `bun run rebuild` | Clean + build |
|
|
382
385
|
| `bun run clean` | Remove build artifacts |
|
|
383
|
-
| `bun run devcheck` | Lint + format + typecheck + security +
|
|
386
|
+
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
384
387
|
| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
|
|
385
388
|
| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
|
|
386
|
-
| `bun run
|
|
387
|
-
| `bun run
|
|
389
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
390
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
391
|
+
| `bun run list-skills` | Print the skill registry |
|
|
392
|
+
| `bun run tree` | Generate directory structure doc |
|
|
388
393
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
389
394
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
390
|
-
| `bun run
|
|
391
|
-
| `bun run lint:packaging` | Validate `manifest.json` ↔ `server.json` env var alignment + bundle/identity guards |
|
|
392
|
-
| `bun run test` | Run the Vitest suite |
|
|
395
|
+
| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
|
|
393
396
|
| `bun run start:stdio` | Production mode (stdio) |
|
|
394
397
|
| `bun run start:http` | Production mode (HTTP) |
|
|
395
398
|
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
@@ -397,13 +400,15 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
397
400
|
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
398
401
|
| `bun run release:github` | Create the GitHub release from the current tag |
|
|
399
402
|
|
|
403
|
+
**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
|
|
404
|
+
|
|
400
405
|
---
|
|
401
406
|
|
|
402
407
|
## Bundling
|
|
403
408
|
|
|
404
|
-
`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
|
|
409
|
+
`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 two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. 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.
|
|
405
410
|
|
|
406
|
-
**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
|
|
411
|
+
**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, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
|
|
407
412
|
|
|
408
413
|
**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
|
|
409
414
|
|
|
@@ -419,14 +424,14 @@ Each per-version file opens with YAML frontmatter:
|
|
|
419
424
|
---
|
|
420
425
|
summary: "One-line headline, ≤350 chars" # required — powers the rollup index
|
|
421
426
|
breaking: false # optional — true flags breaking changes
|
|
422
|
-
security: false # optional — true
|
|
427
|
+
security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
|
|
423
428
|
---
|
|
424
429
|
|
|
425
430
|
# 0.1.0 — YYYY-MM-DD
|
|
426
431
|
...
|
|
427
432
|
```
|
|
428
433
|
|
|
429
|
-
`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
|
|
434
|
+
`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 — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
|
|
430
435
|
|
|
431
436
|
`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.
|
|
432
437
|
|
|
@@ -438,7 +443,7 @@ security: false # optional — true only for this pro
|
|
|
438
443
|
|
|
439
444
|
## Publishing
|
|
440
445
|
|
|
441
|
-
**Every release goes through a release PR
|
|
446
|
+
**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
|
|
442
447
|
|
|
443
448
|
---
|
|
444
449
|
|
|
@@ -470,8 +475,8 @@ import type { EntityType } from '@/services/musicbrainz/types.js';
|
|
|
470
475
|
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
471
476
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
472
477
|
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
|
|
473
|
-
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` =
|
|
474
|
-
- [ ] `.codex-plugin/mcp.json` updated — server name key
|
|
475
|
-
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry
|
|
478
|
+
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
|
|
479
|
+
- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
|
|
480
|
+
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
|
|
476
481
|
- [ ] All upstream calls route through `getMusicBrainzService()` / `getCoverArtService()` — never `fetch()` MusicBrainz directly. The service owns the mandatory descriptive `User-Agent` (with `MUSICBRAINZ_CONTACT`), the process-wide ~1 req/sec rate limiter, and the response cache; a stray fetch bypasses all three.
|
|
477
482
|
- [ ] `bun run devcheck` passes
|
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.13.
|
|
4
|
+
**Version:** 0.1.9
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.14`
|
|
6
6
|
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` ^2.
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
|
|
8
8
|
**Zod:** ^4.6.5
|
|
9
9
|
|
|
10
10
|
> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
|
|
@@ -37,6 +37,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
|
|
|
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
|
+
- **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.
|
|
40
41
|
- **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
42
|
|
|
42
43
|
---
|
|
@@ -102,7 +103,7 @@ export const searchEntitiesTool = tool('musicbrainz_search_entities', {
|
|
|
102
103
|
|
|
103
104
|
### Resource
|
|
104
105
|
|
|
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`
|
|
106
|
+
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`; the framework fills each declared `recovery` hint on the wire.
|
|
106
107
|
|
|
107
108
|
```ts
|
|
108
109
|
import { resource, z } from '@cyanheads/mcp-ts-core';
|
|
@@ -131,9 +132,9 @@ export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
|
|
|
131
132
|
return await getMusicBrainzService().lookup(params.entity_type, params.mbid, { inc: DEFAULT_INC[params.entity_type] }, ctx, { signal: ctx.signal });
|
|
132
133
|
} catch (error: unknown) {
|
|
133
134
|
if (error instanceof McpError && error.code === JsonRpcErrorCode.ValidationError)
|
|
134
|
-
throw ctx.fail('invalid_mbid', `Malformed MBID "${params.mbid}"
|
|
135
|
+
throw ctx.fail('invalid_mbid', `Malformed MBID "${params.mbid}".`);
|
|
135
136
|
if (error instanceof McpError && error.code === JsonRpcErrorCode.NotFound)
|
|
136
|
-
throw ctx.fail('entity_not_found', `No ${params.entity_type} exists with MBID ${params.mbid}
|
|
137
|
+
throw ctx.fail('entity_not_found', `No ${params.entity_type} exists with MBID ${params.mbid}.`);
|
|
137
138
|
throw error;
|
|
138
139
|
}
|
|
139
140
|
},
|
|
@@ -221,14 +222,16 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
221
222
|
|
|
222
223
|
| Property | Description |
|
|
223
224
|
|:---------|:------------|
|
|
224
|
-
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Dual-sink: Pino and
|
|
225
|
-
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix,
|
|
226
|
-
| `ctx.requestInput` | Suspend and ask the caller for
|
|
227
|
-
| `ctx.inputs` |
|
|
228
|
-
| `ctx.
|
|
229
|
-
| `ctx.
|
|
225
|
+
| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |
|
|
226
|
+
| `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). Backs the MusicBrainz response cache. |
|
|
227
|
+
| `ctx.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present. |
|
|
228
|
+
| `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |
|
|
229
|
+
| `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |
|
|
230
|
+
| `ctx.enrich` | Success-path agent context — `.echo(query)`, `.total(n)`, `.notice(msg)`, `.truncated()`. Surfaces the effective query, upstream total, and a zero-hits hint without polluting the typed output; lands only when the definition declares an `enrichment` block. |
|
|
231
|
+
| `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
|
|
232
|
+
| `ctx.fail` | Throw a typed contract error by reason (`ctx.fail('invalid_mbid', …)`); the framework fills the declared `recovery` hint. |
|
|
230
233
|
| `ctx.signal` | `AbortSignal` for cancellation — forwarded into every upstream fetch. |
|
|
231
|
-
| `ctx.requestId` |
|
|
234
|
+
| `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
|
|
232
235
|
| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
|
|
233
236
|
|
|
234
237
|
---
|
|
@@ -237,7 +240,7 @@ Handlers receive a unified `ctx` object. Key properties:
|
|
|
237
240
|
|
|
238
241
|
Handlers throw — the framework catches, classifies, and formats.
|
|
239
242
|
|
|
240
|
-
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required
|
|
243
|
+
**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the wire whenever a failure carrying that `reason` arrives without a hint — a bare `ctx.fail('reason')` or a service throw with `data: { reason }` — as `data.recovery.hint`, mirrored into `content[]` text unless the message already contains it verbatim; override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Every error envelope also carries `data.requestId`, the id the server's log records for that call carry, and `content[]` closes with `(reason … · request <id>)`. Mark an entry the service layer throws with `thrownBy: 'service'` so `error-contract-unthrown` skips it — lint-only metadata, nothing at runtime reads it. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
|
|
241
244
|
|
|
242
245
|
```ts
|
|
243
246
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
@@ -270,7 +273,7 @@ throw new Error('Invalid query format'); // → ValidationError
|
|
|
270
273
|
|
|
271
274
|
// McpError — when no factory exists for the code
|
|
272
275
|
import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
273
|
-
throw new McpError(JsonRpcErrorCode.
|
|
276
|
+
throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
|
|
274
277
|
```
|
|
275
278
|
|
|
276
279
|
See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
|
|
@@ -351,19 +354,19 @@ Available skills:
|
|
|
351
354
|
| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
|
|
352
355
|
| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
|
|
353
356
|
| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
|
|
357
|
+
| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
|
|
354
358
|
| `api-auth` | Auth modes, scopes, JWT/OAuth |
|
|
355
359
|
| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
|
|
356
|
-
| `api-mirror` | MirrorService: stand up a self-refreshing local mirror of a bulk upstream dataset (SQLite + FTS5) — Tier 3 opt-in |
|
|
357
360
|
| `api-config` | AppConfig, parseConfig, env vars |
|
|
358
361
|
| `api-context` | Context interface, RequestContext, logger, state, multi-round-trip input |
|
|
359
362
|
| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
|
|
360
363
|
| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
|
|
364
|
+
| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
|
|
361
365
|
| `api-services` | LLM, Speech, Graph services |
|
|
362
366
|
| `api-testing` | createMockContext, test patterns |
|
|
363
367
|
| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
|
|
364
368
|
| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
|
|
365
369
|
| `api-workers` | Cloudflare Workers runtime |
|
|
366
|
-
| `techniques` | Cross-cutting implementation techniques and recipes for the framework |
|
|
367
370
|
|
|
368
371
|
**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
|
|
369
372
|
|
|
@@ -380,16 +383,16 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
380
383
|
| `bun run build` | Compile TypeScript |
|
|
381
384
|
| `bun run rebuild` | Clean + build |
|
|
382
385
|
| `bun run clean` | Remove build artifacts |
|
|
383
|
-
| `bun run devcheck` | Lint + format + typecheck + security +
|
|
386
|
+
| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
|
|
384
387
|
| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
|
|
385
388
|
| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
|
|
386
|
-
| `bun run
|
|
387
|
-
| `bun run
|
|
389
|
+
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
390
|
+
| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
|
|
391
|
+
| `bun run list-skills` | Print the skill registry |
|
|
392
|
+
| `bun run tree` | Generate directory structure doc |
|
|
388
393
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
389
394
|
| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
|
|
390
|
-
| `bun run
|
|
391
|
-
| `bun run lint:packaging` | Validate `manifest.json` ↔ `server.json` env var alignment + bundle/identity guards |
|
|
392
|
-
| `bun run test` | Run the Vitest suite |
|
|
395
|
+
| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
|
|
393
396
|
| `bun run start:stdio` | Production mode (stdio) |
|
|
394
397
|
| `bun run start:http` | Production mode (HTTP) |
|
|
395
398
|
| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
|
|
@@ -397,13 +400,15 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
397
400
|
| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
|
|
398
401
|
| `bun run release:github` | Create the GitHub release from the current tag |
|
|
399
402
|
|
|
403
|
+
**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
|
|
404
|
+
|
|
400
405
|
---
|
|
401
406
|
|
|
402
407
|
## Bundling
|
|
403
408
|
|
|
404
|
-
`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
|
|
409
|
+
`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 two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. 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.
|
|
405
410
|
|
|
406
|
-
**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
|
|
411
|
+
**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, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
|
|
407
412
|
|
|
408
413
|
**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
|
|
409
414
|
|
|
@@ -419,14 +424,14 @@ Each per-version file opens with YAML frontmatter:
|
|
|
419
424
|
---
|
|
420
425
|
summary: "One-line headline, ≤350 chars" # required — powers the rollup index
|
|
421
426
|
breaking: false # optional — true flags breaking changes
|
|
422
|
-
security: false # optional — true
|
|
427
|
+
security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
|
|
423
428
|
---
|
|
424
429
|
|
|
425
430
|
# 0.1.0 — YYYY-MM-DD
|
|
426
431
|
...
|
|
427
432
|
```
|
|
428
433
|
|
|
429
|
-
`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
|
|
434
|
+
`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 — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
|
|
430
435
|
|
|
431
436
|
`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.
|
|
432
437
|
|
|
@@ -438,7 +443,7 @@ security: false # optional — true only for this pro
|
|
|
438
443
|
|
|
439
444
|
## Publishing
|
|
440
445
|
|
|
441
|
-
**Every release goes through a release PR
|
|
446
|
+
**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
|
|
442
447
|
|
|
443
448
|
---
|
|
444
449
|
|
|
@@ -470,8 +475,8 @@ import type { EntityType } from '@/services/musicbrainz/types.js';
|
|
|
470
475
|
- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
|
|
471
476
|
- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
|
|
472
477
|
- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
|
|
473
|
-
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` =
|
|
474
|
-
- [ ] `.codex-plugin/mcp.json` updated — server name key
|
|
475
|
-
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry
|
|
478
|
+
- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
|
|
479
|
+
- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
|
|
480
|
+
- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
|
|
476
481
|
- [ ] All upstream calls route through `getMusicBrainzService()` / `getCoverArtService()` — never `fetch()` MusicBrainz directly. The service owns the mandatory descriptive `User-Agent` (with `MUSICBRAINZ_CONTACT`), the process-wide ~1 req/sec rate limiter, and the response cache; a stray fetch bypasses all three.
|
|
477
482
|
- [ ] `bun run devcheck` passes
|
package/Dockerfile
CHANGED
|
@@ -3,8 +3,18 @@
|
|
|
3
3
|
#
|
|
4
4
|
# This stage installs all dependencies (including dev), builds the TypeScript
|
|
5
5
|
# source code into JavaScript, and prepares the production assets.
|
|
6
|
+
#
|
|
7
|
+
# Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
|
|
8
|
+
# JavaScript, and only `dist/` crosses into the production stage. Built for the
|
|
9
|
+
# target instead, the non-native leg of a `--platform linux/amd64,linux/arm64`
|
|
10
|
+
# build runs under QEMU, where bun >= 1.4 aborts with a JavaScriptCore allocator
|
|
11
|
+
# assertion and fails the multi-arch push.
|
|
12
|
+
#
|
|
13
|
+
# The constraint this assumes: the build stage produces platform-independent
|
|
14
|
+
# output. A stage that compiles a native addon needs the target-arch toolchain
|
|
15
|
+
# and cannot cross-compile this way — drop the flag there.
|
|
6
16
|
# ==============================================================================
|
|
7
|
-
FROM --platform=$BUILDPLATFORM oven/bun:1.4.
|
|
17
|
+
FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS build
|
|
8
18
|
|
|
9
19
|
WORKDIR /usr/src/app
|
|
10
20
|
|
|
@@ -23,19 +33,92 @@ COPY . .
|
|
|
23
33
|
RUN bun run build
|
|
24
34
|
|
|
25
35
|
|
|
36
|
+
# ==============================================================================
|
|
37
|
+
# Production Dependencies Stage
|
|
38
|
+
#
|
|
39
|
+
# Installs the production dependency tree for the target platform. Every step
|
|
40
|
+
# here can run JavaScript — bunfig.toml's security scanner runs as a Bun
|
|
41
|
+
# program, and so do the OTel and musl-prune scripts — so the stage runs on
|
|
42
|
+
# $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
|
|
43
|
+
# platform-specific optional dependency (native bindings such as DuckDB's) for
|
|
44
|
+
# the target. Only `node_modules` leaves this stage.
|
|
45
|
+
#
|
|
46
|
+
# A clean image rather than `FROM build`: the build stage's node_modules holds
|
|
47
|
+
# devDependencies.
|
|
48
|
+
# ==============================================================================
|
|
49
|
+
FROM --platform=$BUILDPLATFORM oven/bun:1.4.2 AS deps
|
|
50
|
+
|
|
51
|
+
WORKDIR /usr/src/app
|
|
52
|
+
|
|
53
|
+
# Copy dependency manifests. `bunfig.toml` rides along so every install below
|
|
54
|
+
# passes its release-age gate and security scanner, as a local install does.
|
|
55
|
+
COPY package.json bun.lock bunfig.toml ./
|
|
56
|
+
|
|
57
|
+
# The scanner bunfig.toml names is a devDependency, and Bun installs a missing
|
|
58
|
+
# scanner through the same production-filtered install, which omits it and
|
|
59
|
+
# aborts. Seed it from the build stage's full install instead. Remove this line,
|
|
60
|
+
# and the `rm` at the end of this stage, if bunfig.toml stops naming a scanner.
|
|
61
|
+
COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
|
|
62
|
+
|
|
63
|
+
# Docker names the target architecture `amd64`/`arm64`; Bun's `--cpu` takes
|
|
64
|
+
# `x64`/`arm64`. Mapped once here, read by both installs below. `oven/bun`
|
|
65
|
+
# publishes only these two architectures, so any other target fails here.
|
|
66
|
+
ARG TARGETOS
|
|
67
|
+
ARG TARGETARCH
|
|
68
|
+
RUN case "$TARGETARCH" in \
|
|
69
|
+
amd64) echo x64 ;; \
|
|
70
|
+
arm64) echo arm64 ;; \
|
|
71
|
+
*) echo "Unsupported TARGETARCH '$TARGETARCH': expected amd64 or arm64" >&2; exit 1 ;; \
|
|
72
|
+
esac > .bun-cpu
|
|
73
|
+
|
|
74
|
+
# Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
|
|
75
|
+
# that are not needed in the final production image.
|
|
76
|
+
# `--omit=peer` drops the framework's optional peer tiers (test runner, service
|
|
77
|
+
# SDKs, parsers) that Bun would otherwise auto-install. Anything this server
|
|
78
|
+
# actually imports belongs in its own `dependencies`, so nothing needed at
|
|
79
|
+
# runtime is lost.
|
|
80
|
+
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
81
|
+
bun install --production --omit=peer --frozen-lockfile --ignore-scripts \
|
|
82
|
+
--os="$TARGETOS" --cpu="$(cat .bun-cpu)"
|
|
83
|
+
|
|
84
|
+
# Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
|
|
85
|
+
# Installed by default. Omit them for a leaner image at build time
|
|
86
|
+
# with: docker build --build-arg OTEL_ENABLED=false
|
|
87
|
+
# The script reads the list and each range from the installed framework's
|
|
88
|
+
# `peerDependencies` and passes the target flags on to its `bun install`.
|
|
89
|
+
COPY scripts/install-otel.ts ./scripts/
|
|
90
|
+
ARG OTEL_ENABLED=true
|
|
91
|
+
RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
92
|
+
if [ "$OTEL_ENABLED" = "true" ]; then \
|
|
93
|
+
bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
|
|
94
|
+
fi
|
|
95
|
+
|
|
96
|
+
# `--os`/`--cpu` have no libc counterpart, so a native dependency published in
|
|
97
|
+
# glibc and musl variants (DuckDB's bindings, for one) installs both. The
|
|
98
|
+
# runtime image is Debian (glibc) and never loads the musl copy; the script
|
|
99
|
+
# deletes every package whose own `libc` admits only musl. It follows every
|
|
100
|
+
# install, since a later `bun install` restores what it removes. A server on a
|
|
101
|
+
# musl (Alpine) runtime image drops these two lines.
|
|
102
|
+
COPY scripts/prune-musl-packages.ts ./scripts/
|
|
103
|
+
RUN bun scripts/prune-musl-packages.ts
|
|
104
|
+
|
|
105
|
+
# The seeded scanner served only the installs above; keep it out of the image.
|
|
106
|
+
RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
|
|
107
|
+
|
|
108
|
+
|
|
26
109
|
# ==============================================================================
|
|
27
110
|
# Production Stage
|
|
28
111
|
#
|
|
29
112
|
# This stage creates a minimal, optimized, and secure image for running the
|
|
30
113
|
# application. It uses a slim base image and only includes production
|
|
31
|
-
# dependencies and build artifacts.
|
|
114
|
+
# dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
|
|
115
|
+
# and CMD, which run on the real target at container start.
|
|
32
116
|
# ==============================================================================
|
|
33
|
-
FROM oven/bun:1.4.
|
|
117
|
+
FROM oven/bun:1.4.2-slim AS production
|
|
34
118
|
|
|
35
119
|
WORKDIR /usr/src/app
|
|
36
120
|
|
|
37
|
-
# Set the environment to production for performance
|
|
38
|
-
# production dependencies are installed.
|
|
121
|
+
# Set the environment to production for performance.
|
|
39
122
|
ENV NODE_ENV=production
|
|
40
123
|
|
|
41
124
|
# OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
|
|
@@ -46,33 +129,10 @@ LABEL org.opencontainers.image.licenses="Apache-2.0"
|
|
|
46
129
|
LABEL org.opencontainers.image.version="${APP_VERSION}"
|
|
47
130
|
LABEL org.opencontainers.image.source="https://github.com/cyanheads/musicbrainz-mcp-server"
|
|
48
131
|
|
|
49
|
-
#
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
# that are not needed in the final production image.
|
|
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
|
|
58
|
-
|
|
59
|
-
# Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
|
|
60
|
-
# These are not bundled by default to keep the base image lean. Enable at build time
|
|
61
|
-
# with: docker build --build-arg OTEL_ENABLED=true
|
|
62
|
-
ARG OTEL_ENABLED=true
|
|
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 \
|
|
66
|
-
@opentelemetry/instrumentation-http \
|
|
67
|
-
@opentelemetry/exporter-metrics-otlp-http \
|
|
68
|
-
@opentelemetry/exporter-trace-otlp-http \
|
|
69
|
-
@opentelemetry/instrumentation-pino \
|
|
70
|
-
@opentelemetry/resources \
|
|
71
|
-
@opentelemetry/sdk-metrics \
|
|
72
|
-
@opentelemetry/sdk-node \
|
|
73
|
-
@opentelemetry/sdk-trace-node \
|
|
74
|
-
@opentelemetry/semantic-conventions; \
|
|
75
|
-
fi
|
|
132
|
+
# The manifest comes from the build context: the deps stage's copy was rewritten
|
|
133
|
+
# by the OTel install, and the runtime reads only its name, version, and type.
|
|
134
|
+
COPY package.json ./
|
|
135
|
+
COPY --from=deps /usr/src/app/node_modules ./node_modules
|
|
76
136
|
|
|
77
137
|
# Copy the compiled application code from the build stage
|
|
78
138
|
COPY --from=build /usr/src/app/dist ./dist
|
|
@@ -115,7 +175,6 @@ ENV MCP_TRANSPORT_TYPE="http"
|
|
|
115
175
|
ENV MCP_SESSION_MODE="stateless"
|
|
116
176
|
ENV MCP_LOG_LEVEL="info"
|
|
117
177
|
ENV LOGS_DIR="/var/log/musicbrainz-mcp-server"
|
|
118
|
-
ENV MCP_FORCE_CONSOLE_LOGGING="true"
|
|
119
178
|
|
|
120
179
|
# Expose the port the server listens on
|
|
121
180
|
EXPOSE ${MCP_HTTP_PORT}
|