@withpica/mcp-server 2.96.1 → 2.97.0

package/CHANGELOG.md

@@ -11,6 +11,110 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+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
+
+⚠️ Publish order: `@withpica/mcp-sdk` 3.14.0 and `@withpica/mcp-utils` 1.29.0
+must be on npm before this release — the dependency floors are now
+`^3.14.0` / `^1.29.0` (this release imports `pageEnvelope`, which only
+exists from mcp-utils 1.29.0; a clean install against 1.28.0 breaks at
+runtime — the 2.96.2 uninstallable incident).
+
+### Added
+
+- `pica_multimedia_import_url` accepts `person_id` (sets the person's profile image) and its summary names the outcome — `Imported from URL (via)`, profile-image set/NOT set, work link (PR #2118, merged into this release). Page URLs are followed to their `og:image`.
+
+- **Per-tool argument aliasing for `pica_execute`** (`arg-aliases.ts`, D1
+  2026-09-03) — `applyArgAliases` renames a tool's OWN entity id (or an
+  explicit `TOOL_ARG_ALIASES` entry, e.g. `pica_skill_get`'s `skill` /
+  `skill_name`) to the schema's real required field name, structurally by
+  domain (`DOMAIN_ID_ALIASES`) — never a foreign entity's id, never
+  overwriting a value already present, and left untouched when more than
+  one candidate is present. Fixes the wrong diagnosis `pica_execute` gave in
+  all 36 logged cases since July, where an agent sent e.g. `audio_file_id`
+  to `pica_audio_update` and was told the client had dropped the field in
+  transit.
+- **Shared `WRAPPED_ARGS_MISSING` envelope builder**
+  (`wrapped-args-envelope.ts`) — both guards that can reject a
+  `pica_execute` call before dispatch (the plain `required`-list guard, and
+  the `requiredOneOf` one-of-N guard covering `*_inspect` / `pica_search` /
+  bookings / licensing / shows / royalties tools) now build their message
+  and `structuredContent` through one function, naming
+  `unrecognised_fields` and `aliases_applied` in **both** the text block and
+  `structuredContent` instead of asserting "client-side transport loss" for
+  a non-empty args object. Empty args still name transport loss — there's
+  nothing else an empty resolved-args object could be.
+- **`offset` on `pica_audio_query`, `pica_notes_query`, `pica_sessions_query`**
+  (Task 10), each returning a `page` envelope built with
+  `@withpica/mcp-utils`'s `pageEnvelope()`. Audio and sessions fall back to
+  "page was full" (no total available); notes uses the route's real
+  `COUNT` for an exact `has_more`. A new `query-offset-parity` registry
+  guard test pins which remaining `_query` tools still lack `offset` so
+  each can be fixed and measured in isolation.
+
+### Changed
+
+- **Duplicate-release recovery hints point at a fix, not a dead end.**
+  `RELEASE_ALREADY_EXISTS` on `pica_releases_create` /
+  `pica_releases_create_with_tracks` now names `pica_releases_update` /
+  `pica_releases_attach_track` (the message already carries the existing
+  release's id) instead of `pica_releases_query`; `pica_releases_attach_track`'s
+  own `RELEASE_ALREADY_EXISTS` (a different release already holds the UPC)
+  points at `pica_releases_inspect`.
+- **Deprecated alias removal deferred to 2.98.0** — see `metadata.ts`.
+
+## [2.96.2] - 2026-09-02
+
+The MPP pay rail (spec 2026-08-24 WS-B): a new tool that mints a pay link,
+and `pica_subscription_status` learns to say what pica costs and what it is
+holding. Depends on `@withpica/mcp-sdk` 3.13.0 (`BillingResource`) — publish
+order matters, see `docs/releases/2026-08-26-mcp-release.md`. (This entry
+was authored as 2.96.0, which npm deprecated after 2.96.1 shipped from
+develop without `pica_billing_pay`; the branch re-releases on top of 2.96.1
+as 2.96.2, and also carries the stdio relay change below.)
+
+### Added
+
+- **`pica_billing_pay`** — new tool, `scope: read:catalog`, `tier: read`
+  (minting a link mints a capability, not a charge — nothing is billed until
+  the link is paid). Wraps `POST /api/admin/billing/pay-link` via
+  `PicaClient.billing.mintPayLink()`. Takes `offer` (`resident_month` | `unlock`
+  | `settle`, required) and `entity_id` (required for `unlock`). Route
+  refusals — billing disabled, nothing held on that work, offer no longer
+  applies — come back as structured `isError` results with a `next_tool`
+  pointer, not thrown errors. Added to the `subscription` tool category
+  (renamed description: "what does pica cost, how do I pay, and what is pica
+  holding — read your billing state and get a pay link"), the atlas
+  (`"how do i pay pica?"` and its synonyms), and `RECOVERY_HINTS`.
+- **`pica_subscription_status` carries `pricing` and `held` when the route
+  measured them.** `SubscriptionStatusFlat` gains optional `pricing` and
+  `held` fields (omitted, not `null`, when absent — a `null` price would read
+  as "free"). The composed `summary` sentence appends one further clause
+  naming the free-runway/resident-included song counts and, when
+  `held.count > 0`, how many findings across how many works are held pending
+  payment.
+- **`pica_dashboard_briefing`'s `found` block description gains a `billing`
+  clause**: when `billing.tab` is a string, state the tab total once and say
+  that settling it clears what pica is holding; when `billing.pay` names a
+  tool, offer to call it — mint a pay link, never charge unprompted.
+
+### Changed
+
+- **stdio relay forwards a narrowed result projection** — after a successful
+  tool call the audit entry now carries `result_projection` (built by
+  `narrowToolResultForRefs` from `@withpica/mcp-utils` ≥1.28.0), so the
+  relay ingest can attribute import wins: `pica_import_streaming_link` /
+  `pica_import_youtube_link` created-work ids live in the RESULT and their
+  params carry no id, which is why stdio imports recorded `entity_refs:
+null` and were invisible to the weekly roundup's wins beat. Only
+  allow-listed uuid arrays travel; every other tool sends
+  `result_projection: null` — nothing else on the wire changes. (The same
+  entry field also rides `makeHttpAuditFn`'s POST to `/api/mcp/audit`,
+  which destructures a fixed field list and ignores it.)
+  ⚠️ Publish order: `@withpica/mcp-utils` 1.28.0 must be on npm before this
+  release (2.96.2) — the dependency floor is `^1.28.0`.
+
 ## [2.96.1] - 2026-08-31
 
 First npm release since 2.95.4 — carries everything below (the discover

package/README.md

@@ -65,7 +65,7 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ## Tools
 
-329 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.
+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.
 
 **works** — manage your musical works
 
@@ -191,9 +191,9 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 `pica_storage_status`, `pica_storage_configure_start`, `pica_storage_disconnect`, `pica_delete_my_account`
 
-**subscription** — view your billing state, manage your subscription, and pick a tier
+**subscription** — what does pica cost, how do I pay, and what is pica holding — read your billing state and get a pay link
 
-`pica_subscription_status`, `pica_subscription_manage`
+`pica_subscription_status`, `pica_billing_pay`, `pica_subscription_manage`
 
 **profile** — manage your user, organisation, and directory profile
 
@@ -285,4 +285,4 @@ Read tools are annotated read-only and are safe to call freely. Write tools repo
 
 ---
 
-Generated for `@withpica/mcp-server@2.95.4`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.
+Generated for `@withpica/mcp-server@2.97.0`. © 2024-2026 Withpica Ltd. All rights reserved. MIT licensed.