@withpica/mcp-server 2.95.4 → 2.96.0

package/CHANGELOG.md

@@ -11,6 +11,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.96.0] - 2026-08-26
+
+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`.
+
+### 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
+
+- **`pica_discover({ query })` no longer scores the asker's own words as the entity.** Determiners, pronouns, prepositions and light verbs (`my`, `the`, `get`, `list`, `find` …) are dropped before ranking. "start my music catalogue and import my songs" led with three `pica_my_*` tools because "my" matched their domain segment; it now leads with the import tools. A query made only of such words matches nothing.
+- **Query mode carries the fresh-org import line.** The ADR-294 hint ("on a fresh or empty org, run `pica_dashboard_briefing` first … paste a spotify album or playlist link") was only on the no-args category map; it is now on every query response, hit or miss.
+- **Tools the caller cannot run on this connection rank last and are flagged.** Shortlist rows and `pica_tool_details` gain `callable_on_this_surface: false` plus a `surface_note` when the tool is on another surface (stdio / lobby) or needs a scope the connection does not hold — the judgement the HTTP dispatcher enforces at `pica_execute` time (installed only while the inner gate is in enforce mode). An existing scope or destructive-tier `callable_note` is kept beside it, and the `invoke` line on a flagged detail says the call will be refused instead of "pica_execute executes every tool returned here". Rows for callable tools are unchanged (no new keys). A capped shortlist keeps at least five tail rows for flagged tools and lets them fill what visible rows leave, so a gated capability reads as gated, not missing, and a narrow scope never shrinks the list. Query-mode `cache_until` is now one hour (the rows are per-connection); the full map keeps its day.
+
 ## [2.95.4] - 2026-08-25
 
 An agent-readability release. Nothing about auth, tiers or tool behaviour changes; what changes is what a tool **tells** an agent about itself, and the shape of a refusal.

package/README.md

@@ -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