coverartarchive-mcp 1.0.0 → 1.0.2

package/README.md

@@ -22,3 +22,22 @@ The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code
 ## Limits and privacy
 
 This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. No credentials are required.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `cover_gallery`
+* `find_cover_releases`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-coverartarchive-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -12,3 +12,21 @@ export interface CoverInfo {
 export declare function getCover(mbid: string, kind: "release" | "release-group"): Promise<CoverInfo>;
 export declare function frontUrl(mbid: string, kind: "release" | "release-group", size?: 250 | 500 | 1200): string;
 export declare function formatCover(c: CoverInfo): string;
+export interface GalleryArgs {
+    mbid: string;
+    limit?: number;
+    front_only?: boolean;
+}
+export declare function coverGallery(args: GalleryArgs): Promise<string>;
+export interface FindArgs {
+    query: string;
+    limit?: number;
+    type?: string;
+}
+export declare function findCoverReleases(args: FindArgs): Promise<string>;
+export interface BytesArgs {
+    mbid: string;
+    size?: number;
+    image_id?: number;
+}
+export declare function coverImageBytes(args: BytesArgs): Promise<string>;

package/dist/api.js

@@ -50,3 +50,168 @@ export function formatCover(c) {
     ].filter(Boolean);
     return lines.join("\n");
 }
+// ---- muxA tools:
+const MB = "https://musicbrainz.org/ws/2";
+function cap(value, fallback, max) {
+    return Math.max(1, Math.min(Math.round(value ?? fallback), max));
+}
+const MBID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function mbGet(path) {
+    const res = await fetch(`${MB}${path}`, {
+        headers: { "User-Agent": "mrfentmen-coverartarchive-mcp/1.0 (https://github.com/mrfentmen)", Accept: "application/json" },
+        signal: AbortSignal.timeout(25000),
+    });
+    const body = await res.text();
+    if (!res.ok) {
+        let detail = "";
+        try {
+            detail = String(JSON.parse(body).error ?? "").slice(0, 160);
+        }
+        catch {
+            detail = body.slice(0, 120);
+        }
+        throw new CoverArtError(`MusicBrainz returned ${res.status}${detail ? `: ${detail}` : ""}`);
+    }
+    return JSON.parse(body);
+}
+async function coverIndex(mbid, kind) {
+    const res = await fetch(`${BASE}/${kind}/${mbid}`, {
+        headers: { "User-Agent": "coverartarchive-mcp/1.0", Accept: "application/json" },
+        redirect: "follow",
+        signal: AbortSignal.timeout(20000),
+    });
+    if (res.status === 404)
+        throw new CoverArtError(`No cover art archived for this ${kind} MBID yet.`);
+    if (!res.ok)
+        throw new CoverArtError(`Cover Art Archive error ${res.status}`);
+    return (await res.json());
+}
+export async function coverGallery(args) {
+    const mbid = String(args.mbid ?? "").trim().toLowerCase();
+    if (!MBID_RE.test(mbid))
+        throw new CoverArtError("Provide a MusicBrainz MBID, a 36 character dashed UUID.");
+    const kind = mbid === "" ? "release" : "release";
+    const d = await coverIndex(mbid, kind);
+    let images = (d.images ?? []);
+    if (!images.length)
+        return `The Cover Art Archive holds no images for ${kind} ${mbid}.`;
+    const fronts = images.filter((i) => i.front).length;
+    const approved = images.filter((i) => i.approved).length;
+    if (args.front_only === true)
+        images = images.filter((i) => i.front);
+    if (!images.length)
+        return `That ${kind} has ${fronts} image(s) but none is marked as a front cover.`;
+    const limit = cap(args.limit, 10, 60);
+    const shown = images.slice(0, limit);
+    const release = (d.release ?? {});
+    return [
+        `Cover Art Archive gallery for ${kind} ${mbid}: ${images.length} image(s) shown of ${(d.images ?? []).length} archived, ${fronts} front cover(s), ${approved} approved.`,
+        release.title ? `Release title: ${String(release.title).slice(0, 120)}` : "",
+        Array.isArray(release.media) && release.media.length
+            ? `Media: ${release.media.map((m) => `${m.format ?? "?"} (${m["format-id"] ?? "?"}) x${m["track-count"] ?? "?"}`).join(", ")}`
+            : "",
+        ...shown.map((im, i) => {
+            const thumbs = (im.thumbnails ?? {});
+            return [
+                `${i + 1}. image id ${im.id ?? "?"} | types ${Array.isArray(im.types) ? im.types.join(", ") : "untyped"}` +
+                    `${im.front ? " | FRONT" : ""}${im.back ? " | BACK" : ""}${im.approved ? " | approved" : " | unapproved"}`,
+                `   full: ${im.image ?? "not reported"}`,
+                ...Object.entries(thumbs).map(([k, v]) => `   ${k}: ${v}`),
+                im.comment ? `   comment: ${String(im.comment).slice(0, 140)}` : "",
+            ]
+                .filter(Boolean)
+                .join("\n");
+        }),
+        images.length > shown.length ? `plus ${images.length - shown.length} more images` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+export async function findCoverReleases(args) {
+    const query = String(args.query ?? "").trim();
+    if (!query)
+        throw new CoverArtError("Provide a search query, e.g. an artist or release title.");
+    const limit = cap(args.limit, 5, 25);
+    const entity = (args.type ?? "release").trim().toLowerCase();
+    if (!["release", "release-group"].includes(entity)) {
+        return `Unknown entity type "${args.type}". Use release or release-group.`;
+    }
+    const d = await mbGet(`/${entity}?query=${encodeURIComponent(query)}&fmt=json&limit=${limit}`);
+    const rows = (d[`${entity}s`] ?? []);
+    if (!rows.length)
+        return `MusicBrainz has no ${entity} matching "${query}".`;
+    const out = [`MusicBrainz ${entity} search for "${query}": ${Number(d.count ?? rows.length).toLocaleString("en-US")} match(es), showing ${rows.length}.`];
+    let withArt = 0;
+    for (const [i, r] of rows.entries()) {
+        const id = String(r.id ?? "");
+        const hasArt = await coverIndex(id, entity)
+            .then((x) => (x.images ?? []).length)
+            .catch(() => 0);
+        if (hasArt)
+            withArt += 1;
+        const artist = (r["artist-credit"] ?? []);
+        const artistName = artist.map((a) => String(a.name ?? a.artist?.name ?? "")).join("");
+        const date = String(r["first-release-date"] ?? r.date ?? "");
+        out.push(`${i + 1}. [${id}] ${String(r.title ?? "untitled").slice(0, 80)}${artistName ? ` by ${artistName.slice(0, 60)}` : ""}` +
+            `${date ? ` | ${date}` : ""} | cover images: ${hasArt ? `${hasArt} in the archive` : "none archived"}` +
+            `${r.status ? ` | status ${r.status}` : ""}`);
+    }
+    out.push("", `${withArt} of ${rows.length} listed ${entity}s have artwork in the Cover Art Archive. Pass an MBID to cover_gallery for the full image list.`);
+    return out.join("\n");
+}
+export async function coverImageBytes(args) {
+    const mbid = String(args.mbid ?? "").trim().toLowerCase();
+    if (!MBID_RE.test(mbid))
+        throw new CoverArtError("Provide a MusicBrainz MBID, a 36 character dashed UUID.");
+    const size = Math.round(Number(args.size ?? 500));
+    if (![250, 500, 1200].includes(size))
+        return `Size must be 250, 500 or 1200, not ${args.size}.`;
+    const d = await coverIndex(mbid, "release");
+    const images = (d.images ?? []);
+    if (!images.length)
+        return `The Cover Art Archive holds no images for release ${mbid}.`;
+    let target = images[0];
+    if (args.image_id != null) {
+        const found = images.find((i) => Number(i.id) === Number(args.image_id));
+        if (!found)
+            return `Image id ${args.image_id} is not in this release. Available: ${images.map((i) => i.id).join(", ")}.`;
+        target = found;
+    }
+    const url = `${BASE}/release/${mbid}/${target.id}-${size}.jpg`;
+    const res = await fetch(url, { headers: { "User-Agent": "coverartarchive-mcp/1.0" }, redirect: "follow", signal: AbortSignal.timeout(25000) });
+    if (!res.ok)
+        throw new CoverArtError(`Could not fetch the ${size}px image: HTTP ${res.status}`);
+    const buffer = Buffer.from(await res.arrayBuffer());
+    const type = res.headers.get("content-type") ?? "unknown";
+    // PNG and JPEG headers are enough to confirm the bytes really are an image.
+    const isJpeg = buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+    const isPng = buffer[0] === 0x89 && buffer.subarray(1, 4).toString("ascii") === "PNG";
+    const dims = isJpeg ? jpegSize(buffer) : isPng ? pngSize(buffer) : null;
+    return [
+        `Cover image ${size}px for release ${mbid}, image id ${target.id}:`,
+        `  served as ${type} | ${buffer.length.toLocaleString("en-US")} bytes${dims ? ` | ${dims.width} x ${dims.height} pixels` : ""}`,
+        `  header check: ${isJpeg ? "valid JPEG SOI marker" : isPng ? "valid PNG signature" : "unrecognised image header"}`,
+        `  final URL: ${res.url}`,
+        `  archive page: ${target.image ?? "not reported"}`,
+    ].join("\n");
+}
+function pngSize(b) {
+    if (b.length < 24)
+        return null;
+    return { width: b.readUInt32BE(16), height: b.readUInt32BE(20) };
+}
+function jpegSize(b) {
+    let i = 2;
+    while (i < b.length - 9) {
+        if (b[i] !== 0xff) {
+            i += 1;
+            continue;
+        }
+        const marker = b[i + 1];
+        if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+            return { height: b.readUInt16BE(i + 5), width: b.readUInt16BE(i + 7) };
+        }
+        i += 2 + b.readUInt16BE(i + 2);
+    }
+    return null;
+}

package/dist/license.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export declare function premiumRequired(tool: string): Promise<string | null>;

package/dist/license.js

@@ -0,0 +1,79 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "coverartarchive-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "cover_gallery",
+    "find_cover_releases",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { CoverArtError, formatCover, frontUrl, getCover } from "./api.js";
+import { CoverArtError, formatCover, frontUrl, getCover, coverGallery, findCoverReleases, coverImageBytes } from "./api.js";
+import { premiumRequired } from "./license.js";
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -42,6 +43,55 @@ export function createServer() {
             return textError(errorMessage(e));
         }
     });
+    server.registerTool("cover_gallery", {
+        title: "Cover gallery",
+        description: "List every image the Cover Art Archive holds for a MusicBrainz MBID with its types, front and back flags, approval state, comment and full and thumbnail URLs, not just the single front cover.",
+        inputSchema: z.object({ mbid: z.string().describe("MusicBrainz MBID, a 36 character UUID."), limit: z.number().describe("Max images.").optional(), front_only: z.boolean().describe("Only front covers.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: cover_gallery ----
+        const paywallMessage = await premiumRequired("cover_gallery");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await coverGallery(args));
+        }
+        catch (e) {
+            return textError(e instanceof Error ? `Error: ${e.message}` : String(e));
+        }
+    });
+    server.registerTool("find_cover_releases", {
+        title: "Find cover releases",
+        description: "Search MusicBrainz for releases or release groups and report which of the results actually have artwork in the Cover Art Archive, with artists, dates and status.",
+        inputSchema: z.object({ query: z.string().describe("Artist or release search terms."), limit: z.number().describe("Max results.").optional(), type: z.string().describe("release or release-group.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: find_cover_releases ----
+        const paywallMessage = await premiumRequired("find_cover_releases");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await findCoverReleases(args));
+        }
+        catch (e) {
+            return textError(e instanceof Error ? `Error: ${e.message}` : String(e));
+        }
+    });
+    server.registerTool("cover_image_bytes", {
+        title: "Cover image bytes",
+        description: "Download a specific cover art size and verify it really is an image by checking the file header, reporting content type, byte size, pixel dimensions and the final archive URL.",
+        inputSchema: z.object({ mbid: z.string().describe("MusicBrainz MBID."), size: z.number().describe("250, 500 or 1200.").optional(), image_id: z.number().describe("Specific image id when a release has several.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await coverImageBytes(args));
+        }
+        catch (e) {
+            return textError(e instanceof Error ? `Error: ${e.message}` : String(e));
+        }
+    });
     return server;
 }
 function errorMessage(e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coverartarchive-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Keyless MCP server for the Cover Art Archive: album and single artwork by MusicBrainz ID, front/back covers and thumbnails.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/coverartarchive-mcp",