@withpica/mcp-server 2.97.5 → 2.99.0

package/CHANGELOG.md

@@ -11,6 +11,229 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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_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
+
+- The 11 deprecated aliases scheduled for removal in 2.98.0 (among them
+  `pica_releases_list`, `pica_documents_list`, `pica_notes_list` and
+  `pica_royalties_summary`) stay one more version. They are now due for
+  removal in **2.99.0**. Each still answers and names its replacement.
+
+### Added
+
+- **`disambiguation` on `pica_works_create` / `pica_works_update`** — a short
+  note (≤ 200 characters, e.g. "theme", "2019 song") that tells apart two
+  DIFFERENT songs sharing a title and primary artist. It is part of the
+  duplicate check, so set it only when the songs genuinely differ; a
+  `WORK_ALREADY_EXISTS` refusal for a song you know is not the existing one is
+  the cue. The refusal message and its recovery hint now name both ways
+  through: merge when it is the same song, `disambiguation` when it is not.
+  `null` or `""` clears it. Also accepted by `pica_works_bulk_update`, which
+  shares the works write schema.
+- **`score` work type** — music composed for film, TV, games or other
+  picture. Offered wherever `work_type` is (`pica_works_create`,
+  `pica_works_update`, `pica_works_bulk_update`, `pica_works_query`,
+  `pica_register_set`).
+
+- **Programmable rights — `pica_rights_propose`, `pica_rights_status`,
+  `pica_rights_inspect`** (ADR-321 §9, Phase 2). Agents propose, humans
+  confirm. `pica_rights_propose` proposes a song rule, a recording's master
+  rule, or a share rule that divides one party's share (a publishing deal, a
+  manager's commission with an end date), and emails every party it affects to
+  confirm. It never activates or confirms anything and never moves money.
+  Tier `destructive`, `approvalMode: "human"`, scope `write:catalog`: a
+  delegated agent's call becomes a pending approval for the org owner (poll
+  `pica_approval_status`), replayed through the same propose service the route
+  uses. Shares are basis points (100 = 1%; a share rule's parties sum to
+  10,000). A refusal writes nothing and returns its reasons. A master rule
+  needs `ownership` — the user's answer to "who owns the master of this
+  recording?" (`only_me` / `me_and_others` / `someone_else`) — and locks only
+  after every owner signs the recording's master ownership sheet; an agent can
+  never lock "only me" in one step.
+  `pica_rights_status` (`read:catalog`) reads one rule: status, who has
+  confirmed this exact version, and email delivery. `pica_rights_inspect`
+  (`read:catalog`) reads a song's rules on both sides, version history,
+  disputes, and the holds — what money would be held, why, and who clears it.
+  No amounts yet; holds are PICA's rules, not a society's.
+- **`pica_royalties_blockers` — "why isn't this song being paid?"** (ADR-321
+  Phase 0). With `work_id`: what in that song's record is likely holding up its
+  society income — missing ISWC, writers without an IPI or society membership,
+  shares not totalling 100%, disputed credits, no confirmed registration,
+  recordings without an ISRC — each with its fix. Without it: the catalogue
+  summary plus the songs that are not clear, filterable by blocker and paged.
+  Same judgement as the `/inspect` song panel and `/inspect/money`. Scope
+  `read:catalog` (no amounts). The description and result message never call a
+  song clear unless every area was checked; unchecked areas are named.
+- **`pica_audio_bulk_update` — metadata for up to 200 audio files in one
+  call** (ops 5c53049a). Each item sets any of `file_type`, `stem_label`,
+  `version_label`, `title` for one file id; the result is one lean row per
+  item (`updated`, or `failed` with a reason) and never the file records. A bad
+  item does not stop the others. `dry_run: true` previews. Only the caller's
+  organisation's files are touched.
+- **`pica_share_links_create` takes `selection_id`** — share every work a saved
+  selection matches as one playlist link (a snapshot; the link does not follow
+  later changes to the selection). Refused when the selection matches no works
+  or more than 200 (ops 42be8f96).
+- **`pica_share_links_create` takes `allow_view_lyrics`**, and its description
+  now tells agents that lyrics, credits (`allow_view_collaborators`) and splits
+  (`allow_view_financials`) are hidden unless turned on.
+- **`pica_audio_query` takes `work_ids`** (up to 100) — the audio for several
+  works in one paged call, including files attached through a recording of
+  those works (ops 96672119).
+
+### Changed
+
+- **Playlist share links now record `include_all_files: true` by default**
+  (unless `included_file_ids` names a subset), matching what the playlist page
+  already shows — every version of each song, for the recipient to choose.
+- **`pica_audio_update` and `pica_audio_assign` return the lean list row**
+  (the shape a `pica_audio_query` row has) instead of the full stored record
+  with its waveform and fingerprint data — about 8k tokens a file (ops
+  5c53049a).
+- **`pica_works_update` answers with a compact receipt** (ops 61ce1dcc): the
+  work id, `changed` (each field sent, with the value now stored),
+  `unconfirmed` for fields the stored record did not echo, and an `integrity`
+  block listing every open gap by label and code but hinting only the gaps
+  this write opened. It no longer returns the full work (lyrics included) or
+  repeats every open gap as "next steps" on each call. Pass `verbose: true` for
+  the previous answer.
+- **`pica_credits_update` answers in the same shape**: `work_id`,
+  `changed.credits` (person, role, share as written) and `saved` (the save
+  count and any skipped rows). `verbose: true` returns the raw save result.
+
+### Deprecated
+
+- **`pica_royalties_summary` retired in favour of `pica_royalties_blockers`**
+  (founder decision, 2026-09-25). It ran its own gap judgement — PRS, PPL and
+  MCPS hard-coded, a missing row read as "not registered with PRS", only the
+  first 1,000 works. It stays callable as a silent alias until 2.98.0: calls
+  now return `pica_royalties_blockers`' answer (`work_id` and `limit` carry
+  over; `gap_type` and `priority` have no equivalent). No longer listed in
+  discovery. Unmatched payments remain `pica_royalties_unmatched`. Traffic: 2
+  calls from 2 organisations in the 90 days before retirement.
+
+### Fixed
+
+- The "how much has this song earned?" prompt told agents to call
+  `pica_royalties_summary` for cumulative earnings; that tool never returned
+  earnings. It now names `pica_royalties_get`.
+- **`pica_works_query` with `health_filter` honours `limit` and `offset`** and
+  stops reporting the page length as `total` (ops 314325eb).
+  `low_completeness` reports the number of works below the threshold by their
+  stored score (max 200 per page). `needs_attention` now returns only works with reconciliation problems
+  (it was returning reconciled works too), checks at most 50 works per call,
+  pages by works checked (`next_offset`), and reports `total` only when one
+  call from offset 0 checked every candidate (otherwise `null`).
+- **An unknown `sections` name is refused instead of answering `{}`** (ops
+  dfa810f8). `pica_works_inspect { sections: ["work"] }` returned a
+  successful empty result; every tool with a fixed list of sections now
+  answers `VALIDATION_ERROR` naming the unknown entries and the valid ones.
+- **`pica_people_create` / `pica_people_update` accept `ipi`** as the same
+  field as `cae_ipi_number` — the name the other tools use. Sending both with
+  different numbers is refused.
+- **`work_type` is one list everywhere** — song, instrumental, library, demo,
+  sample, matching the database. `pica_works_update` refused `instrumental`
+  while create and bulk update accepted it.
+
 ## [2.97.5] - 2026-09-18
 
 ### Added

package/README.intro.md

@@ -78,7 +78,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 # @withpica/mcp-server-directory
 
-MCP server for the **withPICA public directory** — read-only search over works, recordings and creators that rights holders have chosen to publish. No account, no API key, no setup.
+MCP server for the **withPICA public directory** — search over works, recordings and creators that rights holders have chosen to publish, plus one write: sending a licensing enquiry to an owner, when the user asks. Also hosted, no install: connect a remote MCP client to `https://withpica.com/api/mcp/directory`. No account, no API key, no setup.
 
 ## Install
 

package/README.md

@@ -65,7 +65,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ## Tools
 
-337 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.
+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.
 
 **works** — manage your musical works
 
@@ -101,7 +101,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 **audio** — manage and analyze audio files
 
-`pica_audio_query`, `pica_audio_inspect`, `pica_audio_presigned_upload`, `pica_audio_complete_upload`, `pica_audio_analyze`, `pica_audio_identify`, `pica_audio_assign`, `pica_audio_bulk_assign_suggested`, `pica_audio_dismiss_match`, `pica_audio_update`, `pica_audio_delete`, `pica_upload`, `pica_audio_pipeline_status`
+`pica_audio_query`, `pica_audio_inspect`, `pica_audio_presigned_upload`, `pica_audio_complete_upload`, `pica_audio_analyze`, `pica_audio_identify`, `pica_audio_assign`, `pica_audio_bulk_assign_suggested`, `pica_audio_dismiss_match`, `pica_audio_update`, `pica_audio_bulk_update`, `pica_audio_delete`, `pica_upload`, `pica_audio_pipeline_status`
 
 **projects** — manage albums, EPs, and work groupings
 
@@ -233,7 +233,11 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 **royalties statements** — view royalties and ingested statements
 
-`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`
+`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, 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_statements`, `pica_rights_record_income`
 
 **selections** — save, recall, and resolve named catalog selections — persisted predicates over the catalogue with an honest coverage report
 
@@ -289,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.99.0`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.