@withpica/mcp-server 2.40.0 → 2.44.0

package/dist/resources/required-schemas.generated.d.ts

@@ -1,4 +1,192 @@
 export declare const REQUIRED_SCHEMAS: {
+    readonly "agreement-required": {
+        readonly workflow: "agreement-required";
+        readonly summary: "Required fields to create an agreement, then attach works and (optionally) render from a template.";
+        readonly primary_tool: "pica_agreements_create";
+        readonly primary_required: readonly ["title", "agreement_type", "other_party_name"];
+        readonly primary_recommended: readonly ["id", "other_party_type", "description", "notes", "tags", "agreement_category", "status", "signing_date", "start_date", "end_date", "expires_at", "renewal_date", "termination_date", "counterparty_org_id", "counterparty_email", "advance_amount", "advance_currency", "is_recoupable", "financial_terms", "agreement_terms", "termination_notice_period_days", "include_future_works"];
+        readonly enums: {
+            readonly agreement_type: readonly ["admin_only", "artist_contract", "co_publishing", "distribution", "library_music", "master_recording", "other", "production", "publishing_admin", "report", "sub_publishing", "termination"];
+            readonly other_party_type: readonly ["artist", "individual", "label", "music_library", "other", "production_company", "publisher"];
+            readonly status: readonly ["active", "cancelled", "completed", "draft", "expired", "fully_executed", "partially_signed", "pending_signature", "terminated", "unknown"];
+        };
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_agreements_update";
+            readonly when: "After creation — to amend any inline field. Status changes trigger notifications; counterparty_org_id changes require the linked-org check at the route layer.";
+            readonly required: readonly ["id"];
+        }, {
+            readonly tool: "pica_agreements_link_work";
+            readonly when: "Attach a work to the agreement. Optionally set a royalty split percentage per work.";
+            readonly required: readonly ["agreement_id", "work_id"];
+        }, {
+            readonly tool: "pica_agreement_templates_render";
+            readonly when: "Template-driven flow — fill an agreement template with catalog data (work_id + people_ids) before creating the agreement row.";
+            readonly required: readonly ["id"];
+        }];
+        readonly example: {
+            readonly title: "Songwriter Admin Deal — Midnight Rivers";
+            readonly agreement_type: "publishing_admin";
+            readonly other_party_name: "Indigo Music Publishing Ltd.";
+        };
+    };
+    readonly "audio-upload-required": {
+        readonly workflow: "audio-upload-required";
+        readonly summary: "Three-step chain to add an audio master / stem / version to the catalog: presign → PUT → finalize, then optional async analyze + poll.";
+        readonly primary_tool: "pica_audio_presigned_upload";
+        readonly primary_required: readonly ["filename", "content_type", "file_size"];
+        readonly primary_recommended: readonly ["work_id", "title", "file_type"];
+        readonly enums: {
+            readonly file_type: readonly ["demo", "instrumental", "master", "stem", "version"];
+            readonly classification: readonly ["composition", "demo", "drum_pack", "loop", "other", "released_song", "sample", "stem", "unreleased_song"];
+        };
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_audio_complete_upload";
+            readonly when: "Step 2 — after the uploader PUTs the file to the signed URL returned by step 1. Finalizes the upload, writes the audio_files row, and (optionally) links or auto-creates a recording for master files.";
+            readonly required: readonly ["upload_id", "key", "bucket", "filename", "content_type", "file_size"];
+        }, {
+            readonly tool: "pica_audio_analyze";
+            readonly when: "Step 3 (optional, async). Triggers BPM / key / mood feature extraction (Librosa) and lyrics transcription (Whisper). Each side bills 1 credit. Does not auto-run on complete_upload — explicit call required.";
+            readonly required: readonly ["id"];
+        }, {
+            readonly tool: "pica_audio_inspect";
+            readonly when: "Step 4 (poll). Call with sections: ['analysis', 'status'] until the analysis job reports complete. Lyrics transcripts land on the analysis row, not works.lyrics — copy is a separate step.";
+            readonly required: readonly ["id"];
+        }];
+        readonly example: {
+            readonly filename: "midnight-rivers-master.wav";
+            readonly content_type: "audio/wav";
+            readonly file_size: 48234567;
+            readonly work_id: "<optional uuid — auto-creates a recording for master files>";
+        };
+    };
+    readonly "claim-required": {
+        readonly workflow: "claim-required";
+        readonly summary: "Resolve pending discoveries (credits, custody, artist links) into your catalog. Each discovery type has a typed claim verb; the generic discoveries_review surface accepts/rejects without specialised handling.";
+        readonly primary_tool: "pica_discoveries_query";
+        readonly primary_required: readonly [];
+        readonly primary_recommended: readonly ["status", "limit"];
+        readonly enums: {
+            readonly status: readonly ["expired", "pending", "resolved", "revoked"];
+            readonly match_basis: readonly ["email", "ipi", "ipn", "isni", "musicbrainz"];
+            readonly custody_type: readonly ["composition", "master"];
+        };
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_discoveries_review";
+            readonly when: "Generic accept/reject for any discovery row — accepted discoveries update your catalog automatically. Use for non-credit / non-custody / non-artist discoveries, or when the typed claim tools refuse on rate-limit / state preconditions.";
+            readonly required: readonly ["discovery_id", "status"];
+        }, {
+            readonly tool: "pica_claim_credit";
+            readonly when: "Drain a discovered_credits row and insert a work_credits row in your catalog. Rate-limited to 20 claims/hour. Re-claiming an already-resolved row returns DISCOVERY_ALREADY_RESOLVED (409).";
+            readonly required: readonly ["id"];
+        }, {
+            readonly tool: "pica_claim_custody";
+            readonly when: "Drain a discovered_custody row into a pending custody_claims row with +72h silent-consent auto-approve. The current custodian keeps the catalog row until the window elapses.";
+            readonly required: readonly ["id"];
+        }, {
+            readonly tool: "pica_claim_artist";
+            readonly when: "Drain a discovered_artists row instantly (identity evidence already validated at discovery time). Requires your identity to already be linked via pica_update_my_identity. Refuses (409) when an open artist_claims review row exists.";
+            readonly required: readonly ["id"];
+        }];
+        readonly example: {
+            readonly status: "pending";
+            readonly limit: 50;
+        };
+    };
+    readonly "enrichment-resolve-required": {
+        readonly workflow: "enrichment-resolve-required";
+        readonly summary: "Fan out enrichment across every eligible source for an entity (work / recording / person), then review fuzzy Tier B matches in the proposals queue. Tier A identifier matches apply directly; Tier B fuzzy matches queue as proposals.";
+        readonly primary_tool: "pica_resolve_work";
+        readonly primary_required: readonly ["work_id"];
+        readonly primary_recommended: readonly ["sources", "include_fuzzy"];
+        readonly enums: {
+            readonly status: readonly ["applied", "expired", "pending", "rejected"];
+            readonly entity_type: readonly ["person", "recording", "work"];
+            readonly proposal_action: readonly ["create", "update"];
+        };
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_resolve_recording";
+            readonly when: "Recording-side variant. Fans out across Spotify, YouTube, MusicBrainz, Discogs. Triggered by spotify_track_uri / youtube_video_id on the recording.";
+            readonly required: readonly ["recording_id"];
+        }, {
+            readonly tool: "pica_resolve_person";
+            readonly when: "Person-side variant. Fans out across ISNI and MusicBrainz (Wikidata downstream). Triggered by isni / musicbrainz_id on the person.";
+            readonly required: readonly ["person_id"];
+        }, {
+            readonly tool: "pica_enrichment_proposals_list";
+            readonly when: "After resolve — list pending Tier B fuzzy matches awaiting review. Only pending status is returned.";
+            readonly required: readonly [];
+        }, {
+            readonly tool: "pica_enrichment_proposal_apply";
+            readonly when: "Commit a reviewed proposal. Drift detection runs first on update proposals — pass force=true only after the user has reviewed any conflicts from a prior drift_detected response.";
+            readonly required: readonly ["proposal_id"];
+        }, {
+            readonly tool: "pica_enrichment_proposal_reject";
+            readonly when: "Dismiss a proposal. Content-hash suppression permanently blocks re-proposal of the same exact content; cascade only re-proposes if the source data genuinely changes.";
+            readonly required: readonly ["proposal_id"];
+        }];
+        readonly example: {
+            readonly work_id: "<uuid>";
+            readonly sources: readonly ["mlc", "spotify"];
+            readonly include_fuzzy: true;
+        };
+    };
+    readonly "export-required": {
+        readonly workflow: "export-required";
+        readonly summary: "Generate exports of the works catalog in formats matching the destination — CSV/JSON for general use, CWR for PRO registration, industry-ready packages for publishers/labels/sync, CAR for diligence and finance, AI-consent for declaration matrices.";
+        readonly primary_tool: "pica_export_catalog_csv";
+        readonly primary_required: readonly [];
+        readonly primary_recommended: readonly ["format"];
+        readonly enums: {};
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_export_song_registration";
+            readonly when: "CWR-compatible song-registration export, formatted for PRO/CMO submission. Billing-gated.";
+            readonly required: readonly [];
+        }, {
+            readonly tool: "pica_export_industry_ready";
+            readonly when: "Industry-ready metadata package — formatted for distribution to publishers, labels, and sync agents. Billing-gated.";
+            readonly required: readonly [];
+        }, {
+            readonly tool: "pica_export_catalog_asset_report";
+            readonly when: "Catalog Asset Report (CAR) — unified ZIP bundle with cover PDF, evidence folders, integrity manifest. Property-lending framing for finance / insurance / diligence. Nested `sections` object accepts boolean flags: valuation, assets, agreements, intelligence, audio. Ownership is always included. Billing-gated.";
+            readonly required: readonly [];
+        }, {
+            readonly tool: "pica_export_ai_consent";
+            readonly when: "AI-usage consent declaration matrix — per-work + per-contributor declarations of human-made / AI-assisted / AI-generated.";
+            readonly required: readonly [];
+        }];
+        readonly example: {
+            readonly format: "csv";
+        };
+    };
+    readonly "multimedia-required": {
+        readonly workflow: "multimedia-required";
+        readonly summary: "Required fields to register a multimedia item (photo / video / audio / external streaming link), and the patterns for importing or attaching to a work.";
+        readonly primary_tool: "pica_multimedia_create";
+        readonly primary_required: readonly ["title", "content_type"];
+        readonly primary_recommended: readonly ["url", "classification", "caption", "description", "tags", "credits", "duration_seconds", "collection_id", "display_order", "is_featured", "is_published", "venue", "event_name", "performance_date", "setlist_position", "sync_side", "spotify_url", "spotify_track_uri", "spotify_track_id", "youtube_url", "youtube_video_id", "soundcloud_url", "thumbnail_url"];
+        readonly enums: {
+            readonly content_type: readonly ["live_performance", "soundcloud_track", "spotify_track", "uploaded_audio", "uploaded_photo", "uploaded_video", "youtube_video"];
+            readonly classification: readonly ["album_artwork", "artist_showcase", "behind_the_scenes", "general", "live_performance", "music_video", "promo_material", "studio_session", "sync_placement"];
+        };
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_multimedia_import_url";
+            readonly when: "Import an external image or video URL — downloads the file into PICA storage rather than referencing it externally. Use for Spotify artwork, web images, etc.";
+            readonly required: readonly ["url"];
+        }, {
+            readonly tool: "pica_multimedia_link_youtube";
+            readonly when: "YouTube-specific variant — pulls thumbnail, title, and view count automatically. Use this instead of pica_multimedia_create for YouTube videos.";
+            readonly required: readonly ["youtube_video_id", "title"];
+        }, {
+            readonly tool: "pica_multimedia_link_work";
+            readonly when: "Attach an existing multimedia item to a work with a typed relationship (music_video_for, sync_placement, album_artwork, etc.).";
+            readonly required: readonly ["multimedia_id", "work_id", "relationship_type"];
+        }];
+        readonly example: {
+            readonly title: "Midnight Rivers — Official Music Video";
+            readonly content_type: "youtube_video";
+            readonly url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
+        };
+    };
     readonly "person-required": {
         readonly workflow: "person-required";
         readonly summary: "Required fields to register a person (writer, performer, producer, publisher). Identifiers (IPI / ISNI / PRO / MusicBrainz / etc.) are inline-settable at create time.";
@@ -31,15 +219,9 @@ export declare const REQUIRED_SCHEMAS: {
         readonly companion_calls: readonly [];
         readonly example: {
             readonly recording_id: "<uuid>";
-            readonly credits: readonly [{
-                readonly credited_name: "The Riverbed Trio";
-                readonly role: "MainArtist";
-                readonly display_order: 0;
-            }, {
-                readonly credited_name: "Sam Producer";
-                readonly role: "Producer";
-                readonly display_order: 1;
-            }];
+            readonly credited_name: "The Riverbed Trio";
+            readonly role: "MainArtist";
+            readonly person_id: "<uuid>";
         };
     };
     readonly "recording-required": {
@@ -53,9 +235,8 @@ export declare const REQUIRED_SCHEMAS: {
         };
         readonly companion_calls: readonly [{
             readonly tool: "pica_recording_credits_update";
-            readonly when: "Batch — attach MainArtist / Producer / Engineer credits to the recording.";
-            readonly required: readonly ["recording_id", "credits"];
-            readonly per_row_required: readonly ["credited_name", "role", "display_order"];
+            readonly when: "Per credit — attach a single MainArtist / Producer / Engineer credit. Call once per person; does NOT take a credits[] batch (asymmetric with pica_credits_update for works).";
+            readonly required: readonly ["recording_id", "credited_name", "role"];
         }, {
             readonly tool: "pica_recordings_update";
             readonly when: "After creation — to amend recording_title, artist_name, version_type, isrc, duration_ms, or any other inline field. Same payload shape as create plus `id`.";

package/dist/resources/required-schemas.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"required-schemas.generated.d.ts","sourceRoot":"","sources":["../../src/resources/required-schemas.generated.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgVnB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,gBAAgB,CAAC"}
+{"version":3,"file":"required-schemas.generated.d.ts","sourceRoot":"","sources":["../../src/resources/required-schemas.generated.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8uBnB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,gBAAgB,CAAC"}