@withpica/mcp-server 2.99.0 → 2.100.0

package/CHANGELOG.md

@@ -11,6 +11,150 @@ 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
@@ -95,6 +239,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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

package/README.md

@@ -65,7 +65,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ## Tools
 
-343 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,7 +229,7 @@ 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
 
@@ -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.99.0`. © 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.