@withpica/mcp-server 2.58.0 → 2.60.0

package/CHANGELOG.md

@@ -11,6 +11,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.60.0] - 2026-05-23
+
+Exports release. The four catalog export tools accept per-work scope, the catalog export tool's schema matches what the backend actually validates, and `pica_execute` is forgiving of the three call shapes agents emit in the wild.
+
+### Added
+
+- **`work_ids: string[]` on four export tools.** `pica_export_song_registration`, `pica_export_industry_ready`, `pica_export_ai_consent`, and `pica_export_catalog_asset_report` now accept an optional `work_ids` array. Omitted = whole catalog (existing behaviour). Provided = export limited to that set of works. Tool descriptions disclose the per-tool scoping semantics — `ai_consent` and `catalog_asset_report` apply the scope where it is structurally meaningful (recording rows on ai-consent, placements on CAR) and document the partial-scoping cases so agents don't pass `work_ids` expecting whole-row filtering.
+
+- **`pica_execute` accepts FLAT and `arguments`-alias call shapes.** The dispatcher resolves wrapped args from the first non-empty of `args` / `arguments` / FLAT top-level keys. Canonical remains `{ tool, args: {…} }`; the other two shapes are tolerated because agents emit them in practice. `arguments` alias is for the small fraction that mirror the outer `tools/call` envelope shape; FLAT is what most agents naturally emit when they have a single inner tool to invoke.
+
+- **`pica_execute` returns structured `WRAPPED_ARGS_MISSING` when the wrapped tool needs args.** When the dispatcher resolves no wrapped args AND the wrapped tool's schema declares `required` fields, dispatch is short-circuited with a structured error naming the missing fields and showing both canonical (`args: {…}`) and FLAT example call shapes. Previously the dispatcher silently invoked the wrapped tool with `{}`, surfacing as opaque downstream failures like `PG_INVALID_UUID` on `/admin/works/undefined`. Best-effort — wrapped tools unknown to the registry still dispatch through, letting their own validation speak.
+
+- **`pica_works_inspect` degrades gracefully on missing entities.** Calls naming a non-existent work id no longer fail with an opaque `PG_INVALID_UUID` / 500. The tool returns a structured `{ ok: false, error: "WORK_NOT_FOUND", context: { work_id } }` shape and lists the closest candidates (by name fuzzy match) so the calling agent can recover without round-tripping the user.
+
+### Fixed
+
+- **`pica_export_catalog_csv` schema reconciled with backend.** The tool's `format` enum is now `pro` | `distributor` | `nro` | `sync-pdf` (was `csv` | `json`, both rejected by the backend) and `format` is now marked required. The schema also exposes `work_id` (string) and `work_ids` (string[]) — the backend requires one. Tool description rewritten to explain each format's destination (PRO/CMO, DSP delivery, neighbouring-rights body, sync one-sheet) plus the XOR work scope and the `sync-pdf` single-only constraint. Prior to this fix the tool was uncallable from its own schema: agents got three sequential 400s and could not recover from the surface.
+
+## [2.59.0] - 2026-05-22
+
+Catalog-hygiene release. The interpretation layer an agent had to rebuild from row prose every session — what kind of person record is this, is this work near-complete, why is this attention row at the top — is now exposed as typed columns, queryable filters, sortable fields, and component-scored objects. One breaking change to `pica_dashboard_attention` rows (urgency).
+
+### Added
+
+- **`pica_people_query` filters by record kind and outreach readiness.** New filter params `record_kind` (`individual` / `placeholder` / `artefact`) and `outreach_state` (`ready` / `needs_email` / `needs_disambiguation` / `not_a_target` / `do_not_contact` / `previously_declined`). The same fields ship on every row of the response. "Show me individuals ready to contact" is one call.
+
+- **`pica_works_query` filters and sorts by completeness.** New filter params `completeness_score_lt`, `completeness_score_gt`, `has_statement_data`, and a `sort: completeness_score:asc | completeness_score:desc` option. Every row carries `completeness_score`, `completeness_components`, `completeness_model_version`, and `has_statement_data`. The works-most-worth-fixing query is a single call.
+
+- **Component-scored urgency on `pica_dashboard_attention` rows.** New `urgency: { score, components: { streaming_activity, sync_inquiries, missing_credit_fields, days_to_release }, model_version }` shape replaces the opaque `urgency_score: number`. An agent can now explain why a row is at the top of its queue without re-querying.
+
+- **`failure_mode` field on every attention row.** Stable short identifier (e.g. `missing_iswc`, `no_writer_split`, `placeholder_credit_present`) for client-side clustering. The full set is enumerated in the shared actionable-items source.
+
+- **Four new attention classes**: `placeholder_credits`, `people_records_need_cleanup`, `concatenated_entries`, `publishers_in_people_table`. Surface through `pica_dashboard_attention`, `pica_count_explain`, and `pica_dashboard_briefing` with the same shape as existing classes.
+
+- **Briefing unconnected-people breakdown.** `pica_dashboard_briefing`'s unconnected-people headline now carries `breakdown: { ready, needs_lookup, needs_cleanup, needs_lookup_by_record_kind: { individual, placeholder, artefact } }`. Values sum to the headline by construction.
+
+- **Cached `works.completeness_score`, refreshed on write.** Three new cached columns on the `works` table (`completeness_score`, `completeness_components`, `completeness_model_version`) maintained by an application hook on any cache-invalidating write. The query path on `pica_works_query` reads from cache; the response shape is identical whether served from cache or computed live.
+
+- **Composite indexes for the new query paths.** `works_org_statement_data_idx` on the `work_registrations` satellite (which owns `prs_work_id` / `ppl_recording_id`) and `works_org_completeness_score_idx` on `works(organisation_id, completeness_score DESC)`.
+
+- **`RECIPIENT_DO_NOT_CONTACT` error on `pica_collaborators_invite`.** When the target person has `outreach_state = 'do_not_contact'`, the tool short-circuits before any row is inserted into `collaboration_invites` and returns the new error code with the recipient identifier in `context`.
+
+### Changed
+
+- **BREAKING — `urgency_score: number` removed from `pica_dashboard_attention` row shape.** Callers reading `row.urgency_score` will see `undefined`. Migration: read `row.urgency.score` for the aggregate, or `row.urgency.components.<name>` for the per-axis values.
+
+- **Completeness scorer honours UPC overlay.** `scoreWork()` now resolves UPC through the master-metadata overlay. Works whose canonical UPC lives on an associated `releases` row are no longer scored as if UPC were missing.
+
+- **Completeness scorer recognises non-UK PROs and the MLC.** Beyond the UK PRS/PPL pair, the scorer now counts `pro_ids` membership in ASCAP, BMI, GEMA, SACEM, SOCAN, JASRAC, APRA as registration evidence, and counts `mlc_song_code` presence as US mechanical-rights coverage. ISWC presence counts as registration evidence regardless of UK CMO flags.
+
+- **Completeness response on `pica_works_inspect({ sections: ["completeness"] })` adopts `{ score, components, model_version }` envelope** wrapping the per-category breakdown. Existing readers of `breakdown` keep working.
+
+### Deprecated
+
+- **`suggested_skill` on `pica_dashboard_attention` rows.** Aliased to `drill_down_skill` for one release cycle (~2026-06-22 removal); `pica_count_explain` sources already use that name.
+
+### Fixed
+
+- **`pica_provenance_work` and `pica_provenance_certificate` authenticate correctly under MCP grant tokens.** Both routes (plus four sister provenance routes — certificate download, quality / provenance root / search / verify) now use the standard organisation-context boundary; previously returned 401 to all MCP traffic because they routed through the legacy session-only auth helper.
+
+- **MCP `client_name` attribution lands on every audit row** under both HTTP and stdio transports. The UA-fingerprint regex was widened to recognise `Claude-User` (claude.ai consumer web) and `openai-mcp/X` (ChatGPT) alongside the existing client families, closing a stamping gap on the stateless HTTP transport.
+
+### Database (staging applied; production applied)
+
+- `20260522132950_adr244_record_kind_outreach_state.sql` — `record_kind` and `outreach_state` columns on `people`, with classifier-driven defaults.
+- `20260522160011_adr244_c_works_completeness_cache.sql` — cached completeness columns on `works`, composite indexes (`works_org_statement_data_idx` on `work_registrations`, `works_org_completeness_score_idx` on `works`), and a one-shot backfill function.
+
+Consumes `@withpica/mcp-sdk@1.30.0`.
+
 ## [2.58.0] - 2026-05-19
 
 ### Changed