@withpica/mcp-server 2.43.0 → 2.45.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`.";
@@ -69,9 +250,90 @@ export declare const REQUIRED_SCHEMAS: {
             readonly duration_ms: 213000;
         };
     };
+    readonly "recording-splits-required": {
+        readonly workflow: "recording-splits-required";
+        readonly summary: "Required fields per row when assigning master-rights ownership on a recording. Distinct from publishing splits on works (those flow through pica_credits_update + pica_split_sheet_*). Recording splits drive master royalty payouts and downstream credit gating; pica_recording_splits_create runs an ADR-200 Class D form-confirmation gate when the client supports `elicitation/url`. Use `dry_run: true` for a no-op preview before committing.";
+        readonly primary_tool: "pica_recording_splits_create";
+        readonly primary_required: readonly ["recording_id", "split_type", "percentage"];
+        readonly primary_recommended: readonly ["person_id", "role", "territory", "start_date", "end_date", "notes", "dry_run"];
+        readonly enums: {
+            readonly split_type: readonly ["master", "mechanical", "performance", "sync"];
+            readonly role: readonly ["engineer", "label", "masterer", "mixer", "other", "owner", "performer", "producer"];
+        };
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_recording_splits_verify";
+            readonly when: "After create — explicitly mark a split as confirmed/agreed by the relevant parties. Sets verified=true + verified_at + verified_by on the row.";
+            readonly required: readonly ["recording_id", "split_id"];
+        }, {
+            readonly tool: "pica_recording_splits_list";
+            readonly when: "List all splits on a recording — verify totals and per-row verification state.";
+            readonly required: readonly ["recording_id"];
+        }];
+        readonly example: {
+            readonly recording_id: "<uuid>";
+            readonly split_type: "master";
+            readonly percentage: 50;
+            readonly role: "owner";
+            readonly person_id: "<optional uuid>";
+            readonly territory: "worldwide";
+        };
+    };
+    readonly "session-required": {
+        readonly workflow: "session-required";
+        readonly summary: "Required fields to log a studio session — title + start_time + end_time (ISO 8601 datetimes). Optional `session_type_id` is a UUID FK to the org's session_types lookup table; resolve via pica_sessions_types. The `status` column accepts scheduled / in_progress / completed / cancelled per the inputSchema, but the values are NOT enforced by a DB CHECK constraint — verify against the live tool's inputSchema if values matter to the caller.";
+        readonly primary_tool: "pica_sessions_create";
+        readonly primary_required: readonly ["title", "start_time", "end_time"];
+        readonly primary_recommended: readonly ["description", "session_type_id", "timezone", "is_all_day", "location", "location_url", "work_id", "recording_id", "status", "notes", "metadata", "participants"];
+        readonly enums: {};
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_sessions_types";
+            readonly when: "Pre-flight to discover valid session_type_id values for this org. The lookup table is org-scoped and seeded with recording / mixing / mastering / writing / production / rehearsal entries on org bootstrap.";
+            readonly required: readonly [];
+        }, {
+            readonly tool: "pica_sessions_get";
+            readonly when: "After creation — verify the session row + participants persisted as expected. Reads back the full session record including any participants attached at create time.";
+            readonly required: readonly ["id"];
+        }, {
+            readonly tool: "pica_sessions_list";
+            readonly when: "Discovery / browse — list recent or upcoming sessions for the workspace.";
+            readonly required: readonly [];
+        }];
+        readonly example: {
+            readonly title: "Vocal recording — Midnight Rivers";
+            readonly start_time: "2026-05-08T14:00:00+01:00";
+            readonly end_time: "2026-05-08T17:00:00+01:00";
+            readonly session_type_id: "<uuid from pica_sessions_types>";
+            readonly location: "Tileyard Studios";
+            readonly work_id: "<optional uuid>";
+        };
+    };
+    readonly "split-sheet-required": {
+        readonly workflow: "split-sheet-required";
+        readonly summary: "Required fields to generate a publishing split sheet on a work. Pre-condition: the work's writer credits (set via pica_credits_update) must already total 100% — pica_split_sheet_generate validates and returns 400 otherwise. The generated sheet snapshots current splits + signature state; pica_split_sheet_send notifies each credited writer for review/signature. The split_sheets.status column defaults 'draft' and is NOT enforced by a DB CHECK constraint.";
+        readonly primary_tool: "pica_split_sheet_generate";
+        readonly primary_required: readonly ["work_id"];
+        readonly primary_recommended: readonly [];
+        readonly enums: {};
+        readonly companion_calls: readonly [{
+            readonly tool: "pica_split_sheet_send";
+            readonly when: "After generate — notify each credited writer for review/signature via in-app notification + Telegram (if connected) + email. Non-PICA-user writers receive a collaboration invite email instead. Soft-fails per-writer; aggregate result reports delivered / not_a_pica_user / failed counts.";
+            readonly required: readonly ["work_id", "split_sheet_id"];
+        }, {
+            readonly tool: "pica_split_sheet_get";
+            readonly when: "Read back a specific sheet with its full content + signature state. Use after send to check who has signed.";
+            readonly required: readonly ["work_id", "split_sheet_id"];
+        }, {
+            readonly tool: "pica_split_sheet_list";
+            readonly when: "List all sheets for a work — useful when multiple revisions exist (e.g. a sheet was generated, splits changed, regenerate).";
+            readonly required: readonly ["work_id"];
+        }];
+        readonly example: {
+            readonly work_id: "<uuid — credits must total 100% first via pica_credits_update>";
+        };
+    };
     readonly "work-credits-required": {
         readonly workflow: "work-credits-required";
-        readonly summary: "Required fields per credit row when attaching writer/composer/publisher credits to a work. Splits sum to 100 across writers.";
+        readonly summary: "Required fields per credit row when attaching writer/composer/publisher credits to a work. The tool exposes `role` (mapped to credit_type on work_credits internally) and `splits` (mapped to writer_split_percentage). Splits must sum to 100. The `enums.credit_type` block reflects the column-level CHECK; pass these values via the `role` field.";
         readonly primary_tool: "pica_credits_update";
         readonly primary_required: readonly ["work_id", "credits"];
         readonly primary_recommended: readonly [];
@@ -85,12 +347,12 @@ export declare const REQUIRED_SCHEMAS: {
             readonly work_id: "<uuid>";
             readonly credits: readonly [{
                 readonly person_id: "<uuid>";
-                readonly credit_type: "writer";
-                readonly writer_split_percentage: 50;
+                readonly role: "writer";
+                readonly splits: 50;
             }, {
                 readonly person_id: "<uuid>";
-                readonly credit_type: "writer";
-                readonly writer_split_percentage: 50;
+                readonly role: "writer";
+                readonly splits: 50;
             }];
         };
     };
@@ -108,8 +370,8 @@ export declare const REQUIRED_SCHEMAS: {
             readonly tool: "pica_credits_update";
             readonly when: "Once per work, batch — attach all writer/publisher splits in a single call.";
             readonly required: readonly ["work_id", "credits"];
-            readonly per_row_required: readonly ["person_id", "credit_type"];
-            readonly constraint: "writer_split_percentage values must sum to 100 across all writer credits for the work.";
+            readonly per_row_required: readonly ["person_id", "role"];
+            readonly constraint: "splits values must sum to 100 across all credits for the work (the tool maps role→credit_type and splits→writer_split_percentage on work_credits).";
         }, {
             readonly tool: "pica_works_update";
             readonly when: "After creation — to amend title, work_type, work_status, iswc, lyrics, or any other inline field. Use the same payload shape as create with the addition of `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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAs4BnB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,gBAAgB,CAAC"}