@withpica/mcp-server 2.43.0 → 2.45.0

package/dist/resources/required-schemas.generated.js

@@ -5,6 +5,433 @@
 // Source: required-schemas.source.ts + schema-mirror.json + ToolRegistry inputSchemas.
 // ADR-214 — required-fields contracts per workflow.
 export const REQUIRED_SCHEMAS = {
+    "agreement-required": {
+        "workflow": "agreement-required",
+        "summary": "Required fields to create an agreement, then attach works and (optionally) render from a template.",
+        "primary_tool": "pica_agreements_create",
+        "primary_required": [
+            "title",
+            "agreement_type",
+            "other_party_name"
+        ],
+        "primary_recommended": [
+            "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"
+        ],
+        "enums": {
+            "agreement_type": [
+                "admin_only",
+                "artist_contract",
+                "co_publishing",
+                "distribution",
+                "library_music",
+                "master_recording",
+                "other",
+                "production",
+                "publishing_admin",
+                "report",
+                "sub_publishing",
+                "termination"
+            ],
+            "other_party_type": [
+                "artist",
+                "individual",
+                "label",
+                "music_library",
+                "other",
+                "production_company",
+                "publisher"
+            ],
+            "status": [
+                "active",
+                "cancelled",
+                "completed",
+                "draft",
+                "expired",
+                "fully_executed",
+                "partially_signed",
+                "pending_signature",
+                "terminated",
+                "unknown"
+            ]
+        },
+        "companion_calls": [
+            {
+                "tool": "pica_agreements_update",
+                "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.",
+                "required": [
+                    "id"
+                ]
+            },
+            {
+                "tool": "pica_agreements_link_work",
+                "when": "Attach a work to the agreement. Optionally set a royalty split percentage per work.",
+                "required": [
+                    "agreement_id",
+                    "work_id"
+                ]
+            },
+            {
+                "tool": "pica_agreement_templates_render",
+                "when": "Template-driven flow — fill an agreement template with catalog data (work_id + people_ids) before creating the agreement row.",
+                "required": [
+                    "id"
+                ]
+            }
+        ],
+        "example": {
+            "title": "Songwriter Admin Deal — Midnight Rivers",
+            "agreement_type": "publishing_admin",
+            "other_party_name": "Indigo Music Publishing Ltd."
+        }
+    },
+    "audio-upload-required": {
+        "workflow": "audio-upload-required",
+        "summary": "Three-step chain to add an audio master / stem / version to the catalog: presign → PUT → finalize, then optional async analyze + poll.",
+        "primary_tool": "pica_audio_presigned_upload",
+        "primary_required": [
+            "filename",
+            "content_type",
+            "file_size"
+        ],
+        "primary_recommended": [
+            "work_id",
+            "title",
+            "file_type"
+        ],
+        "enums": {
+            "file_type": [
+                "demo",
+                "instrumental",
+                "master",
+                "stem",
+                "version"
+            ],
+            "classification": [
+                "composition",
+                "demo",
+                "drum_pack",
+                "loop",
+                "other",
+                "released_song",
+                "sample",
+                "stem",
+                "unreleased_song"
+            ]
+        },
+        "companion_calls": [
+            {
+                "tool": "pica_audio_complete_upload",
+                "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.",
+                "required": [
+                    "upload_id",
+                    "key",
+                    "bucket",
+                    "filename",
+                    "content_type",
+                    "file_size"
+                ]
+            },
+            {
+                "tool": "pica_audio_analyze",
+                "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.",
+                "required": [
+                    "id"
+                ]
+            },
+            {
+                "tool": "pica_audio_inspect",
+                "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.",
+                "required": [
+                    "id"
+                ]
+            }
+        ],
+        "example": {
+            "filename": "midnight-rivers-master.wav",
+            "content_type": "audio/wav",
+            "file_size": 48234567,
+            "work_id": "<optional uuid — auto-creates a recording for master files>"
+        }
+    },
+    "claim-required": {
+        "workflow": "claim-required",
+        "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.",
+        "primary_tool": "pica_discoveries_query",
+        "primary_required": [],
+        "primary_recommended": [
+            "status",
+            "limit"
+        ],
+        "enums": {
+            "status": [
+                "expired",
+                "pending",
+                "resolved",
+                "revoked"
+            ],
+            "match_basis": [
+                "email",
+                "ipi",
+                "ipn",
+                "isni",
+                "musicbrainz"
+            ],
+            "custody_type": [
+                "composition",
+                "master"
+            ]
+        },
+        "companion_calls": [
+            {
+                "tool": "pica_discoveries_review",
+                "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.",
+                "required": [
+                    "discovery_id",
+                    "status"
+                ]
+            },
+            {
+                "tool": "pica_claim_credit",
+                "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).",
+                "required": [
+                    "id"
+                ]
+            },
+            {
+                "tool": "pica_claim_custody",
+                "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.",
+                "required": [
+                    "id"
+                ]
+            },
+            {
+                "tool": "pica_claim_artist",
+                "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.",
+                "required": [
+                    "id"
+                ]
+            }
+        ],
+        "example": {
+            "status": "pending",
+            "limit": 50
+        }
+    },
+    "enrichment-resolve-required": {
+        "workflow": "enrichment-resolve-required",
+        "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.",
+        "primary_tool": "pica_resolve_work",
+        "primary_required": [
+            "work_id"
+        ],
+        "primary_recommended": [
+            "sources",
+            "include_fuzzy"
+        ],
+        "enums": {
+            "status": [
+                "applied",
+                "expired",
+                "pending",
+                "rejected"
+            ],
+            "entity_type": [
+                "person",
+                "recording",
+                "work"
+            ],
+            "proposal_action": [
+                "create",
+                "update"
+            ]
+        },
+        "companion_calls": [
+            {
+                "tool": "pica_resolve_recording",
+                "when": "Recording-side variant. Fans out across Spotify, YouTube, MusicBrainz, Discogs. Triggered by spotify_track_uri / youtube_video_id on the recording.",
+                "required": [
+                    "recording_id"
+                ]
+            },
+            {
+                "tool": "pica_resolve_person",
+                "when": "Person-side variant. Fans out across ISNI and MusicBrainz (Wikidata downstream). Triggered by isni / musicbrainz_id on the person.",
+                "required": [
+                    "person_id"
+                ]
+            },
+            {
+                "tool": "pica_enrichment_proposals_list",
+                "when": "After resolve — list pending Tier B fuzzy matches awaiting review. Only pending status is returned.",
+                "required": []
+            },
+            {
+                "tool": "pica_enrichment_proposal_apply",
+                "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.",
+                "required": [
+                    "proposal_id"
+                ]
+            },
+            {
+                "tool": "pica_enrichment_proposal_reject",
+                "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.",
+                "required": [
+                    "proposal_id"
+                ]
+            }
+        ],
+        "example": {
+            "work_id": "<uuid>",
+            "sources": [
+                "mlc",
+                "spotify"
+            ],
+            "include_fuzzy": true
+        }
+    },
+    "export-required": {
+        "workflow": "export-required",
+        "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.",
+        "primary_tool": "pica_export_catalog_csv",
+        "primary_required": [],
+        "primary_recommended": [
+            "format"
+        ],
+        "enums": {},
+        "companion_calls": [
+            {
+                "tool": "pica_export_song_registration",
+                "when": "CWR-compatible song-registration export, formatted for PRO/CMO submission. Billing-gated.",
+                "required": []
+            },
+            {
+                "tool": "pica_export_industry_ready",
+                "when": "Industry-ready metadata package — formatted for distribution to publishers, labels, and sync agents. Billing-gated.",
+                "required": []
+            },
+            {
+                "tool": "pica_export_catalog_asset_report",
+                "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.",
+                "required": []
+            },
+            {
+                "tool": "pica_export_ai_consent",
+                "when": "AI-usage consent declaration matrix — per-work + per-contributor declarations of human-made / AI-assisted / AI-generated.",
+                "required": []
+            }
+        ],
+        "example": {
+            "format": "csv"
+        }
+    },
+    "multimedia-required": {
+        "workflow": "multimedia-required",
+        "summary": "Required fields to register a multimedia item (photo / video / audio / external streaming link), and the patterns for importing or attaching to a work.",
+        "primary_tool": "pica_multimedia_create",
+        "primary_required": [
+            "title",
+            "content_type"
+        ],
+        "primary_recommended": [
+            "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"
+        ],
+        "enums": {
+            "content_type": [
+                "live_performance",
+                "soundcloud_track",
+                "spotify_track",
+                "uploaded_audio",
+                "uploaded_photo",
+                "uploaded_video",
+                "youtube_video"
+            ],
+            "classification": [
+                "album_artwork",
+                "artist_showcase",
+                "behind_the_scenes",
+                "general",
+                "live_performance",
+                "music_video",
+                "promo_material",
+                "studio_session",
+                "sync_placement"
+            ]
+        },
+        "companion_calls": [
+            {
+                "tool": "pica_multimedia_import_url",
+                "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.",
+                "required": [
+                    "url"
+                ]
+            },
+            {
+                "tool": "pica_multimedia_link_youtube",
+                "when": "YouTube-specific variant — pulls thumbnail, title, and view count automatically. Use this instead of pica_multimedia_create for YouTube videos.",
+                "required": [
+                    "youtube_video_id",
+                    "title"
+                ]
+            },
+            {
+                "tool": "pica_multimedia_link_work",
+                "when": "Attach an existing multimedia item to a work with a typed relationship (music_video_for, sync_placement, album_artwork, etc.).",
+                "required": [
+                    "multimedia_id",
+                    "work_id",
+                    "relationship_type"
+                ]
+            }
+        ],
+        "example": {
+            "title": "Midnight Rivers — Official Music Video",
+            "content_type": "youtube_video",
+            "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+        }
+    },
     "person-required": {
         "workflow": "person-required",
         "summary": "Required fields to register a person (writer, performer, producer, publisher). Identifiers (IPI / ISNI / PRO / MusicBrainz / etc.) are inline-settable at create time.",
@@ -112,18 +539,9 @@ export const REQUIRED_SCHEMAS = {
         "companion_calls": [],
         "example": {
             "recording_id": "<uuid>",
-            "credits": [
-                {
-                    "credited_name": "The Riverbed Trio",
-                    "role": "MainArtist",
-                    "display_order": 0
-                },
-                {
-                    "credited_name": "Sam Producer",
-                    "role": "Producer",
-                    "display_order": 1
-                }
-            ]
+            "credited_name": "The Riverbed Trio",
+            "role": "MainArtist",
+            "person_id": "<uuid>"
         }
     },
     "recording-required": {
@@ -177,15 +595,11 @@ export const REQUIRED_SCHEMAS = {
         "companion_calls": [
             {
                 "tool": "pica_recording_credits_update",
-                "when": "Batch — attach MainArtist / Producer / Engineer credits to the recording.",
+                "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).",
                 "required": [
                     "recording_id",
-                    "credits"
-                ],
-                "per_row_required": [
                     "credited_name",
-                    "role",
-                    "display_order"
+                    "role"
                 ]
             },
             {
@@ -204,9 +618,161 @@ export const REQUIRED_SCHEMAS = {
             "duration_ms": 213000
         }
     },
+    "recording-splits-required": {
+        "workflow": "recording-splits-required",
+        "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.",
+        "primary_tool": "pica_recording_splits_create",
+        "primary_required": [
+            "recording_id",
+            "split_type",
+            "percentage"
+        ],
+        "primary_recommended": [
+            "person_id",
+            "role",
+            "territory",
+            "start_date",
+            "end_date",
+            "notes",
+            "dry_run"
+        ],
+        "enums": {
+            "split_type": [
+                "master",
+                "mechanical",
+                "performance",
+                "sync"
+            ],
+            "role": [
+                "engineer",
+                "label",
+                "masterer",
+                "mixer",
+                "other",
+                "owner",
+                "performer",
+                "producer"
+            ]
+        },
+        "companion_calls": [
+            {
+                "tool": "pica_recording_splits_verify",
+                "when": "After create — explicitly mark a split as confirmed/agreed by the relevant parties. Sets verified=true + verified_at + verified_by on the row.",
+                "required": [
+                    "recording_id",
+                    "split_id"
+                ]
+            },
+            {
+                "tool": "pica_recording_splits_list",
+                "when": "List all splits on a recording — verify totals and per-row verification state.",
+                "required": [
+                    "recording_id"
+                ]
+            }
+        ],
+        "example": {
+            "recording_id": "<uuid>",
+            "split_type": "master",
+            "percentage": 50,
+            "role": "owner",
+            "person_id": "<optional uuid>",
+            "territory": "worldwide"
+        }
+    },
+    "session-required": {
+        "workflow": "session-required",
+        "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.",
+        "primary_tool": "pica_sessions_create",
+        "primary_required": [
+            "title",
+            "start_time",
+            "end_time"
+        ],
+        "primary_recommended": [
+            "description",
+            "session_type_id",
+            "timezone",
+            "is_all_day",
+            "location",
+            "location_url",
+            "work_id",
+            "recording_id",
+            "status",
+            "notes",
+            "metadata",
+            "participants"
+        ],
+        "enums": {},
+        "companion_calls": [
+            {
+                "tool": "pica_sessions_types",
+                "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.",
+                "required": []
+            },
+            {
+                "tool": "pica_sessions_get",
+                "when": "After creation — verify the session row + participants persisted as expected. Reads back the full session record including any participants attached at create time.",
+                "required": [
+                    "id"
+                ]
+            },
+            {
+                "tool": "pica_sessions_list",
+                "when": "Discovery / browse — list recent or upcoming sessions for the workspace.",
+                "required": []
+            }
+        ],
+        "example": {
+            "title": "Vocal recording — Midnight Rivers",
+            "start_time": "2026-05-08T14:00:00+01:00",
+            "end_time": "2026-05-08T17:00:00+01:00",
+            "session_type_id": "<uuid from pica_sessions_types>",
+            "location": "Tileyard Studios",
+            "work_id": "<optional uuid>"
+        }
+    },
+    "split-sheet-required": {
+        "workflow": "split-sheet-required",
+        "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.",
+        "primary_tool": "pica_split_sheet_generate",
+        "primary_required": [
+            "work_id"
+        ],
+        "primary_recommended": [],
+        "enums": {},
+        "companion_calls": [
+            {
+                "tool": "pica_split_sheet_send",
+                "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.",
+                "required": [
+                    "work_id",
+                    "split_sheet_id"
+                ]
+            },
+            {
+                "tool": "pica_split_sheet_get",
+                "when": "Read back a specific sheet with its full content + signature state. Use after send to check who has signed.",
+                "required": [
+                    "work_id",
+                    "split_sheet_id"
+                ]
+            },
+            {
+                "tool": "pica_split_sheet_list",
+                "when": "List all sheets for a work — useful when multiple revisions exist (e.g. a sheet was generated, splits changed, regenerate).",
+                "required": [
+                    "work_id"
+                ]
+            }
+        ],
+        "example": {
+            "work_id": "<uuid — credits must total 100% first via pica_credits_update>"
+        }
+    },
     "work-credits-required": {
         "workflow": "work-credits-required",
-        "summary": "Required fields per credit row when attaching writer/composer/publisher credits to a work. Splits sum to 100 across writers.",
+        "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.",
         "primary_tool": "pica_credits_update",
         "primary_required": [
             "work_id",
@@ -250,13 +816,13 @@ export const REQUIRED_SCHEMAS = {
             "credits": [
                 {
                     "person_id": "<uuid>",
-                    "credit_type": "writer",
-                    "writer_split_percentage": 50
+                    "role": "writer",
+                    "splits": 50
                 },
                 {
                     "person_id": "<uuid>",
-                    "credit_type": "writer",
-                    "writer_split_percentage": 50
+                    "role": "writer",
+                    "splits": 50
                 }
             ]
         }
@@ -320,9 +886,9 @@ export const REQUIRED_SCHEMAS = {
                 ],
                 "per_row_required": [
                     "person_id",
-                    "credit_type"
+                    "role"
                 ],
-                "constraint": "writer_split_percentage values must sum to 100 across all writer credits for the work."
+                "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)."
             },
             {
                 "tool": "pica_works_update",