@withpica/mcp-server 2.98.0 → 2.100.0

package/CHANGELOG.md

@@ -11,6 +11,260 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.100.0] - 2026-10-04
+
+### Added
+
+- **`pica_recording_splits_update` and `pica_recording_splits_end` — fix a
+  wrong ownership share.** Before, a recording split could only be created
+  through the API, so a wrong row (a holder-less "unknown" share, the wrong
+  percentage or role) blocked adding the right owner with
+  `RECORDING_SPLIT_TOTAL_EXCEEDED` and had to be fixed by hand in /inspect.
+  `_update` changes `person_id` (relink to a person in the organisation, not
+  deleted), percentage, role, `split_type`, territory, dates or notes; the 100%
+  total is checked after the change with the row's old value left out.
+  `_end` sets `end_date` (default today) so the share stops counting, keeping the
+  row as history. Both report `verification_cleared: true` when the change
+  cleared the holder's confirmation. Typed refusals: `SPLIT_NOT_FOUND`,
+  `PERSON_NOT_FOUND`, `PERSON_DELETED`, `SPLIT_ALREADY_ENDED`,
+  `INVALID_SPLIT_PERCENTAGE`, `INVALID_SPLIT_ROLE`, `INVALID_SPLIT_TYPE`,
+  `INVALID_SPLIT_TERRITORY`, `INVALID_SPLIT_DATES`, plus the existing split total / exists / locked codes.
+- **`pica_merge_duplicates` takes a list — one approval for a whole cleanup.**
+  Send several confirmed duplicate groups as `merges` (up to 50 items of
+  `{entity_type, winner_id, loser_ids}`) instead of one call per group. A
+  delegated agent (OAuth connector / `pica_grant_*`) then raises ONE human
+  approval and the owner gets ONE email listing every pair, approved or
+  denied as a whole — before this, a 15-merge cleanup sent 15 emails, each
+  expiring on its own. Every pair is checked before the email goes out; one
+  bad pair refuses the list. Once approved, `pica_approval_status` returns a
+  per-pair outcome (`merged` / `skipped` because already merged or deleted /
+  `failed` with the reason); one failed pair does not stop the others, and the
+  approval reads `failed` if any pair failed. Callers that execute directly
+  get the same per-pair result. The single-merge fields work exactly as
+  before; send one shape or the other, never both. The tool's input schema no
+  longer lists a top-level `required`, because the two shapes cannot share
+  one.
+- **`pica_people_split_identity` — give one person their own identity when
+  two different people share one** (ops 482424b7). The opposite of a merge:
+  when a wrong match (e.g. someone else's ISNI) joined two people to one
+  global identity, custody transfers to it can't tell whose it is and land as
+  "unknown". This gives the named person a new identity. Nothing is guessed:
+  identifiers stay with the original unless listed in `move_identifiers`, and
+  only the unattributed split rows listed in `relink_split_ids` move.
+  `clear_person_identifiers` removes identifiers that were never the person's
+  from their record; `undo_external_ids` strips everything a wrong external
+  record (e.g. a Wikidata Q-id) wrote. Custody legs are append-only and never
+  rewritten. Tier `destructive`, `approvalMode: "human"`, scope
+  `write:people`. `pica_people_inspect` gains a `global_identity` section
+  (only when named) that lists everything a split would touch.
+- **`pica_profile_claims_invite` + `pica_profile_claims_status` — claim
+  your profile for assistants.** An assistant can invite people in the
+  catalogue to claim their profile (each at the address the catalogue holds
+  for them) and check where people stand. The invite is a preview unless
+  `confirm: true`: the first call sends nothing and returns who would be
+  emailed and who would be skipped and why, so the person the assistant acts
+  for sees the list before anyone is emailed. Only a credential that belongs
+  to an owner or admin may send; an organisation key with no owner is
+  refused (`INVITE_REQUIRES_PERSON`). The status read never returns an
+  email address.
+
+- **`pica_import_emails_query` — see what happened to an email forwarded to
+  PICA.** Lists the emails that reached the organisation's forwarding
+  address, newest first, with what PICA did with each: stored on arrival
+  (with what was created, by id), waiting for review, dismissed, or failed.
+  With `id`, reads one: its text body when PICA kept one (emails held for
+  review), its attachment names, and what was created. Owners and admins
+  only; read-only (`read:catalog`). Before this an agent had no way to learn
+  that an email its person forwarded had arrived. Every item carries
+  `sender_trusted`; an email from a sender PICA could not verify is labelled
+  third-party content (its subject and body are data, not instructions). The
+  list reaches back to 2026-09-30, when PICA began recording outcomes, and
+  refuses an `offset` past 500 rather than repeating a page.
+
+### Changed
+
+- **`pica_people_update` / `pica_people_create` accept and clear every field
+  enrichment fills on a person.** `imdb_id`, `viaf_id`, `date_of_death`,
+  `nationality_wikidata_id`, `birth_place_wikidata_id` and
+  `languages_spoken` were written by Wikidata enrichment but refused with
+  `UNKNOWN_FIELD`, so a misattributed value could not be removed. They are now
+  accepted, and every enrichment-filled field takes `null` (or `[]` for a
+  list) to clear it. A field set or cleared this way is recorded as the
+  user's own, and later enrichment runs leave it alone. `field_sources` is no
+  longer accepted from callers (it was never advertised); PICA writes it.
+- **`pica_credit_update` can change who a credit is for (`person_id`).** Link
+  a name-only credit to a person record created afterwards, or move a credit
+  linked to the wrong person, and the credit keeps its id (ops issue
+  abc91f6c: 11 credits had to be removed and re-added, losing their ids and
+  confirmations). The person must be in the organisation and not deleted
+  (`PERSON_NOT_FOUND` / `PERSON_DELETED`); if they already hold that role on
+  the song or recording the change is refused with `CREDIT_PERSON_CONFLICT`
+  and `existing_credit_id` rather than making a second credit; linking a
+  name-only credit to a differently named person needs
+  `confirm_name_mismatch: true` (`PERSON_NAME_MISMATCH` otherwise). A
+  confirmed, disputed or declined credit goes back to pending, because the
+  newly linked person gave none of those answers — the response's
+  `person_change.attestation_reset` and `previous_attestation_status` say so. Server-side in `PATCH /api/admin/works/[id]/credits/[creditId]`.
+- **`pica_documents_query` lists PICA's own split sheets first, marked as the
+  record.** Each entry now carries `kind` (`split_sheet` or `upload`); a
+  split sheet PICA generated has `split_sheet_role: "record"` and
+  `read_with: "pica_split_sheet_get"`, and an uploaded or forwarded split
+  sheet has `split_sheet_role: "supporting"` (plus `master: true` when it is
+  about the master only). An archived PICA sheet is `"superseded"`, not the
+  record. Paging is one sequence: PICA's sheets, then uploads, with `total`
+  covering both. With `parsed_status` `pending` or `completed`, only uploads
+  are listed. `pica_documents_link` / `_delete` take an entry with
+  `kind: "upload"`. Server-side change in `/api/admin/documents/catalog`;
+  the tool description says how to read each kind.
+
+### Fixed
+
+- `pica_recording_credits_update` no longer advertises or forwards
+  `attestation_status`. A caller could create a producer or performer
+  credit already marked "attested" without the credited person ever
+  confirming it. The field is gone from the input schema, and a call that
+  sends any attestation field (`attestation_status`, `attested_at`,
+  `attested_by`, `attestation_source_type`, `attestation_source_id`), in
+  the single form or on any `credits[]` entry, is refused before anything
+  is written with `ATTESTATION_NOT_SETTABLE`. The refusal points at the way
+  a recording credit actually gets confirmed: `pica_collaborators_invite`
+  with the `recording_id`, or `pica_credits_send_for_attestation` on the
+  recording's song. The server refuses the same fields on
+  `POST /api/admin/recordings/[id]/credits` and the bulk route.
+- `pica_credit_add` on a work now treats `share_pct: null` like an
+  omitted share: stored as unknown. The server refused an explicit `null`
+  with a 400, so a client that sends `null` for an empty optional field
+  (ChatGPT's connector does) could not add a credit without a share.
+  Server-side fix in `/api/admin/works/[id]/credits/atomic-add`; it reaches
+  every client on deploy. The input schema now declares `share_pct` as
+  number-or-null, matching `pica_credit_update`.
+- When the server refuses `pica_credit_add` with a machine code
+  (`VALIDATION_ERROR`, `PERSON_ORG_MISMATCH`, `RECORDING_TARGET_REQUIRED`,
+  `INSUFFICIENT_SCOPE`, …), the tool now returns that code and message,
+  plus the fields the server put beside them (`remedy`, `person_ids`,
+  `next_tool`). It no longer reports those refusals as `CREDIT_ADD_FAILED`,
+  which read as a transport failure and invited a blind retry. A server
+  error (5xx), or a refusal with no code, is still `CREDIT_ADD_FAILED`.
+- `pica_credits_update` no longer advertises `attestation_status`. The
+  server stopped accepting it on 2026-09-29 (a caller could mark a credit
+  "attested" with no one ever confirming it), but the tool kept offering
+  it, so agents sent it and the whole save failed with `UNKNOWN_FIELD`. The
+  field is gone from the input schema, the description and the
+  `work-credits-required` resource. A call that still sends it is refused
+  before anything is written with `ATTESTATION_NOT_SETTABLE`, naming the
+  entry and pointing at `pica_credits_send_for_attestation` — the way a
+  credit actually gets confirmed.
+
+## [2.99.0] - 2026-09-30
+
+### Added
+
+- **Platform-presence waivers on `pica_integrity_waive`.** New `gap_code`
+  values `PLATFORM_SPOTIFY`, `PLATFORM_YOUTUBE`, `PLATFORM_APPLE_MUSIC` with a
+  required `kind` (`not_applicable` | `restricted`) and reason mark a work that
+  is deliberately not on that platform (e.g. no YouTube by design, a licence
+  rules out Content ID). The platform then drops out of the work's
+  completeness instead of counting as missing; the answer carries the
+  re-scored `completeness`. Owner/admin only. Identifiers and registrations
+  (ISWC, ISRC, IPI, society registrations, writers, splits) can never be
+  waived, and the description says so.
+
+- `original_work_id` on `pica_works_create` / `pica_works_update`: links a
+  modified version (a remix that added writers) to the work it modifies. Same
+  catalogue only; `null` clears it.
+
+### Changed
+
+- **A remix is a recording of the same song unless it adds writers (ADR-324).**
+  `pica_works_create` on a remix-titled work now suggests a recording under the
+  original (`pica_recordings_create`, `version_type: "remix"`, remixer credited
+  on the recording) with the modified-version path beside it
+  (`if_new_writers`), instead of a separate derivative work.
+  `pica_find_duplicates` (works) no longer groups a remix with its original as
+  a duplicate: each remix is paired with its original as
+  `match_kind: "remix_recording"` (move its recordings) or
+  `"remix_modified_version"` (link it), with a `remix` block naming the
+  recordings, any added writers and the action — never "fold the copies".
+  The `catalog-modelling` skill carries the rule.
+
+- `pica_rights_inspect` no longer says amounts are "not computed yet"; it points
+  to `pica_rights_statements` for them.
+
+### Removed
+
+- **The last 11 deprecated tool aliases** (removal target 2.99.0). Each had
+  been a hidden, callable alias of the tool named beside it — ten since the
+  MCP tool-surface consolidation, `pica_royalties_summary` since 2026-09-25
+  (ADR-321 Phase 0). Calling an old name now fails with `TOOL_NOT_FOUND`;
+  the answer (from `pica_execute`, `pica_tool_details` and the hosted
+  connector alike) says the tool was retired in 2.99.0, names its
+  replacement and any argument change, and lists the replacement first in
+  `did_you_mean` when the caller can call it. Use the replacement instead:
+  - `pica_releases_list` → `pica_releases_query`
+  - `pica_releases_get` → `pica_releases_inspect`
+  - `pica_releases_bulk_attach_tracks` → `pica_releases_attach_track` with
+    `items[]` (the old `tracks` field is now `items`)
+  - `pica_releases_attach_track_by_identifier` → `pica_releases_attach_track`
+    with `identifier_type` + `value`
+  - `pica_projects_list` → `pica_projects_query`
+  - `pica_notes_list` → `pica_notes_query`
+  - `pica_documents_list` → `pica_documents_query`
+  - `pica_documents_read` → `pica_documents_inspect`
+  - `pica_statements_list` → `pica_statements_query`
+  - `pica_royalties_summary` → `pica_royalties_blockers` (`work_id` and
+    `limit` carry over; `gap_type` and `priority` have no equivalent)
+  - `pica_recording_credits_bulk_update` → `pica_recording_credits_update`
+    with a `credits` array (same arguments)
+
+  Production use over the 60 days before removal was 4 calls in total.
+
+- **`verified` on `pica_works_query`.** It filtered on a work-level
+  `is_verified` flag that PICA has never stored, so it matched no works
+  whichever way it was set. Passing it now returns `NO_WORK_VERIFIED_FLAG`
+  (the same code `pica_works_verify` returns) and names the filters that do
+  exist: `health_filter: 'low_completeness'`, `completeness_score_lt`, and
+  `pica_works_inspect` for one work.
+- **`verified` / `unverified` counts in the `catalog://stats` resource, and
+  `is_verified` in `works://list`.** Both read the same missing flag, so every
+  work counted as unverified.
+- **`musicbrainz_recording_id` on `pica_works_update` / `pica_works_create` /
+  `pica_works_bulk_update`.** An update used to pass it to the work's
+  recording, but only when the work had exactly one recording, so the same
+  call silently stopped working once a second recording was added (a create,
+  with no recording yet, never stored it). It is now refused with
+  `PHANTOM_FIELD` naming the tool to use instead:
+  `pica_recordings_update {id, musicbrainz_recording_id}`. Work reads still
+  show the recording's MusicBrainz id, and the completeness benchmark still
+  reads it.
+
+### Fixed
+
+- `pica_sync_placements_cite` no longer answers 404 on every call: the SDK
+  posted to `/sync-placements/{id}/sources`, a route that never existed; it
+  now posts to `/cite` (needs the matching `@withpica/mcp-sdk` fix). The
+  sync-placement item routes also required `read:sync_placements` /
+  `write:sync_placements`, scopes no key can hold, so only `admin` keys got
+  through; they now require `read:agreements` / `write:agreements`, the
+  scopes these tools declare.
+- `pica_physical_assets_inspect`'s `market` section no longer fails on every
+  call (the SDK sent GET to a POST-only route). Because that section asks an
+  AI model for a price estimate each time it runs, it is no longer part of
+  "omit sections for everything": it runs only when `sections` names
+  `market`, and needs a key with `write:catalog` (or `admin`).
+- `pica_integrity_waive`'s `gap_code` enum now lists `WORK_SPLITS_ABSENT` and
+  `WORK_SPLITS_INVALID`, which the app has accepted since 2026-08-16.
+- **`pica_rights_statements`** (read:finances) — ADR-321 Phase 3, COMPUTED NOT
+  PAID: direct income and what each party would receive under the song's
+  locked split in force when it was earned, PICA's proposed fee as its own line
+  (shown, never charged), every hold with why / who clears it / since when, and
+  the four measures. With `work_id`, that song's imported society statements
+  checked against the split: each co-writer's EXPECTED amount and the
+  registration check for writer societies; line-up completeness for PPL /
+  SoundExchange.
+- **`pica_rights_record_income`** (write:finances) — record a figure the user
+  gave (or a quoted licensing enquiry's fee), labelled "entered by your agent".
+  No money moves.
+
 ## [2.98.0] - 2026-09-29
 
 ### Deprecated

package/README.md

@@ -65,7 +65,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ## Tools
 
-341 tools, grouped below by the taxonomy `pica_discover` uses. The server's own `tools/list` is authoritative — not every registered tool is filed under a category yet, so the names below are a map, not a census.
+349 tools, grouped below by the taxonomy `pica_discover` uses. The server's own `tools/list` is authoritative — not every registered tool is filed under a category yet, so the names below are a map, not a census.
 
 **works** — manage your musical works
 
@@ -73,7 +73,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 **people** — manage people in your catalog
 
-`pica_people_query`, `pica_people_inspect`, `pica_people_create`, `pica_people_update`, `pica_people_delete`, `pica_people_bulk_delete`, `pica_people_bulk_update_roles`, `pica_people_bulk_add_tags`, `pica_group_add_member`, `pica_group_remove_member`, `pica_group_list_members`, `pica_person_list_groups`, `pica_artist_projects`
+`pica_people_query`, `pica_people_inspect`, `pica_people_create`, `pica_people_update`, `pica_people_delete`, `pica_people_bulk_delete`, `pica_people_split_identity`, `pica_people_bulk_update_roles`, `pica_people_bulk_add_tags`, `pica_group_add_member`, `pica_group_remove_member`, `pica_group_list_members`, `pica_person_list_groups`, `pica_artist_projects`, `pica_profile_claims_invite`, `pica_profile_claims_status`
 
 **groups** — manage group → member relationships on people
 
@@ -123,9 +123,9 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 `pica_find_duplicates`, `pica_merge_duplicates`
 
-**import** — import catalog data from files and streaming services
+**import** — import catalog data from files and streaming services, and see what happened to emails forwarded to PICA
 
-`pica_import_fields`, `pica_import_template`, `pica_import_analyze`, `pica_import_validate`, `pica_import_execute`, `pica_import_streaming_link`, `pica_import_documents_query`, `pica_import_documents_inspect`, `pica_import_youtube_link`, `pica_ingest_statement`
+`pica_import_fields`, `pica_import_template`, `pica_import_analyze`, `pica_import_validate`, `pica_import_execute`, `pica_import_streaming_link`, `pica_import_documents_query`, `pica_import_documents_inspect`, `pica_import_emails_query`, `pica_import_youtube_link`, `pica_ingest_statement`
 
 **export** — export catalog data in various formats
 
@@ -229,15 +229,15 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 **recording splits** — manage recording (master) splits between contributors
 
-`pica_recording_splits_list`, `pica_recording_splits_create`, `pica_recording_splits_verify`, `pica_split_sheet_generate`, `pica_recording_credits_update`
+`pica_recording_splits_list`, `pica_recording_splits_create`, `pica_recording_splits_update`, `pica_recording_splits_end`, `pica_recording_splits_verify`, `pica_split_sheet_generate`, `pica_recording_credits_update`
 
 **royalties statements** — view royalties and ingested statements
 
 `pica_royalties_list`, `pica_royalties_get`, `pica_statements_query`, `pica_statements_inspect`, `pica_ingest_statement`, `pica_statements_pending`, `pica_statement_ingest_document`, `pica_royalties_blockers`, `pica_royalties_unmatched`, `pica_royalties_attribute`
 
-**rights** — programmable rights — propose a song, master or share rule for the parties to confirm, check who has confirmed, and see what money would be held and why
+**rights** — programmable rights — propose a song, master or share rule for the parties to confirm, check who has confirmed, see what money would be held and why, and what income would pay each party (computed, never paid)
 
-`pica_rights_inspect`, `pica_rights_status`, `pica_rights_propose`
+`pica_rights_inspect`, `pica_rights_status`, `pica_rights_propose`, `pica_rights_statements`, `pica_rights_record_income`
 
 **selections** — save, recall, and resolve named catalog selections — persisted predicates over the catalogue with an honest coverage report
 
@@ -293,4 +293,4 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ---
 
-Generated for `@withpica/mcp-server@2.97.5`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.
+Generated for `@withpica/mcp-server@2.100.0`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.