@cyanheads/musicbrainz-mcp-server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/AGENTS.md +466 -0
  2. package/CLAUDE.md +466 -0
  3. package/Dockerfile +121 -0
  4. package/LICENSE +201 -0
  5. package/README.md +329 -0
  6. package/changelog/0.1.x/0.1.0.md +27 -0
  7. package/changelog/template.md +127 -0
  8. package/dist/config/server-config.d.ts +24 -0
  9. package/dist/config/server-config.d.ts.map +1 -0
  10. package/dist/config/server-config.js +90 -0
  11. package/dist/config/server-config.js.map +1 -0
  12. package/dist/index.d.ts +10 -0
  13. package/dist/index.d.ts.map +1 -0
  14. package/dist/index.js +27 -0
  15. package/dist/index.js.map +1 -0
  16. package/dist/mcp-server/resources/definitions/entity.resource.d.ts +33 -0
  17. package/dist/mcp-server/resources/definitions/entity.resource.d.ts.map +1 -0
  18. package/dist/mcp-server/resources/definitions/entity.resource.js +72 -0
  19. package/dist/mcp-server/resources/definitions/entity.resource.js.map +1 -0
  20. package/dist/mcp-server/resources/definitions/index.d.ts +27 -0
  21. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -0
  22. package/dist/mcp-server/resources/definitions/index.js +8 -0
  23. package/dist/mcp-server/resources/definitions/index.js.map +1 -0
  24. package/dist/mcp-server/tools/definitions/_shared.d.ts +105 -0
  25. package/dist/mcp-server/tools/definitions/_shared.d.ts.map +1 -0
  26. package/dist/mcp-server/tools/definitions/_shared.js +382 -0
  27. package/dist/mcp-server/tools/definitions/_shared.js.map +1 -0
  28. package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts +62 -0
  29. package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts.map +1 -0
  30. package/dist/mcp-server/tools/definitions/browse-entities.tool.js +236 -0
  31. package/dist/mcp-server/tools/definitions/browse-entities.tool.js.map +1 -0
  32. package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts +78 -0
  33. package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts.map +1 -0
  34. package/dist/mcp-server/tools/definitions/get-artist.tool.js +200 -0
  35. package/dist/mcp-server/tools/definitions/get-artist.tool.js.map +1 -0
  36. package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts +42 -0
  37. package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts.map +1 -0
  38. package/dist/mcp-server/tools/definitions/get-cover-art.tool.js +149 -0
  39. package/dist/mcp-server/tools/definitions/get-cover-art.tool.js.map +1 -0
  40. package/dist/mcp-server/tools/definitions/get-label.tool.d.ts +52 -0
  41. package/dist/mcp-server/tools/definitions/get-label.tool.d.ts.map +1 -0
  42. package/dist/mcp-server/tools/definitions/get-label.tool.js +110 -0
  43. package/dist/mcp-server/tools/definitions/get-label.tool.js.map +1 -0
  44. package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts +58 -0
  45. package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts.map +1 -0
  46. package/dist/mcp-server/tools/definitions/get-recording.tool.js +135 -0
  47. package/dist/mcp-server/tools/definitions/get-recording.tool.js.map +1 -0
  48. package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts +55 -0
  49. package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts.map +1 -0
  50. package/dist/mcp-server/tools/definitions/get-release-group.tool.js +140 -0
  51. package/dist/mcp-server/tools/definitions/get-release-group.tool.js.map +1 -0
  52. package/dist/mcp-server/tools/definitions/get-release.tool.d.ts +66 -0
  53. package/dist/mcp-server/tools/definitions/get-release.tool.d.ts.map +1 -0
  54. package/dist/mcp-server/tools/definitions/get-release.tool.js +213 -0
  55. package/dist/mcp-server/tools/definitions/get-release.tool.js.map +1 -0
  56. package/dist/mcp-server/tools/definitions/get-work.tool.d.ts +62 -0
  57. package/dist/mcp-server/tools/definitions/get-work.tool.d.ts.map +1 -0
  58. package/dist/mcp-server/tools/definitions/get-work.tool.js +132 -0
  59. package/dist/mcp-server/tools/definitions/get-work.tool.js.map +1 -0
  60. package/dist/mcp-server/tools/definitions/index.d.ts +468 -0
  61. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -0
  62. package/dist/mcp-server/tools/definitions/index.js +28 -0
  63. package/dist/mcp-server/tools/definitions/index.js.map +1 -0
  64. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts +59 -0
  65. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts.map +1 -0
  66. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js +214 -0
  67. package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js.map +1 -0
  68. package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts +42 -0
  69. package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map +1 -0
  70. package/dist/mcp-server/tools/definitions/search-entities.tool.js +187 -0
  71. package/dist/mcp-server/tools/definitions/search-entities.tool.js.map +1 -0
  72. package/dist/services/cover-art/cover-art-service.d.ts +40 -0
  73. package/dist/services/cover-art/cover-art-service.d.ts.map +1 -0
  74. package/dist/services/cover-art/cover-art-service.js +118 -0
  75. package/dist/services/cover-art/cover-art-service.js.map +1 -0
  76. package/dist/services/musicbrainz/musicbrainz-service.d.ts +81 -0
  77. package/dist/services/musicbrainz/musicbrainz-service.d.ts.map +1 -0
  78. package/dist/services/musicbrainz/musicbrainz-service.js +188 -0
  79. package/dist/services/musicbrainz/musicbrainz-service.js.map +1 -0
  80. package/dist/services/musicbrainz/rate-limiter.d.ts +32 -0
  81. package/dist/services/musicbrainz/rate-limiter.d.ts.map +1 -0
  82. package/dist/services/musicbrainz/rate-limiter.js +54 -0
  83. package/dist/services/musicbrainz/rate-limiter.js.map +1 -0
  84. package/dist/services/musicbrainz/types.d.ts +301 -0
  85. package/dist/services/musicbrainz/types.d.ts.map +1 -0
  86. package/dist/services/musicbrainz/types.js +11 -0
  87. package/dist/services/musicbrainz/types.js.map +1 -0
  88. package/package.json +103 -0
  89. package/server.json +111 -0
@@ -0,0 +1,28 @@
1
+ /**
2
+ * @fileoverview Barrel collecting all MusicBrainz tool definitions into the
3
+ * `allToolDefinitions` array consumed by createApp().
4
+ * @module mcp-server/tools/definitions/index
5
+ */
6
+ import { browseEntitiesTool } from './browse-entities.tool.js';
7
+ import { getArtistTool } from './get-artist.tool.js';
8
+ import { getCoverArtTool } from './get-cover-art.tool.js';
9
+ import { getLabelTool } from './get-label.tool.js';
10
+ import { getRecordingTool } from './get-recording.tool.js';
11
+ import { getReleaseTool } from './get-release.tool.js';
12
+ import { getReleaseGroupTool } from './get-release-group.tool.js';
13
+ import { getWorkTool } from './get-work.tool.js';
14
+ import { lookupIdentifierTool } from './lookup-identifier.tool.js';
15
+ import { searchEntitiesTool } from './search-entities.tool.js';
16
+ export const allToolDefinitions = [
17
+ searchEntitiesTool,
18
+ getArtistTool,
19
+ getReleaseGroupTool,
20
+ getReleaseTool,
21
+ getRecordingTool,
22
+ getWorkTool,
23
+ getLabelTool,
24
+ lookupIdentifierTool,
25
+ browseEntitiesTool,
26
+ getCoverArtTool,
27
+ ];
28
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,kBAAkB;IAClB,aAAa;IACb,mBAAmB;IACnB,cAAc;IACd,gBAAgB;IAChB,WAAW;IACX,YAAY;IACZ,oBAAoB;IACpB,kBAAkB;IAClB,eAAe;CAChB,CAAC"}
@@ -0,0 +1,59 @@
1
+ /**
2
+ * @fileoverview musicbrainz_lookup_identifier — resolve a standard identifier to
3
+ * MusicBrainz entities without a name search: the deterministic path when you
4
+ * already hold an ID. ISRC → recordings, ISWC → works, barcode → releases. The
5
+ * output is a discriminated union on the resolved entity type, so the agent knows
6
+ * what it is holding.
7
+ * @module mcp-server/tools/definitions/lookup-identifier.tool
8
+ */
9
+ import { z } from '@cyanheads/mcp-ts-core';
10
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
11
+ export declare const lookupIdentifierTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
12
+ id_type: z.ZodEnum<{
13
+ barcode: "barcode";
14
+ isrc: "isrc";
15
+ iswc: "iswc";
16
+ }>;
17
+ value: z.ZodString;
18
+ }, z.core.$strip>, z.ZodObject<{
19
+ result: z.ZodDiscriminatedUnion<[z.ZodObject<{
20
+ kind: z.ZodLiteral<"recordings">;
21
+ identifier: z.ZodString;
22
+ recordings: z.ZodArray<z.ZodObject<{
23
+ mbid: z.ZodString;
24
+ title: z.ZodString;
25
+ artistCredit: z.ZodString;
26
+ length: z.ZodOptional<z.ZodString>;
27
+ }, z.core.$strip>>;
28
+ }, z.core.$strip>, z.ZodObject<{
29
+ kind: z.ZodLiteral<"works">;
30
+ identifier: z.ZodString;
31
+ works: z.ZodArray<z.ZodObject<{
32
+ mbid: z.ZodString;
33
+ title: z.ZodString;
34
+ type: z.ZodOptional<z.ZodString>;
35
+ }, z.core.$strip>>;
36
+ }, z.core.$strip>, z.ZodObject<{
37
+ kind: z.ZodLiteral<"releases">;
38
+ identifier: z.ZodString;
39
+ releases: z.ZodArray<z.ZodObject<{
40
+ mbid: z.ZodString;
41
+ title: z.ZodString;
42
+ artistCredit: z.ZodString;
43
+ date: z.ZodOptional<z.ZodString>;
44
+ country: z.ZodOptional<z.ZodString>;
45
+ score: z.ZodNumber;
46
+ }, z.core.$strip>>;
47
+ }, z.core.$strip>], "kind">;
48
+ }, z.core.$strip>, readonly [{
49
+ readonly reason: "identifier_not_found";
50
+ readonly code: JsonRpcErrorCode.NotFound;
51
+ readonly when: "The identifier is well-formed but resolves to zero entities.";
52
+ readonly recovery: "No entity carries that identifier. Check the value, or search by name with musicbrainz_search_entities.";
53
+ }, {
54
+ readonly reason: "invalid_identifier";
55
+ readonly code: JsonRpcErrorCode.InvalidParams;
56
+ readonly when: "The ISRC/ISWC is malformed (the dedicated endpoint returns HTTP 400).";
57
+ readonly recovery: "ISRC is 12 chars (e.g. USRC17607839); ISWC is T- followed by 10 digits (e.g. T-345246800-1). Verify the format.";
58
+ }], undefined>;
59
+ //# sourceMappingURL=lookup-identifier.tool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lookup-identifier.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/lookup-identifier.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAmD3E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkL/B,CAAC"}
@@ -0,0 +1,214 @@
1
+ /**
2
+ * @fileoverview musicbrainz_lookup_identifier — resolve a standard identifier to
3
+ * MusicBrainz entities without a name search: the deterministic path when you
4
+ * already hold an ID. ISRC → recordings, ISWC → works, barcode → releases. The
5
+ * output is a discriminated union on the resolved entity type, so the agent knows
6
+ * what it is holding.
7
+ * @module mcp-server/tools/definitions/lookup-identifier.tool
8
+ */
9
+ import { tool, z } from '@cyanheads/mcp-ts-core';
10
+ import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
11
+ import { getMusicBrainzService } from '../../../services/musicbrainz/musicbrainz-service.js';
12
+ import { artistCreditString, formatDuration, normalizeArtistCredits, safeText } from './_shared.js';
13
+ /**
14
+ * Classify an upstream error from a dedicated ISRC/ISWC endpoint: a malformed
15
+ * identifier returns HTTP 400 (`InvalidParams`); a well-formed-but-unknown one
16
+ * returns 404 (`NotFound`). Returns the contract reason or `null` (transient
17
+ * failures bubble). Handlers call `ctx.fail(reason, …)` so the reason stays
18
+ * lexically inside the handler for conformance lint.
19
+ */
20
+ function classifyIdentifierError(error) {
21
+ if (!(error instanceof McpError))
22
+ return null;
23
+ if (error.code === JsonRpcErrorCode.InvalidParams)
24
+ return 'invalid_identifier';
25
+ if (error.code === JsonRpcErrorCode.NotFound)
26
+ return 'identifier_not_found';
27
+ return null;
28
+ }
29
+ const RecordingHitSchema = z
30
+ .object({
31
+ mbid: z.string().describe('Recording MBID — chain to musicbrainz_get_recording.'),
32
+ title: z.string().describe('Recording title.'),
33
+ artistCredit: z.string().describe('Credited artist string.'),
34
+ length: z.string().optional().describe('Recording length as m:ss. Omitted when unknown.'),
35
+ })
36
+ .describe('A recording carrying the looked-up ISRC.');
37
+ const WorkHitSchema = z
38
+ .object({
39
+ mbid: z.string().describe('Work MBID — chain to musicbrainz_get_work.'),
40
+ title: z.string().describe('Work title.'),
41
+ type: z.string().optional().describe('Work type. Omitted when absent.'),
42
+ })
43
+ .describe('A work carrying the looked-up ISWC.');
44
+ const ReleaseHitSchema = z
45
+ .object({
46
+ mbid: z.string().describe('Release MBID — chain to musicbrainz_get_release.'),
47
+ title: z.string().describe('Release title.'),
48
+ artistCredit: z.string().describe('Credited artist string.'),
49
+ date: z.string().optional().describe('Release date. Omitted when absent.'),
50
+ country: z.string().optional().describe('Release country code. Omitted when absent.'),
51
+ score: z
52
+ .number()
53
+ .describe('Lucene relevance score, 0–100 (barcode is a search filter; exact = 100).'),
54
+ })
55
+ .describe('A release carrying the looked-up barcode.');
56
+ export const lookupIdentifierTool = tool('musicbrainz_lookup_identifier', {
57
+ title: 'musicbrainz-mcp-server: lookup identifier',
58
+ description: 'Resolve a standard identifier to MusicBrainz entities without a name search — the deterministic path when you already hold an ID. id_type=isrc → recordings (a recording-level code, often shared by several recordings); id_type=iswc → works (a composition-level code); id_type=barcode → releases (UPC/EAN). ISRC and ISWC hit dedicated exact endpoints; barcode is a Lucene search filter so results are ranked (exact match scores 100). The output kind field tells you which entity type came back.',
59
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
60
+ errors: [
61
+ {
62
+ reason: 'identifier_not_found',
63
+ code: JsonRpcErrorCode.NotFound,
64
+ when: 'The identifier is well-formed but resolves to zero entities.',
65
+ recovery: 'No entity carries that identifier. Check the value, or search by name with musicbrainz_search_entities.',
66
+ },
67
+ {
68
+ reason: 'invalid_identifier',
69
+ code: JsonRpcErrorCode.InvalidParams,
70
+ when: 'The ISRC/ISWC is malformed (the dedicated endpoint returns HTTP 400).',
71
+ recovery: 'ISRC is 12 chars (e.g. USRC17607839); ISWC is T- followed by 10 digits (e.g. T-345246800-1). Verify the format.',
72
+ },
73
+ ],
74
+ input: z.object({
75
+ id_type: z
76
+ .enum(['isrc', 'iswc', 'barcode'])
77
+ .describe('Which standard identifier: isrc (recording), iswc (work), or barcode (release).'),
78
+ value: z
79
+ .string()
80
+ .min(1)
81
+ .describe('The identifier value. ISRC e.g. "USRC17607839"; ISWC e.g. "T-345246800-1"; barcode e.g. "075678164125".'),
82
+ }),
83
+ // The resolved entity type varies by id_type, so `result` is a discriminated
84
+ // union on `kind`. Wrapped in an object because the tool() output slot is a
85
+ // ZodObject; `format()` validates each union arm separately for parity.
86
+ output: z.object({
87
+ result: z
88
+ .discriminatedUnion('kind', [
89
+ z
90
+ .object({
91
+ kind: z.literal('recordings').describe('ISRC resolved to recordings.'),
92
+ identifier: z.string().describe('The looked-up identifier value.'),
93
+ recordings: z.array(RecordingHitSchema).describe('Recordings carrying this ISRC.'),
94
+ })
95
+ .describe('ISRC result arm: recordings carrying the ISRC.'),
96
+ z
97
+ .object({
98
+ kind: z.literal('works').describe('ISWC resolved to works.'),
99
+ identifier: z.string().describe('The looked-up identifier value.'),
100
+ works: z.array(WorkHitSchema).describe('Works carrying this ISWC.'),
101
+ })
102
+ .describe('ISWC result arm: works carrying the ISWC.'),
103
+ z
104
+ .object({
105
+ kind: z.literal('releases').describe('Barcode resolved to releases.'),
106
+ identifier: z.string().describe('The looked-up identifier value.'),
107
+ releases: z
108
+ .array(ReleaseHitSchema)
109
+ .describe('Releases carrying this barcode (ranked).'),
110
+ })
111
+ .describe('Barcode result arm: releases carrying the barcode.'),
112
+ ])
113
+ .describe('The resolved entities, discriminated by `kind` (recordings | works | releases).'),
114
+ }),
115
+ async handler(input, ctx) {
116
+ ctx.log.info('musicbrainz_lookup_identifier', { id_type: input.id_type, value: input.value });
117
+ const service = getMusicBrainzService();
118
+ if (input.id_type === 'isrc') {
119
+ let envelope;
120
+ try {
121
+ envelope = await service.resolveIsrc(input.value, ctx, { signal: ctx.signal });
122
+ }
123
+ catch (error) {
124
+ const reason = classifyIdentifierError(error);
125
+ if (reason)
126
+ throw ctx.fail(reason, `Identifier "${input.value}" — ${reason}.`, {
127
+ ...ctx.recoveryFor(reason),
128
+ });
129
+ throw error;
130
+ }
131
+ const recordings = (envelope.recordings ?? []).map((r) => {
132
+ const length = formatDuration(r.length);
133
+ return {
134
+ mbid: r.id,
135
+ title: r.title ?? '',
136
+ artistCredit: artistCreditString(normalizeArtistCredits(r['artist-credit'])),
137
+ ...(length ? { length } : {}),
138
+ };
139
+ });
140
+ if (recordings.length === 0) {
141
+ throw ctx.fail('identifier_not_found', `No recording carries ISRC ${input.value}.`, {
142
+ ...ctx.recoveryFor('identifier_not_found'),
143
+ });
144
+ }
145
+ return { result: { kind: 'recordings', identifier: input.value, recordings } };
146
+ }
147
+ if (input.id_type === 'iswc') {
148
+ let envelope;
149
+ try {
150
+ envelope = await service.resolveIswc(input.value, ctx, { signal: ctx.signal });
151
+ }
152
+ catch (error) {
153
+ const reason = classifyIdentifierError(error);
154
+ if (reason)
155
+ throw ctx.fail(reason, `Identifier "${input.value}" — ${reason}.`, {
156
+ ...ctx.recoveryFor(reason),
157
+ });
158
+ throw error;
159
+ }
160
+ const works = (envelope.works ?? []).map((w) => ({
161
+ mbid: w.id,
162
+ title: w.title ?? '',
163
+ ...(w.type ? { type: w.type } : {}),
164
+ }));
165
+ if (works.length === 0) {
166
+ throw ctx.fail('identifier_not_found', `No work carries ISWC ${input.value}.`, {
167
+ ...ctx.recoveryFor('identifier_not_found'),
168
+ });
169
+ }
170
+ return { result: { kind: 'works', identifier: input.value, works } };
171
+ }
172
+ // barcode — Lucene search filter on releases (ranked, not a dedicated endpoint).
173
+ const envelope = await service.search('release', `barcode:${input.value}`, { limit: 25, offset: 0 }, ctx, { signal: ctx.signal });
174
+ const releases = (envelope.releases ?? []).map((r) => ({
175
+ mbid: r.id,
176
+ title: r.title ?? '',
177
+ artistCredit: artistCreditString(normalizeArtistCredits(r['artist-credit'])),
178
+ ...(r.date ? { date: r.date } : {}),
179
+ ...(r.country ? { country: r.country } : {}),
180
+ score: typeof r.score === 'number' ? r.score : 0,
181
+ }));
182
+ if (releases.length === 0) {
183
+ throw ctx.fail('identifier_not_found', `No release carries barcode ${input.value}.`, {
184
+ ...ctx.recoveryFor('identifier_not_found'),
185
+ });
186
+ }
187
+ return { result: { kind: 'releases', identifier: input.value, releases } };
188
+ },
189
+ format: (output) => {
190
+ const result = output.result;
191
+ const lines = [`## Identifier lookup: ${safeText(result.identifier)}`];
192
+ if (result.kind === 'recordings') {
193
+ lines.push(`**Resolved to ${result.recordings.length} recording(s):**`);
194
+ for (const r of result.recordings) {
195
+ lines.push(`- **${safeText(r.title)}** — ${safeText(r.artistCredit)}${r.length ? ` (${r.length})` : ''} — ${r.mbid}`);
196
+ }
197
+ }
198
+ else if (result.kind === 'works') {
199
+ lines.push(`**Resolved to ${result.works.length} work(s):**`);
200
+ for (const w of result.works) {
201
+ lines.push(`- **${safeText(w.title)}**${w.type ? ` (${safeText(w.type)})` : ''} — ${w.mbid}`);
202
+ }
203
+ }
204
+ else {
205
+ lines.push(`**Resolved to ${result.releases.length} release(s):**`);
206
+ for (const r of result.releases) {
207
+ const meta = [r.date, r.country].filter(Boolean).join(', ');
208
+ lines.push(`- **${safeText(r.title)}** — ${safeText(r.artistCredit)}${meta ? ` (${meta})` : ''} [score ${r.score}] — ${r.mbid}`);
209
+ }
210
+ }
211
+ return [{ type: 'text', text: lines.join('\n') }];
212
+ },
213
+ });
214
+ //# sourceMappingURL=lookup-identifier.tool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lookup-identifier.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/lookup-identifier.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+CAA+C,CAAC;AAEtF,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,sBAAsB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEpG;;;;;;GAMG;AACH,SAAS,uBAAuB,CAC9B,KAAc;IAEd,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC,aAAa;QAAE,OAAO,oBAAoB,CAAC;IAC/E,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC,QAAQ;QAAE,OAAO,sBAAsB,CAAC;IAC5E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,kBAAkB,GAAG,CAAC;KACzB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IACjF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAC9C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAC5D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;CAC1F,CAAC;KACD,QAAQ,CAAC,0CAA0C,CAAC,CAAC;AAExD,MAAM,aAAa,GAAG,CAAC;KACpB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACvE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC;IACzC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;CACxE,CAAC;KACD,QAAQ,CAAC,qCAAqC,CAAC,CAAC;AAEnD,MAAM,gBAAgB,GAAG,CAAC;KACvB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IAC7E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAC5C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAC5D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IAC1E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACrF,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,CAAC,0EAA0E,CAAC;CACxF,CAAC;KACD,QAAQ,CAAC,2CAA2C,CAAC,CAAC;AAEzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC,+BAA+B,EAAE;IACxE,KAAK,EAAE,2CAA2C;IAClD,WAAW,EACT,8eAA8e;IAChf,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAE9E,MAAM,EAAE;QACN;YACE,MAAM,EAAE,sBAAsB;YAC9B,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,8DAA8D;YACpE,QAAQ,EACN,yGAAyG;SAC5G;QACD;YACE,MAAM,EAAE,oBAAoB;YAC5B,IAAI,EAAE,gBAAgB,CAAC,aAAa;YACpC,IAAI,EAAE,uEAAuE;YAC7E,QAAQ,EACN,iHAAiH;SACpH;KACF;IAED,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,OAAO,EAAE,CAAC;aACP,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;aACjC,QAAQ,CAAC,iFAAiF,CAAC;QAC9F,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CACP,yGAAyG,CAC1G;KACJ,CAAC;IAEF,6EAA6E;IAC7E,4EAA4E;IAC5E,wEAAwE;IACxE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,MAAM,EAAE,CAAC;aACN,kBAAkB,CAAC,MAAM,EAAE;YAC1B,CAAC;iBACE,MAAM,CAAC;gBACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,8BAA8B,CAAC;gBACtE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;gBAClE,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,QAAQ,CAAC,gCAAgC,CAAC;aACnF,CAAC;iBACD,QAAQ,CAAC,gDAAgD,CAAC;YAC7D,CAAC;iBACE,MAAM,CAAC;gBACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC;gBAC5D,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;gBAClE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,2BAA2B,CAAC;aACpE,CAAC;iBACD,QAAQ,CAAC,2CAA2C,CAAC;YACxD,CAAC;iBACE,MAAM,CAAC;gBACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,+BAA+B,CAAC;gBACrE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;gBAClE,QAAQ,EAAE,CAAC;qBACR,KAAK,CAAC,gBAAgB,CAAC;qBACvB,QAAQ,CAAC,0CAA0C,CAAC;aACxD,CAAC;iBACD,QAAQ,CAAC,oDAAoD,CAAC;SAClE,CAAC;aACD,QAAQ,CAAC,iFAAiF,CAAC;KAC/F,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9F,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;QAExC,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YAC7B,IAAI,QAAyC,CAAC;YAC9C,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACjF,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,MAAM,MAAM,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;gBAC9C,IAAI,MAAM;oBACR,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,KAAK,CAAC,KAAK,OAAO,MAAM,GAAG,EAAE;wBACjE,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC;qBAC3B,CAAC,CAAC;gBACL,MAAM,KAAK,CAAC;YACd,CAAC;YACD,MAAM,UAAU,GAAG,CAAC,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACvD,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;gBACxC,OAAO;oBACL,IAAI,EAAE,CAAC,CAAC,EAAE;oBACV,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE;oBACpB,YAAY,EAAE,kBAAkB,CAAC,sBAAsB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;oBAC5E,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC9B,CAAC;YACJ,CAAC,CAAC,CAAC;YACH,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE,6BAA6B,KAAK,CAAC,KAAK,GAAG,EAAE;oBAClF,GAAG,GAAG,CAAC,WAAW,CAAC,sBAAsB,CAAC;iBAC3C,CAAC,CAAC;YACL,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,YAAqB,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;QAC1F,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YAC7B,IAAI,QAA+B,CAAC;YACpC,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACjF,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,MAAM,MAAM,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;gBAC9C,IAAI,MAAM;oBACR,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,KAAK,CAAC,KAAK,OAAO,MAAM,GAAG,EAAE;wBACjE,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC;qBAC3B,CAAC,CAAC;gBACL,MAAM,KAAK,CAAC;YACd,CAAC;YACD,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/C,IAAI,EAAE,CAAC,CAAC,EAAE;gBACV,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE;gBACpB,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACpC,CAAC,CAAC,CAAC;YACJ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,MAAM,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE,wBAAwB,KAAK,CAAC,KAAK,GAAG,EAAE;oBAC7E,GAAG,GAAG,CAAC,WAAW,CAAC,sBAAsB,CAAC;iBAC3C,CAAC,CAAC;YACL,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAgB,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;QAChF,CAAC;QAED,iFAAiF;QACjF,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CACnC,SAAS,EACT,WAAW,KAAK,CAAC,KAAK,EAAE,EACxB,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EACxB,GAAG,EACH,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CACvB,CAAC;QACF,MAAM,QAAQ,GAAG,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAa,EAAE,EAAE,CAAC,CAAC;YACjE,IAAI,EAAE,CAAC,CAAC,EAAE;YACV,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE;YACpB,YAAY,EAAE,kBAAkB,CAAC,sBAAsB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;YAC5E,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,KAAK,EAAE,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACjD,CAAC,CAAC,CAAC;QACJ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE,8BAA8B,KAAK,CAAC,KAAK,GAAG,EAAE;gBACnF,GAAG,GAAG,CAAC,WAAW,CAAC,sBAAsB,CAAC;aAC3C,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,UAAmB,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC;IACtF,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,MAAM,KAAK,GAAa,CAAC,yBAAyB,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACjF,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,UAAU,CAAC,MAAM,kBAAkB,CAAC,CAAC;YACxE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBAClC,KAAK,CAAC,IAAI,CACR,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAC1G,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,KAAK,CAAC,MAAM,aAAa,CAAC,CAAC;YAC9D,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CACR,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAClF,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,QAAQ,CAAC,MAAM,gBAAgB,CAAC,CAAC;YACpE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBAChC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC5D,KAAK,CAAC,IAAI,CACR,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,IAAI,EAAE,CACrH,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}
@@ -0,0 +1,42 @@
1
+ /**
2
+ * @fileoverview musicbrainz_search_entities — full-text Lucene search across one
3
+ * MusicBrainz entity type, returning ranked lightweight matches (MBID, name,
4
+ * disambiguation, type, 0–100 relevance score). The required first step when
5
+ * starting from a name rather than an MBID; chain the returned MBID into the
6
+ * matching get_* tool.
7
+ * @module mcp-server/tools/definitions/search-entities.tool
8
+ */
9
+ import { z } from '@cyanheads/mcp-ts-core';
10
+ export declare const searchEntitiesTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
11
+ entityType: z.ZodEnum<{
12
+ artist: "artist";
13
+ "release-group": "release-group";
14
+ release: "release";
15
+ recording: "recording";
16
+ work: "work";
17
+ label: "label";
18
+ }>;
19
+ query: z.ZodString;
20
+ limit: z.ZodDefault<z.ZodNumber>;
21
+ offset: z.ZodDefault<z.ZodNumber>;
22
+ }, z.core.$strip>, z.ZodObject<{
23
+ entityType: z.ZodString;
24
+ results: z.ZodArray<z.ZodObject<{
25
+ mbid: z.ZodString;
26
+ name: z.ZodString;
27
+ score: z.ZodNumber;
28
+ disambiguation: z.ZodOptional<z.ZodString>;
29
+ type: z.ZodOptional<z.ZodString>;
30
+ artistCredit: z.ZodOptional<z.ZodString>;
31
+ date: z.ZodOptional<z.ZodString>;
32
+ country: z.ZodOptional<z.ZodString>;
33
+ length: z.ZodOptional<z.ZodString>;
34
+ isrcs: z.ZodOptional<z.ZodArray<z.ZodString>>;
35
+ iswcs: z.ZodOptional<z.ZodArray<z.ZodString>>;
36
+ }, z.core.$strip>>;
37
+ }, z.core.$strip>, undefined, {
38
+ readonly effectiveQuery: z.ZodString;
39
+ readonly totalCount: z.ZodNumber;
40
+ readonly notice: z.ZodOptional<z.ZodString>;
41
+ }>;
42
+ //# sourceMappingURL=search-entities.tool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"search-entities.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-entities.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AA+HjD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyF7B,CAAC"}
@@ -0,0 +1,187 @@
1
+ /**
2
+ * @fileoverview musicbrainz_search_entities — full-text Lucene search across one
3
+ * MusicBrainz entity type, returning ranked lightweight matches (MBID, name,
4
+ * disambiguation, type, 0–100 relevance score). The required first step when
5
+ * starting from a name rather than an MBID; chain the returned MBID into the
6
+ * matching get_* tool.
7
+ * @module mcp-server/tools/definitions/search-entities.tool
8
+ */
9
+ import { tool, z } from '@cyanheads/mcp-ts-core';
10
+ import { getMusicBrainzService, MusicBrainzService, } from '../../../services/musicbrainz/musicbrainz-service.js';
11
+ import { artistCreditString, formatDuration, normalizeArtistCredits, safeText } from './_shared.js';
12
+ const ENTITY_TYPES = ['artist', 'release-group', 'release', 'recording', 'work', 'label'];
13
+ const ResultSchema = z
14
+ .object({
15
+ mbid: z
16
+ .string()
17
+ .describe('MusicBrainz identifier (UUID) — chain into the matching musicbrainz_get_* tool.'),
18
+ name: z
19
+ .string()
20
+ .describe('Entity name (artist/label) or title (release-group/release/recording/work).'),
21
+ score: z
22
+ .number()
23
+ .describe('Lucene relevance score, 0–100. 100 = exact match; low scores are weak partial matches.'),
24
+ disambiguation: z
25
+ .string()
26
+ .optional()
27
+ .describe('Short qualifier distinguishing same-named entities. Omitted when absent.'),
28
+ type: z
29
+ .string()
30
+ .optional()
31
+ .describe('Entity subtype (artist type, release-group primary type, work type, label type). Omitted when absent.'),
32
+ artistCredit: z
33
+ .string()
34
+ .optional()
35
+ .describe('Credited artist string, for release-group/release/recording results. Omitted for artist/label/work.'),
36
+ date: z
37
+ .string()
38
+ .optional()
39
+ .describe('First-release date (release-group) or release date (release). Omitted when absent.'),
40
+ country: z
41
+ .string()
42
+ .optional()
43
+ .describe('Country code, for release/artist/label results. Omitted when absent.'),
44
+ length: z.string().optional().describe('Recording length as m:ss. Omitted when unknown.'),
45
+ isrcs: z
46
+ .array(z.string())
47
+ .optional()
48
+ .describe('ISRCs on a recording result. Omitted when none.'),
49
+ iswcs: z.array(z.string()).optional().describe('ISWCs on a work result. Omitted when none.'),
50
+ })
51
+ .describe('A ranked search hit. Type-specific fields appear only for the relevant entity type.');
52
+ function mapHit(type, raw) {
53
+ const base = raw;
54
+ const score = typeof base.score === 'number' ? base.score : 0;
55
+ const disambiguation = base.disambiguation?.trim();
56
+ if (type === 'artist' || type === 'label') {
57
+ const e = raw;
58
+ return {
59
+ mbid: e.id,
60
+ name: e.name ?? '',
61
+ score,
62
+ ...(disambiguation ? { disambiguation } : {}),
63
+ ...(e.type ? { type: e.type } : {}),
64
+ ...(e.country ? { country: e.country } : {}),
65
+ };
66
+ }
67
+ if (type === 'work') {
68
+ const e = raw;
69
+ return {
70
+ mbid: e.id,
71
+ name: e.title ?? '',
72
+ score,
73
+ ...(disambiguation ? { disambiguation } : {}),
74
+ ...(e.type ? { type: e.type } : {}),
75
+ ...(e.iswcs?.length ? { iswcs: e.iswcs } : {}),
76
+ };
77
+ }
78
+ if (type === 'recording') {
79
+ const e = raw;
80
+ const length = formatDuration(e.length);
81
+ return {
82
+ mbid: e.id,
83
+ name: e.title ?? '',
84
+ score,
85
+ ...(disambiguation ? { disambiguation } : {}),
86
+ artistCredit: artistCreditString(normalizeArtistCredits(e['artist-credit'])),
87
+ ...(length ? { length } : {}),
88
+ ...(e.isrcs?.length ? { isrcs: e.isrcs } : {}),
89
+ };
90
+ }
91
+ // release-group | release
92
+ const e = raw;
93
+ const isReleaseGroup = type === 'release-group';
94
+ const date = isReleaseGroup
95
+ ? e['first-release-date']
96
+ : e.date;
97
+ const primaryType = isReleaseGroup
98
+ ? e['primary-type']
99
+ : e.status;
100
+ return {
101
+ mbid: e.id,
102
+ name: e.title ?? '',
103
+ score,
104
+ ...(disambiguation ? { disambiguation } : {}),
105
+ ...(primaryType ? { type: primaryType } : {}),
106
+ artistCredit: artistCreditString(normalizeArtistCredits(e['artist-credit'])),
107
+ ...(date ? { date } : {}),
108
+ ...(e.country ? { country: e.country } : {}),
109
+ };
110
+ }
111
+ export const searchEntitiesTool = tool('musicbrainz_search_entities', {
112
+ title: 'musicbrainz-mcp-server: search entities',
113
+ description: 'Full-text search across a MusicBrainz entity type (artist, release-group, release, recording, work, label) using a Lucene query string. Returns ranked matches with MBID, name/title, disambiguation, type, and a 0–100 relevance score (100 = exact). Starting point when resolving a name to an MBID — chain the returned MBID into the matching musicbrainz_get_* tool. Results are in MusicBrainz score-descending order. Supports field-scoped Lucene syntax (e.g. `artist:radiohead AND country:GB`).',
114
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
115
+ input: z.object({
116
+ entityType: z.enum(ENTITY_TYPES).describe('Which entity type to search.'),
117
+ query: z
118
+ .string()
119
+ .min(1)
120
+ .describe('Lucene query string. Plain text matches names/titles; field scoping (e.g. `artist:`, `country:`, `tag:`) is supported.'),
121
+ limit: z
122
+ .number()
123
+ .int()
124
+ .min(1)
125
+ .max(100)
126
+ .default(25)
127
+ .describe('Maximum results to return (1–100).'),
128
+ offset: z.number().int().min(0).default(0).describe('Result offset for pagination (0-based).'),
129
+ }),
130
+ output: z.object({
131
+ entityType: z.string().describe('The entity type that was searched.'),
132
+ results: z
133
+ .array(ResultSchema)
134
+ .describe('Ranked matches, in MusicBrainz score-descending order.'),
135
+ }),
136
+ enrichment: {
137
+ effectiveQuery: z.string().describe('The query string as sent to MusicBrainz.'),
138
+ totalCount: z.number().describe('Total matches upstream before the limit/offset window.'),
139
+ notice: z
140
+ .string()
141
+ .optional()
142
+ .describe('Guidance when zero results matched — how to broaden or correct the query.'),
143
+ },
144
+ async handler(input, ctx) {
145
+ ctx.log.info('musicbrainz_search_entities', {
146
+ entityType: input.entityType,
147
+ query: input.query,
148
+ });
149
+ const service = getMusicBrainzService();
150
+ const envelope = await service.search(input.entityType, input.query, { limit: input.limit, offset: input.offset }, ctx, { signal: ctx.signal });
151
+ const key = MusicBrainzService.pluralKey(input.entityType);
152
+ const rawHits = (envelope[key] ?? []);
153
+ const results = rawHits.map((h) => mapHit(input.entityType, h));
154
+ ctx.enrich.echo(input.query);
155
+ ctx.enrich.total(typeof envelope.count === 'number' ? envelope.count : results.length);
156
+ if (results.length === 0) {
157
+ ctx.enrich.notice(`No ${input.entityType} matched "${input.query}". Broaden the query, check spelling, or try a different entityType.`);
158
+ }
159
+ return { entityType: input.entityType, results };
160
+ },
161
+ format: (result) => {
162
+ const lines = [
163
+ `## MusicBrainz ${result.entityType} search`,
164
+ `**Matches:** ${result.results.length}`,
165
+ ];
166
+ for (const r of result.results) {
167
+ lines.push(`\n### ${safeText(r.name)}${r.disambiguation ? ` (${safeText(r.disambiguation)})` : ''}`);
168
+ lines.push(`**MBID:** ${r.mbid} | **Score:** ${r.score}`);
169
+ if (r.type)
170
+ lines.push(`**Type:** ${safeText(r.type)}`);
171
+ if (r.artistCredit)
172
+ lines.push(`**Artist:** ${safeText(r.artistCredit)}`);
173
+ if (r.date)
174
+ lines.push(`**Date:** ${r.date}`);
175
+ if (r.country)
176
+ lines.push(`**Country:** ${r.country}`);
177
+ if (r.length)
178
+ lines.push(`**Length:** ${r.length}`);
179
+ if (r.isrcs?.length)
180
+ lines.push(`**ISRCs:** ${r.isrcs.join(', ')}`);
181
+ if (r.iswcs?.length)
182
+ lines.push(`**ISWCs:** ${r.iswcs.join(', ')}`);
183
+ }
184
+ return [{ type: 'text', text: lines.join('\n') }];
185
+ },
186
+ });
187
+ //# sourceMappingURL=search-entities.tool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"search-entities.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-entities.tool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,40 @@
1
+ /**
2
+ * @fileoverview Service for the Cover Art Archive (coverartarchive.org) — a host
3
+ * distinct from MusicBrainz WS/2 with its own response shape and failure mode.
4
+ * A release legitimately having no art returns HTTP 404 (with an HTML body), so
5
+ * this service maps 404 to a clean empty image set rather than an error. Art is
6
+ * served at the release level; a release-group MBID returns HTTP 307 redirecting
7
+ * to the representative release's `index.json` — native `fetch` follows the
8
+ * redirect automatically and the response shape is identical afterward.
9
+ * @module services/cover-art/cover-art-service
10
+ */
11
+ import type { Context } from '@cyanheads/mcp-ts-core';
12
+ import type { CallOptions, RawCoverArtResponse } from '../../services/musicbrainz/types.js';
13
+ /** Entity types the Cover Art Archive serves images for. */
14
+ export type CoverArtEntityType = 'release' | 'release-group';
15
+ /**
16
+ * Wraps the Cover Art Archive image-metadata endpoints. Shares nothing with the
17
+ * MusicBrainz limiter — CAA is a different host (backed by archive.org) without
18
+ * the ~1 req/sec MusicBrainz constraint.
19
+ */
20
+ export declare class CoverArtService {
21
+ private readonly baseUrl;
22
+ private readonly timeoutMs;
23
+ private readonly maxRetries;
24
+ private readonly cacheTtlSeconds;
25
+ constructor(baseUrl: string, timeoutMs: number, maxRetries: number, cacheTtlSeconds: number);
26
+ /**
27
+ * Fetch image metadata for a release or release-group MBID. Returns an empty
28
+ * `{ images: [] }` when the entity has no art (CAA 404) — the absence of art
29
+ * is information, not a failure. A malformed/zero MBID still surfaces as the
30
+ * upstream 400 (`InvalidParams`); transient 5xx is retried.
31
+ */
32
+ getImages(entityType: CoverArtEntityType, mbid: string, ctx: Context, options?: CallOptions): Promise<RawCoverArtResponse>;
33
+ }
34
+ /** Initialize the Cover Art service. Call from `setup()` in createApp. */
35
+ export declare function initCoverArtService(): void;
36
+ /** Get the initialized Cover Art service. Throws if not initialized. */
37
+ export declare function getCoverArtService(): CoverArtService;
38
+ /** Reset the service singleton — test-only seam. */
39
+ export declare function resetCoverArtService(): void;
40
+ //# sourceMappingURL=cover-art-service.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cover-art-service.d.ts","sourceRoot":"","sources":["../../../src/services/cover-art/cover-art-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAUtD,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAExF,4DAA4D;AAC5D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,eAAe,CAAC;AAE7D;;;;GAIG;AACH,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe;gBAHf,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM;IAG1C;;;;;OAKG;IACG,SAAS,CACb,UAAU,EAAE,kBAAkB,EAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,mBAAmB,CAAC;CA8DhC;AAMD,0EAA0E;AAC1E,wBAAgB,mBAAmB,IAAI,IAAI,CAe1C;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD;AAED,oDAAoD;AACpD,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}