@withpica/mcp-server 2.10.0 → 2.22.0

package/dist/tools/publishers.js

@@ -31,17 +31,54 @@ export class PublishersTools {
             {
                 definition: {
                     name: "pica_publishers_create",
-                    description: "Create a new publisher record. Check pica_publishers_query first to avoid duplicates.",
+                    description: "Create (or fetch existing) publisher in the catalog-wide " +
+                        "`global_publishers` table. Idempotent by ipi_number — if a " +
+                        "publisher with the same IPI already exists, returns the existing " +
+                        "row. Check `pica_publishers_query` first to avoid duplicates and " +
+                        "to resolve parent_publisher_id.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            name: { type: "string", description: "Publisher name" },
-                            ipi: {
+                            name: { type: "string", description: "Publisher name." },
+                            ipi_number: {
                                 type: "string",
-                                description: "Publisher IPI number (9-11 digits)",
+                                description: "Publisher IPI number (9-11 digits; normalised to 11 with " +
+                                    "leading zero-padding). Required.",
+                            },
+                            legal_name: {
+                                type: "string",
+                                description: "Legal entity name (e.g. 'Example Publishing Ltd.') — optional.",
+                            },
+                            country: {
+                                type: "string",
+                                description: "ISO country code (e.g. 'GB', 'US').",
+                            },
+                            isni: {
+                                type: "string",
+                                description: "ISNI identifier (16-character alphanumeric) if the publisher has one.",
+                            },
+                            publisher_type: {
+                                type: "string",
+                                description: "Category label (e.g. 'major', 'indie', 'admin', 'self_published'). Freeform — no backend CHECK.",
+                            },
+                            wikidata_id: {
+                                type: "string",
+                                description: "Wikidata Q-number (e.g. 'Q123456').",
+                            },
+                            parent_publisher_id: {
+                                type: "string",
+                                description: "UUID of parent publisher for subsidiary/admin relationships. FK → global_publishers.id. Use `pica_publishers_query` to find the parent's ID before passing it here; the route returns FK_NOT_FOUND if the UUID does not exist.",
+                            },
+                            founded_date: {
+                                type: "string",
+                                description: "Founding date (YYYY-MM-DD).",
+                            },
+                            headquarters: {
+                                type: "string",
+                                description: "Freeform location (e.g. 'London, UK').",
                             },
                         },
-                        required: ["name"],
+                        required: ["name", "ipi_number"],
                     },
                 },
                 executor: this.createPublisher.bind(this),
@@ -59,10 +96,7 @@ export class PublishersTools {
         });
     }
     async createPublisher(args) {
-        const result = await this.pica.publishers.create({
-            name: args.name,
-            ipi: args.ipi,
-        });
+        const result = await this.pica.publishers.create(args);
         return formatSuccess("Publisher created", result);
     }
 }

package/dist/tools/publishers.js.map

@@ -1 +1 @@
-{"version":3,"file":"publishers.js","sourceRoot":"","sources":["../../src/tools/publishers.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAQ7D,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE1E,MAAM,OAAO,eAAe;IAClB,IAAI,CAAa;IAEzB,YAAY,IAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,QAAQ;QACN,OAAO;YACL;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,uBAAuB;oBAC7B,WAAW,EACT,2EAA2E;wBAC3E,0DAA0D;oBAC5D,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,iCAAiC;6BAC/C;4BACD,KAAK,EAAE;gCACL,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,2BAA2B;6BACzC;yBACF;qBACF;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;aAC1C;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,wBAAwB;oBAC9B,WAAW,EACT,uFAAuF;oBACzF,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE;4BACvD,GAAG,EAAE;gCACH,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,oCAAoC;6BAClD;yBACF;wBACD,QAAQ,EAAE,CAAC,MAAM,CAAC;qBACnB;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;aAC1C;SACF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,eAAe,CAC3B,IAA6B;QAE7B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAC7C,KAAK,EAAE,IAAI,CAAC,KAA2B;YACvC,KAAK,EAAG,IAAI,CAAC,KAAgB,IAAI,EAAE;SACpC,CAAC,CAAC;QACH,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACvE,OAAO,oBAAoB,CAAC,UAAU,EAAE,WAAW,EAAE;YACnD,KAAK,EAAE,UAAU,CAAC,MAAM;SACzB,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,eAAe,CAC3B,IAA6B;QAE7B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAC/C,IAAI,EAAE,IAAI,CAAC,IAAc;YACzB,GAAG,EAAE,IAAI,CAAC,GAAyB;SACpC,CAAC,CAAC;QACH,OAAO,aAAa,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;CACF"}
+{"version":3,"file":"publishers.js","sourceRoot":"","sources":["../../src/tools/publishers.ts"],"names":[],"mappings":"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"}

package/dist/tools/recordings.d.ts

@@ -8,34 +8,34 @@
 import { PicaClient } from "@withpica/mcp-sdk";
 import { ToolDefinition, ToolExecutor } from "./index.js";
 export declare class RecordingsTools {
-    private pica;
-    constructor(pica: PicaClient);
-    /**
-     * Get all recordings tools
-     */
-    getTools(): Array<{
-        definition: ToolDefinition;
-        executor: ToolExecutor;
-    }>;
-    /**
-     * Query recordings — list all, search by text, or filter by work
-     */
-    private queryRecordings;
-    /**
-     * Inspect a recording — get details with optional section filtering
-     */
-    private inspectRecording;
-    /**
-     * Create recording
-     */
-    private createRecording;
-    /**
-     * Update recording
-     */
-    private updateRecording;
-    /**
-     * Delete recording
-     */
-    private deleteRecording;
+  private pica;
+  constructor(pica: PicaClient);
+  /**
+   * Get all recordings tools
+   */
+  getTools(): Array<{
+    definition: ToolDefinition;
+    executor: ToolExecutor;
+  }>;
+  /**
+   * Query recordings — list all, search by text, or filter by work
+   */
+  private queryRecordings;
+  /**
+   * Inspect a recording — get details with optional section filtering
+   */
+  private inspectRecording;
+  /**
+   * Create recording
+   */
+  private createRecording;
+  /**
+   * Update recording
+   */
+  private updateRecording;
+  /**
+   * Delete recording
+   */
+  private deleteRecording;
 }
-//# sourceMappingURL=recordings.d.ts.map
+//# sourceMappingURL=recordings.d.ts.map

package/dist/tools/recovery-hints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recovery-hints.d.ts","sourceRoot":"","sources":["../../src/tools/recovery-hints.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CA+QzD,CAAC;AAEF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,YAAY,GAAG,SAAS,CAI1B"}
+{"version":3,"file":"recovery-hints.d.ts","sourceRoot":"","sources":["../../src/tools/recovery-hints.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAqUzD,CAAC;AAEF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,YAAY,GAAG,SAAS,CAI1B"}

package/dist/tools/recovery-hints.js

@@ -125,7 +125,19 @@ export const RECOVERY_HINTS = {
         },
     ],
     // ── enrichment tools ──
+    //
+    // ADR-179 Phase 1 (2026-04-17): the five per-source `pica_enrich_work_*`
+    // tools were folded into `pica_resolve_work`. Every call now returns
+    // `TOOL_DEPRECATED` (jsonrpc -32070) with a suggested replacement call.
+    // The NO_MATCH / MISSING_INPUT hints below are dead code today but stay
+    // in the registry until the tools are removed in the next minor so
+    // they don't disappear from `pica_tool_details` mid-version.
     pica_enrich_work_spotify: [
+        {
+            error_code: "TOOL_DEPRECATED",
+            suggestion: "deprecated — use pica_resolve_work with sources: ['spotify']",
+            next_tool: "pica_resolve_work",
+        },
         {
             error_code: "NO_MATCH",
             suggestion: "no Spotify match — try MusicBrainz",
@@ -138,6 +150,11 @@ export const RECOVERY_HINTS = {
         },
     ],
     pica_enrich_work_musicbrainz: [
+        {
+            error_code: "TOOL_DEPRECATED",
+            suggestion: "deprecated — use pica_resolve_work with sources: ['musicbrainz']",
+            next_tool: "pica_resolve_work",
+        },
         {
             error_code: "NO_MATCH",
             suggestion: "no MusicBrainz match — try MLC",
@@ -145,6 +162,11 @@ export const RECOVERY_HINTS = {
         },
     ],
     pica_enrich_work_mlc: [
+        {
+            error_code: "TOOL_DEPRECATED",
+            suggestion: "deprecated — use pica_resolve_work with sources: ['mlc']",
+            next_tool: "pica_resolve_work",
+        },
         {
             error_code: "NO_MATCH",
             suggestion: "no MLC match — try Discogs",
@@ -157,6 +179,11 @@ export const RECOVERY_HINTS = {
         },
     ],
     pica_enrich_work_discogs: [
+        {
+            error_code: "TOOL_DEPRECATED",
+            suggestion: "deprecated — use pica_resolve_work with sources: ['discogs']",
+            next_tool: "pica_resolve_work",
+        },
         {
             error_code: "NO_MATCH",
             suggestion: "no Discogs match — try adding identifiers manually",
@@ -164,13 +191,30 @@ export const RECOVERY_HINTS = {
         },
     ],
     pica_enrich_work_youtube: [
+        {
+            error_code: "TOOL_DEPRECATED",
+            suggestion: "deprecated — use pica_resolve_work with sources: ['youtube']",
+            next_tool: "pica_resolve_work",
+        },
         {
             error_code: "NO_MATCH",
             suggestion: "no YouTube data — ensure a YouTube video is linked",
             next_tool: "pica_multimedia_link_youtube",
         },
     ],
+    //
+    // ADR-179 Phase 2 (2026-04-17): the two per-source `pica_people_enrich_*`
+    // tools were folded into `pica_resolve_person`. Every call now returns
+    // `TOOL_DEPRECATED` (jsonrpc -32070) with a suggested replacement call.
+    // The NO_MATCH hints below are dead code today but stay in the registry
+    // until the tools are removed in the next minor so they don't disappear
+    // from `pica_tool_details` mid-version.
     pica_people_enrich_isni: [
+        {
+            error_code: "TOOL_DEPRECATED",
+            suggestion: "deprecated — use pica_resolve_person with sources: ['isni']",
+            next_tool: "pica_resolve_person",
+        },
         {
             error_code: "NO_MATCH",
             suggestion: "no ISNI match — try MusicBrainz",
@@ -178,6 +222,11 @@ export const RECOVERY_HINTS = {
         },
     ],
     pica_people_enrich_musicbrainz: [
+        {
+            error_code: "TOOL_DEPRECATED",
+            suggestion: "deprecated — use pica_resolve_person with sources: ['musicbrainz']",
+            next_tool: "pica_resolve_person",
+        },
         {
             error_code: "NO_MATCH",
             suggestion: "no MusicBrainz match — try adding identifiers manually",

package/dist/tools/recovery-hints.js.map

@@ -1 +1 @@
-{"version":3,"file":"recovery-hints.js","sourceRoot":"","sources":["../../src/tools/recovery-hints.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"recovery-hints.js","sourceRoot":"","sources":["../../src/tools/recovery-hints.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAe7D,MAAM,CAAC,MAAM,cAAc,GAAmC;IAC5D,0BAA0B;IAC1B,iBAAiB,EAAE;QACjB;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,8BAA8B;YAC1C,SAAS,EAAE,kBAAkB;SAC9B;QACD;YACE,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,wCAAwC;YACpD,SAAS,EAAE,oBAAoB;SAChC;KACF;IACD,sBAAsB,EAAE;QACtB;YACE,UAAU,EAAE,mBAAmB;YAC/B,UAAU,EAAE,gDAAgD;YAC5D,SAAS,EAAE,kBAAkB;SAC9B;KACF;IACD,kBAAkB,EAAE;QAClB;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,+BAA+B;YAC3C,SAAS,EAAE,mBAAmB;SAC/B;QACD;YACE,UAAU,EAAE,oBAAoB;YAChC,UAAU,EAAE,qCAAqC;YACjD,SAAS,EAAE,qBAAqB;SACjC;KACF;IACD,sBAAsB,EAAE;QACtB;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,+BAA+B;YAC3C,SAAS,EAAE,uBAAuB;SACnC;KACF;IACD,sBAAsB,EAAE;QACtB;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,4CAA4C;YACxD,SAAS,EAAE,uBAAuB;SACnC;QACD;YACE,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,6BAA6B;YACzC,SAAS,EAAE,yBAAyB;SACrC;KACF;IACD,oBAAoB,EAAE;QACpB;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,oBAAoB;YAChC,SAAS,EAAE,oBAAoB;SAChC;KACF;IACD,qBAAqB,EAAE;QACrB;YACE,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,2BAA2B;YACvC,SAAS,EAAE,sBAAsB;SAClC;QACD;YACE,UAAU,EAAE,gBAAgB;YAC5B,UAAU,EAAE,4BAA4B;YACxC,SAAS,EAAE,yBAAyB;SACrC;KACF;IACD,gBAAgB,EAAE;QAChB;YACE,UAAU,EAAE,qBAAqB;YACjC,UAAU,EAAE,kBAAkB;YAC9B,SAAS,EAAE,gBAAgB;SAC5B;QACD;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,mBAAmB;YAC/B,SAAS,EAAE,gBAAgB;SAC5B;KACF;IACD,iBAAiB,EAAE;QACjB;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,iBAAiB;YAC7B,SAAS,EAAE,iBAAiB;SAC7B;KACF;IACD,kBAAkB,EAAE;QAClB;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,oBAAoB;YAChC,SAAS,EAAE,kBAAkB;SAC9B;KACF;IACD,2BAA2B,EAAE;QAC3B;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,kBAAkB;YAC9B,SAAS,EAAE,4BAA4B;SACxC;KACF;IACD,+BAA+B,EAAE;QAC/B;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,+BAA+B;YAC3C,SAAS,EAAE,+BAA+B;SAC3C;KACF;IACD,+BAA+B,EAAE;QAC/B;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,+BAA+B;YAC3C,SAAS,EAAE,+BAA+B;SAC3C;KACF;IACD,yBAAyB,EAAE;QACzB;YACE,UAAU,EAAE,WAAW;YACvB,UAAU,EAAE,oCAAoC;YAChD,SAAS,EAAE,yBAAyB;SACrC;KACF;IAED,yBAAyB;IACzB,EAAE;IACF,yEAAyE;IACzE,qEAAqE;IACrE,wEAAwE;IACxE,wEAAwE;IACxE,mEAAmE;IACnE,6DAA6D;IAC7D,wBAAwB,EAAE;QACxB;YACE,UAAU,EAAE,iBAAiB;YAC7B,UAAU,EACR,8DAA8D;YAChE,SAAS,EAAE,mBAAmB;SAC/B;QACD;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,oCAAoC;YAChD,SAAS,EAAE,8BAA8B;SAC1C;QACD;YACE,UAAU,EAAE,eAAe;YAC3B,UAAU,EACR,kEAAkE;YACpE,SAAS,EAAE,mBAAmB;SAC/B;KACF;IACD,4BAA4B,EAAE;QAC5B;YACE,UAAU,EAAE,iBAAiB;YAC7B,UAAU,EACR,kEAAkE;YACpE,SAAS,EAAE,mBAAmB;SAC/B;QACD;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,gCAAgC;YAC5C,SAAS,EAAE,sBAAsB;SAClC;KACF;IACD,oBAAoB,EAAE;QACpB;YACE,UAAU,EAAE,iBAAiB;YAC7B,UAAU,EAAE,0DAA0D;YACtE,SAAS,EAAE,mBAAmB;SAC/B;QACD;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,4BAA4B;YACxC,SAAS,EAAE,0BAA0B;SACtC;QACD;YACE,UAAU,EAAE,qBAAqB;YACjC,UAAU,EAAE,2BAA2B;YACvC,SAAS,EAAE,sBAAsB;SAClC;KACF;IACD,wBAAwB,EAAE;QACxB;YACE,UAAU,EAAE,iBAAiB;YAC7B,UAAU,EACR,8DAA8D;YAChE,SAAS,EAAE,mBAAmB;SAC/B;QACD;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,oDAAoD;YAChE,SAAS,EAAE,mBAAmB;SAC/B;KACF;IACD,wBAAwB,EAAE;QACxB;YACE,UAAU,EAAE,iBAAiB;YAC7B,UAAU,EACR,8DAA8D;YAChE,SAAS,EAAE,mBAAmB;SAC/B;QACD;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,oDAAoD;YAChE,SAAS,EAAE,8BAA8B;SAC1C;KACF;IACD,EAAE;IACF,0EAA0E;IAC1E,uEAAuE;IACvE,wEAAwE;IACxE,wEAAwE;IACxE,wEAAwE;IACxE,wCAAwC;IACxC,uBAAuB,EAAE;QACvB;YACE,UAAU,EAAE,iBAAiB;YAC7B,UAAU,EAAE,6DAA6D;YACzE,SAAS,EAAE,qBAAqB;SACjC;QACD;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,iCAAiC;YAC7C,SAAS,EAAE,gCAAgC;SAC5C;KACF;IACD,8BAA8B,EAAE;QAC9B;YACE,UAAU,EAAE,iBAAiB;YAC7B,UAAU,EACR,oEAAoE;YACtE,SAAS,EAAE,qBAAqB;SACjC;QACD;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,wDAAwD;YACpE,SAAS,EAAE,oBAAoB;SAChC;KACF;IAED,uBAAuB;IACvB,iBAAiB,EAAE;QACjB;YACE,UAAU,EAAE,gBAAgB;YAC5B,UAAU,EAAE,8CAA8C;YAC1D,SAAS,EAAE,kBAAkB;SAC9B;KACF;IACD,kBAAkB,EAAE;QAClB;YACE,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,gDAAgD;YAC5D,SAAS,EAAE,mBAAmB;SAC/B;KACF;IACD,mBAAmB,EAAE;QACnB;YACE,UAAU,EAAE,gBAAgB;YAC5B,UAAU,EAAE,sDAAsD;YAClE,SAAS,EAAE,mBAAmB;SAC/B;QACD;YACE,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,2CAA2C;YACvD,SAAS,EAAE,oBAAoB;SAChC;KACF;IACD,yBAAyB,EAAE;QACzB;YACE,UAAU,EAAE,gBAAgB;YAC5B,UAAU,EAAE,2CAA2C;YACvD,SAAS,EAAE,qBAAqB;SACjC;KACF;IACD,mBAAmB,EAAE;QACnB;YACE,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,mDAAmD;YAC/D,SAAS,EAAE,sBAAsB;SAClC;KACF;IACD,6BAA6B,EAAE;QAC7B;YACE,UAAU,EAAE,qBAAqB;YACjC,UAAU,EAAE,yCAAyC;YACrD,SAAS,EAAE,sBAAsB;SAClC;KACF;IACD,gCAAgC,EAAE;QAChC;YACE,UAAU,EAAE,qBAAqB;YACjC,UAAU,EAAE,sCAAsC;YAClD,SAAS,EAAE,sBAAsB;SAClC;KACF;IACD,kBAAkB,EAAE;QAClB;YACE,UAAU,EAAE,qBAAqB;YACjC,UAAU,EAAE,8BAA8B;YAC1C,SAAS,EAAE,sBAAsB;SAClC;KACF;IACD,mBAAmB,EAAE;QACnB;YACE,UAAU,EAAE,UAAU;YACtB,UAAU,EAAE,gDAAgD;YAC5D,SAAS,EAAE,mBAAmB;SAC/B;KACF;IACD,kBAAkB,EAAE;QAClB;YACE,UAAU,EAAE,eAAe;YAC3B,UAAU,EAAE,0CAA0C;YACtD,SAAS,EAAE,2BAA2B;SACvC;KACF;IACD,sBAAsB,EAAE;QACtB;YACE,UAAU,EAAE,gBAAgB;YAC5B,UAAU,EAAE,yCAAyC;YACrD,SAAS,EAAE,yBAAyB;SACrC;KACF;CACF,CAAC;AAEF,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,SAAiB;IAEjB,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC;AACvD,CAAC"}

package/dist/tools/releases.d.ts

@@ -1,5 +1,13 @@
 /**
- * Releases Tools — manage releases (albums, EPs, singles with release dates, labels, and UPCs)
+ * Releases Tools — manage releases (albums, EPs, singles with release
+ * dates, labels, distributors, UPCs, and artwork).
+ *
+ * ADR-174 Decision 3 reconciliation: label and distributor are
+ * FK-modelled via `label_organization_id` / `distributor_organization_id`
+ * to `organisations`. Agents resolve a name to an ID via
+ * `pica_labels_query` (ADR-174) or `pica_search_all` before calling
+ * create/update. Freetext `label` was removed; it never corresponded to a
+ * real column on `releases`.
  */
 import { PicaClient } from "@withpica/mcp-sdk";
 import { ToolDefinition, ToolExecutor } from "./index.js";
@@ -10,6 +18,11 @@ export declare class ReleasesTools {
         definition: ToolDefinition;
         executor: ToolExecutor;
     }>;
+    private attachTrack;
+    private listTracks;
+    private detachTrack;
+    private reorderTracks;
+    private attachRecordingWithWork;
     private listReleases;
     private getRelease;
     private createRelease;

package/dist/tools/releases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"releases.d.ts","sourceRoot":"","sources":["../../src/tools/releases.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAuG3D,YAAY;YAQZ,UAAU;YAKV,aAAa;YAMb,aAAa;CAK5B"}
+{"version":3,"file":"releases.d.ts","sourceRoot":"","sources":["../../src/tools/releases.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AA0EtE,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA2N3D,WAAW;YAUX,UAAU;YAKV,WAAW;YAYX,aAAa;YAQb,uBAAuB;YAcvB,YAAY;YAQZ,UAAU;YAKV,aAAa;YAMb,aAAa;CAK5B"}

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,213 @@ 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: {
-                                type: "string",
-                                description: "Release title",
-                            },
-                            release_date: {
+                            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 date (YYYY-MM-DD)",
+                                description: "Recording ID (optional — at least one of recording_id or work_id must be provided)",
                             },
-                            release_type: {
+                            work_id: {
                                 type: "string",
-                                description: "Release type (album, ep, single, compilation)",
+                                description: "Work ID (optional — omit for licensed-masters releases where no composition record exists)",
                             },
-                            upc: {
-                                type: "string",
-                                description: "Universal Product Code (UPC/EAN barcode)",
+                            track_number: {
+                                type: "number",
+                                description: "Position on disc (1-based)",
                             },
-                            catalog_number: {
-                                type: "string",
-                                description: "Label catalog number",
+                            disc_number: {
+                                type: "number",
+                                description: "Disc number (default 1)",
                             },
                         },
-                        required: ["title"],
+                        required: ["release_id", "track_number"],
                     },
                 },
-                executor: this.createRelease.bind(this),
+                executor: this.attachTrack.bind(this),
             },
             {
                 definition: {
-                    name: "pica_releases_update",
-                    description: "Update release details — title, date, release type, label, UPC, or catalog number.",
+                    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: {
-                            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" },
+                        },
+                        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)",
                             },
-                            release_type: {
-                                type: "string",
-                                description: "Updated release type (album, ep, single, compilation)",
+                            disc_number: {
+                                type: "number",
+                                description: "Disc number (default 1)",
                             },
-                            upc: {
-                                type: "string",
-                                description: "Updated UPC",
+                            confirm: {
+                                type: "boolean",
+                                description: "Set to true to execute the detach after reviewing the preview",
                             },
-                            catalog_number: {
-                                type: "string",
-                                description: "Updated catalog number",
+                        },
+                        required: ["release_id", "track_number"],
+                    },
+                },
+                executor: this.detachTrack.bind(this),
+            },
+            {
+                definition: {
+                    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: {
+                            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: ["id"],
+                        required: ["release_id", "new_order"],
                     },
                 },
-                executor: this.updateRelease.bind(this),
+                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),
             },
         ];
     }
+    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,