@withpica/mcp-server 2.11.0 → 2.23.0

package/dist/tools/releases.js

@@ -1,5 +1,72 @@
 // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
 import { formatSuccess, formatStructuredList } from "@withpica/mcp-utils";
+/**
+ * Canonical write-schema for `releases`. Every property below must
+ * correspond to a real column on `public.releases`. Keep this list
+ * tight — reintroducing a phantom field is the exact regression
+ * ADR-174 Phase 2 exists to prevent.
+ */
+const RELEASE_WRITE_PROPERTIES = {
+    title: {
+        type: "string",
+        description: "Release title",
+    },
+    release_date: {
+        type: "string",
+        description: "Release date (YYYY-MM-DD)",
+    },
+    release_type: {
+        type: "string",
+        description: "Release type",
+        enum: ["album", "ep", "single", "compilation"],
+    },
+    pre_release_date: {
+        type: "string",
+        description: "Pre-release / announcement date (YYYY-MM-DD)",
+    },
+    upc: {
+        type: "string",
+        description: "Universal Product Code (UPC/EAN barcode)",
+    },
+    catalog_number: {
+        type: "string",
+        description: "Label catalog number",
+    },
+    label_organization_id: {
+        type: "string",
+        description: "organisations.id of the label (must be an org with org_type='label'). " +
+            "Resolve a label name to an ID via pica_labels_query first — never pass a free-text name.",
+    },
+    distributor_organization_id: {
+        type: "string",
+        description: "organisations.id of the distributor. Resolve a distributor name via pica_search_all first.",
+    },
+    artwork_url: {
+        type: "string",
+        description: "Album artwork URL",
+    },
+    spotify_album_uri: {
+        type: "string",
+        description: "Spotify album URI (e.g. spotify:album:…)",
+    },
+    spotify_url: {
+        type: "string",
+        description: "Spotify album web URL",
+    },
+    apple_music_url: {
+        type: "string",
+        description: "Apple Music album URL",
+    },
+    other_urls: {
+        type: "object",
+        description: "DSP URLs keyed by service name (e.g. { tidal: '…', deezer: '…' })",
+        additionalProperties: { type: "string" },
+    },
+    notes: {
+        type: "string",
+        description: "Internal notes",
+    },
+};
 export class ReleasesTools {
     pica;
     constructor(pica) {
@@ -10,7 +77,7 @@ export class ReleasesTools {
             {
                 definition: {
                     name: "pica_releases_list",
-                    description: "List releases — albums, EPs, and singles with release dates, labels, and UPCs.",
+                    description: "List releases — albums, EPs, and singles with release dates, labels, distributors, and UPCs.",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -40,69 +107,478 @@ export class ReleasesTools {
             {
                 definition: {
                     name: "pica_releases_create",
-                    description: "Create a new release — set the title, date, release type, label, and UPC.",
+                    description: "Create a new release — set title, dates, type, catalog number, " +
+                        "label/distributor organisation IDs, artwork, DSP URLs, and notes. " +
+                        "For label_organization_id use pica_labels_query first to resolve a name to an ID " +
+                        "(freetext label names are not accepted — the DB stores label as an FK to organisations).",
+                    inputSchema: {
+                        type: "object",
+                        properties: RELEASE_WRITE_PROPERTIES,
+                        required: ["title"],
+                    },
+                },
+                executor: this.createRelease.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_releases_update",
+                    description: "Update release details — any field in the release write schema. " +
+                        "For label_organization_id use pica_labels_query first to resolve a name to an ID.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            title: {
+                            id: { type: "string", description: "Release ID" },
+                            ...RELEASE_WRITE_PROPERTIES,
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.updateRelease.bind(this),
+            },
+            // ADR-173: release-track primitives + compound workflow
+            {
+                definition: {
+                    name: "pica_releases_attach_track",
+                    description: "Attach a recording and/or work to a release at a specific (disc, track) position. " +
+                        "At least one of recording_id or work_id must be provided. Idempotent on " +
+                        "(release_id, disc_number, track_number) — a second call at the same position " +
+                        "updates the existing row rather than creating a duplicate. " +
+                        "→ then: pica_releases_list_tracks (verify tracklist), pica_releases_reorder_tracks (change order)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release_id: { type: "string", description: "Release ID" },
+                            recording_id: {
                                 type: "string",
-                                description: "Release title",
+                                description: "Recording ID (optional — at least one of recording_id or work_id must be provided)",
                             },
-                            release_date: {
+                            work_id: {
                                 type: "string",
-                                description: "Release date (YYYY-MM-DD)",
+                                description: "Work ID (optional — omit for licensed-masters releases where no composition record exists)",
                             },
-                            release_type: {
-                                type: "string",
-                                description: "Release type (album, ep, single, compilation)",
+                            track_number: {
+                                type: "number",
+                                description: "Position on disc (1-based)",
                             },
-                            upc: {
-                                type: "string",
-                                description: "Universal Product Code (UPC/EAN barcode)",
+                            disc_number: {
+                                type: "number",
+                                description: "Disc number (default 1)",
                             },
-                            catalog_number: {
-                                type: "string",
-                                description: "Label catalog number",
+                        },
+                        required: ["release_id", "track_number"],
+                    },
+                },
+                executor: this.attachTrack.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_releases_list_tracks",
+                    description: "List tracks on a release in (disc_number, track_number) order with " +
+                        "inlined title, artist, ISRC, and duration from the linked recording and work. " +
+                        "→ then: pica_releases_reorder_tracks (change order), pica_recordings_inspect (deep-dive a track)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release_id: { type: "string", description: "Release ID" },
+                        },
+                        required: ["release_id"],
+                    },
+                },
+                executor: this.listTracks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_releases_detach_track",
+                    description: "Remove a track from a release by position. Soft-confirmation: call without " +
+                        "confirm:true to see a preview of the row that would be removed, then call " +
+                        "again with confirm:true to execute.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release_id: { type: "string", description: "Release ID" },
+                            track_number: {
+                                type: "number",
+                                description: "Position on disc (1-based)",
+                            },
+                            disc_number: {
+                                type: "number",
+                                description: "Disc number (default 1)",
+                            },
+                            confirm: {
+                                type: "boolean",
+                                description: "Set to true to execute the detach after reviewing the preview",
                             },
                         },
-                        required: ["title"],
+                        required: ["release_id", "track_number"],
                     },
                 },
-                executor: this.createRelease.bind(this),
+                executor: this.detachTrack.bind(this),
             },
             {
                 definition: {
-                    name: "pica_releases_update",
-                    description: "Update release details — title, date, release type, label, UPC, or catalog number.",
+                    name: "pica_releases_reorder_tracks",
+                    description: "Reorder tracks on a release atomically. Pass the full new order as an array " +
+                        "of { track_id, track_number, disc_number } — the entire reorder commits or " +
+                        "rolls back as one transaction. Duplicate (disc_number, track_number) pairs " +
+                        "in the payload are rejected before any DB write.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            id: { type: "string", description: "Release ID" },
-                            title: { type: "string", description: "Updated title" },
-                            release_date: {
-                                type: "string",
-                                description: "Updated release date (YYYY-MM-DD)",
+                            release_id: { type: "string", description: "Release ID" },
+                            new_order: {
+                                type: "array",
+                                description: "New ordering of tracks. Every existing track should appear here.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        track_id: {
+                                            type: "string",
+                                            description: "release_tracks.id",
+                                        },
+                                        track_number: { type: "number" },
+                                        disc_number: {
+                                            type: "number",
+                                            description: "Default 1",
+                                        },
+                                    },
+                                    required: ["track_id", "track_number"],
+                                },
+                            },
+                        },
+                        required: ["release_id", "new_order"],
+                    },
+                },
+                executor: this.reorderTracks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_releases_attach_recording_with_work",
+                    description: "Attach a recording to a release at a specific position, automatically " +
+                        "pulling the recording's linked work (if any) onto the same track row. " +
+                        "Saves agents the recordings.work_id lookup that pica_releases_attach_track " +
+                        "would otherwise require. Idempotent on (release_id, disc_number, track_number).",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release_id: { type: "string", description: "Release ID" },
+                            recording_id: { type: "string", description: "Recording ID" },
+                            track_number: {
+                                type: "number",
+                                description: "Position on disc (1-based)",
+                            },
+                            disc_number: {
+                                type: "number",
+                                description: "Disc number (default 1)",
+                            },
+                        },
+                        required: ["release_id", "recording_id", "track_number"],
+                    },
+                },
+                executor: this.attachRecordingWithWork.bind(this),
+            },
+            // ADR-175: release workflow tools — compound operations on the primitives
+            {
+                definition: {
+                    name: "pica_releases_bulk_attach_tracks",
+                    description: "Attach many tracks to a release in a single atomic call. Same " +
+                        "idempotency semantics as pica_releases_attach_track — a duplicate " +
+                        "(disc_number, track_number) position updates rather than duplicates. " +
+                        "Duplicate positions WITHIN the payload are rejected before any DB " +
+                        "write. Use when you have an existing release and the full tracklist " +
+                        "at once; use pica_releases_create_with_tracks when the release does " +
+                        "not yet exist.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release_id: { type: "string", description: "Release ID" },
+                            tracks: {
+                                type: "array",
+                                description: "Tracks to attach. Each entry needs at least one of recording_id " +
+                                    "or work_id, plus track_number (1-based).",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        recording_id: {
+                                            type: "string",
+                                            description: "Recording ID (optional if work_id is present)",
+                                        },
+                                        work_id: {
+                                            type: "string",
+                                            description: "Work ID (optional if recording_id is present)",
+                                        },
+                                        track_number: {
+                                            type: "number",
+                                            description: "Position on disc (1-based)",
+                                        },
+                                        disc_number: {
+                                            type: "number",
+                                            description: "Disc number (default 1)",
+                                        },
+                                    },
+                                    required: ["track_number"],
+                                },
+                            },
+                        },
+                        required: ["release_id", "tracks"],
+                    },
+                },
+                executor: this.bulkAttachTracks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_releases_move_track",
+                    description: "Swap two track positions on a release atomically. Internally reads " +
+                        "both rows and writes them with exchanged (disc_number, track_number) " +
+                        "in one transaction. For the rare full re-sequence, use " +
+                        "pica_releases_reorder_tracks instead.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release_id: { type: "string", description: "Release ID" },
+                            from: {
+                                type: "object",
+                                description: "Source position",
+                                properties: {
+                                    track_number: { type: "number" },
+                                    disc_number: { type: "number", description: "Default 1" },
+                                },
+                                required: ["track_number"],
                             },
-                            release_type: {
+                            to: {
+                                type: "object",
+                                description: "Destination position (must be occupied — this is a swap, not a slide)",
+                                properties: {
+                                    track_number: { type: "number" },
+                                    disc_number: { type: "number", description: "Default 1" },
+                                },
+                                required: ["track_number"],
+                            },
+                        },
+                        required: ["release_id", "from", "to"],
+                    },
+                },
+                executor: this.moveTrack.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_releases_attach_track_by_identifier",
+                    description: "Attach a track by external identifier (ISRC, Spotify URL, Spotify " +
+                        "track URI, YouTube video id, MusicBrainz recording id, MLC " +
+                        "recording id). The identifier is resolved to an internal recording " +
+                        "id in the caller's organisation before attaching. This tool does " +
+                        "NOT create recordings — if the identifier resolves to nothing the " +
+                        "call fails with a recovery hint pointing at pica_import_streaming_" +
+                        "link or the relevant import tool. Intended for the post-import " +
+                        "attach step. → then: pica_releases_list_tracks (verify tracklist).",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release_id: { type: "string", description: "Release ID" },
+                            identifier_type: {
                                 type: "string",
-                                description: "Updated release type (album, ep, single, compilation)",
+                                enum: [
+                                    "isrc",
+                                    "spotify_url",
+                                    "spotify_track_uri",
+                                    "youtube_video_id",
+                                    "musicbrainz_recording_id",
+                                    "mlc_recording_id",
+                                ],
+                                description: "Type of external identifier to resolve",
                             },
-                            upc: {
+                            value: {
                                 type: "string",
-                                description: "Updated UPC",
+                                description: "The identifier value itself",
+                            },
+                            track_number: {
+                                type: "number",
+                                description: "Position on disc (1-based)",
+                            },
+                            disc_number: {
+                                type: "number",
+                                description: "Disc number (default 1)",
                             },
-                            catalog_number: {
+                        },
+                        required: [
+                            "release_id",
+                            "identifier_type",
+                            "value",
+                            "track_number",
+                        ],
+                    },
+                },
+                executor: this.attachTrackByIdentifier.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_releases_create_with_tracks",
+                    description: "Create a release and its tracks in a single atomic transaction. " +
+                        "Any failure — FK violation, identifier lookup miss, invalid track " +
+                        "entry — rolls the entire release back. No partial releases. Each " +
+                        "track entry can pass recording_id/work_id directly OR pass an " +
+                        "identifier_lookup object which the tool resolves server-side " +
+                        "(same semantics as pica_releases_attach_track_by_identifier). " +
+                        "Use this when importing a new album — use pica_releases_bulk_" +
+                        "attach_tracks when the release already exists.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release: {
+                                type: "object",
+                                description: "Release fields (same shape as pica_releases_create). " +
+                                    "title is required; release_type defaults to 'single'.",
+                                properties: {
+                                    title: { type: "string", description: "Release title" },
+                                    release_type: {
+                                        type: "string",
+                                        enum: ["album", "ep", "single", "compilation"],
+                                        description: "Release type (default 'single')",
+                                    },
+                                    release_date: {
+                                        type: "string",
+                                        description: "Release date (YYYY-MM-DD)",
+                                    },
+                                    pre_release_date: {
+                                        type: "string",
+                                        description: "Pre-release / announcement date (YYYY-MM-DD)",
+                                    },
+                                    upc: { type: "string", description: "UPC / EAN barcode" },
+                                    catalog_number: {
+                                        type: "string",
+                                        description: "Label catalog number",
+                                    },
+                                    label_organization_id: {
+                                        type: "string",
+                                        description: "organisations.id of the label — resolve via pica_labels_query first.",
+                                    },
+                                    distributor_organization_id: {
+                                        type: "string",
+                                        description: "organisations.id of the distributor.",
+                                    },
+                                    artwork_url: {
+                                        type: "string",
+                                        description: "Album artwork URL",
+                                    },
+                                    spotify_album_uri: { type: "string" },
+                                    spotify_url: { type: "string" },
+                                    apple_music_url: { type: "string" },
+                                    other_urls: {
+                                        type: "object",
+                                        additionalProperties: { type: "string" },
+                                    },
+                                    notes: { type: "string" },
+                                },
+                                required: ["title"],
+                            },
+                            tracks: {
+                                type: "array",
+                                description: "Track entries. Each needs track_number plus one of: " +
+                                    "recording_id, work_id, or identifier_lookup.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        recording_id: { type: "string" },
+                                        work_id: { type: "string" },
+                                        identifier_lookup: {
+                                            type: "object",
+                                            description: "Resolve a recording by external identifier in " +
+                                                "the caller's org before inserting the track. " +
+                                                "Misses and collisions abort the whole create.",
+                                            properties: {
+                                                identifier_type: {
+                                                    type: "string",
+                                                    enum: [
+                                                        "isrc",
+                                                        "spotify_url",
+                                                        "spotify_track_uri",
+                                                        "youtube_video_id",
+                                                        "musicbrainz_recording_id",
+                                                        "mlc_recording_id",
+                                                    ],
+                                                },
+                                                value: { type: "string" },
+                                            },
+                                            required: ["identifier_type", "value"],
+                                        },
+                                        track_number: {
+                                            type: "number",
+                                            description: "Position on disc (1-based)",
+                                        },
+                                        disc_number: {
+                                            type: "number",
+                                            description: "Disc number (default 1)",
+                                        },
+                                    },
+                                    required: ["track_number"],
+                                },
+                            },
+                        },
+                        required: ["release", "tracks"],
+                    },
+                },
+                executor: this.createWithTracks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_releases_completeness_check",
+                    description: "Run the release-scoped completeness diligence report. Pass a " +
+                        "release_id for a single-release report, or omit for a scan of " +
+                        "every release in the caller's organisation. Returns a list of " +
+                        "issues per release with severity (critical/warning/suggestion) " +
+                        "and a recovery hint pointing at the right tool. Issues also " +
+                        "surface in pica_catalog_diligence; this tool gives release-" +
+                        "level granularity.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            release_id: {
                                 type: "string",
-                                description: "Updated catalog number",
+                                description: "Optional — a single release to check. Omit to scan " +
+                                    "every release in the organisation.",
                             },
                         },
-                        required: ["id"],
                     },
                 },
-                executor: this.updateRelease.bind(this),
+                executor: this.completenessCheck.bind(this),
             },
         ];
     }
+    async attachTrack(args) {
+        const track = await this.pica.releases.attachTrack(args.release_id, {
+            recording_id: args.recording_id ?? null,
+            work_id: args.work_id ?? null,
+            track_number: args.track_number,
+            disc_number: args.disc_number,
+        });
+        return formatSuccess("Track attached to release", track);
+    }
+    async listTracks(args) {
+        const tracks = await this.pica.releases.listTracks(args.release_id);
+        return formatSuccess("Release tracks retrieved", tracks);
+    }
+    async detachTrack(args) {
+        const result = await this.pica.releases.detachTrack(args.release_id, {
+            track_number: args.track_number,
+            disc_number: args.disc_number,
+            confirm: args.confirm,
+        });
+        const message = result?.data?.confirmed
+            ? "Track detached from release"
+            : "Preview of track to be detached — call again with confirm:true to execute";
+        return formatSuccess(message, result);
+    }
+    async reorderTracks(args) {
+        const tracks = await this.pica.releases.reorderTracks(args.release_id, args.new_order);
+        return formatSuccess("Release tracks reordered", tracks);
+    }
+    async attachRecordingWithWork(args) {
+        const track = await this.pica.releases.attachRecordingWithWork(args.release_id, {
+            recording_id: args.recording_id,
+            track_number: args.track_number,
+            disc_number: args.disc_number,
+        });
+        return formatSuccess("Recording attached to release with work", track);
+    }
     async listReleases(args) {
         const result = await this.pica.releases.list({
             limit: args.limit,
@@ -124,5 +600,35 @@ export class ReleasesTools {
         const release = await this.pica.releases.update(id, updates);
         return formatSuccess("Release updated", release);
     }
+    // ADR-175 workflow executors
+    async bulkAttachTracks(args) {
+        const tracks = await this.pica.releases.bulkAttachTracks(args.release_id, args.tracks);
+        return formatSuccess(`Bulk attached ${Array.isArray(args.tracks) ? args.tracks.length : 0} tracks`, tracks);
+    }
+    async moveTrack(args) {
+        const tracks = await this.pica.releases.moveTrack(args.release_id, args.from, args.to);
+        return formatSuccess("Tracks swapped", tracks);
+    }
+    async attachTrackByIdentifier(args) {
+        const result = await this.pica.releases.attachTrackByIdentifier(args.release_id, {
+            identifier_type: args.identifier_type,
+            value: args.value,
+            track_number: args.track_number,
+            disc_number: args.disc_number,
+        });
+        return formatSuccess("Track attached by identifier", result);
+    }
+    async createWithTracks(args) {
+        const result = await this.pica.releases.createWithTracks({
+            release: args.release,
+            tracks: args.tracks,
+        });
+        const count = Array.isArray(args.tracks) ? args.tracks.length : 0;
+        return formatSuccess(`Release created with ${count} tracks`, result);
+    }
+    async completenessCheck(args) {
+        const report = await this.pica.releases.completenessCheck(args.release_id ? { release_id: args.release_id } : undefined);
+        return formatSuccess("Release completeness report", report);
+    }
 }
 //# sourceMappingURL=releases.js.map