@withpica/mcp-server 2.97.5 → 2.98.0

package/CHANGELOG.md

@@ -11,6 +11,131 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+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.
 
 **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, and see what money would be held and why
+
+`pica_rights_inspect`, `pica_rights_status`, `pica_rights_propose`
 
 **selections** — save, recall, and resolve named catalog selections — persisted predicates over the catalogue with an honest coverage report