coverartarchive-mcp 1.0.0

package/README.md

@@ -0,0 +1,24 @@
+# Cover Art Archive MCP
+
+Keyless MCP server for the Cover Art Archive: album and single artwork by MusicBrainz ID, front/back covers and thumbnails.
+
+Pairs well with `musicbrainz-mcp` (find the MBID), `audius-mcp`, and `vgmdb-mcp`.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `get_cover`: Archived artwork for a release or release-group MBID.
+- `front_url`: Direct front-cover image URL builder (no fetch).
+
+## 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.

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+export declare class CoverArtError extends Error {
+}
+export interface CoverInfo {
+    mbid: string;
+    kind: string;
+    front?: string;
+    frontThumb?: string;
+    back?: string;
+    imageCount: number;
+    allImages: string[];
+}
+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;

package/dist/api.js

@@ -0,0 +1,52 @@
+/**
+ * Cover Art Archive client, keyless.
+ * Look up artwork for a MusicBrainz release or release-group MBID.
+ * Docs: https://musicbrainz.org/doc/Cover_Art_Archive/API
+ */
+const BASE = "https://coverartarchive.org";
+export class CoverArtError extends Error {
+}
+const MBID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function fetchJson(url) {
+    const res = await fetch(url, {
+        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 MBID yet.");
+    if (!res.ok)
+        throw new CoverArtError(`Cover Art Archive error ${res.status}`);
+    return (await res.json());
+}
+export async function getCover(mbid, kind) {
+    const clean = mbid.trim().toLowerCase();
+    if (!MBID.test(clean))
+        throw new CoverArtError(`Not a valid MBID: "${mbid}". Find one with musicbrainz-mcp first.`);
+    const data = await fetchJson(`${BASE}/${kind}/${clean}/`);
+    const images = Array.isArray(data.images) ? data.images : [];
+    const front = images.find((i) => i.front === true);
+    const back = images.find((i) => i.back === true);
+    return {
+        mbid: clean,
+        kind,
+        front: front?.image,
+        frontThumb: front?.thumbnails?.["500"] ?? front?.thumbnails?.small,
+        back: back?.image,
+        imageCount: images.length,
+        allImages: images.map((i) => String(i.image)).slice(0, 10),
+    };
+}
+export function frontUrl(mbid, kind, size = 500) {
+    return `${BASE}/${kind}/${mbid.trim().toLowerCase()}/front-${size}`;
+}
+export function formatCover(c) {
+    const lines = [
+        `Cover art for ${c.kind} ${c.mbid} (${c.imageCount} image${c.imageCount === 1 ? "" : "s"} archived)`,
+        c.front ? `Front: ${c.front}` : "No front cover archived.",
+        c.frontThumb ? `Front thumbnail: ${c.frontThumb}` : "",
+        c.back ? `Back: ${c.back}` : "",
+        c.allImages.length > 1 ? `All images:\n- ${c.allImages.join("\n- ")}` : "",
+    ].filter(Boolean);
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,53 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CoverArtError, formatCover, frontUrl, getCover } from "./api.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 };
+export function createServer() {
+    const server = new McpServer({
+        name: "coverartarchive-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("get_cover", {
+        title: "Get cover art",
+        description: "Get archived cover art for a MusicBrainz release or release-group: front/back URLs, thumbnails, image count.",
+        inputSchema: z.object({
+            mbid: z.string().describe("MusicBrainz ID, e.g. '76df3287-6cda-33eb-8e9a-044b5e15ffdd' (find it with musicbrainz-mcp)"),
+            kind: z.enum(["release", "release-group"]).default("release"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ mbid, kind }) => {
+        try {
+            return text(formatCover(await getCover(mbid, kind)));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("front_url", {
+        title: "Front cover URL",
+        description: "Build a direct front-cover image URL for a MusicBrainz ID without fetching. Useful for embedding artwork.",
+        inputSchema: z.object({
+            mbid: z.string().describe("MusicBrainz release or release-group MBID"),
+            kind: z.enum(["release", "release-group"]).default("release"),
+            size: z.enum(["250", "500", "1200"]).default("500").describe("Thumbnail size in px"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ mbid, kind, size }) => {
+        try {
+            return text(frontUrl(mbid, kind, Number(size)));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof CoverArtError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "coverartarchive-mcp",
+  "version": "1.0.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/awesome-mcps.git"
+  },
+  "bin": {
+    "coverartarchive-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "cover-art",
+    "musicbrainz",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}