@withpica/mcp-server 2.5.2 → 2.5.4

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

@@ -1 +1 @@
-{"version":3,"file":"recordings.d.ts","sourceRoot":"","sources":["../../src/tools/recordings.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAOtE,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IAqOzE;;OAEG;YACW,cAAc;IAU5B;;OAEG;YACW,YAAY;IAY1B;;OAEG;YACW,eAAe;IAQ7B;;OAEG;YACW,eAAe;IAQ7B;;OAEG;YACW,eAAe;IAO7B;;OAEG;YACW,mBAAmB;CASlC"}
+{"version":3,"file":"recordings.d.ts","sourceRoot":"","sources":["../../src/tools/recordings.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAOtE,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IAyOzE;;OAEG;YACW,eAAe;IAkC7B;;OAEG;YACW,gBAAgB;IA+E9B;;OAEG;YACW,eAAe;IAU7B;;OAEG;YACW,eAAe;IAW7B;;OAEG;YACW,eAAe;CAM9B"}

package/dist/tools/recordings.js

@@ -1,5 +1,5 @@
 // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
-import { formatAsText, formatSuccess, formatStructuredList, } from "../utils/formatting.js";
+import { formatSuccess, formatStructuredList, } from "../utils/formatting.js";
 export class RecordingsTools {
     pica;
     constructor(pica) {
@@ -12,24 +12,34 @@ export class RecordingsTools {
         return [
             {
                 definition: {
-                    name: "pica_recordings_list",
-                    description: "List recordings from PICA catalog",
+                    name: "pica_recordings_query",
+                    description: "Find recordings — list all, search by query, or filter by work. " +
+                        "→ then: pica_recordings_inspect (details for a specific recording)",
                     inputSchema: {
                         type: "object",
                         properties: {
+                            query: {
+                                type: "string",
+                                description: "Search by title, ISRC, or artist name",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Filter recordings by work ID (replaces pica_recordings_by_work)",
+                            },
                             limit: {
                                 type: "number",
-                                description: "Maximum number of results to return (default: 50)",
+                                description: "Max results (default: 50)",
                             },
                         },
                     },
                 },
-                executor: this.listRecordings.bind(this),
+                executor: this.queryRecordings.bind(this),
             },
             {
                 definition: {
-                    name: "pica_recordings_get",
-                    description: "Get details of a specific recording by ID",
+                    name: "pica_recordings_inspect",
+                    description: "Get details for a specific recording. Omit sections for everything. " +
+                        "→ then: pica_audio_query (audio files), pica_credits_update (fix credits)",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -37,21 +47,29 @@ export class RecordingsTools {
                                 type: "string",
                                 description: "Recording ID",
                             },
+                            sections: {
+                                type: "array",
+                                items: {
+                                    type: "string",
+                                    enum: ["basic", "credits", "audio"],
+                                },
+                                description: 'Which data sections to include. Omit for all sections. Use ["basic"] for lightweight lookup.',
+                            },
                         },
                         required: ["id"],
                     },
                 },
-                executor: this.getRecording.bind(this),
+                executor: this.inspectRecording.bind(this),
             },
             {
                 definition: {
                     name: "pica_recordings_create",
-                    description: "Create a new recording. IMPORTANT: Always call pica_recordings_by_work first to check for existing recordings on this work — duplicate recordings cause ISRC conflicts. " +
+                    description: "Create a new recording. IMPORTANT: Always call pica_recordings_query with work_id first to check for existing recordings on this work — duplicate recordings cause ISRC conflicts. " +
                         "Any field from the Recording schema can be passed — " +
                         "the most commonly used fields are listed below. Additional fields " +
                         "(e.g. mlc_recording_id, mlc_song_code, global_recording_id, global_release_id) " +
                         "are also accepted. " +
-                        "→ before: pica_recordings_by_work (check duplicates) → then: pica_audio_presigned_upload (upload audio), pica_audio_analyze (extract features)",
+                        "→ before: pica_recordings_query (check duplicates) → then: pica_audio_presigned_upload (upload audio), pica_audio_analyze (extract features)",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -123,7 +141,7 @@ export class RecordingsTools {
                     name: "pica_recordings_update",
                     description: "Update an existing recording. Any field from the Recording schema can be passed — " +
                         "the most commonly used fields are listed below. Additional fields are also accepted. " +
-                        "→ then: pica_recordings_get (verify changes persisted)",
+                        "→ then: pica_recordings_inspect (verify changes persisted)",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -207,30 +225,33 @@ export class RecordingsTools {
                 },
                 executor: this.deleteRecording.bind(this),
             },
-            {
-                definition: {
-                    name: "pica_recordings_by_work",
-                    description: "Get all recordings of a specific work",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            work_id: {
-                                type: "string",
-                                description: "Work ID",
-                            },
-                        },
-                        required: ["work_id"],
-                    },
-                },
-                executor: this.getRecordingsByWork.bind(this),
-            },
         ];
     }
     /**
-     * List recordings
+     * Query recordings — list all, search by text, or filter by work
      */
-    async listRecordings(args) {
+    async queryRecordings(args) {
         const limit = args.limit || 50;
+        const workId = args.work_id;
+        const query = args.query;
+        // Filter by work_id — delegate to getByWork
+        if (workId) {
+            const recordings = await this.pica.recordings.getByWork(workId);
+            return formatStructuredList(recordings, "recording", {
+                work_id: workId,
+                total: recordings.length,
+            });
+        }
+        // Search by text query — delegate to search method (client-side filtering)
+        if (query) {
+            const result = await this.pica.recordings.search({ query, limit });
+            return formatStructuredList(result.data, "recording", {
+                query,
+                total: result.total,
+                hasMore: result.hasMore,
+            });
+        }
+        // Default: list all
         const recordings = await this.pica.recordings.list({ limit });
         return formatStructuredList(recordings, "recording", {
             total: recordings.length,
@@ -238,16 +259,78 @@ export class RecordingsTools {
         });
     }
     /**
-     * Get recording by ID
+     * Inspect a recording — get details with optional section filtering
      */
-    async getRecording(args) {
-        const recording = await this.pica.recordings.get(args.id);
-        // Enrich with ISRC prefix intelligence if ISRC is present
-        let prefix_intel = null;
-        if (recording.isrc) {
-            prefix_intel = await this.pica.recordings.prefixLookup(recording.isrc);
+    async inspectRecording(args) {
+        const id = args.id;
+        const sections = args.sections;
+        const allSections = !sections || sections.length === 0;
+        const result = {};
+        // Basic section: recording details + ISRC prefix intel
+        if (allSections || sections?.includes("basic")) {
+            try {
+                const recording = await this.pica.recordings.get(id);
+                result.recording = recording;
+                // Enrich with ISRC prefix intelligence if ISRC is present
+                if (recording.isrc) {
+                    const prefixIntel = await this.pica.recordings.prefixLookup(recording.isrc);
+                    if (prefixIntel) {
+                        result.prefix_intel = prefixIntel;
+                    }
+                }
+            }
+            catch (error) {
+                result.recording_error =
+                    error instanceof Error ? error.message : "Failed to fetch recording";
+            }
+        }
+        // Credits section: work credits (via recording's parent work)
+        if (allSections || sections?.includes("credits")) {
+            try {
+                // We need the recording to get its work_id
+                const recording = result.recording ||
+                    (await this.pica.recordings.get(id));
+                const workId = recording.work_id;
+                if (workId) {
+                    const credits = await this.pica.credits.listForWork(workId);
+                    result.credits = credits;
+                }
+                else {
+                    result.credits = [];
+                    result.credits_note = "No parent work linked — no credits available";
+                }
+            }
+            catch (error) {
+                result.credits_error =
+                    error instanceof Error ? error.message : "Failed to fetch credits";
+            }
         }
-        return formatAsText({ ...recording, prefix_intel });
+        // Audio section: audio files linked to the parent work
+        if (allSections || sections?.includes("audio")) {
+            try {
+                const recording = result.recording ||
+                    (await this.pica.recordings.get(id));
+                const workId = recording.work_id;
+                if (workId) {
+                    const audioFiles = await this.pica.audioFiles.list({
+                        work_id: workId,
+                    });
+                    result.audio_files = audioFiles;
+                }
+                else {
+                    result.audio_files = [];
+                    result.audio_note =
+                        "No parent work linked — no audio files available";
+                }
+            }
+            catch (error) {
+                result.audio_error =
+                    error instanceof Error
+                        ? error.message
+                        : "Failed to fetch audio files";
+            }
+        }
+        return formatSuccess("Recording details", result);
     }
     /**
      * Create recording
@@ -273,15 +356,5 @@ export class RecordingsTools {
         await this.pica.recordings.delete(args.id);
         return formatSuccess(`Recording ${args.id} deleted successfully`);
     }
-    /**
-     * Get recordings by work
-     */
-    async getRecordingsByWork(args) {
-        const recordings = await this.pica.recordings.getByWork(args.work_id);
-        return formatStructuredList(recordings, "recording", {
-            work_id: args.work_id,
-            total: recordings.length,
-        });
-    }
 }
 //# sourceMappingURL=recordings.js.map

package/dist/tools/recordings.js.map

@@ -1 +1 @@
-{"version":3,"file":"recordings.js","sourceRoot":"","sources":["../../src/tools/recordings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"recordings.js","sourceRoot":"","sources":["../../src/tools/recordings.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,14 @@
+/**
+ * Recovery Hints Registry — ADR-149 Phase 2
+ *
+ * Per-tool failure-mode declarations. When a tool fails, the hint tells
+ * the AI what to try next — forming a recovery graph.
+ */
+export interface RecoveryHint {
+    error_code: string;
+    suggestion: string;
+    next_tool?: string;
+}
+export declare const RECOVERY_HINTS: Record<string, RecoveryHint[]>;
+export declare function getRecoveryHint(toolName: string, errorCode: string): RecoveryHint | undefined;
+//# sourceMappingURL=recovery-hints.d.ts.map

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

@@ -0,0 +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"}

package/dist/tools/recovery-hints.js

@@ -0,0 +1,277 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+export const RECOVERY_HINTS = {
+    // ── destructive tools ──
+    pica_works_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "search for the work by title",
+            next_tool: "pica_works_query",
+        },
+        {
+            error_code: "HAS_DEPENDENCIES",
+            suggestion: "check what's linked to this work first",
+            next_tool: "pica_works_inspect",
+        },
+    ],
+    pica_works_bulk_delete: [
+        {
+            error_code: "PARTIAL_NOT_FOUND",
+            suggestion: "some IDs not found — list your works to verify",
+            next_tool: "pica_works_query",
+        },
+    ],
+    pica_people_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "search for the person by name",
+            next_tool: "pica_people_query",
+        },
+        {
+            error_code: "PERSON_HAS_CREDITS",
+            suggestion: "check their credits before removing",
+            next_tool: "pica_people_inspect",
+        },
+    ],
+    pica_recordings_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list recordings for this work",
+            next_tool: "pica_recordings_query",
+        },
+    ],
+    pica_agreements_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your agreements to find the right one",
+            next_tool: "pica_agreements_query",
+        },
+        {
+            error_code: "HAS_LINKED_WORKS",
+            suggestion: "check what works are linked",
+            next_tool: "pica_agreements_inspect",
+        },
+    ],
+    pica_projects_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your projects",
+            next_tool: "pica_projects_list",
+        },
+    ],
+    pica_merge_duplicates: [
+        {
+            error_code: "ENTITY_NOT_FOUND",
+            suggestion: "check both entities exist",
+            next_tool: "pica_find_duplicates",
+        },
+        {
+            error_code: "MERGE_CONFLICT",
+            suggestion: "compare the entities first",
+            next_tool: "pica_enrichment_compare",
+        },
+    ],
+    pica_team_remove: [
+        {
+            error_code: "CANNOT_REMOVE_OWNER",
+            suggestion: "check team roles",
+            next_tool: "pica_team_list",
+        },
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list team members",
+            next_tool: "pica_team_list",
+        },
+    ],
+    pica_notes_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your notes",
+            next_tool: "pica_notes_list",
+        },
+    ],
+    pica_memory_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your memories",
+            next_tool: "pica_memory_list",
+        },
+    ],
+    pica_physical_assets_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your assets",
+            next_tool: "pica_physical_assets_query",
+        },
+    ],
+    pica_agreement_templates_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your agreement templates",
+            next_tool: "pica_agreement_templates_list",
+        },
+    ],
+    pica_producer_agreements_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your producer agreements",
+            next_tool: "pica_producer_agreements_list",
+        },
+    ],
+    pica_work_for_hire_delete: [
+        {
+            error_code: "NOT_FOUND",
+            suggestion: "list your work-for-hire agreements",
+            next_tool: "pica_work_for_hire_list",
+        },
+    ],
+    // ── enrichment tools ──
+    pica_enrich_work_spotify: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no Spotify match — try MusicBrainz",
+            next_tool: "pica_enrich_work_musicbrainz",
+        },
+        {
+            error_code: "MISSING_INPUT",
+            suggestion: "provide a Spotify URL or ensure the work has a spotify_track_uri",
+            next_tool: "pica_works_update",
+        },
+    ],
+    pica_enrich_work_musicbrainz: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no MusicBrainz match — try MLC",
+            next_tool: "pica_enrich_work_mlc",
+        },
+    ],
+    pica_enrich_work_mlc: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no MLC match — try Discogs",
+            next_tool: "pica_enrich_work_discogs",
+        },
+        {
+            error_code: "CREDIT_INSUFFICIENT",
+            suggestion: "check your credit balance",
+            next_tool: "pica_credits_balance",
+        },
+    ],
+    pica_enrich_work_discogs: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no Discogs match — try adding identifiers manually",
+            next_tool: "pica_works_update",
+        },
+    ],
+    pica_enrich_work_youtube: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no YouTube data — ensure a YouTube video is linked",
+            next_tool: "pica_multimedia_link_youtube",
+        },
+    ],
+    pica_people_enrich_isni: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no ISNI match — try MusicBrainz",
+            next_tool: "pica_people_enrich_musicbrainz",
+        },
+    ],
+    pica_people_enrich_musicbrainz: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no MusicBrainz match — try adding identifiers manually",
+            next_tool: "pica_people_update",
+        },
+    ],
+    // ── mutating tools ──
+    pica_works_create: [
+        {
+            error_code: "DUPLICATE_WORK",
+            suggestion: "a similar work already exists — search first",
+            next_tool: "pica_works_query",
+        },
+    ],
+    pica_people_create: [
+        {
+            error_code: "DUPLICATE_PERSON",
+            suggestion: "a similar person already exists — search first",
+            next_tool: "pica_people_query",
+        },
+    ],
+    pica_credits_update: [
+        {
+            error_code: "SPLITS_NOT_100",
+            suggestion: "credit splits must total 100% — check current splits",
+            next_tool: "pica_credits_list",
+        },
+        {
+            error_code: "PERSON_NOT_FOUND",
+            suggestion: "person not in catalog — create them first",
+            next_tool: "pica_people_create",
+        },
+    ],
+    pica_split_sheet_generate: [
+        {
+            error_code: "SPLITS_NOT_100",
+            suggestion: "fix credits before generating split sheet",
+            next_tool: "pica_credits_update",
+        },
+    ],
+    pica_import_execute: [
+        {
+            error_code: "VALIDATION_ERROR",
+            suggestion: "validate the import first to see row-level issues",
+            next_tool: "pica_import_validate",
+        },
+    ],
+    pica_export_song_registration: [
+        {
+            error_code: "CREDIT_INSUFFICIENT",
+            suggestion: "song registration export costs 1 credit",
+            next_tool: "pica_credits_balance",
+        },
+    ],
+    pica_export_catalog_asset_report: [
+        {
+            error_code: "CREDIT_INSUFFICIENT",
+            suggestion: "catalog asset report costs 5 credits",
+            next_tool: "pica_credits_balance",
+        },
+    ],
+    pica_audio_analyze: [
+        {
+            error_code: "CREDIT_INSUFFICIENT",
+            suggestion: "audio analysis costs credits",
+            next_tool: "pica_credits_balance",
+        },
+    ],
+    pica_audio_identify: [
+        {
+            error_code: "NO_MATCH",
+            suggestion: "no fingerprint match — enter metadata manually",
+            next_tool: "pica_works_update",
+        },
+    ],
+    pica_notify_person: [
+        {
+            error_code: "NOT_PICA_USER",
+            suggestion: "person isn't on PICA — invite them first",
+            next_tool: "pica_collaborators_invite",
+        },
+    ],
+    pica_recordings_create: [
+        {
+            error_code: "DUPLICATE_ISRC",
+            suggestion: "recording with this ISRC already exists",
+            next_tool: "pica_recordings_by_work",
+        },
+    ],
+};
+export function getRecoveryHint(toolName, errorCode) {
+    const hints = RECOVERY_HINTS[toolName];
+    if (!hints)
+        return undefined;
+    return hints.find((h) => h.error_code === errorCode);
+}
+//# sourceMappingURL=recovery-hints.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-hints.js","sourceRoot":"","sources":["../../src/tools/recovery-hints.ts"],"names":[],"mappings":"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"}

package/dist/tools/royalties.js

@@ -218,7 +218,7 @@ export class RoyaltiesTools {
         if (prsGaps.length > 0) {
             hints.push({
                 gap: "prs_missing",
-                suggestion: `Register ${prsGaps.length} work(s) with PRS (pica_registration_coverage)`,
+                suggestion: `Register ${prsGaps.length} work(s) with PRS (pica_works_inspect with sections: ["registration"])`,
                 count: prsGaps.length,
                 severity: "critical",
             });

package/dist/tools/royalties.js.map

@@ -1 +1 @@
-{"version":3,"file":"royalties.js","sourceRoot":"","sources":["../../src/tools/royalties.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"royalties.js","sourceRoot":"","sources":["../../src/tools/royalties.ts"],"names":[],"mappings":"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"}

package/dist/tools/search.js

@@ -12,7 +12,7 @@ export class SearchTools {
                     name: "pica_search_all",
                     description: "Fuzzy search across the entire catalog: works, people, recordings, physical assets, audio files, studio sessions, agreements, multimedia, and releases. " +
                         "Supports free text, ISRC, ISWC, and IPI lookups. Returns ranked results with the top match expanded to full chain detail. " +
-                        "→ then: pica_works_get_full (work details), pica_people_get_full (person details), pica_recordings_get (recording details)",
+                        "→ then: pica_works_inspect (work details), pica_people_inspect (person details), pica_recordings_inspect (recording details)",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -52,7 +52,7 @@ export class SearchTools {
                         "Returns the canonical global entity + all connected works, recordings, creators, and publishers across the graph. " +
                         "Also shows which entities exist in your catalog. " +
                         "Use this to answer: 'show me everything connected to this IPI/ISRC/ISWC' or 'what else has this person written?'\n\n" +
-                        "→ then: pica_works_get_full (deep-dive a work), pica_enrich_work (enrich a discovered work)",
+                        "→ then: pica_works_inspect (deep-dive a work), pica_enrich_work_spotify (enrich a discovered work)",
                     inputSchema: {
                         type: "object",
                         properties: {