@withpica/mcp-server 2.95.3 → 2.96.0

package/CHANGELOG.md

@@ -11,6 +11,78 @@ 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.
+
+### Added
+
+- **`pica_dashboard_briefing` reports what pica is holding.** The `found` block carries `held: { count, entities }` — findings pica produced but is HOLDING because the org is past its free runway or over its allowance (WS-A of the MPP spec, #2027; dormant unless billing enforcement is on).
+- **Every tool now names the sibling it is most confused with.** 141 descriptions across every 3-or-more-member family gained a clause saying which same-family tool to prefer and when — derived from that sibling's own description and schema, not invented. Families with verb-first names (`pica_get_*`, `pica_update_*`) are deliberately exempt: those segments group unrelated tools by verb, so "name a sibling in your family" has no meaning for them. Where a description had to grow, over-long ones were paid for by dropping text the tool's own `inputSchema` or `nextSteps` already carried.
+- **`did_you_mean` on a missed tool name.** An unknown inner tool via `pica_execute` now comes back with ranked candidates plus `next_tool: pica_discover`. Candidates never include a deprecated alias, and on the HTTP surface they are drawn only from tools the caller can actually see.
+
+### Changed
+
+- **⚠️ Wire change: an unknown tool now returns `TOOL_NOT_FOUND`, not `UNKNOWN_TOOL`.** The code read `UNKNOWN_TOOL` from 2026-07-03 until now. A client matching on the old literal will stop recognising this refusal — match on `isError` instead, which is set on every refusal. The `suggestions` key is kept alongside the new `did_you_mean` so existing readers keep working.
+- **The HTTP dispatcher's bare `Not found` is now the same typed envelope.** An unregistered inner tool name was refused at the gate-shadow step before the registry's typed envelope could run. A registered-but-hidden name keeps its previous refusal, so the change leaks no information about tools the caller may not see.
+- **Annotations are now derived for every tool on both surfaces.** `pica_tool_details` returned `annotations: null` for 275 of 332 tools because it passed the raw declaration through while `tools/list` derived hints from tier. Both now go through one derivation. Two consequences a client may notice: `openWorldHint` follows `createsExternalSideEffects`, so **24 tools flip `false` → `true` on the flat surface** (they already published that side-effect flag by another name — nothing about their behaviour changed); and a **declared** `idempotentHint` now wins over the derived value, which flips **4 tools**. Treat both as corrections to hints that were previously wrong or absent, not as new capability.
+- **`pica_skill_get` puts the skill body in `structuredContent`.** The methodology travelled only in the text block, so clients that prefer `structuredContent` (claude.ai among them) received frontmatter and nothing to follow.
+- **No live surface recommends a deprecated alias any more.** Server instructions, 7 tool descriptions, 17 recovery-hint `next_tool` values, 2 skills and 2 resources pointed agents at alias names. All now name the canonical tool. The alias names still resolve — the only remaining mentions are the aliases' own registration rows.
+- **Refusals are typed envelopes with a `SCREAMING_SNAKE` code.** The notifications and telegram tools returned _success_ envelopes carrying an `error` key with no `isError`, so an agent read a failure as a success; credits and import returned bare prose. All four now share one error envelope.
+- **The agent guide computes its counts at serve time** from the caller-visible tool set, instead of reciting numbers written down by hand and since drifted. It also drops a `mode:` parameter that never existed on the schema and a `prs_work_id` removed under ADR-282.
+- **`pica_discover` ranking singularises tokens properly.** The old `-es` rule turned `notes` into `not` (a false hit on every query containing "not") and `releases` into `releas` (never matching "release"). Domain segments are now weighted, so a query naming a domain reaches that domain's tools first.
+- Server instructions state what the registry actually enforces for `sections` / `limit` (3,110 / 3,200) instead of a softer claim.
+- **`pica_import_execute` now imports one slice per call and tells you where to continue.** A call runs synchronously under the route's ~2 minute budget, so the server imports at most `row_limit` rows (default 2,000, max 10,000) from `row_offset` (default 0) and returns `rowRange.nextOffset` — call again with `row_offset: nextOffset` until it is null. The old "max 10,000 rows per import" claim was not honourable inside the budget: a call the budget ended committed its batches and reported nothing. For files over ~2,000 rows, upload once with `pica_upload_file` → `pica_upload_complete` and pass `file_id` so the CSV is not re-sent per call. (ADR-314)
+
+- **`pica_import_execute` no longer loses a whole batch to one duplicate, and no longer reports a partial commit as a failure.** `conflict_strategy` now defaults to `"skip"` (a row that trips a unique constraint becomes a warning; every other row in its batch still lands) instead of `"error"` (one 23505 discarded the batch). A live run that wrote rows and also carries errors is answered `Import PARTIALLY complete: N created …` with `partial: true` in the payload and an explicit "the created rows are saved, do not re-send the whole file" instruction, because the backing route now returns 200 for a partial commit (400 is reserved for runs that wrote nothing). Observed 2026-08-17: a 2,239-row catalogue import lost a 500-row batch to a single repeated title, was told it had failed while 1,742 rows were already saved, and re-sent the file three times. Pass `conflict_strategy: "error"` explicitly to keep all-or-nothing batches.
+- **`pica_upload_file` / `pica_upload_complete` work on a `write:files` credential again.** The platform's bearer write-scope floor had `/api/admin/storage/**` (the two routes these tools call) floored to `admin`, so every connector — none holds `admin` — was refused "insufficient scope: requires admin". Fixed on the platform side (no package change required); noted here because the tools' declared `write:files` scope was correct all along.
+- **`pica_notifications_recent` / the directory server count.** The `.well-known` directory listing and `pica_discover` count 11 directory tools (was 9 by drift), and the one destructive directory tool no longer wears a write tier — pinned by a parity tripwire (#2024).
+
+### Fixed
+
+- **The daily briefing counted one work three times.** `entityIds` were not deduplicated, so a single work touched by three events reported as "3 works". Counts are deduplicated and a `canonical_total` now travels with them.
+- Internal vocabulary left agent-facing copy in bulk: table names, CHECK-constraint names, HTTP status codes, `jsonb`, repository paths, "1 credit each" and internal constant names were removed from descriptions and required-schema copy. An agent handed a repository path cannot open it, and repeats it to the user as if it were vocabulary they should already know.
+
+> Patch, not minor, on purpose: `2.96.0` stays reserved for the WS5 deprecated-alias removals, which `src/tools/deprecations.ts` enforces as its removal target. No alias is removed in this release.
+
 ## [2.95.3] - 2026-08-18
 
 ### Fixed

package/README.intro.md

@@ -0,0 +1,115 @@
+<!--
+  Hand-written prose for the two published npm READMEs.
+
+  `scripts/build-mcp-readmes.mjs` splices each block below onto a generated
+  tool inventory and writes `mcp-server/README.md` and
+  `mcp-server-directory/README.md`. Edit the prose HERE; never edit the
+  generated files, which carry a do-not-edit banner and are checked by
+  `node scripts/build-mcp-readmes.mjs --check`.
+
+  Both intros live in this one file because the generator has one input for
+  prose and one for structure. The markers below are load-bearing — the
+  generator splits on them.
+-->
+
+<!-- readme:mcp-server -->
+
+# @withpica/mcp-server
+
+MCP server for **withPICA** — music catalog management through conversation. Works, recordings, credits, agreements, rights, royalties, enrichment and registration-ready exports, from Claude, ChatGPT, Cursor, or any MCP-compatible client.
+
+> **Not the same product as `@picahq/mcp`.** That is Pica / picaos.com, an unrelated API-integrations tool that happens to share the short name. If your assistant starts talking about integrations it never set up, or asks you to paste credentials into a dashboard, you have the other one installed.
+
+## Install
+
+```bash
+claude mcp add withpica -- npx --yes @withpica/mcp-server@latest
+```
+
+Or, in any client that reads an `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "withpica": {
+      "command": "npx",
+      "args": ["@withpica/mcp-server"]
+    }
+  }
+}
+```
+
+## Signing in
+
+**On stdio (this package), no API key is needed up front.** Say _"sign me in to withpica"_ in chat; `pica_sign_in` emails you a magic link, you click it, and your tools unlock. `PICA_API_KEY` in the environment also works and skips the link.
+
+**On the hosted HTTP transport** (`https://withpica.com/api/mcp`) there is no in-chat sign-in — `pica_sign_in` and `pica_sign_out` are stdio-only, because the credential file they write would land on an ephemeral filesystem your client never reads. Connect over OAuth 2.1 instead (dynamic client registration + PKCE S256, discovery at `https://withpica.com/.well-known/oauth-protected-resource`), or send an API key as a Bearer token. A Bearer caller should call `pica_introduce_self` first: PICA stamps that declaration onto every audit row that follows, so the owner can later reconstruct what their agent did.
+
+API keys are created and revoked at <https://withpica.com/settings?tab=connections>.
+
+## How the tools are surfaced
+
+Over HTTP the server advertises a small meta-tool surface by default — `pica_discover` → `pica_tool_details` → `pica_execute` — so a schema-constrained client is not handed the whole registry at once. Every tool stays callable by name. Add `?layered=0` to the endpoint for the eager list.
+
+Over stdio the full set is listed directly.
+
+`pica_skill_list` / `pica_skill_get` load methodologies (catalog-audit, register-my-works, prepare-for-sync) as needed, rather than at handshake.
+
+## Safety
+
+Read tools are annotated read-only and are safe to call freely. Write tools report what changed. Destructive tools (delete, merge) require a two-step confirmation token and an elevated scope that ordinary agent grants cannot hold.
+
+## Environment variables
+
+| variable       | required | meaning                                           |
+| -------------- | -------- | ------------------------------------------------- |
+| `PICA_API_KEY` | no       | skips the magic-link flow                         |
+| `PICA_API_URL` | no       | API base URL (default `https://withpica.com/api`) |
+| `DEBUG`        | no       | verbose logging to stderr (`true` / `1`)          |
+
+## Links
+
+- Connect guide: <https://withpica.com/connect>
+- Machine-readable: <https://withpica.com/llms.txt>, <https://withpica.com/connect/llms.txt>
+- Discovery: <https://withpica.com/.well-known/mcp.json>
+- Support: support@withpica.com
+
+<!-- readme:mcp-server-directory -->
+
+# @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.
+
+## Install
+
+```bash
+claude mcp add withpica-directory -- npx --yes @withpica/mcp-server-directory@latest
+```
+
+## What it can answer
+
+Who wrote this song. What the ISWC is. Which recordings exist of a work and what their ISRCs are. Which creators match a name, an ISNI or an IPI. Which published recordings sit in a tempo, key, energy or mood range. And, in one call, the rights chain for a work: writers, publishers, recording, audio.
+
+Every entry is published deliberately by its rights holder, with attested credits and verified identifiers.
+
+## REST, if you would rather not run a process
+
+- `GET https://withpica.com/api/public/directory/works`
+- `GET https://withpica.com/api/public/directory/people`
+- `GET https://withpica.com/api/public/directory/search?q={query}`
+- `GET https://withpica.com/api/public/directory/recordings`
+- `GET https://withpica.com/api/public/directory/consent?iswc={iswc}`
+
+100 requests/minute unauthenticated. Licensing keys unlock extended fields and their own limits.
+
+## Before you train on any of this
+
+withpica.com publishes a blanket TDM reservation at <https://withpica.com/.well-known/tdmrep.json> (`"tdm-reservation": 1`). Nothing here is licensed for text-and-data mining or model training by default.
+
+The `consent` endpoint above is the granular counterpart: ask it about an identifier and it reports what the rights holders have actually cleared, and at what level. A work is cleared at a level only when every credited contributor has granted at least that level; one refusal blocks it. Read `no_assertion_published` literally — it means no permission is published for that identifier, which is not a maybe.
+
+## Links
+
+- Directory: <https://directory.withpica.com>
+- Machine-readable: <https://withpica.com/directory/llms.txt>
+- Support: support@withpica.com