@withpica/mcp-server 2.95.2 → 2.95.4

package/CHANGELOG.md

@@ -11,6 +11,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`tools/list` no longer publishes this package's own authoring metadata.** `ToolDefinition` is two types wearing one name — the MCP `Tool` a client consumes, and the compile-time declarations our lint reads — and `listTools()` spread the whole object, so every field of the second kind crossed the wire. `vernacular_kind`, `vernacular_reason` and `annotationOverrides` are now stripped at the wire boundary. **Not a breaking change:** none of the three is part of the MCP `Tool` schema, no documented behaviour read them, and everything a client acts on (`name`, `description`, `inputSchema`, `annotations`, `tier`, `scope`, `audiences`, `workflows`) is untouched. The registry's own view is untouched too, so tooling that reads definitions in-process still sees them.
+- **The handshake and the skill bodies no longer cite internal decision records.** `vernacular_reason` on ~30 tools read "Specialist context; not yet covered by the Creator Question Atlas — pending telemetry-driven addition per ADR-226 Phase 4 substrate writes"; five `SKILL.md` bodies, two prompt bodies and the server instructions carried similar citations. An ADR number is a coordinate into a repository the reader cannot open, and an agent handed one repeats it to a user as if it were vocabulary they should already know — which is exactly what happened in a real connector session on 2026-08-18.
+- **The handshake's URI-shape pointer now names something reachable.** It read `docs/mcp-source-uri-conventions.md` — a path in the app repository, handed to agents that have no checkout. It now names `pica_skill_get("enrich-from-peer-mcps")`, the skill that actually carries the scheme table, which an agent can follow in one call.
+
+> 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. Bumping the minor here would bring that deadline forward by accident.
+
+> Scope note for anyone tracing this: the stripped-metadata leak affected the **stdio** surface — this package's flat `tools/list`. The app's HTTP transport serves layered discovery, where `tools/list` returns only the meta tools and `pica_discover` / `pica_tool_details` build responses by picking fields explicitly, so a connector was never reading it. The handshake and skill-body fixes reach both surfaces.
+
 ## [2.95.2] - 2026-07-28
 
 ### Added

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