@withpica/mcp-server 2.110.0 → 2.112.0

package/CHANGELOG.md

@@ -11,6 +11,135 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.112.0] - 2026-10-30
+
+> Server only: `@withpica/mcp-sdk`, `@withpica/mcp-utils` and the directory are unchanged (SDK floor
+> stays `^4.1.0`). The hosted `/api/mcp` already serves this text; this release brings npm (stdio)
+> installs level with it.
+
+### Fixed
+
+- `pica_recording_custody_assign` on a recording whose master split is locked (ADR-321) answers
+  409 `SPLIT_LOCKED`. It now carries a recovery hint, and the description says so: the owner must
+  start a change, signed in, on the recording's page (`details.page`); an agent cannot, so tell the
+  user and do not retry. An agent retried this refusal four times in two minutes.
+
+## [2.111.0] - 2026-10-29
+
+> **Publish order:** `@withpica/mcp-sdk` 4.1.0, `@withpica/mcp-utils` 2.0.2, then this package
+> (SDK floor `^4.1.0`: it calls `users.chooseBio` and the song-access methods added since 4.0.0).
+> The hosted `/api/mcp` already serves this text and behaviour; this release brings npm (stdio)
+> installs level with it.
+
+### Claims (founder ruling 2026-10-29)
+
+- `pica_claim_credit` claims as the user who granted the agent access. `pica_claim_custody` and
+  `pica_claim_artist` are refused for any agent with 403 `AGENT_CANNOT_CLAIM`: the person claims
+  custody or an artist link themselves. Their descriptions, the agent guide and the required
+  schemas say so, and tell the agent not to retry. A credit claim from an API key or connected app
+  rather than a grant is refused by the server with 403 `CLAIM_NEEDS_GRANT`.
+
+### Writes are never sent twice (#3391)
+
+- A tool call whose write timed out, lost its connection or got a 502/504 now answers
+  `WRITE_OUTCOME_UNKNOWN` (`retry_safe: false`: look for what it creates before retrying) instead of
+  being resent by the SDK. `pica_works_create` used to answer `WORK_ALREADY_EXISTS` naming the song
+  its own first attempt had made.
+
+### Audio paging (#3392)
+
+- `pica_audio_query` `metadata.total` is the real number of matching files (null where it cannot
+  be counted: `work_id` and `unassigned`), not the page's length.
+- New `cursor` input and `metadata.page.next_cursor`: walk the whole list without the repeat an
+  offset page gives when a file is uploaded meanwhile. A page trimmed to fit the response resumes
+  by cursor right after its last file.
+
+### Who has access to a song (ADR-346)
+
+- New `pica_works_access_query` (read): everyone outside your catalogue who can see one of your
+  songs, one line per organisation or invited address, with the person in your catalogue behind it
+  when known, why they have access, which side (song or recording) and what they can do. Pending
+  lines are invitations not yet accepted.
+- New `pica_works_access_remove` (destructive): ends one line by the key the query returned, every
+  share behind it and a master owner's edit too. `still_shared: true` means they can still see the
+  song; a retry touches only what is still live.
+
+### Deprecated
+
+- `isrc_source` on `pica_recordings_create` and `pica_recordings_update`. PICA records where an ISRC
+  came from itself: `manual` for an ISRC you type, the lookup's or importer's source otherwise, and an
+  unchanged ISRC keeps the source it has. A value you send is ignored, never stored, and the answer
+  carries the hint `isrc_source_ignored` ("isrc_source is set by PICA; your value was ignored"). The
+  web API ignores it the same way and adds that line to the response's `warnings`. It will be removed
+  in a later version.
+
+### Fixed
+
+- `pica_recording_credits_update` batch form (`credits[]`) keeps each credit's `instrument`. The
+  schema has offered it since 2026-09-11, but the executor never passed it on, so every batch credit
+  saved with no instrument.
+- The upload cards' storage allowlist (`PICA_STORAGE_CONNECT_DOMAINS`) named `withpica-media-production`,
+  a bucket PICA does not use. It now names PICA's three production buckets at eu-north-1
+  (`withpica-media-production-eu`, `-audio-`, `-documents-`), the addresses its presigned uploads
+  use, so a host that ignores the wildcard entries no longer refuses PICA uploads.
+- `pica_agreements_create` / `pica_agreements_update`: `other_party_type` now lists the values PICA
+  accepts (`artist`, `label`, `publisher`, `production_company`, `music_library`, `individual`,
+  `other`); its description had suggested `distributor`, which was refused. `agreement_type` gains
+  `sync_license`. A value outside either list is refused with `INVALID_FIELD_VALUE`, naming the field
+  and its allowed values, instead of a check violation that named no field.
+- A status change an agreement does not allow (for example `active` → `fully_executed`) answers 409
+  `INVALID_STATUS_TRANSITION` with the allowed next statuses, instead of `INTERNAL_ERROR`. An active
+  agreement already counts as signed.
+- `pica_documents_link` takes `entity_type: "agreement"`, so a signed contract can be attached to its
+  agreement; `pica_agreements_inspect` lists it under `linkedDocuments`. Linking to a record in
+  another organisation, or one that does not exist, is refused with 404 `LINK_TARGET_NOT_FOUND`.
+- `pica_agreements_inspect` gap hints read real columns: `missing_document` fired on every agreement
+  (it read `document_url`, which agreements do not have) and now fires only when nothing is attached,
+  pointing at `pica_documents_link`; the execution-date hints propose `signing_date`, not the absent
+  `fully_executed_date`.
+
+### Docs
+
+- The README's directory section no longer offers licensing keys. The public
+  directory reads no API key, and every caller gets 100 requests/minute per IP.
+  Licensing keys never worked and are retired.
+
+### Confirmed by them (ADR-346)
+
+- Credits now say whether the person confirmed them themself: `confirmed_by_person` (true or false)
+  and `confirmed_by_person_note`, the same words the browser's mark shows, e.g. "Ada confirmed this
+  from their own account." or "... by signing the split sheet." On `pica_works_inspect` credits,
+  `pica_credits_list`, and `pica_recordings_inspect` `recording_credits`. An owner confirming for
+  the person is `false`. The words name the person; PICA does not check identities.
+- `pica_people_inspect` carries `confirmed_by_person` when the profile is the person's own (an
+  account is proven to be them), with the note "claimed by <name>."
+
+### Share links
+
+- `pica_share_send` takes `share_link_id`: email a link that already exists (made by `pica_share_links_create` or in the browser) instead of making one. Its own settings stand; on a specific-people link the address must be one of its recipients, who is sent their own URL.
+
+### What applies to a song (ADR-344)
+
+- `pica_works_inspect` `health` gains `song_suggestions`: what applies to the song beyond its next
+  step — "which society is <name> with?" for a writer with no society on record, "register it with
+  PRS" for a writer's own society the song is not registered with, "this looks released: update
+  it?" for a song marked unreleased that has a platform link or a past release. None blocks
+  "complete".
+- The four tests ask what applies: an unreleased song (demo status or type, every recording a
+  demo, or set unreleased by someone — never the default) is not asked for an ISRC or a platform
+  link, and its `findable` test passes with the note "not released yet"; a song whose only
+  recordings are videos is identified by its ISWC alone; registered's next step names the
+  writers' own society.
+
+### One bio per person
+
+- A person's bio is the biography on their own person record. `pica_users_set_bio` writes it, with no 280-character cut and paragraphs kept, and refuses with `NO_LINKED_PERSON` when the account has no person. It also takes `choose` ("current" | "earlier") to settle a waiting `bio_choice`; the text not kept goes to `set_aside_bios` and is never deleted.
+- `pica_users_get_my_profile` returns `bio` (that biography), `bio_short` (its opening), `bio_confirmed`, `bio_choice` and `set_aside_bios`. Only a bio the person wrote or confirmed is shown outside its catalogue. Saving it confirms it, and re-saving the same text confirms one someone else wrote.
+- `pica_users_set_bio` is also refused with `NOT_YOUR_PERSON_ANY_MORE` once the caller has left their person's catalogue.
+- `pica_people_inspect` returns `person.claimant_own_bio`: the own bio of the person who claimed the record, read-only, and only if they wrote or confirmed it. `biography` stays the catalogue's own note.
+- **Retired:** `pica_users_import_bio_from_person`. It answers `TOOL_NOT_FOUND` naming `pica_users_set_bio`, because the profile bio is now the person's biography and there is nothing to import.
+- `pica_resolve_person` no longer reports Wikidata's biographical facts as a `biography` write: `applied[].fields` says `biographical_facts`. PICA does not fetch a prose bio from Wikidata.
+
 ## [2.110.0] - 2026-10-23
 
 > **Publish order:** `@withpica/mcp-sdk` 4.0.0, `@withpica/mcp-utils` 2.0.1, then this package

package/README.intro.md

@@ -100,7 +100,7 @@ Every entry is published deliberately by its rights holder, with attested credit
 - `GET https://withpica.com/api/public/directory/recordings`
 - `GET https://withpica.com/api/public/directory/consent?iswc={iswc}`
 
-100 requests/minute unauthenticated. Licensing keys unlock extended fields and their own limits.
+100 requests/minute per IP. No key or sign-in is needed.
 
 ## Before you train on any of this
 

package/README.md

@@ -65,7 +65,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ## Tools
 
-373 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.
+374 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
 
@@ -89,7 +89,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 **sharing** — explain why a user or org can see a work, recording, or person — surfaces the chain of reasons (org membership, custody chain, share links, cross-org grants); send works to named recipients via withPICA-branded email
 
-`pica_share_trace`, `pica_share_send`
+`pica_share_trace`, `pica_works_access_query`, `pica_works_access_remove`, `pica_share_send`
 
 **explainability** — explain dashboard / briefing count discrepancies — when a number doesn't match what the user sees elsewhere
 
@@ -197,7 +197,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 **profile** — manage your user, organisation, and directory profile
 
-`pica_user_profile`, `pica_organisation_profile`, `pica_directory_settings`, `pica_update_my_identity`, `pica_update_organisation_profile`, `pica_users_get_my_profile`, `pica_users_set_handle`, `pica_users_clear_handle`, `pica_users_set_bio`, `pica_users_set_avatar_url`, `pica_users_import_bio_from_person`, `pica_users_find_by_handle`
+`pica_user_profile`, `pica_organisation_profile`, `pica_directory_settings`, `pica_update_my_identity`, `pica_update_organisation_profile`, `pica_users_get_my_profile`, `pica_users_set_handle`, `pica_users_clear_handle`, `pica_users_set_bio`, `pica_users_set_avatar_url`, `pica_users_find_by_handle`
 
 **privacy** — self-service privacy & account controls — read/update marketing opt-ins, request GDPR data export, delete your account
 
@@ -297,4 +297,4 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ---
 
-Generated for `@withpica/mcp-server@2.110.0`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.
+Generated for `@withpica/mcp-server@2.112.0`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.

package/dist/apps/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/apps/shared.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,YAAY,wlsGA+LxB,CAAC;AAMF,eAAO,MAAM,WAAW,+iDA8CvB,CAAC;AAcF,eAAO,MAAM,sBAAsB,g6IA4JlC,CAAC;AAMF,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAiBR;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAM,EAqChD,CAAC"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/apps/shared.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,YAAY,wlsGA+LxB,CAAC;AAMF,eAAO,MAAM,WAAW,+iDA8CvB,CAAC;AAcF,eAAO,MAAM,sBAAsB,g6IA4JlC,CAAC;AAMF,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAiBR;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAM,EAyChD,CAAC"}

package/dist/apps/shared.js

@@ -444,10 +444,14 @@ ${bodyHtml}
  * Users on unlisted endpoints see a graceful "use web dashboard" fallback.
  */
 export const PICA_STORAGE_CONNECT_DOMAINS = [
-    // PICA-hosted media bucket
-    "https://withpica-media-production.s3.amazonaws.com",
-    "https://withpica-media-production.s3.us-east-1.amazonaws.com",
-    "https://withpica-media-production.s3.eu-north-1.amazonaws.com",
+    // PICA's default production buckets (storage-provider-helper.ts
+    // getDefaultBuckets) at region eu-north-1; staging's own buckets are
+    // covered by the eu-north-1 wildcard below. Until
+    // 2026-10-27 these named `withpica-media-production`, a bucket PICA does
+    // not use, so a host that ignores the wildcards below refused PICA uploads.
+    "https://withpica-media-production-eu.s3.eu-north-1.amazonaws.com",
+    "https://withpica-audio-production-eu.s3.eu-north-1.amazonaws.com",
+    "https://withpica-documents-production-eu.s3.eu-north-1.amazonaws.com",
     // AWS S3 BYOC — common region endpoints (virtual-hosted style)
     "https://*.s3.amazonaws.com",
     "https://*.s3.us-east-1.amazonaws.com",

package/dist/apps/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/apps/shared.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,uBAAuB,EACvB,aAAa,GACd,MAAM,8BAA8B,CAAC;AAEtC,8EAA8E;AAC9E,kEAAkE;AAClE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;qCAMS,+BAA+B;;;;;;qCAM/B,8BAA8B;;;;;;qCAM9B,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6K3D,CAAC;AAEF,8EAA8E;AAC9E,kDAAkD;AAClD,8EAA8E;AAE9E,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8C1B,CAAC;AAEF,8EAA8E;AAC9E,0EAA0E;AAC1E,2EAA2E;AAC3E,+EAA+E;AAC/E,EAAE;AACF,oFAAoF;AACpF,yFAAyF;AACzF,sEAAsE;AACtE,EAAE;AACF,kFAAkF;AAClF,8EAA8E;AAE9E,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4JrC,CAAC;AAEF,8EAA8E;AAC9E,sDAAsD;AACtD,8EAA8E;AAE9E,MAAM,UAAU,YAAY,CAC1B,KAAa,EACb,QAAgB,EAChB,KAAa;IAEb,OAAO;;;;;WAKE,KAAK;WACL,YAAY;;;EAGrB,QAAQ;UACA,aAAa;UACb,WAAW;UACX,sBAAsB;UACtB,KAAK;;QAEP,CAAC;AACT,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAa;IACpD,2BAA2B;IAC3B,oDAAoD;IACpD,8DAA8D;IAC9D,+DAA+D;IAE/D,+DAA+D;IAC/D,4BAA4B;IAC5B,sCAAsC;IACtC,sCAAsC;IACtC,sCAAsC;IACtC,sCAAsC;IACtC,sCAAsC;IACtC,sCAAsC;IACtC,yCAAyC;IACzC,uCAAuC;IACvC,2CAA2C;IAC3C,2CAA2C;IAC3C,2CAA2C;IAE3C,gBAAgB;IAChB,oCAAoC;IAEpC,SAAS;IACT,0BAA0B;IAC1B,oCAAoC;IACpC,oCAAoC;IACpC,oCAAoC;IACpC,uCAAuC;IACvC,yCAAyC;IAEzC,6BAA6B;IAC7B,wCAAwC;IACxC,wCAAwC;IACxC,wCAAwC;IACxC,wCAAwC;IACxC,2CAA2C;CAC5C,CAAC"}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/apps/shared.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,uBAAuB,EACvB,aAAa,GACd,MAAM,8BAA8B,CAAC;AAEtC,8EAA8E;AAC9E,kEAAkE;AAClE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;qCAMS,+BAA+B;;;;;;qCAM/B,8BAA8B;;;;;;qCAM9B,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6K3D,CAAC;AAEF,8EAA8E;AAC9E,kDAAkD;AAClD,8EAA8E;AAE9E,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8C1B,CAAC;AAEF,8EAA8E;AAC9E,0EAA0E;AAC1E,2EAA2E;AAC3E,+EAA+E;AAC/E,EAAE;AACF,oFAAoF;AACpF,yFAAyF;AACzF,sEAAsE;AACtE,EAAE;AACF,kFAAkF;AAClF,8EAA8E;AAE9E,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4JrC,CAAC;AAEF,8EAA8E;AAC9E,sDAAsD;AACtD,8EAA8E;AAE9E,MAAM,UAAU,YAAY,CAC1B,KAAa,EACb,QAAgB,EAChB,KAAa;IAEb,OAAO;;;;;WAKE,KAAK;WACL,YAAY;;;EAGrB,QAAQ;UACA,aAAa;UACb,WAAW;UACX,sBAAsB;UACtB,KAAK;;QAEP,CAAC;AACT,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAa;IACpD,gEAAgE;IAChE,qEAAqE;IACrE,kDAAkD;IAClD,yEAAyE;IACzE,4EAA4E;IAC5E,kEAAkE;IAClE,kEAAkE;IAClE,sEAAsE;IAEtE,+DAA+D;IAC/D,4BAA4B;IAC5B,sCAAsC;IACtC,sCAAsC;IACtC,sCAAsC;IACtC,sCAAsC;IACtC,sCAAsC;IACtC,sCAAsC;IACtC,yCAAyC;IACzC,uCAAuC;IACvC,2CAA2C;IAC3C,2CAA2C;IAC3C,2CAA2C;IAE3C,gBAAgB;IAChB,oCAAoC;IAEpC,SAAS;IACT,0BAA0B;IAC1B,oCAAoC;IACpC,oCAAoC;IACpC,oCAAoC;IACpC,uCAAuC;IACvC,yCAAyC;IAEzC,6BAA6B;IAC7B,wCAAwC;IACxC,wCAAwC;IACxC,wCAAwC;IACxC,wCAAwC;IACxC,2CAA2C;CAC5C,CAAC"}