@withpica/mcp-server 2.97.0 → 2.97.2

package/CHANGELOG.md

@@ -11,6 +11,160 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.97.2] - 2026-09-13
+
+### Fixed
+
+- **`pica_credit_update` now actually returns `allocation.status`.** The
+  description promised it and the route sent it, but `@withpica/mcp-sdk`
+  < 3.17.0 unwrapped it away, so the response never carried it and the
+  "writer shares now total N%" hints could never fire. Requires mcp-sdk 3.17.0.
+
+### Added
+
+- **`pica_credit_update` — edit ONE credit in place.** The verb between
+  `pica_credit_add` and `pica_credit_remove`: change a writer's share, an
+  instrumentalist's instrument, a role, the displayed name or notes, leaving
+  every other credit untouched and keeping the row's id and attestation state.
+  `pica_credits_update` remained replace-all, so one split change meant
+  re-listing every work and re-sending the whole array (ops issue bff0af25);
+  nothing edited a recording credit by its id — beyond the natural-key
+  upsert, a change meant remove-then-re-add (17f27449). Agents had already been calling this exact
+  name — it was the `TOOL_NOT_FOUND` miss in 167bb804, six times. Writer-split
+  closure is deliberately NOT enforced on a single edit; the response's
+  `allocation.status` (closed / open / incomplete) reports whether the set
+  still adds up instead. Backed by a new `PATCH
+/admin/works/{id}/credits/{creditId}`, scoped to the work in the path.
+- **`pica_recording_credits_update` batch mode accepts `instrument` per
+  credit** (`credits[].instrument`), applied on every target recording. Until
+  now crediting an instrumentalist across N recordings took N single calls.
+- **`pica_import_streaming_link` returns `STREAMING_LINK_NOT_FOUND`** for a
+  link the provider cannot resolve — user input, not a PICA fault, and no
+  longer opens an ops issue. `STREAMING_IMPORT_FAILED` is now reserved for
+  genuine failures (timeouts, upstream errors). ⚠️ A client matching on the
+  old code for the not-found case will need the new one.
+- **`pica_find_duplicates` accepts `entity_type: "audio_files"`** — the same
+  file uploaded twice, grouped on exact byte size + normalised filename
+  (`audio_files` carries no content hash). Each item reports `storage_bucket`;
+  a `withpica-*` bucket is storage PICA pays for. ⚠️ **Findable, not
+  mergeable:** `pica_merge_duplicates` refuses `audio_files` by design — the
+  outcome is a person deleting a redundant upload, and there is no merge
+  semantics for a file. The two entity lists are now deliberately different
+  sizes.
+- **`pica_publishers_query` works at all.** `GET /admin/publishers` did not
+  exist, so every call since the tool shipped drew a bare 405 and surfaced as
+  `UNKNOWN_ERROR`. Searches by name (substring, on name and legal_name) or by
+  exact IPI.
+- **`pica_approval_status` called with no `approval_id`** now explains what the
+  dashboard's "N awaiting approval" count is and who can act on it, instead of
+  answering "approval_id is required". There is deliberately no tool that lists
+  approvals — an agent grant cannot enumerate the approvals it is itself
+  waiting on.
+
+### Changed
+
+- ⚠️ **Wire change: `pica_execute` now FORWARDS `pica_discover` and
+  `pica_tool_details`** instead of refusing them. A client matching on the old
+  literal `"meta-tools (pica_discover, pica_tool_details, pica_execute) cannot
+be invoked via pica_execute"` will stop seeing that refusal. Only
+  `pica_execute` invoking ITSELF is still refused (that is the only case that
+  can recurse); its message changed accordingly. A connector that surfaces only
+  the wrapper teaches its agent to wrap everything, so refusing the two
+  read-only meta-tools blocked discovery for exactly the clients that need it.
+- ⚠️ **`pica_audio_query`'s `query` filter now applies to ALL results.** It was
+  honoured only when `unassigned: true` was also set; a plain
+  `pica_audio_query {query: "…"}` returned the whole library in upload order
+  and truncated at the 100KB response cap. The parameter description said
+  "with unassigned:true" and no longer does.
+- **`pica_audio_query` rows are a lean LIST shape.** The route flattens the
+  analysis satellite onto every row — `waveform_data` alone is ~4.9KB per file
+  on prod, three times the rest of the row — so the 100KB response guard was
+  trimming a page to about 8 files. List rows now carry identity, size,
+  duration, bpm/key/energy/mood, links, bucket and `probable_match`;
+  waveform, full analysis, `metadata` and the recording/work embeds are on
+  `pica_audio_inspect`. ⚠️ A client reading those fields off the list will
+  need the inspect call.
+- **`pica_recording_splits_verify` records WHICH PERSON attested.** It now
+  resolves the signed-in user to their person record and stamps that as
+  `verified_by` (the column has always referenced `people`). ⚠️ Wire change:
+  an API-key / agent-grant call is refused with
+  `VERIFICATION_REQUIRES_HUMAN_SESSION` (message text changed), and a
+  signed-in user with no person record in the org gets
+  `ATTESTING_PERSON_NOT_FOUND`. Before this the endpoint had never succeeded
+  for anyone.
+- **`pica_credits_update` accepts a signed sheet within ±0.01.** Its own
+  pre-flight used `!== 100`, so 33.34/33.34/33.33 (=100.01) and
+  33.33×3 (=99.99) were refused before the API was called; the message text
+  changed.
+- **`pica_share_links_create` returns `share_url`** beside `token`, so the
+  agent can hand the user a working link rather than sending them to the
+  dashboard to find it. `pica_share_links_query` returns it too. `token` is
+  unchanged.
+- **`pica_recording_credits_update` no longer reports `PERSON_NOT_FOUND` when
+  the RECORDING is the missing one.** It dispatches on the route's own error
+  code rather than matching "not found" anywhere in the message, and a foreign
+  or non-existent `person_id` is now validated org-scoped before the write
+  (it previously reached the FK unchecked, which also accepted another
+  organisation's person).
+- **`pica_tool_details` offers near-miss suggestions** (`did_you_mean`) for an
+  unknown tool name, in `structuredContent` as well as text — the same shape
+  `pica_execute`'s unknown-tool branch has returned since 2.96.
+- **`pica_catalog_health_fix` accepts `actionIds` / `action_ids`** as aliases
+  for `accept` on the `pica_execute` path, and `INVALID_PLAN_TOKEN` now names
+  the remedy rather than only the reason.
+
+## [2.97.1] - 2026-09-08
+
+### Added
+
+- **`pica_catalog_health_fix` accepts `selections: [{actionId, chosenPersonId}]`**
+  — the human choice a `resolve_person` action needs (one of its
+  `preview.candidates[].personId`). A selection accepts its action; a choice
+  the plan never offered is skipped `guard_blocked` with the reason. Until now
+  the applier required a chosen person the tool had no way to pass, so every
+  accepted `resolve_person` came back `stale` (feedback 2026-09-05).
+- **`pica_find_duplicates` sees identifier-less copies.** Recordings group on
+  title + artist and releases on title + equal track count when the ISRC/UPC
+  pass cannot see them (`match_kind: "title_artist"`, keep-separate default);
+  a UPC shared by releases with different titles is reported as
+  `shared_upc_different_title` — the decision is "correct the UPC", with no
+  fold option (feedback 2026-09-05).
+
+### Fixed
+
+- **`pica_works_update {collaborators}` is refused with a redirect** to
+  `pica_credits_update` / `pica_credit_add`. `works.collaborators` is a
+  legacy jsonb mirror; the write showed correct splits on inspect while the
+  `work_collaborators` rows every health check reads still disagreed, and the
+  health plan then proposed "fixing" them (feedback 2026-09-05).
+- **Accepting a held finding is a typed 409, not `INTERNAL_ERROR`.** The
+  apply route now maps every "is already <status>" refusal to
+  `PROPOSAL_ALREADY_CLOSED`, and a held one carries the unlock sentence
+  (`pica_billing_pay`, offer `unlock`, `entity_id` the work) — a ChatGPT user
+  hit "internal server error" three times on 2026-09-04.
+- **`pica_credit_add` never invents a share.** An omitted `share_pct` on a
+  composition credit is stored as NULL (unknown), not 0 — a 0 read as a real
+  share, so the health plan rescaled the other writer to 100 and the second
+  writer's stake vanished (holdout lock, 2026-09-06). For `credit_type:
+"owner"` the share is now REQUIRED (`OWNER_SHARE_REQUIRED`, 422): master
+  ownership is recorded as given, never assumed to be 100.
+- **`pica_releases_update` documents the UPC backfill trigger** — it fires
+  only on a write to `spotify_album_id`, so re-sending the existing id is the
+  way to backfill a UPC (ops issue 9f33cc59).
+
+- **`pica_subscription_status` is callable on the hosted connector.** It was
+  declared `scope: admin`, `audiences: ["stdio"]` while `pica_billing_pay` was
+  `read:catalog` on both surfaces, so a connected agent could mint a pay link
+  but not read the plan it would be paying for (`callable_on_this_surface:
+false` on claude.ai, 2026-09-04). Both now share the catalogue-read floor;
+  `pica_subscription_manage` stays stdio + admin.
+- **The pay path is visible to an agent that never calls `pica_discover`.**
+  The server instructions name `pica_subscription_status` and
+  `pica_billing_pay` with the exact `pica_execute` shape inside the first
+  2,000 characters (the observed cut on the claude.ai connector), and the
+  `pica_discover` description lists "how do i pay pica" among its example
+  queries for clients that surface tool descriptions but not instructions.
+
 PR #2118 (`fix/avatar-import-path-2026-09-03`) is merged into the release branch, so its changes ship in the version below; publish in the order mcp-utils → mcp-sdk → mcp-server.
 
 ## [2.97.0] - 2026-09-04

package/README.md

@@ -65,7 +65,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ## Tools
 
-330 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.
+336 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
 
@@ -119,7 +119,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 `pica_notes_query`, `pica_notes_inspect`, `pica_notes_create`, `pica_notes_delete`
 
-**duplicates** — detect and merge duplicate records
+**duplicates** — detect duplicate records and merge them (audio_files can be found but not merged — a duplicate file is deleted)
 
 `pica_find_duplicates`, `pica_merge_duplicates`
 
@@ -235,6 +235,10 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 `pica_royalties_summary`, `pica_royalties_list`, `pica_royalties_get`, `pica_statements_query`, `pica_statements_inspect`, `pica_ingest_statement`, `pica_statements_pending`, `pica_statement_ingest_document`, `pica_royalties_unmatched`, `pica_royalties_attribute`
 
+**selections** — save, recall, and resolve named catalog selections — persisted predicates over the catalogue with an honest coverage report
+
+`pica_selections_create`, `pica_selections_query`, `pica_selections_inspect`, `pica_selections_update`, `pica_selections_delete`
+
 **share links** — create, inspect, update, and delete share links for catalog content
 
 `pica_share_links_create`, `pica_share_links_query`, `pica_share_links_inspect`, `pica_share_links_update`, `pica_share_links_delete`
@@ -285,4 +289,4 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ---
 
-Generated for `@withpica/mcp-server@2.97.0`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.
+Generated for `@withpica/mcp-server@2.97.1`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.