@withpica/mcp-server 2.46.0 → 2.48.0

package/CHANGELOG.md

@@ -11,6 +11,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.48.0] - 2026-05-03
+
+### Changed
+
+- **Tool description scrub (PR #188).** Stripped internal-only ADR pointers and
+  email-vendor names from user-visible tool descriptions across batch A
+  (agreement-types, agreements, bulk, collaborators, credits), batch B
+  (app-tools, feedback, projects, enrichment, recordings), and batch C.
+  Replaced ADR-N references with the concept the ADR documented (e.g.
+  "ADR-198 round-trip" → "verify the credit persisted") and removed
+  Postmark from collaborator bulk-invite description and elicitation
+  warning text. Tool descriptions surface to third-party agents and shouldn't
+  reveal internal infrastructure choices.
+
+- **recovery_hints expansion (PR #188).** Annotation fix + additional
+  recovery hints for tools that fan out across sections.
+
+- **`pica_releases_show` best-effort catch markers (ADR-224 convention).** Marked
+  the two best-effort catches in `releases-rich.show()` (tracks + cover-art
+  fallbacks) with `/* best-effort */` to match the ADR-224 Phase 4 lint
+  convention. No behaviour change — the catches were already documented inline;
+  this just makes the marker greppable so future scope extensions to `_show`
+  tools recognise the intent. Surface audit confirmed all 9 `_inspect` tools
+  addressed, 22 `_list` tools clean, no swallow patterns elsewhere.
+
+## [2.47.0] - 2026-05-02
+
+### Added
+
+- **ADR-222 W3 — sync placements MCP tool surface (6 tools).**
+  - `pica_sync_placements_query` — list placements with filters (work_id, status, verification_status, brand, production_company, person_id, recording_id, source_license_enquiry_id, min_fee, currency).
+  - `pica_sync_placements_inspect` — fetch one placement with linked recordings, sources, agreement, and parties.
+  - `pica_sync_placements_create` — atomic create (placement + draft sync_license agreement + ≥1 agreement_party + recordings + evidence sources in a single Postgres transaction). Empty `contacts[]` rejects with structured `MISSING_CONTACT` (`next_tool: "pica_people_query"`). New people auto-created inline via `person_name` instead of `person_id`.
+  - `pica_sync_placements_update` — patch placement fields. Operator-only when `verification_status='operator_verified'|'disputed'` or `confidentiality_level` changes (throws structured `OPERATOR_REQUIRED`); illegal status transitions throw `INVALID_TRANSITION`.
+  - `pica_sync_placements_delete` — operator-only hard delete (two-step confirmation token). Customer agents receive structured `OPERATOR_REQUIRED` with `next_tool: "pica_sync_placements_update"` pointing at the soft-delete path (`status: 'terminated'`).
+  - `pica_sync_placements_cite` — attach an evidence source; auto-recomputes `verification_status` (any non-attestation kind → `evidence_attached`).
+
+  All 4 mutating tools wrapped with `withBillingGate`. Stdio path delegates to `pica.syncPlacements.*` (new `@withpica/mcp-sdk` resource). HTTP transport mirrors via the shared `ToolRegistry`. Paired with W4's REST routes at `/api/admin/sync-placements`.
+
+- **`pica://schemas/sync-placement-required` workflow schema resource (ADR-214).** Required + recommended fields for `pica_sync_placements_create` plus 4 companion call entries (inspect / update / cite / delete) and a worked example. Embeds the three `sync_placements` CHECK enums (`status` 5 values, `verification_status` 5 values, `confidentiality_level` 3 values) via the build-time generator + `schema-mirror.json` extension. Lives on both stdio (via the schema generator) and HTTP transport (`UI_RESOURCE_DEFS` in `app/api/mcp/route.ts`).
+
+- **`WorkflowTag` union expanded 15 → 16 values** (added `sync-placement-required`). All 6 sync-placement tools tagged with this workflow; `lint-required-schemas` enforces forward + inverse coverage.
+
+- **`schema-mirror.json` extended with `sync_placements` table** for status / verification_status / confidentiality_level CHECK enum embedding.
+
+- **6 cost-model entries in `lib/billing/tool-cost-model.ts`** (READ for query/inspect, WRITE for create/update/delete/cite). Unblocks ADR-180 lint cost-model coverage check; ADR-215 shadow-metering will record `billable_events` rows on these tools from first call.
+
+- **`sync_placements` discovery category** in `mcp-server/src/tools/discovery.ts` — layered-discovery agents (ChatGPT, Claude.ai connectors with `MCP_LAYERED_DISCOVERY=1`) can find the 6 tools via `pica_discover`.
+
+- **MCP scope mapping** for the 6 tools under existing `read:agreements` (query + inspect) and `write:agreements` (create + update + delete + cite). Bundled under the agreements scope rather than minting a new public scope for one feature — every placement is backed by a sync_license agreement.
+
+- **Four group-membership tools (ADR-223 Phase 5).** Customers can now
+  manage group → member relationships on people directly via AI:
+  - `pica_group_add_member` — add a person to a group person row.
+    Server-side trigger enforces parent.is_group=true and same-org
+    constraint; tool surfaces friendly errors at the route layer.
+    Defaults: `role='member'`, `receive_notifications=true` (opt-out
+    per membership). Wrapped in `withBillingGate`.
+  - `pica_group_remove_member` — set `left_at` on the active row.
+    Rows are never deleted; member history is preserved.
+  - `pica_group_list_members` — active members by default;
+    `include_inactive=true` for history.
+  - `pica_person_list_groups` — inverse: every group a person is or
+    was a member of.
+    Role enum: `member`, `founder`, `lead`, `touring_member`,
+    `session`, `guest`, `producer_in_residence`. Free-text `role_label`
+    for variants outside the enum. Tools route through `mcp-sdk`
+    `groups` resource → `/admin/groups/*` and
+    `/admin/people/{id}/groups` HTTP routes.
+
+### Changed
+
+- **`@withpica/mcp-sdk` peer bumped to `^1.20.0`.** Required for the
+  new `groups` and `syncPlacements` resources; older SDK versions lack
+  `PicaClient.groups` and `PicaClient.syncPlacements`.
+
+### Notes
+
+- The 4 mutating sync-placement tools (`_create`, `_update`, `_delete`, `_cite`) need ADR-198 holdout contract specs in the sibling `Good-FM/pica-holdout-tests` repo. Coordinator follow-up — Path A from W3 Stage 1 audit §11.E.
+- The brief's references to a `mcp-server/src/__tests__/contract-baseline.json` file and a `lint:contract-baseline` script are out of date; both were removed in ADR-180 Phase 3 (the lint chain is now fully strict by default — `scripts/lint-mcp-tools.ts` runs as part of `prepublishOnly`). W3 reinterpreted Stage 4 as ADR-180 metadata + cost-model + taxonomy entries (all added) plus ADR-198 holdout contracts (sibling repo, follow-up).
+
 ## [2.46.0] - 2026-05-02
 
 ### Changed
@@ -23,8 +104,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   edit-symmetry gap surfaced during the SEV-1 sprint: previously the
   user could AI-rename their org but not their own name.
 
-### Changed
-
 - **`pica_update_organisation_profile` now accepts `name`.** Customers can
   rename their organisation via AI (e.g., fix signup typos, replace the
   default "My Organization" placeholder). Updates `organisations.name`