@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.
- package/AGENTS.md +466 -0
- package/CLAUDE.md +466 -0
- package/Dockerfile +121 -0
- package/LICENSE +201 -0
- package/README.md +329 -0
- package/changelog/0.1.x/0.1.0.md +27 -0
- package/changelog/template.md +127 -0
- package/dist/config/server-config.d.ts +24 -0
- package/dist/config/server-config.d.ts.map +1 -0
- package/dist/config/server-config.js +90 -0
- package/dist/config/server-config.js.map +1 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +27 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-server/resources/definitions/entity.resource.d.ts +33 -0
- package/dist/mcp-server/resources/definitions/entity.resource.d.ts.map +1 -0
- package/dist/mcp-server/resources/definitions/entity.resource.js +72 -0
- package/dist/mcp-server/resources/definitions/entity.resource.js.map +1 -0
- package/dist/mcp-server/resources/definitions/index.d.ts +27 -0
- package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -0
- package/dist/mcp-server/resources/definitions/index.js +8 -0
- package/dist/mcp-server/resources/definitions/index.js.map +1 -0
- package/dist/mcp-server/tools/definitions/_shared.d.ts +105 -0
- package/dist/mcp-server/tools/definitions/_shared.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/_shared.js +382 -0
- package/dist/mcp-server/tools/definitions/_shared.js.map +1 -0
- package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts +62 -0
- package/dist/mcp-server/tools/definitions/browse-entities.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/browse-entities.tool.js +236 -0
- package/dist/mcp-server/tools/definitions/browse-entities.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts +78 -0
- package/dist/mcp-server/tools/definitions/get-artist.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-artist.tool.js +200 -0
- package/dist/mcp-server/tools/definitions/get-artist.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts +42 -0
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.js +149 -0
- package/dist/mcp-server/tools/definitions/get-cover-art.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-label.tool.d.ts +52 -0
- package/dist/mcp-server/tools/definitions/get-label.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-label.tool.js +110 -0
- package/dist/mcp-server/tools/definitions/get-label.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts +58 -0
- package/dist/mcp-server/tools/definitions/get-recording.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-recording.tool.js +135 -0
- package/dist/mcp-server/tools/definitions/get-recording.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts +55 -0
- package/dist/mcp-server/tools/definitions/get-release-group.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-release-group.tool.js +140 -0
- package/dist/mcp-server/tools/definitions/get-release-group.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-release.tool.d.ts +66 -0
- package/dist/mcp-server/tools/definitions/get-release.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-release.tool.js +213 -0
- package/dist/mcp-server/tools/definitions/get-release.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/get-work.tool.d.ts +62 -0
- package/dist/mcp-server/tools/definitions/get-work.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/get-work.tool.js +132 -0
- package/dist/mcp-server/tools/definitions/get-work.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/index.d.ts +468 -0
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/index.js +28 -0
- package/dist/mcp-server/tools/definitions/index.js.map +1 -0
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts +59 -0
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js +214 -0
- package/dist/mcp-server/tools/definitions/lookup-identifier.tool.js.map +1 -0
- package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts +42 -0
- package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/search-entities.tool.js +187 -0
- package/dist/mcp-server/tools/definitions/search-entities.tool.js.map +1 -0
- package/dist/services/cover-art/cover-art-service.d.ts +40 -0
- package/dist/services/cover-art/cover-art-service.d.ts.map +1 -0
- package/dist/services/cover-art/cover-art-service.js +118 -0
- package/dist/services/cover-art/cover-art-service.js.map +1 -0
- package/dist/services/musicbrainz/musicbrainz-service.d.ts +81 -0
- package/dist/services/musicbrainz/musicbrainz-service.d.ts.map +1 -0
- package/dist/services/musicbrainz/musicbrainz-service.js +188 -0
- package/dist/services/musicbrainz/musicbrainz-service.js.map +1 -0
- package/dist/services/musicbrainz/rate-limiter.d.ts +32 -0
- package/dist/services/musicbrainz/rate-limiter.d.ts.map +1 -0
- package/dist/services/musicbrainz/rate-limiter.js +54 -0
- package/dist/services/musicbrainz/rate-limiter.js.map +1 -0
- package/dist/services/musicbrainz/types.d.ts +301 -0
- package/dist/services/musicbrainz/types.d.ts.map +1 -0
- package/dist/services/musicbrainz/types.js +11 -0
- package/dist/services/musicbrainz/types.js.map +1 -0
- package/package.json +103 -0
- package/server.json +111 -0
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
---
|
|
2
|
+
# FORMAT REFERENCE — do not edit. Copy this file to
|
|
3
|
+
# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
|
|
4
|
+
# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
|
|
5
|
+
# with a concrete date.
|
|
6
|
+
|
|
7
|
+
# Required. One-line GitHub Release-style headline. 350 character cap.
|
|
8
|
+
# Default short and scannable. Don't pad, don't stitch unrelated changes with
|
|
9
|
+
# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
|
|
10
|
+
# inside the value as a key separator and fails GitHub's strict parser.
|
|
11
|
+
summary: ""
|
|
12
|
+
|
|
13
|
+
# Set `true` when consumers must change code to upgrade: API removals,
|
|
14
|
+
# signature changes, config renames, behavior changes that break existing
|
|
15
|
+
# usage. Flagged as `Breaking` in the rollup.
|
|
16
|
+
breaking: false
|
|
17
|
+
|
|
18
|
+
# Set `true` if this release contains any security fix. Pairs with the
|
|
19
|
+
# `## Security` section below. Flagged as `Security` in the rollup so
|
|
20
|
+
# users can triage upgrade urgency at a glance.
|
|
21
|
+
security: false
|
|
22
|
+
|
|
23
|
+
# Optional free-form notes for maintenance agents processing this release.
|
|
24
|
+
# Not rendered in CHANGELOG — consumed by agents running `maintenance` on
|
|
25
|
+
# downstream servers. Use for adoption instructions that don't fit the
|
|
26
|
+
# human-facing sections: new files to create, fields to populate, one-time
|
|
27
|
+
# migration steps. Omit the field entirely when there's nothing to say.
|
|
28
|
+
# agent-notes: |
|
|
29
|
+
# <instructions for downstream maintenance agents>
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
# <version> — YYYY-MM-DD
|
|
33
|
+
|
|
34
|
+
<!--
|
|
35
|
+
AUTHORING GUIDE — applies to the new per-version file you create from this
|
|
36
|
+
template.
|
|
37
|
+
|
|
38
|
+
Audience: someone scanning release notes to decide what affects them. Lead
|
|
39
|
+
each bullet with the symbol or concept name in **bold** so they can skip
|
|
40
|
+
what's irrelevant and zoom in on what's not.
|
|
41
|
+
|
|
42
|
+
Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
|
|
43
|
+
name the symbol, state what changed, stop. Use a second sentence only when
|
|
44
|
+
it carries weight. If a bullet feels long, it is.
|
|
45
|
+
|
|
46
|
+
Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
|
|
47
|
+
relevant skill), ceremonial framings ("This release introduces…",
|
|
48
|
+
backwards-compat paragraphs), file-by-file test enumerations, internal
|
|
49
|
+
implementation notes. Prefer code/symbol names over English re-explanations.
|
|
50
|
+
|
|
51
|
+
Narrative intro: skip by default. Add one short sentence only when the
|
|
52
|
+
release theme genuinely needs framing the bullets can't carry.
|
|
53
|
+
|
|
54
|
+
Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
|
|
55
|
+
Fixed, Security. Include only sections with entries; delete the rest
|
|
56
|
+
(including the commented-out scaffolding below). Don't ship empty headers.
|
|
57
|
+
|
|
58
|
+
Include: every distinct fact a reader needs to adopt or audit the release —
|
|
59
|
+
new exports, signatures, lint rule IDs, env vars, breaking changes, version
|
|
60
|
+
bumps on shipped skills. Nothing more.
|
|
61
|
+
|
|
62
|
+
Links: link issues, PRs, docs, or skills where they help a reader jump to
|
|
63
|
+
context. Once per item per entry — don't re-link the same issue in summary,
|
|
64
|
+
narrative, and bullet. Skip links for inline symbol names; code spans speak
|
|
65
|
+
for themselves.
|
|
66
|
+
|
|
67
|
+
Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
|
|
68
|
+
inside its own UI, not in npm reads or local editors.
|
|
69
|
+
|
|
70
|
+
[#38](https://github.com/cyanheads/mcp-ts-core/issues/38) ← issue
|
|
71
|
+
[#42](https://github.com/cyanheads/mcp-ts-core/pull/42) ← PR
|
|
72
|
+
|
|
73
|
+
Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
|
|
74
|
+
Never speculate on a future number — `#42` for an upcoming PR silently
|
|
75
|
+
resolves to whatever real item already owns 42, and timeline previews pull
|
|
76
|
+
in that unrelated item's metadata.
|
|
77
|
+
|
|
78
|
+
TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
|
|
79
|
+
via `gh release create --notes-from-tag`. The tag is a derivative of this
|
|
80
|
+
changelog entry — a condensed, scannable version, not a copy. Format:
|
|
81
|
+
|
|
82
|
+
<theme — omit version number, GitHub prepends it>
|
|
83
|
+
← blank line
|
|
84
|
+
<1-2 sentence context: what this release does>
|
|
85
|
+
← blank line
|
|
86
|
+
Dependency bumps: ← section header
|
|
87
|
+
← blank line
|
|
88
|
+
- `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6 ← bullet
|
|
89
|
+
← blank line
|
|
90
|
+
Changed: ← only sections with entries
|
|
91
|
+
← blank line
|
|
92
|
+
- `format()` output includes `query` in text mode
|
|
93
|
+
← blank line
|
|
94
|
+
Added:
|
|
95
|
+
← blank line
|
|
96
|
+
- `manifest.json` scaffolded for MCPB bundle support
|
|
97
|
+
- Install badges (Claude Desktop, Cursor, VS Code)
|
|
98
|
+
← blank line
|
|
99
|
+
<N> tests pass; `bun run devcheck` clean. ← footer
|
|
100
|
+
|
|
101
|
+
Never a flat comma-separated string. Always structured markdown with
|
|
102
|
+
sections. The tag must scan well as a rendered GitHub Release page.
|
|
103
|
+
-->
|
|
104
|
+
|
|
105
|
+
## Added
|
|
106
|
+
|
|
107
|
+
-
|
|
108
|
+
|
|
109
|
+
## Changed
|
|
110
|
+
|
|
111
|
+
-
|
|
112
|
+
|
|
113
|
+
<!-- ## Deprecated
|
|
114
|
+
|
|
115
|
+
- -->
|
|
116
|
+
|
|
117
|
+
<!-- ## Removed
|
|
118
|
+
|
|
119
|
+
- -->
|
|
120
|
+
|
|
121
|
+
## Fixed
|
|
122
|
+
|
|
123
|
+
-
|
|
124
|
+
|
|
125
|
+
<!-- ## Security
|
|
126
|
+
|
|
127
|
+
- -->
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Server-specific configuration for the MusicBrainz Web Service v2
|
|
3
|
+
* and the Cover Art Archive. Lazy-parsed from environment variables; framework
|
|
4
|
+
* config (transport, logging, auth) is owned by @cyanheads/mcp-ts-core and never
|
|
5
|
+
* merged here.
|
|
6
|
+
* @module config/server-config
|
|
7
|
+
*/
|
|
8
|
+
import { z } from '@cyanheads/mcp-ts-core';
|
|
9
|
+
declare const ServerConfigSchema: z.ZodObject<{
|
|
10
|
+
contact: z.ZodDefault<z.ZodPreprocess<z.ZodString>>;
|
|
11
|
+
baseUrl: z.ZodDefault<z.ZodString>;
|
|
12
|
+
coverArtBaseUrl: z.ZodDefault<z.ZodString>;
|
|
13
|
+
rateLimitRps: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
14
|
+
cacheTtlSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
15
|
+
timeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
16
|
+
maxRetries: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
|
|
17
|
+
}, z.core.$strip>;
|
|
18
|
+
export type ServerConfig = z.infer<typeof ServerConfigSchema>;
|
|
19
|
+
/** Parse and cache server config from the environment. Lazy — never reads `process.env` at import time. */
|
|
20
|
+
export declare function getServerConfig(): ServerConfig;
|
|
21
|
+
/** Reset cached config — test-only seam. */
|
|
22
|
+
export declare function resetServerConfig(): void;
|
|
23
|
+
export {};
|
|
24
|
+
//# sourceMappingURL=server-config.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAkB3C,QAAA,MAAM,kBAAkB;;;;;;;;iBA+CtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,2GAA2G;AAC3G,wBAAgB,eAAe,IAAI,YAAY,CAW9C;AAED,4CAA4C;AAC5C,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Server-specific configuration for the MusicBrainz Web Service v2
|
|
3
|
+
* and the Cover Art Archive. Lazy-parsed from environment variables; framework
|
|
4
|
+
* config (transport, logging, auth) is owned by @cyanheads/mcp-ts-core and never
|
|
5
|
+
* merged here.
|
|
6
|
+
* @module config/server-config
|
|
7
|
+
*/
|
|
8
|
+
import { z } from '@cyanheads/mcp-ts-core';
|
|
9
|
+
import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
|
|
10
|
+
/**
|
|
11
|
+
* Treats an unset env var (`undefined`), a set-but-empty env var (`""`), and an
|
|
12
|
+
* unsubstituted MCPB placeholder (`${user_config.X}`) identically as "not set".
|
|
13
|
+
* Without this, `MUSICBRAINZ_CONTACT=` would surface as a present-but-empty
|
|
14
|
+
* contact instead of falling through to the schema default; the placeholder case
|
|
15
|
+
* occurs when a Claude Desktop / MCPB host leaves an optional `user_config` field
|
|
16
|
+
* blank and passes the literal `${user_config.X}` string through to the process.
|
|
17
|
+
*/
|
|
18
|
+
const PLACEHOLDER_PATTERN = /^\$\{[^}]+\}$/;
|
|
19
|
+
const emptyAsUndefined = (v) => {
|
|
20
|
+
if (v === '')
|
|
21
|
+
return;
|
|
22
|
+
if (typeof v === 'string' && PLACEHOLDER_PATTERN.test(v))
|
|
23
|
+
return;
|
|
24
|
+
return v;
|
|
25
|
+
};
|
|
26
|
+
const ServerConfigSchema = z.object({
|
|
27
|
+
/**
|
|
28
|
+
* Contact string (email or URL) embedded in the mandatory descriptive
|
|
29
|
+
* User-Agent. MusicBrainz blocks requests without an application + contact
|
|
30
|
+
* User-Agent, so a default is provided to keep the server functional out of
|
|
31
|
+
* the box; operators running a hosted instance should set their own.
|
|
32
|
+
*/
|
|
33
|
+
contact: z
|
|
34
|
+
.preprocess(emptyAsUndefined, z.string())
|
|
35
|
+
.default('https://github.com/cyanheads/musicbrainz-mcp-server')
|
|
36
|
+
.describe('Contact (email or URL) embedded in the mandatory MusicBrainz User-Agent'),
|
|
37
|
+
baseUrl: z
|
|
38
|
+
.string()
|
|
39
|
+
.url()
|
|
40
|
+
.default('https://musicbrainz.org/ws/2')
|
|
41
|
+
.describe('MusicBrainz Web Service v2 base URL (override for a private mirror or beta)'),
|
|
42
|
+
coverArtBaseUrl: z
|
|
43
|
+
.string()
|
|
44
|
+
.url()
|
|
45
|
+
.default('https://coverartarchive.org')
|
|
46
|
+
.describe('Cover Art Archive base URL'),
|
|
47
|
+
rateLimitRps: z.coerce
|
|
48
|
+
.number()
|
|
49
|
+
.min(0.1)
|
|
50
|
+
.max(50)
|
|
51
|
+
.default(1)
|
|
52
|
+
.describe('Client-side MusicBrainz request-per-second ceiling (~1 is the documented limit)'),
|
|
53
|
+
cacheTtlSeconds: z.coerce
|
|
54
|
+
.number()
|
|
55
|
+
.min(0)
|
|
56
|
+
.max(2_592_000)
|
|
57
|
+
.default(86_400)
|
|
58
|
+
.describe('Response cache TTL in seconds; MBIDs are stable so data changes slowly. 0 disables caching'),
|
|
59
|
+
timeoutMs: z.coerce
|
|
60
|
+
.number()
|
|
61
|
+
.min(1_000)
|
|
62
|
+
.max(120_000)
|
|
63
|
+
.default(30_000)
|
|
64
|
+
.describe('Per-request HTTP timeout in milliseconds'),
|
|
65
|
+
maxRetries: z.coerce
|
|
66
|
+
.number()
|
|
67
|
+
.min(0)
|
|
68
|
+
.max(10)
|
|
69
|
+
.default(3)
|
|
70
|
+
.describe('Max retry attempts for transient upstream failures (503 / 5xx / HTML error page)'),
|
|
71
|
+
});
|
|
72
|
+
let _config;
|
|
73
|
+
/** Parse and cache server config from the environment. Lazy — never reads `process.env` at import time. */
|
|
74
|
+
export function getServerConfig() {
|
|
75
|
+
_config ??= parseEnvConfig(ServerConfigSchema, {
|
|
76
|
+
contact: 'MUSICBRAINZ_CONTACT',
|
|
77
|
+
baseUrl: 'MUSICBRAINZ_BASE_URL',
|
|
78
|
+
coverArtBaseUrl: 'COVER_ART_BASE_URL',
|
|
79
|
+
rateLimitRps: 'MUSICBRAINZ_RATE_LIMIT_RPS',
|
|
80
|
+
cacheTtlSeconds: 'MUSICBRAINZ_CACHE_TTL',
|
|
81
|
+
timeoutMs: 'MUSICBRAINZ_TIMEOUT_MS',
|
|
82
|
+
maxRetries: 'MUSICBRAINZ_MAX_RETRIES',
|
|
83
|
+
});
|
|
84
|
+
return _config;
|
|
85
|
+
}
|
|
86
|
+
/** Reset cached config — test-only seam. */
|
|
87
|
+
export function resetServerConfig() {
|
|
88
|
+
_config = undefined;
|
|
89
|
+
}
|
|
90
|
+
//# sourceMappingURL=server-config.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,mBAAmB,GAAG,eAAe,CAAC;AAC5C,MAAM,gBAAgB,GAAG,CAAC,CAAU,EAAE,EAAE;IACtC,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO;IACrB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO;IACjE,OAAO,CAAC,CAAC;AACX,CAAC,CAAC;AAEF,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC;;;;;OAKG;IACH,OAAO,EAAE,CAAC;SACP,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;SACxC,OAAO,CAAC,qDAAqD,CAAC;SAC9D,QAAQ,CAAC,yEAAyE,CAAC;IACtF,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,8BAA8B,CAAC;SACvC,QAAQ,CAAC,6EAA6E,CAAC;IAC1F,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,6BAA6B,CAAC;SACtC,QAAQ,CAAC,4BAA4B,CAAC;IACzC,YAAY,EAAE,CAAC,CAAC,MAAM;SACnB,MAAM,EAAE;SACR,GAAG,CAAC,GAAG,CAAC;SACR,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,CAAC,CAAC;SACV,QAAQ,CAAC,iFAAiF,CAAC;IAC9F,eAAe,EAAE,CAAC,CAAC,MAAM;SACtB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,SAAS,CAAC;SACd,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CACP,4FAA4F,CAC7F;IACH,SAAS,EAAE,CAAC,CAAC,MAAM;SAChB,MAAM,EAAE;SACR,GAAG,CAAC,KAAK,CAAC;SACV,GAAG,CAAC,OAAO,CAAC;SACZ,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CAAC,0CAA0C,CAAC;IACvD,UAAU,EAAE,CAAC,CAAC,MAAM;SACjB,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,CAAC,CAAC;SACV,QAAQ,CAAC,kFAAkF,CAAC;CAChG,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,2GAA2G;AAC3G,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,qBAAqB;QAC9B,OAAO,EAAE,sBAAsB;QAC/B,eAAe,EAAE,oBAAoB;QACrC,YAAY,EAAE,4BAA4B;QAC1C,eAAe,EAAE,uBAAuB;QACxC,SAAS,EAAE,wBAAwB;QACnC,UAAU,EAAE,yBAAyB;KACtC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,iBAAiB;IAC/B,OAAO,GAAG,SAAS,CAAC;AACtB,CAAC"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* @fileoverview musicbrainz-mcp-server entry point. Wraps the live MusicBrainz
|
|
4
|
+
* Web Service v2 and the Cover Art Archive: search / lookup / browse music
|
|
5
|
+
* metadata, traverse relationships, resolve standard identifiers, and fetch
|
|
6
|
+
* cover art. Keyless, read-only, CC0 core data.
|
|
7
|
+
* @module index
|
|
8
|
+
*/
|
|
9
|
+
export {};
|
|
10
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* @fileoverview musicbrainz-mcp-server entry point. Wraps the live MusicBrainz
|
|
4
|
+
* Web Service v2 and the Cover Art Archive: search / lookup / browse music
|
|
5
|
+
* metadata, traverse relationships, resolve standard identifiers, and fetch
|
|
6
|
+
* cover art. Keyless, read-only, CC0 core data.
|
|
7
|
+
* @module index
|
|
8
|
+
*/
|
|
9
|
+
import { createApp } from '@cyanheads/mcp-ts-core';
|
|
10
|
+
import { allResourceDefinitions } from './mcp-server/resources/definitions/index.js';
|
|
11
|
+
import { allToolDefinitions } from './mcp-server/tools/definitions/index.js';
|
|
12
|
+
import { initCoverArtService } from './services/cover-art/cover-art-service.js';
|
|
13
|
+
import { initMusicBrainzService } from './services/musicbrainz/musicbrainz-service.js';
|
|
14
|
+
await createApp({
|
|
15
|
+
name: 'musicbrainz-mcp-server',
|
|
16
|
+
title: 'musicbrainz-mcp-server',
|
|
17
|
+
websiteUrl: 'https://github.com/cyanheads/musicbrainz-mcp-server',
|
|
18
|
+
tools: allToolDefinitions,
|
|
19
|
+
resources: allResourceDefinitions,
|
|
20
|
+
prompts: [],
|
|
21
|
+
instructions: "Open music metadata over the live MusicBrainz Web Service v2 and the Cover Art Archive. Entities are addressed by MBID (a UUID); starting from a name, call musicbrainz_search_entities first and chain the MBID into the matching musicbrainz_get_* tool. The get_* tools embed at most one page (25) of any linked list (a discography, a label's releases, a work's recordings) — use musicbrainz_browse_entities for the complete set. musicbrainz_lookup_identifier resolves an ISRC/ISWC/barcode without a name search. The server is rate-limited to ~1 request/second against MusicBrainz, so batch enumeration via browse paces accordingly. External IDs (Wikidata QID, Discogs) arrive as url-rels chainable to those servers.",
|
|
22
|
+
setup(core) {
|
|
23
|
+
initMusicBrainzService(core.config.mcpServerVersion);
|
|
24
|
+
initCoverArtService();
|
|
25
|
+
},
|
|
26
|
+
});
|
|
27
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAEvF,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,wBAAwB;IAC9B,KAAK,EAAE,wBAAwB;IAC/B,UAAU,EAAE,qDAAqD;IACjE,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,EAAE;IACX,YAAY,EACV,2sBAA2sB;IAC7sB,KAAK,CAAC,IAAI;QACR,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACrD,mBAAmB,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview musicbrainz://{entity_type}/{mbid} — a single MusicBrainz entity
|
|
3
|
+
* by type and MBID, returned as a stable injectable-context resource. Mirrors the
|
|
4
|
+
* corresponding get_* tool with default `inc` sets. A convenience mirror for
|
|
5
|
+
* clients that support resources; every entity is fully reachable through the
|
|
6
|
+
* get_* tools, so tool-only clients lose nothing. No list() — the corpus is
|
|
7
|
+
* millions of entities; discovery is via musicbrainz_search_entities.
|
|
8
|
+
* @module mcp-server/resources/definitions/entity.resource
|
|
9
|
+
*/
|
|
10
|
+
import { z } from '@cyanheads/mcp-ts-core';
|
|
11
|
+
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
12
|
+
export declare const entityResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
|
|
13
|
+
entity_type: z.ZodEnum<{
|
|
14
|
+
artist: "artist";
|
|
15
|
+
"release-group": "release-group";
|
|
16
|
+
release: "release";
|
|
17
|
+
recording: "recording";
|
|
18
|
+
work: "work";
|
|
19
|
+
label: "label";
|
|
20
|
+
}>;
|
|
21
|
+
mbid: z.ZodString;
|
|
22
|
+
}, z.core.$strip>, undefined, readonly [{
|
|
23
|
+
readonly reason: "invalid_mbid";
|
|
24
|
+
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
25
|
+
readonly when: "The MBID is malformed / all-zeros, or entity_type is not one of the six valid types.";
|
|
26
|
+
readonly recovery: "Use a 36-character UUID MBID and a valid entity_type (artist, release-group, release, recording, work, label).";
|
|
27
|
+
}, {
|
|
28
|
+
readonly reason: "entity_not_found";
|
|
29
|
+
readonly code: JsonRpcErrorCode.NotFound;
|
|
30
|
+
readonly when: "The MBID is well-formed but no entity of that type exists with it.";
|
|
31
|
+
readonly recovery: "Verify the MBID, or find it by name with the musicbrainz_search_entities tool.";
|
|
32
|
+
}]>;
|
|
33
|
+
//# sourceMappingURL=entity.resource.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"entity.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity.resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAgB3E,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;GA8DzB,CAAC"}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview musicbrainz://{entity_type}/{mbid} — a single MusicBrainz entity
|
|
3
|
+
* by type and MBID, returned as a stable injectable-context resource. Mirrors the
|
|
4
|
+
* corresponding get_* tool with default `inc` sets. A convenience mirror for
|
|
5
|
+
* clients that support resources; every entity is fully reachable through the
|
|
6
|
+
* get_* tools, so tool-only clients lose nothing. No list() — the corpus is
|
|
7
|
+
* millions of entities; discovery is via musicbrainz_search_entities.
|
|
8
|
+
* @module mcp-server/resources/definitions/entity.resource
|
|
9
|
+
*/
|
|
10
|
+
import { resource, z } from '@cyanheads/mcp-ts-core';
|
|
11
|
+
import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
|
|
12
|
+
import { getMusicBrainzService } from '../../../services/musicbrainz/musicbrainz-service.js';
|
|
13
|
+
/** Default `inc` sets per entity type — the useful slice the get_* tools fetch. */
|
|
14
|
+
const DEFAULT_INC = {
|
|
15
|
+
artist: ['release-groups', 'artist-rels', 'url-rels', 'aliases', 'tags', 'genres'],
|
|
16
|
+
'release-group': ['releases', 'artist-credits', 'tags', 'genres'],
|
|
17
|
+
release: ['recordings', 'artist-credits', 'labels', 'release-groups'],
|
|
18
|
+
recording: ['artist-credits', 'releases', 'isrcs', 'artist-rels', 'work-rels', 'url-rels'],
|
|
19
|
+
work: ['artist-rels', 'recording-rels', 'aliases', 'tags', 'genres', 'url-rels'],
|
|
20
|
+
label: ['aliases', 'tags', 'genres', 'url-rels'],
|
|
21
|
+
};
|
|
22
|
+
const ENTITY_TYPES = ['artist', 'release-group', 'release', 'recording', 'work', 'label'];
|
|
23
|
+
export const entityResource = resource('musicbrainz://{entity_type}/{mbid}', {
|
|
24
|
+
name: 'musicbrainz-entity',
|
|
25
|
+
title: 'musicbrainz-mcp-server: entity',
|
|
26
|
+
description: "A single MusicBrainz entity by type and MBID, with default linked sub-resources folded in (mirrors the matching musicbrainz_get_* tool). entity_type ∈ artist, release-group, release, recording, work, label. Returns the raw MusicBrainz JSON record. For complete linked sets (a prolific artist's discography, a label's releases) use musicbrainz_browse_entities — embedded lists here are capped at one page.",
|
|
27
|
+
mimeType: 'application/json',
|
|
28
|
+
errors: [
|
|
29
|
+
{
|
|
30
|
+
reason: 'invalid_mbid',
|
|
31
|
+
code: JsonRpcErrorCode.InvalidParams,
|
|
32
|
+
when: 'The MBID is malformed / all-zeros, or entity_type is not one of the six valid types.',
|
|
33
|
+
recovery: 'Use a 36-character UUID MBID and a valid entity_type (artist, release-group, release, recording, work, label).',
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
reason: 'entity_not_found',
|
|
37
|
+
code: JsonRpcErrorCode.NotFound,
|
|
38
|
+
when: 'The MBID is well-formed but no entity of that type exists with it.',
|
|
39
|
+
recovery: 'Verify the MBID, or find it by name with the musicbrainz_search_entities tool.',
|
|
40
|
+
},
|
|
41
|
+
],
|
|
42
|
+
params: z.object({
|
|
43
|
+
entity_type: z
|
|
44
|
+
.enum(ENTITY_TYPES)
|
|
45
|
+
.describe('Entity type: artist, release-group, release, recording, work, or label.'),
|
|
46
|
+
mbid: z.string().describe('Entity MBID (36-character UUID).'),
|
|
47
|
+
}),
|
|
48
|
+
async handler(params, ctx) {
|
|
49
|
+
ctx.log.debug('musicbrainz entity resource', {
|
|
50
|
+
entityType: params.entity_type,
|
|
51
|
+
mbid: params.mbid,
|
|
52
|
+
});
|
|
53
|
+
const service = getMusicBrainzService();
|
|
54
|
+
try {
|
|
55
|
+
return await service.lookup(params.entity_type, params.mbid, { inc: DEFAULT_INC[params.entity_type] }, ctx, { signal: ctx.signal });
|
|
56
|
+
}
|
|
57
|
+
catch (error) {
|
|
58
|
+
if (error instanceof McpError && error.code === JsonRpcErrorCode.InvalidParams) {
|
|
59
|
+
throw ctx.fail('invalid_mbid', `Malformed MBID "${params.mbid}".`, {
|
|
60
|
+
...ctx.recoveryFor('invalid_mbid'),
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
if (error instanceof McpError && error.code === JsonRpcErrorCode.NotFound) {
|
|
64
|
+
throw ctx.fail('entity_not_found', `No ${params.entity_type} exists with MBID ${params.mbid}.`, {
|
|
65
|
+
...ctx.recoveryFor('entity_not_found'),
|
|
66
|
+
});
|
|
67
|
+
}
|
|
68
|
+
throw error;
|
|
69
|
+
}
|
|
70
|
+
},
|
|
71
|
+
});
|
|
72
|
+
//# sourceMappingURL=entity.resource.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"entity.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/entity.resource.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Barrel collecting all MusicBrainz resource definitions into the
|
|
3
|
+
* `allResourceDefinitions` array consumed by createApp().
|
|
4
|
+
* @module mcp-server/resources/definitions/index
|
|
5
|
+
*/
|
|
6
|
+
export declare const allResourceDefinitions: import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
|
|
7
|
+
entity_type: import("zod").ZodEnum<{
|
|
8
|
+
artist: "artist";
|
|
9
|
+
"release-group": "release-group";
|
|
10
|
+
release: "release";
|
|
11
|
+
recording: "recording";
|
|
12
|
+
work: "work";
|
|
13
|
+
label: "label";
|
|
14
|
+
}>;
|
|
15
|
+
mbid: import("zod").ZodString;
|
|
16
|
+
}, import("zod/v4/core").$strip>, undefined, readonly [{
|
|
17
|
+
readonly reason: "invalid_mbid";
|
|
18
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
|
|
19
|
+
readonly when: "The MBID is malformed / all-zeros, or entity_type is not one of the six valid types.";
|
|
20
|
+
readonly recovery: "Use a 36-character UUID MBID and a valid entity_type (artist, release-group, release, recording, work, label).";
|
|
21
|
+
}, {
|
|
22
|
+
readonly reason: "entity_not_found";
|
|
23
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
|
|
24
|
+
readonly when: "The MBID is well-formed but no entity of that type exists with it.";
|
|
25
|
+
readonly recovery: "Verify the MBID, or find it by name with the musicbrainz_search_entities tool.";
|
|
26
|
+
}]>[];
|
|
27
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;KAAmB,CAAC"}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Barrel collecting all MusicBrainz resource definitions into the
|
|
3
|
+
* `allResourceDefinitions` array consumed by createApp().
|
|
4
|
+
* @module mcp-server/resources/definitions/index
|
|
5
|
+
*/
|
|
6
|
+
import { entityResource } from './entity.resource.js';
|
|
7
|
+
export const allResourceDefinitions = [entityResource];
|
|
8
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,cAAc,CAAC,CAAC"}
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Shared Zod sub-schemas and pure normalizers for MusicBrainz tool
|
|
3
|
+
* definitions. Relationships, artist-credits, life-spans, tags, aliases, and
|
|
4
|
+
* external-link (url-rels) extraction recur across the artist / recording / work /
|
|
5
|
+
* label / release tools, so the schemas and the raw→domain mappers live here once.
|
|
6
|
+
*
|
|
7
|
+
* Normalization preserves absence as "unknown": MusicBrainz omits fields entirely
|
|
8
|
+
* (and a field can present as `null` in one mode and `false` in another), so every
|
|
9
|
+
* mapper uses conditional spreads under `exactOptionalPropertyTypes` and never
|
|
10
|
+
* fabricates a concrete value from missing upstream data.
|
|
11
|
+
*
|
|
12
|
+
* NOTE: this file holds shared schemas/helpers, not a tool definition, so it omits
|
|
13
|
+
* the `.tool.ts` suffix to stay out of the definition glob.
|
|
14
|
+
* @module mcp-server/tools/definitions/_shared
|
|
15
|
+
*/
|
|
16
|
+
import { z } from '@cyanheads/mcp-ts-core';
|
|
17
|
+
import type { RawAlias, RawArtistCredit, RawCoverArtStub, RawLifeSpan, RawRelation, RawTag } from '../../../services/musicbrainz/types.js';
|
|
18
|
+
/**
|
|
19
|
+
* Classify an upstream error from an MBID lookup against the MusicBrainz 400-vs-404
|
|
20
|
+
* split: a malformed / all-zeros MBID returns HTTP 400 (`InvalidParams`); a
|
|
21
|
+
* well-formed MBID with no matching entity returns HTTP 404 (`NotFound`). Returns
|
|
22
|
+
* the contract reason for those two cases, or `null` for anything else (transient
|
|
23
|
+
* upstream failures bubble unchanged). Handlers call `ctx.fail(reason, …)` on a
|
|
24
|
+
* non-null result so `data.reason` is populated and typed against their contract.
|
|
25
|
+
*/
|
|
26
|
+
export declare function classifyMbidError(error: unknown): 'invalid_mbid' | 'entity_not_found' | null;
|
|
27
|
+
/** UUID shape MusicBrainz MBIDs follow — surfaced in recovery hints, not used to pre-validate. */
|
|
28
|
+
export declare const MBID_EXAMPLE = "a74b1b7f-71a5-4011-9441-d0b5e4122711";
|
|
29
|
+
export declare const MbidScore: z.ZodNumber;
|
|
30
|
+
export declare const ArtistCreditSchema: z.ZodObject<{
|
|
31
|
+
name: z.ZodString;
|
|
32
|
+
artistId: z.ZodString;
|
|
33
|
+
artistName: z.ZodString;
|
|
34
|
+
joinPhrase: z.ZodOptional<z.ZodString>;
|
|
35
|
+
}, z.core.$strip>;
|
|
36
|
+
export declare const LifeSpanSchema: z.ZodObject<{
|
|
37
|
+
begin: z.ZodOptional<z.ZodString>;
|
|
38
|
+
end: z.ZodOptional<z.ZodString>;
|
|
39
|
+
ended: z.ZodOptional<z.ZodBoolean>;
|
|
40
|
+
}, z.core.$strip>;
|
|
41
|
+
export declare const TagSchema: z.ZodObject<{
|
|
42
|
+
name: z.ZodString;
|
|
43
|
+
count: z.ZodNumber;
|
|
44
|
+
}, z.core.$strip>;
|
|
45
|
+
export declare const AliasSchema: z.ZodObject<{
|
|
46
|
+
name: z.ZodString;
|
|
47
|
+
sortName: z.ZodOptional<z.ZodString>;
|
|
48
|
+
type: z.ZodOptional<z.ZodString>;
|
|
49
|
+
locale: z.ZodOptional<z.ZodString>;
|
|
50
|
+
primary: z.ZodOptional<z.ZodBoolean>;
|
|
51
|
+
}, z.core.$strip>;
|
|
52
|
+
export declare const RelationSchema: z.ZodObject<{
|
|
53
|
+
type: z.ZodString;
|
|
54
|
+
direction: z.ZodOptional<z.ZodString>;
|
|
55
|
+
attributes: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
56
|
+
targetType: z.ZodString;
|
|
57
|
+
targetId: z.ZodOptional<z.ZodString>;
|
|
58
|
+
targetName: z.ZodOptional<z.ZodString>;
|
|
59
|
+
begin: z.ZodOptional<z.ZodString>;
|
|
60
|
+
end: z.ZodOptional<z.ZodString>;
|
|
61
|
+
}, z.core.$strip>;
|
|
62
|
+
export declare const ExternalLinkSchema: z.ZodObject<{
|
|
63
|
+
type: z.ZodString;
|
|
64
|
+
resource: z.ZodString;
|
|
65
|
+
}, z.core.$strip>;
|
|
66
|
+
export declare const CoverArtStubSchema: z.ZodObject<{
|
|
67
|
+
exists: z.ZodBoolean;
|
|
68
|
+
count: z.ZodOptional<z.ZodNumber>;
|
|
69
|
+
front: z.ZodOptional<z.ZodBoolean>;
|
|
70
|
+
back: z.ZodOptional<z.ZodBoolean>;
|
|
71
|
+
}, z.core.$strip>;
|
|
72
|
+
export declare function normalizeArtistCredits(credits: RawArtistCredit[] | undefined): z.infer<typeof ArtistCreditSchema>[];
|
|
73
|
+
/** Render an artist-credit array to its display string, stitching join phrases. */
|
|
74
|
+
export declare function artistCreditString(credits: z.infer<typeof ArtistCreditSchema>[]): string;
|
|
75
|
+
/**
|
|
76
|
+
* Render the artist-credit array as a detail block surfacing every sub-field
|
|
77
|
+
* (credited name, canonical name, MBID, join phrase) — used by tools that expose
|
|
78
|
+
* `artistCredit` as a full array in output, so format() stays parity-complete.
|
|
79
|
+
*/
|
|
80
|
+
export declare function renderArtistCredits(credits: z.infer<typeof ArtistCreditSchema>[]): string[];
|
|
81
|
+
export declare function normalizeLifeSpan(span: RawLifeSpan | null | undefined): z.infer<typeof LifeSpanSchema> | undefined;
|
|
82
|
+
export declare function normalizeTags(tags: RawTag[] | undefined): z.infer<typeof TagSchema>[];
|
|
83
|
+
export declare function normalizeAliases(aliases: RawAlias[] | undefined): z.infer<typeof AliasSchema>[];
|
|
84
|
+
/**
|
|
85
|
+
* Split a raw `relations[]` array into the non-URL relationships (band
|
|
86
|
+
* membership, performers, writers, etc.) and the external links (url-rels).
|
|
87
|
+
* URL relations are where cross-service IDs (Wikidata, Discogs) live, so they
|
|
88
|
+
* get their own typed view.
|
|
89
|
+
*/
|
|
90
|
+
export declare function normalizeRelations(relations: RawRelation[] | undefined): {
|
|
91
|
+
relationships: z.infer<typeof RelationSchema>[];
|
|
92
|
+
externalLinks: z.infer<typeof ExternalLinkSchema>[];
|
|
93
|
+
};
|
|
94
|
+
export declare function normalizeCoverArtStub(stub: RawCoverArtStub | undefined): z.infer<typeof CoverArtStubSchema>;
|
|
95
|
+
/** Format milliseconds as `m:ss` (track lengths are in ms upstream). */
|
|
96
|
+
export declare function formatDuration(ms: number | null | undefined): string | undefined;
|
|
97
|
+
export declare function safeText(value: string): string;
|
|
98
|
+
export declare function renderRelationships(rels: z.infer<typeof RelationSchema>[]): string[];
|
|
99
|
+
export declare function renderExternalLinks(links: z.infer<typeof ExternalLinkSchema>[]): string[];
|
|
100
|
+
export declare function renderTags(tags: z.infer<typeof TagSchema>[]): string | undefined;
|
|
101
|
+
export declare function renderAliases(aliases: z.infer<typeof AliasSchema>[]): string | undefined;
|
|
102
|
+
export declare function renderLifeSpan(span: z.infer<typeof LifeSpanSchema> | undefined): string | undefined;
|
|
103
|
+
/** Render the cover-art availability stub completely (exists/count/front/back). */
|
|
104
|
+
export declare function renderCoverArtStub(stub: z.infer<typeof CoverArtStubSchema>): string;
|
|
105
|
+
//# sourceMappingURL=_shared.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_shared.ts"],"names":[],"mappings":"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"}
|